mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-11-16 20:45:33 -08:00
Show a spec's Pathfinder Map and Plan draft as read-only tabs on the dashboard until it has an overview, so an undocumented spec's main files can be read like a documented one's Overview
AI Assisted
This commit is contained in:
1 parent
0d569954c4
commit
46f1f17261
16 files changed
+210
-50
No files matched your search
@@ -46,7 +46,7 @@ export function helpTabFor({ view, dashboard, gone, adrift, finished, workflow,
|
||||
if (v === "subagents") return "subagents";
|
||||
if (dashboard && meterRed) return "meter";
|
||||
if (dashboard) return "dashboard";
|
||||
if (v === "overview" || v.startsWith("doc:")) return "docs";
|
||||
if (v === "overview" || v === "map" || v === "draft" || v.startsWith("doc:")) return "docs";
|
||||
if (workflow === "git") return "git";
|
||||
if (HELP_BUILD_WORKFLOWS.has(workflow)) return "build";
|
||||
return "about";
|
||||
|
||||
@@ -1654,13 +1654,19 @@
|
||||
<strong>Out of date</strong> by the title means answers have landed that
|
||||
the document does not reflect yet.
|
||||
</p>
|
||||
<h4>The Overview tab</h4>
|
||||
<h4>The Overview, Map and Plan draft tabs</h4>
|
||||
<p>
|
||||
When the session is working on a spec that has an
|
||||
<code>overview.md</code>, the <strong>Overview</strong> tab shows it. It
|
||||
is read-only, and read fresh from disk each time you open the tab, so an
|
||||
edit shows up straight away. No file, no tab.
|
||||
</p>
|
||||
<p>
|
||||
On the dashboard, a picked spec that is not documented yet shows its
|
||||
main files the same way instead: <strong>Map</strong> for its
|
||||
Pathfinder map and <strong>Plan draft</strong> for its plan draft, each
|
||||
when it exists.
|
||||
</p>
|
||||
<h4>Printing and saving</h4>
|
||||
<ul>
|
||||
<li>
|
||||
|
||||
@@ -51,8 +51,8 @@ import { helperRows, showTab } from "../subagents.js";
|
||||
import { FOOTER_TIERS, footerLabel } from "../workspace.js";
|
||||
import {
|
||||
activity, agentAdrift, agentWorking, asked, awaitingReply, byId, dashboardLive, docs, doingNow,
|
||||
finish, gitAwaiting, isDashboard, isGitBoard, isOpen, items, loadOverview, myTurn, openItems,
|
||||
overviewSpec, patience, pressStranded, reviewPending, scan, selSpec, sendCollected, stagedCount, stranded,
|
||||
finish, gitAwaiting, isDashboard, isGitBoard, isOpen, isSpecFileView, items, loadOverview, myTurn, openItems,
|
||||
patience, pressStranded, reviewPending, scan, selSpec, sendCollected, specFileTabs, stagedCount, stranded,
|
||||
topics, workingMs, WORKING_GRACE_MS,
|
||||
workspaceFolders,
|
||||
} from "../selectors.js";
|
||||
@@ -433,9 +433,9 @@ export function adopt(body) {
|
||||
render();
|
||||
if ($("workspace-modal").open) renderWorkspace();
|
||||
tellFolderIssues();
|
||||
// The Overview tab's file changes under a build, so a tab you are watching
|
||||
// A spec file tab's file changes under a build, so a tab you are watching
|
||||
// refetches on every new frame too, not only on the click that opened it.
|
||||
if (firstLoad || page.S.specDir !== prevSpecDir || page.S.workflow !== prevWorkflow || page.view === "overview") loadOverview();
|
||||
if (firstLoad || page.S.specDir !== prevSpecDir || page.S.workflow !== prevWorkflow || isSpecFileView(page.view)) loadOverview();
|
||||
if (announce) showArrival(announce);
|
||||
// New entries land at the bottom of the rail. Gliding down to them beats
|
||||
// leaving the list parked where it was while it grew underneath.
|
||||
@@ -860,7 +860,7 @@ function withFocus(fn) {
|
||||
// (the dashboard menu, the end page).
|
||||
function currentScroller() {
|
||||
if (!drawnView) return null;
|
||||
if (drawnView.startsWith("doc:") || drawnView === "overview") return $("main");
|
||||
if (drawnView.startsWith("doc:") || isSpecFileView(drawnView)) return $("main");
|
||||
if (drawnView === "questions") return $("main").querySelector(":scope > .card.question");
|
||||
if (drawnView === "ask") return $("main").querySelector(".ask-list");
|
||||
return null;
|
||||
@@ -1249,10 +1249,11 @@ function renderViews() {
|
||||
},
|
||||
];
|
||||
// Built in rather than posted: present exactly while the spec in view has
|
||||
// an overview.md. A tab that vanishes under the person sends them home.
|
||||
const hasOverview = typeof page.overview.text === "string" && page.overview.key === overviewSpec();
|
||||
if (hasOverview) tabs.push({ id: "overview", label: "Overview", count: 0 });
|
||||
else if (page.view === "overview") page.view = "questions";
|
||||
// the file (an overview.md, or before one a map or a plan draft). A tab
|
||||
// that vanishes under the person sends them home.
|
||||
const fileTabs = specFileTabs();
|
||||
for (const f of fileTabs) tabs.push({ id: f.id, label: f.label, count: 0 });
|
||||
if (isSpecFileView(page.view) && !fileTabs.some((f) => f.id === page.view)) page.view = "questions";
|
||||
for (const d of docs()) tabs.push({ id: "doc:" + d.id, label: d.title || "Document", count: 0 });
|
||||
// The helpers the agent reported, from the first one on; cleared by a
|
||||
// dashboard hop, which sends the person home like the Overview tab does.
|
||||
@@ -1301,7 +1302,7 @@ function renderViews() {
|
||||
// The cached text paints at once; the fresh read repaints if the file
|
||||
// changed on disk since.
|
||||
render();
|
||||
if (t.id === "overview") loadOverview();
|
||||
if (isSpecFileView(t.id)) loadOverview();
|
||||
});
|
||||
nav.appendChild(b);
|
||||
}
|
||||
@@ -1436,11 +1437,11 @@ function renderMain() {
|
||||
}
|
||||
|
||||
function paintMain(main) {
|
||||
main.classList.toggle("is-doc", page.view.startsWith("doc:") || page.view === "overview");
|
||||
main.classList.toggle("is-doc", page.view.startsWith("doc:") || isSpecFileView(page.view));
|
||||
main.classList.toggle("is-ask", page.view === "ask");
|
||||
|
||||
if (page.view.startsWith("doc:")) return renderDoc(main, page.view.slice(4));
|
||||
if (page.view === "overview") return renderOverview(main);
|
||||
if (isSpecFileView(page.view)) return renderOverview(main, page.view);
|
||||
if (page.view === "ask") return renderAsk(main);
|
||||
if (page.view === "subagents") return renderSubagents(main);
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
// Plan2Code Web Console - documents: tabs, blocks, print and download, and the brief button; defines only.
|
||||
|
||||
import { docs, agentWorking, workingMs, patience, WORKING_GRACE_MS, finish } from "../selectors.js";
|
||||
import { docs, agentWorking, workingMs, patience, WORKING_GRACE_MS, finish, SPEC_FILES } from "../selectors.js";
|
||||
import { el, md } from "../render.js";
|
||||
import { downloadDocHtml, docSavedNote, downloadDoc, blockBody } from "../doc-files.js";
|
||||
import { hooks, page, redraw } from "../state.js";
|
||||
@@ -220,19 +220,22 @@ function printButton() {
|
||||
return print;
|
||||
}
|
||||
|
||||
// The spec's overview.md, read-only and drawn through the same markdown path
|
||||
// as every doc. No Download: the file is already on disk.
|
||||
export function renderOverview(main) {
|
||||
// One of the spec's files (overview.md, the Pathfinder map, the Plan draft),
|
||||
// read-only and drawn through the same markdown path as every doc. No
|
||||
// Download: the file is already on disk.
|
||||
export function renderOverview(main, kind = "overview") {
|
||||
const spec = SPEC_FILES.find((f) => f.id === kind) || SPEC_FILES[0];
|
||||
const found = page.overview.files[spec.id];
|
||||
const head = el("div", "doc-head");
|
||||
head.appendChild(el("h2", null, "Overview"));
|
||||
head.appendChild(el("h2", null, spec.label));
|
||||
const tools = el("div", "doc-tools");
|
||||
tools.appendChild(backButton());
|
||||
tools.appendChild(printButton());
|
||||
head.appendChild(tools);
|
||||
main.appendChild(head);
|
||||
main.appendChild(el("p", "help", `${page.overview.key}/overview.md · read-only, straight from disk`));
|
||||
main.appendChild(el("p", "help", `${page.overview.key}/${found ? found.file : ""} · read-only, straight from disk`));
|
||||
const box = el("div", "block settled");
|
||||
box.appendChild(md(page.overview.text, "md"));
|
||||
box.appendChild(md(found ? found.text : "", "md"));
|
||||
main.appendChild(box);
|
||||
}
|
||||
|
||||
|
||||
@@ -236,26 +236,61 @@ export function pressStranded() {
|
||||
return Date.now() - Date.parse(page.agentLastSeen) > UNCOLLECTED_MS;
|
||||
}
|
||||
|
||||
// The spec whose overview.md the Overview tab shows: the dashboard picker's
|
||||
// The spec whose files the spec file tabs show: the dashboard picker's
|
||||
// selection on the dashboard, the session's own spec everywhere else.
|
||||
export const overviewSpec = () => (isDashboard() ? selSpec()?.dir || "" : (page.S && page.S.specDir) || "");
|
||||
|
||||
// Fresh from disk every time, never cached: the file changes under a build,
|
||||
// and the tab is only worth having if it shows what is there now. Repaints
|
||||
// only when the tab would appear, vanish or show different text.
|
||||
// The spec files a tab can show, in tab order: each a view id, which is also
|
||||
// the server's ?file= kind. Document's overview stands for the whole spec
|
||||
// once it exists; before that the dashboard offers Pathfinder's map and
|
||||
// Plan's draft.
|
||||
export const SPEC_FILES = [
|
||||
{ id: "overview", label: "Overview" },
|
||||
{ id: "map", label: "Map" },
|
||||
{ id: "draft", label: "Plan draft" },
|
||||
];
|
||||
export const isSpecFileView = (v) => SPEC_FILES.some((f) => f.id === v);
|
||||
|
||||
// The spec file tabs to draw now: Overview alone when the spec has one, else
|
||||
// the map and the draft that exist. Only for the spec in view, so a pick that
|
||||
// moved on never shows the last spec's files.
|
||||
export function specFileTabs() {
|
||||
if (page.overview.key !== overviewSpec()) return [];
|
||||
const has = (id) => Boolean(page.overview.files[id]);
|
||||
if (has("overview")) return SPEC_FILES.filter((f) => f.id === "overview");
|
||||
return SPEC_FILES.filter((f) => f.id !== "overview" && has(f.id));
|
||||
}
|
||||
|
||||
async function fetchSpecFile(spec, kind) {
|
||||
try {
|
||||
const res = await fetch("/overview?spec=" + encodeURIComponent(spec) + "&file=" + kind, { cache: "no-store" });
|
||||
if (res.status !== 200) return null;
|
||||
const file = decodeURIComponent(res.headers.get("x-spec-file") || "") || kind;
|
||||
return { file, text: await res.text() };
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
// Fresh from disk every time, never cached: the files change under a build,
|
||||
// and the tabs are only worth having if they show what is there now. Away
|
||||
// from the dashboard only the overview is read: a session's own map or draft
|
||||
// is the work already in front of it. Repaints only when a tab would appear,
|
||||
// vanish or show different text.
|
||||
export async function loadOverview() {
|
||||
const spec = overviewSpec();
|
||||
let text = null;
|
||||
const kinds = isDashboard() ? SPEC_FILES.map((f) => f.id) : ["overview"];
|
||||
const files = {};
|
||||
if (spec) {
|
||||
try {
|
||||
const res = await fetch("/overview?spec=" + encodeURIComponent(spec), { cache: "no-store" });
|
||||
if (res.status === 200) text = await res.text();
|
||||
} catch {}
|
||||
const found = await Promise.all(kinds.map((k) => fetchSpecFile(spec, k)));
|
||||
kinds.forEach((k, i) => {
|
||||
if (found[i]) files[k] = found[i];
|
||||
});
|
||||
}
|
||||
// The selection moved on while this was in flight; its own fetch will land.
|
||||
if (spec !== overviewSpec()) return;
|
||||
const changed = page.overview.key !== spec || page.overview.text !== text;
|
||||
page.overview = { key: spec, text };
|
||||
const changed = page.overview.key !== spec || JSON.stringify(page.overview.files) !== JSON.stringify(files);
|
||||
page.overview = { key: spec, files };
|
||||
if (changed) redraw();
|
||||
}
|
||||
|
||||
|
||||
@@ -108,9 +108,10 @@ export const page = {
|
||||
// The frame's Subagents switch ({ offered, supported, on, instruction, max,
|
||||
// revision }), or null before a server that sends it.
|
||||
subagentsFrame: null,
|
||||
// The spec's overview.md as last fetched: `key` is the spec dir it was read
|
||||
// for, `text` the file, or null when there is none. See loadOverview().
|
||||
overview: { key: null, text: null },
|
||||
// The spec's files as last fetched: `key` is the spec dir they were read
|
||||
// for, `files` maps each SPEC_FILES kind (overview, map, draft) that exists
|
||||
// to `{ file, text }`. See loadOverview().
|
||||
overview: { key: null, files: {} },
|
||||
// The dashboard's first-open wake-up (boot.js), while it runs. `cards` turns
|
||||
// true at the glide, which lets the menu in; `entered` once its entrance has
|
||||
// played; `typed` is how many characters of the note show, or null once all
|
||||
|
||||
@@ -27,7 +27,7 @@ import {
|
||||
writeJsonAtomic,
|
||||
} from "./files.mjs";
|
||||
import { AGENTS_SCHEMA, normalizeAgents, resolveCommand, validateForSave } from "./agents.mjs";
|
||||
import { checkDocument, cleanupFindings, readOverview, removeCleanup } from "./sessions.mjs";
|
||||
import { checkDocument, cleanupFindings, readSpecFile, removeCleanup } from "./sessions.mjs";
|
||||
import { SHOTS_DIR_NAME, SHOT_NAME, shotType } from "./patches.mjs";
|
||||
import { appendChat, currentConversation, pendingChatCount, typedCount } from "./inbox.mjs";
|
||||
import { specKey } from "./workspace.mjs";
|
||||
@@ -302,12 +302,15 @@ function renderIndex(ctx) {
|
||||
|
||||
/* ------------------------------------------------------ read-only routes */
|
||||
|
||||
// The spec's overview.md, read-only. A dashboard honors ?spec= only for a
|
||||
// spec its own scan found; every other workflow reads its own specDir.
|
||||
// readOverview() keeps the read inside the project root.
|
||||
// One of the spec's files, read-only: overview.md by default, or with
|
||||
// ?file=draft or ?file=map the live PLAN-DRAFT or the Pathfinder map. A
|
||||
// dashboard honors ?spec= only for a spec its own scan found; every other
|
||||
// workflow reads its own specDir. readSpecFile() keeps the read inside the
|
||||
// project root, and names the file it read in X-Spec-File.
|
||||
function overview(req, res, ctx, url) {
|
||||
const state = ctx.readState() || {};
|
||||
const asked = url.searchParams.get("spec");
|
||||
const kind = url.searchParams.get("file") || "overview";
|
||||
const spec =
|
||||
state.workflow === "dashboard"
|
||||
? (state.scan?.specs || []).some((s) => s && s.dir === asked)
|
||||
@@ -320,10 +323,14 @@ function overview(req, res, ctx, url) {
|
||||
res.writeHead(204, baseHeaders({ "cache-control": "no-store" }));
|
||||
res.end();
|
||||
};
|
||||
readOverview(state.worktree || state.project, spec)
|
||||
.then((text) =>
|
||||
typeof text === "string"
|
||||
? send(res, 200, text, "text/markdown; charset=utf-8", { "cache-control": "no-store" })
|
||||
readSpecFile(state.worktree || state.project, spec, kind)
|
||||
.then((found) =>
|
||||
found
|
||||
? send(res, 200, found.text, "text/markdown; charset=utf-8", {
|
||||
"cache-control": "no-store",
|
||||
// Encoded: a header value is bytes, and a file name need not be ASCII.
|
||||
"x-spec-file": encodeURIComponent(found.file),
|
||||
})
|
||||
: noOverview()
|
||||
)
|
||||
.catch(noOverview);
|
||||
|
||||
@@ -500,15 +500,38 @@ export async function removeCleanup(ids, opts = {}) {
|
||||
* and a symlink pointing outside all come back null.
|
||||
*/
|
||||
export async function readOverview(root, specDir) {
|
||||
const found = await readSpecFile(root, specDir, "overview");
|
||||
return found ? found.text : null;
|
||||
}
|
||||
|
||||
// The files a spec folder can show as a tab, by kind: Document's overview,
|
||||
// Plan's live draft (the newest PLAN-DRAFT that is not a `-prev` copy, as in
|
||||
// scan.mjs) and Pathfinder's map.
|
||||
async function specFileName(dir, kind) {
|
||||
if (kind === "overview") return "overview.md";
|
||||
if (kind === "map") return "pathfinder/map.md";
|
||||
if (kind !== "draft") return null;
|
||||
const drafts = (await fs.promises.readdir(dir)).filter((n) => /^PLAN-DRAFT.*\.md$/i.test(n));
|
||||
return drafts.filter((n) => !/-prev\.md$/i.test(n)).sort().reverse()[0] || drafts[0] || null;
|
||||
}
|
||||
|
||||
/**
|
||||
* One of a spec's files (`kind`: overview, draft or map), read-only, as
|
||||
* `{ file, text }` with `file` relative to the spec folder, or null. Kept
|
||||
* inside the root the same way readOverview() is.
|
||||
*/
|
||||
export async function readSpecFile(root, specDir, kind) {
|
||||
if (!root || !specDir || typeof specDir !== "string" || path.isAbsolute(specDir)) return null;
|
||||
try {
|
||||
const file = path.resolve(root, specDir, "overview.md");
|
||||
const name = await specFileName(path.resolve(root, specDir), kind);
|
||||
if (!name) return null;
|
||||
const file = path.resolve(root, specDir, name);
|
||||
const [realFile, realRoot] = await Promise.all([fs.promises.realpath(file), fs.promises.realpath(root)]);
|
||||
// path.relative, not a prefix test: a root of `C:\` or `/` already ends
|
||||
// in the separator, and `root + sep` would then match nothing at all.
|
||||
const rel = path.relative(realRoot, realFile);
|
||||
if (!rel || rel === ".." || rel.startsWith(".." + path.sep) || path.isAbsolute(rel)) return null;
|
||||
return await fs.promises.readFile(realFile, "utf8");
|
||||
return { file: name, text: await fs.promises.readFile(realFile, "utf8") };
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
|
||||
Reference in new issue
Block a user