factoryhub 0.1.0 → 0.1.1

package/packages/mcp/src/server.mjs

@@ -2,6 +2,7 @@
 // factories from any MCP client. It runs locally over stdio. Runs use the
 // model key in this process's environment, never one of ours, and stop at
 // every human decision: the client must ask the person and call resume_run.
+import * as fsp from 'node:fs/promises';
 import { readFile, writeFile, mkdir, rm } from 'node:fs/promises';
 import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve, delimiter } from 'node:path';
@@ -43,19 +44,52 @@ function failure(error) {
 
 /**
  * Creates the server. Options exist for tests and embedding:
- * env (keys, FACTORYHUB_FACTORIES, FACTORYHUB_RUNS_DIR), fetchImpl, factoryDirs, runsDir.
+ * env (keys, FACTORYHUB_FACTORIES, FACTORYHUB_RUNS_DIR), fetchImpl, factoryDirs, runsDir,
+ * fs (the file system calls local factories are read with).
  */
-export function createServer({ env = process.env, fetchImpl = fetch, factoryDirs, runsDir } = {}) {
+export function createServer({ env = process.env, fetchImpl = fetch, factoryDirs, runsDir, fs = fsp } = {}) {
   const dirs = factoryDirs || [HOUSE_FACTORIES, ...String(env.FACTORYHUB_FACTORIES || '').split(delimiter).filter(Boolean).map((dir) => resolve(dir))];
   const runs = new Map();
   const runFolder = runsDir || env.FACTORYHUB_RUNS_DIR || join(homedir(), '.factoryhub', 'runs');
 
   async function localIds() {
     const seen = new Map();
-    for (const dir of dirs) for (const id of await listFactoryDirs(dir)) if (!seen.has(id)) seen.set(id, join(dir, id));
+    const lists = await Promise.all(dirs.map((dir) => listFactoryDirs(dir)));
+    dirs.forEach((dir, index) => { for (const id of lists[index]) if (!seen.has(id)) seen.set(id, join(dir, id)); });
     return seen;
   }
 
+  // The folder of a local factory id, as localIds() would map it: the first
+  // factory directory with an entry of exactly that name that is a folder
+  // holding a factory.yaml. Only that entry is checked, not every folder, and
+  // an id that is not an entry name (such as "../x") is never joined to a path.
+  async function localLocation(id) {
+    for (const dir of dirs) {
+      const names = await fs.readdir(dir).catch(() => []);
+      if (!names.includes(id)) continue;
+      const location = join(dir, id);
+      const folder = await fs.lstat(location).then((stats) => stats.isDirectory(), () => false);
+      if (folder && existsSync(join(location, 'factory.yaml'))) return location;
+    }
+    return null;
+  }
+
+  // Local factories are read and summarized again only when one of their
+  // files changed. A folder's signature is the time and size of every file
+  // readFolder would read, found by the same walk with a stat in place of
+  // each read; an edit, an added or a removed file changes it.
+  const cache = new Map();
+  const statFs = { readdir: fs.readdir, readFile: async (path) => { const stats = await fs.stat(path); return `${stats.mtimeMs}:${stats.size}`; } };
+  async function readLocal(id, location) {
+    const signature = JSON.stringify((await readFolder(location, { fs: statFs })).files);
+    const cached = cache.get(location);
+    if (cached?.signature === signature) return cached;
+    const { files, skipped } = await readFolder(location, { fs });
+    const entry = { signature, files, skipped, summary: await summarize(files, { id }) };
+    cache.set(location, entry);
+    return entry;
+  }
+
   async function resolveFactory({ id, path, source = 'local' }) {
     if (path) {
       const read = await readFactory(path, { fetchImpl });
@@ -66,10 +100,10 @@ export function createServer({ env = process.env, fetchImpl = fetch, factoryDirs
       const got = await hubClient({ env, fetchImpl }).get(id);
       return { id, files: got.files, location: got.source, leftOut: got.leftOut };
     }
-    const location = (await localIds()).get(id);
+    const location = await localLocation(id);
     if (!location) throw new Error(`No local factory "${id}". Call list_factories to see the ids, or pass source "hub" or a path.`);
-    const { files, skipped } = await readFolder(location);
-    return { id, files, location, leftOut: skipped };
+    const { files, skipped, summary } = await readLocal(id, location);
+    return { id, files, location, leftOut: skipped, summary };
   }
 
   async function saveRun(state) {
@@ -131,11 +165,8 @@ export function createServer({ env = process.env, fetchImpl = fetch, factoryDirs
       let entries;
       if (source === 'hub') entries = (await hubClient({ env, fetchImpl }).search(query || '')).map((entry) => ({ id: entry.id, title: entry.title, description: entry.description, version: entry.version, tags: entry.tags || [], runnable: entry.runnable, source: 'hub' }));
       else {
-        entries = [];
-        for (const [id, location] of await localIds()) {
-          const summary = await summarize((await readFolder(location)).files, { id });
-          if (matches(summary, query)) entries.push({ id, title: summary.title, description: summary.description, version: summary.version, tags: summary.tags, runnable: summary.runnable, inputs: summary.inputs.map((input) => input.key), steps: summary.steps.length, source: 'local', path: location });
-        }
+        const found = await Promise.all([...await localIds()].map(async ([id, location]) => ({ id, location, summary: (await readLocal(id, location)).summary })));
+        entries = found.filter(({ summary }) => matches(summary, query)).map(({ id, location, summary }) => ({ id, title: summary.title, description: summary.description, version: summary.version, tags: summary.tags, runnable: summary.runnable, inputs: summary.inputs.map((input) => input.key), steps: summary.steps.length, source: 'local', path: location }));
       }
       return result({ factories: entries }, `${entries.length} ${entries.length === 1 ? 'factory' : 'factories'}.`);
     } catch (error) { return failure(error); }
@@ -149,7 +180,7 @@ export function createServer({ env = process.env, fetchImpl = fetch, factoryDirs
   }, async (args) => {
     try {
       const found = await resolveFactory(args);
-      const summary = await summarize(found.files, { id: found.id });
+      const summary = found.summary || await summarize(found.files, { id: found.id });
       return result({ summary, files: canonicalFiles(found.files), location: found.location, left_out: found.leftOut }, `${summary.title} v${summary.version}.`);
     } catch (error) { return failure(error); }
   });
@@ -245,11 +276,10 @@ export function createServer({ env = process.env, fetchImpl = fetch, factoryDirs
 
   server.registerResource('factory', new ResourceTemplate('factoryhub://factories/{id}', {
     list: async () => {
-      const resources = [];
-      for (const [id, location] of await localIds()) {
-        const summary = await summarize((await readFolder(location)).files, { id });
-        resources.push({ uri: `factoryhub://factories/${id}`, name: id, title: summary.title, description: summary.description, mimeType: 'application/json' });
-      }
+      const resources = await Promise.all([...await localIds()].map(async ([id, location]) => {
+        const { summary } = await readLocal(id, location);
+        return { uri: `factoryhub://factories/${id}`, name: id, title: summary.title, description: summary.description, mimeType: 'application/json' };
+      }));
       return { resources };
     },
   }), { title: 'Factory bundle', description: 'A local factory as a transfer bundle: every file with its SHA-256.', mimeType: 'application/json' }, async (uri, { id }) => {

package/packages/sdk/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@factoryhub/sdk",
+  "version": "0.1.1",
+  "description": "The factoryhub SDK for JavaScript: log in, push, pull, publish and run factories on factoryhub, and verify run receipts. Published as the main export of the factoryhub package.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "private": true,
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mindburn-Labs/factoryhub.git",
+    "directory": "packages/sdk"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.mjs"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\""
+  }
+}

package/packages/sdk/src/index.d.ts

@@ -0,0 +1,163 @@
+// Types for the factoryhub SDK (packages/sdk/src/index.mjs).
+
+export type Scope = 'factories:read' | 'factories:write' | 'runs:start' | 'runs:read' | 'factories:publish' | 'runs:decide';
+export const SCOPES: Scope[];
+export const OPT_IN_SCOPES: Scope[];
+export const DEFAULT_HUB: string;
+
+export interface ConnectionOptions {
+  /** The hub address. Default: FACTORYHUB_BASE_URL or https://factory.mindburn.org. */
+  baseUrl?: string;
+  /** A personal access token. Default: FACTORYHUB_TOKEN, then the saved login. */
+  token?: string;
+  /** The private-preview key. Default: FACTORYHUB_ACCESS_KEY. */
+  accessKey?: string;
+  fetch?: typeof fetch;
+  env?: Record<string, string | undefined>;
+}
+
+export class HubError extends Error {
+  status?: number;
+  code: string | null;
+  preview: boolean;
+  scope: string[] | null;
+  retryAfter: number | null;
+  details: Record<string, unknown> | null;
+}
+
+export interface Account { id: string; handle: string; name: string | null; email?: string }
+export interface TokenInfo { id: string; name: string; prefix: string; scopes: Scope[]; expires: string | null }
+export interface DeviceCode { userCode: string; verificationUri: string; verificationUriComplete: string | null; expiresIn: number; scope: string | null }
+
+export interface LoginOptions extends ConnectionOptions {
+  scopes?: Scope[];
+  name?: string;
+  days?: number;
+  /** Show the person the code and the page. Required for a device login. */
+  onCode?: (code: DeviceCode) => void | Promise<void>;
+  /** Store the token where the CLI finds it too. Default true. */
+  save?: boolean;
+  sleep?: (ms: number) => Promise<void>;
+}
+export interface LoginResult {
+  account: Account;
+  token: TokenInfo;
+  saved: string | null;
+  /** What happened to the token saved before: a device-login token is revoked, a passed-in one is kept. */
+  replaced: 'revoked' | 'not_revoked' | 'kept' | null;
+}
+
+export interface PushResult {
+  factory: { id: string; url: string; title: string; visibility: string; mine: boolean; sha256: string };
+  parent: string | null;
+  unchanged: boolean;
+}
+export interface PullResult {
+  id: string;
+  files: Record<string, string>;
+  sha256: string;
+  source: string;
+  leftOut: string[];
+  /** True when `partial` let through a bundle that could not be checked whole. */
+  partial: boolean;
+  /** Why the bundle could not be checked whole, when `partial`. */
+  unchecked: string[];
+  dir: string | null;
+  /** Files an earlier pull wrote that `force` removed. */
+  removed: string[];
+}
+export interface PullOptions {
+  dir?: string;
+  /** Replace an earlier pull: only files that pull recorded are removed. */
+  force?: boolean;
+  /** Accept a bundle that cannot be checked whole (no bundle hash, or files left out). */
+  partial?: boolean;
+}
+export interface PublishResult { factory: { id: string; visibility: string }; already: boolean; message: string }
+export interface RunSummary { id: string; title: string; factoryId: string; started: string; status: string; url: string }
+
+export interface RunEvent { i: number; at: string; type: string; step: string | null; status?: string; error?: string }
+export interface Waiting {
+  approval_id: string;
+  step: string;
+  title: string;
+  ask: string;
+  artifact: string;
+  artifact_sha256: string;
+  revisionsLeft: number;
+  text: string;
+  complete: boolean;
+  totalChars: number;
+}
+export interface Decision { decision: 'approve' | 'revise' | 'reject'; note?: string }
+
+export interface Verification {
+  /** The signature is valid, the deliverable (when given) matches, and the issuer is the hub (when checked against a hub). */
+  valid: boolean;
+  signed: boolean;
+  signatureValid: boolean;
+  deliverableMatches: boolean | null;
+  keyId: string | null;
+  problems: string[];
+  /** "pinned": a production key pinned in this package; "published": keys the hub at `host` publishes; "given": the keys passed in. */
+  trust: 'pinned' | 'published' | 'given' | null;
+  host?: string;
+  issuer?: string | null;
+  issuerMatches?: boolean;
+}
+export interface HostedVerification extends Omit<Verification, 'valid'> {
+  /** The one answer to act on: signature, deliverable and issuer all check out. */
+  verified: boolean;
+  host: string;
+  issuer: string | null;
+  issuerMatches: boolean;
+}
+export interface RunResult {
+  text: string;
+  receipt: Record<string, unknown> | null;
+  verification: HostedVerification;
+  review: string;
+  sha256: string | null;
+}
+export type RunOutcome =
+  | { status: 'done'; run: string; url: string; result: RunResult | null }
+  | { status: 'waiting'; run: string; url: string; waiting: Waiting }
+  | { status: string; run: string; url: string; error: string | null; stopped: { step: string; title: string; note: string } | null };
+
+export interface RunOptions extends ConnectionOptions {
+  inputs?: Record<string, string>;
+  onEvent?: (event: RunEvent) => void | Promise<void>;
+  /** Return the person's own decision, or null to leave the run waiting. Needs runs:decide. An approval of a step whose text was not sent whole (`complete: false`) is refused. */
+  onDecision?: (waiting: Waiting) => Decision | null | Promise<Decision | null>;
+  idempotencyKey?: string;
+  every?: number;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export interface ReceiptKey { key_id: string; public_key: string; alg?: string }
+
+export class Hub {
+  constructor(options?: ConnectionOptions);
+  readonly baseUrl: string;
+  login(options?: LoginOptions & { token?: string }): Promise<LoginResult>;
+  logout(): Promise<boolean>;
+  whoami(): Promise<{ account: Account; token: TokenInfo }>;
+  push(source: string | Record<string, string>, options?: { parent?: string }): Promise<PushResult>;
+  pull(id: string, options?: PullOptions): Promise<PullResult>;
+  publish(id: string, options?: { note?: string }): Promise<PublishResult>;
+  runs(options?: { limit?: number }): Promise<RunSummary[]>;
+  run(id: string, options?: RunOptions): Promise<RunOutcome>;
+  keys(): Promise<ReceiptKey[]>;
+}
+
+export function login(options?: LoginOptions & { token?: string }): Promise<LoginResult>;
+export function logout(options?: ConnectionOptions): Promise<boolean>;
+export function whoami(options?: ConnectionOptions): Promise<{ account: Account; token: TokenInfo }>;
+export function push(source: string | Record<string, string>, options?: ConnectionOptions & { parent?: string }): Promise<PushResult>;
+export function pull(id: string, options?: ConnectionOptions & PullOptions): Promise<PullResult>;
+export function publish(id: string, options?: ConnectionOptions & { note?: string }): Promise<PublishResult>;
+export function run(id: string, options?: RunOptions): Promise<RunOutcome>;
+export function runs(options?: ConnectionOptions & { limit?: number }): Promise<RunSummary[]>;
+export function verifyReceipt(receipt: Record<string, unknown> | string, options?: ConnectionOptions & { keys?: ReceiptKey[]; deliverable?: string }): Promise<Verification>;
+export function saveResult(result: RunResult, file: string): Promise<{ file: string; receipt: string | null }>;
+export function credentialsPath(env?: Record<string, string | undefined>): string;

package/packages/sdk/src/index.mjs

@@ -0,0 +1,266 @@
+// The factoryhub SDK for JavaScript: `import { login, push, run } from 'factoryhub'`.
+//
+// Every function takes the same connection options:
+//   baseUrl    the hub address (default FACTORYHUB_BASE_URL or https://factory.mindburn.org)
+//   token      a personal access token (default FACTORYHUB_TOKEN, then the login
+//              `factoryhub login` or login() saved for that hub)
+//   accessKey  the preview key (default FACTORYHUB_ACCESS_KEY)
+//   fetch      a fetch implementation (default the global one)
+//   env        the environment to read those defaults from (default process.env)
+//
+// The SDK shares its token store with the CLI, so a login in either works for
+// both. A token is sent only in the Authorization header, only over https or
+// to this machine, and is never returned or logged; FACTORYHUB_TOKEN goes only
+// to the production hub or the one FACTORYHUB_BASE_URL names. Redirects are
+// followed only within the hub. Nothing here decides a step of a run for the
+// person: run() asks the caller's onDecision, and refuses an approval of a
+// step whose text was not sent whole.
+//
+// Receipts from https://factory.mindburn.org verify against the production
+// keys pinned in this package; from any other hub, against the keys that hub
+// publishes. The receipt's issuer must be the hub either way.
+import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { resolve, dirname } from 'node:path';
+import { hubClient, deviceLogin, checkedBase, HubError, DEFAULT_HUB, SCOPES, OPT_IN_SCOPES, TOKEN_PATTERN } from '../../engine/lib/hub.mjs';
+import { resolveToken, saveCredential, storedCredential, deleteCredential, credentialsPath } from '../../engine/lib/credentials.mjs';
+import { followRun, runResult, newIdempotencyKey, checkHostedReceipt, FINISHED } from '../../engine/lib/hosted.mjs';
+import { readFolder, writePulled } from '../../engine/lib/node.mjs';
+import { parseBundle, withForeman, verifyReceipt as verifyWithKeys } from '../../engine/src/factory-engine.mjs';
+
+export { HubError, DEFAULT_HUB, SCOPES, OPT_IN_SCOPES };
+
+// https, or http to this machine only: no token or key is sent in the clear.
+function baseOf(options) {
+  const env = options.env || process.env;
+  return checkedBase(options.baseUrl || env.FACTORYHUB_BASE_URL || DEFAULT_HUB);
+}
+
+/**
+ * A connection to one factoryhub site. The module functions below make one
+ * for each call; keep one with `new Hub(options)` to reuse it.
+ */
+export class Hub {
+  constructor(options = {}) {
+    this.options = { ...options };
+    this.env = options.env || process.env;
+    this.baseUrl = baseOf(options);
+  }
+
+  async #client({ needToken = false } = {}) {
+    let token = this.options.token || null;
+    let source = token ? 'option' : null;
+    let scopes = null;
+    if (!token) {
+      const found = await resolveToken(this.baseUrl, this.env);
+      if (found.expired && needToken) throw new HubError(`The saved login for ${this.baseUrl} expired on ${String(found.record.expires).slice(0, 10)}. Log in again with login().`, { code: 'unauthorized', status: 401 });
+      token = found.token;
+      source = found.source;
+      scopes = found.record?.scopes || null;
+      if (found.warning && token) process.emitWarning(found.warning, { code: 'FACTORYHUB_TOKEN_NOT_SENT' });
+      if (found.warning && needToken && !token) throw new HubError(`Not logged in to ${this.baseUrl}. ${found.warning}`, { code: 'unauthorized', status: 401 });
+    }
+    if (needToken && !token) throw new HubError(`Not logged in to ${this.baseUrl}: pass { token }, set FACTORYHUB_TOKEN, or call login() first.`, { code: 'unauthorized', status: 401 });
+    return hubClient({ baseUrl: this.baseUrl, accessKey: this.options.accessKey, env: this.env, fetchImpl: this.options.fetch || fetch, token, tokenSource: source === 'option' ? null : source, tokenScopes: scopes });
+  }
+
+  /**
+   * Logs in and stores the token where the CLI finds it too.
+   * With `token`, checks that token and stores it. Without, runs a device
+   * login: `onCode({ userCode, verificationUri, verificationUriComplete, expiresIn })`
+   * must show the person the code and the page; the promise resolves once
+   * they approve. Returns { account, token, saved, replaced } without the
+   * secret. A token an earlier device login saved is revoked when this one
+   * replaces it; a token that was passed in is never revoked.
+   */
+  async login({ token, scopes, name, days, onCode, save = true, sleep } = {}) {
+    let secret = token;
+    const origin = secret === undefined ? 'device' : 'pasted';
+    if (secret === undefined) {
+      if (typeof onCode !== 'function') throw new HubError('A device login needs onCode, to show the person the code and the page.', { code: 'usage' });
+      const unknown = (scopes || []).filter((scope) => !SCOPES.includes(scope));
+      if (unknown.length) throw new HubError(`Unknown scope ${unknown.join(', ')}. Choose from: ${SCOPES.join(', ')}.`, { code: 'usage' });
+      const anonymous = hubClient({ baseUrl: this.baseUrl, accessKey: this.options.accessKey, env: this.env, fetchImpl: this.options.fetch || fetch });
+      const answer = await deviceLogin(anonymous, { name: name || `factoryhub SDK on ${hostname() || 'this computer'}`.slice(0, 60), scopes, days, onCode, sleep });
+      secret = answer.access_token;
+    } else if (!TOKEN_PATTERN.test(String(secret))) {
+      throw new HubError('That is not a factoryhub personal access token: they start with fhpat_ and are 49 characters long.', { code: 'usage' });
+    }
+    const me = await hubClient({ baseUrl: this.baseUrl, accessKey: this.options.accessKey, env: this.env, fetchImpl: this.options.fetch || fetch, token: secret }).me();
+    let saved = null;
+    let replaced = null;
+    if (save) {
+      const previous = await storedCredential(this.baseUrl, this.env);
+      saved = await saveCredential(this.baseUrl, { token: secret, 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 }, this.env);
+      if (previous?.token && previous.token !== secret) {
+        if (previous.origin !== 'device') replaced = 'kept';
+        else {
+          replaced = await hubClient({ baseUrl: this.baseUrl, accessKey: this.options.accessKey, env: this.env, fetchImpl: this.options.fetch || fetch, token: previous.token }).revoke().then(() => 'revoked', () => 'not_revoked');
+        }
+      }
+    }
+    this.options.token = secret;
+    return { account: me.account, token: me.token, saved, replaced };
+  }
+
+  /** Revokes the stored token on the hub, then forgets it. True when there was one. */
+  async logout() {
+    const stored = await storedCredential(this.baseUrl, this.env);
+    if (!stored) return false;
+    try {
+      await hubClient({ baseUrl: this.baseUrl, accessKey: this.options.accessKey, env: this.env, fetchImpl: this.options.fetch || fetch, token: stored.token, tokenSource: 'file' }).revoke();
+    } catch (error) {
+      if (error.status !== 401) throw error;
+    }
+    await deleteCredential(this.baseUrl, this.env);
+    return true;
+  }
+
+  /** The account and token the token acts for: { account, token }. */
+  async whoami() {
+    return (await this.#client({ needToken: true })).me();
+  }
+
+  /**
+   * Saves a factory to the account, privately. `source` is a folder path or a
+   * { path: content } map. The factory is checked here first, as the site
+   * checks it. Returns { factory: { id, url, title, visibility, sha256 }, parent, unchanged }.
+   */
+  async push(source, { parent } = {}) {
+    const files = typeof source === 'string' ? (await readFolder(resolve(source))).files : source;
+    if (!files || typeof files !== 'object') throw new HubError('push takes a folder path or a { path: content } map of factory files.', { code: 'usage' });
+    const parsed = parseBundle(withForeman(files));
+    if (!parsed.ok) throw new HubError(`This is not a valid factory yet:\n${parsed.errors.map((error) => `  - ${error}`).join('\n')}`, { code: 'invalid_factory' });
+    return (await this.#client({ needToken: true })).push(files, { parent });
+  }
+
+  /**
+   * Downloads a factory the caller can open, checking every file's SHA-256
+   * and the files together against the bundle hash in the hub's answer:
+   * integrity against that answer, not a signature. A bundle that cannot be
+   * checked whole is refused unless `partial`. With `dir`, also writes the
+   * files into that folder, never through a symbolic link (refusing a
+   * non-empty one unless `force`; `force` removes only files an earlier pull
+   * wrote there). Returns { id, files, sha256, source, leftOut, partial, unchecked, dir, removed }.
+   */
+  async pull(id, { dir, force = false, partial = false } = {}) {
+    const target = dir ? resolve(dir) : null;
+    if (target && !force && existsSync(target) && (await readdir(target)).length) throw new HubError(`${target} is not empty. Pass { force: true } to write into it.`, { code: 'usage' });
+    const factory = await (await this.#client()).pull(id, { partial });
+    const { removed } = target ? await writePulled(target, factory.files, { replace: force, record: { id: factory.id, sha256: factory.sha256, source: factory.source, partial: factory.partial } }) : { removed: [] };
+    return { ...factory, dir: target, removed };
+  }
+
+  /** Publishes one of the account's factories: it is public at once. Returns { factory, already, message }. */
+  async publish(id, { note = '' } = {}) {
+    return (await this.#client({ needToken: true })).publish(id, { note });
+  }
+
+  /** The account's recent hosted runs. */
+  async runs({ limit } = {}) {
+    return (await this.#client({ needToken: true })).runs({ limit });
+  }
+
+  /**
+   * Runs a factory on the hub and follows it.
+   *   inputs       { key: value }
+   *   onEvent      (event) => void, for progress
+   *   onDecision   async (waiting) => { decision: 'approve' | 'revise' | 'reject', note? } | null
+   *                Called where the run waits for the person, with the exact
+   *                text. Return the person's own decision, or null to leave
+   *                the run waiting. Needs a token with the opt-in runs:decide.
+   *                When the hub sent only part of the text (`complete: false`),
+   *                an approval is refused: decide on the run page.
+   * Resolves to { status, run, url, result?, waiting? }: status 'done' with
+   * result { text, receipt, verification, review }, 'waiting' with the step,
+   * or 'failed' / 'stopped'.
+   */
+  async run(id, { inputs = {}, onEvent, onDecision, idempotencyKey = newIdempotencyKey(), every = 2000, sleep } = {}) {
+    const hub = await this.#client({ needToken: true });
+    const started = await hub.startRun(id, inputs, { idempotencyKey });
+    const decided = new Set();
+    for (;;) {
+      const view = await followRun(hub, started.id, { onEvent: onEvent ? (event) => onEvent(event) : undefined, every, sleep });
+      const waiting = view.waiting;
+      const key = waiting ? `${waiting.approval_id}:${waiting.artifact_sha256}` : null;
+      if (key && decided.has(key)) { await (sleep || ((ms) => new Promise((done) => setTimeout(done, ms))))(every); continue; }
+      if (waiting) {
+        const choice = onDecision ? await onDecision(waiting) : null;
+        if (!choice) return { status: 'waiting', run: started.id, url: view.url, waiting };
+        if (choice.decision === 'approve' && waiting.complete !== true) {
+          throw new HubError(`Not approved: the hub sent only part of "${waiting.title}" (${waiting.totalChars} characters in all), so it cannot be approved from here. Read and decide on the run page: ${view.url}`, { code: 'incomplete' });
+        }
+        await hub.decide(view.id, { approvalId: waiting.approval_id, seenSha256: waiting.artifact_sha256, decision: choice.decision, note: choice.note || '' });
+        decided.add(key);
+        continue;
+      }
+      if (view.status === 'done') return { status: 'done', run: started.id, url: view.url, result: await runResult(hub, started.id) };
+      return { status: FINISHED.has(view.status) ? view.status : 'unknown', run: started.id, url: view.url, error: view.error || null, stopped: view.stopped || null };
+    }
+  }
+
+  /** The hub's published receipt keys. */
+  async keys() {
+    return (await this.#client()).keys();
+  }
+}
+
+/**
+ * Checks a run receipt's Ed25519 signature over its canonical JSON and, with
+ * `deliverable`, that the text matches the hash it records. With `keys`, it
+ * runs offline against exactly those keys (trust "given"). Without, it checks
+ * the receipt as a receipt from the hub at `baseUrl`: on
+ * https://factory.mindburn.org against the production keys pinned in this
+ * package (trust "pinned"), elsewhere against the keys that hub publishes
+ * (trust "published"), and its issuer against the hub's host. `receipt` is an
+ * object, a JSON string or a path to a .receipt.json file.
+ * Returns { valid, signed, signatureValid, deliverableMatches, keyId, problems, trust, host?, issuerMatches? }.
+ */
+export async function verifyReceipt(receipt, { keys, deliverable, ...options } = {}) {
+  let value = receipt;
+  if (typeof value === 'string') value = value.trimStart().startsWith('{') ? JSON.parse(value) : JSON.parse(await readFile(value, 'utf8'));
+  if (keys) {
+    const result = await verifyWithKeys(value, keys, deliverable);
+    return { valid: result.signatureValid && result.deliverableMatches !== false, ...result, trust: 'given' };
+  }
+  const hub = new Hub(options);
+  const result = await checkHostedReceipt(value, { base: hub.baseUrl, keys: await hub.keys(), text: deliverable });
+  return { valid: result.verified, ...result };
+}
+
+/** Writes a finished run's result and receipt next to each other. */
+export async function saveResult(result, file) {
+  const path = resolve(file);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, result.text);
+  const receipt = `${path.replace(/\.md$/, '')}.receipt.json`;
+  if (result.receipt) await writeFile(receipt, `${JSON.stringify(result.receipt, null, 2)}\n`);
+  return { file: path, receipt: result.receipt ? receipt : null };
+}
+
+const one = (method) => (first, second) => {
+  const takesTarget = ['push', 'pull', 'publish', 'run'].includes(method);
+  const options = (takesTarget ? second : first) || {};
+  const hub = new Hub(options);
+  return takesTarget ? hub[method](first, options) : hub[method](options);
+};
+
+/** Logs in; see Hub#login. */
+export const login = one('login');
+/** Revokes and forgets the stored token; see Hub#logout. */
+export const logout = one('logout');
+/** Who the token acts for; see Hub#whoami. */
+export const whoami = one('whoami');
+/** Saves a folder or files privately; see Hub#push. */
+export const push = one('push');
+/** Downloads and checks a factory; see Hub#pull. */
+export const pull = one('pull');
+/** Publishes a factory; see Hub#publish. */
+export const publish = one('publish');
+/** Runs a factory on the hub; see Hub#run. */
+export const run = one('run');
+/** The account's runs; see Hub#runs. */
+export const runs = one('runs');
+
+export { credentialsPath };

package/spec/README.md

@@ -5,9 +5,11 @@
 | [`factory-format.md`](factory-format.md) | the specification, v1alpha1 |
 | [`schema/factory.schema.json`](schema/factory.schema.json) | JSON Schema (2020-12) for `factory.yaml` |
 | [`schema/flow.schema.json`](schema/flow.schema.json) | JSON Schema (2020-12) for `flow.yaml` |
+| [`schema/factory.yaml.json`](schema/factory.yaml.json) | JSON Schema (draft-07) for a whole factory in one file, the [single-file form](factory-format.md#13-the-single-file-form) |
 | [`skill-export.md`](skill-export.md) | how a factory becomes an Agent Skill folder |
 | [`skill-export/`](skill-export) | the expected `SKILL.md` of every house factory |
-| [`fixtures/`](fixtures) | good, bad, semantic and lenient factories that test the schemas against the engine |
+| [`fixtures/`](fixtures) | good, bad, semantic, unimplemented and lenient factories that test the schemas against the engine |
+| [`conformance/`](conformance) | what the reference engine gives for every fixture, house factory and edge case, for other implementations to match |
 | [`test/`](test) | those tests |
 | [`rfcs/`](rfcs) | proposals to change the format |
 
@@ -24,6 +26,10 @@ type:
 # yaml-language-server: $schema=https://raw.githubusercontent.com/Mindburn-Labs/factoryhub/main/spec/schema/flow.schema.json
 ```
 
+A single-file factory names `schema/factory.yaml.json` the same way. Setup
+for VS Code, Neovim, Helix, Zed and JetBrains IDEs is in
+[docs/editor-setup.md](../docs/editor-setup.md).
+
 The schemas check one file at a time. Rules that span steps and files, such as
 an agent file existing for every step, are in
 [section 6 of the spec](factory-format.md#6-validity-and-runnability);