@pugi/cli 0.1.0-beta.1 → 0.1.0-beta.2

package/dist/runtime/cli.js

@@ -28,6 +28,9 @@ import { runUndoCommand } from './commands/undo.js';
 import { runBudgetCommand } from './commands/budget.js';
 import { runSkillsCommand } from './commands/skills.js';
 import { runAgentsCommand } from './commands/agents.js';
+import { runLspCommand } from './commands/lsp.js';
+import { runPatchCommand } from './commands/patch.js';
+import { runWorktreeCommand } from './commands/worktree.js';
 import { resolveWorkspaceLabel } from '../core/repl/workspace-context.js';
 import { runReviewConsensus } from './commands/review-consensus.js';
 import { FtsSyntaxError, SqliteSessionStore, resolveProjectStoreDir } from '../core/repl/store/index.js';
@@ -44,7 +47,7 @@ import { dispatchEdit, } from '../core/edits/index.js';
  * packages/pugi-sdk/package.json); the publish workflow validates the
  * three are in lockstep.
  */
-const PUGI_CLI_VERSION = "0.1.0-beta.1";
+const PUGI_CLI_VERSION = "0.1.0-beta.2";
 const handlers = {
     accounts,
     agents: dispatchAgents,
@@ -64,6 +67,8 @@ const handlers = {
     jobs,
     login,
     logout,
+    lsp: dispatchLsp,
+    patch: dispatchPatch,
     plan: runEngineTask('plan'),
     'plan-review': dispatchPlanReview,
     privacy: dispatchPrivacy,
@@ -76,6 +81,7 @@ const handlers = {
     version,
     web: dispatchWeb,
     whoami,
+    worktree: dispatchWorktree,
 };
 /**
  * α6.3 `pugi ask "<question>"` — surface the office-hours forcing-question
@@ -314,6 +320,46 @@ async function dispatchWeb(args, flags, _session) {
     }
     writeOutput(flags, result, `# ${result.title}\n# ${result.url}\n# fetched ${result.fetched_at}\n\n${result.content_md}`);
 }
+/**
+ * α7.7: `pugi lsp <op> <file> [args]` — direct LSP queries. Delegated
+ * to the standalone runner in `./commands/lsp.ts` so the giant cli.ts
+ * dispatch table stays narrow. The runner spawns + tears down the LSP
+ * server per invocation (no daemon yet — that ships in α7.7b).
+ */
+async function dispatchLsp(args, flags, _session) {
+    const result = await runLspCommand(args, { cwd: process.cwd(), json: flags.json });
+    if (flags.json)
+        console.log(result.text);
+    else
+        console.log(result.text);
+    if (result.exitCode !== 0)
+        process.exitCode = result.exitCode;
+}
+/**
+ * α7.7: `pugi patch` — apply a unified-diff patch from stdin or a file.
+ * Routes through the same security gate as the Layer A/B/C applicators
+ * (see `src/core/edits/security-gate.ts`). Exit codes mirror the
+ * security taxonomy so CI loops can alert on hostile patches without
+ * confusing them with operator typos.
+ */
+async function dispatchPatch(args, flags, _session) {
+    const result = await runPatchCommand(args, { cwd: process.cwd(), json: flags.json });
+    console.log(result.text);
+    if (result.exitCode !== 0)
+        process.exitCode = result.exitCode;
+}
+/**
+ * α7.7: `pugi worktree <op>` — manual scratch worktree management.
+ * The `pugi build` and `pugi review --consensus` paths use the same
+ * primitives internally (`createWorktree` / `promoteWorktree`); this
+ * surface is the operator escape hatch for debug + experiment flows.
+ */
+async function dispatchWorktree(args, flags, _session) {
+    const result = await runWorktreeCommand(args, { cwd: process.cwd(), json: flags.json });
+    console.log(result.text);
+    if (result.exitCode !== 0)
+        process.exitCode = result.exitCode;
+}
 export async function runCli(argv) {
     const { command, args, flags, isBareInvocation } = parseArgs(argv);
     // Bare `pugi` on a TTY enters the REPL-by-default agentic session

package/dist/runtime/commands/lsp.js

@@ -0,0 +1,184 @@
+/**
+ * `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;
+    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 {
+        await client.stop();
+    }
+}
+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,111 @@
+/**
+ * `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 = {};
+    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
+        }
+        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);
+        }
+    }
+    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

package/dist/runtime/commands/worktree.js

@@ -0,0 +1,133 @@
+/**
+ * `pugi worktree <op>` — α7.7 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 { resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { createWorktree, dropWorktree, promoteWorktree } from '../../core/edits/worktree.js';
+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,
+            };
+        }
+        // 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 });
+        if (!result.ok) {
+            return {
+                ok: false,
+                text: opts.json
+                    ? JSON.stringify(result, null, 2)
+                    : `promote failed: ${result.reason}: ${result.detail}`,
+                exitCode: 1,
+            };
+        }
+        return {
+            ok: true,
+            text: opts.json
+                ? JSON.stringify({ filesChanged: result.value.filesChanged }, null, 2)
+                : `promoted ${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,
+            };
+        }
+        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: 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