@getrouter/getrouter-cli 0.1.0

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

@@ -0,0 +1,327 @@
+# getrouter CLI Scaffold Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Set up a Node/TypeScript CLI scaffold for `getrouter` with build/test tooling, a minimal command tree, and initial core utilities.
+
+**Architecture:** A thin CLI layer built on `commander` with an entrypoint in `src/bin.ts`, a program factory in `src/cli.ts`, placeholder command modules in `src/cmd/*`, and a small `core` utility for config paths. Build with `tsup` and test with `vitest`.
+
+**Tech Stack:** Node.js 18+, TypeScript, commander, tsup, vitest.
+
+---
+
+### Task 1: Tooling & Project Bootstrap
+
+**Files:**
+- Create: `package.json`
+- Create: `tsconfig.json`
+- Create: `tsup.config.ts`
+- Create: `vitest.config.ts`
+- Create: `src/.gitkeep`
+- Create: `tests/.gitkeep`
+
+**Step 1: Create package.json**
+
+```json
+{
+  "name": "getrouter",
+  "version": "0.1.0",
+  "description": "CLI for getrouter.dev",
+  "bin": {
+    "getrouter": "dist/bin.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/bin.ts --help",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.12",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  }
+}
+```
+
+**Step 2: Create tsconfig.json**
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "rootDir": "src",
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "moduleResolution": "node",
+    "skipLibCheck": true
+  },
+  "include": ["src", "tests"]
+}
+```
+
+**Step 3: Create tsup.config.ts**
+
+```ts
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/bin.ts"],
+  format: ["cjs"],
+  sourcemap: true,
+  clean: true,
+});
+```
+
+**Step 4: Create vitest.config.ts**
+
+```ts
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["tests/**/*.test.ts"],
+  },
+});
+```
+
+**Step 5: Add placeholder directories**
+
+Create empty files to ensure directories are tracked:
+
+- `src/.gitkeep`
+- `tests/.gitkeep`
+
+**Step 6: Install deps**
+
+Run: `npm install`  
+Expected: dependencies installed.
+
+**Step 7: Sanity check tooling**
+
+Run: `npm run typecheck`  
+Expected: PASS (no TS files yet).
+
+**Step 8: Commit**
+
+```bash
+git add package.json tsconfig.json tsup.config.ts vitest.config.ts src/.gitkeep tests/.gitkeep
+git commit -m "chore: bootstrap cli tooling"
+```
+
+---
+
+### Task 2: Minimal CLI Program (TDD)
+
+**Files:**
+- Create: `src/cli.ts`
+- Create: `src/bin.ts`
+- Create: `tests/cli.test.ts`
+
+**Step 1: Write the failing test**
+
+```ts
+import { describe, it, expect } from "vitest";
+import { createProgram } from "../src/cli";
+
+describe("getrouter cli", () => {
+  it("exposes name and help", () => {
+    const program = createProgram();
+    expect(program.name()).toBe("getrouter");
+    expect(program.helpInformation()).toContain("getrouter");
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `npm test`  
+Expected: FAIL (module not found or createProgram missing).
+
+**Step 3: Write minimal implementation**
+
+`src/cli.ts`
+
+```ts
+import { Command } from "commander";
+
+export const createProgram = () => {
+  const program = new Command();
+  program
+    .name("getrouter")
+    .description("CLI for getrouter.dev")
+    .version("0.1.0");
+  return program;
+};
+```
+
+`src/bin.ts`
+
+```ts
+#!/usr/bin/env node
+import { createProgram } from "./cli";
+
+createProgram().parse(process.argv);
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `npm test`  
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add src/cli.ts src/bin.ts tests/cli.test.ts
+git commit -m "feat: add minimal cli entrypoint"
+```
+
+---
+
+### Task 3: Command Tree Skeleton
+
+**Files:**
+- Create: `src/cmd/index.ts`
+- Create: `src/cmd/auth.ts`
+- Create: `src/cmd/keys.ts`
+- Create: `src/cmd/subscription.ts`
+- Create: `src/cmd/plans.ts`
+- Create: `src/cmd/models.ts`
+- Create: `src/cmd/providers.ts`
+- Create: `src/cmd/user.ts`
+- Modify: `src/cli.ts`
+
+**Step 1: Implement command modules**
+
+Example (`src/cmd/auth.ts`):
+
+```ts
+import { Command } from "commander";
+
+export const registerAuthCommands = (program: Command) => {
+  const auth = program.command("auth").description("Authentication");
+  auth.command("login").description("Login with GitHub OAuth");
+  auth.command("logout").description("Clear local auth state");
+  auth.command("status").description("Show current auth status");
+};
+```
+
+Repeat similarly for:
+- `keys` (list/create/update/delete/get)
+- `subscription` (show)
+- `plans` (list)
+- `models` (list)
+- `providers` (list)
+- `user` (current)
+
+`src/cmd/index.ts`:
+
+```ts
+import { Command } from "commander";
+import { registerAuthCommands } from "./auth";
+import { registerKeysCommands } from "./keys";
+import { registerSubscriptionCommands } from "./subscription";
+import { registerPlansCommands } from "./plans";
+import { registerModelsCommands } from "./models";
+import { registerProvidersCommands } from "./providers";
+import { registerUserCommands } from "./user";
+
+export const registerCommands = (program: Command) => {
+  registerAuthCommands(program);
+  registerKeysCommands(program);
+  registerSubscriptionCommands(program);
+  registerPlansCommands(program);
+  registerModelsCommands(program);
+  registerProvidersCommands(program);
+  registerUserCommands(program);
+};
+```
+
+**Step 2: Wire command tree**
+
+Modify `src/cli.ts`:
+
+```ts
+import { Command } from "commander";
+import { registerCommands } from "./cmd";
+
+export const createProgram = () => {
+  const program = new Command();
+  program
+    .name("getrouter")
+    .description("CLI for getrouter.dev")
+    .version("0.1.0");
+  registerCommands(program);
+  return program;
+};
+```
+
+**Step 3: Run tests**
+
+Run: `npm test`  
+Expected: PASS.
+
+**Step 4: Commit**
+
+```bash
+git add src/cmd src/cli.ts
+git commit -m "feat: add command tree skeleton"
+```
+
+---
+
+### Task 4: Core Paths Utility (TDD)
+
+**Files:**
+- Create: `src/core/paths.ts`
+- Create: `tests/paths.test.ts`
+
+**Step 1: Write the failing test**
+
+```ts
+import { describe, it, expect } from "vitest";
+import { getConfigDir } from "../src/core/paths";
+
+describe("paths", () => {
+  it("returns ~/.getrouter path", () => {
+    const dir = getConfigDir();
+    expect(dir).toContain(".getrouter");
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `npm test`  
+Expected: FAIL (module not found).
+
+**Step 3: Write minimal implementation**
+
+```ts
+import path from "node:path";
+import os from "node:os";
+
+export const getConfigDir = () => path.join(os.homedir(), ".getrouter");
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `npm test`  
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add src/core/paths.ts tests/paths.test.ts
+git commit -m "feat: add config path helper"
+```

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

@@ -0,0 +1,68 @@
+# getrouter CLI 认证设计（OAuth 未就绪占位）
+
+日期：2026-01-02  
+状态：已确认
+
+## 背景
+- getrouter OAuth/设备码流程仍在开发中，需要先提供 CLI 占位行为以保证体验一致与可预测。
+- 当前阶段不写入虚假 token，避免误导用户或污染本地状态。
+
+## 目标与范围（当前阶段）
+- `auth login` 提示“OAuth 未就绪”，不写入 `auth.json`。
+- `auth logout` 清理本地认证文件。
+- `auth status` 做本地判断，输出“远端验证待开放”。
+- 输出支持 `--json`，默认人类可读。
+
+## 非目标（当前阶段）
+- 不启动本地回调服务。
+- 不与任何 OAuth/设备码接口通信。
+- 不校验远端用户状态。
+
+## 命令与交互
+- `getrouter auth login`
+  - 输出提示：OAuth 仍在开发中，暂不支持登录。
+  - 不写入或修改 `~/.getrouter/auth.json`。
+- `getrouter auth logout`
+  - 删除或清空 `~/.getrouter/auth.json`。
+  - 输出“已清除本地认证信息”。
+- `getrouter auth status`
+  - 读取 `auth.json`（如存在），检查字段完整性与过期时间。
+  - 若缺失或过期：显示“未登录”。
+  - 若完整且未过期：显示“已登录（仅本地验证，远端验证待开放）”。
+
+## 存储与字段
+- 认证文件：`~/.getrouter/auth.json`
+- 结构：
+  ```json
+  {
+    "accessToken": "...",
+    "refreshToken": "...",
+    "expiresAt": "2026-01-02T00:00:00Z",
+    "tokenType": "Bearer"
+  }
+  ```
+- `tokenType` 默认 `Bearer`（后续真实 OAuth 可覆盖）。
+- `expiresAt` 使用 ISO8601 字符串。
+- *nix 系统写入时强制 `0600` 权限；Windows 保持默认 ACL。
+
+## 输出与脱敏
+- 默认输出脱敏 token（仅显示前后 4 位）。
+- 仅在 `--show-secret` 下展示完整 token。
+- `--json` 输出结构化字段：`status`、`expiresAt`、`note`。
+
+## 错误处理
+- JSON 解析失败、无权限写入等：提示路径与修复建议，返回非零退出码。
+- 远端校验未实现时，`auth status` 明确标注“远端验证待开放”。
+
+## 测试策略
+- 单测覆盖：
+  - 状态判定（未登录/已登录/过期）。
+  - `tokenType` 默认值与 `expiresAt` 解析。
+  - `auth login` 只提示不落盘。
+  - `auth logout` 清理文件。
+- *nix 下断言 `0600`；Windows 仅断言写入成功。
+
+## 未来接入 OAuth 的扩展点
+- 登录流程：本地回调 + 浏览器打开 + 回调接口换 token。
+- `auth status` 增加“远端验证”调用。
+- `core/http` 可扩展 401 触发 refresh 并重试。

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

@@ -0,0 +1,73 @@
+# getrouter CLI 设备码式登录设计
+
+日期：2026-01-02
+
+## 背景与目标
+
+现有 CLI 的 `auth login` 仅提示 OAuth 未就绪。根据最新 auth 流程，CLI 需改为类似 tailscale 的设备码式登录：
+- CLI 本地生成 `auth_code`（13 位小写 base32）
+- 打开浏览器访问 `https://getrouter.dev/#/a/{auth_code}`
+- CLI 轮询 `POST /v1/dashboard/auth/authorize`，body `{ code: auth_code }`
+- 成功返回 `AuthToken` 后写入 `~/.getrouter/auth.json`
+
+## 关键流程
+
+1. `auth login` 生成 `auth_code`（13 位小写 base32）。
+2. 输出登录 URL，并尝试自动打开浏览器（macOS: `open`；Windows: `start`；Linux: `xdg-open`）。失败不阻断流程。
+3. CLI 进入轮询：
+   - 请求：`POST /v1/dashboard/auth/authorize`，body `{ code: auth_code }`
+   - 成功：HTTP 200 + `AuthToken`
+   - 未确认：HTTP 404（AUTH not found）→ 继续轮询
+   - 已兑换：HTTP 400（code already exchanged）→ 失败退出
+   - 过期：HTTP 403（token expired）→ 失败退出
+   - 其他 4xx/5xx：失败退出
+4. 轮询策略：指数退避 1s → 2s → 4s → 8s → 10s（封顶），总超时 5 分钟。
+5. 成功后写入 `auth.json`，并输出“登录成功”。
+6. Ctrl+C 中断轮询并提示“已取消登录”。
+
+## 数据与存储
+
+- `AuthToken` 字段：`access_token`、`refresh_token`、`expires_at`。
+- 写入位置：`~/.getrouter/auth.json` 或 `GETROUTER_CONFIG_DIR` 指定路径。
+- 文件权限：`0600`（已有 `writeAuth` 逻辑覆盖）。
+
+## 错误处理
+
+- 404：视为“未确认”，继续轮询。
+- 400：视为“已兑换”，提示重新登录。
+- 403：视为“已过期”，提示重新登录。
+- 其他状态：直接失败，提示重试。
+
+## CLI 交互示例
+
+```
+To authenticate, visit:
+https://getrouter.dev/#/a/<auth_code>
+Waiting for confirmation...
+```
+
+成功后：
+```
+登录成功
+```
+
+## 需要改动的模块
+
+- `src/cmd/auth.ts`：实现设备码式登录流程。
+- `src/core/auth/`：新增设备码登录辅助函数（生成 auth_code、打开浏览器、轮询）。
+- `src/core/api/client.ts`：注入 `createAuthServiceClient`。
+- `src/generated/router/dashboard/v1/index.ts`：确保包含 `AuthService.Authorize`（已生成）。
+- 测试：新增/更新 `tests/cmd/auth.test.ts` 等。
+
+## 测试建议
+
+1. 轮询遇到 404 时继续，直到成功获取 token。
+2. 400/403 立即失败退出。
+3. 超时（5 分钟）后提示失败。
+4. 成功时写入 `auth.json` 且权限正确。
+5. 浏览器打开失败不影响轮询。
+
+## 不在范围内
+
+- OAuth callback / 旧流程保留。
+- 后端接口改动。