@eventmodelers/cli 1.0.163 → 2.0.2

package/shared/scaffold/supabase/template/server.ts.tmpl

@@ -0,0 +1,168 @@
+import {join} from 'path';
+import {spawnSync} from 'child_process';
+import net from 'net';
+import {getApplication, startAPI, WebApiSetup} from '@event-driven-io/emmett-expressjs';
+import {glob} from "glob";
+import express, {Application, Request, Response} from 'express';
+import {jsonBigIntReplacer} from './src/util/sanitize';
+import {requireUser} from "./src/supabase/requireUser";
+import {notImplemented} from "./src/common/notImplemented";
+import {closeDb} from "./src/common/db";
+import swaggerUi from 'swagger-ui-express'
+import {specs} from './src/swagger';
+import cors from 'cors';
+import {findEventstore} from "./src/common/loadPostgresEventstore";
+import {PostgresEventStore} from "@event-driven-io/emmett-postgresql";
+
+// Generated by `eventmodelers scaffold`. Slice work never edits this file (blocked-paths check).
+
+// Run as TypeScript (tsx watch in dev, ts-node in start) or compiled (dist/server.js): either way the slices
+// sit next to this file, with the matching extension.
+const ext = __filename.endsWith('.ts') ? 'ts' : 'js';
+
+// Dev only: apply Flyway migrations on every (re)start, so a slice's new migration reaches the running app
+// with the same hot reload as its code.
+function migrate() {
+    if (process.env.AUTO_MIGRATE !== 'true') return;
+    const result = spawnSync('flyway', ['-configFiles=flyway.conf', '-baselineOnMigrate=true', 'migrate'], {
+        cwd: process.cwd(), env: process.env, encoding: 'utf8',
+    });
+    if (result.status === 0) console.log('Flyway: migrations applied');
+    else console.error(`Flyway migrate failed (fix the migration and save to retry):\n${result.stdout ?? ''}${result.stderr ?? result.error ?? ''}`);
+}
+
+function assertPortFree(port: number): Promise<void> {
+    return new Promise((resolve, reject) => {
+        const probe = net.createServer()
+            .once('error', () => reject(new Error(`Port ${port} is in use. Stop whatever holds it (macOS/Linux: lsof -nP -iTCP:${port} -sTCP:LISTEN; Windows: netstat -ano) or change PORT in .env and skeleton.json.`)))
+            .once('listening', () => probe.close(() => resolve()))
+            .listen(port);
+    });
+}
+
+async function startServer() {
+    const port = parseInt(process.env.PORT || '__API_PORT__', 10);
+    await assertPortFree(port);
+    migrate();
+
+    const eventStore = await findEventstore()
+    const slicesBase = join(__dirname, 'src/slices');
+
+    const routeFiles = await glob(join(slicesBase, `**/routes{,-*}.${ext}`), {nodir: true});
+    console.log('Found route files:', routeFiles);
+
+    const processorFiles = await glob(join(slicesBase, `**/processor{,-*}.${ext}`), {nodir: true});
+    console.log('Found processor files:', processorFiles);
+
+    // Common routes (e.g. projection replay) are privileged/operational and are
+    // only mounted when explicitly enabled via env.
+    const commonRoutesEnabled = process.env.COMMON_ROUTES_ENABLED === 'true';
+    const commonRouteFiles = commonRoutesEnabled
+        ? await glob(join(__dirname, `src/common/routes{,-*}.${ext}`), {nodir: true})
+        : [];
+
+    const rootApp: Application = express();
+    rootApp.set('json replacer', jsonBigIntReplacer);
+
+    const corsOrigins = process.env.CORS_ORIGINS?.split(',').map(o => o.trim()) ?? ['http://localhost:__WEB_PORT__', 'http://127.0.0.1:__WEB_PORT__'];
+    rootApp.use(cors({
+        origin: corsOrigins,
+        credentials: true,
+        methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
+        allowedHeaders: ['Content-Type', 'Content-Encoding', 'accept-encoding', 'Authorization', 'x-user-id', 'x-causation-id', 'x-correlation-id']
+    }));
+
+    const webApis: WebApiSetup[] = [];
+    for (const file of routeFiles.concat(commonRouteFiles)) {
+        const webApiModule: { api: () => WebApiSetup } = await import(file);
+        if (typeof webApiModule.api == 'function') {
+            webApis.push(webApiModule.api());
+        } else {
+            console.error(`Expected api function to be defined in ${file}`);
+        }
+    }
+
+    const startedProcessors: Array<{ stop: () => Promise<void> }> = [];
+    for (const processorFile of processorFiles) {
+        const processor: { processor: { start: (eventStore: PostgresEventStore) => Promise<void>; stop: () => Promise<void> } } = await import(processorFile);
+        if (typeof processor.processor?.start == "function") {
+            console.log(`starting processor ${processorFile}`)
+            processor.processor.start(eventStore).catch(err => console.error(`Processor ${processorFile} failed:`, err));
+            startedProcessors.push(processor.processor);
+        }
+    }
+
+    const shutdown = async (signal: string) => {
+        console.log(`${signal} received, shutting down processors...`);
+        await Promise.allSettled(startedProcessors.map(p => p.stop()));
+        await eventStore.close();
+        await closeDb();
+        process.exit(0);
+    };
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+
+    const childApp: Application = getApplication({
+        apis: webApis,
+        disableJsonMiddleware: false,
+        enableDefaultExpressEtag: true,
+    });
+    childApp.set('json replacer', jsonBigIntReplacer);
+
+    // Signed-in user info
+    childApp.get('/api/user', async (req: Request, res: Response) => {
+        const result = await requireUser(req, res, false)
+        if (result.error) {
+            if (!res.headersSent) res.status(401).json({error: result.error})
+        } else {
+            res.status(200).json({user_id: result.user.id, email: result.user.email, metadata: result.user.user_metadata})
+        }
+    });
+
+    childApp.use('/api-docs', swaggerUi.serve);
+    childApp.get('/api-docs', swaggerUi.setup(specs, {swaggerOptions: {urls: [{url: '/swagger.json', name: 'JSON'}]}}));
+    childApp.get('/swagger.json', (_req: Request, res: Response) => {
+        res.setHeader('Content-Type', 'application/json');
+        res.send(specs);
+    });
+
+    rootApp.use((req: Request, _res: Response, next) => {
+        console.log(`[${req.method}] ${req.path}`);
+        next();
+    });
+    rootApp.use(express.json());
+
+    rootApp.get('/health', (_req: Request, res: Response) => {
+        res.json({ok: true, routes: routeFiles.length, processors: processorFiles.length});
+    });
+
+    // Closed-by-default auth gate: every route requires a valid Supabase JWT
+    // except the explicitly public paths below. New slice routes are protected
+    // even if a handler forgets to call requireUser.
+    const PUBLIC_PATHS = ['/api-docs', '/swagger.json', '/health'];
+    const isPublicPath = (p: string): boolean =>
+        PUBLIC_PATHS.some(pub => p === pub || p.startsWith(pub + '/'));
+    rootApp.use(async (req: Request, res: Response, next) => {
+        if (req.method === 'OPTIONS') return next();
+        if (isPublicPath(req.path)) return next();
+        const {error} = await requireUser(req, res);
+        if (error) return;
+        next();
+    });
+
+    rootApp.use(childApp)
+    // After every real route: modeled endpoints that are not built yet answer 501, not 404.
+    rootApp.use(notImplemented)
+
+    startAPI(rootApp, {port});
+    console.log(`> Ready on port ${port}`);
+
+    process.on('unhandledRejection', (reason) => {
+        console.error('⛔ Unhandled Rejection:', reason);
+    });
+}
+
+startServer().catch(error => {
+    console.error('Failed to start server:', error);
+    process.exit(1);
+});

package/shared/scaffold/supabase/template/src/common/extraEndpoints.ts.tmpl

@@ -0,0 +1,5 @@
+// Endpoints the model describes that do not follow the kit's naming convention (e.g. a file download such as
+// 'GET orderdocument/:orderId/pdf'). `:param` stands for one path segment. Kept by hand: `eventmodelers scaffold`
+// creates this file once and never overwrites it.
+export const EXTRA_ENDPOINTS: string[] = [
+];

package/shared/scaffold/supabase/template/src/common/notImplemented.test.ts.tmpl

@@ -0,0 +1,58 @@
+import {describe, it} from 'node:test';
+import assert from 'node:assert';
+import {existsSync, readdirSync, readFileSync, statSync} from 'node:fs';
+import {join} from 'node:path';
+import type {AddressInfo} from 'node:net';
+import express from 'express';
+import {isModeledEndpoint, notImplemented} from './notImplemented';
+import {MODELED_ENDPOINTS} from './modeledEndpoints';
+
+const slicesRoot = join(__dirname, '../slices');
+
+const routeFiles = (dir: string): string[] =>
+    !existsSync(dir) ? [] : readdirSync(dir).flatMap((name) => {
+        const full = join(dir, name);
+        if (statSync(full).isDirectory()) return routeFiles(full);
+        return /^routes(-.*)?\.ts$/.test(name) ? [full] : [];
+    });
+
+// A concrete request path for a modeled entry: `:param` -> x, and a command gets an id segment.
+const samplePath = (entry: string) => {
+    const [method, path] = entry.split(' ');
+    return {method, url: `/api/${path.replace(/:[A-Za-z]+/g, 'x')}${method === 'POST' ? '/x' : ''}`};
+};
+
+describe('notImplemented fallback', () => {
+    it('every real route is on the modeled list (guards the naming convention)', () => {
+        const missing: string[] = [];
+        for (const file of routeFiles(slicesRoot)) {
+            const source = readFileSync(file, 'utf8');
+            for (const m of source.matchAll(/router\.(get|post)\(\s*['"`]([^'"`]+)['"`]/g)) {
+                const method = m[1].toUpperCase();
+                const path = m[2].replace(/:[A-Za-z]+/g, 'x');
+                if (!isModeledEndpoint(method, path)) missing.push(`${method} ${m[2]} (${file})`);
+            }
+        }
+        assert.deepStrictEqual(missing, [], 'add these to src/common/extraEndpoints.ts, or rename the route to the kit convention');
+    });
+
+    it('answers 501 for a modeled endpoint with no handler, lets a real route win, leaves other paths 404', async () => {
+        const app = express();
+        const [first, second] = MODELED_ENDPOINTS.map(samplePath);
+        if (first) app.all(first.url, (_req, res) => res.json({real: true})); // a "real" route registered first wins
+        app.use(notImplemented);
+        const server = app.listen(0);
+        const base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+        try {
+            if (first) assert.equal((await fetch(base + first.url, {method: first.method})).status, 200);
+            if (second) {
+                const unbuilt = await fetch(base + second.url, {method: second.method});
+                assert.equal(unbuilt.status, 501);
+                assert.equal(((await unbuilt.json()) as {code: string}).code, 'not_implemented');
+            }
+            assert.equal((await fetch(`${base}/api/not-modeled-${Date.now()}`)).status, 404);
+        } finally {
+            server.close();
+        }
+    });
+});

package/shared/scaffold/supabase/template/src/common/notImplemented.ts.tmpl

@@ -0,0 +1,29 @@
+import type {NextFunction, Request, RequestHandler, Response} from 'express';
+import {MODELED_ENDPOINTS} from './modeledEndpoints';
+import {EXTRA_ENDPOINTS} from './extraEndpoints';
+
+const escape = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+// `:param` segments match any single path segment
+const toPathRegex = (path: string) =>
+    path.split('/').map((seg) => (seg.startsWith(':') ? '[^/]+' : escape(seg))).join('/');
+
+// POST /api/<name> or /api/<name>/<one segment>; GET /api/query/<name>-collection (or a listed GET path)
+const patterns = [...MODELED_ENDPOINTS, ...EXTRA_ENDPOINTS].map((entry) => {
+    const [method, path] = entry.split(' ');
+    const re = method === 'POST'
+        ? new RegExp(`^/api/${toPathRegex(path)}(/[^/]+)?/?$`)
+        : new RegExp(`^/api/${toPathRegex(path)}/?$`);
+    return {method, re};
+});
+
+export const isModeledEndpoint = (method: string, path: string): boolean =>
+    patterns.some((p) => p.method === method.toUpperCase() && p.re.test(path));
+
+// Registered AFTER every real route: a modeled endpoint with no handler yet answers 501 Not Implemented
+// (so "not built" is distinguishable from a wrong URL, which stays 404). Once a slice is built, its real
+// route matches first and this never runs for it.
+export const notImplemented: RequestHandler = (req: Request, res: Response, next: NextFunction) => {
+    if (res.headersSent || !isModeledEndpoint(req.method, req.path)) return next();
+    return res.status(501).json({ok: false, code: 'not_implemented', error: 'This feature is not built yet.'});
+};

package/shared/scaffold/supabase/template/supabase/migrations/_V0__supabase_stubs.sql.tmpl

@@ -0,0 +1,34 @@
+-- Test-only stubs for Supabase-provided roles and the auth schema, so migrations
+-- that reference them run on a plain Postgres container. runFlywayMigrations()
+-- (src/common/testHelpers.ts) applies this before Flyway; the leading underscore
+-- keeps Flyway itself from picking it up as a versioned migration.
+
+DO $$
+BEGIN
+    IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'anon') THEN
+        CREATE ROLE anon NOLOGIN;
+    END IF;
+    IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'authenticated') THEN
+        CREATE ROLE authenticated NOLOGIN;
+    END IF;
+    IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'service_role') THEN
+        CREATE ROLE service_role NOLOGIN BYPASSRLS;
+    END IF;
+END
+$$;
+
+CREATE SCHEMA IF NOT EXISTS auth;
+
+CREATE TABLE IF NOT EXISTS auth.users
+(
+    id    UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email TEXT
+);
+
+CREATE OR REPLACE FUNCTION auth.uid() RETURNS UUID
+    LANGUAGE sql STABLE
+AS $$ SELECT NULLIF(current_setting('request.jwt.claim.sub', true), '')::UUID $$;
+
+CREATE OR REPLACE FUNCTION auth.role() RETURNS TEXT
+    LANGUAGE sql STABLE
+AS $$ SELECT NULLIF(current_setting('request.jwt.claim.role', true), '')::TEXT $$;

package/shared/scaffold/supabase/template/web/src/App.tsx.tmpl

@@ -0,0 +1,38 @@
+import { useEffect, useState } from 'react';
+import type { Session } from '@supabase/supabase-js';
+import { Navigate, Route, Routes } from 'react-router-dom';
+import { supabase } from './lib/supabase';
+import { Layout } from './app/Layout';
+import { SignIn } from './app/SignIn';
+import { TimelinePage } from './app/TimelinePage';
+import { pageRoutes } from './app/pages';
+import { HOME_ROUTE } from './app/model';
+import { NotFound } from './app/NotFound';
+
+// App shell generated by `eventmodelers scaffold`. Pages are routed from src/app/model.ts and src/pages/*.tsx;
+// slice work never edits this file.
+export default function App() {
+  const [session, setSession] = useState<Session | null | undefined>(undefined);
+
+  useEffect(() => {
+    supabase.auth.getSession().then(({ data }) => setSession(data.session));
+    const { data } = supabase.auth.onAuthStateChange((_event, s) => setSession(s));
+    return () => data.subscription.unsubscribe();
+  }, []);
+
+  if (session === undefined) return null;
+  if (!session) return <SignIn />;
+
+  return (
+    <Routes>
+      <Route element={<Layout email={session.user.email} onSignOut={() => supabase.auth.signOut()} />}>
+        <Route path="/" element={<Navigate to={HOME_ROUTE} replace />} />
+        <Route path="/timelines/:slug" element={<TimelinePage />} />
+        {pageRoutes.map(({ route, Component }) => (
+          <Route key={route} path={route} element={<Component />} />
+        ))}
+        <Route path="*" element={<NotFound />} />
+      </Route>
+    </Routes>
+  );
+}

package/shared/scaffold/supabase/template/web/src/app/Layout.tsx.tmpl

@@ -0,0 +1,48 @@
+import { matchPath, NavLink, Outlet, useLocation } from 'react-router-dom';
+import { APP_TITLE, PAGES, TIMELINES } from './model';
+
+type LayoutProps = {
+  email: string | undefined;
+  onSignOut: () => void;
+};
+
+// Main container: one navigation entry per timeline in the event model.
+export function Layout({ email, onSignOut }: LayoutProps) {
+  const { pathname } = useLocation();
+  // A timeline stays active on its overview and on any of its pages.
+  const activeTimeline = TIMELINES.find((t) =>
+    matchPath(`/timelines/${t.slug}`, pathname) ||
+    PAGES.some((p) => t.pages.includes(p.name) && matchPath(p.route, pathname)),
+  );
+
+  return (
+    <>
+      <nav className="navbar is-light" aria-label="main navigation">
+        <div className="navbar-brand">
+          <NavLink to="/" className="navbar-item has-text-weight-bold">{APP_TITLE}</NavLink>
+        </div>
+        <div className="navbar-menu is-active">
+          <div className="navbar-start">
+            {TIMELINES.map((t) => (
+              <NavLink key={t.slug} to={`/timelines/${t.slug}`}
+                className={`navbar-item${t === activeTimeline ? ' is-active has-text-weight-semibold' : ''}`}>
+                {t.title}
+              </NavLink>
+            ))}
+          </div>
+          <div className="navbar-end">
+            <div className="navbar-item">{email}</div>
+            <div className="navbar-item">
+              <button className="button is-light" onClick={onSignOut}>Sign out</button>
+            </div>
+          </div>
+        </div>
+      </nav>
+      <section className="section">
+        <div className="container">
+          <Outlet />
+        </div>
+      </section>
+    </>
+  );
+}

package/shared/scaffold/supabase/template/web/src/app/NotFound.tsx.tmpl

@@ -0,0 +1,12 @@
+import { Link } from 'react-router-dom';
+import { HOME_ROUTE } from './model';
+
+/** Shown for an address the app has no page for. Distinct from NotBuilt, which marks a modeled feature not built yet. */
+export function NotFound() {
+  return (
+    <div className="notification" role="status">
+      <p className="has-text-weight-semibold">Page not found</p>
+      <p>There is no page at this address. <Link to={HOME_ROUTE}>Go to the home page</Link> or pick a timeline from the navigation.</p>
+    </div>
+  );
+}

package/shared/scaffold/supabase/template/web/src/app/SignIn.tsx.tmpl

@@ -0,0 +1,42 @@
+import { useState, type FormEvent } from 'react';
+import { supabase } from '../lib/supabase';
+import { APP_TITLE } from './model';
+
+// Supabase email + password sign-in. Users are created with `npm run user -- <email> <password>`.
+export function SignIn() {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  async function onSubmit(e: FormEvent) {
+    e.preventDefault();
+    setBusy(true);
+    setError(null);
+    const { error } = await supabase.auth.signInWithPassword({ email, password });
+    if (error) setError(error.message);
+    setBusy(false);
+  }
+
+  return (
+    <section className="section">
+      <div className="container" style={{ maxWidth: 400 }}>
+        <h1 className="title">{APP_TITLE}</h1>
+        <form onSubmit={onSubmit}>
+          <div className="field">
+            <label className="label" htmlFor="email">Email</label>
+            <input id="email" className="input" type="email" autoComplete="username" required
+              value={email} onChange={(e) => setEmail(e.target.value)} />
+          </div>
+          <div className="field">
+            <label className="label" htmlFor="password">Password</label>
+            <input id="password" className="input" type="password" autoComplete="current-password" required
+              value={password} onChange={(e) => setPassword(e.target.value)} />
+          </div>
+          {error && <p className="help is-danger mb-3">{error}</p>}
+          <button className={`button is-primary${busy ? ' is-loading' : ''}`} type="submit">Sign in</button>
+        </form>
+      </div>
+    </section>
+  );
+}

package/shared/scaffold/supabase/template/web/src/app/TimelinePage.tsx.tmpl

@@ -0,0 +1,73 @@
+import { useEffect, useState } from 'react';
+import { Link, useParams } from 'react-router-dom';
+import { getReadModel, isNotBuilt } from '../lib/api';
+import { NotBuilt } from '../lib/NotBuilt';
+import { NotFound } from './NotFound';
+import { PAGES, TIMELINES, type SliceInfo } from './model';
+
+type Probe = { state: 'loading' } | { state: 'built'; rows: number } | { state: 'not-built' } | { state: 'error'; message: string };
+
+// Asks the backend for a read model. A 501 means its slice is not built yet and shows as a placeholder.
+function ReadModelStatus({ slice }: { slice: SliceInfo }) {
+  const [probe, setProbe] = useState<Probe>({ state: 'loading' });
+  const path = slice.endpoint!.replace(/^GET /, '');
+
+  useEffect(() => {
+    getReadModel<unknown>(path)
+      .then((data) => setProbe({ state: 'built', rows: Array.isArray(data) ? data.length : data ? 1 : 0 }))
+      .catch((err: unknown) =>
+        setProbe(isNotBuilt(err) ? { state: 'not-built' } : { state: 'error', message: err instanceof Error ? err.message : String(err) }),
+      );
+  }, [path]);
+
+  if (probe.state === 'loading') return <span className="tag">checking…</span>;
+  if (probe.state === 'built') return <span className="tag is-success">built · {probe.rows} row{probe.rows === 1 ? '' : 's'}</span>;
+  if (probe.state === 'not-built') return <NotBuilt compact />;
+  return <span className="tag is-danger" title={probe.message}>error: {probe.message}</span>;
+}
+
+const TYPE_LABEL: Record<string, string> = { STATE_CHANGE: 'Command', STATE_VIEW: 'Read model', AUTOMATION: 'Automation' };
+
+// Overview of one timeline: its pages and its slices, with a live 501 check for each read model.
+export function TimelinePage() {
+  const { slug } = useParams();
+  const timeline = TIMELINES.find((t) => t.slug === slug);
+  if (!timeline) return <NotFound />;
+
+  const pages = PAGES.filter((p) => timeline.pages.includes(p.name));
+
+  return (
+    <>
+      <h1 className="title">{timeline.title}</h1>
+
+      <h2 className="title is-5">Pages</h2>
+      {pages.length === 0 ? <p className="mb-5">This timeline has no screens.</p> : (
+        <ul className="mb-5">
+          {pages.map((p) => (
+            <li key={p.name}>
+              {p.hasParams ? <span>{p.title} <span className="has-text-grey">({p.route}, opened from another page)</span></span>
+                : <Link to={p.route}>{p.title}</Link>}
+            </li>
+          ))}
+        </ul>
+      )}
+
+      <h2 className="title is-5">Slices</h2>
+      {timeline.slices.length === 0 ? <p>This timeline has no slices.</p> : (
+        <table className="table is-fullwidth is-narrow">
+          <thead><tr><th>Slice</th><th>Type</th><th>Endpoint</th><th>Status</th></tr></thead>
+          <tbody>
+            {timeline.slices.map((s) => (
+              <tr key={s.title}>
+                <td>{s.title}</td>
+                <td>{TYPE_LABEL[s.type] ?? s.type}</td>
+                <td><code>{s.endpoint ?? '—'}</code></td>
+                <td>{s.type === 'STATE_VIEW' && s.endpoint ? <ReadModelStatus slice={s} /> : <span className="has-text-grey">—</span>}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      )}
+    </>
+  );
+}

package/shared/scaffold/supabase/template/web/src/app/pages.ts.tmpl

@@ -0,0 +1,26 @@
+import { createElement, type ComponentType } from 'react';
+import { PAGES } from './model';
+import { NotBuilt } from '../lib/NotBuilt';
+
+// Every file in src/pages is routed without editing the router: a page from the model gets its route from
+// model.ts, and any other page file gets /pages/<file-name>. The page component is the export named like the
+// file (web kit convention), or the default export.
+const modules = import.meta.glob<Record<string, ComponentType>>('../pages/*.tsx', { eager: true });
+
+const byName = new Map(
+  Object.entries(modules).map(([file, mod]) => {
+    const name = file.replace(/^.*\/(.*)\.tsx$/, '$1');
+    return [name, mod[name] ?? mod.default] as const;
+  }),
+);
+
+const kebab = (s: string) => s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+
+const missing = (title: string): ComponentType => () => createElement(NotBuilt, { detail: `The page file for "${title}" is missing.` });
+
+export const pageRoutes: { route: string; Component: ComponentType }[] = [
+  ...PAGES.map((p) => ({ route: p.route, Component: byName.get(p.name) ?? missing(p.title) })),
+  ...[...byName.entries()]
+    .filter(([name, Component]) => Component && !PAGES.some((p) => p.name === name))
+    .map(([name, Component]) => ({ route: `/pages/${kebab(name)}`, Component: Component! })),
+];

package/shared/scaffold/supabase/template/web/src/app/skeleton.css.tmpl

@@ -0,0 +1,25 @@
+/* Minimal styles for the skeleton's own markup, used when the model's screens name no CSS framework.
+   Only the class names the app shell uses are covered. */
+:root { font-family: system-ui, sans-serif; color: #222; background: #fafafa; }
+body { margin: 0; }
+.navbar { display: flex; align-items: center; gap: 1rem; padding: 0.5rem 1rem; background: #eee; }
+.navbar-brand, .navbar-start, .navbar-end, .navbar-menu { display: flex; align-items: center; gap: 0.75rem; }
+.navbar-menu { flex: 1; justify-content: space-between; }
+.navbar-item { color: inherit; text-decoration: none; padding: 0.25rem 0.5rem; }
+.navbar-item.is-active { background: #ddd; border-radius: 4px; }
+.section { padding: 2rem 1rem; }
+.container { max-width: 960px; margin: 0 auto; }
+.title { font-size: 1.75rem; margin: 0 0 1rem; }
+.title.is-5 { font-size: 1.15rem; }
+.subtitle { color: #666; margin: 0 0 1rem; }
+.notification { padding: 1rem; border-radius: 4px; background: #fff8e1; border: 1px solid #f0d58c; }
+.tag { display: inline-block; padding: 0 0.5rem; border-radius: 4px; background: #eee; font-size: 0.8rem; }
+.tag.is-success { background: #e3f6e8; } .tag.is-warning { background: #fff3cd; } .tag.is-danger { background: #fde2e1; }
+.table { border-collapse: collapse; width: 100%; } .table th, .table td { text-align: left; padding: 0.35rem 0.5rem; border-bottom: 1px solid #ddd; }
+.field { margin-bottom: 0.75rem; } .label { display: block; font-weight: 600; margin-bottom: 0.25rem; }
+.input { width: 100%; padding: 0.4rem; box-sizing: border-box; }
+.button { padding: 0.4rem 0.9rem; border: 1px solid #bbb; border-radius: 4px; background: #fff; cursor: pointer; }
+.button.is-primary { background: #2a6df4; border-color: #2a6df4; color: #fff; }
+.help.is-danger { color: #c0392b; }
+.has-text-grey { color: #777; } .has-text-weight-bold { font-weight: 700; } .has-text-weight-semibold { font-weight: 600; }
+.mb-3 { margin-bottom: 0.75rem; } .mb-5 { margin-bottom: 1.5rem; }

package/shared/scaffold/supabase/template/web/src/lib/NotBuilt.tsx.tmpl

@@ -0,0 +1,12 @@
+import { NOT_BUILT_MESSAGE } from './api';
+
+/** Placeholder for a feature whose slice is not built yet, shown instead of an error. Pair with `isNotBuilt(err)` from `./api`. */
+export function NotBuilt({ detail, compact = false }: { detail?: string; compact?: boolean }) {
+  if (compact) return <span className="tag is-warning is-light">{NOT_BUILT_MESSAGE}</span>;
+  return (
+    <div className="notification is-warning is-light" role="status">
+      <p className="has-text-weight-semibold">{NOT_BUILT_MESSAGE}</p>
+      {detail && <p>{detail}</p>}
+    </div>
+  );
+}