engrm 0.1.0

package/src/lifecycle/purge.ts

@@ -0,0 +1,37 @@
+/**
+ * Purge job: permanently delete archived observations older than 12 months.
+ *
+ * Runs monthly (checked on MCP server startup via scheduler).
+ * Pinned observations and digests are never purged.
+ */
+
+import type { MemDatabase } from "../storage/sqlite.js";
+
+const PURGE_THRESHOLD_SECONDS = 365 * 86400; // 12 months
+
+export interface PurgeResult {
+  deleted: number;
+}
+
+/**
+ * Delete archived observations whose archived_at_epoch is older than 12 months.
+ * Only affects observations with lifecycle = 'archived' and a non-null archived_at_epoch.
+ */
+export function runPurgeJob(
+  db: MemDatabase,
+  nowEpoch?: number
+): PurgeResult {
+  const now = nowEpoch ?? Math.floor(Date.now() / 1000);
+  const cutoff = now - PURGE_THRESHOLD_SECONDS;
+
+  const result = db.db
+    .query(
+      `DELETE FROM observations
+       WHERE lifecycle = 'archived'
+       AND archived_at_epoch IS NOT NULL
+       AND archived_at_epoch < ?`
+    )
+    .run(cutoff);
+
+  return { deleted: result.changes };
+}

package/src/lifecycle/scheduler.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, test, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { MemDatabase } from "../storage/sqlite.js";
+import { runDueJobs } from "./scheduler.js";
+
+let db: MemDatabase;
+let tmpDir: string;
+let projectId: number;
+
+const DAY = 86400;
+const NOW = Math.floor(Date.now() / 1000);
+
+function insertObs(
+  overrides: Partial<{
+    lifecycle: string;
+    created_at_epoch: number;
+    title: string;
+  }> = {}
+) {
+  db.db
+    .query(
+      `INSERT INTO observations (project_id, type, title, quality, lifecycle, sensitivity, user_id, device_id, agent, created_at, created_at_epoch)
+       VALUES (?, 'discovery', ?, 0.5, ?, 'shared', 'user1', 'dev1', 'claude-code', datetime('now'), ?)`
+    )
+    .run(
+      projectId,
+      overrides.title ?? "Test observation",
+      overrides.lifecycle ?? "active",
+      overrides.created_at_epoch ?? NOW - 60 * DAY
+    );
+}
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "candengo-scheduler-test-"));
+  db = new MemDatabase(join(tmpDir, "test.db"));
+  const project = db.upsertProject({
+    canonical_id: "github.com/test/repo",
+    name: "repo",
+  });
+  projectId = project.id;
+});
+
+afterEach(() => {
+  db.close();
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("runDueJobs", () => {
+  test("runs aging when never run before", () => {
+    insertObs({ created_at_epoch: NOW - 31 * DAY });
+    const result = runDueJobs(db, NOW);
+    expect(result.agingRan).toBe(true);
+    expect(result.aging!.transitioned).toBe(1);
+  });
+
+  test("runs aging when last run > 24h ago", () => {
+    db.setSyncState("lifecycle_aging_last_run", String(NOW - 25 * 3600));
+    insertObs({ created_at_epoch: NOW - 31 * DAY });
+    const result = runDueJobs(db, NOW);
+    expect(result.agingRan).toBe(true);
+  });
+
+  test("skips aging when last run < 24h ago", () => {
+    db.setSyncState("lifecycle_aging_last_run", String(NOW - 23 * 3600));
+    const result = runDueJobs(db, NOW);
+    expect(result.agingRan).toBe(false);
+  });
+
+  test("runs compaction when never run before", () => {
+    const result = runDueJobs(db, NOW);
+    expect(result.compactionRan).toBe(true);
+  });
+
+  test("runs compaction when last run > 7 days ago", () => {
+    db.setSyncState(
+      "lifecycle_compaction_last_run",
+      String(NOW - 8 * DAY)
+    );
+    const result = runDueJobs(db, NOW);
+    expect(result.compactionRan).toBe(true);
+  });
+
+  test("skips compaction when last run < 7 days ago", () => {
+    db.setSyncState(
+      "lifecycle_compaction_last_run",
+      String(NOW - 6 * DAY)
+    );
+    const result = runDueJobs(db, NOW);
+    expect(result.compactionRan).toBe(false);
+  });
+
+  test("runs purge when last run > 30 days ago", () => {
+    db.setSyncState("lifecycle_purge_last_run", String(NOW - 31 * DAY));
+    const result = runDueJobs(db, NOW);
+    expect(result.purgeRan).toBe(true);
+  });
+
+  test("skips purge when last run < 30 days ago", () => {
+    db.setSyncState("lifecycle_purge_last_run", String(NOW - 29 * DAY));
+    const result = runDueJobs(db, NOW);
+    expect(result.purgeRan).toBe(false);
+  });
+
+  test("updates sync_state timestamps after each job", () => {
+    runDueJobs(db, NOW);
+    expect(db.getSyncState("lifecycle_aging_last_run")).toBe(String(NOW));
+    expect(db.getSyncState("lifecycle_compaction_last_run")).toBe(String(NOW));
+    expect(db.getSyncState("lifecycle_purge_last_run")).toBe(String(NOW));
+  });
+
+  test("all jobs run independently", () => {
+    // All should run on first invocation (never run before)
+    const result = runDueJobs(db, NOW);
+    expect(result.agingRan).toBe(true);
+    expect(result.compactionRan).toBe(true);
+    expect(result.purgeRan).toBe(true);
+  });
+});

package/src/lifecycle/scheduler.ts

@@ -0,0 +1,101 @@
+/**
+ * Lifecycle job scheduler.
+ *
+ * Checks on MCP server startup whether lifecycle jobs are due,
+ * and runs them if needed. Uses sync_state table for last-run tracking.
+ *
+ * Schedule:
+ *   - Aging: daily (24h)
+ *   - Compaction: weekly (7 days)
+ *   - Purge: monthly (30 days)
+ */
+
+import type { MemDatabase } from "../storage/sqlite.js";
+import { runAgingJob, type AgingResult } from "./aging.js";
+import { runCompactionJob, type CompactionResult } from "./compaction.js";
+import { runPurgeJob, type PurgeResult } from "./purge.js";
+
+const DAY = 86400;
+const AGING_INTERVAL = 1 * DAY;
+const COMPACTION_INTERVAL = 7 * DAY;
+const PURGE_INTERVAL = 30 * DAY;
+
+const KEY_AGING = "lifecycle_aging_last_run";
+const KEY_COMPACTION = "lifecycle_compaction_last_run";
+const KEY_PURGE = "lifecycle_purge_last_run";
+
+export interface SchedulerResult {
+  agingRan: boolean;
+  compactionRan: boolean;
+  purgeRan: boolean;
+  aging?: AgingResult;
+  compaction?: CompactionResult;
+  purge?: PurgeResult;
+}
+
+/**
+ * Run any lifecycle jobs that are due.
+ * Each job is independent — one failure does not block others.
+ */
+export function runDueJobs(
+  db: MemDatabase,
+  nowEpoch?: number
+): SchedulerResult {
+  const now = nowEpoch ?? Math.floor(Date.now() / 1000);
+  const result: SchedulerResult = {
+    agingRan: false,
+    compactionRan: false,
+    purgeRan: false,
+  };
+
+  // Aging: run if never run or > 24h since last run
+  try {
+    if (isDue(db, KEY_AGING, AGING_INTERVAL, now)) {
+      result.aging = runAgingJob(db, now);
+      result.agingRan = true;
+      db.setSyncState(KEY_AGING, String(now));
+    }
+  } catch {
+    // Aging job failed — continue with other jobs
+  }
+
+  // Compaction: run if never run or > 7 days since last run
+  try {
+    if (isDue(db, KEY_COMPACTION, COMPACTION_INTERVAL, now)) {
+      result.compaction = runCompactionJob(db, now);
+      result.compactionRan = true;
+      db.setSyncState(KEY_COMPACTION, String(now));
+    }
+  } catch {
+    // Compaction job failed — continue with other jobs
+  }
+
+  // Purge: run if never run or > 30 days since last run
+  try {
+    if (isDue(db, KEY_PURGE, PURGE_INTERVAL, now)) {
+      result.purge = runPurgeJob(db, now);
+      result.purgeRan = true;
+      db.setSyncState(KEY_PURGE, String(now));
+    }
+  } catch {
+    // Purge job failed — log would be nice but don't crash
+  }
+
+  return result;
+}
+
+/**
+ * Check if a job is due based on its last run timestamp.
+ */
+function isDue(
+  db: MemDatabase,
+  key: string,
+  interval: number,
+  now: number
+): boolean {
+  const lastRun = db.getSyncState(key);
+  if (!lastRun) return true; // Never run
+  const lastEpoch = parseInt(lastRun, 10);
+  if (isNaN(lastEpoch)) return true;
+  return now - lastEpoch >= interval;
+}

package/src/provisioning/browser-auth.ts

@@ -0,0 +1,172 @@
+/**
+ * Browser-based OAuth flow for `engrm init`.
+ *
+ * 1. Start a localhost HTTP server on a random port
+ * 2. Open browser to candengo.com/connect/mem?redirect_uri=...
+ * 3. Wait for callback with authorization code
+ * 4. Return the code for exchange via /v1/mem/provision
+ */
+
+import { randomBytes } from "node:crypto";
+
+const CALLBACK_TIMEOUT_MS = 120_000; // 2 minutes
+
+export interface AuthCallbackResult {
+  code: string;
+  state: string;
+}
+
+/**
+ * Run the browser OAuth flow.
+ * Returns the authorization code to exchange for credentials.
+ */
+export async function runBrowserAuth(
+  candengoUrl: string
+): Promise<AuthCallbackResult> {
+  const state = randomBytes(16).toString("hex");
+
+  // Start callback server
+  const { port, waitForCallback, stop } = await startCallbackServer(state);
+  const redirectUri = `http://localhost:${port}/callback`;
+
+  // Build authorization URL
+  const authUrl = new URL("/connect/mem", candengoUrl);
+  authUrl.searchParams.set("redirect_uri", redirectUri);
+  authUrl.searchParams.set("state", state);
+
+  // Open browser
+  console.log(`\nOpening browser to authorize Engrm...`);
+  console.log(`If the browser doesn't open, visit:\n  ${authUrl.toString()}\n`);
+
+  const opened = await openBrowser(authUrl.toString());
+  if (!opened) {
+    console.log(
+      "Could not open browser. Use --token or --no-browser instead."
+    );
+    stop();
+    throw new Error("Browser launch failed");
+  }
+
+  console.log("Waiting for authorization...");
+
+  try {
+    const result = await waitForCallback;
+    return result;
+  } finally {
+    stop();
+  }
+}
+
+/**
+ * Start a localhost HTTP server that waits for the OAuth callback.
+ */
+async function startCallbackServer(expectedState: string): Promise<{
+  port: number;
+  waitForCallback: Promise<AuthCallbackResult>;
+  stop: () => void;
+}> {
+  let resolveCallback: (result: AuthCallbackResult) => void;
+  let rejectCallback: (error: Error) => void;
+
+  const waitForCallback = new Promise<AuthCallbackResult>(
+    (resolve, reject) => {
+      resolveCallback = resolve;
+      rejectCallback = reject;
+    }
+  );
+
+  const server = Bun.serve({
+    port: 0, // random available port
+    fetch(req) {
+      const url = new URL(req.url);
+
+      if (url.pathname === "/callback") {
+        const code = url.searchParams.get("code");
+        const state = url.searchParams.get("state");
+        const error = url.searchParams.get("error");
+
+        if (error) {
+          const desc =
+            url.searchParams.get("error_description") ?? "Authorization denied";
+          rejectCallback!(new Error(desc));
+          return new Response(errorPage(desc), {
+            headers: { "Content-Type": "text/html" },
+          });
+        }
+
+        if (!code || !state) {
+          rejectCallback!(new Error("Missing code or state in callback"));
+          return new Response(errorPage("Missing authorization parameters"), {
+            headers: { "Content-Type": "text/html" },
+          });
+        }
+
+        if (state !== expectedState) {
+          rejectCallback!(new Error("State mismatch — possible CSRF"));
+          return new Response(errorPage("Security error: state mismatch"), {
+            headers: { "Content-Type": "text/html" },
+          });
+        }
+
+        resolveCallback!({ code, state });
+        return new Response(successPage(), {
+          headers: { "Content-Type": "text/html" },
+        });
+      }
+
+      return new Response("Not found", { status: 404 });
+    },
+  });
+
+  // Timeout
+  const timeout = setTimeout(() => {
+    rejectCallback!(
+      new Error("Authorization timed out. Please try again.")
+    );
+  }, CALLBACK_TIMEOUT_MS);
+
+  const stop = () => {
+    clearTimeout(timeout);
+    server.stop(true);
+  };
+
+  return { port: server.port!, waitForCallback, stop };
+}
+
+/**
+ * Open a URL in the default browser.
+ */
+async function openBrowser(url: string): Promise<boolean> {
+  try {
+    const cmd =
+      process.platform === "darwin"
+        ? ["open", url]
+        : process.platform === "win32"
+          ? ["cmd", "/c", "start", url]
+          : ["xdg-open", url];
+
+    const proc = Bun.spawn(cmd, { stdout: "ignore", stderr: "ignore" });
+    await proc.exited;
+    return proc.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+function successPage(): string {
+  return `<!DOCTYPE html>
+<html><head><title>Engrm</title>
+<style>body{font-family:system-ui;display:flex;justify-content:center;align-items:center;min-height:100vh;margin:0;background:#f8f9fa}
+.card{text-align:center;padding:3rem;border-radius:12px;background:white;box-shadow:0 2px 12px rgba(0,0,0,0.1)}
+h1{color:#10b981;margin-bottom:0.5rem}p{color:#6b7280}</style></head>
+<body><div class="card"><h1>Connected!</h1><p>You can close this tab and return to the terminal.</p></div></body></html>`;
+}
+
+function errorPage(message: string): string {
+  return `<!DOCTYPE html>
+<html><head><title>Engrm</title>
+<style>body{font-family:system-ui;display:flex;justify-content:center;align-items:center;min-height:100vh;margin:0;background:#f8f9fa}
+.card{text-align:center;padding:3rem;border-radius:12px;background:white;box-shadow:0 2px 12px rgba(0,0,0,0.1)}
+h1{color:#ef4444;margin-bottom:0.5rem}p{color:#6b7280}</style></head>
+<body><div class="card"><h1>Authorization Failed</h1><p>${message}</p></div></body></html>`;
+}

package/src/provisioning/provision.test.ts

@@ -0,0 +1,198 @@
+import { describe, expect, test, beforeEach, afterEach, mock } from "bun:test";
+import {
+  provision,
+  ProvisionError,
+  DEFAULT_CANDENGO_URL,
+  type ProvisionResponse,
+} from "./provision.js";
+
+// Mock server using Bun.serve
+let server: ReturnType<typeof Bun.serve>;
+let baseUrl: string;
+let nextResponse: {
+  status: number;
+  body: unknown;
+};
+
+beforeEach(() => {
+  nextResponse = {
+    status: 200,
+    body: {
+      api_key: "cvk_test123456",
+      site_id: "test-site",
+      namespace: "test-ns",
+      user_id: "david",
+      user_email: "david@example.com",
+      teams: [{ id: "team_1", name: "Unimpossible", namespace: "dev-memory" }],
+    } satisfies ProvisionResponse,
+  };
+
+  server = Bun.serve({
+    port: 0,
+    fetch(req) {
+      const url = new URL(req.url);
+      if (url.pathname === "/v1/mem/provision" && req.method === "POST") {
+        return new Response(JSON.stringify(nextResponse.body), {
+          status: nextResponse.status,
+          headers: { "Content-Type": "application/json" },
+        });
+      }
+      return new Response("Not found", { status: 404 });
+    },
+  });
+
+  baseUrl = `http://localhost:${server.port}`;
+});
+
+afterEach(() => {
+  server.stop(true);
+});
+
+describe("provision", () => {
+  test("exchanges token for credentials", async () => {
+    const result = await provision(baseUrl, { token: "cmt_abc123" });
+    expect(result.api_key).toBe("cvk_test123456");
+    expect(result.site_id).toBe("test-site");
+    expect(result.namespace).toBe("test-ns");
+    expect(result.user_id).toBe("david");
+    expect(result.user_email).toBe("david@example.com");
+    expect(result.teams).toHaveLength(1);
+    expect(result.teams[0]!.id).toBe("team_1");
+  });
+
+  test("exchanges OAuth code for credentials", async () => {
+    const result = await provision(baseUrl, { code: "auth_code_123" });
+    expect(result.api_key).toBe("cvk_test123456");
+  });
+
+  test("sends device_name in request", async () => {
+    let capturedBody: string | null = null;
+    server.stop(true);
+    server = Bun.serve({
+      port: 0,
+      async fetch(req) {
+        if (req.method === "POST") {
+          capturedBody = await req.text();
+          return new Response(JSON.stringify(nextResponse.body), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+          });
+        }
+        return new Response("Not found", { status: 404 });
+      },
+    });
+    baseUrl = `http://localhost:${server.port}`;
+
+    await provision(baseUrl, {
+      token: "cmt_test",
+      device_name: "MacBook Pro",
+    });
+    expect(capturedBody!).toContain("MacBook Pro");
+  });
+
+  test("throws ProvisionError on 401", async () => {
+    nextResponse = {
+      status: 401,
+      body: { detail: "Token expired" },
+    };
+
+    try {
+      await provision(baseUrl, { token: "cmt_expired" });
+      expect(true).toBe(false); // should not reach
+    } catch (error) {
+      expect(error).toBeInstanceOf(ProvisionError);
+      expect((error as ProvisionError).status).toBe(401);
+      expect((error as ProvisionError).detail).toBe(
+        "Invalid or expired provisioning token"
+      );
+    }
+  });
+
+  test("throws ProvisionError on 409 (already used)", async () => {
+    nextResponse = {
+      status: 409,
+      body: { detail: "Token already redeemed" },
+    };
+
+    try {
+      await provision(baseUrl, { token: "cmt_used" });
+      expect(true).toBe(false);
+    } catch (error) {
+      expect(error).toBeInstanceOf(ProvisionError);
+      expect((error as ProvisionError).status).toBe(409);
+      expect((error as ProvisionError).detail).toBe(
+        "Token has already been used"
+      );
+    }
+  });
+
+  test("throws ProvisionError on 500", async () => {
+    nextResponse = {
+      status: 500,
+      body: { detail: "Internal error" },
+    };
+
+    try {
+      await provision(baseUrl, { token: "cmt_test" });
+      expect(true).toBe(false);
+    } catch (error) {
+      expect(error).toBeInstanceOf(ProvisionError);
+      expect((error as ProvisionError).status).toBe(500);
+    }
+  });
+
+  test("validates api_key format in response", async () => {
+    nextResponse = {
+      status: 200,
+      body: {
+        api_key: "bad_key",
+        site_id: "s",
+        namespace: "n",
+        user_id: "u",
+        user_email: "e",
+        teams: [],
+      },
+    };
+
+    try {
+      await provision(baseUrl, { token: "cmt_test" });
+      expect(true).toBe(false);
+    } catch (error) {
+      expect(error).toBeInstanceOf(ProvisionError);
+      expect((error as ProvisionError).detail).toContain("invalid API key");
+    }
+  });
+
+  test("validates incomplete response", async () => {
+    nextResponse = {
+      status: 200,
+      body: {
+        api_key: "cvk_test123",
+        site_id: "",
+        namespace: "n",
+        user_id: "u",
+        user_email: "e",
+        teams: [],
+      },
+    };
+
+    try {
+      await provision(baseUrl, { token: "cmt_test" });
+      expect(true).toBe(false);
+    } catch (error) {
+      expect(error).toBeInstanceOf(ProvisionError);
+      expect((error as ProvisionError).detail).toContain("incomplete");
+    }
+  });
+
+  test("strips trailing slash from base URL", async () => {
+    const result = await provision(baseUrl + "/", { token: "cmt_test" });
+    expect(result.api_key).toBe("cvk_test123456");
+  });
+});
+
+describe("DEFAULT_CANDENGO_URL", () => {
+  test("points to production", () => {
+    expect(DEFAULT_CANDENGO_URL).toBe("https://www.candengo.com");
+  });
+});