@ultimat3/cli 22.14.0 → 23.0.0

package/src/templates/resource.ts

@@ -4,61 +4,23 @@
 
 import { actionFiles } from './action';
 import { adminFiles } from './admin';
+import { adminCatalogEntries } from './admin-catalog';
 import { catalogJson } from './catalog-json';
 import type { FeatureTarget } from './entity';
 import { entityFiles } from './entity';
+import { sortedImports } from './imports';
 import { jobFiles } from './job';
 import { catalogPath, resolveLocales } from './locales';
 import type { GeneratedFile, NameSet } from './naming';
-import { names, pascal } from './naming';
+import { names } from './naming';
 import { policyFiles } from './policy';
 import { queryFiles } from './query';
 import { resourceCreateFiles } from './resource-create';
 import { formIslandFiles } from './resource-form-island';
+import { resourcePageFiles } from './resource-page';
+import { serviceFiles } from './resource-service';
 import { routeDir, routeFiles } from './route';
-
-const serviceSource = (
-  feature: NameSet,
-): string => `// Business logic for ${feature.pluralKebab}. Knows nothing about HTTP or requests, so a job and an
-// action can both call it. Takes values, not a request.
-
-import type { ${feature.pascal} } from './entity';
-import { ${feature.pascal}NotFoundError } from './errors';
-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'>;
-
-/** 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<Row> {
-  const row = await repo.byId(id);
-  if (row === undefined) throw new ${feature.pascal}NotFoundError({ id });
-  return row;
-}
-`;
-
-const serviceTest = (
-  feature: NameSet,
-): 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', () => {
-  const error = new ${feature.pascal}NotFoundError({ id: 'missing' });
-  expect(error).toBeUltimateError('X_${feature.kebab.toUpperCase().split('-').join('_')}_NOT_FOUND');
-  expect(error.cause).toContain('missing');
-  expect(error.fix.length).toBeGreaterThan(0);
-});
-`;
+import { PLACEHOLDER_DB_MODULE } from './scaffold-db-client';
 
 /**
  * The generated component reaches strings through the APP's catalog module — the one that calls
@@ -144,18 +106,58 @@ export function ${feature.pascal}Card(props: ${feature.pascal}CardProps) {${tran
 }
 `;
 
-// `admin.<feature>.title` is always here, `--admin` or not: `defineAdmin()` resolves that key the
-// moment anyone writes the override, and a missing key renders ⟦key⟧ and fails the i18n gate,
-// while an unused key is only ever reported (`auditCatalogs` fails on `missing`, never `unused`).
-const catalogSource = (feature: NameSet): string =>
+const uiTest = (
+  feature: NameSet,
+  module: string | undefined,
+): string => `// The ${feature.kebab} list and card, rendered the way a page renders them. What a typecheck
+// cannot see is which branch a prop picks, and whether the words on screen are the catalog's.
+${sortedImports([catalogImport(module), "import { expect, renderView, unitTest } from '@ultimat3/testing';"])}
+import type { ${feature.pascal} } from './entity';
+import { ${feature.pascal}List } from './ui';
+import { ${feature.pascal}Card } from './ui/${feature.kebab}-card';
+
+const titled = (title: string): ${feature.pascal} => ({
+  id: '00000000-0000-4000-8000-000000000001',
+  orgId: '00000000-0000-4000-8000-000000000002',
+  title,
+  price: { minor: 1200, currency: 'USD' },
+  createdAt: new Date(0),
+});
+
+unitTest('the list renders one item per row, in the order it was given', async () => {
+  const rows = [titled('first'), titled('second')];
+  const view = await renderView(${feature.pascal}List, { rows });
+  expect(view.html.match(/<li\\b/g)).toHaveLength(2);
+  expect(view.text).toBe('first second');
+});
+
+unitTest('with no rows the list says so, in one item', async () => {${module === undefined ? '' : '\n  const t = useT();'}
+  const view = await renderView(${feature.pascal}List, { rows: [] });
+  expect(view.html.match(/<li\\b/g)).toHaveLength(1);
+  expect(view.text).toBe(t('app.${feature.kebab}.empty'));
+});
+
+unitTest('the card renders the row it is given, under its own heading', async () => {${module === undefined ? '' : '\n  const t = useT();'}
+  const view = await renderView(${feature.pascal}Card, { row: titled('on a card') });
+  expect(view.html).toContain('<h3>on a card</h3>');
+  expect(view.text).toContain(t('app.${feature.kebab}.updated'));
+});
+`;
+
+// The admin's keys are always here, `--admin` or not: the entity is an admin screen the moment it
+// joins the handle, and that screen reads `admin.<table>.title` and a label per column
+// (`admin-catalog.ts`). A missing key renders ⟦key⟧ in the list's own header.
+const catalogSource = (feature: NameSet, admin: Readonly<Record<string, string>>): string =>
   catalogJson({
     [`app.${feature.kebab}.empty`]: `No ${feature.pluralKebab} yet.`,
     [`app.${feature.kebab}.updated`]: 'Last updated',
     [`app.${feature.kebab}.titleLabel`]: 'Title',
+    [`app.${feature.kebab}.priceLabel`]: 'Price',
+    [`app.${feature.kebab}.new`]: `New ${feature.kebab.replaceAll('-', ' ')}`,
     [`app.${feature.kebab}.submit`]: 'Save',
     [`app.${feature.kebab}.saved`]: 'Saved',
     [`app.${feature.kebab}.retry`]: 'Try again',
-    [`admin.${feature.kebab}.title`]: pascal(feature.plural),
+    ...admin,
   });
 
 export interface ResourceOptions extends FeatureTarget {
@@ -168,15 +170,28 @@ export interface ResourceOptions extends FeatureTarget {
    * `resolveCatalogModule`. Absent only for an app that ships no such package.
    */
   readonly catalogModule?: string;
+  /**
+   * The app has `apps/web/shared/shell.tsx`, the frame `x new` writes, for the page to sit in —
+   * read off the disk by `x g`. Absent is no: a generation imports only what it writes or what the
+   * caller said is there (`slice-foundation.test.ts`), and the page is then its own `<main>`.
+   */
+  readonly shell?: boolean;
 }
 
 export function resourceFiles(rawName: string, target: ResourceOptions): readonly GeneratedFile[] {
   const feature = names(rawName);
-  const slice: FeatureTarget = { surfaceDir: target.surfaceDir, feature: feature.kebab };
+  // `dbModule` travels with the slice: every generator composed below may write the slice's
+  // `repo.ts`, and one that lost the app's name would import the handle from a placeholder.
+  const slice: FeatureTarget = {
+    surfaceDir: target.surfaceDir,
+    feature: feature.kebab,
+    ...(target.dbModule === undefined ? {} : { dbModule: target.dbModule }),
+  };
   const dir = `${slice.surfaceDir}/${slice.feature}`;
   // The page this same call writes, from the function that decides where a route goes — the island
   // specifier is resolved against it, so re-deriving the path here would be two answers to one
   // question and only one of them reaches `routeFiles`.
+  const dbModule = target.dbModule ?? PLACEHOLDER_DB_MODULE;
   const pageDir = routeDir('app', feature.pluralKebab);
   const locales = resolveLocales(target.locales);
   const entity = entityFiles(rawName, slice);
@@ -187,13 +202,18 @@ export function resourceFiles(rawName: string, target: ResourceOptions): readonl
     ...entity,
     ...policyFiles(rawName, slice),
     // Not `x g action`'s body: a resource's create INSERTS (`resource-create.ts`).
-    ...resourceCreateFiles(rawName, dir),
+    ...resourceCreateFiles(rawName, dir, dbModule),
+    // `sliceEntity` is this run's own, so the action's test stores a row and runs its handler
+    // against the repo beside it.
     ...actionFiles(`archive-${feature.kebab}`, { ...slice, sliceEntity }),
-    ...queryFiles(`${feature.camel}List`, { ...slice, live: true }),
+    // And the read's test stores rows through that same repo, then reads them back in order.
+    ...queryFiles(`${feature.camel}List`, { ...slice, live: true, sliceEntity }),
     ...jobFiles(`reindex-${feature.kebab}`, { ...slice, sliceEntity }),
-    { path: `${dir}/service.ts`, contents: serviceSource(feature) },
-    { path: `${dir}/service.test.ts`, contents: serviceTest(feature) },
+    ...serviceFiles(feature, dir, dbModule),
     { path: `${dir}/ui.tsx`, contents: uiSource(feature, target.catalogModule) },
+    // Beside the two components it renders: a generated module with no test is uncovered source
+    // in an app whose gate holds a coverage floor.
+    { path: `${dir}/ui.test.ts`, contents: uiTest(feature, target.catalogModule) },
     { path: `${dir}/ui.module.scss`, contents: uiStyle() },
     {
       path: `${dir}/ui/${feature.kebab}-card.tsx`,
@@ -202,20 +222,25 @@ export function resourceFiles(rawName: string, target: ResourceOptions): readonl
     ...formIslandFiles(feature, dir, pageDir),
     ...locales.map((locale) => ({
       path: catalogPath(locale),
-      contents: catalogSource(feature),
+      contents: catalogSource(feature, adminCatalogEntries(rawName, slice)),
       merge: 'json' as const,
     })),
     // Always an app route: a slice ships a live query, a form island and actions, and `generate()`
-    // refuses `--surface site` for a resource rather than emit them behind a 0kb budget.
-    //
-    // `catalogModule` travels with it. It did not, so the page a RESOURCE writes imported `t` from
-    // `@ultimat3/i18n` while the components beside it imported `useT` from the app's own catalog
-    // module — one command, two idioms, and the framework-import one is issue #249's: it renders
-    // strings while depending on nothing that registers them.
+    // refuses `--surface site` for a resource. The stylesheet, the offline e2e test and the
+    // title/description keys are `x g route`'s; the page and its unit test are the resource's
+    // own (`resource-page.ts`) — they read the rows and mount the form, which a route cannot.
     ...routeFiles(feature.pluralKebab, {
       surface: 'app',
       locales,
       ...(target.catalogModule === undefined ? {} : { catalogModule: target.catalogModule }),
+    }).filter((file) => !/\/page\.(tsx|test\.ts)$/.test(file.path)),
+    ...resourcePageFiles({
+      feature,
+      dir,
+      pageDir,
+      shell: target.shell === true,
+      dbModule,
+      ...(target.catalogModule === undefined ? {} : { catalogModule: target.catalogModule }),
     }),
     ...(target.admin === true ? adminFiles(rawName, slice) : []),
   ];

package/src/templates/route.ts

@@ -103,13 +103,10 @@ const catalogImport = (module: string | undefined): string =>
 const translatorBinding = (module: string | undefined): string =>
   module === undefined ? '' : '\n  const t = useT();\n';
 
+// The component is `Page` in every route file: the name the router looks for first
+// (`pageComponentOf`) and the one both tracked apps use. It was `<Name>Page` — `PostsPage`,
+// `PricingPage` — found only by the router's fallback, and a second spelling of one thing.
 const pageSource = (surface: Surface, path: string, module: string | undefined): string => {
-  const name = pascal(
-    path
-      .split('/')
-      .filter((part) => part.length > 0)
-      .at(-1) ?? 'page',
-  );
   return `// Route: /${path} on the ${surface} surface. Config first: render mode, offline
 // strategy and budget are declarations, not runtime choices.
 
@@ -127,7 +124,7 @@ export const config = defineRoute({
   }),
 });
 
-export function ${name}Page() {${translatorBinding(module)}
+export function Page() {${translatorBinding(module)}
   return (
     <main class={styles.page}>
       <h1>{t('${titleKey(path)}')}</h1>
@@ -170,36 +167,45 @@ const paramsLiteral = (path: string): string => {
 const routeTest = (
   surface: Surface,
   path: string,
-): 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';
+  module: string | undefined,
+): string => `// /${path}, rendered: the heading a visitor reads, the metadata a search result renders, and the
+// render mode, offline strategy and budget the route promises. A route with no title is an SEO
+// regression; one whose page throws is a 500 the config alone never shows.
+${sortedImports([
+  catalogImport(module),
+  "import { expect, renderRoute, unitTest } from '@ultimat3/testing';",
+])}
+import * as page 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)}' };
+// What a request gives this route: the URL it matched and the params in it. \`renderRoute\` resolves
+// the route's data once and hands \`meta\` and the page that one object, as every render mode does.
+const request = {
+  url: 'https://example.test/${sampleUrl(path)}',
+  params: ${paramsLiteral(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(metaContextFor(ctx, await routeDataFor(config, ctx)));
-  expect(meta.title ?? '').not.toBe('');
-  expect(meta.description ?? '').not.toBe('');
+unitTest('the page renders its title as its one heading', async () => {${module === undefined ? '' : '\n  const t = useT();'}
+  const view = await renderRoute(page, request);
+  expect(view.html.match(/<h1\\b/g)).toHaveLength(1);
+  expect(view.text).toBe(t('${titleKey(path)}'));
 });
 
-unitTest('/${path} declares its render and offline strategy', () => {
-  expect(config.render).toBe('${RENDER[surface]}');
-  expect(config.offline).toBe('${OFFLINE[surface]}');
+unitTest('it declares the metadata a search result renders', async () => {${module === undefined ? '' : '\n  const t = useT();'}
+  const view = await renderRoute(page, request);
+  expect(view.meta.title).toBe(t('${titleKey(path)}'));
+  expect(view.meta.description).toBe(t('${titleKey(path).replace('.title', '.description')}'));
 });
 
 // The only budget this route declares, because it is the only one the build can weigh: nothing
 // in the framework observes a paint, so an lcp budget would be a number pinned here and never
 // compared against anything.
-unitTest('/${path} stays inside its byte budget declaration', () => {
-  expect(config.budget.js).toBe('${BUDGET[surface].js}');
+unitTest('it declares its render mode, offline strategy and byte budget', async () => {
+  const view = await renderRoute(page, request);
+  expect(page.config.render).toBe('${RENDER[surface]}');
+  expect(page.config.offline).toBe('${OFFLINE[surface]}');
+  expect(page.config.budget.js).toBe('${BUDGET[surface].js}');
+  // No island yet: what the page ships is what the config says, until the first \`island()\`.
+  expect(view.islands).toEqual([]);
 });
 `;
 
@@ -253,7 +259,10 @@ export function routeFiles(rawPath: string, options: RouteOptions): readonly Gen
   return [
     { path: `${dir}/page.tsx`, contents: pageSource(options.surface, path, options.catalogModule) },
     { path: `${dir}/page.module.scss`, contents: styleSource() },
-    { path: `${dir}/page.test.ts`, contents: routeTest(options.surface, path) },
+    {
+      path: `${dir}/page.test.ts`,
+      contents: routeTest(options.surface, path, options.catalogModule),
+    },
     { path: `${dir}/page.e2e.test.ts`, contents: routeE2eTest(path) },
     ...locales.map((locale) => ({
       path: catalogPath(locale),

package/src/templates/scaffold-api.ts

@@ -4,6 +4,7 @@
 // because `index.ts` has to know the example slice's own file layout.
 
 import type { GeneratedFile } from './naming';
+import { browserClientFiles } from './scaffold-browser-client';
 
 const healthAction =
   (): string => `// api/ holds actions only: no rendering, no components. This one is the readiness probe every
@@ -47,6 +48,50 @@ contractTest('health projects one MCP tool and one OpenAPI operation', () => {
 });
 `;
 
+const healthUnitTest =
+  (): string => `// health, called: what a probe gets back. Its projections — the OpenAPI operation and the MCP
+// tool — are the contract suite's, next door.
+import { anonymousActor, resolveRole } from '@ultimat3/core';
+import { expect, unitTest } from '@ultimat3/testing';
+import { health } from './health';
+
+const target = health.named('health');
+
+unitTest('health answers ok and the role of this process, with no session', async () => {
+  // Anonymous on purpose: a load balancer has no session, and \`allow('public')\` is what lets it
+  // in. The role is the process's own (\`ROLE\`), which is what tells a web probe from a worker's.
+  expect(await target.as(anonymousActor(), {})).toEqual({ ok: true, role: resolveRole() });
+});
+`;
+
+const apiIndexTest = (
+  example: boolean,
+): string => `// The registration, read back. \`defineApi\` names every primitive by its EXPORT, so what this
+// pins is that a declaration reached the call at all — an action left out of the list is a route
+// that answers 404 with every test of the action itself still green.
+import { expect, unitTest } from '@ultimat3/testing';
+import { health } from './health';
+import { api } from './index';
+
+unitTest('health is registered, as the object its module exports', () => {
+  expect(api.actions.health).toBe(health);
+  expect(api.actions.health.describe().name).toBe('health');
+});
+${
+  example
+    ? `
+unitTest('the post slice is registered: two actions, a live query and a job', () => {
+  expect(api.actions.createPost.describe().name).toBe('createPost');
+  expect(api.actions.archivePost.describe().name).toBe('archivePost');
+  expect(api.queries.postList.isLive).toBe(true);
+  // The half an app cannot skip: a job nothing lists keeps \`anonymous-job-<n>\` on the queue row
+  // and in every dead-letter trace.
+  expect(api.jobs.reindexPost.name).toBe('reindexPost');
+});
+`
+    : ''
+}`;
+
 /** The imports and the lists that differ between `x new` and `x new --no-example`. */
 const exampleSlice = {
   imports: `import * as archivePost from '../app/post/actions/archive-post';
@@ -87,14 +132,23 @@ ${slice.imports}import * as health from './health';
 export const api = defineApi({
   actions: [health${slice.actions}],${slice.extra}
 });
+
+/** What the typed client is shaped from — imported as a TYPE only by \`shared/browser-client.ts\`. */
+export type Api = typeof api;
 `;
 };
 
-/** `apps/web/api` for a new app: the readiness action, its contract test, and the registration. */
+/**
+ * `apps/web/api` for a new app: the readiness action, its contract test, and the registration —
+ * plus the browser's typed clients over it (`scaffold-browser-client.ts`), which read its `Api` type.
+ */
 export function apiFiles(example: boolean): readonly GeneratedFile[] {
   return [
     { path: 'apps/web/api/health.ts', contents: healthAction() },
+    { path: 'apps/web/api/health.test.ts', contents: healthUnitTest() },
     { path: 'apps/web/api/health.contract.test.ts', contents: healthTest() },
     { path: 'apps/web/api/index.ts', contents: apiIndex(example) },
+    { path: 'apps/web/api/index.test.ts', contents: apiIndexTest(example) },
+    ...browserClientFiles(example),
   ];
 }