agent-syncer 0.1.0 → 0.1.2

package/lib/prompt.js

@@ -1,7 +1,7 @@
 // @ts-check
 import process from 'node:process';
 import readline from 'node:readline';
-import { bold, cyan, dim, green } from './log.js';
+import { bold, cyan, dim, green, red } from './log.js';
 
 /**
  * 是否具备交互条件。
@@ -123,3 +123,366 @@ export function checkbox({ message, choices, hint, input = process.stdin, output
     render();
   });
 }
+
+/**
+ * 可打印字符吗——即「这次按键是用户想输进筛选框 / 输入框的一个字」。
+ *
+ * 判据是 readline 给的 `str`：方向键、功能键的 str 是转义序列或空串，
+ * 只有可打印字符是一个字符长。再排掉 Ctrl / Alt 组合，否则 Ctrl-A 之类
+ * 会被当成输入了一个 'a'。
+ *
+ * @param {string} str @param {import('node:readline').Key} key
+ */
+function isPrintable(str, key) {
+  return typeof str === 'string' && str.length === 1 && !key.ctrl && !key.meta && str >= ' ';
+}
+
+/**
+ * select / text / confirm 共用的骨架：接管 raw mode、把按键转给调用方，
+ * **无论走哪条路退出都恢复原状**（不恢复的话监听器会留着，进程不退出）。
+ *
+ * 与 checkbox 是同一套做法（重绘前先退回已画的行数、Ctrl-C → null、
+ * finally 里收拾干净）。没有反过来让 checkbox 也用它：那个多选已经稳定，
+ * 有一整套测试钉着，为了少几行重复去改它，风险大于收益。
+ *
+ * @param {{
+ *   input: NodeJS.ReadStream,
+ *   output: NodeJS.WriteStream,
+ *   render: (final: boolean) => string[],
+ *   onKey: (str: string, key: import('node:readline').Key, ctl: {draw: (final?: boolean) => void, finish: (result: any) => void}) => void,
+ * }} opts
+ * @returns {Promise<any>} 取消（Ctrl-C）一律返回 null
+ */
+function interactive({ input, output, render, onKey }) {
+  /** @type {(result: any) => void} */
+  let resolveFn = () => {};
+  const promise = new Promise((r) => {
+    resolveFn = r;
+  });
+
+  let drawn = 0;
+  let settled = false;
+
+  /** 重绘：先退回已画的行数再重画，避免刷屏 */
+  const draw = (final = false) => {
+    if (drawn > 0) {
+      readline.moveCursor(output, 0, -drawn);
+      readline.cursorTo(output, 0);
+      readline.clearScreenDown(output);
+    }
+    const lines = render(final);
+    output.write(`${lines.join('\n')}\n`);
+    drawn = lines.length;
+  };
+
+  /** @param {any} result */
+  const finish = (result) => {
+    if (settled) return;
+    settled = true;
+    input.removeListener('keypress', handler);
+    try {
+      input.setRawMode(false);
+    } catch {
+      // 非 TTY 时 setRawMode 会抛，忽略即可
+    }
+    input.pause();
+    try {
+      draw(true);
+    } catch {
+      // 输出流可能已被关闭，渲染失败不应影响返回值
+    }
+    resolveFn(result);
+  };
+
+  /** @param {string} str @param {import('node:readline').Key} key */
+  const handler = (str, key) => {
+    if (!key) return;
+    // Ctrl-C 是全局的「取消」：所有提示都返回 null，调用方据此不得写盘
+    if (key.ctrl && key.name === 'c') {
+      finish(null);
+      return;
+    }
+    onKey(str, key, { draw, finish });
+  };
+
+  readline.emitKeypressEvents(input);
+  try {
+    input.setRawMode(true);
+  } catch {
+    // 同上：真实交互场景下不会走到这里
+  }
+  input.resume();
+  input.on('keypress', handler);
+  draw();
+
+  return promise;
+}
+
+/**
+ * 单选列表。按键：↑↓（或 k / j）移动　回车 确认　Ctrl-C 取消。
+ *
+ * `filterable` 打开后还能就地筛选——在**下拉框里输字符缩小范围**，退格删字符，
+ * Esc 清空。这一步不是锦上添花：内容仓库的分支和标签动辄几十上百个，
+ * 只能上下翻的话找一个 tag 要按到手酸。（打开筛选后 k / j 让位给输入，
+ * 移动只认方向键。）
+ *
+ * 列表比 `maxVisible` 长时**只画可视区**（其余折叠成「上面还有 N 项」），
+ * 光标始终在窗口内。全刷出来会把前面问过的问题冲掉。
+ *
+ * @param {{
+ *   message: string,
+ *   choices: {value: string, label: string, note?: string}[],
+ *   hint?: string,
+ *   initial?: number,
+ *   maxVisible?: number,
+ *   filterable?: boolean,
+ *   input?: NodeJS.ReadStream,
+ *   output?: NodeJS.WriteStream,
+ * }} opts
+ * @returns {Promise<string|null>} 选中项的 value；取消返回 null；本来就没有可选项也返回 null
+ */
+export function select({
+  message,
+  choices,
+  hint,
+  initial = 0,
+  maxVisible = 12,
+  filterable = false,
+  input = process.stdin,
+  output = process.stdout,
+}) {
+  // 没得选就没什么可问的。调用方应当自己先判空（问「要用哪个版本」之前
+  // 总得先确认取到了版本），这里的 null 只是别让空列表把渲染搞崩。
+  if (choices.length === 0) return Promise.resolve(null);
+
+  const items = choices.map((c) => ({ ...c }));
+  let cursor = Math.min(Math.max(initial, 0), items.length - 1);
+  let filter = '';
+
+  /** 当前可选的项（筛选之后）。空筛选返回原列表，连数组都不新建 */
+  const shown = () => {
+    if (filter === '') return items;
+    const q = filter.toLowerCase();
+    return items.filter((c) => `${c.value} ${c.label}`.toLowerCase().includes(q));
+  };
+
+  const trailing =
+    hint ??
+    (filterable
+      ? '↑↓ 移动 · 回车 确认 · 输入字符筛选 · 退格删除 · Esc 清空 · Ctrl-C 取消'
+      : '↑↓ 移动 · 回车 确认 · Ctrl-C 取消');
+
+  const render = (final) => {
+    const list = shown();
+    // 筛选会让列表变短，光标要跟着收回来，否则回车会读到空位置上
+    if (cursor > list.length - 1) cursor = Math.max(0, list.length - 1);
+
+    const lines = [bold(message)];
+    if (filterable && filter !== '') lines.push(`  ${dim('筛选：')}${cyan(filter)}`);
+
+    const visible = Math.max(1, maxVisible);
+    const start =
+      list.length <= visible
+        ? 0
+        : Math.min(Math.max(cursor - Math.floor(visible / 2), 0), list.length - visible);
+    const end = Math.min(list.length, start + visible);
+
+    if (list.length === 0) {
+      lines.push(dim('  （没有匹配的项，退格或 Esc 可以改回来）'));
+    } else {
+      if (start > 0) lines.push(dim(`  ↑ 上面还有 ${start} 项`));
+      for (let i = start; i < end; i += 1) {
+        const c = list[i];
+        // 光标标记在收尾那一帧**也留着**：多选收尾时勾选状态本身就说明了结果，
+        // 单选不留下标记的话，最后一屏只剩一列一样长的选项，看不出选了哪个
+        const active = i === cursor;
+        lines.push(
+          `  ${active ? cyan('❯') : ' '} ${active ? cyan(c.label) : c.label}` +
+            `${c.note ? `  ${dim(c.note)}` : ''}`,
+        );
+      }
+      if (end < list.length) lines.push(dim(`  ↓ 下面还有 ${list.length - end} 项`));
+    }
+
+    if (!final) lines.push(dim(`  ${trailing}`));
+    return lines;
+  };
+
+  /** @param {string} str @param {import('node:readline').Key} key */
+  const onKey = (str, key, ctl) => {
+    const list = shown();
+
+    if (key.name === 'up' || (!filterable && key.name === 'k')) {
+      if (list.length === 0) return;
+      cursor = (cursor - 1 + list.length) % list.length;
+    } else if (key.name === 'down' || (!filterable && key.name === 'j')) {
+      if (list.length === 0) return;
+      cursor = (cursor + 1) % list.length;
+    } else if (key.name === 'return' || key.name === 'enter') {
+      if (list.length === 0) return;
+      const picked = list[cursor];
+      if (!picked) return;
+      ctl.finish(picked.value);
+      return;
+    } else if (filterable && key.name === 'escape') {
+      if (filter === '') return;
+      filter = '';
+      cursor = 0;
+    } else if (filterable && key.name === 'backspace') {
+      if (filter === '') return;
+      filter = filter.slice(0, -1);
+      cursor = 0;
+    } else if (filterable && isPrintable(str, key)) {
+      filter += str;
+      cursor = 0;
+    } else {
+      return;
+    }
+
+    ctl.draw();
+  };
+
+  return interactive({ input, output, render, onKey });
+}
+
+/**
+ * 单行文本输入。按键：直接输入字符　退格删除　回车 确认　Ctrl-C 取消。
+ *
+ * `initial` 是**预填的默认答案**，不是一段等着往后接的文本：用户一打字就整个替换掉。
+ * 不这样做的话，「预填一条长路径 + 用户开始打字」会拼成两个路径粘在一起，
+ * 想去掉预填还得按几十下退格——而预填值的绝大多数用途正是「懒得重打，但真要改就得换掉」。
+ * 回车原样采纳预填值这条不受影响。
+ *
+ * 返回值**原样**给出，不 trim——要不要去掉两边的空白是调用方的事
+ * （内容仓库路径要，别的未必）。`validate` 返回一段说明就停在原地重问，
+ * 而不是让一个空值混进配置里。
+ *
+ * @param {{
+ *   message: string,
+ *   initial?: string,
+ *   hint?: string,
+ *   validate?: (value: string) => string|null|undefined,
+ *   input?: NodeJS.ReadStream,
+ *   output?: NodeJS.WriteStream,
+ * }} opts
+ * @returns {Promise<string|null>} 输入的原文；取消返回 null
+ */
+export function text({
+  message,
+  initial = '',
+  hint,
+  validate,
+  input = process.stdin,
+  output = process.stdout,
+}) {
+  let value = initial;
+  /** 预填值还没被碰过——这时候打进来的第一个字符是来替换它的 */
+  let pristine = initial !== '';
+  /** @type {string|null} */
+  let error = null;
+
+  // 提示语按「有没有预填值」定，不跟着 pristine 变——提示在编辑途中换词只会让人分神
+  const trailing =
+    hint ??
+    (initial !== ''
+      ? '输入即替换预填值 · 回车 直接采纳 · Ctrl-C 取消'
+      : '直接输入 · 退格删除 · 回车 确认 · Ctrl-C 取消');
+
+  const render = (final) => {
+    const lines = [bold(message), `  ${cyan(value)}${final ? '' : dim('▌')}`];
+    if (error) lines.push(`  ${red(error)}`);
+    if (!final) lines.push(dim(`  ${trailing}`));
+    return lines;
+  };
+
+  /** @param {string} str @param {import('node:readline').Key} key */
+  const onKey = (str, key, ctl) => {
+    if (key.name === 'return' || key.name === 'enter') {
+      const problem = validate ? validate(value) : null;
+      if (problem) {
+        error = problem;
+        ctl.draw();
+        return;
+      }
+      ctl.finish(value);
+      return;
+    }
+    if (key.name === 'backspace' || key.name === 'delete') {
+      if (value === '') return;
+      value = value.slice(0, -1);
+      pristine = false;
+      error = null;
+      ctl.draw();
+      return;
+    }
+    if (isPrintable(str, key)) {
+      value = pristine ? str : value + str;
+      pristine = false;
+      error = null;
+      ctl.draw();
+    }
+  };
+
+  return interactive({ input, output, render, onKey });
+}
+
+/**
+ * 是 / 否。按键：y / n 直接作答（不等回车）　方向键或空格 切换　回车 确认　Ctrl-C 取消。
+ *
+ * 直接按 y / n 就结束，是因为这个提示只用在「要不要写盘」「要不要接着跑」
+ * 这种一句话就能答的地方，多按一次回车没有信息量。
+ *
+ * @param {{
+ *   message: string,
+ *   initial?: boolean,
+ *   hint?: string,
+ *   input?: NodeJS.ReadStream,
+ *   output?: NodeJS.WriteStream,
+ * }} opts
+ * @returns {Promise<boolean|null>} 取消返回 null
+ */
+export function confirm({
+  message,
+  initial = true,
+  hint,
+  input = process.stdin,
+  output = process.stdout,
+}) {
+  let value = Boolean(initial);
+
+  const render = (final) => {
+    const on = (/** @type {boolean} */ v) => (value === v ? cyan(`❯ ${v ? '是' : '否'}`) : dim(`  ${v ? '是' : '否'}`));
+    const lines = [bold(message), `  ${on(true)}  /  ${on(false)}`];
+    if (!final) lines.push(dim(`  ${hint ?? 'y / n 直接作答 · 方向键切换 · 回车 确认 · Ctrl-C 取消'}`));
+    return lines;
+  };
+
+  /** @param {string} str @param {import('node:readline').Key} key */
+  const onKey = (str, key, ctl) => {
+    if (key.name === 'y' || key.name === 'Y') {
+      ctl.finish(true);
+      return;
+    }
+    if (key.name === 'n' || key.name === 'N') {
+      ctl.finish(false);
+      return;
+    }
+    if (key.name === 'return' || key.name === 'enter') {
+      ctl.finish(value);
+      return;
+    }
+    if (
+      key.name === 'up' ||
+      key.name === 'down' ||
+      key.name === 'left' ||
+      key.name === 'right' ||
+      key.name === 'tab' ||
+      key.name === 'space'
+    ) {
+      value = !value;
+      ctl.draw();
+    }
+  };
+
+  return interactive({ input, output, render, onKey });
+}

package/lib/prune.js

@@ -0,0 +1,80 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * `--prune` 删完之后，把因此空掉的目录也收掉。
+ *
+ * ## 为什么敢删目录
+ *
+ * README 里那条承诺是「绝不删除实体目录」，这个模块把它**收窄**成
+ * 「绝不删除**有内容的**目录」——`fs.rmdirSync` 只对空目录成功，非空一律
+ * `ENOTEMPTY` 报错。所以这里不可能删掉任何还装着东西的目录，哪怕判断逻辑
+ * 写错了也删不掉：内核会把这一刀挡下来。
+ *
+ * 另外只认**实体**目录：`lstatSync` 一看是链接就直接放弃。Windows 上
+ * `RemoveDirectoryW` 对 junction 的语义是「摘掉重解析点」而非「删目标内容」，
+ * 所以万一传进来一个指向别处、目标非空的 junction，那一下就把别人的链接摘了。
+ * 链接归 `removeLink` 管，这里不越界。
+ *
+ * ## 为什么要删
+ *
+ * git 不跟踪空目录，所以留着不影响版本库。唯一的实际后果是**误导**：
+ * `doctor` 见到 `.trae/` 还在就会报「目录存在，但未在 links 里声明」，
+ * 而那只是上一轮 `--prune` 的残渣——用户会以为自己的配置写漏了。
+ *
+ * 调用方只在 `--prune` 分支里用它，默认（只报告）那条路上一个字节都不动。
+ */
+
+/**
+ * 空的实体目录就删掉。返回是否真的删了。
+ * @param {string} abs
+ */
+export function rmdirIfEmpty(abs) {
+  try {
+    if (!fs.lstatSync(abs).isDirectory()) return false; // 链接和普通文件一律不碰
+  } catch {
+    return false; // 不存在
+  }
+  try {
+    fs.rmdirSync(abs);
+    return true;
+  } catch {
+    // 非空、被占用、权限不足——一律当作「留着」，不抛错也不上报
+    return false;
+  }
+}
+
+/**
+ * 自下而上收空目录，`abs` 自己也算在内。返回被删掉的目录（自下而上的顺序）。
+ *
+ * 给 `scripts/` 用：里面的相对路径可能带子目录，删掉一个文件之后从它往上
+ * 可能连着空好几层，而每一层都只差最后一次 `rmdir`。
+ *
+ * @param {string} abs
+ * @returns {string[]}
+ */
+export function rmdirTreeIfEmpty(abs) {
+  /** @type {string[]} */
+  const removed = [];
+
+  /** @param {string} dir */
+  const walk = (dir) => {
+    /** @type {fs.Dirent[]} */
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      // 链接不是目录（`isDirectory()` 对 junction 在 Windows 上是 false），
+      // 两道判断都留着，免得跟着链接走到别人的地盘上去
+      if (e.isDirectory() && !e.isSymbolicLink()) walk(path.join(dir, e.name));
+    }
+    if (rmdirIfEmpty(dir)) removed.push(dir);
+  };
+
+  walk(abs);
+  return removed;
+}