@runchr/gstack-antigravity 0.1.0 → 0.1.2

package/.agents/skills/gstack/browse/src/meta-commands.ts

@@ -0,0 +1,269 @@
+/**
+ * Meta commands — tabs, server control, screenshots, chain, diff, snapshot
+ */
+
+import type { BrowserManager } from './browser-manager';
+import { handleSnapshot } from './snapshot';
+import { getCleanText } from './read-commands';
+import { READ_COMMANDS, WRITE_COMMANDS, META_COMMANDS } from './commands';
+import { validateNavigationUrl } from './url-validation';
+import * as Diff from 'diff';
+import * as fs from 'fs';
+import * as path from 'path';
+import { TEMP_DIR, isPathWithin } from './platform';
+
+// Security: Path validation to prevent path traversal attacks
+const SAFE_DIRECTORIES = [TEMP_DIR, process.cwd()];
+
+export function validateOutputPath(filePath: string): void {
+  const resolved = path.resolve(filePath);
+  const isSafe = SAFE_DIRECTORIES.some(dir => isPathWithin(resolved, dir));
+  if (!isSafe) {
+    throw new Error(`Path must be within: ${SAFE_DIRECTORIES.join(', ')}`);
+  }
+}
+
+export async function handleMetaCommand(
+  command: string,
+  args: string[],
+  bm: BrowserManager,
+  shutdown: () => Promise<void> | void
+): Promise<string> {
+  switch (command) {
+    // ─── Tabs ──────────────────────────────────────────
+    case 'tabs': {
+      const tabs = await bm.getTabListWithTitles();
+      return tabs.map(t =>
+        `${t.active ? '→ ' : '  '}[${t.id}] ${t.title || '(untitled)'} — ${t.url}`
+      ).join('\n');
+    }
+
+    case 'tab': {
+      const id = parseInt(args[0], 10);
+      if (isNaN(id)) throw new Error('Usage: browse tab <id>');
+      bm.switchTab(id);
+      return `Switched to tab ${id}`;
+    }
+
+    case 'newtab': {
+      const url = args[0];
+      const id = await bm.newTab(url);
+      return `Opened tab ${id}${url ? ` → ${url}` : ''}`;
+    }
+
+    case 'closetab': {
+      const id = args[0] ? parseInt(args[0], 10) : undefined;
+      await bm.closeTab(id);
+      return `Closed tab${id ? ` ${id}` : ''}`;
+    }
+
+    // ─── Server Control ────────────────────────────────
+    case 'status': {
+      const page = bm.getPage();
+      const tabs = bm.getTabCount();
+      return [
+        `Status: healthy`,
+        `URL: ${page.url()}`,
+        `Tabs: ${tabs}`,
+        `PID: ${process.pid}`,
+      ].join('\n');
+    }
+
+    case 'url': {
+      return bm.getCurrentUrl();
+    }
+
+    case 'stop': {
+      await shutdown();
+      return 'Server stopped';
+    }
+
+    case 'restart': {
+      // Signal that we want a restart — the CLI will detect exit and restart
+      console.log('[browse] Restart requested. Exiting for CLI to restart.');
+      await shutdown();
+      return 'Restarting...';
+    }
+
+    // ─── Visual ────────────────────────────────────────
+    case 'screenshot': {
+      // Parse priority: flags (--viewport, --clip) → selector (@ref, CSS) → output path
+      const page = bm.getPage();
+      let outputPath = `${TEMP_DIR}/browse-screenshot.png`;
+      let clipRect: { x: number; y: number; width: number; height: number } | undefined;
+      let targetSelector: string | undefined;
+      let viewportOnly = false;
+
+      const remaining: string[] = [];
+      for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--viewport') {
+          viewportOnly = true;
+        } else if (args[i] === '--clip') {
+          const coords = args[++i];
+          if (!coords) throw new Error('Usage: screenshot --clip x,y,w,h [path]');
+          const parts = coords.split(',').map(Number);
+          if (parts.length !== 4 || parts.some(isNaN))
+            throw new Error('Usage: screenshot --clip x,y,width,height — all must be numbers');
+          clipRect = { x: parts[0], y: parts[1], width: parts[2], height: parts[3] };
+        } else if (args[i].startsWith('--')) {
+          throw new Error(`Unknown screenshot flag: ${args[i]}`);
+        } else {
+          remaining.push(args[i]);
+        }
+      }
+
+      // Separate target (selector/@ref) from output path
+      for (const arg of remaining) {
+        if (arg.startsWith('@e') || arg.startsWith('@c') || arg.startsWith('.') || arg.startsWith('#') || arg.includes('[')) {
+          targetSelector = arg;
+        } else {
+          outputPath = arg;
+        }
+      }
+
+      validateOutputPath(outputPath);
+
+      if (clipRect && targetSelector) {
+        throw new Error('Cannot use --clip with a selector/ref — choose one');
+      }
+      if (viewportOnly && clipRect) {
+        throw new Error('Cannot use --viewport with --clip — choose one');
+      }
+
+      if (targetSelector) {
+        const resolved = await bm.resolveRef(targetSelector);
+        const locator = 'locator' in resolved ? resolved.locator : page.locator(resolved.selector);
+        await locator.screenshot({ path: outputPath, timeout: 5000 });
+        return `Screenshot saved (element): ${outputPath}`;
+      }
+
+      if (clipRect) {
+        await page.screenshot({ path: outputPath, clip: clipRect });
+        return `Screenshot saved (clip ${clipRect.x},${clipRect.y},${clipRect.width},${clipRect.height}): ${outputPath}`;
+      }
+
+      await page.screenshot({ path: outputPath, fullPage: !viewportOnly });
+      return `Screenshot saved${viewportOnly ? ' (viewport)' : ''}: ${outputPath}`;
+    }
+
+    case 'pdf': {
+      const page = bm.getPage();
+      const pdfPath = args[0] || `${TEMP_DIR}/browse-page.pdf`;
+      validateOutputPath(pdfPath);
+      await page.pdf({ path: pdfPath, format: 'A4' });
+      return `PDF saved: ${pdfPath}`;
+    }
+
+    case 'responsive': {
+      const page = bm.getPage();
+      const prefix = args[0] || `${TEMP_DIR}/browse-responsive`;
+      validateOutputPath(prefix);
+      const viewports = [
+        { name: 'mobile', width: 375, height: 812 },
+        { name: 'tablet', width: 768, height: 1024 },
+        { name: 'desktop', width: 1280, height: 720 },
+      ];
+      const originalViewport = page.viewportSize();
+      const results: string[] = [];
+
+      for (const vp of viewports) {
+        await page.setViewportSize({ width: vp.width, height: vp.height });
+        const path = `${prefix}-${vp.name}.png`;
+        await page.screenshot({ path, fullPage: true });
+        results.push(`${vp.name} (${vp.width}x${vp.height}): ${path}`);
+      }
+
+      // Restore original viewport
+      if (originalViewport) {
+        await page.setViewportSize(originalViewport);
+      }
+
+      return results.join('\n');
+    }
+
+    // ─── Chain ─────────────────────────────────────────
+    case 'chain': {
+      // Read JSON array from args[0] (if provided) or expect it was passed as body
+      const jsonStr = args[0];
+      if (!jsonStr) throw new Error('Usage: echo \'[["goto","url"],["text"]]\' | browse chain');
+
+      let commands: string[][];
+      try {
+        commands = JSON.parse(jsonStr);
+      } catch {
+        throw new Error('Invalid JSON. Expected: [["command", "arg1", "arg2"], ...]');
+      }
+
+      if (!Array.isArray(commands)) throw new Error('Expected JSON array of commands');
+
+      const results: string[] = [];
+      const { handleReadCommand } = await import('./read-commands');
+      const { handleWriteCommand } = await import('./write-commands');
+
+      for (const cmd of commands) {
+        const [name, ...cmdArgs] = cmd;
+        try {
+          let result: string;
+          if (WRITE_COMMANDS.has(name))    result = await handleWriteCommand(name, cmdArgs, bm);
+          else if (READ_COMMANDS.has(name))  result = await handleReadCommand(name, cmdArgs, bm);
+          else if (META_COMMANDS.has(name))  result = await handleMetaCommand(name, cmdArgs, bm, shutdown);
+          else throw new Error(`Unknown command: ${name}`);
+          results.push(`[${name}] ${result}`);
+        } catch (err: any) {
+          results.push(`[${name}] ERROR: ${err.message}`);
+        }
+      }
+
+      return results.join('\n\n');
+    }
+
+    // ─── Diff ──────────────────────────────────────────
+    case 'diff': {
+      const [url1, url2] = args;
+      if (!url1 || !url2) throw new Error('Usage: browse diff <url1> <url2>');
+
+      const page = bm.getPage();
+      await validateNavigationUrl(url1);
+      await page.goto(url1, { waitUntil: 'domcontentloaded', timeout: 15000 });
+      const text1 = await getCleanText(page);
+
+      await validateNavigationUrl(url2);
+      await page.goto(url2, { waitUntil: 'domcontentloaded', timeout: 15000 });
+      const text2 = await getCleanText(page);
+
+      const changes = Diff.diffLines(text1, text2);
+      const output: string[] = [`--- ${url1}`, `+++ ${url2}`, ''];
+
+      for (const part of changes) {
+        const prefix = part.added ? '+' : part.removed ? '-' : ' ';
+        const lines = part.value.split('\n').filter(l => l.length > 0);
+        for (const line of lines) {
+          output.push(`${prefix} ${line}`);
+        }
+      }
+
+      return output.join('\n');
+    }
+
+    // ─── Snapshot ─────────────────────────────────────
+    case 'snapshot': {
+      return await handleSnapshot(args, bm);
+    }
+
+    // ─── Handoff ────────────────────────────────────
+    case 'handoff': {
+      const message = args.join(' ') || 'User takeover requested';
+      return await bm.handoff(message);
+    }
+
+    case 'resume': {
+      bm.resume();
+      // Re-snapshot to capture current page state after human interaction
+      const snapshot = await handleSnapshot(['-i'], bm);
+      return `RESUMED\n${snapshot}`;
+    }
+
+    default:
+      throw new Error(`Unknown meta command: ${command}`);
+  }
+}

package/.agents/skills/gstack/browse/src/platform.ts

@@ -0,0 +1,17 @@
+/**
+ * Cross-platform constants for gstack browse.
+ *
+ * On macOS/Linux: TEMP_DIR = '/tmp', path.sep = '/'  — identical to hardcoded values.
+ * On Windows: TEMP_DIR = os.tmpdir(), path.sep = '\\' — correct Windows behavior.
+ */
+
+import * as os from 'os';
+import * as path from 'path';
+
+export const IS_WINDOWS = process.platform === 'win32';
+export const TEMP_DIR = IS_WINDOWS ? os.tmpdir() : '/tmp';
+
+/** Check if resolvedPath is within dir, using platform-aware separators. */
+export function isPathWithin(resolvedPath: string, dir: string): boolean {
+  return resolvedPath === dir || resolvedPath.startsWith(dir + path.sep);
+}

package/.agents/skills/gstack/browse/src/read-commands.ts

@@ -0,0 +1,335 @@
+/**
+ * Read commands — extract data from pages without side effects
+ *
+ * text, html, links, forms, accessibility, js, eval, css, attrs,
+ * console, network, cookies, storage, perf
+ */
+
+import type { BrowserManager } from './browser-manager';
+import { consoleBuffer, networkBuffer, dialogBuffer } from './buffers';
+import type { Page } from 'playwright';
+import * as fs from 'fs';
+import * as path from 'path';
+import { TEMP_DIR, isPathWithin } from './platform';
+
+/** Detect await keyword, ignoring comments. Accepted risk: await in string literals triggers wrapping (harmless). */
+function hasAwait(code: string): boolean {
+  const stripped = code.replace(/\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '');
+  return /\bawait\b/.test(stripped);
+}
+
+/** Detect whether code needs a block wrapper {…} vs expression wrapper (…) inside an async IIFE. */
+function needsBlockWrapper(code: string): boolean {
+  const trimmed = code.trim();
+  if (trimmed.split('\n').length > 1) return true;
+  if (/\b(const|let|var|function|class|return|throw|if|for|while|switch|try)\b/.test(trimmed)) return true;
+  if (trimmed.includes(';')) return true;
+  return false;
+}
+
+/** Wrap code for page.evaluate(), using async IIFE with block or expression body as needed. */
+function wrapForEvaluate(code: string): string {
+  if (!hasAwait(code)) return code;
+  const trimmed = code.trim();
+  return needsBlockWrapper(trimmed)
+    ? `(async()=>{\n${code}\n})()`
+    : `(async()=>(${trimmed}))()`;
+}
+
+// Security: Path validation to prevent path traversal attacks
+const SAFE_DIRECTORIES = [TEMP_DIR, process.cwd()];
+
+export function validateReadPath(filePath: string): void {
+  if (path.isAbsolute(filePath)) {
+    const resolved = path.resolve(filePath);
+    const isSafe = SAFE_DIRECTORIES.some(dir => isPathWithin(resolved, dir));
+    if (!isSafe) {
+      throw new Error(`Absolute path must be within: ${SAFE_DIRECTORIES.join(', ')}`);
+    }
+  }
+  const normalized = path.normalize(filePath);
+  if (normalized.includes('..')) {
+    throw new Error('Path traversal sequences (..) are not allowed');
+  }
+}
+
+/**
+ * Extract clean text from a page (strips script/style/noscript/svg).
+ * Exported for DRY reuse in meta-commands (diff).
+ */
+export async function getCleanText(page: Page): Promise<string> {
+  return await page.evaluate(() => {
+    const body = document.body;
+    if (!body) return '';
+    const clone = body.cloneNode(true) as HTMLElement;
+    clone.querySelectorAll('script, style, noscript, svg').forEach(el => el.remove());
+    return clone.innerText
+      .split('\n')
+      .map(line => line.trim())
+      .filter(line => line.length > 0)
+      .join('\n');
+  });
+}
+
+export async function handleReadCommand(
+  command: string,
+  args: string[],
+  bm: BrowserManager
+): Promise<string> {
+  const page = bm.getPage();
+
+  switch (command) {
+    case 'text': {
+      return await getCleanText(page);
+    }
+
+    case 'html': {
+      const selector = args[0];
+      if (selector) {
+        const resolved = await bm.resolveRef(selector);
+        if ('locator' in resolved) {
+          return await resolved.locator.innerHTML({ timeout: 5000 });
+        }
+        return await page.innerHTML(resolved.selector);
+      }
+      return await page.content();
+    }
+
+    case 'links': {
+      const links = await page.evaluate(() =>
+        [...document.querySelectorAll('a[href]')].map(a => ({
+          text: a.textContent?.trim().slice(0, 120) || '',
+          href: (a as HTMLAnchorElement).href,
+        })).filter(l => l.text && l.href)
+      );
+      return links.map(l => `${l.text} → ${l.href}`).join('\n');
+    }
+
+    case 'forms': {
+      const forms = await page.evaluate(() => {
+        return [...document.querySelectorAll('form')].map((form, i) => {
+          const fields = [...form.querySelectorAll('input, select, textarea')].map(el => {
+            const input = el as HTMLInputElement;
+            return {
+              tag: el.tagName.toLowerCase(),
+              type: input.type || undefined,
+              name: input.name || undefined,
+              id: input.id || undefined,
+              placeholder: input.placeholder || undefined,
+              required: input.required || undefined,
+              value: input.type === 'password' ? '[redacted]' : (input.value || undefined),
+              options: el.tagName === 'SELECT'
+                ? [...(el as HTMLSelectElement).options].map(o => ({ value: o.value, text: o.text }))
+                : undefined,
+            };
+          });
+          return {
+            index: i,
+            action: form.action || undefined,
+            method: form.method || 'get',
+            id: form.id || undefined,
+            fields,
+          };
+        });
+      });
+      return JSON.stringify(forms, null, 2);
+    }
+
+    case 'accessibility': {
+      const snapshot = await page.locator("body").ariaSnapshot();
+      return snapshot;
+    }
+
+    case 'js': {
+      const expr = args[0];
+      if (!expr) throw new Error('Usage: browse js <expression>');
+      const wrapped = wrapForEvaluate(expr);
+      const result = await page.evaluate(wrapped);
+      return typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result ?? '');
+    }
+
+    case 'eval': {
+      const filePath = args[0];
+      if (!filePath) throw new Error('Usage: browse eval <js-file>');
+      validateReadPath(filePath);
+      if (!fs.existsSync(filePath)) throw new Error(`File not found: ${filePath}`);
+      const code = fs.readFileSync(filePath, 'utf-8');
+      const wrapped = wrapForEvaluate(code);
+      const result = await page.evaluate(wrapped);
+      return typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result ?? '');
+    }
+
+    case 'css': {
+      const [selector, property] = args;
+      if (!selector || !property) throw new Error('Usage: browse css <selector> <property>');
+      const resolved = await bm.resolveRef(selector);
+      if ('locator' in resolved) {
+        const value = await resolved.locator.evaluate(
+          (el, prop) => getComputedStyle(el).getPropertyValue(prop),
+          property
+        );
+        return value;
+      }
+      const value = await page.evaluate(
+        ([sel, prop]) => {
+          const el = document.querySelector(sel);
+          if (!el) return `Element not found: ${sel}`;
+          return getComputedStyle(el).getPropertyValue(prop);
+        },
+        [resolved.selector, property]
+      );
+      return value;
+    }
+
+    case 'attrs': {
+      const selector = args[0];
+      if (!selector) throw new Error('Usage: browse attrs <selector>');
+      const resolved = await bm.resolveRef(selector);
+      if ('locator' in resolved) {
+        const attrs = await resolved.locator.evaluate((el) => {
+          const result: Record<string, string> = {};
+          for (const attr of el.attributes) {
+            result[attr.name] = attr.value;
+          }
+          return result;
+        });
+        return JSON.stringify(attrs, null, 2);
+      }
+      const attrs = await page.evaluate((sel) => {
+        const el = document.querySelector(sel);
+        if (!el) return `Element not found: ${sel}`;
+        const result: Record<string, string> = {};
+        for (const attr of el.attributes) {
+          result[attr.name] = attr.value;
+        }
+        return result;
+      }, resolved.selector);
+      return typeof attrs === 'string' ? attrs : JSON.stringify(attrs, null, 2);
+    }
+
+    case 'console': {
+      if (args[0] === '--clear') {
+        consoleBuffer.clear();
+        return 'Console buffer cleared.';
+      }
+      const entries = args[0] === '--errors'
+        ? consoleBuffer.toArray().filter(e => e.level === 'error' || e.level === 'warning')
+        : consoleBuffer.toArray();
+      if (entries.length === 0) return args[0] === '--errors' ? '(no console errors)' : '(no console messages)';
+      return entries.map(e =>
+        `[${new Date(e.timestamp).toISOString()}] [${e.level}] ${e.text}`
+      ).join('\n');
+    }
+
+    case 'network': {
+      if (args[0] === '--clear') {
+        networkBuffer.clear();
+        return 'Network buffer cleared.';
+      }
+      if (networkBuffer.length === 0) return '(no network requests)';
+      return networkBuffer.toArray().map(e =>
+        `${e.method} ${e.url} → ${e.status || 'pending'} (${e.duration || '?'}ms, ${e.size || '?'}B)`
+      ).join('\n');
+    }
+
+    case 'dialog': {
+      if (args[0] === '--clear') {
+        dialogBuffer.clear();
+        return 'Dialog buffer cleared.';
+      }
+      if (dialogBuffer.length === 0) return '(no dialogs captured)';
+      return dialogBuffer.toArray().map(e =>
+        `[${new Date(e.timestamp).toISOString()}] [${e.type}] "${e.message}" → ${e.action}${e.response ? ` "${e.response}"` : ''}`
+      ).join('\n');
+    }
+
+    case 'is': {
+      const property = args[0];
+      const selector = args[1];
+      if (!property || !selector) throw new Error('Usage: browse is <property> <selector>\nProperties: visible, hidden, enabled, disabled, checked, editable, focused');
+
+      const resolved = await bm.resolveRef(selector);
+      let locator;
+      if ('locator' in resolved) {
+        locator = resolved.locator;
+      } else {
+        locator = page.locator(resolved.selector);
+      }
+
+      switch (property) {
+        case 'visible':  return String(await locator.isVisible());
+        case 'hidden':   return String(await locator.isHidden());
+        case 'enabled':  return String(await locator.isEnabled());
+        case 'disabled': return String(await locator.isDisabled());
+        case 'checked':  return String(await locator.isChecked());
+        case 'editable': return String(await locator.isEditable());
+        case 'focused': {
+          const isFocused = await locator.evaluate(
+            (el) => el === document.activeElement
+          );
+          return String(isFocused);
+        }
+        default:
+          throw new Error(`Unknown property: ${property}. Use: visible, hidden, enabled, disabled, checked, editable, focused`);
+      }
+    }
+
+    case 'cookies': {
+      const cookies = await page.context().cookies();
+      return JSON.stringify(cookies, null, 2);
+    }
+
+    case 'storage': {
+      if (args[0] === 'set' && args[1]) {
+        const key = args[1];
+        const value = args[2] || '';
+        await page.evaluate(([k, v]) => localStorage.setItem(k, v), [key, value]);
+        return `Set localStorage["${key}"]`;
+      }
+      const storage = await page.evaluate(() => ({
+        localStorage: { ...localStorage },
+        sessionStorage: { ...sessionStorage },
+      }));
+      // Redact values that look like secrets (tokens, keys, passwords, JWTs)
+      const SENSITIVE_KEY = /(^|[_.-])(token|secret|key|password|credential|auth|jwt|session|csrf)($|[_.-])|api.?key/i;
+      const SENSITIVE_VALUE = /^(eyJ|sk-|sk_live_|sk_test_|pk_live_|pk_test_|rk_live_|sk-ant-|ghp_|gho_|github_pat_|xox[bpsa]-|AKIA[A-Z0-9]{16}|AIza|SG\.|Bearer\s|sbp_)/;
+      const redacted = JSON.parse(JSON.stringify(storage));
+      for (const storeType of ['localStorage', 'sessionStorage'] as const) {
+        const store = redacted[storeType];
+        if (!store) continue;
+        for (const [key, value] of Object.entries(store)) {
+          if (typeof value !== 'string') continue;
+          if (SENSITIVE_KEY.test(key) || SENSITIVE_VALUE.test(value)) {
+            store[key] = `[REDACTED — ${value.length} chars]`;
+          }
+        }
+      }
+      return JSON.stringify(redacted, null, 2);
+    }
+
+    case 'perf': {
+      const timings = await page.evaluate(() => {
+        const nav = performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming;
+        if (!nav) return 'No navigation timing data available.';
+        return {
+          dns: Math.round(nav.domainLookupEnd - nav.domainLookupStart),
+          tcp: Math.round(nav.connectEnd - nav.connectStart),
+          ssl: Math.round(nav.secureConnectionStart > 0 ? nav.connectEnd - nav.secureConnectionStart : 0),
+          ttfb: Math.round(nav.responseStart - nav.requestStart),
+          download: Math.round(nav.responseEnd - nav.responseStart),
+          domParse: Math.round(nav.domInteractive - nav.responseEnd),
+          domReady: Math.round(nav.domContentLoadedEventEnd - nav.startTime),
+          load: Math.round(nav.loadEventEnd - nav.startTime),
+          total: Math.round(nav.loadEventEnd - nav.startTime),
+        };
+      });
+      if (typeof timings === 'string') return timings;
+      return Object.entries(timings)
+        .map(([k, v]) => `${k.padEnd(12)} ${v}ms`)
+        .join('\n');
+    }
+
+    default:
+      throw new Error(`Unknown read command: ${command}`);
+  }
+}