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

package/dist/core/diagnostics/probe-runner.js

@@ -0,0 +1,93 @@
+/**
+ * Probe runner — orchestrates a set of diagnostic probes in parallel
+ * with per-probe fail-isolation + a global wall-clock budget.
+ *
+ * Design contract:
+ *
+ *   - Probes are independent: one probe's throw or timeout NEVER stops
+ *     the others. The runner wraps each call in a try/catch + a
+ *     `Promise.race` against a timeout sentinel.
+ *
+ *   - Order preservation: the returned `probes[]` array preserves the
+ *     input order so the table renderer always lists rows in the same
+ *     sequence (operators rely on muscle memory: "auth is the first
+ *     row, api is the second").
+ *
+ *   - No I/O ownership: the runner owns ZERO file or network calls.
+ *     Every external dependency is injected via the probe function
+ *     itself. This keeps the test surface minimal and verifies the
+ *     fail-isolation contract without spinning real subprocesses.
+ *
+ *   - Crashes attributed to the probe: a probe that throws maps to a
+ *     synthetic `error` ProbeResult with the probe name + the error
+ *     message. A probe that exceeds the timeout becomes a synthetic
+ *     `warn` (timing out is asymmetric — the host is reachable but
+ *     slow).
+ *
+ *   - The aggregate `DoctorReport` shape comes straight from
+ *     `types.ts` so the doctor command + the Ink table renderer both
+ *     consume the same struct without any glue layer.
+ */
+import { computeOverall, countProbes, } from './types.js';
+/**
+ * Run a set of probes in parallel and produce a structured report.
+ * Never throws — every failure mode maps to a structured ProbeResult.
+ */
+export async function runProbes(probes, options = {}) {
+    const now = options.now ?? Date.now;
+    const defaultTimeoutMs = options.defaultTimeoutMs ?? 5_000;
+    const startedAt = now();
+    // Each probe is wrapped in a fail-isolation envelope.
+    const results = await Promise.all(probes.map(async (entry) => runOne(entry, defaultTimeoutMs)));
+    const overall = computeOverall(results);
+    const counts = countProbes(results);
+    const durationMs = now() - startedAt;
+    return {
+        probes: results,
+        overall,
+        counts,
+        durationMs,
+    };
+}
+async function runOne(entry, defaultTimeoutMs) {
+    const budget = entry.timeoutMs ?? defaultTimeoutMs;
+    try {
+        return await raceWithTimeout(entry, budget);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (error instanceof ProbeTimeoutError) {
+            return {
+                name: entry.name,
+                status: 'warn',
+                detail: `Probe timed out after ${budget}ms`,
+                remediation: 'Re-run later; the host or registry may be slow',
+            };
+        }
+        return {
+            name: entry.name,
+            status: 'error',
+            detail: `Probe crashed: ${message}`,
+        };
+    }
+}
+class ProbeTimeoutError extends Error {
+    constructor(name, budgetMs) {
+        super(`Probe ${name} exceeded ${budgetMs}ms`);
+        this.name = 'ProbeTimeoutError';
+    }
+}
+async function raceWithTimeout(entry, budgetMs) {
+    let timer;
+    const timeoutPromise = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new ProbeTimeoutError(entry.name, budgetMs)), budgetMs);
+    });
+    try {
+        return await Promise.race([entry.run(), timeoutPromise]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=probe-runner.js.map

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

@@ -0,0 +1,46 @@
+/**
+ * API probe — verifies `api.pugi.io` (or the active apiUrl) is
+ * reachable WITHOUT requiring a valid auth token. The auth probe
+ * covers the credentialed path; this probe answers the orthogonal
+ * "is the network broken" question so the operator can disambiguate
+ * "I'm offline" from "my token is bad" without reading two probe
+ * details together.
+ *
+ * Success criteria: any HTTP response (including 401 unauthenticated)
+ * proves the host is reachable. A thrown fetch (DNS / TCP / TLS
+ * failure) is the only true failure mode.
+ */
+export async function probeApi(ctx, deps) {
+    const apiUrl = deps.resolveApiUrl(ctx.env);
+    const startedAt = deps.now();
+    try {
+        const response = await deps.fetchImpl(`${stripTrailingSlash(apiUrl)}/api/pugi/health`, {
+            method: 'GET',
+        });
+        const latencyMs = deps.now() - startedAt;
+        // Any HTTP response confirms the host is reachable. The auth probe
+        // is responsible for verdicting the 401 / 200 split — here we just
+        // confirm we can talk to the server.
+        return {
+            name: 'API',
+            status: 'ok',
+            detail: `${apiUrl} reachable (${response.status})`,
+            latencyMs,
+        };
+    }
+    catch (error) {
+        const latencyMs = deps.now() - startedAt;
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            name: 'API',
+            status: 'error',
+            detail: `Cannot reach ${apiUrl}`,
+            latencyMs,
+            remediation: `Check network or override with PUGI_API_URL: ${message}`,
+        };
+    }
+}
+function stripTrailingSlash(url) {
+    return url.endsWith('/') ? url.slice(0, -1) : url;
+}
+//# sourceMappingURL=api.js.map

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

@@ -0,0 +1,86 @@
+/**
+ * AUTH probe — verifies the active credential resolves to a working
+ * Bearer token by calling `GET /api/pugi/health` with it.
+ *
+ * Failure modes (deterministic mapping):
+ *   - no credential found in env or `~/.pugi/credentials.json`
+ *       → status `error`, remediation = `pugi login`
+ *   - credential exists but server returns 401/403
+ *       → status `error`, remediation = `pugi login` (token expired/revoked)
+ *   - credential exists but server returns 5xx OR network fails
+ *       → status `warn` (server-side; don't blame the operator)
+ *   - credential exists and server returns 200
+ *       → status `ok` (latency captured)
+ *
+ * NOTE: the probe must NEVER log the token itself. Memory hit
+ * `feedback_no_claude_attribution_anywhere_hard_rule` plus the CSO
+ * sweep on bearer leaks (history: PR-AGENT-MERGE-GATE 2026-05-15)
+ * frame why this is enforced at the probe layer.
+ */
+export async function probeAuth(ctx, deps) {
+    const credential = deps.resolveCredential(ctx.env, ctx.home);
+    if (!credential) {
+        return {
+            name: 'AUTH',
+            status: 'error',
+            detail: 'No credential — no PUGI_API_KEY env and no ~/.pugi/credentials.json',
+            remediation: 'Run `pugi login` to authenticate',
+        };
+    }
+    const startedAt = deps.now();
+    let response;
+    try {
+        response = await deps.fetchImpl(`${stripTrailingSlash(credential.apiUrl)}/api/pugi/health`, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${credential.apiKey}`,
+            },
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            name: 'AUTH',
+            status: 'warn',
+            detail: `Auth check skipped — network error contacting ${credential.apiUrl}`,
+            remediation: `Verify network: ${message}`,
+        };
+    }
+    const latencyMs = deps.now() - startedAt;
+    if (response.status === 401 || response.status === 403) {
+        return {
+            name: 'AUTH',
+            status: 'error',
+            detail: `Token rejected (${response.status}) by ${credential.apiUrl}`,
+            latencyMs,
+            remediation: 'Token expired or revoked — run `pugi login`',
+        };
+    }
+    if (response.status >= 500) {
+        return {
+            name: 'AUTH',
+            status: 'warn',
+            detail: `Server error ${response.status} from ${credential.apiUrl}`,
+            latencyMs,
+            remediation: 'Try again in a moment; if it persists, check api.pugi.io status',
+        };
+    }
+    if (response.status !== 200) {
+        return {
+            name: 'AUTH',
+            status: 'warn',
+            detail: `Unexpected status ${response.status} from /api/pugi/health`,
+            latencyMs,
+        };
+    }
+    return {
+        name: 'AUTH',
+        status: 'ok',
+        detail: `Authenticated against ${credential.apiUrl}`,
+        latencyMs,
+    };
+}
+function stripTrailingSlash(url) {
+    return url.endsWith('/') ? url.slice(0, -1) : url;
+}
+//# sourceMappingURL=auth.js.map

package/dist/core/diagnostics/probes/cli-version.js

@@ -0,0 +1,127 @@
+/**
+ * CLI VERSION probe — compares the running @pugi/cli version against
+ * the npm registry's `latest` tag. Surfaces an upgrade banner when
+ * the operator is behind.
+ *
+ * Semver comparison is intentionally minimal — we only need to answer
+ * "is local strictly older than latest" for the WARN gate. Edge cases
+ * (pre-release ordering, build metadata) collapse к string equality
+ * because the publish pipeline only tags clean `X.Y.Z[-channel.N]`.
+ *
+ * Network failure is NOT an error — the operator is offline, that's
+ * a transient condition surfaced by the API probe; this probe reports
+ * `warn` so the doctor table still ships a usable verdict.
+ */
+const REGISTRY_URL = 'https://registry.npmjs.org/@pugi/cli/latest';
+/**
+ * Strict-newer comparison. Returns true when `b` is strictly newer
+ * than `a`. Treats unparseable inputs as equal (no false-positive
+ * upgrade banner on a hand-edited local version).
+ */
+export function isNewerVersion(a, b) {
+    const left = parseSemver(a);
+    const right = parseSemver(b);
+    if (!left || !right)
+        return false;
+    if (right.major !== left.major)
+        return right.major > left.major;
+    if (right.minor !== left.minor)
+        return right.minor > left.minor;
+    if (right.patch !== left.patch)
+        return right.patch > left.patch;
+    // Same X.Y.Z — pre-release ordering: a stable release is newer
+    // than any pre-release of the same X.Y.Z; otherwise compare
+    // pre-release tokens lexicographically as a coarse heuristic
+    // sufficient for the upgrade banner.
+    if (!right.pre && left.pre)
+        return true;
+    if (right.pre && !left.pre)
+        return false;
+    if (right.pre && left.pre)
+        return right.pre > left.pre;
+    return false;
+}
+function parseSemver(version) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(version);
+    if (!match)
+        return null;
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    const patch = Number(match[3]);
+    if (!Number.isFinite(major) || !Number.isFinite(minor) || !Number.isFinite(patch)) {
+        return null;
+    }
+    return { major, minor, patch, pre: match[4] ?? '' };
+}
+export async function probeCliVersion(deps) {
+    const url = deps.registryUrl ?? REGISTRY_URL;
+    const timeoutMs = deps.timeoutMs ?? 3_000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const startedAt = deps.now();
+    let response;
+    try {
+        response = await deps.fetchImpl(url, {
+            method: 'GET',
+            headers: { Accept: 'application/json' },
+            signal: controller.signal,
+        });
+    }
+    catch (error) {
+        clearTimeout(timer);
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            name: 'CLI VERSION',
+            status: 'warn',
+            detail: `local=${deps.localVersion} — registry unreachable`,
+            remediation: `Skip-able. Network error: ${message}`,
+        };
+    }
+    clearTimeout(timer);
+    const latencyMs = deps.now() - startedAt;
+    if (!response.ok) {
+        return {
+            name: 'CLI VERSION',
+            status: 'warn',
+            detail: `local=${deps.localVersion} — registry returned ${response.status}`,
+            latencyMs,
+        };
+    }
+    let body;
+    try {
+        body = (await response.json());
+    }
+    catch {
+        return {
+            name: 'CLI VERSION',
+            status: 'warn',
+            detail: `local=${deps.localVersion} — registry JSON unparseable`,
+            latencyMs,
+        };
+    }
+    const remote = body.version;
+    if (typeof remote !== 'string' || remote.length === 0) {
+        return {
+            name: 'CLI VERSION',
+            status: 'warn',
+            detail: `local=${deps.localVersion} — registry response missing version`,
+            latencyMs,
+        };
+    }
+    if (isNewerVersion(deps.localVersion, remote)) {
+        return {
+            name: 'CLI VERSION',
+            status: 'warn',
+            detail: `local=${deps.localVersion}, latest=${remote}`,
+            latencyMs,
+            remediation: 'Run `npm i -g @pugi/cli@latest` to upgrade',
+        };
+    }
+    return {
+        name: 'CLI VERSION',
+        status: 'ok',
+        detail: `${deps.localVersion} (latest)`,
+        latencyMs,
+    };
+}
+//# sourceMappingURL=cli-version.js.map

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/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