@getrouter/getrouter-cli 0.1.0

package/docs/plans/2026-01-01-getrouter-cli-config-command-plan.md

@@ -0,0 +1,231 @@
+# Config Commands Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add `getrouter config get/set` commands with fixed keys (`apiBase`, `json`), validation, and JSON output option.
+
+**Architecture:** Implement a `config` command module under `src/cmd/config.ts` that uses the `core/config` read/write helpers. Keep parsing/validation in the command layer, with small pure helpers for value parsing and apiBase normalization to make testing easier.
+
+**Tech Stack:** TypeScript, commander, vitest.
+
+---
+
+### Task 1: Parse/Normalize Helpers (TDD)
+
+**Files:**
+- Create: `src/cmd/config-helpers.ts`
+- Test: `tests/cmd/config-helpers.test.ts`
+
+**Step 1: Write the failing test**
+
+```ts
+import { describe, it, expect } from "vitest";
+import { normalizeApiBase, parseConfigValue } from "../../src/cmd/config-helpers";
+
+describe("config helpers", () => {
+  it("normalizes apiBase", () => {
+    expect(normalizeApiBase("https://getrouter.dev/")).toBe("https://getrouter.dev");
+  });
+
+  it("parses json values", () => {
+    expect(parseConfigValue("json", "true")).toBe(true);
+    expect(parseConfigValue("json", "0")).toBe(false);
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `npm test`  
+Expected: FAIL (module not found).
+
+**Step 3: Write minimal implementation**
+
+```ts
+export const normalizeApiBase = (value: string) =>
+  value.trim().replace(/\\/+$/, "");
+
+export const parseConfigValue = (key: "apiBase" | "json", raw: string) => {
+  if (key === "apiBase") {
+    const normalized = normalizeApiBase(raw);
+    if (!/^https?:\\/\\//.test(normalized)) {
+      throw new Error("apiBase must start with http:// or https://");
+    }
+    return normalized;
+  }
+  const lowered = raw.toLowerCase();
+  if (["true", "1"].includes(lowered)) return true;
+  if (["false", "0"].includes(lowered)) return false;
+  throw new Error("json must be true/false or 1/0");
+};
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `npm test`  
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add src/cmd/config-helpers.ts tests/cmd/config-helpers.test.ts
+git commit -m "feat: add config parsing helpers"
+```
+
+---
+
+### Task 2: Config Command (TDD)
+
+**Files:**
+- Create: `src/cmd/config.ts`
+- Modify: `src/cmd/index.ts`
+- Test: `tests/cmd/config.test.ts`
+
+**Step 1: Write the failing test**
+
+```ts
+import { describe, it, expect, vi } from "vitest";
+import { createProgram } from "../../src/cli";
+
+describe("config command", () => {
+  it("prints full config for get", async () => {
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    const program = createProgram();
+    await program.parseAsync(["node", "getrouter", "config", "get"]);
+    expect(log).toHaveBeenCalled();
+    log.mockRestore();
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `npm test`  
+Expected: FAIL (config command missing).
+
+**Step 3: Implement minimal config command**
+
+`src/cmd/config.ts`
+
+```ts
+import { Command } from "commander";
+import { readConfig, writeConfig } from "../core/config";
+import { parseConfigValue } from "./config-helpers";
+
+const VALID_KEYS = new Set(["apiBase", "json"]);
+
+export const registerConfigCommands = (program: Command) => {
+  const config = program.command("config").description("Manage CLI config");
+
+  config
+    .command("get")
+    .argument("[key]")
+    .option("--json", "Output JSON")
+    .action((key: string | undefined, options: { json?: boolean }) => {
+      const cfg = readConfig();
+      if (!key) {
+        if (options.json) {
+          console.log(JSON.stringify(cfg, null, 2));
+        } else {
+          console.log(`apiBase=${cfg.apiBase}`);
+          console.log(`json=${cfg.json}`);
+        }
+        return;
+      }
+      if (!VALID_KEYS.has(key)) {
+        throw new Error("Unknown config key");
+      }
+      const value = (cfg as any)[key];
+      if (options.json) {
+        console.log(JSON.stringify({ [key]: value }, null, 2));
+      } else {
+        console.log(`${key}=${value}`);
+      }
+    });
+
+  config
+    .command("set")
+    .argument("<key>")
+    .argument("<value>")
+    .option("--json", "Output JSON")
+    .action((key: string, value: string, options: { json?: boolean }) => {
+      if (!VALID_KEYS.has(key)) {
+        throw new Error("Unknown config key");
+      }
+      const cfg = readConfig();
+      const parsed = parseConfigValue(key as "apiBase" | "json", value);
+      const next = { ...cfg, [key]: parsed };
+      writeConfig(next);
+      if (options.json) {
+        console.log(JSON.stringify(next, null, 2));
+      } else {
+        console.log(`${key}=${(next as any)[key]}`);
+      }
+    });
+};
+```
+
+`src/cmd/index.ts` add:
+
+```ts
+import { registerConfigCommands } from "./config";
+// ...
+registerConfigCommands(program);
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `npm test`  
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add src/cmd/config.ts src/cmd/index.ts tests/cmd/config.test.ts
+git commit -m "feat: add config get/set commands"
+```
+
+---
+
+### Task 3: Validation & Error Tests (TDD)
+
+**Files:**
+- Modify: `tests/cmd/config.test.ts`
+
+**Step 1: Write failing tests**
+
+```ts
+import { describe, it, expect } from "vitest";
+import { parseConfigValue } from "../../src/cmd/config-helpers";
+
+describe("config validation", () => {
+  it("rejects invalid json value", () => {
+    expect(() => parseConfigValue("json", "nope")).toThrow();
+  });
+
+  it("rejects invalid apiBase", () => {
+    expect(() => parseConfigValue("apiBase", "ftp://bad")).toThrow();
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `npm test`  
+Expected: FAIL if behavior not enforced.
+
+**Step 3: Implement minimal fixes**
+
+Adjust `parseConfigValue` as needed (should already throw for invalid).
+
+**Step 4: Run test to verify it passes**
+
+Run: `npm test`  
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add tests/cmd/config.test.ts src/cmd/config-helpers.ts
+git commit -m "test: cover config validation"
+```

package/docs/plans/2026-01-01-getrouter-cli-config-core-plan.md

@@ -0,0 +1,307 @@
+# getrouter CLI Config Core Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Build the core config/auth file IO utilities for `~/.getrouter`, including read/write helpers, defaults, and safe redaction for output.
+
+**Architecture:** Add a small `core/config` module that reads/writes JSON files under `~/.getrouter`, exposes typed helpers for config and auth state, and includes a redaction utility for secrets. Use sync file IO for simplicity in CLI startup paths.
+
+**Tech Stack:** Node.js fs/path/os, TypeScript, vitest.
+
+---
+
+### Task 1: Auth & Config Types
+
+**Files:**
+- Create: `src/core/config/types.ts`
+- Test: `tests/config/types.test.ts`
+
+**Step 1: Write the failing test**
+
+```ts
+import { describe, it, expect } from "vitest";
+import { defaultConfig, defaultAuthState } from "../../src/core/config/types";
+
+describe("config types defaults", () => {
+  it("provides sane defaults", () => {
+    expect(defaultConfig().apiBase).toBe("https://getrouter.dev");
+    expect(defaultConfig().json).toBe(false);
+    expect(defaultAuthState().accessToken).toBe("");
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `npm test`  
+Expected: FAIL (module not found).
+
+**Step 3: Write minimal implementation**
+
+```ts
+export type ConfigFile = {
+  apiBase: string;
+  json: boolean;
+};
+
+export type AuthState = {
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: string;
+};
+
+export const defaultConfig = (): ConfigFile => ({
+  apiBase: "https://getrouter.dev",
+  json: false,
+});
+
+export const defaultAuthState = (): AuthState => ({
+  accessToken: "",
+  refreshToken: "",
+  expiresAt: "",
+});
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `npm test`  
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add src/core/config/types.ts tests/config/types.test.ts
+git commit -m "feat: add config/auth types and defaults"
+```
+
+---
+
+### Task 2: Config Paths & File Helpers (TDD)
+
+**Files:**
+- Create: `src/core/config/paths.ts`
+- Create: `src/core/config/fs.ts`
+- Test: `tests/config/paths.test.ts`
+- Test: `tests/config/fs.test.ts`
+
+**Step 1: Write failing tests**
+
+`tests/config/paths.test.ts`
+
+```ts
+import { describe, it, expect } from "vitest";
+import { getAuthPath, getConfigPath } from "../../src/core/config/paths";
+
+describe("config paths", () => {
+  it("returns ~/.getrouter paths", () => {
+    expect(getConfigPath()).toContain(".getrouter");
+    expect(getConfigPath()).toContain("config.json");
+    expect(getAuthPath()).toContain("auth.json");
+  });
+});
+```
+
+`tests/config/fs.test.ts`
+
+```ts
+import { describe, it, expect } from "vitest";
+import { readJsonFile, writeJsonFile } from "../../src/core/config/fs";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+describe("config fs", () => {
+  it("writes and reads JSON", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "getrouter-"));
+    const file = path.join(dir, "config.json");
+    writeJsonFile(file, { hello: "world" });
+    expect(readJsonFile(file)).toEqual({ hello: "world" });
+  });
+});
+```
+
+**Step 2: Run tests to verify they fail**
+
+Run: `npm test`  
+Expected: FAIL (module not found).
+
+**Step 3: Implement minimal helpers**
+
+`src/core/config/paths.ts`
+
+```ts
+import path from "node:path";
+import { getConfigDir } from "../paths";
+
+export const getConfigPath = () => path.join(getConfigDir(), "config.json");
+export const getAuthPath = () => path.join(getConfigDir(), "auth.json");
+```
+
+`src/core/config/fs.ts`
+
+```ts
+import fs from "node:fs";
+
+export const readJsonFile = <T = unknown>(filePath: string): T | null => {
+  if (!fs.existsSync(filePath)) return null;
+  const raw = fs.readFileSync(filePath, "utf8");
+  return JSON.parse(raw) as T;
+};
+
+export const writeJsonFile = (filePath: string, value: unknown) => {
+  fs.mkdirSync(require("node:path").dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(value, null, 2), "utf8");
+};
+```
+
+**Step 4: Run tests to verify they pass**
+
+Run: `npm test`  
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add src/core/config/paths.ts src/core/config/fs.ts tests/config/paths.test.ts tests/config/fs.test.ts
+git commit -m "feat: add config path and fs helpers"
+```
+
+---
+
+### Task 3: Config/Auth Read & Write (TDD)
+
+**Files:**
+- Create: `src/core/config/index.ts`
+- Test: `tests/config/index.test.ts`
+
+**Step 1: Write the failing test**
+
+```ts
+import { describe, it, expect } from "vitest";
+import { readConfig, writeConfig, readAuth, writeAuth } from "../../src/core/config";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+describe("config read/write", () => {
+  it("writes and reads config with defaults", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "getrouter-"));
+    process.env.GETROUTER_CONFIG_DIR = dir;
+    writeConfig({ apiBase: "https://getrouter.dev", json: true });
+    const cfg = readConfig();
+    expect(cfg.apiBase).toBe("https://getrouter.dev");
+    expect(cfg.json).toBe(true);
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `npm test`  
+Expected: FAIL (module not found).
+
+**Step 3: Implement minimal read/write**
+
+`src/core/config/index.ts`
+
+```ts
+import path from "node:path";
+import { defaultConfig, defaultAuthState, ConfigFile, AuthState } from "./types";
+import { readJsonFile, writeJsonFile } from "./fs";
+
+const resolveConfigDir = () =>
+  process.env.GETROUTER_CONFIG_DIR ||
+  path.join(require("node:os").homedir(), ".getrouter");
+
+const getConfigPath = () => path.join(resolveConfigDir(), "config.json");
+const getAuthPath = () => path.join(resolveConfigDir(), "auth.json");
+
+export const readConfig = (): ConfigFile => ({
+  ...defaultConfig(),
+  ...(readJsonFile<ConfigFile>(getConfigPath()) ?? {}),
+});
+
+export const writeConfig = (cfg: ConfigFile) => writeJsonFile(getConfigPath(), cfg);
+
+export const readAuth = (): AuthState => ({
+  ...defaultAuthState(),
+  ...(readJsonFile<AuthState>(getAuthPath()) ?? {}),
+});
+
+export const writeAuth = (auth: AuthState) => writeJsonFile(getAuthPath(), auth);
+```
+
+**Step 4: Run tests to verify they pass**
+
+Run: `npm test`  
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add src/core/config/index.ts tests/config/index.test.ts
+git commit -m "feat: add config/auth read write helpers"
+```
+
+---
+
+### Task 4: Redaction Utility (TDD)
+
+**Files:**
+- Create: `src/core/config/redact.ts`
+- Test: `tests/config/redact.test.ts`
+
+**Step 1: Write the failing test**
+
+```ts
+import { describe, it, expect } from "vitest";
+import { redactSecrets } from "../../src/core/config/redact";
+
+describe("redact", () => {
+  it("redacts known secret fields", () => {
+    const out = redactSecrets({
+      accessToken: "secret",
+      refreshToken: "secret2",
+      apiKey: "key",
+      other: "ok",
+    });
+    expect(out.accessToken).toBe("****");
+    expect(out.refreshToken).toBe("****");
+    expect(out.apiKey).toBe("****");
+    expect(out.other).toBe("ok");
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `npm test`  
+Expected: FAIL (module not found).
+
+**Step 3: Implement minimal redaction**
+
+```ts
+const SECRET_KEYS = new Set(["accessToken", "refreshToken", "apiKey"]);
+
+export const redactSecrets = <T extends Record<string, any>>(obj: T): T => {
+  const out = { ...obj } as T;
+  for (const key of Object.keys(out)) {
+    if (SECRET_KEYS.has(key)) {
+      out[key] = "****";
+    }
+  }
+  return out;
+};
+```
+
+**Step 4: Run tests to verify they pass**
+
+Run: `npm test`  
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add src/core/config/redact.ts tests/config/redact.test.ts
+git commit -m "feat: add secret redaction helper"
+```

package/docs/plans/2026-01-01-getrouter-cli-design.md

@@ -0,0 +1,106 @@
+# getrouter CLI 设计（v1）
+
+日期：2026-01-01  
+状态：已确认
+
+## 背景与目标
+- 面向 getrouter.dev 用户提供本地 CLI，覆盖 API Key 管理、订阅查询与自动配置 Codex/Claude 环境。
+- 与现有 dashboard API 保持一致，减少接口漂移与重复维护成本。
+- 默认人类可读输出，支持 `--json` 供脚本自动化。
+
+## 非目标（v1）
+- 不支持组织/工作区切换（未来版本再做）。
+- 不接入 admin API、账单明细、provider/model 写操作。
+- 设备码 OAuth 流程等待后端接口就绪后再开放。
+
+## 需求与功能范围
+- 登录/登出/状态：GitHub OAuth（浏览器回调 + 设备码扩展点）。
+- API Key 管理：Consumer 多 key 的 list/create/update/delete/get。
+- 订阅与计划：当前订阅、计划列表。
+- 只读资源：模型列表、供应商列表、当前用户信息。
+- 环境配置：生成 `~/.getrouter/` 配置与可选 shell 注入，支持 Codex/Claude。
+
+## 方案选型
+**推荐**：复用由 proto 生成的 TypeScript HTTP client（dashboard 同源），CLI 仅封装配置/鉴权/输出层。  
+**理由**：与后端一致、类型稳定、交付最快。
+
+## 架构与模块
+```
+cmd/        命令与交互（login/keys/subscription/setup）
+core/
+  auth/     OAuth 流程、token 刷新与存储
+  config/   ~/.getrouter 读写、权限、脱敏
+  output/   表格输出、--json、错误格式化
+api/        统一 requestHandler + 生成 client
+templates/  env.sh / env.ps1 模板
+```
+
+## 命令设计（建议）
+- `getrouter auth login|logout|status`
+- `getrouter keys list|create|update|delete|get`
+- `getrouter subscription show`
+- `getrouter plans list`
+- `getrouter models list`
+- `getrouter providers list`
+- `getrouter user current`
+- `getrouter setup env [--shell zsh|bash|fish|pwsh]`
+- `getrouter config get|set`
+
+## 认证与 Token
+- 访问管理 API 统一使用 `Authorization: Bearer <access_token>`。
+- token 保存于 `~/.getrouter/auth.json`（明文），文件权限 *nix 600。
+- access 过期后尝试 refresh；刷新失败则提示重新登录。
+- 设备码流程待后端完成后接入（命令入口可先预留）。
+
+## API 映射（当前 dashboard HTTP）
+管理 API 前缀：`https://getrouter.dev/v1`  
+注：生成 client 的 path 已包含 `v1/...`，CLI 建议配置 `api_base=https://getrouter.dev` 以避免双 `v1`。
+
+- OAuth Connect：`GET /v1/dashboard/identities/connect?type=GITHUB`
+- OAuth Callback：`GET /v1/dashboard/identities/GITHUB/callback?code=...&state=...`
+- 当前用户：`GET /v1/dashboard/users/current`
+- 订阅：`GET /v1/dashboard/subscriptions/current`
+- 计划列表：`GET /v1/dashboard/plans`
+- Consumer：
+  - `GET /v1/dashboard/consumers`
+  - `GET /v1/dashboard/consumers/:id`
+  - `POST /v1/dashboard/consumers/create`
+  - `PUT /v1/dashboard/consumers/update?updateMask=...`
+  - `DELETE /v1/dashboard/consumers/:id`
+- 模型列表：`GET /v1/dashboard/models`
+- 供应商列表：`GET /v1/dashboard/providers`
+
+## 配置与环境变量
+目录统一在 `~/.getrouter/`：
+- `auth.json`：token 与过期时间
+- `config.json`：API base、默认 consumer 等
+- `env.sh` / `env.ps1`：可选环境变量脚本
+
+环境变量（用于 Codex/Claude）：
+- `OPENAI_BASE_URL=https://api.getrouter.dev/v1`
+- `OPENAI_API_KEY=<consumer api key>`
+- `ANTHROPIC_BASE_URL=https://api.getrouter.dev/v1`
+- `ANTHROPIC_API_KEY=<consumer api key>`
+
+## 输出格式
+- 默认人类可读（表格/摘要）。
+- `--json` 输出结构化数据，错误也保持 JSON（code/message/details/status）。
+- 默认脱敏 token 与 API key；必要时提供 `--show-secret` 明示。
+
+## 错误处理与重试
+- 统一错误包装：`code/message/details/status`。
+- 仅对幂等 GET 做一次指数退避重试。
+- 401/403 明确提示 `getrouter auth login`。
+
+## 测试策略
+- 单测：配置读写、URL 拼装、错误映射、脱敏、输出格式。
+- 集成：mock server 或 staging（若未来提供）。
+
+## 发布与分发
+- npm 包（`npx getrouter` 或全局安装）。
+- GitHub Releases 提供平台说明与安装指引。
+
+## 待确认/风险
+- refresh token 的字段名、过期策略与刷新接口。
+- 设备码 OAuth 的具体 endpoint 与回调协议。
+- 管理 API base 与 `v1` 路径的最终规范（避免双重 `v1`）。