factoryhub 0.0.0-stage → 0.1.0

package/packages/cli/src/commands/new.mjs

@@ -0,0 +1,148 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+import { engine, writeFiles, out, styles, usage } from '../util.mjs';
+
+/** The files of a new factory: small, valid, and using every kind of step. */
+export function scaffold({ name, title, description }) {
+  const heading = title || name.replace(/-/g, ' ').replace(/^./, (c) => c.toUpperCase());
+  const about = (description || `Turns a brief into a checked first draft, with your approval of the outline first. Use when you need a first draft that keeps to the brief.`).replace(/\s+/g, ' ').trim();
+  const wrapped = about.match(/.{1,76}(\s|$)/g).map((line) => `  ${line.trim()}`).join('\n');
+  return {
+    'factory.yaml': `schemaVersion: v1alpha1
+name: ${name}
+description: |
+${wrapped}
+repositories: []
+agentDefaults:
+  harness:
+    type: claude
+    model: sonnet
+`,
+    'flow.yaml': `flow: mindburn.flow/v1
+title: ${JSON.stringify(heading)}
+version: "0.1.0"
+license: Apache-2.0
+tags: [writing]
+time: about 2 minutes
+inputs:
+  brief:
+    type: longtext
+    help: "What the draft is for, who reads it, and the facts it must use."
+  example:
+    type: url
+    optional: true
+    help: "A page whose tone the draft should match, for example example.com/about."
+steps:
+  outline:
+    title: Outline the draft
+    agent: writer
+    kind: work
+    tools: [web_fetch]
+    task: |
+      If an example page was given, read it to learn its tone. Then write an
+      outline: a working title, the reader in one sentence, and four to six
+      sections with one line each on what the section says. Use only facts
+      from the brief; mark anything missing as "[ADD: what is missing]".
+  approve_outline:
+    title: Agree the outline
+    kind: approve
+    needs: [outline]
+    shows: outline
+    task: |
+      Everything else is written from this outline. Approve it, or say what
+      to change.
+  draft:
+    title: Write the draft
+    agent: writer
+    kind: deliver
+    needs: [approve_outline]
+    task: |
+      Write the full draft from the approved outline, section by section, in
+      the tone of the example page if one was read. Keep every "[ADD: ...]"
+      marker. Do not add facts that are not in the brief.
+  check_draft:
+    title: Check the draft
+    agent: reviewer
+    kind: check
+    needs: [draft]
+    checks: draft
+    task: |
+      Every section of the approved outline is present. Every fact in the
+      draft appears in the brief. Missing facts are marked "[ADD: ...]", not
+      invented.
+done:
+  - "The draft follows the approved outline."
+  - "Nothing in the draft is missing from the brief or invented."
+`,
+    'agents/writer/agent.md': `---
+description: Writes clear drafts from a brief and the steps before it.
+agentType: CUSTOM
+---
+
+You are the writer. You turn what the person gave and what earlier steps
+produced into plain, specific text for a busy reader.
+
+- You use only facts from the inputs, earlier results and pages you read.
+- Where a fact is missing, you leave a marker such as "[ADD: the price]".
+- You keep to the shape, sections and length the step asks for.
+`,
+    'agents/reviewer/agent.md': `---
+description: Checks a result against its criteria and sends weak work back.
+agentType: REVIEW
+---
+
+You are the reviewer. You compare a result with its task, the inputs and the
+earlier evidence, and you pass it only when every criterion is met.
+
+- You fail work only for a clear breach you can point to, and you say where.
+- You never fix the work yourself; you say what must change.
+`,
+    'README.md': `# ${heading}
+
+${about}
+
+Edit the files to make this factory yours:
+
+- \`factory.yaml\`: the name and what the factory is for.
+- \`flow.yaml\`: the inputs and the steps, who does each and what each needs.
+- \`agents/<name>/agent.md\`: one file per agent, its role in prose.
+
+Check it with \`factoryhub validate\`, read it back with \`factoryhub inspect .\`,
+and run it with your own model key with \`factoryhub run .\`.
+`,
+  };
+}
+
+export default {
+  name: 'new',
+  summary: 'Create a new factory folder that validates and runs.',
+  usage: `Usage: factoryhub new <name> [--dir parent] [--title text] [--description text]
+
+Creates <parent>/<name>/ with factory.yaml, flow.yaml, two agents and a README.
+The starting factory turns a brief into a checked draft and uses every kind
+of step: work, approve, deliver and check. Edit it to make it yours.
+
+<name> is lowercase letters, digits and hyphens.
+
+Options:
+  --dir          where to create the folder (default: the current folder)
+  --title        the factory's title
+  --description  what it produces and when to use it`,
+  options: { string: ['dir', 'title', 'description'] },
+  async run({ positional, flags }, io) {
+    const [name] = positional;
+    if (!name) throw usage('Name the new factory: factoryhub new my-factory');
+    if (engine.slugify(name) !== name) throw usage(`"${name}" is not a factory name. Use lowercase letters, digits and hyphens, such as ${engine.slugify(name) || 'my-factory'}.`);
+    const folder = resolve(io.cwd, flags.dir || '.', name);
+    if (existsSync(folder) && readdirSync(folder).length) throw usage(`${folder} already exists and is not empty.`);
+    const files = scaffold({ name, title: flags.title, description: flags.description });
+    const parsed = engine.parseBundle(files);
+    if (!parsed.ok || !parsed.factory.runnable) throw new Error(`The new factory did not validate:\n${[...parsed.errors, ...parsed.factory.blockers].map((item) => `  - ${item}`).join('\n')}`);
+    await writeFiles(folder, files);
+    const s = styles(io);
+    const shown = relative(io.cwd, folder) || '.';
+    out(io, `${s.green('created')}  ${shown}/ with ${Object.keys(files).sort().join(', ')}`);
+    out(io, `It validates and runs. Next:\n  factoryhub inspect ${shown}\n  factoryhub run ${shown}`);
+    return 0;
+  },
+};

package/packages/cli/src/commands/pack.mjs

@@ -0,0 +1,97 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+import { engine, readFactory, canonicalFiles, out, styles, usage } from '../util.mjs';
+import { packageManifest, zip } from '../../../engine/src/package.mjs';
+
+const RUNNER = ['run.mjs', 'factory-engine.mjs', 'author-tests.mjs'];
+const ENGINE_DIR = new URL('../../../engine/src/', import.meta.url);
+
+function running(factory, withRunner) {
+  const example = factory.inputs.filter((input) => input.required).map((input) => ` --input ${input.key}="..."`).join('');
+  return `# ${factory.title}
+
+${factory.description}
+
+This folder holds the factory's files${withRunner ? ' and a portable runner with no dependencies' : ''}. Running it calls the model you choose, with your own key; your provider bills you for it.
+
+- \`factory.yaml\`, \`flow.yaml\` and \`agents/\`: the factory.
+${withRunner ? '- `run.mjs`, `factory-engine.mjs` and `author-tests.mjs`: the runner (Apache-2.0).\n' : ''}- \`INPUTS.schema.json\`: the JSON Schema of the inputs.
+- \`FACTORY-HUB.json\`: the source hash, declared model and cost, and the validation result. It is generated, not source.
+${withRunner ? `
+## Run it
+
+Needs Node.js 22 or newer.
+
+\`\`\`sh
+export ANTHROPIC_API_KEY=...      # or OPENAI_API_KEY=...
+node run.mjs${example}
+\`\`\`
+
+A model on your own machine works through any OpenAI-compatible server:
+
+\`\`\`sh
+node run.mjs --base-url http://localhost:11434/v1 --model <name>
+\`\`\`
+
+The runner stops at every approval step and asks you. With nobody at the keyboard it stops with exit code 3 and approves nothing; \`--yes\` approves every decision and the receipt records it. \`node run.mjs --validate\` checks the files without a key and without running anything. \`node run.mjs --help\` lists every option.
+` : ''}`;
+}
+
+export default {
+  name: 'pack',
+  summary: 'Pack a factory into a zip that runs anywhere with Node, or a bundle .json.',
+  usage: `Usage: factoryhub pack <factory> [--out file] [--format zip|json] [--no-runner]
+
+zip (the default) writes <name>/ with the factory's files, the generated
+foreman, INPUTS.schema.json, FACTORY-HUB.json, RUNNING.md and the portable
+runner (run.mjs with the engine), so "node run.mjs" works after unzipping.
+
+json writes the transfer bundle (mindburn.factory.bundle/v1): every file with
+its SHA-256, the form "factoryhub run" and "factoryhub validate" read back.
+
+Options:
+  --out        output file (default: <name>-<version>.zip or <name>.bundle.json)
+  --format     zip or json
+  --no-runner  leave the runner out of the zip
+  --force      replace an existing output file`,
+  options: { boolean: ['runner', 'force'], string: ['out', 'format'] },
+  async run({ positional, flags }, io) {
+    const [target] = positional;
+    if (!target) throw usage('Name a factory to pack.');
+    const format = flags.format || 'zip';
+    if (!['zip', 'json'].includes(format)) throw usage('--format is zip or json.');
+    const read = await readFactory(target, { cwd: io.cwd, fetchImpl: io.fetch });
+    const files = canonicalFiles(read.files);
+    const parsed = engine.parseBundle(files);
+    if (!parsed.ok) throw new Error(`This factory is not valid, so it was not packed:\n${parsed.errors.map((error) => `  - ${error}`).join('\n')}`);
+    const { factory } = parsed;
+    const output = resolve(io.cwd, flags.out || (format === 'zip' ? `${factory.name}-${factory.version}.zip` : `${factory.name}.bundle.json`));
+    if (existsSync(output) && !flags.force) throw usage(`${output} already exists. Pass --force to replace it.`);
+    let bytes;
+    if (format === 'json') {
+      const envelope = engine.toEnvelope(files, { project: factory.name });
+      for (const entry of envelope.files) {
+        entry.sha256 = await engine.sha256(entry.content);
+        entry.bytes = new TextEncoder().encode(entry.content).length;
+      }
+      envelope.sha256 = await engine.bundleHash(files);
+      bytes = `${JSON.stringify(envelope, null, 2)}\n`;
+    } else {
+      const withRunner = flags.runner !== false;
+      const manifest = await packageManifest(files);
+      const dir = factory.name;
+      const entries = {};
+      for (const [path, content] of Object.entries(files)) entries[`${dir}/${path}`] = content;
+      entries[`${dir}/RUNNING.md`] = running(factory, withRunner);
+      entries[`${dir}/INPUTS.schema.json`] = `${JSON.stringify(manifest.inputs, null, 2)}\n`;
+      entries[`${dir}/FACTORY-HUB.json`] = `${JSON.stringify(manifest, null, 2)}\n`;
+      if (withRunner) for (const name of RUNNER) entries[`${dir}/${name}`] = await readFile(new URL(name, ENGINE_DIR), 'utf8');
+      bytes = Buffer.from(await zip(entries).arrayBuffer());
+    }
+    await writeFile(output, bytes);
+    const s = styles(io);
+    out(io, `${s.green('packed')}  ${relative(io.cwd, output) || output}  ${factory.title} v${factory.version}, sha256 ${await engine.bundleHash(files)}`);
+    return 0;
+  },
+};

package/packages/cli/src/commands/resume.mjs

@@ -0,0 +1,67 @@
+import { readFile, rm } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { usage } from '../util.mjs';
+import { restoreRun, decide, pendingDecision } from '../../../engine/lib/run.mjs';
+import { drive, lineReader, providerFor } from './run.mjs';
+
+const REASONS = {
+  not_waiting: 'This run is not waiting for a decision.',
+  bad_action: 'The decision must be approve, revise or reject.',
+  unseen: 'Pass --seen with the SHA-256 printed with the decision text.',
+  stale: '--seen does not match the text this run is waiting on. Show the person the current text (factoryhub resume <file> --show) and use its hash.',
+  no_revisions: 'This step has been sent back as often as the factory allows: approve or reject it.',
+};
+
+export default {
+  name: 'resume',
+  summary: 'Continue a saved run with the person\'s decision.',
+  usage: `Usage: factoryhub resume <run.json> --decision approve|revise|reject --seen <sha256> [--note text]
+       factoryhub resume <run.json> --show
+
+Continues a run that "factoryhub run --save <run.json>" saved at a decision.
+The decision must be the person's own. --seen is the SHA-256 of the exact
+text they were shown, printed with it, so a decision cannot land on other
+text. The run continues with the same provider and model, using the key in
+this environment, until it is done or reaches the next decision, where it is
+saved to the same file again.
+
+Exit codes: as for "factoryhub run".
+
+Options:
+  --decision  approve, revise (with --note saying what to change) or reject
+  --seen      the SHA-256 of the text the person saw
+  --note      what to change, for revise
+  --show      print the waiting decision and its hash, change nothing
+  --out       where to save the deliverable
+  --yes, -y   approve every later decision without asking (recorded as
+              runner mode "cli --yes" in the receipt)
+  --json      print the outcome as JSON`,
+  options: { boolean: ['show', 'yes', 'json'], string: ['decision', 'seen', 'note', 'out'], alias: { y: 'yes' } },
+  async run({ positional, flags }, io) {
+    const [file] = positional;
+    if (!file) throw usage('Name the saved run: factoryhub resume run.json --decision approve --seen <sha256>');
+    const path = resolve(io.cwd, file);
+    const state = restoreRun(JSON.parse(await readFile(path, 'utf8')));
+    const pending = await pendingDecision(state);
+    if (flags.show) {
+      if (!pending) throw usage('This run is not waiting for a decision.');
+      io.stdout.write(flags.json ? `${JSON.stringify({ step: pending.step, title: pending.title, ask: pending.ask, text: pending.text, seen_sha256: pending.seen_sha256 }, null, 2)}\n` : `${pending.title}\n\n${pending.text}\n\n${pending.ask}\n\nseen: ${pending.seen_sha256}\n`);
+      return 0;
+    }
+    if (!['approve', 'revise', 'reject'].includes(flags.decision)) throw usage('Give the person\'s decision: --decision approve, revise or reject.');
+    if (flags.decision === 'revise' && !String(flags.note || '').trim()) throw usage('A revise decision needs --note saying what to change.');
+    const why = decide(state, { action: flags.decision, note: flags.note || '', seen: flags.seen, approvalId: state.approval?.id });
+    if (why) throw usage(REASONS[why] || why);
+    if (flags.yes) state.runner = { ...state.runner, mode: 'cli --yes' };
+    const provider = providerFor(state.cli || {}, io);
+    const reader = lineReader(io);
+    try {
+      const code = await drive(state, { provider, flags, io, reader, saveTo: path });
+      // A finished or stopped run has nothing left to resume.
+      if (code !== 3) await rm(path, { force: true });
+      return code;
+    } finally {
+      reader.close();
+    }
+  },
+};

package/packages/cli/src/commands/run.mjs

@@ -0,0 +1,190 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { resolve, relative, dirname } from 'node:path';
+import { createInterface } from 'node:readline';
+import { engine, readFactory, canonicalFiles, out, json, styles, usage } from '../util.mjs';
+import { chooseProvider } from '../../../engine/lib/providers.mjs';
+import { nodeHost, prepareRun, continueRun, pendingDecision } from '../../../engine/lib/run.mjs';
+
+/** Reads typed lines one at a time, keeping answers typed ahead. */
+export function lineReader(io) {
+  let reader = null;
+  return {
+    async ask(prompt) {
+      if (!io.interactive) return null;
+      reader ||= createInterface({ input: io.stdin, terminal: false });
+      reader.iterator ||= reader[Symbol.asyncIterator]();
+      io.stderr.write(prompt);
+      const { value, done } = await reader.iterator.next();
+      return done ? null : value;
+    },
+    close() { reader?.close(); },
+  };
+}
+
+/** The provider a saved run continues with: the same settings, the key from this environment. */
+export function providerFor(settings, io) {
+  return chooseProvider({ provider: settings.provider || undefined, model: settings.model, baseUrl: settings.baseUrl || undefined, apiKeyEnv: settings.apiKeyEnv || undefined, env: io.env, fetchImpl: io.fetch });
+}
+
+/**
+ * Runs a prepared or restored run to its end or to a decision nobody answered,
+ * then reports it. Shared by `run` and `resume`. Returns the exit code.
+ */
+export async function drive(state, { provider, flags, io, reader, saveTo }) {
+  const s = styles(io);
+  const say = (text = '') => io.stderr.write(`${text}\n`);
+  const { factory } = state;
+  const titleOf = (id) => factory.steps.find((step) => step.id === id)?.title || id;
+  const host = nodeHost({
+    provider,
+    fetchImpl: io.fetch,
+    emit(event) {
+      if (event.type === 'step_started') say(`\n${s.bold(event.title)}  ${s.dim(event.agent)}${event.redo ? s.dim('  (redoing)') : ''}`);
+      else if (event.type === 'tool') say(s.dim(`   ${titleOf(event.step)}: ${event.tool === 'web_search' ? 'searching' : 'reading'} ${event.target}`));
+      else if (event.type === 'step_done') say(s.dim(`   done, ${event.chars} characters`));
+      else if (event.type === 'check') say(`   ${event.pass ? s.green('passed') : event.status === 'sent_back' ? s.yellow('sent back') : s.red(event.status === 'unreviewed' ? 'unreviewed' : 'flagged')}  ${s.dim(event.note)}${event.pass ? '' : event.issues.map((issue) => `\n     - ${issue}`).join('')}`);
+      else if (event.type === 'run_failed') say(`\n${s.red('Stopped')}: ${event.error}`);
+    },
+  });
+
+  await continueRun(state, host, async (approval, text, problem) => {
+    const seen = await engine.sha256(text);
+    if (problem === 'no_revisions') say(s.dim('This step has been sent back as often as the factory allows: approve it or reject it.'));
+    else say(`\n${s.bold(approval.title)}  ${s.yellow('needs your decision')}\n\n${text}\n\n${s.dim(approval.ask)}`);
+    if (flags.yes) { say(s.dim('Approved by --yes.')); return { action: 'approve', seen, approvalId: approval.id }; }
+    if (!io.interactive) return null;
+    let answer = '';
+    // An empty line is not a decision. Closing the input leaves the run waiting.
+    while (!answer) {
+      const line = await reader.ask(`\nType ${s.bold('approve')} to continue, ${s.bold('reject')} to stop the run, or what to change:\n> `);
+      if (line === null) return null;
+      answer = line.trim();
+    }
+    if (/^(approve|a|yes|y)$/i.test(answer)) return { action: 'approve', seen, approvalId: approval.id };
+    if (/^(reject|stop|no|n)$/i.test(answer)) return { action: 'reject', seen, approvalId: approval.id };
+    return { action: 'revise', note: answer, seen, approvalId: approval.id };
+  });
+
+  if (state.status === 'waiting') {
+    const decision = await pendingDecision(state);
+    let saved = null;
+    if (saveTo) {
+      await mkdir(dirname(saveTo), { recursive: true });
+      await writeFile(saveTo, `${JSON.stringify(state)}\n`);
+      saved = relative(io.cwd, saveTo) || saveTo;
+    }
+    if (flags.json) json(io, { status: 'waiting', step: decision.step, title: decision.title, ask: decision.ask, text: decision.text, seen_sha256: decision.seen_sha256, state: saved });
+    if (saved) {
+      if (!flags.json) say(`\n${s.bold(decision.title)}  ${s.yellow('needs a decision')}\n\n${decision.text}\n\n${s.dim(decision.ask)}`);
+      say(`\nWaiting at "${decision.title}". Nothing was approved. The run is saved in ${saved}.\nShow the person the text above, then continue with their decision:\n  factoryhub resume ${saved} --decision approve --seen ${decision.seen_sha256}\n  factoryhub resume ${saved} --decision revise --note "what to change" --seen ${decision.seen_sha256}\n  factoryhub resume ${saved} --decision reject --seen ${decision.seen_sha256}`);
+    } else say(`\nWaiting at "${decision.title}": nobody answered, so nothing was approved and no result was written.\nRun it at a terminal to decide, pass --save <file> to continue later with "factoryhub resume", or pass --yes to approve every decision.`);
+    return 3;
+  }
+  if (state.status === 'stopped') {
+    if (flags.json) json(io, { status: 'stopped', step: state.stopped.step });
+    say(`\nStopped at "${state.stopped.title}" by your decision. No result was made.`);
+    return 1;
+  }
+  if (state.status !== 'done') {
+    if (flags.json) json(io, { status: state.status, error: state.error, failure: state.failure });
+    return 1;
+  }
+  const stamp = new Date(state.finished).toISOString().slice(0, 16).replace(/[-:T]/g, '');
+  const file = resolve(io.cwd, flags.out || `${factory.name}-${stamp}.md`);
+  const receiptFile = `${file.replace(/\.md$/, '')}.receipt.json`;
+  await mkdir(dirname(file), { recursive: true });
+  await writeFile(file, state.deliverable);
+  await writeFile(receiptFile, `${JSON.stringify(state.receipt, null, 2)}\n`);
+  const review = state.receipt.deliverable_review.status;
+  if (flags.json) json(io, { status: 'done', deliverable: relative(io.cwd, file), receipt: relative(io.cwd, receiptFile), review, flags: state.receipt.flags, usage: { calls: state.usage.llmCalls, input: state.usage.input, output: state.usage.output } });
+  else out(io, state.deliverable);
+  say(s.dim(`\nSaved ${relative(io.cwd, file)} and its receipt. Final check: ${review}. ${state.usage.llmCalls} model calls, ${state.usage.input + state.usage.output} tokens.`));
+  if (state.receipt.flags.length) say(s.dim(`Note: ${state.receipt.flags.join('; ')}`));
+  return 0;
+}
+
+export default {
+  name: 'run',
+  summary: 'Run a factory with your own model key or a local model. Stops at every decision.',
+  usage: `Usage: factoryhub run <factory> [--input name=value ...] [options]
+
+Runs the factory's steps in order on this machine. Steps that do not depend
+on each other run at the same time. At every approval step the run stops,
+shows you the text, and asks: approve, reject, or say what to change.
+
+The model is yours. The first of these that is set decides:
+  ANTHROPIC_API_KEY     Anthropic (default model claude-sonnet-5-5)
+  OPENAI_API_KEY        OpenAI (default model gpt-5)
+  OPENROUTER_API_KEY    OpenRouter (default model openrouter/auto)
+or a server on your machine:
+  --provider ollama --model <name>            Ollama at http://localhost:11434/v1
+  --base-url <url> --model <name>             any OpenAI-compatible server
+
+Web search needs an Anthropic model; with other models the agents read the
+pages they are given. Agents read public web pages only.
+
+When it finishes, the deliverable is printed and saved with a receipt of
+every step. Inputs are asked for when missing and you are at a terminal.
+
+With nobody at the terminal (a script, or an agent's shell) a decision is
+never taken for you: the run stops there. With --save <file> it is saved, and
+"factoryhub resume" continues it with the person's decision.
+
+Exit codes: 0 done, 1 failed or stopped by your decision, 2 usage,
+3 waiting for a decision (nothing was approved).
+
+Options:
+  --input, -i    name=value; name=@file reads the value from a file (repeatable)
+  --provider     anthropic, openai, openrouter, ollama or openai-compatible
+  --model        the model name (or set FACTORYHUB_MODEL)
+  --base-url     an OpenAI-compatible server address
+  --api-key-env  the environment variable holding the key for --base-url
+  --save         where to save the run when it waits for a decision
+  --yes, -y      approve every decision without asking; the receipt's runner
+                 mode then reads "cli --yes"
+  --out          where to save the deliverable (default: <name>-<time>.md)
+  --json         print the outcome as JSON instead of the deliverable`,
+  options: { boolean: ['yes', 'json'], string: ['provider', 'model', 'base-url', 'api-key-env', 'out', 'save'], repeat: ['input'], alias: { i: 'input', y: 'yes' } },
+  async run({ positional, flags }, io) {
+    const [target] = positional;
+    if (!target) throw usage('Name the factory to run.');
+    const s = styles(io);
+    const read = await readFactory(target, { cwd: io.cwd, fetchImpl: io.fetch });
+    const parsed = engine.parseBundle(canonicalFiles(read.files));
+    if (!parsed.ok) throw new Error(`This is not a valid factory:\n${parsed.errors.map((error) => `  - ${error}`).join('\n')}`);
+    if (!parsed.factory.runnable) throw new Error(parsed.factory.blockers.join('\n') || 'This factory has no flow.yaml, so there are no steps to run.');
+    const { factory } = parsed;
+    const settings = { provider: flags.provider || null, model: flags.model || null, baseUrl: flags['base-url'] || null, apiKeyEnv: flags['api-key-env'] || null };
+    const provider = providerFor(settings, io);
+    settings.model = provider.model;
+
+    const inputs = {};
+    for (const pair of flags.input) {
+      const at = pair.indexOf('=');
+      if (at < 1) throw usage(`--input needs name=value, not "${pair}".`);
+      const key = pair.slice(0, at);
+      const value = pair.slice(at + 1);
+      inputs[key] = value.startsWith('@') ? await readFile(resolve(io.cwd, value.slice(1)), 'utf8') : value;
+    }
+
+    const reader = lineReader(io);
+    const say = (text = '') => io.stderr.write(`${text}\n`);
+    try {
+      say(`\n${s.bold(factory.title)}  ${s.dim(`v${factory.version}, ${provider.name}, ${provider.model}`)}`);
+      say(factory.description);
+      for (const input of factory.inputs) {
+        if (inputs[input.key] !== undefined || !io.interactive) continue;
+        const answer = await reader.ask(`\n${s.bold(input.label)}${input.required ? '' : s.dim(' (optional, Enter to skip)')}  ${s.dim(`${input.type}${input.type === 'longtext' ? ', or @file' : ''}`)}\n${s.dim(input.help)}\n> `);
+        if (answer === null) break;
+        inputs[input.key] = answer.startsWith('@') ? await readFile(resolve(io.cwd, answer.slice(1).trim()), 'utf8') : answer;
+      }
+      // An unattended approval is recorded in the receipt's runner mode.
+      const prepared = prepareRun({ files: read.files, inputs, runner: { mode: flags.yes ? 'cli --yes' : 'cli', provider: provider.name, model: provider.model } });
+      if (!prepared.ok) throw usage(prepared.problems.join('\n'));
+      prepared.state.cli = settings;
+      return await drive(prepared.state, { provider, flags, io, reader, saveTo: flags.save ? resolve(io.cwd, flags.save) : null });
+    } finally {
+      reader.close();
+    }
+  },
+};

package/packages/cli/src/commands/search.mjs

@@ -0,0 +1,31 @@
+import { out, json, table } from '../util.mjs';
+import { hubClient, DEFAULT_HUB } from '../../../engine/lib/hub.mjs';
+
+export const HUB_NOTE = `The factoryhub site is in private preview. Until it opens, it answers
+only requests that carry the preview access key: set FACTORYHUB_ACCESS_KEY
+and it is sent as the x-hub-access-key header.`;
+
+export default {
+  name: 'search',
+  summary: 'Search the published factories on factoryhub (needs FACTORYHUB_ACCESS_KEY in preview).',
+  usage: `Usage: factoryhub search [words ...] [--base-url url] [--json]
+
+Lists the published factories whose id, title, description or tags contain
+every word. With no words, lists them all.
+
+${HUB_NOTE}
+
+Options:
+  --base-url  the factoryhub address (default: FACTORYHUB_BASE_URL or ${DEFAULT_HUB})
+  --json      print the catalogue entries as JSON`,
+  options: { boolean: ['json'], string: ['base-url'] },
+  async run({ positional, flags }, io) {
+    const hub = hubClient({ baseUrl: flags['base-url'], env: io.env, fetchImpl: io.fetch });
+    const found = await hub.search(positional.join(' '));
+    if (flags.json) { json(io, found); return 0; }
+    if (!found.length) { out(io, 'No published factory matches.'); return 0; }
+    out(io, table([['ID', 'VERSION', 'TITLE'], ...found.map((entry) => [entry.id, entry.version || '', entry.title || entry.name])]));
+    out(io, `\nGet one with: factoryhub get <id>`);
+    return 0;
+  },
+};

package/packages/cli/src/commands/validate.mjs

@@ -0,0 +1,81 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { engine, readFactory, out, json, plural, styles, usage, canonicalFiles } from '../util.mjs';
+
+export default {
+  name: 'validate',
+  summary: 'Check factories the way the engine reads them. No key, no model.',
+  usage: `Usage: factoryhub validate [factory ...] [--json]
+
+Reads each factory with the engine's parser and lists every problem, every
+tool this runner does not have and every file it did not read. A factory is a
+folder, a bundle .json file, an https address of a bundle, or a house factory
+id. With no factory, validates the folder you are in.
+
+Exit codes: 0 every factory is valid and runs here, 1 one or more does not.
+
+Options:
+  --json   print the results as JSON`,
+  options: { boolean: ['json'] },
+  async run({ positional, flags }, io) {
+    const targets = positional.length ? positional : existsSync(join(io.cwd, 'factory.yaml')) ? ['.'] : [];
+    if (!targets.length) throw usage('Name a factory to validate, or run this inside a factory folder.');
+    const results = [];
+    for (const target of targets) results.push(await check(target, io));
+    if (flags.json) json(io, results);
+    else results.forEach((result, index) => { if (index) out(io); print(result, io); });
+    return results.every((result) => result.runnable) ? 0 : 1;
+  },
+};
+
+export async function check(target, io) {
+  let read;
+  try {
+    read = await readFactory(target, { cwd: io.cwd, fetchImpl: io.fetch });
+  } catch (error) {
+    return { target, valid: false, runnable: false, errors: [error.message], warnings: [], blockers: [], leftOut: [] };
+  }
+  const { ok, errors, warnings, factory } = engine.parseBundle(read.files);
+  // Blockers and the missing flow are reported on their own lines.
+  const notes = warnings.filter((warning) => !factory.blockers.includes(warning) && !warning.startsWith('This bundle has no flow.yaml'));
+  return {
+    target,
+    name: factory.name,
+    title: factory.title,
+    version: factory.version,
+    valid: ok,
+    hasFlow: factory.flowValid,
+    runnable: ok && factory.runnable,
+    sha256: ok ? await engine.bundleHash(canonicalFiles(read.files)) : null,
+    steps: factory.steps.length,
+    agents: Object.values(factory.agents).filter((agent) => agent.type !== 'FOREMAN').length,
+    inputs: factory.inputs.length,
+    tools: [...new Set(factory.steps.flatMap((step) => step.tools))].sort(),
+    errors,
+    blockers: factory.blockers,
+    warnings: notes,
+    leftOut: read.leftOut,
+    hasFlowFile: read.files['flow.yaml'] !== undefined,
+  };
+}
+
+function print(result, io) {
+  const s = styles(io);
+  const name = result.title ? `${result.title} v${result.version}` : result.target;
+  if (!result.valid) {
+    out(io, `${s.red('invalid')}  ${name} (${result.target}): ${plural(result.errors.length, 'problem')}`);
+    for (const error of result.errors) out(io, `  - ${error}`);
+  } else if (!result.hasFlow) {
+    out(io, `${s.yellow('no flow')}  ${name}: readable, but ${result.hasFlowFile ? 'its flow.yaml has no steps' : 'it has no flow.yaml'}, so there is nothing to run. An agent can follow agents/foreman/agent.md.`);
+  } else if (result.blockers.length) {
+    out(io, `${s.yellow('blocked')}  ${name}: valid, but it cannot run here:`);
+    for (const blocker of result.blockers) out(io, `  - ${blocker}`);
+  } else {
+    out(io, `${s.green('valid')}    ${name}: runs here. ${plural(result.steps, 'step')}, ${plural(result.agents, 'agent')}, ${plural(result.inputs, 'input')}; tools: ${result.tools.join(', ') || 'none'}.`);
+  }
+  if (result.warnings.length) {
+    out(io, '  Worth a look:');
+    for (const warning of result.warnings) out(io, `  - ${warning}`);
+  }
+  if (result.leftOut.length) out(io, `  Not part of the factory, so not read: ${result.leftOut.join(', ')}`);
+}