@mcptoolshop/style-dataset-lab 3.0.1 → 3.2.0

package/lib/training-adapters.js

@@ -0,0 +1,84 @@
+/**
+ * Training adapter registry.
+ *
+ * Single source of truth for training-package adapters. Each adapter
+ * lives in `lib/adapters/<id>.js` and exports `buildPackage(opts)`.
+ *
+ * To add a new adapter (e.g. `kohya-lora`, `onedtrainer`):
+ *   1. Add `lib/adapters/<id>.js` exporting `buildPackage`.
+ *   2. Add an entry to ADAPTER_REGISTRY below with a one-line description.
+ *
+ * Why explicit registration: the available adapter list shows up in error
+ * messages, training-profile validation, and (eventually) CLI completion.
+ * A static map keeps those views consistent and makes new adapters a
+ * one-line surface change rather than a directory-listing side effect.
+ */
+
+import { inputError } from './errors.js';
+
+export const ADAPTER_REGISTRY = Object.freeze({
+  'generic-image-caption': {
+    id: 'generic-image-caption',
+    description: 'Image folders + caption JSONL — broadest trainer compatibility',
+    module: './adapters/generic-image-caption.js',
+  },
+  'diffusers-lora': {
+    id: 'diffusers-lora',
+    description: 'Diffusers fine-tuning layout: image + caption .txt sidecars + per-partition JSONL',
+    module: './adapters/diffusers-lora.js',
+  },
+  'ai-toolkit': {
+    id: 'ai-toolkit',
+    description: 'Ostris ai-toolkit Flux training package: image + .txt sidecars + ai-toolkit-config.yaml at root',
+    module: './adapters/ai-toolkit.js',
+  },
+});
+
+/**
+ * Names of all registered adapters.
+ * @returns {string[]}
+ */
+export function listAdapters() {
+  return Object.keys(ADAPTER_REGISTRY);
+}
+
+/**
+ * Whether `id` names a registered adapter.
+ * @param {string} id
+ * @returns {boolean}
+ */
+export function isRegisteredAdapter(id) {
+  return Object.prototype.hasOwnProperty.call(ADAPTER_REGISTRY, id);
+}
+
+/**
+ * Resolve and dynamically import an adapter module.
+ *
+ * Throws `ADAPTER_NOT_REGISTERED` (input error, exit 1) for unknown ids
+ * — distinct from `MODULE_LOAD_FAILED` (runtime, exit 2) for the rare
+ * case where the file vanished after registration.
+ *
+ * @param {string} id
+ * @returns {Promise<{ buildPackage: Function }>}
+ */
+export async function loadAdapter(id) {
+  if (!isRegisteredAdapter(id)) {
+    throw inputError(
+      'ADAPTER_NOT_REGISTERED',
+      `Adapter "${id}" is not registered. Available: ${listAdapters().join(', ')}`,
+      'Pick one of the registered adapters or add a new one to lib/training-adapters.js.'
+    );
+  }
+  const entry = ADAPTER_REGISTRY[id];
+  try {
+    return await import(entry.module);
+  } catch (err) {
+    // The registry says it should exist but import failed — surface the
+    // underlying error so it doesn't get masked as a typo.
+    throw inputError(
+      'ADAPTER_MODULE_LOAD_FAILED',
+      `Adapter "${id}" is registered but its module failed to load: ${err.message}`,
+      `Check that ${entry.module} exists and exports buildPackage().`
+    );
+  }
+}

package/lib/training-packages.js

@@ -17,6 +17,8 @@ import { loadRecord } from './records.js';
 import { loadProjectConfig, detectLane, detectGroup } from './config.js';
 import { inputError } from './errors.js';
 import { SCHEMA_VERSION, checkManifestVersion } from './snapshot.js';
+import { loadAdapter } from './training-adapters.js';
+import { recordToRow, filterRowsForProfile } from './rows.js';
 
 /**
  * Generate a training package ID: tp-YYYYMMDD-HHMMSS-XXXX
@@ -33,20 +35,6 @@ async function sha256File(filePath) {
   return createHash('sha256').update(data).digest('hex');
 }
 
-/**
- * Load an adapter module by name.
- */
-async function loadAdapter(adapterTarget) {
-  const adapterPath = `./adapters/${adapterTarget}.js`;
-  try {
-    return await import(adapterPath);
-  } catch {
-    throw new Error(
-      `Adapter "${adapterTarget}" not found. Available: generic-image-caption, diffusers-lora`
-    );
-  }
-}
-
 /**
  * Build a training package from a manifest.
  *
@@ -74,38 +62,43 @@ export async function buildTrainingPackage(projectRoot, manifestId, options = {}
     );
   }
 
-  // Load split partitions
-  const partitions = {};
-  let totalRecords = 0;
-  let totalImages = 0;
+  // Convert split partitions → canonical rows (D6 adapter input shape).
+  // Adapters only understand rows — records-flow callers go through this
+  // converter, canon-build-flow callers produce rows directly. One input
+  // contract, two producers.
+  const rows = [];
+  const partitionCounts = { train: 0, val: 0, test: 0 };
 
   for (const partition of ['train', 'val', 'test']) {
     const entries = await loadSplitPartition(projectRoot, manifest.source_split_id, partition);
-    const records = [];
 
     for (const entry of entries) {
       const record = await loadRecord(recordsDir, entry.record_id);
       if (!record) continue;
 
-      // Filter by profile's eligible lanes
       const prompt = record.provenance?.prompt || '';
       const lane = detectLane(record.id, prompt, config.lanes);
-      if (profile.eligible_lanes.length > 0 && !profile.eligible_lanes.includes(lane)) {
-        continue;
-      }
-
       const group = detectGroup(record.id, prompt, config.terminology);
-      records.push({ record, lane, group });
+
+      const row = recordToRow(record, lane, group, profile, partition);
+      if (row) rows.push(row);
     }
+  }
 
-    partitions[partition] = records;
-    totalRecords += records.length;
+  // Apply profile filters (eligible_lanes + entity_id_scope — D8).
+  // filterRowsForProfile returns rows where lane ∈ eligible_lanes AND
+  // entity_id === entity_id_scope (when set). Zero filters = identity.
+  const filteredRows = filterRowsForProfile(rows, profile);
+  for (const row of filteredRows) {
+    if (partitionCounts[row.partition] !== undefined) partitionCounts[row.partition]++;
   }
+  const totalRecords = filteredRows.length;
+  let totalImages = 0;
 
-  // Let the adapter build the package layout
+  // Let the adapter build the package layout from the canonical rows.
   const adapterResult = await adapter.buildPackage({
     packageDir,
-    partitions,
+    rows: filteredRows,
     profile,
     manifest,
     config,
@@ -131,9 +124,9 @@ export async function buildTrainingPackage(projectRoot, manifestId, options = {}
     config_fingerprint: manifest.config_fingerprint,
     counts: {
       total_records: totalRecords,
-      train: partitions.train.length,
-      val: partitions.val.length,
-      test: partitions.test.length,
+      train: partitionCounts.train,
+      val: partitionCounts.val,
+      test: partitionCounts.test,
       images: totalImages,
       checksums: 0, // updated after checksum pass below
     },

package/lib/training-profiles.js

@@ -9,9 +9,17 @@
 import { readFile, readdir, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
+import { isRegisteredAdapter, listAdapters } from './training-adapters.js';
 
 const REQUIRED_FIELDS = ['profile_id', 'label', 'target_family', 'asset_type', 'eligible_lanes', 'adapter_targets'];
 
+// trigger_override constraints (research ref: two-LoRA stack D3, 2026-04-24).
+// T5 tokenizes on SentencePiece Unigram with `_` as the space sentinel; hyphens
+// fragment unpredictably and uppercase is not canonicalized. Generic suffixes
+// alone collide across projects — a game-slug prefix is the documented defense.
+const TRIGGER_OVERRIDE_RE = /^[a-z0-9_]+$/;
+const TRIGGER_GENERIC_SUFFIX_DENYLIST = ['style', 'character', 'anime', 'realistic'];
+
 /**
  * Validate a training profile object.
  * @returns {{ valid: boolean, errors: string[] }}
@@ -32,6 +40,41 @@ export function validateProfile(profile) {
   if (profile.adapter_targets?.length === 0) {
     errors.push('adapter_targets must have at least one target');
   }
+  // Reject unregistered adapter targets early — surfaces typos at profile
+  // load time instead of at package-build time.
+  if (Array.isArray(profile.adapter_targets)) {
+    for (const target of profile.adapter_targets) {
+      if (!isRegisteredAdapter(target)) {
+        errors.push(`adapter_targets contains unregistered adapter "${target}". Available: ${listAdapters().join(', ')}`);
+      }
+    }
+  }
+  // trigger_override is optional. When present, enforce SentencePiece-safe
+  // format and reject bare generic suffixes that collide across projects.
+  if (profile.trigger_override !== undefined && profile.trigger_override !== null) {
+    if (typeof profile.trigger_override !== 'string') {
+      errors.push('trigger_override must be a string');
+    } else if (profile.trigger_override.length === 0) {
+      errors.push('trigger_override must be a non-empty string (or omit the field)');
+    } else if (!TRIGGER_OVERRIDE_RE.test(profile.trigger_override)) {
+      errors.push(`trigger_override "${profile.trigger_override}" must match ^[a-z0-9_]+$ (lowercase, digits, underscores — no hyphens, no uppercase)`);
+    } else if (TRIGGER_GENERIC_SUFFIX_DENYLIST.includes(profile.trigger_override)) {
+      errors.push(`trigger_override "${profile.trigger_override}" is a generic suffix; prefix with a game slug (e.g. "sf_${profile.trigger_override}")`);
+    }
+  }
+  // entity_id_scope is optional (post-research D8). Same SentencePiece-safe
+  // format as trigger_override — no hyphens, no uppercase, lowercase slug.
+  // Used by per-character LoRA profiles to row-filter canonical dataset.jsonl
+  // to a single subject at packaging time.
+  if (profile.entity_id_scope !== undefined && profile.entity_id_scope !== null) {
+    if (typeof profile.entity_id_scope !== 'string') {
+      errors.push('entity_id_scope must be a string');
+    } else if (profile.entity_id_scope.length === 0) {
+      errors.push('entity_id_scope must be a non-empty string (or omit the field)');
+    } else if (!TRIGGER_OVERRIDE_RE.test(profile.entity_id_scope)) {
+      errors.push(`entity_id_scope "${profile.entity_id_scope}" must match ^[a-z0-9_]+$ (lowercase, digits, underscores — no hyphens, no uppercase)`);
+    }
+  }
   return { valid: errors.length === 0, errors };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcptoolshop/style-dataset-lab",
-  "version": "3.0.1",
+  "version": "3.2.0",
   "description": "Canon-aligned dataset production and generation workbench — define visual rules, build versioned training data, compile production briefs, run local workflows, batch-produce, select winners, and re-ingest into your corpus",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "scripts": {
     "test": "node --test tests/**/*.test.js",
+    "coverage": "c8 npm test",
     "verify": "node bin/sdlab.js --help && node bin/sdlab.js project doctor --project star-freight",
     "generate": "node scripts/generate.js",
     "curate": "node scripts/curate.js",
@@ -16,6 +17,26 @@
     "painterly": "node scripts/painterly.js",
     "generate:identity": "node scripts/generate-identity.js"
   },
+  "c8": {
+    "include": [
+      "lib/**/*.js"
+    ],
+    "exclude": [
+      "tests/**",
+      "scripts/**",
+      "site/**",
+      "projects/**",
+      "templates/**",
+      "**/*.test.js"
+    ],
+    "reporter": [
+      "text",
+      "lcov",
+      "text-summary"
+    ],
+    "report-dir": "coverage",
+    "all": true
+  },
   "files": [
     "bin/",
     "lib/",
@@ -58,5 +79,11 @@
     "node": ">=20"
   },
   "author": "mcp-tool-shop",
-  "license": "MIT"
+  "license": "MIT",
+  "devDependencies": {
+    "c8": "^10.1.3"
+  },
+  "dependencies": {
+    "yaml": "^2.8.3"
+  }
 }

package/scripts/_batch_cut.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""Batch alpha-cut cast turnaround views via ComfyUI's native BiRefNet (RGBA out).
+For each character, cuts its 8 restylized views -> out/<char>/<view>.png on transparency.
+Free Qwen (POST /free) before running so BiRefNet doesn't co-reside with the 28 GB transformer.
+
+    python _batch_cut.py --restylized <dir-of-per-char> --out <dir> --chars rustgrave,hearthframe,dustwhisper
+"""
+from __future__ import annotations
+import argparse, json, shutil, time, urllib.request, uuid
+from pathlib import Path
+
+COMFY = "http://127.0.0.1:8188"
+COMFY_OUT = Path(r"E:/AI-Models/ComfyUI_windows_portable/ComfyUI/output")
+COMFY_IN = Path(r"E:/AI-Models/ComfyUI_windows_portable/ComfyUI/input")
+MODEL = "birefnet.safetensors"
+
+
+def graph(image_filename: str, out_prefix: str) -> dict:
+    return {
+        "1": {"class_type": "LoadImage", "inputs": {"image": image_filename}},
+        "2": {"class_type": "LoadBackgroundRemovalModel", "inputs": {"bg_removal_name": MODEL}},
+        "3": {"class_type": "RemoveBackground", "inputs": {"image": ["1", 0], "bg_removal_model": ["2", 0]}},
+        "4": {"class_type": "InvertMask", "inputs": {"mask": ["3", 0]}},
+        "5": {"class_type": "JoinImageWithAlpha", "inputs": {"image": ["1", 0], "alpha": ["4", 0]}},
+        "6": {"class_type": "SaveImage", "inputs": {"filename_prefix": out_prefix, "images": ["5", 0]}},
+    }
+
+
+def post(path: str, payload: dict):
+    return json.loads(urllib.request.urlopen(urllib.request.Request(
+        f"{COMFY}{path}", json.dumps(payload).encode(), {"Content-Type": "application/json"}), timeout=120).read())
+
+
+def cut_one(src: Path, staged_name: str, dst: Path):
+    shutil.copyfile(src, COMFY_IN / f"{staged_name}.png")
+    g = graph(f"{staged_name}.png", f"cut_{staged_name}")
+    pid = post("/prompt", {"prompt": g, "client_id": uuid.uuid4().hex})["prompt_id"]
+    for _ in range(600):
+        hist = json.loads(urllib.request.urlopen(f"{COMFY}/history/{pid}", timeout=30).read())
+        if pid in hist and hist[pid].get("outputs"):
+            img = hist[pid]["outputs"]["6"]["images"][0]
+            srcp = COMFY_OUT / img["subfolder"] / img["filename"]
+            for _w in range(120):
+                if srcp.exists():
+                    dst.parent.mkdir(parents=True, exist_ok=True)
+                    shutil.copyfile(srcp, dst)
+                    return
+                time.sleep(0.5)
+        time.sleep(0.5)
+    raise RuntimeError(f"cut timed out: {src}")
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--restylized", required=True)
+    ap.add_argument("--out", required=True)
+    ap.add_argument("--chars", required=True)
+    args = ap.parse_args()
+    rdir = Path(args.restylized); odir = Path(args.out)
+    n = 0
+    for c in args.chars.split(","):
+        c = c.strip()
+        for v in sorted((rdir / c).glob("*.png")):
+            cut_one(v, f"{c}_{v.stem}", odir / c / f"{v.stem}.png")
+            n += 1
+            print(f"  cut {c}/{v.stem}", flush=True)
+    print(f"BATCH CUT DONE: {n} sprites -> {odir}", flush=True)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/_seam_cutout.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""Alpha-cut sprites via ComfyUI's native BiRefNet background removal, for the A1 seam-test.
+
+Replicates the shipped "Remove Background (BiRefNet)" subgraph:
+  LoadImage -> LoadBackgroundRemovalModel -> RemoveBackground -> InvertMask -> JoinImageWithAlpha -> SaveImage
+Outputs RGBA PNGs (figure on transparency) and copies them to the Godot seam-test sprites dir.
+
+Inputs must already be in ComfyUI/input. Run with ComfyUI's embedded python:
+    python _seam_cutout.py seam_front seam_pitch30 seam_pitch40
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import sys
+import time
+import urllib.request
+import uuid
+from pathlib import Path
+
+COMFY = "http://127.0.0.1:8188"
+COMFY_OUT = Path(r"E:/AI-Models/ComfyUI_windows_portable/ComfyUI/output")
+GODOT_SPRITES = Path(r"E:/AI/hesperia/game/seam_test/sprites")
+MODEL = "birefnet.safetensors"
+
+
+def graph(image_filename: str, out_prefix: str) -> dict:
+    return {
+        "1": {"class_type": "LoadImage", "inputs": {"image": image_filename}},
+        "2": {"class_type": "LoadBackgroundRemovalModel", "inputs": {"bg_removal_name": MODEL}},
+        "3": {"class_type": "RemoveBackground", "inputs": {"image": ["1", 0], "bg_removal_model": ["2", 0]}},
+        "4": {"class_type": "InvertMask", "inputs": {"mask": ["3", 0]}},
+        "5": {"class_type": "JoinImageWithAlpha", "inputs": {"image": ["1", 0], "alpha": ["4", 0]}},
+        "6": {"class_type": "SaveImage", "inputs": {"filename_prefix": out_prefix, "images": ["5", 0]}},
+    }
+
+
+def post(path: str, payload: dict):
+    return json.loads(urllib.request.urlopen(urllib.request.Request(
+        f"{COMFY}{path}", json.dumps(payload).encode(), {"Content-Type": "application/json"}), timeout=120).read())
+
+
+def run_one(name: str) -> Path:
+    g = graph(f"{name}.png", f"seamcut_{name}")
+    pid = post("/prompt", {"prompt": g, "client_id": uuid.uuid4().hex})["prompt_id"]
+    for _ in range(600):
+        hist = json.loads(urllib.request.urlopen(f"{COMFY}/history/{pid}", timeout=30).read())
+        if pid in hist and hist[pid].get("outputs"):
+            img = hist[pid]["outputs"]["6"]["images"][0]
+            src = COMFY_OUT / img["subfolder"] / img["filename"]
+            for _w in range(120):
+                if src.exists():
+                    GODOT_SPRITES.mkdir(parents=True, exist_ok=True)
+                    dst = GODOT_SPRITES / f"{name}.png"
+                    shutil.copyfile(src, dst)
+                    return dst
+                time.sleep(0.5)
+        time.sleep(0.5)
+    raise RuntimeError(f"cutout timed out for {name}")
+
+
+def main() -> None:
+    names = sys.argv[1:]
+    if not names:
+        print("usage: _seam_cutout.py <name> [<name> ...]  (names are ComfyUI/input stems, no .png)")
+        sys.exit(2)
+    for n in names:
+        dst = run_one(n)
+        print(f"  cut {n} -> {dst}", flush=True)
+    print(f"\nSEAMCUT DONE: {len(names)} sprite(s) -> {GODOT_SPRITES}")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/batch-generate.js

@@ -15,6 +15,7 @@ import { compileBatch } from '../lib/batch-compiler.js';
 import { getBatchMode } from '../lib/batch-modes.js';
 import {
   createBatchDir,
+  openBatchDirForResume,
   executeBatchRuns,
   saveBatchManifest,
 } from '../lib/batch-runs.js';
@@ -31,20 +32,23 @@ export async function run(argv = process.argv.slice(2)) {
       subject: { type: 'string' },
       theme: { type: 'string' },
       asset: { type: 'string' },
+      resume: { type: 'string' },
       'dry-run': { type: 'boolean' },
       json: { type: 'boolean' },
     },
     deprecated: { game: 'project' },
   });
 
-  if (!flags.mode) {
+  if (!flags.mode && !flags.resume) {
     console.log('Usage: sdlab batch generate --mode <id> [--subject <id>] [--theme <label>] [--project <name>]');
+    console.log('       sdlab batch generate --resume <batch_id> [--project <name>]');
     console.log('');
     console.log('Options:');
-    console.log('  --mode <id>        Batch mode (required)');
+    console.log('  --mode <id>        Batch mode (required unless --resume is given)');
     console.log('  --subject <id>     Subject for subject-driven modes');
     console.log('  --theme <label>    Theme label for environment modes');
     console.log('  --asset <id>       Training asset reference');
+    console.log('  --resume <id>      Resume an existing batch — re-runs only failed/missing slots');
     console.log('  --dry-run          Prepare batch without submitting to ComfyUI');
     console.log('  --json             Output manifest as JSON');
     return;
@@ -53,17 +57,47 @@ export async function run(argv = process.argv.slice(2)) {
   const projectName = flags.project || getProjectName(argv);
   const projectRoot = getProjectRoot(projectName);
   const dryRun = flags['dry-run'] || false;
+  const resumeId = flags.resume || null;
+
+  // Resume short-circuit: load prior manifest and reuse its mode_id + subject/theme
+  // so the user only needs to pass --resume <batch_id>.
+  let batchId;
+  let batchDir;
+  let priorResults = [];
+  let resumedMode = null;
+  let resumedSubject = null;
+  let resumedTheme = null;
+  let resumedAsset = null;
+  if (resumeId) {
+    const opened = openBatchDirForResume(projectRoot, resumeId);
+    batchId = opened.batchId;
+    batchDir = opened.batchDir;
+    priorResults = opened.priorResults;
+    resumedMode = opened.priorManifest.mode_id || null;
+    resumedSubject = opened.priorManifest.subject_id || null;
+    resumedTheme = opened.priorManifest.theme || null;
+    resumedAsset = opened.priorManifest.asset_ref || null;
+  }
+
+  const modeId = flags.mode || resumedMode;
+  const subjectId = flags.subject || resumedSubject;
+  const theme = flags.theme || resumedTheme;
+  const assetRef = flags.asset || resumedAsset;
 
   // Load mode for display
-  const mode = getBatchMode(projectRoot, flags.mode);
+  const mode = getBatchMode(projectRoot, modeId);
 
   console.log(`\x1b[1mstyle-dataset-lab\x1b[0m batch generate`);
   console.log(`  Project: ${projectName}`);
   console.log(`  Mode: ${mode.label} (${mode.mode_id})`);
   console.log(`  Type: ${mode.batch_type}`);
   console.log(`  Slots: ${mode.variant_plan.length}`);
-  if (flags.subject) console.log(`  Subject: ${flags.subject}`);
-  if (flags.theme) console.log(`  Theme: ${flags.theme}`);
+  if (subjectId) console.log(`  Subject: ${subjectId}`);
+  if (theme) console.log(`  Theme: ${theme}`);
+  if (resumeId) {
+    const completed = priorResults.filter(r => r && r.status === 'ok').length;
+    console.log(`  Resume: ${resumeId} (${completed}/${priorResults.length} slots already complete)`);
+  }
   if (dryRun) console.log('  ⚠ DRY RUN');
   console.log('');
 
@@ -71,14 +105,18 @@ export async function run(argv = process.argv.slice(2)) {
   const { baseBrief, slotBriefs } = await compileBatch({
     projectRoot,
     projectId: projectName,
-    modeId: flags.mode,
-    subjectId: flags.subject,
-    theme: flags.theme,
-    assetRef: flags.asset,
+    modeId,
+    subjectId,
+    theme,
+    assetRef,
   });
 
-  // 2. Create batch directory
-  const { batchId, batchDir } = await createBatchDir(projectRoot);
+  // 2. Create or reuse batch directory
+  if (!resumeId) {
+    const created = await createBatchDir(projectRoot);
+    batchId = created.batchId;
+    batchDir = created.batchDir;
+  }
   info('batch-generate', `Batch: ${batchId}`);
 
   // 3. Execute runs
@@ -90,6 +128,7 @@ export async function run(argv = process.argv.slice(2)) {
     mode,
     slotBriefs,
     dryRun,
+    priorResults,
   });
   const batchElapsedMs = Date.now() - batchStartMs;
   if (!dryRun && results.length > 0) {
@@ -111,7 +150,9 @@ export async function run(argv = process.argv.slice(2)) {
       label: r.label,
       brief_id: r.brief_id,
       run_id: r.run_id,
+      status: r.status,
       selected_output: r.selected_output,
+      ...(r.error ? { error: r.error } : {}),
     })),
     sheet_paths: [],
     summary: {
@@ -121,8 +162,10 @@ export async function run(argv = process.argv.slice(2)) {
     },
   };
 
-  if (flags.subject) manifest.subject_id = flags.subject;
-  if (flags.theme) manifest.theme = flags.theme;
+  if (subjectId) manifest.subject_id = subjectId;
+  if (theme) manifest.theme = theme;
+  if (assetRef) manifest.asset_ref = assetRef;
+  if (resumeId) manifest.resumed_from = resumeId;
 
   // 5. Render sheet
   const sheetHtml = renderSheetHTML({ manifest, mode, projectRoot, batchDir });

package/scripts/canon-build.js

@@ -0,0 +1,88 @@
+/**
+ * `sdlab canon build` — CLI entry point for the three-projection build.
+ *
+ * Delegates orchestration to lib/canon-build/build.js. Parses flags, prints
+ * a summary, exits with codes per the errors.js inputError/runtimeError
+ * model (1 = user error, 2 = runtime error).
+ */
+
+import { parseArgs } from 'node:util';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { runBuild } from '../lib/canon-build/build.js';
+import { inputError } from '../lib/errors.js';
+
+export async function run(argv) {
+  const parsed = parseArgs({
+    args: argv,
+    options: {
+      project:  { type: 'string' },
+      game:     { type: 'string' },           // deprecated alias
+      full:     { type: 'boolean', default: false },
+      'no-cache': { type: 'boolean', default: false },
+      'dry-run':  { type: 'boolean', default: false },
+      only:     { type: 'string' },
+      json:     { type: 'boolean', default: false },
+      quiet:    { type: 'boolean', default: false },
+    },
+    allowPositionals: true,
+    strict: false,
+  });
+
+  const projectName = parsed.values.project || parsed.values.game;
+  if (!projectName) {
+    throw inputError(
+      'INPUT_MISSING_FLAG',
+      'sdlab canon build requires --project <name>',
+      'Example: sdlab canon build --project greek-rpg',
+    );
+  }
+
+  const projectRoot = join(process.cwd(), 'projects', projectName);
+  if (!existsSync(projectRoot)) {
+    throw inputError(
+      'INPUT_PROJECT_NOT_FOUND',
+      `Project directory not found: ${projectRoot}`,
+      `Run from the style-dataset-lab repo root, or scaffold the project with "sdlab init ${projectName}".`,
+    );
+  }
+
+  const only = parsed.values.only
+    ? parsed.values.only.split(',').map((s) => s.trim()).filter(Boolean)
+    : null;
+
+  const result = await runBuild({
+    projectRoot,
+    full: parsed.values.full,
+    noCache: parsed.values['no-cache'],
+    dryRun: parsed.values['dry-run'],
+    only,
+  });
+
+  if (parsed.values.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  if (!parsed.values.quiet) {
+    if (result.dryRun) {
+      console.log(`[dry-run] canon build would process ${result.entities_total} entities (${result.entities_cached} cached, ${result.entities_rebuilt} would rebuild) → ${result.rows} dataset rows.`);
+      console.log(`[dry-run] output would land at: ${result.output_dir}`);
+    } else {
+      console.log(`canon build complete: ${result.entities_total} entities (${result.entities_cached} cached, ${result.entities_rebuilt} rebuilt), ${result.rows} dataset rows.`);
+      console.log(`output: ${result.output_dir}`);
+      console.log(`generated_from: ${result.generated_from}`);
+      if (result.frozen_entries > 0) {
+        console.log(`frozen entries: ${result.frozen_entries} stamped with witness hashes`);
+      }
+      if (Array.isArray(result.drift) && result.drift.length > 0) {
+        console.log('');
+        console.log(`drift detected on ${result.drift.length} frozen entr${result.drift.length === 1 ? 'y' : 'ies'} since the previous build:`);
+        for (const d of result.drift) {
+          console.log(`  ${d.schema_kind}:${d.entity_id} (${d.status})`);
+        }
+        console.log('Run `sdlab canon drift` for the full report.');
+      }
+    }
+  }
+}