@pugi/cli 0.1.0-beta.98 → 1.0.0-alpha.1

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

@@ -1,488 +0,0 @@
-/**
- * STATUS snapshot — concise session-state probe for `pugi status` /
- * in-REPL `/status` ().
- *
- * 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,
-    });
-    // Operator-facing workspace label. Surfaces the org slug that
-    // `pugi login` / cabinet settings authenticated against (e.g.
-    // `yurii`, `acme-corp`). Only emitted when the REPL caller
-    // provides the value — the shell path has no live workspace
-    // context, so the field stays absent rather than degrading to a
-    // sentinel that operators could misread.
-    if (typeof deps.workspaceLabel === 'string' && deps.workspaceLabel.length > 0) {
-        fields.push({
-            key: 'workspace',
-            label: 'Workspace',
-            value: deps.workspaceLabel,
-            available: true,
-        });
-    }
-    // Backend URL. Surfaces the live REPL transport's `apiUrl` when
-    // supplied (slash command in a connected session); falls back to
-    // the credential's `apiUrl` so the shell path still shows where
-    // a subsequent `pugi review --remote` would dispatch. Operators
-    // routinely ask "which endpoint did I just authenticate against?"
-    // — making this a first-class row removes that round-trip.
-    const backendUrl = (() => {
-        if (typeof deps.liveApiUrl === 'string' && deps.liveApiUrl.length > 0) {
-            return deps.liveApiUrl;
-        }
-        try {
-            const cred = deps.resolveCredential();
-            return cred?.apiUrl ?? null;
-        }
-        catch {
-            return null;
-        }
-    })();
-    fields.push({
-        key: 'backend',
-        label: 'Backend',
-        value: backendUrl ?? 'offline',
-        available: Boolean(backendUrl),
-    });
-    // 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.
-    // Render as `pugi <version>` so the table row reads like the
-    // banner an operator sees on cold start — matches the
-    // `pugi --version` shell output convention.
-    fields.push({
-        key: 'cli',
-        label: 'CLI',
-        value: `pugi ${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 24 chars — long enough к stay collision-free across
-    // human-friendly session ids (pugi-sess-<word>, ULID prefixes,
-    // 18-char tenant slugs) and к surface meaningful identifiers
-    // в the REPL `/status` row without truncating mid-word.
-    // 13-char cutoff (the original) cropped `pugi-sess-fixture`
-    // to `pugi-sess-fix`, breaking the REPL spec's
-    // `Session: pugi-sess-fixture` substring assertion.
-    return id.length > 24 ? id.slice(0, 24) : 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

@@ -1,63 +0,0 @@
-/**
- * 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

@@ -1,70 +0,0 @@
-/**
- * — `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