@mcptoolshop/style-dataset-lab 2.2.0 → 2.3.0

package/bin/sdlab.js

@@ -7,6 +7,9 @@
  * Each script exports run(argv) and is lazy-loaded on demand.
  */
 
+import { enableDebug, handleCliError, inputError } from '../lib/errors.js';
+import { setLogLevel } from '../lib/log.js';
+
 const COMMANDS = {
   'init':                '../scripts/init.js',
   'generate':            '../scripts/generate.js',
@@ -99,18 +102,27 @@ function printHelp() {
   console.log('Options:');
   console.log('  --project <name>     Project to operate on (default: star-freight)');
   console.log('  --game <name>        Deprecated alias for --project');
+  console.log('  --debug              Show stack traces on error');
+  console.log('  --verbose            Verbose output');
+  console.log('  --quiet              Suppress non-essential output');
+  console.log('  --dry-run            Preview changes without writing (where supported)');
   console.log('  --help               Show this help');
   console.log('');
   console.log('Examples:');
   console.log('  sdlab init my-project --domain character-design');
-  console.log('  sdlab generate inputs/prompts/wave1.json --project star-freight');
-  console.log('  sdlab bind --stats --project star-freight');
-  console.log('  sdlab project doctor --project star-freight');
+  console.log('  sdlab snapshot create --project star-freight');
+  console.log('  sdlab split build --dry-run --project star-freight');
+  console.log('  sdlab training-package build --debug --project star-freight');
 }
 
 async function main() {
   const args = process.argv.slice(2);
 
+  // Global flags
+  if (args.includes('--debug')) enableDebug();
+  if (args.includes('--verbose')) setLogLevel('verbose');
+  if (args.includes('--quiet')) setLogLevel('quiet');
+
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
     printHelp();
     process.exit(0);
@@ -123,30 +135,18 @@ async function main() {
   if (command === 'project' && args[1] && PROJECT_COMMANDS[args[1]]) {
     commandArgs = args.slice(2);
     const modulePath = PROJECT_COMMANDS[args[1]];
-    try {
-      const mod = await import(modulePath);
-      await mod.run(commandArgs);
-    } catch (err) {
-      console.error(`\x1b[31mError:\x1b[0m ${err.message}`);
-      process.exit(1);
-    }
+    const mod = await import(modulePath);
+    await mod.run(commandArgs);
     return;
   }
 
   const modulePath = COMMANDS[command];
   if (!modulePath) {
-    console.error(`Unknown command: ${command}`);
-    console.error(`Run "sdlab --help" for available commands.`);
-    process.exit(1);
+    throw inputError('INPUT_UNKNOWN_COMMAND', `Unknown command: ${command}`, 'Run "sdlab --help" for available commands.');
   }
 
-  try {
-    const mod = await import(modulePath);
-    await mod.run(commandArgs);
-  } catch (err) {
-    console.error(`\x1b[31mError:\x1b[0m ${err.message}`);
-    process.exit(1);
-  }
+  const mod = await import(modulePath);
+  await mod.run(commandArgs);
 }
 
-main();
+main().catch(handleCliError);

package/lib/errors.js

@@ -0,0 +1,82 @@
+/**
+ * Structured error shape for Style Dataset Lab.
+ *
+ * Every user-facing error has: code, message, hint.
+ * Exit codes: 0 ok, 1 user error, 2 runtime error.
+ */
+
+export class SdlabError extends Error {
+  /**
+   * @param {string} code — error code (e.g. INPUT_MISSING_FLAG)
+   * @param {string} message — human-readable description
+   * @param {Object} options
+   * @param {string} [options.hint] — actionable fix suggestion
+   * @param {Error} [options.cause] — original error
+   * @param {number} [options.exitCode] — 1 (user) or 2 (runtime)
+   */
+  constructor(code, message, { hint, cause, exitCode } = {}) {
+    super(message);
+    this.name = 'SdlabError';
+    this.code = code;
+    this.hint = hint || null;
+    this.cause = cause || null;
+    this.exitCode = exitCode || 1;
+  }
+
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      hint: this.hint,
+    };
+  }
+}
+
+// ─── Convenience constructors ──────────────────────────────────────
+
+export function inputError(code, message, hint) {
+  return new SdlabError(code, message, { hint, exitCode: 1 });
+}
+
+export function runtimeError(code, message, hint, cause) {
+  return new SdlabError(code, message, { hint, cause, exitCode: 2 });
+}
+
+// ─── CLI error handler ─────────────────────────────────────────────
+
+let debugMode = false;
+
+export function enableDebug() {
+  debugMode = true;
+}
+
+export function isDebug() {
+  return debugMode;
+}
+
+/**
+ * Handle an error at the CLI boundary.
+ * Shows structured output by default, stack trace with --debug.
+ */
+export function handleCliError(err) {
+  if (err instanceof SdlabError) {
+    console.error(`\x1b[31mError [${err.code}]:\x1b[0m ${err.message}`);
+    if (err.hint) {
+      console.error(`\x1b[33mHint:\x1b[0m ${err.hint}`);
+    }
+    if (debugMode && err.stack) {
+      console.error('\n' + err.stack);
+    }
+    if (debugMode && err.cause) {
+      console.error('\nCaused by:', err.cause);
+    }
+    process.exit(err.exitCode);
+  } else {
+    // Unstructured error — runtime failure
+    console.error(`\x1b[31mError:\x1b[0m ${err.message || err}`);
+    if (debugMode && err.stack) {
+      console.error('\n' + err.stack);
+    }
+    process.exit(2);
+  }
+}

package/lib/log.js

@@ -0,0 +1,36 @@
+/**
+ * Logging levels for CLI output.
+ *
+ * Levels: quiet < normal < verbose
+ * Set via --quiet or --verbose flags (parsed by caller).
+ */
+
+let level = 'normal'; // quiet | normal | verbose
+
+export function setLogLevel(l) {
+  level = l;
+}
+
+export function getLogLevel() {
+  return level;
+}
+
+/** Always shown (errors, final results). */
+export function log(...args) {
+  console.log(...args);
+}
+
+/** Shown at normal and verbose levels (progress, summaries). */
+export function info(...args) {
+  if (level !== 'quiet') console.log(...args);
+}
+
+/** Shown only at verbose level (per-record details, debug context). */
+export function verbose(...args) {
+  if (level === 'verbose') console.log(...args);
+}
+
+/** Always shown on stderr. */
+export function warn(...args) {
+  console.error('\x1b[33m⚠\x1b[0m', ...args);
+}

package/lib/snapshot.js

@@ -53,7 +53,7 @@ export function computeConfigFingerprint(projectRoot) {
  * @param {Object} profile — selection profile
  * @returns {Promise<{snapshotId: string, included: number, excluded: number}>}
  */
-export async function createSnapshot(projectRoot, profile) {
+export async function createSnapshot(projectRoot, profile, options = {}) {
   const config = loadProjectConfig(projectRoot);
   const recordsDir = join(projectRoot, 'records');
   const snapshotId = generateSnapshotId();
@@ -104,7 +104,10 @@ export async function createSnapshot(projectRoot, profile) {
     }
   }
 
-  // Write snapshot files
+  // Write snapshot files (skip if dry run)
+  if (options.dryRun) {
+    return { snapshotId, included: included.length, excluded: excluded.length };
+  }
   await mkdir(snapshotDir, { recursive: true });
 
   const manifest = {

package/lib/split.js

@@ -127,7 +127,7 @@ function buildAncestorMap(records) {
  * @param {Object} profile — split profile (from loadSplitProfile)
  * @returns {Promise<{splitId: string, train: number, val: number, test: number}>}
  */
-export async function createSplit(projectRoot, snapshotId, profile) {
+export async function createSplit(projectRoot, snapshotId, profile, options = {}) {
   const config = loadProjectConfig(projectRoot);
   const snapshot = await loadSnapshot(projectRoot, snapshotId);
   const includedEntries = await loadSnapshotIncluded(projectRoot, snapshotId);
@@ -242,8 +242,11 @@ export async function createSplit(projectRoot, snapshotId, profile) {
     records, trainRecords, valRecords, testRecords, config.lanes
   );
 
-  // Write output
+  // Write output (skip if dry run)
   const splitId = generateSplitId();
+  if (options.dryRun) {
+    return { splitId, train: trainRecords.length, val: valRecords.length, test: testRecords.length };
+  }
   const splitDir = join(projectRoot, 'splits', splitId);
   await mkdir(splitDir, { recursive: true });
 

package/package.json

@@ -1,20 +1,19 @@
 {
   "name": "@mcptoolshop/style-dataset-lab",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Visual canon and dataset production pipeline — snapshots, splits, versioned exports, eval packs, and canon-bound curation for any image production domain",
   "type": "module",
   "bin": {
     "sdlab": "./bin/sdlab.js"
   },
   "scripts": {
+    "verify": "node bin/sdlab.js --help && node bin/sdlab.js project doctor --project star-freight",
     "generate": "node scripts/generate.js",
     "curate": "node scripts/curate.js",
     "compare": "node scripts/compare.js",
     "canon-bind": "node scripts/canon-bind.js",
     "painterly": "node scripts/painterly.js",
-    "generate:identity": "node scripts/generate-identity.js",
-    "export": "echo 'Usage: repo-dataset visual generate ./projects/<project> --format trl'",
-    "inspect": "echo 'Usage: repo-dataset visual inspect ./projects/<project>'"
+    "generate:identity": "node scripts/generate-identity.js"
   },
   "files": [
     "bin/",

package/scripts/snapshot.js

@@ -32,39 +32,43 @@ export async function run(argv = process.argv.slice(2)) {
     const profileIdx = args.indexOf('--profile');
     const profileId = profileIdx >= 0 ? args[profileIdx + 1] : null;
     const profile = loadSelectionProfile(projectRoot, profileId);
+    const dryRun = argv.includes('--dry-run');
 
     console.log(`\x1b[1msdlab snapshot create\x1b[0m — ${projectName}`);
     console.log(`  Profile: ${profileId || 'training-default (built-in)'}`);
+    if (dryRun) console.log('  Mode: DRY RUN (no files written)');
     console.log('');
 
-    const result = await createSnapshot(projectRoot, profile);
+    const result = await createSnapshot(projectRoot, profile, { dryRun });
 
     console.log(`  \x1b[32m✓\x1b[0m Snapshot: ${result.snapshotId}`);
     console.log(`  Included: ${result.included}`);
     console.log(`  Excluded: ${result.excluded}`);
 
-    // Read and display summary
-    const summary = JSON.parse(
-      await readFile(join(projectRoot, 'snapshots', result.snapshotId, 'summary.json'), 'utf-8')
-    );
-    console.log('\n  Lane distribution:');
-    for (const [lane, count] of Object.entries(summary.lane_distribution).sort((a, b) => b[1] - a[1])) {
-      console.log(`    ${lane}: ${count}`);
-    }
-    console.log('\n  Faction distribution:');
-    for (const [f, c] of Object.entries(summary.faction_distribution).sort((a, b) => b[1] - a[1])) {
-      console.log(`    ${f}: ${c}`);
-    }
-
-    // Read and categorize exclusions
-    const excludedRaw = await readFile(
-      join(projectRoot, 'snapshots', result.snapshotId, 'excluded.jsonl'), 'utf-8'
-    );
-    const excluded = excludedRaw.trim().split('\n').filter(Boolean).map(l => JSON.parse(l));
-    const categories = categorizeExclusions(excluded);
-    console.log('\n  Exclusion reasons:');
-    for (const [cat, count] of Object.entries(categories)) {
-      if (count > 0) console.log(`    ${cat}: ${count}`);
+    if (!dryRun) {
+      // Read and display summary
+      const summary = JSON.parse(
+        await readFile(join(projectRoot, 'snapshots', result.snapshotId, 'summary.json'), 'utf-8')
+      );
+      console.log('\n  Lane distribution:');
+      for (const [lane, count] of Object.entries(summary.lane_distribution).sort((a, b) => b[1] - a[1])) {
+        console.log(`    ${lane}: ${count}`);
+      }
+      console.log('\n  Faction distribution:');
+      for (const [f, c] of Object.entries(summary.faction_distribution).sort((a, b) => b[1] - a[1])) {
+        console.log(`    ${f}: ${c}`);
+      }
+
+      // Read and categorize exclusions
+      const excludedRaw = await readFile(
+        join(projectRoot, 'snapshots', result.snapshotId, 'excluded.jsonl'), 'utf-8'
+      );
+      const excluded = excludedRaw.trim().split('\n').filter(Boolean).map(l => JSON.parse(l));
+      const categories = categorizeExclusions(excluded);
+      console.log('\n  Exclusion reasons:');
+      for (const [cat, count] of Object.entries(categories)) {
+        if (count > 0) console.log(`    ${cat}: ${count}`);
+      }
     }
 
   } else if (subcommand === 'list') {

package/scripts/split.js

@@ -42,6 +42,7 @@ export async function run(argv = process.argv.slice(2)) {
     const profileIdx = args.indexOf('--profile');
     const profileId = profileIdx >= 0 ? args[profileIdx + 1] : null;
     const profile = loadSplitProfile(projectRoot, profileId);
+    const dryRun = argv.includes('--dry-run');
 
     console.log(`\x1b[1msdlab split build\x1b[0m — ${projectName}`);
     console.log(`  Snapshot: ${snapshotId}`);
@@ -49,9 +50,10 @@ export async function run(argv = process.argv.slice(2)) {
     console.log(`  Strategy: ${profile.strategy}`);
     console.log(`  Ratios:   ${profile.train_ratio}/${profile.val_ratio}/${profile.test_ratio}`);
     console.log(`  Seed:     ${profile.seed}`);
+    if (dryRun) console.log('  Mode:     DRY RUN (no files written)');
     console.log('');
 
-    const result = await createSplit(projectRoot, snapshotId, profile);
+    const result = await createSplit(projectRoot, snapshotId, profile, { dryRun });
 
     console.log(`  \x1b[32m✓\x1b[0m Split: ${result.splitId}`);
     console.log(`  Train: ${result.train}`);