@mcptoolshop/style-dataset-lab 2.3.0 → 3.0.1

package/lib/reingest.js

@@ -7,7 +7,7 @@
  * canon-bound like everything else.
  */
 
-import { readFile, writeFile, readdir, stat } from 'node:fs/promises';
+import { readFile, writeFile, readdir, stat, mkdir, copyFile } from 'node:fs/promises';
 import { join, basename, extname } from 'node:path';
 import { existsSync } from 'node:fs';
 import { loadTrainingManifest } from './training-manifests.js';
@@ -33,6 +33,12 @@ const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.webp']);
 export async function reingestGenerated(projectRoot, sourcePath, manifestId, options = {}) {
   const manifest = await loadTrainingManifest(projectRoot, manifestId);
   const recordsDir = join(projectRoot, 'records');
+  // D-020: ensure outputs/candidates/ exists so the record's asset_path
+  // contract ("outputs/candidates/<file>") actually points at the image.
+  const candidatesDir = join(projectRoot, 'outputs', 'candidates');
+  if (!options.dryRun) {
+    await mkdir(candidatesDir, { recursive: true });
+  }
 
   // Find image files in source directory
   const entries = await readdir(sourcePath);
@@ -80,6 +86,14 @@ export async function reingestGenerated(projectRoot, sourcePath, manifestId, opt
     record.schema_version = '2.1.0';
 
     if (!options.dryRun) {
+      // D-020: copy the image into outputs/candidates/ so the record's
+      // project-relative asset_path contract is satisfied. Without this,
+      // downstream readers (export, adapters) would silently skip the
+      // record because the file does not exist at the declared path.
+      const destPath = join(candidatesDir, file);
+      if (!existsSync(destPath)) {
+        await copyFile(filePath, destPath);
+      }
       await writeFile(recordPath, JSON.stringify(record, null, 2) + '\n');
     }
 

package/lib/run-summary.js

@@ -0,0 +1,132 @@
+/**
+ * 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
+  const errors = manifest.errors || [];
+  if (errors.length > 0) {
+    lines.push('## Errors');
+    lines.push('');
+    for (const err of 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');
+}

package/lib/runtime-runs.js

@@ -0,0 +1,218 @@
+/**
+ * Runtime run management — create, load, list run artifacts.
+ *
+ * A run is a frozen execution artifact: brief + seeds + outputs + manifest.
+ * The run folder IS the review surface — humans open it directly.
+ */
+
+import { readFile, writeFile, mkdir, readdir, copyFile, rename, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { randomInt } from 'node:crypto';
+import { getRunsDir, getBriefsDir } from './paths.js';
+import { inputError } from './errors.js';
+import { verbose } from './log.js';
+
+// ─── Run ID generation ───────────────────────────────────────────
+
+/**
+ * Generate a run ID: run_YYYY-MM-DD_NNN
+ */
+// PB-008: tighten regex so stray directories like 'run_<date>_001_wip'
+// don't inflate the sequence via parseInt's lenient parsing.
+const RUN_SEQ_RE = /^(\d{3})$/;
+
+export function generateRunId(runsDir) {
+  const today = new Date().toISOString().slice(0, 10);
+  const prefix = `run_${today}_`;
+
+  let maxSeq = 0;
+  if (existsSync(runsDir)) {
+    const existing = readdirSync(runsDir, { withFileTypes: true })
+      .filter(e => e.isDirectory() && e.name.startsWith(prefix));
+    for (const e of existing) {
+      const seqStr = e.name.slice(prefix.length);
+      const match = RUN_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}`;
+}
+
+// ─── Seed planning ───────────────────────────────────────────────
+
+/**
+ * Build a deterministic seed plan.
+ * @param {Object} opts
+ * @param {'fixed'|'increment'|'random'} opts.seedMode
+ * @param {number} opts.outputCount
+ * @param {number} [opts.baseSeed] — explicit base seed (default: random)
+ * @returns {{ base_seed: number, seeds: number[] }}
+ */
+export function buildSeedPlan({ seedMode, outputCount, baseSeed }) {
+  const base = baseSeed ?? randomInt(2_147_483_647);
+  const seeds = [];
+
+  switch (seedMode) {
+    case 'fixed':
+      for (let i = 0; i < outputCount; i++) seeds.push(base);
+      break;
+    case 'increment':
+      for (let i = 0; i < outputCount; i++) seeds.push(base + i);
+      break;
+    case 'random':
+      seeds.push(base);
+      for (let i = 1; i < outputCount; i++) {
+        seeds.push(randomInt(2_147_483_647));
+      }
+      break;
+    default:
+      // Default to increment
+      for (let i = 0; i < outputCount; i++) seeds.push(base + i);
+  }
+
+  return { base_seed: base, seeds };
+}
+
+// ─── Run directory setup ─────────────────────────────────────────
+
+/**
+ * Prepare a run directory and copy brief artifacts into it.
+ * @returns {{ runId: string, runDir: string }}
+ */
+export async function prepareRunDir(projectRoot, brief) {
+  const runsDir = getRunsDir(projectRoot);
+  const runId = generateRunId(runsDir);
+  const runDir = join(runsDir, runId);
+
+  await mkdir(join(runDir, 'outputs'), { recursive: true });
+
+  // Copy brief artifacts
+  const briefsDir = getBriefsDir(projectRoot);
+  const briefJsonSrc = join(briefsDir, `${brief.brief_id}.json`);
+  const briefMdSrc = join(briefsDir, `${brief.brief_id}.md`);
+
+  await writeFile(join(runDir, 'brief.json'), JSON.stringify(brief, null, 2) + '\n');
+
+  if (existsSync(briefMdSrc)) {
+    await copyFile(briefMdSrc, join(runDir, 'brief.md'));
+  }
+
+  // Write standalone prompt/negative files for easy inspection
+  await writeFile(join(runDir, 'prompt.txt'), brief.prompt || '');
+  await writeFile(join(runDir, 'negative-prompt.txt'), brief.negative_prompt || '');
+
+  return { runId, runDir };
+}
+
+// ─── Manifest ────────────────────────────────────────────────────
+
+/**
+ * Atomic write: write to a temp file in the same directory, then rename.
+ * Rename is atomic on the same filesystem, so a crash mid-write can never
+ * leave a half-written manifest in place of a good one.
+ *
+ * PB-002 / PB-005: callers may invoke this after each slot/candidate to
+ * produce incremental checkpoints.
+ */
+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) {
+    // Best-effort cleanup of the temp file on failure.
+    try { await unlink(tmpPath); } catch { /* ignore */ }
+    throw err;
+  }
+}
+
+/**
+ * Build and save a run manifest.
+ *
+ * PB-002: uses atomic write (temp + rename) so a crash mid-write cannot
+ * corrupt an existing manifest. Safe to call repeatedly for incremental
+ * checkpointing after each output completes.
+ */
+export async function saveRunManifest(runDir, manifest) {
+  const target = join(runDir, 'manifest.json');
+  await atomicWriteJson(target, manifest);
+  verbose(`saveRunManifest: wrote ${target}`);
+}
+
+/**
+ * Incremental checkpoint — same shape as saveRunManifest but stamps
+ * `incremental: true` and `last_checkpoint_at` so a human reading a
+ * partial manifest knows the run is in progress.
+ *
+ * PB-002: call after each completed output in long-running loops so a
+ * crash/interruption leaves a partial record instead of an orphan dir.
+ */
+export async function checkpointRunManifest(runDir, manifest) {
+  const snapshot = {
+    ...manifest,
+    incremental: true,
+    last_checkpoint_at: new Date().toISOString(),
+  };
+  await atomicWriteJson(join(runDir, 'manifest.json'), snapshot);
+  verbose(`checkpointRunManifest: ${manifest.run_id} (${manifest.outputs?.length ?? 0} outputs)`);
+}
+
+// ─── Load / List ─────────────────────────────────────────────────
+
+/**
+ * Load a run manifest by ID.
+ */
+export async function loadRun(projectRoot, runId) {
+  const runDir = join(getRunsDir(projectRoot), runId);
+  const manifestPath = join(runDir, 'manifest.json');
+
+  if (!existsSync(manifestPath)) {
+    throw inputError(
+      'RUN_NOT_FOUND',
+      `Run "${runId}" not found`,
+      `Check the run ID or run: sdlab run generate --brief <id>`
+    );
+  }
+
+  return JSON.parse(await readFile(manifestPath, 'utf-8'));
+}
+
+/**
+ * List all runs in a project.
+ */
+export function listRuns(projectRoot) {
+  const runsDir = getRunsDir(projectRoot);
+  if (!existsSync(runsDir)) return [];
+
+  const entries = readdirSync(runsDir, { withFileTypes: true })
+    .filter(e => e.isDirectory() && e.name.startsWith('run_'))
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  const runs = [];
+  for (const entry of entries) {
+    const manifestPath = join(runsDir, entry.name, 'manifest.json');
+    if (!existsSync(manifestPath)) continue;
+
+    try {
+      const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+      runs.push({
+        run_id: manifest.run_id,
+        brief_id: manifest.brief_id,
+        workflow_template_id: manifest.workflow_template_id,
+        output_count: manifest.output_count,
+        created_at: manifest.created_at,
+        adapter_target: manifest.adapter_target,
+      });
+    } catch {
+      // Skip malformed
+    }
+  }
+
+  return runs;
+}