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

package/dist/runtime/commands/vim.js

@@ -1,140 +0,0 @@
-/**
- * — `pugi vim` top-level command + REPL slash
- * companion.
- *
- * Operator surface:
- *
- *  pugi vim                      Show current vim-mode state.
- *  pugi vim on                   Enable + persist (~/.pugi/config.json).
- *  pugi vim off                  Disable + persist (default).
- *  /vim                          Toggle from inside the REPL.
- *  /vim on                       Enable from inside the REPL.
- *  /vim off                      Disable from inside the REPL.
- *
- * The same runner backs both surfaces so the slash + the shell verb
- * stay single-sourced — operators trained on one read the same
- * payload + banner on the other.
- *
- * Exit codes:
- *  0 — show / enable / disable / toggle happy path
- *  2 — unknown subcommand (e.g. `pugi vim chaos`)
- *
- * NOTE: there are NO `--persist` flag and no workspace tier. Vim mode
- * is a single user-level preference, matching the upstream behavior note
- * that operators expect modal editing to be a body-memory trait, not
- * a per-repo concern (see `core/vim/state.ts` header).
- */
-import { resolveVimMode, setVimMode } from '../../core/vim/state.js';
-/**
- * Banner shown on enable so the operator can see the binding cheat
- * sheet without reaching for `/help`. Echoed by both surfaces.
- */
-export const VIM_ENABLED_BANNER = 'Vim mode on. Esc=normal, i=insert, :w=submit, :q=cancel.';
-/**
- * Entry point. Parses `args`, flips persistence as needed, emits the
- * payload + text via `ctx.writeOutput`, and returns the exit code.
- */
-export async function runVimCommand(args, ctx) {
-    // Validate args before reading state so a bad call never has a
-    // side-effect.
-    if (args.length > 1) {
-        const payload = {
-            command: 'vim',
-            status: 'invalid_args',
-            active: resolveVimMode({ env: ctx.env }),
-            message: `pugi vim takes at most one argument (on / off / toggle). Got: ${args.join(' ')}`,
-            attemptedArg: args.join(' '),
-        };
-        ctx.writeOutput(payload, payload.message);
-        return 2;
-    }
-    const current = resolveVimMode({ env: ctx.env });
-    const verb = args[0]?.toLowerCase() ?? '';
-    // No args → toggle (slash convention from the upstream behavior ). The
-    // CLI shell surface ALSO toggles on bare invocation so the two
-    // surfaces converge; if the operator wants the read-only show they
-    // can pipe through `pugi vim --json` or query the config directly.
-    // We surface the change as a `show` status when nothing flipped so
-    // scripts can distinguish read from write.
-    if (verb === '') {
-        const next = !current;
-        setVimMode(next, { env: ctx.env });
-        const status = next ? 'enabled' : 'disabled';
-        const message = next ? VIM_ENABLED_BANNER : 'Vim mode off.';
-        const payload = {
-            command: 'vim',
-            status,
-            active: next,
-            previous: current,
-            message,
-        };
-        ctx.writeOutput(payload, payload.message);
-        return 0;
-    }
-    if (verb === 'on' || verb === 'enable' || verb === 'true') {
-        if (current) {
-            const payload = {
-                command: 'vim',
-                status: 'unchanged',
-                active: true,
-                previous: true,
-                message: 'Vim mode already on.',
-            };
-            ctx.writeOutput(payload, payload.message);
-            return 0;
-        }
-        setVimMode(true, { env: ctx.env });
-        const payload = {
-            command: 'vim',
-            status: 'enabled',
-            active: true,
-            previous: current,
-            message: VIM_ENABLED_BANNER,
-        };
-        ctx.writeOutput(payload, payload.message);
-        return 0;
-    }
-    if (verb === 'off' || verb === 'disable' || verb === 'false') {
-        if (!current) {
-            const payload = {
-                command: 'vim',
-                status: 'unchanged',
-                active: false,
-                previous: false,
-                message: 'Vim mode already off.',
-            };
-            ctx.writeOutput(payload, payload.message);
-            return 0;
-        }
-        setVimMode(false, { env: ctx.env });
-        const payload = {
-            command: 'vim',
-            status: 'disabled',
-            active: false,
-            previous: current,
-            message: 'Vim mode off.',
-        };
-        ctx.writeOutput(payload, payload.message);
-        return 0;
-    }
-    if (verb === 'status' || verb === 'show') {
-        const payload = {
-            command: 'vim',
-            status: 'show',
-            active: current,
-            message: current ? 'Vim mode is on.' : 'Vim mode is off.',
-        };
-        ctx.writeOutput(payload, payload.message);
-        return 0;
-    }
-    const payload = {
-        command: 'vim',
-        status: 'invalid_args',
-        active: current,
-        message: `Unknown vim subcommand "${verb}". Try one of: on, off, status.`,
-        attemptedArg: verb,
-    };
-    ctx.writeOutput(payload, payload.message);
-    return 2;
-}
-//# sourceMappingURL=vim.js.map

package/dist/runtime/commands/worktree.js

@@ -1,177 +0,0 @@
-/**
- * `pugi worktree <op>` — Phase 1.
- *
- * Manual control over the scratch worktree primitive. Three subcommands:
- *
- *  pugi worktree create [branch]   # spawns `.pugi/worktrees/<uuid>`
- *  pugi worktree promote <path>    # applies the worktree's diff back to cwd
- *  pugi worktree drop <path>       # removes the worktree (idempotent)
- *
- * Output: human-readable by default, structured JSON under --json so
- * scripted callers can chain (`pugi worktree create --json | jq .path`).
- *
- * The same primitives are used by the `pugi build` and
- * `pugi review --consensus` paths internally; this surface is the
- * operator escape hatch for debugging / manual experimentation.
- *
- * Brand voice: ASCII only, no emoji, no banned words.
- */
-import { spawnSync } from 'node:child_process';
-import { resolve, sep } from 'node:path';
-import { createWorktree, dropWorktree, promoteWorktree } from '../../core/edits/worktree.js';
-/**
- * R1 fix (2026-05-26, PR r1, P2 #10): operator-facing path
- * validation. The core `promoteWorktree` / `dropWorktree` primitives
- * already gate their inputs, but mirroring the check at the CLI surface
- * gives the operator a clean error message before we even attempt the
- * git invocation (which would otherwise leak `git rev-parse HEAD` stderr).
- */
-function isUnderScratchRoot(cwd, candidate) {
-    const scratchRoot = resolve(cwd, '.pugi', 'worktrees');
-    const abs = resolve(cwd, candidate);
-    return abs.startsWith(scratchRoot + sep) && abs !== scratchRoot;
-}
-export async function runWorktreeCommand(args, opts) {
-    const [op, ...rest] = args;
-    if (!op)
-        return usage();
-    if (op === 'create') {
-        const branch = rest[0];
-        const result = createWorktree({
-            cwd: opts.cwd,
-            ...(branch ? { branch } : {}),
-        });
-        if (!result.ok) {
-            return {
-                ok: false,
-                text: opts.json
-                    ? JSON.stringify(result, null, 2)
-                    : `worktree create failed: ${result.reason}: ${result.detail}`,
-                exitCode: 1,
-            };
-        }
-        const handle = result.value;
-        return {
-            ok: true,
-            text: opts.json
-                ? JSON.stringify({ path: handle.path, baseSha: handle.baseSha }, null, 2)
-                : `worktree created: ${handle.path}\nbase: ${handle.baseSha}`,
-            exitCode: 0,
-        };
-    }
-    if (op === 'promote') {
-        const worktreePath = rest[0];
-        if (!worktreePath) {
-            return {
-                ok: false,
-                text: 'Usage: pugi worktree promote <path>',
-                exitCode: 2,
-            };
-        }
-        if (!isUnderScratchRoot(opts.cwd, worktreePath)) {
-            return {
-                ok: false,
-                text: opts.json
-                    ? JSON.stringify({
-                        ok: false,
-                        reason: 'invalid_worktree_path',
-                        detail: `worktree path must live under <cwd>/.pugi/worktrees/`,
-                    }, null, 2)
-                    : `promote failed: invalid_worktree_path: ${worktreePath} is not under .pugi/worktrees/`,
-                exitCode: 3,
-            };
-        }
-        // Resolve the worktree path's base SHA from its own git HEAD so
-        // the operator never has to remember it after `worktree create`.
-        const abs = resolve(opts.cwd, worktreePath);
-        const head = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: abs, encoding: 'utf8' });
-        if (head.status !== 0) {
-            return {
-                ok: false,
-                text: `cannot read HEAD of ${abs}: ${head.stderr.trim() || 'git rev-parse failed'}`,
-                exitCode: 1,
-            };
-        }
-        const baseSha = head.stdout.trim();
-        const result = promoteWorktree({
-            cwd: opts.cwd,
-            worktreePath: abs,
-            baseSha,
-            ...(opts.dryRun ? { dryRun: true } : {}),
-        });
-        if (!result.ok) {
-            return {
-                ok: false,
-                text: opts.json
-                    ? JSON.stringify(result, null, 2)
-                    : `promote failed: ${result.reason}: ${result.detail}`,
-                exitCode: result.reason === 'protected_file_in_worktree' ? 3 : 1,
-            };
-        }
-        const prefix = opts.dryRun ? 'dry-run: would promote' : 'promoted';
-        return {
-            ok: true,
-            text: opts.json
-                ? JSON.stringify({ filesChanged: result.value.filesChanged, dryRun: opts.dryRun ?? false }, null, 2)
-                : `${prefix} ${result.value.filesChanged} files from ${abs}`,
-            exitCode: 0,
-        };
-    }
-    if (op === 'drop') {
-        const worktreePath = rest[0];
-        if (!worktreePath) {
-            return {
-                ok: false,
-                text: 'Usage: pugi worktree drop <path>',
-                exitCode: 2,
-            };
-        }
-        if (!isUnderScratchRoot(opts.cwd, worktreePath)) {
-            return {
-                ok: false,
-                text: opts.json
-                    ? JSON.stringify({
-                        ok: false,
-                        reason: 'invalid_worktree_path',
-                        detail: `worktree path must live under <cwd>/.pugi/worktrees/`,
-                    }, null, 2)
-                    : `drop failed: invalid_worktree_path: ${worktreePath} is not under .pugi/worktrees/`,
-                exitCode: 3,
-            };
-        }
-        const abs = resolve(opts.cwd, worktreePath);
-        const result = dropWorktree(abs, opts.cwd);
-        if (!result.ok) {
-            return {
-                ok: false,
-                text: opts.json
-                    ? JSON.stringify(result, null, 2)
-                    : `drop failed: ${result.reason}: ${result.detail}`,
-                exitCode: result.reason === 'invalid_worktree_path' ? 3 : 1,
-            };
-        }
-        return {
-            ok: true,
-            text: opts.json
-                ? JSON.stringify({ dropped: abs }, null, 2)
-                : `worktree dropped: ${abs}`,
-            exitCode: 0,
-        };
-    }
-    return {
-        ok: false,
-        text: `unknown worktree operation: ${op}. Supported: create, promote, drop`,
-        exitCode: 2,
-    };
-}
-function usage() {
-    return {
-        ok: false,
-        text: 'Usage: pugi worktree <op>\n' +
-            ' pugi worktree create [branch]\n' +
-            ' pugi worktree promote <path>\n' +
-            ' pugi worktree drop <path>',
-        exitCode: 2,
-    };
-}
-//# sourceMappingURL=worktree.js.map

package/dist/runtime/commands/worktrees.js

@@ -1,155 +0,0 @@
-/**
- * `pugi worktrees <op>` — .
- *
- * Plural surface for the agent-bound worktree manager. Distinct from the
- * singular `pugi worktree <op>` which manages UUID-keyed
- * scratch worktrees for the manual `create / promote / drop` flow.
- *
- *  pugi worktrees list                 # show active agent worktrees
- *  pugi worktrees cleanup <agent-id>   # remove one
- *  pugi worktrees cleanup --all-stale  # sweep orphans + completed/failed
- *  pugi worktrees cleanup --all-stale --dry-run
- *
- * Output: human-readable by default, NDJSON envelope under --json.
- *
- * Brand voice: ASCII only, no emoji, no banned words.
- */
-import { runStaleCleanup } from '../../core/worktree-manager/cleanup.js';
-import { WorktreeManager } from '../../core/worktree-manager/manager.js';
-export async function runWorktreesCommand(args, opts) {
-    const [op, ...rest] = args;
-    if (!op)
-        return usage();
-    if (op === 'list') {
-        return runList(opts);
-    }
-    if (op === 'cleanup') {
-        return runCleanup(rest, opts);
-    }
-    return {
-        ok: false,
-        text: `unknown worktrees operation: ${op}. Supported: list, cleanup`,
-        exitCode: 2,
-    };
-}
-function runList(opts) {
-    const manager = new WorktreeManager({ cwd: opts.cwd });
-    const result = manager.list();
-    if (!result.ok) {
-        return {
-            ok: false,
-            text: opts.json
-                ? JSON.stringify(result, null, 2)
-                : `worktrees list failed: ${result.reason}: ${result.detail}`,
-            exitCode: 1,
-        };
-    }
-    const rows = result.value;
-    if (opts.json) {
-        return {
-            ok: true,
-            text: JSON.stringify({ worktrees: rows }, null, 2),
-            exitCode: 0,
-        };
-    }
-    if (rows.length === 0) {
-        return { ok: true, text: 'no agent worktrees', exitCode: 0 };
-    }
-    const lines = [];
-    lines.push('AGENT ID                   BRANCH                             GIT    PATH');
-    for (const row of rows) {
-        lines.push(`${pad(row.agentId, 28)}${pad(row.branch, 36)}${pad(row.gitTracked ? 'yes' : 'no', 8)}${row.path}`);
-    }
-    return { ok: true, text: lines.join('\n'), exitCode: 0 };
-}
-function runCleanup(args, opts) {
-    // --all-stale sweeps every classified stale entry. Otherwise the next
-    // positional arg is the agent id to remove.
-    const allStale = args.includes('--all-stale');
-    if (allStale) {
-        const report = runStaleCleanup({ cwd: opts.cwd }, opts.dryRun ? { dryRun: true } : {});
-        return formatStaleReport(report, opts);
-    }
-    const agentId = args.find((a) => !a.startsWith('--'));
-    if (!agentId) {
-        return {
-            ok: false,
-            text: 'Usage: pugi worktrees cleanup <agent-id> | --all-stale [--dry-run]',
-            exitCode: 2,
-        };
-    }
-    const manager = new WorktreeManager({ cwd: opts.cwd });
-    const result = manager.cleanup(agentId);
-    if (!result.ok) {
-        // Missing-worktree is idempotent: surface the structured note but
-        // return exit 0 so a double-cleanup in a teardown hook never trips
-        // CI. Every other failure mode (invalid id, git failure) stays
-        // exit 1.
-        return {
-            ok: false,
-            text: opts.json
-                ? JSON.stringify(result, null, 2)
-                : `cleanup failed: ${result.reason}: ${result.detail}`,
-            exitCode: result.reason === 'worktree_missing' ? 0 : 1,
-        };
-    }
-    return {
-        ok: true,
-        text: opts.json
-            ? JSON.stringify({ removed: result.value.removed }, null, 2)
-            : `worktree removed: ${result.value.removed}`,
-        exitCode: 0,
-    };
-}
-function formatStaleReport(report, opts) {
-    if (opts.json) {
-        return {
-            ok: report.errors.length === 0,
-            text: JSON.stringify(report, null, 2),
-            exitCode: report.errors.length === 0 ? 0 : 1,
-        };
-    }
-    const lines = [];
-    lines.push(`scanned: ${report.scanned} worktree(s)`);
-    if (report.removed.length > 0) {
-        lines.push(`removed: ${report.removed.length}`);
-        for (const r of report.removed)
-            lines.push(` - ${r}`);
-    }
-    if (report.preserved.length > 0) {
-        lines.push(`preserved: ${report.preserved.length}`);
-        for (const p of report.preserved)
-            lines.push(` - ${p.agentId} (${p.reason})`);
-    }
-    if (opts.dryRun) {
-        lines.push('dry-run: classifications only, nothing removed');
-        for (const c of report.classified)
-            lines.push(` - ${c.agentId}: ${c.class}`);
-    }
-    if (report.errors.length > 0) {
-        lines.push(`errors: ${report.errors.length}`);
-        for (const e of report.errors)
-            lines.push(` - ${e.agentId}: ${e.detail}`);
-    }
-    return {
-        ok: report.errors.length === 0,
-        text: lines.join('\n'),
-        exitCode: report.errors.length === 0 ? 0 : 1,
-    };
-}
-function usage() {
-    return {
-        ok: false,
-        text: 'Usage: pugi worktrees <op>\n' +
-            ' pugi worktrees list\n' +
-            ' pugi worktrees cleanup <agent-id>\n' +
-            ' pugi worktrees cleanup --all-stale [--dry-run]',
-        exitCode: 2,
-    };
-}
-function pad(s, n) {
-    if (s.length >= n)
-        return `${s.slice(0, n - 1)} `;
-    return s + ' '.repeat(n - s.length);
-}
-//# sourceMappingURL=worktrees.js.map

package/dist/runtime/deprecation-warning.js

@@ -1,69 +0,0 @@
-/**
- * Centralised deprecation warning helper (Trust Sprint item 7).
- *
- * Pugi CLI is in 0.x and we are introducing the first generation of
- * collapsed env vars. Operators with existing scripts need a clear
- * forward path without breakage. Pattern:
- *
- *   warnDeprecation('PUGI_OLD_FLAG', 'PUGI_NEW_FLAG=1', 'rationale...');
- *
- * Behaviour:
- *   - Emits ONE stderr line per (old, new) pair per process. Repeat
- *     calls for the same pair are suppressed so the operator does not
- *     see the same noise across many tool invocations in a session.
- *   - Silenced entirely when `PUGI_SUPPRESS_DEPRECATION_WARNINGS=1` is
- *     set (CI escape hatch; documented in operator-deploy-checklist).
- *   - Silenced in test runs via the standard `NODE_ENV=test` /
- *     `PUGI_TEST_MODE=1` checks so spec output stays clean.
- *
- * Brand rule: no AI attribution, no em dashes. Copy stays short and
- * actionable so the operator can paste the new form into their script
- * in one read.
- */
-const warnedPairs = new Set();
-/**
- * Reset the warned-once memo. Tests call this between cases so the
- * one-warning-per-pair guard does not bleed across specs.
- */
-export function resetDeprecationWarningsForTest() {
-    warnedPairs.clear();
-}
-/**
- * Emit a single deprecation warning to stderr.
- *
- * @param oldName  literal name of the deprecated env/flag the operator
- *                 is using (e.g. 'PUGI_MCP_EXEC_ENABLED').
- * @param newName  literal name of the replacement env/flag, including
- *                 the form an operator should type (e.g.
- *                 'PUGI_MCP_ORCHESTRATOR=1').
- * @param hint     optional one-line rationale appended after the
- *                 redirect. Keep under 80 chars; multi-line wrapping
- *                 is the operator's terminal job, not ours.
- */
-export function warnDeprecation(oldName, newName, hint) {
-    if (isSilenced())
-        return;
-    const key = `${oldName}->${newName}`;
-    if (warnedPairs.has(key))
-        return;
-    warnedPairs.add(key);
-    const baseLine = `pugi: deprecation: ${oldName} is deprecated; prefer ${newName}.`;
-    const line = hint && hint.length > 0 ? `${baseLine} ${hint}` : baseLine;
-    process.stderr.write(`${line}\n`);
-}
-/**
- * Internal helper. Lifted so tests can mock or override.
- */
-function isSilenced() {
-    const env = process.env;
-    if (env.PUGI_SUPPRESS_DEPRECATION_WARNINGS === '1')
-        return true;
-    if (env.PUGI_TEST_MODE === '1')
-        return true;
-    // NODE_ENV=test is set by `node --test`'s harness and by the
-    // pugi-cli vitest workflows.
-    if (env.NODE_ENV === 'test')
-        return true;
-    return false;
-}
-//# sourceMappingURL=deprecation-warning.js.map

package/dist/runtime/engine-exit-code.js

@@ -1,50 +0,0 @@
-/**
- * engine-exit-code - Phase 1 verification gate invariant (PUGI-299).
- *
- * The runtime resolves the CLI exit code from the engine outcome via a
- * deterministic ladder. Extracted from `cli.ts` so the invariant is
- * exercisable from a focused spec without mounting the 9700-LOC entry
- * module.
- *
- * Contract (in priority order):
- *  1. `status === 'needs_verification'`    → exit 2
- *  2. `unverifiedReason === 'verification_command_failed'` → exit 1
- *  3. `verificationFailures` is a non-empty array          → exit 1
- *  4. `verified === false && status === 'done'`            → exit 2
- *  5. `status === 'done'`                                   → exit 0
- *  6. `status === 'failed'`                                 → exit 8
- *  7. `status === 'blocked'` (catch-all)                    → exit 9
- *
- * The rule fires defensively: rules 3 + 4 cover producer bugs where a
- * future engine adapter forgets to flip `unverifiedReason` or
- * downgrade the status to `needs_verification`. Today
- * `computeVerificationOutcome` always synthesises one of the two,
- * but the invariant locks the contract.
- */
-export const ENGINE_EXIT_CODES = {
-    done: 0,
-    failed: 8,
-    blocked: 9,
-    engine_unavailable: 1,
-    needs_verification: 2,
-};
-export function resolveEngineExitCode(result) {
-    if (result.status === 'needs_verification') {
-        return ENGINE_EXIT_CODES.needs_verification;
-    }
-    if (result.unverifiedReason === 'verification_command_failed') {
-        return 1;
-    }
-    if (Array.isArray(result.verificationFailures) && result.verificationFailures.length > 0) {
-        return 1;
-    }
-    if (result.verified === false && result.status === 'done') {
-        return ENGINE_EXIT_CODES.needs_verification;
-    }
-    if (result.status === 'done')
-        return ENGINE_EXIT_CODES.done;
-    if (result.status === 'failed')
-        return ENGINE_EXIT_CODES.failed;
-    return ENGINE_EXIT_CODES.blocked;
-}
-//# sourceMappingURL=engine-exit-code.js.map