@sleep2agi/commhub-server 0.9.0-preview.13 → 0.9.0-preview.130

package/src/requirement-tags.ts

@@ -0,0 +1,89 @@
+/** Small, network-local labels; count Unicode code points rather than UTF-16 units. */
+export function normalizeTags(value: unknown): string[] | null {
+  if (!Array.isArray(value) || value.length > 10) return null;
+  const tags: string[] = [];
+  for (const valueTag of value) {
+    if (typeof valueTag !== "string") return null;
+    const tag = valueTag.trim();
+    if (!tag || [...tag].length > 20 || /[\u0000-\u001f\u007f]/u.test(tag)) return null;
+    if (!tags.includes(tag)) tags.push(tag);
+  }
+  return tags;
+}
+
+export function storedTags(value: string | null): string[] {
+  try { return normalizeTags(JSON.parse(value || "[]")) ?? []; } catch { return []; }
+}
+
+// ── 标签管理(改名 / 合并 / 删除 / 颜色) ──
+// 标签只是卡片 tags 数组里的字符串,没有自己的表;批量操作 = 把网络里每张带这个标签的卡的数组改写一遍。
+// 颜色是可选的,单独存在 network_tags(network_id, name, color);没行 = 客户端用默认灰。
+export const MAX_MERGE_SOURCES = 50;
+export type TagOp =
+  | { op: "rename"; from: string; to: string }
+  | { op: "merge"; from: string[]; to: string }
+  | { op: "delete"; tag: string }
+  | { op: "color"; tag: string; color: string | null };
+
+/** 单个标签名,规则同 normalizeTags。不合法 = null。 */
+export function tagName(value: unknown): string | null {
+  const tags = normalizeTags([value]);
+  return tags && tags.length === 1 ? tags[0] : null;
+}
+
+const TAG_COLOR = /^#[0-9a-fA-F]{6}$/;
+/** 请求体 → 操作;不合法返回错误码。 */
+export function parseTagOp(body: Record<string, unknown>): TagOp | { error: string } {
+  switch (body.op) {
+    case "rename": {
+      const from = tagName(body.from), to = tagName(body.to);
+      if (!from || !to) return { error: "invalid_tag" };
+      if (from === to) return { error: "same_tag" };
+      return { op: "rename", from, to };
+    }
+    case "merge": {
+      if (!Array.isArray(body.from) || body.from.length === 0 || body.from.length > MAX_MERGE_SOURCES) return { error: "invalid_tag" };
+      const from: string[] = [];
+      for (const value of body.from) {
+        const tag = tagName(value);
+        if (!tag) return { error: "invalid_tag" };
+        if (!from.includes(tag)) from.push(tag);
+      }
+      const to = tagName(body.to);
+      if (!to) return { error: "invalid_tag" };
+      // 目标自己出现在来源里不算来源(合并进自己 = 什么都不做)。
+      const sources = from.filter(tag => tag !== to);
+      if (!sources.length) return { error: "same_tag" };
+      return { op: "merge", from: sources, to };
+    }
+    case "delete": {
+      const tag = tagName(body.tag);
+      return tag ? { op: "delete", tag } : { error: "invalid_tag" };
+    }
+    case "color": {
+      const tag = tagName(body.tag);
+      if (!tag) return { error: "invalid_tag" };
+      if (body.color !== null && (typeof body.color !== "string" || !TAG_COLOR.test(body.color))) return { error: "invalid_tag_color" };
+      return { op: "color", tag, color: body.color === null ? null : (body.color as string).toLowerCase() };
+    }
+    default:
+      return { error: "invalid_tag_op" };
+  }
+}
+
+/** 这张卡的标签被这个操作改写后的样子;没变返回 null。顺序保留(新名字占第一个来源的位置),去重。 */
+export function applyTagOp(tags: string[], op: TagOp): string[] | null {
+  let sources: string[];
+  let to: string | null;
+  if (op.op === "rename") { sources = [op.from]; to = op.to; }
+  else if (op.op === "merge") { sources = op.from; to = op.to; }
+  else if (op.op === "delete") { sources = [op.tag]; to = null; }
+  else return null;
+  if (!tags.some(tag => sources.includes(tag))) return null;
+  const next: string[] = [];
+  for (const tag of tags) {
+    const mapped = sources.includes(tag) ? to : tag;
+    if (mapped !== null && !next.includes(mapped)) next.push(mapped);
+  }
+  return next;
+}

package/src/requirements-abandoned-http.test.ts

@@ -0,0 +1,236 @@
+// 任务状态「废弃」(abandoned)—— HTTP 集成测试(真实 Bun.serve,私有端口,临时库)。
+// test2123 在真实 PostgreSQL 上原样再跑一遍(COMMHUB_TEST_PG_URL)。
+//
+// 废弃是关闭态(同 done):不算开着、不逾期、不发到期提醒、不记完成时间;改进 / 改出都记动态;能改回 pool / doing。
+// 旧 App(desktop ≤ 0.2.220)把不认识的状态当 pool —— 所以没声明 `X-Anet-Accept-Columns: abandoned`
+// (或 `accept_columns=abandoned`)的调用者看到的是 done;MCP 总是声明,看到真值。
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-req-abandoned-"));
+process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+process.env.HOST = "127.0.0.1";
+for (const k of ["COMMHUB_DUE_REMINDER_TZ", "COMMHUB_DUE_OVERDUE_MAX_DAYS", "COMMHUB_DUE_REMINDER_NETWORKS", "COMMHUB_DUE_REMINDERS", "COMMHUB_DUE_REMINDERS_NETWORKS", "COMMHUB_DUE_REMINDERS_EXCLUDE_NETWORKS", "COMMHUB_DUE_REMINDERS_OWNERS"]) delete process.env[k];
+const PW = "AbandonedPassw0rd!x";
+const T0 = Date.UTC(2026, 9, 10, 2, 0, 0);
+const DAY = 86_400_000;
+const AWARE = { "X-Anet-Accept-Columns": "abandoned" };
+
+let BASE = "";
+let hub: any = null;
+let NET = "";
+let TOKEN = "";
+let OWNER = "";
+let db: any;
+let due: typeof import("./requirement-due-reminders.js");
+
+type R = { status: number; body: any };
+async function send(method: string, path: string, payload?: unknown, headers: Record<string, string> = {}): Promise<R> {
+  const res = await fetch(`${BASE}${path}`, {
+    method,
+    headers: { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json", ...headers },
+    body: payload === undefined ? undefined : JSON.stringify(payload),
+  }, 60_000);
+  const text = await res.text();
+  let body: any = null;
+  try { body = JSON.parse(text); } catch {}
+  return { status: res.status, body };
+}
+async function mcp(name: string, args: Record<string, unknown>): Promise<any> {
+  const res = await fetch(`${BASE}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
+  }, 60_000);
+  const raw = await res.text();
+  const lines = raw.split("\n").filter(x => x.startsWith("data:"));
+  const payload = lines.length ? JSON.parse(lines.at(-1)!.slice(5).trim()) : JSON.parse(raw);
+  return JSON.parse(payload.result.content[0].text);
+}
+async function card(name: string, extra: Record<string, unknown> = {}): Promise<string> {
+  const r = await send("POST", "/api/requirements", { network_id: NET, name, owner: { kind: "user", id: OWNER }, ...extra });
+  expect(r.status).toBe(201);
+  return r.body.requirement.id as string;
+}
+const get = (id: string, headers: Record<string, string> = {}) => send("GET", `/api/requirements/${id}?network_id=${NET}`, undefined, headers);
+const patch = (id: string, body: Record<string, unknown>, headers: Record<string, string> = {}) => send("PATCH", `/api/requirements/${id}?network_id=${NET}`, body, headers);
+const list = (qs = "", headers: Record<string, string> = {}) => send("GET", `/api/requirements?network_id=${NET}${qs}`, undefined, headers);
+const ids = (r: R) => (r.body.requirements as any[]).map(x => x.id);
+const columnIn = (r: R, id: string) => (r.body.requirements as any[]).find(x => x.id === id)?.column;
+const sentFor = (out: Array<{ requirement_id: string; kind: string }>, id: string) => out.filter(x => x.requirement_id === id).map(x => x.kind);
+const columnEvents = async (id: string) => ((await send("GET", `/api/requirements/events?network_id=${NET}&requirement_id=${id}`, undefined, AWARE)).body.events as any[])
+  .filter(e => e.kind === "changed" && e.field === "column").map(e => [e.old, e.new]).reverse();
+
+beforeAll(async () => {
+  ({ db } = await import("./db.js"));
+  const { register } = await import("./auth.js");
+  const r = register(`ab_owner_${Date.now()}`, PW);
+  expect(r.ok).toBe(true);
+  TOKEN = r.token!;
+  OWNER = r.user!.user_id;
+  NET = r.network_id!;
+  due = await import("./requirement-due-reminders.js");
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+  due.runDueReminders({ now: T0 - 30 * DAY }); // 到期提醒基线(同 requirement-due-reminders-http.test.ts)
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("abandoned column", () => {
+  test("schema accepts abandoned; the legacy CHECK migration is idempotent (SQLite rebuild / PG constraint swap)", async () => {
+    const { migrateRequirementColumnCheck } = await import("./requirements-migrate.js");
+    if (db.dialect === "postgres") {
+      // 模拟旧 PG 库:换回旧约束,迁移后 abandoned 能写,再跑一次照样不报错。
+      db.exec("ALTER TABLE requirements DROP CONSTRAINT IF EXISTS requirements_column_name_check");
+      db.exec("ALTER TABLE requirements ADD CONSTRAINT requirements_column_name_check CHECK(column_name IN ('pool', 'doing', 'done'))");
+      expect(migrateRequirementColumnCheck(db).rebuilt).toBe(true);
+      // 已经认识 abandoned:不再动表(不是每次启动都删了重加)
+      expect(migrateRequirementColumnCheck(db).rebuilt).toBe(false);
+      // 加约束失败要响亮地失败,而且是一条语句:旧约束原样留着,不会落到「没约束」
+      db.exec("ALTER TABLE requirements DROP CONSTRAINT IF EXISTS requirements_column_name_check");
+      db.exec("ALTER TABLE requirements ADD CONSTRAINT requirements_column_name_check CHECK(column_name IN ('pool', 'doing', 'done', 'bogus'))");
+      db.run("INSERT INTO requirements (requirement_id, network_id, title, column_name) VALUES ('req_ab_bogus', ?1, 'bogus', 'bogus')", [NET]);
+      expect(() => migrateRequirementColumnCheck(db)).toThrow();
+      const def = (db.get("SELECT pg_get_constraintdef(c.oid) AS def FROM pg_constraint c JOIN pg_class t ON t.oid = c.conrelid WHERE t.relname = 'requirements' AND c.conname = 'requirements_column_name_check'") as any)?.def ?? "";
+      expect(def).toContain("'bogus'");
+      db.run("DELETE FROM requirements WHERE requirement_id = 'req_ab_bogus'");
+      expect(migrateRequirementColumnCheck(db).rebuilt).toBe(true);
+    } else {
+      expect(migrateRequirementColumnCheck(db).rebuilt).toBe(false);
+    }
+    const id = await card("ab-schema");
+    expect((await patch(id, { column: "abandoned" }, AWARE)).status).toBe(200);
+    expect((await patch(id, { column: "cancelled" }, AWARE)).body.error).toBe("invalid_column");
+    expect((await list()).body.capabilities).toContain("column_abandoned");
+  }, 60_000);
+
+  test("set and restore: events recorded each way, no completedAt, restorable to pool and doing", async () => {
+    const id = await card("ab-set");
+    const a = await patch(id, { column: "abandoned" }, AWARE);
+    expect(a.status).toBe(200);
+    expect(a.body.requirement.column).toBe("abandoned");
+    expect(a.body.requirement.completedAt).toBeNull();
+    expect((await patch(id, { column: "doing" }, AWARE)).body.requirement.column).toBe("doing");
+    expect((await patch(id, { column: "abandoned" }, AWARE)).body.requirement.column).toBe("abandoned");
+    expect((await patch(id, { column: "pool" }, AWARE)).body.requirement.column).toBe("pool");
+    expect(await columnEvents(id)).toEqual([["pool", "abandoned"], ["abandoned", "doing"], ["doing", "abandoned"], ["abandoned", "pool"]]);
+    // 直接建在废弃列(带声明)也行
+    const created = await send("POST", "/api/requirements", { network_id: NET, name: "ab-born", column: "abandoned" }, AWARE);
+    expect(created.body.requirement.column).toBe("abandoned");
+  }, 60_000);
+
+  test("closed like done: not overdue, no due reminder, not counted as open in stats; restoring reopens it", async () => {
+    // id:到期提醒用假时钟 T0(10-10),到期 10-07 = 逾期 3 天;old:列表的 overdue 筛选用真时钟,到期给一个早就过了的日子。
+    const id = await card("ab-overdue", { due: "2026-10-07", column: "doing" });
+    const old = await card("ab-overdue-list", { due: "2020-01-01", column: "doing" });
+    expect(ids(await list("&overdue=1"))).toContain(old);
+    await patch(id, { column: "abandoned" }, AWARE);
+    await patch(old, { column: "abandoned" }, AWARE);
+    expect(ids(await list("&overdue=1"))).not.toContain(old);
+    expect(ids(await list("&overdue=0"))).toContain(old);
+    expect(sentFor(due.runDueReminders({ now: T0 }), id)).toEqual([]);
+    const stats = (await send("GET", `/api/requirements/stats?network_id=${NET}`)).body.totals;
+    const raw = db.all("SELECT column_name FROM requirements WHERE network_id = ?1 AND COALESCE(archived, 0) = 0", NET) as any[];
+    const n = (c: string) => raw.filter(r => r.column_name === c).length;
+    expect(stats.doing).toBe(n("doing"));
+    expect(stats.pool).toBe(n("pool"));
+    expect(stats.abandoned).toBe(n("abandoned"));
+    expect(n("abandoned")).toBeGreaterThan(0);
+    // 子任务进度不把废弃的子任务算进去
+    const parent = await card("ab-parent");
+    const kid = await card("ab-kid", { parent_id: parent });
+    await card("ab-kid2", { parent_id: parent });
+    await patch(kid, { column: "abandoned" }, AWARE);
+    // 声明了:废弃的子需求不算进度;没声明(旧 App 把它当 done 列出来):算进总数、算作完成,和它看到的列表对得上
+    expect((await get(parent, AWARE)).body.requirement.children).toEqual({ total: 1, done: 0 });
+    expect((await get(parent)).body.requirement.children).toEqual({ total: 2, done: 1 });
+    expect(columnIn(await list("&parent_id=" + parent), kid)).toBe("done");
+    // 改回 doing:又逾期、又提醒
+    await patch(id, { column: "doing" }, AWARE);
+    await patch(old, { column: "doing" }, AWARE);
+    expect(ids(await list("&overdue=1"))).toContain(old);
+    expect(sentFor(due.runDueReminders({ now: T0 }), id)).toEqual(["overdue"]);
+  }, 60_000);
+
+  test("old clients (no declaration) see abandoned as done; their writes cannot un-abandon it by echo", async () => {
+    const id = await card("ab-legacy");
+    await patch(id, { column: "abandoned" }, AWARE);
+    expect((await get(id)).body.requirement.column).toBe("done");
+    expect((await get(id, AWARE)).body.requirement.column).toBe("abandoned");
+    expect((await send("GET", `/api/requirements/${id}?network_id=${NET}&accept_columns=abandoned`)).body.requirement.column).toBe("abandoned");
+    expect(columnIn(await list(), id)).toBe("done");
+    expect(columnIn(await list("&view=summary"), id)).toBe("done");
+    expect(columnIn(await list("", AWARE), id)).toBe("abandoned");
+    // 列表缓存按声明分开:同一个查询串,先旧后新,不串值
+    expect(columnIn(await list(), id)).toBe("done");
+    expect(columnIn(await list("", AWARE), id)).toBe("abandoned");
+    // 旧客户端按 done 筛:带上废弃的(它眼里就是 done)
+    expect(ids(await list("&status=done"))).toContain(id);
+    expect(ids(await list("&status=done", AWARE))).not.toContain(id);
+    expect(ids(await list("&status=abandoned", AWARE))).toContain(id);
+    // 旧客户端改别的字段 / 回传它看到的 done:仍是废弃;响应里仍是 done
+    const p1 = await patch(id, { priority: "high" });
+    expect(p1.body.requirement.column).toBe("done");
+    const p2 = await patch(id, { column: "done" });
+    expect(p2.body.requirement.column).toBe("done");
+    expect((await get(id, AWARE)).body.requirement.column).toBe("abandoned");
+    // 旧客户端明确改回 pool:照办
+    expect((await patch(id, { column: "pool" })).body.requirement.column).toBe("pool");
+    // 新客户端从 abandoned 改成 done:真的完成
+    await patch(id, { column: "abandoned" }, AWARE);
+    const done = await patch(id, { column: "done" }, AWARE);
+    expect(done.body.requirement.column).toBe("done");
+    expect(done.body.requirement.completedAt).not.toBeNull();
+  }, 60_000);
+
+  test("events and last_event: undeclared callers see the projected column; done ↔ abandoned disappears for them", async () => {
+    const id = await card("ab-events");
+    await patch(id, { column: "abandoned" }, AWARE);
+    await patch(id, { column: "done" }, AWARE);
+    await patch(id, { column: "abandoned" }, AWARE);
+    const evs = async (headers: Record<string, string> = {}) => ((await send("GET", `/api/requirements/events?network_id=${NET}&requirement_id=${id}`, undefined, headers)).body.events as any[])
+      .filter(e => e.kind === "changed" && e.field === "column").map(e => [e.old, e.new]).reverse();
+    expect(await evs(AWARE)).toEqual([["pool", "abandoned"], ["abandoned", "done"], ["done", "abandoned"]]);
+    expect(await evs()).toEqual([["pool", "done"]]);
+    const legacyRaw = JSON.stringify((await send("GET", `/api/requirements/events?network_id=${NET}`)).body.events);
+    expect(legacyRaw).not.toContain("abandoned");
+    // 每行的 last_event:最新一条是 done → abandoned,旧客户端那里投影后前后一样 → 不给字段 / 摘要
+    const legacyRow = (await list()).body.requirements.find((r: any) => r.id === id);
+    expect(legacyRow.last_event.field).toBeNull();
+    expect(legacyRow.last_event.summary).toBeUndefined();
+    const awareRow = (await list("", AWARE)).body.requirements.find((r: any) => r.id === id);
+    expect(awareRow.last_event).toMatchObject({ field: "column", summary: "done → abandoned" });
+    await patch(id, { column: "doing" }, AWARE);
+    const back = (await list()).body.requirements.find((r: any) => r.id === id);
+    expect(back.last_event).toMatchObject({ field: "column", summary: "done → doing" });
+    expect(JSON.stringify((await list()).body.requirements)).not.toContain("abandoned");
+  }, 60_000);
+
+  test("checklist toggle response is projected for undeclared callers", async () => {
+    const id = await card("ab-check", { checklist: [{ id: "c1", text: "one" }] });
+    await patch(id, { column: "abandoned" }, AWARE);
+    const legacy = await send("PATCH", `/api/requirements/${id}/checklist/c1?network_id=${NET}`, { done: true });
+    expect(legacy.status).toBe(200);
+    expect(legacy.body.requirement.column).toBe("done");
+    const aware = await send("PATCH", `/api/requirements/${id}/checklist/c1?network_id=${NET}`, { done: false }, AWARE);
+    expect(aware.body.requirement.column).toBe("abandoned");
+  }, 60_000);
+
+  test("MCP declares support: requirements_update / get / list carry the real value", async () => {
+    const id = await card("ab-mcp");
+    const up = await mcp("requirements_update", { id, network_id: NET, status: "abandoned" });
+    expect(up.requirement.column).toBe("abandoned");
+    expect((await mcp("requirements_get", { id, network_id: NET })).requirement.column).toBe("abandoned");
+    const l = await mcp("requirements_list", { network_id: NET, status: "abandoned" });
+    expect(l.requirements.map((x: any) => x.id)).toContain(id);
+    expect((await mcp("requirements_update", { id, network_id: NET, column: "doing" })).requirement.column).toBe("doing");
+  }, 60_000);
+});

package/src/requirements-comment-http.test.ts

@@ -0,0 +1,167 @@
+// #474(MCP 任务生命周期测试报告问题 5)—— 评论 / 进展:只追加,进「动态」(requirement_events kind=comment),
+// 不改任务本身。钉住:
+//   - Agent(节点令牌)经 MCP、人经 REST 都能评论,署名是调用者;description / updated_at 一个字节都不动;
+//   - requirements_events 里是 kind=comment、new.text 全文,单任务的动态体积可控;
+//   - 看不见这张卡的人评论 = 404(和读一样),只读角色 = 403,空 / 超长 = 400 + 提示;
+//   - 只追加:没有改 / 删评论的路由。
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register, createNetworkTokenForNode } from "./auth.js";
+import { db } from "./db.js";
+import { COMMENT_MAX_CHARS } from "./requirements.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-req-comment-"));
+let BASE = "";
+let hub: any = null;
+const PW = "ReqCommentPassw0rd!xyz";
+let NET = "";
+const U: Record<string, { token: string; id: string }> = {};
+let card = { id: "", seq: 0 };
+
+async function rest(token: string, method: string, path: string, body?: unknown) {
+  const res = await fetch(`${BASE}${path}`, { method, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) });
+  const text = await res.text();
+  let json: any = null;
+  try { json = JSON.parse(text); } catch {}
+  return { status: res.status, body: json, bytes: text.length };
+}
+async function rpc(token: string, name: string, args: Record<string, unknown>): Promise<{ data: any; raw: any; bytes: number }> {
+  const res = await fetch(`${BASE}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
+  });
+  const raw = await res.text();
+  const lines = raw.split("\n").filter(x => x.startsWith("data:"));
+  const out = lines.length ? JSON.parse(lines.at(-1)!.slice(5).trim()) : JSON.parse(raw);
+  const text = out.result?.content?.[0]?.text ?? "";
+  let data: any = null;
+  try { data = JSON.parse(text); } catch { data = text; }
+  return { data, raw: out, bytes: text.length };
+}
+const mcp = async (token: string, name: string, args: Record<string, unknown>) => (await rpc(token, name, args)).data;
+const cardRow = (id: string) => db.get<{ description: string | null; updated_at: string | null; updated_by_json: string | null }>("SELECT description, updated_at, updated_by_json FROM requirements WHERE requirement_id = ?1", id)!;
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+  process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+  process.env.HOST = "127.0.0.1";
+  const a = register(`cmt_owner_${Date.now()}`, PW, undefined, "Owner");
+  U.owner = { token: a.token!, id: a.user!.user_id };
+  NET = a.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [U.owner.id]);
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+  const mk = async (username: string, role: string) => {
+    expect((await rest(U.owner.token, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role })).status).toBe(200);
+    const login = await rest("", "POST", "/api/auth/login", { username, password: PW });
+    // #746 起新成员默认 scoped;这里的 member / viewer 模拟老成员('all'),scoped 那位下面再收窄。
+    expect((await rest(U.owner.token, "PUT", `/api/networks/${NET}/members/${login.body.user.user_id}/task-grants`, { task_access: "all" })).status).toBe(200);
+    return { token: login.body.token as string, id: login.body.user.user_id as string };
+  };
+  const stamp = Date.now();
+  U.member = await mk(`cmt_member_${stamp}`, "member");
+  U.viewer = await mk(`cmt_viewer_${stamp}`, "viewer");
+  U.scoped = await mk(`cmt_scoped_${stamp}`, "member");
+  expect((await rest(U.owner.token, "PUT", `/api/networks/${NET}/members/${U.scoped.id}/task-grants`, { task_access: "scoped", project_grants: [] })).status).toBe(200);
+  U.nodeA = { token: createNetworkTokenForNode(U.owner.id, NET, "示例-甲", "node_cmt_a").token!, id: "node_cmt_a" };
+  const created = (await mcp(U.nodeA.token, "requirements_create", { name: "示例任务:评论", description: "## 背景\n原文。" })).requirement;
+  card = { id: created.id, seq: created.seq };
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("requirements_comment", () => {
+  test("an Agent comments over MCP (#N): one comment event, attributed to the node; the task itself is untouched", async () => {
+    const before = cardRow(card.id);
+    const r = await mcp(U.nodeA.token, "requirements_comment", { id: `#${card.seq}`, text: "进展:示例草稿已写完,等人看。" });
+    expect(r.ok).toBe(true);
+    expect(r.event.kind).toBe("comment");
+    expect(r.event.field).toBeNull();
+    expect(r.event.new).toEqual({ text: "进展:示例草稿已写完,等人看。" });
+    expect(r.event.actor).toEqual({ kind: "node", id: "node_cmt_a" });
+    expect(r.event.requirement_id).toBe(card.id);
+    const after = cardRow(card.id);
+    expect(after).toEqual(before); // description, updated_at, updated_by all unchanged
+  });
+
+  test("a person comments over REST; both show in requirements_events with the full text, newest first", async () => {
+    const r = await rest(U.member.token, "POST", `/api/requirements/${card.id}/comments`, { text: "  好的,我下午看。  " });
+    expect(r.status).toBe(201);
+    expect(r.body.event.new.text).toBe("好的,我下午看。"); // trimmed
+    expect(r.body.event.actor).toEqual({ kind: "user", id: U.member.id });
+    const ev = await rpc(U.nodeA.token, "requirements_events", { requirement_id: `#${card.seq}` });
+    const comments = ev.data.events.filter((e: any) => e.kind === "comment");
+    expect(comments.map((e: any) => e.new.text)).toEqual(["好的,我下午看。", "进展:示例草稿已写完,等人看。"]);
+    expect(ev.data.events.at(-1).kind).toBe("created");
+  });
+
+  test("full text up to the cap, and the timeline stays small", async () => {
+    const long = "长".repeat(COMMENT_MAX_CHARS);
+    const r = await mcp(U.nodeA.token, "requirements_comment", { id: card.id, text: long });
+    expect(r.ok).toBe(true);
+    expect(r.event.new.text.length).toBe(COMMENT_MAX_CHARS);
+    const ev = await rpc(U.nodeA.token, "requirements_events", { requirement_id: card.id });
+    // 1 created + 3 comments (one of them 4000 chars): well under 20 KB.
+    expect(ev.bytes).toBeLessThan(20_000);
+    expect(ev.data.events.some((e: any) => e.kind === "comment" && e.new.text === long)).toBe(true);
+  });
+
+  test("bad input: empty → invalid_comment, over the cap → comment_too_long (REST), MCP schema → -32602; both with hints", async () => {
+    const empty = await rest(U.member.token, "POST", `/api/requirements/${card.id}/comments`, { text: "   " });
+    expect(empty.status).toBe(400);
+    expect(empty.body.error).toBe("invalid_comment");
+    expect(empty.body.field).toBe("text");
+    const tooLong = await rest(U.member.token, "POST", `/api/requirements/${card.id}/comments`, { text: "x".repeat(COMMENT_MAX_CHARS + 1) });
+    expect(tooLong.status).toBe(400);
+    expect(tooLong.body.error).toBe("comment_too_long");
+    expect(tooLong.body.hint).toContain("Split");
+    const viaMcp = await rpc(U.nodeA.token, "requirements_comment", { id: card.id, text: "x".repeat(COMMENT_MAX_CHARS + 1) });
+    expect(String(viaMcp.raw.error?.code ?? viaMcp.raw.result?.content?.[0]?.text)).toMatch(/-32602|too big|Too big/i);
+  });
+
+  test("permissions: a non-reader gets 404 (like reading), a read-only role 403; neither writes anything", async () => {
+    const count = () => db.get<{ n: number }>("SELECT COUNT(*) AS n FROM requirement_events WHERE requirement_id = ?1 AND kind = 'comment'", card.id)!.n;
+    const n = count();
+    // scoped member with no grant cannot see the task → cannot read it → cannot comment on it.
+    expect((await rest(U.scoped.token, "GET", `/api/requirements/${card.id}`)).status).toBe(404);
+    const scoped = await rest(U.scoped.token, "POST", `/api/requirements/${card.id}/comments`, { text: "看不见也想评论" });
+    expect(scoped.status).toBe(404);
+    expect(scoped.body.error).toBe("requirement_not_found");
+    const viewer = await rest(U.viewer.token, "POST", `/api/requirements/${card.id}/comments`, { text: "只读角色" });
+    expect(viewer.status).toBe(403);
+    expect(viewer.body.error).toBe("permission_denied");
+    expect(count()).toBe(n);
+    // …and the scoped member does not see the comments in the network timeline either.
+    const ev = await rest(U.scoped.token, "GET", `/api/requirements/events?network_id=${NET}`);
+    expect((ev.body.events ?? []).some((e: any) => e.requirement_id === card.id)).toBe(false);
+  });
+
+  test("append-only: no route edits or deletes a comment; unknown task → requirement_not_found with a hint", async () => {
+    expect((await rest(U.owner.token, "PATCH", `/api/requirements/${card.id}/comments`, { text: "改" })).status).toBe(404);
+    expect((await rest(U.owner.token, "DELETE", `/api/requirements/${card.id}/comments`)).status).toBe(404);
+    const missing = await mcp(U.nodeA.token, "requirements_comment", { id: "#9999", text: "没有这张卡" });
+    expect(missing.error).toBe("requirement_not_found");
+    expect(missing.hint).toContain("requirements_list");
+  });
+
+  test("discoverable: tools/list carries requirements_comment, and requirements_events mentions comments", async () => {
+    const res = await fetch(`${BASE}/mcp`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${U.nodeA.token}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list" }),
+    });
+    const raw = await res.text();
+    const lines = raw.split("\n").filter(x => x.startsWith("data:"));
+    const tools = (lines.length ? JSON.parse(lines.at(-1)!.slice(5).trim()) : JSON.parse(raw)).result.tools as any[];
+    const byName = new Map(tools.map(t => [t.name, t]));
+    expect(String(byName.get("requirements_comment")?.description)).toContain("append-only");
+    expect(String(byName.get("requirements_events")?.description)).toContain("kind=comment");
+  });
+});

package/src/requirements-completed-at-migration.test.ts

@@ -0,0 +1,70 @@
+// 完成时间的启动迁移(requirements-migrate.ts ensureRequirementCompletedAt):用加完成时间之前的表结构建库、塞行,
+// 再 import db.ts + requirements.ts(真实启动路径)。覆盖:两种旧时间形状、没有 updated_at 的行、
+// 回滚到旧 Hub 期间「移出完成」留下的残值被清掉、「移进完成」的卡被补上,以及重复执行不再改任何东西。
+import { afterAll, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const dir = mkdtempSync(join(tmpdir(), "anet-req-completed-at-"));
+const file = join(dir, "hub.db");
+process.env.COMMHUB_DB = file;
+
+const legacy = new Database(file);
+legacy.exec(`CREATE TABLE requirements (
+  requirement_id TEXT PRIMARY KEY, network_id TEXT NOT NULL, title TEXT NOT NULL,
+  column_name TEXT NOT NULL DEFAULT 'pool' CHECK(column_name IN ('pool', 'doing', 'done')), priority TEXT NOT NULL DEFAULT 'normal', due_on TEXT, assignee TEXT,
+  client_id TEXT, issues_json TEXT, created_by TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')), updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  owner_json TEXT, participants_json TEXT NOT NULL DEFAULT '[]', updated_by_json TEXT)`);
+const seed: [string, string, string, string][] = [
+  // id, column, created_at, updated_at
+  ["r_done_sqlite_ts", "done", "2026-08-01 08:00:00", "2026-09-01 10:00:00"],
+  ["r_done_iso", "done", "2026-08-02T00:00:00.000Z", "2026-09-02T03:04:05.678Z"],
+  ["r_done_bad_updated", "done", "2026-08-03T00:00:00.000Z", "not a time"],
+  ["r_doing", "doing", "2026-08-04T00:00:00.000Z", "2026-09-04T00:00:00.000Z"],
+  ["r_pool", "pool", "2026-08-05T00:00:00.000Z", "2026-09-05T00:00:00.000Z"],
+];
+for (const [id, column, createdAt, updatedAt] of seed) {
+  legacy.run("INSERT INTO requirements (requirement_id, network_id, title, column_name, created_at, updated_at, updated_by_json) VALUES (?1, 'net', ?1, ?2, ?3, ?4, ?5)",
+    [id, column, createdAt, updatedAt, JSON.stringify({ kind: "user", id: "u_last_editor" })]);
+}
+legacy.close();
+
+afterAll(() => { try { rmSync(dir, { recursive: true, force: true }); } catch {} });
+
+const read = (db: any) => Object.fromEntries((db.all("SELECT requirement_id, column_name, updated_at, completed_at, completed_by_json, completed_at_approx FROM requirements") as any[]).map(r => [r.requirement_id, r]));
+
+test("backfill: done rows get an approximate ISO completed_at from updated_at; others stay empty; idempotent", async () => {
+  const { db } = await import("./db.js");
+  await import("./requirements.js");
+  const { ensureRequirementCompletedAt } = await import("./requirements-migrate.js");
+  const by = read(db);
+  expect(by.r_done_sqlite_ts.completed_at).toBe("2026-09-01T10:00:00.000Z");
+  expect(by.r_done_iso.completed_at).toBe("2026-09-02T03:04:05.678Z");
+  // updated_at 读不懂 → 退到 created_at,而不是留空(留空的完成卡在仪表盘上就「没完成过」)
+  expect(by.r_done_bad_updated.completed_at).toBe("2026-08-03T00:00:00.000Z");
+  for (const id of ["r_done_sqlite_ts", "r_done_iso", "r_done_bad_updated"]) {
+    expect(by[id].completed_at_approx).toBe(1);
+    // 最后改的人不是「完成的人」:近似值不猜完成者
+    expect(by[id].completed_by_json).toBeNull();
+    // 补值不碰 updated_at
+    expect(by[id].updated_at).toBe(seed.find(s => s[0] === id)![3]);
+  }
+  for (const id of ["r_doing", "r_pool"]) expect([by[id].completed_at, by[id].completed_by_json, by[id].completed_at_approx]).toEqual([null, null, 0]);
+
+  // 下次启动:什么都不动
+  expect(ensureRequirementCompletedAt(db)).toEqual({ backfilled: 0, cleared: 0 });
+  expect(read(db)).toEqual(by);
+
+  // 回滚到旧 Hub 期间:旧 Hub 不认识这三列 —— 把一张完成的卡移出(列留着旧值)、把一张卡移进完成(列是空的)。
+  db.run("UPDATE requirements SET column_name = 'doing' WHERE requirement_id = 'r_done_iso'");
+  db.run("UPDATE requirements SET column_name = 'done', updated_at = '2026-09-06T00:00:00.000Z' WHERE requirement_id = 'r_pool'");
+  expect(ensureRequirementCompletedAt(db)).toEqual({ backfilled: 1, cleared: 1 });
+  const after = read(db);
+  expect([after.r_done_iso.completed_at, after.r_done_iso.completed_by_json, after.r_done_iso.completed_at_approx]).toEqual([null, null, 0]);
+  expect([after.r_pool.completed_at, after.r_pool.completed_at_approx]).toEqual(["2026-09-06T00:00:00.000Z", 1]);
+  expect(after.r_done_sqlite_ts).toEqual(by.r_done_sqlite_ts);
+  expect(ensureRequirementCompletedAt(db)).toEqual({ backfilled: 0, cleared: 0 });
+});