create-substrat 0.4.1 → 0.5.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',
@@ -159,6 +162,12 @@ dist/
 *.db
 .data/
 .DS_Store
+
+# Which kernel version this checkout last announced to an agent (.substrat/hooks
+# /session-start.mjs). Per-checkout state, not a project fact.
+.substrat/.docs-pin
+# Opt out of that hook entirely by creating this file.
+.substrat/no-session-context
 `;
 
 function readme(name) {

package/package.json

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

package/template/.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.substrat/hooks/session-start.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/template/.substrat/hooks/session-start.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/**
+ * SessionStart hook — the project announces itself (#754).
+ *
+ * The smooth part of a framework's agent integration is not the skills, it is
+ * that the user never has to remember the framework *has* an integration. This
+ * runs when an agent session starts, and if the project is a Substrat vertical
+ * it hands the agent three things it would otherwise have to discover: what this
+ * project is, where the rules live, and **which version of the docs describes the
+ * kernel actually installed here**.
+ *
+ * That last one is the reason this exists. Substrat is 0.x and interfaces change
+ * without notice, so an agent working from pages it cached two minors ago is the
+ * expensive failure — confident, plausible, and wrong. `llms.txt` is published at
+ * a version-pinned URL precisely so this hook can point at the matching slice.
+ *
+ * ## Deliberately not tool-specific
+ *
+ * This file lives in `.substrat/` — the tool-neutral home, next to `playbook.md` —
+ * not in `.claude/`. `.claude/settings.json` is a three-line adapter that runs it,
+ * and any other client that grows a session hook binds the same way. It also
+ * means the plugin distribution (#753) can ship this script unchanged rather than
+ * forking it.
+ *
+ * ## Deliberately silent, and deliberately offline
+ *
+ * It prints nothing at all unless `package.json` has a `substrat` block, so it is
+ * inert in any other project. And it makes **no network request**: session start
+ * is on the critical path of every session and is frequently offline, while the
+ * check a fetch would perform — does the published doc set still describe my
+ * kernel — is already mechanical for whoever actually fetches, because
+ * `/llms-<version>.txt` 404s exactly when the answer is no.
+ *
+ * Opt out by creating `.substrat/no-session-context`.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const DOCS = 'https://substrat.net';
+const KERNEL = '@substrat-run/kernel';
+
+/** Where the project is. Claude Code sets this; fall back to the cwd it ran us in. */
+const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+/** The marker: which kernel version this project last announced. */
+const MARKER = join(root, '.substrat', '.docs-pin');
+const OPT_OUT = join(root, '.substrat', 'no-session-context');
+
+/** Nothing this hook does is worth failing a session over. */
+function silent() {
+  process.exit(0);
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return undefined;
+  }
+}
+
+function main() {
+  if (existsSync(OPT_OUT)) silent();
+
+  const pkg = readJson(join(root, 'package.json'));
+  // The detection signal is the block `substrat push` already reads — no sentinel
+  // file to invent, and nothing to keep in sync.
+  if (!pkg?.substrat) silent();
+
+  if (existsSync(OPT_OUT)) silent();
+
+  // What is actually installed beats what package.json asked for: a caret range on
+  // 0.x pins the minor, and the resolved version is what the code compiles against.
+  const installed = readJson(join(root, 'node_modules', KERNEL, 'package.json'))?.version;
+  const declared = pkg.dependencies?.[KERNEL] ?? pkg.devDependencies?.[KERNEL];
+
+  const lines = [
+    'This project is a **Substrat vertical** — a multi-tenant business app on the',
+    'Substrat kernel and its engines.',
+    '',
+    '- The always-on rules you must not violate are in `AGENTS.md` — module-code',
+    '  boundaries, the gates, and the two checkpoints you may never self-approve.',
+    '- The build flow (interview → design → reshape → checkpoints) is `.substrat/playbook.md`.',
+    '  It is a playbook, not always-on context: read it when starting or extending a vertical.',
+  ];
+
+  if (installed) {
+    lines.push(
+      '',
+      `This project has **${KERNEL} ${installed}** installed.`,
+      '',
+      `Docs describing that exact version: ${DOCS}/llms-${installed}.txt`,
+      '',
+      'That URL returns 200 only while the published docs still describe this kernel. A 404',
+      `means they have moved on — fetch ${DOCS}/llms.txt instead, and treat anything you`,
+      'already believe about the API as unverified. Substrat is pre-1.0 and interfaces change',
+      'without notice, so do not answer from memory about its surface; the pages are markdown',
+      'at those URLs and every doc page has a `.md` twin.',
+    );
+
+    const announced = existsSync(MARKER) ? readFileSync(MARKER, 'utf8').trim() : '';
+    if (announced && announced !== installed) {
+      lines.unshift(
+        `**The kernel moved: ${announced} → ${installed} since the last session here.**`,
+        'Re-read the docs slice below before relying on anything you remember about the API.',
+        '',
+      );
+    }
+    try {
+      mkdirSync(dirname(MARKER), { recursive: true });
+      writeFileSync(MARKER, `${installed}\n`);
+    } catch {
+      // A read-only checkout still gets the context; it just re-announces next time.
+    }
+  } else {
+    lines.push(
+      '',
+      `**${KERNEL} is not installed yet** (\`package.json\` asks for \`${declared ?? 'it'}\`).`,
+      'Run the install before trusting any version-specific guidance, then re-check the docs',
+      `index at ${DOCS}/llms.txt.`,
+    );
+  }
+
+  process.stdout.write(
+    `${JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: lines.join('\n'),
+      },
+    })}\n`,
+  );
+}
+
+try {
+  main();
+} catch {
+  // Never break a session because orientation failed.
+  silent();
+}

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