@ultimat3/cli 1.0.0

package/src/templates/query.ts

@@ -0,0 +1,116 @@
+// `x g query <name> [--live]` — a read. Live queries must be deterministic and bounded, so the
+// generated declaration always carries `orderBy` + `limit` and the generated test pins them:
+// an unbounded live query is a memory leak that only shows up under load.
+
+import type { FeatureTarget } from './entity';
+import type { GeneratedFile, NameSet } from './naming';
+import { names } from './naming';
+
+/** 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 =>
+  live ? '' : `\n  cache: { tags: [${feature.camel}Tag], ttlMs: 30_000 },`;
+
+const querySource = (
+  name: NameSet,
+  feature: NameSet,
+  live: boolean,
+): string => `// ${name.camel}: a ${live ? 'live (subscribable)' : 'one-shot'} read over ${feature.pluralKebab}.
+// Bounded and ordered — required for${live ? ' live queries' : ' predictable pagination'}.
+// \`t\` comes from @ultimat3/query, not @ultimat3/schema: a query file imports one package.
+
+import { from, query, t } from '@ultimat3/query';
+import type { ${feature.pascal} } from '../entity';
+import { can${feature.pascal}Read${live ? '' : `, ${feature.camel}Tag`} } from '../policy';
+import * as repo from '../repo';
+
+export const ${name.camel} = query({
+  input: t.object({ orgId: t.uuid, limit: t.number.default(50) }),
+  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' },
+  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.
+    from<${feature.pascal}>('${feature.table}', () => repo.listByOrg(orgId, limit))
+      .where({ orgId })
+      .orderBy('createdAt')
+      // The primary key last is what makes the order TOTAL: \`createdAt\` alone ties, and two
+      // rows that tie can swap between evaluations — a bounded read then drops one and repeats
+      // the other, and a live subscription patches a row it never sent.
+      .orderBy('id')
+      .limit(limit),
+});
+`;
+
+const queryTest = (name: NameSet, feature: NameSet, live: boolean): string => {
+  const wrapper = live ? 'liveTest' : 'unitTest';
+  return `import { testActor } from '@ultimat3/policy';
+import { sourceFor } from '@ultimat3/query';
+import { expect, ${wrapper} } from '@ultimat3/testing';
+import { ${name.camel} } from './${name.kebab}';
+
+// A real v4 uuid: the read parses its input the way a request does, so a placeholder that only
+// looks like a uuid would fail before it ever built any SQL.
+const orgId = '00000000-0000-4000-8000-000000000002';
+
+// Named here because every projection needs a stable name and this file does not boot the app.
+// At boot \`registerQueries(await import('./${live ? 'live' : 'queries'}'))\` stamps the same name
+// onto the same object.
+const target = ${name.camel}.named('${name.camel}');
+
+// Holds the grant, wrong org — so a denial here is the predicate deciding, not the grant.
+const outsider = testActor('outsider', {
+  orgId: '00000000-0000-4000-8000-000000000009',
+  permissions: ['${feature.kebab}:read'],
+}).actor;
+
+${wrapper}('${name.camel} is a declared ${live ? 'live ' : ''}query', () => {
+  expect(target.kind).toBe('query');
+  expect(target.isLive).toBe(${String(live)});
+});
+
+${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 });
+  const { sql } = source.toSQL();
+  const text = sql.toLowerCase();
+  expect(text).toContain('order by');
+  expect(text).toContain('limit');
+  // "ordered" is not enough. Dropping the id tiebreak still leaves an ORDER BY, so asserting on
+  // its presence alone would keep passing while the read went non-deterministic under ties.
+  expect(text.slice(text.lastIndexOf('order by'))).toContain('id');
+});
+
+${wrapper}('${name.camel} denies a foreign org before it reads a row', async () => {
+  // \`.as()\` is the one read path with the actor swapped: validate, authorize, then read. The
+  // denial lands before any SQL executes, which is why this needs no database.
+  const denied = await target.as(outsider, { orgId, limit: 50 }).catch((error: unknown) => error);
+  expect(denied).toBeUltimateError('X_FORBIDDEN');
+});
+
+${wrapper}('${name.camel} exposes one MCP tool that reads, and never writes', () => {
+  // Same policy object on both surfaces — an agent cannot reach a different authz path.
+  expect(target.tool().policy).toBe(target.policy);
+  expect(target.tool().mutates).toBe(false);
+});
+`;
+};
+
+export interface QueryOptions extends FeatureTarget {
+  readonly live?: boolean;
+}
+
+export function queryFiles(rawName: string, target: QueryOptions): readonly GeneratedFile[] {
+  const name = names(rawName);
+  const feature = names(target.feature);
+  const live = target.live === true;
+  const dir = `${target.surfaceDir}/${target.feature}/${live ? 'live' : 'queries'}`;
+  return [
+    { 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

@@ -0,0 +1,199 @@
+// `x g resource <name>` — the whole feature slice in one command: entity, repo, service, policy,
+// two actions, a live list query, a UI component and a route, each with a passing test. This is
+// the blessed path; the individual generators exist for adding to a slice that already exists.
+
+import { actionFiles } from './action';
+import { adminFiles } from './admin';
+import { catalogJson } from './catalog-json';
+import type { FeatureTarget } from './entity';
+import { entityFiles } from './entity';
+import { jobFiles } from './job';
+import { catalogPath, resolveLocales } from './locales';
+import type { GeneratedFile, NameSet } from './naming';
+import { names, pascal } from './naming';
+import { policyFiles } from './policy';
+import { queryFiles } from './query';
+import { 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'>;
+
+export async function create(input: Create${feature.pascal}Input): Promise<${feature.pascal}> {
+  return repo.insert(input);
+}
+
+export async function require${feature.pascal}(id: string): Promise<${feature.pascal}> {
+  const row = await repo.byId(id);
+  if (row === undefined) throw new ${feature.pascal}NotFoundError({ id });
+  return row;
+}
+`;
+
+const serviceTest = (
+  feature: NameSet,
+): string => `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);
+});
+`;
+
+const uiSource = (
+  feature: NameSet,
+): string => `// Presentation only. No fetching, no business logic: the list arrives as a prop from the route,
+// which got it from the live query.
+
+import { t } from '@ultimat3/i18n';
+import { For } from 'solid-js';
+import type { ${feature.pascal} } from './entity';
+import styles from './ui.module.scss';
+
+export interface ${feature.pascal}ListProps {
+  readonly rows: readonly ${feature.pascal}[];
+}
+
+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>
+    </ul>
+  );
+}
+`;
+
+const uiStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
+
+.list {
+  display: grid;
+  gap: tokens.$space-2;
+}
+
+.item {
+  padding: tokens.$space-2;
+  border-radius: tokens.$radius-sm;
+  background: tokens.$surface-raised;
+  color: tokens.$text-primary;
+}
+`;
+
+const cardSource = (
+  feature: NameSet,
+): string => `// One ${feature.camel} rendered on its own — the list's \`item\` shown outside a list, so a
+// detail route and a search result render the identical markup.
+
+import { t } from '@ultimat3/i18n';
+import type { ${feature.pascal} } from '../entity';
+import styles from '../ui.module.scss';
+
+export interface ${feature.pascal}CardProps {
+  readonly row: ${feature.pascal};
+}
+
+export function ${feature.pascal}Card(props: ${feature.pascal}CardProps) {
+  return (
+    <article class={styles.item}>
+      <h3>{props.row.title}</h3>
+      <p>{t('app.${feature.kebab}.updated')}</p>
+    </article>
+  );
+}
+`;
+
+const formSource = (
+  feature: NameSet,
+): string => `// Presentation only: the mutator this submits to owns validation server-side, so this form
+// never re-implements the invariant — a blank title fails at the boundary, not in the DOM.
+
+import { t } from '@ultimat3/i18n';
+import { createSignal } from 'solid-js';
+import styles from '../ui.module.scss';
+
+export interface ${feature.pascal}FormProps {
+  readonly onSubmit: (title: string) => void;
+}
+
+export function ${feature.pascal}Form(props: ${feature.pascal}FormProps) {
+  const [title, setTitle] = createSignal('');
+  return (
+    <form
+      class={styles.item}
+      onSubmit={(event) => {
+        event.preventDefault();
+        props.onSubmit(title());
+      }}
+    >
+      <label>
+        {t('app.${feature.kebab}.titleLabel')}
+        <input value={title()} onInput={(event) => setTitle(event.currentTarget.value)} />
+      </label>
+      <button type="submit">{t('app.${feature.kebab}.submit')}</button>
+    </form>
+  );
+}
+`;
+
+// `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 =>
+  catalogJson({
+    [`app.${feature.kebab}.empty`]: `No ${feature.pluralKebab} yet.`,
+    [`app.${feature.kebab}.updated`]: 'Last updated',
+    [`app.${feature.kebab}.titleLabel`]: 'Title',
+    [`app.${feature.kebab}.submit`]: 'Save',
+    [`admin.${feature.kebab}.title`]: pascal(feature.plural),
+  });
+
+export interface ResourceOptions extends FeatureTarget {
+  /** `x g resource post --admin` — also emits the per-entity admin override. */
+  readonly admin?: boolean;
+  /** Every locale the feature's catalog ships for. Defaults to `['en']`. */
+  readonly locales?: readonly string[];
+}
+
+export function resourceFiles(rawName: string, target: ResourceOptions): readonly GeneratedFile[] {
+  const feature = names(rawName);
+  const slice: FeatureTarget = { surfaceDir: target.surfaceDir, feature: feature.kebab };
+  const dir = `${slice.surfaceDir}/${slice.feature}`;
+  const locales = resolveLocales(target.locales);
+  return [
+    ...entityFiles(rawName, slice),
+    ...policyFiles(rawName, slice),
+    ...actionFiles(`create-${feature.kebab}`, slice),
+    ...actionFiles(`archive-${feature.kebab}`, slice),
+    ...queryFiles(`${feature.camel}List`, { ...slice, live: true }),
+    ...jobFiles(`reindex-${feature.kebab}`, slice),
+    { path: `${dir}/service.ts`, contents: serviceSource(feature) },
+    { path: `${dir}/service.test.ts`, contents: serviceTest(feature) },
+    { path: `${dir}/ui.tsx`, contents: uiSource(feature) },
+    { path: `${dir}/ui.module.scss`, contents: uiStyle() },
+    { path: `${dir}/ui/${feature.kebab}-card.tsx`, contents: cardSource(feature) },
+    { path: `${dir}/ui/${feature.kebab}-form.tsx`, contents: formSource(feature) },
+    ...locales.map((locale) => ({
+      path: catalogPath(locale),
+      contents: catalogSource(feature),
+      merge: 'json' as const,
+    })),
+    // Always an app route: a slice ships a live query, a form and actions, and `generate()`
+    // refuses `--surface site` for a resource rather than emit them behind a 0kb budget.
+    ...routeFiles(feature.pluralKebab, { surface: 'app', locales }),
+    ...(target.admin === true ? adminFiles(rawName, slice) : []),
+  ];
+}

package/src/templates/route.ts

@@ -0,0 +1,138 @@
+// `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.
+
+import { catalogJson } from './catalog-json';
+import { catalogPath, resolveLocales } from './locales';
+import type { GeneratedFile } from './naming';
+import { kebab, pascal, titleKey } from './naming';
+
+export type Surface = 'site' | 'app';
+
+const RENDER: Record<Surface, string> = { site: 'isr', app: 'stream' };
+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. */
+const BUDGET: Record<Surface, { readonly js: string; readonly lcp: number }> = {
+  site: { js: '0kb', lcp: 1800 },
+  app: { js: '60kb', lcp: 2500 },
+};
+const budgetLiteral = (surface: Surface): string =>
+  `{ js: '${BUDGET[surface].js}', lcp: ${BUDGET[surface].lcp} }`;
+/** `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
+    .split('/')
+    .filter((part) => part.length > 0)
+    .map(kebab)
+    .join('/')}`;
+
+const pageSource = (surface: Surface, path: string): 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.
+
+import { t } from '@ultimat3/i18n';
+import { defineRoute } from '@ultimat3/render';
+import styles from './page.module.scss';
+
+export const config = defineRoute({
+  render: '${RENDER[surface]}',${REVALIDATE[surface]}
+  hydrate: '${HYDRATE[surface]}',
+  offline: '${OFFLINE[surface]}',
+  budget: ${budgetLiteral(surface)},
+  meta: () => ({
+    title: t('${titleKey(path)}'),
+    description: t('${titleKey(path).replace('.title', '.description')}'),
+  }),
+});
+
+export function ${name}Page() {
+  return (
+    <main class={styles.page}>
+      <h1>{t('${titleKey(path)}')}</h1>
+    </main>
+  );
+}
+`;
+};
+
+const styleSource =
+  (): string => `// Semantic tokens only — a raw hex here is a dark-theme bug and a lint failure.
+@use '@ultimat3/ui/tokens' as tokens;
+
+.page {
+  padding: tokens.$space-6;
+  background: tokens.$surface-base;
+  color: tokens.$text-primary;
+}
+`;
+
+const routeTest = (
+  surface: Surface,
+  path: string,
+): string => `import { e2eTest, expect, unitTest } from '@ultimat3/testing';
+import { config } from './page';
+
+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({});
+  expect(meta.title ?? '').not.toBe('');
+  expect(meta.description ?? '').not.toBe('');
+});
+
+unitTest('/${path} declares a render mode, an offline strategy and a 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.
+  expect(config.budget.lcp).toBe(${BUDGET[surface].lcp});
+});
+
+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}');
+  await offline();
+  await page.reload();
+  expect(await page.title()).not.toBe('');
+});
+`;
+
+const catalogSource = (path: string): string =>
+  catalogJson({
+    [titleKey(path)]: pascal(path.split('/').at(-1) ?? 'Page'),
+    [titleKey(path).replace('.title', '.description')]: 'Describe this page for search results.',
+  });
+
+export interface RouteOptions {
+  readonly surface: Surface;
+  /** Every locale the catalog entry ships for. Defaults to `['en']` — an app narrows or grows it. */
+  readonly locales?: readonly string[];
+}
+
+export function routeFiles(rawPath: string, options: RouteOptions): readonly GeneratedFile[] {
+  const path = rawPath.replace(/^\/+/, '');
+  const dir = routeDir(options.surface, path);
+  const locales = resolveLocales(options.locales);
+  return [
+    { 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) },
+    ...locales.map((locale) => ({
+      path: catalogPath(locale),
+      contents: catalogSource(path),
+      merge: 'json' as const,
+    })),
+  ];
+}