@whispering233/ai-editor-db 0.0.1

package/dist/queries/outline-ops.js

@@ -0,0 +1,346 @@
+// @whispering233/ai-editor-db 大纲树操作（S2.1）：创建/更新/移动/软删/还原/物理删除/回收站列表/章节序
+//
+// 单一事实来源：
+// - doc/design/decisions.md 决策 19（严格三层：volume 挂 root、chapter 挂 volume 或 root、
+//   scene 必须挂 chapter；创建必须显式 parent_id；无游离节点；节点 updated_at 版本戳）、
+//   决策 12（软删 deleted/deleted_at、级联软删子树、restore 祖先链校验 409）、
+//   决策 21（章节序：root → 卷 → 章先序遍历，全局章序号跨卷连续，scene 归入所属章）
+// - doc/api/endpoints.md 第 550-736 行（大纲操作与回收站端点语义）
+// - doc/database/schema.md 第 123-155 行（outline.json 契约）
+//
+// 风格：本模块为「读树 → 操作 → 原子写回」一体化（dir 语义），内部复用 storage/outline.ts
+// 的内存操作（readOutlineFile/writeOutlineFile/findOutlineNode/touch/update/getOutlinePathIds）；
+// relations/deltas 的级联软删由上层（S2.2 路由层）组合 relation/delta 模块完成——本模块
+// 只处理 outline.json 侧（任务卡边界）。
+//
+// 错误约定：抛 OutlineError（带 code），server 层 catch 映射 HttpError：
+//   NODE_NOT_FOUND             → 404 OUTLINE_NODE_NOT_FOUND
+//   PARENT_NOT_FOUND           → 400 OUTLINE_NODE_NOT_FOUND（父不存在是请求参数错误——
+//                                S2.2 实际映射为 400，2026-08 审核同步注释）
+//   INVALID_HIERARCHY          → 400 VALIDATION_ERROR（严格三层违反，决策 19）
+//   OUTLINE_ANCESTOR_DELETED   → 409 OUTLINE_ANCESTOR_DELETED（决策 12 修订）
+import { generateOutlineNodeId } from "@whispering233/ai-editor-shared";
+import { findOutlineNode, getOutlinePathIds, readOutlineFile, writeOutlineFile, } from "../storage/outline.js";
+/** 大纲操作错误：带 code，供上层精确映射 HTTP 语义（替代 message 字符串匹配） */
+export class OutlineError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "OutlineError";
+        this.code = code;
+    }
+}
+/** 取节点 children 的可变引用（卷→章、章→场景；场景返回 undefined） */
+function childrenOf(node) {
+    return node.children;
+}
+/**
+ * 严格三层约束校验（决策 19）：childType 能否挂 parentType 下。
+ * volume → root；chapter → volume 或 root；scene → 必须 chapter。
+ */
+export function assertCanHold(parentType, childType) {
+    const ok = (parentType === "root" && (childType === "volume" || childType === "chapter")) ||
+        (parentType === "volume" && childType === "chapter") ||
+        (parentType === "chapter" && childType === "scene");
+    if (!ok) {
+        throw new OutlineError("INVALID_HIERARCHY", `层级非法（决策 19 严格三层）: ${childType} 不能挂在 ${parentType} 下`);
+    }
+}
+/**
+ * 创建大纲节点（POST /api/v1/outline，endpoints.md 第 550-577 行）：
+ * 读树 → 校验父存在 + 三层约束 → 生成 id（shared generateOutlineNodeId：vol-/ch-/sc- 前缀）
+ * → 插入父 children 尾部 → **父节点 updated_at 统一更新**（决策 19）→ 原子写回。
+ *
+ * @param updatedAt ISO 8601 由调用方（应用层）传入，模块不生成时间
+ * @param data 节点结构化信息（决策 23，可选；校验由路由层按层级 schema 执行，本模块仅透传存储）
+ * @returns 新建节点（含 id/type/title/updated_at/data）
+ * @throws OutlineError PARENT_NOT_FOUND（父不存在）/ INVALID_HIERARCHY（三层违反）
+ */
+export function createOutlineNode(dir, input) {
+    const tree = readOutlineFile(dir);
+    const parent = input.parentId === "root" ? tree : findOutlineNode(tree, input.parentId);
+    if (parent === undefined) {
+        throw new OutlineError("PARENT_NOT_FOUND", `父节点不存在: ${input.parentId}`);
+    }
+    assertCanHold(parent.type, input.type);
+    const node = {
+        id: generateOutlineNodeId(input.type),
+        type: input.type,
+        title: input.title,
+        updated_at: input.updatedAt,
+        ...(input.summary !== undefined ? { summary: input.summary } : {}),
+        ...(input.data !== undefined ? { data: input.data } : {}),
+        // 非 scene 节点必须初始化 children 数组（volume→chapter[]、chapter→scene[]），
+        // 否则 childrenOf 视为叶子、后续挂载失败
+        ...(input.type !== "scene" ? { children: [] } : {}),
+    };
+    const kids = childrenOf(parent);
+    if (kids === undefined) {
+        throw new OutlineError("INVALID_HIERARCHY", `父节点是叶子（scene），无法挂子节点: ${input.parentId}`);
+    }
+    kids.push(node);
+    // 父节点版本戳（决策 19：children 变更由服务端原子写时统一更新）。
+    // root 是树根非节点（schema.md 顶层契约仅 id/type/schema_version/children），
+    // 不写 updated_at——版本戳只适用于节点（oracle 审核修复）
+    if (parent !== tree) {
+        parent.updated_at = input.updatedAt;
+    }
+    writeOutlineFile(dir, tree);
+    return node;
+}
+/**
+ * 更新大纲节点信息（PUT /api/v1/outline/:nodeId，endpoints.md 第 579-597 行）：
+ * title/summary 更新 + 节点 updated_at 统一更新（决策 19），原子写回；
+ * data **浅合并**（决策 23：未传字段保留，与实体 updateEntity 的 data 浅合并同语义）。
+ * @throws OutlineError NODE_NOT_FOUND
+ */
+export function updateOutlineNodeInfo(dir, nodeId, patch, updatedAt) {
+    const tree = readOutlineFile(dir);
+    const node = findOutlineNode(tree, nodeId);
+    if (node === undefined) {
+        throw new OutlineError("NODE_NOT_FOUND", `大纲节点不存在: ${nodeId}`);
+    }
+    if (patch.title !== undefined)
+        node.title = patch.title;
+    if (patch.summary !== undefined)
+        node.summary = patch.summary;
+    // data 浅合并：仅合并传入字段，现有字段保留（决策 23；与 updateEntity 同语义）
+    if (patch.data !== undefined) {
+        node.data = { ...(node.data ?? {}), ...patch.data };
+    }
+    node.updated_at = updatedAt;
+    writeOutlineFile(dir, tree);
+}
+/** 在树中找 nodeId 的直接父（返回树根或节点引用）；不在树中返回 undefined */
+function findParentOf(tree, nodeId) {
+    for (const child of tree.children) {
+        if (child.id === nodeId)
+            return tree;
+        const found = findParentRecursive(child, nodeId);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+function findParentRecursive(node, nodeId) {
+    for (const child of childrenOf(node) ?? []) {
+        if (child.id === nodeId)
+            return node;
+        const found = findParentRecursive(child, nodeId);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+/**
+ * 移动大纲节点（PUT /api/v1/outline/:nodeId/move，endpoints.md 第 599-621 行）：
+ * 从原父移除 → 插入新父指定 order（0-based；同父重排 = 移除后插入）→
+ * 三层约束校验（同 create）→ 新旧父 updated_at 统一更新（决策 19）→ 原子写回。
+ * order 越界时 clamp 到有效范围（拖拽场景边界值，宽松处理）。
+ *
+ * @returns { previousParentId, newParentId }（endpoints.md 语义；root 用 "root"）
+ * @throws OutlineError NODE_NOT_FOUND / PARENT_NOT_FOUND / INVALID_HIERARCHY
+ */
+export function moveOutlineNode(dir, nodeId, input, updatedAt) {
+    const tree = readOutlineFile(dir);
+    const node = findOutlineNode(tree, nodeId);
+    if (node === undefined) {
+        throw new OutlineError("NODE_NOT_FOUND", `大纲节点不存在: ${nodeId}`);
+    }
+    const prevParent = findParentOf(tree, nodeId);
+    if (prevParent === undefined) {
+        throw new OutlineError("NODE_NOT_FOUND", `大纲节点不存在: ${nodeId}`);
+    }
+    const newParent = input.parentId === "root" ? tree : findOutlineNode(tree, input.parentId);
+    if (newParent === undefined) {
+        throw new OutlineError("PARENT_NOT_FOUND", `父节点不存在: ${input.parentId}`);
+    }
+    assertCanHold(newParent.type, node.type);
+    // 从原父移除
+    const prevKids = childrenOf(prevParent);
+    const idx = prevKids?.indexOf(node) ?? -1;
+    if (idx < 0) {
+        throw new OutlineError("NODE_NOT_FOUND", `大纲节点不在父节点 children 中: ${nodeId}`);
+    }
+    prevKids.splice(idx, 1);
+    // 插入新父指定位置（order clamp 到 [0, len]）
+    const newKids = childrenOf(newParent);
+    if (newKids === undefined) {
+        throw new OutlineError("INVALID_HIERARCHY", `新父节点是叶子（scene）: ${input.parentId}`);
+    }
+    const order = Math.max(0, Math.min(Math.trunc(input.order), newKids.length));
+    newKids.splice(order, 0, node);
+    // 新旧父版本戳（决策 19）；同父时只更新一次。
+    // root 是树根非节点，不写 updated_at（schema.md 顶层契约，oracle 审核修复）
+    if (prevParent !== tree) {
+        prevParent.updated_at = updatedAt;
+    }
+    if (newParent !== prevParent && newParent !== tree) {
+        newParent.updated_at = updatedAt;
+    }
+    writeOutlineFile(dir, tree);
+    return {
+        previousParentId: prevParent.type === "root" ? "root" : prevParent.id,
+        newParentId: newParent.type === "root" ? "root" : newParent.id,
+    };
+}
+/** 递归软删子树（决策 12 级联）：标记 deleted + deleted_at + updated_at，返回子节点数 */
+function softDeleteSubtree(node, deletedAt) {
+    let count = 0;
+    for (const child of childrenOf(node) ?? []) {
+        count += 1 + softDeleteSubtree(child, deletedAt);
+        child.deleted = true;
+        child.deleted_at = deletedAt;
+        child.updated_at = deletedAt;
+    }
+    return count;
+}
+/**
+ * 软删大纲节点（DELETE /api/v1/outline/:nodeId，endpoints.md 第 623-640 行，决策 12）：
+ * 标记 deleted + deleted_at，**递归软删整棵子树**（本体保留可还原）。
+ * 已软删节点再次软删：幂等重标（不报错）。
+ *
+ * @returns { children } 级联软删的子节点数（不含自身）
+ *   —— relations/deltas 的级联软删由上层（S2.2）组合 relation/delta 模块处理（本模块边界）
+ * @throws OutlineError NODE_NOT_FOUND
+ */
+export function deleteOutlineNode(dir, nodeId, updatedAt) {
+    const tree = readOutlineFile(dir);
+    const node = findOutlineNode(tree, nodeId);
+    if (node === undefined) {
+        throw new OutlineError("NODE_NOT_FOUND", `大纲节点不存在: ${nodeId}`);
+    }
+    const children = softDeleteSubtree(node, updatedAt);
+    node.deleted = true;
+    node.deleted_at = updatedAt;
+    node.updated_at = updatedAt;
+    writeOutlineFile(dir, tree);
+    return { children };
+}
+/** 递归还原子树（决策 12 修订：子节点若仍在回收站则一并还原），返回还原的子节点数 */
+function restoreSubtree(node, updatedAt) {
+    let count = 0;
+    for (const child of childrenOf(node) ?? []) {
+        count += 1 + restoreSubtree(child, updatedAt);
+        delete child.deleted;
+        delete child.deleted_at;
+        child.updated_at = updatedAt;
+    }
+    return count;
+}
+/**
+ * 还原软删大纲节点（POST /api/v1/trash/outline/:nodeId/restore，endpoints.md 第 694-711 行）：
+ * 清除 deleted/deleted_at → **递归还原子树**（仍软删的子孙一并还原，决策 12 修订）→
+ * **祖先链校验**：存在软删祖先 → 抛 OUTLINE_ANCESTOR_DELETED（409 语义，决策 12 修订，
+ * 杜绝「可见节点挂在不可见父」的畸形树——校验在还原前执行，祖先必须已还原）。
+ *
+ * @returns { children } 级联还原的子节点数
+ * @throws OutlineError NODE_NOT_FOUND / OUTLINE_ANCESTOR_DELETED
+ */
+export function restoreOutlineNode(dir, nodeId, updatedAt) {
+    const tree = readOutlineFile(dir);
+    const node = findOutlineNode(tree, nodeId);
+    if (node === undefined) {
+        throw new OutlineError("NODE_NOT_FOUND", `大纲节点不存在: ${nodeId}`);
+    }
+    // 祖先链校验（决策 12 修订）：路径 [root, ..., nodeId] 中排除 root 与自身的中间祖先
+    const path = getOutlinePathIds(tree, nodeId);
+    for (const ancestorId of path.slice(1, -1)) {
+        const ancestor = findOutlineNode(tree, ancestorId);
+        if (ancestor?.deleted === true) {
+            throw new OutlineError("OUTLINE_ANCESTOR_DELETED", `存在软删祖先 ${ancestorId}，请先还原祖先再还原本节点`);
+        }
+    }
+    const children = restoreSubtree(node, updatedAt);
+    delete node.deleted;
+    delete node.deleted_at;
+    node.updated_at = updatedAt;
+    writeOutlineFile(dir, tree);
+    return { children };
+}
+/**
+ * 物理删除大纲节点（DELETE /api/v1/trash/outline/:nodeId，endpoints.md 第 726-736 行）：
+ * 从树中移除整棵子树（递归，文件内物理清除，不可恢复）。
+ * 边界：不涉及 data.db（relations/deltas 的物理清除由上层组合）；
+ * 不更新父节点 updated_at——purge 属回收站清理，节点已消失，
+ * 基于它的提案快照必然失效（节点不存在），父版本戳无需联动。
+ * @throws OutlineError NODE_NOT_FOUND
+ */
+export function purgeOutlineNode(dir, nodeId) {
+    const tree = readOutlineFile(dir);
+    const parent = findParentOf(tree, nodeId);
+    if (parent === undefined) {
+        throw new OutlineError("NODE_NOT_FOUND", `大纲节点不存在: ${nodeId}`);
+    }
+    const kids = childrenOf(parent);
+    const idx = kids.findIndex((n) => n.id === nodeId);
+    if (idx < 0) {
+        throw new OutlineError("NODE_NOT_FOUND", `大纲节点不在父节点 children 中: ${nodeId}`);
+    }
+    kids.splice(idx, 1);
+    writeOutlineFile(dir, tree);
+}
+/**
+ * 回收站列表（大纲侧）：收集整棵树中 deleted 标记的节点（含子树中的软删节点），
+ * 按 deleted_at 倒序（回收站排序约定，schema.md：跨 SQLite 与 outline.json 统一 ISO 格式）。
+ */
+export function listDeletedNodes(dir) {
+    const tree = readOutlineFile(dir);
+    const out = [];
+    const visit = (node) => {
+        if (node.deleted === true && node.deleted_at !== undefined) {
+            out.push({ id: node.id, type: node.type, title: node.title, deleted_at: node.deleted_at });
+        }
+        for (const child of childrenOf(node) ?? [])
+            visit(child);
+    };
+    for (const child of tree.children)
+        visit(child);
+    return out.sort((a, b) => b.deleted_at.localeCompare(a.deleted_at));
+}
+/**
+ * 章节序推导（决策 21）：按大纲树先序遍历编号——root → 卷 → 章；
+ * 全局章序号**跨卷连续**；直接挂 root 的 chapter 按兄弟顺序编号（决策 19 允许）；
+ * scene 归入所属章，不单独编号（见 getChapterNumber）。
+ */
+export function deriveChapterOrder(dir) {
+    const tree = readOutlineFile(dir);
+    const result = [];
+    let number = 0;
+    // root.children 类型已放宽为 (volume|chapter) 联合（决策 19 允许 chapter 直挂 root，
+    // oracle 回修 shared 类型后此处无需断言），按 type 分支：volume → 卷内章；chapter → 直挂章
+    for (const child of tree.children) {
+        if (child.type === "chapter") {
+            result.push({ chapterId: child.id, chapterNumber: ++number });
+        }
+        else {
+            for (const ch of childrenOf(child) ?? []) {
+                result.push({ chapterId: ch.id, chapterNumber: ++number });
+            }
+        }
+    }
+    return result;
+}
+/**
+ * 节点所属章序号（决策 21）：
+ * - scene → 所属 chapter 的全局序号（严格三层下 scene 的父必为 chapter）
+ * - chapter → 自身序号
+ * - volume / root / 节点不存在 → null（卷无章节号；不存在防御性返回 null 供上层展示）
+ */
+export function getChapterNumber(dir, nodeId) {
+    const tree = readOutlineFile(dir);
+    let path;
+    try {
+        path = getOutlinePathIds(tree, nodeId);
+    }
+    catch {
+        return null; // 节点不存在（防御，伏笔指标/展示场景不因脏引用崩）
+    }
+    // 路径上最后一个 chapter（scene 的父 或 自身）
+    const chapterId = [...path].reverse().find((id) => findOutlineNode(tree, id)?.type === "chapter");
+    if (chapterId === undefined)
+        return null;
+    const order = deriveChapterOrder(dir).find((c) => c.chapterId === chapterId);
+    return order ?? null;
+}
+//# sourceMappingURL=outline-ops.js.map

package/dist/queries/outline-ops.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outline-ops.js","sourceRoot":"","sources":["../../src/queries/outline-ops.ts"],"names":[],"mappings":"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"}

package/dist/queries/outline.d.ts

@@ -0,0 +1,48 @@
+import type { OutlineFileNode, OutlineFileTree, OutlineFileVolume } from "@ai-editor/shared";
+/** outline.json 文件名（与 project.json / data.db 并列的项目数据文件，schema.md 第 3-14 行） */
+export declare const OUTLINE_FILE_NAME = "outline.json";
+/** 大纲节点或树根的公共形态（findOutlineNode 的 parent 引用用） */
+export type OutlineParent = OutlineFileTree | OutlineFileNode;
+/**
+ * 轻量结构校验：是否为合法 OutlineFileTree（根 id/type、schema_version、children 数组）。
+ * shared 未提供 file 形态的校验函数（T1.3 只做字段映射），此处守卫 root 级形状即可，
+ * 节点级字段由写入方（服务端）保证。
+ */
+export declare function isOutlineFileTree(value: unknown): value is OutlineFileTree;
+/**
+ * 读取 outline.json：文件不存在返回 null（由调用方决定初始化，如 initOutlineFile）；
+ * 文件存在但结构非法则抛错（不静默吞坏数据）。
+ */
+export declare function loadOutlineFile(dir: string): OutlineFileTree | null;
+/**
+ * 原子写 outline.json（决策 11：临时文件 + fsync + rename）。
+ * 禁止直接覆盖原文件。
+ */
+export declare function saveOutlineFile(dir: string, tree: OutlineFileTree): void;
+/**
+ * 首次初始化：创建空根树（决策 19：严格三层 root → volume → chapter → scene，无游离节点）
+ * 并原子写入；顶层 schema_version 与 project.json / data.db 的 user_version 同步（决策 13）。
+ */
+export declare function initOutlineFile(dir: string): OutlineFileTree;
+/**
+ * 递归查找节点：返回 { node, parent }（parent 为直接父引用，root 的子节点 parent 为树根）。
+ * 未找到返回 null。供 updateOutlineNode 与后续大纲操作（T2.7 移动/删除）复用。
+ */
+export declare function findOutlineNode(tree: OutlineFileTree, id: string): {
+    node: OutlineFileNode;
+    parent: OutlineParent | null;
+} | null;
+/**
+ * 根到节点的路径 id 数组（含树根 "root" 与节点自身），如 ["root", "vol-1", "ch-1", "sc-1"]。
+ * 未找到返回 null。T2.7 大纲操作（移动/删除的祖先链校验）复用。
+ */
+export declare function getNodePathIds(tree: OutlineFileTree, id: string): string[] | null;
+/**
+ * 更新大纲节点：读树 → 定位节点 → 应用 updater 修改 → 统一更新该节点 updated_at（决策 19：
+ * 节点任何字段变更——title/summary/children 重排——都在原子写流程中刷新版本戳）→ 原子写回。
+ * 返回更新后的整树。outline.json 不存在或节点未找到则抛错。
+ */
+export declare function updateOutlineNode(dir: string, nodeId: string, updater: (node: OutlineFileNode) => void): OutlineFileTree;
+/** 便捷类型导出：卷节点（T2.7 移动操作等会用到） */
+export type { OutlineFileVolume };
+//# sourceMappingURL=outline.d.ts.map

package/dist/queries/outline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outline.d.ts","sourceRoot":"","sources":["../../src/queries/outline.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAI7F,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,iBAAiB,CAAC;AAEhD,iDAAiD;AACjD,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG,eAAe,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAM1E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAUnE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,IAAI,CAExE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAS5D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,eAAe,EACrB,EAAE,EAAE,MAAM,GACT;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,CAQhE;AAuBD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAMjF;AAiBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,GACvC,eAAe,CAajB;AAED,gCAAgC;AAChC,YAAY,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/queries/outline.js

@@ -0,0 +1,134 @@
+// @ai-editor/db 大纲 JSON 存储（outline.json，T2.2）
+//
+// 契约来源：doc/database/schema.md（outline.json 第 123-155 行）、决策 11（原子写）、决策 19（节点版本戳）。
+// 存储形态为 OutlineFileTree（snake_case，shared 定义）；API 形态转换（mapOutlineFileToTree 等）在
+// shared/utils/mapping.ts，由上层（server）在返回前调用，本模块只做文件形态的读写与节点操作。
+//
+// 时间约定：节点 updated_at 由本模块在原子写流程中统一更新（决策 19），应用层写入 ISO 8601。
+import { join } from "node:path";
+import { SCHEMA_VERSION } from "../schema";
+import { readJsonFile, writeJsonAtomic } from "./atomic";
+/** outline.json 文件名（与 project.json / data.db 并列的项目数据文件，schema.md 第 3-14 行） */
+export const OUTLINE_FILE_NAME = "outline.json";
+/**
+ * 轻量结构校验：是否为合法 OutlineFileTree（根 id/type、schema_version、children 数组）。
+ * shared 未提供 file 形态的校验函数（T1.3 只做字段映射），此处守卫 root 级形状即可，
+ * 节点级字段由写入方（服务端）保证。
+ */
+export function isOutlineFileTree(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const v = value;
+    return v.id === "root" && v.type === "root" && typeof v.schema_version === "number" && Array.isArray(v.children);
+}
+/**
+ * 读取 outline.json：文件不存在返回 null（由调用方决定初始化，如 initOutlineFile）；
+ * 文件存在但结构非法则抛错（不静默吞坏数据）。
+ */
+export function loadOutlineFile(dir) {
+    const filePath = join(dir, OUTLINE_FILE_NAME);
+    const raw = readJsonFile(filePath);
+    if (raw === null) {
+        return null;
+    }
+    if (!isOutlineFileTree(raw)) {
+        throw new Error(`loadOutlineFile: ${filePath} 结构非法（非 OutlineFileTree）`);
+    }
+    return raw;
+}
+/**
+ * 原子写 outline.json（决策 11：临时文件 + fsync + rename）。
+ * 禁止直接覆盖原文件。
+ */
+export function saveOutlineFile(dir, tree) {
+    writeJsonAtomic(join(dir, OUTLINE_FILE_NAME), tree);
+}
+/**
+ * 首次初始化：创建空根树（决策 19：严格三层 root → volume → chapter → scene，无游离节点）
+ * 并原子写入；顶层 schema_version 与 project.json / data.db 的 user_version 同步（决策 13）。
+ */
+export function initOutlineFile(dir) {
+    const tree = {
+        id: "root",
+        type: "root",
+        schema_version: SCHEMA_VERSION,
+        children: [],
+    };
+    saveOutlineFile(dir, tree);
+    return tree;
+}
+/**
+ * 递归查找节点：返回 { node, parent }（parent 为直接父引用，root 的子节点 parent 为树根）。
+ * 未找到返回 null。供 updateOutlineNode 与后续大纲操作（T2.7 移动/删除）复用。
+ */
+export function findOutlineNode(tree, id) {
+    for (const child of tree.children) {
+        const found = findNodeRecursive(child, id, tree);
+        if (found) {
+            return found;
+        }
+    }
+    return null;
+}
+/** findOutlineNode 的递归实现（scene 为叶子，无 children 分支） */
+function findNodeRecursive(node, id, parent) {
+    if (node.id === id) {
+        return { node, parent };
+    }
+    if (node.type === "scene") {
+        return null;
+    }
+    for (const child of node.children ?? []) {
+        const found = findNodeRecursive(child, id, node);
+        if (found) {
+            return found;
+        }
+    }
+    return null;
+}
+/**
+ * 根到节点的路径 id 数组（含树根 "root" 与节点自身），如 ["root", "vol-1", "ch-1", "sc-1"]。
+ * 未找到返回 null。T2.7 大纲操作（移动/删除的祖先链校验）复用。
+ */
+export function getNodePathIds(tree, id) {
+    const path = [];
+    if (collectPath(tree, id, path)) {
+        return path;
+    }
+    return null;
+}
+/** getNodePathIds 的递归实现：回溯式收集路径（先压栈，失败弹栈） */
+function collectPath(node, id, path) {
+    if (node.type === "scene") {
+        return false;
+    }
+    for (const child of node.children ?? []) {
+        path.push(child.id);
+        if (child.id === id || (child.type !== "scene" && collectPath(child, id, path))) {
+            return true;
+        }
+        path.pop();
+    }
+    return false;
+}
+/**
+ * 更新大纲节点：读树 → 定位节点 → 应用 updater 修改 → 统一更新该节点 updated_at（决策 19：
+ * 节点任何字段变更——title/summary/children 重排——都在原子写流程中刷新版本戳）→ 原子写回。
+ * 返回更新后的整树。outline.json 不存在或节点未找到则抛错。
+ */
+export function updateOutlineNode(dir, nodeId, updater) {
+    const tree = loadOutlineFile(dir);
+    if (!tree) {
+        throw new Error(`updateOutlineNode: ${join(dir, OUTLINE_FILE_NAME)} 不存在`);
+    }
+    const found = findOutlineNode(tree, nodeId);
+    if (!found) {
+        throw new Error(`updateOutlineNode: 未找到节点 ${nodeId}`);
+    }
+    updater(found.node);
+    found.node.updated_at = new Date().toISOString();
+    saveOutlineFile(dir, tree);
+    return tree;
+}
+//# sourceMappingURL=outline.js.map

package/dist/queries/outline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outline.js","sourceRoot":"","sources":["../../src/queries/outline.ts"],"names":[],"mappings":"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"}

package/dist/queries/project.d.ts

@@ -0,0 +1,21 @@
+import { type ProjectFileConfig, type ProjectLanguage } from "@ai-editor/shared";
+/** project.json 文件名 */
+export declare const PROJECT_FILE_NAME = "project.json";
+/** 读取 project.json：文件不存在返回 null（由调用方决定初始化） */
+export declare function loadProjectFile(dir: string): ProjectFileConfig | null;
+/** 原子写 project.json（决策 11：临时文件 + fsync + rename，与 outline.json 同款） */
+export declare function saveProjectFile(dir: string, config: ProjectFileConfig): void;
+/**
+ * 首次初始化 project.json（决策 8：自动创建，此后跨启动稳定）：
+ * - id：proj- 前缀 + nanoid（shared generateProjectId，跨启动稳定，画布布局 localStorage 隔离 key）
+ * - created_at / updated_at：ISO 8601 应用层写入（schema.md 第 16 行），初始两者相同
+ * - schema_version：与 outline.json 顶层 / data.db user_version 同步（决策 13）
+ * - current_position：null（未设置）
+ * 写入后返回配置对象（调用方持有即可，无需再读）。
+ */
+export declare function initProjectFile(dir: string, init: {
+    name: string;
+    language: ProjectLanguage;
+    prompt: string;
+}): ProjectFileConfig;
+//# sourceMappingURL=project.d.ts.map

package/dist/queries/project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../src/queries/project.ts"],"names":[],"mappings":"AAOA,OAAO,EAAqB,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAIpG,uBAAuB;AACvB,eAAO,MAAM,iBAAiB,iBAAiB,CAAC;AAEhD,8CAA8C;AAC9C,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAErE;AAED,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAE5E;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAChE,iBAAiB,CAcnB"}

package/dist/queries/project.js

@@ -0,0 +1,43 @@
+// @ai-editor/db 项目配置 JSON 存储（project.json，T2.2）
+//
+// 契约来源：doc/database/schema.md（project.json 第 157-186 行）、决策 8（首次初始化自动创建）、
+// 决策 11（同款原子写）、决策 13（schema_version 与 outline.json / data.db user_version 同步）。
+// 硬约束（决策 17）：DeepSeek API key 绝不写入本文件。
+import { join } from "node:path";
+import { generateProjectId } from "@ai-editor/shared";
+import { SCHEMA_VERSION } from "../schema";
+import { readJsonFile, writeJsonAtomic } from "./atomic";
+/** project.json 文件名 */
+export const PROJECT_FILE_NAME = "project.json";
+/** 读取 project.json：文件不存在返回 null（由调用方决定初始化） */
+export function loadProjectFile(dir) {
+    return readJsonFile(join(dir, PROJECT_FILE_NAME));
+}
+/** 原子写 project.json（决策 11：临时文件 + fsync + rename，与 outline.json 同款） */
+export function saveProjectFile(dir, config) {
+    writeJsonAtomic(join(dir, PROJECT_FILE_NAME), config);
+}
+/**
+ * 首次初始化 project.json（决策 8：自动创建，此后跨启动稳定）：
+ * - id：proj- 前缀 + nanoid（shared generateProjectId，跨启动稳定，画布布局 localStorage 隔离 key）
+ * - created_at / updated_at：ISO 8601 应用层写入（schema.md 第 16 行），初始两者相同
+ * - schema_version：与 outline.json 顶层 / data.db user_version 同步（决策 13）
+ * - current_position：null（未设置）
+ * 写入后返回配置对象（调用方持有即可，无需再读）。
+ */
+export function initProjectFile(dir, init) {
+    const now = new Date().toISOString();
+    const config = {
+        id: generateProjectId(),
+        name: init.name,
+        language: init.language,
+        prompt: init.prompt,
+        schema_version: SCHEMA_VERSION,
+        current_position: null,
+        created_at: now,
+        updated_at: now,
+    };
+    saveProjectFile(dir, config);
+    return config;
+}
+//# sourceMappingURL=project.js.map

package/dist/queries/project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../../src/queries/project.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,EAAE;AACF,yEAAyE;AACzE,+EAA+E;AAC/E,uCAAuC;AAEvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAgD,MAAM,mBAAmB,CAAC;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEzD,uBAAuB;AACvB,MAAM,CAAC,MAAM,iBAAiB,GAAG,cAAc,CAAC;AAEhD,8CAA8C;AAC9C,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,OAAO,YAAY,CAAoB,IAAI,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC;AACvE,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,MAAyB;IACpE,eAAe,CAAC,IAAI,CAAC,GAAG,EAAE,iBAAiB,CAAC,EAAE,MAAM,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,GAAW,EACX,IAAiE;IAEjE,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,MAAM,MAAM,GAAsB;QAChC,EAAE,EAAE,iBAAiB,EAAE;QACvB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,cAAc,EAAE,cAAc;QAC9B,gBAAgB,EAAE,IAAI;QACtB,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,GAAG;KAChB,CAAC;IACF,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,MAAM,CAAC;AAChB,CAAC"}