@versdotsh/reef 0.1.2

package/examples/services/registry/registry.test.ts

@@ -0,0 +1,135 @@
+import { describe, test, expect, afterAll } from "bun:test";
+import { createTestHarness, type TestHarness } from "../../../src/core/testing.js";
+import registry from "./index.js";
+
+let t: TestHarness;
+const setup = (async () => {
+  t = await createTestHarness({ services: [registry] });
+})();
+afterAll(() => t?.cleanup());
+
+describe("registry", () => {
+  test("registers a VM", async () => {
+    await setup;
+    const { status, data } = await t.json("/registry/vms", {
+      method: "POST",
+      auth: true,
+      body: {
+        id: "vm-001",
+        name: "worker-1",
+        role: "worker",
+        address: "vm-001.vm.vers.sh",
+        registeredBy: "coordinator",
+      },
+    });
+    expect(status).toBe(201);
+    expect(data.id).toBe("vm-001");
+    expect(data.name).toBe("worker-1");
+    expect(data.status).toBe("running");
+  });
+
+  test("lists VMs", async () => {
+    await setup;
+    const { status, data } = await t.json<{ vms: any[]; count: number }>("/registry/vms", {
+      auth: true,
+    });
+    expect(status).toBe(200);
+    expect(data.vms.length).toBeGreaterThanOrEqual(1);
+    expect(data.count).toBe(data.vms.length);
+  });
+
+  test("gets a VM by id", async () => {
+    await setup;
+    const { status, data } = await t.json("/registry/vms/vm-001", { auth: true });
+    expect(status).toBe(200);
+    expect(data.name).toBe("worker-1");
+  });
+
+  test("filters by role", async () => {
+    await setup;
+    await t.json("/registry/vms", {
+      method: "POST",
+      auth: true,
+      body: { id: "vm-lt", name: "lt-1", role: "lieutenant", address: "lt.vm", registeredBy: "test" },
+    });
+
+    const { data } = await t.json<{ vms: any[] }>("/registry/vms?role=lieutenant", { auth: true });
+    for (const vm of data.vms) {
+      expect(vm.role).toBe("lieutenant");
+    }
+  });
+
+  test("filters by status", async () => {
+    await setup;
+    const { data } = await t.json<{ vms: any[] }>("/registry/vms?status=running", { auth: true });
+    for (const vm of data.vms) {
+      expect(vm.status).toBe("running");
+    }
+  });
+
+  test("updates a VM", async () => {
+    await setup;
+    const { status, data } = await t.json("/registry/vms/vm-001", {
+      method: "PATCH",
+      auth: true,
+      body: { status: "paused", name: "worker-1-updated" },
+    });
+    expect(status).toBe(200);
+    expect(data.status).toBe("paused");
+    expect(data.name).toBe("worker-1-updated");
+  });
+
+  test("heartbeat updates lastSeen", async () => {
+    await setup;
+    const { status, data } = await t.json("/registry/vms/vm-001/heartbeat", {
+      method: "POST",
+      auth: true,
+    });
+    expect(status).toBe(200);
+    expect(data.lastSeen).toBeDefined();
+  });
+
+  test("discovers by role", async () => {
+    await setup;
+    // Reset vm-001 to running for discover
+    await t.json("/registry/vms/vm-001", {
+      method: "PATCH",
+      auth: true,
+      body: { status: "running" },
+    });
+
+    const { status, data } = await t.json<{ vms: any[] }>("/registry/discover/worker", { auth: true });
+    expect(status).toBe(200);
+    expect(data.vms.length).toBeGreaterThanOrEqual(1);
+  });
+
+  test("deletes a VM", async () => {
+    await setup;
+    await t.json("/registry/vms", {
+      method: "POST",
+      auth: true,
+      body: { id: "vm-delete-me", name: "delete", role: "worker", address: "x", registeredBy: "test" },
+    });
+
+    const { status } = await t.json("/registry/vms/vm-delete-me", {
+      method: "DELETE",
+      auth: true,
+    });
+    expect(status).toBe(200);
+
+    const { status: getStatus } = await t.json("/registry/vms/vm-delete-me", { auth: true });
+    expect(getStatus).toBe(404);
+  });
+
+  test("returns 404 for missing VM", async () => {
+    await setup;
+    const { status } = await t.json("/registry/vms/nonexistent", { auth: true });
+    expect(status).toBe(404);
+  });
+
+  test("requires auth", async () => {
+    await setup;
+    const { status } = await t.json("/registry/vms");
+    expect(status).toBe(401);
+  });
+});

package/examples/services/registry/routes.ts

@@ -0,0 +1,76 @@
+/**
+ * Registry HTTP routes — VM registration, discovery, heartbeat.
+ */
+
+import { Hono } from "hono";
+import type { RegistryStore, VMFilters, VMRole, VMStatus } from "./store.js";
+import { NotFoundError, ValidationError, ConflictError } from "./store.js";
+
+export function createRoutes(store: RegistryStore): Hono {
+  const routes = new Hono();
+
+  routes.post("/vms", async (c) => {
+    try {
+      const body = await c.req.json();
+      const vm = store.register(body);
+      return c.json(vm, 201);
+    } catch (e) {
+      if (e instanceof ValidationError) return c.json({ error: e.message }, 400);
+      if (e instanceof ConflictError) return c.json({ error: e.message }, 409);
+      throw e;
+    }
+  });
+
+  routes.get("/vms", (c) => {
+    const filters: VMFilters = {};
+    const role = c.req.query("role");
+    const status = c.req.query("status");
+    if (role) filters.role = role as VMRole;
+    if (status) filters.status = status as VMStatus;
+
+    const vms = store.list(filters);
+    return c.json({ vms, count: vms.length });
+  });
+
+  routes.get("/vms/:id", (c) => {
+    const vm = store.get(c.req.param("id"));
+    if (!vm) return c.json({ error: "VM not found" }, 404);
+    return c.json(vm);
+  });
+
+  routes.patch("/vms/:id", async (c) => {
+    try {
+      const body = await c.req.json();
+      const vm = store.update(c.req.param("id"), body);
+      return c.json(vm);
+    } catch (e) {
+      if (e instanceof NotFoundError) return c.json({ error: e.message }, 404);
+      if (e instanceof ValidationError) return c.json({ error: e.message }, 400);
+      throw e;
+    }
+  });
+
+  routes.delete("/vms/:id", (c) => {
+    const deleted = store.deregister(c.req.param("id"));
+    if (!deleted) return c.json({ error: "VM not found" }, 404);
+    return c.json({ deleted: true });
+  });
+
+  routes.post("/vms/:id/heartbeat", (c) => {
+    try {
+      const vm = store.heartbeat(c.req.param("id"));
+      return c.json({ id: vm.id, lastSeen: vm.lastSeen });
+    } catch (e) {
+      if (e instanceof NotFoundError) return c.json({ error: e.message }, 404);
+      throw e;
+    }
+  });
+
+  routes.get("/discover/:role", (c) => {
+    const role = c.req.param("role") as VMRole;
+    const vms = store.discover(role);
+    return c.json({ vms, count: vms.length });
+  });
+
+  return routes;
+}

package/examples/services/registry/store.ts

@@ -0,0 +1,224 @@
+/**
+ * Registry store — VM service discovery with heartbeat-based liveness.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname } from "node:path";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type VMRole = "infra" | "lieutenant" | "worker" | "golden" | "custom";
+export type VMStatus = "running" | "paused" | "stopped";
+
+export interface VMService {
+  name: string;
+  port: number;
+  protocol?: string;
+}
+
+export interface VM {
+  id: string;
+  name: string;
+  role: VMRole;
+  status: VMStatus;
+  address: string;
+  services: VMService[];
+  registeredBy: string;
+  registeredAt: string;
+  lastSeen: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface RegisterInput {
+  id: string;
+  name: string;
+  role: VMRole;
+  address: string;
+  services?: VMService[];
+  registeredBy: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface UpdateInput {
+  name?: string;
+  status?: VMStatus;
+  address?: string;
+  services?: VMService[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface VMFilters {
+  role?: VMRole;
+  status?: VMStatus;
+}
+
+// =============================================================================
+// Errors
+// =============================================================================
+
+export class NotFoundError extends Error {
+  constructor(message: string) { super(message); this.name = "NotFoundError"; }
+}
+
+export class ValidationError extends Error {
+  constructor(message: string) { super(message); this.name = "ValidationError"; }
+}
+
+export class ConflictError extends Error {
+  constructor(message: string) { super(message); this.name = "ConflictError"; }
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const VALID_ROLES = new Set<string>(["infra", "lieutenant", "worker", "golden", "custom"]);
+const VALID_STATUSES = new Set<string>(["running", "paused", "stopped"]);
+const STALE_THRESHOLD_MS = 5 * 60 * 1000; // 5 minutes
+
+// =============================================================================
+// Store
+// =============================================================================
+
+export class RegistryStore {
+  private vms = new Map<string, VM>();
+  private filePath: string;
+  private writeTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(filePath = "data/registry.json") {
+    this.filePath = filePath;
+    this.load();
+  }
+
+  private load(): void {
+    try {
+      if (existsSync(this.filePath)) {
+        const raw = readFileSync(this.filePath, "utf-8");
+        const data = JSON.parse(raw);
+        if (Array.isArray(data.vms)) {
+          for (const v of data.vms) this.vms.set(v.id, v);
+        }
+      }
+    } catch {
+      this.vms = new Map();
+    }
+  }
+
+  private scheduleSave(): void {
+    if (this.writeTimer) return;
+    this.writeTimer = setTimeout(() => {
+      this.writeTimer = null;
+      this.flush();
+    }, 100);
+  }
+
+  flush(): void {
+    if (this.writeTimer) {
+      clearTimeout(this.writeTimer);
+      this.writeTimer = null;
+    }
+    const dir = dirname(this.filePath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const data = JSON.stringify({ vms: Array.from(this.vms.values()) }, null, 2);
+    writeFileSync(this.filePath, data, "utf-8");
+  }
+
+  private isStale(vm: VM): boolean {
+    return Date.now() - new Date(vm.lastSeen).getTime() > STALE_THRESHOLD_MS;
+  }
+
+  register(input: RegisterInput): VM {
+    if (!input.id?.trim()) throw new ValidationError("id is required");
+    if (!input.name?.trim()) throw new ValidationError("name is required");
+    if (!input.role || !VALID_ROLES.has(input.role)) throw new ValidationError(`invalid role: ${input.role}`);
+    if (!input.address?.trim()) throw new ValidationError("address is required");
+    if (!input.registeredBy?.trim()) throw new ValidationError("registeredBy is required");
+
+    // Allow re-registration (upsert)
+    const now = new Date().toISOString();
+    const existing = this.vms.get(input.id);
+
+    const vm: VM = {
+      id: input.id.trim(),
+      name: input.name.trim(),
+      role: input.role,
+      status: "running",
+      address: input.address.trim(),
+      services: input.services || existing?.services || [],
+      registeredBy: input.registeredBy.trim(),
+      registeredAt: existing?.registeredAt || now,
+      lastSeen: now,
+      metadata: input.metadata || existing?.metadata,
+    };
+
+    this.vms.set(vm.id, vm);
+    this.scheduleSave();
+    return vm;
+  }
+
+  get(id: string): VM | undefined {
+    return this.vms.get(id);
+  }
+
+  list(filters?: VMFilters): VM[] {
+    let results = Array.from(this.vms.values());
+
+    if (filters?.role) results = results.filter((v) => v.role === filters.role);
+    if (filters?.status) {
+      if (filters.status === "running") {
+        // Exclude stale VMs from "running" filter
+        results = results.filter((v) => v.status === "running" && !this.isStale(v));
+      } else {
+        results = results.filter((v) => v.status === filters.status);
+      }
+    }
+
+    results.sort((a, b) => b.lastSeen.localeCompare(a.lastSeen));
+    return results;
+  }
+
+  update(id: string, input: UpdateInput): VM {
+    const vm = this.vms.get(id);
+    if (!vm) throw new NotFoundError("VM not found");
+
+    if (input.status !== undefined && !VALID_STATUSES.has(input.status)) {
+      throw new ValidationError(`invalid status: ${input.status}`);
+    }
+
+    if (input.name !== undefined) vm.name = input.name.trim();
+    if (input.status !== undefined) vm.status = input.status;
+    if (input.address !== undefined) vm.address = input.address.trim();
+    if (input.services !== undefined) vm.services = input.services;
+    if (input.metadata !== undefined) vm.metadata = input.metadata;
+
+    vm.lastSeen = new Date().toISOString();
+    this.vms.set(id, vm);
+    this.scheduleSave();
+    return vm;
+  }
+
+  deregister(id: string): boolean {
+    const existed = this.vms.delete(id);
+    if (existed) this.scheduleSave();
+    return existed;
+  }
+
+  heartbeat(id: string): VM {
+    const vm = this.vms.get(id);
+    if (!vm) throw new NotFoundError("VM not found");
+
+    vm.lastSeen = new Date().toISOString();
+    vm.status = "running";
+    this.vms.set(id, vm);
+    this.scheduleSave();
+    return vm;
+  }
+
+  discover(role: VMRole): VM[] {
+    return Array.from(this.vms.values()).filter(
+      (v) => v.role === role && v.status === "running" && !this.isStale(v),
+    );
+  }
+}

package/examples/services/registry/tools.ts

@@ -0,0 +1,116 @@
+/**
+ * Registry tools — VM registration, discovery, heartbeat.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { FleetClient } from "../src/core/types.js";
+import { Type } from "@sinclair/typebox";
+import { StringEnum } from "@mariozechner/pi-ai";
+
+const ROLE_ENUM = StringEnum(
+  ["infra", "lieutenant", "worker", "golden", "custom"] as const,
+  { description: "VM role in the swarm" },
+);
+
+export function registerTools(pi: ExtensionAPI, client: FleetClient) {
+  pi.registerTool({
+    name: "registry_list",
+    label: "Registry: List VMs",
+    description: "List VMs in the coordination registry. Optionally filter by role or status.",
+    parameters: Type.Object({
+      role: Type.Optional(ROLE_ENUM),
+      status: Type.Optional(
+        StringEnum(["running", "paused", "stopped"] as const, { description: "Filter by status" }),
+      ),
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const qs = new URLSearchParams();
+        if (params.role) qs.set("role", params.role);
+        if (params.status) qs.set("status", params.status);
+        const query = qs.toString();
+        const result = await client.api("GET", `/registry/vms${query ? `?${query}` : ""}`);
+        return client.ok(JSON.stringify(result, null, 2), { result });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "registry_register",
+    label: "Registry: Register VM",
+    description: "Register a VM so other agents can discover it.",
+    parameters: Type.Object({
+      id: Type.String({ description: "VM ID (from Vers)" }),
+      name: Type.String({ description: "Human-readable name" }),
+      role: ROLE_ENUM,
+      address: Type.String({ description: "Network address or endpoint" }),
+      services: Type.Optional(
+        Type.Array(
+          Type.Object({
+            name: Type.String(),
+            port: Type.Number(),
+            protocol: Type.Optional(Type.String()),
+          }),
+          { description: "Services exposed by this VM" },
+        ),
+      ),
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const vm = await client.api("POST", "/registry/vms", {
+          ...params,
+          registeredBy: client.agentName,
+        });
+        return client.ok(JSON.stringify(vm, null, 2), { vm });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "registry_discover",
+    label: "Registry: Discover VMs",
+    description: "Discover VMs by role — find workers, lieutenants, or other agents.",
+    parameters: Type.Object({
+      role: ROLE_ENUM,
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const result = await client.api(
+          "GET",
+          `/registry/discover/${encodeURIComponent(params.role)}`,
+        );
+        return client.ok(JSON.stringify(result, null, 2), { result });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "registry_heartbeat",
+    label: "Registry: Heartbeat",
+    description: "Send a heartbeat to keep a VM's registration active.",
+    parameters: Type.Object({
+      id: Type.String({ description: "VM ID to heartbeat" }),
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const result = await client.api(
+          "POST",
+          `/registry/vms/${encodeURIComponent(params.id)}/heartbeat`,
+        );
+        return client.ok(JSON.stringify(result, null, 2), { result });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+}

package/examples/services/reports/index.ts

@@ -0,0 +1,14 @@
+import type { ServiceModule } from "../src/core/types.js";
+import { ReportsStore } from "./store.js";
+import { createRoutes } from "./routes.js";
+
+const store = new ReportsStore();
+
+const reports: ServiceModule = {
+  name: "reports",
+  description: "Markdown reports",
+  routes: createRoutes(store),
+  store,
+};
+
+export default reports;

package/examples/services/reports/reports.test.ts

@@ -0,0 +1,75 @@
+import { describe, test, expect, afterAll } from "bun:test";
+import { createTestHarness, type TestHarness } from "../../../src/core/testing.js";
+import reports from "./index.js";
+
+let t: TestHarness;
+const setup = (async () => {
+  t = await createTestHarness({ services: [reports] });
+})();
+afterAll(() => t?.cleanup());
+
+describe("reports", () => {
+  test("creates a report", async () => {
+    await setup;
+    const { status, data } = await t.json("/reports", {
+      method: "POST",
+      auth: true,
+      body: {
+        title: "Sprint 1 Summary",
+        content: "# Sprint 1\n\nDone a lot of work.",
+        author: "coordinator",
+        tags: ["sprint", "summary"],
+      },
+    });
+    expect(status).toBe(201);
+    expect(data.title).toBe("Sprint 1 Summary");
+    expect(data.content).toContain("Sprint 1");
+    expect(data.id).toBeDefined();
+  });
+
+  test("lists reports", async () => {
+    await setup;
+    const { status, data } = await t.json<{ reports: any[]; count: number }>("/reports", {
+      auth: true,
+    });
+    expect(status).toBe(200);
+    expect(data.reports.length).toBeGreaterThanOrEqual(1);
+  });
+
+  test("gets a report by id", async () => {
+    await setup;
+    const { data: created } = await t.json<any>("/reports", {
+      method: "POST",
+      auth: true,
+      body: { title: "Get by ID", content: "test content", author: "test" },
+    });
+
+    const { status, data } = await t.json(`/reports/${created.id}`, { auth: true });
+    expect(status).toBe(200);
+    expect(data.title).toBe("Get by ID");
+  });
+
+  test("deletes a report", async () => {
+    await setup;
+    const { data: created } = await t.json<any>("/reports", {
+      method: "POST",
+      auth: true,
+      body: { title: "Delete me", content: "bye", author: "test" },
+    });
+
+    const { status } = await t.json(`/reports/${created.id}`, {
+      method: "DELETE",
+      auth: true,
+    });
+    expect(status).toBe(200);
+
+    const { status: getStatus } = await t.json(`/reports/${created.id}`, { auth: true });
+    expect(getStatus).toBe(404);
+  });
+
+  test("requires auth", async () => {
+    await setup;
+    const { status } = await t.json("/reports");
+    expect(status).toBe(401);
+  });
+});

package/examples/services/reports/routes.ts

@@ -0,0 +1,42 @@
+import { Hono } from "hono";
+import type { ReportsStore } from "./store.js";
+import { ValidationError } from "./store.js";
+
+export function createRoutes(store: ReportsStore): Hono {
+  const routes = new Hono();
+
+  routes.post("/", async (c) => {
+    try {
+      const body = await c.req.json();
+      const report = store.create(body);
+      return c.json(report, 201);
+    } catch (e) {
+      if (e instanceof ValidationError) return c.json({ error: e.message }, 400);
+      throw e;
+    }
+  });
+
+  routes.get("/", (c) => {
+    const reports = store.list({
+      author: c.req.query("author") || undefined,
+      tag: c.req.query("tag") || undefined,
+    });
+    // Listing: omit content for lighter payload
+    const summaries = reports.map(({ content, ...rest }) => rest);
+    return c.json({ reports: summaries, count: summaries.length });
+  });
+
+  routes.get("/:id", (c) => {
+    const report = store.get(c.req.param("id"));
+    if (!report) return c.json({ error: "report not found" }, 404);
+    return c.json(report);
+  });
+
+  routes.delete("/:id", (c) => {
+    const deleted = store.delete(c.req.param("id"));
+    if (!deleted) return c.json({ error: "report not found" }, 404);
+    return c.json({ deleted: true });
+  });
+
+  return routes;
+}