create-substrat 0.5.0 → 0.6.0

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.0",
   "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
+    }
+  ]
+}