@pugi/cli 0.1.0-beta.10 → 0.1.0-beta.100

package/dist/runtime/commands/worktrees.js

@@ -0,0 +1,155 @@
+/**
+ * `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

@@ -0,0 +1,69 @@
+/**
+ * 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

@@ -0,0 +1,50 @@
+/**
+ * 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

package/dist/runtime/headless-repl.js

@@ -0,0 +1,195 @@
+/**
+ * Headless REPL — `pugi --headless` .
+ *
+ * Long-form rationale lives in the spec PR; the short version: every
+ * CLI publish gets manually smoke-tested today (CEO directive
+ * `feedback_live_console_test_every_publish`) and that toil must be
+ * automated. `pugi --headless` is the I/O surface that lets a scripted
+ * harness drive Pugi multi-turn — one stdin line in, one or more JSON
+ * envelopes out on stdout, exit when stdin closes. This is the
+ * machine-facing peer to the human-facing Ink REPL.
+ *
+ * Envelope shape (Phase 1):
+ *
+ *  { "kind": "user-turn"  | "persona-turn" | "tool-call" | "error"
+ *          | "session-start" | "session-end" | "system",
+ *    "body": "<string>",
+ *    "ts":  <epoch ms> }
+ *
+ * One JSON object per line. Stdout stays pure envelopes; stderr gets
+ * any human-readable trace. Discipline mirrors the existing
+ * `runHeadlessPrint` in `headless.ts`.
+ *
+ * Phase 1 engine wiring — the headless REPL emits the user-turn
+ * envelope verbatim, then asks the engine adapter for ONE turn, then
+ * emits the persona-turn / tool-call envelopes. Multi-turn state is
+ * accumulated in a single in-process session so consecutive lines see
+ * the same persona history. When a credential is absent (a common CI
+ * state) we fall through to a deterministic stub responder so the
+ * smoke harness can still exercise the I/O contract WITHOUT requiring
+ * an api.pugi.io reachability dependency.
+ */
+import { createInterface } from 'node:readline';
+import { resolve as resolvePath } from 'node:path';
+import { resolveActiveCredential } from '../core/credentials.js';
+/**
+ * Run the headless REPL loop. Returns the desired process exit code:
+ *
+ *  0 Stdin closed cleanly after at least one successful turn.
+ *  0 Stdin closed with no input (empty pipe — harmless, exit clean).
+ *  1 Fatal error from the turn handler.
+ *
+ * The caller (cli.ts) sets `process.exitCode`; we never call
+ * `process.exit` so an embedded driver can reuse the function.
+ */
+export async function runHeadlessRepl(opts) {
+    const cwd = resolvePath(opts.cwd);
+    const stdoutWrite = opts.stdoutWrite ?? ((chunk) => process.stdout.write(chunk));
+    const stderrWrite = opts.stderrWrite ?? ((chunk) => process.stderr.write(chunk));
+    const now = opts.now ?? Date.now;
+    const turnHandler = opts.turnHandler ?? buildDefaultTurnHandler();
+    const stdin = opts.stdin ?? process.stdin;
+    emit(stdoutWrite, {
+        kind: 'session-start',
+        body: JSON.stringify({ cwd, cliVersion: 'phase1' }),
+        ts: now(),
+    });
+    const rl = createInterface({
+        input: stdin,
+        crlfDelay: Infinity,
+        terminal: false,
+    });
+    let turnIndex = 0;
+    let fatal = false;
+    for await (const rawLine of rl) {
+        const line = rawLine.replace(/\r$/, '');
+        if (line.length === 0)
+            continue;
+        emit(stdoutWrite, {
+            kind: 'user-turn',
+            body: line,
+            ts: now(),
+        });
+        try {
+            const out = await turnHandler({ line, turnIndex, cwd });
+            for (const env of out) {
+                emit(stdoutWrite, { kind: env.kind, body: env.body, ts: now() });
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            emit(stdoutWrite, {
+                kind: 'error',
+                body: JSON.stringify({ message }),
+                ts: now(),
+            });
+            stderrWrite(`pugi --headless: turn handler threw: ${message}\n`);
+            fatal = true;
+            break;
+        }
+        turnIndex += 1;
+    }
+    emit(stdoutWrite, {
+        kind: 'session-end',
+        body: JSON.stringify({ turns: turnIndex }),
+        ts: now(),
+    });
+    return fatal ? 1 : 0;
+}
+/**
+ * Emit a single envelope to stdout. Always terminates with `\n` so a
+ * line-buffered reader (the smoke runner, jq, etc.) sees each
+ * envelope atomically.
+ */
+function emit(write, envelope) {
+    write(`${JSON.stringify(envelope)}\n`);
+}
+/**
+ * Build the default turn handler. When a Pugi credential is resolvable
+ * we'll plumb to the engine adapter in Phase 2; for Phase 1 the
+ * default responder is a deterministic stub. Smoke scenarios that
+ * exercise the engine path use a Phase-2-only flag (`PUGI_HEADLESS_LIVE=1`)
+ * to opt into the real engine; the default keeps CI offline-safe.
+ */
+function buildDefaultTurnHandler() {
+    const credential = resolveActiveCredential();
+    if (credential && process.env.PUGI_HEADLESS_LIVE === '1') {
+        // Phase 2: route through `NativePugiEngineAdapter` here. Left as a
+        // stub so the Phase 1 PR stays narrowly scoped to the I/O surface.
+        // The smoke corpus does NOT exercise this branch in Phase 1.
+        return stubResponder('live engine path not yet wired (Phase 2)');
+    }
+    return stubResponder('pugi headless stub: no credential or PUGI_HEADLESS_LIVE!=1; echoing input');
+}
+/**
+ * Tiny deterministic responder used by Phase 1 smoke tests. Echoes the
+ * input back as a `persona-turn` envelope with a stable prefix so
+ * scenarios can author assertions against it. The contract is:
+ *
+ *  - Input "ты кто?"               → persona-turn "Pugi: ты кто? (stub)"
+ *  - Input "create FILE with content X"
+ *                                   → tool-call Write file=FILE +
+ *                                     persona-turn "Pugi: wrote FILE"
+ *  - Any other input               → persona-turn "Pugi: ...(stub)"
+ *
+ * Real engine routing is Phase 2. The stub exists to validate the
+ * envelope contract end-to-end in CI without depending on api.pugi.io.
+ */
+function stubResponder(banner) {
+    return async (input) => {
+        const text = input.line.trim();
+        const envelopes = [];
+        const createMatch = /^create\s+(\S+)\s+with\s+content\s+['"]([^'"]+)['"]\s*$/i.exec(text);
+        if (createMatch) {
+            const file = createMatch[1] ?? 'unknown';
+            const body = createMatch[2] ?? '';
+            const { writeFileSync, mkdirSync } = await import('node:fs');
+            const { dirname } = await import('node:path');
+            const absolute = resolvePath(input.cwd, file);
+            try {
+                mkdirSync(dirname(absolute), { recursive: true });
+                writeFileSync(absolute, body, 'utf8');
+            }
+            catch (error) {
+                envelopes.push({
+                    kind: 'error',
+                    body: JSON.stringify({
+                        message: `write failed: ${error.message}`,
+                    }),
+                });
+                return envelopes;
+            }
+            envelopes.push({
+                kind: 'tool-call',
+                body: JSON.stringify({
+                    tool: 'Write',
+                    args: { file, content: body },
+                }),
+            });
+            envelopes.push({
+                kind: 'persona-turn',
+                body: `Pugi: wrote ${file}`,
+            });
+            return envelopes;
+        }
+        if (/^ты\s+кто/i.test(text) || /^who\s+are\s+you/i.test(text)) {
+            envelopes.push({
+                kind: 'persona-turn',
+                body: 'Pugi: я Pugi, твой co-pilot. (Пуджи, stub)',
+            });
+            return envelopes;
+        }
+        envelopes.push({
+            kind: 'persona-turn',
+            body: `Pugi: ${text} (stub)`,
+        });
+        // One-time banner on the first turn so operators see why the stub
+        // is firing. Suppressed on subsequent turns to keep the envelope
+        // stream noise-free.
+        if (input.turnIndex === 0) {
+            envelopes.push({ kind: 'system', body: banner });
+        }
+        return envelopes;
+    };
+}
+//# sourceMappingURL=headless-repl.js.map