@springbrand/cli 0.1.4 → 0.1.5-alpha.1

package/README.md

@@ -15,35 +15,26 @@ npm run build
 npm link
 ```
 
-## 推荐安装流程：API key 优先
+## 推荐安装流程：OAuth-first
 
-安装提示词应先引导用户使用 API key。OAuth 仍然支持，但作为 API key 不可用或用户明确选择 OAuth 时的备用路径；不要把 OAuth 作为默认安装方式。
+`sp connect <client>` 是默认入口。没有显式 API key 时，CLI 写入 Host 的原生 MCP 配置并交给该 Host 完成 OAuth；新用户可以在浏览器注册并授权，已有 SpringBrand 会话会直接复用。CLI 不会把 keyless 安装自动转成 `sp auth login`。
 
-先检查当前是否已有可用的 key：
+安装提示词应只执行一次 connect，然后读取机器结果中的 `next_action`（或 `nextAction`）。Host 需要浏览器授权或重载时，结果会给出该 Host 的精确动作；Agent 不得猜测登录命令、切换 Host 或切换认证方式。授权或重载后只运行一次继续命令：
 
 ```bash
-sp auth status --verify
+sp connect codex --json
+sp doctor --harness codex --json
 ```
 
-如果没有 key，或者检查结果显示 key 已被拒绝，运行：
+只有 `connect` 返回 `outcome: "verified"`，或继续执行后的 doctor 结果 `ready: true`，才能报告安装完成。`auth_pending`、`needs_reload`、`failed` 和 `unsupported` 都是非成功状态。
 
-```bash
-sp auth login
-```
-
-CLI 会打开 SpringBrand 的 API key 页面。未注册用户先注册并登录，已有账号的用户直接在页面中创建或复制 API key，然后把 key 粘贴回 CLI。开发环境要根据安装端点打开对应的页面：
-
-```bash
-sp auth login --url https://devconnector.springbrand.ai/mcp
-```
-
-保存 key 后再连接客户端：
+如果用户明确提供 API key，它优先于保存的凭据并走独立的 key 路径：
 
 ```bash
-sp connect codex
+SPRINGBRAND_API_KEY='…' sp connect codex --json
 ```
 
-如果 API key 无法使用，或者用户明确选择 OAuth，则跳过 `sp auth login`，直接运行 `sp connect codex`，由 Codex 完成 OAuth 登录。这个路径仍然需要用户先注册或登录 SpringBrand。
+key 无效、撤销、跨环境或暂时不可验证时，CLI 保留在 key 路径并返回安全的恢复动作；不会打开 OAuth，也不会覆盖原先可用的保存 key。`sp auth login` 仍是用户主动管理 API key 的命令，不是 connect 的自动 fallback。
 
 ## 发布 alpha
 
@@ -130,10 +121,10 @@ sp connect cursor --url http://127.0.0.1:8789/mcp   # 覆盖端点（本地开
 
 `hermes` 仍被插件仓库阻塞，见 TODO。
 
-两种认证形态由客户端能力决定。安装提示词应优先准备 API key：
+两种认证形态由客户端能力决定：
 
-- **API key（推荐）**：先通过 `sp auth login` 打开 API key 页面，保存或复制 key，再执行 `sp connect <client>`。CLI 把 key 写进 `Authorization: Bearer`，客户端不再需要再次浏览器登录；也可以用 `--api-key` 或 `SPRINGBRAND_API_KEY` 直接提供。
-- **OAuth（备用）**：不提供 key 时，写入的条目只有 URL，由客户端自己走 OAuth 授权。它适用于 API key 检查失败或用户明确选择 OAuth 的情况。
+- **OAuth（默认）**：不提供 key 时，写入的条目只有 URL，由客户端自己的 MCP OAuth 完成注册、登录和授权。
+- **API key（显式）**：只有本次命令的 `--api-key` 或 `SPRINGBRAND_API_KEY` 会选择 key 路径；CLI 不会从保存的 key 配置自动改变 keyless landing flow。选中 key 后，CLI 把它写进 `Authorization: Bearer`（或 Host 的等价安全引用），并禁止 OAuth fallback。
 
 **`Authorization: Bearer` 是 Gateway 唯一读取 key 的位置**（`src/auth/mcp-api-key.ts` 的 `classifyMcpAuthorization`），key 写进别的请求头等于没带凭据，客户端会被推回 OAuth。Codex 与 Grok 例外地传环境变量名而非 key 本身：前者用 `--bearer-token-env-var`，后者在加载时展开 `${SPRINGBRAND_API_KEY}`，两者都由客户端自己拼成 Bearer，key 因此不进 argv 与配置文件。
 
@@ -151,7 +142,7 @@ key 形态是 `sbk_v1_<dev|production>_<id>_<secret>`，环境段决定它能用
 sp doctor --json
 ```
 
-该模式输出单个版本化 JSON 文档，顶层包含 `schema_version`、`verdict`、`checks`、`hosts` 和 `repairs`。`hosts` 中每个客户端都固定包含 `detected`、`mcp_configured`、`auth`、`skills`、`tools`、`restart_required` 和 `failed_phase`；阶段状态只能是 `pass`、`warn`、`fail`、`skip` 或 `unknown`。`failed_phase` 按固定的检测、配置、认证、Skill、工具、重启顺序指出第一个失败阶段，未失败时为 `null`。破坏性读取变化会提升 `schema_version`；新增可选字段保持向前兼容。
+该模式输出单个版本化 JSON 文档，顶层包含 `schema_version`、`verdict`、`ready`、`checks`、`hosts` 和 `repairs`。`ready: true` 才表示选定 Host 的 MCP 身份、认证、健康检查和加载状态都已通过。`hosts` 中每个客户端都固定包含 `detected`、`mcp_configured`、`auth`、`skills`、`tools`、`restart_required` 和 `failed_phase`；阶段状态只能是 `pass`、`warn`、`fail`、`skip` 或 `unknown`。`failed_phase` 按固定的检测、配置、认证、Skill、工具、重启顺序指出第一个失败阶段，未失败时为 `null`。破坏性读取变化会提升 `schema_version`；新增可选字段保持向前兼容。
 
 `--json` 与 `--pretty` 不能同时使用，也不能重复指定；这类输入错误退出码为 `3`。正常诊断仍使用既有退出码：`0` 表示没有 Harness 失败，`1` 表示至少一个 Harness 失败，`2` 表示 doctor 自身无法完成。机器模式的 JSON verdict 用于定位问题，退出码仍是自动化的首要信号。
 

package/dist/commands/connect.d.ts

@@ -3,7 +3,7 @@ import type { Command } from 'commander';
 import type { TakeHoistedCliInstall } from '../lib/cli-install.js';
 import type { AgentClient, ConnectAuthMode } from '../lib/connect-runtime.js';
 /** Skill install only: no key handoff or post-install callback to honour. */
-export declare function connectOpenClaw(options: Omit<NativeConnectOptions, 'keyAuthOnly' | 'onPostInstallFailed'>): Promise<void>;
+export declare function connectOpenClaw(options: Omit<NativeConnectOptions, 'keyAuthOnly' | 'onPostInstallFailed'>): Promise<ConnectAuthMode | undefined>;
 /** Writes mcp.json directly — no `cursor mcp add` exists. */
 export declare function connectCursor(options: {
     apiKey?: string;
@@ -12,7 +12,7 @@ export declare function connectCursor(options: {
     verbose?: boolean;
     authTimeoutMs?: number;
     onPostInstallFailed?: () => void;
-}): Promise<void>;
+}): Promise<ConnectAuthMode | undefined>;
 export declare function launchAgent(client: AgentClient): Promise<void>;
 export declare function connectHarness(harness: AgentClient, options: NativeConnectOptions): Promise<ConnectAuthMode | undefined>;
 export declare function registerConnect(program: Command): void;
@@ -25,6 +25,8 @@ export interface NativeConnectOptions {
     keyAuthOnly?: boolean;
     /** Headless --all: bounds sign-in spawns and bars interactive CLI login. */
     authTimeoutMs?: number;
+    /** Single-host machine mode: write the registration and return the native OAuth action. */
+    deferOAuth?: boolean;
     /** Internal only: false leaves the global npm tree untouched. */
     cliInstall?: boolean;
     /** Set by `--all`: the CLI install already ran once, upfront. */

package/dist/commands/connect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../src/commands/connect.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAE5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAyE,MAAM,2BAA2B,CAAC;AAwhBrJ,6EAA6E;AAC7E,wBAAsB,eAAe,CAAC,OAAO,EAAE,IAAI,CAAC,oBAAoB,EAAE,aAAa,GAAG,qBAAqB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CA6D/H;AAiPD,6DAA6D;AAC7D,wBAAsB,aAAa,CAAC,OAAO,EAAE;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,IAAI,CAAC;CACpC,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhB;AAqBD,wBAAsB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpE;AAwDD,wBAAsB,cAAc,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAI9H;AA4ED,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoCtD;AAcD,MAAM,WAAW,oBAAoB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,iEAAiE;IACjE,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;IAC1C,6DAA6D;IAC7D,mBAAmB,CAAC,EAAE,MAAM,IAAI,CAAC;IACjC,wEAAwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,sEAAsE;IACtE,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACjC"}
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../src/commands/connect.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAE5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAyE,MAAM,2BAA2B,CAAC;AAsiBrJ,6EAA6E;AAC7E,wBAAsB,eAAe,CAAC,OAAO,EAAE,IAAI,CAAC,oBAAoB,EAAE,aAAa,GAAG,qBAAqB,CAAC,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAmEtJ;AAsPD,6DAA6D;AAC7D,wBAAsB,aAAa,CAAC,OAAO,EAAE;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,IAAI,CAAC;CACpC,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAEvC;AAqBD,wBAAsB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpE;AAuDD,wBAAsB,cAAc,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAI9H;AA+JD,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAiDtD;AAeD,MAAM,WAAW,oBAAoB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2FAA2F;IAC3F,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,iEAAiE;IACjE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,iEAAiE;IACjE,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;IAC1C,6DAA6D;IAC7D,mBAAmB,CAAC,EAAE,MAAM,IAAI,CAAC;IACjC,wEAAwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,sEAAsE;IACtE,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACjC"}