@mcptoolshop/style-dataset-lab 1.2.1 → 2.1.0

package/scripts/card.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+/**
+ * card.js — Generate dataset cards.
+ *
+ * Usage:
+ *   sdlab card generate --snapshot <id> --split <id> [--project <name>]
+ */
+
+import { join } from 'node:path';
+import { writeFile } from 'node:fs/promises';
+import { getProjectName } from '../lib/args.js';
+import { REPO_ROOT } from '../lib/paths.js';
+import { listSnapshots } from '../lib/snapshot.js';
+import { listSplits } from '../lib/split.js';
+import { generateCard } from '../lib/card.js';
+
+export async function run(argv = process.argv.slice(2)) {
+  const projectName = getProjectName(argv);
+  const projectRoot = join(REPO_ROOT, 'projects', projectName);
+  const subcommand = argv.find(a => !a.startsWith('--')) || 'generate';
+  const args = argv.filter(a => a !== subcommand);
+
+  if (subcommand === 'generate') {
+    // Find snapshot
+    let snapshotId;
+    const snapIdx = args.indexOf('--snapshot');
+    if (snapIdx >= 0) {
+      snapshotId = args[snapIdx + 1];
+    } else {
+      const snapshots = await listSnapshots(projectRoot);
+      if (snapshots.length === 0) throw new Error('No snapshots found. Run: sdlab snapshot create');
+      snapshotId = snapshots[snapshots.length - 1].id;
+    }
+
+    // Find split
+    let splitId;
+    const splitIdx = args.indexOf('--split');
+    if (splitIdx >= 0) {
+      splitId = args[splitIdx + 1];
+    } else {
+      const splits = await listSplits(projectRoot);
+      if (splits.length === 0) throw new Error('No splits found. Run: sdlab split build');
+      splitId = splits[splits.length - 1].id;
+    }
+
+    console.log(`\x1b[1msdlab card generate\x1b[0m — ${projectName}`);
+    console.log(`  Snapshot: ${snapshotId}`);
+    console.log(`  Split:    ${splitId}`);
+    console.log('');
+
+    const { markdown, json } = await generateCard(projectRoot, snapshotId, splitId);
+
+    // Write to project root
+    const mdPath = join(projectRoot, 'dataset-card.md');
+    const jsonPath = join(projectRoot, 'dataset-card.json');
+    await writeFile(mdPath, markdown);
+    await writeFile(jsonPath, JSON.stringify(json, null, 2) + '\n');
+
+    console.log(`  \x1b[32m✓\x1b[0m dataset-card.md`);
+    console.log(`  \x1b[32m✓\x1b[0m dataset-card.json`);
+
+  } else {
+    throw new Error(`Unknown subcommand: ${subcommand}. Use: generate`);
+  }
+}
+
+if (process.argv[1] && (process.argv[1].endsWith('card.js') || process.argv[1].endsWith('card'))) {
+  run().catch((err) => {
+    console.error(err.message || err);
+    process.exit(1);
+  });
+}

package/scripts/compare.js

@@ -5,37 +5,54 @@
  *
  * Usage:
  *   node scripts/compare.js <asset_a_id> <asset_b_id> <winner: a|b|tie> <reasoning>
- *   node scripts/compare.js iron_sword_base iron_sword_icon_mid a "Better silhouette, painterly execution"
+ *   sdlab compare iron_sword_base iron_sword_icon_mid a "Better silhouette" --project star-freight
  */
 
 import { readFile, writeFile, readdir, mkdir } from "node:fs/promises";
 import { join } from "node:path";
+import { getProjectName } from "../lib/args.js";
+import { REPO_ROOT } from "../lib/paths.js";
 
-const REPO_ROOT = new URL("..", import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1");
-const GAME = process.argv.find((a, i) => process.argv[i - 1] === '--game') || 'star-freight';
-const GAME_ROOT = join(REPO_ROOT, 'games', GAME);
+function getFlagValue(args, flag) {
+  const prefix = `--${flag}=`;
+  for (const a of args) {
+    if (a.startsWith(prefix)) return a.slice(prefix.length);
+  }
+  const idx = args.indexOf(`--${flag}`);
+  if (idx !== -1 && idx + 1 < args.length) return args[idx + 1];
+  return undefined;
+}
+
+export async function run(argv = process.argv.slice(2)) {
+  const projectName = getProjectName(argv);
+  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
+
+  // Strip --project/--game and their values from positional parsing
+  const args = argv.filter((a, i) => {
+    if (a === '--project' || a === '--game') return false;
+    if (i > 0 && (argv[i - 1] === '--project' || argv[i - 1] === '--game')) return false;
+    return true;
+  });
 
-async function main() {
-  const args = process.argv.slice(2);
   const [assetAId, assetBId, winner, ...reasonParts] = args;
 
   if (!assetAId || !assetBId || !winner) {
-    console.log("Usage: node scripts/compare.js <asset_a_id> <asset_b_id> <a|b|tie> <reasoning>");
-    process.exit(1);
+    throw new Error("Usage: sdlab compare <asset_a_id> <asset_b_id> <a|b|tie> <reasoning>");
   }
 
   if (!["a", "b", "tie"].includes(winner)) {
-    console.error(`Invalid winner: ${winner}. Must be a, b, or tie.`);
-    process.exit(1);
+    throw new Error(`Invalid winner: ${winner}. Must be a, b, or tie.`);
   }
 
-  const reasoning = reasonParts.join(" ") || null;
+  const reasoning = reasonParts.filter(r => !r.startsWith('--')).join(" ") || null;
 
   // Load records to get paths
-  const recordA = await loadRecord(assetAId);
-  const recordB = await loadRecord(assetBId);
+  const recordA = await loadRecord(GAME_ROOT, assetAId);
+  const recordB = await loadRecord(GAME_ROOT, assetBId);
 
-  if (!recordA || !recordB) process.exit(1);
+  if (!recordA || !recordB) {
+    throw new Error("Could not load one or both records.");
+  }
 
   // Parse optional scores
   const scoresStr = getFlagValue(args, "scores");
@@ -52,7 +69,7 @@ async function main() {
   }
 
   // Build comparison ID
-  const existingComps = await countComparisons();
+  const existingComps = await countComparisons(GAME_ROOT);
   const cmpId = `cmp_${String(existingComps + 1).padStart(3, "0")}`;
 
   const comparison = {
@@ -81,7 +98,7 @@ async function main() {
   if (reasoning) console.log(`  ${reasoning}`);
 }
 
-async function loadRecord(id) {
+async function loadRecord(GAME_ROOT, id) {
   try {
     const path = join(GAME_ROOT, `records/${id}.json`);
     return JSON.parse(await readFile(path, "utf-8"));
@@ -91,7 +108,7 @@ async function loadRecord(id) {
   }
 }
 
-async function countComparisons() {
+async function countComparisons(GAME_ROOT) {
   try {
     const files = await readdir(join(GAME_ROOT, "comparisons"));
     return files.filter((f) => f.endsWith(".json")).length;
@@ -100,17 +117,10 @@ async function countComparisons() {
   }
 }
 
-function getFlagValue(args, flag) {
-  const prefix = `--${flag}=`;
-  for (const a of args) {
-    if (a.startsWith(prefix)) return a.slice(prefix.length);
-  }
-  const idx = args.indexOf(`--${flag}`);
-  if (idx !== -1 && idx + 1 < args.length) return args[idx + 1];
-  return undefined;
+// Direct execution guard
+if (process.argv[1] && (process.argv[1].endsWith('compare.js') || process.argv[1].endsWith('compare'))) {
+  run().catch((err) => {
+    console.error(err.message || err);
+    process.exit(1);
+  });
 }
-
-main().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});

package/scripts/curate-wave25.js

@@ -18,7 +18,7 @@ import { join, basename } from 'path';
 
 const REPO_ROOT = new URL("..", import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1");
 const GAME = process.argv.find((a, i) => process.argv[i - 1] === '--game') || 'star-freight';
-const GAME_ROOT = join(REPO_ROOT, 'games', GAME);
+const GAME_ROOT = join(REPO_ROOT, 'projects', GAME);
 
 const RECORDS_DIR = join(GAME_ROOT, 'records');
 const CANDIDATES_DIR = join(GAME_ROOT, 'outputs', 'candidates');

package/scripts/curate.js

@@ -7,32 +7,47 @@
  *   node scripts/curate.js <asset_id> approved "Clean silhouette, correct palette" --scores silhouette:0.9,palette:0.8
  *   node scripts/curate.js <asset_id> rejected "3D render look, alpha halo" --failures alpha_halo,3d_render_look
  *   node scripts/curate.js --list  (show uncurated candidates)
+ *   sdlab curate <asset_id> approved "explanation" --project star-freight
  */
 
 import { readFile, writeFile, rename, readdir, mkdir } from "node:fs/promises";
 import { join } from "node:path";
+import { getProjectName } from "../lib/args.js";
+import { REPO_ROOT } from "../lib/paths.js";
 
-const REPO_ROOT = new URL("..", import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1");
-const GAME = process.argv.find((a, i) => process.argv[i - 1] === '--game') || 'star-freight';
-const GAME_ROOT = join(REPO_ROOT, 'games', GAME);
+function getFlagValue(args, flag) {
+  const prefix = `--${flag}=`;
+  for (const a of args) {
+    if (a.startsWith(prefix)) return a.slice(prefix.length);
+  }
+  const idx = args.indexOf(`--${flag}`);
+  if (idx !== -1 && idx + 1 < args.length) return args[idx + 1];
+  return undefined;
+}
 
-async function main() {
-  const args = process.argv.slice(2);
+export async function run(argv = process.argv.slice(2)) {
+  const projectName = getProjectName(argv);
+  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
+
+  // Strip --project/--game and their values from positional parsing
+  const args = argv.filter((a, i) => {
+    if (a === '--project' || a === '--game') return false;
+    if (i > 0 && (argv[i - 1] === '--project' || argv[i - 1] === '--game')) return false;
+    return true;
+  });
 
   if (args.includes("--list")) {
-    return listUncurated();
+    return listUncurated(GAME_ROOT);
   }
 
   const [assetId, status, explanation, ...rest] = args;
 
   if (!assetId || !status || !explanation) {
-    console.log("Usage: node scripts/curate.js <asset_id> <approved|rejected|borderline> <explanation> [--scores k:v,...] [--failures f1,f2]");
-    process.exit(1);
+    throw new Error("Usage: sdlab curate <asset_id> <approved|rejected|borderline> <explanation> [--scores k:v,...] [--failures f1,f2]");
   }
 
   if (!["approved", "rejected", "borderline"].includes(status)) {
-    console.error(`Invalid status: ${status}. Must be approved, rejected, or borderline.`);
-    process.exit(1);
+    throw new Error(`Invalid status: ${status}. Must be approved, rejected, or borderline.`);
   }
 
   // Parse optional flags
@@ -56,8 +71,7 @@ async function main() {
   try {
     record = JSON.parse(await readFile(recordPath, "utf-8"));
   } catch {
-    console.error(`Record not found: ${recordPath}`);
-    process.exit(1);
+    throw new Error(`Record not found: ${recordPath}`);
   }
 
   // Update record first (write before move to avoid orphaned images)
@@ -84,8 +98,7 @@ async function main() {
   try {
     await rename(oldPath, join(GAME_ROOT, newPath));
   } catch {
-    console.error(`Could not move ${oldPath} to ${newPath}`);
-    process.exit(1);
+    throw new Error(`Could not move ${oldPath} to ${newPath}`);
   }
 
   console.log(`\x1b[32m✓\x1b[0m ${assetId} → ${status}`);
@@ -93,7 +106,7 @@ async function main() {
   if (failure_modes.length) console.log(`  Failures: ${failure_modes.join(", ")}`);
 }
 
-async function listUncurated() {
+async function listUncurated(GAME_ROOT) {
   const recordsDir = join(GAME_ROOT, "records");
   let files;
   try {
@@ -120,17 +133,10 @@ async function listUncurated() {
   console.log(`\n${uncurated} uncurated, ${curated} curated`);
 }
 
-function getFlagValue(args, flag) {
-  const prefix = `--${flag}=`;
-  for (const a of args) {
-    if (a.startsWith(prefix)) return a.slice(prefix.length);
-  }
-  const idx = args.indexOf(`--${flag}`);
-  if (idx !== -1 && idx + 1 < args.length) return args[idx + 1];
-  return undefined;
+// Direct execution guard
+if (process.argv[1] && (process.argv[1].endsWith('curate.js') || process.argv[1].endsWith('curate'))) {
+  run().catch((err) => {
+    console.error(err.message || err);
+    process.exit(1);
+  });
 }
-
-main().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});

package/scripts/doctor.js

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+
+/**
+ * doctor.js — Validate project config completeness and correctness.
+ *
+ * Checks structural health without deep business logic linting.
+ * Every check produces a specific, actionable message on failure.
+ *
+ * Usage:
+ *   sdlab project doctor --project star-freight
+ *   node scripts/doctor.js --project my-project
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { getProjectName } from '../lib/args.js';
+import { REPO_ROOT } from '../lib/paths.js';
+
+const REQUIRED_CONFIG_FILES = [
+  'project.json',
+  'constitution.json',
+  'lanes.json',
+  'rubric.json',
+  'terminology.json',
+];
+
+const REQUIRED_DIRS = [
+  'canon',
+  'records',
+  'comparisons',
+  'inputs/prompts',
+  'outputs/candidates',
+  'outputs/approved',
+  'outputs/rejected',
+  'exports',
+  'snapshots',
+  'splits',
+  'eval-packs',
+];
+
+function pass(msg) { console.log(`  \x1b[32m✓\x1b[0m ${msg}`); }
+function fail(msg) { console.log(`  \x1b[31m✗\x1b[0m ${msg}`); }
+function warn(msg) { console.log(`  \x1b[33m⚠\x1b[0m ${msg}`); }
+
+function tryParseJson(filePath) {
+  try {
+    return { data: JSON.parse(readFileSync(filePath, 'utf-8')), error: null };
+  } catch (err) {
+    return { data: null, error: err.message };
+  }
+}
+
+export async function run(argv = process.argv.slice(2)) {
+  const projectName = getProjectName(argv);
+  const projectDir = join(REPO_ROOT, 'projects', projectName);
+
+  console.log(`\x1b[1msdlab project doctor\x1b[0m — ${projectName}`);
+  console.log(`  Path: ${projectDir}\n`);
+
+  let passes = 0;
+  let failures = 0;
+  let warnings = 0;
+
+  // ── 1. Project directory exists ──
+  if (!existsSync(projectDir)) {
+    fail(`Project directory not found: ${projectDir}`);
+    console.log(`\n  Run: sdlab init ${projectName} --domain <domain>`);
+    return;
+  }
+  pass('Project directory exists');
+  passes++;
+
+  // ── 2. Required config files present and parseable ──
+  console.log('');
+  const configs = {};
+  for (const file of REQUIRED_CONFIG_FILES) {
+    const filePath = join(projectDir, file);
+    if (!existsSync(filePath)) {
+      fail(`Missing: ${file}`);
+      failures++;
+      continue;
+    }
+    const { data, error } = tryParseJson(filePath);
+    if (error) {
+      fail(`${file} — invalid JSON: ${error}`);
+      failures++;
+      continue;
+    }
+    configs[file] = data;
+    pass(`${file} — valid JSON`);
+    passes++;
+  }
+
+  // ── 3. Required directories ──
+  console.log('');
+  for (const dir of REQUIRED_DIRS) {
+    if (existsSync(join(projectDir, dir))) {
+      pass(`${dir}/`);
+      passes++;
+    } else {
+      warn(`${dir}/ — missing (will be created on first use)`);
+      warnings++;
+    }
+  }
+
+  // ── 4. Project.json validation ──
+  const meta = configs['project.json'];
+  if (meta) {
+    console.log('');
+    if (meta.name) { pass(`project.json: name = "${meta.name}"`); passes++; }
+    else { fail('project.json: missing "name"'); failures++; }
+
+    if (meta.domain) { pass(`project.json: domain = "${meta.domain}"`); passes++; }
+    else { warn('project.json: no "domain" set'); warnings++; }
+  }
+
+  // ── 5. Constitution validation ──
+  const constitution = configs['constitution.json'];
+  if (constitution) {
+    console.log('');
+    const rules = constitution.rules || (Array.isArray(constitution) ? constitution : []);
+    if (rules.length === 0) {
+      fail('constitution.json: no rules defined');
+      failures++;
+    } else {
+      pass(`constitution.json: ${rules.length} rules`);
+      passes++;
+
+      // Check required rule fields
+      const ruleIds = new Set();
+      let ruleErrors = 0;
+      for (const rule of rules) {
+        if (!rule.id) { fail(`constitution.json: rule missing "id"`); ruleErrors++; continue; }
+        if (ruleIds.has(rule.id)) { fail(`constitution.json: duplicate rule ID "${rule.id}"`); ruleErrors++; }
+        ruleIds.add(rule.id);
+        if (!rule.dims || rule.dims.length === 0) {
+          fail(`constitution.json: rule ${rule.id} has no "dims" (scoring dimensions)`);
+          ruleErrors++;
+        }
+      }
+      if (ruleErrors === 0) { pass('constitution.json: all rules have id + dims'); passes++; }
+      else { failures += ruleErrors; }
+    }
+  }
+
+  // ── 6. Lanes validation ──
+  const lanes = configs['lanes.json'];
+  if (lanes) {
+    console.log('');
+    const laneList = lanes.lanes || [];
+    if (laneList.length === 0) {
+      warn('lanes.json: no lanes defined (default lane only)');
+      warnings++;
+    } else {
+      pass(`lanes.json: ${laneList.length} lanes`);
+      passes++;
+
+      // Check lane IDs unique
+      const laneIds = new Set();
+      let laneErrors = 0;
+      for (const lane of laneList) {
+        if (!lane.id) { fail('lanes.json: lane missing "id"'); laneErrors++; continue; }
+        if (laneIds.has(lane.id)) { fail(`lanes.json: duplicate lane ID "${lane.id}"`); laneErrors++; }
+        laneIds.add(lane.id);
+
+        // Check patterns compile
+        for (const pattern of lane.id_patterns || []) {
+          try { new RegExp(pattern); }
+          catch { fail(`lanes.json: lane "${lane.id}" has invalid pattern "${pattern}"`); laneErrors++; }
+        }
+      }
+      if (laneErrors === 0) { pass('lanes.json: all lane IDs unique, patterns compile'); passes++; }
+      else { failures += laneErrors; }
+    }
+
+    if (!lanes.default_lane) {
+      warn('lanes.json: no "default_lane" set');
+      warnings++;
+    }
+  }
+
+  // ── 7. Rubric validation ──
+  const rubric = configs['rubric.json'];
+  if (rubric) {
+    console.log('');
+    const dims = rubric.dimensions || [];
+    if (dims.length === 0) {
+      fail('rubric.json: no dimensions defined');
+      failures++;
+    } else {
+      pass(`rubric.json: ${dims.length} dimensions`);
+      passes++;
+    }
+
+    if (!rubric.thresholds) {
+      fail('rubric.json: missing "thresholds"');
+      failures++;
+    } else {
+      pass('rubric.json: thresholds present');
+      passes++;
+    }
+
+    // Cross-reference: constitution dims should exist in rubric
+    if (constitution && dims.length > 0) {
+      const dimSet = new Set(dims);
+      const rules = constitution.rules || [];
+      const missingDims = new Set();
+      for (const rule of rules) {
+        for (const d of rule.dims || []) {
+          if (!dimSet.has(d)) missingDims.add(d);
+        }
+      }
+      if (missingDims.size > 0) {
+        fail(`rubric.json: constitution references dimensions not in rubric: ${[...missingDims].join(', ')}`);
+        failures++;
+      } else {
+        pass('rubric.json: all constitution dimensions present in rubric');
+        passes++;
+      }
+    }
+
+    // Check failure_to_rules references valid rule IDs
+    if (rubric.failure_to_rules && constitution) {
+      const ruleIds = new Set((constitution.rules || []).map(r => r.id));
+      let badRefs = 0;
+      for (const [mode, ruleList] of Object.entries(rubric.failure_to_rules)) {
+        for (const ruleId of ruleList) {
+          if (!ruleIds.has(ruleId)) {
+            fail(`rubric.json: failure mode "${mode}" references unknown rule "${ruleId}"`);
+            badRefs++;
+          }
+        }
+      }
+      if (badRefs === 0 && Object.keys(rubric.failure_to_rules).length > 0) {
+        pass(`rubric.json: ${Object.keys(rubric.failure_to_rules).length} failure modes, all reference valid rules`);
+        passes++;
+      }
+      if (badRefs > 0) failures += badRefs;
+    }
+  }
+
+  // ── 8. Terminology validation ──
+  const terminology = configs['terminology.json'];
+  if (terminology) {
+    console.log('');
+    const groups = Object.keys(terminology.groups || {});
+    if (groups.length === 0) {
+      pass('terminology.json: no groups defined (valid for projects without faction/group system)');
+      passes++;
+    } else {
+      pass(`terminology.json: ${groups.length} groups (${groups.join(', ')})`);
+      passes++;
+
+      // Check detection order references valid groups
+      for (const orderKey of ['id_detection_order', 'prompt_detection_order']) {
+        const order = terminology[orderKey] || [];
+        for (const name of order) {
+          if (!terminology.groups[name]) {
+            fail(`terminology.json: ${orderKey} references unknown group "${name}"`);
+            failures++;
+          }
+        }
+      }
+
+      // Check group patterns compile
+      let patternErrors = 0;
+      for (const [gName, group] of Object.entries(terminology.groups)) {
+        for (const pattern of group.id_patterns || []) {
+          try { new RegExp(pattern); }
+          catch { fail(`terminology.json: group "${gName}" has invalid id_pattern "${pattern}"`); patternErrors++; }
+        }
+        for (const pattern of group.prompt_patterns || []) {
+          try { new RegExp(pattern); }
+          catch { fail(`terminology.json: group "${gName}" has invalid prompt_pattern "${pattern}"`); patternErrors++; }
+        }
+      }
+      if (patternErrors === 0) { pass('terminology.json: all detection patterns compile'); passes++; }
+      else { failures += patternErrors; }
+    }
+  }
+
+  // ── 9. Records sanity check ──
+  const recordsDir = join(projectDir, 'records');
+  if (existsSync(recordsDir)) {
+    console.log('');
+    const recordFiles = readdirSync(recordsDir).filter(f => f.endsWith('.json'));
+    if (recordFiles.length > 0) {
+      // Spot-check first 3 records
+      let recordErrors = 0;
+      const sample = recordFiles.slice(0, 3);
+      for (const f of sample) {
+        const { data, error } = tryParseJson(join(recordsDir, f));
+        if (error) { fail(`records/${f}: invalid JSON`); recordErrors++; }
+        else if (!data.id) { fail(`records/${f}: missing "id"`); recordErrors++; }
+      }
+      if (recordErrors === 0) {
+        pass(`${recordFiles.length} records (spot-check passed)`);
+        passes++;
+      } else {
+        failures += recordErrors;
+      }
+    } else {
+      pass('records/ — empty (new project)');
+      passes++;
+    }
+  }
+
+  // ── Summary ──
+  console.log('');
+  const status = failures === 0 ? '\x1b[32mHEALTHY\x1b[0m' : '\x1b[31mFAILED\x1b[0m';
+  console.log(`═══ ${status} — ${passes} passed, ${failures} failed, ${warnings} warnings ═══`);
+
+  if (failures > 0) {
+    throw new Error(`Project "${projectName}" has ${failures} issue(s).`);
+  }
+}
+
+// Direct execution guard
+if (process.argv[1] && (process.argv[1].endsWith('doctor.js') || process.argv[1].endsWith('doctor'))) {
+  run().catch((err) => {
+    console.error(err.message || err);
+    process.exit(1);
+  });
+}