ndomo 0.1.0

package/src/db/sessions.test.ts

@@ -0,0 +1,80 @@
+/**
+ * Tests for ensureSession — the idempotent FK-integrity helper.
+ *
+ * Uses in-memory SQLite via bun:sqlite. Each test gets a fresh DB
+ * with the full schema applied by runMigrations.
+ */
+
+import { Database } from "bun:sqlite";
+import { beforeEach, describe, expect, test } from "bun:test";
+import { runMigrations } from "./migrations.ts";
+import { ensureSession, getSession } from "./sessions.ts";
+
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  db.exec("PRAGMA foreign_keys = ON");
+  runMigrations(db);
+});
+
+describe("ensureSession", () => {
+  test("inserts row when missing", () => {
+    const id = crypto.randomUUID();
+    ensureSession(db, id, "test goal");
+
+    const row = getSession(db, id);
+    expect(row).not.toBeNull();
+    expect(row?.id).toBe(id);
+    expect(row?.goal).toBe("test goal");
+    expect(row?.createdBy).toBe("auto");
+    // NOT NULL cols must be populated
+    expect(row?.startedAt).toBeGreaterThan(0);
+    expect(row?.lastCheckpoint).toBeGreaterThan(0);
+    expect(row?.state).toEqual({});
+    expect(row?.agentHistory).toEqual([]);
+  });
+
+  test("is idempotent on existing row with different goal", () => {
+    const id = crypto.randomUUID();
+    ensureSession(db, id, "goal A");
+    ensureSession(db, id, "goal B");
+
+    const row = getSession(db, id);
+    expect(row).not.toBeNull();
+    // INSERT OR IGNORE — original goal preserved
+    expect(row?.goal).toBe("goal A");
+  });
+
+  test("respects custom createdBy", () => {
+    const id = crypto.randomUUID();
+    ensureSession(db, id, "test goal", "test-agent");
+
+    const row = getSession(db, id);
+    expect(row).not.toBeNull();
+    expect(row?.createdBy).toBe("test-agent");
+  });
+
+  test("defaults createdBy to 'auto' when not specified", () => {
+    const id = crypto.randomUUID();
+    ensureSession(db, id, "test goal");
+
+    const row = getSession(db, id);
+    expect(row).not.toBeNull();
+    expect(row?.createdBy).toBe("auto");
+  });
+
+  test("populates started_at and last_checkpoint with current timestamp", () => {
+    const before = Date.now();
+    const id = crypto.randomUUID();
+    ensureSession(db, id, "timestamp check");
+    const after = Date.now();
+
+    const row = getSession(db, id);
+    expect(row).not.toBeNull();
+    expect(row?.startedAt).toBeGreaterThanOrEqual(before);
+    expect(row?.startedAt).toBeLessThanOrEqual(after);
+    expect(row?.lastCheckpoint).toBeGreaterThanOrEqual(before);
+    expect(row?.lastCheckpoint).toBeLessThanOrEqual(after);
+  });
+});

package/src/db/sessions.ts

@@ -0,0 +1,135 @@
+/**
+ * ndomo DB — Session lifecycle management.
+ *
+ * Sessions track continuity across multiple agents working
+ * toward a shared goal. They record checkpoints, agent history,
+ * and key decisions.
+ */
+
+import type { Database } from "bun:sqlite";
+import type { Session, SessionMetadata } from "./types.ts";
+import { sessionFromRow } from "./types.ts";
+
+/**
+ * Idempotent upsert: ensure a session row exists for FK integrity.
+ *
+ * Used by plan_create and plan transition functions so that the harness
+ * session ID (ctx.sessionID) always has a matching row in `sessions`.
+ * INSERT OR IGNORE is safe — if the row already exists, this is a no-op.
+ * Does NOT call `startSession` (which requires full Session shape).
+ */
+export function ensureSession(
+  db: Database,
+  sessionId: string,
+  fallbackGoal: string,
+  createdBy = "auto",
+): void {
+  const now = Date.now();
+  db.query(
+    `INSERT OR IGNORE INTO sessions (id, started_at, last_checkpoint, goal, state, agent_history, created_by)
+     VALUES (?, ?, ?, ?, '{}', '[]', ?)`,
+  ).run(sessionId, now, now, fallbackGoal, createdBy);
+}
+
+export function startSession(
+  db: Database,
+  session: {
+    id: string;
+    goal: string;
+    planId?: string;
+    metadata?: SessionMetadata;
+    createdBy?: string;
+    sourceMessageId?: string;
+  },
+): Session {
+  const now = Date.now();
+  const meta = session.metadata ?? {};
+  db.query(
+    `INSERT INTO sessions (id, started_at, last_checkpoint, plan_id, goal, state, agent_history, key_decisions, metadata, created_by, source_message_id)
+     VALUES (?, ?, ?, ?, ?, '{}', '[]', NULL, ?, ?, ?)`,
+  ).run(
+    session.id,
+    now,
+    now,
+    session.planId ?? null,
+    session.goal,
+    JSON.stringify(meta),
+    session.createdBy ?? "unknown",
+    session.sourceMessageId ?? null,
+  );
+  const created = getSession(db, session.id);
+  if (!created) throw new Error("ndomo: failed to create session");
+  return created;
+}
+
+export function getSession(db: Database, id: string): Session | null {
+  const row = db.query("SELECT * FROM sessions WHERE id = ?").get(id);
+  return row ? sessionFromRow(row) : null;
+}
+
+export function listSessions(
+  db: Database,
+  opts: { planId?: string; limit?: number; includeArchived?: boolean } = {},
+): Session[] {
+  const limit = opts.limit ?? 20;
+  const conditions: string[] = [];
+  const params: (string | number)[] = [];
+
+  if (opts.planId) {
+    conditions.push("plan_id = ?");
+    params.push(opts.planId);
+  }
+  if (!opts.includeArchived) {
+    conditions.push("archived_at IS NULL");
+  }
+
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  params.push(limit);
+
+  const rows = db
+    .query(`SELECT * FROM sessions ${where} ORDER BY started_at DESC LIMIT ?`)
+    .all(...params);
+  return (rows as unknown[]).map((r) => sessionFromRow(r));
+}
+
+export function checkpointSession(
+  db: Database,
+  id: string,
+  state: Record<string, unknown>,
+  keyDecisions?: string,
+): Session | null {
+  const now = Date.now();
+  const result = db
+    .query(
+      "UPDATE sessions SET last_checkpoint = ?, state = ?, key_decisions = COALESCE(?, key_decisions) WHERE id = ?",
+    )
+    .run(now, JSON.stringify(state), keyDecisions ?? null, id);
+  if (result.changes === 0) return null;
+  return getSession(db, id);
+}
+
+export function appendAgentHistory(
+  db: Database,
+  id: string,
+  entry: {
+    agent: string;
+    taskId?: string;
+    startedAt?: number;
+    endedAt?: number | null;
+  },
+): Session | null {
+  const sess = getSession(db, id);
+  if (!sess) return null;
+  const history = [...sess.agentHistory, { ...entry, startedAt: entry.startedAt ?? Date.now() }];
+  db.query("UPDATE sessions SET agent_history = ? WHERE id = ?").run(JSON.stringify(history), id);
+  return getSession(db, id);
+}
+
+export function endSession(db: Database, id: string): Session | null {
+  const now = Date.now();
+  const result = db
+    .query("UPDATE sessions SET ended_at = ? WHERE id = ? AND ended_at IS NULL")
+    .run(now, id);
+  if (result.changes === 0) return null;
+  return getSession(db, id);
+}

package/src/db/shutdown.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Tests for shutdown.ts — plan fcb12dc5 (memory hygiene, finding #2).
+ *
+ * Validates that:
+ *  - Multiple openDb() calls each get SIGTERM/SIGINT/beforeExit cleanup
+ *    (regression: module-level `registered` boolean skipped all but the first).
+ *  - unregister(db) explicitly removes a db from cleanup tracking (needed
+ *    by tests, hot-reload, and explicit teardown paths).
+ *  - process.once is used for SIGTERM/SIGINT so listeners self-remove after
+ *    firing (regression: process.on would leak listeners across signals).
+ *  - SIGTERM cleanly closes all tracked dbs (verify by attempting use-after-close).
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { closeDb, openDb } from "./client.ts";
+import { getRegisteredDbCount, registerShutdownHandlers, unregister } from "./shutdown.ts";
+
+describe("shutdown — tracking", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "ndomo-shutdown-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("registerShutdownHandlers tracks each db in a Set", () => {
+    const baseline = getRegisteredDbCount();
+    const db1 = openDb(tmpDir);
+    const db2 = openDb(join(tmpDir, "sub"));
+
+    registerShutdownHandlers(db1);
+    expect(getRegisteredDbCount()).toBe(baseline + 1);
+
+    registerShutdownHandlers(db2);
+    expect(getRegisteredDbCount()).toBe(baseline + 2);
+
+    // Calling again with the same db should not double-count (Set semantics).
+    registerShutdownHandlers(db1);
+    expect(getRegisteredDbCount()).toBe(baseline + 2);
+
+    unregister(db1);
+    unregister(db2);
+    closeDb(db1);
+    closeDb(db2);
+  });
+
+  test("unregister(db) removes db from tracking", () => {
+    const db = openDb(tmpDir);
+    const baseline = getRegisteredDbCount();
+
+    registerShutdownHandlers(db);
+    expect(getRegisteredDbCount()).toBe(baseline + 1);
+
+    unregister(db);
+    expect(getRegisteredDbCount()).toBe(baseline);
+
+    closeDb(db);
+  });
+
+  test("unregister of an untracked db is a no-op (no throw)", () => {
+    const db = openDb(tmpDir);
+    expect(() => unregister(db)).not.toThrow();
+    closeDb(db);
+  });
+});
+
+describe("shutdown — SIGTERM behavior", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "ndomo-shutdown-sigterm-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("SIGTERM closes ALL registered dbs (regression: 2nd db used to leak)", () => {
+    const db1 = openDb(tmpDir);
+    const db2 = openDb(join(tmpDir, "sub"));
+    registerShutdownHandlers(db1);
+    registerShutdownHandlers(db2);
+
+    process.emit("SIGTERM" as NodeJS.Signals);
+
+    // Both dbs should now be closed — using them throws.
+    expect(() => db1.query("SELECT 1").get()).toThrow();
+    expect(() => db2.query("SELECT 1").get()).toThrow();
+  });
+
+  test("SIGINT closes ALL registered dbs", () => {
+    const db1 = openDb(tmpDir);
+    const db2 = openDb(join(tmpDir, "sub"));
+    registerShutdownHandlers(db1);
+    registerShutdownHandlers(db2);
+
+    process.emit("SIGINT" as NodeJS.Signals);
+
+    expect(() => db1.query("SELECT 1").get()).toThrow();
+    expect(() => db2.query("SELECT 1").get()).toThrow();
+  });
+
+  test("unregistered db is NOT closed on SIGTERM", () => {
+    const db1 = openDb(tmpDir);
+    const db2 = openDb(join(tmpDir, "sub"));
+    registerShutdownHandlers(db1);
+    registerShutdownHandlers(db2);
+    unregister(db2);
+
+    process.emit("SIGTERM" as NodeJS.Signals);
+
+    // db1 closed, db2 still usable
+    expect(() => db1.query("SELECT 1").get()).toThrow();
+    expect(db2.query("SELECT 1").get()).not.toBeNull();
+
+    // Cleanup
+    closeDb(db2);
+  });
+
+  test("process.once — SIGTERM listeners self-remove after firing (no leak)", () => {
+    const db1 = openDb(tmpDir);
+    const db2 = openDb(join(tmpDir, "sub"));
+
+    const beforeRegister = process.listenerCount("SIGTERM");
+    registerShutdownHandlers(db1);
+    registerShutdownHandlers(db2);
+    const afterRegister = process.listenerCount("SIGTERM");
+
+    // We added 2 SIGTERM listeners (one per db registration)
+    expect(afterRegister - beforeRegister).toBe(2);
+
+    // Emit SIGTERM — both listeners fire cleanup, then process.once removes them
+    process.emit("SIGTERM" as NodeJS.Signals);
+
+    const afterEmit = process.listenerCount("SIGTERM");
+
+    // process.once guarantees listeners deregister after firing — count must
+    // drop back to pre-registration baseline (no accumulation across signals).
+    expect(afterEmit).toBe(beforeRegister);
+  });
+});

package/src/db/shutdown.ts

@@ -0,0 +1,45 @@
+/**
+ * ndomo DB — Graceful shutdown handler.
+ *
+ * Tracks every Database returned by openDb() in a module-level Set so each
+ * connection gets SIGTERM/SIGINT/beforeExit cleanup. Replaces the previous
+ * module-level `registered` boolean which silently skipped every call after
+ * the first (resulting in leaked file handles on hot-reload, smoke tests,
+ * and CLI tools running alongside the plugin).
+ *
+ * Signal handlers use `process.once` so listeners self-remove after firing —
+ * prevents listener accumulation when multiple dbs register in sequence.
+ */
+
+import type { Database } from "bun:sqlite";
+import { closeDb } from "./client.ts";
+
+const registeredDbs = new Set<Database>();
+
+export function registerShutdownHandlers(db: Database): void {
+  if (registeredDbs.has(db)) return;
+  registeredDbs.add(db);
+
+  const cleanup = (): void => {
+    for (const tracked of registeredDbs) {
+      try {
+        closeDb(tracked);
+      } catch {
+        /* ignore — already closed or never opened */
+      }
+    }
+    registeredDbs.clear();
+  };
+
+  process.once("SIGTERM", cleanup);
+  process.once("SIGINT", cleanup);
+  process.once("beforeExit", cleanup);
+}
+
+export function unregister(db: Database): void {
+  registeredDbs.delete(db);
+}
+
+export function getRegisteredDbCount(): number {
+  return registeredDbs.size;
+}