@versdotsh/reef 0.1.2

package/src/core/auth.ts

@@ -0,0 +1,28 @@
+/**
+ * Bearer token auth middleware for Hono.
+ *
+ * If VERS_AUTH_TOKEN is set, requires Authorization: Bearer <token>.
+ * If not set, all requests pass through (dev mode).
+ */
+
+import type { MiddlewareHandler } from "hono";
+
+export function bearerAuth(): MiddlewareHandler {
+  return async (c, next) => {
+    const token = process.env.VERS_AUTH_TOKEN;
+
+    if (!token) return next();
+
+    const authHeader = c.req.header("Authorization");
+    if (!authHeader) {
+      return c.json({ error: "Unauthorized — missing Authorization header" }, 401);
+    }
+
+    const match = authHeader.match(/^Bearer\s+(.+)$/i);
+    if (!match || match[1] !== token) {
+      return c.json({ error: "Unauthorized — invalid token" }, 401);
+    }
+
+    return next();
+  };
+}

package/src/core/client.ts

@@ -0,0 +1,99 @@
+/**
+ * FleetClient — shared HTTP client + identity for all service modules.
+ *
+ * Injected into every service's registerTools/registerBehaviors so they
+ * don't manage HTTP or identity themselves.
+ */
+
+import type { FleetClient, ToolResult } from "./types.js";
+
+export function createFleetClient(): FleetClient {
+  const agentName = process.env.VERS_AGENT_NAME || `agent-${process.pid}`;
+  const vmId = process.env.VERS_VM_ID || undefined;
+  const agentRole = process.env.VERS_AGENT_ROLE || "worker";
+
+  function getBaseUrl(): string | null {
+    return process.env.VERS_INFRA_URL || null;
+  }
+
+  async function api<T = unknown>(
+    method: string,
+    path: string,
+    body?: unknown,
+  ): Promise<T> {
+    const base = getBaseUrl();
+    if (!base) throw new Error("VERS_INFRA_URL not set");
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+
+    const token = process.env.VERS_AUTH_TOKEN;
+    if (token) {
+      headers["Authorization"] = `Bearer ${token}`;
+    }
+
+    const res = await fetch(`${base}${path}`, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+
+    const text = await res.text();
+    let data: unknown;
+    try {
+      data = JSON.parse(text);
+    } catch {
+      data = text;
+    }
+
+    if (!res.ok) {
+      const msg =
+        typeof data === "object" &&
+        data !== null &&
+        "error" in (data as Record<string, unknown>)
+          ? (data as { error: string }).error
+          : text;
+      throw new Error(`${method} ${path} (${res.status}): ${msg}`);
+    }
+
+    return data as T;
+  }
+
+  function ok(text: string, details?: Record<string, unknown>): ToolResult {
+    return {
+      content: [{ type: "text", text }],
+      details: details ?? {},
+    };
+  }
+
+  function err(text: string): ToolResult {
+    return {
+      content: [{ type: "text", text: `Error: ${text}` }],
+      isError: true,
+    };
+  }
+
+  function noUrl(): ToolResult {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "Error: VERS_INFRA_URL environment variable is not set.\n\nSet it to the base URL of your reef instance, e.g.:\n  export VERS_INFRA_URL=http://localhost:3000",
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  return {
+    api,
+    getBaseUrl,
+    agentName,
+    vmId,
+    agentRole,
+    ok,
+    err,
+    noUrl,
+  };
+}

package/src/core/discover.ts

@@ -0,0 +1,152 @@
+/**
+ * Service module discovery — scan a directory, dynamic import, topo-sort.
+ *
+ * Follows the pi-mono pattern: each service is a self-contained directory
+ * with an index.ts that default-exports a ServiceModule. Drop a folder in,
+ * it gets picked up. Delete one, it's gone. No import wiring.
+ *
+ * Discovery rules:
+ *   services/foo/index.ts  → import default → ServiceModule
+ *
+ * Modules are topologically sorted by `dependencies` before being returned,
+ * so init() hooks can safely reference stores from upstream modules.
+ */
+
+import { readdirSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { ServiceModule } from "./types.js";
+
+// =============================================================================
+// Initial discovery
+// =============================================================================
+
+/**
+ * Discover and load all service modules from a directory.
+ *
+ * @param servicesDir - Path to the services directory (e.g. "./services")
+ * @returns Topologically sorted array of ServiceModules
+ */
+export async function discoverServiceModules(
+  servicesDir: string,
+): Promise<ServiceModule[]> {
+  const resolved = resolve(servicesDir);
+
+  if (!existsSync(resolved)) {
+    throw new Error(`Services directory not found: ${resolved}`);
+  }
+
+  const entries = readdirSync(resolved, { withFileTypes: true });
+  const modules: ServiceModule[] = [];
+  const errors: Array<{ dir: string; error: string }> = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const indexPath = join(resolved, entry.name, "index.ts");
+    if (!existsSync(indexPath)) continue;
+
+    try {
+      const mod = await import(indexPath);
+      const serviceModule: ServiceModule = mod.default;
+
+      if (!serviceModule?.name) {
+        errors.push({
+          dir: entry.name,
+          error: "No default export or missing 'name' property",
+        });
+        continue;
+      }
+
+      modules.push(serviceModule);
+    } catch (err) {
+      errors.push({
+        dir: entry.name,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  if (errors.length > 0) {
+    for (const { dir, error } of errors) {
+      console.error(`  [discover] Failed to load services/${dir}: ${error}`);
+    }
+  }
+
+  return topoSort(modules);
+}
+
+/**
+ * Filter modules that have client-side code (tools, behaviors, or widgets).
+ * Used by the extension loader to skip server-only modules.
+ */
+export function filterClientModules(modules: ServiceModule[]): ServiceModule[] {
+  return modules.filter(
+    (m) => m.registerTools || m.registerBehaviors || m.widget,
+  );
+}
+
+// =============================================================================
+// Single-module loading (used by reload and install endpoints)
+// =============================================================================
+
+/**
+ * Load a single service module from a directory.
+ * Uses cache-busting so re-imports pick up changes.
+ */
+export async function loadServiceModule(
+  dirPath: string,
+): Promise<ServiceModule> {
+  const indexPath = join(dirPath, "index.ts");
+
+  if (!existsSync(indexPath)) {
+    throw new Error(`No index.ts found in ${dirPath}`);
+  }
+
+  const mod = await import(`${indexPath}?t=${Date.now()}`);
+  const serviceModule: ServiceModule = mod.default;
+
+  if (!serviceModule?.name) {
+    throw new Error(`No valid default export in ${indexPath}`);
+  }
+
+  return serviceModule;
+}
+
+// =============================================================================
+// Topological sort by dependencies
+// =============================================================================
+
+function topoSort(modules: ServiceModule[]): ServiceModule[] {
+  const byName = new Map<string, ServiceModule>();
+  for (const m of modules) byName.set(m.name, m);
+
+  const visited = new Set<string>();
+  const sorted: ServiceModule[] = [];
+
+  function visit(name: string, stack: Set<string>) {
+    if (visited.has(name)) return;
+    if (stack.has(name)) {
+      throw new Error(
+        `Circular dependency detected: ${[...stack, name].join(" → ")}`,
+      );
+    }
+
+    const mod = byName.get(name);
+    if (!mod) return;
+
+    stack.add(name);
+    for (const dep of mod.dependencies ?? []) {
+      visit(dep, stack);
+    }
+    stack.delete(name);
+
+    visited.add(name);
+    sorted.push(mod);
+  }
+
+  for (const mod of modules) {
+    visit(mod.name, new Set());
+  }
+
+  return sorted;
+}

package/src/core/events.ts

@@ -0,0 +1,44 @@
+/**
+ * Server-side event bus — lets service modules communicate without
+ * importing each other. Same pattern as pi.events on the client side.
+ *
+ * Typed loosely on purpose: modules define their own event shapes,
+ * and subscribers cast as needed. This keeps the bus decoupled from
+ * any specific module's types.
+ */
+
+type Handler = (data: any) => void | Promise<void>;
+
+export class ServiceEventBus {
+  private handlers = new Map<string, Set<Handler>>();
+
+  /** Subscribe to an event. Returns an unsubscribe function. */
+  on(event: string, handler: Handler): () => void {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, new Set());
+    }
+    this.handlers.get(event)!.add(handler);
+    return () => {
+      this.handlers.get(event)?.delete(handler);
+    };
+  }
+
+  /** Emit an event. Handlers run in order, errors are caught and logged. */
+  async emit(event: string, data?: unknown): Promise<void> {
+    const handlers = this.handlers.get(event);
+    if (!handlers) return;
+
+    for (const handler of handlers) {
+      try {
+        await handler(data);
+      } catch (err) {
+        console.error(`[events] Handler error for "${event}":`, err);
+      }
+    }
+  }
+
+  /** Fire and forget — emit without awaiting handlers. */
+  fire(event: string, data?: unknown): void {
+    this.emit(event, data).catch(() => {});
+  }
+}

package/src/core/extension.ts

@@ -0,0 +1,66 @@
+/**
+ * Extension — composes all service modules into a single pi extension.
+ *
+ * Each module registers its own tools and behaviors. The extension loader
+ * creates the shared FleetClient and wires up the composite status widget.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ServiceModule, WidgetContribution } from "./types.js";
+import { createFleetClient } from "./client.js";
+
+export function createExtension(modules: ServiceModule[]) {
+  return function (pi: ExtensionAPI) {
+    const client = createFleetClient();
+
+    // Let each module register its tools and behaviors
+    for (const mod of modules) {
+      mod.registerTools?.(pi, client);
+      mod.registerBehaviors?.(pi, client);
+    }
+
+    // Composite widget from all contributing modules
+    const widgetContributions: Array<{ name: string; widget: WidgetContribution }> =
+      modules
+        .filter((m) => m.widget)
+        .map((m) => ({ name: m.name, widget: m.widget! }));
+
+    let widgetTimer: ReturnType<typeof setInterval> | null = null;
+
+    async function updateWidget(ctx: {
+      ui: { setWidget: (id: string, lines: string[]) => void };
+    }) {
+      if (!client.getBaseUrl()) return;
+
+      const allLines: string[] = [];
+      const base = client.getBaseUrl();
+      allLines.push(`--- Fleet Services --- ${base}/ui`);
+
+      for (const { widget } of widgetContributions) {
+        try {
+          const lines = await widget.getLines(client);
+          allLines.push(...lines);
+        } catch {
+          // Best effort — skip failing widgets
+        }
+      }
+
+      if (allLines.length > 1) {
+        ctx.ui.setWidget("reef", allLines);
+      }
+    }
+
+    pi.on("session_start", async (_event, ctx) => {
+      if (!client.getBaseUrl()) return;
+      updateWidget(ctx);
+      widgetTimer = setInterval(() => updateWidget(ctx), 30_000);
+    });
+
+    pi.on("session_shutdown", async () => {
+      if (widgetTimer) {
+        clearInterval(widgetTimer);
+        widgetTimer = null;
+      }
+    });
+  };
+}

package/src/core/server.ts

@@ -0,0 +1,262 @@
+/**
+ * Server — minimal dispatch infrastructure.
+ *
+ * The server's only job is:
+ *   1. Discover and load service modules at startup
+ *   2. Dispatch requests to the right module
+ *   3. Health check
+ *   4. Graceful shutdown
+ *
+ * Everything else — including managing modules at runtime — is handled
+ * by service modules themselves:
+ *   /services   — reload and unload modules
+ *   /installer  — install from git or local paths
+ *   /docs       — auto-generated API documentation
+ */
+
+import { join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { Hono } from "hono";
+import { bearerAuth } from "./auth.js";
+import { discoverServiceModules, loadServiceModule } from "./discover.js";
+import { ServiceEventBus } from "./events.js";
+import type { ServiceModule, ServiceContext } from "./types.js";
+
+export const DEFAULT_SERVICES_DIR = "./services";
+
+export interface ServerOptions {
+  modules?: ServiceModule[];
+  servicesDir?: string;
+  port?: number;
+}
+
+export async function createServer(options: ServerOptions) {
+  const servicesDir = options.servicesDir ?? process.env.SERVICES_DIR ?? DEFAULT_SERVICES_DIR;
+  const resolvedServicesDir = resolve(servicesDir);
+  const initialModules = options.modules ?? await discoverServiceModules(servicesDir);
+  const app = new Hono();
+  const events = new ServiceEventBus();
+
+  // Catch any unhandled errors from service route handlers
+  app.onError((err, c) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`  [dispatch] error: ${msg}`);
+    return c.json({ error: "internal service error" }, 500);
+  });
+
+  // ==========================================================================
+  // Live module registry
+  // ==========================================================================
+
+  const liveModules = new Map<string, ServiceModule>();
+  const stores = new Map<string, unknown>();
+  const dirForModule = new Map<string, string>();
+
+  function registerModule(mod: ServiceModule, dirName?: string): void {
+    liveModules.set(mod.name, mod);
+    if (mod.store) stores.set(mod.name, mod.store);
+    if (dirName) dirForModule.set(mod.name, dirName);
+  }
+
+  async function unregisterModule(name: string): Promise<void> {
+    const mod = liveModules.get(name);
+    if (!mod) return;
+
+    if (mod.store?.flush) mod.store.flush();
+    if (mod.store?.close) await mod.store.close();
+
+    liveModules.delete(name);
+    stores.delete(name);
+    dirForModule.delete(name);
+  }
+
+  async function loadFromDir(
+    dirName: string,
+  ): Promise<{ name: string; action: "added" | "updated" }> {
+    const dirPath = join(resolvedServicesDir, dirName);
+    const serviceModule = await loadServiceModule(dirPath);
+
+    for (const dep of serviceModule.dependencies ?? []) {
+      if (!liveModules.has(dep)) {
+        throw new Error(`Missing dependency "${dep}"`);
+      }
+    }
+
+    const existed = liveModules.has(serviceModule.name);
+
+    if (existed) {
+      const old = liveModules.get(serviceModule.name)!;
+      if (old.store?.flush) old.store.flush();
+      if (old.store?.close) await old.store.close();
+    }
+
+    registerModule(serviceModule, dirName);
+
+    try {
+      serviceModule.init?.(ctx);
+    } catch (err) {
+      // Roll back — don't leave a half-initialized module in the registry
+      liveModules.delete(serviceModule.name);
+      stores.delete(serviceModule.name);
+      dirForModule.delete(serviceModule.name);
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(`Module "${serviceModule.name}" init() failed: ${msg}`);
+    }
+
+    return { name: serviceModule.name, action: existed ? "updated" : "added" };
+  }
+
+  // ==========================================================================
+  // Service context — passed to all modules
+  // ==========================================================================
+
+  const ctx: ServiceContext = {
+    events,
+    servicesDir: resolvedServicesDir,
+
+    getStore<T = unknown>(name: string): T | undefined {
+      return stores.get(name) as T | undefined;
+    },
+
+    getModules(): ServiceModule[] {
+      return Array.from(liveModules.values());
+    },
+
+    getModule(name: string): ServiceModule | undefined {
+      return liveModules.get(name);
+    },
+
+    loadModule(dirName: string) {
+      return loadFromDir(dirName);
+    },
+
+    async unloadModule(name: string) {
+      await unregisterModule(name);
+    },
+  };
+
+  // ==========================================================================
+  // Routes — health check + dynamic dispatch
+  // ==========================================================================
+
+  const auth = bearerAuth();
+
+  app.get("/health", (c) =>
+    c.json({
+      status: "ok",
+      uptime: process.uptime(),
+      services: Array.from(liveModules.values())
+        .filter((m) => m.routes)
+        .map((m) => m.name),
+    }),
+  );
+
+  // Dynamic dispatch: look up module by name on each request
+  async function dispatch(c: any) {
+    const serviceName = c.req.param("service");
+
+    if (serviceName === "health") return c.notFound();
+
+    const mod = liveModules.get(serviceName);
+    if (!mod?.routes || mod.mountAtRoot) {
+      return c.json({ error: "not found" }, 404);
+    }
+
+    if (mod.requiresAuth !== false) {
+      const authResponse = await auth(c, async () => {});
+      if (authResponse instanceof Response) return authResponse;
+      if (c.res.status === 401) return c.res;
+    }
+
+    const url = new URL(c.req.url);
+    const prefix = `/${serviceName}`;
+    url.pathname = url.pathname.slice(prefix.length) || "/";
+    const rewritten = new Request(url.toString(), c.req.raw);
+
+    const response = await mod.routes.fetch(rewritten);
+
+    // If the sub-Hono returned a 500 (e.g. unhandled throw in route handler),
+    // normalize it to a JSON error response
+    if (response.status >= 500) {
+      return c.json({ error: "internal service error" }, response.status as any);
+    }
+
+    return response;
+  }
+
+  // Root-mounted modules (UI, webhooks) — registered before catch-all
+  for (const mod of initialModules) {
+    if (mod.mountAtRoot && mod.routes) {
+      app.route("/", mod.routes);
+    }
+  }
+
+  app.all("/:service{[^/]+}", dispatch);
+  app.all("/:service{[^/]+}/*", dispatch);
+
+  // ==========================================================================
+  // Initialize all modules
+  // ==========================================================================
+
+  for (const mod of initialModules) {
+    registerModule(mod, mod.name);
+  }
+
+  for (const mod of initialModules) {
+    try {
+      mod.init?.(ctx);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`  [init] /${mod.name} failed — skipping: ${msg}`);
+      liveModules.delete(mod.name);
+      stores.delete(mod.name);
+      dirForModule.delete(mod.name);
+    }
+  }
+
+  return { app, liveModules, events, ctx };
+}
+
+/**
+ * Start the server and wire up graceful shutdown.
+ */
+export async function startServer(options: ServerOptions = {}) {
+  const { app, liveModules } = await createServer(options);
+  const port = options.port ?? parseInt(process.env.PORT || "3000", 10);
+
+  if (!process.env.VERS_AUTH_TOKEN) {
+    console.warn(
+      "  VERS_AUTH_TOKEN is not set — all endpoints are unauthenticated.",
+    );
+  }
+
+  console.log("  services:");
+  for (const mod of liveModules.values()) {
+    if (mod.routes) {
+      console.log(`    /${mod.name} — ${mod.description || mod.name}`);
+    }
+  }
+
+  const server = Bun.serve({
+    fetch: app.fetch,
+    port,
+    hostname: "::",
+  });
+
+  console.log(`\n  reef running on :${port}\n`);
+
+  async function shutdown() {
+    console.log("\n  shutting down...");
+    for (const mod of liveModules.values()) {
+      if (mod.store?.flush) mod.store.flush();
+      if (mod.store?.close) await mod.store.close();
+    }
+    server.stop();
+    process.exit(0);
+  }
+
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+
+  return { app, server, liveModules };
+}