@ultimat3/cli 11.3.0 → 13.0.0

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;