Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors
TypeScript a2aai-agentsai-gatewayanthropicclaudeclaude-codeclinecodexcopilotcursordeepseekfree-aigeminikimillm-gatewaymcpopenaiopenai-proxyqwentoken-saver
#!/usr/bin/env node
/**
* Strict environment variable contract checker.
*
* Enforces that every env var referenced in OmniRoute source code appears in
* both `.env.example` and `docs/reference/ENVIRONMENT.md`, and that the two files agree
* on the documented var set. Falls back to a small allowlist for variables
* that are intentionally documented but not literally referenced (legacy
* aliases, future-supported hooks) or vice versa.
*
* Usage:
* node scripts/check/check-env-doc-sync.mjs # strict (CI mode)
* node scripts/check/check-env-doc-sync.mjs --lenient # legacy report-only mode
*
* Strict mode exits non-zero if any of these are non-empty:
* - vars in code but missing from .env.example
* - vars in .env.example but missing from ENVIRONMENT.md
* - vars in ENVIRONMENT.md but missing from .env.example
*
* Programmatic API:
* Other Node tests can `import { runEnvDocSync } from "./check-env-doc-sync.mjs"`
* and pass `{ root, envExample, envDoc, codeVars, ignore, docOnlyAllowlist,
* envOnlyAllowlist }` to drive the checker against fixtures.
*/
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const REPO_ROOT = path.resolve(__dirname, "..", "..");
// ─── Allowlists ────────────────────────────────────────────────────────────
// Env vars referenced in code that should NOT trigger documentation drift.
// These are usually system/process vars or harness-only knobs.
const IGNORE_FROM_CODE = new Set([
"NODE_ENV",
"PATH",
"HOME",
"USER",
"LOGNAME",
"XDG_CURRENT_DESKTOP",
"PWD",
"SHELL",
"TERM",
"TZ",
"LANG",
"LC_ALL",
"LC_MESSAGES",
"CI",
"GITHUB_ACTIONS",
"RUNNER_OS",
// Quality-gate harness knobs (optional cache/report paths for CI scripts — not product config).
"ESLINT_RESULTS_JSON",
"COMPLEXITY_ESLINT_REPORT",
// Agent environment / system execution paths.
"PROJECT_ROOT",
"ARTIFACTS_DIR",
// OS / Node internals frequently surfaced by indirect dependencies.
"APPDATA",
"LOCALAPPDATA",
"PROGRAMFILES",
"XDG_CONFIG_HOME",
// Codex-owned task/runtime locations and child-process markers. OmniRoute reads
// them as external execution context, not as product configuration.
"CODEX_HOME",
"CODEX_CHATGPT_WEB_BROWSER_HELPER_PROCESS",
// Claude Code's own config-root variable: the CLI only SETS it for the child `claude`
// process (bin/cli/commands/launch.mjs, setup-claude hint, #12161) — never product config.
"CLAUDE_CONFIG_DIR",
// systemd-injected notify socket path (sd_notify protocol, see
// scripts/dev/systemd-notify.mjs) — set by systemd only when running under
// a unit, never user config.
"NOTIFY_SOCKET",
// XDG Base Directory cache root — read (never defined by OmniRoute) so the
// Android/Termux serve path can honor an operator-set cache location (#8519).
"XDG_CACHE_HOME",
"USERPROFILE",
"PREFIX",
// X11 display server — set by the OS/session manager, not OmniRoute config.
"DISPLAY",
// POSIX session vars surfaced by cloudflaredTunnel.ts (env passthrough).
"LOGNAME",
"XDG_CURRENT_DESKTOP",
// Next.js / Node test runners — these are framework-managed.
"NEXT_DIST_DIR",
"NEXT_PHASE",
"NEXT_RUNTIME",
// Set/read by Next.js's own dev server (next-dev-server.js) when the turbopack
// bundler is active — framework-internal. The OmniRoute-facing knob is
// OMNIROUTE_USE_TURBOPACK (scripts/dev/run-next.mjs), which IS documented.
"TURBOPACK",
// Electron sets this on its embedded Node server; children must preserve Node mode.
// Runtime-owned context, never a user-facing OmniRoute setting (#16454).
"ELECTRON_RUN_AS_NODE",
"NODE_TEST_CONTEXT",
"VITEST",
// Instruction snippet shown to users (Traffic Inspector HttpProxySnippetCard) — not OmniRoute config.
"NODE_TLS_REJECT_UNAUTHORIZED",
// Claude Code's own auth env var — read from the CLI environment to detect
// existing auth and written into the generated Claude Code settings (so the CLI
// points at OmniRoute). A downstream client-tool var, not an OmniRoute server
// input (src/shared/services/claudeCliConfig.ts, api/cli-tools/claude-settings).
"ANTHROPIC_AUTH_TOKEN",
// CI providers (set by the runner).
"GITHUB_BASE_REF",
"GITHUB_BASE_SHA",
// Actions-owned output file used by scripts/ci/release-green-result.mjs.
// A runner protocol path, not user-configurable OmniRoute environment.
"GITHUB_OUTPUT",
// check-ai-attribution.mjs reads the PR of the Actions event payload when run without args (#14436)
"GITHUB_EVENT_PATH",
// Actions-owned output file used by scripts/ci/release-green-result.mjs.
// A runner protocol path, not user-configurable OmniRoute environment.
"GITHUB_OUTPUT",
// Runner-owned identity/event context and same-run job results consumed by
// scripts/quality/admission-verdict.mjs; never application .env settings.
"GITHUB_EVENT_NAME",
"GITHUB_RUN_ATTEMPT",
"GITHUB_RUN_ID",
"GITHUB_SHA",
"NEEDS_JSON",
// Set by the Actions runner; the ts7 ratchet appends its job summary there
// (scripts/check/check-ts7-diagnostics-ratchet.mjs) — never OmniRoute runtime config (#9985).
"GITHUB_STEP_SUMMARY",
// Same class as BASE_REF: CI passes the PR base ref to the ts7 diagnostics ratchet
// (scripts/check/check-ts7-diagnostics-ratchet.mjs) — a check signal, not runtime config (#9985).
"TS7_BASE_REF",
// CI passes BASE_REF=${{ github.base_ref }} to the OpenAPI breaking-change gate
// (scripts/check/check-openapi-breaking.mjs) — a build/check signal, not OmniRoute runtime config.
"BASE_REF",
// Same class as BASE_REF above: the `changes` job passes these four to the
// self-targeting-PR guard (scripts/check/check-pr-self-target.mjs) so it can compare a PR's
// head against its base. CI-only signals from github.head_ref / github.base_ref /
// pull_request.{head,base}.sha — never OmniRoute runtime config, and meaningless in a .env.
"HEAD_REF",
"HEAD_SHA",
"BASE_SHA",
// Escape hatch for the test-masking gate's release-scale skip
// (scripts/check/check-test-masking.mjs): above ~300 changed test files the per-file diff
// subchecks are skipped, and this raises that cap for anyone who wants the full pass anyway.
// A gate tuning knob, not application configuration.
"TEST_MASKING_MAX_CHANGED_TESTS",
// PR body injected by GitHub Actions into the pr-evidence gate (github.event.pull_request.body);
// a CI-only signal, never an OmniRoute runtime config (Phase 7.10).
"PR_BODY",
// CLI machine-id token opt-out (server-side flag; not user-configurable via .env).
"OMNIROUTE_DISABLE_CLI_TOKEN",
// Gated combo live-smoke harness (scripts/test/_vpsClient.mjs) — override the VPS HTTP
// smoke target host/key. Test/CI-only signals with safe defaults
// ("http://192.168.0.15:20128" / null), never OmniRoute runtime config (#5151).
"COMBO_LIVE_BASE_URL",
"COMBO_LIVE_API_KEY",
// Ad-hoc mesh/coverage scripts under scripts/ad-hoc/*.mjs (mesh-send, mesh-run,
// verify-coverage). Operator-supplied script secrets, not OmniRoute runtime config.
"BOT_TOKEN",
"BOT_URL",
// Homologation E2E suite (npm run homolog) vars — configured via the dedicated
// .env.homolog file (template: .env.homolog.example), never in the runtime .env.
// Test/ops-only signals against the homologation VPS, same class as COMBO_LIVE_*.
// See docs/ops/HOMOLOGATION.md.
"HOMOLOG_BASE_URL",
"HOMOLOG_ADMIN_PASSWORD",
"HOMOLOG_API_KEY",
"HOMOLOG_CRITICAL_PROVIDERS",
"HOMOLOG_EXPECT_VERSION",
// update-notifier opt-out for the CLI binary.
"OMNIROUTE_NO_UPDATE_NOTIFIER",
// Headless CLI execution flag for Electron.
"OMNIROUTE_HEADLESS",
// Platform / OS detection vars read by CLI environment helper (bin/cli/utils/environment.mjs).
// These are external signals set by the host OS or cloud provider — not OmniRoute config.
"CODESPACES",
"GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN",
"GITPOD_WORKSPACE_ID",
"NO_COLOR",
"REPL_ID",
"REPL_SLUG",
"WSL_DISTRO_NAME",
"WSL_INTEROP",
// X11/Wayland display server vars used by tray heuristic (isTraySupported).
"DISPLAY",
"WAYLAND_DISPLAY",
// Build-time overrides for generate-api-commands.mjs (spec input / commands output dir).
// OPENAPI_OUT_DIR exists so tests/unit/cli-api-generator-ref-params.test.ts can regenerate
// into a scratch dir instead of the real bin/cli/api-commands/ tree.
"OPENAPI_SPEC",
"OPENAPI_OUT_DIR",
// Aliases for documented vars handled via fallback ordering.
"API_KEY",
"APP_URL",
"PUBLIC_URL",
"ANTHROPIC_API_URL",
"OPENAI_API_URL",
"LOG_LEVEL",
// Internal QA helpers used only by scripts/ and Playwright.
"QA_BASE_URL",
"QA_LOCALES",
"QA_REPORT_SUFFIX",
"QA_ROUTES",
// Post-publish verifier (scripts/release/verify-published.mjs): env passed INTO the
// clean Docker container script (Hard Rule #13 env-option pattern) — release tooling
// internals, never OmniRoute runtime config.
"VERIFY_DEADLINE_S",
"VERIFY_PORT",
"VERIFY_VERSION",
// Doctor diagnostic flags (no runtime behavior yet — placeholders).
"OMNIROUTE_DOCTOR_HOST",
"OMNIROUTE_DOCTOR_LIVENESS_URL",
"OMNIROUTE_PROVIDER_CATALOG_PATH",
"OMNIROUTE_PROVIDER_TEST_MODEL",
// Test-only opt-out: instructs bin/omniroute.mjs to skip auto-loading the
// repository .env so isolation tests get a deterministic environment.
"OMNIROUTE_CLI_SKIP_REPO_ENV",
// Eval-harness only: operator-supplied provider credentials JSON read by the
// opt-in `npm run eval:compression` CLI (scripts/compression-eval/index.ts).
// A dev/ops measurement tool, never OmniRoute runtime config.
"OMNIROUTE_EVAL_CREDENTIALS",
// Build-time only: set by `build:release` (git short SHA) and read by
// write-build-sha.mjs to stamp dist/BUILD_SHA — injected by the build, never
// configured by users in .env.
"OMNIROUTE_BUILD_SHA",
// Listener-owned self-fetch transport signal. The HTTP/HTTPS launchers set
// this before application imports; it is not user-configurable product env.
"OMNIROUTE_INTERNAL_SCHEME",
// Runner-owned bind-host signal. scripts/dev/run-next.mjs publishes the
// interface it actually binds so the in-process startup guard can name it
// (#13695); operators configure HOST / HOSTNAME, never this.
"OMNIROUTE_BOUND_HOST",
// Source typo / placeholder.
"OMNIROUT",
// Static config alias path (the canonical var is OMNIROUTE_PAYLOAD_RULES_PATH).
"PAYLOAD_RULES_PATH",
// Node.js module resolution path — OS/Node internal, not an OmniRoute config var.
// Referenced in resolveSpawnArgs (ninerouter) to pass bundled native modules to subprocess.
"NODE_PATH",
// NVIDIA diagnostic/test helpers used only by ad-hoc scripts.
"NVIDIA_BASE_URL",
"NVIDIA_MODEL",
// Live smoke check for the claude-mem memory backend (scripts/ad-hoc/claude-mem-live-check.ts,
// #15425) — port of the operator's local claude-mem worker. The backend itself is configured
// through settings.backendConfigs["claude-mem"].port, never this env var.
"CLAUDE_MEM_PORT",
// Lemonade embedding-provider integration test (tests/integration/semantic-cache-lemonade.test.ts)
// — points the gated live test at an operator's local Lemonade server; the test skips itself
// when the endpoint is unreachable, never OmniRoute runtime config.
"LEMONADE_URL",
"LEMONADE_KEY",
"LEMONADE_MODEL",
// Discord integration ad-hoc script (scripts/ad-hoc/mesh-send.mjs) —
// operator-supplied bot credentials, not user-facing OmniRoute config.
"BOT_TOKEN",
"BOT_URL",
// XDG standard data directory — set by OS/desktop session, not OmniRoute config.
// Read by setup-open-code.mjs to locate platform-specific OpenCode data dir.
"XDG_DATA_HOME",
// Test-only override: points setup-open-code.mjs at a fixture plugin dir without
// requiring the real bundled plugin to be built.
"OMNIROUTE_OPENCODE_PLUGIN_DIR",
// Test-only escape hatch: makes getMachineIdRaw() skip the macOS ioreg strategy so
// machineId tests reach the fallback strategies on darwin (#13539). Not user config.
"DISABLE_IOREG_STRATEGY",
// Next.js-internal switch, not OmniRoute config: scripts/dev/standalone-server-ws.mjs sets it
// so Next skips its own SIGINT/SIGTERM handlers and the wrapper owns shutdown.
"NEXT_MANUAL_SIG_HANDLE",
]);
// Vars documented in ENVIRONMENT.md but intentionally absent from .env.example.
// Used for past-tense documentation (Audit / Dead vars section), legacy aliases
// with no runtime hook, and section anchors that look like vars to the regex.
const DOC_ONLY_ALLOWLIST = new Set([
// Audit history (Removed / Dead Variables section).
"CEREBRAS_API_KEY",
"COHERE_API_KEY",
"FIREWORKS_API_KEY",
"GROQ_API_KEY",
"MISTRAL_API_KEY",
"NEBIUS_API_KEY",
"PERPLEXITY_API_KEY",
"TOGETHER_API_KEY",
"XAI_API_KEY",
"QIANFAN_API_KEY",
"CURSOR_PROTOBUF_DEBUG",
"CLI_COMPAT_KIRO",
"CLI_KIMI_CODING_BIN",
"CLI_ROO_BIN",
"IFLOW_OAUTH_CLIENT_ID",
"IFLOW_OAUTH_CLIENT_SECRET",
// Source-code constants accidentally captured by the doc regex.
"CLI_COMPAT_OMITTED_PROVIDER_IDS",
// The stream-recovery tuning object in open-sse/config/constants.ts (`STREAM_RECOVERY.HOLDBACK_MS`
// etc.) — documented for reference; the real operator-facing env vars are STREAM_RECOVERY_ENABLED /
// STREAM_RECOVERY_MIDSTREAM_ENABLED (both in .env.example). The bare prefix is not an env var.
"STREAM_RECOVERY",
// Sample default values that look like SHOUTY_NAMES (not env vars).
"CHANGEME",
// Legacy aliases — present in docs as "would be aliases" but read-only
// through their canonical names today.
"OMNIROUTE_CRYPT_KEY",
"OMNIROUTE_API_KEY_BASE64",
// Future-supported hooks: documented but currently hardcoded constants.
"MAX_RETRY_INTERVAL_SEC",
"REQUEST_RETRY",
"SKILLS_EXECUTION_TIMEOUT_MS",
"SKILLS_SANDBOX_DOCKER_IMAGE",
// Source-code constants referenced in the docs narrative for the local
// endpoints / route-guard classification (PR-3 in #3932).
"LOCAL_ONLY_API_PREFIXES",
// SQL keyword mentioned in the new VACUUM scheduler docs (#4437).
// The check's regex picks up the bare word in description text.
"VACUUM",
// Source-code constant (open-sse/services/combo/comboPredicates.ts:35 —
// `export const COMBO_LOOP_SAFETY_TIMEOUT_MS = 10 * 60 * 1000`), cited in the
// comboTimeoutMs narrative added by #13857. Not operator-configurable.
"COMBO_LOOP_SAFETY_TIMEOUT_MS",
]);
// Vars present in .env.example but intentionally absent from ENVIRONMENT.md.
// Empty today — kept for forward compatibility / explicit exemption.
const ENV_ONLY_ALLOWLIST = new Set([
// Documented in .env.example but not yet in docs/reference/ENVIRONMENT.md
"CODEX_REFRESH_SPACING_MS",
"DEBUG",
"HEAP_PRESSURE_THRESHOLD_MB",
"OMNIROUTE_TRACE",
"PII_TEST_BYPASS_MIN_WINDOW",
"PII_WINDOW_SIZE",
"TRAE_STREAM_TIMEOUT_MS",
"TRAE_TOKEN",
// #12190: Trae host/Origin override. ENVIRONMENT.md documents no Trae variable at
// all; this joins its two siblings above under the same .env.example-only tier.
"TRAE_WEB_ORIGIN",
]);
// ─── Parsing helpers ───────────────────────────────────────────────────────
/**
* Extract VAR= entries from a `.env`-style file (handles commented examples).
*/
export function parseEnvExampleVars(text) {
const vars = new Set();
for (const line of String(text ?? "").split("\n")) {
const m = line.match(/^#?\s*([A-Z][A-Z0-9_]+)\s*=/);
if (m) vars.add(m[1]);
}
return vars;
}
/**
* Extract `VARNAME` tokens from a markdown doc — matches anything in backticks
* that looks like an env var (uppercase + digit + underscore).
*/
export function parseEnvDocVars(text) {
const vars = new Set();
for (const m of String(text ?? "").matchAll(/`([A-Z][A-Z0-9_]{2,})`/g)) {
vars.add(m[1]);
}
return vars;
}
/** Roots scanned for `process.env.X` references, relative to the repo root. */
export const CODE_SCAN_ROOTS = [
"src",
"open-sse",
"bin",
"scripts",
"electron/main.js",
"electron/preload.js",
];
const CODE_ENV_REF = /process\.env\.([A-Z][A-Z0-9_]+)/g;
/**
* Collect environment variable references in source code.
*
* Pure Node on purpose. This used to shell out to
* `grep -rhoE … 2>/dev/null || true`; on Windows that line runs through cmd.exe,
* where `2>/dev/null` is an invalid path, so the command printed an error,
* `|| true` swallowed it, and the scan returned ZERO variables — the
* "in code but missing from .env.example" check then passed vacuously.
*
* Mirrors the grep it replaces: recursive, symlinks not followed, files that
* contain a NUL byte (binary) skipped, missing roots ignored.
*
* @param {{ cwd?: string, roots?: readonly string[] }} [options]
* @returns {Set<string>}
*/
export function scanCodeVars({ cwd, roots = CODE_SCAN_ROOTS } = {}) {
const repoRoot = cwd ?? REPO_ROOT;
const vars = new Set();
const scanFile = (file) => {
let text;
try {
text = fs.readFileSync(file, "utf8");
} catch {
return;
}
if (text.includes("\0")) return;
for (const m of text.matchAll(CODE_ENV_REF)) vars.add(m[1]);
};
const walk = (dir) => {
let entries;
try {
entries = fs.readdirSync(dir, { withFileTypes: true });
} catch {
return;
}
for (const entry of entries) {
const full = path.join(dir, entry.name);
if (entry.isDirectory()) walk(full);
else if (entry.isFile()) scanFile(full);
}
};
for (const root of roots) {
const full = path.join(repoRoot, root);
let stat;
try {
stat = fs.lstatSync(full);
} catch {
continue;
}
if (stat.isDirectory()) walk(full);
else if (stat.isFile()) scanFile(full);
}
return vars;
}
/**
* Diff helper.
*/
function diff(set, against) {
return [...set].filter((v) => !against.has(v)).sort((a, b) => a.localeCompare(b));
}
// ─── Programmatic entry point ──────────────────────────────────────────────
/**
* Run the contract checker. All inputs are overridable for tests.
*
* Returns `{ ok: boolean, summary, problems: { codeMissingEnv, envMissingDoc,
* docMissingEnv } }`.
*/
export function runEnvDocSync(options = {}) {
const ignore = options.ignore ?? IGNORE_FROM_CODE;
const docOnly = options.docOnlyAllowlist ?? DOC_ONLY_ALLOWLIST;
const envOnly = options.envOnlyAllowlist ?? ENV_ONLY_ALLOWLIST;
const envExampleText =
options.envExampleText ??
(options.envExamplePath
? fs.readFileSync(options.envExamplePath, "utf8")
: fs.readFileSync(path.join(REPO_ROOT, ".env.example"), "utf8"));
const envDocText =
options.envDocText ??
(options.envDocPath
? fs.readFileSync(options.envDocPath, "utf8")
: fs.readFileSync(path.join(REPO_ROOT, "docs", "reference", "ENVIRONMENT.md"), "utf8"));
const envVars = parseEnvExampleVars(envExampleText);
const docVars = parseEnvDocVars(envDocText);
const codeVars = new Set(
[...(options.codeVars ?? scanCodeVars({ cwd: options.root }))].filter((v) => !ignore.has(v))
);
const codeMissingEnv = diff(codeVars, envVars);
const envMissingDoc = diff(envVars, docVars).filter((v) => !envOnly.has(v));
const docMissingEnv = diff(docVars, envVars).filter((v) => !docOnly.has(v));
const ok =
codeMissingEnv.length === 0 && envMissingDoc.length === 0 && docMissingEnv.length === 0;
return {
ok,
summary: {
code: codeVars.size,
envExample: envVars.size,
doc: docVars.size,
},
problems: {
codeMissingEnv,
envMissingDoc,
docMissingEnv,
},
};
}
// ─── CLI ───────────────────────────────────────────────────────────────────
function printList(label, list, marker) {
if (list.length === 0) {
console.log(` ${marker || "✓"} ${label}: none`);
return;
}
console.log(` ✗ ${label}: ${list.length}`);
for (const v of list.slice(0, 50)) console.log(` - ${v}`);
if (list.length > 50) console.log(` ... and ${list.length - 50} more`);
}
function main() {
const lenient = process.argv.includes("--lenient");
const result = runEnvDocSync();
console.log("Env var contract sync report");
console.log("============================");
console.log(`Code references: ${result.summary.code} unique vars`);
console.log(`In .env.example: ${result.summary.envExample} unique vars`);
console.log(`In docs/reference/ENVIRONMENT.md: ${result.summary.doc} unique vars`);
console.log();
printList("In code but missing from .env.example", result.problems.codeMissingEnv);
printList("In .env.example but missing from ENVIRONMENT.md", result.problems.envMissingDoc);
printList("In ENVIRONMENT.md but missing from .env.example", result.problems.docMissingEnv);
if (result.ok) {
console.log("\n✓ Env / docs contract is in sync.");
process.exit(0);
}
if (lenient) {
console.log("\n⚠ Drift detected (lenient mode — exit 0).");
process.exit(0);
}
console.log(
"\n✗ Env / docs contract is out of sync. Update .env.example, docs/reference/ENVIRONMENT.md,"
);
console.log(" or the allowlists in scripts/check/check-env-doc-sync.mjs and try again.");
process.exit(1);
}
/**
* True when this module was launched directly as the Node entry point.
*
* `process.argv[1]` is an absolute filesystem path while `import.meta.url` is a
* file URL, so the two only match when encoded through `pathToFileURL`. A raw
* `file://${argv[1]}` comparison silently never matches when the checkout path
* contains characters the URL form percent-encodes (e.g. a space), which made
* the CLI exit 0 without running anything.
*/
export function isMainEntry(argv1, moduleUrl) {
if (!argv1) return false;
try {
return pathToFileURL(argv1).href === moduleUrl;
} catch {
return false;
}
}
if (isMainEntry(process.argv[1], import.meta.url)) {
main();
}