heyhank 0.1.0

package/server/logger.ts

@@ -0,0 +1,259 @@
+// Lightweight structured logger for the HeyHank server.
+// Provides JSON-structured log output for operational events while
+// keeping the familiar console.log interface for human-readable logs.
+//
+// Log file persistence:
+//   By default, all log output is also written to ~/.heyhank/logs/ with
+//   automatic rotation (oldest files deleted when total lines exceed 2M).
+//   Disable with HEYHANK_LOG_FILE=0, override dir with HEYHANK_LOG_DIR,
+//   and configure rotation with HEYHANK_LOG_MAX_LINES.
+//
+// Usage:
+//   import { log } from "./logger.js";
+//   log.info("ws-bridge", "Browser connected", { sessionId, browsers: 3 });
+//   log.warn("orchestrator", "Git fetch failed", { sessionId, error: "..." });
+//   log.error("cli-launcher", "Process crashed", { sessionId, exitCode: 1 });
+
+import {
+  mkdirSync,
+  openSync,
+  writeSync,
+  closeSync,
+  readdirSync,
+  statSync,
+  unlinkSync,
+} from "node:fs";
+import { join } from "node:path";
+import { HEYHANK_HOME } from "./paths.js";
+import { countFileLines } from "./fs-utils.js";
+
+type LogLevel = "info" | "warn" | "error";
+
+interface LogEntry {
+  ts: string;
+  level: LogLevel;
+  module: string;
+  msg: string;
+  [key: string]: unknown;
+}
+
+const STRUCTURED = (process.env.HEYHANK_LOG_FORMAT || process.env.COMPANION_LOG_FORMAT) === "json";
+
+function formatEntry(level: LogLevel, module: string, msg: string, data?: Record<string, unknown>): string {
+  if (STRUCTURED) {
+    const entry: LogEntry = {
+      ...data,
+      ts: new Date().toISOString(),
+      level,
+      module,
+      msg,
+    };
+    return JSON.stringify(entry);
+  }
+
+  // Human-readable format (default): [module] msg key=value key=value
+  let line = `[${module}] ${msg}`;
+  if (data) {
+    const pairs = Object.entries(data)
+      .map(([k, v]) => `${k}=${typeof v === "object" ? JSON.stringify(v) : v}`)
+      .join(" ");
+    if (pairs) line += ` | ${pairs}`;
+  }
+  return line;
+}
+
+// ─── Log File Writer ────────────────────────────────────────────────────────
+
+const DEFAULT_LOG_MAX_LINES = 2_000_000;
+const LOG_CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * Writes log lines to a file under ~/.heyhank/logs/ with automatic rotation.
+ * A new log file is created each time the server starts. When total lines across
+ * all log files exceed maxLines (default 2M), the oldest files are deleted.
+ *
+ * Follows the same pattern as RecorderManager for recordings.
+ */
+export class LogFileWriter {
+  readonly filePath: string;
+  private logsDir: string;
+  private maxLines: number;
+  private fd: number;
+  private closed = false;
+  private dirCreated = false;
+  private initialCleanupTimer: ReturnType<typeof setTimeout> | null = null;
+  private cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(options?: { logsDir?: string; maxLines?: number }) {
+    this.logsDir = options?.logsDir ?? LogFileWriter.resolveDir();
+    this.maxLines =
+      options?.maxLines ??
+      (Number(process.env.HEYHANK_LOG_MAX_LINES || process.env.COMPANION_LOG_MAX_LINES) || DEFAULT_LOG_MAX_LINES);
+
+    this.ensureDir();
+
+    // Create a new log file for this server run and keep the fd open
+    const ts = new Date().toISOString().replace(/:/g, "-");
+    const pid = process.pid;
+    this.filePath = join(this.logsDir, `heyhank_${ts}_${pid}.log`);
+    this.fd = openSync(this.filePath, "a");
+
+    // Defer initial cleanup so it doesn't block the event loop at startup
+    this.initialCleanupTimer = setTimeout(() => {
+      this.initialCleanupTimer = null;
+      this.cleanup();
+    }, 2000);
+    if (this.initialCleanupTimer.unref) this.initialCleanupTimer.unref();
+    this.cleanupTimer = setInterval(() => this.cleanup(), LOG_CLEANUP_INTERVAL_MS);
+    if (this.cleanupTimer.unref) this.cleanupTimer.unref();
+  }
+
+  private static resolveDir(): string {
+    return process.env.HEYHANK_LOG_DIR || process.env.COMPANION_LOG_DIR || join(HEYHANK_HOME, "logs");
+  }
+
+  /** Whether log file writing is enabled. Disable with HEYHANK_LOG_FILE=0|false. */
+  static isEnabled(): boolean {
+    const env = process.env.HEYHANK_LOG_FILE || process.env.COMPANION_LOG_FILE;
+    if (env === "0" || env === "false") return false;
+    return true;
+  }
+
+  getLogsDir(): string {
+    return this.logsDir;
+  }
+
+  getMaxLines(): number {
+    return this.maxLines;
+  }
+
+  write(line: string): void {
+    if (this.closed) return;
+    try {
+      writeSync(this.fd, line + "\n");
+    } catch {
+      // Never throw — logging must not disrupt normal operation
+    }
+  }
+
+  /**
+   * Delete oldest log files until total lines are under maxLines.
+   * Skips the current log file (still being written to).
+   */
+  cleanup(): number {
+    try {
+      this.ensureDir();
+      const files = readdirSync(this.logsDir).filter((f) => f.endsWith(".log"));
+      if (files.length === 0) return 0;
+
+      const entries: { filename: string; path: string; lines: number; mtimeMs: number }[] = [];
+      let totalLines = 0;
+
+      for (const filename of files) {
+        const fullPath = join(this.logsDir, filename);
+        const lines = countFileLines(fullPath);
+        let mtimeMs = 0;
+        try {
+          mtimeMs = statSync(fullPath).mtimeMs;
+        } catch {
+          continue;
+        }
+        entries.push({ filename, path: fullPath, lines, mtimeMs });
+        totalLines += lines;
+      }
+
+      if (totalLines <= this.maxLines) return 0;
+
+      // Sort oldest first
+      entries.sort((a, b) => a.mtimeMs - b.mtimeMs);
+
+      let deleted = 0;
+      for (const entry of entries) {
+        if (totalLines <= this.maxLines) break;
+        // Don't delete the current log file
+        if (entry.path === this.filePath) continue;
+        try {
+          unlinkSync(entry.path);
+          totalLines -= entry.lines;
+          deleted++;
+        } catch {
+          // File may have been removed concurrently
+        }
+      }
+
+      if (deleted > 0) {
+        // Log to console only (avoid recursion)
+        console.log(`[logger] Cleanup: deleted ${deleted} old log file(s), ${totalLines} lines remaining`);
+      }
+      return deleted;
+    } catch {
+      return 0;
+    }
+  }
+
+  close(): void {
+    this.closed = true;
+    if (this.initialCleanupTimer) {
+      clearTimeout(this.initialCleanupTimer);
+      this.initialCleanupTimer = null;
+    }
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+    try { closeSync(this.fd); } catch { /* ignore */ }
+  }
+
+  private ensureDir(): void {
+    if (this.dirCreated) return;
+    mkdirSync(this.logsDir, { recursive: true });
+    this.dirCreated = true;
+  }
+}
+
+// ─── Singleton file writer (initialized lazily) ─────────────────────────────
+
+let fileWriter: LogFileWriter | null = null;
+
+/**
+ * Initialize the log file writer. Call once at server startup.
+ * Returns the writer instance for status reporting, or null if disabled.
+ */
+export function initLogFile(options?: { logsDir?: string; maxLines?: number }): LogFileWriter | null {
+  if (!LogFileWriter.isEnabled()) return null;
+  if (fileWriter) {
+    fileWriter.close();
+  }
+  fileWriter = new LogFileWriter(options);
+  return fileWriter;
+}
+
+/** Shut down the log file writer (clears cleanup timer). */
+export function closeLogFile(): void {
+  if (fileWriter) {
+    fileWriter.close();
+    fileWriter = null;
+  }
+}
+
+// ─── Public logger ──────────────────────────────────────────────────────────
+
+export const log = {
+  info(module: string, msg: string, data?: Record<string, unknown>): void {
+    const line = formatEntry("info", module, msg, data);
+    console.log(line);
+    fileWriter?.write(line);
+  },
+
+  warn(module: string, msg: string, data?: Record<string, unknown>): void {
+    const line = formatEntry("warn", module, msg, data);
+    console.warn(line);
+    fileWriter?.write(line);
+  },
+
+  error(module: string, msg: string, data?: Record<string, unknown>): void {
+    const line = formatEntry("error", module, msg, data);
+    console.error(line);
+    fileWriter?.write(line);
+  },
+};

package/server/mcp-registry.ts

@@ -0,0 +1,401 @@
+// ─── MCP Server Registry ──────────────────────────────────────────────────────
+// Manages MCP server configurations: add, remove, enable/disable, catalog install.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { HEYHANK_HOME } from "./paths.js";
+import { randomUUID } from "node:crypto";
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface McpServerEntry {
+  id: string;
+  name: string;
+  description: string;
+  type: "stdio" | "http" | "sse";
+  command?: string;
+  args?: string[];
+  url?: string;
+  headers?: Record<string, string>;
+  env?: Record<string, string>;
+  enabled: boolean;
+  assignedAgents: string[];
+  requiresAuth?: { field: string; label: string; helpText: string }[];
+  authValues?: Record<string, string>;
+}
+
+export interface CatalogEntry {
+  id: string;
+  name: string;
+  description: string;
+  category: string;
+  type: "stdio" | "http" | "sse";
+  command?: string;
+  args?: string[];
+  url?: string;
+  headers?: Record<string, string>;
+  env?: Record<string, string>;
+  requiresAuth?: { field: string; label: string; helpText: string }[];
+}
+
+// ─── Paths ──────────────────────────────────────────────────────────────────
+
+const CONFIG_PATH = join(HEYHANK_HOME, "mcp-servers.json");
+
+function ensureDir(): void {
+  if (!existsSync(HEYHANK_HOME)) {
+    mkdirSync(HEYHANK_HOME, { recursive: true });
+  }
+}
+
+// ─── Persistence ────────────────────────────────────────────────────────────
+
+function loadServers(): McpServerEntry[] {
+  ensureDir();
+  try {
+    if (existsSync(CONFIG_PATH)) {
+      return JSON.parse(readFileSync(CONFIG_PATH, "utf-8")) as McpServerEntry[];
+    }
+  } catch { /* ignore corrupt files */ }
+  return [];
+}
+
+function saveServers(servers: McpServerEntry[]): void {
+  ensureDir();
+  writeFileSync(CONFIG_PATH, JSON.stringify(servers, null, 2), "utf-8");
+  try {
+    chmodSync(CONFIG_PATH, 0o600);
+  } catch { /* may fail on some platforms */ }
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/\s+/g, "-")
+    .replace(/[^a-z0-9-]/g, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function uniqueId(name: string, existing: McpServerEntry[]): string {
+  const base = slugify(name);
+  if (!existing.some((s) => s.id === base)) return base;
+  // Append short suffix to avoid collision
+  const suffix = randomUUID().slice(0, 6);
+  return `${base}-${suffix}`;
+}
+
+// ─── Catalog ────────────────────────────────────────────────────────────────
+
+const CATALOG: CatalogEntry[] = [
+  {
+    id: "github",
+    name: "GitHub",
+    description: "Pull Requests, Issues und Repositories verwalten via GitHub API.",
+    category: "development",
+    type: "http",
+    url: "https://api.githubcopilot.com/mcp/",
+    requiresAuth: [
+      { field: "GITHUB_PERSONAL_ACCESS_TOKEN", label: "GitHub Personal Access Token", helpText: "Erstelle ein Token unter github.com/settings/tokens mit repo & issues Berechtigung." },
+    ],
+  },
+  {
+    id: "playwright",
+    name: "Playwright",
+    description: "Browser-Automatisierung und Testing mit Playwright MCP.",
+    category: "browser",
+    type: "stdio",
+    command: "npx",
+    args: ["@playwright/mcp@latest"],
+  },
+  {
+    id: "context7",
+    name: "Context7",
+    description: "Dokumentations-Lookup fuer Bibliotheken und Frameworks. Liefert aktuelle Docs direkt in den Kontext.",
+    category: "development",
+    type: "stdio",
+    command: "npx",
+    args: ["-y", "@upstash/context7-mcp@latest"],
+  },
+  {
+    id: "brave-search",
+    name: "Brave Search",
+    description: "Web-Suche ohne Google. Nutzt die Brave Search API fuer datenschutzfreundliche Suchergebnisse.",
+    category: "search",
+    type: "stdio",
+    command: "npx",
+    args: ["-y", "@anthropic/mcp-server-brave-search"],
+    env: { BRAVE_API_KEY: "" },
+    requiresAuth: [
+      { field: "BRAVE_API_KEY", label: "Brave API Key", helpText: "API-Key von brave.com/search/api erstellen (kostenlos bis 2000 Anfragen/Monat)." },
+    ],
+  },
+  {
+    id: "notion",
+    name: "Notion",
+    description: "Notion-Seiten und Datenbanken lesen und bearbeiten.",
+    category: "productivity",
+    type: "stdio",
+    command: "npx",
+    args: ["-y", "@anthropic/mcp-server-notion"],
+    env: { NOTION_API_KEY: "" },
+    requiresAuth: [
+      { field: "NOTION_API_KEY", label: "Notion Integration Token", helpText: "Erstelle eine Integration unter notion.so/my-integrations und kopiere den Secret." },
+    ],
+  },
+  {
+    id: "zapier",
+    name: "Zapier",
+    description: "Zugriff auf ueber 5000+ App-Automationen via Zapier MCP.",
+    category: "productivity",
+    type: "http",
+    url: "https://actions.zapier.com/mcp/",
+    requiresAuth: [
+      { field: "ZAPIER_API_KEY", label: "Zapier API Key", helpText: "API-Key aus den Zapier-Einstellungen unter zapier.com/app/settings kopieren." },
+    ],
+  },
+  {
+    id: "google-drive",
+    name: "Google Drive",
+    description: "Google Docs, Sheets und Drive-Dateien durchsuchen und verwalten.",
+    category: "productivity",
+    type: "stdio",
+    command: "npx",
+    args: ["-y", "@anthropic/mcp-server-google-drive"],
+    env: { GOOGLE_APPLICATION_CREDENTIALS: "" },
+    requiresAuth: [
+      { field: "GOOGLE_APPLICATION_CREDENTIALS", label: "Google Service Account JSON-Pfad", helpText: "Pfad zur Service-Account JSON-Datei. Erstelle einen Service Account in der Google Cloud Console." },
+    ],
+  },
+  {
+    id: "google-maps",
+    name: "Google Maps",
+    description: "Orte, Adressen und Routen via Google Maps API abfragen.",
+    category: "other",
+    type: "stdio",
+    command: "npx",
+    args: ["-y", "@anthropic/mcp-server-google-maps"],
+    env: { GOOGLE_MAPS_API_KEY: "" },
+    requiresAuth: [
+      { field: "GOOGLE_MAPS_API_KEY", label: "Google Maps API Key", helpText: "API-Key in der Google Cloud Console unter APIs & Services erstellen." },
+    ],
+  },
+  {
+    id: "puppeteer",
+    name: "Puppeteer",
+    description: "Browser-Automatisierung mit Puppeteer. Screenshots, Navigation, Formular-Ausfuellung.",
+    category: "browser",
+    type: "stdio",
+    command: "npx",
+    args: ["-y", "@anthropic/mcp-server-puppeteer"],
+  },
+  {
+    id: "memory",
+    name: "Memory",
+    description: "Langzeit-Gedaechtnis fuer Agenten. Speichert und ruft Wissen ueber Sessions hinweg ab.",
+    category: "ai",
+    type: "stdio",
+    command: "npx",
+    args: ["-y", "@anthropic/mcp-server-memory"],
+  },
+  {
+    id: "filesystem",
+    name: "Filesystem",
+    description: "Kontrollierter Dateizugriff. Lesen, Schreiben und Durchsuchen von Dateien in definierten Verzeichnissen.",
+    category: "other",
+    type: "stdio",
+    command: "npx",
+    args: ["-y", "@anthropic/mcp-server-filesystem", "/home"],
+  },
+  {
+    id: "slack",
+    name: "Slack",
+    description: "Slack-Nachrichten lesen und senden. Channels und Threads verwalten.",
+    category: "communication",
+    type: "http",
+    url: "https://slack.com/api/mcp",
+    requiresAuth: [
+      { field: "SLACK_BOT_TOKEN", label: "Slack Bot Token", helpText: "Bot Token (xoxb-...) aus der Slack App Konfiguration unter api.slack.com/apps." },
+    ],
+  },
+  {
+    id: "stripe",
+    name: "Stripe",
+    description: "Zahlungen, Kunden und Abonnements ueber die Stripe API verwalten.",
+    category: "database",
+    type: "http",
+    url: "https://mcp.stripe.com/",
+    requiresAuth: [
+      { field: "STRIPE_API_KEY", label: "Stripe Secret Key", helpText: "Secret Key aus dem Stripe Dashboard unter dashboard.stripe.com/apikeys." },
+    ],
+  },
+  {
+    id: "supabase",
+    name: "Supabase",
+    description: "Supabase-Datenbank abfragen und verwalten. SQL-Queries und Tabellen-Operationen.",
+    category: "database",
+    type: "http",
+    url: "https://supabase.com/api/mcp",
+    requiresAuth: [
+      { field: "SUPABASE_URL", label: "Supabase Project URL", helpText: "Projekt-URL aus dem Supabase Dashboard (z.B. https://xyz.supabase.co)." },
+      { field: "SUPABASE_SERVICE_ROLE_KEY", label: "Supabase Service Role Key", helpText: "Service Role Key aus den Supabase Projekt-Einstellungen > API." },
+    ],
+  },
+  {
+    id: "firebase",
+    name: "Firebase",
+    description: "Firebase-Projekte verwalten. Firestore, Auth, Hosting und Cloud Functions.",
+    category: "database",
+    type: "stdio",
+    command: "npx",
+    args: ["-y", "firebase-mcp-server"],
+    env: { GOOGLE_APPLICATION_CREDENTIALS: "" },
+    requiresAuth: [
+      { field: "GOOGLE_APPLICATION_CREDENTIALS", label: "Firebase Service Account JSON-Pfad", helpText: "Pfad zur Service-Account JSON-Datei aus der Firebase Console." },
+    ],
+  },
+  {
+    id: "exa",
+    name: "Exa",
+    description: "KI-optimierte Web-Suche. Semantische Suche und Content-Extraktion.",
+    category: "search",
+    type: "stdio",
+    command: "npx",
+    args: ["-y", "@anthropic/mcp-server-exa"],
+    env: { EXA_API_KEY: "" },
+    requiresAuth: [
+      { field: "EXA_API_KEY", label: "Exa API Key", helpText: "API-Key von exa.ai erstellen." },
+    ],
+  },
+  {
+    id: "sentry",
+    name: "Sentry",
+    description: "Fehler-Tracking und Performance-Monitoring. Issues und Events aus Sentry abfragen.",
+    category: "development",
+    type: "stdio",
+    command: "npx",
+    args: ["-y", "@sentry/mcp-server"],
+    env: { SENTRY_AUTH_TOKEN: "" },
+    requiresAuth: [
+      { field: "SENTRY_AUTH_TOKEN", label: "Sentry Auth Token", helpText: "Auth Token unter sentry.io/settings/auth-tokens erstellen." },
+    ],
+  },
+  {
+    id: "figma",
+    name: "Figma",
+    description: "Figma-Designs und Dateien lesen. Frames, Komponenten und Styles abfragen.",
+    category: "development",
+    type: "http",
+    url: "https://api.figma.com/mcp",
+    requiresAuth: [
+      { field: "FIGMA_ACCESS_TOKEN", label: "Figma Access Token", helpText: "Personal Access Token unter figma.com/developers/api erstellen." },
+    ],
+  },
+  {
+    id: "nanobanana",
+    name: "nanobanana",
+    description: "KI-Bildgenerierung. Erstellt Bilder aus Text-Beschreibungen via nanobanana.",
+    category: "ai",
+    type: "stdio",
+    command: "npx",
+    args: ["-y", "nanobanana-mcp"],
+  },
+];
+
+// ─── CRUD Operations ────────────────────────────────────────────────────────
+
+export function listServers(): McpServerEntry[] {
+  return loadServers();
+}
+
+export function getServer(id: string): McpServerEntry | undefined {
+  return loadServers().find((s) => s.id === id);
+}
+
+export function addServer(entry: Omit<McpServerEntry, "id">): McpServerEntry {
+  const servers = loadServers();
+  const server: McpServerEntry = {
+    ...entry,
+    id: uniqueId(entry.name, servers),
+  };
+  servers.push(server);
+  saveServers(servers);
+  return server;
+}
+
+export function addFromCatalog(catalogId: string): McpServerEntry {
+  const template = CATALOG.find((c) => c.id === catalogId);
+  if (!template) {
+    throw new Error(`Catalog entry "${catalogId}" not found`);
+  }
+
+  const servers = loadServers();
+
+  // Check if already installed
+  if (servers.some((s) => s.id === catalogId)) {
+    throw new Error(`MCP server "${template.name}" is already installed`);
+  }
+
+  const server: McpServerEntry = {
+    id: template.id,
+    name: template.name,
+    description: template.description,
+    type: template.type,
+    command: template.command,
+    args: template.args ? [...template.args] : undefined,
+    url: template.url,
+    headers: template.headers ? { ...template.headers } : undefined,
+    env: template.env ? { ...template.env } : undefined,
+    enabled: true,
+    assignedAgents: ["*"],
+    requiresAuth: template.requiresAuth,
+    authValues: {},
+  };
+
+  servers.push(server);
+  saveServers(servers);
+  return server;
+}
+
+export function updateServer(
+  id: string,
+  updates: Partial<McpServerEntry>,
+): McpServerEntry | null {
+  const servers = loadServers();
+  const idx = servers.findIndex((s) => s.id === id);
+  if (idx === -1) return null;
+
+  // Prevent changing ID
+  const { id: _ignoreId, ...safeUpdates } = updates;
+  servers[idx] = { ...servers[idx], ...safeUpdates };
+  saveServers(servers);
+  return servers[idx];
+}
+
+export function removeServer(id: string): boolean {
+  const servers = loadServers();
+  const idx = servers.findIndex((s) => s.id === id);
+  if (idx === -1) return false;
+  servers.splice(idx, 1);
+  saveServers(servers);
+  return true;
+}
+
+export function getCatalog(): CatalogEntry[] {
+  const installed = loadServers();
+  // Return catalog with an "installed" hint by checking existing servers
+  return CATALOG.map((c) => ({
+    ...c,
+    installed: installed.some((s) => s.id === c.id),
+  }));
+}
+
+export function getServersForAgent(agentId: string): McpServerEntry[] {
+  return loadServers().filter((s) => {
+    if (!s.enabled) return false;
+    if (s.assignedAgents.includes("*")) return true;
+    return s.assignedAgents.includes(agentId);
+  });
+}