7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.
TypeScript
feat(cli): freellmapi doctor — prove a client's requests reach this gateway (#862)
OhOkThisIsFine1129fc4a214b
diff --git a/cli/package.json b/cli/package.jsonindex 17afcb58..a8ae7a2b 100644--- a/cli/package.json+++ b/cli/package.json@@ -38,6 +38,8 @@"dist/index.d.ts","dist/config-files.js","dist/config-files.d.ts",+ "dist/doctor.js",+ "dist/doctor.d.ts","dist/models.js","dist/models.d.ts","dist/tools.js",diff --git a/cli/src/doctor.test.ts b/cli/src/doctor.test.tsnew file mode 100644index 00000000..278d95fb--- /dev/null+++ b/cli/src/doctor.test.ts@@ -0,0 +1,393 @@+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import { afterEach, describe, expect, it } from 'vitest';+import {+ DEFAULT_PROBE_TIMEOUT_MS,+ claudeLayers,+ codexLayers,+ diagnose,+ exitCodeFor,+ managedSettingsDir,+ managedSettingsPaths,+ normalizeUrl,+ probeGateway,+ sameGateway,+} from './doctor.js';++const temporary: string[] = [];+function tempHome(): string {+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'freellmapi-doctor-'));+ temporary.push(dir);+ return dir;+}+afterEach(() => {+ for (const dir of temporary.splice(0)) fs.rmSync(dir, { recursive: true, force: true });+});++/** A fetch double that answers /livez exactly as the real gateway does. */+function gatewayFetch(+ body: unknown = { status: 'ok', version: '0.7.0', uptime_s: 12 },+ status = 200,+): typeof fetch {+ return (async () => ({ status, json: async () => body })) as unknown as typeof fetch;+}++/** The real 503 body from routes/status.ts when the db or encryption key is down. */+const UNAVAILABLE = { status: 'unavailable', version: '0.7.0', uptime_s: 12, checks: { db: false } };+const deadFetch = (async () => { throw new Error('ECONNREFUSED'); }) as unknown as typeof fetch;++function writeClaudeSettings(home: string, value: Record<string, unknown>): void {+ const dir = path.join(home, '.claude');+ fs.mkdirSync(dir, { recursive: true });+ fs.writeFileSync(path.join(dir, 'settings.json'), JSON.stringify(value));+}++function writeCodexConfig(home: string, toml: string): void {+ const dir = path.join(home, '.codex');+ fs.mkdirSync(dir, { recursive: true });+ fs.writeFileSync(path.join(dir, 'config.toml'), toml);+}++describe('managed settings locations', () => {+ it('uses the documented system directory for each platform', () => {+ expect(managedSettingsDir('darwin')).toBe('/Library/Application Support/ClaudeCode');+ expect(managedSettingsDir('linux')).toBe('/etc/claude-code');+ expect(managedSettingsDir('win32')).toBe('C:\\Program Files\\ClaudeCode');+ });++ it('falls back to the base file alone when there is no drop-in directory', () => {+ // The usual case: an unreadable or absent managed-settings.d contributes+ // nothing rather than failing the whole report.+ const dir = tempHome();+ expect(managedSettingsPaths('linux', dir)).toEqual([path.join(dir, 'managed-settings.json')]);+ });++ it('ranks managed-settings.d drop-ins above the base file, last one first', () => {+ // The drop-in files are merged alphabetically ON TOP of the base, so the+ // alphabetically LAST one wins and the base loses to all of them. Getting+ // this order backwards would name the wrong layer as effective for a+ // fleet-managed install — the exact confident-wrong answer doctor exists+ // to prevent.+ const dir = tempHome();+ fs.mkdirSync(path.join(dir, 'managed-settings.d'));+ for (const name of ['20-b.json', '10-a.json', 'notes.txt']) {+ fs.writeFileSync(path.join(dir, 'managed-settings.d', name), '{}');+ }++ expect(managedSettingsPaths('linux', dir)).toEqual([+ path.join(dir, 'managed-settings.d', '20-b.json'),+ path.join(dir, 'managed-settings.d', '10-a.json'),+ path.join(dir, 'managed-settings.json'),+ ]);+ });+});++describe('url comparison', () => {+ it('ignores trailing slashes, a /v1 suffix, and host case', () => {+ expect(normalizeUrl('http://Localhost:3000/v1/')).toBe('http://localhost:3000');+ expect(sameGateway('http://localhost:3000', 'http://localhost:3000/v1')).toBe(true);+ expect(sameGateway('http://localhost:3000', 'http://localhost:3001')).toBe(false);+ expect(sameGateway(undefined, 'http://localhost:3000')).toBe(false);+ });++ it('keeps a path prefix, so two mounts on one host are not confused', () => {+ // A gateway mounted under a prefix is a different endpoint. Folding the+ // path away reported these as the same gateway.+ expect(normalizeUrl('http://host/gateway/v1/')).toBe('http://host/gateway');+ expect(sameGateway('http://host/gateway', 'http://host/other')).toBe(false);+ expect(sameGateway('http://host/gateway/v1', 'http://host/gateway/')).toBe(true);+ expect(sameGateway('http://host/gateway', 'http://host')).toBe(false);+ });++ it('keeps path case, which is case-sensitive, while folding the host', () => {+ expect(normalizeUrl('HTTP://Host:3000/Gateway')).toBe('http://host:3000/Gateway');+ expect(sameGateway('http://host/Gateway', 'http://host/gateway')).toBe(false);+ });++ it('drops query and fragment, which never identify the endpoint', () => {+ expect(normalizeUrl('http://host:3000/v1?k=1#x')).toBe('http://host:3000');+ });++ it('falls back to lexical trimming for an unparseable value', () => {+ // A malformed config value must still produce a report, not an exception.+ expect(normalizeUrl('localhost:3000/v1/')).toBe('localhost:3000');+ });+});++describe('claude precedence', () => {+ it('ranks a settings env block ABOVE the inherited shell environment', () => {+ // The easy thing to get backwards, and I did: Claude Code writes each+ // `env` entry into the process environment at startup, REPLACING what the+ // shell exported. The shell is the lowest layer, not the highest.+ const home = tempHome();+ writeClaudeSettings(home, { env: { ANTHROPIC_BASE_URL: 'http://localhost:3000' } });+ const layers = claudeLayers({ ANTHROPIC_BASE_URL: 'https://api.anthropic.com' }, home, tempHome());++ expect(layers[0]).toMatchObject({ value: 'http://localhost:3000', effective: true });+ expect(layers[1]).toMatchObject({ value: 'https://api.anthropic.com', effective: false });+ });++ it('uses the shell value when no settings file names one', () => {+ expect(claudeLayers({ ANTHROPIC_BASE_URL: 'http://localhost:3000' }, tempHome(), tempHome())[0])+ .toMatchObject({ value: 'http://localhost:3000', effective: true });+ });++ it('ranks project-local settings above the user scope', () => {+ const home = tempHome();+ const project = tempHome();+ writeClaudeSettings(home, { env: { ANTHROPIC_BASE_URL: 'http://user:1' } });+ fs.mkdirSync(path.join(project, '.claude'), { recursive: true });+ fs.writeFileSync(+ path.join(project, '.claude', 'settings.local.json'),+ JSON.stringify({ env: { ANTHROPIC_BASE_URL: 'http://project-local:2' } }),+ );++ expect(claudeLayers({}, home, project)[0])+ .toMatchObject({ value: 'http://project-local:2', effective: true });+ });++ it('honours CLAUDE_CONFIG_DIR for the user scope', () => {+ // Relocates the user scope wholesale; missing it reads a settings file the+ // running tool never opens.+ const home = tempHome();+ const configDir = tempHome();+ writeClaudeSettings(home, { env: { ANTHROPIC_BASE_URL: 'http://ignored:1' } });+ fs.writeFileSync(+ path.join(configDir, 'settings.json'),+ JSON.stringify({ env: { ANTHROPIC_BASE_URL: 'http://relocated:2' } }),+ );++ expect(claudeLayers({ CLAUDE_CONFIG_DIR: configDir }, home, tempHome())[0]?.value)+ .toBe('http://relocated:2');+ });++ it('reports no layers rather than throwing on absent or malformed settings', () => {+ const home = tempHome();+ expect(claudeLayers({}, home, tempHome())).toEqual([]);+ fs.mkdirSync(path.join(home, '.claude'), { recursive: true });+ fs.writeFileSync(path.join(home, '.claude', 'settings.json'), '{ not json');+ expect(claudeLayers({}, home, tempHome())).toEqual([]);+ });+});++describe('codex precedence', () => {+ it('resolves the SELECTED provider, not the first base_url in the file', () => {+ // Codex names a provider and the provider carries the url. Reading any+ // base_url would report a provider the user is not selecting.+ const home = tempHome();+ writeCodexConfig(home, [+ 'model_provider = "freellmapi"',+ '',+ '[model_providers.other]',+ 'base_url = "http://not-this-one:9999/v1"',+ '',+ '[model_providers.freellmapi]',+ 'base_url = "http://localhost:3000/v1"',+ ].join('\n'));++ expect(codexLayers({}, home)[0]).toMatchObject({+ value: 'http://localhost:3000/v1',+ effective: true,+ });+ });++ it('reads the dotted-key spelling too', () => {+ const home = tempHome();+ writeCodexConfig(home, [+ 'model_provider = "freellmapi"',+ 'model_providers.freellmapi.base_url = "http://localhost:3000/v1"',+ ].join('\n'));+ expect(codexLayers({}, home)[0]?.value).toBe('http://localhost:3000/v1');+ });++ it('honours CODEX_HOME over the default location', () => {+ const home = tempHome();+ const alternate = tempHome();+ writeCodexConfig(home, 'model_provider = "a"\n[model_providers.a]\nbase_url = "http://default:1/v1"');+ writeCodexConfig(alternate, 'model_provider = "b"\n[model_providers.b]\nbase_url = "http://override:2/v1"');++ const layers = codexLayers({ CODEX_HOME: path.join(alternate, '.codex') }, home);+ expect(layers[0]?.value).toBe('http://override:2/v1');+ });++ it('records a selected provider that names no base_url instead of skipping it', () => {+ const home = tempHome();+ writeCodexConfig(home, 'model_provider = "freellmapi"\n');+ const layer = codexLayers({}, home)[0];+ expect(layer.effective).toBe(true);+ expect(layer.value).toBeUndefined();+ expect(layer.source).toContain('no base_url found');+ });+});++describe('verdicts', () => {+ const url = 'http://localhost:3000';++ it('routed only when the tool reaches THIS gateway', async () => {+ const report = await diagnose('claude', {+ expectedUrl: url,+ env: { ANTHROPIC_BASE_URL: url },+ homeDir: tempHome(), cwd: tempHome(),+ fetchImpl: gatewayFetch(),+ });+ expect(report.verdict).toBe('routed');+ expect(report.gateway?.version).toBe('0.7.0');+ });++ it('elsewhere — not routed — when the tool reaches a different host that is alive', async () => {+ // The regression this guards: reporting `routed` for a Claude Code pinned+ // to api.anthropic.com, because it does reach what it is configured to+ // reach. That is a confident wrong answer to the question being asked.+ const report = await diagnose('claude', {+ expectedUrl: url,+ env: { ANTHROPIC_BASE_URL: 'https://api.anthropic.com' },+ homeDir: tempHome(), cwd: tempHome(),+ fetchImpl: gatewayFetch(),+ });+ expect(report.verdict).toBe('elsewhere');+ expect(report.detail).toContain('does not touch this gateway');+ });++ it('elsewhere when the right port answers, but not the way this gateway does', async () => {+ const report = await diagnose('claude', {+ expectedUrl: url,+ env: { ANTHROPIC_BASE_URL: url },+ homeDir: tempHome(), cwd: tempHome(),+ fetchImpl: gatewayFetch({ hello: 'some other service' }),+ });+ expect(report.verdict).toBe('elsewhere');+ });++ it('shadowed names the layer that wins, and the value it beat', async () => {+ const home = tempHome();+ writeClaudeSettings(home, { env: { ANTHROPIC_BASE_URL: url } });+ const report = await diagnose('claude', {+ expectedUrl: url,+ env: { ANTHROPIC_BASE_URL: 'https://api.anthropic.com' },+ homeDir: home, cwd: tempHome(),+ fetchImpl: gatewayFetch(),+ });++ expect(report.verdict).toBe('shadowed');+ // The settings block is what wins, so it is what shadows — and the shell+ // export the user probably set by hand is what got overridden.+ expect(report.shadowedBy).toContain('settings.json');+ expect(report.detail).toContain('process environment');+ expect(report.detail).toContain('https://api.anthropic.com');+ });++ it('degraded — not routed, not elsewhere — when this gateway says it cannot serve', async () => {+ // Routing is correct and the gateway is unmistakably this one; it is sick.+ // `routed` would send the user hunting through config that is already+ // right, and `elsewhere` would blame a service that is not there.+ const report = await diagnose('claude', {+ expectedUrl: url,+ env: { ANTHROPIC_BASE_URL: url },+ homeDir: tempHome(), cwd: tempHome(),+ fetchImpl: gatewayFetch(UNAVAILABLE, 503),+ });+ expect(report.verdict).toBe('degraded');+ expect(report.detail).toContain('that IS this gateway');+ expect(report.detail).toContain('unavailable');+ expect(report.gateway).toMatchObject({ identified: true, healthy: false });+ });++ it('unreachable when the configured endpoint answers nothing', async () => {+ const report = await diagnose('claude', {+ expectedUrl: url,+ env: { ANTHROPIC_BASE_URL: url },+ homeDir: tempHome(), cwd: tempHome(),+ fetchImpl: deadFetch,+ });+ expect(report.verdict).toBe('unreachable');+ expect(report.detail).toContain('ECONNREFUSED');+ });++ it('unknown when nothing configures the tool at all', async () => {+ const report = await diagnose('claude', {+ expectedUrl: url,+ env: {},+ homeDir: tempHome(), cwd: tempHome(),+ fetchImpl: gatewayFetch(),+ });+ expect(report.verdict).toBe('unknown');+ expect(report.detail).toContain('vendor default');+ });++ it('unknown, not a crash, for a tool doctor does not model', async () => {+ const report = await diagnose('aider', { expectedUrl: url, env: {}, homeDir: tempHome() });+ expect(report.verdict).toBe('unknown');+ expect(report.detail).toContain('claude');+ });+});++describe('probeGateway', () => {+ it('requires all three /livez fields before claiming identity', async () => {+ // /livez carries no product marker, so the shape is the only evidence+ // available. Two of three fields is not it.+ expect((await probeGateway('http://x', gatewayFetch({ status: 'ok', version: '1' }))).identified)+ .toBe(false);+ expect((await probeGateway('http://x', gatewayFetch())).identified).toBe(true);+ });++ it('treats a non-JSON body as reachable but unidentified', async () => {+ const htmlFetch = (async () => ({+ status: 200,+ json: async () => { throw new Error('not json'); },+ })) as unknown as typeof fetch;+ expect(await probeGateway('http://x', htmlFetch))+ .toMatchObject({ reachable: true, identified: false, healthy: false });+ });++ it('still IDENTIFIES the gateway when it answers 503 unavailable', async () => {+ // The server really emits this when the db or encryption key is down, and+ // it is unmistakably this gateway. Folding health into identity would+ // report a correctly-routed sick gateway as a foreign service.+ expect(await probeGateway('http://x', gatewayFetch(UNAVAILABLE, 503))).toMatchObject({+ reachable: true,+ identified: true,+ healthy: false,+ serviceStatus: 'unavailable',+ status: 503,+ });+ });++ it('treats an unrecognized status value as unhealthy, not unidentified', async () => {+ // A status added later must degrade into a truthful "this gateway says+ // <status>", never into a claim that it is some other service.+ const probe = await probeGateway(+ 'http://x',+ gatewayFetch({ status: 'draining', version: '9', uptime_s: 1 }),+ );+ expect(probe).toMatchObject({ identified: true, healthy: false, serviceStatus: 'draining' });+ });++ it('is unhealthy when a non-2xx carries an ok body', async () => {+ expect((await probeGateway('http://x', gatewayFetch(undefined, 500))).healthy).toBe(false);+ });++ it('honours the caller-supplied timeout instead of the hard-coded default', async () => {+ // Threaded so a slow link is not misreported as unreachable. That the+ // caller's 20ms fires at all is the proof: the 5s default would not have.+ const neverAnswers = (async (_url: string, init: RequestInit) => new Promise((_resolve, reject) => {+ init.signal?.addEventListener('abort', () => reject(new Error('The operation was aborted')));+ })) as unknown as typeof fetch;++ const started = Date.now();+ const probe = await probeGateway('http://x', neverAnswers, 20);+ expect(Date.now() - started).toBeLessThan(DEFAULT_PROBE_TIMEOUT_MS);+ expect(probe).toMatchObject({ reachable: false, identified: false, healthy: false });+ expect(probe.error).toContain('abort');+ });+});++describe('exit code', () => {+ it('is zero only when every tool is routed', () => {+ expect(exitCodeFor([{ verdict: 'routed' } as never])).toBe(0);+ expect(exitCodeFor([{ verdict: 'routed' } as never, { verdict: 'elsewhere' } as never])).toBe(1);+ expect(exitCodeFor([{ verdict: 'unknown' } as never])).toBe(1);+ // A gateway that cannot serve is a failed precondition, not a pass.+ expect(exitCodeFor([{ verdict: 'degraded' } as never])).toBe(1);+ });+});diff --git a/cli/src/doctor.ts b/cli/src/doctor.tsnew file mode 100644index 00000000..e19b1e3f--- /dev/null+++ b/cli/src/doctor.ts@@ -0,0 +1,508 @@+// `freellmapi doctor` — does this tool's traffic actually reach this gateway?+//+// The load-bearing constraint: the verdict must be computed in a process that+// INHERITS THE USER'S SESSION ENVIRONMENT. The server cannot answer this+// question, because the failure being diagnosed is a request that never+// arrives — there is nothing in any server-side log to look at. So the check+// resolves each tool's effective connection the way that tool resolves it, in+// this process, and only then asks the gateway whether it is alive.+//+// The motivating failure is real and silent: a launcher that sets+// ANTHROPIC_BASE_URL into the process environment overrides the `env` block of+// ~/.claude/settings.json, so a user who edited settings.json is routed+// somewhere else entirely and nothing says so.++import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';++// 'elsewhere' is not decoration. Without it the first real run of this command+// reported `OK claude: routed` for a Claude Code pinned to api.anthropic.com —+// technically "it reaches what it is configured to reach", and precisely the+// confident-wrong answer the command exists to prevent. `routed` now means+// "reaches THIS gateway", which is the only question the user is asking.+export type Verdict = 'routed' | 'degraded' | 'elsewhere' | 'shadowed' | 'unreachable' | 'unknown';++export interface Layer {+ /** Where the value came from, in the tool's own vocabulary. */+ source: string;+ value?: string;+ /** True for the layer whose value the tool will actually use. */+ effective: boolean;+}++export interface ToolReport {+ tool: string;+ verdict: Verdict;+ /** Every layer that set a value, highest precedence first. */+ layers: Layer[];+ /** The base URL the tool will really use, if one could be determined. */+ effectiveUrl?: string;+ /** For 'shadowed': the layer that beat the one the user probably edited. */+ shadowedBy?: string;+ /** Gateway identity, when the effective URL was probed. */+ gateway?: GatewayProbe;+ detail: string;+}++export interface GatewayProbe {+ reachable: boolean;+ /** Whether the response looks like this product. See probeGateway. */+ identified: boolean;+ /** Whether the gateway says it can actually serve requests right now. */+ healthy: boolean;+ /** The `status` field verbatim: 'ok', 'unavailable', or anything added later. */+ serviceStatus?: string;+ version?: string;+ /** HTTP status of the /livez response. */+ status?: number;+ error?: string;+}++/**+ * Normalize for comparison: scheme + host + port + path prefix, with any+ * trailing slash and `/v1` suffix removed.+ *+ * The path is KEPT, and kept case-sensitively. A gateway mounted under a prefix+ * (`http://host/gateway`) is a different endpoint from `http://host/other`, and+ * folding the path away would report the two as the same gateway. Only the+ * scheme and host are case-folded, because only those are case-insensitive.+ * Query and fragment are dropped: they never identify the endpoint.+ *+ * The result is also what the probe is built on, so it must stay a usable URL.+ */+export function normalizeUrl(url: string): string {+ const trimmed = url.trim();+ const lexical = (): string => trimmed.replace(/\/+$/, '').replace(/\/v1$/i, '').toLowerCase();+ let parsed: URL;+ try {+ parsed = new URL(trimmed);+ } catch {+ // Not parseable at all — fall back to lexical trimming rather than+ // throwing, so a malformed config value still yields a report.+ return lexical();+ }+ // A scheme-less value like `localhost:3000/v1` PARSES, as the opaque path+ // `3000/v1` under a `localhost:` scheme, and rebuilding it from parts would+ // produce nonsense. An empty host is the tell.+ if (!parsed.host) return lexical();+ const prefix = parsed.pathname.replace(/\/+$/, '').replace(/\/v1$/i, '');+ return `${parsed.protocol.toLowerCase()}//${parsed.host.toLowerCase()}${prefix}`;+}++export function sameGateway(a: string | undefined, b: string | undefined): boolean {+ if (!a || !b) return false;+ return normalizeUrl(a) === normalizeUrl(b);+}++function readJsonIfPresent(file: string): Record<string, unknown> | undefined {+ try {+ if (!fs.existsSync(file)) return undefined;+ // Claude Code's settings.json is strict JSON, not JSONC.+ return JSON.parse(fs.readFileSync(file, 'utf8')) as Record<string, unknown>;+ } catch {+ return undefined;+ }+}++/** The system directory holding Claude Code's MANAGED settings — the scope+ * nothing else can override. */+export function managedSettingsDir(platform: string = process.platform): string {+ if (platform === 'win32') return 'C:\\Program Files\\ClaudeCode';+ if (platform === 'darwin') return '/Library/Application Support/ClaudeCode';+ return '/etc/claude-code';+}++/**+ * Managed settings files, HIGHEST PRECEDENCE FIRST.+ *+ * Not one file. The same directory also supports a `managed-settings.d/`+ * drop-in, whose `*.json` files are merged alphabetically ON TOP of the base+ * `managed-settings.json` — so a drop-in outranks the base, and the+ * alphabetically LAST drop-in outranks the ones before it. Reading only the+ * base file is how this command would confidently name the wrong effective+ * URL for exactly the fleet-managed install most likely to have one imposed:+ * it would report the layer the operator can see and miss the one actually+ * winning.+ *+ * An unreadable directory (the usual case — it does not exist) contributes+ * nothing rather than failing the report.+ */+export function managedSettingsPaths(+ platform: string = process.platform,+ dir: string = managedSettingsDir(platform),+): string[] {+ const separator = platform === 'win32' ? '\\' : '/';+ const dropInDir = `${dir}${separator}managed-settings.d`;+ let dropIns: string[] = [];+ try {+ dropIns = fs.readdirSync(dropInDir)+ .filter(name => name.endsWith('.json'))+ .sort()+ .reverse() // alphabetically last is merged last, so it wins+ .map(name => `${dropInDir}${separator}${name}`);+ } catch {+ dropIns = [];+ }+ return [...dropIns, `${dir}${separator}managed-settings.json`];+}++/** ANTHROPIC_BASE_URL out of a settings file's `env` block. */+function envBlockUrl(file: string): string | undefined {+ const block = readJsonIfPresent(file)?.env;+ if (!block || typeof block !== 'object' || Array.isArray(block)) return undefined;+ const value = (block as Record<string, unknown>).ANTHROPIC_BASE_URL;+ return typeof value === 'string' && value ? value : undefined;+}++/**+ * Claude Code's base-URL layers, HIGHEST PRECEDENCE FIRST.+ *+ * The ordering that matters, and the one it is easy to get backwards: a+ * settings file's `env` block BEATS the inherited shell environment. Claude+ * Code writes each `env` entry into the process environment at startup and+ * again when the file changes, replacing what the shell exported. So the+ * process environment is the LOWEST layer here, not the highest.+ *+ * The familiar "my launcher overrode my settings.json" case is not a+ * counter-example: a launcher that wins is writing MANAGED settings, which+ * outrank every other scope — note that the rest of that same `env` block+ * still applies, which is what makes the override so hard to see by reading+ * config alone.+ */+export function claudeLayers(+ env: NodeJS.ProcessEnv,+ homeDir: string,+ cwd: string = process.cwd(),+ platform: string = process.platform,+): Layer[] {+ const layers: Layer[] = [];++ for (const managed of managedSettingsPaths(platform)) {+ const value = envBlockUrl(managed);+ if (value) layers.push({ source: `${managed} (MANAGED env block)`, value, effective: false });+ }++ for (const file of [+ path.join(cwd, '.claude', 'settings.local.json'),+ path.join(cwd, '.claude', 'settings.json'),+ // CLAUDE_CONFIG_DIR relocates the user scope wholesale; missing it reads+ // a settings file the running tool never opens.+ path.join(env.CLAUDE_CONFIG_DIR ?? path.join(homeDir, '.claude'), 'settings.json'),+ ]) {+ const value = envBlockUrl(file);+ if (value) layers.push({ source: `${file} (env block)`, value, effective: false });+ }++ if (env.ANTHROPIC_BASE_URL) {+ layers.push({+ source: 'ANTHROPIC_BASE_URL (process environment)',+ value: env.ANTHROPIC_BASE_URL,+ effective: false,+ });+ }++ if (layers.length) layers[0].effective = true;+ return layers;+}++/**+ * Codex's base-URL layers, highest precedence first.+ *+ * Codex resolves a PROVIDER, not a URL: `model_provider` names a key in the+ * `[model_providers]` table and that entry carries base_url. Reading only+ * `base_url` occurrences would report a provider the user is not selecting,+ * so the selected name is resolved first.+ */+export function codexLayers(+ env: NodeJS.ProcessEnv,+ homeDir: string,+): Layer[] {+ const layers: Layer[] = [];+ const configPath = path.join(env.CODEX_HOME ?? path.join(homeDir, '.codex'), 'config.toml');+ let toml = '';+ try {+ toml = fs.existsSync(configPath) ? fs.readFileSync(configPath, 'utf8') : '';+ } catch {+ toml = '';+ }++ const selected = /^\s*model_provider\s*=\s*["']([^"']+)["']/m.exec(toml)?.[1];+ if (selected) {+ // Both spellings the file format allows: a dotted key and a section.+ const dotted = new RegExp(+ `^\\s*model_providers\\.${escapeRegExp(selected)}\\.base_url\\s*=\\s*["']([^"']+)["']`,+ 'm',+ ).exec(toml)?.[1];+ const section = sectionValue(toml, `model_providers.${selected}`, 'base_url');+ const url = dotted ?? section;+ if (url) {+ layers.push({+ source: `${configPath} ([model_providers.${selected}] base_url)`,+ value: url,+ effective: false,+ });+ } else {+ layers.push({+ source: `${configPath} (model_provider = "${selected}", no base_url found)`,+ effective: false,+ });+ }+ }++ if (layers.length) layers[0].effective = true;+ return layers;+}++function escapeRegExp(value: string): string {+ return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');+}++/** Value of `key` inside a `[section]` block of a TOML document. */+function sectionValue(toml: string, section: string, key: string): string | undefined {+ const lines = toml.split('\n');+ let inSection = false;+ for (const raw of lines) {+ const line = raw.trim();+ const header = /^\[([^\]]+)\]$/.exec(line);+ if (header) {+ inSection = header[1].trim() === section;+ continue;+ }+ if (!inSection) continue;+ const match = new RegExp(`^${escapeRegExp(key)}\\s*=\\s*["']([^"']+)["']`).exec(line);+ if (match) return match[1];+ }+ return undefined;+}++/** How long the /livez probe waits before calling an endpoint unreachable. */+export const DEFAULT_PROBE_TIMEOUT_MS = 5_000;++/**+ * Probe a base URL's identity AND its health — two separate questions that must+ * not be collapsed.+ *+ * IDENTITY is structural: `/livez` answers `{status, version, uptime_s}` and+ * carries NO product identifier, so a body with that exact shape is evidence,+ * not proof — another service could serve the same three keys. `identified`+ * therefore means "responds the way this gateway responds", and the report says+ * so. Asserting identity harder would need either an authenticated call (the+ * CLI does not have a key here) or a product marker the server does not emit.+ *+ * HEALTH is the `status` VALUE, and it is deliberately not folded into+ * identity. The server really does emit `{status: 'unavailable', ...}` with a+ * 503 when the database or the encryption key is down (routes/status.ts), and+ * that response is still unmistakably this gateway. Requiring `status === 'ok'`+ * to identify it would report a correctly-routed but sick gateway as "probably+ * a different service on that port" — the confident wrong answer this command+ * exists to prevent. Anything that is not a 2xx `'ok'` is reported as+ * unhealthy and the raw status is echoed, so a status added later degrades into+ * a truthful "reaches this gateway, which says: <status>" instead of a lie.+ */+export async function probeGateway(+ baseUrl: string,+ fetchImpl: typeof fetch = fetch,+ timeoutMs: number = DEFAULT_PROBE_TIMEOUT_MS,+): Promise<GatewayProbe> {+ let response: Response;+ try {+ response = await fetchImpl(`${normalizeUrl(baseUrl)}/livez`, {+ signal: AbortSignal.timeout(timeoutMs),+ });+ } catch (error) {+ return {+ reachable: false,+ identified: false,+ healthy: false,+ error: error instanceof Error ? error.message : String(error),+ };+ }+ let body: Record<string, unknown> = {};+ try {+ body = await response.json() as Record<string, unknown>;+ } catch {+ return {+ reachable: true,+ identified: false,+ healthy: false,+ status: response.status,+ error: 'response was not JSON',+ };+ }+ const serviceStatus = typeof body.status === 'string' ? body.status : undefined;+ const identified = serviceStatus !== undefined+ && typeof body.version === 'string'+ && typeof body.uptime_s === 'number';+ return {+ reachable: true,+ identified,+ healthy: identified && serviceStatus === 'ok' && response.status >= 200 && response.status < 300,+ serviceStatus,+ status: response.status,+ version: typeof body.version === 'string' ? body.version : undefined,+ };+}++export interface DoctorOptions {+ /** The gateway the user believes they are using (--url / FREELLMAPI_URL). */+ expectedUrl: string;+ env?: NodeJS.ProcessEnv;+ homeDir?: string;+ /** Project-scoped settings are resolved relative to this. */+ cwd?: string;+ fetchImpl?: typeof fetch;+ /** Probe timeout. Raise it on a slow link, where the default would report a+ * reachable gateway as unreachable. */+ timeoutMs?: number;+}++const LAYER_RESOLVERS: Record<string, (env: NodeJS.ProcessEnv, homeDir: string, cwd: string) => Layer[]> = {+ claude: (env, homeDir, cwd) => claudeLayers(env, homeDir, cwd),+ codex: (env, homeDir) => codexLayers(env, homeDir),+};++export const DOCTOR_TOOLS = Object.keys(LAYER_RESOLVERS);++export async function diagnose(tool: string, options: DoctorOptions): Promise<ToolReport> {+ const env = options.env ?? process.env;+ const homeDir = options.homeDir ?? os.homedir();+ const resolve = LAYER_RESOLVERS[tool];+ if (!resolve) {+ return {+ tool,+ verdict: 'unknown',+ layers: [],+ detail: `doctor does not know how ${tool} resolves its endpoint. Known tools: ${DOCTOR_TOOLS.join(', ')}.`,+ };+ }++ const layers = resolve(env, homeDir, options.cwd ?? process.cwd());+ const effective = layers.find(layer => layer.effective);++ if (!effective?.value) {+ return {+ tool,+ verdict: 'unknown',+ layers,+ detail: layers.length+ ? 'A configuration layer was found but names no base URL, so the tool falls back to its vendor default.'+ : `No configuration found. ${tool} will use its vendor default endpoint, not this gateway.`,+ };+ }++ const gateway = await probeGateway(effective.value, options.fetchImpl, options.timeoutMs);++ // A lower-precedence layer naming a DIFFERENT url is the silent-override+ // case: the user edited that file and something outranks it.+ const overridden = layers.find(+ layer => !layer.effective && layer.value && !sameGateway(layer.value, effective.value),+ );++ if (!gateway.reachable) {+ return {+ tool,+ verdict: 'unreachable',+ layers,+ effectiveUrl: effective.value,+ gateway,+ detail: `${tool} is configured to use ${effective.value}, but nothing answered there (${gateway.error}).`,+ };+ }++ if (overridden) {+ return {+ tool,+ verdict: 'shadowed',+ layers,+ effectiveUrl: effective.value,+ shadowedBy: effective.source,+ gateway,+ detail:+ `${overridden.source} sets ${overridden.value}, but ${effective.source} outranks it, `+ + `so ${tool} actually uses ${effective.value}.`,+ };+ }++ // Two distinct ways to be pointed somewhere else, and both must fail the+ // check: a different host entirely, or the right host answering nothing that+ // looks like this gateway.+ if (!sameGateway(effective.value, options.expectedUrl)) {+ return {+ tool,+ verdict: 'elsewhere',+ layers,+ effectiveUrl: effective.value,+ gateway,+ detail:+ `${tool} reaches ${effective.value}, NOT the ${options.expectedUrl} this command was pointed at. `+ + 'Its traffic does not touch this gateway.',+ };+ }++ if (!gateway.identified) {+ return {+ tool,+ verdict: 'elsewhere',+ layers,+ effectiveUrl: effective.value,+ gateway,+ detail:+ `Something is listening at ${effective.value} and ${tool} would reach it, but it did not answer `+ + '/livez the way this gateway does — so it is probably a different service on that port.',+ };+ }++ // Routing is correct here and the gateway is unmistakably this one — it just+ // says it cannot serve. Reporting that as `routed` would send the user+ // hunting through config that is already right, so it gets its own verdict+ // and a nonzero exit.+ if (!gateway.healthy) {+ return {+ tool,+ verdict: 'degraded',+ layers,+ effectiveUrl: effective.value,+ gateway,+ detail:+ `${tool} reaches ${effective.value} and that IS this gateway, but it reports `+ + `status "${gateway.serviceStatus}" (HTTP ${gateway.status}) — it cannot serve requests. `+ + 'The routing is fine; the gateway is not.',+ };+ }++ return {+ tool,+ verdict: 'routed',+ layers,+ effectiveUrl: effective.value,+ gateway,+ detail: `${tool} reaches ${effective.value}${gateway.version ? ` (gateway v${gateway.version})` : ''}.`,+ };+}++const SYMBOL: Record<Verdict, string> = {+ routed: 'OK ',+ degraded: 'WARN',+ elsewhere: 'FAIL',+ shadowed: 'WARN',+ unreachable: 'FAIL',+ unknown: '? ',+};++export function formatReport(report: ToolReport): string {+ const lines = [`${SYMBOL[report.verdict]} ${report.tool}: ${report.verdict}`, ` ${report.detail}`];+ for (const layer of report.layers) {+ lines.push(` ${layer.effective ? '->' : ' '} ${layer.source}${layer.value ? ` = ${layer.value}` : ''}`);+ }+ if (report.gateway?.reachable && !report.gateway.identified) {+ lines.push(' note: something answered, but not with this gateway\'s /livez shape.');+ }+ return lines.join('\n');+}++/** Exit code: 0 when every tool is routed, 1 otherwise — so it is usable in a+ * script, not only by eye. */+export function exitCodeFor(reports: ToolReport[]): number {+ return reports.every(report => report.verdict === 'routed') ? 0 : 1;+}diff --git a/cli/src/index.test.ts b/cli/src/index.test.tsindex 6fd96334..341f46fb 100644--- a/cli/src/index.test.ts+++ b/cli/src/index.test.ts@@ -2,7 +2,7 @@ import fs from 'node:fs';import os from 'node:os';import path from 'node:path';import { afterEach, describe, expect, it } from 'vitest';-import { claudeLaunchEnv, codexArgs, parseArgs, resolvePinnedModel } from './index.js';+import { claudeLaunchEnv, codexArgs, main, parseArgs, resolvePinnedModel } from './index.js';import { UnknownModelError } from './models.js';import type { CatalogModel } from './types.js';@@ -36,6 +36,28 @@ describe('CLI arguments and launchers', () => {.toThrow('--profile requires a value');});+ it('parses doctor --timeout, and rejects a value that is not milliseconds', () => {+ expect(parseArgs(['doctor', '--timeout', '30000']).options.timeoutMs).toBe(30_000);+ expect(parseArgs(['doctor', '--timeout=250']).options.timeoutMs).toBe(250);+ // Left undefined rather than defaulted here, so doctor.ts owns the default.+ expect(parseArgs(['doctor']).options.timeoutMs).toBeUndefined();+ // Rejected, not silently ignored: a typo quietly becoming the default is+ // exactly the quiet no-op this command exists to catch.+ expect(() => parseArgs(['doctor', '--timeout', '5s'])).toThrow('positive number of milliseconds');+ expect(() => parseArgs(['doctor', '--timeout', '0'])).toThrow('positive number of milliseconds');+ });++ it('still rejects a stray positional for commands that take none', async () => {+ // `doctor` is the only command with positional arguments, so parseArgs+ // collects them generically. The dispatcher has to reject them for every+ // other command BEFORE dispatch — checked after the setup-* branch, the+ // stray word would be silently ignored instead of erroring.+ await expect(main(['setup-claude', 'typo'])).rejects.toThrow('Unknown option: typo');+ await expect(main(['launch', 'typo'])).rejects.toThrow('Unknown option: typo');+ // ...and doctor still takes them.+ expect(parseArgs(['doctor', 'claude']).options.args).toEqual(['claude']);+ });+const models: CatalogModel[] = [{ id: 'auto' },{ id: 'fast-coder', available: true, context_window: 131072 },diff --git a/cli/src/index.ts b/cli/src/index.tsindex 372a74a2..a02e8c82 100644--- a/cli/src/index.ts+++ b/cli/src/index.ts@@ -10,6 +10,7 @@ import { fileURLToPath } from 'node:url';import { applyGeneratedFiles, printDryRunDiff } from './config-files.js';import { getTool, tools } from './tools.js';import { resolveLaunchModel, type ResolvedModel } from './models.js';+import { DOCTOR_TOOLS, diagnose, exitCodeFor, formatReport, type ToolReport } from './doctor.js';import type { CatalogModel, GenerateContext } from './types.js';interface CliOptions {@@ -18,6 +19,11 @@ interface CliOptions {profile: string;model?: string;dryRun: boolean;+ /** `doctor --timeout`: how long to wait for the /livez probe. */+ timeoutMs?: number;+ /** Positional arguments after the command. Only `doctor` takes any; every+ * other command still rejects a second positional as it always has. */+ args: string[];}function rootUrl(url: string): string {@@ -37,12 +43,24 @@ function validateProfile(profile: string): string {return profile;}+function parseTimeout(value: string): number {+ const ms = Number(value);+ // Rejected rather than clamped: a typo'd `--timeout 5s` parsing to NaN and+ // silently becoming the default is the kind of quiet no-op this command is+ // supposed to be immune to.+ if (!Number.isFinite(ms) || ms <= 0) {+ throw new Error(`--timeout must be a positive number of milliseconds, got '${value}'`);+ }+ return ms;+}+export function parseArgs(argv: string[]): { command?: string; options: CliOptions } {const options: CliOptions = {url: process.env.FREELLMAPI_URL || 'http://localhost:3000',apiKey: process.env.FREELLMAPI_API_KEY,profile: 'default',dryRun: false,+ args: [],};let command: string | undefined;for (let index = 0; index < argv.length; index += 1) {@@ -51,13 +69,23 @@ export function parseArgs(argv: string[]): { command?: string; options: CliOptiocommand = arg;continue;}+ if (!arg.startsWith('-')) {+ // Collected rather than rejected here so the parser stays generic; the+ // dispatcher rejects extras for commands that take none, which keeps+ // `setup-claude typo` an error instead of a silently ignored word.+ options.args.push(arg);+ continue;+ }if (arg === '--dry-run') {options.dryRun = true;continue;}const [flag, inline] = arg.split('=', 2);const value = inline ?? argv[index + 1];- if (flag === '--url' || flag === '--api-key' || flag === '--profile' || flag === '--model') {+ if (+ flag === '--url' || flag === '--api-key' || flag === '--profile'+ || flag === '--model' || flag === '--timeout'+ ) {if (inline === undefined) index += 1;if (!value || (inline === undefined && value.startsWith('-'))) {throw new Error(`${flag} requires a value`);@@ -65,6 +93,7 @@ export function parseArgs(argv: string[]): { command?: string; options: CliOptioif (flag === '--url') options.url = value;else if (flag === '--api-key') options.apiKey = value;else if (flag === '--profile') options.profile = validateProfile(value);+ else if (flag === '--timeout') options.timeoutMs = parseTimeout(value);else options.model = value;continue;}@@ -214,6 +243,8 @@ function help(): string {'','Commands:',...tools.map(tool => ` ${tool.command.padEnd(17)} ${tool.name}`),+ ' doctor [tool…] Check whether a tool\'s requests actually reach this gateway',+ ' (--timeout MS raises the probe wait on a slow link)',' launch Run Claude Code with credentials injected into the child environment',' launch-codex Run Codex with provider overrides and injected credentials',' list List supported coding agents',@@ -380,12 +411,34 @@ async function launchCodex(options: CliOptions): Promise<number> {return runChild('codex', args, env);}+async function runDoctor(options: CliOptions): Promise<number> {+ const requested = options.args.length ? options.args : DOCTOR_TOOLS;+ const reports: ToolReport[] = [];+ for (const tool of requested) {+ reports.push(await diagnose(tool, {+ expectedUrl: rootUrl(options.url),+ timeoutMs: options.timeoutMs,+ }));+ }+ for (const report of reports) process.stdout.write(`${formatReport(report)}\n`);+ // Nonzero when anything is not routed, so this is usable as a precondition+ // in a script rather than only readable by eye.+ return exitCodeFor(reports);+}+export async function main(argv = process.argv.slice(2)): Promise<number> {const { command, options } = parseArgs(argv);if (!command || command === 'help' || argv.includes('--help') || argv.includes('-h')) {process.stdout.write(`${help()}\n`);return 0;}+ // `doctor` is the only command that takes positional arguments. Every other+ // one rejects them here, BEFORE dispatch — checking after the setup-* branch+ // would let `setup-claude typo` run with the stray word silently ignored,+ // where it used to be an error.+ if (command !== 'doctor' && options.args.length) {+ throw new Error(`Unknown option: ${options.args[0]}`);+ }if (command === 'list') {for (const tool of tools) {process.stdout.write(`${tool.id}\t${tool.protocol}\t${tool.baseUrlSupport}\n`);@@ -396,6 +449,7 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {await setup(command, options);return 0;}+ if (command === 'doctor') return runDoctor(options);if (command === 'launch') return launchClaude(options);if (command === 'launch-codex') return launchCodex(options);throw new Error(`Unknown command '${command}'\n\n${help()}`);