@everydaydevopsio/pilot 0.5.0

package/src/cli/init.ts

@@ -0,0 +1,62 @@
+import { mkdir, writeFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { SKILL_CONTENT } from './skill-template.js';
+
+const SKILL_DIR = '.claude/skills/debug-browser';
+const SKILL_FILE = 'SKILL.md';
+
+export async function runInit(
+  options: { force?: boolean } = {}
+): Promise<void> {
+  const cwd = process.cwd();
+  const skillDir = join(cwd, SKILL_DIR);
+  const skillPath = join(skillDir, SKILL_FILE);
+
+  // Check if skill already exists
+  try {
+    await stat(skillPath);
+    if (!options.force) {
+      console.log(`\x1b[33mSkill already exists:\x1b[0m ${skillPath}`);
+      console.log('Use --force to overwrite.');
+      process.exit(1);
+    }
+  } catch {
+    // File doesn't exist, continue
+  }
+
+  // Create directory structure
+  try {
+    await mkdir(skillDir, { recursive: true });
+  } catch (err) {
+    console.error(`\x1b[31mFailed to create directory:\x1b[0m ${skillDir}`);
+    console.error(err);
+    process.exit(1);
+  }
+
+  // Write SKILL.md
+  try {
+    await writeFile(skillPath, SKILL_CONTENT, 'utf-8');
+  } catch (err) {
+    console.error(`\x1b[31mFailed to write skill file:\x1b[0m ${skillPath}`);
+    console.error(err);
+    process.exit(1);
+  }
+
+  // Success message
+  console.log(`\x1b[32m✓ Created Claude Code skill:\x1b[0m ${skillPath}`);
+  console.log('');
+  console.log('\x1b[1mUsage:\x1b[0m');
+  console.log('  In Claude Code, say "debug in browser" or use /debug-browser');
+  console.log('');
+  console.log('\x1b[1mThe skill will:\x1b[0m');
+  console.log('  1. Start Chrome with remote debugging');
+  console.log('  2. Launch the pilot browser service');
+  console.log('  3. Add the MCP server to your session');
+  console.log('  4. Spawn an error-watching sub-agent');
+  console.log('');
+  console.log('\x1b[1mPrerequisites:\x1b[0m');
+  console.log('  - Google Chrome installed');
+  console.log(
+    '  - pilot (install with: npm install -g @everydaydevopsio/pilot)'
+  );
+}

package/src/cli/skill-template.ts

@@ -0,0 +1,113 @@
+export const SKILL_CONTENT = `---
+name: debug-browser
+description: Add the pilot MCP server and watch for console errors. Use this skill when the user wants to debug a web application, watch for JavaScript errors, or test their app with AI assistance.
+tools:
+  - Bash
+  - Task
+---
+
+# Debug Browser Skill
+
+This skill sets up a browser debugging environment for AI-assisted development using the pilot MCP server. The MCP server manages the Chrome lifecycle automatically via \`browser_start\`.
+
+## What This Skill Does
+
+1. Adds the pilot MCP server to your Claude Code session
+2. Starts the browser via \`browser_start\`
+3. Spawns a sub-agent to watch for console errors
+
+## Instructions
+
+Follow these steps in order.
+
+### Step 1: Add MCP Server to Claude Code Session
+
+Add the pilot MCP server to the current Claude Code session:
+
+\`\`\`bash
+claude mcp add pilot --scope session -- npx @everydaydevopsio/pilot
+\`\`\`
+
+This gives you access to browser control tools like:
+- \`browser_start\` - Launch Chrome
+- \`browser_stop\` - Stop Chrome
+- \`browser_screenshot\` - Capture screenshots
+- \`browser_navigate\` - Navigate to URLs
+- \`browser_click\` - Click elements
+- \`browser_type\` - Type text
+- \`browser_evaluate\` - Run JavaScript
+- \`browser_get_errors\` - Get console errors
+- \`browser_clear_errors\` - Clear error buffer
+
+### Step 2: Start the Browser
+
+Use the \`browser_start\` MCP tool to launch Chrome:
+
+\`\`\`
+Call browser_start with headless: false to open a visible Chrome window.
+\`\`\`
+
+### Step 3: Spawn Error-Watching Sub-Agent
+
+Use the Task tool to spawn a background sub-agent that monitors for console errors:
+
+\`\`\`
+Spawn a sub-agent with subagent_type "general-purpose" and run_in_background: true with this prompt:
+
+"You are an error-watching agent monitoring the browser for console errors.
+
+Your job:
+1. First, call browser_clear_errors to start with a clean slate
+2. Report back that monitoring has started
+3. Every 15-20 seconds, call browser_get_errors with includeWarnings: true
+4. If you find errors, report them with:
+   - The error message
+   - The source file and line number
+   - A brief analysis of what might be wrong
+5. Continue monitoring until the main conversation ends
+
+Be concise but informative when reporting errors."
+\`\`\`
+
+### Step 4: Inform the User
+
+Tell the user:
+- The browser debugging environment is ready
+- They can navigate to their app using \`browser_navigate\`
+- You will be notified of any console errors automatically
+- They can ask you to take screenshots, click elements, or run JavaScript
+
+## Cleanup
+
+When done debugging, call \`browser_stop\` to shut down Chrome cleanly.
+
+## Troubleshooting
+
+### browser_start fails
+- Check if Chrome is installed: the MCP server auto-detects common paths
+- Set \`PILOT_CHROME_PATH\` env var to the Chrome executable if auto-detect fails
+
+### No errors detected
+- Errors are only captured while connected
+- Try \`browser_get_errors\` with \`includeWarnings: true\` to see all console output
+- Verify the page has loaded: \`browser_page_info\`
+
+## Example Session
+
+User: "debug in browser"
+
+Claude executes:
+1. Adds MCP server to session
+2. Calls \`browser_start\` (headless: false)
+3. Spawns error-watching sub-agent
+4. Reports: "Browser debugging environment ready! Navigate to your app and I'll watch for errors."
+
+User: "go to localhost:3000"
+Claude: Uses \`browser_navigate\` to go to http://localhost:3000
+
+[User interacts with the app, an error occurs]
+
+Sub-agent reports: "Error detected: TypeError: Cannot read property 'map' of undefined at App.tsx:42"
+
+Claude: Reads App.tsx, identifies the bug, suggests a fix.
+`;

package/src/commands/click.ts

@@ -0,0 +1,93 @@
+import { z } from 'zod';
+import type { Client } from 'chrome-remote-interface';
+
+export const ClickParamsSchema = z
+  .object({
+    selector: z.string().optional(),
+    x: z.number().optional(),
+    y: z.number().optional(),
+    button: z.enum(['left', 'right', 'middle']).default('left'),
+    clickCount: z.number().int().positive().default(1),
+    timeoutMs: z.number().int().positive().default(5000)
+  })
+  .refine(
+    (v) => v.selector !== undefined || (v.x !== undefined && v.y !== undefined),
+    {
+      message: 'Either selector or x/y coordinates are required'
+    }
+  );
+
+export type ClickParams = z.infer<typeof ClickParamsSchema>;
+
+export interface ClickResult {
+  x: number;
+  y: number;
+}
+
+async function waitForSelector(
+  client: Client,
+  selector: string,
+  timeoutMs: number
+): Promise<{ x: number; y: number }> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const result = await client.Runtime.evaluate({
+      expression: `(function() {
+        const el = document.querySelector(${JSON.stringify(selector)});
+        if (!el) return null;
+        const rect = el.getBoundingClientRect();
+        return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
+      })()`,
+      returnByValue: true
+    });
+
+    if (result.result.value !== null && result.result.value !== undefined) {
+      return result.result.value as { x: number; y: number };
+    }
+
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  throw new Error(`timeout waiting for selector: ${selector}`);
+}
+
+export async function executeClick(
+  client: Client,
+  params: ClickParams
+): Promise<ClickResult> {
+  let x: number;
+  let y: number;
+
+  if (params.selector !== undefined) {
+    const pos = await waitForSelector(
+      client,
+      params.selector,
+      params.timeoutMs
+    );
+    x = pos.x;
+    y = pos.y;
+  } else {
+    x = params.x!;
+    y = params.y!;
+  }
+
+  const button = params.button;
+
+  for (let i = 0; i < params.clickCount; i++) {
+    await client.Input.dispatchMouseEvent({
+      type: 'mousePressed',
+      x,
+      y,
+      button,
+      clickCount: 1
+    });
+    await client.Input.dispatchMouseEvent({
+      type: 'mouseReleased',
+      x,
+      y,
+      button,
+      clickCount: 1
+    });
+  }
+
+  return { x, y };
+}

package/src/commands/evaluate.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import type { Client } from 'chrome-remote-interface';
+
+export const EvaluateParamsSchema = z.object({
+  expression: z.string(),
+  awaitPromise: z.boolean().default(true),
+  timeoutMs: z.number().int().positive().default(10000)
+});
+
+export type EvaluateParams = z.infer<typeof EvaluateParamsSchema>;
+
+export interface EvaluateResult {
+  value: unknown;
+  type: string;
+}
+
+export async function executeEvaluate(
+  client: Client,
+  params: EvaluateParams
+): Promise<EvaluateResult> {
+  const result = await Promise.race([
+    client.Runtime.evaluate({
+      expression: params.expression,
+      awaitPromise: params.awaitPromise,
+      returnByValue: true,
+      userGesture: true
+    }),
+    new Promise<never>((_, reject) =>
+      setTimeout(() => reject(new Error('timeout')), params.timeoutMs)
+    )
+  ]);
+
+  if (result.exceptionDetails) {
+    const msg =
+      result.exceptionDetails.exception?.description ??
+      result.exceptionDetails.text ??
+      'evaluation error';
+    throw new Error(msg);
+  }
+
+  return {
+    value: result.result.value,
+    type: result.result.type
+  };
+}

package/src/commands/navigate.ts

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+import type { Client } from 'chrome-remote-interface';
+import type { BrowserManager } from '../browser.js';
+
+export const NavigateParamsSchema = z.object({
+  url: z.string().url(),
+  waitUntil: z
+    .enum(['load', 'domcontentloaded', 'networkidle'])
+    .default('load'),
+  timeoutMs: z.number().int().positive().default(30000)
+});
+
+export type NavigateParams = z.infer<typeof NavigateParamsSchema>;
+
+export interface NavigateResult {
+  url: string;
+  status: number;
+}
+
+export async function executeNavigate(
+  client: Client,
+  manager: BrowserManager,
+  params: NavigateParams
+): Promise<NavigateResult> {
+  let finalStatus = 200;
+
+  const navigationPromise = new Promise<{ url: string; status: number }>(
+    (resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error('timeout'));
+      }, params.timeoutMs);
+
+      const cleanup = () => clearTimeout(timeout);
+
+      if (params.waitUntil === 'load') {
+        client.Page.loadEventFired(() => {
+          cleanup();
+          client.Runtime.evaluate({ expression: 'window.location.href' }).then(
+            (r) => {
+              resolve({
+                url: (r.result.value as string) ?? params.url,
+                status: finalStatus
+              });
+            },
+            reject
+          );
+        });
+      } else if (params.waitUntil === 'domcontentloaded') {
+        client.Page.domContentEventFired(() => {
+          cleanup();
+          client.Runtime.evaluate({ expression: 'window.location.href' }).then(
+            (r) => {
+              resolve({
+                url: (r.result.value as string) ?? params.url,
+                status: finalStatus
+              });
+            },
+            reject
+          );
+        });
+      } else {
+        // networkidle
+        manager
+          .waitForNetworkIdle(params.timeoutMs)
+          .then(() => {
+            cleanup();
+            return client.Runtime.evaluate({
+              expression: 'window.location.href'
+            });
+          })
+          .then((r) => {
+            resolve({
+              url: (r.result.value as string) ?? params.url,
+              status: finalStatus
+            });
+          })
+          .catch((err: unknown) => {
+            cleanup();
+            reject(err);
+          });
+      }
+    }
+  );
+
+  // Capture the response status
+  const responseHandler = (params: {
+    response: { url: string; status: number };
+  }) => {
+    if (params.response.url === params.response.url && params.response.status) {
+      finalStatus = params.response.status;
+    }
+  };
+  client.Network.responseReceived(responseHandler);
+
+  const { frameId } = await client.Page.navigate({ url: params.url });
+  void frameId; // used implicitly
+
+  try {
+    const result = await navigationPromise;
+    return result;
+  } finally {
+    // Event listeners are auto-removed when client disconnects;
+    // for long-lived clients this is acceptable for v0.1
+  }
+}

package/src/commands/page_info.ts

@@ -0,0 +1,21 @@
+import type { Client } from 'chrome-remote-interface';
+
+export interface PageInfoResult {
+  url: string;
+  title: string;
+  readyState: string;
+}
+
+export async function executePageInfo(client: Client): Promise<PageInfoResult> {
+  const result = await client.Runtime.evaluate({
+    expression: `JSON.stringify({
+      url: window.location.href,
+      title: document.title,
+      readyState: document.readyState
+    })`,
+    returnByValue: true
+  });
+
+  const value = result.result.value as string;
+  return JSON.parse(value) as PageInfoResult;
+}

package/src/commands/screenshot.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import type { Client } from 'chrome-remote-interface';
+
+export const ScreenshotParamsSchema = z.object({
+  format: z.enum(['png', 'jpeg']).default('png'),
+  quality: z.number().int().min(1).max(100).default(80),
+  fullPage: z.boolean().default(false)
+});
+
+export type ScreenshotParams = z.infer<typeof ScreenshotParamsSchema>;
+
+export interface ScreenshotResult {
+  dataUrl: string;
+  width: number;
+  height: number;
+}
+
+export async function executeScreenshot(
+  client: Client,
+  params: ScreenshotParams
+): Promise<ScreenshotResult> {
+  let clip:
+    | {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        scale: number;
+      }
+    | undefined;
+
+  if (params.fullPage) {
+    const layoutResult = await client.Page.getLayoutMetrics();
+    const { width, height } = layoutResult.contentSize;
+    clip = { x: 0, y: 0, width, height, scale: 1 };
+  }
+
+  const captureParams: {
+    format?: 'png' | 'jpeg' | 'webp';
+    quality?: number;
+    clip?: typeof clip;
+    captureBeyondViewport?: boolean;
+  } = {
+    format: params.format,
+    captureBeyondViewport: params.fullPage
+  };
+
+  if (params.format === 'jpeg') {
+    captureParams.quality = params.quality;
+  }
+
+  if (clip) {
+    captureParams.clip = clip;
+  }
+
+  const { data } = await client.Page.captureScreenshot(captureParams);
+
+  const mime = params.format === 'jpeg' ? 'image/jpeg' : 'image/png';
+  const dataUrl = `data:${mime};base64,${data}`;
+
+  // Decode dimensions from base64
+  const buf = Buffer.from(data, 'base64');
+  let width = 0;
+  let height = 0;
+
+  if (params.format === 'png' && buf.length > 24) {
+    width = buf.readUInt32BE(16);
+    height = buf.readUInt32BE(20);
+  }
+
+  return { dataUrl, width, height };
+}

package/src/commands/tabs.ts

@@ -0,0 +1,35 @@
+import type { BrowserManager, TabInfo } from '../browser.js';
+
+export async function executeListTabs(
+  manager: BrowserManager
+): Promise<TabInfo[]> {
+  return manager.listTabs();
+}
+
+export interface NewTabResult {
+  targetId: string;
+  url: string;
+}
+
+export async function executeNewTab(
+  manager: BrowserManager,
+  url?: string
+): Promise<NewTabResult> {
+  const tab = await manager.createTab(url);
+  await manager.switchTab(tab.targetId);
+  return { targetId: tab.targetId, url: tab.url };
+}
+
+export async function executeCloseTab(
+  manager: BrowserManager,
+  targetId: string
+): Promise<void> {
+  await manager.closeTab(targetId);
+}
+
+export async function executeSwitchTab(
+  manager: BrowserManager,
+  targetId: string
+): Promise<void> {
+  await manager.switchTab(targetId);
+}

package/src/commands/type.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+import type { Client } from 'chrome-remote-interface';
+
+export const TypeParamsSchema = z.object({
+  text: z.string(),
+  selector: z.string().optional(),
+  clearFirst: z.boolean().default(false),
+  delayMs: z.number().int().min(0).default(0)
+});
+
+export type TypeParams = z.infer<typeof TypeParamsSchema>;
+
+export interface TypeResult {
+  ok: boolean;
+}
+
+async function focusSelector(client: Client, selector: string): Promise<void> {
+  const result = await client.Runtime.evaluate({
+    expression: `(function() {
+      const el = document.querySelector(${JSON.stringify(selector)});
+      if (!el) return false;
+      el.focus();
+      return true;
+    })()`
+  });
+  if (!result.result.value) {
+    throw new Error(`Element not found: ${selector}`);
+  }
+}
+
+export async function executeType(
+  client: Client,
+  params: TypeParams
+): Promise<TypeResult> {
+  if (params.selector) {
+    await focusSelector(client, params.selector);
+  }
+
+  if (params.clearFirst) {
+    // Select all and delete
+    await client.Input.dispatchKeyEvent({
+      type: 'keyDown',
+      key: 'a',
+      modifiers: 2 // Ctrl
+    });
+    await client.Input.dispatchKeyEvent({
+      type: 'keyUp',
+      key: 'a',
+      modifiers: 2
+    });
+    await client.Input.dispatchKeyEvent({
+      type: 'keyDown',
+      key: 'Delete'
+    });
+    await client.Input.dispatchKeyEvent({
+      type: 'keyUp',
+      key: 'Delete'
+    });
+  }
+
+  for (const char of params.text) {
+    await client.Input.dispatchKeyEvent({
+      type: 'keyDown',
+      text: char
+    });
+    await client.Input.dispatchKeyEvent({
+      type: 'keyUp',
+      text: char
+    });
+
+    if (params.delayMs > 0) {
+      await new Promise((r) => setTimeout(r, params.delayMs));
+    }
+  }
+
+  return { ok: true };
+}