@mcptoolshop/style-dataset-lab 3.0.0 → 3.0.1

package/lib/args.js

@@ -10,12 +10,14 @@
  */
 
 import { warnDeprecated } from './deprecation.js';
+import { inputError } from './errors.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
+ * @property {boolean} [allowUnknown] - permit unknown flags (default false)
  */
 
 /**
@@ -28,6 +30,22 @@ export function parseArgs(argv, spec = {}) {
   const flagDefs = spec.flags || {};
   const deprecated = spec.deprecated || {};
   const positionalNames = spec.positionals || [];
+  const allowUnknown = spec.allowUnknown === true;
+
+  // Build alias index once; detect duplicate aliases.
+  const aliasIndex = {};
+  for (const [name, def] of Object.entries(flagDefs)) {
+    if (def && def.alias) {
+      if (aliasIndex[def.alias]) {
+        throw inputError(
+          'INPUT_DUPLICATE_ALIAS',
+          `Duplicate CLI alias "-${def.alias}" (on both "${aliasIndex[def.alias]}" and "${name}")`,
+          'Fix the flag spec: each alias must be unique.'
+        );
+      }
+      aliasIndex[def.alias] = name;
+    }
+  }
 
   const flags = {};
   const positionals = [];
@@ -61,22 +79,44 @@ export function parseArgs(argv, spec = {}) {
         key = deprecated[key];
       }
 
-      // Handle short aliases defined in flagDefs
-      const canonical = Object.entries(flagDefs).find(([, def]) => def.alias === key);
-      if (canonical) key = canonical[0];
+      // Handle short aliases defined in flagDefs (O(1) via prebuilt index)
+      if (aliasIndex[key]) key = aliasIndex[key];
 
       // 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 && !allowUnknown) {
+        const known = Object.keys(flagDefs);
+        const suggestion = findClosest(key, known);
+        const hint = suggestion
+          ? `Did you mean --${suggestion}? (Run with --help to see all supported flags.)`
+          : 'Run with --help to see supported flags.';
+        throw inputError(
+          'UNKNOWN_FLAG',
+          `Unknown flag: --${key}`,
+          hint
+        );
+      }
+
+      const storeKey = key in flagDefs ? key : camelKey;
+
       if (def?.type === 'boolean') {
-        flags[key in flagDefs ? key : camelKey] = true;
+        flags[storeKey] = true;
       } else if (value !== undefined) {
-        flags[key in flagDefs ? key : camelKey] = value;
+        flags[storeKey] = value;
       } else if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) {
-        flags[key in flagDefs ? key : camelKey] = argv[++i];
+        flags[storeKey] = argv[++i];
+      } else if (def && def.type === 'string') {
+        // String flag with no value — that's a user error.
+        throw inputError(
+          'INPUT_MISSING_VALUE',
+          `Flag --${key} requires a value.`,
+          `Pass a value after --${key}.`
+        );
       } else {
-        flags[key in flagDefs ? key : camelKey] = true;
+        // Unknown flag in allowUnknown mode (no def), treat as boolean-style.
+        flags[storeKey] = true;
       }
     } else {
       positionals.push(arg);
@@ -95,12 +135,159 @@ export function parseArgs(argv, spec = {}) {
 
 /**
  * Extract the --project (or deprecated --game) value from argv.
- * Convenience for scripts that just need the project name.
+ *
+ * Returns the explicit value if given. If missing, falls back to
+ * 'star-freight' with a LOUD stderr warning — the fallback exists for
+ * backward compatibility with v2.x scripts but should never be relied on
+ * in new code or documentation.
+ *
+ * Set SDLAB_QUIET_FALLBACK=1 to silence the warning in scripted pipelines.
  */
 export function getProjectName(argv) {
-  const { flags } = parseArgs(argv, {
-    flags: { project: { type: 'string', default: 'star-freight' } },
-    deprecated: { game: 'project' },
-  });
-  return flags.project;
+  // Manual parse (avoids triggering UNKNOWN_FLAG on caller's sibling flags)
+  let explicit = null;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--project' || a === '--game') {
+      if (a === '--game') warnDeprecated('game', 'project');
+      explicit = argv[i + 1];
+      break;
+    }
+    if (a.startsWith('--project=')) { explicit = a.slice('--project='.length); break; }
+    if (a.startsWith('--game=')) { warnDeprecated('game', 'project'); explicit = a.slice('--game='.length); break; }
+  }
+  if (explicit) return explicit;
+
+  // Backward compat: fall back to star-freight but warn LOUDLY.
+  if (process.env.SDLAB_QUIET_FALLBACK !== '1') {
+    process.stderr.write(
+      '\x1b[33m⚠ No --project specified, falling back to "star-freight".\x1b[0m\n' +
+      '\x1b[33m  Use --project <name> to be explicit (set SDLAB_QUIET_FALLBACK=1 to silence).\x1b[0m\n'
+    );
+  }
+  return 'star-freight';
+}
+
+/**
+ * Compute Levenshtein edit distance between two strings.
+ * Small hand-rolled implementation — O(m*n) time, O(min(m,n)) space.
+ */
+export function levenshtein(a, b) {
+  if (a === b) return 0;
+  if (!a) return b.length;
+  if (!b) return a.length;
+  // Keep the shorter string in the inner loop for better memory.
+  if (a.length > b.length) { const t = a; a = b; b = t; }
+  const prev = new Array(a.length + 1);
+  const curr = new Array(a.length + 1);
+  for (let i = 0; i <= a.length; i++) prev[i] = i;
+  for (let j = 1; j <= b.length; j++) {
+    curr[0] = j;
+    for (let i = 1; i <= a.length; i++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[i] = Math.min(
+        curr[i - 1] + 1,      // insertion
+        prev[i] + 1,          // deletion
+        prev[i - 1] + cost    // substitution
+      );
+    }
+    for (let i = 0; i <= a.length; i++) prev[i] = curr[i];
+  }
+  return prev[a.length];
+}
+
+/**
+ * Find the nearest match to `needle` in `candidates` within `maxDistance`.
+ * Returns the closest candidate, or null if nothing qualifies.
+ * Used for "did you mean?" hints on unknown flags / commands.
+ */
+export function findClosest(needle, candidates, maxDistance = 2) {
+  if (!needle || !Array.isArray(candidates) || candidates.length === 0) return null;
+  // Short inputs have little tolerance.
+  const cap = needle.length <= 3 ? 1 : maxDistance;
+  let best = null;
+  let bestDist = Infinity;
+  for (const c of candidates) {
+    if (typeof c !== 'string') continue;
+    const d = levenshtein(needle.toLowerCase(), c.toLowerCase());
+    if (d < bestDist && d <= cap) {
+      bestDist = d;
+      best = c;
+    }
+  }
+  return best;
+}
+
+/**
+ * Parse a CLI value as a number with NaN validation.
+ * @param {string} name - flag name, for error messages
+ * @param {string|number|undefined} value - the raw flag value
+ * @param {{min?:number,max?:number,int?:boolean,default?:number}} opts
+ */
+export function parseNumberFlag(name, value, opts = {}) {
+  if (value === undefined || value === null || value === '') {
+    if (opts.default !== undefined) return opts.default;
+    throw inputError(
+      'INPUT_MISSING_VALUE',
+      `Flag --${name} requires a numeric value.`,
+      `Example: --${name} 4`
+    );
+  }
+  const n = opts.int ? Number.parseInt(String(value), 10) : Number.parseFloat(String(value));
+  if (!Number.isFinite(n)) {
+    throw inputError(
+      'INPUT_BAD_NUMBER',
+      `Flag --${name} expected a number, got "${value}".`,
+      `Pass a ${opts.int ? 'whole number' : 'number'} instead.`
+    );
+  }
+  if (opts.min !== undefined && n < opts.min) {
+    throw inputError('INPUT_OUT_OF_RANGE', `--${name} must be ≥ ${opts.min}, got ${n}.`);
+  }
+  if (opts.max !== undefined && n > opts.max) {
+    throw inputError('INPUT_OUT_OF_RANGE', `--${name} must be ≤ ${opts.max}, got ${n}.`);
+  }
+  return n;
+}
+
+/**
+ * Read an indexed-next-arg value from argv but refuse to consume a flag-like token.
+ * Useful for legacy scripts still using indexOf/argv[idx+1] patterns — wraps the access
+ * with a safety check so `--source --manifest` doesn't silently treat `--manifest` as a path.
+ */
+export function takeFlagValue(argv, flagName) {
+  const idx = argv.indexOf(`--${flagName}`);
+  if (idx < 0) {
+    // Try --flag=value form
+    const eq = argv.find(a => a.startsWith(`--${flagName}=`));
+    if (eq) return eq.slice(`--${flagName}=`.length);
+    return undefined;
+  }
+  const nxt = argv[idx + 1];
+  if (nxt === undefined) {
+    throw inputError('INPUT_MISSING_VALUE', `Flag --${flagName} requires a value.`);
+  }
+  if (typeof nxt === 'string' && nxt.startsWith('--')) {
+    throw inputError(
+      'INPUT_MISSING_VALUE',
+      `Flag --${flagName} is missing its value (got another flag: ${nxt}).`,
+      `Pass a value after --${flagName}.`
+    );
+  }
+  return nxt;
+}
+
+/**
+ * Strip the subcommand token at position argv[firstPositionalIndex] by slicing,
+ * avoiding the value-based filter bug where a project/id that matches the
+ * subcommand string would be stripped too.
+ *
+ * Returns the args AFTER the first non-flag token. If no non-flag token is
+ * found, returns a copy of argv.
+ */
+export function sliceAfterSubcommand(argv, subcommand) {
+  if (subcommand == null) return argv.slice();
+  const idx = argv.indexOf(subcommand);
+  if (idx < 0) return argv.slice();
+  return argv.slice(idx + 1);
 }

package/lib/batch-compiler.js

@@ -26,11 +26,15 @@ export function applySlotDelta(baseBrief, slot) {
     modified.prompt = `${modified.prompt}, ${slot.prompt_additions.join(', ')}`;
   }
 
-  // Negative additions — append without duplicating
+  // Negative additions — append without duplicating (token-exact match)
   if (slot.negative_additions?.length > 0) {
-    const existingLower = modified.negative_prompt.toLowerCase().split(',').map(s => s.trim());
+    const existingLower = modified.negative_prompt
+      .toLowerCase()
+      .split(',')
+      .map(s => s.trim())
+      .filter(s => s.length > 0);
     const additions = slot.negative_additions.filter(
-      n => !existingLower.some(e => e.includes(n.toLowerCase()))
+      n => !existingLower.includes(n.toLowerCase().trim())
     );
     if (additions.length > 0) {
       modified.negative_prompt = `${modified.negative_prompt}, ${additions.join(', ')}`;

package/lib/batch-runs.js

@@ -10,15 +10,32 @@
  *     briefs/ (slot briefs)
  */
 
-import { writeFile, mkdir, copyFile } from 'node:fs/promises';
+import { writeFile, mkdir, copyFile, rename, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { getProjectRoot, getRunsDir } from './paths.js';
 import { executeRun } from './adapters/comfyui-runner.js';
 import { saveRunSummary } from './run-summary.js';
-import { log, info, warn } from './log.js';
+import { log, info, warn, verbose } from './log.js';
 import { inputError } from './errors.js';
 
+/**
+ * PB-002 / PB-005: atomic write helper — write temp + rename.
+ * Rename is atomic on a single filesystem, so a crash mid-write cannot
+ * corrupt an existing manifest.
+ */
+async function atomicWriteJson(targetPath, obj) {
+  const tmpPath = `${targetPath}.tmp-${process.pid}-${Date.now()}`;
+  const body = JSON.stringify(obj, null, 2) + '\n';
+  try {
+    await writeFile(tmpPath, body);
+    await rename(tmpPath, targetPath);
+  } catch (err) {
+    try { await unlink(tmpPath); } catch { /* ignore */ }
+    throw err;
+  }
+}
+
 /**
  * Return the batches directory for a project.
  */
@@ -29,6 +46,10 @@ export function getBatchesDir(projectRoot) {
 /**
  * Generate batch ID: batch_YYYY-MM-DD_NNN
  */
+// PB-008: tighten regex so stray directories like 'batch_<date>_001_wip'
+// don't inflate the sequence via lenient parseInt.
+const BATCH_SEQ_RE = /^(\d{3})$/;
+
 export function generateBatchId(batchesDir) {
   const today = new Date().toISOString().slice(0, 10);
   const prefix = `batch_${today}_`;
@@ -39,8 +60,10 @@ export function generateBatchId(batchesDir) {
       .filter(e => e.isDirectory() && e.name.startsWith(prefix));
     for (const e of existing) {
       const seqStr = e.name.slice(prefix.length);
-      const seq = parseInt(seqStr, 10);
-      if (!isNaN(seq) && seq > maxSeq) maxSeq = seq;
+      const match = BATCH_SEQ_RE.exec(seqStr);
+      if (!match) continue;
+      const seq = parseInt(match[1], 10);
+      if (seq > maxSeq) maxSeq = seq;
     }
   }
 
@@ -82,7 +105,20 @@ export async function executeBatchRuns({
   slotBriefs,
   dryRun = false,
 }) {
+  // PB-005: fail fast on length mismatch instead of crashing deep in the loop.
+  if (!Array.isArray(mode?.variant_plan) || mode.variant_plan.length !== slotBriefs.length) {
+    throw inputError(
+      'BATCH_SLOT_PLAN_MISMATCH',
+      `Batch variant_plan has ${mode?.variant_plan?.length ?? 0} slots but ` +
+      `${slotBriefs.length} brief(s) were compiled`,
+      'This is an internal invariant — rebuild the batch from the mode definition.'
+    );
+  }
+
   const results = [];
+  // PB-005: incremental batch-progress manifest — written after every slot
+  // so a crash never orphans the batch dir without a record of what ran.
+  const progressPath = join(batchDir, 'manifest.json');
 
   for (let i = 0; i < slotBriefs.length; i++) {
     const slot = mode.variant_plan[i];
@@ -98,29 +134,63 @@ export async function executeBatchRuns({
       JSON.stringify(brief, null, 2) + '\n'
     );
 
-    // Execute the run through the existing 4B pipeline
-    const manifest = await executeRun({
-      projectRoot,
-      projectName,
-      brief,
-      dryRun,
-    });
-
-    // Save run summary
-    const runDir = join(getRunsDir(projectRoot), manifest.run_id);
-    await saveRunSummary(runDir, manifest);
-
-    results.push({
-      slot_id: slot.slot_id,
-      label: slotLabel,
-      brief_id: brief.brief_id,
-      run_id: manifest.run_id,
-      manifest,
-      // Pick the first successful output as the selected one
-      selected_output: manifest.outputs.find(o =>
-        o.status === 'ok' || o.status === 'dry_run'
-      )?.filename || null,
-    });
+    // PB-005: per-slot try/catch — one slot failure no longer throws out of
+    // the whole batch. Record the error and keep going so the user doesn't
+    // lose already-completed slots.
+    try {
+      // Execute the run through the existing 4B pipeline
+      const manifest = await executeRun({
+        projectRoot,
+        projectName,
+        brief,
+        dryRun,
+      });
+
+      // Save run summary
+      const runDir = join(getRunsDir(projectRoot), manifest.run_id);
+      await saveRunSummary(runDir, manifest);
+
+      results.push({
+        slot_id: slot.slot_id,
+        label: slotLabel,
+        brief_id: brief.brief_id,
+        run_id: manifest.run_id,
+        manifest,
+        status: 'ok',
+        // Pick the first successful output as the selected one
+        selected_output: manifest.outputs.find(o =>
+          o.status === 'ok' || o.status === 'dry_run'
+        )?.filename || null,
+      });
+    } catch (err) {
+      warn(`  ✗ slot ${slotLabel} failed: ${err.message}`);
+      results.push({
+        slot_id: slot.slot_id,
+        label: slotLabel,
+        brief_id: brief.brief_id,
+        run_id: null,
+        manifest: null,
+        status: 'error',
+        error: err.message,
+        selected_output: null,
+      });
+    }
+
+    // PB-005: checkpoint after every slot (atomic write).
+    try {
+      await atomicWriteJson(progressPath, {
+        batch_dir: batchDir,
+        mode_id: mode?.mode_id ?? mode?.id ?? null,
+        incremental: true,
+        last_checkpoint_at: new Date().toISOString(),
+        completed: i + 1,
+        total: slotBriefs.length,
+        slots: results,
+      });
+      verbose(`batch checkpoint: ${i + 1}/${slotBriefs.length} slots`);
+    } catch (err) {
+      warn(`  batch checkpoint write failed: ${err.message}`);
+    }
   }
 
   return results;
@@ -130,10 +200,9 @@ export async function executeBatchRuns({
  * Save a batch manifest.
  */
 export async function saveBatchManifest(batchDir, manifest) {
-  await writeFile(
-    join(batchDir, 'manifest.json'),
-    JSON.stringify(manifest, null, 2) + '\n'
-  );
+  // PB-002: atomic write — safe to overwrite an in-progress checkpoint
+  // because rename is atomic on a single filesystem.
+  await atomicWriteJson(join(batchDir, 'manifest.json'), manifest);
 }
 
 /**

package/lib/batch-sheet-render.js

@@ -41,12 +41,15 @@ function resolveImagePath(projectRoot, result, batchDir) {
 export function renderSheetHTML({ manifest, mode, projectRoot, batchDir }) {
   const assembly = mode.assembly || {};
   const layout = assembly.layout || 'grid';
-  const columns = assembly.columns || computeColumns(manifest.slots.length);
+  const slots = manifest.slots || [];
+  const rawColumns = assembly.columns;
+  const columns = (typeof rawColumns === 'number' && rawColumns > 0)
+    ? rawColumns
+    : computeColumns(slots.length);
   const showSlotLabels = assembly.annotate_slots !== false;
   const showSeed = assembly.show_seed || false;
 
   const title = `${manifest.mode_id} — ${manifest.subject_id || manifest.theme || manifest.project_id}`;
-  const slots = manifest.slots || [];
 
   // Build slot cells
   const cells = slots.map(slot => {

package/lib/brief-compiler.js

@@ -47,6 +47,24 @@ function generateBriefId(briefsDir) {
   return `${prefix}${seq}`;
 }
 
+// ─── Canonical JSON ──────────────────────────────────────────────
+
+/**
+ * Recursively canonicalize an object: sort keys at every nesting level.
+ * Arrays retain their order (order is semantically meaningful for arrays).
+ * Primitives pass through untouched.
+ */
+export function canonicalize(value) {
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(canonicalize);
+  const sortedKeys = Object.keys(value).sort();
+  const out = {};
+  for (const key of sortedKeys) {
+    out[key] = canonicalize(value[key]);
+  }
+  return out;
+}
+
 // ─── Config fingerprint ──────────────────────────────────────────
 
 /**
@@ -67,9 +85,9 @@ function computeBriefFingerprint(projectRoot, workflow, subjectRecords) {
     }
   }
 
-  // Workflow profile (serialized deterministically)
+  // Workflow profile (serialized deterministically, recursively key-sorted)
   hash.update('--- workflow ---\n');
-  hash.update(JSON.stringify(workflow, Object.keys(workflow).sort()));
+  hash.update(JSON.stringify(canonicalize(workflow)));
   hash.update('\n');
 
   // Subject records (sorted by ID)
@@ -385,16 +403,16 @@ function buildDriftWarnings(workflow, config) {
 /**
  * Build the runtime plan — merge workflow defaults with CLI overrides.
  */
-function buildRuntimePlan(workflow, overrides = {}) {
+export function buildRuntimePlan(workflow, overrides = {}) {
   const rd = workflow.runtime_defaults || {};
   return {
-    adapter_target: overrides.adapter_target || rd.adapter_target || 'comfyui',
-    width: overrides.width || rd.width || 1024,
-    height: overrides.height || rd.height || 1024,
-    steps: overrides.steps || rd.steps || 30,
-    cfg: overrides.cfg || rd.cfg || 6.5,
-    sampler: overrides.sampler || rd.sampler || 'dpmpp_2m',
-    seed_mode: overrides.seed_mode || rd.seed_mode || 'increment',
+    adapter_target: overrides.adapter_target ?? rd.adapter_target ?? 'comfyui',
+    width: overrides.width ?? rd.width ?? 1024,
+    height: overrides.height ?? rd.height ?? 1024,
+    steps: overrides.steps ?? rd.steps ?? 30,
+    cfg: overrides.cfg ?? rd.cfg ?? 6.5,
+    sampler: overrides.sampler ?? rd.sampler ?? 'dpmpp_2m',
+    seed_mode: overrides.seed_mode ?? rd.seed_mode ?? 'increment',
   };
 }
 
@@ -427,6 +445,15 @@ export async function compileBrief({
   // Load workflow profile
   const workflow = await getWorkflowProfile(projectRoot, workflowId);
 
+  // Validate required workflow fields
+  if (typeof workflow.output_mode !== 'string' || workflow.output_mode.length === 0) {
+    throw inputError(
+      'WORKFLOW_INVALID',
+      `Workflow "${workflowId}" is missing a non-empty "output_mode"`,
+      `Check the workflow profile JSON — output_mode must be a non-empty string.`
+    );
+  }
+
   // Enforce subject_mode
   const subjectMode = workflow.subject_mode || 'optional';
   if (subjectMode === 'required' && !subjectId) {
@@ -486,7 +513,7 @@ export async function compileBrief({
   // Expected outputs
   const expectedOutputs = {
     output_mode: workflow.output_mode,
-    output_count: overrides.output_count || workflow.output_count,
+    output_count: overrides.output_count ?? workflow.output_count,
     review_surface: workflow.output_mode.replace(/_/g, ' '),
   };
 

package/lib/card.js

@@ -70,6 +70,13 @@ export async function generateCard(projectRoot, snapshotId, splitId) {
   return { markdown, json };
 }
 
+// D-025: safe percentage formatter — renders '—' for zero-total cases
+// instead of 'NaN%'.
+function pct(numerator, denominator) {
+  if (!denominator || denominator <= 0) return '—';
+  return `${(numerator / denominator * 100).toFixed(1)}%`;
+}
+
 function renderMarkdown(card, config) {
   const lines = [];
   const add = (s = '') => lines.push(s);
@@ -87,7 +94,7 @@ function renderMarkdown(card, config) {
   add(`- **Snapshot:** \`${card.snapshot.id}\``);
   add(`- **Config fingerprint:** \`${card.snapshot.config_fingerprint.slice(0, 16)}...\``);
   add(`- **Total records evaluated:** ${card.snapshot.total_records}`);
-  add(`- **Included:** ${card.snapshot.included} (${(card.snapshot.included / card.snapshot.total_records * 100).toFixed(1)}%)`);
+  add(`- **Included:** ${card.snapshot.included} (${pct(card.snapshot.included, card.snapshot.total_records)})`);
   add(`- **Excluded:** ${card.snapshot.excluded}`);
   add();
 
@@ -111,9 +118,9 @@ function renderMarkdown(card, config) {
   add('| Partition | Records | % |');
   add('|-----------|---------|---|');
   const total = card.split.counts.total_records;
-  add(`| Train | ${card.split.counts.train} | ${(card.split.counts.train / total * 100).toFixed(1)}% |`);
-  add(`| Val | ${card.split.counts.val} | ${(card.split.counts.val / total * 100).toFixed(1)}% |`);
-  add(`| Test | ${card.split.counts.test} | ${(card.split.counts.test / total * 100).toFixed(1)}% |`);
+  add(`| Train | ${card.split.counts.train} | ${pct(card.split.counts.train, total)} |`);
+  add(`| Val | ${card.split.counts.val} | ${pct(card.split.counts.val, total)} |`);
+  add(`| Test | ${card.split.counts.test} | ${pct(card.split.counts.test, total)} |`);
   add();
 
   add('## Lane Balance');