@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.91

package/dist/core/init/template-renderer.js

@@ -0,0 +1,242 @@
+export const STYLE_WORD_CAPS = Object.freeze({
+    minimal: 500,
+    standard: 1500,
+    detailed: 3500,
+});
+/** Render PUGI.md content for the requested tier. */
+export function renderPugiMd(detection, options) {
+    const sections = [];
+    const style = options.style;
+    const now = options.now ?? (() => new Date());
+    sections.push(renderHeader(detection, now()));
+    sections.push(renderStack(detection));
+    sections.push(renderFrameworks(detection, style));
+    if (style !== 'minimal') {
+        sections.push(renderTesting(detection));
+        sections.push(renderCommitConvention(detection));
+        sections.push(renderMonorepo(detection));
+        sections.push(renderAiConfigs(detection, style));
+        sections.push(renderCommands(detection));
+        sections.push(renderProjectLayout(detection));
+    }
+    if (style === 'detailed') {
+        sections.push(renderContributorChecklist());
+    }
+    sections.push(renderFooter());
+    const body = sections.filter((s) => s.length > 0).join('\n\n');
+    const trimmed = enforceWordCap(body, STYLE_WORD_CAPS[style]);
+    return Object.freeze({
+        content: trimmed.endsWith('\n') ? trimmed : `${trimmed}\n`,
+        wordCount: countWords(trimmed),
+        style,
+    });
+}
+/* ------------------------------------------------------------------ */
+/* Section renderers                                                 */
+/* ------------------------------------------------------------------ */
+function renderHeader(detection, now) {
+    const name = detection.stack.nodeName ?? deriveName(detection.cwd);
+    const date = now.toISOString().slice(0, 10);
+    const lines = [
+        `# ${name} — AI Context (PUGI.md)`,
+        '',
+        `Generated by \`pugi init\` on ${date}.`,
+        'Pugi reads this file on every session start. Keep it short and current —',
+        'if a section conflicts with the code, the code wins. Edit freely.',
+    ];
+    return lines.join('\n');
+}
+function renderStack(detection) {
+    const lines = ['## Stack', ''];
+    const stack = detection.stack;
+    if (stack.kind === 'unknown') {
+        lines.push('No language manifest detected at the workspace root.');
+        if (detection.languages.length > 0) {
+            lines.push('');
+            lines.push(`Primary file extensions: ${detection.languages.join(', ')}.`);
+        }
+        return lines.join('\n');
+    }
+    const labelMap = {
+        node: 'Node.js / JavaScript / TypeScript',
+        python: 'Python',
+        rust: 'Rust',
+        go: 'Go',
+        ruby: 'Ruby',
+        php: 'PHP',
+        java: 'Java / Kotlin (JVM)',
+    };
+    lines.push(`- Primary: ${labelMap[stack.kind] ?? stack.kind}`);
+    if (stack.packageManager) {
+        lines.push(`- Package manager: ${stack.packageManager}`);
+    }
+    if (stack.manifests.length > 0) {
+        lines.push(`- Manifests: ${stack.manifests.join(', ')}`);
+    }
+    if (detection.languages.length > 0) {
+        lines.push(`- Languages observed: ${detection.languages.join(', ')}`);
+    }
+    return lines.join('\n');
+}
+function renderFrameworks(detection, style) {
+    if (detection.frameworks.length === 0)
+        return '';
+    const lines = ['## Frameworks', ''];
+    for (const fw of detection.frameworks) {
+        if (style === 'detailed') {
+            lines.push(`- **${fw.name}** — ${fw.evidence}`);
+        }
+        else {
+            lines.push(`- ${fw.name}`);
+        }
+    }
+    return lines.join('\n');
+}
+function renderTesting(detection) {
+    if (detection.testFrameworks.length === 0)
+        return '';
+    const lines = ['## Testing', ''];
+    lines.push(`Detected: ${detection.testFrameworks.join(', ')}.`);
+    return lines.join('\n');
+}
+function renderCommitConvention(detection) {
+    const lines = ['## Commit conventions', ''];
+    switch (detection.commitConvention) {
+        case 'conventional':
+            lines.push('Recent history follows Conventional Commits (`feat:`, `fix:`, `chore:`...).');
+            lines.push('Keep new commits in that style — auto-changelog tooling parses the prefix.');
+            break;
+        case 'gitmoji':
+            lines.push('Recent history uses gitmoji prefixes (`:sparkles:`, `:bug:`...).');
+            lines.push('Keep new commits in that style for visual consistency.');
+            break;
+        case 'freeform':
+            lines.push('Commits are freeform — no detected prefix convention.');
+            lines.push('Pick a short imperative subject line and keep body wrapped at 72 cols.');
+            break;
+        case 'unknown':
+        default:
+            lines.push('No commit history detected yet. Pick a convention (recommended: Conventional Commits).');
+            break;
+    }
+    return lines.join('\n');
+}
+function renderMonorepo(detection) {
+    if (!detection.monorepo)
+        return '';
+    const lines = ['## Monorepo', ''];
+    const kindLabel = {
+        pnpm: 'pnpm workspaces',
+        lerna: 'Lerna',
+        turborepo: 'Turborepo',
+        nx: 'Nx',
+        'yarn-workspaces': 'Yarn / npm workspaces',
+    };
+    lines.push(`- Layout: ${kindLabel[detection.monorepo.kind] ?? detection.monorepo.kind} (${detection.monorepo.file})`);
+    return lines.join('\n');
+}
+function renderAiConfigs(detection, style) {
+    if (detection.aiConfigs.length === 0)
+        return '';
+    const lines = ['## Existing AI configs', ''];
+    for (const cfg of detection.aiConfigs) {
+        lines.push(`- \`${cfg.path}\``);
+    }
+    if (style === 'detailed') {
+        for (const cfg of detection.aiConfigs) {
+            if (!cfg.excerpt)
+                continue;
+            lines.push('');
+            lines.push(`### ${cfg.name} excerpt`);
+            lines.push('');
+            lines.push('```');
+            const trimmed = cfg.excerpt.split('\n').slice(0, 20).join('\n');
+            lines.push(trimmed);
+            lines.push('```');
+        }
+    }
+    return lines.join('\n');
+}
+function renderCommands(detection) {
+    if (detection.scripts.length === 0)
+        return '';
+    const lines = ['## Commands', ''];
+    const pm = detection.stack.packageManager ?? 'npm';
+    lines.push('```bash');
+    for (const entry of detection.scripts) {
+        lines.push(commandLine(entry, pm));
+    }
+    lines.push('```');
+    return lines.join('\n');
+}
+function commandLine(entry, pm) {
+    const runner = pm === 'pnpm' || pm === 'yarn' || pm === 'bun' ? pm : 'npm run';
+    if (runner === 'npm run')
+        return `npm run ${entry.name}`;
+    return `${runner} ${entry.name}`;
+}
+function renderProjectLayout(detection) {
+    if (detection.topLevelDirs.length === 0)
+        return '';
+    const lines = ['## Project layout', ''];
+    for (const dir of detection.topLevelDirs) {
+        lines.push(`- \`${dir}/\``);
+    }
+    return lines.join('\n');
+}
+function renderContributorChecklist() {
+    return [
+        '## Contributor checklist',
+        '',
+        '- Read this file + any in-repo ARCHITECTURE / DESIGN docs before code changes.',
+        '- Run the project test suite before opening a PR.',
+        '- Keep secrets in `.env` (never commit).',
+        '- Update this file when stack / framework / commands change.',
+    ].join('\n');
+}
+function renderFooter() {
+    return [
+        '## How Pugi uses this file',
+        '',
+        'On every session, Pugi loads this file as ambient context.',
+        'Edit it like a README aimed at an AI engineer joining your team.',
+    ].join('\n');
+}
+/* ------------------------------------------------------------------ */
+/* Word-cap enforcement                                              */
+/* ------------------------------------------------------------------ */
+function countWords(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return 0;
+    return trimmed.split(/\s+/).length;
+}
+function enforceWordCap(body, cap) {
+    const current = countWords(body);
+    if (current <= cap)
+        return body;
+    // Greedy truncation: keep paragraphs in order until cap is reached,
+    // then append a truncation marker so the reader understands the file
+    // was clipped (deterministic).
+    const paragraphs = body.split(/\n{2,}/);
+    const kept = [];
+    let used = 0;
+    for (const paragraph of paragraphs) {
+        const words = countWords(paragraph);
+        if (used + words > cap)
+            break;
+        kept.push(paragraph);
+        used += words;
+    }
+    kept.push(`<!-- truncated to fit ${cap}-word cap -->`);
+    return kept.join('\n\n');
+}
+/* ------------------------------------------------------------------ */
+/* Misc                                                              */
+/* ------------------------------------------------------------------ */
+function deriveName(cwd) {
+    const trimmed = cwd.replace(/\/+$/, '');
+    const last = trimmed.split('/').pop();
+    return last && last.length > 0 ? last : 'project';
+}
+//# sourceMappingURL=template-renderer.js.map

package/dist/core/jobs/registry.js

@@ -1,23 +1,23 @@
 /**
- * JobRegistry — Sprint α5.9 (ADR-0056 PR-PUGI-CLI-M1-GAP-J).
+ * JobRegistry — Sprint .
  *
  * First-class persistent registry for background bash jobs. Lifts the
  * inline `~/.pugi/jobs.json` management from `src/tools/bash.ts` and
  * extends it with:
  *
- *   - Atomic write (tempfile + rename) so concurrent CLI invocations
- *     cannot corrupt the ledger (Code Reviewer P2 retro on PR #306).
- *   - Stale-job reaping on every `list()` call: entries whose pid no
- *     longer corresponds to a live process are marked `abandoned`.
- *   - 24h retention for finished / killed / abandoned entries; older
- *     records are dropped silently.
- *   - Lifecycle status field (`running` / `finished` / `killed` /
- *     `failed` / `abandoned`) so the `pugi jobs` CLI can render an
- *     accurate snapshot regardless of which CLI invocation observed
- *     the exit.
+ *  - Atomic write (tempfile + rename) so concurrent CLI invocations
+ *    cannot corrupt the ledger (Code Reviewer P2 retro on PR).
+ *  - Stale-job reaping on every `list()` call: entries whose pid no
+ *    longer corresponds to a live process are marked `abandoned`.
+ *  - 24h retention for finished / killed / abandoned entries; older
+ *    records are dropped silently.
+ *  - Lifecycle status field (`running` / `finished` / `killed` /
+ *    `failed` / `abandoned`) so the `pugi jobs` CLI can render an
+ *    accurate snapshot regardless of which CLI invocation observed
+ *    the exit.
  *
  * Storage stays at `~/.pugi/jobs.json` as a JSON array (not JSONL) so
- * α5.2 readers continue to work. The schema is additive: legacy
+ * readers continue to work. The schema is additive: legacy
  * entries lacking `id` / `status` / etc. are upgraded on read.
  */
 import { randomUUID } from 'node:crypto';
@@ -267,7 +267,7 @@ class FileJobRegistry {
     }
 }
 /**
- * Normalize legacy `~/.pugi/jobs.json` entries (Sprint α5.2 shape with
+ * Normalize legacy `~/.pugi/jobs.json` entries (Sprint shape with
  * `jobId` / `class` / no status) into the JobEntry shape used here.
  * Returns undefined for entries that cannot be migrated so the loop
  * silently skips garbage.
@@ -387,7 +387,7 @@ export function summarizeJobsForPrompt(entries) {
         .slice(-5);
     const lines = ['BACKGROUND JOBS:'];
     if (running.length === 0) {
-        lines.push('  - Running: 0');
+        lines.push(' - Running: 0');
     }
     else {
         const oldest = running.reduce((min, entry) => {
@@ -395,7 +395,7 @@ export function summarizeJobsForPrompt(entries) {
                 ? entry
                 : min;
         }, running[0]);
-        lines.push(`  - Running: ${running.length} (oldest started ${relativeAge(oldest.startedAt)} ago)`);
+        lines.push(` - Running: ${running.length} (oldest started ${relativeAge(oldest.startedAt)} ago)`);
         const counts = new Map();
         for (const entry of running) {
             counts.set(entry.bashClass, (counts.get(entry.bashClass) ?? 0) + 1);
@@ -403,15 +403,15 @@ export function summarizeJobsForPrompt(entries) {
         const classSummary = [...counts.entries()]
             .map(([cls, count]) => `${cls} (${count})`)
             .join(', ');
-        lines.push(`  - Classes in flight: ${classSummary}`);
+        lines.push(` - Classes in flight: ${classSummary}`);
     }
     if (finished.length > 0) {
         const compact = finished
             .map((entry) => `${entry.id.slice(0, 8)} ${entry.status}${entry.exitCode !== undefined ? ` exit=${entry.exitCode}` : ''}`)
             .join('; ');
-        lines.push(`  - Recent finished (last ${finished.length}): ${compact}`);
+        lines.push(` - Recent finished (last ${finished.length}): ${compact}`);
     }
-    lines.push('  Use `pugi jobs tail <id>` to inspect output. Do not spawn another long-running background job while 3+ are already on watch.');
+    lines.push(' Use `pugi jobs tail <id>` to inspect output. Do not spawn another long-running background job while 3+ are already on watch.');
     return lines.join('\n');
 }
 /**

package/dist/core/ledger/results-tsv.js

@@ -0,0 +1,142 @@
+import { promises as fs } from 'node:fs';
+const HEADER = 'ts\trun_id\tscope\tkey\tvalue\tmodel\tprompt_hash\tnotes\n';
+const appendLocks = new Map();
+export class ResultsLedger {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    async append(row) {
+        const previous = appendLocks.get(this.path) ?? Promise.resolve();
+        const next = previous
+            .catch(() => undefined)
+            .then(async () => {
+            if (await this.needsHeader()) {
+                await fs.appendFile(this.path, HEADER, 'utf8');
+            }
+            await fs.appendFile(this.path, `${this.formatRow(row)}\n`, 'utf8');
+        });
+        appendLocks.set(this.path, next);
+        try {
+            await next;
+        }
+        finally {
+            if (appendLocks.get(this.path) === next) {
+                appendLocks.delete(this.path);
+            }
+        }
+    }
+    async query(filter) {
+        const rows = await this.readRows();
+        return rows.filter((row) => {
+            return Object.entries(filter).every(([field, expected]) => {
+                if (expected === undefined) {
+                    return true;
+                }
+                const value = row[field];
+                return value !== undefined && String(value) === String(expected);
+            });
+        });
+    }
+    async aggregate(scope, key, op) {
+        const rows = await this.query({ scope, key });
+        if (op === 'count') {
+            return rows.length;
+        }
+        const values = rows
+            .map((row) => Number(row.value))
+            .filter((value) => Number.isFinite(value));
+        if (values.length === 0) {
+            return 0;
+        }
+        if (op === 'sum') {
+            return values.reduce((sum, value) => sum + value, 0);
+        }
+        if (op === 'avg') {
+            return values.reduce((sum, value) => sum + value, 0) / values.length;
+        }
+        if (op === 'min') {
+            return Math.min(...values);
+        }
+        return Math.max(...values);
+    }
+    async needsHeader() {
+        try {
+            const stat = await fs.stat(this.path);
+            return stat.size === 0;
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === 'ENOENT') {
+                return true;
+            }
+            throw error;
+        }
+    }
+    async readRows() {
+        let data;
+        try {
+            data = await fs.readFile(this.path, 'utf8');
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === 'ENOENT') {
+                return [];
+            }
+            throw error;
+        }
+        if (!data.endsWith('\n')) {
+            data = data.slice(0, data.lastIndexOf('\n') + 1);
+        }
+        const lines = data.split('\n').filter((line) => line.length > 0);
+        const dataLines = lines[0] === HEADER.trimEnd() ? lines.slice(1) : lines;
+        return dataLines.flatMap((line) => {
+            const cells = line.split('\t');
+            if (cells.length !== 8) {
+                return [];
+            }
+            const ts = cells[0];
+            const run_id = cells[1];
+            const scope = cells[2];
+            const key = cells[3];
+            const value = cells[4];
+            const model = cells[5];
+            const prompt_hash = cells[6];
+            const notes = cells[7];
+            if (!ts || !run_id || !scope || !key || value === undefined) {
+                return [];
+            }
+            return [
+                {
+                    ts,
+                    run_id,
+                    scope,
+                    key,
+                    value,
+                    ...(model ? { model } : {}),
+                    ...(prompt_hash ? { prompt_hash } : {}),
+                    ...(notes ? { notes } : {}),
+                },
+            ];
+        });
+    }
+    formatRow(row) {
+        return [
+            row.ts,
+            row.run_id,
+            row.scope,
+            row.key,
+            row.value,
+            row.model ?? '',
+            row.prompt_hash ?? '',
+            row.notes ?? '',
+        ]
+            .map((value) => cleanCell(value))
+            .join('\t');
+    }
+}
+function cleanCell(value) {
+    return String(value).replace(/\r?\n/g, ' ').replace(/\t/g, ' ');
+}
+function isNodeError(error) {
+    return error instanceof Error && 'code' in error;
+}
+//# sourceMappingURL=results-tsv.js.map

package/dist/core/log-discipline/stdout-redirect.js

@@ -0,0 +1,51 @@
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+function stripQuotes(s) {
+    return s
+        .replace(/"(?:\\.|[^"\\])*"/g, '""')
+        .replace(/'(?:\\.|[^'\\])*'/g, "''");
+}
+function hasRedirect(stripped) {
+    const noLogical = stripped.replace(/\|\|/g, ' ').replace(/&&/g, ' ');
+    if (/>\s*\S/.test(noLogical))
+        return true;
+    if (/2>&1/.test(noLogical))
+        return true;
+    if (/\|\s*tee\b/.test(noLogical))
+        return true;
+    if (/\|/.test(noLogical))
+        return true;
+    return false;
+}
+function isCompound(stripped) {
+    return /&&|\|\||;|\|/.test(stripped);
+}
+function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function genLogPath(logDir) {
+    const rand = randomBytes(6).toString('hex');
+    return join(logDir, `cmd-${rand}.log`);
+}
+export function redirectCommand(command, options) {
+    if (!options.workspaceRoot || typeof options.workspaceRoot !== 'string') {
+        throw new Error('redirectCommand: workspaceRoot is required');
+    }
+    const logDir = options.logDir ?? join(options.workspaceRoot, '.pugi', 'logs');
+    const logPath = genLogPath(logDir);
+    const trimmed = command.trim();
+    if (trimmed.length === 0) {
+        return { command: trimmed, logPath, alreadyRedirected: false };
+    }
+    const stripped = stripQuotes(trimmed);
+    const already = hasRedirect(stripped);
+    if (already && !options.forceRedirect) {
+        return { command, logPath, alreadyRedirected: true };
+    }
+    const compound = isCompound(stripped);
+    const transformed = compound
+        ? `sh -c ${shellQuote(trimmed)} > ${logPath} 2>&1`
+        : `${trimmed} > ${logPath} 2>&1`;
+    return { command: transformed, logPath, alreadyRedirected: already };
+}
+//# sourceMappingURL=stdout-redirect.js.map

package/dist/core/lsp/cache.js

@@ -0,0 +1,105 @@
+/**
+ * Per-process LSP client cache — .
+ *
+ * The `runtime/commands/lsp.ts` CLI surface spawns one LSP server
+ * per invocation and stops it at the end. That is correct for the
+ * one-shot `pugi lsp hover ...` shape but wrong for L15's
+ * post-edit auto-diagnostics: every successful `edit`/`write` would
+ * otherwise pay the ~2-3s cold-start of `typescript-language-server`,
+ * which is unusable inside an agent loop.
+ *
+ * This module owns a singleton map keyed by `LspLanguage` with lazy
+ * initialization (`getOrStart`). The first edit of a TS file in a
+ * session pays cold-start; every subsequent edit of any TS/TSX file
+ * in the same workspace reuses the warm client.
+ *
+ * Lifecycle:
+ *  - `getOrStart(lang, cwd)` — spawn if missing, return cached otherwise.
+ *  - `stopAll()` — graceful shutdown of every cached client. Called from
+ *    `runCli` exit so a Ctrl-C never leaves zombie LSP processes behind.
+ *  - `reset()` — test-only escape hatch, drops the cache without
+ *    touching child processes (specs inject stubs that own their own
+ *    lifecycle).
+ *
+ * Failure handling: a startup failure is NOT cached. The next call
+ * tries again. This keeps the cache from poisoning a session when the
+ * operator installs the missing LSP binary mid-session and re-edits.
+ *
+ * Brand voice: ASCII only, no emoji, no banned words.
+ */
+import { isLspLanguageDisabled, startLspClient, } from './client.js';
+const cache = new Map();
+/**
+ * Return a warm client for `lang`, starting one if needed. The
+ * workspace `cwd` is captured at cache-insert time; if a subsequent
+ * call asks for the same language with a different `cwd` we tear
+ * down the old client and start a fresh one. This handles the
+ * agent-worktree case where the same process hops between workspace
+ * roots inside one Node lifetime.
+ */
+export async function getOrStartLspClient(lang, opts) {
+    // β7 L9: respect the per-language disable toggle BEFORE we attempt to
+    // spawn. The check is cheap and keeps the disabled path from paying
+    // the `npx --yes` warmup cost on first use.
+    if (isLspLanguageDisabled(lang, opts.lspSettings)) {
+        return {
+            ok: false,
+            reason: 'lsp_disabled',
+            detail: `${lang} is disabled via .pugi/settings.json::lsp`,
+        };
+    }
+    const existing = cache.get(lang);
+    if (existing && existing.cwd === opts.cwd) {
+        return { ok: true, client: existing.client };
+    }
+    if (existing && existing.cwd !== opts.cwd) {
+        // Workspace switched — stop the old client and fall through to spawn.
+        try {
+            await existing.client.stop();
+        }
+        catch {
+            // best effort; stop() is idempotent + swallow-safe
+        }
+        cache.delete(lang);
+    }
+    const result = await startLspClient(lang, opts);
+    if (!result.ok) {
+        return { ok: false, reason: result.reason, detail: result.detail };
+    }
+    cache.set(lang, { client: result.value, cwd: opts.cwd });
+    return { ok: true, client: result.value };
+}
+/** Look up the cached client without starting one. Returns undefined when missing. */
+export function peekLspClient(lang) {
+    return cache.get(lang)?.client;
+}
+/** Snapshot of currently-cached languages — used by `pugi lsp status` debug output. */
+export function listCachedLanguages() {
+    return Array.from(cache.keys());
+}
+/**
+ * Stop every cached client and clear the cache. Called from `runCli`
+ * exit and from specs that own the lifecycle of their stub servers.
+ */
+export async function stopAllLspClients() {
+    const snapshot = Array.from(cache.values());
+    cache.clear();
+    await Promise.all(snapshot.map(async (entry) => {
+        try {
+            await entry.client.stop();
+        }
+        catch {
+            // best effort — shutting down anyway
+        }
+    }));
+}
+/**
+ * Test-only: drop the cache map WITHOUT calling stop on the children.
+ * Specs that inject stub servers manage the stub lifecycle themselves;
+ * this lets a spec swap a stub mid-test without the cache holding a
+ * stale reference to a torn-down process.
+ */
+export function __resetLspCacheForTests() {
+    cache.clear();
+}
+//# sourceMappingURL=cache.js.map