@mcptoolshop/style-dataset-lab 2.3.0 → 3.0.1

package/scripts/reingest-selected.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+/**
+ * reingest-selected.js — Re-ingest selected outputs as candidate records.
+ *
+ * Usage:
+ *   sdlab reingest selected --selection selection_2026-04-16_001 --project star-freight
+ *   sdlab reingest selected --selection selection_2026-04-16_001 --dry-run
+ */
+
+import { parseArgs, getProjectName } from '../lib/args.js';
+import { getProjectRoot } from '../lib/paths.js';
+import { reingestSelection } from '../lib/reingest-selected.js';
+import { info } from '../lib/log.js';
+
+export async function run(argv = process.argv.slice(2)) {
+  const { flags } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      selection: { type: 'string' },
+      'dry-run': { type: 'boolean' },
+      json: { type: 'boolean' },
+    },
+    deprecated: { game: 'project' },
+  });
+
+  if (!flags.selection) {
+    console.log('Usage: sdlab reingest selected --selection <id> [--project <name>]');
+    console.log('');
+    console.log('Options:');
+    console.log('  --selection <id>   Selection to re-ingest (required)');
+    console.log('  --dry-run          Preview without writing records');
+    console.log('  --json             Output as JSON');
+    return;
+  }
+
+  const projectName = flags.project || getProjectName(argv);
+  const projectRoot = getProjectRoot(projectName);
+  const dryRun = flags['dry-run'] || false;
+
+  console.log(`\x1b[1mstyle-dataset-lab\x1b[0m reingest selected`);
+  console.log(`  Selection: ${flags.selection}`);
+  console.log(`  Project: ${projectName}`);
+  if (dryRun) console.log('  ⚠ DRY RUN');
+  console.log('');
+
+  const { created, skipped } = await reingestSelection({
+    projectRoot,
+    projectId: projectName,
+    selectionId: flags.selection,
+    dryRun,
+  });
+
+  if (flags.json) {
+    console.log(JSON.stringify({ created, skipped }, null, 2));
+    return;
+  }
+
+  if (created.length > 0) {
+    console.log(`  Created ${created.length} candidate record(s):`);
+    for (const id of created) {
+      console.log(`    ✓ ${id}`);
+    }
+  }
+
+  if (skipped.length > 0) {
+    console.log(`  Skipped ${skipped.length} (already exist):`);
+    for (const id of skipped) {
+      console.log(`    ○ ${id}`);
+    }
+  }
+
+  console.log('');
+  if (!dryRun && created.length > 0) {
+    info('Records staged for review. Use sdlab curate to approve/reject.');
+    info(`Images copied to inbox/generated/`);
+  }
+}

package/scripts/reingest.js

@@ -5,38 +5,51 @@
  *
  * Usage:
  *   sdlab reingest generated --source <dir> --manifest <id> [--dry-run] [--project <name>]
+ *   sdlab reingest selected --selection <id> [--project <name>]
  *   sdlab reingest audit [--project <name>]
  */
 
 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 { reingestGenerated, auditReingest } from '../lib/reingest.js';
 
 export async function run(argv = process.argv.slice(2)) {
-  const projectName = getProjectName(argv);
+  const { flags, positionals } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      source: { type: 'string' },
+      manifest: { type: 'string' },
+      selection: { type: 'string' },
+      'dry-run': { type: 'boolean', default: false },
+    },
+    deprecated: { game: 'project' },
+    allowUnknown: true, // forward unknowns to delegated 'selected' path
+  });
+
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = join(REPO_ROOT, 'projects', projectName);
-  const subcommand = argv.find(a => !a.startsWith('--')) || 'audit';
-  const args = argv.filter(a => a !== subcommand);
+  const subcommand = positionals[0] || 'audit';
 
   if (subcommand === 'generated') {
-    const sourceIdx = args.indexOf('--source');
-    if (sourceIdx < 0) throw new Error('--source <dir> is required (directory of generated images)');
-    const sourcePath = args[sourceIdx + 1];
-
-    const manifestIdx = args.indexOf('--manifest');
-    if (manifestIdx < 0) throw new Error('--manifest <id> is required (training manifest that produced the outputs)');
-    const manifestId = args[manifestIdx + 1];
+    if (!flags.source) {
+      throw inputError('INPUT_MISSING_FLAG', '--source <dir> is required (directory of generated images)');
+    }
+    if (!flags.manifest) {
+      throw inputError('INPUT_MISSING_FLAG', '--manifest <id> is required (training manifest that produced the outputs)');
+    }
 
-    const dryRun = args.includes('--dry-run');
+    const safeSource = resolveSafeProjectPath(projectRoot, flags.source, { baseRoot: REPO_ROOT, flagName: 'source' });
+    const dryRun = flags['dry-run'] || flags.dryRun;
 
     console.log(`\x1b[1msdlab reingest generated\x1b[0m — ${projectName}`);
-    console.log(`  Source:   ${sourcePath}`);
-    console.log(`  Manifest: ${manifestId}`);
+    console.log(`  Source:   ${flags.source}`);
+    console.log(`  Manifest: ${flags.manifest}`);
     if (dryRun) console.log(`  Mode:     DRY RUN (no records written)`);
     console.log('');
 
-    const result = await reingestGenerated(projectRoot, sourcePath, manifestId, { dryRun });
+    const result = await reingestGenerated(projectRoot, safeSource, flags.manifest, { dryRun });
 
     console.log(`  \x1b[32m✓\x1b[0m Created: ${result.created} records`);
     if (result.skipped > 0) {
@@ -50,6 +63,12 @@ export async function run(argv = process.argv.slice(2)) {
       console.log('    3. Then eligible for future snapshots');
     }
 
+  } else if (subcommand === 'selected') {
+    // Delegate to reingest-selected.js — pass the full argv so it can re-parse
+    const { run: runSelected } = await import('./reingest-selected.js');
+    await runSelected(argv.slice(argv.indexOf(subcommand) + 1));
+    return;
+
   } else if (subcommand === 'audit') {
     console.log(`\x1b[1msdlab reingest audit\x1b[0m — ${projectName}\n`);
 
@@ -77,10 +96,10 @@ export async function run(argv = process.argv.slice(2)) {
     }
 
   } else {
-    throw new Error(`Unknown subcommand: ${subcommand}. Use: generated, audit`);
+    throw inputError('INPUT_BAD_SUBCOMMAND', `Unknown subcommand: ${subcommand}. Use: generated, selected, audit`);
   }
 }
 
 if (process.argv[1] && (process.argv[1].endsWith('reingest.js') || process.argv[1].endsWith('reingest'))) {
-  run().catch((err) => { console.error(err.message || err); process.exit(1); });
+  run().catch(handleCliError);
 }

package/scripts/run-generate.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+/**
+ * run-generate.js — Execute a compiled brief through ComfyUI.
+ *
+ * Usage:
+ *   sdlab run generate --brief brief_2026-04-15_001 --project star-freight
+ *   sdlab run generate --brief brief_2026-04-15_001 --project star-freight --dry-run
+ *   sdlab run generate --brief brief_2026-04-15_001 --project star-freight --seed 42
+ */
+
+import { parseArgs, getProjectName, parseNumberFlag } from '../lib/args.js';
+import { getProjectRoot, getRunsDir } from '../lib/paths.js';
+import { loadCompiledBrief } from '../lib/brief-compiler.js';
+import { executeRun } from '../lib/adapters/comfyui-runner.js';
+import { saveRunSummary, renderRunText } from '../lib/run-summary.js';
+import { info } from '../lib/log.js';
+import { join } from 'node:path';
+
+export async function run(argv = process.argv.slice(2)) {
+  const { flags } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      brief: { type: 'string' },
+      seed: { type: 'string' },
+      'dry-run': { type: 'boolean' },
+      json: { type: 'boolean' },
+    },
+    deprecated: { game: 'project' },
+  });
+
+  if (!flags.brief) {
+    console.log('Usage: sdlab run generate --brief <id> [--project <name>]');
+    console.log('');
+    console.log('Options:');
+    console.log('  --brief <id>      Compiled brief ID (required)');
+    console.log('  --seed <n>        Override base seed');
+    console.log('  --dry-run         Prepare run dir without submitting to ComfyUI');
+    console.log('  --json            Output manifest as JSON');
+    return;
+  }
+
+  const projectName = flags.project || getProjectName(argv);
+  const projectRoot = getProjectRoot(projectName);
+
+  console.log(`\x1b[1mstyle-dataset-lab\x1b[0m run generate`);
+  console.log(`  Project: ${projectName}`);
+  console.log(`  Brief: ${flags.brief}`);
+  if (flags['dry-run']) console.log('  ⚠ DRY RUN');
+  console.log('');
+
+  // Load brief
+  const brief = await loadCompiledBrief(projectRoot, flags.brief);
+
+  // Execute
+  const manifest = await executeRun({
+    projectRoot,
+    projectName,
+    brief,
+    baseSeed: flags.seed ? parseNumberFlag('seed', flags.seed, { int: true, min: 0 }) : undefined,
+    dryRun: flags['dry-run'] || false,
+  });
+
+  // Save summary
+  const runDir = join(getRunsDir(projectRoot), manifest.run_id);
+  await saveRunSummary(runDir, manifest);
+
+  console.log('');
+  if (flags.json) {
+    console.log(JSON.stringify(manifest, null, 2));
+  } else {
+    console.log(renderRunText(manifest));
+    console.log('');
+    info(`Run saved to: runs/${manifest.run_id}/`);
+  }
+}

package/scripts/run-list.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+/**
+ * run-list.js — List all runs for a project.
+ *
+ * Usage:
+ *   sdlab run list --project star-freight
+ *   sdlab run list --project star-freight --json
+ */
+
+import { parseArgs, getProjectName } from '../lib/args.js';
+import { getProjectRoot } from '../lib/paths.js';
+import { listRuns } from '../lib/runtime-runs.js';
+
+export async function run(argv = process.argv.slice(2)) {
+  const { flags } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      json: { type: 'boolean' },
+    },
+    deprecated: { game: 'project' },
+  });
+
+  const projectName = flags.project || getProjectName(argv);
+  const projectRoot = getProjectRoot(projectName);
+  const runs = listRuns(projectRoot);
+
+  if (flags.json) {
+    console.log(JSON.stringify(runs, null, 2));
+    return;
+  }
+
+  if (runs.length === 0) {
+    console.log('No runs found. Run: sdlab run generate --brief <id>');
+    return;
+  }
+
+  console.log(`\x1b[1mRuns for ${projectName}\x1b[0m (${runs.length})\n`);
+
+  const header = '  ' +
+    'Run ID'.padEnd(26) +
+    'Brief'.padEnd(26) +
+    'Mode'.padEnd(18) +
+    'Count'.padEnd(8) +
+    'Created';
+  console.log(header);
+  console.log('  ' + '─'.repeat(90));
+
+  for (const r of runs) {
+    const line = '  ' +
+      (r.run_id || '').padEnd(26) +
+      (r.brief_id || '').padEnd(26) +
+      (r.adapter_target || '?').padEnd(18) +
+      String(r.output_count ?? '?').padEnd(8) +
+      (r.created_at ? r.created_at.slice(0, 16) : '?');
+    console.log(line);
+  }
+}

package/scripts/run-show.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+/**
+ * run-show.js — Show details of a completed run.
+ *
+ * Usage:
+ *   sdlab run show run_2026-04-16_001 --project star-freight
+ *   sdlab run show run_2026-04-16_001 --project star-freight --json
+ *   sdlab run show run_2026-04-16_001 --project star-freight --md
+ */
+
+import { parseArgs, getProjectName } from '../lib/args.js';
+import { getProjectRoot } from '../lib/paths.js';
+import { loadRun, listRuns } from '../lib/runtime-runs.js';
+import { renderRunText, renderRunMarkdown } from '../lib/run-summary.js';
+
+export async function run(argv = process.argv.slice(2)) {
+  const { positionals, flags } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      json: { type: 'boolean' },
+      md: { type: 'boolean' },
+    },
+    deprecated: { game: 'project' },
+  });
+
+  const runId = positionals[0];
+  const projectName = flags.project || getProjectName(argv);
+  const projectRoot = getProjectRoot(projectName);
+
+  // No run ID → list runs
+  if (!runId) {
+    const runs = listRuns(projectRoot);
+    if (runs.length === 0) {
+      console.log('No runs found. Run: sdlab run generate --brief <id>');
+      return;
+    }
+
+    console.log(`\x1b[1mRuns for ${projectName}\x1b[0m (${runs.length})\n`);
+    console.log('  ID                       Brief                      Mode            Outputs  Adapter');
+    console.log('  ─'.padEnd(100, '─'));
+    for (const r of runs) {
+      const id = (r.run_id || '').padEnd(24);
+      const brief = (r.brief_id || '').padEnd(24);
+      const mode = (r.output_count != null ? `${r.output_count}` : '?').padStart(7);
+      const adapter = r.adapter_target || '?';
+      // output_mode if we have it
+      console.log(`  ${id}  ${brief}  ${mode}  ${adapter}`);
+    }
+    return;
+  }
+
+  // Show single run
+  const manifest = await loadRun(projectRoot, runId);
+
+  if (flags.json) {
+    console.log(JSON.stringify(manifest, null, 2));
+  } else if (flags.md) {
+    console.log(renderRunMarkdown(manifest));
+  } else {
+    console.log(renderRunText(manifest));
+  }
+}

package/scripts/select.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+
+/**
+ * select.js — Approve outputs from runs or batches.
+ *
+ * Usage:
+ *   sdlab select --run run_2026-04-15_001 --approve 001.png,003.png
+ *   sdlab select --batch batch_2026-04-16_001 --approve slot_neutral:001.png,slot_anger:001.png
+ *   sdlab select --run run_2026-04-15_001 --approve 001.png --reason "best continuity" --tags portrait,keeper
+ */
+
+import { parseArgs, getProjectName } from '../lib/args.js';
+import { getProjectRoot } from '../lib/paths.js';
+import { inputError, handleCliError } from '../lib/errors.js';
+import {
+  createSelectionFromRun,
+  createSelectionFromBatch,
+  saveSelection,
+} from '../lib/selections.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' },
+      batch: { type: 'string' },
+      approve: { type: 'string' },
+      reason: { type: 'string' },
+      tags: { type: 'string' },
+      json: { type: 'boolean' },
+    },
+    deprecated: { game: 'project' },
+  });
+
+  if (!flags.approve || (!flags.run && !flags.batch)) {
+    console.log('Usage: sdlab select --run <id> --approve <files>');
+    console.log('       sdlab select --batch <id> --approve <slot:file,...>');
+    console.log('');
+    console.log('Options:');
+    console.log('  --run <id>          Source run');
+    console.log('  --batch <id>        Source batch');
+    console.log('  --approve <list>    Comma-separated files (run) or slot:file pairs (batch)');
+    console.log('  --reason <text>     Why these outputs were chosen');
+    console.log('  --tags <list>       Comma-separated tags');
+    console.log('  --json              Output manifest as JSON');
+    return;
+  }
+
+  const projectName = flags.project || getProjectName(argv);
+  const projectRoot = getProjectRoot(projectName);
+  const reason = flags.reason || undefined;
+  const tags = flags.tags ? flags.tags.split(',').map(t => t.trim()) : undefined;
+
+  let result;
+
+  if (flags.run) {
+    // Run selection: --approve 001.png,003.png
+    const approvedFiles = flags.approve.split(',').map(f => f.trim());
+
+    result = await createSelectionFromRun({
+      projectRoot,
+      projectId: projectName,
+      runId: flags.run,
+      approvedFiles,
+      reason,
+      tags,
+    });
+  } else if (flags.batch) {
+    // Batch selection: --approve slot_neutral:001.png,slot_anger:001.png
+    const pairs = flags.approve.split(',').map(p => p.trim());
+    const approvedSlots = pairs.map(pair => {
+      const colonIdx = pair.indexOf(':');
+      if (colonIdx < 0) {
+        throw inputError('INPUT_BAD_FORMAT', `Invalid batch approve format: "${pair}". Use slot_id:filename`);
+      }
+      return {
+        slotId: pair.slice(0, colonIdx),
+        filename: pair.slice(colonIdx + 1),
+      };
+    });
+
+    result = await createSelectionFromBatch({
+      projectRoot,
+      projectId: projectName,
+      batchId: flags.batch,
+      approvedSlots,
+      reason,
+      tags,
+    });
+  }
+
+  const { selectionId, selectionDir, manifest } = result;
+
+  // Save the selection
+  await saveSelection(selectionDir, manifest);
+
+  if (flags.json) {
+    console.log(JSON.stringify(manifest, null, 2));
+    return;
+  }
+
+  console.log(`\x1b[1mstyle-dataset-lab\x1b[0m select`);
+  console.log('');
+  console.log(`  Selection: ${selectionId}`);
+  console.log(`  Source: ${manifest.source_type} ${manifest.source_id}`);
+  if (manifest.workflow_id) console.log(`  Workflow: ${manifest.workflow_id}`);
+  if (manifest.subject_id) console.log(`  Subject: ${manifest.subject_id}`);
+  console.log(`  Items: ${manifest.items.length}`);
+  console.log('');
+
+  for (const item of manifest.items) {
+    console.log(`  ✓ ${item.slot_or_output.padEnd(28)} → ${item.filename}  ${item.reason}`);
+  }
+
+  console.log('');
+  info(`Selection: selections/${selectionId}/manifest.json`);
+  info(`Chosen files: selections/${selectionId}/chosen/`);
+}

package/scripts/selection-show.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+/**
+ * selection-show.js — Show selection details or list all selections.
+ *
+ * Usage:
+ *   sdlab selection show --project star-freight
+ *   sdlab selection show --selection selection_2026-04-16_001
+ *   sdlab selection show selection_2026-04-16_001 --json
+ */
+
+import { parseArgs, getProjectName } from '../lib/args.js';
+import { getProjectRoot } from '../lib/paths.js';
+import { loadSelection, listSelections, getSelectionsDir } from '../lib/selections.js';
+import { join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+
+export async function run(argv = process.argv.slice(2)) {
+  const { flags, positionals } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      selection: { type: 'string' },
+      json: { type: 'boolean' },
+    },
+    deprecated: { game: 'project' },
+  });
+
+  const projectName = flags.project || getProjectName(argv);
+  const projectRoot = getProjectRoot(projectName);
+  const selectionId = positionals[0] || flags.selection;
+
+  // List mode
+  if (!selectionId) {
+    const selections = listSelections(projectRoot);
+    if (selections.length === 0) {
+      console.log('No selections found.');
+      return;
+    }
+    console.log(`\x1b[1mstyle-dataset-lab\x1b[0m selections (${projectName})`);
+    console.log('');
+    for (const id of selections) {
+      try {
+        const m = loadSelection(projectRoot, id);
+        const items = m.items?.length || 0;
+        const src = `${m.source_type}:${m.source_id}`;
+        const ready = m.reingest_ready ? '✓' : '○';
+        const subject = m.subject_id ? ` (${m.subject_id})` : '';
+        console.log(`  ${ready} ${id}  ${src.padEnd(32)} ${items} items${subject}`);
+      } catch {
+        console.log(`  ? ${id}  (manifest unreadable)`);
+      }
+    }
+    console.log('');
+    return;
+  }
+
+  // Detail mode
+  const manifest = loadSelection(projectRoot, selectionId);
+
+  if (flags.json) {
+    console.log(JSON.stringify(manifest, null, 2));
+    return;
+  }
+
+  console.log(`\x1b[1mstyle-dataset-lab\x1b[0m selection ${selectionId}`);
+  console.log('');
+  console.log(`  Source:          ${manifest.source_type} ${manifest.source_id}`);
+  if (manifest.workflow_id) console.log(`  Workflow:        ${manifest.workflow_id}`);
+  if (manifest.subject_id) console.log(`  Subject:         ${manifest.subject_id}`);
+  console.log(`  Created:         ${manifest.created_at}`);
+  console.log(`  Re-ingest ready: ${manifest.reingest_ready ? 'yes' : 'no'}`);
+  console.log('');
+  console.log('  Chosen outputs:');
+  for (const item of manifest.items || []) {
+    const seedStr = item.seed !== undefined ? `seed=${item.seed}` : '';
+    console.log(`    ✓ ${item.slot_or_output.padEnd(28)} → ${item.filename}  ${seedStr}`);
+    if (item.reason) console.log(`      ${item.reason}`);
+    if (item.tags?.length) console.log(`      tags: ${item.tags.join(', ')}`);
+  }
+
+  // Check provenance log
+  const provPath = join(getSelectionsDir(projectRoot), selectionId, 'provenance.jsonl');
+  if (existsSync(provPath)) {
+    console.log('');
+    console.log('  Provenance log: provenance.jsonl');
+  }
+  console.log('');
+}

package/scripts/snapshot.js

@@ -12,30 +12,33 @@
 
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { existsSync } from 'node:fs';
-import { getProjectName } from '../lib/args.js';
+import { parseArgs, getProjectName } from '../lib/args.js';
 import { REPO_ROOT } from '../lib/paths.js';
 import { loadSelectionProfile } from '../lib/config.js';
+import { inputError, handleCliError } from '../lib/errors.js';
 import { createSnapshot, loadSnapshot, listSnapshots, diffSnapshots } from '../lib/snapshot.js';
-import { evaluateEligibility } from '../lib/eligibility.js';
 import { categorizeExclusions } from '../lib/eligibility.js';
 
 export async function run(argv = process.argv.slice(2)) {
-  const projectName = getProjectName(argv);
-  const projectRoot = join(REPO_ROOT, 'projects', projectName);
-  const subcommand = argv.find(a => !a.startsWith('--')) || 'list';
+  const { flags, positionals } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      profile: { type: 'string' },
+      'dry-run': { type: 'boolean', default: false },
+    },
+    deprecated: { game: 'project' },
+  });
 
-  // Strip subcommand from argv for flag parsing
-  const args = argv.filter(a => a !== subcommand);
+  const projectName = flags.project || getProjectName(argv);
+  const projectRoot = join(REPO_ROOT, 'projects', projectName);
+  const subcommand = positionals[0] || 'list';
+  const dryRun = flags['dry-run'] || flags.dryRun;
 
   if (subcommand === 'create') {
-    const profileIdx = args.indexOf('--profile');
-    const profileId = profileIdx >= 0 ? args[profileIdx + 1] : null;
-    const profile = loadSelectionProfile(projectRoot, profileId);
-    const dryRun = argv.includes('--dry-run');
+    const profile = loadSelectionProfile(projectRoot, flags.profile);
 
     console.log(`\x1b[1msdlab snapshot create\x1b[0m — ${projectName}`);
-    console.log(`  Profile: ${profileId || 'training-default (built-in)'}`);
+    console.log(`  Profile: ${flags.profile || 'training-default (built-in)'}`);
     if (dryRun) console.log('  Mode: DRY RUN (no files written)');
     console.log('');
 
@@ -46,7 +49,6 @@ export async function run(argv = process.argv.slice(2)) {
     console.log(`  Excluded: ${result.excluded}`);
 
     if (!dryRun) {
-      // Read and display summary
       const summary = JSON.parse(
         await readFile(join(projectRoot, 'snapshots', result.snapshotId, 'summary.json'), 'utf-8')
       );
@@ -59,7 +61,6 @@ export async function run(argv = process.argv.slice(2)) {
         console.log(`    ${f}: ${c}`);
       }
 
-      // Read and categorize exclusions
       const excludedRaw = await readFile(
         join(projectRoot, 'snapshots', result.snapshotId, 'excluded.jsonl'), 'utf-8'
       );
@@ -83,8 +84,8 @@ export async function run(argv = process.argv.slice(2)) {
     }
 
   } else if (subcommand === 'show') {
-    const snapshotId = args.find(a => a.startsWith('snap-'));
-    if (!snapshotId) throw new Error('Usage: sdlab snapshot show <snapshot-id>');
+    const snapshotId = positionals[1] || positionals.find(a => a.startsWith('snap-'));
+    if (!snapshotId) throw inputError('INPUT_MISSING_ARGS', 'Usage: sdlab snapshot show <snapshot-id>');
 
     const manifest = await loadSnapshot(projectRoot, snapshotId);
     console.log(`\x1b[1mSnapshot\x1b[0m — ${snapshotId}\n`);
@@ -102,8 +103,8 @@ export async function run(argv = process.argv.slice(2)) {
     }
 
   } else if (subcommand === 'diff') {
-    const snapIds = args.filter(a => a.startsWith('snap-'));
-    if (snapIds.length < 2) throw new Error('Usage: sdlab snapshot diff <id-a> <id-b>');
+    const snapIds = positionals.slice(1).filter(a => a.startsWith('snap-'));
+    if (snapIds.length < 2) throw inputError('INPUT_MISSING_ARGS', 'Usage: sdlab snapshot diff <id-a> <id-b>');
 
     const diff = await diffSnapshots(projectRoot, snapIds[0], snapIds[1]);
     console.log(`\x1b[1mSnapshot diff\x1b[0m — ${snapIds[0]} vs ${snapIds[1]}\n`);
@@ -123,14 +124,11 @@ export async function run(argv = process.argv.slice(2)) {
     }
 
   } else {
-    throw new Error(`Unknown subcommand: ${subcommand}. Use: create, list, show, diff`);
+    throw inputError('INPUT_BAD_SUBCOMMAND', `Unknown subcommand: ${subcommand}. Use: create, list, show, diff`);
   }
 }
 
 // Direct execution guard
 if (process.argv[1] && (process.argv[1].endsWith('snapshot.js') || process.argv[1].endsWith('snapshot'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }