scrum-skills 0.2.2 → 0.2.4

package/tools/agile-tools.mjs

@@ -0,0 +1,504 @@
+/**
+ * 敏捷数据工具（零依赖，node >= 18）
+ *
+ * AI 助手手上的两件家伙事：检索当前项目的敏捷数据、按路径打补丁改它。
+ * 这是全项目唯一「机器自动写业务数据」的入口，所以三层护栏缺一不可：
+ *   1. 只认 agile/backlog.json | sprints.json | journal.json 三个文件，别的路径一律拒；
+ *   2. 写完立刻跑 tools/validate.mjs，校验不过就把改前内容原样写回去；
+ *   3. 手动审核策略下根本不落盘，只产待审变更（propose / applyPending / rejectPending）。
+ *
+ * 补丁路径用「点号 + id」写法（不需要记下标）：
+ *   stories.S-011.status          对象字段
+ *   stories.S-011.tasks           数组本身（配 op: push / remove）
+ *   stories.S-011.tasks.2.title   数组第 2 项（纯数字段当下标）
+ *
+ * ⚠️ 写回是「按文本打补丁」，不是「整份重新 stringify」。
+ * 各家项目的数据文件排版不一样（有人一条记录一行、有人内联数组、有人 CRLF），
+ * 一旦整份重排，改一个状态就会铺出几千行 diff，合并冲突满天飞。
+ * 这里只替换被补丁命中的那段字符，其余字节一个不动。
+ */
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const validator = fileURLToPath(new URL('./validate.mjs', import.meta.url));
+
+/** 允许 AI 写回去的文件白名单——路径拼接只从这里来，杜绝越界 */
+export const AGILE_FILES = ['backlog', 'sprints', 'journal'];
+
+/** 默认校验器：直接调本仓库的 validate.mjs，与 serve 启动前的口径完全一致 */
+export function runValidate(root) {
+  try {
+    execFileSync(process.execPath, [validator, root], { encoding: 'utf8', timeout: 15000, maxBuffer: 1024 * 1024 });
+  } catch (e) {
+    throw new Error(`写入后校验失败：${(e.stdout || e.message || '').toString().split('\n').filter(Boolean).slice(-3).join(' ')}`);
+  }
+}
+
+/** 解析补丁路径 → { parent, key }，路径走不通时把「走不通的那一段」报出来 */
+function resolvePath(doc, path) {
+  const segments = String(path ?? '').split('.').filter(Boolean);
+  if (!segments.length) throw new Error('补丁路径不能为空');
+  let node = doc;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const seg = segments[i];
+    if (Array.isArray(node)) {
+      if (/^\d+$/.test(seg)) {
+        if (Number(seg) >= node.length) throw new Error(`路径 ${path} 里的下标 ${seg} 越界`);
+        node = node[Number(seg)];
+        continue;
+      }
+      const hit = node.find(item => item && item.id === seg);
+      if (!hit) throw new Error(`路径 ${path} 里的 ${seg} 不存在`);
+      node = hit;
+      continue;
+    }
+    if (node && typeof node === 'object' && seg in node) {
+      node = node[seg];
+      continue;
+    }
+    throw new Error(`路径 ${path} 走不通：${seg} 之上没有这个字段`);
+  }
+  return { parent: node, key: segments[segments.length - 1] };
+}
+
+// ============================================================
+// 文本级补丁：带位置的 JSON 解析 + 只改动命中的那一段字符
+// ============================================================
+
+const WS = /[ \t\r\n]/;
+const PRIMITIVE_END = /[\s,\]}]/;
+
+/** 递归下降解析，给每个值记下它在原文里的字符区间（end 为后一位，左闭右开） */
+function parseTree(text) {
+  let i = 0;
+  const skip = () => {
+    while (i < text.length && WS.test(text[i])) i++;
+  };
+  function parseString() {
+    const start = i;
+    i += 1; // 起始引号
+    while (i < text.length) {
+      const ch = text[i];
+      if (ch === '\\') {
+        i += 2;
+        continue;
+      }
+      i += 1;
+      if (ch === '"') break;
+    }
+    return { type: 'string', start, end: i, value: JSON.parse(text.slice(start, i)) };
+  }
+  function parseObject() {
+    const start = i;
+    i += 1; // {
+    const entries = [];
+    skip();
+    if (text[i] === '}') {
+      i += 1;
+      return { type: 'object', start, end: i, entries };
+    }
+    while (true) {
+      skip();
+      const key = parseString();
+      skip();
+      if (text[i] !== ':') throw new Error('JSON 结构异常：对象里缺少冒号');
+      i += 1;
+      const value = parseValue();
+      entries.push({ key: key.value, keyStart: key.start, value });
+      skip();
+      if (text[i] === ',') {
+        i += 1;
+        continue;
+      }
+      if (text[i] === '}') {
+        i += 1;
+        break;
+      }
+      throw new Error('JSON 结构异常：对象没有闭合');
+    }
+    return { type: 'object', start, end: i, entries };
+  }
+  function parseArray() {
+    const start = i;
+    i += 1; // [
+    const items = [];
+    skip();
+    if (text[i] === ']') {
+      i += 1;
+      return { type: 'array', start, end: i, items };
+    }
+    while (true) {
+      items.push(parseValue());
+      skip();
+      if (text[i] === ',') {
+        i += 1;
+        continue;
+      }
+      if (text[i] === ']') {
+        i += 1;
+        break;
+      }
+      throw new Error('JSON 结构异常：数组没有闭合');
+    }
+    return { type: 'array', start, end: i, items };
+  }
+  function parseValue() {
+    skip();
+    const ch = text[i];
+    if (ch === '{') return parseObject();
+    if (ch === '[') return parseArray();
+    if (ch === '"') return parseString();
+    const start = i;
+    while (i < text.length && !PRIMITIVE_END.test(text[i])) i += 1;
+    return { type: 'literal', start, end: i, value: JSON.parse(text.slice(start, i)) };
+  }
+  return parseValue();
+}
+
+/** 按路径段找值节点：对象按字段名，数组按数字下标或记录 id */
+function nodeAt(root, segments) {
+  let node = root;
+  for (const seg of segments) {
+    if (!node) return null;
+    if (node.type === 'object') {
+      const entry = node.entries.find(e => e.key === seg);
+      node = entry ? entry.value : null;
+    } else if (node.type === 'array') {
+      if (/^\d+$/.test(seg)) {
+        node = node.items[Number(seg)] ?? null;
+      } else {
+        const hit = node.items.find(item => item.type === 'object'
+          && item.entries.some(e => e.key === 'id' && e.value.value === seg));
+        node = hit ?? null;
+      }
+    } else {
+      return null;
+    }
+  }
+  return node;
+}
+
+const isInline = (text, node) => !text.slice(node.start, node.end).includes('\n');
+
+/** 单行紧凑写法：{ "a": 1, "b": [1, 2] } —— 对齐「一条记录一行」的项目习惯 */
+function inlineRender(value) {
+  if (Array.isArray(value)) return `[${value.map(inlineRender).join(', ')}]`;
+  if (value && typeof value === 'object') {
+    const body = Object.entries(value).map(([k, v]) => `${JSON.stringify(k)}: ${inlineRender(v)}`);
+    return body.length ? `{ ${body.join(', ')} }` : '{}';
+  }
+  return JSON.stringify(value) ?? 'null';
+}
+
+function prettyRender(value, indent, unit) {
+  const body = JSON.stringify(value, null, unit);
+  if (!body.includes('\n')) return body;
+  return body.split('\n').map((line, idx) => (idx === 0 ? line : indent + line)).join('\n');
+}
+
+/** 某一行开头的空白：用值自己的起始位置反查该行缩进 */
+function lineIndentAt(text, pos) {
+  const lineStart = text.lastIndexOf('\n', pos - 1) + 1;
+  return text.slice(lineStart, pos).match(/^[ \t]*/)?.[0] ?? '';
+}
+
+/** 缩进单位：取文件里第一处缩进；取不到就 2 空格 */
+function indentUnit(text) {
+  return text.match(/\n([ \t]+)\S/)?.[1] ?? '  ';
+}
+
+const newlineOf = text => (text.includes('\r\n') ? '\r\n' : '\n');
+
+/** 让新内容跟原来的长相一致：原来一行就写一行，原来多行就按同缩进展开 */
+function renderValue(text, node, value) {
+  if (isInline(text, node)) return inlineRender(value);
+  return prettyRender(value, lineIndentAt(text, node.start), indentUnit(text));
+}
+
+/** 往对象里插一个新字段（原来没有这个 key），缩进与长相都照兄弟字段 */
+function insertMember(text, obj, key, value) {
+  const unit = indentUnit(text);
+  const nl = newlineOf(text);
+  const last = obj.entries[obj.entries.length - 1];
+  if (!last) {
+    if (!isInline(text, obj)) {
+      const indent = lineIndentAt(text, obj.start);
+      return `${text.slice(0, obj.start)}{${nl}${indent}${unit}"${key}": ${inlineRender(value)}${nl}${indent}}${text.slice(obj.end)}`;
+    }
+    return `${text.slice(0, obj.start)}{ "${key}": ${inlineRender(value)} }${text.slice(obj.end)}`;
+  }
+  const memberIndent = lineIndentAt(text, last.keyStart);
+  const member = isInline(text, last.value)
+    ? `"${key}": ${inlineRender(value)}`
+    : `"${key}": ${prettyRender(value, memberIndent, unit)}`;
+  const at = last.value.end;
+  return `${text.slice(0, at)},${nl}${memberIndent}${member}${text.slice(at)}`;
+}
+
+/** 往数组尾部追加一项，长相跟最后一项保持一致 */
+function insertItem(text, arr, value) {
+  const unit = indentUnit(text);
+  const nl = newlineOf(text);
+  const last = arr.items[arr.items.length - 1];
+  if (!last) {
+    if (!isInline(text, arr)) {
+      const indent = lineIndentAt(text, arr.start);
+      return `${text.slice(0, arr.start)}[${nl}${indent}${unit}${inlineRender(value)}${nl}${indent}]${text.slice(arr.end)}`;
+    }
+    return `${text.slice(0, arr.start)}[${inlineRender(value)}]${text.slice(arr.end)}`;
+  }
+  if (isInline(text, arr)) {
+    return `${text.slice(0, last.end)}, ${inlineRender(value)}${text.slice(last.end)}`;
+  }
+  const itemIndent = lineIndentAt(text, last.start);
+  const item = isInline(text, last) ? inlineRender(value) : prettyRender(value, itemIndent, unit);
+  return `${text.slice(0, last.end)},${nl}${itemIndent}${item}${text.slice(last.end)}`;
+}
+
+/** 删数组第 idx 项：连同它前面（或后面）那个逗号一起删 */
+function removeItem(text, arr, idx) {
+  const items = arr.items;
+  if (items.length === 1) return `${text.slice(0, arr.start)}[]${text.slice(arr.end)}`;
+  if (idx > 0) return text.slice(0, items[idx - 1].end) + text.slice(items[idx].end);
+  return text.slice(0, items[0].start) + text.slice(items[1].start);
+}
+
+/** 删对象里的一个字段：原则同 removeItem */
+function removeMember(text, obj, entry) {
+  const idx = obj.entries.indexOf(entry);
+  if (obj.entries.length === 1) return `${text.slice(0, obj.start)}{}${text.slice(obj.end)}`;
+  if (idx > 0) return text.slice(0, obj.entries[idx - 1].value.end) + text.slice(entry.value.end);
+  return text.slice(0, entry.keyStart) + text.slice(obj.entries[1].keyStart);
+}
+
+/**
+ * 把一条补丁打到原文上，返回新文本。
+ * 语义与 applyOne（改的是解析后的对象）一一对应，区别是这里只动命中的那几个字符。
+ */
+function patchText(text, patch) {
+  const op = patch?.op ?? 'set';
+  const segments = String(patch?.path ?? '').split('.').filter(Boolean);
+  if (!segments.length) throw new Error('补丁路径不能为空');
+  const root = parseTree(text);
+
+  if (op === 'push') {
+    const arr = nodeAt(root, segments);
+    if (!arr || arr.type !== 'array') throw new Error(`路径 ${patch.path} 不是数组，不能 push`);
+    return insertItem(text, arr, patch.value);
+  }
+
+  const parent = nodeAt(root, segments.slice(0, -1));
+  const key = segments[segments.length - 1];
+  if (!parent) throw new Error(`路径 ${patch.path} 走不通`);
+  const isIndex = /^\d+$/.test(key);
+
+  if (op === 'set') {
+    if (parent.type === 'object') {
+      const entry = parent.entries.find(e => e.key === key);
+      if (!entry) return insertMember(text, parent, key, patch.value);
+      return text.slice(0, entry.value.start) + renderValue(text, entry.value, patch.value) + text.slice(entry.value.end);
+    }
+    if (parent.type === 'array') {
+      const item = isIndex ? parent.items[Number(key)] : null;
+      if (!item) throw new Error(`路径 ${patch.path} 在数组里找不到 ${key} 这一项`);
+      return text.slice(0, item.start) + renderValue(text, item, patch.value) + text.slice(item.end);
+    }
+    throw new Error(`路径 ${patch.path} 的父级既不是对象也不是数组`);
+  }
+
+  if (op === 'remove') {
+    if (parent.type === 'array') {
+      const item = isIndex ? parent.items[Number(key)] : null;
+      if (!item) throw new Error(`路径 ${patch.path} 在数组里找不到 ${key} 这一项`);
+      return removeItem(text, parent, Number(key));
+    }
+    if (parent.type === 'object') {
+      const entry = parent.entries.find(e => e.key === key);
+      if (!entry) throw new Error(`路径 ${patch.path} 要删的字段不存在`);
+      return removeMember(text, parent, entry);
+    }
+    throw new Error(`路径 ${patch.path} 的父级既不是对象也不是数组`);
+  }
+
+  throw new Error(`不支持的补丁操作 ${op}（只认 set / push / remove）`);
+}
+
+/** 把三个文件拆成「一条记录一行」的可检索单元，路径直接就是补丁能用的写法 */
+function recordsOf(file, doc) {
+  const out = [];
+  const add = (path, item) => {
+    if (item && typeof item === 'object') out.push({ path, item });
+  };
+  if (file === 'backlog') {
+    (doc.epics ?? []).forEach(e => add(`epics.${e.id}`, e));
+    (doc.stories ?? []).forEach(s => {
+      add(`stories.${s.id}`, s);
+      (s.tasks ?? []).forEach(t => add(`stories.${s.id}.tasks.${t.id}`, t));
+    });
+  } else if (file === 'sprints') {
+    (doc.sprints ?? []).forEach(s => add(`sprints.${s.id}`, s));
+    (doc.milestones ?? []).forEach(m => add(`milestones.${m.id}`, m));
+  } else if (file === 'journal') {
+    (doc.journals ?? []).forEach(j => add(`journals.${j.taskId}`, j));
+  }
+  return out;
+}
+
+function applyOne(doc, patch) {
+  const op = patch?.op ?? 'set';
+  const { parent, key } = resolvePath(doc, patch?.path);
+  const readBefore = () => (Array.isArray(parent) && /^\d+$/.test(key) ? parent[Number(key)] : parent[key]);
+  if (op === 'set') {
+    const before = readBefore();
+    if (Array.isArray(parent) && /^\d+$/.test(key)) parent[Number(key)] = patch.value;
+    else parent[key] = patch.value;
+    return { op, path: patch.path, before, after: patch.value };
+  }
+  if (op === 'push') {
+    const arr = readBefore();
+    if (!Array.isArray(arr)) throw new Error(`路径 ${patch.path} 不是数组，不能 push`);
+    const before = arr.length;
+    arr.push(patch.value);
+    return { op, path: patch.path, before, after: arr.length };
+  }
+  if (op === 'remove') {
+    const before = readBefore();
+    if (Array.isArray(parent) && /^\d+$/.test(key)) parent.splice(Number(key), 1);
+    else if (Array.isArray(parent)) throw new Error(`路径 ${patch.path} 要按下标删除（数组里没有 ${key}）`);
+    else delete parent[key];
+    return { op, path: patch.path, before, after: undefined };
+  }
+  throw new Error(`不支持的补丁操作 ${op}（只认 set / push / remove）`);
+}
+
+/**
+ * root 可以是字符串，也可以是 () => string。
+ * 服务端要传函数：看板上换项目时「当前项目」会变，工具不能一直盯着启动时那个目录，
+ * 否则用户切到 B 项目、AI 却把补丁写进 A 项目。
+ */
+export function createAgileTools({ root, validate = runValidate } = {}) {
+  let seq = 0;
+  const pending = new Map();
+  const currentRoot = typeof root === 'function' ? root : () => root;
+
+  const fileOf = file => {
+    if (!AGILE_FILES.includes(file)) {
+      throw new Error(`只允许写 agile/ 下的三个文件（${AGILE_FILES.join(' / ')}.json），收到的是 ${file}`);
+    }
+    return join(currentRoot(), 'agile', `${file}.json`);
+  };
+  const read = file => JSON.parse(readFileSync(fileOf(file), 'utf8'));
+
+  /**
+   * 写盘 + 校验 + 失败回滚：任何一步出错，文件都必须是改前那份。
+   * 写回走文本补丁（patchText）：只替换命中的字符，排版 / 换行风格原样保留，
+   * 改一个状态就只差一行，不会把整份文件重排成合并冲突。
+   */
+  function persist(file, patches) {
+    const target = fileOf(file);
+    const previous = readFileSync(target, 'utf8');
+    let next = previous;
+    for (const patch of patches) next = patchText(next, patch);
+    writeFileSync(target, next);
+    try {
+      validate(currentRoot());
+    } catch (e) {
+      writeFileSync(target, previous);
+      throw new Error(`校验未通过，已把 ${file}.json 回滚成改前内容：${e.message}`);
+    }
+  }
+
+  function applyAll(file, patches) {
+    const doc = read(file); // 先过文件白名单：非法文件要越过「补丁为空」先报出来
+    if (!Array.isArray(patches) || patches.length === 0) throw new Error('补丁不能为空（要改什么得说清楚）');
+    return { doc, changes: patches.map(p => applyOne(doc, p)) };
+  }
+
+  return {
+    read,
+    /**
+     * 记录级检索：agile 的 JSON 是缩进排版，两个关键词很少落在同一行，
+     * 所以按「一条记录」为单位匹配（story / task / sprint / milestone / journal），
+     * 命中的 path 可以直接拿来写 update 补丁，省掉模型自己数下标。
+     */
+    search(query, { limit = 20, file } = {}) {
+      const terms = String(query ?? '').trim().toLowerCase().split(/\s+/).filter(Boolean);
+      if (!terms.length) throw new Error('检索关键词不能为空');
+      const files = file ? [file] : AGILE_FILES;
+      const hits = [];
+      let truncated = false;
+      for (const name of files) {
+        const abs = fileOf(name);
+        if (!existsSync(abs)) continue;
+        const raw = readFileSync(abs, 'utf8');
+        let doc;
+        try {
+          doc = JSON.parse(raw);
+        } catch {
+          continue; // 半截文件不参与检索，交给 validate 去报
+        }
+        const lines = raw.split(/\r?\n/);
+        for (const { path, item } of recordsOf(name, doc)) {
+          const text = JSON.stringify(item);
+          const lower = text.toLowerCase();
+          if (!terms.every(t => lower.includes(t))) continue;
+          if (hits.length >= limit) {
+            truncated = true;
+            continue;
+          }
+          const anchor = item.id ?? item.taskId;
+          const line = (anchor ? lines.findIndex(l => l.includes(`"${anchor}"`)) : -1) + 1 || 1;
+          hits.push({ file: `agile/${name}.json`, path, line, text: text.slice(0, 400) });
+        }
+      }
+      return { query: String(query), terms, count: hits.length, truncated, hits };
+    },
+
+    /** 直接落盘（自动审核策略走这条） */
+    patch({ file, patches, reason } = {}) {
+      const { changes } = applyAll(file, patches);
+      persist(file, patches);
+      return { ok: true, file, reason: reason ?? '', validated: true, changes };
+    },
+
+    /** 只出待审变更，不落盘（手动审核策略走这条） */
+    propose({ file, patches, reason } = {}) {
+      const { doc, changes } = applyAll(file, patches);
+      void doc;
+      const record = {
+        id: `p-${++seq}-${Math.random().toString(36).slice(2, 6)}`,
+        file,
+        reason: reason ?? '',
+        at: new Date().toISOString(),
+        patches,
+        changes,
+      };
+      pending.set(record.id, record);
+      return { ...record };
+    },
+
+    listPending() {
+      return [...pending.values()];
+    },
+
+    applyPending(id) {
+      const record = pending.get(id);
+      if (!record) throw new Error(`待审变更 ${id} 不存在或已处理`);
+      pending.delete(id);
+      try {
+        return { ...this.patch({ file: record.file, patches: record.patches, reason: record.reason }), id };
+      } catch (e) {
+        pending.set(id, record);
+        throw e;
+      }
+    },
+
+    rejectPending(id) {
+      if (!pending.has(id)) throw new Error(`待审变更 ${id} 不存在或已处理`);
+      pending.delete(id);
+      return { ok: true, id };
+    },
+  };
+}