heyspex 0.1.0 → 0.2.1

package/scripts/lib/hs-worktree-args.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// scripts/lib/hs-worktree-args.mjs — pure argv parser for `hs worktree <verb>`.
+// Task: HS-V9XH (epic HS-03DO "Claim-bound worktree isolation for parallel agent
+// sessions") — the CLI face over dev-factory/lib/worktree-allocator.mjs.
+//
+// Deliberately NOT a wrapper around the allocator's own exported `parseCliArgs`:
+// that parser (a) never validates a verb's REQUIRED flags (alloc/release/rebind
+// with a missing --spec/--to parses clean there — the caller in its own CLI mode
+// checks that per-branch, after parsing), (b) has no `--expect-removed` flag (a
+// hs-worktree-only concept — the allocator's `reap` has no notion of "did the
+// caller expect something to be removed"), and (c) accepts every value flag
+// (--pid, --repo, --session, --agent, ...) for every verb rather than scoping
+// them to the verbs that use them. This module needs both, so it is its own
+// small parser rather than a wrap-then-patch of the core's.
+//
+// → parseWorktreeArgs(argv) => { ok: true, verb, flags }
+//                             | { ok: false, code, message }
+//
+// Exit-code contract (mirrors dev-factory/lib/worktree-allocator.mjs's CLI):
+//   1  (EXIT_USAGE)    unknown verb, unknown flag for that verb
+//   11 (EXIT_BAD_ARG)  a required flag is missing, or a value-flag has no value
+
+export const EXIT_USAGE = 1;
+export const EXIT_BAD_ARG = 11;
+
+const VERBS = new Set(["list", "alloc", "release", "reap", "rebind"]);
+
+// Value-taking flags common to every verb, plus per-verb value flags.
+const COMMON_VALUE_FLAGS = new Set(["--root"]);
+const VERB_VALUE_FLAGS = {
+  list: new Set(),
+  alloc: new Set(["--spec", "--session", "--agent"]),
+  release: new Set(["--spec"]),
+  reap: new Set(),
+  rebind: new Set(["--spec", "--to"]),
+};
+
+// Boolean flags common to every verb, plus per-verb boolean flags.
+const COMMON_BOOL_FLAGS = new Set(["--json", "--dry-run"]);
+const VERB_BOOL_FLAGS = {
+  list: new Set(),
+  alloc: new Set(),
+  release: new Set(),
+  reap: new Set(["--include-foreign", "--yes", "--expect-removed"]),
+  rebind: new Set(),
+};
+
+const REQUIRED_FLAGS = {
+  alloc: ["spec"],
+  release: ["spec"],
+  rebind: ["spec", "to"],
+};
+
+const usageFail = (message) => ({ ok: false, code: EXIT_USAGE, message });
+const badArgFail = (message) => ({ ok: false, code: EXIT_BAD_ARG, message });
+
+/**
+ * Parse `hs worktree <verb> [flags]`.
+ *
+ * `list | alloc --spec <id> [--session <id>] [--agent <name>] | release --spec <id>
+ *  | reap [--include-foreign] [--yes] [--expect-removed] | rebind --spec <id> --to <id>`
+ * plus the common `--json`, `--dry-run`, `--root <dir>`.
+ */
+export function parseWorktreeArgs(argv) {
+  const args = Array.isArray(argv) ? argv.map(String) : [];
+  if (args.length === 0) return usageFail("missing verb (expected list|alloc|release|reap|rebind)");
+
+  const verb = args[0];
+  if (!VERBS.has(verb)) return usageFail(`unknown verb "${verb}" (expected list|alloc|release|reap|rebind)`);
+
+  const boolFlags = VERB_BOOL_FLAGS[verb];
+  const valueFlags = VERB_VALUE_FLAGS[verb];
+
+  const flags = {
+    json: false,
+    dryRun: false,
+    root: null,
+  };
+  if (verb === "reap") { flags.includeForeign = false; flags.yes = false; flags.expectRemoved = false; }
+
+  for (let i = 1; i < args.length; i++) {
+    const a = args[i];
+    if (!a.startsWith("--")) return usageFail(`unexpected argument "${a}" for worktree ${verb}`);
+
+    if (COMMON_BOOL_FLAGS.has(a)) {
+      if (a === "--json") flags.json = true;
+      else flags.dryRun = true;
+      continue;
+    }
+    if (boolFlags.has(a)) {
+      if (a === "--include-foreign") flags.includeForeign = true;
+      else if (a === "--yes") flags.yes = true;
+      else if (a === "--expect-removed") flags.expectRemoved = true;
+      continue;
+    }
+    if (COMMON_VALUE_FLAGS.has(a) || valueFlags.has(a)) {
+      const v = args[i + 1];
+      if (v === undefined) return badArgFail(`${a} requires a value`);
+      i += 1;
+      if (a === "--root") flags.root = v;
+      else if (a === "--spec") flags.spec = v;
+      else if (a === "--to") flags.to = v;
+      else if (a === "--session") flags.session = v;
+      else if (a === "--agent") flags.agent = v;
+      continue;
+    }
+    return usageFail(`unknown flag "${a}" for worktree ${verb}`);
+  }
+
+  for (const key of REQUIRED_FLAGS[verb] ?? []) {
+    if (!flags[key]) return badArgFail(`worktree ${verb} requires --${key === "to" ? "to" : key}`);
+  }
+
+  return { ok: true, verb, flags };
+}

package/scripts/lib/shared-path-helpers.mjs

@@ -0,0 +1,134 @@
+/**
+ * The two path helpers this repo had written by hand twenty-five times
+ * ([[HS-ZA6P-PFMN-TASK-block-a-vault-owned-state-file-from]]).
+ *
+ * Thirteen places answered "where is the code repo" in seven different ways,
+ * and twelve places checked "does this path stay inside its root" with twelve
+ * different names and one identical body. Sixteen of the twenty-five were
+ * written on a single night — by the sessions fixing the bug that duplication
+ * causes ([[HS-AI1T-UGC9-DIAG-nothing-in-the-mcp-server-checks-a]],
+ * [[HS-MMR6-DS0Q-DIAG-the-plan-review-creates-folders-outside]]). Per-site
+ * acceptance criteria cannot see duplication; `scripts/check-shared-helpers.mjs`
+ * is the gate that can.
+ *
+ * Behavior is deliberately unchanged from the copies this replaces — the
+ * thrown messages are byte-identical apart from the caller's own label, so a
+ * test asserting a refusal message keeps passing and a caller catching the
+ * throw keeps catching it.
+ *
+ * Published surface: listed in `package.json`'s `files` (verified by
+ * `scripts/verify-mcp-package.mjs`) because it is in the static import closure
+ * of `vendor/heyspex-mcp/cli.mjs`.
+ */
+import { isAbsolute, resolve, sep } from "node:path";
+
+/**
+ * Refuse to build a path under `root` when the root itself is not absolute, or
+ * when the resolved path would land outside it.
+ *
+ * This is the [[HS-MMR6]] failure: a root that lost its backslashes
+ * (`C:\dev-projects\heyspex-specs` → `C:dev-projectsheyspex-specs`) is
+ * *drive-relative* on Windows, not absolute, and `mkdirSync(..., { recursive:
+ * true })` resolves it against `process.cwd()` and builds a real directory
+ * tree in the wrong repo, returning success. Call this before any
+ * `mkdirSync`/`writeFileSync` so a refusal creates nothing on disk.
+ *
+ * It always THROWS. That is not a policy choice made here — every one of the
+ * twelve copies threw, and each call site routes the throw into a failure path
+ * that already existed in that function (throw onward where the write is the
+ * primary action, `return false` where it is a tidy-up step after the real
+ * work already succeeded, wrap into the module's own error shape where a
+ * caller reads the return). Those per-site decisions live at the call sites
+ * and are untouched by sharing the body.
+ *
+ * @param {string} root       The root everything must stay under (absolute).
+ * @param {string} candidate  The path about to be written.
+ * @param {string} label      Caller prefix, e.g. "capture-focus write" — it is
+ *                            interpolated as `<label> refused: …`.
+ * @throws {Error} naming the root, the resolved path, and the reason refused.
+ */
+export function assertPathUnderRoot(root, candidate, label) {
+  if (typeof root !== "string" || !root.trim() || !isAbsolute(root)) {
+    throw new Error(
+      `${label} refused: vaultRoot "${root}" is not an absolute path — ` +
+        "refusing rather than silently creating directories wherever a relative or " +
+        "drive-relative path resolves against the current working directory.",
+    );
+  }
+  const normalizedRoot = resolve(root);
+  const normalizedPath = resolve(candidate);
+  if (normalizedPath === normalizedRoot || normalizedPath.startsWith(normalizedRoot + sep)) {
+    return;
+  }
+  throw new Error(
+    `${label} refused: resolved to "${normalizedPath}" but vaultRoot requires ` +
+      `everything under "${normalizedRoot}" — refusing rather than silently writing to the wrong location.`,
+  );
+}
+
+/**
+ * Where is the code repo? One precedence order, everywhere:
+ *
+ *   1. `explicit` — a caller that already knows (tests, a dispatcher).
+ *   2. `HS_PKG_ROOT` — the operator override.
+ *   3. `packageRoot` — derived from the calling module's own location.
+ *   4. `vaultRoot` — ONLY when no `packageRoot` was supplied.
+ *
+ * Step 4 is the single-checkout case and it is not a mistake: before the
+ * repo split, the vault and the code lived in one folder, and two callers
+ * (`spex-console/bin/hs-check.ts`, `spex-console/bin/hs-revalidate.ts`) still
+ * rely on that. It does mean the same call reads "the code" in one setup and
+ * "the vault" in another — which nothing at those call sites used to say out
+ * loud. {@link resolveCodeAndVaultRoots} is how you say it: it returns the
+ * vault root ALONGSIDE the code root rather than instead of it, so a caller
+ * that wants both checkouts searched gets both, labeled.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.explicit]    Caller-supplied override, highest precedence.
+ * @param {string} [opts.packageRoot] Root derived from the calling module's location.
+ * @param {string} [opts.vaultRoot]   Single-checkout fallback; used only without packageRoot.
+ * @param {NodeJS.ProcessEnv} [opts.env] Injectable for tests.
+ * @returns {string} The resolved code root, or "" when nothing resolved.
+ */
+export function resolveCodeRoot({
+  explicit,
+  packageRoot,
+  vaultRoot,
+  env = process.env,
+} = {}) {
+  const fromExplicit = typeof explicit === "string" ? explicit.trim() : "";
+  if (fromExplicit) return fromExplicit;
+  const fromEnv = typeof env?.HS_PKG_ROOT === "string" ? env.HS_PKG_ROOT.trim() : "";
+  if (fromEnv) return fromEnv;
+  const fromPackage = typeof packageRoot === "string" ? packageRoot.trim() : "";
+  if (fromPackage) return fromPackage;
+  const fromVault = typeof vaultRoot === "string" ? vaultRoot.trim() : "";
+  return fromVault;
+}
+
+/**
+ * The code root and the vault root as a labeled, deduped list — the shape
+ * `resolveCodeAuditRoots` in `plan-review.mjs` settled on, lifted here so every
+ * caller that searches "the checkout" can search both without re-deciding what
+ * that means.
+ *
+ * The vault entry is omitted when the two resolve to the same directory (the
+ * single-checkout case), so a caller never searches the same folder twice and
+ * never reports one finding as two.
+ *
+ * @param {object} opts
+ * @param {string} opts.vaultRoot
+ * @param {string} [opts.explicit]
+ * @param {string} [opts.packageRoot]
+ * @param {NodeJS.ProcessEnv} [opts.env]
+ * @returns {{ label: string, root: string }[]}
+ */
+export function resolveCodeAndVaultRoots({ vaultRoot, explicit, packageRoot, env } = {}) {
+  const codeRoot = resolveCodeRoot({ explicit, packageRoot, vaultRoot, env });
+  const roots = [{ label: "code root", root: codeRoot }];
+  const vault = typeof vaultRoot === "string" ? vaultRoot : "";
+  if (vault && (!codeRoot || resolve(vault) !== resolve(codeRoot))) {
+    roots.push({ label: "vault root", root: vault });
+  }
+  return roots;
+}