@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.2

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

@@ -1,459 +0,0 @@
-/**
- * Repo detection helper —  (codegraph
- * context-aware auto-install).
- *
- * 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

@@ -1,134 +0,0 @@
-/**
- * Codegraph MCP install helper — .
- *
- * 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