agent-syncer 0.1.0 → 0.1.2

package/lib/commands/init.js

@@ -0,0 +1,332 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { CONFIG_FILENAME, loadConfig, mergeConfig, readConfigRaw, writeConfig } from '../config.js';
+import { dim, fail, info, ok, plain, skip, title, warn } from '../log.js';
+import { listBundles, loadRepo } from '../manifest.js';
+import { checkbox, confirm, isInteractive, select, text } from '../prompt.js';
+import { fetchRepo, isGitUrl, listRefs, orderRefs } from '../source.js';
+import { TOOL_NAMES } from '../target.js';
+import { buildLinkChoices } from './link.js';
+
+/**
+ * 取消（Ctrl-C，或者对「确认写入」答了否）时的统一收尾。
+ *
+ * **退出码是 0**：走到这一步什么都还没写，用户只是不想继续了，
+ * 不是出错。报非零会让脚本把「他自己取消的」当成失败。
+ */
+function cancelled() {
+  plain(dim('已取消，未做任何改动。'));
+  return 0;
+}
+
+/**
+ * 非交互环境下的退路：把配置该怎么写直接摊开。
+ *
+ * 和 link 的做法一致——**绝不猜，也绝不问**。在 CI / 管道 / postinstall 里
+ * 弹提示会永久挂住，这个仓库里没有比这更硬的规矩。
+ */
+function nonInteractiveHelp() {
+  fail('init 需要交互终端');
+  plain('  当前不是交互终端（管道、CI、postinstall 里弹提示会永久挂住，所以不问）。');
+  plain(`  手写一份 ${CONFIG_FILENAME} 放在项目根即可：`);
+  const sample = {
+    content: '<内容仓库：本地路径 或 git 地址>',
+    ref: '<分支 / 标签 / 提交 SHA，可省略>',
+    bundle: 'java-backend',
+    links: ['claude'],
+  };
+  for (const line of JSON.stringify(sample, null, 2).split('\n')) plain(`  ${dim(line)}`);
+  plain('');
+  plain(`  links 里写${dim('工具名')}（可用：${TOOL_NAMES.join('、')}）。`);
+  plain(`  不知道有哪些模板：agent-syncer list --from=<内容仓库>`);
+  return 1;
+}
+
+/**
+ * `--bundle=a,b` 的解析。和 sync 里那段保持一致——同一个选项在两个命令里
+ * 意思不一样会让人踩坑。
+ *
+ * @param {any} value @returns {string[]}
+ */
+function splitBundles(value) {
+  return typeof value === 'string'
+    ? value
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : [];
+}
+
+/**
+ * agent-syncer init —— 交互式生成 `agents.json`。
+ *
+ * 依次问五件事：内容仓库在哪 → 用哪个版本（ref）→ 装哪些模板 → 适配哪些工具
+ * → 确认。**只有最后确认过才落盘**，中途 Ctrl-C 一律什么都不写。
+ *
+ * 每一步都尽量**跳过而不是失败**：内容仓库不是 git 仓库、离线、要凭据——
+ * 取不到 refs 就跳过第二步，取不到 bundles 就跳过第三步。用户先把一份能用的
+ * 配置写下来，比被一个「拿不到列表」卡住有价值得多。
+ *
+ * 输入输出可注入，生产环境用默认值，测试时可传替身跑完整交互链路。
+ *
+ * @param {{cwd: string, flags?: Record<string, any>, input?: NodeJS.ReadStream, output?: NodeJS.WriteStream}} ctx
+ */
+export async function run({ cwd, flags = {}, input = process.stdin, output = process.stdout }) {
+  title('agent-syncer init');
+  plain(dim(`项目根：${cwd}`));
+
+  if (!isInteractive(input, output)) return nonInteractiveHelp();
+
+  /** @type {ReturnType<typeof loadConfig>} */
+  let config;
+  try {
+    config = loadConfig(cwd);
+  } catch (e) {
+    // 读不出来就得停：init 会把整份文件重写一遍，而它读不出原来写了什么。
+    //
+    // **别建议「删掉重来」**——这份文件里可能有用户手写的 include / exclude /
+    // protect，而它们**没有第二处能推导出来**，init 恰恰就是那个会把整份重写掉的命令。
+    // 一句轻飘飘的「删掉重来」正好把人推向最坏的那条路。
+    fail(/** @type {Error} */ (e).message);
+    plain('  init 要把整份文件重写一遍，读不出来就不能往下走——先修好它。');
+    plain(dim('  里面的 include / exclude / protect 是你手写的，本工具没有第二处能推出它们。'));
+    return 1;
+  }
+
+  /** 文件里原有的字段，逐字保留——这是「不做覆盖式重写」的依据 */
+  const existing = config.exists ? readConfigRaw(cwd) : {};
+
+  // 已经配过一次的项目，先把现状摆出来再问要不要重来。这是**两道确认里的第一道**：
+  // 第一道问「要不要重新生成」，最后一道问「就写这些吗」。
+  if (config.exists) {
+    plain('');
+    info(`${CONFIG_FILENAME} 已存在，只重问下面几项，其它字段照旧`);
+    for (const line of JSON.stringify(existing, null, 2).split('\n')) plain(`  ${dim(line)}`);
+    const go = await confirm({ message: `重新生成 ${CONFIG_FILENAME}？`, initial: true, input, output });
+    if (!go) return cancelled();
+  }
+
+  // ---- 第 1 步：内容仓库 ----
+  //
+  // --from / agents.json 里的 content 都当作**预填值**：用户上一秒才在命令行里
+  // 说过的事，没有道理再让他手打一遍。
+  title('第 1 步 · 内容仓库');
+  const typed = await text({
+    message: '内容仓库在哪？（本地路径 或 git 地址）',
+    initial: typeof flags.from === 'string' ? flags.from : (config.content ?? ''),
+    validate: (v) => (v.trim() === '' ? '不能为空：写一个本地路径或 git 地址' : null),
+    input,
+    output,
+  });
+  if (typed === null) return cancelled();
+  const source = typed.trim();
+
+  // 路径不存在不是错误：内容仓库可能还没克隆下来，配置先写下来照样有用。
+  // 但不说一声的话，用户会以为已经万事俱备了。
+  if (!isGitUrl(source) && !fs.existsSync(path.resolve(cwd, source))) {
+    warn(`这个路径不存在：${path.resolve(cwd, source)}——配置先写下来也行，sync 会再报一次`);
+  }
+
+  // ---- 第 2 步：ref ----
+  //
+  // 三态，别混成一个：
+  //   undefined —— 这一步跳过了（取不到 refs），文件里原来的 ref 原样保留
+  //   null      —— 用户明确选了「不指定」，把 ref 字段删掉
+  //   字符串     —— 用户选了一个分支或标签
+  title('第 2 步 · 版本（ref）');
+  /** @type {string|null|undefined} */
+  let pickedRef;
+
+  // **本地路径不问这一项。** 一个本地克隆目录也是 git 仓库，分支标签都列得出来，
+  // 但 `sync` 读的是那个目录的**工作树**（这正是本地路径「改完内容立刻能试」的
+  // 来由），`ref` 一个字都用不上。让用户选一个不生效的版本比不让他选更糟——
+  // 他会以为钉住了。要钉版本就把 content 写成 git 地址。
+  //
+  // 注意这里**不把 --ref 写进配置**：写下去就是个不生效的键，和「选了不生效」
+  // 是同一个坑。给过 --ref 的人本来就想要版本钉死，那句话得让他听见。
+  const refs = isGitUrl(source) ? listRefs({ source, cwd }) : null;
+
+  if (!isGitUrl(source)) {
+    skip('本地路径由你自己的检出决定内容，没有版本可选——跳过这一步');
+    const flagRef = typeof flags.ref === 'string' ? flags.ref.trim() : '';
+    if (flagRef !== '') {
+      warn(`--ref=${flagRef} 没写进配置：对本地路径不生效。要钉版本请把内容仓库写成 git 地址`);
+    }
+  } else if (refs === null || (refs.branches.length === 0 && refs.tags.length === 0)) {
+    // 「不是 git 仓库」「离线」「要凭据」「超时」在这里是同一种处境：问不出选项。
+    // 一行说明带过，不报错——这正是 listRefs 返回 null 而不是抛错的原因。
+    skip('取不到分支和标签（不是 git 仓库、离线，或需要凭据）——跳过这一步');
+    if (typeof flags.ref === 'string' && flags.ref.trim() !== '') pickedRef = flags.ref.trim();
+    if (pickedRef) plain(dim(`  沿用你给的 --ref=${pickedRef}`));
+  } else {
+    // 「不指定」和「选 main」行为很接近，都得每次 sync 重新取最新——真正的区别在
+    // 标签：标签是钉死的版本，内容不会跟着仓库走。这句话不说，用户没理由知道
+    // 该不该选。
+    plain(dim('  不指定 / 分支：每次 sync 取最新　　标签：内容钉死，仓库变了也不跟'));
+    const tagSet = new Set(refs.tags);
+    const choices = [
+      { value: '', label: '不指定', note: '（取仓库默认分支的最新）' },
+      ...orderRefs(refs).map((name) => ({
+        value: name,
+        label: name,
+        note: tagSet.has(name) ? '（标签：钉死的版本）' : '',
+      })),
+    ];
+
+    // 只预填用户说过的那个值（--ref 或文件里已有的 ref）。**不替他猜 main**：
+    // 仓库同时有 main 和 master 时猜错方向，会把他悄悄钉在一个过时的分支上。
+    const flagRef = typeof flags.ref === 'string' ? flags.ref.trim() : '';
+    const want = flagRef !== '' ? flagRef : config.ref;
+    const found = want ? choices.findIndex((c) => c.value === want) : -1;
+
+    const picked = await select({
+      message: '用哪个版本？',
+      choices,
+      initial: found >= 0 ? found : 0,
+      filterable: true,
+      input,
+      output,
+    });
+    if (picked === null) return cancelled();
+    pickedRef = picked === '' ? null : picked;
+  }
+
+  // ---- 第 3 步：模板 ----
+  //
+  // 到这里必须真的看到 bundles/*.json 了，所以要拿到仓库的本地根目录（远端就浅克隆
+  // 一份，和 list 命令一样）。取不到**不算错**——没网也得能把配置写下来，
+  // 只是模板留空、由用户之后自己补。
+  title('第 3 步 · 模板（bundle）');
+  const flagBundles = splitBundles(flags.bundle);
+  const wantBundles = flagBundles.length > 0 ? flagBundles : config.bundles;
+  /** @type {string[]|undefined} */
+  let pickedBundles;
+
+  /** @type {string|null} */
+  let repoRoot = null;
+  /** @type {(() => void)|null} */
+  let cleanup = null;
+  /** @type {string|null} */
+  let repoProblem = null;
+  try {
+    if (isGitUrl(source)) {
+      const fetched = fetchRepo({ url: source, ref: pickedRef ?? undefined });
+      repoRoot = fetched.root;
+      cleanup = fetched.cleanup;
+    } else {
+      repoRoot = path.resolve(cwd, source);
+    }
+    loadRepo(repoRoot);
+  } catch (e) {
+    repoProblem = /** @type {Error} */ (e).message;
+    repoRoot = null;
+    if (cleanup) {
+      cleanup();
+      cleanup = null;
+    }
+  }
+
+  try {
+    if (repoRoot === null) {
+      warn(`读不到内容仓库，跳过模板选择：${repoProblem}`);
+      // 用户明确给过的 --bundle 别丢：写进配置至少能让 sync 的报错说清是哪个模板不对
+      if (flagBundles.length > 0) pickedBundles = flagBundles;
+      plain(dim(`  之后可以在 ${CONFIG_FILENAME} 里补 "bundle"。`));
+    } else {
+      const bundles = listBundles(repoRoot);
+      const available = new Set(bundles.map((b) => b.name));
+
+      // `--bundle=<拼错的名字>` 默认会**悄悄蒸发**：那几项匹配不上 → 复选框一个都不勾 →
+      // 用户回车 → `bundle` 键被删掉，全程没有一句提示。人以为自己选了模板，
+      // 拿到的配置里没有它——和 `link` 拒绝静默兼容 `"claude/skills"` 是同一个道理。
+      const unknown = flagBundles.filter((n) => !available.has(n));
+      if (unknown.length > 0) {
+        fail(`--bundle 里的模板在仓库里不存在：${unknown.join('、')}`);
+        plain(
+          `  可用的模板：${
+            bundles.length > 0 ? bundles.map((b) => b.name).join('、') : '（一个都没有）'
+          }`,
+        );
+        return 1;
+      }
+
+      if (bundles.length === 0) {
+        // 这一步是**跳过**，不是「用户选了空」。仓库里没有模板 ≠ 他想把原来的模板清掉，
+        // 所以保持 undefined（原样保留），和 ref 那一步是同一个三态口径。
+        skip('仓库里没有任何模板（只能靠 include 逐条挑）');
+        if (flagBundles.length > 0) pickedBundles = flagBundles;
+        plain(dim(`  之后可以在 ${CONFIG_FILENAME} 里补 "bundle"。`));
+      } else {
+        plain(dim('  模板可以多选，取并集；一个都不选也行（之后用 include 逐条挑）'));
+        const picked = await checkbox({
+          message: '这个项目要装哪些模板？',
+          choices: bundles.map((b) => ({
+            value: b.name,
+            label: b.title ? `${b.name} · ${b.title}` : b.name,
+            note: b.description ?? '',
+            checked: wantBundles.includes(b.name),
+          })),
+          input,
+          output,
+        });
+        if (picked === null) return cancelled();
+        pickedBundles = picked;
+      }
+    }
+
+    // ---- 第 4 步：links ----
+    //
+    // 复用 link 命令的 choices：note 里写着「暂无内容」「会新建 .claude/」，
+    // 那正是用户要判断的东西。复制一份出来的话，两边迟早会长得不一样。
+    title('第 4 步 · 编码工具');
+    const tools = await checkbox({
+      message: `这个项目用哪些编码工具？（写进 ${CONFIG_FILENAME} 的 "links"）`,
+      choices: buildLinkChoices(cwd, config.tools),
+      input,
+      output,
+    });
+    if (tools === null) return cancelled();
+    if (tools.length === 0) {
+      warn('一个工具都没选——links 会是空的，link / sync 跑起来会无事可做');
+    }
+
+    // ---- 第 5 步：确认、落盘、问要不要 sync ----
+    title('第 5 步 · 确认');
+    /** @type {Record<string, any>} */
+    const patch = { content: source, links: tools };
+    if (pickedRef !== undefined) patch.ref = pickedRef;
+    if (pickedBundles !== undefined) patch.bundle = pickedBundles;
+
+    // 预览走的就是 saveConfig 内部那一套合并逻辑（同一个纯函数），所以「看到的」
+    // 和「写下去的」不可能不一致——包括文件里原有字段被保留这件事。
+    const next = mergeConfig(existing, patch);
+    plain(`  将要写入 ${CONFIG_FILENAME}：`);
+    for (const line of JSON.stringify(next, null, 2).split('\n')) plain(`  ${dim(line)}`);
+    if (config.exists) plain(dim('  （上面没提到的原有字段照旧保留）'));
+
+    const write = await confirm({ message: `写入 ${CONFIG_FILENAME}？`, initial: true, input, output });
+    if (!write) return cancelled();
+
+    // 写下去的**就是刚才预览的那一个对象**——不再读一次文件。两次读之间文件被改了，
+    // 「看到的」和「写下去的」就会不一样，而那正是这份预览存在的唯一理由。
+    const written = writeConfig(cwd, next);
+    ok(`${CONFIG_FILENAME} 已写入 → ${path.relative(cwd, written)}`);
+
+    const now = await confirm({ message: '现在执行一次 sync 吗？', initial: true, input, output });
+    if (!now) {
+      plain(dim('\n之后跑 agent-syncer sync 即可拉取内容并建链接。'));
+      return 0;
+    }
+
+    // 动态 import：init 和 sync 互相调用，静态 import 会绕成环。
+    // no-init 是给 sync 的信号——配置这时已经写好，正常情况下它也不会再走 init，
+    // 这一条是防止将来有人改了那个判断条件后变成套娃。
+    const { run: runSync } = await import('./sync.js');
+    return await runSync({ cwd, flags: { ...flags, 'no-init': true }, input, output });
+  } finally {
+    // 浅克隆下来的临时目录用完即删——无论成功、失败还是中途取消
+    if (cleanup) cleanup();
+  }
+}