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

package/src/requirements-list-slim-http.test.ts

@@ -0,0 +1,319 @@
+// GET /api/requirements 省流(2026-09-30,App「连接较慢 · 数据可能稍有延迟」)—— HTTP 集成测试(真实 Bun.serve,临时库)。
+//   view=summary      —— 不带 description / checklist,换成 has_description / checklist_count;不带 view = 与原来逐字相同。
+//   changes=1         —— updated_since 之后改过的卡(含归档的)+ deleted 墓碑 + server_time;受限成员只收到他看得见的卡的删除。
+//   列表缓存          —— 表没变时复用上一次的正文 / ETag;任何写入(REST、MCP、项目删除)之后都不会拿旧的。
+//   /api/stats/routes —— 每个路由的耗时汇总,只给管理员。
+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";
+import { gunzipSync } from "node:zlib";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-requirements-slim-"));
+process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+
+const PW = "SlimListPassw0rd!x";
+let BASE = "";
+let hub: any = null;
+let NET = "";
+let admin = { token: "", id: "" };
+let member = { token: "", id: "" };
+let scoped = { token: "", id: "" };
+let cache: { size: () => number; clear: () => void; generation: () => number };
+let gzipStats: { hits: number; misses: number };
+
+type R = { status: number; body: any; text: string; headers: Headers };
+async function send(token: string, method: string, path: string, payload?: unknown, headers: Record<string, string> = {}): Promise<R> {
+  const res = await fetch(`${BASE}${path}`, {
+    method,
+    headers: { ...(token ? { Authorization: `Bearer ${token}` } : {}), "Content-Type": "application/json", ...headers },
+    body: payload === undefined ? undefined : JSON.stringify(payload),
+  });
+  const text = await res.text();
+  let body: any = null;
+  try { body = JSON.parse(text); } catch {}
+  return { status: res.status, body, text, headers: res.headers };
+}
+const list = (t: string, qs = "", headers: Record<string, string> = {}) => send(t, "GET", `/api/requirements?network_id=${NET}${qs}`, undefined, headers);
+const create = async (t: string, card: Record<string, unknown>) => {
+  const r = await send(t, "POST", "/api/requirements", { network_id: NET, ...card });
+  expect(r.status).toBe(201);
+  return r.body.requirement as { id: string; updatedAt: string };
+};
+const patch = (t: string, id: string, p: Record<string, unknown>) => send(t, "PATCH", `/api/requirements/${id}?network_id=${NET}`, p);
+const del = (t: string, id: string) => send(t, "DELETE", `/api/requirements/${id}?network_id=${NET}`);
+async function mcp(token: string, 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 } }),
+  });
+  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);
+}
+const tick = () => new Promise(r => setTimeout(r, 5));
+
+beforeAll(async () => {
+  process.env.HOST = "127.0.0.1";
+  const { register } = await import("./auth.js");
+  const { db } = await import("./db.js");
+  const a = register(`slim_admin_${Date.now()}`, PW, undefined, "Admin");
+  expect(a.ok).toBe(true);
+  admin = { token: a.token!, id: a.user!.user_id };
+  NET = a.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [admin.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) => {
+    const r = await send(admin.token, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role: "member" });
+    expect(r.status).toBe(200);
+    const login = await send("", "POST", "/api/auth/login", { username, password: PW });
+    expect(login.status).toBe(200);
+    return { token: login.body.token as string, id: login.body.user.user_id as string };
+  };
+  const stamp = Date.now();
+  member = await mk(`slim_member_${stamp}`);
+  scoped = await mk(`slim_scoped_${stamp}`);
+  // member:看全部任务、全部 Agent(可缓存);scoped:只看相关任务(不缓存,且只收到看得见的卡的删除)。
+  db.run("UPDATE network_members SET task_access = 'all', agent_access = 'all' WHERE network_id = ?1 AND user_id = ?2", [NET, member.id]);
+  db.run("UPDATE network_members SET task_access = 'scoped' WHERE network_id = ?1 AND user_id = ?2", [NET, scoped.id]);
+  cache = (await import("./requirements.js")).__requirementsListCacheForTest();
+  gzipStats = (await import("./http-gzip.js")).gzipCacheStats;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("view=summary", () => {
+  test("drops description and checklist bodies, keeps everything else, adds has_description / checklist_count", async () => {
+    const card = await create(admin.token, {
+      name: "slim-summary",
+      description: "一段很长的描述 ".repeat(200),
+      checklist: [{ text: "第一项", done: true }, { text: "第二项", done: false }, { text: "第三项", done: true }],
+    });
+    await create(admin.token, { name: "slim-empty" });
+    const full = await list(admin.token);
+    const summary = await list(admin.token, "&view=summary");
+    expect(full.status).toBe(200);
+    expect(summary.status).toBe(200);
+    expect(summary.body.view).toBe("summary");
+    expect(full.body.view).toBeUndefined();
+    expect(summary.body.capabilities).toContain("list_summary");
+    expect(summary.body.capabilities).toContain("changes");
+    const f = full.body.requirements.find((r: any) => r.id === card.id);
+    const s = summary.body.requirements.find((r: any) => r.id === card.id);
+    expect(f.description.length).toBeGreaterThan(1000);
+    expect(f.checklist).toHaveLength(3);
+    expect("description" in s).toBe(false);
+    expect("checklist" in s).toBe(false);
+    expect(s.has_description).toBe(true);
+    expect(s.checklist_count).toEqual({ total: 3, done: 2 });
+    const { description: _d, checklist: _c, ...rest } = f;
+    const { has_description: _h, checklist_count: _cc, ...sRest } = s;
+    expect(sRest).toEqual(rest);
+    const empty = summary.body.requirements.find((r: any) => r.name === "slim-empty");
+    expect(empty.has_description).toBe(false);
+    expect(empty.checklist_count).toEqual({ total: 0, done: 0 });
+    // 同样的卡、同样的顺序;全文在单卡接口上照旧拿得到
+    expect(summary.body.requirements.map((r: any) => r.id)).toEqual(full.body.requirements.map((r: any) => r.id));
+    const one = await send(admin.token, "GET", `/api/requirements/${card.id}?network_id=${NET}`);
+    expect(one.body.requirement.description).toBe(f.description);
+    // 比的是 summary 省掉的那部分(正文 / 子任务):两边一样多的 last_event(#506,每行约 150 B)不算,
+    // 否则这张只有几行的小表上,固定开销会把比例拉过一半。capabilities 同理:两边一样、每加一个能力就长一截。
+    const bare = (body: any) => JSON.stringify({ ...body, capabilities: [], requirements: body.requirements.map(({ last_event: _l, ...r }: any) => r) }).length;
+    expect(summary.body.requirements.every((r: any) => "last_event" in r)).toBe(true);
+    expect(bare(summary.body)).toBeLessThan(bare(full.body) / 2);
+  });
+
+  test("view=full is the plain list; an unknown view is a 400", async () => {
+    const plain = await list(admin.token);
+    const explicit = await list(admin.token, "&view=full");
+    expect(explicit.body.requirements).toEqual(plain.body.requirements);
+    expect((await list(admin.token, "&view=tiny")).status).toBe(400);
+    expect((await list(admin.token, "&view=tiny")).body.error).toBe("invalid_view");
+  });
+});
+
+describe("changes=1", () => {
+  test("requires updated_since", async () => {
+    const r = await list(admin.token, "&changes=1");
+    expect(r.status).toBe(400);
+    expect(r.body.error).toBe("updated_since_required");
+  });
+
+  test("returns only cards changed since, archived ones included, plus deleted ids and a server_time to continue from", async () => {
+    const keep = await create(admin.token, { name: "slim-keep" });
+    const edit = await create(admin.token, { name: "slim-edit" });
+    const arch = await create(admin.token, { name: "slim-arch" });
+    const gone = await create(admin.token, { name: "slim-gone" });
+    const first = await list(admin.token, `&changes=1&updated_since=${encodeURIComponent(new Date(Date.now() - 60_000).toISOString())}`);
+    expect(first.status).toBe(200);
+    const t0 = first.body.server_time as string;
+    expect(Date.parse(t0)).toBeGreaterThan(0);
+    expect(first.body.deleted).toEqual([]);
+    await tick();
+
+    expect((await patch(admin.token, edit.id, { name: "slim-edit-2" })).status).toBe(200);
+    expect((await patch(admin.token, arch.id, { archived: true })).status).toBe(200);
+    expect((await del(admin.token, gone.id)).status).toBe(200);
+
+    const delta = await list(admin.token, `&changes=1&updated_since=${encodeURIComponent(t0)}`);
+    expect(delta.status).toBe(200);
+    const ids = delta.body.requirements.map((r: any) => r.id).sort();
+    expect(ids).toEqual([edit.id, arch.id].sort());
+    expect(delta.body.requirements.find((r: any) => r.id === arch.id).archived).toBe(true);
+    expect(delta.body.requirements.find((r: any) => r.id === edit.id).name).toBe("slim-edit-2");
+    expect(delta.body.deleted).toEqual([gone.id]);
+    expect(ids).not.toContain(keep.id);
+    expect(Date.parse(delta.body.tombstones_since)).toBeLessThan(Date.parse(t0));
+
+    // 接着读:什么都没变就是空的
+    const again = await list(admin.token, `&changes=1&updated_since=${encodeURIComponent(delta.body.server_time)}`);
+    expect(again.body.requirements).toEqual([]);
+    expect(again.body.deleted).toEqual([]);
+
+    // 与 view=summary 组合
+    const slim = await list(admin.token, `&changes=1&view=summary&updated_since=${encodeURIComponent(t0)}`);
+    expect(slim.body.requirements.every((r: any) => !("description" in r) && "checklist_count" in r)).toBe(true);
+
+    // 不带 changes 的 updated_since 与原来一样:归档的不回、没有 deleted
+    const legacy = await list(admin.token, `&updated_since=${encodeURIComponent(t0)}`);
+    expect(legacy.body.requirements.map((r: any) => r.id)).toEqual([edit.id]);
+    expect(legacy.body.deleted).toBeUndefined();
+    expect(legacy.body.server_time).toBeUndefined();
+  });
+
+  test("side effects that used to leave updated_at alone now show up: orphaned children, cleared project", async () => {
+    const parent = await create(admin.token, { name: "slim-parent" });
+    const child = await create(admin.token, { name: "slim-child", parent_id: parent.id });
+    const proj = await send(admin.token, "POST", "/api/requirements/projects", { network_id: NET, name: "slim-proj" });
+    expect(proj.status).toBe(201);
+    const inProj = await create(admin.token, { name: "slim-in-proj", project_id: proj.body.project.id });
+    await tick();
+    const t0 = new Date().toISOString();
+    await tick();
+    expect((await del(admin.token, parent.id)).status).toBe(200);
+    expect((await send(admin.token, "DELETE", `/api/requirements/projects/${proj.body.project.id}?network_id=${NET}`)).status).toBe(200);
+    const delta = await list(admin.token, `&changes=1&updated_since=${encodeURIComponent(t0)}`);
+    const byId = new Map(delta.body.requirements.map((r: any) => [r.id, r]));
+    expect((byId.get(child.id) as any)?.parent_id).toBeNull();
+    expect((byId.get(inProj.id) as any)?.project_id).toBeNull();
+    expect(delta.body.deleted).toEqual([parent.id]);
+  });
+
+  test("a scoped member only hears about deletions of cards they could see", async () => {
+    const theirs = await create(admin.token, { name: "slim-theirs", owner: { kind: "user", id: scoped.id } });
+    const hidden = await create(admin.token, { name: "slim-hidden" });
+    const seen = await list(scoped.token);
+    expect(seen.body.requirements.map((r: any) => r.id)).toContain(theirs.id);
+    expect(seen.body.requirements.map((r: any) => r.id)).not.toContain(hidden.id);
+    await tick();
+    const t0 = new Date().toISOString();
+    await tick();
+    expect((await del(admin.token, theirs.id)).status).toBe(200);
+    expect((await del(admin.token, hidden.id)).status).toBe(200);
+    const mine = await list(scoped.token, `&changes=1&updated_since=${encodeURIComponent(t0)}`);
+    expect(mine.body.deleted).toEqual([theirs.id]);
+    const all = await list(admin.token, `&changes=1&updated_since=${encodeURIComponent(t0)}`);
+    expect(all.body.deleted.sort()).toEqual([theirs.id, hidden.id].sort());
+  });
+});
+
+describe("list cache", () => {
+  test("an unchanged table is served from the cache: same ETag, and If-None-Match still 304s", async () => {
+    cache.clear();
+    const a = await list(admin.token);
+    expect(cache.size()).toBe(1);
+    const b = await list(admin.token);
+    expect(b.headers.get("etag")).toBe(a.headers.get("etag"));
+    expect(b.text).toBe(a.text);
+    expect((await list(admin.token, "", { "If-None-Match": a.headers.get("etag")! })).status).toBe(304);
+  });
+
+  test("every kind of write invalidates it: REST patch, MCP update, checklist tick, delete", async () => {
+    const card = await create(admin.token, { name: "slim-cache", checklist: [{ text: "x", done: false }] });
+    const seen = async () => (await list(admin.token)).body.requirements.find((r: any) => r.id === card.id);
+    expect((await seen()).name).toBe("slim-cache");
+    await patch(admin.token, card.id, { name: "slim-cache-rest" });
+    expect((await seen()).name).toBe("slim-cache-rest");
+    const viaMcp = await mcp(admin.token, "requirements_update", { id: card.id, network_id: NET, name: "slim-cache-mcp" });
+    expect(viaMcp.ok).toBe(true);
+    expect((await seen()).name).toBe("slim-cache-mcp");
+    const item = (await seen()).checklist[0];
+    expect((await send(admin.token, "PATCH", `/api/requirements/${card.id}/checklist/${item.id}?network_id=${NET}`, { done: true })).status).toBe(200);
+    expect((await seen()).checklist[0].done).toBe(true);
+    await del(admin.token, card.id);
+    expect(await seen()).toBeUndefined();
+  });
+
+  test("a failed write still invalidates (the handler may have written before failing)", async () => {
+    const g = cache.generation();
+    await send(admin.token, "PATCH", `/api/requirements/does-not-exist?network_id=${NET}`, { name: "x" });
+    expect(cache.generation()).toBe(g + 1);
+    // 不是需求接口的写入不动代数
+    await send(admin.token, "POST", "/api/task", { alias: "nobody", task: "x" });
+    expect(cache.generation()).toBe(g + 1);
+  });
+
+  test("callers are cached separately; a member's access change is seen at once; scoped / agent-restricted members are never cached", async () => {
+    cache.clear();
+    await list(admin.token);
+    await list(member.token);
+    expect(cache.size()).toBe(2);
+    await list(scoped.token);
+    expect(cache.size()).toBe(2);
+    const { db } = await import("./db.js");
+    const before = await list(member.token);
+    db.run("UPDATE network_members SET task_access = 'scoped' WHERE network_id = ?1 AND user_id = ?2", [NET, member.id]);
+    const after = await list(member.token);
+    expect(after.body.requirements.length).toBeLessThan(before.body.requirements.length);
+    db.run("UPDATE network_members SET task_access = 'all' WHERE network_id = ?1 AND user_id = ?2", [NET, member.id]);
+    expect((await list(member.token)).body.requirements.length).toBe(before.body.requirements.length);
+    // Agent 受限(看得见哪些 Agent 取决于节点表)→ 不缓存
+    cache.clear();
+    db.run("UPDATE network_members SET agent_access = 'granted' WHERE network_id = ?1 AND user_id = ?2", [NET, member.id]);
+    await list(member.token);
+    expect(cache.size()).toBe(0);
+    db.run("UPDATE network_members SET agent_access = 'all' WHERE network_id = ?1 AND user_id = ?2", [NET, member.id]);
+  });
+
+  test("changes=1 and search are not cached", async () => {
+    cache.clear();
+    await list(admin.token, `&changes=1&updated_since=${encodeURIComponent(new Date(0).toISOString())}`);
+    await list(admin.token, "&q=slim");
+    expect(cache.size()).toBe(0);
+  });
+
+  test("gzip of an unchanged list is computed once", async () => {
+    const before = { ...gzipStats };
+    const a = await fetch(`${BASE}/api/requirements?network_id=${NET}`, { headers: { Authorization: `Bearer ${admin.token}`, "Accept-Encoding": "gzip" }, decompress: false } as any);
+    const b = await fetch(`${BASE}/api/requirements?network_id=${NET}`, { headers: { Authorization: `Bearer ${admin.token}`, "Accept-Encoding": "gzip" }, decompress: false } as any);
+    expect(a.headers.get("content-encoding")).toBe("gzip");
+    const ga = new Uint8Array(await a.arrayBuffer());
+    const gb = new Uint8Array(await b.arrayBuffer());
+    expect(Buffer.from(gunzipSync(gb)).toString()).toBe(Buffer.from(gunzipSync(ga)).toString());
+    expect(gzipStats.hits).toBeGreaterThanOrEqual(before.hits + 1);
+    expect(JSON.parse(Buffer.from(gunzipSync(gb)).toString()).ok).toBe(true);
+  });
+});
+
+describe("GET /api/stats/routes", () => {
+  test("admin sees per-route timings with ids collapsed; a member gets 403", async () => {
+    await list(admin.token, "&view=summary");
+    const r = await send(admin.token, "GET", "/api/stats/routes?minutes=5");
+    expect(r.status).toBe(200);
+    const routes = r.body.routes.map((x: any) => x.route);
+    expect(routes).toContain("GET /api/requirements?view=summary");
+    expect(routes.some((x: string) => x.startsWith("PATCH /api/requirements/:id"))).toBe(true);
+    const row = r.body.routes.find((x: any) => x.route === "GET /api/requirements");
+    expect(row.count).toBeGreaterThan(0);
+    expect(row.max_ms).toBeGreaterThanOrEqual(row.avg_ms);
+    expect((await send(member.token, "GET", "/api/stats/routes")).status).toBe(403);
+  });
+});

package/src/requirements-mcp.test.ts

@@ -0,0 +1,163 @@
+// 需求池 MCP 工具:走真 MCP in-process transport。Agent(节点令牌)在自己网络里读 / 建 / 改 / 勾 / upsert、
+// 别的网络的节点碰不到、删除不存在于工具里(只有人能在 REST 删)。同步场景:同一个 GitHub issue 同步两次不重复。
+// 跑法:cd server && COMMHUB_DB=/tmp/req-mcp.db bun test src/requirements-mcp.test.ts
+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-mcp-"));
+process.env.COMMHUB_DB = join(dir, "hub.db");
+
+const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
+const { InMemoryTransport } = await import("@modelcontextprotocol/sdk/inMemory.js");
+const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
+const { db } = await import("./db.js");
+const { register, createNetworkTokenForNode } = await import("./auth.js");
+const { registerTools } = await import("./tools.js");
+
+type Identity = { net: string; user: string; alias: string; isNetworkToken: boolean; tokenId: string };
+let owner: Identity, bot: Identity, foreignBot: Identity;
+let ownerNet = "";
+
+async function connect(id: Identity) {
+  const server = new McpServer({ name: "req-mcp-test", version: "1" });
+  registerTools(server, undefined, id.isNetworkToken ? id.net : null, id.user, id.alias, id.isNetworkToken, id.tokenId);
+  const client = new Client({ name: "req-mcp-client", version: "1" });
+  const [ct, st] = InMemoryTransport.createLinkedPair();
+  await server.connect(st);
+  await client.connect(ct);
+  const call = async (name: string, args: Record<string, unknown>) => {
+    const r: any = await client.callTool({ name, arguments: args });
+    const first = r.content?.[0];
+    if (r.isError) return { mcpError: true, text: first?.text };
+    return JSON.parse(first.text);
+  };
+  return { server, call, close: async () => { await client.close(); await server.close(); } };
+}
+
+beforeAll(() => {
+  const o = register(`reqmcp_owner_${Date.now()}`, "ReqMcpOwner123!", undefined, "seed");
+  const x = register(`reqmcp_other_${Date.now()}`, "ReqMcpOther123!", undefined, "seed");
+  ownerNet = o.network_id!;
+  const t1 = createNetworkTokenForNode(o.user!.user_id, ownerNet, "gh-sync", "node_gh_sync");
+  const t2 = createNetworkTokenForNode(x.user!.user_id, x.network_id!, "foreign", "node_foreign");
+  owner = { net: ownerNet, user: o.user!.user_id, alias: o.user!.username, isNetworkToken: false, tokenId: "tok_user" };
+  bot = { net: ownerNet, user: o.user!.user_id, alias: "gh-sync", isNetworkToken: true, tokenId: t1.token_id! };
+  foreignBot = { net: x.network_id!, user: x.user!.user_id, alias: "foreign", isNetworkToken: true, tokenId: t2.token_id! };
+});
+afterAll(() => { try { rmSync(dir, { recursive: true, force: true }); } catch {} });
+
+describe("requirements MCP tools", () => {
+  test("the seven tools are registered with validated schemas; there is no delete tool", async () => {
+    const s = await connect(owner);
+    try {
+      const reg: Record<string, any> = (s.server as any)._registeredTools;
+      for (const n of ["requirements_list", "requirements_get", "requirements_create", "requirements_update", "requirements_checklist_toggle", "requirements_upsert_by_external_ref", "projects_list"]) expect(reg[n], n).toBeDefined();
+      expect(Object.keys(reg).some(n => /^requirements_delete/.test(n))).toBe(false);
+      // 校验:坏的 status / 负责人种类 / 子任务 id 在协议边界被拒
+      expect((await s.call("requirements_list", { status: "nope" })).mcpError).toBe(true);
+      expect((await s.call("requirements_create", { name: "x", owner: { kind: "robot", id: "a" } })).mcpError).toBe(true);
+      expect((await s.call("requirements_checklist_toggle", { id: "r", item_id: "has space", done: true })).mcpError).toBe(true);
+      expect((await s.call("requirements_create", { name: "" })).mcpError).toBe(true);
+      // P0–P3:lowest(P3 极低)在建 / 改 / upsert 都能写;不认识的值在协议边界被拒
+      expect((await s.call("requirements_create", { name: "x", priority: "urgent" })).mcpError).toBe(true);
+      const low = await s.call("requirements_create", { name: "极低", priority: "lowest" });
+      expect(low.requirement.priority).toBe("lowest");
+      expect((await s.call("requirements_update", { id: low.requirement.id, priority: "high" })).requirement.priority).toBe("high");
+      expect((await s.call("requirements_update", { id: low.requirement.id, priority: "lowest" })).requirement.priority).toBe("lowest");
+      expect((await s.call("requirements_upsert_by_external_ref", { external_ref: "github:acme/p3#1", name: "同步", priority: "lowest" })).requirement.priority).toBe("lowest");
+    } finally { await s.close(); }
+  });
+
+  test("an agent syncs a GitHub issue idempotently, edits it, ticks a checklist item and archives it", async () => {
+    const s = await connect(bot);
+    try {
+      const ref = "github:acme/widgets#42";
+      const first = await s.call("requirements_upsert_by_external_ref", { external_ref: ref, external_url: "https://github.com/acme/widgets/issues/42", name: "修复登录", description: "issue 正文", checklist: [{ id: "c1", text: "复现" }, { id: "c2", text: "修" }] });
+      expect(first.ok).toBe(true);
+      expect(first.created).toBe(true);
+      const tagged = await s.call("requirements_update", { id: first.requirement.id, tags: ["release"] });
+      expect(tagged.requirement.tags).toEqual(["release"]);
+      expect(first.requirement.created_by).toEqual({ kind: "node", id: "node_gh_sync" });
+      const again = await s.call("requirements_upsert_by_external_ref", { external_ref: ref, name: "修复登录(改了标题)" });
+      expect(again.created).toBe(false);
+      expect(again.requirement.tags).toEqual(["release"]);
+      expect(again.requirement.id).toBe(first.requirement.id);
+      const listed = await s.call("requirements_list", { external_ref: ref });
+      expect(listed.requirements.length).toBe(1);
+      expect(listed.requirements[0].name).toBe("修复登录(改了标题)");
+      const dup = await s.call("requirements_create", { name: "重复", external_ref: ref });
+      expect(dup.error).toBe("external_ref_exists");
+      expect(dup.existing_id).toBe(first.requirement.id);
+      expect(dup.status).toBe(409);
+      const id = first.requirement.id;
+      expect((await s.call("requirements_update", { id, column: "doing", agent_owner: { kind: "node", id: "node_gh_sync" } })).requirement.column).toBe("doing");
+      const ticked = await s.call("requirements_checklist_toggle", { id, item_id: "c1", done: true });
+      expect(ticked.requirement.checklist.map((i: any) => i.done)).toEqual([true, false]);
+      expect((await s.call("requirements_get", { id })).requirement.agent_owner).toEqual({ kind: "node", id: "node_gh_sync" });
+      expect((await s.call("requirements_list", { status: "doing", agent_owner: "node:node_gh_sync" })).requirements.map((r: any) => r.id)).toContain(id);
+      expect((await s.call("requirements_update", { id, owner: { kind: "node", id: "node_gh_sync" }, agent_owner: null })).error).toBe("owner_must_be_human");
+      expect((await s.call("requirements_update", { id, archived: true })).requirement.archived).toBe(true);
+      expect((await s.call("requirements_list", {})).requirements.some((r: any) => r.id === id)).toBe(false);
+      expect((await s.call("requirements_list", { include_archived: true })).requirements.some((r: any) => r.id === id)).toBe(true);
+      expect(Array.isArray((await s.call("projects_list", {})).projects)).toBe(true);
+      // 子需求:建子卡、父卡上的进度、按父卡 / 顶层过滤
+      const child = await s.call("requirements_create", { name: "子需求", parent_id: id });
+      expect(child.requirement.parent_id).toBe(id);
+      expect((await s.call("requirements_get", { id })).requirement.children.total).toBe(1);
+      expect((await s.call("requirements_list", { parent_id: id })).requirements.map((r: any) => r.id)).toEqual([child.requirement.id]);
+      expect((await s.call("requirements_list", { top_level: true, include_archived: true })).requirements.some((r: any) => r.id === child.requirement.id)).toBe(false);
+      expect((await s.call("requirements_update", { id, parent_id: child.requirement.id })).error).toBe("parent_cycle");
+      // q= / limit / cursor 透传到 GET /api/requirements
+      expect((await s.call("requirements_list", { q: "子需求" })).requirements.map((r: any) => r.id)).toEqual([child.requirement.id]);
+      const page = await s.call("requirements_list", { limit: 1, include_archived: true });
+      expect(page.requirements.length).toBe(1);
+      expect(page.has_more).toBe(true);
+      expect((await s.call("requirements_list", { limit: 1, include_archived: true, cursor: page.next_cursor })).requirements[0].id).not.toBe(page.requirements[0].id);
+      // view / changes 透传(Hub capability list_summary / changes):精简行没有正文;增量带 deleted 与 server_time
+      const slim = await s.call("requirements_list", { view: "summary", include_archived: true });
+      const slimRow = slim.requirements.find((r: any) => r.id === id);
+      expect(slim.view).toBe("summary");
+      expect("description" in slimRow).toBe(false);
+      expect(typeof slimRow.checklist_count.total).toBe("number");
+      expect(typeof slimRow.has_description).toBe("boolean");
+      expect((await s.call("requirements_list", { view: "tiny" })).mcpError).toBe(true);
+      expect((await s.call("requirements_list", { changes: true })).error).toBe("updated_since_required");
+      const since = new Date(Date.now() - 1000).toISOString();
+      await s.call("requirements_update", { id: child.requirement.id, name: "子需求改名" });
+      const delta = await s.call("requirements_list", { changes: true, updated_since: since, view: "summary" });
+      expect(delta.requirements.map((r: any) => r.id)).toContain(child.requirement.id);
+      expect(Array.isArray(delta.deleted)).toBe(true);
+      expect(typeof delta.server_time).toBe("string");
+    } finally { await s.close(); }
+  });
+
+  test("a node token from another network cannot see or touch these tasks, nor write into this network", async () => {
+    const mine = await connect(bot);
+    const theirs = await connect(foreignBot);
+    try {
+      const made = await mine.call("requirements_create", { name: "只属于本网络" });
+      const id = made.requirement.id;
+      expect((await theirs.call("requirements_get", { id })).error).toBe("requirement_not_found");
+      expect((await theirs.call("requirements_update", { id, name: "越界" })).error).toBe("requirement_not_found");
+      expect((await theirs.call("requirements_checklist_toggle", { id, item_id: "x", done: true })).error).toBe("requirement_not_found");
+      expect((await theirs.call("requirements_list", { network_id: ownerNet })).requirements.some((r: any) => r.id === id)).toBe(false);
+      const planted = await theirs.call("requirements_create", { name: "塞进去", network_id: ownerNet });
+      expect(planted.ok).toBe(true);
+      const row = db.get<{ network_id: string }>("SELECT network_id FROM requirements WHERE requirement_id = ?1", planted.requirement.id)!;
+      expect(row.network_id).toBe(foreignBot.net);
+      expect((await mine.call("requirements_get", { id })).requirement.name).toBe("只属于本网络");
+    } finally { await mine.close(); await theirs.close(); }
+  });
+
+  test("a user token keeps working through the same tools", async () => {
+    const s = await connect(owner);
+    try {
+      const made = await s.call("requirements_create", { name: "人建的", network_id: ownerNet, owner: { kind: "user", id: owner.user } });
+      expect(made.ok).toBe(true);
+      expect(made.requirement.created_by).toEqual({ kind: "user", id: owner.user });
+      expect((await s.call("requirements_list", { network_id: ownerNet, owner: `user:${owner.user}` })).requirements.map((r: any) => r.id)).toContain(made.requirement.id);
+    } finally { await s.close(); }
+  });
+});