@archlast/forge-cli 0.0.0-stage → 0.2.0

package/src/serve.ts

@@ -0,0 +1,57 @@
+import { startServer, type AppHost, type RunningServer } from "@archlast/forge-runtime/server";
+import { watch } from "node:fs";
+import { basename } from "node:path";
+import { fail, loadDashboard } from "./common";
+
+export interface ServeOptions {
+  forgeDir: string;
+  dev: boolean;
+  env: Record<string, string | undefined>;
+  /** Watch this directory and call `onChange` with changed files (dev). */
+  watchDir?: string;
+  /** Prepares for a reload (codegen, installs); return false to skip it. */
+  onChange?: (files: string[]) => Promise<boolean>;
+  /** A frontend served next to the API (framework mode). */
+  app?: AppHost;
+}
+
+/** Runs the server in this process: SIGTERM/SIGINT stop gracefully, SIGHUP reloads the function runtime. */
+export async function serve(opts: ServeOptions): Promise<RunningServer> {
+  const server = await startServer({ forgeDir: opts.forgeDir, dev: opts.dev, env: opts.env, dashboard: await loadDashboard(), app: opts.app }).catch((e) => fail(e.message));
+  let stopping = false;
+  const stop = async (signal: string) => {
+    if (stopping) process.exit(1); // second signal: don't wait
+    stopping = true;
+    console.log(`\n${signal}: draining connections…`);
+    await server.stop();
+    process.exit(0);
+  };
+  process.on("SIGTERM", () => void stop("SIGTERM"));
+  process.on("SIGINT", () => void stop("SIGINT"));
+  process.on("SIGHUP", () => void server.reload().then(() => console.log("✓ function runtime reloaded (SIGHUP)"), (e) => console.error(`✗ ${e.message}`)));
+
+  if (opts.watchDir && opts.onChange) {
+    const changed = new Set<string>();
+    let timer: Timer | undefined;
+    let running = Promise.resolve();
+    const apply = async () => {
+      const files = [...changed];
+      changed.clear();
+      try {
+        if (!(await opts.onChange!(files))) return;
+        await server.reload();
+        console.log(`✓ function runtime restarted (${files.map((f) => basename(f)).slice(0, 3).join(", ")}${files.length > 3 ? ", …" : ""})`);
+      } catch (e) {
+        console.error(`✗ ${(e as Error).message}`);
+      }
+    };
+    watch(opts.watchDir, { recursive: true }, (_event, file) => {
+      if (!file || /(^|\/)(node_modules|\.|data\/)/.test(file)) return;
+      if (!/\.(ts|js)$/.test(file) && !["package.json", "bun.lock"].includes(basename(file))) return;
+      changed.add(file);
+      clearTimeout(timer);
+      timer = setTimeout(() => (running = running.then(apply)), 150);
+    });
+  }
+  return server;
+}

package/src/stack.ts

@@ -0,0 +1,106 @@
+// The production stack: `up` builds the app image and starts everything in compose.yaml, `down` stops it.
+import { generateSecrets, renderEnv, type StackService } from "create-archlast-forge/stack";
+import { existsSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { fail } from "./common";
+import { dockerAvailable, engineImage, ensureEngineImage } from "./docker";
+import { banner, c, ok, task, warn } from "./ui";
+
+const DOCKER = process.env.DOCKER ?? "docker";
+
+const composeFile = (root: string) => join(root, "compose.yaml");
+
+function requireStack(root: string) {
+  if (!dockerAvailable()) fail("Docker isn't available. Install it and make sure it is running; the stack runs in containers.");
+  if (!existsSync(composeFile(root)))
+    fail(`No compose.yaml in ${root}. Projects made with \`archlast-forge init\` have one; for an older project, create the stack with:\n  bun create archlast-forge <new-folder> --mode backend\nand copy compose.yaml, Dockerfile and .dockerignore across.`);
+}
+
+/** Runs `docker compose` for the project without blocking the spinner. */
+async function compose(root: string, args: string[], opts: { inherit?: boolean } = {}) {
+  const proc = Bun.spawn([DOCKER, "compose", "--project-directory", root, "-f", composeFile(root), ...args], {
+    env: { ...process.env, ENGINE_IMAGE: process.env.ENGINE_IMAGE ?? engineImage() },
+    stdin: "ignore",
+    stdout: opts.inherit ? "inherit" : "pipe",
+    stderr: opts.inherit ? "inherit" : "pipe",
+  });
+  const [out, err, code] = await Promise.all([proc.stdout ? new Response(proc.stdout).text() : "", proc.stderr ? new Response(proc.stderr).text() : "", proc.exited]);
+  return { ok: code === 0, out: out.trim(), err: err.trim() };
+}
+
+/** Creates .env with fresh secrets if there isn't one. It is never overwritten: it holds the keys to the data. */
+export function ensureEnv(root: string, services: StackService[]): boolean {
+  const file = join(root, ".env");
+  if (existsSync(file)) return false;
+  writeFileSync(file, renderEnv(services, generateSecrets()));
+  chmodSync(file, 0o600);
+  return true;
+}
+
+const rawEnvValue = (root: string, key: string) => new RegExp(`^${key}=(.*)$`, "m").exec(existsSync(join(root, ".env")) ? readFileSync(join(root, ".env"), "utf8") : "")?.[1]?.trim();
+/** A value from .env, with `${OTHER}` filled in from the same file the way compose does (BETTER_AUTH_URL=https://${DOMAIN}). */
+const envValue = (root: string, key: string) => rawEnvValue(root, key)?.replace(/\$\{(\w+)\}/g, (_, other) => rawEnvValue(root, other) ?? "");
+
+/** The running app container of the project's compose stack, for commands that have to run inside it. */
+export function appContainer(root: string): string | undefined {
+  if (!existsSync(composeFile(root)) || !dockerAvailable()) return undefined;
+  const p = Bun.spawnSync([DOCKER, "compose", "--project-directory", root, "-f", composeFile(root), "ps", "-q", "app"], { stdout: "pipe", stderr: "ignore", stdin: "ignore", env: { ...process.env, ENGINE_IMAGE: process.env.ENGINE_IMAGE ?? engineImage() } });
+  return p.exitCode === 0 ? p.stdout.toString().trim().split("\n")[0] || undefined : undefined;
+}
+
+/** Builds and starts the stack, and waits until the app reports healthy. */
+export async function up(root: string, services: StackService[], opts: { rebuild?: boolean } = {}) {
+  requireStack(root);
+  if (ensureEnv(root, services)) ok("Created .env with fresh secrets (keep it out of git; it holds the keys to your data)");
+  ensureEngineImage();
+
+  await task("Building the app image", async () => {
+    const r = await compose(root, ["build", ...(opts.rebuild ? ["--no-cache"] : [])]);
+    if (!r.ok) throw new Error(r.err || r.out);
+  }).catch((e: Error) => fail(`The app image didn't build. The end of the output:\n\n${e.message.split("\n").slice(-15).join("\n")}`));
+
+  let upResult: { ok: boolean; err: string } | undefined;
+  await task(`Starting ${services.length ? `the app and ${services.filter((s) => s !== "caddy").join(", ") || "its proxy"}` : "the app"}`, async () => {
+    upResult = await compose(root, ["up", "-d", "--no-build", "--wait", "--wait-timeout", "240"]);
+    if (!upResult.ok) throw new Error(upResult.err);
+  }).catch(async () => {
+    console.error(`\n${upResult?.err.split("\n").slice(-6).join("\n")}\n`);
+    const logs = await compose(root, ["logs", "--tail", "30", "app"]);
+    console.error(c.dim(logs.out || logs.err));
+    fail("The stack didn't become healthy. The app's last log lines are above; `archlast-forge logs` follows them.");
+  });
+
+  const url = envValue(root, "BETTER_AUTH_URL") ?? "http://localhost:3000";
+  banner(`${c.green("●")} ${c.bold("up")}`, [
+    ["App", url],
+    ["Dashboard", `${url}/_dashboard`],
+    ["Admin key", "ADMIN_KEY in .env"],
+    ["Logs", "archlast-forge logs"],
+    ["Stop", "archlast-forge down"],
+  ]);
+  if (envValue(root, "ALLOW_INSECURE_HTTP") === "1" && !services.includes("caddy")) warn("Serving plain http, which is fine for trying it out. Put it behind https (add Caddy, or your own proxy) before real users arrive.");
+}
+
+export async function down(root: string, opts: { volumes?: boolean } = {}) {
+  requireStack(root);
+  const r = await task(opts.volumes ? "Stopping the stack and deleting its data" : "Stopping the stack", () => compose(root, ["down", ...(opts.volumes ? ["--volumes"] : [])]));
+  if (!r.ok) fail(r.err);
+  if (!opts.volumes) console.log(c.dim("  Data stays in Docker volumes. `archlast-forge down --volumes` deletes it."));
+}
+
+/** True when the project's stack has containers (running or not). */
+export async function hasStack(root: string): Promise<boolean> {
+  if (!existsSync(composeFile(root)) || !dockerAvailable()) return false;
+  const r = await compose(root, ["ps", "-a", "-q"]);
+  return r.ok && r.out.length > 0;
+}
+
+export async function logs(root: string, service?: string) {
+  requireStack(root);
+  await compose(root, ["logs", "--follow", "--tail", "100", ...(service ? [service] : [])], { inherit: true });
+}
+
+export async function status(root: string) {
+  requireStack(root);
+  await compose(root, ["ps", "-a"], { inherit: true });
+}

package/src/ui.ts

@@ -0,0 +1,48 @@
+// Terminal output: colors when there's a terminal to show them, and a spinner that becomes plain lines in logs and CI.
+
+const tty = Boolean(process.stdout.isTTY);
+const color = (tty && !process.env.NO_COLOR && process.env.TERM !== "dumb") || Boolean(process.env.FORCE_COLOR);
+const wrap = (open: number, close: number) => (s: string) => (color ? `\x1b[${open}m${s}\x1b[${close}m` : s);
+
+export const c = { bold: wrap(1, 22), dim: wrap(2, 22), red: wrap(31, 39), green: wrap(32, 39), yellow: wrap(33, 39), cyan: wrap(36, 39), magenta: wrap(35, 39) };
+
+export const ok = (message: string) => console.log(`${c.green("✓")} ${message}`);
+export const warn = (message: string) => console.log(`${c.yellow("!")} ${message}`);
+export const step = (message: string) => console.log(`${c.cyan("→")} ${message}`);
+
+/** A heading and aligned rows, e.g. the addresses a server answers on. */
+export function banner(title: string, rows: [label: string, value: string][]) {
+  const width = Math.max(...rows.map(([l]) => l.length));
+  console.log(`\n  ${title}\n`);
+  for (const [label, value] of rows) console.log(`  ${c.dim("➜")}  ${c.bold(label.padEnd(width))}  ${value}`);
+  console.log();
+}
+
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+/**
+ * Shows `message` with a spinner while `work` runs, then a ✓ or ✗ line. In a log (no terminal) it prints the message once.
+ * `work` gets a function to change the message.
+ */
+export async function task<T>(message: string, work: (update: (message: string) => void) => Promise<T>): Promise<T> {
+  const began = performance.now();
+  let text = message;
+  let frame = 0;
+  const draw = () => process.stdout.write(`\r\x1b[2K${c.cyan(FRAMES[frame++ % FRAMES.length]!)} ${text}`);
+  const timer = tty ? setInterval(draw, 80) : undefined;
+  if (tty) draw();
+  else console.log(`→ ${message}`);
+  const took = () => c.dim(` ${((performance.now() - began) / 1000).toFixed(1)}s`);
+  try {
+    const result = await work((m) => (text = m));
+    if (timer) clearInterval(timer);
+    if (tty) process.stdout.write(`\r\x1b[2K`);
+    console.log(`${c.green("✓")} ${text}${took()}`);
+    return result;
+  } catch (e) {
+    if (timer) clearInterval(timer);
+    if (tty) process.stdout.write(`\r\x1b[2K`);
+    console.log(`${c.red("✗")} ${text}`);
+    throw e;
+  }
+}