heyspex 0.1.0 → 0.2.0

package/scripts/lib/hs-source-push.mjs

@@ -16,16 +16,26 @@
  *
  * Force-push and protected-ref refusal DEFERS to the existing destructive-git
  * guardrail (`classifyGitDestructive` in
- * scripts/claude-hooks/git-stash-gate.mjs) and the protected-ref list already
- * used by scripts/hs-night-branch.mjs — this module does not ship a second,
- * competing allowlist.
+ * spexharness/src/gates/git-stash-gate.decide.mjs — relocated out of
+ * scripts/claude-hooks/git-stash-gate.mjs by HS-IQBF; that hook script is now
+ * a generated shell over the spexharness/src/gates/git-stash-gate.mjs port)
+ * and the protected-ref list already used by scripts/hs-night-branch.mjs —
+ * this module does not ship a second, competing allowlist.
+ *
+ * Both of those modules (plus git-stash-gate.decide.mjs's own hook-chain
+ * dependencies) are dev-only — never in the package's `files`
+ * (RUNTIME_FILES / `package.json`) — so a static import of either one crashed
+ * EVERY `hs source push` invocation with a raw `ERR_MODULE_NOT_FOUND` on a
+ * published npm install. They are loaded via a guarded dynamic import instead
+ * (see `loadDestructiveGitGuard` below); `pushBranch` needs them on every
+ * call (the force-push/protected-ref check is not behind an opt-in flag), so
+ * a resolution failure refuses the ENTIRE push — zero `git push` subprocess
+ * calls — with a clear message, never a stack trace.
  */
 import { spawn, execFileSync } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { PROTECTED_REFS } from '../hs-night-branch.mjs';
-import { classifyGitDestructive } from '../claude-hooks/git-stash-gate.mjs';
 import { scanPaths } from './hs-source-secret-scan.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -33,6 +43,41 @@ export const REPO_ROOT = path.resolve(__dirname, '..', '..');
 
 export const DEFAULT_TIMEOUT_MS = 60_000;
 
+export const DESTRUCTIVE_GIT_GUARD_UNAVAILABLE_MESSAGE =
+  'hs source push: refusing — the destructive-git safety check ' +
+  '(scripts/hs-night-branch.mjs, scripts/claude-hooks/git-stash-gate.mjs) is not available on ' +
+  'this install. Those modules ship only inside a full source checkout of the HeySpex repo, not ' +
+  'a published npm install, and `hs source push` requires them to classify force-push / ' +
+  'protected-ref requests before it ever touches git — so it refuses rather than pushing ' +
+  'without that check.';
+
+let destructiveGitGuardPromise;
+
+/**
+ * Guarded, on-demand, cached load of the two dev-only modules `pushBranch`
+ * depends on for every call. Never throws — a resolution failure (module
+ * absent, as on a published install) comes back as `{ ok: false }` so the
+ * caller can refuse gracefully instead of letting `ERR_MODULE_NOT_FOUND`
+ * propagate as an unhandled rejection / stack trace.
+ * @returns {Promise<{ ok: true, PROTECTED_REFS: string[], classifyGitDestructive: Function } | { ok: false, error: unknown }>}
+ */
+export function loadDestructiveGitGuard() {
+  if (!destructiveGitGuardPromise) {
+    destructiveGitGuardPromise = Promise.all([
+      import('../hs-night-branch.mjs'),
+      import('../../spexharness/src/gates/git-stash-gate.decide.mjs'),
+    ]).then(
+      ([nightBranch, stashGate]) => ({
+        ok: true,
+        PROTECTED_REFS: nightBranch.PROTECTED_REFS,
+        classifyGitDestructive: stashGate.classifyGitDestructive,
+      }),
+      (error) => ({ ok: false, error }),
+    );
+  }
+  return destructiveGitGuardPromise;
+}
+
 /**
  * Pushes `branch` to `remote` through the credential-hang-safe invocation,
  * refusing outright (zero subprocess calls) on a force-push flag or a
@@ -50,7 +95,7 @@ export const DEFAULT_TIMEOUT_MS = 60_000;
  * }} opts
  * @returns {Promise<{ ok: boolean, code: string, message?: string }>}
  */
-export function pushBranch({
+export async function pushBranch({
   remote = 'origin',
   branch,
   extraArgs = [],
@@ -59,64 +104,68 @@ export function pushBranch({
   spawnFn = spawn,
   preScan = null,
 } = {}) {
-  return new Promise((resolve) => {
-    if (!branch || typeof branch !== 'string' || branch.trim() === '') {
-      resolve({
-        ok: false,
-        code: 'NO_BRANCH',
-        message: 'hs source push: a branch name is required (e.g. `hs source push origin my-branch`).',
-      });
-      return;
-    }
+  if (!branch || typeof branch !== 'string' || branch.trim() === '') {
+    return {
+      ok: false,
+      code: 'NO_BRANCH',
+      message: 'hs source push: a branch name is required (e.g. `hs source push origin my-branch`).',
+    };
+  }
 
-    // ---- protected-ref refusal — reuses hs-night-branch.mjs's own list ----
-    if (PROTECTED_REFS.includes(branch)) {
-      resolve({
-        ok: false,
-        code: 'PROTECTED_REF',
-        message: `hs source push: refusing to push to protected ref \`${branch}\` (${PROTECTED_REFS.join(', ')}). This is never allowed through hs source push.`,
-      });
-      return;
-    }
+  // ---- destructive-git guard load — every push needs it, not just an
+  // opt-in flag, so a resolution failure (module absent, as on a published
+  // install) refuses the entire push before any git subprocess is spawned ----
+  const guard = await loadDestructiveGitGuard();
+  if (!guard.ok) {
+    return { ok: false, code: 'PACKAGE_INCOMPLETE', message: DESTRUCTIVE_GIT_GUARD_UNAVAILABLE_MESSAGE };
+  }
+  const { PROTECTED_REFS, classifyGitDestructive } = guard;
 
-    // ---- force-push refusal — defers to the destructive-git guardrail's
-    // own classifier rather than a second, competing allowlist ----
-    const syntheticCommand = ['git', 'push', ...extraArgs, remote, branch].join(' ');
-    if (classifyGitDestructive('Bash', { command: syntheticCommand }) === 'gated') {
-      resolve({
+  // ---- protected-ref refusal — reuses hs-night-branch.mjs's own list ----
+  if (PROTECTED_REFS.includes(branch)) {
+    return {
+      ok: false,
+      code: 'PROTECTED_REF',
+      message: `hs source push: refusing to push to protected ref \`${branch}\` (${PROTECTED_REFS.join(', ')}). This is never allowed through hs source push.`,
+    };
+  }
+
+  // ---- force-push refusal — defers to the destructive-git guardrail's
+  // own classifier rather than a second, competing allowlist ----
+  const syntheticCommand = ['git', 'push', ...extraArgs, remote, branch].join(' ');
+  if (classifyGitDestructive('Bash', { command: syntheticCommand }) === 'gated') {
+    return {
+      ok: false,
+      code: 'FORCE_REFUSED',
+      message:
+        'hs source push: refusing — this invocation is classified as a gated destructive git action (force-push or similar) by the existing destructive-git guardrail. Force-push is never allowed through hs source push; use the guardrail\'s own owner-authorized path if this is truly intended.',
+    };
+  }
+
+  // ---- secret-scan extension point (implemented by sibling task
+  // HS-5NXX-CWPX; inert here — a caller that passes no preScan gets no
+  // scanning, exactly today's behavior) ----
+  if (typeof preScan === 'function') {
+    let scanResult;
+    try {
+      scanResult = preScan({ remote, branch, cwd });
+    } catch (err) {
+      return {
         ok: false,
-        code: 'FORCE_REFUSED',
-        message:
-          'hs source push: refusing — this invocation is classified as a gated destructive git action (force-push or similar) by the existing destructive-git guardrail. Force-push is never allowed through hs source push; use the guardrail\'s own owner-authorized path if this is truly intended.',
-      });
-      return;
+        code: 'PRESCAN_ERROR',
+        message: `hs source push: the preScan hook threw — ${err instanceof Error ? err.message : String(err)}`,
+      };
     }
-
-    // ---- secret-scan extension point (implemented by sibling task
-    // HS-5NXX-CWPX; inert here — a caller that passes no preScan gets no
-    // scanning, exactly today's behavior) ----
-    if (typeof preScan === 'function') {
-      let scanResult;
-      try {
-        scanResult = preScan({ remote, branch, cwd });
-      } catch (err) {
-        resolve({
-          ok: false,
-          code: 'PRESCAN_ERROR',
-          message: `hs source push: the preScan hook threw — ${err instanceof Error ? err.message : String(err)}`,
-        });
-        return;
-      }
-      if (scanResult && scanResult.ok === false) {
-        resolve({
-          ok: false,
-          code: 'PRESCAN_BLOCKED',
-          message: scanResult.message || 'hs source push: blocked by preScan (likely secret detected).',
-        });
-        return;
-      }
+    if (scanResult && scanResult.ok === false) {
+      return {
+        ok: false,
+        code: 'PRESCAN_BLOCKED',
+        message: scanResult.message || 'hs source push: blocked by preScan (likely secret detected).',
+      };
     }
+  }
 
+  return new Promise((resolve) => {
     // ---- the actual push: credential-helper override + GIT_TERMINAL_PROMPT=0,
     // both together, unconditionally, per the recorded lesson ----
     const argv = [

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;
+}