create-substrat 0.10.16 → 0.11.1

package/index.js

@@ -17,7 +17,7 @@ import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { DEV_SERVERS } from './dev-servers.js';
-import { TSCONFIG, VITEST_CONFIG } from './project-files.js';
+import { TEST_RUNNER, TSCONFIG, VITEST_CONFIG } from './project-files.js';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const TEMPLATE = join(HERE, 'template');
@@ -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.139.0';
-const ENGINE_WORKORDER = '^0.12.23';
-const ENGINE_INVOICING = '^0.11.23';
-const BOUNDARY_LINT = '^0.6.1';
-const DEV_ISSUER = '^0.2.21';
-const ATTACHMENT_EXTRACTORS = '^0.2.0';
+const SUBSTRAT = '^0.141.0';
+const ENGINE_WORKORDER = '^0.12.25';
+const ENGINE_INVOICING = '^0.11.25';
+const BOUNDARY_LINT = '^0.6.2';
+const DEV_ISSUER = '^0.2.23';
+const ATTACHMENT_EXTRACTORS = '^0.2.2';
 
 const DOCS = 'https://substrat.net';
 
@@ -114,8 +114,8 @@ function packageJson(name) {
         issuer: 'substrat-dev-issuer --personas src/personas.ts',
         server: 'tsx src/server.ts',
         test: 'vitest run',
-        // The live test dashboard in the Browser pane: the `tests` entry of
-        // .claude/launch.json. `--watch` is explicit, since vitest runs once and exits without a TTY.
+        // The live test dashboard: the `tests` entry of .claude/launch.json, opened at the
+        // tokenised URL vitest prints. `--watch` is explicit, since vitest runs once and exits without a TTY.
         'test:ui': 'vitest --watch --ui --open=false -c vitest.ui.config.ts',
         typecheck: 'tsc --noEmit && tsc -p tsconfig.worker.json --noEmit',
         'lint:boundaries': 'substrat-boundary-lint',
@@ -144,8 +144,7 @@ function packageJson(name) {
         concurrently: '^9.0.0',
         tsx: '^4.19.0',
         typescript: '^5.6.0',
-        vitest: '^3.0.0',
-        '@vitest/ui': '^3.0.0',
+        ...TEST_RUNNER,
       },
       // Do NOT add `zod` here — import `z` from `@substrat-run/contracts` (AGENTS.md, rule 10).
       // better-sqlite3 >=13 ships prebuilt binaries for every supported platform and

package/package.json

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

package/project-files.js

@@ -52,3 +52,11 @@ export default defineConfig({
   },
 });
 `;
+
+/**
+ * The test runner a scaffold installs. Here rather than inline in `index.js`'s `packageJson()`
+ * so `tools/template-sync.mjs` can hold it to the vitest the workspace runs the template on
+ * (#2129): `packages/template-check` tests the template on the catalog's vitest, and a scaffold
+ * on a different major is a project nothing on a PR has ever run.
+ */
+export const TEST_RUNNER = { vitest: '^5.0.0', '@vitest/ui': '^5.0.0' };

package/template/AGENTS.md

@@ -336,6 +336,11 @@ The page worth opening first on a vertical that serves the Scalar API reference
 vertical's own origin, so a try-it request carries the session cookie you already have and
 a 403 in the playground is the permission system working rather than a broken page.
 
+The `tests` entry is the one whose bare origin shows nothing: the vitest dashboard serves
+only the URL it prints when it starts (`UI started at …/__vitest__/?token=…`) and answers a
+403 without the token, which guards an API that can write files and run code. Take that URL
+from the server's output; never work around the token.
+
 ## When it breaks — symptom → fix
 
 Six failures that have each cost someone a day. What makes them expensive is that none of

package/template/src/module.ts

@@ -254,13 +254,12 @@ const closeRepairOp: Op<'shop/close-repair'> = async (ctx, input) => {
  * on their own customer record, so the walk workorder → bike → customer lets
  * them through for their own repairs and no one else's.
  *
- * Paged by OVER-FETCHING, which is what a permission-filtered walk needs: a page
+ * Paged with `pageVisible`, which is what a permission-filtered walk needs: a page
  * of 20 rows read from the table can leave 3 standing after the proof walk, so the
- * fetch size and the page size are not the same number and cannot be made the same
- * number. `pageVisible` does the over-fetch and advances the cursor by the last row
- * EXAMINED — advancing by the last row RETURNED would re-examine every rejected row
- * on the next request, and a page the walk rejects entirely would never advance at
- * all. So a SHORT page does not end this walk; only a null `nextCursor` does.
+ * fetch size and the page size are not the same number. `pageVisible` reads on past
+ * refused rows until the page is full or the budget is spent. It seals the
+ * continuation, including on a short page at a budget stop, so a refused row's
+ * position never reaches the caller (#2074).
  */
 const portalRepairsOp: Op<'shop/portal-repairs'> = async (ctx, input) =>
   pageVisible(
@@ -268,6 +267,7 @@ const portalRepairsOp: Op<'shop/portal-repairs'> = async (ctx, input) =>
     input,
     async (order) =>
       (await ctx.check(WO.read, { entityType: 'workorder', entityId: order.id })).allowed,
+    { continuation: ctx.pageContinuation('workorder:portal-repairs', input) },
   );
 
 /**

package/template/src/provision.ts

@@ -1,5 +1,6 @@
 import {
   definePermissions,
+  type EntityGrantShape,
   type PermissionKey,
   type RoleDefinition,
 } from '@substrat-run/contracts';
@@ -65,9 +66,18 @@ export const portalPerms: PermissionKey[] = [WO.read];
  * Entity-narrowed grant SHAPES. The grants themselves are per-principal and
  * minted at runtime, so they can never be a build artifact; their shape is what
  * tells a reviewer which keys are reachable outside the role table.
+ *
+ * `customer` is a BOOTSTRAP shape: a person linked to a customer record is
+ * given all of it at once (`grantEntityShape`, never key by key), and when you
+ * add a key here, the platform's next reconcile gives it to everyone who
+ * already holds the shape. A customer record names no principal and can have
+ * several people, so its holder is `'grantee'`: whoever holds a key of it
+ * there. That stays true because `ctx.grant` cannot give these keys on a
+ * customer. A shape people reach by sharing (`ctx.grant`) is declared without
+ * `bootstrap`, and is never topped up.
  */
-export const ENTITY_GRANTS: { entityType: string; permissions: PermissionKey[] }[] = [
-  { entityType: 'customer', permissions: portalPerms },
+export const ENTITY_GRANTS: EntityGrantShape[] = [
+  { entityType: 'customer', permissions: portalPerms, bootstrap: true, holder: 'grantee' },
 ];
 
 /**

package/template/src/routes.ts

@@ -1,5 +1,5 @@
 import type { Context, Hono } from 'hono';
-import { mountOperations, problemResponse, type ResolveStub } from '@substrat-run/vertical-host';
+import { externalInput, externalJson, mountOperations, problemResponse, type ResolveStub } from '@substrat-run/vertical-host';
 import { bikeShopEngineRoutes, bikeShopInvoicingRoutes, bikeShopOperations } from './operations.js';
 
 /**
@@ -76,7 +76,9 @@ export function mountApi(
   // `shop/complete-repair` wraps) is still callable here, on BOTH hosts.
   app.post('/api/invoke', async (c) => {
     const { op, input } = await c.req.json<{ op: string; input?: unknown }>();
-    return c.json((await (await resolveStub(c)).invoke(op, input)) ?? null);
+    // Through the platform's one door (#2073), as the derived routes are: a caller cannot ask
+    // for a page's row cursors, and none ever leave in a response.
+    return externalJson(c, (await (await resolveStub(c)).invoke(op, externalInput(input))) ?? null);
   });
 
   // Returns what it mounted, in registration order — a test pins the complete

package/template/src/seed.ts

@@ -12,7 +12,7 @@ import {
 import { ulid } from '@substrat-run/kernel';
 import { SqliteScopeHost } from '@substrat-run/adapter-sqlite';
 import { defaultAttachmentExtractors } from '@substrat-run/attachment-extractors';
-import { ENTITLEMENT_KEYS, MODULES, OWNER_ROLE_KEY, portalPerms, ROLES } from './provision.js';
+import { ENTITLEMENT_KEYS, ENTITY_GRANTS, MODULES, OWNER_ROLE_KEY, portalPerms, ROLES } from './provision.js';
 
 // The provisioning surface (modules, roles, grant shapes) lives in
 // provision.ts — node-free so the worker bundles it and `substrat push` reads
@@ -86,13 +86,14 @@ async function provisionShop(
  * Idempotent seed. Everything that mutates the control plane runs only on a
  * FRESH data dir (guarded by cast.json); on restart the tenants, roles, grants
  * and entities are already in the SQLite files, so we just rebuild the handle
- * object. Safe to call on every server start and on every test.
+ * object — and re-apply the portal grants, which are idempotent. Safe to call
+ * on every server start and on every test.
  */
 export async function seedBikeShop(host: SqliteScopeHost, dir: string): Promise<BikeShopWorld> {
   const castPath = join(dir, 'cast.json');
   if (existsSync(castPath)) {
     const raw = JSON.parse(readFileSync(castPath, 'utf8')) as Record<string, string>;
-    return {
+    const world: BikeShopWorld = {
       t1: tenantId.parse(raw.t1),
       s1: scopeId.parse(raw.s1),
       t2: tenantId.parse(raw.t2),
@@ -107,6 +108,8 @@ export async function seedBikeShop(host: SqliteScopeHost, dir: string): Promise<
       crescentId: raw.crescentId!,
       bianchiId: raw.bianchiId!,
     };
+    await grantPortals(host, world);
+    return world;
   }
 
   const staff = platformActorId.parse(ulid());
@@ -202,26 +205,38 @@ export async function seedBikeShop(host: SqliteScopeHost, dir: string): Promise<
   world.crescentId = crescent.id;
   world.bianchiId = bianchi.id;
 
-  // Portal grants: entity-narrowed per customer (ENTITY_GRANTS). Lisbeth and
-  // Otto each hold workorder:read on their OWN customer record only — the walk
-  // workorder → bike → customer does the rest.
+  await grantPortals(host, world);
+
+  writeFileSync(castPath, JSON.stringify(world, null, 2));
+  return world;
+}
+
+/**
+ * Portal grants: the `customer` shape (ENTITY_GRANTS) on each customer's own
+ * record. Lisbeth and Otto each hold workorder:read on their OWN customer
+ * record only — the walk workorder → bike → customer does the rest.
+ *
+ * Given as the SHAPE, so a key you add to `portalPerms` later reaches them,
+ * and then topped up to the shape as it is now, which is what the platform's
+ * reconcile does for a deployed install. Both are idempotent, so this runs on
+ * every boot, and a world seeded before you added a key receives it.
+ */
+async function grantPortals(host: SqliteScopeHost, world: BikeShopWorld): Promise<void> {
+  const staff = platformActorId.parse(ulid());
+  const node = { tenantId: world.t1, scopeId: world.s1 };
   for (const [principal, customerId] of [
     [world.lisbeth, world.lisbethId],
     [world.otto, world.ottoId],
   ] as const) {
-    for (const permission of portalPerms) {
-      await host.admin.grant(staff, {
-        principalId: principal,
-        permission,
-        node: { tenantId: world.t1, scopeId: world.s1 },
-        entity: { entityType: 'customer', entityId: customerId },
-        grantedBy: world.greta,
-      });
-    }
+    await host.admin.grantEntityShape(staff, {
+      principalId: principal,
+      node,
+      entity: { entityType: 'customer', entityId: customerId },
+      permissions: portalPerms,
+      grantedBy: world.greta,
+    });
   }
-
-  writeFileSync(castPath, JSON.stringify(world, null, 2));
-  return world;
+  await host.admin.reconcileEntityGrantShapes(staff, node, ENTITY_GRANTS);
 }
 
 /**

package/template/test/invoke-route.test.ts

@@ -0,0 +1,47 @@
+/**
+ * The generic `/api/invoke` route goes through the platform's one door (#2073).
+ *
+ * A page's `rowCursors` are each row's own cursor: an in-process answer for a walk that stops
+ * partway through a page. A handler that filtered its entries after the read would leave them
+ * naming the rows it dropped, so they never leave in a response — and a caller cannot ask for
+ * them. This route is hand-written, not derived, so it is held to that here.
+ */
+import { Hono } from 'hono';
+import { describe, expect, it } from 'vitest';
+import type { ScopeStub } from '@substrat-run/kernel';
+import { mountApi } from '../src/routes.js';
+
+function harness(result: unknown) {
+  const got: { input?: unknown } = {};
+  const app = new Hono();
+  mountApi(app, async () => ({ invoke: async (_op: string, input: unknown) => ((got.input = input), result) }) as unknown as ScopeStub);
+  const call = (input: unknown) =>
+    app.request('/api/invoke', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ op: 'shop/anything', input }),
+    });
+  return { call, got };
+}
+
+describe('/api/invoke — the one hand-written route (#2073)', () => {
+  it("never answers with a page's rowCursors, at the top or nested", async () => {
+    const page = { entries: [{ id: 'a' }], nextCursor: 'a', rowCursors: ['a', 'HIDDEN'] };
+    for (const result of [page, { nested: page, again: page }]) {
+      const text = await (await harness(result).call({})).text();
+      expect(text).toContain('"a"');
+      expect(text).not.toContain('HIDDEN');
+    }
+  });
+
+  it('keeps a rowCursors field on something that is not a page', async () => {
+    const res = await harness({ id: 'a', rowCursors: ['kept'] }).call({});
+    expect(await res.json()).toEqual({ id: 'a', rowCursors: ['kept'] });
+  });
+
+  it('a caller cannot ask for rowCursors: the operation never sees the flag', async () => {
+    const { call, got } = harness(null);
+    await call({ q: 'x', rowCursors: true });
+    expect(got.input).toEqual({ q: 'x' });
+  });
+});

package/template/test/portal-shape.test.ts

@@ -0,0 +1,75 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { platformActorId, principalId, type Page } from '@substrat-run/contracts';
+import { ulid } from '@substrat-run/kernel';
+import type { SqliteScopeHost } from '@substrat-run/adapter-sqlite';
+import { INVOICING_PERM as INV } from '@substrat-run/engine-invoicing';
+import { buildBikeShopHost, ENTITY_GRANTS, seedBikeShop, type BikeShopWorld } from '../src/seed.js';
+import { portalPerms } from '../src/provision.js';
+
+// ============================================================================
+// The portal grant is a declared SHAPE (`ENTITY_GRANTS`), so a key you add to
+// `portalPerms` reaches the customers who already hold it — including ones a
+// release before the shape grant gave it key by key.
+//
+// The second shop (t2) stands for one an older release left behind: never
+// reconciled, one repair, and Kerstin given one key of an older shape on her
+// customer's record, with no holder marker. The reconcile carries the shape
+// grown by the key she lacks (`workorder:read`, the key `shop/portal-repairs`
+// walks). Before it she sees nothing; after it she sees her repair.
+// ============================================================================
+
+describe('a key the portal shape gains reaches a customer granted before markers', () => {
+  let dir: string;
+  let host: SqliteScopeHost;
+  let w: BikeShopWorld;
+  let repairId: string;
+  const staff = platformActorId.parse(ulid());
+  const kerstin = principalId.parse(ulid());
+
+  beforeAll(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'bike-shop-portal-shape-'));
+    host = buildBikeShopHost(dir);
+    w = await seedBikeShop(host, dir);
+    const shop = await host.getScope(w.rutger, w.t2, w.s2);
+    const customer = await shop.invoke<{ id: string }>('shop/create-customer', { number: '1', name: 'Kerstin' });
+    const bike = await shop.invoke<{ id: string }>('shop/register-bike', { customerId: customer.id, label: 'Crescent' });
+    repairId = (await shop.invoke<{ id: string }>('shop/create-repair', { bikeId: bike.id, kind: 'punktering', title: 'Punktering' })).id;
+    await host.admin.grant(staff, {
+      principalId: kerstin,
+      permission: INV.read,
+      node: { tenantId: w.t2, scopeId: w.s2 },
+      entity: { entityType: 'customer', entityId: customer.id },
+      grantedBy: w.rutger,
+    });
+  });
+
+  afterAll(async () => {
+    await host.close();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const sees = async () =>
+    (await (await host.getScope(kerstin, w.t2, w.s2)).invoke<Page<{ id: string }>>('shop/portal-repairs')).entries.map((o) => o.id);
+
+  it('the seeded customers each receive one audited shape grant', async () => {
+    const grants = await host.admin.auditLog(staff, { tenantId: w.t1, scopeId: w.s1, action: 'grantEntityShape' });
+    expect(grants.map((entry) => (entry.after as { principalId: string }).principalId).sort()).toEqual([w.lisbeth, w.otto].sort());
+  });
+
+  it('the shape is declared bootstrap, and its holder is whoever holds a key of it', () => {
+    expect(ENTITY_GRANTS).toEqual([{ entityType: 'customer', permissions: portalPerms, bootstrap: true, holder: 'grantee' }]);
+  });
+
+  it('before the reconcile she sees nothing', async () => {
+    expect(await sees()).toEqual([]);
+  });
+
+  it('after it, she sees her repair', async () => {
+    const grown = ENTITY_GRANTS.map((g) => ({ ...g, permissions: [INV.read, ...g.permissions] }));
+    await host.admin.reconcileEntityGrantShapes(staff, { tenantId: w.t2, scopeId: w.s2 }, grown);
+    expect(await sees()).toEqual([repairId]);
+  });
+});

package/template/vitest.ui.config.ts

@@ -1,32 +1,20 @@
 /**
  * The config behind `pnpm test:ui` — your own `vitest.config.ts`, plus the live test
- * dashboard served on a port Claude Desktop's Browser pane can open (`.claude/launch.json`,
- * the `tests` entry).
+ * dashboard on a fixed port (`.claude/launch.json`, the `tests` entry).
  *
- * The UI lives at `/__vitest__/` and the bare origin is a 404, but a launch entry carries
- * a port and never a path, so `/` is redirected to the UI here. `VITEST_UI_PORT` moves
- * the port; it binds 127.0.0.1 only, since the dashboard can re-run your tests. The port
- * is strict: a busy one fails the start rather than moving the dashboard somewhere the
- * launch entry does not point.
+ * Open it at the URL vitest prints when it starts (`UI started at
+ * http://127.0.0.1:5290/__vitest__/?token=…`). The dashboard refuses any request without that
+ * token, because its API can re-run your tests, write files and run code; the token is what
+ * keeps another page in your browser from driving it. So nothing here redirects the bare
+ * origin to it. `VITEST_UI_PORT` moves the port; it binds 127.0.0.1 only. The port is strict:
+ * a busy one fails the start rather than moving the dashboard somewhere the launch entry does
+ * not point.
  */
-import { mergeConfig, type Plugin } from 'vitest/config';
+import { mergeConfig } from 'vitest/config';
 
 import base from './vitest.config.ts';
 
-const redirectRootToUi: Plugin = {
-  name: 'substrat:vitest-ui-root',
-  configureServer(server) {
-    server.middlewares.use((req, res, next) => {
-      if (req.url !== '/') return next();
-      res.statusCode = 302;
-      res.setHeader('Location', '/__vitest__/');
-      res.end();
-    });
-  },
-};
-
 export default mergeConfig(base, {
-  plugins: [redirectRootToUi],
   test: {
     api: {
       host: '127.0.0.1',