ndomo 0.1.0

package/src/http/routes/sessions.ts

@@ -0,0 +1,50 @@
+// ─── Sessions Routes ──────────────────────────────────────────────────────────
+/**
+ * GET /api/sessions          — list sessions (optional: planId, limit)
+ * GET /api/sessions/active   — list active sessions (endedAt === null)
+ * GET /api/sessions/:id      — get single session by id
+ */
+import type { Database } from "bun:sqlite";
+import { Elysia, t } from "elysia";
+import { getSession, listSessions } from "../../db/sessions.ts";
+
+export function sessionsRoute(db: Database) {
+  return new Elysia({ name: "sessions" })
+    .get(
+      "/api/sessions",
+      async ({ query }) => {
+        const opts: { planId?: string; limit?: number } = {};
+        if (query.planId) opts.planId = query.planId;
+        if (query.limit) opts.limit = query.limit;
+        return listSessions(db, opts);
+      },
+      {
+        query: t.Object({
+          planId: t.Optional(t.String()),
+          limit: t.Optional(t.Number({ minimum: 1, maximum: 100 })),
+        }),
+      },
+    )
+    .get(
+      "/api/sessions/active",
+      async () => {
+        // Fetch all recent sessions and filter active (endedAt === null)
+        const all = listSessions(db, { limit: 20 });
+        return all.filter((s) => s.endedAt === null);
+      },
+    )
+    .get(
+      "/api/sessions/:id",
+      async ({ params: { id }, set }) => {
+        const session = getSession(db, id);
+        if (!session) {
+          set.status = 404;
+          return { error: "not_found", message: `session ${id} not found` };
+        }
+        return session;
+      },
+      {
+        params: t.Object({ id: t.String() }),
+      },
+    );
+}

package/src/http/routes/tasks.ts

@@ -0,0 +1,60 @@
+// ─── Tasks Routes ─────────────────────────────────────────────────────────────
+/**
+ * GET /api/tasks           — list tasks by planId (required), optional: status
+ * GET /api/tasks/search    — FTS5 search (required: q, optional: limit)
+ * GET /api/tasks/:id       — get single task by id
+ */
+import type { Database } from "bun:sqlite";
+import { Elysia, t } from "elysia";
+import { getTask, listTasksByPlan, searchTasks } from "../../db/tasks.ts";
+import type { TaskStatus } from "../../db/types.ts";
+
+const TaskStatusValues = ["pending", "running", "done", "failed", "blocked"] as const;
+
+export function tasksRoute(db: Database) {
+  return new Elysia({ name: "tasks" })
+    .get(
+      "/api/tasks",
+      async ({ query, set }) => {
+        if (!query.planId) {
+          set.status = 422;
+          return { error: "validation_error", message: "planId is required" };
+        }
+        const opts: { status?: TaskStatus } = {};
+        if (query.status) opts.status = query.status as TaskStatus;
+        return listTasksByPlan(db, query.planId, opts);
+      },
+      {
+        query: t.Object({
+          planId: t.String(),
+          status: t.Optional(t.UnionEnum(TaskStatusValues)),
+        }),
+      },
+    )
+    .get(
+      "/api/tasks/search",
+      async ({ query }) => {
+        return searchTasks(db, query.q, query.limit ?? 20);
+      },
+      {
+        query: t.Object({
+          q: t.String({ minLength: 1 }),
+          limit: t.Optional(t.Number({ minimum: 1, maximum: 100 })),
+        }),
+      },
+    )
+    .get(
+      "/api/tasks/:id",
+      async ({ params: { id }, set }) => {
+        const task = getTask(db, id);
+        if (!task) {
+          set.status = 404;
+          return { error: "not_found", message: `task ${id} not found` };
+        }
+        return task;
+      },
+      {
+        params: t.Object({ id: t.String() }),
+      },
+    );
+}

package/src/http/server.ts

@@ -0,0 +1,95 @@
+// ─── HTTP Server Builder ──────────────────────────────────────────────────────
+/**
+ * Builds and starts the Elysia HTTP server for ndomo.
+ *
+ * Encapsulation order:
+ * 1. securityHeaders (global)
+ * 2. corsMiddleware (global)
+ * 3. httpBasicAuth (global — applied to /api/* via guard, exempt /health)
+ * 4. health route (no auth)
+ * 5. /api/plans, /api/tasks, /api/sessions (auth required)
+ */
+import type { Database } from "bun:sqlite";
+import type { OpencodeClient } from "@opencode-ai/sdk/client";
+import { Elysia } from "elysia";
+import type { HttpConfig } from "../config/schema.ts";
+import { httpBasicAuth } from "./auth.ts";
+import { corsMiddleware } from "./middleware/cors.ts";
+import { securityHeaders } from "./middleware/security-headers.ts";
+import { eventsRoute } from "./routes/events.ts";
+import { healthRoute } from "./routes/health.ts";
+import { plansRoute } from "./routes/plans.ts";
+import { sessionsRoute } from "./routes/sessions.ts";
+import { tasksRoute } from "./routes/tasks.ts";
+
+interface BuildHttpServerArgs {
+  db: Database;
+  httpConfig: HttpConfig;
+  /** OpenCode SDK client for SSE events. If null/undefined, /api/events returns 503. */
+  sdkClient?: OpencodeClient;
+}
+
+export interface HttpServerHandle {
+  port: number;
+  stop: () => Promise<void>;
+}
+
+/**
+ * Build the Elysia app with all middleware and routes.
+ * Returns the app instance and a listen function.
+ *
+ * @throws if port is out of range 1-65535
+ * @throws if auth is required but OPENCODE_SERVER_PASSWORD is not set
+ */
+export async function buildHttpServer(args: BuildHttpServerArgs) {
+  const { db, httpConfig } = args;
+
+  // Validate port range
+  if (httpConfig.port < 1 || httpConfig.port > 65535) {
+    throw new Error(`Invalid HTTP port: ${httpConfig.port}. Must be 1-65535.`);
+  }
+
+  // If auth required but password not set, fail fast (do not start)
+  if (httpConfig.auth.required && !process.env.OPENCODE_SERVER_PASSWORD) {
+    throw new Error(
+      "HTTP auth is required but OPENCODE_SERVER_PASSWORD is not set. Cannot start server.",
+    );
+  }
+
+  // Build the protected API sub-app first
+  const apiProtected = new Elysia({ name: "api-protected" })
+    .use(httpBasicAuth(httpConfig))
+    .use(plansRoute(db))
+    .use(tasksRoute(db))
+    .use(sessionsRoute(db))
+    .use(eventsRoute(args.sdkClient ?? null));
+
+  // Compose the full app
+  const app = new Elysia({ name: "ndomo-http" })
+    .use(securityHeaders)
+    .use(corsMiddleware(httpConfig.cors.origins))
+    .use(healthRoute(db))
+    .use(apiProtected);
+
+  return {
+    app: app as unknown as Elysia,
+    listen: async (port: number): Promise<HttpServerHandle> => {
+      const server = app.listen(port);
+      return {
+        port,
+        stop: async () => {
+          server.stop();
+        },
+      };
+    },
+  };
+}
+
+/**
+ * Convenience: build + listen in one call.
+ * Returns the running server handle.
+ */
+export async function startHttpServer(args: BuildHttpServerArgs): Promise<HttpServerHandle> {
+  const { listen } = await buildHttpServer(args);
+  return listen(args.httpConfig.port);
+}

package/src/http/sse.ts

@@ -0,0 +1,116 @@
+// ─── SSE Format Helpers ──────────────────────────────────────────────────────
+/**
+ * Pure functions for encoding Server-Sent Events (SSE) format.
+ *
+ * SSE spec: https://html.spec.whatwg.org/multipage/server-sent-events.html
+ * Format: `field: value\n` lines terminated by `\n` (blank line = end of event).
+ *
+ * All functions return strings — callers encode to Uint8Array themselves.
+ */
+import type { ReadableStreamDefaultController } from "node:stream/web";
+
+/**
+ * Encode a single event in SSE format.
+ *
+ * @param opts.eventName - optional event name (maps to `event:` field)
+ * @param opts.data - JSON-serializable payload (multi-line data splits into multiple `data:` lines)
+ * @param opts.id - optional event ID (for Last-Event-ID resume)
+ * @returns SSE-formatted string ending with `\n\n`
+ */
+export function formatSseEvent(opts: { eventName?: string; data: unknown; id?: string }): string {
+  const lines: string[] = [];
+  if (opts.eventName) lines.push(`event: ${opts.eventName}`);
+  if (opts.id) lines.push(`id: ${opts.id}`);
+  // Multi-line data must split each line into a separate `data:` field
+  const dataStr = JSON.stringify(opts.data);
+  for (const line of dataStr.split("\n")) lines.push(`data: ${line}`);
+  return `${lines.join("\n")}\n\n`;
+}
+
+/**
+ * SSE keepalive comment — prevents proxy/load-balancer timeouts.
+ * Format: `: keepalive\n\n` (colon = comment, ignored by clients).
+ */
+export function formatKeepalive(): string {
+  return ": keepalive\n\n\n";
+}
+
+/**
+ * Writer interface for SSE streams.
+ *
+ * Abstracts the ReadableStream controller + abort signal into a
+ * clean API that handles encoding, error suppression, and cleanup.
+ */
+export interface SseWriter {
+  /** Write a named event with JSON data. */
+  write(eventName: string | null, data: unknown): void;
+  /** Write a keepalive comment to prevent proxy timeouts. */
+  writeKeepalive(): void;
+  /** Close the stream. */
+  end(): void;
+  /** Register a cleanup callback invoked on abort. */
+  onCleanup(cb: () => void): void;
+}
+
+/**
+ * Wrap a Node ReadableStream controller + abort signal into a SseWriter.
+ *
+ * The writer suppresses all write errors (controller already closed)
+ * and runs registered cleanup callbacks when the abort signal fires.
+ *
+ * @param controller - the ReadableStream controller to write to
+ * @param signal - abort signal (from request.signal) for cleanup
+ */
+export function createSseWriter(
+  controller: ReadableStreamDefaultController<Uint8Array>,
+  signal: AbortSignal,
+): SseWriter {
+  const encoder = new TextEncoder();
+  const cleanups: Array<() => void> = [];
+
+  signal.addEventListener("abort", () => {
+    for (const cb of cleanups) {
+      try {
+        cb();
+      } catch {
+        /* ignore cleanup errors */
+      }
+    }
+    try {
+      controller.close();
+    } catch {
+      /* already closed */
+    }
+  });
+
+  return {
+    write(eventName, data) {
+      try {
+        const chunk = formatSseEvent({
+          ...(eventName !== null ? { eventName } : {}),
+          data,
+        });
+        controller.enqueue(encoder.encode(chunk));
+      } catch {
+        // Controller closed — ignore
+      }
+    },
+    writeKeepalive() {
+      try {
+        controller.enqueue(encoder.encode(formatKeepalive()));
+      } catch {
+        /* ignore */
+      }
+    },
+    end() {
+      try {
+        controller.close();
+      } catch {
+        /* ignore */
+      }
+    },
+    onCleanup(cb) {
+      cleanups.push(cb);
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * ndomo — OpenCode multi-agent plugin.
+ *
+ * Entry point. Import as a plugin in opencode.json:
+ * ```jsonc
+ * { "plugin": ["ndomo"] }
+ * ```
+ */
+
+export type {
+  BackgroundTask,
+  DispatchOptions,
+  IntegrityReport,
+  MemoryEntry,
+  ReconciliationReport,
+  RoutingDecision,
+  TaskRequest,
+  TaskResult,
+  Worktree,
+  WorktreeState,
+} from "./lib.ts";
+export {
+  BackgroundDispatcher,
+  canRunParallel,
+  cavemanCompress,
+  createWorktree,
+  getProjectTag,
+  listActive,
+  memorySearchOptions,
+  prepareForMemory,
+  reconcileResults,
+  removeWorktree,
+  routeTask,
+  shouldStoreMemory,
+  verifyIntegrity,
+} from "./lib.ts";
+export { NdomoPlugin, type NdomoPluginOptions } from "./plugin.ts";

package/src/lib.ts

@@ -0,0 +1,65 @@
+/**
+ * ndomo — OpenCode multi-agent orchestrator.
+ *
+ * Entry point that re-exports all public APIs.
+ *
+ * @example
+ * ```ts
+ * import { routeTask, BackgroundDispatcher, cavemanCompress } from "ndomo";
+ * ```
+ */
+
+// Memory: scoped tag helpers
+export {
+  getAllTags,
+  getProjectTag,
+  getUserTag,
+  memoryAddOptions,
+  memorySearchOptions,
+} from "./mem/scoped.ts";
+
+// Orchestrator: background dispatcher
+export {
+  BackgroundDispatcher,
+  type BackgroundTask,
+  type DispatchOptions,
+} from "./orchestrator/background.ts";
+// Orchestrator: memory hooks
+export {
+  cavemanCompress,
+  type MemoryEntry,
+  prepareForMemory,
+  shouldStoreMemory,
+} from "./orchestrator/memory-hook.ts";
+// Orchestrator: result reconciliation
+export {
+  type ReconciliationReport,
+  reconcileResults,
+  type TaskResult,
+} from "./orchestrator/reconciler.ts";
+// Orchestrator: scheduler
+export {
+  canRunParallel,
+  type RoutingDecision,
+  routeTask,
+  type TaskRequest,
+} from "./orchestrator/scheduler.ts";
+
+// Worktrees: git worktree manager
+export {
+  cleanup,
+  createWorktree,
+  getWorktree,
+  listActive,
+  loadState,
+  removeWorktree,
+  saveState,
+  type Worktree,
+  type WorktreeState,
+} from "./worktrees/manager.ts";
+
+// Worktrees: integrity verification
+export {
+  type IntegrityReport,
+  verifyIntegrity,
+} from "./worktrees/state.ts";

package/src/mem/scoped.ts

@@ -0,0 +1,65 @@
+/**
+ * Project-scoped memory helpers wrapping opencode-mem/tags.
+ * Provides convenience functions for tag resolution and memory operations.
+ */
+
+import { getProjectTagInfo, getTags, getUserTagInfo } from "opencode-mem/tags";
+
+/**
+ * Get the project tag for the current (or specified) working directory.
+ *
+ * @param cwd - Working directory. Defaults to process.cwd().
+ * @returns Project tag string (e.g. "project:ndomo:abc123").
+ */
+export function getProjectTag(cwd?: string): string {
+  return getProjectTagInfo(cwd ?? process.cwd()).tag;
+}
+
+/**
+ * Get the user tag for the current system user.
+ *
+ * @returns User tag string (e.g. "user:nico:xyz789").
+ */
+export function getUserTag(): string {
+  return getUserTagInfo().tag;
+}
+
+/**
+ * Get both user and project tags for a directory.
+ *
+ * @param cwd - Working directory. Defaults to process.cwd().
+ * @returns Object with user and project TagInfo.
+ */
+export function getAllTags(cwd?: string) {
+  return getTags(cwd ?? process.cwd());
+}
+
+/**
+ * Build options object for a memory search operation.
+ *
+ * @param query - Search query text.
+ * @param scope - Search scope: "project" (default) or "all-projects".
+ * @returns Options object for the opencode-mem search API.
+ */
+export function memorySearchOptions(query: string, scope: "project" | "all-projects" = "project") {
+  return {
+    mode: "search" as const,
+    query,
+    scope,
+  };
+}
+
+/**
+ * Build options object for a memory add operation.
+ *
+ * @param content - Content to store in memory.
+ * @param topic - Topic/category for the memory entry.
+ * @returns Options object for the opencode-mem add API.
+ */
+export function memoryAddOptions(content: string, topic: string) {
+  return {
+    mode: "add" as const,
+    content,
+    topic,
+  };
+}