@mcptoolshop/style-dataset-lab 3.3.0 → 3.5.0

package/lib/comfyui.js

@@ -16,36 +16,114 @@ const HEARTBEAT_MS = 15_000; // emit a heartbeat at most every 15s
 // than hang until MAX_POLL_MS.
 const UNKNOWN_STATUS_BAIL_POLLS = 30; // ~30s of unrecognized shape
 
+// SDL-H8: per-REQUEST timeout, distinct from the per-CALL poll budget
+// (timeoutMs/MAX_POLL_MS above, which only bounds the interval *between*
+// requests). Without this, a ComfyUI that accepts the TCP connection and
+// never responds hangs `await fetch()` forever — a hang never rejects, so
+// no retry/catch logic anywhere downstream ever fires. Configurable via env
+// so operators can widen it for a slow/remote ComfyUI without a code change.
+const DEFAULT_REQUEST_TIMEOUT_MS = Number(process.env.SDLAB_COMFY_REQUEST_TIMEOUT_MS) || 30_000;
+
+/**
+ * fetch() with a hard per-request timeout via AbortController. Guarantees
+ * the returned promise always settles (resolve or reject) within
+ * `timeoutMs`, even against a server that accepts the connection and then
+ * never responds. On timeout, rejects with a plain Error (not a raw
+ * AbortError/DOMException) naming the URL and elapsed time, so it reads
+ * like any other network failure to callers' existing catch/retry logic.
+ *
+ * @param {string} url
+ * @param {RequestInit} [init]
+ * @param {number} [timeoutMs]
+ * @returns {Promise<Response>}
+ */
+async function fetchWithTimeout(url, init = {}, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  const start = Date.now();
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } catch (err) {
+    if (err?.name === 'AbortError') {
+      const elapsedSec = ((Date.now() - start) / 1000).toFixed(1);
+      throw new Error(
+        `ComfyUI request timed out after ${elapsedSec}s (limit ${(timeoutMs / 1000).toFixed(1)}s): ${url}`
+      );
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 /**
- * Check if ComfyUI is reachable.
+ * B04: comfyHealth() used to collapse EVERY failure mode into a bare
+ * `false` via `catch { return false }` with no bound error. A 503 while a
+ * custom node loads, a refused connection, a DNS typo, and a genuine
+ * timeout all produced the identical "ComfyUI not reachable — start
+ * ComfyUI" message downstream — factually wrong for the 503 (ComfyUI IS
+ * reachable and running) and useless for the others (starting ComfyUI does
+ * not fix a DNS typo).
+ *
+ * Check if ComfyUI is reachable, WITH a reason when it isn't.
+ *
  * @param {string} [comfyUrl]
- * @returns {Promise<boolean>}
+ * @param {{timeoutMs?: number}} [opts]
+ * @returns {Promise<{ok: boolean, reason: string|null}>} reason is one of
+ *   'timeout' | 'refused' | 'dns' | 'http-<status>' | 'unknown' | null (when ok)
  */
-export async function comfyHealth(comfyUrl = DEFAULT_URL) {
+export async function comfyHealthDetailed(comfyUrl = DEFAULT_URL, opts = {}) {
   try {
-    const res = await fetch(`${comfyUrl}/system_stats`);
-    return res.ok;
-  } catch {
-    return false;
+    const res = await fetchWithTimeout(`${comfyUrl}/system_stats`, {}, opts.timeoutMs);
+    if (res.ok) return { ok: true, reason: null };
+    return { ok: false, reason: `http-${res.status}` };
+  } catch (err) {
+    if (/timed out/i.test(err?.message || '')) return { ok: false, reason: 'timeout' };
+    const code = err?.cause?.code || err?.code;
+    if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') return { ok: false, reason: 'dns' };
+    if (code === 'ECONNREFUSED' || code === 'ECONNRESET') return { ok: false, reason: 'refused' };
+    return { ok: false, reason: 'unknown' };
   }
 }
 
+/**
+ * Check if ComfyUI is reachable. Thin plain-boolean wrapper over
+ * comfyHealthDetailed() — kept as a SEPARATE, unchanged-signature export
+ * because 5 scripts (generate.js, generate-identity.js,
+ * generate-controlnet.js, generate-ipadapter.js, painterly.js) already call
+ * `if (!(await comfyHealth(...)))`; returning a richer object here would
+ * make every one of those checks permanently truthy (an object is always
+ * truthy) and silently disable their offline handling.
+ *
+ * @param {string} [comfyUrl]
+ * @param {{timeoutMs?: number}} [opts]
+ * @returns {Promise<boolean>}
+ */
+export async function comfyHealth(comfyUrl = DEFAULT_URL, opts = {}) {
+  const { ok } = await comfyHealthDetailed(comfyUrl, opts);
+  return ok;
+}
+
 /**
  * Submit a workflow and poll until complete.
  * @param {Object} workflow — ComfyUI prompt graph
  * @param {string} [comfyUrl]
- * @param {{ clientPrefix?: string, timeoutMs?: number }} [opts]
+ * @param {{ clientPrefix?: string, timeoutMs?: number, requestTimeoutMs?: number }} [opts]
+ *   `timeoutMs` bounds the OVERALL poll loop (unchanged, default 10 min).
+ *   `requestTimeoutMs` (SDL-H8) bounds each INDIVIDUAL fetch — the submit
+ *   POST and every /history poll — so a server that never responds can't
+ *   hang the whole call forever.
  * @returns {Promise<Object>} — history entry
  */
 export async function submitAndWait(workflow, comfyUrl = DEFAULT_URL, opts = {}) {
-  const { clientPrefix = 'sdl', timeoutMs = MAX_POLL_MS } = opts;
+  const { clientPrefix = 'sdl', timeoutMs = MAX_POLL_MS, requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS } = opts;
   const clientId = `${clientPrefix}-${Date.now()}`;
 
-  const res = await fetch(`${comfyUrl}/prompt`, {
+  const res = await fetchWithTimeout(`${comfyUrl}/prompt`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ prompt: workflow, client_id: clientId }),
-  });
+  }, requestTimeoutMs);
 
   if (!res.ok) {
     const text = await res.text();
@@ -72,7 +150,10 @@ export async function submitAndWait(workflow, comfyUrl = DEFAULT_URL, opts = {})
     await new Promise(r => setTimeout(r, 1000));
     let histRes;
     try {
-      histRes = await fetch(`${comfyUrl}/history/${promptId}`);
+      // SDL-H8: bounded so a server that accepts the connection and never
+      // responds lands in this catch (as an AbortError → clear timeout
+      // Error) instead of hanging `await fetch()` forever.
+      histRes = await fetchWithTimeout(`${comfyUrl}/history/${promptId}`, {}, requestTimeoutMs);
     } catch (err) {
       consecutiveHistoryFailures++;
       if (consecutiveHistoryFailures >= MAX_CONSECUTIVE_HISTORY_FAILURES) {
@@ -91,8 +172,23 @@ export async function submitAndWait(workflow, comfyUrl = DEFAULT_URL, opts = {})
       }
       continue;
     }
+    // SDL-L3: histRes.json() used to sit outside the retry block above, so
+    // a 200-OK non-JSON body (e.g. a proxy error page) threw a raw
+    // SyntaxError here, uncaught, permanently failing the image the
+    // adjacent 5-strike tolerance would otherwise have recovered from.
+    let history;
+    try {
+      history = await histRes.json();
+    } catch (err) {
+      consecutiveHistoryFailures++;
+      if (consecutiveHistoryFailures >= MAX_CONSECUTIVE_HISTORY_FAILURES) {
+        throw new Error(
+          `ComfyUI history endpoint returned an unparseable response ${MAX_CONSECUTIVE_HISTORY_FAILURES} times in a row for prompt ${promptId}: ${err.message}`
+        );
+      }
+      continue;
+    }
     consecutiveHistoryFailures = 0;
-    const history = await histRes.json();
     const entry = history[promptId];
 
     // PB-001: emit heartbeats so the user knows the pipeline isn't hung.
@@ -159,9 +255,10 @@ export async function submitAndWait(workflow, comfyUrl = DEFAULT_URL, opts = {})
  * @param {string} [subfolder]
  * @param {string} [comfyUrl]
  * @param {string} [type='output']
+ * @param {{timeoutMs?: number}} [opts]
  * @returns {Promise<Buffer>}
  */
-export async function downloadImage(filename, subfolder, comfyUrl = DEFAULT_URL, type = 'output') {
+export async function downloadImage(filename, subfolder, comfyUrl = DEFAULT_URL, type = 'output', opts = {}) {
   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(', ')}`);
@@ -170,7 +267,7 @@ export async function downloadImage(filename, subfolder, comfyUrl = DEFAULT_URL,
     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);
+  const res = await fetchWithTimeout(url, {}, opts.timeoutMs);
   if (!res.ok) throw new Error(`Download failed: ${res.status}`);
   return Buffer.from(await res.arrayBuffer());
 }
@@ -180,18 +277,19 @@ export async function downloadImage(filename, subfolder, comfyUrl = DEFAULT_URL,
  * @param {string} filePath — local file to upload
  * @param {string} filename — name to assign in ComfyUI
  * @param {string} [comfyUrl]
+ * @param {{timeoutMs?: number}} [opts]
  * @returns {Promise<string>} — assigned name from ComfyUI
  */
-export async function uploadImage(filePath, filename, comfyUrl = DEFAULT_URL) {
+export async function uploadImage(filePath, filename, comfyUrl = DEFAULT_URL, opts = {}) {
   const data = await readFile(filePath);
   const formData = new FormData();
   formData.append('image', new Blob([data], { type: 'image/png' }), filename);
   formData.append('overwrite', 'true');
 
-  const res = await fetch(`${comfyUrl}/upload/image`, {
+  const res = await fetchWithTimeout(`${comfyUrl}/upload/image`, {
     method: 'POST',
     body: formData,
-  });
+  }, opts.timeoutMs);
 
   if (!res.ok) {
     const text = await res.text();

package/lib/config.js

@@ -10,6 +10,7 @@ import { readFileSync, existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { inputError, runtimeError } from './errors.js';
+import { warn } from './log.js';
 
 function loadJsonFile(filePath) {
   if (!existsSync(filePath)) return null;
@@ -25,6 +26,80 @@ function loadJsonFile(filePath) {
   }
 }
 
+/**
+ * Validate a user-authored regex pattern string at CONFIG LOAD TIME rather
+ * than lazily inside detectLane()/detectGroup() on whatever record happens
+ * to process first.
+ *
+ * B02: detectLane()/detectGroup() build `new RegExp(pattern)` from strings
+ * loaded verbatim from lanes.json/terminology.json across 7 construction
+ * sites, with zero validation before this. One unescaped bracket
+ * (`"[freeport"`) used to abort a whole `sdlab bind` pass with a raw
+ * `SyntaxError: Invalid regular expression` naming neither the file, the
+ * lane/group, nor the offending pattern — finding it required manual
+ * bisection of the config. This throws ONE structured error naming all
+ * three, before any record is processed.
+ *
+ * @param {string} pattern
+ * @param {{file: string, context: string}} where
+ */
+function validateRegexPattern(pattern, { file, context }) {
+  try {
+    // eslint-disable-next-line no-new -- validation only, result unused
+    new RegExp(pattern);
+  } catch (err) {
+    throw inputError(
+      'INPUT_BAD_REGEX',
+      `Invalid regex pattern in ${file} (${context}): "${pattern}" — ${err.message}`,
+      'Fix or escape the pattern (e.g. escape literal brackets/parens/braces) and try again.'
+    );
+  }
+}
+
+/**
+ * Validate every id_patterns entry across all lanes in a loaded lanes.json.
+ * Fails fast on the FIRST invalid pattern (not an aggregate report) so the
+ * thrown error always names one concrete offending pattern.
+ */
+function validateLanePatterns(lanesData) {
+  for (const lane of lanesData.lanes || []) {
+    for (const pattern of lane.id_patterns || []) {
+      validateRegexPattern(pattern, { file: 'lanes.json', context: `lane "${lane.id}"` });
+    }
+  }
+}
+
+/**
+ * Validate every pattern site across a loaded terminology.json: per-group
+ * id_patterns/prompt_patterns, plus the four dict/array pattern collections
+ * detectGroup() also builds RegExp from (cross_group_patterns, edge_defaults,
+ * null_faction_patterns, id_fallbacks) — the full set of 6 sites detectGroup()
+ * itself constructs (the 7th is detectLane()'s single site, covered by
+ * validateLanePatterns above).
+ */
+function validateTerminologyPatterns(termData) {
+  for (const [groupName, group] of Object.entries(termData.groups || {})) {
+    for (const pattern of group?.id_patterns || []) {
+      validateRegexPattern(pattern, { file: 'terminology.json', context: `group "${groupName}" id_patterns` });
+    }
+    for (const pattern of group?.prompt_patterns || []) {
+      validateRegexPattern(pattern, { file: 'terminology.json', context: `group "${groupName}" prompt_patterns` });
+    }
+  }
+  for (const pattern of Object.keys(termData.cross_group_patterns || {})) {
+    validateRegexPattern(pattern, { file: 'terminology.json', context: 'cross_group_patterns' });
+  }
+  for (const pattern of Object.keys(termData.edge_defaults || {})) {
+    validateRegexPattern(pattern, { file: 'terminology.json', context: 'edge_defaults' });
+  }
+  for (const pattern of termData.null_faction_patterns || []) {
+    validateRegexPattern(pattern, { file: 'terminology.json', context: 'null_faction_patterns' });
+  }
+  for (const pattern of Object.keys(termData.id_fallbacks || {})) {
+    validateRegexPattern(pattern, { file: 'terminology.json', context: 'id_fallbacks' });
+  }
+}
+
 /**
  * Async-safe readFile + JSON.parse with structured error handling.
  * Optionally validates that required top-level fields are present.
@@ -75,8 +150,12 @@ export async function readJsonFile(filePath, opts = {}) {
  * Load project.json — project identity and generation defaults.
  */
 export function loadProjectMeta(projectRoot) {
-  const data = loadJsonFile(join(projectRoot, 'project.json'));
-  if (!data) {
+  const filePath = join(projectRoot, 'project.json');
+  if (!existsSync(filePath)) {
+    // B05: this loader used to substitute its default with zero logging —
+    // the module didn't even import lib/log.js. A dropped/never-created
+    // project.json now names its expected path instead of degrading silently.
+    warn(`project.json not found at ${filePath} — using built-in defaults (name: "unknown")`);
     return {
       name: 'unknown',
       display_name: 'Unknown Project',
@@ -85,7 +164,7 @@ export function loadProjectMeta(projectRoot) {
       defaults: {},
     };
   }
-  return data;
+  return loadJsonFile(filePath);
 }
 
 /**
@@ -111,8 +190,14 @@ export function resolveGpuModel(projectDefaults) {
  * Load constitution.json — array of rule objects.
  */
 export function loadConstitution(projectRoot) {
-  const data = loadJsonFile(join(projectRoot, 'constitution.json'));
-  if (!data) return { rules: [] };
+  const filePath = join(projectRoot, 'constitution.json');
+  if (!existsSync(filePath)) {
+    // B05: see loadProjectMeta above — warn once, naming the expected path,
+    // instead of silently substituting the empty-rules default.
+    warn(`constitution.json not found at ${filePath} — using built-in defaults (no rules configured)`);
+    return { rules: [] };
+  }
+  const data = loadJsonFile(filePath);
   if (Array.isArray(data)) return { rules: data };
   if (!data.rules) {
     throw inputError(
@@ -128,10 +213,14 @@ export function loadConstitution(projectRoot) {
  * Load lanes.json — lane definitions with detection patterns.
  */
 export function loadLanes(projectRoot) {
-  const data = loadJsonFile(join(projectRoot, 'lanes.json'));
-  if (!data) {
+  const filePath = join(projectRoot, 'lanes.json');
+  if (!existsSync(filePath)) {
+    // B05: warn once, naming the expected path, instead of silently
+    // substituting the no-lanes default.
+    warn(`lanes.json not found at ${filePath} — using built-in defaults (no lanes configured)`);
     return { default_lane: 'default', lanes: [] };
   }
+  const data = loadJsonFile(filePath);
   if (!data.lanes) {
     throw inputError(
       'INPUT_BAD_CONFIG',
@@ -139,6 +228,9 @@ export function loadLanes(projectRoot) {
       'Top-level shape: { "default_lane": "...", "lanes": [ ... ] }.'
     );
   }
+  // B02: validate every id_patterns regex now, before any record is ever
+  // tested against it — see validateRegexPattern's docstring above.
+  validateLanePatterns(data);
   return data;
 }
 
@@ -146,23 +238,31 @@ export function loadLanes(projectRoot) {
  * Load rubric.json — scoring dimensions, thresholds, failure modes.
  */
 export function loadRubric(projectRoot) {
-  const data = loadJsonFile(join(projectRoot, 'rubric.json'));
-  if (!data) {
+  const filePath = join(projectRoot, 'rubric.json');
+  if (!existsSync(filePath)) {
+    // B05: warn once, naming the expected path, instead of silently
+    // substituting the built-in thresholds default.
+    warn(`rubric.json not found at ${filePath} — using built-in defaults (pass=0.7/partial=0.5/fail_ceiling=0.4)`);
     return {
       dimensions: [],
       thresholds: { pass: 0.7, partial: 0.5, fail_ceiling: 0.4 },
       failure_to_rules: {},
     };
   }
-  return data;
+  return loadJsonFile(filePath);
 }
 
 /**
  * Load terminology.json — group vocabulary and detection patterns.
  */
 export function loadTerminology(projectRoot) {
-  const data = loadJsonFile(join(projectRoot, 'terminology.json'));
-  if (!data) {
+  const filePath = join(projectRoot, 'terminology.json');
+  if (!existsSync(filePath)) {
+    // B05: this is the finding's own example — a dropped terminology.json
+    // used to make detectGroup() return null for every record with zero
+    // signal. Warn once, naming the expected path, instead of substituting
+    // the empty-groups default silently.
+    warn(`terminology.json not found at ${filePath} — using built-in defaults (no groups configured)`);
     return {
       group_label: 'group',
       groups: {},
@@ -171,6 +271,10 @@ export function loadTerminology(projectRoot) {
       prompt_fallbacks: {},
     };
   }
+  const data = loadJsonFile(filePath);
+  // B02: validate every pattern site now, before any record is ever tested
+  // against it — see validateRegexPattern's docstring above.
+  validateTerminologyPatterns(data);
   return data;
 }
 

package/lib/critique-engine.js

@@ -255,6 +255,17 @@ export function critiqueCandidate({ brief, workflow, candidate, activeDimensions
     filename: candidate.filename,
     seed: candidate.seed,
     overall_fit: 'usable', // Default — human or LLM overrides
+    // H2: this is the ONLY assignment site for overall_fit anywhere in the
+    // codebase — nothing currently overrides it, so every candidate in
+    // every critique report is uniformly 'usable' by construction. That is
+    // a non-judgment ("nobody has looked at the image yet"), not a judgment
+    // ("looked, and they're all fine") — `reviewed: false` records which one
+    // this is so recommendAction() (below) and the CLI can tell the two
+    // apart instead of presenting keyword-drift tiebreaking as a considered
+    // recommendation. Flip to true at the (future, NOT built here — see the
+    // finding's explicit scoping note) point where a human or LLM judge
+    // actually assesses fit and overrides overall_fit.
+    reviewed: false,
     // EXTERNAL_VERIFIER: this rule-based engine is a different artifact class
     // from the image generator, so it is a legitimate cross-artifact verifier.
     judged_by_model: RULE_BASED_JUDGE,
@@ -301,12 +312,27 @@ export function triageCandidates(candidates, { driftThreshold = DEFAULT_DRIFT_TH
 
 /**
  * Derive a run-level recommended action from candidate notes.
+ *
+ * H2: `overall_fit: 'usable'` (critiqueCandidate's default, and — today —
+ * its ONLY assignment anywhere in the codebase) means "nobody has assessed
+ * fit yet", not "assessed and found uniformly usable". Before this fix,
+ * recommendAction() could not tell those two states apart, so an unreviewed
+ * run always took the same `usable.length > 0` branch a genuinely-reviewed
+ * run would, picking a "preferred" candidate by brief-keyword drift count —
+ * not by looking at the image — and presenting it with the same confidence
+ * either way. `reviewed` on the returned recommendation lets the CLI (see
+ * scripts/critique.js) qualify or suppress the auto "Next:" suggestion when
+ * nothing has actually been reviewed, without changing `mode` /
+ * `preferred_candidate` semantics for callers that don't look at it —
+ * critique.json's shape stays backward-compatible (additive field only).
  */
 export function recommendAction({ candidates }) {
   if (candidates.length === 0) {
-    return { mode: 'discard_run', reason: 'No candidates in run' };
+    return { mode: 'discard_run', reason: 'No candidates in run', reviewed: false };
   }
 
+  const anyReviewed = candidates.some(c => c.reviewed === true);
+
   const strong = candidates.filter(c => c.overall_fit === 'strong');
   const usable = candidates.filter(c => c.overall_fit === 'usable');
   const offModel = candidates.filter(c => c.overall_fit === 'off-model');
@@ -317,6 +343,7 @@ export function recommendAction({ candidates }) {
       mode: 'accept_one',
       preferred_candidate: strong[0].filename,
       reason: `${strong.length} strong candidate(s) — ${strong[0].filename} is the best fit`,
+      reviewed: anyReviewed,
     };
   }
 
@@ -327,7 +354,12 @@ export function recommendAction({ candidates }) {
     return {
       mode: 'refine_from_one',
       preferred_candidate: sorted[0].filename,
-      reason: `${usable.length} usable candidate(s) — ${sorted[0].filename} has fewest drift issues`,
+      reason: anyReviewed
+        ? `${usable.length} usable candidate(s) — ${sorted[0].filename} has fewest drift issues`
+        : `${usable.length} candidate(s) at the unreviewed default "usable" — nobody has assessed fit yet. ` +
+          `${sorted[0].filename} has the fewest rule-based drift issues, which is a tiebreaker, not a ` +
+          `judgment of the image.`,
+      reviewed: anyReviewed,
     };
   }
 
@@ -336,6 +368,7 @@ export function recommendAction({ candidates }) {
     return {
       mode: 'discard_run',
       reason: 'All candidates are off-model — brief may need fundamental revision',
+      reviewed: anyReviewed,
     };
   }
 
@@ -343,6 +376,7 @@ export function recommendAction({ candidates }) {
   return {
     mode: 'rerun_broader',
     reason: 'No clear winner — try broader seed range or adjusted parameters',
+    reviewed: anyReviewed,
   };
 }