projectstore-claude 0.29.2 → 0.29.3

package/node_modules/projectstore/scripts/binding.mjs

@@ -23,12 +23,26 @@
 // (cli.mjs's resolveProject) and supplies the author. Normative: the CLI
 // story's slice-2 plan (PS-CORE); the fresh config's keys mirror
 // commands/bind.md step 3 (a test pins the two together).
+//
+// `init` creates a whole vault (the story "Scaffold is a core verb, and init
+// creates a whole vault…", PS-CORE; the front-door ADR's decision 7): for a
+// directory that is missing, or there and empty, the plan is the binding's
+// AND the scaffold's, refused as one before anything is made; the apply is
+// mkdir, the binding, `git init`, then the scaffold. Naming the vault stays
+// the confirmation, as for `bind` — `init`'s command line names what it
+// writes, which `scaffold --write`'s does not, so `init` asks nothing even at
+// a terminal. A directory that is not empty is bound as before and never
+// touched: no `git init` inside someone's files, no scaffold. For `bind`, and
+// for that `init`, the scaffold plan only decides the "Next" line.
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, realpathSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { join, resolve, isAbsolute, dirname } from "node:path";
 import { homedir } from "node:os";
 import { writeFileAtomic, pluginRoot, ensureRuntimeDir, layoutPaths, commandForm } from "./lib.mjs";
-import { configPath as harnessConfigPath } from "./harness.mjs";
+import { configPath as harnessConfigPath, invokedAs } from "./harness.mjs";
+import { planScaffold, applyScaffold } from "./scaffold.mjs";
+import { icon, kv, commandBlock, wrap, PLAIN } from "./term.mjs";
 
 export const DEFAULT_LAYOUT = "engineering";
 export const DEFAULT_LANGUAGE = "en";
@@ -71,13 +85,22 @@ function readExisting(configPath) {
   try { return { cfg: JSON.parse(readFileSync(configPath, "utf8")), corrupt: false }; } catch { return { cfg: null, corrupt: true }; }
 }
 
-const shellQuote = (s) => (/^[A-Za-z0-9_\/.~-]+$/.test(s) ? s : `'${String(s).replace(/'/g, `'\\''`)}'`);
+export const shellQuote = (s) => (/^[A-Za-z0-9_\/.~-]+$/.test(s) ? s : `'${String(s).replace(/'/g, `'\\''`)}'`);
+
+// A directory with no entries at all. A `.DS_Store` makes it not empty: that
+// edge stays visible rather than guessed at. Unreadable is not empty either.
+function isEmptyDir(p) {
+  try { return statSync(p).isDirectory() && readdirSync(p).length === 0; } catch { return false; }
+}
 
 // What `bind` would write. `state`: "unbound" (fresh bind), "same" (already
 // bound to this vault — nothing to write), "different" (bound elsewhere —
 // needs --rebind). Refusals are the reasons apply() must not run; each has a
 // code: USAGE (exit 2 upstream), MISSING, REBIND, BOUND, UNREADABLE,
-// NO_PROJECT (exit 1).
+// NO_PROJECT, and on `init`'s whole-vault path the scaffold plan's own
+// (exit 1). `buildsVault`: `init` on a missing or empty directory — mkdir
+// (createsVault, missing only), git and the scaffold follow the binding.
+// `scaffold` is the scaffold plan for the vault, on every path that has one.
 export function planBind(projectDir, { vault, layout = null, language = null, rebind = false, init = false, author = "", env = process.env, root = pluginRoot(), home = homedir() } = {}) {
   const refusals = [];
   const configPath = harnessConfigPath(projectDir, env);
@@ -104,23 +127,81 @@ export function planBind(projectDir, { vault, layout = null, language = null, re
   if (vaultPath && vaultExists && !statSync(vaultPath).isDirectory()) refusals.push({ code: "USAGE", message: `${vaultPath} is not a directory` });
   if (vaultPath && !vaultExists && !init) refusals.push({ code: "MISSING", message: `${vaultPath} does not exist — create it first, or run \`projectstore init ${shellQuote(String(vault))}${rebind ? " --rebind" : ""}\` to create and bind in one step` });
   if (state === "different" && !rebind) refusals.push({ code: "REBIND", message: `${projectDir} is bound to ${before.vault_path}; pass --rebind to point it at ${vaultPath} instead (every other setting is kept)` });
-  if (state === "same" && init) refusals.push({ code: "BOUND", message: `${projectDir} is already bound to ${vaultPath}` });
+  const scaffold = vaultPath ? planScaffold(vaultPath, { layout: chosenLayout, language: chosenLanguage, root }) : null;
+  const missingFolders = Boolean(scaffold && scaffold.ok && scaffold.creates > 0);
+  // Only while the vault is there. A binding whose vault directory was deleted
+  // made `init` refuse as BOUND, so "run init" — the scaffold verb's own
+  // advice for a missing vault — led nowhere; such an `init` rebuilds it
+  // under the binding it already has, writing no config.
+  if (state === "same" && init && vaultExists) refusals.push({ code: "BOUND", message: `${projectDir} is already bound to ${vaultPath}${missingFolders ? ` — ${commandForm("scaffold", { env })} in a session, or \`projectstore scaffold --write\`, creates the layout's missing folders and READMEs` : ""}` });
+  const buildable = Boolean(init && vaultPath && refusals.length === 0 && (!vaultExists || isEmptyDir(vaultPath)));
+  // The whole-vault path is refused as one plan: a missing template or folder
+  // string stops the mkdir too. Elsewhere the scaffold plan's refusals are not
+  // the binding's — a bind into a vault this language cannot scaffold still
+  // binds, and its Next line names `status`.
+  if (buildable && scaffold) refusals.push(...scaffold.refusals);
   const after = state === "same" ? before : state === "different"
     ? { ...before, vault_path: vaultPath, layout: chosenLayout, language: chosenLanguage }
     : { vault_path: vaultPath, layout: chosenLayout, auto_inject: true, language: chosenLanguage, tags: [], default_author: author || "", active_skills: true, approval_mode: "always" };
   const keptKeys = state === "different" ? Object.keys(before).filter((k) => !["vault_path", "layout", "language"].includes(k)).sort() : [];
+  const ok = refusals.length === 0;
   return {
     projectDir, configPath, vault: vaultPath, vaultExists, layout: chosenLayout, language: chosenLanguage, ignored,
-    state, before, after, keptKeys, writes: refusals.length === 0 && state !== "same", createsVault: Boolean(init && vaultPath && !vaultExists && refusals.length === 0), refusals, ok: refusals.length === 0,
+    state, before, after, keptKeys, writes: ok && state !== "same", createsVault: Boolean(init && vaultPath && !vaultExists && ok),
+    buildsVault: buildable && ok, scaffold, refusals, ok,
   };
 }
 
-// Writes what the plan says: the vault directory when init asked for it, the
-// config through writeFileAtomic (its directory made first — the helper never
-// mkdirs). Refuses to run a plan with refusals; a "same" plan writes nothing.
-export function applyBind(plan) {
+// `git init` in a vault `init` just made: no commit, on the person's own
+// init.defaultBranch (no `-b`), quiet, with its stderr captured so git's
+// default-branch hint never reaches the person — its exit status alone
+// decides done or failed. The vault is the cwd, so a spawn ENOENT can only
+// mean git is not on PATH: the one skip the front-door ADR allows, and
+// doctor's vault-git finding then stays. Every variable that locates a
+// repository is dropped (GIT_LOCAL_ENV, git's own `rev-parse
+// --local-env-vars`): inherited from a hook or a script, GIT_DIR alone would
+// make this init create — or reinitialise — a repository somewhere else.
+// `rev-parse --show-toplevel` from the new directory says whether it lies
+// inside a work tree (realpath'd: macOS answers /private/var for /var); git
+// init still runs, and the result carries that top. A failure carries its
+// remedy, so a caller reading --json can relay it as the text does.
+const GIT_LOCAL_ENV = Object.freeze([
+  "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_CONFIG", "GIT_CONFIG_PARAMETERS", "GIT_CONFIG_COUNT",
+  "GIT_OBJECT_DIRECTORY", "GIT_DIR", "GIT_WORK_TREE", "GIT_IMPLICIT_WORK_TREE", "GIT_GRAFT_FILE",
+  "GIT_INDEX_FILE", "GIT_NO_REPLACE_OBJECTS", "GIT_REPLACE_REF_BASE", "GIT_PREFIX",
+  "GIT_SHALLOW_FILE", "GIT_COMMON_DIR",
+]);
+function runGit(vault, { spawn = spawnSync, env = process.env } = {}) {
+  const childEnv = { ...env };
+  for (const k of GIT_LOCAL_ENV) delete childEnv[k];
+  const opts = { cwd: vault, env: childEnv, encoding: "utf8", timeout: 15000, stdio: ["ignore", "pipe", "pipe"] };
+  const absent = (r) => r.error && r.error.code === "ENOENT";
+  const failed = (message) => ({ failed: message, remedy: `Run \`git init\` in ${vault}, or ${commandForm("doctor", { args: "--fix", env })}, which offers it.` });
+  const top = spawn("git", ["rev-parse", "--show-toplevel"], opts);
+  if (absent(top)) return { skipped: "git is not on PATH" };
+  const inside = top.status === 0 && top.stdout && top.stdout.trim() ? top.stdout.trim() : null;
+  const r = spawn("git", ["init", "--quiet"], opts);
+  if (absent(r)) return { skipped: "git is not on PATH" };
+  if (r.error) return failed(r.error.message);
+  if (r.status !== 0) return failed(String(r.stderr || "").trim() || `git init exited with ${r.status}`);
+  return inside && realOr(inside) !== realOr(vault) ? { done: true, inside } : { done: true };
+}
+
+const SCAFFOLD_REMEDY = "The binding is written; `projectstore scaffold --write` finishes the vault.";
+
+// Writes what the plan says, in the story's order: the vault directory when
+// init asked for it (not when it is there and empty), the config through
+// writeFileAtomic (its directory made first — the helper never mkdirs), then,
+// on init's whole-vault path, `git init` and the scaffold. Refuses to run a
+// plan with refusals; a "same" plan writes nothing unless it rebuilds a vault
+// that went missing. A git or scaffold step that fails is reported in `done`
+// and the next step still runs — the binding is already written, so a re-run
+// of `init` would only be refused, and the output names the one command that
+// finishes the vault instead. `spawn` is a parameter so tests can stand in
+// for git.
+export function applyBind(plan, { spawn = spawnSync, env = process.env } = {}) {
   if (!plan.ok) throw Object.assign(new Error(plan.refusals.map((r) => r.message).join("; ")), { code: plan.refusals[0].code });
-  const done = { created_vault: false, wrote_config: false };
+  const done = { created_vault: false, wrote_config: false, git: null, scaffold: null };
   if (plan.createsVault) { mkdirSync(plan.vault, { recursive: true }); done.created_vault = true; }
   if (plan.writes) {
     // Contract 5 names bind among the writers of the line-merged
@@ -138,28 +219,87 @@ export function applyBind(plan) {
     writeFileAtomic(plan.configPath, JSON.stringify(plan.after, null, 2) + "\n");
     done.wrote_config = true;
   }
+  if (plan.buildsVault) {
+    done.git = runGit(plan.vault, { spawn, env });
+    try { done.scaffold = applyScaffold(plan.scaffold); } catch (e) { done.scaffold = { failed: e && e.message ? e.message : String(e), remedy: SCAFFOLD_REMEDY }; }
+  }
   return done;
 }
 
 // The result a front-end reports: the decided values, never the file body.
+// `git` and `scaffold` are null unless `init` built the vault: git is
+// {done: true[, inside]}, {skipped: reason} or {failed: message, remedy};
+// scaffold is {created, exists} or {failed: message, remedy}.
 export function bindResult(plan, done) {
   return {
     state: plan.state, vault_path: plan.vault, vault_exists: Boolean(done && done.created_vault) || plan.vaultExists, layout: plan.layout, language: plan.language,
     config_path: plan.configPath, wrote: Boolean(done && done.wrote_config), created_vault: Boolean(done && done.created_vault),
     kept_keys: plan.keptKeys, ignored: plan.ignored, refusals: plan.refusals,
+    git: (done && done.git) || null, scaffold: (done && done.scaffold) || null,
   };
 }
 
-export function renderBindPlan(p, done = null) {
+// Whether a run left the vault unfinished: a failed git init or scaffold is
+// exit 1 with `ok: false`, though everything before it was written.
+export function bindFailed(done) {
+  return Boolean(done && ((done.git && done.git.failed) || (done.scaffold && done.scaffold.failed)));
+}
+
+// A line of prose, wrapped on a live terminal with a hanging indent of two
+// (presentation spec contract 5); `lead` is what the first line starts
+// with. A path or a command inside it is one word and never broken.
+const prose = (c, text, lead = "") => lead + wrap(text, c.live ? c.width : 0, lead + "  ");
+
+// The bind Next lines, one decision: the scaffold plan has a `create` row.
+// Both forms — the session's and the bin's — because the bind interview
+// relays this to a person who runs slash commands, and a git-marketplace
+// install has no bin on PATH: the terminal's form is the package this run was
+// invoked as, through npx (harness.mjs invokedAs — a shell's own name when it
+// came through one). `--write`: at a terminal that form shows the plan and
+// asks anyway. Each command stands on its own line, after a blank one
+// (presentation spec contract 6), so a copy takes exactly the command.
+function nextLines(p, env, c) {
+  const { cmd } = invokedAs(env);
+  return p.scaffold && p.scaffold.ok && p.scaffold.creates > 0
+    ? ["", prose(c, "Next: create the layout's missing folders and READMEs, in a session or from a terminal:"), ...commandBlock(c, [commandForm("scaffold", { env }), `${cmd} scaffold --write`])]
+    : ["", prose(c, "Next: see where the project stands:"), ...commandBlock(c, [`${cmd} status`])];
+}
+
+// One line per step that ran. The whole-vault path's own Next lines: the
+// derived views are reconcile's, offered rather than run.
+function vaultSteps(p, done, c, env) {
+  const lines = [];
+  const g = done.git;
+  if (g && g.done) lines.push(prose(c, `Initialised a git repository in ${p.vault} (no commit).`));
+  if (g && g.inside) lines.push(prose(c, `\`${p.vault}\` is inside the git work tree at \`${g.inside}\`; the vault gets its own repository, which that repository will see as an embedded one.`));
+  if (g && g.skipped) lines.push(prose(c, `Skipped git init: ${g.skipped}. The vault works without one; doctor's vault-git finding stays until it is a repository.`));
+  if (g && g.failed) lines.push(prose(c, `git init failed: ${g.failed}`), prose(c, g.remedy, "  "));
+  const s = done.scaffold;
+  if (s && s.failed) lines.push(prose(c, `Scaffold failed: ${s.failed}`), prose(c, s.remedy, "  "));
+  else if (s) lines.push(prose(c, `Scaffolded the ${p.layout} layout (${p.language}): ${s.created.length} folders and READMEs created${s.exists.length ? `, ${s.exists.length} already there` : ""}.`));
+  if (!bindFailed(done)) lines.push("", prose(c, `Next, optional: generate the derived views ${icon(c, "dash")} kanban.md, graph.md and code-map.md:`), ...commandBlock(c, [`${invokedAs(env).cmd} reconcile --write`]));
+  return lines;
+}
+
+// bind's and init's screen: what was written, the binding as key–value lines,
+// then what to run next (presentation spec contracts 5 and 6). Its prose
+// wraps on a live terminal. A refusal prints its message as it is. `caps` is
+// the stream's (term.mjs); the default is plain text.
+export function renderBindPlan(p, done = null, { env = process.env, caps: c = PLAIN } = {}) {
   const lines = [];
   if (!p.ok) { for (const r of p.refusals) lines.push(r.message); return lines.join("\n") + "\n"; }
-  if (p.state === "same") {
-    lines.push(`Already bound to ${p.vault}${p.ignored.length ? ` — --${p.ignored.join(" and --")} ignored: a change of ${p.ignored.join("/")} is not a rebind (edit the config, or rebind to another vault)` : ""}. Run ${commandForm("scaffold")} to (re)create the layout, or \`projectstore status\` to inspect it.`);
+  const ignoredNote = p.ignored.length ? ` ${icon(c, "dash")} --${p.ignored.join(" and --")} ignored: a change of ${p.ignored.join("/")} is not a rebind (edit the config, or rebind to another vault)` : "";
+  if (p.state === "same" && !(done && p.buildsVault)) {
+    lines.push(prose(c, `Already bound to ${p.vault}${ignoredNote}.`), ...nextLines(p, env, c));
     return lines.join("\n") + "\n";
   }
-  if (done && done.created_vault) lines.push(`Created ${p.vault}`);
-  lines.push(`Wrote ${p.configPath}${p.state === "different" ? ` (rebind from ${p.before.vault_path}; kept: ${p.keptKeys.join(", ") || "nothing else"})` : ""}`);
-  lines.push(`  vault_path: ${p.vault}`, `  layout:     ${p.layout}`, `  language:   ${p.language}`);
-  if (done) lines.push("", p.vaultExists && !done.created_vault ? `Next: \`projectstore status\`, or ${commandForm("scaffold")} if the vault has no layout folders yet.` : `Next: ${commandForm("scaffold")} in a session creates the layout's folders and READMEs.`);
+  if (done && done.created_vault) lines.push(prose(c, `Created ${p.vault}`));
+  if (p.state === "same") lines.push(prose(c, `Already bound to ${p.vault}${ignoredNote}; its directory was missing, so init made the vault again.`));
+  else {
+    lines.push(prose(c, `Wrote ${p.configPath}${p.state === "different" ? ` (rebind from ${p.before.vault_path}; kept: ${p.keptKeys.join(", ") || "nothing else"})` : ""}`));
+    lines.push(...kv(c, [["vault_path", p.vault], ["layout", p.layout], ["language", p.language]]));
+  }
+  if (done && p.buildsVault) lines.push(...vaultSteps(p, done, c, env));
+  else if (done) lines.push(...nextLines(p, env, c));
   return lines.join("\n") + "\n";
 }

package/node_modules/projectstore/scripts/build-adapters.mjs

@@ -6,7 +6,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { emittingHarnesses, sourceHarness, invocation, uiWordPatterns } from "./harness.mjs";
+import { emittingHarnesses, sourceHarness, invocation, uiWordPatterns, hasBand } from "./harness.mjs";
 import { writeFileAtomic } from "./lib.mjs";
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -128,17 +128,24 @@ hand.
 
 1. Resolve the requested vault path, and the layout and language when the
    request passes \`--layout <name>\` or \`--language <code>\`. If the vault
-   exists, use \`bind\`; if the user explicitly asks to create it, use
-   \`init\`. Ask for layout and language only when the request has not
+   exists and holds files, use \`bind\`. If it exists and is empty, use
+   \`init\`. If it is missing, use \`init\` when the user asks to create it.
+   \`init\` creates the whole vault: the directory (unless it is there and
+   empty), its git repository with no commit, and the layout's folders and
+   READMEs. Ask for layout and language only when the request has not
    supplied them.
 2. Show the resolved project, vault, verb, layout and language. Ask for explicit
    approval. Naming the vault is the core's non-interactive confirmation.
 3. Run \`node "\${PROJECTSTORE_CORE_ROOT}/bin/projectstore.mjs" <bind|init>
    "<vault-path>" --layout <layout> --language <language> --project "$PWD"
    --json\` and report the result. Use \`--rebind\` only when the user explicitly
-   approved replacing an existing binding.
-4. Run \`status --json\` to verify the stored path and policies. Offer
-   \`$projectstore-scaffold\` only for a newly initialized empty vault.
+   approved replacing an existing binding. If the result carries
+   \`git.failed\` or \`scaffold.failed\`, the binding is written; relay the
+   remedy and continue.
+4. Run \`status --json\` to verify the stored path and policies. After
+   \`bind\` (an \`init\` vault is already scaffolded), run \`scaffold --json
+   --project "$PWD"\` and offer \`$projectstore-scaffold\` only when a row
+   reads \`create\`.
 
 Codex plugin updates are performed with the \`projectstore-codex upgrade\`
 installer command; this skill never sends the user to another harness's plugin
@@ -159,6 +166,14 @@ running it; then run \`upgrade --harness codex --json\`, whose envelope is the
 result — \`--json\` never waits on a terminal's question. Unsupported
 surfaces remain unsupported; do not create host configuration by hand. Never
 claim a fix after a non-zero exit.`,
+  },
+  bar: {
+    description: "Explain ProjectStore band availability for Codex. This surface is unsupported and the skill never writes configuration. Arguments: on | off | status | epic [<ID>].",
+    body: `ProjectStore's band above the prompt is not supported by the Codex
+harness: Codex has no surface that draws above the prompt and no module
+runtime to draw it. Do not run the band verb's writes and do not edit project
+or host configuration. Report the surface as unsupported. For project state
+use \`$projectstore-status\`.`,
   },
   statusline: {
     description: "Explain ProjectStore status-line availability for Codex. This surface is unsupported and the skill never writes configuration. Arguments: on | off | status.",
@@ -209,8 +224,12 @@ function renderRole(file) {
   return [join("skills", name, "SKILL.md"), skill(name, description, orchestration + body)];
 }
 
-function renderHooks(manifest, root = ROOT) {
+export function renderHooks(manifest, root = ROOT) {
   const source = json(join(root, "hooks", "hooks.json"));
+  // The band is a hooks module only a harness with a band runs (the band
+  // spec, contract 1): elsewhere `modules` would name a file that harness
+  // cannot load, so its tree carries the classic hooks alone.
+  if (!hasBand(manifest)) delete source.modules;
   const post = source.hooks?.PostToolUse || [];
   for (const group of post) if (group.matcher) group.matcher = (manifest.tools?.write_tools || []).join("|");
   const rewrite = (value) => {