bono-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sillyfrogster
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# bono
+
+[![npm](https://img.shields.io/npm/v/bono-cli)](https://www.npmjs.com/package/bono-cli)
+[![license](https://img.shields.io/npm/l/bono-cli)](LICENSE)
+[![bun](https://img.shields.io/badge/runtime-bun-f9f1e1)](https://bun.sh)
+
+Scaffold a Hono API on Bun with the boring setup already done.
+
+```sh
+bunx bono-cli new my-api
+```
+
+Prompts for Postgres, docker-compose, and Drizzle. `--base` skips them all.
+
+## The base
+
+- Feature-based file structure, with a `todos` example to copy from
+- pino logging with request IDs
+- One error shape everywhere, `AppError` to control it
+- zod env validation, crashes at startup instead of at runtime
+- Request validation wired to the same error shape
+- Rate limiting behind a swappable store
+- Health endpoint, CORS, graceful shutdown
+- Biome and `bun test` configured
+
+## Flags
+
+| Flag | |
+| --- | --- |
+| `--base` | Skip prompts, base only |
+| `--database <postgres\|none>` | |
+| `--docker` / `--no-docker` | docker-compose for local Postgres |
+| `--orm <drizzle\|none>` | |
+| `--no-git` | Skip `git init` |
+| `--no-install` | Skip `bun install` |
+
+## Requirements
+
+Bun 1.2+
+
+## License
+
+MIT

package/cli/index.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env bun
+import { parseArgs } from "node:util";
+import { runNew } from "./src/new.ts";
+
+const HELP = `bono - scaffold a production-ready Hono API on Bun
+
+Usage:
+  bono new <name> [options]
+
+Options:
+  --base                       Skip all prompts, generate the base
+  --database <postgres|none>   Answer the database prompt
+  --orm <drizzle|none>         Answer the ORM prompt
+  --docker / --no-docker       Answer the docker-compose prompt
+  --no-git                     Skip git init
+  --no-install                 Skip bun install
+  --help, -h                   Show this help
+`;
+
+const { values, positionals } = parseArgs({
+  args: Bun.argv.slice(2),
+  allowPositionals: true,
+  options: {
+    base: { type: "boolean", default: false },
+    database: { type: "string" },
+    orm: { type: "string" },
+    docker: { type: "boolean", default: false },
+    "no-docker": { type: "boolean", default: false },
+    "no-git": { type: "boolean", default: false },
+    "no-install": { type: "boolean", default: false },
+    help: { type: "boolean", short: "h", default: false },
+  },
+});
+
+const [command, projectName] = positionals;
+
+if (values.help || !command) {
+  console.log(HELP);
+  process.exit(values.help ? 0 : 1);
+}
+
+if (command !== "new") {
+  console.error(`Unknown command "${command}".\n\n${HELP}`);
+  process.exit(1);
+}
+
+if (!projectName) {
+  console.error(`Missing project name.\n\nUsage: bono new <name>`);
+  process.exit(1);
+}
+
+await runNew({
+  projectName,
+  base: values.base,
+  database: values.database,
+  orm: values.orm,
+  docker: values.docker ? true : values["no-docker"] ? false : undefined,
+  git: !values["no-git"],
+  install: !values["no-install"],
+});

package/cli/src/apply.ts

@@ -0,0 +1,149 @@
+import { cpSync, existsSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { type IntegrationManifest, loadManifest } from "./manifest.ts";
+
+/** Copies the base template and personalizes it (name, .gitignore). */
+export async function copyBase(
+  templatesDir: string,
+  dest: string,
+  projectName: string,
+): Promise<void> {
+  // The filter matters when running from the repo, where the template
+  // workspace has its own install and env; the published tarball ships none
+  // of these.
+  const skip = ["node_modules", "bun.lock", ".env"];
+  cpSync(join(templatesDir, "base"), dest, {
+    recursive: true,
+    filter: (source) => !skip.some((name) => source.endsWith(`/${name}`)),
+  });
+
+  // npm strips .gitignore from published tarballs, so the template ships
+  // it as _gitignore and it gets renamed here.
+  renameSync(join(dest, "_gitignore"), join(dest, ".gitignore"));
+
+  const packageJsonPath = join(dest, "package.json");
+  const packageJson = await Bun.file(packageJsonPath).json();
+  packageJson.name = projectName;
+  await writeJson(packageJsonPath, packageJson);
+
+  const readmePath = join(dest, "README.md");
+  const readme = await Bun.file(readmePath).text();
+  await Bun.write(readmePath, readme.replace(/^# .+/, `# ${projectName}`));
+}
+
+/** Copies an integration's files in and applies its manifest. */
+export async function applyIntegration(
+  templatesDir: string,
+  dest: string,
+  name: string,
+): Promise<IntegrationManifest> {
+  const integrationDir = join(templatesDir, "integrations", name);
+  const manifest = await loadManifest(integrationDir);
+
+  const filesDir = join(integrationDir, "files");
+  if (existsSync(filesDir)) {
+    cpSync(filesDir, dest, { recursive: true });
+  }
+
+  await mergePackageJson(dest, manifest);
+  await appendEnv(dest, manifest.env ?? []);
+  for (const insert of manifest.inserts ?? []) {
+    await applyInsert(dest, insert.file, insert.anchor, insert.line);
+  }
+  if (manifest.readme) {
+    await appendReadme(dest, manifest.readme);
+  }
+  return manifest;
+}
+
+/** Appends an integration's docs to the generated README, once. */
+async function appendReadme(dest: string, section: string): Promise<void> {
+  const path = join(dest, "README.md");
+  const current = await Bun.file(path).text();
+  const trimmed = section.trim();
+  if (current.includes(trimmed)) {
+    return;
+  }
+  await Bun.write(path, `${current.trimEnd()}\n\n${trimmed}\n`);
+}
+
+async function mergePackageJson(
+  dest: string,
+  manifest: IntegrationManifest,
+): Promise<void> {
+  const path = join(dest, "package.json");
+  const packageJson = await Bun.file(path).json();
+  packageJson.dependencies = sortKeys({
+    ...packageJson.dependencies,
+    ...manifest.dependencies,
+  });
+  packageJson.devDependencies = sortKeys({
+    ...packageJson.devDependencies,
+    ...manifest.devDependencies,
+  });
+  packageJson.scripts = { ...packageJson.scripts, ...manifest.scripts };
+  await writeJson(path, packageJson);
+}
+
+/** Adds env entries to .env.example, skipping keys that already exist. */
+async function appendEnv(
+  dest: string,
+  entries: { key: string; value: string }[],
+): Promise<void> {
+  if (entries.length === 0) {
+    return;
+  }
+  const path = join(dest, ".env.example");
+  const current = await Bun.file(path).text();
+  const existingKeys = new Set(
+    current
+      .split("\n")
+      .map((line) => line.split("=")[0]?.trim())
+      .filter(Boolean),
+  );
+  const missing = entries.filter((entry) => !existingKeys.has(entry.key));
+  if (missing.length === 0) {
+    return;
+  }
+  const lines = missing
+    .map((entry) => `${entry.key}=${entry.value}`)
+    .join("\n");
+  const separator = current.endsWith("\n") ? "" : "\n";
+  await Bun.write(path, `${current}${separator}${lines}\n`);
+}
+
+/**
+ * Inserts a line directly above a known anchor comment in a base file.
+ * Applying the same insert twice is a no-op.
+ */
+async function applyInsert(
+  dest: string,
+  file: string,
+  anchor: string,
+  line: string,
+): Promise<void> {
+  const path = join(dest, file);
+  const content = await Bun.file(path).text();
+  if (content.includes(line)) {
+    return;
+  }
+  const lines = content.split("\n");
+  const anchorIndex = lines.findIndex(
+    (candidate) => candidate.trim() === anchor.trim(),
+  );
+  if (anchorIndex === -1) {
+    throw new Error(`Anchor "${anchor}" not found in ${file}`);
+  }
+  lines.splice(anchorIndex, 0, line);
+  await Bun.write(path, lines.join("\n"));
+}
+
+function sortKeys(record: Record<string, string>): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(record).sort(([a], [b]) => a.localeCompare(b)),
+  );
+}
+
+async function writeJson(path: string, value: unknown): Promise<void> {
+  await Bun.write(path, `${JSON.stringify(value, null, 2)}\n`);
+}

package/cli/src/manifest.ts

@@ -0,0 +1,36 @@
+import { join } from "node:path";
+
+export interface EnvEntry {
+  key: string;
+  value: string;
+}
+
+/** A line added to an existing base file, placed before a known anchor comment. */
+export interface Insert {
+  file: string;
+  anchor: string;
+  line: string;
+}
+
+export interface IntegrationManifest {
+  name: string;
+  description: string;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  scripts?: Record<string, string>;
+  env?: EnvEntry[];
+  inserts?: Insert[];
+  /** Markdown appended to the generated project's README. */
+  readme?: string;
+}
+
+export async function loadManifest(
+  integrationDir: string,
+): Promise<IntegrationManifest> {
+  const path = join(integrationDir, "manifest.json");
+  const manifest = (await Bun.file(path).json()) as IntegrationManifest;
+  if (!manifest.name || !manifest.description) {
+    throw new Error(`Manifest at ${path} is missing name or description`);
+  }
+  return manifest;
+}

package/cli/src/new.ts

@@ -0,0 +1,165 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { applyIntegration, copyBase } from "./apply.ts";
+import {
+  type Answers,
+  type Database,
+  integrationsFor,
+  type Orm,
+  validateAnswers,
+} from "./plan.ts";
+
+export interface NewOptions {
+  projectName: string;
+  base: boolean;
+  database?: string;
+  orm?: string;
+  docker?: boolean;
+  git: boolean;
+  install: boolean;
+}
+
+export async function runNew(options: NewOptions): Promise<void> {
+  const dest = resolve(process.cwd(), options.projectName);
+  const templatesDir = resolve(import.meta.dir, "../../templates");
+
+  if (!/^[a-z0-9][a-z0-9-_]*$/i.test(options.projectName)) {
+    failInput(
+      `"${options.projectName}" is not a valid project name (letters, numbers, - and _).`,
+    );
+  }
+  if (existsSync(dest)) {
+    failInput(`${dest} already exists.`);
+  }
+
+  p.intro(pc.bold("bono"));
+
+  const answers = await collectAnswers(options);
+  const validationError = validateAnswers(answers);
+  if (validationError) {
+    failInput(validationError);
+  }
+
+  const spinner = p.spinner();
+  spinner.start("Copying base");
+  await copyBase(templatesDir, dest, options.projectName);
+  for (const name of integrationsFor(answers)) {
+    spinner.message(`Adding ${name}`);
+    await applyIntegration(templatesDir, dest, name);
+  }
+  spinner.stop("Project files written");
+
+  if (options.git) {
+    run(["git", "init", "-b", "main"], dest, "git init failed");
+  }
+  if (options.install) {
+    const installSpinner = p.spinner();
+    installSpinner.start("Installing dependencies");
+    run(["bun", "install"], dest, "bun install failed");
+    installSpinner.stop("Dependencies installed");
+  }
+
+  const nextSteps = [
+    `cd ${options.projectName}`,
+    ...(options.install ? [] : ["bun install"]),
+    "cp .env.example .env",
+    ...(answers.docker ? ["docker compose up -d"] : []),
+    "bun run dev",
+  ].join("\n");
+  p.note(nextSteps, "Next steps");
+  p.outro("Done.");
+}
+
+async function collectAnswers(options: NewOptions): Promise<Answers> {
+  // Flags answer prompts directly; --base or a non-interactive terminal
+  // answers everything not given with "none".
+  const skipPrompts = options.base || !process.stdout.isTTY;
+
+  const database =
+    (options.database as Database | undefined) ??
+    (skipPrompts ? "none" : await askDatabase());
+
+  if (database === "none") {
+    return { database, docker: false, orm: "none" };
+  }
+
+  const docker = options.docker ?? (skipPrompts ? false : await askDocker());
+
+  const orm =
+    (options.orm as Orm | undefined) ?? (skipPrompts ? "none" : await askOrm());
+
+  return { database, docker, orm };
+}
+
+async function askDatabase(): Promise<Database> {
+  const choice = await p.select({
+    message: "Database?",
+    options: [
+      {
+        value: "postgres" as const,
+        label: "Postgres",
+        hint: "Bun-native client, zero dependencies",
+      },
+      {
+        value: "none" as const,
+        label: "None",
+        hint: "set one up yourself later",
+      },
+    ],
+  });
+  return cancelled(choice);
+}
+
+async function askDocker(): Promise<boolean> {
+  const choice = await p.confirm({
+    message: "docker-compose for local Postgres?",
+  });
+  return cancelled(choice);
+}
+
+async function askOrm(): Promise<Orm> {
+  const choice = await p.select({
+    message: "ORM?",
+    options: [
+      {
+        value: "drizzle" as const,
+        label: "Drizzle",
+        hint: "schema, migrations, typed queries",
+      },
+      {
+        value: "none" as const,
+        label: "None",
+        hint: "raw SQL through the client",
+      },
+    ],
+  });
+  return cancelled(choice);
+}
+
+function cancelled<T>(value: T | symbol): T {
+  if (p.isCancel(value)) {
+    p.cancel("Cancelled, nothing was created.");
+    process.exit(1);
+  }
+  return value;
+}
+
+function run(command: string[], cwd: string, errorMessage: string): void {
+  const result = Bun.spawnSync(command, {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (result.exitCode !== 0) {
+    p.log.error(`${errorMessage}:\n${result.stderr.toString()}`);
+    process.exit(1);
+  }
+}
+
+// Input mistakes are not failures; keep them calm, not red.
+function failInput(message: string): never {
+  p.log.warn(message);
+  process.exit(1);
+}

package/cli/src/plan.ts

@@ -0,0 +1,47 @@
+export const DATABASES = ["postgres", "none"] as const;
+export const ORMS = ["drizzle", "none"] as const;
+
+export type Database = (typeof DATABASES)[number];
+export type Orm = (typeof ORMS)[number];
+
+export interface Answers {
+  database: Database;
+  /** docker-compose for local Postgres; only meaningful with database=postgres. */
+  docker: boolean;
+  orm: Orm;
+}
+
+/**
+ * Maps prompt answers to the integration folders to apply, in order.
+ * The whole CLI's decision logic lives here so it can be tested as data.
+ */
+export function integrationsFor(answers: Answers): string[] {
+  if (answers.database === "none") {
+    return [];
+  }
+  const integrations = ["db-postgres"];
+  if (answers.docker) {
+    integrations.push("compose-postgres");
+  }
+  if (answers.orm === "drizzle") {
+    integrations.push("drizzle");
+  }
+  return integrations;
+}
+
+/** Rejects combinations that make no sense before any file is written. */
+export function validateAnswers(answers: Answers): string | null {
+  if (!DATABASES.includes(answers.database)) {
+    return `Unknown database "${answers.database}". Expected: ${DATABASES.join(", ")}`;
+  }
+  if (!ORMS.includes(answers.orm)) {
+    return `Unknown ORM "${answers.orm}". Expected: ${ORMS.join(", ")}`;
+  }
+  if (answers.database === "none" && answers.orm !== "none") {
+    return "An ORM without a database makes no sense. Pick a database or drop the ORM.";
+  }
+  if (answers.database === "none" && answers.docker) {
+    return "docker-compose is only for the Postgres option.";
+  }
+  return null;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "bono-cli",
+  "version": "0.1.0",
+  "description": "CLI for scaffolding Hono APIs on Bun",
+  "license": "MIT",
+  "author": "Sillyfrogster (https://github.com/Sillyfrogster)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sillyfrogster/bono.git"
+  },
+  "homepage": "https://github.com/Sillyfrogster/bono#readme",
+  "bugs": "https://github.com/Sillyfrogster/bono/issues",
+  "type": "module",
+  "bin": {
+    "bono": "cli/index.ts"
+  },
+  "files": [
+    "cli",
+    "templates",
+    "!cli/**/*.test.ts",
+    "!**/node_modules",
+    "!**/bun.lock",
+    "!**/.env"
+  ],
+  "scripts": {
+    "test": "bun test cli",
+    "check": "biome check .",
+    "typecheck": "tsc --noEmit",
+    "verify": "bun scripts/verify-combos.ts",
+    "prepublishOnly": "bun test cli && bun run verify"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.0",
+    "@types/bun": "latest",
+    "typescript": "^5.8.0"
+  },
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "keywords": [
+    "hono",
+    "bun",
+    "scaffold",
+    "cli",
+    "api"
+  ]
+}

package/templates/base/.env.example

@@ -0,0 +1,3 @@
+NODE_ENV=development
+PORT=3000
+LOG_LEVEL=info

package/templates/base/README.md

@@ -0,0 +1,46 @@
+# bono-app
+
+Hono on Bun, scaffolded by [bono](https://www.npmjs.com/package/bono-cli).
+
+```sh
+cp .env.example .env
+bun run dev
+```
+
+## Scripts
+
+| | |
+| --- | --- |
+| `bun run dev` | start with watch |
+| `bun run start` | start |
+| `bun test` | tests |
+| `bun run check` | lint + format |
+| `bun run typecheck` | tsc |
+
+## Structure
+
+```
+src/
+  index.ts       server start + shutdown
+  app.ts         middleware + route mounting
+  config/env.ts  env validation
+  lib/           logger, errors, validate helper
+  middleware/    request logging, rate limiting
+  features/      one folder per feature
+```
+
+`features/todos` is the example. Copy the pattern, then delete it.
+
+## Errors
+
+Everything error-shaped comes back as:
+
+```json
+{ "error": { "code": "TODO_NOT_FOUND", "message": "..." }, "requestId": "..." }
+```
+
+Throw `AppError(status, code, message)` anywhere. Anything else thrown is a 500 with the details kept out of the response.
+
+## Rate limiting
+
+In-memory, 100 req/min per IP. Implement `RateLimitStore` (`src/middleware/rate-limit.ts`) to back it with something shared.

package/templates/base/_gitignore

@@ -0,0 +1,2 @@
+node_modules/
+.env

package/templates/base/biome.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.3/schema.json",
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended"
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "always"
+    }
+  }
+}

package/templates/base/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "bono-app",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun --watch src/index.ts",
+    "start": "bun src/index.ts",
+    "test": "bun test",
+    "check": "biome check .",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@hono/zod-validator": "^0.7.0",
+    "hono": "^4.8.0",
+    "pino": "^9.7.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.0",
+    "@types/bun": "latest",
+    "pino-pretty": "^13.0.0",
+    "typescript": "^5.8.0"
+  }
+}

package/templates/base/src/app.ts

@@ -0,0 +1,52 @@
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { requestId } from "hono/request-id";
+import { todosRoutes } from "./features/todos/todos.routes.ts";
+import type { AppEnv } from "./lib/app-env.ts";
+import { AppError, type ErrorBody } from "./lib/errors.ts";
+import { logger } from "./lib/logger.ts";
+import { rateLimit } from "./middleware/rate-limit.ts";
+import { requestLogger } from "./middleware/request-logger.ts";
+
+export const app = new Hono<AppEnv>();
+
+app.use(requestId());
+app.use(requestLogger());
+app.use(cors());
+app.use(rateLimit());
+// bono:middleware
+
+app.get("/health", (c) => c.json({ status: "ok" }));
+app.route("/todos", todosRoutes);
+// bono:routes
+
+app.notFound((c) => {
+  const body: ErrorBody = {
+    error: {
+      code: "NOT_FOUND",
+      message: `No route for ${c.req.method} ${c.req.path}`,
+    },
+    requestId: c.get("requestId") ?? "",
+  };
+  return c.json(body, 404);
+});
+
+app.onError((err, c) => {
+  const requestId = c.get("requestId") ?? "";
+
+  if (err instanceof AppError) {
+    const body: ErrorBody = {
+      error: { code: err.code, message: err.message },
+      requestId,
+    };
+    return c.json(body, err.status);
+  }
+
+  // Unexpected errors: log everything, leak nothing.
+  logger.error({ requestId, err }, "unhandled error");
+  const body: ErrorBody = {
+    error: { code: "INTERNAL_ERROR", message: "Something went wrong" },
+    requestId,
+  };
+  return c.json(body, 500);
+});

package/templates/base/src/config/env.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+
+const envSchema = z.object({
+  NODE_ENV: z
+    .enum(["development", "test", "production"])
+    .default("development"),
+  PORT: z.coerce.number().int().positive().default(3000),
+  LOG_LEVEL: z
+    .enum(["fatal", "error", "warn", "info", "debug", "trace"])
+    .default("info"),
+  // bono:env
+});
+
+const parsed = envSchema.safeParse(process.env);
+
+if (!parsed.success) {
+  // The logger depends on this file, so plain stderr is the only option here.
+  console.error("Invalid environment variables:");
+  for (const issue of parsed.error.issues) {
+    console.error(`  ${issue.path.join(".")}: ${issue.message}`);
+  }
+  process.exit(1);
+}
+
+export const env = parsed.data;

package/templates/base/src/features/todos/todos.routes.ts

@@ -0,0 +1,53 @@
+import { Hono } from "hono";
+import type { AppEnv } from "../../lib/app-env.ts";
+import { AppError } from "../../lib/errors.ts";
+import { validate } from "../../lib/validate.ts";
+import {
+  createTodoSchema,
+  todoIdParamSchema,
+  updateTodoSchema,
+} from "./todos.schema.ts";
+import {
+  createTodo,
+  deleteTodo,
+  getTodo,
+  listTodos,
+  updateTodo,
+} from "./todos.service.ts";
+
+export const todosRoutes = new Hono<AppEnv>()
+  .get("/", (c) => {
+    return c.json(listTodos());
+  })
+  .get("/:id", validate("param", todoIdParamSchema), (c) => {
+    const { id } = c.req.valid("param");
+    const todo = getTodo(id);
+    if (!todo) {
+      throw new AppError(404, "TODO_NOT_FOUND", `No todo with id ${id}`);
+    }
+    return c.json(todo);
+  })
+  .post("/", validate("json", createTodoSchema), (c) => {
+    const todo = createTodo(c.req.valid("json"));
+    return c.json(todo, 201);
+  })
+  .patch(
+    "/:id",
+    validate("param", todoIdParamSchema),
+    validate("json", updateTodoSchema),
+    (c) => {
+      const { id } = c.req.valid("param");
+      const todo = updateTodo(id, c.req.valid("json"));
+      if (!todo) {
+        throw new AppError(404, "TODO_NOT_FOUND", `No todo with id ${id}`);
+      }
+      return c.json(todo);
+    },
+  )
+  .delete("/:id", validate("param", todoIdParamSchema), (c) => {
+    const { id } = c.req.valid("param");
+    if (!deleteTodo(id)) {
+      throw new AppError(404, "TODO_NOT_FOUND", `No todo with id ${id}`);
+    }
+    return c.body(null, 204);
+  });

package/templates/base/src/features/todos/todos.schema.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+
+export const todoSchema = z.object({
+  id: z.uuid(),
+  title: z.string().min(1).max(200),
+  completed: z.boolean(),
+  createdAt: z.iso.datetime(),
+});
+
+export const createTodoSchema = z.object({
+  title: z.string().min(1).max(200),
+});
+
+export const updateTodoSchema = z
+  .object({
+    title: z.string().min(1).max(200).optional(),
+    completed: z.boolean().optional(),
+  })
+  .refine((body) => Object.keys(body).length > 0, {
+    message: "Provide at least one field to update",
+  });
+
+export const todoIdParamSchema = z.object({
+  id: z.uuid(),
+});
+
+export type Todo = z.infer<typeof todoSchema>;
+export type CreateTodo = z.infer<typeof createTodoSchema>;
+export type UpdateTodo = z.infer<typeof updateTodoSchema>;

package/templates/base/src/features/todos/todos.service.ts

@@ -0,0 +1,36 @@
+import type { CreateTodo, Todo, UpdateTodo } from "./todos.schema.ts";
+
+const todos = new Map<string, Todo>();
+
+export function listTodos(): Todo[] {
+  return [...todos.values()];
+}
+
+export function getTodo(id: string): Todo | undefined {
+  return todos.get(id);
+}
+
+export function createTodo(input: CreateTodo): Todo {
+  const todo: Todo = {
+    id: crypto.randomUUID(),
+    title: input.title,
+    completed: false,
+    createdAt: new Date().toISOString(),
+  };
+  todos.set(todo.id, todo);
+  return todo;
+}
+
+export function updateTodo(id: string, input: UpdateTodo): Todo | undefined {
+  const existing = todos.get(id);
+  if (!existing) {
+    return undefined;
+  }
+  const updated: Todo = { ...existing, ...input };
+  todos.set(id, updated);
+  return updated;
+}
+
+export function deleteTodo(id: string): boolean {
+  return todos.delete(id);
+}

package/templates/base/src/index.ts

@@ -0,0 +1,19 @@
+import { app } from "./app.ts";
+import { env } from "./config/env.ts";
+import { logger } from "./lib/logger.ts";
+
+const server = Bun.serve({
+  port: env.PORT,
+  fetch: app.fetch,
+});
+
+logger.info({ port: env.PORT, env: env.NODE_ENV }, "server listening");
+
+async function shutdown(signal: string): Promise<void> {
+  logger.info({ signal }, "shutting down");
+  await server.stop();
+  process.exit(0);
+}
+
+process.on("SIGINT", () => void shutdown("SIGINT"));
+process.on("SIGTERM", () => void shutdown("SIGTERM"));

package/templates/base/src/lib/app-env.ts

@@ -0,0 +1,6 @@
+import type { RequestIdVariables } from "hono/request-id";
+
+/** Hono env shared by the app and every route file. */
+export type AppEnv = {
+  Variables: RequestIdVariables;
+};

package/templates/base/src/lib/errors.ts

@@ -0,0 +1,26 @@
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+
+/**
+ * Throw this anywhere in a handler or service to produce a clean error
+ * response. Anything else that throws becomes a 500 with no leaked details.
+ */
+export class AppError extends Error {
+  readonly status: ContentfulStatusCode;
+  readonly code: string;
+
+  constructor(status: ContentfulStatusCode, code: string, message: string) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+/** The one error response shape used everywhere. */
+export interface ErrorBody {
+  error: {
+    code: string;
+    message: string;
+    details?: unknown;
+  };
+  requestId: string;
+}

package/templates/base/src/lib/logger.ts

@@ -0,0 +1,17 @@
+import pino from "pino";
+import { env } from "../config/env.ts";
+
+const usePretty = env.NODE_ENV === "development" && process.stdout.isTTY;
+
+export const logger = pino(
+  // Silent during `bun test` unless LOG_LEVEL is set explicitly.
+  {
+    level:
+      env.NODE_ENV === "test" && !process.env.LOG_LEVEL
+        ? "silent"
+        : env.LOG_LEVEL,
+  },
+  usePretty
+    ? (await import("pino-pretty")).default({ colorize: true })
+    : undefined,
+);

package/templates/base/src/lib/validate.ts

@@ -0,0 +1,29 @@
+import { zValidator } from "@hono/zod-validator";
+import type { ValidationTargets } from "hono";
+import type { ZodType } from "zod";
+import type { ErrorBody } from "./errors.ts";
+
+/**
+ * zValidator wrapped so validation failures use the app's error shape
+ * instead of the library default. Use it exactly like zValidator:
+ *
+ *   app.post("/", validate("json", createTodoSchema), handler)
+ */
+export function validate<Schema extends ZodType, Target extends keyof ValidationTargets>(target: Target, schema: Schema) {
+  return zValidator(target, schema, (result, c) => {
+    if (!result.success) {
+      const body: ErrorBody = {
+        error: {
+          code: "VALIDATION_ERROR",
+          message: `Invalid ${target}`,
+          details: result.error.issues.map((issue) => ({
+            path: issue.path.join("."),
+            message: issue.message,
+          })),
+        },
+        requestId: c.get("requestId") ?? "",
+      };
+      return c.json(body, 400);
+    }
+  });
+}

package/templates/base/src/middleware/rate-limit.ts

@@ -0,0 +1,100 @@
+import type { Context } from "hono";
+import { getConnInfo } from "hono/bun";
+import { createMiddleware } from "hono/factory";
+import type { ErrorBody } from "../lib/errors.ts";
+
+/**
+ * Where hit counts live.
+ */
+export interface RateLimitStore {
+  hit(
+    key: string,
+    windowMs: number,
+  ): Promise<{ count: number; resetAt: number }>;
+}
+
+export class MemoryRateLimitStore implements RateLimitStore {
+  private readonly windows = new Map<
+    string,
+    { count: number; resetAt: number }
+  >();
+
+  async hit(
+    key: string,
+    windowMs: number,
+  ): Promise<{ count: number; resetAt: number }> {
+    const now = Date.now();
+    const existing = this.windows.get(key);
+    if (existing && existing.resetAt > now) {
+      const updated = { count: existing.count + 1, resetAt: existing.resetAt };
+      this.windows.set(key, updated);
+      return updated;
+    }
+    this.sweep(now);
+    const fresh = { count: 1, resetAt: now + windowMs };
+    this.windows.set(key, fresh);
+    return fresh;
+  }
+
+  // Drops expired windows so the map doesn't grow forever.
+  private sweep(now: number): void {
+    for (const [key, window] of this.windows) {
+      if (window.resetAt <= now) {
+        this.windows.delete(key);
+      }
+    }
+  }
+}
+
+const DEFAULT_WINDOW_MS = 60_000;
+const DEFAULT_MAX_REQUESTS = 100;
+
+export interface RateLimitOptions {
+  windowMs?: number;
+  max?: number;
+  store?: RateLimitStore;
+}
+
+export function rateLimit(options: RateLimitOptions = {}) {
+  const windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
+  const max = options.max ?? DEFAULT_MAX_REQUESTS;
+  const store = options.store ?? new MemoryRateLimitStore();
+
+  return createMiddleware(async (c, next) => {
+    const key = clientKey(c);
+    const { count, resetAt } = await store.hit(key, windowMs);
+    const secondsToReset = Math.max(
+      0,
+      Math.ceil((resetAt - Date.now()) / 1000),
+    );
+
+    c.header("RateLimit-Limit", String(max));
+    c.header("RateLimit-Remaining", String(Math.max(0, max - count)));
+    c.header("RateLimit-Reset", String(secondsToReset));
+
+    if (count > max) {
+      const body: ErrorBody = {
+        error: {
+          code: "RATE_LIMITED",
+          message: "Too many requests, retry later",
+        },
+        requestId: c.get("requestId") ?? "",
+      };
+      return c.json(body, 429);
+    }
+    await next();
+  });
+}
+
+// Proxy header first, then the socket address. "unknown" only happens in tests.
+function clientKey(c: Context): string {
+  const forwarded = c.req.header("x-forwarded-for");
+  if (forwarded) {
+    return forwarded.split(",")[0]?.trim() ?? "unknown";
+  }
+  try {
+    return getConnInfo(c).remote.address ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}

package/templates/base/src/middleware/request-logger.ts

@@ -0,0 +1,21 @@
+import { createMiddleware } from "hono/factory";
+import { logger } from "../lib/logger.ts";
+
+/** One structured log line per request: method, path, status, duration, request ID. */
+export function requestLogger() {
+  return createMiddleware(async (c, next) => {
+    const startedAt = performance.now();
+    await next();
+    const durationMs = Math.round(performance.now() - startedAt);
+    logger.info(
+      {
+        requestId: c.get("requestId"),
+        method: c.req.method,
+        path: c.req.path,
+        status: c.res.status,
+        durationMs,
+      },
+      "request",
+    );
+  });
+}

package/templates/base/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noFallthroughCasesInSwitch": true,
+    "skipLibCheck": true,
+    "types": ["bun"]
+  },
+  "include": ["src"]
+}

package/templates/integrations/compose-postgres/files/docker-compose.yml

@@ -0,0 +1,15 @@
+services:
+  postgres:
+    image: postgres:17-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: app
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+
+volumes:
+  postgres-data:

package/templates/integrations/compose-postgres/manifest.json

@@ -0,0 +1,5 @@
+{
+  "name": "compose-postgres",
+  "description": "docker-compose service for local Postgres",
+  "readme": "## Local Postgres\n\n```sh\ndocker compose up -d\n```\n\nCredentials match the default `DATABASE_URL`."
+}

package/templates/integrations/db-postgres/files/src/db/client.ts

@@ -0,0 +1,7 @@
+import { SQL } from "bun";
+import { env } from "../config/env.ts";
+
+/**
+ * Bun's native Postgres client.
+ */
+export const sql = new SQL(env.DATABASE_URL);

package/templates/integrations/db-postgres/manifest.json

@@ -0,0 +1,18 @@
+{
+  "name": "db-postgres",
+  "description": "Postgres client using Bun's native SQL bindings (no dependencies)",
+  "env": [
+    {
+      "key": "DATABASE_URL",
+      "value": "postgres://postgres:postgres@localhost:5432/app"
+    }
+  ],
+  "inserts": [
+    {
+      "file": "src/config/env.ts",
+      "anchor": "// bono:env",
+      "line": "  DATABASE_URL: z.url(),"
+    }
+  ],
+  "readme": "## Database\n\n`sql` from `src/db/client.ts` (Bun's native Postgres client, no driver dep). Tagged templates are parameterized:\n\n```ts\nconst rows = await sql`select * from todos where id = ${id}`;\n```\n\nConnection string: `DATABASE_URL` in `.env`."
+}

package/templates/integrations/drizzle/files/drizzle.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  dialect: "postgresql",
+  schema: "./src/db/schema",
+  out: "./drizzle",
+  dbCredentials: {
+    // biome-ignore lint/style/noNonNullAssertion: fails loudly at CLI time if unset
+    url: process.env.DATABASE_URL!,
+  },
+});

package/templates/integrations/drizzle/files/src/db/index.ts

@@ -0,0 +1,8 @@
+import { drizzle } from "drizzle-orm/bun-sql";
+import { sql } from "./client.ts";
+import * as schema from "./schema/index.ts";
+
+/**
+ * Query through Drizzle
+ */
+export const db = drizzle({ client: sql, schema });

package/templates/integrations/drizzle/files/src/db/schema/index.ts

@@ -0,0 +1 @@
+export * from "./todos.ts";

package/templates/integrations/drizzle/files/src/db/schema/todos.ts

@@ -0,0 +1,10 @@
+import { boolean, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+
+// Example table mirroring the todos feature. Replace with your own tables;
+// each table gets its own file, exported from schema/index.ts.
+export const todos = pgTable("todos", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  title: text("title").notNull(),
+  completed: boolean("completed").notNull().default(false),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+});

package/templates/integrations/drizzle/manifest.json

@@ -0,0 +1,17 @@
+{
+  "name": "drizzle",
+  "description": "Drizzle ORM over the Bun Postgres client, with drizzle-kit migrations",
+  "dependencies": {
+    "drizzle-orm": "^0.44.0"
+  },
+  "devDependencies": {
+    "drizzle-kit": "^0.31.0",
+    "pg": "^8.16.0"
+  },
+  "scripts": {
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:push": "drizzle-kit push"
+  },
+  "readme": "## Drizzle\n\n`db` from `src/db/index.ts`. Tables go in `src/db/schema/`, one file per table, exported from `schema/index.ts`.\n\n```sh\nbun run db:generate   # migration from schema changes\nbun run db:migrate    # apply\n```\n\n`pg` is dev-only for drizzle-kit; the app uses Bun's native client."
+}