@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.90

package/dist/runtime/sigint-guard.js

@@ -0,0 +1,272 @@
+/**
+ * Double-press Ctrl+C exit guard for the Pugi CLI top-level lifecycle.
+ *
+ * # Problem
+ *
+ * Operator dogfood reported a single Ctrl+C exits the REPL / headless
+ * loop. Operators expect a forgiving "press again to confirm" gesture
+ * — the same shell convention `^C ^C` already used by the per-engine
+ * task abort path in `runtime/cli.ts` (`runEngineTask`). Without the
+ * gesture at the top level, a stray Ctrl+C while typing a slash command
+ * or scrolling a transcript kills the session and any in-memory state
+ * the operator hasn't synced yet.
+ *
+ * # Behavior
+ *
+ *  1. **First Ctrl+C** — emit a one-line stderr prompt
+ *     "Press Ctrl+C again to exit (within 2s), or any key to continue."
+ *     Arm a 2-second window timer. Install a one-shot `stdin.once('data', …)`
+ *     so the FIRST keystroke after the prompt cancels the exit gesture.
+ *  2. **Second Ctrl+C inside window** — flush log streams, persist a
+ *     minimal session-state snapshot to `~/.pugi/session-state.json`,
+ *     and exit with code 0. The state file is best-effort: any write
+ *     error is swallowed so the operator's exit is never blocked on
+ *     a disk hiccup.
+ *  3. **Other key inside window** — clear the timer, drop the prompt,
+ *     emit "Exit cancelled." to stderr, and resume normally.
+ *  4. **Window expires** — clear `lastSigintTs`. A subsequent isolated
+ *     Ctrl+C is treated as a NEW first press, not a confirmation.
+ *  5. **Headless mode** — when `process.stdin.isTTY === false`, the
+ *     guard switches strategy: it closes stdin (so any `for await rl`
+ *     loop in `headless-repl.ts` unwinds naturally), emits a
+ *     `session-end` envelope to stdout (single JSON line, matches
+ *     the envelope schema), and exits 0. Stdin can't deliver "any
+ *     other key" when it's not a TTY, so the double-press dance is
+ *     skipped in this mode.
+ *
+ * # Coexistence with the per-engine-run handler
+ *
+ * `runEngineTask` in `runtime/cli.ts` installs its OWN
+ * `process.on('SIGINT', …)` for the duration of an engine dispatch
+ * (lines around 6233). That handler aborts the in-flight turn on the
+ * first press and exits 130 on a second press inside its OWN 2s
+ * window. Both handlers receive every SIGINT — Node delivers signals
+ * to every listener.
+ *
+ * To avoid a double prompt while an engine turn is running, this
+ * guard checks `process.listenerCount('SIGINT')` at the start of its
+ * handler: if any other listener is attached (i.e. an engine run owns
+ * the foreground), we step aside and let that handler drive the UX.
+ * The engine handler's "press again to exit" prompt already covers
+ * the abort-then-quit story for that window. When the engine run
+ * unwinds, it detaches its listener and the REPL-level guard regains
+ * control.
+ *
+ * # Why module-scope, not per-call closure
+ *
+ * The press-count state must survive between two distinct SIGINT
+ * deliveries. A closure-scoped flag would reset on the second SIGINT
+ * because Node invokes the handler in a fresh microtask each time.
+ * Module-scope `let` is the simplest store that gives us cross-press
+ * persistence without leaking to other files.
+ *
+ * # Testability
+ *
+ * `installSigintGuard()` takes an optional `SigintGuardOptions` bag
+ * so the spec can inject:
+ *   - a fake `stdin` (for "any key cancels"),
+ *   - a fake `stdout` / `stderr` sink,
+ *   - a `now()` clock seam,
+ *   - a `setTimeout` / `clearTimeout` pair,
+ *   - a `exit(code)` seam (the test never lets the real process exit),
+ *   - and a `persistSessionState(payload)` injection so the spec
+ *     observes the persisted snapshot without touching `~/`.
+ *
+ * In production all seams default to the real Node primitives.
+ */
+import { writeFile, mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve as resolvePath, dirname } from 'node:path';
+/**
+ * Default double-press window. Matches the per-engine-run handler so
+ * operators see one consistent timing rule across the CLI.
+ */
+export const SIGINT_DOUBLE_PRESS_WINDOW_MS = 2000;
+/**
+ * Default location for the session-state snapshot the guard writes on
+ * a confirmed exit. Resolved at call time so `homedir()` is read late
+ * enough to honor a test override of the `HOME` env var.
+ */
+export function defaultSessionStatePath(home = homedir()) {
+    return resolvePath(home, '.pugi', 'session-state.json');
+}
+/**
+ * Default JSON-file persister. Best-effort: a failed write is logged
+ * to stderr (so the operator notices in debug runs) and then
+ * swallowed — the exit must not block on filesystem health.
+ */
+async function defaultPersist(snapshot) {
+    const filePath = defaultSessionStatePath();
+    try {
+        await mkdir(dirname(filePath), { recursive: true });
+        await writeFile(filePath, JSON.stringify(snapshot, null, 2), {
+            mode: 0o600,
+            encoding: 'utf8',
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`pugi: session-state write failed: ${message}\n`);
+    }
+}
+/**
+ * Default SIGINT subscription wires the handler onto `process` and
+ * returns an unsubscribe closure that detaches it. We use `.on` (not
+ * `.once`) so the handler stays attached across multiple presses
+ * within the same process lifetime.
+ */
+function defaultOnSigint(handler) {
+    process.on('SIGINT', handler);
+    return () => {
+        process.off('SIGINT', handler);
+    };
+}
+/**
+ * Install the double-press Ctrl+C exit guard. Returns a handle whose
+ * `uninstall()` detaches the SIGINT listener and clears any pending
+ * window timer; production never calls it.
+ *
+ * This function is idempotent: calling it a second time installs a
+ * NEW guard alongside the old one, which would cause duplicate
+ * prompts. The caller (cli.ts main entry) MUST call it exactly once,
+ * at the very top of the run. Tests that need multiple installs are
+ * expected to `uninstall()` between scenarios.
+ */
+export function installSigintGuard(options = {}) {
+    const stdin = options.stdin ?? process.stdin;
+    const stderr = options.stderr ?? process.stderr;
+    const stdout = options.stdout ?? process.stdout;
+    const now = options.now ?? Date.now;
+    const setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+    const clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+    const exit = options.exit ?? ((code) => process.exit(code));
+    const persist = options.persistSessionState ?? defaultPersist;
+    const subscribe = options.onSigint ?? defaultOnSigint;
+    const isHeadless = options.isHeadless ?? (() => stdin.isTTY !== true);
+    const windowMs = options.windowMs ?? SIGINT_DOUBLE_PRESS_WINDOW_MS;
+    // State scoped to THIS install. Each call to `installSigintGuard`
+    // gets a fresh closure so concurrent tests do not bleed into each
+    // other. Production calls the function once at the top of the run.
+    let lastSigintTs = null;
+    let pendingTimer = null;
+    let pendingDataListener = null;
+    const resetWindow = () => {
+        lastSigintTs = null;
+        if (pendingTimer !== null) {
+            clearTimer(pendingTimer);
+            pendingTimer = null;
+        }
+        if (pendingDataListener !== null) {
+            // Detach via the same instance we attached; never the typed
+            // overload that re-binds 'data' to all listeners.
+            stdin.removeListener('data', pendingDataListener);
+            pendingDataListener = null;
+        }
+    };
+    const performExit = (reason) => {
+        const snapshot = {
+            exitedAt: new Date(now()).toISOString(),
+            reason,
+            cwd: process.cwd(),
+            pid: process.pid,
+        };
+        // Fire-and-forget persistence: we attempt to flush, but do not
+        // block the exit on the result. The promise is observed only to
+        // suppress unhandled-rejection noise in the test runner.
+        void persist(snapshot).catch(() => {
+            /* defaultPersist already logged */
+        });
+        exit(0);
+    };
+    const handleHeadless = () => {
+        // In headless mode we never prompt — the operator (or harness)
+        // has no keyboard to confirm with. We emit one final
+        // session-end envelope so any line-buffered consumer sees a
+        // clean terminator, close stdin so the `for await rl` loop in
+        // headless-repl.ts unwinds, and exit 0.
+        const envelope = {
+            kind: 'session-end',
+            body: JSON.stringify({ reason: 'sigint' }),
+            ts: now(),
+        };
+        stdout.write(`${JSON.stringify(envelope)}\n`);
+        // Best-effort stdin close so any in-flight readline loop terminates.
+        // Some stream implementations (e.g. test doubles) lack `.destroy`;
+        // guard the call so we never throw out of a signal handler.
+        const stdinAsAny = stdin;
+        try {
+            if (typeof stdinAsAny.destroy === 'function') {
+                stdinAsAny.destroy();
+            }
+            else if (typeof stdinAsAny.pause === 'function') {
+                stdinAsAny.pause();
+            }
+        }
+        catch {
+            /* ignore — destroy/pause is opportunistic */
+        }
+        performExit('sigint-headless');
+    };
+    const handleInteractive = () => {
+        const ts = now();
+        if (lastSigintTs !== null && ts - lastSigintTs <= windowMs) {
+            // Confirmed double-press. Drop the prompt artifacts, persist
+            // state, exit clean. resetWindow() handles the listener
+            // cleanup so a stray `data` event after exit does not fire.
+            resetWindow();
+            stderr.write('\npugi: exiting (^C^C confirmed).\n');
+            performExit('sigint-double-press');
+            return;
+        }
+        // First press — arm the window.
+        lastSigintTs = ts;
+        stderr.write('\nPress Ctrl+C again to exit (within 2s), or any key to continue.\n');
+        // Schedule a window-expiry reset. When the timer fires the
+        // operator's prior press no longer "counts" — the next ^C is
+        // treated as a fresh first press.
+        pendingTimer = setTimer(() => {
+            lastSigintTs = null;
+            pendingTimer = null;
+            if (pendingDataListener !== null) {
+                stdin.removeListener('data', pendingDataListener);
+                pendingDataListener = null;
+            }
+        }, windowMs);
+        // Install a one-shot 'data' listener so any keystroke other than
+        // a follow-up SIGINT cancels the exit gesture. We use
+        // `removeListener` after firing rather than `.once` because we
+        // also detach the listener from `resetWindow()` (the timer or
+        // a second SIGINT can both kill it).
+        const onData = (_chunk) => {
+            resetWindow();
+            stderr.write('Exit cancelled.\n');
+        };
+        pendingDataListener = onData;
+        stdin.on('data', onData);
+    };
+    const handler = () => {
+        // Coexistence guard: if another SIGINT listener is registered
+        // (e.g. the per-engine-run handler in runEngineTask), step aside
+        // and let it drive the UX. We count `> 1` because OUR handler
+        // is also in the list.
+        if (process.listenerCount('SIGINT') > 1 && !options.onSigint) {
+            // Drop any state we'd accumulated so an interactive prompt
+            // after the engine run starts from a clean slate.
+            resetWindow();
+            return;
+        }
+        if (isHeadless()) {
+            handleHeadless();
+            return;
+        }
+        handleInteractive();
+    };
+    const unsubscribe = subscribe(handler);
+    return {
+        uninstall: () => {
+            resetWindow();
+            unsubscribe();
+        },
+    };
+}
+//# sourceMappingURL=sigint-guard.js.map

package/dist/runtime/update-check.js

@@ -1,5 +1,5 @@
 /**
- * Update check + install-method detection — Sprint α6.2.
+ * Update check + install-method detection — Sprint .
  *
  * Shows the REPL operator a one-shot banner at startup when the npm
  * registry advertises a `@pugi/cli` version newer than what is running.
@@ -8,19 +8,19 @@
  *
  * Constraints baked into the spec:
  *
- *   - **Default-quiet.** Network errors, cache misses, and the
- *     `PUGI_SKIP_UPDATE_BANNER=1` env var all return `null` so the
- *     REPL renders unchanged.
- *   - **24h cache.** The check runs at most once per day, persisted to
- *     `~/.pugi/update-check.json`. Repeated REPL launches in the same
- *     day skip the registry call entirely.
- *   - **3s timeout.** A slow registry never blocks REPL startup; the
- *     undici request is aborted after 3 seconds and treated as a
- *     silent miss.
- *   - **Pure helpers, IO at the edge.** Detection, comparison, cache
- *     decode/encode are exported as pure functions with explicit env /
- *     home / now / fetch seams so the spec's 8 tests can drive every
- *     branch without touching the network or the real filesystem.
+ *  - **Default-quiet.** Network errors, cache misses, and the
+ *    `PUGI_SKIP_UPDATE_BANNER=1` env var all return `null` so the
+ *    REPL renders unchanged.
+ *  - **24h cache.** The check runs at most once per day, persisted to
+ *    `~/.pugi/update-check.json`. Repeated REPL launches in the same
+ *    day skip the registry call entirely.
+ *  - **3s timeout.** A slow registry never blocks REPL startup; the
+ *    undici request is aborted after 3 seconds and treated as a
+ *    silent miss.
+ *  - **Pure helpers, IO at the edge.** Detection, comparison, cache
+ *    decode/encode are exported as pure functions with explicit env /
+ *    home / now / fetch seams so the spec's 8 tests can drive every
+ *    branch without touching the network or the real filesystem.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -120,16 +120,16 @@ export function isCacheFresh(record, nowMs) {
  * `0.1.0-alpha.6` vs `0.1.0-alpha.7` / `0.1.0-beta.1` / `1.0.0`).
  *
  * Returns:
- *   -1 if `a < b`
- *    0 if `a === b`
- *    1 if `a > b`
+ *  -1 if `a < b`
+ *   0 if `a === b`
+ *   1 if `a > b`
  *
  * Rules follow semver §11:
- *   - Major.Minor.Patch compared numerically left-to-right.
- *   - A version with a prerelease tag is LOWER than the same version
- *     without one (`1.0.0-alpha` < `1.0.0`).
- *   - Prerelease identifiers compared dot-by-dot; numeric chunks
- *     numerically, mixed chunks ASCII-lexicographic.
+ *  - Major.Minor.Patch compared numerically left-to-right.
+ *  - A version with a prerelease tag is LOWER than the same version
+ *    without one (`1.0.0-alpha` < `1.0.0`).
+ *  - Prerelease identifiers compared dot-by-dot; numeric chunks
+ *    numerically, mixed chunks ASCII-lexicographic.
  */
 export function compareVersions(a, b) {
     const [coreA, preA] = splitVersion(a);
@@ -233,11 +233,11 @@ export async function fetchLatestVersion(fetcher = request) {
  * declines to fire, otherwise `null`.
  *
  * Silence rules (any one of these short-circuits to `null`):
- *   - `cliSkip === true` (operator passed `--no-update-check`).
- *   - `env.PUGI_SKIP_UPDATE_BANNER === '1'`.
- *   - `isTty === false` (CI / piped / scripted invocation).
- *   - Cache + network both miss — silent skip per spec.
- *   - `installed >= latest` — no upgrade to advertise.
+ *  - `cliSkip === true` (operator passed `--no-update-check`).
+ *  - `env.PUGI_SKIP_UPDATE_BANNER === '1'`.
+ *  - `isTty === false` (CI / piped / scripted invocation).
+ *  - Cache + network both miss — silent skip per spec.
+ *  - `installed >= latest` — no upgrade to advertise.
  */
 export async function checkForUpdate(options) {
     const env = options.env ?? process.env;
@@ -288,7 +288,7 @@ export function upgradeCommand(method) {
             return 'curl -fsSL https://install.pugi.io | sh';
         case 'unknown':
         default:
-            return 'npm install -g @pugi/cli@latest  # or your install method';
+            return 'npm install -g @pugi/cli@latest # or your install method';
     }
 }
 //# sourceMappingURL=update-check.js.map

package/dist/runtime/version.js

@@ -0,0 +1,65 @@
+/**
+ * Pugi CLI ↔ admin-api version handshake — shared constants.
+ *
+ * The CLI declares its installed version on every outbound request to
+ * the admin-api so the server can enforce a minClientVersion floor and
+ * surface a soft-warn for stale-but-allowed installs. See ADR-225 and
+ * `apps/admin-api/src/runtime/version.contract.ts` for the server side.
+ *
+ * # Why the constants live here, not in `@pugi/sdk`
+ *
+ * The SDK ships to customers as part of the public npm package; bumping
+ * a header name there would force a coupled CLI ↔ SDK release. Keeping
+ * the constants in the CLI gives us room to evolve the handshake
+ * without coupling the SDK's release cadence to it.
+ */
+/**
+ * Defensive semver sanitizer — single source of truth for the
+ * `0.0.0-unknown` fallback when a partially-published pnpm release
+ * leaks `workspace:*` into the version literal. `runtime/cli.ts`
+ * re-exports this under its `__test__` surface so the existing
+ * cli.ts test corpus keeps working with zero churn.
+ *
+ * Lives here (not in cli.ts) because the version handshake interceptor
+ * needs the same guarantee without pulling in the heavyweight cli.ts
+ * module graph during transport bootstrap.
+ */
+export function sanitizeSemver(raw) {
+    if (typeof raw !== 'string')
+        return '0.0.0-unknown';
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return '0.0.0-unknown';
+    const stripped = trimmed.replace(/^(workspace:|npm:|file:)/, '');
+    if (/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(stripped)) {
+        return stripped;
+    }
+    return '0.0.0-unknown';
+}
+/**
+ * Installed CLI version — single source of truth for the handshake
+ * header value. Mirrors the literal in `runtime/cli.ts` (intentional
+ * duplication because the cli.ts module pulls in Ink + half the CLI
+ * surface and the transport interceptor must remain side-effect-free
+ * during import). When bumping the CLI version BOTH literals must be
+ * updated; the release smoke-test (`pack:smoke`) verifies they agree.
+ */
+export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.90');
+/**
+ * Outbound: the CLI's installed semver. Read at request time by
+ * `version-interceptor.ts` and injected on every `fetch` call.
+ */
+export const PUGI_CLI_VERSION_HEADER = 'X-Pugi-Cli-Version';
+/**
+ * Inbound: the server's recommendation for which CLI version operators
+ * should be on. Surfaces through the UpdateBanner alongside the npm
+ * registry poll (the higher of the two wins).
+ */
+export const PUGI_CLI_UPGRADE_RECOMMENDED_HEADER = 'X-Pugi-Cli-Upgrade-Recommended';
+/**
+ * Inbound: server's own admin-api version. Useful for diagnostics
+ * (`pugi doctor --json`) but no enforcement logic keys off it — server
+ * drift between admin-api releases is normal during rolling deploys.
+ */
+export const PUGI_SERVER_VERSION_HEADER = 'X-Pugi-Server-Version';
+//# sourceMappingURL=version.js.map