@dassi_ai/cli 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "dassi",
+  "description": "Drive the Dassi Chrome extension from Claude Code. Pick tabs/groups, then run AI agent or browser tools against them.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Omnify Labs",
+    "email": "team@dassi.ai"
+  },
+  "homepage": "https://dassi.ai",
+  "license": "MIT",
+  "keywords": ["browser", "automation", "chrome-extension", "agent"]
+}

package/README.md

@@ -0,0 +1,106 @@
+# dassi-cli
+
+Standalone CLI for the [Dassi](../extension/README.md) Chrome extension — run browser automation from the terminal.
+
+## Installation
+
+```bash
+# Zero-install
+npx dassi-cli --help
+
+# Or install globally
+npm install -g dassi-cli
+```
+
+Or, for local development from a clone of this repo:
+
+```bash
+cd cli
+npm install
+npm link    # exposes `dassi` on PATH
+```
+
+## Prerequisites
+
+- Node.js >= 20.11.1
+- Dassi Chrome extension installed and running
+- **External Bridge** enabled in Dassi Options (`options.html?dev`)
+
+## Usage
+
+```bash
+# List all open Chrome tabs
+dassi list-tabs
+
+# Run an agent prompt on a specific tab
+dassi run "summarize the top issues" --tab 456
+
+# Run with a timeout (ms)
+dassi run "check inbox" --tab 123 --timeout 60000
+
+# Send a raw JSON command
+dassi raw '{"id":"1","action":"list_tabs"}'
+
+# Output as JSON (for scripting)
+dassi list-tabs --json
+
+# Use a named session
+dassi list-tabs --session work
+
+# Show version / help
+dassi --version
+dassi --help
+```
+
+### Tab groups
+
+```bash
+# List all tab groups
+dassi list-groups
+
+# Run agent against every tab in a group (sequential)
+dassi run "summarize each page" --group 7
+
+# Use a group title instead of id (errors if title is ambiguous)
+dassi run "extract prices" --group-title "Shopping"
+
+# Tool commands also accept --group / --group-title
+dassi screenshot --group-title "Research" -o shot.png
+```
+
+When `--group`/`--group-title` is used, the CLI expands to member tab ids and runs them sequentially in one daemon session. True parallel execution is not currently supported — the daemon binds a fixed WebSocket port (`18790` by default, override with `DASSI_BRIDGE_PORT`), so multiple daemon processes can't coexist regardless of `--session`. Sequential dispatch is the only supported pattern.
+
+## Claude Code Plugin
+
+This package also ships as a Claude Code plugin under the `dassi` namespace. After installation (via either `npm install -g dassi-cli` or `npm link` from this directory), Claude Code auto-discovers two skills:
+
+- **`dassi:pick-tabs`** — a reusable tab/group picker. Lists open tabs and Chrome tab groups, asks the user to pick, returns the selected Chrome tab IDs.
+- **`dassi:operate`** — main entry point. Translates natural-language browser asks ("summarize my Research group", "screenshot the active tab", etc.) into `dassi` CLI invocations.
+
+The plugin manifest lives at `.claude-plugin/plugin.json`; skill content is under `skills/<name>/SKILL.md`. No additional configuration is required — installing the CLI is sufficient.
+
+## How It Works
+
+The CLI (`dassi.mjs`) auto-spawns a background daemon (`dassi-daemon.mjs`) that:
+
+- Hosts a WebSocket server on port 18790 for the Chrome extension to connect to
+- Exposes a Unix socket (`~/.dassi/<session>.sock`) for CLI commands via NDJSON protocol
+- Serializes concurrent `run` commands via a FIFO queue
+- Handles first-run onboarding (extension install detection, login flow)
+- Shuts down after 30 minutes of idle
+
+## Dependencies
+
+- [`ws`](https://www.npmjs.com/package/ws) — WebSocket server for extension communication
+- [`open`](https://www.npmjs.com/package/open) — Opens browser for onboarding/install flow
+
+## Development
+
+```bash
+# Run tests
+npm test
+```
+
+## License
+
+MIT

package/dassi-daemon.mjs

@@ -0,0 +1,374 @@
+#!/usr/bin/env node
+/**
+ * Dassi CLI Daemon
+ *
+ * Persistent process that hosts a WebSocket server on port 18790 (override
+ * with DASSI_BRIDGE_PORT — the benchmark harness uses 18791 to isolate
+ * from a developer's real Chrome on the default port), waits for the Dassi
+ * Chrome extension to connect, and exposes a Unix socket for thin CLI
+ * clients to send NDJSON commands.
+ *
+ * Protocol is compatible with agent-browser: {id, action, ...} → {id, success, data/error}.
+ * Socket path: ~/.dassi/<session>.sock  (env: DASSI_SESSION, default: "default")
+ */
+
+import * as net from 'net';
+import * as fs from 'fs';
+import { pathToFileURL } from 'url';
+import {
+  getAppDir,
+  getSocketPath,
+  getReadyFile,
+  getPidFile,
+  validateSession,
+  cleanupDaemonFiles,
+  buildReadyPayload,
+  createCommandQueue,
+} from './dassi-shared.mjs';
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const IDLE_TIMEOUT_MS = 30 * 60 * 1000;
+const IDLE_CHECK_INTERVAL_MS = 5 * 60 * 1000;
+
+// ─── Module-level extension connection state ──────────────────────────────────
+
+/** Active WebSocket connection to the registered Dassi extension. */
+let extensionSocket = null;
+/** Pending response callbacks keyed by request ID. */
+const pendingExtResponses = new Map();
+
+// ─── WebSocket loader helper ──────────────────────────────────────────────────
+
+/**
+ * Dynamically loads the `ws` package and returns both the WebSocket client
+ * class and the WebSocketServer class.
+ * @returns {Promise<{ WS: typeof import('ws').WebSocket; WSServer: typeof import('ws').WebSocketServer }>}
+ */
+async function loadWebSocket() {
+  try {
+    const mod = await import('ws');
+    // Reason: ws may export default or named WebSocket depending on build
+    return { WS: mod.WebSocket ?? mod.default, WSServer: mod.WebSocketServer };
+  } catch {
+    // Fallback for environments where dynamic import of CJS doesn't work
+    const { createRequire } = await import('module');
+    const require = createRequire(import.meta.url);
+    const mod = require('ws');
+    return { WS: mod.WebSocket ?? mod.default, WSServer: mod.WebSocketServer };
+  }
+}
+
+// ─── Extension response routing ──────────────────────────────────────────────
+
+/**
+ * Sets up the persistent message handler on the extension WebSocket that routes
+ * responses back to callers waiting in pendingExtResponses.
+ * @param {import('ws').WebSocket} ws
+ */
+function setupResponseRouter(ws) {
+  ws.on('message', (responseData) => {
+    let resp;
+    try { resp = JSON.parse(responseData.toString()); } catch { return; }
+    const pending = pendingExtResponses.get(String(resp.id));
+    if (!pending) return;
+    pendingExtResponses.delete(String(resp.id));
+    if (resp.error) {
+      pending.reject(new Error(resp.error.message ?? String(resp.error)));
+    } else {
+      pending.resolve(resp.result);
+    }
+  });
+}
+
+/**
+ * Reject all pending extension responses with a disconnection error.
+ * Called when the extension WebSocket closes so callers don't hang forever.
+ */
+function drainPendingResponses() {
+  for (const [id, pending] of pendingExtResponses) {
+    pending.reject(new Error('Extension disconnected'));
+    pendingExtResponses.delete(id);
+  }
+}
+
+// ─── Extension server ─────────────────────────────────────────────────────────
+
+/**
+ * Accepts a newly registered extension WebSocket: replaces any existing socket,
+ * drains pending responses from the old connection, and wires up the new one.
+ * @param {import('ws').WebSocket} ws - The new WebSocket connection.
+ */
+function acceptExtensionSocket(ws) {
+  // Reason: if an old socket exists, close it cleanly before replacing
+  if (extensionSocket && extensionSocket !== ws) {
+    try { extensionSocket.close(); } catch { /* already closed */ }
+  }
+  drainPendingResponses();
+  extensionSocket = ws;
+  ws.on('close', () => {
+    if (extensionSocket === ws) {
+      extensionSocket = null;
+      drainPendingResponses();
+      console.log('[dassi-daemon] Extension disconnected, waiting for reconnect…');
+    }
+  });
+  setupResponseRouter(ws);
+}
+
+/**
+ * Handles a registration message from a newly connected extension WebSocket.
+ * On first registration, resolves the startup promise with auth status.
+ * On subsequent registrations (reconnects), logs and continues silently.
+ * @param {import('ws').WebSocket} ws - The connected WebSocket.
+ * @param {Buffer} data - Raw message data.
+ * @param {{ resolved: boolean; timeout: ReturnType<typeof setTimeout> }} ctx - Shared state.
+ * @param {import('ws').WebSocketServer} wss - The server (closed on fatal error).
+ * @param {(value: unknown) => void} resolve - Promise resolve callback.
+ * @param {(reason: Error) => void} reject - Promise reject callback.
+ */
+async function handleRegistration(ws, data, ctx, wss, resolve, reject) {
+  let msg;
+  try { msg = JSON.parse(data.toString()); } catch { return; }
+  if (msg.type !== 'register' || msg.client !== 'dassi-extension') return;
+
+  // Reason: only accept a new registration when the current socket is dead.
+  // This prevents a rogue local process from hijacking the extension socket
+  // while a healthy connection exists.
+  if (extensionSocket && extensionSocket.readyState === 1 /* OPEN */) {
+    console.log('[dassi-daemon] Rejected registration — existing socket still healthy');
+    ws.close();
+    return;
+  }
+
+  acceptExtensionSocket(ws);
+
+  if (!ctx.resolved) {
+    clearTimeout(ctx.timeout);
+    try {
+      const status = await dispatchToExtension({ id: 'init', action: 'status' });
+      ctx.resolved = true;
+      resolve(status);
+    } catch (err) {
+      // Reason: don't close WSS — extension may reconnect and retry
+      console.error('[dassi-daemon] Initial status check failed:', err.message);
+      reject(err);
+    }
+  } else {
+    console.log('[dassi-daemon] Extension reconnected');
+  }
+}
+
+// Reason: Port is configurable via DASSI_BRIDGE_PORT so the benchmark harness
+// can run a daemon that doesn't conflict with the developer's real Chrome
+// daemon. Defaults to 18790 — the production port that the prod extension
+// SW connects to.
+// Validate so an empty/garbage env var (DASSI_BRIDGE_PORT="") doesn't yield NaN,
+// which `new WSServer({ port: NaN })` would silently accept and bind to a random
+// ephemeral port — leaving the extension's known-port connect attempt hanging.
+const _rawPort = parseInt(process.env.DASSI_BRIDGE_PORT ?? '', 10);
+const BRIDGE_PORT = Number.isInteger(_rawPort) && _rawPort > 0 && _rawPort <= 65535
+  ? _rawPort
+  : 18790;
+
+/**
+ * Starts a WebSocket server on the configured bridge port (default 18790).
+ * Stays alive for the daemon's lifetime. Waits for the first extension
+ * connection, then resolves with the auth status. Subsequent reconnections
+ * are handled transparently.
+ * @returns {Promise<{ authenticated: boolean; email: string | null; optionsUrl: string }>}
+ */
+async function startExtensionServer() {
+  const { WSServer } = await loadWebSocket();
+
+  return new Promise((resolve, reject) => {
+    const wss = new WSServer({ host: '127.0.0.1', port: BRIDGE_PORT });
+    const ctx = { resolved: false, timeout: null };
+
+    ctx.timeout = setTimeout(() => {
+      wss.close();
+      reject(new Error('extension_not_installed'));
+    }, 30_000);
+
+    wss.on('error', (err) => {
+      if (!ctx.resolved) {
+        clearTimeout(ctx.timeout);
+        // Reason: EADDRINUSE means another daemon instance already owns the port
+        reject(err.code === 'EADDRINUSE' ? new Error('port_in_use') : new Error('extension_not_installed'));
+      }
+    });
+
+    wss.on('connection', (ws) => {
+      ws.once('message', (data) => handleRegistration(ws, data, ctx, wss, resolve, reject));
+    });
+  });
+}
+
+// ─── Internal extension dispatcher ───────────────────────────────────────────
+
+/**
+ * Dispatches a single command to the Dassi extension via the persistent WS
+ * connection, translating from the daemon's internal format to the extension's
+ * JSON-RPC-style protocol.
+ * @param {Record<string, unknown>} cmd - Command object with {id, action, ...params}
+ * @returns {Promise<unknown>} The extension's result value (not wrapped in success/data).
+ */
+async function dispatchToExtension(cmd) {
+  if (!extensionSocket || extensionSocket.readyState !== 1 /* OPEN */) {
+    throw new Error('Extension not connected');
+  }
+
+  const { id, action, ...params } = cmd;
+  // Reason: the extension expects JSON-RPC style {id, method, params}, not {id, action, ...}
+  const message = { id, method: action ?? String(id), params };
+  extensionSocket.send(JSON.stringify(message));
+
+  const timeoutMs = typeof params.timeoutMs === 'number' ? params.timeoutMs + 10_000 : 65_000;
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      pendingExtResponses.delete(String(id));
+      reject(new Error(`Extension timeout after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    pendingExtResponses.set(String(id), {
+      resolve: (result) => { clearTimeout(timer); resolve(result); },
+      reject: (err) => { clearTimeout(timer); reject(err); },
+    });
+  });
+}
+
+// ─── Daemon setup helpers ─────────────────────────────────────────────────────
+
+/**
+ * Initializes daemon process: creates app dir, writes PID, registers shutdown handlers.
+ * @param {string} session - Validated session name.
+ * @returns {{ socketPath: string; readyFile: string }}
+ */
+function initDaemonProcess(session) {
+  const appDir = getAppDir();
+  const socketPath = getSocketPath(session);
+  const readyFile = getReadyFile(session);
+
+  fs.mkdirSync(appDir, { recursive: true, mode: 0o700 });
+  cleanupDaemonFiles(session);
+  fs.writeFileSync(getPidFile(session), String(process.pid));
+
+  const shutdown = () => {
+    cleanupDaemonFiles(session);
+    process.exit(0);
+  };
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+
+  return { socketPath, readyFile };
+}
+
+/**
+ * Creates and starts a Unix socket server that dispatches NDJSON commands to the queue.
+ * @param {{ enqueue: (cmd: Record<string, unknown>) => Promise<unknown> }} queue
+ * @param {string} socketPath
+ * @returns {net.Server}
+ */
+function createSocketServer(queue, socketPath) {
+  const server = net.createServer((socket) => {
+    let buffer = '';
+
+    socket.on('data', (chunk) => {
+      buffer += chunk.toString();
+      const lines = buffer.split('\n');
+      // Reason: keep the incomplete last line in the buffer for the next data event
+      buffer = lines.pop() ?? '';
+
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        let cmd;
+        try {
+          cmd = JSON.parse(line);
+        } catch {
+          socket.write(JSON.stringify({ id: 'unknown', success: false, error: 'Invalid JSON' }) + '\n');
+          continue;
+        }
+
+        queue.enqueue(cmd)
+          .then((response) => {
+            if (!socket.destroyed) socket.write(JSON.stringify(response) + '\n');
+          })
+          .catch((err) => console.error('[dassi-daemon] enqueue error:', err));
+      }
+    });
+
+    socket.on('error', () => { /* ignore client disconnects */ });
+  });
+
+  server.listen(socketPath);
+  return server;
+}
+
+/**
+ * Sets up an idle timer that shuts down the daemon after IDLE_TIMEOUT_MS of inactivity.
+ * @param {net.Server} server
+ * @param {string} session
+ * @param {() => number} getLastCommandAt - Returns timestamp of last command.
+ */
+function startIdleShutdown(server, session, getLastCommandAt) {
+  // Reason: unref() prevents the timer from keeping the process alive if the
+  // server is closed; the server itself keeps the process alive while running
+  setInterval(() => {
+    if (Date.now() - getLastCommandAt() > IDLE_TIMEOUT_MS) {
+      server.close();
+      cleanupDaemonFiles(session);
+      process.exit(0);
+    }
+  }, IDLE_CHECK_INTERVAL_MS).unref();
+}
+
+// ─── Daemon entry point ───────────────────────────────────────────────────────
+
+/**
+ * Main daemon entry point. Starts the extension WebSocket server, waits for
+ * the extension to register, runs onboarding checks, starts the Unix socket
+ * server for CLI commands, and sets up idle shutdown.
+ * @returns {Promise<void>}
+ */
+export async function startDaemon() {
+  const session = validateSession(process.env.DASSI_SESSION ?? 'default');
+  const { socketPath, readyFile } = initDaemonProcess(session);
+
+  let statusData;
+  try {
+    statusData = await startExtensionServer();
+  } catch {
+    // Reason: write the ready file even on failure so the CLI can read the error state,
+    // then exit so the WSS doesn't keep the process alive as a zombie.
+    fs.writeFileSync(readyFile, JSON.stringify({ status: 'extension_not_installed' }));
+    process.exit(1);
+  }
+
+  let lastCommandAt = Date.now();
+  const queue = createCommandQueue(async (cmd) => {
+    lastCommandAt = Date.now();
+    try {
+      const result = await dispatchToExtension(cmd);
+      return { id: String(cmd.id ?? 'unknown'), success: true, data: result };
+    } catch (err) {
+      return { id: String(cmd.id ?? 'unknown'), success: false, error: err.message };
+    }
+  });
+
+  // Reason: start the socket server before writing the ready file so the CLI
+  // can connect immediately (e.g. for needs_login polling).
+  const server = createSocketServer(queue, socketPath);
+  fs.writeFileSync(readyFile, JSON.stringify(buildReadyPayload(statusData)));
+
+  startIdleShutdown(server, session, () => lastCommandAt);
+}
+
+// ── Entry point ───────────────────────────────────────────────────────────────
+// Reason: guard allows this file to be imported by tests without starting the daemon
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  startDaemon().catch((err) => {
+    console.error('[dassi-daemon] fatal:', err.message);
+    process.exit(1);
+  });
+}

package/dassi-shared.mjs

@@ -0,0 +1,182 @@
+/**
+ * Dassi CLI Shared Utilities
+ *
+ * Pure helper functions shared between the CLI client (dassi.mjs) and the
+ * daemon process (dassi-daemon.mjs). Includes path resolution, session
+ * validation, daemon lifecycle helpers, ready-file payload handling, and
+ * the serialized command queue.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+// ─── Path helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Returns the base directory for dassi socket/pid/ready files.
+ * Priority: XDG_RUNTIME_DIR > ~/.dassi
+ * @returns {string}
+ */
+export function getAppDir() {
+  if (process.env.XDG_RUNTIME_DIR) {
+    return path.join(process.env.XDG_RUNTIME_DIR, 'dassi');
+  }
+  return path.join(os.homedir(), '.dassi');
+}
+
+/**
+ * Returns the Unix socket path for the given session.
+ * @param {string} session
+ * @returns {string}
+ */
+export function getSocketPath(session) {
+  return path.join(getAppDir(), `${session}.sock`);
+}
+
+/**
+ * Returns the PID file path for the given session.
+ * @param {string} session
+ * @returns {string}
+ */
+export function getPidFile(session) {
+  return path.join(getAppDir(), `${session}.pid`);
+}
+
+/**
+ * Returns the ready file path for the given session.
+ * Written by the daemon once the extension WS is connected and auth is verified.
+ * @param {string} session
+ * @returns {string}
+ */
+export function getReadyFile(session) {
+  return path.join(getAppDir(), `${session}.ready`);
+}
+
+// ─── Session validation ───────────────────────────────────────────────────────
+
+/**
+ * Validates a session name to prevent path traversal.
+ * Only allows alphanumeric characters, hyphens, and underscores.
+ * @param {string} session
+ * @returns {string} The validated session name.
+ * @throws {Error} If the session name contains unsafe characters.
+ */
+export function validateSession(session) {
+  if (!/^[a-zA-Z0-9_-]+$/.test(session)) {
+    throw new Error(`Invalid session name: "${session}". Only alphanumeric, hyphen, and underscore allowed.`);
+  }
+  return session;
+}
+
+// ─── Daemon lifecycle helpers ─────────────────────────────────────────────────
+
+/**
+ * Removes socket, PID, and ready files for the given session.
+ * Called on stale daemon detection or on clean shutdown.
+ * @param {string} session
+ */
+export function cleanupDaemonFiles(session) {
+  for (const filePath of [getSocketPath(session), getPidFile(session), getReadyFile(session)]) {
+    try { fs.unlinkSync(filePath); } catch { /* ignore missing files */ }
+  }
+}
+
+/**
+ * Checks whether the daemon is already running for the given session.
+ * Reads the PID file and sends signal 0 to verify the process is alive.
+ * Cleans up stale files if the process is dead.
+ * @param {string} session
+ * @returns {boolean}
+ */
+export function isDaemonRunning(session) {
+  const pidFile = getPidFile(session);
+  if (!fs.existsSync(pidFile)) return false;
+
+  try {
+    const pid = parseInt(fs.readFileSync(pidFile, 'utf8').trim(), 10);
+    // Reason: signal 0 checks process existence without delivering a real signal
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    // Process does not exist — clean up stale files
+    cleanupDaemonFiles(session);
+    return false;
+  }
+}
+
+// ─── Onboarding payload helpers ───────────────────────────────────────────────
+
+/**
+ * Builds the ready file payload from an extension status response.
+ * @param {{ authenticated: boolean; email: string | null; optionsUrl: string }} status
+ * @returns {{ status: string; email?: string | null; optionsUrl?: string }}
+ */
+export function buildReadyPayload(status) {
+  if (status.authenticated) {
+    return { status: 'ok', email: status.email };
+  }
+  return { status: 'needs_login', optionsUrl: status.optionsUrl };
+}
+
+/**
+ * Parses the ready file content into a status object.
+ * Returns extension_not_installed on parse failure as a safe fallback.
+ * @param {string} raw
+ * @returns {{ status: string; [key: string]: unknown }}
+ */
+export function parseReadyPayload(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return { status: 'extension_not_installed' };
+  }
+}
+
+// ─── Serialized command queue ─────────────────────────────────────────────────
+
+/**
+ * Creates a serialized command queue.
+ * Commands are executed one at a time in FIFO order regardless of how many
+ * socket clients are connected simultaneously. This prevents concurrent `run`
+ * calls from racing inside the extension.
+ *
+ * @param {(cmd: Record<string, unknown>) => Promise<{id: string; success: boolean; data?: unknown; error?: string}>} handler
+ * @returns {{ enqueue: (cmd: Record<string, unknown>) => Promise<{id: string; success: boolean; data?: unknown; error?: string}> }}
+ */
+export function createCommandQueue(handler) {
+  const queue = [];
+  let processing = false;
+
+  async function processNext() {
+    if (processing || queue.length === 0) return;
+    processing = true;
+    const { cmd, resolve } = queue.shift();
+    try {
+      const result = await handler(cmd);
+      resolve(result);
+    } catch (err) {
+      resolve({ id: String(cmd.id ?? 'unknown'), success: false, error: err.message ?? String(err) });
+    } finally {
+      processing = false;
+      // Reason: .catch() prevents unhandled rejection from crashing the daemon
+      // if the recursive call fails before reaching its own try/catch
+      processNext().catch(() => {});
+    }
+  }
+
+  return {
+    /**
+     * Enqueue a command and return a promise that resolves with the response.
+     * The returned Promise always resolves; errors are encoded as { success: false, error } values.
+     * @param {Record<string, unknown>} cmd
+     * @returns {Promise<{id: string; success: boolean; data?: unknown; error?: string}>}
+     */
+    enqueue(cmd) {
+      return new Promise((resolve) => {
+        queue.push({ cmd, resolve });
+        processNext().catch(() => {});
+      });
+    },
+  };
+}