pixelkiln 0.35.0 → 0.36.0

package/dist/index.cjs

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AssetSchema: () => AssetSchema,
+  BudgetError: () => BudgetError,
   ComfyUIProvider: () => ComfyUIProvider,
   DEFAULT_HISTORY_LIMIT: () => DEFAULT_HISTORY_LIMIT,
   DEFAULT_QUALITY_TOLERANCES: () => DEFAULT_QUALITY_TOLERANCES,
@@ -38,6 +39,7 @@ __export(index_exports, {
   DEFAULT_TIMEOUT_MS: () => DEFAULT_TIMEOUT_MS,
   EDITOR_PIN: () => EDITOR_PIN,
   EDITOR_RELEASE_BASE: () => EDITOR_RELEASE_BASE,
+  EXIT_CODES: () => EXIT_CODES,
   EditorInstallError: () => EditorInstallError,
   FAKE_PNG: () => FAKE_PNG,
   FakeProvider: () => FakeProvider,
@@ -62,11 +64,15 @@ __export(index_exports, {
   ManifestInputSchema: () => ManifestInputSchema,
   ManifestSchema: () => ManifestSchema,
   MediaType: () => MediaType,
+  OverwriteRefusedError: () => OverwriteRefusedError,
   PIXEL_ART_FIXER_REVISION: () => PIXEL_ART_FIXER_REVISION,
   PIXEL_ART_FIXER_URL: () => PIXEL_ART_FIXER_URL,
+  PixelKilnError: () => PixelKilnError,
   PixelLabClient: () => PixelLabClient,
   PixelLabError: () => PixelLabError,
   PixelLabProvider: () => PixelLabProvider,
+  ProjectError: () => ProjectError,
+  ProviderError: () => ProviderError,
   QualityBaselineSchema: () => QualityBaselineSchema,
   QualityProfileSchema: () => QualityProfileSchema,
   QualityToleranceSchema: () => QualityToleranceSchema,
@@ -78,6 +84,7 @@ __export(index_exports, {
   StyleInputSchema: () => StyleInputSchema,
   StyleSchema: () => StyleSchema,
   UnsupportedCapabilityError: () => UnsupportedCapabilityError,
+  UsageError: () => UsageError,
   WorkspaceProjectSchema: () => WorkspaceProjectSchema,
   WorkspaceSchema: () => WorkspaceSchema,
   adopt: () => adopt,
@@ -115,7 +122,9 @@ __export(index_exports, {
   editorRoute: () => editorRoute,
   editorStatus: () => editorStatus,
   editorToolsRoot: () => editorToolsRoot,
+  errorCode: () => errorCode,
   evaluateAudit: () => evaluateAudit,
+  exitCodeFor: () => exitCodeFor,
   expectedOutputPath: () => expectedOutputPath,
   exportTileset: () => exportTileset,
   fallbackOutputRole: () => fallbackOutputRole,
@@ -745,6 +754,72 @@ function lockKey(styleId, assetId) {
   return `${styleId}/${assetId}`;
 }
 
+// src/errors.ts
+var EXIT_CODES = {
+  usage: 2,
+  project: 3,
+  provider: 4,
+  "refused-overwrite": 5,
+  budget: 6,
+  capability: 7
+};
+var PixelKilnError = class extends Error {
+  code;
+  hint;
+  constructor(message6, code, opts = {}) {
+    super(message6, opts.cause === void 0 ? void 0 : { cause: opts.cause });
+    this.name = "PixelKilnError";
+    this.code = code;
+    if (opts.hint) this.hint = opts.hint;
+  }
+};
+var UsageError = class extends PixelKilnError {
+  constructor(message6, opts) {
+    super(message6, "usage", opts);
+    this.name = "UsageError";
+  }
+};
+var ProjectError = class extends PixelKilnError {
+  constructor(message6, opts) {
+    super(message6, "project", opts);
+    this.name = "ProjectError";
+  }
+};
+var ProviderError = class extends PixelKilnError {
+  /** Registry id of the provider that failed. */
+  provider;
+  /** HTTP status when the failure was a response, otherwise undefined. */
+  status;
+  constructor(provider, message6, opts = {}) {
+    super(message6, "provider", opts);
+    this.name = "ProviderError";
+    this.provider = provider;
+    if (opts.status !== void 0) this.status = opts.status;
+  }
+};
+var OverwriteRefusedError = class extends PixelKilnError {
+  /** The file(s) left untouched. */
+  files;
+  constructor(message6, files, opts) {
+    super(message6, "refused-overwrite", opts);
+    this.name = "OverwriteRefusedError";
+    this.files = files;
+  }
+};
+var BudgetError = class extends PixelKilnError {
+  constructor(message6, opts) {
+    super(message6, "budget", opts);
+    this.name = "BudgetError";
+  }
+};
+function errorCode(err) {
+  return err instanceof PixelKilnError ? err.code : void 0;
+}
+function exitCodeFor(err) {
+  const code = errorCode(err);
+  return code ? EXIT_CODES[code] : 1;
+}
+
 // src/client.ts
 var import_zod2 = require("zod");
 
@@ -861,14 +936,12 @@ function validateResponse(schema, raw, operation) {
   const issues = parsed.error.issues.slice(0, 4).map((i) => `${i.path.join(".") || "response"}: ${i.message}`).join("; ");
   throw new Error(`Invalid PixelLab response for ${operation}: ${issues}`);
 }
-var PixelLabError = class extends Error {
+var PixelLabError = class extends ProviderError {
   constructor(message6, status, body) {
-    super(message6);
-    this.status = status;
+    super("pixellab", message6, { status });
     this.body = body;
     this.name = "PixelLabError";
   }
-  status;
   body;
 };
 var PixelLabClient = class {
@@ -1148,10 +1221,11 @@ function measureBalanceChange(before, after) {
   };
 }
 var DEFAULT_RATE_LIMIT = { spacingMs: 2500, maxInFlight: 8 };
-var UnsupportedCapabilityError = class extends Error {
+var UnsupportedCapabilityError = class extends PixelKilnError {
   constructor(providerId, capability) {
     super(
-      `Provider "${providerId}" does not support ${capability}. That command is unavailable with this backend.`
+      `Provider "${providerId}" does not support ${capability}. That command is unavailable with this backend.`,
+      "capability"
     );
     this.name = "UnsupportedCapabilityError";
   }
@@ -1976,7 +2050,7 @@ var RetroDiffusionClient = class {
   /** Result URLs are signed; no token header, and the same retry policy as the API. */
   async download(url) {
     const response = await this.request(url);
-    if (!response.ok) throw new Error(`Retro Diffusion download failed (${response.status})`);
+    if (!response.ok) throw new ProviderError("retrodiffusion", `Retro Diffusion download failed (${response.status})`, { status: response.status });
     return Buffer.from(await response.arrayBuffer());
   }
   async call(path32, init = {}) {
@@ -1999,8 +2073,10 @@ var RetroDiffusionClient = class {
     if (!response.ok) {
       const retry = response.headers.get("retry-after");
       const detail = retroError(value);
-      throw new Error(
-        `Retro Diffusion request failed (${response.status}): ${detail}` + (retry ? `; retry after ${retry}s` : "")
+      throw new ProviderError(
+        "retrodiffusion",
+        `Retro Diffusion request failed (${response.status}): ${detail}` + (retry ? `; retry after ${retry}s` : ""),
+        { status: response.status }
       );
     }
     return value;
@@ -2392,7 +2468,7 @@ var ScenarioClient = class {
       throw new Error("Scenario downloads must use HTTP or HTTPS");
     }
     const response = await this.request(parsed);
-    if (!response.ok) throw new Error(`Scenario download failed (${response.status})`);
+    if (!response.ok) throw new ProviderError("scenario", `Scenario download failed (${response.status})`, { status: response.status });
     const declared = Number(response.headers.get("content-length"));
     if (Number.isFinite(declared) && declared > MAX_DOWNLOAD_BYTES) {
       throw new Error(`Scenario download exceeds the ${MAX_DOWNLOAD_BYTES}-byte safety limit`);
@@ -2439,8 +2515,10 @@ var ScenarioClient = class {
     if (!response.ok) {
       const retry = response.headers.get("retry-after");
       const detail = redactScenarioError(value, [this.apiKey, this.apiSecret, auth]);
-      throw new Error(
-        `Scenario request failed (${response.status}): ${detail}` + (retry ? `; retry after ${retry}s` : "")
+      throw new ProviderError(
+        "scenario",
+        `Scenario request failed (${response.status}): ${detail}` + (retry ? `; retry after ${retry}s` : ""),
+        { status: response.status }
       );
     }
     return value;
@@ -2890,8 +2968,10 @@ var ComfyUIClient = class {
       value = null;
     }
     if (!response.ok) {
-      throw new Error(
-        `ComfyUI image upload failed (${response.status})` + (apiError(value) ? `: ${apiError(value)}` : "")
+      throw new ProviderError(
+        "comfyui",
+        `ComfyUI image upload failed (${response.status})` + (apiError(value) ? `: ${apiError(value)}` : ""),
+        { status: response.status }
       );
     }
     if (!isObject(value) || typeof value.name !== "string" || !value.name) {
@@ -2914,7 +2994,7 @@ var ComfyUIClient = class {
     let target = source;
     if (source.startsWith("comfyui://")) target = this.viewUrl(parseSource(source));
     const response = await this.request(target);
-    if (!response.ok) throw new Error(`ComfyUI download failed (${response.status})`);
+    if (!response.ok) throw new ProviderError("comfyui", `ComfyUI download failed (${response.status})`, { status: response.status });
     return Buffer.from(await response.arrayBuffer());
   }
   endpoint(route) {
@@ -2939,8 +3019,10 @@ var ComfyUIClient = class {
     }
     if (!response.ok) {
       const detail = apiError(value);
-      throw new Error(
-        `ComfyUI request failed (${response.status}) at ${url.pathname}` + (detail ? `: ${detail}` : "")
+      throw new ProviderError(
+        "comfyui",
+        `ComfyUI request failed (${response.status}) at ${url.pathname}` + (detail ? `: ${detail}` : ""),
+        { status: response.status }
       );
     }
     return value;
@@ -3930,9 +4012,10 @@ async function loadLock(lockPath) {
   try {
     return parseLock(JSON.parse(await (0, import_promises2.readFile)(lockPath, "utf8")));
   } catch (err) {
-    throw new Error(
+    throw new ProjectError(
       `Lockfile at ${lockPath} is malformed:
-${err instanceof Error ? err.message : String(err)}`
+${err instanceof Error ? err.message : String(err)}`,
+      { cause: err }
     );
   }
 }
@@ -3966,8 +4049,9 @@ async function writeLockWhileHeld(file, lock) {
     try {
       disk = parseLock(JSON.parse(await (0, import_promises2.readFile)(file, "utf8")));
     } catch (err) {
-      throw new Error(
-        `Refusing to overwrite malformed lockfile at ${file}: ${err instanceof Error ? err.message : String(err)}`
+      throw new ProjectError(
+        `Refusing to overwrite malformed lockfile at ${file}: ${err instanceof Error ? err.message : String(err)}`,
+        { cause: err }
       );
     }
   }
@@ -4223,18 +4307,18 @@ function resolveSpecOutputs(spec, lock, manifestDir) {
 // src/manifest.ts
 async function loadManifest(manifestPath) {
   const abs = import_node_path5.default.resolve(manifestPath);
-  if (!(0, import_node_fs5.existsSync)(abs)) throw new Error(`No manifest at ${abs}`);
+  if (!(0, import_node_fs5.existsSync)(abs)) throw new ProjectError(`No manifest at ${abs}`);
   const input = ManifestInputSchema.safeParse(JSON.parse(await (0, import_promises3.readFile)(abs, "utf8")));
   if (!input.success) {
     const issues = formatManifestIssues(input.error.issues);
-    throw new Error(`Manifest at ${abs} is invalid:
+    throw new ProjectError(`Manifest at ${abs} is invalid:
 ${issues}`);
   }
   let styles;
   try {
     styles = resolveStyleInheritance(input.data.styles);
   } catch (error) {
-    throw new Error(
+    throw new ProjectError(
       `Manifest at ${abs} is invalid:
   ${error instanceof Error ? error.message : String(error)}`
     );
@@ -4242,7 +4326,7 @@ ${issues}`);
   const parsed = ManifestSchema.safeParse({ ...input.data, styles });
   if (!parsed.success) {
     const issues = formatManifestIssues(parsed.error.issues);
-    throw new Error(`Manifest at ${abs} is invalid:
+    throw new ProjectError(`Manifest at ${abs} is invalid:
 ${issues}`);
   }
   const styleIds = new Set(Object.keys(parsed.data.styles));
@@ -4292,7 +4376,7 @@ ${issues}`);
   };
   for (const assetId of Object.keys(parsed.data.assets)) visitRevision(assetId, []);
   if (unknownReferences.length) {
-    throw new Error(`Manifest at ${abs} is invalid:
+    throw new ProjectError(`Manifest at ${abs} is invalid:
 ${unknownReferences.map((i) => `  ${i}`).join("\n")}`);
   }
   return { manifest: parsed.data, root: import_node_path5.default.dirname(abs), path: abs };
@@ -4371,14 +4455,14 @@ async function resolveSpecs(loaded, filter) {
   );
   for (const unknownStyle of filter?.styles ?? []) {
     if (!manifest.styles[unknownStyle]) {
-      throw new Error(
+      throw new UsageError(
         `Unknown style "${unknownStyle}". Defined: ${Object.keys(manifest.styles).join(", ") || "(none)"}`
       );
     }
   }
   for (const unknownAsset of filter?.assets ?? []) {
     if (!manifest.assets[unknownAsset]) {
-      throw new Error(`Unknown asset "${unknownAsset}".`);
+      throw new UsageError(`Unknown asset "${unknownAsset}".`);
     }
   }
   const requestedAssetIds = new Set(filter?.assets?.length ? filter.assets : Object.keys(manifest.assets));
@@ -4989,10 +5073,11 @@ async function writeManagedArtifactBundle(manifestPath, outputs, provenance, opt
       if (!expected || digest(current) !== expected) conflicts.push(destination);
     }
     if (conflicts.length) {
-      throw new Error(
+      throw new OverwriteRefusedError(
         `Refusing to overwrite modified or unowned artifact file(s):
 ` + conflicts.map((file) => `  ${file}`).join("\n") + `
-Pass { force: true } (CLI: --force) to take ownership and replace the complete bundle.`
+Pass { force: true } (CLI: --force) to take ownership and replace the complete bundle.`,
+        conflicts
       );
     }
   }
@@ -6790,8 +6875,9 @@ async function installRecipe(target, options = {}) {
       if (!(0, import_node_fs11.existsSync)(file.path)) continue;
       const current = await (0, import_promises7.readFile)(file.path);
       if (!current.equals(file.data)) {
-        throw new Error(
-          `Recipe destination has local changes: ${file.path}. Choose another --out or pass --force to replace declared recipe files.`
+        throw new OverwriteRefusedError(
+          `Recipe destination has local changes: ${file.path}. Choose another --out or pass --force to replace declared recipe files.`,
+          [file.path]
         );
       }
     }
@@ -7058,7 +7144,10 @@ async function snapshotQualityBaseline(inputs, baselinePath, options = {}) {
   if ((0, import_node_fs12.existsSync)(absolute) && !options.force) {
     const current = await (0, import_promises8.readFile)(absolute);
     if (!current.equals(data)) {
-      throw new Error(`Quality baseline already exists with different content: ${absolute}. Pass --force to replace it.`);
+      throw new OverwriteRefusedError(
+        `Quality baseline already exists with different content: ${absolute}. Pass --force to replace it.`,
+        [absolute]
+      );
     }
   }
   const result = await writeArtifactBundle([{ path: absolute, data }]);
@@ -7583,8 +7672,9 @@ async function revertGeneration(provider, spec, lock, lockPath, opts) {
     const file = currentEntryOutputPath(entry, spec, i);
     if (!(0, import_node_fs15.existsSync)(file)) continue;
     if (await sha256File(file) !== entry.outputs[i].sha256 && !opts.force) {
-      throw new Error(
-        `${import_node_path18.default.relative(process.cwd(), file)} was changed after download; keep it with pixelkiln edit, or pass --force to replace it`
+      throw new OverwriteRefusedError(
+        `${import_node_path18.default.relative(process.cwd(), file)} was changed after download; keep it with pixelkiln edit, or pass --force to replace it`,
+        [file]
       );
     }
   }
@@ -8334,7 +8424,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
   if (opts.budget != null) {
     const cost = [...estimates.values()].reduce((sum, estimate) => sum + estimate.amount, 0);
     if (cost > opts.budget) {
-      throw new Error(
+      throw new BudgetError(
         `This run would spend ${formatCost(unit, cost)} but the budget is ${formatCost(unit, opts.budget)}. Narrow it with --only/--style, or raise --budget.`
       );
     }
@@ -9661,7 +9751,7 @@ var WorkspaceSchema = import_zod6.z.object({
 function parseWorkspace(raw) {
   const parsed = WorkspaceSchema.safeParse(raw);
   if (parsed.success) return parsed.data;
-  throw new Error(
+  throw new ProjectError(
     `Workspace catalog is not valid v1:
 ${parsed.error.issues.slice(0, 5).map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n")}`
   );
@@ -9672,7 +9762,7 @@ async function loadWorkspace(workspacePath) {
   try {
     raw = JSON.parse(await (0, import_promises17.readFile)(workspacePath, "utf8"));
   } catch (err) {
-    throw new Error(
+    throw new ProjectError(
       `Workspace catalog at ${workspacePath} is malformed:
 ${err instanceof Error ? err.message : String(err)}`
     );
@@ -12465,6 +12555,7 @@ async function workspaceStatus(ws, dir) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AssetSchema,
+  BudgetError,
   ComfyUIProvider,
   DEFAULT_HISTORY_LIMIT,
   DEFAULT_QUALITY_TOLERANCES,
@@ -12472,6 +12563,7 @@ async function workspaceStatus(ws, dir) {
   DEFAULT_TIMEOUT_MS,
   EDITOR_PIN,
   EDITOR_RELEASE_BASE,
+  EXIT_CODES,
   EditorInstallError,
   FAKE_PNG,
   FakeProvider,
@@ -12496,11 +12588,15 @@ async function workspaceStatus(ws, dir) {
   ManifestInputSchema,
   ManifestSchema,
   MediaType,
+  OverwriteRefusedError,
   PIXEL_ART_FIXER_REVISION,
   PIXEL_ART_FIXER_URL,
+  PixelKilnError,
   PixelLabClient,
   PixelLabError,
   PixelLabProvider,
+  ProjectError,
+  ProviderError,
   QualityBaselineSchema,
   QualityProfileSchema,
   QualityToleranceSchema,
@@ -12512,6 +12608,7 @@ async function workspaceStatus(ws, dir) {
   StyleInputSchema,
   StyleSchema,
   UnsupportedCapabilityError,
+  UsageError,
   WorkspaceProjectSchema,
   WorkspaceSchema,
   adopt,
@@ -12549,7 +12646,9 @@ async function workspaceStatus(ws, dir) {
   editorRoute,
   editorStatus,
   editorToolsRoot,
+  errorCode,
   evaluateAudit,
+  exitCodeFor,
   expectedOutputPath,
   exportTileset,
   fallbackOutputRole,