vellum 0.2.0 → 0.2.2

package/src/cli/doordash.ts

@@ -139,8 +139,8 @@ export function registerDoordashCommand(program: Command): void {
   dd.command('refresh')
     .description(
       'Start a Ride Shotgun learn session to capture fresh DoorDash cookies. ' +
-      'Opens doordash.com in Chrome — sign in when prompted. ' +
-      'NOTE: Chrome will restart with debugging enabled; your tabs will be restored.',
+      'Opens doordash.com in a separate Chrome window — sign in when prompted. ' +
+      'Your existing Chrome and tabs are not affected.',
     )
     .option('--duration <seconds>', 'Recording duration in seconds', '180')
     .action(async (opts: { duration: string }, cmd: Command) => {
@@ -148,6 +148,9 @@ export function registerDoordashCommand(program: Command): void {
       const duration = parseInt(opts.duration, 10);
 
       try {
+        // Restore minimized Chrome window so user can see the login page
+        try { await restoreChromeWindow(); } catch { /* best-effort */ }
+
         const result = await startLearnSession(duration);
         if (result.recordingPath) {
           const session = importFromRecording(result.recordingPath);
@@ -167,6 +170,14 @@ export function registerDoordashCommand(program: Command): void {
             // Non-fatal: query extraction is best-effort
           }
 
+          // Best-effort: minimize Chrome window after capturing session
+          try {
+            await minimizeChromeWindow();
+            process.stderr.write('[doordash] Chrome window minimized\n');
+          } catch {
+            // Non-fatal: minimizing is best-effort
+          }
+
           output(
             {
               ok: true,
@@ -326,7 +337,8 @@ export function registerDoordashCommand(program: Command): void {
     .description('Inspect GraphQL operations in a recording')
     .argument('<recordingId>', 'Recording ID or path to recording JSON file')
     .option('--op <operationName>', 'Filter to a specific operation name')
-    .action(async (recordingIdOrPath: string, opts: { op?: string }, cmd: Command) => {
+    .option('--extract-options', 'Extract item customization options from updateCartItem operations')
+    .action(async (recordingIdOrPath: string, opts: { op?: string; extractOptions?: boolean }, cmd: Command) => {
       const json = getJson(cmd);
 
       try {
@@ -352,6 +364,43 @@ export function registerDoordashCommand(program: Command): void {
 
         const queries = extractQueries(recording);
 
+        if (opts.extractOptions) {
+          const cartOps = queries.filter(q => q.operationName === 'updateCartItem');
+          if (cartOps.length === 0) {
+            outputError('No updateCartItem operations found in this recording');
+            return;
+          }
+
+          const extracted = cartOps.map(q => {
+            const vars = (q.exampleVariables ?? {}) as Record<string, unknown>;
+            const params = (vars.updateCartItemApiParams ?? {}) as Record<string, unknown>;
+            return {
+              itemId: params.itemId as string | undefined,
+              itemName: params.itemName as string | undefined,
+              nestedOptions: params.nestedOptions as string | undefined,
+              specialInstructions: params.specialInstructions as string | undefined,
+              unitPrice: params.unitPrice as number | undefined,
+              menuId: params.menuId as string | undefined,
+              storeId: params.storeId as string | undefined,
+            };
+          });
+
+          if (json) {
+            output({ ok: true, items: extracted, count: extracted.length }, true);
+          } else {
+            for (const item of extracted) {
+              process.stderr.write(`\nItem: ${item.itemName ?? 'unknown'} (${item.itemId ?? '?'})\n`);
+              process.stderr.write(`  Store: ${item.storeId ?? '?'}, Menu: ${item.menuId ?? '?'}\n`);
+              process.stderr.write(`  Unit Price: ${item.unitPrice ?? '?'}\n`);
+              if (item.specialInstructions) {
+                process.stderr.write(`  Special Instructions: ${item.specialInstructions}\n`);
+              }
+              process.stderr.write(`  Options: ${item.nestedOptions ?? '[]'}\n`);
+            }
+          }
+          return;
+        }
+
         if (opts.op) {
           const match = queries.find(q => q.operationName === opts.op);
           if (!match) {
@@ -511,6 +560,7 @@ export function registerDoordashCommand(program: Command): void {
     .option('--quantity <n>', 'Quantity', '1')
     .option('--cart-id <cartId>', 'Existing cart ID (creates new if omitted)')
     .option('--special-instructions <text>', 'Special instructions')
+    .option('--options <json>', 'Item customization options as JSON array (from item details or recording)')
     .action(
       async (
         opts: {
@@ -522,6 +572,7 @@ export function registerDoordashCommand(program: Command): void {
           quantity: string;
           cartId?: string;
           specialInstructions?: string;
+          options?: string;
         },
         cmd: Command,
       ) => {
@@ -535,6 +586,7 @@ export function registerDoordashCommand(program: Command): void {
             quantity: parseInt(opts.quantity, 10),
             cartId: opts.cartId,
             specialInstructions: opts.specialInstructions,
+            nestedOptions: opts.options,
           });
           return { cart: result };
         });
@@ -580,6 +632,115 @@ export function registerDoordashCommand(program: Command): void {
       });
     });
 
+  // cart learn — capture customization options via CDP recording
+  cart
+    .command('learn')
+    .description(
+      'Learn item customization options by recording a browser interaction. ' +
+      'Opens Chrome and watches you customize an item — when you add it to cart, ' +
+      'the nestedOptions and specialInstructions are extracted and output.',
+    )
+    .option('--duration <seconds>', 'Max recording duration in seconds', '120')
+    .action(async (opts: { duration: string }, cmd: Command) => {
+      const json = getJson(cmd);
+      const duration = parseInt(opts.duration, 10);
+
+      try {
+        await ensureChromeWithCDP();
+
+        const startTime = Date.now() / 1000;
+        const recorder = new NetworkRecorder('doordash.com');
+        await recorder.startDirect('http://localhost:9222');
+
+        process.stderr.write('Recording... Navigate to an item, customize it, and add it to cart.\n');
+        process.stderr.write(`Will auto-stop when "updateCartItem" is detected. Timeout: ${duration}s.\n`);
+
+        await new Promise<void>((resolve) => {
+          const timer = setTimeout(() => {
+            if (poll) clearInterval(poll);
+            process.stderr.write(`\nTimeout reached (${duration}s).\n`);
+            resolve();
+          }, duration * 1000);
+
+          process.on('SIGINT', () => {
+            if (poll) clearInterval(poll);
+            clearTimeout(timer);
+            resolve();
+          });
+
+          const poll = setInterval(() => {
+            const entries = recorder.getEntries();
+            const found = entries.some(e => {
+              if (!e.request.postData) return false;
+              try {
+                const body = JSON.parse(e.request.postData) as { operationName?: string };
+                return body.operationName === 'updateCartItem';
+              } catch { return false; }
+            });
+            if (found) {
+              clearInterval(poll);
+              clearTimeout(timer);
+              process.stderr.write('\nDetected "updateCartItem" operation.\n');
+              setTimeout(() => resolve(), 3000);
+            }
+          }, 500);
+        });
+
+        process.stderr.write('Stopping recording...\n');
+        const cookies = await recorder.extractCookies('doordash.com');
+        const entries = await recorder.stop();
+
+        const recording: SessionRecording = {
+          id: crypto.randomUUID(),
+          startedAt: startTime,
+          endedAt: Date.now() / 1000,
+          targetDomain: 'doordash.com',
+          networkEntries: entries,
+          cookies,
+          observations: [],
+        };
+
+        // Extract updateCartItem operations
+        const queries = extractQueries(recording);
+        const cartOps = queries.filter(q => q.operationName === 'updateCartItem');
+
+        if (cartOps.length === 0) {
+          outputError('No updateCartItem operations captured. Did you add an item to cart?');
+          return;
+        }
+
+        const extracted = cartOps.map(q => {
+          const vars = (q.exampleVariables ?? {}) as Record<string, unknown>;
+          const params = (vars.updateCartItemApiParams ?? {}) as Record<string, unknown>;
+          return {
+            itemId: params.itemId as string | undefined,
+            itemName: params.itemName as string | undefined,
+            nestedOptions: params.nestedOptions as string | undefined,
+            specialInstructions: params.specialInstructions as string | undefined,
+            unitPrice: params.unitPrice as number | undefined,
+            menuId: params.menuId as string | undefined,
+            storeId: params.storeId as string | undefined,
+          };
+        });
+
+        // Also save the recording for future reference
+        const recordingPath = saveRecording(recording);
+
+        output(
+          {
+            ok: true,
+            items: extracted,
+            count: extracted.length,
+            recordingId: recording.id,
+            recordingPath,
+          },
+          json,
+        );
+      } catch (err) {
+        outputError(err instanceof Error ? err.message : String(err));
+      }
+    });
+
   // =========================================================================
   // checkout — get checkout / dropoff options
   // =========================================================================
@@ -664,7 +825,7 @@ export function registerDoordashCommand(program: Command): void {
 // Chrome CDP restart helper
 // ---------------------------------------------------------------------------
 
-import { execSync, spawn as spawnChild } from 'node:child_process';
+import { spawn as spawnChild } from 'node:child_process';
 import { homedir } from 'node:os';
 import { join as pathJoin } from 'node:path';
 
@@ -687,33 +848,15 @@ async function ensureChromeWithCDP(): Promise<void> {
   // Already running with CDP?
   if (await isCdpReady()) return;
 
-  // Kill existing Chrome gracefully
-  try {
-    execSync('osascript -e \'tell application "Google Chrome" to quit\'', {
-      timeout: 5000,
-      stdio: 'ignore',
-    });
-  } catch {
-    // Chrome might not be running
-  }
-
-  // Wait for Chrome to quit
-  for (let i = 0; i < 30; i++) {
-    try {
-      execSync('pgrep -x "Google Chrome"', { stdio: 'ignore' });
-      await new Promise(r => setTimeout(r, 200));
-    } catch {
-      break; // Not running
-    }
-  }
-
-  // Relaunch Chrome with CDP flags
+  // Launch a separate Chrome instance with CDP flags alongside any existing Chrome.
+  // Using a dedicated --user-data-dir allows coexistence without killing the user's browser.
   const chromeApp =
     '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
   spawnChild(chromeApp, [
     `--remote-debugging-port=9222`,
     `--force-renderer-accessibility`,
     `--user-data-dir=${CHROME_DATA_DIR}`,
+    `https://www.doordash.com/consumer/login/`,
   ], {
     detached: true,
     stdio: 'ignore',
@@ -727,6 +870,94 @@ async function ensureChromeWithCDP(): Promise<void> {
   throw new Error('Chrome started but CDP endpoint not responding after 15s');
 }
 
+async function minimizeChromeWindow(): Promise<void> {
+  const res = await fetch(`${CDP_BASE}/json/list`);
+  const targets = (await res.json()) as Array<{ type: string; webSocketDebuggerUrl: string }>;
+  const pageTarget = targets.find(t => t.type === 'page');
+  if (!pageTarget) return;
+
+  const ws = new WebSocket(pageTarget.webSocketDebuggerUrl);
+
+  await new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      ws.close();
+      reject(new Error('CDP minimize timed out'));
+    }, 5000);
+
+    ws.addEventListener('open', () => {
+      ws.send(JSON.stringify({ id: 1, method: 'Browser.getWindowForTarget' }));
+    });
+
+    ws.addEventListener('message', (event) => {
+      const msg = JSON.parse(String(event.data)) as { id: number; result?: { windowId: number } };
+      if (msg.id === 1 && msg.result) {
+        ws.send(JSON.stringify({
+          id: 2,
+          method: 'Browser.setWindowBounds',
+          params: { windowId: msg.result.windowId, bounds: { windowState: 'minimized' } },
+        }));
+      } else if (msg.id === 1) {
+        clearTimeout(timeout);
+        ws.close();
+        reject(new Error('Browser.getWindowForTarget failed'));
+      } else if (msg.id === 2) {
+        clearTimeout(timeout);
+        ws.close();
+        resolve();
+      }
+    });
+
+    ws.addEventListener('error', (err) => {
+      clearTimeout(timeout);
+      reject(err);
+    });
+  });
+}
+
+async function restoreChromeWindow(): Promise<void> {
+  const res = await fetch(`${CDP_BASE}/json/list`);
+  const targets = (await res.json()) as Array<{ type: string; webSocketDebuggerUrl: string }>;
+  const pageTarget = targets.find(t => t.type === 'page');
+  if (!pageTarget) return;
+
+  const ws = new WebSocket(pageTarget.webSocketDebuggerUrl);
+
+  await new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      ws.close();
+      reject(new Error('CDP restore timed out'));
+    }, 5000);
+
+    ws.addEventListener('open', () => {
+      ws.send(JSON.stringify({ id: 1, method: 'Browser.getWindowForTarget' }));
+    });
+
+    ws.addEventListener('message', (event) => {
+      const msg = JSON.parse(String(event.data)) as { id: number; result?: { windowId: number } };
+      if (msg.id === 1 && msg.result) {
+        ws.send(JSON.stringify({
+          id: 2,
+          method: 'Browser.setWindowBounds',
+          params: { windowId: msg.result.windowId, bounds: { windowState: 'normal' } },
+        }));
+      } else if (msg.id === 1) {
+        clearTimeout(timeout);
+        ws.close();
+        reject(new Error('Browser.getWindowForTarget failed'));
+      } else if (msg.id === 2) {
+        clearTimeout(timeout);
+        ws.close();
+        resolve();
+      }
+    });
+
+    ws.addEventListener('error', (err) => {
+      clearTimeout(timeout);
+      reject(err);
+    });
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Ride Shotgun learn session helper
 // ---------------------------------------------------------------------------

package/src/cli/ipc-client.ts

@@ -0,0 +1,82 @@
+import * as net from 'node:net';
+import { getSocketPath, readSessionToken } from '../util/platform.js';
+import {
+  serialize,
+  createMessageParser,
+  type ClientMessage,
+  type ServerMessage,
+} from '../daemon/ipc-protocol.js';
+import { IpcError } from '../util/errors.js';
+
+export function sendOneMessage(
+  msg: ClientMessage,
+): Promise<ServerMessage> {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(getSocketPath());
+    const parser = createMessageParser();
+    let resolved = false;
+    let authenticated = false;
+
+    socket.on('connect', () => {
+      // Authenticate first — the daemon requires a valid session token
+      // before it will accept any other messages.
+      const token = readSessionToken();
+      if (!token) {
+        resolved = true;
+        reject(new IpcError('Session token not found — is the daemon running?'));
+        socket.destroy();
+        return;
+      }
+      socket.write(serialize({ type: 'auth', token }));
+    });
+
+    socket.on('data', (data) => {
+      const messages = parser.feed(data.toString()) as ServerMessage[];
+      for (const m of messages) {
+        // Handle auth handshake
+        if (!authenticated) {
+          if (m.type === 'auth_result') {
+            if ((m as { success: boolean }).success) {
+              authenticated = true;
+              // Now send the actual message
+              socket.write(serialize(msg));
+            } else {
+              resolved = true;
+              reject(new IpcError((m as { message?: string }).message ?? 'Authentication failed'));
+              socket.destroy();
+            }
+          }
+          continue;
+        }
+
+        // Skip push messages that aren't responses to our request
+        if (m.type === 'daemon_status') {
+          continue;
+        }
+        // On auto-auth sockets the server may send a second auth_result
+        // in response to the client's auth message after we're already
+        // authenticated — ignore it so it doesn't resolve as the response.
+        if (m.type === 'auth_result') {
+          continue;
+        }
+        if (m.type === 'session_info' && msg.type !== 'session_create') {
+          continue;
+        }
+        resolved = true;
+        socket.end();
+        resolve(m);
+        return;
+      }
+    });
+
+    socket.on('error', (err) => {
+      if (!resolved) reject(err);
+    });
+
+    socket.on('close', () => {
+      if (!resolved) {
+        reject(new IpcError('Socket closed before receiving a response'));
+      }
+    });
+  });
+}

package/src/cli/map.ts

@@ -0,0 +1,246 @@
+/**
+ * CLI command: `vellum map <domain>`
+ *
+ * Launches Chrome with CDP, starts a Ride Shotgun learn session to auto-navigate
+ * the given domain, then analyzes captured network traffic into a deduplicated API map.
+ */
+
+import * as net from 'node:net';
+import { spawn as spawnChild } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join as pathJoin } from 'node:path';
+import { Command } from 'commander';
+import { getSocketPath, readSessionToken } from '../util/platform.js';
+import {
+  serialize,
+  createMessageParser,
+} from '../daemon/ipc-protocol.js';
+import { loadRecording } from '../tools/browser/recording-store.js';
+import { analyzeApiMap, saveApiMap, printApiMapTable } from '../tools/browser/api-map.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function output(data: unknown, json: boolean): void {
+  process.stdout.write(
+    json ? JSON.stringify(data) + '\n' : JSON.stringify(data, null, 2) + '\n',
+  );
+}
+
+function outputError(message: string, code = 1): void {
+  output({ ok: false, error: message }, true);
+  process.exitCode = code;
+}
+
+function getJson(cmd: Command): boolean {
+  let c: Command | null = cmd;
+  while (c) {
+    if ((c.opts() as { json?: boolean }).json) return true;
+    c = c.parent;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Chrome CDP helpers
+// ---------------------------------------------------------------------------
+
+const CDP_BASE = 'http://localhost:9222';
+const CHROME_DATA_DIR = pathJoin(
+  homedir(),
+  'Library/Application Support/Google/Chrome-CDP',
+);
+
+async function isCdpReady(): Promise<boolean> {
+  try {
+    const res = await fetch(`${CDP_BASE}/json/version`);
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+async function ensureChromeWithCDP(domain: string): Promise<void> {
+  // Already running with CDP?
+  if (await isCdpReady()) return;
+
+  // Launch a separate Chrome instance with CDP flags alongside any existing Chrome.
+  const chromeApp =
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+  spawnChild(chromeApp, [
+    `--remote-debugging-port=9222`,
+    `--force-renderer-accessibility`,
+    `--user-data-dir=${CHROME_DATA_DIR}`,
+    `https://${domain}/`,
+  ], {
+    detached: true,
+    stdio: 'ignore',
+  }).unref();
+
+  // Wait for CDP to be ready
+  for (let i = 0; i < 30; i++) {
+    await new Promise(r => setTimeout(r, 500));
+    if (await isCdpReady()) return;
+  }
+  throw new Error('Chrome started but CDP endpoint not responding after 15s');
+}
+
+// ---------------------------------------------------------------------------
+// Ride Shotgun learn session helper
+// ---------------------------------------------------------------------------
+
+interface LearnResult {
+  recordingId?: string;
+  recordingPath?: string;
+}
+
+async function startLearnSession(domain: string, durationSeconds: number): Promise<LearnResult> {
+  await ensureChromeWithCDP(domain);
+
+  return new Promise((resolve, reject) => {
+    const socketPath = getSocketPath();
+    const sessionToken = readSessionToken();
+    const socket = net.createConnection(socketPath);
+    const parser = createMessageParser();
+
+    socket.on('error', (err) => {
+      reject(new Error(`Cannot connect to daemon: ${err.message}. Is the daemon running?`));
+    });
+
+    const timeoutHandle = setTimeout(() => {
+      socket.destroy();
+      reject(new Error(`Learn session timed out after ${durationSeconds + 30}s`));
+    }, (durationSeconds + 30) * 1000);
+    timeoutHandle.unref();
+
+    let authenticated = !sessionToken;
+
+    const sendStartCommand = () => {
+      socket.write(
+        serialize({
+          type: 'ride_shotgun_start',
+          durationSeconds,
+          intervalSeconds: 5,
+          mode: 'learn',
+          targetDomain: domain,
+          autoNavigate: true,
+        } as unknown as import('../daemon/ipc-protocol.js').ClientMessage),
+      );
+    };
+
+    socket.on('data', (chunk) => {
+      const messages = parser.feed(chunk.toString('utf-8'));
+      for (const msg of messages) {
+        const m = msg as unknown as Record<string, unknown>;
+
+        if (!authenticated && m.type === 'auth_result') {
+          if ((m as { success: boolean }).success) {
+            authenticated = true;
+            sendStartCommand();
+          } else {
+            clearTimeout(timeoutHandle);
+            socket.destroy();
+            reject(new Error('Daemon authentication failed'));
+          }
+          continue;
+        }
+
+        if (m.type === 'auth_result') {
+          continue;
+        }
+
+        if (m.type === 'ride_shotgun_result') {
+          clearTimeout(timeoutHandle);
+          socket.destroy();
+          resolve({
+            recordingId: m.recordingId as string | undefined,
+            recordingPath: m.recordingPath as string | undefined,
+          });
+        }
+      }
+    });
+
+    socket.on('connect', () => {
+      if (sessionToken) {
+        socket.write(
+          serialize({
+            type: 'auth',
+            token: sessionToken,
+          } as unknown as import('../daemon/ipc-protocol.js').ClientMessage),
+        );
+      } else {
+        sendStartCommand();
+      }
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
+
+export function registerMapCommand(program: Command): void {
+  program
+    .command('map')
+    .description(
+      'Auto-navigate a domain and produce a deduplicated API map. ' +
+      'Launches Chrome with CDP, starts a Ride Shotgun learn session, ' +
+      'then analyzes captured network traffic.',
+    )
+    .argument('<domain>', 'Domain to map (e.g., example.com)')
+    .option('--duration <seconds>', 'Recording duration in seconds', '120')
+    .option('--json', 'Machine-readable JSON output')
+    .action(async (domain: string, opts: { duration: string; json?: boolean }, cmd: Command) => {
+      const json = getJson(cmd);
+      const duration = parseInt(opts.duration, 10);
+
+      try {
+        // 1. Start learn session (launches Chrome + auto-navigates)
+        if (!json) {
+          console.log(`Starting API map session for ${domain} (${duration}s)...`);
+        }
+        const result = await startLearnSession(domain, duration);
+
+        if (!result.recordingId) {
+          outputError('Recording completed but no recording ID returned');
+          return;
+        }
+
+        // 2. Load the recording
+        const recording = loadRecording(result.recordingId);
+        if (!recording) {
+          outputError(`Failed to load recording ${result.recordingId}`);
+          return;
+        }
+
+        // 3. Analyze the API map
+        const apiMap = analyzeApiMap(recording.networkEntries, domain);
+
+        // 4. Save the API map
+        const savedPath = saveApiMap(domain, apiMap);
+
+        // 5. Display results
+        if (!json) {
+          printApiMapTable(apiMap);
+          console.log(`API map saved to: ${savedPath}`);
+        }
+
+        // 6. Output JSON result
+        output(
+          {
+            ok: true,
+            domain,
+            recordingId: result.recordingId,
+            savedPath,
+            totalRequests: apiMap.totalRequests,
+            endpointCount: apiMap.endpoints.length,
+            apiMap,
+          },
+          json,
+        );
+      } catch (err) {
+        outputError(err instanceof Error ? err.message : String(err));
+      }
+    });
+}