pixelkiln 0.35.0 → 0.36.0

package/dist/index.js

@@ -474,6 +474,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
 import { z as z2 } from "zod";
 
@@ -590,14 +656,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 {
@@ -877,10 +941,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";
   }
@@ -1705,7 +1770,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 = {}) {
@@ -1728,8 +1793,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;
@@ -2121,7 +2188,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`);
@@ -2168,8 +2235,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;
@@ -2619,8 +2688,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) {
@@ -2643,7 +2714,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) {
@@ -2668,8 +2739,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;
@@ -3659,9 +3732,10 @@ async function loadLock(lockPath) {
   try {
     return parseLock(JSON.parse(await readFile2(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 }
     );
   }
 }
@@ -3695,8 +3769,9 @@ async function writeLockWhileHeld(file, lock) {
     try {
       disk = parseLock(JSON.parse(await readFile2(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 }
       );
     }
   }
@@ -3952,18 +4027,18 @@ function resolveSpecOutputs(spec, lock, manifestDir) {
 // src/manifest.ts
 async function loadManifest(manifestPath) {
   const abs = path5.resolve(manifestPath);
-  if (!existsSync4(abs)) throw new Error(`No manifest at ${abs}`);
+  if (!existsSync4(abs)) throw new ProjectError(`No manifest at ${abs}`);
   const input = ManifestInputSchema.safeParse(JSON.parse(await readFile3(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)}`
     );
@@ -3971,7 +4046,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));
@@ -4021,7 +4096,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: path5.dirname(abs), path: abs };
@@ -4100,14 +4175,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));
@@ -4718,10 +4793,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
       );
     }
   }
@@ -6519,8 +6595,9 @@ async function installRecipe(target, options = {}) {
       if (!existsSync10(file.path)) continue;
       const current = await readFile7(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]
         );
       }
     }
@@ -6787,7 +6864,10 @@ async function snapshotQualityBaseline(inputs, baselinePath, options = {}) {
   if (existsSync11(absolute) && !options.force) {
     const current = await readFile8(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 }]);
@@ -7312,8 +7392,9 @@ async function revertGeneration(provider, spec, lock, lockPath, opts) {
     const file = currentEntryOutputPath(entry, spec, i);
     if (!existsSync14(file)) continue;
     if (await sha256File(file) !== entry.outputs[i].sha256 && !opts.force) {
-      throw new Error(
-        `${path17.relative(process.cwd(), file)} was changed after download; keep it with pixelkiln edit, or pass --force to replace it`
+      throw new OverwriteRefusedError(
+        `${path17.relative(process.cwd(), file)} was changed after download; keep it with pixelkiln edit, or pass --force to replace it`,
+        [file]
       );
     }
   }
@@ -8063,7 +8144,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.`
       );
     }
@@ -9390,7 +9471,7 @@ var WorkspaceSchema = z6.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")}`
   );
@@ -9401,7 +9482,7 @@ async function loadWorkspace(workspacePath) {
   try {
     raw = JSON.parse(await readFile16(workspacePath, "utf8"));
   } catch (err) {
-    throw new Error(
+    throw new ProjectError(
       `Workspace catalog at ${workspacePath} is malformed:
 ${err instanceof Error ? err.message : String(err)}`
     );
@@ -12193,6 +12274,7 @@ async function workspaceStatus(ws, dir) {
 }
 export {
   AssetSchema,
+  BudgetError,
   ComfyUIProvider,
   DEFAULT_HISTORY_LIMIT,
   DEFAULT_QUALITY_TOLERANCES,
@@ -12200,6 +12282,7 @@ export {
   DEFAULT_TIMEOUT_MS,
   EDITOR_PIN,
   EDITOR_RELEASE_BASE,
+  EXIT_CODES,
   EditorInstallError,
   FAKE_PNG,
   FakeProvider,
@@ -12224,11 +12307,15 @@ export {
   ManifestInputSchema,
   ManifestSchema,
   MediaType,
+  OverwriteRefusedError,
   PIXEL_ART_FIXER_REVISION,
   PIXEL_ART_FIXER_URL,
+  PixelKilnError,
   PixelLabClient,
   PixelLabError,
   PixelLabProvider,
+  ProjectError,
+  ProviderError,
   QualityBaselineSchema,
   QualityProfileSchema,
   QualityToleranceSchema,
@@ -12240,6 +12327,7 @@ export {
   StyleInputSchema,
   StyleSchema,
   UnsupportedCapabilityError,
+  UsageError,
   WorkspaceProjectSchema,
   WorkspaceSchema,
   adopt,
@@ -12277,7 +12365,9 @@ export {
   editorRoute,
   editorStatus,
   editorToolsRoot,
+  errorCode,
   evaluateAudit,
+  exitCodeFor,
   expectedOutputPath,
   exportTileset,
   fallbackOutputRole,