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

package/dist/runtime/commands/doctor.js

@@ -1,579 +0,0 @@
-/**
- * `pugi doctor` — environment health report ().
- *
- * Parity command with the upstream tool's `/doctor` (gap doc:
- * docs/research/2026-05-27-pugi-.md §6). Probes
- * auth, API reachability, CLI version, workspace state, disk space,
- * Node version, pnpm, git, MCP servers, config file, and session
- * activity. Emits either a human-readable table OR a structured JSON
- * envelope depending on `--json`.
- *
- * Module contract:
- *
- *  - This file owns the WIRING from CLI flags + workspace context to
- *    the probe runner. The probes themselves live in
- *    `core/diagnostics/probes/*.ts` and have NO module-level coupling
- *    to the CLI dispatch surface.
- *
- *  - `runDoctorCommand` is the single entry point. Both the top-level
- *    `pugi doctor` handler in `runtime/cli.ts` AND the in-REPL
- *    `/doctor` slash command call it. The function returns the
- *    `DoctorReport` so the REPL can render via the Ink table without
- *    re-running the probes.
- *
- *  - Exit codes are derived from `exitCodeFor(overall)` in
- *    `core/diagnostics/types.ts` and bubble up via `process.exitCode`
- *    (matches the convention of every other CLI handler in cli.ts).
- *
- *  - The MCP probe is opportunistic: if `core/mcp/registry.js` is
- *    unavailable for any reason (e.g. sibling L13 not yet landed,
- *    unexpected schema change), the probe degrades to a graceful
- *    `skipped` result so the rest of the table still renders.
- */
-import { execFileSync } from 'node:child_process';
-import { constants as fsConstants, existsSync, accessSync, readFileSync, statSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { resolve as resolvePath } from 'node:path';
-import { resolveActiveCredential } from '../../core/credentials.js';
-import { loadSettings } from '../../core/settings.js';
-import { resolveMode } from '../../core/permissions/state.js';
-import { toolRegistry } from '../../tools/registry.js';
-import { PUGI_CLI_VERSION } from '../version.js';
-import { runProbes, } from '../../core/diagnostics/probe-runner.js';
-import { computeOverall, countProbes, exitCodeFor, } from '../../core/diagnostics/types.js';
-import { probeAuth } from '../../core/diagnostics/probes/auth.js';
-import { probeApi } from '../../core/diagnostics/probes/api.js';
-import { probeCliVersion } from '../../core/diagnostics/probes/cli-version.js';
-import { probeWorkspace } from '../../core/diagnostics/probes/workspace.js';
-import { probeDisk } from '../../core/diagnostics/probes/disk.js';
-import { probeNode } from '../../core/diagnostics/probes/node.js';
-import { probePnpm } from '../../core/diagnostics/probes/pnpm.js';
-import { probeGit } from '../../core/diagnostics/probes/git.js';
-import { probeMcp } from '../../core/diagnostics/probes/mcp.js';
-import { probeConfig } from '../../core/diagnostics/probes/config.js';
-import { probeSession } from '../../core/diagnostics/probes/session.js';
-import { probeDenialTracking } from '../../core/diagnostics/probes/denial-tracking.js';
-import { probeBareMode } from '../../core/diagnostics/probes/bare-mode.js';
-import { probePugiMdHierarchy } from '../../core/diagnostics/probes/pugi-md.js';
-import { probeSandbox } from '../../core/diagnostics/probes/sandbox.js';
-import { probeHooks } from '../../core/diagnostics/probes/hooks.js';
-import { probeEngineLive } from '../../core/diagnostics/probes/engine-live.js';
-/**
- * Default API URL when no PUGI_API_URL env override is set. Mirrors
- * the constant in `core/credentials.ts` (kept local to avoid an
- * extra named export from that module).
- */
-const DEFAULT_API_URL = 'https://api.pugi.io';
-/**
- * Build the standard probe set with production dependencies. Exported
- * for the spec so the test can construct the same suite with stub
- * deps + assert per-probe ordering + fail-isolation in isolation.
- */
-export function buildDefaultProbes(ctx, options = {}) {
-    const fetchImpl = ctx.fetchImpl ?? globalThis.fetch.bind(globalThis);
-    const now = Date.now;
-    const probes = [
-        {
-            name: 'AUTH',
-            run: () => probeAuth(ctx, {
-                resolveCredential: (env, home) => {
-                    const credential = resolveActiveCredential(env, home);
-                    if (!credential)
-                        return null;
-                    return { apiUrl: credential.apiUrl, apiKey: credential.apiKey };
-                },
-                fetchImpl,
-                now,
-            }),
-            timeoutMs: 4_000,
-        },
-        {
-            name: 'API',
-            run: () => probeApi(ctx, {
-                resolveApiUrl: (env) => {
-                    return env.PUGI_API_URL ?? DEFAULT_API_URL;
-                },
-                fetchImpl,
-                now,
-            }),
-            timeoutMs: 4_000,
-        },
-        {
-            name: 'CLI VERSION',
-            run: () => probeCliVersion({
-                localVersion: options.localCliVersion ?? PUGI_CLI_VERSION,
-                fetchImpl,
-                now,
-            }),
-            timeoutMs: 4_000,
-        },
-        {
-            name: 'WORKSPACE',
-            run: async () => probeWorkspace(ctx, {
-                existsSync,
-                statSync,
-                accessSync,
-                W_OK: fsConstants.W_OK,
-            }),
-        },
-        {
-            name: 'DISK',
-            run: async () => probeDisk(ctx, {
-                getFreeBytes: (home) => getFreeBytesViaDf(home),
-            }),
-        },
-        {
-            name: 'NODE',
-            run: async () => probeNode({ version: process.version }),
-        },
-        {
-            name: 'PNPM',
-            run: async () => probePnpm({
-                resolveVersion: () => execFileSync('pnpm', ['--version'], {
-                    encoding: 'utf8',
-                    timeout: 2_000,
-                    stdio: ['ignore', 'pipe', 'ignore'],
-                }).trim(),
-            }),
-        },
-        {
-            name: 'GIT',
-            run: async () => probeGit(ctx, {
-                resolveVersion: () => execFileSync('git', ['--version'], {
-                    encoding: 'utf8',
-                    timeout: 2_000,
-                    stdio: ['ignore', 'pipe', 'ignore'],
-                }).trim(),
-                isInWorkTree: (cwd) => {
-                    try {
-                        const result = execFileSync('git', ['-C', cwd, 'rev-parse', '--is-inside-work-tree'], {
-                            encoding: 'utf8',
-                            timeout: 2_000,
-                            stdio: ['ignore', 'pipe', 'ignore'],
-                        }).trim();
-                        return result === 'true';
-                    }
-                    catch {
-                        return false;
-                    }
-                },
-                resolveHeadSha: (cwd) => {
-                    try {
-                        return execFileSync('git', ['-C', cwd, 'rev-parse', 'HEAD'], {
-                            encoding: 'utf8',
-                            timeout: 2_000,
-                            stdio: ['ignore', 'pipe', 'ignore'],
-                        }).trim();
-                    }
-                    catch {
-                        return null;
-                    }
-                },
-                resolveRoot: (cwd) => {
-                    try {
-                        return execFileSync('git', ['-C', cwd, 'rev-parse', '--show-toplevel'], {
-                            encoding: 'utf8',
-                            timeout: 2_000,
-                            stdio: ['ignore', 'pipe', 'ignore'],
-                        }).trim();
-                    }
-                    catch {
-                        return null;
-                    }
-                },
-            }),
-        },
-        {
-            name: 'MCP SERVERS',
-            run: async () => probeMcpSafely(ctx),
-        },
-        {
-            name: 'CONFIG',
-            run: async () => probeConfig(ctx, {
-                existsSync,
-                readFileSync: (p, encoding) => readFileSync(p, encoding),
-            }),
-        },
-        {
-            name: 'SESSION',
-            run: async () => probeSession(ctx, {
-                existsSync,
-                statSync,
-                readFileSync: (p, encoding) => readFileSync(p, encoding),
-            }, {
-                now,
-                ...(options.liveSessionId ? { liveSessionId: options.liveSessionId } : {}),
-            }),
-        },
-        // L11 : DENIAL TRACKING probe. Reports the live
-        // session's denial pressure when the REPL adapter wired the
-        // tracker through `runDoctorCommand`; degrades к `skipped` for
-        // top-level `pugi doctor` calls outside the REPL.
-        {
-            name: 'DENIAL TRACKING',
-            run: async () => probeDenialTracking({
-                ...(options.denialTracking ? { tracker: options.denialTracking } : {}),
-            }),
-        },
-        // BARE MODE row. Always present so the JSON
-        // schema stays stable; status flips to `ok` when `--bare` or
-        // `PUGI_BARE=1` is active, otherwise `skipped`.
-        {
-            name: 'BARE MODE',
-            run: async () => probeBareMode({ env: ctx.env }),
-        },
-        // PUGI.md HIERARCHY row. Reports how many
-        // ambient `PUGI.md` / `CLAUDE.md` files the cwd → homedir walk
-        // discovered, and the closest path. `skipped` when bare mode is
-        // active (walk disabled) or zero files found.
-        // SANDBOX row. Reports the platform's available
-        // OS-level sandbox primitive (Seatbelt / Landlock / AppContainer) and
-        // surfaces a `warning` status until the bash-tool sandbox adapter 
-        // is armed. Operator-trust gap visibility — better к flag "not yet
-        // jailed" loud than let operators assume it's already on.
-        {
-            name: 'SANDBOX',
-            run: async () => probeSandbox(ctx),
-        },
-        // HOOKS row. Validates `.pugi/hooks-mvp.json`
-        // + `.pugi/hook-chains.json` syntax + shape before the first tool
-        // dispatch fires. Absence = skipped (most workspaces don't ship
-        // hooks); bad JSON = error с remediation hint.
-        {
-            name: 'HOOKS',
-            run: async () => probeHooks(ctx, {
-                existsSync,
-                readFileSync: (p, encoding) => readFileSync(p, encoding),
-            }),
-        },
-        {
-            name: 'PUGI.md HIERARCHY',
-            run: async () => probePugiMdHierarchy({
-                cwd: ctx.cwd,
-                homedir: ctx.home,
-                env: ctx.env,
-            }),
-        },
-    ];
-    // CEO P1 #22 : ENGINE LIVE probe — end-to-end smoke
-    // against api.pugi.io. Only fires when `--live` is set so the
-    // default `pugi doctor` stays offline-safe.
-    if (options.live) {
-        probes.push({
-            name: 'ENGINE LIVE',
-            run: async () => probeEngineLive(ctx, {
-                resolveApiUrl: (env) => env['PUGI_API_URL'] ?? 'https://api.pugi.io',
-                resolveApiKey: (env) => {
-                    const fromEnv = env['PUGI_API_KEY'];
-                    if (fromEnv && fromEnv.length > 0)
-                        return fromEnv;
-                    const credential = resolveActiveCredential(env, ctx.home);
-                    return credential?.apiKey ?? null;
-                },
-                fetchImpl,
-                now,
-            }),
-            timeoutMs: 20_000,
-        });
-    }
-    return probes;
-}
-/**
- * Run the full doctor sweep + emit the output via the supplied
- * writeOutput sink. Returns the report so REPL callers can route it
- * к the Ink renderer instead of the plain-text fallback.
- */
-export async function runDoctorCommand(ctx) {
-    const probeCtx = {
-        cwd: ctx.cwd,
-        home: ctx.home,
-        env: ctx.env,
-    };
-    const probes = buildDefaultProbes(probeCtx, {
-        ...(ctx.liveSessionId ? { liveSessionId: ctx.liveSessionId } : {}),
-        ...(ctx.denialTracking ? { denialTracking: ctx.denialTracking } : {}),
-        ...(ctx.live ? { live: ctx.live } : {}),
-    });
-    const report = await runProbes(probes);
-    // Defensive recompute: even though runProbes already computed the
-    // overall + counts, recomputing here documents the invariant for the
-    // reader and gives the JSON envelope a single source of truth.
-    const overall = computeOverall(report.probes);
-    const counts = countProbes(report.probes);
-    // Envelope enrichment : four additive fields surfaced
-    // directly on the envelope so support flows can grep them without
-    // walking the per-probe array.
-    //
-    //  - pugiDir        : boolean smoke for "is this a Pugi workspace?"
-    //  - permissionMode : resolved permission slug (settings → session → global → default)
-    //  - tools          : snapshot of the dispatch-engine tool registry
-    //  - protectedFile  : protected-files gate spot-check against `.env`
-    //
-    // Every read is local + defensive. Settings load can throw on
-    // malformed JSON; we trap and fall back to the canonical default so
-    // doctor stays single-shot reliable.
-    const pugiDirPath = resolvePath(ctx.cwd, '.pugi');
-    const pugiDirExists = safeExistsSync(pugiDirPath);
-    const permissionMode = resolveWorkspacePermissionMode(ctx.cwd, ctx.home);
-    const tools = snapshotToolRegistry();
-    const protectedFile = evaluateProtectedFile('.env');
-    const envelope = {
-        command: 'doctor',
-        overall,
-        counts,
-        durationMs: report.durationMs,
-        probes: report.probes,
-        pugiDir: pugiDirExists,
-        permissionMode,
-        tools,
-        protectedFile,
-        meta: {
-            cliVersion: PUGI_CLI_VERSION,
-            nodeVersion: process.version,
-            cwd: ctx.cwd,
-            pugiDirPath: pugiDirExists ? pugiDirPath : null,
-        },
-    };
-    const text = renderDoctorTable(envelope);
-    ctx.writeOutput(envelope, text);
-    process.exitCode = exitCodeFor(overall);
-    return { ...report, overall, counts };
-}
-/**
- * Plain-text table renderer. Mirrors the layout from the leak-parity
- * spec but is intentionally column-light (3 columns: NAME / STATUS /
- * DETAIL) so it composes well in narrow terminals without dragging
- * a layout library into the CLI hot path. The Ink TUI renderer in
- * `tui/doctor-table.tsx` is the colour-aware variant used inside the
- * REPL.
- */
-export function renderDoctorTable(envelope) {
-    const NAME_WIDTH = Math.max('NAME'.length, ...envelope.probes.map((row) => row.name.length));
-    const STATUS_WIDTH = Math.max('STATUS'.length, ...envelope.probes.map((row) => row.status.length));
-    const lines = [];
-    lines.push('Pugi Doctor — environment health report');
-    lines.push('='.repeat(50));
-    lines.push('');
-    for (const row of envelope.probes) {
-        const namePart = row.name.padEnd(NAME_WIDTH, ' ');
-        const statusPart = row.status.toUpperCase().padEnd(STATUS_WIDTH, ' ');
-        const latencyPart = typeof row.latencyMs === 'number' ? ` (${row.latencyMs}ms)` : '';
-        lines.push(`${namePart} ${statusPart} ${row.detail}${latencyPart}`);
-        if (row.remediation && (row.status === 'warn' || row.status === 'error')) {
-            lines.push(`${' '.repeat(NAME_WIDTH + STATUS_WIDTH + 4)}→ ${row.remediation}`);
-        }
-    }
-    lines.push('');
-    const { ok, warn, error: errorCount, skipped } = envelope.counts;
-    const summary = envelope.overall === 'healthy'
-        ? 'HEALTHY'
-        : envelope.overall === 'warning'
-            ? 'WARNINGS'
-            : 'ERRORS';
-    lines.push(`${errorCount} error(s), ${warn} warning(s), ${ok} ok, ${skipped} skipped. Overall: ${summary}`);
-    lines.push(`CLI ${envelope.meta.cliVersion} Node ${envelope.meta.nodeVersion} cwd ${envelope.meta.cwd}`);
-    return lines.join('\n');
-}
-/**
- * Wrap the MCP probe in a dynamic import + try/catch so a missing
- * sibling L13 surface (or a schema mismatch in `core/mcp/registry`)
- * degrades the row к `skipped` instead of breaking the entire sweep.
- * The probe-runner already isolates throws into `error` rows; this
- * wrapper additionally distinguishes "feature not available" from
- * "feature crashed".
- */
-async function probeMcpSafely(ctx) {
-    try {
-        const mod = await import('../../core/mcp/registry.js');
-        if (typeof mod.loadMcpRegistry !== 'function') {
-            return {
-                name: 'MCP SERVERS',
-                status: 'skipped',
-                detail: 'MCP integration not exported by this build',
-            };
-        }
-        return await probeMcp(ctx, {
-            loadRegistry: (cwd, options) => mod.loadMcpRegistry(cwd, { connect: options.connect ?? false }),
-        });
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return {
-            name: 'MCP SERVERS',
-            status: 'skipped',
-            detail: 'MCP integration not available',
-            remediation: `Inspection failed: ${message}`,
-        };
-    }
-}
-/**
- * Best-effort free-bytes lookup via `df -k <home>`. Parses the second
- * line (header + one data row) and returns the `Available` column ×
- * 1024. Throws on parse failure so the probe surfaces a `warn`
- * instead of a misleading 0-bytes-free verdict.
- *
- * Exported for the spec so we can drive it through a stubbed
- * execFileSync without spawning a real subprocess.
- */
-export function getFreeBytesViaDf(home) {
-    const out = execFileSync('df', ['-k', home], {
-        encoding: 'utf8',
-        timeout: 2_000,
-        stdio: ['ignore', 'pipe', 'ignore'],
-    });
-    return parseDfOutput(out);
-}
-/**
- * Parse the textual output of `df -k`. Handles both BSD and GNU
- * variants — both emit a `Available` column at index 3 of the data
- * row, with one quirk: long device names wrap к the next line on
- * GNU, so we collapse whitespace + tab newlines first.
- */
-export function parseDfOutput(out) {
-    // Collapse multi-line device-name wraps into a single logical row.
-    const collapsed = out.replace(/\n\s+/g, ' ');
-    const lines = collapsed
-        .split('\n')
-        .map((line) => line.trim())
-        .filter((line) => line.length > 0);
-    if (lines.length < 2) {
-        throw new Error(`df output too short: ${JSON.stringify(out.slice(0, 64))}`);
-    }
-    const data = lines[1].split(/\s+/);
-    // Schema: Filesystem 1K-blocks Used Available Capacity Mounted-on
-    const availableField = data[3];
-    if (!availableField) {
-        throw new Error(`df output missing Available column: ${JSON.stringify(lines[1])}`);
-    }
-    const value = Number(availableField);
-    if (!Number.isFinite(value) || value < 0) {
-        throw new Error(`df Available column not numeric: ${availableField}`);
-    }
-    return value * 1024;
-}
-/**
- * Default home dir resolver. Centralised so the CLI handler can call
- * `runDoctorCommand` without re-importing `os.homedir` everywhere.
- */
-export function defaultHome() {
-    return homedir();
-}
-/**
- * Defensive `existsSync` wrapper — sandboxed environments occasionally
- * lack the permission bits required for stat; we trap to keep the
- * envelope single-shot reliable.
- */
-function safeExistsSync(path) {
-    try {
-        return existsSync(path);
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Resolve the workspace permission mode for the envelope. Precedence:
- *
- *  1. `.pugi/settings.json::permissions.mode` (workspace config —
- *     authored by the operator at init time).
- *  2. `.pugi/session.json::permissionMode` ( live-session
- *     override set by `/permissions <mode>`).
- *  3. `~/.pugi/config.json::defaultPermissionMode` (global default).
- *  4. Hard fallback `default`.
- *
- * Reads are wrapped в try/catch — a malformed settings file never
- * crashes the doctor envelope, the worst case is the field surfaces
- * the next layer in the precedence chain.
- */
-export function resolveWorkspacePermissionMode(cwd, home) {
-    try {
-        const settings = loadSettings(cwd);
-        // `permissions.mode` is zod-validated and always present (default
-        // `auto`). When the operator wrote `.pugi/settings.json` with an
-        // explicit mode it wins; when no file exists the zod default kicks
-        // in. We honour the explicit-file value first so the operator's
-        // declared intent is preserved verbatim.
-        if (settings.permissions.mode) {
-            return settings.permissions.mode;
-        }
-    }
-    catch {
-        // Malformed JSON / unreadable file — fall through to the session
-        // resolver which has its own defensive parse layer.
-    }
-    try {
-        return resolveMode({ workspaceRoot: cwd, homeDir: home });
-    }
-    catch {
-        return 'default';
-    }
-}
-/**
- * Snapshot the dispatch-engine tool registry for the envelope. Today
- * every registered tool is `enabled: true` — the registry is the
- * source of truth for what dispatch can call. Future work that gates
- * tools per-tier / per-workspace flips `enabled` based on the
- * effective allow / deny list without breaking the envelope shape.
- */
-export function snapshotToolRegistry() {
-    return toolRegistry.map((tool) => ({
-        name: tool.name,
-        kind: tool.permission,
-        enabled: true,
-    }));
-}
-/**
- * Evaluate the protected-files policy against a target basename. The
- * check is purely lexical — we do NOT read the file. Mirrors the
- * `isProtectedPath` rule baked into `runtime/cli.ts` (the diff
- * untracked-files filter) so a single source of truth governs both
- * surfaces. Centralising this в a probe-able function lets the
- * doctor envelope surface "yes, the .env gate would fire" without
- * the operator having к dispatch a real edit.
- */
-export function evaluateProtectedFile(path) {
-    if (!path || path.length === 0) {
-        return { matches: false };
-    }
-    const base = path.split('/').pop() ?? path;
-    if (base === '.env' || base.startsWith('.env.')) {
-        return {
-            matches: true,
-            path,
-            reason: 'protected basename: .env (or .env.* variant)',
-        };
-    }
-    const exactNames = new Set([
-        '.npmrc',
-        '.yarnrc',
-        '.pypirc',
-        '.gitconfig',
-        '.netrc',
-        'id_rsa',
-        'id_ed25519',
-        'id_ecdsa',
-        'id_dsa',
-        'credentials',
-        'credentials.json',
-    ]);
-    if (exactNames.has(base)) {
-        return {
-            matches: true,
-            path,
-            reason: `protected basename: ${base}`,
-        };
-    }
-    if (/\.(pem|key|crt|cer|der|pfx|p12|dump|sql|secret)$/i.test(base)) {
-        return {
-            matches: true,
-            path,
-            reason: `protected extension on ${base}`,
-        };
-    }
-    return {
-        matches: false,
-        path,
-        reason: 'not on the protected-files denylist',
-    };
-}
-//# sourceMappingURL=doctor.js.map