@hellcoder/companion 0.96.0

package/server/linear-credential-migration.test.ts

@@ -0,0 +1,337 @@
+// Tests for the Linear OAuth credential migration module.
+// Verifies the one-time migration of global Linear OAuth credentials
+// from settings.json to the first eligible agent (has linear trigger
+// enabled but no per-agent oauthClientId yet).
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+import type { AgentConfig } from "./agent-types.js";
+
+// ─── Mocks ──────────────────────────────────────────────────────────────────
+
+// Mock the agent store: listAgents and updateAgent
+vi.mock("./agent-store.js", () => ({
+  listAgents: vi.fn(() => []),
+  updateAgent: vi.fn(() => null),
+}));
+
+// Mock the settings manager: getSettings and updateSettings
+vi.mock("./settings-manager.js", () => ({
+  getSettings: vi.fn(() => ({
+    linearOAuthClientId: "",
+    linearOAuthClientSecret: "",
+    linearOAuthWebhookSecret: "",
+    linearOAuthAccessToken: "",
+    linearOAuthRefreshToken: "",
+  })),
+  updateSettings: vi.fn(),
+}));
+
+import { migrateLinearCredentialsToAgents } from "./linear-credential-migration.js";
+import * as agentStore from "./agent-store.js";
+import { getSettings, updateSettings } from "./settings-manager.js";
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/** Build a minimal AgentConfig for testing with optional overrides. */
+function makeAgent(overrides: Partial<AgentConfig> = {}): AgentConfig {
+  return {
+    id: "test-agent",
+    version: 1,
+    name: "Test Agent",
+    description: "",
+    backendType: "claude",
+    model: "claude-sonnet-4-6",
+    permissionMode: "default",
+    cwd: "/tmp",
+    prompt: "do stuff",
+    enabled: true,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+    totalRuns: 0,
+    consecutiveFailures: 0,
+    ...overrides,
+  };
+}
+
+// ─── Tests ──────────────────────────────────────────────────────────────────
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("migrateLinearCredentialsToAgents", () => {
+  // When no global OAuth client ID exists in settings, the function should
+  // return early without even querying for agents.
+  it("does nothing when no global OAuth credentials exist", () => {
+    vi.mocked(getSettings).mockReturnValue({
+      linearOAuthClientId: "",
+      linearOAuthClientSecret: "",
+      linearOAuthWebhookSecret: "",
+      linearOAuthAccessToken: "",
+      linearOAuthRefreshToken: "",
+    } as ReturnType<typeof getSettings>);
+
+    migrateLinearCredentialsToAgents();
+
+    // Should not attempt to list agents when there are no credentials to migrate
+    expect(agentStore.listAgents).not.toHaveBeenCalled();
+    expect(agentStore.updateAgent).not.toHaveBeenCalled();
+    expect(updateSettings).not.toHaveBeenCalled();
+  });
+
+  // When global credentials exist but no agent has linear enabled without
+  // existing oauthClientId, the function should log a message and return
+  // without modifying anything.
+  it("does nothing when no eligible agent is found", () => {
+    vi.mocked(getSettings).mockReturnValue({
+      linearOAuthClientId: "client-id-123",
+      linearOAuthClientSecret: "secret-456",
+      linearOAuthWebhookSecret: "webhook-789",
+      linearOAuthAccessToken: "access-token",
+      linearOAuthRefreshToken: "refresh-token",
+    } as ReturnType<typeof getSettings>);
+
+    // Agent has linear enabled but already has its own oauthClientId
+    const agentWithCreds = makeAgent({
+      id: "already-configured",
+      name: "Already Configured",
+      triggers: {
+        linear: {
+          enabled: true,
+          oauthClientId: "existing-client-id",
+        },
+      },
+    });
+
+    vi.mocked(agentStore.listAgents).mockReturnValue([agentWithCreds]);
+
+    const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    migrateLinearCredentialsToAgents();
+
+    // Should have listed agents to search for eligible ones
+    expect(agentStore.listAgents).toHaveBeenCalled();
+    // But should not have updated any agent or cleared settings
+    expect(agentStore.updateAgent).not.toHaveBeenCalled();
+    expect(updateSettings).not.toHaveBeenCalled();
+    // Should log a staging message
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining("no Linear agent found to migrate to"),
+    );
+
+    consoleSpy.mockRestore();
+  });
+
+  // Happy path: global credentials exist and there is exactly one eligible
+  // agent (linear enabled, no oauthClientId). The function should copy all
+  // credentials to the agent and then clear the global settings.
+  it("migrates credentials to the first eligible agent", () => {
+    const globalCreds = {
+      linearOAuthClientId: "client-id-123",
+      linearOAuthClientSecret: "secret-456",
+      linearOAuthWebhookSecret: "webhook-789",
+      linearOAuthAccessToken: "access-token",
+      linearOAuthRefreshToken: "refresh-token",
+    };
+
+    vi.mocked(getSettings).mockReturnValue(
+      globalCreds as ReturnType<typeof getSettings>,
+    );
+
+    const eligibleAgent = makeAgent({
+      id: "linear-agent",
+      name: "My Linear Agent",
+      triggers: {
+        linear: {
+          enabled: true,
+          // No oauthClientId — eligible for migration
+        },
+      },
+    });
+
+    vi.mocked(agentStore.listAgents).mockReturnValue([eligibleAgent]);
+    vi.mocked(agentStore.updateAgent).mockReturnValue(eligibleAgent);
+
+    const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    migrateLinearCredentialsToAgents();
+
+    // Should copy all global credentials to the agent's linear trigger config
+    expect(agentStore.updateAgent).toHaveBeenCalledWith("linear-agent", {
+      triggers: {
+        linear: {
+          enabled: true,
+          oauthClientId: "client-id-123",
+          oauthClientSecret: "secret-456",
+          webhookSecret: "webhook-789",
+          accessToken: "access-token",
+          refreshToken: "refresh-token",
+        },
+      },
+    });
+
+    // Should clear global credentials after successful migration
+    expect(updateSettings).toHaveBeenCalledWith({
+      linearOAuthClientId: "",
+      linearOAuthClientSecret: "",
+      linearOAuthWebhookSecret: "",
+      linearOAuthAccessToken: "",
+      linearOAuthRefreshToken: "",
+    });
+
+    // Should log success with agent name and ID
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Migrated global OAuth credentials to agent "My Linear Agent"'),
+    );
+
+    consoleSpy.mockRestore();
+  });
+
+  // When multiple agents have linear enabled, but the first one already has
+  // its own oauthClientId, the migration should skip it and migrate to the
+  // second agent that lacks credentials.
+  it("skips agents that already have oauthClientId and migrates to the next eligible one", () => {
+    vi.mocked(getSettings).mockReturnValue({
+      linearOAuthClientId: "global-client",
+      linearOAuthClientSecret: "global-secret",
+      linearOAuthWebhookSecret: "global-webhook",
+      linearOAuthAccessToken: "global-access",
+      linearOAuthRefreshToken: "global-refresh",
+    } as ReturnType<typeof getSettings>);
+
+    const agentWithCreds = makeAgent({
+      id: "agent-with-creds",
+      name: "Agent With Creds",
+      triggers: {
+        linear: {
+          enabled: true,
+          oauthClientId: "already-has-one",
+        },
+      },
+    });
+
+    const agentWithoutCreds = makeAgent({
+      id: "agent-without-creds",
+      name: "Agent Without Creds",
+      triggers: {
+        linear: {
+          enabled: true,
+          // No oauthClientId — this one should receive the migration
+        },
+      },
+    });
+
+    vi.mocked(agentStore.listAgents).mockReturnValue([
+      agentWithCreds,
+      agentWithoutCreds,
+    ]);
+    vi.mocked(agentStore.updateAgent).mockReturnValue(agentWithoutCreds);
+
+    const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    migrateLinearCredentialsToAgents();
+
+    // Should migrate to the second agent (the one without existing credentials)
+    expect(agentStore.updateAgent).toHaveBeenCalledWith(
+      "agent-without-creds",
+      expect.objectContaining({
+        triggers: expect.objectContaining({
+          linear: expect.objectContaining({
+            oauthClientId: "global-client",
+          }),
+        }),
+      }),
+    );
+
+    // Should clear global settings after migration
+    expect(updateSettings).toHaveBeenCalled();
+
+    consoleSpy.mockRestore();
+  });
+
+  // An agent exists but its linear trigger is not enabled (enabled: false).
+  // It should not be considered eligible for migration.
+  it("skips agents without linear trigger enabled", () => {
+    vi.mocked(getSettings).mockReturnValue({
+      linearOAuthClientId: "client-id",
+      linearOAuthClientSecret: "secret",
+      linearOAuthWebhookSecret: "webhook",
+      linearOAuthAccessToken: "access",
+      linearOAuthRefreshToken: "refresh",
+    } as ReturnType<typeof getSettings>);
+
+    const disabledLinearAgent = makeAgent({
+      id: "disabled-linear",
+      name: "Disabled Linear Agent",
+      triggers: {
+        linear: {
+          enabled: false,
+          // No oauthClientId, but linear is disabled so it shouldn't qualify
+        },
+      },
+    });
+
+    // Also test an agent with no triggers at all
+    const noTriggersAgent = makeAgent({
+      id: "no-triggers",
+      name: "No Triggers Agent",
+      // No triggers property
+    });
+
+    vi.mocked(agentStore.listAgents).mockReturnValue([
+      disabledLinearAgent,
+      noTriggersAgent,
+    ]);
+
+    const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    migrateLinearCredentialsToAgents();
+
+    // Neither agent should receive credentials
+    expect(agentStore.updateAgent).not.toHaveBeenCalled();
+    expect(updateSettings).not.toHaveBeenCalled();
+
+    // Should log the "no agent found" message
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining("no Linear agent found to migrate to"),
+    );
+
+    consoleSpy.mockRestore();
+  });
+
+  // If updateAgent returns null (store failure), the global credentials
+  // must NOT be cleared — otherwise the user's credentials are silently lost.
+  it("does NOT clear global credentials when updateAgent fails during migration", () => {
+    vi.mocked(getSettings).mockReturnValue({
+      linearOAuthClientId: "client-id",
+      linearOAuthClientSecret: "secret",
+      linearOAuthWebhookSecret: "webhook",
+      linearOAuthAccessToken: "access",
+      linearOAuthRefreshToken: "refresh",
+    } as ReturnType<typeof getSettings>);
+
+    const eligible = makeAgent({
+      id: "linear-agent",
+      name: "Linear Agent",
+      triggers: { linear: { enabled: true } },
+    });
+    vi.mocked(agentStore.listAgents).mockReturnValue([eligible]);
+    // Simulate a store failure
+    vi.mocked(agentStore.updateAgent).mockReturnValue(null);
+
+    const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    migrateLinearCredentialsToAgents();
+
+    expect(agentStore.updateAgent).toHaveBeenCalled();
+    // Credentials must NOT be cleared if the agent write failed
+    expect(updateSettings).not.toHaveBeenCalled();
+    // Should log an error about the failure
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Failed to write credentials to agent"),
+    );
+
+    consoleErrorSpy.mockRestore();
+  });
+});

package/server/linear-credential-migration.ts

@@ -0,0 +1,63 @@
+// Linear OAuth Credential Migration
+// One-time migration: copies global Linear OAuth credentials from settings.json
+// to the first Linear agent that doesn't have per-agent credentials.
+// This runs on server startup to handle the transition from global to per-agent storage.
+
+import * as agentStore from "./agent-store.js";
+import { getSettings, updateSettings } from "./settings-manager.js";
+
+/** Migrate global Linear OAuth credentials to the first eligible agent.
+ *  This is a one-time operation: once credentials are moved, global fields are cleared. */
+export function migrateLinearCredentialsToAgents(): void {
+  const settings = getSettings();
+
+  // Nothing to migrate if no global OAuth client ID
+  if (!settings.linearOAuthClientId.trim()) return;
+
+  const agents = agentStore.listAgents();
+  const linearAgent = agents.find(
+    (a) => a.triggers?.linear?.enabled && !a.triggers.linear.oauthClientId
+  );
+
+  if (!linearAgent) {
+    console.log(
+      "[linear-migration] Global OAuth credentials exist but no Linear agent found to migrate to. Credentials will remain in global settings as staging."
+    );
+    return;
+  }
+
+  // Copy credentials to the agent
+  const triggers = linearAgent.triggers!;
+  const updated = agentStore.updateAgent(linearAgent.id, {
+    triggers: {
+      ...triggers,
+      linear: {
+        enabled: true,
+        ...triggers.linear,
+        oauthClientId: settings.linearOAuthClientId,
+        oauthClientSecret: settings.linearOAuthClientSecret,
+        webhookSecret: settings.linearOAuthWebhookSecret,
+        accessToken: settings.linearOAuthAccessToken,
+        refreshToken: settings.linearOAuthRefreshToken,
+      },
+    },
+  });
+
+  // Only clear global credentials after a confirmed successful write
+  if (!updated) {
+    console.error("[linear-migration] Failed to write credentials to agent — global credentials preserved");
+    return;
+  }
+
+  updateSettings({
+    linearOAuthClientId: "",
+    linearOAuthClientSecret: "",
+    linearOAuthWebhookSecret: "",
+    linearOAuthAccessToken: "",
+    linearOAuthRefreshToken: "",
+  });
+
+  console.log(
+    `[linear-migration] Migrated global OAuth credentials to agent "${linearAgent.name}" (${linearAgent.id})`
+  );
+}

package/server/linear-oauth-connections-migration.test.ts

@@ -0,0 +1,268 @@
+/**
+ * Tests for the migrateFromAgents() auto-migration in linear-oauth-connections.ts.
+ *
+ * Validates:
+ * - Agents with inline OAuth credentials get migrated to standalone connections
+ * - Global settings with OAuth credentials get migrated
+ * - Deduplication by oauthClientId (multiple agents sharing the same app)
+ * - Agents get updated with oauthConnectionId after migration
+ * - No migration when connections already exist
+ * - Agents without oauthClientId are skipped
+ * - Status correctly derived from accessToken presence
+ * - Migrated connections persist to disk
+ *
+ * Uses the exported `migrateFromAgents(deps)` with injected dependencies
+ * instead of relying on `require()` interception.
+ */
+import { vi, describe, it, expect, beforeEach, afterAll } from "vitest";
+import { mkdirSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  listOAuthConnections,
+  createOAuthConnection,
+  migrateFromAgents,
+  _resetForTest,
+} from "./linear-oauth-connections.js";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+const TEST_DIR = join(tmpdir(), `companion-oauth-migration-test-${Date.now()}`);
+const TEST_FILE = join(TEST_DIR, "linear-oauth-connections.json");
+
+const mockUpdateAgent = vi.fn();
+
+function makeDeps(
+  agents: Array<Record<string, unknown>> = [],
+  settings: Record<string, string> = {},
+) {
+  return {
+    listAgents: () => agents as Array<{ id: string; name: string; triggers?: { linear?: Record<string, unknown> } }>,
+    updateAgent: mockUpdateAgent as (id: string, patch: Record<string, unknown>) => void,
+    getSettings: () => ({
+      linearOAuthClientId: "",
+      linearOAuthClientSecret: "",
+      linearOAuthWebhookSecret: "",
+      linearOAuthAccessToken: "",
+      linearOAuthRefreshToken: "",
+      ...settings,
+    }),
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  _resetForTest(TEST_FILE);
+  if (existsSync(TEST_DIR)) {
+    rmSync(TEST_DIR, { recursive: true });
+  }
+  mkdirSync(TEST_DIR, { recursive: true });
+});
+
+afterAll(() => {
+  if (existsSync(TEST_DIR)) {
+    rmSync(TEST_DIR, { recursive: true });
+  }
+});
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe("migrateFromAgents", () => {
+  it("migrates agents with inline OAuth credentials to standalone connections", () => {
+    const deps = makeDeps([
+      {
+        id: "agent-1",
+        name: "Linear Bot",
+        triggers: {
+          linear: {
+            enabled: true,
+            oauthClientId: "inline-cid",
+            oauthClientSecret: "inline-csec",
+            webhookSecret: "inline-wsec",
+            accessToken: "inline-tok",
+            refreshToken: "inline-ref",
+          },
+        },
+      },
+    ]);
+
+    migrateFromAgents(deps);
+    const conns = listOAuthConnections();
+
+    expect(conns).toHaveLength(1);
+    expect(conns[0].oauthClientId).toBe("inline-cid");
+    expect(conns[0].oauthClientSecret).toBe("inline-csec");
+    expect(conns[0].webhookSecret).toBe("inline-wsec");
+    expect(conns[0].accessToken).toBe("inline-tok");
+    expect(conns[0].status).toBe("connected");
+    expect(conns[0].name).toBe("Linear Bot OAuth App");
+
+    // Agent should be updated with oauthConnectionId
+    expect(mockUpdateAgent).toHaveBeenCalledWith(
+      "agent-1",
+      expect.objectContaining({
+        triggers: expect.objectContaining({
+          linear: expect.objectContaining({
+            oauthConnectionId: conns[0].id,
+          }),
+        }),
+      }),
+    );
+  });
+
+  it("deduplicates by oauthClientId when multiple agents share the same app", () => {
+    const deps = makeDeps([
+      {
+        id: "agent-1",
+        name: "Bot A",
+        triggers: {
+          linear: {
+            enabled: true,
+            oauthClientId: "shared-cid",
+            oauthClientSecret: "csec",
+            webhookSecret: "wsec",
+            accessToken: "tok",
+          },
+        },
+      },
+      {
+        id: "agent-2",
+        name: "Bot B",
+        triggers: {
+          linear: {
+            enabled: true,
+            oauthClientId: "shared-cid", // same clientId
+            oauthClientSecret: "csec",
+            webhookSecret: "wsec",
+            accessToken: "tok",
+          },
+        },
+      },
+    ]);
+
+    migrateFromAgents(deps);
+    const conns = listOAuthConnections();
+
+    // Should create only one connection (deduplication)
+    expect(conns).toHaveLength(1);
+
+    // Both agents should be updated with the same connection ID
+    expect(mockUpdateAgent).toHaveBeenCalledTimes(2);
+    expect(mockUpdateAgent).toHaveBeenCalledWith("agent-1", expect.anything());
+    expect(mockUpdateAgent).toHaveBeenCalledWith("agent-2", expect.anything());
+  });
+
+  it("migrates from global settings when no agent credentials exist", () => {
+    const deps = makeDeps([], {
+      linearOAuthClientId: "settings-cid",
+      linearOAuthClientSecret: "settings-csec",
+      linearOAuthWebhookSecret: "settings-wsec",
+      linearOAuthAccessToken: "settings-tok",
+      linearOAuthRefreshToken: "settings-ref",
+    });
+
+    migrateFromAgents(deps);
+    const conns = listOAuthConnections();
+
+    expect(conns).toHaveLength(1);
+    expect(conns[0].name).toBe("Default OAuth App");
+    expect(conns[0].oauthClientId).toBe("settings-cid");
+    expect(conns[0].status).toBe("connected");
+  });
+
+  it("skips migration when connections already exist", () => {
+    // Pre-create a connection
+    createOAuthConnection({
+      name: "Existing",
+      oauthClientId: "existing-cid",
+      oauthClientSecret: "csec",
+      webhookSecret: "wsec",
+    });
+
+    const deps = makeDeps([
+      {
+        id: "agent-1",
+        name: "Bot",
+        triggers: {
+          linear: {
+            enabled: true,
+            oauthClientId: "new-cid",
+            oauthClientSecret: "csec",
+          },
+        },
+      },
+    ]);
+
+    migrateFromAgents(deps);
+    const conns = listOAuthConnections();
+
+    // Should NOT create additional connections
+    expect(conns).toHaveLength(1);
+    expect(conns[0].oauthClientId).toBe("existing-cid");
+    expect(mockUpdateAgent).not.toHaveBeenCalled();
+  });
+
+  it("skips agents without oauthClientId", () => {
+    const deps = makeDeps([
+      {
+        id: "agent-1",
+        name: "No OAuth",
+        triggers: { linear: { enabled: true } },
+      },
+    ]);
+
+    migrateFromAgents(deps);
+    expect(listOAuthConnections()).toHaveLength(0);
+  });
+
+  it("sets status to disconnected when agent has no accessToken", () => {
+    const deps = makeDeps([
+      {
+        id: "agent-1",
+        name: "Unconnected Bot",
+        triggers: {
+          linear: {
+            enabled: true,
+            oauthClientId: "cid",
+            oauthClientSecret: "csec",
+          },
+        },
+      },
+    ]);
+
+    migrateFromAgents(deps);
+    const conns = listOAuthConnections();
+
+    expect(conns).toHaveLength(1);
+    expect(conns[0].status).toBe("disconnected");
+  });
+
+  it("persists migrated connections to disk", () => {
+    const deps = makeDeps([
+      {
+        id: "agent-1",
+        name: "Persist Test",
+        triggers: {
+          linear: {
+            enabled: true,
+            oauthClientId: "persist-cid",
+            oauthClientSecret: "csec",
+            webhookSecret: "wsec",
+          },
+        },
+      },
+    ]);
+
+    migrateFromAgents(deps);
+    expect(existsSync(TEST_FILE)).toBe(true);
+
+    // Reload from disk and verify
+    _resetForTest(TEST_FILE);
+    const conns = listOAuthConnections();
+    expect(conns).toHaveLength(1);
+    expect(conns[0].oauthClientId).toBe("persist-cid");
+  });
+});