mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-07-26 09:52:11 +03:00
68e4d0c599
* chore(release): open v3.8.19 development cycle * chore(release): sync electron lockfile to 3.8.19 * feat(quality): quality-gate ratchet + anti-hallucination/rule-enforcement guardrails (Phases 0-6) (#3471) * feat(quality): generic ratchet comparator (multi-metric, regression-only) * chore(ci): Fase 0 quality-gate fixes — reconcile coverage gate (40->60), tier npm audit, wire orphaned contract gates, re-enable cheap husky pre-commit * feat(quality): ratchet engine (collector + frozen baseline + CI job) and provider-consistency gate - collect-metrics.mjs: emits quality-metrics.json (ESLint warnings + coverage when present) - quality-baseline.json: frozen baseline (eslintWarnings=3482, regression-only) - ci.yml: quality-gate job (ratchet + step summary + artifact) and check:provider-consistency in lint job - check-provider-consistency.ts: every REGISTRY id must be a canonical provider (found krutrim half-registered → allowlisted as known pre-existing, blocks any NEW orphan) - TDD: 9 tests (5 ratchet + 4 provider-consistency) * feat(quality): Fase 2 anti-hallucination gates — fetch-targets, openapi-routes, deps allowlist - check-fetch-targets: every dashboard fetch(/api/...) resolves to a real route.ts; found 7 pre-existing dashboard->route mismatches frozen as KNOWN_MISSING for triage - check-openapi-routes: every openapi.yaml path resolves to a real route; found 1 stale spec entry (agent-bridge agents/{id}/state) frozen as KNOWN_STALE_SPEC - check-deps: anti-slopsquatting allowlist (105 deps); new deps need explicit human-reviewed entry - all wired into CI lint/docs jobs; TDD +12 tests (21 total across 5 gates) * docs(quality): add quality-gates report + implementation plan to repo root * feat(quality): Fase 3a — file-size ratchet (freeze 91 files >800 LOC, cap 800 for new) - check-file-size.mjs: frozen files can only shrink; new files must be <= cap (kills the next 12k-line god-component) - file-size-baseline.json: 91 files frozen at current LOC (largest 12883) - wired into CI lint job; TDD 5 tests; --update ratchets the baseline down on shrink * feat(quality): Fase 3b — duplication ratchet (jscpd@4, baseline 5.72%) - check-duplication.mjs: runs jscpd@4 (pinned; v5 is an incompatible Rust rewrite) over src+open-sse, fails if duplication % rises vs frozen baseline (5.72%, measured: 1358 clones / 22967 dup lines). Targets the executor copy-paste (48/50 override execute() wholesale) - wired into the parallel quality-gate CI job (off the lint critical path); TDD 4 tests; --update ratchets down - snapshot now complete: coverage ~82.6%, eslint 3482 (98.5% no-explicit-any), duplication 5.72%, 91 files >800 LOC * feat(quality): Fase 4a — anti test-masking gate - check-test-masking.mjs: for each MODIFIED test file in a PR, flags net assert removal + new assert.ok(true) tautologies (base...HEAD diff). Directly enforces CLAUDE.md 'never weaken asserts to go green' - wired into pr-test-policy CI job (reuses base fetch); no-op outside PR; TDD 5 tests * feat(quality): Fase 4b — coverage ratchet (conservative floors, CI consumes merged coverage) - quality-baseline.json: coverage.{statements,lines,functions,branches} floors (80/80/82/73, real ~82.58/82.58/84.23/75.22 with margin; tighten via --update after a green main run) - check-quality-ratchet.mjs: --allow-missing (local quality:gate skips coverage.* without a coverage run; CI runs strict) - ci.yml quality-gate job: needs test-coverage + downloads merged coverage-report so the ratchet enforces 'coverage cannot drop' - TDD +1 test (6 total) * feat(quality): Fase 6 — 8 new gates (Rule #11/#12, migrations, known-symbols, route-guard, complexity, docs-symbols, db-rules) Deterministic gates, each freezing pre-existing violations in a documented allowlist (ratchet) so they pass now and block only NEW regressions: - check-error-helper (Rule #12): 7 executors/handlers forwarding raw err.message frozen - check-public-creds (Rule #11): 5 literal client_ids (Claude/Codex/Qwen/Kimi/Copilot) frozen - check-migration-numbering: gaps 026/055 + dup 041 frozen (prevents the git-rm-deleted-migration incident) - check-known-symbols: 93 executors conformance + 15 combo strategies + 18 translator pairs - check-route-guard-membership (#15/#17): all 25 spawn-capable routes verified local-only (0 gaps) - check-complexity: cyclomatic>15 / fn-length>80 ratchet (baseline 1739) - check-docs-symbols: 30 stale doc /api refs frozen (docs hallucination) - check-db-rules (#2/#5): 25 unexported db modules + 15 raw-SQL routes frozen Wired into CI (lint / docs-sync-strict / quality-gate jobs). 115 TDD tests, all green. ESLint ratchet held at 3482. * docs(quality): Phase 7 plan (security/dead-code/mutation/community tooling) — GATED to 2026-06-16 Stored, not active. 7 suggested gates + all discussed OSS/Community tools (SonarQube Community + osv-scanner + CodeQL + knip + sonarjs + type-coverage + lockfile-lint + Stryker + size-limit + axe-core + semcheck + agent-lsp + Qlty). Activation gate: do not start before 2026-06-16 (use Phases 0-6 in production for 1 week, validate in practice, then evolve). * docs(quality): Phase 6A critical-audit plan + Phase 7 additions — gated to 2026-06-16 (#3530) PLANO-QUALITY-GATES-FASE6A.md (12-task audit of Phases 0-6: orphan tests, stale-allowlist enforcement, scope gaps) + Phase 7 additions (gitleaks, actionlint+zizmor, license compliance). Both stored, activation gated to 2026-06-16. Tasks 6A.1/6A.2 were fast-tracked separately (#3536). * feat(quality): 6A.1+6A.2 — test-discovery gate, 135 orphan tests re-wired, 2 production bug fixes, vitest in CI (#3536) check-test-discovery gate (TDD; 195 orphans found, 135 re-wired into the node runner, 60 frozen+annotated). Triage fixed 2 real production bugs: missing BYPASS_PREFIX_NOT_ALLOWED zod refine (spawn-capable prefixes accepted into the bypass list, Hard Rules #15/#17) and resetDbInstance not firing stateReset resetters (stale schema memo → 503 instead of 403; also hit backup-restore). New test-vitest CI job: test:vitest blocking (146/146), test:vitest:ui informational (14 pre-existing fails, triage 2026-06-16). * chore: ignore generated yt-downloader artifact files Add dated yt-downloader output files to .gitignore to prevent local automation artifacts from being accidentally committed. * chore(quality): green-light the quality-gate — conscious file-size + eslintWarnings re-baselines (#3538) file-size: 9 files frozen at current sizes (v3.8.18-era growth + core.ts +7 from #3536 fix). eslintWarnings 3482→3501: the published v3.8.18 tag already measures 3501 (delta predates the quality-gate job); v3.8.19 cycle is neutral. Reduction + --require-tighten = Phase 6A (2026-06-16). * fix(check): exclude internal planning docs (docs/superpowers/) from the docs-symbols gate docs/superpowers/plans/*.md are historical implementation-plan snapshots that may cite planned/abandoned routes — not claims about the current code. Three such refs entered during the v3.8.18 cycle, before this gate was on the pipeline, and would have blocked the v3.8.19 release merge. * chore(release): v3.8.19 — 2026-06-09 CHANGELOG section for the quality-infrastructure release (7 commits, 1:1 coverage), [3.8.18] label corrected to its real release date, local prompt artifacts ignored. * test: hermetic auth context for 2 re-wired suites + real headroom on the breaker reset-timeout flake CI shards exposed what the dev DATA_DIR was masking locally: detect.test.ts and managementCliToken.test.ts asserted 401/403/reject outcomes that only exist when login protection is configured — on a fresh CI DB isAuthRequired() is false and the policy anonymous-allows. Both now create an isolated DATA_DIR with requireLogin+password (the established pattern). observability-fase04: the breaker reset-timeout test ran with a 5ms margin (resetTimeout 10 / sleep 15) — lazy HALF_OPEN refresh under shard contention flipped the first OPEN assert. Now 250/300ms. * test: align bypass-prefix schema test to the restored layer-1 contract + real waitFor headroom appearance-widget-settings-schema asserted that /api/cli-tools/runtime/ was ACCEPTED into the bypass list — written against the buggy schema (missing BYPASS_PREFIX_NOT_ALLOWED refine, restored in #3536) and consecrating the bug the AC-8 orphan test guards against. Split into accept-safe + reject-spawn-capable cases. chatcore waitFor ceiling 1500→10000ms (green runs return immediately; observed 1580ms expiry on 2-core CI runners). * test(chatcore): fix structurally-broken pending-detail predicate (flatten before find) pendingRequests.details[connectionId] is Record<modelKey, PendingRequestDetail[]> — the upstream-timeout test's waitFor tested each ARRAY's .providerRequest (always undefined), so it could never resolve and expired (failed on 3 CI jobs; reproduced deterministically isolated, including at the published v3.8.18 tag). Flatten to the actual details + declare the call_log_pipeline_enabled dependency explicitly + waitFor ceiling with real CI headroom. * chore(quality): re-baseline coverage floors to the honest post-re-wire denominator + changelog coverage for the stabilization commits The 135 re-wired tests import modules that were never loaded before, so the c8 denominator grew: the old ~82.5% was inflated by never-imported modules being invisible. CI merged coverage now measures 78.4/78.4/83.84/75.73 — floors set ~2pt below (76.5/76.5; functions/branches floors already hold). Tightening via --require-tighten is Phase 6A work (2026-06-16).
title, version, lastUpdated
| title | version | lastUpdated |
|---|---|---|
| OmniRoute Documentation | 3.8.2 | 2026-05-13 |
OmniRoute Documentation
Navigable index of the OmniRoute documentation set. Topics are grouped by intent so you can find what you need quickly.
Looking for the project overview, install steps, or release notes? See the root README.md, CHANGELOG.md, and CONTRIBUTING.md.
architecture/
How the system is put together — read these to understand the runtime, code layout, and resilience model.
- ARCHITECTURE.md — high-level system architecture (request pipeline, layers, modules).
- CODEBASE_DOCUMENTATION.md — engineering reference for the codebase.
- REPOSITORY_MAP.md — directory-by-directory navigation guide.
- AUTHZ_GUIDE.md — authorization pipeline (route classifier + policy engine).
- RESILIENCE_GUIDE.md — provider circuit breaker, connection cooldown, and model lockout.
For Non-Tech Users
Simple guides for using OmniRoute — no technical background needed.
getting-started/
- QUICK-START.md — install and run OmniRoute in 3 minutes.
- AUTO-COMBO-GUIDE.md — let OmniRoute pick the best AI for you.
- PROVIDERS-GUIDE.md — how to connect AI providers.
- FREE-TIERS-GUIDE.md — get free AI with no credit card.
- TROUBLESHOOTING.md — fix common issues.
guides/
- SETUP_GUIDE.md — first-time setup of OmniRoute.
- USER_GUIDE.md — daily usage of the dashboard and API.
- DOCKER_GUIDE.md — running OmniRoute under Docker.
- ELECTRON_GUIDE.md — desktop (Electron) builds.
- TERMUX_GUIDE.md — running on Android via Termux.
- PWA_GUIDE.md — installing the dashboard as a PWA.
- UNINSTALL.md — clean removal steps.
- I18N.md — translation and locale workflow.
- FEATURES.md — dashboard feature gallery.
For Tech Users
Technical documentation for developers and contributors.
architecture/
Lookup material — API surface, environment variables, CLI flags, provider catalog.
- API_REFERENCE.md — REST API endpoints and shapes.
- PROVIDER_REFERENCE.md — auto-generated provider catalog.
- openapi.yaml — OpenAPI 3.1 spec for the public API.
- ENVIRONMENT.md — environment variables reference.
- CLI-TOOLS.md — bundled CLI commands.
- FREE_TIERS.md — free-tier LLM provider directory.
frameworks/
Pluggable subsystems exposed to clients, agents, and operators.
- MCP-SERVER.md — Model Context Protocol server.
- A2A-SERVER.md — Agent-to-Agent (A2A) JSON-RPC server.
- AGENT_PROTOCOLS_GUIDE.md — A2A / ACP / Cloud agent overview.
- CLOUD_AGENT.md — cloud agent runtime and providers.
- SKILLS.md — Skills framework (sandboxed extension).
- MEMORY.md — persistent memory (FTS5 + Qdrant).
- WEBHOOKS.md — webhook events and dispatch.
- EVALS.md — eval suites.
routing/
Combo routing, scoring, and replay.
- AUTO-COMBO.md — Auto-Combo (9-factor scoring, 14 strategies).
- REASONING_REPLAY.md — reasoning replay flow.
security/
Guardrails, compliance, stealth, and the mandatory patterns for handling public credentials and error messages.
- GUARDRAILS.md — PII, prompt injection, vision guardrails.
- COMPLIANCE.md — audit trails and compliance.
- STEALTH_GUIDE.md — TLS / fingerprint stealth.
- PUBLIC_CREDS.md — mandatory pattern for embedding public upstream OAuth client_id/secret + Firebase Web keys without tripping secret scanners.
- ERROR_SANITIZATION.md — mandatory pattern for routing every error response through
sanitizeErrorMessageto prevent stack-trace exposure.
compression/
Prompt compression engines, rules, and language packs.
- COMPRESSION_GUIDE.md — top-level compression overview.
- COMPRESSION_ENGINES.md — available compression engines.
- COMPRESSION_RULES_FORMAT.md — rule file format.
- COMPRESSION_LANGUAGE_PACKS.md — language packs.
- RTK_COMPRESSION.md — RTK engine deep dive.
ops/
Release, deployment, proxies, tunnels, coverage.
- RELEASE_CHECKLIST.md — release flow checklist.
- COVERAGE_PLAN.md — test coverage plan.
- FLY_IO_DEPLOYMENT_GUIDE.md — Fly.io deployment.
- VM_DEPLOYMENT_GUIDE.md — generic VM deployment.
- PROXY_GUIDE.md — upstream proxy configuration.
- TUNNELS_GUIDE.md — Cloudflare tunnel and friends.
diagrams/
Mermaid sources and exported SVG/PNG diagrams referenced from the docs above. Populated incrementally — see diagrams/README.md.
i18n/
Translated mirrors of the documentation in 40 locales. See i18n/README.md for the supported language list.
screenshots/
Static screenshots used by the dashboard and the README. Not part of the doc body.
Auto-generated artifacts
- reference/PROVIDER_REFERENCE.md is generated by
scripts/docs/gen-provider-reference.tsfromsrc/shared/constants/providers.ts. Do not edit by hand. - The
/docsUI is backed by Fumadocs MDX source generation from the subfolders above.