create-stitchkit 0.6.3 → 0.6.5

package/CHANGELOG.md

@@ -12,6 +12,53 @@ step is overwritten by the next release.
 
 ## [Unreleased]
 
+## [0.6.5] — 2026-09-24
+
+### Added
+
+- `--template telegram-bot` — a long-polling Telegram bot assembled from
+  Stitchkit primitives: `grammyBotResources` (command menu, then polling with
+  updates admitted by batch), the JSON journal, an SQLite database resource,
+  an optional operator channel and local Bot API files, an entry point with
+  signals and the one policy for a poller that ended on its own (shut down,
+  exit 1), a `runtime-bindings.ts` where a deployment platform's state
+  publisher attaches, and a lifecycle test against a stand-in for Telegram.
+  Generated with `bun create stitchkit my-bot --template telegram-bot`.
+
+### Changed
+
+- Generated projects track Stitchkit `^0.96.0`, the release that ships the
+  bot primitives the new template is built from.
+
+## [0.6.4] — 2026-09-23
+
+### Fixed
+
+- **The board reaches the API on two local ports.** The base template's board
+  posts to its own origin (`/api/…`), and the README said the web role forwards
+  that — but the forwarding route lived only in the repository example, so a
+  blank scaffold answered 404. The route
+  (`packages/frontend/src/app/api/[...path]/route.ts`) is now in the base
+  template, and says in words when `INTERNAL_API_URL` is unset.
+- **The browser build carries the socket client.** The board passes
+  `peers: { client: () => import('socket.io-client') }` to
+  `createRealtimeClient`; without the literal loader the bundle had no
+  `socket.io-client` and the page failed with "needs the socket.io-client peer".
+- **The socket dials the API role in development.** `.env.example` now sets
+  `INTERNAL_API_URL`, `PUBLIC_REALTIME_ORIGIN` and `CORS_ORIGIN` for the two
+  local ports, and the repository example passes its realtime origin to the
+  board. A two-tab browser test proves a note posted in one tab reaches the
+  other in both variants.
+
+### Changed
+
+- **A scaffold starts on stitchkit 0.95.3**, whose watch client no longer drops
+  the values of a restarted API. The template's range moves from `^0.94.0` to
+  `^0.95.3`, over a lockfile resolving 0.95.3.
+
+  A project generated from 0.6.3 adds the route file above, the `peers` line in
+  `features/board/board-live.ts` and the three variables to its `.env`.
+
 ## [0.6.3] — 2026-09-23
 
 ### Changed

package/README.md

@@ -32,6 +32,22 @@ and recovery state. The bounded startup picker reads current tool-capable models
 windows from OpenRouter instead of duplicating provider metadata in environment variables. The
 workspace path is a containment boundary, not an OS sandbox.
 
+To start from a long-polling Telegram bot:
+
+```bash
+bun create stitchkit my-bot --template telegram-bot
+cd my-bot
+cp .env.example .env
+# Set BOT_TOKEN.
+bun run dev
+```
+
+The bot is assembled from published primitives only: the bot's resources with
+updates admitted by batch, a JSON journal, an SQLite database resource, an
+optional operator channel and local Bot API files, and one entry point that
+turns signals — and a poller that ended on its own — into a bounded shutdown.
+Its product is `src/handlers.ts`.
+
 It uses one conventional `packages/*` namespace: `backend`, `frontend`,
 `config`, `db` and `shared`. The destination name becomes the generated slug;
 `--display-name` sets the human title. Both are recorded once in

package/dist/cli.js

@@ -206,7 +206,7 @@ function withIdentity(declaration2, identity) {
 var HELP = `Create a production-shaped Stitchkit application.
 
 Usage:
-  bun create stitchkit <directory> [--template application|agent] [--display-name "Product Name"] [--example repository] [--no-install]
+  bun create stitchkit <directory> [--template application|agent|telegram-bot] [--display-name "Product Name"] [--example repository] [--no-install]
 
 Options:
   --no-install  Generate files without installing dependencies
@@ -238,10 +238,10 @@ function parseOptions(args) {
   if (templateFlagIndex !== -1 && template === undefined) {
     throw new Error("--template requires a value");
   }
-  if (template !== "application" && template !== "agent") {
+  if (template !== "application" && template !== "agent" && template !== "telegram-bot") {
     throw new Error(`Unknown template: ${template}`);
   }
-  if (template === "agent" && example !== undefined) {
+  if (template !== "application" && example !== undefined) {
     throw new Error("--example is only supported by the application template");
   }
   const displayNameFlagIndex = args.indexOf("--display-name");
@@ -479,12 +479,12 @@ async function run(args) {
     }
     const destination = resolve2(options.destination);
     const applicationTemplateDirectory = resolve2(import.meta.dir, "../template");
-    const templateDirectory = options.template === "agent" ? resolve2(import.meta.dir, "../templates/agent") : applicationTemplateDirectory;
+    const templateDirectory = options.template === "application" ? applicationTemplateDirectory : resolve2(import.meta.dir, `../templates/${options.template}`);
     const overlayDirectory = options.example ? resolve2(import.meta.dir, `../examples/${options.example}`) : undefined;
     await scaffoldProject(templateDirectory, destination, {
       ...overlayDirectory && { overlayDirectory },
       ...options.displayName && { displayName: options.displayName },
-      ...options.template === "agent" && {
+      ...options.template !== "application" && {
         identityModule: false,
         lockfile: false,
         stitchkitCatalogTarget: await readStitchkitCatalogTarget(applicationTemplateDirectory)
@@ -501,7 +501,7 @@ async function run(args) {
       if (exitCode !== 0)
         throw new Error(`bun install failed with exit code ${exitCode}`);
     }
-    const mode = options.template === "agent" ? " from the agent template" : options.example ? ` with the ${options.example} example` : "";
+    const mode = options.template !== "application" ? ` from the ${options.template} template` : options.example ? ` with the ${options.example} example` : "";
     process.stdout.write(`
 Created ${options.displayName ?? basename3(destination)}${mode}
 

package/examples/repository/_env.example.append

@@ -1,17 +1,3 @@
-# The web role reaches the API role internally, and forwards the browser's
-# same-origin `/api/…` calls to it. This one is required.
-INTERNAL_API_URL=http://127.0.0.1:3211
-
-# The realtime socket, and ONLY it. A WebSocket upgrade does not survive the
-# route handler that forwards `/api`, so two roles on two loopback ports must
-# name the socket's origin even though their HTTP is already same-origin.
-# Behind one routing layer that forwards `/socket.io`, leave this unset.
-PUBLIC_REALTIME_ORIGIN=http://127.0.0.1:3211
-
-# The browser origin the API role admits — for HTTP and for the realtime
-# handshake alike. Needed here because the socket above is cross-origin.
-CORS_ORIGIN=http://127.0.0.1:3210
-
 # THE CROSS-ORIGIN HTTP VARIANT — unset, and unnecessary for this example.
 # Set it only for a frontend that dials the API role itself instead of calling
 # its own `/api`: separate hostnames with nothing in front of them. Setting it

package/examples/repository/packages/frontend/src/app/[locale]/page.tsx

@@ -3,6 +3,7 @@ import { dehydrate, HydrationBoundary } from '@tanstack/react-query';
 import type { Metadata } from 'next';
 import { getTranslations } from 'next-intl/server';
 import { LocaleSchema } from '@/i18n/locales';
+import { publicRealtimeOrigin } from '@/lib/api/place';
 import { useRepository } from '@/lib/api/queries';
 import { createServerRepositoryApi } from '@/lib/api/server-client';
 import { getQueryClient } from '@/lib/query-client';
@@ -39,6 +40,7 @@ export default async function Page({ params }: { params: Promise<{ locale: strin
         heroTitle={t('heroTitle')}
         catalogueLabel={t('ui')}
         locale={appLocale}
+        realtimeOrigin={publicRealtimeOrigin()}
       />
     </HydrationBoundary>
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stitchkit",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Create a production-shaped Stitchkit application",
   "license": "MIT",
   "author": "Max Listov <maxlistov@gmail.com>",
@@ -45,6 +45,7 @@
     "!templates/**/*.tsbuildinfo",
     "!templates/**/coverage/**",
     "!templates/agent/bun.lock",
+    "!templates/telegram-bot/bun.lock",
     "!examples/**/.env",
     "!examples/**/.build-stamp.json",
     "!examples/**/node_modules/**",
@@ -68,7 +69,7 @@
   },
   "scripts": {
     "check": "bun x tsc --noEmit",
-    "test": "bun test tests",
+    "test": "bun test ./tests",
     "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"
   },
@@ -83,7 +84,7 @@
     "@types/react": "^19.3.0",
     "ai": "^7.0.111",
     "react": "^19.3.0",
-    "stitchkit": "0.93.0",
+    "stitchkit": "0.96.0",
     "typescript": "^7.0.2"
   },
   "engines": {

package/template/README.md

@@ -72,10 +72,12 @@ 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
+origin even though their HTTP is already same-origin — `.env.example` sets it,
+with `CORS_ORIGIN` admitting the web origin, for the two local ports. Behind one
+routing layer that forwards `/socket.io`, leave both unset.
+**`PUBLIC_API_ORIGIN`** is HTTP, for a frontend that genuinely dials the API
+role itself — and setting it changes nothing on its own: with
+`--example repository`, 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),

package/template/_env.example

@@ -22,5 +22,17 @@ SMOKE_WEB_ORIGIN=http://127.0.0.1:3210
 # carries. List here only the hosts this deployment really answers for.
 PUBLIC_WEB_HOSTS=127.0.0.1:3210
 LOG_FORMAT=pretty
-# CORS_ORIGIN is only needed for a genuinely cross-origin browser.
-# CORS_ORIGIN=http://127.0.0.1:3210
+
+# The web role reaches the API role internally, and forwards the browser's
+# same-origin `/api/…` calls to it (packages/frontend/src/app/api/[...path]).
+INTERNAL_API_URL=http://127.0.0.1:3211
+
+# The realtime socket, and ONLY it. A WebSocket upgrade does not survive the
+# route handler that forwards `/api`, so two roles on two loopback ports must
+# name the socket's origin even though their HTTP is already same-origin.
+# Behind one routing layer that forwards `/socket.io`, leave this unset.
+PUBLIC_REALTIME_ORIGIN=http://127.0.0.1:3211
+
+# The browser origin the API role admits — for HTTP and for the realtime
+# handshake alike. Needed here because the socket above is cross-origin.
+CORS_ORIGIN=http://127.0.0.1:3210

package/template/bun.lock

@@ -145,7 +145,7 @@
     "zod": "4.6.5",
   },
   "catalog": {
-    "stitchkit": "^0.94.0",
+    "stitchkit": "^0.96.0",
   },
   "packages": {
     "@ai-sdk/gateway": ["@ai-sdk/gateway@4.0.89", "", { "dependencies": { "@ai-sdk/provider": "4.0.17", "@ai-sdk/provider-utils": "5.0.45", "@vercel/oidc": "3.2.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-n0Q88UUASYQBGK3Ogs9pCe8h3ZXeTHFSuGOLBJAyH73MVGNKUv9w8EJX2f340WUF3eDWWOV305gO7YBpSCPblA=="],
@@ -1128,7 +1128,7 @@
 
     "std-env": ["std-env@3.10.0", "", {}, "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg=="],
 
-    "stitchkit": ["stitchkit@0.94.0", "", { "dependencies": { "ky": "^2.1.0" }, "peerDependencies": { "@modelcontextprotocol/ext-apps": "^1.7.2 || ^2.0.0", "@modelcontextprotocol/server": "^2.0.0", "@openrouter/ai-sdk-provider": "^3.1.0", "@opentelemetry/api": "^1.9.0", "@socket.io/bun-engine": "^0.1.2", "@socket.io/component-emitter": "^3.1.2", "@tanstack/react-query": ">=5", "@types/bun": "^1.4.2", "ai": "^7.0.107", "google-auth-library": "^11.1.0", "grammy": "^1.46.0", "maxmind": "^5.0.7", "react": ">=18", "react-query-kit": "^3.3.3", "socket.io": "^4.8.3", "socket.io-client": "^4.8.3", "srvx": "^0.12.5 || ^1.0.5", "zod": "^4.6.5" }, "optionalPeers": ["@modelcontextprotocol/ext-apps", "@modelcontextprotocol/server", "@openrouter/ai-sdk-provider", "@opentelemetry/api", "@socket.io/bun-engine", "@socket.io/component-emitter", "@tanstack/react-query", "@types/bun", "ai", "google-auth-library", "grammy", "maxmind", "react", "react-query-kit", "socket.io", "socket.io-client", "srvx"], "bin": { "stitchkit": "dist/entrypoints/bin/upgrade-cli.js" } }, "sha512-fZ7b/YwiOs8Hia5cNJgDxOzRBAb2nNMaEq2Zh7GWeIFdhKVz9Ywn2B83G4ZvUjqgNnPooclMdDXo6NBSOL/wBA=="],
+    "stitchkit": ["stitchkit@0.96.0", "", { "dependencies": { "ky": "^2.1.0" }, "peerDependencies": { "@modelcontextprotocol/ext-apps": "^1.7.2 || ^2.0.0", "@modelcontextprotocol/server": "^2.0.0", "@openrouter/ai-sdk-provider": "^3.1.0", "@opentelemetry/api": "^1.9.0", "@socket.io/bun-engine": "^0.1.2", "@socket.io/component-emitter": "^3.1.2", "@tanstack/react-query": ">=5", "@types/bun": "^1.4.2", "ai": "^7.0.107", "google-auth-library": "^11.1.0", "grammy": "^1.46.0", "maxmind": "^5.0.7", "react": ">=18", "react-query-kit": "^3.3.3", "socket.io": "^4.8.3", "socket.io-client": "^4.8.3", "srvx": "^0.12.5 || ^1.0.5", "zod": "^4.6.5" }, "optionalPeers": ["@modelcontextprotocol/ext-apps", "@modelcontextprotocol/server", "@openrouter/ai-sdk-provider", "@opentelemetry/api", "@socket.io/bun-engine", "@socket.io/component-emitter", "@tanstack/react-query", "@types/bun", "ai", "google-auth-library", "grammy", "maxmind", "react", "react-query-kit", "socket.io", "socket.io-client", "srvx"], "bin": { "stitchkit": "dist/entrypoints/bin/upgrade-cli.js" } }, "sha512-5cgzNatZtqE0HCXozqGXdcAeudG+QLxKXKZSHFasYu7O6JvU0rViDVO76hWFSwOiczaSoqsqwk/GM01ArMMUmw=="],
 
     "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/e2e/starter.spec.ts

@@ -35,6 +35,24 @@ test('calls the live backend through the typed contract client', async () => {
   }).toPass({ timeout: 5_000 });
 });
 
+test('a note posted in one tab reaches another through the web origin and the socket', async ({
+  browser,
+}) => {
+  // The browser's own origin carries HTTP (`/api` is forwarded by the web
+  // role) and the socket dials the API role; a post in one tab must reach a
+  // second tab that never asked for it. Both halves failed silently before:
+  // `/api` was a 404 on the web port, and the browser build had no socket.
+  const writer = await browser.newPage();
+  const reader = await browser.newPage();
+  await Promise.all([writer.goto('/en'), reader.goto('/en')]);
+  const note = `note ${Date.now()}`;
+  await writer.getByRole('textbox', { name: 'Note' }).fill(note);
+  await writer.getByRole('button', { name: 'Post' }).click();
+  await expect(writer.getByText(note)).toBeVisible();
+  await expect(reader.getByText(note)).toBeVisible({ timeout: 10_000 });
+  await Promise.all([writer.close(), reader.close()]);
+});
+
 test('publishes complete page metadata', async ({ page }) => {
   await page.goto('/en/ui/themes');
   await expect(page).toHaveTitle(`Theme system · ${appDeclaration.identity.name}`);

package/template/package.json

@@ -7,7 +7,7 @@
     "packages/*"
   ],
   "catalog": {
-    "stitchkit": "^0.94.0"
+    "stitchkit": "^0.96.0"
   },
   "overrides": {
     "@playwright/test": "1.63.0",

package/{examples/repository → template}/packages/frontend/src/app/api/[...path]/route.ts

@@ -1,10 +1,10 @@
-import { internalApiUrl } from '@/lib/api/place';
+import { env } from '@/env';
 
 /**
  * The default shape: the browser talks to its OWN origin, and the web role
- * forwards to the API role.
+ * forwards `/api/…` to the API role.
  *
- * This is what makes the example's client a plain module constant. A browser
+ * This is what makes the board's client a plain module constant. A browser
  * that dials the API role directly needs that role's public address, which is a
  * property of the place — so the address has to arrive from the server at
  * runtime, the client cannot exist until it does, and every call site pays for
@@ -13,9 +13,9 @@ import { internalApiUrl } from '@/lib/api/place';
  *
  * What it costs: one extra hop through the web role, and no WebSocket — a
  * route handler cannot proxy an upgrade. The realtime socket is therefore the
- * one place this example still needs the API role's address, or a routing layer
- * in front of both roles that serves them on one origin (see
- * `lib/api/cross-origin.ts`).
+ * one place the browser still needs the API role's address
+ * (`PUBLIC_REALTIME_ORIGIN`), or a routing layer in front of both roles that
+ * serves them on one origin.
  */
 export const dynamic = 'force-dynamic';
 
@@ -28,10 +28,18 @@ const FORWARDED_REQUEST_HEADERS = [
 const FORWARDED_RESPONSE_HEADERS = ['content-type', 'cache-control', 'etag'];
 
 async function forward(request: Request): Promise<Response> {
+  const apiUrl = env.INTERNAL_API_URL;
+  if (!apiUrl) {
+    // Said here, in words, rather than as a 404 from a route that is not there.
+    return Response.json(
+      { error: 'INTERNAL_API_URL is not set, so the web role cannot reach the API role' },
+      { status: 503 },
+    );
+  }
   const incoming = new URL(request.url);
   // Rebuilt from the incoming pathname rather than from the matched segments,
   // so an encoded segment reaches the API role exactly as it arrived.
-  const target = new URL(`${incoming.pathname}${incoming.search}`, internalApiUrl());
+  const target = new URL(`${incoming.pathname}${incoming.search}`, apiUrl);
 
   const headers = new Headers();
   for (const name of FORWARDED_REQUEST_HEADERS) {

package/template/packages/frontend/src/features/board/board-live.ts

@@ -27,6 +27,10 @@ let shared: ReturnType<typeof connect> | undefined;
 function connect(realtimeOrigin?: string) {
   const realtime = createRealtimeClient(liveContract, {
     url: realtimeOrigin ?? window.location.origin,
+    // The literal loader is what puts the socket client into this bundle.
+    // Stitchkit's own import of the peer is left alone by bundlers on purpose,
+    // so without this line the browser build has no `socket.io-client` in it.
+    peers: { client: () => import('socket.io-client') },
   });
   realtime.connect();
   return {

package/templates/telegram-bot/README.md

@@ -0,0 +1,41 @@
+# Stitchkit Telegram Bot
+
+A long-polling Telegram bot assembled from Stitchkit primitives. The product is
+`src/handlers.ts`; everything else is the assembly every bot needs and none
+should write again.
+
+## Start
+
+```bash
+cp .env.example .env
+# Fill BOT_TOKEN.
+bun run dev
+```
+
+## Shape
+
+- `src/handlers.ts` — the product: commands, messages, what goes to the operators' chat.
+- `src/application.ts` — the resource graph: `database` → (`telegram-files`) →
+  (`operator-channel`) → `telegram-configuration` → `telegram-polling`. Queues, an
+  HTTP server for payment webhooks, schedules and metrics go between the database
+  and the bot.
+- `src/index.ts` — the entry point: environment, journal, signals, and the one
+  policy for a poller that ended on its own (shut down, exit 1, let the supervisor
+  restart).
+- `src/runtime-bindings.ts` — where a deployment platform's state publisher is
+  attached, without the bot importing it anywhere else.
+- `src/log.ts` — the journal: one JSON line per event, `"level":50` is an error.
+- `tests/application.test.ts` — the whole life of the bot against a stand-in for Telegram.
+
+Updates are admitted by batch: nothing is fetched while the application is not
+ready, and a batch taken before a stop is finished before the offset is
+confirmed, so a restart neither loses nor repeats an update.
+
+## Commands
+
+```bash
+bun run check   # types
+bun run lint
+bun test
+bun run build   # dist/index.js, started by `bun run start`
+```

package/templates/telegram-bot/_env.example

@@ -0,0 +1,11 @@
+# The bot's token from @BotFather.
+BOT_TOKEN=
+# debug | info | warn | error
+LOG_LEVEL=info
+# SQLite file for the bot's own data; relative paths are from the working directory.
+DATABASE_PATH=.data/bot.sqlite
+# Optional: the operators' chat (a group, forum topics welcome) for product events.
+OPERATOR_CHAT_ID=
+# Optional: a local Bot API server, and the directory it was started with (--dir).
+BOT_API_URL=
+BOT_API_FILES_ROOT=

package/templates/telegram-bot/_gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+.env
+.data/
+coverage/
+*.log

package/templates/telegram-bot/biome.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.14/schema.json",
+  "files": {
+    "includes": ["**", "!!node_modules", "!!dist", "!!project.json", "!!**/.data"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 96
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "jsxQuoteStyle": "single",
+      "trailingCommas": "all",
+      "semicolons": "always"
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended",
+      "suspicious": {
+        "noExplicitAny": "error",
+        "noUnknownAttribute": "off"
+      }
+    }
+  }
+}

package/templates/telegram-bot/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "stitchkit-telegram-bot-starter",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "bun --watch src/index.ts",
+    "start": "bun dist/index.js",
+    "check": "bun x tsgo --noEmit",
+    "lint": "bun x biome check --error-on-warnings .",
+    "lint:fix": "bun x biome check --write .",
+    "test": "bun test",
+    "build": "bun build src/index.ts --outdir dist --target bun --packages external"
+  },
+  "dependencies": {
+    "@grammyjs/auto-retry": "^2.0.2",
+    "grammy": "^1.46.0",
+    "stitchkit": "file:../../../core",
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "@types/bun": "^1.4.2",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "packageManager": "bun@1.3.14"
+}

package/templates/telegram-bot/project.json

@@ -0,0 +1,76 @@
+{
+  "schemaVersion": 1,
+  "kind": "application",
+  "identity": {
+    "slug": "stitchkit-telegram-bot-starter",
+    "name": "Stitchkit Telegram Bot Starter",
+    "version": "0.1.0",
+    "description": {
+      "en": "A long-polling Telegram bot assembled from Stitchkit primitives."
+    }
+  },
+  "roles": [
+    {
+      "name": "bot",
+      "workingDirectory": ".",
+      "commands": {
+        "development": {
+          "executable": "bun",
+          "args": [
+            "--watch",
+            "src/index.ts"
+          ]
+        },
+        "production": {
+          "executable": "bun",
+          "args": [
+            "dist/index.js"
+          ]
+        }
+      },
+      "drainFloorMs": 1000
+    }
+  ],
+  "requires": [],
+  "release": {},
+  "env": {
+    "variables": [
+      {
+        "name": "BOT_TOKEN",
+        "shape": "string",
+        "required": true
+      },
+      {
+        "name": "LOG_LEVEL",
+        "shape": "enum",
+        "required": false,
+        "members": [
+          "debug",
+          "info",
+          "warn",
+          "error"
+        ]
+      },
+      {
+        "name": "DATABASE_PATH",
+        "shape": "string",
+        "required": false
+      },
+      {
+        "name": "OPERATOR_CHAT_ID",
+        "shape": "integer",
+        "required": false
+      },
+      {
+        "name": "BOT_API_URL",
+        "shape": "url",
+        "required": false
+      },
+      {
+        "name": "BOT_API_FILES_ROOT",
+        "shape": "string",
+        "required": false
+      }
+    ]
+  }
+}

package/templates/telegram-bot/src/application.ts

@@ -0,0 +1,92 @@
+import type { Bot } from 'grammy';
+import {
+  type ApplicationHandle,
+  createApplication,
+  defineManagedResource,
+  type ManagedResource,
+} from 'stitchkit/application';
+import { type GrammyPollingEnd, grammyBotResources } from 'stitchkit/application/grammy';
+import type { TelegramLocalFiles, TelegramOperatorChannel } from 'stitchkit/telegram';
+import { createDatabase } from './database';
+import { COMMANDS, type OperatorTopic, registerHandlers } from './handlers';
+import type { Log } from './log';
+
+export interface BotApplicationConfig {
+  readonly bot: Bot;
+  readonly databasePath: string;
+  readonly log: Log;
+  readonly operators?: TelegramOperatorChannel<OperatorTopic>;
+  /** Present when a local Bot API server shares its files directory with the bot. */
+  readonly files?: TelegramLocalFiles;
+  /** Polling ended on its own; the entry point turns this into its shutdown. */
+  readonly onPollingEnded: (end: GrammyPollingEnd) => void;
+  /** How long stopping may take. */
+  readonly shutdown?: { readonly gracePeriodMs: number; readonly forceTimeoutMs: number };
+}
+
+/**
+ * The graph, in start order:
+ *
+ *   database → [telegram-files] → [operator-channel] → telegram-configuration → telegram-polling
+ *
+ * Product resources — queues, an HTTP server for payment webhooks, schedules,
+ * metrics — go between the database and the bot, and join the bot's
+ * `dependsOn` when handlers need them before the first update.
+ */
+export function createBotApplication(config: BotApplicationConfig): ApplicationHandle {
+  const database = createDatabase(config.databasePath);
+  registerHandlers(config.bot, {
+    store: database.store,
+    ...(config.operators && { operators: config.operators }),
+  });
+  config.bot.catch(({ error, ctx }) => {
+    config.log.error('Telegram update failed', { updateId: ctx.update.update_id, error });
+    config.operators?.post(`Update ${ctx.update.update_id} failed`, 'errors');
+  });
+
+  const files = config.files;
+  const botDependencies: ManagedResource[] = [database.resource];
+  if (files) {
+    botDependencies.push(
+      defineManagedResource({
+        id: 'telegram-files',
+        dependsOn: [database.resource],
+        async start() {
+          const check = await files.check();
+          if (!check.ready) throw new Error(`Local Bot API files unavailable: ${check.reason}`);
+        },
+      }),
+    );
+  }
+  const operators = config.operators;
+  if (operators) {
+    botDependencies.push(
+      defineManagedResource({
+        id: 'operator-channel',
+        required: false,
+        start() {},
+        drain: (context) => operators.drain(context.signal),
+        close: () => operators.close(),
+      }),
+    );
+  }
+
+  const telegram = grammyBotResources({
+    bot: config.bot,
+    dependsOn: botDependencies,
+    configure: async () => {
+      await config.bot.api.setMyCommands(COMMANDS);
+    },
+    onStart: ({ username }) => config.log.info('Telegram polling started', { username }),
+    onError: (error) => config.log.error('Telegram polling failed', { error }),
+    onEnded: config.onPollingEnded,
+  });
+
+  return createApplication({
+    id: 'telegram-bot',
+    resources: [...botDependencies, ...telegram.resources],
+    shutdown: config.shutdown ?? { gracePeriodMs: 30_000, forceTimeoutMs: 5_000 },
+    onResourceFailure: ({ resourceId, phase, error }) =>
+      config.log.error('Resource failed', { resourceId, phase, error }),
+  });
+}

package/templates/telegram-bot/src/database.ts

@@ -0,0 +1,61 @@
+import { Database } from 'bun:sqlite';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { defineManagedResource } from 'stitchkit/application';
+
+/** What the bot stores. Replace it with the product's own tables. */
+export interface Store {
+  /** Remember a user; `true` the first time this user is seen. */
+  rememberUser(user: { id: number; firstName: string }): boolean;
+  userCount(): number;
+}
+
+function openStore(path: string): { store: Store; close(): void } {
+  if (path !== ':memory:') mkdirSync(dirname(path), { recursive: true });
+  const db = new Database(path, { create: true, strict: true });
+  db.run('PRAGMA journal_mode = WAL');
+  db.run(`CREATE TABLE IF NOT EXISTS users (
+    id INTEGER PRIMARY KEY,
+    first_name TEXT NOT NULL,
+    first_seen_at TEXT NOT NULL
+  )`);
+  const insert = db.query(
+    'INSERT OR IGNORE INTO users (id, first_name, first_seen_at) VALUES ($id, $firstName, $at)',
+  );
+  const count = db.query<{ count: number }, []>('SELECT count(*) AS count FROM users');
+  return {
+    store: {
+      rememberUser: (user) =>
+        insert.run({ id: user.id, firstName: user.firstName, at: new Date().toISOString() })
+          .changes > 0,
+      userCount: () => count.get()?.count ?? 0,
+    },
+    close: () => db.close(),
+  };
+}
+
+/**
+ * The database as the first resource of the graph. Handlers are registered
+ * before it opens, so they reach the store through `store()`, which the graph
+ * guarantees is open by the time an update is admitted.
+ */
+export function createDatabase(path: string) {
+  let opened: ReturnType<typeof openStore> | undefined;
+  const resource = defineManagedResource({
+    id: 'database',
+    start() {
+      opened = openStore(path);
+    },
+    close() {
+      opened?.close();
+      opened = undefined;
+    },
+  });
+  return {
+    resource,
+    store(): Store {
+      if (!opened) throw new Error('The database is not open');
+      return opened.store;
+    },
+  };
+}

package/templates/telegram-bot/src/env.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+
+const blankIsAbsent = (value: unknown) => (value === '' ? undefined : value);
+
+/** The variables `project.json` declares, parsed once at the edge of the process. */
+export const EnvSchema = z.object({
+  BOT_TOKEN: z.string().min(1, 'BOT_TOKEN is required — the token from @BotFather'),
+  LOG_LEVEL: z.preprocess(
+    blankIsAbsent,
+    z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+  ),
+  DATABASE_PATH: z.preprocess(blankIsAbsent, z.string().min(1).default('.data/bot.sqlite')),
+  OPERATOR_CHAT_ID: z.preprocess(blankIsAbsent, z.coerce.number().int().optional()),
+  BOT_API_URL: z.preprocess(blankIsAbsent, z.url().optional()),
+  BOT_API_FILES_ROOT: z.preprocess(
+    blankIsAbsent,
+    z.string().startsWith('/', 'BOT_API_FILES_ROOT must be absolute').optional(),
+  ),
+});
+export type Env = z.infer<typeof EnvSchema>;
+
+export function readEnv(source: Record<string, string | undefined> = process.env): Env {
+  const env = EnvSchema.parse(source);
+  if (env.BOT_API_URL && !env.BOT_API_FILES_ROOT) {
+    throw new Error(
+      'BOT_API_FILES_ROOT is required with BOT_API_URL: the bot reads its files from there',
+    );
+  }
+  return env;
+}

package/templates/telegram-bot/src/handlers.ts

@@ -0,0 +1,32 @@
+import type { Bot } from 'grammy';
+import type { TelegramOperatorChannel } from 'stitchkit/telegram';
+import type { Store } from './database';
+
+/** The command menu Telegram shows; published by `telegram-configuration`. */
+export const COMMANDS = [
+  { command: 'start', description: 'Start' },
+  { command: 'users', description: 'How many people found this bot' },
+];
+
+export type OperatorTopic = 'users' | 'errors';
+
+export interface Product {
+  readonly store: () => Store;
+  readonly operators?: TelegramOperatorChannel<OperatorTopic>;
+}
+
+/** The product. Everything else in this project is the assembly around it. */
+export function registerHandlers(bot: Bot, product: Product): void {
+  bot.command('start', async (ctx) => {
+    if (!ctx.from) return;
+    const isNew = product
+      .store()
+      .rememberUser({ id: ctx.from.id, firstName: ctx.from.first_name });
+    if (isNew) product.operators?.post(`New user ${ctx.from.id}`, 'users');
+    await ctx.reply(`Hello, ${ctx.from.first_name}!`);
+  });
+
+  bot.command('users', (ctx) => ctx.reply(`${product.store().userCount()} people so far.`));
+
+  bot.on('message:text', (ctx) => ctx.reply(ctx.message.text));
+}

package/templates/telegram-bot/src/index.ts

@@ -0,0 +1,100 @@
+import { autoRetry } from '@grammyjs/auto-retry';
+import { Bot } from 'grammy';
+import { bindProcessSignals } from 'stitchkit/server';
+import {
+  createTelegramLocalFiles,
+  createTelegramOperatorChannel,
+  telegramOperatorSender,
+} from 'stitchkit/telegram';
+import { createBotApplication } from './application';
+import { readEnv } from './env';
+import type { OperatorTopic } from './handlers';
+import { createLog } from './log';
+import { runtimeBindings } from './runtime-bindings';
+
+const env = readEnv();
+const log = createLog(env);
+
+const bot = new Bot(env.BOT_TOKEN, {
+  ...(env.BOT_API_URL && { client: { apiRoot: env.BOT_API_URL } }),
+});
+// A 429 on a reply is Telegram asking to wait, not a failure: wait what it names, then repeat.
+bot.api.config.use(autoRetry({ maxRetryAttempts: 3, maxDelaySeconds: 10 }));
+
+const operators =
+  env.OPERATOR_CHAT_ID === undefined
+    ? undefined
+    : createTelegramOperatorChannel<OperatorTopic>({
+        chatId: env.OPERATOR_CHAT_ID,
+        // Forum topic ids of the operators' chat, when it has topics.
+        topics: {},
+        send: telegramOperatorSender({
+          token: env.BOT_TOKEN,
+          ...(env.BOT_API_URL && { apiRoot: env.BOT_API_URL }),
+        }),
+        onDropped: (drop) => log.warn('Operator message dropped', { ...drop }),
+      });
+
+const app = createBotApplication({
+  bot,
+  databasePath: env.DATABASE_PATH,
+  log,
+  ...(operators && { operators }),
+  ...(env.BOT_API_FILES_ROOT && {
+    files: createTelegramLocalFiles({ root: env.BOT_API_FILES_ROOT, token: env.BOT_TOKEN }),
+  }),
+  // grammY's poller does not recover in-process: stop the way a signal would,
+  // and exit non-zero so the supervisor starts a fresh process.
+  onPollingEnded: ({ error }) => {
+    log.error('Telegram polling ended', { error });
+    stopAndExit(1);
+  },
+});
+const bindings = runtimeBindings(app, log);
+
+let exiting = false;
+async function finish(code: number): Promise<never> {
+  await Promise.allSettled(bindings.map((binding) => binding.close()));
+  process.exit(code);
+}
+function stopAndExit(code: number): void {
+  if (exiting) return;
+  exiting = true;
+  signals.close();
+  app
+    .shutdown()
+    .then((result) => {
+      log.info('Application stopped', { outcome: result.outcome });
+      return finish(code);
+    })
+    .catch((error: unknown) => {
+      log.error('Application shutdown failed', { error });
+      return finish(1);
+    });
+}
+
+const signals = bindProcessSignals(app, {
+  async onComplete(result) {
+    if (exiting) return;
+    exiting = true;
+    log.info('Application stopped', { outcome: result.outcome });
+    await finish(result.outcome === 'clean' && result.cleanupComplete ? 0 : 1);
+  },
+  onError(phase, error) {
+    log.error('Application lifecycle failed', { phase, error });
+    void finish(1);
+  },
+  onEscalationBlocked() {
+    void finish(1);
+  },
+});
+
+async function main(): Promise<void> {
+  for (const binding of bindings) await binding.start();
+  await app.start();
+}
+
+main().catch((error: unknown) => {
+  log.error('Application startup failed', { error });
+  void finish(1);
+});

package/templates/telegram-bot/src/log.ts

@@ -0,0 +1,18 @@
+import { createJsonLogger } from 'stitchkit/observability';
+import { TELEGRAM_BOT_TOKEN_PATTERN } from 'stitchkit/telegram';
+import type { Env } from './env';
+
+/**
+ * The process journal: one JSON line per event on standard output. An `Error`
+ * under any key keeps its name, message, stack and cause, and a bot token
+ * inside a URL or an error message is masked. A line with `"level":50` is an
+ * error — the one contract a supervisor reading the journal relies on.
+ */
+export function createLog(env: Pick<Env, 'LOG_LEVEL'>) {
+  return createJsonLogger({
+    level: env.LOG_LEVEL,
+    sensitiveUrlPatterns: [TELEGRAM_BOT_TOKEN_PATTERN],
+  });
+}
+
+export type Log = ReturnType<typeof createLog>;

package/templates/telegram-bot/src/runtime-bindings.ts

@@ -0,0 +1,24 @@
+import type { ApplicationHandle } from 'stitchkit/application';
+import type { Log } from './log';
+
+/**
+ * Something outside the bot that follows its application state — a deployment
+ * platform publishing readiness for its supervisor, a metrics exporter. It
+ * starts before the application and closes after it.
+ */
+export interface RuntimeBinding {
+  start(): Promise<void>;
+  close(): Promise<void>;
+}
+
+/**
+ * The one place such a binding is attached. The template binds nothing: a
+ * platform's own package supplies the binding, for example
+ *
+ *   return [bindReleasedApplication(app, { onError: (error) => log.error('…', { error }) })];
+ *
+ * and nothing else in the bot changes.
+ */
+export function runtimeBindings(_app: ApplicationHandle, _log: Log): RuntimeBinding[] {
+  return [];
+}

package/templates/telegram-bot/tests/application.test.ts

@@ -0,0 +1,120 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { Bot } from 'grammy';
+import { z } from 'zod';
+import { createBotApplication } from '../src/application';
+import { createLog } from '../src/log';
+
+/*
+ * The bot's whole life against a stand-in for Telegram: it starts in graph
+ * order, publishes its menu, answers, and stops cleanly — confirming exactly
+ * the updates it handled.
+ */
+
+const Poll = z.object({ offset: z.number().optional(), timeout: z.number().optional() });
+
+function fakeTelegram() {
+  let queue: number[] = [];
+  const calls: { method: string; body: Record<string, unknown> }[] = [];
+  const offsets: number[] = [];
+  let wake: (() => void) | undefined;
+  const server = Bun.serve({
+    port: 0,
+    hostname: '127.0.0.1',
+    async fetch(request) {
+      const method = new URL(request.url).pathname.split('/').pop() ?? '';
+      const body = z
+        .record(z.string(), z.unknown())
+        .parse(await request.json().catch(() => ({})));
+      calls.push({ method, body });
+      if (method === 'getMe') {
+        return Response.json({
+          ok: true,
+          result: { id: 1, is_bot: true, first_name: 'Bot', username: 'template_bot' },
+        });
+      }
+      if (method !== 'getUpdates') return Response.json({ ok: true, result: true });
+      const { offset = 0, timeout } = Poll.parse(body);
+      offsets.push(offset);
+      queue = queue.filter((id) => id >= offset);
+      if (queue.length === 0 && timeout !== undefined) {
+        await new Promise<void>((resolve) => {
+          wake = resolve;
+          request.signal.addEventListener('abort', () => resolve());
+          setTimeout(resolve, 200);
+        });
+      }
+      const batch = timeout === undefined ? [] : [...queue];
+      return Response.json({
+        ok: true,
+        result: batch.map((update_id) => ({
+          update_id,
+          message: {
+            message_id: update_id,
+            date: 0,
+            chat: { id: 7, type: 'private', first_name: 'Ada' },
+            from: { id: 7, is_bot: false, first_name: 'Ada' },
+            text: '/start',
+            entities: [{ type: 'bot_command', offset: 0, length: 6 }],
+          },
+        })),
+      });
+    },
+  });
+  return {
+    origin: server.url.origin,
+    calls,
+    offsets,
+    push(id: number) {
+      queue.push(id);
+      wake?.();
+    },
+    stop: () => server.stop(true),
+  };
+}
+
+const servers: { stop(): void }[] = [];
+afterEach(() => {
+  for (const server of servers.splice(0)) server.stop();
+});
+
+async function until(check: () => boolean): Promise<void> {
+  for (let attempt = 0; attempt < 400 && !check(); attempt += 1) await Bun.sleep(5);
+  expect(check()).toBe(true);
+}
+
+describe('the bot application', () => {
+  test('starts in graph order, answers /start and stops cleanly', async () => {
+    const telegram = fakeTelegram();
+    servers.push(telegram);
+    const ended: unknown[] = [];
+    const bot = new Bot('1:template', { client: { apiRoot: telegram.origin } });
+    const app = createBotApplication({
+      bot,
+      databasePath: ':memory:',
+      log: createLog({ LOG_LEVEL: 'info' }),
+      onPollingEnded: (end) => void ended.push(end),
+      shutdown: { gracePeriodMs: 2_000, forceTimeoutMs: 200 },
+    });
+
+    const snapshot = await app.start();
+    expect(snapshot.ready).toBe(true);
+    expect(snapshot.resources.map((resource) => resource.id)).toEqual([
+      'database',
+      'telegram-configuration',
+      'telegram-polling',
+    ]);
+    expect(telegram.calls.map((call) => call.method)).toContain('setMyCommands');
+
+    telegram.push(5);
+    await until(() => telegram.calls.some((call) => call.method === 'sendMessage'));
+    expect(telegram.calls.find((call) => call.method === 'sendMessage')?.body).toMatchObject({
+      chat_id: 7,
+      text: 'Hello, Ada!',
+    });
+
+    const result = await app.shutdown();
+    expect(result.outcome).toBe('clean');
+    expect(Math.max(...telegram.offsets)).toBe(6);
+    expect(ended).toEqual([]);
+  });
+});

package/templates/telegram-bot/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "skipLibCheck": true,
+    "types": ["bun"]
+  },
+  "include": ["src", "tests"]
+}