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:
jparkerweb committed 2026-10-26 21:44:38 -07:00
1 parent 0d569954c4
commit 46f1f17261
16 files changed
+210 -50

No files matched your search

+1 -1
View File
@@ -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";
+7 -1
View File
@@ -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>
+13 -12
View File
@@ -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);
+10 -7
View File
@@ -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);
}
+46 -11
View File
@@ -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();
}
+4 -3
View File
@@ -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
+15 -8
View File
@@ -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);
+25 -2
View File
@@ -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;
}