From 75424bc8ef886d7da45281489f5f24a125fbcebf Mon Sep 17 00:00:00 2001 From: ndycode <405533+ndycode@users.noreply.github.com> Date: Sun, 22 Mar 2026 11:09:11 +0800 Subject: [PATCH 1/4] docs: add maintainer runbooks --- docs/README.md | 3 ++ .../RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md | 36 +++++++++++++++++ .../RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md | 39 +++++++++++++++++++ .../RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md | 37 ++++++++++++++++++ test/documentation.test.ts | 11 ++++++ 5 files changed, 126 insertions(+) create mode 100644 docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md create mode 100644 docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md create mode 100644 docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md diff --git a/docs/README.md b/docs/README.md index f63480fb..7325b927 100644 --- a/docs/README.md +++ b/docs/README.md @@ -63,6 +63,9 @@ Public documentation for `codex-multi-auth`. | [development/CONFIG_FIELDS.md](development/CONFIG_FIELDS.md) | Complete field and environment inventory | | [development/CONFIG_FLOW.md](development/CONFIG_FLOW.md) | Configuration resolution flow | | [development/REPOSITORY_SCOPE.md](development/REPOSITORY_SCOPE.md) | Ownership map by repository path | +| [development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md](development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md) | Safe workflow for adding a new `codex auth` command | +| [development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md](development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md) | Safe workflow for introducing a new config/settings field | +| [development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md](development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md) | Safe workflow for changing routing or account-selection policy | | [development/TESTING.md](development/TESTING.md) | Validation gates and test matrix | | [development/TUI_PARITY_CHECKLIST.md](development/TUI_PARITY_CHECKLIST.md) | Dashboard UX parity checklist | | [benchmarks/code-edit-format-benchmark.md](benchmarks/code-edit-format-benchmark.md) | Benchmark methodology and outputs | diff --git a/docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md b/docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md new file mode 100644 index 00000000..ae44bc0a --- /dev/null +++ b/docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md @@ -0,0 +1,36 @@ +# Runbook: Add an Auth Manager Command + +Use this when adding a new `codex auth ...` command. + +## Goal + +Add a command without breaking the existing CLI surface, help text, JSON mode, or dashboard/menu behavior. + +## Where to Change + +- `lib/codex-manager.ts` — command parsing and dispatch +- `lib/codex-manager/` — extracted command/controller helpers when the command grows beyond trivial size +- `docs/reference/commands.md` — command reference +- `test/codex-manager-cli.test.ts` — CLI behavior coverage +- `test/documentation.test.ts` — docs parity when command text/help changes + +## Safe Workflow + +1. Add the smallest possible parsing/dispatch change in `lib/codex-manager.ts`. +2. If the command has more than one logical branch, extract a helper under `lib/codex-manager/` instead of growing the main file. +3. Keep JSON output stable and explicit if the command already has `--json`. +4. Update command help text and `docs/reference/commands.md` in the same change. +5. Add or extend `test/codex-manager-cli.test.ts` for the new path. + +## Compatibility Checks + +- Preserve canonical command shape: `codex auth ` +- Do not silently change existing help text unless docs/tests are updated too +- If adding flags, update both help text and command reference + +## QA + +- `npm run typecheck` +- `npm run lint -- lib/codex-manager.ts test/codex-manager-cli.test.ts docs/reference/commands.md test/documentation.test.ts` +- `npm run test -- test/codex-manager-cli.test.ts test/documentation.test.ts` +- Run the real command or `--help` path in Bash and inspect output diff --git a/docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md b/docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md new file mode 100644 index 00000000..595e0381 --- /dev/null +++ b/docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md @@ -0,0 +1,39 @@ +# Runbook: Add a Config Field Safely + +Use this when introducing a new `pluginConfig` or dashboard setting field. + +## Goal + +Add a field without breaking defaults, migration behavior, settings persistence, or documentation parity. + +## Where to Change + +- `lib/config.ts` — runtime config resolution/defaults +- `lib/dashboard-settings.ts` or `lib/unified-settings.ts` — persisted settings shape +- `lib/codex-manager/settings-hub.ts` and extracted settings helpers — interactive editing if user-facing +- `docs/configuration.md` — user-facing config docs +- `docs/reference/settings.md` — settings reference +- `docs/development/CONFIG_FIELDS.md` — full field inventory +- `test/config.test.ts`, `test/dashboard-settings.test.ts`, `test/unified-settings.test.ts` — behavior coverage +- `test/documentation.test.ts` — docs parity + +## Safe Workflow + +1. Define the default in the owning config/settings module first. +2. Thread it through persistence and loading paths before exposing UI controls. +3. If user-facing, add the smallest possible settings UI path after the storage/config part is correct. +4. Document the field in both user docs and maintainer inventory. +5. Add tests for defaulting, persistence, and docs parity. + +## Compatibility Checks + +- New fields must have deterministic defaults. +- Do not change existing default values in the same PR unless that is the actual feature. +- Keep docs and code aligned in the same change. + +## QA + +- `npm run typecheck` +- `npm run lint -- lib/config.ts lib/dashboard-settings.ts lib/unified-settings.ts test/config.test.ts test/dashboard-settings.test.ts test/unified-settings.test.ts test/documentation.test.ts` +- Run the targeted test files that cover the field +- If the field is user-visible, exercise the real settings path manually diff --git a/docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md b/docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md new file mode 100644 index 00000000..51a64fa1 --- /dev/null +++ b/docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md @@ -0,0 +1,37 @@ +# Runbook: Change Routing or Account-Selection Policy Safely + +Use this when changing account selection, quota behavior, retry/failover logic, or forecast/report reasoning. + +## Goal + +Change policy without breaking request flow, account safety, or diagnostics. + +## Where to Change + +- `index.ts` — runtime orchestration +- `lib/rotation.ts` — account selection +- `lib/forecast.ts` — readiness/risk forecasting +- `lib/request/failure-policy.ts` — retry/failover decisions +- `lib/request/rate-limit-backoff.ts` — cooldown/backoff behavior +- `lib/quota-probe.ts` / `lib/quota-cache.ts` — quota-derived decision inputs +- `test/rotation.test.ts`, `test/forecast.test.ts`, `test/failure-policy.test.ts`, `test/rate-limit-backoff.test.ts`, `test/codex-manager-cli.test.ts` — policy coverage + +## Safe Workflow + +1. Isolate the policy change from pure code motion. +2. Update the reasoning-producing surfaces (`forecast`, `report`, diagnostics) if their output semantics change. +3. Add or update focused tests before widening scope. +4. Prefer one policy change per PR. + +## Compatibility Checks + +- Do not break existing JSON contract shapes unless the contract is explicitly being revised. +- If recommendation or routing reasoning changes, update the explain/report output tests too. +- Keep live-probe behavior and storage mutations covered by tests. + +## QA + +- `npm run typecheck` +- `npm run lint -- index.ts lib/rotation.ts lib/forecast.ts lib/request/failure-policy.ts lib/request/rate-limit-backoff.ts test/rotation.test.ts test/forecast.test.ts test/failure-policy.test.ts test/rate-limit-backoff.test.ts test/codex-manager-cli.test.ts` +- Run the targeted policy tests you touched +- Execute at least one real CLI/manual QA path that demonstrates the changed reasoning or routing behavior diff --git a/test/documentation.test.ts b/test/documentation.test.ts index 1c696d36..38ce182b 100644 --- a/test/documentation.test.ts +++ b/test/documentation.test.ts @@ -267,10 +267,21 @@ describe("Documentation Integrity", () => { const configGuide = read("docs/configuration.md").toLowerCase(); const settingsRef = read("docs/reference/settings.md").toLowerCase(); const fieldInventoryPath = "docs/development/CONFIG_FIELDS.md"; + const runbooks = [ + "docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md", + "docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md", + "docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md", + ]; expect( existsSync(join(projectRoot, fieldInventoryPath)), `${fieldInventoryPath} should exist`, ).toBe(true); + for (const runbook of runbooks) { + expect( + existsSync(join(projectRoot, runbook)), + `${runbook} should exist`, + ).toBe(true); + } const fieldInventory = read(fieldInventoryPath).toLowerCase(); expect(configGuide).toContain("stable environment overrides"); From 52f475a3d5b21c58e6b7f31bf83263d10e6668a0 Mon Sep 17 00:00:00 2001 From: ndycode <405533+ndycode@users.noreply.github.com> Date: Sun, 22 Mar 2026 11:37:09 +0800 Subject: [PATCH 2/4] docs: add v1.2.0 release notes stub --- docs/releases/v1.2.0.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 docs/releases/v1.2.0.md diff --git a/docs/releases/v1.2.0.md b/docs/releases/v1.2.0.md new file mode 100644 index 00000000..95b9d235 --- /dev/null +++ b/docs/releases/v1.2.0.md @@ -0,0 +1,18 @@ +# Release v1.2.0 + +Release line: `stable` + +This document anchors the current stable release reference used by the docs portal. + +## Scope + +- Current package version in `package.json` is `1.2.0`. +- Canonical command family remains `codex auth ...`. +- Canonical package name remains `codex-multi-auth`. + +## Related + +- [../getting-started.md](../getting-started.md) +- [../upgrade.md](../upgrade.md) +- [../reference/commands.md](../reference/commands.md) +- [../reference/public-api.md](../reference/public-api.md) From 18b69115c10f1e496e3d947a34da329cdfdef592 Mon Sep 17 00:00:00 2001 From: ndycode <405533+ndycode@users.noreply.github.com> Date: Sun, 22 Mar 2026 13:03:01 +0800 Subject: [PATCH 3/4] docs: tighten maintainer runbooks --- .../RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md | 1 + .../RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md | 2 ++ .../RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md | 3 ++- test/documentation.test.ts | 20 +++++++++++-------- 4 files changed, 17 insertions(+), 9 deletions(-) diff --git a/docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md b/docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md index ae44bc0a..2740fc20 100644 --- a/docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md +++ b/docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md @@ -10,6 +10,7 @@ Add a command without breaking the existing CLI surface, help text, JSON mode, o - `lib/codex-manager.ts` — command parsing and dispatch - `lib/codex-manager/` — extracted command/controller helpers when the command grows beyond trivial size +- `lib/cli.ts` — prompt-heavy shared CLI helpers when the command needs reusable interactive flows - `docs/reference/commands.md` — command reference - `test/codex-manager-cli.test.ts` — CLI behavior coverage - `test/documentation.test.ts` — docs parity when command text/help changes diff --git a/docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md b/docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md index 595e0381..a8748f5a 100644 --- a/docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md +++ b/docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md @@ -9,6 +9,7 @@ Add a field without breaking defaults, migration behavior, settings persistence, ## Where to Change - `lib/config.ts` — runtime config resolution/defaults +- `lib/schemas.ts` — env/config schema validation and typed field contracts - `lib/dashboard-settings.ts` or `lib/unified-settings.ts` — persisted settings shape - `lib/codex-manager/settings-hub.ts` and extracted settings helpers — interactive editing if user-facing - `docs/configuration.md` — user-facing config docs @@ -30,6 +31,7 @@ Add a field without breaking defaults, migration behavior, settings persistence, - New fields must have deterministic defaults. - Do not change existing default values in the same PR unless that is the actual feature. - Keep docs and code aligned in the same change. +- Recheck the Windows persistence notes when the field is written to disk; `EBUSY` and `EPERM` retry behavior must stay documented and covered. ## QA diff --git a/docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md b/docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md index 51a64fa1..157a17f8 100644 --- a/docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md +++ b/docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md @@ -9,12 +9,13 @@ Change policy without breaking request flow, account safety, or diagnostics. ## Where to Change - `index.ts` — runtime orchestration +- `lib/accounts.ts` — account selection inputs, health state, and cooldown readiness data - `lib/rotation.ts` — account selection - `lib/forecast.ts` — readiness/risk forecasting - `lib/request/failure-policy.ts` — retry/failover decisions - `lib/request/rate-limit-backoff.ts` — cooldown/backoff behavior - `lib/quota-probe.ts` / `lib/quota-cache.ts` — quota-derived decision inputs -- `test/rotation.test.ts`, `test/forecast.test.ts`, `test/failure-policy.test.ts`, `test/rate-limit-backoff.test.ts`, `test/codex-manager-cli.test.ts` — policy coverage +- `test/accounts.test.ts`, `test/rotation.test.ts`, `test/forecast.test.ts`, `test/failure-policy.test.ts`, `test/rate-limit-backoff.test.ts`, `test/codex-manager-cli.test.ts` — policy coverage ## Safe Workflow diff --git a/test/documentation.test.ts b/test/documentation.test.ts index 38ce182b..f4a01cc0 100644 --- a/test/documentation.test.ts +++ b/test/documentation.test.ts @@ -263,25 +263,29 @@ describe("Documentation Integrity", () => { expect(manager).not.toContain("codex-multi-auth auth switch "); }); - it("documents stable overrides separately from advanced and internal overrides", () => { - const configGuide = read("docs/configuration.md").toLowerCase(); - const settingsRef = read("docs/reference/settings.md").toLowerCase(); - const fieldInventoryPath = "docs/development/CONFIG_FIELDS.md"; + it("keeps maintainer runbooks present", () => { const runbooks = [ "docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md", "docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md", "docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md", ]; - expect( - existsSync(join(projectRoot, fieldInventoryPath)), - `${fieldInventoryPath} should exist`, - ).toBe(true); + for (const runbook of runbooks) { expect( existsSync(join(projectRoot, runbook)), `${runbook} should exist`, ).toBe(true); } + }); + + it("documents stable overrides separately from advanced and internal overrides", () => { + const configGuide = read("docs/configuration.md").toLowerCase(); + const settingsRef = read("docs/reference/settings.md").toLowerCase(); + const fieldInventoryPath = "docs/development/CONFIG_FIELDS.md"; + expect( + existsSync(join(projectRoot, fieldInventoryPath)), + `${fieldInventoryPath} should exist`, + ).toBe(true); const fieldInventory = read(fieldInventoryPath).toLowerCase(); expect(configGuide).toContain("stable environment overrides"); From dd90b77592bb534c0965ae7d59437b5b64568d7a Mon Sep 17 00:00:00 2001 From: ndycode <405533+ndycode@users.noreply.github.com> Date: Sun, 22 Mar 2026 13:52:21 +0800 Subject: [PATCH 4/4] Add auth log redaction QA note --- docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md b/docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md index 2740fc20..2c8662d6 100644 --- a/docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md +++ b/docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md @@ -34,4 +34,5 @@ Add a command without breaking the existing CLI surface, help text, JSON mode, o - `npm run typecheck` - `npm run lint -- lib/codex-manager.ts test/codex-manager-cli.test.ts docs/reference/commands.md test/documentation.test.ts` - `npm run test -- test/codex-manager-cli.test.ts test/documentation.test.ts` +- For auth flows, never paste raw tokens/session headers in PRs, issues, or logs; redact sensitive output. - Run the real command or `--help` path in Bash and inspect output