@getrouter/getrouter-cli 0.1.0

package/docs/plans/2026-01-04-cli-docs-cleanup-plan.md

@@ -0,0 +1,126 @@
+# CLI Command Cleanup + README Localization Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Remove unregistered command entrypoints and split README into English/Chinese/Japanese files.
+
+**Architecture:** Keep the registered command list unchanged while deleting unused command modules. Split README content into language-specific files with a small language switch header.
+
+**Tech Stack:** TypeScript, Vitest, Commander, Markdown.
+
+### Task 1: Add a failing test that enforces the command entrypoint set
+
+**Files:**
+- Modify: `tests/cli.test.ts`
+
+**Step 1: Write the failing test**
+
+```ts
+import { readdirSync } from "node:fs";
+import path from "node:path";
+
+it("only ships registered command entrypoints", () => {
+  const cmdDir = path.join(process.cwd(), "src", "cmd");
+  const files = readdirSync(cmdDir).filter((file) => file.endsWith(".ts"));
+  const expected = [
+    "auth.ts",
+    "claude.ts",
+    "codex.ts",
+    "config-helpers.ts",
+    "config.ts",
+    "env.ts",
+    "index.ts",
+    "keys.ts",
+    "models.ts",
+    "status.ts",
+    "usages.ts",
+  ];
+  expect(files.sort()).toEqual(expected.sort());
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun run test -- tests/cli.test.ts`
+Expected: FAIL (extra files exist in `src/cmd`).
+
+**Step 3: Commit**
+
+```bash
+git add tests/cli.test.ts
+git commit -m "test: guard cmd entrypoints"
+```
+
+### Task 2: Remove unused command entrypoints
+
+**Files:**
+- Delete: `src/cmd/plans.ts`
+- Delete: `src/cmd/providers.ts`
+- Delete: `src/cmd/subscription.ts`
+- Delete: `src/cmd/user.ts`
+
+**Step 1: Remove files**
+
+```bash
+rm src/cmd/plans.ts src/cmd/providers.ts src/cmd/subscription.ts src/cmd/user.ts
+```
+
+**Step 2: Run test to verify it passes**
+
+Run: `bun run test -- tests/cli.test.ts`
+Expected: PASS.
+
+**Step 3: Commit**
+
+```bash
+git add src/cmd/plans.ts src/cmd/providers.ts src/cmd/subscription.ts src/cmd/user.ts
+git commit -m "chore: remove unused cmd entrypoints"
+```
+
+### Task 3: Split README into language-specific files
+
+**Files:**
+- Modify: `README.md`
+- Create: `README.zh-cn.md`
+- Create: `README.ja.md`
+
+**Step 1: Update `README.md` to English only and add language links**
+
+Add a language switcher at the top, then keep only the English content.
+
+**Step 2: Create `README.zh-cn.md`**
+
+Move the current Chinese section into this file and add the same language switcher.
+
+**Step 3: Create `README.ja.md`**
+
+Translate the English content into Japanese, keeping the same structure and headings.
+
+**Step 4: Commit**
+
+```bash
+git add README.md README.zh-cn.md README.ja.md
+git commit -m "docs: split readmes by language"
+```
+
+### Task 4: Full verification
+
+**Step 1: Run tests**
+
+Run: `bun run test`
+Expected: PASS.
+
+**Step 2: Run typecheck**
+
+Run: `bun run typecheck`
+Expected: PASS.
+
+**Step 3: Run lint**
+
+Run: `bun run lint`
+Expected: PASS.
+
+**Step 4: Run format**
+
+Run: `bun run format`
+Expected: PASS (no changes).

package/docs/plans/2026-01-04-codex-multistep-design.md

@@ -0,0 +1,76 @@
+# Codex Multi-step Config Design
+
+## Goals
+- Replace `getrouter codex` env output with a multi-step interactive flow.
+- Support fuzzy search at each step (model, reasoning, key).
+- Write `~/.codex/config.toml` with selected model, reasoning effort, and provider config.
+- Write `~/.codex/auth.json` with `OPENAI_API_KEY` from selected key.
+- Preserve other keys in existing config/auth files (merge, don’t clobber).
+
+## Non-Goals
+- Do not change `getrouter claude` behavior.
+- No new dependencies (manual TOML merge).
+- No non-interactive mode for codex (TTY required).
+
+## Command Flow (TTY only)
+1. **Model**: select from fixed list with descriptions and fuzzy search.
+   - gpt-5.2-codex — Latest frontier agentic coding model.
+   - gpt-5.1-codex-max — Codex-optimized flagship for deep and fast reasoning.
+   - gpt-5.1-codex-mini — Optimized for codex. Cheaper, faster, but less capable.
+   - gpt-5.2 — Latest frontier model with improvements across knowledge, reasoning and coding.
+   - Prompt message includes: “Access legacy models by running codex -m <model_name> or in your config.toml”.
+2. **Reasoning**: fuzzy select with display name + description.
+   - Low → `low`
+   - Medium (default) → `medium`
+   - High → `high`
+   - Extra high → `xhigh` (display name differs from stored value)
+3. **Key**: fuzzy select existing API keys (reuse consumer list flow).
+4. **Confirm**: show summary (model, reasoning, provider, key id/name) and ask for final confirm.
+
+If any step is canceled, exit quietly with no writes.
+
+## Output Files
+### `~/.codex/config.toml`
+Set/merge:
+```
+model = "<model>"
+model_reasoning_effort = "<low|medium|high|xhigh>"
+model_provider = "getrouter"
+
+[model_providers.getrouter]
+name = "getrouter"
+base_url = "https://api.getrouter.dev/codex"
+wire_api = "responses"
+requires_openai_auth = true
+```
+
+### `~/.codex/auth.json`
+Merge JSON and set:
+```
+{ "OPENAI_API_KEY": "<key>" }
+```
+Ensure permissions 0600 on non-Windows systems.
+
+## Merge Strategy
+- TOML: line-based update at root for `model`, `model_reasoning_effort`, `model_provider`.
+- `[model_providers.getrouter]`:
+  - If present, update/insert keys within that table.
+  - If absent, append the table block.
+- JSON: read existing, update only `OPENAI_API_KEY`.
+
+## Error Handling
+- Non-TTY: error “Interactive mode required…”
+- Missing keys: error “No available API keys”.
+- Write/parse failures: throw and exit with status 1.
+
+## Testing Plan
+- Update `tests/cmd/codex.test.ts` for multi-step flow and file writes.
+- Add tests for TOML merge and auth.json merge.
+- Validate reasoning value mapping (Extra high → xhigh).
+
+## Files To Touch
+- `src/cmd/codex.ts`
+- `src/core/setup/codex.ts` (new)
+- `src/core/interactive/codex.ts` (new)
+- `tests/cmd/codex.test.ts`
+- `README.*` (doc updates for codex behavior)

package/docs/plans/2026-01-04-codex-multistep-plan.md

@@ -0,0 +1,240 @@
+# Codex Multi-step Config Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Replace `getrouter codex` with a multi-step interactive flow that writes `~/.codex/config.toml` and `~/.codex/auth.json`, preserving existing keys.
+
+**Architecture:** Add codex-specific interactive helpers and TOML/JSON merge utilities. Update codex command to use the new flow and remove env/hook writing for codex only.
+
+**Tech Stack:** TypeScript, prompts, Vitest, Node fs.
+
+### Task 1: Add failing tests for codex multi-step flow + file writes
+
+**Files:**
+- Modify: `tests/cmd/codex.test.ts`
+
+**Step 1: Write the failing tests**
+
+```ts
+import fs from "node:fs";
+import path from "node:path";
+import prompts from "prompts";
+import { createProgram } from "../../src/cli";
+
+const mockModels = [
+  "gpt-5.2-codex",
+  "gpt-5.1-codex-max",
+  "gpt-5.1-codex-mini",
+  "gpt-5.2",
+];
+
+it("writes codex config and auth after interactive flow", async () => {
+  // arrange env + mock consumer
+  // inject: model, reasoning, key, confirm
+  // expect config.toml + auth.json content
+});
+
+it("merges existing codex config and auth", async () => {
+  // write preexisting config.toml with extra keys and table
+  // write preexisting auth.json with extra fields
+  // run codex flow and assert extra keys are preserved
+});
+```
+
+**Step 2: Run tests to verify they fail**
+
+Run: `bun run test -- tests/cmd/codex.test.ts`
+Expected: FAIL (codex still writes env/hook).
+
+**Step 3: Commit**
+
+```bash
+git add tests/cmd/codex.test.ts
+git commit -m "test: codex multistep flow"
+```
+
+### Task 2: Add codex config merge helpers
+
+**Files:**
+- Create: `src/core/setup/codex.ts`
+- Test: `tests/core/setup/codex.test.ts`
+
+**Step 1: Write the failing tests**
+
+```ts
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { mergeCodexToml, mergeAuthJson } from "../../../src/core/setup/codex";
+
+it("merges codex toml at root and provider table", () => {
+  const input = "other = \"keep\"\n[model_providers.other]\nname = \"x\"\n";
+  const output = mergeCodexToml(input, {
+    model: "gpt-5.2-codex",
+    reasoning: "xhigh",
+  });
+  expect(output).toContain("model = \"gpt-5.2-codex\"");
+  expect(output).toContain("model_reasoning_effort = \"xhigh\"");
+  expect(output).toContain("model_provider = \"getrouter\"");
+  expect(output).toContain("[model_providers.getrouter]");
+  expect(output).toContain("other = \"keep\"");
+});
+
+it("merges auth json", () => {
+  const output = mergeAuthJson({ existing: "keep" }, "key-123");
+  expect(output.OPENAI_API_KEY).toBe("key-123");
+  expect(output.existing).toBe("keep");
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun run test -- tests/core/setup/codex.test.ts`
+Expected: FAIL (helpers missing).
+
+**Step 3: Implement minimal helpers**
+
+```ts
+export const mergeCodexToml = (content: string, input: { model: string; reasoning: string }) => {
+  // line-based update for top-level keys
+  // update or append [model_providers.getrouter]
+};
+
+export const mergeAuthJson = (data: Record<string, unknown>, apiKey: string) => ({
+  ...data,
+  OPENAI_API_KEY: apiKey,
+});
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun run test -- tests/core/setup/codex.test.ts`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/core/setup/codex.ts tests/core/setup/codex.test.ts
+git commit -m "feat: codex config merge helpers"
+```
+
+### Task 3: Add codex interactive helpers (model + reasoning)
+
+**Files:**
+- Create: `src/core/interactive/codex.ts`
+- Test: `tests/core/interactive/codex.test.ts`
+
+**Step 1: Write the failing tests**
+
+```ts
+import { describe, it, expect } from "vitest";
+import { MODEL_CHOICES, REASONING_CHOICES, mapReasoningValue } from "../../../src/core/interactive/codex";
+
+it("maps extra high to xhigh", () => {
+  expect(mapReasoningValue("extra_high")).toBe("xhigh");
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun run test -- tests/core/interactive/codex.test.ts`
+Expected: FAIL (module missing).
+
+**Step 3: Implement minimal helpers**
+
+```ts
+export const MODEL_CHOICES = [
+  { id: "gpt-5.2-codex", title: "gpt-5.2-codex", description: "Latest frontier agentic coding model." },
+  // ...
+];
+
+export const REASONING_CHOICES = [
+  { id: "low", label: "Low", value: "low", description: "Fast responses with lighter reasoning" },
+  { id: "medium", label: "Medium (default)", value: "medium", description: "Balances speed and reasoning depth for everyday tasks" },
+  { id: "high", label: "High", value: "high", description: "Greater reasoning depth for complex problems" },
+  { id: "extra_high", label: "Extra high", value: "xhigh", description: "Extra high reasoning depth for complex problems" },
+];
+
+export const mapReasoningValue = (id: string) =>
+  REASONING_CHOICES.find((item) => item.id === id)?.value ?? "medium";
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun run test -- tests/core/interactive/codex.test.ts`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/core/interactive/codex.ts tests/core/interactive/codex.test.ts
+git commit -m "feat: codex interactive choices"
+```
+
+### Task 4: Implement codex command flow
+
+**Files:**
+- Modify: `src/cmd/codex.ts`
+- Modify: `src/cmd/index.ts` (if needed)
+- Modify: `tests/cmd/codex.test.ts`
+
+**Step 1: Implement flow**
+
+- Replace `registerEnvCommand` usage with custom `codex` command.
+- Use fuzzy selects for model + reasoning.
+- Use `selectConsumer` for key selection and fetch API key via `GetConsumer`.
+- Confirm summary before writing.
+- Write config/auth using helpers and set file permissions (0600).
+
+**Step 2: Run test to verify it passes**
+
+Run: `bun run test -- tests/cmd/codex.test.ts`
+Expected: PASS
+
+**Step 3: Commit**
+
+```bash
+git add src/cmd/codex.ts tests/cmd/codex.test.ts
+ git commit -m "feat: codex multistep config"
+```
+
+### Task 5: Update docs
+
+**Files:**
+- Modify: `README.md`
+- Modify: `README.zh-cn.md`
+- Modify: `README.ja.md`
+
+**Step 1: Update codex description**
+
+- Note that `getrouter codex` now configures `~/.codex/config.toml` + `~/.codex/auth.json`.
+- Remove or soften env/hook wording for codex only (claude still env-based).
+
+**Step 2: Commit**
+
+```bash
+git add README.md README.zh-cn.md README.ja.md
+ git commit -m "docs: update codex config flow"
+```
+
+### Task 6: Full verification
+
+**Step 1: Run tests**
+
+Run: `bun run test`
+Expected: PASS
+
+**Step 2: Run typecheck**
+
+Run: `bun run typecheck`
+Expected: PASS
+
+**Step 3: Run lint**
+
+Run: `bun run lint`
+Expected: PASS
+
+**Step 4: Run format**
+
+Run: `bun run format`
+Expected: PASS

package/docs/plans/2026-01-04-env-hook-design.md

@@ -0,0 +1,48 @@
+# Env Hook Auto-Source Design
+
+## Goals
+- Ensure `getrouter codex` / `getrouter claude` automatically `source` the generated env file in the **current shell** after successful execution.
+- Install a shell hook on `--install` that wraps `getrouter` and performs the auto-source step.
+- Keep existing behavior (env file generation, rc insertion) intact and best-effort.
+
+## Non-Goals
+- No new dependencies.
+- No attempt to force the current parent shell to reload rc automatically (shell limitation).
+- No new CLI flags in this iteration (use existing `--install`).
+
+## Behavior
+- `getrouter codex --install` / `getrouter claude --install` will:
+  - Write the env file (`env.sh` or `env.ps1`) as today.
+  - Write a shell hook file under `~/.getrouter/` (or `GETROUTER_CONFIG_DIR`).
+  - Append a `source`/dot-source line for the hook into the user’s rc file (idempotent).
+- Once the hook is loaded (by reloading rc or opening a new shell), any subsequent `getrouter codex` or `getrouter claude` call will:
+  - Run the real CLI command.
+  - If exit code is 0, `source` the env file to update variables in the current shell.
+
+## Hook Format
+- **bash/zsh**: `hook.sh` with a `getrouter()` wrapper that calls `command getrouter` to avoid recursion.
+- **fish**: `hook.fish` defining a `getrouter` function with `command getrouter`.
+- **pwsh**: `hook.ps1` defining `function getrouter { & getrouter @args; ...; . $envPath }`.
+- Hook resolves config dir dynamically at runtime:
+  - `GETROUTER_CONFIG_DIR` if set, else `~/.getrouter`.
+  - Env file path: `env.sh` for sh/fish, `env.ps1` for pwsh.
+
+## Error Handling
+- Hook is best-effort and silent on failures.
+- Auto-source only runs when the CLI exits successfully.
+
+## Testing Plan
+- Update `tests/core/setup/env.test.ts` to cover hook path + hook rendering output.
+- Update `tests/cmd/codex.test.ts` and `tests/cmd/claude.test.ts` to assert:
+  - Hook file is written.
+  - Rc file includes hook source line.
+
+## Files To Touch
+- `src/core/setup/env.ts`
+- `src/cmd/env.ts`
+- `tests/core/setup/env.test.ts`
+- `tests/cmd/codex.test.ts`
+- `tests/cmd/claude.test.ts`
+- `README.md`
+- `README.zh-cn.md`
+- `README.ja.md`

package/docs/plans/2026-01-04-env-hook-plan.md

@@ -0,0 +1,173 @@
+# Env Hook Auto-Source Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Install a shell hook on `--install` so `getrouter codex/claude` auto-sources env vars in the current shell.
+
+**Architecture:** Generate a shell-specific hook file and append a source line to the user’s rc file. The hook wraps `getrouter` and sources the env file after successful `codex/claude` runs.
+
+**Tech Stack:** TypeScript, Commander, Vitest, Node fs.
+
+### Task 1: Add failing tests for hook generation + installation
+
+**Files:**
+- Modify: `tests/core/setup/env.test.ts`
+- Modify: `tests/cmd/codex.test.ts`
+- Modify: `tests/cmd/claude.test.ts`
+
+**Step 1: Write the failing tests**
+
+```ts
+// tests/core/setup/env.test.ts
+import { getHookFilePath, renderHook } from "../../../src/core/setup/env";
+
+it("renders sh hook", () => {
+  const output = renderHook("bash");
+  expect(output).toContain("getrouter() {");
+  expect(output).toContain("command getrouter");
+  expect(output).toContain("source");
+});
+
+it("renders pwsh hook", () => {
+  const output = renderHook("pwsh");
+  expect(output).toContain("function getrouter");
+  expect(output).toContain("$LASTEXITCODE");
+});
+
+it("resolves hook file paths", () => {
+  expect(getHookFilePath("bash", "/tmp")).toBe("/tmp/hook.sh");
+  expect(getHookFilePath("zsh", "/tmp")).toBe("/tmp/hook.sh");
+  expect(getHookFilePath("fish", "/tmp")).toBe("/tmp/hook.fish");
+  expect(getHookFilePath("pwsh", "/tmp")).toBe("/tmp/hook.ps1");
+});
+```
+
+```ts
+// tests/cmd/codex.test.ts
+import { getHookFilePath } from "../../src/core/setup/env";
+
+it("installs hook into rc", async () => {
+  // ...existing setup...
+  await program.parseAsync(["node", "getrouter", "codex", "--install"]);
+  const hookPath = getHookFilePath("bash", dir);
+  expect(fs.existsSync(hookPath)).toBe(true);
+  const rcContent = fs.readFileSync(rcPath ?? "", "utf8");
+  expect(rcContent).toContain(`source ${hookPath}`);
+});
+```
+
+```ts
+// tests/cmd/claude.test.ts
+import { getHookFilePath } from "../../src/core/setup/env";
+
+it("installs hook into rc", async () => {
+  // ...existing setup...
+  await program.parseAsync(["node", "getrouter", "claude", "--install"]);
+  const hookPath = getHookFilePath("bash", dir);
+  expect(fs.existsSync(hookPath)).toBe(true);
+  const rcContent = fs.readFileSync(rcPath ?? "", "utf8");
+  expect(rcContent).toContain(`source ${hookPath}`);
+});
+```
+
+**Step 2: Run tests to verify they fail**
+
+Run: `bun run test -- tests/core/setup/env.test.ts`
+Expected: FAIL (missing exports)
+
+Run: `bun run test -- tests/cmd/codex.test.ts`
+Expected: FAIL (hook not created)
+
+**Step 3: Commit**
+
+```bash
+git add tests/core/setup/env.test.ts tests/cmd/codex.test.ts tests/cmd/claude.test.ts
+git commit -m "test: cover env hook installation"
+```
+
+### Task 2: Implement hook generation + installation
+
+**Files:**
+- Modify: `src/core/setup/env.ts`
+- Modify: `src/cmd/env.ts`
+
+**Step 1: Implement hook helpers**
+
+```ts
+export const getHookFilePath = (shell: RcShell, configDir: string) => {
+  if (shell === "pwsh") return path.join(configDir, "hook.ps1");
+  if (shell === "fish") return path.join(configDir, "hook.fish");
+  return path.join(configDir, "hook.sh");
+};
+
+export const renderHook = (shell: RcShell) => {
+  // return shell-specific wrapper that auto-sources env file
+};
+```
+
+**Step 2: Wire hook into `--install`**
+
+```ts
+const hookPath = getHookFilePath(shell, configDir);
+writeEnvFile(hookPath, renderHook(shell));
+appendRcIfMissing(rcPath, formatSourceLine(envShell, hookPath));
+```
+
+**Step 3: Run tests to verify they pass**
+
+Run: `bun run test -- tests/core/setup/env.test.ts`
+Expected: PASS
+
+Run: `bun run test -- tests/cmd/codex.test.ts`
+Expected: PASS
+
+Run: `bun run test -- tests/cmd/claude.test.ts`
+Expected: PASS
+
+**Step 4: Commit**
+
+```bash
+git add src/core/setup/env.ts src/cmd/env.ts
+git commit -m "feat: install env auto-source hook"
+```
+
+### Task 3: Update docs
+
+**Files:**
+- Modify: `README.md`
+- Modify: `README.zh-cn.md`
+- Modify: `README.ja.md`
+
+**Step 1: Add install hook note**
+
+- Mention `--install` adds a shell hook that auto-sources env after `codex/claude`.
+- Add a short note: reload your shell or `source ~/.zshrc` once to activate.
+
+**Step 2: Commit**
+
+```bash
+git add README.md README.zh-cn.md README.ja.md
+git commit -m "docs: document env auto-source hook"
+```
+
+### Task 4: Full verification
+
+**Step 1: Run tests**
+
+Run: `bun run test`
+Expected: PASS
+
+**Step 2: Run typecheck**
+
+Run: `bun run typecheck`
+Expected: PASS
+
+**Step 3: Run lint**
+
+Run: `bun run lint`
+Expected: PASS
+
+**Step 4: Run format**
+
+Run: `bun run format`
+Expected: PASS