@ultimat3/cli 1.2.0 → 2.0.0

package/src/templates/scaffold-repo.ts

@@ -1,12 +1,28 @@
-// The config half of what `x new` writes: the one config file, the tooling configs and the
-// workspace packages. Committed defaults only — a fresh clone boots with `x dev` and no env
-// scavenger hunt. The docs and shims live in scaffold-docs.ts, the container files in
-// scaffold-container.ts.
-
+// The REPO ROOT half of what `x new` writes: `app.config.ts`, the tooling configs, the committed
+// env files — and the one list that names every other scaffold module in write order. Committed
+// defaults only, so a fresh clone boots with `x dev` and no env scavenger hunt. Each workspace
+// package owns its own files (`scaffold-<name>-package.ts`); docs and shims are scaffold-docs.ts,
+// container files scaffold-container.ts.
+
+import { ENV_EXAMPLE_PATH } from '@ultimat3/core';
+import { VERIFY_FLOOR_FILE } from '../verify-floor';
+import type { VerifyStepName } from '../verify-step';
 import type { GeneratedFile, NameSet } from './naming';
+import { dbPackageFiles } from './scaffold-db-package';
 import { docsFiles } from './scaffold-docs';
+import { domainPackageFiles } from './scaffold-domain-package';
+import { envExampleSource, envSchemaSource } from './scaffold-env';
 import { i18nFiles } from './scaffold-i18n';
-import { packageShapeFiles } from './scaffold-package-shape';
+import { mcpPackageFiles } from './scaffold-mcp-package';
+import { uiPackageFiles } from './scaffold-ui-package';
+
+/**
+ * Spelled once and pinned EXACTLY, because two places named it and a caret let them disagree:
+ * `"^2.4.15"` beside a `$schema` of `2.4.15` installed 2.5.8, whose own parser then reported the
+ * config as out of date on every `bun run lint`. A formatter is a build input — a range that floats
+ * is a `lint` step whose verdict depends on the day the app was installed.
+ */
+const BIOME_VERSION = '2.5.8';
 
 // `version` is not decoration: the manifest's app version IS the contract's compatibility gate,
 // and the manifest never fabricates one — so an app scaffolded without it failed `x manifest`,
@@ -32,7 +48,7 @@ const rootPackage = (app: NameSet, version: string): string => `{
     "db:seed": "bun run packages/db/src/seed.ts"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.15",
+    "@biomejs/biome": "${BIOME_VERSION}",
     "@electric-sql/pglite": "^0.5.4",
     "@types/bun": "^1.3.14",
     "@ultimat3/testing": "^${version}",
@@ -40,6 +56,7 @@ const rootPackage = (app: NameSet, version: string): string => `{
   },
   "dependencies": {
     "@ultimat3/action": "^${version}",
+    "@ultimat3/admin": "^${version}",
     "@ultimat3/cache": "^${version}",
     "@ultimat3/cli": "^${version}",
     "@ultimat3/core": "^${version}",
@@ -52,8 +69,9 @@ const rootPackage = (app: NameSet, version: string): string => `{
     "@ultimat3/pwa": "^${version}",
     "@ultimat3/query": "^${version}",
     "@ultimat3/render": "^${version}",
+    "@ultimat3/schema": "^${version}",
     "@ultimat3/ui": "^${version}",
-    "solid-js": "2.0.0-experimental.16"
+    "solid-js": "1.9.14"
   },
   "engines": {
     "bun": ">=1.3.0"
@@ -88,12 +106,29 @@ const rootTsconfig = (app: NameSet): string => `{
 }
 `;
 
+/**
+ * The env half of `app.config.ts`, projected from `SCAFFOLD_ENV_SCHEMA` — never typed out here.
+ * `envSchema` is a named export on purpose and not an inline argument: `defineEnv()` returns the
+ * resolved VALUES, so an inline record is unreachable afterwards, and `.env.example`, `x env
+ * check` and the gate's drift check are all projections of the record rather than of the values.
+ */
+const envDeclaration = (): string => `${envSchemaSource()}
+
+/**
+ * Validated once, at module scope, before anything listens: a missing or malformed key fails the
+ * boot in ~40ms naming every offender at once, never as a 500 an hour later.
+ */
+export const env = defineEnv(envSchema);`;
+
 const appConfig = (
   app: NameSet,
 ): string => `// The one config file. Everything the app needs to boot is here, typed and validated at startup —
 // a missing value fails the boot with the exact command that fixes it, never at the first request.
 // A named export, never a default: the CLI and the runtime both import \`config\` by name.
-import { defineConfig } from '@ultimat3/core';
+import type { EnvSchema } from '@ultimat3/core';
+import { defineConfig, defineEnv } from '@ultimat3/core';
+
+${envDeclaration()}
 
 export const config = defineConfig({
   name: '${app.kebab}',
@@ -101,8 +136,8 @@ export const config = defineConfig({
   defaultLocale: 'en',
   defaultTimeZone: 'UTC',
   defaultCurrency: 'USD',
-  // Env KEYS, never the value: the same image deploys to every environment.
-  database: { urlEnv: 'DATABASE_URL', poolSize: 10 },
+  // Env KEYS, never the value: the same image deploys to every environment. The database is
+  // configured entirely from the environment — \`DATABASE_URL\` and \`DATABASE_POOL_MAX\`.
   cache: { driver: 'memory', tiers: ['memo', 'lru'] },
   jobs: { driver: 'postgres', queues: ['${app.kebab}-default'], concurrency: 4 },
   // In-process transport by default; set urlEnv and transport: 'nats' to scale past one node.
@@ -116,14 +151,21 @@ export const config = defineConfig({
 // scaffolded app fail its first `x verify` on the config rather than on the code. The note that
 // used to be a comment lives here, where it is read by the person who would have changed the line:
 // x.manifest.json and openapi.json are emitted byte-for-byte by `x manifest`, so a formatter
-// rewriting them puts `x manifest` and `x verify` in a loop neither can win.
+// rewriting them puts `x manifest` and `x verify` in a loop neither can win. `**/migrations` is the
+// same rule for the same reason and the same glob this repo's own biome.json carries: `x db gen`
+// writes the `.sql` and its `.snapshot.json` sidecar, and an app that narrows `lineWidth` would
+// otherwise fail `lint` on a file no author typed and `x db gen` would rewrite anyway.
+// `preset`, not `recommended`: the older key is deprecated from 2.5 on and every `bun run lint`
+// in the scaffolded app printed the migration notice for a config the app never wrote by hand.
 const biome = (): string => `{
-  "$schema": "https://biomejs.dev/schemas/2.4.15/schema.json",
-  "files": { "includes": ["**", "!x.manifest.json", "!openapi.json"] },
+  "$schema": "https://biomejs.dev/schemas/${BIOME_VERSION}/schema.json",
+  "files": {
+    "includes": ["**", "!**/migrations", "!x.manifest.json", "!openapi.json"]
+  },
   "formatter": { "indentStyle": "space", "indentWidth": 2, "lineWidth": 100 },
   "linter": {
     "rules": {
-      "recommended": true,
+      "preset": "recommended",
       "suspicious": { "noExplicitAny": "error" },
       "correctness": { "noUnusedVariables": "error", "noUnusedImports": "error" }
     }
@@ -134,6 +176,41 @@ const biome = (): string => `{
 }
 `;
 
+/**
+ * The suite ratchet, committed on day one. Without it `readVerifyFloor` answers "no file is no
+ * floor" and a deleted suite turns its step from green into skipped-and-green — so
+ * `X_VERIFY_SUITE_VANISHED` was unreachable in every generated app, in the one repo shape that
+ * grows suites fastest.
+ *
+ * Every name here is a step this scaffold has proved it can run: the SIX that declare no `applies`
+ * at all — typecheck, lint, boundaries, filesize, errors, manifest — plus `package-shape` (five
+ * workspace packages), `unit` (every generator emits a `<file>.test.ts`; like every suite step it
+ * applies on its own file list, `verify-tests.ts`), and `eval`, `drift` and `budgets`, which apply
+ * to any root with an `app.config.ts`. Typed as `VerifyStepName`, so a name the gate does not run
+ * is a compile error rather than a floor that covers nothing.
+ *
+ * Four are deliberately absent. `contract`, `live` and `job` have no scaffolded file; `e2e` has
+ * one, and it is an `e2eTest` — `test.skip` until the app registers a browser driver, so the step
+ * would run zero tests and fail the ratchet on the scaffold's own placeholder. `contract-diff`
+ * needs a committed `x.manifest.json`, which `x manifest` writes later. Each joins the list in the
+ * commit that makes the app's own gate run it.
+ */
+const SCAFFOLD_FLOOR: readonly VerifyStepName[] = [
+  'typecheck',
+  'lint',
+  'boundaries',
+  'filesize',
+  'package-shape',
+  'errors',
+  'unit',
+  'eval',
+  'drift',
+  'budgets',
+  'manifest',
+];
+
+const verifyFloor = (): string => `${JSON.stringify({ steps: SCAFFOLD_FLOOR }, null, 2)}\n`;
+
 const bunfig = (): string => `[test]
 root = "."
 # Frozen clock, seeded RNG, sealed network — nondeterminism in a test is a bug.
@@ -148,6 +225,14 @@ declare module '*.module.scss' {
   const classes: Readonly<Record<string, string>>;
   export default classes;
 }
+
+// A plain stylesheet is the global layer: it emits top-level CSS and has no class map worth
+// binding, so \`shared/global.ts\` imports it for the side effect alone. Without this declaration
+// \`tsc\` reports TS2307 on the one import that puts the app's tokens in the document.
+declare module '*.scss' {
+  const classes: Readonly<Record<string, string>>;
+  export default classes;
+}
 `;
 
 const gitignore = (): string => `node_modules/
@@ -161,226 +246,19 @@ playwright-report/
 test-results/
 `;
 
+// Values, not declarations — the declaration is `envSchema` and `.env.example` is its projection.
+// Every key here is one `envSchema` declares, plus `ROLE`, which `@ultimat3/core` reads directly
+// (`roles.ts`) and no app schema may redeclare.
 const envDevelopment =
   (): string => `# Committed non-secret defaults. Per-box secrets go in .env.development.local, which wins.
 # Empty DATABASE_URL means "embedded": x dev runs PGlite in-process, no Docker required.
 DATABASE_URL=
 NATS_URL=
-S3_ENDPOINT=
 PORT=3000
+SESSION_SECRET=dev-only-not-a-real-secret
 ROLE=web
 `;
 
-const domainPackage = (app: NameSet, name: string, description: string): string => `{
-  "name": "@${app.kebab}/${name}",
-  "version": "0.0.0",
-  "private": true,
-  "type": "module",
-  "description": "${description}",
-  "exports": {
-    ".": "./src/index.ts"
-  },
-  "scripts": {
-    "typecheck": "tsc --noEmit -p ../../tsconfig.json"
-  }
-}
-`;
-
-const domainIndex =
-  (): string => `// Pure types and constants. No I/O of any kind: no fs, no network, no database, no env reads.
-export const ROLES = ['owner', 'member', 'viewer'] as const;
-
-export type Role = (typeof ROLES)[number];
-
-export interface Money {
-  readonly minor: number;
-  readonly currency: string;
-}
-
-export const zero = (currency: string): Money => ({ minor: 0, currency });
-
-export const add = (a: Money, b: Money): Money => {
-  if (a.currency !== b.currency) throw new RangeError(\`cannot add \${a.currency} to \${b.currency}\`);
-  return { minor: a.minor + b.minor, currency: a.currency };
-};
-`;
-
-const domainTest = (): string => `import { expect } from 'bun:test';
-import { unitTest } from '@ultimat3/testing';
-import { add, zero } from './index';
-
-unitTest('money adds in minor units', () => {
-  expect(add({ minor: 1050, currency: 'USD' }, { minor: 250, currency: 'USD' })).toEqual({
-    minor: 1300,
-    currency: 'USD',
-  });
-});
-
-unitTest('money refuses to add across currencies', () => {
-  expect(() => add(zero('USD'), zero('EUR'))).toThrow();
-});
-`;
-
-const dbIndex =
-  (): string => `// Schema and migrations only — no business logic lives in this package. The client itself is
-// @ultimat3/db's: one connection pool, sized by ROLE, shared by every package in the app.
-export type { DbClient, SqlFragment } from '@ultimat3/db';
-export { db, sql, withTransaction } from '@ultimat3/db';
-export * as schema from './schema';
-`;
-
-// The four pieces below describe the example slice's table. Under `--no-example` that slice is
-// never written, so each one ships its empty counterpart instead of a reference to a file that is
-// not there — `export { post } from …` alone made `x new --no-example` an app that cannot compile.
-
-const SCHEMA_HEADER = `// Every entity the app declares, re-exported here. This list is what the migration generator
-// reads, so an entity that is not exported here does not exist as far as the database is concerned.`;
-
-/**
- * `bun run db:seed`'s entry point. Identical either way — only the rows differ. Interpolated, not
- * nested, so it carries exactly the escaping a single template literal needs.
- */
-const SEED_MAIN = `
-
-if (import.meta.main) {
-  const count = await seed();
-  // Bun's stdout, not process.stdout: one runtime, one API. Awaited because the write resolves
-  // asynchronously, and this JSON line is the whole output of \`bun run db:seed\`.
-  await Bun.stdout.write(\`\${JSON.stringify({ ok: true, seeded: count })}\\n\`);
-}
-`;
-
-const dbSchema = (app: NameSet, example: boolean): string =>
-  example
-    ? `${SCHEMA_HEADER}
-export { post } from '@${app.kebab}/web/app/post/entity';
-`
-    : `${SCHEMA_HEADER}
-// \`x g entity <name>\` writes the entity; add its export here so the database learns about it.
-export {};
-`;
-
-const dbSeed = (app: NameSet, example: boolean): string =>
-  example
-    ? `// Deterministic seed: same rows every time, so a test and a demo see the same database.
-import { db, sql } from '@ultimat3/db';
-
-const ORG = '00000000-0000-0000-0000-000000000002';
-
-export async function seed(): Promise<number> {
-  const rows = [
-    { id: '00000000-0000-0000-0000-000000000101', title: 'Hello ${app.pascal}', minor: 0 },
-    { id: '00000000-0000-0000-0000-000000000102', title: 'Second post', minor: 1900 },
-  ];
-  for (const row of rows) {
-    // Idempotent by primary key, so re-seeding a branch database is a no-op rather than a crash.
-    await db().execute(sql\`
-      insert into posts (id, org_id, title, price_minor, price_currency)
-      values (\${row.id}, \${ORG}, \${row.title}, \${row.minor}, 'USD')
-      on conflict (id) do nothing\`);
-  }
-  return rows.length;
-}${SEED_MAIN}`
-    : `// Deterministic seed: same rows every time, so a test and a demo see the same database.
-// No entity is declared yet, so there is nothing to insert — the shape stays, so the first
-// \`x g entity\` has one obvious place to seed from.
-
-export async function seed(): Promise<number> {
-  return 0;
-}${SEED_MAIN}`;
-
-const migration = (example: boolean): string =>
-  example
-    ? `-- 0000_initial: the example feature slice. Reversible: the down section is required.
-CREATE TABLE IF NOT EXISTS posts (
-  id uuid PRIMARY KEY,
-  org_id uuid NOT NULL,
-  title varchar(200) NOT NULL,
-  price_minor integer NOT NULL DEFAULT 0,
-  price_currency char(3) NOT NULL DEFAULT 'USD',
-  created_at timestamptz NOT NULL DEFAULT now()
-);
-CREATE INDEX IF NOT EXISTS posts_org_created_idx ON posts (org_id, created_at);
-
--- down
--- DROP INDEX IF EXISTS posts_org_created_idx;
--- DROP TABLE IF EXISTS posts;
-`
-    : `-- 0000_initial: no entity is declared yet, so this migration creates nothing. It exists so the
--- schema hash beside it has a migration to belong to, and \`x verify\` sees no drift on run one.
--- Reversible: the down section is required.
-
--- down
-`;
-
-const uiIndex =
-  (): string => `// App components on top of @ultimat3/ui. Same byte budgets as shared/: this package is imported
-// by site/, so a chart library in here costs the landing page.
-export { Card } from './card';
-`;
-
-const uiCard = (): string => `import type { JSX } from 'solid-js';
-import styles from './card.module.scss';
-
-export interface CardProps {
-  readonly title: string;
-  readonly children?: JSX.Element;
-}
-
-export function Card(props: CardProps) {
-  return (
-    <section class={styles.card}>
-      <h2 class={styles.title}>{props.title}</h2>
-      {props.children}
-    </section>
-  );
-}
-`;
-
-const uiCardStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
-
-.card {
-  padding: tokens.$space-4;
-  border-radius: tokens.$radius-md;
-  background: tokens.$surface-raised;
-  color: tokens.$text-primary;
-}
-
-.title {
-  font: tokens.$text-heading-sm;
-}
-`;
-
-const mcpIndex = (
-  app: NameSet,
-): string => `// The app's own MCP tools. Every action with mcp.expose is already a tool; add app-specific
-// read-only helpers here. Authorization is the action's policy, unchanged.
-import * as api from '@${app.kebab}/web/api/health';
-import { registerActions } from '@ultimat3/action';
-import { defineAppMcp } from '@ultimat3/mcp';
-
-// Names come from export names, so the registry agrees with the module the app already wrote.
-registerActions(api);
-
-// \`include: 'exposed'\` projects straight from the registry. Re-listing the actions here would
-// copy \`mcp: { expose: true }\` into a second place, and the copy goes stale in silence.
-export const mcp = defineAppMcp({
-  name: '${app.kebab}',
-  include: 'exposed',
-});
-`;
-
-const mcpTest = (): string => `import { expect, unitTest } from '@ultimat3/testing';
-import { mcp } from './index';
-
-unitTest('the app exposes its actions as MCP tools', () => {
-  expect(mcp.tools.length).toBeGreaterThan(0);
-  // Every projected tool must describe itself: an agent picks a tool by its description. Assert
-  // on the value, not its length — a failure then prints the empty description, not "0 > 0".
-  for (const tool of mcp.tools) expect(tool.description).not.toBe('');
-});
-`;
-
 /**
  * `example` reaches only the four files that describe the slice's table — schema, seed, initial
  * migration, and nothing in the catalog. Everything else is the same app either way, which is what
@@ -398,40 +276,21 @@ export function repoFiles(
     { path: 'biome.json', contents: biome() },
     { path: 'bunfig.toml', contents: bunfig() },
     { path: 'app.config.ts', contents: appConfig(app) },
+    { path: VERIFY_FLOOR_FILE, contents: verifyFloor() },
     { path: 'types/scss.d.ts', contents: scssTypes() },
     { path: '.gitignore', contents: gitignore() },
     { path: '.env.development', contents: envDevelopment() },
-    {
-      path: 'packages/domain/package.json',
-      contents: domainPackage(app, 'domain', 'Pure types and constants, no I/O'),
-    },
-    ...packageShapeFiles(app, 'domain', 'Pure types and constants, no I/O'),
-    { path: 'packages/domain/src/index.ts', contents: domainIndex() },
-    { path: 'packages/domain/src/index.test.ts', contents: domainTest() },
-    {
-      path: 'packages/db/package.json',
-      contents: domainPackage(app, 'db', 'Entity re-exports and SQL migrations, no business logic'),
-    },
-    ...packageShapeFiles(app, 'db', 'Entity re-exports and SQL migrations, no business logic'),
-    { path: 'packages/db/src/index.ts', contents: dbIndex() },
-    { path: 'packages/db/src/schema.ts', contents: dbSchema(app, example) },
-    { path: 'packages/db/src/seed.ts', contents: dbSeed(app, example) },
-    { path: 'packages/db/migrations/0000_initial.sql', contents: migration(example) },
+    // Committed, and generated: `x env example` rewrites this file from `envSchema`, and the
+    // gate's `manifest` step fails with X_ENV_EXAMPLE_DRIFT when the two stop agreeing. A
+    // scaffold that shipped a hand-written one would fail its own first `x verify`.
+    { path: ENV_EXAMPLE_PATH, contents: envExampleSource() },
+    // One call per workspace package, in write order. Each owns its own files (`scaffold-i18n.ts`
+    // already did), so this list stays a table of contents rather than a second copy of every
+    // package's contents.
+    ...domainPackageFiles(app),
+    ...dbPackageFiles(app, example),
     ...i18nFiles(app, version),
-    {
-      path: 'packages/ui/package.json',
-      contents: domainPackage(app, 'ui', 'App components on @ultimat3/ui'),
-    },
-    ...packageShapeFiles(app, 'ui', 'App components on @ultimat3/ui'),
-    { path: 'packages/ui/src/index.ts', contents: uiIndex() },
-    { path: 'packages/ui/src/card.tsx', contents: uiCard() },
-    { path: 'packages/ui/src/card.module.scss', contents: uiCardStyle() },
-    {
-      path: 'packages/mcp/package.json',
-      contents: domainPackage(app, 'mcp', "The app's own MCP tools"),
-    },
-    ...packageShapeFiles(app, 'mcp', "The app's own MCP tools"),
-    { path: 'packages/mcp/src/index.ts', contents: mcpIndex(app) },
-    { path: 'packages/mcp/src/index.test.ts', contents: mcpTest() },
+    ...uiPackageFiles(app),
+    ...mcpPackageFiles(app),
   ];
 }

package/src/templates/scaffold-roles.ts

@@ -0,0 +1,68 @@
+// The one place a scaffolded app's roles live, decided rather than left to each feature to invent.
+// `defineRoles()` MERGES, so a second call in a feature folder is legal and silent — which is
+// exactly why the location has to ship: without a scaffolded file, "where do roles live?" has as
+// many answers as the app has folders, and the framework's two tracked apps already disagree.
+
+import type { GeneratedFile } from './naming';
+
+const rolesSource =
+  (): string => `// Who holds which permission, for the whole app. Roles are sugar: every one expands to a flat
+// permission set before any policy runs, so a rule never reasons about the hierarchy.
+//
+// ONE file, and it lives in shared/ — the leaf both site/ and app/ already import, and the one the
+// boot scan loads, so the map is filled before the first request. \`defineRoles()\` merges into that
+// map rather than replacing it, and refuses a role two modules define differently
+// (X_ROLE_REDEFINED, naming both declaration sites). A feature that needs a new grant adds it to a
+// role HERE; calling defineRoles() again from a feature folder works and is the drift this file
+// exists to prevent.
+//
+// \`x g policy <feature>\` declares \`<feature>:read\` and \`<feature>:write\`. Granting them is this
+// file's job — a permission no role holds is one no actor can ever exercise.
+
+import { defineRoles } from '@ultimat3/policy';
+
+export const roles = defineRoles({
+  member: {
+    description: 'Signed in. Reads the app surface.',
+    grants: ['dashboard:read'],
+  },
+  admin: {
+    description: 'Runs the app: the /admin surface, plus everything a member may do.',
+    grants: ['admin:read'],
+    inherits: ['member'],
+  },
+});
+`;
+
+const rolesTest =
+  (): string => `// The app's role map, expanded: what each role grants once inheritance is flattened, and which
+// roles hold a given permission. An undeclared role must grant nothing at all.
+import { expandRoles, rolesGranting } from '@ultimat3/policy';
+import { expect, unitTest } from '@ultimat3/testing';
+import { roles } from './roles';
+
+// The map is passed explicitly rather than read off the module-global one: a test that depended on
+// which module imported first would pass alone and fail inside a suite.
+
+unitTest('admin inherits every member grant and adds its own', () => {
+  expect(expandRoles(['member'], roles)).toEqual(['dashboard:read']);
+  expect(expandRoles(['admin'], roles)).toEqual(['admin:read', 'dashboard:read']);
+});
+
+unitTest('a role nobody declared grants nothing', () => {
+  expect(expandRoles(['visitor'], roles)).toEqual([]);
+});
+
+unitTest('every permission the app enforces is held by some role', () => {
+  expect(rolesGranting('dashboard:read', roles)).toEqual(['admin', 'member']);
+  expect(rolesGranting('admin:read', roles)).toEqual(['admin']);
+});
+`;
+
+/** `apps/web/shared/roles.ts` and its test. Written by `x new`, with or without the example slice. */
+export function rolesFiles(): readonly GeneratedFile[] {
+  return [
+    { path: 'apps/web/shared/roles.ts', contents: rolesSource() },
+    { path: 'apps/web/shared/roles.test.ts', contents: rolesTest() },
+  ];
+}

package/src/templates/scaffold-ui-package.ts

@@ -0,0 +1,56 @@
+// The generated app's `packages/ui`: one example component on top of @ultimat3/ui, so the app has
+// a worked instance of the semantic-token rule before it writes its own. Imported by `site/`, so
+// its byte budget is the landing page's.
+
+import type { GeneratedFile, NameSet } from './naming';
+import { packageShapeFiles, workspacePackageJson } from './scaffold-package-shape';
+
+const DESCRIPTION = 'App components on @ultimat3/ui';
+
+const uiIndex =
+  (): string => `// App components on top of @ultimat3/ui. Same byte budgets as shared/: this package is imported
+// by site/, so a chart library in here costs the landing page.
+export { Card } from './card';
+`;
+
+const uiCard = (): string => `import type { JSX } from 'solid-js';
+import styles from './card.module.scss';
+
+export interface CardProps {
+  readonly title: string;
+  readonly children?: JSX.Element;
+}
+
+export function Card(props: CardProps) {
+  return (
+    <section class={styles.card}>
+      <h2 class={styles.title}>{props.title}</h2>
+      {props.children}
+    </section>
+  );
+}
+`;
+
+const uiCardStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
+
+.card {
+  padding: tokens.space(4);
+  border-radius: tokens.radius('md');
+  background: tokens.role('surface-raised');
+  color: tokens.role('fg');
+}
+
+.title {
+  font-size: tokens.text('lg');
+  font-weight: tokens.weight('semibold');
+}
+`;
+
+/** Every file the `packages/ui` workspace ships, in the order `x new` writes them. */
+export const uiPackageFiles = (app: NameSet): readonly GeneratedFile[] => [
+  { path: 'packages/ui/package.json', contents: workspacePackageJson(app, 'ui', DESCRIPTION) },
+  ...packageShapeFiles(app, 'ui', DESCRIPTION),
+  { path: 'packages/ui/src/index.ts', contents: uiIndex() },
+  { path: 'packages/ui/src/card.tsx', contents: uiCard() },
+  { path: 'packages/ui/src/card.module.scss', contents: uiCardStyle() },
+];