@archlast/forge-cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 algochad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,7 @@
-# Temporary Holding Version
+# @archlast/forge-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The archlast-forge command line: dev, up, build, data and config commands.
+
+Part of [archlast-forge](https://github.com/algochad/archlast-forge), a self-hosted reactive backend and full-stack framework for TypeScript on Bun. Start with `bun create archlast-forge`; the documentation is in the repository.
+
+MIT licensed.

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@archlast/forge-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The archlast-forge command line: dev, up, build, data and config commands.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/algochad/archlast-forge.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/algochad/archlast-forge#readme",
+  "bugs": "https://github.com/algochad/archlast-forge/issues",
+  "keywords": [
+    "archlast-forge",
+    "backend",
+    "realtime",
+    "bun",
+    "convex"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/codegen.ts"
+  },
+  "bin": {
+    "archlast-forge": "./src/index.ts"
+  },
+  "dependencies": {
+    "@archlast/forge-dashboard": "^0.1.0",
+    "@archlast/forge-runtime": "^0.1.0",
+    "create-archlast-forge": "^0.1.0"
+  },
+  "engines": {
+    "bun": ">=1.4.3"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/app.ts

@@ -0,0 +1,43 @@
+// Framework mode, from the CLI's side: find the framework package in the project, build the app, and describe the result.
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { fail } from "./common";
+import { c, task } from "./ui";
+
+type Server = typeof import("@archlast/forge-framework/server");
+type Build = typeof import("@archlast/forge-framework/build");
+type Parts = { server: Server; build: Build };
+
+/**
+ * Loads @archlast/forge-framework/<part> from the project. Inside the engine image the project's copy is a link to the engine's own,
+ * and a checkout of this repository finds it next to the CLI.
+ */
+export async function loadFramework<P extends keyof Parts>(root: string, part: P): Promise<Parts[P]> {
+  const spec = `@archlast/forge-framework/${part}`;
+  const sibling = new URL(`../../framework/src/${part === "server" ? "server.tsx" : "build.ts"}`, import.meta.url).pathname;
+  for (const from of [() => Bun.resolveSync(spec, root), () => sibling]) {
+    try {
+      const path = from();
+      if (existsSync(path)) return (await import(path)) as Parts[P];
+    } catch {
+      // try the next place
+    }
+  }
+  return fail(`This is a full-stack project, which needs @archlast/forge-framework. Install it with:\n  bun add @archlast/forge-framework`);
+}
+
+const kb = (bytes: number) => `${(bytes / 1024).toFixed(bytes < 10240 ? 1 : 0)} kB`;
+
+/** Builds the production bundles into <root>/.forge/build and prints what the browser will download. */
+export async function buildFramework(root: string) {
+  const { buildApp } = await loadFramework(root, "build");
+  const { manifest, dir } = await task("Building the app", () => buildApp({ root, dev: false })).catch((e: Error) => fail(e.message));
+  const client = join(dir, "client");
+  const size = (file: string, ext = "") => (existsSync(join(client, file + ext)) ? statSync(join(client, file + ext)).size : 0);
+  const chunks = readdirSync(client).filter((f) => f.endsWith(".js"));
+  const total = chunks.reduce((n, f) => n + size(f), 0);
+  const first = [manifest.entry, ...manifest.css];
+  console.log(`  ${c.dim("first load")}  ${first.map((f) => `${f.replace(/-[a-z0-9]+(\.\w+)$/, "$1")} ${kb(size(f))} ${c.dim(`(${kb(size(f, ".br") || size(f, ".gz") || size(f))} compressed)`)}`).join(", ")}`);
+  console.log(`  ${c.dim("all code ")}  ${chunks.length} files, ${kb(total)}; each page loads only the routes it shows`);
+  return { manifest, dir };
+}

package/src/codegen.ts

@@ -0,0 +1,67 @@
+import { listModules } from "@archlast/forge-runtime/server";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+
+const HEADER = "// Generated by `archlast-forge codegen`. Do not edit.\n";
+
+type Tree = { [key: string]: Tree | string };
+
+const render = (tree: Tree, visibility: string, indent = "  "): string =>
+  Object.entries(tree)
+    .map(
+      ([k, v]) =>
+        `${indent}${JSON.stringify(k)}: ${typeof v === "string" ? `ModuleRefs<typeof ${v}, "${visibility}">` : `{\n${render(v, visibility, indent + "  ")}${indent}}`};\n`,
+    )
+    .join("");
+
+/** Writes forge/_generated/{api,dataModel}.ts. Types are derived from the modules, so nothing is hand-written. */
+export async function codegen(forgeDir: string) {
+  const modules = listModules(forgeDir);
+  const tree: Tree = {};
+  const imports = modules.map((m, i) => {
+    const id = `m${i}_${m.name.replace(/[^a-zA-Z0-9]/g, "_")}`;
+    const path = m.name.split("/");
+    let node = tree;
+    for (const seg of path.slice(0, -1)) node = (node[seg] ??= {}) as Tree;
+    node[path.at(-1)!] = id;
+    return `import type * as ${id} from "../${m.name}";\n`;
+  });
+  const api =
+    HEADER +
+    `import { anyApi, type ModuleRefs } from "@archlast/forge-runtime";\n` +
+    `import type {} from "./dataModel";\n` +
+    imports.join("") +
+    `\n/** Public functions, callable from clients. */\nexport const api: {\n${render(tree, "public")}} = anyApi;\n` +
+    `\n/** Internal functions: callable only from other functions, the scheduler and crons. */\nexport const internal: {\n${render(tree, "internal")}} = anyApi;\n`;
+  const dataModel =
+    HEADER +
+    `import type schema from "../schema";\n\n` +
+    `declare module "@archlast/forge-runtime" {\n  interface Register {\n    schema: typeof schema;\n  }\n}\n\n` +
+    `export type { Doc, Id, TableNames } from "@archlast/forge-runtime";\n`;
+  const out = join(forgeDir, "_generated");
+  mkdirSync(out, { recursive: true });
+  // Skip unchanged files so watchers don't loop.
+  for (const [file, content] of [["api.ts", api], ["dataModel.ts", dataModel]] as const) {
+    const path = join(out, file);
+    if (!existsSync(path) || (await Bun.file(path).text()) !== content) await Bun.write(path, content);
+  }
+  return modules.map((m) => m.name);
+}
+
+/** Frontend code (src/ in an app with its own bundler, app/ in framework mode) may import only forge/_generated, or server-only code would reach the browser bundle. */
+export async function checkFrontendImports(forgeDir: string) {
+  const generated = join(forgeDir, "_generated");
+  const violations: string[] = [];
+  for (const dir of ["src", "app"].map((d) => join(dirname(forgeDir), d)).filter(existsSync)) {
+    for (const file of new Bun.Glob("**/*.{ts,tsx,js,jsx,mts}").scanSync({ cwd: dir, absolute: true })) {
+      const loader = file.endsWith("x") ? "tsx" : "ts";
+      for (const imp of new Bun.Transpiler({ loader }).scanImports(await Bun.file(file).text())) {
+        if (!imp.path.startsWith(".")) continue;
+        const target = resolve(dirname(file), imp.path);
+        const inside = (d: string) => target === d || target.startsWith(d + "/");
+        if (inside(forgeDir) && !inside(generated)) violations.push(`${relative(process.cwd(), file)} imports "${imp.path}"`);
+      }
+    }
+  }
+  return violations;
+}

package/src/common.ts

@@ -0,0 +1,56 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { checkFrontendImports, codegen } from "./codegen";
+import { c } from "./ui";
+
+export function fail(message: string): never {
+  console.error(`${c.red("✗")} ${message}`);
+  process.exit(1);
+}
+
+/** The folder holding schema.ts and your functions: `forge/`, or the current directory if it has schema.ts. A project still using the old `convex/` name keeps working, with a nudge to rename it. */
+export function findForgeDir(dir?: string) {
+  let picked = dir;
+  if (!picked) {
+    if (existsSync("forge/schema.ts")) picked = "forge";
+    else if (existsSync("schema.ts")) picked = ".";
+    else if (existsSync("convex/schema.ts")) {
+      console.warn("! Using convex/, the old name for this folder. Rename it to forge/ (and update imports of ../convex/_generated).");
+      picked = "convex";
+    } else picked = "forge";
+  }
+  const abs = resolve(picked);
+  if (!existsSync(join(abs, "schema.ts"))) fail(`No schema.ts in ${abs}. Pass --dir <path to forge/>.`);
+  return abs;
+}
+
+/** Dev-only secrets, persisted so sessions and the dashboard key survive restarts. */
+export function devSecrets(env: Record<string, string | undefined>, dir: string) {
+  const file = join(dir, ".dev-secrets.json");
+  const saved: Record<string, string> = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
+  for (const key of ["BETTER_AUTH_SECRET", "ADMIN_KEY"]) env[key] ||= saved[key] ??= Buffer.from(crypto.getRandomValues(new Uint8Array(24))).toString("hex");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(file, JSON.stringify(saved, null, 2), { mode: 0o600 });
+  return env;
+}
+
+/** Behind code-server's port proxy (VSCODE_PROXY_URI=https://{{port}}.host/), browsers use the proxy origin, so trust it too. */
+export function trustProxyOrigins(env: Record<string, string | undefined>) {
+  const uri = env.VSCODE_PROXY_URI;
+  if (!uri?.includes("{{port}}.")) return;
+  const ports = (env.TRUSTED_ORIGINS ?? "").split(",").map((o) => /^http:\/\/localhost:(\d+)$/.exec(o.trim())?.[1]);
+  const extra = ports.filter(Boolean).map((p) => new URL(uri.replace("{{port}}", p!)).origin);
+  env.TRUSTED_ORIGINS = [env.TRUSTED_ORIGINS, ...extra].filter(Boolean).join(",");
+}
+
+export async function generate(dir: string) {
+  const modules = await codegen(dir);
+  const violations = await checkFrontendImports(dir);
+  if (violations.length) throw new Error(`Frontend code must import only forge/_generated:\n  ${violations.join("\n  ")}`);
+  return modules;
+}
+
+export const loadDashboard = async () => (await import("@archlast/forge-dashboard")).default;
+
+/** The CLI's own version; the engine image is tagged with it. */
+export const VERSION: string = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;

package/src/deps.ts

@@ -0,0 +1,33 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export function findUp(dir: string, name: string): string | undefined {
+  for (let d = dir; ; d = dirname(d)) {
+    if (existsSync(join(d, name))) return join(d, name);
+    if (dirname(d) === d) return undefined;
+  }
+}
+
+const depsHash = async (pkg: string, lock?: string) =>
+  String(Bun.hash((await Bun.file(pkg).text()) + (lock && existsSync(lock) ? await Bun.file(lock).text() : "")));
+
+/**
+ * Runs `bun install` for forge/package.json when it or the lockfile changed since the last install.
+ * Lifecycle scripts are off unless the manifest lists `trustedDependencies` (then Bun runs only those).
+ */
+export async function ensureDeps(forgeDir: string): Promise<boolean> {
+  const pkg = join(forgeDir, "package.json");
+  if (!existsSync(pkg)) return false;
+  const lock = findUp(forgeDir, "bun.lock");
+  const stamp = join(forgeDir, "_generated", ".depshash");
+  if (existsSync(stamp) && (await Bun.file(stamp).text()) === (await depsHash(pkg, lock))) return false;
+  const manifest = await Bun.file(pkg).json();
+  const args = manifest.trustedDependencies ? ["install"] : ["install", "--ignore-scripts"];
+  console.log(`→ installing server dependencies: bun ${args.join(" ")} (${forgeDir})`);
+  const proc = Bun.spawnSync([process.execPath, ...args], { cwd: forgeDir, stdout: "inherit", stderr: "inherit" });
+  if (proc.exitCode !== 0)
+    throw new Error(`bun install failed in ${forgeDir} (exit ${proc.exitCode}). Fix forge/package.json; native packages may need "trustedDependencies".`);
+  mkdirSync(dirname(stamp), { recursive: true });
+  await Bun.write(stamp, await depsHash(pkg, findUp(forgeDir, "bun.lock")));
+  return true;
+}

package/src/docker.ts

@@ -0,0 +1,256 @@
+// Host side of the Docker engine: the CLI starts, stops and talks to the engine container.
+import { cpSync, existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, relative } from "node:path";
+import { fail, VERSION } from "./common";
+import { projectRoot } from "./project";
+
+const DOCKER = process.env.DOCKER ?? "docker";
+const REPO_ROOT = new URL("../../..", import.meta.url).pathname.replace(/\/$/, "");
+export const ENGINE_DOCKERFILE = join(REPO_ROOT, "docker", "engine.Dockerfile");
+
+/** Released to GHCR by the release workflow; `engine build` tags local builds the same way. */
+export const engineImage = () => process.env.ARCHLAST_ENGINE_IMAGE ?? `ghcr.io/algochad/archlast-forge-engine:${VERSION}`;
+
+export function docker(args: string[], opts: { inherit?: boolean; input?: string } = {}) {
+  const proc = Bun.spawnSync([DOCKER, ...args], {
+    stdout: opts.inherit ? "inherit" : "pipe",
+    stderr: opts.inherit ? "inherit" : "pipe",
+    stdin: opts.input === undefined ? "ignore" : new TextEncoder().encode(opts.input),
+  });
+  return { ok: proc.exitCode === 0, out: proc.stdout?.toString().trim() ?? "", err: proc.stderr?.toString().trim() ?? "" };
+}
+
+let available: boolean | undefined;
+export const dockerAvailable = () => (available ??= Bun.spawnSync([DOCKER, "info"], { stdout: "ignore", stderr: "ignore" }).exitCode === 0);
+
+/** Stable per-project name, from the directory holding forge/. */
+export function projectName(forgeDir: string) {
+  const root = ["forge", "convex"].includes(basename(forgeDir)) ? dirname(forgeDir) : forgeDir;
+  const slug = basename(root).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "app";
+  return `${slug}-${Bun.hash(root).toString(16).slice(0, 6)}`;
+}
+/** Production and dev containers of a project have separate names, so one never replaces the other. */
+export const containerName = (forgeDir: string, dev = false) => `archlast-forge-${projectName(forgeDir)}${dev ? "-dev" : ""}`;
+
+/** The project's running engine container (production first), if any. */
+export const runningContainer = (forgeDir: string) => [containerName(forgeDir), containerName(forgeDir, true)].find(isRunning);
+
+export const isRunning = (name: string) => docker(["inspect", "-f", "{{.State.Running}}", name]).out === "true";
+
+/** Builds the engine image from this repository. */
+export function buildEngine(tag = engineImage()) {
+  if (!existsSync(ENGINE_DOCKERFILE)) fail(`No engine Dockerfile at ${ENGINE_DOCKERFILE}; set ARCHLAST_ENGINE_IMAGE to a published image instead.`);
+  console.log(`→ building ${tag}`);
+  if (!docker(["build", "-f", ENGINE_DOCKERFILE, "-t", tag, REPO_ROOT], { inherit: true }).ok) fail("Engine image build failed");
+  return tag;
+}
+
+export function ensureEngineImage() {
+  const image = engineImage();
+  if (docker(["image", "inspect", image]).ok) return image;
+  if (existsSync(ENGINE_DOCKERFILE)) return buildEngine(image);
+  console.log(`→ pulling ${image}`);
+  if (docker(["pull", image], { inherit: true }).ok) return image;
+  fail(`Engine image ${image} isn't available. Set ARCHLAST_ENGINE_IMAGE to one you can pull or build.`);
+}
+
+const SERVICES = {
+  postgres: {
+    image: "postgres:17-alpine",
+    env: { POSTGRES_USER: "forge", POSTGRES_PASSWORD: "forge", POSTGRES_DB: "forge" },
+    volume: "/var/lib/postgresql/data",
+    port: 5432,
+    provides: (address: string) => ({ DATABASE_URL: `postgres://forge:forge@${address}/forge` }),
+  },
+  redis: { image: "redis:7-alpine", env: {}, volume: "/data", port: 6379, provides: (address: string) => ({ REDIS_URL: `redis://${address}` }) },
+  s3: {
+    image: "rustfs/rustfs:latest",
+    env: { RUSTFS_ACCESS_KEY: "forgeadmin", RUSTFS_SECRET_KEY: "forgeadmin", RUSTFS_CORS_ALLOWED_ORIGINS: "*" },
+    volume: "/data",
+    cmd: ["/data"],
+    port: 9000,
+    // shortcut: with the engine in a container, one project per machine can publish 9000; set S3_ENDPOINT yourself for more.
+    publish: "9000:9000",
+    provides: (address: string, host: boolean) => ({
+      S3_ENDPOINT: `http://${address}`,
+      S3_PUBLIC_ENDPOINT: host ? `http://${address}` : process.env.S3_PUBLIC_ENDPOINT || "http://localhost:9000",
+      S3_BUCKET: "forge",
+      S3_ACCESS_KEY_ID: "forgeadmin",
+      S3_SECRET_ACCESS_KEY: "forgeadmin",
+      S3_REGION: "us-east-1",
+    }),
+  },
+} as const;
+export type Service = keyof typeof SERVICES;
+
+/** The host port Docker published for a container port. */
+function publishedPort(container: string, port: number) {
+  const out = docker(["port", container, `${port}/tcp`]).out;
+  const found = /:(\d+)\s*$/m.exec(out);
+  if (!found) fail(`Couldn't find the published port of ${container} (docker port said: ${out || "nothing"})`);
+  return Number(found![1]);
+}
+
+/** Blocks until a service answers, so the engine doesn't start against a database that is still initializing. */
+function waitReady(container: string, service: Service) {
+  const probe = { postgres: ["pg_isready", "-U", "forge", "-d", "forge"], redis: ["redis-cli", "ping"], s3: undefined }[service];
+  if (!probe) return;
+  for (let i = 0; i < 120; i++) {
+    if (docker(["exec", container, ...probe]).ok) return;
+    Bun.sleepSync(500);
+  }
+  fail(`${service} didn't become ready in 60 s. See: docker logs ${container}`);
+}
+
+export interface StartedServices {
+  env: Record<string, string>;
+  /** For display: "postgres on localhost:54321". */
+  where: string[];
+}
+
+/** Service containers this process started, so `dev` can stop exactly those when it ends. */
+const startedHere = new Set<string>();
+
+/** Stops the service containers this process started. Their data stays in the named volumes. */
+export function stopStartedServices() {
+  for (const container of startedHere) docker(["stop", "-t", "3", container]);
+  startedHere.clear();
+}
+
+/**
+ * Starts service containers on the project's network and returns the env vars that point the engine at them.
+ * `host: true` is for an engine running on this machine: ports are published on 127.0.0.1 and the URLs say localhost.
+ * Otherwise the engine is a container on the same network and uses the containers' names.
+ */
+export function startServices(name: string, services: Service[], opts: { host?: boolean } = {}): StartedServices {
+  const out: StartedServices = { env: {}, where: [] };
+  if (!services.length) return out;
+  docker(["network", "create", name]);
+  for (const s of services) {
+    const def = SERVICES[s];
+    if (!def) fail(`Unknown service "${s}" (postgres, redis, s3)`);
+    const container = `${name}-${s}`;
+    if (!isRunning(container)) {
+      docker(["rm", "-f", container]);
+      const envArgs = Object.entries(def.env).flatMap(([k, v]) => ["-e", `${k}=${v}`]);
+      const cmd = "cmd" in def ? [...def.cmd] : [];
+      const publish = opts.host ? ["-p", `127.0.0.1::${def.port}`] : "publish" in def ? ["-p", def.publish] : [];
+      const run = docker(["run", "-d", "--name", container, "--network", name, "-v", `${container}:${def.volume}`, ...publish, ...envArgs, def.image, ...cmd]);
+      if (!run.ok) fail(`Couldn't start ${s}: ${run.err}`);
+      startedHere.add(container);
+    }
+    waitReady(container, s);
+    const address = opts.host ? `localhost:${publishedPort(container, def.port)}` : `${container}:${def.port}`;
+    Object.assign(out.env, (def.provides as (a: string, h: boolean) => Record<string, string>)(address, Boolean(opts.host)));
+    out.where.push(`${s} on ${address}`);
+  }
+  if (services.includes("s3")) {
+    // The bucket must exist before the first upload.
+    for (let i = 0; i < 30; i++) {
+      const mb = docker(["run", "--rm", "--network", name, "-e", "AWS_ACCESS_KEY_ID=forgeadmin", "-e", "AWS_SECRET_ACCESS_KEY=forgeadmin", "-e", "AWS_DEFAULT_REGION=us-east-1", "amazon/aws-cli", "--endpoint-url", `http://${name}-s3:9000`, "s3", "mb", "s3://forge"]);
+      if (mb.ok || /BucketAlready/.test(mb.err)) break;
+      Bun.sleepSync(1000);
+    }
+  }
+  return out;
+}
+
+export interface RunOptions {
+  forgeDir: string;
+  port: number;
+  dev: boolean;
+  env: Record<string, string>;
+  services?: Service[];
+  image?: string;
+  /** Defaults to forge/.env when it exists. */
+  envFile?: string;
+}
+
+/** Runs the engine container. In dev, forge/ is mounted read-only and the engine watches it. */
+export function runEngine(o: RunOptions) {
+  const name = containerName(o.forgeDir, o.dev);
+  const image = o.image ?? ensureEngineImage();
+  docker(["rm", "-f", name]);
+  const serviceEnv = startServices(name, o.services ?? []).env;
+  const env = { PORT: "3000", DATA_DIR: "/data", ...serviceEnv, ...o.env };
+  const envFile = o.envFile ?? join(o.forgeDir, ".env");
+  const args = [
+    "run",
+    "-d",
+    "--name",
+    name,
+    "-p",
+    `${o.port}:3000`,
+    "-v",
+    `${name}-data:/data`,
+    "--add-host",
+    "host.docker.internal:host-gateway",
+    ...((o.services ?? []).length ? ["--network", name] : []),
+    ...(existsSync(envFile) ? ["--env-file", envFile] : []),
+    ...Object.entries(env).flatMap(([k, v]) => ["-e", `${k}=${v}`]),
+    ...(o.dev ? ["-v", `${o.forgeDir}:/src/forge:ro`, "-v", `${name}-modules:/app/forge/node_modules`] : ["--restart", "unless-stopped"]),
+    image,
+    "engine",
+    "serve",
+    ...(o.dev ? ["--dev"] : []),
+  ];
+  const run = docker(args);
+  if (!run.ok) fail(`docker run failed: ${run.err}`);
+  return name;
+}
+
+/** Follows the container's logs; Ctrl-C stops the container (dev). */
+export function attach(name: string, stopOnExit: boolean) {
+  const logs = Bun.spawn([DOCKER, "logs", "-f", "--since", "0s", name], { stdout: "inherit", stderr: "inherit" });
+  const stop = () => {
+    if (stopOnExit) {
+      console.log(`\nstopping ${name}…`);
+      docker(["stop", "-t", "15", name]); // SIGTERM: the engine drains connections first
+      stopStartedServices();
+    }
+    logs.kill();
+    process.exit(0);
+  };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+  return logs.exited;
+}
+
+/**
+ * Builds a production image: the engine plus this project's code and dependencies.
+ * A project made by `archlast-forge init` has its own Dockerfile and builds from its root; older ones get a generated one around forge/.
+ */
+export function buildAppImage(forgeDir: string, tag: string) {
+  const image = ensureEngineImage();
+  const root = projectRoot(forgeDir);
+  if (existsSync(join(root, "Dockerfile")) && existsSync(join(root, "archlast-forge.json"))) {
+    console.log(`→ building ${tag} from ${image}`);
+    if (!docker(["build", "-t", tag, "-f", join(root, "Dockerfile"), "--build-arg", `ENGINE_IMAGE=${image}`, root], { inherit: true }).ok) fail("App image build failed");
+    return tag;
+  }
+  const ctx = mkdtempSync(join(tmpdir(), "afx-build-"));
+  try {
+    cpSync(forgeDir, join(ctx, "forge"), {
+      recursive: true,
+      filter: (src) => !relative(forgeDir, src).split("/").some((seg) => seg === "node_modules" || seg === "data" || seg === ".env" || seg === ".git"),
+    });
+    writeFileSync(
+      join(ctx, "Dockerfile"),
+      `FROM ${image}\nCOPY forge /src/forge\nRUN bun /engine/packages/cli/src/index.ts engine prepare\nENV NODE_ENV=production\n`,
+    );
+    console.log(`→ building ${tag} from ${image}`);
+    if (!docker(["build", "-t", tag, ctx], { inherit: true }).ok) fail("App image build failed");
+  } finally {
+    rmSync(ctx, { recursive: true, force: true });
+  }
+  return tag;
+}
+
+/** Runs a CLI command inside the running engine container. */
+export function execInEngine(name: string, args: string[], opts: { inherit?: boolean } = { inherit: true }) {
+  return docker(["exec", name, "bun", "/engine/packages/cli/src/index.ts", ...args, "--dir", "/app/forge", "--no-docker"], opts);
+}
+
+export const copyFrom = (name: string, path: string, to: string) => docker(["cp", `${name}:${path}`, to]).ok;
+export const copyTo = (name: string, from: string, path: string) => docker(["cp", from, `${name}:${path}`]).ok;