create-substrat 0.11.2 → 0.11.4

package/index.js

@@ -36,12 +36,12 @@ const TEMPLATE = join(HERE, 'template');
 // The runtime packages release together off one version line (the changesets `fixed`
 // group), so one constant is right for all of them. Engines do NOT share a line —
 // each versions on its own, so one pin per engine, deliberately.
-const SUBSTRAT = '^0.142.0';
-const ENGINE_WORKORDER = '^0.12.26';
-const ENGINE_INVOICING = '^0.11.26';
-const BOUNDARY_LINT = '^0.6.2';
-const DEV_ISSUER = '^0.2.24';
-const ATTACHMENT_EXTRACTORS = '^0.2.3';
+const SUBSTRAT = '^0.144.0';
+const ENGINE_WORKORDER = '^0.12.28';
+const ENGINE_INVOICING = '^0.11.28';
+const BOUNDARY_LINT = '^0.7.0';
+const DEV_ISSUER = '^0.2.26';
+const ATTACHMENT_EXTRACTORS = '^0.2.5';
 
 const DOCS = 'https://substrat.net';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-substrat",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "description": "Scaffold a Substrat vertical — `npm create substrat <dir>`.",
   "license": "Apache-2.0",
   "repository": {

package/template/.substrat/playbook.md

@@ -376,9 +376,9 @@ operations + the `ModuleRegistration`. Keep the split — the linter and tests e
   timestamps, money/decimals as TEXT. **Append-only forever after first ship.**
 - Operations: first line is always `assertAllowed(await ctx.check(PERM))`.
   `ctx.link(child, parent)` when creating related entities.
-- **Handlers do not hand-parse their input.** The module passes
-  `operationInputs: operationInputsOf(<vertical>Operations)` beside its `operations`, and
-  the host parses every invocation against the declared schema before the guards and the
+- **Handlers do not hand-parse their input.** The module binds its handlers with
+  `...operationsFor(<vertical>Operations)({ … })`, which hands the host the declared schemas
+  with them, and the host parses every invocation against them before the guards and the
   handler run — on every path in (HTTP, test, seed, schedule). The reference module already
   does this; keep it. An inline `z.object(…).parse(input)` at the top of a handler is a
   second description of a schema the model already declares, and it only covers the paths

package/template/AGENTS.md

@@ -150,15 +150,21 @@ export const bikeShopOperations = defineOperations(bikeShopEntities, SHOP_PERMIS
 Then `src/module.ts` holds only the **bodies**, bound to that declaration:
 
 ```ts
-} satisfies OperationImpl<typeof bikeShopOperations, OperationContext>;
+const bound = operationsFor(bikeShopOperations)({
+  'shop/create-customer': createCustomerOp,
+  …
+});
+export const bikeShopModule: ModuleRegistration = { manifest, migrations, ...bound };
 ```
 
-Four things are now compile errors at the exact method: a handler whose input
+Five things are now compile errors at the exact method: a handler whose input
 disagrees with the declared `input`, one whose return disagrees with `output`, an
-operation declared and not implemented, and one implemented and not declared. The
-same object feeds `operationInputs: operationInputsOf(bikeShopOperations)`, so the
-schemas the host parses with are the ones the declaration states — they cannot drift,
-because there is only one of them.
+operation declared and not implemented, one implemented and not declared, and one
+whose type was thrown away with `as never` or `as any`. The same call hands the host
+the schemas it parses with (`operationInputsOf(bikeShopOperations)`), so they are the
+ones the declaration states — they cannot drift, because there is only one of them.
+A registration takes no other kind of map: a hand-written `operations: { … }` does not
+compile, and `boundary-lint` refuses a cast of the whole map.
 
 The permission list works the same way. `SHOP_PERMISSIONS`, the array handed to
 `defineOperations`, is also the `keys` that `src/provision.ts` hands
@@ -190,6 +196,23 @@ matter what the operation supports, forget the second and it answers with an
 envelope where it used to answer with an array. That is the case for not
 hand-mounting anything an operation can declare.
 
+**An operation the model describes completely says who writes its handler.** These
+shapes are derivable: a `GET` of one row by its id, a `GET` that is a `paged.over` page of the
+entity's own rows behind declared filters, a `PATCH` field bag with `concurrency`, a
+`DELETE` of a row nothing declares as parent, a `POST` that inserts a row every column of
+which comes from the input, the parent its check narrows to, a minted id or the entity's
+declared `stamps`, and, on an entity that declares `archive` or `trash`, its four moves and
+its bin. Declare `derive: 'get'` (or `'list'`, `'update'`, `'delete'`, `'create'`,
+`'archive'`, `'unarchive'`, `'trash'`, `'restore'`, `'trashed'`) and write no handler:
+`operationsFor` leaves it out of the map it requires and supplies the platform's handler,
+which checks the declared key first, reads and writes only declared columns and emits the
+declared event (the bin is checked row by row instead, and a move's event is the kernel's).
+Keep a handler
+only with `authored: '<what the derived one would get wrong here>'`. `defineOperations`
+refuses at module load a derivable operation that declares neither, a `derive` whose
+declaration is not that shape, and an `authored` on an operation nothing could derive.
+Each refusal names its remedy.
+
 ## The rules (non-negotiable)
 
 **Module code** = everything reachable from a `ModuleRegistration` (operations,
@@ -239,11 +262,11 @@ consumers). Rules 1–5 are enforced mechanically by `boundary-lint`.
    (`moneyOf`, `mulMoney`, `addDecimal`, `compareDecimal`) — never floats.
 10. **Web-standard APIs always** — `globalThis.crypto`, `TextEncoder`, `URL`. Never
     hand-roll a hash to dodge an import ban.
-11. **Parse, don't trust** — and the **host** is what parses. A module passes
-    `operationInputs: operationInputsOf(ops)` beside its `operations`, and every invocation
-    is parsed against the declared schema before the guards and the handler, on every path
-    in (HTTP, test, seed, schedule). Handlers do not hand-parse; a declared input nobody
-    parses stops being possible rather than merely discouraged. Import `z` from
+11. **Parse, don't trust** — and the **host** is what parses. A module binds its
+    handlers with `operationsFor(ops)(…)`, which hands the host the declared schemas with
+    them, and every invocation is parsed against them before the guards and the handler,
+    on every path in (HTTP, test, seed, schedule). Handlers do not hand-parse; a declared
+    input nobody parses stops being possible rather than merely discouraged. Import `z` from
     `@substrat-run/contracts`, **never from `zod`**. Zod schemas don't compose across
     copies or majors; composing a contracts schema into one built from a separate `zod`
     fails at *runtime* (`expected a Zod schema`) with an error pointing nowhere near the

package/template/src/entities.ts

@@ -1,4 +1,4 @@
-import { defineEntities, emitModel, z } from '@substrat-run/contracts';
+import { defineEntities, z } from '@substrat-run/contracts';
 
 // ============================================================================
 // The bike shop's ENTITY REGISTRY — what this vertical declares exists.
@@ -71,13 +71,3 @@ export const bikeShopEntities = defineEntities({
   },
 });
 
-/**
- * The artifact of record, emitted from the declaration above.
- *
- * A scaffolded project is not in this repo's `demos/`, so nothing here re-emits
- * a `model.json` for it — `pnpm lint:model` walks `demos/` and `engines/`. What
- * this export is for in a scaffold is the same thing it is for in the reference
- * verticals: one object downstream reads, so the authoring notation stays
- * swappable.
- */
-export const bikeShopModel = emitModel(bikeShopEntities);

package/template/src/model.ts

@@ -0,0 +1,16 @@
+import { emitModel } from '@substrat-run/contracts';
+import { bikeShopEntities } from './entities.js';
+import { bikeShopOperations } from './operations.js';
+
+/**
+ * The artifact of record, emitted from the declaration.
+ *
+ * A file of its own, because it renders who writes each handler (`derive` or `authored`), so it
+ * reads the operations, and the operations import the entities. Nothing imports it back.
+ *
+ * A scaffolded project is not in this repo's `demos/`, so nothing here re-emits a `model.json`
+ * for it — `pnpm lint:model` walks `demos/` and `engines/`. What this export is for in a
+ * scaffold is the same thing it is for in the reference verticals: one object downstream reads, so
+ * the authoring notation stays swappable.
+ */
+export const bikeShopModel = emitModel(bikeShopEntities, { operations: bikeShopOperations });

package/template/src/module.ts

@@ -4,21 +4,20 @@ import {
   listLimitOf,
   moneyOf,
   mulMoney,
-  operationInputsOf,
   pageOf,
   pageVisible,
+  substratError,
   z,
   type HandlerInput,
   type HandlerOutput,
-  type OperationImpl,
 } from '@substrat-run/contracts';
 import {
   assertAllowed,
   readTimeline,
   ulid,
   type ModuleRegistration,
-  type OperationContext,
   type OperationHandler,
+  operationsFor,
 } from '@substrat-run/kernel';
 import {
   closeWorkOrder,
@@ -46,7 +45,7 @@ import { bikeShopMigrations } from './migrations.js';
 //
 // WHAT EACH OPERATION IS is declared in `src/operations.ts`, against the
 // entities in `src/entities.ts` — this file holds only the bodies. The binding
-// at the bottom is `satisfies OperationImpl<…>`, so a handler that disagrees
+// at the bottom is `operationsFor(bikeShopOperations)`, so a handler that disagrees
 // with its declaration is a compile error at the exact method.
 // ============================================================================
 
@@ -111,7 +110,7 @@ const registerBikeOp: Op<'shop/register-bike'> = async (ctx, input) => {
   const customer = ctx.sql.query<CustomerRow>('SELECT * FROM shop_customers WHERE id = ?', [
     input.customerId,
   ])[0];
-  if (!customer) throw new Error(`customer not found: ${input.customerId}`);
+  if (!customer) throw substratError('not_found', `customer not found: ${input.customerId}`);
   const id = ulid();
   ctx.sql.exec(
     `INSERT INTO shop_bikes (id, customer_id, label, frame_no, created_at) VALUES (?, ?, ?, ?, ?)`,
@@ -169,7 +168,7 @@ const priceListOp: Op<'shop/price-list'> = async (ctx, input) => {
 const createRepairOp: Op<'shop/create-repair'> = async (ctx, input) => {
   assertAllowed(await ctx.check(WO.create));
   const bike = ctx.sql.query<BikeRow>('SELECT * FROM shop_bikes WHERE id = ?', [input.bikeId])[0];
-  if (!bike) throw new Error(`bike not found: ${input.bikeId}`);
+  if (!bike) throw substratError('not_found', `bike not found: ${input.bikeId}`);
   return createWorkOrder(ctx, {
     facility: { entityType: 'bike', entityId: bike.id },
     customer: { entityType: 'customer', entityId: bike.customer_id },
@@ -294,12 +293,13 @@ const timelineOp: Op<'shop/timeline'> = async (ctx, input) => {
 };
 
 /**
- * The handlers, bound to `bikeShopOperations`. `satisfies` is the drift
+ * The handlers, bound to `bikeShopOperations`. `operationsFor` is the drift
  * detector: change a declared input or return and tsc names the method whose
  * handler no longer agrees. An operation declared but not implemented, or
- * implemented but not declared, is an error here too.
+ * implemented but not declared, is an error here too — and the schemas the
+ * host parses every invocation with come from the same declaration.
  */
-const declaredOperations = {
+const bound = operationsFor(bikeShopOperations)({
   'shop/create-customer': createCustomerOp,
   'shop/list-customers': listCustomersOp,
   'shop/register-bike': registerBikeOp,
@@ -310,21 +310,10 @@ const declaredOperations = {
   'shop/close-repair': closeRepairOp,
   'shop/portal-repairs': portalRepairsOp,
   'shop/timeline': timelineOp,
-} satisfies OperationImpl<typeof bikeShopOperations, OperationContext>;
+});
 
 export const bikeShopModule: ModuleRegistration = {
   manifest: bikeShopManifest,
   migrations: bikeShopMigrations,
-  // The host parses every invocation against the DECLARED input schemas before
-  // the guards, the permission check and the handler — so "parse, don't trust"
-  // holds on every path in (HTTP, test, seed, schedule) rather than in the
-  // handlers that remembered to do it themselves.
-  operationInputs: operationInputsOf(bikeShopOperations),
-  operations: {
-    // All ten bound to the declaration: input and return are checked against
-    // `bikeShopOperations` at the exact method. The `as never` casts this map
-    // used to carry were never necessary — `OperationHandler<never, unknown>`
-    // accepts any handler by contravariance — they simply threw the types away.
-    ...(declaredOperations as Record<string, OperationHandler<never, unknown>>),
-  },
+  ...bound,
 };

package/template/src/operations.ts

@@ -14,12 +14,11 @@ import { bikeShopEntities } from './entities.js';
 // HTTP API.
 //
 // This is one declaration, not documentation of another one. `src/module.ts`
-// binds its handlers to this object with `satisfies OperationImpl<…>`, so four
-// things become compile errors at the exact method: a handler whose input
+// binds its handlers to this object with `operationsFor(bikeShopOperations)`, so
+// four things become compile errors at the exact method: a handler whose input
 // disagrees with `input`, one whose return disagrees with `output`, an
 // operation declared and not implemented, and one implemented and not declared.
-// `operationInputsOf(bikeShopOperations)` hands the host the same schemas, so
-// every invocation is parsed before the guards and the handler — and
+// The same call hands the host the declared schemas, so every invocation is parsed before the guards and the handler — and
 // `mountOperations` (src/routes.ts) derives the route table from the `http`
 // each operation declares, so a `{var}` in a path that names no input field is
 // a compile error too, and there is no second list of routes to drift.

package/template/test/entities.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
-import { bikeShopEntities, bikeShopModel } from '../src/entities.js';
+import { bikeShopEntities } from '../src/entities.js';
+import { bikeShopModel } from '../src/model.js';
 import { bikeShopMigrations } from '../src/migrations.js';
 import { bikeShopManifest } from '../src/manifest.js';
 

package/template/test/scenario.test.ts

@@ -6,6 +6,7 @@ import { Hono } from 'hono';
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
 import {
   addMoney,
+  errorCodeOf,
   moneyOf,
   mulMoney,
   type Page,
@@ -435,4 +436,34 @@ describe('bike-shop scenario', () => {
     expect((await timeline.json()) as unknown[]).toHaveLength(1);
     expect(nextOf(timeline)).toMatch(/^\/api\/repairs\/.+\/timeline\?limit=1&cursor=.+$/);
   });
+
+  // #113: a missing record is a refusal that SAYS it is `not_found`, rather than a sentence
+  // the host has to recognise. Its status follows from the code, so it survives the host
+  // dropping the wording it still reads untyped throws by — and so does the sentence.
+  it('13. an unknown customer or bike is a not_found, on the operation and over HTTP', async () => {
+    const unknown = 'nonexistent';
+    const refusalOf = (p: Promise<unknown>) => p.then(() => undefined, (e: unknown) => e);
+
+    const noCustomer = await refusalOf(
+      greta.invoke('shop/register-bike', { customerId: unknown, label: 'x' }),
+    );
+    expect(errorCodeOf(noCustomer)).toBe('not_found');
+    expect((noCustomer as Error).message).toBe(`customer not found: ${unknown}`);
+
+    const noBike = await refusalOf(
+      greta.invoke('shop/create-repair', { bikeId: unknown, kind: 'puncture', title: 'x' }),
+    );
+    expect(errorCodeOf(noBike)).toBe('not_found');
+    expect((noBike as Error).message).toBe(`bike not found: ${unknown}`);
+
+    const app = new Hono();
+    mountApi(app, async () => greta);
+    const res = await app.request('/api/repairs', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ bikeId: unknown, kind: 'puncture', title: 'x' }),
+    });
+    expect(res.status).toBe(404);
+    expect(await res.json()).toMatchObject({ code: 'not_found', detail: `bike not found: ${unknown}` });
+  });
 });