wiki-graph-sdk 0.7.0 → 0.8.0

package/dist/conversions.cjs

@@ -34,8 +34,11 @@ __export(conversions_exports, {
   WikiGraphConversionManager: () => WikiGraphConversionManager
 });
 module.exports = __toCommonJS(conversions_exports);
-var import_promises2 = require("fs/promises");
-var import_wiki_graph_core2 = require("wiki-graph-core");
+var import_crypto = require("crypto");
+var import_fs = require("fs");
+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");
@@ -336,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}`);
@@ -347,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();
       });
     });
   }
@@ -396,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);
     });
   });
 }
@@ -408,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();
@@ -430,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("/")) {
@@ -540,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);
@@ -676,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 = {
@@ -1233,6 +1244,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;
@@ -1247,6 +1359,9 @@ var WikiGraphConversionManager = class {
     if (options.targetStage !== void 0 && options.output.format !== "wikg") {
       throw new Error("targetStage is only supported for wikg output.");
     }
+    if (options.output.format === "pcex") {
+      throw new Error("pcex is supported only as a conversion input.");
+    }
     if (options.targetStage !== void 0 && options.input.format === "wikg") {
       throw new Error(
         "targetStage is only supported when creating a wikg archive."
@@ -1257,7 +1372,7 @@ var WikiGraphConversionManager = class {
     const config = await loadWikiGraphRuntimeConfig({
       ...options.llmJSON === void 0 ? {} : { llmJSON: options.llmJSON }
     });
-    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) } : {}
     });
@@ -1265,7 +1380,17 @@ var WikiGraphConversionManager = class {
       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);
     };
     if (options.input.format === "wikg") {
@@ -1273,7 +1398,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) {
@@ -1298,16 +1425,29 @@ var WikiGraphConversionManager = class {
       };
       if (options.input.format === "epub") {
         await app.digestEpubSession(digestOptions, write);
+      } else if (options.input.format === "pcex") {
+        await app.digestPcexSession(
+          {
+            ...digestOptions,
+            pdfDigest: options.input.sourcePdf.digest,
+            ...options.input.sourcePdf.name === void 0 ? {} : { pdfName: options.input.sourcePdf.name }
+          },
+          write
+        );
       } else if (options.input.format === "markdown") {
         await app.digestMarkdownSession(digestOptions, write);
       } else {
         await app.digestTxtSession(digestOptions, write);
       }
     }
+    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
+      outputPath: options.output.path,
+      ...sourceArtifact === void 0 ? {} : { sourceArtifact }
     };
   }
 };
@@ -1316,15 +1456,71 @@ 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.");
   else await archive.exportText(file);
 }
+async function resolveSourceArtifact(input) {
+  if (!("path" in input) || input.format === "wikg") return void 0;
+  if (input.format === "pcex") {
+    return {
+      digest: input.sourcePdf.digest.trim().toLowerCase(),
+      mediaType: "application/pdf",
+      ...input.sourcePdf.name === void 0 ? {} : { name: input.sourcePdf.name }
+    };
+  }
+  if (input.format !== "epub") return void 0;
+  const path = resolveWikiGraphRuntimePath(input.path);
+  const hash = (0, import_crypto.createHash)("sha256");
+  try {
+    for await (const chunk of (0, import_fs.createReadStream)(path)) {
+      hash.update(chunk);
+    }
+  } catch (error) {
+    if (isNodeErrorCode(error, "ENOENT")) return void 0;
+    throw error;
+  }
+  return {
+    digest: hash.digest("hex"),
+    mediaType: "application/epub+zip",
+    name: (0, import_path4.basename)(path)
+  };
+}
+function isNodeErrorCode(error, code) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+function countTocChapters(items) {
+  let count = 0;
+  for (const item of items) {
+    if (item.serialId !== void 0) count += 1;
+    count += countTocChapters(
+      item.children
+    );
+  }
+  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