@thinair/factory 0.0.0-stage → 0.1.124

package/cli/load.ts

@@ -0,0 +1,463 @@
+#!/usr/bin/env bun
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { access, mkdir, readdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Context, Effect, Layer, Result, Schema } from "effect";
+import { LOAD_VERSION, LoadJson, LoadPost, type Finding, type Load } from "../domain/load";
+import { appShapeProblems, AUTHORING_MODULES, folderKey, IGNORED_FOLDERS, isLoadedPath, memberFiles } from "../domain/system-elements/app-shape";
+import { FrameworkVersion, holesOf, type Node, type Program } from "../domain/system-elements/program";
+import { EvaluateOutputJson, type EvaluateInput } from "./evaluate";
+import { templateFiles } from "./template";
+
+/*
+ * The factory loader: one program, two hosts. The factory VM runs it on the
+ * tree the plane fetched (live); an agent runs `dev` in its working copy
+ * (preview). It runs under bun.
+ *
+ *   init [dir] [--framework <spec>]   write the blank factory template
+ *   load [tree] [--framework <x.y.z>] load once; print the Load as JSON
+ *   dev --factory <id> [--tree <dir>] load on every save and post each load
+ *
+ * A load: snapshot → shape → the factory-code lint → bundle ∥ type check →
+ * evaluate in a subprocess with a runaway deadline → value checks → encode.
+ * Every finding holds the revision and is pinned to a node, a file and a
+ * line where the loader can tell. The same files under the same framework
+ * give the same key, and a key loaded before comes from the cache.
+ *
+ * A load names the framework it was made by: this package's version, or the
+ * version `--framework` gives, for a host that carries this framework under
+ * a release's number (a Thinair release's factory engine).
+ *
+ * Exit codes: 0 ready, 1 held, 2 the loader itself failed.
+ */
+
+export class FactoryLoadFailed extends Schema.TaggedError<FactoryLoadFailed>()("FactoryLoadFailed", { message: Schema.String }) {}
+
+/** Where each load goes: `factory.load.post`, as whoever runs the loader. */
+export class LoadPosts extends Context.Service<LoadPosts, {
+  readonly post: (post: LoadPost) => Effect.Effect<PostedLoad, FactoryLoadFailed>;
+}>()("@thinair/factory/cli/load/LoadPosts") {}
+
+/** What the plane answered a post: the ref's row as it keeps it now. */
+export type PostedLoad = Readonly<{ state: "ready" | "held"; revision: string | null }>;
+
+const ToolEnvelope = Schema.Struct({
+  data: Schema.optionalKey(Schema.Struct({ success: Schema.Boolean, output: Schema.optionalKey(Schema.Struct({
+    load: Schema.Struct({ state: Schema.Literals(["ready", "held"]), revision: Schema.NullOr(Schema.String) }),
+  })) })),
+  error: Schema.optionalKey(Schema.Struct({ message: Schema.String })),
+});
+
+/**
+ * Each post through `thinair tool call factory.load.post`, as the caller the `thinair` CLI speaks for: in a Thinair
+ * Terminal, its person (or their agent) there. The loader holds no credential of its own.
+ */
+export const LoadPostsThroughThinair = Layer.succeed(LoadPosts, {
+  post: (post) => Effect.gen(function* () {
+    const input = JSON.stringify(Schema.encodeSync(LoadPostJson)(post));
+    const ran = yield* runCommand("thinair", ["--json", "tool", "call", "factory.load.post", "--input-stdin", "--timeout", String(POST_GUARD_MILLIS)], { cwd: process.cwd(), guardMillis: POST_GUARD_MILLIS + 5_000, input });
+    if (ran.timedOut) return yield* new FactoryLoadFailed({ message: `factory.load.post ran past its runaway guard of ${POST_GUARD_MILLIS / 1000} s.` });
+    const envelope = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(ToolEnvelope))(ran.stdout.trim()).pipe(
+      Effect.mapError(() => new FactoryLoadFailed({ message: `factory.load.post did not answer (${ran.code ?? "stopped"}): ${`${ran.stderr}${ran.stdout}`.trim().slice(-500)}` })),
+    );
+    if (envelope.error !== undefined || envelope.data?.success !== true || envelope.data.output === undefined)
+      return yield* new FactoryLoadFailed({ message: `factory.load.post refused the load: ${envelope.error?.message ?? "no answer"}` });
+    return envelope.data.output.load;
+  }),
+});
+
+/** Runaway guards, never speed checks. */
+const EVALUATE_GUARD_MILLIS = 60_000;
+const TYPE_GUARD_MILLIS = 300_000;
+const LINT_GUARD_MILLIS = 120_000;
+const POLL_MILLIS = 250;
+const POST_GUARD_MILLIS = 60_000;
+const SETTLE_MILLIS = 150;
+
+const LoadPostJson = Schema.toCodecJson(LoadPost);
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const requireHere = createRequire(import.meta.url);
+const sha256 = (text: string | Uint8Array) => createHash("sha256").update(text).digest("hex");
+const failed = (message: string) => () => new FactoryLoadFailed({ message });
+
+const readJson = (file: string) => Effect.tryPromise({ try: async () => JSON.parse(await readFile(file, "utf8")) as Readonly<Record<string, unknown>>, catch: failed(`Could not read ${file}.`) });
+const exists = (file: string) => Effect.promise(() => access(file).then(() => true, () => false));
+
+/** The framework's own version, and the effect it is built with: what init pins. */
+const versions = Effect.fn("factory.load.versions")(function* () {
+  const own = yield* readJson(path.join(here, "..", "package.json"));
+  const effect = yield* readJson(requireHere.resolve("effect/package.json"));
+  return { framework: String(own["version"]), effect: String(effect["version"]) };
+});
+
+type Ran = Readonly<{ code: number | null; stdout: string; stderr: string; timedOut: boolean }>;
+
+/** Run a command to its end, or stop it (by its own PID) at its runaway guard. */
+const runCommand = (command: string, args: ReadonlyArray<string>, options: Readonly<{ cwd: string; guardMillis: number; input?: string }>) =>
+  Effect.callback<Ran, FactoryLoadFailed>((resume) => {
+    const child = spawn(command, [...args], { cwd: options.cwd, env: { ...process.env, NO_COLOR: "1", FORCE_COLOR: "0" }, stdio: [options.input === undefined ? "ignore" : "pipe", "pipe", "pipe"] });
+    if (options.input !== undefined) child.stdin?.end(options.input);
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    child.stdout?.setEncoding("utf8").on("data", (chunk: string) => { stdout += chunk; });
+    child.stderr?.setEncoding("utf8").on("data", (chunk: string) => { stderr += chunk; });
+    const guard = setTimeout(() => { timedOut = true; child.kill("SIGKILL"); }, options.guardMillis);
+    child.on("error", (error) => { clearTimeout(guard); resume(Effect.fail(new FactoryLoadFailed({ message: `${command} did not start: ${error.message}` }))); });
+    child.on("close", (code) => { clearTimeout(guard); resume(Effect.succeed({ code, stdout, stderr, timedOut })); });
+    return Effect.sync(() => {
+      clearTimeout(guard);
+      if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+    });
+  });
+
+const IGNORED = new Set<string>([...IGNORED_FOLDERS, ".git"]);
+
+/** The folder's files, relative and sorted: everything but installed packages and dot entries (except .gitignore). */
+const listTree = (tree: string) => Effect.tryPromise({
+  try: async () => {
+    const found: string[] = [];
+    const pending = [""];
+    while (pending.length > 0) {
+      const folder = pending.pop()!;
+      for (const entry of await readdir(path.join(tree, folder), { withFileTypes: true })) {
+        const relative = folder === "" ? entry.name : `${folder}/${entry.name}`;
+        if (IGNORED.has(entry.name) || !isLoadedPath(relative)) continue;
+        if (entry.isDirectory()) pending.push(relative);
+        else if (entry.isFile()) found.push(relative);
+      }
+    }
+    return found.sort();
+  },
+  catch: failed(`Could not read the factory folder ${tree}.`),
+});
+
+const finding = (step: Finding["step"], message: string, where: Readonly<{ file?: string | null; line?: number | null; node?: Finding["node"] }> = {}): Finding =>
+  ({ step, node: where.node ?? null, file: where.file ?? null, line: where.line ?? null, message });
+
+/** `0.1.12` against `0.1.11-dev.3`: core numbers first, then a release above its prereleases. */
+const compareVersions = (left: string, right: string) => {
+  const parse = (version: string) => {
+    const [core = "", pre = ""] = version.split("-", 2);
+    return { core: core.split(".").map(Number), pre };
+  };
+  const a = parse(left);
+  const b = parse(right);
+  for (let index = 0; index < 3; index += 1) if ((a.core[index] ?? 0) !== (b.core[index] ?? 0)) return (a.core[index] ?? 0) - (b.core[index] ?? 0);
+  if (a.pre === b.pre) return 0;
+  if (a.pre === "") return 1;
+  if (b.pre === "") return -1;
+  return a.pre < b.pre ? -1 : 1;
+};
+
+const OxlintReport = Schema.Struct({
+  diagnostics: Schema.Array(Schema.Struct({
+    message: Schema.String,
+    code: Schema.optionalKey(Schema.String),
+    filename: Schema.String,
+    labels: Schema.optionalKey(Schema.Array(Schema.Struct({ span: Schema.Struct({ line: Schema.optionalKey(Schema.Number) }) }))),
+  })),
+});
+const categoriesOff = Object.fromEntries(["correctness", "suspicious", "pedantic", "style", "nursery", "perf", "restriction"].map((category) => [category, "off"]));
+
+/** The factory-code lint: one oxlint set, whose allowlist is AUTHORING_MODULES. */
+const lint = Effect.fn("factory.load.lint")(function* (tree: string, paths: ReadonlyArray<string>, packages: ReadonlyArray<string>, scratch: string) {
+  const files = paths.filter((file) => file.endsWith(".ts"));
+  if (files.length === 0) return [];
+  const options = { root: tree, modules: [...AUTHORING_MODULES], packages: [...packages], members: [...memberFiles(paths)] };
+  const config = path.join(scratch, "factory-code.json");
+  yield* Effect.tryPromise({
+    try: () => writeFile(config, JSON.stringify({
+      plugins: [],
+      categories: categoriesOff,
+      jsPlugins: [path.join(here, "factory-code-lint.ts")],
+      rules: { "thinair-factory/imports": ["error", options], "thinair-factory/sealed": "error", "thinair-factory/one-default-export": ["error", options] },
+    })),
+    catch: failed("Could not write the lint's settings."),
+  });
+  const oxlint = path.join(path.dirname(requireHere.resolve("oxlint/package.json")), "bin", "oxlint");
+  const ran = yield* runCommand(process.execPath, [oxlint, "--config", config, "--format", "json", "--", ...files], { cwd: tree, guardMillis: LINT_GUARD_MILLIS });
+  if (ran.timedOut || (ran.code !== 0 && ran.code !== 1)) return yield* new FactoryLoadFailed({ message: `oxlint failed (${ran.code ?? "stopped"}): ${ran.stderr.slice(0, 500)}` });
+  const report = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(OxlintReport))(ran.stdout).pipe(Effect.mapError(failed("oxlint answered in a form this loader does not read.")));
+  return report.diagnostics.map((diagnostic) => finding("lint", diagnostic.message, {
+    file: path.relative(tree, path.resolve(tree, diagnostic.filename)).split(path.sep).join("/"),
+    line: diagnostic.labels?.[0]?.span.line ?? null,
+  }));
+});
+
+/** The type check: bun's checker, with the folder's own tsconfig. */
+const typecheck = Effect.fn("factory.load.type")(function* (tree: string) {
+  const ran = yield* runCommand(process.execPath, ["check", "--no-pretty", "-p", tree], { cwd: tree, guardMillis: TYPE_GUARD_MILLIS });
+  if (ran.timedOut) return [finding("type", `The type check ran past its runaway guard of ${TYPE_GUARD_MILLIS / 1000} s and was stopped.`)];
+  if (ran.code !== 0 && ran.code !== 1) return yield* new FactoryLoadFailed({ message: `bun check failed (${ran.code}): ${ran.stderr.slice(0, 500)}` });
+  const found = `${ran.stdout}\n${ran.stderr}`.split("\n").flatMap((line) => {
+    const match = /^(.+?)\((\d+),\d+\): error (TS\d+): (.*)$/u.exec(line.trim());
+    return match === null ? [] : [finding("type", `${match[3]}: ${match[4]}`, {
+      file: path.relative(tree, path.resolve(tree, match[1]!)).split(path.sep).join("/"),
+      line: Number(match[2]),
+    })];
+  });
+  if (ran.code === 1 && found.length === 0) return [finding("type", `The type check failed: ${`${ran.stdout}\n${ran.stderr}`.trim().slice(0, 500)}`)];
+  return found;
+});
+
+type BunBuild = (options: Readonly<{
+  entrypoints: ReadonlyArray<string>; outdir: string; naming: string; target: "bun"; format: "esm"; sourcemap: "inline"; metafile: true; packages: "external"; throw: false;
+}>) => Promise<Readonly<{
+  success: boolean;
+  outputs: ReadonlyArray<Readonly<{ path: string }>>;
+  logs: ReadonlyArray<Readonly<{ message: string; position?: Readonly<{ file: string; line: number }> | null }>>;
+  metafile?: Readonly<{ inputs: Readonly<Record<string, Readonly<{ imports: ReadonlyArray<Readonly<{ path: string }>> }>>> }>;
+}>>;
+
+type Bundled = Readonly<{ bundle: string | null; imports: Readonly<Record<string, ReadonlyArray<string>>>; findings: ReadonlyArray<Finding> }>;
+
+/** The content-keyed bundle of the factory's code, and its import graph inside the folder. */
+const bundle = Effect.fn("factory.load.bundle")(function* (tree: string, key: string, cache: string) {
+  const build = (globalThis as { Bun?: { build: BunBuild } }).Bun?.build;
+  if (build === undefined) return yield* new FactoryLoadFailed({ message: "The factory loader runs under bun: run it with bunx @thinair/factory." });
+  const result = yield* Effect.tryPromise({
+    // Written by the bundler into the folder's own node_modules: its packages resolve from there, and its
+    // source map names the factory's files, so a throw or a made-at line points at the code that made it.
+    try: () => build({
+      entrypoints: [path.join(tree, "factory.ts")], outdir: path.join(cache, "bundles"), naming: `${key}.js`,
+      target: "bun", format: "esm", sourcemap: "inline", metafile: true, packages: "external", throw: false,
+    }),
+    catch: (error) => new FactoryLoadFailed({ message: `The bundler failed: ${error instanceof Error ? error.message : String(error)}` }),
+  });
+  const inTree = (file: string): string | null => {
+    for (const base of [process.cwd(), tree]) {
+      const relative = path.relative(tree, path.resolve(base, file)).split(path.sep).join("/");
+      if (!relative.startsWith("..") && !path.isAbsolute(relative) && !relative.startsWith("node_modules/")) return relative;
+    }
+    return null;
+  };
+  if (!result.success || result.outputs[0] === undefined)
+    return { bundle: null, imports: {}, findings: result.logs.map((log) => finding("bundle", log.message, { file: log.position ? inTree(log.position.file) : null, line: log.position?.line ?? null })) } satisfies Bundled;
+  const imports: Record<string, string[]> = {};
+  for (const [input, facts] of Object.entries(result.metafile?.inputs ?? {})) {
+    const from = inTree(input);
+    if (from !== null) imports[from] = facts.imports.flatMap((imported) => { const to = inTree(imported.path); return to === null ? [] : [to]; });
+  }
+  return { bundle: result.outputs[0].path, imports, findings: [] } satisfies Bundled;
+});
+
+/** Run the evaluator on the bundle in its own process, with a runaway deadline. */
+const evaluate = Effect.fn("factory.load.evaluate")(function* (input: Omit<EvaluateInput, "out">, cache: string, key: string) {
+  const folder = path.join(cache, "evaluations");
+  const inputFile = path.join(folder, `${key}.input.json`);
+  const out = path.join(folder, `${key}.output.json`);
+  yield* Effect.tryPromise({ try: () => mkdir(folder, { recursive: true }).then(() => writeFile(inputFile, JSON.stringify({ ...input, out }))), catch: failed("Could not write the evaluator's input.") });
+  const ran = yield* runCommand(process.execPath, [path.join(here, "evaluate.ts"), inputFile], { cwd: input.tree, guardMillis: EVALUATE_GUARD_MILLIS });
+  if (ran.timedOut)
+    return { program: null, findings: [finding("evaluate", `Evaluating the factory's code ran past its runaway guard of ${EVALUATE_GUARD_MILLIS / 1000} s and was stopped. Factory code declares; it never waits.`)] };
+  if (ran.code !== 0) return yield* new FactoryLoadFailed({ message: `The evaluator failed (${ran.code}): ${ran.stderr.slice(-1_000)}` });
+  const output = yield* Effect.tryPromise({ try: () => readFile(out, "utf8"), catch: failed("The evaluator wrote nothing.") }).pipe(
+    Effect.flatMap(Schema.decodeUnknownEffect(Schema.fromJsonString(EvaluateOutputJson))),
+    Effect.mapError((error) => new FactoryLoadFailed({ message: `The evaluator's answer does not decode: ${error.message}` })),
+  );
+  return {
+    program: output.program,
+    findings: output.problems.map((problem) => finding(problem.step, problem.message, { node: problem.node, file: problem.at?.file ?? null, line: problem.at?.line ?? null })),
+  };
+});
+
+/** A finding in a file pinned to the node made nearest above it; in factory.ts, above every node, to the root. */
+const pinned = (program: Program | null) => (found: Finding): Finding => {
+  if (found.node !== null || found.file === null || program === null) return found;
+  const made = (Object.values(program.nodes) as Node[]).filter((node) => node.at.file === found.file).sort((left, right) => left.at.line - right.at.line);
+  const above = found.line === null ? [] : made.filter((node) => node.at.line <= found.line!);
+  const node = above.at(-1) ?? (found.file === "factory.ts" ? program.nodes[program.root] : made.at(-1));
+  return node === undefined ? found : { ...found, node: node.id };
+};
+
+type Timed = { step: Load["steps"][number]["step"]; millis: number };
+const timed = <A, E, R>(steps: Timed[], step: Timed["step"], effect: Effect.Effect<A, E, R>) => Effect.gen(function* () {
+  const started = performance.now();
+  const value = yield* effect;
+  steps.push({ step, millis: Math.round(performance.now() - started) });
+  return value;
+});
+
+/** Load a factory folder once. */
+export const loadFactory = Effect.fn("factory.load")(function* (input: Readonly<{ tree: string; framework?: string }>) {
+  const tree = yield* Effect.tryPromise({ try: () => realpath(path.resolve(input.tree)), catch: failed(`There is no factory folder at ${input.tree}.`) });
+  const framework = input.framework === undefined ? (yield* versions()).framework
+    : yield* Schema.decodeUnknownEffect(FrameworkVersion)(input.framework).pipe(Effect.mapError(failed(`${input.framework} is not a framework version.`)));
+  const steps: Timed[] = [];
+  const snapshot = yield* timed(steps, "snapshot", Effect.gen(function* () {
+    const paths = yield* listTree(tree);
+    const digests: Record<string, string> = {};
+    for (const file of paths) digests[file] = sha256(yield* Effect.tryPromise({ try: () => readFile(path.join(tree, file)), catch: failed(`Could not read ${file}.`) }));
+    return { paths, digests, key: folderKey(framework, digests, sha256) };
+  }));
+  const installed = (yield* exists(path.join(tree, "node_modules", "@thinair", "factory", "package.json"))) && (yield* exists(path.join(tree, "node_modules", "effect", "package.json")));
+  const cache = path.join(tree, "node_modules", ".thinair-factory");
+  const cacheFile = path.join(cache, "loads", `${snapshot.key}.json`);
+  if (installed && (yield* exists(cacheFile))) {
+    const cached = yield* Effect.tryPromise({ try: () => readFile(cacheFile, "utf8"), catch: failed("Could not read the load cache.") }).pipe(
+      Effect.flatMap(Schema.decodeUnknownEffect(Schema.fromJsonString(LoadJson))),
+      Effect.result,
+    );
+    if (Result.isSuccess(cached)) return { ...cached.success, cached: true, steps } satisfies Load;
+  }
+
+  const findings: Finding[] = [];
+  const manifest = snapshot.paths.includes("package.json") ? yield* readJson(path.join(tree, "package.json")) : {};
+  const dependencies = (manifest["dependencies"] ?? {}) as Readonly<Record<string, string>>;
+  yield* timed(steps, "shape", Effect.sync(() => {
+    for (const problem of appShapeProblems(snapshot.paths)) findings.push(finding("shape", problem.message, { file: problem.path }));
+    const pin = dependencies["@thinair/factory"];
+    if (pin !== undefined && /^\d+\.\d+\.\d+/u.test(pin) && compareVersions(pin, framework) > 0)
+      findings.push(finding("framework", `This factory needs @thinair/factory ${pin}; this loader is ${framework}. It loads when the newer framework runs here.`, { file: "package.json" }));
+    if (!installed) findings.push(finding("shape", "Its packages are not installed: run bun install in the factory folder.", { file: "package.json" }));
+  }));
+  if (!installed || !snapshot.paths.includes("factory.ts"))
+    return { version: LOAD_VERSION, framework, key: snapshot.key, state: "held", program: null, holes: [], findings, cached: false, steps } satisfies Load;
+
+  yield* Effect.tryPromise({ try: () => mkdir(cache, { recursive: true }), catch: failed(`Could not make the loader's cache at ${cache}.`) });
+  const packages = Object.keys(dependencies).filter((name) => name !== "@thinair/factory");
+  findings.push(...yield* timed(steps, "lint", lint(tree, snapshot.paths, packages, cache)));
+  const [bundled, types] = yield* Effect.all([timed(steps, "bundle", bundle(tree, snapshot.key, cache)), timed(steps, "type", typecheck(tree))], { concurrency: 2 });
+  findings.push(...bundled.findings, ...types);
+
+  let program: Program | null = null;
+  if (bundled.bundle !== null) {
+    const files = Object.fromEntries(snapshot.paths.filter((file) => file.endsWith(".ts")).map((file) => [file, { digest: snapshot.digests[file]!, imports: bundled.imports[file] ?? [] }]));
+    const evaluated = yield* timed(steps, "evaluate", evaluate({ tree, bundle: bundled.bundle, framework, files }, cache, snapshot.key));
+    program = evaluated.program;
+    findings.push(...evaluated.findings);
+    yield* timed(steps, "value", Effect.sync(() => {
+      for (const member of memberFiles(snapshot.paths))
+        if (member !== "factory.ts" && bundled.imports[member] === undefined)
+          findings.push(finding("value", `${member} is not reachable from factory.ts: list what it makes there, or delete it.`, { file: member }));
+      for (const node of Object.values(program?.nodes ?? {}) as Node[])
+        if (node._tag === "Agent" && !snapshot.paths.includes(node.instructions))
+          findings.push(finding("value", `Its instructions, ${node.instructions}, are not in the factory folder.`, { node: node.id, file: node.at.file, line: node.at.line }));
+    }));
+  }
+
+  const load: Load = yield* timed(steps, "encode", Effect.sync((): Load => {
+    const all = findings.map(pinned(program));
+    return { version: LOAD_VERSION, framework, key: snapshot.key, state: all.length === 0 ? "ready" : "held", program, holes: program === null ? [] : holesOf(program), findings: all, cached: false, steps };
+  }));
+  const encoded = yield* Schema.encodeEffect(LoadJson)(load).pipe(Effect.mapError((error) => new FactoryLoadFailed({ message: `The load does not encode: ${error.message}` })));
+  yield* Effect.tryPromise({ try: () => mkdir(path.dirname(cacheFile), { recursive: true }).then(() => writeFile(cacheFile, JSON.stringify(encoded))), catch: failed("Could not write the load cache.") });
+  return load;
+});
+
+/** Write the blank factory template into an empty or new folder. */
+export const initFactory = Effect.fn("factory.init")(function* (input: Readonly<{ directory: string; framework?: string }>) {
+  const directory = path.resolve(input.directory);
+  const present = yield* Effect.tryPromise({ try: () => readdir(directory), catch: () => null }).pipe(Effect.orElseSucceed(() => null));
+  if (present !== null && present.length > 0) return yield* new FactoryLoadFailed({ message: `${directory} is not empty: init writes a new factory folder.` });
+  const pins = yield* versions();
+  const files = templateFiles({ framework: input.framework ?? pins.framework, effect: pins.effect });
+  for (const [file, text] of Object.entries(files))
+    yield* Effect.tryPromise({ try: () => mkdir(path.dirname(path.join(directory, file)), { recursive: true }).then(() => writeFile(path.join(directory, file), text)), catch: failed(`Could not write ${file}.`) });
+  return { directory, files: Object.keys(files).sort() };
+});
+
+const branchOf = Effect.fn("factory.dev.branch")(function* (tree: string) {
+  const ran = yield* runCommand("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: tree, guardMillis: 15_000 });
+  return ran.code === 0 && ran.stdout.trim() !== "" ? ran.stdout.trim() : "working-copy";
+});
+
+/** The commit the working copy sits on; its load may hold changes not committed yet. */
+const commitOf = Effect.fn("factory.dev.commit")(function* (tree: string) {
+  const ran = yield* runCommand("git", ["rev-parse", "HEAD"], { cwd: tree, guardMillis: 15_000 });
+  return ran.code === 0 && /^[0-9a-f]{40}$/u.test(ran.stdout.trim()) ? ran.stdout.trim() : null;
+});
+
+const summary = (load: Load) => [
+  `${load.state} ${load.key.slice(0, 12)}${load.cached ? " (cached)" : ""}: ${Object.keys(load.program?.nodes ?? {}).length} nodes, ${load.holes.length} holes, ${load.findings.length} findings`,
+  ...load.findings.map((found) => `  ${found.node ?? "-"} ${found.file ?? ""}${found.line === null ? "" : `:${found.line}`} ${found.step}: ${found.message}`),
+].join("\n");
+
+/** The folder's files with their sizes and modification times: it changes when a save lands. */
+const signatureOf = (tree: string) => listTree(tree).pipe(Effect.flatMap((paths) => Effect.forEach(paths, (file) =>
+  Effect.tryPromise({ try: () => stat(path.join(tree, file)), catch: failed(`Could not read ${file}.`) }).pipe(
+    Effect.map((facts) => `${file} ${facts.size} ${facts.mtimeMs}`),
+    Effect.orElseSucceed(() => `${file} gone`),
+  ))), Effect.map((lines) => lines.join("\n")));
+
+/**
+ * Load on every save, and post each load as the branch's preview. It polls
+ * the folder rather than asking for file events: VM shared folders and some
+ * hosts never deliver them, and a factory folder is a few dozen files. A
+ * post that fails is said on stderr and the watch goes on: the next save
+ * posts again.
+ */
+export const watchFactory = Effect.fn("factory.dev")(function* (input: Readonly<{ tree: string; factory: string }>) {
+  const posts = yield* LoadPosts;
+  const tree = path.resolve(input.tree);
+  const loadAndPost = Effect.gen(function* () {
+    const load = yield* loadFactory({ tree });
+    const ref = yield* branchOf(tree);
+    process.stderr.write(`${summary(load)}\n`);
+    const started = performance.now();
+    const posted = yield* posts.post({ factory: input.factory, ref, commit: yield* commitOf(tree), load }).pipe(Effect.result);
+    process.stderr.write(posted._tag === "Success"
+      ? `posted ${ref}: ${posted.success.state}, drawing ${posted.success.revision?.slice(0, 12) ?? "nothing yet"} (${Math.round(performance.now() - started)} ms)\n`
+      : `not posted: ${posted.failure.message}\n`);
+  });
+  let seen = yield* signatureOf(tree);
+  yield* loadAndPost;
+  return yield* Effect.forever(Effect.gen(function* () {
+    yield* Effect.sleep(POLL_MILLIS);
+    const now = yield* signatureOf(tree);
+    if (now === seen) return;
+    yield* Effect.sleep(SETTLE_MILLIS);
+    seen = yield* signatureOf(tree);
+    yield* loadAndPost;
+  }));
+});
+
+const USAGE = `thinair-factory: the factory loader
+  init [dir] [--framework <spec>]   write the blank factory template (dir: factory)
+  load [tree] [--framework <x.y.z>] load once and print the Load as JSON (tree: .)
+  dev --factory <id> [--tree <dir>] load on every save and post each load
+`;
+
+const flag = (args: ReadonlyArray<string>, name: string) => {
+  const index = args.indexOf(name);
+  return index === -1 ? undefined : args[index + 1];
+};
+const positional = (args: ReadonlyArray<string>) => args.filter((arg, index) => !arg.startsWith("--") && !(args[index - 1] ?? "").startsWith("--"));
+
+const main = Effect.fn("factory.cli")(function* (argv: ReadonlyArray<string>) {
+  const [command, ...args] = argv;
+  if (command === "init") {
+    const framework = flag(args, "--framework");
+    const made = yield* initFactory({ directory: positional(args)[0] ?? "factory", ...(framework === undefined ? {} : { framework }) });
+    process.stderr.write(`Wrote ${made.files.join(", ")} to ${made.directory}. Next: bun install there, then load.\n`);
+    return 0;
+  }
+  if (command === "load") {
+    const framework = flag(args, "--framework");
+    const load = yield* loadFactory({ tree: positional(args)[0] ?? ".", ...(framework === undefined ? {} : { framework }) });
+    process.stdout.write(`${JSON.stringify(Schema.encodeSync(LoadJson)(load))}\n`);
+    process.stderr.write(`${summary(load)}\n`);
+    return load.state === "ready" ? 0 : 1;
+  }
+  if (command === "dev") {
+    const factory = flag(args, "--factory");
+    if (factory === undefined) return yield* new FactoryLoadFailed({ message: `dev needs --factory <id>.\n${USAGE}` });
+    return yield* watchFactory({ tree: flag(args, "--tree") ?? ".", factory }).pipe(Effect.provide(LoadPostsThroughThinair));
+  }
+  process.stderr.write(USAGE);
+  return command === undefined || command === "--help" ? 0 : 2;
+});
+
+if (import.meta.main) {
+  const exit = await Effect.runPromiseExit(main(process.argv.slice(2)));
+  if (exit._tag === "Success") process.exitCode = exit.value;
+  else {
+    process.stderr.write(`${String(exit.cause)}\n`);
+    process.exitCode = 2;
+  }
+}

package/cli/template.ts

@@ -0,0 +1,73 @@
+/*
+ * What `init` writes: a blank factory. Every slot of the root is a hole by
+ * the tag it expects, so the floor draws a blank floor of dashed amber
+ * parts. Filling a hole is one change in place: write the member file, and
+ * list it in factory.ts where its hole was.
+ */
+
+export type TemplatePins = Readonly<{ framework: string; effect: string }>;
+
+const factoryTs = `import { defineFactory } from "@thinair/factory/domain/system-elements/factory";
+import { hole } from "@thinair/factory/domain/system-elements/hole";
+
+/*
+ * This factory's root: what it lists runs and shows; nothing else does.
+ * Each hole is a part still to build. Fill one by writing its member file
+ * (repositories/, intake/, stages/, jobs/, agents/) with one default export,
+ * and listing it here where its hole was.
+ */
+export default defineFactory({
+  repositories: [hole("Repository", "main")],
+  rules: [hole("Rule", "intake")],
+  stages: [hole("Stage", "change")],
+  fleet: [hole("Pool", "macs")],
+  agents: [hole("Agent", "coder")],
+});
+`;
+
+const tsconfig = {
+  compilerOptions: {
+    target: "ES2022",
+    module: "ESNext",
+    moduleResolution: "Bundler",
+    moduleDetection: "force",
+    lib: ["ES2022"],
+    types: [],
+    strict: true,
+    noUncheckedIndexedAccess: true,
+    isolatedModules: true,
+    skipLibCheck: true,
+    noEmit: true,
+  },
+  include: ["**/*.ts"],
+  exclude: ["node_modules"],
+};
+
+const readme = `# factory
+
+This folder is the code of a Thinair factory. It declares what should be
+true: repositories, stages of work, jobs, agents, the fleet and standing
+goals. \`@thinair/factory\` compiles it to one program; the factory's
+\`.factory\` File runs it.
+
+- \`bunx @thinair/factory load .\` checks it and prints the program.
+- \`bunx @thinair/factory dev --factory <id>\` reloads it on every save.
+
+Factory code imports only the authoring modules of \`@thinair/factory\` and
+its own npm packages. Steps are the only imperative code, and outward writes
+are acts.
+`;
+
+/** The template's files, by path relative to the factory folder. */
+export const templateFiles = (pins: TemplatePins): Readonly<Record<string, string>> => ({
+  "factory.ts": factoryTs,
+  "package.json": `${JSON.stringify({
+    name: "factory",
+    private: true,
+    type: "module",
+    dependencies: { "@thinair/factory": pins.framework, effect: pins.effect },
+  }, null, 2)}\n`,
+  "tsconfig.json": `${JSON.stringify(tsconfig, null, 2)}\n`,
+  "README.md": readme,
+  ".gitignore": "node_modules\n",
+});

package/domain/load.ts

@@ -0,0 +1,67 @@
+import { Schema } from "effect";
+import { NodeId, NodeTag } from "./system-elements/node";
+import { FrameworkVersion, Program } from "./system-elements/program";
+
+/*
+ * What one load of a factory's code gives: the program, its state, and its
+ * findings, each pinned to a node, a file and a line where it knows them.
+ * The loader prints it; `factory.load.post` carries it to the plane, which
+ * keeps one load row per (factory, ref): the live one for the followed ref,
+ * a preview per branch.
+ */
+
+export const LOAD_VERSION = 1;
+
+/** Which step found it: the folder's shape, the factory-code lint, the type check, the bundle, evaluation, or the value checks. */
+export const FindingStep = Schema.Literals(["shape", "lint", "type", "bundle", "evaluate", "value", "framework"]);
+export type FindingStep = typeof FindingStep.Type;
+
+export const Finding = Schema.Struct({
+  step: FindingStep,
+  node: Schema.NullOr(NodeId),
+  file: Schema.NullOr(Schema.String),
+  line: Schema.NullOr(Schema.Int),
+  message: Schema.String,
+});
+export type Finding = typeof Finding.Type;
+
+/** `ready` runs (live) or draws (preview). `held` keeps the last good revision: its findings say why. */
+export const LoadState = Schema.Literals(["ready", "held"]);
+export type LoadState = typeof LoadState.Type;
+
+export const LoadStep = Schema.Literals(["snapshot", "shape", "lint", "bundle", "type", "evaluate", "value", "encode"]);
+
+export const Load = Schema.Struct({
+  version: Schema.Literal(LOAD_VERSION),
+  /** The `@thinair/factory` version that loaded it. */
+  framework: FrameworkVersion,
+  /** The content key of the folder: the same files under the same framework give the same key. */
+  key: Schema.String,
+  state: LoadState,
+  /** The program, when its code evaluated, even while held. */
+  program: Schema.NullOr(Program),
+  /** The holes still to build, by the tag each expects. */
+  holes: Schema.Array(Schema.Struct({ expects: NodeTag, id: NodeId })),
+  findings: Schema.Array(Finding),
+  /** This load came from the cache of an earlier load with the same key. */
+  cached: Schema.Boolean,
+  /** How long each step took, for the record; never a pass condition. */
+  steps: Schema.Array(Schema.Struct({ step: LoadStep, millis: Schema.Number })),
+});
+export type Load = typeof Load.Type;
+export const LoadJson = Schema.toCodecJson(Load);
+
+/** A git ref or a commit, as a load names it: one line, no spaces. */
+export const RefName = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(255), Schema.isPattern(/^[^\s]+$/u));
+
+/** What `factory.load.post` takes: a load of one ref of one factory, posted as the agent. */
+export const LoadPost = Schema.Struct({
+  /** The `.factory` File's id. */
+  factory: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256)),
+  /** The branch the working copy is on. */
+  ref: RefName,
+  /** The commit the working copy sat on when it loaded, when it knows; the load may hold changes not committed yet. */
+  commit: Schema.optionalKey(Schema.NullOr(RefName)),
+  load: Load,
+});
+export type LoadPost = typeof LoadPost.Type;