@mcptoolshop/style-dataset-lab 2.2.1 → 3.0.0

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 };
+}

package/lib/reingest-selected.js

@@ -0,0 +1,173 @@
+/**
+ * Re-ingest selected outputs as new candidate records.
+ *
+ * Selected outputs re-enter the project as generated candidates
+ * with full provenance. They go through the same review and
+ * canon-binding flow as everything else. No bypass.
+ */
+
+import { writeFile, mkdir, copyFile } from 'node:fs/promises';
+import { join, extname } from 'node:path';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { getRunsDir } from './paths.js';
+import { getBatchesDir } from './batch-runs.js';
+import { getSelectionsDir, loadSelection } from './selections.js';
+import { buildGeneratedProvenance } from './generated-provenance.js';
+import { buildBaseRecord } from './records.js';
+import { inputError } from './errors.js';
+
+/**
+ * Re-ingest a selection — creates candidate records from chosen outputs.
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectRoot
+ * @param {string} opts.projectId
+ * @param {string} opts.selectionId
+ * @param {boolean} [opts.dryRun]
+ * @returns {Promise<{created: string[], skipped: string[]}>}
+ */
+export async function reingestSelection({ projectRoot, projectId, selectionId, dryRun }) {
+  const manifest = loadSelection(projectRoot, selectionId);
+
+  if (!manifest.reingest_ready) {
+    throw inputError(
+      'SELECTION_NOT_READY',
+      `Selection "${selectionId}" is not marked reingest_ready`,
+      'Set reingest_ready: true in the selection manifest.',
+    );
+  }
+
+  const selectionDir = join(getSelectionsDir(projectRoot), selectionId);
+  const recordsDir = join(projectRoot, 'records');
+  const inboxDir = join(projectRoot, 'inbox', 'generated');
+
+  if (!dryRun) {
+    await mkdir(recordsDir, { recursive: true });
+    await mkdir(inboxDir, { recursive: true });
+  }
+
+  // Load source manifests for provenance
+  const runsDir = getRunsDir(projectRoot);
+  const runManifestCache = new Map();
+
+  function getRunManifest(runId) {
+    if (runManifestCache.has(runId)) return runManifestCache.get(runId);
+    const mPath = join(runsDir, runId, 'manifest.json');
+    if (!existsSync(mPath)) return null;
+    const m = JSON.parse(readFileSync(mPath, 'utf-8'));
+    runManifestCache.set(runId, m);
+    return m;
+  }
+
+  let batchManifest = null;
+  if (manifest.source_type === 'batch') {
+    const bmPath = join(getBatchesDir(projectRoot), manifest.source_id, 'manifest.json');
+    if (existsSync(bmPath)) {
+      batchManifest = JSON.parse(readFileSync(bmPath, 'utf-8'));
+    }
+  }
+
+  const created = [];
+  const skipped = [];
+  const provenanceLines = [];
+
+  for (const item of manifest.items) {
+    // Determine record ID from selection + item index
+    const idx = String(manifest.items.indexOf(item) + 1).padStart(3, '0');
+    const recordId = `gen_${selectionId}_${idx}`;
+    const recordPath = join(recordsDir, `${recordId}.json`);
+
+    if (existsSync(recordPath)) {
+      skipped.push(recordId);
+      continue;
+    }
+
+    // Resolve the run manifest for this item
+    let runManifest;
+    if (manifest.source_type === 'run') {
+      runManifest = getRunManifest(manifest.source_id);
+    } else if (manifest.source_type === 'batch' && batchManifest) {
+      // Find which run this slot belongs to
+      const slotId = item.slot_or_output.split(':')[0];
+      const slot = batchManifest.slots?.find(s => s.slot_id === slotId);
+      if (slot) {
+        runManifest = getRunManifest(slot.run_id);
+      }
+    }
+
+    if (!runManifest) {
+      // Fallback: minimal provenance
+      runManifest = {
+        run_id: manifest.source_id,
+        brief_id: 'unknown',
+        workflow_template_id: manifest.workflow_id || 'unknown',
+        created_at: manifest.created_at,
+      };
+    }
+
+    // Build provenance
+    const prov = buildGeneratedProvenance({
+      sourceType: manifest.source_type,
+      sourceId: manifest.source_id,
+      runManifest,
+      batchManifest,
+      item,
+      projectRoot,
+    });
+
+    // Image source in selection/chosen/
+    const srcImage = join(selectionDir, 'chosen', item.filename);
+    const ext = extname(item.filename) || '.png';
+    const destImage = `${recordId}${ext}`;
+    const inboxPath = join(inboxDir, destImage);
+    const assetPath = `inbox/generated/${destImage}`;
+
+    // Get file size
+    let fileBytes = 0;
+    if (existsSync(srcImage)) {
+      fileBytes = statSync(srcImage).size;
+    }
+
+    // Build record
+    const record = buildBaseRecord(recordId, assetPath, {
+      width: null,
+      height: null,
+      bytes: fileBytes,
+    }, {
+      source: 'generated',
+      selection_id: selectionId,
+      generation_provenance: prov,
+    });
+
+    record.schema_version = '2.2.0';
+
+    // Tags
+    const recordTags = ['generated', 'selected'];
+    if (manifest.workflow_id) recordTags.push(manifest.workflow_id);
+    if (manifest.subject_id) recordTags.push(manifest.subject_id);
+    if (item.tags?.length) recordTags.push(...item.tags);
+    record.tags = [...new Set(recordTags)];
+
+    if (!dryRun) {
+      // Copy image into inbox
+      if (existsSync(srcImage)) {
+        await copyFile(srcImage, inboxPath);
+      }
+      // Write record
+      await writeFile(recordPath, JSON.stringify(record, null, 2) + '\n');
+    }
+
+    created.push(recordId);
+    provenanceLines.push(JSON.stringify({ record_id: recordId, ...prov }));
+  }
+
+  // Write provenance log
+  if (!dryRun && provenanceLines.length > 0) {
+    await writeFile(
+      join(selectionDir, 'provenance.jsonl'),
+      provenanceLines.join('\n') + '\n',
+    );
+  }
+
+  return { created, skipped };
+}

package/lib/run-summary.js

@@ -0,0 +1,131 @@
+/**
+ * Run summary — render manifest to human-readable summary files.
+ *
+ * Writes summary.md + summary.json to the run directory.
+ * Contact sheet generation is separate (requires image processing).
+ */
+
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Build a summary object from a manifest.
+ */
+export function buildRunSummary(manifest) {
+  const ok = manifest.outputs.filter(o => o.status === 'ok');
+  const failed = manifest.outputs.filter(o => o.status === 'error');
+  const totalElapsed = ok.reduce((sum, o) => sum + (o.elapsed_ms || 0), 0);
+
+  return {
+    run_id: manifest.run_id,
+    brief_id: manifest.brief_id,
+    project_id: manifest.project_id,
+    adapter_target: manifest.adapter_target,
+    output_mode: manifest.output_mode,
+    created_at: manifest.created_at,
+    dry_run: manifest.dry_run,
+    success_count: manifest.success_count,
+    error_count: manifest.error_count,
+    total_outputs: manifest.output_count,
+    total_elapsed_ms: totalElapsed,
+    avg_elapsed_ms: ok.length > 0 ? Math.round(totalElapsed / ok.length) : 0,
+    seed_plan: manifest.seed_plan,
+    checkpoint: manifest.checkpoint,
+  };
+}
+
+/**
+ * Render a manifest to Markdown summary.
+ */
+export function renderRunMarkdown(manifest) {
+  const lines = [];
+  lines.push(`# Run: ${manifest.run_id}`);
+  lines.push('');
+  lines.push(`**Brief:** ${manifest.brief_id}`);
+  lines.push(`**Project:** ${manifest.project_id}`);
+  lines.push(`**Created:** ${manifest.created_at}`);
+  lines.push(`**Adapter:** ${manifest.adapter_target}`);
+  lines.push(`**Mode:** ${manifest.output_mode}`);
+  if (manifest.dry_run) lines.push('**⚠ DRY RUN — no images generated**');
+  lines.push('');
+
+  // Results
+  lines.push('## Results');
+  lines.push('');
+  lines.push(`| # | Seed | Status | File | Time |`);
+  lines.push(`|---|------|--------|------|------|`);
+  for (const out of manifest.outputs) {
+    const file = out.filename || '—';
+    const time = out.elapsed_ms ? `${(out.elapsed_ms / 1000).toFixed(1)}s` : '—';
+    const status = out.status === 'ok' ? '✓' : out.status === 'dry_run' ? '○' : '✗';
+    lines.push(`| ${out.index + 1} | ${out.seed} | ${status} | ${file} | ${time} |`);
+  }
+  lines.push('');
+
+  // Errors
+  if (manifest.errors.length > 0) {
+    lines.push('## Errors');
+    lines.push('');
+    for (const err of manifest.errors) {
+      lines.push(`- **Image ${err.index + 1}** (seed ${err.seed}): ${err.error}`);
+    }
+    lines.push('');
+  }
+
+  // Runtime
+  lines.push('## Runtime');
+  lines.push('');
+  lines.push(`| Parameter | Value |`);
+  lines.push(`|-----------|-------|`);
+  lines.push(`| Checkpoint | ${manifest.checkpoint || '—'} |`);
+  lines.push(`| LoRAs | ${(manifest.loras || []).map(l => l.name).join(', ') || '—'} |`);
+  lines.push(`| ComfyUI | ${manifest.comfy_url || '—'} |`);
+
+  const rp = manifest.runtime_plan || {};
+  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(`| Base seed | ${manifest.seed_plan?.base_seed || '?'} |`);
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Render a manifest to terminal text.
+ */
+export function renderRunText(manifest) {
+  const ok = manifest.outputs.filter(o => o.status === 'ok' || o.status === 'dry_run');
+  const failed = manifest.outputs.filter(o => o.status === 'error');
+  const lines = [];
+
+  lines.push(`Run: ${manifest.run_id}`);
+  lines.push(`Brief: ${manifest.brief_id}`);
+  lines.push(`Project: ${manifest.project_id}`);
+  lines.push(`Mode: ${manifest.output_mode} (${manifest.adapter_target})`);
+  if (manifest.dry_run) lines.push('⚠ DRY RUN');
+  lines.push(`Results: ${ok.length}/${manifest.output_count} succeeded`);
+  if (failed.length > 0) lines.push(`Errors: ${failed.length}`);
+  lines.push('');
+
+  for (const out of manifest.outputs) {
+    const status = out.status === 'ok' ? '✓' : out.status === 'dry_run' ? '○' : '✗';
+    const time = out.elapsed_ms ? ` (${(out.elapsed_ms / 1000).toFixed(1)}s)` : '';
+    const file = out.filename ? ` → ${out.filename}` : '';
+    const err = out.error ? ` — ${out.error}` : '';
+    lines.push(`  ${status} [${out.index + 1}] seed ${out.seed}${file}${time}${err}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Save summary files into the run directory.
+ */
+export async function saveRunSummary(runDir, manifest) {
+  const summary = buildRunSummary(manifest);
+  await writeFile(join(runDir, 'summary.json'), JSON.stringify(summary, null, 2) + '\n');
+  await writeFile(join(runDir, 'summary.md'), renderRunMarkdown(manifest) + '\n');
+}