@metagptx/deepflow-cli 0.1.0

package/README.md

@@ -0,0 +1,109 @@
+# DeepFlow CLI
+
+Zero-dependency CLI wrapper for DeepFlow Web methods.
+
+## Install
+
+```bash
+npm install -g @metagptx/deepflow-cli
+deepflow --help
+deepflow -l -t <dfpat_token> --base-url https://deepflow.example.com
+```
+
+`npx` is still useful for one-off execution, but it does not install
+`deepflow` into your PATH for later shell sessions:
+
+```bash
+npx @metagptx/deepflow-cli --help
+npx --package @metagptx/deepflow-cli deepflow --help
+```
+
+For local development from this repository:
+
+```bash
+npm link
+deepflow --help
+node bin/deepflow.js --help
+```
+
+## Authenticate
+
+```bash
+deepflow -l -t <dfpat_token>
+```
+
+Equivalent forms:
+
+```bash
+deepflow -login -t <dfpat_token>
+deepflow --login -t <dfpat_token>
+deepflow auth login -t <dfpat_token>
+```
+
+Config is stored at:
+
+```text
+~/.deepflow/config.json
+```
+
+## Run Plan
+
+```bash
+deepflow plan run \
+  --repo <repo_id_or_app_code> \
+  --name "Demo Iteration" \
+  --context "Plan this change" \
+  --prompt "Create an implementation plan only." \
+  --json
+```
+
+`plan run --json` returns `statusUrl`, `messagesUrl`, and `stopUrl` so
+external callers can poll or stop the created session without knowing
+DeepFlow Web route details.
+
+## Checks
+
+```bash
+npm run check
+npm test
+npm run smoke
+npm run pack:dry-run
+```
+
+Run the full Web/Core-backed smoke when a token and app are available:
+
+```bash
+DEEPFLOW_CLI_E2E_TOKEN=<dfpat_token> \
+DEEPFLOW_CLI_E2E_BASE_URL=http://localhost:3100 \
+npm run smoke:e2e
+```
+
+Useful environment variables:
+
+```bash
+export DEEPFLOW_BASE_URL=http://localhost:3100
+export DEEPFLOW_TOKEN=dfpat_xxx
+```
+
+## Publish
+
+Validate the package contents before publishing:
+
+```bash
+npm run check
+npm test
+npm run smoke
+npm run pack:dry-run
+```
+
+Publish to the configured npm registry:
+
+```bash
+npm publish --access public
+```
+
+For a private company registry, pass the registry explicitly:
+
+```bash
+npm publish --registry <registry-url>
+```

package/bin/deepflow.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+import { main } from "../src/cli.js";
+
+const exitCode = await main(process.argv.slice(2));
+
+process.exitCode = exitCode;

package/docs/cli-design.md

@@ -0,0 +1,365 @@
+# DeepFlow CLI 设计文档
+
+## 背景
+
+DeepFlow 需要提供一种面向外部系统的调用方式，但外部调用方不应直接耦合 Web/Core 的 HTTP API 细节。CLI 作为稳定入口，对外暴露“方法”语义：调用方执行 `deepflow <method>`，CLI 负责读取配置、鉴权、请求 DeepFlow Web API、处理响应和输出结构化结果。
+
+首版目标是支持外部创建一个迭代并启动 Plan，后续再逐步扩展查询、停止、继续执行、获取结果等能力。
+
+## 目标
+
+1. 提供 `deepflow` 命令行入口，供外部脚本、CI、平台服务调用。
+2. 支持全局配置文件读取 token 和服务地址。
+3. 支持通过 `deepflow -l/-login -t <token>` 完成 token 认证写入。
+4. 对外暴露稳定方法，不暴露底层 API 路径和请求体。
+5. 支持机器可读输出，便于外部系统解析执行结果。
+6. 所有调用默认携带 token，走 `Authorization: Bearer <token>`。
+
+## 非目标
+
+1. 首版不实现交互式登录 OAuth/OIDC。
+2. 首版不直接调用 DeepFlowCore 外部 API，统一走 DeepFlowWeb，复用用户级 token、权限和本地迭代能力。
+3. 首版不提供完整前端功能镜像，只封装外部自动化需要的核心方法。
+4. 首版不在 CLI 内保存 token 明文之外的服务端状态，token 生命周期仍由 Web token 管理页负责。
+
+## 命令入口
+
+命令名：
+
+```bash
+deepflow
+```
+
+发布包名：
+
+```text
+@metagptx/deepflow-cli
+```
+
+推荐外部调用方先全局安装，然后直接使用固定的 `deepflow` 命令：
+
+```bash
+npm install -g @metagptx/deepflow-cli
+deepflow --help
+deepflow plan run --repo <repo_id_or_app_code> --json
+```
+
+`npx` 只适合临时执行，不会把 `deepflow` 持久安装到 PATH。需要临时执行时可以使用：
+
+```bash
+npx @metagptx/deepflow-cli --help
+npx --package @metagptx/deepflow-cli deepflow --help
+```
+
+认证快捷入口：
+
+```bash
+deepflow -l -t <token>
+deepflow -login -t <token>
+deepflow --login -t <token>
+```
+
+说明：
+
+- `-l` 是短选项。
+- `--login` 是标准长选项。
+- `-login` 兼容用户明确提出的写法，内部等价于 `--login`。
+- `-t, --token <token>` 指定 token。
+
+推荐也支持子命令形式，便于长期维护：
+
+```bash
+deepflow auth login -t <token>
+deepflow auth logout
+deepflow auth status
+```
+
+## 全局配置
+
+配置文件路径：
+
+```text
+~/.deepflow/config.json
+```
+
+权限建议：
+
+```text
+0600
+```
+
+配置结构：
+
+```json
+{
+  "baseUrl": "http://localhost:3100",
+  "token": "dfpat_xxx",
+  "profile": "default",
+  "profiles": {
+    "default": {
+      "baseUrl": "http://localhost:3100",
+      "token": "dfpat_xxx"
+    }
+  }
+}
+```
+
+首版可以只实现 `baseUrl` 和 `token`，同时预留 `profiles`，避免后续多环境改配置结构。
+
+配置读取优先级：
+
+1. 命令行参数，例如 `--token`、`--base-url`。
+2. 环境变量：
+   - `DEEPFLOW_TOKEN`
+   - `DEEPFLOW_BASE_URL`
+3. 全局配置 `~/.deepflow/config.json` 当前 profile。
+4. 默认值：
+   - `baseUrl = http://localhost:3100`
+
+## Token 认证设计
+
+### 登录写入
+
+```bash
+deepflow -l -t dfpat_xxx
+```
+
+执行逻辑：
+
+1. 校验 token 格式，必须以 `dfpat_` 开头。
+2. 使用 token 调用 Web 的轻量校验接口：`GET /api/auth/token/verify`。
+3. 校验通过后写入 `~/.deepflow/config.json`。
+4. 设置配置文件权限为 `0600`。
+5. 输出当前认证状态。
+
+输出示例：
+
+```json
+{
+  "ok": true,
+  "baseUrl": "http://localhost:3100",
+  "authenticated": true
+}
+```
+
+### 登出
+
+```bash
+deepflow auth logout
+```
+
+只删除本地 token，不删除服务端 token。服务端 token 删除仍通过 Web 设置页完成。
+
+### 状态检查
+
+```bash
+deepflow auth status
+```
+
+输出：
+
+```json
+{
+  "authenticated": true,
+  "baseUrl": "http://localhost:3100",
+  "tokenPrefix": "dfpat_OQ"
+}
+```
+
+## 方法设计
+
+CLI 对外提供方法式命令。每个方法负责把业务参数转换为 Web API 调用，并输出统一结构。
+
+### 创建迭代并运行 Plan
+
+命令：
+
+```bash
+deepflow plan run --repo <repo_id_or_app_code> --name "Demo Iteration" --context "..." 
+```
+
+可选参数：
+
+```bash
+--base-branch <branch>
+--target-branch <branch>
+--runtime <claude|codex>
+--prompt <text>
+--prompt-file <path>
+--json
+```
+
+执行链路：
+
+1. 读取 token 和 baseUrl。
+2. 创建本地迭代：`POST /api/local/iterations`。
+3. 创建 Plan session：`POST /api/local/sessions`。
+4. 发送 Plan prompt：`POST /api/local/sessions/{session_id}/messages`。
+5. 输出迭代、session、run 和 UI URL。
+
+输出示例：
+
+```json
+{
+  "ok": true,
+  "method": "plan.run",
+  "iterationId": "local-iteration-id",
+  "backendIterationId": "backend-iteration-id",
+  "planSessionId": "session-id",
+  "runId": "run-id",
+  "uiUrl": "http://localhost:3100/iterations/backend-iteration-id/plan?sessionId=session-id",
+  "statusUrl": "http://localhost:3100/api/local/sessions/session-id?iterationId=local-iteration-id",
+  "messagesUrl": "http://localhost:3100/api/sessions/session-id/messages?iteration_id=backend-iteration-id",
+  "stopUrl": "http://localhost:3100/api/sessions/session-id/stop?iteration_id=backend-iteration-id"
+}
+```
+
+### 查询 Plan 状态
+
+命令：
+
+```bash
+deepflow plan status --iteration <iteration_id> --session <session_id>
+```
+
+用于外部系统轮询结果。
+
+### 获取消息/结果
+
+命令：
+
+```bash
+deepflow session messages --iteration <iteration_id> --session <session_id>
+```
+
+用于拉取会话消息，后续可以增加 `--latest`、`--format markdown`。
+
+### 停止运行
+
+命令：
+
+```bash
+deepflow session stop --iteration <iteration_id> --session <session_id>
+```
+
+用于外部系统主动中断 plan 或 execute。
+
+## 统一输出与退出码
+
+默认输出人类可读文本，带 `--json` 时输出 JSON。外部系统建议总是加 `--json`。
+
+退出码：
+
+| 退出码 | 含义 |
+| --- | --- |
+| 0 | 成功 |
+| 1 | 通用失败 |
+| 2 | 参数错误 |
+| 3 | 未认证或 token 无效 |
+| 4 | 权限不足 |
+| 5 | DeepFlow Web 不可达 |
+| 6 | DeepFlow Core 透传失败 |
+
+错误输出示例：
+
+```json
+{
+  "ok": false,
+  "errorCode": "unauthorized",
+  "message": "Authentication is required.",
+  "status": 401
+}
+```
+
+## 安全设计
+
+1. Token 只写入用户级配置文件，不写入项目目录。
+2. 配置文件创建后强制 `0600`。
+3. 日志和错误信息不打印完整 token，只打印 token prefix。
+4. 命令行参数中的 token 会进入 shell history，文档中建议优先使用环境变量或 stdin 方式。
+5. 后续可支持：
+   - `deepflow auth login --token-stdin`
+   - macOS Keychain / Linux Secret Service / Windows Credential Manager。
+
+## 与 Web Token 权限的关系
+
+CLI 使用 Web 个人 API Token。首版需要以下权限范围：
+
+| CLI 方法 | 需要 scope |
+| --- | --- |
+| `auth status` | `deepflow:read` 或 `web:*` |
+| `plan run` | `deepflow:read` + `deepflow:invoke` 或 `web:*` |
+| `plan status` | `deepflow:read` 或 `web:*` |
+| `session messages` | `deepflow:read` 或 `web:*` |
+| `session stop` | `deepflow:invoke` 或 `web:*` |
+
+## 推荐技术方案
+
+DeepFlowCli 作为独立仓库/包，建议使用 Node.js + TypeScript：
+
+- 与 DeepFlowWeb 技术栈一致，方便复用类型和请求工具。
+- 可通过 npm/pnpm 发布或本地 link。
+- Node 18+ 原生 `fetch` 足够完成 HTTP 调用。
+
+候选依赖：
+
+- `commander`：命令解析。
+- `zod`：配置和响应校验。
+- `conf` 或自定义轻量 config store：全局配置管理。
+- `vitest`：单元测试。
+- `tsx`：开发期运行 TypeScript。
+
+也可以先用纯 Node.js 实现 MVP，减少依赖；后续稳定后再切 TypeScript。
+
+## 项目结构建议
+
+```text
+DeepFlowCli/
+  package.json
+  tsconfig.json
+  src/
+    cli.ts
+    config.ts
+    auth.ts
+    client.ts
+    methods/
+      plan-run.ts
+      plan-status.ts
+      session-messages.ts
+      session-stop.ts
+    output.ts
+    errors.ts
+  tests/
+    config.test.ts
+    auth.test.ts
+    plan-run.test.ts
+  docs/
+    cli-design.md
+```
+
+## MVP 实现步骤
+
+1. 初始化 Node/TypeScript CLI 工程，生成 `deepflow` bin。
+2. 实现全局配置读写：
+   - `~/.deepflow/config.json`
+   - `baseUrl`
+   - `token`
+3. 实现登录入口：
+   - `deepflow -l -t <token>`
+   - `deepflow -login -t <token>`
+   - `deepflow --login -t <token>`
+   - `deepflow auth login -t <token>`
+4. 实现 Web API client：
+   - 自动注入 `Authorization: Bearer <token>`
+   - 统一 timeout
+   - 统一错误转换
+5. 实现 `deepflow plan run`，返回 `statusUrl` / `messagesUrl` / `stopUrl`。
+6. 增加 `--json` 输出和退出码。
+7. 补单元测试、本地 smoke 和可选 Web/Core e2e smoke。
+
+## 待确认问题
+
+1. CLI 默认 `baseUrl` 是否固定为 `http://localhost:3100`，还是从部署环境统一配置。
+2. `plan run` 是否必须传 `--repo`，还是允许默认选择第一个应用。
+3. 是否需要支持多 profile，例如 `deepflow --profile prod plan run ...`。
+4. 后续是否需要把 `GET /api/auth/token/verify` 暴露在 API 文档中。

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@metagptx/deepflow-cli",
+  "version": "0.1.0",
+  "description": "Command line interface for DeepFlow external automation.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "deepflow": "bin/deepflow.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "docs/cli-design.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "check": "node --check bin/deepflow.js && node --check src/*.js",
+    "pack:dry-run": "npm pack --dry-run",
+    "smoke": "node scripts/smoke.mjs",
+    "smoke:e2e": "node scripts/e2e-smoke.mjs",
+    "test": "node --test"
+  }
+}

package/src/args.js

@@ -0,0 +1,198 @@
+import { CliError } from "./errors.js";
+
+const VALUE_FLAGS = new Set([
+  "base-url",
+  "baseUrl",
+  "base-branch",
+  "backend-iteration",
+  "context",
+  "context-file",
+  "fast-timeout",
+  "iteration",
+  "iteration-type",
+  "local-iteration",
+  "name",
+  "profile",
+  "prompt",
+  "prompt-file",
+  "repo",
+  "runtime",
+  "session",
+  "target-branch",
+  "timeout",
+  "token",
+]);
+
+const BOOLEAN_FLAGS = new Set([
+  "force-new",
+  "help",
+  "json",
+  "login",
+  "token-stdin",
+  "version",
+]);
+
+const SHORT_FLAGS = new Map([
+  ["-h", "help"],
+  ["-j", "json"],
+  ["-l", "login"],
+  ["-t", "token"],
+]);
+
+const LONG_ALIASES = new Map([
+  ["-login", "login"],
+  ["--login", "login"],
+  ["--base-url", "base-url"],
+  ["--baseUrl", "baseUrl"],
+  ["--base-branch", "base-branch"],
+  ["--backend-iteration", "backend-iteration"],
+  ["--context", "context"],
+  ["--context-file", "context-file"],
+  ["--fast-timeout", "fast-timeout"],
+  ["--force-new", "force-new"],
+  ["--help", "help"],
+  ["--iteration", "iteration"],
+  ["--iteration-type", "iteration-type"],
+  ["--json", "json"],
+  ["--local-iteration", "local-iteration"],
+  ["--name", "name"],
+  ["--profile", "profile"],
+  ["--prompt", "prompt"],
+  ["--prompt-file", "prompt-file"],
+  ["--repo", "repo"],
+  ["--runtime", "runtime"],
+  ["--session", "session"],
+  ["--target-branch", "target-branch"],
+  ["--timeout", "timeout"],
+  ["--token", "token"],
+  ["--token-stdin", "token-stdin"],
+  ["--version", "version"],
+]);
+
+function toCamelCase(name) {
+  return name.replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+}
+
+function setFlag(flags, rawName, value) {
+  flags[toCamelCase(rawName)] = value;
+}
+
+function resolveFlagName(arg) {
+  if (SHORT_FLAGS.has(arg)) {
+    return SHORT_FLAGS.get(arg);
+  }
+
+  if (LONG_ALIASES.has(arg)) {
+    return LONG_ALIASES.get(arg);
+  }
+
+  return null;
+}
+
+function parseLongAssignment(arg) {
+  const index = arg.indexOf("=");
+
+  if (index === -1) {
+    return null;
+  }
+
+  const namePart = arg.slice(0, index);
+  const value = arg.slice(index + 1);
+  const name = resolveFlagName(namePart);
+
+  if (!name) {
+    return null;
+  }
+
+  return { name, value };
+}
+
+export function parseArgs(argv) {
+  const flags = {};
+  const positionals = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "--") {
+      positionals.push(...argv.slice(index + 1));
+      break;
+    }
+
+    if (arg.startsWith("--no-")) {
+      const name = arg.slice("--no-".length);
+
+      if (!BOOLEAN_FLAGS.has(name)) {
+        throw new CliError(`Unknown option: ${arg}`, {
+          code: "bad_option",
+          exitCode: 2,
+        });
+      }
+
+      setFlag(flags, name, false);
+      continue;
+    }
+
+    const assignment = parseLongAssignment(arg);
+
+    if (assignment) {
+      if (!VALUE_FLAGS.has(assignment.name)) {
+        throw new CliError(`Option does not take a value: ${arg}`, {
+          code: "bad_option",
+          exitCode: 2,
+        });
+      }
+
+      setFlag(flags, assignment.name, assignment.value);
+      continue;
+    }
+
+    const name = resolveFlagName(arg);
+
+    if (name) {
+      if (VALUE_FLAGS.has(name)) {
+        const value = argv[index + 1];
+
+        if (!value || value.startsWith("-")) {
+          throw new CliError(`Missing value for ${arg}`, {
+            code: "missing_option_value",
+            exitCode: 2,
+          });
+        }
+
+        setFlag(flags, name, value);
+        index += 1;
+        continue;
+      }
+
+      if (!BOOLEAN_FLAGS.has(name)) {
+        throw new CliError(`Unknown option: ${arg}`, {
+          code: "bad_option",
+          exitCode: 2,
+        });
+      }
+
+      setFlag(flags, name, true);
+      continue;
+    }
+
+    if (arg.startsWith("-")) {
+      throw new CliError(`Unknown option: ${arg}`, {
+        code: "bad_option",
+        exitCode: 2,
+      });
+    }
+
+    positionals.push(arg);
+  }
+
+  return { flags, positionals };
+}
+
+export function commandFromParsedArgs(parsed) {
+  if (parsed.flags.login) {
+    return ["auth", "login"];
+  }
+
+  return parsed.positionals;
+}