mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-11-18 07:58:27 +00:00
* feat(server): headless mode gate for dashboard routes and optional boot subsystems
OMNIROUTE_HEADLESS=1 boots only the proxy engine. A single helper
(src/lib/system/headless.ts) drives two gates:
- route gate in src/proxy.ts: /dashboard, /dashboard/*, /home, /home/*
answer 404 {"error":"dashboard disabled (headless)"} before the authz
pipeline; /v1/*, /api/monitoring/health and /api/auth/* are untouched.
- boot gate in src/instrumentation-node.ts: the optional subsystems of the
background block move into OPTIONAL_BOOT_SUBSYSTEMS, started through
startOptionalBootSubsystems() (skipped as a whole when headless); the
free-proxy sync and cloud sync serial steps use skipInHeadless(). No init
code is removed; proxy-core work (token auto-refresh, cooldown recovery,
context-window reconcile, backup schedule) stays inline in both modes.
* feat(cli): omniroute serve --headless sets OMNIROUTE_HEADLESS=1 on the server
The flag reaches the server process through the same child env that
carries --port (applyHeadlessServeEnv). Headless runs skip the automatic
browser open, print 'Dashboard: disabled (headless)' in the banners, and
reject --tray (the tray exists to open the dashboard). New CLI string
serve.headless added to all 67 CLI locales.
* docs(server): headless mode guide and OMNIROUTE_HEADLESS env reference
docs/guides/HEADLESS.md covers what stays on, what is switched off, curl
checks and limits; linked from docs/README.md and the guides nav. The
variable is documented in .env.example and docs/reference/ENVIRONMENT.md.
* fix(headless): keep the memory subsystems running in headless mode
Memory is cross-cutting to the request pipeline (/v1 injects and queries
memory), so memory-backends and memory-decay-sweep leave the
OPTIONAL_BOOT_SUBSYSTEMS table and return to the inline core boot path in
registerNodejs() (same position as on the base branch), running in both
modes. The test now asserts both stay out of the headless-skipped table and
start inline; HEADLESS.md lists memory as staying on.
bin/cli — OmniRoute CLI internals
This directory contains the CLI runtime, helpers, and commands for the omniroute binary.
Structure
bin/cli/
├── CONVENTIONS.md ← normative design rules (read this first)
├── README.md ← this file
├── program.mjs ← Commander setup — global flags, registerCommands()
├── api.mjs ← apiFetch() — all HTTP calls + retry/backoff
├── runtime.mjs ← withRuntime() — server-first / DB-fallback
├── i18n.mjs ← t() — i18n helper + locale detection
├── output.mjs ← emit() — table/json/jsonl/csv + printSuccess/printError
├── io.mjs ← ask() / askSecret() — interactive prompts
├── data-dir.mjs ← resolveDataDir() / resolveStoragePath()
├── sqlite.mjs ← openOmniRouteDb() — DB bootstrap
├── encryption.mjs ← encrypt/decrypt credentials
├── provider-catalog.mjs ← static provider catalog
├── provider-store.mjs ← DB CRUD for provider_connections
├── provider-test.mjs ← testProviderApiKey()
├── settings-store.mjs ← DB CRUD for key_value settings
├── locales/
│ ├── en.json ← English strings (source of truth, 42 locales)
│ ├── pt-BR.json ← Portuguese (Brazil) — fully translated
│ └── {locale}.json ← 41 additional locales (ar, az, de, es, fr, ja, zh-CN, …)
├── scripts/
│ └── generate-locales.mjs ← scaffold new locale files from config/i18n.json
└── commands/
├── setup.mjs
├── doctor.mjs
├── providers.mjs
├── config.mjs ← includes `config lang get/set/list`
├── status.mjs
├── logs.mjs
└── update.mjs
Key helpers
apiFetch(path, opts) — api.mjs
All HTTP calls to the OmniRoute server must go through this wrapper.
import { apiFetch } from "./api.mjs";
const res = await apiFetch("/api/health");
if (!res.ok) await res.assertOk(); // throws ApiError with mapped exit code
const data = await res.json();
Options:
baseUrl— override base URL (default:OMNIROUTE_BASE_URLenv orlocalhost:20128)apiKey— override API key (default:OMNIROUTE_API_KEY)method,body,headers— standard fetch optionstimeout— per-attempt ms (default:30000)retry—falseto disable (default: enabled)retryMax— total attempts (default:3)verbose— log retry attempts to stderr
withRuntime(fn, opts) — runtime.mjs
Provides server-first / DB-fallback transparently.
import { withRuntime } from "./runtime.mjs";
await withRuntime(async (ctx) => {
if (ctx.kind === "http") {
const res = await ctx.api("/v1/providers");
return res.json();
}
return ctx.db.prepare("SELECT * FROM provider_connections").all();
});
opts.requireServer = true— throwsServerOfflineError(exit 3) if offlineopts.preferDb = true— always use DB (skip server check)
t(key, vars) — i18n.mjs
Internationalized strings. Catalog loaded from locales/{locale}.json.
import { t } from "./i18n.mjs";
console.log(t("common.serverOffline"));
console.log(t("setup.testFailed", { error: err.message }));
Locale detection order: OMNIROUTE_LANG → LC_ALL → LC_MESSAGES → LANG → en.
emit(data, opts) — output.mjs
Format-aware output. Reads opts.output to select table/json/jsonl/csv.
import { emit, printError, EXIT_CODES } from "./output.mjs";
emit(providers, { output: opts.output ?? "table" });
printError("Something went wrong");
process.exit(EXIT_CODES.SERVER_OFFLINE);
Locale selection
The CLI displays text in the user's language. Detection order:
--lang <code>flag on the command lineOMNIROUTE_LANGenvironment variable- System env:
LC_ALL→LC_MESSAGES→LANG - Fallback:
en
Set permanently:
omniroute config lang set pt-BR # saves to ~/.omniroute/.env
omniroute config lang list # show all 42 available locales
omniroute config lang get # show currently active locale
One-time override:
omniroute --lang de providers list # run in German, not persisted
OMNIROUTE_LANG=ja omniroute status # same effect via env
Adding a new locale: add entry to config/i18n.json, then run:
node bin/cli/scripts/generate-locales.mjs
Adding a new command
- Create
bin/cli/commands/your-command.mjs - Export
registerYourCommand(program)following the Commander pattern - Register in
bin/cli/commands/registry.mjs - Add strings to
locales/en.jsonandlocales/pt-BR.json - Write test in
tests/unit/cli-your-command.test.ts
See CONVENTIONS.md for exit codes, flag naming, output format, and destructive-action rules.