@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.1

package/dist/runtime/sigint-guard.js

@@ -1,272 +0,0 @@
-/**
- * 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/stream-renderer.js

@@ -1,195 +0,0 @@
-/**
- * Streaming event renderer (Trust Sprint item 5).
- *
- * Subscribes to the engine adapter's `streamEmitter` and writes
- * human-readable progress lines to stderr while the dispatch is in
- * flight. Solves Codex dogfood 2026-06-04 finding: `pugi
- * code/fix/build/plan` were silent until the full dispatch
- * completed, which produced an empty terminal for 20-30s and made
- * customers think the CLI had hung.
- *
- * Design constraints:
- *
- *   1. STDERR ONLY. The CLI's machine-readable contract is "JSON on
- *      stdout, prose on stderr". Streaming on stdout would break the
- *      JSON envelope for `pugi code --json`.
- *
- *   2. No engine modifications. We attach a listener to the existing
- *      `streamEmitter` that the engine already emits to (used by the
- *      headless mode). The engine adapter file is owned by the other
- *      agent on PUGI-VERIFY-GATE and intentionally NOT touched here.
- *
- *   3. TTY-only by default. CI / pipes / JSON consumers get a clean
- *      stream. Explicit `--stream` overrides to force progress lines
- *      on; `--no-stream` overrides off.
- *
- *   4. Compact. One line per tool call (start) and one line per
- *      finish. Text deltas are aggregated to a single "thinking..."
- *      pulse so we don't paint the terminal with token-level noise.
- */
-/**
- * Decide whether to enable the streaming renderer.
- *
- *   - explicit=true  → ON regardless of TTY.
- *   - explicit=false → OFF regardless of TTY.
- *   - explicit=null  → ON when stderr is a TTY, OFF otherwise.
- *
- * Centralised so the CLI dispatcher and tests share one rule.
- */
-export function shouldStream(opts) {
-    if (opts.explicit === true)
-        return true;
-    if (opts.explicit === false)
-        return false;
-    return opts.isTty;
-}
-/**
- * Attach a stderr-based event renderer to the engine emitter.
- *
- * Returns a handle whose `enabled` field is true when the renderer
- * actually attached. When disabled (non-TTY or explicit-off) the
- * returned handle is a no-op so callers don't need to branch.
- */
-export function attachStreamRenderer(emitter, opts) {
-    const enabled = shouldStream({ isTty: opts.isTty, explicit: opts.explicit });
-    if (!enabled) {
-        return { enabled: false, detach: () => { } };
-    }
-    const write = opts.write ?? ((line) => process.stderr.write(line));
-    // Aggregate text deltas so we don't paint a line per token. We
-    // print one "thinking..." pulse every ~500ms while text is
-    // streaming so the operator sees the loop is alive without a wall
-    // of partial sentences.
-    let pendingTextChars = 0;
-    let lastTextPulseAt = 0;
-    // Aggregate thinking deltas the same way. Separate budget so a
-    // chatty reasoning trace doesn't blow out the visible-text counter.
-    let pendingThinkingChars = 0;
-    let lastThinkingPulseAt = 0;
-    // Cache the running tool calls so the "end" line can report a
-    // duration without forcing the producer to round-trip the start
-    // timestamp through the discriminated union.
-    const toolStartedAt = new Map();
-    const handler = (event) => {
-        switch (event.type) {
-            case 'status': {
-                // Only surface the high-signal status frames. Turn-boundary
-                // frames are noise for a live operator; the tool-level lines
-                // already tell them what's happening. Dispatch start /
-                // budget / abort frames are worth one line each.
-                const msg = event.message;
-                if (msg.startsWith('dispatch_start') ||
-                    msg.startsWith('budget') ||
-                    msg.startsWith('aborted') ||
-                    msg.startsWith('cancelled')) {
-                    write(`pugi: ${msg}\n`);
-                }
-                return;
-            }
-            case 'tool.start': {
-                toolStartedAt.set(event.callId, Date.now());
-                const argsBrief = briefArgs(event.arguments);
-                write(`pugi: tool ${event.name}(${argsBrief}) running\n`);
-                return;
-            }
-            case 'tool.end': {
-                const startedAt = toolStartedAt.get(event.callId);
-                toolStartedAt.delete(event.callId);
-                const ms = startedAt ? Date.now() - startedAt : null;
-                const glyph = event.ok ? 'ok' : 'fail';
-                const summary = (event.summary ?? '').slice(0, 80).replace(/\s+/g, ' ').trim();
-                const tail = ms !== null ? ` (${ms}ms)` : '';
-                write(`pugi: tool ${glyph}${tail}${summary ? `: ${summary}` : ''}\n`);
-                return;
-            }
-            case 'tool.delta': {
-                // Most bash tools emit a single delta with the entire stdout
-                // tail. We surface the first non-empty chunk only, capped to
-                // a single line, so the operator gets a peek without
-                // flooding.
-                const chunk = (event.chunk ?? '').replace(/\s+/g, ' ').trim();
-                if (chunk.length === 0)
-                    return;
-                const oneLine = chunk.slice(0, 80);
-                write(`pugi:   stdout: ${oneLine}\n`);
-                return;
-            }
-            case 'text.delta': {
-                pendingTextChars += (event.chunk ?? '').length;
-                const now = Date.now();
-                if (now - lastTextPulseAt >= 500 && pendingTextChars >= 40) {
-                    lastTextPulseAt = now;
-                    pendingTextChars = 0;
-                    write(`pugi: writing reply...\n`);
-                }
-                return;
-            }
-            case 'thinking.start':
-                write(`pugi: thinking...\n`);
-                lastThinkingPulseAt = Date.now();
-                return;
-            case 'thinking.delta': {
-                pendingThinkingChars += (event.chunk ?? '').length;
-                const now = Date.now();
-                if (now - lastThinkingPulseAt >= 1500 && pendingThinkingChars >= 80) {
-                    lastThinkingPulseAt = now;
-                    pendingThinkingChars = 0;
-                    write(`pugi: still thinking...\n`);
-                }
-                return;
-            }
-            case 'thinking.end':
-                // Quiet — text.delta will pick up the visible answer next.
-                return;
-            default:
-                return;
-        }
-    };
-    emitter.on('event', handler);
-    return {
-        enabled: true,
-        detach: () => {
-            emitter.off('event', handler);
-        },
-    };
-}
-/**
- * Render a tool's JSON-serialised arguments to a single-line brief.
- * Keep this very cheap — runs on every tool.start event.
- */
-function briefArgs(serialised) {
-    if (!serialised || serialised === '{}')
-        return '';
-    try {
-        const parsed = JSON.parse(serialised);
-        // Prioritise the most signal-bearing field name for known tools.
-        const path = pickStringField(parsed, ['path', 'file', 'file_path', 'target', 'cwd']);
-        if (path)
-            return path.slice(0, 60);
-        const command = pickStringField(parsed, ['command', 'cmd', 'query', 'pattern']);
-        if (command)
-            return command.slice(0, 60);
-        // Fallback — surface the first scalar field so we surface
-        // something rather than an empty string.
-        for (const [, value] of Object.entries(parsed)) {
-            if (typeof value === 'string')
-                return value.slice(0, 60);
-            if (typeof value === 'number' || typeof value === 'boolean') {
-                return String(value);
-            }
-        }
-        return '';
-    }
-    catch {
-        return serialised.slice(0, 60);
-    }
-}
-function pickStringField(obj, keys) {
-    for (const key of keys) {
-        const value = obj[key];
-        if (typeof value === 'string' && value.length > 0)
-            return value;
-    }
-    return null;
-}
-//# sourceMappingURL=stream-renderer.js.map