create-archlast-forge 0.0.0-stage → 0.2.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
+# create-archlast-forge
 
-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.
+Create an archlast-forge project: a full-stack app or a backend, with the services you choose.
+
+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": "create-archlast-forge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Create an archlast-forge project: a full-stack app or a backend, with the services you choose.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/algochad/archlast-forge.git",
+    "directory": "packages/create-archlast-forge"
+  },
+  "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",
+  "bin": {
+    "create-archlast-forge": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "template"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.8.1"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./stack": "./src/stack.ts"
+  },
+  "engines": {
+    "bun": ">=1.4.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,148 @@
+import * as p from "@clack/prompts";
+import { existsSync, readdirSync } from "node:fs";
+import { basename, relative, resolve } from "node:path";
+import type { Readable, Writable } from "node:stream";
+import { scaffold } from "./scaffold";
+import { defaultServices, nameOf, parseFlags, USAGE, type Flags } from "./options";
+import { DEFAULT_SERVICES, MODES, SERVICES, type Mode, type StackService } from "./stack";
+
+/** Where prompts read and write; tests pass their own streams. */
+export interface Io {
+  input?: Readable;
+  output?: Writable;
+}
+
+export interface Answers {
+  dir: string;
+  mode: Mode;
+  services: StackService[];
+  install: boolean;
+  git: boolean;
+}
+
+/** The person pressed Ctrl-C at a prompt. */
+export class Cancelled extends Error {}
+
+const answer = <T>(value: T | symbol): T => {
+  if (p.isCancel(value)) throw new Cancelled("Cancelled");
+  return value as T;
+};
+
+const dirProblem = (dir: string) => (existsSync(resolve(dir)) && readdirSync(resolve(dir)).length ? `${dir} already has files in it. Pick an empty folder or a new name.` : undefined);
+
+/** Asks for whatever the flags left out. With `interactive` false, missing answers take their defaults. */
+export async function gather(flags: Flags, interactive: boolean, io: Io = {}): Promise<Answers> {
+  const ask = <T>(run: (o: Io) => Promise<T | symbol>): Promise<T> => run(io).then((v) => answer<T>(v));
+
+  let dir = flags.dir;
+  if (dir === undefined) {
+    if (!interactive) throw new Error("Which folder? Pass a directory: bun create archlast-forge my-app");
+    dir = await ask<string>((o) =>
+      p.text({ ...o, message: "Where should we create your project?", placeholder: "my-app", defaultValue: "my-app", validate: (v) => dirProblem(v || "my-app") }),
+    );
+  } else {
+    const problem = dirProblem(dir);
+    if (problem) throw new Error(problem);
+  }
+
+  let mode: Mode;
+  if (flags.mode) mode = flags.mode;
+  else {
+    mode = interactive
+      ? await ask<Mode>((o) =>
+          p.select<Mode>({
+            ...o,
+            message: "What are you building?",
+            initialValue: "framework",
+            options: (Object.keys(MODES) as Mode[]).map((m) => ({ value: m, label: MODES[m].label, hint: MODES[m].hint })),
+          }),
+        )
+      : "framework";
+  }
+
+  let services = flags.services;
+  if (!services) {
+    services = interactive
+      ? await ask<StackService[]>((o) =>
+          p.multiselect<StackService>({
+            ...o,
+            message: "Which services will production need? (space selects, enter confirms; none keeps SQLite, with no database container)",
+            required: false,
+            initialValues: DEFAULT_SERVICES[mode],
+            options: (Object.keys(SERVICES) as StackService[]).map((s) => ({ value: s, label: SERVICES[s].label, hint: SERVICES[s].hint })),
+          }),
+        )
+      : defaultServices(mode);
+  }
+
+  const confirm = async (given: boolean | undefined, message: string) => given ?? (interactive ? await ask<boolean>((o) => p.confirm({ ...o, message, initialValue: true })) : false);
+  const install = await confirm(flags.install, "Install dependencies with bun?");
+  const git = await confirm(flags.git, "Start a git repository?");
+  return { dir, mode, services, install, git };
+}
+
+const run = async (cmd: string[], cwd: string) => {
+  const proc = Bun.spawn(cmd, { cwd, stdout: "pipe", stderr: "pipe" });
+  const [out, err, code] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited]);
+  return { ok: code === 0, output: (err || out).trim() };
+};
+
+export function nextSteps(a: Answers, installed: boolean): string {
+  const rel = relative(process.cwd(), resolve(a.dir)) || ".";
+  const cd = rel.startsWith("..") ? resolve(a.dir) : rel; // a path that climbs out of here reads better in full
+  const lines = [cd !== "." ? `cd ${cd}` : undefined, installed ? undefined : "bun install", "bun run dev"].filter(Boolean) as string[];
+  const where = a.mode === "framework" ? "Your app: http://localhost:3000" : "Your backend: http://localhost:3000";
+  return `${lines.join("\n")}\n\n${where}\nDashboard: http://localhost:3000/_dashboard\n\nTo deploy: bun run up   (builds the image and starts the stack in compose.yaml)`;
+}
+
+export async function main(argv: string[], io: Io = {}): Promise<void> {
+  let flags: Flags;
+  try {
+    flags = parseFlags(argv);
+  } catch (e) {
+    console.error(`✗ ${(e as Error).message}\n\n${USAGE}`);
+    process.exit(1);
+  }
+  if (flags.help) return console.log(USAGE);
+  const interactive = !flags.yes && Boolean(process.stdin.isTTY && process.stdout.isTTY) && !process.env.CI;
+
+  if (interactive) p.intro(" create archlast-forge ");
+  let answers: Answers;
+  try {
+    answers = await gather(flags, interactive, io);
+  } catch (e) {
+    if (e instanceof Cancelled) {
+      p.cancel("Cancelled. Nothing was created.");
+      process.exit(130);
+    }
+    console.error(`✗ ${(e as Error).message}`);
+    process.exit(1);
+  }
+
+  const target = (() => {
+    try {
+      return scaffold(answers);
+    } catch (e) {
+      console.error(`✗ ${(e as Error).message}`);
+      return process.exit(1);
+    }
+  })();
+  p.log.success(`Created ${basename(target)} (${MODES[answers.mode].label.toLowerCase()}${answers.services.length ? `, with ${answers.services.map((s) => SERVICES[s].label).join(", ")}` : ""})`);
+
+  let installed = false;
+  if (answers.install) {
+    const spin = p.spinner();
+    spin.start("Installing dependencies");
+    const r = await run(["bun", "install"], target);
+    installed = r.ok;
+    if (r.ok) spin.stop("Installed dependencies");
+    else spin.error(`bun install failed:\n${r.output.split("\n").slice(-8).join("\n")}\nRun it again once that is fixed.`);
+  }
+  if (answers.git && !existsSync(resolve(target, ".git"))) {
+    const r = await run(["git", "init", "-q"], target);
+    if (r.ok) p.log.success("Started a git repository");
+    else p.log.warn("Couldn't start a git repository (is git installed?)");
+  }
+  p.note(nextSteps(answers, installed), "Next");
+  p.outro("Happy building.");
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env bun
+// bun create archlast-forge my-app   (or: bunx create-archlast-forge my-app, or: archlast-forge init)
+export { main } from "./cli";
+export { scaffold, VERSION, type ScaffoldOptions } from "./scaffold";
+export * from "./options";
+export * from "./stack";
+
+if (import.meta.main) {
+  const { main } = await import("./cli");
+  await main(process.argv.slice(2));
+}

package/src/options.ts

@@ -0,0 +1,63 @@
+import { basename, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { DEFAULT_SERVICES, MODES, parseServiceList, type Mode, type StackService } from "./stack";
+
+export interface Flags {
+  dir?: string;
+  mode?: Mode;
+  services?: StackService[];
+  yes: boolean;
+  install?: boolean;
+  git?: boolean;
+  help: boolean;
+}
+
+export const USAGE = `Usage: bun create archlast-forge [directory] [options]
+
+  --mode <framework|backend>   framework: a full-stack React app (server rendering, file routes, live queries)
+                               backend:   a backend container with its own database, cache and storage
+  --services <list>            postgres, redis, s3, caddy (comma separated) or "none"
+  --install / --no-install     run \`bun install\` afterwards
+  --git / --no-git             start a git repository
+  -y, --yes                    take the default for everything not given, and ask nothing
+  -h, --help
+
+Without options you are asked. Defaults: framework mode with postgres, redis, s3 and caddy;
+backend mode with postgres, redis and s3.`;
+
+export function parseFlags(argv: string[]): Flags {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      mode: { type: "string", short: "m" },
+      template: { type: "string" },
+      services: { type: "string", short: "s" },
+      install: { type: "boolean" },
+      "no-install": { type: "boolean" },
+      git: { type: "boolean" },
+      "no-git": { type: "boolean" },
+      yes: { type: "boolean", short: "y" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+  const mode = values.mode ?? values.template;
+  if (mode !== undefined && !(mode in MODES)) throw new Error(`Unknown mode "${mode}". Choose framework or backend.`);
+  const pick = (on?: boolean, off?: boolean) => (off ? false : on ? true : undefined);
+  return {
+    dir: positionals[0],
+    mode: mode as Mode | undefined,
+    services: values.services === undefined ? undefined : parseServiceList(values.services),
+    yes: Boolean(values.yes),
+    install: pick(values.install, values["no-install"]),
+    git: pick(values.git, values["no-git"]),
+    help: Boolean(values.help),
+  };
+}
+
+/** A name safe for package.json and Docker Compose: lowercase letters, digits, `-` and `_`. */
+export function nameOf(dir: string): string {
+  return basename(resolve(dir)).toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^[-_]+|[-_]+$/g, "") || "app";
+}
+
+export const defaultServices = (mode: Mode, given?: StackService[]) => given ?? DEFAULT_SERVICES[mode];

package/src/scaffold.ts

@@ -0,0 +1,57 @@
+// Writes a new project from the templates.
+import { chmodSync, cpSync, existsSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { nameOf } from "./options";
+import {
+  DOCKERIGNORE,
+  generateSecrets,
+  renderCaddyfile,
+  renderCompose,
+  renderDockerfile,
+  renderEnv,
+  type Mode,
+  type StackService,
+} from "./stack";
+
+const TEMPLATE = new URL("../template", import.meta.url).pathname;
+export const VERSION: string = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
+export interface ScaffoldOptions {
+  dir: string;
+  mode: Mode;
+  services: StackService[];
+  /** The archlast-forge version the project depends on. Defaults to this package's. */
+  version?: string;
+}
+
+/** Writes a new project into `dir` (which may exist but must be empty) and returns its absolute path. */
+export function scaffold({ dir, mode, services, version = VERSION }: ScaffoldOptions): string {
+  const target = resolve(dir);
+  if (existsSync(target) && readdirSync(target).length) throw new Error(`${target} isn't empty`);
+  const name = nameOf(target);
+  for (const part of ["base", mode]) cpSync(join(TEMPLATE, part), target, { recursive: true });
+  renameSync(join(target, "gitignore"), join(target, ".gitignore")); // npm drops .gitignore files from packages
+  if (services.includes("s3")) cpSync(join(TEMPLATE, "extras", "files.ts"), join(target, "forge", "files.ts")); // something that uses the storage
+
+  const fill = (path: string) => {
+    for (const entry of readdirSync(path)) {
+      const p = join(path, entry);
+      if (statSync(p).isDirectory()) fill(p);
+      else writeFileSync(p, readFileSync(p, "utf8").replaceAll("__NAME__", name).replaceAll("__VERSION__", version));
+    }
+  };
+  fill(target);
+
+  const write = (file: string, text: string, secret = false) => {
+    writeFileSync(join(target, file), text);
+    if (secret) chmodSync(join(target, file), 0o600);
+  };
+  write("archlast-forge.json", JSON.stringify({ mode, services }, null, 2) + "\n");
+  write("Dockerfile", renderDockerfile(version));
+  write(".dockerignore", DOCKERIGNORE);
+  write("compose.yaml", renderCompose({ name, services, version }));
+  write(".env.example", renderEnv(services));
+  write(".env", renderEnv(services, generateSecrets()), true);
+  if (services.includes("caddy")) write("Caddyfile", renderCaddyfile(services));
+  return target;
+}

package/src/stack.ts

@@ -0,0 +1,249 @@
+// What a project says about how it is built and deployed: archlast-forge.json, and the files generated from it
+// (compose.yaml, Dockerfile, .env, Caddyfile). Pure functions, so the CLI and the scaffolder share them.
+
+export type Mode = "framework" | "backend";
+
+export const MODES: Record<Mode, { label: string; hint: string }> = {
+  framework: { label: "Full-stack app", hint: "React with server rendering, file routes and live queries, served by the same container as your backend" },
+  backend: { label: "Backend only", hint: "A container with its database, cache and storage; use any frontend or none" },
+};
+
+export const SERVICES = {
+  postgres: { label: "PostgreSQL", hint: "shared database instead of a SQLite file" },
+  redis: { label: "Redis", hint: "reactivity across servers, cache and rate limits" },
+  s3: { label: "S3 storage (RustFS)", hint: "file uploads with presigned URLs" },
+  caddy: { label: "Caddy", hint: "HTTPS with automatic certificates in front of the app" },
+} as const;
+export type StackService = keyof typeof SERVICES;
+
+/** Services a mode starts with: what a production deployment needs. An app gets HTTPS too; a backend is usually put behind a proxy of its own. */
+export const DEFAULT_SERVICES: Record<Mode, StackService[]> = { framework: ["postgres", "redis", "s3", "caddy"], backend: ["postgres", "redis", "s3"] };
+
+/** archlast-forge.json */
+export interface ProjectConfig {
+  mode: Mode;
+  services: StackService[];
+}
+
+/** Validates archlast-forge.json with messages that say what to change. */
+export function parseProjectConfig(json: unknown, source = "archlast-forge.json"): ProjectConfig {
+  const bad = (why: string): never => {
+    throw new Error(`${source}: ${why}`);
+  };
+  if (typeof json !== "object" || json === null || Array.isArray(json)) return bad("expected an object like { \"mode\": \"framework\", \"services\": [] }");
+  const { mode, services = [] } = json as { mode?: unknown; services?: unknown };
+  if (mode !== "framework" && mode !== "backend") return bad(`"mode" must be "framework" or "backend" (got ${JSON.stringify(mode)})`);
+  if (!Array.isArray(services)) return bad(`"services" must be a list such as ["postgres", "redis"]`);
+  for (const s of services) if (!(s in SERVICES)) return bad(`unknown service ${JSON.stringify(s)}; choose from ${Object.keys(SERVICES).join(", ")}`);
+  return { mode, services: [...new Set(services as StackService[])] };
+}
+
+export const parseServiceList = (text: string): StackService[] => {
+  const names = text.split(",").map((s) => s.trim().toLowerCase()).filter((s) => s && s !== "none");
+  for (const n of names) if (!(n in SERVICES)) throw new Error(`Unknown service "${n}". Choose from ${Object.keys(SERVICES).join(", ")}, or "none".`);
+  return [...new Set(names as StackService[])];
+};
+
+const hex = (bytes: number) => Buffer.from(crypto.getRandomValues(new Uint8Array(bytes))).toString("hex");
+
+export interface Secrets {
+  BETTER_AUTH_SECRET: string;
+  ADMIN_KEY: string;
+  POSTGRES_PASSWORD: string;
+  S3_ACCESS_KEY: string;
+  S3_SECRET_KEY: string;
+}
+
+export const generateSecrets = (): Secrets => ({
+  BETTER_AUTH_SECRET: hex(32),
+  ADMIN_KEY: hex(24),
+  POSTGRES_PASSWORD: hex(16),
+  S3_ACCESS_KEY: `forge${hex(6)}`,
+  S3_SECRET_KEY: hex(20),
+});
+
+/** The compose file's `.env`. With no secrets it is `.env.example`: the same keys, empty. */
+export function renderEnv(services: StackService[], secrets?: Secrets): string {
+  const has = (s: StackService) => services.includes(s);
+  const v = (k: keyof Secrets) => secrets?.[k] ?? "";
+  const lines = [
+    secrets ? "# Generated by archlast-forge. It holds secrets: keep it out of git." : "# Copy to .env and fill in, or let `archlast-forge up` generate one.",
+    "",
+    "# Signs sessions. Changing it signs everybody out.",
+    `BETTER_AUTH_SECRET=${v("BETTER_AUTH_SECRET")}`,
+    "# Opens the dashboard (/_dashboard) and the CLI's data commands.",
+    `ADMIN_KEY=${v("ADMIN_KEY")}`,
+    "",
+    // DOMAIN comes first: Compose fills ${DOMAIN} only from lines above the one that uses it.
+    ...(has("caddy")
+      ? ["# Your domain; point its DNS (and s3.<domain>) at this machine.", "DOMAIN=localhost", "", "# The address people use to reach the app.", "BETTER_AUTH_URL=https://${DOMAIN}"]
+      : ["# The address people use to reach the app.", "BETTER_AUTH_URL=http://localhost:3000", "# Plain http is only for trying things out; remove this once BETTER_AUTH_URL is https.", "ALLOW_INSECURE_HTTP=1", "PORT=3000"]),
+  ];
+  if (has("postgres")) lines.push("", "POSTGRES_PASSWORD=" + v("POSTGRES_PASSWORD"));
+  if (has("s3")) lines.push("", `S3_ACCESS_KEY=${v("S3_ACCESS_KEY")}`, `S3_SECRET_KEY=${v("S3_SECRET_KEY")}`, "# Where browsers upload to and download from.", has("caddy") ? "S3_PUBLIC_ENDPOINT=https://s3.${DOMAIN}" : "S3_PUBLIC_ENDPOINT=http://localhost:9000");
+  if (has("s3") && !has("caddy")) lines.push("# The port above is published on; change both together if 9000 is taken.", "S3_PORT=9000");
+  return lines.join("\n") + "\n";
+}
+
+export function renderCaddyfile(services: StackService[]): string {
+  return `# HTTPS for the app${services.includes("s3") ? " and its file storage" : ""}. Caddy gets and renews certificates by itself once DOMAIN points here.
+{$DOMAIN:localhost} {
+	encode zstd gzip
+	reverse_proxy app:3000
+}
+${services.includes("s3") ? `
+s3.{$DOMAIN:localhost} {
+	reverse_proxy rustfs:9000
+}
+` : ""}`;
+}
+
+/** The engine image the project builds on; `ENGINE_IMAGE` overrides it. */
+export const engineImageFor = (version: string) => `ghcr.io/algochad/archlast-forge-engine:${version}`;
+
+export const renderDockerfile = (version: string) => `# Your app on the archlast-forge engine: \`archlast-forge build\` and \`docker compose up --build\` both use this.
+ARG ENGINE_IMAGE=${engineImageFor(version)}
+FROM \${ENGINE_IMAGE}
+COPY . /src
+# Installs dependencies for Linux, generates the types and, in a full-stack app, builds the browser and server bundles.
+RUN bun /engine/packages/cli/src/index.ts engine prepare
+ENV NODE_ENV=production
+`;
+
+export const DOCKERIGNORE = `node_modules
+.forge
+.git
+.env
+.env.*
+!.env.example
+data
+forge/data
+forge/node_modules
+dist
+`;
+
+/** compose.yaml: the app and the services it was asked to run, wired together. */
+export function renderCompose({ name, services, version }: { name: string; services: StackService[]; version: string }): string {
+  const has = (s: StackService) => services.includes(s);
+  const proxied = has("caddy");
+  const env: string[] = [
+    "BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET:?missing: run `archlast-forge up`, which creates .env}",
+    "ADMIN_KEY: ${ADMIN_KEY:?missing: run `archlast-forge up`, which creates .env}",
+    "BETTER_AUTH_URL: ${BETTER_AUTH_URL:-http://localhost:3000}",
+    "ALLOW_INSECURE_HTTP: ${ALLOW_INSECURE_HTTP:-}",
+    "DASHBOARD: ${DASHBOARD:-on}",
+  ];
+  if (proxied) env.push("TRUST_PROXY: \"1\"", "TRUSTED_ORIGINS: https://${DOMAIN}");
+  if (has("postgres")) env.push("DATABASE_URL: postgres://forge:${POSTGRES_PASSWORD}@postgres:5432/forge");
+  if (has("redis")) env.push("REDIS_URL: redis://redis:6379");
+  if (has("s3"))
+    env.push("S3_ENDPOINT: http://rustfs:9000", "S3_PUBLIC_ENDPOINT: ${S3_PUBLIC_ENDPOINT}", "S3_BUCKET: forge", "S3_REGION: us-east-1", "S3_ACCESS_KEY_ID: ${S3_ACCESS_KEY}", "S3_SECRET_ACCESS_KEY: ${S3_SECRET_KEY}");
+
+  // Quoted: the "missing" messages contain ": ", which YAML would take for a new key. Compose still expands ${...} inside quotes.
+  const quoted = (e: string) => `      ${e.slice(0, e.indexOf(": "))}: "${e.slice(e.indexOf(": ") + 2).replace(/^"|"$/g, "")}"`;
+
+  const deps: string[] = [];
+  if (has("postgres")) deps.push("      postgres:\n        condition: service_healthy");
+  if (has("redis")) deps.push("      redis:\n        condition: service_healthy");
+  if (has("s3")) deps.push("      rustfs-init:\n        condition: service_completed_successfully");
+
+  const parts: string[] = [];
+  parts.push(`# The production stack for ${name}. \`archlast-forge up\` builds and starts it; \`archlast-forge down\` stops it.
+# This file is yours: edit it, and archlast-forge will run what you wrote.
+name: ${name}
+
+services:
+  app:
+    build:
+      context: .
+      args:
+        ENGINE_IMAGE: \${ENGINE_IMAGE:-${engineImageFor(version)}}
+    image: ${name}:latest
+    restart: unless-stopped
+${proxied ? "" : `    ports:\n      - "\${PORT:-3000}:3000"\n`}    environment:
+${env.map(quoted).join("\n")}
+    volumes:
+      - app-data:/data${deps.length ? `\n    depends_on:\n${deps.join("\n")}` : ""}`);
+
+  if (has("postgres"))
+    parts.push(`  postgres:
+    image: postgres:17-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: forge
+      POSTGRES_PASSWORD: "\${POSTGRES_PASSWORD:?missing: run \`archlast-forge up\`, which creates .env}"
+      POSTGRES_DB: forge
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U forge -d forge"]
+      interval: 3s
+      timeout: 3s
+      retries: 20`);
+
+  if (has("redis"))
+    parts.push(`  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    command: ["redis-server", "--appendonly", "yes"]
+    volumes:
+      - redis-data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 3s
+      timeout: 3s
+      retries: 20`);
+
+  if (has("s3"))
+    parts.push(`  rustfs:
+    image: rustfs/rustfs:latest
+    restart: unless-stopped
+    command: ["/data"]
+    environment:
+      RUSTFS_ACCESS_KEY: "\${S3_ACCESS_KEY:?missing: run \`archlast-forge up\`, which creates .env}"
+      RUSTFS_SECRET_KEY: "\${S3_SECRET_KEY:?missing: run \`archlast-forge up\`, which creates .env}"
+      RUSTFS_CORS_ALLOWED_ORIGINS: "*"
+${proxied ? "" : `    ports:\n      - "\${S3_PORT:-9000}:9000"   # browsers upload and download here, through presigned URLs\n`}    volumes:
+      - rustfs-data:/data
+
+  # Creates the bucket once, then exits.
+  rustfs-init:
+    image: amazon/aws-cli
+    depends_on:
+      - rustfs
+    restart: "no"
+    environment:
+      AWS_ACCESS_KEY_ID: \${S3_ACCESS_KEY}
+      AWS_SECRET_ACCESS_KEY: \${S3_SECRET_KEY}
+      AWS_DEFAULT_REGION: us-east-1
+    entrypoint:
+      - sh
+      - -c
+      - |
+        for i in $$(seq 1 60); do
+          out=$$(aws --endpoint-url http://rustfs:9000 s3 mb s3://forge 2>&1) && exit 0
+          echo "$$out" | grep -q BucketAlready && exit 0
+          sleep 1
+        done
+        echo "$$out"; exit 1`);
+
+  if (proxied)
+    parts.push(`  caddy:
+    image: caddy:2-alpine
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
+      - "443:443/udp"
+    environment:
+      DOMAIN: \${DOMAIN:-localhost}
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - caddy-data:/data
+      - caddy-config:/config
+    depends_on:
+      - app`);
+
+  const volumes = ["app-data", ...(has("postgres") ? ["postgres-data"] : []), ...(has("redis") ? ["redis-data"] : []), ...(has("s3") ? ["rustfs-data"] : []), ...(proxied ? ["caddy-data", "caddy-config"] : [])];
+  return `${parts.join("\n\n")}\n\nvolumes:\n${volumes.map((v) => `  ${v}:`).join("\n")}\n`;
+}

package/template/backend/README.md

@@ -0,0 +1,39 @@
+# __NAME__
+
+A backend on [archlast-forge](https://github.com/algochad/archlast-forge): your schema and functions in `forge/`, running in a container next to its database, cache and storage.
+
+```bash
+bun install
+bun run dev      # the engine in Docker, reloading as you edit forge/
+bun run up       # the production stack from compose.yaml
+```
+
+## Develop
+
+`bun run dev` starts the engine with `forge/` mounted, and the services listed in `archlast-forge.json`. Edits restart only your functions; open connections stay up.
+
+- Dashboard: http://localhost:3000/_dashboard (the admin key is printed on start)
+- Try the example function: `curl localhost:3000/http/hello`
+
+Your frontend, whatever it is, talks to this server:
+
+```ts
+import { ArchlastForgeClient } from "@archlast/forge-client";
+import { api } from "./forge/_generated/api";
+
+const client = new ArchlastForgeClient({ url: "http://localhost:3000" });
+const page = await client.query(api.messages.list, { paginationOpts: { numItems: 20, cursor: null } });
+client.watch(api.messages.list, { paginationOpts: { numItems: 20, cursor: null } }, (update) => console.log(update)); // live
+```
+
+React, Vue and Svelte bindings are `@archlast/forge-react`, `@archlast/forge-vue` and `@archlast/forge-svelte`. Add your frontend's origin to `TRUSTED_ORIGINS` so its cookies and requests are accepted.
+
+## Deploy
+
+```bash
+bun run up       # builds the image, starts everything, waits until it is healthy
+bun run logs
+bun run down     # stops it; data stays in Docker volumes
+```
+
+`compose.yaml` is the stack. It is yours to edit. Secrets live in `.env`, which `init` created with fresh keys and git ignores (`up` makes one only if it's missing); `.env.example` lists the keys. To put it on a server, copy the project there and run `bun run up` (or `docker compose up -d --build`).

package/template/backend/forge/http.ts

@@ -0,0 +1,13 @@
+import { httpAction, httpRouter } from "@archlast/forge-runtime";
+
+// Plain HTTP routes, served under /http: this one answers GET /http/hello.
+// Use them for webhooks and public APIs; everything else should be a query or mutation.
+const http = httpRouter();
+
+http.route({
+  method: "GET",
+  path: "/hello",
+  handler: httpAction(async () => Response.json({ message: "Hello from __NAME__" })),
+});
+
+export default http;

package/template/backend/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "__NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "archlast-forge dev",
+    "codegen": "archlast-forge codegen",
+    "typecheck": "archlast-forge codegen && tsc -p forge --noEmit",
+    "up": "archlast-forge up",
+    "down": "archlast-forge down",
+    "logs": "archlast-forge logs"
+  },
+  "devDependencies": {
+    "@archlast/forge-cli": "^__VERSION__",
+    "typescript": "^7.0.2"
+  }
+}

package/template/base/forge/messages.ts

@@ -0,0 +1,22 @@
+import { ForgeError, mutation, paginationOptsValidator, query, v } from "@archlast/forge-runtime";
+
+/** Newest first, paginated: the client loads more as you scroll. */
+export const list = query({
+  args: { paginationOpts: paginationOptsValidator },
+  handler: (ctx, { paginationOpts }) => ctx.db.query("messages").order("desc").paginate(paginationOpts),
+});
+
+export const search = query({
+  args: { text: v.string() },
+  handler: (ctx, { text }) => ctx.db.query("messages").withSearchIndex("search_body", (q) => q.search("body", text)).take(20),
+});
+
+export const send = mutation({
+  args: { body: v.string() },
+  handler: async (ctx, { body }) => {
+    const me = await ctx.auth.getUserIdentity();
+    if (!me) throw new ForgeError("Sign in to post");
+    if (!body.trim() || body.length > 2000) throw new ForgeError("Messages are 1 to 2000 characters");
+    return ctx.db.insert("messages", { body: body.trim(), authorId: me.userId, authorName: me.name });
+  },
+});

package/template/base/forge/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "__NAME__-forge",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@archlast/forge-runtime": "^__VERSION__"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.3"
+  }
+}

package/template/base/forge/schema.ts

@@ -0,0 +1,6 @@
+import { defineSchema, defineTable, v } from "@archlast/forge-runtime";
+
+// `users` and Better Auth's tables are built in.
+export default defineSchema({
+  messages: defineTable({ body: v.string(), authorId: v.id("users"), authorName: v.string() }).searchIndex("search_body", { searchField: "body" }),
+});

package/template/base/forge/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023", "DOM"],
+    "types": ["bun"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "data"]
+}

package/template/base/gitignore

@@ -0,0 +1,7 @@
+node_modules
+dist
+.forge
+.env
+forge/data
+data
+forge/_generated/.depshash

package/template/extras/files.ts

@@ -0,0 +1,19 @@
+import { ForgeError, mutation, query, v } from "@archlast/forge-runtime";
+
+/**
+ * Step one of an upload: the browser PUTs the file to the returned `uploadUrl`, then saves `storageId`
+ * (with another mutation) wherever it belongs. In React, `useUploadFile(api.files.generateUploadUrl)` does both steps.
+ */
+export const generateUploadUrl = mutation({
+  args: { contentType: v.optional(v.string()) },
+  handler: async (ctx, args) => {
+    if (!(await ctx.auth.getUserIdentity())) throw new ForgeError("Sign in to upload files");
+    return ctx.storage.generateUploadUrl(args);
+  },
+});
+
+/** A temporary link to a stored file, or null if it no longer exists. */
+export const url = query({
+  args: { storageId: v.id("_storage") },
+  handler: (ctx, { storageId }) => ctx.storage.getUrl(storageId),
+});

package/template/framework/README.md

@@ -0,0 +1,37 @@
+# __NAME__
+
+A full-stack app on [archlast-forge](https://github.com/algochad/archlast-forge): server-rendered React pages, a typed backend and live queries, served by one container.
+
+```bash
+bun install
+bun run dev      # http://localhost:3000, reloading as you edit
+```
+
+`dev` starts the services in `archlast-forge.json` (PostgreSQL, Redis, S3 storage) in Docker. `bun run dev -- --no-docker` skips them and uses SQLite.
+
+## Where things are
+
+```
+app/
+  root.tsx           the HTML document, header and footer around every page
+  routes/            one file per page: index.tsx is /, chat.tsx is /chat, [id].tsx is /:id
+  styles.css
+forge/               your backend: schema.ts and functions
+public/              served as they are: /favicon.svg, /robots.txt
+```
+
+- A route's `loader` runs on the server for the first load and in the browser after that. `ctx.query(api.x.y, args)` fetches data and keeps it live for `useQuery`.
+- `useViewer()` is the signed-in user, already right in the server-rendered HTML.
+- Server-only packages go in `forge/package.json`; pages may import only `forge/_generated`.
+- The admin dashboard is at http://localhost:3000/_dashboard (the key is printed on start).
+
+## Deploy
+
+```bash
+bun run up       # builds the image, starts the stack from compose.yaml, waits until it is healthy
+bun run down
+```
+
+`compose.yaml` runs the app with PostgreSQL, Redis, S3 storage (RustFS) and Caddy, which serves HTTPS on ports 80 and 443. Before the first real deploy, open `.env` and set `DOMAIN` to your domain, and point its DNS and `s3.<domain>` at the machine. Caddy then gets the certificates itself.
+
+`bun run build && bun run start` runs the production bundles on this machine without Docker. `compose.yaml` is yours to edit; secrets are in `.env`, which `init` created with fresh keys and git ignores (`up` makes one only if it's missing).

package/template/framework/app/env.d.ts

@@ -0,0 +1,10 @@
+// Files the bundler understands. Add more here as you import them.
+declare module "*.css";
+declare module "*.svg" {
+  const src: string;
+  export default src;
+}
+declare module "*.png" {
+  const src: string;
+  export default src;
+}

package/template/framework/app/root.tsx

@@ -0,0 +1,88 @@
+import { isRouteErrorResponse, Link, NavLink, Outlet, useNavigate, useRouteError, useViewer } from "@archlast/forge-framework";
+import { useAuth } from "@archlast/forge-react";
+import type { ReactNode } from "react";
+import "./styles.css";
+
+/** The HTML document around every page, including error pages. */
+export function Layout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+
+/** The header and footer around a page, and around the error page, so there is always a way back. */
+function Chrome({ children }: { children: ReactNode }) {
+  const viewer = useViewer();
+  const auth = useAuth();
+  const navigate = useNavigate();
+
+  async function signOut() {
+    await auth.signOut();
+    await navigate("/");
+  }
+
+  return (
+    <>
+      <header className="site-header">
+        <div className="container">
+          <Link to="/" className="brand">
+            <img src="/favicon.svg" alt="" />
+            __NAME__
+          </Link>
+          <nav className="site-nav" aria-label="Main">
+            <NavLink to="/" end>Home</NavLink>
+            <NavLink to="/chat">Chat</NavLink>
+          </nav>
+          {viewer ? (
+            <div className="who">
+              <span className="avatar" aria-hidden>{viewer.name.slice(0, 1).toUpperCase()}</span>
+              <span>{viewer.name}</span>
+              <button className="btn small" onClick={signOut}>Sign out</button>
+            </div>
+          ) : (
+            <Link className="btn small primary" to="/sign-in">Sign in</Link>
+          )}
+        </div>
+      </header>
+      <div className="page">{children}</div>
+      <footer className="site-footer">
+        <div className="container">Built with archlast-forge · edit <code>app/root.tsx</code> to change this page</div>
+      </footer>
+    </>
+  );
+}
+
+export default function Root() {
+  return (
+    <Chrome>
+      <Outlet />
+    </Chrome>
+  );
+}
+
+/** Shown for 404s and for errors thrown by loaders and components. */
+export function ErrorBoundary() {
+  const error = useRouteError();
+  const status = isRouteErrorResponse(error) ? error.status : 500;
+  const message = status === 404 ? "That page doesn't exist." : isRouteErrorResponse(error) ? String(error.data || error.statusText) : error instanceof Error ? error.message : "Something went wrong.";
+  return (
+    <Chrome>
+      <main className="container problem">
+        <title>{status === 404 ? "Page not found" : "Something went wrong"}</title>
+        <p className="code">{status}</p>
+        <h1>{status === 404 ? "Page not found" : "Something went wrong"}</h1>
+        <p className="lead">{message}</p>
+        <p>
+          <Link className="btn primary" to="/">Go home</Link>
+        </p>
+      </main>
+    </Chrome>
+  );
+}

package/template/framework/app/routes/chat.tsx

@@ -0,0 +1,69 @@
+import { redirect, useViewer, type LoaderArgs } from "@archlast/forge-framework";
+import { ForgeError, useMutation, usePaginatedQuery } from "@archlast/forge-react";
+import { useEffect, useRef, useState, type FormEvent } from "react";
+import { api } from "../../forge/_generated/api";
+
+const PAGE = 30;
+
+// Runs on the server for the first load and in the browser for later visits. The messages it fetches are kept in the live cache,
+// so the list below has its data on first render and then stays current.
+export const loader = async ({ ctx }: LoaderArgs) => {
+  if (!(await ctx.viewer())) throw redirect("/sign-in");
+  await ctx.query(api.messages.list, { paginationOpts: { numItems: PAGE, cursor: null } });
+  return null;
+};
+
+export default function Chat() {
+  const viewer = useViewer();
+  const { results, status, loadMore } = usePaginatedQuery(api.messages.list, {}, { initialNumItems: PAGE });
+  const send = useMutation(api.messages.send);
+  const [body, setBody] = useState("");
+  const [error, setError] = useState<string>();
+  const end = useRef<HTMLLIElement>(null);
+  const messages = [...results].reverse(); // the query is newest first; a chat reads oldest first
+
+  useEffect(() => {
+    end.current?.scrollIntoView({ block: "end" }); // not returned: in current browsers it returns a Promise, which an effect must not
+  }, [messages.length]);
+
+  async function submit(e: FormEvent) {
+    e.preventDefault();
+    if (!body.trim()) return;
+    setError(undefined);
+    try {
+      await send({ body });
+      setBody("");
+    } catch (err) {
+      setError(err instanceof ForgeError || err instanceof Error ? err.message : "Couldn't send that");
+    }
+  }
+
+  return (
+    <main className="container">
+      <title>Chat</title>
+      <h1>Chat</h1>
+      <section className="card chat" aria-label="Messages">
+        <ul className="chat-log">
+          {status === "CanLoadMore" && (
+            <li className="more">
+              <button className="btn small" onClick={() => loadMore(PAGE)}>Load earlier messages</button>
+            </li>
+          )}
+          {messages.length === 0 && <li className="chat-empty">No messages yet. Say hello, then open this page in another window.</li>}
+          {messages.map((m) => (
+            <li key={m._id} className={`msg${m.authorId === viewer?.userId ? " mine" : ""}`}>
+              <small>{m.authorName}</small>
+              <p>{m.body}</p>
+            </li>
+          ))}
+          <li ref={end} aria-hidden />
+        </ul>
+        <form className="chat-form" onSubmit={submit}>
+          <input type="text" value={body} onChange={(e) => setBody(e.target.value)} placeholder="Write a message" aria-label="Message" maxLength={2000} autoComplete="off" />
+          <button className="btn primary" disabled={!body.trim()}>Send</button>
+        </form>
+        {error && <p className="error" role="alert" style={{ padding: "0 1rem" }}>{error}</p>}
+      </section>
+    </main>
+  );
+}

package/template/framework/app/routes/index.tsx

@@ -0,0 +1,37 @@
+import { Link, useViewer } from "@archlast/forge-framework";
+
+export default function Home() {
+  const viewer = useViewer();
+  return (
+    <main className="container hero">
+      <title>__NAME__</title>
+      <p className="eyebrow">archlast-forge</p>
+      <h1>Realtime. Full-stack. One deploy.</h1>
+      <p className="lead">
+        Server-rendered React, a typed backend and live queries in a single container. Edit <code>app/routes/index.tsx</code> and save: the page reloads by itself.
+      </p>
+      <div className="actions">
+        {viewer ? (
+          <Link className="btn primary" to="/chat">Open the chat</Link>
+        ) : (
+          <Link className="btn primary" to="/sign-in">Get started</Link>
+        )}
+        <a className="btn" href="https://github.com/algochad/archlast-forge">Read the docs</a>
+      </div>
+      <ul className="features">
+        <li className="card">
+          <h3>Rendered on the server</h3>
+          <p>Every page arrives as HTML with its data already in it, then the browser takes over without a flicker.</p>
+        </li>
+        <li className="card">
+          <h3>Live by default</h3>
+          <p>A query in a component stays current. Open the chat in two windows and watch both update.</p>
+        </li>
+        <li className="card">
+          <h3>One container</h3>
+          <p>Pages, API, auth, files and the dashboard ship together. <code>archlast-forge up</code> starts the lot.</p>
+        </li>
+      </ul>
+    </main>
+  );
+}

package/template/framework/app/routes/sign-in.tsx

@@ -0,0 +1,60 @@
+import { redirect, useNavigate, type LoaderArgs } from "@archlast/forge-framework";
+import { useAuth } from "@archlast/forge-react";
+import { useState, type FormEvent } from "react";
+
+export const loader = async ({ ctx }: LoaderArgs) => {
+  if (await ctx.viewer()) throw redirect("/chat");
+  return null;
+};
+
+export default function SignIn() {
+  const auth = useAuth();
+  const navigate = useNavigate();
+  const [creating, setCreating] = useState(false);
+  const [error, setError] = useState<string>();
+  const [busy, setBusy] = useState(false);
+
+  async function submit(e: FormEvent<HTMLFormElement>) {
+    e.preventDefault();
+    const form = new FormData(e.currentTarget);
+    const email = String(form.get("email"));
+    const password = String(form.get("password"));
+    setBusy(true);
+    setError(undefined);
+    const res = creating
+      ? await auth.signUp.email({ email, password, name: String(form.get("name") || email.split("@")[0]) })
+      : await auth.signIn.email({ email, password });
+    setBusy(false);
+    if (res.error) return setError(res.error.message ?? "That didn't work");
+    await navigate("/chat");
+  }
+
+  return (
+    <main className="narrow form-card card">
+      <title>{creating ? "Create account" : "Sign in"}</title>
+      <h1>{creating ? "Create your account" : "Welcome back"}</h1>
+      <form onSubmit={submit}>
+        {creating && (
+          <div className="field">
+            <label htmlFor="name">Name</label>
+            <input id="name" name="name" type="text" autoComplete="name" />
+          </div>
+        )}
+        <div className="field">
+          <label htmlFor="email">Email</label>
+          <input id="email" name="email" type="email" autoComplete="email" required />
+        </div>
+        <div className="field">
+          <label htmlFor="password">Password</label>
+          <input id="password" name="password" type="password" autoComplete={creating ? "new-password" : "current-password"} minLength={8} required />
+        </div>
+        {error && <p className="error" role="alert">{error}</p>}
+        <button className="btn primary" style={{ width: "100%" }} disabled={busy}>{busy ? "One moment…" : creating ? "Create account" : "Sign in"}</button>
+      </form>
+      <p className="switch">
+        {creating ? "Already have an account? " : "New here? "}
+        <button type="button" onClick={() => (setCreating(!creating), setError(undefined))}>{creating ? "Sign in" : "Create an account"}</button>
+      </p>
+    </main>
+  );
+}

package/template/framework/app/styles.css

@@ -0,0 +1,96 @@
+:root {
+  color-scheme: light dark;
+  --bg: #fafaf9;
+  --fg: #1c1917;
+  --muted: #78716c;
+  --line: #e7e5e4;
+  --card: #ffffff;
+  --accent: #4f46e5;
+  --accent-fg: #ffffff;
+  --accent-soft: #eef2ff;
+  --danger: #dc2626;
+  --radius: 14px;
+  --font: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  --mono: ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #0c0a09;
+    --fg: #fafaf9;
+    --muted: #a8a29e;
+    --line: #292524;
+    --card: #1c1917;
+    --accent: #818cf8;
+    --accent-fg: #0c0a09;
+    --accent-soft: #1e1b4b;
+    --danger: #f87171;
+  }
+}
+
+* { box-sizing: border-box; }
+html { -webkit-text-size-adjust: 100%; }
+body { margin: 0; min-height: 100dvh; display: flex; flex-direction: column; background: var(--bg); color: var(--fg); font: 16px/1.6 var(--font); }
+a { color: var(--accent); }
+h1, h2, h3 { line-height: 1.15; letter-spacing: -0.02em; margin: 0 0 0.5em; }
+h1 { font-size: clamp(2rem, 5vw, 3.25rem); }
+code { font-family: var(--mono); font-size: 0.9em; background: var(--accent-soft); padding: 0.1em 0.4em; border-radius: 6px; }
+:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+
+.container { width: min(100% - 2rem, 64rem); margin-inline: auto; }
+.narrow { width: min(100% - 2rem, 26rem); margin-inline: auto; }
+.page { flex: 1; padding-block: 2.5rem; }
+
+.site-header { border-bottom: 1px solid var(--line); background: color-mix(in srgb, var(--bg) 85%, transparent); backdrop-filter: blur(8px); position: sticky; top: 0; z-index: 10; }
+.site-header .container { display: flex; align-items: center; gap: 1.25rem; min-height: 3.5rem; }
+.brand { display: inline-flex; align-items: center; gap: 0.6rem; font-weight: 700; color: var(--fg); text-decoration: none; }
+.brand img { width: 1.6rem; height: 1.6rem; }
+.site-nav { display: flex; gap: 0.25rem; flex: 1; }
+.site-nav a { color: var(--muted); text-decoration: none; padding: 0.35rem 0.7rem; border-radius: 8px; font-size: 0.95rem; }
+.site-nav a:hover { color: var(--fg); background: var(--accent-soft); }
+.site-nav a[aria-current="page"] { color: var(--fg); font-weight: 600; }
+.who { display: flex; align-items: center; gap: 0.6rem; font-size: 0.9rem; color: var(--muted); }
+.avatar { display: grid; place-items: center; width: 1.9rem; height: 1.9rem; border-radius: 50%; background: var(--accent); color: var(--accent-fg); font-weight: 700; font-size: 0.85rem; }
+
+.btn { display: inline-flex; align-items: center; justify-content: center; gap: 0.4rem; font: inherit; font-weight: 600; padding: 0.55rem 1.1rem; border-radius: 10px; border: 1px solid var(--line); background: var(--card); color: var(--fg); cursor: pointer; text-decoration: none; transition: transform 0.05s, background 0.15s; }
+.btn:hover { background: var(--accent-soft); }
+.btn:active { transform: translateY(1px); }
+.btn.primary { background: var(--accent); border-color: var(--accent); color: var(--accent-fg); }
+.btn.primary:hover { filter: brightness(1.08); }
+.btn.small { padding: 0.3rem 0.7rem; font-size: 0.85rem; }
+.btn:disabled { opacity: 0.55; cursor: not-allowed; }
+
+.hero { padding-block: 3rem 2rem; }
+.eyebrow { text-transform: uppercase; letter-spacing: 0.12em; font-size: 0.78rem; font-weight: 700; color: var(--accent); margin: 0 0 1rem; }
+.lead { font-size: 1.2rem; color: var(--muted); max-width: 42rem; }
+.actions { display: flex; gap: 0.75rem; flex-wrap: wrap; margin-block: 1.75rem 3rem; }
+.features { display: grid; grid-template-columns: repeat(auto-fit, minmax(15rem, 1fr)); gap: 1rem; list-style: none; padding: 0; margin: 0; }
+.card { background: var(--card); border: 1px solid var(--line); border-radius: var(--radius); padding: 1.25rem; }
+.features h3 { font-size: 1.05rem; margin-bottom: 0.3rem; }
+.features p { margin: 0; color: var(--muted); font-size: 0.95rem; }
+
+.form-card { margin-top: 4vh; }
+.form-card h1 { font-size: 1.6rem; }
+.field { display: grid; gap: 0.3rem; margin-bottom: 1rem; }
+.field label { font-size: 0.85rem; font-weight: 600; }
+input[type="text"], input[type="email"], input[type="password"] { font: inherit; padding: 0.6rem 0.8rem; border-radius: 10px; border: 1px solid var(--line); background: var(--bg); color: inherit; width: 100%; }
+.switch { margin: 1rem 0 0; text-align: center; color: var(--muted); font-size: 0.9rem; }
+.switch button { all: unset; color: var(--accent); cursor: pointer; text-decoration: underline; }
+.error { color: var(--danger); font-size: 0.9rem; margin: 0 0 1rem; }
+
+.chat { display: flex; flex-direction: column; height: min(70dvh, 40rem); padding: 0; overflow: hidden; }
+.chat-log { flex: 1; overflow-y: auto; padding: 1rem; display: flex; flex-direction: column; gap: 0.6rem; list-style: none; margin: 0; }
+.chat-empty { margin: auto; color: var(--muted); text-align: center; }
+.msg { max-width: 80%; padding: 0.55rem 0.85rem; border-radius: 14px; background: var(--accent-soft); align-self: flex-start; }
+.msg.mine { align-self: flex-end; background: var(--accent); color: var(--accent-fg); }
+.msg small { display: block; opacity: 0.7; font-size: 0.75rem; margin-bottom: 0.1rem; }
+.msg p { margin: 0; overflow-wrap: anywhere; }
+.chat-form { display: flex; gap: 0.6rem; padding: 0.75rem; border-top: 1px solid var(--line); }
+.chat-form input { flex: 1; }
+.more { text-align: center; }
+
+.site-footer { border-top: 1px solid var(--line); color: var(--muted); font-size: 0.85rem; padding-block: 1.25rem; }
+.problem { text-align: center; padding-block: 8vh; }
+.problem .lead { margin-inline: auto; }
+.problem .code { font-size: clamp(3rem, 12vw, 6rem); font-weight: 800; color: var(--accent); line-height: 1; margin: 0; }
+.problem pre { text-align: left; background: var(--card); border: 1px solid var(--line); border-radius: 10px; padding: 1rem; overflow: auto; font: 0.8rem/1.5 var(--mono); }

package/template/framework/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "__NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "archlast-forge dev",
+    "build": "archlast-forge build --no-docker",
+    "start": "archlast-forge start --no-docker",
+    "codegen": "archlast-forge codegen",
+    "typecheck": "archlast-forge codegen && tsc --noEmit",
+    "up": "archlast-forge up",
+    "down": "archlast-forge down"
+  },
+  "dependencies": {
+    "@archlast/forge-framework": "^__VERSION__",
+    "@archlast/forge-react": "^__VERSION__",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1"
+  },
+  "devDependencies": {
+    "@archlast/forge-cli": "^__VERSION__",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "typescript": "^7.0.2"
+  }
+}

package/template/framework/public/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><rect width="64" height="64" rx="16" fill="#4f46e5"/><path d="M20 44V20h10c6 0 10 3 10 8s-4 8-10 8h-4v8z" fill="#fff"/><circle cx="46" cy="44" r="4" fill="#a5b4fc"/></svg>

package/template/framework/public/robots.txt

@@ -0,0 +1,2 @@
+User-agent: *
+Allow: /

package/template/framework/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "types": []
+  },
+  "include": ["app"]
+}