@mcptoolshop/style-dataset-lab 2.0.0 → 2.2.0

package/scripts/eval-pack.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+/**
+ * eval-pack.js — Build and inspect canon-aware eval packs.
+ *
+ * Usage:
+ *   sdlab eval-pack build [--project <name>]
+ *   sdlab eval-pack list [--project <name>]
+ *   sdlab eval-pack show <eval-id> [--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 { buildEvalPack, listEvalPacks, loadEvalPack } from '../lib/eval-pack.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 args = argv.filter(a => a !== subcommand);
+
+  if (subcommand === 'build') {
+    console.log(`\x1b[1msdlab eval-pack build\x1b[0m — ${projectName}\n`);
+
+    const result = await buildEvalPack(projectRoot);
+
+    console.log(`  \x1b[32m✓\x1b[0m Eval pack: ${result.evalId}`);
+    console.log('');
+    console.log('  Tasks:');
+    for (const [task, count] of Object.entries(result.tasks)) {
+      console.log(`    ${task.padEnd(24)} ${count} records`);
+    }
+    const total = Object.values(result.tasks).reduce((s, n) => s + n, 0);
+    console.log(`    ${'─'.repeat(36)}`);
+    console.log(`    ${'total'.padEnd(24)} ${total} records`);
+
+  } else if (subcommand === 'list') {
+    const packs = await listEvalPacks(projectRoot);
+    if (packs.length === 0) {
+      console.log('No eval packs found. Run: sdlab eval-pack build');
+      return;
+    }
+    console.log(`\x1b[1mEval packs\x1b[0m — ${projectName}\n`);
+    for (const p of packs) {
+      console.log(`  ${p.id}  total=${p.total}  lane=${p.tasks.lane_coverage} drift=${p.tasks.forbidden_drift} gold=${p.tasks.anchor_gold} cont=${p.tasks.subject_continuity}  ${p.created_at}`);
+    }
+
+  } 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 manifest = await loadEvalPack(projectRoot, evalId);
+    console.log(`\x1b[1mEval pack\x1b[0m — ${evalId}\n`);
+    console.log(`  Created: ${manifest.created_at}`);
+    console.log(`  Project: ${manifest.project}`);
+    console.log('');
+    console.log('  Tasks:');
+    for (const [task, count] of Object.entries(manifest.task_counts)) {
+      console.log(`    ${task.padEnd(24)} ${count} records`);
+    }
+    console.log(`\n  Total: ${manifest.total_records} records`);
+
+    // Show sample from each task file
+    const evalDir = join(projectRoot, 'eval-packs', evalId);
+    for (const taskFile of ['lane-coverage', 'forbidden-drift', 'anchor-gold', 'subject-continuity']) {
+      const raw = await readFile(join(evalDir, `${taskFile}.jsonl`), 'utf-8');
+      const entries = raw.trim().split('\n').filter(Boolean).map(l => JSON.parse(l));
+      if (entries.length > 0) {
+        console.log(`\n  ${taskFile} (first 3):`);
+        for (const entry of entries.slice(0, 3)) {
+          const summary = entry.record_id || entry.subject_name;
+          const detail = entry.pass_ratio != null ? `ratio=${entry.pass_ratio}` :
+            entry.violations ? `violations=${entry.violations.length}` :
+              `records=${entry.record_count}`;
+          console.log(`    ${summary}  ${detail}`);
+        }
+      }
+    }
+
+  } else {
+    throw new Error(`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);
+  });
+}

package/scripts/eval-run.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+/**
+ * eval-run.js — Create, score, and inspect eval runs.
+ *
+ * Usage:
+ *   sdlab eval-run create --manifest <id> --eval-pack <id> [--project <name>]
+ *   sdlab eval-run score <eval-run-id> --outputs <path> [--project <name>]
+ *   sdlab eval-run show <eval-run-id> [--project <name>]
+ *   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 { 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 projectRoot = join(REPO_ROOT, 'projects', projectName);
+  const subcommand = argv.find(a => !a.startsWith('--') && !a.startsWith('er-')) || 'list';
+  const args = argv.filter(a => a !== subcommand);
+
+  if (subcommand === 'create') {
+    // Find manifest
+    let manifestId;
+    const manifestIdx = args.indexOf('--manifest');
+    if (manifestIdx >= 0) {
+      manifestId = args[manifestIdx + 1];
+    } else {
+      const manifests = await listTrainingManifests(projectRoot);
+      if (manifests.length === 0) throw new Error('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 {
+      const packs = await listEvalPacks(projectRoot);
+      if (packs.length === 0) throw new Error('No eval packs. Run: sdlab eval-pack build');
+      evalPackId = packs[packs.length - 1].id;
+    }
+
+    console.log(`\x1b[1msdlab eval-run create\x1b[0m — ${projectName}`);
+    console.log(`  Manifest:  ${manifestId}`);
+    console.log(`  Eval pack: ${evalPackId}`);
+    console.log('');
+
+    const result = await createEvalRun(projectRoot, manifestId, evalPackId);
+    console.log(`  \x1b[32m✓\x1b[0m Eval run: ${result.evalRunId}`);
+    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 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];
+
+    console.log(`\x1b[1msdlab eval-run score\x1b[0m — ${evalRunId}\n`);
+
+    const { scorecard } = await scoreEvalRun(projectRoot, evalRunId, outputsPath);
+
+    const verdict = scorecard.overall_verdict === 'pass'
+      ? `\x1b[32mPASS\x1b[0m` : `\x1b[31mFAIL\x1b[0m`;
+    console.log(`  Verdict: ${verdict} (${(scorecard.overall_score * 100).toFixed(1)}%)`);
+    console.log(`  Outputs: ${scorecard.output_count} (${scorecard.accepted_count} accepted, ${scorecard.rejected_count} rejected)`);
+    console.log('');
+    console.log('  Tasks:');
+    for (const [name, task] of Object.entries(scorecard.tasks)) {
+      const status = task.passed ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
+      console.log(`    ${status} ${name.padEnd(24)} ${(task.score * 100).toFixed(1)}%`);
+    }
+
+  } 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 run = await loadEvalRun(projectRoot, evalRunId);
+    console.log(`\x1b[1mEval run\x1b[0m — ${evalRunId}\n`);
+    console.log(`  Created:   ${run.created_at}`);
+    console.log(`  Status:    ${run.status}`);
+    console.log(`  Manifest:  ${run.training_manifest_id}`);
+    console.log(`  Eval pack: ${run.eval_pack_id}`);
+    console.log(`  Profile:   ${run.training_profile_id}`);
+    console.log(`  Adapter:   ${run.adapter_target}`);
+
+    if (run.scorecard) {
+      console.log('');
+      console.log(`  Verdict:   ${run.scorecard.overall_verdict.toUpperCase()}`);
+      console.log(`  Score:     ${(run.scorecard.overall_score * 100).toFixed(1)}%`);
+      console.log(`  Outputs:   ${run.scorecard.output_count} (${run.scorecard.accepted_count} accepted)`);
+    }
+
+  } else if (subcommand === 'list') {
+    const runs = await listEvalRuns(projectRoot);
+    if (runs.length === 0) {
+      console.log('No eval runs found. Run: sdlab eval-run create');
+      return;
+    }
+    console.log(`\x1b[1mEval runs\x1b[0m — ${projectName}\n`);
+    for (const r of runs) {
+      const verdict = r.verdict ? ` verdict=${r.verdict}` : '';
+      console.log(`  ${r.id}  manifest=${r.manifest}  status=${r.status}${verdict}  ${r.created_at}`);
+    }
+
+  } else {
+    throw new Error(`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); });
+}

package/scripts/export.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+/**
+ * export.js — Build and list versioned export packages.
+ *
+ * Usage:
+ *   sdlab export build [--snapshot <id>] [--split <id>] [--profile <name>] [--copy] [--project <name>]
+ *   sdlab export list [--project <name>]
+ */
+
+import { join } from 'node:path';
+import { getProjectName } from '../lib/args.js';
+import { REPO_ROOT } from '../lib/paths.js';
+import { listSnapshots } from '../lib/snapshot.js';
+import { listSplits } from '../lib/split.js';
+import { buildExport, listExports, loadExport } from '../lib/export.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('--') && a !== 'true') || 'list';
+  const args = argv.filter(a => a !== subcommand);
+
+  if (subcommand === 'build') {
+    // Find snapshot
+    let snapshotId;
+    const snapIdx = args.indexOf('--snapshot');
+    if (snapIdx >= 0) {
+      snapshotId = args[snapIdx + 1];
+    } else {
+      const snapshots = await listSnapshots(projectRoot);
+      if (snapshots.length === 0) throw new Error('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 {
+      const splits = await listSplits(projectRoot);
+      if (splits.length === 0) throw new Error('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('');
+
+    const result = await buildExport(projectRoot, snapshotId, splitId, { profileId, copy });
+
+    console.log(`  \x1b[32m✓\x1b[0m Export: ${result.exportId}`);
+    console.log(`  Records: ${result.recordCount}`);
+    console.log(`  Images:  ${result.imageCount}`);
+
+  } else if (subcommand === 'list') {
+    const exports = await listExports(projectRoot);
+    if (exports.length === 0) {
+      console.log('No exports found. Run: sdlab export build');
+      return;
+    }
+    console.log(`\x1b[1mExports\x1b[0m — ${projectName}\n`);
+    for (const e of exports) {
+      console.log(`  ${e.id}  snap=${e.snapshot_id}  split=${e.split_id}  records=${e.records}  images=${e.images}  ${e.created_at}`);
+    }
+
+  } else {
+    throw new Error(`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);
+  });
+}

package/scripts/implementation-pack.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+/**
+ * implementation-pack.js — Build and inspect implementation example packs.
+ *
+ * Usage:
+ *   sdlab implementation-pack build --manifest <id> [--project <name>]
+ *   sdlab implementation-pack show <impl-id> [--project <name>]
+ *   sdlab implementation-pack list [--project <name>]
+ */
+
+import { join } from 'node:path';
+import { getProjectName } from '../lib/args.js';
+import { REPO_ROOT } from '../lib/paths.js';
+import { listTrainingManifests } from '../lib/training-manifests.js';
+import { buildImplementationPack, listImplementationPacks, loadImplementationPack } from '../lib/implementation-packs.js';
+
+export async function run(argv = process.argv.slice(2)) {
+  const projectName = getProjectName(argv);
+  const projectRoot = join(REPO_ROOT, 'projects', projectName);
+  const subcommand = argv.find(a => !a.startsWith('--') && !a.startsWith('impl-') && !a.startsWith('tm-')) || 'list';
+  const args = argv.filter(a => a !== subcommand);
+
+  if (subcommand === 'build') {
+    let manifestId;
+    const manifestIdx = args.indexOf('--manifest');
+    if (manifestIdx >= 0) {
+      manifestId = args[manifestIdx + 1];
+    } else {
+      const manifests = await listTrainingManifests(projectRoot);
+      if (manifests.length === 0) throw new Error('No training manifests. Run: sdlab training-manifest create');
+      manifestId = manifests[manifests.length - 1].id;
+    }
+
+    console.log(`\x1b[1msdlab implementation-pack build\x1b[0m — ${projectName}`);
+    console.log(`  Manifest: ${manifestId}`);
+    console.log('');
+
+    const result = await buildImplementationPack(projectRoot, manifestId);
+
+    console.log(`  \x1b[32m✓\x1b[0m Implementation pack: ${result.implId}`);
+    console.log(`  Prompt examples:      ${result.prompts}`);
+    console.log(`  Known failures:       ${result.failures}`);
+    console.log(`  Subject continuity:   ${result.subjects}`);
+
+  } else if (subcommand === 'show') {
+    const implId = args.find(a => a.startsWith('impl-'));
+    if (!implId) throw new Error('Usage: sdlab implementation-pack show <impl-id>');
+
+    const pack = await loadImplementationPack(projectRoot, implId);
+    console.log(`\x1b[1mImplementation pack\x1b[0m — ${implId}\n`);
+    console.log(`  Created:    ${pack.created_at}`);
+    console.log(`  Manifest:   ${pack.training_manifest_id}`);
+    console.log(`  Profile:    ${pack.training_profile_id}`);
+    console.log(`  Prompts:    ${pack.counts.prompt_examples}`);
+    console.log(`  Failures:   ${pack.counts.known_failures}`);
+    console.log(`  Subjects:   ${pack.counts.subject_examples}`);
+    console.log(`  Lanes:      ${pack.counts.lanes_covered}`);
+
+  } else if (subcommand === 'list') {
+    const packs = await listImplementationPacks(projectRoot);
+    if (packs.length === 0) {
+      console.log('No implementation packs. Run: sdlab implementation-pack build');
+      return;
+    }
+    console.log(`\x1b[1mImplementation packs\x1b[0m — ${projectName}\n`);
+    for (const p of packs) {
+      console.log(`  ${p.id}  manifest=${p.manifest}  prompts=${p.prompts}  failures=${p.failures}  ${p.created_at}`);
+    }
+
+  } else {
+    throw new Error(`Unknown subcommand: ${subcommand}. Use: build, show, list`);
+  }
+}
+
+if (process.argv[1] && (process.argv[1].endsWith('implementation-pack.js') || process.argv[1].endsWith('implementation-pack'))) {
+  run().catch((err) => { console.error(err.message || err); process.exit(1); });
+}

package/scripts/init.js

@@ -32,6 +32,14 @@ const PROJECT_DIRS = [
   'outputs/painterly',
   'outputs/painterly-test',
   'exports',
+  'snapshots',
+  'splits',
+  'eval-packs',
+  'training/profiles',
+  'training/manifests',
+  'training/packages',
+  'training/eval-runs',
+  'training/implementations',
 ];
 
 function isValidName(name) {

package/scripts/reingest.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+/**
+ * reingest.js — Re-ingest generated outputs as new project records.
+ *
+ * Usage:
+ *   sdlab reingest generated --source <dir> --manifest <id> [--dry-run] [--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 { reingestGenerated, auditReingest } from '../lib/reingest.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('--')) || 'audit';
+  const args = argv.filter(a => a !== subcommand);
+
+  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];
+
+    const dryRun = args.includes('--dry-run');
+
+    console.log(`\x1b[1msdlab reingest generated\x1b[0m — ${projectName}`);
+    console.log(`  Source:   ${sourcePath}`);
+    console.log(`  Manifest: ${manifestId}`);
+    if (dryRun) console.log(`  Mode:     DRY RUN (no records written)`);
+    console.log('');
+
+    const result = await reingestGenerated(projectRoot, sourcePath, manifestId, { dryRun });
+
+    console.log(`  \x1b[32m✓\x1b[0m Created: ${result.created} records`);
+    if (result.skipped > 0) {
+      console.log(`  Skipped: ${result.skipped} (already exist)`);
+    }
+    if (result.created > 0) {
+      console.log('');
+      console.log('  Next steps:');
+      console.log('    1. Review: sdlab curate <id> approved/rejected "explanation"');
+      console.log('    2. Bind:   sdlab bind --project ' + projectName);
+      console.log('    3. Then eligible for future snapshots');
+    }
+
+  } else if (subcommand === 'audit') {
+    console.log(`\x1b[1msdlab reingest audit\x1b[0m — ${projectName}\n`);
+
+    const result = await auditReingest(projectRoot);
+
+    if (result.total === 0) {
+      console.log('  No re-ingested records found (gen_* prefix).');
+      return;
+    }
+
+    console.log(`  Re-ingested records: ${result.total}`);
+    console.log(`  Reviewed:            ${result.reviewed}`);
+    console.log(`  Unreviewed:          ${result.unreviewed}`);
+    console.log(`  Canon-bound:         ${result.bound}`);
+    console.log(`  Unbound:             ${result.unbound}`);
+
+    if (result.unreviewed > 0) {
+      console.log(`\n  \x1b[33m⚠\x1b[0m ${result.unreviewed} records awaiting review`);
+    }
+    if (result.unbound > 0) {
+      console.log(`  \x1b[33m⚠\x1b[0m ${result.unbound} reviewed records not yet canon-bound`);
+    }
+    if (result.unreviewed === 0 && result.unbound === 0) {
+      console.log(`\n  \x1b[32m✓\x1b[0m All re-ingested records are reviewed and canon-bound`);
+    }
+
+  } else {
+    throw new Error(`Unknown subcommand: ${subcommand}. Use: generated, 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); });
+}

package/scripts/snapshot.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+
+/**
+ * snapshot.js — Create, list, show, and diff dataset snapshots.
+ *
+ * Usage:
+ *   sdlab snapshot create [--profile <name>] [--project <name>]
+ *   sdlab snapshot list [--project <name>]
+ *   sdlab snapshot show <snapshot-id> [--project <name>]
+ *   sdlab snapshot diff <id-a> <id-b> [--project <name>]
+ */
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { getProjectName } from '../lib/args.js';
+import { REPO_ROOT } from '../lib/paths.js';
+import { loadSelectionProfile } from '../lib/config.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';
+
+  // Strip subcommand from argv for flag parsing
+  const args = argv.filter(a => a !== subcommand);
+
+  if (subcommand === 'create') {
+    const profileIdx = args.indexOf('--profile');
+    const profileId = profileIdx >= 0 ? args[profileIdx + 1] : null;
+    const profile = loadSelectionProfile(projectRoot, profileId);
+
+    console.log(`\x1b[1msdlab snapshot create\x1b[0m — ${projectName}`);
+    console.log(`  Profile: ${profileId || 'training-default (built-in)'}`);
+    console.log('');
+
+    const result = await createSnapshot(projectRoot, profile);
+
+    console.log(`  \x1b[32m✓\x1b[0m Snapshot: ${result.snapshotId}`);
+    console.log(`  Included: ${result.included}`);
+    console.log(`  Excluded: ${result.excluded}`);
+
+    // Read and display summary
+    const summary = JSON.parse(
+      await readFile(join(projectRoot, 'snapshots', result.snapshotId, 'summary.json'), 'utf-8')
+    );
+    console.log('\n  Lane distribution:');
+    for (const [lane, count] of Object.entries(summary.lane_distribution).sort((a, b) => b[1] - a[1])) {
+      console.log(`    ${lane}: ${count}`);
+    }
+    console.log('\n  Faction distribution:');
+    for (const [f, c] of Object.entries(summary.faction_distribution).sort((a, b) => b[1] - a[1])) {
+      console.log(`    ${f}: ${c}`);
+    }
+
+    // Read and categorize exclusions
+    const excludedRaw = await readFile(
+      join(projectRoot, 'snapshots', result.snapshotId, 'excluded.jsonl'), 'utf-8'
+    );
+    const excluded = excludedRaw.trim().split('\n').filter(Boolean).map(l => JSON.parse(l));
+    const categories = categorizeExclusions(excluded);
+    console.log('\n  Exclusion reasons:');
+    for (const [cat, count] of Object.entries(categories)) {
+      if (count > 0) console.log(`    ${cat}: ${count}`);
+    }
+
+  } else if (subcommand === 'list') {
+    const snapshots = await listSnapshots(projectRoot);
+    if (snapshots.length === 0) {
+      console.log('No snapshots found. Run: sdlab snapshot create');
+      return;
+    }
+    console.log(`\x1b[1mSnapshots\x1b[0m — ${projectName}\n`);
+    for (const s of snapshots) {
+      console.log(`  ${s.id}  included=${s.included}  excluded=${s.excluded}  fp=${s.fingerprint}  ${s.created_at}`);
+    }
+
+  } else if (subcommand === 'show') {
+    const snapshotId = args.find(a => a.startsWith('snap-'));
+    if (!snapshotId) throw new Error('Usage: sdlab snapshot show <snapshot-id>');
+
+    const manifest = await loadSnapshot(projectRoot, snapshotId);
+    console.log(`\x1b[1mSnapshot\x1b[0m — ${snapshotId}\n`);
+    console.log(`  Created: ${manifest.created_at}`);
+    console.log(`  Project: ${manifest.project_name}`);
+    console.log(`  Frozen:  ${manifest.frozen}`);
+    console.log(`  Records: ${manifest.counts.total_records}`);
+    console.log(`  Included: ${manifest.counts.included}`);
+    console.log(`  Excluded: ${manifest.counts.excluded}`);
+    console.log(`  Config fingerprint: ${manifest.config_fingerprint}`);
+    console.log('');
+    console.log('  Selection profile:');
+    for (const [k, v] of Object.entries(manifest.selection_profile)) {
+      console.log(`    ${k}: ${JSON.stringify(v)}`);
+    }
+
+  } 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 diff = await diffSnapshots(projectRoot, snapIds[0], snapIds[1]);
+    console.log(`\x1b[1mSnapshot diff\x1b[0m — ${snapIds[0]} vs ${snapIds[1]}\n`);
+    console.log(`  ${snapIds[0]}: ${diff.countA} records`);
+    console.log(`  ${snapIds[1]}: ${diff.countB} records`);
+    console.log(`  Shared: ${diff.shared.length}`);
+    console.log(`  Added in ${snapIds[1]}: ${diff.added.length}`);
+    console.log(`  Removed from ${snapIds[0]}: ${diff.removed.length}`);
+
+    if (diff.added.length > 0 && diff.added.length <= 20) {
+      console.log('\n  Added:');
+      for (const id of diff.added) console.log(`    + ${id}`);
+    }
+    if (diff.removed.length > 0 && diff.removed.length <= 20) {
+      console.log('\n  Removed:');
+      for (const id of diff.removed) console.log(`    - ${id}`);
+    }
+
+  } else {
+    throw new Error(`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);
+  });
+}