@mcptoolshop/style-dataset-lab 2.0.0 → 2.1.0

package/scripts/canon-bind.js

@@ -20,93 +20,7 @@ import { readFileSync, writeFileSync, readdirSync, existsSync } from 'fs';
 import { join } from 'path';
 import { getProjectName } from '../lib/args.js';
 import { REPO_ROOT } from '../lib/paths.js';
-import { loadConstitution, loadLanes, loadRubric, loadTerminology } from '../lib/config.js';
-
-// ─── Config-Driven Detection ────────────────────────────────────────
-
-/**
- * Detect lane from asset ID using project lane config.
- * Tests each lane's id_patterns as regex against the lowercase ID.
- * Returns the first match, or the default_lane.
- */
-function detectLane(id, prompt, lanesConfig) {
-  const lower = id.toLowerCase();
-  for (const lane of lanesConfig.lanes) {
-    if (!lane.id_patterns || lane.id_patterns.length === 0) continue;
-    for (const pattern of lane.id_patterns) {
-      if (new RegExp(pattern).test(lower)) return lane.id;
-    }
-  }
-  return lanesConfig.default_lane;
-}
-
-/**
- * Detect group (faction) from asset ID and prompt using terminology config.
- * Mirrors the exact detection order from the original hardcoded detectFaction():
- *   1. Primary ID patterns per group
- *   2. Cross-group patterns (e.g. ^cf_ → detect from ID suffix)
- *   3. Edge defaults (e.g. ^edge_ → compact)
- *   4. Prompt-based fallback patterns
- *   5. Null-faction patterns (generic rejects with no faction)
- *   6. ID fallback patterns (specific reject/borderline IDs)
- */
-function detectGroup(id, prompt, termConfig) {
-  // Explicit ordering for ID-based and prompt-based detection phases.
-  // These can differ — e.g. ID checks reach before keth, but prompt
-  // checks veshan before keth before orryn before reach.
-  const idOrder = termConfig.id_detection_order || Object.keys(termConfig.groups);
-  const promptOrder = termConfig.prompt_detection_order || Object.keys(termConfig.groups);
-
-  // 1. Primary ID patterns per group (id_detection_order)
-  for (const groupName of idOrder) {
-    const group = termConfig.groups[groupName];
-    if (!group?.id_patterns) continue;
-    for (const pattern of group.id_patterns) {
-      if (new RegExp(pattern).test(id)) return groupName;
-    }
-  }
-
-  // 2. Cross-group patterns
-  for (const [pattern, behavior] of Object.entries(termConfig.cross_group_patterns || {})) {
-    if (new RegExp(pattern).test(id)) {
-      if (behavior === 'detect_from_id_suffix') {
-        for (const groupName of idOrder) {
-          if (id.includes(groupName)) return groupName;
-        }
-      }
-      return null;
-    }
-  }
-
-  // 3. Edge defaults
-  for (const [pattern, groupName] of Object.entries(termConfig.edge_defaults || {})) {
-    if (new RegExp(pattern).test(id)) return groupName;
-  }
-
-  // 4. Prompt-based fallback (prompt_detection_order)
-  if (prompt) {
-    const p = prompt.toLowerCase();
-    for (const groupName of promptOrder) {
-      const group = termConfig.groups[groupName];
-      if (!group?.prompt_patterns || group.prompt_patterns.length === 0) continue;
-      for (const keyword of group.prompt_patterns) {
-        if (new RegExp(keyword).test(p)) return groupName;
-      }
-    }
-  }
-
-  // 5. Null-faction patterns (generic rejects — no faction)
-  for (const pattern of termConfig.null_faction_patterns || []) {
-    if (new RegExp(pattern).test(id)) return null;
-  }
-
-  // 6. ID fallback patterns
-  for (const [pattern, groupName] of Object.entries(termConfig.id_fallbacks || {})) {
-    if (new RegExp(pattern).test(id)) return groupName;
-  }
-
-  return null;
-}
+import { loadConstitution, loadLanes, loadRubric, loadTerminology, detectLane, detectGroup } from '../lib/config.js';
 
 /**
  * Build rationale string from rule's template, interpolating variables.

package/scripts/card.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+/**
+ * card.js — Generate dataset cards.
+ *
+ * Usage:
+ *   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 { REPO_ROOT } from '../lib/paths.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 projectRoot = join(REPO_ROOT, 'projects', projectName);
+  const subcommand = argv.find(a => !a.startsWith('--')) || 'generate';
+  const args = argv.filter(a => a !== subcommand);
+
+  if (subcommand === 'generate') {
+    // 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;
+    }
+
+    console.log(`\x1b[1msdlab card generate\x1b[0m — ${projectName}`);
+    console.log(`  Snapshot: ${snapshotId}`);
+    console.log(`  Split:    ${splitId}`);
+    console.log('');
+
+    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);
+    await writeFile(jsonPath, JSON.stringify(json, null, 2) + '\n');
+
+    console.log(`  \x1b[32m✓\x1b[0m dataset-card.md`);
+    console.log(`  \x1b[32m✓\x1b[0m dataset-card.json`);
+
+  } else {
+    throw new Error(`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);
+  });
+}

package/scripts/doctor.js

@@ -33,6 +33,9 @@ const REQUIRED_DIRS = [
   'outputs/approved',
   'outputs/rejected',
   'exports',
+  'snapshots',
+  'splits',
+  'eval-packs',
 ];
 
 function pass(msg) { console.log(`  \x1b[32m✓\x1b[0m ${msg}`); }

package/scripts/eligibility.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+/**
+ * eligibility.js — Audit training/eval eligibility for all project records.
+ *
+ * Usage:
+ *   sdlab eligibility audit [--project <name>]
+ */
+
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getProjectName } from '../lib/args.js';
+import { REPO_ROOT } from '../lib/paths.js';
+import { loadProjectConfig, loadSelectionProfile } from '../lib/config.js';
+import { evaluateEligibility, 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 profileIdx = argv.indexOf('--profile');
+  const profileId = profileIdx >= 0 ? argv[profileIdx + 1] : null;
+  const profile = loadSelectionProfile(projectRoot, profileId);
+  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(`  Records: ${files.length}`);
+  console.log('');
+
+  const eligible = [];
+  const excluded = [];
+  const nearMiss = []; // Records with exactly 1 failing reason
+
+  for (const file of files) {
+    const raw = await readFile(join(recordsDir, file), 'utf-8');
+    const record = JSON.parse(raw);
+
+    const result = evaluateEligibility(record, profile, config.lanes, config.terminology);
+
+    if (result.eligible) {
+      eligible.push(record.id);
+    } else {
+      excluded.push({ record_id: record.id, reasons: result.reasons });
+      if (result.reasons.length === 1) {
+        nearMiss.push({ record_id: record.id, reason: result.reasons[0] });
+      }
+    }
+  }
+
+  console.log(`  \x1b[32m✓\x1b[0m Eligible: ${eligible.length}`);
+  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)) {
+    if (count > 0) {
+      const bar = '█'.repeat(Math.min(Math.round(count / files.length * 50), 50));
+      console.log(`    ${cat.padEnd(20)} ${String(count).padStart(4)}  ${bar}`);
+    }
+  }
+
+  // Near-miss improvement opportunities
+  if (nearMiss.length > 0) {
+    console.log(`\n  Improvement opportunities (${nearMiss.length} records with 1 failing check):`);
+    const byReason = {};
+    for (const nm of nearMiss) {
+      byReason[nm.reason] = (byReason[nm.reason] || 0) + 1;
+    }
+    for (const [reason, count] of Object.entries(byReason).sort((a, b) => b[1] - a[1]).slice(0, 5)) {
+      console.log(`    ${count} records: ${reason}`);
+    }
+  }
+
+  console.log('');
+  const pct = ((eligible.length / files.length) * 100).toFixed(1);
+  console.log(`  Eligibility rate: ${pct}% (${eligible.length}/${files.length})`);
+}
+
+// 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);
+  });
+}

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/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/init.js

@@ -32,6 +32,9 @@ const PROJECT_DIRS = [
   'outputs/painterly',
   'outputs/painterly-test',
   'exports',
+  'snapshots',
+  'splits',
+  'eval-packs',
 ];
 
 function isValidName(name) {

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