@ultimat3/cli 20.2.1 → 22.0.0

package/src/sw-artifacts.ts

@@ -57,6 +57,12 @@ export interface ServiceWorkerInput {
    * this map does not name.
    */
   readonly documents?: ReadonlyMap<string, RenderedDocument>;
+  /**
+   * The page's framework scripts — realtime's page boot and sync worker (`pageSync(…).scripts`).
+   * Precached beside the island chunks for their reason: source-addressed and `immutable`, and an
+   * offline reload that cannot load the boot restores no record and shows the old count.
+   */
+  readonly scripts?: readonly { readonly url: string; readonly bytes: number }[];
 }
 
 /**
@@ -117,8 +123,12 @@ const pwaRoutes = (
  * Sorted by url, because `buildPrecacheManifest` sorts its own entries but the ASSET list is what
  * decides which of two equal urls wins, and `sw.js` must be byte-identical for identical input.
  */
-const staticAssets = (islands: IslandBundle, styles: StyleBundle): readonly PrecacheAsset[] =>
-  [...islands.chunks, ...styles.chunks]
+const staticAssets = (
+  islands: IslandBundle,
+  styles: StyleBundle,
+  scripts: readonly { readonly url: string; readonly bytes: number }[],
+): readonly PrecacheAsset[] =>
+  [...islands.chunks, ...styles.chunks, ...scripts]
     .map((chunk) => ({ url: chunk.url, revision: chunk.url, bytes: chunk.bytes }))
     .sort((a, b) => (a.url < b.url ? -1 : a.url > b.url ? 1 : 0));
 
@@ -200,7 +210,7 @@ export function serviceWorkerArtifacts(
         neverCache: pwa.offline.neverCache,
       },
       capabilities: { backgroundSync: pwa.backgroundSync, push: pwa.push },
-      assets: staticAssets(input.islands, input.styles),
+      assets: staticAssets(input.islands, input.styles, input.scripts ?? []),
     },
     input.buildId,
   );

package/src/sync-url.ts

@@ -0,0 +1,31 @@
+// Where a page's one socket dials — the framework's answer, so no app owns a `sync-url.ts`. Read
+// once at boot from the deployment's env and handed to every document as `ultimate-sync`.
+
+import { ConfigInvalidError } from '@ultimat3/core';
+
+/**
+ * The sync node's own path (`createSyncNode`'s default in `@ultimat3/realtime`). Same origin by
+ * default because every rung already serves it there: `x dev` and a combined-role container mount
+ * the node on the web port, and `docker/helm`'s ingress routes `/_x/sync` to the `sync` service.
+ */
+export const SYNC_PATH = '/_x/sync';
+
+/**
+ * `SYNC_URL` verbatim when the deployment states one — the Compose rung publishes `sync` on its
+ * own port with no proxy in front, so only the deployment knows that URL — else `SYNC_PATH`,
+ * resolved by the browser against its own origin. Never derived from a port: behind any ingress a
+ * neighbouring port is a URL nothing publishes.
+ */
+export function syncUrlFrom(env: Readonly<Record<string, string | undefined>>): string {
+  const declared = env['SYNC_URL']?.trim() ?? '';
+  if (declared === '') return SYNC_PATH;
+  const parsed = URL.parse(declared);
+  if (parsed === null || (parsed.protocol !== 'ws:' && parsed.protocol !== 'wss:')) {
+    throw new ConfigInvalidError({
+      cause: 'SYNC_URL is set but is not a ws:// or wss:// URL, so no browser could dial it',
+      fix: 'export SYNC_URL="wss://sync.example.com/_x/sync"   # or unset it to dial /_x/sync on the page origin',
+      meta: { key: 'SYNC_URL' },
+    });
+  }
+  return declared;
+}

package/src/templates/action.ts

@@ -15,15 +15,19 @@ import { wrapImport } from './wrap';
  * (ai-maxxing's `fleet`, with `HostNotFoundError` and `SessionNotFoundError`) declares the errors
  * it has and not this one. Importing it anyway is a file that fails at import.
  */
-const missingLookup = (feature: NameSet): string =>
-  `    // No lookup by id: ../errors declares no ${feature.pascal}NotFoundError, and a row that is not
+const missingLookup = (feature: NameSet, entity: boolean): string =>
+  entity
+    ? `    // No lookup by id: ../errors declares no ${feature.pascal}NotFoundError, and a row that is not
     // there needs one to be thrown for it. Declare it there — the shape \`x g resource\` writes —
-    // then read the row through ../repo and throw it when the read answers nothing.`;
+    // then read the row through ../repo and throw it when the read answers nothing.`
+    : `    // No lookup by id: this feature has no entity, and a generator writing into a slice never
+    // invents one. \`x g entity ${feature.kebab}\` declares the table; this body is yours until then.`;
 
 const actionSource = (
   name: NameSet,
   feature: NameSet,
   lookup: boolean,
+  entity: boolean,
 ): string => `// ${name.camel}: one mutation, server-authoritative. Input is validated before the handler runs
 // and the policy is the same object the MCP tool and the HTTP route evaluate.
 // \`t\` comes from @ultimat3/action, not @ultimat3/schema: an action file imports one package.
@@ -40,14 +44,15 @@ export const ${name.camel} = action({
   output: t.object({ id: t.uuid${lookup ? ', title: t.string' : ''} }),
   policy: can${feature.pascal}Write,
   cache: { invalidates: [${feature.camel}Tag] },
-  mcp: { expose: true, description: '${name.raw} — edit this description' },
+  // No \`mcp\`: a tool's description is what an agent reads to decide to call it, and a placeholder
+  // there is worse than no tool. Write one, then \`mcp: { expose: true, description: '…' }\`.
   async handle({ input }) {
 ${
   lookup
     ? `    const row = await repo.byId(input.id);
     if (row === undefined) throw new ${feature.pascal}NotFoundError({ id: input.id });
     return { id: row.id, title: row.title };`
-    : `${missingLookup(feature)}
+    : `${missingLookup(feature, entity)}
     return { id: input.id };`
 }
   },
@@ -58,6 +63,7 @@ const mutatorSource = (
   name: NameSet,
   feature: NameSet,
   lookup: boolean,
+  entity: boolean,
 ): string => `// ${name.camel}: an action with an optimistic local twin. The local half runs against the client
 // store immediately; the server half is authoritative and reconciles on conflict.
 
@@ -74,7 +80,7 @@ export const ${name.camel} = mutator({
   input: t.object({ id: t.uuid, orgId: t.uuid, title: t.string }),
   output: t.object({ id: t.uuid, title: t.string }),
   policy: can${feature.pascal}Write,
-  mcp: { expose: true, description: '${name.raw} — edit this description' },
+  // No \`mcp\` until a real description is written: see \`x g action\`.
   // tx.table(name) rather than tx.${feature.plural}: the typed accessor exists only once the app
   // augments LocalTables, and generated code cannot assume that has happened yet. The name is the
   // entity's snake_case table, so the local twin and the server row live under one key.
@@ -90,7 +96,7 @@ ${
     ? `    const row = await repo.byId(input.id);
     if (row === undefined) throw new ${feature.pascal}NotFoundError({ id: input.id });
     return { id: row.id, title: input.title };`
-    : `${missingLookup(feature)}
+    : `${missingLookup(feature, entity)}
     return { id: input.id, title: input.title };`
 }
   },
@@ -190,11 +196,10 @@ contractTest('${name.camel} denies a foreign org', async () => {
   expect(denied).toBeUltimateError('X_FORBIDDEN');
 });
 
-contractTest('${name.camel} projects one tool and one operation', () => {
-  // Same policy object on both surfaces — an MCP call cannot reach a different authz path.
-  expect(target.tool().policy).toBe(target.policy);
-  expect(target.tool().description).not.toBe('');
+// No MCP tool until it is described: a placeholder description misleads the agent reading it.
+contractTest('${name.camel} projects one operation and no tool', () => {
   expect(target.openapi().operationId).toBe('${name.camel}');
+  expect(target.mcp?.expose ?? false).toBe(false);
 });
 `;
 
@@ -207,6 +212,12 @@ export interface ActionOptions extends FeatureTarget {
    * `sliceExports` finds it there.
    */
   readonly sliceErrors?: string;
+  /**
+   * The slice's `entity.ts`, or absent when the feature has none. Absent, the action reads no row
+   * and the generator writes no entity — only `x g entity` and `x g resource` create a feature's
+   * data. `x g resource` passes the entity it is writing in the same run.
+   */
+  readonly sliceEntity?: string;
 }
 
 export function actionFiles(rawName: string, target: ActionOptions): readonly GeneratedFile[] {
@@ -214,19 +225,22 @@ export function actionFiles(rawName: string, target: ActionOptions): readonly Ge
   const feature = names(target.feature);
   const dir = `${target.surfaceDir}/${target.feature}/actions`;
   const isMutator = target.mutator === true;
+  const entity = target.sliceEntity !== undefined;
   const lookup =
-    target.sliceErrors === undefined ||
-    sliceExports(target.sliceErrors, `${feature.pascal}NotFoundError`);
+    entity &&
+    (target.sliceErrors === undefined ||
+      sliceExports(target.sliceErrors, `${feature.pascal}NotFoundError`));
   return [
     // The three slice modules this action's source imports — `../errors`, `../policy`, `../repo`
     // (which comes with `../entity`, its row type). Composed rather than assumed: `x g action`
     // into a slice no `x g resource` had created emitted all three imports and wrote none of them.
-    ...sliceFoundation(target, ['entity', 'policy', 'errors']),
+    // With no entity, only the policy: a lookup-free body imports neither ../errors nor ../repo.
+    ...sliceFoundation(target, entity ? ['entity', 'policy', 'errors'] : ['policy']),
     {
       path: `${dir}/${name.kebab}.ts`,
       contents: isMutator
-        ? mutatorSource(name, feature, lookup)
-        : actionSource(name, feature, lookup),
+        ? mutatorSource(name, feature, lookup, entity)
+        : actionSource(name, feature, lookup, entity),
     },
     // TWO test files, because the gate types a test by its FILENAME and this declaration owes two
     // suites: the input parse is a `unit` assertion and the three projections are `contract` ones.

package/src/templates/entity.ts

@@ -68,7 +68,7 @@ const repoSource = (name: NameSet, table: string): string => {
   const row = name.pascal;
   const byIdCall = wrapList(
     '  ',
-    `const row = await db().one<${row}>(`,
+    'const row = await db().one<Physical>(',
     [`sql\`select * from ${table} where id = \${id}\``],
     ');',
   );
@@ -90,32 +90,37 @@ const repoSource = (name: NameSet, table: string): string => {
 // join the caller's transaction without knowing one is open.
 
 import { db, sql } from '@ultimat3/db';
-import { dbDrift, newId } from '@ultimat3/entity';
-import type { ${name.pascal} } from './entity';
+import { dbDrift, decodeRow, newId } from '@ultimat3/entity';
+${wrapImport([`type ${name.pascal}`, name.camel], './entity')}
+
+// What \`select *\` answers: snake_case columns, and money as three of them. Never cast to the row
+// type — \`decodeRow\` is the entity's own reading of it, so \`price\` is a Money again.
+type Physical = Readonly<Record<string, unknown>>;
 
 export async function byId(id: string): Promise<${name.pascal} | undefined> {
 ${byIdCall}
-  return row ?? undefined;
+  return row === null ? undefined : decodeRow(${name.camel}, row);
 }
 
 ${listSignature}
   // Ordered and bounded: an unordered page is a different page on every request.
-  return db().query<${name.pascal}>(
+  const rows = await db().query<Physical>(
     sql\`select * from ${table} where org_id = \${orgId} order by created_at desc limit \${limit}\`,
   );
+  return rows.map((row) => decodeRow(${name.camel}, row));
 }
 
 ${insertSignature}
   // Money is three physical columns — integer minor units, the ISO code, and the scale, never a
   // float. \`scale ?? null\`: an amount at the currency's own minor unit carries no scale at all,
   // and writing \`0\` for it would claim whole units — a 100x reinterpretation of the price.
-  const created = await db().one<${name.pascal}>(sql\`
+  const created = await db().one<Physical>(sql\`
     insert into ${table} (id, org_id, title, price_minor, price_currency, price_scale)
     values (\${newId()}, \${row.orgId}, \${row.title}, \${row.price.minor}, \${row.price.currency},
             \${row.price.scale ?? null})
     returning *\`);
   if (created === null) throw dbDrift('${table}', 'id');
-  return created;
+  return decodeRow(${name.camel}, created);
 }
 `;
 };

package/src/templates/index.ts

@@ -45,7 +45,7 @@ export { entryFiles } from './scaffold-entries';
 export { errorPageFiles, PWA_COLORS } from './scaffold-errors';
 // The nine guards `x new` ships, distinct from `guardFiles` above, which is `x g guard <name>`.
 export { scaffoldGuardFiles } from './scaffold-guards';
-export { i18nIndex } from './scaffold-i18n';
+export { i18nIndex, localeEntry, localeImport } from './scaffold-i18n';
 export { repoFiles } from './scaffold-repo';
 export { shellFiles } from './scaffold-shell';
 export { siteFiles } from './scaffold-site';

package/src/templates/job.ts

@@ -3,11 +3,12 @@
 // both; the generated test pins them through a real driver, because a key that is not stable is a
 // job that runs twice and a tenant that is not declared is a job that reads the wrong org's rows.
 
-import { stripComments } from '../ts-scan';
+import { stripComments } from '@ultimat3/core';
 import type { FeatureTarget } from './entity';
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
 import { sliceExports, sliceFoundation } from './slice-foundation';
+import { wrapList } from './wrap';
 
 const jobSource = (
   name: NameSet,
@@ -69,7 +70,8 @@ export const ${name.camel} = job({
   retry: { attempts: 5, backoff: 'exponential' },
   async run({ step }) {
     await step.run('process', async () => {
-      // TODO: this job's own work.
+      // This job's own work. No table is read here: this feature has no entity, and a generator
+      // writing into a slice never invents one — \`x g entity\` declares it.
     });
     return { processed: true };
   },
@@ -117,7 +119,7 @@ export const ${name.camel} = task({
   tz: 'UTC',
   // No org in the payload: the job this enqueues declares \`tenant: 'none'\`, because this
   // feature's entity names no tenant column (or has none yet).
-  enqueue: () => [[${jobName.camel}, { id: '00000000-0000-4000-8000-000000000001' }]],
+${wrapList('  ', 'enqueue: () => [', [`[${jobName.camel}, { id: '00000000-0000-4000-8000-000000000001' }]`], '],')}
 });
 `;
 
@@ -291,9 +293,10 @@ export interface JobOptions extends FeatureTarget {
 }
 
 /**
- * Whether `x g job`/`x g task` may assume the tenant-scoped shape: an `entity.ts` this feature
- * does not have yet is about to be scaffolded fresh by `sliceFoundation` below, tenant-scoped by
- * default — so absent counts as scoped. One that exists is trusted over that default: it declares
+ * Whether `x g job`/`x g task` may assume the tenant-scoped shape. A feature with no `entity.ts` is
+ * NOT: only `x g entity` and `x g resource` create a feature's data, and counting absent as scoped
+ * made `x g task nightly` lay down an `entity('nightlies', { title, price })` that the `drift` step
+ * then demanded a migration for. One that exists is trusted: it declares
  * a real, non-`'none'` `tenant`, AND its `repo.ts` actually exports the `byId`/`listByOrg` pair the
  * tenant-scoped body calls. Both have to hold — an entity that still names `tenant: 'orgId'` after
  * an author trimmed `listByOrg` out of `repo.ts` (or never generated one) is not a slice this job
@@ -303,7 +306,7 @@ export function isTenantScopedSlice(
   sliceEntity: string | undefined,
   sliceRepo: string | undefined,
 ): boolean {
-  if (sliceEntity === undefined) return true;
+  if (sliceEntity === undefined) return false;
   const declaresTenant = /\btenant\s*:\s*'(?!none')[^']+'/.test(stripComments(sliceEntity));
   if (!declaresTenant) return false;
   if (sliceRepo === undefined) return true;

package/src/templates/policy.ts

@@ -4,7 +4,7 @@
 
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
-import { wrapList } from './wrap';
+import { wrapImport, wrapList } from './wrap';
 
 /** Biome would rewrap this itself, so the generator emits the already-formatted form. */
 const permissionSet = (feature: NameSet): string =>
@@ -65,6 +65,15 @@ export const can${feature.pascal}Write = can<${feature.pascal}Scope>(
   '${feature.kebab}:write',
   ({ actor, input }) => actor !== null && actor.orgId === input.orgId,
 );
+
+/**
+ * Create takes no org from its input — the row is written under the actor's own — so the tenancy
+ * rule is that the actor HAS one. Same grant as write.
+ */
+export const can${feature.pascal}Create = can(
+  '${feature.kebab}:write',
+  ({ actor }) => actor !== null && typeof actor.orgId === 'string' && actor.orgId !== '',
+);
 `;
 
 const policyTest = (
@@ -73,7 +82,7 @@ const policyTest = (
 // 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';
+${wrapImport([`can${feature.pascal}Create`, `can${feature.pascal}Read`, `can${feature.pascal}Write`], './policy')}
 
 const org = '00000000-0000-4000-8000-000000000002';
 const otherOrg = '00000000-0000-4000-8000-000000000009';
@@ -108,9 +117,18 @@ unitTest('${feature.camel} write denies the read-only actor', async () => {
   await expect(can${feature.pascal}Write).not.toDenyPolicy({ actor: writer, input });
 });
 
+unitTest('${feature.camel} create denies the read-only and the orgless actor', async () => {
+  const orgless = testActor('orgless', { permissions: [read, write] }).actor;
+  await expect(can${feature.pascal}Create).toDenyPolicy({ actor: null, input: {} });
+  await expect(can${feature.pascal}Create).toDenyPolicy({ actor: reader, input: {} });
+  await expect(can${feature.pascal}Create).toDenyPolicy({ actor: orgless, input: {} });
+  await expect(can${feature.pascal}Create).not.toDenyPolicy({ actor: writer, input: {} });
+});
+
 unitTest('${feature.camel} rules name the permission they require', () => {
   expect(can${feature.pascal}Read.permissions).toEqual(['${feature.kebab}:read']);
   expect(can${feature.pascal}Write.permissions).toEqual(['${feature.kebab}:write']);
+  expect(can${feature.pascal}Create.permissions).toEqual(['${feature.kebab}:write']);
 });
 `;
 

package/src/templates/resource-create.ts

@@ -0,0 +1,127 @@
+// `x g resource`'s create action: a real insert. It used to be `x g action`'s generic body — read a
+// row by id, throw NotFound — so the route the resource named `create` could never create, and its
+// input was `{ id, orgId }` while the form posted `{ title }`. The input is the entity's own view of
+// the columns a caller supplies; the org comes from the actor, never from the body.
+
+import type { GeneratedFile, NameSet } from './naming';
+import { names } from './naming';
+import { wrapImport, wrapList } from './wrap';
+
+/** The columns a caller supplies: the resource entity's, minus `id`, `orgId` and `createdAt`. */
+export const CREATE_COLUMNS = ['title', 'price'] as const;
+
+const createSource = (
+  feature: NameSet,
+): string => `// create${feature.pascal}: inserts one ${feature.kebab} in the caller's org and returns it.
+// The input is a view of the entity's own columns, so a column added there is one edit here —
+// the list below — and never a second schema to keep in step.
+
+import { action } from '@ultimat3/action';
+import { tenancyActorOrgRequired } from '@ultimat3/entity';
+${wrapImport([`${feature.pascal}View`, feature.camel], '../entity')}
+${wrapImport([`can${feature.pascal}Create`, `${feature.camel}Tag`], '../policy')}
+import * as service from '../service';
+
+/** What a caller supplies. \`id\`, \`orgId\` and \`createdAt\` are the server's to write. */
+${wrapList(
+  '',
+  `export const Create${feature.pascal}Input = ${feature.camel}.$view([`,
+  CREATE_COLUMNS.map((column) => `'${column}'`),
+  ']);',
+)}
+
+export const create${feature.pascal} = action({
+  input: Create${feature.pascal}Input,
+  output: ${feature.pascal}View,
+  policy: can${feature.pascal}Create,
+  cache: { invalidates: [${feature.camel}Tag] },
+  // No \`mcp\`: an MCP tool's description IS what an agent reads to decide to call it, and a
+  // placeholder there is worse than no tool. Write one, then \`mcp: { expose: true, description }\`.
+  async handle({ input, ctx }) {
+    // The tenant is the actor's. The policy already refused an actor with none; this is the same
+    // fact for the type checker, and the framework's own refusal if a caller skips the policy.
+    const orgId = ctx.actor.orgId;
+    if (typeof orgId !== 'string' || orgId === '') {
+      throw tenancyActorOrgRequired({
+        entityName: '${feature.camel}',
+        operation: 'create',
+        actorId: ctx.actor.id,
+        actorKind: ctx.actor.kind,
+      });
+    }
+    return service.create({ ...input, orgId });
+  },
+});
+`;
+
+const ORG = '00000000-0000-4000-8000-000000000002';
+
+const createUnitTest = (
+  feature: NameSet,
+): string => `// create${feature.pascal}: its declared shape and the input it refuses — answered by the
+// declaration alone, so they belong to the \`unit\` step.
+import { expect, unitTest } from '@ultimat3/testing';
+import { create${feature.pascal} } from './create-${feature.kebab}';
+
+const target = create${feature.pascal}.named('create${feature.pascal}');
+const input = { title: 'A ${feature.kebab}', price: { minor: 1200, currency: 'USD' } };
+
+unitTest('create${feature.pascal} is a declared action', () => {
+  expect(target.kind).toBe('action');
+  expect(target.describe().name).toBe('create${feature.pascal}');
+});
+
+unitTest('create${feature.pascal} takes the columns a caller supplies', async () => {
+  await expect(target.input).toAcceptInput(input);
+  await expect(target.input).toRejectInput({ price: input.price });
+});
+`;
+
+const createContractTest = (
+  feature: NameSet,
+): string => `// create${feature.pascal}: the contract every action owes, and the orgless actor it denies before
+// the handler runs — the org a row is written under is the actor's, so an actor with none is refused.
+import { testActor } from '@ultimat3/policy';
+import { contractTest, expect } from '@ultimat3/testing';
+import { create${feature.pascal} } from './create-${feature.kebab}';
+
+const target = create${feature.pascal}.named('create${feature.pascal}');
+const input = { title: 'A ${feature.kebab}', price: { minor: 1200, currency: 'USD' } };
+
+// Holds the grant and belongs to no org: the denial is the predicate deciding, not the grant.
+const orgless = testActor('orgless', { permissions: ['${feature.kebab}:write'] }).actor;
+// And one that holds both, so the refusal above is not simply "every actor is refused".
+const writer = testActor('writer', {
+  orgId: '${ORG}',
+  permissions: ['${feature.kebab}:write'],
+}).actor;
+
+contractTest('create${feature.pascal} passes the action contract', async () => {
+  for (const contract of target.contract()) await contract.run();
+});
+
+contractTest('create${feature.pascal} needs an actor with an org', async () => {
+  expect(await target.as(orgless, input).catch((error: unknown) => error)).toBeUltimateError(
+    'X_FORBIDDEN',
+  );
+  await expect(target.policy).not.toDenyPolicy({ actor: writer, input });
+});
+
+contractTest('create${feature.pascal} projects one operation', () => {
+  expect(target.openapi().operationId).toBe('create${feature.pascal}');
+});
+`;
+
+/** The create action and its two suites, under `<slice>/actions/create-<feature>`. */
+export function resourceCreateFiles(rawName: string, sliceDir: string): readonly GeneratedFile[] {
+  const feature = names(rawName);
+  const dir = `${sliceDir}/actions`;
+  return [
+    { path: `${dir}/create-${feature.kebab}.ts`, contents: createSource(feature) },
+    { path: `${dir}/create-${feature.kebab}.test.ts`, contents: createUnitTest(feature) },
+    {
+      path: `${dir}/create-${feature.kebab}.contract.test.ts`,
+      contents: createContractTest(feature),
+    },
+  ];
+}