create-stitchkit 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -6,6 +6,46 @@ is declared in the template root catalog.
 
 ## [Unreleased]
 
+## [0.3.3] — 2026-08-18
+
+### Changed
+
+- **Generated applications bind loopback by default.** Both processes listen on
+  `BIND_HOST` (default `127.0.0.1`) instead of a hardcoded `0.0.0.0` in the
+  backend server and both PM2 configs. Exposing the app to the network is now a
+  single conscious opt-in (`BIND_HOST=0.0.0.0` in `.env`) rather than the state
+  a forgotten edit leaves behind. Reported from a production deployment of a
+  generated app.
+- **The template targets Stitchkit `^0.52.0`** — new applications get
+  `implement.declare`, keyed registries and hook-derived scope maps out of the
+  box. Purely additive relative to 0.50.
+- **`bun run dev` reports honest URLs and fails fast on occupied ports.** The
+  final `Web:`/`API:` lines are rendered from the validated environment instead
+  of hardcoded ports, and before starting fresh PM2 processes the script probes
+  `API_PORT`/`WEB_PORT` and names the offending variable when a foreign process
+  holds one. Reloads of the app's own processes are unaffected.
+- **`start` without a build says what to do.** A missing `dist/index.js` now
+  fails with “run `bun run build` first” (also preflighted in `pm2:prod`)
+  instead of a bare module-resolution error.
+- **README and AGENTS.md pin the Prisma entry point.** Database commands go
+  through the root `bun run db:*` scripts; the `prisma` CLI invoked directly has
+  no datasource URL by design.
+
+## [0.3.2] — 2026-08-17
+
+### Changed
+
+- **The template targets Stitchkit 0.50.0 and binds process signals through the
+  framework.** Generated backends replace the hand-written shutdown coordinator
+  with `bindProcessSignals(server, …)`: MCP and Prisma close in `onComplete`, the
+  exit code is set there, and failures are reported by phase. The manual version
+  the template used to ship reported a failing `mcp.close()` as a failed
+  shutdown, did nothing on a third signal, and collapsed the grace period when a
+  supervisor delivered two signals at once.
+- **The repository example declares its domain error message once.**
+  `GITHUB_UNAVAILABLE` carries its text in the `defineErrors` definition instead
+  of repeating it at the throw site.
+
 ## [0.3.1] — 2026-08-15
 
 ### Changed

package/examples/repository/packages/backend/src/domain/errors.ts

@@ -4,6 +4,8 @@ import { z } from 'zod';
 export const { errors: domainErrors, codes: domainErrorCodes } = defineErrors({
   GITHUB_UNAVAILABLE: {
     status: 503,
+    // Declared once here instead of at every throw site.
+    message: 'GitHub repository data is temporarily unavailable',
     details: z.object({ cause: z.string() }),
   },
 });

package/examples/repository/packages/backend/src/domain/repository/github-cache.ts

@@ -197,7 +197,6 @@ export class GitHubRepositoryCache {
     } catch (error) {
       if (previous) return serialize(previous, 'stale');
       throw domainErrors.GITHUB_UNAVAILABLE({
-        message: 'GitHub repository data is temporarily unavailable',
         details: { cause: error instanceof Error ? error.message : 'Unknown upstream error' },
         hint: 'Retry after the upstream service recovers',
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stitchkit",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Create a production-shaped Stitchkit application",
   "license": "MIT",
   "author": "Max Listov <maxlistov@gmail.com>",

package/template/AGENTS.md

@@ -29,6 +29,9 @@ Shared never imports an application runtime package.
   endpoint URLs, query keys or error envelopes by hand.
 - Use Socket.IO through the shared realtime contract and Stitchkit wrappers.
   Authentication, authorization and room membership remain application policy.
+- Drive Prisma only through the root `bun run db:*` scripts; the `prisma` CLI
+  invoked directly has no datasource URL. Keep `BIND_HOST` at its loopback
+  default unless network exposure is an explicit requirement.
 - Extend runtime smoke with an explicit typed probe for operations whose handler
   behavior matters. Generic OpenAPI/MCP discovery checks are already derived.
 

package/template/README.md

@@ -75,4 +75,12 @@ PostgreSQL is external infrastructure in development and production. The
 application owns its schema and migrations; the environment owns the database
 process and supplies its connection through `DATABASE_URL`.
 
+Both processes bind `BIND_HOST` (default `127.0.0.1`, loopback only). Set
+`BIND_HOST=0.0.0.0` in `.env` to expose the app on every network interface —
+that is a conscious opt-in, typically behind a reverse proxy or firewall.
+
+Always drive Prisma through the root `bun run db:*` scripts — invoking the
+`prisma` CLI directly fails because the datasource URL is wired through the
+`@app/db` package environment, not a static config.
+
 `bun run dev` and `bun run pm2:dev` use the same direct PM2 development path.

package/template/_env.example

@@ -1,5 +1,7 @@
 NODE_ENV=development
 DATABASE_URL=postgresql://USER:PASSWORD@127.0.0.1:5432/stitchkit_starter
+# 0.0.0.0 exposes the app to every network interface — opt in consciously.
+BIND_HOST=127.0.0.1
 API_PORT=3211
 WEB_PORT=3210
 NEXT_PUBLIC_API_URL=http://127.0.0.1:3211

package/template/bun.lock

@@ -138,7 +138,7 @@
     },
   },
   "catalog": {
-    "stitchkit": "^0.49.2",
+    "stitchkit": "^0.52.0",
   },
   "packages": {
     "@ai-sdk/gateway": ["@ai-sdk/gateway@4.0.46", "", { "dependencies": { "@ai-sdk/provider": "4.0.7", "@ai-sdk/provider-utils": "5.0.25", "@vercel/oidc": "3.2.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-LIAO6kAG8fpXQb9L0iwPk1FIbXftvqnyC56v5NEAzeWTeL8fUsy/Hx86VPBTWEDFdwbVprjWifJOAqS6AOj3mA=="],
@@ -1117,7 +1117,7 @@
 
     "std-env": ["std-env@3.10.0", "", {}, "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg=="],
 
-    "stitchkit": ["stitchkit@0.49.2", "", { "dependencies": { "ky": "^2.0.2" }, "peerDependencies": { "@modelcontextprotocol/ext-apps": "^1.7.2", "@modelcontextprotocol/server": "^2.0.0", "@socket.io/bun-engine": "^0.1.1", "@socket.io/component-emitter": "^3.1.2", "@tanstack/react-query": ">=5", "@types/bun": "^1.3.14", "ai": "^7.0.0", "react": ">=18", "react-query-kit": "^3.3.3", "socket.io": "^4.8.3", "socket.io-client": "^4.8.3", "srvx": "^0.12.5", "zod": "^4.4.3" }, "optionalPeers": ["@modelcontextprotocol/ext-apps", "@modelcontextprotocol/server", "@socket.io/bun-engine", "@socket.io/component-emitter", "@tanstack/react-query", "@types/bun", "ai", "react", "react-query-kit", "socket.io", "socket.io-client", "srvx"] }, "sha512-QP0I//fs/khC+bTqYungjpZskAseQAB/Lm8UOx3mZDx+rmYtdsBhlAn0I0hBYE/du9jag5rE032s9HrZgT2VXg=="],
+    "stitchkit": ["stitchkit@0.52.0", "", { "dependencies": { "ky": "^2.0.2" }, "peerDependencies": { "@modelcontextprotocol/ext-apps": "^1.7.2", "@modelcontextprotocol/server": "^2.0.0", "@socket.io/bun-engine": "^0.1.1", "@socket.io/component-emitter": "^3.1.2", "@tanstack/react-query": ">=5", "@types/bun": "^1.3.14", "ai": "^7.0.0", "react": ">=18", "react-query-kit": "^3.3.3", "socket.io": "^4.8.3", "socket.io-client": "^4.8.3", "srvx": "^0.12.5", "zod": "^4.4.3" }, "optionalPeers": ["@modelcontextprotocol/ext-apps", "@modelcontextprotocol/server", "@socket.io/bun-engine", "@socket.io/component-emitter", "@tanstack/react-query", "@types/bun", "ai", "react", "react-query-kit", "socket.io", "socket.io-client", "srvx"] }, "sha512-sqtbZUbndsInagUr8/QoD1Hkc8nQMy1TiHu0Txo0XcRMSu4b73aGDdbyk8g4lnhEk0jOqxPXoGQZS/m7XMnnbQ=="],
 
     "stringify-entities": ["stringify-entities@4.0.4", "", { "dependencies": { "character-entities-html4": "^2.0.0", "character-entities-legacy": "^3.0.0" } }, "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg=="],
 

package/template/ecosystem.config.cjs

@@ -19,7 +19,13 @@ module.exports = {
       name: `${identity.slug}-frontend`,
       cwd: path.join(__dirname, 'packages/frontend'),
       script: 'node_modules/.bin/next',
-      args: ['start', '--port', process.env.WEB_PORT, '--hostname', '0.0.0.0'],
+      args: [
+        'start',
+        '--port',
+        process.env.WEB_PORT,
+        '--hostname',
+        process.env.BIND_HOST ?? '127.0.0.1',
+      ],
       interpreter: 'bun',
       autorestart: true,
       kill_timeout: 15000,

package/template/ecosystem.dev.config.cjs

@@ -4,7 +4,13 @@ const identity = require('./app.config.json');
 
 config({ path: path.join(__dirname, '.env'), quiet: true });
 
-const frontendArgs = ['dev', '--port', process.env.WEB_PORT, '--hostname', '0.0.0.0'];
+const frontendArgs = [
+  'dev',
+  '--port',
+  process.env.WEB_PORT,
+  '--hostname',
+  process.env.BIND_HOST ?? '127.0.0.1',
+];
 
 module.exports = {
   apps: [

package/template/package.json

@@ -7,7 +7,7 @@
     "packages/*"
   ],
   "catalog": {
-    "stitchkit": "^0.49.2"
+    "stitchkit": "^0.52.0"
   },
   "scripts": {
     "dev": "bun scripts/dev.ts",
@@ -31,7 +31,7 @@
     "lint": "biome check --error-on-warnings .",
     "lint:fix": "biome check --write .",
     "pm2:dev": "bun scripts/dev.ts",
-    "pm2:prod": "bun run db:deploy && pm2 startOrReload ecosystem.config.cjs --update-env"
+    "pm2:prod": "bun run db:deploy && bun packages/backend/scripts/ensure-built.ts && pm2 startOrReload ecosystem.config.cjs --update-env"
   },
   "dependencies": {
     "dotenv": "^17.4.2"

package/template/packages/backend/package.json

@@ -6,7 +6,7 @@
   "scripts": {
     "dev": "bun --watch src/index.ts",
     "build": "rm -rf dist && bun build src/index.ts src/cli.ts src/tools.ts --outdir dist --target bun --packages external",
-    "start": "bun dist/index.js",
+    "start": "bun scripts/ensure-built.ts && bun dist/index.js",
     "check": "bun x tsc --noEmit",
     "test": "bun test --pass-with-no-tests",
     "cli": "bun src/cli.ts",

package/template/packages/backend/scripts/ensure-built.ts

@@ -0,0 +1,7 @@
+// Preflight for `start` / `pm2:prod`: a missing build otherwise surfaces as a
+// bare `Module not found "dist/index.js"` with no hint at the obvious fix.
+const entry = new URL('../dist/index.js', import.meta.url);
+if (!(await Bun.file(entry).exists())) {
+  console.error('dist/index.js not found — run `bun run build` first.');
+  process.exit(1);
+}

package/template/packages/backend/src/index.ts

@@ -1,7 +1,12 @@
 import { env } from '@app/config';
 import { appIdentity } from '@app/config/identity';
 import { wrapInRequestContext } from 'stitchkit/observability';
-import { createServer, generateOpenApiDocument, openApiRoute } from 'stitchkit/server';
+import {
+  bindProcessSignals,
+  createServer,
+  generateOpenApiDocument,
+  openApiRoute,
+} from 'stitchkit/server';
 import { createMcpHandler, createMcpHttpRoute } from 'stitchkit/tools';
 import { prisma } from './lib/db';
 import { createSurface } from './surface';
@@ -22,7 +27,7 @@ async function main(): Promise<void> {
   const server = createServer({
     groups: [{ pathPrefix: '/api', services }],
     port: env.API_PORT,
-    hostname: '0.0.0.0',
+    hostname: env.BIND_HOST,
     cors: { origin: env.CORS_ORIGIN },
     hooks: { onError },
     logging: { format: env.LOG_FORMAT },
@@ -39,34 +44,23 @@ async function main(): Promise<void> {
     wrapFetch: (fetch) => wrapInRequestContext(fetch),
   });
 
-  const shutdownController = new AbortController();
-  let shutdownPromise: Promise<void> | undefined;
-
-  function shutdown(): Promise<void> {
-    if (shutdownPromise) {
-      shutdownController.abort();
-      return shutdownPromise;
-    }
-
-    shutdownPromise = (async () => {
-      await server.shutdown({
-        gracePeriodMs: 30_000,
-        signal: shutdownController.signal,
-      });
+  // The server owns HTTP and Socket.IO; MCP, Prisma and the exit code are the
+  // application's and close after the drain. A second signal forces this same
+  // shutdown, a third hands the signal back to its default disposition.
+  bindProcessSignals(server, {
+    shutdown: { gracePeriodMs: 30_000 },
+    onComplete: async (result) => {
       await mcp.close();
       await prisma.$disconnect();
-    })();
-    return shutdownPromise;
-  }
-
-  const onSignal = () =>
-    void shutdown().catch((error: unknown) => {
-      console.error('Shutdown failed', error);
-    });
+      process.exitCode = result.outcome === 'clean' ? 0 : 1;
+    },
+    onError: (phase, error) => {
+      console.error(`Shutdown failed during ${phase}`, error);
+      process.exitCode = 1;
+    },
+  });
 
-  process.on('SIGTERM', onSignal);
-  process.on('SIGINT', onSignal);
-  console.log(`API listening on http://127.0.0.1:${env.API_PORT}`);
+  console.log(`API listening on http://${env.BIND_HOST}:${env.API_PORT}`);
 }
 
 main().catch((error: unknown) => {

package/template/packages/backend/tsconfig.json

@@ -4,5 +4,5 @@
     "types": ["bun"],
     "paths": { "@/*": ["./src/*"] }
   },
-  "include": ["src"]
+  "include": ["src", "scripts"]
 }

package/template/packages/config/src/server.ts

@@ -10,6 +10,9 @@ export const env = createEnv({
   server: {
     NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
     DATABASE_URL: z.url(),
+    // Loopback by default — exposing the app to the network is an explicit
+    // opt-in (`BIND_HOST=0.0.0.0`), never something a forgotten edit causes.
+    BIND_HOST: z.string().min(1).default('127.0.0.1'),
     API_PORT: z.coerce.number().int().positive(),
     WEB_PORT: z.coerce.number().int().positive(),
     NEXT_PUBLIC_API_URL: z.url(),

package/template/scripts/dev.ts

@@ -1,4 +1,5 @@
 import { resolve } from 'node:path';
+import { z } from 'zod';
 import { appIdentity } from '../packages/config/src/identity';
 import { ensureLocalEnvironment } from './local-env';
 import { inheritToolingEnvironment } from './tooling-env';
@@ -26,6 +27,7 @@ export async function runDevelopment(environment?: Record<string, string>): Prom
       'DATABASE_URL still contains the starter placeholder. Create a PostgreSQL database, update DATABASE_URL in .env, then rerun `bun run dev`.',
     );
   }
+  await assertPortsAvailable(environmentForRun);
   await run(['bun', 'run', 'db:setup'], environmentForRun);
   await run(
     ['pm2', 'startOrReload', 'ecosystem.dev.config.cjs', '--update-env'],
@@ -33,6 +35,50 @@ export async function runDevelopment(environment?: Record<string, string>): Prom
   );
 }
 
+/**
+ * Fail fast with the offending variable when a port is held by a FOREIGN
+ * process. A rerun of `bun run dev` reloads this app's own PM2 processes while
+ * they still hold the ports, so the probe is skipped once they are registered.
+ */
+async function assertPortsAvailable(environment: Record<string, string>): Promise<void> {
+  const registered = await registeredPm2Names();
+  const managed = [`${appIdentity.slug}-backend-dev`, `${appIdentity.slug}-frontend-dev`];
+  if (managed.some((name) => registered.has(name))) return;
+  assertPortFree(Number(environment.API_PORT), 'API_PORT');
+  assertPortFree(Number(environment.WEB_PORT), 'WEB_PORT');
+}
+
+async function registeredPm2Names(): Promise<Set<string>> {
+  const child = Bun.spawn(['pm2', 'jlist'], { cwd: root, stdout: 'pipe', stderr: 'ignore' });
+  const output = await new Response(child.stdout).text();
+  await child.exited;
+  const parsed = z.array(z.object({ name: z.string() })).safeParse(safeJsonParse(output));
+  return new Set(parsed.success ? parsed.data.map((entry) => entry.name) : []);
+}
+
+function safeJsonParse(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+function assertPortFree(port: number, variable: string): void {
+  try {
+    const listener = Bun.listen({
+      hostname: '127.0.0.1',
+      port,
+      socket: { data: () => undefined },
+    });
+    listener.stop(true);
+  } catch {
+    throw new Error(
+      `Port ${port} (${variable}) is already in use by another process. Pick a free port in .env and update the URLs that embed it.`,
+    );
+  }
+}
+
 function assertToolAvailable(command: string, instruction: string): void {
   if (!Bun.which(command)) throw new Error(`${command} is required. ${instruction}`);
 }
@@ -43,6 +89,7 @@ export async function developmentEnvironment(
   const { env } = await import('../packages/config/src/server');
   return {
     DATABASE_URL: env.DATABASE_URL,
+    BIND_HOST: env.BIND_HOST,
     API_PORT: String(env.API_PORT),
     WEB_PORT: String(env.WEB_PORT),
     CORS_ORIGIN: env.CORS_ORIGIN,
@@ -56,7 +103,8 @@ export async function developmentEnvironment(
 if (import.meta.main) {
   await runDevelopment();
 
+  const environment = await developmentEnvironment();
   console.log(`${appIdentity.name} development processes are running`);
-  console.log('Web: http://localhost:3210/en');
-  console.log('API: http://localhost:3211');
+  console.log(`Web: ${environment.NEXT_PUBLIC_WEB_URL}/en`);
+  console.log(`API: ${environment.NEXT_PUBLIC_API_URL}`);
 }