create-substrat 0.4.0 → 0.4.2

package/README.md

@@ -1,25 +1,59 @@
 # create-substrat
 
-Reserves `npm create substrat` for the Substrat initializer.
+Scaffold a [Substrat](https://substrat.net) vertical.
 
-**The initializer is not released yet.** This package prints a pointer to the docs and
-exits. It does not scaffold anything, because a stub that pretended to would be worse than
-nothing.
+```sh
+npm create substrat <dir>
+npm create substrat .        # scaffold into the current directory
+```
+
+**Full documentation: https://substrat.net/reference/create-substrat**
+
+## What you get
+
+A project that installs and runs, plus an **instruction layer** so your AI editor already
+knows the rules and the build flow:
+
+- `src/` — `manifest.ts`, `migrations.ts`, `module.ts`, `provision.ts`, `seed.ts`, a Node
+  `server.ts` for local work, and a `worker.ts` that mounts the platform surface via
+  [`@substrat-run/vertical-host`](https://npmjs.com/package/@substrat-run/vertical-host).
+- `test/scenario.test.ts` — the scenario test the build flow grows.
+- `AGENTS.md` + `.substrat/playbook.md` — the rules and the build flow, read by Claude Code,
+  Cursor, and opencode alike; each gets its own command stub.
+- Generated `package.json`, `tsconfig.json`, `vitest.config.ts`, `.gitignore`, `README.md`,
+  including the `substrat` block that `substrat push` reads — so you never author wrangler
+  config.
 
-To start a vertical today, follow the [getting started guide](https://substrat.net/guide/getting-started).
-The packages are published and usable:
+The scaffolder writes the skeleton; **the agent writes the vertical**, guided by the playbook.
 
 ```sh
-pnpm add @substrat-run/kernel @substrat-run/contracts @substrat-run/adapter-sqlite zod
+cd <dir> && pnpm install
+# then, in your AI editor:
+#   Claude Code:       /substrat
+#   Cursor / opencode: the new-vertical command
 ```
 
+## Don't add `zod`
+
+Substrat is on Zod 4, and Zod schemas do not compose across copies or majors — mixing two
+makes `z.object({ facility: entityRef })` fail at runtime with `expected a Zod schema`,
+pointing nowhere near the cause. Import `z` from contracts instead, and never install zod:
+
+```ts
+import { z, entityRef, money } from '@substrat-run/contracts';
+```
+
+## Dependency-free by design
+
+Node built-ins only, no build step. It can never break at install time and damage the name it
+exists to protect.
+
 ## Note on the name
 
 `substrat` on npm is an **unrelated** package — an HTML5 build system published in 2013.
-Substrat's own packages are all under the [`@substrat-run`](https://www.npmjs.com/org/substrat-run)
-scope. Never `npm install substrat`.
+Substrat's own packages are all under the
+[`@substrat-run`](https://www.npmjs.com/org/substrat-run) scope. Never `npm install substrat`.
 
 ---
 
-[Docs](https://substrat.net) · [Repo](https://github.com/substrat-run/substrat) ·
-Apache-2.0
+[Docs](https://substrat.net) · [Repo](https://github.com/substrat-run/substrat) · Apache-2.0

package/index.js

@@ -20,13 +20,16 @@ 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.
-// 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.37';
-const BOUNDARY_LINT = '^0.0.5';
+// The runtime packages release together off one version line, so one constant is right
+// for all of them.
+const SUBSTRAT = '^0.71.0';
+// Engines do NOT share a line — each one versions on its own, so a single ENGINES
+// constant silently stops resolving the moment any engine crosses a minor. It did:
+// this file pinned `^0.3.37` while workorder had moved to 0.4.x and invoicing to 0.6.x,
+// so a freshly scaffolded project could not install. One pin per engine, deliberately.
+const ENGINE_WORKORDER = '^0.4.3';
+const ENGINE_INVOICING = '^0.6.2';
+const BOUNDARY_LINT = '^0.0.7';
 
 const DOCS = 'https://substrat.net';
 
@@ -95,8 +98,8 @@ function packageJson(name) {
         '@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,
+        '@substrat-run/engine-workorder': ENGINE_WORKORDER,
+        '@substrat-run/engine-invoicing': ENGINE_INVOICING,
         hono: '^4.6.0',
         '@hono/node-server': '^1.13.0',
         'better-sqlite3': '^13.0.3',

package/package.json

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

package/template/.substrat/playbook.md

@@ -222,7 +222,62 @@ Approval of the design is what unlocks Step 5. Until you have it, you are still
 
 ---
 
-## Step 5 — Reshape the reference
+## Step 5 — Declare the model
+
+The design is approved. Before reshaping any code, declare **what exists** in
+`spec/model.ts`: entities, the operations over them, and the permissions those operations
+check. One TypeScript module, and the compiler checks the joins between them.
+
+```ts
+import { defineEntities, defineOperations, emitModel } from '@substrat-run/contracts';
+import { z } from '@substrat-run/contracts';
+
+export const entities = defineEntities({
+  customer: {
+    table: 'acme_customers',
+    fields: z.object({ id: z.string(), number: z.string(), name: z.string() }),
+    key: ['number'],
+    erasable: ['name'],
+  },
+  site: { table: 'acme_sites', fields: z.object({ id: z.string(), customer_id: z.string() }), parents: ['customer'] },
+});
+
+export const PERMISSIONS = ['customer:manage'] as const;
+
+export const operations = defineOperations(entities, PERMISSIONS)({
+  'acme/create-customer': {
+    summary: 'Register a customer',
+    permission: 'customer:manage',
+    input: z.object({ number: z.string(), name: z.string() }),
+    output: entities.customer.fields,
+    emits: { entity: 'customer', entityIdFrom: 'id', type: 'acme.customer-created', schemaVersion: 1, piiClass: 'none' },
+  },
+});
+
+export const model = emitModel(entities);
+```
+
+These are compile errors, not lints: a `parents` naming no entity, a `permission` that is
+not declared, an `entityIdFrom` naming no field of that operation's `output`, a `payload`
+carrying a field the entity marks `erasable`, a `{var}` in an HTTP path that names no input
+field. All before a handler exists.
+
+Field names mirror the SQL columns, snake_case included — a prettier naming here is a second
+description of the same rows. Not every table is an entity: an entity is something the
+platform can point at (attachments hang off one, grants narrow to one, events are about one).
+
+Behaviour stays prose in `DESIGN.md`. Inventing a way to declare a state *transition* means
+the boundary slipped.
+
+Full reference: https://substrat.net/concepts/model
+
+**Do not edit `spec/model.ts` while reshaping the code.** If a handler cannot return what the
+model declares, that is real information — say so and stop, rather than reshaping the model
+to make the build pass.
+
+---
+
+## Step 6 — Reshape the reference
 
 The design is approved. The scaffold already contains a working vertical in `src/` + `test/` —
 the bike-repair shop. **Read it first** (it's your Callout: the real, green implementation of
@@ -314,7 +369,7 @@ closed-door assertion with a control proving a neighbouring door is still open.
 
 ---
 
-## Step 6 — Run it
+## Step 7 — Run it
 
 Build confidence in this order, and **show the user the output of each**:
 
@@ -336,7 +391,7 @@ and typed wrappers over the routes. Ask first — it roughly doubles the work.
 
 ---
 
-## Step 7 — The two checkpoints. STOP HERE.
+## Step 8 — The two checkpoints. STOP HERE.
 
 **You may never self-approve these. Present them and wait.** The design gate (Step 4) already
 took the user's approval of *what* to build; these confirm that the code matches it.
@@ -357,7 +412,7 @@ and who can see other tenants' data?* A permission diff nobody understands is th
 
 ---
 
-## Step 8 — Deploy (optional)
+## Step 9 — Deploy (optional)
 
 Only if the user asks. Local-first is a legitimate stopping point.
 
@@ -389,7 +444,7 @@ cross-tenant hole with a UI.
 
 ---
 
-## Step 9 — Leave the project competent
+## Step 10 — Leave the project competent
 
 The next session — in any tool — starts cold. The scaffold already ships `AGENTS.md`,
 `CLAUDE.md`, and the Cursor/opencode command stubs, so the rules and this flow survive. Your