wiki-graph-sdk 0.9.3 → 0.9.5

package/dist/index.cjs

@@ -152,6 +152,7 @@ var import_os3 = require("os");
 var import_path5 = require("path");
 var import_stream = require("stream");
 var import_wiki_graph_core7 = require("wiki-graph-core");
+var import_platform2 = require("wiki-graph-core/platform");
 
 // src/conversions.ts
 var import_crypto = require("crypto");
@@ -258,7 +259,7 @@ var NodeFile = class {
   }
   path;
   async getPhysicalIdentity() {
-    const value = await fsPromises.stat(this.path).catch((error) => {
+    const value = await fsPromises.stat(toNodeFilesystemPath(this.path)).catch((error) => {
       if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT")
         return void 0;
       throw error;
@@ -271,7 +272,7 @@ var NodeFile = class {
   identity;
   name;
   async openReader() {
-    const handle = await fsPromises.open(this.path, "r");
+    const handle = await fsPromises.open(toNodeFilesystemPath(this.path), "r");
     let closed = false;
     try {
       const stats = await handle.stat();
@@ -311,7 +312,7 @@ var NodeFile = class {
   }
   async getLastModified() {
     try {
-      return (await fsPromises.stat(this.path)).mtimeMs;
+      return (await fsPromises.stat(toNodeFilesystemPath(this.path))).mtimeMs;
     } catch (error) {
       if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
         return void 0;
@@ -320,9 +321,14 @@ var NodeFile = class {
     }
   }
   async openWriter() {
-    await fsPromises.mkdir(pathModule.dirname(this.path), { recursive: true });
+    await fsPromises.mkdir(
+      toNodeFilesystemPath(pathModule.dirname(this.path)),
+      {
+        recursive: true
+      }
+    );
     const temporary = `${this.path}.tmp-${crypto.randomUUID()}`;
-    const handle = await fsPromises.open(temporary, "wx");
+    const handle = await fsPromises.open(toNodeFilesystemPath(temporary), "wx");
     let closed = false;
     return {
       write: async (data) => {
@@ -337,14 +343,17 @@ var NodeFile = class {
       commit: async () => {
         if (!closed) {
           await handle.close();
-          await fsPromises.rename(temporary, this.path);
+          await fsPromises.rename(
+            toNodeFilesystemPath(temporary),
+            toNodeFilesystemPath(this.path)
+          );
         }
         closed = true;
       },
       abort: async () => {
         if (!closed) {
           await handle.close();
-          await fsPromises.rm(temporary, { force: true });
+          await fsPromises.rm(toNodeFilesystemPath(temporary), { force: true });
         }
         closed = true;
       }
@@ -391,7 +400,7 @@ var NodeDirectory = class _NodeDirectory {
   }
   path;
   async getPhysicalIdentity() {
-    const value = await fsPromises.stat(this.path).catch((error) => {
+    const value = await fsPromises.stat(toNodeFilesystemPath(this.path)).catch((error) => {
       if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT")
         return void 0;
       throw error;
@@ -407,7 +416,7 @@ var NodeDirectory = class _NodeDirectory {
     assertChildName(name);
     const file = new NodeFile(pathModule.join(this.path, name));
     try {
-      return (await fsPromises.stat(file.path)).isFile() ? file : void 0;
+      return (await fsPromises.stat(toNodeFilesystemPath(file.path))).isFile() ? file : void 0;
     } catch (error) {
       if (typeof error === "object" && error !== null && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR"))
         return void 0;
@@ -416,7 +425,7 @@ var NodeDirectory = class _NodeDirectory {
   }
   async getLastModified() {
     try {
-      return (await fsPromises.stat(this.path)).mtimeMs;
+      return (await fsPromises.stat(toNodeFilesystemPath(this.path))).mtimeMs;
     } catch (error) {
       if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
         return void 0;
@@ -428,7 +437,7 @@ var NodeDirectory = class _NodeDirectory {
     assertChildName(name);
     const directory = new _NodeDirectory(pathModule.join(this.path, name));
     try {
-      return (await fsPromises.stat(directory.path)).isDirectory() ? directory : void 0;
+      return (await fsPromises.stat(toNodeFilesystemPath(directory.path))).isDirectory() ? directory : void 0;
     } catch (error) {
       if (typeof error === "object" && error !== null && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR"))
         return void 0;
@@ -436,7 +445,7 @@ var NodeDirectory = class _NodeDirectory {
     }
   }
   async list() {
-    const entries = await fsPromises.readdir(this.path, {
+    const entries = await fsPromises.readdir(toNodeFilesystemPath(this.path), {
       withFileTypes: true
     });
     return entries.map(
@@ -445,26 +454,45 @@ var NodeDirectory = class _NodeDirectory {
   }
   async createFile(name) {
     assertChildName(name);
-    await fsPromises.mkdir(this.path, { recursive: true });
+    await fsPromises.mkdir(toNodeFilesystemPath(this.path), {
+      recursive: true
+    });
     const file = new NodeFile(pathModule.join(this.path, name));
-    await fsPromises.writeFile(file.path, "", { flag: "wx" });
+    await fsPromises.writeFile(toNodeFilesystemPath(file.path), "", {
+      flag: "wx"
+    });
     return file;
   }
   async createDirectory(name) {
     assertChildName(name);
-    await fsPromises.mkdir(this.path, { recursive: true });
+    await fsPromises.mkdir(toNodeFilesystemPath(this.path), {
+      recursive: true
+    });
     const directory = new _NodeDirectory(pathModule.join(this.path, name));
-    await fsPromises.mkdir(directory.path);
+    await fsPromises.mkdir(toNodeFilesystemPath(directory.path));
     return directory;
   }
   async remove(name, options) {
     assertChildName(name);
-    await fsPromises.rm(pathModule.join(this.path, name), {
-      force: true,
-      recursive: options?.recursive === true
-    });
+    await fsPromises.rm(
+      toNodeFilesystemPath(pathModule.join(this.path, name)),
+      {
+        force: true,
+        recursive: options?.recursive === true
+      }
+    );
   }
 };
+function toNodeFilesystemPath(path) {
+  if (nodeProcess.platform !== "win32" || path.startsWith("\\\\?\\")) {
+    return path;
+  }
+  const absolute = pathModule.resolve(path);
+  if (absolute.startsWith("\\\\")) {
+    return `\\\\?\\UNC\\${absolute.slice(2)}`;
+  }
+  return `\\\\?\\${absolute}`;
+}
 function encodeNodeResourceIdentity(kind, path) {
   return `node-${kind}:${Buffer.from(pathModule.resolve(path), "utf8").toString("base64url")}`;
 }
@@ -550,10 +578,14 @@ async function openNativeNodeDatabase(file, flags) {
     throw new TypeError("The Node database adapter requires a NodeFile");
   }
   return await new Promise((resolve4, reject) => {
-    const database = new nodeSqlite3.Database(path, flags, (error) => {
-      if (error) reject(error);
-      else resolve4(database);
-    });
+    const database = new nodeSqlite3.Database(
+      toNodeFilesystemPath(path),
+      flags,
+      (error) => {
+        if (error) reject(error);
+        else resolve4(database);
+      }
+    );
   });
 }
 async function openNodeZip(file, options = {}) {
@@ -561,7 +593,7 @@ async function openNodeZip(file, options = {}) {
   if (path === void 0) {
     throw new TypeError("The Node ZIP adapter requires a NodeFile");
   }
-  const handle = await fsPromises.open(path, "r");
+  const handle = await fsPromises.open(toNodeFilesystemPath(path), "r");
   let size;
   try {
     size = (await handle.stat()).size;
@@ -876,6 +908,11 @@ async function writeNodeZip(file, entries) {
   }
 }
 async function addNodeZipEntries(zipFile, iterator, state) {
+  const stableZipOptions = {
+    compress: false,
+    forceDosTimestamp: true,
+    mtime: new Date(1980, 0, 2)
+  };
   while (!state.cancelled) {
     const result = await iterator.next();
     if (state.cancelled) return;
@@ -887,17 +924,17 @@ async function addNodeZipEntries(zipFile, iterator, state) {
       zipFile.addReadStream(
         createNodeFileReadStream(result.value.file),
         result.value.name,
-        { compress: false }
+        stableZipOptions
       );
     } else if ("data" in result.value) {
       zipFile.addBuffer(Buffer.from(result.value.data), result.value.name, {
-        compress: false
+        ...stableZipOptions
       });
     } else {
       zipFile.addReadStream(
         createNodeRangeReadStream(result.value),
         result.value.name,
-        { compress: false, size: result.value.size }
+        { ...stableZipOptions, size: result.value.size }
       );
     }
   }
@@ -2701,7 +2738,10 @@ var WikiGraphArchiveManager = class {
           });
         }
         if (options.replace === true) {
-          await (0, import_promises5.rename)(outputPath, path);
+          await new import_wiki_graph_core7.WikgCoordinator().withExclusiveArchiveReplacement(
+            new NodeFile(path),
+            async () => await (0, import_promises5.rename)(outputPath, path)
+          );
         } else {
           try {
             await (0, import_promises5.link)(outputPath, path);
@@ -2730,6 +2770,18 @@ var WikiGraphArchiveManager = class {
     }, options.signal);
     return new WikiGraphArchiveHandle(this.#runtime, location);
   }
+  async inspectSchema(target, options = {}) {
+    return await this.#runtime.run(
+      async () => ({
+        schemaVersion: await (0, import_wiki_graph_core7.readWikiGraphArchiveSchemaVersion)(
+          await resolveWikiGraphArchiveLocation(target).then(
+            (location) => location.archiveFile
+          )
+        )
+      }),
+      options.signal
+    );
+  }
 };
 var WikiGraphArchiveHandle = class {
   #runtime;
@@ -2756,6 +2808,19 @@ var WikiGraphArchiveHandle = class {
   get target() {
     return this.#location.target;
   }
+  /** Export this archive through the SDK without exposing core file adapters. */
+  async export(path) {
+    return await this.#runtime.run(async () => {
+      const outputPath = await assertStandaloneWikiGraphArchivePath(path);
+      const output = new NodeFile(outputPath);
+      if (this.#location.archiveFile.kind === "directory") {
+        await (0, import_wiki_graph_core7.writeWikgArchive)(this.#location.archiveFile, output);
+      } else {
+        await (0, import_platform2.copyFileContent)(this.#location.archiveFile, output);
+      }
+      return { path: outputPath };
+    });
+  }
   async #persistCursor(cursor) {
     return await this.#runtime.run(
       async () => await (0, import_wiki_graph_core7.createContinuationCursor)(cursor)
@@ -3288,6 +3353,38 @@ var WikiGraphArchiveHandle = class {
       options
     );
   }
+  /** Read archive-level data without exposing the underlying Core reader. */
+  async readOverview(options = {}) {
+    return await this.#readDocument(async (document) => {
+      const [metadata, cover, toc] = await Promise.all([
+        document.readBookMeta(),
+        document.readCover(),
+        document.readToc()
+      ]);
+      const serials = toc === void 0 ? [] : await collectArchiveSerials(document, toc.items);
+      return {
+        ...metadata === void 0 ? {} : { metadata },
+        ...cover === void 0 ? {} : { cover },
+        ...toc === void 0 ? {} : { toc },
+        serials
+      };
+    }, options);
+  }
+  /** Read a chapter and expose its graph as the stable WikgObject stream. */
+  async readChapterData(serialId, options = {}) {
+    const result = await this.#readDocument(async (document) => {
+      const [chapter, summary] = await Promise.all([
+        (0, import_wiki_graph_core7.getChapterDetails)(document, serialId),
+        document.readSummary(serialId)
+      ]);
+      return { chapter, summary };
+    }, options);
+    return {
+      chapter: result.chapter,
+      ...result.summary === void 0 ? {} : { summary: result.summary },
+      objects: this.#readChapterObjects(serialId, options)
+    };
+  }
   async replaceBookMeta(meta, options = {}) {
     return await this.#writeDocument(async (document) => {
       await document.replaceBookMeta(meta);
@@ -3375,6 +3472,33 @@ var WikiGraphArchiveHandle = class {
       (error) => rethrowArchiveSchemaError(error, this.#location.target)
     );
   }
+  async *#readChapterObjects(serialId, options) {
+    const queue = createAsyncValueQueue();
+    const producer = this.#readDocument(async (document) => {
+      try {
+        for await (const object of (0, import_wiki_graph_core7.createChapterReadingGraphObjectStream)({
+          chapterId: serialId,
+          document
+        })) {
+          if (!await queue.push(object)) break;
+        }
+        queue.end();
+      } catch (error) {
+        queue.fail(error);
+        throw error;
+      }
+    }, options).catch((error) => {
+      queue.fail(error);
+      throw error;
+    });
+    try {
+      for await (const object of queue) yield object;
+      await producer;
+    } finally {
+      queue.cancel();
+      await producer.catch(() => void 0);
+    }
+  }
   async #writeDocument(operation, options = {}) {
     return await this.#runtime.run(async () => {
       return await writeWikiGraphArchiveLocation(this.#location, operation, {
@@ -3569,6 +3693,94 @@ function requireChapter(chapters, chapterId) {
 function asTextStream(text) {
   return import_stream.Readable.from([text]);
 }
+async function collectArchiveSerials(document, items, ancestorTitles = []) {
+  const entries = [];
+  for (const item of items) {
+    const title = item.title?.trim() || `Chapter ${item.serialId ?? "group"}`;
+    const tocPath = [...ancestorTitles, title];
+    if (item.serialId !== void 0) {
+      entries.push({
+        fragmentCount: (await document.getSerialFragments(item.serialId).listFragmentIds()).length,
+        serialId: item.serialId,
+        title,
+        tocPath
+      });
+    }
+    entries.push(
+      ...await collectArchiveSerials(document, item.children, tocPath)
+    );
+  }
+  return entries;
+}
+function createAsyncValueQueue() {
+  const values = [];
+  const readers = [];
+  const writers = [];
+  let cancelled = false;
+  let ended = false;
+  let failure;
+  const settleReaders = () => {
+    while (readers.length > 0) {
+      const reader = readers.shift();
+      if (failure !== void 0) reader.reject(failure);
+      else if (values.length > 0) {
+        reader.resolve({ done: false, value: values.shift() });
+        writers.shift()?.();
+      } else if (ended) reader.resolve({ done: true, value: void 0 });
+      else {
+        readers.unshift(reader);
+        return;
+      }
+    }
+  };
+  return {
+    [Symbol.asyncIterator]: () => ({
+      next: async () => {
+        if (failure !== void 0) throw failure;
+        if (values.length > 0) {
+          const value = values.shift();
+          writers.shift()?.();
+          return { done: false, value };
+        }
+        if (ended) return { done: true, value: void 0 };
+        return await new Promise((resolve4, reject) => {
+          readers.push({ reject, resolve: resolve4 });
+        });
+      }
+    }),
+    cancel: () => {
+      cancelled = true;
+      ended = true;
+      values.length = 0;
+      while (writers.length > 0) writers.shift()();
+      settleReaders();
+    },
+    end: () => {
+      ended = true;
+      settleReaders();
+    },
+    fail: (error) => {
+      failure = error instanceof Error ? error : new Error(String(error));
+      ended = true;
+      values.length = 0;
+      while (writers.length > 0) writers.shift()();
+      settleReaders();
+    },
+    push: async (value) => {
+      if (cancelled || ended || failure !== void 0) return false;
+      if (readers.length > 0) {
+        readers.shift().resolve({ done: false, value });
+        return true;
+      }
+      if (values.length > 0) {
+        await new Promise((resolve4) => writers.push(resolve4));
+        if (cancelled || ended || failure !== void 0) return false;
+      }
+      values.push(value);
+      return true;
+    }
+  };
+}
 async function assertChapterResetAllowed(archive, chapterId, stage) {
   if (stage === "planned") {
     await (0, import_wiki_graph_core7.assertNoActiveBuildJobs)({
@@ -4259,13 +4471,13 @@ var import_worker = require("wiki-graph-core/worker");
 var import_wiki_graph_core13 = require("wiki-graph-core");
 
 // src/host.ts
-var import_platform2 = require("wiki-graph-core/platform");
+var import_platform3 = require("wiki-graph-core/platform");
 function prepareWikiGraphSDKHost(host) {
   if (host?.platform === void 0) {
     ensureNodeWikiGraphPlatform();
     return;
   }
-  (0, import_platform2.installWikiGraphPlatform)(host.platform);
+  (0, import_platform3.installWikiGraphPlatform)(host.platform);
 }
 function assertWikiGraphSDKHostOptions(options) {
   if (options.host?.storage !== void 0 && options.host.stateDir === void 0) {
@@ -4296,7 +4508,7 @@ async function withWikiGraphSDKHost(options, operation) {
     operation
   );
   if (effective.host?.storage !== void 0) {
-    return await (0, import_platform2.withWikiGraphStorage)(effective.host.storage, runWithContext);
+    return await (0, import_platform3.withWikiGraphStorage)(effective.host.storage, runWithContext);
   }
   return await withNodeWikiGraphStorage(
     effective.host?.stateDir ?? effective.stateDir,