@ronkovic/aad 0.3.0

package/src/modules/plugin/__tests__/plugin-manager.test.ts

@@ -0,0 +1,187 @@
+import { describe, test, expect, mock } from "bun:test";
+import { PluginManager } from "../plugin-manager";
+import type { AADPlugin, PluginContext, HookHandler } from "../plugin.types";
+import { EventBus } from "../../../shared/events";
+import { loadConfig } from "../../../shared/config";
+import pino from "pino";
+
+function createTestContext(): PluginContext {
+  return {
+    config: loadConfig({}),
+    eventBus: new EventBus(),
+    logger: pino({ level: "silent" }),
+  };
+}
+
+function createTestPlugin(overrides: Partial<AADPlugin> = {}): AADPlugin {
+  return {
+    name: "test-plugin",
+    version: "1.0.0",
+    activate: mock(() => {}),
+    deactivate: mock(() => {}),
+    ...overrides,
+  };
+}
+
+describe("PluginManager", () => {
+  test("register activates plugin and adds to list", async () => {
+    const ctx = createTestContext();
+    const manager = new PluginManager(ctx);
+    const plugin = createTestPlugin();
+
+    await manager.register(plugin);
+
+    expect(plugin.activate).toHaveBeenCalledWith(ctx);
+    expect(manager.list()).toEqual([{ name: "test-plugin", version: "1.0.0" }]);
+  });
+
+  test("register skips duplicate plugin names", async () => {
+    const ctx = createTestContext();
+    const manager = new PluginManager(ctx);
+    const plugin1 = createTestPlugin();
+    const plugin2 = createTestPlugin({ activate: mock(() => {}) });
+
+    await manager.register(plugin1);
+    await manager.register(plugin2);
+
+    expect(plugin1.activate).toHaveBeenCalledTimes(1);
+    expect(plugin2.activate).not.toHaveBeenCalled();
+    expect(manager.list()).toHaveLength(1);
+  });
+
+  test("register throws on activation failure", async () => {
+    const ctx = createTestContext();
+    const manager = new PluginManager(ctx);
+    const plugin = createTestPlugin({
+      activate: () => { throw new Error("activation failed"); },
+    });
+
+    await expect(manager.register(plugin)).rejects.toThrow("activation failed");
+    expect(manager.list()).toHaveLength(0);
+  });
+
+  test("deactivateAll calls deactivate on all plugins", async () => {
+    const ctx = createTestContext();
+    const manager = new PluginManager(ctx);
+    const p1 = createTestPlugin({ name: "p1" });
+    const p2 = createTestPlugin({ name: "p2" });
+
+    await manager.register(p1);
+    await manager.register(p2);
+    await manager.deactivateAll();
+
+    expect(p1.deactivate).toHaveBeenCalledTimes(1);
+    expect(p2.deactivate).toHaveBeenCalledTimes(1);
+    expect(manager.list()).toHaveLength(0);
+  });
+
+  test("deactivateAll handles plugin without deactivate", async () => {
+    const ctx = createTestContext();
+    const manager = new PluginManager(ctx);
+    const plugin = createTestPlugin({ deactivate: undefined });
+
+    await manager.register(plugin);
+    await manager.deactivateAll(); // should not throw
+    expect(manager.list()).toHaveLength(0);
+  });
+
+  test("deactivateAll continues if one plugin deactivation fails", async () => {
+    const ctx = createTestContext();
+    const manager = new PluginManager(ctx);
+    const p1 = createTestPlugin({
+      name: "p1",
+      deactivate: () => { throw new Error("cleanup failed"); },
+    });
+    const p2 = createTestPlugin({ name: "p2" });
+
+    await manager.register(p1);
+    await manager.register(p2);
+    await manager.deactivateAll();
+
+    expect(p2.deactivate).toHaveBeenCalledTimes(1);
+  });
+
+  test("addHook and runHook execute in registration order (waterfall)", async () => {
+    const ctx = createTestContext();
+    const manager = new PluginManager(ctx);
+
+    manager.addHook("before:planning", ((data: unknown) => {
+      return { ...(data as Record<string, unknown>), step1: true };
+    }) as HookHandler);
+    manager.addHook("before:planning", ((data: unknown) => {
+      return { ...(data as Record<string, unknown>), step2: true };
+    }) as HookHandler);
+
+    const result = await manager.runHook("before:planning", { initial: true } as Record<string, unknown>);
+
+    expect(result).toEqual({ initial: true, step1: true, step2: true });
+  });
+
+  test("runHook returns original data if handler returns void", async () => {
+    const ctx = createTestContext();
+    const manager = new PluginManager(ctx);
+
+    manager.addHook("before:execution", (() => {
+      // side effect only, no return
+    }) as HookHandler);
+
+    const result = await manager.runHook("before:execution", { value: 42 });
+    expect(result).toEqual({ value: 42 });
+  });
+
+  test("runHook returns data unchanged when no hooks registered", async () => {
+    const ctx = createTestContext();
+    const manager = new PluginManager(ctx);
+
+    const data = { test: true };
+    const result = await manager.runHook("on:error", data);
+    expect(result).toBe(data);
+  });
+
+  test("runHook continues on handler error", async () => {
+    const ctx = createTestContext();
+    const manager = new PluginManager(ctx);
+
+    manager.addHook("before:planning", (() => {
+      throw new Error("hook error");
+    }) as HookHandler);
+    manager.addHook("before:planning", ((data: unknown) => {
+      return { ...(data as Record<string, unknown>), recovered: true };
+    }) as HookHandler);
+
+    const result = await manager.runHook("before:planning", { initial: true } as Record<string, unknown>);
+    expect(result).toEqual({ initial: true, recovered: true });
+  });
+
+  test("runHook supports async handlers", async () => {
+    const ctx = createTestContext();
+    const manager = new PluginManager(ctx);
+
+    manager.addHook("after:execution", (async (data: unknown) => {
+      await new Promise((r) => setTimeout(r, 1));
+      return { ...(data as Record<string, unknown>), async: true };
+    }) as HookHandler);
+
+    const result = await manager.runHook("after:execution", { sync: true } as Record<string, unknown>);
+    expect(result).toEqual({ sync: true, async: true });
+  });
+
+  test("list returns empty array when no plugins registered", () => {
+    const ctx = createTestContext();
+    const manager = new PluginManager(ctx);
+    expect(manager.list()).toEqual([]);
+  });
+
+  test("list returns all registered plugins", async () => {
+    const ctx = createTestContext();
+    const manager = new PluginManager(ctx);
+
+    await manager.register(createTestPlugin({ name: "alpha", version: "1.0.0" }));
+    await manager.register(createTestPlugin({ name: "beta", version: "2.0.0" }));
+
+    expect(manager.list()).toEqual([
+      { name: "alpha", version: "1.0.0" },
+      { name: "beta", version: "2.0.0" },
+    ]);
+  });
+});

package/src/modules/plugin/index.ts

@@ -0,0 +1,3 @@
+export { PluginManager } from "./plugin-manager";
+export { loadPlugin } from "./plugin-loader";
+export type { AADPlugin, PluginContext, HookPoint, HookHandler } from "./plugin.types";

package/src/modules/plugin/plugin-loader.ts

@@ -0,0 +1,46 @@
+/**
+ * Plugin Loader
+ * Dynamic loading and validation of AAD plugins
+ */
+
+import { z } from "zod";
+import { resolve, isAbsolute } from "node:path";
+import type { AADPlugin } from "./plugin.types";
+
+const pluginSchema = z.object({
+  name: z.string().min(1),
+  version: z.string().min(1),
+  activate: z.function(),
+  deactivate: z.function().optional(),
+});
+
+/** Load a plugin from a file path or module name */
+export async function loadPlugin(pathOrModule: string): Promise<AADPlugin> {
+  let modulePath: string;
+
+  if (isAbsolute(pathOrModule)) {
+    modulePath = pathOrModule;
+  } else if (pathOrModule.startsWith("./") || pathOrModule.startsWith("../")) {
+    modulePath = resolve(process.cwd(), pathOrModule);
+  } else {
+    // npm package name
+    modulePath = pathOrModule;
+  }
+
+  let mod: unknown;
+  try {
+    mod = await import(modulePath);
+  } catch (error) {
+    throw new Error(`Failed to load plugin from "${pathOrModule}": ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  // Support both default export and named 'plugin' export
+  const raw = (mod as Record<string, unknown>)?.default ?? (mod as Record<string, unknown>)?.plugin ?? mod;
+
+  const result = pluginSchema.safeParse(raw);
+  if (!result.success) {
+    throw new Error(`Invalid plugin from "${pathOrModule}": ${result.error.message}`);
+  }
+
+  return raw as AADPlugin;
+}

package/src/modules/plugin/plugin-manager.ts

@@ -0,0 +1,90 @@
+/**
+ * PluginManager
+ * Manages plugin lifecycle and hook execution
+ */
+
+import type { AADPlugin, PluginContext, HookPoint, HookHandler } from "./plugin.types";
+
+export class PluginManager {
+  private plugins: Map<string, AADPlugin> = new Map();
+  private hooks: Map<HookPoint, HookHandler[]> = new Map();
+
+  constructor(private ctx: PluginContext) {}
+
+  /** Register a plugin */
+  async register(plugin: AADPlugin): Promise<void> {
+    if (this.plugins.has(plugin.name)) {
+      this.ctx.logger.warn({ plugin: plugin.name }, "Plugin already registered, skipping");
+      return;
+    }
+
+    try {
+      await plugin.activate(this.ctx);
+      this.plugins.set(plugin.name, plugin);
+      this.ctx.logger.info({ plugin: plugin.name, version: plugin.version }, "Plugin registered");
+    } catch (error) {
+      this.ctx.logger.error({ plugin: plugin.name, error }, "Plugin activation failed");
+      throw error;
+    }
+  }
+
+  /** Load plugins from config (file paths or package names) */
+  async loadFromConfig(pluginPaths: string[]): Promise<void> {
+    const { loadPlugin } = await import("./plugin-loader");
+    for (const pathOrModule of pluginPaths) {
+      try {
+        const plugin = await loadPlugin(pathOrModule);
+        await this.register(plugin);
+      } catch (error) {
+        this.ctx.logger.error({ pathOrModule, error }, "Failed to load plugin");
+        // Continue loading other plugins
+      }
+    }
+  }
+
+  /** Run all hooks for a given point (waterfall pattern) */
+  async runHook<T>(point: HookPoint, data: T): Promise<T> {
+    const handlers = this.hooks.get(point);
+    if (!handlers || handlers.length === 0) return data;
+
+    let result = data;
+    for (const handler of handlers) {
+      try {
+        const output = await handler(result);
+        if (output !== undefined && output !== null) {
+          result = output as T;
+        }
+      } catch (error) {
+        this.ctx.logger.error({ hookPoint: point, error }, "Hook handler error");
+        // Continue with other handlers
+      }
+    }
+    return result;
+  }
+
+  /** Register a hook handler */
+  addHook(point: HookPoint, handler: HookHandler): void {
+    const handlers = this.hooks.get(point) ?? [];
+    handlers.push(handler);
+    this.hooks.set(point, handlers);
+  }
+
+  /** Deactivate all plugins */
+  async deactivateAll(): Promise<void> {
+    for (const [name, plugin] of this.plugins) {
+      try {
+        await plugin.deactivate?.();
+        this.ctx.logger.debug({ plugin: name }, "Plugin deactivated");
+      } catch (error) {
+        this.ctx.logger.error({ plugin: name, error }, "Plugin deactivation failed");
+      }
+    }
+    this.plugins.clear();
+    this.hooks.clear();
+  }
+
+  /** List registered plugins */
+  list(): Array<{ name: string; version: string }> {
+    return Array.from(this.plugins.values()).map(({ name, version }) => ({ name, version }));
+  }
+}

package/src/modules/plugin/plugin.types.ts

@@ -0,0 +1,37 @@
+/**
+ * Plugin System Types
+ * Hook-based plugin interface for AAD lifecycle extensibility
+ */
+
+import type { EventBus } from "../../shared/events";
+import type { Config } from "../../shared/config";
+import type pino from "pino";
+
+export interface PluginContext {
+  config: Config;
+  eventBus: EventBus;
+  logger: pino.Logger;
+}
+
+export interface AADPlugin {
+  name: string;
+  version: string;
+
+  /** Called when plugin is loaded. Register event listeners here. */
+  activate(ctx: PluginContext): Promise<void> | void;
+
+  /** Called on shutdown. Clean up resources. */
+  deactivate?(): Promise<void> | void;
+}
+
+/** Hook points for synchronous/async interceptors */
+export type HookPoint =
+  | "before:planning"
+  | "after:planning"
+  | "before:execution"
+  | "after:execution"
+  | "before:merge"
+  | "after:merge"
+  | "on:error";
+
+export type HookHandler<T = unknown> = (data: T) => Promise<T | void> | T | void;

package/src/modules/process-manager/__tests__/process-manager.test.ts

@@ -0,0 +1,210 @@
+import { describe, test, expect, beforeEach } from "bun:test";
+import { createWorkerId, createTaskId } from "@aad/shared/types";
+import { EventBus } from "@aad/shared/events";
+import { ProcessManager } from "../process-manager";
+import { pino } from "pino";
+
+describe("ProcessManager", () => {
+  let processManager: ProcessManager;
+  let eventBus: EventBus;
+
+  beforeEach(() => {
+    eventBus = new EventBus();
+    const logger = pino({ level: "silent" });
+
+    processManager = new ProcessManager({
+      eventBus,
+      config: {
+        workers: { num: 4, max: 8 },
+        models: {},
+        timeouts: { claude: 30000, test: 60000, staleTask: 300000 },
+        retry: { maxRetries: 2 },
+        debug: false,
+        adaptiveEffort: false,
+        teams: { splitter: false, reviewer: false },
+        memorySync: false,
+        dashboard: { enabled: false, port: 7333, host: "localhost" },
+      },
+      logger,
+    });
+  });
+
+  describe("initializePool", () => {
+    test("initializes worker pool with specified number of workers", () => {
+      processManager.initializePool(3);
+
+      const allWorkers = processManager.getAllWorkers();
+      expect(allWorkers).toHaveLength(3);
+
+      const stats = processManager.getStats();
+      expect(stats.total).toBe(3);
+      expect(stats.idle).toBe(3);
+    });
+
+    test("emits worker:started events", () => {
+      const startedWorkers: string[] = [];
+
+      eventBus.on("worker:started", (event) => {
+        if (event.type === "worker:started") {
+          startedWorkers.push(event.workerId as string);
+        }
+      });
+
+      processManager.initializePool(2);
+
+      expect(startedWorkers).toHaveLength(2);
+    });
+
+    test("throws error if already initialized", () => {
+      processManager.initializePool(2);
+
+      expect(() => processManager.initializePool(2)).toThrow("already initialized");
+    });
+  });
+
+  describe("getIdleWorkers", () => {
+    test("returns all workers initially", () => {
+      processManager.initializePool(3);
+
+      const idleWorkers = processManager.getIdleWorkers();
+      expect(idleWorkers).toHaveLength(3);
+    });
+
+    test("returns only idle workers after assigning tasks", () => {
+      processManager.initializePool(3);
+
+      const allWorkers = processManager.getAllWorkers();
+      processManager.assignTask(allWorkers[0]!, createTaskId("task-1"));
+
+      const idleWorkers = processManager.getIdleWorkers();
+      expect(idleWorkers).toHaveLength(2);
+    });
+  });
+
+  describe("assignTask", () => {
+    test("assigns task to worker", () => {
+      processManager.initializePool(2);
+
+      const workerId = processManager.getIdleWorkers()[0]!;
+      const taskId = createTaskId("task-1");
+
+      processManager.assignTask(workerId, taskId);
+
+      const worker = processManager.getWorker(workerId);
+      expect(worker?.isBusy()).toBe(true);
+      expect(worker?.getCurrentTask()).toBe(taskId);
+    });
+
+    test("emits worker:busy event", () => {
+      processManager.initializePool(2);
+
+      let busyEventEmitted = false;
+      eventBus.on("worker:busy", () => {
+        busyEventEmitted = true;
+      });
+
+      const workerId = processManager.getIdleWorkers()[0]!;
+      processManager.assignTask(workerId, createTaskId("task-1"));
+
+      expect(busyEventEmitted).toBe(true);
+    });
+
+    test("throws error for non-existent worker", () => {
+      processManager.initializePool(2);
+
+      expect(() =>
+        processManager.assignTask(createWorkerId("worker-999"), createTaskId("task-1"))
+      ).toThrow("Worker not found");
+    });
+  });
+
+  describe("completeTask", () => {
+    test("marks worker as idle", () => {
+      processManager.initializePool(2);
+
+      const workerId = processManager.getIdleWorkers()[0]!;
+      processManager.assignTask(workerId, createTaskId("task-1"));
+      processManager.completeTask(workerId);
+
+      const worker = processManager.getWorker(workerId);
+      expect(worker?.isIdle()).toBe(true);
+      expect(worker?.getCurrentTask()).toBeNull();
+    });
+
+    test("emits worker:idle event", () => {
+      processManager.initializePool(2);
+
+      let idleEventEmitted = false;
+      eventBus.on("worker:idle", () => {
+        idleEventEmitted = true;
+      });
+
+      const workerId = processManager.getIdleWorkers()[0]!;
+      processManager.assignTask(workerId, createTaskId("task-1"));
+      processManager.completeTask(workerId);
+
+      expect(idleEventEmitted).toBe(true);
+    });
+  });
+
+  describe("stopAll", () => {
+    test("stops all workers", () => {
+      processManager.initializePool(3);
+
+      processManager.stopAll();
+
+      const stats = processManager.getStats();
+      expect(stats.stopped).toBe(3);
+      expect(stats.idle).toBe(0);
+    });
+
+    test("emits worker:stopped events for all workers", () => {
+      processManager.initializePool(2);
+
+      const stoppedWorkers: string[] = [];
+      eventBus.on("worker:stopped", (event) => {
+        if (event.type === "worker:stopped") {
+          stoppedWorkers.push(event.workerId as string);
+        }
+      });
+
+      processManager.stopAll();
+
+      expect(stoppedWorkers).toHaveLength(2);
+    });
+  });
+
+  describe("stopWorker", () => {
+    test("stops specific worker", () => {
+      processManager.initializePool(3);
+
+      const workerId = processManager.getAllWorkers()[0]!;
+      processManager.stopWorker(workerId);
+
+      const worker = processManager.getWorker(workerId);
+      expect(worker?.isStopped()).toBe(true);
+
+      const stats = processManager.getStats();
+      expect(stats.stopped).toBe(1);
+      expect(stats.idle).toBe(2);
+    });
+  });
+
+  describe("getStats", () => {
+    test("returns accurate statistics", () => {
+      processManager.initializePool(4);
+
+      const workers = processManager.getAllWorkers();
+      processManager.assignTask(workers[0]!, createTaskId("task-1"));
+      processManager.assignTask(workers[1]!, createTaskId("task-2"));
+      processManager.stopWorker(workers[2]!);
+
+      const stats = processManager.getStats();
+
+      expect(stats.total).toBe(4);
+      expect(stats.idle).toBe(1);
+      expect(stats.busy).toBe(2);
+      expect(stats.stopped).toBe(1);
+    });
+  });
+});

package/src/modules/process-manager/__tests__/worker.test.ts

@@ -0,0 +1,89 @@
+import { describe, test, expect } from "bun:test";
+import { createWorkerId, createTaskId } from "@aad/shared/types";
+import { WorkerStateMachine } from "../worker";
+import { ProcessManagerError } from "@aad/shared/errors";
+
+describe("WorkerStateMachine", () => {
+  test("initializes with idle status", () => {
+    const worker = new WorkerStateMachine(createWorkerId("worker-1"));
+
+    expect(worker.getStatus()).toBe("idle");
+    expect(worker.getCurrentTask()).toBeNull();
+    expect(worker.isIdle()).toBe(true);
+  });
+
+  test("transitions from idle to busy when task assigned", () => {
+    const worker = new WorkerStateMachine(createWorkerId("worker-1"));
+    const taskId = createTaskId("task-1");
+
+    worker.assignTask(taskId);
+
+    expect(worker.getStatus()).toBe("busy");
+    expect(worker.getCurrentTask()).toBe(taskId);
+    expect(worker.isBusy()).toBe(true);
+  });
+
+  test("transitions from busy to idle when task completed", () => {
+    const worker = new WorkerStateMachine(createWorkerId("worker-1"));
+    const taskId = createTaskId("task-1");
+
+    worker.assignTask(taskId);
+    worker.completeTask();
+
+    expect(worker.getStatus()).toBe("idle");
+    expect(worker.getCurrentTask()).toBeNull();
+    expect(worker.isIdle()).toBe(true);
+  });
+
+  test("throws error when assigning task to busy worker", () => {
+    const worker = new WorkerStateMachine(createWorkerId("worker-1"));
+
+    worker.assignTask(createTaskId("task-1"));
+
+    expect(() => worker.assignTask(createTaskId("task-2"))).toThrow(ProcessManagerError);
+  });
+
+  test("throws error when completing task on idle worker", () => {
+    const worker = new WorkerStateMachine(createWorkerId("worker-1"));
+
+    expect(() => worker.completeTask()).toThrow(ProcessManagerError);
+  });
+
+  test("stops worker from any state", () => {
+    const worker = new WorkerStateMachine(createWorkerId("worker-1"));
+
+    worker.stop();
+    expect(worker.getStatus()).toBe("stopped");
+    expect(worker.isStopped()).toBe(true);
+  });
+
+  test("stops worker from busy state", () => {
+    const worker = new WorkerStateMachine(createWorkerId("worker-1"));
+
+    worker.assignTask(createTaskId("task-1"));
+    worker.stop();
+
+    expect(worker.getStatus()).toBe("stopped");
+    expect(worker.getCurrentTask()).toBeNull();
+  });
+
+  test("sets and gets PID", () => {
+    const worker = new WorkerStateMachine(createWorkerId("worker-1"));
+
+    worker.setPid(12345);
+
+    const state = worker.getState();
+    expect(state.pid).toBe(12345);
+  });
+
+  test("getState returns immutable copy", () => {
+    const worker = new WorkerStateMachine(createWorkerId("worker-1"));
+
+    const state1 = worker.getState();
+    worker.assignTask(createTaskId("task-1"));
+    const state2 = worker.getState();
+
+    expect(state1.status).toBe("idle");
+    expect(state2.status).toBe("busy");
+  });
+});

package/src/modules/process-manager/index.ts

@@ -0,0 +1,5 @@
+export { WorkerStateMachine } from "./worker";
+export type { WorkerState } from "./worker";
+
+export { ProcessManager } from "./process-manager";
+export type { ProcessManagerDeps } from "./process-manager";