create-stitchkit 0.6.4 → 0.6.6

package/CHANGELOG.md

@@ -12,6 +12,46 @@ step is overwritten by the next release.
 
 ## [Unreleased]
 
+## [0.6.6] — 2026-09-24
+
+### Fixed
+
+- **A project from `--template agent` or `--template telegram-bot` installs.**
+  The scaffolder rewrote their Stitchkit dependency to `catalog:` and wrote a
+  root `catalog`, which Bun reads only in a workspace root, so `bun install`
+  refused the generated project ("stitchkit@catalog: is not in the catalog").
+  A project without `workspaces` now gets the range itself —
+  `"stitchkit": "^0.96.0"` — and no catalog; the application template, a
+  workspace, is unchanged. A project already generated from either template
+  replaces each `"catalog:"` in its dependencies with the range from its
+  `catalog` field and deletes that field.
+- **A project from `--template agent` passes its own tests.** It mounts its
+  agent with `stitchkit/tools`, whose optional peer
+  `@modelcontextprotocol/server` the template did not declare; inside this
+  repository the workspace supplied it. The template now depends on
+  `@modelcontextprotocol/server` `^2.0.0`.
+- A new lane generates both single-package templates the way a user does,
+  installs them from the registry, and runs their check and tests — neither
+  defect above could be seen by a lane that installs the template directory.
+
+## [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

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");
@@ -299,6 +299,7 @@ var TEMPLATE_RENAMES = new Map([
 var RootManifestSchema = z2.looseObject({
   name: z2.string().min(1),
   catalog: z2.record(z2.string(), z2.string()).optional(),
+  workspaces: z2.unknown().optional(),
   dependencies: z2.record(z2.string(), z2.string()).optional(),
   devDependencies: z2.record(z2.string(), z2.string()).optional()
 });
@@ -435,21 +436,33 @@ async function scaffoldProject(templateDirectory, destination, options = {}) {
     const manifestPath = join(resolvedDestination, "package.json");
     const manifest = RootManifestSchema.parse(JSON.parse(await readFile(manifestPath, "utf8")));
     const catalog = options.stitchkitCatalogTarget ? { ...manifest.catalog ?? {}, stitchkit: options.stitchkitCatalogTarget } : manifest.catalog;
+    const isWorkspace = manifest.workspaces !== undefined;
+    const localReference = (name) => {
+      if (isWorkspace)
+        return "catalog:";
+      const range = catalog?.[name];
+      if (!range)
+        throw new Error(`Template catalog has no range for ${name}`);
+      return range;
+    };
     const replaceLocalPackages = (dependencies) => {
       if (!dependencies)
         return dependencies;
       return {
         ...dependencies,
-        ...dependencies.stitchkit?.startsWith("file:") && { stitchkit: "catalog:" },
+        ...dependencies.stitchkit?.startsWith("file:") && {
+          stitchkit: localReference("stitchkit")
+        },
         ...dependencies["stitchkit-tui"]?.startsWith("file:") && {
-          "stitchkit-tui": "catalog:"
+          "stitchkit-tui": localReference("stitchkit-tui")
         }
       };
     };
+    const { catalog: _templateCatalog, ...withoutCatalog } = manifest;
     await writeFile(manifestPath, `${JSON.stringify({
-      ...manifest,
+      ...isWorkspace ? manifest : withoutCatalog,
       name: identity.slug,
-      ...catalog && { catalog },
+      ...isWorkspace && catalog && { catalog },
       ...manifest.dependencies && {
         dependencies: replaceLocalPackages(manifest.dependencies)
       },
@@ -479,12 +492,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 +514,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stitchkit",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "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.95.3",
+    "stitchkit": "0.96.0",
     "typescript": "^7.0.2"
   },
   "engines": {

package/template/bun.lock

@@ -145,7 +145,7 @@
     "zod": "4.6.5",
   },
   "catalog": {
-    "stitchkit": "^0.95.3",
+    "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.95.3", "", { "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-IVIf7CF951Q4Olfiu+wONxAmc802zvPwGYWjNo+657OHua4gzc91XNo4/zmmPPZzkvA6iyOQmzFurgrbmJ9SrQ=="],
+    "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/package.json

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

package/templates/agent/package.json

@@ -16,6 +16,7 @@
     "build": "bun build src/index.ts --outdir dist --target bun --packages external"
   },
   "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
     "@openrouter/ai-sdk-provider": "^3.1.0",
     "ai": "^7.0.111",
     "stitchkit": "file:../../../core",

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"]
+}