@hellcoder/companion 0.96.0

package/server/linear-cache.ts

@@ -0,0 +1,113 @@
+/**
+ * Server-side TTL cache for Linear API responses.
+ *
+ * Prevents hitting Linear's 5000 requests/hour rate limit by caching
+ * read-only GraphQL responses with configurable TTLs. Concurrent identical
+ * requests are deduplicated — only one fetch is made and all callers share
+ * the same promise.
+ */
+
+interface CacheEntry<T = unknown> {
+  data: T;
+  timestamp: number;
+  pending?: Promise<T>;
+}
+
+const MAX_ENTRIES = 500;
+const EVICT_AGE_MS = 5 * 60 * 1000; // 5 minutes — sweep threshold
+
+export class LinearCache {
+  private store = new Map<string, CacheEntry>();
+
+  /**
+   * Return cached data if fresh, otherwise execute `fetcher` and cache the result.
+   * Concurrent calls with the same key share a single in-flight request.
+   */
+  async getOrFetch<T>(key: string, ttlMs: number, fetcher: () => Promise<T>): Promise<T> {
+    const existing = this.store.get(key) as CacheEntry<T> | undefined;
+
+    // Serve from cache if still fresh
+    if (existing && !existing.pending && Date.now() - existing.timestamp < ttlMs) {
+      return existing.data;
+    }
+
+    // Deduplicate: if a fetch is already in flight for this key, piggyback on it
+    if (existing?.pending) {
+      return existing.pending;
+    }
+
+    const pending = fetcher()
+      .then((data) => {
+        this.store.set(key, { data, timestamp: Date.now() });
+        this.maybeEvict();
+        return data;
+      })
+      .catch((err) => {
+        // On failure, remove the pending promise so the next call can retry.
+        // If we have stale data, keep it around (callers won't use it because
+        // timestamp is old, but a future getOrFetch will retry the fetch).
+        const entry = this.store.get(key);
+        if (entry?.pending === pending) {
+          delete entry.pending;
+          // If there was never any cached data, remove the entry entirely
+          if (entry.timestamp === 0) {
+            this.store.delete(key);
+          }
+        }
+        throw err;
+      });
+
+    // Store the in-flight promise
+    if (existing) {
+      existing.pending = pending;
+    } else {
+      this.store.set(key, { data: undefined as T, timestamp: 0, pending });
+    }
+
+    return pending;
+  }
+
+  /** Invalidate a specific key, or all keys that start with `keyOrPrefix`. */
+  invalidate(keyOrPrefix: string): void {
+    // Exact match first
+    if (this.store.has(keyOrPrefix)) {
+      this.store.delete(keyOrPrefix);
+      return;
+    }
+    // Prefix match
+    for (const k of this.store.keys()) {
+      if (k.startsWith(keyOrPrefix)) {
+        this.store.delete(k);
+      }
+    }
+  }
+
+  /** Clear the entire cache (e.g. when the Linear API key changes). */
+  clear(): void {
+    this.store.clear();
+  }
+
+  /** Current number of cached entries. */
+  get size(): number {
+    return this.store.size;
+  }
+
+  /** Sweep stale entries when the store grows too large. */
+  private maybeEvict(): void {
+    if (this.store.size <= MAX_ENTRIES) return;
+    const now = Date.now();
+    for (const [k, entry] of this.store) {
+      if (now - entry.timestamp > EVICT_AGE_MS && !entry.pending) {
+        this.store.delete(k);
+      }
+    }
+  }
+}
+
+/** Singleton cache instance used across all Linear route handlers. */
+export const linearCache = new LinearCache();
+
+/** Reset for test isolation — clears all cached data. */
+export function _resetForTest(): void {
+  linearCache.clear();
+}

package/server/linear-connections.test.ts

@@ -0,0 +1,350 @@
+import {
+  mkdtempSync,
+  rmSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+  listConnections,
+  getConnection,
+  getDefaultConnection,
+  createConnection,
+  updateConnection,
+  deleteConnection,
+  resolveApiKey,
+  _resetForTest,
+  type LinearConnection,
+} from "./linear-connections.js";
+
+// Mock settings-manager to control legacy linearApiKey fallback
+vi.mock("./settings-manager.js", () => ({
+  getSettings: vi.fn(() => ({
+    linearApiKey: "",
+    linearAutoTransition: false,
+    linearAutoTransitionStateId: "",
+    linearAutoTransitionStateName: "",
+    linearArchiveTransition: false,
+    linearArchiveTransitionStateId: "",
+    linearArchiveTransitionStateName: "",
+  })),
+}));
+
+import { getSettings } from "./settings-manager.js";
+
+let tempDir: string;
+
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), "linear-connections-test-"));
+  _resetForTest(join(tempDir, "linear-connections.json"));
+  vi.mocked(getSettings).mockReturnValue({
+    linearApiKey: "",
+    linearAutoTransition: false,
+    linearAutoTransitionStateId: "",
+    linearAutoTransitionStateName: "",
+    linearArchiveTransition: false,
+    linearArchiveTransitionStateId: "",
+    linearArchiveTransitionStateName: "",
+    anthropicApiKey: "",
+    anthropicModel: "",
+    linearOAuthClientId: "",
+    linearOAuthClientSecret: "",
+    linearOAuthWebhookSecret: "",
+    linearOAuthAccessToken: "",
+    linearOAuthRefreshToken: "",
+    claudeCodeOAuthToken: "",
+    openaiApiKey: "",
+    onboardingCompleted: false,
+    aiValidationEnabled: false,
+    aiValidationAutoApprove: true,
+    aiValidationAutoDeny: false,
+    publicUrl: "",
+    updateChannel: "stable",
+    dockerAutoUpdate: false,
+    updatedAt: 0,
+  });
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe("linear-connections", () => {
+  // ─── CRUD ────────────────────────────────────────────────────────────
+
+  it("listConnections returns empty array when no connections exist", () => {
+    expect(listConnections()).toEqual([]);
+  });
+
+  it("createConnection creates a connection and persists", () => {
+    const conn = createConnection({ name: "Work", apiKey: "lin_api_work123" });
+    expect(conn.name).toBe("Work");
+    expect(conn.apiKey).toBe("lin_api_work123");
+    expect(conn.id).toBeTruthy();
+    expect(conn.connected).toBe(false);
+    expect(conn.autoTransition).toBe(false);
+
+    // Verify persisted to disk
+    const raw = JSON.parse(readFileSync(join(tempDir, "linear-connections.json"), "utf-8"));
+    expect(raw).toHaveLength(1);
+    expect(raw[0].name).toBe("Work");
+  });
+
+  it("getConnection retrieves by id", () => {
+    const conn = createConnection({ name: "Test", apiKey: "lin_api_test" });
+    expect(getConnection(conn.id)).toEqual(conn);
+    expect(getConnection("nonexistent")).toBeNull();
+  });
+
+  it("getDefaultConnection returns the first connection", () => {
+    expect(getDefaultConnection()).toBeNull();
+    createConnection({ name: "First", apiKey: "lin_api_first" });
+    createConnection({ name: "Second", apiKey: "lin_api_second" });
+    expect(getDefaultConnection()?.name).toBe("First");
+  });
+
+  it("updateConnection updates fields and preserves others", () => {
+    const conn = createConnection({ name: "Original", apiKey: "lin_api_orig" });
+    const updated = updateConnection(conn.id, {
+      name: "Updated",
+      connected: true,
+      workspaceName: "My Workspace",
+    });
+    expect(updated).not.toBeNull();
+    expect(updated!.name).toBe("Updated");
+    expect(updated!.apiKey).toBe("lin_api_orig"); // unchanged
+    expect(updated!.connected).toBe(true);
+    expect(updated!.workspaceName).toBe("My Workspace");
+  });
+
+  it("updateConnection returns null for nonexistent id", () => {
+    expect(updateConnection("nope", { name: "x" })).toBeNull();
+  });
+
+  it("deleteConnection removes a connection and persists", () => {
+    const conn = createConnection({ name: "ToDelete", apiKey: "lin_api_del" });
+    expect(deleteConnection(conn.id)).toBe(true);
+    expect(getConnection(conn.id)).toBeNull();
+    expect(listConnections()).toEqual([]);
+  });
+
+  it("deleteConnection returns false for nonexistent id", () => {
+    expect(deleteConnection("nope")).toBe(false);
+  });
+
+  it("supports multiple connections", () => {
+    createConnection({ name: "A", apiKey: "lin_api_a" });
+    createConnection({ name: "B", apiKey: "lin_api_b" });
+    createConnection({ name: "C", apiKey: "lin_api_c" });
+    expect(listConnections()).toHaveLength(3);
+  });
+
+  it("trims name and apiKey on create and update", () => {
+    const conn = createConnection({ name: "  Spaced  ", apiKey: "  lin_api_key  " });
+    expect(conn.name).toBe("Spaced");
+    expect(conn.apiKey).toBe("lin_api_key");
+
+    const updated = updateConnection(conn.id, { name: "  Updated  " });
+    expect(updated!.name).toBe("Updated");
+  });
+
+  // ─── resolveApiKey ─────────────────────────────────────────────────
+
+  it("resolveApiKey returns specific connection when connectionId is provided", () => {
+    const conn = createConnection({ name: "Target", apiKey: "lin_api_target" });
+    const result = resolveApiKey(conn.id);
+    expect(result).toEqual({ apiKey: "lin_api_target", connectionId: conn.id });
+  });
+
+  it("resolveApiKey returns null for invalid connectionId", () => {
+    expect(resolveApiKey("nonexistent")).toBeNull();
+  });
+
+  it("resolveApiKey falls back to default connection when no connectionId", () => {
+    const conn = createConnection({ name: "Default", apiKey: "lin_api_default" });
+    const result = resolveApiKey();
+    expect(result).toEqual({ apiKey: "lin_api_default", connectionId: conn.id });
+  });
+
+  it("resolveApiKey falls back to legacy settings.linearApiKey", () => {
+    // No connections exist, but settings has a key
+    vi.mocked(getSettings).mockReturnValue({
+      linearApiKey: "lin_api_legacy",
+      linearAutoTransition: false,
+      linearAutoTransitionStateId: "",
+      linearAutoTransitionStateName: "",
+      linearArchiveTransition: false,
+      linearArchiveTransitionStateId: "",
+      linearArchiveTransitionStateName: "",
+      anthropicApiKey: "",
+      anthropicModel: "",
+      linearOAuthClientId: "",
+      linearOAuthClientSecret: "",
+      linearOAuthWebhookSecret: "",
+      linearOAuthAccessToken: "",
+      linearOAuthRefreshToken: "",
+      claudeCodeOAuthToken: "",
+      openaiApiKey: "",
+      onboardingCompleted: false,
+      aiValidationEnabled: false,
+      aiValidationAutoApprove: true,
+      aiValidationAutoDeny: false,
+      publicUrl: "",
+      updateChannel: "stable",
+      dockerAutoUpdate: false,
+      updatedAt: 0,
+    });
+    // Need to reset so migration runs with updated mock
+    _resetForTest(join(tempDir, "linear-connections-legacy.json"));
+    // Migration should create a connection from the legacy key
+    const result = resolveApiKey();
+    expect(result).not.toBeNull();
+    expect(result!.apiKey).toBe("lin_api_legacy");
+  });
+
+  it("resolveApiKey returns null when nothing configured", () => {
+    expect(resolveApiKey()).toBeNull();
+  });
+
+  // ─── Migration ─────────────────────────────────────────────────────
+
+  it("migrates from settings.linearApiKey on first load", () => {
+    vi.mocked(getSettings).mockReturnValue({
+      linearApiKey: "lin_api_migrated",
+      linearAutoTransition: true,
+      linearAutoTransitionStateId: "state-1",
+      linearAutoTransitionStateName: "In Progress",
+      linearArchiveTransition: false,
+      linearArchiveTransitionStateId: "",
+      linearArchiveTransitionStateName: "",
+      anthropicApiKey: "",
+      anthropicModel: "",
+      linearOAuthClientId: "",
+      linearOAuthClientSecret: "",
+      linearOAuthWebhookSecret: "",
+      linearOAuthAccessToken: "",
+      linearOAuthRefreshToken: "",
+      claudeCodeOAuthToken: "",
+      openaiApiKey: "",
+      onboardingCompleted: false,
+      aiValidationEnabled: false,
+      aiValidationAutoApprove: true,
+      aiValidationAutoDeny: false,
+      publicUrl: "",
+      updateChannel: "stable",
+      dockerAutoUpdate: false,
+      updatedAt: 0,
+    });
+    _resetForTest(join(tempDir, "linear-connections-migrate.json"));
+
+    const conns = listConnections();
+    expect(conns).toHaveLength(1);
+    expect(conns[0].name).toBe("Default");
+    expect(conns[0].apiKey).toBe("lin_api_migrated");
+    expect(conns[0].autoTransition).toBe(true);
+    expect(conns[0].autoTransitionStateId).toBe("state-1");
+  });
+
+  it("does not migrate when connections already exist on disk", () => {
+    // Pre-populate the file with an existing connection
+    writeFileSync(
+      join(tempDir, "linear-connections-existing.json"),
+      JSON.stringify([{
+        id: "existing-id",
+        name: "Existing",
+        apiKey: "lin_api_existing",
+        workspaceName: "",
+        workspaceId: "",
+        viewerName: "",
+        viewerEmail: "",
+        connected: false,
+        autoTransition: false,
+        autoTransitionStateId: "",
+        autoTransitionStateName: "",
+        archiveTransition: false,
+        archiveTransitionStateId: "",
+        archiveTransitionStateName: "",
+        createdAt: 1000,
+        updatedAt: 1000,
+      }]),
+    );
+
+    vi.mocked(getSettings).mockReturnValue({
+      linearApiKey: "lin_api_should_not_migrate",
+      linearAutoTransition: false,
+      linearAutoTransitionStateId: "",
+      linearAutoTransitionStateName: "",
+      linearArchiveTransition: false,
+      linearArchiveTransitionStateId: "",
+      linearArchiveTransitionStateName: "",
+      anthropicApiKey: "",
+      anthropicModel: "",
+      linearOAuthClientId: "",
+      linearOAuthClientSecret: "",
+      linearOAuthWebhookSecret: "",
+      linearOAuthAccessToken: "",
+      linearOAuthRefreshToken: "",
+      claudeCodeOAuthToken: "",
+      openaiApiKey: "",
+      onboardingCompleted: false,
+      aiValidationEnabled: false,
+      aiValidationAutoApprove: true,
+      aiValidationAutoDeny: false,
+      publicUrl: "",
+      updateChannel: "stable",
+      dockerAutoUpdate: false,
+      updatedAt: 0,
+    });
+
+    _resetForTest(join(tempDir, "linear-connections-existing.json"));
+    const conns = listConnections();
+    expect(conns).toHaveLength(1);
+    expect(conns[0].name).toBe("Existing");
+  });
+
+  // ─── Persistence ───────────────────────────────────────────────────
+
+  it("loads existing data from disk on first access", () => {
+    const existingConn = {
+      id: "loaded-id",
+      name: "Loaded",
+      apiKey: "lin_api_loaded",
+      workspaceName: "WS",
+      workspaceId: "ws-id",
+      viewerName: "User",
+      viewerEmail: "user@test.com",
+      connected: true,
+      autoTransition: false,
+      autoTransitionStateId: "",
+      autoTransitionStateName: "",
+      archiveTransition: false,
+      archiveTransitionStateId: "",
+      archiveTransitionStateName: "",
+      createdAt: 1000,
+      updatedAt: 2000,
+    };
+    writeFileSync(
+      join(tempDir, "linear-connections.json"),
+      JSON.stringify([existingConn]),
+    );
+    _resetForTest(join(tempDir, "linear-connections.json"));
+    const conn = getConnection("loaded-id");
+    expect(conn?.name).toBe("Loaded");
+    expect(conn?.workspaceName).toBe("WS");
+  });
+
+  it("handles corrupt JSON gracefully", () => {
+    writeFileSync(join(tempDir, "linear-connections.json"), "NOT VALID JSON");
+    _resetForTest(join(tempDir, "linear-connections.json"));
+    expect(listConnections()).toEqual([]);
+  });
+
+  it("creates parent directories if needed", () => {
+    const nestedPath = join(tempDir, "nested", "dir", "connections.json");
+    _resetForTest(nestedPath);
+    createConnection({ name: "Nested", apiKey: "lin_api_nested" });
+    expect(listConnections()).toHaveLength(1);
+  });
+});

package/server/linear-connections.ts

@@ -0,0 +1,231 @@
+import {
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  existsSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { randomUUID } from "node:crypto";
+import { getSettings } from "./settings-manager.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface LinearConnection {
+  id: string;
+  name: string;
+  apiKey: string;
+  workspaceName: string;
+  workspaceId: string;
+  viewerName: string;
+  viewerEmail: string;
+  connected: boolean;
+  autoTransition: boolean;
+  autoTransitionStateId: string;
+  autoTransitionStateName: string;
+  archiveTransition: boolean;
+  archiveTransitionStateId: string;
+  archiveTransitionStateName: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+// ─── Paths ───────────────────────────────────────────────────────────────────
+
+const DEFAULT_PATH = join(homedir(), ".companion", "linear-connections.json");
+
+// ─── Store ───────────────────────────────────────────────────────────────────
+
+let connections: LinearConnection[] = [];
+let loaded = false;
+let filePath = DEFAULT_PATH;
+
+function ensureLoaded(): void {
+  if (loaded) return;
+  try {
+    if (existsSync(filePath)) {
+      const raw = JSON.parse(readFileSync(filePath, "utf-8"));
+      if (Array.isArray(raw)) {
+        connections = raw.filter(
+          (c: unknown): c is LinearConnection =>
+            typeof c === "object" &&
+            c !== null &&
+            typeof (c as LinearConnection).id === "string" &&
+            typeof (c as LinearConnection).apiKey === "string",
+        );
+      } else {
+        connections = [];
+      }
+    }
+  } catch {
+    connections = [];
+  }
+  loaded = true;
+
+  // Auto-migrate from settings.json if no connections exist
+  migrateFromSettings();
+}
+
+function persist(): void {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(connections, null, 2), "utf-8");
+}
+
+// ─── Migration ───────────────────────────────────────────────────────────────
+
+/**
+ * One-time migration: if no connections exist but settings.linearApiKey is set,
+ * create a "Default" connection from it.
+ */
+function migrateFromSettings(): void {
+  if (connections.length > 0) return;
+
+  const settings = getSettings();
+  if (!settings.linearApiKey.trim()) return;
+
+  const now = Date.now();
+  connections.push({
+    id: randomUUID(),
+    name: "Default",
+    apiKey: settings.linearApiKey.trim(),
+    workspaceName: "",
+    workspaceId: "",
+    viewerName: "",
+    viewerEmail: "",
+    connected: false,
+    autoTransition: settings.linearAutoTransition,
+    autoTransitionStateId: settings.linearAutoTransitionStateId,
+    autoTransitionStateName: settings.linearAutoTransitionStateName,
+    archiveTransition: settings.linearArchiveTransition,
+    archiveTransitionStateId: settings.linearArchiveTransitionStateId,
+    archiveTransitionStateName: settings.linearArchiveTransitionStateName,
+    createdAt: now,
+    updatedAt: now,
+  });
+  persist();
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+export function listConnections(): LinearConnection[] {
+  ensureLoaded();
+  return [...connections];
+}
+
+export function getConnection(id: string): LinearConnection | null {
+  ensureLoaded();
+  return connections.find((c) => c.id === id) ?? null;
+}
+
+/** Returns the first connection (used as default when no connectionId is specified). */
+export function getDefaultConnection(): LinearConnection | null {
+  ensureLoaded();
+  return connections[0] ?? null;
+}
+
+export function createConnection(data: {
+  name: string;
+  apiKey: string;
+}): LinearConnection {
+  ensureLoaded();
+  const now = Date.now();
+  const conn: LinearConnection = {
+    id: randomUUID(),
+    name: data.name.trim(),
+    apiKey: data.apiKey.trim(),
+    workspaceName: "",
+    workspaceId: "",
+    viewerName: "",
+    viewerEmail: "",
+    connected: false,
+    autoTransition: false,
+    autoTransitionStateId: "",
+    autoTransitionStateName: "",
+    archiveTransition: false,
+    archiveTransitionStateId: "",
+    archiveTransitionStateName: "",
+    createdAt: now,
+    updatedAt: now,
+  };
+  connections.push(conn);
+  persist();
+  return conn;
+}
+
+export function updateConnection(
+  id: string,
+  patch: Partial<Omit<LinearConnection, "id" | "createdAt">>,
+): LinearConnection | null {
+  ensureLoaded();
+  const conn = connections.find((c) => c.id === id);
+  if (!conn) return null;
+
+  if (patch.name !== undefined) conn.name = patch.name.trim();
+  if (patch.apiKey !== undefined) conn.apiKey = patch.apiKey.trim();
+  if (patch.workspaceName !== undefined) conn.workspaceName = patch.workspaceName;
+  if (patch.workspaceId !== undefined) conn.workspaceId = patch.workspaceId;
+  if (patch.viewerName !== undefined) conn.viewerName = patch.viewerName;
+  if (patch.viewerEmail !== undefined) conn.viewerEmail = patch.viewerEmail;
+  if (patch.connected !== undefined) conn.connected = patch.connected;
+  if (patch.autoTransition !== undefined) conn.autoTransition = patch.autoTransition;
+  if (patch.autoTransitionStateId !== undefined) conn.autoTransitionStateId = patch.autoTransitionStateId;
+  if (patch.autoTransitionStateName !== undefined) conn.autoTransitionStateName = patch.autoTransitionStateName;
+  if (patch.archiveTransition !== undefined) conn.archiveTransition = patch.archiveTransition;
+  if (patch.archiveTransitionStateId !== undefined) conn.archiveTransitionStateId = patch.archiveTransitionStateId;
+  if (patch.archiveTransitionStateName !== undefined) conn.archiveTransitionStateName = patch.archiveTransitionStateName;
+  conn.updatedAt = Date.now();
+
+  persist();
+  return conn;
+}
+
+export function deleteConnection(id: string): boolean {
+  ensureLoaded();
+  const idx = connections.findIndex((c) => c.id === id);
+  if (idx === -1) return false;
+  connections.splice(idx, 1);
+  persist();
+  return true;
+}
+
+/**
+ * Resolve a Linear API key from a connectionId.
+ * - If connectionId is provided, look up that specific connection.
+ * - Otherwise, fall back to the first connection.
+ * - As a last resort, fall back to the legacy settings.linearApiKey.
+ * Returns null if no API key can be found.
+ */
+export function resolveApiKey(
+  connectionId?: string,
+): { apiKey: string; connectionId: string } | null {
+  ensureLoaded();
+
+  if (connectionId) {
+    const conn = connections.find((c) => c.id === connectionId);
+    if (conn?.apiKey.trim()) {
+      return { apiKey: conn.apiKey.trim(), connectionId: conn.id };
+    }
+    return null;
+  }
+
+  // Default to first connection
+  const defaultConn = connections[0];
+  if (defaultConn?.apiKey.trim()) {
+    return { apiKey: defaultConn.apiKey.trim(), connectionId: defaultConn.id };
+  }
+
+  // Legacy fallback: settings.linearApiKey
+  const settings = getSettings();
+  if (settings.linearApiKey.trim()) {
+    return { apiKey: settings.linearApiKey.trim(), connectionId: "legacy" };
+  }
+
+  return null;
+}
+
+/** Reset internal state and optionally set a custom file path (for testing). */
+export function _resetForTest(customPath?: string): void {
+  connections = [];
+  loaded = false;
+  filePath = customPath || DEFAULT_PATH;
+}