@mcptoolshop/style-dataset-lab 2.3.0 → 3.0.0

package/lib/critique-render.js

@@ -0,0 +1,171 @@
+/**
+ * Critique renderer — converts critique report to human-readable formats.
+ *
+ * Reads like a working note, not a report card.
+ */
+
+// ─── Fit badge ───────────────────────────────────────────────────
+
+const FIT_BADGES = {
+  strong: '✓ strong',
+  usable: '○ usable',
+  'off-model': '✗ off-model',
+};
+
+const FIT_EMOJI = {
+  strong: '🟢',
+  usable: '🟡',
+  'off-model': '🔴',
+};
+
+// ─── Markdown renderer ──────────────────────────────────────────
+
+/**
+ * Render a critique report as Markdown.
+ */
+export function renderCritiqueMarkdown(report) {
+  const lines = [];
+
+  lines.push(`# Critique: ${report.run_id}`);
+  lines.push('');
+  lines.push(`**Brief:** ${report.brief_id}`);
+  lines.push(`**Workflow:** ${report.workflow_id}`);
+  lines.push(`**Project:** ${report.project_id}`);
+  if (report.subject_id) lines.push(`**Subject:** ${report.subject_id}`);
+  lines.push(`**Created:** ${report.created_at}`);
+  lines.push('');
+
+  // Recommended action
+  const action = report.recommended_action;
+  const modeLabel = {
+    accept_one: '✓ Accept one candidate',
+    refine_from_one: '→ Refine from one candidate',
+    rerun_broader: '↻ Rerun with broader parameters',
+    discard_run: '✗ Discard this run',
+  };
+  lines.push('## Recommended Action');
+  lines.push('');
+  lines.push(`**${modeLabel[action.mode] || action.mode}**`);
+  if (action.preferred_candidate) {
+    lines.push(`Preferred: **${action.preferred_candidate}**`);
+  }
+  if (action.reason) lines.push(`Reason: ${action.reason}`);
+  lines.push('');
+
+  // Active dimensions
+  lines.push('## Active Dimensions');
+  lines.push('');
+  for (const dim of report.active_dimensions) {
+    lines.push(`- ${dim.replace(/_/g, ' ')}`);
+  }
+  lines.push('');
+
+  // Candidates
+  lines.push('## Candidates');
+  lines.push('');
+
+  for (const c of report.candidates) {
+    const badge = FIT_EMOJI[c.overall_fit] || '?';
+    lines.push(`### ${badge} ${c.filename} (seed: ${c.seed ?? '?'})`);
+    lines.push('');
+    lines.push(`**Fit:** ${c.overall_fit}`);
+    lines.push('');
+
+    if (c.strengths.length > 0) {
+      lines.push('**Strengths:**');
+      for (const s of c.strengths) lines.push(`- ${s}`);
+      lines.push('');
+    }
+
+    if (c.drift_issues.length > 0) {
+      lines.push('**Drift Issues:**');
+      for (const d of c.drift_issues) lines.push(`- ⚠ ${d}`);
+      lines.push('');
+    }
+
+    if (c.preserve_next_pass.length > 0) {
+      lines.push('**Preserve Next Pass:**');
+      for (const p of c.preserve_next_pass) lines.push(`- ✓ ${p}`);
+      lines.push('');
+    }
+
+    if (c.correct_next_pass.length > 0) {
+      lines.push('**Correct Next Pass:**');
+      for (const x of c.correct_next_pass) lines.push(`- → ${x}`);
+      lines.push('');
+    }
+  }
+
+  // Next-pass direction summary
+  lines.push('## Next-Pass Direction');
+  lines.push('');
+
+  // Aggregate preserve/correct across all candidates
+  const allPreserve = new Set();
+  const allCorrect = new Set();
+  for (const c of report.candidates) {
+    for (const p of c.preserve_next_pass) allPreserve.add(p);
+    for (const x of c.correct_next_pass) allCorrect.add(x);
+  }
+
+  if (allPreserve.size > 0) {
+    lines.push('**Preserve:**');
+    for (const p of allPreserve) lines.push(`- ${p}`);
+    lines.push('');
+  }
+
+  if (allCorrect.size > 0) {
+    lines.push('**Correct:**');
+    for (const x of allCorrect) lines.push(`- ${x}`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+// ─── Terminal text renderer ──────────────────────────────────────
+
+/**
+ * Render a critique report as plain text for terminal display.
+ */
+export function renderCritiqueText(report) {
+  const lines = [];
+
+  lines.push(`Critique: ${report.run_id}`);
+  lines.push(`Brief: ${report.brief_id}  Workflow: ${report.workflow_id}`);
+  if (report.subject_id) lines.push(`Subject: ${report.subject_id}`);
+  lines.push('');
+
+  // Action
+  const action = report.recommended_action;
+  const actionIcon = {
+    accept_one: '✓',
+    refine_from_one: '→',
+    rerun_broader: '↻',
+    discard_run: '✗',
+  };
+  lines.push(`${actionIcon[action.mode] || '?'} ${action.mode.replace(/_/g, ' ')}`);
+  if (action.preferred_candidate) lines.push(`  Preferred: ${action.preferred_candidate}`);
+  if (action.reason) lines.push(`  ${action.reason}`);
+  lines.push('');
+
+  // Dimensions
+  lines.push(`Dimensions: ${report.active_dimensions.map(d => d.replace(/_/g, ' ')).join(', ')}`);
+  lines.push('');
+
+  // Candidates
+  for (const c of report.candidates) {
+    const badge = FIT_BADGES[c.overall_fit] || '? unknown';
+    lines.push(`  ${badge}  ${c.filename} (seed: ${c.seed ?? '?'})`);
+
+    if (c.strengths.length > 0) {
+      lines.push(`    strengths: ${c.strengths.slice(0, 3).join('; ')}`);
+    }
+    if (c.drift_issues.length > 0) {
+      lines.push(`    drift: ${c.drift_issues.slice(0, 3).join('; ')}`);
+    }
+  }
+  lines.push('');
+
+  return lines.join('\n');
+}

package/lib/generated-provenance.js

@@ -0,0 +1,87 @@
+/**
+ * Generated provenance builder — constructs the provenance block
+ * attached to records created from selected run/batch outputs.
+ *
+ * Normalizes source context (run vs batch) into a single shape
+ * that traces back through brief → workflow → seed → config.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+
+/**
+ * Build a generation provenance payload for a selected output.
+ *
+ * @param {Object} opts
+ * @param {'run'|'batch'} opts.sourceType
+ * @param {string} opts.sourceId — run_id or batch_id
+ * @param {Object} opts.runManifest — the run manifest containing this output
+ * @param {Object} [opts.batchManifest] — batch manifest if source is batch
+ * @param {Object} opts.item — the selection item (slot_or_output, filename, seed)
+ * @param {string} opts.projectRoot
+ * @returns {Object} generation_provenance block
+ */
+export function buildGeneratedProvenance({
+  sourceType,
+  sourceId,
+  runManifest,
+  batchManifest,
+  item,
+  projectRoot,
+}) {
+  const prov = {
+    source_type: sourceType,
+    source_id: sourceId,
+    run_id: runManifest.run_id,
+    brief_id: runManifest.brief_id,
+    workflow_id: runManifest.workflow_template_id,
+    selected_filename: item.filename,
+    generated_at: runManifest.created_at,
+  };
+
+  if (sourceType === 'batch' && batchManifest) {
+    prov.batch_id = batchManifest.batch_id;
+  }
+
+  // Seed from the item or from the run manifest outputs
+  if (item.seed !== undefined) {
+    prov.seed = item.seed;
+  } else if (runManifest.outputs) {
+    const match = runManifest.outputs.find(o => o.filename === item.filename);
+    if (match?.seed !== undefined) prov.seed = match.seed;
+  }
+
+  // Adapter target from run manifest
+  if (runManifest.adapter_target) {
+    prov.adapter_target = runManifest.adapter_target;
+  }
+
+  // Subject from run brief or batch manifest
+  if (batchManifest?.subject_id) {
+    prov.subject_id = batchManifest.subject_id;
+  } else {
+    // Try to read subject from brief
+    const briefPath = join(projectRoot, 'briefs', `${runManifest.brief_id}.json`);
+    if (existsSync(briefPath)) {
+      try {
+        const brief = JSON.parse(readFileSync(briefPath, 'utf-8'));
+        if (brief.subject_id) prov.subject_id = brief.subject_id;
+        if (brief.parent_brief_id) prov.parent_brief_id = brief.parent_brief_id;
+      } catch { /* skip */ }
+    }
+  }
+
+  // Config fingerprint — hash the run manifest for reproducibility tracing
+  prov.config_fingerprint = createHash('sha256')
+    .update(JSON.stringify({
+      brief_id: runManifest.brief_id,
+      workflow_template_id: runManifest.workflow_template_id,
+      adapter_target: runManifest.adapter_target,
+      seed_plan: runManifest.seed_plan,
+    }))
+    .digest('hex')
+    .slice(0, 16);
+
+  return prov;
+}

package/lib/paths.js

@@ -36,3 +36,34 @@ export function getProjectRoot(name) {
 export function resolveProjectPath(name, ...segments) {
   return join(getProjectRoot(name), ...segments);
 }
+
+/**
+ * Return the workflow profiles directory for a project root.
+ * @param {string} projectRoot — absolute path to project
+ */
+export function getWorkflowProfilesDir(projectRoot) {
+  return join(projectRoot, 'workflows', 'profiles');
+}
+
+/**
+ * Return the briefs directory for a project root.
+ * @param {string} projectRoot — absolute path to project
+ */
+export function getBriefsDir(projectRoot) {
+  return join(projectRoot, 'briefs');
+}
+
+/**
+ * Return the runs directory for a project root.
+ * @param {string} projectRoot — absolute path to project
+ */
+export function getRunsDir(projectRoot) {
+  return join(projectRoot, 'runs');
+}
+
+/**
+ * Return the runtime templates directory (repo-level).
+ */
+export function getRuntimeDir() {
+  return join(REPO_ROOT, 'runtime');
+}

package/lib/refine-briefs.js

@@ -0,0 +1,329 @@
+/**
+ * Refine briefs — derive a next-pass brief from critique of a previous run.
+ *
+ * A refined brief is NOT a brand-new brief. It is a delta layer:
+ *   - Preserves: original workflow, subject, lane, canon constraints, runtime plan
+ *   - Adds: preserve/push/suppress instructions derived from critique
+ *   - Updates: prompt and negative prompt with targeted refinements
+ *
+ * This keeps the loop stable — each pass improves, never scrambles.
+ */
+
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync, readdirSync } from 'node:fs';
+import { getRunsDir } from './paths.js';
+import { inputError } from './errors.js';
+
+// ─── Refined brief ID generation ─────────────────────────────────
+
+/**
+ * Generate refined brief ID: <parent_brief_id>_refine_NN
+ */
+function generateRefinedBriefId(refineDir, parentBriefId) {
+  const prefix = `${parentBriefId}_refine_`;
+
+  let maxSeq = 0;
+  if (existsSync(refineDir)) {
+    const existing = readdirSync(refineDir)
+      .filter(f => f.startsWith(prefix) && f.endsWith('.json'));
+    for (const f of existing) {
+      const seqStr = f.slice(prefix.length, -5);
+      const seq = parseInt(seqStr, 10);
+      if (!isNaN(seq) && seq > maxSeq) maxSeq = seq;
+    }
+  }
+
+  const seq = String(maxSeq + 1).padStart(2, '0');
+  return `${prefix}${seq}`;
+}
+
+// ─── Prompt refinement ───────────────────────────────────────────
+
+/**
+ * Render a refined prompt from parent prompt + delta instructions.
+ *
+ * Strategy:
+ *   - Start with the original prompt
+ *   - Append preserve notes as reinforcement
+ *   - Append push notes as emphasis
+ *   - Do NOT remove anything from the original — only add emphasis
+ */
+export function renderRefinedPrompt(parentPrompt, delta) {
+  const parts = [parentPrompt];
+
+  // Preserve instructions — reinforce what worked
+  if (delta.preserve?.length > 0) {
+    parts.push(`[preserve: ${delta.preserve.join(', ')}]`);
+  }
+
+  // Push instructions — emphasize what needs to be stronger
+  if (delta.push?.length > 0) {
+    parts.push(`[emphasize: ${delta.push.join(', ')}]`);
+  }
+
+  return parts.join(', ');
+}
+
+/**
+ * Render a refined negative prompt from parent negative + suppress instructions.
+ *
+ * Strategy:
+ *   - Keep the entire original negative prompt
+ *   - Append suppress items that aren't already present
+ */
+export function renderRefinedNegative(parentNegative, delta) {
+  const existing = parentNegative.split(',').map(s => s.trim().toLowerCase());
+  const additions = [];
+
+  for (const item of delta.suppress || []) {
+    const lower = item.toLowerCase();
+    // Don't duplicate if already in negative
+    if (!existing.some(e => e.includes(lower) || lower.includes(e))) {
+      additions.push(item);
+    }
+  }
+
+  if (additions.length === 0) return parentNegative;
+  return `${parentNegative}, ${additions.join(', ')}`;
+}
+
+// ─── Delta extraction from critique ──────────────────────────────
+
+/**
+ * Extract a refine delta from a critique report + picked candidate.
+ *
+ * @param {Object} critique — critique report
+ * @param {string} pickedFilename — filename of the picked candidate
+ * @param {Object} cliOverrides — { preserve: string[], push: string[], suppress: string[] }
+ * @returns {{ preserve: string[], push: string[], suppress: string[] }}
+ */
+export function extractDelta(critique, pickedFilename, cliOverrides = {}) {
+  // Find the picked candidate in the critique
+  const picked = critique.candidates.find(c => c.filename === pickedFilename);
+  if (!picked) {
+    throw inputError(
+      'REFINE_CANDIDATE_NOT_FOUND',
+      `Candidate "${pickedFilename}" not found in critique for run "${critique.run_id}"`,
+      `Available candidates: ${critique.candidates.map(c => c.filename).join(', ')}`
+    );
+  }
+
+  // Start with critique-derived instructions
+  const preserve = [...(picked.preserve_next_pass || [])];
+  const push = [];
+  const suppress = [];
+
+  // Derive push from drift issues that need correction
+  for (const issue of picked.correct_next_pass || []) {
+    push.push(issue);
+  }
+
+  // Derive suppress from drift issues
+  for (const drift of picked.drift_issues || []) {
+    // Strip "check:" and "negative check:" prefixes for cleaner suppress
+    const cleaned = drift
+      .replace(/^\[.*?\]\s*check:\s*/i, '')
+      .replace(/^negative check:\s*/i, '')
+      .trim();
+    if (cleaned) suppress.push(cleaned);
+  }
+
+  // CLI overrides — append without duplicating
+  if (cliOverrides.preserve) {
+    for (const p of cliOverrides.preserve) {
+      if (!preserve.includes(p)) preserve.push(p);
+    }
+  }
+  if (cliOverrides.push) {
+    for (const p of cliOverrides.push) {
+      if (!push.includes(p)) push.push(p);
+    }
+  }
+  if (cliOverrides.suppress) {
+    for (const s of cliOverrides.suppress) {
+      if (!suppress.includes(s)) suppress.push(s);
+    }
+  }
+
+  return { preserve, push, suppress };
+}
+
+// ─── Build refined brief ─────────────────────────────────────────
+
+/**
+ * Build a refined brief from parent brief, critique, and delta.
+ *
+ * @param {Object} opts
+ * @param {Object} opts.parentBrief — original compiled brief
+ * @param {Object} opts.critique — critique report
+ * @param {string} opts.pickedCandidate — filename of selected candidate
+ * @param {Object} opts.delta — { preserve, push, suppress }
+ * @param {string} opts.runId — source run ID
+ * @param {string} opts.refineDir — path to write refined brief
+ * @returns {Object} refined brief
+ */
+export function buildRefinedBrief({ parentBrief, critique, pickedCandidate, delta, runId, refineDir }) {
+  const briefId = generateRefinedBriefId(refineDir, parentBrief.brief_id);
+
+  // Render updated prompts
+  const prompt = renderRefinedPrompt(parentBrief.prompt, delta);
+  const negativePrompt = renderRefinedNegative(parentBrief.negative_prompt, delta);
+
+  const refined = {
+    brief_id: briefId,
+    parent_brief_id: parentBrief.brief_id,
+    source_run_id: runId,
+    source_candidate: pickedCandidate,
+
+    project_id: parentBrief.project_id,
+    workflow_id: parentBrief.workflow_id,
+    lane_id: parentBrief.lane_id,
+    compiled_at: new Date().toISOString(),
+    config_fingerprint: parentBrief.config_fingerprint,
+
+    prompt,
+    negative_prompt: negativePrompt,
+
+    refine_delta: delta,
+
+    // Carry forward from parent
+    canon_constraints: parentBrief.canon_constraints || [],
+    drift_warnings: parentBrief.drift_warnings || [],
+    runtime_plan: { ...parentBrief.runtime_plan },
+    expected_outputs: { ...parentBrief.expected_outputs },
+  };
+
+  // Optional fields
+  if (parentBrief.subject_id) refined.subject_id = parentBrief.subject_id;
+  if (parentBrief.subject_constraints) refined.subject_constraints = parentBrief.subject_constraints;
+  if (parentBrief.reference_selection) refined.reference_selection = parentBrief.reference_selection;
+
+  return refined;
+}
+
+// ─── Markdown renderer ──────────────────────────────────────────
+
+/**
+ * Render a refined brief as Markdown.
+ */
+export function renderRefinedBriefMarkdown(brief) {
+  const lines = [];
+
+  lines.push(`# Refined Brief: ${brief.brief_id}`);
+  lines.push('');
+  lines.push(`**Parent Brief:** ${brief.parent_brief_id}`);
+  lines.push(`**Source Run:** ${brief.source_run_id}`);
+  lines.push(`**Picked Candidate:** ${brief.source_candidate}`);
+  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}`);
+  lines.push('');
+
+  // Refine delta — the key section
+  lines.push('## Refine Delta');
+  lines.push('');
+
+  if (brief.refine_delta?.preserve?.length > 0) {
+    lines.push('### Preserve');
+    for (const p of brief.refine_delta.preserve) lines.push(`- ✓ ${p}`);
+    lines.push('');
+  }
+
+  if (brief.refine_delta?.push?.length > 0) {
+    lines.push('### Push');
+    for (const p of brief.refine_delta.push) lines.push(`- → ${p}`);
+    lines.push('');
+  }
+
+  if (brief.refine_delta?.suppress?.length > 0) {
+    lines.push('### Suppress');
+    for (const s of brief.refine_delta.suppress) lines.push(`- ✗ ${s}`);
+    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('');
+  }
+
+  // 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 || {};
+  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 || {};
+  lines.push(`- **Mode:** ${eo.output_mode || '?'}`);
+  lines.push(`- **Count:** ${eo.output_count || '?'}`);
+  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');
+}
+
+// ─── Save ────────────────────────────────────────────────────────
+
+/**
+ * Save a refined brief to the run's refine directory.
+ */
+export async function saveRefinedBrief(projectRoot, runId, refinedBrief) {
+  const refineDir = join(getRunsDir(projectRoot), runId, 'refine');
+  await mkdir(refineDir, { recursive: true });
+
+  const jsonPath = join(refineDir, `${refinedBrief.brief_id}.json`);
+  await writeFile(jsonPath, JSON.stringify(refinedBrief, null, 2) + '\n');
+
+  const md = renderRefinedBriefMarkdown(refinedBrief);
+  const mdPath = join(refineDir, `${refinedBrief.brief_id}.md`);
+  await writeFile(mdPath, md);
+
+  return { jsonPath, mdPath, refineDir };
+}