heyspex 0.1.0

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

@@ -0,0 +1,402 @@
+#!/usr/bin/env node
+/**
+ * hs-source-preflight.mjs — read-only tree status + path-scoped stage plan
+ * for `hs source status` / `hs source preflight`
+ * (HS-QKO3-CWPX, epic [[HS-Q0K8-CWPX-EPIC-spexsource-local-git-preflight-commit]]).
+ *
+ * Both exported entry points below are STRICTLY READ-ONLY: this module must
+ * never shell out to `git add`, `git commit`, or `git push`. That is proven
+ * by the colocated test, which spies on the injected command runner and
+ * asserts no invocation's argv ever contains those verbs.
+ *
+ * `hs source commit` (sibling task HS-EZNJ-CWPX) consumes the stage plan
+ * this module produces; it is the ONLY module in this epic allowed to stage.
+ */
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+import { scanPaths as defaultScanPaths } from './hs-source-secret-scan.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// Where `hs source preflight` persists its stage plan so `hs source commit`
+// (sibling task HS-EZNJ-CWPX) can consume it and refuse on drift/staleness.
+// Lives under `.git/` (like `.git/MERGE_MSG`, `.git/COMMIT_EDITMSG`) rather
+// than anywhere in the tracked working tree: `.git/` is never reported by
+// `git status`, so persisting the plan can never itself perturb the dirty
+// snapshot the plan's own freshness check re-reads a moment later. Writing
+// a plain file here is a filesystem write, not a git mutation — it never
+// touches refs/branches/commits.
+export const STAGE_PLAN_FILENAME = 'hs-source-stage-plan.json';
+
+// ---- staging denylist -------------------------------------------------
+// Machine-state junk that must never be swept into a commit by this tool —
+// per the originating incident and capture
+// [[HS-G7NR-V4RB-CAP-spexsource-a-heyspex-source-control-syst]].
+export const DENYLIST_PATTERNS = [
+  /(^|\/)\.heyspex\/[^/]*-history\.jsonl$/i,
+  /(^|\/)scheduler-cache\.json$/i,
+  /(^|\/)terminal-close-debug\.jsonl$/i,
+  /^spex-console\/\.next-prod\//i,
+];
+
+/** @param {string} relPath @returns {boolean} */
+export function isDenylisted(relPath) {
+  const norm = String(relPath).split(path.sep).join('/');
+  return DENYLIST_PATTERNS.some((re) => re.test(norm));
+}
+
+/**
+ * Default subprocess runner — injectable so tests can spy without ever
+ * touching real git state. Never throws on a non-zero exit; callers check
+ * `.status`.
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {object} [opts]
+ * @returns {{ status: number, stdout: string, stderr: string }}
+ */
+export function defaultRun(cmd, args, opts = {}) {
+  try {
+    const stdout = execFileSync(cmd, args, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      ...opts,
+    });
+    return { status: 0, stdout, stderr: '' };
+  } catch (err) {
+    return {
+      status: typeof err.status === 'number' ? err.status : 1,
+      stdout: err.stdout ? String(err.stdout) : '',
+      stderr: err.stderr ? String(err.stderr) : String(err.message ?? ''),
+    };
+  }
+}
+
+/** @param {string} raw @returns {{ code: string, path: string }[]} */
+function parsePorcelain(raw) {
+  return String(raw ?? '')
+    .split(/\r?\n/)
+    .map((l) => l.replace(/\r$/, ''))
+    .filter((l) => l.length > 0)
+    .map((line) => {
+      const code = line.slice(0, 2);
+      let rest = line.slice(3);
+      const arrow = rest.indexOf(' -> ');
+      if (arrow !== -1) rest = rest.slice(arrow + 4);
+      if (rest.startsWith('"') && rest.endsWith('"')) rest = rest.slice(1, -1);
+      return { code, path: rest };
+    });
+}
+
+/**
+ * Bare, read-only working-tree report: dirty paths + `gh auth status`.
+ * Performs ZERO git mutations.
+ * @param {{ cwd?: string, run?: typeof defaultRun }} [opts]
+ */
+export function getTreeStatus({ cwd = process.cwd(), run = defaultRun } = {}) {
+  const statusResult = run('git', ['status', '--porcelain=v1'], { cwd });
+  const dirty = statusResult.status === 0 ? parsePorcelain(statusResult.stdout) : [];
+
+  const ghResult = run('gh', ['auth', 'status'], { cwd });
+  const ghAuth = {
+    ok: ghResult.status === 0,
+    output: `${ghResult.stdout}${ghResult.stderr}`.trim(),
+  };
+
+  return { dirty, ghAuth };
+}
+
+// ---- lint/format scoping -----------------------------------------------
+// Mirrors the technique in scripts/run-pre-commit-checks.mjs
+// (stagedConsoleEslintPaths / stagedConsolePrettierPaths / resolveConsoleBin):
+// scope strictly to touched files under spex-console/ (the only place in
+// this repo with an eslint/prettier config today), resolve the bin via the
+// package's own package.json#bin rather than a subpath import, and never run
+// a bare `eslint .` / whole-workspace invocation — applied here to the
+// WORKING TREE (`git status`), not the staged index, since preflight runs
+// before anything is staged.
+const CONSOLE_ESLINT_RE = /^spex-console\/.+\.(ts|tsx|js|jsx|mjs|cjs)$/i;
+const CONSOLE_PRETTIER_RE = /^spex-console\/.+\.(ts|tsx|js|jsx|mjs|cjs|css|json|md|yml|yaml)$/i;
+const CONSOLE_EXCLUDE_RE =
+  /^spex-console\/(\.next|\.next-prod|node_modules|dist|coverage|public\/design-(previews|system)|figma-connect)\//i;
+
+/** @param {string} pkgName @returns {string | null} */
+function resolveConsoleBin(pkgName) {
+  try {
+    const req = createRequire(path.join(REPO_ROOT, 'spex-console', 'package.json'));
+    const pkgJsonPath = req.resolve(`${pkgName}/package.json`);
+    const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+    const binEntry = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.[pkgName];
+    if (!binEntry) return null;
+    return path.join(path.dirname(pkgJsonPath), binEntry);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Builds the path-scoped stage plan: touched paths minus the denylist, plus
+ * a scoped eslint/prettier pass and a secret scan limited to those paths.
+ * Still READ-ONLY — lint/format run in check mode only (`--check` for
+ * prettier; eslint's default is already non-mutating), the secret scan only
+ * reads file contents, and no `git add`/`commit`/`push` is ever invoked.
+ *
+ * The secret scan (HS-5NXX-CWPX) runs over `included` — the same paths the
+ * stage plan would `git add` — and a finding blocks the plan (`ok: false`)
+ * exactly like a failing lint/format check.
+ * @param {{ cwd?: string, run?: typeof defaultRun, scanPaths?: typeof defaultScanPaths }} [opts]
+ */
+export function buildStagePlan({ cwd = process.cwd(), run = defaultRun, scanPaths = defaultScanPaths } = {}) {
+  const { dirty, ghAuth } = getTreeStatus({ cwd, run });
+
+  const included = [];
+  const excluded = [];
+  for (const { path: p } of dirty) {
+    if (isDenylisted(p)) excluded.push(p);
+    else included.push(p);
+  }
+
+  const eslintTargets = included.filter(
+    (p) => CONSOLE_ESLINT_RE.test(p) && !CONSOLE_EXCLUDE_RE.test(p),
+  );
+  const prettierTargets = included.filter(
+    (p) => CONSOLE_PRETTIER_RE.test(p) && !CONSOLE_EXCLUDE_RE.test(p),
+  );
+
+  const lint = { ran: false, tool: /** @type {string|null} */ (null), targets: eslintTargets, ok: true, output: '' };
+  const format = { ran: false, tool: /** @type {string|null} */ (null), targets: prettierTargets, ok: true, output: '' };
+
+  if (eslintTargets.length > 0) {
+    const bin = resolveConsoleBin('eslint');
+    if (bin) {
+      const relTargets = eslintTargets.map((p) => p.replace(/^spex-console\//, ''));
+      const result = run(process.execPath, [bin, ...relTargets], {
+        cwd: path.join(cwd, 'spex-console'),
+      });
+      lint.ran = true;
+      lint.tool = bin;
+      lint.ok = result.status === 0;
+      lint.output = `${result.stdout}${result.stderr}`.trim();
+    }
+  }
+
+  if (prettierTargets.length > 0) {
+    const bin = resolveConsoleBin('prettier');
+    if (bin) {
+      const relTargets = prettierTargets.map((p) => p.replace(/^spex-console\//, ''));
+      const result = run(process.execPath, [bin, '--check', ...relTargets], {
+        cwd: path.join(cwd, 'spex-console'),
+      });
+      format.ran = true;
+      format.tool = bin;
+      format.ok = result.status === 0;
+      format.output = `${result.stdout}${result.stderr}`.trim();
+    }
+  }
+
+  const secretScanFindings = included.length > 0 ? scanPaths(included, { cwd }) : [];
+  const secretScan = {
+    ran: included.length > 0,
+    engine: secretScanFindings.engine ?? null,
+    findings: Array.from(secretScanFindings),
+  };
+
+  return {
+    ghAuth,
+    dirty,
+    included,
+    excluded,
+    lint,
+    format,
+    secretScan,
+    ok: lint.ok && format.ok && secretScan.findings.length === 0,
+  };
+}
+
+// ---- stage-plan persistence --------------------------------------------
+// `hs source preflight` writes the plan here; `hs source commit` (sibling
+// task HS-EZNJ-CWPX) reads it back and refuses to stage when the working
+// tree has drifted since the plan was produced.
+
+/**
+ * Deterministic fingerprint of a working tree's dirty-path snapshot — used
+ * to detect drift between "the plan was built" and "the plan is consumed".
+ * @param {{ code: string, path: string }[]} dirty
+ * @returns {string}
+ */
+export function computeDirtyFingerprint(dirty) {
+  const normalized = [...dirty]
+    .map((d) => `${d.code} ${d.path}`)
+    .sort()
+    .join('\n');
+  return crypto.createHash('sha256').update(normalized, 'utf8').digest('hex');
+}
+
+/** @param {string} cwd @returns {string} */
+export function stagePlanFilePath(cwd = REPO_ROOT) {
+  return path.join(cwd, '.git', STAGE_PLAN_FILENAME);
+}
+
+/**
+ * Persists a stage plan (as produced by buildStagePlan) to disk so a later
+ * `hs source commit` invocation can consume it. Best-effort: swallows write
+ * errors (e.g. `.git/` missing — not actually a git repo) rather than
+ * failing the read-only preflight command itself — the commit step will
+ * simply report "no plan".
+ * @param {ReturnType<typeof buildStagePlan>} plan
+ * @param {{ cwd?: string }} [opts]
+ */
+export function writeStagePlanFile(plan, { cwd = process.cwd() } = {}) {
+  try {
+    const dir = path.join(cwd, '.git');
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const record = {
+      createdAt: new Date().toISOString(),
+      cwd,
+      included: plan.included,
+      excluded: plan.excluded,
+      ok: plan.ok,
+      dirtyFingerprint: computeDirtyFingerprint(plan.dirty),
+    };
+    fs.writeFileSync(stagePlanFilePath(cwd), JSON.stringify(record, null, 2), 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Reads back a persisted stage plan. Returns `null` when no plan file
+ * exists or it cannot be parsed — callers treat that as "no plan".
+ * @param {{ cwd?: string }} [opts]
+ */
+export function readStagePlanFile({ cwd = process.cwd() } = {}) {
+  try {
+    const raw = fs.readFileSync(stagePlanFilePath(cwd), 'utf8');
+    const record = JSON.parse(raw);
+    if (!record || typeof record !== 'object' || !Array.isArray(record.included)) return null;
+    return record;
+  } catch {
+    return null;
+  }
+}
+
+// ---- CLI report formatting ---------------------------------------------
+
+/** @param {ReturnType<typeof getTreeStatus>} status */
+export function formatStatusReport(status) {
+  const lines = [];
+  lines.push('hs source status');
+  lines.push('');
+  if (status.dirty.length === 0) {
+    lines.push('Working tree clean.');
+  } else {
+    lines.push(`Dirty paths (${status.dirty.length}):`);
+    for (const d of status.dirty) lines.push(`  ${d.code} ${d.path}`);
+  }
+  lines.push('');
+  lines.push(`gh auth status: ${status.ghAuth.ok ? 'OK' : 'NOT LOGGED IN / ERROR'}`);
+  if (status.ghAuth.output) {
+    for (const l of status.ghAuth.output.split(/\r?\n/)) lines.push(`  ${l}`);
+  }
+  lines.push('');
+  lines.push('(read-only — nothing was staged, committed, or pushed)');
+  return lines.join('\n');
+}
+
+/** @param {ReturnType<typeof buildStagePlan>} plan */
+export function formatPreflightReport(plan) {
+  const lines = [];
+  lines.push('hs source preflight');
+  lines.push('');
+  lines.push(`gh auth status: ${plan.ghAuth.ok ? 'OK' : 'NOT LOGGED IN / ERROR'}`);
+  lines.push('');
+  if (plan.included.length === 0) {
+    lines.push('Stage plan: (empty — nothing to stage)');
+  } else {
+    lines.push(`Stage plan (${plan.included.length} path(s) — what \`hs source commit\` would \`git add\`):`);
+    for (const p of plan.included) lines.push(`  + ${p}`);
+  }
+  if (plan.excluded.length > 0) {
+    lines.push('');
+    lines.push(`Excluded (denylisted machine-state paths, ${plan.excluded.length}):`);
+    for (const p of plan.excluded) lines.push(`  - ${p}`);
+  }
+  lines.push('');
+  if (plan.lint.ran) {
+    lines.push(`ESLint (${plan.lint.targets.length} file(s)): ${plan.lint.ok ? 'PASS' : 'FAIL'}`);
+    if (!plan.lint.ok && plan.lint.output) lines.push(plan.lint.output);
+  } else if (plan.lint.targets.length > 0) {
+    lines.push(`ESLint: skipped (eslint binary not resolvable) for ${plan.lint.targets.length} file(s)`);
+  } else {
+    lines.push('ESLint: no touched spex-console/ files to scope to');
+  }
+  if (plan.format.ran) {
+    lines.push(`Prettier --check (${plan.format.targets.length} file(s)): ${plan.format.ok ? 'PASS' : 'FAIL'}`);
+    if (!plan.format.ok && plan.format.output) lines.push(plan.format.output);
+  } else if (plan.format.targets.length > 0) {
+    lines.push(`Prettier: skipped (prettier binary not resolvable) for ${plan.format.targets.length} file(s)`);
+  } else {
+    lines.push('Prettier: no touched spex-console/ files to scope to');
+  }
+  if (plan.secretScan) {
+    const findings = plan.secretScan.findings ?? [];
+    if (plan.secretScan.ran) {
+      lines.push(`Secret scan (engine: ${plan.secretScan.engine ?? 'unknown'}): ${findings.length === 0 ? 'PASS' : 'BLOCKED'}`);
+      for (const f of findings) lines.push(`  ! ${f.path} (${f.rule})`);
+    } else {
+      lines.push('Secret scan: nothing to stage, skipped');
+    }
+  }
+  lines.push('');
+  lines.push(plan.ok ? 'Preflight: PASS' : 'Preflight: FAIL — fix the issues above before `hs source commit`');
+  lines.push('(read-only — nothing was staged, committed, or pushed)');
+  return lines.join('\n');
+}
+
+/**
+ * CLI entry for `hs source status`. Returns a process exit code; always 0
+ * (read-only report, never fails the invocation itself).
+ * @param {{ cwd?: string }} [opts]
+ */
+export function runStatusCommand({ cwd = process.cwd() } = {}) {
+  const status = getTreeStatus({ cwd });
+  console.log(formatStatusReport(status));
+  return 0;
+}
+
+/**
+ * CLI entry for `hs source preflight`. Returns 0 when the stage plan's lint
+ * and format checks both pass, 1 otherwise — so a caller/script can gate on
+ * the exit code without parsing the printed report.
+ * @param {{ cwd?: string }} [opts]
+ */
+export function runPreflightCommand({ cwd = process.cwd() } = {}) {
+  const plan = buildStagePlan({ cwd });
+  writeStagePlanFile(plan, { cwd });
+  console.log(formatPreflightReport(plan));
+  console.log(`\nStage plan written to ${path.relative(cwd, stagePlanFilePath(cwd))} for \`hs source commit\`.`);
+  return plan.ok ? 0 : 1;
+}
+
+// ---- direct-invocation entry --------------------------------------------
+
+function invokedDirectly() {
+  try {
+    return import.meta.url === new URL(`file://${process.argv[1].replace(/\\/g, '/')}`).href
+      || path.resolve(fileURLToPath(import.meta.url)) === path.resolve(process.argv[1] ?? '');
+  } catch {
+    return false;
+  }
+}
+
+if (invokedDirectly()) {
+  const verb = process.argv[2];
+  if (verb === 'preflight') process.exit(runPreflightCommand());
+  else process.exit(runStatusCommand());
+}