@versdotsh/reef 0.1.2

package/services/docs/index.ts

@@ -0,0 +1,391 @@
+/**
+ * Docs service module — auto-generated API documentation.
+ *
+ * Introspects all loaded service modules to produce endpoint documentation.
+ * Reads routes from Hono instances and combines with routeDocs metadata.
+ *
+ *   GET /docs           — full API docs (JSON)
+ *   GET /docs/:service  — docs for a specific service
+ *   GET /docs/ui        — browsable HTML docs
+ */
+
+import { Hono } from "hono";
+import type {
+  ServiceModule,
+  ServiceContext,
+  RouteDocs,
+  ParamDoc,
+} from "../src/core/types.js";
+
+let ctx: ServiceContext;
+
+// =============================================================================
+// Types
+// =============================================================================
+
+interface RouteDoc {
+  method: string;
+  path: string;
+  summary?: string;
+  detail?: string;
+  params?: Record<string, ParamDoc>;
+  query?: Record<string, ParamDoc>;
+  body?: Record<string, ParamDoc>;
+  response?: string;
+}
+
+interface ServiceDoc {
+  name: string;
+  description: string | undefined;
+  auth: boolean;
+  routes: RouteDoc[];
+  capabilities: {
+    hasTools: boolean;
+    hasBehaviors: boolean;
+    hasWidget: boolean;
+    hasStore: boolean;
+  };
+  dependencies: string[];
+}
+
+// =============================================================================
+// Introspection
+// =============================================================================
+
+function documentService(mod: ServiceModule): ServiceDoc {
+  const routes: RouteDoc[] = [];
+  const docMap = mod.routeDocs ?? {};
+
+  if (mod.routes) {
+    for (const r of (mod.routes as any).routes || []) {
+      if (r.method === "ALL" && (r.path === "/*" || r.path === "*")) continue;
+
+      const prefix = mod.mountAtRoot ? "" : `/${mod.name}`;
+
+      // Look up docs by "METHOD /path" (path relative to module, as declared)
+      const key = `${r.method} ${r.path}`;
+      const docs = docMap[key];
+
+      routes.push({
+        method: r.method,
+        path: prefix + r.path,
+        ...(docs ?? {}),
+      });
+    }
+  }
+
+  return {
+    name: mod.name,
+    description: mod.description,
+    auth: mod.requiresAuth !== false,
+    routes,
+    capabilities: {
+      hasTools: !!mod.registerTools,
+      hasBehaviors: !!mod.registerBehaviors,
+      hasWidget: !!mod.widget,
+      hasStore: !!mod.store,
+    },
+    dependencies: mod.dependencies ?? [],
+  };
+}
+
+function documentAll(): ServiceDoc[] {
+  return ctx
+    .getModules()
+    .filter((m) => m.name !== "docs")
+    .map(documentService)
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// =============================================================================
+// HTML renderer
+// =============================================================================
+
+function renderHTML(docs: ServiceDoc[]): string {
+  const methodColor: Record<string, string> = {
+    GET: "#4f9",
+    POST: "#5af",
+    PATCH: "#fd0",
+    PUT: "#fd0",
+    DELETE: "#f55",
+    ALL: "#888",
+  };
+
+  const services = docs
+    .map((svc) => {
+      const routes = svc.routes
+        .map((r) => {
+          const color = methodColor[r.method] || "#ccc";
+          const summary = r.summary
+            ? `<span class="summary">${esc(r.summary)}</span>`
+            : "";
+          const detail = r.detail
+            ? `<div class="detail">${esc(r.detail)}</div>`
+            : "";
+          const params = renderParamTable("Path params", r.params);
+          const query = renderParamTable("Query params", r.query);
+          const body = renderParamTable("Body", r.body);
+          const response = r.response
+            ? `<div class="response-doc"><span class="field-label">Response:</span> <span class="response-text">${esc(r.response)}</span></div>`
+            : "";
+          const hasDetails = r.summary || r.params || r.query || r.body || r.response;
+          const expandClass = hasDetails ? " expandable" : "";
+          const detailBlock =
+            detail || params || query || body || response
+              ? `<div class="route-details">${detail}${params}${query}${body}${response}</div>`
+              : "";
+
+          return `<div class="route${expandClass}"${hasDetails ? ' onclick="this.classList.toggle(\'open\')"' : ""}>
+            <div class="route-header">
+              <span class="method" style="color:${color}">${esc(r.method)}</span>
+              <span class="path">${esc(r.path)}</span>
+              ${summary}
+            </div>
+            ${detailBlock}
+          </div>`;
+        })
+        .join("\n");
+
+      const badges = [
+        svc.auth
+          ? '<span class="badge auth">auth</span>'
+          : '<span class="badge public">public</span>',
+        svc.capabilities.hasTools
+          ? '<span class="badge tools">tools</span>'
+          : "",
+        svc.capabilities.hasBehaviors
+          ? '<span class="badge behaviors">behaviors</span>'
+          : "",
+        svc.capabilities.hasWidget
+          ? '<span class="badge widget">widget</span>'
+          : "",
+        svc.capabilities.hasStore
+          ? '<span class="badge store">store</span>'
+          : "",
+      ]
+        .filter(Boolean)
+        .join(" ");
+
+      const deps = svc.dependencies.length
+        ? `<div class="deps">depends on: ${svc.dependencies.map((d) => `<code>${esc(d)}</code>`).join(", ")}</div>`
+        : "";
+
+      return `<div class="service" id="svc-${esc(svc.name)}">
+        <div class="service-header">
+          <h2><a href="#svc-${esc(svc.name)}">/${esc(svc.name)}</a></h2>
+          <div class="badges">${badges}</div>
+        </div>
+        ${svc.description ? `<p class="desc">${esc(svc.description)}</p>` : ""}
+        ${deps}
+        <div class="routes">${routes || '<div class="empty">No routes</div>'}</div>
+      </div>`;
+    })
+    .join("\n");
+
+  const nav = docs
+    .map(
+      (svc) =>
+        `<a href="#svc-${esc(svc.name)}" class="nav-item">/${esc(svc.name)} <span class="route-count">${svc.routes.length}</span></a>`,
+    )
+    .join("\n");
+
+  const totalRoutes = docs.reduce((sum, s) => sum + s.routes.length, 0);
+  const documented = docs.reduce(
+    (sum, s) => sum + s.routes.filter((r) => r.summary).length,
+    0,
+  );
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Fleet Services — API Docs</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    :root {
+      --bg: #0a0a0a; --bg-panel: #111; --bg-card: #1a1a1a;
+      --border: #2a2a2a; --text: #ccc; --text-dim: #666;
+      --text-bright: #eee; --accent: #4f9;
+    }
+    html, body {
+      height: 100%; background: var(--bg); color: var(--text);
+      font-family: 'SF Mono', 'Cascadia Code', 'Fira Code', monospace;
+      font-size: 13px; line-height: 1.6;
+    }
+    .layout { display: flex; height: 100vh; }
+    .sidebar {
+      width: 220px; background: var(--bg-panel); border-right: 1px solid var(--border);
+      padding: 16px 0; overflow-y: auto; flex-shrink: 0;
+    }
+    .sidebar h1 {
+      font-size: 13px; color: var(--accent); padding: 0 16px 12px;
+      border-bottom: 1px solid var(--border); margin-bottom: 8px; font-weight: 600;
+    }
+    .sidebar .summary { font-size: 11px; color: var(--text-dim); padding: 0 16px 12px; }
+    .nav-item {
+      display: flex; justify-content: space-between; align-items: center;
+      padding: 4px 16px; color: var(--text-dim); text-decoration: none;
+      font-size: 12px; transition: all 0.1s;
+    }
+    .nav-item:hover { color: var(--text); background: var(--bg-card); }
+    .route-count {
+      font-size: 10px; background: var(--bg-card); padding: 1px 6px;
+      border-radius: 3px; color: var(--text-dim);
+    }
+    .content { flex: 1; overflow-y: auto; padding: 24px 32px; }
+    .service {
+      margin-bottom: 32px; padding-bottom: 24px;
+      border-bottom: 1px solid var(--border);
+    }
+    .service:last-child { border-bottom: none; }
+    .service-header { display: flex; align-items: center; gap: 12px; margin-bottom: 8px; }
+    .service-header h2 { font-size: 16px; font-weight: 600; }
+    .service-header h2 a { color: var(--text-bright); text-decoration: none; }
+    .service-header h2 a:hover { color: var(--accent); }
+    .desc { color: var(--text-dim); margin-bottom: 8px; font-size: 12px; }
+    .deps { color: var(--text-dim); font-size: 11px; margin-bottom: 8px; }
+    .deps code { color: var(--accent); }
+    .badges { display: flex; gap: 4px; }
+    .badge {
+      font-size: 10px; padding: 2px 8px; border-radius: 3px;
+      text-transform: uppercase; letter-spacing: 0.5px; font-weight: 600;
+    }
+    .badge.auth { background: #2a1a1a; color: #f93; }
+    .badge.public { background: #1a2a1a; color: var(--accent); }
+    .badge.tools { background: #1a1a2a; color: #5af; }
+    .badge.behaviors { background: #2a1a2a; color: #a7f; }
+    .badge.widget { background: #2a2a1a; color: #fd0; }
+    .badge.store { background: #1a2a2a; color: #5cc; }
+    .routes { margin-top: 8px; }
+    .route {
+      margin: 2px 0; border-left: 2px solid var(--border);
+      transition: border-color 0.15s;
+    }
+    .route:hover { border-left-color: #444; }
+    .route.expandable { cursor: pointer; }
+    .route.expandable .route-header::after {
+      content: "▸"; color: var(--text-dim); font-size: 10px; margin-left: auto;
+      transition: transform 0.15s;
+    }
+    .route.open .route-header::after { transform: rotate(90deg); }
+    .route-header {
+      display: flex; align-items: center; gap: 8px;
+      padding: 6px 12px; font-size: 13px;
+    }
+    .route-header:hover { background: var(--bg-card); }
+    .method { display: inline-block; width: 65px; font-weight: 700; flex-shrink: 0; }
+    .path { color: var(--text-bright); }
+    .summary { color: var(--text-dim); font-size: 12px; margin-left: 8px; }
+    .route-details {
+      display: none; padding: 8px 12px 12px 24px;
+      border-top: 1px solid var(--border); background: var(--bg-panel);
+      font-size: 12px;
+    }
+    .route.open .route-details { display: block; }
+    .detail { color: var(--text-dim); margin-bottom: 8px; font-style: italic; }
+    .param-table { margin: 8px 0; }
+    .param-table-title {
+      font-size: 10px; text-transform: uppercase; letter-spacing: 0.5px;
+      color: var(--text-dim); margin-bottom: 4px; font-weight: 600;
+    }
+    .param-row {
+      display: flex; gap: 8px; padding: 3px 0;
+      border-bottom: 1px solid #1a1a1a; align-items: baseline;
+    }
+    .param-row:last-child { border-bottom: none; }
+    .param-name { color: var(--accent); font-weight: 600; min-width: 120px; flex-shrink: 0; }
+    .param-type { color: #5af; font-size: 11px; min-width: 80px; flex-shrink: 0; }
+    .param-required { color: #f93; font-size: 10px; font-weight: 600; }
+    .param-desc { color: var(--text-dim); }
+    .field-label { color: var(--text-dim); font-size: 10px; text-transform: uppercase; letter-spacing: 0.5px; font-weight: 600; }
+    .response-doc { margin-top: 8px; }
+    .response-text { color: var(--text); }
+    .empty { color: var(--text-dim); font-style: italic; padding: 8px 12px; }
+    @media (max-width: 700px) {
+      .sidebar { display: none; }
+      .content { padding: 16px; }
+    }
+  </style>
+</head>
+<body>
+  <div class="layout">
+    <div class="sidebar">
+      <h1>▸ API Docs</h1>
+      <div class="summary">${docs.length} services · ${totalRoutes} routes · ${documented} documented</div>
+      ${nav}
+    </div>
+    <div class="content">
+      ${services}
+    </div>
+  </div>
+</body>
+</html>`;
+}
+
+function renderParamTable(
+  title: string,
+  params?: Record<string, ParamDoc>,
+): string {
+  if (!params || Object.keys(params).length === 0) return "";
+
+  const rows = Object.entries(params)
+    .map(([name, p]) => {
+      const req = p.required
+        ? ' <span class="param-required">required</span>'
+        : "";
+      return `<div class="param-row">
+        <span class="param-name">${esc(name)}${req}</span>
+        <span class="param-type">${esc(p.type)}</span>
+        <span class="param-desc">${esc(p.description ?? "")}</span>
+      </div>`;
+    })
+    .join("\n");
+
+  return `<div class="param-table">
+    <div class="param-table-title">${esc(title)}</div>
+    ${rows}
+  </div>`;
+}
+
+function esc(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+// =============================================================================
+// Routes
+// =============================================================================
+
+const routes = new Hono();
+
+routes.get("/", (c) => c.json({ services: documentAll() }));
+
+routes.get("/ui", (c) => c.html(renderHTML(documentAll())));
+
+routes.get("/:service", (c) => {
+  const name = c.req.param("service");
+  const mod = ctx.getModule(name);
+  if (!mod) return c.json({ error: `Service "${name}" not found` }, 404);
+  return c.json(documentService(mod));
+});
+
+// =============================================================================
+// Module
+// =============================================================================
+
+const docs: ServiceModule = {
+  name: "docs",
+  description: "Auto-generated API documentation",
+  routes,
+  requiresAuth: false,
+
+  init(serviceCtx: ServiceContext) {
+    ctx = serviceCtx;
+  },
+};
+
+export default docs;

package/services/feed/behaviors.ts

@@ -0,0 +1,23 @@
+/**
+ * Feed behaviors — auto-publish agent lifecycle events.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { FleetClient } from "../src/core/types.js";
+
+export function registerBehaviors(pi: ExtensionAPI, client: FleetClient) {
+  pi.on("agent_start", async () => {
+    if (!client.getBaseUrl()) return;
+    try {
+      await client.api("POST", "/feed/events", {
+        agent: client.agentName,
+        type: "agent_started",
+        summary: `Agent ${client.agentName} started processing`,
+      });
+    } catch {
+      // best-effort
+    }
+  });
+
+  // agent_end publish is handled by the usage service (it has cost data to include)
+}

package/services/feed/index.ts

@@ -0,0 +1,117 @@
+/**
+ * Feed service module — activity event stream for coordination and observability.
+ *
+ * Listens to server-side events from other modules and auto-publishes
+ * them as feed events:
+ *   board:task_created  → feed event "task_started"
+ *   board:task_updated  → feed event "task_completed" (if status=done)
+ *   board:task_deleted  → (ignored)
+ */
+
+import type { ServiceModule, ServiceContext, FleetClient } from "../src/core/types.js";
+import { FeedStore } from "./store.js";
+import { createRoutes } from "./routes.js";
+import { registerTools } from "./tools.js";
+import { registerBehaviors } from "./behaviors.js";
+
+const store = new FeedStore();
+
+const feed: ServiceModule = {
+  name: "feed",
+  description: "Activity event stream",
+  routes: createRoutes(store),
+  registerTools,
+  registerBehaviors,
+
+  routeDocs: {
+    "POST /events": {
+      summary: "Publish an event to the feed",
+      body: {
+        agent: { type: "string", required: true, description: "Agent name that produced the event" },
+        type: { type: "string", required: true, description: "task_started | task_completed | task_failed | blocker_found | question | finding | skill_proposed | file_changed | cost_update | agent_started | agent_stopped | token_update | custom" },
+        summary: { type: "string", required: true, description: "Short human-readable summary" },
+        detail: { type: "string", description: "Longer detail or structured JSON string" },
+        metadata: { type: "object", description: "Arbitrary key-value metadata" },
+      },
+      response: "The created event with generated ID and timestamp",
+    },
+    "GET /events": {
+      summary: "List recent events with optional filters",
+      query: {
+        agent: { type: "string", description: "Filter by agent name" },
+        type: { type: "string", description: "Filter by event type" },
+        since: { type: "string", description: "ULID or ISO timestamp — return events after this point" },
+        limit: { type: "number", description: "Max events to return. Default: 50" },
+      },
+      response: "Array of feed events, most recent last",
+    },
+    "GET /events/:id": {
+      summary: "Get a single event by ID",
+      params: { id: { type: "string", required: true, description: "Event ID (ULID)" } },
+    },
+    "DELETE /events": {
+      summary: "Clear all events",
+      detail: "Destructive — removes all events from memory and disk. Use with caution.",
+      response: "{ ok: true }",
+    },
+    "GET /stats": {
+      summary: "Get feed statistics",
+      response: "{ total, byAgent: { [name]: count }, byType: { [type]: count }, latestPerAgent: { [name]: Event } }",
+    },
+    "GET /stream": {
+      summary: "Server-Sent Events stream of new events in real time",
+      detail: "Connect with EventSource. Pass ?since=<ulid> to replay missed events on reconnect. Pass ?agent=<name> to filter by agent. Sends heartbeat comments every 15s.",
+      query: {
+        agent: { type: "string", description: "Filter to events from this agent only" },
+        since: { type: "string", description: "ULID — replay events since this ID before streaming" },
+      },
+      response: "SSE stream. Each message data is a JSON-encoded FeedEvent.",
+    },
+  },
+
+  init(ctx: ServiceContext) {
+    ctx.events.on("board:task_created", (data: any) => {
+      const task = data.task;
+      store.publish({
+        agent: task.createdBy || "unknown",
+        type: "task_started",
+        summary: `Task created: ${task.title}`,
+        metadata: { taskId: task.id, status: task.status },
+      });
+    });
+
+    ctx.events.on("board:task_updated", (data: any) => {
+      const task = data.task;
+      const changes = data.changes || {};
+
+      if (changes.status === "done") {
+        store.publish({
+          agent: task.assignee || task.createdBy || "unknown",
+          type: "task_completed",
+          summary: `Task completed: ${task.title}`,
+          metadata: { taskId: task.id },
+        });
+      } else if (changes.status === "blocked") {
+        store.publish({
+          agent: task.assignee || task.createdBy || "unknown",
+          type: "blocker_found",
+          summary: `Task blocked: ${task.title}`,
+          metadata: { taskId: task.id },
+        });
+      }
+    });
+  },
+
+  widget: {
+    async getLines(client: FleetClient) {
+      try {
+        const stats = await client.api<{ total: number }>("GET", "/feed/stats");
+        return [`Feed: ${stats.total} events`];
+      } catch {
+        return [];
+      }
+    },
+  },
+};
+
+export default feed;