llm-relay 0.46.2 → 0.47.1

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { isRecord } from "./json-shape.js";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
@@ -8,7 +9,7 @@ import { loadEnvFile } from "./dotenv.js";
 import { recoverWindowsEnv } from "./winenv.js";
 import { offloadState, setOffload } from "./offload.js";
 import { buildCandidates } from "./candidates.js";
-import { CREDENTIAL_LABEL_PATTERN, makeCredentialId, parseCredentialId } from "./credential-id.js";
+import { CREDENTIAL_LABEL_PATTERN, makeCredentialId } from "./credential-id.js";
 import { providerCredentialSlots, slotAllowsModel } from "./credential-fleet.js";
 import { loadLaneManifest, verifyModel } from "./lane-manifest.js";
 import { probeLanes } from "./lane-probe.js";
@@ -28,6 +29,7 @@ import { materializeDynamicPools } from "./dynamic-pools.js";
 import { currentVersion, ensureUpToDate, shouldCheckUpdates } from "./self-update.js";
 import { deleteConfigPath, parseConfigValue, readConfigDocument, readConfigPath, updateConfigDocument, writeConfigPath, } from "./config-edit.js";
 import { createControlAuthorization, resolveControlAuthorizationConfigDir } from "./control-authorization.js";
+import { isCooldownClearResult } from "./cooldown-clear.js";
 import { createDashboardSnapshotReadPort } from "./dashboard-snapshot.js";
 import { DASHBOARD_MEDIA_TYPE, isDashboardUtcTimestamp } from "./dashboard-contract.js";
 import { DASHBOARD_BOOTSTRAP_SCHEMA, DASHBOARD_BOOTSTRAP_REQUEST_SCHEMA } from "./dashboard-routes.js";
@@ -751,136 +753,6 @@ function cooldownCommandFailure(message) {
     process.stderr.write(`llm-relay cooldowns: ${message}\n`);
     process.exit(1);
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function hasExactKeys(value, keys) {
-    const actual = Object.keys(value);
-    return actual.length === keys.length && actual.every((key) => keys.includes(key));
-}
-function nonEmptyString(value) {
-    return typeof value === "string" && value.length > 0;
-}
-const COOLING_FACT_KINDS = new Set([
-    "allowance-exhausted",
-    "rate-limited",
-    "credential-invalid",
-]);
-function credentialIdBelongsTo(provider, value) {
-    if (typeof value !== "string")
-        return false;
-    return parseCredentialId(value)?.provider === provider;
-}
-function isCooldownFactScope(value) {
-    if (!isRecord(value))
-        return false;
-    switch (value.kind) {
-        case "attempt":
-            return hasExactKeys(value, ["kind", "provider", "credentialId", "model"]) &&
-                nonEmptyString(value.provider) &&
-                credentialIdBelongsTo(value.provider, value.credentialId) &&
-                nonEmptyString(value.model);
-        case "group": {
-            const keys = Object.hasOwn(value, "credentialId")
-                ? ["kind", "provider", "credentialId", "members"]
-                : ["kind", "provider", "members"];
-            return hasExactKeys(value, keys) &&
-                nonEmptyString(value.provider) &&
-                Array.isArray(value.members) &&
-                value.members.length > 0 &&
-                value.members.every(nonEmptyString) &&
-                (!Object.hasOwn(value, "credentialId") || credentialIdBelongsTo(value.provider, value.credentialId));
-        }
-        case "deployment":
-            return hasExactKeys(value, ["kind", "provider", "model"]) &&
-                nonEmptyString(value.provider) && nonEmptyString(value.model);
-        case "credential":
-            return hasExactKeys(value, ["kind", "provider", "credentialId"]) &&
-                nonEmptyString(value.provider) && credentialIdBelongsTo(value.provider, value.credentialId);
-        case "provider":
-            return hasExactKeys(value, ["kind", "provider"]) && nonEmptyString(value.provider);
-        case "model":
-            return hasExactKeys(value, ["kind", "model"]) && nonEmptyString(value.model);
-        default:
-            return false;
-    }
-}
-function scopeIsContainedByTarget(scope, target) {
-    const credentialId = target.credential === undefined
-        ? undefined
-        : makeCredentialId(target.provider, target.credential);
-    switch (scope.kind) {
-        case "attempt":
-            return scope.provider === target.provider &&
-                (target.model === undefined || scope.model === target.model) &&
-                (credentialId === undefined || scope.credentialId === credentialId);
-        case "group":
-            return scope.provider === target.provider &&
-                (target.model === undefined || scope.members.every((member) => member === target.model)) &&
-                (credentialId === undefined || scope.credentialId === credentialId);
-        case "deployment":
-            return scope.provider === target.provider && credentialId === undefined &&
-                (target.model === undefined || scope.model === target.model);
-        case "credential":
-            return scope.provider === target.provider && target.model === undefined &&
-                (credentialId === undefined || scope.credentialId === credentialId);
-        case "provider":
-            return scope.provider === target.provider && target.model === undefined && credentialId === undefined;
-        case "model":
-            return false;
-    }
-}
-function isCooldownCell(value, target) {
-    if (!isRecord(value) || !hasExactKeys(value, ["provider", "model", "credential"]))
-        return false;
-    if (!nonEmptyString(value.provider) || value.provider !== target.provider)
-        return false;
-    if (!(value.model === null || nonEmptyString(value.model)))
-        return false;
-    if (!nonEmptyString(value.credential) || !CREDENTIAL_LABEL_PATTERN.test(value.credential))
-        return false;
-    return (target.model === undefined || value.model === target.model) &&
-        (target.credential === undefined || value.credential === target.credential);
-}
-function isCooldownFact(value, target) {
-    return isRecord(value) &&
-        hasExactKeys(value, ["kind", "scope"]) &&
-        typeof value.kind === "string" &&
-        COOLING_FACT_KINDS.has(value.kind) &&
-        isCooldownFactScope(value.scope) &&
-        scopeIsContainedByTarget(value.scope, target);
-}
-function isClearedGroup(value, isItem) {
-    if (!isRecord(value) || !hasExactKeys(value, ["count", "items"]) ||
-        typeof value.count !== "number" || !Number.isSafeInteger(value.count) ||
-        value.count < 0 || !Array.isArray(value.items)) {
-        return false;
-    }
-    return value.count === value.items.length && value.items.every(isItem);
-}
-function isExactCooldownTarget(value, expected) {
-    if (!isRecord(value))
-        return false;
-    const keys = [
-        "provider",
-        ...(expected.model === undefined ? [] : ["model"]),
-        ...(expected.credential === undefined ? [] : ["credential"]),
-    ];
-    return hasExactKeys(value, keys) &&
-        value.provider === expected.provider &&
-        (expected.model === undefined || value.model === expected.model) &&
-        (expected.credential === undefined || value.credential === expected.credential);
-}
-function isCooldownClearResult(value, target) {
-    if (!isRecord(value) || !hasExactKeys(value, ["target", "cleared"]) ||
-        !isExactCooldownTarget(value.target, target) || !isRecord(value.cleared) ||
-        !hasExactKeys(value.cleared, ["breakerCells", "credentialFaults", "facts"])) {
-        return false;
-    }
-    return isClearedGroup(value.cleared.breakerCells, (item) => isCooldownCell(item, target)) &&
-        isClearedGroup(value.cleared.credentialFaults, (item) => isCooldownCell(item, target)) &&
-        isClearedGroup(value.cleared.facts, (item) => isCooldownFact(item, target));
-}
 const COOLDOWN_CLEAR_OPTIONS = new Map([
     ["--credential", { semantic: "credential", takesValue: true }],
     ["--json", { semantic: "json", takesValue: false }],
@@ -891,11 +763,119 @@ const COOLDOWN_CLEAR_OPTIONS = new Map([
     ["--refresh", { semantic: "refresh", takesValue: false }],
     ["-r", { semantic: "refresh", takesValue: false }],
 ]);
-const CLI_COMMAND_NAMES = new Set([
+export const CLI_COMMAND_NAMES = new Set([
     "onboard", "setup", "keys", "check-keys", "models", "ping", "dashboard", "telemetry",
     "offload", "lanes", "dispatch", "cooldowns", "eligibility", "candidates", "cost", "pools",
     "routing", "route", "config", "help", "version",
 ]);
+/**
+ * Positional-ARITY bounds per command — the shared half of "an ignored argument is a lie".
+ *
+ * `llm-relay cost --window 1h 7d` silently dropped `7d` and reported 24h; `llm-relay models nim`
+ * listed every provider. Exact arity existed only on the mutating/custody surfaces, so the whole
+ * read-only family accepted and discarded whatever it did not understand. Counting INCLUDES the
+ * command token: `llm-relay cost` is 1, `llm-relay config set a b` is 4.
+ *
+ * ⚠ Every bound is derived from what the DISPATCHER READS — `arg3`/`arg4`/`positionals[n]`/
+ * `.slice()` — never from HELP, which drifts: `lanes` and the `route` alias appear nowhere in it,
+ * and `setup`'s documented `claude-cli` target matches no branch at all (it works by fall-through).
+ * A table built from the help text would have left two commands unguarded and mis-bounded a third.
+ *
+ * ⚠ DELIBERATELY ABSENT — do not "complete" this table with them:
+ *   `keys`      — `validateKeysCommandArgs` is EXACT per subcommand and runs above this guard. It
+ *                 is also secret-safe by design ("diagnostics deliberately never echo rejected
+ *                 argv tokens", since a pasted credential can land in argv). A generic entry would
+ *                 be dead code at best and a second, laxer refusal at worst.
+ *   `cooldowns` — `parseCooldownClearArgs` requires exactly 3 and its branch RETURNS before this
+ *                 guard; it is also reachable through `rawCliCommand`'s special case, which keys
+ *                 on raw argv this guard cannot see.
+ *   `help` /    — both `process.exit(0)` above this guard, which is what makes `llm-relay <cmd>
+ *   `version`     --help` work for every command. A bound here could never fire.
+ */
+const COMMAND_ARITY = {
+    // Reads no positional; `--import` is a VALUE_FLAG and `--force` is a boolean.
+    onboard: { min: 1, max: 1 },
+    // `arg3` is the last slot read: `claude-desktop` / `desktop`, else fall-through to the CLI setup.
+    setup: { min: 1, max: 2 },
+    // Handled inline in main(); arg3/arg4 are in scope and never referenced.
+    telemetry: { min: 1, max: 1 },
+    // `runCheckKeys()` takes no arguments. ⚠ No hint: it has no provider filter — it hands the whole
+    // config to `validateProviderKeys`, so suggesting `-p` would point at a flag that does nothing.
+    "check-keys": { min: 1, max: 1 },
+    models: { min: 1, max: 1, hint: "llm-relay models -p <name>" },
+    ping: { min: 1, max: 1, hint: "llm-relay ping -p <name>" },
+    candidates: { min: 1, max: 1, hint: "llm-relay candidates -p <name>" },
+    // `runCostCommand` takes only a test seam; window/by/include-repair are all flags.
+    cost: { min: 1, max: 1, hint: "llm-relay cost --window <w> --by <d>" },
+    // ⚠ Absent from HELP entirely, so its users cannot check usage — and the adjacent `dispatch`
+    // DOES take a positional lane, which is exactly the confusion worth naming.
+    lanes: { min: 1, max: 1, hint: "llm-relay dispatch <lane>" },
+    dashboard: { min: 1, max: 1 },
+    // `runDispatch(arg3)` — one optional lane positional.
+    dispatch: { min: 1, max: 2 },
+    // `runOffload(arg3, arg4)`. The semantic checks inside it (refusing a bare `offload on`, and
+    // `offload status <anything>`) sit INSIDE this bound and stay where they are.
+    offload: { min: 1, max: 3 },
+    // `runEligibility(arg3, arg4)`.
+    eligibility: { min: 1, max: 3 },
+    // `positionals[3]` is the highest fixed slot anywhere in this file. `config set`/`unset` cap
+    // themselves tighter; this is the outer bound only.
+    config: { min: 1, max: 4 },
+    // VARIADIC: `positionals.slice(3)` — `pools set <name> <spec> [<spec>...]`.
+    pools: { min: 1, max: -1 },
+    // VARIADIC twice over: `slice(2)` for `routing default`, `slice(3)` for `routing tier`.
+    // Multi-candidate specs are a documented routing feature, so any finite max is a false positive.
+    routing: { min: 1, max: -1 },
+    // Same handler as `routing`; omitting the alias would leave it unguarded.
+    route: { min: 1, max: -1 },
+};
+/**
+ * Refuse a command given more positionals than it can read, or fewer than it needs.
+ *
+ * Pure and exported so the whole table is testable without driving `main()`.
+ *
+ * ⚠ Returns null on an EMPTY positional list. That is bare `llm-relay` — the documented way to
+ * start the proxy — and also the `--ping` flag entry, which reaches the ping command with no
+ * positional at all. Applying a minimum there is the one guaranteed false positive available.
+ *
+ * ⚠ Returns null on a table MISS. An unknown command name belongs to `dispatchDashboardOrProxy`,
+ * which already refuses it against `CLI_COMMAND_NAMES`; two refusals for one mistake would be
+ * worse than one.
+ *
+ * ⚠ The extra token is deliberately NOT echoed, unlike the unknown-command guard. An unknown
+ * COMMAND is by definition not a secret-bearing position and naming it is the whole diagnostic;
+ * a stray POSITIONAL can be anything the user pasted — and `check-keys` here is the same command
+ * as `keys check`, whose parser never echoes argv for exactly that reason. The count plus a
+ * verified hint is enough to act on, and the user can still see what they typed.
+ */
+/**
+ * Commands whose arity is owned elsewhere, exported so the coverage test can state WHY each is
+ * absent from `COMMAND_ARITY` rather than letting a future omission look identical to an oversight.
+ */
+export const ARITY_EXEMPT = new Set(["keys", "cooldowns", "help", "version"]);
+/** The commands this guard bounds — exported for the drift test, not for dispatch. */
+export const ARITY_GUARDED_COMMANDS = Object.keys(COMMAND_ARITY);
+export function commandArityError(positionals) {
+    const name = positionals[0];
+    if (name === undefined)
+        return null;
+    const arity = COMMAND_ARITY[name];
+    if (!arity)
+        return null;
+    const hint = arity.hint ? ` Did you mean \`${arity.hint}\`?` : "";
+    if (arity.max >= 0 && positionals.length > arity.max) {
+        const extra = positionals.length - arity.max;
+        const allowed = arity.max - 1;
+        const takes = allowed === 0
+            ? "takes no arguments after the command"
+            : `takes at most ${allowed} argument${allowed === 1 ? "" : "s"} after the command`;
+        return `llm-relay ${name}: ${takes} (got ${extra} too many).${hint} Run 'llm-relay help' for usage.`;
+    }
+    if (positionals.length < arity.min) {
+        return `llm-relay ${name}: missing required argument.${hint} Run 'llm-relay help' for usage.`;
+    }
+    return null;
+}
 /** Find a real command token without letting a typoed option/value pair hide a later mutation. */
 function rawCliCommand(argv) {
     for (let index = 2; index < argv.length; index++) {
@@ -981,6 +961,11 @@ export async function runCooldowns(_action, _spec) {
         ...(model === undefined ? {} : { model }),
         ...(credential === undefined ? {} : { credential }),
     };
+    const acceptedTargetKeys = [
+        "provider",
+        ...(model === undefined ? [] : ["model"]),
+        ...(credential === undefined ? [] : ["credential"]),
+    ];
     const cfg = loadOrExit();
     if (!Object.hasOwn(cfg.providers, provider)) {
         cooldownCommandFailure(`no provider "${provider}" configured`);
@@ -1018,7 +1003,7 @@ export async function runCooldowns(_action, _spec) {
         const detail = controlErrorMessage(payload);
         cooldownCommandFailure(`the running relay rejected the clear${detail === null ? "" : `: ${detail}`}`);
     }
-    if (!isCooldownClearResult(payload, target)) {
+    if (!isCooldownClearResult(payload, target, acceptedTargetKeys)) {
         cooldownCommandFailure("the running relay returned an invalid cooldown-clear response");
     }
     if (parsed.json) {
@@ -2888,6 +2873,28 @@ export function main() {
         process.stdout.write(`${currentVersion()}\n`);
         process.exit(0);
     }
+    // ⚠ THIS LINE, not one earlier and not one later.
+    //
+    // BELOW it is the first side effect in the whole ladder: the very next branch calls
+    // `loadOrExit()`, whose `resolveConfigPath` fall-through CREATES `~/.llm-relay/config.json`. Past
+    // that lie probes of every model (`ping`), authenticated provider calls (`check-keys`), spawned
+    // lane commands (`lanes --probe`), POSTs to the running relay, a minted one-use dashboard
+    // bootstrap, and the accounting store. Refusing here costs none of them.
+    //
+    // ABOVE it, nothing durable has happened — but two things MUST stay above: `keys` and
+    // `cooldowns` own strict, fail-closed, secret-safe parsers (and cooldowns returns), and
+    // `--help`/`--version` short-circuit, which is what makes `llm-relay <cmd> --help` work for
+    // every command. Moving this check above them would flip `llm-relay cost extra --help` from
+    // printing help to exit 1.
+    //
+    // Keyed on `positionals[0]`, never on `rawCliCommand`: that scans PAST a leading non-command
+    // token, so `llm-relay bogus cost` would arity-check `cost` while main() dispatches `bogus`.
+    const arityError = commandArityError(positionals);
+    if (arityError !== null) {
+        process.stderr.write(`${arityError}\n`);
+        process.exit(1);
+        return;
+    }
     if (arg2 === "onboard") {
         const cfg = loadOrExit();
         if (hasFlag("--import", "-import")) {