wiki-graph-sdk 0.9.3 → 0.9.5

package/dist/archives.d.ts

@@ -1,4 +1,4 @@
-export { h as WikiGraphArchiveChapterInspection, i as WikiGraphArchiveCover, j as WikiGraphArchiveCreateOptions, k as WikiGraphArchiveCreateResult, l as WikiGraphArchiveEvidenceOptions, m as WikiGraphArchiveExistsError, n as WikiGraphArchiveHandle, o as WikiGraphArchiveIndexArtifactInspection, p as WikiGraphArchiveIndexStatus, q as WikiGraphArchiveIndexSyncOptions, r as WikiGraphArchiveInspection, s as WikiGraphArchiveListOptions, W as WikiGraphArchiveManager, t as WikiGraphArchivePageOptions, u as WikiGraphArchiveRelatedOptions, v as WikiGraphArchiveScope, w as WikiGraphArchiveScopeOptions, x as WikiGraphArchiveSearchOptions, y as WikiGraphArchiveWriteOptions, z as WikiGraphChapterArtifactStatus, B as WikiGraphChapterMoveOptions, D as WikiGraphChapterResetStage, E as WikiGraphChapterSourceOptions, F as WikiGraphChapterTreeInput, G as WikiGraphOperationOptions, S as inspectWikiGraphArchive } from './index-DQzLAnjf.js';
+export { h as WikiGraphArchiveChapterData, i as WikiGraphArchiveChapterInspection, j as WikiGraphArchiveCover, k as WikiGraphArchiveCreateOptions, l as WikiGraphArchiveCreateResult, m as WikiGraphArchiveEvidenceOptions, n as WikiGraphArchiveExistsError, o as WikiGraphArchiveExportResult, p as WikiGraphArchiveHandle, q as WikiGraphArchiveIndexArtifactInspection, r as WikiGraphArchiveIndexStatus, s as WikiGraphArchiveIndexSyncOptions, t as WikiGraphArchiveInspection, u as WikiGraphArchiveListOptions, W as WikiGraphArchiveManager, v as WikiGraphArchiveOverview, w as WikiGraphArchivePageOptions, x as WikiGraphArchiveRelatedOptions, y as WikiGraphArchiveSchemaInspection, z as WikiGraphArchiveScope, B as WikiGraphArchiveScopeOptions, D as WikiGraphArchiveSearchOptions, E as WikiGraphArchiveTocFile, F as WikiGraphArchiveTocItem, G as WikiGraphArchiveWriteOptions, H as WikiGraphChapterArtifactStatus, J as WikiGraphChapterMoveOptions, K as WikiGraphChapterResetStage, M as WikiGraphChapterSourceOptions, N as WikiGraphChapterTreeInput, O as WikiGraphOperationOptions, Z as inspectWikiGraphArchive } from './index-4YX4dv6Y.js';
 export { a as WikiGraphArchiveOwnershipError, W as WikiGraphArchiveTarget } from './target-CZ7elwmj.js';
 import 'wiki-graph-core';
 import './jobs-CRK-DZ40.js';

package/dist/archives.js

@@ -14,10 +14,12 @@ import {
   assertArchiveQueryReady,
   resolveIndexedArchiveChapterScope,
   ensureWikiGraphArchiveSchemaCurrent,
+  readWikiGraphArchiveSchemaVersion,
   assertNoActiveBuildJobConflicts,
   assertNoActiveBuildJobs,
   deleteArchiveSearchSessions,
   createContinuationCursor,
+  createChapterReadingGraphObjectStream,
   deleteContinuationCursor,
   DirectoryDocument,
   findArchiveObjects,
@@ -43,13 +45,16 @@ import {
   setChapterSummary,
   setChapterTitle,
   getChapterTree,
+  getChapterDetails,
   WikiGraph as WikiGraph2,
   WikiGraphArchiveFile as WikiGraphArchiveFile2,
   WikiGraphDirectoryFile as WikiGraphDirectoryFile2,
+  WikgCoordinator,
   TOC_FILE_VERSION,
   writeWikgArchive,
   ObjectMetadataKind
 } from "wiki-graph-core";
+import { copyFileContent } from "wiki-graph-core/platform";
 
 // src/conversions.ts
 import { createHash } from "crypto";
@@ -165,7 +170,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;
@@ -178,7 +183,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();
@@ -218,7 +223,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;
@@ -227,9 +232,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) => {
@@ -244,14 +254,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;
       }
@@ -298,7 +311,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;
@@ -314,7 +327,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;
@@ -323,7 +336,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;
@@ -335,7 +348,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;
@@ -343,7 +356,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(
@@ -352,26 +365,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")}`;
 }
@@ -457,10 +489,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 = {}) {
@@ -468,7 +504,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;
@@ -783,6 +819,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;
@@ -794,17 +835,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 }
       );
     }
   }
@@ -2391,7 +2432,10 @@ var WikiGraphArchiveManager = class {
           });
         }
         if (options.replace === true) {
-          await rename2(outputPath, path);
+          await new WikgCoordinator().withExclusiveArchiveReplacement(
+            new NodeFile(path),
+            async () => await rename2(outputPath, path)
+          );
         } else {
           try {
             await link(outputPath, path);
@@ -2420,6 +2464,18 @@ var WikiGraphArchiveManager = class {
     }, options.signal);
     return new WikiGraphArchiveHandle(this.#runtime, location);
   }
+  async inspectSchema(target, options = {}) {
+    return await this.#runtime.run(
+      async () => ({
+        schemaVersion: await readWikiGraphArchiveSchemaVersion(
+          await resolveWikiGraphArchiveLocation(target).then(
+            (location) => location.archiveFile
+          )
+        )
+      }),
+      options.signal
+    );
+  }
 };
 var WikiGraphArchiveHandle = class {
   #runtime;
@@ -2446,6 +2502,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 writeWikgArchive(this.#location.archiveFile, output);
+      } else {
+        await copyFileContent(this.#location.archiveFile, output);
+      }
+      return { path: outputPath };
+    });
+  }
   async #persistCursor(cursor) {
     return await this.#runtime.run(
       async () => await createContinuationCursor(cursor)
@@ -2978,6 +3047,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([
+        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);
@@ -3065,6 +3166,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 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, {
@@ -3259,6 +3387,94 @@ function requireChapter(chapters, chapterId) {
 function asTextStream(text) {
   return Readable2.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 assertNoActiveBuildJobs({