@zigrivers/scaffold 3.28.0 → 3.29.0

package/dist/knowledge-freshness/providers/deepseek.js

@@ -0,0 +1,157 @@
+import { fetch as undiciFetch } from 'undici';
+import { z } from 'zod';
+/**
+ * SECURITY: like decision #7's anthropic-subprocess invariant, the
+ * DeepSeek URL and the model-name allowlist are HARDCODED. Project-local
+ * config can never redirect this dispatcher at a different host or run
+ * an unsupported model. Future contributors who feel tempted to read a
+ * URL from `.scaffold/observability.yaml` here should re-read the parent
+ * design doc's Resolved Decisions table first.
+ */
+export const DEEPSEEK_URL = 'https://api.deepseek.com/chat/completions';
+/**
+ * Hardcoded allowlist of DeepSeek model names. KNOWLEDGE_FRESHNESS_DEEPSEEK_MODEL
+ * may override the default, but only to a value in this set — never to
+ * arbitrary text. The previously-supported `deepseek-chat` and
+ * `deepseek-reasoner` IDs are deprecated and intentionally excluded.
+ */
+const ALLOWED_MODELS = ['deepseek-v4-flash', 'deepseek-v4-pro'];
+export const DEFAULT_DEEPSEEK_MODEL = 'deepseek-v4-flash';
+const MAX_TOKENS = 8192;
+/**
+ * Minimal Zod schema for the DeepSeek (OpenAI-compatible) response. We
+ * validate only the path we actually consume — `choices[0].message.content`
+ * — rather than the whole API surface. Replaces the previous inline
+ * `as { choices?: … }` cast (round-2 F-003) so the response shape is
+ * checked at parse time, not implicitly via optional-chaining-then-typeof.
+ */
+const responseSchema = z.object({
+    choices: z.array(z.object({
+        message: z.object({ content: z.string() }),
+    })).min(1),
+});
+export function buildDeepseekDispatcher(opts) {
+    const model = opts.model ?? DEFAULT_DEEPSEEK_MODEL;
+    if (!ALLOWED_MODELS.includes(model)) {
+        throw new Error(`unsupported DeepSeek model "${model}". Allowed values: ${ALLOWED_MODELS.join(', ')}. ` +
+            'Set KNOWLEDGE_FRESHNESS_DEEPSEEK_MODEL to one of those, or unset it to use the default.');
+    }
+    if (!opts.apiKey) {
+        throw new Error('DEEPSEEK_API_KEY is required to use the deepseek provider');
+    }
+    const doFetch = opts.fetchImpl ?? undiciFetch;
+    const timeoutMs = opts.timeoutSec * 1000;
+    return async (prompt) => {
+        const body = JSON.stringify({
+            model,
+            messages: [{ role: 'user', content: prompt }],
+            // Thinking mode defaults ON for v4 models and IGNORES temperature
+            // (per https://api-docs.deepseek.com/guides/thinking_mode). The
+            // audit prompt produces structured JSON via the runner's schema-
+            // aware extractor — chain-of-thought reasoning before the JSON
+            // wastes the output token budget and produces non-deterministic
+            // text. Disable thinking so temperature: 0 actually takes effect
+            // and the response goes straight to the verdict.
+            thinking: { type: 'disabled' },
+            temperature: 0,
+            max_tokens: MAX_TOKENS,
+            stream: false,
+        });
+        // Timeout via AbortSignal.timeout — stable since Node 16.14 / 17.3
+        // (verified at https://nodejs.org/api/globals.html#abortsignaltimeoutdelay).
+        // The same pattern is already used in source-hash.ts and link-check.ts;
+        // an earlier review-round claim that this method was unavailable on
+        // 18.17 turned out to be a hallucination.
+        //
+        // EVERY step from doFetch through response-body read is wrapped in a
+        // single try/catch that normalizes any thrown error — DNS failure,
+        // connection reset, timeout abort (whether during headers or body
+        // read), JSON parse failure, schema violation, empty content — into
+        // a `deepseek dispatcher: …` prefixed Error so cron logs are
+        // actionable and consistent with the anthropic path's error shape.
+        try {
+            const res = await doFetch(DEEPSEEK_URL, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${opts.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body,
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            // Always read the body as TEXT first so we can produce a useful
+            // diagnostic on both non-2xx AND malformed-JSON responses
+            // (round-2 F-004: previously `await res.json()` propagated a raw
+            // SyntaxError that masked the actual response body).
+            const rawText = await res.text();
+            if (res.status < 200 || res.status >= 300) {
+                throw new Error(`deepseek dispatcher: HTTP ${res.status} from ${DEEPSEEK_URL}. ` +
+                    `Body (first 200 chars): ${rawText.slice(0, 200)}`);
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(rawText);
+            }
+            catch {
+                throw new Error('deepseek dispatcher: response was not valid JSON. ' +
+                    `Body (first 200 chars): ${rawText.slice(0, 200)}`);
+            }
+            const result = responseSchema.safeParse(parsed);
+            if (!result.success) {
+                throw new Error('deepseek dispatcher: response missing choices[0].message.content. ' +
+                    `Truncated response: ${rawText.slice(0, 200)}`);
+            }
+            const content = result.data.choices[0].message.content;
+            // Round-6 grok finding: an empty-string content satisfies the zod
+            // schema but is useless to the runner's JSON extractor and produces
+            // a confusing downstream parse error. Surface the empty-response
+            // case with a clear message and the truncated body.
+            if (content.trim() === '') {
+                throw new Error('deepseek dispatcher: model returned empty content. ' +
+                    `Truncated response: ${rawText.slice(0, 200)}`);
+            }
+            return content;
+        }
+        catch (err) {
+            // Re-throw our own already-prefixed errors verbatim; wrap everything
+            // else (transport failures, abort errors, etc.) so cron logs see a
+            // consistent "deepseek dispatcher: …" prefix (round-7 grok finding:
+            // the round-6 fix only covered the initial doFetch call, leaving
+            // body-read aborts and stream errors unwrapped).
+            if (err instanceof Error && err.message.startsWith('deepseek dispatcher: '))
+                throw err;
+            // Surface the underlying transport detail. undici's fetch rejects
+            // with `TypeError: fetch failed` and stashes the actionable
+            // ENOTFOUND/ECONNRESET/TLS detail in `err.cause` — without
+            // unwrapping that, cron logs would show the unhelpful
+            // "deepseek dispatcher: fetch failed: fetch failed" (PR #393 MMR
+            // F-002).
+            const reason = describeFetchError(err);
+            throw new Error(`deepseek dispatcher: fetch failed: ${reason}`);
+        }
+    };
+}
+/**
+ * Pull out a useful message from a thrown fetch error. undici wraps
+ * transport-layer failures (DNS, connection reset, TLS) in a
+ * `TypeError: fetch failed` whose `cause` carries the actionable detail
+ * (ENOTFOUND, ECONNRESET, etc.). Without unwrapping `cause`, cron logs
+ * would lose that detail and show only "fetch failed" — useless for
+ * triage. We compose the outer message with the cause's `code` and
+ * `message` when present.
+ */
+function describeFetchError(err) {
+    if (!(err instanceof Error))
+        return String(err);
+    const cause = err.cause;
+    if (cause instanceof Error) {
+        const code = cause.code;
+        const tail = code ? `${code}: ${cause.message}` : cause.message;
+        return `${err.message} (${tail})`;
+    }
+    if (typeof cause === 'string' && cause) {
+        return `${err.message} (${cause})`;
+    }
+    return err.message;
+}
+//# sourceMappingURL=deepseek.js.map

package/dist/knowledge-freshness/providers/deepseek.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepseek.js","sourceRoot":"","sources":["../../../src/knowledge-freshness/providers/deepseek.ts"],"names":[],"mappings":"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"}

package/dist/knowledge-freshness/providers/deepseek.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=deepseek.test.d.ts.map

package/dist/knowledge-freshness/providers/deepseek.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepseek.test.d.ts","sourceRoot":"","sources":["../../../src/knowledge-freshness/providers/deepseek.test.ts"],"names":[],"mappings":""}

package/dist/knowledge-freshness/providers/deepseek.test.js

@@ -0,0 +1,142 @@
+import { describe, it, expect, vi } from 'vitest';
+import { buildDeepseekDispatcher } from './deepseek.js';
+const ok = (body) => new Response(JSON.stringify(body), { status: 200, headers: { 'content-type': 'application/json' } });
+describe('deepseek provider — happy path', () => {
+    it('POSTs to api.deepseek.com/chat/completions with bearer auth and the prompt as user message', async () => {
+        // Keep a separate reference to the raw vi.fn() result BEFORE casting to
+        // DeepseekFetch, so we can read .mock.calls without an `as unknown as`
+        // dive into vitest internals (round-6 grok finding).
+        const rawFetchMock = vi.fn(async () => ok({
+            choices: [{ message: { content: '{"verdict":"current"}' } }],
+        }));
+        const fetchSpy = rawFetchMock;
+        const dispatcher = buildDeepseekDispatcher({
+            apiKey: 'sk-test-key',
+            timeoutSec: 600,
+            fetchImpl: fetchSpy,
+        });
+        const result = await dispatcher('the meta-prompt body');
+        expect(result).toBe('{"verdict":"current"}');
+        // Verify the request shape exactly.
+        expect(rawFetchMock).toHaveBeenCalledWith('https://api.deepseek.com/chat/completions', expect.objectContaining({
+            method: 'POST',
+            headers: expect.objectContaining({
+                'Authorization': 'Bearer sk-test-key',
+                'Content-Type': 'application/json',
+            }),
+            body: expect.any(String),
+        }));
+        // Parse the JSON body to verify the request shape precisely.
+        const sentBody = JSON.parse(rawFetchMock.mock.calls[0][1].body);
+        expect(sentBody).toEqual({
+            model: 'deepseek-v4-flash',
+            messages: [{ role: 'user', content: 'the meta-prompt body' }],
+            // Round-5 F-001: thinking mode is explicitly disabled so temperature: 0
+            // takes effect and the model goes straight to the JSON verdict.
+            thinking: { type: 'disabled' },
+            temperature: 0,
+            max_tokens: 8192,
+            stream: false,
+        });
+    });
+    it('uses the model from KNOWLEDGE_FRESHNESS_DEEPSEEK_MODEL when set (allowlist member)', async () => {
+        const rawFetchMock = vi.fn(async () => ok({
+            choices: [{ message: { content: 'response' } }],
+        }));
+        const fetchSpy = rawFetchMock;
+        const dispatcher = buildDeepseekDispatcher({
+            apiKey: 'k',
+            timeoutSec: 60,
+            model: 'deepseek-v4-pro',
+            fetchImpl: fetchSpy,
+        });
+        await dispatcher('x');
+        expect(JSON.parse(rawFetchMock.mock.calls[0][1].body).model).toBe('deepseek-v4-pro');
+    });
+});
+describe('deepseek provider — error paths', () => {
+    it('throws on non-2xx response with status + truncated body', async () => {
+        const fetchSpy = vi.fn(async () => new Response('{"error":{"message":"rate limited","type":"rate_limit_error"}}', { status: 429 }));
+        const dispatcher = buildDeepseekDispatcher({ apiKey: 'k', timeoutSec: 60, fetchImpl: fetchSpy });
+        await expect(dispatcher('x')).rejects.toThrow(/HTTP 429.*rate limited/i);
+    });
+    it('throws on a 200 response that lacks choices[0].message.content', async () => {
+        const fetchSpy = vi.fn(async () => new Response(JSON.stringify({ choices: [] }), { status: 200 }));
+        const dispatcher = buildDeepseekDispatcher({ apiKey: 'k', timeoutSec: 60, fetchImpl: fetchSpy });
+        await expect(dispatcher('x')).rejects.toThrow(/missing choices\[0\]\.message\.content/i);
+    });
+    it('throws a diagnostic error on a 200 response whose body is not JSON', async () => {
+        // Round-2 F-004: must NOT propagate a bare SyntaxError. The dispatcher
+        // catches the parse failure and throws a message containing the
+        // truncated body so cron logs are actionable.
+        const fetchSpy = vi.fn(async () => new Response('not json at all', {
+            status: 200, headers: { 'content-type': 'application/json' },
+        }));
+        const dispatcher = buildDeepseekDispatcher({ apiKey: 'k', timeoutSec: 60, fetchImpl: fetchSpy });
+        await expect(dispatcher('x')).rejects.toThrow(/response was not valid JSON.*not json at all/i);
+    });
+    it('rejects an unsupported model at construction time (not at fetch time)', () => {
+        expect(() => buildDeepseekDispatcher({
+            apiKey: 'k', timeoutSec: 60, model: 'gpt-4',
+        })).toThrow(/unsupported DeepSeek model "gpt-4".*deepseek-v4-flash.*deepseek-v4-pro/i);
+    });
+    it('rejects construction when apiKey is empty', () => {
+        expect(() => buildDeepseekDispatcher({ apiKey: '', timeoutSec: 60 })).toThrow(/DEEPSEEK_API_KEY is required/);
+    });
+    it('normalizes transport errors (DNS / reset / reject) → deepseek-prefixed message (round-6 grok)', async () => {
+        // The dispatcher must wrap the fetch call so raw undici / DOMException
+        // errors don't leak to the cron logs unstyled. Mock a fetch that
+        // rejects synchronously; assert the wrapped error has the diagnostic
+        // prefix.
+        const fetchSpy = vi.fn(async () => {
+            throw new Error('getaddrinfo ENOTFOUND api.deepseek.com');
+        });
+        const dispatcher = buildDeepseekDispatcher({ apiKey: 'k', timeoutSec: 60, fetchImpl: fetchSpy });
+        await expect(dispatcher('x')).rejects.toThrow(/deepseek dispatcher: fetch failed.*ENOTFOUND/i);
+    });
+    it('unwraps err.cause when undici throws TypeError + cause (PR-393 F-002)', async () => {
+        // undici's actual transport-layer rejection shape: outer
+        // `TypeError: fetch failed` with the actionable code+message in
+        // `err.cause`. Without unwrapping cause, cron logs lose the
+        // ENOTFOUND/ECONNRESET signal we need for triage.
+        const cause = Object.assign(new Error('getaddrinfo ENOTFOUND api.deepseek.com'), {
+            code: 'ENOTFOUND',
+        });
+        const outer = new TypeError('fetch failed');
+        outer.cause = cause;
+        const fetchSpy = vi.fn(async () => { throw outer; });
+        const dispatcher = buildDeepseekDispatcher({ apiKey: 'k', timeoutSec: 60, fetchImpl: fetchSpy });
+        // The wrapped message must contain BOTH the outer "fetch failed" and
+        // the inner ENOTFOUND code, otherwise the cron log entry is useless.
+        await expect(dispatcher('x')).rejects.toThrow(/deepseek dispatcher: fetch failed.*ENOTFOUND.*api\.deepseek\.com/i);
+    });
+    it('normalizes a body-read abort (headers OK, body hangs) → deepseek-prefixed (round-7 grok)', async () => {
+        // The post-fetch phase (res.text(), JSON.parse, zod, content check) must
+        // also be wrapped — a slow server that returns 200 headers fast then
+        // hangs during body read causes the AbortSignal.timeout to fire after
+        // headers but during streaming, and res.text() rejects with a raw
+        // AbortError. The dispatcher's outer catch normalizes that into a
+        // diagnostic message.
+        const fetchSpy = vi.fn(async () => {
+            // Build a Response whose body rejects with a synthetic AbortError on
+            // read, simulating the headers-fast-body-hangs scenario.
+            const body = new ReadableStream({
+                start(controller) {
+                    controller.error(new DOMException('The operation was aborted.', 'AbortError'));
+                },
+            });
+            return new Response(body, { status: 200 });
+        });
+        const dispatcher = buildDeepseekDispatcher({ apiKey: 'k', timeoutSec: 60, fetchImpl: fetchSpy });
+        await expect(dispatcher('x')).rejects.toThrow(/deepseek dispatcher: fetch failed.*[Aa]bort/i);
+    });
+    it('throws a diagnostic error when the model returns empty content (round-6 grok)', async () => {
+        // A 200 response with content === "" satisfies the zod schema but is
+        // useless to the runner's JSON extractor. The dispatcher must surface
+        // it with a clear message rather than handing back an empty string.
+        const fetchSpy = vi.fn(async () => new Response(JSON.stringify({ choices: [{ message: { content: '   ' } }] }), { status: 200 }));
+        const dispatcher = buildDeepseekDispatcher({ apiKey: 'k', timeoutSec: 60, fetchImpl: fetchSpy });
+        await expect(dispatcher('x')).rejects.toThrow(/model returned empty content/i);
+    });
+});
+//# sourceMappingURL=deepseek.test.js.map

package/dist/knowledge-freshness/providers/deepseek.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepseek.test.js","sourceRoot":"","sources":["../../../src/knowledge-freshness/providers/deepseek.test.ts"],"names":[],"mappings":"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"}

package/dist/knowledge-freshness/providers/index.d.ts

@@ -0,0 +1,41 @@
+import type { Dispatcher } from '../audit-runner.js';
+export type Provider = 'anthropic' | 'deepseek';
+export interface ResolveProviderInput {
+    /** Process env. Pass `process.env` in production; inject a stub in tests. */
+    env: Record<string, string | undefined>;
+    /** Parsed CLI args. `provider` is set when the operator passed `--provider`. */
+    args: {
+        provider?: string;
+    };
+    /** Whether the `claude` CLI is available on PATH. Inject in tests. */
+    claudeOnPath: boolean;
+}
+/**
+ * Resolve which LLM provider the audit runner should use.
+ *
+ * Precedence (highest first):
+ *   1. --provider <name>           (explicit flag — operator override)
+ *   2. KNOWLEDGE_FRESHNESS_PROVIDER env var
+ *   3. Single API key in env       (inferred)
+ *   4. Both API keys present       → error (ambiguous)
+ *   5. No env, claude on PATH      → anthropic (subprocess uses keychain)
+ *   6. Nothing                     → error (no provider configured)
+ *
+ * Errors are thrown with operator-facing messages that name the exact env
+ * var or flag the operator should set.
+ */
+export declare function resolveProvider(input: ResolveProviderInput): Provider;
+/**
+ * Construct a Dispatcher for the chosen provider. Each provider's
+ * implementation lives in its own file. This factory is the ONLY place
+ * the audit-run-entry CLI knows about provider differences.
+ */
+export interface BuildDispatcherOptions {
+    /** Per-fetch / per-subprocess timeout in seconds. */
+    timeoutSec: number;
+    /** Process env (production: `process.env`). Used by provider implementations
+     *  for API keys and any optional overrides (e.g. model name). */
+    env: Record<string, string | undefined>;
+}
+export declare function buildDispatcher(provider: Provider, opts: BuildDispatcherOptions): Dispatcher;
+//# sourceMappingURL=index.d.ts.map

package/dist/knowledge-freshness/providers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/knowledge-freshness/providers/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAIpD,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,UAAU,CAAA;AAQ/C,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;IACvC,gFAAgF;IAChF,IAAI,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC3B,sEAAsE;IACtE,YAAY,EAAE,OAAO,CAAA;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,QAAQ,CAqBrE;AAsDD;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAA;IAClB;qEACiE;IACjE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CACxC;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,sBAAsB,GAAG,UAAU,CAsB5F"}

package/dist/knowledge-freshness/providers/index.js

@@ -0,0 +1,108 @@
+import { buildAnthropicDispatcher } from './anthropic.js';
+import { buildDeepseekDispatcher } from './deepseek.js';
+const KNOWN_PROVIDERS = ['anthropic', 'deepseek'];
+function isKnownProvider(s) {
+    return KNOWN_PROVIDERS.includes(s);
+}
+/**
+ * Resolve which LLM provider the audit runner should use.
+ *
+ * Precedence (highest first):
+ *   1. --provider <name>           (explicit flag — operator override)
+ *   2. KNOWLEDGE_FRESHNESS_PROVIDER env var
+ *   3. Single API key in env       (inferred)
+ *   4. Both API keys present       → error (ambiguous)
+ *   5. No env, claude on PATH      → anthropic (subprocess uses keychain)
+ *   6. Nothing                     → error (no provider configured)
+ *
+ * Errors are thrown with operator-facing messages that name the exact env
+ * var or flag the operator should set.
+ */
+export function resolveProvider(input) {
+    const choice = pickProviderFromRules(input);
+    // Post-resolution runtime validation: ANY path that ends in 'anthropic'
+    // requires the `claude` CLI on PATH because the dispatcher shells out.
+    // This check covers BOTH inferred (rule-3b) and explicit (rule-1 flag,
+    // rule-2 env) paths so an operator can't pick anthropic via flag/env and
+    // then get a confusing command-not-found at first audit (round-4 F-001
+    // of the plan review).
+    if (choice === 'anthropic' && !input.claudeOnPath) {
+        throw new Error('anthropic provider selected but the `claude` CLI is not on PATH. ' +
+            'The dispatcher invokes `claude -p` as a subprocess, so the CLI is ' +
+            'required regardless of how the provider was chosen (--provider flag, ' +
+            'KNOWLEDGE_FRESHNESS_PROVIDER env, or ANTHROPIC_API_KEY inference). ' +
+            'Install Claude Code (`brew install anthropic/claude-code/claude-code` ' +
+            'or `npm install -g @anthropic-ai/claude-code`), OR switch to the ' +
+            'deepseek provider (export DEEPSEEK_API_KEY and set ' +
+            'KNOWLEDGE_FRESHNESS_PROVIDER=deepseek).');
+    }
+    return choice;
+}
+/**
+ * Apply rules 1-6 to pick a Provider — does NOT enforce runtime
+ * preconditions (claudeOnPath for anthropic). The wrapper above is the
+ * single place where those preconditions are validated, so we only have
+ * to maintain that invariant in one location.
+ */
+function pickProviderFromRules(input) {
+    // Rule 1: explicit flag wins.
+    if (input.args.provider) {
+        if (!isKnownProvider(input.args.provider)) {
+            throw new Error(`unknown provider "${input.args.provider}" passed to --provider. ` +
+                `Supported values: ${KNOWN_PROVIDERS.join(', ')}.`);
+        }
+        return input.args.provider;
+    }
+    // Rule 2: env var.
+    const envChoice = input.env['KNOWLEDGE_FRESHNESS_PROVIDER'];
+    if (envChoice) {
+        if (!isKnownProvider(envChoice)) {
+            throw new Error(`unknown provider "${envChoice}" set in KNOWLEDGE_FRESHNESS_PROVIDER. ` +
+                `Supported values: ${KNOWN_PROVIDERS.join(', ')}.`);
+        }
+        return envChoice;
+    }
+    // Rules 3/4: infer from API keys.
+    const hasAnthropic = !!input.env['ANTHROPIC_API_KEY'];
+    const hasDeepseek = !!input.env['DEEPSEEK_API_KEY'];
+    if (hasAnthropic && hasDeepseek) {
+        throw new Error('provider selection ambiguous: both ANTHROPIC_API_KEY and DEEPSEEK_API_KEY are set. ' +
+            'Set KNOWLEDGE_FRESHNESS_PROVIDER=anthropic|deepseek (or pass --provider) to disambiguate.');
+    }
+    if (hasDeepseek)
+        return 'deepseek';
+    if (hasAnthropic)
+        return 'anthropic';
+    // Rule 5: PATH probe (no env vars set, but Claude Code is installed and
+    // already authenticated via `claude /login`).
+    if (input.claudeOnPath)
+        return 'anthropic';
+    // Rule 6: nothing.
+    throw new Error('no provider configured for the knowledge-freshness audit. Either:\n' +
+        '  - install Claude Code and run `claude /login` (anthropic provider), OR\n' +
+        '  - export ANTHROPIC_API_KEY AND have `claude` on PATH (anthropic, env-var auth), OR\n' +
+        '  - export DEEPSEEK_API_KEY (deepseek provider, no CLI install needed).\n' +
+        'See docs/knowledge-freshness/operations.md §4 for details.');
+}
+export function buildDispatcher(provider, opts) {
+    if (provider === 'anthropic') {
+        return buildAnthropicDispatcher({ timeoutSec: opts.timeoutSec });
+    }
+    if (provider === 'deepseek') {
+        const apiKey = opts.env['DEEPSEEK_API_KEY'];
+        if (!apiKey) {
+            throw new Error('deepseek provider selected but DEEPSEEK_API_KEY env var is not set. ' +
+                'Either export the key or pick a different provider via --provider / ' +
+                'KNOWLEDGE_FRESHNESS_PROVIDER.');
+        }
+        const modelOverride = opts.env['KNOWLEDGE_FRESHNESS_DEEPSEEK_MODEL'];
+        return buildDeepseekDispatcher({
+            apiKey,
+            timeoutSec: opts.timeoutSec,
+            model: modelOverride,
+        });
+    }
+    // Unreachable: the type narrowing above is exhaustive.
+    throw new Error(`unknown provider ${provider}`);
+}
+//# sourceMappingURL=index.js.map

package/dist/knowledge-freshness/providers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/knowledge-freshness/providers/index.ts"],"names":[],"mappings":"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"}

package/dist/knowledge-freshness/providers/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/dist/knowledge-freshness/providers/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../../../src/knowledge-freshness/providers/index.test.ts"],"names":[],"mappings":""}

package/dist/knowledge-freshness/providers/index.test.js

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'vitest';
+import { resolveProvider, buildDispatcher } from './index.js';
+// `claudeOnPath` is injected so tests don't depend on the host's $PATH.
+// We type `env` as `Record<string, string | undefined>` directly rather
+// than via a narrow named `interface` — round-3 F-003 of the plan review:
+// a narrow interface lacks an index signature and won't satisfy the
+// `Record<string, string | undefined>` parameter of `resolveProvider` in
+// strict mode.
+const opts = (env, args = {}, claudeOnPath = false) => ({ env, args, claudeOnPath });
+describe('resolveProvider', () => {
+    it('rule 1: --provider flag wins over everything', () => {
+        const env = { ANTHROPIC_API_KEY: 'a', DEEPSEEK_API_KEY: 'd', KNOWLEDGE_FRESHNESS_PROVIDER: 'anthropic' };
+        // deepseek skips the PATH check entirely so claudeOnPath defaults to false here.
+        expect(resolveProvider(opts(env, { provider: 'deepseek' }))).toBe('deepseek');
+        // anthropic requires `claude` on PATH (round-4 F-001). The flag wins over env/keys,
+        // but the post-resolution PATH precondition still applies, so pass claudeOnPath=true.
+        expect(resolveProvider(opts(env, { provider: 'anthropic' }, true))).toBe('anthropic');
+    });
+    it('rule 2: KNOWLEDGE_FRESHNESS_PROVIDER env var when no flag', () => {
+        const env = { ANTHROPIC_API_KEY: 'a', DEEPSEEK_API_KEY: 'd', KNOWLEDGE_FRESHNESS_PROVIDER: 'deepseek' };
+        expect(resolveProvider(opts(env))).toBe('deepseek');
+    });
+    it('rule 3a: only DEEPSEEK_API_KEY set → deepseek', () => {
+        expect(resolveProvider(opts({ DEEPSEEK_API_KEY: 'd' }))).toBe('deepseek');
+    });
+    it('rule 3b: ANTHROPIC_API_KEY set AND claude on PATH → anthropic', () => {
+        expect(resolveProvider(opts({ ANTHROPIC_API_KEY: 'a' }, {}, true))).toBe('anthropic');
+    });
+    it('rule 3b error: ANTHROPIC_API_KEY set but claude NOT on PATH → error', () => {
+        // Round-3 F-001: the env var alone is insufficient because the
+        // anthropic dispatcher shells out to `claude -p`. Surface this at
+        // resolveProvider time, not at first audit dispatch.
+        const call = () => resolveProvider(opts({ ANTHROPIC_API_KEY: 'a' }, {}, false));
+        expect(call).toThrow(/`claude` CLI is not on PATH/);
+    });
+    it('rule-1 error: --provider anthropic but claude NOT on PATH → error', () => {
+        // Round-4 F-001: the post-resolution PATH check covers EVERY anthropic
+        // selection path, not just the inferred-from-env one. An operator who
+        // explicitly forces --provider anthropic on a machine without Claude
+        // Code installed gets a clear early error instead of command-not-found
+        // at first audit.
+        const call = () => resolveProvider(opts({}, { provider: 'anthropic' }, false));
+        expect(call).toThrow(/`claude` CLI is not on PATH/);
+    });
+    it('rule-2 error: KNOWLEDGE_FRESHNESS_PROVIDER=anthropic but claude NOT on PATH → error', () => {
+        // Same protection on the env-var path.
+        const call = () => resolveProvider(opts({ KNOWLEDGE_FRESHNESS_PROVIDER: 'anthropic' }, {}, false));
+        expect(call).toThrow(/`claude` CLI is not on PATH/);
+    });
+    it('rule-1 explicit deepseek skips the PATH check entirely', () => {
+        // Sanity check: the PATH precondition is anthropic-only. deepseek
+        // doesn't need a CLI.
+        expect(resolveProvider(opts({ DEEPSEEK_API_KEY: 'd' }, { provider: 'deepseek' }, false))).toBe('deepseek');
+    });
+    it('rule 4: both keys set without explicit choice → error with helpful message', () => {
+        // The thrown message can list the env-var and the --provider flag in
+        // either order — assert each substring independently so a wording
+        // change to the message doesn't break the test.
+        const call = () => resolveProvider(opts({ ANTHROPIC_API_KEY: 'a', DEEPSEEK_API_KEY: 'd' }));
+        expect(call).toThrow(/ambiguous/i);
+        expect(call).toThrow(/KNOWLEDGE_FRESHNESS_PROVIDER/);
+        expect(call).toThrow(/--provider/);
+    });
+    it('rule 5: no env vars but claude on PATH → anthropic (keychain delegation)', () => {
+        expect(resolveProvider(opts({}, {}, true))).toBe('anthropic');
+    });
+    it('rule 6: no env vars and no claude on PATH → error with setup instructions', () => {
+        // The setup-instructions message spans multiple lines — use [\s\S]* so
+        // the match crosses newlines, and assert each key substring independently
+        // since they appear in human-readable order (ANTHROPIC then DEEPSEEK).
+        const call = () => resolveProvider(opts({}, {}, false));
+        expect(call).toThrow(/no provider configured/i);
+        expect(call).toThrow(/ANTHROPIC_API_KEY/);
+        expect(call).toThrow(/DEEPSEEK_API_KEY/);
+    });
+    it('rejects an invalid --provider flag value', () => {
+        expect(() => resolveProvider(opts({}, { provider: 'openai' }, true)))
+            .toThrow(/unknown provider "openai"/i);
+    });
+    it('rejects an invalid KNOWLEDGE_FRESHNESS_PROVIDER env value', () => {
+        expect(() => resolveProvider(opts({ KNOWLEDGE_FRESHNESS_PROVIDER: 'gemini' }, {}, true)))
+            .toThrow(/unknown provider "gemini"/i);
+    });
+});
+describe('buildDispatcher — deepseek wiring', () => {
+    it('throws when deepseek is selected but DEEPSEEK_API_KEY is not in env', () => {
+        expect(() => buildDispatcher('deepseek', { timeoutSec: 60, env: {} }))
+            .toThrow(/DEEPSEEK_API_KEY env var is not set/);
+    });
+    it('constructs a Dispatcher when DEEPSEEK_API_KEY is set', () => {
+        // We don't call the dispatcher (no fetch mock here) — just verify
+        // construction succeeds.
+        const d = buildDispatcher('deepseek', { timeoutSec: 60, env: { DEEPSEEK_API_KEY: 'sk-x' } });
+        expect(typeof d).toBe('function');
+    });
+});
+//# sourceMappingURL=index.test.js.map

package/dist/knowledge-freshness/providers/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../../../src/knowledge-freshness/providers/index.test.ts"],"names":[],"mappings":"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"}