create-substrat 0.8.5 → 0.9.0

package/index.js

@@ -36,11 +36,11 @@ 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.97.0';
-const ENGINE_WORKORDER = '^0.10.5';
-const ENGINE_INVOICING = '^0.9.13';
-const BOUNDARY_LINT = '^0.3.0';
-const DEV_ISSUER = '^0.1.12';
+const SUBSTRAT = '^0.99.0';
+const ENGINE_WORKORDER = '^0.10.7';
+const ENGINE_INVOICING = '^0.9.15';
+const BOUNDARY_LINT = '^0.4.2';
+const DEV_ISSUER = '^0.1.14';
 
 const DOCS = 'https://substrat.net';
 
@@ -101,21 +101,10 @@ function packageJson(name) {
             { binding: 'CONFIG', class: 'ConfigDO' },
           ],
         },
-        // The declared per-instance settings — MIRRORED from src/manifest.ts
-        // (`SHOP_ENV`), because `substrat push` reads JSON, not TS. The dashboard
-        // renders its Settings form from this; keep the two in sync.
-        envSpec: [
-          {
-            key: 'SHOP_NAME',
-            label: 'Workshop name',
-            description: 'The workshop name shown to customers. Set per install.',
-            placeholder: 'Söder Cykel & Service',
-            default: 'Substrat Bike Shop',
-            required: false,
-            secret: false,
-            group: 'General',
-          },
-        ],
+        // No envSpec copy here (#1206): the declared per-instance settings live in
+        // src/manifest.ts (`SHOP_ENV`), re-exported as `envSpec` from the permissions
+        // entry — `substrat push` reads them off that same import. The dashboard
+        // renders its Settings form from what the push uploads.
         devServers: DEV_SERVERS,
       },
       scripts: {

package/package.json

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

package/template/AGENTS.md

@@ -87,9 +87,9 @@ dashboard reports `delivered: false`, and the app never sees it. That includes t
 back through `resolveScopedEnvSpec` (`instanceConfig`). Read settings that way and
 never off `env` directly: an `envSpec` default rides as a worker binding shared by
 every install of one serving script, so `env.FOO` is the same string for every
-tenant no matter what any of them saved. Declare a setting in **both**
-`src/manifest.ts` (`SHOP_ENV`) and package.json `substrat.envSpec` — `substrat
-push` reads the JSON, not the TypeScript.
+tenant no matter what any of them saved. Declare a setting once, in
+`src/manifest.ts` (`SHOP_ENV`) — `src/provision.ts` re-exports it as `envSpec`,
+which is what `substrat push` uploads; package.json carries no copy.
 
 ## The rules (non-negotiable)
 
@@ -223,6 +223,21 @@ vertical done, boot the server and drive the real flow over HTTP as two personas
 should succeed and one who should be denied — and confirm the denial arrives as a denial
 (not a generic error).
 
+## When it breaks — symptom → fix
+
+Six failures that have each cost someone a day. What makes them expensive is that none of
+them names its own cause: the symptom points somewhere other than the fix, so an agent
+debugging from first principles walks away from the answer.
+
+| Symptom | Fix |
+|---|---|
+| `expected a Zod schema` at runtime, pointing nowhere useful | Two copies of Zod. Never add `zod` to `package.json` — import `z` from `@substrat-run/contracts`, so the schema you build and the one the host validates with are the same class. |
+| Killing the dev server kills unrelated ones too | `pkill -f 'tsx src/server.ts'` matches every Substrat project running on the machine, not just yours. Kill by port instead: `kill $(lsof -ti :<port>)`. |
+| Green locally, red in CI, with nothing in the diff that explains it | A warm build output hides it. Delete `dist`, reinstall from the lockfile (`--frozen-lockfile`), and re-run the gates before believing a local green. |
+| Green test suite, broken app | The scenario calls operations directly and never reaches `server.ts`, its routes, or the principal picker. Boot the server and drive the flow over HTTP as two personas — one who should succeed and one who should be denied. |
+| Permission denied after you widened a role | Roles are projected into a scope when that scope is provisioned, from `ROLES` in `src/provision.ts`. An existing scope keeps the projection it was born with — re-provision it (or re-seed onto a fresh data directory), then present the permission diff below. |
+| `pnpm install` dies compiling `better-sqlite3` | Take `better-sqlite3` out of `pnpm.onlyBuiltDependencies`. Since 13.x it ships prebuilt binaries and no install script, but it still ships a `binding.gyp` — so an allowlist entry makes pnpm run a `node-gyp rebuild` that nothing here needs. |
+
 ## Two human checkpoints — you may never self-approve
 
 Present these and stop:

package/template/src/manifest.ts

@@ -29,8 +29,8 @@ export const SHOP_PERM = {
  * value one tenant saved for one install — a spec `default` rides as a worker binding
  * shared by every install of the serving script.
  *
- * MIRRORED in package.json `substrat.envSpec` (what `substrat push` carries — it reads
- * JSON, not TS); keep the two in sync.
+ * The single declaration (#1206): `src/provision.ts` re-exports this as `envSpec`, which
+ * is what `substrat push` uploads — package.json carries no copy.
  */
 export const SHOP_ENV: EnvVarSpec[] = [
   {

package/template/src/provision.ts

@@ -8,6 +8,11 @@ import { invoicingModule, INVOICING_PERM as INV } from '@substrat-run/engine-inv
 import { bikeShopModule } from './module.js';
 import { SHOP_PERM } from './manifest.js';
 
+// The manifest's config surface rides the same import `substrat push` already makes for
+// `permissions` (#1206): this export is what the push uploads, so `src/manifest.ts` is the
+// single envSpec declaration and package.json carries no copy.
+export { SHOP_ENV as envSpec } 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