pixelkiln 0.17.0 → 0.18.0

package/README.md

@@ -56,7 +56,7 @@ PixelKiln keeps the missing record:
 |---|---|
 | 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, 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. |
+| Controlled inputs | Hashed image-to-image/inpaint lineage, fail-closed parent approval, source-versus-candidate review, and content-addressed per-asset ComfyUI bindings. |
 | Existing-art onboarding | Manifest scaffolding, exact-hash account adoption, and prompt recovery. |
 | 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. |
@@ -356,7 +356,7 @@ exporters, managed artifact writes, and offline provenance verification. See
 | [Getting started](./docs/GETTING_STARTED.md) | First project, existing-art onboarding, everyday workflow, and what to commit. |
 | [Set up PixelLab](./docs/PIXELLAB.md) | Production-provider credentials, manifest, generators, and account workflows. |
 | [Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md) | Experimental-provider credentials, styles, formats, cost checks, and limits. |
-| [Set up ComfyUI](./docs/COMFYUI.md) | Experimental self-hosted server, workflow bindings, local cost semantics, and limits. |
+| [Set up ComfyUI](./docs/COMFYUI.md) | Self-hosted workflows, per-asset input uploads, local cost semantics, and quality limits. |
 | [Set up Scenario](./docs/SCENARIO.md) | Experimental hosted models, two-part credentials, CU preflight, review, and durable downloads. |
 | [Versioned recipes](./docs/RECIPES.md) | Pinned workflow packs, model hashes, manifest templates, and quality contracts. |
 | [Controlled revisions](./docs/REVISIONS.md) | Image-to-image/inpaint parents, masks, fail-closed readiness, provenance, and ComfyUI bindings. |

package/dist/cli.js

@@ -123,13 +123,14 @@ async function sha256File(path25) {
     stream.on("end", () => resolve(hash.digest("hex")));
   });
 }
-function specHash(spec, styleImageHashes, providerOptionIdentity = spec.providerOptions) {
+function specHash(spec, styleImageHashes, providerOptionIdentity = spec.providerOptions, providerInputIdentity = spec.providerInputs ?? {}) {
   return sha256(
     JSON.stringify({
       // Preserve every existing PixelLab hash while making a provider switch
       // invalidate the spec. Older manifests implicitly mean pixellab.
       provider: spec.provider === "pixellab" ? void 0 : spec.provider,
       providerOptions: providerOptionIdentity && (typeof providerOptionIdentity !== "object" || Object.keys(providerOptionIdentity).length > 0) ? providerOptionIdentity : void 0,
+      providerInputs: providerInputIdentity && (typeof providerInputIdentity !== "object" || Object.keys(providerInputIdentity).length > 0) ? providerInputIdentity : void 0,
       generator: spec.generator,
       prompt: spec.prompt,
       width: spec.width,
@@ -604,6 +605,16 @@ function cacheFileName(hash, mediaType = MediaType.PNG) {
 
 // src/providers/comfyui.ts
 var DEFAULT_BASE_URL = "http://127.0.0.1:8188";
+var BUILTIN_BINDINGS = /* @__PURE__ */ new Set([
+  "prompt",
+  "width",
+  "height",
+  "batchSize",
+  "seed",
+  "sourceImage",
+  "maskImage",
+  "strength"
+]);
 var ComfyUIClient = class {
   constructor(baseUrl = process.env.COMFYUI_BASE_URL ?? DEFAULT_BASE_URL, request = fetch) {
     this.request = request;
@@ -753,6 +764,63 @@ var ComfyUIProvider = class _ComfyUIProvider {
       }
     };
   }
+  async resolveInputs(value, context) {
+    const options = parseOptions(context.providerOptions);
+    if (!options.workflow || !options.workflowSha256) {
+      throw new Error("ComfyUI provider inputs require resolved workflow options");
+    }
+    const inputs = {};
+    const identity = {};
+    for (const [name, input] of Object.entries(value)) {
+      if (BUILTIN_BINDINGS.has(name)) {
+        throw new Error(
+          `ComfyUI providerInputs.${name} is reserved; use PixelKiln's built-in ${name} field`
+        );
+      }
+      const binding = Object.hasOwn(options.bindings, name) ? options.bindings[name] : void 0;
+      if (!binding) {
+        throw new Error(
+          `ComfyUI providerInputs.${name} has no matching bindings.${name} target`
+        );
+      }
+      if (isImageBinding(options.workflow, binding)) {
+        if (typeof input !== "string") {
+          throw new Error(`ComfyUI providerInputs.${name} must be a manifest-relative PNG or JPEG path`);
+        }
+        const file = path2.resolve(context.root, input);
+        let bytes;
+        try {
+          bytes = await readFile(file);
+        } catch (error) {
+          throw new Error(
+            `ComfyUI providerInputs.${name} could not be read at ${file}: ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+        const format = inputImageFormat(bytes);
+        if (!format) {
+          throw new Error(`ComfyUI providerInputs.${name} is not a PNG or JPEG: ${file}`);
+        }
+        const hash = sha256(bytes);
+        inputs[name] = { kind: "image", path: file, sha256: hash, format };
+        identity[name] = { kind: "image", sha256: hash, format };
+      } else {
+        const current = options.workflow[binding.nodeId].inputs[binding.input];
+        if (typeof current !== "string" && typeof current !== "number" && typeof current !== "boolean") {
+          throw new Error(
+            `ComfyUI providerInputs.${name} cannot replace non-scalar ${binding.nodeId}.${binding.input}`
+          );
+        }
+        if (typeof current !== typeof input) {
+          throw new Error(
+            `ComfyUI providerInputs.${name} must be ${typeof current} to match ${binding.nodeId}.${binding.input}`
+          );
+        }
+        inputs[name] = input;
+        identity[name] = input;
+      }
+    }
+    return { inputs, identity };
+  }
   supports(generator) {
     return generator === "map";
   }
@@ -820,6 +888,20 @@ var ComfyUIProvider = class _ComfyUIProvider {
     if (spec.seed != null && options.bindings.seed) {
       setBinding(workflow, options.bindings.seed, spec.seed);
     }
+    for (const [name, input] of Object.entries(spec.providerInputs ?? {})) {
+      const binding = Object.hasOwn(options.bindings, name) ? options.bindings[name] : void 0;
+      if (!binding) throw new Error(`ComfyUI provider input "${name}" has no binding`);
+      if (isComfyImageInput(input)) {
+        const bytes = await readFile(input.path);
+        if (sha256(bytes) !== input.sha256) {
+          throw new Error(`ComfyUI provider input "${name}" changed before upload`);
+        }
+        const uploaded = await this.client.uploadImage(bytes, input.sha256, input.format);
+        setBinding(workflow, binding, uploaded);
+      } else {
+        setBinding(workflow, binding, input);
+      }
+    }
     if (spec.revision) {
       if (!spec.revision.sourceSha256 || !spec.revision.sourceFormat) {
         throw new Error("ComfyUI revision source is not ready");
@@ -854,19 +936,22 @@ var ComfyUIProvider = class _ComfyUIProvider {
       }
     }
     const promptId = await this.client.submit(workflow);
-    return {
-      jobId: encodeJob(promptId, options.outputNodeId),
+    const inputs = providerInputProvenance(spec.providerInputs);
+    const metadata = {
+      ...Object.keys(inputs).length ? { inputs } : {},
       ...spec.revision ? {
-        metadata: {
-          revision: {
-            mode: spec.revision.mode,
-            sourceAssetId: spec.revision.sourceAssetId,
-            sourceSha256: spec.revision.sourceSha256,
-            ...spec.revision.maskSha256 ? { maskSha256: spec.revision.maskSha256 } : {}
-          }
+        revision: {
+          mode: spec.revision.mode,
+          sourceAssetId: spec.revision.sourceAssetId,
+          sourceSha256: spec.revision.sourceSha256,
+          ...spec.revision.maskSha256 ? { maskSha256: spec.revision.maskSha256 } : {}
         }
       } : {}
     };
+    return {
+      jobId: encodeJob(promptId, options.outputNodeId),
+      ...Object.keys(metadata).length ? { metadata } : {}
+    };
   }
   async poll(jobId, _generator, context) {
     const { promptId, outputNodeId } = decodeJob(jobId);
@@ -941,28 +1026,10 @@ function parseOptions(value) {
     throw new Error("ComfyUI numImages must be a whole number from 1 to 16");
   }
   if (!isObject(value.bindings)) throw new Error("ComfyUI bindings must be an object");
-  const bindingKeys = /* @__PURE__ */ new Set([
-    "prompt",
-    "width",
-    "height",
-    "batchSize",
-    "seed",
-    "sourceImage",
-    "maskImage",
-    "strength"
-  ]);
-  const extraBindings = Object.keys(value.bindings).filter((key) => !bindingKeys.has(key));
-  if (extraBindings.length) throw new Error(`Unknown ComfyUI binding(s): ${extraBindings.join(", ")}`);
-  const bindings = {
-    prompt: parseBinding(value.bindings.prompt, "prompt"),
-    ...value.bindings.width == null ? {} : { width: parseBinding(value.bindings.width, "width") },
-    ...value.bindings.height == null ? {} : { height: parseBinding(value.bindings.height, "height") },
-    ...value.bindings.batchSize == null ? {} : { batchSize: parseBinding(value.bindings.batchSize, "batchSize") },
-    ...value.bindings.seed == null ? {} : { seed: parseBinding(value.bindings.seed, "seed") },
-    ...value.bindings.sourceImage == null ? {} : { sourceImage: parseBinding(value.bindings.sourceImage, "sourceImage") },
-    ...value.bindings.maskImage == null ? {} : { maskImage: parseBinding(value.bindings.maskImage, "maskImage") },
-    ...value.bindings.strength == null ? {} : { strength: parseBinding(value.bindings.strength, "strength") }
-  };
+  const bindings = Object.fromEntries(
+    Object.entries(value.bindings).map(([name, binding]) => [name, parseBinding(binding, name)])
+  );
+  if (!bindings.prompt) throw new Error("ComfyUI bindings.prompt must be an object");
   const workflow = value.workflow == null ? void 0 : parseWorkflow(value.workflow, workflowFile);
   const workflowSha256 = value.workflowSha256 == null ? void 0 : requiredString(value.workflowSha256, "workflowSha256");
   return {
@@ -1002,6 +1069,7 @@ function parseWorkflow(value, label) {
   return value;
 }
 function validateWorkflowBindings(workflow, options) {
+  const targets = /* @__PURE__ */ new Map();
   for (const [name, binding] of Object.entries(options.bindings)) {
     if (!binding) continue;
     const node = workflow[binding.nodeId];
@@ -1011,6 +1079,12 @@ function validateWorkflowBindings(workflow, options) {
         `ComfyUI ${name} binding refers to missing input "${binding.input}" on node "${binding.nodeId}"`
       );
     }
+    const target = `${binding.nodeId}.${binding.input}`;
+    const prior = targets.get(target);
+    if (prior) {
+      throw new Error(`ComfyUI bindings.${name} and bindings.${prior} target the same input ${target}`);
+    }
+    targets.set(target, name);
   }
   if (!workflow[options.outputNodeId]) {
     throw new Error(`ComfyUI outputNodeId refers to missing node "${options.outputNodeId}"`);
@@ -1048,6 +1122,7 @@ function outputImages(entry, outputNodeId) {
 }
 function comfyMetadata(spec, promptId, outputNodeId, images) {
   const options = resolvedOptions(spec);
+  const inputs = providerInputProvenance(spec.providerInputs);
   return {
     promptId,
     outputNodeId,
@@ -1055,6 +1130,7 @@ function comfyMetadata(spec, promptId, outputNodeId, images) {
     workflowFile: options.workflowFile,
     workflowSha256: options.workflowSha256,
     files: images.map((image) => ({ ...image })),
+    ...Object.keys(inputs).length ? { inputs } : {},
     ...spec.revision ? {
       revision: {
         mode: spec.revision.mode,
@@ -1066,6 +1142,41 @@ function comfyMetadata(spec, promptId, outputNodeId, images) {
     } : {}
   };
 }
+function isImageBinding(workflow, binding) {
+  const node = workflow[binding.nodeId];
+  return binding.input === "image" && (node?.class_type === "LoadImage" || node?.class_type === "LoadImageMask");
+}
+function isComfyImageInput(value) {
+  return isObject(value) && value.kind === "image" && typeof value.path === "string" && typeof value.sha256 === "string" && (value.format === "png" || value.format === "jpeg");
+}
+function providerInputProvenance(inputs) {
+  return Object.fromEntries(Object.entries(inputs ?? {}).map(([name, input]) => [
+    name,
+    isComfyImageInput(input) ? { kind: "image", sha256: input.sha256, format: input.format } : { kind: "value", value: input }
+  ]));
+}
+function inputImageFormat(bytes) {
+  if (bytes.length >= 24 && bytes.readUInt32BE(0) === 2303741511 && bytes.readUInt32BE(4) === 218765834 && bytes.toString("ascii", 12, 16) === "IHDR" && bytes.readUInt32BE(16) > 0 && bytes.readUInt32BE(20) > 0) return "png";
+  if (bytes.length < 4 || bytes[0] !== 255 || bytes[1] !== 216) return null;
+  let offset = 2;
+  while (offset + 3 < bytes.length) {
+    if (bytes[offset] !== 255) return null;
+    while (bytes[offset] === 255) offset++;
+    const marker = bytes[offset++];
+    if (marker == null || marker === 217 || marker === 218) break;
+    if (marker === 1 || marker >= 208 && marker <= 215) continue;
+    if (offset + 2 > bytes.length) return null;
+    const length = bytes.readUInt16BE(offset);
+    if (length < 2 || offset + length > bytes.length) return null;
+    const isStartOfFrame = marker >= 192 && marker <= 207 && ![196, 200, 204].includes(marker);
+    if (isStartOfFrame) {
+      if (length < 7) return null;
+      return bytes.readUInt16BE(offset + 3) > 0 && bytes.readUInt16BE(offset + 5) > 0 ? "jpeg" : null;
+    }
+    offset += length;
+  }
+  return null;
+}
 function encodeJob(promptId, outputNodeId) {
   return `${promptId}#${encodeURIComponent(outputNodeId)}`;
 }
@@ -1768,7 +1879,13 @@ var AssetSchema = z2.object({
    * exactly right for a colour style. Editing the shared prompt to suit one
    * style would invalidate every other style's already-generated art.
    */
-  promptByStyle: z2.record(z2.string()).default({})
+  promptByStyle: z2.record(z2.string()).default({}),
+  /**
+   * Named per-asset values consumed by the active provider's declared
+   * bindings. Values are JSON scalars; adapters may interpret a string as a
+   * manifest-relative file when the target node accepts an uploaded input.
+   */
+  providerInputs: z2.record(z2.union([z2.string(), z2.number().finite(), z2.boolean()])).default({})
 }).strict().superRefine((asset, context) => {
   if (asset.source && asset.revision) {
     context.addIssue({
@@ -3211,6 +3328,7 @@ async function resolveSpecs(loaded, filter) {
       return { base64: hit.base64, width: hit.width, height: hit.height, format: hit.format };
     });
     const styleSpecs = /* @__PURE__ */ new Map();
+    const providerInputIdentities = /* @__PURE__ */ new Map();
     for (const [assetId, asset] of Object.entries(manifest.assets)) {
       if (!resolutionAssetIds.has(assetId)) continue;
       if (asset.styles.length && !asset.styles.includes(styleId)) continue;
@@ -3218,6 +3336,20 @@ async function resolveSpecs(loaded, filter) {
       if (!activeProvider.supports(generator)) {
         throw new Error(`Provider "${activeProvider.id}" does not support generator "${generator}"`);
       }
+      if (Object.keys(asset.providerInputs).length && !activeProvider.resolveInputs) {
+        throw new Error(
+          `Provider "${activeProvider.id}" does not support asset providerInputs (${styleId}/${assetId})`
+        );
+      }
+      const inputResolution = activeProvider.resolveInputs ? await activeProvider.resolveInputs(asset.providerInputs, {
+        root,
+        styleId,
+        assetId,
+        providerOptions
+      }) : { inputs: {} };
+      const providerInputs = inputResolution.inputs;
+      const providerInputIdentity = inputResolution.identity ?? providerInputs;
+      providerInputIdentities.set(assetId, providerInputIdentity);
       let width;
       let height;
       let size;
@@ -3246,6 +3378,7 @@ async function resolveSpecs(loaded, filter) {
         assetId,
         provider: activeProvider.id,
         providerOptions,
+        providerInputs,
         generator,
         prompt,
         width,
@@ -3344,7 +3477,12 @@ async function resolveSpecs(loaded, filter) {
           ...asset.revision.strength == null ? {} : { strength: asset.revision.strength }
         };
       }
-      resolved.specHash = specHash(resolved, styleImageHashes, providerOptionIdentity);
+      resolved.specHash = specHash(
+        resolved,
+        styleImageHashes,
+        providerOptionIdentity,
+        providerInputIdentities.get(assetId)
+      );
       activeProvider.validate?.(resolved, resolvedImages);
       const estimate = validateCostEstimate(activeProvider.id, activeProvider.estimate(resolved));
       resolved.cost = estimate.amount;
@@ -6767,6 +6905,7 @@ function buildManifest(name, styleId, generator, outDir, scanned) {
       file: asset.file,
       tags: [],
       styles: [],
+      providerInputs: {},
       ...generator === "map" ? { width: asset.width, height: asset.height } : asset.width === asset.height && asset.width !== commonSize ? { size: asset.width } : {}
     };
   }
@@ -7829,6 +7968,7 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
               file: rel,
               tags: ["salvaged"],
               styles: [ctx.styleId],
+              providerInputs: {},
               ...orphan.width === orphan.height ? { size: orphan.width } : { width: orphan.width, height: orphan.height }
             };
             const durableSource = shouldPersistSourceUrl(orphan.previewUrl) ? orphan.previewUrl : null;