create-substrat 0.4.2 → 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',
@@ -162,6 +167,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.2",
+  "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
+    }
+  ]
+}

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();
+}