@askalf/dario 6.0.12 → 6.0.13

package/dist/doctor-core.d.ts

@@ -0,0 +1,239 @@
+/**
+ * dario doctor — health report aggregator.
+ *
+ * Runs every check we know how to run and returns a list of labelled
+ * results. The CLI passes the result list through `formatChecks` for
+ * display; `runChecks` is the I/O-heavy collector, `formatChecks` is a
+ * pure function the tests exercise directly.
+ *
+ * Keep `runChecks` defensive: a check that throws must not take the
+ * rest of the report down — every check is wrapped so a broken sub-
+ * system surfaces as `fail` instead of crashing the CLI.
+ */
+export type CheckStatus = 'ok' | 'warn' | 'fail' | 'info';
+export interface Check {
+    /** 'ok' passes; 'warn' is advisory; 'fail' blocks (exit code 1); 'info' is neutral. */
+    status: CheckStatus;
+    /** Short left-column label, e.g. `"Node"`, `"CC binary"`. */
+    label: string;
+    /** Right-column detail — human readable, may include versions, paths, counts. */
+    detail: string;
+}
+/**
+ * Decide what `doctor` should say about pool-exhaustion failover, from
+ * configuration alone. Pure and exported so every branch is testable — the
+ * live box can only ever exercise the one that matches its own credentials,
+ * which is how the inert case went unnoticed in the first place.
+ *
+ * This check exists because of a specific outage. The box ran with
+ * --pool-fallback armed, no Codex account and no api-key backend, so failover
+ * was INERT: correctly configured by every check that existed, and incapable of
+ * doing anything. On 2026-08-29 the Claude pool filled twice and the fleet went
+ * dark beside an idle ChatGPT subscription. Nothing reported it, because
+ * nothing asked "armed" and "has somewhere to go" as a single question.
+ *
+ * It reports configuration, never reachability. Claiming a route WORKS needs a
+ * live request, and this release was built on the lesson that a green config is
+ * not a working path.
+ */
+export declare function failoverReadiness(input: {
+    chain: readonly string[];
+    codexAccounts: number;
+    backends: readonly string[];
+}): {
+    status: CheckStatus;
+    detail: string;
+};
+/**
+ * Format a epoch timestamp reset time relative to the current time.
+ * Returns a human-friendly string like "1h 9m", "45m", "2d 3h".
+ */
+export declare function formatReset(resetEpochSecs: number, nowMs: number): string;
+/**
+ * Pretty-print a list of Check results as aligned ASCII. No color codes —
+ * Windows cmd / CI logs render plain text reliably; colors are a downside
+ * not an upside for a report that's often piped or pasted.
+ */
+export declare function formatChecks(checks: Check[]): string;
+/**
+ * Derive a CLI exit code from a set of check results. Any `fail` → 1.
+ * `warn` alone does not fail — we don't want `dario doctor` to CI-fail
+ * a user's machine just because they're on an untested CC version.
+ */
+export declare function exitCodeFor(checks: Check[]): number;
+/**
+ * Serialize a check report as structured JSON. Lets other tools
+ * (claude-bridge's /status command, deepdive, CI scripts) consume
+ * dario's health programmatically instead of scraping the formatted
+ * text. Emitted by `dario doctor --json`.
+ */
+export declare function formatChecksJson(checks: Check[]): string;
+/**
+ * Pure function: compare each pool account's stored {deviceId, accountUuid}
+ * against the live `.claude.json` identity and return Check rows describing
+ * any drift. Factored out of runChecks so it's unit-testable without I/O.
+ *
+ * Drift surfaces when a user re-installs Claude Code (or switches the active
+ * account inside CC) AFTER `dario accounts add`, so the stored snapshot in
+ * `~/.dario/accounts/<alias>.json` no longer matches what the proxy reads
+ * live from `~/.claude.json` per request. Anthropic cross-validates the
+ * OAuth bearer against `metadata.user_id` (built from the live deviceId)
+ * and 401s with `authentication_error` on non-Haiku models when they
+ * disagree — Haiku is more permissive and may succeed despite the mismatch,
+ * which makes the failure mode look intermittent and account-tier-shaped
+ * even though it's an identity-staleness bug.
+ *
+ * Single-account mode (no pool, just `~/.dario/credentials.json`) is not
+ * covered here: the proxy reads identity live and dario never stored a
+ * baseline to compare against. Future: add `dario doctor --identity` for
+ * an opt-in network probe that hits Anthropic with the bearer and live
+ * deviceId to confirm they align.
+ */
+export interface IdentityDriftInput {
+    /** Live `{deviceId, accountUuid}` from `~/.claude.json`, or null if absent. */
+    live: {
+        deviceId: string;
+        accountUuid: string;
+    } | null;
+    /** Pool account snapshots — `[]` when no pool accounts are materialized yet. */
+    poolAccounts: Array<{
+        alias: string;
+        deviceId: string;
+        accountUuid: string;
+    }>;
+}
+/**
+ * The OAuth doctor row, as a pure decision — mirrors checkIdentityDrift so the
+ * branch logic is unit-testable without touching the filesystem.
+ *
+ * WHY THIS EXISTS. The legacy `credentials.json` is not what serves once an
+ * account pool exists: dario#805 deliberately keeps a NEWER pool token and
+ * refuses to overwrite that file, so "credentials.json is stale" is an expected
+ * steady state — every recovery that restores a pool account leaves one behind.
+ * Reporting that as `OAuth expired` while the pool answers every request is a
+ * false alarm, and dario-doctor-watch opens an issue for it on EVERY run:
+ * dario#1105 was filed while a live probe was returning 200 on both Haiku and
+ * Sonnet. A watcher that cries wolf on a healthy proxy trains its reader to
+ * ignore it, which is the failure the watcher exists to prevent.
+ *
+ * So: a live pool overrides a dead legacy file (and says so, rather than hiding
+ * it), and only "nothing can serve" is reported as a failure.
+ */
+export declare function oauthCheckRow(input: {
+    legacyStatus: string;
+    legacyCanRefresh: boolean;
+    poolHealthy: number;
+    poolTotal: number;
+}): Check;
+export declare function checkIdentityDrift(input: IdentityDriftInput): Check[];
+export declare function probeNpmLatestCC(): string | null;
+/**
+ * The client system prompt the `--obedience` probe sends. Deliberately
+ * trivial: any model that weighs client system text at all can comply,
+ * so a miss isolates "the client system prompt is being ignored" from
+ * "the instruction was too hard".
+ */
+export declare const OBEDIENCE_SYSTEM_PROMPT = "Reply with ONLY the word PONG. No other words, no punctuation, no formatting.";
+/**
+ * Join the text blocks of a `/v1/messages` response body. Thinking
+ * blocks are excluded — adaptive thinking may prepend them and they are
+ * not part of what the client-facing instruction governs. A refusal
+ * (empty content) or a malformed body yields ''.
+ */
+export declare function extractMessageText(body: unknown): string;
+/**
+ * Verdict for one obedience reply. Lenient on case and a single trailing
+ * `.`/`!` — the drift class this detects is "the model ignored the client
+ * system prompt entirely" (it answers as the CC persona instead), and a
+ * stray "Pong!" is obedient in substance. Strict equality would file
+ * 6-hourly drift issues over punctuation sampling.
+ */
+export declare function isObedientReply(text: string): boolean;
+export interface RunChecksOptions {
+    /**
+     * Opt-in: hit Anthropic's authorize endpoint with the scope set dario
+     * would use on `accounts add`, and surface the server's verdict as a
+     * check row. Default off — `dario doctor` without `--probe` is a
+     * read-only local scan, no outbound traffic beyond what the other
+     * checks already make (OAuth token refresh, CC binary version probe,
+     * npm drift check). Enable with `dario doctor --probe`; costs one
+     * GET to `claude.ai` and runs in parallel with the other checks.
+     */
+    probe?: boolean;
+    /**
+     * Opt-in: fire a minimal `POST /v1/messages` through the user's OAuth
+     * (Haiku, `max_tokens=1`) to capture the current rate-limit snapshot,
+     * including the unified buckets AND the per-model buckets Anthropic
+     * started carving in late April 2026 (`7d_sonnet-utilization` etc).
+     * Surfaces "All models X%, Sonnet only Y%" the way the user dashboard
+     * does. Enable with `dario doctor --usage`; costs ~1 subscription
+     * request.
+     */
+    usage?: boolean;
+    /**
+     * Opt-in: probe each model family THROUGH the running proxy with a
+     * client system prompt ("reply with ONLY the word PONG") and assert
+     * the reply obeys. Catches upstream behavioral drift in client-system
+     * steering — the 2026-06-12 class (dario#509) where sonnet silently
+     * stopped following client system text while every other signal
+     * (200s, subscription billing, template labels, model smoke) stayed
+     * green. Enable with `dario doctor --obedience`; costs at most
+     * `families × 3` tiny subscription requests.
+     */
+    obedience?: boolean;
+}
+/**
+ * Run every available health check. Never throws — each check is
+ * individually try/caught so a broken subsystem (e.g. unreadable accounts
+ * dir) shows up as a `fail` row instead of crashing the CLI.
+ *
+ * The order is curated — more fundamental checks first (Node, dario
+ * version, platform) so a reader scanning the output top-down sees
+ * the environment before the subsystems.
+ */
+export declare function runChecks(opts?: RunChecksOptions): Promise<Check[]>;
+export interface SeenHeader {
+    present: boolean;
+    /** Redacted preview: `"abcd...wxyz"` — first 4 + last 4 chars, or length tag if the value is too short to excerpt safely. */
+    redacted?: string;
+    length?: number;
+    /** For Authorization: whether the value started with "Bearer " (case-insensitive). */
+    bearerPrefix?: boolean;
+    /** Did this header's value (after any `Bearer ` strip) match DARIO_API_KEY? */
+    matches?: boolean;
+}
+export type AuthCheckVerdict = 'match' | 'mismatch' | 'no-auth-header' | 'timeout' | 'no-enforcement';
+export interface AuthCheckResult {
+    received: boolean;
+    port?: number;
+    expected: string;
+    xApiKey?: SeenHeader;
+    authorization?: SeenHeader;
+    verdict: AuthCheckVerdict;
+    diagnosis: string;
+}
+export interface AuthCheckOptions {
+    /** Milliseconds to wait for an inbound request. Default 30,000. */
+    timeoutMs?: number;
+    /** Override the expected key. Default: `process.env.DARIO_API_KEY`. */
+    expectedKey?: string;
+    /** Test hook: called when the server is listening, with the port. */
+    onListening?: (port: number) => void;
+}
+export declare function redactSecret(value: string): string;
+export declare function classifyAuthHeaders(headers: {
+    'x-api-key'?: string | string[];
+    authorization?: string | string[];
+}, expected: string): {
+    xApiKey: SeenHeader;
+    authorization: SeenHeader;
+    verdict: AuthCheckVerdict;
+};
+/**
+ * Listen for one inbound request on a random loopback port, classify
+ * whatever auth headers it carries against `DARIO_API_KEY`, return a
+ * structured result. Sends 200 / 401 to the inbound request so the
+ * client doesn't hang, then closes. This is a probe — it does not
+ * proxy, does not log, does not persist.
+ */
+export declare function runAuthCheck(opts?: AuthCheckOptions): Promise<AuthCheckResult>;