@donkeylabs/server 0.1.1 → 0.1.2

package/docs/cli.md

@@ -0,0 +1,353 @@
+# CLI & Scripts
+
+Command-line tools for managing plugins, generating types, and scaffolding code.
+
+## Quick Reference
+
+### Non-Interactive Commands (AI-Friendly)
+
+These commands run without prompts - ideal for automation and AI assistants:
+
+```sh
+# Create plugin with options
+bun scripts/create-plugin.ts --name myPlugin --schema --deps auth,cache
+bun scripts/create-plugin.ts --help  # Show all options
+
+# Create server file
+bun scripts/create-server.ts --name server.ts --port 3000 --plugins auth,users
+bun scripts/create-server.ts --help  # Show all options
+
+# Create migration
+bun scripts/create-migration.ts users add_avatar_column
+bun scripts/create-migration.ts --help  # Show usage
+
+# Generate types
+bun run gen:registry                           # Regenerate registry.d.ts
+bun run gen:server                             # Regenerate context.d.ts
+bun scripts/generate-types.ts <plugin>         # Generate schema types for plugin
+
+# Watch plugin for changes (runs watcher)
+bun scripts/watcher.ts <plugin>
+```
+
+### Interactive CLI
+
+For guided workflows with menus:
+
+```sh
+bun run cli
+```
+
+---
+
+## Non-Interactive Commands
+
+### Create Plugin
+
+```sh
+bun scripts/create-plugin.ts [options]
+
+Options:
+  --name <name>        Plugin name (required)
+  --schema             Include database schema (optional)
+  --config             Include configuration support (optional)
+  --deps <list>        Comma-separated dependencies (optional)
+  --handlers           Include custom handler template (optional)
+  --middleware         Include custom middleware template (optional)
+
+Examples:
+  # Simple plugin
+  bun scripts/create-plugin.ts --name analytics
+
+  # Plugin with schema and dependencies
+  bun scripts/create-plugin.ts --name orders --schema --deps auth,products
+
+  # Full-featured plugin
+  bun scripts/create-plugin.ts --name notifications --schema --config --deps auth --handlers --middleware
+```
+
+**Generated structure:**
+
+```
+plugins/myPlugin/
+├── index.ts          # Plugin definition
+├── schema.ts         # Database types (if --schema)
+└── migrations/       # Migration folder (if --schema)
+    └── 001_initial.ts
+```
+
+### Create Server
+
+```sh
+bun scripts/create-server.ts [options]
+
+Options:
+  --name <filename>    Output filename (default: server.ts)
+  --port <number>      Server port (default: 3000)
+  --plugins <list>     Comma-separated plugins to include
+
+Examples:
+  # Basic server
+  bun scripts/create-server.ts --name app.ts --port 8080
+
+  # Server with plugins
+  bun scripts/create-server.ts --name api.ts --port 3000 --plugins auth,users,orders
+```
+
+### Create Migration
+
+```sh
+bun scripts/create-migration.ts <plugin> <migration_name>
+
+Examples:
+  bun scripts/create-migration.ts users add_avatar_column
+  bun scripts/create-migration.ts orders add_status_index
+```
+
+**Generated file:** `plugins/<plugin>/migrations/002_add_avatar_column.ts`
+
+### Generate Types
+
+```sh
+# Regenerate all plugin/handler registry types
+bun run gen:registry
+
+# Regenerate server context types
+bun run gen:server
+
+# Generate schema types for a specific plugin
+bun scripts/generate-types.ts <plugin>
+
+Examples:
+  bun scripts/generate-types.ts users
+  bun scripts/generate-types.ts orders
+```
+
+### Watch Plugin
+
+```sh
+bun scripts/watch.ts <plugin>
+
+Examples:
+  bun scripts/watch.ts auth
+  bun scripts/watch.ts orders
+```
+
+Watches for changes and auto-regenerates types.
+
+---
+
+## Interactive CLI
+
+Launch the interactive menu:
+
+```sh
+bun run cli
+```
+
+### From Project Root
+
+```
+Plugin CLI
+
+Context: Project Root
+
+? Select a command:
+  1. Create New Plugin
+  2. Create New Server
+  ─────────────────────────
+  3. Publish Plugin Version
+  4. Install Plugin from Global
+  ─────────────────────────
+  5. Generate Registry
+  6. Watch Plugin
+  ─────────────────────────
+  × Exit
+```
+
+### From Plugin Directory
+
+When running from inside `plugins/<name>/`:
+
+```
+Plugin CLI
+
+Context: Plugin 'auth'
+
+? What would you like to do?
+  1. Live Watch
+  2. Generate Schema Types
+  3. Create Migration
+  4. Publish New Version
+  ─────────────────────────
+  ← Back to Global Menu
+  × Exit
+```
+
+---
+
+## Package.json Scripts
+
+Add these to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "cli": "bun scripts/cli.ts",
+    "gen:registry": "bun scripts/generate-registry.ts",
+    "gen:server": "bun scripts/generate-server.ts",
+    "dev": "bun --watch index.ts",
+    "test": "bun test",
+    "typecheck": "bun --bun tsc --noEmit"
+  }
+}
+```
+
+---
+
+## Global Plugin Registry
+
+Share plugins across projects using the global registry.
+
+### Publish Plugin
+
+```sh
+# Interactive
+bun run cli
+# Select: Publish Plugin Version
+
+# Non-interactive (from plugin directory)
+bun scripts/publish.ts --version 1.0.0
+```
+
+### Install Plugin
+
+```sh
+# Interactive
+bun run cli
+# Select: Install Plugin from Global
+
+# Non-interactive
+bun scripts/install.ts --name auth --version latest
+```
+
+### Check for Updates
+
+The CLI automatically checks for updates when opened and shows:
+
+```
+Updates Available:
+  auth: 1.0.0 → 1.1.0
+  users: 2.0.0 → 2.1.0
+```
+
+---
+
+## Workflow Examples
+
+### Creating a New Feature
+
+```sh
+# 1. Create the plugin
+bun scripts/create-plugin.ts --name orders --schema --deps auth,products
+
+# 2. Edit the generated files
+#    - plugins/orders/index.ts (service logic)
+#    - plugins/orders/migrations/001_initial.ts (database schema)
+
+# 3. Generate types
+bun run gen:registry
+
+# 4. Start watching for changes
+bun scripts/watch.ts orders
+
+# 5. Add routes and test
+```
+
+### Adding Database Changes
+
+```sh
+# 1. Create migration
+bun scripts/create-migration.ts orders add_shipping_address
+
+# 2. Edit the migration file
+#    - plugins/orders/migrations/002_add_shipping_address.ts
+
+# 3. Regenerate schema types
+bun scripts/generate-types.ts orders
+
+# 4. Update service code to use new columns
+```
+
+### Setting Up a New Project
+
+```sh
+# 1. Initialize project
+mkdir my-api && cd my-api
+bun init
+
+# 2. Install dependencies
+bun add kysely zod
+
+# 3. Copy framework files or install from template
+
+# 4. Create initial plugins
+bun scripts/create-plugin.ts --name auth --schema
+bun scripts/create-plugin.ts --name users --schema --deps auth
+
+# 5. Generate registry
+bun run gen:registry
+
+# 6. Create server
+bun scripts/create-server.ts --name index.ts --port 3000 --plugins auth,users
+
+# 7. Start development
+bun --watch index.ts
+```
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `INIT_CWD` | Original directory when running via `bun run` |
+| `GLOBAL_REGISTRY_PATH` | Path to global plugin registry |
+
+---
+
+## Troubleshooting
+
+### "Plugin not found" after creation
+
+```sh
+bun run gen:registry
+```
+
+### Types not updating
+
+```sh
+# Regenerate all types
+bun run gen:registry
+bun run gen:server
+
+# Restart TypeScript server in your IDE
+# VS Code: Cmd+Shift+P > "TypeScript: Restart TS Server"
+```
+
+### Migration not running
+
+Check that migration file exports `up` and `down` functions:
+
+```ts
+export async function up(db: Kysely<any>): Promise<void> { ... }
+export async function down(db: Kysely<any>): Promise<void> { ... }
+```
+
+### Watch mode not detecting changes
+
+Ensure you're watching the correct plugin:
+
+```sh
+bun scripts/watch.ts <exact-plugin-name>
+```

package/docs/core-services.md

@@ -0,0 +1,338 @@
+# Core Services
+
+Core services are foundational utilities automatically available to all plugins and route handlers via `ctx.core`. They provide essential functionality like logging, caching, background jobs, and real-time communication.
+
+## Available Services
+
+| Service | Purpose | Default Backend |
+|---------|---------|-----------------|
+| [Logger](logger.md) | Structured logging with levels | Console |
+| [Cache](cache.md) | Key-value store with TTL | In-memory (LRU) |
+| [Events](events.md) | Pub/sub event system | In-memory |
+| [Cron](cron.md) | Scheduled recurring tasks | In-memory |
+| [Jobs](jobs.md) | Background job queue | In-memory |
+| [SSE](sse.md) | Server-Sent Events | In-memory |
+| [RateLimiter](rate-limiter.md) | Request throttling | In-memory |
+| [Errors](errors.md) | HTTP error factories | - |
+
+---
+
+## Accessing Core Services
+
+### In Route Handlers
+
+```ts
+router.route("example").typed({
+  handle: async (input, ctx) => {
+    // All services available via ctx.core
+    ctx.core.logger.info("Processing request", { input });
+
+    const cached = await ctx.core.cache.get("key");
+
+    await ctx.core.events.emit("request.processed", { input });
+
+    return { success: true };
+  },
+});
+```
+
+### In Plugins
+
+```ts
+createPlugin.define({
+  name: "myPlugin",
+  service: async (ctx) => {
+    // Schedule background work
+    ctx.core.cron.schedule("0 * * * *", () => {
+      ctx.core.logger.info("Hourly task running");
+    });
+
+    // Register job handler
+    ctx.core.jobs.register("sendEmail", async (data) => {
+      // Process in background
+    });
+
+    // Subscribe to events
+    ctx.core.events.on("user.created", async (user) => {
+      await ctx.core.jobs.enqueue("sendEmail", {
+        to: user.email,
+        template: "welcome",
+      });
+    });
+
+    return { /* service methods */ };
+  },
+});
+```
+
+### In Middleware
+
+```ts
+createMiddleware(async (req, ctx, next, config) => {
+  const start = Date.now();
+
+  const response = await next();
+
+  ctx.core.logger.info("Request completed", {
+    method: req.method,
+    path: new URL(req.url).pathname,
+    duration: Date.now() - start,
+    status: response.status,
+  });
+
+  return response;
+});
+```
+
+---
+
+## CoreServices Interface
+
+```ts
+interface CoreServices {
+  db: Kysely<any>;           // Database connection
+  config: Record<string, any>; // Global config
+
+  // Utility services
+  logger: Logger;
+  cache: Cache;
+  events: Events;
+  cron: Cron;
+  jobs: Jobs;
+  sse: SSE;
+  rateLimiter: RateLimiter;
+  errors: Errors;            // HTTP error factories
+}
+```
+
+---
+
+## Configuration
+
+Configure services when creating the server:
+
+```ts
+import { AppServer } from "./server";
+
+const server = new AppServer({
+  db: database,
+  port: 3000,
+
+  // Service configurations (all optional)
+  logger: {
+    level: "debug",        // "debug" | "info" | "warn" | "error"
+    format: "pretty",      // "pretty" | "json"
+  },
+
+  cache: {
+    defaultTtlMs: 300000,  // 5 minutes
+    maxSize: 10000,        // LRU max items
+  },
+
+  events: {
+    maxHistorySize: 1000,  // Event history limit
+  },
+
+  cron: {
+    timezone: "UTC",       // For future use
+  },
+
+  jobs: {
+    concurrency: 5,        // Max parallel jobs
+    pollInterval: 1000,    // Check interval (ms)
+    maxAttempts: 3,        // Default retries
+  },
+
+  sse: {
+    heartbeatInterval: 30000,  // Keep-alive interval
+    retryInterval: 3000,       // Client reconnect hint
+  },
+
+  rateLimiter: {
+    // Uses in-memory by default
+  },
+});
+```
+
+---
+
+## Service Lifecycle
+
+### Startup
+
+When `server.start()` is called:
+
+1. All services are already initialized (in constructor)
+2. Cron scheduler starts (`cron.start()`)
+3. Job processor starts (`jobs.start()`)
+4. Server begins accepting requests
+
+### Shutdown
+
+When `server.shutdown()` is called:
+
+1. SSE connections are closed
+2. Job processor stops (waits for active jobs)
+3. Cron scheduler stops
+
+```ts
+// Graceful shutdown
+process.on("SIGTERM", async () => {
+  await server.shutdown();
+  process.exit(0);
+});
+```
+
+---
+
+## Common Patterns
+
+### Caching Database Queries
+
+```ts
+async function getUser(id: number, ctx: ServerContext) {
+  return ctx.core.cache.getOrSet(
+    `user:${id}`,
+    () => ctx.db.selectFrom("users").where("id", "=", id).executeTakeFirst(),
+    60000 // 1 minute TTL
+  );
+}
+```
+
+### Event-Driven Architecture
+
+```ts
+// In plugin: emit events
+service: async (ctx) => ({
+  async createOrder(data) {
+    const order = await ctx.db.insertInto("orders").values(data).execute();
+    await ctx.core.events.emit("order.created", order);
+    return order;
+  },
+});
+
+// In another plugin: react to events
+service: async (ctx) => {
+  ctx.core.events.on("order.created", async (order) => {
+    await ctx.core.jobs.enqueue("sendOrderConfirmation", order);
+    await ctx.core.jobs.enqueue("updateInventory", order.items);
+  });
+};
+```
+
+### Rate Limiting Routes
+
+```ts
+router.route("api").typed({
+  handle: async (input, ctx) => {
+    const result = await ctx.core.rateLimiter.check(
+      `api:${ctx.ip}`,
+      100,    // 100 requests
+      60000   // per minute
+    );
+
+    if (!result.allowed) {
+      throw new Error(`Rate limited. Retry in ${result.retryAfter}s`);
+    }
+
+    // Process request...
+  },
+});
+```
+
+### Real-Time Updates with SSE
+
+```ts
+// Route to establish SSE connection
+router.route("subscribe").raw({
+  handle: async (req, ctx) => {
+    const { client, response } = ctx.core.sse.addClient();
+
+    // Subscribe to user's channel
+    ctx.core.sse.subscribe(client.id, `user:${ctx.user.id}`);
+
+    return response;
+  },
+});
+
+// Broadcast updates from anywhere
+ctx.core.sse.broadcast(`user:${userId}`, "notification", {
+  message: "You have a new message",
+});
+```
+
+### Background Job Processing
+
+```ts
+// Register handler in plugin
+ctx.core.jobs.register("processImage", async (data) => {
+  const { imageId, operations } = data;
+  // Heavy processing...
+  return { processed: true };
+});
+
+// Enqueue from route handler
+router.route("upload").typed({
+  handle: async (input, ctx) => {
+    const image = await saveImage(input.file);
+
+    // Process in background
+    await ctx.core.jobs.enqueue("processImage", {
+      imageId: image.id,
+      operations: ["resize", "optimize"],
+    });
+
+    return { imageId: image.id, status: "processing" };
+  },
+});
+```
+
+---
+
+## Testing with Core Services
+
+The test harness automatically creates all core services:
+
+```ts
+import { createTestHarness } from "./harness";
+
+const { core } = await createTestHarness(myPlugin);
+
+// All services available
+core.logger.info("Test starting");
+await core.cache.set("test", "value");
+await core.events.emit("test.event", { data: 1 });
+
+// Jobs and cron are created but not started
+// Call manually if needed:
+core.jobs.start();
+core.cron.start();
+```
+
+---
+
+## Custom Adapters
+
+Each service supports custom adapters for different backends:
+
+```ts
+import { createCache, type CacheAdapter } from "./core/cache";
+
+// Implement custom adapter (e.g., Redis)
+class RedisCacheAdapter implements CacheAdapter {
+  async get<T>(key: string): Promise<T | null> { /* ... */ }
+  async set<T>(key: string, value: T, ttlMs?: number): Promise<void> { /* ... */ }
+  // ... other methods
+}
+
+// Use custom adapter
+const cache = createCache({
+  adapter: new RedisCacheAdapter(redisClient),
+});
+```
+
+See individual service documentation for adapter interfaces:
+- [Cache Adapters](cache.md#custom-adapters)
+- [Events Adapters](events.md#custom-adapters)
+- [Jobs Adapters](jobs.md#custom-adapters)
+- [Rate Limiter Adapters](rate-limiter.md#custom-adapters)