@mcptoolshop/style-dataset-lab 2.2.1 → 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/errors.js

@@ -0,0 +1,82 @@
+/**
+ * Structured error shape for Style Dataset Lab.
+ *
+ * Every user-facing error has: code, message, hint.
+ * Exit codes: 0 ok, 1 user error, 2 runtime error.
+ */
+
+export class SdlabError extends Error {
+  /**
+   * @param {string} code — error code (e.g. INPUT_MISSING_FLAG)
+   * @param {string} message — human-readable description
+   * @param {Object} options
+   * @param {string} [options.hint] — actionable fix suggestion
+   * @param {Error} [options.cause] — original error
+   * @param {number} [options.exitCode] — 1 (user) or 2 (runtime)
+   */
+  constructor(code, message, { hint, cause, exitCode } = {}) {
+    super(message);
+    this.name = 'SdlabError';
+    this.code = code;
+    this.hint = hint || null;
+    this.cause = cause || null;
+    this.exitCode = exitCode || 1;
+  }
+
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      hint: this.hint,
+    };
+  }
+}
+
+// ─── Convenience constructors ──────────────────────────────────────
+
+export function inputError(code, message, hint) {
+  return new SdlabError(code, message, { hint, exitCode: 1 });
+}
+
+export function runtimeError(code, message, hint, cause) {
+  return new SdlabError(code, message, { hint, cause, exitCode: 2 });
+}
+
+// ─── CLI error handler ─────────────────────────────────────────────
+
+let debugMode = false;
+
+export function enableDebug() {
+  debugMode = true;
+}
+
+export function isDebug() {
+  return debugMode;
+}
+
+/**
+ * Handle an error at the CLI boundary.
+ * Shows structured output by default, stack trace with --debug.
+ */
+export function handleCliError(err) {
+  if (err instanceof SdlabError) {
+    console.error(`\x1b[31mError [${err.code}]:\x1b[0m ${err.message}`);
+    if (err.hint) {
+      console.error(`\x1b[33mHint:\x1b[0m ${err.hint}`);
+    }
+    if (debugMode && err.stack) {
+      console.error('\n' + err.stack);
+    }
+    if (debugMode && err.cause) {
+      console.error('\nCaused by:', err.cause);
+    }
+    process.exit(err.exitCode);
+  } else {
+    // Unstructured error — runtime failure
+    console.error(`\x1b[31mError:\x1b[0m ${err.message || err}`);
+    if (debugMode && err.stack) {
+      console.error('\n' + err.stack);
+    }
+    process.exit(2);
+  }
+}

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/log.js

@@ -0,0 +1,36 @@
+/**
+ * Logging levels for CLI output.
+ *
+ * Levels: quiet < normal < verbose
+ * Set via --quiet or --verbose flags (parsed by caller).
+ */
+
+let level = 'normal'; // quiet | normal | verbose
+
+export function setLogLevel(l) {
+  level = l;
+}
+
+export function getLogLevel() {
+  return level;
+}
+
+/** Always shown (errors, final results). */
+export function log(...args) {
+  console.log(...args);
+}
+
+/** Shown at normal and verbose levels (progress, summaries). */
+export function info(...args) {
+  if (level !== 'quiet') console.log(...args);
+}
+
+/** Shown only at verbose level (per-record details, debug context). */
+export function verbose(...args) {
+  if (level === 'verbose') console.log(...args);
+}
+
+/** Always shown on stderr. */
+export function warn(...args) {
+  console.error('\x1b[33m⚠\x1b[0m', ...args);
+}

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