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

package/dist/runtime/cli.js

@@ -73,6 +73,7 @@ import { installDefaultSkills } from '../core/skills/defaults.js';
 import { runRememberCommand, runSimplifyCommand, runStuckCommand, runBatchCommand, runVerifyCommand, runLoopCommand, runSkillifyCommand, } from '../skills/bundled/index.js';
 import { runAgentsCommand } from './commands/agents.js';
 import { runIndexCommand } from './commands/index-cmd.js';
+import { runServersCliCommand } from './commands/servers-cli.js';
 import { runLspCommand } from './commands/lsp.js';
 import { runPatchCommand } from './commands/patch.js';
 import { runWorktreeCommand } from './commands/worktree.js';
@@ -214,6 +215,21 @@ const handlers = {
     // scenario. Subcommand-only — no slash counterpart per the Phase 1
     // scope ("no new slash commands; harness is CLI subcommand only").
     smoke: dispatchSmoke,
+    // Backlog #120 ( Reviewer foundation): `pugi eval-v1` runs
+    // the frozen 20-task benchmark and produces a scalar pugi_score per
+    // task plus an aggregate mean. Ledger lives at `eval/v1/results.tsv`
+    // (append-only per backlog #110). Real-engine runs are operator-
+    // triggered via `--all`; CI wires the same command on a nightly
+    // schedule in `.github/workflows/eval-v1.yml`.
+    'eval-v1': dispatchEvalV1,
+    // PR M (2026-06-05): `pugi servers` top-level CLI mirroring the
+    // `/servers` REPL slash. Lists tracked server_start processes and
+    // kills them via the SIGTERM ladder. Same primitive
+    // (`runServersCommand`) as the slash; this wrapper only owns the
+    // argv contract + exit codes (0 / 2 / 3) + the `--workspace`
+    // override so the operator can rescue an orphaned server from any
+    // shell after the REPL is gone.
+    servers: dispatchServers,
     sync,
     style: dispatchStyle,
     // `pugi theme` flips the local TUI color
@@ -623,6 +639,29 @@ async function dispatchSmoke(args, flags, _session) {
     if (rc !== 0)
         process.exitCode = rc;
 }
+/**
+ * Backlog #120 - `pugi eval-v1` dispatcher.
+ *
+ * Forwards к `runEvalV1Command`. The handler stays thin: the eval
+ * runner owns workspace setup + scoring + ledger; the dispatcher only
+ * routes argv + JSON flag + exit code.
+ *
+ * Exit codes:
+ *  0 - every task passed (or `--list` / `--help`).
+ *  1 - at least one task failed.
+ *  2 - invalid args / task load failure.
+ */
+async function dispatchEvalV1(args, flags, _session) {
+    const { runEvalV1Command } = await import('./commands/eval-v1.js');
+    const rc = await runEvalV1Command({
+        args,
+        cwd: process.cwd(),
+        json: flags.json,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+    if (rc !== 0)
+        process.exitCode = rc;
+}
 /**
  * Backlog — `pugi stuck` top-level dispatcher.
  *
@@ -975,6 +1014,25 @@ async function dispatchIndex(args, flags, _session) {
     if (rc !== 0)
         process.exitCode = rc;
 }
+/**
+ * PR M (2026-06-05): `pugi servers [stop <target>] [--workspace <path>]`
+ * top-level dispatcher. Thin wrapper around `runServersCliCommand` -
+ * the runner owns argv parsing, IO sink wiring, and the exit-code
+ * mapping. Mirrors the `dispatchIndex` shape.
+ *
+ * Exit-code policy (forwarded from the runner):
+ *  0 - success / empty / stopped / --help
+ *  2 - usage error (unknown flag, missing stop target)
+ *  3 - not-found (stop target did not match)
+ */
+async function dispatchServers(args, flags, _session) {
+    const rc = await runServersCliCommand(args, {
+        workspaceRoot: process.cwd(),
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+    if (rc !== 0)
+        process.exitCode = rc;
+}
 /**
  * — `pugi onboarding` top-level dispatcher.
  *

package/dist/runtime/commands/eval-v1.js

@@ -0,0 +1,266 @@
+/**
+ * `pugi eval-v1` - run the frozen 20-task benchmark harness (#120).
+ *
+ * Surface:
+ *
+ *   pugi eval-v1 --list                       # list task ids + briefs
+ *   pugi eval-v1 --task 01-snake-html         # run one task
+ *   pugi eval-v1 --task 01,02,03              # run a subset
+ *   pugi eval-v1 --all                        # run the full 20
+ *   pugi eval-v1 --all --model qwen3-coder    # pin the engine model
+ *   pugi eval-v1 --all --json                 # JSON envelope output
+ *   pugi eval-v1 --all --no-ledger            # skip results.tsv append
+ *
+ * The handler stays thin: it resolves the tasks directory + pugi
+ * binary, calls `runHarness`, appends every result к the ledger
+ * (unless `--no-ledger`), and renders either a text table or a JSON
+ * envelope.
+ *
+ * Aggregate scoring (mean across all per-task scores) drives the CI
+ * regression gate in `.github/workflows/eval-v1.yml`. The gate is
+ * "aggregatePugiScore must not drop more than 10% vs the last week
+ * median" - the workflow computes the median itself from the
+ * committed ledger; the CLI's only job is к produce a fresh row.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defaultLedgerPath, defaultTasksDir, loadAllTasks, } from '../../core/eval/v1/task-loader.js';
+import { aggregateScore } from '../../core/eval/v1/scoring.js';
+import { appendLedgerRows } from '../../core/eval/v1/ledger.js';
+import { runHarness } from '../../core/eval/v1/runner.js';
+function parseFlags(args) {
+    const out = {
+        list: false,
+        all: false,
+        task: [],
+        model: undefined,
+        ledger: true,
+        tasksDir: undefined,
+        ledgerPath: undefined,
+        help: false,
+    };
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i] ?? '';
+        if (arg === '--list')
+            out.list = true;
+        else if (arg === '--all')
+            out.all = true;
+        else if (arg === '--no-ledger')
+            out.ledger = false;
+        else if (arg === '--help' || arg === '-h')
+            out.help = true;
+        else if (arg === '--task') {
+            const next = args[i + 1];
+            if (!next || next.startsWith('--')) {
+                throw new Error('--task requires a comma-separated list of ids');
+            }
+            out.task.push(...next.split(',').map((s) => s.trim()).filter(Boolean));
+            i += 1;
+        }
+        else if (arg.startsWith('--task=')) {
+            out.task.push(...arg.slice('--task='.length).split(',').map((s) => s.trim()).filter(Boolean));
+        }
+        else if (arg === '--model') {
+            const next = args[i + 1];
+            if (!next)
+                throw new Error('--model requires a value');
+            out.model = next;
+            i += 1;
+        }
+        else if (arg.startsWith('--model=')) {
+            out.model = arg.slice('--model='.length);
+        }
+        else if (arg === '--tasks-dir') {
+            const next = args[i + 1];
+            if (!next)
+                throw new Error('--tasks-dir requires a path');
+            out.tasksDir = next;
+            i += 1;
+        }
+        else if (arg.startsWith('--tasks-dir=')) {
+            out.tasksDir = arg.slice('--tasks-dir='.length);
+        }
+        else if (arg === '--ledger') {
+            const next = args[i + 1];
+            if (!next)
+                throw new Error('--ledger requires a path');
+            out.ledgerPath = next;
+            i += 1;
+        }
+        else if (arg.startsWith('--ledger=')) {
+            out.ledgerPath = arg.slice('--ledger='.length);
+        }
+        else if (arg === '--json') {
+            // accepted at top-level; ignore here
+        }
+        else {
+            throw new Error(`unknown eval-v1 flag: ${arg}`);
+        }
+    }
+    return out;
+}
+function resolvePackageRoot(override) {
+    if (override)
+        return resolve(override);
+    // The compiled file lives at `dist/runtime/commands/eval-v1.js`;
+    // climb three directories to reach the package root in both dev
+    // (`src/runtime/commands/eval-v1.ts`) and dist builds.
+    const here = dirname(fileURLToPath(import.meta.url));
+    return resolve(here, '..', '..', '..');
+}
+function resolvePugiBin(override, packageRoot) {
+    if (override)
+        return resolve(override);
+    const local = resolve(packageRoot, 'bin', 'run.js');
+    if (existsSync(local))
+        return local;
+    // Fall back к PATH lookup; spawn will pick it up.
+    return 'pugi';
+}
+function captureGitSha(packageRoot) {
+    try {
+        const out = execFileSync('git', ['rev-parse', '--short', 'HEAD'], {
+            cwd: packageRoot,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const trimmed = out.trim();
+        return trimmed === '' ? '(unknown)' : trimmed;
+    }
+    catch {
+        return '(unknown)';
+    }
+}
+function renderTable(report) {
+    const headers = ['id', 'difficulty', 'status', 'score', 'tokens', 'wall_ms', 'verifs'];
+    const rows = report.results.map((r) => [
+        r.taskId,
+        findDifficulty(r.taskId, report) ?? '?',
+        r.status,
+        r.pugiScore.toFixed(2),
+        String(r.tokensUsed),
+        String(r.wallClockMs),
+        `${r.verifications.filter((v) => v.passed).length}/${r.verifications.length}`,
+    ]);
+    const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length)));
+    const renderRow = (cells) => cells.map((c, i) => c.padEnd(widths[i] ?? 0)).join('  ');
+    const lines = [renderRow(headers), renderRow(widths.map((w) => '-'.repeat(w)))];
+    for (const row of rows)
+        lines.push(renderRow(row));
+    lines.push('');
+    lines.push(`aggregate pugi_score: ${report.aggregatePugiScore.toFixed(2)} (mean of ${report.results.length})`);
+    lines.push(`model: ${report.model}`);
+    lines.push(`git_sha: ${report.gitSha}`);
+    return lines.join('\n');
+}
+const difficultyMap = new WeakMap();
+function findDifficulty(taskId, report) {
+    const cached = difficultyMap.get(report);
+    return cached?.get(taskId);
+}
+function indexDifficulty(report, specs) {
+    const map = new Map();
+    for (const s of specs)
+        map.set(s.id, s.difficulty);
+    difficultyMap.set(report, map);
+}
+export async function runEvalV1Command(ctx) {
+    let flags;
+    try {
+        flags = parseFlags(ctx.args);
+    }
+    catch (err) {
+        ctx.writeOutput({ command: 'eval-v1', status: 'invalid_args', reason: err.message }, `pugi eval-v1: ${err.message}`);
+        return 2;
+    }
+    if (flags.help) {
+        const help = [
+            'pugi eval-v1 - frozen 20-task benchmark harness (#120)',
+            '',
+            'usage:',
+            '  pugi eval-v1 --list',
+            '  pugi eval-v1 --task <id[,id...]>',
+            '  pugi eval-v1 --all [--model <slug>] [--no-ledger] [--json]',
+        ].join('\n');
+        ctx.writeOutput({ command: 'eval-v1', status: 'help', help }, help);
+        return 0;
+    }
+    const packageRoot = resolvePackageRoot(ctx.packageRoot);
+    const tasksDir = flags.tasksDir ?? defaultTasksDir(packageRoot);
+    const ledgerPath = flags.ledgerPath ?? defaultLedgerPath(packageRoot);
+    const log = ctx.log ?? ((line) => process.stderr.write(`${line}\n`));
+    let loaded;
+    try {
+        loaded = loadAllTasks(tasksDir);
+    }
+    catch (err) {
+        ctx.writeOutput({
+            command: 'eval-v1',
+            status: 'tasks_load_failed',
+            reason: err.message,
+        }, `pugi eval-v1: ${err.message}`);
+        return 2;
+    }
+    const specs = loaded.map((l) => l.spec);
+    if (flags.list) {
+        const indexLines = specs.map((s) => `${s.id}  [${s.command}/${s.difficulty}]  ${s.brief}`);
+        const out = indexLines.join('\n');
+        ctx.writeOutput({ command: 'eval-v1', status: 'listed', tasks: specs.map((s) => ({
+                id: s.id, command: s.command, difficulty: s.difficulty, brief: s.brief,
+            })) }, out);
+        return 0;
+    }
+    if (!flags.all && flags.task.length === 0) {
+        const reason = 'pass --all OR --task <id[,id...]> OR --list';
+        ctx.writeOutput({ command: 'eval-v1', status: 'invalid_args', reason }, `pugi eval-v1: ${reason}`);
+        return 2;
+    }
+    const only = flags.all ? undefined : flags.task;
+    if (only) {
+        const known = new Set(specs.map((s) => s.id));
+        const unknown = only.filter((id) => !known.has(id));
+        if (unknown.length) {
+            const reason = `unknown task id(s): ${unknown.join(', ')}`;
+            ctx.writeOutput({ command: 'eval-v1', status: 'invalid_args', reason }, `pugi eval-v1: ${reason}`);
+            return 2;
+        }
+    }
+    const pugiBin = resolvePugiBin(ctx.pugiBin, packageRoot);
+    const startedAt = new Date().toISOString();
+    const gitSha = captureGitSha(packageRoot);
+    const results = await runHarness({
+        specs,
+        options: {
+            pugiBin,
+            ...(flags.model !== undefined ? { model: flags.model } : {}),
+            ...(only !== undefined ? { only } : {}),
+            ...(ctx.runner ? { runner: ctx.runner } : {}),
+            ...(ctx.env !== undefined ? { env: ctx.env } : {}),
+            onTaskStart: (s) => log(`[eval-v1] ${s.id} starting (${s.command}/${s.difficulty})`),
+            onTaskFinish: (r) => log(`[eval-v1] ${r.taskId} ${r.status} score=${r.pugiScore.toFixed(2)} tokens=${r.tokensUsed} wall=${r.wallClockMs}ms`),
+        },
+    });
+    const report = {
+        schemaVersion: 1,
+        startedAt,
+        model: flags.model ?? '(default)',
+        results,
+        aggregatePugiScore: aggregateScore(results),
+        gitSha,
+    };
+    indexDifficulty(report, specs);
+    if (flags.ledger && results.length > 0) {
+        appendLedgerRows(ledgerPath, results.map((r) => ({
+            timestamp: startedAt,
+            gitSha,
+            model: report.model,
+            result: r,
+        })));
+    }
+    ctx.writeOutput(report, renderTable(report));
+    const anyFail = results.some((r) => r.status !== 'pass');
+    return anyFail ? 1 : 0;
+}
+//# sourceMappingURL=eval-v1.js.map

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

@@ -40,6 +40,8 @@
  */
 import { resolve } from 'node:path';
 import { closeIndex, countSymbols, findCallers, findDefinition, openIndex, resolveIndexPath, searchSymbols, } from '../../core/codegraph/db.js';
+import { reindexWorkspace } from '../../core/codegraph/reindex.js';
+import { startWatcher } from '../../core/codegraph/watcher.js';
 import { INDEXED_LANGUAGES } from '../../core/codegraph/types.js';
 /**
  * Single entry-point. Returns the process exit code; the caller in
@@ -106,7 +108,7 @@ function printHelp(ctx) {
         '',
         'Usage:',
         '  pugi index                        Re-index the workspace.',
-        '  pugi index --watch                Start file watcher (PR L2, not yet wired).',
+        '  pugi index --watch                Live auto-sync via chokidar (2s debounce).',
         '  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>.',
@@ -121,37 +123,34 @@ 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) {
+async 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;
+        return runWatch(ctx);
     }
     let db = null;
     try {
         db = openIndex(ctx.workspaceRoot);
+        const summary = await reindexWorkspace(db, { quiet: true });
         const symCount = countSymbols(db);
         ctx.writeOutput({
             command: 'index',
             sub: 'reindex',
             watch: false,
-            status: 'scaffold-ready',
-            followup: 'PR L1',
+            status: 'ok',
             dbPath: db.dbPath,
             schemaVersion: db.version,
-            symbolCount: symCount,
+            filesScanned: summary.filesScanned,
+            filesIndexed: summary.filesIndexed,
+            symbolsInserted: summary.symbolsInserted,
+            edgesInserted: summary.edgesInserted,
+            edgesOrphaned: summary.edgesOrphaned,
+            totalSymbols: symCount,
+            elapsedMs: summary.totalMs,
         }, [
             `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.',
+            `Scanned ${summary.filesScanned} files, indexed ${summary.filesIndexed}.`,
+            `Symbols inserted: ${summary.symbolsInserted}. Edges inserted: ${summary.edgesInserted} (${summary.edgesOrphaned} orphans dropped).`,
+            `Elapsed: ${summary.totalMs} ms. Total symbols on disk: ${symCount}.`,
         ].join('\n'));
         return 0;
     }
@@ -165,11 +164,94 @@ function runReindex(ctx, watch) {
             closeIndex(db);
     }
 }
+/**
+ * `pugi index --watch` runtime: do one full re-index up-front so the
+ * index reflects the workspace as it stood at startup, then hand off
+ * к the chokidar watcher and block until SIGINT / SIGTERM. The DB
+ * handle stays open для the watcher's lifetime - the watcher writes
+ * incrementally, the operator quits with Ctrl+C, we close.
+ */
+async function runWatch(ctx) {
+    const writeStderr = ctx.writeStderr ?? ((text) => void process.stderr.write(text));
+    let db = null;
+    try {
+        db = openIndex(ctx.workspaceRoot);
+        // Baseline reindex so the watcher starts on a known-current index.
+        // Reindex is idempotent + cheap on subsequent runs (no-op for
+        // unchanged files via the sha256 fingerprint).
+        const summary = await reindexWorkspace(db, { quiet: true });
+        ctx.writeOutput({
+            command: 'index',
+            sub: 'reindex',
+            watch: true,
+            status: 'watching',
+            dbPath: db.dbPath,
+            schemaVersion: db.version,
+            filesScanned: summary.filesScanned,
+            filesIndexed: summary.filesIndexed,
+            symbolsInserted: summary.symbolsInserted,
+            edgesInserted: summary.edgesInserted,
+            baselineMs: summary.totalMs,
+        }, [
+            `Baseline index ready (${summary.filesIndexed} files, ${summary.symbolsInserted} symbols, ${summary.edgesInserted} edges).`,
+            `watching ${ctx.workspaceRoot}...`,
+            '  Press Ctrl+C to stop.',
+        ].join('\n'));
+        const handle = startWatcher({
+            db,
+            workspaceRoot: ctx.workspaceRoot,
+            writeStderr,
+        });
+        // Set up SIGINT / SIGTERM traps. Resolve the promise that gates
+        // `runWatch` once the handle has fully closed.
+        return await new Promise((resolvePromise) => {
+            let shuttingDown = false;
+            const shutdown = async (signal) => {
+                if (shuttingDown)
+                    return;
+                shuttingDown = true;
+                try {
+                    await handle.close();
+                    writeStderr(`pugi index --watch: stopped (${signal}).\n`);
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    writeStderr(`pugi index --watch: shutdown error: ${message}\n`);
+                }
+                finally {
+                    if (db)
+                        closeIndex(db);
+                    db = null;
+                    process.off('SIGINT', sigintListener);
+                    process.off('SIGTERM', sigtermListener);
+                    resolvePromise(0);
+                }
+            };
+            const sigintListener = () => void shutdown('SIGINT');
+            const sigtermListener = () => void shutdown('SIGTERM');
+            process.on('SIGINT', sigintListener);
+            process.on('SIGTERM', sigtermListener);
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.writeOutput({ command: 'index', sub: 'reindex', watch: true, error: 'watcher_failed', message }, `pugi index --watch failed: ${message}`);
+        if (db)
+            closeIndex(db);
+        return 1;
+    }
+}
 function runSearch(ctx, query) {
     let db = null;
     try {
         db = openIndex(ctx.workspaceRoot);
-        const results = searchSymbols(db, query, { limit: 50 });
+        // Wrap a bare identifier in a prefix-match phrase so operators
+        // can type `pugi index search foo` and find `fooBar`. FTS5 will
+        // happily accept a more specific raw expression too (e.g.
+        // `foo*` or `"exact phrase"`) - we only inject the convenience
+        // wrapping when the input looks like a plain identifier.
+        const wrapped = wrapSearchQuery(query);
+        const results = searchSymbols(db, wrapped, { limit: 50 });
         ctx.writeOutput({
             command: 'index',
             sub: 'search',
@@ -347,6 +429,30 @@ function renderCallersText(symbol, callers) {
 export function resolveWorkspaceRoot(input) {
     return resolve(input);
 }
+/**
+ * Best-effort prefix wrap for FTS5. When the operator types a plain
+ * identifier (`fooBar`, `my_func`, `Greeter`), wrap it as a prefix
+ * match. When the input already looks like an FTS5 expression
+ * (contains `*` / `"` / `:` / leading `+` `-`), pass it through
+ * untouched. Exported so the spec can pin the behaviour.
+ *
+ * `unicode61` (the FTS5 default tokenizer) splits on punctuation
+ * other than ASCII letters/digits; an unquoted identifier with
+ * `_` или `-` would be tokenised к multiple terms. We avoid that
+ * by quoting before appending `*` for prefix-match.
+ */
+export function wrapSearchQuery(query) {
+    const trimmed = query.trim();
+    if (trimmed.length === 0)
+        return trimmed;
+    if (/["*:+\-^()]/.test(trimmed))
+        return trimmed;
+    // Single identifier-like token: quote + prefix.
+    if (!/\s/.test(trimmed)) {
+        return `"${trimmed}"*`;
+    }
+    return trimmed;
+}
 // 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 };