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

package/dist/runtime/commands/delegate.js

@@ -6,13 +6,20 @@
  * handlers table) does not need a try/catch wrapper.
  */
 export async function runDelegateCommand(args, ctx) {
-    const slug = args[0];
-    const brief = args.slice(1).join(' ').trim();
+    // Extract the optional `--wait` flag from positional args. Accept it
+    // in any position so `pugi delegate --wait dev "..."` and
+    // `pugi delegate dev "..." --wait` both work; positional ordering of
+    // slug + brief is preserved by filtering the flag out before the
+    // slug/brief split (Claude P2 fix 2026-05-25).
+    const wait = args.some((a) => a === '--wait');
+    const positional = args.filter((a) => a !== '--wait');
+    const slug = positional[0];
+    const brief = positional.slice(1).join(' ').trim();
     if (!slug || !brief) {
         ctx.writeOutput({
             ok: false,
-            error: 'Usage: pugi delegate <persona-slug> "<one-sentence brief>"',
-        }, 'Usage: pugi delegate <persona-slug> "<one-sentence brief>"');
+            error: 'Usage: pugi delegate [--wait] <persona-slug> "<one-sentence brief>"',
+        }, 'Usage: pugi delegate [--wait] <persona-slug> "<one-sentence brief>"');
         process.exitCode = 2;
         return;
     }
@@ -47,14 +54,66 @@ export async function runDelegateCommand(args, ctx) {
         brief,
     });
     switch (result.status) {
-        case 'ok':
-            ctx.writeOutput({
-                ok: true,
-                sessionId: opened.sessionId,
-                dispatchId: result.response.dispatchId,
-                personaSlug: result.response.personaSlug,
-            }, `dispatched ${result.response.personaSlug} (dispatchId=${result.response.dispatchId}); stream via GET /sessions/${opened.sessionId}/stream.`);
+        case 'ok': {
+            const ok = result.response;
+            if (!wait) {
+                ctx.writeOutput({
+                    ok: true,
+                    sessionId: opened.sessionId,
+                    dispatchId: ok.dispatchId,
+                    personaSlug: ok.personaSlug,
+                }, `dispatched ${ok.personaSlug} (dispatchId=${ok.dispatchId}); stream via GET /sessions/${opened.sessionId}/stream.`);
+                return;
+            }
+            // --wait: subscribe to SSE until the persona reaches a terminal
+            // event. The waiter contract is provider-shaped so tests can pass
+            // a fake without standing up fetch.
+            const waiter = ctx.waitForTerminal ?? waitForDelegateTerminal;
+            const outcome = await waiter(config, opened.sessionId, ok.personaSlug);
+            switch (outcome.kind) {
+                case 'completed':
+                    ctx.writeOutput({
+                        ok: true,
+                        sessionId: opened.sessionId,
+                        dispatchId: ok.dispatchId,
+                        personaSlug: outcome.personaSlug,
+                        status: 'completed',
+                    }, `completed ${outcome.personaSlug} (dispatchId=${ok.dispatchId}).`);
+                    return;
+                case 'blocked':
+                    ctx.writeOutput({
+                        ok: false,
+                        sessionId: opened.sessionId,
+                        dispatchId: ok.dispatchId,
+                        personaSlug: outcome.personaSlug,
+                        status: 'blocked',
+                        detail: outcome.detail,
+                    }, `blocked ${outcome.personaSlug}: ${outcome.detail}`);
+                    process.exitCode = 5;
+                    return;
+                case 'failed':
+                    ctx.writeOutput({
+                        ok: false,
+                        sessionId: opened.sessionId,
+                        dispatchId: ok.dispatchId,
+                        personaSlug: outcome.personaSlug,
+                        status: 'failed',
+                        error: outcome.error,
+                    }, `failed ${outcome.personaSlug}: ${outcome.error}`);
+                    process.exitCode = 5;
+                    return;
+                case 'stream_error':
+                    ctx.writeOutput({
+                        ok: false,
+                        sessionId: opened.sessionId,
+                        dispatchId: ok.dispatchId,
+                        error: outcome.error,
+                    }, `pugi delegate --wait: ${outcome.error}`);
+                    process.exitCode = 1;
+                    return;
+            }
             return;
+        }
         case 'unknown_persona':
             ctx.writeOutput({ ok: false, error: result.message, code: result.code }, `pugi delegate: ${result.message}`);
             process.exitCode = 3;
@@ -78,4 +137,153 @@ export async function runDelegateCommand(args, ctx) {
             return;
     }
 }
+/* ------------------------------------------------------------------ */
+/* --wait waiter                                                      */
+/* ------------------------------------------------------------------ */
+/**
+ * Subscribe to the session SSE stream and resolve when the named
+ * persona reaches a terminal event (agent.completed / agent.blocked /
+ * agent.failed). Falls back to a `stream_error` outcome when the
+ * stream closes before any terminal event arrives or when the
+ * underlying fetch fails.
+ *
+ * The waiter is intentionally a single-call helper (not a long-lived
+ * subscriber) - the scripted `pugi delegate --wait` caller wants to
+ * exit on the first terminal event for THIS persona, not maintain a
+ * persistent connection.
+ *
+ * Why we parse the lifecycle in this file (not via the repl-render
+ * subscribe helper): repl-render carries Ink/React deps the
+ * non-interactive delegate path does not want to load. Duplicating the
+ * minimal SSE-line parser here keeps the command lean (this is the same
+ * shape `apps/admin-api/src/pugi/sessions.controller.ts` writes to the
+ * wire).
+ */
+export async function waitForDelegateTerminal(config, sessionId, targetPersonaSlug) {
+    const url = `${config.apiUrl.replace(/\/+$/, '')}/api/pugi/sessions/${encodeURIComponent(sessionId)}/stream`;
+    const controller = new AbortController();
+    // Hard-cap the waiter at 5 minutes so a stalled server cannot keep
+    // a scripted caller hanging forever; the dispatcher's per-turn budget
+    // is well under this.
+    const timeout = setTimeout(() => controller.abort(), 5 * 60 * 1000);
+    try {
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                Accept: 'text/event-stream',
+                Authorization: `Bearer ${config.apiKey}`,
+            },
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            return { kind: 'stream_error', error: `HTTP ${response.status}` };
+        }
+        if (!response.body) {
+            return { kind: 'stream_error', error: 'no response body' };
+        }
+        // Track the most-recent persona slug seen on agent.spawned so the
+        // terminal event (which carries only taskId) can be matched to the
+        // delegate target without parsing the random nonce suffix.
+        const taskToPersona = new Map();
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder('utf-8');
+        let buffer = '';
+        let currentData = '';
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done) {
+                return { kind: 'stream_error', error: 'stream ended without terminal event' };
+            }
+            buffer += decoder.decode(value, { stream: true });
+            let newlineIndex;
+            while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
+                const rawLine = buffer.slice(0, newlineIndex).replace(/\r$/, '');
+                buffer = buffer.slice(newlineIndex + 1);
+                if (rawLine.length === 0) {
+                    if (currentData.length > 0) {
+                        const parsed = parseDelegateFrame(currentData);
+                        if (parsed) {
+                            if (parsed.type === 'agent.spawned') {
+                                taskToPersona.set(parsed.taskId, parsed.personaSlug);
+                            }
+                            else if (parsed.type === 'agent.completed' ||
+                                parsed.type === 'agent.blocked' ||
+                                parsed.type === 'agent.failed') {
+                                const slug = taskToPersona.get(parsed.taskId) ?? targetPersonaSlug;
+                                if (slug === targetPersonaSlug) {
+                                    controller.abort();
+                                    if (parsed.type === 'agent.completed') {
+                                        return {
+                                            kind: 'completed',
+                                            personaSlug: slug,
+                                            taskId: parsed.taskId,
+                                        };
+                                    }
+                                    if (parsed.type === 'agent.blocked') {
+                                        return {
+                                            kind: 'blocked',
+                                            personaSlug: slug,
+                                            taskId: parsed.taskId,
+                                            detail: parsed.detail,
+                                        };
+                                    }
+                                    return {
+                                        kind: 'failed',
+                                        personaSlug: slug,
+                                        taskId: parsed.taskId,
+                                        error: parsed.error,
+                                    };
+                                }
+                            }
+                        }
+                    }
+                    currentData = '';
+                    continue;
+                }
+                if (rawLine.startsWith(':'))
+                    continue;
+                const colonIndex = rawLine.indexOf(':');
+                const field = colonIndex === -1 ? rawLine : rawLine.slice(0, colonIndex);
+                const value = colonIndex === -1 ? '' : rawLine.slice(colonIndex + 1).replace(/^ /, '');
+                if (field === 'data') {
+                    currentData = currentData.length === 0 ? value : `${currentData}\n${value}`;
+                }
+            }
+        }
+    }
+    catch (err) {
+        if (controller.signal.aborted) {
+            return { kind: 'stream_error', error: 'wait timed out' };
+        }
+        return { kind: 'stream_error', error: err.message };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function parseDelegateFrame(data) {
+    try {
+        const raw = JSON.parse(data);
+        const type = raw.type;
+        const taskId = typeof raw.taskId === 'string' ? raw.taskId : null;
+        if (!taskId)
+            return null;
+        if (type === 'agent.spawned' && typeof raw.personaSlug === 'string') {
+            return { type, taskId, personaSlug: raw.personaSlug };
+        }
+        if (type === 'agent.completed') {
+            return { type, taskId };
+        }
+        if (type === 'agent.blocked') {
+            return { type, taskId, detail: typeof raw.detail === 'string' ? raw.detail : '' };
+        }
+        if (type === 'agent.failed') {
+            return { type, taskId, error: typeof raw.error === 'string' ? raw.error : '' };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
 //# sourceMappingURL=delegate.js.map

package/dist/runtime/commands/lsp.js

@@ -0,0 +1,206 @@
+/**
+ * `pugi lsp <op> <file> [args...]` — α7.7 Phase 1.
+ *
+ * Direct LSP queries from the CLI surface. Operators use this for
+ * debugging and scripting; the agent loop reaches the same operations
+ * via the `lsp_hover` / `lsp_definition` / `lsp_references` /
+ * `lsp_diagnostics` tool wrappers in `src/tools/lsp-tools.ts`.
+ *
+ * Supported subcommands:
+ *
+ *   pugi lsp hover <file> <line> <col> [--lang ts|js|py|go|rust]
+ *   pugi lsp definition <file> <line> <col> [--lang ...]
+ *   pugi lsp references <file> <line> <col> [--lang ...]
+ *   pugi lsp diagnostics <file> [--lang ...]
+ *
+ * When `--lang` is omitted we infer from the file extension. An unknown
+ * extension surfaces `language_unsupported` so the operator can specify
+ * the language explicitly.
+ *
+ * Lifecycle: we spawn an LSP server per invocation and stop it before
+ * returning. This is slow on cold start (TS server takes ~2-3s the
+ * first time) but the single-shot scripting path doesn't need a
+ * persistent daemon. Future work (α7.7b) wires a per-REPL daemon.
+ *
+ * Brand voice: ASCII only, no emoji, no banned words.
+ */
+import { extname } from 'node:path';
+import { startLspClient } from '../../core/lsp/client.js';
+export async function runLspCommand(args, opts) {
+    const [op, file, ...rest] = args;
+    if (!op || !file) {
+        return usage();
+    }
+    if (!['hover', 'definition', 'references', 'diagnostics'].includes(op)) {
+        return {
+            ok: false,
+            text: `unknown lsp operation: ${op}. Supported: hover, definition, references, diagnostics`,
+            exitCode: 2,
+        };
+    }
+    const { lang: explicitLang, positional } = pullLangFlag(rest);
+    const lang = explicitLang ?? inferLanguage(file);
+    if (!lang) {
+        return {
+            ok: false,
+            text: `cannot infer language from ${file}; pass --lang ts|js|py|go|rust. ` +
+                `Supported extensions: .ts/.tsx, .js/.jsx/.mjs, .py, .go, .rs`,
+            exitCode: 2,
+        };
+    }
+    const clientResult = await startLspClient(lang, { cwd: opts.cwd });
+    if (!clientResult.ok) {
+        return {
+            ok: false,
+            text: `lsp_unavailable: ${clientResult.detail}`,
+            exitCode: 1,
+        };
+    }
+    const client = clientResult.value;
+    // R1 fix (2026-05-26, PR #413 r1, P2 #12): propagate SIGINT/SIGTERM
+    // to the LSP child process. Without this, ^C in the middle of a
+    // hung definition request would kill the CLI but leave the spawned
+    // language server orphaned (especially expensive for rust-analyzer
+    // / pyright which hold workspace indices in memory). We register
+    // listeners narrowly scoped to this single command invocation and
+    // tear them down in the `finally` block.
+    let interrupted = false;
+    const signalHandler = () => {
+        interrupted = true;
+        void client.stop();
+    };
+    process.once('SIGINT', signalHandler);
+    process.once('SIGTERM', signalHandler);
+    try {
+        if (op === 'diagnostics') {
+            const result = await client.diagnostics(file);
+            if (!result.ok) {
+                return { ok: false, text: `${result.reason}: ${result.detail}`, exitCode: 1 };
+            }
+            if (opts.json) {
+                return { ok: true, text: JSON.stringify(result.value, null, 2), exitCode: 0 };
+            }
+            if (result.value.length === 0) {
+                return { ok: true, text: `${file}: no diagnostics`, exitCode: 0 };
+            }
+            const lines = result.value.map((d) => `${d.severityLabel}\t${file}:${d.range.start.line + 1}:${d.range.start.character + 1}\t${d.message}`);
+            return { ok: true, text: lines.join('\n'), exitCode: 0 };
+        }
+        const line = Number.parseInt(positional[0] ?? '', 10);
+        const col = Number.parseInt(positional[1] ?? '', 10);
+        if (!Number.isFinite(line) || !Number.isFinite(col)) {
+            return {
+                ok: false,
+                text: `lsp ${op} requires <line> <col> arguments (1-based)`,
+                exitCode: 2,
+            };
+        }
+        // LSP positions are 0-based; we accept 1-based input from the CLI
+        // (matches every other editor convention) and convert here.
+        const pos = { line: Math.max(0, line - 1), character: Math.max(0, col - 1) };
+        if (op === 'hover') {
+            const result = await client.hover(file, pos);
+            if (!result.ok) {
+                return { ok: false, text: `${result.reason}: ${result.detail}`, exitCode: 1 };
+            }
+            if (opts.json) {
+                return { ok: true, text: JSON.stringify(result.value ?? null, null, 2), exitCode: 0 };
+            }
+            if (!result.value) {
+                return { ok: true, text: `${file}:${line}:${col}: no hover available`, exitCode: 0 };
+            }
+            return { ok: true, text: result.value.content, exitCode: 0 };
+        }
+        if (op === 'definition') {
+            const result = await client.definition(file, pos);
+            if (!result.ok) {
+                return { ok: false, text: `${result.reason}: ${result.detail}`, exitCode: 1 };
+            }
+            if (opts.json) {
+                return { ok: true, text: JSON.stringify(result.value, null, 2), exitCode: 0 };
+            }
+            const lines = result.value.map((loc) => `${loc.path || loc.uri}:${loc.range.start.line + 1}:${loc.range.start.character + 1}`);
+            return { ok: true, text: lines.join('\n') || 'no definition', exitCode: 0 };
+        }
+        // references
+        const result = await client.references(file, pos);
+        if (!result.ok) {
+            return { ok: false, text: `${result.reason}: ${result.detail}`, exitCode: 1 };
+        }
+        if (opts.json) {
+            return { ok: true, text: JSON.stringify(result.value, null, 2), exitCode: 0 };
+        }
+        const lines = result.value.map((loc) => `${loc.path || loc.uri}:${loc.range.start.line + 1}:${loc.range.start.character + 1}`);
+        return { ok: true, text: lines.join('\n') || 'no references', exitCode: 0 };
+    }
+    finally {
+        process.removeListener('SIGINT', signalHandler);
+        process.removeListener('SIGTERM', signalHandler);
+        await client.stop();
+        if (interrupted) {
+            // Propagate the interruption so the shell sees a sensible exit
+            // code on ^C rather than the last successful result code.
+            // 130 is the canonical "terminated by SIGINT" exit value.
+            return { ok: false, text: 'lsp aborted by signal', exitCode: 130 };
+        }
+    }
+}
+function usage() {
+    return {
+        ok: false,
+        text: 'Usage: pugi lsp <op> <file> [line] [col] [--lang ts|js|py|go|rust]\n' +
+            '  pugi lsp hover <file> <line> <col>\n' +
+            '  pugi lsp definition <file> <line> <col>\n' +
+            '  pugi lsp references <file> <line> <col>\n' +
+            '  pugi lsp diagnostics <file>',
+        exitCode: 2,
+    };
+}
+function pullLangFlag(args) {
+    let lang;
+    const positional = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i] ?? '';
+        if (arg === '--lang') {
+            const value = args[i + 1];
+            if (isLspLanguage(value))
+                lang = value;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith('--lang=')) {
+            const value = arg.slice('--lang='.length);
+            if (isLspLanguage(value))
+                lang = value;
+            continue;
+        }
+        positional.push(arg);
+    }
+    return { lang, positional };
+}
+function isLspLanguage(value) {
+    return value === 'ts' || value === 'js' || value === 'py' || value === 'go' || value === 'rust';
+}
+export function inferLanguage(file) {
+    const ext = extname(file).toLowerCase();
+    switch (ext) {
+        case '.ts':
+        case '.tsx':
+            return 'ts';
+        case '.js':
+        case '.jsx':
+        case '.mjs':
+        case '.cjs':
+            return 'js';
+        case '.py':
+        case '.pyi':
+            return 'py';
+        case '.go':
+            return 'go';
+        case '.rs':
+            return 'rust';
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=lsp.js.map

package/dist/runtime/commands/patch.js

@@ -0,0 +1,128 @@
+/**
+ * `pugi patch` — α7.7 Phase 1.
+ *
+ * Apply a unified-diff patch from stdin or a file. The dominant use is
+ * the `pugi patch < patch.diff` shell pattern that lets external tools
+ * (Codex, manual `git diff`) hand off changes through pugi's same
+ * security gate the layers use.
+ *
+ * Surface:
+ *
+ *   pugi patch                  # read patch from stdin
+ *   pugi patch <file.diff>      # read patch from file
+ *   pugi patch --dry-run        # run --check only, report
+ *   pugi patch --3way --base=<sha>  # enable git apply --3way fuzz
+ *
+ * Exit codes:
+ *
+ *   0  patch applied (or dry-run check passed)
+ *   1  patch rejected (any non-security reason)
+ *   2  usage error
+ *   3  security gate refused the patch (path traversal / protected file / symlink escape)
+ *
+ * Distinct exit codes let CI loops differentiate "operator typo" from
+ * "model produced a hostile patch" — the latter is a security event
+ * worth alerting on.
+ *
+ * Brand voice: ASCII only, no emoji, no banned words.
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { applyPatch } from '../../tools/apply-patch.js';
+import { FileReadCache } from '../../core/file-cache.js';
+import { openSession } from '../../core/session.js';
+import { loadSettings } from '../../core/settings.js';
+const SECURITY_REASONS = new Set(['path_outside_workspace', 'protected_file', 'symlink_escape']);
+export async function runPatchCommand(args, opts) {
+    const positional = [];
+    const applyOpts = {};
+    // Seed from caller-supplied options first; arg-flag parsing below
+    // overrides when present.
+    if (opts.dryRun)
+        applyOpts.dryRun = true;
+    if (opts.baseSha)
+        applyOpts.baseSha = opts.baseSha;
+    let threeWaySeen = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i] ?? '';
+        if (arg === '--dry-run')
+            applyOpts.dryRun = true;
+        else if (arg === '--3way') {
+            // honored only when --base is also supplied
+            threeWaySeen = true;
+        }
+        else if (arg === '--base') {
+            const next = args[i + 1];
+            if (next)
+                applyOpts.baseSha = next;
+            i += 1;
+        }
+        else if (arg.startsWith('--base=')) {
+            applyOpts.baseSha = arg.slice('--base='.length);
+        }
+        else if (arg === '--json') {
+            // already parsed by the outer CLI
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    // R1 fix (2026-05-26, PR #413 r1, P2 #14): `--3way` without `--base`
+    // is meaningless because `git apply --3way` falls back to the index,
+    // which a CLI-side `pugi patch` invocation does not have populated
+    // with the patch's pre-image. Warn the operator instead of dropping
+    // the flag silently.
+    if (threeWaySeen && !applyOpts.baseSha) {
+        const warn = opts.warn ?? ((m) => console.warn(m));
+        warn('warning: --3way ignored without --base=<sha>; pass --base or drop --3way');
+    }
+    let patch;
+    try {
+        patch = await readPatchSource(positional[0], opts);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return failure({ ok: false, filesChanged: [], reason: 'invalid_patch', detail: message }, opts.json, 2);
+    }
+    const ctx = {
+        root: opts.cwd,
+        settings: loadSettings(opts.cwd),
+        session: openSession(opts.cwd),
+        readCache: new FileReadCache(),
+    };
+    const result = applyPatch(ctx, patch, applyOpts);
+    if (!result.ok) {
+        const exitCode = result.reason && SECURITY_REASONS.has(result.reason) ? 3 : 1;
+        return failure(result, opts.json, exitCode);
+    }
+    const text = opts.json
+        ? JSON.stringify(result, null, 2)
+        : `applied ${result.filesChanged.length} files:\n  ${result.filesChanged.join('\n  ')}`;
+    return { ok: true, text, exitCode: 0, result };
+}
+function failure(result, json, exitCode) {
+    const text = json
+        ? JSON.stringify(result, null, 2)
+        : `patch refused: ${result.reason ?? 'unknown'}${result.detail ? `\n  ${result.detail}` : ''}`;
+    return { ok: false, text, exitCode, result };
+}
+async function readPatchSource(filePath, opts) {
+    if (filePath) {
+        const resolved = resolve(opts.cwd, filePath);
+        return readFileSync(resolved, 'utf8');
+    }
+    if (opts.stdinOverride !== undefined)
+        return opts.stdinOverride;
+    // Read all of stdin. The process pipe is the canonical CLI handoff
+    // for inbound diffs (e.g. `git diff origin/main | pugi patch`).
+    return new Promise((resolveFn, rejectFn) => {
+        let body = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            body += chunk;
+        });
+        process.stdin.on('end', () => resolveFn(body));
+        process.stdin.on('error', (error) => rejectFn(error));
+    });
+}
+//# sourceMappingURL=patch.js.map