scrum-skills 0.3.2 → 0.3.3

package/tools/projects.mjs

@@ -1,215 +1,240 @@
-import { readFileSync, writeFileSync, mkdirSync, realpathSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import { homedir } from 'node:os';
-import { execFile, execFileSync } from 'node:child_process';
-import { promisify } from 'node:util';
-import { randomBytes } from 'node:crypto';
-import { fileURLToPath } from 'node:url';
-import { createAgileTools } from './agile-tools.mjs';
-import { checkLastChange, listLastChangeHistory, readLastChangeAt } from './last-change.mjs';
-import { commitAll, commitPreview } from './git-commit.mjs';
-
-const exec = promisify(execFile);
-const validator = fileURLToPath(new URL('./validate.mjs', import.meta.url));
-const defaultStore = join(process.env.APPDATA || join(homedir(), '.config'), 'scrum-skills', 'projects.json');
-
-export async function pickDirectory() {
-  let command, args;
-  if (process.platform === 'win32') {
-    command = 'powershell.exe';
-    const script = `
-[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new()
-Add-Type -TypeDefinition @'
-using System;
-using System.Runtime.InteropServices;
-public static class FolderPickerDpi {
-  [DllImport("user32.dll")] private static extern IntPtr SetThreadDpiAwarenessContext(IntPtr context);
-  [DllImport("user32.dll")] private static extern bool SetProcessDPIAware();
-  public static void Enable() {
-    try {
-      if (SetThreadDpiAwarenessContext(new IntPtr(-4)) != IntPtr.Zero) return;
-      if (SetThreadDpiAwarenessContext(new IntPtr(-3)) != IntPtr.Zero) return;
-    } catch (EntryPointNotFoundException) {}
-    SetProcessDPIAware();
-  }
-}
-'@
-[FolderPickerDpi]::Enable()
-Add-Type -AssemblyName System.Windows.Forms
-[System.Windows.Forms.Application]::EnableVisualStyles()
-$d = New-Object System.Windows.Forms.FolderBrowserDialog
-$d.Description = '选择包含 agile 文件夹的项目根目录'
-$d.ShowNewFolderButton = $false
-try {
-  if ($d.ShowDialog() -eq 'OK') { [Console]::Write($d.SelectedPath) }
-} finally { $d.Dispose() }
-`;
-    args = ['-NoProfile', '-STA', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')];
-  } else if (process.platform === 'darwin') {
-    command = 'osascript';
-    args = ['-e', 'try', '-e', 'POSIX path of (choose folder with prompt "选择包含 agile 的项目根目录")', '-e', 'on error number -128', '-e', 'return ""', '-e', 'end try'];
-  } else {
-    command = 'zenity';
-    args = ['--file-selection', '--directory', '--title=选择包含 agile 的项目根目录'];
-  }
-  try {
-    const { stdout } = await exec(command, args, { encoding: 'utf8', timeout: 300000, maxBuffer: 65536 });
-    return stdout.trim() || null;
-  } catch (e) {
-    if (process.platform === 'linux' && e.code === 1) return null;
-    throw new Error('无法打开系统目录选择框，请确认本机有图形桌面（Linux 需安装 zenity）。');
-  }
-}
-
-/**
- * 故事状态单向车道。看板卡片的「下一步 / 退回」就按这条线走，
- * done 是终点、cancelled 是另一条终点，两者都不许再动。
- */
-export const STORY_FLOW = ['draft', 'ready', 'in-progress', 'review', 'done'];
-
-const ACTION_LABEL = { next: '推进到下一状态', prev: '退回上一状态', cancel: '标记为已取消' };
-
-/** 按动作算出目标状态；算不出来（已是终点 / 动作不认识）返回 null */
-export function statusAfter(from, action) {
-  if (action === 'cancel') return ['draft', 'ready', 'in-progress', 'review'].includes(from) ? 'cancelled' : null;
-  if (!STORY_FLOW.includes(from)) return null;
-  const i = STORY_FLOW.indexOf(from);
-  if (action === 'next') return STORY_FLOW[i + 1] ?? null;
-  if (action === 'prev') return STORY_FLOW[i - 1] ?? null;
-  return null;
-}
-
-function snapshot(root) {
-  const read = file => JSON.parse(readFileSync(join(root, 'agile', file + '.json'), 'utf8'));
-  // last-change.json 可选：还没交付过东西就没有它，看板按 null 显示空状态。
-  // 这里吞掉解析异常，坏文件交给 validate 报，别让整个 /api/agile 挂掉。
-  let lastChange = null;
-  try {
-    lastChange = read('last-change');
-  } catch {}
-  // tests.json 同样可选：没登记用例的项目就是空数组，页面给空状态。
-  // 坏文件交给 validate 报，这里吞掉异常，别让整个 /api/agile 挂掉。
-  let tests = null;
-  try {
-    tests = read('tests');
-  } catch {}
-  // 页面开头要说明「已提交才覆盖、未提交要合并」，所以状态跟着快照一起给出去
-  const { state, advice, hash, date, subject } = checkLastChange(root);
-  return {
-    backlog: read('backlog'), sprints: read('sprints'), journal: read('journal'), lastChange, tests,
-    meta: { root, servedAt: new Date().toISOString(), lastChangeGit: { state, advice, hash, date, subject } },
-  };
-}
-
-function validate(root) {
-  try {
-    execFileSync(process.execPath, [validator, root], { encoding: 'utf8', timeout: 15000, maxBuffer: 1024 * 1024 });
-  } catch (e) {
-    throw new Error(`项目敏捷数据校验失败：${e.stdout || e.message}`);
-  }
-}
-
-export function createProjects({ root, store = defaultStore, pick = pickDirectory }) {
-  const token = randomBytes(24).toString('hex');
-  let recent = [];
-  try {
-    const saved = JSON.parse(readFileSync(store, 'utf8'));
-    if (Array.isArray(saved.recent)) recent = saved.recent.filter(x => typeof x === 'string').slice(0, 10);
-  } catch {}
-  // 启动目录优先：从哪个目录起服务，看板就打开哪个目录。
-  // 最近列表只是「切回上次那个项目」的入口，不许顶替启动目录——
-  // 否则在 A 项目里 serve，会悄悄打开上一次的 B 项目数据（JSON 看着像是 A 的，其实全错）。
-  const initial = realpathSync(root);
-  let current = initial;
-  recent = [...new Set([current, ...recent])].slice(0, 10);
-  let selecting = false;
-  const list = () => ({ recent: [...recent], root: current, token });
-  const read = (path = current) => {
-    if (!recent.includes(path)) throw new Error('该项目未打开，请先选择文件夹。');
-    return snapshot(path);
-  };
-  const open = async path => {
-    const canonical = realpathSync(path);
-    validate(canonical);
-    const data = snapshot(canonical);
-    const next = [canonical, ...recent.filter(x => x !== canonical)].slice(0, 10);
-    mkdirSync(dirname(store), { recursive: true });
-    writeFileSync(store, JSON.stringify({ recent: next }, null, 2) + '\n', { mode: 0o600 });
-    recent = next;
-    current = canonical;
-    return { ...list(), data };
-  };
-  const select = async () => {
-    if (selecting) throw new Error('目录选择框已打开，请先完成选择。');
-    selecting = true;
-    try {
-      const selected = await pick();
-      return selected ? await open(selected) : null;
-    } finally { selecting = false; }
-  };
-  // 写盘复用 AI 助手那套「文本补丁 + 写后校验 + 失败回滚」，
-  // 不另写一份：改一个状态只差一行字符，校验不过自动还原。
-  const tools = createAgileTools({ root: () => current });
-  const setStoryStatus = ({ id, action } = {}) => {
-    if (!id) throw new Error('缺少故事 id');
-    const { backlog } = snapshot(current);
-    const story = (backlog.stories ?? []).find(s => s.id === id);
-    if (!story) throw new Error(`找不到故事 ${id}`);
-    const from = story.status;
-    const to = statusAfter(from, action);
-    if (!to) throw new Error(`${id} 当前是 ${from}，没法${ACTION_LABEL[action] ?? `执行 ${action}`}`);
-    const patches = [{ path: `stories.${id}.status`, value: to }];
-    // 取消一条还被阻塞的故事：阻塞标记要一起摘掉。
-    // 校验器不许「已取消却还标着 blocked」，不摘会整条改动作废。
-    if (to === 'cancelled' && story.blocked) patches.push({ op: 'remove', path: `stories.${id}.blocked` });
-    tools.patch({ file: 'backlog', patches, reason: `看板卡片操作：${from} → ${to}` });
-    return { id, from, to };
-  };
-  /**
-   * 「自动提交」：提交信息由看板按交付记录生成后整份带上来，这里只负责执行。
-   * 生成器只有一份（apps/board/app/utils/commit-message.js）——复制按钮与自动提交用的是同一段文本，
-   * 不会出现「复制的和提交的不一样」。tools/ 不 import 看板源码，发布包里也就不用带 apps/。
-   */
-  const commit = ({ message } = {}) => commitAll(current, message);
-  return { list, read, open, select, setStoryStatus, commit };
-}
-
-export async function handleProjectApi(projects, { method, path, headers, body }) {
-  const host = headers.host || '';
-  const denied = () => ({ status: 403, body: { error: '仅允许本机同来源访问。' } });
-  if (!/^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/.test(host)) return denied();
-  if (headers.origin && headers.origin !== `http://${host}`) return denied();
-  if (headers['sec-fetch-site'] === 'cross-site') return denied();
-  const url = new URL(path, `http://${host}`);
-  try {
-    if (method === 'GET' && url.pathname === '/api/projects') return { status: 200, body: projects.list() };
-    if (method === 'GET' && url.pathname === '/api/agile') return { status: 200, body: projects.read(url.searchParams.get('root') || undefined) };
-    // 交付说明的历史版本：只读，直接从 git 里取（不写文件，所以不需要 token）
-    if (method === 'GET' && url.pathname === '/api/agile/last-change/history') {
-      return { status: 200, body: listLastChangeHistory(projects.list().root) };
-    }
-    if (method === 'GET' && url.pathname === '/api/agile/last-change/revision') {
-      return { status: 200, body: readLastChangeAt(projects.list().root, url.searchParams.get('hash')) };
-    }
-    // 自动提交前的预览（能不能提交、会带走哪些文件）：只读，同样不要 token
-    if (method === 'GET' && url.pathname === '/api/agile/git/status') {
-      return { status: 200, body: commitPreview(projects.list().root) };
-    }
-    if (method !== 'POST') return { status: 405, body: { error: '不支持的请求方法。' } };
-    if (headers['x-project-token'] !== projects.list().token) return denied();
-    // 看板卡片的退回 / 下一步 / 取消：改的是当前打开项目的 backlog.json
-    if (url.pathname === '/api/agile/story-status') {
-      return { status: 200, body: projects.setStoryStatus({ id: body?.id, action: body?.action }) };
-    }
-    // 自动提交：真跑 git add -A + git commit（不 push）
-    if (url.pathname === '/api/agile/git/commit') {
-      return { status: 200, body: projects.commit({ message: body?.message }) };
-    }
-    if (url.pathname === '/api/projects/select') return { status: 200, body: await projects.select() };
-    if (url.pathname === '/api/projects/open') {
-      if (!projects.list().recent.includes(body?.root)) throw new Error('该项目不在最近列表中，请选择文件夹。');
-      return { status: 200, body: await projects.open(body.root) };
-    }
-    return { status: 404, body: { error: '接口不存在。' } };
-  } catch (e) { return { status: 400, body: { error: String(e.message) } }; }
-}
+import { readFileSync, writeFileSync, mkdirSync, realpathSync, existsSync } from 'node:fs';
+import { join, dirname, resolve, sep } from 'node:path';
+import { homedir } from 'node:os';
+import { execFile, execFileSync } from 'node:child_process';
+import { promisify } from 'node:util';
+import { randomBytes } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { createAgileTools } from './agile-tools.mjs';
+import { checkLastChange, listLastChangeHistory, readLastChangeAt } from './last-change.mjs';
+import { commitAll, commitPreview } from './git-commit.mjs';
+
+const exec = promisify(execFile);
+const validator = fileURLToPath(new URL('./validate.mjs', import.meta.url));
+const defaultStore = join(process.env.APPDATA || join(homedir(), '.config'), 'scrum-skills', 'projects.json');
+
+export async function pickDirectory() {
+  let command, args;
+  if (process.platform === 'win32') {
+    command = 'powershell.exe';
+    const script = `
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new()
+Add-Type -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
+public static class FolderPickerDpi {
+  [DllImport("user32.dll")] private static extern IntPtr SetThreadDpiAwarenessContext(IntPtr context);
+  [DllImport("user32.dll")] private static extern bool SetProcessDPIAware();
+  public static void Enable() {
+    try {
+      if (SetThreadDpiAwarenessContext(new IntPtr(-4)) != IntPtr.Zero) return;
+      if (SetThreadDpiAwarenessContext(new IntPtr(-3)) != IntPtr.Zero) return;
+    } catch (EntryPointNotFoundException) {}
+    SetProcessDPIAware();
+  }
+}
+'@
+[FolderPickerDpi]::Enable()
+Add-Type -AssemblyName System.Windows.Forms
+[System.Windows.Forms.Application]::EnableVisualStyles()
+$d = New-Object System.Windows.Forms.FolderBrowserDialog
+$d.Description = '选择包含 agile 文件夹的项目根目录'
+$d.ShowNewFolderButton = $false
+try {
+  if ($d.ShowDialog() -eq 'OK') { [Console]::Write($d.SelectedPath) }
+} finally { $d.Dispose() }
+`;
+    args = ['-NoProfile', '-STA', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')];
+  } else if (process.platform === 'darwin') {
+    command = 'osascript';
+    args = ['-e', 'try', '-e', 'POSIX path of (choose folder with prompt "选择包含 agile 的项目根目录")', '-e', 'on error number -128', '-e', 'return ""', '-e', 'end try'];
+  } else {
+    command = 'zenity';
+    args = ['--file-selection', '--directory', '--title=选择包含 agile 的项目根目录'];
+  }
+  try {
+    const { stdout } = await exec(command, args, { encoding: 'utf8', timeout: 300000, maxBuffer: 65536 });
+    return stdout.trim() || null;
+  } catch (e) {
+    if (process.platform === 'linux' && e.code === 1) return null;
+    throw new Error('无法打开系统目录选择框，请确认本机有图形桌面（Linux 需安装 zenity）。');
+  }
+}
+
+/**
+ * 故事状态单向车道。看板卡片的「下一步 / 退回」就按这条线走，
+ * done 是终点、cancelled 是另一条终点，两者都不许再动。
+ */
+export const STORY_FLOW = ['draft', 'ready', 'in-progress', 'review', 'done'];
+
+const ACTION_LABEL = { next: '推进到下一状态', prev: '退回上一状态', cancel: '标记为已取消' };
+
+/** 按动作算出目标状态；算不出来（已是终点 / 动作不认识）返回 null */
+export function statusAfter(from, action) {
+  if (action === 'cancel') return ['draft', 'ready', 'in-progress', 'review'].includes(from) ? 'cancelled' : null;
+  if (!STORY_FLOW.includes(from)) return null;
+  const i = STORY_FLOW.indexOf(from);
+  if (action === 'next') return STORY_FLOW[i + 1] ?? null;
+  if (action === 'prev') return STORY_FLOW[i - 1] ?? null;
+  return null;
+}
+
+function snapshot(root) {
+  const read = file => JSON.parse(readFileSync(join(root, 'agile', file + '.json'), 'utf8'));
+  // last-change.json 可选：还没交付过东西就没有它，看板按 null 显示空状态。
+  // 这里吞掉解析异常，坏文件交给 validate 报，别让整个 /api/agile 挂掉。
+  let lastChange = null;
+  try {
+    lastChange = read('last-change');
+  } catch {}
+  // tests.json 同样可选：没登记用例的项目就是空数组，页面给空状态。
+  // 坏文件交给 validate 报，这里吞掉异常，别让整个 /api/agile 挂掉。
+  let tests = null;
+  try {
+    tests = read('tests');
+  } catch {}
+  // diagrams.json 同样可选：没登记图例的项目就是空数组，/diagrams 页给空状态
+  let diagrams = null;
+  try {
+    diagrams = read('diagrams');
+  } catch {}
+  // 页面开头要说明「已提交才覆盖、未提交要合并」，所以状态跟着快照一起给出去
+  const { state, advice, hash, date, subject } = checkLastChange(root);
+  return {
+    backlog: read('backlog'), sprints: read('sprints'), journal: read('journal'), lastChange, tests, diagrams,
+    meta: { root, servedAt: new Date().toISOString(), lastChangeGit: { state, advice, hash, date, subject } },
+  };
+}
+
+function validate(root) {
+  try {
+    execFileSync(process.execPath, [validator, root], { encoding: 'utf8', timeout: 15000, maxBuffer: 1024 * 1024 });
+  } catch (e) {
+    throw new Error(`项目敏捷数据校验失败：${e.stdout || e.message}`);
+  }
+}
+
+export function createProjects({ root, store = defaultStore, pick = pickDirectory }) {
+  const token = randomBytes(24).toString('hex');
+  let recent = [];
+  try {
+    const saved = JSON.parse(readFileSync(store, 'utf8'));
+    if (Array.isArray(saved.recent)) recent = saved.recent.filter(x => typeof x === 'string').slice(0, 10);
+  } catch {}
+  // 启动目录优先：从哪个目录起服务，看板就打开哪个目录。
+  // 最近列表只是「切回上次那个项目」的入口，不许顶替启动目录——
+  // 否则在 A 项目里 serve，会悄悄打开上一次的 B 项目数据（JSON 看着像是 A 的，其实全错）。
+  const initial = realpathSync(root);
+  let current = initial;
+  recent = [...new Set([current, ...recent])].slice(0, 10);
+  let selecting = false;
+  const list = () => ({ recent: [...recent], root: current, token });
+  const read = (path = current) => {
+    if (!recent.includes(path)) throw new Error('该项目未打开，请先选择文件夹。');
+    return snapshot(path);
+  };
+  const open = async path => {
+    const canonical = realpathSync(path);
+    validate(canonical);
+    const data = snapshot(canonical);
+    const next = [canonical, ...recent.filter(x => x !== canonical)].slice(0, 10);
+    mkdirSync(dirname(store), { recursive: true });
+    writeFileSync(store, JSON.stringify({ recent: next }, null, 2) + '\n', { mode: 0o600 });
+    recent = next;
+    current = canonical;
+    return { ...list(), data };
+  };
+  const select = async () => {
+    if (selecting) throw new Error('目录选择框已打开，请先完成选择。');
+    selecting = true;
+    try {
+      const selected = await pick();
+      return selected ? await open(selected) : null;
+    } finally { selecting = false; }
+  };
+  // 写盘复用 AI 助手那套「文本补丁 + 写后校验 + 失败回滚」，
+  // 不另写一份：改一个状态只差一行字符，校验不过自动还原。
+  const tools = createAgileTools({ root: () => current });
+  const setStoryStatus = ({ id, action } = {}) => {
+    if (!id) throw new Error('缺少故事 id');
+    const { backlog } = snapshot(current);
+    const story = (backlog.stories ?? []).find(s => s.id === id);
+    if (!story) throw new Error(`找不到故事 ${id}`);
+    const from = story.status;
+    const to = statusAfter(from, action);
+    if (!to) throw new Error(`${id} 当前是 ${from}，没法${ACTION_LABEL[action] ?? `执行 ${action}`}`);
+    const patches = [{ path: `stories.${id}.status`, value: to }];
+    // 取消一条还被阻塞的故事：阻塞标记要一起摘掉。
+    // 校验器不许「已取消却还标着 blocked」，不摘会整条改动作废。
+    if (to === 'cancelled' && story.blocked) patches.push({ op: 'remove', path: `stories.${id}.blocked` });
+    tools.patch({ file: 'backlog', patches, reason: `看板卡片操作：${from} → ${to}` });
+    return { id, from, to };
+  };
+  /**
+   * 「自动提交」：提交信息由看板按交付记录生成后整份带上来，这里只负责执行。
+   * 生成器只有一份（apps/board/app/utils/commit-message.js）——复制按钮与自动提交用的是同一段文本，
+   * 不会出现「复制的和提交的不一样」。tools/ 不 import 看板源码，发布包里也就不用带 apps/。
+   */
+  const commit = ({ message } = {}) => commitAll(current, message);
+  /**
+   * 图例产物（自包含 HTML / SVG）。**只认 id，不认路径**：
+   * 路径一律从索引里取，客户端传什么都不会穿越目录；即便索引被手改成 `../../etc/passwd`，
+   * 这里还会再核一次「必须在 agile/ 下」。
+   */
+  const readDiagram = (id, format = 'html') => {
+    if (!id) throw new Error('缺少图例 id');
+    const d = (snapshot(current).diagrams?.diagrams ?? []).find(x => x.id === id);
+    if (!d) throw new Error(`没有图例 ${id}（先用 node tools/diagram.mjs add 登记）`);
+    const rel = format === 'svg' && d.svg ? d.svg : d.file;
+    if (!rel) throw new Error(`图例 ${id} 没有产物路径`);
+    const abs = resolve(current, rel);
+    const base = join(current, 'agile');
+    if (abs !== base && !abs.startsWith(base + sep)) throw new Error(`图例 ${id} 的产物必须在 agile/ 下：${rel}`);
+    if (!existsSync(abs)) throw new Error(`图例 ${id} 的产物不存在：${rel}`);
+    return {
+      contentType: /\.svg$/i.test(abs) ? 'image/svg+xml; charset=utf-8' : 'text/html; charset=utf-8',
+      text: readFileSync(abs, 'utf8'),
+    };
+  };
+  return { list, read, open, select, setStoryStatus, commit, readDiagram };
+}
+
+export async function handleProjectApi(projects, { method, path, headers, body }) {
+  const host = headers.host || '';
+  const denied = () => ({ status: 403, body: { error: '仅允许本机同来源访问。' } });
+  if (!/^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/.test(host)) return denied();
+  if (headers.origin && headers.origin !== `http://${host}`) return denied();
+  if (headers['sec-fetch-site'] === 'cross-site') return denied();
+  const url = new URL(path, `http://${host}`);
+  try {
+    if (method === 'GET' && url.pathname === '/api/projects') return { status: 200, body: projects.list() };
+    if (method === 'GET' && url.pathname === '/api/agile') return { status: 200, body: projects.read(url.searchParams.get('root') || undefined) };
+    // 交付说明的历史版本：只读，直接从 git 里取（不写文件，所以不需要 token）
+    if (method === 'GET' && url.pathname === '/api/agile/last-change/history') {
+      return { status: 200, body: listLastChangeHistory(projects.list().root) };
+    }
+    if (method === 'GET' && url.pathname === '/api/agile/last-change/revision') {
+      return { status: 200, body: readLastChangeAt(projects.list().root, url.searchParams.get('hash')) };
+    }
+    // 自动提交前的预览（能不能提交、会带走哪些文件）：只读，同样不要 token
+    if (method === 'GET' && url.pathname === '/api/agile/git/status') {
+      return { status: 200, body: commitPreview(projects.list().root) };
+    }
+    if (method !== 'POST') return { status: 405, body: { error: '不支持的请求方法。' } };
+    if (headers['x-project-token'] !== projects.list().token) return denied();
+    // 看板卡片的退回 / 下一步 / 取消：改的是当前打开项目的 backlog.json
+    if (url.pathname === '/api/agile/story-status') {
+      return { status: 200, body: projects.setStoryStatus({ id: body?.id, action: body?.action }) };
+    }
+    // 自动提交：真跑 git add -A + git commit（不 push）
+    if (url.pathname === '/api/agile/git/commit') {
+      return { status: 200, body: projects.commit({ message: body?.message }) };
+    }
+    if (url.pathname === '/api/projects/select') return { status: 200, body: await projects.select() };
+    if (url.pathname === '/api/projects/open') {
+      if (!projects.list().recent.includes(body?.root)) throw new Error('该项目不在最近列表中，请选择文件夹。');
+      return { status: 200, body: await projects.open(body.root) };
+    }
+    return { status: 404, body: { error: '接口不存在。' } };
+  } catch (e) { return { status: 400, body: { error: String(e.message) } }; }
+}