@pugi/cli 0.1.0-beta.8 → 0.1.0-beta.87

package/dist/core/diagnostics/probes/config.js

@@ -0,0 +1,72 @@
+/**
+ * CONFIG probe — verifies `~/.pugi/credentials.json` exists, parses,
+ * and carries the canonical shape (a `tokens` array). Lighter-weight
+ * than the auth probe (no network); catches `corrupted JSON` /
+ * `accidentally overwrote with empty file` / `bad permissions` cases
+ * that would otherwise surface as confusing errors deeper in the
+ * auth path.
+ *
+ * Absence of the file is NOT an error here — the operator may not
+ * have run `pugi login` yet. That case is caught by the AUTH probe
+ * with a clean "run pugi login" remediation. CONFIG's job is to
+ * verify the file is sane WHEN it exists.
+ */
+export function probeConfig(ctx, fs) {
+    const credPath = `${ctx.home}/.pugi/credentials.json`;
+    if (!fs.existsSync(credPath)) {
+        return {
+            name: 'CONFIG',
+            status: 'skipped',
+            detail: '~/.pugi/credentials.json absent (operator has not logged in)',
+        };
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(credPath, 'utf8');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            name: 'CONFIG',
+            status: 'error',
+            detail: `Cannot read ~/.pugi/credentials.json`,
+            remediation: `Fix permissions or delete and re-login: ${message}`,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            name: 'CONFIG',
+            status: 'error',
+            detail: `~/.pugi/credentials.json is not valid JSON`,
+            remediation: `Delete and re-login: ${message}`,
+        };
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        return {
+            name: 'CONFIG',
+            status: 'error',
+            detail: `credentials.json root is not an object`,
+            remediation: 'Delete and re-login',
+        };
+    }
+    const tokens = parsed.tokens;
+    if (!Array.isArray(tokens)) {
+        return {
+            name: 'CONFIG',
+            status: 'error',
+            detail: `credentials.json missing required \`tokens\` array`,
+            remediation: 'Delete and re-login',
+        };
+    }
+    return {
+        name: 'CONFIG',
+        status: 'ok',
+        detail: `~/.pugi/credentials.json valid (${tokens.length} token(s) stored)`,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/core/diagnostics/probes/denial-tracking.js

@@ -0,0 +1,57 @@
+/**
+ * L11 — DENIAL TRACKING probe for `pugi doctor`.
+ *
+ * Reports the current session's denial pressure: total denial count,
+ * unique (tool, args) patterns, and how many patterns have repeated
+ * past the reminder threshold. Operators read this to spot:
+ *
+ *  - A hook script refusing more dispatches than expected (mis-
+ *    configured `.pugi/hooks.json`).
+ *  - Plan-mode runs where the model keeps trying mutating tools
+ *    (a sign the prompt is not anchoring it correctly).
+ *  - Stale-read loops indicating concurrent multi-agent writes.
+ *
+ * Status semantics:
+ *
+ *  - `ok` when the tracker is empty OR carries denials but none have
+ *    repeated past the threshold. Single denials are normal session
+ *    hygiene; repeats are the signal.
+ *  - `warn` when one or more patterns repeated >= the reminder
+ *    threshold. The probe surfaces the count so the operator can act.
+ *  - `skipped` when no tracker is wired (e.g. doctor invoked outside
+ *    a live REPL session, top-level `pugi doctor`).
+ *
+ * Pure: takes a tracker snapshot — no I/O, no module-level state.
+ */
+import { DENIAL_REMINDER_THRESHOLD, } from '../../denial-tracking/state.js';
+export function probeDenialTracking(deps) {
+    if (!deps.tracker) {
+        return {
+            name: 'DENIAL TRACKING',
+            status: 'skipped',
+            detail: 'No live session — run `pugi doctor` from inside the REPL to see denials.',
+        };
+    }
+    const summary = deps.tracker.summary();
+    if (summary.totalDenials === 0) {
+        return {
+            name: 'DENIAL TRACKING',
+            status: 'ok',
+            detail: 'No tool denials this session.',
+        };
+    }
+    if (summary.repeatedPatterns === 0) {
+        return {
+            name: 'DENIAL TRACKING',
+            status: 'ok',
+            detail: `${summary.totalDenials} denial(s), ${summary.uniquePatterns} unique pattern(s), none repeated.`,
+        };
+    }
+    return {
+        name: 'DENIAL TRACKING',
+        status: 'warn',
+        detail: `${summary.totalDenials} denial(s), ${summary.repeatedPatterns} pattern(s) repeated >= ${DENIAL_REMINDER_THRESHOLD}.`,
+        remediation: 'Inspect via `/permissions denials` (when L6 lands) or check `.pugi/events.jsonl` for the latest refusals.',
+    };
+}
+//# sourceMappingURL=denial-tracking.js.map

package/dist/core/diagnostics/probes/disk.js

@@ -0,0 +1,81 @@
+/**
+ * DISK probe — warn the operator when the home partition is dangerously
+ * full. The session log, file cache, MCP working dirs, and the engine
+ * artifact bundle all land under `~/.pugi/`, so a full disk produces
+ * cryptic ENOSPC errors mid-dispatch. We catch that early.
+ *
+ * Implementation strategy: call `df -k` (POSIX-portable BSD tool with a
+ * stable column ordering) on the home dir and parse the available
+ * column. Bytes math + 1k blocks = simple integer arithmetic. We
+ * deliberately avoid `statvfs` because Node's stable surface for it
+ * (`fs.statfs` introduced in Node 18.15) returns BigInts that callers
+ * routinely mishandle on cross-platform builds.
+ *
+ * Thresholds:
+ *  - `< 256 MiB` available → error (Pugi cannot do meaningful work)
+ *  - `< 1 GiB` available → warn (operator should clear space soon)
+ *  - otherwise           → ok
+ */
+const MIB = 1024 * 1024;
+const GIB = MIB * 1024;
+const ERROR_THRESHOLD_BYTES = 256 * MIB;
+const WARN_THRESHOLD_BYTES = 1 * GIB;
+export function probeDisk(ctx, deps) {
+    let freeBytes;
+    try {
+        freeBytes = deps.getFreeBytes(ctx.home);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            name: 'DISK',
+            status: 'warn',
+            detail: `Cannot determine free space on ${ctx.home}`,
+            remediation: `Inspection failed: ${message}`,
+        };
+    }
+    if (!Number.isFinite(freeBytes) || freeBytes < 0) {
+        return {
+            name: 'DISK',
+            status: 'warn',
+            detail: `df returned implausible value (${freeBytes}) for ${ctx.home}`,
+        };
+    }
+    const human = formatBytes(freeBytes);
+    if (freeBytes < ERROR_THRESHOLD_BYTES) {
+        return {
+            name: 'DISK',
+            status: 'error',
+            detail: `${human} free on home partition`,
+            remediation: 'Free disk space — Pugi writes ~/.pugi/sessions and cache files',
+        };
+    }
+    if (freeBytes < WARN_THRESHOLD_BYTES) {
+        return {
+            name: 'DISK',
+            status: 'warn',
+            detail: `${human} free on home partition`,
+            remediation: 'Consider clearing ~/.pugi/sessions older entries',
+        };
+    }
+    return {
+        name: 'DISK',
+        status: 'ok',
+        detail: `${human} free on home partition`,
+    };
+}
+/**
+ * Format bytes as `1.2GB` / `512MB` / `42KB`. Stays in IEC base-1024
+ * because that's what `df -k` returns and what operators reading the
+ * doctor table expect to see on their `df` follow-up.
+ */
+export function formatBytes(bytes) {
+    if (bytes >= GIB)
+        return `${(bytes / GIB).toFixed(1)}GB`;
+    if (bytes >= MIB)
+        return `${Math.round(bytes / MIB)}MB`;
+    if (bytes >= 1024)
+        return `${Math.round(bytes / 1024)}KB`;
+    return `${bytes}B`;
+}
+//# sourceMappingURL=disk.js.map

package/dist/core/diagnostics/probes/engine-live.js

@@ -0,0 +1,46 @@
+const LIVE_PROMPT = 'Reply with the single word OK.';
+const TIMEOUT_MS = 15_000;
+export async function probeEngineLive(ctx, deps) {
+    const apiKey = deps.resolveApiKey(ctx.env);
+    if (!apiKey) {
+        return { name: 'ENGINE LIVE', status: 'skipped', detail: 'no API key (run `pugi login` or set PUGI_API_KEY)' };
+    }
+    const apiUrl = deps.resolveApiUrl(ctx.env);
+    const startedAt = deps.now();
+    const url = (apiUrl.endsWith('/') ? apiUrl.slice(0, -1) : apiUrl) + '/api/pugi/engine';
+    try {
+        const res = await deps.fetchImpl(url, {
+            method: 'POST',
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
+            body: JSON.stringify({
+                personaSlug: 'main',
+                command: 'explain',
+                messages: [{ role: 'user', content: LIVE_PROMPT }],
+                tools: [],
+                temperature: 0,
+                maxTokens: 32,
+            }),
+        });
+        const latencyMs = deps.now() - startedAt;
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            return { name: 'ENGINE LIVE', status: 'error', detail: `engine returned HTTP ${res.status}${body ? `: ${body.slice(0, 200)}` : ''}`, latencyMs };
+        }
+        const json = (await res.json().catch(() => null));
+        if (!json)
+            return { name: 'ENGINE LIVE', status: 'error', detail: 'engine returned 2xx but body is not JSON', latencyMs };
+        const model = typeof json['model'] === 'string' ? json['model'] : 'unknown';
+        const content = typeof json['content'] === 'string' ? json['content'] : '';
+        if (!content.toLowerCase().includes('ok')) {
+            return { name: 'ENGINE LIVE', status: 'warn', detail: `round-trip OK via ${model} (${latencyMs}ms) but reply did not contain expected token; got "${content.slice(0, 80)}"`, latencyMs };
+        }
+        return { name: 'ENGINE LIVE', status: 'ok', detail: `round-trip OK via ${model} (${latencyMs}ms)`, latencyMs };
+    }
+    catch (error) {
+        const latencyMs = deps.now() - startedAt;
+        const message = error instanceof Error ? error.message : String(error);
+        return { name: 'ENGINE LIVE', status: 'error', detail: `engine round-trip failed: ${message}`, latencyMs };
+    }
+}
+//# sourceMappingURL=engine-live.js.map

package/dist/core/diagnostics/probes/git.js

@@ -0,0 +1,65 @@
+/**
+ * GIT probe — verifies git is on PATH AND the current cwd is inside a
+ * git work tree. Reports the short HEAD sha + repo root for context.
+ *
+ * Pugi treats the workspace as a git project (worktree isolation,
+ * /codex review, /triple-review and the entire agent loop assume
+ * `git diff origin/main..HEAD` is meaningful). A workspace that is
+ * not a git work tree still works for read-only commands but the
+ * doctor surface flags this so the operator knows where the limits
+ * are.
+ */
+export function probeGit(ctx, deps) {
+    let version;
+    try {
+        version = deps.resolveVersion();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            name: 'GIT',
+            status: 'warn',
+            detail: 'git not on PATH',
+            remediation: `Install git (error: ${message})`,
+        };
+    }
+    let inWorkTree = false;
+    try {
+        inWorkTree = deps.isInWorkTree(ctx.cwd);
+    }
+    catch {
+        inWorkTree = false;
+    }
+    if (!inWorkTree) {
+        return {
+            name: 'GIT',
+            status: 'warn',
+            detail: `${version} (cwd is not a git work tree)`,
+            remediation: 'Run `git init` to enable diff-based commands',
+        };
+    }
+    const sha = (() => {
+        try {
+            return deps.resolveHeadSha(ctx.cwd);
+        }
+        catch {
+            return null;
+        }
+    })();
+    const root = (() => {
+        try {
+            return deps.resolveRoot(ctx.cwd);
+        }
+        catch {
+            return null;
+        }
+    })();
+    const shaSuffix = sha ? ` @ ${sha.slice(0, 8)}` : '';
+    const rootSuffix = root ? ` (${root})` : '';
+    return {
+        name: 'GIT',
+        status: 'ok',
+        detail: `${version}${shaSuffix}${rootSuffix}`,
+    };
+}
+//# sourceMappingURL=git.js.map

package/dist/core/diagnostics/probes/hooks.js

@@ -0,0 +1,118 @@
+/**
+ * HOOKS probe — verifies `.pugi/hooks-mvp.json` and `.pugi/hook-chains.json`
+ * exist + parse + carry their declared shape. Absence is OK (most workspaces
+ * don't ship hooks); presence с invalid JSON is a deployment-blocking error
+ * the operator wants surfaced before a tool dispatch fires a malformed hook
+ * and the model sees a confusing failure.
+ *
+ * Validation tier:
+ *  1. JSON.parse — catches typos / trailing commas / bad escapes.
+ *  2. Top-level shape sniff — `hooks-mvp.json` MUST be an object с a
+ *     `hooks` array property; `hook-chains.json` MUST be an object
+ *     с string-keyed event names mapping to arrays.
+ *  3. Per-entry require-fields sniff — minimal так что probe stays cheap.
+ *
+ * Out of scope: full Zod schema validation. That lives in the hook loader
+ * itself (apps/pugi-cli/src/core/hooks/v2/loader.ts). The probe is a
+ * fast sanity check; the loader produces the canonical error message
+ * when a hook actually fires.
+ */
+function loadHookFile(fs, path) {
+    if (!fs.existsSync(path))
+        return null;
+    try {
+        const raw = fs.readFileSync(path, 'utf8');
+        return { path, parsed: JSON.parse(raw) };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { parseError: `${path}: ${message}` };
+    }
+}
+function validateMvpShape(parsed) {
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return 'top-level value must be an object';
+    }
+    const hooks = parsed['hooks'];
+    if (hooks !== undefined && !Array.isArray(hooks)) {
+        return '`hooks` property must be an array when present';
+    }
+    return null;
+}
+function validateChainsShape(parsed) {
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return 'top-level value must be an object';
+    }
+    for (const [event, body] of Object.entries(parsed)) {
+        if (!Array.isArray(body)) {
+            return `event "${event}": value must be an array of hook entries`;
+        }
+    }
+    return null;
+}
+export function probeHooks(ctx, fs) {
+    const mvpPath = `${ctx.cwd}/.pugi/hooks-mvp.json`;
+    const chainsPath = `${ctx.cwd}/.pugi/hook-chains.json`;
+    const mvp = loadHookFile(fs, mvpPath);
+    const chains = loadHookFile(fs, chainsPath);
+    const issues = [];
+    let mvpCount = 0;
+    let chainEvents = 0;
+    if (mvp !== null) {
+        if ('parseError' in mvp) {
+            issues.push(`hooks-mvp.json parse failed: ${mvp.parseError}`);
+        }
+        else {
+            const shapeIssue = validateMvpShape(mvp.parsed);
+            if (shapeIssue) {
+                issues.push(`hooks-mvp.json: ${shapeIssue}`);
+            }
+            else {
+                const hooksArr = mvp.parsed['hooks'];
+                mvpCount = Array.isArray(hooksArr) ? hooksArr.length : 0;
+            }
+        }
+    }
+    if (chains !== null) {
+        if ('parseError' in chains) {
+            issues.push(`hook-chains.json parse failed: ${chains.parseError}`);
+        }
+        else {
+            const shapeIssue = validateChainsShape(chains.parsed);
+            if (shapeIssue) {
+                issues.push(`hook-chains.json: ${shapeIssue}`);
+            }
+            else {
+                chainEvents = Object.keys(chains.parsed).length;
+            }
+        }
+    }
+    if (issues.length > 0) {
+        return {
+            name: 'HOOKS',
+            status: 'error',
+            detail: issues.join('; '),
+            remediation: 'Fix the JSON syntax / shape, or delete the file if hooks are not in use. The hook loader surfaces the canonical error when a hook actually fires; this probe catches the problem before the first dispatch.',
+        };
+    }
+    if (mvp === null && chains === null) {
+        return {
+            name: 'HOOKS',
+            status: 'skipped',
+            detail: 'no hook config files in .pugi/ (workspace has not opted into hooks)',
+        };
+    }
+    const parts = [];
+    if (mvp !== null && !('parseError' in mvp)) {
+        parts.push(`hooks-mvp.json OK (${mvpCount} entr${mvpCount === 1 ? 'y' : 'ies'})`);
+    }
+    if (chains !== null && !('parseError' in chains)) {
+        parts.push(`hook-chains.json OK (${chainEvents} event${chainEvents === 1 ? '' : 's'})`);
+    }
+    return {
+        name: 'HOOKS',
+        status: 'ok',
+        detail: parts.join('; '),
+    };
+}
+//# sourceMappingURL=hooks.js.map

package/dist/core/diagnostics/probes/mcp.js

@@ -0,0 +1,75 @@
+/**
+ * MCP probe — reports the configured Model Context Protocol servers
+ * along with their trust + connection state.
+ *
+ * Sibling L13 (MCP server config) ships its own command surface; this
+ * probe consumes the existing `loadMcpRegistry` helper в a graceful
+ * try/catch so an unconfigured workspace (no `.pugi/mcp.json` OR an
+ * empty `servers: {}` map) lands as `ok` with detail "no servers
+ * configured" rather than a noisy failure row.
+ *
+ * Failure modes:
+ *  - registry helper throws → `warn` with the error message;
+ *    the table renderer surfaces the remediation hint;
+ *  - one or more servers report `lastError` → `warn` summarising the
+ *    count;
+ *  - all configured servers connected cleanly → `ok` listing them.
+ */
+export async function probeMcp(ctx, deps) {
+    let registry;
+    try {
+        // `connect: false` keeps the probe cheap — we only need the
+        // declared config + trust ledger entries, not live subprocess
+        // handshakes. The doctor sweep budget shouldn't be eaten by
+        // server-spawn latency.
+        registry = await deps.loadRegistry(ctx.cwd, { connect: false });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            name: 'MCP SERVERS',
+            status: 'warn',
+            detail: 'MCP registry not loadable (config or schema error)',
+            remediation: `Inspect .pugi/mcp.json: ${message}`,
+        };
+    }
+    const servers = Array.from(registry.servers.values());
+    // Best-effort shutdown — even with `connect: false` we still own the
+    // registry handle. Swallow errors so a clean-up failure never
+    // poisons the probe verdict.
+    await registry.shutdown().catch(() => { });
+    if (servers.length === 0) {
+        return {
+            name: 'MCP SERVERS',
+            status: 'ok',
+            detail: 'No MCP servers configured',
+        };
+    }
+    const labels = servers.map((server) => `${server.name}:${server.trust}`);
+    const trusted = servers.filter((server) => server.trust === 'trusted');
+    const pending = servers.filter((server) => server.trust === 'pending');
+    const denied = servers.filter((server) => server.trust === 'denied');
+    const failing = servers.filter((server) => typeof server.lastError === 'string' && server.lastError.length > 0);
+    if (failing.length > 0) {
+        return {
+            name: 'MCP SERVERS',
+            status: 'warn',
+            detail: `${failing.length}/${servers.length} server(s) reporting errors: ${labels.join(', ')}`,
+            remediation: `Inspect: \`pugi mcp list\``,
+        };
+    }
+    if (pending.length > 0) {
+        return {
+            name: 'MCP SERVERS',
+            status: 'warn',
+            detail: `${pending.length} pending trust decision(s): ${labels.join(', ')}`,
+            remediation: 'Run `pugi mcp trust <name>` or `pugi mcp deny <name>`',
+        };
+    }
+    return {
+        name: 'MCP SERVERS',
+        status: 'ok',
+        detail: `${trusted.length} trusted, ${denied.length} denied (${labels.join(', ')})`,
+    };
+}
+//# sourceMappingURL=mcp.js.map

package/dist/core/diagnostics/probes/node.js

@@ -0,0 +1,59 @@
+/**
+ * NODE probe — verifies the running Node major version meets the
+ * `engines.node` floor declared in @pugi/cli's package.json.
+ *
+ * We bake the floor in as a constant rather than reading package.json
+ * at runtime because the published .tgz strips the file from a location
+ * the compiled bundle can reach (`--resolveJsonModule` is off for the
+ * CLI build). The lockstep is enforced by
+ * `scripts/check-version-lockstep.sh` in the publish pipeline.
+ */
+/**
+ * Minimum supported Node major. Mirrors `engines.node` in
+ * apps/pugi-cli/package.json (`">=22.5.0"`).
+ */
+export const MIN_NODE_MAJOR = 22;
+export const MIN_NODE_MINOR = 5;
+/**
+ * Parse a Node version string of the form `v<major>.<minor>.<patch>`.
+ * Returns null when the input doesn't match — the caller treats null
+ * as an error condition.
+ */
+export function parseNodeVersion(version) {
+    const match = /^v(\d+)\.(\d+)\./.exec(version);
+    if (!match)
+        return null;
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    if (!Number.isFinite(major) || !Number.isFinite(minor))
+        return null;
+    return { major, minor };
+}
+export function probeNode(input) {
+    const parsed = parseNodeVersion(input.version);
+    if (!parsed) {
+        return {
+            name: 'NODE',
+            status: 'error',
+            detail: `Unparseable Node version "${input.version}"`,
+            remediation: `Install Node >= ${MIN_NODE_MAJOR}.${MIN_NODE_MINOR}.0 (current binary returns a non-semver version string)`,
+        };
+    }
+    const { major, minor } = parsed;
+    const passes = major > MIN_NODE_MAJOR ||
+        (major === MIN_NODE_MAJOR && minor >= MIN_NODE_MINOR);
+    if (passes) {
+        return {
+            name: 'NODE',
+            status: 'ok',
+            detail: `${input.version} (>= ${MIN_NODE_MAJOR}.${MIN_NODE_MINOR}.0 required)`,
+        };
+    }
+    return {
+        name: 'NODE',
+        status: 'error',
+        detail: `${input.version} below floor >= ${MIN_NODE_MAJOR}.${MIN_NODE_MINOR}.0`,
+        remediation: `Upgrade Node: \`nvm install ${MIN_NODE_MAJOR}\` or download from nodejs.org`,
+    };
+}
+//# sourceMappingURL=node.js.map

package/dist/core/diagnostics/probes/pnpm.js

@@ -0,0 +1,36 @@
+/**
+ * PNPM probe — verifies pnpm is on PATH and reports its version. The
+ * customer-facing CLI doesn't strictly require pnpm at runtime
+ * (`@pugi/cli` is published as a regular npm package), but a missing
+ * pnpm means `pugi code` cannot run `pnpm test` / `pnpm typecheck`
+ * gates the agent loop emits. Surfacing this early prevents the
+ * agent from issuing a meaningless `command not found: pnpm` error
+ * three turns into a session.
+ */
+export function probePnpm(deps) {
+    try {
+        const version = deps.resolveVersion();
+        if (!version) {
+            return {
+                name: 'PNPM',
+                status: 'warn',
+                detail: 'pnpm reported empty version string',
+            };
+        }
+        return {
+            name: 'PNPM',
+            status: 'ok',
+            detail: `pnpm ${version}`,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            name: 'PNPM',
+            status: 'warn',
+            detail: 'pnpm not on PATH — agent quality gates will be skipped',
+            remediation: `Install pnpm: \`npm i -g pnpm\` (error: ${message})`,
+        };
+    }
+}
+//# sourceMappingURL=pnpm.js.map