create-stitchkit 0.3.2 → 0.4.0

package/template/ecosystem.config.cjs

@@ -1,28 +1,57 @@
+// GENERATED FILE — do not edit.
+//
+// Rendered from `project.json` by `scripts/declaration.ts`; run
+// `bun run gen:declaration` after changing a role. Roles, commands and the
+// drain floor come from the declaration because they are true of the code;
+// restart policy and the kill timeout are this machine's, and the generator
+// refuses a timeout shorter than any role's full shutdown budget.
 const path = require('node:path');
 const { config } = require('dotenv');
-const identity = require('./app.config.json');
+const declaration = require('./project.json');
 
-config({ path: path.join(__dirname, '.env'), quiet: true, override: true });
+// NOT `override`: an environment a deployment injected into this process must
+// win over a file in the repository. The file fills gaps; it does not overrule
+// the place.
+config({ path: path.join(__dirname, '.env'), quiet: true });
 
 module.exports = {
   apps: [
     {
-      name: `${identity.slug}-backend`,
-      cwd: path.join(__dirname, 'packages/backend'),
-      script: 'dist/index.js',
-      interpreter: 'bun',
+      name: `${declaration.identity.slug}-api`,
+      // The role's OWN process, in its OWN directory — no launcher in between.
+      // Measured: a launcher makes the role see the stop signal twice (once from
+      // the supervisor, once forwarded), the second press forces the shutdown,
+      // and a declared drain of seconds collapses to milliseconds. A workspace
+      // filter is worse: the signal never arrives at all.
+      cwd: path.join(__dirname, "packages/backend"),
+      script: "bun",
+      // No argv invented here: the deployment injects `API_PORT` and the command
+      // reads it. Serialised rather than concatenated — an argument with a space
+      // or a quote has to survive this file intact.
+      args: ["dist/index.js"],
+      interpreter: 'none',
       autorestart: true,
-      kill_timeout: 15000,
+      // >= this role's full shutdown budget of 25000ms.
+      kill_timeout: 30000,
       env: { NODE_ENV: 'production' },
     },
     {
-      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'],
-      interpreter: 'bun',
+      name: `${declaration.identity.slug}-web`,
+      // The role's OWN process, in its OWN directory — no launcher in between.
+      // Measured: a launcher makes the role see the stop signal twice (once from
+      // the supervisor, once forwarded), the second press forces the shutdown,
+      // and a declared drain of seconds collapses to milliseconds. A workspace
+      // filter is worse: the signal never arrives at all.
+      cwd: path.join(__dirname, "packages/frontend"),
+      script: "bun",
+      // No argv invented here: the deployment injects `WEB_PORT` and the command
+      // reads it. Serialised rather than concatenated — an argument with a space
+      // or a quote has to survive this file intact.
+      args: ["scripts/serve.ts","production"],
+      interpreter: 'none',
       autorestart: true,
-      kill_timeout: 15000,
+      // >= this role's full shutdown budget of 15000ms.
+      kill_timeout: 30000,
       env: { NODE_ENV: 'production' },
     },
   ],

package/template/ecosystem.dev.config.cjs

@@ -1,31 +1,57 @@
+// GENERATED FILE — do not edit.
+//
+// Rendered from `project.json` by `scripts/declaration.ts`; run
+// `bun run gen:declaration` after changing a role. Roles, commands and the
+// drain floor come from the declaration because they are true of the code;
+// restart policy and the kill timeout are this machine's, and the generator
+// refuses a timeout shorter than any role's full shutdown budget.
 const path = require('node:path');
 const { config } = require('dotenv');
-const identity = require('./app.config.json');
+const declaration = require('./project.json');
 
+// NOT `override`: an environment a deployment injected into this process must
+// win over a file in the repository. The file fills gaps; it does not overrule
+// the place.
 config({ path: path.join(__dirname, '.env'), quiet: true });
 
-const frontendArgs = ['dev', '--port', process.env.WEB_PORT, '--hostname', '0.0.0.0'];
-
 module.exports = {
   apps: [
     {
-      name: `${identity.slug}-backend-dev`,
-      cwd: path.join(__dirname, 'packages/backend'),
-      script: 'src/index.ts',
-      interpreter: 'bun',
-      interpreter_args: '--watch',
+      name: `${declaration.identity.slug}-api-dev`,
+      // The role's OWN process, in its OWN directory — no launcher in between.
+      // Measured: a launcher makes the role see the stop signal twice (once from
+      // the supervisor, once forwarded), the second press forces the shutdown,
+      // and a declared drain of seconds collapses to milliseconds. A workspace
+      // filter is worse: the signal never arrives at all.
+      cwd: path.join(__dirname, "packages/backend"),
+      script: "bun",
+      // No argv invented here: the deployment injects `API_PORT` and the command
+      // reads it. Serialised rather than concatenated — an argument with a space
+      // or a quote has to survive this file intact.
+      args: ["--watch","src/index.ts"],
+      interpreter: 'none',
       autorestart: true,
-      kill_timeout: 10000,
+      // >= this role's full shutdown budget of 25000ms.
+      kill_timeout: 30000,
       env: { NODE_ENV: 'development' },
     },
     {
-      name: `${identity.slug}-frontend-dev`,
-      cwd: path.join(__dirname, 'packages/frontend'),
-      script: 'node_modules/.bin/next',
-      args: frontendArgs,
-      interpreter: 'bun',
+      name: `${declaration.identity.slug}-web-dev`,
+      // The role's OWN process, in its OWN directory — no launcher in between.
+      // Measured: a launcher makes the role see the stop signal twice (once from
+      // the supervisor, once forwarded), the second press forces the shutdown,
+      // and a declared drain of seconds collapses to milliseconds. A workspace
+      // filter is worse: the signal never arrives at all.
+      cwd: path.join(__dirname, "packages/frontend"),
+      script: "bun",
+      // No argv invented here: the deployment injects `WEB_PORT` and the command
+      // reads it. Serialised rather than concatenated — an argument with a space
+      // or a quote has to survive this file intact.
+      args: ["scripts/serve.ts","development"],
+      interpreter: 'none',
       autorestart: true,
-      kill_timeout: 10000,
+      // >= this role's full shutdown budget of 15000ms.
+      kill_timeout: 30000,
       env: { NODE_ENV: 'development' },
     },
   ],

package/template/package.json

@@ -7,14 +7,14 @@
     "packages/*"
   ],
   "catalog": {
-    "stitchkit": "^0.50.0"
+    "stitchkit": "^0.60.0"
   },
   "scripts": {
     "dev": "bun scripts/dev.ts",
     "check": "bun run db:generate && bun run check:authored && bun x tsc -p tsconfig.json --noEmit && bun run --filter '*' check",
     "check:authored": "bun scripts/check-authored.ts",
-    "test": "bun run --filter '*' test",
-    "build": "bun run db:generate && bun --filter @app/backend build && bun --filter @app/frontend build",
+    "test": "bun test scripts && bun run --filter '*' test",
+    "build": "bun scripts/build-inputs.ts && bun run db:generate && bun --filter @app/backend build && bun --filter @app/frontend build",
     "start:api": "bun --filter @app/backend start",
     "start:web": "bun --filter @app/frontend start",
     "env:ensure": "bun scripts/local-env.ts",
@@ -31,7 +31,8 @@
     "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 scripts/release.ts",
+    "gen:declaration": "bun scripts/declaration.ts"
   },
   "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/cli.ts

@@ -1,13 +1,17 @@
 #!/usr/bin/env bun
 
-import { appIdentity } from '@app/config/identity';
+import { appDeclaration } from '@app/config/declaration';
 import { createCli } from 'stitchkit/cli';
 import { createSurface } from './surface';
 
 const { services, socket } = await createSurface();
 
 try {
-  await createCli({ name: appIdentity.slug, version: appIdentity.version, services });
+  await createCli({
+    name: appDeclaration.identity.slug,
+    version: appDeclaration.identity.version,
+    services,
+  });
 } finally {
   await socket.close();
 }

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

@@ -1,5 +1,5 @@
 import { env } from '@app/config';
-import { appIdentity } from '@app/config/identity';
+import { apiRole, appDeclaration } from '@app/config/declaration';
 import { wrapInRequestContext } from 'stitchkit/observability';
 import {
   bindProcessSignals,
@@ -15,20 +15,26 @@ import { onError } from './transport/errors';
 async function main(): Promise<void> {
   const { services, socket } = await createSurface();
   const mcp = createMcpHandler({
-    serverInfo: { name: appIdentity.slug, version: appIdentity.version },
+    serverInfo: {
+      name: appDeclaration.identity.slug,
+      version: appDeclaration.identity.version,
+    },
     auth: () => ({ scope: 'public' }),
     services,
   });
   const openApi = generateOpenApiDocument({
-    info: { title: `${appIdentity.name} API`, version: appIdentity.version },
+    info: {
+      title: `${appDeclaration.identity.name} API`,
+      version: appDeclaration.identity.version,
+    },
     groups: [{ pathPrefix: '/api', services }],
   });
 
   const server = createServer({
     groups: [{ pathPrefix: '/api', services }],
     port: env.API_PORT,
-    hostname: '0.0.0.0',
-    cors: { origin: env.CORS_ORIGIN },
+    hostname: env.BIND_HOST,
+    cors: env.CORS_ORIGIN ? { origin: env.CORS_ORIGIN } : undefined,
     hooks: { onError },
     logging: { format: env.LOG_FORMAT },
     socket,
@@ -48,10 +54,20 @@ async function main(): Promise<void> {
   // 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 },
+    // The FLOOR comes from the declaration, which is where a supervisor reads
+    // it too — one number, not two that can disagree. It is a property of the
+    // code: whatever supervises this process must allow at least this much
+    // before sending SIGKILL, or the drain never finishes.
+    shutdown: { gracePeriodMs: apiRole.drainFloorMs },
     onComplete: async (result) => {
       await mcp.close();
       await prisma.$disconnect();
+      // Say how the drain ended. Without this an operator sees a process that
+      // vanished and an exit code, and cannot tell a clean drain from one the
+      // deadline or a second signal cut short.
+      console.log(
+        `Shutdown ${result.outcome}${result.reason ? ` (${result.reason})` : ''} in ${result.durationMs}ms — ${result.completedRequests} requests completed, ${result.abortedRequests} aborted, ${result.forcedWebSockets} sockets forced`,
+      );
       process.exitCode = result.outcome === 'clean' ? 0 : 1;
     },
     onError: (phase, error) => {
@@ -60,7 +76,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/src/surface.ts

@@ -3,6 +3,11 @@ import { createSocketIOServer } from 'stitchkit/server';
 import { createSystemService } from './transport/system-service';
 
 export async function createSurface() {
-  const socket = await createSocketIOServer({ cors: { origin: env.CORS_ORIGIN } });
+  // An EMPTY allow-list is same-origin: no origin is permitted to open a
+  // cross-origin socket, and no browser on this app's own origin needs one.
+  // `CORS_ORIGIN` is set only when the browser genuinely lives elsewhere.
+  // (Once the workspace targets a Stitchkit release where `cors` itself is
+  // optional, this becomes `undefined` and the empty array goes away.)
+  const socket = await createSocketIOServer({ cors: { origin: env.CORS_ORIGIN ?? [] } });
   return { socket, services: [createSystemService()] };
 }

package/template/packages/backend/src/transport/errors.ts

@@ -1,7 +1,9 @@
-import type { StitchErrorCode } from 'stitchkit';
 import { createErrorHook } from 'stitchkit/server';
 
-const codeMap: Record<StitchErrorCode, string> = {
+// Deliberately not annotated as an exhaustive `Record<StitchErrorCode, …>`:
+// this template compiles against both its pinned Stitchkit target and HEAD, and
+// the code union differs between them. Unlisted codes travel as themselves.
+const codeMap = {
   BAD_REQUEST: 'bad_request',
   VALIDATION_ERROR: 'validation_error',
   UNAUTHORIZED: 'unauthorized',

package/template/packages/backend/tsconfig.json

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

package/template/packages/config/package.json

@@ -5,7 +5,9 @@
   "type": "module",
   "exports": {
     ".": "./src/server.ts",
-    "./identity": "./src/identity.ts"
+    "./variables": "./src/variables.ts",
+    "./declaration": "./src/declaration.ts",
+    "./app-identity": "./src/app-identity.generated.ts"
   },
   "scripts": {
     "check": "bun x tsc --noEmit",

package/template/packages/config/src/app-identity.generated.ts

@@ -0,0 +1,20 @@
+// GENERATED FILE — do not edit.
+//
+// Rendered from `project.json` by `scripts/declaration.ts`.
+//
+// Identity ONLY, inlined rather than imported, because this is the part of the
+// declaration a browser may know. Importing the whole declaration from a client
+// component would put role commands, working directories, build artifact paths,
+// the migration lockfile and every environment variable name into the browser
+// bundle — the same mistake as publishing internal topology from a status
+// endpoint, made from the other side.
+
+export const appIdentity = {
+  "slug": "stitchkit-starter",
+  "name": "Stitchkit Starter",
+  "version": "0.1.0",
+  "description": {
+    "en": "Stitchkit Starter is a production application built with Stitchkit.",
+    "ru": "Stitchkit Starter — production-приложение на Stitchkit."
+  }
+};

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

@@ -0,0 +1,30 @@
+import source from '../../../project.json' with { type: 'json' };
+import { findProjectRole, parseProjectDeclaration } from './project-declaration.generated';
+
+/**
+ * What this repository says about itself — the one machine-readable statement
+ * that is true with no machine in existence.
+ *
+ * Ports, hosts, addresses, machine paths and supervision policy are NOT here by
+ * construction: the schema has nowhere to put them. A deployment supplies those
+ * under the variable names the declaration lists.
+ */
+export const appDeclaration = parseProjectDeclaration(source);
+
+/**
+ * This application's API role.
+ *
+ * Resolved once, here, so the role's own code can read what the declaration
+ * says about it — the drain floor above all — instead of restating it. A
+ * declaration without the role is a broken declaration, and saying so at
+ * startup beats a silent `undefined` deep inside a shutdown path.
+ */
+const API_ROLE_NAME = 'api';
+
+export const apiRole = (() => {
+  const role = findProjectRole(appDeclaration, API_ROLE_NAME);
+  if (!role) {
+    throw new Error(`project.json declares no "${API_ROLE_NAME}" role.`);
+  }
+  return role;
+})();