@mcptoolshop/style-dataset-lab 3.3.0 → 3.5.0

package/scripts/migrate-records.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * migrate-records.js — One-time migration for curator-divergent records (Shape 2 + Shape 4)
+ *
+ * Normalizes verdict/scores/explanation/failures/curated_at/curator at top level
+ * into the standard judgment.{status,criteria_scores,explanation,failure_modes,reviewed_at,reviewer} shape.
+ *
+ * Also fixes asset_path from outputs/candidates/ to outputs/approved/ when the image exists in approved/.
+ *
+ * DOES NOT TOUCH Shape 3 (identity packet) records — those have judgment=null by design.
+ *
+ * Usage:
+ *   node scripts/migrate-records.js --dry-run    # Preview changes
+ *   node scripts/migrate-records.js              # Apply changes
+ *   sdlab project migrate --dry-run --project star-freight
+ */
+
+import { readdir, readFile, writeFile, access } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+import { getProjectName } from '../lib/args.js';
+import { getProjectRoot } from '../lib/paths.js';
+import { handleCliError } from '../lib/errors.js';
+
+async function fileExists(p) {
+  try { await access(p); return true; } catch { return false; }
+}
+
+function isCuratorDivergent(rec) {
+  return rec.judgment === null && typeof rec.verdict === 'string' && !rec.identity;
+}
+
+function isIdentityRecord(rec) {
+  return rec.identity != null;
+}
+
+async function migrateRecord(filePath, GAME_ROOT, DRY_RUN) {
+  const raw = await readFile(filePath, 'utf-8');
+  const rec = JSON.parse(raw);
+
+  if (isIdentityRecord(rec)) return { file: basename(filePath), action: 'skip-identity' };
+
+  if (!isCuratorDivergent(rec)) {
+    if (rec.asset_path && rec.asset_path.includes('outputs/candidates/')) {
+      const approvedPath = rec.asset_path.replace('outputs/candidates/', 'outputs/approved/');
+      const fullApproved = join(GAME_ROOT, approvedPath);
+      if (await fileExists(fullApproved)) {
+        rec.asset_path = approvedPath;
+        if (!DRY_RUN) await writeFile(filePath, JSON.stringify(rec, null, 2) + '\n');
+        return { file: basename(filePath), action: 'path-fix-only', from: 'candidates/', to: 'approved/' };
+      }
+    }
+    return { file: basename(filePath), action: 'skip-standard' };
+  }
+
+  const changes = [];
+
+  rec.judgment = {
+    status: rec.verdict || 'unknown',
+    reviewer: rec.curator || 'wave25-script',
+    reviewed_at: rec.curated_at || new Date().toISOString(),
+    explanation: rec.explanation || '',
+    criteria_scores: rec.scores || {},
+    failure_modes: rec.failures || [],
+    improvement_notes: null,
+    confidence: 0.8,
+  };
+  changes.push(`verdict="${rec.verdict}" → judgment.status`);
+
+  delete rec.verdict;
+  delete rec.scores;
+  delete rec.explanation;
+  delete rec.failures;
+  delete rec.curated_at;
+  delete rec.curator;
+  changes.push('removed top-level verdict/scores/explanation/failures/curated_at/curator');
+
+  if (rec.asset_path && rec.asset_path.includes('outputs/candidates/')) {
+    const approvedPath = rec.asset_path.replace('outputs/candidates/', 'outputs/approved/');
+    const fullApproved = join(GAME_ROOT, approvedPath);
+    if (await fileExists(fullApproved)) {
+      rec.asset_path = approvedPath;
+      changes.push(`asset_path: candidates/ → approved/`);
+    } else {
+      changes.push(`asset_path: candidates/ (image not in approved/, kept as-is)`);
+    }
+  }
+
+  if (!DRY_RUN) {
+    await writeFile(filePath, JSON.stringify(rec, null, 2) + '\n');
+  }
+
+  return { file: basename(filePath), action: 'migrated', changes };
+}
+
+export async function run(argv = process.argv.slice(2)) {
+  const projectName = getProjectName(argv);
+  const GAME_ROOT = getProjectRoot(projectName);
+  const RECORDS_DIR = join(GAME_ROOT, 'records');
+  const DRY_RUN = argv.includes('--dry-run');
+
+  console.log(DRY_RUN ? '=== DRY RUN ===' : '=== APPLYING MIGRATION ===');
+
+  const files = (await readdir(RECORDS_DIR)).filter(f => f.endsWith('.json'));
+  console.log(`Found ${files.length} record files\n`);
+
+  const results = { skipped: 0, migrated: 0, pathFixed: 0, identity: 0, errors: 0 };
+
+  for (const file of files) {
+    try {
+      const result = await migrateRecord(join(RECORDS_DIR, file), GAME_ROOT, DRY_RUN);
+      switch (result.action) {
+        case 'skip-standard': results.skipped++; break;
+        case 'skip-identity': results.identity++; break;
+        case 'migrated':
+          results.migrated++;
+          console.log(`MIGRATE: ${result.file}`);
+          result.changes.forEach(c => console.log(`  → ${c}`));
+          break;
+        case 'path-fix-only':
+          results.pathFixed++;
+          console.log(`PATH-FIX: ${result.file} (${result.from} → ${result.to})`);
+          break;
+      }
+    } catch (err) {
+      results.errors++;
+      console.error(`ERROR: ${file}: ${err.message}`);
+    }
+  }
+
+  console.log(`\n=== Summary ===`);
+  console.log(`Standard (unchanged): ${results.skipped}`);
+  console.log(`Identity (untouched): ${results.identity}`);
+  console.log(`Migrated (schema fix): ${results.migrated}`);
+  console.log(`Path-fixed only: ${results.pathFixed}`);
+  console.log(`Errors: ${results.errors}`);
+  console.log(`Total: ${files.length}`);
+}
+
+// Direct execution guard
+if (process.argv[1] && (process.argv[1].endsWith('migrate-records.js') || process.argv[1].endsWith('migrate-records'))) {
+  run().catch(handleCliError);
+}

package/scripts/painterly-test.js

@@ -12,8 +12,9 @@
 import { writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { getProjectName } from "../lib/args.js";
-import { REPO_ROOT } from "../lib/paths.js";
+import { getProjectRoot } from "../lib/paths.js";
 import { submitAndWait, downloadImage, uploadImage } from "../lib/comfyui.js";
+import { handleCliError } from "../lib/errors.js";
 
 const PAINTERLY_PROMPT = [
   "oil painting, visible brushstrokes, painterly concept art,",
@@ -72,7 +73,7 @@ function buildWorkflow(imagePath, denoise, loraWeight, seed) {
 
 export async function run(argv = process.argv.slice(2)) {
   const projectName = getProjectName(argv);
-  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
+  const GAME_ROOT = getProjectRoot(projectName);
   const COMFY_URL = process.env.COMFY_URL || "http://127.0.0.1:8188";
 
   const outDir = join(GAME_ROOT, "outputs/painterly-test");
@@ -118,5 +119,5 @@ export async function run(argv = process.argv.slice(2)) {
 
 // Direct execution guard
 if (process.argv[1] && (process.argv[1].endsWith('painterly-test.js') || process.argv[1].endsWith('painterly-test'))) {
-  run().catch(e => { console.error(e.message || e); process.exit(1); });
+  run().catch(handleCliError);
 }

package/scripts/painterly.js

@@ -19,7 +19,7 @@ import { writeFile, mkdir, readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { existsSync } from "node:fs";
 import { getProjectName, parseNumberFlag } from "../lib/args.js";
-import { REPO_ROOT, resolveSafeProjectPath } from "../lib/paths.js";
+import { getProjectRoot, resolveSafeProjectPath } from "../lib/paths.js";
 import { runtimeError, handleCliError } from "../lib/errors.js";
 import { comfyHealth, submitAndWait, downloadImage, uploadImage } from "../lib/comfyui.js";
 
@@ -145,7 +145,7 @@ function buildImg2ImgWorkflow(imagePath, seed) {
 
 export async function run(argv = process.argv.slice(2)) {
   const projectName = getProjectName(argv);
-  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
+  const GAME_ROOT = getProjectRoot(projectName);
   const COMFY_URL = process.env.COMFY_URL || "http://127.0.0.1:8188";
 
   const dryRun = argv.includes("--dry-run");
@@ -163,7 +163,11 @@ export async function run(argv = process.argv.slice(2)) {
 
   const fullSourceDir = resolveSafeProjectPath(GAME_ROOT, sourceDir, { flagName: 'source' });
   const outDir = join(GAME_ROOT, "outputs/painterly");
-  await mkdir(outDir, { recursive: true });
+  // SDL-M11: only create the output dir on a real run — a --dry-run preview
+  // must be side-effect-free (README.md promises "preview the effect first").
+  if (!dryRun) {
+    await mkdir(outDir, { recursive: true });
+  }
 
   // Collect source PNGs
   const allFiles = (await readdir(fullSourceDir))

package/scripts/qwen_generate.py

@@ -22,6 +22,7 @@ import os
 import time
 import urllib.request
 import uuid
+from decimal import Decimal
 from pathlib import Path
 
 from PIL import Image
@@ -58,20 +59,71 @@ _KIND_SUBDIRS = {
 
 
 def _js_number(n) -> str:
-    """Format a number the way JS String(n) does, so the graph hash matches the JS
-    helper: integer-valued floats drop the decimal (1.0 -> "1"), others use the
-    shortest round-trip repr (3.1 -> "3.1")."""
+    """Format a number exactly the way JS Number::toString (ECMA-262
+    6.1.6.1.20) does, so the graph hash matches the JS helper
+    (lib/run-manifest.js stableStringify).
+
+    SDL-H3: the previous implementation delegated non-integer floats to
+    Python's repr(), which disagrees with JS in the [1e-6, 1e-4) magnitude
+    band and on exponent zero-padding:
+        0.00005   -> Python repr "5e-05"   vs JS "0.00005"
+        0.000001  -> Python repr "1e-06"   vs JS "0.000001"
+        9.9e-7    -> Python repr "9.9e-07" vs JS "9.9e-7"
+    Any wave with a LoRA weight or float param in that band produced a
+    different comfy_workflow_sha than the JS path for an identical graph.
+
+    Fix: Python's repr()/str() already compute the same "shortest
+    round-trip decimal digit string" JS engines use internally (both use a
+    Grisu/Ryu-class shortest-repr algorithm) — the two runtimes only
+    disagree on how that digit string is laid out (decimal point position,
+    when to switch to exponential, exponent zero-padding). So: borrow
+    Python's digit string via repr(), hand it to Decimal (which parses
+    repr()'s scientific-notation form natively, no manual string
+    splitting), then re-render per the ECMA spec's own branches.
+    """
     if isinstance(n, bool):
         return "true" if n else "false"
     if isinstance(n, int):
         return str(n)
     if isinstance(n, float):
-        if not math.isfinite(n):
+        if math.isnan(n) or math.isinf(n):
             return "null"
-        return str(int(n)) if n.is_integer() else repr(n)
+        if n == 0:
+            return "0"  # covers -0.0 too — JS String(-0) is "0"
+        sign = "-" if n < 0 else ""
+        _, digits_tuple, exponent = Decimal(repr(abs(n))).as_tuple()
+        m = len(digits_tuple)
+        # value == 0.<all m digits> * 10**point_pos (this is ECMA's "n")
+        point_pos = exponent + m
+        digits = "".join(map(str, digits_tuple)).rstrip("0") or "0"
+        k = len(digits)
+        if k <= point_pos <= 21:
+            return sign + digits + ("0" * (point_pos - k))
+        if 0 < point_pos <= 21:
+            return sign + digits[:point_pos] + "." + digits[point_pos:]
+        if -6 < point_pos <= 0:
+            return sign + "0." + ("0" * -point_pos) + digits
+        mantissa = digits[0] if k == 1 else digits[0] + "." + digits[1:]
+        e = point_pos - 1
+        esign = "+" if e >= 0 else "-"
+        return f"{sign}{mantissa}e{esign}{abs(e)}"
     return "null"
 
 
+def _js_nullish(value, default):
+    """Mirror JS `value ?? default` — substitutes only when value is None
+    (JS null/undefined), never for other falsy values like 0 or False.
+
+    SDL-H4: dict.get(key, default) is NOT equivalent — it only substitutes
+    when the KEY is missing, never when the key is present with an
+    explicit null. {"weight": None}.get("weight", 1.0) returns None, not
+    1.0, silently splitting the graph hash from the JS side's
+    `l.weight ?? 1.0` AND submitting a literal null strength_model to
+    ComfyUI's /prompt.
+    """
+    return default if value is None else value
+
+
 def _stable_stringify(value) -> str:
     """Deterministic serialization mirroring lib/run-manifest.js stableStringify:
     object keys sorted, arrays in order, JS-style number/string formatting."""
@@ -204,7 +256,7 @@ def _build_pinning(graph, models, loras, seed_policy, do_hash, cache) -> dict:
     lora_hashes = []
     for lora in loras or []:
         entry = _hash_model_file(lora.get("name"), "lora", do_hash, cache)
-        entry["weight"] = lora.get("weight", 1.0)
+        entry["weight"] = _js_nullish(lora.get("weight"), 1.0)  # SDL-H4
         lora_hashes.append(entry)
     return {
         "pinning_version": PINNING_VERSION,
@@ -216,11 +268,22 @@ def _build_pinning(graph, models, loras, seed_policy, do_hash, cache) -> dict:
 
 
 def qwen_graph(pos: str, neg: str, seed: int, w: int, h: int, steps: int, cfg: float, prefix: str,
-               loras: list | None = None) -> dict:
+               loras: list | None = None, sampler: str = "euler", scheduler: str = "simple",
+               shift: float = 3.1) -> dict:
     """loras: [{name, weight}] chained as DiT-only LoraLoaderModelOnly nodes (ids from
     "40", between UNETLoader and ModelSamplingAuraFlow) — mirrors sdlab buildQwenGraph.
     Model-only because studio Qwen style LoRAs train the transformer with the text
-    encoder frozen."""
+    encoder frozen.
+
+    SDL-H11: sampler/scheduler/shift used to be hardcoded literals here (always
+    "euler"/"simple"/3.1, regardless of what the wave declared) and were not
+    even accepted as parameters — so a wave asking for dpmpp_2m/karras/shift 5.0
+    silently generated with euler/simple/3.1 instead, produced a different
+    comfy_workflow_sha than the JS `sdlab generate` path for the "same" graph,
+    AND had those wrong values stamped into the provenance receipt. Defaults
+    here match QWEN_DEFAULTS in lib/adapters/comfyui-workflows.js — used only
+    when a wave omits the fields (mirrors JS's `rp.sampler || defaults.sampler
+    || QWEN_DEFAULTS.sampler` fallback chain)."""
     nodes = {
         "37": {"class_type": "UNETLoader", "inputs": {"unet_name": QWEN_UNET, "weight_dtype": "default"}},
         "38": {"class_type": "CLIPLoader", "inputs": {"clip_name": QWEN_CLIP, "type": "qwen_image"}},
@@ -232,13 +295,13 @@ def qwen_graph(pos: str, neg: str, seed: int, w: int, h: int, steps: int, cfg: f
     for i, lora in enumerate(loras or []):
         lid = str(40 + i)
         nodes[lid] = {"class_type": "LoraLoaderModelOnly", "inputs": {
-            "lora_name": lora["name"], "strength_model": lora.get("weight", 1.0), "model": model_out}}
+            "lora_name": lora["name"], "strength_model": _js_nullish(lora.get("weight"), 1.0), "model": model_out}}  # SDL-H4
         model_out = [lid, 0]
     nodes.update({
-        "66": {"class_type": "ModelSamplingAuraFlow", "inputs": {"shift": 3.1, "model": model_out}},
+        "66": {"class_type": "ModelSamplingAuraFlow", "inputs": {"shift": shift, "model": model_out}},
         "5": {"class_type": "EmptySD3LatentImage", "inputs": {"width": w, "height": h, "batch_size": 1}},
-        "3": {"class_type": "KSampler", "inputs": {"seed": seed, "steps": steps, "cfg": cfg, "sampler_name": "euler",
-              "scheduler": "simple", "denoise": 1.0, "model": ["66", 0], "positive": ["6", 0], "negative": ["7", 0], "latent_image": ["5", 0]}},
+        "3": {"class_type": "KSampler", "inputs": {"seed": seed, "steps": steps, "cfg": cfg, "sampler_name": sampler,
+              "scheduler": scheduler, "denoise": 1.0, "model": ["66", 0], "positive": ["6", 0], "negative": ["7", 0], "latent_image": ["5", 0]}},
         "8": {"class_type": "VAEDecode", "inputs": {"samples": ["3", 0], "vae": ["39", 0]}},
         "9": {"class_type": "SaveImage", "inputs": {"filename_prefix": prefix, "images": ["8", 0]}},
     })
@@ -251,7 +314,9 @@ def _post(path: str, payload: dict):
 
 
 def generate(pos: str, neg: str, seed: int, dst: Path, **kw) -> Path:
-    g = qwen_graph(pos, neg, seed, kw["w"], kw["h"], kw["steps"], kw["cfg"], dst.stem, loras=kw.get("loras"))
+    g = qwen_graph(pos, neg, seed, kw["w"], kw["h"], kw["steps"], kw["cfg"], dst.stem, loras=kw.get("loras"),
+                   sampler=kw.get("sampler", "euler"), scheduler=kw.get("scheduler", "simple"),
+                   shift=kw.get("shift", 3.1))
     pid = _post("/prompt", {"prompt": g, "client_id": uuid.uuid4().hex})["prompt_id"]
     for _ in range(1200):
         hist = json.loads(urllib.request.urlopen(f"{COMFY}/history/{pid}", timeout=30).read())
@@ -284,10 +349,16 @@ def main() -> None:
     steps, cfg = d.get("steps", 22), d.get("cfg", 3.5)
     base_seed = d.get("base_seed", 1000)
     loras = d.get("loras", [])
+    # SDL-H11: read sampler/scheduler/shift from the wave instead of hardcoding
+    # them — defaults match QWEN_DEFAULTS in lib/adapters/comfyui-workflows.js
+    # so an omitted field falls back to the same value the JS path would use.
+    sampler = d.get("sampler", "euler")
+    scheduler = d.get("scheduler", "simple")
+    shift = d.get("shift", 3.1)
     args.out.mkdir(parents=True, exist_ok=True)
 
     receipt = {"wave": wave.get("wave"), "base": "qwen-image", "unet": QWEN_UNET, "clip": QWEN_CLIP,
-               "vae": QWEN_VAE, "sampler": "euler", "scheduler": "simple", "shift": 3.1,
+               "vae": QWEN_VAE, "sampler": sampler, "scheduler": scheduler, "shift": shift,
                "steps": steps, "cfg": cfg, "size": [w, h], "style_prefix": prefix, "negative": neg,
                "loras": loras, "items": []}
 
@@ -296,7 +367,8 @@ def main() -> None:
     # out and recorded per item in items[]). seed_policy is "explicit-per-item"
     # because each item's seed is written verbatim below. Mirror of the JS contract.
     hash_cache = _load_hash_cache()
-    pin_graph = qwen_graph(prefix or "x", neg, base_seed, w, h, steps, cfg, "sdl", loras=loras)
+    pin_graph = qwen_graph(prefix or "x", neg, base_seed, w, h, steps, cfg, "sdl", loras=loras,
+                            sampler=sampler, scheduler=scheduler, shift=shift)
     receipt["pinning"] = _build_pinning(
         pin_graph,
         {"unet": QWEN_UNET, "clip": QWEN_CLIP, "vae": QWEN_VAE},
@@ -306,21 +378,67 @@ def main() -> None:
         hash_cache,
     )
 
+    receipt_path = args.out / "generation.json"
+
+    def _save_receipt() -> None:
+        # M3: incremental checkpoint (mirrors lib/batch-runs.js's per-slot
+        # atomicWriteJson pattern) — written after EVERY item, not once at
+        # the end. Before this fix, the subject loop called generate() with
+        # no try/except (it can raise the named ComfyUI timeout at its
+        # RuntimeError above), and generation.json was written exactly once,
+        # after the loop finished. A 200-image wave failing at item 130 left
+        # 129 rendered PNGs on disk with NO generation.json at all — the
+        # PIN_PER_STEP provenance this file's own docstring promises, fully
+        # lost, for every item including the ones that succeeded.
+        receipt_path.write_text(json.dumps(receipt, indent=2), encoding="utf-8")
+
     seed = base_seed
+    error_count = 0
     for subj in wave["subjects"]:
         nvar = args.variations if args.variations is not None else subj.get("variations", 1)
         pos = f"{prefix}, {subj['prompt']}" if prefix else subj["prompt"]
         for v in range(nvar):
             dst = args.out / f"{subj['id']}_v{v}.png"
-            generate(pos, neg, seed, dst, w=w, h=h, steps=steps, cfg=cfg, loras=loras)
-            print(f"  {subj['id']} v{v} (seed {seed}) -> {dst.name}", flush=True)
-            receipt["items"].append({"id": subj["id"], "variation": v, "seed": seed, "file": dst.name, "prompt": pos})
+            item = {"id": subj["id"], "variation": v, "seed": seed, "file": dst.name, "prompt": pos}
+            try:
+                generate(pos, neg, seed, dst, w=w, h=h, steps=steps, cfg=cfg, loras=loras,
+                         sampler=sampler, scheduler=scheduler, shift=shift)
+            except Exception as exc:
+                # A single item's failure no longer takes the whole wave's
+                # provenance down with it — record the failure and keep
+                # going. The receipt is checkpointed below regardless of
+                # per-item outcome.
+                item["status"] = "error"
+                item["error"] = str(exc)
+                error_count += 1
+                print(f"  {subj['id']} v{v} (seed {seed}) -> ERROR: {exc}", flush=True)
+            else:
+                item["status"] = "ok"
+                print(f"  {subj['id']} v{v} (seed {seed}) -> {dst.name}", flush=True)
+            receipt["items"].append(item)
             seed += 1
+            _save_receipt()
 
     if args.hash_models:
         _save_hash_cache(hash_cache)
-    (args.out / "generation.json").write_text(json.dumps(receipt, indent=2), encoding="utf-8")
-    print(f"\n{len(receipt['items'])} images -> {args.out}  (+ generation.json provenance)")
+    _save_receipt()
+    ok_count = len(receipt["items"]) - error_count
+    # Plain ASCII only (no em-dash) — matches the rest of this file's
+    # runtime print()/error strings. A Windows console not running in UTF-8
+    # mode mangles non-ASCII on stdout; the docstring/comments can afford
+    # Unicode since those never reach a terminal at runtime.
+    summary = f"\n{ok_count}/{len(receipt['items'])} images -> {args.out}  (+ generation.json provenance)"
+    if error_count:
+        summary += f"  ({error_count} error(s) - see generation.json for per-item detail)"
+    print(summary)
+
+    # Mirror scripts/generate.js's RUNTIME_ALL_FAILED convention: a run where
+    # EVERY item failed exits non-zero (nothing to salvage); a partial
+    # failure still exits 0 — the per-item errors are visible above and in
+    # the checkpointed receipt, and individual item failure is tolerated
+    # everywhere else in this pipeline.
+    if receipt["items"] and error_count == len(receipt["items"]):
+        raise SystemExit(f"all {error_count} generation attempt(s) failed - see generation.json for per-item errors")
 
 
 if __name__ == "__main__":

package/scripts/reingest.js

@@ -11,7 +11,7 @@
 
 import { join } from 'node:path';
 import { parseArgs, getProjectName } from '../lib/args.js';
-import { REPO_ROOT, resolveSafeProjectPath } from '../lib/paths.js';
+import { REPO_ROOT, getProjectRoot, resolveSafeProjectPath } from '../lib/paths.js';
 import { inputError, handleCliError } from '../lib/errors.js';
 import { reingestGenerated, auditReingest } from '../lib/reingest.js';
 
@@ -29,7 +29,7 @@ export async function run(argv = process.argv.slice(2)) {
   });
 
   const projectName = flags.project || getProjectName(argv);
-  const projectRoot = join(REPO_ROOT, 'projects', projectName);
+  const projectRoot = getProjectRoot(projectName);
   const subcommand = positionals[0] || 'audit';
 
   if (subcommand === 'generated') {

package/scripts/sheet.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+
+/**
+ * sheet.js — Render an HTML contact sheet over a directory of images.
+ *
+ * No batch manifest required. Points the SAME HTML renderer that powers
+ * `sdlab batch sheet` (lib/batch-sheet-render.js, via lib/candidate-sheet.js)
+ * at an arbitrary directory under a project — outputs/candidates/,
+ * outputs/approved/, outputs/, whatever — instead of requiring a
+ * batches/<id>/manifest.json that only `sdlab batch generate` can produce.
+ *
+ * Each image is matched to its record by asset_path (when a record exists)
+ * for id / curation status / prompt. Images with no matching record
+ * (pre-ingest — generated but not yet re-ingested) still render, labeled by
+ * filename instead of crashing or being skipped.
+ *
+ * Usage:
+ *   sdlab sheet [<dir>] --project <name> [--out <path>] [--dry-run]
+ *
+ * Examples:
+ *   sdlab sheet --project star-freight                     # outputs/candidates (default)
+ *   sdlab sheet outputs/approved --project star-freight
+ *   sdlab sheet outputs --project star-freight --dry-run    # whole tree, no write
+ */
+
+import { existsSync } from 'node:fs';
+import { relative, dirname } from 'node:path';
+import { parseArgs, getProjectName } from '../lib/args.js';
+import { getProjectRoot, resolveSafeProjectPath } from '../lib/paths.js';
+import { inputError, handleCliError } from '../lib/errors.js';
+import { result } from '../lib/log.js';
+import {
+  buildCandidateSheetItems,
+  renderCandidateSheetHTML,
+  saveCandidateSheet,
+  defaultSheetOutputPath,
+} from '../lib/candidate-sheet.js';
+
+const DEFAULT_DIR = 'outputs/candidates';
+
+function posix(p) {
+  return p.replace(/\\/g, '/');
+}
+
+export async function run(argv = process.argv.slice(2)) {
+  // Checked against the raw argv, not via parseArgs' flag defs: parseArgs
+  // only recognizes "--"-prefixed flags (see lib/args.js), so a bare "-h"
+  // would otherwise fall through to the positional `dir` slot instead of
+  // showing help. Mirrors bin/sdlab.js's own argvHasHelp() check.
+  if (argv.includes('--help') || argv.includes('-h')) {
+    printUsage();
+    return;
+  }
+
+  const { flags, positionals } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      out: { type: 'string' },
+      'dry-run': { type: 'boolean', default: false },
+    },
+    positionals: ['dir'],
+    deprecated: { game: 'project' },
+  });
+
+  const projectName = flags.project || getProjectName(argv);
+  const projectRoot = getProjectRoot(projectName);
+  const dryRun = flags['dry-run'] || flags.dryRun;
+
+  const dirArg = positionals[0] || DEFAULT_DIR;
+  // Containment check — a user-supplied path must never be joined by hand.
+  const safeDir = resolveSafeProjectPath(projectRoot, dirArg, { flagName: 'dir' });
+  const relDir = posix(relative(projectRoot, safeDir)) || '.';
+
+  if (!existsSync(safeDir)) {
+    throw inputError(
+      'INPUT_DIR_NOT_FOUND',
+      `Directory not found: ${relDir} (looked under ${projectRoot})`,
+      'Try outputs/candidates, outputs/approved, outputs/rejected, outputs/borderline, or outputs (the whole tree).'
+    );
+  }
+
+  const items = await buildCandidateSheetItems(projectRoot, safeDir);
+
+  console.log(`\x1b[1mstyle-dataset-lab\x1b[0m sheet — ${projectName}`);
+  console.log(`  Source: ${relDir}`);
+
+  if (items.length === 0) {
+    console.log('  No images found — nothing to render.');
+    return;
+  }
+
+  const matched = items.filter((i) => i.hasRecord).length;
+  console.log(`  Images: ${items.length} (${matched} with records, ${items.length - matched} pre-ingest)`);
+
+  const outRel = flags.out
+    ? flags.out
+    : posix(relative(projectRoot, defaultSheetOutputPath(projectRoot, relDir)));
+  const safeOut = resolveSafeProjectPath(projectRoot, outRel, { flagName: 'out' });
+
+  if (dryRun) {
+    console.log(`  \x1b[33m(dry-run)\x1b[0m would write: ${posix(relative(projectRoot, safeOut))}`);
+    return;
+  }
+
+  const html = renderCandidateSheetHTML({
+    items,
+    title: `Contact sheet — ${projectName} — ${relDir}`,
+    sourceLabel: relDir,
+    sheetOutputDir: dirname(safeOut),
+  });
+
+  const written = await saveCandidateSheet(safeOut, html);
+  result('sheet', posix(relative(projectRoot, written)));
+}
+
+function printUsage() {
+  console.log('Usage: sdlab sheet [<dir>] --project <name> [--out <path>] [--dry-run]');
+  console.log('');
+  console.log('Render an HTML contact sheet over a directory of images — no batch');
+  console.log('manifest required. Matches each image to its record (by asset_path)');
+  console.log('when one exists; degrades to filename when it does not (pre-ingest).');
+  console.log('');
+  console.log('Positional:');
+  console.log('  dir                 Directory to sheet, relative to the project root');
+  console.log(`                      (default: ${DEFAULT_DIR})`);
+  console.log('');
+  console.log('Flags:');
+  console.log('  --project <name>    Project to operate on');
+  console.log('  --out <path>        Output HTML path, relative to project root');
+  console.log('                      (default: outputs/sheets/<slugified-dir>.html)');
+  console.log('  --dry-run           Report what would be written without writing it');
+  console.log('');
+  console.log('Examples:');
+  console.log('  sdlab sheet --project star-freight');
+  console.log('  sdlab sheet outputs/approved --project star-freight');
+  console.log('  sdlab sheet outputs --project star-freight --dry-run');
+}
+
+// Direct execution guard — same pattern as every other script in this repo.
+if (process.argv[1] && (process.argv[1].endsWith('sheet.js') || process.argv[1].endsWith('sheet'))) {
+  run().catch(handleCliError);
+}

package/scripts/snapshot.js

@@ -13,7 +13,7 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { parseArgs, getProjectName } from '../lib/args.js';
-import { REPO_ROOT } from '../lib/paths.js';
+import { getProjectRoot } from '../lib/paths.js';
 import { loadSelectionProfile } from '../lib/config.js';
 import { inputError, handleCliError } from '../lib/errors.js';
 import { createSnapshot, loadSnapshot, listSnapshots, diffSnapshots } from '../lib/snapshot.js';
@@ -30,7 +30,7 @@ export async function run(argv = process.argv.slice(2)) {
   });
 
   const projectName = flags.project || getProjectName(argv);
-  const projectRoot = join(REPO_ROOT, 'projects', projectName);
+  const projectRoot = getProjectRoot(projectName);
   const subcommand = positionals[0] || 'list';
   const dryRun = flags['dry-run'] || flags.dryRun;
 

package/scripts/split.js

@@ -12,7 +12,7 @@
 
 import { join } from 'node:path';
 import { parseArgs, getProjectName } from '../lib/args.js';
-import { REPO_ROOT } from '../lib/paths.js';
+import { getProjectRoot } from '../lib/paths.js';
 import { loadSplitProfile } from '../lib/config.js';
 import { inputError, handleCliError } from '../lib/errors.js';
 import { listSnapshots } from '../lib/snapshot.js';
@@ -30,7 +30,7 @@ export async function run(argv = process.argv.slice(2)) {
   });
 
   const projectName = flags.project || getProjectName(argv);
-  const projectRoot = join(REPO_ROOT, 'projects', projectName);
+  const projectRoot = getProjectRoot(projectName);
   const subcommand = positionals[0] || 'list';
   const dryRun = flags['dry-run'] || flags.dryRun;