factoryhub 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,37 @@
+import { existsSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+import { engine, writeFiles, out, styles, usage } from '../util.mjs';
+import { hubClient, DEFAULT_HUB } from '../../../engine/lib/hub.mjs';
+import { HUB_NOTE } from './search.mjs';
+
+export default {
+  name: 'get',
+  usage: `Usage: factoryhub get <id> [--out dir] [--base-url url] [--force]
+
+Downloads the factory's transfer bundle, checks every file against its
+recorded SHA-256, and writes the files to <dir>/<id>/.
+
+${HUB_NOTE}
+
+Options:
+  --out       the parent folder (default: the current folder)
+  --base-url  the factoryhub address (default: FACTORYHUB_BASE_URL or ${DEFAULT_HUB})
+  --force     write into an existing folder`,
+  options: { boolean: ['force'], string: ['out', 'base-url'] },
+  async run({ positional, flags }, io) {
+    const [id] = positional;
+    if (!id) throw usage('Name the factory to get: factoryhub get <id>');
+    const hub = hubClient({ baseUrl: flags['base-url'], env: io.env, fetchImpl: io.fetch });
+    const factory = await hub.get(id);
+    const folder = resolve(io.cwd, flags.out || '.', id);
+    if (existsSync(folder) && !flags.force) throw usage(`${folder} already exists. Pass --force to write into it.`);
+    await writeFiles(folder, factory.files);
+    const parsed = engine.parseBundle(factory.files);
+    const s = styles(io);
+    const state = !parsed.ok ? s.red('invalid') : parsed.factory.runnable ? s.green('runs here') : s.yellow('does not run here');
+    out(io, `${s.green('saved')}  ${relative(io.cwd, folder) || folder}/  ${parsed.factory.title} v${parsed.factory.version}, ${Object.keys(factory.files).length} files, ${state}`);
+    if (factory.leftOut.length) out(io, `Not part of the factory, so not written: ${factory.leftOut.join(', ')}`);
+    out(io, `Source: ${factory.source}`);
+    return parsed.ok ? 0 : 1;
+  },
+};

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

@@ -0,0 +1,65 @@
+import { engine, readFactory, summarize, out, json, table, plural, styles, usage, canonicalFiles } from '../util.mjs';
+
+export default {
+  name: 'inspect',
+  usage: `Usage: factoryhub inspect <factory> [--json]
+
+Prints a factory's inputs, its steps stage by stage (steps in one stage can
+run at the same time), who does each, its agents, tools, and the
+statements its deliverable is checked against. A factory is a folder, a
+bundle .json file, an https address of a bundle, or a house factory id.
+
+Options:
+  --json   print the full summary as JSON, including the JSON Schema of the inputs`,
+  options: { boolean: ['json'] },
+  async run({ positional, flags }, io) {
+    const [target] = positional;
+    if (!target) throw usage('Name a factory to inspect.');
+    const read = await readFactory(target, { cwd: io.cwd, fetchImpl: io.fetch });
+    const summary = await summarize(read.files, { id: read.source.id });
+    if (flags.json) { json(io, summary); return summary.valid ? 0 : 1; }
+    const s = styles(io);
+    if (!summary.valid) {
+      out(io, `${s.red('invalid')}  ${target}`);
+      for (const error of summary.errors) out(io, `  - ${error}`);
+      return 1;
+    }
+    const { factory } = engine.parseBundle(canonicalFiles(read.files));
+    out(io, `${s.bold(summary.title)}  ${s.dim(`v${summary.version}${summary.license ? `, ${summary.license}` : ''}${summary.author ? `, by ${summary.author}` : ''}`)}`);
+    out(io, summary.description);
+    out(io, s.dim(`${summary.name}  sha256 ${summary.sha256}${summary.time ? `  ${summary.time}` : ''}  ${summary.runnable ? 'runs here' : 'does not run here'}`));
+    out(io);
+    out(io, s.bold('Inputs'));
+    out(io, summary.inputs.length ? table(summary.inputs.map((input) => [`  ${input.key}`, input.type, input.required ? 'required' : 'optional', input.help])) : '  none');
+    out(io);
+    if (factory.steps.length) {
+      const { columns } = engine.layout(factory);
+      out(io, s.bold(`Steps (${plural(factory.steps.length, 'step')} in ${plural(columns.length, 'stage')})`));
+      const rows = [];
+      columns.forEach((ids, stage) => {
+        for (const id of ids) {
+          const step = factory.steps.find((item) => item.id === id);
+          const who = step.kind === 'approve' ? 'the person' : step.agent;
+          const detail = step.kind === 'check' ? `checks ${step.target}` : step.kind === 'approve' ? `shows ${step.target}, waits for a decision` : step.needs.length ? `after ${step.needs.join(', ')}` : 'first';
+          const tools = [...step.tools, ...step.missing];
+          rows.push([`  ${stage + 1}`, step.id, step.kind, who, `${detail}${tools.length ? `; tools ${tools.join(', ')}` : ''}`]);
+        }
+      });
+      out(io, table(rows));
+    } else out(io, `${s.bold('Steps')}\n  none: this factory has no flow`);
+    out(io);
+    out(io, s.bold('Agents'));
+    out(io, table(summary.agents.map((agent) => [`  ${agent.name}`, agent.type === 'FOREMAN' ? 'coordinates the flow (generated from it)' : agent.description])));
+    if (summary.done.length) {
+      out(io);
+      out(io, s.bold('Done when'));
+      for (const line of summary.done) out(io, `  - ${line}`);
+    }
+    if (summary.blockers.length) {
+      out(io);
+      out(io, s.bold('Cannot run here'));
+      for (const blocker of summary.blockers) out(io, `  - ${blocker}`);
+    }
+    return 0;
+  },
+};

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

@@ -0,0 +1,24 @@
+import { resolve } from 'node:path';
+import { readFolder, listFactoryDirs, summarize, matches, out, json, table, HOUSE_FACTORIES } from '../util.mjs';
+
+export default {
+  name: 'list',
+  usage: `Usage: factoryhub list [directory] [--query words] [--json]
+
+Lists the factory folders directly inside a directory. With no directory,
+lists the house factories that ship with factoryhub.
+
+Options:
+  --query  keep factories whose id, title, description or tags contain every word
+  --json   print the summaries as JSON`,
+  options: { boolean: ['json'], string: ['query'] },
+  async run({ positional, flags }, io) {
+    const dir = positional[0] ? resolve(io.cwd, positional[0]) : HOUSE_FACTORIES;
+    const entries = await Promise.all((await listFactoryDirs(dir)).map(async (id) => summarize((await readFolder(resolve(dir, id))).files, { id })));
+    const kept = entries.filter((entry) => matches(entry, flags.query));
+    if (flags.json) { json(io, kept); return 0; }
+    if (!kept.length) { out(io, entries.length ? 'No factory matches.' : `No factory folders in ${dir}.`); return 0; }
+    out(io, table([['ID', 'VERSION', 'STEPS', 'INPUTS', 'TITLE'], ...kept.map((entry) => [entry.id, entry.version, entry.steps.length, entry.inputs.length, entry.valid ? entry.title : `${entry.title} (invalid)`])]));
+    return 0;
+  },
+};

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

@@ -0,0 +1,161 @@
+import { hostname } from 'node:os';
+import { createInterface } from 'node:readline';
+import { Writable } from 'node:stream';
+import { out, err, json, styles, usage, connect, day, BASE_URL_HELP } from '../util.mjs';
+import { hubClient, deviceLogin, SCOPES, OPT_IN_SCOPES, TOKEN_PATTERN } from '../../../engine/lib/hub.mjs';
+import { saveCredential, storedCredential, credentialsPath, TOKEN_ENV, PRIVACY } from '../../../engine/lib/credentials.mjs';
+
+const MAX_DAYS = 366;
+
+/** Scopes from --scopes "a,b" or "a b": each one known, none repeated. */
+export function parseScopes(value) {
+  if (value === undefined) return null;
+  const scopes = [...new Set(String(value).split(/[\s,]+/).filter(Boolean))];
+  if (!scopes.length) throw usage(`--scopes needs at least one of: ${SCOPES.join(', ')}.`);
+  const unknown = scopes.filter((scope) => !SCOPES.includes(scope));
+  if (unknown.length) throw usage(`Unknown scope ${unknown.join(', ')}. Choose from: ${SCOPES.join(', ')}.`);
+  return SCOPES.filter((scope) => scopes.includes(scope));
+}
+
+function parseDays(value) {
+  if (value === undefined) return null;
+  const days = Number(value);
+  if (!Number.isInteger(days) || days < 1 || days > MAX_DAYS) throw usage(`--days needs a whole number from 1 to ${MAX_DAYS}, not "${value}".`);
+  return days;
+}
+
+/** Reads a token without showing it: hidden typing at a terminal, else all of stdin. */
+export async function readSecret(io, prompt) {
+  if (io.stdin.isTTY) {
+    io.stderr.write(prompt);
+    const muted = new Writable({ write(_chunk, _encoding, done) { done(); } });
+    const reader = createInterface({ input: io.stdin, output: muted, terminal: true });
+    try {
+      const line = await new Promise((resolve) => { reader.once('line', resolve); reader.once('close', () => resolve('')); });
+      io.stderr.write('\n');
+      return line.trim();
+    } finally { reader.close(); }
+  }
+  let text = '';
+  for await (const chunk of io.stdin) text += chunk;
+  return text.trim();
+}
+
+const shortName = () => `factoryhub CLI on ${hostname() || 'this computer'}`.slice(0, 60);
+const prefixOf = (token) => (token?.prefix ? `${token.prefix}…` : 'fhpat_…');
+
+/** What the person sees once a token is stored. */
+function report(io, { base, me, path, flags, replaced, origin }) {
+  const s = styles(io);
+  if (flags.json) {
+    json(io, { base, account: { handle: me.account.handle, name: me.account.name }, token: { id: me.token.id, name: me.token.name, prefix: me.token.prefix, scopes: me.token.scopes, expires: me.token.expires, origin }, saved: path, replaced });
+    return;
+  }
+  out(io, `${s.green('Logged in')} to ${base} as ${s.bold(`@${me.account.handle}`)}.`);
+  out(io, `  Token    ${me.token.name} (${prefixOf(me.token)}), expires ${day(me.token.expires)}`);
+  out(io, `  Scopes   ${me.token.scopes.join(', ')}`);
+  out(io, `  Saved in ${path}, ${PRIVACY}.`);
+  if (replaced === 'revoked') out(io, s.dim('  The token this computer received by its previous login was revoked.'));
+  else if (replaced === 'kept') out(io, s.dim('  The token saved before was one you passed in, so it was not revoked: revoke it in your account settings if nothing else uses it.'));
+  else if (replaced === 'not_revoked') out(io, s.yellow('  The token this computer received by its previous login could not be revoked: revoke it in your account settings.'));
+  out(io, `\nNext: ${s.bold('factoryhub push <folder>')} saves a factory to your account, privately.`);
+  if (!me.token.scopes.includes('factories:publish')) out(io, s.dim('To publish factories from here, log in with --scopes including factories:publish.'));
+  if (io.env[TOKEN_ENV]) err(io, s.yellow(`\nFACTORYHUB_TOKEN is set, so it is used instead of this login until you unset it.`));
+}
+
+// After a new token is stored, the one it replaced is revoked only if this
+// CLI received it by device login: it was never printed, so nothing else
+// should be using it. A token the person passed in with --token may also live
+// in CI or another machine, so it is left alone. A record without an origin
+// predates this rule and is treated as passed in.
+// Returns 'revoked', 'not_revoked', 'kept' or null when nothing was replaced.
+async function revokeReplaced(base, previous, io) {
+  if (!previous?.token) return null;
+  if (previous.origin !== 'device') return 'kept';
+  try {
+    await hubClient({ baseUrl: base, env: io.env, fetchImpl: io.fetch, token: previous.token }).revoke();
+    return 'revoked';
+  } catch {
+    return 'not_revoked';
+  }
+}
+
+export default {
+  name: 'login',
+  usage: `Usage: factoryhub login [--scopes a,b] [--name text] [--days n] [--no-browser]
+       factoryhub login --token < token.txt
+
+Shows a short code and opens the factoryhub device page. Sign in there,
+check the code matches, choose what this computer may do, and approve.
+The token it receives is saved in ${'${XDG_CONFIG_HOME:-~/.config}'}/factoryhub/credentials.json,
+readable only by you on macOS and Linux (mode 0600; on Windows, as private
+as your user folder). It is never printed. A later login revokes a token an
+earlier device login saved, but never one you passed in with --token.
+
+Scopes (default: every scope that is not opt-in):
+  factories:read     open your private factories
+  factories:write    save factories to your account (push)
+  runs:start         start hosted runs
+  runs:read          follow your runs and read their results
+  factories:publish  publish factories (opt-in: tick it on the page)
+  runs:decide        decide a waiting step for you (opt-in: tick it on the page)
+
+For CI or a machine without a browser, make a token in your account
+settings and pass it on standard input with --token, or set FACTORYHUB_TOKEN
+(which always wins over a saved login).
+
+Options:
+  --scopes      the scopes to ask for, comma-separated
+  --name        what the token is called on your account page
+                (default: "factoryhub CLI on <this computer>")
+  --days        how long the token lives, 1 to ${MAX_DAYS} days (default: the hub's, 90)
+  --no-browser  print the address instead of opening it
+  --token       read a token from standard input instead
+  --base-url    ${BASE_URL_HELP}
+  --json        print the result as JSON`,
+  options: { boolean: ['token', 'browser', 'json'], string: ['scopes', 'name', 'days', 'base-url'] },
+  async run({ positional, flags }, io) {
+    if (positional.length) throw usage(`login takes no words, only options. To pass a token, use: factoryhub login --token < token.txt`);
+    const { base, hub } = await connect(flags, io);
+    const s = styles(io);
+    const scopes = parseScopes(flags.scopes);
+    const days = parseDays(flags.days);
+    const name = flags.name === undefined ? shortName() : String(flags.name).trim().slice(0, 60);
+    if (!name) throw usage('--name cannot be empty.');
+    const previous = await storedCredential(base, io.env);
+
+    let token;
+    let origin;
+    if (flags.token) {
+      if (flags.scopes || flags.days || flags.name) throw usage('--token uses the token as it was made; --scopes, --days and --name apply to a new login only.');
+      token = await readSecret(io, 'Paste your factoryhub token (it is not shown) and press Enter: ');
+      if (!token) throw usage('No token on standard input. Pass it like this: factoryhub login --token < token.txt');
+      if (!TOKEN_PATTERN.test(token)) throw usage('That is not a factoryhub personal access token: they start with fhpat_ and are 49 characters long.');
+      origin = 'pasted';
+    } else {
+      const asked = scopes || [];
+      const optIn = asked.filter((scope) => OPT_IN_SCOPES.includes(scope));
+      const answer = await deviceLogin(hub, {
+        name, scopes, days,
+        sleep: io.sleep,
+        onCode: async ({ userCode, verificationUri, verificationUriComplete, expiresIn }) => {
+          err(io, `To log in to ${base}, open this page in a browser where you are signed in:\n\n  ${s.bold(verificationUri)}\n\nand enter the code  ${s.bold(userCode)}\n`);
+          err(io, s.dim(`Check that the page shows the same code before you approve.${optIn.length ? ` Tick ${optIn.join(' and ')} there: opt-in scopes are granted only when you tick them.` : ''}`));
+          const page = verificationUriComplete || verificationUri;
+          if (flags.browser !== false && io.openUrl && new URL(page, base).origin === new URL(base).origin) {
+            if (await io.openUrl(new URL(page, base).href)) err(io, s.dim('Opened the page in your browser.'));
+          }
+          err(io, `Waiting for you to approve (the code works for ${Math.round(expiresIn / 60)} minutes; Ctrl+C to stop)...`);
+        },
+      });
+      token = answer.access_token;
+      origin = 'device';
+    }
+
+    const me = await hubClient({ baseUrl: base, env: io.env, fetchImpl: io.fetch, token }).me();
+    const path = await saveCredential(base, { token, origin, id: me.token.id, name: me.token.name, prefix: me.token.prefix, scopes: me.token.scopes, expires: me.token.expires, account: me.account.handle }, io.env);
+    const replaced = previous && previous.token !== token ? await revokeReplaced(base, previous, io) : null;
+    report(io, { base, me, path: credentialsPath(io.env) || path, flags, replaced, origin });
+    return 0;
+  },
+};

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

@@ -0,0 +1,43 @@
+import { out, styles, usage, hubBase, BASE_URL_HELP } from '../util.mjs';
+import { hubClient } from '../../../engine/lib/hub.mjs';
+import { storedCredential, deleteCredential, credentialsPath, TOKEN_ENV } from '../../../engine/lib/credentials.mjs';
+
+export default {
+  name: 'logout',
+  usage: `Usage: factoryhub logout [--base-url url]
+
+Revokes the token "factoryhub login" saved, on the factoryhub server first,
+so it stops working everywhere, and then deletes it from this computer. If
+the server cannot be reached, nothing is deleted: run it again later, or
+revoke the token in your account settings.
+
+A token in FACTORYHUB_TOKEN is not touched: unset it yourself, and revoke it
+in your account settings if nobody needs it.
+
+Options:
+  --base-url  ${BASE_URL_HELP}`,
+  options: { string: ['base-url'] },
+  async run({ positional, flags }, io) {
+    if (positional.length) throw usage('logout takes no words, only options.');
+    const s = styles(io);
+    const base = hubBase(flags, io);
+    const stored = await storedCredential(base, io.env);
+    const envNote = io.env[TOKEN_ENV] ? s.yellow(`\nFACTORYHUB_TOKEN is still set, so commands still use that token. Unset it, and revoke it in your account settings if nobody needs it.`) : '';
+    if (!stored) {
+      out(io, `Not logged in to ${base} on this computer: nothing to do.${envNote}`);
+      return 0;
+    }
+    let note;
+    try {
+      await hubClient({ baseUrl: base, env: io.env, fetchImpl: io.fetch, token: stored.token, tokenSource: 'file' }).revoke();
+      note = 'revoked on the server';
+    } catch (error) {
+      // A token the server no longer accepts is already as good as revoked.
+      if (error.status === 401) note = 'the server no longer accepted it';
+      else throw new Error(`${error.message}\nThe token was not revoked, so it is still saved in ${credentialsPath(io.env)}. Try again, or revoke "${stored.name || 'it'}" in your account settings.`, { cause: error });
+    }
+    await deleteCredential(base, io.env);
+    out(io, `${s.green('Logged out')} of ${base}: ${stored.name ? `"${stored.name}" ` : ''}${note}, and deleted from this computer.${envNote}`);
+    return 0;
+  },
+};

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

@@ -0,0 +1,25 @@
+// Starts the local MCP server on stdio: the same server as the factoryhub-mcp bin.
+// It exists so one published package starts its MCP server with
+// `npx factoryhub mcp`, the form MCP registries and clients build from
+// server.json (identifier + version, then the package arguments).
+// stdout carries MCP only; the server logs to stderr.
+
+export default {
+  name: 'mcp',
+  usage: `Usage: factoryhub mcp
+
+Starts the factoryhub MCP server on stdin and stdout, the same server as the
+factoryhub-mcp command. An MCP client starts it; it is not meant to be typed.
+Model keys and folders come from the environment: ANTHROPIC_API_KEY,
+OPENAI_API_KEY or OPENROUTER_API_KEY (only to run factories), FACTORYHUB_MODEL,
+FACTORYHUB_FACTORIES and FACTORYHUB_RUNS_DIR.`,
+  options: {},
+  async run() {
+    // Loaded here, not at the top, so other commands do not pay for the MCP SDK.
+    const { serveStdio } = await import('@modelcontextprotocol/server/stdio');
+    const { createServer } = await import('../../../mcp/src/server.mjs');
+    serveStdio(() => createServer());
+    // The open stdin keeps the process alive until the client closes it.
+    return 0;
+  },
+};

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

@@ -0,0 +1,147 @@
+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',
+  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,96 @@
+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',
+  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/publish.mjs

@@ -0,0 +1,62 @@
+import { out, json, styles, usage, connect, BASE_URL_HELP } from '../util.mjs';
+
+/** The reasons a refused submission carries, as lines for a person. */
+export function refusalLines(details) {
+  if (!details) return [];
+  const lines = [];
+  for (const blocker of details.blockers || []) lines.push(`  - ${blocker}`);
+  const tests = details.tests;
+  if (tests && typeof tests === 'object') {
+    lines.push(`  - Declared examples: ${tests.status || 'not run'}${Number.isFinite(tests.passed) && Number.isFinite(tests.total) ? ` (${tests.passed} of ${tests.total} passed)` : ''}`);
+    for (const failure of (tests.failures || tests.cases || []).filter((item) => item && item.status && item.status !== 'passed').slice(0, 5)) lines.push(`      ${failure.id || failure.name || 'case'}: ${failure.status}`);
+  }
+  const scan = details.scan;
+  if (scan && typeof scan === 'object') {
+    lines.push(`  - Archive check: ${scan.status || 'not run'}${scan.summary ? `. ${scan.summary}` : ''}`);
+    for (const concern of (scan.concerns || scan.findings || []).slice(0, 5)) lines.push(`      ${typeof concern === 'string' ? concern : concern.summary || concern.title || JSON.stringify(concern)}`);
+  }
+  return lines;
+}
+
+export default {
+  name: 'publish',
+  usage: `Usage: factoryhub publish <id> [--note text] [--base-url url] [--json]
+
+Publishes a factory you pushed. factoryhub runs the checks the site runs
+first (for example, that it runs), and refuses with the reasons when one
+fails. Publishing again changes nothing.
+
+Needs a login with the opt-in factories:publish scope:
+  factoryhub login --scopes factories:read,factories:write,factories:publish
+
+Options:
+  --note      a note recorded with this publication
+  --base-url  ${BASE_URL_HELP}
+  --json      print the hub's answer as JSON`,
+  options: { boolean: ['json'], string: ['note', 'base-url'] },
+  async run({ positional, flags }, io) {
+    const [id, ...rest] = positional;
+    if (!id || rest.length) throw usage('Name the factory to publish: factoryhub publish <id>   ("factoryhub push" prints the id.)');
+    const { hub } = await connect(flags, io, { needToken: true });
+    let answer;
+    try {
+      answer = await hub.publish(id, { note: flags.note || '' });
+    } catch (error) {
+      const lines = refusalLines(error.details);
+      if (lines.length || error.status === 409 || error.status === 422) error.message = [`Not published: ${error.message}`, ...lines].join('\n');
+      throw error;
+    }
+    if (flags.json) { json(io, answer); return 0; }
+    const s = styles(io);
+    // The hub says what state the factory is in; nothing is assumed here.
+    const factory = answer.factory || {};
+    const url = factory.url || hub.sourceUrl(factory.id || id);
+    if (factory.visibility === 'public') {
+      out(io, `${answer.already ? s.dim('Already published:') : s.green('Published:')} ${s.bold(factory.id || id)} is live at ${url}`);
+    } else {
+      out(io, `${s.bold(factory.id || id)}: ${factory.visibility || 'unknown state'}. ${answer.message || ''}`.trim());
+    }
+    if (factory.safety) out(io, s.dim(`Safety check: ${typeof factory.safety === 'string' ? factory.safety : factory.safety.status || 'unknown'}`));
+    return 0;
+  },
+};