pixelkiln 0.16.0 → 0.17.0

package/README.md

@@ -55,10 +55,10 @@ PixelKiln keeps the missing record:
 | Workflow | What PixelKiln provides |
 |---|---|
 | Plan and budget | Offline manifest/lock/disk diff, provider-grouped estimates, keyed mixed-provider budget ceilings, JSON/CI gate. |
-| Generate and review | Resumable submit/poll/pick/fetch pipeline with a fast local candidate sheet. |
+| Generate and review | Resumable submit/poll/pick/fetch pipeline, exact next-step hints, and a fast local candidate sheet. |
 | Controlled revisions | Hashed image-to-image/inpaint lineage, fail-closed parent approval, and source-versus-candidate review; ComfyUI is the first adapter. |
 | Existing-art onboarding | Manifest scaffolding, exact-hash account adoption, and prompt recovery. |
-| Recovery | Validated local content cache, durable provider-reference restore, account object-hash cache, and resumable jobs. |
+| Recovery | Safe stale-output replacement, validated caches, durable references, and resumable paid jobs. |
 | Shared-account safety | Cross-project claim files or a registered workspace catalog, sibling-style exclusion, reviewed salvage, keep/discard tags, separate confirmed purge. |
 | Quality control | Manifest-native grid recovery, closed palettes, named approval, regression baselines, and fail-closed packaging. |
 | Sprite packaging | Deterministic RGBA packing, stable-cell mounting, explicit external input lists, structural output roles. |

package/dist/cli.d.ts

@@ -4,8 +4,23 @@ import { z } from 'zod';
 declare const GridConfidenceSchema: z.ZodEnum<["low", "medium", "high"]>;
 type GridConfidence = z.infer<typeof GridConfidenceSchema>;
 
+interface ReviewReadyInfo {
+    url: string;
+    keys: string[];
+}
+
 type TilesetFormat = "generic" | "tiled" | "godot";
 
+interface CliWritable {
+    isTTY?: boolean;
+    write(chunk: string): unknown;
+}
+/**
+ * Interactive readiness is progress, not command output. Keep it on stdout in
+ * a terminal, but use stderr when stdout is piped so consumers such as `tail`
+ * cannot hold the only copy of the live URL until the server exits.
+ */
+declare function announceReviewReady(info: ReviewReadyInfo, stdout?: CliWritable, stderr?: CliWritable): void;
 interface Args {
     command: string;
     manifest: string;
@@ -76,4 +91,4 @@ declare const COMMANDS: readonly ["init", "plan", "doctor", "gen", "submit", "po
  */
 declare function parseArgs(argv: string[]): Args;
 
-export { COMMANDS, parseArgs };
+export { COMMANDS, announceReviewReady, parseArgs };

package/dist/cli.js

@@ -1550,7 +1550,9 @@ var QualityProfileSchema = z2.object({
   /** Optional alpha requirement for isolated assets. */
   minTransparency: z2.number().min(0).max(1).optional(),
   /** Pixel Art Fixer revision written into the quality record. */
-  fixerRevision: z2.string().min(1).optional()
+  fixerRevision: z2.string().min(1).optional(),
+  /** Python executable containing Pixel Art Fixer, relative to the manifest unless absolute. */
+  fixerPython: z2.string().min(1).optional()
 }).strict().refine(
   (profile) => new Set(profile.palette.map((color) => color.replace(/^#/, "").toLowerCase())).size === profile.palette.length,
   { message: "quality palette colors must be unique", path: ["palette"] }
@@ -1804,6 +1806,18 @@ var LockEntrySchema = z2.object({
     maskSha256: z2.string().regex(/^[0-9a-f]{64}$/).optional(),
     strength: z2.number().min(0).max(1).optional()
   }).strict().nullable().default(null),
+  /**
+   * Output hashes owned by the previous generation while its replacement is
+   * pending. They authorize replacing only unchanged PixelKiln-owned files.
+   */
+  supersededOutputs: z2.array(
+    z2.object({
+      path: z2.string(),
+      sha256: z2.string(),
+      role: z2.string().optional(),
+      mediaType: MediaTypeSchema.optional()
+    })
+  ).optional(),
   /** Set at submit time, before the request is awaited, so a crash is recoverable. */
   jobId: z2.string().nullable().default(null),
   /** For `1dir`: the multi-candidate parent object awaiting selection. */
@@ -3273,7 +3287,8 @@ async function resolveSpecs(loaded, filter) {
             palette: style.quality.palette,
             minGridConfidence: style.quality.minGridConfidence,
             ...style.quality.minTransparency == null ? {} : { minTransparency: style.quality.minTransparency },
-            ...style.quality.fixerRevision ? { fixerRevision: style.quality.fixerRevision } : {}
+            ...style.quality.fixerRevision ? { fixerRevision: style.quality.fixerRevision } : {},
+            ...style.quality.fixerPython ? { fixerPython: path4.resolve(root, style.quality.fixerPython) } : {}
           }
         } : {},
         tags,
@@ -5075,7 +5090,9 @@ async function refineQualityProfiles(specs, lock, options = {}) {
         minGridConfidence: spec.quality.minGridConfidence,
         ...spec.quality.minTransparency == null ? {} : { minTransparency: spec.quality.minTransparency },
         fixerRevision: spec.quality.fixerRevision ?? PIXEL_ART_FIXER_REVISION,
-        fixerPython: options.fixerPython,
+        // A one-off CLI/library override wins; otherwise each style can carry
+        // the stable project-local interpreter that provides its pinned fixer.
+        fixerPython: options.fixerPython ?? spec.quality.fixerPython,
         fixerCommand: options.fixerCommand,
         fixerArgsPrefix: options.fixerArgsPrefix,
         force: options.force
@@ -5199,6 +5216,29 @@ async function anyOutputModified(entry, spec) {
   }
   return false;
 }
+function resumeCommandForStatus(status) {
+  if (status === "pending" || status === "processing") return "poll";
+  if (status === "review") return "pick";
+  if (status === "selected" || status === "download-failed") return "fetch";
+  return null;
+}
+function resumeActions(specs, lock) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const spec of specs) {
+    const key = lockKey(spec.styleId, spec.assetId);
+    const entry = lock.entries[key];
+    if (!entry || entry.specHash !== spec.specHash) continue;
+    const command = resumeCommandForStatus(entry.status);
+    if (!command) continue;
+    if (command === "poll" && !entry.jobId) continue;
+    if (command === "pick" && !entry.reviewObjectId) continue;
+    grouped.set(command, [...grouped.get(command) ?? [], key]);
+  }
+  return ["poll", "pick", "fetch"].flatMap((command) => {
+    const keys = grouped.get(command);
+    return keys?.length ? [{ command, keys }] : [];
+  });
+}
 async function buildPlan(specs, lock, opts = {}) {
   const items = [];
   for (const spec of specs) {
@@ -5234,10 +5274,20 @@ async function buildPlan(specs, lock, opts = {}) {
       reason = "prompt, size, or style changed";
     } else if (entry.status === "download-failed") {
       state = "recoverable";
-      reason = `${entry.error ?? "download failed"}; run fetch or restore (no generation cost)`;
+      const force = entry.error?.includes("pass --force") ? " --force" : "";
+      reason = `${entry.error ?? "download failed"}; run pixelkiln fetch${force} (no generation cost)`;
     } else if (entry.status === "failed") {
       state = "failed";
       reason = entry.error ?? "previous attempt failed";
+    } else if (entry.status === "selected") {
+      state = "recoverable";
+      reason = "provider output is selected; run pixelkiln fetch (no generation cost)";
+    } else if (entry.status === "pending" || entry.status === "processing") {
+      state = "in-flight";
+      reason = entry.jobId ? "awaiting processing; run pixelkiln poll" : "submission state has no job id; run pixelkiln doctor before retrying";
+    } else if (entry.status === "review") {
+      state = "in-flight";
+      reason = entry.reviewObjectId ? "awaiting review; run pixelkiln pick" : "review state has no review object id; run pixelkiln doctor";
     } else if (entry.status !== "downloaded") {
       state = "in-flight";
       reason = `awaiting ${entry.status}`;
@@ -5374,6 +5424,8 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
     const since = Date.now() - lastSubmitAt;
     if (since < spacing) await sleep2(spacing - since);
     await requireRevisionReady(spec, lock);
+    const previousEntry = lock.entries[key];
+    const supersededOutputs = previousEntry?.outputs.length ? previousEntry.outputs : previousEntry?.supersededOutputs ?? [];
     upsert(lock, key, {
       styleId: spec.styleId,
       assetId: spec.assetId,
@@ -5397,6 +5449,9 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
       candidateIndex: null,
       error: null,
       outputs: [],
+      // Keep the old ownership proof while new bytes are pending. Fetch may
+      // replace that file only while its hash still matches this record.
+      supersededOutputs,
       providerMetadata: {},
       sourceUrl: null,
       sourceUrls: [],
@@ -5607,22 +5662,37 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
           );
           const target = recorded ? resolveOutputPath(recorded.path, spec.root) : expectedOutputPath(spec, source.role, index, sources.length, source.mediaType);
           if (existsSync9(target)) {
-            if (!recorded) {
-              throw new Error(`refusing to overwrite untracked output ${target}`);
-            }
-            if (await sha256File(target) !== recorded.sha256) {
-              throw new Error(`refusing to overwrite modified output ${target}`);
+            const currentHash = await sha256File(target);
+            if (recorded && currentHash === recorded.sha256) {
+              if (cacheDir) {
+                await cacheMedia(
+                  cacheDir,
+                  await readFile7(target),
+                  recorded.mediaType ?? MediaType.PNG,
+                  recorded.sha256
+                );
+              }
+              outputs.push({ ...recorded, path: portableOutputPath(target, spec.root) });
+              continue;
             }
-            if (cacheDir) {
-              await cacheMedia(
-                cacheDir,
-                await readFile7(target),
-                recorded.mediaType ?? MediaType.PNG,
-                recorded.sha256
-              );
+            const superseded = (entry.supersededOutputs ?? []).find(
+              (output, oldIndex, all) => currentOutputPath(output, spec, oldIndex, all.length) === target
+            );
+            if (!opts.force) {
+              if (!recorded && superseded && currentHash === superseded.sha256) {
+              } else if (recorded || superseded) {
+                throw new Error(
+                  `refusing to overwrite modified output ${target}; pass --force to replace it`
+                );
+              } else {
+                throw new Error(
+                  `refusing to overwrite untracked output ${target}; pass --force to replace it`
+                );
+              }
             }
-            outputs.push({ ...recorded, path: portableOutputPath(target, spec.root) });
-            continue;
+            log2(
+              `  replace ${path14.relative(process.cwd(), target)}` + (opts.force ? " (--force)" : " (previous tracked generation)")
+            );
           }
           const expectedMediaType = source.mediaType ?? recorded?.mediaType ?? MediaType.PNG;
           let buf = recorded && cacheDir ? await readCachedMedia(cacheDir, recorded.sha256, expectedMediaType) : null;
@@ -5670,7 +5740,8 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
           sourceUrl: persistentSources[0]?.url ?? null,
           sourceUrls: persistentSources,
           downloadedAt: (/* @__PURE__ */ new Date()).toISOString(),
-          error: null
+          error: null,
+          supersededOutputs: []
         });
         result.downloaded++;
       } catch (err) {
@@ -5841,6 +5912,14 @@ async function doctor(loaded, specs, lock, lockPath, opts = {}) {
     unsettled ? "warning" : "ok",
     unsettled ? `${unsettled} spec(s) are not current: ` + Object.entries(counts).filter(([, n]) => n > 0).map(([state, n]) => `${n} ${state}`).join(", ") : "every resolved spec is current"
   );
+  const resumable = resumeActions(specs, lock);
+  add(
+    "next-actions",
+    resumable.length ? "warning" : "ok",
+    resumable.length ? "resume paid work without regenerating: " + resumable.map(
+      (action) => `pixelkiln ${action.command} (${action.keys.length} asset${action.keys.length === 1 ? "" : "s"})`
+    ).join(", ") : "no generation stage is waiting for poll, pick, or fetch"
+  );
   const quality = plan.items.flatMap((item) => item.quality ? [item.quality] : []);
   const qualityPending = quality.filter((item) => item.state !== "approved");
   if (quality.length) {
@@ -6578,10 +6657,15 @@ async function runPicker(provider, lock, lockPath, opts = {}) {
     onProgress: log2,
     assets: reviewAssets,
     onReady: (url) => {
-      log2(`
+      const info = { url, keys: groups.map((group) => group.key) };
+      if (opts.onReady) {
+        opts.onReady(info);
+      } else {
+        log2(`
   ${groups.length} asset(s) awaiting selection: ${url}`);
-      log2(`  (leave this running; it exits once you apply)
+        log2(`  (leave this running; it exits once you apply)
 `);
+      }
     },
     handleApply: async (body) => {
       const { selections } = body;
@@ -8543,6 +8627,17 @@ async function checkQualityBaseline(baselinePath) {
 
 // src/cli.ts
 var log = (msg = "") => console.log(msg);
+function announceReviewReady(info, stdout = process.stdout, stderr = process.stderr) {
+  const stream = stdout.isTTY ? stdout : stderr;
+  const count = info.keys.length;
+  stream.write(
+    `
+  ${count} asset${count === 1 ? "" : "s"} awaiting selection: ${info.url}
+  (leave this running; it exits once you apply)
+
+`
+  );
+}
 async function provenanceFile(id, file) {
   const absolute = path24.resolve(file);
   return {
@@ -8900,7 +8995,7 @@ Options
   --max-colors <n>    audit: maximum distinct opaque colors
   --sigma <n>         audit: relative outlier cutoff (default: 1.5)
   --palette <hexes>   refine: final comma-separated #rrggbb colors (repeatable)
-  --fixer-python <path>  refine: Python with Pixel Art Fixer installed
+  --fixer-python <path>  refine: override Python with Pixel Art Fixer installed
   --fixer-revision <sha>  refine: Pixel Art Fixer revision to record
   --min-grid-confidence <level>  refine: high (default), medium, or low
   --reviewer <name>   refine approve: human reviewer recorded in provenance
@@ -8914,7 +9009,7 @@ Options
   --budget <n|provider=n>  Refuse to exceed one provider ceiling; repeat keyed budgets
                            for a mixed-provider run
   --provider <id>     Choose the account for balance/adopt/salvage/purge in a mixed manifest
-  --force             Regenerate; also rerun refinement or replace changed derived state
+  --force             Regenerate, replace a fetch destination, or rebuild managed output
   --dry-run           Never spend; doctor also skips provider connectivity
   --all               salvage --dry-run: list every unclaimed object, not just the first 30
   --json              Machine-readable output where supported, including quality checks
@@ -8997,6 +9092,17 @@ function printPlan(plan) {
     }
   }
 }
+function printResumeActions(specs, lock) {
+  const actions = resumeActions(specs, lock);
+  for (const action of actions) {
+    const shown = action.keys.slice(0, 3).join(", ");
+    const more = action.keys.length > 3 ? `, +${action.keys.length - 3} more` : "";
+    log(
+      `  next: pixelkiln ${action.command} \u2014 ${action.keys.length} asset${action.keys.length === 1 ? "" : "s"} (${shown}${more})`
+    );
+  }
+  return actions.length;
+}
 function manifestProviderIds(manifest) {
   return [...new Set(
     Object.values(manifest.styles).map((style) => style.provider ?? manifest.provider)
@@ -10395,7 +10501,10 @@ async function main() {
   ${total.completed} ready \xB7 ${total.review} awaiting selection \xB7 ${total.failed} failed`
     );
     if (total.failed || total.stillRunning) process.exitCode = 1;
-    if (args.command === "poll") return;
+    if (args.command === "poll") {
+      printResumeActions(specs, lock);
+      return;
+    }
   }
   if (args.command === "pick" || args.command === "gen") {
     const total = { selected: 0, skipped: 0 };
@@ -10404,6 +10513,7 @@ async function main() {
         port: args.port,
         open: !args.noOpen,
         onProgress: log,
+        onReady: announceReviewReady,
         keys: providerSpecsForRun.map((spec) => lockKey(spec.styleId, spec.assetId)),
         specs: providerSpecsForRun
       });
@@ -10417,7 +10527,10 @@ async function main() {
   selected ${total.selected}, left in review ${total.skipped}`);
     }
     if (args.command === "gen" && total.skipped) process.exitCode = 1;
-    if (args.command === "pick") return;
+    if (args.command === "pick") {
+      printResumeActions(specs, lock);
+      return;
+    }
   }
   if (args.command === "fetch" || args.command === "restore" || args.command === "gen") {
     log(`
@@ -10427,7 +10540,8 @@ async function main() {
       const groupProvider = providerFor(providerId);
       const res = await fetchAssets(groupProvider, providerSpecsForRun, lock, args.lock, {
         onProgress: log,
-        repair: args.command === "restore"
+        repair: args.command === "restore",
+        force: args.force
       });
       total.downloaded += res.downloaded;
       total.skipped += res.skipped;
@@ -10446,10 +10560,22 @@ async function main() {
     if (args.tag) log(`  tagged ${total.tagged} object(s) upstream`);
     await saveLock(args.lock, lock);
     log(`  lockfile written: ${args.lock}`);
+    const resumeActionCount = printResumeActions(specs, lock);
     if (args.command === "gen" && specs.some((spec) => spec.quality) && !total.failed) {
-      log(`
+      const quality = (await Promise.all(
+        specs.filter((spec) => spec.quality).map((spec) => inspectQualityProfile(spec, lock))
+      )).filter((item) => item !== null);
+      const blocked = quality.filter((item) => item.state === "blocked");
+      if (blocked.length) {
+        log(
+          `
+  ${blocked.length} quality source${blocked.length === 1 ? " is" : "s are"} not ready; ` + (resumeActionCount ? "finish the resume steps above before refining." : "run `pixelkiln plan` for the blocking reason before refining.")
+        );
+      } else {
+        log(`
   Raw provider output is ready. Run \`pixelkiln refine\` to build the configured quality output.`);
-      log(`  Packaging stays blocked until each refined PNG has a current human approval.`);
+        log(`  Packaging stays blocked until each refined PNG has a current human approval.`);
+      }
     }
     return;
   }
@@ -10463,6 +10589,7 @@ main().catch((err) => {
 });
 export {
   COMMANDS,
+  announceReviewReady,
   parseArgs
 };
 //# sourceMappingURL=cli.js.map