wehub-resource-sync
225 lines
8.7 KiB
Markdown
225 lines
8.7 KiB
Markdown
# OmniRoute CLI — Internal Conventions
|
||
|
||
> Status: normative. Source: `_tasks/features-v3.8.0/cli/fase-0-preparacao/0.3-definir-convencoes.md`.
|
||
> This file is the authoritative reference for every new or migrated CLI command.
|
||
> If reality diverges from this document, fix the code first; only edit this file
|
||
> after the discrepancy has been justified in a PR.
|
||
|
||
## 1. Subcommand style
|
||
|
||
**Standard**: `git`-style nested verbs.
|
||
|
||
```
|
||
omniroute keys add openai sk-xxx
|
||
omniroute combo switch fastest
|
||
omniroute memory search "react hooks"
|
||
```
|
||
|
||
**Not allowed**:
|
||
|
||
```
|
||
omniroute --add-key openai sk-xxx # ❌ flag-as-verb
|
||
omniroute add-key openai sk-xxx # ❌ hyphen at the top level
|
||
```
|
||
|
||
## 2. Flags
|
||
|
||
- Only `--long` and `-s` shorts (one-letter shorts reserved for very common
|
||
flags: `-h`, `-v`, `-o`, `-q`, `--no-open`).
|
||
- Format: `--api-key sk-xxx` (space). `=` accepted for parity but doc uses space.
|
||
- Naming: kebab-case (`--api-key`, `--non-interactive`, `--max-tokens`).
|
||
- Booleans: `--no-foo` (negative) and `--foo` (positive). Default `false` unless
|
||
documented.
|
||
- Multi-value: repeat the flag (`--header X-A=1 --header X-B=2`).
|
||
|
||
## 3. Output (`--output`)
|
||
|
||
| Value | Use case |
|
||
| ------- | -------------------------------------------- |
|
||
| `table` | default human-readable |
|
||
| `json` | single JSON object, pretty-printed |
|
||
| `jsonl` | streamed objects, one per line (logs, lists) |
|
||
| `csv` | spreadsheet ingestion |
|
||
|
||
Related flags:
|
||
|
||
- `--quiet` / `-q` — suppress headers/spinners (pipe-friendly).
|
||
- `--no-color` — force ANSI off (auto-detected if `!stdout.isTTY`).
|
||
|
||
Helper: `emit(rows, opts)` from `bin/cli/output.mjs` handles all four formats.
|
||
|
||
## 4. Exit codes
|
||
|
||
| Code | Meaning |
|
||
| ----- | --------------------------------- |
|
||
| `0` | success |
|
||
| `1` | generic error (uncaught, runtime) |
|
||
| `2` | invalid argument / misuse |
|
||
| `3` | server offline (when required) |
|
||
| `4` | auth / permission (401/403) |
|
||
| `5` | rate limit / quota (429) |
|
||
| `124` | timeout |
|
||
|
||
Helper: `exitWith(code, message?)` from `bin/cli/exit.mjs` (added under
|
||
`output.mjs` if needed) — always uses these constants. **Never** raw
|
||
`process.exit(N)` in command code.
|
||
|
||
## 5. HTTP errors + retry/backoff
|
||
|
||
All API calls go through `apiFetch(path, opts)` (`bin/cli/api.mjs`), which:
|
||
|
||
- Reads base URL from `OMNIROUTE_BASE_URL` env or `~/.omniroute/config.json`
|
||
(active profile).
|
||
- Injects `Authorization: Bearer ${OMNIROUTE_API_KEY}` when available.
|
||
- Injects `x-omniroute-cli-token` when applicable (see task 8.12).
|
||
- Applies a per-attempt timeout (`--timeout 30000`, default 30s).
|
||
- Maps status → exit code (401→4, 429→5, 5xx→1, etc.).
|
||
- Never exposes `err.stack` (CLAUDE.md hard rule #12).
|
||
- Applies exponential backoff with jitter on retryable statuses.
|
||
|
||
### Retry defaults
|
||
|
||
```js
|
||
export const RETRY_DEFAULTS = {
|
||
maxAttempts: 3, // 1 initial + 2 retries
|
||
baseMs: 500,
|
||
maxMs: 8000, // jitter can slightly exceed
|
||
jitter: true, // ±25%
|
||
retryableStatuses: [408, 425, 429, 502, 503, 504],
|
||
retryableErrorCodes: [
|
||
"ECONNRESET",
|
||
"ECONNREFUSED",
|
||
"ETIMEDOUT",
|
||
"ENOTFOUND",
|
||
"EAI_AGAIN",
|
||
"EPIPE",
|
||
],
|
||
};
|
||
```
|
||
|
||
### Global flags wired
|
||
|
||
- `--retry` (default on) / `--no-retry`
|
||
- `--retry-max <n>` (default 3) — total attempts
|
||
- `--timeout <ms>` (default 30000) — per attempt
|
||
- `--retry-on <csv>` — extra retryable statuses (e.g. `--retry-on 500`)
|
||
|
||
### Method semantics
|
||
|
||
- Mutations (`POST`/`PUT`/`DELETE`) retry **only** on idempotent-ish statuses
|
||
(`502`/`503`/`504`/`408`/network), never `409`/`422`. This avoids duplicate
|
||
side-effects.
|
||
- `GET` retries all `RETRY_DEFAULTS.retryableStatuses`.
|
||
- SSE / streaming does **not** auto-retry (operator decides).
|
||
- Optional `--idempotency-key <uuid>` for extra-safe mutations.
|
||
|
||
### Status → exit code map
|
||
|
||
| Status | Exit | Retry? |
|
||
| --------------- | ---- | ------------------------------ |
|
||
| 200–299 | 0 | n/a |
|
||
| 400 | 2 | no |
|
||
| 401 | 4 | no |
|
||
| 403 | 4 | no |
|
||
| 404 | 2 | no |
|
||
| 408 | 124 | **yes** |
|
||
| 409 | 1 | no (mutations) |
|
||
| 422 | 2 | no |
|
||
| 425 | 1 | **yes** |
|
||
| 429 | 5 | **yes** (respects Retry-After) |
|
||
| 500 | 1 | configurable (default no) |
|
||
| 502 / 503 / 504 | 1 | **yes** |
|
||
| Network errors | 1 | **yes** |
|
||
| Timeout | 124 | **yes** |
|
||
|
||
## 6. Internationalization
|
||
|
||
- Every user-facing string goes through `t("module.key", vars)`.
|
||
- Catalogs live in `bin/cli/locales/{locale}.json` (nested objects).
|
||
42 files ship out-of-the-box: `en`, `pt-BR`, and 40 additional locales.
|
||
11 locales are scaffold-only (empty `{}`); all keys fall back to `en` automatically.
|
||
- Detection order: `--lang` flag → `OMNIROUTE_LANG` env → `LC_ALL` → `LC_MESSAGES` → `LANG` → `en`.
|
||
- Locale persisted via `config lang set <code>` — saves `OMNIROUTE_LANG` to `~/.omniroute/.env`.
|
||
- Missing keys return the key itself (no crash).
|
||
- PRs that add new strings **must** update `en.json` and `pt-BR.json`.
|
||
Other locale files are best-effort; missing keys silently fall back to `en`.
|
||
- `normalize()` in `i18n.mjs` validates locale codes via `/^[a-zA-Z0-9-]+$/` to
|
||
prevent path traversal — never pass raw filesystem paths.
|
||
- Canonical locale list: `config/i18n.json` — source of truth used by both CLI and
|
||
dashboard i18n pipelines.
|
||
|
||
### Adding a new locale file
|
||
|
||
1. Add entry to `config/i18n.json` with `code`, `english`, `native`, `flag`.
|
||
2. Run `node bin/cli/scripts/generate-locales.mjs` — creates `bin/cli/locales/{code}.json`.
|
||
3. Fill in translations (or leave as `{}` for en-fallback scaffold).
|
||
4. The pre-commit hook `check-cli-i18n` will verify all `t()` keys exist in `en.json`.
|
||
|
||
## 7. Logs / output channels
|
||
|
||
- `stdout` — useful output (parseable when `--output json|jsonl|csv`).
|
||
- `stderr` — progress, warnings, errors, spinners.
|
||
- `--verbose` / `-V` — extra detail on stderr.
|
||
- `--debug` — stack traces, request bodies (dev-mode only; redacts secrets).
|
||
|
||
## 8. Server-first / DB-fallback
|
||
|
||
Single helper:
|
||
|
||
```js
|
||
import { withRuntime } from "./runtime.mjs";
|
||
|
||
await withRuntime(async ({ kind, api, db }) => {
|
||
if (kind === "http")
|
||
return api("/api/combos", { retry: false, timeout: 5000, acceptNotOk: true });
|
||
return db.combos.getCombos();
|
||
});
|
||
```
|
||
|
||
- `kind: "http"` when server is up (preferred). `api` is `apiFetch` bound to
|
||
the current profile/base-URL.
|
||
- `kind: "db"` when server is offline. `db` exposes typed module exports:
|
||
- `db.combos` → `src/lib/db/combos.ts` (getCombos, getComboByName, createCombo,
|
||
deleteComboByName, setActiveCombo, …)
|
||
- `db.recovery` → `src/lib/db/recovery.ts` (countEncryptedCredentials,
|
||
resetEncryptedColumns)
|
||
- Mutations that require server **must** error with exit code `3` when the
|
||
server is down, never silently fall back.
|
||
- **Never** write raw SQL in commands — always go through `src/lib/db/` modules.
|
||
The Semgrep rule at `.semgrep/rules/cli-no-sqlite.yaml` enforces this at commit time.
|
||
|
||
## 9. Audit of destructive actions
|
||
|
||
Commands that mutate state (delete, reset, `--force`) **must**:
|
||
|
||
- Ask for interactive confirmation (skipped with `--yes`).
|
||
- POST to `/api/compliance/audit-log` when the server is up.
|
||
- Support `--dry-run` (preview without effect).
|
||
|
||
## 10. Secrets
|
||
|
||
- **Never** log secrets. Mask as `sk-***-xxx` via `maskSecret()` from
|
||
`bin/cli/output.mjs`.
|
||
- **Never** accept a secret via positional without warning. Prefer:
|
||
- env (`OMNIROUTE_*_API_KEY`)
|
||
- stdin (`--api-key-stdin`)
|
||
- interactive `askSecret()` (echo off — already implemented in `io.mjs`)
|
||
- Secrets must not appear in `--verbose` / `--debug` output.
|
||
|
||
## 11. Testing baseline
|
||
|
||
- Every new command ships with at least one smoke test (happy path + one
|
||
error path).
|
||
- Use `tests/unit/cli-*.test.ts` naming. Prefer `node:test` for CLI suites
|
||
(no extra deps).
|
||
- Coverage target: ≥60% for `bin/cli/commands/`, ≥75% for `bin/cli/` overall
|
||
after Fase 8.
|
||
|
||
## 12. References
|
||
|
||
- CLAUDE.md hard rules — especially #11 (publicCreds), #12 (error
|
||
sanitization), #13 (shell injection).
|
||
- `docs/security/ERROR_SANITIZATION.md` — the only acceptable error shapes.
|
||
- `tests/unit/cli-tools-i18n.test.ts` — current i18n infrastructure (pre-`t()`).
|
||
- Commander.js docs — Options & subcommand patterns.
|