@mcptoolshop/style-dataset-lab 2.3.0 → 3.0.1

package/lib/batch-runs.js

@@ -0,0 +1,237 @@
+/**
+ * Batch runs — create batch directories, execute coordinated runs, save manifests.
+ *
+ * A batch groups multiple runs under one artifact:
+ *   batch_YYYY-MM-DD_NNN/
+ *     manifest.json
+ *     summary.json / summary.md
+ *     sheets/
+ *     runs/   (symlinks or copies to project-level runs)
+ *     briefs/ (slot briefs)
+ */
+
+import { writeFile, mkdir, copyFile, rename, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { getProjectRoot, getRunsDir } from './paths.js';
+import { executeRun } from './adapters/comfyui-runner.js';
+import { saveRunSummary } from './run-summary.js';
+import { log, info, warn, verbose } from './log.js';
+import { inputError } from './errors.js';
+
+/**
+ * PB-002 / PB-005: atomic write helper — write temp + rename.
+ * Rename is atomic on a single filesystem, so a crash mid-write cannot
+ * corrupt an existing manifest.
+ */
+async function atomicWriteJson(targetPath, obj) {
+  const tmpPath = `${targetPath}.tmp-${process.pid}-${Date.now()}`;
+  const body = JSON.stringify(obj, null, 2) + '\n';
+  try {
+    await writeFile(tmpPath, body);
+    await rename(tmpPath, targetPath);
+  } catch (err) {
+    try { await unlink(tmpPath); } catch { /* ignore */ }
+    throw err;
+  }
+}
+
+/**
+ * Return the batches directory for a project.
+ */
+export function getBatchesDir(projectRoot) {
+  return join(projectRoot, 'batches');
+}
+
+/**
+ * Generate batch ID: batch_YYYY-MM-DD_NNN
+ */
+// PB-008: tighten regex so stray directories like 'batch_<date>_001_wip'
+// don't inflate the sequence via lenient parseInt.
+const BATCH_SEQ_RE = /^(\d{3})$/;
+
+export function generateBatchId(batchesDir) {
+  const today = new Date().toISOString().slice(0, 10);
+  const prefix = `batch_${today}_`;
+
+  let maxSeq = 0;
+  if (existsSync(batchesDir)) {
+    const existing = readdirSync(batchesDir, { withFileTypes: true })
+      .filter(e => e.isDirectory() && e.name.startsWith(prefix));
+    for (const e of existing) {
+      const seqStr = e.name.slice(prefix.length);
+      const match = BATCH_SEQ_RE.exec(seqStr);
+      if (!match) continue;
+      const seq = parseInt(match[1], 10);
+      if (seq > maxSeq) maxSeq = seq;
+    }
+  }
+
+  const seq = String(maxSeq + 1).padStart(3, '0');
+  return `${prefix}${seq}`;
+}
+
+/**
+ * Create a batch directory and prepare its structure.
+ */
+export async function createBatchDir(projectRoot) {
+  const batchesDir = getBatchesDir(projectRoot);
+  const batchId = generateBatchId(batchesDir);
+  const batchDir = join(batchesDir, batchId);
+
+  await mkdir(join(batchDir, 'sheets'), { recursive: true });
+  await mkdir(join(batchDir, 'briefs'), { recursive: true });
+
+  return { batchId, batchDir };
+}
+
+/**
+ * Execute all slot briefs as coordinated runs.
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectRoot
+ * @param {string} opts.projectName
+ * @param {string} opts.batchDir
+ * @param {Object} opts.mode — batch mode definition
+ * @param {Object[]} opts.slotBriefs — one brief per slot
+ * @param {boolean} [opts.dryRun]
+ * @returns {Promise<Object[]>} — array of { slot, brief, manifest }
+ */
+export async function executeBatchRuns({
+  projectRoot,
+  projectName,
+  batchDir,
+  mode,
+  slotBriefs,
+  dryRun = false,
+}) {
+  // PB-005: fail fast on length mismatch instead of crashing deep in the loop.
+  if (!Array.isArray(mode?.variant_plan) || mode.variant_plan.length !== slotBriefs.length) {
+    throw inputError(
+      'BATCH_SLOT_PLAN_MISMATCH',
+      `Batch variant_plan has ${mode?.variant_plan?.length ?? 0} slots but ` +
+      `${slotBriefs.length} brief(s) were compiled`,
+      'This is an internal invariant — rebuild the batch from the mode definition.'
+    );
+  }
+
+  const results = [];
+  // PB-005: incremental batch-progress manifest — written after every slot
+  // so a crash never orphans the batch dir without a record of what ran.
+  const progressPath = join(batchDir, 'manifest.json');
+
+  for (let i = 0; i < slotBriefs.length; i++) {
+    const slot = mode.variant_plan[i];
+    const brief = slotBriefs[i];
+    const slotLabel = slot.label || slot.slot_id;
+
+    info(`[${i + 1}/${slotBriefs.length}] Slot: ${slotLabel}`);
+
+    // Save brief into batch/briefs/
+    const briefFilename = `${slot.slot_id}.json`;
+    await writeFile(
+      join(batchDir, 'briefs', briefFilename),
+      JSON.stringify(brief, null, 2) + '\n'
+    );
+
+    // PB-005: per-slot try/catch — one slot failure no longer throws out of
+    // the whole batch. Record the error and keep going so the user doesn't
+    // lose already-completed slots.
+    try {
+      // Execute the run through the existing 4B pipeline
+      const manifest = await executeRun({
+        projectRoot,
+        projectName,
+        brief,
+        dryRun,
+      });
+
+      // Save run summary
+      const runDir = join(getRunsDir(projectRoot), manifest.run_id);
+      await saveRunSummary(runDir, manifest);
+
+      results.push({
+        slot_id: slot.slot_id,
+        label: slotLabel,
+        brief_id: brief.brief_id,
+        run_id: manifest.run_id,
+        manifest,
+        status: 'ok',
+        // Pick the first successful output as the selected one
+        selected_output: manifest.outputs.find(o =>
+          o.status === 'ok' || o.status === 'dry_run'
+        )?.filename || null,
+      });
+    } catch (err) {
+      warn(`  ✗ slot ${slotLabel} failed: ${err.message}`);
+      results.push({
+        slot_id: slot.slot_id,
+        label: slotLabel,
+        brief_id: brief.brief_id,
+        run_id: null,
+        manifest: null,
+        status: 'error',
+        error: err.message,
+        selected_output: null,
+      });
+    }
+
+    // PB-005: checkpoint after every slot (atomic write).
+    try {
+      await atomicWriteJson(progressPath, {
+        batch_dir: batchDir,
+        mode_id: mode?.mode_id ?? mode?.id ?? null,
+        incremental: true,
+        last_checkpoint_at: new Date().toISOString(),
+        completed: i + 1,
+        total: slotBriefs.length,
+        slots: results,
+      });
+      verbose(`batch checkpoint: ${i + 1}/${slotBriefs.length} slots`);
+    } catch (err) {
+      warn(`  batch checkpoint write failed: ${err.message}`);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Save a batch manifest.
+ */
+export async function saveBatchManifest(batchDir, manifest) {
+  // PB-002: atomic write — safe to overwrite an in-progress checkpoint
+  // because rename is atomic on a single filesystem.
+  await atomicWriteJson(join(batchDir, 'manifest.json'), manifest);
+}
+
+/**
+ * Load a batch manifest by ID.
+ */
+export function loadBatchManifest(projectRoot, batchId) {
+  const batchDir = join(getBatchesDir(projectRoot), batchId);
+  const manifestPath = join(batchDir, 'manifest.json');
+
+  if (!existsSync(manifestPath)) {
+    throw inputError(
+      'BATCH_NOT_FOUND',
+      `Batch "${batchId}" not found`,
+      'Check the batch ID or run: sdlab batch generate --mode <id>'
+    );
+  }
+
+  return JSON.parse(readFileSync(manifestPath, 'utf-8'));
+}
+
+/**
+ * List all batches for a project.
+ */
+export function listBatches(projectRoot) {
+  const batchesDir = getBatchesDir(projectRoot);
+  if (!existsSync(batchesDir)) return [];
+
+  return readdirSync(batchesDir, { withFileTypes: true })
+    .filter(e => e.isDirectory() && e.name.startsWith('batch_'))
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map(e => e.name);
+}

package/lib/batch-sheet-render.js

@@ -0,0 +1,209 @@
+/**
+ * Batch sheet renderer — assembles run outputs into reviewable HTML surfaces.
+ *
+ * Produces an HTML file with a CSS grid layout that references output images.
+ * Zero dependencies — works in any browser. Slot labels, seeds, and metadata
+ * are embedded for human review.
+ *
+ * Future: add PNG rendering via sharp if needed.
+ */
+
+import { writeFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { existsSync } from 'node:fs';
+import { getRunsDir } from './paths.js';
+
+/**
+ * Resolve the image path for a slot result.
+ * Returns a relative path from the sheet directory to the output image.
+ */
+function resolveImagePath(projectRoot, result, batchDir) {
+  if (!result.selected_output || !result.run_id) return null;
+
+  const imagePath = join(getRunsDir(projectRoot), result.run_id, 'outputs', result.selected_output);
+  if (!existsSync(imagePath)) return null;
+
+  // Relative from sheets/ dir to the image
+  const sheetsDir = join(batchDir, 'sheets');
+  return relative(sheetsDir, imagePath).replace(/\\/g, '/');
+}
+
+/**
+ * Render a batch sheet as HTML.
+ *
+ * @param {Object} opts
+ * @param {Object} opts.manifest — batch manifest
+ * @param {Object} opts.mode — batch mode definition
+ * @param {string} opts.projectRoot
+ * @param {string} opts.batchDir
+ * @returns {string} HTML content
+ */
+export function renderSheetHTML({ manifest, mode, projectRoot, batchDir }) {
+  const assembly = mode.assembly || {};
+  const layout = assembly.layout || 'grid';
+  const slots = manifest.slots || [];
+  const rawColumns = assembly.columns;
+  const columns = (typeof rawColumns === 'number' && rawColumns > 0)
+    ? rawColumns
+    : computeColumns(slots.length);
+  const showSlotLabels = assembly.annotate_slots !== false;
+  const showSeed = assembly.show_seed || false;
+
+  const title = `${manifest.mode_id} — ${manifest.subject_id || manifest.theme || manifest.project_id}`;
+
+  // Build slot cells
+  const cells = slots.map(slot => {
+    const imgPath = resolveImagePath(projectRoot, slot, batchDir);
+    const hasImage = !!imgPath;
+
+    return {
+      slot_id: slot.slot_id,
+      label: slot.label,
+      run_id: slot.run_id,
+      selected_output: slot.selected_output,
+      imgPath,
+      hasImage,
+      seed: findSlotSeed(manifest, slot),
+    };
+  });
+
+  // Generate HTML
+  const css = generateCSS(layout, columns, cells.length);
+  const grid = cells.map((cell, i) => renderCell(cell, i, showSlotLabels, showSeed)).join('\n');
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>${escapeHtml(title)}</title>
+<style>${css}</style>
+</head>
+<body>
+<header>
+  <h1>${escapeHtml(title)}</h1>
+  <p class="meta">
+    Batch: ${escapeHtml(manifest.batch_id)} |
+    Mode: ${escapeHtml(manifest.mode_id)} |
+    Type: ${escapeHtml(mode.batch_type)} |
+    ${slots.length} slots |
+    ${manifest.created_at?.slice(0, 16) || '?'}
+  </p>
+</header>
+<div class="grid">${grid}
+</div>
+<footer>
+  <p>Generated by style-dataset-lab — ${manifest.created_at || ''}</p>
+</footer>
+</body>
+</html>`;
+}
+
+/**
+ * Compute optimal column count based on slot count.
+ */
+function computeColumns(slotCount) {
+  if (slotCount <= 3) return slotCount;
+  if (slotCount <= 4) return 2;
+  if (slotCount <= 6) return 3;
+  if (slotCount <= 9) return 3;
+  return 4;
+}
+
+/**
+ * Generate CSS for the layout.
+ */
+function generateCSS(layout, columns, slotCount) {
+  return `
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      background: #1a1a1a; color: #e0e0e0;
+      padding: 24px;
+    }
+    header { margin-bottom: 24px; }
+    h1 { font-size: 1.4rem; font-weight: 600; }
+    .meta { font-size: 0.85rem; color: #888; margin-top: 4px; }
+    .grid {
+      display: grid;
+      grid-template-columns: repeat(${columns}, 1fr);
+      gap: 12px;
+    }
+    .cell {
+      background: #252525;
+      border: 1px solid #333;
+      border-radius: 6px;
+      overflow: hidden;
+      position: relative;
+    }
+    .cell img {
+      width: 100%; height: auto; display: block;
+    }
+    .cell .placeholder {
+      width: 100%; aspect-ratio: 1;
+      background: #2a2a2a;
+      display: flex; align-items: center; justify-content: center;
+      color: #555; font-size: 0.9rem;
+    }
+    .cell .label-bar {
+      padding: 6px 10px;
+      font-size: 0.8rem;
+      background: #2a2a2a;
+      border-top: 1px solid #333;
+    }
+    .cell .label-bar .slot-label { font-weight: 600; color: #ccc; }
+    .cell .label-bar .seed { color: #666; margin-left: 8px; }
+    footer {
+      margin-top: 24px;
+      font-size: 0.75rem; color: #555;
+      text-align: center;
+    }
+  `;
+}
+
+/**
+ * Render a single cell.
+ */
+function renderCell(cell, index, showLabel, showSeed) {
+  const imgTag = cell.hasImage
+    ? `<img src="${escapeHtml(cell.imgPath)}" alt="${escapeHtml(cell.label)}" loading="lazy">`
+    : `<div class="placeholder">${escapeHtml(cell.label)}<br><small>${cell.selected_output || 'no output'}</small></div>`;
+
+  const labelHtml = showLabel
+    ? `<div class="label-bar">
+        <span class="slot-label">${escapeHtml(cell.label)}</span>
+        ${showSeed && cell.seed != null ? `<span class="seed">seed: ${cell.seed}</span>` : ''}
+       </div>`
+    : '';
+
+  return `  <div class="cell">${imgTag}${labelHtml}</div>`;
+}
+
+/**
+ * Find the seed used for a slot's selected output.
+ */
+function findSlotSeed(manifest, slot) {
+  // Not always available — return null if not found
+  return null; // Could be enriched from run manifests later
+}
+
+/**
+ * Escape HTML entities.
+ */
+function escapeHtml(str) {
+  if (!str) return '';
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/**
+ * Save the sheet HTML to the batch sheets directory.
+ */
+export async function saveSheet(batchDir, filename, html) {
+  const sheetsDir = join(batchDir, 'sheets');
+  const sheetPath = join(sheetsDir, filename);
+  await writeFile(sheetPath, html);
+  return sheetPath;
+}