wiki-graph-sdk 0.7.0 → 0.8.0

package/dist/worker.cjs

@@ -32,12 +32,15 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var worker_exports = {};
 __export(worker_exports, {
   applyChapterJobArtifactFile: () => import_worker2.applyChapterJobArtifactFile,
+  applyWikiGraphJobArtifacts: () => applyWikiGraphJobArtifacts,
   createLocalChapterJobFileExecutor: () => import_worker2.createLocalChapterJobFileExecutor,
+  extractWikiGraphJobSnapshots: () => extractWikiGraphJobSnapshots,
   runBuildJobWorker: () => runBuildJobWorker,
   writeChapterJobInputFile: () => import_worker2.writeChapterJobInputFile
 });
 module.exports = __toCommonJS(worker_exports);
 var import_worker = require("wiki-graph-core/worker");
+var import_wiki_graph_core3 = require("wiki-graph-core");
 
 // src/node-platform.ts
 var asyncHooks = __toESM(require("async_hooks"), 1);
@@ -46,7 +49,7 @@ var fs = __toESM(require("fs"), 1);
 var fsPromises = __toESM(require("fs/promises"), 1);
 var os = __toESM(require("os"), 1);
 var pathModule = __toESM(require("path"), 1);
-var process = __toESM(require("process"), 1);
+var process2 = __toESM(require("process"), 1);
 var import_node_stream = require("stream");
 var import_promises = require("stream/promises");
 var sqlite3 = __toESM(require("sqlite3"), 1);
@@ -54,7 +57,7 @@ var yauzl = __toESM(require("yauzl"), 1);
 var yazl = __toESM(require("yazl"), 1);
 var import_nunjucks = require("nunjucks");
 var import_platform = require("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 {
@@ -266,6 +269,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}`);
@@ -277,42 +288,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();
       });
     });
   }
@@ -326,10 +337,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);
     });
   });
 }
@@ -338,19 +349,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();
@@ -360,7 +371,7 @@ async function openNodeZip(file) {
       };
       const resolveEntries = () => {
         zipFile.off("error", rejectAndClose);
-        resolve2(discovered);
+        resolve4(discovered);
       };
       zipFile.on("entry", (entry) => {
         if (!entry.fileName.endsWith("/")) {
@@ -470,12 +481,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);
@@ -606,11 +617,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 = {
@@ -711,6 +722,14 @@ function installNodeWikiGraphPlatform(stateRoot) {
   (0, import_platform.installWikiGraphPlatform)(nodeWikiGraphPlatform);
   (0, import_platform.installWikiGraphStorage)(createNodeWikiGraphStorage(stateRoot));
 }
+function ensureNodeWikiGraphPlatform() {
+  (0, import_platform.installWikiGraphPlatform)(nodeWikiGraphPlatform);
+  try {
+    (0, import_platform.getWikiGraphStorage)();
+  } catch {
+    (0, import_platform.installWikiGraphStorage)(createNodeWikiGraphStorage());
+  }
+}
 async function withNodeWikiGraphStorage(stateRoot, operation) {
   return await (0, import_platform.withWikiGraphStorage)(
     stateRoot === void 0 ? void 0 : createNodeWikiGraphStorage(stateRoot),
@@ -718,8 +737,293 @@ async function withNodeWikiGraphStorage(stateRoot, operation) {
   );
 }
 
+// src/archive/target.ts
+var import_promises2 = require("fs/promises");
+var import_path2 = require("path");
+var import_wiki_graph_core = require("wiki-graph-core");
+
+// src/runtime-path.ts
+var import_os = require("os");
+var import_path = require("path");
+
+// src/runtime-context.ts
+var import_async_hooks = require("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 import_async_hooks.AsyncLocalStorage();
+  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 === "" ? (0, import_os.homedir)() : environmentHome;
+  if (path === "~") return home;
+  if (path.startsWith("~/")) return (0, import_path.resolve)(home, path.slice(2));
+  return (0, import_path.isAbsolute)(path) ? path : (0, import_path.resolve)(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 (0, import_wiki_graph_core.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 ${(0, import_wiki_graph_core.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 ${(0, import_wiki_graph_core.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: (0, import_wiki_graph_core.formatLocatedWikiGraphUri)(path, target.objectUri),
+    target: normalized
+  };
+}
+async function resolveLibraryLocation(target) {
+  const parsedLocated = (0, import_wiki_graph_core.parseLocatedWikiGraphUri)(target.uri);
+  const archiveUri = parsedLocated.archivePath ?? target.uri;
+  const parsed = (0, import_wiki_graph_core.parseWikiGraphLibraryUri)(archiveUri);
+  if (parsed?.kind !== "archive") {
+    throw new WikiGraphArchiveOwnershipError(
+      `Library archive target must be a UUID archive URI: ${target.uri}`
+    );
+  }
+  await (0, import_wiki_graph_core.resolveWikiGraphLibrary)(parsed);
+  const archiveFile = await (0, import_wiki_graph_core.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 (0, import_promises2.realpath)(path);
+  } catch {
+    const absolute = (0, import_path2.resolve)(path);
+    const parent = (0, import_path2.dirname)(absolute);
+    return parent === absolute ? absolute : (0, import_path2.join)(await canonicalPath(parent), (0, import_path2.basename)(absolute));
+  }
+}
+function isWithin(root, candidate) {
+  const child = (0, import_path2.relative)(root, candidate);
+  return child === "" || !child.startsWith("..") && !(0, import_path2.isAbsolute)(child);
+}
+async function findMatchingMembers(libraries, candidate, candidateIdentity) {
+  const members = [];
+  for (const library of libraries) {
+    const archives = await (0, import_wiki_graph_core.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 (0, import_promises2.stat)(path);
+    return `${value.dev}:${value.ino}`;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/archive/write.ts
+var import_wiki_graph_core2 = require("wiki-graph-core");
+async function writeWikiGraphArchiveLocation(location, operation, options = {}) {
+  const cacheOnly = options.searchIndexWritebackPolicy === "cache";
+  const write = async (archiveFile = location.archiveFile) => await new import_wiki_graph_core2.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 (0, import_wiki_graph_core2.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
 var import_worker2 = require("wiki-graph-core/worker");
+async function extractWikiGraphJobSnapshots(options) {
+  ensureNodeWikiGraphPlatform();
+  return await withNodeWikiGraphStorage(
+    options.stateDir,
+    async () => await new import_wiki_graph_core3.WikiGraphArchiveFile(
+      new NodeFile(options.wikgPath)
+    ).readDocument(async (document) => {
+      const results = [];
+      for (const request of options.requests) {
+        options.signal?.throwIfAborted();
+        const chapterId = await (0, import_wiki_graph_core3.resolveChapterPathReadonly)(
+          document,
+          request.chapterPath
+        );
+        const revision = await (0, import_worker.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 (0, import_worker.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;
@@ -731,7 +1035,9 @@ async function runBuildJobWorker(options) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   applyChapterJobArtifactFile,
+  applyWikiGraphJobArtifacts,
   createLocalChapterJobFileExecutor,
+  extractWikiGraphJobSnapshots,
   runBuildJobWorker,
   writeChapterJobInputFile
 });