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

package/dist/runtime/commands/hooks.js

@@ -0,0 +1,184 @@
+/**
+ * `pugi hooks` — operator surface for user-config hooks (Leak L12 MVP).
+ *
+ * Two subcommands ship in the MVP:
+ *
+ *   pugi hooks list         List configured hooks per event.
+ *   pugi hooks doctor       Validate the config and surface any
+ *                           parse / schema errors.
+ *
+ * Both accept `--json` for scripted callers. Argument grammar is
+ * intentionally narrow — no `add` / `remove` / `test` subcommands in
+ * the MVP. Operators hand-edit `~/.pugi/hooks-mvp.json` for now.
+ *
+ * Exit codes:
+ *   0  -> happy path (no hooks OR config valid).
+ *   1  -> config present but invalid (only `doctor` returns this).
+ *   2  -> unknown subcommand / argument error.
+ *
+ * Brand voice: ASCII only.
+ */
+import { ALL_HOOK_EVENTS_V2, defaultHooksMvpPath, loadHooksConfig, } from '../../core/hooks/index.js';
+function parseFlags(args) {
+    const rest = [];
+    const flags = { json: false };
+    for (const arg of args) {
+        if (arg === '--json') {
+            flags.json = true;
+            continue;
+        }
+        rest.push(arg);
+    }
+    return { rest, flags };
+}
+/**
+ * Top-level dispatcher for `pugi hooks <subcommand>`. Returns the
+ * intended process exit code. `cli.ts` is expected to set
+ * `process.exitCode = <return value>` so error states propagate to
+ * scripted callers without throwing.
+ */
+export async function runHooksCommand(args, ctx) {
+    const { rest, flags } = parseFlags(args);
+    const sub = rest[0];
+    if (!sub || sub === 'help' || sub === '--help') {
+        emitUsage(ctx, flags);
+        return sub ? 0 : 2;
+    }
+    if (sub === 'list') {
+        return runList(ctx, flags);
+    }
+    if (sub === 'doctor') {
+        return runDoctor(ctx, flags);
+    }
+    ctx.writeOutput({ ok: false, error: `unknown subcommand: ${sub}` }, `pugi hooks: unknown subcommand '${sub}'. Try 'pugi hooks --help'.`);
+    return 2;
+}
+function emitUsage(ctx, flags) {
+    const text = [
+        'pugi hooks — user-config lifecycle hooks (MVP).',
+        '',
+        'Subcommands:',
+        '  pugi hooks list        Show hooks configured per event.',
+        '  pugi hooks doctor      Validate ~/.pugi/hooks-mvp.json.',
+        '',
+        'Flags:',
+        '  --json                 Emit a JSON envelope instead of human text.',
+        '',
+        'Config file:',
+        '  ~/.pugi/hooks-mvp.json',
+        '',
+        'Status:',
+        '  MVP — 2 events out of 8. Remaining events (PostToolUse,',
+        "  UserPromptSubmit, Stop, SubagentStop, PreCompact, Notification)",
+        '  deferred to fast-follow PR.',
+    ].join('\n');
+    ctx.writeOutput({
+        ok: true,
+        command: 'hooks',
+        usage: text,
+    }, text);
+    if (flags.json) {
+        // The structured payload is already emitted by writeOutput when
+        // --json is on; nothing extra to do.
+    }
+}
+function runList(ctx, flags) {
+    let config;
+    try {
+        config = loadHooksConfig(ctx.configPath);
+    }
+    catch (error) {
+        const msg = error.message;
+        ctx.writeOutput({ ok: false, error: msg }, `pugi hooks list: ${msg}\nFix the config or remove the file. Run 'pugi hooks doctor' for details.`);
+        return 1;
+    }
+    const perEvent = {
+        SessionStart: [],
+        PreToolUse: [],
+        PostToolUse: [],
+        UserPromptSubmit: [],
+        Stop: [],
+        SubagentStop: [],
+        PreCompact: [],
+        Notification: [],
+    };
+    for (const event of ALL_HOOK_EVENTS_V2) {
+        perEvent[event] = config.list(event).map((entry) => ({
+            matcher: entry.matcher,
+            command: entry.command,
+            timeoutMs: entry.timeoutMs,
+            blocking: entry.blocking,
+        }));
+    }
+    const total = Object.values(perEvent).reduce((acc, list) => acc + list.length, 0);
+    const payload = {
+        ok: true,
+        configPath: config.configPath(),
+        total,
+        perEvent,
+    };
+    if (flags.json) {
+        ctx.writeOutput(payload, JSON.stringify(payload, null, 2));
+        return 0;
+    }
+    const lines = [];
+    lines.push(`pugi hooks (${total} configured)`);
+    lines.push(`  config: ${config.configPath()}`);
+    if (total === 0) {
+        lines.push('  no hooks configured — create the file above to add one.');
+    }
+    else {
+        for (const event of ALL_HOOK_EVENTS_V2) {
+            const list = perEvent[event];
+            if (list.length === 0)
+                continue;
+            lines.push(`  ${event}:`);
+            for (const entry of list) {
+                const tags = [];
+                if (entry.matcher)
+                    tags.push(`matcher=${entry.matcher}`);
+                if (entry.timeoutMs)
+                    tags.push(`timeoutMs=${entry.timeoutMs}`);
+                if (entry.blocking)
+                    tags.push('blocking');
+                const suffix = tags.length ? `  [${tags.join(', ')}]` : '';
+                lines.push(`    - ${entry.command}${suffix}`);
+            }
+        }
+    }
+    const text = lines.join('\n');
+    ctx.writeOutput(payload, text);
+    return 0;
+}
+function runDoctor(ctx, flags) {
+    const path = ctx.configPath ?? defaultHooksMvpPath();
+    try {
+        const config = loadHooksConfig(ctx.configPath);
+        const total = config.flatten().length;
+        const payload = {
+            ok: true,
+            configPath: config.configPath(),
+            total,
+            issues: [],
+        };
+        const text = total
+            ? `pugi hooks doctor: ${path} OK (${total} hooks).`
+            : `pugi hooks doctor: ${path} not present (no hooks configured).`;
+        ctx.writeOutput(payload, text);
+        return 0;
+    }
+    catch (error) {
+        const msg = error.message;
+        const payload = {
+            ok: false,
+            configPath: path,
+            error: msg,
+        };
+        const text = `pugi hooks doctor: ${msg}`;
+        ctx.writeOutput(payload, text);
+        return 1;
+    }
+    // flags.json is consumed by writeOutput in the host shell.
+    void flags;
+}
+//# sourceMappingURL=hooks.js.map

package/dist/runtime/commands/lsp.js

@@ -0,0 +1,368 @@
+/**
+ * `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 { inspectLspServers, startLspClient } from '../../core/lsp/client.js';
+import { languageForFile as inferLanguage } from '../../core/lsp/language-detect.js';
+import { loadSettings } from '../../core/settings.js';
+export async function runLspCommand(args, opts) {
+    const [op, file, ...rest] = args;
+    if (!op) {
+        return usage();
+    }
+    // β7 L9: introspection subcommand. `pugi lsp servers` reports the
+    // language matrix — binary-on-PATH + enabled-via-settings — so the
+    // operator can debug `lsp_unavailable` vs `lsp_disabled` without
+    // re-running an actual hover.
+    if (op === 'servers' || op === 'status') {
+        const settings = loadSettings(opts.cwd);
+        const lspSettings = settings.lsp;
+        const rows = inspectLspServers(lspSettings);
+        if (opts.json) {
+            return { ok: true, text: JSON.stringify(rows, null, 2), exitCode: 0 };
+        }
+        const lines = ['language\tcommand\tavailable\tenabled'];
+        for (const r of rows) {
+            lines.push(`${r.language}\t${r.command}\t${r.available ? 'yes' : 'no'}\t${r.enabled ? 'yes' : 'no'}`);
+        }
+        return { ok: true, text: lines.join('\n'), exitCode: 0 };
+    }
+    if (!file) {
+        return usage();
+    }
+    // β7 L6: `find_definition` convenience subcommand. Identical wire to
+    // `definition` but takes `<symbol>` instead of <line> <col>. We grep
+    // the workspace for the first hit on `<symbol>` (whole-word match) to
+    // recover a position, then route through LSP. Falls back cleanly when
+    // the symbol is not present in the file.
+    if (op === 'find_definition' || op === 'find-definition') {
+        const { lang: explicitLangFD, positional: positionalFD } = pullLangFlag(rest);
+        const symbol = positionalFD[0];
+        if (!symbol) {
+            return {
+                ok: false,
+                text: 'Usage: pugi lsp find_definition <file> <symbol> [--lang ts|js|py|go|rust]',
+                exitCode: 2,
+            };
+        }
+        const lang = explicitLangFD ?? 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,
+            };
+        }
+        return await findDefinition(file, symbol, lang, opts);
+    }
+    if (!['hover', 'definition', 'references', 'diagnostics'].includes(op)) {
+        return {
+            ok: false,
+            text: `unknown lsp operation: ${op}. Supported: hover, definition, references, diagnostics, find_definition, servers`,
+            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 settings = loadSettings(opts.cwd);
+    // Leak L15 (2026-05-27): `pugi lsp check <file>` — manual probe of
+    // the post-edit diagnostics pipeline. Identical output to what the
+    // model sees appended to its tool envelope after a successful
+    // edit/write. Lets operators dry-run the auto-diagnostic surface
+    // without dispatching an actual edit.
+    if (op === 'check') {
+        const { runPostEditDiagnostics } = await import('../../core/lsp/post-edit-diagnostics.js');
+        const result = await runPostEditDiagnostics(file, {
+            cwd: opts.cwd,
+            ...(settings.lsp ? { lspSettings: settings.lsp } : {}),
+        });
+        if (opts.json) {
+            return { ok: true, text: JSON.stringify(result, null, 2), exitCode: 0 };
+        }
+        if (result.skip) {
+            return { ok: true, text: `${file}: skipped (${result.reason})`, exitCode: 0 };
+        }
+        return { ok: true, text: result.tail, exitCode: 0 };
+    }
+    const clientResult = await startLspClient(lang, {
+        cwd: opts.cwd,
+        ...(settings.lsp ? { lspSettings: settings.lsp } : {}),
+    });
+    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>\n' +
+            '  pugi lsp check <file>          (Leak L15: probe post-edit tail)\n' +
+            '  pugi lsp find_definition <file> <symbol>\n' +
+            '  pugi lsp servers',
+        exitCode: 2,
+    };
+}
+/**
+ * β7 L6: find_definition convenience.
+ *
+ * Reads the file, walks line-by-line looking for the first whole-word
+ * match of `<symbol>`, then runs `lsp definition` at that position.
+ * The result is a normal location array — empty when the LSP server
+ * can't resolve the symbol (typically because the workspace TS server
+ * hasn't indexed the import yet).
+ *
+ * "Whole-word match" uses the same identifier-boundary rules as Layer
+ * D's tokenizer: matches inside string literals / comments / partial
+ * identifiers are skipped. This keeps the result aligned with what the
+ * operator means by "where is foo defined" — not "any character sequence
+ * spelling foo".
+ */
+async function findDefinition(file, symbol, lang, opts) {
+    const { readFileSync, existsSync } = await import('node:fs');
+    const { resolve } = await import('node:path');
+    const abs = resolve(opts.cwd, file);
+    if (!existsSync(abs)) {
+        return { ok: false, text: `file not found: ${file}`, exitCode: 1 };
+    }
+    let body;
+    try {
+        body = readFileSync(abs, 'utf8');
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return { ok: false, text: `cannot read ${file}: ${detail}`, exitCode: 1 };
+    }
+    const position = locateIdentifier(body, symbol);
+    if (!position) {
+        return {
+            ok: false,
+            text: `symbol '${symbol}' not found in ${file}`,
+            exitCode: 1,
+        };
+    }
+    const settings = loadSettings(opts.cwd);
+    const clientResult = await startLspClient(lang, {
+        cwd: opts.cwd,
+        ...(settings.lsp ? { lspSettings: settings.lsp } : {}),
+    });
+    if (!clientResult.ok) {
+        return { ok: false, text: `${clientResult.reason}: ${clientResult.detail}`, exitCode: 1 };
+    }
+    const client = clientResult.value;
+    try {
+        const result = await client.definition(file, position);
+        if (!result.ok) {
+            return { ok: false, text: `${result.reason}: ${result.detail}`, exitCode: 1 };
+        }
+        if (opts.json) {
+            return {
+                ok: true,
+                text: JSON.stringify({
+                    symbol,
+                    file,
+                    sourcePosition: { line: position.line + 1, character: position.character + 1 },
+                    definitions: result.value,
+                }, null, 2),
+                exitCode: 0,
+            };
+        }
+        if (result.value.length === 0) {
+            return { ok: true, text: `no definition for ${symbol}`, 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'), exitCode: 0 };
+    }
+    finally {
+        await client.stop();
+    }
+}
+/**
+ * Find the first whole-word occurrence of `symbol` in `body`. Returns
+ * the 0-based LSP position (line + character) or null when absent.
+ * Uses the same identifier boundary rule as Layer D's tokenizer to
+ * avoid matching inside larger identifiers.
+ */
+export function locateIdentifier(body, symbol) {
+    const lines = body.split('\n');
+    // Build the boundary regex once. We can't use `\b` directly because
+    // it treats `$` as a word boundary and TS/JS allow `$` in identifiers;
+    // implement the boundary check with a manual lookaround.
+    const isIdent = (ch) => {
+        if (!ch)
+            return false;
+        return /[A-Za-z0-9_$]/.test(ch);
+    };
+    for (let line = 0; line < lines.length; line += 1) {
+        const text = lines[line];
+        let from = 0;
+        while (from < text.length) {
+            const idx = text.indexOf(symbol, from);
+            if (idx === -1)
+                break;
+            const before = idx > 0 ? text[idx - 1] : undefined;
+            const after = idx + symbol.length < text.length ? text[idx + symbol.length] : undefined;
+            if (!isIdent(before) && !isIdent(after)) {
+                return { line, character: idx };
+            }
+            from = idx + symbol.length;
+        }
+    }
+    return null;
+}
+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';
+}
+// Leak L15 (2026-05-27): single source of truth for ext → language
+// lives in `core/lsp/language-detect.ts`. The CLI surface re-exports
+// the lookup so existing call sites keep their import path.
+export { inferLanguage };
+//# sourceMappingURL=lsp.js.map