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

package/dist/runtime/commands/index-cmd.js

@@ -0,0 +1,353 @@
+/**
+ * `pugi index` - local symbol index CLI surface.
+ *
+ * Operator entry point for the Pugi-native symbol index living at
+ * `.pugi/codegraph.db`. Four subcommands today, all wired against the
+ * scaffold DB layer in `core/codegraph/db.ts`:
+ *
+ *  - `pugi index`                       - full (re)index of the workspace.
+ *                                          Today: opens the DB, runs the
+ *                                          v1 migration, and reports the
+ *                                          stub parser state. PR L1
+ *                                          replaces this with a real
+ *                                          tree-sitter walk.
+ *  - `pugi index --watch`               - start the file watcher. Not
+ *                                          implemented in this PR; exits
+ *                                          with rc=3 + a pointer at
+ *                                          PR L2 which ships chokidar
+ *                                          + 2s debounce.
+ *  - `pugi index search <query>`        - FTS5 query against
+ *                                          `symbols_fts`. Works on top
+ *                                          of an empty index too -
+ *                                          returns zero matches.
+ *  - `pugi index definition <symbol>`   - exact-name lookup. Same shape
+ *                                          as `--search`.
+ *  - `pugi index callers <symbol>`      - reverse-edge query. Empty
+ *                                          today because the stub
+ *                                          parser emits no edges.
+ *
+ * The command is intentionally narrow - every information surface
+ * (count, freshness, language coverage) routes through the existing
+ * `/codegraph-status` slash that already ships in `runtime/commands/
+ * codegraph-status.ts`. This file owns the indexing verbs; status
+ * lives over there.
+ *
+ * Exit codes:
+ *  0 - success / "nothing to do" idempotent path
+ *  1 - runtime failure (db error, IO error)
+ *  2 - invalid CLI args (unknown subcommand, missing required positional)
+ *  3 - not implemented yet (parser stub, watcher) - pointer in stderr
+ */
+import { resolve } from 'node:path';
+import { closeIndex, countSymbols, findCallers, findDefinition, openIndex, resolveIndexPath, searchSymbols, } from '../../core/codegraph/db.js';
+import { INDEXED_LANGUAGES } from '../../core/codegraph/types.js';
+/**
+ * Single entry-point. Returns the process exit code; the caller in
+ * `runtime/cli.ts` propagates it via `process.exitCode` (mirrors the
+ * `dispatchFlatten` pattern).
+ */
+export async function runIndexCommand(args, ctx) {
+    const sub = parseArgs(args);
+    switch (sub.kind) {
+        case 'help':
+            return printHelp(ctx);
+        case 'unknown':
+            return printUnknown(ctx, sub.raw);
+        case 'reindex':
+            return runReindex(ctx, sub.watch);
+        case 'search':
+            return runSearch(ctx, sub.query);
+        case 'definition':
+            return runDefinition(ctx, sub.symbol);
+        case 'callers':
+            return runCallers(ctx, sub.symbol);
+    }
+}
+/**
+ * Parse the argv tail (everything after `pugi index`). Pure - exported
+ * for the spec to pin canonical shapes.
+ */
+export function parseArgs(args) {
+    if (args.length === 0) {
+        return { kind: 'reindex', watch: false };
+    }
+    const [head, ...rest] = args;
+    if (!head)
+        return { kind: 'reindex', watch: false };
+    if (head === '--help' || head === '-h' || head === 'help') {
+        return { kind: 'help' };
+    }
+    if (head === '--watch' || head === '-w') {
+        return { kind: 'reindex', watch: true };
+    }
+    if (head === 'search') {
+        const query = rest.join(' ').trim();
+        if (query.length === 0)
+            return { kind: 'unknown', raw: 'search (missing query)' };
+        return { kind: 'search', query };
+    }
+    if (head === 'definition') {
+        const symbol = rest.join(' ').trim();
+        if (symbol.length === 0)
+            return { kind: 'unknown', raw: 'definition (missing symbol)' };
+        return { kind: 'definition', symbol };
+    }
+    if (head === 'callers') {
+        const symbol = rest.join(' ').trim();
+        if (symbol.length === 0)
+            return { kind: 'unknown', raw: 'callers (missing symbol)' };
+        return { kind: 'callers', symbol };
+    }
+    return { kind: 'unknown', raw: head };
+}
+function printHelp(ctx) {
+    ctx.writeOutput({ command: 'index', sub: 'help', subcommands: ['search', 'definition', 'callers'] }, [
+        'pugi index - local symbol index (CodeGraph-style).',
+        '',
+        'Usage:',
+        '  pugi index                        Re-index the workspace.',
+        '  pugi index --watch                Start file watcher (PR L2, not yet wired).',
+        '  pugi index search <query>         FTS5 search across symbol names.',
+        '  pugi index definition <symbol>    Find the definition of <symbol>.',
+        '  pugi index callers <symbol>       List call sites referencing <symbol>.',
+        '',
+        `Languages (v1): ${INDEXED_LANGUAGES.join(', ')}.`,
+        'Storage: .pugi/codegraph.db (gitignored, regenerable).',
+        'Design memo: docs/research/2026-06-05-pugi-index-codegraph-design.md',
+    ].join('\n'));
+    return 0;
+}
+function printUnknown(ctx, raw) {
+    ctx.writeOutput({ command: 'index', error: 'unknown-subcommand', got: raw }, `pugi index: unknown subcommand "${raw}". Allowed: search, definition, callers, --watch, --help.`);
+    return 2;
+}
+function runReindex(ctx, watch) {
+    if (watch) {
+        ctx.writeOutput({
+            command: 'index',
+            sub: 'reindex',
+            watch: true,
+            status: 'not-implemented',
+            followup: 'PR L2',
+        }, [
+            'pugi index --watch: file watcher not implemented in this scaffold PR.',
+            'Tracked in follow-up PR L2 (chokidar + 2s debounce + incremental).',
+        ].join('\n'));
+        return 3;
+    }
+    let db = null;
+    try {
+        db = openIndex(ctx.workspaceRoot);
+        const symCount = countSymbols(db);
+        ctx.writeOutput({
+            command: 'index',
+            sub: 'reindex',
+            watch: false,
+            status: 'scaffold-ready',
+            followup: 'PR L1',
+            dbPath: db.dbPath,
+            schemaVersion: db.version,
+            symbolCount: symCount,
+        }, [
+            `Index DB ready at ${db.dbPath} (schema v${db.version}).`,
+            `Indexed symbols: ${symCount}.`,
+            'Parser is stubbed in this PR. Real tree-sitter extraction lands in PR L1.',
+        ].join('\n'));
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.writeOutput({ command: 'index', sub: 'reindex', error: 'db_error', message }, `pugi index failed: ${message}`);
+        return 1;
+    }
+    finally {
+        if (db)
+            closeIndex(db);
+    }
+}
+function runSearch(ctx, query) {
+    let db = null;
+    try {
+        db = openIndex(ctx.workspaceRoot);
+        const results = searchSymbols(db, query, { limit: 50 });
+        ctx.writeOutput({
+            command: 'index',
+            sub: 'search',
+            query,
+            matches: results.length,
+            results: results.map(serializeSearchResult),
+        }, renderSearchText(query, results, db.dbPath));
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.writeOutput({ command: 'index', sub: 'search', error: 'query_failed', message }, `pugi index search failed: ${message}`);
+        return 1;
+    }
+    finally {
+        if (db)
+            closeIndex(db);
+    }
+}
+function runDefinition(ctx, symbol) {
+    let db = null;
+    try {
+        db = openIndex(ctx.workspaceRoot);
+        const result = findDefinition(db, symbol);
+        ctx.writeOutput({
+            command: 'index',
+            sub: 'definition',
+            symbol,
+            result: serializeDefinitionResult(result),
+        }, renderDefinitionText(symbol, result));
+        return result.kind === 'found' ? 0 : 0;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.writeOutput({ command: 'index', sub: 'definition', error: 'query_failed', message }, `pugi index definition failed: ${message}`);
+        return 1;
+    }
+    finally {
+        if (db)
+            closeIndex(db);
+    }
+}
+function runCallers(ctx, symbol) {
+    let db = null;
+    try {
+        db = openIndex(ctx.workspaceRoot);
+        const def = findDefinition(db, symbol);
+        if (def.kind !== 'found' || def.definition.id === undefined) {
+            ctx.writeOutput({
+                command: 'index',
+                sub: 'callers',
+                symbol,
+                matches: 0,
+                note: 'definition_not_found',
+            }, `pugi index callers: no definition known for "${symbol}". Run \`pugi index\` first or check the spelling.`);
+            return 0;
+        }
+        const callers = findCallers(db, def.definition.id);
+        ctx.writeOutput({
+            command: 'index',
+            sub: 'callers',
+            symbol,
+            definitionId: def.definition.id,
+            matches: callers.length,
+            callers: callers.map(serializeCallerResult),
+        }, renderCallersText(symbol, callers));
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.writeOutput({ command: 'index', sub: 'callers', error: 'query_failed', message }, `pugi index callers failed: ${message}`);
+        return 1;
+    }
+    finally {
+        if (db)
+            closeIndex(db);
+    }
+}
+function serializeSearchResult(r) {
+    return {
+        name: r.symbol.name,
+        kind: r.symbol.kind,
+        file: r.symbol.file,
+        line: r.symbol.line,
+        col: r.symbol.column,
+        scope: r.symbol.scope,
+        signature: r.symbol.signature ?? null,
+        rank: r.rank,
+    };
+}
+function serializeDefinitionResult(r) {
+    if (r.kind === 'not_found')
+        return { found: false, name: r.name };
+    return {
+        found: true,
+        definition: serializeSymbol(r.definition),
+        disambiguations: r.disambiguations.map(serializeSymbol),
+    };
+}
+function serializeCallerResult(c) {
+    return {
+        name: c.caller.name,
+        kind: c.caller.kind,
+        file: c.caller.file,
+        line: c.caller.line,
+        col: c.caller.column,
+        scope: c.caller.scope,
+        edgeKind: c.edge.kind,
+    };
+}
+function serializeSymbol(s) {
+    return {
+        id: s.id,
+        name: s.name,
+        kind: s.kind,
+        file: s.file,
+        line: s.line,
+        col: s.column,
+        scope: s.scope,
+        signature: s.signature ?? null,
+    };
+}
+function renderSearchText(query, results, dbPath) {
+    if (results.length === 0) {
+        return [
+            `pugi index search "${query}" - 0 matches.`,
+            `Index DB: ${dbPath}`,
+            'Hint: the parser stub does not extract symbols yet. PR L1 wires real tree-sitter extraction.',
+        ].join('\n');
+    }
+    const lines = [
+        `pugi index search "${query}" - ${results.length} matches:`,
+        '',
+    ];
+    for (const r of results) {
+        lines.push(` ${r.symbol.name}  [${r.symbol.kind}]  ${r.symbol.file}:${r.symbol.line}  rank=${r.rank.toFixed(2)}`);
+    }
+    return lines.join('\n');
+}
+function renderDefinitionText(symbol, result) {
+    if (result.kind === 'not_found') {
+        return [
+            `pugi index definition "${symbol}" - not found.`,
+            'Hint: PR L1 wires the parser; until then the index is empty unless seeded by tests.',
+        ].join('\n');
+    }
+    const d = result.definition;
+    const head = ` ${d.name}  [${d.kind}]  ${d.file}:${d.line}`;
+    if (result.disambiguations.length === 0)
+        return head;
+    return [
+        head,
+        `Also found in ${result.disambiguations.length} other locations:`,
+        ...result.disambiguations.map((s) => `  - ${s.file}:${s.line}  [${s.kind}]`),
+    ].join('\n');
+}
+function renderCallersText(symbol, callers) {
+    if (callers.length === 0) {
+        return `pugi index callers "${symbol}" - 0 call sites.`;
+    }
+    const lines = [
+        `pugi index callers "${symbol}" - ${callers.length} call sites:`,
+        '',
+    ];
+    for (const c of callers) {
+        lines.push(` ${c.caller.name}  ${c.caller.file}:${c.caller.line}  edge=${c.edge.kind}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Resolve the absolute workspace root from a relative input. Exported so
+ * the cli.ts dispatcher can call this once and pass an already-absolute
+ * path to the context. Pure - no IO.
+ */
+export function resolveWorkspaceRoot(input) {
+    return resolve(input);
+}
+// Re-export `resolveIndexPath` from db.ts for callers that want to know
+// where the DB lives without opening it (e.g. `pugi doctor`).
+export { resolveIndexPath };
+//# sourceMappingURL=index-cmd.js.map

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