create-stitchkit 0.3.3 → 0.4.1

package/examples/repository/project.json

@@ -0,0 +1,189 @@
+{
+  "schemaVersion": 1,
+  "kind": "application",
+  "identity": {
+    "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."
+    }
+  },
+  "roles": [
+    {
+      "name": "api",
+      "workingDirectory": "packages/backend",
+      "commands": {
+        "development": {
+          "executable": "bun",
+          "args": [
+            "--watch",
+            "src/index.ts"
+          ]
+        },
+        "production": {
+          "executable": "bun",
+          "args": [
+            "dist/index.js"
+          ]
+        }
+      },
+      "listener": {
+        "portVariable": "API_PORT",
+        "bindVariable": "BIND_HOST",
+        "readinessPath": "/health"
+      },
+      "drainFloorMs": 15000
+    },
+    {
+      "name": "web",
+      "workingDirectory": "packages/frontend",
+      "commands": {
+        "development": {
+          "executable": "bun",
+          "args": [
+            "scripts/serve.ts",
+            "development"
+          ]
+        },
+        "production": {
+          "executable": "bun",
+          "args": [
+            "scripts/serve.ts",
+            "production"
+          ]
+        }
+      },
+      "listener": {
+        "portVariable": "WEB_PORT",
+        "bindVariable": "BIND_HOST",
+        "readinessPath": "/"
+      },
+      "drainFloorMs": 5000
+    }
+  ],
+  "build": {
+    "command": {
+      "executable": "bun",
+      "args": [
+        "run",
+        "build"
+      ]
+    },
+    "artifacts": [
+      "packages/backend/dist",
+      "packages/frontend/.next",
+      "packages/db/src/generated"
+    ]
+  },
+  "requires": [
+    {
+      "name": "postgres",
+      "phases": [
+        "release",
+        "start"
+      ]
+    }
+  ],
+  "release": {
+    "migrations": {
+      "engine": "prisma",
+      "root": "packages/db/migrations",
+      "lockfile": "packages/db/migrations/migration_lock.toml"
+    }
+  },
+  "env": {
+    "variables": [
+      {
+        "name": "API_PORT",
+        "shape": "integer",
+        "required": true
+      },
+      {
+        "name": "BIND_HOST",
+        "shape": "string",
+        "required": false
+      },
+      {
+        "name": "CORS_ORIGIN",
+        "shape": "url",
+        "required": false
+      },
+      {
+        "name": "DATABASE_URL",
+        "shape": "url",
+        "required": true
+      },
+      {
+        "name": "GITHUB_API_URL",
+        "shape": "url",
+        "required": false
+      },
+      {
+        "name": "GITHUB_CACHE_TTL_SECONDS",
+        "shape": "integer",
+        "required": false
+      },
+      {
+        "name": "GITHUB_REPOSITORY",
+        "shape": "string",
+        "required": true
+      },
+      {
+        "name": "GITHUB_TOKEN",
+        "shape": "string",
+        "required": false
+      },
+      {
+        "name": "INTERNAL_API_URL",
+        "shape": "url",
+        "required": true
+      },
+      {
+        "name": "LOG_FORMAT",
+        "shape": "enum",
+        "required": false,
+        "members": [
+          "pretty",
+          "json"
+        ]
+      },
+      {
+        "name": "NODE_ENV",
+        "shape": "enum",
+        "required": false,
+        "members": [
+          "development",
+          "test",
+          "production"
+        ]
+      },
+      {
+        "name": "PUBLIC_API_ORIGIN",
+        "shape": "url",
+        "required": false
+      },
+      {
+        "name": "PUBLIC_REALTIME_ORIGIN",
+        "shape": "url",
+        "required": false
+      },
+      {
+        "name": "PUBLIC_WEB_HOSTS",
+        "shape": "string",
+        "required": false
+      },
+      {
+        "name": "PUBLIC_WEB_ORIGIN",
+        "shape": "url",
+        "required": false
+      },
+      {
+        "name": "WEB_PORT",
+        "shape": "integer",
+        "required": true
+      }
+    ]
+  }
+}

package/examples/repository/scripts/runtime-smoke.ts

@@ -1,15 +1,24 @@
 import { RepositorySnapshotSchema, repositoryRealtimeContract } from '@app/shared';
 import { createRealtimeClient, defineRealtimeContract } from 'stitchkit';
 import { z } from 'zod';
+import { assertDeploymentIsAnswering } from './deployment-preflight';
 import { defineSurfaceProbe, runSurfaceConformance } from './surface-conformance';
 import { loadToolingEnv } from './tooling-env';
-import { assertPublicWebSurface } from './web-surface-smoke';
+import { assertArtifactIsPlacementFree, assertPublicWebSurface } from './web-surface-smoke';
 
 const toolingEnv = loadToolingEnv();
-const apiOrigin = toolingEnv.NEXT_PUBLIC_API_URL;
+const apiOrigin = toolingEnv.SMOKE_API_ORIGIN;
+
+await assertDeploymentIsAnswering({
+  'the API role': apiOrigin,
+  'the web role': toolingEnv.SMOKE_WEB_ORIGIN,
+});
 
 async function json(path: string, init?: RequestInit): Promise<unknown> {
-  const response = await fetch(`${apiOrigin}${path}`, init);
+  const response = await fetch(`${apiOrigin}${path}`, {
+    ...init,
+    signal: AbortSignal.timeout(30_000),
+  });
   if (!response.ok)
     throw new Error(`${init?.method ?? 'GET'} ${path} returned ${response.status}`);
   return response.json();
@@ -155,7 +164,7 @@ await runSurfaceConformance({
   });
   if (
     corsResponse.headers.get('access-control-allow-origin') !==
-    new URL(toolingEnv.NEXT_PUBLIC_WEB_URL).origin
+    new URL(toolingEnv.SMOKE_WEB_ORIGIN).origin
   ) {
     throw new Error('API CORS origin differs from the configured web origin');
   }
@@ -167,6 +176,29 @@ await runSurfaceConformance({
   }
 }
 
-await assertPublicWebSurface(toolingEnv.NEXT_PUBLIC_WEB_URL);
+{
+  // THE DEFAULT PATH, end to end: the browser's own origin answers `/api/…`
+  // because the web role forwards it. This is what makes the example's client a
+  // module constant, so it is checked rather than described.
+  const proxied = await fetch(`${toolingEnv.SMOKE_WEB_ORIGIN}/api/repository`);
+  if (!proxied.ok) {
+    throw new Error(
+      `The web role did not forward /api/repository (${proxied.status}) — the same-origin default is broken`,
+    );
+  }
+  const sameOrigin = RepositorySnapshotSchema.parse(await proxied.json());
+  const direct = RepositorySnapshotSchema.parse(await json('/api/repository/'));
+  if (sameOrigin.fullName !== direct.fullName) {
+    throw new Error("the forwarded answer differs from the API role's own");
+  }
+}
+
+await assertPublicWebSurface(toolingEnv.SMOKE_WEB_ORIGIN);
+await assertArtifactIsPlacementFree(toolingEnv.SMOKE_WEB_ORIGIN, {
+  origin: toolingEnv.PUBLIC_WEB_ORIGIN,
+  hosts: toolingEnv.PUBLIC_WEB_HOSTS,
+});
 
-console.log('Runtime HTTP, OpenAPI, Socket.IO, MCP and public web smoke passed');
+console.log(
+  'Runtime HTTP (same-origin and direct), OpenAPI, Socket.IO, MCP and public web smoke passed',
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stitchkit",
-  "version": "0.3.3",
+  "version": "0.4.1",
   "description": "Create a production-shaped Stitchkit application",
   "license": "MIT",
   "author": "Max Listov <maxlistov@gmail.com>",
@@ -18,6 +18,7 @@
     "template/**/*",
     "examples/**/*",
     "!template/**/.env",
+    "!template/**/.build-stamp.json",
     "!template/**/node_modules/**",
     "!template/**/.next/**",
     "!template/**/dist/**",
@@ -27,13 +28,22 @@
     "!template/**/src/generated/**",
     "!template/**/*.log",
     "!template/**/*.tsbuildinfo",
+    "!template/**/coverage/**",
+    "!examples/**/.env",
+    "!examples/**/.build-stamp.json",
     "!examples/**/node_modules/**",
     "!examples/**/.next/**",
     "!examples/**/dist/**",
+    "!examples/**/coverage/**",
+    "!examples/**/playwright-report/**",
+    "!examples/**/test-results/**",
+    "!examples/**/next-env.d.ts",
+    "!examples/**/src/generated/**",
     "!examples/**/*.log",
     "!examples/**/*.tsbuildinfo",
     "README.md",
     "CHANGELOG.md",
+    "UPGRADING.md",
     "LICENSE"
   ],
   "publishConfig": {
@@ -49,7 +59,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.14",
+    "@types/bun": "^1.4.0",
     "typescript": "^7.0.2"
   },
   "engines": {

package/template/AGENTS.md

@@ -12,8 +12,19 @@ framework source repository.
   owns application policy. Routes remain thin transport boundaries.
 - `packages/frontend` owns Next.js pages, typed clients, query/mutation hooks and
   cache reactions.
-- `packages/config/src/server.ts` is the only server environment boundary.
-  `app.config.json` is the only application identity boundary.
+- `packages/config/src/variables.ts` is the only declaration of an environment
+  variable. `server.ts` and `frontend/src/env.ts` are projections of it, and
+  the declaration's `env.variables` is derived from it — never restated.
+- `project.json` is the only place this project describes itself. It is written
+  by machine — the scaffolder stamps the identity, `bun run gen:declaration`
+  derives `env.variables` — so the formatter leaves it alone and
+  `scripts/declaration.test.ts` is what checks it.
+- Four things are generated from it and must not be hand-edited:
+  `ecosystem.config.cjs`, `ecosystem.dev.config.cjs`,
+  `packages/config/src/app-identity.generated.ts` and the `env.variables` block
+  of `project.json`. Run `bun run gen:declaration` after changing a role. It
+  holds nothing that differs between two deployments; those are named there by
+  variable and supplied by the place.
 
 Dependencies point inward: frontend/backend → shared; backend → db/config.
 Shared never imports an application runtime package.
@@ -48,6 +59,15 @@ vertical path. Before handing work off, run:
 bun run check
 bun run test
 bun run build
-bun run runtime:smoke
+bun run acceptance:local
 ```
 
+`acceptance:local` is part of the list because `runtime:smoke` and `e2e` check a
+running deployment: it creates one of its own — separate PM2 home, ephemeral
+ports, and its own database from `ACCEPTANCE_DATABASE_URL` — runs both against
+it, and destroys it. The separate database is not tidiness: the gates write, so
+one borrowing `DATABASE_URL` writes rows wherever `.env` points. **Never put
+`pm2:prod` in this list.** It applies the declared migrations to *your* database
+and reloads the running deployment; deploying is its own command, asked for on
+purpose, and no gate performs it.
+

package/template/README.md

@@ -2,9 +2,24 @@
 
 Production-shaped application generated by `create-stitchkit`.
 
-Application identity lives in [`app.config.json`](app.config.json). Change the
-slug, display name, version and localized description there; package names,
-process names, MCP/OpenAPI identity, UI copy and SEO derive from it.
+This project describes itself in [`project.json`](project.json) — its
+**declaration**: identity, the roles it runs, what it builds, what it needs
+before it starts, and the environment variables a deployment must supply.
+
+The declaration is true **with no machine in existence**. A field you cannot
+fill in without knowing where the code will run is a *binding*, not a
+declaration: ports, hosts, addresses, machine paths and supervision policy are
+named there by variable and never by value. The schema has no field that asks
+for one, so nothing in it ever requires a value of the place; where a value
+could still be written into a free-text field, a filter refuses the known
+shapes of a machine name. Change the slug, display name, version or description there and package
+names, process names, MCP/OpenAPI identity, UI copy and SEO follow.
+
+Four things are **generated** from it — `ecosystem.config.cjs`,
+`ecosystem.dev.config.cjs`, `packages/config/src/app-identity.generated.ts` and
+the `env.variables` block of the declaration itself. Run
+`bun run gen:declaration` after changing a role; the test suite refuses a stale
+copy.
 
 ## Start
 
@@ -35,6 +50,27 @@ Configure it with `GITHUB_REPOSITORY`; `GITHUB_TOKEN` is optional.
 Repository visibility then demonstrates the canonical Prisma enum → shared Zod schema
 → HTTP/UI path without duplicating its allowed values.
 
+**How the browser reaches the API, and what each shape costs.** By default it
+does not reach it at all: the browser calls its own origin (`/api/…`), the web
+role forwards to the API role (`packages/frontend/src/app/api/[...path]/route.ts`),
+and the client is a plain module constant — no address to wait for, no lazy
+accessor, nothing to order relative to `<Providers>`. A single-origin deployment
+supplies only `INTERNAL_API_URL`.
+
+Two things can pull a deployment out of that, and they are separate questions,
+so they have separate variables. **`PUBLIC_REALTIME_ORIGIN`** is the socket: a
+WebSocket upgrade does not survive the route handler that forwards `/api`, so
+two roles on two ports with nothing in front of them must name the socket's
+origin even though their HTTP is already same-origin. Behind one routing layer
+that forwards `/socket.io`, leave it unset. **`PUBLIC_API_ORIGIN`** is HTTP, for
+a frontend that genuinely dials the API role itself — and setting it changes
+nothing on its own: switching is one import in
+`packages/frontend/src/lib/api/queries.ts`, documented in
+`packages/frontend/src/lib/api/cross-origin.ts`. That variant costs a
+server-delivered address, a client built on first use (hence the parentheses),
+an ordering requirement relative to `<Providers>`, and `CORS_ORIGIN` on the API
+role.
+
 The `/en/ui` catalogue is isolated under
 `packages/frontend/src/app/[locale]/ui` and can be removed as one directory;
 reusable primitives remain in `components/ui`. It renders the complete
@@ -54,22 +90,61 @@ Unsupported browsers and users requesting reduced motion switch immediately.
 bun run check
 bun run test
 bun run build
-bun run runtime:smoke
-bun run e2e
+bun run acceptance:local
 ```
 
+Top to bottom, in one terminal, and none of it touches a deployment. They
+assume your development database is already set up — see [Start](#start).
+
+`acceptance:local` is the last one because `runtime:smoke` and `e2e` check a
+**running** deployment rather than a source tree — so it creates one and
+destroys it: its own PM2 home, ephemeral ports, its own public-host allowlist,
+and a stop that names the roles the declaration declares. It reloads nothing
+you are running.
+
+It also brings its own database, `ACCEPTANCE_DATABASE_URL`, and applies this
+project's migrations to that — not to yours. The gates WRITE (the repository
+example's smoke posts a refresh, and that upserts), so borrowing `DATABASE_URL`
+would make a gate a writer in whatever database your `.env` names. It refuses to
+start when the variable is unset or names the same database, and says what to
+add. It needs `pm2` (see [Requirements](#requirements)).
+
+Deploying is a separate, deliberate command — `bun run pm2:prod` under
+[Production](#production) — and it is not a gate.
+
+To run the two runtime gates against a deployment that already exists somewhere,
+point `SMOKE_API_ORIGIN` / `SMOKE_WEB_ORIGIN` at it and call `bun run
+runtime:smoke` / `bun run e2e` directly. `runtime:smoke` asks the web role to
+answer as two of the addresses `PUBLIC_WEB_HOSTS` claims, to prove one artifact
+serves many; a deployment claiming fewer than two addresses besides the one
+being dialled is told exactly what to add rather than failing on a refused host.
+
+## Requirements
+
+- **Bun** and **Node ≥ 22**.
+- **PostgreSQL** — external infrastructure, in development and production
+  alike. This project owns its schema and migrations, never the database
+  process.
+- **PM2** on `PATH` (`bun add --global pm2`) for `bun run dev`,
+  `bun run acceptance:local` and `bun run pm2:prod`.
+- **Playwright browsers** (`bunx playwright install`) for `bun run e2e`.
+
 ## Production
 
 Provide a production `.env`, then:
 
 ```bash
-bun run db:deploy
 bun run build
 bun run pm2:prod
 ```
 
-The Next.js frontend and Stitchkit API are separate processes and can also be
-deployed independently.
+`pm2:prod` is the release: it checks every artifact `build.artifacts` declares,
+applies the migrations `release.migrations` declares, and only then starts the
+roles from the generated supervision file. There is no separate `db:deploy`
+step to remember — the declaration already says the migrations exist, and one
+place saying it is the point.
+
+The roles are separate processes and can also be deployed independently.
 
 PostgreSQL is external infrastructure in development and production. The
 application owns its schema and migrations; the environment owns the database

package/template/_env.example

@@ -1,11 +1,23 @@
 NODE_ENV=development
 DATABASE_URL=postgresql://USER:PASSWORD@127.0.0.1:5432/stitchkit_starter
+# The throwaway database `bun run acceptance:local` creates and writes to. The
+# runtime gates WRITE, so they get one of their own: the harness refuses to
+# start if this is unset or names the database above.
+ACCEPTANCE_DATABASE_URL=postgresql://USER:PASSWORD@127.0.0.1:5432/stitchkit_starter_acceptance
 # 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
-INTERNAL_API_URL=http://127.0.0.1:3211
-NEXT_PUBLIC_WEB_URL=http://127.0.0.1:3210
+SMOKE_API_ORIGIN=http://127.0.0.1:3211
+SMOKE_WEB_ORIGIN=http://127.0.0.1:3210
+# Hosts this deployment answers for, comma-separated. One built artifact can
+# serve several addresses; a forwarded host outside this list is refused rather
+# than believed. Leave unset and set PUBLIC_WEB_ORIGIN instead for a single one.
+#
+# `bun run acceptance:local` supplies its own list to the deployment it creates,
+# so the addresses the portability check needs are not policy this project
+# carries. List here only the hosts this deployment really answers for.
+PUBLIC_WEB_HOSTS=127.0.0.1:3210
 LOG_FORMAT=pretty
-CORS_ORIGIN=http://127.0.0.1:3210
+# CORS_ORIGIN is only needed for a genuinely cross-origin browser.
+# CORS_ORIGIN=http://127.0.0.1:3210

package/template/_gitignore

@@ -3,6 +3,7 @@ dist/
 .next/
 next-env.d.ts
 .env
+.build-stamp.json
 coverage/
 *.log
 packages/db/src/generated/

package/template/biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.5.7/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.5.10/schema.json",
   "files": {
     "includes": [
       "**",
@@ -9,7 +9,11 @@
       "!!playwright-report",
       "!!test-results",
       "!!packages/frontend/next-env.d.ts",
-      "!!packages/frontend/public"
+      "!!packages/frontend/public",
+      "!!project.json",
+      "!!ecosystem.config.cjs",
+      "!!ecosystem.dev.config.cjs",
+      "!!packages/config/src/app-identity.generated.ts"
     ]
   },
   "formatter": {