@mcptoolshop/style-dataset-lab 1.2.1 → 2.1.0

package/CHANGELOG.md

@@ -2,6 +2,79 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.1.0] - 2026-04-16
+
+### Added
+
+- **Dataset spine** -- complete snapshot-to-export pipeline with proof at every stage
+  - `sdlab snapshot create/list/show/diff` -- frozen, deterministic record selections with config fingerprinting
+  - `sdlab eligibility audit` -- training eligibility evaluation with explicit reason traces
+  - `sdlab split build/list/show/audit` -- subject-isolated, lane-balanced train/val/test splitting
+  - `sdlab card generate` -- dataset card generation (markdown + JSON twin)
+  - `sdlab export build/list` -- self-contained export packages with manifest, metadata, images, splits, checksums
+  - `sdlab eval-pack build/list/show` -- canon-aware eval packs (4 task types)
+- **New library modules:**
+  - `lib/snapshot.js` -- snapshot creation, loading, diffing
+  - `lib/eligibility.js` -- eligibility evaluation with reason traces and exclusion categorization
+  - `lib/split.js` -- subject isolation (identity/lineage/suffix), mulberry32 PRNG, lane-balanced splitting, leakage audit
+  - `lib/card.js` -- dataset card rendering from snapshot + split + config
+  - `lib/export.js` -- export package builder with checksums and reproducibility manifest
+  - `lib/eval-pack.js` -- four eval task types (lane coverage, forbidden drift, anchor/gold, subject continuity)
+- **Selection, split, and export profiles** in `lib/config.js` with sensible defaults
+- **Detection functions** (`detectLane`, `detectGroup`) extracted from canon-bind into `lib/config.js` for reuse
+
+### Key properties
+
+- Snapshots are frozen -- once created, never silently changes
+- Inclusion is explainable -- every record has a reason trace
+- Splits preserve canon truth -- no subject family appears in multiple partitions
+- Exports are reproducible -- rebuildable from snapshot ref + split ref + config fingerprint
+
+## [2.0.0] - 2026-04-15
+
+### Breaking changes
+
+- **`games/` renamed to `projects/`** -- all project data now lives under `projects/<name>/`
+- **`--game` renamed to `--project`** -- `--game` still works with a deprecation warning (will be removed in v3.0)
+- **Canon-bind loads from config files** -- rules, lanes, rubric, and terminology are now per-project JSON, not hardcoded
+
+### Added
+
+- **`sdlab` CLI** -- unified command-line interface (`bin/sdlab.js`)
+  - `sdlab init <name> --domain <domain>` -- scaffold projects from domain templates
+  - `sdlab project doctor` -- validate project config and structure
+  - `sdlab bind`, `sdlab curate`, `sdlab generate`, etc. -- all pipeline commands
+- **Shared library** (`lib/`) -- 6 modules replacing duplicated code across 13 scripts
+  - `lib/args.js` -- unified argument parser with `--project` and deprecated `--game` support
+  - `lib/paths.js` -- centralized path resolution
+  - `lib/comfyui.js` -- ComfyUI HTTP client (extracted from 5 scripts)
+  - `lib/config.js` -- per-project JSON config loader
+  - `lib/records.js` -- record I/O utilities
+  - `lib/deprecation.js` -- one-shot deprecation warnings
+- **Per-project config files** -- 5 JSON files per project:
+  - `project.json` -- identity, domain, generation defaults
+  - `constitution.json` -- rules with rationale templates
+  - `lanes.json` -- subject lanes with regex detection patterns
+  - `rubric.json` -- scoring dimensions, thresholds, failure-to-rule mappings
+  - `terminology.json` -- group vocabulary with separate `id_detection_order` and `prompt_detection_order`
+- **5 domain starter templates** -- game-art, character-design, creature-design, architecture, vehicle-mech
+- **Training profile placeholders** in domain templates (eligible lanes, thresholds, export format)
+
+### Changed
+
+- Canon-bind is now fully config-driven -- loads rules, lanes, dimensions, thresholds, group vocabulary, and rationale templates from per-project JSON files
+- Missing config files cause hard failure with actionable error messages (no silent fallback)
+- All 10 CLI-exposed scripts refactored to export `run(argv)` for CLI dispatch
+- Net code reduction: ~305 lines removed from deduplication
+
+### Migration
+
+1. Rename `games/` to `projects/`
+2. Use `--project` instead of `--game` (or keep `--game` with deprecation warning)
+3. For canon-bind: add 5 JSON config files to your project (use `sdlab init` as reference)
+
+Star Freight config files are included as the canonical example.
+
 ## [1.2.0] - 2026-04-14
 
 - Added `templates/` with blank constitution, review rubric, and example prompt pack

package/README.md

@@ -1,7 +1,3 @@
-<p align="center">
-  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
-</p>
-
 <p align="center">
   <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/style-dataset-lab/readme.png" width="400">
 </p>
@@ -13,163 +9,192 @@
 
 # style-dataset-lab
 
-A production pipeline for visual dataset creation -- from canon rules to structured prompts to ComfyUI generation to curated, canon-bound training data.
+Turn approved visual work into versioned, review-backed datasets, splits, export packages, and eval packs.
 
 ## What this is
 
-A **pipeline** for building structured visual training datasets. You write style rules (canon), compose prompts, generate with ComfyUI, curate with per-dimension scoring, bind judgments to canon rules, and export in 10 formats via [`@mcptoolshop/repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset).
-
-The pipeline is game-agnostic. Each game gets its own data directory under `games/<name>/`; the 13 scripts and blank templates are shared. Every asset produced carries three things:
+A **visual canon and dataset production pipeline**. Define what your project looks like. Curate against constitution rules. Produce reproducible dataset packages with leakage-safe splits. Generate eval packs for future model verification.
 
-1. **Image pixels** -- generated by ComfyUI with full provenance (checkpoint, LoRA, seed, sampler, cfg)
-2. **Canon explanation** -- why this is on-style or off-style, grounded in a style constitution
-3. **Quality judgment** -- approved/rejected with per-dimension scores and cited rules
+The pipeline produces four artifacts:
 
-## Security model
-
-**Local-only.** style-dataset-lab talks to ComfyUI on `localhost:8188` and never makes external network requests. No telemetry, no analytics, no phoning home. Image generation happens entirely on your GPU. Records and canon data stay on your filesystem.
+| Artifact | What it is |
+|----------|-----------|
+| **Snapshot** | Frozen, fingerprinted selection of eligible records. Every inclusion has an explicit reason trace. |
+| **Split** | Leakage-safe train/val/test partition. Records sharing a subject family always land in the same split. |
+| **Export package** | Self-contained dataset: manifest, metadata, images, splits, dataset card, and checksums. |
+| **Eval pack** | Canon-aware verification tasks: lane coverage, forbidden drift, anchor/gold, subject continuity. |
 
-## What the npm package ships
+Every asset in the pipeline carries three things:
 
-`npm install @mcptoolshop/style-dataset-lab` gives you:
+1. **Provenance** -- full generation history (checkpoint, LoRA, seed, sampler, cfg, timing)
+2. **Canon binding** -- which constitution rules this asset passes, fails, or partially meets
+3. **Quality judgment** -- approved/rejected/borderline with per-dimension scores
 
-- **13 scripts** -- generate, curate, compare, canon-bind, painterly, identity generation, ControlNet/IP-Adapter generation, bulk curation, migration
-- **Blank templates** -- starter constitution, review rubric, and example prompt pack in `templates/`
+Works for game art, character design, creature design, architecture, vehicle/mech concepts, and any domain where visual production needs to stay on-model.
 
-The npm package does **not** include game data. Clone the repo if you want the Star Freight example (1,182 records, 28 prompt waves, 18 visual categories).
-
-## Install
+## Quick start
 
 ```bash
-# Get the pipeline scripts + templates
-npm install @mcptoolshop/style-dataset-lab
+# Install the CLI + pipeline
+npm install -g @mcptoolshop/style-dataset-lab
 
-# Or clone the repo for the Star Freight example data
-git clone https://github.com/mcp-tool-shop-org/style-dataset-lab
-cd style-dataset-lab
-npm install
+# Scaffold a new project
+sdlab init my-project --domain character-design
+
+# Validate the project structure
+sdlab project doctor --project my-project
 ```
 
-To start a new game from the templates:
+Available domains: `game-art`, `character-design`, `creature-design`, `architecture`, `vehicle-mech`, or `generic`.
+
+## CLI
 
 ```bash
-# Copy templates into your game directory
-mkdir -p games/my-game/{records,comparisons,inputs/prompts,outputs/{candidates,approved,rejected,borderline,painterly},exports}
-cp -r templates/canon games/my-game/canon
-cp templates/inputs/prompts/example-wave.json games/my-game/inputs/prompts/wave1.json
-# Edit the canon and prompts, then generate
+sdlab init <name> [--domain <domain>]     # Scaffold a new project
+sdlab project doctor [--project <name>]   # Validate project config
+
+sdlab generate <pack> [--project <name>]  # Generate candidates via ComfyUI
+sdlab generate:identity <packet>          # Named-subject identity images
+sdlab generate:controlnet                 # ControlNet-guided generation
+sdlab generate:ipadapter                  # IP-Adapter reference-guided
+
+sdlab curate <id> <status> <explanation>  # Record review judgment
+sdlab compare <a> <b> <winner> <reason>   # Pairwise A-vs-B comparison
+sdlab bind [--project <name>]             # Bind records to constitution rules
+sdlab painterly [--project <name>]        # Post-processing style pass
+
+sdlab snapshot create [--profile <name>]  # Create frozen dataset snapshot
+sdlab snapshot list                       # List all snapshots
+sdlab snapshot diff <a> <b>               # Compare two snapshots
+sdlab eligibility audit                   # Audit record training eligibility
+sdlab split build [--snapshot <id>]       # Build train/val/test split
+sdlab split audit <id>                    # Audit split for leakage + balance
+sdlab card generate                       # Generate dataset card (md + JSON)
+sdlab export build [--snapshot <id>]      # Build versioned export package
+sdlab eval-pack build                     # Build canon-aware eval pack
 ```
 
-## Monorepo structure
+All commands accept `--project <name>` (default: `star-freight`).
+
+## Project model
 
-The pipeline lives in `scripts/` and `templates/`. Each game lives in `games/<name>/` with its own canon, records, and assets. Scripts accept `--game <name>` (defaults to `star-freight`).
+Each project is a self-contained directory under `projects/` with its own canon, config, and data:
 
 ```
-style-dataset-lab/
-  scripts/                  13 pipeline scripts (generate, curate, compare, etc.)
-  templates/                Blank starting point for new games
-    canon/                  Starter constitution + review rubric
-    inputs/prompts/         Example prompt pack
-  games/
-    star-freight/           Star Freight example (1,182 records, repo-only)
-      canon/                Style constitution, review rubric, species canon
-      records/              Per-asset JSON (provenance + judgment + canon)
-      comparisons/          A-vs-B preference judgments
-      inputs/               Prompt packs, identity packets, references
-      outputs/              Generated images (gitignored)
-      exports/              repo-dataset output (gitignored)
-    <your-game>/            Add more games with the same structure
+projects/
+  my-project/
+    project.json            Project identity + generation defaults
+    constitution.json       Rules array with rationale templates
+    lanes.json              Subject lanes with detection patterns
+    rubric.json             Scoring dimensions + thresholds
+    terminology.json        Group vocabulary + detection order
+    canon/                  Style constitution (markdown)
+    records/                Per-asset JSON (provenance + judgment + canon)
+    inputs/prompts/         Prompt packs (JSON)
+    outputs/                Generated images (gitignored)
+    comparisons/            A-vs-B preference judgments
+    snapshots/              Frozen dataset snapshots
+    splits/                 Train/val/test partitions
+    exports/                Versioned export packages
+    eval-packs/             Canon-aware eval instruments
 ```
 
-## Pipeline workflow
+## Pipeline
 
-The full pipeline from canon to training export:
-
-```bash
-# 1. Write your canon -- style constitution + review rubric
-#    (start from templates/ or write from scratch)
+```
+canon → generate → curate → bind → snapshot → split → export → eval
+  |        |          |        |        |         |        |       |
+rules   ComfyUI   judgment  rules   frozen    subject  package  verify
+                                    selection isolation
+```
 
-# 2. Create prompt packs in inputs/prompts/
-#    (see templates/inputs/prompts/example-wave.json)
+1. **Define canon** -- write your style constitution and review rubric
+2. **Generate** -- ComfyUI produces candidates with full provenance
+3. **Curate** -- approve/reject with per-dimension scores and failure modes
+4. **Bind** -- link each asset to constitution rules with pass/fail/partial verdicts
+5. **Snapshot** -- freeze eligible records into a deterministic, fingerprinted selection
+6. **Split** -- partition into train/val/test with subject isolation and lane balance
+7. **Export** -- build a self-contained package with manifest, metadata, images, and checksums
+8. **Eval** -- generate canon-aware test instruments for model verification
 
-# 3. Start ComfyUI and generate candidates
-npm run generate -- --game star-freight inputs/prompts/wave1.json
-npm run generate -- --game star-freight inputs/prompts/wave1.json --dry-run
+Downstream format conversion (TRL, LLaVA, Parquet, etc.) is handled by [`repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset). `sdlab` owns dataset truth; `repo-dataset` renders it into specialized formats.
 
-# 4. Generate identity-packet characters (named subjects)
-npm run generate:identity -- --game star-freight inputs/identity-packets/wave27a.json
+## Domain templates
 
-# 5. Curate -- approve, reject, or mark borderline
-npm run curate -- --game star-freight <asset_id> approved "explanation"
-npm run curate -- --game star-freight <asset_id> rejected "explanation" --failures "too_clean"
+Each domain template ships with lane definitions, constitution rules, scoring rubrics, and terminology structures designed for that production context:
 
-# 6. Generate painterly variants of approved assets
-npm run painterly -- --game star-freight
+| Domain | Lanes | Key concerns |
+|--------|-------|-------------|
+| **game-art** | character, environment, prop, UI, ship, interior, equipment | Silhouette at gameplay scale, faction differentiation, wear/aging |
+| **character-design** | portrait, full_body, turnaround, expression_sheet, action_pose | Proportion accuracy, costume logic, personality read, gesture clarity |
+| **creature-design** | concept, orthographic, detail_study, action, scale_reference, habitat | Anatomical plausibility, evolutionary logic, silhouette distinction |
+| **architecture** | exterior, interior, streetscape, structural_detail, ruin, landscape | Structural plausibility, material consistency, perspective, era coherence |
+| **vehicle-mech** | exterior, cockpit, component, schematic, silhouette_sheet, damage_variant | Mechanical logic, functional design language, access points, damage narrative |
 
-# 7. Bind canon explanations to curated assets
-npm run canon-bind -- --game star-freight
+## Dataset production
 
-# 8. Record pairwise comparisons
-npm run compare -- --game star-freight <asset_a> <asset_b> a "A has better faction read"
+The full dataset spine: snapshot, split, export, eval.
 
-# 9. Export training data via repo-dataset
-repo-dataset visual generate ./games/star-freight --format trl
-repo-dataset visual inspect ./games/star-freight
 ```
+snapshot  -->  split  -->  export  -->  eval-pack
+   |            |            |             |
+  frozen     subject      package       canon-aware
+  selection  isolation    (manifest,    test instruments
+             + lane       metadata,     (4 task types)
+             balance      images,
+                          checksums,
+                          card)
+```
+
+**Snapshots** freeze a deterministic selection of eligible records. Every inclusion has a reason trace. Config fingerprints ensure reproducibility.
+
+**Splits** assign records to train/val/test partitions with subject isolation (no subject family appears in multiple splits) and lane-balanced distribution. Seeded PRNG ensures identical results from the same seed.
+
+**Export packages** are self-contained: manifest, metadata.jsonl, images (symlinked or copied), splits, dataset card (markdown + JSON), and BSD-format checksums. Everything needed to rebuild the dataset from scratch.
 
-## Adding a new game
+**Eval packs** are canon-aware test instruments with four task types: lane coverage, forbidden drift, anchor/gold, and subject continuity. They prove the dataset spine is feeding future model evaluation, not just dumping files.
+
+Export to downstream formats via [`repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) (TRL, LLaVA, Qwen2-VL, JSONL, Parquet, and more). `repo-dataset` handles format conversion; `sdlab` owns dataset truth.
+
+## Star Freight example
+
+Clone the repo for a complete working example: 1,182 records, 28 prompt waves, 5 factions, 7 lanes, 24 constitution rules, and 892 approved assets from a gritty sci-fi RPG.
 
 ```bash
-# Create structure and copy blank templates
-mkdir -p games/my-game/{records,comparisons,inputs/prompts,outputs/{candidates,approved,rejected,borderline,painterly},exports}
-cp -r templates/canon games/my-game/canon
-cp templates/inputs/prompts/example-wave.json games/my-game/inputs/prompts/wave1.json
+git clone https://github.com/mcp-tool-shop-org/style-dataset-lab
+cd style-dataset-lab
+
+# Validate the project
+sdlab project doctor --project star-freight
 
-# Edit your canon/constitution.md and canon/review-rubric.md
-# Edit your prompt pack, then run the pipeline with --game my-game
+# Run the full dataset spine
+sdlab snapshot create --project star-freight    # 839 eligible records
+sdlab split build --project star-freight        # ~80/10/10, zero leakage
+sdlab export build --project star-freight       # package with checksums
+sdlab eval-pack build --project star-freight    # 78 eval records
 ```
 
-## Per-game directory layout
+## Migrating from v1.x
 
-Each `games/<name>/` directory contains:
+v2.0 renames `games/` to `projects/` and `--game` to `--project`:
 
-```
-canon/                  Style constitution, review rubric, species canon, identity gates
-inputs/
-  prompts/              Prompt packs per wave (JSON: subjects, variations, defaults)
-  references/           IP-Adapter reference images
-  control-guides/       ControlNet guide overlays
-  identity-packets/     Named character identity spines
-outputs/
-  candidates/           Raw generations (gitignored)
-  approved/             Curated approved (gitignored)
-  rejected/             Curated rejected (gitignored)
-  borderline/           Curated borderline (gitignored)
-  painterly/            Painterly-style variants (gitignored)
-records/                Per-asset JSON (provenance + judgment + canon binding)
-comparisons/            A-vs-B preference judgments
-exports/                repo-dataset output (gitignored)
-```
+```bash
+# Rename your data directory
+mv games projects
 
-## Generation setup
-
-```yaml
-checkpoint: dreamshaperXL_v21TurboDPMSDE.safetensors
-lora: classipeintxl_v21.safetensors (weight: 1.0)
-resolution: 1024x1024
-steps: 8
-cfg: 2.0
-sampler: dpmpp_sde
-scheduler: karras
-speed: ~9s per image (RTX 5080)
+# --game still works with a deprecation warning (removed in v3.0)
+sdlab bind --game star-freight   # works, prints warning
+sdlab bind --project star-freight # canonical form
 ```
 
-Additional generation modes: ControlNet (pose/depth-guided), IP-Adapter (reference-driven), and identity packets (named character consistency).
+## Security model
+
+**Local-only.** Talks to ComfyUI on `localhost:8188`. No telemetry, no analytics, no external requests. Images stay on your GPU and filesystem.
 
 ## Requirements
 
 - [ComfyUI](https://github.com/comfyanonymous/ComfyUI) running on localhost:8188
-- DreamShaper XL Turbo checkpoint + ClassipeintXL LoRA
+- SDXL-compatible checkpoint + style LoRA
 - Node.js 20+
 - [`@mcptoolshop/repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) for training export
 

package/bin/sdlab.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+
+/**
+ * sdlab — CLI entry point for Style Dataset Lab.
+ *
+ * Thin dispatcher that routes subcommands to existing scripts.
+ * Each script exports run(argv) and is lazy-loaded on demand.
+ */
+
+const COMMANDS = {
+  'init':                '../scripts/init.js',
+  'generate':            '../scripts/generate.js',
+  'generate:identity':   '../scripts/generate-identity.js',
+  'generate:controlnet': '../scripts/generate-controlnet.js',
+  'generate:ipadapter':  '../scripts/generate-ipadapter.js',
+  'curate':              '../scripts/curate.js',
+  'compare':             '../scripts/compare.js',
+  'bind':                '../scripts/canon-bind.js',
+  'canon-bind':          '../scripts/canon-bind.js',
+  'painterly':           '../scripts/painterly.js',
+  'painterly:test':      '../scripts/painterly-test.js',
+  'migrate':             '../scripts/migrate-records.js',
+  'snapshot':            '../scripts/snapshot.js',
+  'eligibility':         '../scripts/eligibility.js',
+  'split':               '../scripts/split.js',
+  'card':                '../scripts/card.js',
+  'export':              '../scripts/export.js',
+  'eval-pack':           '../scripts/eval-pack.js',
+};
+
+// Two-word commands under "project" namespace
+const PROJECT_COMMANDS = {
+  'doctor':  '../scripts/doctor.js',
+  'migrate': '../scripts/migrate-records.js',
+};
+
+function printHelp() {
+  console.log(`\x1b[1msdlab\x1b[0m — Style Dataset Lab CLI\n`);
+  console.log('Usage: sdlab <command> [options]\n');
+  console.log('Project:');
+  console.log('  init <name>          Scaffold a new project from a domain template');
+  console.log('  project doctor       Validate project config and structure');
+  console.log('  project migrate      Migrate record schemas');
+  console.log('');
+  console.log('Pipeline:');
+  console.log('  generate             Generate candidates from a prompt pack');
+  console.log('  generate:identity    Generate named-subject identity images');
+  console.log('  generate:controlnet  ControlNet-guided structural generation');
+  console.log('  generate:ipadapter   IP-Adapter reference-guided generation');
+  console.log('  curate               Move candidate to approved/rejected/borderline');
+  console.log('  compare              Record pairwise A-vs-B comparison');
+  console.log('  bind                 Bind approved records to constitution rules');
+  console.log('  painterly            Post-processing painterly style pass');
+  console.log('  painterly:test       Test denoise levels on reference images');
+  console.log('');
+  console.log('Dataset:');
+  console.log('  snapshot create      Create a frozen dataset snapshot');
+  console.log('  snapshot list        List all snapshots');
+  console.log('  snapshot show <id>   Show snapshot details');
+  console.log('  snapshot diff <a> <b> Compare two snapshots');
+  console.log('  eligibility audit    Audit record training eligibility');
+  console.log('  split build          Build train/val/test split from snapshot');
+  console.log('  split list           List all splits');
+  console.log('  split show <id>      Show split details');
+  console.log('  split audit <id>     Audit split for leakage and balance');
+  console.log('  card generate        Generate dataset card (markdown + JSON)');
+  console.log('  export build         Build self-contained export package');
+  console.log('  export list          List all export packages');
+  console.log('  eval-pack build      Build canon-aware eval pack');
+  console.log('  eval-pack list       List eval packs');
+  console.log('  eval-pack show <id>  Show eval pack details');
+  console.log('');
+  console.log('Options:');
+  console.log('  --project <name>     Project to operate on (default: star-freight)');
+  console.log('  --game <name>        Deprecated alias for --project');
+  console.log('  --help               Show this help');
+  console.log('');
+  console.log('Examples:');
+  console.log('  sdlab init my-project --domain character-design');
+  console.log('  sdlab generate inputs/prompts/wave1.json --project star-freight');
+  console.log('  sdlab bind --stats --project star-freight');
+  console.log('  sdlab project doctor --project star-freight');
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    printHelp();
+    process.exit(0);
+  }
+
+  let command = args[0];
+  let commandArgs = args.slice(1);
+
+  // Handle "project <subcommand>" two-word form
+  if (command === 'project' && args[1] && PROJECT_COMMANDS[args[1]]) {
+    commandArgs = args.slice(2);
+    const modulePath = PROJECT_COMMANDS[args[1]];
+    try {
+      const mod = await import(modulePath);
+      await mod.run(commandArgs);
+    } catch (err) {
+      console.error(`\x1b[31mError:\x1b[0m ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  const modulePath = COMMANDS[command];
+  if (!modulePath) {
+    console.error(`Unknown command: ${command}`);
+    console.error(`Run "sdlab --help" for available commands.`);
+    process.exit(1);
+  }
+
+  try {
+    const mod = await import(modulePath);
+    await mod.run(commandArgs);
+  } catch (err) {
+    console.error(`\x1b[31mError:\x1b[0m ${err.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/lib/args.js

@@ -0,0 +1,106 @@
+/**
+ * Unified CLI argument parser.
+ *
+ * Supports:
+ *   --flag value       (space-separated)
+ *   --flag=value       (equals form)
+ *   --boolean-flag     (boolean)
+ *   positional args    (collected in order)
+ *   deprecated aliases (warns once, maps to canonical name)
+ */
+
+import { warnDeprecated } from './deprecation.js';
+
+/**
+ * @typedef {Object} ArgSpec
+ * @property {Object<string, {type: 'string'|'boolean', default?: any, alias?: string}>} flags
+ * @property {string[]} [positionals] - names for positional args (in order)
+ * @property {Object<string, string>} [deprecated] - old flag name → new flag name
+ */
+
+/**
+ * Parse CLI arguments.
+ * @param {string[]} argv — typically process.argv.slice(2)
+ * @param {ArgSpec} spec
+ * @returns {{ flags: Object, positionals: string[], rest: string[] }}
+ */
+export function parseArgs(argv, spec = {}) {
+  const flagDefs = spec.flags || {};
+  const deprecated = spec.deprecated || {};
+  const positionalNames = spec.positionals || [];
+
+  const flags = {};
+  const positionals = [];
+
+  // Set defaults
+  for (const [name, def] of Object.entries(flagDefs)) {
+    if (def.default !== undefined) flags[name] = def.default;
+    else if (def.type === 'boolean') flags[name] = false;
+    else flags[name] = undefined;
+  }
+
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+
+    if (arg.startsWith('--')) {
+      let key, value;
+
+      if (arg.includes('=')) {
+        const eqIdx = arg.indexOf('=');
+        key = arg.slice(2, eqIdx);
+        value = arg.slice(eqIdx + 1);
+      } else {
+        key = arg.slice(2);
+        value = undefined;
+      }
+
+      // Handle deprecated aliases
+      if (deprecated[key]) {
+        warnDeprecated(key, deprecated[key]);
+        key = deprecated[key];
+      }
+
+      // Handle short aliases defined in flagDefs
+      const canonical = Object.entries(flagDefs).find(([, def]) => def.alias === key);
+      if (canonical) key = canonical[0];
+
+      // Normalize kebab-case to camelCase for lookup
+      const camelKey = key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+      const def = flagDefs[key] || flagDefs[camelKey];
+
+      if (def?.type === 'boolean') {
+        flags[key in flagDefs ? key : camelKey] = true;
+      } else if (value !== undefined) {
+        flags[key in flagDefs ? key : camelKey] = value;
+      } else if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) {
+        flags[key in flagDefs ? key : camelKey] = argv[++i];
+      } else {
+        flags[key in flagDefs ? key : camelKey] = true;
+      }
+    } else {
+      positionals.push(arg);
+    }
+    i++;
+  }
+
+  // Map positionals to named keys
+  const named = {};
+  for (let j = 0; j < positionalNames.length && j < positionals.length; j++) {
+    named[positionalNames[j]] = positionals[j];
+  }
+
+  return { flags, positionals, named, rest: positionals.slice(positionalNames.length) };
+}
+
+/**
+ * Extract the --project (or deprecated --game) value from argv.
+ * Convenience for scripts that just need the project name.
+ */
+export function getProjectName(argv) {
+  const { flags } = parseArgs(argv, {
+    flags: { project: { type: 'string', default: 'star-freight' } },
+    deprecated: { game: 'project' },
+  });
+  return flags.project;
+}