@donkeylabs/server 0.5.0 → 0.6.3

package/src/core.ts

@@ -1,4 +1,4 @@
-import type { Kysely } from "kysely";
+import { sql, type Kysely } from "kysely";
 import { readdir } from "node:fs/promises";
 import { join } from "node:path";
 import type { z } from "zod";
@@ -11,6 +11,7 @@ import type { SSE } from "./core/sse";
 import type { RateLimiter } from "./core/rate-limiter";
 import type { Errors, CustomErrorRegistry } from "./core/errors";
 import type { Workflows } from "./core/workflows";
+import type { Processes } from "./core/processes";
 
 export interface PluginRegistry {}
 
@@ -54,6 +55,7 @@ export interface CoreServices {
   rateLimiter: RateLimiter;
   errors: Errors;
   workflows: Workflows;
+  processes: Processes;
 }
 
 /**
@@ -355,8 +357,53 @@ export class PluginManager {
     this.plugins.set(plugin.name, plugin);
   }
 
+  /**
+   * Ensures the migrations tracking table exists.
+   * This table tracks which migrations have been applied for each plugin.
+   */
+  private async ensureMigrationsTable(): Promise<void> {
+    await this.core.db.schema
+      .createTable("__donkeylabs_migrations__")
+      .ifNotExists()
+      .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+      .addColumn("plugin_name", "text", (col) => col.notNull())
+      .addColumn("migration_name", "text", (col) => col.notNull())
+      .addColumn("executed_at", "text", (col) => col.defaultTo(sql`CURRENT_TIMESTAMP`))
+      .execute();
+
+    // Create unique index for plugin_name + migration_name (if not exists)
+    // Using raw SQL since Kysely doesn't have ifNotExists for indexes
+    await sql`CREATE UNIQUE INDEX IF NOT EXISTS idx_migrations_unique
+              ON __donkeylabs_migrations__(plugin_name, migration_name)`.execute(this.core.db);
+  }
+
+  /**
+   * Checks if a migration has already been applied for a specific plugin.
+   */
+  private async isMigrationApplied(pluginName: string, migrationName: string): Promise<boolean> {
+    const result = await sql<{ count: number }>`
+      SELECT COUNT(*) as count FROM __donkeylabs_migrations__
+      WHERE plugin_name = ${pluginName} AND migration_name = ${migrationName}
+    `.execute(this.core.db);
+    return (result.rows[0]?.count ?? 0) > 0;
+  }
+
+  /**
+   * Records that a migration has been applied for a specific plugin.
+   */
+  private async recordMigration(pluginName: string, migrationName: string): Promise<void> {
+    await sql`
+      INSERT INTO __donkeylabs_migrations__ (plugin_name, migration_name)
+      VALUES (${pluginName}, ${migrationName})
+    `.execute(this.core.db);
+  }
+
   async migrate(): Promise<void> {
     console.log("Running migrations (File-System Based)...");
+
+    // Ensure the migrations tracking table exists
+    await this.ensureMigrationsTable();
+
     const sortedPlugins = this.resolveOrder();
 
     for (const plugin of sortedPlugins) {
@@ -392,22 +439,46 @@ export class PluginManager {
                  console.log(`[Migration] checking plugin: ${pluginName} at ${migrationDir}`);
 
                  for (const file of migrationFiles.sort()) {
+                     // Check if this migration has already been applied
+                     const isApplied = await this.isMigrationApplied(pluginName, file);
+                     if (isApplied) {
+                         console.log(`  - Skipping (already applied): ${file}`);
+                         continue;
+                     }
+
                      console.log(`  - Executing migration: ${file}`);
                      const migrationPath = join(migrationDir, file);
-                     const migration = await import(migrationPath);
+
+                     let migration;
+                     try {
+                         migration = await import(migrationPath);
+                     } catch (importError) {
+                         const err = importError instanceof Error ? importError : new Error(String(importError));
+                         throw new Error(`Failed to import migration ${file}: ${err.message}`);
+                     }
 
                      if (migration.up) {
                          try {
                               await migration.up(this.core.db);
+                              // Record successful migration
+                              await this.recordMigration(pluginName, file);
                               console.log(`    Success`);
                          } catch (e) {
                              console.error(`    Failed to run ${file}:`, e);
+                             throw e; // Stop on migration failure - don't continue with inconsistent state
                          }
                      }
                  }
              }
-        } catch {
-            // Migration directory doesn't exist, skip
+        } catch (e) {
+            // Re-throw migration execution errors (they've already been logged)
+            // Only silently catch directory read errors (ENOENT)
+            const isDirectoryError = e instanceof Error &&
+              ((e as NodeJS.ErrnoException).code === 'ENOENT' ||
+               (e as NodeJS.ErrnoException).code === 'ENOTDIR');
+            if (!isDirectoryError) {
+                throw e;
+            }
         }
     }
   }

package/src/harness.ts

@@ -12,6 +12,7 @@ import {
   createRateLimiter,
   createErrors,
   createWorkflows,
+  createProcesses,
 } from "./core/index";
 
 /**
@@ -36,6 +37,7 @@ export async function createTestHarness(targetPlugin: Plugin, dependencies: Plug
   const rateLimiter = createRateLimiter();
   const errors = createErrors();
   const workflows = createWorkflows({ events, jobs, sse });
+  const processes = createProcesses({ events, autoRecoverOrphans: false });
 
   const core: CoreServices = {
     db,
@@ -49,6 +51,7 @@ export async function createTestHarness(targetPlugin: Plugin, dependencies: Plug
     rateLimiter,
     errors,
     workflows,
+    processes,
   };
 
   const manager = new PluginManager(core);

package/src/index.ts

@@ -45,6 +45,7 @@ export {
   type InferHandlers,
   type InferMiddleware,
   type InferDependencies,
+  type EventSchemas,
 } from "./core";
 
 // Middleware
@@ -72,3 +73,14 @@ export function defineConfig(config: DonkeylabsConfig): DonkeylabsConfig {
 
 // Re-export HttpError for custom error creation
 export { HttpError } from "./core/errors";
+
+// Workflows (step functions)
+export {
+  workflow,
+  WorkflowBuilder,
+  type WorkflowDefinition,
+  type WorkflowInstance,
+  type WorkflowStatus,
+  type WorkflowContext,
+  type Workflows,
+} from "./core/workflows";

package/src/server.ts

@@ -15,6 +15,7 @@ import {
   createRateLimiter,
   createErrors,
   createWorkflows,
+  createProcesses,
   extractClientIP,
   HttpError,
   type LoggerConfig,
@@ -26,6 +27,7 @@ import {
   type RateLimiterConfig,
   type ErrorsConfig,
   type WorkflowsConfig,
+  type ProcessesConfig,
 } from "./core/index";
 import { zodSchemaToTs } from "./generator/zod-to-ts";
 
@@ -60,6 +62,7 @@ export interface ServerConfig {
   rateLimiter?: RateLimiterConfig;
   errors?: ErrorsConfig;
   workflows?: WorkflowsConfig;
+  processes?: ProcessesConfig;
 }
 
 export class AppServer {
@@ -88,6 +91,10 @@ export class AppServer {
       jobs,
       sse,
     });
+    const processes = createProcesses({
+      ...options.processes,
+      events,
+    });
 
     this.coreServices = {
       db: options.db,
@@ -101,6 +108,7 @@ export class AppServer {
       rateLimiter,
       errors,
       workflows,
+      processes,
     };
 
     this.manager = new PluginManager(this.coreServices);
@@ -226,12 +234,19 @@ export class AppServer {
       outputSource?: string;
     }> = [];
 
+    const routesWithoutOutput: string[] = [];
+
     for (const router of this.routers) {
       for (const route of router.getRoutes()) {
         const parts = route.name.split(".");
         const routeName = parts[parts.length - 1] || route.name;
         const prefix = parts.slice(0, -1).join(".");
 
+        // Track typed routes without explicit output schema
+        if (route.handler === "typed" && !route.output) {
+          routesWithoutOutput.push(route.name);
+        }
+
         routes.push({
           name: route.name,
           prefix,
@@ -243,6 +258,17 @@ export class AppServer {
       }
     }
 
+    // Warn about routes missing output schemas
+    if (routesWithoutOutput.length > 0) {
+      logger.warn(
+        `${routesWithoutOutput.length} route(s) missing output schema - output type will be 'void'`,
+        { routes: routesWithoutOutput }
+      );
+      logger.debug(
+        "Tip: Add an 'output' Zod schema to define the return type, or ensure handlers return nothing"
+      );
+    }
+
     // Generate the client code
     const code = this.generateClientCode(routes);
 
@@ -334,7 +360,7 @@ export function createApi(options?: ClientOptions) {
            if (r.handler !== "typed") return "";
            const routeNs = toPascalCase(r.routeName);
            const inputType = r.inputSource ?? "Record<string, never>";
-           const outputType = r.outputSource ?? "unknown";
+           const outputType = r.outputSource ?? "void";
            return `${indent}export namespace ${routeNs} {
 ${indent}  export type Input = Expand<${inputType}>;
 ${indent}  export type Output = Expand<${outputType}>;
@@ -458,7 +484,8 @@ ${factoryFunction}
     this.coreServices.cron.start();
     this.coreServices.jobs.start();
     await this.coreServices.workflows.resume();
-    logger.info("Background services started (cron, jobs, workflows)");
+    this.coreServices.processes.start();
+    logger.info("Background services started (cron, jobs, workflows, processes)");
 
     for (const router of this.routers) {
       for (const route of router.getRoutes()) {
@@ -677,7 +704,8 @@ ${factoryFunction}
     this.coreServices.cron.start();
     this.coreServices.jobs.start();
     await this.coreServices.workflows.resume();
-    logger.info("Background services started (cron, jobs, workflows)");
+    this.coreServices.processes.start();
+    logger.info("Background services started (cron, jobs, workflows, processes)");
 
     // 4. Build route map
     for (const router of this.routers) {
@@ -817,6 +845,7 @@ ${factoryFunction}
     this.coreServices.sse.shutdown();
 
     // Stop background services
+    await this.coreServices.processes.shutdown();
     await this.coreServices.workflows.stop();
     await this.coreServices.jobs.stop();
     await this.coreServices.cron.stop();