Skip to content

Commit dafb9bd

Browse files
ndycodendycode
committed
Merge remote-tracking branch 'origin/docs/pr7-maintainer-runbooks-latest' into release/mainbound-20260323
2 parents e820c32 + dd90b77 commit dafb9bd

6 files changed

Lines changed: 153 additions & 0 deletions

File tree

‎docs/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,9 @@ Public documentation for `codex-multi-auth`.
7272
| [development/RUNBOOK_ADD_CONFIG_FIELD.md](development/RUNBOOK_ADD_CONFIG_FIELD.md) | Safe workflow for introducing a new config field |
7373
| [development/RUNBOOK_CHANGE_ROUTING_POLICY.md](development/RUNBOOK_CHANGE_ROUTING_POLICY.md) | Safe workflow for changing routing, retry, or fallback policy |
7474
| [development/REPOSITORY_SCOPE.md](development/REPOSITORY_SCOPE.md) | Ownership map by repository path |
75+
| [development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md](development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md) | Safe workflow for adding a new `codex auth` command |
76+
| [development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md](development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md) | Safe workflow for introducing a new config/settings field |
77+
| [development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md](development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md) | Safe workflow for changing routing or account-selection policy |
7578
| [development/TESTING.md](development/TESTING.md) | Validation gates and test matrix |
7679
| [development/TUI_PARITY_CHECKLIST.md](development/TUI_PARITY_CHECKLIST.md) | Dashboard UX parity checklist |
7780
| [benchmarks/code-edit-format-benchmark.md](benchmarks/code-edit-format-benchmark.md) | Benchmark methodology and outputs |

‎docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Runbook: Add an Auth Manager Command
2+
3+
Use this when adding a new `codex auth ...` command.
4+
5+
## Goal
6+
7+
Add a command without breaking the existing CLI surface, help text, JSON mode, or dashboard/menu behavior.
8+
9+
## Where to Change
10+
11+
- `lib/codex-manager.ts` — command parsing and dispatch
12+
- `lib/codex-manager/` — extracted command/controller helpers when the command grows beyond trivial size
13+
- `lib/cli.ts` — prompt-heavy shared CLI helpers when the command needs reusable interactive flows
14+
- `docs/reference/commands.md` — command reference
15+
- `test/codex-manager-cli.test.ts` — CLI behavior coverage
16+
- `test/documentation.test.ts` — docs parity when command text/help changes
17+
18+
## Safe Workflow
19+
20+
1. Add the smallest possible parsing/dispatch change in `lib/codex-manager.ts`.
21+
2. If the command has more than one logical branch, extract a helper under `lib/codex-manager/` instead of growing the main file.
22+
3. Keep JSON output stable and explicit if the command already has `--json`.
23+
4. Update command help text and `docs/reference/commands.md` in the same change.
24+
5. Add or extend `test/codex-manager-cli.test.ts` for the new path.
25+
26+
## Compatibility Checks
27+
28+
- Preserve canonical command shape: `codex auth <subcommand>`
29+
- Do not silently change existing help text unless docs/tests are updated too
30+
- If adding flags, update both help text and command reference
31+
32+
## QA
33+
34+
- `npm run typecheck`
35+
- `npm run lint -- lib/codex-manager.ts test/codex-manager-cli.test.ts docs/reference/commands.md test/documentation.test.ts`
36+
- `npm run test -- test/codex-manager-cli.test.ts test/documentation.test.ts`
37+
- For auth flows, never paste raw tokens/session headers in PRs, issues, or logs; redact sensitive output.
38+
- Run the real command or `--help` path in Bash and inspect output

‎docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Runbook: Add a Config Field Safely
2+
3+
Use this when introducing a new `pluginConfig` or dashboard setting field.
4+
5+
## Goal
6+
7+
Add a field without breaking defaults, migration behavior, settings persistence, or documentation parity.
8+
9+
## Where to Change
10+
11+
- `lib/config.ts` — runtime config resolution/defaults
12+
- `lib/schemas.ts` — env/config schema validation and typed field contracts
13+
- `lib/dashboard-settings.ts` or `lib/unified-settings.ts` — persisted settings shape
14+
- `lib/codex-manager/settings-hub.ts` and extracted settings helpers — interactive editing if user-facing
15+
- `docs/configuration.md` — user-facing config docs
16+
- `docs/reference/settings.md` — settings reference
17+
- `docs/development/CONFIG_FIELDS.md` — full field inventory
18+
- `test/config.test.ts`, `test/dashboard-settings.test.ts`, `test/unified-settings.test.ts` — behavior coverage
19+
- `test/documentation.test.ts` — docs parity
20+
21+
## Safe Workflow
22+
23+
1. Define the default in the owning config/settings module first.
24+
2. Thread it through persistence and loading paths before exposing UI controls.
25+
3. If user-facing, add the smallest possible settings UI path after the storage/config part is correct.
26+
4. Document the field in both user docs and maintainer inventory.
27+
5. Add tests for defaulting, persistence, and docs parity.
28+
29+
## Compatibility Checks
30+
31+
- New fields must have deterministic defaults.
32+
- Do not change existing default values in the same PR unless that is the actual feature.
33+
- Keep docs and code aligned in the same change.
34+
- Recheck the Windows persistence notes when the field is written to disk; `EBUSY` and `EPERM` retry behavior must stay documented and covered.
35+
36+
## QA
37+
38+
- `npm run typecheck`
39+
- `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`
40+
- Run the targeted test files that cover the field
41+
- If the field is user-visible, exercise the real settings path manually

‎docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Runbook: Change Routing or Account-Selection Policy Safely
2+
3+
Use this when changing account selection, quota behavior, retry/failover logic, or forecast/report reasoning.
4+
5+
## Goal
6+
7+
Change policy without breaking request flow, account safety, or diagnostics.
8+
9+
## Where to Change
10+
11+
- `index.ts` — runtime orchestration
12+
- `lib/accounts.ts` — account selection inputs, health state, and cooldown readiness data
13+
- `lib/rotation.ts` — account selection
14+
- `lib/forecast.ts` — readiness/risk forecasting
15+
- `lib/request/failure-policy.ts` — retry/failover decisions
16+
- `lib/request/rate-limit-backoff.ts` — cooldown/backoff behavior
17+
- `lib/quota-probe.ts` / `lib/quota-cache.ts` — quota-derived decision inputs
18+
- `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
19+
20+
## Safe Workflow
21+
22+
1. Isolate the policy change from pure code motion.
23+
2. Update the reasoning-producing surfaces (`forecast`, `report`, diagnostics) if their output semantics change.
24+
3. Add or update focused tests before widening scope.
25+
4. Prefer one policy change per PR.
26+
27+
## Compatibility Checks
28+
29+
- Do not break existing JSON contract shapes unless the contract is explicitly being revised.
30+
- If recommendation or routing reasoning changes, update the explain/report output tests too.
31+
- Keep live-probe behavior and storage mutations covered by tests.
32+
33+
## QA
34+
35+
- `npm run typecheck`
36+
- `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`
37+
- Run the targeted policy tests you touched
38+
- Execute at least one real CLI/manual QA path that demonstrates the changed reasoning or routing behavior

‎docs/releases/v1.2.0.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Release v1.2.0
2+
3+
Release line: `stable`
4+
5+
This document anchors the current stable release reference used by the docs portal.
6+
7+
## Scope
8+
9+
- Current package version in `package.json` is `1.2.0`.
10+
- Canonical command family remains `codex auth ...`.
11+
- Canonical package name remains `codex-multi-auth`.
12+
13+
## Related
14+
15+
- [../getting-started.md](../getting-started.md)
16+
- [../upgrade.md](../upgrade.md)
17+
- [../reference/commands.md](../reference/commands.md)
18+
- [../reference/public-api.md](../reference/public-api.md)

‎test/documentation.test.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -280,6 +280,21 @@ describe("Documentation Integrity", () => {
280280
expect(manager).not.toContain("codex-multi-auth auth switch <index>");
281281
});
282282

283+
it("keeps maintainer runbooks present", () => {
284+
const runbooks = [
285+
"docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md",
286+
"docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md",
287+
"docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md",
288+
];
289+
290+
for (const runbook of runbooks) {
291+
expect(
292+
existsSync(join(projectRoot, runbook)),
293+
`${runbook} should exist`,
294+
).toBe(true);
295+
}
296+
});
297+
283298
it("documents stable overrides separately from advanced and internal overrides", () => {
284299
const configGuide = read("docs/configuration.md").toLowerCase();
285300
const settingsRef = read("docs/reference/settings.md").toLowerCase();

0 commit comments

Comments
 (0)