diff --git a/ROADMAP.md b/ROADMAP.md index 010e9dd7f..09a08c914 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,42 +1,50 @@ # Roadmap -Roadmap for [OnlineChefGroep/opencodex](https://github.com/OnlineChefGroep/opencodex). +**Independent OnlineChefGroep fork** of upstream opencodex +([lidge-jun/opencodex](https://github.com/lidge-jun/opencodex) as historical source; +canonical product work lives in [OnlineChefGroep/opencodex](https://github.com/OnlineChefGroep/opencodex)). + +For the full audit + phased execution plan, see +[`structure/09_x10-terminal-plan.md`](structure/09_x10-terminal-plan.md). ## Vision A fully self-sufficient fork with our own release cadence, feature set, and quality bar — -no longer dependent on upstream decisions or timelines. +not dependent on upstream decisions or timelines, while retaining a deliberate intake path for +relevant security and compatibility fixes. The operator “terminal” (CLI + GUI + proxy) should +feel 10× less frictional than stock upstream for ChefGroep kitchens. ## Short term (done) -- [x] **Independent versioning** — fully detached from upstream, own semver scheme -- [x] **All closed PRs merged** — Dutch GUI, Claude Desktop, combo/alias, cursor fixes, etc. -- [x] **Enhanced CI** — CodeQL, dependabot, security audit, workflow linting -- [x] **Release process**: main-only publishing via `.github/workflows/release.yml` - and `scripts/release.ts`, with review and promotion policy in `MAINTAINERS.md` - -## Near term (next) - -- [ ] **First fork release (`2.7.43`)**: publish from `main` on npm dist-tag `latest` - (prereleases use `X.Y.Z-preview.N` and ship on `preview`) -- [ ] **Release documentation**: add `VERSIONING.md`, `RELEASE_PROCESS.md`, and - `CHANGELOG.md` for the fork's release model -- [ ] **Update READMEs** — ensure all translated READMEs (ko, zh, ru, ja) reflect fork status -- [ ] **Clean up old tags** — remove stale upstream tags that don't point to our commits -- [ ] **Dependency audit** — review and update all dependencies (gui + root) -- [ ] **TypeScript strict mode** — enable `strict` in tsconfig and fix all violations - -## Medium term - -- [ ] **Custom provider: OnlineChef AI gateway** — first-party provider integration -- [ ] **Performance benchmarks** — proxy latency regression tests in CI -- [ ] **Improved documentation** — deploy docs to GitHub Pages for our fork -- [ ] **Automated dependency upgrades** — Dependabot auto-merge for non-breaking updates -- [ ] **Smoke test suite** — end-to-end tests that spin up the proxy and make real API calls - -## Long term - -- [ ] **Own GUI theme** — custom branding for the dashboard -- [ ] **Plugin system** — third-party provider adapters -- [ ] **Service mode improvements** — better systemd/launchd integration -- [ ] **Multi-host fleet management** — centralized config across machines +- [x] **Fork repository + branch model** — OnlineChefGroep remote; `dev` integration; `main` release +- [x] **Inherited product work on lines** — Dutch/ChefGroep GUI language, Claude Desktop, combos/aliases, Cursor fixes (verify per-branch; reconcile still open) +- [x] **Enhanced CI baseline** — Dependabot, security audit job, actionlint, cross-platform package smoke +- [x] **Release docs scaffolding** — `VERSIONING.md`, `RELEASE_PROCESS.md`, `CHANGELOG.md` +- [x] **Infrastructure lanes started on `dev`** — plugins contract (#40), Prometheus metrics (#42), admission rate-limit (#44/#45), ChefVault provider-security (#38) + +## Near term (next) — Phase 0–1 of x10 plan + +- [ ] **Merge open train** — #51 CI shards → #53 Claude recursive OCX → #52 rate-limit metrics (undraft) +- [ ] **Reconcile `dev` ↔ `main`** — diverged (~222 ahead / ~43 behind); one coherent line before release +- [ ] **Publish first fork release (`v1.0.0-alpha.1`)** — tag from reconciled `main`, guarded release workflow, npm install evidence +- [ ] **Canonical npm ownership** — OnlineChefGroep-controlled scope + compatibility path for `@bitkyc08/opencodex` +- [ ] **Docs Pages for the fork** — deploy docs-site with OnlineChefGroep URLs (not upstream domain assumptions) +- [ ] **Upstream intake policy** — security/protocol/client-compat only; no release dependence +- [ ] **ROADMAP/docs truth pass** — drop false claims (e.g. CodeQL “done” without workflow; strict already enabled) + +## Medium term — Phase 2–4 + +- [ ] **Terminal UX 10x** — guided `ocx init`, `doctor --fix`, observe cockpit, help IA +- [ ] **De Pas / control-plane GUI** — wire fleet shell under ChefGroep skins; metrics + rate-limit visibility +- [ ] **Custom provider: OnlineChef AI gateway** — first-party registry preset +- [ ] **ChefVault operator UX** — degraded-mode clarity when vault tunnel is down +- [ ] **Smoke test suite** — start proxy + fixture provider requests in CI +- [ ] **Benchmark harness** — latency/artifact lane after APIs stabilize +- [ ] **Config diagnostics** — enhance `ocx config validate` (no second validator) + +## Long term — Phase 5 + +- [ ] **Multi-host fleet management** — centralized config / status across machines +- [ ] **Service mode improvements** — systemd/launchd/WinSW parity +- [ ] **Plugin system (beyond observational contract)** — only with explicit security model; no arbitrary FS loaders by default +- [ ] **Performance regression gates** — p95 TTFT / proxy overhead in CI after baselines diff --git a/structure/00_overview.md b/structure/00_overview.md index de2608ea3..ad251f47b 100644 --- a/structure/00_overview.md +++ b/structure/00_overview.md @@ -16,6 +16,8 @@ belong in `docs-site/`; historical investigations belong in `docs/`. | [`06_docs-and-release.md`](06_docs-and-release.md) | Public docs site, GitHub Pages, README ownership, release flow. | | [`07_design-methodology.md`](07_design-methodology.md) | Design process discipline for new GUI, CLI, and user-facing surfaces. | | [`08_openai-provider-tiers.md`](08_openai-provider-tiers.md) | OpenAI Pool/Direct account-mode and API credential/routing invariants. | +| [`09_x10-terminal-plan.md`](09_x10-terminal-plan.md) | Fork audit, open-PR pickup, and OnlineChefGroep “terminal x10” execution plan. | +| [`plugin-metrics-ratelimit-benchmarks.md`](plugin-metrics-ratelimit-benchmarks.md) | Staged plugin / metrics / rate-limit / benchmark lane plan. | ## Product boundary diff --git a/structure/09_x10-terminal-plan.md b/structure/09_x10-terminal-plan.md new file mode 100644 index 000000000..e46fc253d --- /dev/null +++ b/structure/09_x10-terminal-plan.md @@ -0,0 +1,234 @@ +# 09 — Full Audit + x10 Terminal Plan (OnlineChefGroep) + +Status: living execution plan for the OnlineChefGroep fork of opencodex (`ocx`). +Authored from a full-repo audit on 2026-08-02. Targets `dev` as the integration +branch unless a step is explicitly a `main` promotion. + +## What “terminal x10” means here + +opencodex is the local control plane for Codex / Claude Code / Grok Build. The +“terminal” is the whole operator surface: `ocx` CLI, doctor/observe loops, GUI +(“De Pas” / ChefGroep instrument), and the proxy that keeps nested agent CLIs +routed through OCX. 10x is not “10× more providers” — it is 10× less friction +from install → first successful routed turn → trustworthy ops at kitchen scale. + +--- + +## A. Audit snapshot (current state) + +### Product shape + +| Layer | State on `dev` | Notes | +| --- | --- | --- | +| Runtime proxy | Mature | Bun-native; Responses + Claude Messages + images; adapters for 60+ presets | +| CLI (`ocx`) | Wide but uneven | ~30 command families; init/doctor/observe exist; little personality or guided recovery | +| GUI | ChefGroep skin landed (#30) | Warm Devin / Strak skins; nl default; De Pas WIP pages live on `main` only, unwired | +| Observability | Partial | Prometheus metrics (#42); rate-limit admission (#44/#45); projection PR #52 open | +| Plugins | Contract only | Observational lifecycle (#40); no dynamic loaders; ROADMAP still lists plugins as long-term | +| Provider security | ChefVault slots (#38) | Per-request credentials; vault tunnel outages are an external dependency | +| Fork identity | Split brain | `dev` @ 2.7.43; `main` still carries 2.7.42 + unfinished `v1.0.0-alpha.1` attempt | + +### Branch divergence (highest systemic risk) + +| Metric | Value | +| --- | --- | +| `dev` ahead of `main` | ~222 commits | +| `dev` behind `main` | ~43 commits | +| Relationship | **Diverged** (not fast-forwardable) | + +`main`-only value to preserve on intake: upstream OmniRoute / provider parity +fixes, PostHog + budget/latency experiments, De Pas page stubs, any release- +identity commits that still apply after rebase. + +`dev`-only value that must not be lost: rate-limit, metrics, plugins contract, +ChefVault provider-security, GUI redesign + en/nl i18n, accounts workspace. + +Until this is reconciled, every release and every “ship x10” claim is blocked. + +### Strengths to keep + +1. Maintainer SOT in `structure/` with explicit invariants. +2. Single provider registry + parity tests. +3. Deep cross-platform test suite (~390 root test files + GUI tests). +4. Clean adapter → `bridge.ts` boundary. +5. Operational primitives: doctor, usage JSONL, startup health, restore-on-stop. +6. Multi-client: Codex + Claude Code + Claude Desktop + Grok. + +### Debt / risk hotspots + +| Hotspot | Why it matters | +| --- | --- | +| `src/server/responses/core.ts` (~2k LOC) | Central path; hard to change safely | +| Cursor / Kiro adapters | Largest adapter complexity | +| `dev` ↔ `main` divergence | Blocks first fork release | +| ROADMAP vs reality | Claims CodeQL / strict / GUI theme done or pending incorrectly | +| Dead De Pas pages on `main` | Brand work without routing | +| Windows CI ~13 min | Near timeout without #51 sharding | +| Docs / package URLs | Residual upstream residue on some branches | +| No real e2e smoke | ROADMAP item still open | +| ChefVault dependency | Provider-security degrades when vault tunnel is down | + +--- + +## B. Open PR pickup (executed 2026-08-02) + +Merge order for the open train targeting `dev`: + +| Pri | PR | Action taken | Remaining human step | +| --- | --- | --- | --- | +| 1 | [#51](https://github.com/OnlineChefGroep/opencodex/pull/51) CI shard | Rebased onto `dev`; Greptile thread resolved; merge-ready comment | Security sign-off on workflow → **merge** | +| 2 | [#53](https://github.com/OnlineChefGroep/opencodex/pull/53) Claude recursive OCX | Stale P1/trivial threads resolved; CI green | **Merge** (highest user impact) | +| 3 | [#52](https://github.com/OnlineChefGroep/opencodex/pull/52) rate-limit metrics | Threads resolved; still **draft** | Undraft → review → **merge** | + +No code conflicts between these three. #51 first protects CI for everything else. + +--- + +## C. x10 execution plan + +Five phases. Each phase has an exit gate. Do not start the next phase until the +gate is green. All implementation PRs target `dev`; promotion to `main` is a +maintainer-controlled release step. + +### Phase 0 — Stabilize the train (unblocks everything) + +**Goal:** One coherent integration line and reliable CI. + +1. Merge #51 → #53 → #52 in that order. +2. Reconcile `main` → `dev` (or rebuild `main` from `dev` + selective cherry-picks): + - Prefer: bring OmniRoute / upstream parity + useful PostHog/budget pieces onto `dev`. + - Decide De Pas stubs: wire into App routing **or** delete from `main` so they stop drifting. +3. Update required CI checks for new shard job names (`macos-quality`, `windows-quality`, `windows-latest shard 2/2`). +4. Fix ROADMAP truth: strike false “done” claims (CodeQL absent; strict already on; GUI theme partially done on `dev`). + +**Exit gate:** `dev` contains all fork-critical work; CI green under sharded Windows; ROADMAP matches reality; no orphan De Pas files without owners. + +### Phase 1 — Ship the fork identity (trust ×10 for install) + +**Goal:** A stranger can install OnlineChefGroep ocx and know it is ours. + +1. Publish `v1.0.0-alpha.1` from reconciled `main` (release workflow + evidence in CHANGELOG). +2. Canonical npm scope under OnlineChefGroep control; keep `@bitkyc08/opencodex` compatibility path documented. +3. Align `package.json` / README / docs-site / star-prompt / update URLs on both branches. +4. Deploy fork docs to GitHub Pages (replace upstream `opencodex.me` assumptions). +5. Upstream intake policy doc (security/protocol only; no release dependence). +6. Enforce high-severity `bun audit` (already claimed on some histories — verify on `dev`). + +**Exit gate:** `npm i -g /opencodex@alpha` works on Linux/macOS/Windows without preinstalled Bun; docs and update notifier point only at OnlineChefGroep. + +### Phase 2 — Terminal UX 10x (CLI + guided recovery) + +**Goal:** First successful routed turn in minutes; failures become actionable. + +This is the core “terminal x10” phase. + +| Workstream | Concrete deliverables | +| --- | --- | +| **Guided `ocx init`** | Design-first wizard (structure/07 dials): auth-kind stages, Dutch/EN voice, OnlineChef gateway as first-class preset when ready | +| **Doctor → fix loops** | `ocx doctor --fix` for safe auto-repairs (shim, catalog inject, port conflict, vault degraded mode messaging) | +| **Observe as cockpit** | Unify `observe logs|usage|memory` into one TUI-friendly status strip + JSON for agents | +| **Claude/Codex spawn reliability** | Land #53; add e2e regression for nested `claude` + Agent View; document recursive PATH rules | +| **Star/update noise** | Keep star prompt opt-in; make update notify fork-correct and quiet by default | +| **Help IA** | Restructure `ocx help` into lifecycle / providers / observe / integrations; drop dead aliases | + +**Exit gate:** Timed cold-start scenario (clean home → init → start → one mock Responses turn) documented and covered by an e2e-style test; doctor can repair the top 5 failure modes without reading source. + +### Phase 3 — Control-plane 10x (GUI “De Pas” + ops) + +**Goal:** The dashboard feels like ChefGroep infrastructure, not a generic admin template. + +1. Wire or rebuild fleet shell pages (Modellen / Verkeer / Systeem / Instellingen) on `dev` under the existing ChefGroep skins — one composition language, no card soup. +2. Surface metrics + rate-limit aggregates (#52) in GUI: allow/deny, surface breakdown, no identity leakage. +3. Provider workspace: ChefVault slot status, degraded-mode banners, per-provider fallback already started in #36. +4. Claude + Codex auth pages: single “accounts” mental model (already generalized — finish consistency). +5. Strict i18n: en source complete; nl overrides for operator voice; drop unused locale residue. + +**Exit gate:** Operator can answer “is the kitchen proxy healthy, who is rate-limited, and which vault slots are live?” from the GUI in under 10 seconds. + +### Phase 4 — Platform 10x (gateway, plugins, security) + +**Goal:** OnlineChef-native differentiation without forking the adapter model. + +1. **OnlineChef AI gateway** provider preset (registry + adapter path + docs). +2. **ChefVault** hardening: offline/degraded UX, doctor checks, no secret logging (privacy:scan green). +3. **Plugins v1 → useful:** first-party observational plugins (metrics already separate; example: budget alert, PostHog projection) registered in-process — still no arbitrary FS loaders. +4. Finish structure plan leftovers: config diagnostics enhancements; benchmark harness (#5 in plugin-metrics plan). +5. Smoke suite: start proxy + fixture provider Responses + Claude Messages in CI. + +**Exit gate:** One OnlineChef-branded provider path works end-to-end; plugins/metrics/rate-limit/benchmark lanes marked complete in `structure/plugin-metrics-ratelimit-benchmarks.md`. + +### Phase 5 — Scale 10x (fleet + reliability) + +**Goal:** Multi-machine kitchens without babysitting. + +1. Multi-host fleet management (config sync, admission keys, read-only status aggregation). +2. Service mode improvements (systemd/launchd/WinSW parity + lifecycle workflow always green). +3. Performance budgets: p95 TTFT / proxy overhead regression gates after baseline week. +4. Optional Go native-port intake only if upstream `dev2-go` proves install-size wins — not a fork priority until Phase 1–4 land. + +**Exit gate:** Documented fleet of ≥2 hosts managed from one control surface; CI blocks on latency regression beyond agreed budget. + +--- + +## D. Priority matrix (what moves the needle) + +| Lever | Impact | Invasiveness | Phase | +| --- | --- | --- | --- | +| Merge open PRs + fix CI shards | High | Low | 0 | +| Reconcile `dev`/`main` | Critical | High | 0 | +| First alpha release + npm identity | High | Medium | 1 | +| Doctor--fix + init redesign | Very high | Medium | 2 | +| Claude recursive routing (#53) | High | Low | 0/2 | +| De Pas / metrics GUI | High | Medium | 3 | +| OnlineChef gateway + Vault UX | Differentiating | Medium–High | 4 | +| Fleet multi-host | Strategic | High | 5 | + +--- + +## E. Non-goals (explicit) + +- Do not reintroduce dynamic plugin code loading from arbitrary paths. +- Do not log prompts, API keys, or account identifiers. +- Do not target `main` for feature PRs. +- Do not claim “independent versioning done” until alpha is actually published. +- Do not copy generated “improvement bundles” that duplicate config/cost systems (see plugin-metrics plan). + +--- + +## F. Linear packaging (created 2026-08-02) + +| Phase | Linear | URL | +| --- | --- | --- | +| 0 Stabilize | [CHE-5](https://linear.app/chefgroepp/issue/CHE-5/ocx-0-stabilize-train-merge-515352-reconcile-devmain) | Urgent / Todo | +| 1 Identity | [CHE-6](https://linear.app/chefgroepp/issue/CHE-6/ocx-1-ship-fork-identity-alpha-release-npmdocs) | High / Backlog (child of CHE-5) | +| 2 Terminal UX | [CHE-9](https://linear.app/chefgroepp/issue/CHE-9/ocx-2-terminal-ux-10x-init-doctor-fix-observe-help) | High / Backlog | +| 3 Control plane | [CHE-10](https://linear.app/chefgroepp/issue/CHE-10/ocx-3-control-plane-de-pas-gui-metrics-visibility) | Medium / Backlog | +| 4 Platform | [CHE-8](https://linear.app/chefgroepp/issue/CHE-8/ocx-4-platform-gateway-vault-ux-plugins-completion-smoke) | Medium / Backlog | +| 5 Scale | [CHE-7](https://linear.app/chefgroepp/issue/CHE-7/ocx-5-scale-fleet-service-parity-latency-gates) | Low / Backlog | + +Each phase opens as a stacked PR series against `dev`. + +--- + +## G. Immediate next commands (operators) + +```bash +# After security OK on #51: +gh pr merge 51 --merge +gh pr merge 53 --merge +# Undraft #52 in the GitHub UI, then: +gh pr merge 52 --merge + +# Then start Phase 0 reconcile on a branch off latest dev: +git fetch origin +git checkout -b cursor/reconcile-main-into-dev-ecac origin/dev +# cherry-pick / merge selected origin/main commits; open PR → dev +``` + +Validation on every runtime PR: + +```bash +bun run typecheck +bun run test +bun run privacy:scan +```