@ultimat3/cli 1.1.0 → 2.0.0

package/src/templates/policy.ts

@@ -4,16 +4,16 @@
 
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
+import { wrapList } from './wrap';
 
 /** Biome would rewrap this itself, so the generator emits the already-formatted form. */
-const permissionSet = (feature: NameSet): string => {
-  const read = `'${feature.kebab}:read'`;
-  const write = `'${feature.kebab}:write'`;
-  const line = `export const ${feature.camel}Permissions = definePermissions([${read}, ${write}]);`;
-  return line.length <= 100
-    ? line
-    : `export const ${feature.camel}Permissions = definePermissions([\n  ${read},\n  ${write},\n]);`;
-};
+const permissionSet = (feature: NameSet): string =>
+  wrapList(
+    '',
+    `export const ${feature.camel}Permissions = definePermissions([`,
+    [`'${feature.kebab}:read'`, `'${feature.kebab}:write'`],
+    ']);',
+  );
 
 const policySource = (
   feature: NameSet,
@@ -67,38 +67,45 @@ export const can${feature.pascal}Write = can<${feature.pascal}Scope>(
 );
 `;
 
-const policyTest = (feature: NameSet): string => `import { testActor } from '@ultimat3/policy';
+const policyTest = (
+  feature: NameSet,
+): string => `// The ${feature.kebab} rules, from the DENIAL side: anonymous, cross-org, and the actor holding
+// only read. A policy whose tests all pass is a policy nobody has tried to get past.
+import { testActor } from '@ultimat3/policy';
 import { expect, unitTest } from '@ultimat3/testing';
 import { can${feature.pascal}Read, can${feature.pascal}Write } from './policy';
 
 const org = '00000000-0000-4000-8000-000000000002';
 const otherOrg = '00000000-0000-4000-8000-000000000009';
 
-// Direct grants rather than roles: the role map is app-global and defineRoles() replaces it
-// wholesale, so a generated test that installed one would decide authz for every other test in
-// the process. \`permissions\` is the same check one layer down.
-const reader = testActor('reader', { orgId: org, permissions: ['${feature.kebab}:read'] }).actor;
-const writer = testActor('writer', {
-  orgId: org,
-  permissions: ['${feature.kebab}:read', '${feature.kebab}:write'],
-}).actor;
-const outsider = testActor('outsider', {
-  orgId: otherOrg,
-  permissions: ['${feature.kebab}:read', '${feature.kebab}:write'],
-}).actor;
+// Direct grants rather than roles: defineRoles() MERGES into one app-global map that outlives this
+// file, so a role installed here would still be granting permissions to every later test in the
+// process — and a second test declaring the same name differently is X_ROLE_REDEFINED rather than
+// an override. The app's roles live in apps/web/shared/roles.ts, once. \`permissions\` is the same
+// check one layer down.
+// The two grants and the org, each named once. Not decoration: every assertion below then carries
+// the feature's own name and still fits the formatter's width, whatever that name is — a generated
+// file the app's \`lint\` step rewrites is a red gate over code nobody typed.
+const read = '${feature.kebab}:read';
+const write = '${feature.kebab}:write';
+const input = { orgId: org };
+
+const reader = testActor('reader', { orgId: org, permissions: [read] }).actor;
+const writer = testActor('writer', { orgId: org, permissions: [read, write] }).actor;
+const outsider = testActor('outsider', { orgId: otherOrg, permissions: [read, write] }).actor;
 
 unitTest('${feature.camel} read denies anonymous and cross-org actors', async () => {
-  await expect(can${feature.pascal}Read).toDenyPolicy({ actor: null, input: { orgId: org } });
-  await expect(can${feature.pascal}Read).toDenyPolicy({ actor: outsider, input: { orgId: org } });
-  await expect(can${feature.pascal}Read).not.toDenyPolicy({ actor: reader, input: { orgId: org } });
+  await expect(can${feature.pascal}Read).toDenyPolicy({ actor: null, input });
+  await expect(can${feature.pascal}Read).toDenyPolicy({ actor: outsider, input });
+  await expect(can${feature.pascal}Read).not.toDenyPolicy({ actor: reader, input });
 });
 
-unitTest('${feature.camel} write denies an actor holding only the read grant', async () => {
+unitTest('${feature.camel} write denies the read-only actor', async () => {
   // The outsider holds the grant and is still denied: the predicate is a second, independent
   // gate, and this is the assertion that fails if someone deletes it.
-  await expect(can${feature.pascal}Write).toDenyPolicy({ actor: reader, input: { orgId: org } });
-  await expect(can${feature.pascal}Write).toDenyPolicy({ actor: outsider, input: { orgId: org } });
-  await expect(can${feature.pascal}Write).not.toDenyPolicy({ actor: writer, input: { orgId: org } });
+  await expect(can${feature.pascal}Write).toDenyPolicy({ actor: reader, input });
+  await expect(can${feature.pascal}Write).toDenyPolicy({ actor: outsider, input });
+  await expect(can${feature.pascal}Write).not.toDenyPolicy({ actor: writer, input });
 });
 
 unitTest('${feature.camel} rules name the permission they require', () => {

package/src/templates/query.ts

@@ -5,6 +5,8 @@
 import type { FeatureTarget } from './entity';
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
+import { sliceFoundation } from './slice-foundation';
+import { wrapImport } from './wrap';
 
 /** A live read always fans out fresh, so a TTL on it would only ever be dead configuration. */
 const cacheLine = (feature: NameSet, live: boolean): string =>
@@ -20,7 +22,10 @@ const querySource = (
 
 import { from, query, t } from '@ultimat3/query';
 import type { ${feature.pascal} } from '../entity';
-import { can${feature.pascal}Read${live ? '' : `, ${feature.camel}Tag`} } from '../policy';
+${wrapImport(
+  live ? [`can${feature.pascal}Read`] : [`can${feature.pascal}Read`, `${feature.camel}Tag`],
+  '../policy',
+)}
 import * as repo from '../repo';
 
 export const ${name.camel} = query({
@@ -28,7 +33,7 @@ export const ${name.camel} = query({
   policy: can${feature.pascal}Read,
   live: ${String(live)},${cacheLine(feature, live)}
   // Opt-in, unlike an action's tool: a read hands rows to an agent, so silence exposes nothing.
-  mcp: { expose: true, description: '${name.raw} — generated, edit the description' },
+  mcp: { expose: true, description: '${name.raw} — edit this description' },
   sql: ({ orgId, limit }) =>
     // \`feature.table\`, not the kebab plural: \`from()\` quotes the identifier into the SQL text,
     // and the entity created the table as snake_case.
@@ -45,7 +50,9 @@ export const ${name.camel} = query({
 
 const queryTest = (name: NameSet, feature: NameSet, live: boolean): string => {
   const wrapper = live ? 'liveTest' : 'unitTest';
-  return `import { testActor } from '@ultimat3/policy';
+  return `// ${name.camel}: the shape it reads, the policy it asserts, and the actor it refuses. The read is
+// declarative, so what a test can get wrong is the authz, and that is what this pins.
+import { testActor } from '@ultimat3/policy';
 import { sourceFor } from '@ultimat3/query';
 import { expect, ${wrapper} } from '@ultimat3/testing';
 import { ${name.camel} } from './${name.kebab}';
@@ -74,8 +81,16 @@ ${wrapper}('${name.camel} is bounded and TOTALLY ordered', async () => {
   // The SQL text is the contract an agent reads to self-correct, so assert on it, not on a
   // shape. \`sourceFor\` is the one read path — it parses the input and builds the source exactly
   // as a request does. \`actor: null\` gives the call a context of its own rather than borrowing
-  // an ambient one, and \`enforce: false\` leaves the policy to the test below.
-  const source = await sourceFor(target, { orgId, limit: 50 }, { actor: null, enforce: false });
+  // an ambient one, and \`unenforced\` states WHY the policy is skipped: the escape hatch takes a
+  // written reason, never a boolean, because a boolean reads exactly like forgetting the policy.
+  const source = await sourceFor(
+    target,
+    { orgId, limit: 50 },
+    {
+      actor: null,
+      unenforced: 'a scaffolded test asserts the SQL text; the policy is asserted separately',
+    },
+  );
   const { sql } = source.toSQL();
   const text = sql.toLowerCase();
   expect(text).toContain('order by');
@@ -110,6 +125,10 @@ export function queryFiles(rawName: string, target: QueryOptions): readonly Gene
   const live = target.live === true;
   const dir = `${target.surfaceDir}/${target.feature}/${live ? 'live' : 'queries'}`;
   return [
+    // A read declares the row type it returns (`../entity`), the rule that admits it (`../policy`)
+    // and the one module allowed to query the table (`../repo`) — all three are the slice's, and
+    // `--live` changes only which directory this file lands in.
+    ...sliceFoundation(target, ['entity', 'policy']),
     { path: `${dir}/${name.kebab}.ts`, contents: querySource(name, feature, live) },
     { path: `${dir}/${name.kebab}.test.ts`, contents: queryTest(name, feature, live) },
   ];

package/src/templates/resource.ts

@@ -27,11 +27,16 @@ import * as repo from './repo';
 /** Derived from the row, never restated: a new column reaches this input without an edit here. */
 export type Create${feature.pascal}Input = Omit<${feature.pascal}, 'id' | 'createdAt'>;
 
-export async function create(input: Create${feature.pascal}Input): Promise<${feature.pascal}> {
+/** The row, aliased once, so every signature below reads at one width whatever the feature is
+ * called — a generated file the app's own formatter rewrites is a red \`lint\` over code nobody
+ * typed. */
+type Row = ${feature.pascal};
+
+export async function create(input: Create${feature.pascal}Input): Promise<Row> {
   return repo.insert(input);
 }
 
-export async function require${feature.pascal}(id: string): Promise<${feature.pascal}> {
+export async function require${feature.pascal}(id: string): Promise<Row> {
   const row = await repo.byId(id);
   if (row === undefined) throw new ${feature.pascal}NotFoundError({ id });
   return row;
@@ -40,7 +45,9 @@ export async function require${feature.pascal}(id: string): Promise<${feature.pa
 
 const serviceTest = (
   feature: NameSet,
-): string => `import { expect, unitTest } from '@ultimat3/testing';
+): string => `// The ${feature.kebab} feature's failure, pinned: a code an agent can match on, a cause naming
+// the row, and a fix that is an instruction. A bare Error would satisfy none of the three.
+import { expect, unitTest } from '@ultimat3/testing';
 import { ${feature.pascal}NotFoundError } from './errors';
 
 unitTest('${feature.pascal}NotFoundError carries a code, a cause and a fix', () => {
@@ -69,9 +76,10 @@ export function ${feature.pascal}List(props: ${feature.pascal}ListProps) {
   return (
     <ul class={styles.list}>
       <For each={props.rows} fallback={<li>{t('app.${feature.kebab}.empty')}</li>}>
-        {/* The item arrives as an accessor: reading it inside the row is what keeps the update
-            surgical instead of re-rendering the list. */}
-        {(row) => <li class={styles.item}>{row().title}</li>}
+        {/* <For> is keyed by value identity, so the item arrives directly and a row is only
+            re-created when its value changes. <Index> is the accessor-shaped one — reach for it
+            when the list is a fixed set of slots whose contents mutate. */}
+        {(row) => <li class={styles.item}>{row.title}</li>}
       </For>
     </ul>
   );
@@ -82,14 +90,14 @@ const uiStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
 
 .list {
   display: grid;
-  gap: tokens.$space-2;
+  gap: tokens.space(2);
 }
 
 .item {
-  padding: tokens.$space-2;
-  border-radius: tokens.$radius-sm;
-  background: tokens.$surface-raised;
-  color: tokens.$text-primary;
+  padding: tokens.space(2);
+  border-radius: tokens.radius('sm');
+  background: tokens.role('surface-raised');
+  color: tokens.role('fg');
 }
 `;
 

package/src/templates/route.ts

@@ -1,6 +1,8 @@
 // `x g route <path>` — a URL, its render mode, its metadata, its offline strategy and its budget.
-// The generated test pins metadata presence and the offline fallback: a route with no title is an
-// SEO regression and a route with no fallback is a blank screen on a train.
+// Two generated tests, because the gate types a test by its filename: `page.test.ts` pins metadata
+// presence and the budget declaration on the `unit` step, `page.e2e.test.ts` pins the offline
+// fallback on the `e2e` step. A route with no title is an SEO regression and a route with no
+// fallback is a blank screen on a train.
 
 import { catalogJson } from './catalog-json';
 import { catalogPath, resolveLocales } from './locales';
@@ -9,7 +11,14 @@ import { kebab, pascal, titleKey } from './naming';
 
 export type Surface = 'site' | 'app';
 
-const RENDER: Record<Surface, string> = { site: 'isr', app: 'stream' };
+/**
+ * `ssr` on `app/`, not `stream`, for the reason `scaffold-app.ts`'s dashboard already states:
+ * `stream` sets `needsSuspense`, the framework ships no hole marker, and `defineRoute` therefore
+ * throws `X_ROUTE_MODE_INVALID` at import. That is not a failing page — it is a page that registers
+ * NO route at all, so every `x g route --surface app` and every `x g resource` scaffolded a URL
+ * that was absent from `x routes`, from the manifest and from `budgets`. Ship the mode that works.
+ */
+const RENDER: Record<Surface, string> = { site: 'isr', app: 'ssr' };
 const HYDRATE: Record<Surface, string> = { site: 'never', app: 'visible' };
 const OFFLINE: Record<Surface, string> = { site: 'precache', app: 'runtime' };
 /** Structured, not a literal string: the route and the test that pins it read the same fact. */
@@ -22,12 +31,35 @@ const budgetLiteral = (surface: Surface): string =>
 /** `isr` without a trigger is `static` wearing a costume — @ultimat3/render rejects it at boot. */
 const REVALIDATE: Record<Surface, string> = { site: "\n  revalidate: { ttl: '1h' },", app: '' };
 
-const routeDir = (surface: Surface, path: string): string =>
-  `apps/web/${surface}/${path
+/** `[slug]`, `[...rest]` — the repo's own convention (`app/posts/[id]`, `site/blog/[slug]`). */
+const DYNAMIC_SEGMENT = /^\[(?<spread>\.\.\.)?(?<name>[^\]]+)\]$/;
+
+/**
+ * One URL segment. `kebab()` strips `[` and `]` along with every other non-alphanumeric, so
+ * `x g route "posts/[slug]"` scaffolded `apps/web/app/posts/slug/page.tsx` — a different, STATIC
+ * route — and reported `ok:true` with no warning. Only the parameter NAME is kebabed now.
+ */
+export const routeSegment = (part: string): string => {
+  const match = DYNAMIC_SEGMENT.exec(part);
+  if (match === null) return kebab(part);
+  return `[${match.groups?.['spread'] ?? ''}${kebab(match.groups?.['name'] ?? '')}]`;
+};
+
+const segmentsOf = (path: string): readonly string[] =>
+  path
     .split('/')
     .filter((part) => part.length > 0)
-    .map(kebab)
-    .join('/')}`;
+    .map(routeSegment);
+
+/** Every `[param]` the URL declares, in order — what a render actually hands the page. */
+export const routeParams = (path: string): readonly string[] =>
+  segmentsOf(path).flatMap((part) => {
+    const name = DYNAMIC_SEGMENT.exec(part)?.groups?.['name'];
+    return name === undefined ? [] : [name];
+  });
+
+const routeDir = (surface: Surface, path: string): string =>
+  `apps/web/${surface}/${segmentsOf(path).join('/')}`;
 
 const pageSource = (surface: Surface, path: string): string => {
   const name = pascal(
@@ -69,28 +101,55 @@ const styleSource =
 @use '@ultimat3/ui/tokens' as tokens;
 
 .page {
-  padding: tokens.$space-6;
-  background: tokens.$surface-base;
-  color: tokens.$text-primary;
+  padding: tokens.space(6);
+  background: tokens.role('bg');
+  color: tokens.role('fg');
 }
 `;
 
+/** A value for a `[param]`, distinct per parameter so a two-param URL reads unambiguously. */
+const sampleValue = (name: string): string => `${name}-1`;
+
+/** The URL a render would actually match, with every `[param]` filled in. */
+const sampleUrl = (path: string): string =>
+  segmentsOf(path)
+    .map((part) => {
+      const name = DYNAMIC_SEGMENT.exec(part)?.groups?.['name'];
+      return name === undefined ? part : sampleValue(name);
+    })
+    .join('/');
+
+/** The params object that URL implies. `{}` was a lie for every dynamic route. */
+const paramsLiteral = (path: string): string => {
+  const params = routeParams(path);
+  if (params.length === 0) return '{}';
+  return `{ ${params.map((name) => `${name}: '${sampleValue(name)}'`).join(', ')} }`;
+};
+
 const routeTest = (
   surface: Surface,
   path: string,
-): string => `import { e2eTest, expect, unitTest } from '@ultimat3/testing';
+): string => `// /${path}'s declaration, on the \`unit\` step: metadata that renders, and the render mode,
+// offline strategy and budget it promises. A route with no title is an SEO regression.
+import { metaContextFor, routeDataFor } from '@ultimat3/render';
+import { expect, unitTest } from '@ultimat3/testing';
 import { config } from './page';
 
+// What a render gives this route: the URL it matched and the params in it. \`routeDataFor\` is the
+// one resolver — with no \`load\` the context IS the data, and with one the loader decides — so a
+// test asserts on the same object the page component and \`meta\` are handed in production.
+const ctx = { params: ${paramsLiteral(path)}, url: 'https://example.test/${sampleUrl(path)}' };
+
 unitTest('/${path} declares metadata', async () => {
   expect(config.kind).toBe('route');
   // meta() takes the route's data and always resolves — awaiting is the one shape, whether the
   // declaration was written sync or async.
-  const meta = await config.meta({});
+  const meta = await config.meta(metaContextFor(ctx, await routeDataFor(config, ctx)));
   expect(meta.title ?? '').not.toBe('');
   expect(meta.description ?? '').not.toBe('');
 });
 
-unitTest('/${path} declares a render mode, an offline strategy and a budget', () => {
+unitTest('/${path} declares its render, offline and budget', () => {
   expect(config.render).toBe('${RENDER[surface]}');
   expect(config.offline).toBe('${OFFLINE[surface]}');
   // budget is always on the descriptor, so pin the number: presence cannot fail.
@@ -100,9 +159,24 @@ unitTest('/${path} declares a render mode, an offline strategy and a budget', ()
 unitTest('/${path} stays inside its byte budget declaration', () => {
   expect(config.budget.js).toBe('${BUDGET[surface].js}');
 });
+`;
 
-e2eTest('/${path} renders offline from its fallback', async ({ page, offline }) => {
-  await page.goto('/${path}');
+/**
+ * The offline assertion, in its own file — and that is the whole point of the split. The gate
+ * types a test by its FILENAME, so an `e2eTest` living in `page.test.ts` was classified as a UNIT
+ * test and could never reach the `e2e` step no matter what drove it. `page.e2e.test.ts` is the
+ * name the `e2e` step selects on.
+ */
+const routeE2eTest = (
+  path: string,
+): string => `// /${path} on a train: the offline fallback, asserted against the BUILT output. Its own file
+// because the gate types a test by its FILENAME — an e2eTest in page.test.ts is a unit test.
+import { e2eTest, expect } from '@ultimat3/testing';
+
+// Runs under the \`e2e\` step, against the BUILT output. Without a registered browser driver
+// \`e2eTest\` reports itself skipped, naming the command that builds what it would drive.
+e2eTest('/${path} renders offline', async ({ page, offline }) => {
+  await page.goto('/${sampleUrl(path)}');
   await offline();
   await page.reload();
   expect(await page.title()).not.toBe('');
@@ -129,6 +203,7 @@ export function routeFiles(rawPath: string, options: RouteOptions): readonly Gen
     { path: `${dir}/page.tsx`, contents: pageSource(options.surface, path) },
     { path: `${dir}/page.module.scss`, contents: styleSource() },
     { path: `${dir}/page.test.ts`, contents: routeTest(options.surface, path) },
+    { path: `${dir}/page.e2e.test.ts`, contents: routeE2eTest(path) },
     ...locales.map((locale) => ({
       path: catalogPath(locale),
       contents: catalogSource(path),