@mcptoolshop/style-dataset-lab 3.1.0 → 3.2.0

package/scripts/canon-freeze.js

@@ -0,0 +1,211 @@
+/**
+ * `sdlab canon freeze <entity_id> --reason "<text>"` — stamp a freeze block
+ * on a canon entry (D7 command).
+ *
+ * Validates the entry exists, that a canon-build output exists to witness
+ * against (so the `locked_at_build` field has a real value — D1), rewrites
+ * the entry's frontmatter with the new `freeze` block, and appends a
+ * `freeze` event to freeze-events.jsonl (D4).
+ */
+
+import { parseArgs } from 'node:util';
+import { readFile, writeFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { loadBuildConfig } from '../lib/canon-build/load-config.js';
+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';
+
+export async function run(argv) {
+  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 },
+    },
+    allowPositionals: true,
+    strict: false,
+  });
+
+  const positional = parsed.positionals || [];
+  const entityIdArg = positional[0];
+  if (!entityIdArg) {
+    throw inputError(
+      'INPUT_MISSING_ARG',
+      'sdlab canon freeze requires an entity id as the first positional argument.',
+      'Example: sdlab canon freeze heracles --reason "Labor III reference plate approved"',
+    );
+  }
+
+  const projectName = parsed.values.project || parsed.values.game;
+  if (!projectName) {
+    throw inputError('INPUT_MISSING_FLAG', 'sdlab canon freeze requires --project <name>', 'Example: --project greek-rpg');
+  }
+
+  if (!parsed.values.reason) {
+    throw inputError(
+      'FREEZE_REASON_REQUIRED',
+      'sdlab canon freeze requires --reason "<short text>".',
+      'The reason lands in both the entry frontmatter and canon-build/freeze-events.jsonl as the audit record. Future you (and the LLM crew) need it to understand why.',
+    );
+  }
+
+  if (!FREEZE_STATUSES.includes(parsed.values.status)) {
+    throw inputError(
+      'INPUT_INVALID_VALUE',
+      `--status must be one of ${FREEZE_STATUSES.join(', ')} (got "${parsed.values.status}")`,
+    );
+  }
+  if (parsed.values.status === 'auto') {
+    throw inputError(
+      'INPUT_INVALID_VALUE',
+      '--status auto means "no freeze" — use `sdlab canon unfreeze` instead of freezing with status=auto.',
+    );
+  }
+
+  const projectRoot = join(process.cwd(), 'projects', projectName);
+  const configPath = join(projectRoot, 'canon-build', 'config.json');
+  const config = await loadBuildConfig(configPath, projectRoot);
+
+  // Find the entry file
+  const resolved = await findEntryFile(config, entityIdArg);
+  if (!resolved) {
+    throw inputError(
+      'CANON_ENTRY_NOT_FOUND',
+      `No canon entry with id "${entityIdArg}" found under ${config.canon_root}.`,
+      `Check the entry filename matches the id field, and that the schema-subdirectory mapping in canon-build/config.json covers this entity type.`,
+    );
+  }
+
+  // Resolve the witness build hash
+  const lockedAtBuild = parsed.values.build || await findLatestBuildHash(projectRoot);
+  if (!lockedAtBuild) {
+    throw inputError(
+      'FREEZE_NO_BUILD_WITNESS',
+      'No canon-build output exists to witness this freeze against.',
+      'Run `sdlab canon build` first to produce a build artifact, then retry the freeze. The witness chain (D1) requires a real build hash to stamp.',
+    );
+  }
+
+  // Resolve watch-fields: --watch override > entry override > config default
+  const watchFields = resolveEffectiveWatchFields({
+    entry: resolved.entry,
+    schemaName: resolved.schemaName,
+    buildConfig: config,
+    cliOverride: parsed.values.watch,
+  });
+
+  // Build the new freeze block, preserving existing overrides[] if any
+  const existing = resolved.entry.frontmatter.freeze || {};
+  const priorStatus = existing.status || 'auto';
+  const newBlock = buildFreezeBlock({
+    status: parsed.values.status,
+    lockedAtBuild,
+    frozenBy: parsed.values.by,
+    frozenReason: parsed.values.reason,
+    watchFields,
+    overrides: existing.overrides,
+  });
+
+  // Rewrite the entry file
+  const updatedFm = { ...resolved.entry.frontmatter, freeze: newBlock };
+  await rewriteEntryFrontmatter(resolved.filePath, updatedFm, resolved.entry.body);
+
+  // Append audit event
+  const event = await appendEvent(projectRoot, {
+    type: 'freeze',
+    entity_id: entityIdArg,
+    schema_kind: resolved.schemaName.replace('.schema.json', ''),
+    by: parsed.values.by,
+    reason: parsed.values.reason,
+    prior_status: priorStatus,
+    new_status: parsed.values.status,
+    watch_fields: watchFields,
+    build_hash: lockedAtBuild,
+  });
+
+  const result = {
+    ok: true,
+    entity_id: entityIdArg,
+    status: parsed.values.status,
+    locked_at_build: lockedAtBuild,
+    watch_fields: watchFields,
+    event_at: event.at,
+  };
+
+  if (parsed.values.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(`froze "${entityIdArg}" (${parsed.values.status}) witnessed at ${lockedAtBuild}`);
+  console.log(`  watching: ${watchFields.length ? watchFields.join(', ') : '(no fields — build-config has no default for this schema and no --watch was passed)'}`);
+  console.log(`  reason:   ${parsed.values.reason}`);
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────
+
+async function findEntryFile(config, entityId) {
+  for (const [schemaName, subdir] of Object.entries(config.entity_dirs)) {
+    const dir = join(config.canon_root, subdir);
+    const entries = await loadCanonEntriesInDir(dir);
+    for (const entry of entries) {
+      const id = entry.frontmatter?.id;
+      if (id === entityId) {
+        return { entry, schemaName, filePath: entry.filePath };
+      }
+    }
+  }
+  return null;
+}
+
+async function findLatestBuildHash(projectRoot) {
+  const canonBuildDir = join(projectRoot, 'canon-build');
+  if (!existsSync(canonBuildDir)) return null;
+  const entries = await readdir(canonBuildDir, { withFileTypes: true });
+  const buildDirs = entries
+    .filter((e) => e.isDirectory() && !e.name.startsWith('.') && !e.name.endsWith('.tmp') && !e.name.includes('.tmp-'))
+    .map((e) => e.name);
+  if (buildDirs.length === 0) return null;
+
+  // Pick the most recent by mtime of its manifest.json
+  let latest = null;
+  let latestMtime = 0;
+  for (const name of buildDirs) {
+    const manifestPath = join(canonBuildDir, name, 'manifest.json');
+    if (!existsSync(manifestPath)) continue;
+    try {
+      const manifest = JSON.parse(await readFile(manifestPath, 'utf-8'));
+      const built = new Date(manifest.built_at || 0).getTime();
+      if (built > latestMtime) {
+        latestMtime = built;
+        latest = manifest.generated_from || name;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return latest;
+}
+
+function resolveEffectiveWatchFields({ entry, schemaName, buildConfig, cliOverride }) {
+  if (cliOverride) {
+    return cliOverride.split(',').map((s) => s.trim()).filter(Boolean);
+  }
+  return resolveWatchFields(entry.frontmatter, schemaName, buildConfig);
+}
+
+async function rewriteEntryFrontmatter(filePath, frontmatter, body) {
+  const yaml = stringifyYaml(frontmatter).trimEnd();
+  const content = `---\n${yaml}\n---\n${body}`;
+  await writeFile(filePath, content, 'utf-8');
+}

package/scripts/canon-unfreeze.js

@@ -0,0 +1,137 @@
+/**
+ * `sdlab canon unfreeze <entity_id> --reason "<text>"` — lift a freeze (D7).
+ *
+ * Writes the entry's `freeze.status` to `auto`, appends an `unfreeze` event
+ * with the prior state captured. Preserves the `overrides[]` history on the
+ * entry (append-only) so re-freeze later shows the full lifecycle.
+ *
+ * --reason is REQUIRED — unfreezes are where shipping studios (Sabotage,
+ * Supergiant, Pentiment) most often wished they had captured intent.
+ */
+
+import { parseArgs } from 'node:util';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { stringify as stringifyYaml } from 'yaml';
+import { loadBuildConfig } from '../lib/canon-build/load-config.js';
+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';
+
+export async function run(argv) {
+  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 },
+    },
+    allowPositionals: true,
+    strict: false,
+  });
+
+  const entityIdArg = (parsed.positionals || [])[0];
+  if (!entityIdArg) {
+    throw inputError('INPUT_MISSING_ARG', 'sdlab canon unfreeze requires an entity id.');
+  }
+  const projectName = parsed.values.project || parsed.values.game;
+  if (!projectName) throw inputError('INPUT_MISSING_FLAG', '--project required');
+  if (!parsed.values.reason) {
+    throw inputError(
+      'FREEZE_REASON_REQUIRED',
+      'sdlab canon unfreeze requires --reason "<text>".',
+      'Unfreezes are where shipping studios most often regret not capturing intent. The reason lands in canon-build/freeze-events.jsonl and in the entry frontmatter\'s overrides[] append-only log.',
+    );
+  }
+
+  const projectRoot = join(process.cwd(), 'projects', projectName);
+  const config = await loadBuildConfig(join(projectRoot, 'canon-build', 'config.json'), projectRoot);
+  const resolved = await findEntryFile(config, entityIdArg);
+  if (!resolved) {
+    throw inputError('CANON_ENTRY_NOT_FOUND', `No canon entry with id "${entityIdArg}".`);
+  }
+
+  const fm = resolved.entry.frontmatter;
+  const priorStatus = readFreezeStatus(fm);
+  if (priorStatus === 'auto') {
+    throw inputError(
+      'FREEZE_ALREADY_AUTO',
+      `Canon entry "${entityIdArg}" is already at status=auto; nothing to unfreeze.`,
+    );
+  }
+
+  const priorFreeze = fm.freeze || {};
+  const buildHash = parsed.values.build || priorFreeze.locked_at_build || null;
+
+  // Append override record to the entry's overrides[] log
+  const overrideRecord = {
+    at: buildHash || new Date().toISOString(),
+    by: parsed.values.by,
+    reason: parsed.values.reason,
+    prior_status: priorStatus,
+    prior_build_hash: priorFreeze.locked_at_build || null,
+  };
+  const updatedBlock = appendOverrideToFreezeBlock(
+    { ...priorFreeze, status: 'auto' },
+    overrideRecord,
+  );
+  // Drop fields that only make sense on an active freeze
+  delete updatedBlock.locked_at_build;
+  delete updatedBlock.locked_at_canon_version;
+  delete updatedBlock.frozen_by;
+  delete updatedBlock.frozen_reason;
+  delete updatedBlock.watch_fields;
+
+  const updatedFm = { ...fm, freeze: updatedBlock };
+  await rewriteEntryFrontmatter(resolved.filePath, updatedFm, resolved.entry.body);
+
+  const event = await appendEvent(projectRoot, {
+    type: 'unfreeze',
+    entity_id: entityIdArg,
+    schema_kind: resolved.schemaName.replace('.schema.json', ''),
+    by: parsed.values.by,
+    reason: parsed.values.reason,
+    prior_status: priorStatus,
+    new_status: 'auto',
+    prior_build_hash: priorFreeze.locked_at_build || null,
+    build_hash: buildHash,
+  });
+
+  const result = {
+    ok: true,
+    entity_id: entityIdArg,
+    prior_status: priorStatus,
+    new_status: 'auto',
+    event_at: event.at,
+  };
+
+  if (parsed.values.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`unfroze "${entityIdArg}" (was ${priorStatus})`);
+  console.log(`  reason: ${parsed.values.reason}`);
+  console.log(`  overrides[] history preserved with ${updatedBlock.overrides.length} entries`);
+}
+
+async function findEntryFile(config, entityId) {
+  for (const [schemaName, subdir] of Object.entries(config.entity_dirs)) {
+    const dir = join(config.canon_root, subdir);
+    const entries = await loadCanonEntriesInDir(dir);
+    for (const entry of entries) {
+      if (entry.frontmatter?.id === entityId) {
+        return { entry, schemaName, filePath: entry.filePath };
+      }
+    }
+  }
+  return null;
+}
+
+async function rewriteEntryFrontmatter(filePath, frontmatter, body) {
+  const yaml = stringifyYaml(frontmatter).trimEnd();
+  await writeFile(filePath, `---\n${yaml}\n---\n${body}`, 'utf-8');
+}

package/scripts/curate.js

@@ -17,6 +17,7 @@ import { REPO_ROOT } from "../lib/paths.js";
 import { readJsonFile } from "../lib/config.js";
 import { inputError, runtimeError, handleCliError } from "../lib/errors.js";
 import { result } from "../lib/log.js";
+import { assertNotFrozenByAssetPath } from "../lib/freeze-gate.js";
 
 export async function run(argv = process.argv.slice(2)) {
   const { flags, positionals } = parseArgs(argv, {
@@ -27,6 +28,7 @@ export async function run(argv = process.argv.slice(2)) {
       notes: { type: 'string' },
       list: { type: 'boolean', default: false },
       'dry-run': { type: 'boolean', default: false },
+      'i-know': { type: 'boolean', default: false },
     },
     deprecated: { game: 'project' },
   });
@@ -106,6 +108,16 @@ export async function run(argv = process.argv.slice(2)) {
     return;
   }
 
+  // Freeze gate: refuse to recurate to a path that a frozen canon entry owns.
+  // No-op when the project has no canon-build config. The explanation doubles
+  // as the bypass reason when the target entry is soft-advisory.
+  await assertNotFrozenByAssetPath(GAME_ROOT, newPath, {
+    action: 'curate',
+    allowSoftAdvisoryBypass: flags['i-know'],
+    bypassReason: explanation,
+    by: 'mike',
+  });
+
   await mkdir(join(GAME_ROOT, newDir), { recursive: true });
 
   // Move image FIRST — if the rename fails we still have a clean record.

package/scripts/generate-controlnet.js

@@ -19,6 +19,7 @@ import { REPO_ROOT, resolveSafeProjectPath } from "../lib/paths.js";
 import { readJsonFile } from "../lib/config.js";
 import { inputError, runtimeError, handleCliError } from "../lib/errors.js";
 import { comfyHealth, submitAndWait, downloadImage, uploadImage } from "../lib/comfyui.js";
+import { assertNotFrozenBySubject } from "../lib/freeze-gate.js";
 
 const DEFAULTS = {
   checkpoint: "dreamshaperXL_v21TurboDPMSDE.safetensors",
@@ -177,6 +178,17 @@ export async function run(argv = process.argv.slice(2)) {
     throw inputError('INPUT_MISSING_FLAG', "--guide <path> is required");
   }
 
+  // Freeze gate (advisory): refuse if the subject's canon entry is frozen.
+  // Supports --i-know + --reason bypass for soft-advisory entries.
+  const reasonFlagIdx = argv.indexOf('--reason');
+  const bypassReason = reasonFlagIdx >= 0 && argv[reasonFlagIdx + 1] ? argv[reasonFlagIdx + 1] : null;
+  await assertNotFrozenBySubject(GAME_ROOT, opts.subject, {
+    action: 'generate:controlnet',
+    allowSoftAdvisoryBypass: argv.includes('--i-know'),
+    bypassReason,
+    by: 'mike',
+  });
+
   // Validate guide stays inside the project tree.
   const safeGuide = resolveSafeProjectPath(GAME_ROOT, opts.guidePath, { flagName: 'guide' });
 

package/scripts/generate-identity.js

@@ -24,9 +24,10 @@ import { writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { getProjectName, parseNumberFlag } from "../lib/args.js";
 import { REPO_ROOT, resolveSafeProjectPath } from "../lib/paths.js";
-import { readJsonFile } from "../lib/config.js";
+import { readJsonFile, loadProjectMeta, resolveGpuModel } from "../lib/config.js";
 import { inputError, runtimeError, handleCliError } from "../lib/errors.js";
 import { comfyHealth, submitAndWait, downloadImage } from "../lib/comfyui.js";
+import { assertNotFrozenBySubject } from "../lib/freeze-gate.js";
 
 // ── Defaults (match existing lab pipeline) ──
 
@@ -309,7 +310,7 @@ function buildImg2ImgWorkflow(prompt, negativePrompt, seed, imagePath, denoise)
 
 // ── Record Builder ──
 
-function buildRecord(pack, subject, shot, seed, seedIndex, imgData, destPath, elapsedMs, phase, anchorInfo) {
+function buildRecord(pack, subject, shot, seed, seedIndex, imgData, destPath, elapsedMs, phase, anchorInfo, gpuModel) {
   const assetId = `${shot.id}_s${seedIndex}`;
   const fullPrompt = `${pack.style_prefix}, ${shot.prompt}`;
   const negativePrompt = [
@@ -343,7 +344,7 @@ function buildRecord(pack, subject, shot, seed, seedIndex, imgData, destPath, el
       width: DEFAULTS.width,
       height: DEFAULTS.height,
       generation_time_ms: elapsedMs,
-      gpu_model: "RTX 5080",
+      gpu_model: gpuModel,
       denoise: phase === "follow_on" ? (anchorInfo?.denoise || 0.38) : 1.0,
     },
     identity: {
@@ -379,6 +380,7 @@ export async function run(argv = process.argv.slice(2)) {
   const projectName = getProjectName(argv);
   const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
   const COMFY_URL = process.env.COMFY_URL || "http://127.0.0.1:8188";
+  const gpuModel = resolveGpuModel(loadProjectMeta(GAME_ROOT)?.defaults);
 
   // Collect positionals, skipping values that belong to known flags
   const knownFlagsWithValue = new Set(['--subject', '--seeds', '--phase', '--anchor', '--denoise', '--project', '--game']);
@@ -396,6 +398,20 @@ export async function run(argv = process.argv.slice(2)) {
   const subjectFilter = argv.includes("--subject")
     ? argv[argv.indexOf("--subject") + 1]
     : null;
+
+  // Freeze gate (advisory): when --subject is given, refuse if that subject's
+  // canon entry is frozen. No-op when --subject is absent (pack-driven) or
+  // when the project has no canon-build config.
+  if (subjectFilter) {
+    const reasonFlagIdx = argv.indexOf('--reason');
+    const bypassReason = reasonFlagIdx >= 0 && argv[reasonFlagIdx + 1] ? argv[reasonFlagIdx + 1] : null;
+    await assertNotFrozenBySubject(GAME_ROOT, subjectFilter, {
+      action: 'generate:identity',
+      allowSoftAdvisoryBypass: argv.includes('--i-know'),
+      bypassReason,
+      by: 'mike',
+    });
+  }
   const seedCount = argv.includes("--seeds")
     ? parseNumberFlag('seeds', argv[argv.indexOf("--seeds") + 1], { int: true, min: 1 })
     : 3;
@@ -536,7 +552,7 @@ export async function run(argv = process.argv.slice(2)) {
 
           const record = buildRecord(
             pack, subject, shot, seed, si,
-            imgData, destPath, elapsed, phase, anchorInfo
+            imgData, destPath, elapsed, phase, anchorInfo, gpuModel
           );
 
           await writeFile(

package/scripts/generate-ipadapter.js

@@ -17,6 +17,7 @@ import { getProjectName, parseNumberFlag } from "../lib/args.js";
 import { REPO_ROOT, resolveSafeProjectPath } from "../lib/paths.js";
 import { inputError, runtimeError, handleCliError } from "../lib/errors.js";
 import { comfyHealth, submitAndWait, downloadImage, uploadImage } from "../lib/comfyui.js";
+import { assertNotFrozenBySubject } from "../lib/freeze-gate.js";
 
 const DEFAULTS = {
   checkpoint: "dreamshaperXL_v21TurboDPMSDE.safetensors",
@@ -186,6 +187,16 @@ export async function run(argv = process.argv.slice(2)) {
     throw inputError('INPUT_MISSING_FLAG', "--prompt is required");
   }
 
+  // Freeze gate (advisory): refuse if the subject's canon entry is frozen.
+  const reasonFlagIdx = argv.indexOf('--reason');
+  const bypassReason = reasonFlagIdx >= 0 && argv[reasonFlagIdx + 1] ? argv[reasonFlagIdx + 1] : null;
+  await assertNotFrozenBySubject(GAME_ROOT, opts.subject, {
+    action: 'generate:ipadapter',
+    allowSoftAdvisoryBypass: argv.includes('--i-know'),
+    bypassReason,
+    by: 'mike',
+  });
+
   // Validate --ref path stays inside project tree.
   const safeRefPath = resolveSafeProjectPath(GAME_ROOT, opts.refPath, { flagName: 'ref' });