@ultimat3/cli 11.3.0 → 12.0.0

package/src/templates/scaffold-docs.ts

@@ -63,9 +63,9 @@ Built with [Ultimate](https://github.com/developerz-ai/ultimate). Bun-only, Post
 ## 🚀 Start
 
 \`\`\`sh
-bin/setup     # prerequisites, deps, env, the first migration, migrate, seed
-x dev         # all roles in one process, embedded Postgres, /_x mounted
-x verify      # the gate: typecheck, lint, boundaries, tests, drift, budgets
+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
 \`\`\`
 
 \`packages/db/migrations\` starts empty and \`x db gen\` is its only writer — \`bin/setup\` runs
@@ -104,7 +104,13 @@ bunx x db migrate "$@"
 # \`postgres:\` DATABASE_URL and so dies on a clone with no Postgres — one line after reporting a
 # successful migration.
 bunx x db seed
-echo "setup complete — next: x dev"
+# The file \`AGENTS.md\` line 3 tells an agent facts live in, and \`x dev\` prints the path of. It
+# is a projection of the loaded app, so \`x new\` cannot write it — node_modules does not exist
+# yet — and nothing else ever ran the command: after \`x new\`, \`bin/setup\` and all 13
+# generators, \`find . -name '*.manifest.json'\` returned nothing while \`x verify\` reported
+# \`\u2713 manifest\`. \`x verify\`'s manifest step now refuses its absence (X_MANIFEST_MISSING).
+bunx x manifest
+echo "setup complete — next: bin/dev"
 `;
 
 const binDev = (): string => `#!/usr/bin/env bash

package/src/templates/scaffold-http.ts

@@ -0,0 +1,84 @@
+// The scaffold's answer to "how does this server bind, and what does it admit?", which it did not
+// have. `configureHttp()` is the one registration site an app has for CORS origins, the body
+// limit, the request deadline, the in-flight ceiling and the rate-limit buckets — and until it
+// shipped, the only `HttpConfig` any process built was a fixed literal inside `@ultimat3/cli`.
+//
+// `DEFAULT_CORS.origins` is `[]`, so a scaffolded app refuses every cross-origin browser call. The
+// most common homework-scale need — a Vite front end on `localhost:5173` calling the app — was
+// inexpressible; now it is one uncommented line, and this file is where an agent finds it.
+
+import type { GeneratedFile, NameSet } from './naming';
+
+const httpConfig = (
+  app: NameSet,
+): string => `// What this app declares about HTTP. Module scope IS the wiring: the boot scan imports every
+// module under \`apps/*\` before a listener binds, and \`x dev\` and the container both read the
+// configured value back at start — the same seam \`app/auth/dev-actor.ts\` installs through.
+//
+// The BOOT lays its own facts over whatever this says: \`port\`, \`hostname\`, \`dev\`, \`buildId\`,
+// \`signInPath\`, \`trustProxy\`, \`trustedProxyHops\` and \`rateLimit.scope\` are all facts about the
+// PROCESS, so writing one here is a type error rather than a value silently overwritten at the
+// next boot.
+
+import { configureHttp } from '@ultimat3/http';
+
+configureHttp({
+  // EMPTY by default, and that is a refusal rather than an oversight: an origin list is a list of
+  // sites allowed to make credentialed calls with this app's cookies, and a framework may not
+  // guess one. A browser app served from another origin — a Vite dev server, a separate marketing
+  // site — goes here, exactly spelled, scheme and port included:
+  //
+  //   cors: { origins: ['http://localhost:5173'] },
+  //
+  // \`credentials\` is \`true\` by default, and \`'*'\` with credentials is the one combination a
+  // browser refuses — \`@ultimat3/http\` refuses it here instead, at the moment you can act on it.
+  cors: { origins: [] },
+  // The two bounds a request is measured against. Both are the framework's defaults spelled out,
+  // so raising one for an endpoint that really does take a 4 MB CSV or five minutes is an edit to
+  // a number that is already in front of you rather than a search for the knob.
+  bodyLimitBytes: 1024 * 1024,
+  requestTimeoutMs: 30_000,
+});
+
+/** Named so the module has an export; importing it for the side effect alone is the wiring. */
+export const ${app.camel}Http = 'configured';
+`;
+
+const httpConfigTest =
+  (): string => `// The declaration reached the registry. \`configureHttp()\` is a module-scope side effect, so the
+// only thing that can go wrong is nobody importing the module — which is exactly how a shipped app
+// rendered every string as ⟦key⟧ for a whole release (issue #249), one seam along.
+import { configuredHttp, resetHttpConfig } from '@ultimat3/http';
+import { expect, unitTest } from '@ultimat3/testing';
+import './http';
+
+unitTest('importing the module IS the registration', () => {
+  const declared = configuredHttp();
+  expect(declared).toBeDefined();
+  // The list is empty on a fresh scaffold and that is the shipped default; what is asserted is
+  // that the KEY reaches the boot, so adding an origin to it takes effect.
+  expect(declared?.cors?.origins).toEqual([]);
+});
+
+unitTest('the boot-owned keys are absent — the boot measures them, an app can only guess', () => {
+  const declared = configuredHttp() ?? {};
+  for (const key of ['port', 'hostname', 'dev', 'buildId', 'signInPath']) {
+    expect({ key, declared: Object.hasOwn(declared, key) }).toEqual({ key, declared: false });
+  }
+});
+
+// The registration is process-global, so a suite that left it set would hand the next file this
+// app's config. \`resetHttpConfig()\` is the seam; this is the one place it is called.
+unitTest('and it is resettable, so no test file inherits the server config of another', () => {
+  resetHttpConfig();
+  expect(configuredHttp()).toBeUndefined();
+});
+`;
+
+/** `apps/web/app/http.ts` and its test. Written by `x new`, with or without the example slice. */
+export function httpFiles(app: NameSet): readonly GeneratedFile[] {
+  return [
+    { path: 'apps/web/app/http.ts', contents: httpConfig(app) },
+    { path: 'apps/web/app/http.test.ts', contents: httpConfigTest() },
+  ];
+}

package/src/templates/scaffold-repo.ts

@@ -82,6 +82,21 @@ const rootPackage = (app: NameSet, version: string): string => `{
 }
 `;
 
+/**
+ * `"incremental": true` is ONE line and it is the difference between a 4.9s typecheck and a 92s
+ * one. `x verify`'s first step is `tsc -b`, and `-b` decides "up to date?" by comparing emitted
+ * OUTPUTS against inputs — with `noEmit` and no `composite`/`references`, the output it looks for
+ * is an `app.config.js` that will never exist (`Project 'tsconfig.json' is out of date because
+ * output file 'app.config.js' does not exist`), so every run rebuilt the whole program from
+ * scratch, forever. Measured on a 166-file scaffold with no source change between runs: 92s wall
+ * / 43s user CPU without it, 4.9s / 8.8s warm with it, and the whole gate at 12s rather than
+ * 24-71s. This was the only tree in the framework without incremental typechecking — the repo
+ * root has 32 `references` and `examples/dummy/tsconfig.json` sets `composite`.
+ *
+ * The note lives HERE and not in the emitted file, for the reason `biome.json` below gives: an
+ * app author has no use for eight lines of framework archaeology in their own tsconfig, and
+ * `*.tsbuildinfo` is already in the scaffold's `.gitignore`.
+ */
 const rootTsconfig = (app: NameSet): string => `{
   "compilerOptions": {
     "target": "ES2023",
@@ -101,6 +116,7 @@ const rootTsconfig = (app: NameSet): string => `{
     "isolatedModules": true,
     "skipLibCheck": true,
     "noEmit": true,
+    "incremental": true,
     "resolveJsonModule": true,
     "jsx": "preserve",
     "jsxImportSource": "solid-js"
@@ -258,6 +274,10 @@ const SCAFFOLD_FLOOR: readonly VerifyStepName[] = [
   'eval',
   'drift',
   'budgets',
+  // Always applicable to a scaffolded app — it has an `app.config.ts`, roles and two guarded
+  // routes — so a run that reports it skipped is a gate that lost the step, not an app with
+  // nothing to check. It is the step that would have caught the 500 `x new` used to ship.
+  'policy',
   'manifest',
 ];
 

package/src/templates/scaffold-roles.ts

@@ -19,7 +19,15 @@ const rolesSource =
 // \`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';
+import { definePermissions, defineRoles } from '@ultimat3/policy';
+
+// DECLARED before it is granted, and that order is the whole point. \`can()\` calls
+// \`assertPermission\`, which refuses a name no \`definePermissions()\` call registered
+// (X_PERMISSION_UNKNOWN) — and \`defineRoles()\` does NOT: it took \`grants: ['dashboard:read']\`
+// in silence while nothing declared it, so every scaffolded app answered HTTP 500 on /dashboard
+// and /admin from its first \`x dev\`, under a green gate. A permission a role grants and a
+// permission a route requires both belong here.
+export const appPermissions = definePermissions(['admin:read', 'dashboard:read']);
 
 export const roles = defineRoles({
   member: {
@@ -37,9 +45,9 @@ export const roles = defineRoles({
 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 { expandRoles, isKnownPermission, rolesGranting } from '@ultimat3/policy';
 import { expect, unitTest } from '@ultimat3/testing';
-import { roles } from './roles';
+import { appPermissions, 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.
@@ -57,6 +65,26 @@ 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']);
 });
+
+// The assertion whose absence shipped a 500. Expansion above proves the MAP is right and says
+// nothing about the registry \`can()\` actually consults: a grant naming a permission no
+// \`definePermissions()\` declared expands perfectly and then throws X_PERMISSION_UNKNOWN on the
+// first request to the route that requires it.
+unitTest('every granted permission is in the registry can() asks', () => {
+  for (const permission of new Set(Object.values(roles).flatMap((role) => role.grants))) {
+    expect({ permission, known: isKnownPermission(permission) }).toEqual({
+      permission,
+      known: true,
+    });
+  }
+});
+
+unitTest('the routes this app ships require permissions this app declares', () => {
+  // The two \`defineRoute({ policy: { permission } })\` values \`x new\` writes. \`RouteGuard\`
+  // keeps a bare string, so nothing but this holds them to the declared set.
+  expect(appPermissions.has('dashboard:read')).toBe(true);
+  expect(appPermissions.has('admin:read')).toBe(true);
+});
 `;
 
 /** `apps/web/shared/roles.ts` and its test. Written by `x new`, with or without the example slice. */

package/src/verify-checks.ts

@@ -19,6 +19,7 @@ import { checkAppBoundaries } from './app-boundaries';
 import { envExampleFindings } from './app-env';
 import { appManifest, readAppManifest } from './app-manifest';
 import { OPENAPI_FILE, openApiJson } from './app-openapi';
+import { policyFindings } from './app-permissions';
 import { APP_CONFIG_FILE } from './app-root';
 import { checkBudgets, readBuildStats } from './budgets';
 import { checkDestructiveMigrations } from './db-destructive';
@@ -265,6 +266,15 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     applies: async (ctx) => existsSync(join(ctx.root, APP_CONFIG_FILE)),
     run: async (ctx) => fromFindings(await catalogFindings(ctx.root)),
   },
+  {
+    name: 'policy',
+    summary: 'every permission this app grants or requires is one it declares',
+    // A repo with no `app.config.ts` is the framework monorepo, which declares no roles and
+    // registers no routes — SKIPPED there, never passed, for the reason `i18n` gives: a step that
+    // answers `ok` about nothing is the vacuous green these checks exist to refuse.
+    applies: async (ctx) => existsSync(join(ctx.root, APP_CONFIG_FILE)),
+    run: async (ctx) => fromFindings(await policyFindings(ctx.root)),
+  },
   {
     name: 'manifest',
     summary: 'the files an agent reads: generated facts, hand-written conventions, the env example',
@@ -283,6 +293,7 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     async run(ctx) {
       const agents = await checkAgentsMd(ctx.root);
       const findings = [
+        ...manifestMissingFindings(ctx.root),
         ...(await driftFindings(ctx.root)),
         ...(await envExampleFindings(ctx.root)),
         ...floorProblemFindings(await readVerifyFloor(ctx.root)),
@@ -312,6 +323,31 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
   },
 ];
 
+/**
+ * The half that had never been asked: is the file there at all? `driftFindings` returns nothing
+ * when it is absent — correctly, it has nothing to compare — and `AGENTS.md` line 3 tells an agent
+ * that facts live in `x.manifest.json`, `x dev` prints its path, and `x manifest` is the only
+ * thing that writes it. Nothing ran it: after `x new`, `bin/setup` and all thirteen generators,
+ * `find . -name '*.manifest.json'` returned nothing while this step reported green (#F7).
+ *
+ * An app root, never this repo: the framework monorepo emits `framework.manifest.json` and has no
+ * `x.manifest.json` to be missing, so the `app.config.ts` is what decides — the same discriminator
+ * `drift`, `budgets`, `seo`, `i18n` and `policy` each use.
+ */
+function manifestMissingFindings(root: string): readonly Finding[] {
+  if (!existsSync(join(root, APP_CONFIG_FILE))) return [];
+  if (existsSync(join(root, MANIFEST_FILENAME))) return [];
+  return [
+    {
+      code: 'X_MANIFEST_MISSING',
+      cause: `${MANIFEST_FILENAME} does not exist, so every fact an agent reads about this app — route table, action schemas, policies, error codes — is unavailable`,
+      fix: 'x manifest',
+      docs: ERROR_DOCS_URL,
+      at: MANIFEST_FILENAME,
+    },
+  ];
+}
+
 /** `assertNoDrift` throws `X_MANIFEST_DRIFT`; a step reports, so the error becomes a finding. */
 async function driftFindings(root: string): Promise<readonly Finding[]> {
   const path = join(root, MANIFEST_FILENAME);

package/src/verify-step.ts

@@ -41,6 +41,14 @@ export const VERIFY_STEP_NAMES = [
   // registries that load filled. Until it existed, an app could ship every user-facing string as
   // `⟦key⟧` with `x verify` green, because nothing in the gate ever asked (issue #249).
   'i18n',
+  // Twentieth, by the same test `seo` and `i18n` each passed: a rider must ask the SAME question
+  // off the same data, and "was this import legal?" is not "does the permission this app grants
+  // and requires exist?". Reported under `budgets` it would hand the reader a byte budget for an
+  // authz defect (axiom 4). Until it existed, `x new` shipped an app that answered HTTP 500 with
+  // X_PERMISSION_UNKNOWN on two of its three routes under a green gate: `defineRoles()` accepts an
+  // undeclared grant in silence and `RouteGuard.permission` is a bare string. It costs no second
+  // app load — `budgets` already imported every module, and this reads the registries that filled.
+  'policy',
   'manifest',
   'roadmap',
 ] as const;