heyspex 0.1.0 → 0.2.1

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

@@ -1,307 +1,386 @@
-#!/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));
-}
+#!/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
+ * 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 { 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;
+
+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
+ * 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 async function pushBranch({
+  remote = 'origin',
+  branch,
+  extraArgs = [],
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  cwd = process.cwd(),
+  spawnFn = spawn,
+  preScan = null,
+} = {}) {
+  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`).',
+    };
+  }
+
+  // ---- 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;
+
+  // ---- 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: 'PRESCAN_ERROR',
+        message: `hs source push: the preScan hook threw — ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+    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 = [
+      '-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) : '' };
+  }
+}
+
+/**
+ * Default no-branch resolver. Imported lazily so the (console-HTTP) resolver
+ * module graph loads ONLY when no branch was typed — an explicit-branch push
+ * keeps its original, minimal import surface.
+ */
+async function lazyResolvePushBranch(opts) {
+  const { resolvePushBranch } = await import('./hs-source-branch.mjs');
+  return resolvePushBranch(opts);
+}
+
+/**
+ * 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,
+    resolvePushBranchFn = lazyResolvePushBranch,
+  } = {},
+) {
+  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';
+  let branch = positional.length > 1 ? positional[1] : positional[0];
+
+  // No branch typed: ask the ONE shared branch resolver (the same function the
+  // cloud-write drain calls) via the console; offline it falls back to the
+  // checked-out branch and says so. An explicit branch is never second-guessed.
+  if (!branch) {
+    const resolved = await resolvePushBranchFn({ cwd });
+    if (!resolved.branch) {
+      console.error(`hs source push: ${resolved.note}. Pass a branch explicitly.`);
+      return 1;
+    }
+    if (resolved.note) console.error(`hs source push: ${resolved.note}.`);
+    else console.log(`hs source push: target branch \`${resolved.branch}\` (${resolved.source === 'session' ? 'declared session branch' : 'resolver fallback'}).`);
+    branch = resolved.branch;
+  }
+
+  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));
+}