bopodev-api 0.1.1

package/src/routes/heartbeats.ts

@@ -0,0 +1,61 @@
+import { Router } from "express";
+import { z } from "zod";
+import { and, eq } from "drizzle-orm";
+import { agents } from "bopodev-db";
+import type { AppContext } from "../context";
+import { sendError, sendOk } from "../http";
+import { requireCompanyScope } from "../middleware/company-scope";
+import { requirePermission } from "../middleware/request-actor";
+import { runHeartbeatForAgent, runHeartbeatSweep } from "../services/heartbeat-service";
+
+const runAgentSchema = z.object({
+  agentId: z.string().min(1)
+});
+
+export function createHeartbeatRouter(ctx: AppContext) {
+  const router = Router();
+  router.use(requireCompanyScope);
+
+  router.post("/run-agent", async (req, res) => {
+    requirePermission("heartbeats:run")(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const parsed = runAgentSchema.safeParse(req.body);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const [agent] = await ctx.db
+      .select({ id: agents.id, status: agents.status })
+      .from(agents)
+      .where(and(eq(agents.companyId, req.companyId!), eq(agents.id, parsed.data.agentId)))
+      .limit(1);
+    if (!agent) {
+      return sendError(res, "Agent not found.", 404);
+    }
+    if (agent.status === "paused" || agent.status === "terminated") {
+      return sendError(res, `Agent is not invokable in status '${agent.status}'.`, 409);
+    }
+
+    const runId = await runHeartbeatForAgent(ctx.db, req.companyId!, parsed.data.agentId, {
+      requestId: req.requestId,
+      trigger: "manual",
+      realtimeHub: ctx.realtimeHub
+    });
+    return sendOk(res, { runId, requestId: req.requestId });
+  });
+
+  router.post("/sweep", async (req, res) => {
+    requirePermission("heartbeats:sweep")(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const runIds = await runHeartbeatSweep(ctx.db, req.companyId!, {
+      requestId: req.requestId,
+      realtimeHub: ctx.realtimeHub
+    });
+    return sendOk(res, { runIds, requestId: req.requestId });
+  });
+
+  return router;
+}

package/src/routes/issues.ts

@@ -0,0 +1,319 @@
+import { Router } from "express";
+import { z } from "zod";
+import {
+  addIssueComment,
+  appendActivity,
+  appendAuditEvent,
+  createIssue,
+  deleteIssueComment,
+  deleteIssue,
+  listIssueComments,
+  listIssues,
+  updateIssueComment,
+  updateIssue
+} from "bopodev-db";
+import type { AppContext } from "../context";
+import { sendError, sendOk } from "../http";
+import { requireCompanyScope } from "../middleware/company-scope";
+import { requirePermission } from "../middleware/request-actor";
+
+const createIssueSchema = z.object({
+  projectId: z.string().min(1),
+  parentIssueId: z.string().optional(),
+  title: z.string().min(1),
+  body: z.string().optional(),
+  status: z.enum(["todo", "in_progress", "blocked", "in_review", "done", "canceled"]).default("todo"),
+  priority: z.enum(["none", "low", "medium", "high", "urgent"]).default("none"),
+  assigneeAgentId: z.string().nullable().optional(),
+  labels: z.array(z.string()).default([]),
+  tags: z.array(z.string()).default([])
+});
+
+const createIssueCommentSchema = z.object({
+  body: z.string().min(1),
+  authorType: z.enum(["human", "agent", "system"]).default("human"),
+  authorId: z.string().optional()
+});
+
+const createIssueCommentLegacySchema = z.object({
+  issueId: z.string().min(1),
+  body: z.string().min(1),
+  authorType: z.enum(["human", "agent", "system"]).default("human"),
+  authorId: z.string().optional()
+});
+
+const updateIssueCommentSchema = z.object({
+  body: z.string().min(1)
+});
+
+function parseStringArray(value: unknown) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => String(entry));
+  }
+  if (typeof value !== "string") {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed.map((entry) => String(entry)) : [];
+  } catch {
+    return [];
+  }
+}
+
+function toIssueResponse(issue: Record<string, unknown>) {
+  const labels = parseStringArray(issue.labelsJson);
+  const tags = parseStringArray(issue.tagsJson);
+  const { labelsJson: _labelsJson, tagsJson: _tagsJson, ...rest } = issue;
+  return {
+    ...rest,
+    labels,
+    tags
+  };
+}
+
+const updateIssueSchema = z
+  .object({
+    projectId: z.string().min(1).optional(),
+    title: z.string().min(1).optional(),
+    body: z.string().nullable().optional(),
+    status: z.enum(["todo", "in_progress", "blocked", "in_review", "done", "canceled"]).optional(),
+    priority: z.enum(["none", "low", "medium", "high", "urgent"]).optional(),
+    assigneeAgentId: z.string().nullable().optional(),
+    labels: z.array(z.string()).optional(),
+    tags: z.array(z.string()).optional()
+  })
+  .refine((payload) => Object.keys(payload).length > 0, "At least one field must be provided.");
+
+export function createIssuesRouter(ctx: AppContext) {
+  const router = Router();
+  router.use(requireCompanyScope);
+
+  router.get("/", async (req, res) => {
+    const projectId = req.query.projectId?.toString();
+    const rows = await listIssues(ctx.db, req.companyId!, projectId);
+    return sendOk(
+      res,
+      rows.map((row) => toIssueResponse(row as unknown as Record<string, unknown>))
+    );
+  });
+
+  router.post("/", async (req, res) => {
+    requirePermission("issues:write")(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const parsed = createIssueSchema.safeParse(req.body);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const issue = await createIssue(ctx.db, { companyId: req.companyId!, ...parsed.data });
+    await appendActivity(ctx.db, {
+      companyId: req.companyId!,
+      issueId: issue.id,
+      actorType: "human",
+      eventType: "issue.created",
+      payload: { issue }
+    });
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: "human",
+      eventType: "issue.created",
+      entityType: "issue",
+      entityId: issue.id,
+      payload: issue
+    });
+    return sendOk(res, toIssueResponse(issue as unknown as Record<string, unknown>));
+  });
+
+  router.get("/:issueId/comments", async (req, res) => {
+    const comments = await listIssueComments(ctx.db, req.companyId!, req.params.issueId);
+    return sendOk(res, comments);
+  });
+
+  router.post("/:issueId/comments", async (req, res) => {
+    requirePermission("issues:write")(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const parsed = createIssueCommentSchema.safeParse(req.body);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const comment = await addIssueComment(ctx.db, {
+      companyId: req.companyId!,
+      issueId: req.params.issueId,
+      ...parsed.data
+    });
+    await appendActivity(ctx.db, {
+      companyId: req.companyId!,
+      issueId: comment.issueId,
+      actorType: comment.authorType,
+      actorId: comment.authorId,
+      eventType: "issue.comment_added",
+      payload: { commentId: comment.id }
+    });
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: comment.authorType,
+      actorId: comment.authorId,
+      eventType: "issue.comment_added",
+      entityType: "issue_comment",
+      entityId: comment.id,
+      payload: comment
+    });
+    return sendOk(res, comment);
+  });
+
+  // Backward-compatible endpoint used by older clients.
+  router.post("/comment", async (req, res) => {
+    requirePermission("issues:write")(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const parsed = createIssueCommentLegacySchema.safeParse(req.body);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const comment = await addIssueComment(ctx.db, { companyId: req.companyId!, ...parsed.data });
+    await appendActivity(ctx.db, {
+      companyId: req.companyId!,
+      issueId: comment.issueId,
+      actorType: comment.authorType,
+      actorId: comment.authorId,
+      eventType: "issue.comment_added",
+      payload: { commentId: comment.id }
+    });
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: comment.authorType,
+      actorId: comment.authorId,
+      eventType: "issue.comment_added",
+      entityType: "issue_comment",
+      entityId: comment.id,
+      payload: comment
+    });
+    return sendOk(res, comment);
+  });
+
+  router.put("/:issueId/comments/:commentId", async (req, res) => {
+    requirePermission("issues:write")(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const parsed = updateIssueCommentSchema.safeParse(req.body);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+
+    const comment = await updateIssueComment(ctx.db, {
+      companyId: req.companyId!,
+      issueId: req.params.issueId,
+      id: req.params.commentId,
+      body: parsed.data.body
+    });
+    if (!comment) {
+      return sendError(res, "Comment not found.", 404);
+    }
+
+    await appendActivity(ctx.db, {
+      companyId: req.companyId!,
+      issueId: req.params.issueId,
+      actorType: "human",
+      eventType: "issue.comment_updated",
+      payload: { commentId: comment.id }
+    });
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: "human",
+      eventType: "issue.comment_updated",
+      entityType: "issue_comment",
+      entityId: comment.id,
+      payload: comment
+    });
+    return sendOk(res, comment);
+  });
+
+  router.delete("/:issueId/comments/:commentId", async (req, res) => {
+    requirePermission("issues:write")(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const deleted = await deleteIssueComment(ctx.db, req.companyId!, req.params.issueId, req.params.commentId);
+    if (!deleted) {
+      return sendError(res, "Comment not found.", 404);
+    }
+
+    await appendActivity(ctx.db, {
+      companyId: req.companyId!,
+      issueId: req.params.issueId,
+      actorType: "human",
+      eventType: "issue.comment_deleted",
+      payload: { commentId: req.params.commentId }
+    });
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: "human",
+      eventType: "issue.comment_deleted",
+      entityType: "issue_comment",
+      entityId: req.params.commentId,
+      payload: { id: req.params.commentId, issueId: req.params.issueId }
+    });
+    return sendOk(res, { deleted: true });
+  });
+
+  router.put("/:issueId", async (req, res) => {
+    requirePermission("issues:write")(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const parsed = updateIssueSchema.safeParse(req.body);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+
+    const issue = await updateIssue(ctx.db, { companyId: req.companyId!, id: req.params.issueId, ...parsed.data });
+    if (!issue) {
+      return sendError(res, "Issue not found.", 404);
+    }
+
+    await appendActivity(ctx.db, {
+      companyId: req.companyId!,
+      issueId: issue.id,
+      actorType: "human",
+      eventType: "issue.updated",
+      payload: { issue }
+    });
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: "human",
+      eventType: "issue.updated",
+      entityType: "issue",
+      entityId: issue.id,
+      payload: issue
+    });
+    return sendOk(res, toIssueResponse(issue as unknown as Record<string, unknown>));
+  });
+
+  router.delete("/:issueId", async (req, res) => {
+    requirePermission("issues:write")(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const deleted = await deleteIssue(ctx.db, req.companyId!, req.params.issueId);
+    if (!deleted) {
+      return sendError(res, "Issue not found.", 404);
+    }
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: "human",
+      eventType: "issue.deleted",
+      entityType: "issue",
+      entityId: req.params.issueId,
+      payload: { id: req.params.issueId }
+    });
+    return sendOk(res, { deleted: true });
+  });
+
+  return router;
+}

package/src/routes/observability.ts

@@ -0,0 +1,47 @@
+import { Router } from "express";
+import { listAuditEvents, listCostEntries, listHeartbeatRuns } from "bopodev-db";
+import type { AppContext } from "../context";
+import { sendOk } from "../http";
+import { requireCompanyScope } from "../middleware/company-scope";
+
+export function createObservabilityRouter(ctx: AppContext) {
+  const router = Router();
+  router.use(requireCompanyScope);
+
+  router.get("/logs", async (req, res) => {
+    const rows = await listAuditEvents(ctx.db, req.companyId!);
+    return sendOk(
+      res,
+      rows.map((row) => ({
+        ...row,
+        payload: parsePayload(row.payloadJson)
+      }))
+    );
+  });
+
+  router.get("/costs", async (req, res) => {
+    const rows = await listCostEntries(ctx.db, req.companyId!);
+    return sendOk(
+      res,
+      rows.map((row) => ({
+        ...row,
+        usdCost: typeof row.usdCost === "number" ? row.usdCost : Number(row.usdCost ?? 0)
+      }))
+    );
+  });
+
+  router.get("/heartbeats", async (req, res) => {
+    return sendOk(res, await listHeartbeatRuns(ctx.db, req.companyId!));
+  });
+
+  return router;
+}
+
+function parsePayload(payloadJson: string) {
+  try {
+    const parsed = JSON.parse(payloadJson) as unknown;
+    return typeof parsed === "object" && parsed !== null ? parsed : {};
+  } catch {
+    return {};
+  }
+}

package/src/routes/projects.ts

@@ -0,0 +1,152 @@
+import { Router } from "express";
+import { z } from "zod";
+import { appendAuditEvent, createProject, deleteProject, listProjects, syncProjectGoals, updateProject } from "bopodev-db";
+import type { AppContext } from "../context";
+import { sendError, sendOk } from "../http";
+import { requireCompanyScope } from "../middleware/company-scope";
+import { requirePermission } from "../middleware/request-actor";
+
+const projectStatusSchema = z.enum(["planned", "active", "paused", "blocked", "completed", "archived"]);
+
+const createProjectSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().optional(),
+  status: projectStatusSchema.default("planned"),
+  plannedStartAt: z.string().optional(),
+  workspaceLocalPath: z.string().optional(),
+  workspaceGithubRepo: z.string().url().optional(),
+  goalIds: z.array(z.string().min(1)).default([])
+});
+
+const updateProjectSchema = z
+  .object({
+    name: z.string().min(1).optional(),
+    description: z.string().nullable().optional(),
+    status: projectStatusSchema.optional(),
+    plannedStartAt: z.string().nullable().optional(),
+    workspaceLocalPath: z.string().nullable().optional(),
+    workspaceGithubRepo: z.string().url().nullable().optional(),
+    goalIds: z.array(z.string().min(1)).optional()
+  })
+  .refine((payload) => Object.keys(payload).length > 0, "At least one field must be provided.");
+
+function parsePlannedStartAt(value?: string | null) {
+  if (!value) {
+    return null;
+  }
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) {
+    throw new Error("Invalid plannedStartAt value.");
+  }
+  return parsed;
+}
+
+export function createProjectsRouter(ctx: AppContext) {
+  const router = Router();
+  router.use(requireCompanyScope);
+
+  router.get("/", async (req, res) => {
+    const projects = await listProjects(ctx.db, req.companyId!);
+    return sendOk(res, projects);
+  });
+
+  router.post("/", async (req, res) => {
+    requirePermission("projects:write")(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const parsed = createProjectSchema.safeParse(req.body);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const project = await createProject(ctx.db, {
+      companyId: req.companyId!,
+      name: parsed.data.name,
+      description: parsed.data.description,
+      status: parsed.data.status,
+      plannedStartAt: parsePlannedStartAt(parsed.data.plannedStartAt),
+      workspaceLocalPath: parsed.data.workspaceLocalPath,
+      workspaceGithubRepo: parsed.data.workspaceGithubRepo
+    });
+    await syncProjectGoals(ctx.db, {
+      companyId: req.companyId!,
+      projectId: project.id,
+      goalIds: parsed.data.goalIds
+    });
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: "human",
+      eventType: "project.created",
+      entityType: "project",
+      entityId: project.id,
+      payload: project
+    });
+    return sendOk(res, project);
+  });
+
+  router.put("/:projectId", async (req, res) => {
+    requirePermission("projects:write")(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const parsed = updateProjectSchema.safeParse(req.body);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+
+    const project = await updateProject(ctx.db, {
+      companyId: req.companyId!,
+      id: req.params.projectId,
+      name: parsed.data.name,
+      description: parsed.data.description,
+      status: parsed.data.status,
+      plannedStartAt:
+        parsed.data.plannedStartAt === undefined ? undefined : parsePlannedStartAt(parsed.data.plannedStartAt),
+      workspaceLocalPath: parsed.data.workspaceLocalPath,
+      workspaceGithubRepo: parsed.data.workspaceGithubRepo
+    });
+    if (!project) {
+      return sendError(res, "Project not found.", 404);
+    }
+    if (parsed.data.goalIds) {
+      await syncProjectGoals(ctx.db, {
+        companyId: req.companyId!,
+        projectId: project.id,
+        goalIds: parsed.data.goalIds
+      });
+    }
+
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: "human",
+      eventType: "project.updated",
+      entityType: "project",
+      entityId: project.id,
+      payload: project
+    });
+    return sendOk(res, project);
+  });
+
+  router.delete("/:projectId", async (req, res) => {
+    requirePermission("projects:write")(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const deleted = await deleteProject(ctx.db, req.companyId!, req.params.projectId);
+    if (!deleted) {
+      return sendError(res, "Project not found.", 404);
+    }
+
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: "human",
+      eventType: "project.deleted",
+      entityType: "project",
+      entityId: req.params.projectId,
+      payload: { id: req.params.projectId }
+    });
+    return sendOk(res, { deleted: true });
+  });
+
+  return router;
+}

package/src/scripts/db-init.ts

@@ -0,0 +1,13 @@
+import { bootstrapDatabase } from "bopodev-db";
+
+async function main() {
+  const { client } = await bootstrapDatabase(process.env.BOPO_DB_PATH);
+  const maybeClose = (client as { close?: () => Promise<void> }).close;
+  if (maybeClose) {
+    await maybeClose.call(client);
+  }
+  // eslint-disable-next-line no-console
+  console.log("Database initialized.");
+}
+
+void main();

package/src/server.ts

@@ -0,0 +1,51 @@
+import { createServer } from "node:http";
+import { bootstrapDatabase } from "bopodev-db";
+import { checkRuntimeCommandHealth } from "bopodev-agent-sdk";
+import { createApp } from "./app";
+import { loadGovernanceRealtimeSnapshot } from "./realtime/governance";
+import { loadOfficeSpaceRealtimeSnapshot } from "./realtime/office-space";
+import { attachRealtimeHub } from "./realtime/hub";
+import { createHeartbeatScheduler } from "./worker/scheduler";
+
+async function main() {
+  const dbPath = process.env.BOPO_DB_PATH;
+  const port = Number(process.env.PORT ?? 4020);
+  const { db } = await bootstrapDatabase(dbPath);
+  const codexCommand = process.env.BOPO_CODEX_COMMAND ?? "codex";
+  const getRuntimeHealth = async () => {
+    const codex = await checkRuntimeCommandHealth(codexCommand, {
+      timeoutMs: 5_000
+    });
+    return {
+      codex
+    };
+  };
+  const startupCodexHealth = await checkRuntimeCommandHealth(codexCommand, {
+    timeoutMs: 5_000
+  });
+  if (!startupCodexHealth.available) {
+    // eslint-disable-next-line no-console
+    console.warn("[startup] Codex command preflight failed.", startupCodexHealth);
+  }
+
+  const server = createServer();
+  const realtimeHub = attachRealtimeHub(server, {
+    bootstrapLoaders: {
+      governance: (companyId) => loadGovernanceRealtimeSnapshot(db, companyId),
+      "office-space": (companyId) => loadOfficeSpaceRealtimeSnapshot(db, companyId)
+    }
+  });
+  const app = createApp({ db, getRuntimeHealth, realtimeHub });
+  server.on("request", app);
+  server.listen(port, () => {
+    // eslint-disable-next-line no-console
+    console.log(`BopoHQ API running on http://localhost:${port}`);
+  });
+
+  const defaultCompanyId = process.env.BOPO_DEFAULT_COMPANY_ID;
+  if (defaultCompanyId) {
+    createHeartbeatScheduler(db, defaultCompanyId, realtimeHub);
+  }
+}
+
+void main();

package/src/services/budget-service.ts

@@ -0,0 +1,31 @@
+import { and, eq } from "drizzle-orm";
+import type { BopoDb } from "bopodev-db";
+import { agents } from "bopodev-db";
+
+export interface BudgetCheckResult {
+  allowed: boolean;
+  hardStopped: boolean;
+  utilizationPct: number;
+}
+
+export async function checkAgentBudget(db: BopoDb, companyId: string, agentId: string): Promise<BudgetCheckResult> {
+  const [agent] = await db
+    .select()
+    .from(agents)
+    .where(and(eq(agents.companyId, companyId), eq(agents.id, agentId)))
+    .limit(1);
+
+  if (!agent) {
+    return { allowed: false, hardStopped: true, utilizationPct: 100 };
+  }
+
+  const monthlyBudget = Number(agent.monthlyBudgetUsd);
+  const usedBudget = Number(agent.usedBudgetUsd);
+  const utilizationPct = monthlyBudget <= 0 ? 0 : (usedBudget / monthlyBudget) * 100;
+
+  return {
+    allowed: utilizationPct < 100,
+    hardStopped: utilizationPct >= 100,
+    utilizationPct
+  };
+}