@getstrata/starter 1.0.0 → 1.0.2

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

@@ -1,9 +1,49 @@
 # API-only scaffold
 
-This template enables `FRONTEND_MODE=api`.
+This scaffold sets `FRONTEND_MODE=api`: no server-rendered views beyond the welcome page, and no SPA assets.
 
-- JSON API routes under `/api/v1/*`
-- No server-rendered views or SPA assets
-- Use bearer tokens or dev auth headers in tests (`actingAs`, `postJson`)
+## What exists after migrating
 
-Generate an API app with `bunx create-strata my-app --frontend api --yes`.
+- `GET /health` returns plain text `ok`, or `degraded` (503) until the database ping succeeds and the migrated `notes` table exists. Docker HEALTHCHECK uses `/health`.
+- `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/spa-react/frontend/src/App.tsx

@@ -1,10 +1,8 @@
 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";
-import OrganizationsPage from "./pages/OrganizationsPage";
-import ProjectsPage from "./pages/ProjectsPage";
-import TasksPage from "./pages/TasksPage";
 
 function ProtectedRoute({ children }: { children: React.ReactNode }) {
   const { token, loading } = useAuth();
@@ -28,9 +26,7 @@ function AppShell() {
       <header className="site-header">
         <strong>Strata SPA</strong>
         <nav>
-          <Link to="/organizations">Organizations</Link>
-          <Link to="/projects">Projects</Link>
-          <Link to="/tasks">Tasks</Link>
+          <Link to="/">Home</Link>
           {user ? (
             <>
               <span className="hint">{user.email}</span>
@@ -43,29 +39,12 @@ function AppShell() {
       </header>
 
       <Routes>
-        <Route path="/" element={<Navigate to="/organizations" replace />} />
         <Route path="/login" element={<LoginPage />} />
         <Route
-          path="/organizations"
+          path="/"
           element={
             <ProtectedRoute>
-              <OrganizationsPage />
-            </ProtectedRoute>
-          }
-        />
-        <Route
-          path="/projects"
-          element={
-            <ProtectedRoute>
-              <ProjectsPage />
-            </ProtectedRoute>
-          }
-        />
-        <Route
-          path="/tasks"
-          element={
-            <ProtectedRoute>
-              <TasksPage />
+              <HomePage />
             </ProtectedRoute>
           }
         />

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

@@ -0,0 +1,72 @@
+import { useAuth } from "../auth/AuthContext";
+
+export default function HomePage() {
+  const { user } = useAuth();
+
+  return (
+    <section>
+      <h1>Signed in</h1>
+      <p className="hint">
+        This page reads <code>GET /api/v1/auth/me</code> with the bearer token from the login
+        response. It is the only resource the generated backend serves, so it is the only one this
+        page shows.
+      </p>
+
+      <div className="card">
+        <table>
+          <tbody>
+            <tr>
+              <th>Name</th>
+              <td>{user?.name ?? "—"}</td>
+            </tr>
+            <tr>
+              <th>Email</th>
+              <td>{user?.email ?? "—"}</td>
+            </tr>
+            <tr>
+              <th>Role</th>
+              <td>
+                <code>{user?.role ?? "—"}</code>
+              </td>
+            </tr>
+          </tbody>
+        </table>
+      </div>
+
+      <h2>Add your first resource</h2>
+      <p>
+        Create a module under <code>src/modules/</code> and return routes from it. The kernel picks
+        it up on the next boot.
+      </p>
+
+      <pre className="card">
+        <code>{`// 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;`}</code>
+      </pre>
+
+      <p className="hint">
+        Then fetch it here with <code>apiFetch("/notes", {"{ token }"})</code>. The{" "}
+        <code>notes</code> table already exists after <code>bun run db:migrate</code>.
+      </p>
+    </section>
+  );
+}

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

@@ -12,7 +12,7 @@ export default function LoginPage() {
   const [submitting, setSubmitting] = useState(false);
 
   if (token) {
-    return <Navigate to="/organizations" replace />;
+    return <Navigate to="/" replace />;
   }
 
   async function onSubmit(event: FormEvent<HTMLFormElement>) {
@@ -22,7 +22,7 @@ export default function LoginPage() {
 
     try {
       await login(email, password);
-      navigate("/organizations");
+      navigate("/");
     } catch (cause) {
       setError(cause instanceof ApiError ? cause.message : "Login failed");
     } finally {
@@ -33,7 +33,10 @@ export default function LoginPage() {
   return (
     <section className="card">
       <h1>Sign in</h1>
-      <p className="hint">Use seeded credentials or your own API user.</p>
+      <p className="hint">
+        Seeded users are <code>demo@example.com</code> and <code>admin@example.test</code>, password
+        <code>password</code>.
+      </p>
 
       {error ? <p className="error">{error}</p> : null}
 

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

@@ -5,7 +5,7 @@ export default function NotFoundPage() {
     <section className="card">
       <h1>Not found</h1>
       <p>
-        Return to <Link to="/organizations">organizations</Link>.
+        Return <Link to="/">home</Link>.
       </p>
     </section>
   );

package/dist/templates/package.json

@@ -11,9 +11,9 @@
     "check": "tsc --noEmit"
   },
   "dependencies": {
-    "@getstrata/bootstrap": "^1.0.0",
-    "@getstrata/cli": "^1.0.0",
-    "@getstrata/core": "^1.0.0"
+    "@getstrata/bootstrap": "^1.0.2",
+    "@getstrata/cli": "^1.0.2",
+    "@getstrata/core": "^1.0.2"
   },
   "devDependencies": {
     "@types/bun": "^1.4.0",

package/dist/templates/src/bootstrap/config.ts

@@ -16,3 +16,14 @@ export function loadConfig(): AppConfig {
     databaseUrl,
   };
 }
+
+/** Cookie sessions and signed cookies are keyed by this; there is no default. */
+export function sessionSecret(): string {
+  const secret = process.env.SESSION_SECRET?.trim();
+  if (!secret) {
+    throw new Error(
+      "SESSION_SECRET is required. Copy .env.example to .env and set it (32+ characters).",
+    );
+  }
+  return secret;
+}

package/dist/templates/src/bootstrap/createApp.ts

@@ -68,7 +68,8 @@ function createAppContext(): AppContext {
 }
 
 export async function bootstrapApp(options: BootstrapOptions = {}): Promise<BootstrappedApp> {
-  const { migrate: runMigrate = true } = options;
+  const isProduction = process.env.APP_ENV === "production";
+  const { migrate: runMigrate = !isProduction } = options;
 
   const appConfig = loadConfig();
   const context = createAppContext();

package/dist/templates/src/bootstrap/server.ts

@@ -9,7 +9,7 @@ const { routes, config } = await bootstrapApp();
 
 const server = createAppServer(routes, config.port);
 
-console.log(`${config.appUrl} (port ${server.port})`);
+console.log(`Listening on http://localhost:${server.port} (APP_URL ${config.appUrl})`);
 
 if (!(await pingDatabase())) {
   console.warn("Warning: database ping failed.");

package/dist/templates/src/lib/view.ts

@@ -16,6 +16,6 @@ export async function renderPage(
   return htmlResponse(html);
 }
 
-export function plainText(body: string): Response {
-  return new Response(body, { headers: { "content-type": "text/plain; charset=utf-8" } });
+export function plainText(body: string, status = 200): Response {
+  return new Response(body, { status, headers: { "content-type": "text/plain; charset=utf-8" } });
 }

package/dist/templates/src/modules/site/index.ts

@@ -19,7 +19,7 @@ const siteModule: AppModule = {
       "/health": kernel.wrapWeb(
         withErrorHandling(async () => {
           const dbOk = await pingDatabase();
-          return plainText(dbOk ? "ok" : "degraded");
+          return plainText(dbOk ? "ok" : "degraded", dbOk ? 200 : 503);
         }),
       ),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getstrata/starter",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Interactive create-strata wizard. Choose each layer; one database engine.",
   "type": "module",
   "license": "MIT",

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

@@ -1,69 +0,0 @@
-import { useEffect, useState } from "react";
-import { Link } from "react-router-dom";
-import { apiFetch } from "../api/client";
-import { useAuth } from "../auth/AuthContext";
-
-interface Organization {
-  id: number;
-  name: string;
-  slug: string;
-}
-
-interface PaginatedOrganizations {
-  data: Organization[];
-  meta: {
-    total: number;
-  };
-}
-
-export default function OrganizationsPage() {
-  const { token } = useAuth();
-  const [organizations, setOrganizations] = useState<Organization[]>([]);
-  const [error, setError] = useState<string | null>(null);
-
-  useEffect(() => {
-    if (!token) {
-      return;
-    }
-
-    apiFetch<PaginatedOrganizations>("/organizations", { token })
-      .then((body) => setOrganizations(body.data))
-      .catch((cause: unknown) => {
-        setError(cause instanceof Error ? cause.message : "Failed to load organizations");
-      });
-  }, [token]);
-
-  return (
-    <section>
-      <h1>Organizations</h1>
-      <p className="hint">{organizations.length} loaded from the JSON API.</p>
-
-      {error ? <p className="error">{error}</p> : null}
-
-      <div className="card">
-        <table>
-          <thead>
-            <tr>
-              <th>Name</th>
-              <th>Slug</th>
-            </tr>
-          </thead>
-          <tbody>
-            {organizations.map((organization) => (
-              <tr key={organization.id}>
-                <td>{organization.name}</td>
-                <td>
-                  <code>{organization.slug}</code>
-                </td>
-              </tr>
-            ))}
-          </tbody>
-        </table>
-      </div>
-
-      <p>
-        Continue to <Link to="/projects">projects</Link> or <Link to="/tasks">tasks</Link>.
-      </p>
-    </section>
-  );
-}

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

@@ -1,65 +0,0 @@
-import { useEffect, useState } from "react";
-import { Link } from "react-router-dom";
-import { apiFetch } from "../api/client";
-import { useAuth } from "../auth/AuthContext";
-
-interface Project {
-  id: number;
-  name: string;
-  status: string;
-  organization_id: number;
-}
-
-interface PaginatedProjects {
-  data: Project[];
-}
-
-export default function ProjectsPage() {
-  const { token } = useAuth();
-  const [projects, setProjects] = useState<Project[]>([]);
-  const [error, setError] = useState<string | null>(null);
-
-  useEffect(() => {
-    if (!token) {
-      return;
-    }
-
-    apiFetch<PaginatedProjects>("/projects?include=organization", { token })
-      .then((body) => setProjects(body.data))
-      .catch((cause: unknown) => {
-        setError(cause instanceof Error ? cause.message : "Failed to load projects");
-      });
-  }, [token]);
-
-  return (
-    <section>
-      <h1>Projects</h1>
-      {error ? <p className="error">{error}</p> : null}
-
-      <div className="card">
-        <table>
-          <thead>
-            <tr>
-              <th>Name</th>
-              <th>Status</th>
-              <th>Organization</th>
-            </tr>
-          </thead>
-          <tbody>
-            {projects.map((project) => (
-              <tr key={project.id}>
-                <td>{project.name}</td>
-                <td>{project.status}</td>
-                <td>{project.organization_id}</td>
-              </tr>
-            ))}
-          </tbody>
-        </table>
-      </div>
-
-      <p>
-        Back to <Link to="/organizations">organizations</Link>.
-      </p>
-    </section>
-  );
-}

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

@@ -1,65 +0,0 @@
-import { useEffect, useState } from "react";
-import { Link } from "react-router-dom";
-import { apiFetch } from "../api/client";
-import { useAuth } from "../auth/AuthContext";
-
-interface Task {
-  id: number;
-  title: string;
-  status: string;
-  project_id: number;
-}
-
-interface PaginatedTasks {
-  data: Task[];
-}
-
-export default function TasksPage() {
-  const { token } = useAuth();
-  const [tasks, setTasks] = useState<Task[]>([]);
-  const [error, setError] = useState<string | null>(null);
-
-  useEffect(() => {
-    if (!token) {
-      return;
-    }
-
-    apiFetch<PaginatedTasks>("/tasks", { token })
-      .then((body) => setTasks(body.data))
-      .catch((cause: unknown) => {
-        setError(cause instanceof Error ? cause.message : "Failed to load tasks");
-      });
-  }, [token]);
-
-  return (
-    <section>
-      <h1>Tasks</h1>
-      {error ? <p className="error">{error}</p> : null}
-
-      <div className="card">
-        <table>
-          <thead>
-            <tr>
-              <th>Title</th>
-              <th>Status</th>
-              <th>Project</th>
-            </tr>
-          </thead>
-          <tbody>
-            {tasks.map((task) => (
-              <tr key={task.id}>
-                <td>{task.title}</td>
-                <td>{task.status}</td>
-                <td>{task.project_id}</td>
-              </tr>
-            ))}
-          </tbody>
-        </table>
-      </div>
-
-      <p>
-        Back to <Link to="/organizations">organizations</Link>.
-      </p>
-    </section>
-  );
-}