gx-code-agent 0.0.0-stage → 0.1.1

package/src/application/initWorkflow.js

@@ -0,0 +1,563 @@
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+
+import { McpHttpClient } from "../adapters/platform/mcpClient.js";
+import { printPlan } from "../adapters/cli/output.js";
+import { ApprovalRequiredError, UsageError } from "./errors.js";
+import { InitTransaction, createBackupRoot, pruneBackups } from "../store/backupStore.js";
+import { readJson, readText, writeText } from "../store/localStore.js";
+
+const RULES_START = "<!-- GX-MCP-RULES:START -->";
+const RULES_END = "<!-- GX-MCP-RULES:END -->";
+const DEFAULT_TIMEOUT_MS = 180000;
+const STARTUP_TIMEOUT_MS = 15000;
+const CATALOG_TIMEOUT_MS = 30000;
+const STDIO_BIN = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../bin/gx-stdio-mcp.js");
+const GITIGNORE_LINES = ["backup/", "generated/", "*.local.json", "cline-mcp-settings.json"];
+
+/**
+ * 构造鉴权头。默认写环境变量引用，避免明文 Token 落盘。
+ *
+ * @param {string} client
+ * @param {string} tokenEnv
+ * @param {string | undefined} token
+ * @param {boolean} embedToken
+ * @returns {string}
+ */
+function authHeader(client, tokenEnv, token, embedToken) {
+  if (embedToken) {
+    return `Bearer ${token}`;
+  }
+  if (client === "opencode") {
+    return `Bearer {env:${tokenEnv}}`;
+  }
+  if (client === "claude") {
+    return `Bearer \${${tokenEnv}}`;
+  }
+  return `Bearer \${env:${tokenEnv}}`;
+}
+
+/**
+ * @param {string} url
+ * @param {string} tokenEnv
+ * @param {string | undefined} token
+ * @param {boolean} embedToken
+ * @param {number} timeoutMs
+ * @returns {Record<string, unknown>}
+ */
+function remoteEntry(url, tokenEnv, token, embedToken, timeoutMs) {
+  return {
+    type: "remote",
+    url,
+    enabled: true,
+    oauth: false,
+    headers: { Authorization: authHeader("opencode", tokenEnv, token, embedToken) },
+    timeout: timeoutMs
+  };
+}
+
+/**
+ * OpenCode 本地 stdio MCP 配置。
+ *
+ * @param {"legacy"|"v2"} format
+ * @returns {Record<string, unknown>}
+ */
+function openCodeLocalEntry(format) {
+  const base = {
+    type: "local",
+    command: [process.execPath, STDIO_BIN],
+    cwd: "."
+  };
+  if (format === "v2") {
+    return { ...base, disabled: false, timeout: { startup: STARTUP_TIMEOUT_MS, catalog: CATALOG_TIMEOUT_MS, execution: DEFAULT_TIMEOUT_MS } };
+  }
+  return { ...base, enabled: true };
+}
+
+/**
+ * @param {string} client
+ * @param {string} url
+ * @param {string} tokenEnv
+ * @param {string | undefined} token
+ * @param {boolean} embedToken
+ * @param {{ withLocal: boolean, opencodeFormat: "legacy"|"v2", timeoutMs: number }} options
+ * @returns {Record<string, unknown>}
+ */
+function mcpEntry(client, url, tokenEnv, token, embedToken, options) {
+  const headers = { Authorization: authHeader(client, tokenEnv, token, embedToken) };
+  if (client === "opencode") {
+    if (options.opencodeFormat === "v2") {
+      return {
+        type: "remote",
+        url,
+        oauth: false,
+        headers,
+        timeout: {
+          startup: STARTUP_TIMEOUT_MS,
+          catalog: CATALOG_TIMEOUT_MS,
+          execution: options.timeoutMs
+        }
+      };
+    }
+    return { ...remoteEntry(url, tokenEnv, token, embedToken, options.timeoutMs) };
+  }
+  if (client === "claude") {
+    return { type: "http", url, headers };
+  }
+  return { url, headers, disabled: false, autoApprove: [] };
+}
+
+/**
+ * 生成客户端配置计划。
+ *
+ * @param {string} client
+ * @param {string} dir
+ * @param {string} url
+ * @param {string} tokenEnv
+ * @param {string | undefined} token
+ * @param {boolean} embedToken
+ * @param {{ withLocal: boolean, opencodeFormat: "legacy"|"v2", timeoutMs: number }} options
+ * @returns {{ path: string, before: string | null, after: string }}
+ */
+function clientPlan(client, dir, url, tokenEnv, token, embedToken, options) {
+  const entry = mcpEntry(client, url, tokenEnv, token, embedToken, options);
+
+  if (client === "opencode") {
+    const file = path.join(dir, "opencode.json");
+    const existed = fs.existsSync(file);
+    const config = readJson(file, { $schema: "https://opencode.ai/config.json" });
+    if (options.opencodeFormat === "v2") {
+      config.mcp = config.mcp && typeof config.mcp === "object" ? config.mcp : {};
+      config.mcp.servers = config.mcp.servers && typeof config.mcp.servers === "object"
+        ? config.mcp.servers : {};
+      config.mcp.servers["gx-code"] = entry;
+      if (options.withLocal) {
+        config.mcp.servers["gx-local"] = openCodeLocalEntry("v2");
+      }
+    }
+    else {
+      config.mcp = config.mcp || {};
+      config.mcp["gx-code"] = entry;
+      if (options.withLocal) {
+        config.mcp["gx-local"] = openCodeLocalEntry("legacy");
+      }
+    }
+    return {
+      path: file,
+      before: existed ? readText(file) : null,
+      after: `${JSON.stringify(config, null, 2)}\n`
+    };
+  }
+
+  if (client === "claude") {
+    const file = path.join(dir, ".mcp.json");
+    const existed = fs.existsSync(file);
+    const config = readJson(file, { mcpServers: {} });
+    config.mcpServers = config.mcpServers || {};
+    config.mcpServers["gx-code"] = entry;
+    if (options.withLocal) {
+      config.mcpServers["gx-local"] = {
+        type: "stdio",
+        command: process.execPath,
+        args: [STDIO_BIN]
+      };
+    }
+    return {
+      path: file,
+      before: existed ? readText(file) : null,
+      after: `${JSON.stringify(config, null, 2)}\n`
+    };
+  }
+
+  if (client === "cline") {
+    const file = path.join(dir, ".gx", "cline-mcp-settings.json");
+    const existed = fs.existsSync(file);
+    const config = readJson(file, { mcpServers: {} });
+    config.mcpServers = config.mcpServers || {};
+    config.mcpServers["gx-code"] = entry;
+    if (options.withLocal) {
+      config.mcpServers["gx-local"] = {
+        command: process.execPath,
+        args: [STDIO_BIN],
+        disabled: false,
+        autoApprove: []
+      };
+    }
+    return {
+      path: file,
+      before: existed ? readText(file) : null,
+      after: `${JSON.stringify(config, null, 2)}\n`
+    };
+  }
+
+  throw new UsageError(`不支持的客户端：${client}，可选 opencode / claude / cline`);
+}
+
+/**
+ * 注入平台规范块。
+ *
+ * @param {string} existing
+ * @param {string} rules
+ * @returns {string}
+ */
+export function injectRulesText(existing, rules) {
+  const block = `${RULES_START}\n${rules.trim()}\n${RULES_END}`;
+  const start = existing.indexOf(RULES_START);
+  const end = existing.indexOf(RULES_END);
+  if (start >= 0 && end > start) {
+    return `${existing.slice(0, start)}${block}${existing.slice(end + RULES_END.length)}`;
+  }
+  return existing.trim() ? `${existing.trimEnd()}\n\n${block}\n` : `${block}\n`;
+}
+
+/**
+ * 生成项目绑定块。
+ *
+ * @param {{ planId?: string, templateId?: string, mcpUrl?: string, generatedDir?: string }} input
+ * @returns {string}
+ */
+export function buildProjectBinding(input) {
+  const planId = input.planId || "<planId>";
+  const templateId = input.templateId || "<templateId>";
+  const generatedDir = input.generatedDir || "<按 .gx/manifest.json 的实际路径填写>";
+  return `## GX 项目绑定
+
+- planId: ${planId}
+- templateId: ${templateId}
+- MCP Server: gx-code（remote）
+- 本地校验: gx-local（stdio，可选）
+- 生成层目录: ${generatedDir}
+- MCP 地址: ${input.mcpUrl || "<mcpUrl>"}
+
+### 固定动作
+1. 任何结构问题先调用 get_task_context 或 get_plan_structure，不要猜字段。
+2. 任何写操作先 dryRun=true，展示 affectedFiles / changeSet / warnings，得到确认后再 apply。
+3. 生成层文件只允许通过 generate_code + gx pull/apply 更新。
+4. 行为代码只写扩展层，并加 @ExtMethod。
+5. 结束前执行 gx verify --strict、gx scan、gx audit --strict；有切片变更再执行 gx chunks。`;
+}
+
+/**
+ * 从 manifest 推断生成层目录。
+ *
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function detectGeneratedDirs(dir) {
+  const manifest = readJson(path.join(dir, ".gx", "manifest.json"), null);
+  const files = Array.isArray(manifest?.files) ? manifest.files : [];
+  const dirs = [];
+  for (const item of files) {
+    const value = typeof item === "string" ? item : item?.path;
+    if (typeof value !== "string" || !value.trim()) {
+      continue;
+    }
+    const normalized = value.replaceAll("\\", "/");
+    const dirname = path.posix.dirname(normalized);
+    if (dirname && dirname !== "." && !dirs.includes(dirname)) {
+      dirs.push(dirname);
+    }
+    if (dirs.length >= 5) {
+      break;
+    }
+  }
+  return dirs;
+}
+
+/**
+ * 生成规则文件计划。
+ *
+ * @param {string} dir
+ * @param {string} rulesPath
+ * @param {string} binding
+ * @returns {{ path: string, before: string | null, after: string }}
+ */
+function rulesPlan(dir, rulesPath, binding) {
+  const preferred = ["AGENTS.md", "CLAUDE.md"];
+  const target = preferred.map((name) => path.join(dir, name)).find((file) => fs.existsSync(file))
+    || path.join(dir, "AGENTS.md");
+  const before = fs.existsSync(target) ? readText(target) : null;
+  const rules = fs.readFileSync(rulesPath, "utf8");
+  const content = binding ? `${rules.trim()}\n\n${binding.trim()}\n` : rules;
+  return { path: target, before, after: injectRulesText(before ?? "", content) };
+}
+
+/**
+ * 生成 .gx/.gitignore 计划。
+ *
+ * @param {string} dir
+ * @returns {{ path: string, before: string | null, after: string } | null}
+ */
+function gitignorePlan(dir) {
+  const file = path.join(dir, ".gx", ".gitignore");
+  const existed = fs.existsSync(file);
+  const before = existed ? readText(file) : null;
+  const existingLines = (before ?? "")
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const missing = GITIGNORE_LINES.filter((line) => !existingLines.includes(line));
+  if (missing.length === 0) {
+    return null;
+  }
+  return {
+    path: file,
+    before,
+    after: `${[...existingLines, ...missing].join("\n")}\n`
+  };
+}
+
+/**
+ * 生成项目配置计划。
+ *
+ * @param {string} dir
+ * @param {string | undefined} planId
+ * @param {string} mcpUrl
+ * @param {string | undefined} templateId
+ * @returns {{ path: string, before: string | null, after: string } | null}
+ */
+function projectPlan(dir, planId, mcpUrl, templateId) {
+  if (!planId && !templateId) {
+    return null;
+  }
+  const file = path.join(dir, ".gx", "config.json");
+  const existed = fs.existsSync(file);
+  const config = readJson(file, {});
+  if (planId) {
+    config.planId = planId;
+  }
+  if (mcpUrl) {
+    config.mcpUrl = mcpUrl;
+  }
+  if (templateId) {
+    config.templateId = templateId;
+  }
+  return {
+    path: file,
+    before: existed ? readText(file) : null,
+    after: `${JSON.stringify(config, null, 2)}\n`
+  };
+}
+
+/**
+ * @param {Record<string, unknown>} args
+ * @param {{ stdin: NodeJS.ReadStream, stdout: NodeJS.WriteStream, stderr: NodeJS.WriteStream }} io
+ * @returns {Promise<boolean>}
+ */
+async function confirm(plan, io) {
+  if (!io.stdin.isTTY) {
+    throw new ApprovalRequiredError("非交互模式写入需要 --yes 确认");
+  }
+  io.stderr.write(`即将写入 ${plan.length} 个文件：\n`);
+  for (const item of plan) {
+    io.stderr.write(`  - ${item.path}${item.before === null ? "（新建）" : "（更新）"}\n`);
+  }
+  const rl = readline.createInterface({ input: io.stdin, output: io.stdout });
+  try {
+    const answer = await rl.question("继续？[y/N] ");
+    return /^y(es)?$/iu.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * 连接检查：ping + tools/list + get_current_user。
+ *
+ * @param {string} url
+ * @param {string | undefined} token
+ * @param {number} timeoutMs
+ * @returns {Promise<Record<string, unknown>>}
+ */
+async function verifyConnection(url, token, timeoutMs) {
+  if (!token) {
+    return { status: "skipped", reason: "未提供 Token" };
+  }
+  const client = new McpHttpClient({
+    url,
+    token,
+    clientName: "gx-code-agent-init",
+    timeoutMs
+  });
+  try {
+    await client.initialize();
+    const tools = await client.listTools();
+    const ping = await client.callTool("ping", { client: "gx init" });
+    let user = null;
+    try {
+      user = await client.callTool("get_current_user", {});
+    }
+    catch {
+      user = null;
+    }
+    return {
+      status: "ok",
+      protocolVersion: client.protocolVersion,
+      toolCount: tools.length,
+      tools: tools.map((item) => item.name).filter(Boolean),
+      ping,
+      user
+    };
+  }
+  catch (error) {
+    return {
+      status: "failed",
+      reason: error instanceof Error ? error.message : String(error)
+    };
+  }
+  finally {
+    await client.close().catch(() => {});
+  }
+}
+
+/**
+ * 输出连接检查结果。
+ *
+ * @param {Record<string, unknown>} verification
+ * @param {NodeJS.WriteStream} stdout
+ */
+function printVerification(verification, stdout) {
+  if (verification.status === "skipped") {
+    stdout.write(`- 连接检查: 跳过（${verification.reason}）\n`);
+    return;
+  }
+  if (verification.status === "failed") {
+    stdout.write(`- 连接检查: 失败（${verification.reason}）\n`);
+    return;
+  }
+  const user = verification.user && typeof verification.user === "object" ? verification.user : null;
+  const scopes = Array.isArray(user?.scopes) ? user.scopes.join(",") : "";
+  const planScope = Array.isArray(user?.planScope) ? user.planScope.join(",") : "";
+  stdout.write(`- 连接检查: OK（协议 ${verification.protocolVersion}，工具 ${verification.toolCount} 个）\n`);
+  if (user) {
+    stdout.write(`- 当前用户: userId=${user.userId ?? "-"}, tokenId=${user.tokenId ?? "-"}\n`);
+    stdout.write(`- scopes: ${scopes || "-"}\n`);
+    stdout.write(`- planScope: ${planScope || "全部方案"}\n`);
+  }
+}
+
+/**
+ * 执行 gx init。
+ *
+ * @param {Record<string, unknown>} args
+ * @param {{ stdin: NodeJS.ReadStream, stdout: NodeJS.WriteStream, stderr: NodeJS.WriteStream }} [io]
+ * @returns {Promise<Record<string, unknown>>}
+ */
+export async function runInit(args, io = { stdin: process.stdin, stdout: process.stdout, stderr: process.stderr }) {
+  const client = String(args.client || "opencode");
+  const url = String(args.url || "http://127.0.0.1:4013/mcp");
+  const tokenEnv = String(args["token-env"] || "GX_API_TOKEN");
+  const embedToken = Boolean(args["embed-token"]);
+  const token = typeof args.token === "string" ? args.token : process.env[tokenEnv];
+  const dir = path.resolve(String(args.dir || process.cwd()));
+  const dryRun = Boolean(args["dry-run"]);
+  const check = Boolean(args.check);
+  const yes = Boolean(args.yes);
+  const withLocal = Boolean(args["with-local"]);
+  const skipVerify = Boolean(args["skip-verify"]) || process.env.GX_INIT_SKIP_VERIFY === "1";
+  const opencodeFormat = String(args["opencode-format"] || "legacy");
+  const timeoutMs = Number(args.timeout || DEFAULT_TIMEOUT_MS);
+  const existingConfig = readJson(path.join(dir, ".gx", "config.json"), {});
+  const planId = typeof args.plan === "string" ? args.plan : existingConfig.planId;
+  const templateId = typeof args.template === "string" ? args.template : existingConfig.templateId;
+  const generatedDir = typeof args["generated-dir"] === "string"
+    ? args["generated-dir"]
+    : detectGeneratedDirs(dir).join(", ");
+
+  if (embedToken && !token) {
+    throw new UsageError("使用 --embed-token 时必须提供 --token 或设置对应环境变量。");
+  }
+  if (!embedToken && !token) {
+    io.stderr.write(`[gx] 未检测到 ${tokenEnv}，配置将写入环境变量引用；启动客户端前请设置该变量。\n`);
+  }
+  if (!fs.existsSync(dir)) {
+    throw new UsageError(`目标目录不存在：${dir}`);
+  }
+  if (client === "opencode" && !["legacy", "v2"].includes(opencodeFormat)) {
+    throw new UsageError("--opencode-format 仅支持 legacy 或 v2");
+  }
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new UsageError("--timeout 必须是正整数毫秒");
+  }
+
+  const rulesPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../templates/platform-rules.md");
+  const binding = buildProjectBinding({ planId, templateId, mcpUrl: url, generatedDir });
+  const plan = [
+    clientPlan(client, dir, url, tokenEnv, token, embedToken, { withLocal, opencodeFormat, timeoutMs }),
+    rulesPlan(dir, rulesPath, binding)
+  ];
+  const project = projectPlan(dir, planId, url, templateId);
+  if (project) {
+    plan.push(project);
+  }
+  const gitignore = gitignorePlan(dir);
+  if (gitignore) {
+    plan.push(gitignore);
+  }
+
+  if (check) {
+    const changed = plan.filter((item) => item.before !== item.after);
+    io.stdout.write("检查模式（不写入任何文件）\n");
+    if (changed.length === 0) {
+      io.stdout.write("- 配置文件: 已是最新\n");
+    }
+    else {
+      io.stdout.write(`- 配置文件: 需要更新 ${changed.length} 个\n`);
+      for (const item of changed) {
+        io.stdout.write(`  - ${item.path}\n`);
+      }
+    }
+    const verification = skipVerify
+      ? { status: "skipped", reason: "使用 --skip-verify" }
+      : await verifyConnection(url, token, Math.min(timeoutMs, 5000));
+    printVerification(verification, io.stdout);
+    const failed = changed.length > 0 || verification.status === "failed";
+    if (failed) {
+      throw new Error(changed.length > 0 ? "配置需要更新，请执行 gx init 写入" : "连接检查失败");
+    }
+    return { status: "checked", files: plan.map((item) => item.path), verification };
+  }
+
+  if (dryRun) {
+    printPlan(plan);
+    return { status: "planned", files: plan.map((item) => item.path) };
+  }
+
+  const approved = yes || await confirm(plan, io);
+  if (!approved) {
+    throw new ApprovalRequiredError("用户取消写入");
+  }
+
+  const backupRoot = createBackupRoot(dir);
+  const transaction = new InitTransaction(dir, backupRoot);
+  try {
+    for (const item of plan) {
+      transaction.record(item.path);
+      writeText(item.path, item.after);
+    }
+  }
+  catch (error) {
+    transaction.rollback();
+    throw error;
+  }
+  pruneBackups(dir);
+
+  const verification = skipVerify
+    ? { status: "skipped", reason: "使用 --skip-verify" }
+    : await verifyConnection(url, token, Math.min(timeoutMs, 5000));
+
+  io.stdout.write("\n初始化完成。\n");
+  io.stdout.write(`- 客户端: ${client}${client === "opencode" ? `（${opencodeFormat}）` : ""}\n`);
+  io.stdout.write(`- MCP 地址: ${url}\n`);
+  io.stdout.write(`- 鉴权方式: ${embedToken ? "明文 Token（已写入配置，请勿提交）" : `环境变量 ${tokenEnv}`}\n`);
+  io.stdout.write(`- 本地 MCP: ${withLocal ? "已注册 gx-local" : "未注册（可加 --with-local）"}\n`);
+  for (const item of plan) {
+    io.stdout.write(`- 已写入: ${item.path}\n`);
+  }
+  printVerification(verification, io.stdout);
+  io.stdout.write("\n下一步：重启客户端，确认 gx-code 已连接。\n");
+
+  return { status: "applied", files: plan.map((item) => item.path), verification };
+}

package/src/application/pullWorkflow.js

@@ -0,0 +1,74 @@
+import path from "node:path";
+
+import { McpHttpClient } from "../adapters/platform/mcpClient.js";
+import { readJson, writeJson, writeText } from "../store/localStore.js";
+
+/**
+ * 从平台拉取生成结果并写入本地 .gx 目录。
+ *
+ * @param {Record<string, unknown>} args
+ * @param {{ stdout: NodeJS.WriteStream, stderr: NodeJS.WriteStream }} io
+ * @returns {Promise<Record<string, unknown>>}
+ */
+export async function runPull(args, io = { stdout: process.stdout, stderr: process.stderr }) {
+  const dir = path.resolve(String(args.dir || process.cwd()));
+  const config = readJson(path.join(dir, ".gx", "config.json"), {});
+  const planId = String(args.plan || config.planId || "");
+  const templateId = String(args.template || config.templateId || "");
+  const url = String(args.url || config.mcpUrl || "http://127.0.0.1:4013/mcp");
+  const token = String(args.token || process.env.GX_API_TOKEN || "");
+  const modelIds = typeof args["model-ids"] === "string"
+    ? args["model-ids"].split(",").map((item) => item.trim()).filter(Boolean)
+    : undefined;
+  const dryRun = Boolean(args["dry-run"]);
+
+  if (!planId) {
+    throw new Error("gx pull 需要 --plan 或 .gx/config.json 中的 planId");
+  }
+  if (!templateId) {
+    throw new Error("gx pull 需要 --template 或 .gx/config.json 中的 templateId");
+  }
+  if (!token) {
+    throw new Error("缺少 API Token；请设置 GX_API_TOKEN 或传入 --token");
+  }
+
+  const client = new McpHttpClient({ url, token });
+  try {
+    const result = await client.callTool("generate_code", {
+      planId,
+      templateId,
+      modelIds,
+      includeContent: true
+    });
+    if (!result || !Array.isArray(result.files) || !result.manifest) {
+      throw new Error("generate_code 返回结构不完整");
+    }
+    io.stdout.write(`生成成功：${result.files.length} 个文件，metadataVersion=${result.metadataVersion}\n`);
+    for (const warning of result.warnings ?? []) {
+      io.stderr.write(`[warn] ${warning}\n`);
+    }
+    if (dryRun) {
+      for (const file of result.files) {
+        io.stdout.write(`[dry-run] ${file.path} sha256=${file.sha256}\n`);
+      }
+      return { status: "planned", planId, templateId, fileCount: result.files.length };
+    }
+
+    for (const file of result.files) {
+      const target = path.join(dir, ".gx", "generated", file.path);
+      writeText(target, file.content ?? "");
+    }
+    writeJson(path.join(dir, ".gx", "manifest.json"), result.manifest);
+    writeJson(path.join(dir, ".gx", "pull.json"), {
+      planId,
+      templateId,
+      metadataVersion: result.metadataVersion,
+      generatedAt: result.generatedAt,
+      fileCount: result.files.length
+    });
+    io.stdout.write(`已写入 .gx/generated 与 .gx/manifest.json\n`);
+    return { status: "pulled", planId, templateId, fileCount: result.files.length };
+  } finally {
+    await client.close();
+  }
+}