@whispering233/ai-editor-db 0.0.1

package/dist/storage/outline.js

@@ -0,0 +1,154 @@
+// @whispering233/ai-editor-db outline.json 存储模块（T2.2）
+//
+// 单一事实来源：doc/database/schema.md 第 123-155 行（outline.json 契约）——
+// 严格三层（卷→章→场景，决策 19）、节点携带 updated_at 版本戳、顶层 schema_version、
+// 软删字段 deleted/deleted_at（决策 12）。
+// 读接口返回 shared 存储形态 OutlineFileTree（snake_case），映射到 API 形态由
+// @whispering233/ai-editor-shared/utils 的 mapOutlineFileToTree 负责（本模块不映射）。
+import { join } from "node:path";
+import { SCHEMA_VERSION } from "../schema.js";
+import { readTextFileOrNull, writeJsonAtomic } from "./atomic.js";
+/** outline.json 文件名（决策 8：项目根目录） */
+export const OUTLINE_FILE_NAME = "outline.json";
+/** 最小空树：文件缺失时的返回值（见 readOutlineFile 注释） */
+const EMPTY_TREE = {
+    id: "root",
+    type: "root",
+    schema_version: SCHEMA_VERSION,
+    children: [],
+};
+/**
+ * 读取 outline.json。
+ *
+ * 缺失文件语义（本项目首次初始化即创建，决策 8）：**返回最小空树**而非抛错——
+ * 调用方（server 打开项目前的探测、初始化流程）无需为「文件还不存在」分支处理；
+ * 空树的 schema_version 取当前 SCHEMA_VERSION，与初始化流程写入的一致（决策 13）。
+ * 注意：返回的是新对象，调用方修改它不会影响后续读取。
+ *
+ * JSON 损坏 / 结构不符：**抛错**，不静默重建——静默覆盖会掩盖文件损坏并可能
+ * 丢弃用户数据，由上层决定提示用户还是重建。
+ * schema_version 数值与 SCHEMA_VERSION 不一致时**不在此校验**（决策 13：以
+ * data.db 的 user_version 为准判定重建，JSON 版本仅用于结构判断，由上层流程处理）。
+ *
+ * @param dir 项目根目录
+ * @throws 文件存在但 JSON 解析失败或顶层结构不符时抛出
+ */
+export function readOutlineFile(dir) {
+    const raw = readTextFileOrNull(join(dir, OUTLINE_FILE_NAME));
+    if (raw === null)
+        return { ...EMPTY_TREE, children: [] };
+    const parsed = JSON.parse(raw); // JSON 损坏抛 SyntaxError，不静默吞
+    return validateOutlineFile(parsed);
+}
+/**
+ * 校验 outline.json 顶层结构（读时校验，schema.md 契约）：
+ * 顶层必须是 { id:"root", type:"root", schema_version:number, children:[] }。
+ * 节点级字段（title/updated_at 等）不逐一校验——文件格式演进由 schema_version
+ * 判定（决策 13），此处只拦「完全不是大纲树」的脏数据。
+ */
+function validateOutlineFile(parsed) {
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        parsed.id !== "root" ||
+        parsed.type !== "root" ||
+        typeof parsed.schema_version !== "number" ||
+        !Array.isArray(parsed.children)) {
+        throw new Error("outline.json 顶层结构不符契约（需 {id:\"root\", type:\"root\", schema_version, children[]}）");
+    }
+    return parsed;
+}
+/**
+ * 原子写 outline.json（决策 11：临时文件 + fsync + rename，见 writeJsonAtomic）。
+ * 顶层 schema_version 随 tree.schema_version 原样写入——保持与 project.json
+ * 同步写入是调用方职责（决策 13 修订：两个文件用同一版本号常量）。
+ * 节点 updated_at 版本戳（决策 19）由调用方在变更后通过 touch/update 更新，
+ * 本函数不隐式修改树。
+ */
+export function writeOutlineFile(dir, tree) {
+    writeJsonAtomic(join(dir, OUTLINE_FILE_NAME), tree);
+}
+/**
+ * 按 id 递归查找节点（卷/章/场景，不匹配 root 自身）。
+ * @returns 找到的节点引用（修改它即修改树）；未找到返回 undefined
+ */
+export function findOutlineNode(tree, nodeId) {
+    return findInChildren(tree.children, nodeId);
+}
+/** 在节点数组内递归查找（children 可选，严格三层由 shared 类型约束） */
+function findInChildren(nodes, nodeId) {
+    for (const node of nodes) {
+        if (node.id === nodeId)
+            return node;
+        const children = nodeChildren(node);
+        if (children !== undefined) {
+            const found = findInChildren(children, nodeId);
+            if (found !== undefined)
+                return found;
+        }
+    }
+    return undefined;
+}
+/** 取节点的 children（卷→章、章→场景；场景为叶子返回 undefined） */
+function nodeChildren(node) {
+    return node.children;
+}
+/**
+ * 更新节点版本戳（决策 19：任何字段变更——含 children 重排、软删/还原——
+ * 由服务端原子写时统一更新 updated_at，支撑决策 14 提案快照比对）。
+ * 仅更新 updated_at，不改动其他字段；改 title/summary 用 updateOutlineNode。
+ *
+ * @param updatedAt ISO 8601，由调用方（应用层）传入，模块不生成时间
+ * @throws 节点不存在时抛错——静默忽略会掩盖「改了个不存在的节点」的调用方 bug
+ */
+export function touchOutlineNode(tree, nodeId, updatedAt) {
+    const node = findOutlineNode(tree, nodeId);
+    if (node === undefined) {
+        throw new Error(`touchOutlineNode: 大纲节点不存在 ${nodeId}`);
+    }
+    node.updated_at = updatedAt;
+}
+/**
+ * 更新节点字段并统一更新 updated_at 版本戳（决策 19）。
+ * 就地修改树（返回节点引用），调用方随后 writeOutlineFile 落盘；
+ * children 重排等无法用 patch 表达的变更请用 touchOutlineNode。
+ *
+ * @param updatedAt ISO 8601，由调用方（应用层）传入，模块不生成时间
+ * @returns 更新后的节点引用
+ * @throws 节点不存在时抛错
+ */
+export function updateOutlineNode(tree, nodeId, patch, updatedAt) {
+    const node = findOutlineNode(tree, nodeId);
+    if (node === undefined) {
+        throw new Error(`updateOutlineNode: 大纲节点不存在 ${nodeId}`);
+    }
+    Object.assign(node, patch);
+    node.updated_at = updatedAt;
+    return node;
+}
+/**
+ * 根 → 目标节点的路径 id 列表（含 root 与目标节点自身）。
+ * 供后续卡使用：章节序现推（决策 21）、computeState 树路径排序（决策 9，
+ * data-flow.md 第 50 行 getNodePathIds）。
+ *
+ * @throws 节点不存在时抛错（路径唯一是严格三层的推论，找不到即调用方 bug）
+ */
+export function getOutlinePathIds(tree, nodeId) {
+    const path = [tree.id];
+    if (findPath(tree.children, nodeId, path))
+        return path;
+    throw new Error(`getOutlinePathIds: 大纲节点不存在 ${nodeId}`);
+}
+/** 递归找路径：命中返回 true 且 path 已包含完整路径；未命中回溯 */
+function findPath(nodes, nodeId, path) {
+    for (const node of nodes) {
+        path.push(node.id);
+        if (node.id === nodeId)
+            return true;
+        const children = nodeChildren(node);
+        if (children !== undefined && findPath(children, nodeId, path))
+            return true;
+        path.pop();
+    }
+    return false;
+}
+//# sourceMappingURL=outline.js.map

package/dist/storage/outline.js.map

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

package/dist/storage/project.d.ts

@@ -0,0 +1,24 @@
+import type { ProjectFileConfig } from "@whispering233/ai-editor-shared";
+/** project.json 文件名（决策 8：项目根目录） */
+export declare const PROJECT_FILE_NAME = "project.json";
+/**
+ * 读取 project.json。
+ *
+ * 缺失文件语义：**返回 null**——project.json 是项目「是否已初始化」的判定文件
+ * （决策 8：首次初始化时自动创建），null 即未初始化，由上层决定创建流程；
+ * 与 readOutlineFile（缺失返回空树）语义不同：大纲空树可直接使用，项目配置
+ * 不存在则无法合成默认值（id 需生成、name 需取目录名，属初始化逻辑）。
+ *
+ * 文件存在但 JSON 损坏：**抛错**，不静默重建（同 readOutlineFile 的取舍）。
+ *
+ * @param dir 项目根目录
+ * @returns 项目配置；文件不存在返回 null
+ * @throws 文件存在但 JSON 解析失败或顶层结构不符契约时抛出
+ */
+export declare function readProjectFile(dir: string): ProjectFileConfig | null;
+/**
+ * 原子写 project.json（决策 11 同款流程：临时文件 + fsync + rename，schema.md 第 186 行）。
+ * schema_version 随 config 原样写入——与 outline.json 同步写入是调用方职责（决策 13 修订）。
+ */
+export declare function writeProjectFile(dir: string, config: ProjectFileConfig): void;
+//# sourceMappingURL=project.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../src/storage/project.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAGzE,mCAAmC;AACnC,eAAO,MAAM,iBAAiB,iBAAiB,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAIrE;AAuBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAE7E"}

package/dist/storage/project.js

@@ -0,0 +1,55 @@
+// @whispering233/ai-editor-db project.json 存储模块（T2.2）
+//
+// 单一事实来源：doc/database/schema.md 第 157-186 行（project.json 契约）——
+// id/name/language/prompt/schema_version/current_position/created_at/updated_at，
+// 文件写入走决策 11 原子写同款流程（第 186 行），DeepSeek key 绝不写入本文件（决策 17）。
+import { join } from "node:path";
+import { readTextFileOrNull, writeJsonAtomic } from "./atomic.js";
+/** project.json 文件名（决策 8：项目根目录） */
+export const PROJECT_FILE_NAME = "project.json";
+/**
+ * 读取 project.json。
+ *
+ * 缺失文件语义：**返回 null**——project.json 是项目「是否已初始化」的判定文件
+ * （决策 8：首次初始化时自动创建），null 即未初始化，由上层决定创建流程；
+ * 与 readOutlineFile（缺失返回空树）语义不同：大纲空树可直接使用，项目配置
+ * 不存在则无法合成默认值（id 需生成、name 需取目录名，属初始化逻辑）。
+ *
+ * 文件存在但 JSON 损坏：**抛错**，不静默重建（同 readOutlineFile 的取舍）。
+ *
+ * @param dir 项目根目录
+ * @returns 项目配置；文件不存在返回 null
+ * @throws 文件存在但 JSON 解析失败或顶层结构不符契约时抛出
+ */
+export function readProjectFile(dir) {
+    const raw = readTextFileOrNull(join(dir, PROJECT_FILE_NAME));
+    if (raw === null)
+        return null;
+    return validateProjectFile(JSON.parse(raw)); // JSON 损坏抛 SyntaxError，不静默吞
+}
+/**
+ * 校验 project.json 顶层结构（读时校验，与 outline.ts 的 validateOutlineFile 对称）。
+ * 必检字段（oracle 审核补）：id / name / schema_version——schema_version 是 JSON
+ * 结构演进判定依据（决策 13），id/name 是初始化即写入的必填项；language/prompt/
+ * current_position/时间戳等属可缺省或后续扩展字段，不在此拦截（避免旧文件误伤）。
+ * 节点级字段不逐一校验——文件格式演进由 schema_version 判定，此处只拦
+ * 「完全不是项目配置」的脏数据。
+ */
+function validateProjectFile(parsed) {
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        typeof parsed.id !== "string" ||
+        typeof parsed.name !== "string" ||
+        typeof parsed.schema_version !== "number") {
+        throw new Error("project.json 顶层结构不符契约（需 {id:string, name:string, schema_version:number, ...}）");
+    }
+    return parsed;
+}
+/**
+ * 原子写 project.json（决策 11 同款流程：临时文件 + fsync + rename，schema.md 第 186 行）。
+ * schema_version 随 config 原样写入——与 outline.json 同步写入是调用方职责（决策 13 修订）。
+ */
+export function writeProjectFile(dir, config) {
+    writeJsonAtomic(join(dir, PROJECT_FILE_NAME), config);
+}
+//# sourceMappingURL=project.js.map

package/dist/storage/project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../../src/storage/project.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,EAAE;AACF,+DAA+D;AAC/D,iFAAiF;AACjF,2DAA2D;AAE3D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAElE,mCAAmC;AACnC,MAAM,CAAC,MAAM,iBAAiB,GAAG,cAAc,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,MAAM,GAAG,GAAG,kBAAkB,CAAC,IAAI,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAC7D,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC9B,OAAO,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,4BAA4B;AAC3E,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,mBAAmB,CAAC,MAAe;IAC1C,IACE,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,OAAQ,MAAkC,CAAC,EAAE,KAAK,QAAQ;QAC1D,OAAQ,MAAkC,CAAC,IAAI,KAAK,QAAQ;QAC5D,OAAQ,MAAkC,CAAC,cAAc,KAAK,QAAQ,EACtE,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,+EAA+E,CAAC,CAAC;IACnG,CAAC;IACD,OAAO,MAA2B,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW,EAAE,MAAyB;IACrE,eAAe,CAAC,IAAI,CAAC,GAAG,EAAE,iBAAiB,CAAC,EAAE,MAAM,CAAC,CAAC;AACxD,CAAC"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@whispering233/ai-editor-db",
+  "version": "0.0.1",
+  "description": "数据库层：better-sqlite3 连接 / 建表 / 查询",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "prepack": "node ../../scripts/prepare-package-for-publish.mjs",
+    "postpack": "node ../../scripts/restore-package-json.mjs"
+  },
+  "dependencies": {
+    "@whispering233/ai-editor-shared": "0.0.1",
+    "better-sqlite3": "^13.0.0",
+    "nanoid": "^5.1.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "typescript": "^5.8.0"
+  }
+}