pixelkiln 0.35.0 → 0.36.0

package/CONTRIBUTING.md

@@ -19,8 +19,15 @@ npm run test:security
 npm test
 npm run build
 npm run test:package
+npm run test:gallery
 ```
 
+`test:gallery` serves a gallery over `FakeProvider` and drives it in headless
+Chrome: the Generate and Regenerate buttons, the busy badge while a job runs,
+the previous generation kept and restored for free, and zero console errors.
+It needs a Chrome or Chromium binary (`CHROME=/path/to/chrome` when it is not
+in a usual place) and skips without one outside CI.
+
 The Next.js marketing/documentation site is isolated in `website/`:
 
 ```bash

package/dist/cli.js

@@ -1,5 +1,71 @@
 #!/usr/bin/env node
 
+// 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/cli/main.ts
 import { existsSync as existsSync31 } from "fs";
 import { readFile as readFile27 } from "fs/promises";
@@ -103,7 +169,7 @@ var TOOLS = ["editor"];
 function parseArgs(argv) {
   const [command = "help"] = argv;
   if (!COMMANDS.includes(command)) {
-    throw new Error(`Unknown command "${command}". Run \`pixelkiln help\` for the list.`);
+    throw new UsageError(`Unknown command "${command}". Run \`pixelkiln help\` for the list.`);
   }
   let rest = argv.slice(1);
   let subcommand;
@@ -111,10 +177,10 @@ function parseArgs(argv) {
   if (command === "quality") {
     subcommand = rest[0];
     if (subcommand === void 0 || subcommand.startsWith("-")) {
-      throw new Error(`quality needs a subcommand: ${QUALITY_SUBCOMMANDS.join(", ")}`);
+      throw new UsageError(`quality needs a subcommand: ${QUALITY_SUBCOMMANDS.join(", ")}`);
     }
     if (!QUALITY_SUBCOMMANDS.includes(subcommand)) {
-      throw new Error(
+      throw new UsageError(
         `Unknown quality subcommand "${subcommand}". Known: ${QUALITY_SUBCOMMANDS.join(", ")}`
       );
     }
@@ -122,10 +188,10 @@ function parseArgs(argv) {
   } else if (command === "recipe") {
     subcommand = rest[0];
     if (subcommand === void 0 || subcommand.startsWith("-")) {
-      throw new Error(`recipe needs a subcommand: ${RECIPE_SUBCOMMANDS.join(", ")}`);
+      throw new UsageError(`recipe needs a subcommand: ${RECIPE_SUBCOMMANDS.join(", ")}`);
     }
     if (!RECIPE_SUBCOMMANDS.includes(subcommand)) {
-      throw new Error(
+      throw new UsageError(
         `Unknown recipe subcommand "${subcommand}". Known: ${RECIPE_SUBCOMMANDS.join(", ")}`
       );
     }
@@ -133,17 +199,17 @@ function parseArgs(argv) {
     if (subcommand !== "list") {
       target = rest[0];
       if (target === void 0 || target.startsWith("-")) {
-        throw new Error(`recipe ${subcommand} needs a recipe id, selector, or path.`);
+        throw new UsageError(`recipe ${subcommand} needs a recipe id, selector, or path.`);
       }
       rest = rest.slice(1);
     }
   } else if (command === "workspace") {
     subcommand = rest[0];
     if (subcommand === void 0 || subcommand.startsWith("-")) {
-      throw new Error(`workspace needs a subcommand: ${WORKSPACE_SUBCOMMANDS.join(", ")}`);
+      throw new UsageError(`workspace needs a subcommand: ${WORKSPACE_SUBCOMMANDS.join(", ")}`);
     }
     if (!WORKSPACE_SUBCOMMANDS.includes(subcommand)) {
-      throw new Error(
+      throw new UsageError(
         `Unknown workspace subcommand "${subcommand}". Known: ${WORKSPACE_SUBCOMMANDS.join(", ")}`
       );
     }
@@ -151,7 +217,7 @@ function parseArgs(argv) {
     if (subcommand === "add" || subcommand === "remove") {
       target = rest[0];
       if (target === void 0 || target.startsWith("-")) {
-        throw new Error(
+        throw new UsageError(
           subcommand === "add" ? "workspace add needs a manifest path." : "workspace remove needs a project id or manifest path."
         );
       }
@@ -160,29 +226,29 @@ function parseArgs(argv) {
   } else if (command === "edit") {
     subcommand = rest[0]?.startsWith("-") || rest[0] === void 0 ? "start" : rest[0];
     if (!EDIT_SUBCOMMANDS.includes(subcommand)) {
-      throw new Error(`Unknown edit subcommand "${subcommand}". Known: ${EDIT_SUBCOMMANDS.join(", ")}`);
+      throw new UsageError(`Unknown edit subcommand "${subcommand}". Known: ${EDIT_SUBCOMMANDS.join(", ")}`);
     }
     if (rest[0] === subcommand) rest = rest.slice(1);
   } else if (command === "tools") {
     subcommand = rest[0]?.startsWith("-") || rest[0] === void 0 ? "status" : rest[0];
     if (!TOOLS_SUBCOMMANDS.includes(subcommand)) {
-      throw new Error(`Unknown tools subcommand "${subcommand}". Known: ${TOOLS_SUBCOMMANDS.join(", ")}`);
+      throw new UsageError(`Unknown tools subcommand "${subcommand}". Known: ${TOOLS_SUBCOMMANDS.join(", ")}`);
     }
     if (rest[0] === subcommand) rest = rest.slice(1);
     target = rest[0]?.startsWith("-") ? void 0 : rest[0];
     if (subcommand === "install" && target === void 0) {
-      throw new Error(`tools install needs a tool name: ${TOOLS.join(", ")}`);
+      throw new UsageError(`tools install needs a tool name: ${TOOLS.join(", ")}`);
     }
     if (target !== void 0) {
       if (!TOOLS.includes(target)) {
-        throw new Error(`Unknown tool "${target}". Known: ${TOOLS.join(", ")}`);
+        throw new UsageError(`Unknown tool "${target}". Known: ${TOOLS.join(", ")}`);
       }
       rest = rest.slice(1);
     }
   } else if (command === "refine") {
     subcommand = rest[0]?.startsWith("-") || rest[0] === void 0 ? "run" : rest[0];
     if (!REFINE_SUBCOMMANDS.includes(subcommand)) {
-      throw new Error(
+      throw new UsageError(
         `Unknown refine subcommand "${subcommand}". Known: ${REFINE_SUBCOMMANDS.join(", ")}`
       );
     }
@@ -191,19 +257,19 @@ function parseArgs(argv) {
   for (let i = 0; i < rest.length; i++) {
     const token = rest[i];
     if (!token.startsWith("-")) {
-      throw new Error(`Unexpected argument "${token}". Options must be passed with a named flag.`);
+      throw new UsageError(`Unexpected argument "${token}". Options must be passed with a named flag.`);
     }
     if (BOOL_FLAGS.includes(token)) continue;
     if (VALUE_FLAGS.includes(token)) {
       const value = rest[i + 1];
       const looksLikeFlag = value !== void 0 && value.startsWith("-") && !Number.isFinite(Number(value));
       if (value === void 0 || looksLikeFlag) {
-        throw new Error(`${token} needs a value.`);
+        throw new UsageError(`${token} needs a value.`);
       }
       i++;
       continue;
     }
-    throw new Error(
+    throw new UsageError(
       `Unknown flag "${token}". Known flags: ${[...VALUE_FLAGS, ...BOOL_FLAGS].join(", ")}`
     );
   }
@@ -227,7 +293,7 @@ function parseArgs(argv) {
   if (rawColumns !== void 0) {
     columns = Number(rawColumns);
     if (!Number.isInteger(columns) || columns < 1 || columns > 1024) {
-      throw new Error(`--columns must be a whole number between 1 and 1024, got "${rawColumns}"`);
+      throw new UsageError(`--columns must be a whole number between 1 and 1024, got "${rawColumns}"`);
     }
   }
   const rawPort = get("--port");
@@ -235,7 +301,7 @@ function parseArgs(argv) {
   if (rawPort !== void 0) {
     port = Number(rawPort);
     if (!Number.isInteger(port) || port < 1 || port > 65535) {
-      throw new Error(`--port must be a whole number between 1 and 65535, got "${rawPort}"`);
+      throw new UsageError(`--port must be a whole number between 1 and 65535, got "${rawPort}"`);
     }
   }
   let budget;
@@ -248,30 +314,30 @@ function parseArgs(argv) {
       const rawAmount = rawBudget.slice(separator + 1).trim();
       const amount2 = Number(rawAmount);
       if (!providerId || /[=\s]/.test(providerId) || !Number.isFinite(amount2) || amount2 < 0) {
-        throw new Error(
+        throw new UsageError(
           `--budget must be a non-negative number or provider=number, got "${rawBudget}".`
         );
       }
       if (Object.hasOwn(providerBudgets, providerId)) {
-        throw new Error(`--budget repeats provider "${providerId}".`);
+        throw new UsageError(`--budget repeats provider "${providerId}".`);
       }
       providerBudgets[providerId] = amount2;
       continue;
     }
     const amount = Number(rawBudget);
     if (!Number.isFinite(amount) || amount < 0) {
-      throw new Error(`--budget must be a non-negative number, got "${rawBudget}".`);
+      throw new UsageError(`--budget must be a non-negative number, got "${rawBudget}".`);
     }
-    if (budget !== void 0) throw new Error("Only one unkeyed --budget may be passed.");
+    if (budget !== void 0) throw new UsageError("Only one unkeyed --budget may be passed.");
     budget = amount;
   }
   if (budget !== void 0 && Object.keys(providerBudgets).length) {
-    throw new Error("Do not mix an unkeyed --budget with provider-keyed budgets.");
+    throw new UsageError("Do not mix an unkeyed --budget with provider-keyed budgets.");
   }
   const manifest = get("--manifest") ?? "pixelkiln.manifest.json";
   const rawFormat = get("--format");
   if (rawFormat && rawFormat !== "generic" && rawFormat !== "tiled" && rawFormat !== "godot") {
-    throw new Error(`--format must be generic, tiled, or godot, got "${rawFormat}"`);
+    throw new UsageError(`--format must be generic, tiled, or godot, got "${rawFormat}"`);
   }
   const numberOption = (flag, opts) => {
     const raw = get(flag);
@@ -279,13 +345,13 @@ function parseArgs(argv) {
     const value = Number(raw);
     if (!Number.isFinite(value) || value < opts.min || opts.max !== void 0 && value > opts.max || opts.integer && !Number.isInteger(value)) {
       const range = opts.max === void 0 ? `at least ${opts.min}` : `${opts.min} to ${opts.max}`;
-      throw new Error(`${flag} must be ${opts.integer ? "a whole number " : "a number "}${range}, got "${raw}"`);
+      throw new UsageError(`${flag} must be ${opts.integer ? "a whole number " : "a number "}${range}, got "${raw}"`);
     }
     return value;
   };
   const rawGridConfidence = get("--min-grid-confidence");
   if (rawGridConfidence !== void 0 && rawGridConfidence !== "low" && rawGridConfidence !== "medium" && rawGridConfidence !== "high") {
-    throw new Error(
+    throw new UsageError(
       `--min-grid-confidence must be low, medium, or high, got "${rawGridConfidence}"`
     );
   }
@@ -505,10 +571,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";
   }
@@ -1086,9 +1153,10 @@ async function loadLock(lockPath) {
   try {
     return parseLock(JSON.parse(await 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 }
     );
   }
 }
@@ -1122,8 +1190,9 @@ async function writeLockWhileHeld(file, lock) {
     try {
       disk = parseLock(JSON.parse(await 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 }
       );
     }
   }
@@ -2051,10 +2120,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
       );
     }
   }
@@ -3706,8 +3776,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) {
@@ -3730,7 +3802,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) {
@@ -3755,8 +3827,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;
@@ -4592,14 +4666,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 {
@@ -5180,7 +5252,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(path43, init = {}) {
@@ -5203,8 +5275,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;
@@ -5596,7 +5670,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`);
@@ -5643,8 +5717,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;
@@ -6043,18 +6119,18 @@ import { existsSync as existsSync9 } from "fs";
 import path13 from "path";
 async function loadManifest(manifestPath) {
   const abs = path13.resolve(manifestPath);
-  if (!existsSync9(abs)) throw new Error(`No manifest at ${abs}`);
+  if (!existsSync9(abs)) throw new ProjectError(`No manifest at ${abs}`);
   const input = ManifestInputSchema.safeParse(JSON.parse(await readFile6(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)}`
     );
@@ -6062,7 +6138,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));
@@ -6112,7 +6188,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: path13.dirname(abs), path: abs };
@@ -6191,14 +6267,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));
@@ -7232,7 +7308,7 @@ var WorkspaceSchema = z4.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")}`
   );
@@ -7243,7 +7319,7 @@ async function loadWorkspace(workspacePath) {
   try {
     raw = JSON.parse(await readFile11(workspacePath, "utf8"));
   } catch (err) {
-    throw new Error(
+    throw new ProjectError(
       `Workspace catalog at ${workspacePath} is malformed:
 ${err instanceof Error ? err.message : String(err)}`
     );
@@ -7885,14 +7961,14 @@ function accountProviderId(manifest, requested, command) {
   const providers = manifestProviderIds(manifest);
   if (requested) {
     if (!providers.includes(requested)) {
-      throw new Error(
+      throw new UsageError(
         `Provider "${requested}" is not used by this manifest. Used: ${providers.join(", ")}.`
       );
     }
     return requested;
   }
   if (providers.length > 1) {
-    throw new Error(
+    throw new UsageError(
       `${command} is account-scoped and this manifest uses ${providers.join(", ")}. Pass --provider <id>.`
     );
   }
@@ -7903,13 +7979,13 @@ function budgetsForPlan(plan, args) {
   const keyed = Object.entries(args.providerBudgets);
   for (const [provider] of keyed) {
     if (!providerIds.has(provider)) {
-      throw new Error(
+      throw new BudgetError(
         `Budget names provider "${provider}", but this run has work only for ${[...providerIds].join(", ") || "no providers"}.`
       );
     }
   }
   if (plan.groups.length > 1 && args.budget !== void 0) {
-    throw new Error(
+    throw new BudgetError(
       "A mixed-provider run needs provider-keyed budgets, for example --budget pixellab=40 --budget retrodiffusion=1.25."
     );
   }
@@ -7917,7 +7993,7 @@ function budgetsForPlan(plan, args) {
   for (const group of plan.groups) {
     const ceiling = args.providerBudgets[group.provider];
     if (plan.groups.length > 1 && group.costUnit !== "free" && group.cost > 0 && ceiling === void 0) {
-      throw new Error(
+      throw new BudgetError(
         `Mixed-provider run is missing --budget ${group.provider}=<amount> for ${formatCost(group.costUnit, group.cost)} of planned work.`
       );
     }
@@ -7927,14 +8003,14 @@ function budgetsForPlan(plan, args) {
 }
 async function requireCompleteWorkspaceClaims(workspacePath) {
   if (!existsSync15(workspacePath)) {
-    throw new Error(`Workspace catalog not found: ${workspacePath}`);
+    throw new ProjectError(`Workspace catalog not found: ${workspacePath}`);
   }
   const dir = path20.dirname(path20.resolve(workspacePath));
   const ws = await loadWorkspace(workspacePath);
   const diagnostics = validateWorkspace(ws, dir);
   const errors = diagnostics.filter((d) => d.level === "error");
   if (errors.length) {
-    throw new Error(
+    throw new ProjectError(
       `Workspace catalog at ${workspacePath} is not safe to derive a claim set from:
 ` + errors.map((d) => `  ${d.id}: ${d.message}`).join("\n")
     );
@@ -7953,7 +8029,7 @@ async function openAccountProject(args) {
 }
 async function open(args) {
   if (!existsSync15(path20.resolve(args.manifest))) {
-    throw new Error(
+    throw new ProjectError(
       `No manifest at ${path20.resolve(args.manifest)}. Pass --manifest, or run \`pixelkiln init --from <dir>\`.`
     );
   }
@@ -7962,7 +8038,7 @@ async function open(args) {
   let specs = project.specs;
   const accountProvider = ACCOUNT_COMMANDS.has(args.command) ? accountProviderId(loaded.manifest, args.provider, args.command) : void 0;
   if (args.provider && !accountProvider) {
-    throw new Error("--provider is only used by balance, adopt, salvage, purge, or workspace add.");
+    throw new UsageError("--provider is only used by balance, adopt, salvage, purge, or workspace add.");
   }
   if (accountProvider) specs = specs.filter((spec) => spec.provider === accountProvider);
   const accountManifest = accountProvider ? {
@@ -7975,7 +8051,7 @@ async function open(args) {
     )
   } : loaded.manifest;
   if (accountProvider && args.styles.some((styleId) => !accountManifest.styles[styleId])) {
-    throw new Error(`Selected style is not assigned to provider "${accountProvider}".`);
+    throw new UsageError(`Selected style is not assigned to provider "${accountProvider}".`);
   }
   return { loaded, specs, lock, accountProvider, accountManifest };
 }
@@ -9010,8 +9086,9 @@ async function revertGeneration(provider, spec, lock, lockPath, opts) {
     const file = currentEntryOutputPath(entry, spec, i);
     if (!existsSync18(file)) continue;
     if (await sha256File(file) !== entry.outputs[i].sha256 && !opts.force) {
-      throw new Error(
-        `${path26.relative(process.cwd(), file)} was changed after download; keep it with pixelkiln edit, or pass --force to replace it`
+      throw new OverwriteRefusedError(
+        `${path26.relative(process.cwd(), file)} was changed after download; keep it with pixelkiln edit, or pass --force to replace it`,
+        [file]
       );
     }
   }
@@ -10080,7 +10157,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.`
       );
     }
@@ -11690,12 +11767,12 @@ async function runGenerate(args) {
   balance: ${formatCost(balance.unit, balance.remaining)} remaining (${group.provider})`
           );
           if (balance.unit !== group.costUnit) {
-            throw new Error(
+            throw new BudgetError(
               `Provider ${group.provider} estimate unit ${group.costUnit} does not match balance unit ${balance.unit}.`
             );
           }
           if (balance.unit !== "free" && group.cost > balance.remaining) {
-            throw new Error(
+            throw new BudgetError(
               `${group.provider} needs ${formatCost(balance.unit, group.cost)} but only ${formatCost(balance.unit, balance.remaining)} remain.`
             );
           }
@@ -11707,7 +11784,7 @@ async function runGenerate(args) {
         }
         const ceiling = budgets.get(group.provider);
         if (ceiling !== void 0 && group.cost > ceiling) {
-          throw new Error(
+          throw new BudgetError(
             `${group.provider} would spend ${formatCost(group.costUnit, group.cost)} but its budget is ${formatCost(group.costUnit, ceiling)}.`
           );
         }
@@ -13522,7 +13599,10 @@ async function snapshotQualityBaseline(inputs, baselinePath, options = {}) {
   if (existsSync28(absolute) && !options.force) {
     const current = await readFile24(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 }]);
@@ -14051,8 +14131,9 @@ async function installRecipe(target, options = {}) {
       if (!existsSync29(file.path)) continue;
       const current = await readFile26(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]
         );
       }
     }
@@ -14519,9 +14600,12 @@ async function main(argv = process.argv.slice(2)) {
 
 // src/cli.ts
 main().catch((err) => {
+  const message6 = err instanceof Error ? err.message : String(err);
+  const hint = err instanceof PixelKilnError && err.hint ? `  ${err.hint}
+` : "";
   console.error(`
-  error: ${err instanceof Error ? err.message : String(err)}
-`);
-  process.exit(1);
+  error: ${message6}
+${hint}`);
+  process.exit(exitCodeFor(err));
 });
 //# sourceMappingURL=cli.js.map