create-substrat 0.5.0 → 0.6.1

package/dev-servers.js

@@ -0,0 +1,29 @@
+/**
+ * The dev servers a scaffolded vertical runs — declared once, client-neutrally.
+ *
+ * `.claude/launch.json` is a Claude Desktop **adapter**: it lets the agent start
+ * the server, open it in the Browser pane, and verify its own changes. Under
+ * design/agent-surface.md §3 an adapter may route, describe and trigger but may
+ * never *hold* substance — so the topology lives here, in the `substrat` block of
+ * package.json that `substrat push` and the SessionStart hook already read, and
+ * the client file is emitted from it (`pnpm lint:launch`, guarded in CI).
+ *
+ * A port is deliberately NOT a field. `portEnv` + `portFrom` say *where* the port
+ * is bound; the number is read out of that file. Otherwise the declaration becomes
+ * a second copy of a number whose first copy is the one that actually runs, and
+ * with `autoPort: false` a stale copy is a hard boot failure — for an agent, mid
+ * session, which is the worst possible audience for it.
+ *
+ * @typedef {object} DevServer
+ * @property {string}   name      Entry name. Mirrors the `-n` label of the `dev` script.
+ * @property {string}   run       pnpm script to run. With `dir`, the script in that subdir.
+ * @property {string}  [dir]      Subdirectory of the project (a Vite app), if any.
+ * @property {string}   portEnv   The env var that moves this port (`PORT`, `WEB_PORT`, …).
+ * @property {string}   portFrom  Project-relative file binding it: `process.env.<portEnv> ?? N`.
+ * @property {Record<string,string>} [env] Env the `dev` script sets for this process.
+ */
+
+/** The template ships one process: the Hono API. There is no web app to scaffold yet. */
+export const DEV_SERVERS = [
+  { name: 'api', run: 'server', portEnv: 'PORT', portFrom: 'src/server.ts' },
+];

package/index.js

@@ -16,6 +16,8 @@ import { cpSync, existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { DEV_SERVERS } from './dev-servers.js';
+
 const HERE = dirname(fileURLToPath(import.meta.url));
 const TEMPLATE = join(HERE, 'template');
 
@@ -73,7 +75,9 @@ function packageJson(name) {
       // 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).
+      // entry; ScopeDO is the store it exports). Also the client-neutral home of
+      // the dev topology `.claude/launch.json` is emitted from — see
+      // dev-servers.js for why the port is read from the code and never declared.
       substrat: {
         permissions: 'src/provision.ts',
         runtimeNeeds: {
@@ -84,6 +88,7 @@ function packageJson(name) {
             { binding: 'SWEEPER', class: 'SweeperDO' },
           ],
         },
+        devServers: DEV_SERVERS,
       },
       scripts: {
         dev: 'tsx watch src/server.ts',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-substrat",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Scaffold a Substrat vertical — `npm create substrat <dir>`.",
   "license": "Apache-2.0",
   "repository": {
@@ -24,6 +24,7 @@
   },
   "files": [
     "index.js",
+    "dev-servers.js",
     "template"
   ],
   "engines": {

package/template/.claude/launch.json

@@ -0,0 +1,15 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "api",
+      "runtimeExecutable": "pnpm",
+      "runtimeArgs": [
+        "run",
+        "server"
+      ],
+      "port": 8873,
+      "autoPort": false
+    }
+  ]
+}

package/template/.substrat/playbook.md

@@ -190,10 +190,21 @@ plain language, so nothing there is a surprise:
    cross-tenant attacker gets nothing).
 9. **Open decisions** — each with a **recommended default**, so the user chooses rather
    than specifies:
-   - **Auth.** Local dev uses an `x-principal` header — a dev seam, not a login. Default to
-     it and note it must be replaced before anything real; offer to wire a real login (the
-     bike-shop reference shows the Better Auth pattern) now if they want it. Real auth gates
-     *exposing* the app, not *building* it.
+   - **Auth.** Local dev uses an `x-principal` header — a dev seam, not a login. Real auth
+     gates *exposing* the app, not *building* it — but if the app will be deployed for real
+     users, wire the OIDC seam from the start: the standard is a **separate OIDC issuer**
+     (an Auth Server app in the same team, or an external issuer — Supabase/Auth0/AuthHero/
+     Keycloak), never per-app credential storage. The vertical is a pure OIDC **relying
+     party**: depend on `@substrat-run/vertical-auth`, bind its `IdentityDO` (the
+     `sub → principal` directory, TOFU owner claim, invites) as a third DO store, read the
+     platform-delivered `substrat:auth` config per scope (`authWiring`), and build
+     `oidcRpAuthProvider` per request — see https://substrat.net/concepts/identity. The
+     dashboard's New-app **Identity** section does the automatic half (dynamic client
+     registration at the issuer + `/internal/configure` delivery) — but ONLY at app
+     creation, and only for verticals that implement this seam. An install created without
+     the identity choice stays `builtin`/unwired forever (switching issuers is deliberately
+     create-time only); a starter worker whose `authenticatedPrincipal` returns null answers
+     401 to everything deployed, however many auth servers exist in the team.
    - **Deploy or stay local.** Local-first is a legitimate endpoint; default to it.
 10. **Out of scope / deferred** — what you are deliberately not building, so the review is
     about a bounded thing.
@@ -428,7 +439,9 @@ only in seed.ts would run locally and silently not deploy. The deploy path is th
 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)
+- `substrat push` — push the vertical. By default the version is the registry's highest
+  semver, patch-bumped; `package.json`'s version is only a **seed for the first push of a
+  new slug**, and an explicit `--version` always wins. A **private** (tenant-owned)
   vertical is admitted automatically; a **listed/shared** one waits for staff admission.
 - `substrat promote <slug> --channel dev|staging|prod --version … [--ack-permissions]
   [--ack-migrations]` — the owner promotes every channel, prod included, for their own
@@ -436,6 +449,50 @@ authenticated CLI, and the author never holds a Cloudflare token:
 - `substrat hostnames bind <slug> --surface <s> [--domain <d>]` — mint a live hostname, or
   record a custom domain pending DNS validation (`substrat hostnames verify`).
 
+**A SPA ships as NATIVE assets — never inline it into the worker.** Declare it in
+`runtimeNeeds` and `substrat push` builds, hashes, and uploads the directory to the
+runtime's own asset store, served from the edge without invoking the worker:
+
+```jsonc
+"substrat": {
+  "runtimeNeeds": {
+    "entry": "src/worker.ts",
+    "build": "npm --prefix app install && npm --prefix app run build",
+    "assets": {
+      "directory": "app/dist",
+      "notFoundHandling": "single-page-application",   // deep client routes → index.html
+      "runWorkerFirst": ["/api/*", "/internal/*"]      // only these reach the worker
+    }
+  }
+}
+```
+
+`build` runs before assets are collected, so the directory may be pure build output. Never
+base64-inline a built `app/dist` into a generated worker module: it costs ~+33 % script
+size and a worker invocation per image.
+
+**Let changesets own the version, and pass it to push explicitly** — the default bump walks
+the registry forward on its own, so `package.json` and the registry drift apart within a
+few deploys. Set this up when the vertical first deploys:
+
+```sh
+pnpm add -D @changesets/cli && npx changeset init
+```
+
+Then in `.changeset/config.json` add `"privatePackages": { "version": true, "tag": false }`
+(the vertical is a private package, never npm-published), make sure `pnpm-workspace.yaml`
+lists `packages: ["."]` so changesets can see the root package, and add the scripts:
+
+```json
+"changeset": "changeset",
+"release": "pnpm test && pnpm typecheck && pnpm lint:boundaries && changeset version && substrat push --version $(node -p \"require('./package.json').version\") --promote prod"
+```
+
+Read the version with `node -p` at that point in the script, not `$npm_package_version` —
+the latter is captured before `changeset version` rewrites `package.json`, so it would push
+the version you just replaced. Changesets needs a git repo with a commit on the base branch
+(`git init -b main`) — a scaffold that isn't a repo yet must init before the first release.
+
 Updates deploy **in place** from one stable script — data carries forward, migrations run
 against prod data, backout is a time-boxed PITR rewind.