@mcptoolshop/style-dataset-lab 2.3.0 → 3.0.1

package/scripts/generate-ipadapter.js

@@ -11,10 +11,11 @@
  *   sdlab generate:ipadapter --subject corrigan --ref <image> --seeds 4 --project star-freight
  */
 
-import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import { getProjectName } from "../lib/args.js";
-import { REPO_ROOT } from "../lib/paths.js";
+import { getProjectName, parseNumberFlag } from "../lib/args.js";
+import { REPO_ROOT, resolveSafeProjectPath } from "../lib/paths.js";
+import { inputError, runtimeError, handleCliError } from "../lib/errors.js";
 import { comfyHealth, submitAndWait, downloadImage, uploadImage } from "../lib/comfyui.js";
 
 const DEFAULTS = {
@@ -34,17 +35,22 @@ const DEFAULTS = {
 function parseLocalArgs(argv) {
   const get = (flag, def) => {
     const i = argv.indexOf(flag);
-    return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
+    if (i < 0 || i + 1 >= argv.length) return def;
+    const v = argv[i + 1];
+    if (typeof v === 'string' && v.startsWith('--')) {
+      throw inputError('INPUT_MISSING_VALUE', `Flag ${flag} is missing its value (got another flag: ${v}).`);
+    }
+    return v;
   };
   return {
     subject: get("--subject", "unknown"),
     refPath: get("--ref", null),
     prompt: get("--prompt", null),
     negative: get("--negative", null),
-    seeds: parseInt(get("--seeds", "4"), 10),
-    weight: parseFloat(get("--weight", "0.55")),
-    start: parseFloat(get("--start", "0.0")),
-    end: parseFloat(get("--end", "0.8")),
+    seeds: parseNumberFlag('seeds', get("--seeds", "4"), { int: true, min: 1 }),
+    weight: parseNumberFlag('weight', get("--weight", "0.55"), { min: 0, max: 2 }),
+    start: parseNumberFlag('start', get("--start", "0.0"), { min: 0, max: 1 }),
+    end: parseNumberFlag('end', get("--end", "0.8"), { min: 0, max: 1 }),
     dryRun: argv.includes("--dry-run"),
   };
 }
@@ -174,12 +180,15 @@ export async function run(argv = process.argv.slice(2)) {
   const opts = parseLocalArgs(argv);
 
   if (!opts.refPath) {
-    throw new Error("--ref <path> is required");
+    throw inputError('INPUT_MISSING_FLAG', "--ref <path> is required");
   }
   if (!opts.prompt) {
-    throw new Error("--prompt is required");
+    throw inputError('INPUT_MISSING_FLAG', "--prompt is required");
   }
 
+  // Validate --ref path stays inside project tree.
+  const safeRefPath = resolveSafeProjectPath(GAME_ROOT, opts.refPath, { flagName: 'ref' });
+
   const negative = opts.negative ||
     "photorealistic, photograph, 3d render, anime, cartoon, text, watermark, blurry, low quality";
 
@@ -196,11 +205,11 @@ export async function run(argv = process.argv.slice(2)) {
   if (!opts.dryRun) {
     const online = await comfyHealth(COMFY_URL);
     if (!online) {
-      throw new Error("ComfyUI not reachable");
+      throw runtimeError('RUNTIME_COMFY_UNREACHABLE', "ComfyUI not reachable at " + COMFY_URL);
     }
     console.log("\x1b[32m+\x1b[0m ComfyUI online");
 
-    await uploadImage(join(GAME_ROOT, opts.refPath), refFilename, COMFY_URL);
+    await uploadImage(safeRefPath, refFilename, COMFY_URL);
     console.log(`\x1b[32m+\x1b[0m Reference uploaded: ${refFilename}`);
   }
 
@@ -255,8 +264,5 @@ export async function run(argv = process.argv.slice(2)) {
 
 // Direct execution guard
 if (process.argv[1] && (process.argv[1].endsWith('generate-ipadapter.js') || process.argv[1].endsWith('generate-ipadapter'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }

package/scripts/generate.js

@@ -10,11 +10,34 @@
  * downloads the output PNG, and writes a provenance record to records/.
  */
 
-import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import { getProjectName } from "../lib/args.js";
-import { REPO_ROOT } from "../lib/paths.js";
+import { parseArgs, getProjectName } from "../lib/args.js";
+import { REPO_ROOT, resolveSafeProjectPath } from "../lib/paths.js";
+import { readJsonFile } from "../lib/config.js";
+import { runtimeError, handleCliError } from "../lib/errors.js";
 import { comfyHealth, submitAndWait, downloadImage } from "../lib/comfyui.js";
+import { info, result } from "../lib/log.js";
+
+/**
+ * Format milliseconds as a human ETA string like "6m 12s" or "42s".
+ */
+function formatEta(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return '—';
+  const totalSec = Math.round(ms / 1000);
+  if (totalSec < 60) return `${totalSec}s`;
+  const m = Math.floor(totalSec / 60);
+  const s = totalSec % 60;
+  return `${m}m ${s}s`;
+}
+
+/**
+ * COMFY_URL precedence:
+ *   1. process.env.COMFY_URL (explicit user env)
+ *   2. project defaults.comfy_url (set by `sdlab project doctor`)
+ *   3. built-in default http://127.0.0.1:8188
+ * The adapter (lib/adapters/comfyui-runner.js) applies the same precedence.
+ */
 
 function buildWorkflow(prompt, negativePrompt, checkpoint, loras, seed, steps, cfg, sampler, scheduler, width, height, ipAdapterConfig) {
   const nodes = {};
@@ -157,11 +180,19 @@ export async function run(argv = process.argv.slice(2)) {
   const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
   const COMFY_URL = process.env.COMFY_URL || "http://127.0.0.1:8188";
 
-  const packPath = argv.find((a) => !a.startsWith("--")) || "inputs/prompts/rpg-icons-lane1.json";
-  const dryRun = argv.includes("--dry-run");
+  const parsed = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      game: { type: 'string' },
+      'dry-run': { type: 'boolean' },
+    },
+    deprecated: { game: 'project' },
+  });
+  const packPath = parsed.positionals[0] || "inputs/prompts/rpg-icons-lane1.json";
+  const dryRun = parsed.flags['dry-run'] === true;
 
-  const fullPackPath = join(GAME_ROOT, packPath);
-  const pack = JSON.parse(await readFile(fullPackPath, "utf-8"));
+  const fullPackPath = resolveSafeProjectPath(GAME_ROOT, packPath, { flagName: 'pack-path' });
+  const pack = await readJsonFile(fullPackPath, { requiredFields: ['lane', 'subjects', 'variations', 'defaults'] });
 
   console.log(`\x1b[1mstyle-dataset-lab\x1b[0m generate`);
   console.log(`  Lane: ${pack.lane}`);
@@ -173,7 +204,7 @@ export async function run(argv = process.argv.slice(2)) {
   if (!dryRun) {
     const online = await comfyHealth(COMFY_URL);
     if (!online) {
-      throw new Error("ComfyUI not reachable at " + COMFY_URL);
+      throw runtimeError('RUNTIME_COMFY_UNREACHABLE', "ComfyUI not reachable at " + COMFY_URL, 'Start ComfyUI or set COMFY_URL to the right host.');
     }
     console.log("\x1b[32m✓\x1b[0m ComfyUI online");
   }
@@ -183,7 +214,9 @@ export async function run(argv = process.argv.slice(2)) {
 
   const d = pack.defaults;
   let generated = 0;
+  let errors = 0;
   const totalExpected = pack.subjects.length * pack.variations.length;
+  const runStartMs = Date.now();
 
   for (const subject of pack.subjects) {
     for (const variation of pack.variations) {
@@ -272,21 +305,43 @@ export async function run(argv = process.argv.slice(2)) {
         console.log(`    \x1b[32m✓\x1b[0m ${destPath} (${elapsed}ms, ${imgData.length} bytes)`);
       } catch (err) {
         console.log(`    \x1b[31m✗\x1b[0m ${err.message}`);
+        errors++;
       }
 
       generated++;
+
+      // ETA every 5 items (not every item — too noisy for long runs).
+      if (!dryRun && generated > 0 && generated % 5 === 0 && generated < totalExpected) {
+        const elapsedTotal = Date.now() - runStartMs;
+        const avgMs = elapsedTotal / generated;
+        const remaining = totalExpected - generated;
+        const etaMs = avgMs * remaining;
+        info('generate', `progress ${generated}/${totalExpected} — avg ${formatEta(avgMs)}/item, ETA ~${formatEta(etaMs)}`);
+      }
     }
   }
 
   console.log("");
-  console.log(`\x1b[32m✓\x1b[0m Generated ${generated} candidates`);
+  const succeeded = generated - errors;
+  const totalElapsedMs = Date.now() - runStartMs;
+  console.log(`\x1b[32m✓\x1b[0m Generated ${succeeded} candidates (${errors} errors)`);
+  if (!dryRun && generated > 0) {
+    const avgMs = totalElapsedMs / generated;
+    console.log(`  Total: ${formatEta(totalElapsedMs)} — avg ${formatEta(avgMs)}/item`);
+  }
   if (dryRun) console.log("  (dry run — no images produced)");
+  // Always print the output directory so scripted pipelines can parse it,
+  // even under --quiet.
+  if (!dryRun && succeeded > 0) {
+    result(`Candidates: ${join(GAME_ROOT, 'outputs/candidates')}`);
+    result(`Records: ${join(GAME_ROOT, 'records')}`);
+  }
+  if (!dryRun && errors > 0 && succeeded === 0) {
+    throw runtimeError('RUNTIME_ALL_FAILED', `All ${totalExpected} generation attempts failed.`);
+  }
 }
 
 // Direct execution guard
 if (process.argv[1] && (process.argv[1].endsWith('generate.js') || process.argv[1].endsWith('generate'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }

package/scripts/implementation-pack.js

@@ -10,25 +10,30 @@
  */
 
 import { join } from 'node:path';
-import { getProjectName } from '../lib/args.js';
+import { parseArgs, getProjectName } from '../lib/args.js';
 import { REPO_ROOT } from '../lib/paths.js';
+import { inputError, handleCliError } from '../lib/errors.js';
 import { listTrainingManifests } from '../lib/training-manifests.js';
 import { buildImplementationPack, listImplementationPacks, loadImplementationPack } from '../lib/implementation-packs.js';
 
 export async function run(argv = process.argv.slice(2)) {
-  const projectName = getProjectName(argv);
+  const { flags, positionals } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      manifest: { type: 'string' },
+    },
+    deprecated: { game: 'project' },
+  });
+
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = join(REPO_ROOT, 'projects', projectName);
-  const subcommand = argv.find(a => !a.startsWith('--') && !a.startsWith('impl-') && !a.startsWith('tm-')) || 'list';
-  const args = argv.filter(a => a !== subcommand);
+  const subcommand = positionals.find(a => !a.startsWith('impl-') && !a.startsWith('tm-')) || 'list';
 
   if (subcommand === 'build') {
-    let manifestId;
-    const manifestIdx = args.indexOf('--manifest');
-    if (manifestIdx >= 0) {
-      manifestId = args[manifestIdx + 1];
-    } else {
+    let manifestId = flags.manifest;
+    if (!manifestId) {
       const manifests = await listTrainingManifests(projectRoot);
-      if (manifests.length === 0) throw new Error('No training manifests. Run: sdlab training-manifest create');
+      if (manifests.length === 0) throw inputError('INPUT_NO_MANIFEST', 'No training manifests. Run: sdlab training-manifest create');
       manifestId = manifests[manifests.length - 1].id;
     }
 
@@ -44,8 +49,8 @@ export async function run(argv = process.argv.slice(2)) {
     console.log(`  Subject continuity:   ${result.subjects}`);
 
   } else if (subcommand === 'show') {
-    const implId = args.find(a => a.startsWith('impl-'));
-    if (!implId) throw new Error('Usage: sdlab implementation-pack show <impl-id>');
+    const implId = positionals.find(a => a.startsWith('impl-'));
+    if (!implId) throw inputError('INPUT_MISSING_ARGS', 'Usage: sdlab implementation-pack show <impl-id>');
 
     const pack = await loadImplementationPack(projectRoot, implId);
     console.log(`\x1b[1mImplementation pack\x1b[0m — ${implId}\n`);
@@ -69,10 +74,10 @@ export async function run(argv = process.argv.slice(2)) {
     }
 
   } else {
-    throw new Error(`Unknown subcommand: ${subcommand}. Use: build, show, list`);
+    throw inputError('INPUT_BAD_SUBCOMMAND', `Unknown subcommand: ${subcommand}. Use: build, show, list`);
   }
 }
 
 if (process.argv[1] && (process.argv[1].endsWith('implementation-pack.js') || process.argv[1].endsWith('implementation-pack'))) {
-  run().catch((err) => { console.error(err.message || err); process.exit(1); });
+  run().catch(handleCliError);
 }

package/scripts/init.js

@@ -13,6 +13,7 @@ import { mkdir, readdir, readFile, writeFile, copyFile } from 'node:fs/promises'
 import { join, basename } from 'node:path';
 import { existsSync } from 'node:fs';
 import { REPO_ROOT } from '../lib/paths.js';
+import { inputError, handleCliError } from '../lib/errors.js';
 
 const TEMPLATES_DIR = join(REPO_ROOT, 'templates');
 const PROJECTS_DIR = join(REPO_ROOT, 'projects');
@@ -40,6 +41,13 @@ const PROJECT_DIRS = [
   'training/packages',
   'training/eval-runs',
   'training/implementations',
+  'workflows/profiles',
+  'workflows/batch-modes',
+  'briefs',
+  'runs',
+  'batches',
+  'selections',
+  'inbox/generated',
 ];
 
 function isValidName(name) {
@@ -75,15 +83,28 @@ export async function run(argv = process.argv.slice(2)) {
   }
 
   if (!isValidName(projectName)) {
-    throw new Error(
-      `Invalid project name "${projectName}".\n` +
+    throw inputError(
+      'INPUT_BAD_NAME',
+      `Invalid project name "${projectName}".`,
       `Use lowercase letters, numbers, and hyphens (e.g. "my-project").`
     );
   }
 
+  // Validate --domain to prevent path traversal via template lookup.
+  if (!isValidName(domain)) {
+    throw inputError(
+      'INPUT_BAD_DOMAIN',
+      `Invalid --domain "${domain}".`,
+      `Use lowercase letters, numbers, and hyphens (e.g. "character-design").`
+    );
+  }
+
   const projectDir = join(PROJECTS_DIR, projectName);
   if (existsSync(projectDir)) {
-    throw new Error(`Project "${projectName}" already exists at ${projectDir}`);
+    throw inputError(
+      'INPUT_PROJECT_EXISTS',
+      `Project "${projectName}" already exists at ${projectDir}`
+    );
   }
 
   // Resolve domain template source
@@ -92,8 +113,9 @@ export async function run(argv = process.argv.slice(2)) {
     domainDir = join(TEMPLATES_DIR, 'domains', domain);
     if (!existsSync(domainDir)) {
       const domains = await listDomains();
-      throw new Error(
-        `Domain "${domain}" not found.\n` +
+      throw inputError(
+        'INPUT_UNKNOWN_DOMAIN',
+        `Domain "${domain}" not found.`,
         `Available: generic, ${domains.join(', ')}`
       );
     }
@@ -199,36 +221,134 @@ export async function run(argv = process.argv.slice(2)) {
 
   // Copy canon markdown templates
   const canonTemplates = ['constitution.md', 'review-rubric.md'];
+  const wroteCanon = {};
   for (const file of canonTemplates) {
     const src = join(TEMPLATES_DIR, 'canon', file);
     if (existsSync(src)) {
       await copyFile(src, join(projectDir, 'canon', file));
+      wroteCanon[file] = true;
       console.log(`  \x1b[32m✓\x1b[0m canon/${file}`);
     }
   }
 
-  // Copy example prompt pack
-  const examplePack = join(TEMPLATES_DIR, 'inputs', 'prompts', 'example-wave.json');
-  if (existsSync(examplePack)) {
+  // Copy example prompt pack — prefer per-domain example (subjects match domain lane id_patterns),
+  // fall back to legacy global template if it exists (pre-v3.0.1 installs may still ship it).
+  let wroteExamplePack = false;
+  const domainExamplePack = domainDir
+    ? join(domainDir, 'inputs', 'prompts', 'example-wave.json')
+    : null;
+  const globalExamplePack = join(TEMPLATES_DIR, 'inputs', 'prompts', 'example-wave.json');
+  const examplePack =
+    domainExamplePack && existsSync(domainExamplePack) ? domainExamplePack
+    : existsSync(globalExamplePack) ? globalExamplePack
+    : null;
+  if (examplePack) {
     await copyFile(examplePack, join(projectDir, 'inputs', 'prompts', 'example-wave.json'));
+    wroteExamplePack = true;
     console.log(`  \x1b[32m✓\x1b[0m inputs/prompts/example-wave.json`);
   }
 
+  // Copy domain workflow profiles if available
+  if (domainDir) {
+    const domainWorkflowsDir = join(domainDir, 'workflows', 'profiles');
+    if (existsSync(domainWorkflowsDir)) {
+      const wfFiles = (await readdir(domainWorkflowsDir)).filter(f => f.endsWith('.json'));
+      for (const file of wfFiles) {
+        await copyFile(
+          join(domainWorkflowsDir, file),
+          join(projectDir, 'workflows', 'profiles', file)
+        );
+        console.log(`  \x1b[32m✓\x1b[0m workflows/profiles/${file}`);
+      }
+    }
+  }
+
+  // Write a starter README.md inside the project so users have a home base
+  // with copy-pasteable next commands and a place for their notes.
+  const readmeLines = [
+    `# ${projectName}`,
+    '',
+    `A \`style-dataset-lab\` project — domain: **${domain}**.`,
+    '',
+    '## Quick commands',
+    '',
+    '```bash',
+    `# Validate that the scaffold is healthy`,
+    `sdlab project doctor --project ${projectName}`,
+    '',
+  ];
+  if (wroteExamplePack) {
+    readmeLines.push(
+      `# Generate candidates from the example prompt pack`,
+      `sdlab generate inputs/prompts/example-wave.json --project ${projectName}`,
+      ''
+    );
+  } else {
+    readmeLines.push(
+      `# Generate candidates (add a prompt pack under inputs/prompts/ first)`,
+      `sdlab generate <pack-path> --project ${projectName}`,
+      ''
+    );
+  }
+  readmeLines.push(
+    `# Curate a candidate (approved | rejected | borderline)`,
+    `sdlab curate <asset_id> approved "reads clean" --project ${projectName}`,
+    '',
+    `# Bind approved records to constitution rules`,
+    `sdlab canon-bind --project ${projectName}`,
+    '',
+    `# Create a frozen dataset snapshot`,
+    `sdlab snapshot create --project ${projectName}`,
+    '```',
+    '',
+    '## Project layout',
+    '',
+    '- `project.json` — defaults (checkpoint, width, height, sampler)',
+    '- `constitution.json` — machine-readable style rules',
+    '- `canon/` — human-authored style reference (constitution.md, review-rubric.md)',
+    '- `inputs/prompts/` — generation prompt packs',
+    '- `outputs/candidates/` — raw generated PNGs',
+    '- `outputs/approved/` · `outputs/rejected/` · `outputs/borderline/` — curated outputs',
+    '- `records/` — provenance + judgment records (one JSON per candidate)',
+    '- `snapshots/` · `splits/` · `exports/` — frozen dataset artifacts',
+    '',
+    '## Docs',
+    '',
+    '- Handbook: https://mcp-tool-shop-org.github.io/style-dataset-lab/',
+    '- CLI reference: `sdlab --help` (or `sdlab <cmd> --help` for any command)',
+    '',
+    '## TODO',
+    '',
+    '- [ ] Fill in `canon/constitution.md` with your style rules',
+    '- [ ] Encode those rules in `constitution.json` for canon-bind',
+    '- [ ] Add at least one prompt pack under `inputs/prompts/`',
+    '- [ ] Run `sdlab project doctor` and fix any warnings',
+    ''
+  );
+  await writeFile(join(projectDir, 'README.md'), readmeLines.join('\n'));
+  console.log(`  \x1b[32m✓\x1b[0m README.md`);
+
   console.log('');
   console.log(`\x1b[32m✓\x1b[0m Project "${projectName}" initialized`);
   console.log('');
   console.log('Next steps:');
-  console.log(`  1. Edit ${projectName}/canon/constitution.md — define your visual rules`);
-  console.log(`  2. Edit ${projectName}/constitution.json — encode rules for canon-bind`);
-  console.log(`  3. Create prompt packs in ${projectName}/inputs/prompts/`);
-  console.log(`  4. Run: sdlab generate <pack> --project ${projectName}`);
-  console.log(`  5. Run: sdlab project doctor --project ${projectName}`);
+  let step = 1;
+  if (wroteCanon['constitution.md']) {
+    console.log(`  ${step++}. Edit ${projectName}/canon/constitution.md — define your visual rules`);
+  }
+  console.log(`  ${step++}. Edit ${projectName}/constitution.json — encode rules for canon-bind`);
+  if (wroteExamplePack) {
+    console.log(`  ${step++}. Run: sdlab generate inputs/prompts/example-wave.json --project ${projectName}`);
+  } else {
+    console.log(`  ${step++}. Create prompt packs under ${projectName}/inputs/prompts/`);
+    console.log(`  ${step++}. Run: sdlab generate <pack> --project ${projectName}`);
+  }
+  console.log(`  ${step++}. Run: sdlab project doctor --project ${projectName}`);
+  console.log('');
+  console.log(`See ${projectName}/README.md for the full quick-start.`);
 }
 
 // Direct execution guard
 if (process.argv[1] && (process.argv[1].endsWith('init.js') || process.argv[1].endsWith('init'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }

package/scripts/painterly.js

@@ -18,8 +18,9 @@
 import { writeFile, mkdir, readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { existsSync } from "node:fs";
-import { getProjectName } from "../lib/args.js";
-import { REPO_ROOT } from "../lib/paths.js";
+import { getProjectName, parseNumberFlag } from "../lib/args.js";
+import { REPO_ROOT, resolveSafeProjectPath } from "../lib/paths.js";
+import { runtimeError, handleCliError } from "../lib/errors.js";
 import { comfyHealth, submitAndWait, downloadImage, uploadImage } from "../lib/comfyui.js";
 
 // ── Config ──
@@ -156,11 +157,11 @@ export async function run(argv = process.argv.slice(2)) {
 
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === "--source" && argv[i + 1]) sourceDir = argv[++i];
-    if (argv[i] === "--limit" && argv[i + 1]) limit = parseInt(argv[++i]);
-    if (argv[i] === "--offset" && argv[i + 1]) offset = parseInt(argv[++i]);
+    else if (argv[i] === "--limit" && argv[i + 1]) limit = parseNumberFlag('limit', argv[++i], { int: true, min: 1 });
+    else if (argv[i] === "--offset" && argv[i + 1]) offset = parseNumberFlag('offset', argv[++i], { int: true, min: 0 });
   }
 
-  const fullSourceDir = join(GAME_ROOT, sourceDir);
+  const fullSourceDir = resolveSafeProjectPath(GAME_ROOT, sourceDir, { flagName: 'source' });
   const outDir = join(GAME_ROOT, "outputs/painterly");
   await mkdir(outDir, { recursive: true });
 
@@ -195,7 +196,7 @@ export async function run(argv = process.argv.slice(2)) {
   if (!dryRun) {
     const online = await comfyHealth(COMFY_URL);
     if (!online) {
-      throw new Error("ComfyUI not reachable at " + COMFY_URL);
+      throw runtimeError('RUNTIME_COMFY_UNREACHABLE', "ComfyUI not reachable at " + COMFY_URL);
     }
     console.log("\x1b[32m✓\x1b[0m ComfyUI online");
   }
@@ -263,8 +264,5 @@ export async function run(argv = process.argv.slice(2)) {
 
 // Direct execution guard
 if (process.argv[1] && (process.argv[1].endsWith('painterly.js') || process.argv[1].endsWith('painterly'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }

package/scripts/refine.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+
+/**
+ * refine.js — Generate a refined next-pass brief from critique.
+ *
+ * Usage:
+ *   sdlab refine --project star-freight --run run_2026-04-15_001 --pick 003.png
+ *   sdlab refine --run run_2026-04-15_001 --pick 003.png --push "stronger faction read" --suppress "extra ornament"
+ *   sdlab refine --run run_2026-04-15_001 --pick 003.png --json
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseArgs, getProjectName } from '../lib/args.js';
+import { getProjectRoot, getRunsDir } from '../lib/paths.js';
+import { loadCritique } from '../lib/critique-engine.js';
+import {
+  extractDelta,
+  buildRefinedBrief,
+  saveRefinedBrief,
+  renderRefinedBriefMarkdown,
+} from '../lib/refine-briefs.js';
+import { info } from '../lib/log.js';
+
+export async function run(argv = process.argv.slice(2)) {
+  const { flags } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      run: { type: 'string' },
+      pick: { type: 'string' },
+      preserve: { type: 'string' },
+      push: { type: 'string' },
+      suppress: { type: 'string' },
+      json: { type: 'boolean' },
+    },
+    deprecated: { game: 'project' },
+  });
+
+  if (!flags.run || !flags.pick) {
+    console.log('Usage: sdlab refine --run <id> --pick <filename> [--project <name>]');
+    console.log('');
+    console.log('Options:');
+    console.log('  --run <id>             Run to refine from (required)');
+    console.log('  --pick <filename>      Candidate filename to refine from (required)');
+    console.log('  --preserve <notes>     Comma-separated preserve instructions');
+    console.log('  --push <notes>         Comma-separated push instructions');
+    console.log('  --suppress <notes>     Comma-separated suppress instructions');
+    console.log('  --json                 Output raw JSON');
+    return;
+  }
+
+  const projectName = flags.project || getProjectName(argv);
+  const projectRoot = getProjectRoot(projectName);
+  const runId = flags.run;
+  const pickedFilename = flags.pick;
+
+  console.log(`\x1b[1mstyle-dataset-lab\x1b[0m refine`);
+  console.log(`  Project: ${projectName}`);
+  console.log(`  Run: ${runId}`);
+  console.log(`  Picked: ${pickedFilename}`);
+  console.log('');
+
+  // Load critique
+  const critique = loadCritique(projectRoot, runId);
+
+  // Load parent brief from the run
+  const runDir = join(getRunsDir(projectRoot), runId);
+  const parentBrief = JSON.parse(readFileSync(join(runDir, 'brief.json'), 'utf-8'));
+
+  // Parse CLI delta overrides
+  const cliOverrides = {
+    preserve: flags.preserve ? flags.preserve.split(',').map(s => s.trim()).filter(Boolean) : [],
+    push: flags.push ? flags.push.split(',').map(s => s.trim()).filter(Boolean) : [],
+    suppress: flags.suppress ? flags.suppress.split(',').map(s => s.trim()).filter(Boolean) : [],
+  };
+
+  // Extract delta from critique + overrides
+  const delta = extractDelta(critique, pickedFilename, cliOverrides);
+
+  // Build refined brief
+  const refineDir = join(runDir, 'refine');
+  const refinedBrief = buildRefinedBrief({
+    parentBrief,
+    critique,
+    pickedCandidate: pickedFilename,
+    delta,
+    runId,
+    refineDir,
+  });
+
+  // Save
+  const { jsonPath, mdPath } = await saveRefinedBrief(projectRoot, runId, refinedBrief);
+
+  if (flags.json) {
+    console.log(JSON.stringify(refinedBrief, null, 2));
+  } else {
+    console.log(`Refined brief: ${refinedBrief.brief_id}`);
+    console.log(`Parent: ${refinedBrief.parent_brief_id}`);
+    console.log(`Source: ${runId} → ${pickedFilename}`);
+    console.log('');
+
+    if (delta.preserve.length > 0) {
+      console.log('Preserve:');
+      for (const p of delta.preserve) console.log(`  ✓ ${p}`);
+    }
+    if (delta.push.length > 0) {
+      console.log('Push:');
+      for (const p of delta.push) console.log(`  → ${p}`);
+    }
+    if (delta.suppress.length > 0) {
+      console.log('Suppress:');
+      for (const s of delta.suppress) console.log(`  ✗ ${s}`);
+    }
+
+    console.log('');
+    info(`Saved: runs/${runId}/refine/${refinedBrief.brief_id}.json`);
+    info(`Next: sdlab run generate --brief ${refinedBrief.brief_id} (from refine dir)`);
+  }
+}