@pugi/cli 0.1.0-beta.17 → 0.1.0-beta.19

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

@@ -0,0 +1,57 @@
+/**
+ * α7 L11 (2026-05-27) — 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/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/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

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

@@ -0,0 +1,74 @@
+/**
+ * SESSION probe — reports the active session id + age when the doctor
+ * runs from inside the REPL OR finds a recent NDJSON session log in
+ * the workspace.
+ *
+ * The CLI command path has no live session context (each `pugi <cmd>`
+ * invocation is a fresh process), so we read `.pugi/events.jsonl` if
+ * present and report the most-recent event's age + total line count.
+ * Inside the REPL we pass an explicit `sessionId` so the probe
+ * surfaces the live state without re-reading disk.
+ *
+ * Absence of `.pugi/events.jsonl` is `skipped`, not an error — the
+ * operator may simply be running `pugi doctor` in a workspace that
+ * has not yet seen a dispatch.
+ */
+export function probeSession(ctx, fs, deps) {
+    if (deps.liveSessionId) {
+        return {
+            name: 'SESSION',
+            status: 'ok',
+            detail: `session=${deps.liveSessionId} (live, REPL active)`,
+        };
+    }
+    const eventsPath = `${ctx.cwd}/.pugi/events.jsonl`;
+    if (!fs.existsSync(eventsPath)) {
+        return {
+            name: 'SESSION',
+            status: 'skipped',
+            detail: 'No prior dispatch logged in this workspace',
+        };
+    }
+    let stats;
+    try {
+        stats = fs.statSync(eventsPath);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            name: 'SESSION',
+            status: 'warn',
+            detail: `.pugi/events.jsonl present but unreadable`,
+            remediation: `Inspect: ${message}`,
+        };
+    }
+    const ageMs = Math.max(0, deps.now() - stats.mtimeMs);
+    const ageLabel = formatAge(ageMs);
+    // Counting lines is cheap on a small NDJSON file; a "huge" Pugi
+    // session is single-digit MB. We avoid loading binary blobs by
+    // simply walking the buffer count.
+    let lineCount = 0;
+    try {
+        const raw = fs.readFileSync(eventsPath, 'utf8');
+        lineCount = raw.split('\n').filter((line) => line.trim().length > 0).length;
+    }
+    catch {
+        lineCount = -1;
+    }
+    const linePart = lineCount >= 0 ? `, ${lineCount} event(s)` : '';
+    return {
+        name: 'SESSION',
+        status: 'ok',
+        detail: `last event ${ageLabel} ago${linePart}`,
+    };
+}
+export function formatAge(ms) {
+    if (ms < 60_000)
+        return `${Math.round(ms / 1000)}s`;
+    if (ms < 3_600_000)
+        return `${Math.round(ms / 60_000)}m`;
+    if (ms < 86_400_000)
+        return `${Math.round(ms / 3_600_000)}h`;
+    return `${Math.round(ms / 86_400_000)}d`;
+}
+//# sourceMappingURL=session.js.map