@mcptoolshop/style-dataset-lab 1.2.1 → 2.0.0

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.0.0] - 2026-04-15
+
+### Breaking changes
+
+- **`games/` renamed to `projects/`** -- all project data now lives under `projects/<name>/`
+- **`--game` renamed to `--project`** -- `--game` still works with a deprecation warning (will be removed in v3.0)
+- **Canon-bind loads from config files** -- rules, lanes, rubric, and terminology are now per-project JSON, not hardcoded
+
+### Added
+
+- **`sdlab` CLI** -- unified command-line interface (`bin/sdlab.js`)
+  - `sdlab init <name> --domain <domain>` -- scaffold projects from domain templates
+  - `sdlab project doctor` -- validate project config and structure
+  - `sdlab bind`, `sdlab curate`, `sdlab generate`, etc. -- all pipeline commands
+- **Shared library** (`lib/`) -- 6 modules replacing duplicated code across 13 scripts
+  - `lib/args.js` -- unified argument parser with `--project` and deprecated `--game` support
+  - `lib/paths.js` -- centralized path resolution
+  - `lib/comfyui.js` -- ComfyUI HTTP client (extracted from 5 scripts)
+  - `lib/config.js` -- per-project JSON config loader
+  - `lib/records.js` -- record I/O utilities
+  - `lib/deprecation.js` -- one-shot deprecation warnings
+- **Per-project config files** -- 5 JSON files per project:
+  - `project.json` -- identity, domain, generation defaults
+  - `constitution.json` -- rules with rationale templates
+  - `lanes.json` -- subject lanes with regex detection patterns
+  - `rubric.json` -- scoring dimensions, thresholds, failure-to-rule mappings
+  - `terminology.json` -- group vocabulary with separate `id_detection_order` and `prompt_detection_order`
+- **5 domain starter templates** -- game-art, character-design, creature-design, architecture, vehicle-mech
+- **Training profile placeholders** in domain templates (eligible lanes, thresholds, export format)
+
+### Changed
+
+- Canon-bind is now fully config-driven -- loads rules, lanes, dimensions, thresholds, group vocabulary, and rationale templates from per-project JSON files
+- Missing config files cause hard failure with actionable error messages (no silent fallback)
+- All 10 CLI-exposed scripts refactored to export `run(argv)` for CLI dispatch
+- Net code reduction: ~305 lines removed from deduplication
+
+### Migration
+
+1. Rename `games/` to `projects/`
+2. Use `--project` instead of `--game` (or keep `--game` with deprecation warning)
+3. For canon-bind: add 5 JSON config files to your project (use `sdlab init` as reference)
+
+Star Freight config files are included as the canonical example.
+
 ## [1.2.0] - 2026-04-14
 
 - Added `templates/` with blank constitution, review rubric, and example prompt pack

package/README.md

@@ -1,7 +1,3 @@
-<p align="center">
-  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
-</p>
-
 <p align="center">
   <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/style-dataset-lab/readme.png" width="400">
 </p>
@@ -13,163 +9,146 @@
 
 # style-dataset-lab
 
-A production pipeline for visual dataset creation -- from canon rules to structured prompts to ComfyUI generation to curated, canon-bound training data.
+A canon-bound visual dataset pipeline for directed image production.
 
-## What this is
+Define what your project looks like. Generate candidates. Curate against your canon. Bind approved work to constitution rules. Export trustworthy datasets for training, evaluation, and production reuse.
 
-A **pipeline** for building structured visual training datasets. You write style rules (canon), compose prompts, generate with ComfyUI, curate with per-dimension scoring, bind judgments to canon rules, and export in 10 formats via [`@mcptoolshop/repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset).
+## What this is
 
-The pipeline is game-agnostic. Each game gets its own data directory under `games/<name>/`; the 13 scripts and blank templates are shared. Every asset produced carries three things:
+A **visual canon + dataset pipeline** for teams that care about style consistency, provenance, and reviewable judgment. Every asset carries three things:
 
-1. **Image pixels** -- generated by ComfyUI with full provenance (checkpoint, LoRA, seed, sampler, cfg)
-2. **Canon explanation** -- why this is on-style or off-style, grounded in a style constitution
-3. **Quality judgment** -- approved/rejected with per-dimension scores and cited rules
+1. **Provenance** -- full generation history (checkpoint, LoRA, seed, sampler, cfg, timing)
+2. **Canon binding** -- which constitution rules this asset passes, fails, or partially meets
+3. **Quality judgment** -- approved/rejected/borderline with per-dimension scores
 
-## Security model
+The pipeline works for game art, character design, creature design, architecture, vehicle/mech concepts, and any domain where visual production needs to stay on-model.
 
-**Local-only.** style-dataset-lab talks to ComfyUI on `localhost:8188` and never makes external network requests. No telemetry, no analytics, no phoning home. Image generation happens entirely on your GPU. Records and canon data stay on your filesystem.
+## Quick start
 
-## What the npm package ships
+```bash
+# Install the CLI + pipeline
+npm install -g @mcptoolshop/style-dataset-lab
 
-`npm install @mcptoolshop/style-dataset-lab` gives you:
+# Scaffold a new project
+sdlab init my-project --domain character-design
 
-- **13 scripts** -- generate, curate, compare, canon-bind, painterly, identity generation, ControlNet/IP-Adapter generation, bulk curation, migration
-- **Blank templates** -- starter constitution, review rubric, and example prompt pack in `templates/`
+# Validate the project structure
+sdlab project doctor --project my-project
+```
 
-The npm package does **not** include game data. Clone the repo if you want the Star Freight example (1,182 records, 28 prompt waves, 18 visual categories).
+Available domains: `game-art`, `character-design`, `creature-design`, `architecture`, `vehicle-mech`, or `generic`.
 
-## Install
+## CLI
 
 ```bash
-# Get the pipeline scripts + templates
-npm install @mcptoolshop/style-dataset-lab
-
-# Or clone the repo for the Star Freight example data
-git clone https://github.com/mcp-tool-shop-org/style-dataset-lab
-cd style-dataset-lab
-npm install
+sdlab init <name> [--domain <domain>]     # Scaffold a new project
+sdlab project doctor [--project <name>]   # Validate project config
+
+sdlab generate <pack> [--project <name>]  # Generate candidates via ComfyUI
+sdlab generate:identity <packet>          # Named-subject identity images
+sdlab generate:controlnet                 # ControlNet-guided generation
+sdlab generate:ipadapter                  # IP-Adapter reference-guided
+
+sdlab curate <id> <status> <explanation>  # Record review judgment
+sdlab compare <a> <b> <winner> <reason>   # Pairwise A-vs-B comparison
+sdlab bind [--project <name>]             # Bind records to constitution rules
+sdlab painterly [--project <name>]        # Post-processing style pass
 ```
 
-To start a new game from the templates:
-
-```bash
-# Copy templates into your game directory
-mkdir -p games/my-game/{records,comparisons,inputs/prompts,outputs/{candidates,approved,rejected,borderline,painterly},exports}
-cp -r templates/canon games/my-game/canon
-cp templates/inputs/prompts/example-wave.json games/my-game/inputs/prompts/wave1.json
-# Edit the canon and prompts, then generate
-```
+All commands accept `--project <name>` (default: `star-freight`).
 
-## Monorepo structure
+## Project model
 
-The pipeline lives in `scripts/` and `templates/`. Each game lives in `games/<name>/` with its own canon, records, and assets. Scripts accept `--game <name>` (defaults to `star-freight`).
+Each project is a self-contained directory under `projects/` with its own canon, config, and data:
 
 ```
-style-dataset-lab/
-  scripts/                  13 pipeline scripts (generate, curate, compare, etc.)
-  templates/                Blank starting point for new games
-    canon/                  Starter constitution + review rubric
-    inputs/prompts/         Example prompt pack
-  games/
-    star-freight/           Star Freight example (1,182 records, repo-only)
-      canon/                Style constitution, review rubric, species canon
-      records/              Per-asset JSON (provenance + judgment + canon)
-      comparisons/          A-vs-B preference judgments
-      inputs/               Prompt packs, identity packets, references
-      outputs/              Generated images (gitignored)
-      exports/              repo-dataset output (gitignored)
-    <your-game>/            Add more games with the same structure
+projects/
+  my-project/
+    project.json            Project identity + generation defaults
+    constitution.json       Rules array with rationale templates
+    lanes.json              Subject lanes with detection patterns
+    rubric.json             Scoring dimensions + thresholds
+    terminology.json        Group vocabulary + detection order
+    canon/                  Style constitution (markdown)
+    records/                Per-asset JSON (provenance + judgment + canon)
+    inputs/prompts/         Prompt packs (JSON)
+    outputs/                Generated images (gitignored)
+    comparisons/            A-vs-B preference judgments
+    exports/                Training data output (gitignored)
 ```
 
-## Pipeline workflow
+## Pipeline
 
-The full pipeline from canon to training export:
+```
+canon  -->  prompts  -->  generate  -->  curate  -->  bind  -->  compare  -->  export
+ |            |             |              |           |            |            |
+ rules      packs        ComfyUI       judgment    assertions   preferences   dataset
+```
 
-```bash
-# 1. Write your canon -- style constitution + review rubric
-#    (start from templates/ or write from scratch)
+1. **Define canon** -- write your style constitution and review rubric
+2. **Create prompt packs** -- structured subjects with style prefix and variations
+3. **Generate** -- ComfyUI produces candidates with full provenance
+4. **Curate** -- approve/reject with per-dimension scores and failure modes
+5. **Bind** -- link each asset to constitution rules with pass/fail/partial verdicts
+6. **Compare** -- record pairwise preferences for DPO/ranking datasets
+7. **Export** -- produce training data via [`repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) in 10+ formats
 
-# 2. Create prompt packs in inputs/prompts/
-#    (see templates/inputs/prompts/example-wave.json)
+## Domain templates
 
-# 3. Start ComfyUI and generate candidates
-npm run generate -- --game star-freight inputs/prompts/wave1.json
-npm run generate -- --game star-freight inputs/prompts/wave1.json --dry-run
+Each domain template ships with lane definitions, constitution rules, scoring rubrics, and terminology structures designed for that production context:
 
-# 4. Generate identity-packet characters (named subjects)
-npm run generate:identity -- --game star-freight inputs/identity-packets/wave27a.json
+| Domain | Lanes | Key concerns |
+|--------|-------|-------------|
+| **game-art** | character, environment, prop, UI, ship, interior, equipment | Silhouette at gameplay scale, faction differentiation, wear/aging |
+| **character-design** | portrait, full_body, turnaround, expression_sheet, action_pose | Proportion accuracy, costume logic, personality read, gesture clarity |
+| **creature-design** | concept, orthographic, detail_study, action, scale_reference, habitat | Anatomical plausibility, evolutionary logic, silhouette distinction |
+| **architecture** | exterior, interior, streetscape, structural_detail, ruin, landscape | Structural plausibility, material consistency, perspective, era coherence |
+| **vehicle-mech** | exterior, cockpit, component, schematic, silhouette_sheet, damage_variant | Mechanical logic, functional design language, access points, damage narrative |
 
-# 5. Curate -- approve, reject, or mark borderline
-npm run curate -- --game star-freight <asset_id> approved "explanation"
-npm run curate -- --game star-freight <asset_id> rejected "explanation" --failures "too_clean"
+## The dataset angle
 
-# 6. Generate painterly variants of approved assets
-npm run painterly -- --game star-freight
+The pipeline produces more than organized images. It produces **trustworthy, structured datasets** with:
 
-# 7. Bind canon explanations to curated assets
-npm run canon-bind -- --game star-freight
+- **Full provenance** on every asset (reproducible generations)
+- **Canon-bound judgments** (not just labels -- reasoned verdicts against declared rules)
+- **Pairwise preferences** (for DPO and ranking-based training)
+- **Per-dimension scoring** (fine-grained quality signals, not just pass/fail)
+- **Failure mode tagging** (what specifically went wrong and which rules were violated)
 
-# 8. Record pairwise comparisons
-npm run compare -- --game star-freight <asset_a> <asset_b> a "A has better faction read"
+Export via `repo-dataset` to TRL, LLaVA, Qwen2-VL, JSONL, Parquet, and more.
 
-# 9. Export training data via repo-dataset
-repo-dataset visual generate ./games/star-freight --format trl
-repo-dataset visual inspect ./games/star-freight
-```
+## Star Freight example
 
-## Adding a new game
+Clone the repo for a complete working example: 1,182 records, 28 prompt waves, 5 factions, 7 lanes, 24 constitution rules, and 892 approved assets from a gritty sci-fi RPG.
 
 ```bash
-# Create structure and copy blank templates
-mkdir -p games/my-game/{records,comparisons,inputs/prompts,outputs/{candidates,approved,rejected,borderline,painterly},exports}
-cp -r templates/canon games/my-game/canon
-cp templates/inputs/prompts/example-wave.json games/my-game/inputs/prompts/wave1.json
-
-# Edit your canon/constitution.md and canon/review-rubric.md
-# Edit your prompt pack, then run the pipeline with --game my-game
+git clone https://github.com/mcp-tool-shop-org/style-dataset-lab
+cd style-dataset-lab
+sdlab bind --stats --project star-freight
+sdlab project doctor --project star-freight
 ```
 
-## Per-game directory layout
+## Migrating from v1.x
 
-Each `games/<name>/` directory contains:
+v2.0 renames `games/` to `projects/` and `--game` to `--project`:
 
-```
-canon/                  Style constitution, review rubric, species canon, identity gates
-inputs/
-  prompts/              Prompt packs per wave (JSON: subjects, variations, defaults)
-  references/           IP-Adapter reference images
-  control-guides/       ControlNet guide overlays
-  identity-packets/     Named character identity spines
-outputs/
-  candidates/           Raw generations (gitignored)
-  approved/             Curated approved (gitignored)
-  rejected/             Curated rejected (gitignored)
-  borderline/           Curated borderline (gitignored)
-  painterly/            Painterly-style variants (gitignored)
-records/                Per-asset JSON (provenance + judgment + canon binding)
-comparisons/            A-vs-B preference judgments
-exports/                repo-dataset output (gitignored)
-```
+```bash
+# Rename your data directory
+mv games projects
 
-## Generation setup
-
-```yaml
-checkpoint: dreamshaperXL_v21TurboDPMSDE.safetensors
-lora: classipeintxl_v21.safetensors (weight: 1.0)
-resolution: 1024x1024
-steps: 8
-cfg: 2.0
-sampler: dpmpp_sde
-scheduler: karras
-speed: ~9s per image (RTX 5080)
+# --game still works with a deprecation warning (removed in v3.0)
+sdlab bind --game star-freight   # works, prints warning
+sdlab bind --project star-freight # canonical form
 ```
 
-Additional generation modes: ControlNet (pose/depth-guided), IP-Adapter (reference-driven), and identity packets (named character consistency).
+## Security model
+
+**Local-only.** Talks to ComfyUI on `localhost:8188`. No telemetry, no analytics, no external requests. Images stay on your GPU and filesystem.
 
 ## Requirements
 
 - [ComfyUI](https://github.com/comfyanonymous/ComfyUI) running on localhost:8188
-- DreamShaper XL Turbo checkpoint + ClassipeintXL LoRA
+- SDXL-compatible checkpoint + style LoRA
 - Node.js 20+
 - [`@mcptoolshop/repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) for training export
 

package/bin/sdlab.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+/**
+ * sdlab — CLI entry point for Style Dataset Lab.
+ *
+ * Thin dispatcher that routes subcommands to existing scripts.
+ * Each script exports run(argv) and is lazy-loaded on demand.
+ */
+
+const COMMANDS = {
+  'init':                '../scripts/init.js',
+  'generate':            '../scripts/generate.js',
+  'generate:identity':   '../scripts/generate-identity.js',
+  'generate:controlnet': '../scripts/generate-controlnet.js',
+  'generate:ipadapter':  '../scripts/generate-ipadapter.js',
+  'curate':              '../scripts/curate.js',
+  'compare':             '../scripts/compare.js',
+  'bind':                '../scripts/canon-bind.js',
+  'canon-bind':          '../scripts/canon-bind.js',
+  'painterly':           '../scripts/painterly.js',
+  'painterly:test':      '../scripts/painterly-test.js',
+  'migrate':             '../scripts/migrate-records.js',
+};
+
+// Two-word commands under "project" namespace
+const PROJECT_COMMANDS = {
+  'doctor':  '../scripts/doctor.js',
+  'migrate': '../scripts/migrate-records.js',
+};
+
+function printHelp() {
+  console.log(`\x1b[1msdlab\x1b[0m — Style Dataset Lab CLI\n`);
+  console.log('Usage: sdlab <command> [options]\n');
+  console.log('Project:');
+  console.log('  init <name>          Scaffold a new project from a domain template');
+  console.log('  project doctor       Validate project config and structure');
+  console.log('  project migrate      Migrate record schemas');
+  console.log('');
+  console.log('Pipeline:');
+  console.log('  generate             Generate candidates from a prompt pack');
+  console.log('  generate:identity    Generate named-subject identity images');
+  console.log('  generate:controlnet  ControlNet-guided structural generation');
+  console.log('  generate:ipadapter   IP-Adapter reference-guided generation');
+  console.log('  curate               Move candidate to approved/rejected/borderline');
+  console.log('  compare              Record pairwise A-vs-B comparison');
+  console.log('  bind                 Bind approved records to constitution rules');
+  console.log('  painterly            Post-processing painterly style pass');
+  console.log('  painterly:test       Test denoise levels on reference images');
+  console.log('');
+  console.log('Options:');
+  console.log('  --project <name>     Project to operate on (default: star-freight)');
+  console.log('  --game <name>        Deprecated alias for --project');
+  console.log('  --help               Show this help');
+  console.log('');
+  console.log('Examples:');
+  console.log('  sdlab init my-project --domain character-design');
+  console.log('  sdlab generate inputs/prompts/wave1.json --project star-freight');
+  console.log('  sdlab bind --stats --project star-freight');
+  console.log('  sdlab project doctor --project star-freight');
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    printHelp();
+    process.exit(0);
+  }
+
+  let command = args[0];
+  let commandArgs = args.slice(1);
+
+  // Handle "project <subcommand>" two-word form
+  if (command === 'project' && args[1] && PROJECT_COMMANDS[args[1]]) {
+    commandArgs = args.slice(2);
+    const modulePath = PROJECT_COMMANDS[args[1]];
+    try {
+      const mod = await import(modulePath);
+      await mod.run(commandArgs);
+    } catch (err) {
+      console.error(`\x1b[31mError:\x1b[0m ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  const modulePath = COMMANDS[command];
+  if (!modulePath) {
+    console.error(`Unknown command: ${command}`);
+    console.error(`Run "sdlab --help" for available commands.`);
+    process.exit(1);
+  }
+
+  try {
+    const mod = await import(modulePath);
+    await mod.run(commandArgs);
+  } catch (err) {
+    console.error(`\x1b[31mError:\x1b[0m ${err.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/lib/args.js

@@ -0,0 +1,106 @@
+/**
+ * Unified CLI argument parser.
+ *
+ * Supports:
+ *   --flag value       (space-separated)
+ *   --flag=value       (equals form)
+ *   --boolean-flag     (boolean)
+ *   positional args    (collected in order)
+ *   deprecated aliases (warns once, maps to canonical name)
+ */
+
+import { warnDeprecated } from './deprecation.js';
+
+/**
+ * @typedef {Object} ArgSpec
+ * @property {Object<string, {type: 'string'|'boolean', default?: any, alias?: string}>} flags
+ * @property {string[]} [positionals] - names for positional args (in order)
+ * @property {Object<string, string>} [deprecated] - old flag name → new flag name
+ */
+
+/**
+ * Parse CLI arguments.
+ * @param {string[]} argv — typically process.argv.slice(2)
+ * @param {ArgSpec} spec
+ * @returns {{ flags: Object, positionals: string[], rest: string[] }}
+ */
+export function parseArgs(argv, spec = {}) {
+  const flagDefs = spec.flags || {};
+  const deprecated = spec.deprecated || {};
+  const positionalNames = spec.positionals || [];
+
+  const flags = {};
+  const positionals = [];
+
+  // Set defaults
+  for (const [name, def] of Object.entries(flagDefs)) {
+    if (def.default !== undefined) flags[name] = def.default;
+    else if (def.type === 'boolean') flags[name] = false;
+    else flags[name] = undefined;
+  }
+
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+
+    if (arg.startsWith('--')) {
+      let key, value;
+
+      if (arg.includes('=')) {
+        const eqIdx = arg.indexOf('=');
+        key = arg.slice(2, eqIdx);
+        value = arg.slice(eqIdx + 1);
+      } else {
+        key = arg.slice(2);
+        value = undefined;
+      }
+
+      // Handle deprecated aliases
+      if (deprecated[key]) {
+        warnDeprecated(key, deprecated[key]);
+        key = deprecated[key];
+      }
+
+      // Handle short aliases defined in flagDefs
+      const canonical = Object.entries(flagDefs).find(([, def]) => def.alias === key);
+      if (canonical) key = canonical[0];
+
+      // Normalize kebab-case to camelCase for lookup
+      const camelKey = key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+      const def = flagDefs[key] || flagDefs[camelKey];
+
+      if (def?.type === 'boolean') {
+        flags[key in flagDefs ? key : camelKey] = true;
+      } else if (value !== undefined) {
+        flags[key in flagDefs ? key : camelKey] = value;
+      } else if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) {
+        flags[key in flagDefs ? key : camelKey] = argv[++i];
+      } else {
+        flags[key in flagDefs ? key : camelKey] = true;
+      }
+    } else {
+      positionals.push(arg);
+    }
+    i++;
+  }
+
+  // Map positionals to named keys
+  const named = {};
+  for (let j = 0; j < positionalNames.length && j < positionals.length; j++) {
+    named[positionalNames[j]] = positionals[j];
+  }
+
+  return { flags, positionals, named, rest: positionals.slice(positionalNames.length) };
+}
+
+/**
+ * Extract the --project (or deprecated --game) value from argv.
+ * Convenience for scripts that just need the project name.
+ */
+export function getProjectName(argv) {
+  const { flags } = parseArgs(argv, {
+    flags: { project: { type: 'string', default: 'star-freight' } },
+    deprecated: { game: 'project' },
+  });
+  return flags.project;
+}

package/lib/comfyui.js

@@ -0,0 +1,109 @@
+/**
+ * ComfyUI HTTP API client — extracted from 5 generation scripts.
+ *
+ * All functions take comfyUrl as a parameter so projects can override
+ * the default localhost:8188 endpoint.
+ */
+
+import { readFile } from 'node:fs/promises';
+
+const DEFAULT_URL = 'http://127.0.0.1:8188';
+const MAX_POLL_MS = 600_000; // 10 minutes
+
+/**
+ * Check if ComfyUI is reachable.
+ * @param {string} [comfyUrl]
+ * @returns {Promise<boolean>}
+ */
+export async function comfyHealth(comfyUrl = DEFAULT_URL) {
+  try {
+    const res = await fetch(`${comfyUrl}/system_stats`);
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Submit a workflow and poll until complete.
+ * @param {Object} workflow — ComfyUI prompt graph
+ * @param {string} [comfyUrl]
+ * @param {{ clientPrefix?: string, timeoutMs?: number }} [opts]
+ * @returns {Promise<Object>} — history entry
+ */
+export async function submitAndWait(workflow, comfyUrl = DEFAULT_URL, opts = {}) {
+  const { clientPrefix = 'sdl', timeoutMs = MAX_POLL_MS } = opts;
+  const clientId = `${clientPrefix}-${Date.now()}`;
+
+  const res = await fetch(`${comfyUrl}/prompt`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ prompt: workflow, client_id: clientId }),
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`ComfyUI submit failed: ${res.status} ${text}`);
+  }
+
+  const { prompt_id: promptId } = await res.json();
+
+  const start = Date.now();
+  while (true) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(`ComfyUI poll timeout after ${timeoutMs / 1000}s for prompt ${promptId}`);
+    }
+    await new Promise(r => setTimeout(r, 1000));
+    const histRes = await fetch(`${comfyUrl}/history/${promptId}`);
+    if (!histRes.ok) continue;
+    const history = await histRes.json();
+    const entry = history[promptId];
+    if (!entry) continue;
+    if (entry.status?.completed) return entry;
+    if (entry.status?.status_str === 'error') {
+      throw new Error(`ComfyUI generation failed: ${JSON.stringify(entry.status)}`);
+    }
+  }
+}
+
+/**
+ * Download a generated image from ComfyUI.
+ * @param {string} filename
+ * @param {string} [subfolder]
+ * @param {string} [comfyUrl]
+ * @param {string} [type='output']
+ * @returns {Promise<Buffer>}
+ */
+export async function downloadImage(filename, subfolder, comfyUrl = DEFAULT_URL, type = 'output') {
+  const url = `${comfyUrl}/view?filename=${encodeURIComponent(filename)}&subfolder=${encodeURIComponent(subfolder || '')}&type=${type}`;
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Download failed: ${res.status}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+/**
+ * Upload an image to ComfyUI's input folder.
+ * @param {string} filePath — local file to upload
+ * @param {string} filename — name to assign in ComfyUI
+ * @param {string} [comfyUrl]
+ * @returns {Promise<string>} — assigned name from ComfyUI
+ */
+export async function uploadImage(filePath, filename, comfyUrl = DEFAULT_URL) {
+  const data = await readFile(filePath);
+  const formData = new FormData();
+  formData.append('image', new Blob([data], { type: 'image/png' }), filename);
+  formData.append('overwrite', 'true');
+
+  const res = await fetch(`${comfyUrl}/upload/image`, {
+    method: 'POST',
+    body: formData,
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Upload failed: ${res.status} ${text}`);
+  }
+
+  const result = await res.json();
+  return result.name;
+}