wiki-graph-sdk 0.7.0 → 0.8.0

package/dist/{jobs-Dd5PMSId.d.ts → jobs-xIm_kshM.d.ts}

@@ -1,4 +1,5 @@
 import { AddBuildJobOptions, BuildJob, BuildJobListOptions, BuildJobEventChunk, BuildJobEvent, BuildJobTarget, ChapterEntry } from 'wiki-graph-core';
+import { W as WikiGraphArchiveTarget } from './target-CZ7elwmj.js';
 
 interface WikiGraphJobBackend {
     add(options: AddBuildJobOptions): Promise<BuildJob>;
@@ -13,18 +14,25 @@ interface WikiGraphJobBackend {
     setTarget(jobId: string, target: BuildJobTarget): Promise<BuildJob>;
 }
 interface WikiGraphJobCreateOptions extends Omit<AddBuildJobOptions, "archive"> {
-    readonly archive: string | AddBuildJobOptions["archive"];
+    readonly archive: WikiGraphArchiveTarget;
 }
 interface WikiGraphJobListOptions extends Omit<BuildJobListOptions, "archive"> {
-    readonly archive?: string | BuildJobListOptions["archive"];
+    readonly archive?: WikiGraphArchiveTarget;
 }
 interface WikiGraphJobChapterReference {
     readonly locatedUri: string;
     readonly title: string | null;
     readonly uri: string;
 }
+interface WikiGraphJobSnapshot extends Omit<BuildJob, "archive" | "cache" | "events" | "log" | "workspace"> {
+    readonly archive: WikiGraphArchiveTarget;
+    readonly cachePath?: string;
+    readonly eventsPath?: string;
+    readonly logPath?: string;
+    readonly workspacePath?: string;
+}
 interface WikiGraphJobEnqueueOptions {
-    readonly archive: string;
+    readonly archive: WikiGraphArchiveTarget;
     readonly boost?: boolean;
     readonly chapterId?: number;
     readonly chapterIds?: readonly number[];
@@ -73,8 +81,8 @@ declare class WikiGraphJobManager {
     get(jobId: string): Promise<WikiGraphJob>;
     resolveId(reference: string): Promise<string>;
     list(options?: WikiGraphJobListOptions): Promise<readonly WikiGraphJob[]>;
-    resolveChapters(jobs: readonly BuildJob[]): Promise<ReadonlyMap<string, WikiGraphJobChapterReference>>;
-    resolveChapter(job: BuildJob): Promise<WikiGraphJobChapterReference | undefined>;
+    resolveChapters(jobs: readonly WikiGraphJobSnapshot[]): Promise<ReadonlyMap<string, WikiGraphJobChapterReference>>;
+    resolveChapter(job: WikiGraphJobSnapshot): Promise<WikiGraphJobChapterReference | undefined>;
     enqueue(options: WikiGraphJobEnqueueOptions): Promise<WikiGraphJobEnqueueResult>;
     planEnqueue(options: WikiGraphJobEnqueueOptions): Promise<WikiGraphJobEnqueuePlan>;
     close(): void;
@@ -82,17 +90,17 @@ declare class WikiGraphJobManager {
 }
 declare class WikiGraphJob {
     #private;
-    constructor(manager: WikiGraphJobManager, runtime: WikiGraphJobRuntime, backend: WikiGraphJobBackend, snapshot: BuildJob);
+    constructor(manager: WikiGraphJobManager, runtime: WikiGraphJobRuntime, backend: WikiGraphJobBackend, snapshot: BuildJob, archiveTarget: WikiGraphArchiveTarget);
     get id(): string;
-    get snapshot(): BuildJob;
-    status(): Promise<BuildJob>;
-    pause(): Promise<BuildJob>;
-    resume(): Promise<BuildJob>;
-    cancel(): Promise<BuildJob>;
-    boost(): Promise<BuildJob>;
-    setTarget(target: BuildJobTarget): Promise<BuildJob>;
+    get snapshot(): WikiGraphJobSnapshot;
+    status(): Promise<WikiGraphJobSnapshot>;
+    pause(): Promise<WikiGraphJobSnapshot>;
+    resume(): Promise<WikiGraphJobSnapshot>;
+    cancel(): Promise<WikiGraphJobSnapshot>;
+    boost(): Promise<WikiGraphJobSnapshot>;
+    setTarget(target: BuildJobTarget): Promise<WikiGraphJobSnapshot>;
     events(options?: WikiGraphJobEventsOptions): AsyncIterable<BuildJobEvent>;
     subscribe(listener: WikiGraphJobEventListener, options?: WikiGraphJobSubscriptionOptions): () => void;
 }
 
-export { type WikiGraphJobRuntime as W, WikiGraphJobManager as a, WikiGraphJob as b, type WikiGraphJobBackend as c, type WikiGraphJobChapterReference as d, type WikiGraphJobCreateOptions as e, type WikiGraphJobEnqueueOptions as f, type WikiGraphJobEnqueuePlan as g, type WikiGraphJobEnqueueResult as h, type WikiGraphJobEventListener as i, type WikiGraphJobEventsOptions as j, type WikiGraphJobListOptions as k, type WikiGraphJobSubscriptionOptions as l };
+export { type WikiGraphJobRuntime as W, WikiGraphJobManager as a, WikiGraphJob as b, type WikiGraphJobBackend as c, type WikiGraphJobChapterReference as d, type WikiGraphJobCreateOptions as e, type WikiGraphJobEnqueueOptions as f, type WikiGraphJobEnqueuePlan as g, type WikiGraphJobEnqueueResult as h, type WikiGraphJobEventListener as i, type WikiGraphJobEventsOptions as j, type WikiGraphJobListOptions as k, type WikiGraphJobSnapshot as l, type WikiGraphJobSubscriptionOptions as m };

package/dist/maintenance.cjs

@@ -34,8 +34,8 @@ __export(maintenance_exports, {
   WikiGraphMaintenanceManager: () => WikiGraphMaintenanceManager
 });
 module.exports = __toCommonJS(maintenance_exports);
-var import_wiki_graph_core = require("wiki-graph-core");
-var import_path2 = require("path");
+var import_wiki_graph_core2 = require("wiki-graph-core");
+var import_path3 = require("path");
 
 // src/node-platform.ts
 var asyncHooks = __toESM(require("async_hooks"), 1);
@@ -264,6 +264,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}`);
@@ -275,42 +283,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();
       });
     });
   }
@@ -324,10 +332,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);
     });
   });
 }
@@ -336,19 +344,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();
@@ -358,7 +366,7 @@ async function openNodeZip(file) {
       };
       const resolveEntries = () => {
         zipFile.off("error", rejectAndClose);
-        resolve3(discovered);
+        resolve4(discovered);
       };
       zipFile.on("entry", (entry) => {
         if (!entry.fileName.endsWith("/")) {
@@ -468,12 +476,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);
@@ -604,11 +612,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 = {
@@ -741,6 +749,107 @@ function resolveWikiGraphRuntimePath(path) {
   return (0, import_path.isAbsolute)(path) ? path : (0, import_path.resolve)(context.cwd, path);
 }
 
+// src/archive/target.ts
+var import_promises2 = require("fs/promises");
+var import_path2 = require("path");
+var import_wiki_graph_core = 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_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 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/maintenance.ts
 var WikiGraphMaintenanceManager = class {
   #runtime;
@@ -751,22 +860,22 @@ var WikiGraphMaintenanceManager = class {
     return await this.#runtime.run(
       async () => {
         if (target.kind === "home") {
-          return await (0, import_wiki_graph_core.upgradeWikiGraphMaintenanceTarget)({ kind: "home" });
+          return await (0, import_wiki_graph_core2.upgradeWikiGraphMaintenanceTarget)({ kind: "home" });
         }
         if (target.kind === "library") {
-          const parsed = (0, import_wiki_graph_core.parseWikiGraphLibraryUri)(target.uri);
+          const parsed = (0, import_wiki_graph_core2.parseWikiGraphLibraryUri)(target.uri);
           if (parsed === void 0 || parsed.kind === "archive") {
             throw new Error(
               `Invalid Wiki Graph library upgrade target: ${target.uri}`
             );
           }
-          return await (0, import_wiki_graph_core.upgradeWikiGraphMaintenanceTarget)({
+          return await (0, import_wiki_graph_core2.upgradeWikiGraphMaintenanceTarget)({
             kind: "library",
             target: parsed
           });
         }
-        const path = resolveWikiGraphRuntimePath(target.path);
-        return await (0, import_wiki_graph_core.upgradeWikiGraphMaintenanceTarget)({
+        const path = await assertStandaloneWikiGraphArchivePath(target.path);
+        return await (0, import_wiki_graph_core2.upgradeWikiGraphMaintenanceTarget)({
           file: new NodeFile(path),
           kind: "archive"
         });
@@ -779,9 +888,9 @@ var WikiGraphMaintenanceManager = class {
     return await this.#runtime.run(async () => {
       const resolvedInputPath = resolveWikiGraphRuntimePath(inputPath);
       const resolvedOutputPath = resolveWikiGraphRuntimePath(outputPath);
-      await (0, import_wiki_graph_core.migrateLegacySdpubToWikg)(
+      await (0, import_wiki_graph_core2.migrateLegacySdpubToWikg)(
         new NodeFile(resolvedInputPath),
-        new NodeFile(resolvedOutputPath, (0, import_path2.basename)(resolvedOutputPath))
+        new NodeFile(resolvedOutputPath, (0, import_path3.basename)(resolvedOutputPath))
       );
       return {
         inputPath: resolvedInputPath,