wiki-graph-sdk 0.7.1 → 0.8.1

package/dist/conversions.cjs

@@ -36,9 +36,9 @@ __export(conversions_exports, {
 module.exports = __toCommonJS(conversions_exports);
 var import_crypto = require("crypto");
 var import_fs = require("fs");
-var import_promises2 = require("fs/promises");
-var import_path3 = require("path");
-var import_wiki_graph_core2 = require("wiki-graph-core");
+var import_promises3 = require("fs/promises");
+var import_path4 = require("path");
+var import_wiki_graph_core3 = require("wiki-graph-core");
 
 // src/llm.ts
 var import_anthropic = require("@ai-sdk/anthropic");
@@ -339,6 +339,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}`);
@@ -350,42 +358,42 @@ var NodeDatabaseConnection = class {
   }
   database;
   async close() {
-    await new Promise((resolve3, reject) => {
+    await new Promise((resolve4, reject) => {
       this.database.close((error) => {
         if (error) reject(error);
-        else resolve3();
+        else resolve4();
       });
     });
   }
   async execute(sql) {
-    await new Promise((resolve3, reject) => {
+    await new Promise((resolve4, reject) => {
       this.database.exec(sql, (error) => {
         if (error) reject(error);
-        else resolve3();
+        else resolve4();
       });
     });
   }
   async queryAll(sql, params = []) {
-    return await new Promise((resolve3, reject) => {
+    return await new Promise((resolve4, reject) => {
       this.database.all(sql, [...params], (error, rows) => {
         if (error) reject(error);
-        else resolve3(rows);
+        else resolve4(rows);
       });
     });
   }
   async queryOne(sql, params = []) {
-    return await new Promise((resolve3, reject) => {
+    return await new Promise((resolve4, reject) => {
       this.database.get(sql, [...params], (error, row) => {
         if (error) reject(error);
-        else resolve3(row);
+        else resolve4(row);
       });
     });
   }
   async run(sql, params = []) {
-    await new Promise((resolve3, reject) => {
+    await new Promise((resolve4, reject) => {
       this.database.run(sql, [...params], (error) => {
         if (error) reject(error);
-        else resolve3();
+        else resolve4();
       });
     });
   }
@@ -399,10 +407,10 @@ async function openNativeNodeDatabase(file, flags) {
   if (path === void 0) {
     throw new TypeError("The Node database adapter requires a NodeFile");
   }
-  return await new Promise((resolve3, reject) => {
+  return await new Promise((resolve4, reject) => {
     const database = new nodeSqlite3.Database(path, flags, (error) => {
       if (error) reject(error);
-      else resolve3(database);
+      else resolve4(database);
     });
   });
 }
@@ -411,19 +419,19 @@ async function openNodeZip(file) {
   if (path === void 0) {
     throw new TypeError("The Node ZIP adapter requires a NodeFile");
   }
-  const zipFile = await new Promise((resolve3, 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 resolve3(opened);
+        else resolve4(opened);
       }
     );
   });
   const entries = await new Promise(
-    (resolve3, reject) => {
+    (resolve4, reject) => {
       const discovered = /* @__PURE__ */ new Map();
       const rejectAndClose = (error) => {
         zipFile.close();
@@ -433,7 +441,7 @@ async function openNodeZip(file) {
       };
       const resolveEntries = () => {
         zipFile.off("error", rejectAndClose);
-        resolve3(discovered);
+        resolve4(discovered);
       };
       zipFile.on("entry", (entry) => {
         if (!entry.fileName.endsWith("/")) {
@@ -543,12 +551,12 @@ async function collectDecodedNodeStreamRange(input, offset, length) {
   return Buffer.concat(chunks, collected);
 }
 async function openNodeZipEntryStream(zipFile, entry, options) {
-  return await new Promise((resolve3, 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 {
-        resolve3(opened);
+        resolve4(opened);
       }
     };
     if (options === void 0) zipFile.openReadStream(entry, callback);
@@ -679,11 +687,11 @@ async function writeNodeStream(input, writer) {
   );
 }
 async function collectNodeStream(input) {
-  return await new Promise((resolve3, reject) => {
+  return await new Promise((resolve4, reject) => {
     const chunks = [];
     input.on("data", (chunk) => chunks.push(chunk));
     input.once("error", reject);
-    input.once("end", () => resolve3(Buffer.concat(chunks)));
+    input.once("end", () => resolve4(Buffer.concat(chunks)));
   });
 }
 var nodeWikiGraphPlatform = {
@@ -804,12 +812,16 @@ function getWikiGraphSDKRuntimeContext() {
   return runtimeContext.getStore() ?? {
     cwd: process.cwd(),
     env: process.env,
-    envPolicy: "production"
+    envPolicy: "production",
+    providers: {}
   };
 }
 function getWikiGraphSDKStateDir() {
   return getWikiGraphSDKRuntimeContext().stateDir;
 }
+function getWikiGraphSDKProviders() {
+  return getWikiGraphSDKRuntimeContext().providers ?? {};
+}
 
 // src/local-config.ts
 var import_path = require("path");
@@ -1027,8 +1039,8 @@ var inlineLLMConfigSchema = import_zod.z.object({
 });
 async function loadWikiGraphRuntimeConfig(options) {
   const [embedding, localLLM, concurrent, wikimedia, wikispine] = await Promise.all([
-    readLocalConfigSection("embeddings"),
-    readLocalConfigSection("llm"),
+    options?.skipEmbeddingConfig === true ? Promise.resolve({}) : readLocalConfigSection("embeddings"),
+    options?.skipLLMConfig === true ? Promise.resolve({}) : readLocalConfigSection("llm"),
     readLocalConfigSection("concurrent"),
     readLocalConfigSection("wikimedia"),
     readLocalConfigSection("wikispine")
@@ -1224,6 +1236,14 @@ function formatError2(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
+// src/providers.ts
+function resolveWikiGraphLLMJSON(options) {
+  if (options.llm !== void 0 && options.llmJSON !== void 0) {
+    throw new Error("Pass either llm or llmJSON, not both.");
+  }
+  return options.llm === void 0 ? options.llmJSON : JSON.stringify(options.llm);
+}
+
 // src/runtime-path.ts
 var import_os2 = require("os");
 var import_path2 = require("path");
@@ -1236,6 +1256,107 @@ function resolveWikiGraphRuntimePath(path) {
   return (0, import_path2.isAbsolute)(path) ? path : (0, import_path2.resolve)(context.cwd, path);
 }
 
+// src/archive/target.ts
+var import_promises2 = require("fs/promises");
+var import_path3 = require("path");
+var import_wiki_graph_core2 = require("wiki-graph-core");
+var WikiGraphArchiveOwnershipError = class extends Error {
+  code = "WIKI_GRAPH_ARCHIVE_OWNERSHIP_MISMATCH";
+  constructor(message) {
+    super(message);
+    this.name = "WikiGraphArchiveOwnershipError";
+  }
+};
+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_core2.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_core2.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_core2.formatWikiGraphLibraryUri)(
+        library.isDefault ? void 0 : library.publicId
+      )}: ${path}. Scan the library, then address the archive by its library UUID URI.`
+    );
+  }
+  return path;
+}
+async function canonicalPath(path) {
+  try {
+    return await (0, import_promises2.realpath)(path);
+  } catch {
+    const absolute = (0, import_path3.resolve)(path);
+    const parent = (0, import_path3.dirname)(absolute);
+    return parent === absolute ? absolute : (0, import_path3.join)(await canonicalPath(parent), (0, import_path3.basename)(absolute));
+  }
+}
+function isWithin(root, candidate) {
+  const child = (0, import_path3.relative)(root, candidate);
+  return child === "" || !child.startsWith("..") && !(0, import_path3.isAbsolute)(child);
+}
+async function findMatchingMembers(libraries, candidate, candidateIdentity) {
+  const members = [];
+  for (const library of libraries) {
+    const archives = await (0, import_wiki_graph_core2.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/conversions.ts
 var WikiGraphConversionManager = class {
   #runtime;
@@ -1260,23 +1381,33 @@ var WikiGraphConversionManager = class {
     }
     const requiresDigest = options.input.format !== "wikg";
     const requiresLLM = requiresDigest && targetStage !== "planned" && targetStage !== "sourced";
+    const llmJSON = resolveWikiGraphLLMJSON(options);
+    const injectedLLM = llmJSON === void 0 ? getWikiGraphSDKProviders().llm : void 0;
     const config = await loadWikiGraphRuntimeConfig({
-      ...options.llmJSON === void 0 ? {} : { llmJSON: options.llmJSON }
+      ...llmJSON === void 0 ? {} : { llmJSON },
+      ...injectedLLM === void 0 ? {} : { skipLLMConfig: true },
+      ...getWikiGraphSDKProviders().embedding === void 0 ? {} : { skipEmbeddingConfig: true }
     });
-    const app = new import_wiki_graph_core2.WikiGraph({
+    const app = new import_wiki_graph_core3.WikiGraph({
       ...options.verbose === true ? { verbose: true } : {},
-      ...requiresLLM ? { llm: buildWikiGraphLLMOptions(config) } : {}
+      ...requiresLLM ? {
+        llm: injectedLLM === void 0 ? buildWikiGraphLLMOptions(config) : { streamProvider: injectedLLM }
+      } : {}
     });
     const documentDirectory = await prepareDigestDirectory(
       options.digestDirectory,
       requiresDigest
     );
     let chapterCount;
+    let chapterPaths;
     const write = async (archive) => {
       if (requiresDigest) await options.onSourceImported?.();
       if (typeof archive.readToc === "function") {
         const toc = await archive.readToc();
         chapterCount = toc === void 0 ? void 0 : countTocChapters(toc.items);
+        if (options.output.format === "wikg") {
+          chapterPaths = toc === void 0 ? [] : collectTocChapterPaths(toc.items);
+        }
       }
       await writeArchive(archive, options.output.path, options.output.format);
     };
@@ -1285,7 +1416,9 @@ var WikiGraphConversionManager = class {
         throw new Error("wikg input requires a file path.");
       }
       await app.openSession(
-        new NodeFile(resolveWikiGraphRuntimePath(options.input.path)),
+        new NodeFile(
+          await assertStandaloneWikiGraphArchivePath(options.input.path)
+        ),
         write
       );
     } else if ("stream" in options.input) {
@@ -1328,6 +1461,7 @@ var WikiGraphConversionManager = class {
     const sourceArtifact = await resolveSourceArtifact(options.input);
     return {
       ...chapterCount === void 0 ? {} : { chapterCount },
+      ...chapterPaths === void 0 ? {} : { chapterPaths },
       inputFormat: options.input.format,
       outputFormat: options.output.format,
       outputPath: options.output.path,
@@ -1340,11 +1474,12 @@ async function prepareDigestDirectory(path, required) {
   if (!required || normalized === void 0 || normalized === "")
     return void 0;
   const resolved = resolveWikiGraphRuntimePath(normalized);
-  await (0, import_promises2.rm)(resolved, { force: true, recursive: true });
+  await (0, import_promises3.rm)(resolved, { force: true, recursive: true });
   return new NodeDirectory(resolved);
 }
 async function writeArchive(archive, path, format) {
-  const file = new NodeFile(resolveWikiGraphRuntimePath(path));
+  const outputPath = format === "wikg" ? await assertStandaloneWikiGraphArchivePath(path) : resolveWikiGraphRuntimePath(path);
+  const file = new NodeFile(outputPath);
   if (format === "epub") await archive.exportEpub(file);
   else if (format === "wikg") await archive.saveAs(file);
   else if (format === "pcex") throw new Error("pcex output is not supported.");
@@ -1373,7 +1508,7 @@ async function resolveSourceArtifact(input) {
   return {
     digest: hash.digest("hex"),
     mediaType: "application/epub+zip",
-    name: (0, import_path3.basename)(path)
+    name: (0, import_path4.basename)(path)
   };
 }
 function isNodeErrorCode(error, code) {
@@ -1389,6 +1524,21 @@ function countTocChapters(items) {
   }
   return count;
 }
+function collectTocChapterPaths(items, ancestorKeys = []) {
+  const paths = [];
+  for (const item of items) {
+    const key = item.key ?? `chapter-${item.serialId ?? "group"}`;
+    const chapterPath = [...ancestorKeys, key];
+    if (item.serialId !== void 0) paths.push(chapterPath.join("/"));
+    paths.push(
+      ...collectTocChapterPaths(
+        item.children,
+        chapterPath
+      )
+    );
+  }
+  return paths;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   WikiGraphConversionManager