@mcptoolshop/style-dataset-lab 3.0.0 → 3.1.0

package/scripts/card.js

@@ -4,43 +4,44 @@
  * card.js — Generate dataset cards.
  *
  * Usage:
- *   sdlab card generate --snapshot <id> --split <id> [--project <name>]
+ *   sdlab card generate [--snapshot <id>] [--split <id>] [--project <name>]
  */
 
 import { join } from 'node:path';
 import { writeFile } from 'node:fs/promises';
-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 { generateCard } from '../lib/card.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' },
+    },
+    deprecated: { game: 'project' },
+  });
+
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = join(REPO_ROOT, 'projects', projectName);
-  const subcommand = argv.find(a => !a.startsWith('--')) || 'generate';
-  const args = argv.filter(a => a !== subcommand);
+  const subcommand = positionals[0] || 'generate';
 
   if (subcommand === 'generate') {
-    // 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;
     }
 
@@ -51,7 +52,6 @@ export async function run(argv = process.argv.slice(2)) {
 
     const { markdown, json } = await generateCard(projectRoot, snapshotId, splitId);
 
-    // Write to project root
     const mdPath = join(projectRoot, 'dataset-card.md');
     const jsonPath = join(projectRoot, 'dataset-card.json');
     await writeFile(mdPath, markdown);
@@ -61,13 +61,10 @@ export async function run(argv = process.argv.slice(2)) {
     console.log(`  \x1b[32m✓\x1b[0m dataset-card.json`);
 
   } else {
-    throw new Error(`Unknown subcommand: ${subcommand}. Use: generate`);
+    throw inputError('INPUT_BAD_SUBCOMMAND', `Unknown subcommand: ${subcommand}. Use: generate`);
   }
 }
 
 if (process.argv[1] && (process.argv[1].endsWith('card.js') || process.argv[1].endsWith('card'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }

package/scripts/compare.js

@@ -8,62 +8,70 @@
  *   sdlab compare iron_sword_base iron_sword_icon_mid a "Better silhouette" --project star-freight
  */
 
-import { readFile, writeFile, readdir, mkdir } from "node:fs/promises";
+import { writeFile, readdir, mkdir, readFile } from "node:fs/promises";
 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";
-
-function getFlagValue(args, flag) {
-  const prefix = `--${flag}=`;
-  for (const a of args) {
-    if (a.startsWith(prefix)) return a.slice(prefix.length);
-  }
-  const idx = args.indexOf(`--${flag}`);
-  if (idx !== -1 && idx + 1 < args.length) return args[idx + 1];
-  return undefined;
-}
+import { readJsonFile } from "../lib/config.js";
+import { inputError, handleCliError } from "../lib/errors.js";
 
 export async function run(argv = process.argv.slice(2)) {
-  const projectName = getProjectName(argv);
-  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
-
-  // Strip --project/--game and their values from positional parsing
-  const args = argv.filter((a, i) => {
-    if (a === '--project' || a === '--game') return false;
-    if (i > 0 && (argv[i - 1] === '--project' || argv[i - 1] === '--game')) return false;
-    return true;
+  const { flags, positionals } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      scores: { type: 'string' },
+    },
+    deprecated: { game: 'project' },
   });
 
-  const [assetAId, assetBId, winner, ...reasonParts] = args;
+  const projectName = flags.project || getProjectName(argv);
+  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
+
+  const [assetAId, assetBId, winner, ...reasonParts] = positionals;
 
   if (!assetAId || !assetBId || !winner) {
-    throw new Error("Usage: sdlab compare <asset_a_id> <asset_b_id> <a|b|tie> <reasoning>");
+    throw inputError(
+      'INPUT_MISSING_ARGS',
+      'Usage: sdlab compare <asset_a_id> <asset_b_id> <a|b|tie> <reasoning>'
+    );
   }
 
   if (!["a", "b", "tie"].includes(winner)) {
-    throw new Error(`Invalid winner: ${winner}. Must be a, b, or tie.`);
+    throw inputError(
+      'INPUT_BAD_WINNER',
+      `Invalid winner: ${winner}. Must be a, b, or tie.`
+    );
   }
 
-  const reasoning = reasonParts.filter(r => !r.startsWith('--')).join(" ") || null;
+  const reasoning = reasonParts.join(" ") || null;
 
   // Load records to get paths
   const recordA = await loadRecord(GAME_ROOT, assetAId);
   const recordB = await loadRecord(GAME_ROOT, assetBId);
 
   if (!recordA || !recordB) {
-    throw new Error("Could not load one or both records.");
+    throw inputError('INPUT_UNKNOWN_RECORD', 'Could not load one or both records.');
   }
 
   // Parse optional scores
-  const scoresStr = getFlagValue(args, "scores");
+  const scoresStr = flags.scores;
   const criteria_scores = {};
   if (scoresStr) {
     for (const pair of scoresStr.split(",")) {
       const [k, v] = pair.split(":");
       // Format: "silhouette:0.9/0.6" → { silhouette: { a: 0.9, b: 0.6 } }
       if (k && v) {
-        const [aScore, bScore] = v.split("/");
-        criteria_scores[k.trim()] = { a: parseFloat(aScore), b: parseFloat(bScore) };
+        const [aStr, bStr] = v.split("/");
+        const aScore = parseFloat(aStr);
+        const bScore = parseFloat(bStr);
+        if (!Number.isFinite(aScore) || !Number.isFinite(bScore)) {
+          throw inputError(
+            'INPUT_BAD_SCORE',
+            `Score for "${k.trim()}" is not numeric: "${v}"`,
+            'Use the form --scores silhouette:0.9/0.6,palette:0.8/0.7'
+          );
+        }
+        criteria_scores[k.trim()] = { a: aScore, b: bScore };
       }
     }
   }
@@ -101,7 +109,7 @@ export async function run(argv = process.argv.slice(2)) {
 async function loadRecord(GAME_ROOT, id) {
   try {
     const path = join(GAME_ROOT, `records/${id}.json`);
-    return JSON.parse(await readFile(path, "utf-8"));
+    return await readJsonFile(path);
   } catch {
     console.error(`Record not found: records/${id}.json`);
     return null;
@@ -119,8 +127,5 @@ async function countComparisons(GAME_ROOT) {
 
 // Direct execution guard
 if (process.argv[1] && (process.argv[1].endsWith('compare.js') || process.argv[1].endsWith('compare'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }

package/scripts/critique-show.js

@@ -9,7 +9,7 @@
  *   sdlab critique show --project star-freight --run run_2026-04-15_001 --md
  */
 
-import { parseArgs } from '../lib/args.js';
+import { parseArgs, getProjectName } from '../lib/args.js';
 import { getProjectRoot } from '../lib/paths.js';
 import { loadCritique } from '../lib/critique-engine.js';
 import { renderCritiqueMarkdown, renderCritiqueText } from '../lib/critique-render.js';
@@ -17,7 +17,7 @@ import { renderCritiqueMarkdown, renderCritiqueText } from '../lib/critique-rend
 export async function run(argv = process.argv.slice(2)) {
   const { flags } = parseArgs(argv, {
     flags: {
-      project: { type: 'string', default: 'star-freight' },
+      project: { type: 'string' },
       run: { type: 'string' },
       json: { type: 'boolean' },
       md: { type: 'boolean' },
@@ -35,7 +35,7 @@ export async function run(argv = process.argv.slice(2)) {
     return;
   }
 
-  const projectName = flags.project;
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = getProjectRoot(projectName);
 
   const report = loadCritique(projectRoot, flags.run);

package/scripts/critique.js

@@ -8,7 +8,7 @@
  *   sdlab critique --project star-freight --run run_2026-04-15_001 --json
  */
 
-import { parseArgs } from '../lib/args.js';
+import { parseArgs, getProjectName } from '../lib/args.js';
 import { getProjectRoot } from '../lib/paths.js';
 import { critiqueRun, saveCritique } from '../lib/critique-engine.js';
 import { renderCritiqueMarkdown, renderCritiqueText } from '../lib/critique-render.js';
@@ -17,7 +17,7 @@ import { info } from '../lib/log.js';
 export async function run(argv = process.argv.slice(2)) {
   const { flags } = parseArgs(argv, {
     flags: {
-      project: { type: 'string', default: 'star-freight' },
+      project: { type: 'string' },
       run: { type: 'string' },
       json: { type: 'boolean' },
     },
@@ -33,7 +33,7 @@ export async function run(argv = process.argv.slice(2)) {
     return;
   }
 
-  const projectName = flags.project;
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = getProjectRoot(projectName);
 
   console.log(`\x1b[1mstyle-dataset-lab\x1b[0m critique`);

package/scripts/curate.js

@@ -7,59 +7,73 @@
  *   node scripts/curate.js <asset_id> approved "Clean silhouette, correct palette" --scores silhouette:0.9,palette:0.8
  *   node scripts/curate.js <asset_id> rejected "3D render look, alpha halo" --failures alpha_halo,3d_render_look
  *   node scripts/curate.js --list  (show uncurated candidates)
- *   sdlab curate <asset_id> approved "explanation" --project star-freight
+ *   sdlab curate <asset_id> approved "explanation" --project star-freight [--dry-run]
  */
 
-import { readFile, writeFile, rename, readdir, mkdir } from "node:fs/promises";
+import { writeFile, rename, readdir, mkdir, readFile } from "node:fs/promises";
 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";
-
-function getFlagValue(args, flag) {
-  const prefix = `--${flag}=`;
-  for (const a of args) {
-    if (a.startsWith(prefix)) return a.slice(prefix.length);
-  }
-  const idx = args.indexOf(`--${flag}`);
-  if (idx !== -1 && idx + 1 < args.length) return args[idx + 1];
-  return undefined;
-}
+import { readJsonFile } from "../lib/config.js";
+import { inputError, runtimeError, handleCliError } from "../lib/errors.js";
+import { result } from "../lib/log.js";
 
 export async function run(argv = process.argv.slice(2)) {
-  const projectName = getProjectName(argv);
-  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
-
-  // Strip --project/--game and their values from positional parsing
-  const args = argv.filter((a, i) => {
-    if (a === '--project' || a === '--game') return false;
-    if (i > 0 && (argv[i - 1] === '--project' || argv[i - 1] === '--game')) return false;
-    return true;
+  const { flags, positionals } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      scores: { type: 'string' },
+      failures: { type: 'string' },
+      notes: { type: 'string' },
+      list: { type: 'boolean', default: false },
+      'dry-run': { type: 'boolean', default: false },
+    },
+    deprecated: { game: 'project' },
   });
 
-  if (args.includes("--list")) {
+  const projectName = flags.project || getProjectName(argv);
+  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
+  const dryRun = flags['dry-run'] || flags.dryRun;
+
+  if (flags.list) {
     return listUncurated(GAME_ROOT);
   }
 
-  const [assetId, status, explanation, ...rest] = args;
+  const [assetId, status, explanation] = positionals;
 
   if (!assetId || !status || !explanation) {
-    throw new Error("Usage: sdlab curate <asset_id> <approved|rejected|borderline> <explanation> [--scores k:v,...] [--failures f1,f2]");
+    throw inputError(
+      'INPUT_MISSING_ARGS',
+      'Usage: sdlab curate <asset_id> <approved|rejected|borderline> <explanation> [--scores k:v,...] [--failures f1,f2] [--dry-run]'
+    );
   }
 
   if (!["approved", "rejected", "borderline"].includes(status)) {
-    throw new Error(`Invalid status: ${status}. Must be approved, rejected, or borderline.`);
+    throw inputError(
+      'INPUT_BAD_STATUS',
+      `Invalid status: ${status}. Must be approved, rejected, or borderline.`
+    );
   }
 
-  // Parse optional flags
-  const scoresStr = getFlagValue(rest, "scores");
-  const failuresStr = getFlagValue(rest, "failures");
-  const notesStr = getFlagValue(rest, "notes");
+  const scoresStr = flags.scores;
+  const failuresStr = flags.failures;
+  const notesStr = flags.notes;
 
   const criteria_scores = {};
   if (scoresStr) {
     for (const pair of scoresStr.split(",")) {
       const [k, v] = pair.split(":");
-      if (k && v) criteria_scores[k.trim()] = parseFloat(v);
+      if (k && v) {
+        const score = parseFloat(v);
+        if (!Number.isFinite(score)) {
+          throw inputError(
+            'INPUT_BAD_SCORE',
+            `Score value for "${k.trim()}" is not a number: "${v}"`,
+            'Use the form --scores silhouette:0.9,palette:0.8'
+          );
+        }
+        criteria_scores[k.trim()] = score;
+      }
     }
   }
 
@@ -69,17 +83,44 @@ export async function run(argv = process.argv.slice(2)) {
   const recordPath = join(GAME_ROOT, `records/${assetId}.json`);
   let record;
   try {
-    record = JSON.parse(await readFile(recordPath, "utf-8"));
-  } catch {
-    throw new Error(`Record not found: ${recordPath}`);
+    record = await readJsonFile(recordPath);
+  } catch (err) {
+    if (err && err.code === 'INPUT_FILE_NOT_FOUND') {
+      throw inputError('INPUT_UNKNOWN_RECORD', `Record not found: ${recordPath}`);
+    }
+    throw err;
   }
 
-  // Update record first (write before move to avoid orphaned images)
-  const oldPath = join(GAME_ROOT, record.asset_path);
+  const originalAssetPath = record.asset_path;
+  const oldPath = join(GAME_ROOT, originalAssetPath);
   const newDir = `outputs/${status}`;
   const newPath = `${newDir}/${assetId}.png`;
+  const newFullPath = join(GAME_ROOT, newPath);
+
+  if (dryRun) {
+    console.log(`\x1b[33m(dry-run)\x1b[0m ${assetId}`);
+    console.log(`  status: ${status}`);
+    console.log(`  move:   ${originalAssetPath} -> ${newPath}`);
+    console.log(`  note:   ${explanation}`);
+    if (failure_modes.length) console.log(`  failures: ${failure_modes.join(", ")}`);
+    return;
+  }
+
   await mkdir(join(GAME_ROOT, newDir), { recursive: true });
 
+  // Move image FIRST — if the rename fails we still have a clean record.
+  try {
+    await rename(oldPath, newFullPath);
+  } catch (err) {
+    throw runtimeError(
+      'RUNTIME_MOVE_FAILED',
+      `Could not move ${oldPath} to ${newPath}: ${err.message}`,
+      'Check that the source image exists and the destination is writable.',
+      err
+    );
+  }
+
+  // Now safely update the record. If writing fails, try to restore the image.
   record.asset_path = newPath;
   record.judgment = {
     status,
@@ -92,16 +133,23 @@ export async function run(argv = process.argv.slice(2)) {
     confidence: 0.9,
   };
 
-  await writeFile(recordPath, JSON.stringify(record, null, 2));
-
-  // Move image file
   try {
-    await rename(oldPath, join(GAME_ROOT, newPath));
-  } catch {
-    throw new Error(`Could not move ${oldPath} to ${newPath}`);
+    await writeFile(recordPath, JSON.stringify(record, null, 2));
+  } catch (err) {
+    // Attempt rollback: put the image back.
+    try { await rename(newFullPath, oldPath); } catch {}
+    throw runtimeError(
+      'RUNTIME_WRITE_FAILED',
+      `Could not write record ${recordPath}: ${err.message}`,
+      null,
+      err
+    );
   }
 
-  console.log(`\x1b[32m✓\x1b[0m ${assetId} → ${status}`);
+  // Final artifact path — always shown, even under --quiet.
+  result('curate', `${assetId} → ${status}`);
+  result(`  image: ${newPath}`);
+  result(`  record: records/${assetId}.json`);
   console.log(`  ${explanation}`);
   if (failure_modes.length) console.log(`  Failures: ${failure_modes.join(", ")}`);
 }
@@ -135,8 +183,5 @@ async function listUncurated(GAME_ROOT) {
 
 // Direct execution guard
 if (process.argv[1] && (process.argv[1].endsWith('curate.js') || process.argv[1].endsWith('curate'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }

package/scripts/doctor.js

@@ -15,6 +15,7 @@ import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { getProjectName } from '../lib/args.js';
 import { REPO_ROOT } from '../lib/paths.js';
+import { runtimeError, handleCliError } from '../lib/errors.js';
 
 const REQUIRED_CONFIG_FILES = [
   'project.json',
@@ -484,14 +485,11 @@ export async function run(argv = process.argv.slice(2)) {
   console.log(`═══ ${status} — ${passes} passed, ${failures} failed, ${warnings} warnings ═══`);
 
   if (failures > 0) {
-    throw new Error(`Project "${projectName}" has ${failures} issue(s).`);
+    throw runtimeError('PROJECT_UNHEALTHY', `Project "${projectName}" has ${failures} issue(s).`);
   }
 }
 
 // Direct execution guard
 if (process.argv[1] && (process.argv[1].endsWith('doctor.js') || process.argv[1].endsWith('doctor'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }

package/scripts/eligibility.js

@@ -4,36 +4,44 @@
  * eligibility.js — Audit training/eval eligibility for all project records.
  *
  * Usage:
- *   sdlab eligibility audit [--project <name>]
+ *   sdlab eligibility audit [--project <name>] [--profile <id>]
  */
 
 import { readdir, readFile } from 'node:fs/promises';
 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 { loadProjectConfig, loadSelectionProfile } from '../lib/config.js';
+import { handleCliError } from '../lib/errors.js';
 import { evaluateEligibility, categorizeExclusions } from '../lib/eligibility.js';
 
 export async function run(argv = process.argv.slice(2)) {
-  const projectName = getProjectName(argv);
+  const { flags } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      profile: { type: 'string' },
+    },
+    deprecated: { game: 'project' },
+    allowUnknown: true,
+  });
+
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = join(REPO_ROOT, 'projects', projectName);
 
-  const profileIdx = argv.indexOf('--profile');
-  const profileId = profileIdx >= 0 ? argv[profileIdx + 1] : null;
-  const profile = loadSelectionProfile(projectRoot, profileId);
+  const profile = loadSelectionProfile(projectRoot, flags.profile);
   const config = loadProjectConfig(projectRoot);
 
   const recordsDir = join(projectRoot, 'records');
   const files = (await readdir(recordsDir)).filter(f => f.endsWith('.json')).sort();
 
   console.log(`\x1b[1msdlab eligibility audit\x1b[0m — ${projectName}`);
-  console.log(`  Profile: ${profileId || 'training-default (built-in)'}`);
+  console.log(`  Profile: ${flags.profile || 'training-default (built-in)'}`);
   console.log(`  Records: ${files.length}`);
   console.log('');
 
   const eligible = [];
   const excluded = [];
-  const nearMiss = []; // Records with exactly 1 failing reason
+  const nearMiss = [];
 
   for (const file of files) {
     const raw = await readFile(join(recordsDir, file), 'utf-8');
@@ -55,7 +63,6 @@ export async function run(argv = process.argv.slice(2)) {
   console.log(`  \x1b[31m✗\x1b[0m Excluded: ${excluded.length}`);
   console.log('');
 
-  // Categorize exclusions
   const categories = categorizeExclusions(excluded);
   console.log('  Exclusion breakdown:');
   for (const [cat, count] of Object.entries(categories)) {
@@ -65,7 +72,6 @@ export async function run(argv = process.argv.slice(2)) {
     }
   }
 
-  // Near-miss improvement opportunities
   if (nearMiss.length > 0) {
     console.log(`\n  Improvement opportunities (${nearMiss.length} records with 1 failing check):`);
     const byReason = {};
@@ -84,8 +90,5 @@ export async function run(argv = process.argv.slice(2)) {
 
 // Direct execution guard
 if (process.argv[1] && (process.argv[1].endsWith('eligibility.js') || process.argv[1].endsWith('eligibility'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }

package/scripts/eval-pack.js

@@ -11,15 +11,20 @@
 
 import { readFile } from 'node:fs/promises';
 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 { buildEvalPack, listEvalPacks, loadEvalPack } from '../lib/eval-pack.js';
 
 export async function run(argv = process.argv.slice(2)) {
-  const projectName = getProjectName(argv);
+  const { flags, positionals } = parseArgs(argv, {
+    flags: { project: { 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('--')) || 'list';
-  const args = argv.filter(a => a !== subcommand);
+  const subcommand = positionals[0] || 'list';
 
   if (subcommand === 'build') {
     console.log(`\x1b[1msdlab eval-pack build\x1b[0m — ${projectName}\n`);
@@ -48,8 +53,8 @@ export async function run(argv = process.argv.slice(2)) {
     }
 
   } else if (subcommand === 'show') {
-    const evalId = args.find(a => a.startsWith('eval-'));
-    if (!evalId) throw new Error('Usage: sdlab eval-pack show <eval-id>');
+    const evalId = positionals.find(a => a.startsWith('eval-'));
+    if (!evalId) throw inputError('INPUT_MISSING_ARGS', 'Usage: sdlab eval-pack show <eval-id>');
 
     const manifest = await loadEvalPack(projectRoot, evalId);
     console.log(`\x1b[1mEval pack\x1b[0m — ${evalId}\n`);
@@ -80,13 +85,10 @@ export async function run(argv = process.argv.slice(2)) {
     }
 
   } else {
-    throw new Error(`Unknown subcommand: ${subcommand}. Use: build, list, show`);
+    throw inputError('INPUT_BAD_SUBCOMMAND', `Unknown subcommand: ${subcommand}. Use: build, list, show`);
   }
 }
 
 if (process.argv[1] && (process.argv[1].endsWith('eval-pack.js') || process.argv[1].endsWith('eval-pack'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }