factoryhub 0.0.0-stage → 0.1.0

package/packages/engine/src/index.mjs

@@ -0,0 +1,9 @@
+// The engine's public surface in one import. Each module can also be imported
+// on its own: see "exports" in package.json.
+export * from './factory-engine.mjs';
+export * from './author-tests.mjs';
+export * from './compose.mjs';
+export * from './cost.mjs';
+export * from './diagnostics.mjs';
+export * from './markdown.mjs';
+export * from './package.mjs';

package/packages/engine/src/markdown.mjs

@@ -0,0 +1,97 @@
+// A small, safe Markdown renderer for deliverables: escapes everything first,
+// then builds headings, lists, tables, quotes, code, links and emphasis.
+
+const escapeHtml = (text) => String(text).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+function inline(text) {
+  let out = escapeHtml(String(text).replace(/\u0000/g, ''));
+  const codes = [];
+  out = out.replace(/`([^`]+)`/g, (_, code) => { codes.push(code); return `\u0000${codes.length - 1}\u0000`; });
+  // Finished links are set aside like code spans, so the bare-address pass
+  // can never match inside an href that was already written.
+  const stash = (html) => { codes.push({ html }); return `\u0000${codes.length - 1}\u0000`; };
+  out = out.replace(/\[([^\]]+)\]\((https?:\/\/[^\s()<>"]+)\)/g, (_, label, href) => stash(`<a href="${href}" target="_blank" rel="noopener nofollow">${label}</a>`));
+  out = out.replace(/(^|[\s(])(https?:\/\/[^\s<>()"]+[^\s<>()".,;:!?])/g, (_, lead, href) => `${lead}${stash(`<a href="${href}" target="_blank" rel="noopener nofollow">${href.replace(/^https?:\/\/(www\.)?/, '').replace(/\/$/, '')}</a>`)}`);
+  out = out.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>').replace(/(^|[^*\w])\*([^*\s][^*]*)\*(?!\w)/g, '$1<em>$2</em>').replace(/(^|[^\w])_([^_\s][^_]*)_(?!\w)/g, '$1<em>$2</em>');
+  out = out.replace(/\[(ADD|DECISION NEEDED):([^\]]*)\]/g, '<mark>[$1:$2]</mark>');
+  const restore = (text) => text.replace(/\u0000(\d+)\u0000/g, (_, index) => { const item = codes[Number(index)]; return typeof item === 'string' ? `<code>${item}</code>` : restore(item.html); });
+  return restore(out);
+}
+
+// A plain message whose field and tool names sit in backticks, such as a
+// factory's problems, as parts to show as text: the names as code, without the
+// backticks, and nothing else read as Markdown.
+export function codeParts(text) {
+  return String(text ?? '').split(/`([^`\n]+)`/).map((part, index) => ({ code: index % 2 === 1, text: part })).filter((part) => part.text);
+}
+
+const cells = (row) => row.trim().replace(/^\||\|$/g, '').split('|').map((cell) => cell.trim());
+
+export function renderMarkdown(source) {
+  const lines = String(source || '').replace(/\r\n/g, '\n').split('\n');
+  const html = [];
+  let i = 0;
+  const listAt = (line) => line.match(/^(\s*)([-*•]|\d+[.)])\s+(.*)$/);
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!line.trim()) { i += 1; continue; }
+    if (/^```/.test(line)) {
+      const buffer = [];
+      i += 1;
+      while (i < lines.length && !/^```/.test(lines[i])) { buffer.push(lines[i]); i += 1; }
+      i += 1;
+      html.push(`<pre><code>${escapeHtml(buffer.join('\n'))}</code></pre>`);
+      continue;
+    }
+    const heading = line.match(/^(#{1,6})\s+(.*)$/);
+    if (heading) {
+      const level = Math.min(heading[1].length + 1, 5);
+      html.push(`<h${level}>${inline(heading[2].replace(/#+\s*$/, ''))}</h${level}>`);
+      i += 1;
+      continue;
+    }
+    if (/^\s*([-*_])\s*\1\s*\1[\s\-*_]*$/.test(line)) { html.push('<hr>'); i += 1; continue; }
+    if (line.includes('|') && i + 1 < lines.length && /^\s*\|?\s*:?-{2,}/.test(lines[i + 1]) && lines[i + 1].includes('-')) {
+      const head = cells(line);
+      i += 2;
+      const rows = [];
+      while (i < lines.length && lines[i].includes('|') && lines[i].trim()) { rows.push(cells(lines[i])); i += 1; }
+      html.push(`<div class="table-wrap"><table><thead><tr>${head.map((cell) => `<th>${inline(cell)}</th>`).join('')}</tr></thead><tbody>${rows.map((row) => `<tr>${head.map((_, index) => `<td>${inline(row[index] || '')}</td>`).join('')}</tr>`).join('')}</tbody></table></div>`);
+      continue;
+    }
+    if (/^\s*>/.test(line)) {
+      const buffer = [];
+      while (i < lines.length && /^\s*>/.test(lines[i])) { buffer.push(lines[i].replace(/^\s*>\s?/, '')); i += 1; }
+      html.push(`<blockquote>${renderMarkdown(buffer.join('\n'))}</blockquote>`);
+      continue;
+    }
+    if (listAt(line)) {
+      const base = listAt(line)[1].length;
+      const ordered = /\d/.test(listAt(line)[2]);
+      const items = [];
+      while (i < lines.length) {
+        const item = listAt(lines[i]);
+        if (item && item[1].length <= base + 1) {
+          items.push([item[3]]);
+          i += 1;
+        } else if (items.length && lines[i].trim() && (/^\s{2,}/.test(lines[i]) || (item && item[1].length > base + 1))) {
+          items[items.length - 1].push(lines[i].slice(Math.min(base + 2, lines[i].match(/^\s*/)[0].length)));
+          i += 1;
+        } else if (!lines[i].trim() && i + 1 < lines.length && (listAt(lines[i + 1]) || /^\s{2,}\S/.test(lines[i + 1]))) {
+          i += 1;
+        } else break;
+      }
+      const tag = ordered ? 'ol' : 'ul';
+      html.push(`<${tag}>${items.map(([first, ...rest]) => ((box) => `<li${box ? ' class="task"' : ''}>${box ? `<input type="checkbox" disabled${box[1] === ' ' ? '' : ' checked'} aria-label="${box[1] === ' ' ? 'Not done' : 'Done'}">` : ''}<span>${inline(box ? first.slice(box[0].length) : first)}${rest.length ? renderMarkdown(rest.join('\n')) : ''}</span></li>`)(first.match(/^\[([ xX])\]\s+/))).join('')}</${tag}>`);
+      continue;
+    }
+    const buffer = [];
+    while (i < lines.length && lines[i].trim() && !/^(#{1,6}\s|```|\s*>)/.test(lines[i]) && !listAt(lines[i]) && !(lines[i].includes('|') && i + 1 < lines.length && /^\s*\|?\s*:?-{2,}/.test(lines[i + 1]))) {
+      buffer.push(lines[i]);
+      i += 1;
+    }
+    if (buffer.length) html.push(`<p>${buffer.map(inline).join('<br>')}</p>`);
+    else { html.push(`<p>${inline(lines[i])}</p>`); i += 1; }
+  }
+  return html.join('\n');
+}

package/packages/engine/src/package.mjs

@@ -0,0 +1,116 @@
+// Portable package metadata and ZIP downloads, derived from the executable source.
+import { parseBundle, parseYaml, inputSchema, bundleHash } from './factory-engine.mjs';
+import { readAuthorTests, authorTestSummary, AUTHOR_TEST_VERSION } from './author-tests.mjs';
+
+// Requirements are author declarations, never proof of compatibility or cost.
+// An invalid companion remains in the source archive, with visible diagnostics.
+export function packageDetails(files) {
+  const parsed = parseBundle(files);
+  const { factory } = parsed;
+  const warnings = [];
+  let declared = {};
+  if (files['mindburn.requirements.yaml']) {
+    try {
+      declared = parseYaml(files['mindburn.requirements.yaml']);
+      if (!declared || typeof declared !== 'object' || Array.isArray(declared)) throw new Error('Use a mapping.');
+    } catch {
+      warnings.push('Model and cost requirements could not be read. Check mindburn.requirements.yaml.');
+      declared = {};
+    }
+  }
+  const model = (value, label) => {
+    if (value === undefined) return null;
+    if (typeof value !== 'string' || !value.trim() || value.length > 160) {
+      warnings.push(`${label} must name a model in at most 160 characters.`);
+      return null;
+    }
+    return value.trim();
+  };
+  const minimum = model(declared.models?.minimum, 'Minimum model');
+  if (declared.models !== undefined && (!declared.models || typeof declared.models !== 'object' || Array.isArray(declared.models))) warnings.push('Model requirements must contain named minimum and recommended fields.');
+  const recommended = model(declared.models?.recommended, 'Recommended model') || model(factory.harness?.model, 'Default model');
+  let expectedCost = null;
+  const cost = declared.expected_cost;
+  if (cost !== undefined) {
+    if (cost && typeof cost === 'object' && cost.currency === 'USD'
+      && Number.isFinite(cost.min) && Number.isFinite(cost.max) && cost.min >= 0 && cost.max >= cost.min
+      && typeof cost.model === 'string' && cost.model.trim() && cost.model.length <= 160
+      && typeof cost.basis === 'string' && cost.basis.trim() && cost.basis.length <= 1000) {
+      expectedCost = { currency: 'USD', min: cost.min, max: cost.max, model: cost.model.trim(), basis: cost.basis.trim(), provenance: 'author-estimate' };
+    } else warnings.push('Expected cost needs USD, non-negative min/max, a model and the basis of the estimate.');
+  }
+  return {
+    format: 'mindburn-factory-package/v1',
+    name: factory.name, title: factory.title, version: factory.version,
+    inputs: inputSchema(factory),
+    requirements: {
+      runtime: 'Node.js 20 or newer for the included runner',
+      models: { minimum, recommended, provenance: 'author-declared', verified: false },
+      tools: [...new Set(factory.steps.flatMap((step) => [...step.tools, ...step.missing]))].sort(),
+      unsupported: factory.unsupportedRequirements,
+      expectedCost,
+    },
+    validation: { runnable: parsed.ok && factory.runnable, errors: parsed.errors, blockers: factory.blockers, warnings: [...parsed.warnings, ...warnings] },
+    // Structural validation is deliberately separate from effectiveness tests.
+    authorTests: authorTestSummary(readAuthorTests(files)),
+    securityScan: { status: 'not-scanned' },
+    changelog: Object.keys(files).find((path) => /^CHANGELOG(?:\.(?:md|txt))?$/.test(path)) || null,
+  };
+}
+
+export async function packageManifest(files, scan = null, tests = null) {
+  const sourceSha256 = await bundleHash(files);
+  const manifest = { ...packageDetails(files), sourceSha256 };
+  if (scan?.sourceSha256 === sourceSha256 && scan.version === 1) manifest.securityScan = scan;
+  if (tests?.sourceSha256 === sourceSha256 && tests.version === AUTHOR_TEST_VERSION) manifest.authorTests = tests;
+  return manifest;
+}
+
+// ---------------------------------------------------------------- bundle ----
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n += 1) {
+    let c = n;
+    for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+function crc32(bytes) {
+  let crc = 0xffffffff;
+  for (const byte of bytes) crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+// A plain (stored, uncompressed) zip: enough for a handful of text files.
+export function zip(files) {
+  const encoder = new TextEncoder();
+  const parts = [];
+  const central = [];
+  let offset = 0;
+  for (const [name, text] of Object.entries(files)) {
+    const nameBytes = encoder.encode(name);
+    const data = encoder.encode(text);
+    const crc = crc32(data);
+    const local = new DataView(new ArrayBuffer(30));
+    local.setUint32(0, 0x04034b50, true); local.setUint16(4, 20, true); local.setUint16(6, 0x0800, true);
+    local.setUint16(8, 0, true); local.setUint16(10, 0, true); local.setUint16(12, 0x21, true);
+    local.setUint32(14, crc, true); local.setUint32(18, data.length, true); local.setUint32(22, data.length, true);
+    local.setUint16(26, nameBytes.length, true); local.setUint16(28, 0, true);
+    parts.push(new Uint8Array(local.buffer), nameBytes, data);
+    const entry = new DataView(new ArrayBuffer(46));
+    entry.setUint32(0, 0x02014b50, true); entry.setUint16(4, 20, true); entry.setUint16(6, 20, true); entry.setUint16(8, 0x0800, true);
+    entry.setUint16(10, 0, true); entry.setUint16(12, 0, true); entry.setUint16(14, 0x21, true);
+    entry.setUint32(16, crc, true); entry.setUint32(20, data.length, true); entry.setUint32(24, data.length, true);
+    entry.setUint16(28, nameBytes.length, true); entry.setUint32(42, offset, true);
+    central.push(new Uint8Array(entry.buffer), nameBytes);
+    offset += 30 + nameBytes.length + data.length;
+  }
+  const centralSize = central.reduce((sum, part) => sum + part.length, 0);
+  const end = new DataView(new ArrayBuffer(22));
+  end.setUint32(0, 0x06054b50, true); end.setUint16(8, Object.keys(files).length, true); end.setUint16(10, Object.keys(files).length, true);
+  end.setUint32(12, centralSize, true); end.setUint32(16, offset, true);
+  return new Blob([...parts, ...central, new Uint8Array(end.buffer)], { type: 'application/zip' });
+}

package/packages/engine/src/run.mjs

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+// Runs a factory on your own machine with your own model.
+//
+//   node run.mjs                       run the factory in this folder
+//   node run.mjs path/to/factory       run a factory folder
+//   node run.mjs https://factory.mindburn.org/f/launch-kit.json
+//   node run.mjs --validate [folder, bundle.json or address]   check it, run nothing
+//
+// Model: set ANTHROPIC_API_KEY, or OPENAI_API_KEY, or point at any
+// OpenAI-compatible server (Ollama, LM Studio, OpenRouter, vLLM):
+//   node run.mjs --base-url http://localhost:11434/v1 --model llama3.3
+//
+// Options: --input name=value (repeatable)  --model NAME  --provider anthropic|openai
+//          --base-url URL  --out FILE
+//          --yes   approve every decision step without asking. This is the
+//                  only way a run is approved with nobody at the keyboard.
+//          --validate  read the factory as the Hub does and list what is wrong
+//                  or missing. No key, no model, no questions, nothing written.
+//          --test  run declared examples; write author-test-results.json.
+//          --input-schema  print the current JSON input schema and exit.
+//
+// Exit codes: 0 done, 1 failed or stopped at your decision, 3 waiting for a
+// decision nobody was there to make (run it in a terminal, or pass --yes).
+// With --validate: 0 it would run, 1 it would not.
+//
+// Needs Node 20 or newer and factory-engine.mjs next to this file.
+// --test also needs author-tests.mjs; all three ship in a packed factory. Apache-2.0.
+import { readFile, writeFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, relative, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline/promises';
+import process from 'node:process';
+
+const enginePath = new URL('./factory-engine.mjs', import.meta.url);
+const engine = await import(existsSync(enginePath) ? enginePath.href : new URL('./engine/factory-engine.mjs', import.meta.url).href);
+
+const args = process.argv.slice(2);
+const options = { inputs: {}, yes: false, validate: false };
+let target = null;
+for (let i = 0; i < args.length; i += 1) {
+  const arg = args[i];
+  if (arg === '--yes' || arg === '-y') options.yes = true;
+  else if (arg === '--test') options.test = true;
+  else if (arg === '--validate') options.validate = true;
+  else if (arg === '--input-schema') options.inputSchema = true;
+  // The help is this file's opening comment, all of it.
+  else if (arg === '--help' || arg === '-h') { const lines = (await readFile(new URL(import.meta.url), 'utf8')).split('\n').slice(1); console.log(lines.slice(0, lines.findIndex((line) => !line.startsWith('//'))).map((line) => line.replace(/^\/\/ ?/, '')).join('\n')); process.exit(0); }
+  else if (arg === '--input' || arg === '-i') { const pair = args[i += 1] || ''; const at = pair.indexOf('='); options.inputs[pair.slice(0, at)] = pair.slice(at + 1); }
+  else if (arg.startsWith('--')) options[arg.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = args[i += 1];
+  else target = arg;
+}
+
+const dim = (text) => (process.stdout.isTTY ? `\x1b[2m${text}\x1b[0m` : text);
+const bold = (text) => (process.stdout.isTTY ? `\x1b[1m${text}\x1b[0m` : text);
+const die = (message, code = 1) => { console.error(`\n${message}\n`); process.exit(code); };
+
+// The files of a factory, as the Hub would hold them. `skipped` collects what
+// looks meant for the factory but is not part of it: a misnamed flow.yml, a
+// note next to an agent. The runner and engine beside it are not listed.
+// Walk the source directories admitted by ALLOWED_PATH, never unrelated project
+// trees such as node_modules. File admission remains with the shared engine.
+const SOURCE_FOLDERS = new Set(['agents', 'automations', 'scorers', 'runners', 'routers', 'webhooks', 'benchmarks', 'skills', 'self-improvement',
+  'profiles', 'flows', 'schemas', 'prompts', 'assets', 'examples', 'checks', 'fixtures', 'capabilities', 'policies', 'adapters', 'ui']);
+async function readFolder(root, skipped = []) {
+  const files = {};
+  const walk = async (dir) => {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      const { name } = entry;
+      if (name.startsWith('.')) continue;
+      const path = join(dir, name);
+      const rel = relative(root, path).split('\\').join('/');
+      if (entry.isSymbolicLink()) {
+        if (dir !== root || SOURCE_FOLDERS.has(name) || engine.ALLOWED_PATH.test(rel)) throw new Error(`Factory source cannot contain a symbolic link: ${rel}`);
+        continue;
+      }
+      if (entry.isDirectory()) { if (SOURCE_FOLDERS.has(name) || dir !== root) await walk(path); continue; }
+      if (engine.ALLOWED_PATH.test(rel)) files[rel] = await readFile(path, 'utf8');
+      else if (dir !== root || (/\.(md|ya?ml)$/i.test(name) && name !== 'RUNNING.md')) skipped.push(rel);
+    }
+  };
+  await walk(root);
+  return files;
+}
+
+// --validate: what the Hub would make of these files, and whether this runner
+// would run them. Prints to stdout and exits 0 when it would run, 1 when not.
+function validate(files, leftOut) {
+  const { ok, errors, warnings, factory } = engine.parseBundle(files);
+  const name = `${factory.title || 'This factory'} v${factory.version}`;
+  const lines = [];
+  if (!ok) lines.push(`${name}: not a valid factory. ${errors.length} ${errors.length === 1 ? 'problem' : 'problems'}:`, ...errors.map((error) => `  - ${error}`));
+  else if (!factory.flowValid) lines.push(`${name}: readable, but ${files['flow.yaml'] === undefined ? 'it has no flow.yaml' : 'its flow.yaml has no steps'}, so there are no steps to run. It can be read, shared, and run in an agent from agents/foreman/agent.md.`);
+  else if (factory.blockers.length) lines.push(`${name}: readable, but it cannot run here:`, ...factory.blockers.map((blocker) => `  - ${blocker}`));
+  else {
+    const tools = [...new Set(factory.steps.flatMap((step) => step.tools))].sort();
+    const count = (n, one) => `${n} ${one}${n === 1 ? '' : 's'}`;
+    lines.push(`${name}: valid, and it runs here. ${count(factory.steps.length, 'step')}, ${count(Object.values(factory.agents).filter((agent) => agent.type !== 'FOREMAN').length, 'agent')}, ${count(factory.inputs.length, 'input')}; tools: ${tools.join(', ') || 'none'}.`);
+  }
+  // Blockers and the missing flow are said above; the rest is worth reading.
+  const notes = warnings.filter((warning) => !factory.blockers.includes(warning) && !warning.startsWith('This bundle has no flow.yaml'));
+  if (notes.length) lines.push('', 'Worth a look:', ...notes.map((note) => `  - ${note}`));
+  if (leftOut.length) lines.push('', `Not part of the factory, so not read: ${leftOut.join(', ')}`);
+  console.log(lines.join('\n'));
+  process.exit(ok && factory.runnable ? 0 : 1);
+}
+
+target ||= existsSync('factory.yaml') ? '.' : dirname(fileURLToPath(import.meta.url));
+let files;
+let leftOut = [];
+if (/^https?:\/\//.test(target)) {
+  const read = await engine.fromEnvelope(await (await fetch(target)).json());
+  if (read.problems.length) die(`That bundle could not be read:\n${read.problems.map((problem) => `  - ${problem}`).join('\n')}`);
+  ({ files, leftOut } = read);
+} else if (existsSync(target) && target.endsWith('.json')) {
+  const read = await engine.fromEnvelope(JSON.parse(await readFile(target, 'utf8')));
+  if (read.problems.length) die(`That bundle could not be read:\n${read.problems.map((problem) => `  - ${problem}`).join('\n')}`);
+  ({ files, leftOut } = read);
+} else {
+  if (!existsSync(join(target, 'factory.yaml'))) die(`No factory.yaml in ${target}. Run: node run.mjs path/to/factory`);
+  files = await readFolder(target, leftOut);
+}
+if (options.validate) validate(files, leftOut);
+const parsed = engine.parseBundle(files);
+if (!parsed.ok) die(`This is not a valid factory:\n${parsed.errors.map((error) => `  - ${error}`).join('\n')}`);
+if (options.inputSchema) { console.log(JSON.stringify(engine.inputSchema(parsed.factory), null, 2)); process.exit(0); }
+if (!parsed.factory.runnable) die(parsed.factory.blockers.length ? `${parsed.factory.blockers.join('\n')}\n\nOr run it in an agent that has the tool, from agents/foreman/agent.md.` : 'This factory has no flow.yaml, so there are no steps to run. Add a flow, or run it in an agent from agents/foreman/agent.md.');
+const { factory } = parsed;
+
+const kind = options.provider || (options.baseUrl || process.env.OPENAI_BASE_URL ? 'openai' : process.env.ANTHROPIC_API_KEY ? 'anthropic' : process.env.OPENAI_API_KEY ? 'openai' : null);
+if (!kind) die('No model configured. Set ANTHROPIC_API_KEY or OPENAI_API_KEY, or pass --base-url and --model for a local model.');
+const provider = kind === 'anthropic'
+  ? engine.anthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY, model: options.model || process.env.FACTORY_MODEL || 'claude-sonnet-5-5' })
+  : engine.openaiProvider({ apiKey: process.env.OPENAI_API_KEY || process.env.OPENROUTER_API_KEY || '', baseUrl: options.baseUrl || process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1', model: options.model || process.env.FACTORY_MODEL || 'gpt-5' });
+
+const terminal = createInterface({ input: process.stdin, output: process.stdout });
+console.log(`\n${bold(factory.title)}  ${dim(`v${factory.version}, ${provider.name}, ${provider.model}`)}\n${factory.description}\n`);
+for (const input of options.test ? [] : factory.inputs) {
+  if (options.inputs[input.key] !== undefined) continue;
+  if (!process.stdin.isTTY) continue;
+  const hint = input.type === 'longtext' ? ' (a file path also works)' : '';
+  options.inputs[input.key] = await terminal.question(`${bold(input.label)}${input.required ? '' : dim(' (optional)')}${hint}\n${dim(input.help)}\n> `);
+  console.log('');
+}
+for (const input of options.test ? [] : factory.inputs) {
+  const value = options.inputs[input.key];
+  if (input.type === 'longtext' && value && value.length < 300 && existsSync(value.trim())) options.inputs[input.key] = await readFile(value.trim(), 'utf8');
+}
+const checked = engine.checkInputs(factory, options.inputs);
+if (!options.test && !checked.ok) die(checked.problems.join('\n'));
+const testsPath = new URL('./author-tests.mjs', import.meta.url);
+const tests = options.test ? await import(existsSync(testsPath) ? testsPath.href : new URL('./engine/author-tests.mjs', import.meta.url).href) : null;
+const definition = tests?.readAuthorTests(files);
+if (options.test && (!definition.declared || !definition.ok)) die(definition.errors.join('\n') || 'This factory has no mindburn.tests.yaml examples.');
+
+const titleOf = (id) => factory.steps.find((step) => step.id === id)?.title || id;
+const host = {
+  provider,
+  limits: engine.DEFAULT_LIMITS,
+  now: () => Date.now(),
+  // Agents read public web pages only: never this machine or its network,
+  // whatever a factory or a page asks for. Each redirect is checked too.
+  async fetchPage(address) {
+    let url = address;
+    for (let hop = 0; hop < 6; hop += 1) {
+      if (!engine.isPublicAddress(url)) throw new Error('that is not a public web address');
+      const response = await fetch(url, { redirect: 'manual', headers: { 'user-agent': 'Mozilla/5.0 (compatible; FactoryRunner/1.0)', accept: 'text/html,*/*;q=0.5' }, signal: AbortSignal.timeout(20000) });
+      if (response.status >= 300 && response.status < 400) { url = new URL(response.headers.get('location') || '', url).href; continue; }
+      if (!response.ok) throw new Error(`the site answered with status ${response.status}`);
+      return `Address: ${url}\n\n${engine.htmlToText(await response.text(), url)}`;
+    }
+    throw new Error('the page redirects too many times');
+  },
+  emit(event) {
+    if (event.type === 'step_started') console.log(`${bold(event.title)}  ${dim(event.agent)}${event.redo ? dim('  (redoing)') : ''}`);
+    else if (event.type === 'tool') console.log(dim(`   ${titleOf(event.step)}: ${event.tool === 'web_search' ? 'searching' : 'reading'}  ${event.target}`));
+    else if (event.type === 'step_done') console.log(dim(`   ${titleOf(event.step)}: done, ${event.chars} characters`));
+    else if (event.type === 'check') console.log(`   ${event.pass ? 'passed' : event.status === 'sent_back' ? 'sent back' : 'flagged'}  ${dim(event.note)}${event.pass ? '' : `\n${event.issues.map((issue) => dim(`     - ${issue}`)).join('\n')}`}`);
+    else if (event.type === 'run_failed') console.log(`\nStopped: ${event.error}`);
+  },
+};
+
+async function execute(inputs, suffix = '') {
+const state = engine.newRun({ id: `local-${Date.now().toString(36)}${suffix}`, factory, inputs, runner: { mode: 'cli', provider: provider.name, model: provider.model } });
+await engine.runToEnd(state, host, async (approval, text, problem) => {
+  const approvalId = approval.id;
+  // The decision names the text printed here, so it cannot land on any other.
+  const seen = await engine.sha256(text);
+  if (problem === 'no_revisions') console.log(dim('This step has been sent back as often as the factory allows: approve it or reject it.'));
+  else console.log(`\n${bold(approval.title)}  ${dim('needs your decision')}\n\n${text}\n\n${dim(approval.ask)}\n`);
+  if (options.yes) return { action: 'approve', seen, approvalId };
+  // Nobody is at the keyboard: the run waits. It is never approved by default.
+  if (!process.stdin.isTTY) return null;
+  // An empty line is not a decision: ask again. Closing the input (Ctrl-D)
+  // leaves the run waiting.
+  let answer = '';
+  while (!answer) {
+    try { answer = (await terminal.question(`Type ${bold('approve')} to continue, ${bold('reject')} to stop the run, or what to change:\n> `)).trim(); } catch { return null; }
+  }
+  console.log('');
+  if (/^(approve|a|yes|y)$/i.test(answer)) return { action: 'approve', seen, approvalId };
+  if (/^(reject|stop|no|n)$/i.test(answer)) return { action: 'reject', seen, approvalId };
+  return { action: 'revise', note: answer, seen, approvalId };
+});
+return state;
+}
+if (options.test) {
+  const cases = [];
+  try {
+    for (const example of definition.cases) {
+      console.log(`\nExample: ${example.name}`);
+      const state = await execute(example.inputs, `-${example.id}`);
+      const report = await tests.evaluateAuthorTest(example, state);
+      cases.push({ caseId: example.id, ...report });
+      console.log(`${report.status}: ${report.passed}/${report.total} checks${report.failures.length ? `\n${report.failures.join('\n')}` : ''}`);
+    }
+  } finally { terminal.close(); }
+  const report = { ...tests.authorTestSummary(definition, cases), sourceSha256: await engine.bundleHash(files), provenance: 'local-run-tests', signed: false };
+  await writeFile(options.out || 'author-test-results.json', `${JSON.stringify(report, null, 2)}\n`);
+  process.exit(report.status === 'passed' ? 0 : 1);
+}
+const state = await execute(checked.inputs);
+terminal.close();
+if (state.status === 'waiting') die(`Waiting at "${state.approval.title}": no decision was made, so nothing was approved and no result was written.\nRun this in a terminal to decide, or pass --yes to approve every decision step.`, 3);
+if (state.status === 'stopped') die(`Stopped at "${state.stopped.title}" by your decision. No result was made.`);
+if (state.status !== 'done') process.exit(1);
+
+const out = options.out || `${factory.name}-${new Date().toISOString().slice(0, 16).replace(/[:T]/g, '')}.md`;
+await writeFile(out, state.deliverable);
+await writeFile(out.replace(/\.md$/, '') + '.receipt.json', `${JSON.stringify(state.receipt, null, 2)}\n`);
+console.log(`\n${state.deliverable}\n\n${dim(`Saved ${out} and its receipt. ${state.usage.llmCalls} model calls, ${state.usage.input + state.usage.output} tokens.`)}`);
+if (state.receipt.flags.length) console.log(dim(`Note: ${state.receipt.flags.join('; ')}`));

package/packages/mcp/bin/factoryhub-mcp.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// The factoryhub MCP server over stdio. Logs go to stderr; stdout carries MCP.
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { createServer } from '../src/server.mjs';
+
+serveStdio(() => createServer());

package/packages/mcp/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@factoryhub/mcp",
+  "version": "0.1.0",
+  "description": "A local stdio MCP server for AI factories: list, read, validate, export as a skill, and run with your own model, stopping at every human decision.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "private": true,
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mindburn-Labs/factoryhub.git",
+    "directory": "packages/mcp"
+  },
+  "bin": {
+    "factoryhub-mcp": "bin/factoryhub-mcp.mjs"
+  },
+  "exports": {
+    ".": "./src/server.mjs"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\""
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.4.0",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.4.0"
+  }
+}