@donkeylabs/server 0.1.3 → 0.1.4

package/examples/starter/node_modules/@donkeylabs/server/cli/commands/init.ts

@@ -0,0 +1,476 @@
+/**
+ * Init Command
+ *
+ * Initialize a new @donkeylabs/server project with proper database setup.
+ */
+
+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";
+
+interface InitOptions {
+  projectName: string;
+  useDatabase: boolean;
+}
+
+export async function initCommand(args: string[]): Promise<void> {
+  const projectDir = args[0] || ".";
+  const targetDir = resolve(process.cwd(), projectDir);
+
+  console.log(pc.bold("\nInitializing @donkeylabs/server project...\n"));
+
+  // Check for existing files
+  if (existsSync(targetDir)) {
+    const files = await readdir(targetDir);
+    const hasConflicts = files.some(
+      (f) => f === "src" || f === "donkeylabs.config.ts"
+    );
+
+    if (hasConflicts) {
+      const { overwrite } = await prompts({
+        type: "confirm",
+        name: "overwrite",
+        message: "Directory contains existing files. Overwrite?",
+        initial: false,
+      });
+
+      if (!overwrite) {
+        console.log(pc.yellow("Cancelled."));
+        return;
+      }
+    }
+  }
+
+  // Ask for project configuration
+  const responses = await prompts([
+    {
+      type: "text",
+      name: "projectName",
+      message: "Project name:",
+      initial: projectDir === "." ? "my-server" : projectDir,
+    },
+    {
+      type: "confirm",
+      name: "useDatabase",
+      message: "Set up SQLite database?",
+      initial: true,
+    },
+  ]);
+
+  if (!responses.projectName) {
+    console.log(pc.yellow("Cancelled."));
+    return;
+  }
+
+  const options: InitOptions = {
+    projectName: responses.projectName,
+    useDatabase: responses.useDatabase ?? true,
+  };
+
+  // Create directories
+  await mkdir(join(targetDir, "src/plugins"), { recursive: true });
+  await mkdir(join(targetDir, ".@donkeylabs/server"), { recursive: true });
+
+  // Create config file
+  await writeFile(
+    join(targetDir, "donkeylabs.config.ts"),
+    generateConfig()
+  );
+  console.log(pc.green("  Created:"), "donkeylabs.config.ts");
+
+  // Create database setup file if using SQLite
+  if (options.useDatabase) {
+    await writeFile(join(targetDir, "src/db.ts"), generateDatabaseSetup());
+    console.log(pc.green("  Created:"), "src/db.ts");
+
+    await writeFile(join(targetDir, ".env.example"), generateEnvExample());
+    console.log(pc.green("  Created:"), ".env.example");
+  }
+
+  // Create main index file
+  await writeFile(
+    join(targetDir, "src/index.ts"),
+    generateIndexFile(options.useDatabase)
+  );
+  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)
+    ? await readFile(gitignorePath, "utf-8")
+    : "";
+
+  const gitignoreAdditions: string[] = [];
+  if (!gitignoreContent.includes(".@donkeylabs")) {
+    gitignoreAdditions.push("# Generated types", ".@donkeylabs/");
+  }
+  if (!gitignoreContent.includes(".env") && options.useDatabase) {
+    gitignoreAdditions.push("# Environment", ".env", ".env.local");
+  }
+  if (options.useDatabase && !gitignoreContent.includes("*.db")) {
+    gitignoreAdditions.push("# SQLite", "*.db", "*.db-journal");
+  }
+
+  if (gitignoreAdditions.length > 0) {
+    const newGitignore = gitignoreContent + "\n" + gitignoreAdditions.join("\n") + "\n";
+    await writeFile(gitignorePath, newGitignore);
+    console.log(pc.green("  Updated:"), ".gitignore");
+  }
+
+  // Create tsconfig.json if not exists
+  if (!existsSync(join(targetDir, "tsconfig.json"))) {
+    await writeFile(
+      join(targetDir, "tsconfig.json"),
+      generateTsConfig()
+    );
+    console.log(pc.green("  Created:"), "tsconfig.json");
+  }
+
+  // Update package.json
+  const pkgPath = join(targetDir, "package.json");
+  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;
+  pkg.type = "module";
+  pkg.scripts.dev = "bun --watch src/index.ts";
+  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("  Created:"), "package.json");
+
+  // Print next steps
+  console.log(`
+${pc.bold(pc.green("Success!"))} Project initialized.
+
+${pc.bold("Next steps:")}
+  1. Install dependencies:
+     ${pc.cyan("bun install")}
+${options.useDatabase ? `
+  2. Set up your database:
+     ${pc.cyan(`cp .env.example .env`)}
+` : ""}
+  ${options.useDatabase ? "3" : "2"}. Start development:
+     ${pc.cyan("bun run dev")}
+`);
+}
+
+function generateConfig(): string {
+  return `import { defineConfig } from "@donkeylabs/server";
+
+export default defineConfig({
+  plugins: ["./src/plugins/**/index.ts"],
+  outDir: ".@donkeylabs/server",
+});
+`;
+}
+
+function generateDatabaseSetup(): string {
+  return `import { Kysely } from "kysely";
+import { BunSqliteDialect } from "kysely-bun-sqlite";
+import { Database } from "bun:sqlite";
+
+const dbPath = process.env.DATABASE_URL || "app.db";
+
+export const db = new Kysely<any>({
+  dialect: new BunSqliteDialect({
+    database: new Database(dbPath),
+  }),
+});
+
+export type DB = typeof db;
+`;
+}
+
+function generateIndexFile(useDatabase: boolean): string {
+  const dbImport = useDatabase
+    ? `import { db } from "./db";\n`
+    : `import {
+  Kysely,
+  DummyDriver,
+  SqliteAdapter,
+  SqliteIntrospector,
+  SqliteQueryCompiler,
+} from "kysely";
+
+// No database configured - using dummy driver for type compatibility
+const db = new Kysely<any>({
+  dialect: {
+    createAdapter: () => new SqliteAdapter(),
+    createDriver: () => new DummyDriver(),
+    createIntrospector: (db) => new SqliteIntrospector(db),
+    createQueryCompiler: () => new SqliteQueryCompiler(),
+  },
+});
+`;
+
+  return `${dbImport}import { AppServer, createRouter } from "@donkeylabs/server";
+import { z } from "zod";
+
+// Create Server
+const server = new AppServer({
+  port: Number(process.env.PORT) || 3000,
+  db,
+  config: { env: process.env.NODE_ENV || "development" },
+});
+
+// Define Routes
+const router = createRouter("api")
+  .route("hello").typed({
+    input: z.object({ name: z.string().optional() }),
+    output: z.object({ message: z.string() }),
+    handle: async (input) => {
+      return { message: \`Hello, \${input.name || "World"}!\` };
+    },
+  })
+  .route("health").raw({
+    handle: async () => {
+      return Response.json({ status: "ok", timestamp: new Date().toISOString() });
+    },
+  });
+
+server.use(router);
+
+// Start Server
+await server.start();
+`;
+}
+
+function generateEnvExample(): string {
+  return `# Database (SQLite file path)
+DATABASE_URL=app.db
+
+# Server
+PORT=3000
+NODE_ENV=development
+`;
+}
+
+function generateTsConfig(): string {
+  return `{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true
+  },
+  "include": ["src/**/*", "*.ts", ".@donkeylabs/**/*"]
+}
+`;
+}
+
+// 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/examples/starter/node_modules/@donkeylabs/server/cli/commands/interactive.ts

@@ -0,0 +1,223 @@
+/**
+ * Interactive CLI Menu
+ *
+ * Full interactive experience with context-aware menus
+ */
+
+import prompts from "prompts";
+import pc from "picocolors";
+import { readdir, writeFile, mkdir } from "node:fs/promises";
+import { join, basename } from "node:path";
+import { existsSync } from "node:fs";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+
+const execAsync = promisify(exec);
+
+export async function interactiveCommand() {
+  console.clear();
+  console.log(pc.magenta(pc.bold("\n  @donkeylabs/server CLI\n")));
+
+  // Detect context - are we in a plugin directory?
+  const cwd = process.cwd();
+  const pathParts = cwd.split("/");
+  const parentDir = pathParts[pathParts.length - 2];
+  const currentDir = pathParts[pathParts.length - 1];
+
+  let contextPlugin: string | null = null;
+  if (parentDir === "plugins" && currentDir && existsSync(join(cwd, "index.ts"))) {
+    contextPlugin = currentDir;
+  }
+
+  // Run appropriate menu loop
+  if (contextPlugin) {
+    await pluginMenuLoop(contextPlugin);
+  } else {
+    await globalMenuLoop();
+  }
+}
+
+// ============================================
+// Plugin Context Menu (Inside plugins/<name>/)
+// ============================================
+
+async function pluginMenuLoop(pluginName: string) {
+  while (true) {
+    console.log(pc.cyan(`\n  Context: Plugin ${pc.bold(`'${pluginName}'`)}\n`));
+
+    const response = await prompts({
+      type: "select",
+      name: "action",
+      message: "What would you like to do?",
+      choices: [
+        { title: pc.yellow("1.") + " Generate Schema Types", value: "gen-types" },
+        { title: pc.yellow("2.") + " Create Migration", value: "migration" },
+        { title: pc.gray("─".repeat(35)), value: "separator", disabled: true },
+        { title: pc.blue("←") + "  Back to Global Menu", value: "global" },
+        { title: pc.red("×") + "  Exit", value: "exit" },
+      ],
+    });
+
+    if (!response.action || response.action === "exit") {
+      console.log(pc.gray("\nGoodbye!\n"));
+      process.exit(0);
+    }
+
+    if (response.action === "global") {
+      console.clear();
+      console.log(pc.magenta(pc.bold("\n  @donkeylabs/server CLI\n")));
+      await globalMenuLoop();
+      return;
+    }
+
+    console.log(""); // spacing
+
+    switch (response.action) {
+      case "gen-types":
+        await runCommand(`bun scripts/generate-types.ts ${pluginName}`);
+        break;
+      case "migration":
+        await createMigration(pluginName);
+        break;
+    }
+
+    await pressEnterToContinue();
+  }
+}
+
+// ============================================
+// Global Root Menu
+// ============================================
+
+async function globalMenuLoop() {
+  while (true) {
+    console.log(pc.cyan("\n  Context: Project Root\n"));
+
+    const choices = [
+      { title: pc.yellow("1.") + " Create New Plugin", value: "new-plugin" },
+      { title: pc.yellow("2.") + " Initialize New Project", value: "init" },
+      { title: pc.gray("─".repeat(35)), value: "separator1", disabled: true },
+      { title: pc.yellow("3.") + " Generate Types", value: "generate" },
+      { title: pc.yellow("4.") + " Generate Registry", value: "gen-registry" },
+      { title: pc.yellow("5.") + " Generate Server Context", value: "gen-server" },
+      { title: pc.gray("─".repeat(35)), value: "separator2", disabled: true },
+      { title: pc.red("×") + "  Exit", value: "exit" },
+    ];
+
+    const response = await prompts({
+      type: "select",
+      name: "action",
+      message: "Select a command:",
+      choices,
+    });
+
+    if (!response.action || response.action === "exit") {
+      console.log(pc.gray("\nGoodbye!\n"));
+      process.exit(0);
+    }
+
+    console.log(""); // spacing
+
+    switch (response.action) {
+      case "new-plugin":
+        const { pluginCommand } = await import("./plugin");
+        await pluginCommand(["create"]);
+        break;
+      case "init":
+        const { initCommand } = await import("./init");
+        await initCommand([]);
+        break;
+      case "generate":
+        const { generateCommand } = await import("./generate");
+        await generateCommand([]);
+        break;
+      case "gen-registry":
+        await runCommand("bun scripts/generate-registry.ts");
+        break;
+      case "gen-server":
+        await runCommand("bun scripts/generate-server.ts");
+        break;
+    }
+
+    await pressEnterToContinue();
+  }
+}
+
+// ============================================
+// Commands
+// ============================================
+
+async function createMigration(pluginName: string) {
+  const nameRes = await prompts({
+    type: "text",
+    name: "migName",
+    message: "Migration name (e.g. add_comments):",
+    validate: (v) =>
+      /^[a-z0-9_]+$/.test(v) ? true : "Use lowercase letters, numbers, and underscores",
+  });
+
+  if (!nameRes.migName) return;
+
+  // Determine migrations directory
+  const cwd = process.cwd();
+  const isPluginDir = basename(join(cwd, "..")) === "plugins";
+  const migrationsDir = isPluginDir
+    ? join(cwd, "migrations")
+    : join(process.cwd(), "src/plugins", pluginName, "migrations");
+
+  // Generate sequential number
+  let nextNum = 1;
+  try {
+    const files = await readdir(migrationsDir);
+    const nums = files
+      .map((f) => parseInt(f.split("_")[0] || "", 10))
+      .filter((n) => !isNaN(n));
+    if (nums.length > 0) {
+      nextNum = Math.max(...nums) + 1;
+    }
+  } catch {}
+
+  const filename = `${String(nextNum).padStart(3, "0")}_${nameRes.migName}.ts`;
+  const content = `import type { Kysely } from "kysely";
+
+export async function up(db: Kysely<any>): Promise<void> {
+  // await db.schema.createTable("...").execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  // await db.schema.dropTable("...").execute();
+}
+`;
+
+  if (!existsSync(migrationsDir)) {
+    await mkdir(migrationsDir, { recursive: true });
+  }
+
+  await writeFile(join(migrationsDir, filename), content);
+  console.log(pc.green(`Created migration: ${filename}`));
+}
+
+// ============================================
+// Helpers
+// ============================================
+
+async function runCommand(cmd: string) {
+  console.log(pc.gray(`> ${cmd}\n`));
+  try {
+    const { stdout, stderr } = await execAsync(cmd);
+    if (stdout) console.log(stdout);
+    if (stderr) console.error(pc.yellow(stderr));
+  } catch (e: any) {
+    console.error(pc.red("Command failed:"), e.message);
+  }
+}
+
+async function pressEnterToContinue() {
+  await prompts({
+    type: "invisible",
+    name: "continue",
+    message: pc.gray("Press Enter to continue..."),
+  });
+  console.clear();
+  console.log(pc.magenta(pc.bold("\n  @donkeylabs/server CLI\n")));
+}