create-strata 1.0.1

package/dist/templates/.env.example

@@ -0,0 +1,22 @@
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/{{PROJECT_NAME}}
+PORT=3000
+APP_URL=http://localhost:3000
+APP_ENV=local
+APP_NAME={{PROJECT_NAME}}
+# Cookie/Redis namespace. Unset defaults to `strata`.
+# APP_KEY_PREFIX={{PROJECT_NAME}}
+FRONTEND_MODE=api
+# SPA_PREFIX=/app
+TENANCY_DRIVER=none
+
+# Required in production when FRONTEND_MODE=server-htmx or hybrid
+# SESSION_SECRET=
+
+# Set only behind a trusted reverse proxy
+# TRUST_FORWARDED_FOR=true
+
+# Required in production to expose GET /metrics
+# METRICS_TOKEN=
+
+# Production should set FEATURE_PUBLIC_READS=false
+# FEATURE_PUBLIC_READS=false

package/dist/templates/docker-compose.yml

@@ -0,0 +1,14 @@
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: {{PROJECT_NAME}}
+    ports:
+      - "5432:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+
+volumes:
+  pgdata:

package/dist/templates/overlays/api/docs/API.md

@@ -0,0 +1,49 @@
+# API-only scaffold
+
+This scaffold sets `FRONTEND_MODE=api`: no server-rendered views beyond the welcome page, and no SPA assets.
+
+## What exists after migrating
+
+- `GET /health` returns plain text `ok`, or `degraded` when the database ping fails.
+- `GET /` returns the welcome page.
+- A `notes` table, with no routes on it yet.
+
+Login endpoints depend on the auth layer you chose. Token auth adds `POST /api/v1/auth/login` and `GET /api/v1/auth/me`; JWT auth adds `POST /api/auth/token`; header auth adds none and expects `x-authenticated-user-id` for local work only.
+
+There is no CRUD endpoint for `notes`. Adding your own routes is the first thing you do.
+
+## Adding a route
+
+```typescript
+// src/modules/notes/index.ts
+import type { AppModule } from "@getstrata/bootstrap/contracts";
+import { jsonResponse } from "@getstrata/core/http/response";
+import { getSql } from "../../bootstrap/database.ts";
+
+const notesModule: AppModule = {
+  name: "notes",
+  order: 2,
+  routes({ kernel }) {
+    return {
+      "/api/v1/notes": kernel.wrap("api", async () => {
+        const rows = await getSql().unsafe<{ id: number; body: string }>(
+          "SELECT id, body FROM notes ORDER BY id DESC",
+        );
+        return jsonResponse({ data: rows });
+      }),
+    };
+  },
+};
+
+export default notesModule;
+```
+
+Import from `@getstrata/core/...` subpaths rather than the package root, so singleton state such as the database pool stays shared.
+
+## Generating an app instead
+
+```bash
+bunx create-strata my-app --frontend api --yes
+```
+
+A generated app writes its own `docs/API.md` listing only the routes its layers actually serve.

package/dist/templates/overlays/server-htmx/public/assets/app.css

@@ -0,0 +1,89 @@
+:root {
+  color-scheme: light;
+  font-family: system-ui, sans-serif;
+}
+
+body {
+  margin: 0;
+  background: #f6f7fb;
+  color: #1f2937;
+}
+
+.site-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 1rem 1.5rem;
+  background: #111827;
+  color: #f9fafb;
+}
+
+.site-header a {
+  color: inherit;
+  text-decoration: none;
+  margin-right: 1rem;
+}
+
+.site-main {
+  max-width: 960px;
+  margin: 0 auto;
+  padding: 1.5rem;
+}
+
+.page-header,
+.create-form,
+.card {
+  background: #fff;
+  border-radius: 0.75rem;
+  padding: 1.25rem;
+  margin-bottom: 1rem;
+  box-shadow: 0 1px 2px rgb(15 23 42 / 0.08);
+}
+
+.stack-form {
+  display: grid;
+  gap: 0.75rem;
+}
+
+.flash {
+  padding: 0.75rem 1rem;
+  border-radius: 0.5rem;
+  margin-bottom: 1rem;
+}
+
+.flash-success {
+  background: #ecfdf5;
+  color: #065f46;
+}
+
+.flash-error {
+  background: #fef2f2;
+  color: #991b1b;
+}
+
+.form-errors {
+  background: #fef2f2;
+  color: #991b1b;
+  padding: 0.75rem 1rem;
+  border-radius: 0.5rem;
+}
+
+.inline-form {
+  display: inline;
+}
+
+.hint {
+  color: #6b7280;
+}
+
+table {
+  width: 100%;
+  border-collapse: collapse;
+}
+
+th,
+td {
+  padding: 0.5rem;
+  border-bottom: 1px solid #e5e7eb;
+  text-align: left;
+}

package/dist/templates/overlays/server-htmx/resources/views/errors/error.eta

@@ -0,0 +1,14 @@
+<section class="page-header">
+  <h1><%= it.title ?? "Something went wrong" %></h1>
+  <p><%= it.message ?? "Please try again." %></p>
+  <% if (it.errors) { %>
+  <ul class="error-list">
+    <% for (const [field, messages] of Object.entries(it.errors)) { %>
+      <% for (const message of messages) { %>
+    <li><%= field %>: <%= message %></li>
+      <% } %>
+    <% } %>
+  </ul>
+  <p><a href="javascript:history.back()">Go back</a></p>
+  <% } %>
+</section>

package/dist/templates/overlays/server-htmx/resources/views/errors/forbidden.eta

@@ -0,0 +1,4 @@
+<section class="page-header">
+  <h1><%= it.title ?? "Forbidden" %></h1>
+  <p><%= it.message ?? "You do not have permission to view this page." %></p>
+</section>

package/dist/templates/overlays/server-htmx/resources/views/errors/not-found.eta

@@ -0,0 +1,4 @@
+<section class="page-header">
+  <h1><%= it.title ?? "Not Found" %></h1>
+  <p><%= it.message ?? "The page you requested was not found." %></p>
+</section>

package/dist/templates/overlays/server-htmx/resources/views/layouts/app.eta

@@ -0,0 +1,34 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title><%= it.title ?? "Strata" %></title>
+    <meta name="csrf-token" content="<%= it.csrfToken ?? "" %>" />
+    <meta name="htmx-config" content='{"inlineStyleNonce":"<%= it.cspNonce ?? "" %>"}' />
+    <script src="https://unpkg.com/htmx.org@2.0.4"></script>
+    <script nonce="<%= it.cspNonce ?? "" %>">
+      document.addEventListener("htmx:configRequest", (event) => {
+        const token = document.querySelector('meta[name="csrf-token"]')?.getAttribute("content");
+        if (token) {
+          event.detail.headers["X-CSRF-Token"] = token;
+        }
+      });
+    </script>
+    <link rel="stylesheet" href="/assets/app.css" />
+  </head>
+  <body>
+    <header class="site-header">
+      <a href="/organizations" class="brand">Strata</a>
+      <nav>
+        <a href="/organizations">Organizations</a>
+      </nav>
+    </header>
+    <main class="site-main">
+      <% if (it.flash) { %>
+      <div class="flash flash-<%= it.flash.level %>" role="status"><%= it.flash.message %></div>
+      <% } %>
+      <%~ it.body %>
+    </main>
+  </body>
+</html>

package/dist/templates/overlays/server-htmx/resources/views/organizations/_table.eta

@@ -0,0 +1,23 @@
+<table>
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Slug</th>
+      <th></th>
+    </tr>
+  </thead>
+  <tbody>
+    <% for (const organization of it.organizations ?? []) { %>
+    <tr>
+      <td><%= organization.name %></td>
+      <td><code><%= organization.slug %></code></td>
+      <td>
+        <form method="post" action="/organizations/<%= organization.id %>/delete" class="inline-form">
+          <input type="hidden" name="_token" value="<%= it.csrfToken ?? "" %>" />
+          <button type="submit">Delete</button>
+        </form>
+      </td>
+    </tr>
+    <% } %>
+  </tbody>
+</table>

package/dist/templates/overlays/server-htmx/resources/views/organizations/index.eta

@@ -0,0 +1,37 @@
+<section class="page-header">
+  <h1>Organizations</h1>
+  <p class="hint">Sample HTMX CRUD scaffold with CSRF and flash messages.</p>
+</section>
+
+<section class="create-form">
+  <h2>Create organization</h2>
+
+  <% if (Object.keys(it.errors ?? {}).length > 0) { %>
+  <div class="form-errors" role="alert">
+    <% for (const [field, messages] of Object.entries(it.errors)) { %>
+      <% for (const message of messages) { %>
+        <p><strong><%= field %></strong>: <%= message %></p>
+      <% } %>
+    <% } %>
+  </div>
+  <% } %>
+
+  <form method="post" action="/organizations" class="stack-form">
+    <input type="hidden" name="_token" value="<%= it.csrfToken ?? "" %>" />
+    <label>
+      Name
+      <input type="text" name="name" value="<%= it.old?.name ?? '' %>" required />
+    </label>
+
+    <label>
+      Slug
+      <input type="text" name="slug" value="<%= it.old?.slug ?? '' %>" required />
+    </label>
+
+    <button type="submit">Create</button>
+  </form>
+</section>
+
+<div id="org-table">
+  <%~ include('./_table', it) %>
+</div>

package/dist/templates/overlays/server-htmx/resources/views/pages/home.eta

@@ -0,0 +1,4 @@
+<section class="page-header">
+  <h1>Welcome</h1>
+  <p class="hint">Replace this page by adding modules with webRoutes().</p>
+</section>

package/dist/templates/overlays/server-htmx/resources/views/partials/_flash.eta

@@ -0,0 +1,3 @@
+<% if (it.flash) { %>
+<div class="flash flash-<%= it.flash.level %>" role="status"><%= it.flash.message %></div>
+<% } %>

package/dist/templates/overlays/spa-react/frontend/build.ts

@@ -0,0 +1,17 @@
+const result = await Bun.build({
+  entrypoints: ["./index.html"],
+  outdir: "./dist",
+  target: "browser",
+  minify: true,
+  publicPath: "/app/",
+});
+
+if (!result.success) {
+  for (const log of result.logs) {
+    console.error(log);
+  }
+
+  throw new Error("Frontend build failed.");
+}
+
+console.log(`Built ${result.outputs.length} frontend files into dist/`);

package/dist/templates/overlays/spa-react/frontend/bun-env.d.ts

@@ -0,0 +1,4 @@
+declare module "*.html" {
+  const value: import("bun").HTMLBundle;
+  export default value;
+}

package/dist/templates/overlays/spa-react/frontend/bun.lock

@@ -0,0 +1,51 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "strata-frontend",
+      "dependencies": {
+        "react": "^19.1.1",
+        "react-dom": "^19.1.1",
+        "react-router-dom": "^7.8.0",
+      },
+      "devDependencies": {
+        "@types/bun": "^1.4.0",
+        "@types/react": "^19.1.10",
+        "@types/react-dom": "^19.1.7",
+        "typescript": "^5.9.2",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.4.0", "", { "dependencies": { "bun-types": "1.4.0" } }, "sha512-K+lZULY23vRgK/CfTjFIV+tyifaNdSMlPh9j+6mQ/cLfpOznLyAuzgV/JQysyECpkBQLVMSyvjlr2fBUSA9wFQ=="],
+
+    "@types/node": ["@types/node@26.2.0", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-5IviulTZeRNp2vAJ514cc/HUlY5nZ9fCbq9DMyC52BrhFZACo3nI0R7qBxhQmo/d27NFe96ur/b7Wwxklda+kg=="],
+
+    "@types/react": ["@types/react@19.2.18", "", { "dependencies": { "csstype": "^3.2.2" } }, "sha512-AnzbBERsrLKtk2XSfTbYRLjQPdy116Sty4q+T+Bp3IC4l6jNBvreVPAHmpq9qhXQM7CXZPjLVmGMw9sy+hxQ3w=="],
+
+    "@types/react-dom": ["@types/react-dom@19.2.4", "", { "peerDependencies": { "@types/react": "^19.2.0" } }, "sha512-Bsc+QHgp+P/F02XDzNCY9jnZNCUuLki36KT7VKrTXXLdHf+vHMNZnW1rVu5DNW/rCK+fya3DATySbLM4yhtKUw=="],
+
+    "bun-types": ["bun-types@1.4.0", "", { "dependencies": { "@types/node": "*" } }, "sha512-iIKw23BspnQQYd3prITOBxeUsxBHnwzX6YJfGMuNOZzeNcMmVqzIIVGRm1l69ogaPQmb4wB6BN8mA5bE9YuC5Q=="],
+
+    "cookie": ["cookie@1.1.1", "", {}, "sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ=="],
+
+    "csstype": ["csstype@3.2.3", "", {}, "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ=="],
+
+    "react": ["react@19.2.8", "", {}, "sha512-PWaYA1L/q9u2u7xYQi+Y3L3Yfnie7XyLeaJICV1MGD6LprsBxcAqGjYyr0eY3p+QdsA+x/Irkt4Qif8D63+Sbw=="],
+
+    "react-dom": ["react-dom@19.2.8", "", { "dependencies": { "scheduler": "^0.27.0" }, "peerDependencies": { "react": "^19.2.8" } }, "sha512-rVprimfGBG3DR+Tq0IQG2DT5PxKth1WIGDmj5yPmlzr4YBe7uyE+Du4oVqTDXZSHGGGXRtTJEGSSePyQCMBglQ=="],
+
+    "react-router": ["react-router@7.18.2", "", { "dependencies": { "cookie": "^1.0.1", "set-cookie-parser": "^2.6.0" }, "peerDependencies": { "react": ">=18", "react-dom": ">=18" }, "optionalPeers": ["react-dom"] }, "sha512-aUVMjFm3GAPTTZL7oYr5E7ETiqfQCHRLH+B+5afnICvf0r7kkK4eR6SMuwbSTJw/7t+12khT/Kahij49fqOCIg=="],
+
+    "react-router-dom": ["react-router-dom@7.18.2", "", { "dependencies": { "react-router": "7.18.2" }, "peerDependencies": { "react": ">=18", "react-dom": ">=18" } }, "sha512-AIKJ/jgGlFb3EbfCXk5Gzshiwt+l3mqbCrNjmEWMMjqQxNJ3svBa6bgzFyCC2Sw3RA0VWF1kg3uQf2OFhxb8hw=="],
+
+    "scheduler": ["scheduler@0.27.0", "", {}, "sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q=="],
+
+    "set-cookie-parser": ["set-cookie-parser@2.7.2", "", {}, "sha512-oeM1lpU/UvhTxw+g3cIfxXHyJRc/uidd3yK1P242gzHds0udQBYzs3y8j4gCCW+ZJ7ad0yctld8RYO+bdurlvw=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],
+  }
+}

package/dist/templates/overlays/spa-react/frontend/dev-server.ts

@@ -0,0 +1,66 @@
+import { join } from "node:path";
+import index from "./index.html";
+
+const API_ORIGIN = process.env.API_ORIGIN ?? "http://localhost:3000";
+const PORT = Number(process.env.FRONTEND_PORT ?? "5173");
+const PREVIEW = process.argv.includes("--preview");
+const DIST_DIRECTORY = join(import.meta.dir, "dist");
+
+async function proxyToApi(request: Request): Promise<Response> {
+  const incoming = new URL(request.url);
+  const target = new URL(`${incoming.pathname}${incoming.search}`, API_ORIGIN);
+  const headers = new Headers(request.headers);
+  headers.delete("host");
+
+  return fetch(target, {
+    method: request.method,
+    headers,
+    body: request.body,
+    redirect: "manual",
+    verbose: false,
+  });
+}
+
+async function servePreview(request: Request): Promise<Response> {
+  const pathname = new URL(request.url).pathname;
+  const relativePath = pathname.replace(/^\/app\/?/, "");
+  const asset = Bun.file(join(DIST_DIRECTORY, relativePath));
+
+  if (relativePath.length > 0 && (await asset.exists())) {
+    return new Response(asset);
+  }
+
+  const indexFile = Bun.file(join(DIST_DIRECTORY, "index.html"));
+
+  if (await indexFile.exists()) {
+    return new Response(indexFile, {
+      headers: { "content-type": "text/html; charset=utf-8" },
+    });
+  }
+
+  return new Response("SPA build not found. Run `bun run build`.", { status: 503 });
+}
+
+const server = Bun.serve({
+  port: PORT,
+  development: PREVIEW
+    ? false
+    : {
+        hmr: true,
+        console: true,
+      },
+  routes: {
+    "/api/*": proxyToApi,
+    "/health": proxyToApi,
+    "/ready": proxyToApi,
+    "/app": PREVIEW ? servePreview : index,
+    "/app/": PREVIEW ? servePreview : index,
+    "/app/*": PREVIEW ? servePreview : index,
+  },
+});
+
+console.log(
+  PREVIEW
+    ? `SPA preview on ${server.url}app/ (proxy ${API_ORIGIN})`
+    : `SPA dev server on ${server.url}app/ (proxy ${API_ORIGIN})`,
+);

package/dist/templates/overlays/spa-react/frontend/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Strata</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./src/main.tsx"></script>
+  </body>
+</html>

package/dist/templates/overlays/spa-react/frontend/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "strata-frontend",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun --hot dev-server.ts",
+    "build": "bun run build.ts",
+    "preview": "bun run build.ts && bun dev-server.ts --preview"
+  },
+  "dependencies": {
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "react-router-dom": "^7.8.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.0",
+    "@types/react": "^19.1.10",
+    "@types/react-dom": "^19.1.7",
+    "typescript": "^5.9.2"
+  }
+}

package/dist/templates/overlays/spa-react/frontend/src/App.tsx

@@ -0,0 +1,59 @@
+import { Link, Navigate, Route, Routes } from "react-router-dom";
+import { useAuth } from "./auth/AuthContext";
+import HomePage from "./pages/HomePage";
+import LoginPage from "./pages/LoginPage";
+import NotFoundPage from "./pages/NotFoundPage";
+
+function ProtectedRoute({ children }: { children: React.ReactNode }) {
+  const { token, loading } = useAuth();
+
+  if (loading) {
+    return <p className="hint">Loading session…</p>;
+  }
+
+  if (!token) {
+    return <Navigate to="/login" replace />;
+  }
+
+  return children;
+}
+
+function AppShell() {
+  const { user, logout } = useAuth();
+
+  return (
+    <div className="app-shell">
+      <header className="site-header">
+        <strong>Strata SPA</strong>
+        <nav>
+          <Link to="/">Home</Link>
+          {user ? (
+            <>
+              <span className="hint">{user.email}</span>
+              <button type="button" className="secondary" onClick={logout}>
+                Sign out
+              </button>
+            </>
+          ) : null}
+        </nav>
+      </header>
+
+      <Routes>
+        <Route path="/login" element={<LoginPage />} />
+        <Route
+          path="/"
+          element={
+            <ProtectedRoute>
+              <HomePage />
+            </ProtectedRoute>
+          }
+        />
+        <Route path="*" element={<NotFoundPage />} />
+      </Routes>
+    </div>
+  );
+}
+
+export default function App() {
+  return <AppShell />;
+}

package/dist/templates/overlays/spa-react/frontend/src/api/client.ts

@@ -0,0 +1,86 @@
+const API_PREFIX = "/api/v1";
+
+interface ApiErrorBody {
+  error?: string;
+  details?: Record<string, string[]>;
+}
+
+class ApiError extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+    readonly details?: Record<string, string[]>,
+  ) {
+    super(message);
+    this.name = "ApiError";
+  }
+}
+
+interface ApiFetchOptions extends RequestInit {
+  token?: string | null;
+  etag?: string | null;
+}
+
+async function apiFetch<T>(path: string, options: ApiFetchOptions = {}): Promise<T> {
+  const headers = new Headers(options.headers);
+
+  if (options.token) {
+    headers.set("authorization", `Bearer ${options.token}`);
+  }
+
+  if (options.etag) {
+    headers.set("if-match", options.etag);
+  }
+
+  if (options.body && !headers.has("content-type")) {
+    headers.set("content-type", "application/json");
+  }
+
+  const response = await fetch(`${API_PREFIX}${path}`, {
+    ...options,
+    headers,
+  });
+
+  if (response.status === 204) {
+    return undefined as T;
+  }
+
+  const contentType = response.headers.get("content-type") ?? "";
+
+  if (!contentType.includes("application/json")) {
+    if (!response.ok) {
+      throw new ApiError(response.status, `Request failed with ${response.status}`);
+    }
+
+    return undefined as T;
+  }
+
+  const body = (await response.json()) as T & ApiErrorBody;
+
+  if (!response.ok) {
+    throw new ApiError(response.status, body.error ?? "Request failed", body.details);
+  }
+
+  return body;
+}
+
+async function fetchResourceEtag(path: string, token: string): Promise<string> {
+  const response = await fetch(`${API_PREFIX}${path}`, {
+    headers: { authorization: `Bearer ${token}` },
+  });
+
+  if (!response.ok) {
+    throw new ApiError(response.status, `Failed to load ETag for ${path}`);
+  }
+
+  const etag = response.headers.get("etag");
+
+  if (!etag) {
+    throw new ApiError(412, `Missing ETag for ${path}`);
+  }
+
+  return etag;
+}
+
+export type { ApiErrorBody };
+export { API_PREFIX, ApiError, apiFetch, fetchResourceEtag };