@askalf/dario 3.16.0 → 3.19.0

package/dist/doctor.js

@@ -0,0 +1,208 @@
+/**
+ * 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.
+ */
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir, platform, arch, release } from 'node:os';
+import { CC_TEMPLATE, } from './cc-template.js';
+import { describeTemplate, detectDrift, checkCCCompat, findInstalledCC, SUPPORTED_CC_RANGE, CURRENT_SCHEMA_VERSION, } from './live-fingerprint.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * 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 function formatChecks(checks) {
+    const prefix = {
+        ok: '[ OK ]',
+        warn: '[WARN]',
+        fail: '[FAIL]',
+        info: '[INFO]',
+    };
+    const labelWidth = checks.reduce((n, c) => Math.max(n, c.label.length), 0);
+    const lines = checks.map((c) => `  ${prefix[c.status]}  ${c.label.padEnd(labelWidth)}  ${c.detail}`);
+    return lines.join('\n');
+}
+/**
+ * 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 function exitCodeFor(checks) {
+    return checks.some((c) => c.status === 'fail') ? 1 : 0;
+}
+/**
+ * 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 async function runChecks() {
+    const checks = [];
+    // ---- dario version
+    try {
+        const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+        checks.push({ status: 'info', label: 'dario', detail: `v${pkg.version}` });
+    }
+    catch {
+        checks.push({ status: 'warn', label: 'dario', detail: 'package.json not readable — version unknown' });
+    }
+    // ---- Node
+    checks.push({
+        status: nodeStatus(),
+        label: 'Node',
+        detail: process.version,
+    });
+    // ---- Platform
+    checks.push({
+        status: 'info',
+        label: 'Platform',
+        detail: `${platform()} ${arch()} (${release()})`,
+    });
+    // ---- CC binary
+    const cc = safely(() => findInstalledCC(), { path: null, version: null });
+    if (cc.path && cc.version) {
+        const compat = checkCCCompat(cc.version);
+        const status = compat.status === 'ok' ? 'ok' :
+            compat.status === 'untested-above' ? 'warn' :
+                compat.status === 'below-min' ? 'fail' :
+                    'warn';
+        checks.push({
+            status,
+            label: 'CC binary',
+            detail: `v${cc.version} at ${cc.path}  (range: v${SUPPORTED_CC_RANGE.min} – v${SUPPORTED_CC_RANGE.maxTested})`,
+        });
+    }
+    else if (cc.path) {
+        checks.push({
+            status: 'warn',
+            label: 'CC binary',
+            detail: `found at ${cc.path} but --version didn't parse — compat unchecked`,
+        });
+    }
+    else {
+        checks.push({
+            status: 'warn',
+            label: 'CC binary',
+            detail: 'not on PATH — dario falls back to bundled template',
+        });
+    }
+    // ---- Template source
+    try {
+        checks.push({
+            status: CC_TEMPLATE._source === 'live' ? 'ok' : 'info',
+            label: 'Template',
+            detail: `${describeTemplate(CC_TEMPLATE)} (schema v${CC_TEMPLATE._schemaVersion ?? '?'})`,
+        });
+    }
+    catch (err) {
+        checks.push({ status: 'fail', label: 'Template', detail: `load failed: ${err.message}` });
+    }
+    // ---- Template drift
+    try {
+        const drift = detectDrift(CC_TEMPLATE);
+        const status = drift.installedVersion === null ? 'info' : drift.drifted ? 'warn' : 'ok';
+        checks.push({ status, label: 'Template drift', detail: drift.message });
+    }
+    catch (err) {
+        checks.push({ status: 'warn', label: 'Template drift', detail: `check failed: ${err.message}` });
+    }
+    void CURRENT_SCHEMA_VERSION; // keep the import load-bearing for future schema checks
+    // ---- OAuth
+    try {
+        const { getStatus } = await import('./oauth.js');
+        const s = await getStatus();
+        if (!s.authenticated) {
+            checks.push({
+                status: s.status === 'expired' && s.canRefresh ? 'warn' : 'fail',
+                label: 'OAuth',
+                detail: s.status === 'none' ? 'not authenticated — run `dario login`' : s.status,
+            });
+        }
+        else {
+            checks.push({ status: 'ok', label: 'OAuth', detail: `${s.status} (expires in ${s.expiresIn})` });
+        }
+    }
+    catch (err) {
+        checks.push({ status: 'warn', label: 'OAuth', detail: `check failed: ${err.message}` });
+    }
+    // ---- Account pool
+    try {
+        const { listAccountAliases, loadAllAccounts } = await import('./accounts.js');
+        const aliases = await listAccountAliases();
+        if (aliases.length === 0) {
+            checks.push({ status: 'info', label: 'Pool', detail: 'single-account mode (no pool configured)' });
+        }
+        else {
+            const loaded = await loadAllAccounts();
+            const now = Date.now();
+            const expired = loaded.filter((a) => a.expiresAt <= now).length;
+            checks.push({
+                status: expired > 0 ? 'warn' : aliases.length >= 2 ? 'ok' : 'info',
+                label: 'Pool',
+                detail: `${aliases.length} account${aliases.length === 1 ? '' : 's'}` +
+                    (expired > 0 ? `, ${expired} expired` : '') +
+                    (aliases.length < 2 ? ' (pool activates at 2+)' : ''),
+            });
+        }
+    }
+    catch (err) {
+        checks.push({ status: 'warn', label: 'Pool', detail: `check failed: ${err.message}` });
+    }
+    // ---- Secondary backends
+    try {
+        const { listBackends } = await import('./openai-backend.js');
+        const backends = await listBackends();
+        checks.push({
+            status: 'info',
+            label: 'Backends',
+            detail: backends.length === 0
+                ? 'none configured (Claude subscription is the only route)'
+                : `${backends.length} configured: ${backends.map((b) => b.name).join(', ')}`,
+        });
+    }
+    catch (err) {
+        checks.push({ status: 'warn', label: 'Backends', detail: `check failed: ${err.message}` });
+    }
+    // ---- ~/.dario dir
+    try {
+        const home = join(homedir(), '.dario');
+        checks.push({ status: 'info', label: 'Home', detail: home });
+    }
+    catch {
+        // never fails in practice — homedir() is always defined on supported platforms
+    }
+    return checks;
+}
+function nodeStatus() {
+    const m = /^v(\d+)\./.exec(process.version);
+    const major = m ? parseInt(m[1], 10) : 0;
+    // engines: >=18 (see package.json). 18/20 are current supported Node LTS
+    // lines — anything below 18 fails; above is ok.
+    if (major >= 18)
+        return 'ok';
+    if (major === 0)
+        return 'warn';
+    return 'fail';
+}
+function safely(fn, fallback) {
+    try {
+        return fn();
+    }
+    catch {
+        return fallback;
+    }
+}

package/dist/live-fingerprint.d.ts

@@ -84,10 +84,18 @@
  * contributor — or dario maintainer six months from now — can pick up
  * the right piece without re-deriving the threat model.
  */
+/**
+ * Cache-file schema version. Bump when `TemplateData` gains a required
+ * field or changes shape in a way that would make older caches produce
+ * wrong behavior if loaded verbatim. Mismatched caches are rejected at
+ * load time so the fallback + next background refresh write a fresh one.
+ */
+export declare const CURRENT_SCHEMA_VERSION = 2;
 export interface TemplateData {
     _version: string;
     _captured: string;
     _source?: 'bundled' | 'live';
+    _schemaVersion?: number;
     agent_identity: string;
     system_prompt: string;
     tools: Array<{
@@ -104,6 +112,23 @@ export interface TemplateData {
      * header ordering instead of Node's alphabetical default.
      */
     header_order?: string[];
+    /**
+     * The `anthropic-beta` flag set CC sent on the captured request, verbatim.
+     * Schema v2 (v3.19). Previously the proxy path hardcoded this — bumping
+     * CC's beta list required a dario release. Now the shim and proxy both
+     * replay whatever the live capture recorded. Falls back to
+     * `'claude-code-20250219'` when undefined (bundled snapshots, older caches).
+     */
+    anthropic_beta?: string;
+    /**
+     * Selected static headers CC sent on the captured request. Scoped to
+     * fingerprint-relevant keys — values that CC sets identically on every
+     * request and that don't change per session (user-agent, anthropic-version,
+     * x-app, x-stainless-*). Excludes auth (authorization), body-framing
+     * (content-type, content-length, host), and session-scoped identifiers
+     * (x-claude-code-session-id, x-client-request-id). Schema v2.
+     */
+    header_values?: Record<string, string>;
 }
 /**
  * Load the template synchronously. Prefers the live cache (fresh capture
@@ -131,6 +156,8 @@ export declare function refreshLiveFingerprintAsync(options?: {
     silent?: boolean;
     timeoutMs?: number;
 }): Promise<TemplateData | null>;
+/** Test-only surface for `atomicWriteJson`. Production code uses `writeLiveCache`. */
+export declare function _atomicWriteJsonForTest(targetPath: string, data: unknown): void;
 interface CapturedRequest {
     method: string;
     path: string;
@@ -151,12 +178,122 @@ interface CapturedRequest {
  * Returns null on timeout or spawn failure. Does not throw.
  */
 export declare function captureLiveTemplateAsync(timeoutMs?: number): Promise<TemplateData | null>;
+/**
+ * Locate the installed `claude` binary and its version. Thin public
+ * wrapper over `findClaudeBinary` + `probeInstalledCCVersion` — the
+ * doctor CLI and external callers use this to report install state
+ * without reaching into module-private helpers.
+ */
+export declare function findInstalledCC(): {
+    path: string | null;
+    version: string | null;
+};
 /**
  * Given a captured /v1/messages request body, pull out the fields that
  * matter for template replay: agent identity, system prompt, tool list,
  * and CC version (from the billing header or user-agent).
  */
 export declare function extractTemplate(captured: CapturedRequest): TemplateData | null;
+/**
+ * Sync-probe `claude --version` and return the parsed version string, e.g.
+ * `"2.1.104"`. Memoized per-process — the binary is invoked at most once,
+ * subsequent calls return the cached result. Returns `null` if the binary
+ * isn't on PATH, or the probe failed / timed out, or the output didn't
+ * match the expected format.
+ *
+ * Used by `detectDrift` to compare the installed CC against the version
+ * recorded in the cache at capture time.
+ */
+export declare function probeInstalledCCVersion(): string | null;
+/**
+ * Format how old a captured timestamp is, human-readable. `_captured` is
+ * an ISO string written by `extractTemplate` or the bundled snapshot.
+ * Falls back to `"unknown age"` if the timestamp doesn't parse.
+ */
+export declare function formatCaptureAge(capturedIso: string, now?: number): string;
+/**
+ * One-line human summary of the active template — what source, which CC
+ * version captured it, and how old that capture is. Proxy and shim
+ * startup log this so users can tell at a glance whether they're on a
+ * fresh live capture or a stale bundled fallback.
+ */
+export declare function describeTemplate(t: TemplateData): string;
+export interface DriftResult {
+    /** True when we can confirm the cache is from a different CC version than the one currently installed. */
+    drifted: boolean;
+    cachedVersion: string;
+    /** null when the probe couldn't run (no CC on PATH, timeout, parse fail). */
+    installedVersion: string | null;
+    /** Reason string — safe to log as-is. */
+    message: string;
+}
+/**
+ * Compare the loaded template's captured CC version against the version
+ * reported by `claude --version` on the current machine. Drifted caches
+ * are still usable — the shape is probably compatible — but the proxy
+ * should force-refresh ASAP so the next startup is back in sync.
+ *
+ * @param installedOverride test-only injection for unit tests; production
+ *   callers pass nothing and the real binary probe runs.
+ */
+export declare function detectDrift(t: TemplateData, installedOverride?: string | null): DriftResult;
+/**
+ * Reset the memoized `claude --version` probe. Test-only — production
+ * code should never need to clear the cache since the installed binary
+ * doesn't change mid-process.
+ */
+export declare function _resetInstalledVersionProbeForTest(): void;
+/**
+ * The CC version range the current dario release has been exercised
+ * against. Update `maxTested` every time we validate against a new CC
+ * (ideally as part of the release checklist — the e2e test against the
+ * user's own CC is the ground-truth signal).
+ *
+ * - `min`: below this, dario's extractor hasn't been validated; proxy
+ *   will still run but may mis-parse CC's request body.
+ * - `maxTested`: the newest CC version the current dario release has
+ *   been exercised against. Above this, dario is *likely* fine (CC's
+ *   request shape evolves slowly) but it's explicitly untested, so
+ *   users get a soft warn and we get a signal to refresh the bundled
+ *   snapshot + rerun e2e.
+ */
+export declare const SUPPORTED_CC_RANGE: {
+    readonly min: "1.0.0";
+    readonly maxTested: "2.1.104";
+};
+/**
+ * Compare two dotted-numeric version strings. Returns negative if `a<b`,
+ * zero if equal, positive if `a>b`. Handles suffixes like `-beta.1` or
+ * `.dev` by comparing the numeric prefix first and treating anything
+ * after as a tiebreaker (strings compared lexicographically; absence of
+ * suffix beats presence, matching semver's "release > prerelease").
+ *
+ * Intentionally minimal — dario's "zero runtime deps" policy rules out
+ * pulling `semver`. CC versions are well-formed `M.m.p[-suffix]` so we
+ * don't need the full spec.
+ */
+export declare function compareVersions(a: string, b: string): number;
+export type CompatStatus = 'ok' | 'untested-above' | 'below-min' | 'unknown';
+export interface CompatResult {
+    status: CompatStatus;
+    installedVersion: string | null;
+    range: {
+        min: string;
+        maxTested: string;
+    };
+    message: string;
+}
+/**
+ * Check whether the installed CC version sits inside the supported range.
+ * Called at startup by the proxy; the result drives whether we emit a
+ * compatibility warning to the user.
+ *
+ * `unknown` is not a failure — it just means we couldn't probe (no CC on
+ * PATH, timeout, parse miss). Dario still runs on bundled template.
+ *
+ * @param installedOverride test-only injection; production callers pass nothing.
+ */
+export declare function checkCCCompat(installedOverride?: string | null): CompatResult;
 /**
  * Test hook: given a captured request object (from a mocked server or a
  * synthetic fixture), run it through the same extraction path. Exposed so