heyspex 0.1.0

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

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+/**
+ * hs-source-commit.mjs — `hs source commit`: path-based staging wrapper
+ * around the existing owner-directed commit gate
+ * (HS-EZNJ-CWPX, epic [[HS-Q0K8-CWPX-EPIC-spexsource-local-git-preflight-commit]]).
+ *
+ * This module NEVER runs `git add -A` / `git add -u` and NEVER runs a bare
+ * `git commit` — it stages exactly the paths named in the most recent
+ * `hs source preflight` stage plan (one `git add <path>` per path) and then
+ * shells out to the existing owner-directed commit path
+ * (`scripts/owner-commit.mjs`, i.e. `npm run commit:owner`) so
+ * `guard-agent-commit` and the pre-commit hooks still run unmodified. See
+ * the colocated test for the enforcement proof.
+ */
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  getTreeStatus,
+  readStagePlanFile,
+  computeDirtyFingerprint,
+  REPO_ROOT,
+} from './hs-source-preflight.mjs';
+import { createSessionBranch } from './session-branch.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const OWNER_COMMIT_SCRIPT = path.join(REPO_ROOT, 'scripts', 'owner-commit.mjs');
+
+/**
+ * Default subprocess runner — injectable so tests can spy without ever
+ * mutating real git state. Never throws; callers check `.status`.
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {object} [opts]
+ * @returns {{ status: number, error?: Error }}
+ */
+export function defaultRun(cmd, args, opts = {}) {
+  const result = spawnSync(cmd, args, { stdio: 'inherit', ...opts });
+  if (result.error) return { status: 1, error: result.error };
+  return { status: result.status ?? 1 };
+}
+
+/**
+ * Stages exactly the paths in `plan.included` (path-based `git add <path>`,
+ * one invocation per path — never `-A`/`-u`), then commits via the existing
+ * owner-directed gate. Refuses (no staging calls at all) when no plan is on
+ * disk or it has drifted from the current working tree.
+ *
+ * @param {{
+ *   message: string,
+ *   cwd?: string,
+ *   run?: typeof defaultRun,
+ *   getStatus?: typeof getTreeStatus,
+ *   readPlan?: typeof readStagePlanFile,
+ * }} opts
+ * @returns {{ ok: boolean, code?: string, message?: string, staged?: string[] }}
+ */
+export function commitFromPlan({
+  message,
+  cwd = process.cwd(),
+  run = defaultRun,
+  getStatus = getTreeStatus,
+  readPlan = readStagePlanFile,
+} = {}) {
+  if (!message || typeof message !== 'string' || message.trim() === '') {
+    return {
+      ok: false,
+      code: 'NO_MESSAGE',
+      message:
+        'hs source commit: a commit message is required (e.g. `hs source commit -m "feat: …"`).',
+    };
+  }
+
+  const plan = readPlan({ cwd });
+  if (!plan) {
+    return {
+      ok: false,
+      code: 'NO_PLAN',
+      message:
+        'hs source commit: no stage plan found. Run `hs source preflight` first — it produces the plan this command consumes.',
+    };
+  }
+
+  const currentStatus = getStatus({ cwd, run });
+  const currentFingerprint = computeDirtyFingerprint(currentStatus.dirty);
+  if (currentFingerprint !== plan.dirtyFingerprint) {
+    return {
+      ok: false,
+      code: 'STALE_PLAN',
+      message:
+        'hs source commit: the working tree has changed since the last `hs source preflight` — the stage plan is stale. Re-run `hs source preflight` and try again.',
+    };
+  }
+
+  if (!Array.isArray(plan.included) || plan.included.length === 0) {
+    return {
+      ok: false,
+      code: 'EMPTY_PLAN',
+      message:
+        'hs source commit: the stage plan has nothing to stage (empty or fully denylisted). Nothing to commit.',
+    };
+  }
+
+  if (plan.ok === false) {
+    return {
+      ok: false,
+      code: 'PREFLIGHT_FAILED',
+      message:
+        'hs source commit: the last `hs source preflight` reported a failing lint/format check or a secret-scan finding. Fix it and re-run preflight before committing.',
+    };
+  }
+
+  const staged = [];
+  for (const p of plan.included) {
+    const result = run('git', ['add', p], { cwd });
+    if (result.status !== 0) {
+      return {
+        ok: false,
+        code: 'STAGE_FAILED',
+        message: `hs source commit: \`git add ${p}\` failed — aborting before any commit was attempted.`,
+        staged,
+      };
+    }
+    staged.push(p);
+  }
+
+  const commitResult = run(process.execPath, [OWNER_COMMIT_SCRIPT, '-m', message], { cwd });
+  if (commitResult.status !== 0) {
+    return {
+      ok: false,
+      code: 'COMMIT_FAILED',
+      message: 'hs source commit: the owner-directed commit gate (owner-commit.mjs) failed — see its output above.',
+      staged,
+    };
+  }
+
+  return { ok: true, staged };
+}
+
+/**
+ * CLI entry for `hs source commit`. Parses `-m/--message <msg>` and an
+ * optional `--session <id>` from argv.
+ *
+ * When `--session <id>` is given, the session's branch is created/selected
+ * via `scripts/lib/session-branch.mjs` (HS-Z7VJ) BEFORE any staging or
+ * committing happens — session-branch.mjs is the only thing that ever runs
+ * `git checkout`/`git checkout -b`/`git config` on that path; this function
+ * never spawns git itself. Omitting `--session` leaves the existing
+ * no-flag path completely unchanged: `createSessionBranch` is never called,
+ * so there is no branch-creation/selection side effect at all (AC2).
+ *
+ * @param {string[]} argv (verb-stripped: just the flags/args after `commit`)
+ * @param {{
+ *   cwd?: string,
+ *   run?: (cmd: string, args: string[], opts?: object) => { status: number, stdout?: string, stderr?: string },
+ *   createSessionBranchFn?: typeof createSessionBranch,
+ * }} [opts]
+ * @returns {number} process exit code
+ */
+export function runCommitCommand(argv, { cwd = process.cwd(), run, createSessionBranchFn = createSessionBranch } = {}) {
+  let message = '';
+  let sessionId;
+  for (let i = 0; i < argv.length; i++) {
+    if ((argv[i] === '-m' || argv[i] === '--message') && argv[i + 1] !== undefined) {
+      message = argv[i + 1];
+      i++;
+    } else if (argv[i] === '--session' && argv[i + 1] !== undefined) {
+      sessionId = argv[i + 1];
+      i++;
+    }
+  }
+
+  if (sessionId !== undefined) {
+    const branchResult = createSessionBranchFn({ sessionId, cwd, run });
+    if (!branchResult.ok) {
+      console.error(branchResult.message);
+      return 1;
+    }
+    console.log(
+      `hs source commit: ${branchResult.reused ? 'reusing' : 'created'} session branch ${branchResult.branch}.`,
+    );
+  }
+
+  const result = commitFromPlan({ message, cwd, run });
+  if (!result.ok) {
+    console.error(result.message);
+    return 1;
+  }
+  console.log(`hs source commit: committed ${result.staged.length} path(s).`);
+  return 0;
+}
+
+// ---- direct-invocation entry --------------------------------------------
+
+function invokedDirectly() {
+  try {
+    return path.resolve(fileURLToPath(import.meta.url)) === path.resolve(process.argv[1] ?? '');
+  } catch {
+    return false;
+  }
+}
+
+if (invokedDirectly()) {
+  // argv: [node, script, "commit", ...flags] — drop the leading verb token.
+  process.exit(runCommitCommand(process.argv.slice(3)));
+}

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

@@ -0,0 +1,366 @@
+#!/usr/bin/env node
+/**
+ * hs-source-log.mjs — `hs source log <spec-id>`: commit-history retrieval
+ * for diagnosis (HS-I6AB, epic
+ * [[HS-VKD5-6JBX-EPIC-commit-history-retrieval-for-diagnosis]]).
+ *
+ * Reads the console's `GET /api/specs/:id/settlement` route
+ * (`spex-console/src/app/api/specs/[id]/settlement/route.ts`) to print the
+ * most recent commit-settlement row for a spec — repo, branch, commit sha,
+ * and when it settled — so diagnosis/triage can look up a spec's commit
+ * history from the console-known side, without a local git checkout
+ * (mirrors why `spec-settlement-info.tsx` exists in the console itself:
+ * under ADR-0022/ADR-0023 a browser-only cloud user has none).
+ *
+ * The console lookup is an injectable HTTP client (`fetchImpl`), never a
+ * hardcoded `fetch` call — tests inject a fake console and never touch the
+ * network. Console URL resolution reuses the ONE shared resolver
+ * (`console-url-resolver.mjs`) rather than a hand-rolled localhost guess.
+ *
+ * HS-CZ84 extends this module with `lookupCommitHistory` — a local
+ * `git -C <vaultRoot> log --grep <spec-id>` fallback (through the same
+ * injected-runner pattern `hs-source-commit.mjs`'s `defaultRun` uses) for
+ * when the console lookup finds nothing, so commit-history lookup still
+ * works with no console reachable. Provenance (`console` vs
+ * `local-git-log`) is always explicit on the result — see
+ * {@link formatSettlementResult}.
+ */
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { resolveConsoleUrl } from './console-url-resolver.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// ---- Bearer-header idiom -------------------------------------------------
+// Mirrors `readPairedToken`/`bearerHeaderFor` in
+// `spex-console/src/lib/cli/control-shared.ts` byte-for-byte in behavior:
+// same paired `hsmcp_`/`hscmp_` token read from `~/.heyspex/credentials.yaml`,
+// same loopback-skip rule (a local dev console never needed auth; a genuinely
+// remote/paired console does — [[HS-PH7O-ILNC-DIAG-hs-check-report-cannot-authenticate]]).
+// Duplicated here in plain Node ESM rather than imported from that TS module
+// because `scripts/lib/*.mjs` runs standalone (bare `node`, no Next.js build
+// step) — the same reasoning `console-url-resolver.mjs`'s own module doc
+// gives for staying dependency-free.
+
+/**
+ * Raw paired Bearer token from `~/.heyspex/credentials.yaml`, or `undefined`
+ * if absent/unreadable.
+ * @returns {string | undefined}
+ */
+export function readPairedToken() {
+  try {
+    const raw = readFileSync(join(homedir(), '.heyspex', 'credentials.yaml'), 'utf-8');
+    const match = raw.match(/\b(hsmcp_[A-Za-z0-9_-]+|hscmp_[A-Za-z0-9_-]+)\b/);
+    return match?.[1];
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Bearer header for a non-loopback console; `{}` for loopback targets or
+ * when no token is paired.
+ * @param {string} consoleUrl
+ * @returns {Record<string, string>}
+ */
+export function bearerHeaderFor(consoleUrl) {
+  try {
+    const host = new URL(consoleUrl).hostname;
+    if (host === 'localhost' || host === '127.0.0.1' || host === '0.0.0.0' || host === '::1') {
+      return {};
+    }
+    const token = readPairedToken();
+    return token ? { authorization: `Bearer ${token}` } : {};
+  } catch {
+    return {};
+  }
+}
+
+// ---- console settlement lookup ------------------------------------------
+
+/**
+ * The minimal HTTP-client surface this module needs — an injectable stand-in
+ * for `fetch`. Production uses the real global `fetch`; tests inject a fake
+ * console that never touches the network.
+ * @typedef {(url: string, init?: object) => Promise<{
+ *   ok: boolean,
+ *   status: number,
+ *   json: () => Promise<any>,
+ * }>} HttpClient
+ */
+
+/**
+ * One settlement row, shaped exactly like `SettlementRow` in
+ * `spex-console/src/lib/git-export/settlement-store.ts` — never reimplemented
+ * ad hoc.
+ * @typedef {{
+ *   found: true,
+ *   provenance: 'console',
+ *   repo: string,
+ *   branch: string,
+ *   commitSha: string,
+ *   settledAt: string,
+ * }} ConsoleSettlementFound
+ * @typedef {{
+ *   found: false,
+ *   provenance: 'console',
+ *   reason: string,
+ * }} ConsoleSettlementNotFound
+ * @typedef {ConsoleSettlementFound | ConsoleSettlementNotFound} ConsoleSettlementResult
+ */
+
+/**
+ * Look up the most recent settlement row for `specId` via the console's
+ * `GET /api/specs/:id/settlement` route. NEVER throws: a network error, a
+ * non-OK HTTP status, an unparsable body, or a `{ settled: false }` response
+ * all resolve to a typed `{ found: false, reason }` result rather than
+ * rejecting or crashing the caller.
+ *
+ * @param {{
+ *   specId: string,
+ *   consoleUrl?: string,
+ *   fetchImpl?: HttpClient,
+ *   repoRoot?: string,
+ * }} opts
+ * @returns {Promise<ConsoleSettlementResult>}
+ */
+export async function lookupConsoleSettlement({
+  specId,
+  consoleUrl,
+  fetchImpl = fetch,
+  repoRoot,
+} = {}) {
+  const resolvedUrl = consoleUrl ?? resolveConsoleUrl({ repoRoot });
+  const url = `${resolvedUrl}/api/specs/${encodeURIComponent(specId)}/settlement`;
+
+  let res;
+  try {
+    res = await fetchImpl(url, { headers: { ...bearerHeaderFor(resolvedUrl) } });
+  } catch (err) {
+    return {
+      found: false,
+      provenance: 'console',
+      reason: `no console reachable at ${resolvedUrl} (${err instanceof Error ? err.message : String(err)})`,
+    };
+  }
+
+  if (!res || !res.ok) {
+    return {
+      found: false,
+      provenance: 'console',
+      reason: `console returned ${res ? res.status : 'no response'} for ${url}`,
+    };
+  }
+
+  let body;
+  try {
+    body = await res.json();
+  } catch (err) {
+    return {
+      found: false,
+      provenance: 'console',
+      reason: `console response was not valid JSON (${err instanceof Error ? err.message : String(err)})`,
+    };
+  }
+
+  if (!body || body.settled !== true) {
+    return {
+      found: false,
+      provenance: 'console',
+      reason:
+        body && typeof body.reason === 'string'
+          ? `no settlement found (${body.reason})`
+          : 'no settlement found for this spec',
+    };
+  }
+
+  return {
+    found: true,
+    provenance: 'console',
+    repo: body.repo,
+    branch: body.branch,
+    commitSha: body.commit_sha,
+    settledAt: body.settled_at,
+  };
+}
+
+// ---- local git-log fallback (HS-CZ84) ------------------------------------
+
+/**
+ * Default git-log runner — injectable so tests never touch a real repo,
+ * exactly like `defaultRun` in `hs-source-commit.mjs`. Unlike that sibling
+ * (which uses `stdio: 'inherit'` because it only cares about the exit code),
+ * this runner CAPTURES stdout — this module needs to parse and print the
+ * matched commits, not just observe whether the command succeeded.
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {object} [opts]
+ * @returns {{ status: number, stdout: string, error?: Error }}
+ */
+export function defaultGitLogRun(cmd, args, opts = {}) {
+  const result = spawnSync(cmd, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    ...opts,
+  });
+  if (result.error) return { status: 1, stdout: '', error: result.error };
+  return { status: result.status ?? 1, stdout: result.stdout ?? '' };
+}
+
+/**
+ * @typedef {{
+ *   found: true,
+ *   provenance: 'local-git-log',
+ *   output: string,
+ * } | {
+ *   found: false,
+ *   provenance: 'local-git-log',
+ *   reason: string,
+ * }} LocalGitLogResult
+ * @typedef {ConsoleSettlementResult | LocalGitLogResult} LookupResult
+ */
+
+/**
+ * Local fallback: `git -C <vaultRoot> log --grep <spec-id>`, run ONLY
+ * through the injected `run` — this module never shells out to git any
+ * other way. Never throws: a failed spawn or a non-zero exit resolves to a
+ * typed `{ found: false, reason }` result, same contract as
+ * {@link lookupConsoleSettlement}.
+ *
+ * @param {{ specId: string, vaultRoot?: string, run?: typeof defaultGitLogRun }} opts
+ * @returns {LocalGitLogResult}
+ */
+export function lookupLocalGitLog({ specId, vaultRoot = REPO_ROOT, run = defaultGitLogRun } = {}) {
+  const result = run('git', ['-C', vaultRoot, 'log', '--grep', specId]);
+
+  if (result.error) {
+    return {
+      found: false,
+      provenance: 'local-git-log',
+      reason: `git log failed to run (${result.error.message})`,
+    };
+  }
+  if (result.status !== 0) {
+    return {
+      found: false,
+      provenance: 'local-git-log',
+      reason: `git log exited ${result.status}`,
+    };
+  }
+
+  const output = (result.stdout ?? '').trim();
+  if (!output) {
+    return {
+      found: false,
+      provenance: 'local-git-log',
+      reason: `no local commits found matching --grep ${specId}`,
+    };
+  }
+
+  return { found: true, provenance: 'local-git-log', output };
+}
+
+/**
+ * Combined commit-history lookup (HS-CZ84): try the console settlement
+ * route first; when it finds nothing (unreachable OR no rows — both are
+ * "the console path came up empty"), fall back to the local
+ * `git log --grep <spec-id>` path. The returned result's `provenance` field
+ * always says which path actually produced it — the two result shapes are
+ * never silently merged (per this task's own do-not).
+ *
+ * @param {{
+ *   specId: string,
+ *   consoleUrl?: string,
+ *   fetchImpl?: HttpClient,
+ *   repoRoot?: string,
+ *   vaultRoot?: string,
+ *   gitRun?: typeof defaultGitLogRun,
+ * }} opts
+ * @returns {Promise<LookupResult>}
+ */
+export async function lookupCommitHistory({
+  specId,
+  consoleUrl,
+  fetchImpl = fetch,
+  repoRoot,
+  vaultRoot,
+  gitRun = defaultGitLogRun,
+} = {}) {
+  const consoleResult = await lookupConsoleSettlement({ specId, consoleUrl, fetchImpl, repoRoot });
+  if (consoleResult.found) return consoleResult;
+  return lookupLocalGitLog({ specId, vaultRoot: vaultRoot ?? repoRoot ?? REPO_ROOT, run: gitRun });
+}
+
+/**
+ * Render a lookup result as the CLI's printed output. Always labels
+ * provenance explicitly (`console` vs `local-git-log`) so a diagnosis
+ * reading the output is never misled about where the answer came from
+ * (AC2).
+ * @param {LookupResult} result
+ * @returns {string}
+ */
+export function formatSettlementResult(result) {
+  if (result.found && result.provenance === 'console') {
+    return [
+      `hs source log: settled (via ${result.provenance})`,
+      `  repo:       ${result.repo}`,
+      `  branch:     ${result.branch}`,
+      `  commitSha:  ${result.commitSha}`,
+      `  settledAt:  ${result.settledAt}`,
+    ].join('\n');
+  }
+  if (result.found && result.provenance === 'local-git-log') {
+    return [`hs source log: found (via ${result.provenance} fallback)`, result.output].join('\n');
+  }
+  return `hs source log: not found (via ${result.provenance}) — ${result.reason}`;
+}
+
+/**
+ * CLI entry for `hs source log <spec-id>`. Tries the console settlement
+ * route first, then falls back to local `git log --grep` (HS-CZ84) when the
+ * console path comes up empty — see {@link lookupCommitHistory}.
+ * @param {string[]} argv (verb-stripped: args after `log`)
+ * @param {{
+ *   cwd?: string,
+ *   fetchImpl?: HttpClient,
+ *   gitRun?: typeof defaultGitLogRun,
+ * }} [opts]
+ * @returns {Promise<number>} process exit code — 0 when found by either
+ *   path, 1 when the command ran cleanly but found nothing (usage error
+ *   included), never a thrown exception either way.
+ */
+export async function runLogCommand(
+  argv,
+  { cwd = process.cwd(), fetchImpl = fetch, gitRun = defaultGitLogRun } = {},
+) {
+  const specId = argv[0];
+  if (!specId) {
+    console.error('hs source log: a spec id is required (e.g. `hs source log HS-TASK-XA40`).');
+    return 1;
+  }
+
+  const result = await lookupCommitHistory({ specId, fetchImpl, repoRoot: cwd, gitRun });
+  console.log(formatSettlementResult(result));
+  return result.found ? 0 : 1;
+}
+
+// ---- direct-invocation entry --------------------------------------------
+
+function invokedDirectly() {
+  try {
+    return path.resolve(fileURLToPath(import.meta.url)) === path.resolve(process.argv[1] ?? '');
+  } catch {
+    return false;
+  }
+}
+
+if (invokedDirectly()) {
+  // argv: [node, script, "log", ...flags] — drop the leading verb token.
+  runLogCommand(process.argv.slice(3)).then((code) => process.exit(code));
+}