@pugi/cli 0.1.0-beta.23 → 0.1.0-beta.25

package/dist/core/lsp/post-edit-diagnostics.js

@@ -0,0 +1,171 @@
+/**
+ * Post-edit diagnostics — Leak L15.
+ *
+ * Claude Code's leak intel surfaced this pattern: after a `FileEdit` /
+ * `Write` tool call lands, an LSP diagnostic pass runs on the touched
+ * file and the result is appended to the tool envelope before the
+ * model sees it. The model then self-corrects in the same turn —
+ * "TS2304: Cannot find name 'undef'" comes back, the model fixes the
+ * typo in the next tool call, no operator round-trip needed.
+ *
+ * This module is the Pugi side of that pattern:
+ *
+ *   1. The tool-bridge calls `runPostEditDiagnostics(path, ctx)` after
+ *      a successful `edit` / `write` / `multi_edit`.
+ *   2. We infer the language from the extension (`language-detect`).
+ *      Unsupported extension → `{ skip: true }` and the bridge appends
+ *      nothing.
+ *   3. We borrow (or lazily start) the per-language cached client
+ *      from `cache.ts`. A spawn failure → `{ skip: true }` and the
+ *      envelope stays clean. Silence on failure is intentional: an
+ *      operator who has not installed `typescript-language-server`
+ *      should not see an LSP nag on every edit.
+ *   4. We pull diagnostics with a hard 5s ceiling. A timeout logs a
+ *      warning on stderr (gated on `PUGI_LSP_DEBUG=1`) and skips —
+ *      the envelope is never blocked on LSP.
+ *   5. We format the surviving diagnostics into a readable tail
+ *      mirroring the leak format:
+ *
+ *         LSP DIAGNOSTICS (typescript):
+ *           foo.ts:42:5 error TS2304: Cannot find name 'undef'.
+ *           foo.ts:51:1 warn  TS6133: 'unused' is declared.
+ *
+ * The bridge concatenates this tail onto its existing `wrote ...` /
+ * `edited ...` body with a single newline separator. When there are
+ * zero diagnostics we return `{ skip: true }` so the existing body
+ * is unchanged — the "no news is good news" path stays terse.
+ *
+ * Brand voice: ASCII only, no emoji, no banned words.
+ */
+import { isAbsolute, relative, resolve } from 'node:path';
+import { getOrStartLspClient } from './cache.js';
+import { languageForFile } from './language-detect.js';
+const DEFAULT_TIMEOUT_MS = 5_000;
+/**
+ * Hard cap on how many diagnostics we surface to the model. A file
+ * with 200 errors after a broken bulk edit would otherwise blow the
+ * context window; the model can re-run `pugi lsp diagnostics` if
+ * it needs the full list.
+ */
+const MAX_DIAGNOSTICS = 25;
+export async function runPostEditDiagnostics(filePath, opts) {
+    const lang = languageForFile(filePath);
+    if (!lang) {
+        return { skip: true, reason: 'unsupported_language' };
+    }
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const clientResult = await loadClient(lang, opts);
+    if (!clientResult.ok) {
+        return { skip: true, reason: mapStartFailure(clientResult.reason) };
+    }
+    // Run diagnostics with a hard timeout. The underlying LspClient has
+    // its own per-request timeout (5s default) but a slow handshake
+    // can blow past it; we belt-and-suspenders here so the agent loop
+    // never blocks on LSP.
+    const relPath = toWorkspaceRelative(filePath, opts.cwd);
+    const diagnosticsPromise = clientResult.client.diagnostics(relPath);
+    let timer;
+    const timeoutPromise = new Promise((resolveFn) => {
+        timer = setTimeout(() => resolveFn({ timedOut: true }), timeoutMs);
+        timer.unref();
+    });
+    const race = await Promise.race([
+        diagnosticsPromise.then((value) => ({ timedOut: false, value })),
+        timeoutPromise,
+    ]);
+    if (timer)
+        clearTimeout(timer);
+    if (race.timedOut) {
+        const writeFn = opts.debugWrite ?? ((line) => {
+            if (process.env.PUGI_LSP_DEBUG === '1')
+                process.stderr.write(`${line}\n`);
+        });
+        writeFn(`[pugi-lsp] post-edit diagnostics for ${relPath} timed out after ${timeoutMs}ms (lang=${lang})`);
+        return { skip: true, reason: 'timeout' };
+    }
+    const diag = race.value;
+    if (!diag.ok) {
+        return { skip: true, reason: 'lsp_error' };
+    }
+    if (diag.value.length === 0) {
+        return { skip: true, reason: 'no_diagnostics' };
+    }
+    const tail = formatDiagnosticsTail(relPath, lang, diag.value);
+    return { skip: false, tail, count: diag.value.length, language: lang };
+}
+async function loadClient(lang, opts) {
+    if (opts.clientLoader) {
+        return opts.clientLoader(lang);
+    }
+    const { cwd, timeoutMs, clientLoader: _ignoredA, debugWrite: _ignoredB, ...rest } = opts;
+    const result = await getOrStartLspClient(lang, { cwd, ...rest });
+    if (!result.ok) {
+        return { ok: false, reason: result.reason, detail: result.detail };
+    }
+    return { ok: true, client: result.client };
+}
+function mapStartFailure(reason) {
+    if (reason === 'lsp_unavailable' || reason === 'language_unsupported')
+        return 'lsp_unavailable';
+    if (reason === 'lsp_disabled')
+        return 'lsp_disabled';
+    return 'lsp_error';
+}
+/**
+ * Convert an absolute or workspace-relative path into the form the
+ * LSP client expects — same shape as `runtime/commands/lsp.ts` uses.
+ */
+function toWorkspaceRelative(filePath, cwd) {
+    if (!isAbsolute(filePath))
+        return filePath;
+    const rel = relative(cwd, resolve(cwd, filePath));
+    return rel || filePath;
+}
+/**
+ * Format diagnostics into the leak-shaped envelope tail. Pure function
+ * exported for unit tests to assert the line format independent of
+ * any LSP plumbing.
+ */
+export function formatDiagnosticsTail(relPath, lang, diagnostics) {
+    const visible = diagnostics.slice(0, MAX_DIAGNOSTICS);
+    const truncated = diagnostics.length > visible.length;
+    const lines = [`LSP DIAGNOSTICS (${LANGUAGE_LABELS[lang]}):`];
+    for (const diag of visible) {
+        const line = diag.range.start.line + 1; // LSP is zero-based; humans expect 1-based.
+        const col = diag.range.start.character + 1;
+        const severity = SEVERITY_LABELS[diag.severityLabel];
+        const code = diag.code !== undefined && diag.code !== '' ? ` ${diag.code}` : '';
+        const source = diag.source ? `${diag.source}` : '';
+        const head = source ? `${severity}${code} (${source}):` : `${severity}${code}:`;
+        lines.push(`  ${relPath}:${line}:${col} ${head} ${diag.message}`);
+    }
+    if (truncated) {
+        lines.push(`  ... ${diagnostics.length - visible.length} more diagnostic(s) — re-run pugi lsp diagnostics ${relPath} for the full list`);
+    }
+    return lines.join('\n');
+}
+const LANGUAGE_LABELS = {
+    ts: 'typescript',
+    js: 'javascript',
+    py: 'python',
+    go: 'go',
+    rust: 'rust',
+};
+/**
+ * Map LSP severity label → the short token the leak envelope uses.
+ * "warn" is shorter than "warning" and matches Claude Code's leak
+ * verbatim; the rest mirror LSP terminology.
+ */
+const SEVERITY_LABELS = {
+    error: 'error',
+    warning: 'warn ',
+    info: 'info ',
+    hint: 'hint ',
+};
+/** Test-only surface so specs can poke the pure helpers without LSP. */
+export const __test__ = {
+    formatDiagnosticsTail,
+    MAX_DIAGNOSTICS,
+    DEFAULT_TIMEOUT_MS,
+};
+//# sourceMappingURL=post-edit-diagnostics.js.map

package/dist/core/repl/codebase-survey.js

@@ -0,0 +1,308 @@
+/**
+ * Codebase survey for the `/init` interview - Phase 2.
+ *
+ * Inspired by Claude Code's /init Phase 2 (the upstream spawns a
+ * Task-tool subagent to read manifest files + CI config + existing
+ * agent rules and produce a structured "what this repo is" digest).
+ * Independent implementation: Pugi's subagent infra is admin-api
+ * scheduled and not available in the local REPL boot path, so the
+ * survey runs as a direct filesystem scan instead. The shape of the
+ * output matches the upstream pattern - manifest, languages, build /
+ * test / lint commands, existing AI-tool configs - so the downstream
+ * Phase 3 / Phase 4 logic stays portable.
+ *
+ * # Design notes
+ *
+ * - Pure fs reads. No spawn, no network, no LLM call. Safe to run on
+ *   every `/init` invocation without rate-limit concern.
+ * - Bounded: every read caps at 16 KB to defend against an enormous
+ *   manifest pinning memory. Real package.json / pyproject.toml are
+ *   well under that.
+ * - Defensive: a missing or unreadable file maps to `undefined` in the
+ *   returned record. Phase 3 treats unknowns as "ask the operator".
+ * - Manifest grammar is closed: package.json (Node) and pyproject.toml
+ *   (Python) are recognised explicitly because Pugi customers ship one
+ *   of those nine times out of ten. Cargo.toml / go.mod / pom.xml are
+ *   detected by filename only - we surface "rust"/"go"/"java" as the
+ *   language hint but do not parse them, because the Phase 3 question
+ *   set asks for build commands directly when the manifest is opaque.
+ *
+ * # What we collect
+ *
+ *   1. `manifest`: which manifest file was found (closed enum).
+ *   2. `languages`: deduped list inferred from manifest + file extension
+ *      heuristics under the workspace root (one-level deep scan).
+ *   3. `packageManager`: pnpm / npm / yarn (Node only) or `unknown`.
+ *   4. `buildCommand` / `testCommand` / `lintCommand`: parsed out of
+ *      `package.json` scripts when a Node manifest is present.
+ *   5. `aiToolConfigs`: a record of which sibling-agent config files
+ *      already exist (CLAUDE.md, AGENTS.md, .cursorrules,
+ *      .github/copilot-instructions.md, .windsurfrules, .clinerules,
+ *      .mcp.json). Phase 4 mines these for "important parts" without
+ *      duplicating them into PUGI.md.
+ *   6. `hasReadme`, `hasGit`, `hasCi`: simple booleans for the
+ *      gap-question logic.
+ *   7. `hasExistingPugiMd`: true when re-running `/init` against a
+ *      workspace that already produced PUGI.md.
+ *
+ * # Why not spawn a Pugi subagent
+ *
+ * The Pugi subagent dispatcher (apps/pugi-cli/src/core/subagents/)
+ * speaks to admin-api over the SSE transport. Running the codebase
+ * survey through that path would (a) burn a tenant token quota on
+ * every `/init`, (b) require an online connection, and (c) round-trip
+ * structured data through the persona prompt - which is the wrong
+ * tool for "list which files exist". A direct fs scan is faster,
+ * deterministic, and works offline. The upstream Task-tool decision
+ * makes sense in a hosted product where every operation is metered;
+ * Pugi runs locally so we keep the survey local too.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Maximum bytes the survey reads from any single file. Real manifests
+ * are tiny (<8 KB); this cap defends against a hostile or accidental
+ * gigabyte JSON pinning the REPL boot.
+ */
+const MAX_READ_BYTES = 16 * 1024;
+/**
+ * Top-level directory scan budget. The survey looks at the workspace
+ * root + at most this many entries when inferring languages from file
+ * extensions. Deep walks are not needed - the manifest is the source
+ * of truth for the active stack.
+ */
+const MAX_TOP_LEVEL_ENTRIES = 200;
+/**
+ * Run a codebase survey against `workspaceRoot`. Pure: returns a
+ * snapshot record; the caller decides how to render it.
+ */
+export function surveyCodebase(workspaceRoot) {
+    const errors = [];
+    const manifest = detectManifest(workspaceRoot);
+    const packageJson = manifest === 'package.json'
+        ? safeReadJson(join(workspaceRoot, 'package.json'), errors)
+        : undefined;
+    const packageManager = inferPackageManager(workspaceRoot, packageJson);
+    const languages = inferLanguages(workspaceRoot, manifest, errors);
+    const scripts = (packageJson && typeof packageJson === 'object' && packageJson !== null
+        ? packageJson.scripts
+        : undefined) ?? {};
+    const buildCommand = pickScript(scripts, ['build', 'compile']);
+    const testCommand = pickScript(scripts, ['test', 'tests']);
+    const lintCommand = pickScript(scripts, ['lint', 'check']);
+    const formatCommand = pickScript(scripts, ['format', 'fmt', 'prettier']);
+    const aiToolConfigs = scanAiToolConfigs(workspaceRoot);
+    return {
+        workspaceRoot,
+        manifest,
+        packageManager,
+        languages,
+        buildCommand,
+        testCommand,
+        lintCommand,
+        formatCommand,
+        aiToolConfigs,
+        hasReadme: existsSafe(join(workspaceRoot, 'README.md')) ||
+            existsSafe(join(workspaceRoot, 'readme.md')),
+        hasGit: existsSafe(join(workspaceRoot, '.git')),
+        hasCi: detectCi(workspaceRoot),
+        hasExistingPugiMd: aiToolConfigs['PUGI.md'],
+        readErrors: errors,
+    };
+}
+/* ------------------------------------------------------------------ */
+/* Manifest detection                                                  */
+/* ------------------------------------------------------------------ */
+const MANIFEST_PROBE_ORDER = Object.freeze([
+    'package.json',
+    'pyproject.toml',
+    'Cargo.toml',
+    'go.mod',
+    'pom.xml',
+    'Gemfile',
+    'composer.json',
+]);
+function detectManifest(root) {
+    for (const candidate of MANIFEST_PROBE_ORDER) {
+        if (existsSafe(join(root, candidate)))
+            return candidate;
+    }
+    return 'unknown';
+}
+function inferPackageManager(root, packageJson) {
+    // package.json `packageManager` field wins when present (corepack convention).
+    if (packageJson &&
+        typeof packageJson === 'object' &&
+        packageJson !== null &&
+        'packageManager' in packageJson) {
+        const declared = packageJson.packageManager;
+        if (typeof declared === 'string') {
+            if (declared.startsWith('pnpm@'))
+                return 'pnpm';
+            if (declared.startsWith('yarn@'))
+                return 'yarn';
+            if (declared.startsWith('npm@'))
+                return 'npm';
+            if (declared.startsWith('bun@'))
+                return 'bun';
+        }
+    }
+    // Lockfile fallback.
+    if (existsSafe(join(root, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (existsSafe(join(root, 'yarn.lock')))
+        return 'yarn';
+    if (existsSafe(join(root, 'bun.lockb')) || existsSafe(join(root, 'bun.lock')))
+        return 'bun';
+    if (existsSafe(join(root, 'package-lock.json')))
+        return 'npm';
+    return 'unknown';
+}
+/* ------------------------------------------------------------------ */
+/* Language inference                                                  */
+/* ------------------------------------------------------------------ */
+const EXT_TO_LANG = Object.freeze({
+    '.ts': 'typescript',
+    '.tsx': 'typescript',
+    '.js': 'javascript',
+    '.jsx': 'javascript',
+    '.mjs': 'javascript',
+    '.cjs': 'javascript',
+    '.py': 'python',
+    '.rs': 'rust',
+    '.go': 'go',
+    '.java': 'java',
+    '.kt': 'kotlin',
+    '.swift': 'swift',
+    '.rb': 'ruby',
+    '.php': 'php',
+    '.cs': 'csharp',
+    '.cpp': 'cpp',
+    '.c': 'c',
+});
+const MANIFEST_TO_LANG = Object.freeze({
+    'package.json': ['javascript'],
+    'pyproject.toml': ['python'],
+    'Cargo.toml': ['rust'],
+    'go.mod': ['go'],
+    'pom.xml': ['java'],
+    'Gemfile': ['ruby'],
+    'composer.json': ['php'],
+    'unknown': [],
+});
+function inferLanguages(root, manifest, errors) {
+    const collected = new Set(MANIFEST_TO_LANG[manifest]);
+    // Top-level extension scan, bounded.
+    try {
+        const entries = readdirSync(root);
+        let scanned = 0;
+        for (const entry of entries) {
+            if (scanned >= MAX_TOP_LEVEL_ENTRIES)
+                break;
+            scanned += 1;
+            // Skip dotfiles + common dependency dirs - they pollute the
+            // language inference with build/cache content.
+            if (entry.startsWith('.') || entry === 'node_modules' || entry === 'dist')
+                continue;
+            const dot = entry.lastIndexOf('.');
+            if (dot <= 0)
+                continue;
+            const ext = entry.slice(dot);
+            const lang = EXT_TO_LANG[ext];
+            if (lang)
+                collected.add(lang);
+        }
+    }
+    catch (error) {
+        errors.push(`readdir ${root}: ${normalizeError(error)}`);
+    }
+    // `typescript` implies `javascript` runtime; keep both so the
+    // interview can ask "compiled-with vs run-with" if needed.
+    return Array.from(collected).sort();
+}
+/* ------------------------------------------------------------------ */
+/* Script picker                                                       */
+/* ------------------------------------------------------------------ */
+function pickScript(scripts, candidates) {
+    for (const key of candidates) {
+        const value = scripts[key];
+        if (typeof value === 'string' && value.trim().length > 0) {
+            // Surface the npm-style invocation so Phase 4 can quote it
+            // verbatim. The package manager name is filled in by the caller
+            // once it has resolved `packageManager`.
+            return key;
+        }
+    }
+    return undefined;
+}
+/* ------------------------------------------------------------------ */
+/* AI tool config scan                                                 */
+/* ------------------------------------------------------------------ */
+const AI_TOOL_CONFIG_PATHS = Object.freeze([
+    'CLAUDE.md',
+    'CLAUDE.local.md',
+    'AGENTS.md',
+    '.cursorrules',
+    '.cursor/rules',
+    '.github/copilot-instructions.md',
+    '.windsurfrules',
+    '.clinerules',
+    '.mcp.json',
+    'PUGI.md',
+    'PUGI.local.md',
+]);
+function scanAiToolConfigs(root) {
+    const result = {};
+    for (const rel of AI_TOOL_CONFIG_PATHS) {
+        result[rel] = existsSafe(join(root, rel));
+    }
+    return Object.freeze(result);
+}
+/* ------------------------------------------------------------------ */
+/* CI detection                                                        */
+/* ------------------------------------------------------------------ */
+const CI_PROBE_PATHS = Object.freeze([
+    '.github/workflows',
+    '.gitlab-ci.yml',
+    '.circleci/config.yml',
+    'azure-pipelines.yml',
+    '.travis.yml',
+    '.buildkite',
+]);
+function detectCi(root) {
+    return CI_PROBE_PATHS.some((rel) => existsSafe(join(root, rel)));
+}
+/* ------------------------------------------------------------------ */
+/* Safe IO helpers                                                     */
+/* ------------------------------------------------------------------ */
+function existsSafe(path) {
+    try {
+        return existsSync(path);
+    }
+    catch {
+        return false;
+    }
+}
+function safeReadJson(path, errors) {
+    try {
+        const stats = statSync(path);
+        if (!stats.isFile())
+            return undefined;
+        if (stats.size > MAX_READ_BYTES) {
+            errors.push(`oversize ${path}: ${stats.size} bytes`);
+            return undefined;
+        }
+        const raw = readFileSync(path, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        errors.push(`read ${path}: ${normalizeError(error)}`);
+        return undefined;
+    }
+}
+function normalizeError(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+//# sourceMappingURL=codebase-survey.js.map