wiki-graph-sdk 0.7.0 → 0.8.0

package/dist/worker.js

@@ -4,8 +4,14 @@ globalThis.__WIKIGRAPH_DATA_DIR__ ??= __WIKIGRAPH_RESOLVE__(__WIKIGRAPH_FILE_URL
 
 // src/worker.ts
 import {
-  runBuildJobWorker as runCoreBuildJobWorker
+  applyChapterJobArtifactFile,
+  runBuildJobWorker as runCoreBuildJobWorker,
+  writeChapterJobInputFile
 } from "wiki-graph-core/worker";
+import {
+  resolveChapterPathReadonly,
+  WikiGraphArchiveFile as WikiGraphArchiveFile2
+} from "wiki-graph-core";
 
 // src/node-platform.ts
 import * as asyncHooks from "async_hooks";
@@ -14,7 +20,7 @@ import * as fs from "fs";
 import * as fsPromises from "fs/promises";
 import * as os from "os";
 import * as pathModule from "path";
-import * as process from "process";
+import * as process2 from "process";
 import { Readable, Writable } from "stream";
 import { pipeline } from "stream/promises";
 import * as sqlite3 from "sqlite3";
@@ -28,7 +34,7 @@ import {
   withWikiGraphStorage,
   normalizeTemplateName
 } from "wiki-graph-core/platform";
-var nodeProcess = process.default ?? process;
+var nodeProcess = process2.default ?? process2;
 var nodeSqlite3 = sqlite3.default ?? sqlite3;
 var NODE_RESOURCE_KIND = /* @__PURE__ */ Symbol.for("wiki-graph-sdk.node-resource.v1");
 var NodeFile = class {
@@ -240,6 +246,14 @@ function decodeNodeResourceIdentity(identity, kind) {
     return void 0;
   }
 }
+function getNodeResourcePath(resource) {
+  const brandedPath = getBrandedNodeResourcePath(resource, resource.kind);
+  if (brandedPath !== void 0) return brandedPath;
+  if (typeof resource === "object" && resource !== null && "path" in resource && typeof resource.path === "string") {
+    return resource.path;
+  }
+  throw new TypeError("Expected a Node File or Directory resource");
+}
 function assertChildName(name) {
   if (name.length === 0 || name === "." || name === ".." || pathModule.isAbsolute(name) || name.includes("/") || name.includes("\\")) {
     throw new TypeError(`Directory child must be a relative name: ${name}`);
@@ -251,42 +265,42 @@ var NodeDatabaseConnection = class {
   }
   database;
   async close() {
-    await new Promise((resolve2, reject) => {
+    await new Promise((resolve4, reject) => {
       this.database.close((error) => {
         if (error) reject(error);
-        else resolve2();
+        else resolve4();
       });
     });
   }
   async execute(sql) {
-    await new Promise((resolve2, reject) => {
+    await new Promise((resolve4, reject) => {
       this.database.exec(sql, (error) => {
         if (error) reject(error);
-        else resolve2();
+        else resolve4();
       });
     });
   }
   async queryAll(sql, params = []) {
-    return await new Promise((resolve2, reject) => {
+    return await new Promise((resolve4, reject) => {
       this.database.all(sql, [...params], (error, rows) => {
         if (error) reject(error);
-        else resolve2(rows);
+        else resolve4(rows);
       });
     });
   }
   async queryOne(sql, params = []) {
-    return await new Promise((resolve2, reject) => {
+    return await new Promise((resolve4, reject) => {
       this.database.get(sql, [...params], (error, row) => {
         if (error) reject(error);
-        else resolve2(row);
+        else resolve4(row);
       });
     });
   }
   async run(sql, params = []) {
-    await new Promise((resolve2, reject) => {
+    await new Promise((resolve4, reject) => {
       this.database.run(sql, [...params], (error) => {
         if (error) reject(error);
-        else resolve2();
+        else resolve4();
       });
     });
   }
@@ -300,10 +314,10 @@ async function openNativeNodeDatabase(file, flags) {
   if (path === void 0) {
     throw new TypeError("The Node database adapter requires a NodeFile");
   }
-  return await new Promise((resolve2, reject) => {
+  return await new Promise((resolve4, reject) => {
     const database = new nodeSqlite3.Database(path, flags, (error) => {
       if (error) reject(error);
-      else resolve2(database);
+      else resolve4(database);
     });
   });
 }
@@ -312,19 +326,19 @@ async function openNodeZip(file) {
   if (path === void 0) {
     throw new TypeError("The Node ZIP adapter requires a NodeFile");
   }
-  const zipFile = await new Promise((resolve2, reject) => {
+  const zipFile = await new Promise((resolve4, reject) => {
     yauzl.open(
       path,
       { autoClose: false, lazyEntries: true },
       (error, opened) => {
         if (error || opened === void 0)
           reject(error ?? new Error("Cannot open ZIP"));
-        else resolve2(opened);
+        else resolve4(opened);
       }
     );
   });
   const entries = await new Promise(
-    (resolve2, reject) => {
+    (resolve4, reject) => {
       const discovered = /* @__PURE__ */ new Map();
       const rejectAndClose = (error) => {
         zipFile.close();
@@ -334,7 +348,7 @@ async function openNodeZip(file) {
       };
       const resolveEntries = () => {
         zipFile.off("error", rejectAndClose);
-        resolve2(discovered);
+        resolve4(discovered);
       };
       zipFile.on("entry", (entry) => {
         if (!entry.fileName.endsWith("/")) {
@@ -444,12 +458,12 @@ async function collectDecodedNodeStreamRange(input, offset, length) {
   return Buffer.concat(chunks, collected);
 }
 async function openNodeZipEntryStream(zipFile, entry, options) {
-  return await new Promise((resolve2, reject) => {
+  return await new Promise((resolve4, reject) => {
     const callback = (error, opened) => {
       if (error || opened === void 0) {
         reject(error ?? new Error(`Cannot read ZIP entry: ${entry.fileName}`));
       } else {
-        resolve2(opened);
+        resolve4(opened);
       }
     };
     if (options === void 0) zipFile.openReadStream(entry, callback);
@@ -580,11 +594,11 @@ async function writeNodeStream(input, writer) {
   );
 }
 async function collectNodeStream(input) {
-  return await new Promise((resolve2, reject) => {
+  return await new Promise((resolve4, reject) => {
     const chunks = [];
     input.on("data", (chunk) => chunks.push(chunk));
     input.once("error", reject);
-    input.once("end", () => resolve2(Buffer.concat(chunks)));
+    input.once("end", () => resolve4(Buffer.concat(chunks)));
   });
 }
 var nodeWikiGraphPlatform = {
@@ -685,6 +699,14 @@ function installNodeWikiGraphPlatform(stateRoot) {
   installWikiGraphPlatform(nodeWikiGraphPlatform);
   installWikiGraphStorage(createNodeWikiGraphStorage(stateRoot));
 }
+function ensureNodeWikiGraphPlatform() {
+  installWikiGraphPlatform(nodeWikiGraphPlatform);
+  try {
+    getWikiGraphStorage();
+  } catch {
+    installWikiGraphStorage(createNodeWikiGraphStorage());
+  }
+}
 async function withNodeWikiGraphStorage(stateRoot, operation) {
   return await withWikiGraphStorage(
     stateRoot === void 0 ? void 0 : createNodeWikiGraphStorage(stateRoot),
@@ -692,12 +714,309 @@ async function withNodeWikiGraphStorage(stateRoot, operation) {
   );
 }
 
+// src/archive/target.ts
+import { realpath, stat as stat2 } from "fs/promises";
+import { basename as basename2, dirname as dirname2, isAbsolute as isAbsolute3, join as join2, relative, resolve as resolve3 } from "path";
+import {
+  formatLocatedWikiGraphUri,
+  formatWikiGraphLibraryUri,
+  listWikiGraphLibraries,
+  listWikiGraphLibraryArchives,
+  parseLocatedWikiGraphUri,
+  parseWikiGraphLibraryUri,
+  resolveWikiGraphLibrary,
+  resolveWikiGraphLibraryArchiveFile
+} from "wiki-graph-core";
+
+// src/runtime-path.ts
+import { homedir as homedir2 } from "os";
+import { isAbsolute as isAbsolute2, resolve as resolve2 } from "path";
+
+// src/runtime-context.ts
+import { AsyncLocalStorage as AsyncLocalStorage2 } from "async_hooks";
+var RUNTIME_CONTEXT_KEY = /* @__PURE__ */ Symbol.for("wiki-graph-sdk.runtime-context.v1");
+var runtimeContext = getRuntimeContextStorage();
+function getRuntimeContextStorage() {
+  const runtimeGlobal = globalThis;
+  const existing = runtimeGlobal[RUNTIME_CONTEXT_KEY];
+  if (existing !== void 0) {
+    return existing;
+  }
+  const storage = new AsyncLocalStorage2();
+  Object.defineProperty(runtimeGlobal, RUNTIME_CONTEXT_KEY, {
+    configurable: false,
+    enumerable: false,
+    value: storage,
+    writable: false
+  });
+  return storage;
+}
+function getWikiGraphSDKRuntimeContext() {
+  return runtimeContext.getStore() ?? {
+    cwd: process.cwd(),
+    env: process.env,
+    envPolicy: "production"
+  };
+}
+
+// src/runtime-path.ts
+function resolveWikiGraphRuntimePath(path) {
+  const context = getWikiGraphSDKRuntimeContext();
+  const environmentHome = context.env.HOME?.trim();
+  const home = environmentHome === void 0 || environmentHome === "" ? homedir2() : environmentHome;
+  if (path === "~") return home;
+  if (path.startsWith("~/")) return resolve2(home, path.slice(2));
+  return isAbsolute2(path) ? path : resolve2(context.cwd, path);
+}
+
+// src/archive/target.ts
+var WikiGraphArchiveOwnershipError = class extends Error {
+  code = "WIKI_GRAPH_ARCHIVE_OWNERSHIP_MISMATCH";
+  constructor(message) {
+    super(message);
+    this.name = "WikiGraphArchiveOwnershipError";
+  }
+};
+async function resolveWikiGraphArchiveLocation(target) {
+  if (target.kind === "standalone") {
+    return await resolveStandaloneLocation(target);
+  }
+  return await resolveLibraryLocation(target);
+}
+async function assertStandaloneWikiGraphArchivePath(inputPath) {
+  const path = resolveWikiGraphRuntimePath(inputPath);
+  const candidate = await canonicalPath(path);
+  const candidateIdentity = await readFileIdentity(path);
+  const libraries = await listWikiGraphLibraries();
+  const matches = await findMatchingMembers(
+    libraries,
+    candidate,
+    candidateIdentity
+  );
+  if (matches.length > 0) {
+    const match = requireUnambiguousManagedMatch(path, matches);
+    throw new WikiGraphArchiveOwnershipError(
+      `Standalone archive path belongs to registered library ${formatWikiGraphLibraryUri(
+        match.library.isDefault ? void 0 : match.library.publicId
+      )}: ${path}. Use the library UUID URI ${match.archive.uri} instead.`
+    );
+  }
+  for (const library of libraries) {
+    const rootPath = getNodeResourcePath(library.folder);
+    const root = await canonicalPath(rootPath);
+    if (!isWithin(root, candidate)) continue;
+    throw new WikiGraphArchiveOwnershipError(
+      `Standalone archive path belongs to registered library ${formatWikiGraphLibraryUri(
+        library.isDefault ? void 0 : library.publicId
+      )}: ${path}. Scan the library, then address the archive by its library UUID URI.`
+    );
+  }
+  return path;
+}
+async function resolveStandaloneLocation(target) {
+  if (target.path.startsWith("wikg://lib/")) {
+    throw new WikiGraphArchiveOwnershipError(
+      `A library archive URI cannot be used as a standalone path: ${target.path}`
+    );
+  }
+  const path = await assertStandaloneWikiGraphArchivePath(target.path);
+  const normalized = {
+    kind: "standalone",
+    path,
+    ...target.objectUri === void 0 ? {} : { objectUri: target.objectUri }
+  };
+  return {
+    archiveFile: new NodeFile(path),
+    archiveKey: path,
+    archivePath: path,
+    indexScope: { archiveKey: path, archivePath: path, kind: "archive-index" },
+    locatedUri: formatLocatedWikiGraphUri(path, target.objectUri),
+    target: normalized
+  };
+}
+async function resolveLibraryLocation(target) {
+  const parsedLocated = parseLocatedWikiGraphUri(target.uri);
+  const archiveUri = parsedLocated.archivePath ?? target.uri;
+  const parsed = parseWikiGraphLibraryUri(archiveUri);
+  if (parsed?.kind !== "archive") {
+    throw new WikiGraphArchiveOwnershipError(
+      `Library archive target must be a UUID archive URI: ${target.uri}`
+    );
+  }
+  await resolveWikiGraphLibrary(parsed);
+  const archiveFile = await resolveWikiGraphLibraryArchiveFile(archiveUri);
+  const normalized = {
+    kind: "library",
+    uri: target.uri
+  };
+  return {
+    archiveFile,
+    archiveKey: archiveUri,
+    archivePath: archiveUri,
+    indexScope: {
+      archiveKey: archiveUri,
+      archivePath: archiveUri,
+      kind: "archive-index"
+    },
+    libraryArchiveTarget: parsed,
+    locatedUri: target.uri,
+    publicArchiveUri: archiveUri,
+    target: normalized
+  };
+}
+async function canonicalPath(path) {
+  try {
+    return await realpath(path);
+  } catch {
+    const absolute = resolve3(path);
+    const parent = dirname2(absolute);
+    return parent === absolute ? absolute : join2(await canonicalPath(parent), basename2(absolute));
+  }
+}
+function isWithin(root, candidate) {
+  const child = relative(root, candidate);
+  return child === "" || !child.startsWith("..") && !isAbsolute3(child);
+}
+async function findMatchingMembers(libraries, candidate, candidateIdentity) {
+  const members = [];
+  for (const library of libraries) {
+    const archives = await listWikiGraphLibraryArchives({
+      isDefault: library.isDefault,
+      kind: "scope",
+      ...library.isDefault ? {} : { publicId: library.publicId }
+    });
+    for (const archive of archives) {
+      if (archive.file === void 0) continue;
+      members.push({
+        archive,
+        library,
+        memberPath: getNodeResourcePath(archive.file)
+      });
+    }
+  }
+  const exact = [];
+  for (const member of members) {
+    if (await canonicalPath(member.memberPath) === candidate) {
+      exact.push(member);
+    }
+  }
+  if (exact.length > 0 || candidateIdentity === void 0) return exact;
+  const identityMatches = [];
+  for (const member of members) {
+    if (await readFileIdentity(member.memberPath) === candidateIdentity) {
+      identityMatches.push(member);
+    }
+  }
+  return identityMatches;
+}
+function requireUnambiguousManagedMatch(path, matches) {
+  if (matches.length === 1) return matches[0];
+  throw new WikiGraphArchiveOwnershipError(
+    `Archive file identity is ambiguous across managed archives: ${path}. Use an explicit library UUID URI (${matches.map((match) => match.archive.uri).join(", ")}).`
+  );
+}
+async function readFileIdentity(path) {
+  try {
+    const value = await stat2(path);
+    return `${value.dev}:${value.ino}`;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/archive/write.ts
+import {
+  WikiGraphArchiveFile,
+  writeWikiGraphLibraryArchive
+} from "wiki-graph-core";
+async function writeWikiGraphArchiveLocation(location, operation, options = {}) {
+  const cacheOnly = options.searchIndexWritebackPolicy === "cache";
+  const write = async (archiveFile = location.archiveFile) => await new WikiGraphArchiveFile(archiveFile).write(operation, {
+    ...cacheOnly ? {} : { derivedStateKeys: [location.archiveKey, location.archivePath] },
+    ...options.invalidateContinuationCursors === void 0 ? {} : {
+      invalidateContinuationCursors: options.invalidateContinuationCursors
+    },
+    ...options.searchIndexWritebackPolicy === void 0 ? {} : { searchIndexWritebackPolicy: options.searchIndexWritebackPolicy }
+  });
+  if (location.libraryArchiveTarget === void 0 || cacheOnly || options.refreshLibraryIndex === false) {
+    return await write();
+  }
+  return await writeWikiGraphLibraryArchive({
+    additionalDerivedStateKeys: [location.archiveKey, location.archivePath],
+    ...options.invalidateContinuationCursors === void 0 ? {} : {
+      invalidateContinuationCursors: options.invalidateContinuationCursors
+    },
+    ...options.onIndexSyncError === void 0 ? {} : { onIndexSyncError: options.onIndexSyncError },
+    operation: async (archiveFile) => await write(archiveFile),
+    target: location.libraryArchiveTarget
+  });
+}
+
 // src/worker.ts
 import {
-  applyChapterJobArtifactFile,
+  applyChapterJobArtifactFile as applyChapterJobArtifactFile2,
   createLocalChapterJobFileExecutor,
-  writeChapterJobInputFile
+  writeChapterJobInputFile as writeChapterJobInputFile2
 } from "wiki-graph-core/worker";
+async function extractWikiGraphJobSnapshots(options) {
+  ensureNodeWikiGraphPlatform();
+  return await withNodeWikiGraphStorage(
+    options.stateDir,
+    async () => await new WikiGraphArchiveFile2(
+      new NodeFile(options.wikgPath)
+    ).readDocument(async (document) => {
+      const results = [];
+      for (const request of options.requests) {
+        options.signal?.throwIfAborted();
+        const chapterId = await resolveChapterPathReadonly(
+          document,
+          request.chapterPath
+        );
+        const revision = await writeChapterJobInputFile(
+          document,
+          chapterId,
+          request.kind,
+          new NodeFile(request.outputPath),
+          request.options
+        );
+        const result = { ...request, chapterId, revision };
+        results.push(result);
+        await options.onSnapshot?.(result);
+      }
+      options.signal?.throwIfAborted();
+      return results;
+    })
+  );
+}
+async function applyWikiGraphJobArtifacts(options) {
+  ensureNodeWikiGraphPlatform();
+  return await withNodeWikiGraphStorage(options.stateDir, async () => {
+    const location = await resolveWikiGraphArchiveLocation(options.archive);
+    let applied = 0;
+    await writeWikiGraphArchiveLocation(
+      location,
+      async (document) => {
+        for await (const artifact of options.artifacts) {
+          options.signal?.throwIfAborted();
+          const revision = await document.serials.getRevision(
+            artifact.chapterId
+          );
+          await applyChapterJobArtifactFile(
+            document,
+            artifact.chapterId,
+            artifact.kind,
+            revision,
+            new NodeFile(artifact.artifactPath)
+          );
+          applied += 1;
+        }
+      },
+      { invalidateContinuationCursors: true }
+    );
+    options.signal?.throwIfAborted();
+    return { applied };
+  });
+}
 async function runBuildJobWorker(options) {
   installNodeWikiGraphPlatform();
   const { stateDir, ...coreOptions } = options;
@@ -707,9 +1026,11 @@ async function runBuildJobWorker(options) {
   );
 }
 export {
-  applyChapterJobArtifactFile,
+  applyChapterJobArtifactFile2 as applyChapterJobArtifactFile,
+  applyWikiGraphJobArtifacts,
   createLocalChapterJobFileExecutor,
+  extractWikiGraphJobSnapshots,
   runBuildJobWorker,
-  writeChapterJobInputFile
+  writeChapterJobInputFile2 as writeChapterJobInputFile
 };
 //# sourceMappingURL=worker.js.map