@creativeintelligence/abbie 0.1.0

package/src/lib/panes/server.ts

@@ -0,0 +1,379 @@
+import { existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { createServer, type Server, type Socket } from "node:net";
+import { dirname } from "node:path";
+
+import { capturePaneScreen, ensurePipePane, getPaneMetrics } from "../tmux/panes.js";
+import * as windows from "../windows/index.js";
+import {
+  createNdjsonLineParser,
+  getDefaultPanesBrokerSocketPath,
+  type PanesBrokerPanesSnapshot,
+  type PanesBrokerPanesStatus,
+  type PanesBrokerServerHello,
+  type PanesBrokerServerMessage,
+} from "./broker.js";
+
+type BrokerClient = {
+  socket: Socket;
+  id: string;
+  kind: "ui" | "pipe";
+  paneId?: string;
+};
+
+type Subscription = {
+  requestId: string;
+  clientId: string;
+  paneId: string;
+  encoding: "text" | "ansi";
+  redaction: "raw" | "default";
+  follow: boolean;
+  active: boolean;
+};
+
+type PaneState = {
+  paneId: string;
+  dirty: boolean;
+  lastEmitAt: number;
+  subs: Set<string>; // requestIds
+  pipeClientId?: string;
+  controllerClientId?: string;
+};
+
+type BrokerOptions = {
+  socketPath?: string;
+  fps?: number;
+  forcePipe?: boolean;
+};
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+function ensureDirForSocket(socketPath: string): void {
+  mkdirSync(dirname(socketPath), { recursive: true });
+}
+
+function safeUnlinkSocket(socketPath: string): void {
+  try {
+    if (existsSync(socketPath)) unlinkSync(socketPath);
+  } catch {
+    // ignore
+  }
+}
+
+function send(socket: Socket, msg: unknown): void {
+  socket.write(`${JSON.stringify(msg)}\n`);
+}
+
+function getRefFromTarget(target: unknown): string | null {
+  if (typeof target !== "object" || target === null) return null;
+  const record = target as Record<string, unknown>;
+  return typeof record.ref === "string" ? record.ref : null;
+}
+
+function parseTargetToPaneId(target: unknown): { paneId?: string; error?: string } {
+  if (typeof target !== "object" || target === null) return { error: "Invalid target" };
+  const maybe = target as Record<string, unknown>;
+
+  const paneId = typeof maybe.paneId === "string" ? maybe.paneId : undefined;
+  const ref = typeof maybe.ref === "string" ? maybe.ref : undefined;
+
+  if (paneId) return { paneId };
+  if (!ref) return { error: "Missing target.paneId or target.ref" };
+  if (ref.startsWith("%")) return { paneId: ref };
+  return { paneId: undefined, error: "Ref must be a pane id (e.g. %3) or resolved via windows" };
+}
+
+export async function startPanesBroker(
+  opts: BrokerOptions,
+  ctx: {
+    agentsBinPath: string;
+    logInfo: (msg: string) => void;
+    logWarn: (msg: string) => void;
+  },
+): Promise<{ socketPath: string; server: Server; stop: () => Promise<void> }> {
+  const socketPath = opts.socketPath ?? getDefaultPanesBrokerSocketPath();
+  ensureDirForSocket(socketPath);
+  safeUnlinkSocket(socketPath);
+
+  const clients = new Map<string, BrokerClient>();
+  const subs = new Map<string, Subscription>();
+  const panes = new Map<string, PaneState>();
+
+  const fps = Math.max(1, Math.min(60, opts.fps ?? 30));
+  const frameMs = Math.floor(1000 / fps);
+
+  const server = createServer((socket) => {
+    const clientId = `c_${Math.random().toString(16).slice(2)}`;
+    const client: BrokerClient = { socket, id: clientId, kind: "ui" };
+    clients.set(clientId, client);
+
+    const hello: PanesBrokerServerHello = {
+      type: "broker.hello",
+      at: nowIso(),
+      version: 1,
+      pid: process.pid,
+    };
+    send(socket, hello);
+
+    const parser = createNdjsonLineParser<Record<string, unknown>>();
+    socket.on("data", (chunk) => parser.pushChunk(chunk));
+    socket.on("close", () => {
+      // Drop subscriptions
+      for (const [requestId, sub] of subs) {
+        if (sub.clientId !== clientId) continue;
+        subs.delete(requestId);
+        const pane = panes.get(sub.paneId);
+        pane?.subs.delete(requestId);
+      }
+      // If pipe client, detach
+      if (client.kind === "pipe" && client.paneId) {
+        const pane = panes.get(client.paneId);
+        if (pane?.pipeClientId === clientId) pane.pipeClientId = undefined;
+        if (pane?.controllerClientId === clientId) pane.controllerClientId = undefined;
+      }
+      clients.delete(clientId);
+    });
+
+    parser.onMessage(async (msg) => {
+      const type = typeof msg.type === "string" ? msg.type : "";
+
+      if (type === "client.ping") {
+        const nonce = typeof msg.nonce === "string" ? msg.nonce : "";
+        send(socket, { type: "broker.pong", at: nowIso(), nonce });
+        return;
+      }
+
+      if (type === "client.hello") {
+        return;
+      }
+
+      if (type === "panes.pipe.hello") {
+        const paneId = typeof msg.paneId === "string" ? msg.paneId : undefined;
+        if (!paneId) return;
+        client.kind = "pipe";
+        client.paneId = paneId;
+        const pane = panes.get(paneId) ?? { paneId, dirty: true, lastEmitAt: 0, subs: new Set() };
+        pane.pipeClientId = clientId;
+        panes.set(paneId, pane);
+        return;
+      }
+
+      if (type === "panes.pipe.chunk") {
+        const paneId = typeof msg.paneId === "string" ? msg.paneId : undefined;
+        if (!paneId) return;
+        const pane = panes.get(paneId) ?? { paneId, dirty: true, lastEmitAt: 0, subs: new Set() };
+        pane.dirty = true;
+        panes.set(paneId, pane);
+        return;
+      }
+
+      if (type === "panes.subscribe") {
+        const requestId = typeof msg.requestId === "string" ? msg.requestId : undefined;
+        const target = msg.target;
+        if (!requestId) return;
+
+        // Resolve paneId
+        let paneId: string | undefined;
+        const parsed = parseTargetToPaneId(target);
+        paneId = parsed.paneId;
+
+        // If we got a non-pane-id ref (session:window.pane), resolve via windows inventory.
+        const ref = getRefFromTarget(target);
+        if (!paneId && ref) {
+          const state = await windows.getWindowState(ref, {
+            includeNvim: false,
+            includeAgent: false,
+            includeBuffers: false,
+          });
+          paneId = state?.window.paneId ?? undefined;
+        }
+
+        if (!paneId) {
+          const status: PanesBrokerPanesStatus = {
+            type: "panes.status",
+            at: nowIso(),
+            requestId,
+            level: "error",
+            message: parsed.error ?? "Failed to resolve paneId",
+          };
+          send(socket, status);
+          return;
+        }
+
+        const encoding = msg.encoding === "ansi" ? "ansi" : "text";
+        const redaction = msg.redaction === "default" ? "default" : "raw";
+        const follow = msg.follow !== false;
+
+        subs.set(requestId, {
+          requestId,
+          clientId,
+          paneId,
+          encoding,
+          redaction,
+          follow,
+          active: true,
+        });
+
+        const pane = panes.get(paneId) ?? { paneId, dirty: true, lastEmitAt: 0, subs: new Set() };
+        pane.subs.add(requestId);
+        panes.set(paneId, pane);
+
+        // Ensure pipe-pane is attached (best-effort). The pipe-sink provides
+        // event-driven invalidation + raw input injection (bidirectional pipe).
+        const sinkCommand = `${ctx.agentsBinPath} panes pipe-sink --pane ${paneId} --sock ${socketPath}`;
+        const attached = await ensurePipePane(paneId, sinkCommand, {
+          onlyIfUnset: !opts.forcePipe,
+          bidirectional: true,
+        });
+        if (!attached.attached) {
+          ctx.logWarn(`pipe-pane attach failed for ${paneId}: ${attached.error ?? "unknown"}`);
+        }
+
+        // Send an initial snapshot immediately.
+        pane.dirty = true;
+        await emitSnapshotForPane(paneId);
+
+        return;
+      }
+
+      if (type === "panes.unsubscribe") {
+        const requestId = typeof msg.requestId === "string" ? msg.requestId : undefined;
+        if (!requestId) return;
+        const sub = subs.get(requestId);
+        if (!sub) return;
+        subs.delete(requestId);
+        panes.get(sub.paneId)?.subs.delete(requestId);
+        return;
+      }
+
+      if (type === "panes.control.claim") {
+        const paneId = typeof msg.paneId === "string" ? msg.paneId : undefined;
+        if (!paneId) return;
+        const pane = panes.get(paneId) ?? { paneId, dirty: false, lastEmitAt: 0, subs: new Set() };
+        panes.set(paneId, pane);
+
+        if (pane.controllerClientId && pane.controllerClientId !== clientId) {
+          send(socket, {
+            type: "panes.status",
+            at: nowIso(),
+            paneId,
+            level: "warn",
+            message: "Control already claimed by another client",
+          });
+          return;
+        }
+
+        pane.controllerClientId = clientId;
+        send(socket, { type: "panes.status", at: nowIso(), paneId, level: "info", message: "ok" });
+        return;
+      }
+
+      if (type === "panes.control.release") {
+        const paneId = typeof msg.paneId === "string" ? msg.paneId : undefined;
+        if (!paneId) return;
+        const pane = panes.get(paneId);
+        if (pane?.controllerClientId === clientId) pane.controllerClientId = undefined;
+        return;
+      }
+
+      if (type === "panes.input") {
+        const paneId = typeof msg.paneId === "string" ? msg.paneId : undefined;
+        const data = typeof msg.data === "string" ? msg.data : undefined;
+        if (!paneId || !data) return;
+
+        const pane = panes.get(paneId);
+        if (pane?.controllerClientId && pane.controllerClientId !== clientId) return;
+        if (!pane?.pipeClientId) return;
+
+        const pipeClient = clients.get(pane.pipeClientId);
+        if (!pipeClient) return;
+
+        send(pipeClient.socket, { type: "panes.pipe.input", at: nowIso(), paneId, data });
+        return;
+      }
+    });
+
+    parser.onError(() => {
+      // ignore parse errors
+    });
+  });
+
+  const emitSnapshotForPane = async (paneId: string): Promise<void> => {
+    const pane = panes.get(paneId);
+    if (!pane) return;
+    if (pane.subs.size === 0) return;
+
+    const metrics = await getPaneMetrics(paneId);
+    const rows = metrics?.rows ?? 24;
+    const cols = metrics?.cols ?? 80;
+
+    // Use the first subscription's encoding as the capture mode; if there are
+    // mixed encodings, we will send snapshots per-sub below.
+    const byRequest: Subscription[] = [];
+    for (const requestId of pane.subs) {
+      const sub = subs.get(requestId);
+      if (sub?.active) byRequest.push(sub);
+    }
+    if (byRequest.length === 0) return;
+
+    const captureAnsi = byRequest.some((s) => s.encoding === "ansi");
+    const screen = await capturePaneScreen(paneId, {
+      ansi: captureAnsi,
+      rows,
+      cursor: metrics
+        ? { x: metrics.cursorX, y: metrics.cursorY, visible: metrics.cursorFlag !== 0 }
+        : undefined,
+    });
+    // biome-ignore lint/complexity/useRegexLiterals: Regex literal with \u001b triggers Biome control-char lint.
+    const sgrRegex = new RegExp("\\u001b\\[[0-9;]*m", "g");
+
+    for (const sub of byRequest) {
+      const client = clients.get(sub.clientId);
+      if (!client) continue;
+
+      const content = sub.encoding === "ansi" ? screen : screen.replace(sgrRegex, "");
+      const snapshot: PanesBrokerPanesSnapshot = {
+        type: "panes.snapshot",
+        at: nowIso(),
+        requestId: sub.requestId,
+        paneId,
+        encoding: sub.encoding,
+        redaction: sub.redaction,
+        cols,
+        rows,
+        content,
+      };
+      send(client.socket, snapshot satisfies PanesBrokerServerMessage);
+    }
+  };
+
+  const interval = setInterval(
+    async () => {
+      const now = Date.now();
+      for (const pane of panes.values()) {
+        if (!pane.dirty) continue;
+        if (now - pane.lastEmitAt < frameMs) continue;
+        pane.dirty = false;
+        pane.lastEmitAt = now;
+        await emitSnapshotForPane(pane.paneId);
+      }
+    },
+    Math.max(10, Math.floor(frameMs / 2)),
+  );
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(socketPath, () => resolve());
+  });
+
+  ctx.logInfo(`panes broker listening: ${socketPath} (${fps}fps)`);
+
+  const stop = async () => {
+    clearInterval(interval);
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    safeUnlinkSocket(socketPath);
+  };
+
+  return { socketPath, server, stop };
+}

package/src/lib/preview/detect.ts

@@ -0,0 +1,184 @@
+/**
+ * Auto-detect project type and generate optimal dev command for sprites
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface ProjectInfo {
+  type: "monorepo" | "single";
+  packageManager: "pnpm" | "bun" | "npm";
+  hasTurbo: boolean;
+  appDir?: string; // e.g., 'apps/app' for monorepos
+  devCommand: string; // Full command to run dev server
+  port: number;
+}
+
+/**
+ * Detect project type and return optimal configuration
+ */
+export function detectProject(projectPath: string): ProjectInfo {
+  const hasPnpmWorkspace = existsSync(join(projectPath, "pnpm-workspace.yaml"));
+  const hasTurbo = existsSync(join(projectPath, "turbo.json"));
+  const hasBunLock =
+    existsSync(join(projectPath, "bun.lock")) || existsSync(join(projectPath, "bun.lockb"));
+  const hasPnpmLock = existsSync(join(projectPath, "pnpm-lock.yaml"));
+  const hasAppsDir = existsSync(join(projectPath, "apps"));
+
+  // Determine package manager
+  let packageManager: "pnpm" | "bun" | "npm" = "npm";
+  if (hasPnpmWorkspace || hasPnpmLock) {
+    packageManager = "pnpm";
+  } else if (hasBunLock) {
+    packageManager = "bun";
+  }
+
+  // Detect monorepo with apps directory
+  if (hasAppsDir && (hasPnpmWorkspace || hasTurbo)) {
+    const appDir = findMainApp(join(projectPath, "apps"));
+    if (appDir) {
+      const devCommand = buildMonorepoDevCommand(projectPath, appDir, packageManager);
+      return {
+        type: "monorepo",
+        packageManager,
+        hasTurbo,
+        appDir: `apps/${appDir}`,
+        devCommand,
+        port: 8080,
+      };
+    }
+  }
+
+  // Single package project
+  const devCommand = buildSingleDevCommand(projectPath, packageManager);
+  return {
+    type: "single",
+    packageManager,
+    hasTurbo,
+    devCommand,
+    port: 8080,
+  };
+}
+
+/**
+ * Find the main app directory in a monorepo
+ * Priority: app > web > admin > first directory
+ */
+function findMainApp(appsPath: string): string | undefined {
+  if (!existsSync(appsPath)) return undefined;
+
+  const entries = readdirSync(appsPath, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name);
+
+  // Priority order
+  const priority = ["app", "web", "admin"];
+  for (const name of priority) {
+    if (entries.includes(name)) {
+      // Verify it has a package.json (is a real app)
+      if (existsSync(join(appsPath, name, "package.json"))) {
+        return name;
+      }
+    }
+  }
+
+  // Fall back to first directory with package.json
+  for (const name of entries) {
+    if (existsSync(join(appsPath, name, "package.json"))) {
+      return name;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Build dev command for monorepo
+ */
+function buildMonorepoDevCommand(
+  projectPath: string,
+  appDir: string,
+  packageManager: "pnpm" | "bun" | "npm",
+): string {
+  const appPath = join(projectPath, "apps", appDir);
+  const appPkg = readPackageJson(appPath) as Record<string, Record<string, unknown>> | undefined;
+
+  // Check if app uses Next.js
+  const deps = appPkg?.dependencies as Record<string, string> | undefined;
+  const devDeps = appPkg?.devDependencies as Record<string, string> | undefined;
+  const scripts = appPkg?.scripts as Record<string, string> | undefined;
+
+  const hasNext = deps?.next || devDeps?.next;
+  const devScript = scripts?.dev || "";
+
+  if (hasNext) {
+    // For Next.js, run directly in the app directory with proper port binding
+    // This is more reliable than turbo for sprite previews
+    const usesTurbopack = devScript.includes("--turbopack") || devScript.includes("turbo");
+    const turboFlag = usesTurbopack ? " --turbopack" : "";
+    return `cd apps/${appDir} && npx next dev${turboFlag} -p 8080 -H 0.0.0.0`;
+  }
+
+  // For other frameworks, use the package manager's workspace command
+  if (packageManager === "pnpm") {
+    return `pnpm --filter ./apps/${appDir} dev -- -p 8080 -H 0.0.0.0`;
+  }
+
+  return `cd apps/${appDir} && ${packageManager} run dev -p 8080 -H 0.0.0.0`;
+}
+
+/**
+ * Build dev command for single package project
+ */
+function buildSingleDevCommand(
+  projectPath: string,
+  packageManager: "pnpm" | "bun" | "npm",
+): string {
+  const pkg = readPackageJson(projectPath) as Record<string, Record<string, unknown>> | undefined;
+
+  const deps = pkg?.dependencies as Record<string, string> | undefined;
+  const devDeps = pkg?.devDependencies as Record<string, string> | undefined;
+  const scripts = pkg?.scripts as Record<string, string> | undefined;
+
+  const hasNext = deps?.next || devDeps?.next;
+  const devScript = scripts?.dev || "";
+
+  if (hasNext) {
+    const usesTurbopack = devScript.includes("--turbopack") || devScript.includes("turbo");
+    const turboFlag = usesTurbopack ? " --turbopack" : "";
+    return `npx next dev${turboFlag} -p 8080 -H 0.0.0.0`;
+  }
+
+  // Generic dev command
+  return `${packageManager} run dev -p 8080 -H 0.0.0.0`;
+}
+
+/**
+ * Read package.json safely
+ */
+function readPackageJson(dir: string): Record<string, unknown> | undefined {
+  const pkgPath = join(dir, "package.json");
+  if (!existsSync(pkgPath)) return undefined;
+
+  try {
+    return JSON.parse(readFileSync(pkgPath, "utf-8"));
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Get install command for package manager
+ * Note: On sprites, pnpm isn't in PATH by default. Use npx to run it.
+ */
+export function getInstallCommand(packageManager: "pnpm" | "bun" | "npm"): string {
+  switch (packageManager) {
+    case "pnpm":
+      // Use npx pnpm which automatically installs if needed
+      return "npx pnpm install";
+    case "bun":
+      return "bun install";
+    case "npm":
+      return "npm install";
+  }
+}

package/src/lib/preview/index.ts

@@ -0,0 +1 @@
+export * from "./detect.js";

package/src/lib/process/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Process snapshot utilities.
+ * Provides parent chain walking and descendant search for process correlation.
+ */
+
+export {
+  buildProcessTree,
+  detectAgentType,
+  findDeepestDescendant,
+  findDescendants,
+  getProcessSnapshot,
+  isAgentProcess,
+  isNvimProcess,
+  type ProcessInfo,
+  walkParentChain,
+} from "./snapshot.js";