@ultimat3/cli 20.1.6 → 20.2.0

package/src/serve.ts

@@ -40,6 +40,7 @@ import { startServices } from './dev-runtime';
 import type { Env } from './dev-services';
 import { resolveServices } from './dev-services';
 import { storageRoutes } from './dev-storage';
+import { errorPageStyleSources } from './error-page-csp';
 import { PortInvalidError, RoleUnknownError } from './errors';
 import { holdUntilShutdown } from './hold';
 import { buildIslands } from './island-bundle';
@@ -53,6 +54,7 @@ import { styleBundle } from './style-bundle';
 import { styleRoutes } from './style-routes';
 import { serviceWorkerArtifacts } from './sw-artifacts';
 import { serviceWorkerRoutes } from './sw-routes';
+import { loadThemeMode, themeBoot } from './theme-boot';
 
 export const DEFAULT_PORT = 3000;
 
@@ -360,6 +362,7 @@ async function bootRoles(boot: {
   // on a laptop and absent in the image is exactly the dev/prod difference this file exists to
   // prevent, and it is the one an operator cannot see without installing the app.
   const pwa = await loadPwaArtifacts(options.root);
+  const theme = themeBoot(await loadThemeMode(options.root));
   // The worker, from the SAME route table this process is about to serve — `describeRoutes()` is
   // the one projection `x.manifest.json`, `/_x`, the sitemap and `sw.js` are all built from, so a
   // route added here cannot be missing from the precache manifest.
@@ -393,6 +396,7 @@ async function bootRoles(boot: {
     ...appRoutes({
       buildId,
       resolveIsland: (file) => islands.resolverFor(file),
+      themeHead: theme.head,
       ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
       // Only when a store was supplied. `createIsrController` defaults to a per-process memory
       // store, so twelve replicas hold twelve of them and a purge tag regenerates one twelfth of
@@ -419,6 +423,10 @@ async function bootRoles(boot: {
     // Same declaration `x dev` reads. Without it a container answers a browser that opened a
     // guarded page with the problem document, rendered as raw JSON in the viewport.
     signInPath: await loadSignInPath(options.root),
+    // The enforced policy this process sends must admit the app's own error pages' `<style>` and
+    // the theme boot the documents carry; `x dev` is report-only, so only here was it a blank page.
+    inlineStyles: await errorPageStyleSources(options.root),
+    inlineScripts: [theme.cspSource],
     // The app's own `apps/web/site/errors/<status>.html`, resolved inside `startWeb` so this
     // process and `x dev` cannot answer a browser differently.
     root: options.root,

package/src/templates/index.ts

@@ -39,11 +39,15 @@ export { claudeFiles } from './scaffold-claude';
 export { claudeAgentFiles } from './scaffold-claude-agents';
 export { claudeCommandFiles } from './scaffold-claude-commands';
 export { containerFiles } from './scaffold-container';
+export { dashboardFiles } from './scaffold-dashboard';
 export { docsFiles, EXECUTABLE_FILES } from './scaffold-docs';
 export { entryFiles } from './scaffold-entries';
-// The four guards `x new` ships, distinct from `guardFiles` above, which is `x g guard <name>`.
+export { errorPageFiles, PWA_COLORS } from './scaffold-errors';
+// The nine guards `x new` ships, distinct from `guardFiles` above, which is `x g guard <name>`.
 export { scaffoldGuardFiles } from './scaffold-guards';
 export { i18nIndex } from './scaffold-i18n';
 export { repoFiles } from './scaffold-repo';
+export { shellFiles } from './scaffold-shell';
+export { siteFiles } from './scaffold-site';
 export type { SliceModule } from './slice-foundation';
 export { sliceFoundation } from './slice-foundation';

package/src/templates/scaffold-app.ts

@@ -6,10 +6,14 @@ import { sortedImports } from './imports';
 import type { GeneratedFile, NameSet } from './naming';
 import { apiFiles } from './scaffold-api';
 import { authFiles } from './scaffold-auth';
+import { dashboardFiles } from './scaffold-dashboard';
 import { entryFiles } from './scaffold-entries';
+import { errorPageFiles } from './scaffold-errors';
 import { httpFiles } from './scaffold-http';
 import { icon } from './scaffold-icon';
 import { rolesFiles } from './scaffold-roles';
+import { shellFiles } from './scaffold-shell';
+import { siteFiles } from './scaffold-site';
 
 // The one dependency this manifest names, and it is not decoration: every page below reads its
 // strings through `@<app>/i18n`'s `useT()`, so the surface that renders a string DEPENDS on the
@@ -42,154 +46,6 @@ const tsconfig = (): string => `{
 }
 `;
 
-const sitePage = (
-  app: NameSet,
-): string => `// The landing page. site/ is 0kb JS: static render, hydrate never, no framework script tag.
-//
-// Strings come from \`useT()\` — this app's own catalog module — and never from
-// \`t\` in @ultimat3/i18n. That import is what puts the module holding \`defineCatalogs()\` in
-// this page's graph, so rendering a string is what registers the catalogs. A page that reached
-// past it shipped every string as \`\u27e6key\u27e7\` with \`x verify\` green (issue #249).
-${sortedImports([
-  `import { useT } from '@${app.kebab}/i18n';`,
-  `import { defineRoute } from '@ultimat3/render';`,
-])}
-import styles from './page.module.scss';
-
-export const config = defineRoute({
-  render: 'static',
-  hydrate: 'never',
-  offline: 'precache',
-  budget: { js: '0kb' },
-  // \`t\` is handed to \`meta\` by the router — one translator per render, resolved against the
-  // request's locale before the head is built.
-  meta: ({ t }) => ({
-    title: t('site.home.title'),
-    description: t('site.home.description'),
-  }),
-});
-
-export function HomePage() {
-  const t = useT();
-
-  return (
-    <main class={styles.hero}>
-      <h1>{t('site.home.title')}</h1>
-      <p>{t('site.home.description')}</p>
-      <a class={styles.cta} href="/dashboard">
-        {t('site.home.cta')}
-      </a>
-    </main>
-  );
-}
-
-export const appName = '${app.kebab}';
-`;
-
-const siteStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
-
-.hero {
-  display: grid;
-  gap: tokens.space(4);
-  padding: tokens.space(8);
-  background: tokens.role('bg');
-  color: tokens.role('fg');
-}
-
-.cta {
-  justify-self: start;
-  padding: tokens.space(2) tokens.space(4);
-  border-radius: tokens.radius('md');
-  background: tokens.role('accent');
-  color: tokens.role('accent-fg');
-}
-`;
-
-const sitePageTest =
-  (): string => `// The landing page ships zero JS and declares its metadata. Both are promises the file makes in
-// its config, and both are the kind that rot silently when someone adds one import.
-import { metaContextFor, routeDataFor } from '@ultimat3/render';
-import { expect, unitTest } from '@ultimat3/testing';
-import { config } from './page';
-
-// The same two objects a render builds: \`routeDataFor\` resolves the route's data once, and
-// \`metaContextFor\` wraps it the way every render mode wraps it before calling \`meta\`.
-const ctx = { params: {}, url: 'https://example.test/' };
-
-unitTest('the landing page ships zero JS and declares metadata', async () => {
-  expect(config.render).toBe('static');
-  expect(config.hydrate).toBe('never');
-  expect(config.budget.js).toBe('0kb');
-  const meta = await config.meta(metaContextFor(ctx, await routeDataFor(config, ctx)));
-  expect(meta.title ?? '').not.toBe('');
-});
-`;
-
-const dashboardPage = (
-  app: NameSet,
-): string => `// The authed dashboard. app/ streams: a static shell is flushed instantly and the holes arrive
-// as their data resolves.
-
-// \`useT()\`, not \`t\` from @ultimat3/i18n — see apps/web/site/page.tsx for why.
-${sortedImports([
-  `import { useT } from '@${app.kebab}/i18n';`,
-  `import { defineRoute } from '@ultimat3/render';`,
-])}
-import styles from './page.module.scss';
-
-export const config = defineRoute({
-  // 'ssr', not 'stream', and this is not a downgrade: 'stream' needs a boundary to stream into,
-  // and the framework has no hole marker yet. Solid's <Suspense> is not it — it throws outside a
-  // Solid renderer, and the server JSX factory is inert on purpose. A scaffolded 'stream' route
-  // therefore failed x routes with X_ROUTE_MODE_INVALID on the first run, printing a fix nobody
-  // could follow. Ship the mode that works. Async data needs no boundary: await it in the page.
-  render: 'ssr',
-  // Stated with no island on the page, deliberately and for free — \`apps/admin/app/admin/page.tsx\`
-  // carries the reason.
-  hydrate: 'visible',
-  offline: 'runtime',
-  // Auth is a policy, never a route-local flag: one authz system, evaluated everywhere.
-  policy: { permission: 'dashboard:read' },
-  budget: { js: '60kb' },
-  meta: ({ t }) => ({
-    title: t('app.dashboard.title'),
-    description: t('app.dashboard.description'),
-  }),
-});
-
-export function DashboardPage() {
-  const t = useT();
-
-  return (
-    <section class={styles.panel}>
-      <h1>{t('app.dashboard.title')}</h1>
-    </section>
-  );
-}
-`;
-
-const dashboardStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
-
-.panel {
-  padding: tokens.space(6);
-  background: tokens.role('surface-raised');
-  color: tokens.role('fg');
-}
-`;
-
-const dashboardTest =
-  (): string => `// The dashboard renders per request, is gated by a policy, and has an offline strategy. Losing
-// the policy is the interesting regression: the page still renders, to anyone.
-import { expect, unitTest } from '@ultimat3/testing';
-import { config } from './page';
-
-unitTest('the dashboard renders on the server, is gated, and has an offline strategy', () => {
-  expect(config.render).toBe('ssr');
-  expect(config.policy?.permission).toBe('dashboard:read');
-  expect(config.offline).toBe('runtime');
-});
-`;
-
 const offlineTest =
   (): string => `// The offline fallback has to render with nothing: no network, no session, no database, and no
 // JavaScript. Every one of those is a config field here, and every one of them rots the moment
@@ -419,7 +275,8 @@ restructure.
 | Start | \`x new ${app.kebab}-${surface}\` inside this directory, or wire it by hand |
 `;
 
-/** `example` reaches only `apps/web/api/index.ts`: the slice it registers is written elsewhere. */
+/** `example` decides the API registration, the shell's nav and which dashboard is written; the
+ * slice itself is written elsewhere. */
 export function appFiles(app: NameSet, example: boolean): readonly GeneratedFile[] {
   return [
     { path: 'apps/web/package.json', contents: webPackage(app) },
@@ -427,12 +284,14 @@ export function appFiles(app: NameSet, example: boolean): readonly GeneratedFile
     // The process a container starts and the artifact a CDN is handed — `scaffold-entries.ts`.
     ...entryFiles(),
     { path: 'apps/web/site/icon.png', contents: icon() },
-    { path: 'apps/web/site/page.tsx', contents: sitePage(app) },
-    { path: 'apps/web/site/page.module.scss', contents: siteStyle() },
-    { path: 'apps/web/site/page.test.ts', contents: sitePageTest() },
-    { path: 'apps/web/app/dashboard/page.tsx', contents: dashboardPage(app) },
-    { path: 'apps/web/app/dashboard/page.module.scss', contents: dashboardStyle() },
-    { path: 'apps/web/app/dashboard/page.test.ts', contents: dashboardTest() },
+    // The landing page: hero, two calls to action, three feature cards — `scaffold-site.ts`.
+    ...siteFiles(app),
+    // The signed-in product: its frame and the one island it ships (`scaffold-shell.ts`), then the
+    // dashboard in the shape the invocation earns (`scaffold-dashboard.ts`).
+    ...shellFiles(app, example),
+    ...dashboardFiles(app, example),
+    // Served verbatim for those statuses and carried into the static export — `scaffold-errors.ts`.
+    ...errorPageFiles(app),
     // The third piece of the authz story the scaffold already tells twice: the routes declare a
     // policy and `shared/roles.ts` declares the grants, and until this file existed nothing
     // answered "who is this?" — so every one of those routes refused every request.

package/src/templates/scaffold-dashboard-bare.ts

@@ -0,0 +1,182 @@
+// The `--no-example` dashboard: framework facts and the route table, and no chart — there is no
+// series to draw until the first `x g resource`, and a chart of invented numbers would be the first
+// lie in the app. The route declaration and the island come from `scaffold-dashboard-shared.ts`.
+
+import { sortedImports } from './imports';
+import type { GeneratedFile, NameSet } from './naming';
+import { DASHBOARD_DIR, routeConfig, themeActions, themeIsland } from './scaffold-dashboard-shared';
+
+// Plain strings for the framework lines, never template literals: the workspace-dependency scanner
+// blanks a string's contents but not a nested template's, so a template here would bill the CLI
+// for the imports of the app it writes.
+const barePage = (
+  app: NameSet,
+): string => `// The authed dashboard of an app with no entity yet. Nothing here is invented: the tiles are the
+// framework's own registries — routes, locales, roles, version — and the table is the route table
+// \`x routes\` prints. NO CHART, deliberately: there is no series to draw until the first
+// \`x g resource\`, and a chart of made-up numbers would be the first lie in the app.
+//
+// \`useT()\`, not \`t\` from @ultimat3/i18n — see apps/web/site/page.tsx for why.
+${sortedImports([
+  `import { catalogs, useT } from '@${app.kebab}/i18n';`,
+  "import { frameworkVersion } from '@ultimat3/core';",
+  "import { currentLocale } from '@ultimat3/i18n';",
+  "import { defineRoute, island, routeEntries } from '@ultimat3/render';",
+  "import { DataTable, Grid, PageHeader, Section, StatTile, ThemeToggle } from '@ultimat3/ui';",
+])}
+import { roles } from '../../shared/roles';
+import { Shell } from '../../shared/shell';
+import { factsOf, formatCount, type RouteRow, routeRows } from './dashboard-view';
+import styles from './page.module.scss';
+
+${themeIsland}
+
+${routeConfig('')}
+
+export function DashboardPage() {
+  const t = useT();
+  const locale = currentLocale();
+  // Read at render, not at import: the registries are filled by the boot scan, after this module.
+  const entries = routeEntries();
+  const facts = factsOf({
+    routes: entries.length,
+    locales: catalogs.locales.length,
+    roles: Object.keys(roles).length,
+    version: frameworkVersion(),
+  });
+  const rows = routeRows(entries);
+
+  return (
+    <Shell
+      nav="dashboard"
+      actions={
+        ${themeActions}
+      }
+    >
+      <div class={styles.page}>
+        <PageHeader title={t('app.dashboard.title')} description={t('app.dashboard.subtitle')} />
+        {/* 12rem, not the catalog's 16rem default: four tiles pair up two-by-two on a tablet's main
+            column and sit in one row on a desktop, never three and an orphan. */}
+        <Grid minColumn="12rem">
+          <StatTile
+            stat="routes"
+            label={t('app.dashboard.statRoutes')}
+            value={formatCount(facts.routes, locale)}
+            hint={t('app.dashboard.hintRoutes')}
+          />
+          <StatTile
+            stat="locales"
+            label={t('app.dashboard.statLocales')}
+            value={formatCount(facts.locales, locale)}
+            hint={t('app.dashboard.hintLocales')}
+          />
+          <StatTile
+            stat="roles"
+            label={t('app.dashboard.statRoles')}
+            value={formatCount(facts.roles, locale)}
+            hint={t('app.dashboard.hintRoles')}
+          />
+          <StatTile
+            stat="version"
+            label={t('app.dashboard.statVersion')}
+            value={facts.version}
+            hint={t('app.dashboard.hintVersion')}
+          />
+        </Grid>
+        <Section title={t('app.dashboard.routesTitle')}>
+          <DataTable
+            caption={t('app.dashboard.routesCaption')}
+            rowKey={(row: RouteRow) => row.path}
+            rows={rows}
+            columns={[
+              { key: 'path', header: t('app.dashboard.columnPath'), cell: (row) => row.path },
+              {
+                key: 'surface',
+                header: t('app.dashboard.columnSurface'),
+                cell: (row) => row.surface,
+              },
+              { key: 'render', header: t('app.dashboard.columnRender'), cell: (row) => row.render },
+            ]}
+          />
+        </Section>
+      </div>
+    </Shell>
+  );
+}
+`;
+
+const bareView =
+  (): string => `// The dashboard's facts, apart from its markup: pure projections of what the framework registered,
+// so the page and a test read the same shape. No I/O, no \`t()\`, no JSX.
+
+/** The three columns of the route table, as \`x routes\` prints them. */
+export interface RouteRow {
+  readonly path: string;
+  readonly surface: string;
+  readonly render: string;
+}
+
+/** What \`routeEntries()\` hands over, narrowed to the fields the table reads. */
+export interface RouteLike {
+  readonly path: string;
+  readonly surface: string;
+  readonly config: { readonly render: string };
+}
+
+/** Sorted by path in code-unit order — the order \`x routes\` and the manifest both use. */
+export const routeRows = (entries: readonly RouteLike[]): readonly RouteRow[] =>
+  entries
+    .map((entry) => ({ path: entry.path, surface: entry.surface, render: entry.config.render }))
+    .toSorted((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+
+export interface FrameworkFacts {
+  readonly routes: number;
+  readonly locales: number;
+  readonly roles: number;
+  readonly version: string;
+}
+
+/** Counts are never negative, and a blank version is reported as unknown rather than as nothing. */
+export const factsOf = (input: FrameworkFacts): FrameworkFacts => ({
+  routes: Math.max(0, input.routes),
+  locales: Math.max(0, input.locales),
+  roles: Math.max(0, input.roles),
+  version: input.version === '' ? 'unknown' : input.version,
+});
+
+/** A figure for a tile, in the page's locale. \`Intl.NumberFormat\` needs no time zone. */
+export const formatCount = (value: number, locale: string): string =>
+  new Intl.NumberFormat(locale).format(value);
+`;
+
+const bareViewTest = (): string => `// The route table and the fact tiles, pinned on fixed input.
+import { expect, unitTest } from '@ultimat3/testing';
+import { factsOf, formatCount, routeRows } from './dashboard-view';
+
+unitTest('routeRows projects the three columns and sorts by path', () => {
+  const rows = routeRows([
+    { path: '/dashboard', surface: 'app', config: { render: 'ssr' } },
+    { path: '/', surface: 'site', config: { render: 'static' } },
+  ]);
+  expect(rows.map((row) => row.path)).toEqual(['/', '/dashboard']);
+  expect(rows[1]).toEqual({ path: '/dashboard', surface: 'app', render: 'ssr' });
+});
+
+unitTest('factsOf clamps counts and names an unknown version', () => {
+  const facts = factsOf({ routes: -1, locales: 1, roles: 2, version: '' });
+  expect(facts).toEqual({ routes: 0, locales: 1, roles: 2, version: 'unknown' });
+  expect(factsOf({ routes: 3, locales: 1, roles: 2, version: '1.2.3' }).version).toBe('1.2.3');
+});
+
+unitTest('formatCount follows the locale', () => {
+  expect(formatCount(1234, 'en')).toBe('1,234');
+  expect(formatCount(1234, 'de')).toBe('1.234');
+});
+`;
+
+/** The bare dashboard's page, view module and view test. */
+export const bareDashboardFiles = (app: NameSet): readonly GeneratedFile[] => [
+  { path: `${DASHBOARD_DIR}/page.tsx`, contents: barePage(app) },
+  { path: `${DASHBOARD_DIR}/dashboard-view.ts`, contents: bareView() },
+  { path: `${DASHBOARD_DIR}/dashboard-view.test.ts`, contents: bareViewTest() },
+];