heyspex 0.1.0

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

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+/**
+ * hs-source-push.mjs — `hs source push`: credential-hang prevention and
+ * destructive-verb refusal (HS-XFB3-CWPX, epic
+ * [[HS-Q0K8-CWPX-EPIC-spexsource-local-git-preflight-commit]]).
+ *
+ * Fixes the exact failure mode in
+ * [[specs/memory/lessons/an-agent-shell-git-push-hangs-on-the.md]]: `git
+ * push` over HTTPS on Windows falling through to the invisible GUI
+ * credential-manager prompt and hanging forever with no output. The fix is
+ * BOTH of: (1) substituting `gh`'s own credential helper
+ * (`-c credential.helper= -c "credential.helper=!gh auth git-credential"`)
+ * and (2) `GIT_TERMINAL_PROMPT=0` in the child env — the lesson is explicit
+ * that #2 alone does not stop the GUI-prompt path, so both are always
+ * applied together, on every invocation, unconditionally.
+ *
+ * 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.
+ */
+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));
+export const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+export const DEFAULT_TIMEOUT_MS = 60_000;
+
+/**
+ * Pushes `branch` to `remote` through the credential-hang-safe invocation,
+ * refusing outright (zero subprocess calls) on a force-push flag or a
+ * protected-ref target, and killing the child if it exceeds `timeoutMs`.
+ *
+ * @param {{
+ *   remote?: string,
+ *   branch: string,
+ *   extraArgs?: string[],
+ *   timeoutMs?: number,
+ *   cwd?: string,
+ *   spawnFn?: typeof spawn,
+ *   preScan?: (ctx: { remote: string, branch: string, cwd: string }) =>
+ *     ({ ok: boolean, message?: string } | null | undefined),
+ * }} opts
+ * @returns {Promise<{ ok: boolean, code: string, message?: string }>}
+ */
+export function pushBranch({
+  remote = 'origin',
+  branch,
+  extraArgs = [],
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  cwd = process.cwd(),
+  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;
+    }
+
+    // ---- 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;
+    }
+
+    // ---- 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({
+        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;
+    }
+
+    // ---- 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;
+      }
+    }
+
+    // ---- the actual push: credential-helper override + GIT_TERMINAL_PROMPT=0,
+    // both together, unconditionally, per the recorded lesson ----
+    const argv = [
+      '-c',
+      'credential.helper=',
+      '-c',
+      'credential.helper=!gh auth git-credential',
+      'push',
+      ...extraArgs,
+      remote,
+      branch,
+    ];
+    const env = { ...process.env, GIT_TERMINAL_PROMPT: '0' };
+
+    let settled = false;
+    let timedOut = false;
+
+    const child = spawnFn('git', argv, { cwd, env, stdio: 'inherit' });
+
+    // Deliberately NOT unref'd: the timer is always cleared the moment the
+    // child exits/errors (see finish() below), so it never outlives the
+    // child in practice — and staying ref'd is what lets a hung child
+    // actually be observed and killed rather than letting the process (or
+    // a test's event loop) end early while the timer is still outstanding.
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try {
+        child.kill();
+      } catch {
+        /* best effort — the exit/error handler below still resolves */
+      }
+    }, timeoutMs);
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(result);
+    };
+
+    child.on('error', (err) => {
+      finish({ ok: false, code: 'SPAWN_ERROR', message: `hs source push: failed to run git — ${err.message}` });
+    });
+
+    child.on('exit', (code, signal) => {
+      if (timedOut) {
+        finish({
+          ok: false,
+          code: 'TIMEOUT',
+          message: `hs source push: push exceeded the ${timeoutMs}ms wall-clock timeout and was killed. This is a HUNG PUSH (most likely the Windows credential-manager GUI prompt — [[specs/memory/lessons/an-agent-shell-git-push-hangs-on-the.md]]), not a normal git error. Re-check \`gh auth status\` and retry.`,
+        });
+        return;
+      }
+      if (code === 0) {
+        finish({ ok: true, code: 'OK' });
+        return;
+      }
+      finish({
+        ok: false,
+        code: 'GIT_EXIT_NONZERO',
+        message: `hs source push: git push exited with code ${code}${signal ? ` (signal ${signal})` : ''}.`,
+      });
+    });
+  });
+}
+
+/**
+ * Lists the paths touched by the commit(s) this push is about to send —
+ * the diff between the remote-tracking ref and HEAD when one exists, or
+ * just HEAD's own files for a branch never pushed before. Read-only: only
+ * `git rev-parse`/`git diff`/`git show --name-only` are ever run. Injectable
+ * `run` so tests never touch a real repo.
+ * @param {{ remote: string, branch: string, cwd: string, run?: (cmd:string,args:string[],opts:object)=>{status:number,stdout?:string} }} args
+ * @returns {string[]}
+ */
+export function pathsInOutgoingCommits({ remote, branch, cwd, run = defaultDiffRun }) {
+  const remoteRef = `${remote}/${branch}`;
+  const check = run('git', ['rev-parse', '--verify', '--quiet', remoteRef], { cwd });
+  const hasRemoteRef = check.status === 0;
+  const diffArgs = hasRemoteRef
+    ? ['diff', '--name-only', `${remoteRef}..HEAD`]
+    : ['show', '--name-only', '--pretty=format:', 'HEAD'];
+  const result = run('git', diffArgs, { cwd });
+  if (result.status !== 0) return [];
+  return String(result.stdout ?? '')
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter(Boolean);
+}
+
+function defaultDiffRun(cmd, args, opts = {}) {
+  try {
+    const stdout = execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], ...opts });
+    return { status: 0, stdout };
+  } catch (err) {
+    return { status: typeof err.status === 'number' ? err.status : 1, stdout: err.stdout ? String(err.stdout) : '' };
+  }
+}
+
+/**
+ * CLI entry for `hs source push`. Parses `[remote] <branch> [--force] [-f]
+ * [--force-with-lease] [--timeout <ms>]` from argv. Any force flag is
+ * forwarded into extraArgs so the guardrail classifier sees it and refuses —
+ * never silently dropped.
+ *
+ * Wires the secret-scan gate (HS-5NXX-CWPX) as the `preScan` passed into
+ * `pushBranch`: it lists the paths in the commits about to be pushed and
+ * scans them, blocking the push (with zero `git push` subprocess calls) on
+ * any finding.
+ *
+ * @param {string[]} argv (verb-stripped: args after `push`)
+ * @param {{
+ *   cwd?: string,
+ *   pushBranchFn?: typeof pushBranch,
+ *   scanPathsFn?: typeof scanPaths,
+ *   listOutgoingPaths?: typeof pathsInOutgoingCommits,
+ * }} [opts]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runPushCommand(
+  argv,
+  { cwd = process.cwd(), pushBranchFn = pushBranch, scanPathsFn = scanPaths, listOutgoingPaths = pathsInOutgoingCommits } = {},
+) {
+  const positional = [];
+  const extraArgs = [];
+  let timeoutMs = DEFAULT_TIMEOUT_MS;
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--timeout' && argv[i + 1] !== undefined) {
+      const parsed = Number(argv[i + 1]);
+      if (Number.isFinite(parsed) && parsed > 0) timeoutMs = parsed;
+      i++;
+      continue;
+    }
+    if (a === '--force' || a === '-f' || a === '--force-with-lease' || a === '--delete') {
+      extraArgs.push(a);
+      continue;
+    }
+    positional.push(a);
+  }
+
+  const remote = positional.length > 1 ? positional[0] : 'origin';
+  const branch = positional.length > 1 ? positional[1] : positional[0];
+
+  const preScan = ({ remote: r, branch: b, cwd: c }) => {
+    let paths;
+    try {
+      paths = listOutgoingPaths({ remote: r, branch: b, cwd: c });
+    } catch {
+      // Read-only listing failed (e.g. no commits yet) — nothing to scan,
+      // never block the push on a listing failure.
+      return { ok: true };
+    }
+    const findings = scanPathsFn(paths, { cwd: c });
+    if (findings.length > 0) {
+      const names = findings.map((f) => `${f.path} (${f.rule})`).join(', ');
+      return {
+        ok: false,
+        message: `hs source push: secret scan blocked the push — likely secret(s) found: ${names}`,
+      };
+    }
+    return { ok: true };
+  };
+
+  const result = await pushBranchFn({ remote, branch, extraArgs, timeoutMs, cwd, preScan });
+  if (!result.ok) {
+    console.error(result.message);
+    return 1;
+  }
+  console.log(`hs source push: pushed ${remote}/${branch}.`);
+  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, "push", ...flags] — drop the leading verb token.
+  runPushCommand(process.argv.slice(3)).then((code) => process.exit(code));
+}

package/scripts/lib/hs-source-secret-scan.mjs

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+/**
+ * hs-source-secret-scan.mjs — secret-scan gate wired into `hs source
+ * preflight` and `hs source push` (HS-5NXX-CWPX, epic
+ * [[HS-Q0K8-CWPX-EPIC-spexsource-local-git-preflight-commit]]).
+ *
+ * Nothing in this repo scanned for secrets before this task. `scanPaths`
+ * prefers a real `gitleaks` binary when one is already resolvable on PATH
+ * (detected, never auto-installed — this repo's hard rule is no npm/network
+ * installs from an agent session, and `npx gitleaks` would silently attempt
+ * to download+run an arbitrary binary on first use, which is worse than just
+ * not having it); otherwise it falls back to an in-repo regex/entropy
+ * scanner covering AWS keys, GitHub tokens, private-key blocks, `.env`
+ * files, and high-entropy values assigned to key/secret/token/password-named
+ * variables. Either way the public shape is the same: an array of findings
+ * (empty = clean) with a `.engine` property naming which backend ran.
+ *
+ * NEVER logs a matched secret's actual value — findings carry only the
+ * file path and the rule name that matched.
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+// ---- engine detection ----------------------------------------------------
+
+/**
+ * Resolves a binary's location via `where`/`which` — detection only, never
+ * an install/download. Injectable so tests can simulate gitleaks being
+ * present without it actually being on this machine.
+ * @param {string} bin
+ * @returns {string | null}
+ */
+export function defaultWhich(bin) {
+  try {
+    const finder = process.platform === 'win32' ? 'where' : 'which';
+    const out = execFileSync(finder, [bin], { encoding: 'utf8' });
+    const first = out
+      .split(/\r?\n/)
+      .map((l) => l.trim())
+      .find(Boolean);
+    return first || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {{ which?: typeof defaultWhich }} [opts]
+ * @returns {string | null} the gitleaks binary path, or null if not on PATH
+ */
+export function detectGitleaksBinary({ which = defaultWhich } = {}) {
+  return which('gitleaks');
+}
+
+// ---- built-in fallback scanner --------------------------------------------
+
+const RULES = [
+  { name: 'aws-access-key-id', re: /AKIA[0-9A-Z]{16}/g },
+  { name: 'github-token', re: /(?:ghp_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{22,})/g },
+  {
+    name: 'private-key-block',
+    re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |ENCRYPTED )?PRIVATE KEY-----/g,
+  },
+];
+
+const DOTENV_FILENAME_RE = /(^|[\\/])\.env(\..+)?$/i;
+
+// key/secret/token/password assigned to a long, base64/url-safe-ish looking
+// value — the "generic high-entropy string" fallback family. Captures the
+// identifier too (group 1) so obviously-non-secret identifiers (charset /
+// alphabet constants that merely CONTAIN "key") can be excluded.
+const ASSIGNMENT_RE =
+  /([A-Za-z_][A-Za-z0-9_]*(?:key|secret|token|passwd|password)[A-Za-z0-9_]*)\s*[:=]\s*["']([A-Za-z0-9+/_.\-]{20,})["']/gi;
+const ENTROPY_MIN_LENGTH = 24;
+const ENTROPY_THRESHOLD_BITS_PER_CHAR = 3.6;
+
+// Identifiers that merely contain "key"/"secret"/etc but name something
+// structurally unrelated (a charset/alphabet constant, not a credential).
+const NON_SECRET_IDENTIFIER_RE = /charset|alphabet/i;
+
+// Values that are obviously placeholders/fixtures, not real secrets — kept
+// deliberately short and generic (this is a heuristic fallback, not
+// gitleaks; some false positives are expected and acceptable, but these
+// words are unambiguous enough to skip without losing real coverage).
+const PLACEHOLDER_VALUE_RE = /test|fake|dummy|example|placeholder|changeme|not-?real|sample|xxx|todo/i;
+
+/** @param {string} s @returns {number} Shannon entropy, bits/char */
+function shannonEntropy(s) {
+  const counts = new Map();
+  for (const ch of s) counts.set(ch, (counts.get(ch) ?? 0) + 1);
+  let entropy = 0;
+  for (const count of counts.values()) {
+    const p = count / s.length;
+    entropy -= p * Math.log2(p);
+  }
+  return entropy;
+}
+
+/**
+ * Scans one file's content for the built-in rule set. Never includes the
+ * matched text in the returned finding.
+ * @param {string} relPath
+ * @param {string} content
+ * @returns {{ path: string, rule: string }[]}
+ */
+export function scanContent(relPath, content) {
+  const findings = [];
+  const seenRules = new Set();
+
+  for (const rule of RULES) {
+    rule.re.lastIndex = 0;
+    if (rule.re.test(content) && !seenRules.has(rule.name)) {
+      findings.push({ path: relPath, rule: rule.name });
+      seenRules.add(rule.name);
+    }
+  }
+
+  if (DOTENV_FILENAME_RE.test(relPath.split(path.sep).join('/')) && !seenRules.has('dotenv-file')) {
+    findings.push({ path: relPath, rule: 'dotenv-file' });
+    seenRules.add('dotenv-file');
+  }
+
+  ASSIGNMENT_RE.lastIndex = 0;
+  let m;
+  while ((m = ASSIGNMENT_RE.exec(content))) {
+    const identifier = m[1];
+    const value = m[2];
+    if (NON_SECRET_IDENTIFIER_RE.test(identifier)) continue;
+    if (PLACEHOLDER_VALUE_RE.test(value)) continue;
+    if (value.length >= ENTROPY_MIN_LENGTH && shannonEntropy(value) >= ENTROPY_THRESHOLD_BITS_PER_CHAR) {
+      if (!seenRules.has('high-entropy-assignment')) {
+        findings.push({ path: relPath, rule: 'high-entropy-assignment' });
+        seenRules.add('high-entropy-assignment');
+      }
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * @param {string[]} paths
+ * @param {{ cwd?: string }} [opts]
+ * @returns {{ path: string, rule: string }[]}
+ */
+// Test files legitimately contain secret-shaped fixture strings (this
+// scanner's own test proves detection with a fake AWS key and a fake RSA
+// key block) — scanning them against real commits would block on the
+// scanner's own fixtures forever. Real test suites don't need literal
+// production secrets to pass, so this costs no real coverage.
+const TEST_FILE_RE = /\.test\.[cm]?[jt]sx?$/;
+
+function builtinScan(paths, { cwd = process.cwd() } = {}) {
+  const findings = [];
+  for (const relPath of paths) {
+    if (TEST_FILE_RE.test(relPath.split(path.sep).join('/'))) continue;
+    const abs = path.isAbsolute(relPath) ? relPath : path.join(cwd, relPath);
+    let content;
+    try {
+      const stat = fs.statSync(abs);
+      if (!stat.isFile()) continue;
+      content = fs.readFileSync(abs, 'utf8');
+    } catch {
+      continue; // deleted/unreadable/binary — skip, never crash the gate
+    }
+    findings.push(...scanContent(relPath, content));
+  }
+  return findings;
+}
+
+// ---- real-gitleaks backend (used only when the binary is already on PATH) --
+
+/**
+ * Default real-gitleaks invocation. Injectable so tests can simulate its
+ * JSON report shape without the binary actually being installed. Any
+ * failure here (spawn error, unparsable report) propagates as a thrown
+ * error — `scanPaths` catches it and falls back to the built-in scanner
+ * rather than letting a flaky external binary break the gate.
+ * @param {{ bin: string, cwd: string, paths: string[] }} args
+ * @returns {{ path: string, rule: string }[]}
+ */
+export function defaultRunGitleaks({ bin, cwd, paths }) {
+  const reportPath = path.join(cwd, `.hs-source-gitleaks-${process.pid}-${Date.now()}.json`);
+  try {
+    execFileSync(
+      bin,
+      ['detect', '--no-git', '--source', cwd, '--report-format', 'json', '--report-path', reportPath, '--exit-code', '0'],
+      { cwd, stdio: ['ignore', 'ignore', 'ignore'] },
+    );
+    const raw = fs.readFileSync(reportPath, 'utf8');
+    const report = JSON.parse(raw || '[]');
+    const targetSet = new Set(paths.map((p) => p.split(path.sep).join('/')));
+    const findings = [];
+    for (const entry of Array.isArray(report) ? report : []) {
+      const file = String(entry.File ?? entry.file ?? '').split(path.sep).join('/');
+      if (targetSet.size > 0 && !targetSet.has(file)) continue;
+      findings.push({ path: file, rule: String(entry.RuleID ?? entry.rule ?? 'gitleaks-finding') });
+    }
+    return findings;
+  } finally {
+    try {
+      fs.unlinkSync(reportPath);
+    } catch {
+      /* best effort cleanup */
+    }
+  }
+}
+
+// ---- public entry point ----------------------------------------------------
+
+/**
+ * Scans `paths` for likely secrets. Prefers a real `gitleaks` binary already
+ * on PATH; falls back to the built-in scanner otherwise (or if the real
+ * invocation throws for any reason). Returns an array of findings (empty =
+ * clean) with a non-enumerable-looking-but-plain `.engine` property naming
+ * which backend ran ('gitleaks' | 'builtin').
+ *
+ * @param {string[]} paths
+ * @param {{
+ *   cwd?: string,
+ *   which?: typeof defaultWhich,
+ *   runGitleaks?: typeof defaultRunGitleaks,
+ * }} [opts]
+ * @returns {{ path: string, rule: string }[] & { engine: 'gitleaks' | 'builtin' }}
+ */
+export function scanPaths(paths, { cwd = process.cwd(), which = defaultWhich, runGitleaks = defaultRunGitleaks } = {}) {
+  const targets = Array.isArray(paths) ? paths.filter(Boolean) : [];
+  if (targets.length === 0) {
+    const empty = [];
+    empty.engine = 'builtin';
+    return empty;
+  }
+
+  const gitleaksBin = detectGitleaksBinary({ which });
+  if (gitleaksBin) {
+    try {
+      const findings = runGitleaks({ bin: gitleaksBin, cwd, paths: targets });
+      findings.engine = 'gitleaks';
+      return findings;
+    } catch {
+      // Fall through to the built-in scanner — a flaky/misbehaving external
+      // binary must never break the gate or crash the caller.
+    }
+  }
+
+  const findings = builtinScan(targets, { cwd });
+  findings.engine = 'builtin';
+  return findings;
+}
+
+/**
+ * Human-readable one-line summary of a findings array, for CLI reports.
+ * Never prints the matched secret value — file + rule only.
+ * @param {ReturnType<typeof scanPaths>} findings
+ * @returns {string}
+ */
+export function formatFindings(findings) {
+  if (!findings || findings.length === 0) return 'Secret scan: clean (0 findings)';
+  const lines = [`Secret scan: BLOCKED — ${findings.length} likely secret(s) found (engine: ${findings.engine ?? 'unknown'}):`];
+  for (const f of findings) lines.push(`  - ${f.path} (${f.rule})`);
+  return lines.join('\n');
+}

package/scripts/lib/standalone-doctor.mjs

@@ -0,0 +1,89 @@
+/**
+ * standalone-doctor.mjs — the `runtime-files` check for `hs doctor` in
+ * published-install mode (no `scripts/heyspex-doctor.mjs` on disk — that
+ * script only ships inside a source clone; see `bin/hs.mjs`'s dispatch site).
+ *
+ * Extracted out of `bin/hs.mjs`'s `runStandaloneDoctor()` so it is testable
+ * as a pure function over an injected fs seam, rather than only reachable by
+ * spawning the whole CLI ([[HS-67ES-0JNK-TASK-fresh-install-honesty-statusline-only]]
+ * AC3). Before this, a published install's health check only verified
+ * version + sibling-bins-on-PATH — it never noticed that a runtime file the
+ * server dynamic-imports or spawns (e.g. `scripts/lib/dev-mode.mjs`, missing
+ * from `package.json` `files` until [[HS-PO09-0JNK-TASK-packed-mcp-server-runs-the-agent-loop]])
+ * was simply absent from the install. `hs doctor` — the FIRST command a
+ * customer would reasonably run to sanity-check a fresh install — reported
+ * everything green while `heyspex_preflight` threw `MODULE_NOT_FOUND` on the
+ * very next command.
+ *
+ * `RUNTIME_FILES` is the same set `scripts/lib/packed-runtime-imports.test.mjs`
+ * proves ships in the published tarball (its two explicitly-diagnosed
+ * dynamic-import targets, the `hs source` entrypoints it spawns, and the two
+ * `dist/cli/*.mjs` bundle entries `hs init`/`hs install` dispatch to) — this
+ * is deliberately the SAME list, not a re-derivation, so the two checks can
+ * never silently drift apart (one says "ships", the other says "present").
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Runtime files a published install must have next to `bin/hs.mjs` — each
+ * entry is a path-segment array (portable across `path.join`/posix).
+ */
+export const RUNTIME_FILES = Object.freeze([
+  ["vendor", "heyspex-mcp", "cli.mjs"],
+  ["scripts", "lib", "dev-mode.mjs"],
+  ["scripts", "dev-server-status.mjs"],
+  ["scripts", "lib", "hs-source-preflight.mjs"],
+  ["scripts", "lib", "hs-source-commit.mjs"],
+  ["scripts", "lib", "hs-source-push.mjs"],
+  ["scripts", "lib", "hs-source-secret-scan.mjs"],
+  ["dist", "cli", "hs-init.mjs"],
+  ["dist", "cli", "hs-install.mjs"],
+]);
+
+/**
+ * Check every {@link RUNTIME_FILES} entry against `pkgRoot`. Returns
+ * `{ ok, missing, present }` — `missing`/`present` are POSIX-joined relative
+ * paths (e.g. `"scripts/lib/dev-mode.mjs"`), never absolute, so a report can
+ * name the missing file without leaking this machine's install path.
+ *
+ * `exists` is injectable (defaults to the real `node:fs.existsSync`) so tests
+ * can point this at a real temp directory (never a mocked `node:fs`) with one
+ * file deliberately removed.
+ */
+export function checkRuntimeFiles(pkgRoot, { exists = existsSync } = {}) {
+  const missing = [];
+  const present = [];
+  for (const rel of RUNTIME_FILES) {
+    const relPosix = rel.join("/");
+    const abs = join(pkgRoot, ...rel);
+    if (exists(abs)) present.push(relPosix);
+    else missing.push(relPosix);
+  }
+  return { ok: missing.length === 0, missing, present };
+}
+
+/**
+ * Render {@link checkRuntimeFiles}'s result as one `hs doctor` check row —
+ * same shape `runStandaloneDoctor` pushes onto `report.checks` for its other
+ * checks (`id`/`status`/`detail`/optional `human`).
+ */
+export function runtimeFilesCheckRow(pkgRoot, opts = {}) {
+  const { ok, missing } = checkRuntimeFiles(pkgRoot, opts);
+  if (ok) {
+    return {
+      id: "runtime-files",
+      status: "ok",
+      detail: "every packaged runtime file is present",
+    };
+  }
+  return {
+    id: "runtime-files",
+    status: "fail",
+    detail: `missing: ${missing.join(", ")}`,
+    human:
+      `This install is missing ${missing.length} runtime file${missing.length === 1 ? "" : "s"} ` +
+      `the server needs at call time (${missing.join(", ")}). Re-run \`npm install heyspex\` — ` +
+      "if it's still missing after a clean reinstall, the published package itself is broken.",
+  };
+}