Browse

#!/bin/bash
# Shim: delegates to compiled find-browse binary, falls back to basic discovery.
# The compiled binary handles git root detection for workspace-local installs.
DIR="$(cd "$(dirname "$0")/.." && pwd)/dist"
if test -x "$DIR/find-browse"; then
  exec "$DIR/find-browse" "$@"
fi
# Fallback: basic discovery with priority chain
ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
for MARKER in .codex .agents .claude; do
  if [ -n "$ROOT" ] && test -x "$ROOT/$MARKER/skills/gstack/browse/dist/browse"; then
    echo "$ROOT/$MARKER/skills/gstack/browse/dist/browse"
    exit 0
  fi
  if test -x "$HOME/$MARKER/skills/gstack/browse/dist/browse"; then
    echo "$HOME/$MARKER/skills/gstack/browse/dist/browse"
    exit 0
  fi
done
echo "ERROR: browse binary not found. Run: cd <skill-dir> && ./setup" >&2
exit 1

#!/usr/bin/env bash
# Output the remote slug (owner-repo) for the current git repo.
# Used by SKILL.md files to derive project-specific paths in ~/.gstack/projects/.
set -e
URL=$(git remote get-url origin 2>/dev/null || true)
if [ -n "$URL" ]; then
  # Strip trailing .git if present, then extract owner/repo
  URL="${URL%.git}"
  # Handle both SSH (git@host:owner/repo) and HTTPS (https://host/owner/repo)
  OWNER_REPO=$(echo "$URL" | sed -E 's#.*[:/]([^/]+)/([^/]+)$#\1-\2#')
  echo "$OWNER_REPO"
else
  basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
fi

#!/usr/bin/env bash
# Build a Node.js-compatible server bundle for Windows.
#
# On Windows, Bun can't launch or connect to Playwright's Chromium
# (oven-sh/bun#4253, #9911). This script produces a server bundle
# that runs under Node.js with Bun API polyfills.

set -e

GSTACK_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
SRC_DIR="$GSTACK_DIR/browse/src"
DIST_DIR="$GSTACK_DIR/browse/dist"

echo "Building Node-compatible server bundle..."

# Step 1: Transpile server.ts to a single .mjs bundle (externalize runtime deps)
#
# Externalize packages with native addons, dynamic imports, or runtime resolution.
# If you add a new dependency that uses `await import()` or has a .node addon,
# add it here. Otherwise `bun build --outfile` will fail with
# "cannot write multiple output files without an output directory".
bun build "$SRC_DIR/server.ts" \
  --target=node \
  --outfile "$DIST_DIR/server-node.mjs" \
  --external playwright \
  --external playwright-core \
  --external diff \
  --external "bun:sqlite" \
  --external "@ngrok/ngrok"

# Step 2: Post-process
# Replace import.meta.dir with a resolvable reference
perl -pi -e 's/import\.meta\.dir/__browseNodeSrcDir/g' "$DIST_DIR/server-node.mjs"
# Stub out bun:sqlite (macOS-only cookie import, not needed on Windows)
perl -pi -e 's|import { Database } from "bun:sqlite";|const Database = null; // bun:sqlite stubbed on Node|g' "$DIST_DIR/server-node.mjs"

# Step 3: Create the final file with polyfill header injected after the first line
{
  head -1 "$DIST_DIR/server-node.mjs"
  echo '// ── Windows Node.js compatibility (auto-generated) ──'
  echo 'import { fileURLToPath as _ftp } from "node:url";'
  echo 'import { dirname as _dn } from "node:path";'
  echo 'const __browseNodeSrcDir = _dn(_dn(_ftp(import.meta.url))) + "/src";'
  echo '{ const _r = createRequire(import.meta.url); _r("./bun-polyfill.cjs"); }'
  echo '// ── end compatibility ──'
  tail -n +2 "$DIST_DIR/server-node.mjs"
} > "$DIST_DIR/server-node.tmp.mjs"

mv "$DIST_DIR/server-node.tmp.mjs" "$DIST_DIR/server-node.mjs"

# Step 4: Copy polyfill to dist/
cp "$SRC_DIR/bun-polyfill.cjs" "$DIST_DIR/bun-polyfill.cjs"

echo "Node server bundle ready: $DIST_DIR/server-node.mjs"

---
name: browse
preamble-tier: 1
version: 1.1.0
description: |
  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". (gstack)
triggers:
  - browse a page
  - headless browser
  - take page screenshot
allowed-tools:
  - Bash
  - Read
  - AskUserQuestion

---

{{PREAMBLE}}

# browse: QA Testing & Dogfooding

Persistent headless Chromium. First call auto-starts (~3s), then ~100ms per command.
State persists between calls (cookies, tabs, login sessions).

{{BROWSE_SETUP}}

## Core QA Patterns

### 1. Verify a page loads correctly
```bash
$B goto https://yourapp.com
$B text                          # content loads?
$B console                       # JS errors?
$B network                       # failed requests?
$B is visible ".main-content"    # key elements present?
```

### 2. Test a user flow
```bash
$B goto https://app.com/login
$B snapshot -i                   # see all interactive elements
$B fill @e3 "user@test.com"
$B fill @e4 "password"
$B click @e5                     # submit
$B snapshot -D                   # diff: what changed after submit?
$B is visible ".dashboard"       # success state present?
```

### 3. Verify an action worked
```bash
$B snapshot                      # baseline
$B click @e3                     # do something
$B snapshot -D                   # unified diff shows exactly what changed
```

### 4. Visual evidence for bug reports
```bash
$B snapshot -i -a -o /tmp/annotated.png   # labeled screenshot
$B screenshot /tmp/bug.png                # plain screenshot
$B console                                # error log
```

### 5. Find all clickable elements (including non-ARIA)
```bash
$B snapshot -C                   # finds divs with cursor:pointer, onclick, tabindex
$B click @c1                     # interact with them
```

### 6. Assert element states
```bash
$B is visible ".modal"
$B is enabled "#submit-btn"
$B is disabled "#submit-btn"
$B is checked "#agree-checkbox"
$B is editable "#name-field"
$B is focused "#search-input"
$B js "document.body.textContent.includes('Success')"
```

### 7. Test responsive layouts
```bash
$B responsive /tmp/layout        # mobile + tablet + desktop screenshots
$B viewport 375x812              # or set specific viewport
$B screenshot /tmp/mobile.png
```

### 8. Test file uploads
```bash
$B upload "#file-input" /path/to/file.pdf
$B is visible ".upload-success"
```

### 9. Test dialogs
```bash
$B dialog-accept "yes"           # set up handler
$B click "#delete-button"        # trigger dialog
$B dialog                        # see what appeared
$B snapshot -D                   # verify deletion happened
```

### 10. Compare environments
```bash
$B diff https://staging.app.com https://prod.app.com
```

### 11. Show screenshots to the user
After `$B screenshot`, `$B snapshot -a -o`, or `$B responsive`, always use the Read tool on the output PNG(s) so the user can see them. Without this, screenshots are invisible.

### 12. Render local HTML (no HTTP server needed)
Two paths, pick the cleaner one:
```bash
# HTML file on disk → goto file:// (absolute, or cwd-relative)
$B goto file:///tmp/report.html
$B goto file://./docs/page.html        # cwd-relative
$B goto file://~/Documents/page.html   # home-relative

# HTML generated in memory → load-html reads the file into setContent
echo '<div class="tweet">hello</div>' > /tmp/tweet.html
$B load-html /tmp/tweet.html
```

`goto file://...` is usually cleaner (URL is saved in state, relative asset URLs resolve against the file's dir, scale changes replay naturally). `load-html` uses `page.setContent()` — URL stays `about:blank`, but the content survives `viewport --scale` via in-memory replay. Both are scoped to files under cwd or `$TMPDIR`.

### 13. Retina screenshots (deviceScaleFactor)
```bash
$B viewport 480x600 --scale 2       # 2x deviceScaleFactor
$B load-html /tmp/tweet.html        # or: $B goto file://./tweet.html
$B screenshot /tmp/out.png --selector .tweet-card
# → /tmp/out.png is 2x the pixel dimensions of the element
```
Scale must be 1-3 (gstack policy cap). Changing `--scale` recreates the browser context; refs from `snapshot` are invalidated (rerun `snapshot`), but `load-html` content is replayed automatically. Not supported in headed mode.

### 14. Offline render mode (rasterize your own HTML/JSON, zero network)

This is the blessed path for "I just want to turn my own local HTML or JSON into a
PNG/PDF/bytes on disk" — Excalidraw diagrams, tweet/quote cards, og-images,
report rasterization. It is **plain headless, shared Chromium, no proxy, no Xvfb,
no anti-bot stealth**. Default `$B` is already exactly this; you do not pass
`--headed` or `--proxy`. One Chromium per box, shared by every skill — **do not
`npm i puppeteer` and ship a second browser** (see the note under the cheatsheet).

Two output shapes, pick by what you have:

**A) Visual output → `screenshot --selector` (preferred).** If the thing you want
is a picture of something on the page, screenshot it. The PNG is written from the
browser process straight to disk — the image bytes never cross the CDP wire.

```bash
echo '<div id="card" style="width:400px;height:200px;background:#1da1f2;color:#fff;padding:20px">hi</div>' > /tmp/card.html
$B viewport 480x600 --scale 2
$B load-html /tmp/card.html
$B screenshot /tmp/card.png --selector '#card'   # disk path — no megabytes over CDP
```
(Use the disk path, NOT `screenshot --base64` — base64 serializes the bytes back
through the command channel, which is the cost you're trying to avoid.)

**B) Bytes a function returns → `js --out` / `eval --out`.** When a library hands
you the result as a return value (a base64 data URL, a blob, computed JSON) rather
than painting a stable element — e.g. Excalidraw's export function returns a PNG
data URL — write the evaluate result straight to disk. `--out` decodes a
`data:*;base64,...` result to raw bytes automatically (pass `--raw` to write the
literal string). The payload is written by the daemon and never serialized back
out to the CLI/stdout.

```bash
# Load the render bundle, signal readiness, then render-to-file.
$B load-html /tmp/excalidraw-export.html        # bundle sets window.__render + a #done flag
$B wait '#done'                                  # deterministic ready handshake
$B js "window.__render(SCENE_JSON)" --out /tmp/diagram.png   # data URL → decoded PNG on disk
```

`--out` is a WRITE: it needs the `write` scope and is never allowed over the
pair-agent tunnel (a remote agent can't write to your disk). Parent directories
are created; malformed base64 errors instead of writing corrupt bytes. Pick A when
you can (no CDP transfer at all); reach for B only when the bytes come back as a
return value.

## Puppeteer → browse cheatsheet

Migrating from Puppeteer? Here's the 1:1 mapping for the core workflow:

| Puppeteer | browse |
|---|---|
| `await page.goto(url)` | `$B goto <url>` |
| `await page.setContent(html)` | `$B load-html <file>` (or `$B goto file://<abs>`) |
| `await page.setViewport({width, height})` | `$B viewport WxH` |
| `await page.setViewport({width, height, deviceScaleFactor: 2})` | `$B viewport WxH --scale 2` |
| `await (await page.$('.x')).screenshot({path})` | `$B screenshot <path> --selector .x` |
| `await page.screenshot({fullPage: true, path})` | `$B screenshot <path>` (full page default) |
| `await page.screenshot({clip: {x, y, w, h}, path})` | `$B screenshot <path> --clip x,y,w,h` |
| `const r = await page.evaluate(fn)` | `$B js "<expr>"` (result to stdout) |
| `fs.writeFileSync(out, Buffer.from(dataUrl.split(',')[1],'base64'))` | `$B js "<expr>" --out <file>` (data URL auto-decoded) |

Worked example (the tweet-renderer flow — Puppeteer → browse):

```bash
# Generate HTML in memory, render at 2x scale, screenshot the tweet card.
echo '<div class="tweet-card" style="width:400px;height:200px;background:#1da1f2;color:white;padding:20px">hello</div>' > /tmp/tweet.html
$B viewport 480x600 --scale 2
$B load-html /tmp/tweet.html
$B screenshot /tmp/out.png --selector .tweet-card
# /tmp/out.png is 800x400 px, crisp (2x deviceScaleFactor).
```

Aliases: typing `setcontent` or `set-content` routes to `load-html` automatically. Typing a typo (`load-htm`) returns `Did you mean 'load-html'?`.

**Don't bundle your own puppeteer/Chromium.** `browse` is the one shared Chromium
per box. Skills that need to rasterize local HTML/JSON (diagrams, cards, og-images)
should route through `browse` — `screenshot --selector` for visual output,
`load-html` + `js --out` for bytes a function returns — instead of
`npm i puppeteer` and downloading a second Chromium that drifts out of version sync.
One install to pin, one daemon's lifecycle to manage.

## User Handoff

When you hit something you can't handle in headless mode (CAPTCHA, complex auth, multi-factor
login), hand off to the user:

```bash
# 1. Open a visible Chrome at the current page
$B handoff "Stuck on CAPTCHA at login page"

# 2. Tell the user what happened (via AskUserQuestion)
#    "I've opened Chrome at the login page. Please solve the CAPTCHA
#     and let me know when you're done."

# 3. When user says "done", re-snapshot and continue
$B resume
```

**When to use handoff:**
- CAPTCHAs or bot detection
- Multi-factor authentication (SMS, authenticator app)
- OAuth flows that require user interaction
- Complex interactions the AI can't handle after 3 attempts

The browser preserves all state (cookies, localStorage, tabs) across the handoff.
After `resume`, you get a fresh snapshot of wherever the user left off.

## Headed Mode + Proxy + Anti-Bot Sites

For sites that block headless browsers, fingerprint Playwright defaults, or require routing through an authenticated SOCKS5 proxy (residential VPN, etc.), browse exposes three coordinated flags:

```bash
# Headed mode — visible Chromium window. Auto-spawns Xvfb on Linux
# containers without DISPLAY (no extra setup needed on Debian/Ubuntu).
browse --headed goto https://example.com

# SOCKS5 with auth (Chromium can't prompt for SOCKS5 creds itself —
# browse runs a local 127.0.0.1 bridge that handles the auth handshake).
browse --proxy socks5://user:pass@residential.proxy.host:1080 goto https://example.com

# HTTP/HTTPS proxy (passes through to Chromium directly):
browse --proxy http://corp-proxy:3128 goto https://example.com

# Browser-triggered file download (Content-Disposition, redirect chain,
# anti-bot CDN — falls back from page.request.fetch() to browser native
# download handler):
browse download "https://protected.example.com/file" /tmp/file.bin --navigate

# Combined: headed + proxy + navigate-download
browse --headed --proxy socks5://user:pass@host:1080 \
  download "https://protected.example.com/file" /tmp/file.bin --navigate
```

**Credential policy.** Pass creds via either the URL (`socks5://user:pass@host`) OR the env vars `BROWSE_PROXY_USER` and `BROWSE_PROXY_PASS` — never both. Browse refuses with a clear hint when both are set, because silent override creates "works on my machine" debugging traps.

**Daemon discipline.** Browse runs as a long-lived daemon. `--proxy` and `--headed` change daemon-startup config, so they only apply on a fresh daemon. If a daemon is already running with different config, browse refuses and tells you to `browse disconnect` first. No silent restart that would drop tab state, cookies, or logged-in sessions.

**Stealth.** When `--headed` or `--proxy` are set, browse masks `navigator.webdriver` (the obvious automation tell) via Chromium's `--disable-blink-features=AutomationControlled` plus a small init script. We do NOT fake `navigator.plugins`, `navigator.languages`, or `window.chrome` — modern fingerprinters check those for consistency, and synthesizing fixed values can flag MORE bot-like, not less.

**Container support.** `--headed` on Linux without `DISPLAY` automatically picks a free X display (`:99`, `:100`, ...) and spawns Xvfb. Cleanup on `browse disconnect` validates the recorded PID's `/proc/<pid>/cmdline` matches `Xvfb` AND start-time matches before sending any signal — no PID-reuse footguns. Standard Debian/Ubuntu containers work out of the box; minimal images (alpine, distroless) may also need fonts/dbus/gtk libs for headed Chromium to render.

**Failure modes.** SOCKS5 upstream rejected or unreachable → fail-fast at startup with a redacted error after 3 retries (5s budget). Mid-stream upstream drop → browse kills the affected client connection only; no transport retries (which could corrupt browser traffic). Mismatched daemon config → exit 1 with a `browse disconnect` hint.

## Snapshot Flags

{{SNAPSHOT_FLAGS}}

## CSS Inspector & Style Modification

### Inspect element CSS
```bash
$B inspect .header              # full CSS cascade for selector
$B inspect                      # latest picked element from sidebar
$B inspect --all                # include user-agent stylesheet rules
$B inspect --history            # show modification history
```

### Modify styles live
```bash
$B style .header background-color #1a1a1a   # modify CSS property
$B style --undo                              # revert last change
$B style --undo 2                            # revert specific change
```

### Clean screenshots
```bash
$B cleanup --all                 # remove ads, cookies, sticky, social
$B cleanup --ads --cookies       # selective cleanup
$B prettyscreenshot --cleanup --scroll-to ".pricing" --width 1440 ~/Desktop/hero.png
```

## Full Command List

{{COMMAND_REFERENCE}}

/**
 * Activity streaming — real-time feed of browse commands for the Chrome extension Side Panel
 *
 * Architecture:
 *   handleCommand() ──► emitActivity(command_start)
 *                   ──► emitActivity(command_end)
 *   wirePageEvents() ──► emitActivity(navigation)
 *
 *   GET /activity/stream?after=ID ──► SSE via ReadableStream
 *   GET /activity/history?limit=N ──► REST fallback
 *
 * Privacy: filterArgs() redacts passwords, auth tokens, and sensitive query params.
 * Backpressure: subscribers notified via queueMicrotask (never blocks command path).
 * Gap detection: client sends ?after=ID, server detects if ring buffer overflowed.
 */

import { CircularBuffer } from './buffers';

// ─── Types ──────────────────────────────────────────────────────

export interface ActivityEntry {
  id: number;
  timestamp: number;
  type: 'command_start' | 'command_end' | 'navigation' | 'error';
  command?: string;
  args?: string[];
  url?: string;
  duration?: number;
  status?: 'ok' | 'error';
  error?: string;
  result?: string;
  tabs?: number;
  mode?: string;
  clientId?: string;
}

// ─── Buffer & Subscribers ───────────────────────────────────────

const BUFFER_CAPACITY = 1000;
const activityBuffer = new CircularBuffer<ActivityEntry>(BUFFER_CAPACITY);
let nextId = 1;

type ActivitySubscriber = (entry: ActivityEntry) => void;
const subscribers = new Set<ActivitySubscriber>();

// ─── Privacy Filtering ─────────────────────────────────────────

const SENSITIVE_COMMANDS = new Set(['fill', 'type', 'cookie', 'header']);
const SENSITIVE_PARAM_PATTERN = /\b(password|token|secret|key|auth|bearer|api[_-]?key)\b/i;

/**
 * Redact sensitive data from command args before streaming.
 */
export function filterArgs(command: string, args: string[]): string[] {
  if (!args || args.length === 0) return args;

  // fill: redact the value (last arg) for password-type fields
  if (command === 'fill' && args.length >= 2) {
    const selector = args[0];
    // If the selector suggests a password field, redact the value
    if (/password|passwd|secret|token/i.test(selector)) {
      return [selector, '[REDACTED]'];
    }
    return args;
  }

  // header: redact Authorization and other sensitive headers
  if (command === 'header' && args.length >= 1) {
    const headerLine = args[0];
    if (/^(authorization|x-api-key|cookie|set-cookie)/i.test(headerLine)) {
      const colonIdx = headerLine.indexOf(':');
      if (colonIdx > 0) {
        return [headerLine.substring(0, colonIdx + 1) + '[REDACTED]'];
      }
    }
    return args;
  }

  // cookie: redact cookie values
  if (command === 'cookie' && args.length >= 1) {
    const cookieStr = args[0];
    const eqIdx = cookieStr.indexOf('=');
    if (eqIdx > 0) {
      return [cookieStr.substring(0, eqIdx + 1) + '[REDACTED]'];
    }
    return args;
  }

  // type: always redact (could be a password field)
  if (command === 'type') {
    return ['[REDACTED]'];
  }

  // URL args: redact sensitive query params
  return args.map(arg => {
    if (arg.startsWith('http://') || arg.startsWith('https://')) {
      try {
        const url = new URL(arg);
        let redacted = false;
        for (const key of url.searchParams.keys()) {
          if (SENSITIVE_PARAM_PATTERN.test(key)) {
            url.searchParams.set(key, '[REDACTED]');
            redacted = true;
          }
        }
        return redacted ? url.toString() : arg;
      } catch {
        return arg;
      }
    }
    return arg;
  });
}

/**
 * Truncate result text for streaming (max 200 chars).
 */
function truncateResult(result: string | undefined): string | undefined {
  if (!result) return undefined;
  if (result.length <= 200) return result;
  return result.substring(0, 200) + '...';
}

// ─── Public API ─────────────────────────────────────────────────

/**
 * Emit an activity event. Backpressure-safe: subscribers notified asynchronously.
 */
export function emitActivity(entry: Omit<ActivityEntry, 'id' | 'timestamp'>): ActivityEntry {
  const full: ActivityEntry = {
    ...entry,
    id: nextId++,
    timestamp: Date.now(),
    args: entry.args ? filterArgs(entry.command || '', entry.args) : undefined,
    result: truncateResult(entry.result),
  };
  activityBuffer.push(full);

  // Notify subscribers asynchronously — never block the command path
  for (const notify of subscribers) {
    queueMicrotask(() => {
      try { notify(full); } catch { /* subscriber error — don't crash */ }
    });
  }

  return full;
}

/**
 * Subscribe to live activity events. Returns unsubscribe function.
 */
export function subscribe(fn: ActivitySubscriber): () => void {
  subscribers.add(fn);
  return () => subscribers.delete(fn);
}

/**
 * Get recent activity entries after the given cursor ID.
 * Returns entries and gap info if the buffer has overflowed.
 */
export function getActivityAfter(afterId: number): {
  entries: ActivityEntry[];
  gap: boolean;
  gapFrom?: number;
  availableFrom?: number;
  totalAdded: number;
} {
  const total = activityBuffer.totalAdded;
  const allEntries = activityBuffer.toArray();

  if (afterId === 0) {
    return { entries: allEntries, gap: false, totalAdded: total };
  }

  // Check for gap: if afterId is too old and has been evicted
  const oldestId = allEntries.length > 0 ? allEntries[0].id : nextId;
  if (afterId < oldestId) {
    return {
      entries: allEntries,
      gap: true,
      gapFrom: afterId + 1,
      availableFrom: oldestId,
      totalAdded: total,
    };
  }

  // Filter to entries after the cursor
  const filtered = allEntries.filter(e => e.id > afterId);
  return { entries: filtered, gap: false, totalAdded: total };
}

/**
 * Get the N most recent activity entries.
 */
export function getActivityHistory(limit: number = 50): {
  entries: ActivityEntry[];
  totalAdded: number;
} {
  const allEntries = activityBuffer.toArray();
  const sliced = limit < allEntries.length ? allEntries.slice(-limit) : allEntries;
  return { entries: sliced, totalAdded: activityBuffer.totalAdded };
}

/**
 * Get subscriber count (for debugging/health).
 */
export function getSubscriberCount(): number {
  return subscribers.size;
}

/**
 * Persistent command audit log — forensic trail for all browse server commands.
 *
 * Writes append-only JSONL to .gstack/browse-audit.jsonl. Unlike the in-memory
 * ring buffers (console, network, dialog), the audit log persists across server
 * restarts and is never truncated by the server. Each entry records:
 *
 *   - timestamp, command, args (truncated), page origin
 *   - duration, status (ok/error), error message if any
 *   - whether cookies were imported (elevated security context)
 *   - connection mode (headless/headed)
 *
 * All writes are best-effort — audit failures never cause command failures.
 */

import * as fs from 'fs';

export interface AuditEntry {
  ts: string;
  cmd: string;
  /** If the agent typed an alias (e.g. 'setcontent'), the raw input is preserved here
   *  while `cmd` holds the canonical name ('load-html'). Omitted when cmd === rawCmd. */
  aliasOf?: string;
  args: string;
  origin: string;
  durationMs: number;
  status: 'ok' | 'error';
  error?: string;
  hasCookies: boolean;
  mode: 'launched' | 'headed';
}

const MAX_ARGS_LENGTH = 200;
const MAX_ERROR_LENGTH = 300;

let auditPath: string | null = null;

export function initAuditLog(logPath: string): void {
  auditPath = logPath;
}

export function writeAuditEntry(entry: AuditEntry): void {
  if (!auditPath) return;
  try {
    const truncatedArgs = entry.args.length > MAX_ARGS_LENGTH
      ? entry.args.slice(0, MAX_ARGS_LENGTH) + '…'
      : entry.args;
    const truncatedError = entry.error && entry.error.length > MAX_ERROR_LENGTH
      ? entry.error.slice(0, MAX_ERROR_LENGTH) + '…'
      : entry.error;

    const record: Record<string, unknown> = {
      ts: entry.ts,
      cmd: entry.cmd,
      args: truncatedArgs,
      origin: entry.origin,
      durationMs: entry.durationMs,
      status: entry.status,
      hasCookies: entry.hasCookies,
      mode: entry.mode,
    };
    if (entry.aliasOf) record.aliasOf = entry.aliasOf;
    if (truncatedError) record.error = truncatedError;

    fs.appendFileSync(auditPath, JSON.stringify(record) + '\n');
  } catch {
    // Audit write failures are silent — never block command execution
  }
}

/**
 * browse-client — canonical SDK that browser-skill scripts import to drive the
 * gstack daemon over loopback HTTP.
 *
 * Distribution model:
 *   This file is the canonical source. Each browser-skill ships a sibling
 *   copy at `<skill>/_lib/browse-client.ts` (Phase 2's generator copies it
 *   alongside every generated skill; Phase 1's bundled `hackernews-frontpage`
 *   reference skill ships a hand-copied version). The skill imports the
 *   sibling via relative path: `import { browse } from './_lib/browse-client'`.
 *
 *   Why per-skill copies and not a single global SDK: each skill is fully
 *   portable (copy the directory anywhere, it runs), version drift is
 *   impossible (the SDK is frozen at the version the skill was authored
 *   against), no npm publish workflow, no fixed-path tilde imports.
 *
 * Auth resolution:
 *   1. GSTACK_PORT + GSTACK_SKILL_TOKEN env vars (set by `$B skill run` when
 *      spawning the script). The token is a per-spawn scoped capability bound
 *      to read+write commands; it expires when the spawn ends.
 *   2. State file fallback: read `BROWSE_STATE_FILE` env or `<git-root>/.gstack/browse.json`
 *      and use the `port` + `token` (the daemon root token). This path exists
 *      for developers running a skill directly via `bun run script.ts` outside
 *      the harness — your own authority, not an agent's.
 *
 * Trust:
 *   The SDK exposes only the daemon's existing HTTP surface (POST /command).
 *   No new capabilities. The token's scopes (read+write for spawned skills,
 *   full root for standalone debug) determine what actually executes.
 *
 * Zero side effects on import. Safe to import from tests or plain scripts.
 */

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

export interface BrowseClientOptions {
  /** Override port. Default: GSTACK_PORT env or state file. */
  port?: number;
  /** Override token. Default: GSTACK_SKILL_TOKEN env, then state file root token. */
  token?: string;
  /** Tab id to target (every command can scope to a tab). Default: BROWSE_TAB env or undefined (active tab). */
  tabId?: number;
  /** Per-request timeout in milliseconds. Default: 30_000. */
  timeoutMs?: number;
  /** Override state-file path. Default: BROWSE_STATE_FILE env or <git-root>/.gstack/browse.json. */
  stateFile?: string;
}

interface ResolvedAuth {
  port: number;
  token: string;
  source: 'env' | 'state-file';
}

function parseIntegerEnvValue(value: string | undefined): number | undefined {
  const trimmed = value?.trim();
  if (!trimmed || !/^-?\d+$/.test(trimmed)) return undefined;
  const parsed = parseInt(trimmed, 10);
  return Number.isFinite(parsed) ? parsed : undefined;
}

/** Resolve the daemon port + token. Throws a clear error if neither path works. */
export function resolveBrowseAuth(opts: BrowseClientOptions = {}): ResolvedAuth {
  if (opts.port !== undefined && opts.token !== undefined) {
    return { port: opts.port, token: opts.token, source: 'env' };
  }

  // 1. Env vars (set by $B skill run when spawning).
  const envPort = process.env.GSTACK_PORT;
  const envToken = process.env.GSTACK_SKILL_TOKEN;
  if (envPort && envToken) {
    const port = opts.port ?? parseIntegerEnvValue(envPort);
    if (port !== undefined) {
      return { port, token: opts.token ?? envToken, source: 'env' };
    }
  }

  // 2. State file fallback (developer running `bun run script.ts` directly).
  const stateFile = opts.stateFile ?? process.env.BROWSE_STATE_FILE ?? defaultStateFile();
  if (stateFile && fs.existsSync(stateFile)) {
    try {
      const data = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
      if (typeof data.port === 'number' && typeof data.token === 'string') {
        return {
          port: opts.port ?? data.port,
          token: opts.token ?? data.token,
          source: 'state-file',
        };
      }
    } catch {
      // fall through to error
    }
  }

  throw new Error(
    'browse-client: cannot find daemon port + token. Either spawn via `$B skill run` ' +
    '(sets GSTACK_PORT + GSTACK_SKILL_TOKEN) or run from a project with a live daemon ' +
    '(.gstack/browse.json must exist).'
  );
}

function defaultStateFile(): string | null {
  try {
    const proc = cp.spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf-8', timeout: 2000 });
    const root = proc.status === 0 ? proc.stdout.trim() : null;
    const base = root || process.cwd();
    return path.join(base, '.gstack', 'browse.json');
  } catch {
    return path.join(process.cwd(), '.gstack', 'browse.json');
  }
}

export class BrowseClientError extends Error {
  constructor(
    message: string,
    public readonly status?: number,
    public readonly body?: string,
  ) {
    super(message);
    this.name = 'BrowseClientError';
  }
}

/**
 * Thin client over the daemon's POST /command endpoint.
 *
 * Convenience methods cover the common cases (goto, click, text, snapshot,
 * etc.). For anything not exposed as a method, use `command(cmd, args)`.
 */
export class BrowseClient {
  readonly port: number;
  readonly token: string;
  readonly tabId?: number;
  readonly timeoutMs: number;

  constructor(opts: BrowseClientOptions = {}) {
    const auth = resolveBrowseAuth(opts);
    this.port = auth.port;
    this.token = auth.token;
    this.tabId = opts.tabId ?? parseIntegerEnvValue(process.env.BROWSE_TAB);
    this.timeoutMs = opts.timeoutMs ?? 30_000;
  }

  // ─── Low-level dispatch ─────────────────────────────────────────

  /** Send an arbitrary command; returns raw response text. Throws on non-2xx. */
  async command(cmd: string, args: string[] = []): Promise<string> {
    const body = JSON.stringify({
      command: cmd,
      args,
      ...(this.tabId !== undefined && !isNaN(this.tabId) ? { tabId: this.tabId } : {}),
    });

    let resp: Response;
    try {
      resp = await fetch(`http://127.0.0.1:${this.port}/command`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${this.token}`,
        },
        body,
        signal: AbortSignal.timeout(this.timeoutMs),
      });
    } catch (err: any) {
      if (err.name === 'TimeoutError' || err.name === 'AbortError') {
        throw new BrowseClientError(`browse-client: command "${cmd}" timed out after ${this.timeoutMs}ms`);
      }
      if (err.code === 'ECONNREFUSED') {
        throw new BrowseClientError(`browse-client: daemon not running on port ${this.port}`);
      }
      throw new BrowseClientError(`browse-client: ${err.message ?? err}`);
    }

    const text = await resp.text();
    if (!resp.ok) {
      let message = `browse-client: command "${cmd}" failed with status ${resp.status}`;
      try {
        const parsed = JSON.parse(text);
        if (parsed.error) message += `: ${parsed.error}`;
      } catch {
        if (text) message += `: ${text.slice(0, 200)}`;
      }
      throw new BrowseClientError(message, resp.status, text);
    }
    return text;
  }

  // ─── Navigation ─────────────────────────────────────────────────

  async goto(url: string): Promise<string> { return this.command('goto', [url]); }
  async wait(arg: string): Promise<string> { return this.command('wait', [arg]); }

  // ─── Reading ────────────────────────────────────────────────────

  async text(selector?: string): Promise<string> {
    return this.command('text', selector ? [selector] : []);
  }
  async html(selector?: string): Promise<string> {
    return this.command('html', selector ? [selector] : []);
  }
  async links(): Promise<string> { return this.command('links'); }
  async forms(): Promise<string> { return this.command('forms'); }
  async accessibility(): Promise<string> { return this.command('accessibility'); }
  async attrs(selector: string): Promise<string> { return this.command('attrs', [selector]); }
  async media(...flags: string[]): Promise<string> { return this.command('media', flags); }
  async data(...flags: string[]): Promise<string> { return this.command('data', flags); }

  // ─── Interaction ────────────────────────────────────────────────

  async click(selector: string): Promise<string> { return this.command('click', [selector]); }
  async fill(selector: string, value: string): Promise<string> { return this.command('fill', [selector, value]); }
  async select(selector: string, value: string): Promise<string> { return this.command('select', [selector, value]); }
  async hover(selector: string): Promise<string> { return this.command('hover', [selector]); }
  async type(text: string): Promise<string> { return this.command('type', [text]); }
  async press(key: string): Promise<string> { return this.command('press', [key]); }
  async scroll(selector?: string): Promise<string> {
    return this.command('scroll', selector ? [selector] : []);
  }

  // ─── Snapshot + screenshot ──────────────────────────────────────

  /** Snapshot returns the ARIA tree. Pass flags like '-i' (interactive only), '-c' (compact). */
  async snapshot(...flags: string[]): Promise<string> { return this.command('snapshot', flags); }
  async screenshot(...args: string[]): Promise<string> { return this.command('screenshot', args); }
}

/**
 * Default singleton. Lazily resolves auth on first method call so a script can
 * import `browse` and immediately call `await browse.goto(...)` without
 * threading through a constructor.
 */
class LazyBrowseClient {
  private inner: BrowseClient | null = null;
  private get(): BrowseClient {
    if (!this.inner) this.inner = new BrowseClient();
    return this.inner;
  }
  // Mirror the BrowseClient surface; each method delegates to a freshly resolved instance.
  command(cmd: string, args: string[] = []) { return this.get().command(cmd, args); }
  goto(url: string) { return this.get().goto(url); }
  wait(arg: string) { return this.get().wait(arg); }
  text(selector?: string) { return this.get().text(selector); }
  html(selector?: string) { return this.get().html(selector); }
  links() { return this.get().links(); }
  forms() { return this.get().forms(); }
  accessibility() { return this.get().accessibility(); }
  attrs(selector: string) { return this.get().attrs(selector); }
  media(...flags: string[]) { return this.get().media(...flags); }
  data(...flags: string[]) { return this.get().data(...flags); }
  click(selector: string) { return this.get().click(selector); }
  fill(selector: string, value: string) { return this.get().fill(selector, value); }
  select(selector: string, value: string) { return this.get().select(selector, value); }
  hover(selector: string) { return this.get().hover(selector); }
  type(text: string) { return this.get().type(text); }
  press(key: string) { return this.get().press(key); }
  scroll(selector?: string) { return this.get().scroll(selector); }
  snapshot(...flags: string[]) { return this.get().snapshot(...flags); }
  screenshot(...args: string[]) { return this.get().screenshot(...args); }
}

export const browse = new LazyBrowseClient();

/**
 * $B skill subcommands — CLI surface for browser-skills.
 *
 * Subcommands:
 *   list                                       — list all skills, with resolved tier
 *   show <name>                                — print skill SKILL.md
 *   run <name> [--arg ...] [--timeout=Ns]      — spawn the skill script, return JSON
 *   test <name>                                — run script.test.ts via bun test
 *   rm <name> [--global]                       — tombstone a user-tier skill
 *
 * Load-bearing: spawnSkill mints a per-spawn scoped token (read+write scope)
 * and passes it via GSTACK_SKILL_TOKEN. The skill never sees the daemon root
 * token. Untrusted skills get a scrubbed env (no $HOME, $PATH minimal, no
 * secrets like $GITHUB_TOKEN/$OPENAI_API_KEY/etc.) and a locked cwd. Trusted
 * skills (frontmatter `trusted: true`) inherit the full process env.
 *
 * Output protocol: stdout = JSON, stderr = streaming logs, exit code 0/non-0.
 * stdout cap = 1MB (truncate + nonzero exit if exceeded). Default timeout 60s.
 */

import * as fs from 'fs';
import * as path from 'path';
import {
  listBrowserSkills,
  readBrowserSkill,
  tombstoneBrowserSkill,
  defaultTierPaths,
  type BrowserSkill,
  type TierPaths,
} from './browser-skills';
import { mintSkillToken, revokeSkillToken, generateSpawnId } from './skill-token';

const DEFAULT_TIMEOUT_SECONDS = 60;
const MAX_STDOUT_BYTES = 1024 * 1024; // 1 MB

// ─── Public command dispatcher ──────────────────────────────────

export interface SkillCommandContext {
  /** Daemon port the skill should connect back to. */
  port: number;
  /** Optional override of tier paths (tests pass synthetic dirs). */
  tiers?: TierPaths;
}

/**
 * Dispatch a `$B skill <subcommand>` invocation. Returns the response string
 * for the daemon to relay back to the CLI. Throws on invalid usage.
 */
export async function handleSkillCommand(args: string[], ctx: SkillCommandContext): Promise<string> {
  const sub = args[0];
  const rest = args.slice(1);

  switch (sub) {
    case undefined:
    case 'help':
    case '--help':
      return formatUsage();
    case 'list':
      return handleList(ctx);
    case 'show':
      return handleShow(rest, ctx);
    case 'run':
      return handleRun(rest, ctx);
    case 'test':
      return handleTest(rest, ctx);
    case 'rm':
      return handleRm(rest, ctx);
    default:
      throw new Error(`Unknown skill subcommand: "${sub}". Try: list, show, run, test, rm.`);
  }
}

function formatUsage(): string {
  return [
    'Usage: $B skill <subcommand>',
    '',
    '  list                                  List all skills with resolved tier',
    '  show <name>                           Print SKILL.md',
    '  run <name> [--arg k=v]... [--timeout=Ns]   Run the skill script',
    '  test <name>                           Run script.test.ts',
    '  rm <name> [--global]                  Tombstone a user-tier skill',
  ].join('\n');
}

// ─── list ───────────────────────────────────────────────────────

function handleList(ctx: SkillCommandContext): string {
  const tiers = ctx.tiers ?? defaultTierPaths();
  const skills = listBrowserSkills(tiers);
  if (skills.length === 0) {
    return 'No browser-skills found.\n\nTry: $B skill show <name>  (none right now)\n';
  }
  const lines: string[] = ['NAME                          TIER     HOST                        DESC'];
  for (const s of skills) {
    const desc = (s.frontmatter.description ?? '').slice(0, 40);
    lines.push(
      [
        s.name.padEnd(30),
        s.tier.padEnd(8),
        s.frontmatter.host.padEnd(28),
        desc,
      ].join(' '),
    );
  }
  return lines.join('\n') + '\n';
}

// ─── show ───────────────────────────────────────────────────────

function handleShow(args: string[], ctx: SkillCommandContext): string {
  const name = args[0];
  if (!name) throw new Error('Usage: $B skill show <name>');
  const tiers = ctx.tiers ?? defaultTierPaths();
  const skill = readBrowserSkill(name, tiers);
  if (!skill) throw new Error(`Skill "${name}" not found in any tier.`);
  return readFile(path.join(skill.dir, 'SKILL.md'));
}

function readFile(p: string): string {
  return fs.readFileSync(p, 'utf-8');
}

// ─── run ────────────────────────────────────────────────────────

interface ParsedRunArgs {
  passthrough: string[];
  timeoutSeconds: number;
}

export function parseSkillRunArgs(args: string[]): ParsedRunArgs {
  const passthrough: string[] = [];
  let timeoutSeconds = DEFAULT_TIMEOUT_SECONDS;
  for (let i = 0; i < args.length; i++) {
    const a = args[i];
    if (a.startsWith('--timeout=')) {
      const n = parseInt(a.slice('--timeout='.length), 10);
      if (!isNaN(n) && n > 0) timeoutSeconds = n;
      continue;
    }
    passthrough.push(a);
  }
  return { passthrough, timeoutSeconds };
}

async function handleRun(args: string[], ctx: SkillCommandContext): Promise<string> {
  const name = args[0];
  if (!name) throw new Error('Usage: $B skill run <name> [--arg k=v]... [--timeout=Ns]');
  const tiers = ctx.tiers ?? defaultTierPaths();
  const skill = readBrowserSkill(name, tiers);
  if (!skill) throw new Error(`Skill "${name}" not found.`);

  const { passthrough, timeoutSeconds } = parseSkillRunArgs(args.slice(1));
  const result = await spawnSkill({
    skill,
    skillArgs: passthrough,
    trusted: skill.frontmatter.trusted,
    timeoutSeconds,
    port: ctx.port,
  });

  if (result.exitCode !== 0 || result.timedOut || result.truncated) {
    const summary = result.truncated
      ? `truncated stdout at ${MAX_STDOUT_BYTES} bytes`
      : result.timedOut
        ? `timed out after ${timeoutSeconds}s`
        : `exit ${result.exitCode}`;
    const err = new Error(`Skill "${name}" failed: ${summary}\n--- stderr ---\n${result.stderr.slice(0, 4096)}`);
    (err as any).exitCode = result.exitCode || 1;
    throw err;
  }
  return result.stdout;
}

// ─── test ───────────────────────────────────────────────────────

async function handleTest(args: string[], ctx: SkillCommandContext): Promise<string> {
  const name = args[0];
  if (!name) throw new Error('Usage: $B skill test <name>');
  const tiers = ctx.tiers ?? defaultTierPaths();
  const skill = readBrowserSkill(name, tiers);
  if (!skill) throw new Error(`Skill "${name}" not found.`);

  const testFile = path.join(skill.dir, 'script.test.ts');
  if (!fs.existsSync(testFile)) {
    throw new Error(`Skill "${name}" has no script.test.ts at ${testFile}`);
  }

  const proc = Bun.spawn(['bun', 'test', testFile], {
    cwd: skill.dir,
    stdout: 'pipe',
    stderr: 'pipe',
    env: process.env,
  });
  const exitCode = await proc.exited;
  const stdout = proc.stdout ? await new Response(proc.stdout).text() : '';
  const stderr = proc.stderr ? await new Response(proc.stderr).text() : '';
  if (exitCode !== 0) {
    throw new Error(`Skill "${name}" tests failed (exit ${exitCode}).\n${stderr}`);
  }
  return stderr || stdout || `tests passed for "${name}"`;
}

// ─── rm ─────────────────────────────────────────────────────────

function handleRm(args: string[], ctx: SkillCommandContext): string {
  const name = args[0];
  if (!name) throw new Error('Usage: $B skill rm <name> [--global]');
  const isGlobal = args.includes('--global');
  const tier: 'project' | 'global' = isGlobal ? 'global' : 'project';

  const tiers = ctx.tiers ?? defaultTierPaths();
  // For UX: if no project tier exists at all, default to global.
  const effectiveTier: 'project' | 'global' = (tier === 'project' && !tiers.project) ? 'global' : tier;

  const dst = tombstoneBrowserSkill(name, effectiveTier, tiers);
  return `Tombstoned "${name}" (${effectiveTier} tier) → ${dst}\n`;
}

// ─── spawnSkill (load-bearing) ──────────────────────────────────

export interface SpawnSkillOptions {
  skill: BrowserSkill;
  skillArgs: string[];
  trusted: boolean;
  timeoutSeconds: number;
  port: number;
}

export interface SpawnSkillResult {
  stdout: string;
  stderr: string;
  exitCode: number;
  timedOut: boolean;
  truncated: boolean;
}

/**
 * Spawn a skill script as a child process.
 *
 * 1. Mint a scoped token (read+write only; expires at timeout + 30s slack).
 * 2. Build the env: trusted=true → process.env; trusted=false → scrubbed.
 *    GSTACK_PORT and GSTACK_SKILL_TOKEN are always set.
 * 3. Spawn `bun run script.ts -- <args>` with cwd=skill.dir.
 * 4. Capture stdout (capped at 1MB) and stderr; enforce timeout.
 * 5. On exit/timeout, revoke the token. Always.
 */
export async function spawnSkill(opts: SpawnSkillOptions): Promise<SpawnSkillResult> {
  const spawnId = generateSpawnId();
  const tokenInfo = mintSkillToken({
    skillName: opts.skill.name,
    spawnId,
    spawnTimeoutSeconds: opts.timeoutSeconds,
  });

  try {
    const env = buildSpawnEnv({
      trusted: opts.trusted,
      port: opts.port,
      skillToken: tokenInfo.token,
    });
    const scriptPath = path.join(opts.skill.dir, 'script.ts');
    if (!fs.existsSync(scriptPath)) {
      throw new Error(`Skill "${opts.skill.name}" missing script.ts at ${scriptPath}`);
    }

    const proc = Bun.spawn(['bun', 'run', scriptPath, '--', ...opts.skillArgs], {
      cwd: opts.skill.dir,
      env,
      stdout: 'pipe',
      stderr: 'pipe',
    });

    let timedOut = false;
    const killer = setTimeout(() => {
      timedOut = true;
      try { proc.kill(); } catch {}
    }, opts.timeoutSeconds * 1000);

    const stdoutPromise = readCapped(proc.stdout, MAX_STDOUT_BYTES);
    const stderrPromise = readCapped(proc.stderr, MAX_STDOUT_BYTES);

    const exitCode = await proc.exited;
    clearTimeout(killer);

    const stdoutResult = await stdoutPromise;
    const stderrResult = await stderrPromise;

    return {
      stdout: stdoutResult.text,
      stderr: stderrResult.text,
      exitCode: timedOut ? 124 : exitCode,
      timedOut,
      truncated: stdoutResult.truncated,
    };
  } finally {
    revokeSkillToken(opts.skill.name, spawnId);
  }
}

interface CappedRead { text: string; truncated: boolean; }

async function readCapped(stream: ReadableStream<Uint8Array> | undefined, capBytes: number): Promise<CappedRead> {
  if (!stream) return { text: '', truncated: false };
  const reader = stream.getReader();
  const chunks: Uint8Array[] = [];
  let total = 0;
  let truncated = false;
  try {
    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      if (!value) continue;
      total += value.length;
      if (total > capBytes) {
        truncated = true;
        // Take only what fits; drop the rest of the stream (release reader).
        const fits = value.length - (total - capBytes);
        if (fits > 0) chunks.push(value.subarray(0, fits));
        try { await reader.cancel(); } catch {}
        break;
      }
      chunks.push(value);
    }
  } finally {
    try { reader.releaseLock(); } catch {}
  }
  const buf = Buffer.concat(chunks.map(c => Buffer.from(c)));
  return { text: buf.toString('utf-8'), truncated };
}

// ─── env construction (security-critical) ───────────────────────

/**
 * Env keys ALWAYS scrubbed for untrusted skills. These represent secrets,
 * authority, or developer-environment context that an agent-authored script
 * should not see.
 */
const SECRET_KEY_PATTERNS = [
  /TOKEN/i, /KEY/i, /SECRET/i, /PASSWORD/i, /CREDENTIAL/i,
  /^AWS_/, /^AZURE_/, /^GCP_/, /^GOOGLE_APPLICATION_/,
  /^ANTHROPIC_/, /^OPENAI_/, /^GITHUB_/, /^GH_/,
  /^SSH_/, /^GPG_/,
  /^NPM_TOKEN/, /^PYPI_/,
];

/**
 * Allowlist for untrusted spawns. Anything not in this list is dropped.
 * Includes: minimal PATH, locale, terminal type. Skills get GSTACK_PORT +
 * GSTACK_SKILL_TOKEN injected separately.
 */
const UNTRUSTED_ALLOWLIST = new Set([
  'LANG', 'LC_ALL', 'LC_CTYPE',
  'TERM',
  'TZ',
]);

interface BuildEnvOptions {
  trusted: boolean;
  port: number;
  skillToken: string;
}

export function buildSpawnEnv(opts: BuildEnvOptions): Record<string, string> {
  const out: Record<string, string> = {};

  if (opts.trusted) {
    // Trusted: pass through process.env, but always strip the daemon root token
    // if the parent had one in env (defense in depth).
    for (const [k, v] of Object.entries(process.env)) {
      if (v === undefined) continue;
      if (k === 'GSTACK_TOKEN') continue; // never propagate root token
      out[k] = v;
    }
    // Set a minimal PATH if missing.
    if (!out.PATH) out.PATH = '/usr/local/bin:/usr/bin:/bin';
  } else {
    // Untrusted: minimal allowlist.
    for (const k of UNTRUSTED_ALLOWLIST) {
      const v = process.env[k];
      if (v !== undefined) out[k] = v;
    }
    // Provide a minimal PATH so `bun` is findable. Prefer the resolved bun dir
    // so scripts using a custom Bun install still work, but otherwise fall back
    // to /usr/local/bin:/usr/bin:/bin.
    out.PATH = resolveMinimalPath();
  }

  // Drop anything that pattern-matches a secret. (Trusted path can have secrets
  // intentionally — e.g. an internal-tool skill — but we still strip GSTACK_TOKEN
  // above.)
  if (!opts.trusted) {
    for (const k of Object.keys(out)) {
      if (SECRET_KEY_PATTERNS.some(p => p.test(k))) delete out[k];
    }
  }

  // Inject the daemon connection (always last so callers can't override).
  out.GSTACK_PORT = String(opts.port);
  out.GSTACK_SKILL_TOKEN = opts.skillToken;

  return out;
}

function resolveMinimalPath(): string {
  // Prefer the directory bun lives in; fall back to standard system dirs.
  const fallback = '/usr/local/bin:/usr/bin:/bin';
  const bunPath = process.execPath;
  if (bunPath && bunPath.includes('/bun')) {
    const dir = path.dirname(bunPath);
    return `${dir}:${fallback}`;
  }
  return fallback;
}

/**
 * Atomic-write helper for agent-authored browser-skills (D3 from Phase 2 plan).
 *
 * /skillify stages a candidate skill into ~/.gstack/.tmp/skillify-<spawnId>/,
 * runs $B skill test against it, and only renames the directory into its final
 * tier path on success + user approval. On failure or rejection, the staged
 * directory is removed entirely — no half-written skill ever appears in
 * $B skill list, no tombstone for something the user never approved.
 *
 *   stageSkill    — write all files into the staging dir, return its path
 *   commitSkill   — atomic rename into the final tier path; refuses to clobber
 *   discardStaged — rm -rf the staged dir (called on test fail or reject)
 *
 * Symlink discipline: lstat() the staging dir before rename to refuse moves
 * through symlinks; realpath() the final tier root to ensure the destination
 * lands inside the expected directory tree.
 */

import * as fs from 'fs';
import * as path from 'path';
import * as os from 'os';
import { mkdirSecure } from './file-permissions';
import { isPathWithin } from './platform';
import type { TierPaths } from './browser-skills';
import { defaultTierPaths } from './browser-skills';

// ─── Naming validation ──────────────────────────────────────────

/**
 * Skill names must be safe directory names: lowercase letters, digits, dashes.
 * Starts with a letter, no consecutive dashes, no trailing dash, ≤64 chars.
 * Rejects '..', leading dots, slashes, anything that could escape the tier dir.
 */
const SKILL_NAME_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;

export function validateSkillName(name: string): void {
  if (!name) throw new Error('Skill name is empty.');
  if (name.length > 64) throw new Error(`Skill name too long (${name.length} > 64).`);
  if (!SKILL_NAME_PATTERN.test(name)) {
    throw new Error(
      `Invalid skill name "${name}". Must be lowercase letters/digits/dashes, ` +
      `start with a letter, no leading/trailing/consecutive dashes.`,
    );
  }
}

// ─── Staging ────────────────────────────────────────────────────

export interface StageSkillOptions {
  name: string;
  /** Map of relative path → contents. Path may contain '/' for nested dirs. */
  files: Map<string, string | Buffer>;
  /** Optional override (tests pass synthetic spawn ids). */
  spawnId?: string;
  /** Optional override (tests pass a fake tmp root). */
  tmpRoot?: string;
}

/**
 * Stage a skill into the staging tree:
 *   <tmpRoot>/.gstack/.tmp/skillify-<spawnId>/<name>/
 *
 * The leaf <name> directory is what gets renamed during commit. The wrapper
 * skillify-<spawnId>/ is per-spawn so concurrent /skillify invocations don't
 * collide. Returns the absolute path to the staged skill dir (ending in <name>).
 */
export function stageSkill(opts: StageSkillOptions): string {
  validateSkillName(opts.name);
  if (opts.files.size === 0) {
    throw new Error('stageSkill: files map is empty.');
  }

  const spawnId = opts.spawnId ?? generateSpawnId();
  const tmpRoot = opts.tmpRoot ?? path.join(os.homedir(), '.gstack', '.tmp');
  const wrapperDir = path.join(tmpRoot, `skillify-${spawnId}`);
  const stagedDir = path.join(wrapperDir, opts.name);

  mkdirSecure(wrapperDir);
  mkdirSecure(stagedDir);

  for (const [relPath, contents] of opts.files) {
    if (relPath.startsWith('/') || relPath.includes('..')) {
      // Defense in depth: validateSkillName above bounds the leaf, but a
      // bad relPath in files could still write outside the staged dir.
      throw new Error(`Invalid file path in stageSkill: "${relPath}".`);
    }
    const filePath = path.join(stagedDir, relPath);
    const fileDir = path.dirname(filePath);
    fs.mkdirSync(fileDir, { recursive: true });
    fs.writeFileSync(filePath, contents);
  }

  return stagedDir;
}

// ─── Commit (atomic rename) ─────────────────────────────────────

export interface CommitSkillOptions {
  name: string;
  tier: 'project' | 'global';
  stagedDir: string;
  /** Optional override (tests pass synthetic tier paths). */
  tiers?: TierPaths;
}

/**
 * Atomically move the staged skill into its final tier path. Refuses to
 * clobber an existing skill at the same path — the agent's approval gate
 * MUST surface name collisions before calling this.
 *
 * Returns the absolute path of the committed skill dir.
 *
 * Throws when:
 *   - tier path is unresolved (project tier with no project root)
 *   - destination already exists
 *   - staged dir is a symlink (refuses to follow)
 *   - resolved destination escapes the tier root (defense in depth)
 */
export function commitSkill(opts: CommitSkillOptions): string {
  validateSkillName(opts.name);

  const tiers = opts.tiers ?? defaultTierPaths();
  const tierRoot = opts.tier === 'project' ? tiers.project : tiers.global;
  if (!tierRoot) {
    throw new Error(`commitSkill: tier "${opts.tier}" has no resolved path.`);
  }

  // Refuse to follow a symlinked staging dir — caller should hand us the path
  // returned by stageSkill, which is always a real directory.
  let stagedStat: fs.Stats;
  try {
    stagedStat = fs.lstatSync(opts.stagedDir);
  } catch (err: any) {
    throw new Error(`commitSkill: staged dir "${opts.stagedDir}" not accessible: ${err.code ?? err.message}`);
  }
  if (stagedStat.isSymbolicLink()) {
    throw new Error(`commitSkill: staged dir "${opts.stagedDir}" is a symlink — refusing to commit.`);
  }
  if (!stagedStat.isDirectory()) {
    throw new Error(`commitSkill: staged path "${opts.stagedDir}" is not a directory.`);
  }

  // Ensure the tier root exists, then resolve its real path so the final
  // destination check defends against tierRoot itself being a symlink.
  fs.mkdirSync(tierRoot, { recursive: true, mode: 0o755 });
  const realTierRoot = fs.realpathSync(tierRoot);

  const dest = path.join(realTierRoot, opts.name);
  if (!isPathWithin(dest, realTierRoot)) {
    // Should be impossible after validateSkillName, but defense in depth.
    throw new Error(`commitSkill: destination "${dest}" escapes tier root.`);
  }

  // Refuse to clobber. Both regular dirs and symlinks count.
  let destExists = false;
  try {
    fs.lstatSync(dest);
    destExists = true;
  } catch (err: any) {
    if (err.code !== 'ENOENT') throw err;
  }
  if (destExists) {
    throw new Error(
      `commitSkill: a skill named "${opts.name}" already exists at ${dest}. ` +
      `Pick a different name or remove the existing skill first ` +
      `($B skill rm ${opts.name}${opts.tier === 'global' ? ' --global' : ''}).`,
    );
  }

  fs.renameSync(opts.stagedDir, dest);
  return dest;
}

// ─── Discard (cleanup on failure or reject) ─────────────────────

/**
 * Remove the staged skill directory and its per-spawn wrapper. Called on
 * test failure (step 8 of /skillify) or approval rejection (step 9).
 *
 * Idempotent: missing dirs are not an error. Best-effort: failures are
 * swallowed (cleanup is fire-and-forget, not load-bearing).
 */
export function discardStaged(stagedDir: string): void {
  // Remove the leaf skill dir first, then the wrapper skillify-<spawnId>/.
  // If the wrapper was the only thing inside it, this tidies up that too.
  try {
    fs.rmSync(stagedDir, { recursive: true, force: true });
  } catch {
    // best effort
  }
  const wrapperDir = path.dirname(stagedDir);
  if (path.basename(wrapperDir).startsWith('skillify-')) {
    try {
      // Only remove the wrapper if it's now empty — concurrent /skillify
      // invocations get their own wrappers, but if a buggy caller passed
      // a stagedDir not under a skillify-<id> wrapper we should not nuke
      // an unrelated parent.
      const remaining = fs.readdirSync(wrapperDir);
      if (remaining.length === 0) {
        fs.rmdirSync(wrapperDir);
      }
    } catch {
      // best effort
    }
  }
}

// ─── Spawn id ───────────────────────────────────────────────────

/** Per-spawn id matching the format used by skill-token.ts. */
function generateSpawnId(): string {
  // 8 random hex chars + millis suffix — collision risk negligible across
  // concurrent /skillify invocations on a single machine.
  const rand = Math.floor(Math.random() * 0xffffffff).toString(16).padStart(8, '0');
  return `${rand}-${Date.now().toString(36)}`;
}

/**
 * Shared buffers and types — extracted to break circular dependency
 * between server.ts and browser-manager.ts
 *
 * CircularBuffer<T>: O(1) insert ring buffer with fixed capacity.
 *
 *   ┌───┬───┬───┬───┬───┬───┐
 *   │ 3 │ 4 │ 5 │   │ 1 │ 2 │  capacity=6, head=4, size=5
 *   └───┴───┴───┴───┴─▲─┴───┘
 *                      │
 *                    head (oldest entry)
 *
 *   push() writes at (head+size) % capacity, O(1)
 *   toArray() returns entries in insertion order, O(n)
 *   totalAdded keeps incrementing past capacity (flush cursor)
 */

// ─── CircularBuffer ─────────────────────────────────────────

export class CircularBuffer<T> {
  private buffer: (T | undefined)[];
  private head: number = 0;
  private _size: number = 0;
  private _totalAdded: number = 0;
  readonly capacity: number;

  constructor(capacity: number) {
    this.capacity = capacity;
    this.buffer = new Array(capacity);
  }

  push(entry: T): void {
    const index = (this.head + this._size) % this.capacity;
    this.buffer[index] = entry;
    if (this._size < this.capacity) {
      this._size++;
    } else {
      // Buffer full — advance head (overwrites oldest)
      this.head = (this.head + 1) % this.capacity;
    }
    this._totalAdded++;
  }

  /** Return entries in insertion order (oldest first) */
  toArray(): T[] {
    const result: T[] = [];
    for (let i = 0; i < this._size; i++) {
      result.push(this.buffer[(this.head + i) % this.capacity] as T);
    }
    return result;
  }

  /** Return the last N entries (most recent first → reversed to oldest first) */
  last(n: number): T[] {
    const count = Math.min(n, this._size);
    const result: T[] = [];
    const start = (this.head + this._size - count) % this.capacity;
    for (let i = 0; i < count; i++) {
      result.push(this.buffer[(start + i) % this.capacity] as T);
    }
    return result;
  }

  get length(): number {
    return this._size;
  }

  get totalAdded(): number {
    return this._totalAdded;
  }

  clear(): void {
    this.head = 0;
    this._size = 0;
    // Don't reset totalAdded — flush cursor depends on it
  }

  /** Get entry by index (0 = oldest) — used by network response matching */
  get(index: number): T | undefined {
    if (index < 0 || index >= this._size) return undefined;
    return this.buffer[(this.head + index) % this.capacity];
  }

  /** Set entry by index (0 = oldest) — used by network response matching */
  set(index: number, entry: T): void {
    if (index < 0 || index >= this._size) return;
    this.buffer[(this.head + index) % this.capacity] = entry;
  }
}

// ─── Entry Types ────────────────────────────────────────────

export interface LogEntry {
  timestamp: number;
  level: string;
  text: string;
}

export interface NetworkEntry {
  timestamp: number;
  method: string;
  url: string;
  status?: number;
  duration?: number;
  size?: number;
}

export interface DialogEntry {
  timestamp: number;
  type: string;        // 'alert' | 'confirm' | 'prompt' | 'beforeunload'
  message: string;
  defaultValue?: string;
  action: string;      // 'accepted' | 'dismissed'
  response?: string;   // text provided for prompt
}

// ─── Buffer Instances ───────────────────────────────────────

const HIGH_WATER_MARK = 50_000;

export const consoleBuffer = new CircularBuffer<LogEntry>(HIGH_WATER_MARK);
export const networkBuffer = new CircularBuffer<NetworkEntry>(HIGH_WATER_MARK);
export const dialogBuffer = new CircularBuffer<DialogEntry>(HIGH_WATER_MARK);

// ─── Convenience add functions ──────────────────────────────

export function addConsoleEntry(entry: LogEntry) {
  consoleBuffer.push(entry);
}

export function addNetworkEntry(entry: NetworkEntry) {
  networkBuffer.push(entry);
}

export function addDialogEntry(entry: DialogEntry) {
  dialogBuffer.push(entry);
}