@ultimat3/cli 1.1.0 → 2.0.0

package/src/templates/scaffold-app.ts

@@ -4,6 +4,7 @@
 
 import type { GeneratedFile, NameSet } from './naming';
 import { icon } from './scaffold-icon';
+import { rolesFiles } from './scaffold-roles';
 
 const webPackage = (app: NameSet): string => `{
   "name": "@${app.kebab}/web",
@@ -66,29 +67,37 @@ const siteStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
 
 .hero {
   display: grid;
-  gap: tokens.$space-4;
-  padding: tokens.$space-8;
-  background: tokens.$surface-base;
-  color: tokens.$text-primary;
+  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.$accent-solid;
-  color: tokens.$accent-on-solid;
+  padding: tokens.space(2) tokens.space(4);
+  border-radius: tokens.radius('md');
+  background: tokens.role('accent');
+  color: tokens.role('accent-fg');
 }
 `;
 
-const sitePageTest = (): string => `import { expect, unitTest } from '@ultimat3/testing';
+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({});
+  const meta = await config.meta(metaContextFor(ctx, await routeDataFor(config, ctx)));
   expect(meta.title ?? '').not.toBe('');
 });
 `;
@@ -102,7 +111,12 @@ import { defineRoute } from '@ultimat3/render';
 import styles from './page.module.scss';
 
 export const config = defineRoute({
-  render: 'stream',
+  // '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',
   hydrate: 'visible',
   offline: 'runtime',
   // Auth is a policy, never a route-local flag: one authz system, evaluated everywhere.
@@ -123,17 +137,20 @@ export function DashboardPage() {
 const dashboardStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
 
 .panel {
-  padding: tokens.$space-6;
-  background: tokens.$surface-raised;
-  color: tokens.$text-primary;
+  padding: tokens.space(6);
+  background: tokens.role('surface-raised');
+  color: tokens.role('fg');
 }
 `;
 
-const dashboardTest = (): string => `import { expect, unitTest } from '@ultimat3/testing';
+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 streams, requires a permission and has an offline strategy', () => {
-  expect(config.render).toBe('stream');
+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');
 });
@@ -160,10 +177,10 @@ const offlineStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
 
 .offline {
   display: grid;
-  gap: tokens.$space-3;
-  padding: tokens.$space-8;
-  background: tokens.$surface-base;
-  color: tokens.$text-secondary;
+  gap: tokens.space(3);
+  padding: tokens.space(8);
+  background: tokens.role('bg');
+  color: tokens.role('fg-muted');
 }
 `;
 
@@ -187,7 +204,10 @@ export const health = action({
 });
 `;
 
-const apiTest = (): string => `import { contractTest, expect } from '@ultimat3/testing';
+const apiTest =
+  (): string => `// The health action's contract, run as the framework generates it: garbage input refused, the
+// operation in the OpenAPI document. The declaration is the source; this only runs it.
+import { contractTest, expect } from '@ultimat3/testing';
 import { health } from './health';
 
 // Named here because every projection needs a stable name and this file does not boot the app.
@@ -207,39 +227,84 @@ contractTest('health projects one MCP tool and one OpenAPI operation', () => {
 `;
 
 const sharedTokens =
-  (): string => `// Semantic tokens for this app, layered on @ultimat3/ui. Components reference these names; a raw
-// hex anywhere in the app is a lint failure, because dark theme is not a later project.
-@use '@ultimat3/ui/tokens' as base;
-
-$surface-base: base.$surface-base;
-$surface-raised: base.$surface-raised;
-$text-primary: base.$text-primary;
-$text-secondary: base.$text-secondary;
-$accent-solid: base.$accent-solid;
-$accent-on-solid: base.$accent-on-solid;
+  (): string => `// This app's authoring layer for stylesheets: \`@use '../../shared/tokens' as t;\` in a
+// \`*.module.scss\` and reach for \`t.role(…)\`. Forwards @ultimat3/ui's token layer verbatim and is
+// where this app's own functions and mixins go.
+//
+// Emits no CSS, and must not: every module is its own Sass compilation, so a \`:root\` block in here
+// would be inlined once per stylesheet that uses it. The custom properties those functions REFER to
+// are defined exactly once, by \`shared/global.scss\`.
+//
+// A raw hex anywhere in the app is a lint failure, because dark theme is not a later project.
+//
+// The API is functions, not variables: \`role('accent')\`, \`space(4)\`, \`radius('md')\`,
+// \`text('lg')\`, \`shadow('sm')\`, plus mixins like \`@include focus-ring\` and \`@include surface\`.
+// Colours are stored as space-separated RGB CHANNELS, so \`role('accent', 0.12)\` gives you a tint
+// without inventing a second token.
+@forward '@ultimat3/ui/tokens';
+`;
+
+const sharedGlobalStyle =
+  (): string => `// The app document's global layer, and the only stylesheet in this app that emits top-level CSS:
+// @ultimat3/ui's custom properties (\`:root{--color-*;--space-*;…}\`) and then its reset. Every rule
+// a component emits reads those properties through \`var(--…)\`, so without this file the browser
+// drops every one of those declarations and the app renders unstyled.
+//
+// Exactly one file, imported for its side effect by \`global.ts\` — never \`@use\`d from a
+// \`*.module.scss\`. Each module is a separate Sass compilation, so a \`@use\` that emits would
+// duplicate the whole \`:root\` block once per module.
+//
+// This app's own global rules go below the @use, never inside a component module.
+@use '@ultimat3/ui/global.scss';
+`;
+
+const sharedGlobalModule =
+  (): string => `// The one edge that puts the global stylesheet in this app's module graph. \`shared/\` is loaded by
+// both surfaces and by the framework's own boot scan, so the tokens reach every document without a
+// page having to remember to import them — and \`x verify\` fails with X_STYLES_GLOBAL_MISSING if
+// this edge is ever cut.
+
+import './global.scss';
 `;
 
 const sharedActor =
   (): string => `// The actor type both surfaces agree on. Policies read this and nothing else, so authz cannot
 // disagree between HTTP, live queries, jobs and MCP.
+import { expandRoles, grantMatches } from '@ultimat3/policy';
+import { roles } from './roles';
+
 export interface Actor {
   readonly id: string;
   readonly orgId: string;
   readonly roles: readonly string[];
 }
 
-export const isMember = (actor: Actor | null): boolean =>
-  actor !== null && (actor.roles.includes('member') || actor.roles.includes('owner'));
+/**
+ * What this actor may DO, answered from the declared role map. Never \`actor.roles.includes('admin')\`:
+ * a role-name comparison is a second authz rule, and it goes stale the moment a role is renamed or
+ * a grant moves to another role. \`grantMatches\` is what reads a \`post:*\` wildcard as one.
+ */
+export const holds = (actor: Actor | null, permission: string): boolean =>
+  actor !== null &&
+  expandRoles(actor.roles, roles).some((grant) => grantMatches(grant, permission));
 `;
 
-const sharedActorTest = (): string => `import { expect } from 'bun:test';
-import { unitTest } from '@ultimat3/testing';
-import { isMember } from './actor';
-
-unitTest('isMember rejects anonymous and viewer actors', () => {
-  expect(isMember(null)).toBe(false);
-  expect(isMember({ id: 'a', orgId: 'o', roles: ['viewer'] })).toBe(false);
-  expect(isMember({ id: 'a', orgId: 'o', roles: ['owner'] })).toBe(true);
+const sharedActorTest =
+  (): string => `// \`holds\` answers from the declared role map, never from a role NAME. An undeclared role must
+// expand to no grants — the branch that turns a typo into an actor who can do everything.
+import { expect, unitTest } from '@ultimat3/testing';
+import type { Actor } from './actor';
+import { holds } from './actor';
+
+const actor = (...names: readonly string[]): Actor => ({ id: 'a', orgId: 'o', roles: names });
+
+unitTest('holds answers from the role map, and an anonymous actor holds nothing', () => {
+  expect(holds(null, 'dashboard:read')).toBe(false);
+  // A role no defineRoles() call declares expands to no grants — never to every grant.
+  expect(holds(actor('visitor'), 'dashboard:read')).toBe(false);
+  expect(holds(actor('member'), 'dashboard:read')).toBe(true);
+  expect(holds(actor('admin'), 'dashboard:read')).toBe(true);
+  expect(holds(actor('member'), 'admin:read')).toBe(false);
 });
 `;
 
@@ -293,6 +358,19 @@ const server =
 import { join } from 'node:path';
 import { runRole } from '@ultimat3/cli';
 
+// MORE THAN ONE REPLICA? Add these two lines, above \`runRole\`:
+//
+//   import { configureIdempotency } from '@ultimat3/action';
+//   configureIdempotency({ scope: 'shared' });
+//
+// \`idempotent: true\` on an action promises that a retry does not repeat the work. Under the
+// process-scoped default that promise holds inside ONE process — a client retrying
+// \`POST /api/payments/charge\` after a timeout lands on another replica, which has never seen the
+// key, and charges the card twice, silently, with \`x verify\` green. Declaring \`'shared'\` is what
+// makes that a boot error (\`X_IDEMPOTENCY_NOT_SHARED\`) unless a shared store is installed.
+// \`runRole\` installs the Postgres one for you, on the connection it resolved from \`DATABASE_URL\`,
+// so the declaration is all this app owes. It must run before \`runRole\` imports the actions.
+
 /**
  * Where the app is. From this file normally — the image's WORKDIR is not the app root's business.
  * A \`--compile\` binary is the exception: its \`import.meta.dir\` is Bun's virtual filesystem, which
@@ -315,6 +393,11 @@ const prerender =
   (): string => `// The static entry. \`x build --target static\` runs this with \`--out <dir>\` and it writes one HTML
 // file per \`render: 'static'\` route — a CDN or an object store then serves site/ with no process
 // behind it. Every other render mode needs a running app and is reported as skipped, never emitted.
+//
+// Skipped is not unweighed: a route that declares a \`budget:\` is rendered in memory and measured
+// whatever its mode, so \`x verify\`'s \`budgets\` step has a number for it. \`unmeasured\` is the list
+// this build could not render — each one is an X_BUDGET_UNMEASURED at the gate, and this is where
+// the reason is.
 
 import { join } from 'node:path';
 import { prerenderSite } from '@ultimat3/cli';
@@ -323,12 +406,15 @@ const root = join(import.meta.dir, '..', '..');
 const flag = Bun.argv.indexOf('--out');
 const out = (flag === -1 ? undefined : Bun.argv[flag + 1]) ?? join(root, '.x', 'static');
 // SITE_ORIGIN is what canonical and og:url are built from; the default is only ever a local build.
-const origin = Bun.env['SITE_ORIGIN'];
+// Property access, not \`Bun.env['SITE_ORIGIN']\`: the scaffolded tsconfig does not set
+// \`noPropertyAccessFromIndexSignature\`, so the bracket form is the one biome's useLiteralKeys
+// reports — a diagnostic in an app's first lint run over a file the app never wrote.
+const origin = Bun.env.SITE_ORIGIN;
 
 if (import.meta.main) {
   const report = await prerenderSite({ root, out, ...(origin === undefined ? {} : { origin }) });
   await Bun.stdout.write(
-    \`\${JSON.stringify({ ok: true, out: report.out, pages: report.pages.length, skipped: report.skipped })}\\n\`,
+    \`\${JSON.stringify({ ok: true, out: report.out, pages: report.pages.length, skipped: report.skipped, unmeasured: report.unmeasured })}\\n\`,
   );
 }
 `;
@@ -364,11 +450,22 @@ export function appFiles(app: NameSet): readonly GeneratedFile[] {
     { path: 'apps/web/api/health.ts', contents: apiAction() },
     { path: 'apps/web/api/health.test.ts', contents: apiTest() },
     { path: 'apps/web/shared/tokens.scss', contents: sharedTokens() },
+    { path: 'apps/web/shared/global.scss', contents: sharedGlobalStyle() },
+    { path: 'apps/web/shared/global.ts', contents: sharedGlobalModule() },
     { path: 'apps/web/shared/actor.ts', contents: sharedActor() },
     { path: 'apps/web/shared/actor.test.ts', contents: sharedActorTest() },
+    // The app's role map, beside the actor that reads it. `shared/` and not a feature folder:
+    // `defineRoles()` merges, so a per-feature call is legal and is how an app ends up with no
+    // answer to "which roles exist?" — see `scaffold-roles.ts`.
+    ...rolesFiles(),
     { path: 'apps/admin/package.json', contents: adminPackage(app) },
     { path: 'apps/admin/tsconfig.json', contents: tsconfig() },
-    { path: 'apps/admin/app/page.tsx', contents: adminPage() },
+    // `apps/admin/app/admin/page.tsx`, not `apps/admin/app/page.tsx`: the directory IS the URL,
+    // relative to the surface root, so the shallower path resolves to `/` and collides with
+    // `apps/web/site/page.tsx` — `x dev` loads both surfaces into one route table and the
+    // scaffolded app failed its own `x routes` with X_ROUTE_DUPLICATE. `/admin` also matches
+    // @ultimat3/admin's own `basePath` default, so the two agree instead of merely not clashing.
+    { path: 'apps/admin/app/admin/page.tsx', contents: adminPage() },
     { path: 'apps/mobile/README.md', contents: placeholder('mobile', app) },
     { path: 'apps/desktop/README.md', contents: placeholder('desktop', app) },
   ];

package/src/templates/scaffold-claude-agents.ts

@@ -0,0 +1,149 @@
+// The subagents `x new` writes into `.claude/agents/`. Scoped by BOUNDARY, never by role: a
+// researcher/coder/reviewer trio has no file set, so it cannot be told what it may not touch. The
+// app's real boundaries are the eight primitives and the surfaces — one agent per boundary, plus
+// `shape`, the read-only one that decides whether there is anything to build at all.
+
+import type { GeneratedFile, NameSet } from './naming';
+
+const shape = (app: NameSet): string => `---
+name: shape
+description: Use BEFORE writing any code, at the idea stage — turns a product request into the one decision that governs everything after it: which of the eight primitives each piece is, which slice and surface it lives in, and the exact \`x g\` invocations. Read-only; it decides, it never builds. Also use when a request seems to need something the framework does not have.
+tools: Read, Glob, Grep, Bash
+---
+
+You decide **whether and what to build** in ${app.kebab}. You write no code, and you do not edit
+files. Your answer is a plan a builder can execute without re-deciding anything.
+
+## The eight, and there is no ninth
+
+\`entity\` · \`policy\` · \`action\` · \`mutator\` · \`query\` · \`job\` · \`route\` · \`task\`
+
+| Question | Primitive |
+|---|---|
+| what is stored, and what is always true of it | \`entity\` |
+| who may do it | \`policy\` |
+| a server-authoritative operation with an input and an output | \`action\` |
+| an \`action\` that writes exactly one entity | \`mutator\` |
+| a read, cached and optionally live | \`query\` |
+| durable background work, retried, idempotent | \`job\` |
+| a URL a human visits | \`route\` |
+| work on a schedule | \`task\` |
+
+**A request that fits none is not one feature.** Split it until every piece is one of the eight,
+and name the pieces. A capability that genuinely has no home arrives as a **function that returns**
+one of these — never as a ninth kind of thing. If you cannot express it that way, say so plainly and
+stop; that answer is worth more than a plan built on a shape the app cannot hold.
+
+## Then place it
+
+| Where | What belongs there |
+|---|---|
+| \`apps/web/site/<path>/page.tsx\` | public, SEO-critical, 0kb JS |
+| \`apps/web/app/<slice>/\` | the feature slice: entity, repo, policy, actions, queries, jobs, UI |
+| \`apps/web/api/<name>/route.ts\` | HTTP surface for actions |
+| \`apps/web/shared/\` | tokens, primitives, the actor type — a leaf, imports nothing of yours |
+| \`packages/db/\` | schema, migrations, seed |
+| \`packages/ui/\` | components with no feature knowledge |
+
+Read the tree before you place anything. \`x routes\`, \`x actions\`, \`x queries\`, \`x entities\`,
+\`x jobs\`, \`x tasks\` and \`x policy list\` are the registries — check whether the thing already
+exists before proposing it, and add \`--json\` to any of them.
+
+## Report
+
+\`\`\`
+Build:      yes | no — <one line>
+Pieces:     <primitive> <name> → <dir>          (one line each)
+Generate:   x g <kind> <name> --feature <slice> (one line each, in dependency order)
+Existing:   <what already covers part of this>
+Refused:    <anything that fits no primitive, and why>
+\`\`\`
+`;
+
+const data = (app: NameSet): string => `---
+name: data
+description: Use for anything about what is stored — entity definitions, invariants, indexes, repositories, migrations and seed data in ${app.kebab}. Owns \`packages/db/\` and every \`entity.ts\` and \`repo.ts\`. Not for actions, queries or UI.
+tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+You own the data boundary of ${app.kebab}: \`packages/db/\` plus every \`entity.ts\` and \`repo.ts\` in a
+feature slice. Nothing else. A change outside that set is a collision — report it, do not make it.
+
+| Rule | Detail |
+|---|---|
+| The entity is the schema | columns, invariants, indexes and tenancy are declared there, never in SQL |
+| Migrations are generated | edit \`entity.ts\`, then \`x db gen "what changed"\`. Never hand-write a file into \`packages/db/migrations/\` |
+| Destructive is declared | a migration that drops, truncates or retypes carries \`-- destructive: true\`, or the gate refuses it |
+| \`repo.ts\` is the only door | every read and write goes through it; a raw statement anywhere else is authz bypassed |
+| Branch before you break things | \`x db branch create <name>\`, never the shared dev database |
+| Money | \`{ minor, currency }\` — integer minor units and an ISO code, both, always. Never a float |
+| Time | store UTC; a formatted date always names an explicit IANA time zone |
+
+Inspect before you change: \`x entities list\`, \`x entities describe <name>\`, both with \`--json\`.
+
+Checks: \`bun test <path>/entity.test.ts\`, \`bunx biome check --write <paths>\`, and \`bun run typecheck\`
+once when you are otherwise done. Never \`x verify\` — that belongs to whoever coordinates you.
+`;
+
+const server = (app: NameSet): string => `---
+name: server
+description: Use for server-authoritative behaviour in ${app.kebab} — actions, mutators, queries, jobs, tasks and policies, plus the HTTP surface under \`apps/web/api/\`. Not for entities, migrations or anything that renders.
+tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+You own the server boundary of ${app.kebab}: \`policy.ts\`, actions, mutators, queries, jobs and tasks
+inside a feature slice, plus \`apps/web/api/\`. Not \`entity.ts\`, not \`repo.ts\`, not anything that
+renders. A change outside that set is a collision — report it, do not make it.
+
+| Rule | Detail |
+|---|---|
+| Generate, then edit | \`x g <kind> <name> --feature <slice>\` for every one of them — a hand-written primitive is missing from every registry that projects it |
+| One authz object | the policy decides; a route or a UI that re-checks is a second answer that will drift |
+| Data through the repo | an action calls \`repo.ts\`, never the database |
+| Errors are instructions | never \`throw new Error\` — subclass \`UltimateError\` with a stable \`X_SCREAMING_SNAKE\` code, a cause and a \`fix:\` a caller can actually run |
+| Jobs run at least once | a handler must be idempotent — an upsert or a statement whose second run changes nothing, never \`count + 1\` |
+| Tasks name a time zone | a cron schedule with an ambient zone is a different time twice a year |
+| No \`any\` | \`unknown\` plus a schema parse |
+
+Inspect before you change: \`x actions describe <name>\`, \`x queries describe <name>\`, \`x jobs ls\`,
+\`x tasks list\`, \`x policy explain <subject>\` — every one takes \`--json\`.
+
+Checks: \`bun test <path>/<file>.test.ts\`, \`bunx biome check --write <paths>\`, and \`bun run typecheck\`
+once when you are otherwise done. Never \`x verify\` — that belongs to whoever coordinates you.
+`;
+
+const web = (app: NameSet): string => `---
+name: web
+description: Use for anything rendered in ${app.kebab} — pages under \`apps/web/site/\` and \`apps/web/app/\`, islands, components in \`packages/ui/\`, styles, tokens and i18n catalogs. Not for actions, queries, entities or migrations.
+tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+You own the rendering boundary of ${app.kebab}: \`apps/web/site/\`, the pages and UI of
+\`apps/web/app/\`, \`apps/web/shared/\`, \`packages/ui/\` and the i18n catalogs. Not the primitives a page
+calls. A change outside that set is a collision — report it, do not make it.
+
+| Rule | Detail |
+|---|---|
+| \`site/\` is 0kb JS | and may not import from \`app/\`. One interactive control on a static page is an island: \`x g island <name> --at <dir>\` |
+| \`shared/\` is a leaf | tokens, primitives, the actor type. It imports nothing of yours |
+| The directory is the URL | \`page.tsx\` under \`site/\`/\`app/\`, \`route.ts\` under \`api/\`. The filename is never the path |
+| Every string through \`t()\` | a literal in a component is a string no locale can ever translate |
+| Semantic tokens only | never a raw hex, in a component or a stylesheet |
+| Dates name a zone | explicit IANA time zone at every call site, no ambient default |
+| A page calls primitives | queries and actions, never a repo and never the database |
+
+Inspect before you change: \`x routes --json\`, and \`x i18n check\` for catalog gaps.
+
+Checks: \`bun test <path>/page.test.ts\`, \`bunx biome check --write <paths>\`, and \`bun run typecheck\`
+once when you are otherwise done. Never \`x verify\` — that belongs to whoever coordinates you.
+`;
+
+/** One agent per boundary, plus the read-only one that runs before there is a boundary to hold. */
+export function claudeAgentFiles(app: NameSet): readonly GeneratedFile[] {
+  return [
+    { path: '.claude/agents/shape.md', contents: shape(app) },
+    { path: '.claude/agents/data.md', contents: data(app) },
+    { path: '.claude/agents/server.md', contents: server(app) },
+    { path: '.claude/agents/web.md', contents: web(app) },
+  ];
+}