projectstore-codex 0.0.1 → 0.28.1

package/node_modules/projectstore/scripts/draft.mjs

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+// projectstore — draft.mjs
+// Pure renderer. Given a kind declared in the bound layout (epic/story are
+// structural special cases; every other kind comes from the layout's folders)
+// and arguments, produces a JSON draft on stdout describing the target file
+// and its rendered content. Does NOT touch the disk — no writes AND no
+// mkdir: declining the approval gate must leave the vault byte-for-byte
+// unchanged (ADR-001 review / PS-IMPROVE story-006). Directory creation is
+// the caller's job after approval (the Write tool creates parents).
+//
+// Output schema:
+// {
+//   "kind": "adr",
+//   "path": "/abs/path/to/vault/adr/foo.md",
+//   "content": "...rendered markdown...",
+//   "index": {                          // optional, when folder has a README index
+//     "path": "/abs/path/to/vault/adr/README.md",
+//     "folder": "adr",                  //   selector for `reconcile.mjs --write
+//                                       //   --only indexes=<folder>` — the command
+//                                       //   applies the row by regenerating the
+//                                       //   table, never by an Edit append, and
+//                                       //   prose must not derive this path itself
+//                                       //   (ADR-009: no logic in prose). Note the
+//                                       //   folder is NOT the kind: runbook lives
+//                                       //   in ops/.
+//     "line": "| [foo](./foo.md) | Foo | proposed | 2026-05-19 |"
+//                                       //   preview only — the row is written by
+//                                       //   reconcile's rebuildIndexRows. Rendered
+//                                       //   by the same rules, so for a newly
+//                                       //   created artifact it is byte-identical
+//                                       //   to the row that lands.
+//   },
+//   "collision": {                      // null, or the normalized-identity clash
+//     "with": "ADR-003-foo.md",        //   (SPEC-002 contract 4 — computed in
+//     "identity": "foo",               //   lib.mjs; command prose only renders
+//     "selfMatch": false,              //   it, an exact `test -e` cannot see
+//     "digitLeading": false            //   cross-era collisions)
+//   },
+//   "warnings": ["..."],               // e.g. digit-leading slug advisory
+//   "vars": { ... }                     // template vars used (for debugging)
+// }
+//
+// Errors are written to stderr as plain text and exit code 1.
+
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import {
+  readConfig,
+  loadLayout,
+  folderByKind,
+  loadTemplate,
+  renderTemplate,
+  parseFrontmatter,
+  slugify,
+  findSlugCollision,
+  displayNumberOf,
+  today, isMain
+} from "./lib.mjs";
+
+function die(msg, code = 1) {
+  process.stderr.write(`projectstore/draft: ${msg}\n`);
+  process.exit(code);
+}
+
+function commonVars(cfg) {
+  return {
+    date: today(),
+    author: cfg.default_author || process.env.USER || "anonymous",
+    tags: JSON.stringify(cfg.tags || []),
+  };
+}
+
+// Preview of the row the regeneration will land. Every cell is read from the
+// RENDERED template's own frontmatter, by the same rules reconcile's
+// rebuildIndexRows applies to an artifact on disk — so for a newly created
+// artifact the preview is byte-identical to the written row, and a new kind's
+// template stays the single source of its initial status. The label in
+// particular must not come from `vars.id`: for date-prefixed kinds that is the
+// bare slug while the regeneration labels by filename stem, and the two rows
+// visibly disagreed.
+function makeIndexLine(kind, fileName, vars, content, folder) {
+  const fm = parseFrontmatter(content).data;
+  // Empty, not today's date, when a template carries neither field — the
+  // regeneration renders "" there, and byte-identity is a contract that must
+  // hold for a custom kind too, not just the bundled ones.
+  const date = fm.date || fm.created || "";
+  if (kind === "epic") {
+    return `| [${vars.id}](./${vars.id}/epic.md) | ${fm.title || vars.id} | ${fm.status || "planned"} | ${date} |`;
+  }
+  const status = fm.status || (folder.numbered ? "proposed" : "draft");
+  const number = displayNumberOf(fm, fileName, { prefix: folder.prefix || null });
+  const label = number && folder.prefix ? `${folder.prefix}${number}` : fileName.replace(/\.md$/, "");
+  return `| [${label}](./${fileName}) | ${fm.title || label} | ${status} | ${date} |`;
+}
+
+function indexPath(vault, folderPath) {
+  return join(vault, folderPath, "README.md");
+}
+
+// ─── Builders (layout-driven — PS-SPEC story-001) ──────────────────────
+//
+// Any kind declared in the layout with a folder builds here with a slug-only
+// filename (ADR-010: identity lives in the slug; sequential numbering is
+// removed from creation — collision-free by construction, no read-then-write
+// race between concurrent writers). Layout keys `numbered`/`prefix`/`pad`
+// remain declared for grandfathered labels and legacy-strip matching, but
+// creation no longer reads a next number. epic/story remain structural
+// special cases (subfolder-per-id, stories/ subdirectory).
+
+// Read-only normalized-identity scan of the target directory (SPEC-002
+// contract 4). Directory entries include folder-shape stories (dirs).
+function scanCollision(dir, fileName, opts) {
+  if (!existsSync(dir)) return null;
+  return findSlugCollision(fileName, readdirSync(dir).sort(), opts);
+}
+
+function digitLeadingWarnings(slug) {
+  return /^\d/.test(slug)
+    ? [`Slug "${slug}" is digit-leading — the filename visually resembles a numbered-era artifact. Machine resolution keys on id:, so this is safe, but a word-leading title avoids the ambiguity.`]
+    : [];
+}
+
+function buildEpic(cfg, layout, args) {
+  const id = args[0];
+  const title = args.slice(1).join(" ").trim();
+  if (!id || !title) die("Epic requires <id> and <title>");
+  const folder = folderByKind(layout, "epic");
+  if (!folder) die("Layout has no folder of kind=epic");
+  const vault = cfg.vault_path;
+  const epicDir = join(vault, folder.path, id);
+  const vars = { ...commonVars(cfg), id, title };
+  const tpl = loadTemplate(cfg.language || "en", "epic");
+  const content = renderTemplate(tpl, vars);
+  return {
+    kind: "epic",
+    path: join(epicDir, "epic.md"),
+    content,
+    index: existsSync(indexPath(vault, folder.path))
+      ? {
+          path: indexPath(vault, folder.path),
+          folder: folder.path,
+          line: makeIndexLine("epic", "epic.md", vars, content, folder),
+        }
+      : null,
+    collision: null, // epic ids are user-chosen; the command's own folder check gates them
+    warnings: [],
+    vars,
+  };
+}
+
+function buildStory(cfg, layout, args) {
+  const epicId = args[0];
+  const title = args.slice(1).join(" ").trim();
+  if (!epicId || !title) die("Story requires <epic_id> and <title>");
+  const folder = folderByKind(layout, "epic");
+  if (!folder) die("Layout has no folder of kind=epic");
+  const vault = cfg.vault_path;
+  const storiesDir = join(vault, folder.path, epicId, "stories");
+  if (!existsSync(join(vault, folder.path, epicId))) {
+    die(`Epic folder not found: ${folder.path}/${epicId}. Create the epic first via /projectstore:epic.`);
+  }
+  const storyPrefix = folder.story_prefix || "story-";
+  const slug = slugify(title);
+  const id = `${storyPrefix}${slug}`;
+  const fileName = `${id}.md`;
+  const vars = {
+    ...commonVars(cfg),
+    id,
+    epic_id: epicId,
+    title,
+    slug,
+  };
+  const tpl = loadTemplate(cfg.language || "en", "story");
+  // The identity scope is the EPIC, not just stories/: standalone
+  // epics/<id>/story-<slug>.md files share it (doctor scopes them together).
+  const epicDir = join(vault, folder.path, epicId);
+  const scopeNames = [
+    ...(existsSync(storiesDir) ? readdirSync(storiesDir) : []),
+    ...readdirSync(epicDir).filter((n) => n.startsWith("story-") && n.endsWith(".md")),
+  ].sort();
+  return {
+    kind: "story",
+    path: join(storiesDir, fileName),
+    content: renderTemplate(tpl, vars),
+    index: null,
+    collision: findSlugCollision(fileName, scopeNames, { story: true }),
+    warnings: digitLeadingWarnings(slug),
+    vars,
+  };
+}
+
+function buildSimple(kind, cfg, layout, args) {
+  const title = args.join(" ").trim();
+  if (!title) die(`${kind} requires a title`);
+  const folder = folderByKind(layout, kind);
+  const vault = cfg.vault_path;
+  const dir = join(vault, folder.path);
+  const slug = slugify(title);
+  const date = today();
+  const fileName = folder.date_prefix ? `${date}-${slug}.md` : `${slug}.md`;
+  const vars = {
+    ...commonVars(cfg),
+    id: slug, // exact machine id (ADR-010): the slug itself, no allocated number
+    slug,
+    title,
+  };
+  const tpl = loadTemplate(cfg.language || "en", kind);
+  const content = renderTemplate(tpl, vars);
+  return {
+    kind,
+    path: join(dir, fileName),
+    content,
+    index: existsSync(indexPath(vault, folder.path))
+      ? {
+          path: indexPath(vault, folder.path),
+          folder: folder.path,
+          line: makeIndexLine(kind, fileName, vars, content, folder),
+        }
+      : null,
+    collision: scanCollision(dir, fileName, { prefix: folder.prefix || null }),
+    // A date-prefixed filename (meetings) is digit-leading by design — the
+    // slug itself is what must not resemble the numbered era.
+    warnings: folder.date_prefix ? [] : digitLeadingWarnings(slug),
+    vars,
+  };
+}
+
+// ─── Main ──────────────────────────────────────────────────────────────
+
+function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length < 2) die("usage: draft.mjs <kind> <args...>");
+  const kind = argv[0];
+  const rest = argv.slice(1);
+
+  const cfg = readConfig();
+  if (!cfg) die("No projectstore config. Run /projectstore:bind <vault-path> first.");
+  const layout = loadLayout(cfg.layout);
+
+  let result;
+  if (kind === "epic") {
+    result = buildEpic(cfg, layout, rest);
+  } else if (kind === "story") {
+    result = buildStory(cfg, layout, rest);
+  } else {
+    const folder = folderByKind(layout, kind);
+    if (!folder) {
+      const known = layout.folders.map((f) => f.kind).filter((k) => k !== "epic");
+      die(`Unknown kind: ${kind}. This layout (${cfg.layout}) declares: epic, story, ${known.join(", ")}.`);
+    }
+    // `numbered` folders route through buildSimple too (ADR-010): the key
+    // stays declared in layouts for grandfathered labels, creation ignores it.
+    result = buildSimple(kind, cfg, layout, rest);
+  }
+
+  process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+}
+
+if (isMain(import.meta.url)) {
+  main();
+}

package/node_modules/projectstore/scripts/graph.mjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+// projectstore — graph.mjs
+// Derives graph.md — the vault link graph — from body links and typed
+// frontmatter relations (source of truth). Third root-level derived view
+// beside kanban.md and code-map.md (spec:
+// vault-link-graph-derived-view-and-shared-link-resolver; the accepted
+// link-graph ADR decides the shape). Nodes are layout artifacts keyed by
+// full vault-relative path; edges are typed; nothing resolves silently —
+// dead, ambiguous and out-of-scope targets stay visible as edges.
+//
+// Output: JSON { path, content, stats } — compute only. The applier is
+// reconcile.mjs --write (atomic replace, recompute-at-write), not the
+// harness: no Write-tool step remains in the derived-view flows.
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import {
+  readConfig,
+  loadLayout,
+  folderByKind,
+  listOf,
+  nowIso,
+  buildNodeIndex,
+  extractLinks,
+  resolveLinkTarget,
+  storyMatchesEntry, isMain
+} from "./lib.mjs";
+import { walkVaultFiles } from "./doctor.mjs";
+
+function die(msg) {
+  process.stderr.write(`projectstore/graph: ${msg}\n`);
+  process.exit(1);
+}
+
+// Frontmatter refs arrive as inline-flow lists (listOf) or, for
+// supersedes/superseded_by, as a bare scalar — normalize both to a list.
+function refsOf(fm, key) {
+  const viaList = listOf(fm, key);
+  if (viaList.length) return viaList;
+  const raw = fm[key];
+  return typeof raw === "string" && raw && raw !== "[]" && !raw.trim().startsWith("[")
+    ? [raw.trim()]
+    : [];
+}
+
+// Resolve a qualified "<epic-id>/<story-id>" spec entry to a story node —
+// the same tiered control flow as doctor's resolveSpecStory, on the same
+// SPEC-002 primitive (storyMatchesEntry): strongest tier wins across the
+// epic's stories, a tie within it is ambiguity, never a silent first match.
+function resolveStoryEntry(entry, index, epicsPath) {
+  const m = String(entry).match(/^([^/]+)\/(.+)$/);
+  if (!m) return { outcome: "dead" };
+  const [, epicId, storyId] = m;
+  let best = 0;
+  let hits = [];
+  for (const n of index.nodes) {
+    if (n.type !== "story" || !n.path.startsWith(`${epicsPath}/${epicId}/`)) continue;
+    const tier = storyMatchesEntry(storyId, { id: n.identity, stem: n.stem });
+    if (!tier) continue;
+    if (best === 0 || tier < best) { best = tier; hits = [n]; }
+    else if (tier === best) hits.push(n);
+  }
+  if (hits.length === 1) return { outcome: "node", node: hits[0] };
+  if (hits.length > 1) return { outcome: "ambiguous", candidates: hits.map((n) => n.path).sort() };
+  return { outcome: "dead" };
+}
+
+export function buildGraph(cfg, layout, { files = null } = {}) {
+  const index = buildNodeIndex(cfg, layout);
+  const vaultFiles = files ?? walkVaultFiles(cfg.vault_path);
+  const epicsPath = folderByKind(layout, "epic")?.path ?? null;
+
+  // Dedup on the (from, kind, to) triple (spec contract 4). The To cell for
+  // dead targets is the raw text as written; ambiguous additionally lists
+  // every candidate path in the row.
+  const edges = new Map();
+  const addEdge = (from, kind, to) => {
+    const k = `${from}\u0000${kind}\u0000${to}`;
+    if (!edges.has(k)) edges.set(k, { from, kind, to });
+  };
+  const addResolved = (from, r, raw, kinds = {}) => {
+    if (r.outcome === "node") addEdge(from, kinds.node ?? "wikilink", r.node.path);
+    else if (r.outcome === "dead") addEdge(from, "dead", raw);
+    else if (r.outcome === "ambiguous") addEdge(from, "ambiguous", `${raw} (matches: ${r.candidates.join(", ")})`);
+    else addEdge(from, "out-of-scope", r.path ?? raw);
+  };
+
+  const exists = (rel) => existsSync(join(cfg.vault_path, rel));
+  for (const n of index.nodes) {
+    // Body links — kind-unscoped, extracted ONLY from node files: derived
+    // views and READMEs are never link sources, so graph.md can never feed
+    // back into itself (spec contract 2). One ctx per node: the resolver
+    // caches its file set on the ctx object, and rebuilding it per link
+    // would be O(links × files) — the growth curve this view exists for.
+    const ctx = { sourceRel: n.path, index, files: vaultFiles, exists };
+    for (const link of extractLinks(n.body)) {
+      addResolved(n.path, resolveLinkTarget(link.target, link.type, ctx), link.target, { node: link.type });
+    }
+
+    // Typed frontmatter relations — kind-scoped by their field (spec
+    // contract 3). The two-sided spec↔story declaration is read as a union
+    // and normalized to spec→story before dedup (contract 4); asymmetry is
+    // doctor's existing checkSpecLinks warning, not a graph finding.
+    const refCtx = (kinds) => ({ ...ctx, kinds });
+    if (n.type === "spec") {
+      for (const entry of refsOf(n.fm, "stories")) {
+        const r = epicsPath ? resolveStoryEntry(entry, index, epicsPath) : { outcome: "dead" };
+        if (r.outcome === "node") addEdge(n.path, "spec-covers", r.node.path);
+        else addResolved(n.path, r, entry);
+      }
+      for (const entry of refsOf(n.fm, "adr")) {
+        const r = resolveLinkTarget(entry, "ref", refCtx(["adr"]));
+        if (r.outcome === "node") addEdge(n.path, "spec-implements-adr", r.node.path);
+        else addResolved(n.path, r, entry);
+      }
+    }
+    if (n.type === "story") {
+      for (const entry of refsOf(n.fm, "specs")) {
+        const r = resolveLinkTarget(entry, "ref", refCtx(["spec"]));
+        if (r.outcome === "node") addEdge(r.node.path, "spec-covers", n.path);
+        else addResolved(n.path, r, entry);
+      }
+    }
+    if (n.type === "adr") {
+      for (const entry of refsOf(n.fm, "supersedes")) {
+        const r = resolveLinkTarget(entry, "ref", refCtx(["adr"]));
+        if (r.outcome === "node") addEdge(n.path, "supersedes", r.node.path);
+        else addResolved(n.path, r, entry);
+      }
+      for (const entry of refsOf(n.fm, "superseded_by")) {
+        // Normalized to the superseding ADR as From — one direction, dedup
+        // then collapses the two-sided declaration.
+        const r = resolveLinkTarget(entry, "ref", refCtx(["adr"]));
+        if (r.outcome === "node") addEdge(r.node.path, "supersedes", n.path);
+        else addResolved(n.path, r, entry);
+      }
+    }
+    // Folder structure: epic.md contains its stories.
+    if (n.type === "epic") {
+      const epicDirPrefix = n.path.replace(/\/epic\.md$/, "/");
+      for (const s of index.nodes) {
+        if (s.type === "story" && s.path.startsWith(epicDirPrefix)) {
+          addEdge(n.path, "epic-contains", s.path);
+        }
+      }
+    }
+  }
+
+  // Stable plain-string sort (from, kind, to) — deterministic across
+  // machines and locales; minimal diffs on a synced root file.
+  const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+  const nodeRows = [...index.nodes].sort((a, b) => cmp(a.path, b.path));
+  const edgeRows = [...edges.values()].sort(
+    (a, b) => cmp(a.from, b.from) || cmp(a.kind, b.kind) || cmp(a.to, b.to));
+
+  const esc = (s) => String(s).replace(/\|/g, "\\|");
+  const lines = [
+    "---",
+    "",
+    "projectstore: derived",
+    `generated_at: ${nowIso()}`,
+    "",
+    "---",
+    "",
+    "# Vault link graph",
+    "",
+    "Nodes (layout artifacts, keyed by vault-relative path) and typed edges,",
+    "derived from body links and frontmatter relations (source of truth).",
+    "Regenerate via `/projectstore:graph`; grep a path to see an artifact's",
+    "full typed neighborhood, both directions, in one call.",
+    "",
+    "## Nodes",
+    "",
+    "| Path | Title | Type | Status |",
+    "|------|-------|------|--------|",
+  ];
+  for (const n of nodeRows) {
+    lines.push(`| ${n.path} | ${esc(n.title)} | ${n.type} | ${n.status ?? "-"} |`);
+  }
+  lines.push("", "## Edges", "", "| From | Kind | To |", "|------|------|----|");
+  for (const e of edgeRows) {
+    lines.push(`| ${e.from} | ${e.kind} | ${e.to} |`);
+  }
+  lines.push("");
+
+  const byKind = {};
+  for (const e of edgeRows) byKind[e.kind] = (byKind[e.kind] || 0) + 1;
+
+  return {
+    content: lines.join("\n"),
+    stats: {
+      nodes: nodeRows.length,
+      edges: edgeRows.length,
+      by_kind: Object.fromEntries(Object.entries(byKind).sort(([a], [b]) => cmp(a, b))),
+    },
+    // The facts the view is rendered from, for the query verbs (neighbors,
+    // lineage): the same edges, so `graph neighbors` and `grep graph.md`
+    // cannot disagree. main() prints content and stats only — reconcile's
+    // parse surface and the golden tests are unchanged.
+    nodes: index.nodes.map((n) => ({ path: n.path, type: n.type, title: n.title, status: n.status })),
+    edges: edgeRows.map((e) => ({ from: e.from, kind: e.kind, to: e.to })),
+  };
+}
+
+function main() {
+  const cfg = readConfig();
+  if (!cfg) die("No projectstore config. Run /projectstore:bind first.");
+  const layout = loadLayout(cfg.layout);
+  const g = buildGraph(cfg, layout);
+  process.stdout.write(JSON.stringify({
+    path: join(cfg.vault_path, "graph.md"),
+    content: g.content,
+    stats: g.stats,
+  }, null, 2) + "\n");
+}
+
+if (isMain(import.meta.url)) {
+  main();
+}