wiki-graph-sdk 0.8.1 → 0.8.3

package/dist/index.cjs

@@ -61,6 +61,7 @@ __export(src_exports, {
   createEntryRuntimeContext: () => createEntryRuntimeContext,
   createGenerationPerformanceHints: () => createGenerationPerformanceHints,
   createNodeTemplateEnvironment: () => createNodeTemplateEnvironment,
+  createNodeWikiGraphPlatform: () => createNodeWikiGraphPlatform,
   createNodeWikiGraphStorage: () => createNodeWikiGraphStorage,
   createStageLLM: () => createStageLLM,
   createWikiGraphSDK: () => createWikiGraphSDK,
@@ -75,6 +76,8 @@ __export(src_exports, {
   formatLocatedChapterSourceCollectionUri: () => import_wiki_graph_core19.formatLocatedChapterSourceCollectionUri,
   formatLocatedChapterUri: () => import_wiki_graph_core19.formatLocatedChapterUri,
   formatLocatedWikiGraphUri: () => import_wiki_graph_core19.formatLocatedWikiGraphUri,
+  formatSourceArtifactUri: () => import_wiki_graph_core19.formatSourceArtifactUri,
+  formatSourceLocatorFragment: () => import_wiki_graph_core19.formatSourceLocatorFragment,
   formatWikiGraphCommandUri: () => import_wiki_graph_core19.formatWikiGraphCommandUri,
   formatWikiGraphLibraryUri: () => import_wiki_graph_core19.formatWikiGraphLibraryUri,
   getNodeResourcePath: () => getNodeResourcePath,
@@ -84,7 +87,9 @@ __export(src_exports, {
   inspectWikiGraphArchive: () => inspectWikiGraphArchive,
   installNodeWikiGraphPlatform: () => installNodeWikiGraphPlatform,
   isSourceLocatorScopeUri: () => import_wiki_graph_core19.isSourceLocatorScopeUri,
+  isWikiGraphJobUri: () => import_wiki_graph_core19.isWikiGraphJobUri,
   isWikiGraphLibraryUri: () => import_wiki_graph_core19.isWikiGraphLibraryUri,
+  isWikiGraphUri: () => import_wiki_graph_core19.isWikiGraphUri,
   loadRequiredStageConfig: () => loadRequiredStageConfig,
   loadWikiGraphRuntimeConfig: () => loadWikiGraphRuntimeConfig,
   maskLocalConfigSection: () => maskLocalConfigSection,
@@ -96,6 +101,7 @@ __export(src_exports, {
   parseChapterUriPath: () => import_wiki_graph_core19.parseChapterUriPath,
   parseLocalConfigSection: () => parseLocalConfigSection,
   parseLocatedWikiGraphUri: () => import_wiki_graph_core19.parseLocatedWikiGraphUri,
+  parseSourceLocatorFragment: () => import_wiki_graph_core19.parseSourceLocatorFragment,
   parseSourceTextJsonl: () => import_wiki_graph_core19.parseSourceTextJsonl,
   parseWikiGraphLibraryUri: () => import_wiki_graph_core19.parseWikiGraphLibraryUri,
   parseWikiGraphUriSyntax: () => import_wiki_graph_core19.parseWikiGraphUriSyntax,
@@ -104,7 +110,10 @@ __export(src_exports, {
   readLocalConfigSection: () => readLocalConfigSection,
   readWikiGraphEmbeddingConfig: () => readWikiGraphEmbeddingConfig,
   replaceLocalConfigSection: () => replaceLocalConfigSection,
+  requireArchiveUri: () => import_wiki_graph_core19.requireArchiveUri,
   requireKnowledgeGraphWikispineConfig: () => requireKnowledgeGraphWikispineConfig,
+  requireLocatedObjectOrArchiveUri: () => import_wiki_graph_core19.requireLocatedObjectOrArchiveUri,
+  requireLocatedObjectUri: () => import_wiki_graph_core19.requireLocatedObjectUri,
   resolveExtractionPrompt: () => import_wiki_graph_core10.resolveExtractionPrompt,
   resolveHostedProviderEndpoint: () => resolveHostedProviderEndpoint,
   resolveKnowledgeGraphRecallPrompt: () => import_wiki_graph_core10.resolveKnowledgeGraphRecallPrompt,
@@ -120,7 +129,7 @@ module.exports = __toCommonJS(src_exports);
 
 // src/archive/archive.ts
 var import_crypto2 = require("crypto");
-var import_promises4 = require("fs/promises");
+var import_promises5 = require("fs/promises");
 var import_os3 = require("os");
 var import_path5 = require("path");
 var import_stream = require("stream");
@@ -129,7 +138,7 @@ var import_wiki_graph_core7 = require("wiki-graph-core");
 // src/conversions.ts
 var import_crypto = require("crypto");
 var import_fs = require("fs");
-var import_promises3 = require("fs/promises");
+var import_promises4 = require("fs/promises");
 var import_path4 = require("path");
 var import_wiki_graph_core3 = require("wiki-graph-core");
 
@@ -836,6 +845,9 @@ var nodeWikiGraphPlatform = {
     write: writeNodeZip
   }
 };
+function createNodeWikiGraphPlatform(options = {}) {
+  return options.lifecycle === void 0 ? nodeWikiGraphPlatform : { ...nodeWikiGraphPlatform, lifecycle: options.lifecycle };
+}
 var NodeTemplateLoader = class extends import_nunjucks.Loader {
   #dataDirectory;
   constructor(dataDirectory) {
@@ -881,10 +893,15 @@ function resolveNodeDataDirectory() {
     directory = parent;
   }
 }
-function createNodeWikiGraphStorage(stateRoot = pathModule.join(os.homedir(), ".wikigraph")) {
+function createNodeWikiGraphStorage(stateRootOrOptions = pathModule.join(
+  os.homedir(),
+  ".wikigraph"
+)) {
+  const libraryRoot = typeof stateRootOrOptions === "string" ? stateRootOrOptions : stateRootOrOptions.libraryRoot;
+  const documentStoreRoot = typeof stateRootOrOptions === "string" ? pathModule.join(stateRootOrOptions, "documents") : stateRootOrOptions.documentStoreRoot;
   return {
-    library: new NodeDirectory(stateRoot),
-    documentStore: new NodeDirectory(pathModule.join(stateRoot, "documents"))
+    library: new NodeDirectory(libraryRoot),
+    documentStore: new NodeDirectory(documentStoreRoot)
   };
 }
 function installNodeWikiGraphPlatform(stateRoot) {
@@ -892,7 +909,11 @@ function installNodeWikiGraphPlatform(stateRoot) {
   (0, import_platform.installWikiGraphStorage)(createNodeWikiGraphStorage(stateRoot));
 }
 function ensureNodeWikiGraphPlatform() {
-  (0, import_platform.installWikiGraphPlatform)(nodeWikiGraphPlatform);
+  try {
+    (0, import_platform.getWikiGraphPlatform)();
+  } catch {
+    (0, import_platform.installWikiGraphPlatform)(nodeWikiGraphPlatform);
+  }
   try {
     (0, import_platform.getWikiGraphStorage)();
   } catch {
@@ -943,13 +964,15 @@ function getWikiGraphSDKRuntimeContext() {
   };
 }
 function getWikiGraphSDKStateDir() {
-  return getWikiGraphSDKRuntimeContext().stateDir;
+  const context = getWikiGraphSDKRuntimeContext();
+  return context.host?.stateDir ?? context.stateDir;
 }
 function getWikiGraphSDKProviders() {
   return getWikiGraphSDKRuntimeContext().providers ?? {};
 }
 
 // src/local-config.ts
+var import_promises2 = require("fs/promises");
 var import_path = require("path");
 var import_os = require("os");
 var LOCAL_CONFIG_SECTIONS = [
@@ -1050,13 +1073,10 @@ function validateLocalConfigSection(section, value) {
   }
 }
 async function withLocalConfigDatabase(operation) {
+  const stateDir = getWikiGraphSDKStateDir() ?? (0, import_path.join)((0, import_os.homedir)(), ".wikigraph");
+  await (0, import_promises2.mkdir)(stateDir, { recursive: true });
   const database = await (0, import_wiki_graph_core.openSharedStateDatabase)(
-    new NodeFile(
-      (0, import_path.join)(
-        getWikiGraphSDKStateDir() ?? (0, import_path.join)((0, import_os.homedir)(), ".wikigraph"),
-        "core.sqlite"
-      )
-    ),
+    new NodeFile((0, import_path.join)(stateDir, "core.sqlite")),
     LOCAL_CONFIG_SCHEMA_SQL
   );
   try {
@@ -1466,7 +1486,7 @@ function resolveWikiGraphRuntimePath(path) {
 }
 
 // src/archive/target.ts
-var import_promises2 = require("fs/promises");
+var import_promises3 = require("fs/promises");
 var import_path3 = require("path");
 var import_wiki_graph_core2 = require("wiki-graph-core");
 var WikiGraphArchiveOwnershipError = class extends Error {
@@ -1595,7 +1615,7 @@ function withObjectUri(archiveLocator, objectUri) {
 }
 async function canonicalPath(path) {
   try {
-    return await (0, import_promises2.realpath)(path);
+    return await (0, import_promises3.realpath)(path);
   } catch {
     const absolute = (0, import_path3.resolve)(path);
     const parent = (0, import_path3.dirname)(absolute);
@@ -1646,7 +1666,7 @@ function requireUnambiguousManagedMatch(path, matches) {
 }
 async function readFileIdentity(path) {
   try {
-    const value = await (0, import_promises2.stat)(path);
+    const value = await (0, import_promises3.stat)(path);
     return `${value.dev}:${value.ino}`;
   } catch {
     return void 0;
@@ -1770,7 +1790,7 @@ async function prepareDigestDirectory(path, required) {
   if (!required || normalized === void 0 || normalized === "")
     return void 0;
   const resolved = resolveWikiGraphRuntimePath(normalized);
-  await (0, import_promises3.rm)(resolved, { force: true, recursive: true });
+  await (0, import_promises4.rm)(resolved, { force: true, recursive: true });
   return new NodeDirectory(resolved);
 }
 async function writeArchive(archive, path, format) {
@@ -2188,10 +2208,10 @@ var WikiGraphArchiveManager = class {
           });
         }
         if (options.replace === true) {
-          await (0, import_promises4.rename)(outputPath, path);
+          await (0, import_promises5.rename)(outputPath, path);
         } else {
           try {
-            await (0, import_promises4.link)(outputPath, path);
+            await (0, import_promises5.link)(outputPath, path);
           } catch (error) {
             if (isNodeEEXISTError(error)) {
               throw new WikiGraphArchiveExistsError(path);
@@ -2201,7 +2221,7 @@ var WikiGraphArchiveManager = class {
         }
         return { locatedUri: (0, import_wiki_graph_core7.formatLocatedWikiGraphUri)(path), path };
       } finally {
-        await (0, import_promises4.rm)(outputPath, { force: true, recursive: true });
+        await (0, import_promises5.rm)(outputPath, { force: true, recursive: true });
       }
     }, options.signal);
   }
@@ -2364,6 +2384,13 @@ var WikiGraphArchiveHandle = class {
     );
     return status;
   }
+  /** Clear cached search sessions without changing the archive index. */
+  async clearSearchSessions(options = {}) {
+    await this.#runtime.run(
+      async () => await (0, import_wiki_graph_core7.deleteArchiveSearchSessions)(this.path),
+      options.signal
+    );
+  }
   async listChapters(options = {}) {
     return await this.#readDocument(
       async (document) => await (0, import_wiki_graph_core7.listChapters)(document),
@@ -2815,7 +2842,7 @@ function selectChapterSubtree(chapters, rootChapterId, depth) {
   );
 }
 async function createEmptyArchiveFile(path) {
-  const directoryPath = await (0, import_promises4.mkdtemp)(
+  const directoryPath = await (0, import_promises5.mkdtemp)(
     (0, import_path5.join)((0, import_os3.tmpdir)(), "wikigraph-archive-write-")
   );
   try {
@@ -2830,7 +2857,7 @@ async function createEmptyArchiveFile(path) {
     }
     await (0, import_wiki_graph_core7.writeWikgArchive)(directory, new NodeFile(path));
   } finally {
-    await (0, import_promises4.rm)(directoryPath, { force: true, recursive: true });
+    await (0, import_promises5.rm)(directoryPath, { force: true, recursive: true });
   }
 }
 function isNodeEEXISTError(error) {
@@ -2838,7 +2865,7 @@ function isNodeEEXISTError(error) {
 }
 async function nodePathExists(path) {
   try {
-    await (0, import_promises4.stat)(path);
+    await (0, import_promises5.stat)(path);
     return true;
   } catch (error) {
     if (isNodeENOENTError(error)) return false;
@@ -3294,6 +3321,8 @@ async function createFindOptions(cursor, limit) {
     cursor: cursor.cursor,
     ...cursor.evidenceLimit === void 0 ? {} : { evidenceLimit: cursor.evidenceLimit },
     limit,
+    ...cursor.match === void 0 ? {} : { match: cursor.match },
+    ...cursor.order === void 0 ? {} : { order: cursor.order },
     ...cursor.queryMode === void 0 ? {} : { queryMode: cursor.queryMode },
     ...cursor.skipUnindexed === void 0 ? {} : { skipUnindexed: cursor.skipUnindexed },
     ...cursor.sourceContext === void 0 ? {} : { sourceContext: cursor.sourceContext },
@@ -3397,6 +3426,8 @@ function createContinuationPayload(context, cursor) {
         indexScope: context.indexScope,
         kind: "search",
         ...createLibraryQueryPayload(context),
+        ...context.match === void 0 ? {} : { match: context.match },
+        ...context.order === void 0 ? {} : { order: context.order },
         ...context.query === void 0 ? {} : { query: context.query },
         ...context.queryMode === void 0 ? {} : { queryMode: context.queryMode },
         ...context.skipUnindexed === void 0 ? {} : { skipUnindexed: context.skipUnindexed },
@@ -3599,12 +3630,62 @@ function getGenerationPlanningProfile(task) {
 // src/worker.ts
 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");
+function prepareWikiGraphSDKHost(host) {
+  if (host?.platform === void 0) {
+    ensureNodeWikiGraphPlatform();
+    return;
+  }
+  (0, import_platform2.installWikiGraphPlatform)(host.platform);
+}
+function assertWikiGraphSDKHostOptions(options) {
+  if (options.host?.storage !== void 0 && options.host.stateDir === void 0) {
+    throw new TypeError(
+      "Wiki Graph SDK host.storage requires host.stateDir so SDK configuration cannot fall back to the default user state directory."
+    );
+  }
+  if (options.stateDir !== void 0 && (options.host?.stateDir !== void 0 || options.host?.storage !== void 0)) {
+    throw new TypeError(
+      "Wiki Graph SDK host state/storage and top-level stateDir cannot be used together. Put the state directory in host.stateDir when providing host.storage."
+    );
+  }
+}
+async function withWikiGraphSDKHost(options, operation) {
+  const current = getWikiGraphSDKRuntimeContext();
+  const effective = {
+    ...options.host === void 0 ? current.host === void 0 ? {} : { host: current.host } : { host: options.host },
+    ...options.stateDir === void 0 ? current.stateDir === void 0 ? {} : { stateDir: current.stateDir } : { stateDir: options.stateDir }
+  };
+  assertWikiGraphSDKHostOptions(effective);
+  prepareWikiGraphSDKHost(effective.host);
+  const runWithContext = async () => await withWikiGraphSDKRuntimeContext(
+    {
+      ...current,
+      ...effective.host === void 0 ? {} : { host: effective.host },
+      ...effective.stateDir === void 0 ? {} : { stateDir: effective.stateDir }
+    },
+    operation
+  );
+  if (effective.host?.storage !== void 0) {
+    return await (0, import_platform2.withWikiGraphStorage)(effective.host.storage, runWithContext);
+  }
+  return await withNodeWikiGraphStorage(
+    effective.host?.stateDir ?? effective.stateDir,
+    runWithContext
+  );
+}
+
+// src/worker.ts
 var import_worker2 = require("wiki-graph-core/worker");
 async function runBuildJobWorker(options) {
-  installNodeWikiGraphPlatform();
-  const { stateDir, ...coreOptions } = options;
-  await withNodeWikiGraphStorage(
-    stateDir,
+  const { host, stateDir, ...coreOptions } = options;
+  await withWikiGraphSDKHost(
+    {
+      ...host === void 0 ? {} : { host },
+      ...stateDir === void 0 ? {} : { stateDir }
+    },
     async () => await (0, import_worker.runBuildJobWorker)(coreOptions)
   );
 }
@@ -4495,7 +4576,7 @@ function forwardAbort(source, target) {
 
 // src/libraries.ts
 var import_wiki_graph_core16 = require("wiki-graph-core");
-var import_promises5 = require("fs/promises");
+var import_promises6 = require("fs/promises");
 async function resolveQueryEmbeddingProvider(queryMode) {
   if (queryMode === "fts") return void 0;
   const provider = await createConfiguredEmbeddingProvider();
@@ -4514,7 +4595,7 @@ var WikiGraphLibraryManager = class {
   async create(folder) {
     const record = await this.#runtime.run(async () => {
       const path = resolveWikiGraphRuntimePath(folder);
-      await (0, import_promises5.mkdir)(path);
+      await (0, import_promises6.mkdir)(path);
       return await (0, import_wiki_graph_core16.createWikiGraphLibrary)({ folder: new NodeDirectory(path) });
     });
     return new WikiGraphLibrary(this.#runtime, record);
@@ -5030,11 +5111,13 @@ var WikiGraphSDK = class {
   libraries;
   maintenance;
   constructor(options = {}) {
-    ensureNodeWikiGraphPlatform();
+    assertWikiGraphSDKHostOptions(options);
+    prepareWikiGraphSDKHost(options.host);
     this.#context = {
       cwd: options.cwd ?? process.cwd(),
       env: { ...process.env, ...options.env },
       envPolicy: options.envPolicy ?? "production",
+      ...options.host === void 0 ? {} : { host: options.host },
       providers: { ...options.providers },
       ...options.stateDir === void 0 ? {} : { stateDir: options.stateDir }
     };
@@ -5060,8 +5143,11 @@ var WikiGraphSDK = class {
       }
       return await operation();
     });
-    const result = this.#context.stateDir === void 0 ? await runWithContext() : await withNodeWikiGraphStorage(
-      this.#context.stateDir,
+    const result = await withWikiGraphSDKHost(
+      {
+        ...this.#context.host === void 0 ? {} : { host: this.#context.host },
+        ...this.#context.stateDir === void 0 ? {} : { stateDir: this.#context.stateDir }
+      },
       runWithContext
     );
     throwIfAborted2(signal);
@@ -5113,6 +5199,7 @@ var import_wiki_graph_core19 = require("wiki-graph-core");
   createEntryRuntimeContext,
   createGenerationPerformanceHints,
   createNodeTemplateEnvironment,
+  createNodeWikiGraphPlatform,
   createNodeWikiGraphStorage,
   createStageLLM,
   createWikiGraphSDK,
@@ -5127,6 +5214,8 @@ var import_wiki_graph_core19 = require("wiki-graph-core");
   formatLocatedChapterSourceCollectionUri,
   formatLocatedChapterUri,
   formatLocatedWikiGraphUri,
+  formatSourceArtifactUri,
+  formatSourceLocatorFragment,
   formatWikiGraphCommandUri,
   formatWikiGraphLibraryUri,
   getNodeResourcePath,
@@ -5136,7 +5225,9 @@ var import_wiki_graph_core19 = require("wiki-graph-core");
   inspectWikiGraphArchive,
   installNodeWikiGraphPlatform,
   isSourceLocatorScopeUri,
+  isWikiGraphJobUri,
   isWikiGraphLibraryUri,
+  isWikiGraphUri,
   loadRequiredStageConfig,
   loadWikiGraphRuntimeConfig,
   maskLocalConfigSection,
@@ -5148,6 +5239,7 @@ var import_wiki_graph_core19 = require("wiki-graph-core");
   parseChapterUriPath,
   parseLocalConfigSection,
   parseLocatedWikiGraphUri,
+  parseSourceLocatorFragment,
   parseSourceTextJsonl,
   parseWikiGraphLibraryUri,
   parseWikiGraphUriSyntax,
@@ -5156,7 +5248,10 @@ var import_wiki_graph_core19 = require("wiki-graph-core");
   readLocalConfigSection,
   readWikiGraphEmbeddingConfig,
   replaceLocalConfigSection,
+  requireArchiveUri,
   requireKnowledgeGraphWikispineConfig,
+  requireLocatedObjectOrArchiveUri,
+  requireLocatedObjectUri,
   resolveExtractionPrompt,
   resolveHostedProviderEndpoint,
   resolveKnowledgeGraphRecallPrompt,