create-stitchkit 0.1.0 → 0.2.0

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

@@ -0,0 +1,91 @@
+import { RepositorySnapshotSchema } from '@app/shared';
+import { io } from 'socket.io-client';
+import { z } from 'zod';
+import { defineSurfaceProbe, runSurfaceConformance } from './surface-conformance';
+import { toolingEnv } from './tooling-env';
+
+const apiOrigin = toolingEnv.NEXT_PUBLIC_API_URL;
+
+async function json(path: string, init?: RequestInit): Promise<unknown> {
+  const response = await fetch(`${apiOrigin}${path}`, init);
+  if (!response.ok)
+    throw new Error(`${init?.method ?? 'GET'} ${path} returned ${response.status}`);
+  return response.json();
+}
+
+z.object({ status: z.literal('ok') }).parse(await json('/health'));
+
+await runSurfaceConformance({
+  apiOrigin,
+  probes: [
+    defineSurfaceProbe({
+      name: 'repository refresh lifecycle',
+      input: z.object({ path: z.literal('/api/repository/refresh') }),
+      fixture: { path: '/api/repository/refresh' },
+      output: RepositorySnapshotSchema,
+      run: async ({ path }) => {
+        const socket = io(apiOrigin, { transports: ['websocket'] });
+        try {
+          await new Promise<void>((resolve, reject) => {
+            const timeout = setTimeout(
+              () => reject(new Error('Socket.IO connection timed out')),
+              5_000,
+            );
+            const onConnect = () => {
+              clearTimeout(timeout);
+              socket.off('connect_error', onConnectError);
+              resolve();
+            };
+            const onConnectError = (error: Error) => {
+              clearTimeout(timeout);
+              socket.off('connect', onConnect);
+              reject(error);
+            };
+            socket.once('connect', onConnect);
+            socket.once('connect_error', onConnectError);
+          });
+          const refreshedEvent = new Promise<string>((resolve, reject) => {
+            const timeout = setTimeout(
+              () => reject(new Error('Socket.IO repository refresh event timed out')),
+              5_000,
+            );
+            socket.once('repository:refreshed', (snapshot) => {
+              clearTimeout(timeout);
+              resolve(snapshot.fullName);
+            });
+          });
+          const refreshed = RepositorySnapshotSchema.parse(
+            await json(path, { method: 'POST' }),
+          );
+          if ((await refreshedEvent) !== refreshed.fullName) {
+            throw new Error('Socket.IO repository identity differs');
+          }
+          const cached = RepositorySnapshotSchema.parse(await json('/api/repository/'));
+          if (cached.fullName !== refreshed.fullName) {
+            throw new Error('Repository cache read differs');
+          }
+          return refreshed;
+        } finally {
+          socket.close();
+        }
+      },
+    }),
+  ],
+});
+
+{
+  const corsResponse = await fetch(`${apiOrigin}/api/repository/`, {
+    headers: { Origin: 'http://localhost:58302' },
+  });
+  if (corsResponse.headers.get('access-control-allow-origin') !== '*') {
+    throw new Error('Public API does not allow a forwarded browser origin');
+  }
+  const openApi = z
+    .object({ paths: z.record(z.string(), z.unknown()) })
+    .parse(await json('/openapi.json'));
+  if (!Object.keys(openApi.paths).some((path) => path.startsWith('/api/repository'))) {
+    throw new Error('OpenAPI repository path is missing');
+  }
+}
+
+console.log('Runtime HTTP, OpenAPI, Socket.IO and MCP smoke passed');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stitchkit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Create a production-shaped Stitchkit application",
   "license": "MIT",
   "author": "Max Listov <maxlistov@gmail.com>",
@@ -16,6 +16,7 @@
   "files": [
     "dist",
     "template/**/*",
+    "examples/**/*",
     "!template/**/.env",
     "!template/**/node_modules/**",
     "!template/**/.next/**",
@@ -26,6 +27,11 @@
     "!template/**/src/generated/**",
     "!template/**/*.log",
     "!template/**/*.tsbuildinfo",
+    "!examples/**/node_modules/**",
+    "!examples/**/.next/**",
+    "!examples/**/dist/**",
+    "!examples/**/*.log",
+    "!examples/**/*.tsbuildinfo",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -39,6 +45,9 @@
     "build": "rm -rf dist && bun build src/cli.ts --outdir dist --target bun --packages external && chmod +x dist/cli.js",
     "prepublishOnly": "bun run check && bun run test && bun run build"
   },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
   "devDependencies": {
     "@types/bun": "^1.3.14",
     "typescript": "^7.0.2"

package/template/AGENTS.md

@@ -0,0 +1,50 @@
+# Application agent guide
+
+This repository is a generated Stitchkit application. It is not the Stitchkit
+framework source repository.
+
+## Architecture
+
+- `packages/shared` owns named Zod schemas, inferred DTO types, HTTP contracts
+  and realtime event definitions. It has no database, server or browser imports.
+- `packages/db` owns Prisma schema, migrations and the generated client.
+- `packages/backend` implements contracts, composes the registered surface and
+  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.
+
+Dependencies point inward: frontend/backend → shared; backend → db/config.
+Shared never imports an application runtime package.
+
+## Required patterns
+
+- Define each runtime DTO as a named Zod schema in `packages/shared/src/schemas`.
+- Reference schemas from a separate contract module; never inline `z.object()`
+  inside `defineContract`.
+- Implement one service method per contract operation and register the service
+  once in `packages/backend/src/surface.ts`.
+- Use Stitchkit's typed browser client and react-query-kit hooks; do not rebuild
+  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.
+- Extend runtime smoke with an explicit typed probe for operations whose handler
+  behavior matters. Generic OpenAPI/MCP discovery checks are already derived.
+
+Do not duplicate DTOs, copy Stitchkit internals, add raw routes for operations a
+contract can express, or create compatibility aliases. Fix framework gaps in
+Stitchkit rather than copying its implementation into this application.
+
+## Workflow
+
+Follow [`docs/ADDING_A_FEATURE.md`](docs/ADDING_A_FEATURE.md) for the complete
+vertical path. Before handing work off, run:
+
+```bash
+bun run check
+bun run test
+bun run build
+bun run runtime:smoke
+```
+

package/template/README.md

@@ -2,6 +2,10 @@
 
 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.
+
 ## Start
 
 Point `DATABASE_URL` in `.env` at an existing PostgreSQL database, then run:
@@ -19,11 +23,16 @@ checked-in migrations and launches:
 - OpenAPI: <http://localhost:3211/openapi.json>
 - MCP: <http://localhost:3211/mcp>
 
-The home page is a compact Stitchkit Starter reference surface. One configured
-GitHub repository exercises the PostgreSQL cache → contract → typed client →
+The home page is a compact, domain-free Stitchkit Starter reference surface.
+Add application features as vertical schema → contract → service → client slices.
+The exact workflow is in [`docs/ADDING_A_FEATURE.md`](docs/ADDING_A_FEATURE.md),
+and root [`AGENTS.md`](AGENTS.md) gives coding agents the application boundaries.
+
+When generated with `--example repository`, one configured GitHub repository
+exercises the PostgreSQL cache → contract → typed client →
 mutation invalidation → realtime path without adding a demo product domain.
 Configure it with `GITHUB_REPOSITORY`; `GITHUB_TOKEN` is optional.
-Repository visibility demonstrates the canonical Prisma enum → shared Zod schema
+Repository visibility then demonstrates the canonical Prisma enum → shared Zod schema
 → HTTP/UI path without duplicating its allowed values.
 
 The `/en/ui` catalogue is isolated under
@@ -47,6 +56,12 @@ bun run test
 bun run build
 ```
 
+## Physical-device HTTPS
+
+`bun run dev:lan` is an explicit trusted-LAN mode powered by mkcert. It leaves
+normal development and production unchanged. Setup and device trust steps are
+in [`docs/LAN_HTTPS.md`](docs/LAN_HTTPS.md).
+
 ## Production
 
 Provide a production `.env`, then:
@@ -65,5 +80,3 @@ application owns its schema and migrations; the environment owns the database
 process and supplies its connection through `DATABASE_URL`.
 
 `bun run dev` and `bun run pm2:dev` use the same direct PM2 development path.
-Rename the neutral `stitchkit-starter` package and process names when adopting
-the template for a product.

package/template/_env

@@ -6,6 +6,4 @@ 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
 LOG_FORMAT=pretty
-GITHUB_REPOSITORY=max-listov/stitchkit
-GITHUB_CACHE_TTL_SECONDS=900
-# GITHUB_TOKEN=github_pat_...
+CORS_ORIGIN=*

package/template/_env.example

@@ -6,7 +6,4 @@ 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
 LOG_FORMAT=pretty
-GITHUB_REPOSITORY=max-listov/stitchkit
-GITHUB_CACHE_TTL_SECONDS=900
-# Optional. Authenticated conditional requests have a higher GitHub rate limit.
-# GITHUB_TOKEN=github_pat_...
+CORS_ORIGIN=*

package/template/app.config.json

@@ -0,0 +1,9 @@
+{
+  "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."
+  }
+}