factoryhub 0.1.0 → 0.1.1

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

@@ -1,22 +1,73 @@
 // 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 validate from './commands/validate.mjs';
-import inspect from './commands/inspect.mjs';
-import list from './commands/list.mjs';
-import create from './commands/new.mjs';
-import pack from './commands/pack.mjs';
-import run from './commands/run.mjs';
-import resume from './commands/resume.mjs';
-import exportCommand from './commands/export.mjs';
-import search from './commands/search.mjs';
-import get from './commands/get.mjs';
-import mcp from './commands/mcp.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 })));
+}
 
-export const COMMANDS = [list, inspect, validate, run, resume, create, pack, exportCommand, search, get, mcp];
 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 {
@@ -28,6 +79,20 @@ export function defaultIo() {
     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)),
   };
 }
 
@@ -51,8 +116,9 @@ 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 command = COMMANDS.find((item) => item.name === name);
-  if (!command) { io.stderr.write(`Unknown command "${name}". Run "factoryhub --help" for the list.\n`); return 2; }
+  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`);

package/packages/cli/src/tool-sources.mjs

@@ -0,0 +1,272 @@
+// Experimental tool sources for `factoryhub run`: reading the flags, and
+// opening the MCP servers and Nango sessions they name. Nothing here runs
+// without --experimental-tools. See docs/experimental-tool-sources.md.
+import { usage } from './util.mjs';
+import { createMcpClient, MIN_TOKEN_LENGTH } from '../../engine/src/mcp-client.mjs';
+import { createToolSources, displayLine } from '../../engine/src/tool-sources.mjs';
+import { openNangoSession } from '../../engine/lib/nango.mjs';
+import { isPrivateIp } from '../../engine/lib/run.mjs';
+import { isPublicAddress } from '../../engine/src/factory-engine.mjs';
+import { lookup } from 'node:dns/promises';
+
+// Flags that name sources on the command line; and flags that grant the sources a factory declares.
+export const TOOL_SOURCE_FLAGS = ['mcp', 'mcp-token-env', 'allow-tool', 'read-only', 'nango'];
+export const GRANT_FLAGS = ['grant', 'bind', 'target'];
+const NAME = /^[a-z0-9][a-z0-9_-]{0,40}$/;
+const TOOL = /^[A-Za-z0-9_.-]{1,128}$/;
+const ENV = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]']);
+
+const split = (value, sep, flag) => {
+  const at = value.indexOf(sep);
+  if (at < 1 || at === value.length - 1) throw usage(`--${flag} needs ${flag === 'mcp' ? 'name=url' : flag === 'mcp-token-env' ? 'name=ENV_VAR' : 'name:tool'}, not "${value}".`);
+  return [value.slice(0, at), value.slice(at + 1)];
+};
+
+/**
+ * The tool sources the flags name, checked, or null when none are given.
+ * Every flag here needs --experimental-tools.
+ */
+export function toolSourcePlan(flags, env) {
+  const given = [...TOOL_SOURCE_FLAGS, ...GRANT_FLAGS].filter((flag) => flags[flag]?.length);
+  if (flags['nango-user'] !== undefined) given.push('nango-user');
+  if (!flags['experimental-tools']) {
+    if (given.length) throw usage(`${given.map((flag) => `--${flag}`).join(', ')} need${given.length === 1 ? 's' : ''} --experimental-tools: tool sources are an experimental runner mode.`);
+    return null;
+  }
+  const granting = GRANT_FLAGS.filter((flag) => flags[flag]?.length);
+  if (granting.length) throw usage(`${granting.map((flag) => `--${flag}`).join(', ')} grant${granting.length === 1 ? 's' : ''} the sources a factory declares, and this factory declares none.`);
+  const sources = new Map();
+  const add = (name, entry, flag) => {
+    if (!NAME.test(name)) throw usage(`--${flag}: "${name}" is not a source name. Use lowercase letters, digits, - and _.`);
+    if (sources.has(name)) throw usage(`The tool source "${name}" is named twice.`);
+    sources.set(name, { name, allow: [], readOnly: [], ...entry });
+  };
+  for (const value of flags.mcp || []) {
+    const [name, address] = split(value, '=', 'mcp');
+    let url;
+    try { url = new URL(address); } catch { throw usage(`--mcp ${name}: "${address}" is not a URL.`); }
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && LOOPBACK.has(url.hostname))) throw usage(`--mcp ${name}: the address must start with https:// (http:// only for this machine).`);
+    if (url.username || url.password) throw usage(`--mcp ${name}: put credentials in an environment variable and name it with --mcp-token-env, not in the address.`);
+    add(name, { kind: 'mcp', url: url.href, tokenEnv: null }, 'mcp');
+  }
+  for (const value of flags['mcp-token-env'] || []) {
+    const [name, variable] = split(value, '=', 'mcp-token-env');
+    const source = sources.get(name);
+    if (!source || source.kind !== 'mcp') throw usage(`--mcp-token-env ${name}: there is no --mcp ${name}=<url>.`);
+    if (!ENV.test(variable)) throw usage(`--mcp-token-env ${name}: "${variable}" is not an environment variable name.`);
+    if (!env[variable]) throw usage(`${variable} is not set.`);
+    if (env[variable].length < MIN_TOKEN_LENGTH) throw usage(`${variable} holds a token shorter than ${MIN_TOKEN_LENGTH} characters, too short to find again in what the server sends back.`);
+    source.tokenEnv = variable;
+  }
+  for (const value of flags.nango || []) {
+    const [integration, list] = value.includes(':') ? split(value, ':', 'nango') : [value, ''];
+    add(integration, { kind: 'nango' }, 'nango');
+    for (const tool of list.split(',').map((item) => item.trim()).filter(Boolean)) sources.get(integration).allow.push(tool);
+  }
+  for (const [flag, field] of [['allow-tool', 'allow'], ['read-only', 'readOnly']]) {
+    for (const value of flags[flag] || []) {
+      const [name, list] = split(value, ':', flag);
+      const source = sources.get(name);
+      if (!source) throw usage(`--${flag} ${name}: there is no tool source "${name}". Name it with --mcp or --nango first.`);
+      source[field].push(...list.split(',').map((item) => item.trim()).filter(Boolean));
+    }
+  }
+  if (!sources.size) throw usage('--experimental-tools needs a tool source: --mcp name=url or --nango integration:tool.');
+  if (flags['nango-user'] !== undefined && ![...sources.values()].some((source) => source.kind === 'nango')) throw usage('--nango-user goes with --nango.');
+  for (const source of sources.values()) {
+    const tools = [...source.allow, ...source.readOnly];
+    const bad = tools.find((tool) => !TOOL.test(tool));
+    if (bad) throw usage(`"${bad}" is not a tool name.`);
+    if (!tools.length) throw usage(`Allow at least one tool of "${source.name}": --allow-tool ${source.name}:<tool>, --read-only ${source.name}:<tool>${source.kind === 'nango' ? ` or --nango ${source.name}:<tool>` : ''}.`);
+    if (source.kind === 'nango' && !env.NANGO_API_KEY) throw usage('NANGO_API_KEY is not set.');
+    source.allow = [...new Set(source.allow)];
+    source.readOnly = [...new Set(source.readOnly)];
+  }
+  return { sources: [...sources.values()], endUserId: flags['nango-user'] || 'local-dev-user' };
+}
+
+/**
+ * What is open, so it can be closed from anywhere: the end of a run, an
+ * error, or Ctrl+C while sources are still being opened. Closing twice is
+ * harmless.
+ */
+export function openThings() {
+  const closers = [];
+  return {
+    add(closeOne) { closers.push(closeOne); },
+    async close() { await Promise.all(closers.splice(0).map((closeOne) => Promise.resolve().then(closeOne).catch(() => {}))); },
+  };
+}
+
+/**
+ * Opens every source in the plan and builds the run's catalog. Each source
+ * is added to `open` as soon as it exists. Resolves to `{ sources, close }`,
+ * or to `{ needsConnection }` when a Nango integration is not connected yet
+ * (nothing stays open then).
+ */
+export async function openToolSources(plan, { env, fetchImpl, open = openThings() }) {
+  const closers = { push: (closeOne) => open.add(closeOne) };
+  const close = () => open.close();
+  try {
+    const specs = [];
+    for (const source of plan.sources) {
+      let client;
+      if (source.kind === 'nango') {
+        // Registered for Ctrl+C before Nango is first asked: see openNangoSession.
+        const session = await openNangoSession({ apiKey: env.NANGO_API_KEY, integration: source.integration || source.name, tools: [...new Set([...source.allow, ...source.readOnly])], endUserId: plan.endUserId, fetchImpl, register: (closeOne) => closers.push(closeOne) });
+        if (!session.connected) {
+          await close();
+          return { needsConnection: session };
+        }
+        client = session.client;
+      } else {
+        client = createMcpClient({ url: source.url, token: source.tokenEnv ? env[source.tokenEnv] : '', fetchImpl });
+        closers.push(() => client.close());
+      }
+      specs.push({
+        name: source.name, client, allow: source.allow, readOnly: source.readOnly,
+        // A source the factory declares: its declarations, target, and how it was granted.
+        ...(source.declared ? { declared: source.declared, target: source.target || null, targetValue: source.targetValue } : {}),
+        ...(source.kind === 'nango' && source.integration && source.integration !== source.name ? { prefix: source.integration } : {}),
+        granted: source.granted || (source.kind === 'nango' ? 'nango' : 'address'),
+      });
+    }
+    const sources = await createToolSources(specs);
+    return { sources, close };
+  } catch (error) {
+    await close();
+    throw error;
+  }
+}
+
+const PLAIN = { read: 'reads', write: 'changes something', external: 'sends outside', irreversible: 'cannot be undone' };
+const hostOf = (url) => { try { return new URL(url).host; } catch { return '(no address)'; } };
+
+/**
+ * The plan for the sources a factory declares (RFC 0017, experimental): for
+ * each source a step uses, the grant the flags give it, if any. Nothing is
+ * granted by the factory alone, and --yes never grants. A source the person
+ * has not granted here may still be granted at an interactive terminal; the
+ * run starts only when every one is.
+ *
+ * - `--grant <source>`: the address the factory declares, with a token from
+ *   `--mcp-token-env <source>=<ENV>` when the server needs one.
+ * - `--bind <source>=nango:<integration>`: a Nango agent session limited to
+ *   the declared tools the steps use.
+ * - `--bind <source>=<url>`: another address, with a token as above.
+ * - `--target <source>=<value>`: the one target the run is limited to.
+ * - `--read-only <source>:<tool>`: the person vouches that a declared read
+ *   only reads, for a server that does not mark it so.
+ */
+export function declaredPlan(declarations, flags, env) {
+  const cliOnly = ['mcp', 'nango', 'allow-tool'].filter((flag) => flags[flag]?.length);
+  if (cliOnly.length) throw usage(`This factory declares the sources it needs: grant them with --grant or --bind, not ${cliOnly.map((flag) => `--${flag}`).join(', ')}.`);
+  const used = new Map();
+  for (const capability of Object.keys(declarations.uses)) {
+    const [source, tool] = capability.split('/');
+    if (!used.has(source)) used.set(source, new Set());
+    used.get(source).add(tool);
+  }
+  const known = (key, flag) => { if (!Object.hasOwn(declarations.sources, key)) throw usage(`--${flag} ${displayLine(key)}: the factory declares no source "${displayLine(key)}".`); return declarations.sources[key]; };
+  const bindings = new Map();
+  const bind = (key, binding) => { if (bindings.has(key)) throw usage(`The source "${key}" is granted twice.`); bindings.set(key, binding); };
+  for (const key of flags.grant || []) {
+    const source = known(key, 'grant');
+    if (!source.url) throw usage(`The source "${key}" declares no address, only a registry name: bind it with --bind ${key}=<url> or --bind ${key}=nango:<integration>.`);
+    bind(key, { kind: 'mcp', url: source.url, granted: 'declared' });
+  }
+  for (const value of flags.bind || []) {
+    const [key, where] = split(value, '=', 'bind');
+    known(key, 'bind');
+    if (where.startsWith('nango:')) {
+      const integration = where.slice('nango:'.length);
+      if (!NAME.test(integration)) throw usage(`--bind ${key}: "${integration}" is not a Nango integration name.`);
+      if (!env.NANGO_API_KEY) throw usage('NANGO_API_KEY is not set.');
+      bind(key, { kind: 'nango', integration, granted: 'nango' });
+      continue;
+    }
+    let url;
+    try { url = new URL(where); } catch { throw usage(`--bind ${key}: "${where}" is not a URL or nango:<integration>.`); }
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && LOOPBACK.has(url.hostname))) throw usage(`--bind ${key}: the address must start with https:// (http:// only for this machine).`);
+    if (url.username || url.password) throw usage(`--bind ${key}: put credentials in an environment variable and name it with --mcp-token-env, not in the address.`);
+    bind(key, { kind: 'mcp', url: url.href, granted: 'address' });
+  }
+  const targets = new Map();
+  for (const value of flags.target || []) {
+    const [key, given] = split(value, '=', 'target');
+    const source = known(key, 'target');
+    if (!source.target) throw usage(`The source "${key}" declares no target.`);
+    if (given.length > 500 || /[\p{Cc}\p{Cf}]/u.test(given)) throw usage(`--target ${key}: a target is plain text of at most 500 characters.`);
+    targets.set(key, given);
+  }
+  const tokens = new Map();
+  for (const value of flags['mcp-token-env'] || []) {
+    const [key, variable] = split(value, '=', 'mcp-token-env');
+    known(key, 'mcp-token-env');
+    if (!ENV.test(variable)) throw usage(`--mcp-token-env ${key}: "${variable}" is not an environment variable name.`);
+    if (!env[variable]) throw usage(`${variable} is not set.`);
+    if (env[variable].length < MIN_TOKEN_LENGTH) throw usage(`${variable} holds a token shorter than ${MIN_TOKEN_LENGTH} characters, too short to find again in what the server sends back.`);
+    tokens.set(key, variable);
+  }
+  const vouched = new Map();
+  for (const value of flags['read-only'] || []) {
+    const [key, list] = split(value, ':', 'read-only');
+    const source = known(key, 'read-only');
+    for (const tool of list.split(',').map((item) => item.trim()).filter(Boolean)) {
+      if (!Object.hasOwn(source.tools, tool)) throw usage(`--read-only ${key}: the factory declares no tool "${displayLine(tool)}" for that source.`);
+      if (source.tools[tool].effect !== 'read') throw usage(`--read-only ${key}: the factory declares "${tool}" as ${source.tools[tool].effect}, so it cannot be vouched for as a read.`);
+      if (!vouched.has(key)) vouched.set(key, []);
+      vouched.get(key).push(tool);
+    }
+  }
+  for (const [key, binding] of bindings) if (binding.kind === 'nango' && tokens.has(key)) throw usage(`--mcp-token-env ${key}: a Nango session brings its own token.`);
+  if (flags['nango-user'] !== undefined && ![...bindings.values()].some((binding) => binding.kind === 'nango')) throw usage('--nango-user goes with --bind <source>=nango:<integration>.');
+  return {
+    endUserId: flags['nango-user'] || 'local-dev-user',
+    sources: [...used.keys()].map((key) => {
+      const source = declarations.sources[key];
+      return {
+        name: key, title: source.title, url: source.url, binding: bindings.get(key) || null,
+        allow: [...used.get(key)], readOnly: vouched.get(key) || [], declared: source.tools, target: source.target,
+        targetValue: targets.get(key), tokenEnv: tokens.get(key) || null, uses: declarations.uses,
+      };
+    }),
+  };
+}
+
+/**
+ * An address the factory declares is reached only when it is public: a host
+ * name on the normal ports that resolves to no local or private address
+ * (section 5.5 of the format). The check is made before any connection.
+ * An address the person gives with --bind is theirs to choose.
+ */
+export async function checkDeclaredAddress(source, { lookupImpl = (host) => lookup(host, { all: true, verbatim: true }) } = {}) {
+  const host = hostOf(source.url);
+  const refuse = (why) => usage(`The address the factory declares for the source "${source.name}" (${host}) ${why}, so nothing was connected. Bind it yourself with --bind ${source.name}=<url> if you mean to reach it.`);
+  if (!isPublicAddress(source.url)) throw refuse('is not a public address');
+  let answers;
+  try { answers = await lookupImpl(new URL(source.url).hostname); } catch { throw refuse('could not be found'); }
+  if (!answers?.length || answers.some((answer) => isPrivateIp(answer.address))) throw refuse('points at this machine or a private network');
+}
+
+/** What the factory asks for, for the person to read before granting anything. */
+export function consentText({ title, version, hash, plan, provider }) {
+  const lines = [`${displayLine(title, 120)} v${displayLine(version, 40)} (sha256 ${hash.slice(0, 12)}) asks to use these sources. Nothing is connected until each one is granted:`];
+  for (const source of plan.sources) {
+    const binding = source.binding;
+    const where = !binding ? (source.url ? `${hostOf(source.url)}, the address the factory declares` : 'no address yet: the factory names only a registry entry')
+      : binding.kind === 'nango' ? `a Nango agent session for ${binding.integration}, limited to the tools below`
+        : `${hostOf(binding.url)}${binding.granted === 'declared' ? ', the address the factory declares' : ', the address you gave'}`;
+    lines.push('', `  ${source.name}: ${displayLine(source.title, 100)}`, `    reached at: ${where}`);
+    if (source.target) lines.push(`    limited to one ${displayLine(source.target.label, 40)}: ${source.targetValue === undefined ? '(not given yet)' : displayLine(source.targetValue, 200)}${source.target.help ? `. ${displayLine(source.target.help, 200)}` : ''}`);
+    for (const tool of source.allow) {
+      const declared = source.declared[tool];
+      const steps = source.uses[`${source.name}/${tool}`] || [];
+      lines.push(`    ${source.name}/${tool}  "${displayLine(declared.title, 100)}"  the factory says it ${PLAIN[declared.effect]}  used by: ${steps.map((step) => displayLine(step, 100)).join(', ')}${source.target && !declared.target ? `  (not limited to one ${displayLine(source.target.label, 40)})` : ''}`);
+    }
+  }
+  lines.push('', '  A source receives the arguments the model writes, which can include the inputs a step sees.',
+    `  What a tool returns goes to the model provider: ${displayLine(provider, 200)}. Only tools that read can run, and a grant lasts for this run only.`);
+  return lines.join('\n');
+}

package/packages/cli/src/util.mjs

@@ -1,4 +1,7 @@
 // Shared bits for the commands: styling, output and the engine imports.
+import { hubClient, checkedBase, DEFAULT_HUB } from '../../engine/lib/hub.mjs';
+import { resolveToken } from '../../engine/lib/credentials.mjs';
+import { usage as usageError } from '../../engine/lib/node.mjs';
 export * as engine from '../../engine/src/factory-engine.mjs';
 export { readFactory, readFolder, writeFiles, listFactoryDirs, usage, HOUSE_FACTORIES } from '../../engine/lib/node.mjs';
 export { summarize, canonicalFiles, matches } from '../../engine/lib/catalog.mjs';
@@ -19,3 +22,37 @@ export function table(rows) {
   const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => String(row[column] ?? '').length)));
   return rows.map((row) => row.map((cell, column) => (column === row.length - 1 ? String(cell ?? '') : String(cell ?? '').padEnd(widths[column]))).join('  ').trimEnd()).join('\n');
 }
+
+// ---- the factoryhub site ----
+
+export { DEFAULT_HUB };
+export const BASE_URL_HELP = `the factoryhub address (default: FACTORYHUB_BASE_URL or ${DEFAULT_HUB})`;
+
+/** The hub address a command talks to. Tokens travel only over https, or http to this machine. */
+export function hubBase(flags, io) {
+  try {
+    return checkedBase(flags['base-url'] || io.env.FACTORYHUB_BASE_URL || DEFAULT_HUB);
+  } catch (error) {
+    throw usageError(error.message);
+  }
+}
+
+/** A date for people: 2027-02-13. */
+export const day = (iso) => (iso ? String(iso).slice(0, 10) : 'never');
+
+/**
+ * A hub client with the token from FACTORYHUB_TOKEN or `factoryhub login`.
+ * With `needToken`, refuses before any request when there is none.
+ */
+export async function connect(flags, io, { needToken = false } = {}) {
+  const base = hubBase(flags, io);
+  const credential = await resolveToken(base, io.env);
+  if (credential.warning) io.stderr.write(`${styles(io).yellow(credential.warning)}\n`);
+  if (needToken && !credential.token) {
+    throw new Error(credential.expired
+      ? `Your login to ${base} expired on ${day(credential.record.expires)}. Run "factoryhub login" to log in again.`
+      : `You are not logged in to ${base}. Run "factoryhub login" first, or set FACTORYHUB_TOKEN.`);
+  }
+  const hub = hubClient({ baseUrl: base, env: io.env, fetchImpl: io.fetch, token: credential.token, tokenSource: credential.source, tokenScopes: credential.record?.scopes || null });
+  return { hub, credential, base };
+}