@donkeylabs/server 0.1.0 → 0.1.1

package/cli/commands/init.ts

@@ -4,9 +4,10 @@
  * Initialize a new @donkeylabs/server project with proper database setup.
  */
 
-import { mkdir, writeFile, readFile, readdir } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { mkdir, writeFile, readFile, readdir, copyFile } from "node:fs/promises";
+import { join, resolve, dirname } from "node:path";
 import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import pc from "picocolors";
 import prompts from "prompts";
 
@@ -96,6 +97,14 @@ export async function initCommand(args: string[]): Promise<void> {
   );
   console.log(pc.green("  Created:"), "src/index.ts");
 
+  // Copy docs and create CLAUDE.md for AI assistants
+  await copyDocsToProject(targetDir);
+  await writeFile(
+    join(targetDir, "CLAUDE.md"),
+    generateClaudeMd(options.projectName)
+  );
+  console.log(pc.green("  Created:"), "CLAUDE.md + docs/");
+
   // Update .gitignore
   const gitignorePath = join(targetDir, ".gitignore");
   const gitignoreContent = existsSync(gitignorePath)
@@ -130,11 +139,12 @@ export async function initCommand(args: string[]): Promise<void> {
 
   // Update package.json
   const pkgPath = join(targetDir, "package.json");
-  let pkg: any = { name: options.projectName, type: "module", scripts: {} };
+  let pkg: any = { name: options.projectName, type: "module", scripts: {}, dependencies: {} };
 
   if (existsSync(pkgPath)) {
     pkg = JSON.parse(await readFile(pkgPath, "utf-8"));
     pkg.scripts = pkg.scripts || {};
+    pkg.dependencies = pkg.dependencies || {};
   }
 
   pkg.name = pkg.name || options.projectName;
@@ -143,8 +153,20 @@ export async function initCommand(args: string[]): Promise<void> {
   pkg.scripts.start = "bun src/index.ts";
   pkg.scripts["gen:types"] = "donkeylabs generate";
 
+  // Add dependencies
+  pkg.dependencies["@donkeylabs/server"] = "latest";
+  pkg.dependencies["kysely"] = "^0.27.0";
+  pkg.dependencies["zod"] = "^3.24.0";
+  if (options.useDatabase) {
+    pkg.dependencies["kysely-bun-sqlite"] = "^0.3.0";
+  }
+
+  // Add dev dependencies
+  pkg.devDependencies = pkg.devDependencies || {};
+  pkg.devDependencies["@types/bun"] = "latest";
+
   await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
-  console.log(pc.green("  Updated:"), "package.json");
+  console.log(pc.green("  Created:"), "package.json");
 
   // Print next steps
   console.log(`
@@ -152,17 +174,13 @@ ${pc.bold(pc.green("Success!"))} Project initialized.
 
 ${pc.bold("Next steps:")}
   1. Install dependencies:
-     ${pc.cyan(getDependencyCommand(options.useDatabase))}
+     ${pc.cyan("bun install")}
 ${options.useDatabase ? `
   2. Set up your database:
      ${pc.cyan(`cp .env.example .env`)}
-     ${pc.dim("# Edit .env with your database path")}
 ` : ""}
   ${options.useDatabase ? "3" : "2"}. Start development:
      ${pc.cyan("bun run dev")}
-
-  ${options.useDatabase ? "4" : "3"}. Generate types after adding plugins:
-     ${pc.cyan("bun run gen:types")}
 `);
 }
 
@@ -281,7 +299,178 @@ function generateTsConfig(): string {
 `;
 }
 
-function getDependencyCommand(useDatabase: boolean): string {
-  const base = "bun add @donkeylabs/server kysely zod";
-  return useDatabase ? `${base} kysely-bun-sqlite` : base;
+// Docs to copy to user projects (subset relevant for users)
+const USER_DOCS = [
+  "plugins.md",
+  "router.md",
+  "handlers.md",
+  "core-services.md",
+  "errors.md",
+  "cache.md",
+  "logger.md",
+  "events.md",
+  "jobs.md",
+  "cron.md",
+  "sse.md",
+  "rate-limiter.md",
+  "middleware.md",
+  "api-client.md",
+  "svelte-frontend.md",
+];
+
+async function copyDocsToProject(targetDir: string): Promise<void> {
+  const docsDir = join(targetDir, "docs");
+  await mkdir(docsDir, { recursive: true });
+
+  // Find the package's docs directory
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = dirname(__filename);
+  const packageDocsDir = resolve(__dirname, "../../docs");
+
+  for (const doc of USER_DOCS) {
+    const srcPath = join(packageDocsDir, doc);
+    const destPath = join(docsDir, doc);
+
+    if (existsSync(srcPath)) {
+      await copyFile(srcPath, destPath);
+    }
+  }
+}
+
+function generateClaudeMd(projectName: string): string {
+  return `# ${projectName}
+
+Built with @donkeylabs/server - a type-safe RPC framework for Bun.
+
+## Project Structure
+
+\`\`\`
+src/
+├── index.ts          # Server entry + routes (start here)
+├── db.ts             # Database setup
+└── plugins/          # Your plugins
+    └── example/
+        ├── index.ts      # Plugin definition
+        ├── schema.ts     # DB types (if needed)
+        └── migrations/   # SQL migrations
+docs/                 # Framework documentation
+\`\`\`
+
+## Quick Start
+
+See \`src/index.ts\` for a working example with routes.
+
+## 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 handle HTTP requests and call plugin services.
+
+\`\`\`ts
+const router = createRouter("notes")
+  .route("create").typed({
+    input: z.object({ title: z.string() }),
+    handle: async (input, ctx) => ctx.plugins.notes.create(input.title),
+  });
+\`\`\`
+
+→ See **docs/router.md** for typed handlers, raw handlers, and middleware.
+
+## Handlers
+
+Two types: \`typed\` (validated JSON) and \`raw\` (full Request/Response).
+
+→ See **docs/handlers.md** for input/output validation and error handling.
+
+## 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 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donkeylabs/server",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Type-safe plugin system for building RPC-style APIs with Bun",
   "main": "./src/index.ts",