@pugi/cli 0.1.0-beta.31 → 0.1.0-beta.35

package/dist/core/codegraph/detect-repo.js

@@ -0,0 +1,459 @@
+/**
+ * Repo detection helper — Wave 6 BIG TRACK 9 Phase 2 (codegraph
+ * context-aware auto-install, 2026-05-27).
+ *
+ * Walks up from `cwd` looking for a `.git/` directory; if found, runs a
+ * bounded scan (≤ MAX_SCAN_FILES files, depth-limited) to classify the
+ * repo size + detect primary languages. The result feeds two surfaces:
+ *
+ *   1. `pugi init` — when the repo is medium+ AND has a supported
+ *      primary language, the init flow asks the operator whether to
+ *      install the codegraph MCP server (Phase 1 example config →
+ *      auto-merged into .pugi/mcp.json).
+ *   2. Cold-start hook — every `pugi` invocation looks up the last-asked
+ *      timestamp; if the operator declined more than 30 days ago AND
+ *      the repo still triggers, we surface a one-line nudge.
+ *
+ * Why a stand-alone scanner (vs. reusing core/repo-map/scanner.ts):
+ *
+ *   - repo-map scans up to 5000 files with statSync per file to build a
+ *     symbol cache. We need a much cheaper classification: ≤ 1000 files,
+ *     no stat for size (just dirent.name), bail early on the first
+ *     manifest file we recognise. The 5000-file walker would dominate
+ *     cold-start latency on a monorepo.
+ *   - We deliberately do NOT respect .pugiignore here — codegraph cares
+ *     about the WHOLE repo (vendored libs included), not the operator's
+ *     curated workspace view. The repo-map scanner does the opposite.
+ *   - The output is structurally different (size category + language
+ *     manifest list) so even if we reused the walker the post-processing
+ *     would be different. Keeping the scans independent prevents one
+ *     surface's heuristics from leaking into the other.
+ *
+ * Pure module: no logging, no network, no telemetry. Errors during
+ * readdir on a subtree (permission denied, symlink loop) are swallowed
+ * and the walker continues — repo detection is best-effort context.
+ * The function NEVER throws; a malformed cwd returns `{ isRepo: false }`.
+ */
+import { readdirSync, existsSync, statSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+/**
+ * Maximum directories we descend into. A 1000-file repo classifies as
+ * "large" already; deeper walks add latency without changing the
+ * verdict. Hit this cap and we cap the file count at MAX_SCAN_FILES
+ * and return the verdict — the codegraph decision does not care
+ * whether the repo is 1001 or 100_001 files.
+ */
+export const MAX_SCAN_FILES = 1000;
+/**
+ * Hard cap on walk depth. Counted from `gitRoot`. Anything beyond is
+ * deep tooling output (node_modules, vendored deps, generated). The
+ * scanner short-circuits at this depth and the result is reported as
+ * `wasCapped: true` so the consumer can hint the operator if needed.
+ */
+export const MAX_SCAN_DEPTH = 6;
+/**
+ * Walk-up cap searching for the `.git/` parent. 12 ancestors matches
+ * the bootstrap.ts contract for project-marker detection — operators
+ * running `pugi` from `node_modules/foo/bar/baz` are an error case, not
+ * a feature.
+ */
+export const MAX_GIT_WALK = 12;
+/**
+ * Directory basenames we skip outright. These are pure noise for code
+ * navigation — vendored deps, build artefacts, version-control plumbing,
+ * cached test outputs. Trimming them at the dirent level keeps the scan
+ * O(useful-source-files) rather than O(everything-on-disk).
+ */
+const SKIP_DIRS = new Set([
+    '.git',
+    'node_modules',
+    'dist',
+    'build',
+    'out',
+    '.next',
+    '.nuxt',
+    '.turbo',
+    '.cache',
+    'coverage',
+    '__pycache__',
+    '.venv',
+    'venv',
+    'target',
+    '.gradle',
+    '.idea',
+    '.vscode',
+    '.pugi',
+]);
+/**
+ * Source-file extensions that count toward the size category. Mirrors
+ * the codegraph upstream's own language list (tree-sitter grammars for
+ * 19 languages) but pruned to the set that we actually return as
+ * `supported` languages — the categorisation must agree with the
+ * language-match gate that drives the install prompt.
+ */
+const SOURCE_EXTENSIONS = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+    '.py',
+    '.rs',
+    '.go',
+    '.java', '.kt', '.kts',
+    '.rb',
+    '.php',
+    '.c', '.h', '.cpp', '.hpp', '.cc', '.cxx',
+    '.cs',
+    '.swift',
+    '.scala',
+]);
+export const CODEGRAPH_SUPPORTED_LANGUAGES = Object.freeze([
+    'typescript',
+    'javascript',
+    'python',
+    'rust',
+    'go',
+    'java',
+]);
+const MANIFEST_HINTS = Object.freeze([
+    { filename: 'package.json', languages: ['javascript', 'typescript'] },
+    { filename: 'tsconfig.json', languages: ['typescript'] },
+    { filename: 'pyproject.toml', languages: ['python'] },
+    { filename: 'requirements.txt', languages: ['python'] },
+    { filename: 'setup.py', languages: ['python'] },
+    { filename: 'Pipfile', languages: ['python'] },
+    { filename: 'Cargo.toml', languages: ['rust'] },
+    { filename: 'go.mod', languages: ['go'] },
+    { filename: 'pom.xml', languages: ['java'] },
+    { filename: 'build.gradle', languages: ['java'] },
+    { filename: 'build.gradle.kts', languages: ['java'] },
+]);
+/**
+ * Walk up from `cwd` looking for `.git/`. Returns the absolute path of
+ * the git-root directory OR null if none is found within the walk cap.
+ */
+export function findGitRoot(cwd) {
+    let current = resolve(cwd);
+    for (let i = 0; i < MAX_GIT_WALK; i += 1) {
+        if (existsSync(join(current, '.git')))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+    return null;
+}
+/**
+ * Read manifest files at the git root + classify their languages.
+ * Pure file-system stat — we do NOT parse the manifests (a malformed
+ * package.json should not break detection). Multiple manifests can
+ * hit; e.g. a polyglot repo with package.json + pyproject.toml lights
+ * up both `typescript`/`javascript` and `python`.
+ *
+ * `package.json` is special-cased: if a `tsconfig.json` lives next to
+ * it we drop the `javascript` hint so a pure-TS repo doesn't get
+ * counted twice. JS-only repos surface as `javascript`.
+ */
+function detectManifestLanguages(gitRoot) {
+    const out = new Set();
+    const hasTsconfig = existsSync(join(gitRoot, 'tsconfig.json'));
+    for (const hint of MANIFEST_HINTS) {
+        if (!existsSync(join(gitRoot, hint.filename)))
+            continue;
+        for (const lang of hint.languages) {
+            if (hint.filename === 'package.json' && hasTsconfig && lang === 'javascript') {
+                continue;
+            }
+            out.add(lang);
+        }
+    }
+    return out;
+}
+/**
+ * Bounded BFS-by-stack walk from `root`. Caps at MAX_SCAN_FILES +
+ * MAX_SCAN_DEPTH. Returns `{ srcCount, languages, wasCapped }`.
+ *
+ * Why a manual stack rather than `readdirSync({ recursive: true })`:
+ * the recursive readdir loads the entire tree into memory before we
+ * see the first entry; on a monorepo we would walk node_modules
+ * (forbidden) before our SKIP_DIRS filter could fire. A manual stack
+ * lets us prune at every level.
+ */
+function scanRepo(root) {
+    const languagesFromExt = new Set();
+    let srcCount = 0;
+    let wasCapped = false;
+    // Per-language file counts so we can apply the "at least 3 files"
+    // threshold below — a single stray .py in a TS repo should not light
+    // up python.
+    const perLang = new Map();
+    const stack = [{ abs: root, depth: 0 }];
+    while (stack.length > 0) {
+        const frame = stack.pop();
+        if (!frame)
+            break;
+        if (frame.depth > MAX_SCAN_DEPTH) {
+            wasCapped = true;
+            continue;
+        }
+        let entries;
+        try {
+            entries = readdirSync(frame.abs, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (srcCount >= MAX_SCAN_FILES) {
+                wasCapped = true;
+                break;
+            }
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name))
+                    continue;
+                if (entry.name.startsWith('.') && entry.name !== '.') {
+                    // Skip hidden dirs that are NOT in our whitelist (e.g. .yarn,
+                    // .pnpm-store). .pugi/.git are already in SKIP_DIRS.
+                    continue;
+                }
+                stack.push({ abs: join(frame.abs, entry.name), depth: frame.depth + 1 });
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const ext = extensionOf(entry.name);
+            if (!ext)
+                continue;
+            if (!SOURCE_EXTENSIONS.has(ext))
+                continue;
+            srcCount += 1;
+            const lang = languageForExtension(ext);
+            if (lang) {
+                perLang.set(lang, (perLang.get(lang) ?? 0) + 1);
+            }
+        }
+        if (srcCount >= MAX_SCAN_FILES) {
+            wasCapped = true;
+            break;
+        }
+    }
+    // Promote per-language counts to detected languages with a noise
+    // floor. The threshold is intentionally low (3) so a small repo
+    // with a handful of Python utility scripts in an otherwise-TS
+    // codebase still surfaces as polyglot.
+    for (const [lang, count] of perLang.entries()) {
+        if (count >= 3)
+            languagesFromExt.add(lang);
+    }
+    return { srcCount, languagesFromExt, wasCapped };
+}
+/**
+ * Map a file extension to a SupportedLanguage. Returns null for
+ * extensions we count toward the size category but do NOT surface as
+ * supported languages (c, cs, swift, scala, …) — codegraph supports
+ * more languages than our nudge gate.
+ */
+export function languageForExtension(ext) {
+    switch (ext) {
+        case '.ts':
+        case '.tsx':
+            return 'typescript';
+        case '.js':
+        case '.jsx':
+        case '.mjs':
+        case '.cjs':
+            return 'javascript';
+        case '.py':
+            return 'python';
+        case '.rs':
+            return 'rust';
+        case '.go':
+            return 'go';
+        case '.java':
+        case '.kt':
+        case '.kts':
+            return 'java';
+        default:
+            return null;
+    }
+}
+/**
+ * Lowercase extension including the leading dot. Returns null for
+ * dotfiles (no extension) and for paths without a dot.
+ */
+function extensionOf(filename) {
+    const idx = filename.lastIndexOf('.');
+    if (idx <= 0)
+        return null;
+    // `.env` style dotfiles return `'.env'` from lastIndexOf — they
+    // are filtered by the SOURCE_EXTENSIONS membership check below
+    // since `.env` is not in the source-language set.
+    return filename.slice(idx).toLowerCase();
+}
+/**
+ * Classify a file count into the small / medium / large bucket. Pure —
+ * exposed so spec callers can pin the exact thresholds independent of
+ * the rest of the walker. Operators reading the prompt copy MUST see
+ * the same boundaries the implementation enforces.
+ */
+export function categoriseSize(srcCount) {
+    if (srcCount <= 50)
+        return 'small';
+    if (srcCount <= 500)
+        return 'medium';
+    return 'large';
+}
+/**
+ * Single entry-point. Pure. Never throws. Returns the structured
+ * verdict so the init prompt + cold-start hook + status command can
+ * all branch off one shared computation.
+ */
+export function detectRepo(cwd) {
+    let absCwd;
+    try {
+        absCwd = resolve(cwd);
+        const stat = statSync(absCwd);
+        if (!stat.isDirectory()) {
+            return { isRepo: false, reason: 'unreadable-cwd' };
+        }
+    }
+    catch {
+        return { isRepo: false, reason: 'unreadable-cwd' };
+    }
+    const gitRoot = findGitRoot(absCwd);
+    if (!gitRoot) {
+        return { isRepo: false, reason: 'no-git' };
+    }
+    const manifestLangs = detectManifestLanguages(gitRoot);
+    const { srcCount, languagesFromExt, wasCapped } = scanRepo(gitRoot);
+    const allLangs = new Set();
+    for (const lang of manifestLangs)
+        allLangs.add(lang);
+    for (const lang of languagesFromExt)
+        allLangs.add(lang);
+    const sortedLangs = [...allLangs].sort();
+    const sizeCategory = categoriseSize(srcCount);
+    const offerCodegraph = sizeCategory !== 'small' && sortedLangs.length > 0;
+    return {
+        isRepo: true,
+        gitRoot,
+        sizeCategory,
+        primarySymbolCount: srcCount,
+        languages: sortedLangs,
+        offerCodegraph,
+        wasCapped,
+    };
+}
+/**
+ * Render the cold-start nudge copy. Pure — exposed for spec parity so
+ * the cold-start hook + the spec assert against the same line.
+ *
+ *   "Detected medium TypeScript repo with ~200 src files. Install
+ *    codegraph MCP for symbol-aware code navigation? (Y/n)"
+ *
+ * The "~N" formatting rounds to the nearest 10 so the operator does
+ * not see a flapping count between scans on the same repo (one stray
+ * test fixture would change a precise N by 1).
+ */
+export function buildOfferCopy(detection) {
+    const noun = humanLanguageLabel(detection.languages);
+    const sizeLabel = detection.sizeCategory === 'large' ? 'large' : 'medium';
+    const approx = approxFileCount(detection.primarySymbolCount, detection.wasCapped);
+    const strength = detection.sizeCategory === 'large' ? 'strongly recommended' : 'recommended';
+    return `Detected ${sizeLabel} ${noun} repo with ${approx} src files (${strength}). Install codegraph MCP for symbol-aware code navigation? (Y/n)`;
+}
+/**
+ * Render the "X days old, refresh?" reminder copy. Single sentence,
+ * one CTA. The session module surfaces this on the system pane when
+ * the codegraph mcp.json entry exists but `lastIndexedAt` is stale.
+ */
+export function buildStaleIndexCopy(daysOld) {
+    return `Codegraph index is ${daysOld} day${daysOld === 1 ? '' : 's'} old. Run /codegraph-status to refresh.`;
+}
+/**
+ * Render the primary language label for the prompt. We use the
+ * first detected language (alphabetic order from `detectRepo`) so
+ * the copy is deterministic. Multi-language repos get a generic
+ * `polyglot` suffix — saves us from enumerating "TypeScript +
+ * Python + Rust + …" in the headline.
+ */
+function humanLanguageLabel(langs) {
+    if (langs.length === 0)
+        return 'source';
+    const primary = labelFor(langs[0]);
+    if (langs.length === 1)
+        return primary;
+    return `${primary} polyglot`;
+}
+function labelFor(lang) {
+    switch (lang) {
+        case 'typescript': return 'TypeScript';
+        case 'javascript': return 'JavaScript';
+        case 'python': return 'Python';
+        case 'rust': return 'Rust';
+        case 'go': return 'Go';
+        case 'java': return 'Java';
+    }
+}
+function approxFileCount(count, wasCapped) {
+    if (wasCapped)
+        return `${MAX_SCAN_FILES}+`;
+    if (count < 10)
+        return String(count);
+    const rounded = Math.round(count / 10) * 10;
+    return `~${rounded}`;
+}
+/**
+ * Parse a manifest hint into its declared languages. Tiny export so
+ * spec callers can drive the same map without re-declaring it.
+ */
+export function manifestHintFor(filename) {
+    for (const hint of MANIFEST_HINTS) {
+        if (hint.filename === filename)
+            return hint.languages;
+    }
+    return null;
+}
+/**
+ * Best-effort manifest-only language detection. Useful for callers
+ * that already have a `gitRoot` and do NOT want to walk the filesystem
+ * (e.g. /codegraph-status, which trusts the existing scan cache).
+ *
+ * The file-IO is just `existsSync` per manifest — no read/parse. A
+ * package.json that mentions Python in its `engines` will NOT light up
+ * python here; that is by design. The full scan is the source of truth.
+ */
+export function detectManifestLanguagesPublic(gitRoot) {
+    return [...detectManifestLanguages(gitRoot)].sort();
+}
+/**
+ * Sniff whether a manifest is structurally JSON. Pure — exposed only
+ * so a future surface can avoid double-checking. The manifest probe
+ * itself does NOT depend on this; it uses existsSync and trusts the
+ * filename heuristic.
+ *
+ * @internal
+ */
+export function looksLikeJson(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return false;
+    return trimmed.startsWith('{') || trimmed.startsWith('[');
+}
+/**
+ * Read the contents of a manifest file. Truncated к 8 KiB so a
+ * misnamed multi-MB file (e.g. a vendored lockfile masquerading as
+ * package.json) cannot stall the detector. Returns null on any IO
+ * error. Reserved for future use by surfaces that want manifest
+ * content beyond presence checks.
+ *
+ * @internal
+ */
+export function readManifestTruncated(absPath, maxBytes = 8 * 1024) {
+    try {
+        const raw = readFileSync(absPath, 'utf8');
+        return raw.length > maxBytes ? raw.slice(0, maxBytes) : raw;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=detect-repo.js.map

package/dist/core/codegraph/install.js

@@ -0,0 +1,134 @@
+/**
+ * Codegraph MCP install helper — Wave 6 BIG TRACK 9 Phase 2.
+ *
+ * Writes the codegraph MCP server config к `.pugi/mcp.json` so the
+ * registry loader picks it up on the next dispatch. Mirrors the
+ * Phase 1 example config at `apps/pugi-cli/docs/examples/codegraph.mcp.json`
+ * — same `codegraph serve --mcp` command + `pending` trust state. The
+ * operator still has to run `pugi mcp trust codegraph` before tools
+ * actually surface; the install path NEVER auto-trusts, by design.
+ *
+ * Idempotent: re-running on a workspace that already has a `codegraph`
+ * entry is a no-op + returns `{ status: 'already-installed' }`. Other
+ * MCP servers in the same file are preserved.
+ *
+ * The function is intentionally NOT bundled into core/mcp/ to keep
+ * the codegraph product (install copy, decision store, language gate)
+ * one cohesive module. The MCP registry is a generic surface; the
+ * codegraph adoption is a feature on top of it.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+/**
+ * Canonical config shape we write into `.pugi/mcp.json` under the
+ * `codegraph` key. Matches `mcpServerConfigSchema` (Zod) in
+ * core/mcp/client.ts and the published example at docs/examples/
+ * codegraph.mcp.json. Drift here MUST land alongside a registry
+ * schema change OR the next dispatch crashes with a validation error.
+ */
+export const CODEGRAPH_MCP_ENTRY = Object.freeze({
+    command: 'codegraph',
+    args: Object.freeze(['serve', '--mcp']),
+    env: Object.freeze({}),
+    trust: 'pending',
+});
+/**
+ * Documentation URL surfaced after a successful install so the operator
+ * knows how to actually run codegraph index commands. Single source of
+ * truth — both the init flow and the /codegraph-status command pull
+ * from this constant.
+ */
+export const CODEGRAPH_DOCS_URL = 'https://github.com/colbymchenry/codegraph';
+/**
+ * Merge the codegraph entry into `.pugi/mcp.json`. Creates the file
+ * (with `{ schema: 1, servers: { codegraph: ... } }`) when it does not
+ * exist. Preserves every other server entry on disk.
+ *
+ * @param workspaceRoot absolute path to the project root that owns the
+ *                      `.pugi/` directory. The caller is responsible for
+ *                      ensuring `.pugi/` exists (the install helper
+ *                      creates it as a defensive fallback).
+ */
+export function installCodegraphMcpEntry(workspaceRoot) {
+    const pugiDir = resolve(workspaceRoot, '.pugi');
+    const configPath = resolve(pugiDir, 'mcp.json');
+    try {
+        if (!existsSync(pugiDir)) {
+            mkdirSync(pugiDir, { recursive: true });
+        }
+        let existing = {};
+        if (existsSync(configPath)) {
+            try {
+                const raw = readFileSync(configPath, 'utf8');
+                if (raw.trim().length > 0) {
+                    const parsed = JSON.parse(raw);
+                    if (parsed && typeof parsed === 'object') {
+                        existing = parsed;
+                    }
+                }
+            }
+            catch (error) {
+                return {
+                    status: 'failed',
+                    reason: `cannot parse existing .pugi/mcp.json: ${error.message}`,
+                };
+            }
+        }
+        const servers = (existing.servers && typeof existing.servers === 'object')
+            ? { ...existing.servers }
+            : {};
+        if (servers['codegraph']) {
+            return { status: 'already-installed', configPath };
+        }
+        servers['codegraph'] = {
+            command: CODEGRAPH_MCP_ENTRY.command,
+            args: [...CODEGRAPH_MCP_ENTRY.args],
+            env: { ...CODEGRAPH_MCP_ENTRY.env },
+            trust: CODEGRAPH_MCP_ENTRY.trust,
+        };
+        const out = {
+            schema: typeof existing.schema === 'number' ? existing.schema : 1,
+            servers,
+        };
+        writeFileSync(configPath, `${JSON.stringify(out, null, 2)}\n`, { mode: 0o600 });
+        return { status: 'installed', configPath };
+    }
+    catch (error) {
+        return { status: 'failed', reason: error.message };
+    }
+}
+/**
+ * Check whether `.pugi/mcp.json` already declares the `codegraph`
+ * server. Pure best-effort — a malformed file returns false (we err
+ * on the side of "not installed" so the operator can re-trigger the
+ * install path instead of being silently locked out).
+ *
+ * Returns the parsed `trust` state when present so callers can render
+ * the right status copy ("declared, awaiting trust" vs "active").
+ */
+export function detectCodegraphInstalled(workspaceRoot) {
+    const configPath = resolve(workspaceRoot, '.pugi/mcp.json');
+    if (!existsSync(configPath)) {
+        return { installed: false, trust: null, configPath };
+    }
+    try {
+        const raw = readFileSync(configPath, 'utf8');
+        if (raw.trim().length === 0) {
+            return { installed: false, trust: null, configPath };
+        }
+        const parsed = JSON.parse(raw);
+        const codegraph = parsed.servers?.['codegraph'];
+        if (!codegraph) {
+            return { installed: false, trust: null, configPath };
+        }
+        return {
+            installed: true,
+            trust: codegraph.trust === 'trusted' || codegraph.trust === 'denied' ? codegraph.trust : 'pending',
+            configPath,
+        };
+    }
+    catch {
+        return { installed: false, trust: null, configPath };
+    }
+}
+//# sourceMappingURL=install.js.map