@mcptoolshop/style-dataset-lab 3.0.0 → 3.1.0

package/scripts/eval-run.js

@@ -10,40 +10,42 @@
  *   sdlab eval-run list [--project <name>]
  */
 
-import { readFile } 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 { inputError, handleCliError } from '../lib/errors.js';
 import { listTrainingManifests } from '../lib/training-manifests.js';
 import { listEvalPacks } from '../lib/eval-pack.js';
 import { createEvalRun, scoreEvalRun, loadEvalRun, listEvalRuns } from '../lib/eval-runs.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' },
+      'eval-pack': { type: 'string' },
+      outputs: { 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('er-')) || 'list';
-  const args = argv.filter(a => a !== subcommand);
+  // First non-flag positional that isn't an er-id is the subcommand
+  const subcommand = positionals.find(a => !a.startsWith('er-')) || 'list';
 
   if (subcommand === 'create') {
-    // Find manifest
-    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;
     }
 
-    // Find eval pack
-    let evalPackId;
-    const evalIdx = args.indexOf('--eval-pack');
-    if (evalIdx >= 0) {
-      evalPackId = args[evalIdx + 1];
-    } else {
+    let evalPackId = flags['eval-pack'] || flags.evalPack;
+    if (!evalPackId) {
       const packs = await listEvalPacks(projectRoot);
-      if (packs.length === 0) throw new Error('No eval packs. Run: sdlab eval-pack build');
+      if (packs.length === 0) throw inputError('INPUT_NO_EVALPACK', 'No eval packs. Run: sdlab eval-pack build');
       evalPackId = packs[packs.length - 1].id;
     }
 
@@ -57,12 +59,11 @@ export async function run(argv = process.argv.slice(2)) {
     console.log(`  Status: created (use "sdlab eval-run score" to score outputs)`);
 
   } else if (subcommand === 'score') {
-    const evalRunId = args.find(a => a.startsWith('er-'));
-    if (!evalRunId) throw new Error('Usage: sdlab eval-run score <eval-run-id> --outputs <path>');
+    const evalRunId = positionals.find(a => a.startsWith('er-'));
+    if (!evalRunId) throw inputError('INPUT_MISSING_ARGS', 'Usage: sdlab eval-run score <eval-run-id> --outputs <path>');
 
-    const outputsIdx = args.indexOf('--outputs');
-    if (outputsIdx < 0) throw new Error('--outputs <path> is required (JSONL with record_id, accept, notes)');
-    const outputsPath = args[outputsIdx + 1];
+    if (!flags.outputs) throw inputError('INPUT_MISSING_FLAG', '--outputs <path> is required (JSONL with record_id, accept, notes)');
+    const outputsPath = resolveSafeProjectPath(projectRoot, flags.outputs, { baseRoot: REPO_ROOT, flagName: 'outputs' });
 
     console.log(`\x1b[1msdlab eval-run score\x1b[0m — ${evalRunId}\n`);
 
@@ -80,8 +81,8 @@ export async function run(argv = process.argv.slice(2)) {
     }
 
   } else if (subcommand === 'show') {
-    const evalRunId = args.find(a => a.startsWith('er-'));
-    if (!evalRunId) throw new Error('Usage: sdlab eval-run show <eval-run-id>');
+    const evalRunId = positionals.find(a => a.startsWith('er-'));
+    if (!evalRunId) throw inputError('INPUT_MISSING_ARGS', 'Usage: sdlab eval-run show <eval-run-id>');
 
     const run = await loadEvalRun(projectRoot, evalRunId);
     console.log(`\x1b[1mEval run\x1b[0m — ${evalRunId}\n`);
@@ -112,10 +113,10 @@ export async function run(argv = process.argv.slice(2)) {
     }
 
   } else {
-    throw new Error(`Unknown subcommand: ${subcommand}. Use: create, score, show, list`);
+    throw inputError('INPUT_BAD_SUBCOMMAND', `Unknown subcommand: ${subcommand}. Use: create, score, show, list`);
   }
 }
 
 if (process.argv[1] && (process.argv[1].endsWith('eval-run.js') || process.argv[1].endsWith('eval-run'))) {
-  run().catch((err) => { console.error(err.message || err); process.exit(1); });
+  run().catch(handleCliError);
 }

package/scripts/export.js

@@ -9,53 +9,52 @@
  */
 
 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 { listSnapshots } from '../lib/snapshot.js';
 import { listSplits } from '../lib/split.js';
-import { buildExport, listExports, loadExport } from '../lib/export.js';
+import { buildExport, listExports } from '../lib/export.js';
 
 export async function run(argv = process.argv.slice(2)) {
-  const projectName = getProjectName(argv);
+  const { flags, positionals } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      snapshot: { type: 'string' },
+      split: { type: 'string' },
+      profile: { type: 'string' },
+      copy: { type: 'boolean', default: false },
+    },
+    deprecated: { game: 'project' },
+  });
+
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = join(REPO_ROOT, 'projects', projectName);
-  const subcommand = argv.find(a => !a.startsWith('--') && a !== 'true') || 'list';
-  const args = argv.filter(a => a !== subcommand);
+  const subcommand = positionals[0] || 'list';
 
   if (subcommand === 'build') {
-    // Find snapshot
-    let snapshotId;
-    const snapIdx = args.indexOf('--snapshot');
-    if (snapIdx >= 0) {
-      snapshotId = args[snapIdx + 1];
-    } else {
+    let snapshotId = flags.snapshot;
+    if (!snapshotId) {
       const snapshots = await listSnapshots(projectRoot);
-      if (snapshots.length === 0) throw new Error('No snapshots found. Run: sdlab snapshot create');
+      if (snapshots.length === 0) throw inputError('INPUT_NO_SNAPSHOT', 'No snapshots found. Run: sdlab snapshot create');
       snapshotId = snapshots[snapshots.length - 1].id;
     }
 
-    // Find split
-    let splitId;
-    const splitIdx = args.indexOf('--split');
-    if (splitIdx >= 0) {
-      splitId = args[splitIdx + 1];
-    } else {
+    let splitId = flags.split;
+    if (!splitId) {
       const splits = await listSplits(projectRoot);
-      if (splits.length === 0) throw new Error('No splits found. Run: sdlab split build');
+      if (splits.length === 0) throw inputError('INPUT_NO_SPLIT', 'No splits found. Run: sdlab split build');
       splitId = splits[splits.length - 1].id;
     }
 
-    const profileIdx = args.indexOf('--profile');
-    const profileId = profileIdx >= 0 ? args[profileIdx + 1] : null;
-    const copy = args.includes('--copy');
-
     console.log(`\x1b[1msdlab export build\x1b[0m — ${projectName}`);
     console.log(`  Snapshot: ${snapshotId}`);
     console.log(`  Split:    ${splitId}`);
-    console.log(`  Profile:  ${profileId || 'canonical-package (built-in)'}`);
-    console.log(`  Images:   ${copy ? 'copy' : 'symlink'}`);
+    console.log(`  Profile:  ${flags.profile || 'canonical-package (built-in)'}`);
+    console.log(`  Images:   ${flags.copy ? 'copy' : 'symlink'}`);
     console.log('');
 
-    const result = await buildExport(projectRoot, snapshotId, splitId, { profileId, copy });
+    const result = await buildExport(projectRoot, snapshotId, splitId, { profileId: flags.profile, copy: flags.copy });
 
     console.log(`  \x1b[32m✓\x1b[0m Export: ${result.exportId}`);
     console.log(`  Records: ${result.recordCount}`);
@@ -73,13 +72,10 @@ export async function run(argv = process.argv.slice(2)) {
     }
 
   } else {
-    throw new Error(`Unknown subcommand: ${subcommand}. Use: build, list`);
+    throw inputError('INPUT_BAD_SUBCOMMAND', `Unknown subcommand: ${subcommand}. Use: build, list`);
   }
 }
 
 if (process.argv[1] && (process.argv[1].endsWith('export.js') || process.argv[1].endsWith('export'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }

package/scripts/generate-controlnet.js

@@ -12,10 +12,12 @@
  *   sdlab generate:controlnet --subject naia --guide <path> --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 { readJsonFile } from "../lib/config.js";
+import { inputError, runtimeError, handleCliError } from "../lib/errors.js";
 import { comfyHealth, submitAndWait, downloadImage, uploadImage } from "../lib/comfyui.js";
 
 const DEFAULTS = {
@@ -33,7 +35,12 @@ 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"),
@@ -41,9 +48,9 @@ function parseLocalArgs(argv) {
     prompt: get("--prompt", null),
     promptFile: get("--prompt-file", null),
     negative: get("--negative", null),
-    seeds: parseInt(get("--seeds", "4"), 10),
-    weight: parseFloat(get("--weight", "0.70")),
-    guidanceEnd: parseFloat(get("--guidance-end", "0.65")),
+    seeds: parseNumberFlag('seeds', get("--seeds", "4"), { int: true, min: 1 }),
+    weight: parseNumberFlag('weight', get("--weight", "0.70"), { min: 0, max: 2 }),
+    guidanceEnd: parseNumberFlag('guidance-end', get("--guidance-end", "0.65"), { min: 0, max: 1 }),
     controlModel: get("--model", "controlnet-canny-sdxl-1.0.safetensors"),
     dryRun: argv.includes("--dry-run"),
   };
@@ -167,21 +174,25 @@ export async function run(argv = process.argv.slice(2)) {
   const opts = parseLocalArgs(argv);
 
   if (!opts.guidePath) {
-    throw new Error("--guide <path> is required");
+    throw inputError('INPUT_MISSING_FLAG', "--guide <path> is required");
   }
 
+  // Validate guide stays inside the project tree.
+  const safeGuide = resolveSafeProjectPath(GAME_ROOT, opts.guidePath, { flagName: 'guide' });
+
   // Resolve prompt
   let prompt = opts.prompt;
   let negative = opts.negative;
 
   if (opts.promptFile && !prompt) {
-    const pf = JSON.parse(await readFile(join(GAME_ROOT, opts.promptFile), "utf-8"));
+    const safePromptFile = resolveSafeProjectPath(GAME_ROOT, opts.promptFile, { flagName: 'prompt-file' });
+    const pf = await readJsonFile(safePromptFile, { requiredFields: ['prompt'] });
     prompt = pf.prompt;
     negative = negative || pf.negative;
   }
 
   if (!prompt) {
-    throw new Error("--prompt or --prompt-file required");
+    throw inputError('INPUT_MISSING_FLAG', "--prompt or --prompt-file required");
   }
 
   if (!negative) {
@@ -200,12 +211,12 @@ 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 at " + COMFY_URL);
+      throw runtimeError('RUNTIME_COMFY_UNREACHABLE', "ComfyUI not reachable at " + COMFY_URL);
     }
     console.log("\x1b[32m+\x1b[0m ComfyUI online");
   }
 
-  const guideFullPath = join(GAME_ROOT, opts.guidePath);
+  const guideFullPath = safeGuide;
   const guideFilename = `cn_guide_${opts.subject}.png`;
 
   if (!opts.dryRun) {
@@ -215,6 +226,7 @@ export async function run(argv = process.argv.slice(2)) {
 
   await mkdir(join(GAME_ROOT, "outputs/candidates"), { recursive: true });
 
+  let successes = 0, failures = 0;
   for (let si = 0; si < opts.seeds; si++) {
     const seed = DEFAULTS.base_seed + si;
     const assetId = `${opts.subject}_cn_s${si}`;
@@ -254,19 +266,21 @@ export async function run(argv = process.argv.slice(2)) {
       const imgData = await downloadImage(imageFile, imageSubfolder, COMFY_URL);
       await writeFile(join(GAME_ROOT, destPath), imgData);
       console.log(`    \x1b[32m+\x1b[0m ${destPath} (${elapsed}ms, ${imgData.length} bytes)`);
+      successes++;
     } catch (err) {
       console.log(`    \x1b[31mx\x1b[0m ${err.message}`);
+      failures++;
     }
   }
 
-  console.log("\n\x1b[32m+\x1b[0m ControlNet discovery complete");
+  console.log(`\n\x1b[32m+\x1b[0m ControlNet discovery complete (${successes} success, ${failures} failed)`);
   if (opts.dryRun) console.log("  (dry run)");
+  if (!opts.dryRun && failures > 0 && successes === 0) {
+    throw runtimeError('RUNTIME_ALL_FAILED', `All ${opts.seeds} ControlNet generation attempts failed.`);
+  }
 }
 
 // Direct execution guard
 if (process.argv[1] && (process.argv[1].endsWith('generate-controlnet.js') || process.argv[1].endsWith('generate-controlnet'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }

package/scripts/generate-identity.js

@@ -20,10 +20,12 @@
  *   --denoise N     Denoise strength for follow_on phase (default: 0.38)
  */
 
-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 { readJsonFile } from "../lib/config.js";
+import { inputError, runtimeError, handleCliError } from "../lib/errors.js";
 import { comfyHealth, submitAndWait, downloadImage } from "../lib/comfyui.js";
 
 // ── Defaults (match existing lab pipeline) ──
@@ -378,13 +380,24 @@ 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("--"));
+  // Collect positionals, skipping values that belong to known flags
+  const knownFlagsWithValue = new Set(['--subject', '--seeds', '--phase', '--anchor', '--denoise', '--project', '--game']);
+  const positionals = [];
+  for (let k = 0; k < argv.length; k++) {
+    const a = argv[k];
+    if (a.startsWith('--')) {
+      if (!a.includes('=') && knownFlagsWithValue.has(a)) k++;
+      continue;
+    }
+    positionals.push(a);
+  }
+  const packPath = positionals[0];
   const dryRun = argv.includes("--dry-run");
   const subjectFilter = argv.includes("--subject")
     ? argv[argv.indexOf("--subject") + 1]
     : null;
   const seedCount = argv.includes("--seeds")
-    ? parseInt(argv[argv.indexOf("--seeds") + 1], 10)
+    ? parseNumberFlag('seeds', argv[argv.indexOf("--seeds") + 1], { int: true, min: 1 })
     : 3;
   const phase = argv.includes("--phase")
     ? argv[argv.indexOf("--phase") + 1]
@@ -393,30 +406,31 @@ export async function run(argv = process.argv.slice(2)) {
     ? argv[argv.indexOf("--anchor") + 1]
     : null;
   const denoise = argv.includes("--denoise")
-    ? parseFloat(argv[argv.indexOf("--denoise") + 1])
+    ? parseNumberFlag('denoise', argv[argv.indexOf("--denoise") + 1], { min: 0, max: 1 })
     : 0.38;
 
   if (!packPath) {
-    throw new Error("Usage: sdlab generate:identity <packet-file> [options]");
+    throw inputError('INPUT_MISSING_ARGS', "Usage: sdlab generate:identity <packet-file> [options]");
   }
 
   if (phase === "follow_on" && !anchorPath) {
-    throw new Error("--phase follow_on requires --anchor <image-path>");
+    throw inputError('INPUT_MISSING_FLAG', "--phase follow_on requires --anchor <image-path>");
   }
 
-  const fullPackPath = join(GAME_ROOT, packPath);
-  const pack = JSON.parse(await readFile(fullPackPath, "utf-8"));
+  const fullPackPath = resolveSafeProjectPath(GAME_ROOT, packPath, { flagName: 'packet-file' });
+  if (anchorPath) resolveSafeProjectPath(GAME_ROOT, anchorPath, { flagName: 'anchor' });
+  const pack = await readJsonFile(fullPackPath, { requiredFields: ['subjects'] });
 
-  const errors = validatePacket(pack);
-  if (errors.length > 0) {
-    throw new Error("Packet validation failed:\n  " + errors.join("\n  "));
+  const vErrors = validatePacket(pack);
+  if (vErrors.length > 0) {
+    throw inputError('INPUT_BAD_PACKET', "Packet validation failed:\n  " + vErrors.join("\n  "));
   }
 
   let subjects = pack.subjects;
   if (subjectFilter) {
     subjects = subjects.filter((s) => s.subject_name === subjectFilter);
     if (subjects.length === 0) {
-      throw new Error(`No subject found with name '${subjectFilter}'`);
+      throw inputError('INPUT_UNKNOWN_SUBJECT', `No subject found with name '${subjectFilter}'`);
     }
   }
 
@@ -439,7 +453,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");
   }
@@ -448,6 +462,7 @@ export async function run(argv = process.argv.slice(2)) {
   await mkdir(join(GAME_ROOT, "records"), { recursive: true });
 
   let generated = 0;
+  let errors = 0;
   let imageIndex = 0;
 
   for (const subject of subjects) {
@@ -532,6 +547,7 @@ 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[31mx\x1b[0m ${err.message}`);
+          errors++;
         }
 
         generated++;
@@ -540,8 +556,12 @@ export async function run(argv = process.argv.slice(2)) {
     }
   }
 
-  console.log(`\n\x1b[32m+\x1b[0m Generated ${generated} images`);
+  const succeeded = generated - errors;
+  console.log(`\n\x1b[32m+\x1b[0m Generated ${succeeded} images (${errors} errors)`);
   if (dryRun) console.log("  (dry run — no images produced)");
+  if (!dryRun && errors > 0 && succeeded === 0) {
+    throw runtimeError('RUNTIME_ALL_FAILED', `All ${generated} generation attempts failed.`);
+  }
 
   console.log("\nNext steps:");
   if (phase === "discovery") {
@@ -558,8 +578,5 @@ export async function run(argv = process.argv.slice(2)) {
 
 // Direct execution guard
 if (process.argv[1] && (process.argv[1].endsWith('generate-identity.js') || process.argv[1].endsWith('generate-identity'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }

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);
 }