@pugi/cli 0.1.0-beta.2 → 0.1.0-beta.20

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

package/dist/core/diagnostics/probes/status-snapshot.js

@@ -0,0 +1,442 @@
+/**
+ * STATUS snapshot — concise session-state probe for `pugi status` /
+ * in-REPL `/status` (Leak L34, 2026-05-27).
+ *
+ * Different from `pugi doctor` (which probes ENVIRONMENT health —
+ * Node version, disk space, auth round-trip, MCP servers, …). The
+ * status snapshot answers the operator question "what is THIS
+ * Pugi session doing right now?" — current session id + age, cwd,
+ * permission mode, CLI version, cumulative token usage, active
+ * dispatches, last command, compact boundary count, auth identity.
+ *
+ * # Fail-soft contract
+ *
+ * Every field is gathered via try/catch. A missing dep (permission
+ * state module not yet present, no `.pugi/agent-progress/` dir,
+ * no `~/.pugi/credentials.json`) is **never** an error — it
+ * degrades to `null` for nullable fields or a sentinel label
+ * (`"unknown"`, `"n/a"`, `0`) for required ones. The snapshot
+ * never throws; the renderer can always print a complete table.
+ *
+ * The module is intentionally dep-injected so the spec can drive
+ * every fail-soft branch without standing up `fs`, the credential
+ * store, or a real process clock. The `runStatusCommand` wrapper
+ * in `runtime/commands/status.ts` plugs in production deps.
+ *
+ * # Field semantics
+ *
+ *   sessionId / sessionAgeMs : taken verbatim from caller when in
+ *     REPL mode (the slash dispatcher passes the live id +
+ *     `briefStartedAtEpochMs`); else best-effort from the on-disk
+ *     `.pugi/events.jsonl` mtime, OR null when no prior dispatch is
+ *     logged in the workspace.
+ *
+ *   cwd : pure function of the caller's `ctx.cwd`. Never null.
+ *
+ *   permissionMode : reads the optional permissions state module
+ *     when available (L6 in the leak-parity roadmap). On any
+ *     import failure the field degrades to "unknown" so this
+ *     command lands before L6 without a compile-time coupling.
+ *
+ *   cliVersion : injected literal so the build's PUGI_CLI_VERSION
+ *     constant is the single source of truth.
+ *
+ *   tokensUsed : injected from the caller — REPL mode passes the
+ *     live `sessionTokensIn + sessionTokensOut` total; the
+ *     top-level `pugi status` invocation has no REPL state so
+ *     this field stays null and the renderer prints "n/a".
+ *
+ *   activeDispatches / completedDispatches : counted by scanning
+ *     `.pugi/agent-progress/*.json` and classifying by the
+ *     `status` field. Missing dir → 0/0 (no crash).
+ *
+ *   lastCommand : injected from the REPL when available; null on
+ *     the top-level shell path so the renderer prints "n/a".
+ *
+ *   compactBoundaries : counts lines in `.pugi/events.jsonl`
+ *     where the event `kind === 'compact.boundary'`. Missing file
+ *     → 0. Wired against Memory Phase 0 NDJSON; downgrade to 0 if
+ *     the file is malformed.
+ *
+ *   auth : resolved via the same credential helper `pugi whoami`
+ *     uses. Returns either an `{ apiUrl, apiKey, label?, tier? }`
+ *     summary or null when the operator is not authenticated. We
+ *     do NOT make a network call here — the tier is read from
+ *     local creds metadata; live tier lookup belongs to
+ *     `pugi whoami --remote` (separate command).
+ */
+/**
+ * Collect the full snapshot. The function is synchronous because
+ * every field source is local (process state, fs, injected
+ * resolvers) — no network calls.
+ */
+export function collectStatusSnapshot(deps) {
+    const fields = [];
+    // Session id + age. REPL-mode caller passes both; top-level
+    // shell path passes neither и we fall back to the on-disk NDJSON
+    // tail mtime so the operator still sees a useful age figure for
+    // the most-recent workspace activity.
+    fields.push(buildSessionField(deps));
+    // Working directory. Pure function of caller's ctx — always
+    // available (sentinel only if caller passed an empty string,
+    // which the renderer treats as "unknown").
+    fields.push({
+        key: 'workdir',
+        label: 'Workdir',
+        value: deps.cwd.length > 0 ? deps.cwd : 'unknown',
+        available: deps.cwd.length > 0,
+    });
+    // Permission mode. Fail-soft — degrades к "unknown" until L6
+    // lands the permissions/state module.
+    fields.push(buildPermissionModeField(deps));
+    // Pugi CLI version. The build-time constant is the single
+    // source of truth; sanitised upstream (sanitizeSemver in
+    // runtime/version.ts) so we never see `workspace:*` here.
+    fields.push({
+        key: 'cli',
+        label: 'CLI',
+        value: deps.cliVersion,
+        available: deps.cliVersion !== '0.0.0-unknown',
+    });
+    // Token usage. REPL caller passes the live total; shell path
+    // degrades к "n/a" (no REPL state in a fresh process).
+    fields.push(buildTokenField(deps));
+    // Active + completed dispatches scanned from
+    // `.pugi/agent-progress/*.json`. Missing dir → 0 active, 0
+    // completed (no crash).
+    fields.push(buildDispatchField(deps));
+    // Last command. REPL caller passes the most-recent operator
+    // line + its timestamp; shell path degrades к "n/a".
+    fields.push(buildLastCommandField(deps));
+    // Compact boundary marker count. Read from
+    // `.pugi/events.jsonl` per Memory Phase 0; missing file → 0.
+    fields.push(buildCompactField(deps));
+    // Auth identity. Read from the credential resolver — local-only
+    // (no network call); the live tier comes from the stored
+    // credential metadata.
+    fields.push(buildAuthField(deps));
+    // Connection mode. Today simply mirrors the credential source
+    // (env vs file) so the operator can see at a glance whether
+    // they are in CI-env mode or a logged-in shell. Future wiring
+    // overlays the REPL's live connection state when invoked from
+    // the slash dispatcher.
+    fields.push(buildConnectionField(deps));
+    return {
+        command: 'status',
+        fields,
+        meta: {
+            cliVersion: deps.cliVersion,
+            nodeVersion: process.version,
+            cwd: deps.cwd,
+            capturedAt: new Date(deps.now()).toISOString(),
+        },
+    };
+}
+/* -------------------------- field builders -------------------------- */
+function buildSessionField(deps) {
+    if (deps.liveSessionId && deps.liveSessionId.length > 0) {
+        const ageMs = typeof deps.sessionStartedAtEpochMs === 'number' && deps.sessionStartedAtEpochMs > 0
+            ? Math.max(0, deps.now() - deps.sessionStartedAtEpochMs)
+            : null;
+        const ageLabel = ageMs === null ? '' : ` (${formatAgeShort(ageMs)})`;
+        return {
+            key: 'session',
+            label: 'Session',
+            value: `${shortId(deps.liveSessionId)}${ageLabel}`,
+            available: true,
+        };
+    }
+    // Top-level shell path: best-effort tail of .pugi/events.jsonl.
+    const eventsPath = `${deps.cwd}/.pugi/events.jsonl`;
+    try {
+        if (!deps.fs.existsSync(eventsPath)) {
+            return {
+                key: 'session',
+                label: 'Session',
+                value: 'unbound (no prior dispatch in this workspace)',
+                available: false,
+                note: '.pugi/events.jsonl not found',
+            };
+        }
+        const stats = deps.fs.statSync(eventsPath);
+        const ageMs = Math.max(0, deps.now() - stats.mtimeMs);
+        return {
+            key: 'session',
+            label: 'Session',
+            value: `unbound · last activity ${formatAgeShort(ageMs)} ago`,
+            // Shell path never has a live id — flag as unavailable so the
+            // renderer can dim the row.
+            available: false,
+            note: 'shell-mode: showing last NDJSON activity instead of a live id',
+        };
+    }
+    catch (error) {
+        return {
+            key: 'session',
+            label: 'Session',
+            value: 'unknown',
+            available: false,
+            note: errorNote(error),
+        };
+    }
+}
+function buildPermissionModeField(deps) {
+    try {
+        const mode = deps.resolvePermissionMode();
+        if (mode && mode.length > 0) {
+            return {
+                key: 'mode',
+                label: 'Mode',
+                value: mode,
+                available: true,
+            };
+        }
+        return {
+            key: 'mode',
+            label: 'Mode',
+            value: 'unknown',
+            available: false,
+            note: 'permission state module not yet present (lands with L6)',
+        };
+    }
+    catch (error) {
+        return {
+            key: 'mode',
+            label: 'Mode',
+            value: 'unknown',
+            available: false,
+            note: errorNote(error),
+        };
+    }
+}
+function buildTokenField(deps) {
+    if (typeof deps.liveTokensUsed === 'number' && deps.liveTokensUsed >= 0) {
+        return {
+            key: 'tokens',
+            label: 'Tokens',
+            value: `~${formatThousands(deps.liveTokensUsed)} used this session`,
+            available: true,
+        };
+    }
+    return {
+        key: 'tokens',
+        label: 'Tokens',
+        value: 'n/a (REPL not active)',
+        available: false,
+        note: 'token counter only available inside a live REPL session',
+    };
+}
+function buildDispatchField(deps) {
+    const dir = `${deps.cwd}/.pugi/agent-progress`;
+    try {
+        if (!deps.fs.existsSync(dir)) {
+            return {
+                key: 'dispatches',
+                label: 'Dispatches',
+                value: '0 active, 0 completed',
+                available: false,
+                note: '.pugi/agent-progress/ not present',
+            };
+        }
+        const entries = deps.fs.readdirSync(dir);
+        let active = 0;
+        let completed = 0;
+        for (const entry of entries) {
+            if (!entry.endsWith('.json'))
+                continue;
+            try {
+                const raw = deps.fs.readFileSync(`${dir}/${entry}`, 'utf8');
+                const parsed = JSON.parse(raw);
+                const status = typeof parsed.status === 'string' ? parsed.status.toLowerCase() : null;
+                const completedAt = typeof parsed.completedAt === 'string' ? parsed.completedAt : null;
+                if (status === 'complete' || status === 'completed' || completedAt) {
+                    completed += 1;
+                }
+                else {
+                    active += 1;
+                }
+            }
+            catch {
+                // Malformed progress JSON shouldn't crash the snapshot.
+                // Count it as active so the operator sees the row + can
+                // open the file manually.
+                active += 1;
+            }
+        }
+        return {
+            key: 'dispatches',
+            label: 'Dispatches',
+            value: `${active} active, ${completed} completed`,
+            available: true,
+        };
+    }
+    catch (error) {
+        return {
+            key: 'dispatches',
+            label: 'Dispatches',
+            value: '0 active, 0 completed',
+            available: false,
+            note: errorNote(error),
+        };
+    }
+}
+function buildLastCommandField(deps) {
+    if (typeof deps.lastCommand === 'string' && deps.lastCommand.trim().length > 0) {
+        const cmd = truncate(deps.lastCommand.trim(), 60);
+        const agoLabel = typeof deps.lastCommandAtEpochMs === 'number' && deps.lastCommandAtEpochMs > 0
+            ? ` (${formatAgeShort(Math.max(0, deps.now() - deps.lastCommandAtEpochMs))} ago)`
+            : '';
+        return {
+            key: 'lastCommand',
+            label: 'Last cmd',
+            value: `${cmd}${agoLabel}`,
+            available: true,
+        };
+    }
+    return {
+        key: 'lastCommand',
+        label: 'Last cmd',
+        value: 'n/a',
+        available: false,
+        note: 'no command observed in this session',
+    };
+}
+function buildCompactField(deps) {
+    const eventsPath = `${deps.cwd}/.pugi/events.jsonl`;
+    try {
+        if (!deps.fs.existsSync(eventsPath)) {
+            return {
+                key: 'compact',
+                label: 'Compact',
+                value: '0 boundary markers',
+                available: false,
+                note: '.pugi/events.jsonl not present',
+            };
+        }
+        const raw = deps.fs.readFileSync(eventsPath, 'utf8');
+        let count = 0;
+        for (const line of raw.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed.length === 0)
+                continue;
+            try {
+                const parsed = JSON.parse(trimmed);
+                const kind = typeof parsed.kind === 'string' ? parsed.kind : null;
+                const type = typeof parsed.type === 'string' ? parsed.type : null;
+                if (kind === 'compact.boundary' || type === 'compact.boundary') {
+                    count += 1;
+                }
+            }
+            catch {
+                // Malformed line in NDJSON is not a snapshot failure.
+                // Skip and keep counting.
+            }
+        }
+        return {
+            key: 'compact',
+            label: 'Compact',
+            value: `${count} boundary marker${count === 1 ? '' : 's'}`,
+            available: true,
+        };
+    }
+    catch (error) {
+        return {
+            key: 'compact',
+            label: 'Compact',
+            value: '0 boundary markers',
+            available: false,
+            note: errorNote(error),
+        };
+    }
+}
+function buildAuthField(deps) {
+    try {
+        const cred = deps.resolveCredential();
+        if (!cred) {
+            return {
+                key: 'auth',
+                label: 'Auth',
+                value: 'not signed in',
+                available: false,
+                note: 'run `pugi login` к authenticate',
+            };
+        }
+        const identity = cred.identity ?? cred.label ?? cred.apiUrl;
+        const tier = cred.tier ? ` (tier: ${cred.tier})` : '';
+        return {
+            key: 'auth',
+            label: 'Auth',
+            value: `${identity}${tier}`,
+            available: true,
+        };
+    }
+    catch (error) {
+        return {
+            key: 'auth',
+            label: 'Auth',
+            value: 'unknown',
+            available: false,
+            note: errorNote(error),
+        };
+    }
+}
+function buildConnectionField(deps) {
+    try {
+        const cred = deps.resolveCredential();
+        if (!cred) {
+            return {
+                key: 'connection',
+                label: 'Connection',
+                value: 'offline (no credential)',
+                available: false,
+            };
+        }
+        return {
+            key: 'connection',
+            label: 'Connection',
+            value: cred.apiUrl,
+            available: true,
+        };
+    }
+    catch {
+        return {
+            key: 'connection',
+            label: 'Connection',
+            value: 'unknown',
+            available: false,
+        };
+    }
+}
+/* ---------------------------- formatters ---------------------------- */
+export function formatAgeShort(ms) {
+    if (!Number.isFinite(ms) || ms < 0)
+        return '0s';
+    if (ms < 60_000)
+        return `${Math.round(ms / 1000)} sec`;
+    if (ms < 3_600_000)
+        return `${Math.round(ms / 60_000)} min`;
+    if (ms < 86_400_000)
+        return `${Math.round(ms / 3_600_000)} hr`;
+    return `${Math.round(ms / 86_400_000)} day`;
+}
+export function formatThousands(value) {
+    if (!Number.isFinite(value) || value < 0)
+        return '0';
+    return Math.round(value).toLocaleString('en-US');
+}
+export function shortId(id) {
+    // The full ULID / UUID is awkward in a table cell. Keep the
+    // first 13 chars (long enough к stay collision-free across the
+    // recent-sessions list, short enough к share at a glance).
+    return id.length > 13 ? id.slice(0, 13) : id;
+}
+export function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, Math.max(1, max - 1))}…`;
+}
+function errorNote(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return `field unavailable: ${message}`;
+}
+//# sourceMappingURL=status-snapshot.js.map

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

@@ -0,0 +1,63 @@
+/**
+ * WORKSPACE probe — verifies `.pugi/` exists, is writable, and is not
+ * littered with stale lock files. Optional NDJSON session log presence
+ * is reported as additional context but never the basis for a verdict
+ * change (it is created on first dispatch, not at init time).
+ *
+ * The probe owns its fs surface so the spec can run in a tmp sandbox.
+ */
+export function probeWorkspace(ctx, fs) {
+    const pugiDir = `${ctx.cwd}/.pugi`;
+    if (!fs.existsSync(pugiDir)) {
+        return {
+            name: 'WORKSPACE',
+            status: 'warn',
+            detail: `.pugi/ not initialised in ${ctx.cwd}`,
+            remediation: 'Run `pugi init` to scaffold the workspace',
+        };
+    }
+    let isDir = false;
+    try {
+        isDir = fs.statSync(pugiDir).isDirectory();
+    }
+    catch {
+        return {
+            name: 'WORKSPACE',
+            status: 'error',
+            detail: `.pugi/ stat failed in ${ctx.cwd}`,
+            remediation: 'Re-create the directory: `rm -rf .pugi && pugi init`',
+        };
+    }
+    if (!isDir) {
+        return {
+            name: 'WORKSPACE',
+            status: 'error',
+            detail: `${pugiDir} exists but is not a directory`,
+            remediation: 'Remove the file at .pugi and run `pugi init`',
+        };
+    }
+    try {
+        fs.accessSync(pugiDir, fs.W_OK);
+    }
+    catch {
+        return {
+            name: 'WORKSPACE',
+            status: 'error',
+            detail: `.pugi/ is not writable for the current user`,
+            remediation: `chown / chmod the directory so the current user can write it`,
+        };
+    }
+    // Best-effort: report session log presence as detail context. Absence
+    // is normal (events.jsonl is created lazily) so it never moves the
+    // verdict.
+    const eventLogPresent = fs.existsSync(`${pugiDir}/events.jsonl`);
+    const detail = eventLogPresent
+        ? `.pugi/ writable, events.jsonl present`
+        : `.pugi/ writable (events.jsonl created on first dispatch)`;
+    return {
+        name: 'WORKSPACE',
+        status: 'ok',
+        detail,
+    };
+}
+//# sourceMappingURL=workspace.js.map

package/dist/core/diagnostics/types.js

@@ -0,0 +1,70 @@
+/**
+ * Leak L17 — `pugi doctor` diagnostics types.
+ *
+ * The doctor command probes the local environment + remote API +
+ * workspace state and produces a structured health report. Each probe
+ * runs independently; one probe's failure NEVER cascades to another.
+ *
+ * Status semantics:
+ *   - `ok`      : probe verified the expected state.
+ *   - `warn`    : non-blocking signal (stale CLI, low-but-not-empty disk,
+ *                 missing optional config, etc.). Overall verdict still
+ *                 passes the gate.
+ *   - `error`   : a real problem the operator must fix before Pugi will
+ *                 work end-to-end (auth missing, API unreachable, .pugi/
+ *                 unwritable, Node version below floor, disk full).
+ *   - `skipped` : prerequisite for the probe is absent (e.g. MCP probe
+ *                 when no mcp.json exists). Does NOT count against the
+ *                 overall verdict.
+ *
+ * Layered design: this module owns NO I/O. Individual probe files own
+ * their I/O surface. The runner orchestrates them in parallel with a
+ * timeout + fail-isolation wrapper. The doctor command formats the
+ * results for human + JSON consumers.
+ */
+/**
+ * Helper for the runner to compute the overall verdict from a probe
+ * set without leaking the algorithm into the doctor command. Any error
+ * → 'error'; any warn (no errors) → 'warning'; otherwise 'healthy'.
+ * Skipped probes do NOT influence the verdict.
+ */
+export function computeOverall(probes) {
+    let hasError = false;
+    let hasWarn = false;
+    for (const probe of probes) {
+        if (probe.status === 'error')
+            hasError = true;
+        else if (probe.status === 'warn')
+            hasWarn = true;
+    }
+    if (hasError)
+        return 'error';
+    if (hasWarn)
+        return 'warning';
+    return 'healthy';
+}
+/**
+ * Compute the per-status counts in a single pass so renderers do not
+ * have to re-iterate. Surfaces in both the trailer line and the JSON
+ * envelope so downstream consumers can render a one-line summary
+ * without re-walking the probe array.
+ */
+export function countProbes(probes) {
+    const counts = { ok: 0, warn: 0, error: 0, skipped: 0 };
+    for (const probe of probes)
+        counts[probe.status] += 1;
+    return counts;
+}
+/**
+ * Exit-code map. Exposed for both the CLI handler and the spec so the
+ * contract stays in one place.
+ *   0 — healthy OR warnings only.
+ *   1 — internal crash (unhandled throw in the runner itself).
+ *   2 — at least one probe reported `error`.
+ */
+export function exitCodeFor(overall) {
+    if (overall === 'error')
+        return 2;
+    return 0;
+}
+//# sourceMappingURL=types.js.map