@mcptoolshop/style-dataset-lab 3.3.0 → 3.4.0

package/scripts/_shared-args.js

@@ -0,0 +1,44 @@
+/**
+ * _shared-args.js — internal helper module (NOT a CLI command; underscore
+ * prefix matches the existing scripts/_batch_cut.py / _seam_cutout.py
+ * convention for "helper, not dispatched by bin/sdlab.js").
+ *
+ * H4 (second half): the five canon-*.js scripts (canon-build.js,
+ * canon-drift.js, canon-freeze.js, canon-freeze-status.js,
+ * canon-unfreeze.js) all use Node's built-in `util.parseArgs({strict:
+ * false})`. strict:false is there deliberately, so a bare positional
+ * argument (the entity id) isn't rejected — but it has a side effect: ANY
+ * unrecognized `--flag` is silently accepted too. A misspelled OPTIONAL
+ * flag (`--staus follow` instead of `--status follow`, `--jsn` instead of
+ * `--json`) produces no error and no warning — the option you meant to set
+ * just quietly keeps its default, and Node's parser stores the typo under
+ * ITS OWN key in `parsed.values`, never touching the one you meant.
+ *
+ * assertKnownOptions() closes that gap without giving up strict:false's
+ * positional leniency: after parsing, walk `parsed.values`'s keys — since
+ * every DECLARED option (default or explicit) and every UNDECLARED flag
+ * alike lands there — and reject any key outside the known option set.
+ * Mirrors lib/args.js's own UNKNOWN_FLAG shape (same code, same
+ * "Did you mean" hint via findClosest) so a typo on a canon-*.js flag reads
+ * identically to a typo anywhere else in the CLI.
+ */
+import { inputError } from '../lib/errors.js';
+import { findClosest } from '../lib/args.js';
+
+/**
+ * @param {Object} parsedValues — the `.values` object returned by
+ *   node:util's parseArgs({strict:false, ...})
+ * @param {Object} optionsSpec — the SAME `options` object passed to parseArgs
+ * @param {{ command?: string }} [opts] — command label for the hint text
+ */
+export function assertKnownOptions(parsedValues, optionsSpec, opts = {}) {
+  const known = new Set(Object.keys(optionsSpec));
+  for (const key of Object.keys(parsedValues || {})) {
+    if (known.has(key)) continue;
+    const suggestion = findClosest(key, [...known]);
+    const hint = suggestion
+      ? `Did you mean --${suggestion}? (Run "sdlab ${opts.command ? opts.command + ' ' : ''}--help" to see all supported flags.)`
+      : `Run "sdlab ${opts.command ? opts.command + ' ' : ''}--help" to see supported flags.`;
+    throw inputError('UNKNOWN_FLAG', `Unknown flag: --${key}`, hint);
+  }
+}

package/scripts/brief-compile.js

@@ -14,6 +14,7 @@ import { parseArgs, getProjectName, parseNumberFlag } from '../lib/args.js';
 import { getProjectRoot } from '../lib/paths.js';
 import { compileBrief, saveCompiledBrief } from '../lib/brief-compiler.js';
 import { info } from '../lib/log.js';
+import { handleCliError } from '../lib/errors.js';
 
 export async function run(argv = process.argv.slice(2)) {
   const { flags } = parseArgs(argv, {
@@ -130,5 +131,5 @@ export async function run(argv = process.argv.slice(2)) {
 }
 
 if (process.argv[1] && (process.argv[1].endsWith('brief-compile.js') || process.argv[1].endsWith('brief-compile'))) {
-  run().catch((err) => { console.error(err.message || err); process.exit(1); });
+  run().catch(handleCliError);
 }

package/scripts/brief-show.js

@@ -13,6 +13,7 @@ import { parseArgs, getProjectName } from '../lib/args.js';
 import { getProjectRoot } from '../lib/paths.js';
 import { loadCompiledBrief } from '../lib/brief-compiler.js';
 import { renderBriefText, renderBriefMarkdown } from '../lib/brief-render.js';
+import { handleCliError } from '../lib/errors.js';
 
 export async function run(argv = process.argv.slice(2)) {
   const { flags, positionals } = parseArgs(argv, {
@@ -49,5 +50,5 @@ export async function run(argv = process.argv.slice(2)) {
 }
 
 if (process.argv[1] && (process.argv[1].endsWith('brief-show.js') || process.argv[1].endsWith('brief-show'))) {
-  run().catch((err) => { console.error(err.message || err); process.exit(1); });
+  run().catch(handleCliError);
 }

package/scripts/canon-bind.js

@@ -19,7 +19,7 @@
 import { readFileSync, writeFileSync, readdirSync, existsSync } from 'fs';
 import { join } from 'path';
 import { getProjectName } from '../lib/args.js';
-import { REPO_ROOT } from '../lib/paths.js';
+import { getProjectRoot } from '../lib/paths.js';
 import { loadConstitution, loadLanes, loadRubric, loadTerminology, detectLane, detectGroup } from '../lib/config.js';
 import { inputError, handleCliError } from '../lib/errors.js';
 
@@ -155,7 +155,7 @@ function generateAssertions(record, constitutionRules, lanesConfig, rubricConfig
 
 export async function run(argv = process.argv.slice(2)) {
   const projectName = getProjectName(argv);
-  const PROJECT_ROOT = join(REPO_ROOT, 'projects', projectName);
+  const PROJECT_ROOT = getProjectRoot(projectName);
   const RECORDS_DIR = join(PROJECT_ROOT, 'records');
   const DRY_RUN = argv.includes('--dry-run');
   const STATS_ONLY = argv.includes('--stats');

package/scripts/canon-build.js

@@ -7,27 +7,35 @@
  */
 
 import { parseArgs } from 'node:util';
-import { join } from 'node:path';
-import { existsSync } from 'node:fs';
+import { getProjectRoot } from '../lib/paths.js';
 import { runBuild } from '../lib/canon-build/build.js';
 import { inputError } from '../lib/errors.js';
+import { assertKnownOptions } from './_shared-args.js';
 
 export async function run(argv) {
+  const options = {
+    project:  { type: 'string' },
+    game:     { type: 'string' },           // deprecated alias
+    full:     { type: 'boolean', default: false },
+    'no-cache': { type: 'boolean', default: false },
+    'dry-run':  { type: 'boolean', default: false },
+    only:     { type: 'string' },
+    json:     { type: 'boolean', default: false },
+    quiet:    { type: 'boolean', default: false },
+  };
   const parsed = parseArgs({
     args: argv,
-    options: {
-      project:  { type: 'string' },
-      game:     { type: 'string' },           // deprecated alias
-      full:     { type: 'boolean', default: false },
-      'no-cache': { type: 'boolean', default: false },
-      'dry-run':  { type: 'boolean', default: false },
-      only:     { type: 'string' },
-      json:     { type: 'boolean', default: false },
-      quiet:    { type: 'boolean', default: false },
-    },
+    options,
     allowPositionals: true,
     strict: false,
   });
+  // H4: strict:false is deliberate (it lets the entity-id positional through
+  // unrejected) but its side effect is that ANY unrecognized --flag is
+  // silently accepted too — a misspelled OPTIONAL flag (--ful instead of
+  // --full, --dry-Run) produces no error, no warning, and the option you
+  // meant to set just quietly keeps its default. Post-validate instead of
+  // trusting strict:false's leniency for everything.
+  assertKnownOptions(parsed.values, options, { command: 'canon build' });
 
   const projectName = parsed.values.project || parsed.values.game;
   if (!projectName) {
@@ -38,14 +46,13 @@ export async function run(argv) {
     );
   }
 
-  const projectRoot = join(process.cwd(), 'projects', projectName);
-  if (!existsSync(projectRoot)) {
-    throw inputError(
-      'INPUT_PROJECT_NOT_FOUND',
-      `Project directory not found: ${projectRoot}`,
-      `Run from the style-dataset-lab repo root, or scaffold the project with "sdlab init ${projectName}".`,
-    );
-  }
+  // SDL-H12: resolve via the hardened workspace-root-aware resolver instead of
+  // join(process.cwd(), 'projects', projectName) — for a globally-installed
+  // sdlab the user is never inside the package directory, so process.cwd()
+  // silently pointed at the wrong place. getProjectRoot() also subsumes the
+  // existence check this used to do by hand (same INPUT_UNKNOWN_PROJECT shape
+  // as every other command, with an accurate "sdlab init" hint).
+  const projectRoot = getProjectRoot(projectName);
 
   const only = parsed.values.only
     ? parsed.values.only.split(',').map((s) => s.trim()).filter(Boolean)

package/scripts/canon-drift.js

@@ -19,24 +19,33 @@ import { loadSchema } from '../lib/canon-build/load-schema.js';
 import { readFreezeStatus, resolveWatchFields, computeWatchHash } from '../lib/freeze-stamp.js';
 import { readEventsSince } from '../lib/freeze-events.js';
 import { inputError } from '../lib/errors.js';
+import { getProjectRoot } from '../lib/paths.js';
+import { assertKnownOptions } from './_shared-args.js';
 
 export async function run(argv) {
+  const options = {
+    project: { type: 'string' },
+    game:    { type: 'string' },
+    since:   { type: 'string' },
+    json:    { type: 'boolean', default: false },
+  };
   const parsed = parseArgs({
     args: argv,
-    options: {
-      project: { type: 'string' },
-      game:    { type: 'string' },
-      since:   { type: 'string' },
-      json:    { type: 'boolean', default: false },
-    },
+    options,
     allowPositionals: true,
     strict: false,
   });
+  // H4: see canon-build.js's comment — strict:false's leniency on unknown
+  // flags means a typo'd optional flag (e.g. --sinse instead of --since)
+  // silently no-ops instead of erroring.
+  assertKnownOptions(parsed.values, options, { command: 'canon drift' });
 
   const projectName = parsed.values.project || parsed.values.game;
   if (!projectName) throw inputError('INPUT_MISSING_FLAG', '--project required');
 
-  const projectRoot = join(process.cwd(), 'projects', projectName);
+  // SDL-H12: resolve via the hardened workspace-root-aware resolver, not
+  // process.cwd() (wrong base for a globally-installed sdlab).
+  const projectRoot = getProjectRoot(projectName);
   const config = await loadBuildConfig(join(projectRoot, 'canon-build', 'config.json'), projectRoot);
 
   // Load latest build manifest for the stamped watch-hashes

package/scripts/canon-freeze-status.js

@@ -10,25 +10,33 @@ import { loadCanonEntriesInDir } from '../lib/canon-build/load-entry.js';
 import { readFreezeStatus, resolveWatchFields } from '../lib/freeze-stamp.js';
 import { readEventsFor } from '../lib/freeze-events.js';
 import { inputError } from '../lib/errors.js';
+import { getProjectRoot } from '../lib/paths.js';
+import { assertKnownOptions } from './_shared-args.js';
 
 export async function run(argv) {
+  const options = {
+    project: { type: 'string' },
+    game:    { type: 'string' },
+    json:    { type: 'boolean', default: false },
+  };
   const parsed = parseArgs({
     args: argv,
-    options: {
-      project: { type: 'string' },
-      game:    { type: 'string' },
-      json:    { type: 'boolean', default: false },
-    },
+    options,
     allowPositionals: true,
     strict: false,
   });
+  // H4: see canon-build.js's comment — strict:false's leniency on unknown
+  // flags means a typo'd optional flag silently no-ops instead of erroring.
+  assertKnownOptions(parsed.values, options, { command: 'canon freeze-status' });
 
   const entityIdArg = (parsed.positionals || [])[0];
   if (!entityIdArg) throw inputError('INPUT_MISSING_ARG', 'sdlab canon freeze-status requires an entity id.');
   const projectName = parsed.values.project || parsed.values.game;
   if (!projectName) throw inputError('INPUT_MISSING_FLAG', '--project required');
 
-  const projectRoot = join(process.cwd(), 'projects', projectName);
+  // SDL-H12: resolve via the hardened workspace-root-aware resolver, not
+  // process.cwd() (wrong base for a globally-installed sdlab).
+  const projectRoot = getProjectRoot(projectName);
   const config = await loadBuildConfig(join(projectRoot, 'canon-build', 'config.json'), projectRoot);
 
   let resolved = null;

package/scripts/canon-freeze.js

@@ -18,23 +18,33 @@ import { loadCanonEntriesInDir, entryId } from '../lib/canon-build/load-entry.js
 import { buildFreezeBlock, FREEZE_STATUSES, resolveWatchFields } from '../lib/freeze-stamp.js';
 import { appendEvent } from '../lib/freeze-events.js';
 import { inputError } from '../lib/errors.js';
+import { getProjectRoot } from '../lib/paths.js';
+import { assertKnownOptions } from './_shared-args.js';
 
 export async function run(argv) {
+  const options = {
+    project: { type: 'string' },
+    game:    { type: 'string' },
+    reason:  { type: 'string' },
+    status:  { type: 'string', default: 'frozen' },
+    watch:   { type: 'string' },
+    build:   { type: 'string' },
+    by:      { type: 'string', default: 'mike' },
+    json:    { type: 'boolean', default: false },
+  };
   const parsed = parseArgs({
     args: argv,
-    options: {
-      project: { type: 'string' },
-      game:    { type: 'string' },
-      reason:  { type: 'string' },
-      status:  { type: 'string', default: 'frozen' },
-      watch:   { type: 'string' },
-      build:   { type: 'string' },
-      by:      { type: 'string', default: 'mike' },
-      json:    { type: 'boolean', default: false },
-    },
+    options,
     allowPositionals: true,
     strict: false,
   });
+  // H4: see canon-build.js's comment — strict:false's leniency on unknown
+  // flags means a typo'd optional flag silently no-ops instead of erroring.
+  // This one matters more than most: `sdlab canon freeze X --staus
+  // soft-advisory` (typo) would silently keep status at its default
+  // 'frozen' — a HARD block — instead of the 'soft-advisory' the operator
+  // typed, and a typo'd --watch/--build silently drops a real override too.
+  assertKnownOptions(parsed.values, options, { command: 'canon freeze' });
 
   const positional = parsed.positionals || [];
   const entityIdArg = positional[0];
@@ -72,7 +82,13 @@ export async function run(argv) {
     );
   }
 
-  const projectRoot = join(process.cwd(), 'projects', projectName);
+  // SDL-H12: was join(process.cwd(), 'projects', projectName) — wrong base for
+  // a globally-installed sdlab. getProjectRoot() resolves from the workspace
+  // root (not cwd) and throws a clear INPUT_UNKNOWN_PROJECT before ever
+  // reaching loadBuildConfig(), instead of a deeper, misleading
+  // CANON_BUILD_CONFIG_NOT_FOUND pointed at a config that "already exists" —
+  // just under a different (correct) project root.
+  const projectRoot = getProjectRoot(projectName);
   const configPath = join(projectRoot, 'canon-build', 'config.json');
   const config = await loadBuildConfig(configPath, projectRoot);
 

package/scripts/canon-unfreeze.js

@@ -18,21 +18,27 @@ import { loadCanonEntriesInDir } from '../lib/canon-build/load-entry.js';
 import { appendOverrideToFreezeBlock, readFreezeStatus } from '../lib/freeze-stamp.js';
 import { appendEvent } from '../lib/freeze-events.js';
 import { inputError } from '../lib/errors.js';
+import { getProjectRoot } from '../lib/paths.js';
+import { assertKnownOptions } from './_shared-args.js';
 
 export async function run(argv) {
+  const options = {
+    project: { type: 'string' },
+    game:    { type: 'string' },
+    reason:  { type: 'string' },
+    by:      { type: 'string', default: 'mike' },
+    build:   { type: 'string' },
+    json:    { type: 'boolean', default: false },
+  };
   const parsed = parseArgs({
     args: argv,
-    options: {
-      project: { type: 'string' },
-      game:    { type: 'string' },
-      reason:  { type: 'string' },
-      by:      { type: 'string', default: 'mike' },
-      build:   { type: 'string' },
-      json:    { type: 'boolean', default: false },
-    },
+    options,
     allowPositionals: true,
     strict: false,
   });
+  // H4: see canon-build.js's comment — strict:false's leniency on unknown
+  // flags means a typo'd optional flag silently no-ops instead of erroring.
+  assertKnownOptions(parsed.values, options, { command: 'canon unfreeze' });
 
   const entityIdArg = (parsed.positionals || [])[0];
   if (!entityIdArg) {
@@ -48,7 +54,9 @@ export async function run(argv) {
     );
   }
 
-  const projectRoot = join(process.cwd(), 'projects', projectName);
+  // SDL-H12: resolve via the hardened workspace-root-aware resolver, not
+  // process.cwd() (wrong base for a globally-installed sdlab).
+  const projectRoot = getProjectRoot(projectName);
   const config = await loadBuildConfig(join(projectRoot, 'canon-build', 'config.json'), projectRoot);
   const resolved = await findEntryFile(config, entityIdArg);
   if (!resolved) {

package/scripts/card.js

@@ -10,7 +10,7 @@
 import { join } from 'node:path';
 import { writeFile } from 'node:fs/promises';
 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 { listSnapshots } from '../lib/snapshot.js';
 import { listSplits } from '../lib/split.js';
@@ -27,7 +27,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] || 'generate';
 
   if (subcommand === 'generate') {

package/scripts/compare.js

@@ -11,7 +11,7 @@
 import { writeFile, readdir, mkdir, 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 { readJsonFile } from "../lib/config.js";
 import { inputError, handleCliError } from "../lib/errors.js";
 
@@ -25,7 +25,7 @@ export async function run(argv = process.argv.slice(2)) {
   });
 
   const projectName = flags.project || getProjectName(argv);
-  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
+  const GAME_ROOT = getProjectRoot(projectName);
 
   const [assetAId, assetBId, winner, ...reasonParts] = positionals;
 

package/scripts/critique.js

@@ -84,9 +84,24 @@ export async function run(argv = process.argv.slice(2)) {
     const action = report.recommended_action;
     console.log(`Critique saved to: runs/${flags.run}/critique.json`);
 
+    // H2: `refine_from_one` fires today purely from every candidate sitting
+    // at the unreviewed default overall_fit "usable" (nothing in the
+    // codebase currently sets it to anything else) — action.reviewed
+    // (lib/critique-engine.js recommendAction) distinguishes that from an
+    // actually-assessed run. Printing "Next: ..." with the same confidence
+    // either way presented brief-keyword drift tiebreaking as a considered
+    // recommendation. Qualify instead of suppressing outright — the pick is
+    // still a reasonable place to look first, it's just not a judgment.
     if (action.mode === 'refine_from_one' && action.preferred_candidate) {
       console.log('');
-      info(`Next: sdlab refine --run ${flags.run} --pick ${action.preferred_candidate}`);
+      if (action.reviewed) {
+        info(`Next: sdlab refine --run ${flags.run} --pick ${action.preferred_candidate}`);
+      } else {
+        info(`No candidate has been reviewed yet — every image is at the rule-based pass's default "usable" ` +
+          `until a human or LLM judge assesses fit.`);
+        info(`If you want to proceed anyway: sdlab refine --run ${flags.run} --pick ${action.preferred_candidate} ` +
+          `(picked by fewest rule-based drift issues, not by looking at the image).`);
+      }
     } else if (action.mode === 'accept_one' && action.preferred_candidate) {
       console.log('');
       info(`Preferred candidate: ${action.preferred_candidate}`);

package/scripts/curate.js

@@ -13,7 +13,7 @@
 import { writeFile, rename, readdir, mkdir, 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 { readJsonFile } from "../lib/config.js";
 import { inputError, runtimeError, handleCliError } from "../lib/errors.js";
 import { result } from "../lib/log.js";
@@ -35,7 +35,7 @@ export async function run(argv = process.argv.slice(2)) {
   });
 
   const projectName = flags.project || getProjectName(argv);
-  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
+  const GAME_ROOT = getProjectRoot(projectName);
   const dryRun = flags['dry-run'] || flags.dryRun;
 
   if (flags.list) {