@hellcoder/companion 0.96.0

package/server/path-resolver.ts

@@ -0,0 +1,186 @@
+/**
+ * PATH discovery and binary resolution for service environments.
+ *
+ * When The Companion runs as a macOS launchd or Linux systemd service, it inherits
+ * a restricted PATH that omits directories from version managers (nvm, fnm, volta,
+ * mise, etc.) and user-local installs (~/.local/bin, ~/.cargo/bin). This module
+ * captures the user's real shell PATH at runtime and provides binary resolution
+ * that works regardless of how the server was started.
+ */
+
+import { execSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Capture the user's full interactive shell PATH by spawning a login shell.
+ * This picks up all version manager initializations (nvm, fnm, volta, mise, etc.).
+ * Falls back to probing common directories if shell sourcing fails.
+ */
+export function captureUserShellPath(): string {
+  try {
+    const shell = process.env.SHELL || "/bin/bash";
+    const captured = execSync(
+      `${shell} -lic 'echo "___PATH_START___$PATH___PATH_END___"'`,
+      {
+        encoding: "utf-8",
+        timeout: 10_000,
+        env: { HOME: homedir(), USER: process.env.USER, SHELL: shell },
+      },
+    );
+    const match = captured.match(/___PATH_START___(.+)___PATH_END___/);
+    if (match?.[1]) {
+      return match[1];
+    }
+  } catch {
+    // Shell sourcing failed (timeout, compinit prompt, etc.)
+  }
+
+  return buildFallbackPath();
+}
+
+/**
+ * Build a PATH by probing common binary installation directories.
+ * Used as fallback when shell-sourcing fails.
+ */
+export function buildFallbackPath(): string {
+  const home = homedir();
+  const candidates = [
+    // Standard system paths
+    "/opt/homebrew/bin",
+    "/opt/homebrew/sbin",
+    "/usr/local/bin",
+    "/usr/bin",
+    "/bin",
+    "/usr/sbin",
+    "/sbin",
+    // Bun
+    join(home, ".bun", "bin"),
+    // Claude CLI / user-local installs
+    join(home, ".local", "bin"),
+    // Cargo / Rust
+    join(home, ".cargo", "bin"),
+    // Volta (Node version manager)
+    join(home, ".volta", "bin"),
+    // mise (formerly rtx)
+    join(home, ".local", "share", "mise", "shims"),
+    // pyenv
+    join(home, ".pyenv", "bin"),
+    join(home, ".pyenv", "shims"),
+    // Go
+    join(home, "go", "bin"),
+    "/usr/local/go/bin",
+    // Deno
+    join(home, ".deno", "bin"),
+  ];
+
+  // Probe nvm-managed node versions
+  const nvmDir = process.env.NVM_DIR || join(home, ".nvm");
+  const nvmVersionsDir = join(nvmDir, "versions", "node");
+  if (existsSync(nvmVersionsDir)) {
+    try {
+      for (const v of readdirSync(nvmVersionsDir)) {
+        candidates.push(join(nvmVersionsDir, v, "bin"));
+      }
+    } catch { /* ignore */ }
+  }
+
+  // fnm (Fast Node Manager) — versions stored in fnm multishell or XDG data
+  const fnmDir = join(home, "Library", "Application Support", "fnm", "node-versions");
+  if (existsSync(fnmDir)) {
+    try {
+      for (const v of readdirSync(fnmDir)) {
+        candidates.push(join(fnmDir, v, "installation", "bin"));
+      }
+    } catch { /* ignore */ }
+  }
+
+  const pathSep = process.platform === "win32" ? ";" : ":";
+  return [...new Set(candidates.filter((dir) => existsSync(dir)))].join(pathSep);
+}
+
+// ─── Enriched PATH (cached) ───────────────────────────────────────────────────
+
+let _cachedPath: string | null = null;
+
+/**
+ * Returns an enriched PATH that merges the user's shell PATH (or probed common
+ * directories) with the current process PATH. Deduplicates entries.
+ * Result is cached after the first call.
+ */
+export function getEnrichedPath(): string {
+  if (_cachedPath) return _cachedPath;
+
+  const currentPath = process.env.PATH || "";
+  const userPath = captureUserShellPath();
+  const pathSep = process.platform === "win32" ? ";" : ":";
+
+  // Merge: user shell PATH first (takes precedence), then current process PATH
+  const allDirs = [...userPath.split(pathSep), ...currentPath.split(pathSep)];
+  const seen = new Set<string>();
+  const deduped: string[] = [];
+  for (const dir of allDirs) {
+    if (dir && !seen.has(dir)) {
+      seen.add(dir);
+      deduped.push(dir);
+    }
+  }
+
+  _cachedPath = deduped.join(pathSep);
+  return _cachedPath;
+}
+
+/** Reset the cached PATH (for testing). */
+export function _resetPathCache(): void {
+  _cachedPath = null;
+}
+
+// ─── Binary resolution ────────────────────────────────────────────────────────
+
+/**
+ * Resolve a binary name to an absolute path using the enriched PATH.
+ * Returns null if the binary is not found anywhere.
+ */
+export function resolveBinary(name: string): string | null {
+  if (name.startsWith("/")) {
+    return existsSync(name) ? name : null;
+  }
+  // On Windows, also accept absolute paths like C:\... or D:\...
+  if (process.platform === "win32" && /^[a-zA-Z]:[/\\]/.test(name)) {
+    return existsSync(name) ? name : null;
+  }
+
+  const sanitized = name.replace(/[^a-zA-Z0-9._@/-]/g, "");
+  const enrichedPath = getEnrichedPath();
+
+  // Try `where` first on Windows (returns native Win32 paths), then `which` as fallback
+  const commands = process.platform === "win32" ? ["where", "which"] : ["which"];
+  for (const cmd of commands) {
+    try {
+      const result = execSync(`${cmd} ${sanitized}`, {
+        encoding: "utf-8",
+        timeout: 5_000,
+        env: { ...process.env, PATH: enrichedPath },
+      }).trim();
+      if (!result) continue;
+      // `where` on Windows may return multiple lines; prefer .cmd for Bun.spawn compatibility
+      if (cmd === "where") {
+        const lines = result.split(/\r?\n/).filter(Boolean);
+        return lines.find(l => l.endsWith(".cmd")) || lines[0];
+      }
+      return result;
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * Returns a PATH string suitable for embedding in service definitions
+ * (plist/systemd unit). Captures the user's shell PATH at install time.
+ */
+export function getServicePath(): string {
+  return getEnrichedPath();
+}

package/server/paths.test.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+describe("paths", () => {
+  const originalEnv = process.env.COMPANION_HOME;
+
+  afterEach(() => {
+    // Restore original env
+    if (originalEnv === undefined) {
+      delete process.env.COMPANION_HOME;
+    } else {
+      process.env.COMPANION_HOME = originalEnv;
+    }
+  });
+
+  it("defaults to ~/.companion/ when COMPANION_HOME is not set", async () => {
+    delete process.env.COMPANION_HOME;
+    // Dynamic import to pick up env change (module is already cached, so we
+    // test the value computed at import time — which uses the env at startup)
+    const { COMPANION_HOME } = await import("./paths.js");
+    // When env var is unset at module load time, it should be ~/.companion
+    expect(COMPANION_HOME).toBe(join(homedir(), ".companion"));
+  });
+
+  it("exports a string path", async () => {
+    const { COMPANION_HOME } = await import("./paths.js");
+    expect(typeof COMPANION_HOME).toBe("string");
+    expect(COMPANION_HOME.length).toBeGreaterThan(0);
+  });
+});

package/server/paths.ts

@@ -0,0 +1,11 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+/**
+ * Base directory for all Companion configuration and state.
+ * Defaults to ~/.companion/ for self-hosted installs.
+ * Override with COMPANION_HOME env var for managed deployments
+ * (e.g. COMPANION_HOME=/data/companion on Fly.io volumes).
+ */
+export const COMPANION_HOME =
+  process.env.COMPANION_HOME || join(homedir(), ".companion");

package/server/pr-poller.test.ts

@@ -0,0 +1,191 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// ─── Mocks ──────────────────────────────────────────────────────────────────
+
+const mockFetchPRInfoAsync = vi.hoisted(() => vi.fn());
+const mockComputeAdaptiveTTL = vi.hoisted(() => vi.fn());
+
+vi.mock("./github-pr.js", () => ({
+  fetchPRInfoAsync: mockFetchPRInfoAsync,
+  computeAdaptiveTTL: mockComputeAdaptiveTTL,
+}));
+
+import { PRPoller } from "./pr-poller.js";
+import type { GitHubPRInfo } from "./github-pr.js";
+
+function makeMockBridge() {
+  return {
+    broadcastToSession: vi.fn(),
+  } as any;
+}
+
+function makePR(overrides?: Partial<GitHubPRInfo>): GitHubPRInfo {
+  return {
+    number: 42,
+    title: "test pr",
+    url: "https://github.com/org/repo/pull/42",
+    state: "OPEN",
+    isDraft: false,
+    reviewDecision: null,
+    additions: 10,
+    deletions: 5,
+    changedFiles: 2,
+    checks: [],
+    checksSummary: { total: 0, success: 0, failure: 0, pending: 0 },
+    reviewThreads: { total: 0, resolved: 0, unresolved: 0 },
+    ...overrides,
+  };
+}
+
+/** Flush microtasks so async callbacks in the poller can settle. */
+async function flushMicrotasks() {
+  await new Promise((r) => setTimeout(r, 0));
+}
+
+// ─── Tests ──────────────────────────────────────────────────────────────────
+
+describe("PRPoller", () => {
+  let poller: PRPoller;
+  let bridge: ReturnType<typeof makeMockBridge>;
+
+  beforeEach(() => {
+    mockFetchPRInfoAsync.mockReset();
+    mockComputeAdaptiveTTL.mockReset();
+    mockComputeAdaptiveTTL.mockReturnValue(30_000);
+    bridge = makeMockBridge();
+    poller = new PRPoller(bridge);
+  });
+
+  afterEach(() => {
+    poller.destroy();
+  });
+
+  it("returns null on initial watch (no cached data)", () => {
+    mockFetchPRInfoAsync.mockResolvedValue(null);
+    const result = poller.watch("s1", "/repo", "main");
+    expect(result).toBeNull();
+  });
+
+  it("fetches and broadcasts PR data after watch", async () => {
+    const pr = makePR();
+    mockFetchPRInfoAsync.mockResolvedValue(pr);
+
+    poller.watch("s1", "/repo", "feat/test");
+
+    // Let the async fetch settle
+    await flushMicrotasks();
+
+    expect(mockFetchPRInfoAsync).toHaveBeenCalledWith("/repo", "feat/test");
+    expect(bridge.broadcastToSession).toHaveBeenCalledWith("s1", {
+      type: "pr_status_update",
+      pr,
+      available: true,
+    });
+  });
+
+  it("shares one timer across multiple sessions watching the same branch", async () => {
+    const pr = makePR();
+    mockFetchPRInfoAsync.mockResolvedValue(pr);
+
+    poller.watch("s1", "/repo", "main");
+    poller.watch("s2", "/repo", "main");
+
+    await flushMicrotasks();
+
+    // Should only have fetched once (shared timer)
+    expect(mockFetchPRInfoAsync).toHaveBeenCalledTimes(1);
+    // But should broadcast to both sessions
+    expect(bridge.broadcastToSession).toHaveBeenCalledWith("s1", expect.objectContaining({ type: "pr_status_update" }));
+    expect(bridge.broadcastToSession).toHaveBeenCalledWith("s2", expect.objectContaining({ type: "pr_status_update" }));
+  });
+
+  it("returns cached data on subsequent watch calls", async () => {
+    const pr = makePR();
+    mockFetchPRInfoAsync.mockResolvedValue(pr);
+
+    poller.watch("s1", "/repo", "main");
+    await flushMicrotasks();
+
+    // Second session watches the same branch — should get cached data
+    const cached = poller.watch("s2", "/repo", "main");
+    expect(cached).toEqual(pr);
+  });
+
+  it("cleans up when last session unwatches", async () => {
+    mockFetchPRInfoAsync.mockResolvedValue(makePR());
+
+    poller.watch("s1", "/repo", "main");
+    poller.watch("s2", "/repo", "main");
+    await flushMicrotasks();
+
+    poller.unwatch("s1");
+    // Still one session watching — cache should remain
+    expect(poller.getCached("/repo", "main")).not.toBeNull();
+
+    poller.unwatch("s2");
+    // No sessions left — should be cleaned up
+    expect(poller.getCached("/repo", "main")).toBeNull();
+  });
+
+  it("getCached returns null for unknown branches", () => {
+    expect(poller.getCached("/repo", "nonexistent")).toBeNull();
+  });
+
+  it("uses computeAdaptiveTTL for scheduling", async () => {
+    const pr = makePR({ checksSummary: { total: 3, success: 1, failure: 0, pending: 2 } });
+    mockFetchPRInfoAsync.mockResolvedValue(pr);
+    mockComputeAdaptiveTTL.mockReturnValue(10_000);
+
+    poller.watch("s1", "/repo", "feat/ci");
+    await flushMicrotasks();
+
+    expect(mockComputeAdaptiveTTL).toHaveBeenCalledWith(pr);
+  });
+
+  it("handles session switching branches (unwatches old, watches new)", async () => {
+    mockFetchPRInfoAsync.mockResolvedValue(makePR());
+
+    poller.watch("s1", "/repo", "branch-a");
+    await flushMicrotasks();
+
+    // Same session now watches a different branch
+    poller.watch("s1", "/repo", "branch-b");
+    await flushMicrotasks();
+
+    // Old branch should have been cleaned up (only session was s1)
+    expect(poller.getCached("/repo", "branch-a")).toBeNull();
+    expect(poller.getCached("/repo", "branch-b")).not.toBeNull();
+  });
+
+  it("handles fetch errors gracefully", async () => {
+    mockFetchPRInfoAsync.mockRejectedValue(new Error("network error"));
+
+    poller.watch("s1", "/repo", "main");
+    await flushMicrotasks();
+
+    // Should not throw, should not broadcast (no data on error)
+    expect(bridge.broadcastToSession).not.toHaveBeenCalled();
+  });
+
+  it("prevents concurrent fetches for the same key", async () => {
+    // Create a fetch that takes time to resolve
+    let resolveFirst: (value: GitHubPRInfo) => void;
+    mockFetchPRInfoAsync.mockReturnValueOnce(
+      new Promise<GitHubPRInfo>((r) => { resolveFirst = r; }),
+    );
+
+    poller.watch("s1", "/repo", "main");
+    // Try to trigger another fetch immediately (e.g., from a second session)
+    poller.watch("s2", "/repo", "main");
+
+    // Only one fetch should have started
+    expect(mockFetchPRInfoAsync).toHaveBeenCalledTimes(1);
+
+    // Resolve the first fetch
+    resolveFirst!(makePR());
+    await flushMicrotasks();
+
+    // Now broadcast should have gone to both sessions
+    expect(bridge.broadcastToSession).toHaveBeenCalledTimes(2);
+  });
+});

package/server/pr-poller.ts

@@ -0,0 +1,162 @@
+import { fetchPRInfoAsync, computeAdaptiveTTL, type GitHubPRInfo } from "./github-pr.js";
+import type { WsBridge } from "./ws-bridge.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+interface WatchedPR {
+  cwd: string;
+  branch: string;
+  /** Sessions interested in this PR (same cwd:branch may be shared) */
+  sessionIds: Set<string>;
+  lastData: GitHubPRInfo | null;
+  timer: ReturnType<typeof setTimeout> | null;
+  lastFetchTime: number;
+  currentInterval: number;
+  fetching: boolean;
+}
+
+// ─── PR Poller ───────────────────────────────────────────────────────────────
+
+/**
+ * Server-side poller that fetches GitHub PR status at adaptive intervals
+ * and pushes updates to browsers via WebSocket.
+ *
+ * One timer per unique cwd:branch — shared across sessions on the same branch.
+ */
+export class PRPoller {
+  private watched = new Map<string, WatchedPR>();
+  private wsBridge: WsBridge;
+  /** Reverse index: sessionId → cwd:branch key (a session can only watch one PR at a time) */
+  private sessionToKey = new Map<string, string>();
+
+  constructor(wsBridge: WsBridge) {
+    this.wsBridge = wsBridge;
+  }
+
+  /**
+   * Start watching a PR for a session.
+   * Returns cached data immediately if available.
+   * Triggers an async fetch if cache is stale or missing.
+   */
+  watch(sessionId: string, cwd: string, branch: string): GitHubPRInfo | null {
+    const key = `${cwd}:${branch}`;
+
+    // If this session was watching a different PR, unregister from the old one
+    const prevKey = this.sessionToKey.get(sessionId);
+    if (prevKey && prevKey !== key) {
+      this.unwatchKey(sessionId, prevKey);
+    }
+    this.sessionToKey.set(sessionId, key);
+
+    const existing = this.watched.get(key);
+    if (existing) {
+      existing.sessionIds.add(sessionId);
+      // If cache is stale, trigger a refresh
+      if (Date.now() - existing.lastFetchTime > existing.currentInterval) {
+        this.fetchAndBroadcast(key);
+      }
+      return existing.lastData;
+    }
+
+    // New watch — create entry and fetch immediately
+    const entry: WatchedPR = {
+      cwd,
+      branch,
+      sessionIds: new Set([sessionId]),
+      lastData: null,
+      timer: null,
+      lastFetchTime: 0,
+      currentInterval: 10_000, // start aggressive for fast initial load
+      fetching: false,
+    };
+    this.watched.set(key, entry);
+    this.fetchAndBroadcast(key);
+
+    return null;
+  }
+
+  /** Stop watching for a specific session. */
+  unwatch(sessionId: string): void {
+    const key = this.sessionToKey.get(sessionId);
+    if (!key) return;
+    this.sessionToKey.delete(sessionId);
+    this.unwatchKey(sessionId, key);
+  }
+
+  /** Get current cached data for a cwd:branch pair (for REST fallback). */
+  getCached(cwd: string, branch: string): { available: boolean; pr: GitHubPRInfo | null } | null {
+    const key = `${cwd}:${branch}`;
+    const entry = this.watched.get(key);
+    if (!entry) return null;
+    return { available: true, pr: entry.lastData };
+  }
+
+  /** Stop all timers (for testing / cleanup). */
+  destroy(): void {
+    for (const entry of this.watched.values()) {
+      if (entry.timer) clearTimeout(entry.timer);
+    }
+    this.watched.clear();
+    this.sessionToKey.clear();
+  }
+
+  // ─── Internal ──────────────────────────────────────────────────────────
+
+  private unwatchKey(sessionId: string, key: string): void {
+    const entry = this.watched.get(key);
+    if (!entry) return;
+    entry.sessionIds.delete(sessionId);
+    if (entry.sessionIds.size === 0) {
+      if (entry.timer) clearTimeout(entry.timer);
+      this.watched.delete(key);
+    }
+  }
+
+  private async fetchAndBroadcast(key: string): Promise<void> {
+    const entry = this.watched.get(key);
+    if (!entry) return;
+
+    // Prevent concurrent fetches for the same key
+    if (entry.fetching) return;
+    entry.fetching = true;
+
+    // Clear existing timer (will be rescheduled after fetch)
+    if (entry.timer) {
+      clearTimeout(entry.timer);
+      entry.timer = null;
+    }
+
+    try {
+      const prInfo = await fetchPRInfoAsync(entry.cwd, entry.branch);
+      // Re-check entry still exists (may have been unwatched during async fetch)
+      const current = this.watched.get(key);
+      if (!current) return;
+
+      current.lastData = prInfo;
+      current.lastFetchTime = Date.now();
+      current.currentInterval = computeAdaptiveTTL(prInfo);
+
+      // Push to all sessions watching this PR
+      for (const sessionId of current.sessionIds) {
+        this.wsBridge.broadcastToSession(sessionId, {
+          type: "pr_status_update",
+          pr: prInfo,
+          available: true,
+        });
+      }
+    } catch {
+      // On error, use a moderate interval
+      const current = this.watched.get(key);
+      if (current) {
+        current.currentInterval = 30_000;
+      }
+    } finally {
+      const current = this.watched.get(key);
+      if (current) {
+        current.fetching = false;
+        // Schedule next fetch
+        current.timer = setTimeout(() => this.fetchAndBroadcast(key), current.currentInterval);
+      }
+    }
+  }
+}