@getrouter/getrouter-cli 0.1.0

package/docs/plans/2026-01-02-getrouter-cli-keys-interactive-plan.md

@@ -0,0 +1,247 @@
+# Keys Interactive Selection Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add interactive key selection for `keys get/update/delete` when `id` is omitted, with non-TTY fallback errors and delete confirmation.
+
+**Architecture:** Introduce a small interactive helper using `prompts` to select a key from `ListConsumers` (sorted by `createdAt` desc) and confirm deletes. Update `cmd/keys` to make `id` optional, gate on `process.stdin.isTTY`, and route through selection/confirmation while keeping `--json` output unchanged.
+
+**Tech Stack:** TypeScript, Commander, Vitest, prompts.
+
+**Skills:** @superpowers:test-driven-development, @superpowers:systematic-debugging (if failures)
+
+### Task 1: Add prompts dependency and failing tests for interactive selection
+
+**Files:**
+- Modify: `package.json`
+- Modify: `package-lock.json`
+- Modify: `tests/cmd/keys.test.ts`
+
+**Step 1: Add prompts dependency**
+
+Run: `npm install prompts`
+
+**Step 2: Write the failing tests**
+
+```ts
+import prompts from "prompts";
+import { describe, it, expect, vi, afterEach } from "vitest";
+
+const originalIsTTY = process.stdin.isTTY;
+const setStdinTTY = (value: boolean) => {
+  Object.defineProperty(process.stdin, "isTTY", {
+    value,
+    configurable: true,
+  });
+};
+
+afterEach(() => {
+  setStdinTTY(originalIsTTY);
+  prompts.inject([]);
+});
+
+it("get selects newest key when id is missing", async () => {
+  setStdinTTY(true);
+  prompts.inject([0]);
+  const listConsumers = vi.fn().mockResolvedValue({
+    consumers: [
+      { id: "old", name: "old", enabled: true, createdAt: "2026-01-01T00:00:00Z" },
+      { id: "new", name: "new", enabled: true, createdAt: "2026-01-02T00:00:00Z" },
+    ],
+  });
+  const getConsumer = vi
+    .fn()
+    .mockResolvedValue({ ...mockConsumer, id: "new" });
+  (createApiClients as unknown as ReturnType<typeof vi.fn>).mockReturnValue({
+    consumerService: { ListConsumers: listConsumers, GetConsumer: getConsumer },
+    subscriptionService: {} as any,
+  });
+  const log = vi.spyOn(console, "log").mockImplementation(() => {});
+  const program = createProgram();
+  await program.parseAsync(["node", "getrouter", "keys", "get"]);
+  expect(getConsumer).toHaveBeenCalledWith({ id: "new" });
+  log.mockRestore();
+});
+
+it("delete does not run when confirmation is declined", async () => {
+  setStdinTTY(true);
+  prompts.inject([0, false]);
+  const deleteConsumer = vi.fn().mockResolvedValue({});
+  const listConsumers = vi.fn().mockResolvedValue({
+    consumers: [
+      { id: "c1", name: "dev", enabled: true, createdAt: "2026-01-01T00:00:00Z" },
+    ],
+  });
+  (createApiClients as unknown as ReturnType<typeof vi.fn>).mockReturnValue({
+    consumerService: { ListConsumers: listConsumers, DeleteConsumer: deleteConsumer },
+    subscriptionService: {} as any,
+  });
+  const log = vi.spyOn(console, "log").mockImplementation(() => {});
+  const program = createProgram();
+  await program.parseAsync(["node", "getrouter", "keys", "delete"]);
+  expect(deleteConsumer).not.toHaveBeenCalled();
+  log.mockRestore();
+});
+
+it("get without id fails in non-tty mode", async () => {
+  setStdinTTY(false);
+  const program = createProgram();
+  await expect(
+    program.parseAsync(["node", "getrouter", "keys", "get"])
+  ).rejects.toThrow("缺少 id");
+});
+```
+
+**Step 3: Run test to verify it fails**
+
+Run: `npm test -- tests/cmd/keys.test.ts`
+
+Expected: FAIL because `keys get/delete` still require explicit `id` and no interactive selection exists.
+
+**Step 4: Commit the failing tests**
+
+```bash
+git add package.json package-lock.json tests/cmd/keys.test.ts
+git commit -m "test: cover keys interactive selection"
+```
+
+### Task 2: Implement interactive selection helper and wire commands
+
+**Files:**
+- Create: `src/core/interactive/keys.ts`
+- Modify: `src/cmd/keys.ts`
+- Test: `tests/cmd/keys.test.ts`
+
+**Step 1: Create interactive helper**
+
+```ts
+import prompts from "prompts";
+
+type Consumer = {
+  id?: string;
+  name?: string;
+  enabled?: boolean;
+  createdAt?: string;
+};
+
+type ConsumerService = {
+  ListConsumers: (args: { pageSize?: number; pageToken?: string }) => Promise<{ consumers?: Consumer[] }>;
+};
+
+const sortByCreatedAtDesc = (consumers: Consumer[]) =>
+  consumers
+    .slice()
+    .sort((a, b) => {
+      const aTime = Date.parse(a.createdAt ?? "") || 0;
+      const bTime = Date.parse(b.createdAt ?? "") || 0;
+      return bTime - aTime;
+    });
+
+const formatChoice = (consumer: Consumer) => {
+  const name = consumer.name ?? "-";
+  const id = consumer.id ?? "-";
+  const enabled = consumer.enabled == null ? "-" : consumer.enabled ? "ENABLED" : "DISABLED";
+  const createdAt = consumer.createdAt ?? "-";
+  return `${name} (${id}) | ${enabled} | ${createdAt}`;
+};
+
+export const selectConsumer = async (consumerService: ConsumerService) => {
+  const res = await consumerService.ListConsumers({ pageSize: undefined, pageToken: undefined });
+  const consumers = res?.consumers ?? [];
+  if (consumers.length === 0) {
+    throw new Error("没有可用的 API key");
+  }
+  const sorted = sortByCreatedAtDesc(consumers);
+  const response = await prompts({
+    type: "select",
+    name: "id",
+    message: "选择 API key",
+    choices: sorted.map((consumer) => ({
+      title: formatChoice(consumer),
+      value: consumer.id,
+    })),
+  });
+  if (!response.id) return null;
+  return sorted.find((consumer) => consumer.id === response.id) ?? { id: response.id };
+};
+
+export const confirmDelete = async (consumer: Consumer) => {
+  const name = consumer.name ?? "-";
+  const id = consumer.id ?? "-";
+  const response = await prompts({
+    type: "confirm",
+    name: "confirm",
+    message: `确认删除 ${name} (${id})?`,
+    initial: false,
+  });
+  return Boolean(response.confirm);
+};
+```
+
+**Step 2: Wire interactive selection into commands**
+
+```ts
+// imports
+import { selectConsumer, confirmDelete } from "../core/interactive/keys";
+
+// make args optional
+.argument("[id]")
+
+// in get/update/delete
+if (!id) {
+  if (!process.stdin.isTTY) {
+    throw new Error("缺少 id");
+  }
+  const selected = await selectConsumer(consumerService);
+  if (!selected?.id) return;
+  id = selected.id;
+}
+```
+
+For delete confirmation:
+
+```ts
+let selected: any = null;
+if (!id) {
+  if (!process.stdin.isTTY) {
+    throw new Error("缺少 id");
+  }
+  selected = await selectConsumer(consumerService);
+  if (!selected?.id) return;
+  id = selected.id;
+  const confirmed = await confirmDelete(selected);
+  if (!confirmed) return;
+}
+```
+
+**Step 3: Run tests to verify pass**
+
+Run: `npm test -- tests/cmd/keys.test.ts`
+
+Expected: PASS
+
+**Step 4: Commit**
+
+```bash
+git add src/cmd/keys.ts src/core/interactive/keys.ts tests/cmd/keys.test.ts
+git commit -m "feat: add interactive selection for keys"
+```
+
+### Task 3: Full test run
+
+**Files:**
+- None
+
+**Step 1: Run full test suite**
+
+Run: `npm test`
+
+Expected: PASS
+
+**Step 2: Commit (if needed)**
+
+```bash
+git status -sb
+```
+
+If clean, no commit needed.

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

@@ -0,0 +1,31 @@
+# getrouter CLI Keys 列表输出设计（表格）
+
+日期：2026-01-02  
+状态：已确认
+
+## 目标
+- `keys list` 默认输出改为表格，提升可读性。
+- 保留 `--json` 作为脚本接口；`apiKey` 默认脱敏。
+
+## 表格列与顺序
+- 列顺序固定：`ID | NAME | ENABLED | LAST_ACCESS | CREATED_AT | API_KEY`
+- 空值显示 `-`，避免列塌陷。
+- `apiKey` 默认脱敏（前 4 后 4），`--show-secret` 明文。
+
+## 表格渲染组件
+新增轻量表格工具（建议 `src/core/output/table.ts`）：
+- 输入：`headers: string[]`、`rows: Array<Array<string>>`
+- 列宽 = `max(表头宽度, 各行最大宽度)`，再受 `MAX_COL_WIDTH` 约束（如 32）。
+- 超宽截断：保留前 `MAX-3` 字符并追加 `...`。
+- 左对齐，列间空两格。
+- 不做脱敏，仅渲染字符串。
+
+## 命令层行为
+- `keys list` 在非 `--json` 情况使用表格输出。
+- `--json` 输出完整结构（已脱敏）。
+- 其他 keys 子命令暂保持 key=value 输出（可后续统一为表格）。
+
+## 测试策略
+- 表格渲染单测：宽度计算、截断、空值、对齐。
+- `keys list` 输出单测：确保表头与列顺序；校验脱敏结果。
+

package/docs/plans/2026-01-02-getrouter-cli-keys-output-plan.md

@@ -0,0 +1,187 @@
+# Keys List Table Output Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Implement a reusable table renderer and switch `keys list` default output to a readable table format with truncation and redaction.
+
+**Architecture:** Add `core/output/table` for width calculation + truncation, then update `cmd/keys` to render list rows via table when not `--json`.
+
+**Tech Stack:** TypeScript, Node.js, vitest.
+
+### Task 1: Add table renderer utility
+
+**Files:**
+- Create: `src/core/output/table.ts`
+- Create: `tests/output/table.test.ts`
+
+**Step 1: Write the failing test**
+
+Create `tests/output/table.test.ts`:
+
+```ts
+import { describe, it, expect } from "vitest";
+import { renderTable } from "../../src/core/output/table";
+
+describe("table renderer", () => {
+  it("renders headers and rows with alignment", () => {
+    const out = renderTable(
+      ["ID", "NAME"],
+      [
+        ["1", "alpha"],
+        ["2", "beta"],
+      ]
+    );
+    expect(out).toContain("ID");
+    expect(out).toContain("NAME");
+    expect(out).toContain("alpha");
+  });
+
+  it("truncates long cells", () => {
+    const out = renderTable(["ID"], [["0123456789ABCDEFGHIJ"]], {
+      maxColWidth: 8,
+    });
+    expect(out).toContain("0123...");
+  });
+
+  it("fills empty with dash", () => {
+    const out = renderTable(["ID"], [[""]]);
+    expect(out).toContain("-");
+  });
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `npm test -- tests/output/table.test.ts`  
+Expected: FAIL (module missing)
+
+**Step 3: Write minimal implementation**
+
+Create `src/core/output/table.ts`:
+
+```ts
+type TableOptions = { maxColWidth?: number };
+
+const truncate = (value: string, max: number) => {
+  if (value.length <= max) return value;
+  if (max <= 3) return value.slice(0, max);
+  return `${value.slice(0, max - 3)}...`;
+};
+
+export const renderTable = (
+  headers: string[],
+  rows: string[][],
+  options: TableOptions = {}
+) => {
+  const maxColWidth = options.maxColWidth ?? 32;
+  const normalized = rows.map((row) =>
+    row.map((cell) => (cell && cell.length > 0 ? cell : "-"))
+  );
+  const widths = headers.map((h, i) => {
+    const colValues = normalized.map((row) => row[i] ?? "-");
+    const maxLen = Math.max(h.length, ...colValues.map((v) => v.length));
+    return Math.min(maxLen, maxColWidth);
+  });
+  const renderRow = (cells: string[]) =>
+    cells
+      .map((cell, i) => {
+        const raw = cell ?? "-";
+        const clipped = truncate(raw, widths[i]);
+        return clipped.padEnd(widths[i], " ");
+      })
+      .join("  ");
+  const headerRow = renderRow(headers);
+  const body = normalized.map((row) => renderRow(row)).join("\n");
+  return `${headerRow}\n${body}`;
+};
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `npm test -- tests/output/table.test.ts`  
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/core/output/table.ts tests/output/table.test.ts
+git commit -m "feat: add table renderer"
+```
+
+### Task 2: Switch keys list to table output
+
+**Files:**
+- Modify: `src/cmd/keys.ts`
+- Modify: `tests/cmd/keys.test.ts`
+
+**Step 1: Write the failing test**
+
+Update `tests/cmd/keys.test.ts` with a human-readable output assertion:
+
+```ts
+it("list prints table header in default mode", async () => {
+  (createApiClients as unknown as ReturnType<typeof vi.fn>).mockReturnValue({
+    consumerService: {
+      ListConsumers: vi.fn().mockResolvedValue({ consumers: [mockConsumer] }),
+    },
+    subscriptionService: {} as any,
+  });
+  const log = vi.spyOn(console, "log").mockImplementation(() => {});
+  const program = createProgram();
+  await program.parseAsync(["node", "getrouter", "keys", "list"]);
+  const output = log.mock.calls.map((c) => c[0]).join("\n");
+  expect(output).toContain("ID");
+  expect(output).toContain("NAME");
+  expect(output).toContain("API_KEY");
+  log.mockRestore();
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `npm test -- tests/cmd/keys.test.ts`  
+Expected: FAIL (still key=value)
+
+**Step 3: Write minimal implementation**
+
+Update `src/cmd/keys.ts`:
+- import `renderTable`
+- in `keys list`, when not `--json`, build headers/rows and `console.log(renderTable(...))`
+- map row cells to strings, use `-` for empty
+
+Example mapping:
+```ts
+const headers = ["ID", "NAME", "ENABLED", "LAST_ACCESS", "CREATED_AT", "API_KEY"];
+const rows = consumers.map((c) => [
+  String(c.id ?? ""),
+  String(c.name ?? ""),
+  String(c.enabled ?? ""),
+  String(c.lastAccess ?? ""),
+  String(c.createdAt ?? ""),
+  String(c.apiKey ?? ""),
+]);
+console.log(renderTable(headers, rows));
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `npm test -- tests/cmd/keys.test.ts`  
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/cmd/keys.ts tests/cmd/keys.test.ts
+git commit -m "feat: use table output for keys list"
+```
+
+---
+
+Plan complete and saved to `docs/plans/2026-01-02-getrouter-cli-keys-output-plan.md`.
+
+Two execution options:
+
+1. Subagent-Driven (this session) — use superpowers:subagent-driven-development
+2. Parallel Session (separate) — open a new session with executing-plans in this worktree
+
+Which approach?

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

@@ -0,0 +1,52 @@
+# getrouter CLI Keys & Subscription 设计（v1）
+
+日期：2026-01-02  
+状态：已确认
+
+## 背景
+- `keys` 命令映射 dashboard `consumer` 资源，用于管理 API key。
+- `subscription show` 用于展示当前订阅信息。
+- 复用 dashboard 生成的 TypeScript client，避免路径与类型漂移。
+
+## 方案选型
+**采用**：复用 dashboard 生成的 TS client（ConsumerService/SubscriptionService），CLI 仅做参数解析与输出层。
+
+## 命令设计
+### Keys（consumer）
+- `getrouter keys list`
+- `getrouter keys get <id>`
+- `getrouter keys create --name <name> [--enabled <true|false>]`
+- `getrouter keys update <id> --name <name> --enabled <true|false>`
+- `getrouter keys delete <id>`
+
+约定：
+- `list` 暂不支持分页参数（使用服务端默认）。
+- `update` 仅允许更新 `name` 与 `enabled`。未提供任何可更新字段时报错。
+- `apiKey` 默认脱敏展示，仅在 `--show-secret` 下明文。
+- `create` 成功后默认脱敏展示 `apiKey`，并提示“请妥善保存 API Key”。
+
+### Subscription
+- `getrouter subscription show`
+
+默认输出字段：
+- `plan.name`, `status`, `startAt`, `endAt`, `plan.requestPerMinute`, `plan.tokenPerMinute`
+- `--json` 输出原始结构
+
+## 组件与数据流
+- `core/api`：包装生成 client（ConsumerService/SubscriptionService）。
+- `core/http`：统一鉴权与错误封装（Authorization: Bearer）。
+- `cmd/keys`/`cmd/subscription`：参数解析、调用 `core/api`。
+- 输出层：默认人类可读，`--json` 输出结构化 JSON。
+
+## 错误处理
+- 401/403：提示 `getrouter auth login`。
+- `subscription show` 若 404/空响应，提示“未订阅”。
+- 其他错误：默认输出 message；JSON 模式输出 `{code,message,details,status}`。
+
+## 测试策略
+- `core/api`/adapter：验证路径、方法、请求体与 `updateMask` 生成。
+- `cmd/keys`：list/create/update/delete/get 输出与脱敏/`--show-secret` 行为。
+- `cmd/subscription`：正常与 404 场景，JSON 与默认输出。
+
+## 备注
+- `apiBase` 默认 `https://getrouter.dev`，生成 client path 已含 `v1/...`。