@pugi/cli 0.1.0-beta.10 → 0.1.0-beta.100

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

package/dist/core/diagnostics/probes/pugi-md.js

@@ -0,0 +1,89 @@
+/**
+ * PUGI.md hierarchy probe — .
+ *
+ * Surfaces how many ambient `PUGI.md` / `CLAUDE.md` files were
+ * discovered by the cwd → homedir walk-up. Operators triaging "why
+ * is the model not following my project conventions" can run
+ * `pugi doctor` and immediately see whether the hierarchy walk
+ * loaded the file they expected.
+ *
+ * Status semantics:
+ *  - `skipped` when bare mode is active (the walk is deliberately
+ *    disabled). The row still renders so the JSON schema stays
+ *    stable for downstream consumers.
+ *  - `skipped` when zero files were found. This is the default
+ *    state on a clean machine and is NOT an error — most operators
+ *    do not maintain a `~/PUGI.md`.
+ *  - `ok` when one or more files were discovered. The detail names
+ *    the closest file and the total count.
+ *
+ * Side effects:
+ *  - One filesystem walk from cwd to homedir (bounded by the walker's
+ *    depth cap). Each level performs at most 2 `existsSync` calls.
+ *    Cost is single-digit ms even on cold cache; well inside the
+ *    doctor probe wall-clock budget.
+ *
+ * Wired into `buildDefaultProbes` in `runtime/commands/doctor.ts`.
+ */
+import { isBareMode } from '../../bare-mode/index.js';
+import { walkUpPugiMd } from '../../pugi-md/walk-up.js';
+export const PUGI_MD_DOCTOR_LABEL = 'PUGI.md HIERARCHY';
+/** Detail string emitted when bare mode disables the walk. */
+export const PUGI_MD_BARE_SKIP_DETAIL = 'skipped (--bare)';
+/** Detail string emitted when the walk ran but found nothing. */
+export const PUGI_MD_EMPTY_DETAIL = 'no PUGI.md / CLAUDE.md found in cwd → homedir';
+export function probePugiMdHierarchy(input = {}) {
+    const env = input.env ?? process.env;
+    if (isBareMode(env)) {
+        return {
+            name: PUGI_MD_DOCTOR_LABEL,
+            status: 'skipped',
+            detail: PUGI_MD_BARE_SKIP_DETAIL,
+        };
+    }
+    const cwd = input.cwd ?? process.cwd();
+    const walk = input.walkImpl ?? ((c, o) => walkUpPugiMd(c, o));
+    let files;
+    try {
+        files = walk(cwd, input.homedir !== undefined ? { homedir: input.homedir } : {});
+    }
+    catch {
+        // Defensive: walker is wrapped in per-file try/catch already, so
+        // a throw here means a programmer error (bad input). Degrade to
+        // a `warn` row rather than crashing the doctor sweep.
+        return {
+            name: PUGI_MD_DOCTOR_LABEL,
+            status: 'warn',
+            detail: 'walk-up failed (see logs)',
+        };
+    }
+    if (files.length === 0) {
+        return {
+            name: PUGI_MD_DOCTOR_LABEL,
+            status: 'skipped',
+            detail: PUGI_MD_EMPTY_DETAIL,
+        };
+    }
+    // `files` is shallow-to-deep; the first entry is the closest to cwd.
+    // Operators reading the table care most about that one — it is the
+    // file that will most directly influence model behaviour. The
+    // additional count gives a quick "is the homedir / parent picked up
+    // too?" signal without listing every path.
+    const closest = files[0];
+    // closest is guaranteed non-undefined: files.length > 0 enforced
+    // by the early return above.
+    if (!closest) {
+        return {
+            name: PUGI_MD_DOCTOR_LABEL,
+            status: 'skipped',
+            detail: PUGI_MD_EMPTY_DETAIL,
+        };
+    }
+    const suffix = files.length === 1 ? '' : ` (+${files.length - 1} more)`;
+    return {
+        name: PUGI_MD_DOCTOR_LABEL,
+        status: 'ok',
+        detail: `${files.length} file${files.length === 1 ? '' : 's'}: ${closest.path}${suffix}`,
+    };
+}
+//# sourceMappingURL=pugi-md.js.map

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

@@ -0,0 +1,72 @@
+/**
+ * SANDBOX probe — surfaces the current OS-level sandbox posture (
+ * Trust Sprint item 6: macOS Seatbelt adapter wired; Linux Landlock
+ * and Docker variants still backlog).
+ *
+ * Sources `bash.sandbox` from `.pugi/settings.json`, defaults to
+ * `none`. When set to `macOS-seatbelt` the probe verifies the OS
+ * primitive is callable and reports `ok` (armed) or `error`
+ * (configured-but-unavailable). When set to `none` the probe reports
+ * `warn` with the operator-readable reason "policy 'none' selected".
+ */
+import { homedir } from 'node:os';
+import { loadSettings } from '../../settings.js';
+import { probeSandbox as probeSandboxAdapter } from '../../sandboxing/index.js';
+export function probeSandbox(ctx) {
+    const settings = loadSettings(ctx.cwd);
+    const configured = (settings.bash?.sandbox ?? 'none');
+    const home = ctx.home || homedir();
+    const extraWritePaths = [`${home}/.pugi`];
+    try {
+        const state = probeSandboxAdapter({
+            mode: configured,
+            workspaceRoot: ctx.cwd,
+            extraWritePaths,
+        });
+        if (state.armed) {
+            // Discipline-gap honesty (Trust Sprint thesis): the adapter
+            // probes ok, but spawn-wrap is NOT yet wired into the bash
+            // runner (that file is owned by another agent on PUGI-VERIFY-
+            // GATE). Reporting status=ok would overstate the posture — an
+            // operator reading 'armed' would assume their bash calls were
+            // jailed when they still run with full process privileges. We
+            // surface 'warn' with a precise reason instead and flip к 'ok'
+            // when the runner indirection lands.
+            return {
+                name: 'SANDBOX',
+                status: 'warn',
+                detail: `configured (mode=${state.mode}) but spawn-wrap not yet wired — bash dispatches still run with full process privileges. ` +
+                    `Adapter posture: ${state.details.join('; ')}`,
+                remediation: 'The seatbelt adapter is in-tree and exercised by tests; the bash runner indirection that consumes it lands in a follow-up. ' +
+                    'Bash classifier denylist + permission FSM remain in force in the meantime.',
+            };
+        }
+        // Not armed — distinguish "operator chose none" from "configured
+        // mode failed". The latter is an error; the former is a documented
+        // posture and stays a warning.
+        if (state.mode === 'none') {
+            return {
+                name: 'SANDBOX',
+                status: 'warn',
+                detail: `not armed: ${state.reason ?? 'mode none'}`,
+                remediation: 'Set `bash.sandbox = "macOS-seatbelt"` in .pugi/settings.json on macOS to enable workspace-scoped write isolation. ' +
+                    'Bash classifier denylist + permission FSM still apply.',
+            };
+        }
+        return {
+            name: 'SANDBOX',
+            status: 'error',
+            detail: `configured mode "${state.mode}" failed to arm: ${state.reason ?? 'unknown'}`,
+            remediation: 'Set `bash.sandbox` to a supported mode for this platform or remove the key to fall back to "none".',
+        };
+    }
+    catch (err) {
+        return {
+            name: 'SANDBOX',
+            status: 'error',
+            detail: `sandbox probe threw: ${err.message}`,
+            remediation: 'Remove the bash.sandbox key from .pugi/settings.json or set it to "none".',
+        };
+    }
+}
+//# sourceMappingURL=sandbox.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