create-stitchkit 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -6,6 +6,31 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stitchkit",
-  "version": "0.3.2",
+  "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.50.0",
+    "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.50.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-lMadqgQ9aryAhULyA0biVjx9bn86HOUhcUj809TyHy2MuUZSnL9qI4fiByQbVAqlxW6i1a1RLAeguEJeu6jwWg=="],
+    "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.50.0"
+    "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

@@ -27,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 },
@@ -60,7 +60,7 @@ async function main(): Promise<void> {
     },
   });
 
-  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}`);
 }