factoryhub 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,52 @@
+import { out, json, table, styles, usage, connect, BASE_URL_HELP } from '../util.mjs';
+import { listRuns, finish } from '../hosted.mjs';
+import { FINISHED } from '../../../engine/lib/hosted.mjs';
+
+export default {
+  name: 'runs',
+  usage: `Usage: factoryhub runs [--limit n] [--base-url url] [--json]
+       factoryhub runs <run-id> [--out file] [--base-url url] [--json]
+
+With no run id, lists your recent hosted runs, newest first.
+
+With a run id, shows where that run is. A finished run's result is printed
+and saved with its signed receipt, which is checked here: on
+factory.mindburn.org against the production keys pinned in this version of
+factoryhub, elsewhere against the keys that hub publishes; the receipt's
+issuer must be that hub. A run waiting for you names the step and the page
+where you decide.
+
+Needs a login with the runs:read scope.
+
+Exit codes with a run id: 0 done and verified, 1 failed, stopped or not
+verified, 3 waiting for a decision.
+
+Options:
+  --limit     how many runs to list, 1 to 30 (default 15)
+  --out       where to save the result (default: <factory>-<time>.md)
+  --base-url  ${BASE_URL_HELP}
+  --json      print the answer as JSON`,
+  options: { boolean: ['json'], string: ['limit', 'out', 'base-url'] },
+  async run({ positional, flags }, io) {
+    const [id, ...rest] = positional;
+    if (rest.length) throw usage('Show one run at a time: factoryhub runs <run-id>');
+    if (!id) {
+      if (flags.out) throw usage('--out saves one run\'s result: factoryhub runs <run-id> --out file.md');
+      const runs = await listRuns(flags, io);
+      if (flags.json) { json(io, runs); return 0; }
+      if (!runs.length) { out(io, 'No hosted runs yet. Start one with: factoryhub run <id> --hosted'); return 0; }
+      out(io, table([['ID', 'STATUS', 'STARTED', 'FACTORY'], ...runs.map((run) => [run.id, run.status, String(run.started || '').slice(0, 16).replace('T', ' '), run.title || run.factoryId])]));
+      out(io, styles(io).dim('\nShow one, and save its result: factoryhub runs <run-id>'));
+      return 0;
+    }
+    if (flags.limit) throw usage('--limit applies to the list of runs, not to one run.');
+    const { hub } = await connect(flags, io, { needToken: true });
+    const run = await hub.getRun(id);
+    if (!run.waiting && !FINISHED.has(run.status)) {
+      if (flags.json) json(io, { status: run.status, run: run.id, url: run.url });
+      else out(io, `${run.title || run.factoryId}: ${run.status}. Follow it on ${run.url}`);
+      return 0;
+    }
+    return finish(hub, run, { io, flags, name: run.factoryId || 'run' });
+  },
+};

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

@@ -0,0 +1,30 @@
+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',
+  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,79 @@
+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',
+  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 = await Promise.all(targets.map((target) => 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(', ')}`);
+}

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

@@ -0,0 +1,34 @@
+import { out, json, styles, usage, connect, day, BASE_URL_HELP } from '../util.mjs';
+import { credentialsPath } from '../../../engine/lib/credentials.mjs';
+
+export default {
+  name: 'whoami',
+  usage: `Usage: factoryhub whoami [--base-url url] [--json]
+
+Asks factoryhub who the token acts for: the account, the token's name,
+scopes and expiry, and where the token comes from (FACTORYHUB_TOKEN or the
+login saved on this computer). The token itself is never printed.
+
+Exit codes: 0 logged in, 1 not logged in or the token is not accepted.
+
+Options:
+  --base-url  ${BASE_URL_HELP}
+  --json      print the answer as JSON`,
+  options: { boolean: ['json'], string: ['base-url'] },
+  async run({ positional, flags }, io) {
+    if (positional.length) throw usage('whoami takes no words, only options.');
+    const { hub, credential, base } = await connect(flags, io, { needToken: true });
+    const me = await hub.me();
+    const source = credential.source === 'env' ? 'FACTORYHUB_TOKEN' : credentialsPath(io.env);
+    if (flags.json) {
+      json(io, { base, source: credential.source, account: me.account, token: me.token });
+      return 0;
+    }
+    const s = styles(io);
+    out(io, `${s.bold(`@${me.account.handle}`)}${me.account.name ? ` (${me.account.name})` : ''} on ${base}`);
+    out(io, `  Token    ${me.token.name} (${me.token.prefix ? `${me.token.prefix}…` : 'fhpat_…'}), from ${source}`);
+    out(io, `  Scopes   ${me.token.scopes.join(', ')}`);
+    out(io, `  Expires  ${day(me.token.expires)}`);
+    return 0;
+  },
+};

package/packages/cli/src/hosted.mjs

@@ -0,0 +1,159 @@
+// `factoryhub run <id> --hosted` and `factoryhub runs <id>`: start and follow
+// runs on factoryhub, decide where the person decides, and save the result
+// with its signed receipt.
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { resolve, relative, dirname } from 'node:path';
+import { out, err, json, styles, usage, connect } from './util.mjs';
+import { followRun, runResult, newIdempotencyKey, receiptVerdict } from '../../engine/lib/hosted.mjs';
+import { FACTORY_ID } from '../../engine/lib/hub.mjs';
+
+const pauseFor = (io) => io.sleep || ((ms) => new Promise((done) => setTimeout(done, ms)));
+/** Options of `run` that only a run on this machine uses; a hosted run refuses them. */
+export const LOCAL_ONLY = ['provider', 'model', 'base-url', 'api-key-env', 'effort', 'max-output', 'timeout', 'check-model', 'check-effort', 'save',
+  'experimental-tools', 'mcp', 'mcp-token-env', 'allow-tool', 'read-only', 'nango', 'nango-user', 'grant', 'bind', 'target'];
+// A repeatable option is an empty list when it is not given.
+const given = (value) => (Array.isArray(value) ? value.length > 0 : value !== undefined);
+
+/** name=value pairs, with name=@file read from a file. */
+export async function readInputs(pairs, io) {
+  const inputs = {};
+  for (const pair of pairs) {
+    const at = pair.indexOf('=');
+    if (at < 1) throw usage(`--input needs name=value, not "${pair}".`);
+    const value = pair.slice(at + 1);
+    inputs[pair.slice(0, at)] = value.startsWith('@') ? await readFile(resolve(io.cwd, value.slice(1)), 'utf8') : value;
+  }
+  return inputs;
+}
+
+/**
+ * Saves a finished run's result and receipt; returns their paths. Without
+ * `outFile` the name comes from the factory id, which the hub sends: one that
+ * is not a factory id is replaced by "run", so it never names a path.
+ */
+export async function saveResult(io, { name, result, outFile, finished }) {
+  const stamp = new Date(finished || Date.now()).toISOString().slice(0, 16).replace(/[-:T]/g, '');
+  const file = resolve(io.cwd, outFile || `${FACTORY_ID.test(String(name || '')) ? name : 'run'}-${stamp}.md`);
+  const receiptFile = `${file.replace(/\.md$/, '')}.receipt.json`;
+  await mkdir(dirname(file), { recursive: true });
+  await writeFile(file, result.text);
+  if (result.receipt) await writeFile(receiptFile, `${JSON.stringify(result.receipt, null, 2)}\n`);
+  return { file: relative(io.cwd, file) || file, receipt: result.receipt ? relative(io.cwd, receiptFile) || receiptFile : null };
+}
+
+
+/**
+ * Reports a run that finished, waits or failed. Returns the exit code:
+ * 0 done, 1 failed or stopped, 3 waiting for a decision.
+ */
+export async function finish(hub, run, { io, flags, name }) {
+  const s = styles(io);
+  const say = (text = '') => err(io, text);
+  if (run.waiting) {
+    const waiting = run.waiting;
+    if (flags.json) json(io, { status: 'waiting', run: run.id, url: run.url, step: waiting.step, title: waiting.title, ask: waiting.ask, approval_id: waiting.approval_id, artifact_sha256: waiting.artifact_sha256, complete: waiting.complete });
+    say(`\nWaiting at "${waiting.title}" for your decision. Nothing was decided.\nDecide on the run page: ${run.url}\nThen read the result with: factoryhub runs ${run.id}`);
+    return 3;
+  }
+  if (run.status === 'done') {
+    const result = await runResult(hub, run.id);
+    if (!result) {
+      if (flags.json) json(io, { status: 'done', run: run.id, url: run.url, error: 'no_result' });
+      say(`\n${s.red('No result')}: the run is done, but ${hub.base} sent no result to save. ${run.url}`);
+      return 1;
+    }
+    const saved = await saveResult(io, { name, result, outFile: flags.out });
+    if (flags.json) json(io, { status: 'done', run: run.id, url: run.url, deliverable: saved.file, receipt: saved.receipt, review: result.review, verification: result.verification });
+    else out(io, result.text);
+    say(s.dim(`\nSaved ${saved.file}${saved.receipt ? ' and its receipt' : ''}. Final check: ${result.review}. Receipt: ${receiptVerdict(result.verification)}.`));
+    return result.verification.verified ? 0 : 1;
+  }
+  if (flags.json) json(io, { status: run.status, run: run.id, url: run.url, error: run.error, stopped: run.stopped });
+  if (run.status === 'stopped' && run.stopped) say(`\nStopped at "${run.stopped.title}" by a decision. No result was made.`);
+  else say(`\n${s.red(run.status === 'failed' ? 'Failed' : `Run ${run.status}`)}${run.error ? `: ${run.error}` : '.'} ${run.url}`);
+  return 1;
+}
+
+/** Asks the person at the terminal; null when nobody answers. */
+async function askPerson(reader, io, waiting) {
+  const s = styles(io);
+  let answer = '';
+  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 { decision: 'approve' };
+  if (/^(reject|stop|no|n)$/i.test(answer)) return { decision: 'reject' };
+  if (waiting.revisionsLeft === 0) err(io, s.dim('This step cannot be sent back again: approve it or reject it.'));
+  return waiting.revisionsLeft === 0 ? askPerson(reader, io, waiting) : { decision: 'revise', note: answer };
+}
+
+/** `factoryhub run <id> --hosted`. */
+export async function hostedRun(target, flags, io, reader) {
+  const used = LOCAL_ONLY.filter((name) => given(flags[name]));
+  if (used.length) throw usage(`--${used[0]} applies to a run on this machine. A hosted run uses factoryhub's model; leave it out.`);
+  const s = styles(io);
+  const say = (text = '') => err(io, text);
+  const { hub } = await connect({ 'base-url': flags.hub }, io, { needToken: true });
+  const me = await hub.me();
+  const scopes = me.token.scopes || [];
+  if (!scopes.includes('runs:start') || !scopes.includes('runs:read')) {
+    throw new Error(`A hosted run needs a token with runs:start and runs:read; this one has ${scopes.join(', ') || 'none'}. Log in again: factoryhub login --scopes ${[...new Set([...scopes, 'runs:start', 'runs:read'])].join(',')}`);
+  }
+  const canDecide = scopes.includes('runs:decide');
+  if (flags.yes && !canDecide) throw new Error('--yes on a hosted run needs a token with the opt-in runs:decide scope. Log in again with it, or leave out --yes and decide on the run page.');
+
+  const { factory } = await hub.factory(target);
+  if (!factory.runnable) throw new Error(`${target} does not run: ${(factory.blockers || []).join(' ') || 'it has no steps.'}`);
+  const inputs = await readInputs(flags.input, io);
+  say(`\n${s.bold(factory.title)}  ${s.dim(`v${factory.version}, hosted on ${hub.base}`)}`);
+  if (factory.description) 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;
+    if (answer !== '' || input.required) inputs[input.key] = answer.startsWith('@') ? await readFile(resolve(io.cwd, answer.slice(1).trim()), 'utf8') : answer;
+  }
+
+  const started = await hub.startRun(target, inputs, { idempotencyKey: newIdempotencyKey() });
+  say(`Started ${started.url}${Number.isFinite(started.runsLeftToday) ? s.dim(`  (${started.runsLeftToday} hosted runs left today)`) : ''}`);
+  say(s.dim('Ctrl+C stops following here; the run goes on, and "factoryhub runs" finds it.'));
+  const titles = new Map();
+  const decided = new Set();
+  const pause = pauseFor(io);
+  for (;;) {
+    const run = await followRun(hub, started.id, {
+      sleep: io.sleep,
+      onEvent(event, view) {
+        for (const step of view.steps || []) titles.set(step.id, step.title);
+        const title = titles.get(event.step) || event.step || '';
+        if (event.type === 'step_started') say(`\n${s.bold(title)}`);
+        else if (event.type === 'step_done') say(s.dim('   done'));
+        else if (event.type === 'check') say(`   ${event.status === 'passed' ? s.green('passed') : s.yellow(event.status || 'checked')}`);
+        else if (event.type === 'run_failed') say(`\n${s.red('Stopped')}: ${event.error || ''}`);
+        else if (event.type && title) say(s.dim(`   ${title}: ${event.type.replace(/_/g, ' ')}${event.status ? ` (${event.status})` : ''}`));
+      },
+    });
+    const waiting = run.waiting;
+    // A decision this command sent that the run has not taken yet: keep following.
+    if (waiting && decided.has(`${waiting.approval_id}:${waiting.artifact_sha256}`)) { await pause(2000); continue; }
+    if (!waiting) return finish(hub, run, { io, flags, name: started.factoryId || target });
+    if (!flags.json) say(`\n${s.bold(waiting.title)}  ${s.yellow('needs your decision')}\n\n${waiting.text}${waiting.complete ? '' : `\n[${waiting.totalChars} characters in all; the rest is on the run page.]`}\n\n${s.dim(waiting.ask)}`);
+    let choice = null;
+    if (flags.yes) { choice = { decision: 'approve' }; say(s.dim('Approved by --yes.')); }
+    else if (canDecide && io.interactive && waiting.complete) choice = await askPerson(reader, io, waiting);
+    else if (!canDecide && io.interactive) say(s.dim('This token cannot decide steps (it lacks the opt-in runs:decide scope).'));
+    if (!choice) return finish(hub, run, { io, flags, name: started.factoryId || target });
+    await hub.decide(run.id, { approvalId: waiting.approval_id, seenSha256: waiting.artifact_sha256, decision: choice.decision, note: choice.note || '' });
+    decided.add(`${waiting.approval_id}:${waiting.artifact_sha256}`);
+  }
+}
+
+/** `factoryhub runs` with no id: the account's recent runs. */
+export async function listRuns(flags, io) {
+  const { hub } = await connect(flags, io, { needToken: true });
+  const limit = flags.limit === undefined ? undefined : Number(flags.limit);
+  if (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > 30)) throw usage('--limit needs a whole number from 1 to 30.');
+  return hub.runs({ limit });
+}

package/packages/cli/src/main.mjs

@@ -0,0 +1,134 @@
+// factoryhub: find, run, make and share AI factories from the terminal.
+import process from 'node:process';
+import { readFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { parseArgs } from './args.mjs';
+import { hasControl } from '../../engine/lib/text.mjs';
+
+// Every command, in the order --help lists them. A command's module is
+// imported only when that command runs: `factoryhub --version` or one
+// command does not load the engine, the packer, the runner and the hub
+// client of all the others. Usage and options stay in each module.
+export const COMMANDS = [
+  { name: 'list', summary: 'List the house factories, or the factory folders in a directory.', load: () => import('./commands/list.mjs') },
+  { name: 'inspect', summary: 'Show what a factory does: inputs, steps in order, agents, tools, checks.', load: () => import('./commands/inspect.mjs') },
+  { name: 'validate', summary: 'Check factories the way the engine reads them. No key, no model.', load: () => import('./commands/validate.mjs') },
+  { name: 'run', summary: 'Run a factory with your own model key or a local model. Stops at every decision.', load: () => import('./commands/run.mjs') },
+  { name: 'resume', summary: 'Continue a saved run with the person\'s decision.', load: () => import('./commands/resume.mjs') },
+  { name: 'new', summary: 'Create a new factory folder that validates and runs.', load: () => import('./commands/new.mjs') },
+  { name: 'pack', summary: 'Pack a factory into a zip that runs anywhere with Node, or a bundle .json.', load: () => import('./commands/pack.mjs') },
+  { name: 'export', summary: 'Export a factory as an Agent Skill folder (SKILL.md plus the factory).', load: () => import('./commands/export.mjs') },
+  { name: 'search', summary: 'Search the published factories on factoryhub (needs FACTORYHUB_ACCESS_KEY in preview).', load: () => import('./commands/search.mjs') },
+  { name: 'get', summary: 'Download a published factory from factoryhub into a folder, checking every file.', load: () => import('./commands/get.mjs') },
+  { name: 'login', summary: 'Log in to factoryhub from this computer, with a code you approve in your browser.', load: () => import('./commands/login.mjs') },
+  { name: 'logout', summary: 'Revoke this computer\'s factoryhub token on the server, then forget it.', load: () => import('./commands/logout.mjs') },
+  { name: 'whoami', summary: 'Show which factoryhub account and token this computer uses.', load: () => import('./commands/whoami.mjs') },
+  { name: 'push', summary: 'Save a factory folder to your factoryhub account, privately. Nothing is published.', load: () => import('./commands/push.mjs') },
+  { name: 'pull', summary: 'Download a factory you can open on factoryhub, yours included, checking every file.', load: () => import('./commands/pull.mjs') },
+  { name: 'publish', summary: 'Publish one of your factories on factoryhub, so anyone can find and run it.', load: () => import('./commands/publish.mjs') },
+  { name: 'runs', summary: 'List your hosted runs on factoryhub, or show one and save its result and receipt.', load: () => import('./commands/runs.mjs') },
+  { name: 'mcp', summary: 'Start the local MCP server on stdio, for MCP clients.', load: () => import('./commands/mcp.mjs') },
+];
+
+/** Every command's module with its summary, for the CLI reference. */
+export async function loadCommands() {
+  return Promise.all(COMMANDS.map(async ({ name, summary, load }) => ({ ...(await load()).default, name, summary })));
+}
+
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+/**
+ * The command that opens `url` in a browser on `platform`, or null when the
+ * address is not a plain http(s) one. No shell runs it: on Windows,
+ * rundll32 hands the address to the default browser, so characters cmd.exe
+ * would read (& | ^ % < > ") are never interpreted.
+ */
+export function browserCommand(url, platform = process.platform) {
+  let parsed;
+  try { parsed = new URL(String(url)); } catch { return null; }
+  if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password) return null;
+  const href = parsed.href;
+  // The URL parser percent-encodes spaces, quotes and controls; refuse anything it left.
+  if (/[\s"'`<>\\]/.test(href) || hasControl(href)) return null;
+  if (platform === 'darwin') return ['open', [href]];
+  if (platform === 'win32') return ['rundll32', ['url.dll,FileProtocolHandler', href]];
+  return ['xdg-open', [href]];
+}
+
+/** Opens an address in the person's browser. True when a browser was started. */
+export function openInBrowser(url, { platform = process.platform, spawnImpl = spawn } = {}) {
+  const command = browserCommand(url, platform);
+  if (!command) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    try {
+      const child = spawnImpl(command[0], command[1], { stdio: 'ignore', detached: true, shell: false, windowsHide: true });
+      child.once('error', () => resolve(false));
+      child.once('spawn', () => { child.unref(); resolve(true); });
+    } catch { resolve(false); }
+  });
+}
+
+/** The streams and environment a command uses. Tests pass their own. */
+export function defaultIo() {
+  return {
+    stdout: process.stdout,
+    stderr: process.stderr,
+    stdin: process.stdin,
+    env: process.env,
+    cwd: process.cwd(),
+    fetch: globalThis.fetch,
+    interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    color: Boolean(process.stdout.isTTY) && !process.env.NO_COLOR,
+    // Runs `cleanup` (at most five seconds) before Ctrl+C or a stop signal
+    // ends the process. Returns the function that removes it again.
+    onInterrupt(cleanup) {
+      const handler = (signal) => {
+        Promise.race([Promise.resolve().then(cleanup).catch(() => {}), new Promise((resolve) => { setTimeout(resolve, 5000).unref?.(); })])
+          .finally(() => process.exit(signal === 'SIGTERM' ? 143 : 130));
+      };
+      process.once('SIGINT', handler);
+      process.once('SIGTERM', handler);
+      return () => { process.off('SIGINT', handler); process.off('SIGTERM', handler); };
+    },
+    // Only at a terminal: a script or an agent's shell never opens a browser.
+    openUrl: process.stdin.isTTY && process.stdout.isTTY ? openInBrowser : null,
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  };
+}
+
+function help(io) {
+  const width = Math.max(...COMMANDS.map((command) => command.name.length));
+  io.stdout.write(`factoryhub ${VERSION}: find, run, make and share AI factories.
+
+Usage: factoryhub <command> [options]
+
+Commands:
+${COMMANDS.map((command) => `  ${command.name.padEnd(width)}  ${command.summary}`).join('\n')}
+
+Run "factoryhub <command> --help" for a command's options.
+A factory is a folder with factory.yaml, flow.yaml and agents/<name>/agent.md.
+The format: spec/factory-format.md in https://github.com/Mindburn-Labs/factoryhub
+`);
+}
+
+/** Runs one command line. Returns the exit code. */
+export async function main(argv, io = defaultIo()) {
+  const [name, ...rest] = argv;
+  if (!name || name === '--help' || name === '-h' || name === 'help') { help(io); return 0; }
+  if (name === '--version' || name === '-v') { io.stdout.write(`${VERSION}\n`); return 0; }
+  const entry = COMMANDS.find((item) => item.name === name);
+  if (!entry) { io.stderr.write(`Unknown command "${name}". Run "factoryhub --help" for the list.\n`); return 2; }
+  const command = (await entry.load()).default;
+  let args;
+  try { args = parseArgs(rest, command.options || {}); } catch (error) {
+    io.stderr.write(`${error.message}\n\n${command.usage}\n`);
+    return 2;
+  }
+  if (args.flags.help) { io.stdout.write(`${command.usage}\n`); return 0; }
+  try {
+    return await command.run(args, io);
+  } catch (error) {
+    io.stderr.write(`${error.message}\n`);
+    return error.usage ? 2 : 1;
+  }
+}