@mcptoolshop/style-dataset-lab 2.3.0 → 3.0.1

package/lib/brief-render.js

@@ -0,0 +1,205 @@
+/**
+ * Brief renderer — converts compiled brief JSON to human-readable formats.
+ */
+
+/**
+ * Render a compiled brief as Markdown.
+ */
+export function renderBriefMarkdown(brief) {
+  const lines = [];
+
+  lines.push(`# Brief: ${brief.brief_id}`);
+  lines.push('');
+  lines.push(`**Workflow:** ${brief.workflow_id}`);
+  lines.push(`**Project:** ${brief.project_id}`);
+  lines.push(`**Lane:** ${brief.lane_id}`);
+  if (brief.subject_id) {
+    lines.push(`**Subject:** ${brief.subject_id}`);
+  }
+  if (brief.training_asset_ref) {
+    lines.push(`**Training Asset:** ${brief.training_asset_ref}`);
+  }
+  if (brief.implementation_pack_ref) {
+    lines.push(`**Implementation Pack:** ${brief.implementation_pack_ref}`);
+  }
+  lines.push('');
+
+  // Prompt
+  lines.push('## Prompt');
+  lines.push('');
+  lines.push('```');
+  lines.push(brief.prompt);
+  lines.push('```');
+  lines.push('');
+
+  // Negative prompt
+  lines.push('## Negative Prompt');
+  lines.push('');
+  lines.push('```');
+  lines.push(brief.negative_prompt);
+  lines.push('```');
+  lines.push('');
+
+  // Canon constraints
+  if (brief.canon_constraints?.length > 0) {
+    lines.push('## Canon Constraints');
+    lines.push('');
+    for (const c of brief.canon_constraints) {
+      lines.push(`- ${c}`);
+    }
+    lines.push('');
+  }
+
+  // Subject constraints
+  if (brief.subject_constraints?.length > 0) {
+    lines.push('## Subject Constraints');
+    lines.push('');
+    for (const c of brief.subject_constraints) {
+      lines.push(`- ${c}`);
+    }
+    lines.push('');
+  }
+
+  // Drift warnings
+  if (brief.drift_warnings?.length > 0) {
+    lines.push('## Drift Warnings');
+    lines.push('');
+    for (const w of brief.drift_warnings) {
+      lines.push(`- ⚠ ${w}`);
+    }
+    lines.push('');
+  }
+
+  // Runtime plan
+  lines.push('## Runtime Plan');
+  lines.push('');
+  lines.push('| Parameter | Value |');
+  lines.push('|-----------|-------|');
+  const rp = brief.runtime_plan;
+  if (rp) {
+    lines.push(`| Adapter | ${rp.adapter_target} |`);
+    lines.push(`| Width | ${rp.width} |`);
+    lines.push(`| Height | ${rp.height} |`);
+    lines.push(`| Steps | ${rp.steps} |`);
+    lines.push(`| CFG | ${rp.cfg} |`);
+    lines.push(`| Sampler | ${rp.sampler} |`);
+    lines.push(`| Seed Mode | ${rp.seed_mode} |`);
+  }
+  lines.push('');
+
+  // Expected outputs
+  lines.push('## Expected Outputs');
+  lines.push('');
+  const eo = brief.expected_outputs;
+  if (eo) {
+    lines.push(`- **Mode:** ${eo.output_mode}`);
+    lines.push(`- **Count:** ${eo.output_count}`);
+    if (eo.review_surface) {
+      lines.push(`- **Review Surface:** ${eo.review_surface}`);
+    }
+  }
+  lines.push('');
+
+  // Selected references
+  if (brief.reference_selection?.length > 0) {
+    lines.push('## Selected References');
+    lines.push('');
+    for (const ref of brief.reference_selection) {
+      lines.push(`- **${ref.record_id}** (${ref.role}): ${ref.reason}`);
+    }
+    lines.push('');
+  }
+
+  // Metadata
+  lines.push('---');
+  lines.push('');
+  lines.push(`Compiled: ${brief.compiled_at}`);
+  lines.push(`Config fingerprint: \`${brief.config_fingerprint}\``);
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Render a compiled brief as plain text for terminal output.
+ */
+export function renderBriefText(brief) {
+  const lines = [];
+
+  lines.push(`\x1b[1mBrief: ${brief.brief_id}\x1b[0m`);
+  lines.push(`  Workflow:  ${brief.workflow_id}`);
+  lines.push(`  Project:   ${brief.project_id}`);
+  lines.push(`  Lane:      ${brief.lane_id}`);
+  if (brief.subject_id) {
+    lines.push(`  Subject:   ${brief.subject_id}`);
+  }
+  if (brief.training_asset_ref) {
+    lines.push(`  Asset:     ${brief.training_asset_ref}`);
+  }
+  lines.push('');
+
+  lines.push('\x1b[1mPrompt:\x1b[0m');
+  lines.push(`  ${brief.prompt}`);
+  lines.push('');
+
+  lines.push('\x1b[1mNegative:\x1b[0m');
+  lines.push(`  ${brief.negative_prompt}`);
+  lines.push('');
+
+  if (brief.canon_constraints?.length > 0) {
+    lines.push('\x1b[1mCanon Constraints:\x1b[0m');
+    for (const c of brief.canon_constraints) {
+      lines.push(`  • ${c}`);
+    }
+    lines.push('');
+  }
+
+  if (brief.subject_constraints?.length > 0) {
+    lines.push('\x1b[1mSubject Constraints:\x1b[0m');
+    for (const c of brief.subject_constraints) {
+      lines.push(`  • ${c}`);
+    }
+    lines.push('');
+  }
+
+  if (brief.drift_warnings?.length > 0) {
+    lines.push('\x1b[1mDrift Warnings:\x1b[0m');
+    for (const w of brief.drift_warnings) {
+      lines.push(`  \x1b[33m⚠\x1b[0m ${w}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('\x1b[1mRuntime Plan:\x1b[0m');
+  const rp = brief.runtime_plan;
+  if (rp) {
+    lines.push(`  Adapter:   ${rp.adapter_target}`);
+    lines.push(`  Size:      ${rp.width}×${rp.height}`);
+    lines.push(`  Steps:     ${rp.steps}`);
+    lines.push(`  CFG:       ${rp.cfg}`);
+    lines.push(`  Sampler:   ${rp.sampler}`);
+    lines.push(`  Seed mode: ${rp.seed_mode}`);
+  }
+  lines.push('');
+
+  lines.push('\x1b[1mExpected Outputs:\x1b[0m');
+  const eo = brief.expected_outputs;
+  if (eo) {
+    lines.push(`  Mode:  ${eo.output_mode}`);
+    lines.push(`  Count: ${eo.output_count}`);
+  }
+  lines.push('');
+
+  if (brief.reference_selection?.length > 0) {
+    lines.push('\x1b[1mSelected References:\x1b[0m');
+    for (const ref of brief.reference_selection) {
+      lines.push(`  ${ref.record_id} (${ref.role}) — ${ref.reason}`);
+    }
+    lines.push('');
+  }
+
+  lines.push(`  Compiled:    ${brief.compiled_at}`);
+  lines.push(`  Fingerprint: ${brief.config_fingerprint}`);
+
+  return lines.join('\n');
+}

package/lib/card.js

@@ -70,6 +70,13 @@ export async function generateCard(projectRoot, snapshotId, splitId) {
   return { markdown, json };
 }
 
+// D-025: safe percentage formatter — renders '—' for zero-total cases
+// instead of 'NaN%'.
+function pct(numerator, denominator) {
+  if (!denominator || denominator <= 0) return '—';
+  return `${(numerator / denominator * 100).toFixed(1)}%`;
+}
+
 function renderMarkdown(card, config) {
   const lines = [];
   const add = (s = '') => lines.push(s);
@@ -87,7 +94,7 @@ function renderMarkdown(card, config) {
   add(`- **Snapshot:** \`${card.snapshot.id}\``);
   add(`- **Config fingerprint:** \`${card.snapshot.config_fingerprint.slice(0, 16)}...\``);
   add(`- **Total records evaluated:** ${card.snapshot.total_records}`);
-  add(`- **Included:** ${card.snapshot.included} (${(card.snapshot.included / card.snapshot.total_records * 100).toFixed(1)}%)`);
+  add(`- **Included:** ${card.snapshot.included} (${pct(card.snapshot.included, card.snapshot.total_records)})`);
   add(`- **Excluded:** ${card.snapshot.excluded}`);
   add();
 
@@ -111,9 +118,9 @@ function renderMarkdown(card, config) {
   add('| Partition | Records | % |');
   add('|-----------|---------|---|');
   const total = card.split.counts.total_records;
-  add(`| Train | ${card.split.counts.train} | ${(card.split.counts.train / total * 100).toFixed(1)}% |`);
-  add(`| Val | ${card.split.counts.val} | ${(card.split.counts.val / total * 100).toFixed(1)}% |`);
-  add(`| Test | ${card.split.counts.test} | ${(card.split.counts.test / total * 100).toFixed(1)}% |`);
+  add(`| Train | ${card.split.counts.train} | ${pct(card.split.counts.train, total)} |`);
+  add(`| Val | ${card.split.counts.val} | ${pct(card.split.counts.val, total)} |`);
+  add(`| Test | ${card.split.counts.test} | ${pct(card.split.counts.test, total)} |`);
   add();
 
   add('## Lane Balance');

package/lib/comfyui.js

@@ -6,9 +6,15 @@
  */
 
 import { readFile } from 'node:fs/promises';
+import { info } from './log.js';
 
 const DEFAULT_URL = 'http://127.0.0.1:8188';
 const MAX_POLL_MS = 600_000; // 10 minutes
+const HEARTBEAT_MS = 15_000; // emit a heartbeat at most every 15s
+// PB-004: if we see an unfamiliar status shape for this many consecutive
+// polls without completed/error, bail with a descriptive message rather
+// than hang until MAX_POLL_MS.
+const UNKNOWN_STATUS_BAIL_POLLS = 30; // ~30s of unrecognized shape
 
 /**
  * Check if ComfyUI is reachable.
@@ -48,21 +54,102 @@ export async function submitAndWait(workflow, comfyUrl = DEFAULT_URL, opts = {})
 
   const { prompt_id: promptId } = await res.json();
 
+  const MAX_CONSECUTIVE_HISTORY_FAILURES = 5;
+  let consecutiveHistoryFailures = 0;
+  // PB-001: heartbeats
+  let lastHeartbeatAt = Date.now();
+  let announcedStart = false;
+  let seenEntry = false;
+  // PB-004: count polls where entry exists but status shape is unfamiliar
+  let unknownStatusPolls = 0;
+  let lastObservedStatus = null;
   const start = Date.now();
   while (true) {
-    if (Date.now() - start > timeoutMs) {
+    const now = Date.now();
+    if (now - start > timeoutMs) {
       throw new Error(`ComfyUI poll timeout after ${timeoutMs / 1000}s for prompt ${promptId}`);
     }
     await new Promise(r => setTimeout(r, 1000));
-    const histRes = await fetch(`${comfyUrl}/history/${promptId}`);
-    if (!histRes.ok) continue;
+    let histRes;
+    try {
+      histRes = await fetch(`${comfyUrl}/history/${promptId}`);
+    } catch (err) {
+      consecutiveHistoryFailures++;
+      if (consecutiveHistoryFailures >= MAX_CONSECUTIVE_HISTORY_FAILURES) {
+        throw new Error(
+          `ComfyUI history endpoint unreachable after ${MAX_CONSECUTIVE_HISTORY_FAILURES} consecutive attempts for prompt ${promptId}: ${err.message}`
+        );
+      }
+      continue;
+    }
+    if (!histRes.ok) {
+      consecutiveHistoryFailures++;
+      if (consecutiveHistoryFailures >= MAX_CONSECUTIVE_HISTORY_FAILURES) {
+        throw new Error(
+          `ComfyUI history endpoint returned ${histRes.status} ${MAX_CONSECUTIVE_HISTORY_FAILURES} times in a row for prompt ${promptId}`
+        );
+      }
+      continue;
+    }
+    consecutiveHistoryFailures = 0;
     const history = await histRes.json();
     const entry = history[promptId];
-    if (!entry) continue;
-    if (entry.status?.completed) return entry;
+
+    // PB-001: emit heartbeats so the user knows the pipeline isn't hung.
+    const elapsedSec = Math.round((Date.now() - start) / 1000);
+    const heartbeatDue = Date.now() - lastHeartbeatAt >= HEARTBEAT_MS;
+    if (!entry) {
+      // Queued on ComfyUI but not yet visible in /history.
+      if (!announcedStart) {
+        info(`ComfyUI: queued (prompt ${promptId})`);
+        announcedStart = true;
+        lastHeartbeatAt = Date.now();
+      } else if (heartbeatDue) {
+        info(`ComfyUI: queued, waiting... (${elapsedSec}s)`);
+        lastHeartbeatAt = Date.now();
+      }
+      continue;
+    }
+
+    if (!seenEntry) {
+      seenEntry = true;
+      info(`ComfyUI: generating... (prompt ${promptId})`);
+      lastHeartbeatAt = Date.now();
+    } else if (heartbeatDue) {
+      info(`ComfyUI: generating... (${elapsedSec}s elapsed)`);
+      lastHeartbeatAt = Date.now();
+    }
+
+    // PB-004: success signals — accept both completed===true and status_str==='success'
+    // (future-proof for schema drift where one may change without the other).
+    if (entry.status?.completed === true || entry.status?.status_str === 'success') {
+      info(`ComfyUI: completed in ${elapsedSec}s`);
+      return entry;
+    }
+
+    // PB-004: known failure signals — bail immediately.
     if (entry.status?.status_str === 'error') {
       throw new Error(`ComfyUI generation failed: ${JSON.stringify(entry.status)}`);
     }
+    if (entry.status?.execution_error || entry.execution_error) {
+      const errObj = entry.status?.execution_error || entry.execution_error;
+      throw new Error(`ComfyUI execution error for prompt ${promptId}: ${JSON.stringify(errObj)}`);
+    }
+
+    // PB-004: the entry exists but matches neither a known success nor
+    // a known failure. This is the schema-drift hang scenario — count
+    // consecutive unknown-shape polls and bail with context.
+    const statusStr = entry.status?.status_str ?? null;
+    lastObservedStatus = entry.status ?? null;
+    unknownStatusPolls++;
+    if (unknownStatusPolls >= UNKNOWN_STATUS_BAIL_POLLS) {
+      throw new Error(
+        `ComfyUI returned an unrecognized status shape for prompt ${promptId} ` +
+        `after ${unknownStatusPolls} polls (status_str=${JSON.stringify(statusStr)}). ` +
+        `This usually means the ComfyUI history schema changed. ` +
+        `Observed status: ${JSON.stringify(lastObservedStatus)}`
+      );
+    }
   }
 }
 
@@ -75,7 +162,14 @@ export async function submitAndWait(workflow, comfyUrl = DEFAULT_URL, opts = {})
  * @returns {Promise<Buffer>}
  */
 export async function downloadImage(filename, subfolder, comfyUrl = DEFAULT_URL, type = 'output') {
-  const url = `${comfyUrl}/view?filename=${encodeURIComponent(filename)}&subfolder=${encodeURIComponent(subfolder || '')}&type=${type}`;
+  const ALLOWED_TYPES = ['output', 'input', 'temp'];
+  if (!ALLOWED_TYPES.includes(type)) {
+    throw new Error(`Invalid ComfyUI image type "${type}" — must be one of: ${ALLOWED_TYPES.join(', ')}`);
+  }
+  if (typeof comfyUrl !== 'string' || comfyUrl.length === 0 || !/^https?:\/\//i.test(comfyUrl)) {
+    throw new Error(`Invalid comfyUrl "${comfyUrl}" — must start with http:// or https://`);
+  }
+  const url = `${comfyUrl}/view?filename=${encodeURIComponent(filename)}&subfolder=${encodeURIComponent(subfolder || '')}&type=${encodeURIComponent(type)}`;
   const res = await fetch(url);
   if (!res.ok) throw new Error(`Download failed: ${res.status}`);
   return Buffer.from(await res.arrayBuffer());

package/lib/config.js

@@ -7,17 +7,70 @@
  */
 
 import { readFileSync, existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { inputError, runtimeError } from './errors.js';
 
 function loadJsonFile(filePath) {
   if (!existsSync(filePath)) return null;
   try {
     return JSON.parse(readFileSync(filePath, 'utf-8'));
   } catch (err) {
-    throw new Error(`Failed to parse ${filePath}: ${err.message}`);
+    throw runtimeError(
+      'INPUT_INVALID_JSON',
+      `Failed to parse ${filePath}: ${err.message}`,
+      'Check the file for JSON syntax errors (trailing commas, unquoted keys, etc).',
+      err
+    );
   }
 }
 
+/**
+ * Async-safe readFile + JSON.parse with structured error handling.
+ * Optionally validates that required top-level fields are present.
+ *
+ * @param {string} filePath — absolute path to a JSON file
+ * @param {{requiredFields?: string[]}} [opts]
+ */
+export async function readJsonFile(filePath, opts = {}) {
+  let raw;
+  try {
+    raw = await readFile(filePath, 'utf-8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      throw inputError(
+        'INPUT_FILE_NOT_FOUND',
+        `File not found: ${filePath}`,
+        'Check the path and try again.'
+      );
+    }
+    throw runtimeError('RUNTIME_READ_FAILED', `Could not read ${filePath}: ${err.message}`, null, err);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw runtimeError(
+      'INPUT_INVALID_JSON',
+      `Failed to parse ${filePath}: ${err.message}`,
+      'Check the file for JSON syntax errors.',
+      err
+    );
+  }
+  const required = opts.requiredFields || [];
+  if (required.length) {
+    const missing = required.filter((f) => parsed == null || parsed[f] === undefined);
+    if (missing.length) {
+      throw inputError(
+        'INPUT_MISSING_FIELDS',
+        `${filePath} is missing required fields: ${missing.join(', ')}`,
+        `Add the fields to the file, or use a valid example as template.`
+      );
+    }
+  }
+  return parsed;
+}
+
 /**
  * Load project.json — project identity and generation defaults.
  */
@@ -42,7 +95,13 @@ export function loadConstitution(projectRoot) {
   const data = loadJsonFile(join(projectRoot, 'constitution.json'));
   if (!data) return { rules: [] };
   if (Array.isArray(data)) return { rules: data };
-  if (!data.rules) throw new Error(`constitution.json must have a "rules" array`);
+  if (!data.rules) {
+    throw inputError(
+      'INPUT_BAD_CONFIG',
+      `constitution.json must have a "rules" array`,
+      'Wrap your rules in { "rules": [...] } or use an array at the top level.'
+    );
+  }
   return data;
 }
 
@@ -54,7 +113,13 @@ export function loadLanes(projectRoot) {
   if (!data) {
     return { default_lane: 'default', lanes: [] };
   }
-  if (!data.lanes) throw new Error(`lanes.json must have a "lanes" array`);
+  if (!data.lanes) {
+    throw inputError(
+      'INPUT_BAD_CONFIG',
+      `lanes.json must have a "lanes" array`,
+      'Top-level shape: { "default_lane": "...", "lanes": [ ... ] }.'
+    );
+  }
   return data;
 }