projectstore-claude 0.29.2 → 0.29.4

package/node_modules/projectstore/scripts/stages.mjs

@@ -0,0 +1,84 @@
+// projectstore — stages.mjs: how a story's status reads on the board.
+//
+// One table for two readers: the kanban board (scripts/kanban.mjs) and the
+// band above the prompt (hooks/band.tsx), which counts an epic's stories by
+// the same rule so the band and kanban.md never disagree. The band is a Claude
+// Code hooks module and runs with no Node, so this file imports nothing at
+// all — keep it that way.
+
+// Statuses that describe work which is not on the board by definition: it was
+// replaced, postponed, or set aside. Putting them in a column would claim the
+// work is queued, which is the opposite of what the status says.
+export const NOT_ACTIONABLE = new Set(["superseded", "deferred", "parked"]);
+
+// A lower-cased status to its board column. Exact match; anything the table
+// does not name is Backlog.
+export function statusToColumn(status) {
+  const m = {
+    planned: "Backlog",
+    todo: "ToDo",
+    "to-do": "ToDo",
+    "in-progress": "In Progress",
+    in_progress: "In Progress",
+    "in progress": "In Progress",
+    review: "Review",
+    done: "Done",
+    closed: "Done",
+  };
+  return m[status] || "Backlog";
+}
+
+// The band's three stages, folded from the board's columns.
+export const COLUMN_STAGE = Object.freeze({
+  Done: "done",
+  "In Progress": "active",
+  Review: "active",
+  ToDo: "backlog",
+  Backlog: "backlog",
+});
+
+// A story's stage from its raw frontmatter status, as the board reads it:
+// lower-cased; no status, or a status the board leaves off, counts nowhere
+// (null).
+export function stageOf(raw) {
+  if (raw === null || raw === undefined || raw === "") return null;
+  const status = String(raw).toLowerCase();
+  if (NOT_ACTIONABLE.has(status)) return null;
+  return COLUMN_STAGE[statusToColumn(status)] || "backlog";
+}
+
+// Raw statuses → { done, active, backlog }.
+export function foldStages(statuses) {
+  const out = { done: 0, active: 0, backlog: 0 };
+  for (const raw of statuses) {
+    const stage = stageOf(raw);
+    if (stage) out[stage]++;
+  }
+  return out;
+}
+
+// Line-based frontmatter: `key: value` scalars between the opening `---` and
+// the next one. Quoted values are JSON-decoded (titles that hold quotes),
+// `null` is null; block sequences are invisible to it.
+export function parseFrontmatter(md) {
+  const m = md.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return { data: {}, body: md };
+  const data = {};
+  for (const line of m[1].split("\n")) {
+    const kv = line.match(/^(\w+):\s*(.*)$/);
+    if (!kv) continue;
+    let v = kv[2].trim();
+    if (v === "null") v = null;
+    else if (v.startsWith('"') && v.endsWith('"')) {
+      // JSON.parse round-trips escaped scalars from renderTemplate's _json
+      // form (titles containing quotes); fall back to the bare strip.
+      try {
+        v = JSON.parse(v);
+      } catch {
+        v = v.slice(1, -1);
+      }
+    }
+    data[kv[1]] = v;
+  }
+  return { data, body: md.slice(m[0].length) };
+}

package/node_modules/projectstore/scripts/statusline-launcher.mjs

@@ -20,7 +20,7 @@ import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { spawnSync } from "node:child_process";
-import { pathToFileURL, fileURLToPath } from "node:url";
+import { pathToFileURL } from "node:url";
 
 // Substituted by renderStatusLineLauncher() in scripts/lib.mjs — the fallback
 // root and the harness's own variable names (this file runs before it knows
@@ -35,7 +35,9 @@ const PLUGIN_ROOT_ENV = "__PROJECTSTORE_PLUGIN_ROOT_ENV__";
 const PROJECT_DIR = "__PROJECTSTORE_PROJECT__";
 
 function versionKey(v) {
-  const p = String(v || "0").split(".").map((n) => parseInt(n, 10) || 0);
+  const p = String(v || "0")
+    .split(".")
+    .map((n) => parseInt(n, 10) || 0);
   return [p[0] || 0, p[1] || 0, p[2] || 0]; // pad: a missing component must compare as 0, not NaN
 }
 
@@ -46,16 +48,24 @@ function versionKey(v) {
 function installedRoot() {
   try {
     const claudeHome = (HOME_ENV && process.env[HOME_ENV]) || join(homedir(), ".claude");
-    const reg = JSON.parse(
-      readFileSync(join(claudeHome, "plugins", "installed_plugins.json"), "utf8"),
-    );
+    const reg = JSON.parse(readFileSync(join(claudeHome, "plugins", "installed_plugins.json"), "utf8"));
     const family = dirname(FALLBACK_ROOT); // …/<marketplace>/projectstore
     // This launcher lives at <project>/<config dir>/<runtime dir>/…: a row the
     // host recorded for THIS checkout (local scope, one per checkout) comes
     // first; another checkout's newer install is the fallback, not the pick.
     let project = null;
-    try { project = realpathSync(PROJECT_DIR); } catch { project = PROJECT_DIR || null; }
-    const sameProject = (p) => { try { return Boolean(project && p && realpathSync(p) === project); } catch { return false; } };
+    try {
+      project = realpathSync(PROJECT_DIR);
+    } catch {
+      project = PROJECT_DIR || null;
+    }
+    const sameProject = (p) => {
+      try {
+        return Boolean(project && p && realpathSync(p) === project);
+      } catch {
+        return false;
+      }
+    };
     const found = [];
     for (const [key, list] of Object.entries((reg && reg.plugins) || {})) {
       if (key !== "projectstore" && !key.startsWith("projectstore@")) continue;
@@ -116,12 +126,20 @@ for (const root of [installedRoot(), FALLBACK_ROOT]) {
 if (!rendered) {
   let out = null;
   try {
-    const stdin = (() => { try { return readFileSync(0, "utf8"); } catch { return ""; } })();
+    const stdin = (() => {
+      try {
+        return readFileSync(0, "utf8");
+      } catch {
+        return "";
+      }
+    })();
     const projectDir = (() => {
       try {
         const i = JSON.parse(stdin) || {};
         return (i.workspace && i.workspace.project_dir) || i.cwd || null;
-      } catch { return null; }
+      } catch {
+        return null;
+      }
     })();
     const claudeHome = (HOME_ENV && process.env[HOME_ENV]) || join(homedir(), ".claude");
     const candidates = [
@@ -130,11 +148,18 @@ if (!rendered) {
     ].filter(Boolean);
     for (const p of candidates) {
       let cmd = null;
-      try { cmd = JSON.parse(readFileSync(p, "utf8"))?.statusLine?.command; } catch { continue; }
+      try {
+        cmd = JSON.parse(readFileSync(p, "utf8"))?.statusLine?.command;
+      } catch {
+        continue;
+      }
       if (typeof cmd !== "string" || !cmd.trim()) continue;
       if (cmd.includes("statusline.mjs")) continue; // ours — would recurse
       const r = spawnSync(cmd, { shell: true, input: stdin, encoding: "utf8", timeout: 2000, maxBuffer: 1 << 20 });
-      if (r.status === 0 && r.stdout && r.stdout.trim()) { out = r.stdout.replace(/\s+$/, ""); break; }
+      if (r.status === 0 && r.stdout && r.stdout.trim()) {
+        out = r.stdout.replace(/\s+$/, "");
+        break;
+      }
     }
   } catch {}
   process.stdout.write((out || "") + "\n");

package/node_modules/projectstore/scripts/statusline.mjs

@@ -18,13 +18,21 @@
 // vault reads (ADR-006):
 //   1. this session's pointer file
 //      (<project>/.projectstore/state/sessions/<session_id>.json — written by
-//      the PreToolUse hook with denormalized titles), else
+//      the tool hooks with denormalized titles, a write's after the write;
+//      by `session refresh` after a story close; and at SessionStart), else
 //   2. an explicit localized cold-start line ("no epic or story in this
 //      session yet"). Never blank while enabled; a pointer that exists but
 //      fails to parse renders an error-marked string, never the cheerful
 //      cold-start line. The renderer drops a .last-render.json breadcrumb so
 //      doctor can detect session_id divergence between hook and statusLine.
 //
+// While this session's band above the prompt is drawing (hooks/band.tsx keeps
+// a heartbeat fresh in the session-state directory), our line gives way to it:
+// composed, the base HUD prints alone; standalone, the badge and the 📚
+// segment drop. A missing, unreadable or stale heartbeat changes nothing, so
+// a band that cannot draw always gives the line back (the band ADR, decision
+// 5; spec contract 11).
+//
 // Everything is best-effort; on any error emit what we have and exit 0.
 
 import { readFileSync, existsSync } from "node:fs";
@@ -41,6 +49,7 @@ import {
   claudeHome,
   writeFileAtomic,
 } from "./lib.mjs";
+import { heartbeatFile, heartbeatYields, storyIsCurrent } from "./band-shared.mjs";
 
 const SELF = fileURLToPath(import.meta.url);
 const SEP = " · ";
@@ -53,7 +62,11 @@ const ARROW = " › ";
 process.stdout.on("error", () => process.exit(0));
 
 function readRawStdin() {
-  try { return readFileSync(0, "utf8"); } catch { return ""; }
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
 }
 
 const FALLBACK_STRINGS = {
@@ -146,13 +159,29 @@ function bookSegment(cfg, proj, input, strings) {
   if (!state || !state.active_epic) return BOOK + strings.statusline_no_work;
 
   let seg = BOOK + (state.epic_title || state.active_epic);
-  if (state.active_story) {
+  // The story only while it is work the session is moving — the band's rule
+  // (ADR-006, amended 2026-10-12): a done, closed, parked or status-less
+  // story leaves the epic alone.
+  if (state.active_story && storyIsCurrent(state.story_status)) {
     seg += ARROW + (state.story_title || state.active_story);
     if (state.story_status) seg += ` (${state.story_status})`;
   }
   return seg;
 }
 
+// Whether this session's band is drawing now. Read after bookSegment has
+// written the breadcrumb, so doctor keeps its evidence while the band is up;
+// any failure reads as "no band" and the line stays.
+function bandYields(proj, sid) {
+  try {
+    const name = heartbeatFile(sid);
+    if (!name) return false;
+    return heartbeatYields(JSON.parse(readFileSync(join(stateDir(proj), name), "utf8")), Date.now());
+  } catch {
+    return false;
+  }
+}
+
 // The base statusLine command we compose with — highest-precedence entry BELOW
 // our own local one: project settings.json, else user settings.json.
 function discoverBaseCommand(projectDir) {
@@ -193,25 +222,38 @@ function runBase(cmd, rawStdin, env) {
 
 function main() {
   const raw = readRawStdin();
-  let input = {};
-  try { input = JSON.parse(raw) || {}; } catch { input = {}; }
+  let input;
+  try {
+    input = JSON.parse(raw) || {};
+  } catch {
+    input = {};
+  }
 
   // The status line gets no project variable from the harness; the project is
   // on stdin, and it deliberately beats any exported variable. Read the config
   // for that directory directly — never by mutating process.env, which the
   // composed base command would then inherit.
-  const projectDir =
-    (input.workspace && input.workspace.project_dir) || input.cwd || process.cwd();
+  const projectDir = (input.workspace && input.workspace.project_dir) || input.cwd || process.cwd();
 
-  let cfg = null;
-  try { cfg = readConfigAt(projectDir); } catch { cfg = null; }
+  let cfg;
+  try {
+    cfg = readConfigAt(projectDir);
+  } catch {
+    cfg = null;
+  }
 
   const strings = loadStrings(cfg && cfg.language);
-  let book = null;
-  try { book = cfg && cfg.vault_path ? bookSegment(cfg, projectDir, input, strings) : null; } catch { book = null; }
+  let book;
+  try {
+    book = cfg && cfg.vault_path ? bookSegment(cfg, projectDir, input, strings) : null;
+  } catch {
+    book = null;
+  }
+
+  const yielded = Boolean(cfg && cfg.vault_path && bandYields(projectDir, input.session_id));
 
   const showVersion = !(cfg && cfg.statusline && cfg.statusline.show_version === false);
-  const ver = showVersion ? pluginVersion() : null;
+  const ver = showVersion && !yielded ? pluginVersion() : null;
   const badge = ver ? `[PS#${ver}] ` : "";
 
   const baseCmd = discoverBaseCommand(projectDir);
@@ -219,8 +261,7 @@ function main() {
 
   // "Never blank" must be total: even if the resolver threw (book === null on a
   // bound project), fall back to the cold-start line rather than vanishing.
-  const bookOut =
-    cfg && cfg.vault_path ? book || BOOK + strings.statusline_no_work : null;
+  const bookOut = cfg && cfg.vault_path && !yielded ? book || BOOK + strings.statusline_no_work : null;
 
   const lines = [];
   if (baseOut) {

package/node_modules/projectstore/scripts/story-section.mjs

@@ -132,9 +132,13 @@ function main() {
   const status = String(fm.status || "").toLowerCase();
 
   if (mode === "plan") {
-    const r = insertSection(text, "implementation_plan", lang,
+    const r = insertSection(
+      text,
+      "implementation_plan",
+      lang,
       "<!-- Route through the covering spec's contracts: which contracts, in what order, which files. Filled at the gate. -->",
-      ["decomposition", "description"]);
+      ["decomposition", "description"],
+    );
     text = r.text;
     if (r.inserted) notes.push("inserted Implementation Plan section");
     if (!["in-progress", "in_progress", "review", "done"].includes(status)) {
@@ -148,9 +152,13 @@ function main() {
     text = setFm(text, "plan_updated_at", JSON.stringify(now));
     notes.push("stamped plan_updated_at");
   } else {
-    const r = insertSection(text, "final_summary", lang,
+    const r = insertSection(
+      text,
+      "final_summary",
+      lang,
       "<!-- What changed, why, tests executed, risks and follow-ups. Filled at the gate. -->",
-      ["acceptance", "decomposition", "description"]);
+      ["acceptance", "decomposition", "description"],
+    );
     text = r.text;
     if (r.inserted) notes.push("inserted Final Summary section");
     if (status !== "done") {
@@ -181,28 +189,42 @@ function main() {
       // otherwise shifts every later pairing and the report drowns in
       // artifacts of the shift instead of naming the change. Line numbers are
       // post-normalization (volatile keys may have been inserted).
-      const al = a.split("\n"), bl = b.split("\n");
+      const al = a.split("\n"),
+        bl = b.split("\n");
       let lo = 0;
       while (lo < al.length && lo < bl.length && al[lo] === bl[lo]) lo++;
-      let hiA = al.length - 1, hiB = bl.length - 1;
-      while (hiA > lo && hiB > lo && al[hiA] === bl[hiB]) { hiA--; hiB--; }
+      let hiA = al.length - 1,
+        hiB = bl.length - 1;
+      while (hiA > lo && hiB > lo && al[hiA] === bl[hiB]) {
+        hiA--;
+        hiB--;
+      }
       for (let i = 0; i <= Math.max(hiA, hiB) - lo && drift.length < 5; i++) {
-        const x = al[lo + i], y = bl[lo + i];
+        const x = al[lo + i],
+          y = bl[lo + i];
         if (lo + i > hiA && lo + i > hiB) break;
-        drift.push(`normalized line ${lo + i + 1}: ${JSON.stringify((x ?? "«absent»").slice(0, 120))} vs ${JSON.stringify((y ?? "«absent»").slice(0, 120))}`);
+        drift.push(
+          `normalized line ${lo + i + 1}: ${JSON.stringify((x ?? "«absent»").slice(0, 120))} vs ${JSON.stringify((y ?? "«absent»").slice(0, 120))}`,
+        );
       }
     }
     check = { baseline: resolve(checkPath), match: a === b, drift };
   }
 
-  process.stdout.write(JSON.stringify({
-    path: abs,
-    mode,
-    changed: text !== original,
-    check,
-    notes,
-    content: text,
-  }, null, 2) + "\n");
+  process.stdout.write(
+    JSON.stringify(
+      {
+        path: abs,
+        mode,
+        changed: text !== original,
+        check,
+        notes,
+        content: text,
+      },
+      null,
+      2,
+    ) + "\n",
+  );
 }
 
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {