@ultimat3/cli 19.4.0 → 20.1.0

package/src/templates/scaffold-docs.ts

@@ -2,9 +2,11 @@
 // the bin/ shims and the optional dev compose. Separated from the config half so neither file has
 // to be scrolled to find the other — one file, one job applies to templates too. The image, its
 // ignore file, the production topology and the deploy page are `scaffold-container.ts`; the
-// `.claude/` harness that reads AGENTS.md is `scaffold-claude.ts`.
+// `.claude/` harness that reads AGENTS.md is `scaffold-claude.ts`; the one workflow is
+// `github/ci.yml.ts`.
 
 import { LINE_CEILING } from '../workspace-checks';
+import { githubFiles } from './github/ci.yml';
 import type { GeneratedFile, NameSet } from './naming';
 import { claudeFiles } from './scaffold-claude';
 import { containerFiles } from './scaffold-container';
@@ -19,7 +21,7 @@ not exist — five of these had an empty column and were each measured green on
 
 | Rule | Detail | Refused by |
 |---|---|---|
-| One gate | \`x verify\` — green means shippable. Never merge red. | the gate itself |
+| One gate | \`bin/check\` — \`x build\` and then \`x verify\`. Green means shippable; never merge red. | the gate itself, and \`.github/workflows/ci.yml\` on every push and pull request |
 | One way | generators, not hand-rolled files: \`x g resource\`, \`x g action\`, \`x g route\` | review |
 | Surfaces | \`site/\` is 0kb JS and may not import \`app/\`; \`shared/\` is a leaf | \`X_BOUNDARY_SITE_TO_APP\` |
 | Data | routes call actions and queries; only \`repo.ts\` touches the database | \`X_BOUNDARY_ROUTE_TO_DB\` |
@@ -28,11 +30,22 @@ not exist — five of these had an empty column and were each measured green on
 | Time | store UTC, format with an explicit IANA time zone | \`guards/unzoned-date.ts\` |
 | Strings | every user-facing string goes through \`t()\` | \`guards/untranslated-string.ts\` |
 | Colour | semantic tokens only, never a raw hex | \`guards/raw-colour.ts\` |
+| Interaction | a click is answered by a control — never a \`<div onClick>\`, and never a \`role=\` where the native tag exists | \`guards/semantic-interactive.ts\` |
+| Focus | \`outline: none\` replaces the ring in the same rule or the one beside it, or it does not remove it | \`guards/focus-visible.ts\` |
+| Images | every image carries width + height or an aspect-ratio, and the priority one is never \`loading="lazy"\` | \`guards/image-dimensions.ts\` |
+| Motion | animate \`transform\` and \`opacity\` — never a layout property, never \`transition: all\` | \`guards/animated-layout-property.ts\` |
+| Islands | every \`*.island.tsx\` has a sibling \`*.island.states.ts\`, so \`x shot --island\` can photograph its failures | \`guards/island-without-states.ts\` |
 | Size | one file, one job — ${LINE_CEILING} lines of reviewable logic, and split past it | \`X_FILE_TOO_LONG\` |
 
 \`guards/\` is yours: each file is one rule, discovered by \`x verify\` and run inside its
 \`boundaries\` step. Delete one to drop the rule, and \`x g guard <name>\` writes the next.
 
+The last five rows are about what this app is like to USE, and each is decidable from the file
+alone — which is why they are those five and not the many that are not. A role is a promise:
+\`role="button"\` obliges you to answer Space, Enter, focus and disabled, and the native element
+already does. Only \`transform\` and \`opacity\` animate without a layout pass. An image with no box
+moves everything under it when its bytes land.
+
 Size is a hard line and not a style note: past ${LINE_CEILING} lines a file has stopped being the
 unit of review, and \`x verify\` refuses it. The one exemption is a file that is nothing but re-exports —
 it has one job by construction, and its length tracks the API's size rather than its complexity;
@@ -43,7 +56,19 @@ see, and the type already fires — measured, \`price: 19.99\` in a seed is
 \`TS2322: Type 'number' is not assignable to type 'MoneyInput'\`. A guard that pretended to check
 it would be worse than the type that really does.
 
-Commands: \`x dev\`, \`x verify\`, \`x g <primitive>\`, \`x g guard <name>\`, \`x db branch create <name>\`, \`x doctor\`.
+\`bin/check\` is the gate and \`x verify\` is only its second half: the first is
+\`x build --target static\`, and the build is what writes the \`.x/build-stats.json\` the
+\`budgets\` step measures. Run \`x verify\` on a tree nobody has built and \`budgets\` is red with
+X_BUDGET_UNMEASURED — the gate reporting on a file that does not exist, not on your code.
+
+The platform's \`.dz/\` is ADDITIVE, in both directions. developerz.ai keeps its own files under
+\`.dz/maintainer/\` and \`.dz/pipeline/\`; nothing \`x new\` writes lands under \`.dz/\` and nothing
+here is generated from it. So the scaffold never clobbers a maintainer policy, the platform never
+clobbers \`AGENTS.md\`, \`bin/\`, \`.claude/\` or \`.github/\`, and deleting either side leaves the
+other exactly as it was.
+
+Commands: \`bin/setup\`, \`bin/dev\`, \`bin/check\`, \`x g <primitive>\`, \`x g guard <name>\`,
+\`x db branch create <name>\`, \`x doctor\`.
 
 Project notes for ${app.kebab}: replace this line with the conventions a newcomer could not guess.
 `;
@@ -52,7 +77,12 @@ const claude = (app: NameSet): string => `# CLAUDE.md
 
 ${app.kebab} — Ultimate app. Read AGENTS.md first; it is the same content in the same order.
 
-- Gate: \`x verify\` (add \`--json\` for machine output).
+- Gate: \`bin/check\` (add \`--json\` for machine output — it reaches both halves). It is
+  \`x build --target static\` and then \`x verify\`; \`x verify\` alone leaves \`budgets\` with
+  nothing to measure. \`.github/workflows/ci.yml\` runs \`bin/setup && bin/check\` on every push
+  and pull request, so CI and your terminal run the same two commands.
+- \`.dz/\` belongs to the developerz.ai platform and is additive both ways: the scaffold writes
+  nothing there, and nothing there is generated from this repo. Neither side clobbers the other.
 - Scaffold, do not hand-write: \`x g <kind> <name>\` — \`x g --help\` lists every kind, and is the
   only place that list is stated.
 - Destructive DB work goes in a branch: \`x db branch create <name>\`, never the shared dev DB.
@@ -72,7 +102,7 @@ Built with [Ultimate](https://github.com/developerz-ai/ultimate). Bun-only, Post
 \`\`\`sh
 bin/setup     # prerequisites, deps, env, the first migration, migrate, seed, the manifest
 bin/dev       # all roles in one process, embedded Postgres, /_x mounted
-bin/check     # the gate: typecheck, lint, boundaries, tests, drift, budgets
+bin/check     # the gate: a static build, then typecheck, lint, boundaries, tests, drift, budgets
 \`\`\`
 
 \`packages/db/migrations\` starts empty and \`x db gen\` is its only writer — \`bin/setup\` runs
@@ -91,6 +121,7 @@ with \`X_DB_DRIFT\`, and that is the fix it names.
 | \`packages/*\` | domain, db, i18n, ui, mcp |
 | \`app.config.ts\` | the one config file |
 | \`x.manifest.json\` | generated facts: routes, actions, jobs, policies |
+| \`.github/workflows/ci.yml\` | \`bin/setup\` then \`bin/check\`, on push and pull request |
 `;
 
 const binSetup = (): string => `#!/usr/bin/env bash
@@ -193,6 +224,10 @@ export function docsFiles(app: NameSet): readonly GeneratedFile[] {
     // The harness half of the same job AGENTS.md does. It lands in the app's own repo rather than
     // in a global config, so it is visible in the scaffold's diff and deletable in one line.
     ...claudeFiles(app),
+    // The same two commands `README.md` opens with, run by a machine that has never seen this
+    // repository. Registered here and not in `scaffold-repo.ts` because it is documentation of the
+    // gate in executable form, which is the job this file has.
+    ...githubFiles(app),
     ...containerFiles(app),
   ];
 }

package/src/templates/scaffold-guards.ts

@@ -6,9 +6,19 @@
 // (`packages/cli/src/guards.ts`). What was missing is any guard to discover. Four of the five are
 // here; the fifth, money-as-float, has no static signature and is answered by the `Money` type
 // instead — `scaffold-docs.ts` says so where an author reads it.
+//
+// The other five are about what the app is like to USE, which no row of `AGENTS.md` had ever been
+// about: a control a keyboard cannot reach, a focus ring taken away and not replaced, an image with
+// no box, an animation the compositor cannot run, and an island nobody has seen fail. Each is
+// statically decidable from the file alone — the reason those five and not the many that are not.
 
+import { animatedLayoutPropertyGuardFiles } from './guard-animated-layout-property';
 import { bareErrorGuardFiles } from './guard-bare-error';
+import { focusVisibleGuardFiles } from './guard-focus-visible';
+import { imageDimensionsGuardFiles } from './guard-image-dimensions';
+import { islandWithoutStatesGuardFiles } from './guard-island-without-states';
 import { rawColourGuardFiles } from './guard-raw-colour';
+import { semanticInteractiveGuardFiles } from './guard-semantic-interactive';
 import { untranslatedStringGuardFiles } from './guard-untranslated-string';
 import { unzonedDateGuardFiles } from './guard-unzoned-date';
 import type { GeneratedFile } from './naming';
@@ -19,8 +29,13 @@ import type { GeneratedFile } from './naming';
  * `x g guard <name>`, the same shape.
  */
 export const scaffoldGuardFiles = (): readonly GeneratedFile[] => [
+  ...animatedLayoutPropertyGuardFiles(),
   ...bareErrorGuardFiles(),
+  ...focusVisibleGuardFiles(),
+  ...imageDimensionsGuardFiles(),
+  ...islandWithoutStatesGuardFiles(),
   ...rawColourGuardFiles(),
+  ...semanticInteractiveGuardFiles(),
   ...untranslatedStringGuardFiles(),
   ...unzonedDateGuardFiles(),
 ];

package/src/templates/scaffold-repo.ts

@@ -5,6 +5,7 @@
 // container files scaffold-container.ts.
 
 import { ENV_EXAMPLE_PATH } from '@ultimat3/core';
+import { REQUIRED_BUN } from '../app-root';
 import { VERIFY_FLOOR_FILE } from '../verify-floor';
 import type { VerifyStepName } from '../verify-step';
 import type { GeneratedFile, NameSet } from './naming';
@@ -26,6 +27,25 @@ import { uiPackageFiles } from './scaffold-ui-package';
  */
 const BIOME_VERSION = '2.5.8';
 
+/**
+ * The checker a scaffolded app typechecks with, and it must not lag the one the FRAMEWORK is built
+ * and gated on: `@ultimat3/*` ships `.d.ts` emitted by this compiler, so an app pinned a major
+ * behind reads the types its own dependencies were written against through an older checker.
+ * It drifted for exactly the reason `BIOME_VERSION` did not — Biome's was spelled once as a
+ * constant and TypeScript's was a literal buried in a dependency block, so the framework moved to
+ * 7.x and every `x new` kept scaffolding `^6.0.3`. `scaffold-repo.test.ts` now pins this against
+ * the repo's own root `package.json`, so the next bump cannot leave the scaffold behind in silence.
+ */
+const TYPESCRIPT_VERSION = '^7.0.2';
+
+// `engines.bun` is `REQUIRED_BUN`, the floor the SHIPPED `x` enforces
+// (`packages/cli/src/app-root.ts`), and not a second literal. It was one: `>=1.3.0`, a whole minor
+// BELOW the CLI the app then runs, so on a box with Bun 1.3.x `bun install` succeeded and the very
+// next line of `bin/setup` died `X_BUN_VERSION: Bun 1.3.14 is older than the required 1.4.0` — a
+// floor admitting a runtime the app's own first command refuses. Interpolated, the two cannot
+// disagree; `scripts/bun-pin.test.ts` reads the emitted string as one more pin site, and
+// `github/ci.yml.ts` pins the workflow's Bun to the same constant.
+//
 // `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`,
 // the `manifest` verify step and every production boot with X_APP_PACKAGE_INVALID.
@@ -54,7 +74,7 @@ const rootPackage = (app: NameSet, version: string): string => `{
     "@electric-sql/pglite": "^0.5.4",
     "@types/bun": "^1.4.0",
     "@ultimat3/testing": "^${version}",
-    "typescript": "^6.0.3"
+    "typescript": "${TYPESCRIPT_VERSION}"
   },
   "dependencies": {
     "@ultimat3/action": "^${version}",
@@ -78,7 +98,7 @@ const rootPackage = (app: NameSet, version: string): string => `{
     "solid-js": "1.9.14"
   },
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=${REQUIRED_BUN}"
   }
 }
 `;