@mcptoolshop/style-dataset-lab 2.3.0 → 3.0.1

package/scripts/batch-generate.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+
+/**
+ * batch-generate.js — Execute a batch production mode.
+ *
+ * Usage:
+ *   sdlab batch generate --mode expression-sheet --subject captain-orryn --project star-freight
+ *   sdlab batch generate --mode environment-board --theme freeport-night --project star-freight
+ *   sdlab batch generate --mode silhouette-pack --project star-freight --dry-run
+ */
+
+import { parseArgs, getProjectName } from '../lib/args.js';
+import { getProjectRoot, getRunsDir } from '../lib/paths.js';
+import { compileBatch } from '../lib/batch-compiler.js';
+import { getBatchMode } from '../lib/batch-modes.js';
+import {
+  createBatchDir,
+  executeBatchRuns,
+  saveBatchManifest,
+} from '../lib/batch-runs.js';
+import { renderSheetHTML, saveSheet } from '../lib/batch-sheet-render.js';
+import { info, result } from '../lib/log.js';
+import { join } from 'node:path';
+import { writeFile } from 'node:fs/promises';
+
+export async function run(argv = process.argv.slice(2)) {
+  const { flags } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      mode: { type: 'string' },
+      subject: { type: 'string' },
+      theme: { type: 'string' },
+      asset: { type: 'string' },
+      'dry-run': { type: 'boolean' },
+      json: { type: 'boolean' },
+    },
+    deprecated: { game: 'project' },
+  });
+
+  if (!flags.mode) {
+    console.log('Usage: sdlab batch generate --mode <id> [--subject <id>] [--theme <label>] [--project <name>]');
+    console.log('');
+    console.log('Options:');
+    console.log('  --mode <id>        Batch mode (required)');
+    console.log('  --subject <id>     Subject for subject-driven modes');
+    console.log('  --theme <label>    Theme label for environment modes');
+    console.log('  --asset <id>       Training asset reference');
+    console.log('  --dry-run          Prepare batch without submitting to ComfyUI');
+    console.log('  --json             Output manifest as JSON');
+    return;
+  }
+
+  const projectName = flags.project || getProjectName(argv);
+  const projectRoot = getProjectRoot(projectName);
+  const dryRun = flags['dry-run'] || false;
+
+  // Load mode for display
+  const mode = getBatchMode(projectRoot, flags.mode);
+
+  console.log(`\x1b[1mstyle-dataset-lab\x1b[0m batch generate`);
+  console.log(`  Project: ${projectName}`);
+  console.log(`  Mode: ${mode.label} (${mode.mode_id})`);
+  console.log(`  Type: ${mode.batch_type}`);
+  console.log(`  Slots: ${mode.variant_plan.length}`);
+  if (flags.subject) console.log(`  Subject: ${flags.subject}`);
+  if (flags.theme) console.log(`  Theme: ${flags.theme}`);
+  if (dryRun) console.log('  ⚠ DRY RUN');
+  console.log('');
+
+  // 1. Compile batch briefs
+  const { baseBrief, slotBriefs } = await compileBatch({
+    projectRoot,
+    projectId: projectName,
+    modeId: flags.mode,
+    subjectId: flags.subject,
+    theme: flags.theme,
+    assetRef: flags.asset,
+  });
+
+  // 2. Create batch directory
+  const { batchId, batchDir } = await createBatchDir(projectRoot);
+  info('batch-generate', `Batch: ${batchId}`);
+
+  // 3. Execute runs
+  const batchStartMs = Date.now();
+  const results = await executeBatchRuns({
+    projectRoot,
+    projectName,
+    batchDir,
+    mode,
+    slotBriefs,
+    dryRun,
+  });
+  const batchElapsedMs = Date.now() - batchStartMs;
+  if (!dryRun && results.length > 0) {
+    const avgSec = Math.round(batchElapsedMs / results.length / 1000);
+    const totalSec = Math.round(batchElapsedMs / 1000);
+    info('batch-generate', `Completed ${results.length} slot(s) in ${totalSec}s (avg ${avgSec}s/slot)`);
+  }
+
+  // 4. Build manifest
+  const manifest = {
+    batch_id: batchId,
+    project_id: projectName,
+    mode_id: mode.mode_id,
+    created_at: new Date().toISOString(),
+    brief_ids: results.map(r => r.brief_id),
+    run_ids: results.map(r => r.run_id),
+    slots: results.map(r => ({
+      slot_id: r.slot_id,
+      label: r.label,
+      brief_id: r.brief_id,
+      run_id: r.run_id,
+      selected_output: r.selected_output,
+    })),
+    sheet_paths: [],
+    summary: {
+      total_slots: results.length,
+      successful_slots: results.filter(r => r.selected_output).length,
+      dry_run: dryRun,
+    },
+  };
+
+  if (flags.subject) manifest.subject_id = flags.subject;
+  if (flags.theme) manifest.theme = flags.theme;
+
+  // 5. Render sheet
+  const sheetHtml = renderSheetHTML({ manifest, mode, projectRoot, batchDir });
+  const sheetPath = await saveSheet(batchDir, 'primary-sheet.html', sheetHtml);
+  manifest.sheet_paths.push('sheets/primary-sheet.html');
+
+  // 6. Save manifest + summary
+  await saveBatchManifest(batchDir, manifest);
+
+  // Write summary.md
+  const summaryLines = [
+    `# Batch: ${batchId}`,
+    '',
+    `**Mode:** ${mode.label} (${mode.mode_id})`,
+    `**Type:** ${mode.batch_type}`,
+    `**Project:** ${projectName}`,
+  ];
+  if (manifest.subject_id) summaryLines.push(`**Subject:** ${manifest.subject_id}`);
+  if (manifest.theme) summaryLines.push(`**Theme:** ${manifest.theme}`);
+  summaryLines.push(`**Created:** ${manifest.created_at}`);
+  if (dryRun) summaryLines.push('**⚠ DRY RUN**');
+  summaryLines.push('');
+  summaryLines.push('## Slots');
+  summaryLines.push('');
+  summaryLines.push('| Slot | Run | Output |');
+  summaryLines.push('|------|-----|--------|');
+  for (const r of results) {
+    summaryLines.push(`| ${r.label} | ${r.run_id} | ${r.selected_output || '—'} |`);
+  }
+  summaryLines.push('');
+  await writeFile(join(batchDir, 'summary.md'), summaryLines.join('\n'));
+
+  // 7. Output
+  console.log('');
+  if (flags.json) {
+    console.log(JSON.stringify(manifest, null, 2));
+  } else {
+    console.log(`Batch: ${batchId}`);
+    console.log(`Slots: ${results.length}`);
+    console.log('');
+    for (const r of results) {
+      const status = r.selected_output ? '✓' : '○';
+      console.log(`  ${status} ${r.label.padEnd(24)} → ${r.run_id}  ${r.selected_output || '(dry run)'}`);
+    }
+    console.log('');
+    // Primary artifact paths — always print (survives --quiet) so pipelines
+    // can parse the output location.
+    result(`Sheet: batches/${batchId}/sheets/primary-sheet.html`);
+    result(`Manifest: batches/${batchId}/manifest.json`);
+  }
+}

package/scripts/batch-sheet.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+/**
+ * batch-sheet.js — Re-render a batch sheet from saved manifest.
+ *
+ * Usage:
+ *   sdlab batch sheet batch_2025-06-30_001 --project star-freight
+ */
+
+import { parseArgs, getProjectName } from '../lib/args.js';
+import { getProjectRoot } from '../lib/paths.js';
+import { loadBatchManifest } from '../lib/batch-runs.js';
+import { getBatchMode } from '../lib/batch-modes.js';
+import { renderSheetHTML, saveSheet } from '../lib/batch-sheet-render.js';
+import { getBatchesDir } from '../lib/batch-runs.js';
+import { join } from 'node:path';
+import { inputError } from '../lib/errors.js';
+import { info } from '../lib/log.js';
+
+export async function run(argv = process.argv.slice(2)) {
+  const { flags, positionals } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      batch: { type: 'string' },
+    },
+    deprecated: { game: 'project' },
+  });
+
+  const projectName = flags.project || getProjectName(argv);
+  const projectRoot = getProjectRoot(projectName);
+  const batchId = positionals[0] || flags.batch;
+
+  if (!batchId) {
+    console.log('Usage: sdlab batch sheet <batch-id> [--project <name>]');
+    return;
+  }
+
+  const manifest = loadBatchManifest(projectRoot, batchId);
+  const mode = getBatchMode(projectRoot, manifest.mode_id);
+  const batchDir = join(getBatchesDir(projectRoot), batchId);
+
+  const html = renderSheetHTML({ manifest, mode, projectRoot, batchDir });
+  const sheetPath = await saveSheet(batchDir, 'primary-sheet.html', html);
+
+  info(`Sheet written: ${sheetPath}`);
+}

package/scripts/batch-show.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+/**
+ * batch-show.js — List batches or show batch details.
+ *
+ * Usage:
+ *   sdlab batch show --project star-freight          # list all batches
+ *   sdlab batch show batch_2025-06-30_001            # show specific batch
+ *   sdlab batch show batch_2025-06-30_001 --json     # as JSON
+ */
+
+import { parseArgs, getProjectName } from '../lib/args.js';
+import { getProjectRoot } from '../lib/paths.js';
+import { listBatches, loadBatchManifest } from '../lib/batch-runs.js';
+
+export async function run(argv = process.argv.slice(2)) {
+  const { flags, positionals } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      batch: { type: 'string' },
+      json: { type: 'boolean' },
+    },
+    deprecated: { game: 'project' },
+  });
+
+  const projectName = flags.project || getProjectName(argv);
+  const projectRoot = getProjectRoot(projectName);
+  const batchId = positionals[0] || flags.batch;
+
+  // List mode
+  if (!batchId) {
+    const batches = listBatches(projectRoot);
+    if (batches.length === 0) {
+      console.log('No batches found.');
+      return;
+    }
+    console.log(`\x1b[1mstyle-dataset-lab\x1b[0m batches (${projectName})`);
+    console.log('');
+    for (const id of batches) {
+      try {
+        const manifest = loadBatchManifest(projectRoot, id);
+        const mode = manifest.mode_id || '?';
+        const slots = manifest.summary?.total_slots || manifest.slots?.length || 0;
+        const ok = manifest.summary?.successful_slots ?? '?';
+        const dry = manifest.summary?.dry_run ? ' [dry]' : '';
+        const subject = manifest.subject_id ? ` (${manifest.subject_id})` : '';
+        console.log(`  ${id}  ${mode.padEnd(24)} ${ok}/${slots} slots${dry}${subject}`);
+      } catch {
+        console.log(`  ${id}  (manifest unreadable)`);
+      }
+    }
+    console.log('');
+    return;
+  }
+
+  // Detail mode
+  const manifest = loadBatchManifest(projectRoot, batchId);
+
+  if (flags.json) {
+    console.log(JSON.stringify(manifest, null, 2));
+    return;
+  }
+
+  console.log(`\x1b[1mstyle-dataset-lab\x1b[0m batch ${batchId}`);
+  console.log('');
+  console.log(`  Mode:      ${manifest.mode_id}`);
+  console.log(`  Project:   ${manifest.project_id}`);
+  if (manifest.subject_id) console.log(`  Subject:   ${manifest.subject_id}`);
+  if (manifest.theme) console.log(`  Theme:     ${manifest.theme}`);
+  console.log(`  Created:   ${manifest.created_at}`);
+  if (manifest.summary?.dry_run) console.log('  ⚠ DRY RUN');
+  console.log('');
+  console.log('  Slots:');
+  for (const slot of manifest.slots || []) {
+    const status = slot.selected_output ? '✓' : '○';
+    console.log(`    ${status} ${(slot.label || slot.slot_id).padEnd(24)} run=${slot.run_id}  ${slot.selected_output || ''}`);
+  }
+  console.log('');
+  if (manifest.sheet_paths?.length) {
+    console.log('  Sheets:');
+    for (const p of manifest.sheet_paths) {
+      console.log(`    ${p}`);
+    }
+    console.log('');
+  }
+}

package/scripts/brief-compile.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+/**
+ * brief-compile.js — Compile a generation brief from project truth.
+ *
+ * Usage:
+ *   sdlab brief compile --project star-freight --workflow character-portrait-set --subject kael_maren
+ *   sdlab brief compile --project star-freight --workflow environment-moodboard
+ *   sdlab brief compile --project star-freight --workflow character-portrait-set --subject kael_maren --reference sf_001,sf_018
+ *   sdlab brief compile --project star-freight --workflow character-portrait-set --subject kael_maren --output-count 8 --json
+ */
+
+import { parseArgs, getProjectName, parseNumberFlag } from '../lib/args.js';
+import { getProjectRoot } from '../lib/paths.js';
+import { compileBrief, saveCompiledBrief } from '../lib/brief-compiler.js';
+import { info } from '../lib/log.js';
+
+export async function run(argv = process.argv.slice(2)) {
+  const { flags } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      workflow: { type: 'string' },
+      subject: { type: 'string' },
+      asset: { type: 'string' },
+      'implementation-pack': { type: 'string' },
+      reference: { type: 'string' },
+      'output-count': { type: 'string' },
+      width: { type: 'string' },
+      height: { type: 'string' },
+      steps: { type: 'string' },
+      cfg: { type: 'string' },
+      sampler: { type: 'string' },
+      'seed-mode': { type: 'string' },
+      json: { type: 'boolean' },
+      'dry-run': { type: 'boolean' },
+    },
+    deprecated: { game: 'project' },
+  });
+
+  if (!flags.workflow) {
+    console.log('Usage: sdlab brief compile --workflow <id> [--subject <id>] [--project <name>]');
+    console.log('');
+    console.log('Options:');
+    console.log('  --workflow <id>         Workflow profile to use (required)');
+    console.log('  --subject <id>          Subject ID for subject-driven workflows');
+    console.log('  --asset <id>            Training asset reference');
+    console.log('  --implementation-pack <id>  Implementation pack reference');
+    console.log('  --reference <ids>       Comma-separated reference record IDs');
+    console.log('  --output-count <n>      Override output count');
+    console.log('  --width <px>            Override width');
+    console.log('  --height <px>           Override height');
+    console.log('  --steps <n>             Override steps');
+    console.log('  --cfg <n>               Override CFG scale');
+    console.log('  --sampler <name>        Override sampler');
+    console.log('  --seed-mode <mode>      Override seed mode (fixed|increment|random)');
+    console.log('  --json                  Output raw JSON');
+    console.log('  --dry-run               Preview without saving');
+    return;
+  }
+
+  const projectName = flags.project || getProjectName(argv);
+  const projectRoot = getProjectRoot(projectName);
+
+  // Parse reference IDs
+  const referenceIds = flags.reference
+    ? flags.reference.split(',').map(s => s.trim()).filter(Boolean)
+    : undefined;
+
+  // Parse overrides
+  const overrides = {};
+  if (flags['output-count']) overrides.output_count = parseNumberFlag('output-count', flags['output-count'], { int: true, min: 1 });
+  if (flags.width) overrides.width = parseNumberFlag('width', flags.width, { int: true, min: 1 });
+  if (flags.height) overrides.height = parseNumberFlag('height', flags.height, { int: true, min: 1 });
+  if (flags.steps) overrides.steps = parseNumberFlag('steps', flags.steps, { int: true, min: 1 });
+  if (flags.cfg) overrides.cfg = parseNumberFlag('cfg', flags.cfg, { min: 0 });
+  if (flags.sampler) overrides.sampler = flags.sampler;
+  if (flags['seed-mode']) overrides.seed_mode = flags['seed-mode'];
+
+  const brief = await compileBrief({
+    projectRoot,
+    projectId: projectName,
+    workflowId: flags.workflow,
+    subjectId: flags.subject,
+    assetRef: flags.asset,
+    implementationPackRef: flags['implementation-pack'],
+    referenceIds,
+    overrides,
+  });
+
+  if (flags.json) {
+    console.log(JSON.stringify(brief, null, 2));
+    if (!flags['dry-run']) {
+      await saveCompiledBrief(projectRoot, brief);
+    }
+    return;
+  }
+
+  if (!flags['dry-run']) {
+    const { jsonPath, mdPath } = await saveCompiledBrief(projectRoot, brief);
+    info(`\x1b[1msdlab brief compile\x1b[0m — ${projectName}\n`);
+    info(`  Brief ID:   ${brief.brief_id}`);
+    info(`  Workflow:   ${brief.workflow_id}`);
+    info(`  Lane:       ${brief.lane_id}`);
+    if (brief.subject_id) info(`  Subject:    ${brief.subject_id}`);
+    info(`  Outputs:    ${brief.expected_outputs.output_count}× ${brief.expected_outputs.output_mode}`);
+    info('');
+    info(`  Saved: ${jsonPath}`);
+    info(`         ${mdPath}`);
+  } else {
+    info(`\x1b[1msdlab brief compile\x1b[0m — dry run\n`);
+    info(`  Brief ID:   ${brief.brief_id}`);
+    info(`  Workflow:   ${brief.workflow_id}`);
+    info(`  Lane:       ${brief.lane_id}`);
+    if (brief.subject_id) info(`  Subject:    ${brief.subject_id}`);
+    info(`  Outputs:    ${brief.expected_outputs.output_count}× ${brief.expected_outputs.output_mode}`);
+    info('');
+    info('  Prompt:');
+    info(`    ${brief.prompt}`);
+    info('');
+    info('  Negative:');
+    info(`    ${brief.negative_prompt}`);
+    info('');
+    if (brief.drift_warnings?.length > 0) {
+      info('  Drift warnings:');
+      for (const w of brief.drift_warnings) {
+        info(`    \x1b[33m⚠\x1b[0m ${w}`);
+      }
+    }
+  }
+}
+
+if (process.argv[1] && (process.argv[1].endsWith('brief-compile.js') || process.argv[1].endsWith('brief-compile'))) {
+  run().catch((err) => { console.error(err.message || err); process.exit(1); });
+}

package/scripts/brief-show.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+/**
+ * brief-show.js — Show a compiled brief.
+ *
+ * Usage:
+ *   sdlab brief show brief_2026-04-15_001 --project star-freight
+ *   sdlab brief show brief_2026-04-15_001 --json
+ *   sdlab brief show brief_2026-04-15_001 --md
+ */
+
+import { parseArgs, getProjectName } from '../lib/args.js';
+import { getProjectRoot } from '../lib/paths.js';
+import { loadCompiledBrief } from '../lib/brief-compiler.js';
+import { renderBriefText, renderBriefMarkdown } from '../lib/brief-render.js';
+
+export async function run(argv = process.argv.slice(2)) {
+  const { flags, positionals } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      json: { type: 'boolean' },
+      md: { type: 'boolean' },
+    },
+    positionals: ['briefId'],
+    deprecated: { game: 'project' },
+  });
+
+  const briefId = positionals[0];
+  if (!briefId) {
+    console.log('Usage: sdlab brief show <brief-id> [--project <name>] [--json] [--md]');
+    return;
+  }
+
+  const projectName = flags.project || getProjectName(argv);
+  const projectRoot = getProjectRoot(projectName);
+  const brief = await loadCompiledBrief(projectRoot, briefId);
+
+  if (flags.json) {
+    console.log(JSON.stringify(brief, null, 2));
+    return;
+  }
+
+  if (flags.md) {
+    console.log(renderBriefMarkdown(brief));
+    return;
+  }
+
+  console.log(renderBriefText(brief));
+}
+
+if (process.argv[1] && (process.argv[1].endsWith('brief-show.js') || process.argv[1].endsWith('brief-show'))) {
+  run().catch((err) => { console.error(err.message || err); process.exit(1); });
+}

package/scripts/canon-bind.js

@@ -21,6 +21,7 @@ import { join } from 'path';
 import { getProjectName } from '../lib/args.js';
 import { REPO_ROOT } from '../lib/paths.js';
 import { loadConstitution, loadLanes, loadRubric, loadTerminology, detectLane, detectGroup } from '../lib/config.js';
+import { inputError, handleCliError } from '../lib/errors.js';
 
 /**
  * Build rationale string from rule's template, interpolating variables.
@@ -162,10 +163,10 @@ export async function run(argv = process.argv.slice(2)) {
 
   // Load project config — fail loudly if missing
   if (!existsSync(join(PROJECT_ROOT, 'constitution.json'))) {
-    throw new Error(
-      `No constitution.json found in ${PROJECT_ROOT}.\n` +
-      `Canon binding requires per-project config files.\n` +
-      `Run: sdlab init ${projectName} --domain <domain>`
+    throw inputError(
+      'INPUT_MISSING_CONFIG',
+      `No constitution.json found in ${PROJECT_ROOT}.`,
+      `Canon binding requires per-project config files. Run: sdlab init ${projectName} --domain <domain>`
     );
   }
 
@@ -175,7 +176,7 @@ export async function run(argv = process.argv.slice(2)) {
   const termConfig = loadTerminology(PROJECT_ROOT);
 
   if (!constitutionConfig.rules || constitutionConfig.rules.length === 0) {
-    throw new Error(`constitution.json has no rules — cannot bind.`);
+    throw inputError('INPUT_EMPTY_CONFIG', `constitution.json has no rules — cannot bind.`);
   }
 
   const constitutionRules = constitutionConfig.rules;
@@ -280,8 +281,5 @@ export async function run(argv = process.argv.slice(2)) {
 
 // Direct execution guard
 if (process.argv[1] && (process.argv[1].endsWith('canon-bind.js') || process.argv[1].endsWith('canon-bind'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }

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