@mcptoolshop/style-dataset-lab 3.2.0 → 3.4.0

package/scripts/qwen_generate.py

@@ -15,10 +15,14 @@ embedded python (has PIL): start the watchdog (E:/AI/training/_watchdog.ps1) bef
 from __future__ import annotations
 
 import argparse
+import hashlib
 import json
+import math
+import os
 import time
 import urllib.request
 import uuid
+from decimal import Decimal
 from pathlib import Path
 
 from PIL import Image
@@ -31,13 +35,255 @@ QWEN_UNET = "qwen_image_fp8_e4m3fn.safetensors"
 QWEN_CLIP = "qwen_2.5_vl_7b_fp8_scaled.safetensors"
 QWEN_VAE = "qwen_image_vae.safetensors"
 
+# ─── PIN_PER_STEP pinning contract ────────────────────────────────────────────
+# Mirror of lib/run-manifest.js (the JS helper is the field-name authority). This
+# receipt carries the IDENTICAL `pinning` block so a wave produced by this bridge
+# generator is pinned the same way as one produced through the JS `sdlab generate`
+# / `sdlab run generate` paths. Keep PINNING_VERSION + the field names in lockstep
+# with lib/run-manifest.js.
+PINNING_VERSION = "1.0.0"
+MODELS_DIR = os.environ.get(
+    "SDLAB_MODELS_DIR", r"E:/AI-Models/ComfyUI_windows_portable/ComfyUI/models"
+)
+HASH_CACHE_FILE = os.environ.get("SDLAB_HASH_CACHE") or str(
+    Path(MODELS_DIR) / ".sdlab-hash-cache.json"
+)
+# kind → candidate subdirs under the models dir, in search order (mirror of JS).
+_KIND_SUBDIRS = {
+    "unet": ["diffusion_models", "unet"],
+    "clip": ["text_encoders", "clip"],
+    "vae": ["vae"],
+    "checkpoint": ["checkpoints"],
+    "lora": ["loras"],
+}
+
+
+def _js_number(n) -> str:
+    """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 math.isnan(n) or math.isinf(n):
+            return "null"
+        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."""
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return _js_number(value)
+    if isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False)
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(_stable_stringify(v) for v in value) + "]"
+    if isinstance(value, dict):
+        # JS omits `undefined` keys; Python has no undefined, and None maps to JS
+        # `null` which stableStringify DOES serialize — so serialize every key.
+        parts = [
+            json.dumps(k, ensure_ascii=False) + ":" + _stable_stringify(value[k])
+            for k in sorted(value.keys())
+        ]
+        return "{" + ",".join(parts) + "}"
+    return "null"
+
+
+def _normalize_graph_for_hash(graph: dict) -> dict:
+    """Blank per-item nondeterminism (seed, prompt text, filename_prefix) so the
+    whole wave shares one comfy_workflow_sha. Mirror of the JS normalizer."""
+    out = {}
+    for nid, node in (graph or {}).items():
+        inputs = dict(node.get("inputs", {}))
+        cls = node.get("class_type")
+        if cls in ("KSampler", "KSamplerAdvanced"):
+            if "seed" in inputs:
+                inputs["seed"] = 0
+            if "noise_seed" in inputs:
+                inputs["noise_seed"] = 0
+        elif cls == "CLIPTextEncode":
+            if "text" in inputs:
+                inputs["text"] = ""
+        elif cls == "SaveImage":
+            if "filename_prefix" in inputs:
+                inputs["filename_prefix"] = ""
+        out[nid] = {"class_type": cls, "inputs": inputs}
+    return out
+
+
+def _comfy_workflow_sha(graph: dict):
+    if not graph:
+        return None
+    payload = _stable_stringify(_normalize_graph_for_hash(graph))
+    return "sha256:" + hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def _resolve_model_path(name: str, kind: str):
+    if not name:
+        return None
+    subdirs = list(_KIND_SUBDIRS.get(kind, []))
+    for group in _KIND_SUBDIRS.values():
+        subdirs.extend(group)
+    subdirs.append(".")
+    seen = set()
+    for sub in subdirs:
+        cand = os.path.join(MODELS_DIR, sub, name)
+        if cand in seen:
+            continue
+        seen.add(cand)
+        if os.path.exists(cand):
+            return cand
+    return None
+
+
+def _sha256_file(path: str) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return "sha256:" + h.hexdigest()
+
+
+def _load_hash_cache() -> dict:
+    try:
+        with open(HASH_CACHE_FILE, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception:
+        return {}
+
+
+def _save_hash_cache(cache: dict) -> None:
+    try:
+        with open(HASH_CACHE_FILE, "w", encoding="utf-8") as f:
+            json.dump(cache, f, indent=2)
+    except Exception:
+        pass
+
+
+def _hash_model_file(name: str, kind: str, do_hash: bool, cache: dict) -> dict:
+    """Best-effort {name, size_bytes, sha256} for a model/LoRA file (mirror of the
+    JS hashModelFile). size_bytes is always filled when resolvable; sha256 is
+    gated behind do_hash and cached by (name, size, mtime)."""
+    if not name:
+        return {"name": name, "size_bytes": None, "sha256": None, "hash_note": "no filename"}
+    resolved = _resolve_model_path(name, kind)
+    if not resolved:
+        return {"name": name, "size_bytes": None, "sha256": None, "hash_note": f"unresolved under {MODELS_DIR}"}
+    try:
+        st = os.stat(resolved)
+        size_bytes = st.st_size
+        mtime_ms = round(st.st_mtime * 1000)
+    except OSError:
+        return {"name": name, "size_bytes": None, "sha256": None, "hash_note": "stat failed"}
+    if not do_hash:
+        return {"name": name, "size_bytes": size_bytes, "sha256": None, "hash_note": "hash skipped (pass --hash-models)"}
+    key = f"{name}:{size_bytes}:{mtime_ms}"
+    if key in cache:
+        return {"name": name, "size_bytes": size_bytes, "sha256": cache[key]}
+    try:
+        sha = _sha256_file(resolved)
+    except OSError:
+        return {"name": name, "size_bytes": size_bytes, "sha256": None, "hash_note": "hash failed (read error)"}
+    cache[key] = sha
+    return {"name": name, "size_bytes": size_bytes, "sha256": sha}
+
+
+def _build_pinning(graph, models, loras, seed_policy, do_hash, cache) -> dict:
+    """Assemble the pinning block — identical shape to lib/run-manifest.js buildPinning."""
+    model_hashes = {}
+    for role, kind in (("unet", "unet"), ("clip", "clip"), ("vae", "vae"), ("checkpoint", "checkpoint")):
+        if models.get(role):
+            model_hashes[role] = _hash_model_file(models[role], kind, do_hash, cache)
+    lora_hashes = []
+    for lora in loras or []:
+        entry = _hash_model_file(lora.get("name"), "lora", do_hash, cache)
+        entry["weight"] = _js_nullish(lora.get("weight"), 1.0)  # SDL-H4
+        lora_hashes.append(entry)
+    return {
+        "pinning_version": PINNING_VERSION,
+        "comfy_workflow_sha": _comfy_workflow_sha(graph),
+        "seed_policy": seed_policy,
+        "models": model_hashes,
+        "loras": lora_hashes,
+    }
+
 
 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"}},
@@ -49,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]}},
     })
@@ -68,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())
@@ -89,6 +337,8 @@ def main() -> None:
     ap.add_argument("--wave", required=True, type=Path)
     ap.add_argument("--out", required=True, type=Path)
     ap.add_argument("--variations", type=int, default=None, help="override per-subject variation count")
+    ap.add_argument("--hash-models", action="store_true",
+                    help="content-hash the unet/clip/vae/LoRA files into the pinning block (best-effort, cached)")
     args = ap.parse_args()
 
     wave = json.loads(args.wave.read_text(encoding="utf-8"))
@@ -99,25 +349,96 @@ 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": []}
+
+    # PIN_PER_STEP: pin the exact graph + model/LoRA content identity + seed policy.
+    # The wave shares ONE comfy_workflow_sha (per-item seed + prompt are normalized
+    # 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,
+                            sampler=sampler, scheduler=scheduler, shift=shift)
+    receipt["pinning"] = _build_pinning(
+        pin_graph,
+        {"unet": QWEN_UNET, "clip": QWEN_CLIP, "vae": QWEN_VAE},
+        loras,
+        "explicit-per-item",
+        args.hash_models,
+        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)
+    _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)
 
-    (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)")
+    # 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/run-generate.js

@@ -24,6 +24,7 @@ export async function run(argv = process.argv.slice(2)) {
       brief: { type: 'string' },
       seed: { type: 'string' },
       'dry-run': { type: 'boolean' },
+      'hash-models': { type: 'boolean' },
       json: { type: 'boolean' },
     },
     deprecated: { game: 'project' },
@@ -36,6 +37,7 @@ export async function run(argv = process.argv.slice(2)) {
     console.log('  --brief <id>      Compiled brief ID (required)');
     console.log('  --seed <n>        Override base seed');
     console.log('  --dry-run         Prepare run dir without submitting to ComfyUI');
+    console.log('  --hash-models     Content-hash the model/LoRA files into the run manifest (best-effort, cached)');
     console.log('  --json            Output manifest as JSON');
     return;
   }
@@ -59,6 +61,7 @@ export async function run(argv = process.argv.slice(2)) {
     brief,
     baseSeed: flags.seed ? parseNumberFlag('seed', flags.seed, { int: true, min: 0 }) : undefined,
     dryRun: flags['dry-run'] || false,
+    hashModels: flags['hash-models'] || false,
   });
 
   // Save summary

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;
 

package/scripts/training-manifest.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 { inputError, handleCliError } from '../lib/errors.js';
 import { listExports } from '../lib/export.js';
 import {
@@ -35,7 +35,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.find(a => !a.startsWith('tm-')) || 'list';
 
   if (subcommand === 'create') {