@donkeylabs/cli 0.1.0

package/src/index.ts

@@ -0,0 +1,108 @@
+#!/usr/bin/env bun
+/**
+ * @donkeylabs/cli
+ *
+ * Commands:
+ *   init        Initialize a new project
+ *   generate    Generate types (registry, context, client)
+ *   plugin      Plugin management (create, list)
+ */
+
+import { parseArgs } from "node:util";
+import pc from "picocolors";
+
+const { positionals, values } = parseArgs({
+  args: process.argv.slice(2),
+  options: {
+    help: { type: "boolean", short: "h" },
+    version: { type: "boolean", short: "v" },
+    type: { type: "string", short: "t" },
+  },
+  allowPositionals: true,
+});
+
+const command = positionals[0];
+
+function printHelp() {
+  console.log(`
+${pc.bold("@donkeylabs/cli")} - CLI for @donkeylabs/server
+
+${pc.bold("Usage:")}
+  donkeylabs                    Interactive menu
+  donkeylabs <command> [options]
+
+${pc.bold("Commands:")}
+  ${pc.cyan("init")}         Initialize a new project
+  ${pc.cyan("generate")}     Generate types (registry, context, client)
+  ${pc.cyan("plugin")}       Plugin management
+
+${pc.bold("Options:")}
+  -h, --help              Show this help message
+  -v, --version           Show version number
+  -t, --type <type>       Project type for init (server, sveltekit)
+
+${pc.bold("Examples:")}
+  donkeylabs                       # Interactive menu
+  donkeylabs init                  # Interactive project setup
+  donkeylabs init --type server    # Server-only project
+  donkeylabs init --type sveltekit # SvelteKit + adapter project
+  donkeylabs generate
+  donkeylabs plugin create myPlugin
+`);
+}
+
+function printVersion() {
+  // Read from package.json
+  console.log("0.1.0");
+}
+
+async function main() {
+  if (values.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (values.version) {
+    printVersion();
+    process.exit(0);
+  }
+
+  // No command provided - launch interactive mode
+  if (!command) {
+    const { interactiveCommand } = await import("./commands/interactive");
+    await interactiveCommand();
+    return;
+  }
+
+  switch (command) {
+    case "init":
+      const { initCommand } = await import("./commands/init");
+      const initArgs = [...positionals.slice(1)];
+      if (values.type) {
+        initArgs.push("--type", values.type);
+      }
+      await initCommand(initArgs);
+      break;
+
+    case "generate":
+    case "gen":
+      const { generateCommand } = await import("./commands/generate");
+      await generateCommand(positionals.slice(1));
+      break;
+
+    case "plugin":
+      const { pluginCommand } = await import("./commands/plugin");
+      await pluginCommand(positionals.slice(1));
+      break;
+
+    default:
+      console.error(pc.red(`Unknown command: ${command}`));
+      console.log(`Run ${pc.cyan("donkeylabs --help")} for available commands.`);
+      process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error(pc.red("Error:"), error.message);
+  process.exit(1);
+});

package/templates/starter/.env.example

@@ -0,0 +1,3 @@
+DATABASE_URL=app.db
+PORT=3000
+NODE_ENV=development

package/templates/starter/.gitignore.template

@@ -0,0 +1,4 @@
+node_modules/
+.@donkeylabs/
+*.db
+.env

package/templates/starter/CLAUDE.md

@@ -0,0 +1,144 @@
+# {{PROJECT_NAME}}
+
+Built with @donkeylabs/server - a type-safe RPC framework for Bun.
+
+## Project Structure
+
+```
+src/
+├── index.ts              # Server entry point
+├── db.ts                 # Database setup
+├── routes/               # Route handlers
+│   └── health/
+│       ├── index.ts      # Route definitions
+│       └── ping/
+│           ├── handler.ts
+│           ├── models/
+│           │   └── model.ts  # Input/output schemas
+│           └── tests/
+│               ├── unit.test.ts
+│               └── integ.test.ts
+└── plugins/              # Business logic plugins
+    └── example/
+        ├── index.ts      # Plugin definition
+        ├── schema.ts     # DB types
+        └── migrations/   # SQL migrations
+docs/                     # Framework documentation
+```
+
+## Quick Start
+
+See `src/routes/health/ping/` for a complete example with handler, model, and tests.
+
+## Plugins
+
+Plugins encapsulate business logic with optional database schemas.
+
+```ts
+import { createPlugin } from "@donkeylabs/server";
+
+export const notesPlugin = createPlugin.define({
+  name: "notes",
+  service: async (ctx) => ({
+    async create(title: string) {
+      return ctx.db.insertInto("notes").values({ title }).execute();
+    },
+  }),
+});
+```
+
+→ See **docs/plugins.md** for schemas, migrations, and dependencies.
+
+## Routes
+
+Routes are organized by feature in `src/routes/`. Each route has:
+- `handler.ts` - Handler logic
+- `models/model.ts` - Zod schemas for input/output
+- `tests/unit.test.ts` - Unit tests
+- `tests/integ.test.ts` - Integration tests
+
+```ts
+// routes/notes/index.ts
+import { createRouter } from "@donkeylabs/server";
+import { createHandler } from "./create/handler";
+
+export const notesRouter = createRouter("notes")
+  .route("create").typed(createHandler);
+```
+
+→ See **docs/router.md** and **src/routes/health/** for examples.
+
+## Errors
+
+Use built-in error factories for proper HTTP responses.
+
+```ts
+throw ctx.errors.NotFound("User not found");
+throw ctx.errors.BadRequest("Invalid email");
+```
+
+→ See **docs/errors.md** for all error types and custom errors.
+
+## Core Services
+
+Available via `ctx.core`. **Only use what you need.**
+
+| Service | Purpose | Docs |
+|---------|---------|------|
+| `logger` | Structured logging | docs/logger.md |
+| `cache` | In-memory key-value cache | docs/cache.md |
+| `events` | Pub/sub between plugins | docs/events.md |
+| `jobs` | Background job queue | docs/jobs.md |
+| `cron` | Scheduled tasks | docs/cron.md |
+| `sse` | Server-sent events | docs/sse.md |
+| `rateLimiter` | Request rate limiting | docs/rate-limiter.md |
+
+→ See **docs/core-services.md** for overview.
+
+## Middleware
+
+Add authentication, logging, or other cross-cutting concerns.
+
+→ See **docs/middleware.md** for usage patterns.
+
+## API Client
+
+Generate a typed client for your frontend:
+
+```sh
+bun run gen:client --output ./frontend/src/lib/api
+```
+
+→ See **docs/api-client.md** for client configuration and usage.
+
+## Svelte 5 Frontend
+
+Build type-safe frontends with Svelte 5 and SvelteKit.
+
+```svelte
+<script lang="ts">
+  import { api } from "$lib/api";
+  let items = $state<Item[]>([]);
+
+  $effect(() => {
+    api.items.list({}).then((r) => items = r.items);
+  });
+</script>
+```
+
+→ See **docs/svelte-frontend.md** for patterns and SSE integration.
+
+## CLI Commands
+
+```sh
+bun run dev          # Start with hot reload
+bun run test         # Run tests
+bun run gen:types    # Generate types after adding plugins
+```
+
+## Guidelines
+
+- **Keep it simple** - don't add services you don't need
+- **One concern per plugin** - auth, notes, billing as separate plugins
+- **Minimal logging** - log errors and key events, not every call
+- **Read the docs** - check docs/*.md before implementing something complex

package/templates/starter/donkeylabs.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from "@donkeylabs/server";
+
+export default defineConfig({
+  plugins: ["./src/plugins/**/index.ts"],
+  outDir: ".@donkeylabs/server",
+});

package/templates/starter/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "my-donkeylabs-app",
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "dev": "bun --watch src/index.ts",
+    "start": "bun src/index.ts",
+    "test": "bun test",
+    "gen:types": "donkeylabs generate"
+  },
+  "dependencies": {
+    "@donkeylabs/server": "*",
+    "kysely": "^0.27.0",
+    "kysely-bun-sqlite": "^0.3.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@donkeylabs/cli": "*",
+    "@types/bun": "latest"
+  }
+}

package/templates/starter/src/client.test.ts

@@ -0,0 +1,7 @@
+import { createApiClient } from "$server/client"
+
+
+const client = createApiClient("http://localhost:3000", {})
+
+client.api.health.ping({}).then(console.log)
+

package/templates/starter/src/db.ts

@@ -0,0 +1,9 @@
+import { Kysely } from "kysely";
+import { BunSqliteDialect } from "kysely-bun-sqlite";
+import { Database } from "bun:sqlite";
+
+export const db = new Kysely<any>({
+  dialect: new BunSqliteDialect({
+    database: new Database("app.db"),
+  }),
+});

package/templates/starter/src/index.ts

@@ -0,0 +1,48 @@
+import { db } from "./db";
+import { AppServer } from "@donkeylabs/server";
+import { healthRouter } from "./routes/health";
+import { statsPlugin } from "./plugins/stats";
+import { z } from "zod";
+
+const server = new AppServer({
+  port: Number(process.env.PORT) || 3000,
+  db,
+  config: { env: process.env.NODE_ENV || "development" },
+});
+
+// Register plugins
+server.registerPlugin(statsPlugin);
+
+// Register routes with middleware applied at router level
+
+const api = server.router("api")
+.middleware
+.timing()
+
+const hello = api.router("hello")
+hello.route("test").typed({
+  input: z.string(),
+  output: z.string(),
+  handle: (input, ctx) => {
+    // ctx.plugins.stats should now be typed correctly
+    const stats = ctx.plugins.stats;
+    return input;
+  }
+}).route("ping").typed({
+  input: z.string(),
+  output: z.string(),
+  handle: (input, ctx) => {
+    return input;
+  }
+})
+.route("pong").typed({
+  input: z.string(),
+  output: z.string(),
+  handle: (input, ctx) => {
+    return input;
+  }
+})
+
+api.router(healthRouter)
+
+await server.start();

package/templates/starter/src/plugins/stats/index.ts

@@ -0,0 +1,105 @@
+import { createPlugin, createMiddleware } from "@donkeylabs/server";
+
+export interface RequestStats {
+  totalRequests: number;
+  avgResponseTime: number;
+  minResponseTime: number;
+  maxResponseTime: number;
+  requestsPerRoute: Map<string, number>;
+}
+
+export interface StatsService {
+  /** Record a request with its duration */
+  recordRequest(route: string, durationMs: number): void;
+  /** Get current stats snapshot */
+  getStats(): RequestStats;
+  /** Reset all stats */
+  reset(): void;
+}
+
+export const statsPlugin = createPlugin.define({
+  name: "stats",
+  version: "1.0.0",
+
+  // Service must come before middleware for TypeScript to infer the Service type
+  service: async (ctx): Promise<StatsService> => {
+    const logger = ctx.core.logger.child({ plugin: "stats" });
+
+    // In-memory stats
+    let totalRequests = 0;
+    let totalTime = 0;
+    let minTime = Infinity;
+    let maxTime = 0;
+    const requestsPerRoute = new Map<string, number>();
+
+    function getStats(): RequestStats {
+      return {
+        totalRequests,
+        avgResponseTime: totalRequests > 0 ? totalTime / totalRequests : 0,
+        minResponseTime: minTime,
+        maxResponseTime: maxTime,
+        requestsPerRoute: new Map(requestsPerRoute),
+      };
+    }
+
+    logger.info("Stats plugin initialized");
+
+    return {
+      recordRequest(route: string, durationMs: number) {
+        totalRequests++;
+        totalTime += durationMs;
+        minTime = Math.min(minTime, durationMs);
+        maxTime = Math.max(maxTime, durationMs);
+        requestsPerRoute.set(route, (requestsPerRoute.get(route) ?? 0) + 1);
+
+        logger.debug("Request recorded", { route, durationMs: durationMs.toFixed(2) });
+      },
+
+      getStats,
+
+      reset() {
+        totalRequests = 0;
+        totalTime = 0;
+        minTime = Infinity;
+        maxTime = 0;
+        requestsPerRoute.clear();
+        logger.info("Stats reset");
+      },
+    };
+  },
+
+  // Middleware - ctx is typed PluginContext, service is typed StatsService
+  middleware: (ctx, service) => ({
+    /** Timing middleware - records request duration and updates stats */
+    timing: createMiddleware(async (req, _reqCtx, next) => {
+      const logger = ctx.core.logger;
+      const route = new URL(req.url).pathname.slice(1);
+      const start = performance.now();
+      const response = await next();
+      const duration = performance.now() - start;
+
+      // Use own service to record stats - service is typed!
+      service.recordRequest(route, duration);
+      logger.info("Request processed", { route, durationMs: duration.toFixed(2) });
+
+      return response;
+    }),
+  }),
+
+  // Register crons, events, etc. after service is created
+  init: (ctx, service) => {
+    const logger = ctx.core.logger.child({ plugin: "stats" });
+
+    // Log stats every minute
+    ctx.core.cron.schedule("* * * * *", () => {
+      const stats = service.getStats();
+      logger.info("Server stats", {
+        requests: stats.totalRequests,
+        avgMs: stats.avgResponseTime.toFixed(2),
+        minMs: stats.minResponseTime === Infinity ? 0 : stats.minResponseTime.toFixed(2),
+        maxMs: stats.maxResponseTime.toFixed(2),
+        routes: Object.fromEntries(stats.requestsPerRoute),
+      });
+    }, { name: "stats-reporter" });
+  },
+});

package/templates/starter/src/routes/health/index.ts

@@ -0,0 +1,5 @@
+import { createRouter } from "@donkeylabs/server";
+import { pingRoute } from "./ping";
+
+export const healthRouter = createRouter("health")
+  .route("ping").typed(pingRoute);

package/templates/starter/src/routes/health/ping/index.ts

@@ -0,0 +1,13 @@
+// Route definition with full type inference
+import { createRoute } from "@donkeylabs/server";
+import { Input, Output } from "./schema";
+import { PingModel } from "./models/model";
+
+export const pingRoute = createRoute.typed({
+  input: Input,
+  output: Output,
+  handle: async (input, ctx) => {
+    const model = new PingModel(ctx);
+    return model.handle(input);
+  },
+});

package/templates/starter/src/routes/health/ping/models/model.ts

@@ -0,0 +1,23 @@
+// After running `bun run gen:types`, use typed Handler:
+import { Handler } from "@donkeylabs/server";
+import type { Health } from "$server/routes";
+import { AppContext } from "$server/context";
+
+/**
+ * Model class with handler logic.
+ */
+export class PingModel implements Handler<Health.Ping> {
+  ctx: AppContext;
+
+  constructor(ctx: AppContext) {
+    this.ctx = ctx;
+  }
+
+  handle(input: Health.Ping.Input): Health.Ping.Output {
+    return {
+      status: "ok",
+      timestamp: new Date().toISOString(),
+      echo: input.echo,
+    };
+  }
+}

package/templates/starter/src/routes/health/ping/schema.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+
+export const Input = z.object({
+  echo: z.string().optional(),
+});
+
+export const Output = z.object({
+  status: z.literal("ok"),
+  timestamp: z.string(),
+  echo: z.string().optional(),
+});
+
+export type Input = z.infer<typeof Input>;
+export type Output = z.infer<typeof Output>;

package/templates/starter/src/routes/health/ping/tests/integ.test.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from "bun:test";
+import type { Output } from "../models/model";
+
+const BASE_URL = "http://localhost:3000";
+
+describe("health/ping integration", () => {
+  // Note: Server must be running for integration tests
+  // Run with: bun run dev & bun test src/routes/health/ping/tests/integ.test.ts
+
+  it("POST /health.ping returns ok", async () => {
+    const res = await fetch(`${BASE_URL}/health.ping`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    expect(res.ok).toBe(true);
+    const data = (await res.json()) as Output;
+    expect(data.status).toBe("ok");
+  });
+});

package/templates/starter/src/routes/health/ping/tests/unit.test.ts

@@ -0,0 +1,21 @@
+import { describe, it, expect } from "bun:test";
+import { PingModel } from "../models/model";
+import { Input } from "../schema";
+
+describe("health/ping model", () => {
+  it("returns ok status", () => {
+    const input = Input.parse({});
+    const ctx = {} as any;
+    const model = new PingModel(ctx);
+    const result = model.handle(input);
+    expect(result.status).toBe("ok");
+  });
+
+  it("echoes input", () => {
+    const input = Input.parse({ echo: "hello" });
+    const ctx = {} as any;
+    const model = new PingModel(ctx);
+    const result = model.handle(input);
+    expect(result.echo).toBe("hello");
+  });
+});

package/templates/starter/src/test-ctx.ts

@@ -0,0 +1,24 @@
+/// <reference path="../.@donkeylabs/server/registry.d.ts" />
+// Test that ctx.plugins.stats is typed correctly
+import type { ServerContext, InferService } from "@donkeylabs/server";
+import { statsPlugin } from "./plugins/stats";
+import type { StatsService } from "./plugins/stats";
+
+// Verify InferService works correctly
+type InferredService = InferService<typeof statsPlugin>;
+
+// This type assertion verifies that InferredService equals StatsService
+const _typeCheck: InferredService extends StatsService
+  ? StatsService extends InferredService
+    ? true
+    : false
+  : false = true;
+
+// Verify ctx.plugins.stats is typed as StatsService
+declare const ctx: ServerContext;
+const stats: StatsService = ctx.plugins.stats;  // Should compile without error
+
+// These methods should all work
+stats.recordRequest("test", 100);
+stats.getStats();
+stats.reset();

package/templates/starter/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "lib": [
+      "ESNext"
+    ],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "preserveSymlinks": true,
+    "baseUrl": ".",
+    "paths": {
+      "$server/*": [".@donkeylabs/server/*"],
+      "$api": [".@donkeylabs/server/client"]
+    }
+  },
+  "include": [
+    "src",
+    ".@donkeylabs/server"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/templates/sveltekit-app/.env.example

@@ -0,0 +1,3 @@
+PORT=3000
+DATABASE_URL=app.db
+NODE_ENV=development