@pugi/cli 0.1.0-beta.4 → 0.1.0-beta.40

package/dist/core/transport/version-interceptor.js

@@ -0,0 +1,166 @@
+/**
+ * Pugi CLI ↔ admin-api version handshake — CLI-side interceptor.
+ *
+ * Wraps the engine HTTP transport (and, via the same helpers, any
+ * other `fetch` call the CLI makes to admin-api) so the CLI:
+ *
+ *   1. Sends `X-Pugi-Cli-Version: <installed semver>` on every
+ *      outbound request. The server middleware
+ *      (`apps/admin-api/src/runtime/cli-version.middleware.ts`) reads
+ *      this header and decides whether to honour, soft-warn, or 426.
+ *
+ *   2. Inspects every response for:
+ *      - `X-Pugi-Cli-Upgrade-Recommended` → cache the server's
+ *        recommendation so `UpdateBanner` can compare it against the
+ *        npm-registry poll and show the operator the higher of the two.
+ *      - `X-Pugi-Server-Version` → cache for diagnostics
+ *        (`pugi doctor --json`).
+ *
+ *   3. Throws `PugiCliUpgradeRequiredError` when the server returns
+ *      HTTP 426. The top-level catch in `index.ts` / `runtime/cli.ts`
+ *      renders a clean upgrade banner + `process.exit(1)`.
+ *
+ * # Design: pure helpers, not a callable wrapper
+ *
+ * Wrapping fetch as a higher-order function would require every
+ * transport call site to opt in via `interceptedFetch(...)`. Instead
+ * we expose three small helpers that the existing transport classes
+ * (currently just `AnvilEngineLoopClient`) call inline:
+ *
+ *   - `injectClientVersionHeader(headers)` — adds the X-Pugi-Cli-Version
+ *     entry to an outbound header bag.
+ *   - `inspectVersionResponse(response)` — reads recommended/server
+ *     headers, updates the module cache. Returns void.
+ *   - `assertNotUpgradeRequired(response)` — if status is 426, parses
+ *     the JSON body and throws `PugiCliUpgradeRequiredError`. Returns
+ *     void otherwise.
+ *
+ * That layout keeps the spec tests trivially focused on each branch and
+ * gives future SSE callers (engine-stream EventSource) the same hooks
+ * without touching the fetch wrapper indirection.
+ */
+import { PUGI_CLI_UPGRADE_RECOMMENDED_HEADER, PUGI_CLI_VERSION_HEADER, PUGI_SERVER_VERSION_HEADER, } from '../../runtime/version.js';
+/**
+ * Thrown when admin-api responds with HTTP 426 Upgrade Required. The
+ * top-level CLI catch (see `runtime/cli.ts`) renders this with the
+ * operator-friendly upgrade banner.
+ *
+ * Mirrors the server-side `CliUpgradeRequiredBody` shape; populated
+ * from the response JSON when present and from the request context
+ * (installed version) when the body parse fails.
+ */
+export class PugiCliUpgradeRequiredError extends Error {
+    code = 'cli_upgrade_required';
+    installedVersion;
+    minClientVersion;
+    recommendedVersion;
+    upgradeCommand;
+    upgradeUrl;
+    constructor(details) {
+        super(details.message ??
+            `Pugi CLI ${details.installedVersion} is below the server minimum ${details.minClientVersion}. Upgrade with: ${details.upgradeCommand}`);
+        this.name = 'PugiCliUpgradeRequiredError';
+        this.installedVersion = details.installedVersion;
+        this.minClientVersion = details.minClientVersion;
+        this.recommendedVersion = details.recommendedVersion;
+        this.upgradeCommand = details.upgradeCommand;
+        this.upgradeUrl = details.upgradeUrl;
+    }
+}
+/**
+ * Module-level cache of the most recent server-recommended version.
+ * Read by `UpdateBanner` (via `getCachedServerRecommendation`) when
+ * computing the version it shows the operator. Kept in module scope
+ * (not class state) because both the engine client and the banner live
+ * in different module subtrees and there's no shared service container
+ * to thread DI through.
+ */
+let cachedServerRecommendation = null;
+let cachedServerVersion = null;
+/**
+ * UpdateBanner reads this to merge with its npm-registry poll. Returns
+ * `null` when no Pugi response has been seen yet (very first REPL
+ * launch before the engine has been called).
+ */
+export function getCachedServerRecommendation() {
+    return cachedServerRecommendation;
+}
+/**
+ * `pugi doctor --json` reads this for the server-version diagnostic
+ * field. Returns `null` when no response has been seen yet.
+ */
+export function getCachedServerVersion() {
+    return cachedServerVersion;
+}
+/**
+ * Test seam — reset the cache between specs so cross-test leakage
+ * doesn't make assertions flaky. Not part of the public CLI surface.
+ */
+export function __resetVersionCacheForTests() {
+    cachedServerRecommendation = null;
+    cachedServerVersion = null;
+}
+/**
+ * Mutate an outbound header bag to add the CLI version. Accepts both
+ * the plain-object header shape that `fetch` uses and Headers
+ * instances. Returns the same bag for chaining.
+ *
+ * Header names go in canonical capitalization since some
+ * test/intermediary tools (mitmproxy, charles) display the exact case
+ * the client sent rather than normalising to lowercase.
+ */
+export function injectClientVersionHeader(headers, cliVersion) {
+    if (headers instanceof Headers) {
+        headers.set(PUGI_CLI_VERSION_HEADER, cliVersion);
+        return headers;
+    }
+    headers[PUGI_CLI_VERSION_HEADER] = cliVersion;
+    return headers;
+}
+/**
+ * Inbound-header inspection. Reads `X-Pugi-Cli-Upgrade-Recommended`
+ * and `X-Pugi-Server-Version` from the response and updates the
+ * module-level cache. Caller passes a `headers.get(...)` shim so this
+ * helper stays decoupled from the concrete response type — `Response`,
+ * `undici.Dispatcher.ResponseData`, or a stub in tests.
+ */
+export function inspectVersionResponse(getHeader) {
+    const recommended = getHeader(PUGI_CLI_UPGRADE_RECOMMENDED_HEADER);
+    if (typeof recommended === 'string' && recommended.length > 0) {
+        cachedServerRecommendation = recommended;
+    }
+    const serverVersion = getHeader(PUGI_SERVER_VERSION_HEADER);
+    if (typeof serverVersion === 'string' && serverVersion.length > 0) {
+        cachedServerVersion = serverVersion;
+    }
+}
+/**
+ * If the response is HTTP 426, throw `PugiCliUpgradeRequiredError`.
+ * Otherwise return void. Caller is responsible for already having
+ * read the response body — pass it in so we can parse the
+ * documented JSON shape without consuming the stream a second time.
+ *
+ * `installedFallback` is used when the response body doesn't carry
+ * `installedVersion` (e.g. CDN-injected 426). Should be the CLI's own
+ * PUGI_CLI_VERSION constant.
+ */
+export function assertNotUpgradeRequired(status, bodyText, installedFallback) {
+    if (status !== 426)
+        return;
+    let parsed = {};
+    try {
+        parsed = JSON.parse(bodyText);
+    }
+    catch {
+        // Body wasn't JSON — fall back to constants below.
+    }
+    throw new PugiCliUpgradeRequiredError({
+        installedVersion: parsed.installedVersion ?? installedFallback,
+        minClientVersion: parsed.minClientVersion ?? 'unknown',
+        recommendedVersion: parsed.recommendedVersion ?? 'unknown',
+        upgradeCommand: parsed.upgradeCommand ?? 'npm i -g @pugi/cli@latest',
+        upgradeUrl: parsed.upgradeUrl ?? 'https://www.npmjs.com/package/@pugi/cli',
+        message: parsed.message,
+    });
+}
+//# sourceMappingURL=version-interceptor.js.map

package/dist/core/vim/keymap.js

@@ -0,0 +1,288 @@
+/**
+ * Leak L26 (2026-05-27) — Vim-style modal editing keymap.
+ *
+ * Pure, data-only motion + edit primitives. The TUI layer
+ * (`tui/vim-input.tsx`) maps Ink key events onto these helpers so the
+ * keymap stays trivially testable and the React component stays free
+ * of motion arithmetic.
+ *
+ * Scope (matches the leak research surface for Claude Code `/vim`):
+ *
+ *   Normal-mode motions
+ *     h / j / k / l        → left / down / up / right (j/k are
+ *                            no-ops on a single-line buffer; we keep
+ *                            the kind in the discriminator so the
+ *                            multi-line buffer follow-up can extend
+ *                            without churning the call sites).
+ *     0 / $                → line start / line end
+ *     w / b                → word forward / word backward
+ *
+ *   Normal-mode edits
+ *     x                    → delete the char under the cursor
+ *     dd                   → delete the entire line (clears the buffer
+ *                            for the single-line REPL prompt)
+ *     i / a                → enter insert mode (`a` advances cursor by
+ *                            one column first, capped at line length)
+ *
+ *   Ex-line commands (typed after `:` in normal mode)
+ *     :w                   → submit current buffer (same as Enter in
+ *                            insert mode)
+ *     :q                   → clear buffer + return to prompt (no
+ *                            submission)
+ *
+ *   Mode transitions
+ *     Esc                  → return to normal mode
+ *     i / a in normal      → insert mode
+ *
+ * The motion helpers return both the new cursor position AND a
+ * structured discriminator so the TUI layer can react (e.g. animate
+ * the caret, log an undo entry, etc.) without re-parsing the key.
+ *
+ * The keymap is intentionally NOT a full vim implementation. We model
+ * just the subset that maps cleanly onto a single-line input buffer +
+ * the four REPL verbs (submit / cancel / accept-insert / leave-insert).
+ * Counts (`3dd`, `5j`), registers, marks, search (`/pattern`), visual
+ * mode, undo/redo, and macros are explicitly out of scope and left
+ * for a follow-up sprint once the single-line surface is shipped.
+ */
+export const PENDING_NONE = { kind: 'none' };
+/**
+ * Whitespace classifier used by `w` / `b`. Matches vim's default
+ * "word" classification loosely — treat any non-whitespace, non-
+ * punctuation byte as a word character; collapse runs.
+ *
+ * We DELIBERATELY do not split on punctuation the way vim's `w`/`b`
+ * do (`hello-world` is two words in vim but one here). The REPL
+ * brief is prose-heavy and operators expect `w` to skip whole tokens
+ * — splitting on punctuation surprised every internal tester.
+ */
+function isWordChar(ch) {
+    return /[^\s]/.test(ch);
+}
+/**
+ * Move cursor forward by one word: skip the current run of word
+ * chars, then skip the run of whitespace, land on the first char of
+ * the next word. Clamps at `line.length` so end-of-line is safe.
+ */
+export function wordForward(line, cursor) {
+    if (cursor >= line.length)
+        return line.length;
+    let i = cursor;
+    // Skip current word chars (if we're on one).
+    while (i < line.length && isWordChar(line[i] ?? ''))
+        i++;
+    // Skip whitespace gap.
+    while (i < line.length && !isWordChar(line[i] ?? ''))
+        i++;
+    return i;
+}
+/**
+ * Move cursor backward by one word: step back over whitespace, then
+ * step back over the previous word. Clamps at 0.
+ */
+export function wordBackward(line, cursor) {
+    if (cursor <= 0)
+        return 0;
+    let i = cursor - 1;
+    // Skip whitespace behind cursor.
+    while (i > 0 && !isWordChar(line[i] ?? ''))
+        i--;
+    // Skip the word until we hit whitespace or start.
+    while (i > 0 && isWordChar(line[i - 1] ?? ''))
+        i--;
+    return i;
+}
+/**
+ * Single-character delete under the cursor (`x`). When the cursor sits
+ * past end-of-line (legal in insert mode) we no-op.
+ *
+ * The cursor stays at the same offset after the splice unless the
+ * deleted char was the trailing one — in which case we step back so
+ * the caret does not sit past EOL.
+ */
+function deleteCharUnder(line, cursor) {
+    if (cursor < 0 || cursor >= line.length)
+        return { line, cursor };
+    const next = line.slice(0, cursor) + line.slice(cursor + 1);
+    const nextCursor = cursor >= next.length ? Math.max(0, next.length - (next.length === 0 ? 0 : 1)) : cursor;
+    // Subtle: when the deletion empties the buffer we want cursor=0,
+    // NOT length-1=−1. The Math.max above guards it but spell it out.
+    return { line: next, cursor: next.length === 0 ? 0 : nextCursor };
+}
+/**
+ * Apply a normal-mode keystroke and return the new buffer + cursor +
+ * mode + pending state. Pure — no side effects. The TUI is the only
+ * caller; tests exercise this directly.
+ */
+export function handleNormalKey(input) {
+    const { line, cursor, pending, ch } = input;
+    // Esc resets any in-flight multi-key sequence and re-asserts normal
+    // mode (we stay in normal — the caller invoked us BECAUSE we are in
+    // normal, but a stale `pending=d` should not survive an Esc).
+    if (input.escape) {
+        return {
+            result: { kind: 'noop', cursor, line, mode: 'normal' },
+            pending: PENDING_NONE,
+        };
+    }
+    // ─── Ex-line composition ───────────────────────────────────────
+    // Once `:` has been pressed we accumulate keystrokes into the
+    // pending buffer until Enter (commit) or Esc (cancel, handled
+    // above). Backspace shortens the buffer; any other char extends.
+    if (pending.kind === 'ex') {
+        if (input.enter) {
+            const cmd = pending.buffer;
+            if (cmd === 'w') {
+                return {
+                    result: { kind: 'submit', cursor, line, mode: 'normal', payload: line },
+                    pending: PENDING_NONE,
+                };
+            }
+            if (cmd === 'q') {
+                return {
+                    result: { kind: 'cancel', cursor: 0, line: '', mode: 'normal' },
+                    pending: PENDING_NONE,
+                };
+            }
+            // Unknown ex command — drop silently. The TUI may surface a
+            // dim hint but the keymap stays narrow (only `:w` / `:q` are
+            // contractual today).
+            return {
+                result: { kind: 'noop', cursor, line, mode: 'normal' },
+                pending: PENDING_NONE,
+            };
+        }
+        if (input.backspace) {
+            const nextBuf = pending.buffer.slice(0, -1);
+            if (nextBuf.length === 0) {
+                // Operator backspaced past `:` — exit ex composition.
+                return {
+                    result: { kind: 'noop', cursor, line, mode: 'normal' },
+                    pending: PENDING_NONE,
+                };
+            }
+            return {
+                result: { kind: 'noop', cursor, line, mode: 'normal' },
+                pending: { kind: 'ex', buffer: nextBuf },
+            };
+        }
+        if (ch.length > 0) {
+            return {
+                result: { kind: 'noop', cursor, line, mode: 'normal' },
+                pending: { kind: 'ex', buffer: pending.buffer + ch },
+            };
+        }
+        return {
+            result: { kind: 'noop', cursor, line, mode: 'normal' },
+            pending,
+        };
+    }
+    // ─── Single-shot bindings ──────────────────────────────────────
+    switch (ch) {
+        case 'i':
+            return {
+                result: { kind: 'mode', cursor, line, mode: 'insert' },
+                pending: PENDING_NONE,
+            };
+        case 'a': {
+            // `a` = append: advance cursor by one (capped) then enter
+            // insert. Matches vim semantics for the single-line case.
+            const next = Math.min(line.length, cursor + 1);
+            return {
+                result: { kind: 'mode', cursor: next, line, mode: 'insert' },
+                pending: PENDING_NONE,
+            };
+        }
+        case 'h':
+            return {
+                result: { kind: 'move', cursor: Math.max(0, cursor - 1), line, mode: 'normal' },
+                pending: PENDING_NONE,
+            };
+        case 'l':
+            return {
+                result: { kind: 'move', cursor: Math.min(line.length, cursor + 1), line, mode: 'normal' },
+                pending: PENDING_NONE,
+            };
+        case 'j':
+        case 'k':
+            // Single-line buffer — j/k are inert today. Returning a `move`
+            // keeps the discriminator consistent; the multi-line follow-up
+            // will compute a real new offset here.
+            return {
+                result: { kind: 'move', cursor, line, mode: 'normal' },
+                pending: PENDING_NONE,
+            };
+        case '0':
+            return {
+                result: { kind: 'move', cursor: 0, line, mode: 'normal' },
+                pending: PENDING_NONE,
+            };
+        case '$':
+            return {
+                result: { kind: 'move', cursor: line.length, line, mode: 'normal' },
+                pending: PENDING_NONE,
+            };
+        case 'w':
+            return {
+                result: { kind: 'move', cursor: wordForward(line, cursor), line, mode: 'normal' },
+                pending: PENDING_NONE,
+            };
+        case 'b':
+            return {
+                result: { kind: 'move', cursor: wordBackward(line, cursor), line, mode: 'normal' },
+                pending: PENDING_NONE,
+            };
+        case 'x': {
+            const { line: nextLine, cursor: nextCursor } = deleteCharUnder(line, cursor);
+            return {
+                result: { kind: 'edit', cursor: nextCursor, line: nextLine, mode: 'normal' },
+                pending: PENDING_NONE,
+            };
+        }
+        case 'd': {
+            // First `d` arms the dd sequence; second `d` commits the line
+            // delete. Any other key intervenes the sequence collapses
+            // (handled below in the fall-through path).
+            if (pending.kind === 'd') {
+                return {
+                    result: { kind: 'edit', cursor: 0, line: '', mode: 'normal' },
+                    pending: PENDING_NONE,
+                };
+            }
+            return {
+                result: { kind: 'noop', cursor, line, mode: 'normal' },
+                pending: { kind: 'd' },
+            };
+        }
+        case ':':
+            return {
+                result: { kind: 'noop', cursor, line, mode: 'normal' },
+                pending: { kind: 'ex', buffer: '' },
+            };
+        default:
+            // Unknown binding in normal mode — drop the keystroke + reset
+            // any pending sequence so a stale `d` does not silently arm a
+            // future delete after the operator wandered through unbound
+            // keys.
+            return {
+                result: { kind: 'noop', cursor, line, mode: 'normal' },
+                pending: PENDING_NONE,
+            };
+    }
+}
+/**
+ * Tiny helper exposed for the TUI so the banner / status line can
+ * render the active pending state without re-implementing the
+ * discriminator switch.
+ */
+export function describePending(pending) {
+    switch (pending.kind) {
+        case 'none':
+            return '';
+        case 'd':
+            return 'd';
+        case 'ex':
+            return `:${pending.buffer}`;
+    }
+}
+//# sourceMappingURL=keymap.js.map

package/dist/core/vim/state.js

@@ -0,0 +1,92 @@
+/**
+ * Leak L26 (2026-05-27) — Vim mode preference persistence.
+ *
+ * Single-tier storage (user-only, `~/.pugi/config.json`):
+ *
+ *   `{ ..., "vimMode": true }`
+ *
+ * The leak research shows Claude Code persists `/vim` as a user-level
+ * preference (not per-workspace) — vim-style editing is a body-memory
+ * trait of the operator, not a per-repo concern. We match that.
+ *
+ * Reader tolerances mirror `core/output-style/state.ts`:
+ *   - missing file        → returns `false` (vim mode off, the default)
+ *   - empty file          → returns `false`
+ *   - malformed JSON      → returns `false` (REPL must not crash on a
+ *                            hand-edited config)
+ *   - non-boolean         → returns `false`
+ *
+ * Writer is a read-modify-write — neighbouring keys (`outputStyle`,
+ * `permissionMode`, …) survive a vim-mode flip.
+ *
+ * File mode 0o600 mirrors `core/output-style/state.ts` so the same
+ * config does not silently downgrade its permission bits depending on
+ * which helper last touched it.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+/**
+ * Env override for `~/.pugi`. Re-uses the same `PUGI_HOME` knob as
+ * the output-style helpers so test sandboxes are uniform.
+ */
+export const PUGI_HOME_ENV = 'PUGI_HOME';
+/** Default when the file is missing / malformed / does not set the key. */
+export const VIM_MODE_DEFAULT = false;
+/**
+ * Read the persisted vim-mode preference. Pure read, never throws —
+ * every IO failure path degrades to `VIM_MODE_DEFAULT`.
+ */
+export function resolveVimMode(io = {}) {
+    const config = readConfigFile(userConfigPath(io.env ?? process.env));
+    return typeof config.vimMode === 'boolean' ? config.vimMode : VIM_MODE_DEFAULT;
+}
+/**
+ * Write the vim-mode preference. Read-modify-write so neighbouring
+ * config keys survive (`outputStyle`, `permissionMode`, …).
+ */
+export function setVimMode(value, io = {}) {
+    const path = userConfigPath(io.env ?? process.env);
+    const config = readConfigFile(path);
+    config.vimMode = value;
+    writeConfigFile(path, config);
+}
+/**
+ * Path resolver exported for the spec; production callers should use
+ * `resolveVimMode` / `setVimMode`.
+ */
+export function userConfigPath(env = process.env) {
+    const home = env[PUGI_HOME_ENV] ?? resolve(homedir(), '.pugi');
+    return resolve(home, 'config.json');
+}
+function readConfigFile(path) {
+    if (!existsSync(path))
+        return {};
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return {};
+    }
+    if (raw.trim().length === 0)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return {};
+    return parsed;
+}
+function writeConfigFile(path, config) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+}
+//# sourceMappingURL=state.js.map

package/dist/index.js

@@ -1,6 +1,34 @@
 #!/usr/bin/env node
 import { runCli } from './runtime/cli.js';
+import { PugiCliUpgradeRequiredError } from './core/transport/version-interceptor.js';
 runCli(process.argv.slice(2)).catch((error) => {
+    // PR-CLI-SERVER-VERSION-HANDSHAKE (#225). When the admin-api returns
+    // 426 Upgrade Required, the engine transport throws a typed
+    // PugiCliUpgradeRequiredError. Render an operator-friendly banner
+    // (vs. the bland `pugi: <message>` default) so the upgrade command
+    // is obvious + copy-pasteable. Plain console.error rather than Ink
+    // here because the error may surface during one-shot commands where
+    // no Ink renderer is mounted (REPL paths catch via runtime/cli.ts).
+    if (error instanceof PugiCliUpgradeRequiredError) {
+        const lines = [
+            '',
+            'Pugi CLI upgrade required',
+            '',
+            `  Your installed version: ${error.installedVersion}`,
+            `  Server requires minimum: ${error.minClientVersion}`,
+            `  Latest recommended:     ${error.recommendedVersion}`,
+            '',
+            `  Upgrade: ${error.upgradeCommand}`,
+            `  Docs:    ${error.upgradeUrl}`,
+            '',
+            '  Until you upgrade, the server will reject your requests.',
+            '  This protects you from silent protocol-drift bugs.',
+            '',
+        ];
+        console.error(lines.join('\n'));
+        process.exitCode = 1;
+        return;
+    }
     const message = error instanceof Error ? error.message : String(error);
     console.error(`pugi: ${message}`);
     process.exitCode = 1;