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

package/dist/runtime/commands/init.js

@@ -0,0 +1,254 @@
+/**
+ * `pugi init` codebase scan → PUGI.md auto-gen (backlog #82).
+ *
+ * Extends the existing `init()` scaffold with a project-aware PUGI.md
+ * generator. Runs AFTER `scaffoldPugiWorkspace` so the `.pugi/` workspace
+ * exists for the `init-report.json` write.
+ *
+ * Flow:
+ *
+ *  1. Detect existing PUGI.md. If present without `--force`, refuse
+ *     with `refused_existing`.
+ *  2. Run `detectWorkspace` against cwd.
+ *  3. Render PUGI.md content for the requested style.
+ *  4. Confirm with the operator unless `--yes` / `--json` / `--force`.
+ *  5. Write `<cwd>/PUGI.md` atomically (tmp + rename, fallback к
+ *     direct write on EXDEV — happens когда tmp lives на a different
+ *     volume).
+ *  6. Write `.pugi/init-report.json` (mode 0o600) with the raw
+ *     detection payload for re-runs / auditing.
+ *  7. Emit a JSON envelope describing the outcome.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+import { detectWorkspace } from '../../core/init/detector.js';
+import { renderPugiMd, STYLE_WORD_CAPS, } from '../../core/init/template-renderer.js';
+export const DEFAULT_PUGI_MD_STYLE = 'standard';
+/** Entry point invoked by `cli.ts::init`. */
+export async function runInitScanCommand(args, ctx) {
+    const cwd = resolve(ctx.cwd);
+    const pugiMdPath = join(cwd, 'PUGI.md');
+    const reportPath = join(cwd, '.pugi', 'init-report.json');
+    // `args` is currently consumed only via flags. Keep the parameter to
+    // mirror every other command surface so we can grow positional args
+    // (e.g. an explicit target path) without breaking the call site.
+    void args;
+    try {
+        if (existsSync(pugiMdPath) && !ctx.force) {
+            const envelope = {
+                command: 'init-scan',
+                status: 'refused_existing',
+                pugiMdPath,
+                reportPath,
+                style: ctx.style,
+                message: 'PUGI.md already exists. Re-run with --force to overwrite, or edit by hand.',
+            };
+            ctx.writeOutput(envelope, formatHuman(envelope));
+            return envelope;
+        }
+        const detection = detectWorkspace(cwd);
+        const rendered = renderPugiMd(detection, { style: ctx.style, now: ctx.now });
+        const shouldConfirm = !ctx.yes && !ctx.json && !ctx.force;
+        if (shouldConfirm) {
+            const confirm = ctx.confirm ?? defaultConfirm;
+            const ok = await confirm(`Write PUGI.md at ${pugiMdPath} (${rendered.wordCount} words, style: ${ctx.style})? [y/N] `);
+            if (!ok) {
+                const envelope = {
+                    command: 'init-scan',
+                    status: 'aborted',
+                    pugiMdPath,
+                    reportPath,
+                    style: ctx.style,
+                    message: 'Aborted by operator before write.',
+                };
+                ctx.writeOutput(envelope, formatHuman(envelope));
+                return envelope;
+            }
+        }
+        atomicWrite(pugiMdPath, rendered.content);
+        writeReport(reportPath, detection, rendered.wordCount, ctx.style);
+        const envelope = {
+            command: 'init-scan',
+            status: 'written',
+            pugiMdPath,
+            reportPath,
+            detection,
+            wordCount: rendered.wordCount,
+            style: ctx.style,
+        };
+        ctx.writeOutput(envelope, formatHuman(envelope));
+        return envelope;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const envelope = {
+            command: 'init-scan',
+            status: 'error',
+            pugiMdPath,
+            reportPath,
+            style: ctx.style,
+            message,
+        };
+        ctx.writeOutput(envelope, formatHuman(envelope));
+        return envelope;
+    }
+}
+/* ------------------------------------------------------------------ */
+/* Atomic write                                                      */
+/* ------------------------------------------------------------------ */
+function atomicWrite(targetPath, content) {
+    const dir = dirname(targetPath);
+    mkdirSync(dir, { recursive: true });
+    const tmpName = `.pugi-md-${process.pid}-${Date.now()}.tmp`;
+    const tmpPath = join(tmpdir(), tmpName);
+    try {
+        writeFileSync(tmpPath, content, { encoding: 'utf8', mode: 0o644 });
+        renameSync(tmpPath, targetPath);
+        return;
+    }
+    catch (error) {
+        // EXDEV — cross-device link: tmpdir lives on a different volume
+        // than the workspace. Retry with the tmpfile inside the workspace.
+        cleanupTmp(tmpPath);
+        const code = error.code;
+        if (code !== 'EXDEV') {
+            // Fall through to the in-dir fallback for any rename failure so
+            // we keep the contract: PUGI.md is either fully written or not
+            // written. The direct writeFileSync at the end is the final
+            // safety net.
+        }
+        const localTmpPath = join(dir, `.pugi-md-${process.pid}-${Date.now()}.tmp`);
+        try {
+            writeFileSync(localTmpPath, content, { encoding: 'utf8', mode: 0o644 });
+            renameSync(localTmpPath, targetPath);
+            return;
+        }
+        catch {
+            cleanupTmp(localTmpPath);
+        }
+        // Final fallback — direct write. We sacrifice the atomicity guarantee
+        // here but keep behavioural correctness when both the tmp + in-dir
+        // strategies fail (rare; usually FS quirks).
+        writeFileSync(targetPath, content, { encoding: 'utf8', mode: 0o644 });
+    }
+}
+function cleanupTmp(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // best effort
+    }
+}
+function writeReport(reportPath, detection, wordCount, style) {
+    mkdirSync(dirname(reportPath), { recursive: true });
+    const payload = {
+        generatedAt: new Date().toISOString(),
+        style,
+        wordCap: STYLE_WORD_CAPS[style],
+        wordCount,
+        detection,
+    };
+    writeFileSync(reportPath, JSON.stringify(payload, null, 2), {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+    try {
+        chmodSync(reportPath, 0o600);
+    }
+    catch {
+        // Some filesystems (FAT, NTFS over CIFS) reject chmod; the mode
+        // option on writeFileSync is the primary guard. Best-effort here.
+    }
+}
+/* ------------------------------------------------------------------ */
+/* Confirm prompt                                                    */
+/* ------------------------------------------------------------------ */
+async function defaultConfirm(question) {
+    if (process.stdin.isTTY !== true) {
+        return true;
+    }
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    return new Promise((resolveAnswer) => {
+        let settled = false;
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            rl.close();
+            resolveAnswer(value);
+        };
+        rl.once('close', () => settle(false));
+        rl.question(question, (answer) => {
+            settle(/^y(es)?$/i.test(answer.trim()));
+        });
+    });
+}
+/* ------------------------------------------------------------------ */
+/* Human-readable formatting                                         */
+/* ------------------------------------------------------------------ */
+function formatHuman(env) {
+    switch (env.status) {
+        case 'written':
+            return [
+                `PUGI.md written to ${env.pugiMdPath}`,
+                ` Style:     ${env.style}`,
+                ` Word count: ${env.wordCount ?? 0}`,
+                ` Report:    ${env.reportPath}`,
+            ].join('\n');
+        case 'refused_existing':
+            return env.message ?? 'PUGI.md already exists. Use --force to overwrite.';
+        case 'aborted':
+            return env.message ?? 'Aborted.';
+        case 'error':
+            return `pugi init scan failed: ${env.message ?? 'unknown error'}`;
+        default:
+            return 'pugi init scan complete.';
+    }
+}
+/* ------------------------------------------------------------------ */
+/* Helpers consumed by cli.ts                                        */
+/* ------------------------------------------------------------------ */
+/** Parse `--style=<minimal|standard|detailed>` (or `--style minimal`). */
+export function parseInitStyle(args) {
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (typeof arg !== 'string')
+            continue;
+        if (arg.startsWith('--style=')) {
+            const value = arg.slice('--style='.length);
+            const parsed = coerceStyle(value);
+            if (parsed)
+                return parsed;
+        }
+        else if (arg === '--style') {
+            const next = args[i + 1];
+            if (typeof next === 'string') {
+                const parsed = coerceStyle(next);
+                if (parsed)
+                    return parsed;
+            }
+        }
+    }
+    return DEFAULT_PUGI_MD_STYLE;
+}
+function coerceStyle(value) {
+    if (value === 'minimal' || value === 'standard' || value === 'detailed')
+        return value;
+    return null;
+}
+/** Test surface: read back the on-disk report. */
+export function readInitReport(reportPath) {
+    try {
+        return JSON.parse(readFileSync(reportPath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=init.js.map

package/dist/runtime/commands/lsp.js

@@ -1,5 +1,5 @@
 /**
- * `pugi lsp <op> <file> [args...]` — α7.7 Phase 1.
+ * `pugi lsp <op> <file> [args...]` — Phase 1.
  *
  * Direct LSP queries from the CLI surface. Operators use this for
  * debugging and scripting; the agent loop reaches the same operations
@@ -8,10 +8,10 @@
  *
  * 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 ...]
+ *  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
@@ -20,21 +20,68 @@
  * 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.
+ * persistent daemon. Future work 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';
+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 || !file) {
+    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`,
+            text: `unknown lsp operation: ${op}. Supported: hover, definition, references, diagnostics, find_definition, servers`,
             exitCode: 2,
         };
     }
@@ -48,7 +95,30 @@ export async function runLspCommand(args, opts) {
             exitCode: 2,
         };
     }
-    const clientResult = await startLspClient(lang, { cwd: opts.cwd });
+    const settings = loadSettings(opts.cwd);
+    // `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,
@@ -57,7 +127,7 @@ export async function runLspCommand(args, opts) {
         };
     }
     const client = clientResult.value;
-    // R1 fix (2026-05-26, PR #413 r1, P2 #12): propagate SIGINT/SIGTERM
+    // R1 fix (2026-05-26, PR 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
@@ -149,13 +219,123 @@ 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>',
+            ' 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>         (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 = [];
@@ -181,26 +361,8 @@ function pullLangFlag(args) {
 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;
-    }
-}
+// 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