@versdotsh/reef 0.1.2

package/src/core/testing.ts

@@ -0,0 +1,155 @@
+/**
+ * Test helpers for service modules.
+ *
+ * Usage:
+ *   import { createTestHarness } from "../src/core/testing.js";
+ *
+ *   const t = await createTestHarness({
+ *     services: [import("../services/board/index.js")],
+ *   });
+ *
+ *   const res = await t.fetch("/board/tasks", { auth: true });
+ *   expect(res.status).toBe(200);
+ *
+ *   t.cleanup();
+ */
+
+import { mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { createServer } from "./server.js";
+import type { ServiceModule } from "./types.js";
+
+export interface TestHarnessOptions {
+  /** Service modules to load. Can be module objects or dynamic imports. */
+  services: Array<ServiceModule | Promise<{ default: ServiceModule }>>;
+  /** Auth token (default: "test-token") */
+  authToken?: string;
+  /** Temp data dir for stores (default: auto-created, auto-cleaned) */
+  dataDir?: string;
+}
+
+export interface TestHarness {
+  /** The Hono app — call app.fetch() to make requests */
+  app: { fetch: (req: Request) => Promise<Response> };
+  /** Auth token for this test */
+  authToken: string;
+  /** Temp directory for data files */
+  dataDir: string;
+
+  /** Make a request with optional auth and body */
+  fetch(
+    path: string,
+    opts?: {
+      method?: string;
+      body?: unknown;
+      auth?: boolean | string;
+      headers?: Record<string, string>;
+    },
+  ): Promise<Response>;
+
+  /** Make a request and parse JSON response */
+  json<T = unknown>(
+    path: string,
+    opts?: {
+      method?: string;
+      body?: unknown;
+      auth?: boolean | string;
+    },
+  ): Promise<{ status: number; data: T }>;
+
+  /** Clean up temp directories */
+  cleanup(): void;
+}
+
+export async function createTestHarness(
+  options: TestHarnessOptions,
+): Promise<TestHarness> {
+  const authToken = options.authToken ?? "test-token";
+  const dataDir =
+    options.dataDir ??
+    join(import.meta.dir, "..", "..", "tests", `.tmp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+
+  // Set up env
+  const prevToken = process.env.VERS_AUTH_TOKEN;
+  process.env.VERS_AUTH_TOKEN = authToken;
+
+  // Create temp dirs
+  mkdirSync(dataDir, { recursive: true });
+
+  // Resolve modules
+  const modules: ServiceModule[] = [];
+  for (const mod of options.services) {
+    if ("name" in mod && "routes" in mod) {
+      // Already a ServiceModule
+      modules.push(mod as ServiceModule);
+    } else {
+      // Dynamic import — resolve the promise and get default export
+      const resolved = await (mod as Promise<{ default: ServiceModule }>);
+      modules.push(resolved.default);
+    }
+  }
+
+  // Create server with the modules directly (no services dir needed)
+  const emptyDir = join(dataDir, "_empty_services");
+  mkdirSync(emptyDir, { recursive: true });
+  const { app } = await createServer({
+    modules,
+    servicesDir: emptyDir,
+  });
+
+  function makeFetch(
+    path: string,
+    opts: {
+      method?: string;
+      body?: unknown;
+      auth?: boolean | string;
+      headers?: Record<string, string>;
+    } = {},
+  ): Promise<Response> {
+    const headers: Record<string, string> = { ...(opts.headers || {}) };
+    if (opts.body) headers["Content-Type"] = "application/json";
+    if (opts.auth === true) {
+      headers["Authorization"] = `Bearer ${authToken}`;
+    } else if (typeof opts.auth === "string") {
+      headers["Authorization"] = `Bearer ${opts.auth}`;
+    }
+
+    return app.fetch(
+      new Request(`http://localhost${path}`, {
+        method: opts.method ?? "GET",
+        headers,
+        body: opts.body ? JSON.stringify(opts.body) : undefined,
+      }),
+    );
+  }
+
+  async function makeJson<T = unknown>(
+    path: string,
+    opts: {
+      method?: string;
+      body?: unknown;
+      auth?: boolean | string;
+    } = {},
+  ): Promise<{ status: number; data: T }> {
+    const res = await makeFetch(path, opts);
+    return { status: res.status, data: (await res.json()) as T };
+  }
+
+  function cleanup() {
+    rmSync(dataDir, { recursive: true, force: true });
+    if (prevToken !== undefined) {
+      process.env.VERS_AUTH_TOKEN = prevToken;
+    } else {
+      delete process.env.VERS_AUTH_TOKEN;
+    }
+  }
+
+  return {
+    app,
+    authToken,
+    dataDir,
+    fetch: makeFetch,
+    json: makeJson,
+    cleanup,
+  };
+}

package/src/core/types.ts

@@ -0,0 +1,194 @@
+/**
+ * Core types for the reef plugin system.
+ *
+ * A ServiceModule is the fundamental unit — it declares both server-side
+ * routes and client-side pi extension behavior in one place.
+ */
+
+import type { Hono } from "hono";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ServiceEventBus } from "./events.js";
+
+// =============================================================================
+// Tool result types (matching pi's expected shape)
+// =============================================================================
+
+export interface ToolContent {
+  type: "text";
+  text: string;
+}
+
+export interface ToolResult {
+  content: ToolContent[];
+  details?: Record<string, unknown>;
+  isError?: boolean;
+}
+
+// =============================================================================
+// FleetClient — injected into every service's client-side code
+// =============================================================================
+
+export interface FleetClient {
+  /** Make an authenticated API call to the fleet server */
+  api<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
+
+  /** Get the base URL, or null if not configured */
+  getBaseUrl(): string | null;
+
+  /** This agent's name (from VERS_AGENT_NAME or fallback) */
+  readonly agentName: string;
+
+  /** This agent's VM ID, if set */
+  readonly vmId: string | undefined;
+
+  /** This agent's role (from VERS_AGENT_ROLE or "worker") */
+  readonly agentRole: string;
+
+  /** Build a successful tool result */
+  ok(text: string, details?: Record<string, unknown>): ToolResult;
+
+  /** Build an error tool result */
+  err(text: string): ToolResult;
+
+  /** Build a "no URL configured" error result */
+  noUrl(): ToolResult;
+}
+
+// =============================================================================
+// Widget contribution — services add lines to the composite status widget
+// =============================================================================
+
+export interface WidgetContribution {
+  /** Lines to contribute to the status widget */
+  getLines(client: FleetClient): Promise<string[]>;
+}
+
+// =============================================================================
+// ServiceContext — passed to modules during server-side initialization
+// =============================================================================
+
+export interface ServiceContext {
+  /** Server-side event bus for inter-module communication */
+  events: ServiceEventBus;
+
+  /** Get another module's store by service name. Returns undefined if not found. */
+  getStore<T = unknown>(serviceName: string): T | undefined;
+
+  /** All currently loaded modules (read-only view). */
+  getModules(): ServiceModule[];
+
+  /** Get a loaded module by name. */
+  getModule(name: string): ServiceModule | undefined;
+
+  /**
+   * Load or reload a module from a directory under the services dir.
+   * Returns the module name and whether it was added or updated.
+   */
+  loadModule(dirName: string): Promise<{ name: string; action: "added" | "updated" }>;
+
+  /** Unload a module by name. Flushes and closes its store. */
+  unloadModule(name: string): Promise<void>;
+
+  /** The resolved services directory path. */
+  servicesDir: string;
+}
+
+// =============================================================================
+// ServiceModule — the plugin interface
+// =============================================================================
+
+export interface ServiceModule {
+  /** Unique name, used as route prefix: /board, /feed, etc. */
+  name: string;
+
+  /** Human-readable description */
+  description?: string;
+
+  // --- Server side ---
+
+  /** Hono routes, mounted at /{name}/* (or root if mountAtRoot is true) */
+  routes?: Hono;
+
+  /** Mount routes at / instead of /{name}/. Used for UI, webhooks, etc. */
+  mountAtRoot?: boolean;
+
+  /** Whether routes need bearer auth. Default: true */
+  requiresAuth?: boolean;
+
+  /** Store handle for graceful shutdown (flush pending writes, close connections) */
+  store?: {
+    flush?(): void;
+    close?(): Promise<void>;
+  };
+
+  /**
+   * Server-side initialization hook. Called after all modules are loaded,
+   * so you can subscribe to events or look up other modules' stores.
+   */
+  init?(ctx: ServiceContext): void;
+
+  // --- Client side (pi extension) ---
+
+  /** Register tools the LLM can call */
+  registerTools?(pi: ExtensionAPI, client: FleetClient): void;
+
+  /** Register automatic behaviors (event handlers, timers) */
+  registerBehaviors?(pi: ExtensionAPI, client: FleetClient): void;
+
+  /** Contribute lines to the composite status widget */
+  widget?: WidgetContribution;
+
+  // --- Metadata ---
+
+  /** Services this module depends on (for load ordering) */
+  dependencies?: string[];
+
+  /**
+   * Route documentation. Keyed by "METHOD /path" (path relative to module root).
+   * Used by the docs service to generate API documentation.
+   *
+   * @example
+   * routeDocs: {
+   *   "POST /tasks": {
+   *     summary: "Create a task",
+   *     body: {
+   *       title: { type: "string", required: true, description: "Task title" },
+   *       assignee: { type: "string", description: "Agent or user to assign to" },
+   *     },
+   *     response: "The created task object with generated ID and timestamps",
+   *   },
+   *   "GET /tasks": {
+   *     summary: "List tasks with optional filters",
+   *     query: {
+   *       status: { type: "string", description: "open | in_progress | in_review | blocked | done" },
+   *     },
+   *   },
+   * }
+   */
+  routeDocs?: Record<string, RouteDocs>;
+}
+
+// =============================================================================
+// Route documentation types
+// =============================================================================
+
+export interface ParamDoc {
+  type: string;
+  required?: boolean;
+  description?: string;
+}
+
+export interface RouteDocs {
+  /** Short description of what this endpoint does */
+  summary: string;
+  /** Longer explanation, usage notes, or examples */
+  detail?: string;
+  /** URL path parameters (e.g. :id) */
+  params?: Record<string, ParamDoc>;
+  /** Query string parameters */
+  query?: Record<string, ParamDoc>;
+  /** Request body fields (for POST/PATCH/PUT) */
+  body?: Record<string, ParamDoc>;
+  /** Description of the response */
+  response?: string;
+}

package/src/extension.ts

@@ -0,0 +1,16 @@
+/**
+ * Pi extension entrypoint — discovers service modules and composes their
+ * client-side code into a single extension that agents install.
+ *
+ * This is the client half. The server half is src/main.ts.
+ */
+
+import { createExtension } from "./core/extension.js";
+import { discoverServiceModules, filterClientModules } from "./core/discover.js";
+import { DEFAULT_SERVICES_DIR } from "./core/server.js";
+
+const servicesDir = process.env.SERVICES_DIR ?? DEFAULT_SERVICES_DIR;
+const allModules = await discoverServiceModules(servicesDir);
+const clientModules = filterClientModules(allModules);
+
+export default createExtension(clientModules);

package/src/main.ts

@@ -0,0 +1,11 @@
+/**
+ * Server entrypoint — discovers service modules and starts the server.
+ *
+ * Configure via env vars:
+ *   SERVICES_DIR  — path to services directory (default: ./services)
+ *   PORT          — server port (default: 3000)
+ */
+
+import { startServer } from "./core/server.js";
+
+await startServer();