Skip to content

olaafrossi/FoamPilot / .claude/skills/browse

browse

Flagged

Fast headless browser for QA testing and site dogfooding. Navigate any URL, interact with elements, verify page state, diff before/after actions, take annotated screenshots, check responsive layouts, test forms and uploads, handle dialogs, and assert element states. ~100ms per command. Use when you need to test a feature, verify a deployment, dogfood a user flow, or file a bug with evidence. Use when asked to "open in browser", "test the site", "take a screenshot", or "dogfood this".

FileKindSize
SKILL.mdskill md22.5 KB
SKILL.md.tmplother4.1 KB
scripts/build-node-server.shscript1.9 KB
src/activity.tsscript6.4 KB
src/browser-manager.tsscript33.3 KB
src/buffers.tsscript4.2 KB
src/bun-polyfill.cjsscript2.9 KB
src/cli.tsscript25.0 KB
src/commands.tsscript9.0 KB
src/config.tsscript4.6 KB
src/cookie-import-browser.tsscript22.5 KB
src/cookie-picker-routes.tsscript8.5 KB
src/cookie-picker-ui.tsscript21.6 KB
src/find-browse.tsscript1.7 KB
src/meta-commands.tsscript20.6 KB
src/platform.tsscript634 B
src/read-commands.tsscript13.4 KB
src/server.tsscript47.9 KB
src/sidebar-agent.tsscript10.0 KB
src/sidebar-utils.tsscript629 B
src/snapshot.tsscript15.1 KB
src/url-validation.tsscript3.5 KB
src/write-commands.tsscript14.1 KB
test/activity.test.tsscript4.4 KB
test/adversarial-security.test.tsscript1.2 KB
test/browser-manager-unit.test.tsscript677 B
test/bun-polyfill.test.tsscript2.9 KB
test/commands.test.tsscript76.7 KB
test/compare-board.test.tsscript11.3 KB
test/config.test.tsscript13.0 KB
test/cookie-import-browser.test.tsscript20.8 KB
test/cookie-picker-routes.test.tsscript9.5 KB
test/file-drop.test.tsscript10.0 KB
test/find-browse.test.tsscript2.0 KB
test/findport.test.tsscript6.2 KB
test/fixtures/basic.htmlother914 B
test/fixtures/cursor-interactive.htmlother883 B
test/fixtures/dialog.htmlother603 B
test/fixtures/empty.htmlother43 B
test/fixtures/forms.htmlother1.8 KB
test/fixtures/iframe.htmlother852 B
test/fixtures/network-idle.htmlother974 B
test/fixtures/qa-eval-checkout.htmlother4.2 KB
test/fixtures/qa-eval-spa.htmlother3.2 KB
test/fixtures/qa-eval.htmlother1.7 KB
test/fixtures/responsive.htmlother1.4 KB
test/fixtures/snapshot.htmlother1.5 KB
test/fixtures/spa.htmlother638 B
test/fixtures/states.htmlother567 B
test/fixtures/upload.htmlother849 B
test/gstack-config.test.tsscript5.2 KB
test/gstack-update-check.test.tsscript21.4 KB
test/handoff.test.tsscript8.1 KB
test/path-validation.test.tsscript3.3 KB
test/platform.test.tsscript1.0 KB
test/server-auth.test.tsscript3.0 KB
test/sidebar-agent-roundtrip.test.tsscript7.5 KB
test/sidebar-agent.test.tsscript6.8 KB
test/sidebar-integration.test.tsscript9.8 KB
test/sidebar-security.test.tsscript4.2 KB
test/sidebar-unit.test.tsscript3.3 KB
test/snapshot.test.tsscript19.7 KB
test/state-ttl.test.tsscript1.3 KB
test/test-server.tsscript1.7 KB
test/url-validation.test.tsscript2.8 KB
test/watch.test.tsscript4.0 KB

src/config.ts

View on GitHub
/**
 * Shared config for browse CLI + server.
 *
 * Resolution:
 *   1. BROWSE_STATE_FILE env → derive stateDir from parent
 *   2. git rev-parse --show-toplevel → projectDir/.gstack/
 *   3. process.cwd() fallback (non-git environments)
 *
 * The CLI computes the config and passes BROWSE_STATE_FILE to the
 * spawned server. The server derives all paths from that env var.
 */

import * as fs from 'fs';
import * as path from 'path';

export interface BrowseConfig {
  projectDir: string;
  stateDir: string;
  stateFile: string;
  consoleLog: string;
  networkLog: string;
  dialogLog: string;
}

/**
 * Detect the git repository root, or null if not in a repo / git unavailable.
 */
export function getGitRoot(): string | null {
  try {
    const proc = Bun.spawnSync(['git', 'rev-parse', '--show-toplevel'], {
      stdout: 'pipe',
      stderr: 'pipe',
      timeout: 2_000, // Don't hang if .git is broken
    });
    if (proc.exitCode !== 0) return null;
    return proc.stdout.toString().trim() || null;
  } catch {
    return null;
  }
}

/**
 * Resolve all browse config paths.
 *
 * If BROWSE_STATE_FILE is set (e.g. by CLI when spawning server, or by
 * tests for isolation), all paths are derived from it. Otherwise, the
 * project root is detected via git or cwd.
 */
export function resolveConfig(
  env: Record<string, string | undefined> = process.env,
): BrowseConfig {
  let stateFile: string;
  let stateDir: string;
  let projectDir: string;

  if (env.BROWSE_STATE_FILE) {
    stateFile = env.BROWSE_STATE_FILE;
    stateDir = path.dirname(stateFile);
    projectDir = path.dirname(stateDir); // parent of .gstack/
  } else {
    projectDir = getGitRoot() || process.cwd();
    stateDir = path.join(projectDir, '.gstack');
    stateFile = path.join(stateDir, 'browse.json');
  }

  return {
    projectDir,
    stateDir,
    stateFile,
    consoleLog: path.join(stateDir, 'browse-console.log'),
    networkLog: path.join(stateDir, 'browse-network.log'),
    dialogLog: path.join(stateDir, 'browse-dialog.log'),
  };
}

/**
 * Create the .gstack/ state directory if it doesn't exist.
 * Throws with a clear message on permission errors.
 */
export function ensureStateDir(config: BrowseConfig): void {
  try {
    fs.mkdirSync(config.stateDir, { recursive: true });
  } catch (err: any) {
    if (err.code === 'EACCES') {
      throw new Error(`Cannot create state directory ${config.stateDir}: permission denied`);
    }
    if (err.code === 'ENOTDIR') {
      throw new Error(`Cannot create state directory ${config.stateDir}: a file exists at that path`);
    }
    throw err;
  }

  // Ensure .gstack/ is in the project's .gitignore
  const gitignorePath = path.join(config.projectDir, '.gitignore');
  try {
    const content = fs.readFileSync(gitignorePath, 'utf-8');
    if (!content.match(/^\.gstack\/?$/m)) {
      const separator = content.endsWith('\n') ? '' : '\n';
      fs.appendFileSync(gitignorePath, `${separator}.gstack/\n`);
    }
  } catch (err: any) {
    if (err.code !== 'ENOENT') {
      // Write warning to server log (visible even in daemon mode)
      const logPath = path.join(config.stateDir, 'browse-server.log');
      try {
        fs.appendFileSync(logPath, `[${new Date().toISOString()}] Warning: could not update .gitignore at ${gitignorePath}: ${err.message}\n`);
      } catch {
        // stateDir write failed too — nothing more we can do
      }
    }
    // ENOENT (no .gitignore) — skip silently
  }
}

/**
 * Derive a slug from the git remote origin URL (owner-repo format).
 * Falls back to the directory basename if no remote is configured.
 */
export function getRemoteSlug(): string {
  try {
    const proc = Bun.spawnSync(['git', 'remote', 'get-url', 'origin'], {
      stdout: 'pipe',
      stderr: 'pipe',
      timeout: 2_000,
    });
    if (proc.exitCode !== 0) throw new Error('no remote');
    const url = proc.stdout.toString().trim();
    // SSH:   git@github.com:owner/repo.git → owner-repo
    // HTTPS: https://github.com/owner/repo.git → owner-repo
    const match = url.match(/[:/]([^/]+)\/([^/]+?)(?:\.git)?$/);
    if (match) return `${match[1]}-${match[2]}`;
    throw new Error('unparseable');
  } catch {
    const root = getGitRoot();
    return path.basename(root || process.cwd());
  }
}

/**
 * Read the binary version (git SHA) from browse/dist/.version.
 * Returns null if the file doesn't exist or can't be read.
 */
export function readVersionHash(execPath: string = process.execPath): string | null {
  try {
    const versionFile = path.resolve(path.dirname(execPath), '.version');
    return fs.readFileSync(versionFile, 'utf-8').trim() || null;
  } catch {
    return null;
  }
}
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall