create-substrat 0.1.1 → 0.3.0

package/index.js

@@ -20,9 +20,12 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 const TEMPLATE = join(HERE, 'template');
 
 // Published today; Substrat is 0.x, so these are caret ranges on the current minor.
-const SUBSTRAT = '^0.29.0';
+// 0.45.0 is the release that ships `@substrat-run/vertical-host` (#510) — the
+// mountPlatformSurface the template's worker mounts — so this pin and that release
+// move together (it also covers `defineScopeSweeperDO`, #461, from 0.40.0).
+const SUBSTRAT = '^0.45.0';
 // Engines version on their own line (0.3.x), independent of the kernel/contracts line.
-const ENGINES = '^0.3.27';
+const ENGINES = '^0.3.37';
 const BOUNDARY_LINT = '^0.0.5';
 
 const DOCS = 'https://substrat.net';
@@ -64,17 +67,34 @@ function packageJson(name) {
       version: '0.0.0',
       private: true,
       type: 'module',
+      // What `substrat push` reads: the permission surface (the registry the
+      // promotion checkpoint diffs) and the runtime needs the deploy config is
+      // derived from — you never author wrangler config (src/worker.ts is the
+      // entry; ScopeDO is the store it exports).
+      substrat: {
+        permissions: 'src/provision.ts',
+        runtimeNeeds: {
+          entry: 'src/worker.ts',
+          stores: [
+            { binding: 'SCOPE', class: 'ScopeDO' },
+            // The scope-local sweep singleton — the deployment's own timer (#461).
+            { binding: 'SWEEPER', class: 'SweeperDO' },
+          ],
+        },
+      },
       scripts: {
         dev: 'tsx watch src/server.ts',
         server: 'tsx src/server.ts',
         test: 'vitest run',
-        typecheck: 'tsc --noEmit',
+        typecheck: 'tsc --noEmit && tsc -p tsconfig.worker.json --noEmit',
         'lint:boundaries': 'substrat-boundary-lint',
       },
       dependencies: {
         '@substrat-run/kernel': SUBSTRAT,
         '@substrat-run/contracts': SUBSTRAT,
         '@substrat-run/adapter-sqlite': SUBSTRAT,
+        '@substrat-run/adapter-cloudflare': SUBSTRAT,
+        '@substrat-run/vertical-host': SUBSTRAT,
         '@substrat-run/engine-workorder': ENGINES,
         '@substrat-run/engine-invoicing': ENGINES,
         hono: '^4.6.0',
@@ -83,7 +103,9 @@ function packageJson(name) {
       },
       devDependencies: {
         '@substrat-run/boundary-lint': BOUNDARY_LINT,
+        '@cloudflare/workers-types': '^4.20250109.0',
         '@types/better-sqlite3': '^7.6.0',
+        '@types/node': '^22.0.0',
         concurrently: '^9.0.0',
         tsx: '^4.19.0',
         typescript: '^5.6.0',
@@ -112,6 +134,9 @@ const TSCONFIG = `${JSON.stringify(
       types: ['node'],
     },
     include: ['src', 'test'],
+    // The worker compiles against workers-types under its own config
+    // (tsconfig.worker.json) — the node config must not see it.
+    exclude: ['src/worker.ts'],
   },
   null,
   2,

package/package.json

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

package/template/.substrat/playbook.md

@@ -103,10 +103,12 @@ Imported directly; their in-scope functions run in **your** transaction. Read ea
 **No import.** You emit; they consume. This is the star topology.
 
 - **`engine-invoicing`** — invoice basis and lines, immutable after export. Consumes
-  `workorder.completed` and `commerce.order-placed`, so a vertical that imports zero engines
-  still gets invoicing by emitting an event. Its consumer find-or-creates the customer's
-  *open* basis and appends. It has **no tax/VAT concept** — say so before an EU user
-  discovers it.
+  `workorder.completed`, `commerce.order-placed` **and** `timesheet.period-closed` (a
+  closed/approved period of reported time — `closeId`/`customer`/`period`/`billable`/
+  `total`, deduped on `closeId`), so an e-commerce or time-reporting vertical that imports
+  zero engines still gets invoicing by emitting an event. Its consumer find-or-creates the
+  customer's *open* basis and appends. It has **no tax/VAT concept** — say so before an EU
+  user discovers it.
 
 ### Tier 2b — connectors, for anything off-box
 
@@ -178,7 +180,11 @@ plain language, so nothing there is a surprise:
    than claimed.
 7. **The data we'll store** — the vertical's own tables and fields in plain terms. This
    *previews the migration diff*; migrations are **append-only forever after first ship**,
-   so this is the cheap moment to get the shape right.
+   so this is the cheap moment to get the shape right. **Every human-readable string the
+   design promises on an output artifact needs a named source here** — if §8 shows an
+   invoice line saying "Konsulttid Anna", some table in §7 must own that name, because
+   principals are ULIDs. A promised name with no source table is a missing table,
+   discovered at build time instead of in this review.
 8. **The scenario the test will replay** — the happy path plus the denials that prove
    isolation (wrong role denied, customer A sees theirs and customer B sees nothing, a
    cross-tenant attacker gets nothing).
@@ -355,10 +361,16 @@ and who can see other tenants' data?* A permission diff nobody understands is th
 
 Only if the user asks. Local-first is a legitimate stopping point.
 
-Substrat runs on Cloudflare via `@substrat-run/adapter-cloudflare` (Durable Objects). A
-vertical declares what it needs at runtime with a `substrat.runtimeNeeds` block in
-`package.json` (stores, node-compat, build). The deploy path is the authenticated CLI, and
-the author never holds a Cloudflare token:
+Substrat runs on Cloudflare via `@substrat-run/adapter-cloudflare` (Durable Objects).
+**This starter is pushable as scaffolded**: `src/worker.ts` is the deploy entry (the
+sandbox-clean shape, with the platform's `/internal/*` management contract already mounted
+via `mountPlatformSurface` from `@substrat-run/vertical-host` — you never re-author those
+routes), and package.json already carries the `substrat.runtimeNeeds` block the CLI
+derives the deploy config from (stores, node-compat, build) — you never author wrangler
+config. When you reshape the vertical, keep `src/provision.ts` the single source of
+MODULES/ROLES: both the dev server and the worker register from it, so a module added
+only in seed.ts would run locally and silently not deploy. The deploy path is the
+authenticated CLI, and the author never holds a Cloudflare token:
 
 - `substrat login` / `substrat whoami` — authenticate against the control plane.
 - `substrat push` — push the vertical; the version auto-bumps. A **private** (tenant-owned)

package/template/AGENTS.md

@@ -42,11 +42,25 @@ code** (the rules below bind them); `seed`/`server` are **harness** (exempt).
 src/manifest.ts        moduleManifest.parse({…}) + PERM consts   ← module code
 src/migrations.ts      the SqlMigration[]                         ← module code
 src/module.ts          imports both; operations + registration    ← module code
-src/seed.ts            host, tenants, roles, grants, seed world    ← harness
+src/provision.ts       MODULES, ROLES, grant shapes — node-free    ← module code
+src/seed.ts            host, tenants, demo cast, seed world        ← harness
 src/server.ts          thin wrapper, one route per operation       ← harness
+src/worker.ts          the deployable Cloudflare worker            ← harness
 test/scenario.test.ts  the scenario — including the denials
 ```
 
+`provision.ts` is deliberately node-free: both hosts register from it (the dev
+server's SQLite host and the worker's `ScopeDO`), and `substrat push` reads the
+permission registry from it (package.json `substrat.permissions`). Roles or
+modules defined anywhere else will run locally and silently not deploy.
+`worker.ts` **mounts** the platform's `/internal/*` management contract via
+`mountPlatformSurface` from `@substrat-run/vertical-host` (one call — the routes
+and the `{ error }` envelope are authored there, not here, so they can't drift or
+ship half-done). What `worker.ts` still owns is your app routes and **the auth
+seam** — the dev `x-principal` header is the only caller resolution until you wire
+real auth there; deploying with `ALLOW_DEV_HEADER` set is a cross-tenant hole with
+a UI.
+
 ## The rules (non-negotiable)
 
 **Module code** = everything reachable from a `ModuleRegistration` (operations,

package/template/src/provision.ts

@@ -0,0 +1,76 @@
+import {
+  definePermissions,
+  type PermissionKey,
+  type RoleDefinition,
+} from '@substrat-run/contracts';
+import { workorderModule, PERM as WO } from '@substrat-run/engine-workorder';
+import { invoicingModule, INVOICING_PERM as INV } from '@substrat-run/engine-invoicing';
+import { bikeShopModule } from './module.js';
+import { SHOP_PERM } from './manifest.js';
+
+// ============================================================================
+// The vertical's PROVISIONING surface — everything a deployment needs to know
+// about modules, roles and grant shapes, with NO node imports. Split from
+// seed.ts (which pulls in node:fs + the SQLite adapter) so the Cloudflare
+// worker (src/worker.ts) can bundle it, and so `substrat push` can read the
+// permission registry from it (package.json `substrat.permissions`).
+// ============================================================================
+
+/**
+ * The modules this vertical composes, in registration order. Registered by
+ * BOTH hosts (the dev server's SqliteScopeHost and the worker's ScopeDO), and
+ * read by the permission checkpoint — the artifact can never drift from what
+ * actually runs.
+ */
+export const MODULES = [workorderModule, invoicingModule, bikeShopModule];
+
+/** Entitlements are default-deny: one SKU key per module this vertical runs. */
+export const ENTITLEMENT_KEYS = ['workorder', 'invoicing', 'bikeshop'];
+
+const adminPerms: PermissionKey[] = [
+  SHOP_PERM.customerManage,
+  SHOP_PERM.bikeManage,
+  WO.create,
+  WO.read,
+  WO.assign,
+  WO.report,
+  WO.complete,
+  WO.close,
+  INV.read,
+  INV.export,
+];
+
+/**
+ * This vertical's role table — identical in every tenant, so it is a plain
+ * constant the permission snapshot can render without naming a tenant.
+ */
+export const ROLES: RoleDefinition[] = [
+  { key: 'workshop-admin', permissions: adminPerms, source: 'vertical' },
+  { key: 'mechanic', permissions: [WO.read, WO.report], source: 'vertical' },
+];
+
+/** Which role the installing owner holds — what /internal/provision assigns. */
+export const OWNER_ROLE_KEY = 'workshop-admin';
+
+/** What a portal customer receives, narrowed to their own customer record. */
+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.
+ */
+export const ENTITY_GRANTS: { entityType: string; permissions: PermissionKey[] }[] = [
+  { entityType: 'customer', permissions: portalPerms },
+];
+
+/**
+ * The single typed source for this vertical's permission surface — what the
+ * permission checkpoint and `substrat push` read (via package.json
+ * `substrat.permissions`).
+ */
+export const permissions = definePermissions({
+  modules: MODULES,
+  roles: ROLES,
+  entityGrants: ENTITY_GRANTS,
+});

package/template/src/seed.ts

@@ -5,18 +5,18 @@ import {
   principalId,
   scopeId,
   tenantId,
-  type PermissionKey,
   type PrincipalId,
-  type RoleDefinition,
   type ScopeId,
   type TenantId,
 } from '@substrat-run/contracts';
 import { ulid } from '@substrat-run/kernel';
 import { SqliteScopeHost } from '@substrat-run/adapter-sqlite';
-import { workorderModule, PERM as WO } from '@substrat-run/engine-workorder';
-import { invoicingModule, INVOICING_PERM as INV } from '@substrat-run/engine-invoicing';
-import { bikeShopModule } from './module.js';
-import { SHOP_PERM } from './manifest.js';
+import { ENTITLEMENT_KEYS, 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
+// it. Re-exported here for callers that treat seed.ts as the world's front door.
+export { ENTITY_GRANTS, MODULES, permissions, ROLES } from './provision.js';
 
 // ============================================================================
 // The seeded world. TWO tenants on purpose: the first is the shop the scenario
@@ -41,48 +41,6 @@ export interface BikeShopWorld {
   bianchiId: string; // Otto's bike
 }
 
-/**
- * The modules this vertical composes, in registration order. Exported so the
- * permission checkpoint (`pnpm lint:permissions`) renders from the same array
- * the running host registers — the artifact can never drift from reality.
- */
-export const MODULES = [workorderModule, invoicingModule, bikeShopModule];
-
-const adminPerms: PermissionKey[] = [
-  SHOP_PERM.customerManage,
-  SHOP_PERM.bikeManage,
-  WO.create,
-  WO.read,
-  WO.assign,
-  WO.report,
-  WO.complete,
-  WO.close,
-  INV.read,
-  INV.export,
-];
-
-/**
- * This vertical's role table — identical in every tenant, so it is a plain
- * constant the permission snapshot can render without naming a tenant. Exported
- * for the same reason as MODULES.
- */
-export const ROLES: RoleDefinition[] = [
-  { key: 'workshop-admin', permissions: adminPerms, source: 'vertical' },
-  { key: 'mechanic', permissions: [WO.read, WO.report], source: 'vertical' },
-];
-
-/** What a portal customer receives, narrowed to their own customer record. */
-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.
- */
-export const ENTITY_GRANTS: { entityType: string; permissions: PermissionKey[] }[] = [
-  { entityType: 'customer', permissions: portalPerms },
-];
-
 export function buildBikeShopHost(dir: string): SqliteScopeHost {
   const host = new SqliteScopeHost({ dir });
   for (const m of MODULES) host.registerModule(m);
@@ -102,7 +60,7 @@ async function provisionShop(
   await host.admin.createTenant(staff, { id: input.tenantId, slug: input.slug, name: input.name });
   // Entitlements are default-deny: the SKU flag for each module this vertical
   // runs must be granted before any of its operations resolve.
-  for (const key of ['workorder', 'invoicing', 'bikeshop']) {
+  for (const key of ENTITLEMENT_KEYS) {
     await host.admin.grantEntitlement(staff, input.tenantId, key);
   }
   await host.provisionScope(staff, {
@@ -117,7 +75,7 @@ async function provisionShop(
   for (const role of ROLES) await host.admin.defineRole(staff, input.tenantId, role);
   await host.admin.assignRole(staff, {
     principalId: input.owner,
-    roleKey: 'workshop-admin',
+    roleKey: OWNER_ROLE_KEY,
     node: { tenantId: input.tenantId, scopeId: null },
   });
 }

package/template/src/worker.ts

@@ -0,0 +1,182 @@
+/**
+ * This vertical as a deployable Cloudflare Worker — SANDBOX-CLEAN and
+ * control-plane-less: the shape `substrat push` deploys into the platform's
+ * dispatch namespace. Its only durable stores are its OWN DO classes — `SCOPE`
+ * (kernel + engines + this vertical, bundled) and `SWEEPER` (the deployment's
+ * own timer, #461); no CONTROL_PLANE binding, no service bindings, no ASSETS
+ * binding — the platform refuses those.
+ *
+ * `substrat push` derives the deploy config from `substrat.runtimeNeeds` in
+ * package.json (entry = this file, stores = the DO classes exported here) —
+ * you never author wrangler config.
+ *
+ * ── THE AUTH SEAM ────────────────────────────────────────────────────────────
+ * This starter resolves a caller ONLY through the `x-principal` dev header,
+ * gated on ALLOW_DEV_HEADER — an impersonation bypass by design, for local
+ * `wrangler dev` and smoke tests. In production the gate is off and every
+ * /api/* call is 401 until you wire real auth into `authenticatedPrincipal`
+ * below (a session/bearer verifier that maps a login → PrincipalId — see
+ * @substrat-run/vertical-auth, the platform's pluggable AuthProvider +
+ * per-tenant identity DO, for the intended shape). Deploying with the dev
+ * header enabled is a cross-tenant hole with a UI. ──────────────────────────
+ */
+import { Hono } from 'hono';
+import type { Context } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import {
+  principalId,
+  scopeId,
+  tenantId,
+  type PrincipalId,
+  type ScopeId,
+  type TenantId,
+} from '@substrat-run/contracts';
+import {
+  CloudflareScopeHost,
+  defineScopeDO,
+  defineScopeSweeperDO,
+  SCOPE_SWEEPER_NAME,
+  type ScopeSweeperDo,
+} from '@substrat-run/adapter-cloudflare';
+import { readRoutedNode, RouterAssertionError, type ScopeStub } from '@substrat-run/kernel';
+import { mountPlatformSurface } from '@substrat-run/vertical-host';
+import { MODULES, OWNER_ROLE_KEY, ROLES } from './provision.js';
+
+/** The scope-DO class = the app binary: kernel + engines + this vertical, bundled. */
+export const ScopeDO = defineScopeDO(MODULES, {});
+
+/**
+ * The deployment's own timer (#461): a roster-keeping singleton whose alarm runs
+ * each provisioned scope's due recurring work — executor retries and any
+ * `manifest.schedules` your modules declare — with no control plane anywhere.
+ * `/internal/provision` and `/internal/reconcile` add scopes to the roster;
+ * `/internal/delete-scope` removes them. Costs nothing while the roster is empty.
+ */
+export const SweeperDO = defineScopeSweeperDO<Env>({
+  intervalMs: 120_000,
+  host: hostFor,
+});
+
+/** The sweeper singleton's stub — one roster and one alarm per deployment. */
+function sweeper(env: Env): DurableObjectStub & ScopeSweeperDo {
+  return env.SWEEPER.get(
+    env.SWEEPER.idFromName(SCOPE_SWEEPER_NAME),
+  ) as DurableObjectStub & ScopeSweeperDo;
+}
+
+interface Node {
+  tenantId: TenantId;
+  scopeId: ScopeId;
+}
+
+// A fixed dev node (valid ULIDs) — ONLY the fallback for local `wrangler dev`,
+// where there is no router to assert one; gated on ALLOW_DEV_HEADER (never set
+// in prod).
+const DEV_NODE: Node = {
+  tenantId: tenantId.parse('01JZ00000000000000000DEV01'),
+  scopeId: scopeId.parse('01JZ00000000000000000DEV02'),
+};
+
+interface Env {
+  /** One DO per scope — the vertical's only durable store (sandbox-clean). */
+  SCOPE: DurableObjectNamespace;
+  /** The roster-keeping sweep singleton — the deployment's own timer (#461). */
+  SWEEPER: DurableObjectNamespace;
+  /** Local dev only: when 'true', trust the `x-principal` header. NEVER set in prod. */
+  ALLOW_DEV_HEADER?: string;
+  /** Shared secret the router presents (how this worker knows the asserted node is real). */
+  ROUTER_SECRET?: string;
+  /** Shared secret the platform presents on /internal/* calls. */
+  PLATFORM_SECRET?: string;
+}
+
+/** The routed (tenant, scope) — from the router assertion, or the dev node. */
+function nodeFor(req: Request, env: Env): Node {
+  let routed;
+  try {
+    routed = readRoutedNode(req.headers, { expectedSecret: env.ROUTER_SECRET });
+  } catch (e) {
+    if (e instanceof RouterAssertionError) throw new HTTPException(400, { message: e.message });
+    throw e;
+  }
+  if (routed) return { tenantId: routed.tenantId, scopeId: routed.scopeId };
+  if (env.ALLOW_DEV_HEADER === 'true') return DEV_NODE;
+  throw new HTTPException(503, { message: 'no scope was asserted for this request (missing router assertion)' });
+}
+
+function hostFor(env: Env): CloudflareScopeHost {
+  const host = new CloudflareScopeHost({ scope: env.SCOPE });
+  for (const m of MODULES) host.registerModule(m);
+  return host;
+}
+
+/**
+ * THE AUTH SEAM (see the header comment): resolve the caller to a PrincipalId,
+ * or null for nobody. Replace the body with a real session/bearer verifier
+ * before exposing this worker to users — the dev header is dev-only.
+ */
+async function authenticatedPrincipal(req: Request, env: Env): Promise<PrincipalId | null> {
+  if (env.ALLOW_DEV_HEADER === 'true') {
+    const parsed = principalId.safeParse(req.headers.get('x-principal') ?? '');
+    if (parsed.success) return parsed.data;
+  }
+  return null; // ← wire real auth here
+}
+
+/** Resolve caller + routed node → a scope stub. 401 if nobody. */
+async function stub(c: Context<{ Bindings: Env }>): Promise<ScopeStub> {
+  const node = nodeFor(c.req.raw, c.env);
+  const principal = await authenticatedPrincipal(c.req.raw, c.env);
+  if (!principal) throw new HTTPException(401, { message: 'unauthorized' });
+  return hostFor(c.env).getScope(principal, node.tenantId, node.scopeId);
+}
+
+const app = new Hono<{ Bindings: Env }>();
+
+// Who am I — resolves the caller without invoking anything.
+app.get('/api/me', async (c) => {
+  const principal = await authenticatedPrincipal(c.req.raw, c.env);
+  if (!principal) return c.json({ error: 'unauthorized' }, 401);
+  return c.json({ principal });
+});
+
+// Generic invoke: the kernel checks a permission inside EVERY operation, so a
+// generic route is exactly as safe as one route per operation.
+app.post('/api/invoke', async (c) => {
+  const { op, input } = await c.req.json<{ op: string; input?: unknown }>();
+  return c.json((await (await stub(c)).invoke(op, input)) ?? null);
+});
+
+// ── /internal/* — the platform-gated management contract ────────────────────
+// The control plane provisions, heals, inspects and restores installs through
+// these routes. The whole contract — provision, reconcile, introspection, the
+// read-only SQL console, platform-request drain, snapshot/delete/export/restore,
+// and bookmarks/rewind — plus the guaranteed { error } envelope is authored ONCE
+// in @substrat-run/vertical-host (issue #510); mount it and it cannot drift.
+//
+// This starter's hooks keep the deployment's sweep roster (#461) in step: a newly
+// provisioned scope joins it (so its schedules run), and a deleted one leaves it.
+// Reconcile needs a durable owner-of-record to heal from — this starter keeps none
+// (that lives with real auth, the auth seam), so `resolveOwner` is omitted and
+// /internal/reconcile answers 501 until you wire auth and supply one.
+mountPlatformSurface<Env>(app, {
+  platformSecret: (env) => env.PLATFORM_SECRET,
+  hostFor,
+  roles: ROLES,
+  ownerRoleKey: OWNER_ROLE_KEY,
+  onProvision: (env, b) => sweeper(env).noteScope(b.tenantId, b.scopeId),
+  onDeleteScope: (env, s) => sweeper(env).forgetScope(s),
+});
+
+// Unmatched /api/* fails as JSON; everything else gets a pointer, not a UI —
+// this starter ships no SPA (add one and inline it at build time when you do).
+app.all('/api/*', (c) => c.json({ error: `unknown route: ${new URL(c.req.raw.url).pathname}` }, 404));
+app.all('*', (c) =>
+  c.json({
+    service: 'substrat vertical',
+    api: 'POST /api/invoke { op, input }',
+    docs: 'https://substrat.net',
+  }),
+);
+
+export default app;

package/template/tsconfig.worker.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "types": ["@cloudflare/workers-types"],
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src/worker.ts", "src/provision.ts", "src/manifest.ts", "src/migrations.ts", "src/module.ts"]
+}