@mcptoolshop/style-dataset-lab 3.0.0 → 3.0.1

package/scripts/curate.js

@@ -7,59 +7,73 @@
  *   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
+ *   sdlab curate <asset_id> approved "explanation" --project star-freight [--dry-run]
  */
 
-import { readFile, writeFile, rename, readdir, mkdir } from "node:fs/promises";
+import { writeFile, rename, readdir, mkdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { getProjectName } from "../lib/args.js";
+import { parseArgs, getProjectName } from "../lib/args.js";
 import { REPO_ROOT } from "../lib/paths.js";
-
-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;
-}
+import { readJsonFile } from "../lib/config.js";
+import { inputError, runtimeError, handleCliError } from "../lib/errors.js";
+import { result } from "../lib/log.js";
 
 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;
+  const { flags, positionals } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      scores: { type: 'string' },
+      failures: { type: 'string' },
+      notes: { type: 'string' },
+      list: { type: 'boolean', default: false },
+      'dry-run': { type: 'boolean', default: false },
+    },
+    deprecated: { game: 'project' },
   });
 
-  if (args.includes("--list")) {
+  const projectName = flags.project || getProjectName(argv);
+  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
+  const dryRun = flags['dry-run'] || flags.dryRun;
+
+  if (flags.list) {
     return listUncurated(GAME_ROOT);
   }
 
-  const [assetId, status, explanation, ...rest] = args;
+  const [assetId, status, explanation] = positionals;
 
   if (!assetId || !status || !explanation) {
-    throw new Error("Usage: sdlab curate <asset_id> <approved|rejected|borderline> <explanation> [--scores k:v,...] [--failures f1,f2]");
+    throw inputError(
+      'INPUT_MISSING_ARGS',
+      'Usage: sdlab curate <asset_id> <approved|rejected|borderline> <explanation> [--scores k:v,...] [--failures f1,f2] [--dry-run]'
+    );
   }
 
   if (!["approved", "rejected", "borderline"].includes(status)) {
-    throw new Error(`Invalid status: ${status}. Must be approved, rejected, or borderline.`);
+    throw inputError(
+      'INPUT_BAD_STATUS',
+      `Invalid status: ${status}. Must be approved, rejected, or borderline.`
+    );
   }
 
-  // Parse optional flags
-  const scoresStr = getFlagValue(rest, "scores");
-  const failuresStr = getFlagValue(rest, "failures");
-  const notesStr = getFlagValue(rest, "notes");
+  const scoresStr = flags.scores;
+  const failuresStr = flags.failures;
+  const notesStr = flags.notes;
 
   const criteria_scores = {};
   if (scoresStr) {
     for (const pair of scoresStr.split(",")) {
       const [k, v] = pair.split(":");
-      if (k && v) criteria_scores[k.trim()] = parseFloat(v);
+      if (k && v) {
+        const score = parseFloat(v);
+        if (!Number.isFinite(score)) {
+          throw inputError(
+            'INPUT_BAD_SCORE',
+            `Score value for "${k.trim()}" is not a number: "${v}"`,
+            'Use the form --scores silhouette:0.9,palette:0.8'
+          );
+        }
+        criteria_scores[k.trim()] = score;
+      }
     }
   }
 
@@ -69,17 +83,44 @@ export async function run(argv = process.argv.slice(2)) {
   const recordPath = join(GAME_ROOT, `records/${assetId}.json`);
   let record;
   try {
-    record = JSON.parse(await readFile(recordPath, "utf-8"));
-  } catch {
-    throw new Error(`Record not found: ${recordPath}`);
+    record = await readJsonFile(recordPath);
+  } catch (err) {
+    if (err && err.code === 'INPUT_FILE_NOT_FOUND') {
+      throw inputError('INPUT_UNKNOWN_RECORD', `Record not found: ${recordPath}`);
+    }
+    throw err;
   }
 
-  // Update record first (write before move to avoid orphaned images)
-  const oldPath = join(GAME_ROOT, record.asset_path);
+  const originalAssetPath = record.asset_path;
+  const oldPath = join(GAME_ROOT, originalAssetPath);
   const newDir = `outputs/${status}`;
   const newPath = `${newDir}/${assetId}.png`;
+  const newFullPath = join(GAME_ROOT, newPath);
+
+  if (dryRun) {
+    console.log(`\x1b[33m(dry-run)\x1b[0m ${assetId}`);
+    console.log(`  status: ${status}`);
+    console.log(`  move:   ${originalAssetPath} -> ${newPath}`);
+    console.log(`  note:   ${explanation}`);
+    if (failure_modes.length) console.log(`  failures: ${failure_modes.join(", ")}`);
+    return;
+  }
+
   await mkdir(join(GAME_ROOT, newDir), { recursive: true });
 
+  // Move image FIRST — if the rename fails we still have a clean record.
+  try {
+    await rename(oldPath, newFullPath);
+  } catch (err) {
+    throw runtimeError(
+      'RUNTIME_MOVE_FAILED',
+      `Could not move ${oldPath} to ${newPath}: ${err.message}`,
+      'Check that the source image exists and the destination is writable.',
+      err
+    );
+  }
+
+  // Now safely update the record. If writing fails, try to restore the image.
   record.asset_path = newPath;
   record.judgment = {
     status,
@@ -92,16 +133,23 @@ export async function run(argv = process.argv.slice(2)) {
     confidence: 0.9,
   };
 
-  await writeFile(recordPath, JSON.stringify(record, null, 2));
-
-  // Move image file
   try {
-    await rename(oldPath, join(GAME_ROOT, newPath));
-  } catch {
-    throw new Error(`Could not move ${oldPath} to ${newPath}`);
+    await writeFile(recordPath, JSON.stringify(record, null, 2));
+  } catch (err) {
+    // Attempt rollback: put the image back.
+    try { await rename(newFullPath, oldPath); } catch {}
+    throw runtimeError(
+      'RUNTIME_WRITE_FAILED',
+      `Could not write record ${recordPath}: ${err.message}`,
+      null,
+      err
+    );
   }
 
-  console.log(`\x1b[32m✓\x1b[0m ${assetId} → ${status}`);
+  // Final artifact path — always shown, even under --quiet.
+  result('curate', `${assetId} → ${status}`);
+  result(`  image: ${newPath}`);
+  result(`  record: records/${assetId}.json`);
   console.log(`  ${explanation}`);
   if (failure_modes.length) console.log(`  Failures: ${failure_modes.join(", ")}`);
 }
@@ -135,8 +183,5 @@ async function listUncurated(GAME_ROOT) {
 
 // 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);
-  });
+  run().catch(handleCliError);
 }

package/scripts/doctor.js

@@ -15,6 +15,7 @@ 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';
+import { runtimeError, handleCliError } from '../lib/errors.js';
 
 const REQUIRED_CONFIG_FILES = [
   'project.json',
@@ -484,14 +485,11 @@ export async function run(argv = process.argv.slice(2)) {
   console.log(`═══ ${status} — ${passes} passed, ${failures} failed, ${warnings} warnings ═══`);
 
   if (failures > 0) {
-    throw new Error(`Project "${projectName}" has ${failures} issue(s).`);
+    throw runtimeError('PROJECT_UNHEALTHY', `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);
-  });
+  run().catch(handleCliError);
 }

package/scripts/eligibility.js

@@ -4,36 +4,44 @@
  * eligibility.js — Audit training/eval eligibility for all project records.
  *
  * Usage:
- *   sdlab eligibility audit [--project <name>]
+ *   sdlab eligibility audit [--project <name>] [--profile <id>]
  */
 
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { getProjectName } from '../lib/args.js';
+import { parseArgs, getProjectName } from '../lib/args.js';
 import { REPO_ROOT } from '../lib/paths.js';
 import { loadProjectConfig, loadSelectionProfile } from '../lib/config.js';
+import { handleCliError } from '../lib/errors.js';
 import { evaluateEligibility, categorizeExclusions } from '../lib/eligibility.js';
 
 export async function run(argv = process.argv.slice(2)) {
-  const projectName = getProjectName(argv);
+  const { flags } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      profile: { type: 'string' },
+    },
+    deprecated: { game: 'project' },
+    allowUnknown: true,
+  });
+
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = join(REPO_ROOT, 'projects', projectName);
 
-  const profileIdx = argv.indexOf('--profile');
-  const profileId = profileIdx >= 0 ? argv[profileIdx + 1] : null;
-  const profile = loadSelectionProfile(projectRoot, profileId);
+  const profile = loadSelectionProfile(projectRoot, flags.profile);
   const config = loadProjectConfig(projectRoot);
 
   const recordsDir = join(projectRoot, 'records');
   const files = (await readdir(recordsDir)).filter(f => f.endsWith('.json')).sort();
 
   console.log(`\x1b[1msdlab eligibility audit\x1b[0m — ${projectName}`);
-  console.log(`  Profile: ${profileId || 'training-default (built-in)'}`);
+  console.log(`  Profile: ${flags.profile || 'training-default (built-in)'}`);
   console.log(`  Records: ${files.length}`);
   console.log('');
 
   const eligible = [];
   const excluded = [];
-  const nearMiss = []; // Records with exactly 1 failing reason
+  const nearMiss = [];
 
   for (const file of files) {
     const raw = await readFile(join(recordsDir, file), 'utf-8');
@@ -55,7 +63,6 @@ export async function run(argv = process.argv.slice(2)) {
   console.log(`  \x1b[31m✗\x1b[0m Excluded: ${excluded.length}`);
   console.log('');
 
-  // Categorize exclusions
   const categories = categorizeExclusions(excluded);
   console.log('  Exclusion breakdown:');
   for (const [cat, count] of Object.entries(categories)) {
@@ -65,7 +72,6 @@ export async function run(argv = process.argv.slice(2)) {
     }
   }
 
-  // Near-miss improvement opportunities
   if (nearMiss.length > 0) {
     console.log(`\n  Improvement opportunities (${nearMiss.length} records with 1 failing check):`);
     const byReason = {};
@@ -84,8 +90,5 @@ export async function run(argv = process.argv.slice(2)) {
 
 // Direct execution guard
 if (process.argv[1] && (process.argv[1].endsWith('eligibility.js') || process.argv[1].endsWith('eligibility'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }

package/scripts/eval-pack.js

@@ -11,15 +11,20 @@
 
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { getProjectName } from '../lib/args.js';
+import { parseArgs, getProjectName } from '../lib/args.js';
 import { REPO_ROOT } from '../lib/paths.js';
+import { inputError, handleCliError } from '../lib/errors.js';
 import { buildEvalPack, listEvalPacks, loadEvalPack } from '../lib/eval-pack.js';
 
 export async function run(argv = process.argv.slice(2)) {
-  const projectName = getProjectName(argv);
+  const { flags, positionals } = parseArgs(argv, {
+    flags: { project: { type: 'string' } },
+    deprecated: { game: 'project' },
+  });
+
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = join(REPO_ROOT, 'projects', projectName);
-  const subcommand = argv.find(a => !a.startsWith('--')) || 'list';
-  const args = argv.filter(a => a !== subcommand);
+  const subcommand = positionals[0] || 'list';
 
   if (subcommand === 'build') {
     console.log(`\x1b[1msdlab eval-pack build\x1b[0m — ${projectName}\n`);
@@ -48,8 +53,8 @@ export async function run(argv = process.argv.slice(2)) {
     }
 
   } else if (subcommand === 'show') {
-    const evalId = args.find(a => a.startsWith('eval-'));
-    if (!evalId) throw new Error('Usage: sdlab eval-pack show <eval-id>');
+    const evalId = positionals.find(a => a.startsWith('eval-'));
+    if (!evalId) throw inputError('INPUT_MISSING_ARGS', 'Usage: sdlab eval-pack show <eval-id>');
 
     const manifest = await loadEvalPack(projectRoot, evalId);
     console.log(`\x1b[1mEval pack\x1b[0m — ${evalId}\n`);
@@ -80,13 +85,10 @@ export async function run(argv = process.argv.slice(2)) {
     }
 
   } else {
-    throw new Error(`Unknown subcommand: ${subcommand}. Use: build, list, show`);
+    throw inputError('INPUT_BAD_SUBCOMMAND', `Unknown subcommand: ${subcommand}. Use: build, list, show`);
   }
 }
 
 if (process.argv[1] && (process.argv[1].endsWith('eval-pack.js') || process.argv[1].endsWith('eval-pack'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }

package/scripts/eval-run.js

@@ -10,40 +10,42 @@
  *   sdlab eval-run list [--project <name>]
  */
 
-import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { getProjectName } from '../lib/args.js';
-import { REPO_ROOT } from '../lib/paths.js';
+import { parseArgs, getProjectName } from '../lib/args.js';
+import { REPO_ROOT, resolveSafeProjectPath } from '../lib/paths.js';
+import { inputError, handleCliError } from '../lib/errors.js';
 import { listTrainingManifests } from '../lib/training-manifests.js';
 import { listEvalPacks } from '../lib/eval-pack.js';
 import { createEvalRun, scoreEvalRun, loadEvalRun, listEvalRuns } from '../lib/eval-runs.js';
 
 export async function run(argv = process.argv.slice(2)) {
-  const projectName = getProjectName(argv);
+  const { flags, positionals } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      manifest: { type: 'string' },
+      'eval-pack': { type: 'string' },
+      outputs: { type: 'string' },
+    },
+    deprecated: { game: 'project' },
+  });
+
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = join(REPO_ROOT, 'projects', projectName);
-  const subcommand = argv.find(a => !a.startsWith('--') && !a.startsWith('er-')) || 'list';
-  const args = argv.filter(a => a !== subcommand);
+  // First non-flag positional that isn't an er-id is the subcommand
+  const subcommand = positionals.find(a => !a.startsWith('er-')) || 'list';
 
   if (subcommand === 'create') {
-    // Find manifest
-    let manifestId;
-    const manifestIdx = args.indexOf('--manifest');
-    if (manifestIdx >= 0) {
-      manifestId = args[manifestIdx + 1];
-    } else {
+    let manifestId = flags.manifest;
+    if (!manifestId) {
       const manifests = await listTrainingManifests(projectRoot);
-      if (manifests.length === 0) throw new Error('No training manifests. Run: sdlab training-manifest create');
+      if (manifests.length === 0) throw inputError('INPUT_NO_MANIFEST', 'No training manifests. Run: sdlab training-manifest create');
       manifestId = manifests[manifests.length - 1].id;
     }
 
-    // Find eval pack
-    let evalPackId;
-    const evalIdx = args.indexOf('--eval-pack');
-    if (evalIdx >= 0) {
-      evalPackId = args[evalIdx + 1];
-    } else {
+    let evalPackId = flags['eval-pack'] || flags.evalPack;
+    if (!evalPackId) {
       const packs = await listEvalPacks(projectRoot);
-      if (packs.length === 0) throw new Error('No eval packs. Run: sdlab eval-pack build');
+      if (packs.length === 0) throw inputError('INPUT_NO_EVALPACK', 'No eval packs. Run: sdlab eval-pack build');
       evalPackId = packs[packs.length - 1].id;
     }
 
@@ -57,12 +59,11 @@ export async function run(argv = process.argv.slice(2)) {
     console.log(`  Status: created (use "sdlab eval-run score" to score outputs)`);
 
   } else if (subcommand === 'score') {
-    const evalRunId = args.find(a => a.startsWith('er-'));
-    if (!evalRunId) throw new Error('Usage: sdlab eval-run score <eval-run-id> --outputs <path>');
+    const evalRunId = positionals.find(a => a.startsWith('er-'));
+    if (!evalRunId) throw inputError('INPUT_MISSING_ARGS', 'Usage: sdlab eval-run score <eval-run-id> --outputs <path>');
 
-    const outputsIdx = args.indexOf('--outputs');
-    if (outputsIdx < 0) throw new Error('--outputs <path> is required (JSONL with record_id, accept, notes)');
-    const outputsPath = args[outputsIdx + 1];
+    if (!flags.outputs) throw inputError('INPUT_MISSING_FLAG', '--outputs <path> is required (JSONL with record_id, accept, notes)');
+    const outputsPath = resolveSafeProjectPath(projectRoot, flags.outputs, { baseRoot: REPO_ROOT, flagName: 'outputs' });
 
     console.log(`\x1b[1msdlab eval-run score\x1b[0m — ${evalRunId}\n`);
 
@@ -80,8 +81,8 @@ export async function run(argv = process.argv.slice(2)) {
     }
 
   } else if (subcommand === 'show') {
-    const evalRunId = args.find(a => a.startsWith('er-'));
-    if (!evalRunId) throw new Error('Usage: sdlab eval-run show <eval-run-id>');
+    const evalRunId = positionals.find(a => a.startsWith('er-'));
+    if (!evalRunId) throw inputError('INPUT_MISSING_ARGS', 'Usage: sdlab eval-run show <eval-run-id>');
 
     const run = await loadEvalRun(projectRoot, evalRunId);
     console.log(`\x1b[1mEval run\x1b[0m — ${evalRunId}\n`);
@@ -112,10 +113,10 @@ export async function run(argv = process.argv.slice(2)) {
     }
 
   } else {
-    throw new Error(`Unknown subcommand: ${subcommand}. Use: create, score, show, list`);
+    throw inputError('INPUT_BAD_SUBCOMMAND', `Unknown subcommand: ${subcommand}. Use: create, score, show, list`);
   }
 }
 
 if (process.argv[1] && (process.argv[1].endsWith('eval-run.js') || process.argv[1].endsWith('eval-run'))) {
-  run().catch((err) => { console.error(err.message || err); process.exit(1); });
+  run().catch(handleCliError);
 }

package/scripts/export.js

@@ -9,53 +9,52 @@
  */
 
 import { join } from 'node:path';
-import { getProjectName } from '../lib/args.js';
+import { parseArgs, getProjectName } from '../lib/args.js';
 import { REPO_ROOT } from '../lib/paths.js';
+import { inputError, handleCliError } from '../lib/errors.js';
 import { listSnapshots } from '../lib/snapshot.js';
 import { listSplits } from '../lib/split.js';
-import { buildExport, listExports, loadExport } from '../lib/export.js';
+import { buildExport, listExports } from '../lib/export.js';
 
 export async function run(argv = process.argv.slice(2)) {
-  const projectName = getProjectName(argv);
+  const { flags, positionals } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      snapshot: { type: 'string' },
+      split: { type: 'string' },
+      profile: { type: 'string' },
+      copy: { type: 'boolean', default: false },
+    },
+    deprecated: { game: 'project' },
+  });
+
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = join(REPO_ROOT, 'projects', projectName);
-  const subcommand = argv.find(a => !a.startsWith('--') && a !== 'true') || 'list';
-  const args = argv.filter(a => a !== subcommand);
+  const subcommand = positionals[0] || 'list';
 
   if (subcommand === 'build') {
-    // Find snapshot
-    let snapshotId;
-    const snapIdx = args.indexOf('--snapshot');
-    if (snapIdx >= 0) {
-      snapshotId = args[snapIdx + 1];
-    } else {
+    let snapshotId = flags.snapshot;
+    if (!snapshotId) {
       const snapshots = await listSnapshots(projectRoot);
-      if (snapshots.length === 0) throw new Error('No snapshots found. Run: sdlab snapshot create');
+      if (snapshots.length === 0) throw inputError('INPUT_NO_SNAPSHOT', '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 {
+    let splitId = flags.split;
+    if (!splitId) {
       const splits = await listSplits(projectRoot);
-      if (splits.length === 0) throw new Error('No splits found. Run: sdlab split build');
+      if (splits.length === 0) throw inputError('INPUT_NO_SPLIT', 'No splits found. Run: sdlab split build');
       splitId = splits[splits.length - 1].id;
     }
 
-    const profileIdx = args.indexOf('--profile');
-    const profileId = profileIdx >= 0 ? args[profileIdx + 1] : null;
-    const copy = args.includes('--copy');
-
     console.log(`\x1b[1msdlab export build\x1b[0m — ${projectName}`);
     console.log(`  Snapshot: ${snapshotId}`);
     console.log(`  Split:    ${splitId}`);
-    console.log(`  Profile:  ${profileId || 'canonical-package (built-in)'}`);
-    console.log(`  Images:   ${copy ? 'copy' : 'symlink'}`);
+    console.log(`  Profile:  ${flags.profile || 'canonical-package (built-in)'}`);
+    console.log(`  Images:   ${flags.copy ? 'copy' : 'symlink'}`);
     console.log('');
 
-    const result = await buildExport(projectRoot, snapshotId, splitId, { profileId, copy });
+    const result = await buildExport(projectRoot, snapshotId, splitId, { profileId: flags.profile, copy: flags.copy });
 
     console.log(`  \x1b[32m✓\x1b[0m Export: ${result.exportId}`);
     console.log(`  Records: ${result.recordCount}`);
@@ -73,13 +72,10 @@ export async function run(argv = process.argv.slice(2)) {
     }
 
   } else {
-    throw new Error(`Unknown subcommand: ${subcommand}. Use: build, list`);
+    throw inputError('INPUT_BAD_SUBCOMMAND', `Unknown subcommand: ${subcommand}. Use: build, list`);
   }
 }
 
 if (process.argv[1] && (process.argv[1].endsWith('export.js') || process.argv[1].endsWith('export'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }