@sleep2agi/commhub-server 0.9.0-preview.154 → 0.9.0-preview.155

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.154",
+  "version": "0.9.0-preview.155",
   "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and MCP tools (17 collaboration-core + node/provider ops tools; authoritative list: docs-site/docs/api/mcp-tools.md).",
   "type": "module",
   "main": "src/index.ts",

package/src/project-viewer-can-http.test.ts

@@ -91,7 +91,9 @@ describe("GET /api/requirements/projects 的 viewer_can.edit", () => {
 
   test("只加字段:其余键与之前逐字相同", async () => {
     const row = (await projects("alice"))["pvc-P2"];
-    expect(Object.keys(row).sort()).toEqual(["archived", "color", "createdAt", "id", "name", "sort", "viewer_can"]);
+    // parentId 是 2026-10-24 加的「子项目」字段（admin：管理项目里看不到层级）；
+    // 它同样是加法式的：这里钉的是「已知键一个不多一个不少」，新键必须显式加进这个清单。
+    expect(Object.keys(row).sort()).toEqual(["archived", "color", "createdAt", "id", "name", "parentId", "sort", "viewer_can"]);
     expect(Object.keys(row.viewer_can)).toEqual(["edit"]);
   });
 

package/src/requirements-errors.ts

@@ -40,6 +40,13 @@ const ENTRIES: Record<string, Entry> = {
   tag_parent_not_found: { field: 'parent_id', message: 'No tag named that in this network.', hint: 'Create the parent first (parent_id: null), or read GET /api/requirements/tags → nodes for the names that exist.' },
   invalid_tag_parent_id: { field: 'parent_id', message: 'parent_id must be a tag name in this network, or null for the root.', hint: 'Tag names are 1–20 characters; read GET /api/requirements/tags → nodes for the names that exist.' },
   tag_parent_cycle: { field: 'parent_id', message: 'A tag cannot be its own parent.', hint: 'Pass a different parent, or null for the root.' },
+  // 子项目（admin 2026-10-24）：项目也能成层级，错误码与标签那几条**分开**，文案指向 proj_… 而不是标签名。
+  invalid_project_parent: { field: 'parent_id', message: 'parent_id must be a project id (proj_…) or null for a top-level project.', hint: 'Call projects_list to get project ids.' },
+  project_parent_not_found: { field: 'parent_id', message: 'No project with that id in this network (or it was deleted).', hint: 'Call projects_list to get the ids that exist.' },
+  project_parent_archived: { field: 'parent_id', message: 'That parent project is archived, so it cannot take children.', hint: 'Unarchive it first, or pick an active project.' },
+  project_parent_cycle: { field: 'parent_id', message: 'That parent would make the project its own ancestor.', hint: 'Pick a project that is not this one or one of its children.' },
+  project_parent_too_deep: { field: 'parent_id', message: 'Projects nest at most 3 levels (a top-level project counts as level 1).', hint: 'Attach it to a higher-level project.' },
+  project_has_children: { message: 'This project still has sub-projects, so it cannot be deleted.', hint: 'Move or delete the sub-projects first (a parent is never silently orphaned).' },
   tag_depth_exceeded: { field: 'parent_id', message: 'Tags nest at most 4 levels (the root counts as level 1).', hint: 'Attach the tag to a higher-level tag.' },
   invalid_tag: { field: 'name', message: 'Tag names are 1–20 characters after trimming, with no control characters.', hint: 'Shorten the name, or remove line breaks.' },
   checklist_item_not_found: { field: 'item_id', message: 'This task has no checklist item with that id.', hint: 'Item ids (ck_…) are in requirements_get → checklist[].id.' },

package/src/requirements-migrate.ts

@@ -41,6 +41,9 @@ export function ensureRequirementProjects(database: DbAdapter): void {
     );
     CREATE INDEX IF NOT EXISTS idx_requirement_projects_network ON requirement_projects(network_id, sort);
   `);
+  // 子项目（admin 2026-10-24：管理项目里没有层级）。加法式列，老库用 ALTER 补；重复执行无副作用。
+  // NULL = 顶层项目，所以现有行不需要回填。
+  try { database.exec("ALTER TABLE requirement_projects ADD COLUMN parent_id TEXT"); } catch {}
 }
 
 /**

package/src/requirements-projects-parent-http.test.ts

@@ -0,0 +1,123 @@
+// 子项目（admin 2026-10-24：管理项目里只能平铺，看不到层级）。
+//
+// 本文件钉住四件事，任何一条错都会让「项目」这个词变得不可信：
+//   1. 建/搬家都能指定 parent_id，GET 列表能读回；
+//   2. 深度上限 3 层（顶层=1），超了拒绝而不是悄悄截断；
+//   3. 环（把自己挂到自己的后代下面 / 挂到自己身上）必须拒绝；
+//   4. 有子项目的项目不能直接删（不偷偷把子项目变孤儿或改写它们的层级）。
+// 另外：父项目必须同网络、未归档。
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import "./require-explicit-test-db.js";
+import { register } from "./auth.js";
+import { bootServer } from "./server.js";
+
+let BASE = "";
+let server: any = null;
+let token = "";
+let NET = "";
+
+async function send(method: string, path: string, payload?: unknown) {
+  const res = await fetch(`${BASE}${path}`, {
+    method,
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    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 };
+}
+
+const P = (path: string) => `${path}${path.includes("?") ? "&" : "?"}network_id=${NET}`;
+const mk = (name: string, parent_id?: string | null) =>
+  send("POST", P("/api/requirements/projects"), parent_id === undefined ? { name } : { name, parent_id });
+
+beforeAll(async () => {
+  const suffix = `${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+  const a = register(`projparent_${suffix}`, "ProjParentPw123!", undefined, "pp");
+  expect(a.ok).toBe(true);
+  token = a.token!;
+  NET = a.network_id!;
+  server = bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${server.port}`;
+}, 30_000);
+
+afterAll(() => { try { server?.stop?.(true); } catch {} });
+
+describe("sub-projects (parent_id)", () => {
+  test("create a child and read the hierarchy back", async () => {
+    const parent = await mk("父项目");
+    expect(parent.status).toBe(201);
+    const parentId = parent.body.project.id;
+    expect(parent.body.project.parentId).toBeNull();
+
+    const child = await mk("子项目", parentId);
+    expect(child.status).toBe(201);
+    expect(child.body.project.parentId).toBe(parentId);
+
+    const list = await send("GET", P("/api/requirements/projects"));
+    expect(list.status).toBe(200);
+    const rows = list.body.projects as any[];
+    expect(rows.find((r) => r.name === "子项目")!.parentId).toBe(parentId);
+    expect(rows.find((r) => r.name === "父项目")!.parentId).toBeNull();
+  });
+
+  test("a project can be moved under another one, and back to the top", async () => {
+    const a = await mk("可搬 A");
+    const b = await mk("可搬 B");
+    const moved = await send("PATCH", P(`/api/requirements/projects/${b.body.project.id}`), { parent_id: a.body.project.id });
+    expect(moved.status).toBe(200);
+    expect(moved.body.project.parentId).toBe(a.body.project.id);
+
+    const back = await send("PATCH", P(`/api/requirements/projects/${b.body.project.id}`), { parent_id: null });
+    expect(back.status).toBe(200);
+    expect(back.body.project.parentId).toBeNull();
+  });
+
+  test("depth is capped at 3 (top level counts as 1)", async () => {
+    const l1 = await mk("深 1");
+    const l2 = await mk("深 2", l1.body.project.id);
+    const l3 = await mk("深 3", l2.body.project.id);
+    expect(l3.status).toBe(201);
+    const l4 = await mk("深 4", l3.body.project.id);
+    expect(l4.status).toBe(400);
+    expect(l4.body.error).toBe("project_parent_too_deep");
+  });
+
+  test("a cycle is refused (self, and a descendant)", async () => {
+    const a = await mk("环 A");
+    const b = await mk("环 B", a.body.project.id);
+    const self = await send("PATCH", P(`/api/requirements/projects/${a.body.project.id}`), { parent_id: a.body.project.id });
+    expect(self.status).toBe(400);
+    expect(self.body.error).toBe("project_parent_cycle");
+
+    // 把 A 挂到它自己的子项目 B 下面 = 环
+    const loop = await send("PATCH", P(`/api/requirements/projects/${a.body.project.id}`), { parent_id: b.body.project.id });
+    expect(loop.status).toBe(400);
+    expect(loop.body.error).toBe("project_parent_cycle");
+  });
+
+  test("a parent that does not exist, is archived, or lives in another network is refused", async () => {
+    const missing = await mk("缺父", "proj_does_not_exist");
+    expect(missing.status).toBe(404);
+    expect(missing.body.error).toBe("project_parent_not_found");
+
+    const parent = await mk("会归档的父");
+    await send("PATCH", P(`/api/requirements/projects/${parent.body.project.id}`), { archived: true });
+    const archived = await mk("挂到归档父", parent.body.project.id);
+    expect(archived.status).toBe(400);
+    expect(archived.body.error).toBe("project_parent_archived");
+  });
+
+  test("a project with children cannot be deleted (children are not silently orphaned)", async () => {
+    const parent = await mk("有孩子的父");
+    const child = await mk("孩子", parent.body.project.id);
+    const del = await send("DELETE", P(`/api/requirements/projects/${parent.body.project.id}`));
+    expect(del.status).toBe(409);
+    expect(del.body.error).toBe("project_has_children");
+
+    // 先删孩子，父就能删
+    expect((await send("DELETE", P(`/api/requirements/projects/${child.body.project.id}`))).status).toBe(200);
+    expect((await send("DELETE", P(`/api/requirements/projects/${parent.body.project.id}`))).status).toBe(200);
+  });
+});

package/src/requirements-status-participants-http.test.ts

@@ -213,8 +213,8 @@ describe("tool descriptions", () => {
     // #478:节点令牌的 tools/list 里本来就没有 projects_create / projects_update(调了也是 403),那两条的说明从人的列表里读。
     expect(byName.has("projects_create")).toBe(false);
     const human = new Map(((await rpc(U.member.token, "tools/list", {})).result.tools as any[]).map(t => [t.name, t]));
-    expect(byName.get("projects_list").description).toMatch(/node \(Agent\) tokens can only read projects/i);
-    for (const name of ["projects_create", "projects_update"]) expect(human.get(name).description).toMatch(/node \(Agent\) tokens can only read projects/i);
+    expect(byName.get("projects_list").description).toMatch(/node (?:\(Agent\) )?tokens can only read projects/i);
+    for (const name of ["projects_create", "projects_update"]) expect(human.get(name).description).toMatch(/node (?:\(Agent\) )?tokens can only read projects/i);
     const denied = await mcp(U.nodeA.token, "projects_create", { name: "示例项目" });
     expect(denied.status).toBe(403);
     expect(denied.error).toBe("user_token_required");

package/src/requirements.ts

@@ -348,11 +348,13 @@ function storedChecklist(raw: string | null): ChecklistItem[] {
 // ── 项目 ──
 // 按网络隔离;名字 1–40 字,同一网络里未归档的项目不重名;颜色 #RRGGBB;sort 越小越靠前。
 // 删除 = 删项目行 + 把引用它的卡片 project_id 置空(卡片本身不动);归档 = 保留引用,只是不能再被选。
-type ProjectRow = { project_id: string; network_id: string; name: string; color: string; sort: number; archived: number; created_at: string };
+type ProjectRow = { project_id: string; network_id: string; name: string; color: string; sort: number; archived: number; created_at: string; parent_id: string | null };
 const PROJECT_COLOR = /^#[0-9a-fA-F]{6}$/;
 const PROJECT_PALETTE = ["#2563eb", "#16a34a", "#d97706", "#dc2626", "#7c3aed", "#0891b2", "#db2777", "#4b5563"];
-const PROJECT_SELECT = "project_id, network_id, name, color, sort, archived, created_at";
-const projectPublic = (row: ProjectRow) => ({ id: row.project_id, name: row.name, color: row.color, sort: row.sort, archived: !!row.archived, createdAt: row.created_at });
+const PROJECT_SELECT = "project_id, network_id, name, color, sort, archived, created_at, parent_id";
+/** 子项目最多 3 层（顶层=1）。再深的话「项目」这个词就没有意义了，也没人能在选择器里点对。 */
+const PROJECT_MAX_DEPTH = 3;
+const projectPublic = (row: ProjectRow) => ({ id: row.project_id, name: row.name, color: row.color, sort: row.sort, archived: !!row.archived, createdAt: row.created_at, parentId: row.parent_id ?? null });
 const projectName = (raw: unknown): string | null => {
   if (typeof raw !== "string") return null;
   const name = raw.replace(/[\r\n\t]+/g, " ").trim();
@@ -361,6 +363,50 @@ const projectName = (raw: unknown): string | null => {
 function projectNameTaken(networkId: string, name: string, except?: string): boolean {
   return !!db.get("SELECT 1 FROM requirement_projects WHERE network_id = ?1 AND name = ?2 AND archived = 0 AND project_id != ?3", networkId, name, except ?? "");
 }
+/** 这个项目往上数有几层（自己算第一层）。用于深度上限与环路判断。 */
+function projectDepth(projectId: string): number {
+  let depth = 0;
+  let cur: string | null = projectId;
+  const seen = new Set<string>();
+  while (cur && depth < 64) {
+    if (seen.has(cur)) return Number.POSITIVE_INFINITY;  // 循环：当成超深，调用方会拒绝
+    seen.add(cur);
+    depth++;
+    const row: { parent_id: string | null } | null = db.get("SELECT parent_id FROM requirement_projects WHERE project_id = ?1", cur);
+    cur = row?.parent_id ?? null;
+  }
+  return depth;
+}
+
+/**
+ * 校验 parent_id（新项目或搬家时）。返回 { parent } 或错误码。
+ * 规则：同一网络、存在、未归档、不是自己或自己的后代、加进来后不超过 PROJECT_MAX_DEPTH。
+ */
+function validateProjectParent(
+  networkId: string, parentId: string, selfId: string | null,
+): { ok: true; parent: ProjectRow } | { ok: false; error: string } {
+  const parent = db.get<ProjectRow>(`SELECT ${PROJECT_SELECT} FROM requirement_projects WHERE project_id = ?1`, parentId);
+  if (!parent || parent.network_id !== networkId) return { ok: false, error: "project_parent_not_found" };
+  if (parent.archived) return { ok: false, error: "project_parent_archived" };
+  if (selfId) {
+    if (parent.project_id === selfId) return { ok: false, error: "project_parent_cycle" };
+    // 把 A 挂到 A 的后代下面 = 环。沿 parent 链往上走，遇到自己就拒绝。
+    let cur: string | null = parent.parent_id ?? null;
+    const seen = new Set<string>();
+    while (cur && !seen.has(cur)) {
+      if (cur === selfId) return { ok: false, error: "project_parent_cycle" };
+      seen.add(cur);
+      cur = db.get<{ parent_id: string | null }>("SELECT parent_id FROM requirement_projects WHERE project_id = ?1", cur)?.parent_id ?? null;
+    }
+    if (projectDepth(selfId) + projectDepth(parent.project_id) > PROJECT_MAX_DEPTH) {
+      return { ok: false, error: "project_parent_too_deep" };
+    }
+  } else if (projectDepth(parent.project_id) + 1 > PROJECT_MAX_DEPTH) {
+    return { ok: false, error: "project_parent_too_deep" };
+  }
+  return { ok: true, parent };
+}
+
 /** 卡片上的 project_id:null 清空;字符串必须是同一网络、未归档的项目。 */
 function projectRef(value: unknown, networkId: string): string | null {
   if (value === null) return null;
@@ -405,13 +451,24 @@ async function handleProjects(ctx: RequirementsRequestContext): Promise<Response
     const sort = body.sort === undefined ? count : body.sort;
     if (!Number.isInteger(sort)) return jsonError("invalid_project_sort", 400);
     const id = `proj_${crypto.randomUUID()}`;
-    db.run(`INSERT INTO requirement_projects (${PROJECT_SELECT}) VALUES (?1, ?2, ?3, ?4, ?5, 0, ?6)`, [id, networkId, name, color, sort, new Date().toISOString()]);
+    // 子项目：parent_id 可选；null/缺省 = 顶层。
+    let parentId: string | null = null;
+    if (body.parent_id !== undefined && body.parent_id !== null && body.parent_id !== "") {
+      if (typeof body.parent_id !== "string") return jsonError("invalid_project_parent", 400);
+      const check = validateProjectParent(networkId, body.parent_id, null);
+      if (!check.ok) return jsonError(check.error, check.error === "project_parent_not_found" ? 404 : 400);
+      parentId = check.parent.project_id;
+    }
+    db.run(`INSERT INTO requirement_projects (${PROJECT_SELECT}) VALUES (?1, ?2, ?3, ?4, ?5, 0, ?6, ?7)`, [id, networkId, name, color, sort, new Date().toISOString(), parentId]);
     return Response.json({ ok: true, project: projectPublic(db.get<ProjectRow>(`SELECT ${PROJECT_SELECT} FROM requirement_projects WHERE project_id = ?1`, id)!) }, { status: 201 });
   }
   if (!one) return jsonError("not_found", 404);
   const current = db.get<ProjectRow>(`SELECT ${PROJECT_SELECT} FROM requirement_projects WHERE project_id = ?1`, decodeURIComponent(one[1]));
   if (!current || current.network_id !== networkId) return jsonError("project_not_found", 404);
   if (req.method === "DELETE") {
+    // 子项目不能凭空变孤儿：先搬走或删掉它们（明确拒绝，不偷偷改层级）。
+    const kids = db.get<{ n: number }>("SELECT COUNT(*) AS n FROM requirement_projects WHERE parent_id = ?1", current.project_id)?.n ?? 0;
+    if (kids > 0) return jsonError("project_has_children", 409);
     // 先把卡片上的引用置空,再删项目:卡片一张不少。
     // updated_at 跟着动:按 updated_since 增量同步的客户端要看得见「项目被清空」这一改动。
     // 每张被清空项目的卡记一条「项目 X → 无」(与清空同一个事务)。
@@ -445,8 +502,20 @@ async function handleProjects(ctx: RequirementsRequestContext): Promise<Response
     if (typeof body.archived !== "boolean") return jsonError("invalid_project_archived", 400);
     archived = body.archived ? 1 : 0;
   }
+  let parentId: string | null = current.parent_id ?? null;
+  if ("parent_id" in body) {
+    if (body.parent_id === null || body.parent_id === "") {
+      parentId = null;                                    // 变成顶层
+    } else if (typeof body.parent_id !== "string") {
+      return jsonError("invalid_project_parent", 400);
+    } else {
+      const check = validateProjectParent(networkId, body.parent_id, current.project_id);
+      if (!check.ok) return jsonError(check.error, check.error === "project_parent_not_found" ? 404 : 400);
+      parentId = check.parent.project_id;
+    }
+  }
   if (!archived && projectNameTaken(networkId, name, current.project_id)) return jsonError("project_name_taken", 409);
-  db.run("UPDATE requirement_projects SET name = ?1, color = ?2, sort = ?3, archived = ?4 WHERE project_id = ?5", [name, color, sort, archived, current.project_id]);
+  db.run("UPDATE requirement_projects SET name = ?1, color = ?2, sort = ?3, archived = ?4, parent_id = ?6 WHERE project_id = ?5", [name, color, sort, archived, current.project_id, parentId]);
   return Response.json({ ok: true, project: projectPublic(db.get<ProjectRow>(`SELECT ${PROJECT_SELECT} FROM requirement_projects WHERE project_id = ?1`, current.project_id)!) });
 }
 

package/src/tools.ts

@@ -4104,7 +4104,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "tail_node_logs",
-    "Ask a node for the tail of its own agent-node run log (read-only, redacted on the node before it leaves). No path argument: the node reads only its own log directory. User logins only; the node's owner or a network owner/admin. Poll get_rules_file_result — content is JSON {files, lines:[{ts, level, text, key}], truncated, matched, now_ts}; it is handed out once and then purged.",
+    "Tail of a node's own agent-node run log (read-only, redacted on the node). No path argument: it reads only its own log directory. User logins only (node owner or network owner/admin). Poll get_rules_file_result; JSON {files, lines, truncated, matched}; handed out once, then purged.",
     {
       ...NODE_ID_ALIAS_FIELDS,
       alias: z.string().min(1).max(200).optional().describe("Alias instead of node_id (a node, or a session reporting logs_capable)."),
@@ -6916,7 +6916,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "projects_list",
-    "List requirement projects in your network (id, name, color, sort, archived). Node (Agent) tokens can only read projects; creating / changing them (projects_create / projects_update) needs a person's token.",
+    "List requirement projects (id, name, color, sort, archived, parentId). node tokens can only read projects; creating / changing needs a person's token (projects_create / projects_update).",
     { network_id: z.string().max(200).optional() },
     async ({ network_id }) => requirementsCall("GET", "/api/requirements/projects", network_id),
   );
@@ -6926,19 +6926,20 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   // write access and is refused to 「仅相关任务」(task-scoped) members; events use the task list's visibility.
   server.tool(
     "projects_create",
-    "Create a requirement project in your network (same as 管理项目 → 新建 in the app). name 1–40 characters, unique in the network; color #RRGGBB (default: next palette colour); sort integer. Returns { project }. Needs a person's token: node (Agent) tokens can only read projects (403 user_token_required). Also refused (403) for task-scoped members and read-only roles.",
+    "Create a requirement project (管理项目 → 新建). name 1–40, unique; color #RRGGBB; sort int; parent_id optional (≤3 levels). Returns { project }. node tokens can only read projects (403 user_token_required); task-scoped / read-only members are refused.",
     {
       network_id: z.string().max(200).optional(),
       name: z.string().min(1).max(40),
       color: z.string().regex(/^#[0-9a-fA-F]{6}$/).optional(),
       sort: z.number().int().optional(),
+      parent_id: z.string().max(200).nullable().optional(),
     },
-    async (args) => requirementsCall("POST", "/api/requirements/projects", args.network_id, pick(args, ["name", "color", "sort"])),
+    async (args) => requirementsCall("POST", "/api/requirements/projects", args.network_id, pick(args, ["name", "color", "sort", "parent_id"])),
   );
 
   server.tool(
     "projects_update",
-    "Rename, recolour, reorder, archive or unarchive a requirement project (same as 管理项目 in the app). Only the fields you pass change. archived=true hides it from pickers (its tasks keep project_id); archived=false brings it back. Returns { project }. Needs a person's token: node (Agent) tokens can only read projects (403 user_token_required). Also refused (403) for task-scoped members and read-only roles.",
+    "Rename, recolour, reorder, archive/unarchive, or move a project under another (parent_id; null = top level, cycles / depth>3 refused). Only the fields you pass change; archived hides it from pickers. Returns { project }. node tokens can only read projects (403); task-scoped / read-only members refused.",
     {
       network_id: z.string().max(200).optional(),
       id: z.string().min(1).max(200).describe("project id (proj_…), from projects_list"),
@@ -6946,8 +6947,9 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       color: z.string().regex(/^#[0-9a-fA-F]{6}$/).optional(),
       sort: z.number().int().optional(),
       archived: z.boolean().optional(),
+      parent_id: z.string().max(200).nullable().optional(),
     },
-    async (args) => requirementsCall("PATCH", `/api/requirements/projects/${encodeURIComponent(args.id)}`, args.network_id, pick(args, ["name", "color", "sort", "archived"])),
+    async (args) => requirementsCall("PATCH", `/api/requirements/projects/${encodeURIComponent(args.id)}`, args.network_id, pick(args, ["name", "color", "sort", "archived", "parent_id"])),
   );
 
   // #476 —— 不带 requirement_id 的全网动态默认 50 条(REST 默认 200 不变,App 走 REST);严格参数同 #471。