@amg555/frameforge-mcp 2.7.6 → 2.7.8

package/.agent/skills/gstack-browse/src/commands.ts

@@ -1,296 +0,0 @@
-/**
- * Command registry — single source of truth for all browse commands.
- *
- * Dependency graph:
- *   commands.ts ──▶ server.ts (runtime dispatch)
- *                ──▶ gen-skill-docs.ts (doc generation)
- *                ──▶ skill-parser.ts (validation)
- *                ──▶ skill-check.ts (health reporting)
- *
- * Zero side effects. Safe to import from build scripts and tests.
- */
-
-export const READ_COMMANDS = new Set([
-  'text', 'html', 'links', 'forms', 'accessibility',
-  'js', 'eval', 'css', 'attrs',
-  'console', 'network', 'cookies', 'storage', 'perf',
-  'dialog', 'is',
-  'inspect',
-  'media', 'data',
-]);
-
-export const WRITE_COMMANDS = new Set([
-  'goto', 'back', 'forward', 'reload',
-  'load-html',
-  'click', 'fill', 'select', 'hover', 'type', 'press', 'scroll', 'wait',
-  'viewport', 'cookie', 'cookie-import', 'cookie-import-browser', 'header', 'useragent',
-  'upload', 'dialog-accept', 'dialog-dismiss',
-  'style', 'cleanup', 'prettyscreenshot',
-  'download', 'scrape', 'archive',
-]);
-
-export const META_COMMANDS = new Set([
-  'tabs', 'tab', 'tab-each', 'newtab', 'closetab',
-  'status', 'stop', 'restart',
-  'screenshot', 'pdf', 'responsive',
-  'chain', 'diff',
-  'url', 'snapshot',
-  'handoff', 'resume',
-  'connect', 'disconnect', 'focus',
-  'inbox',
-  'watch',
-  'state',
-  'frame',
-  'ux-audit',
-  'domain-skill',
-  'skill',
-  'cdp',
-  'memory',
-]);
-
-export const ALL_COMMANDS = new Set([...READ_COMMANDS, ...WRITE_COMMANDS, ...META_COMMANDS]);
-
-/** Commands that return untrusted third-party page content */
-export const PAGE_CONTENT_COMMANDS = new Set([
-  'text', 'html', 'links', 'forms', 'accessibility', 'attrs',
-  'console', 'dialog',
-  'media', 'data',
-  'ux-audit',
-  // snapshot emits aria tree with attacker-controlled aria-label strings.
-  // The sidebar's system prompt pushes agents to run `$B snapshot` as the
-  // primary read path, so unwrapped snapshot output is the biggest ingress
-  // for indirect prompt injection. Envelope it like every other read.
-  'snapshot',
-]);
-
-/**
- * Subset of PAGE_CONTENT_COMMANDS whose output is derived from the
- * live page DOM. These channels can carry hidden elements or
- * ARIA-injection payloads that the centralized envelope wrap alone
- * does not neutralize, so the scoped-token pipeline runs
- * `markHiddenElements` on the page before the read and surfaces any
- * hits as CONTENT WARNINGS to the LLM.
- *
- * `console`, `dialog` intentionally excluded — they read separate
- * runtime state (console capture, dialog events), not the DOM tree.
- */
-export const DOM_CONTENT_COMMANDS = new Set([
-  'text', 'html', 'links', 'forms', 'accessibility', 'attrs',
-  'media', 'data', 'ux-audit',
-]);
-
-/** Wrap output from untrusted-content commands with trust boundary markers */
-export function wrapUntrustedContent(result: string, url: string): string {
-  // Sanitize URL: remove newlines to prevent marker injection via history.pushState
-  const safeUrl = url.replace(/[\n\r]/g, '').slice(0, 200);
-  // Escape marker strings in content to prevent boundary escape attacks
-  const safeResult = result.replace(/--- (BEGIN|END) UNTRUSTED EXTERNAL CONTENT/g, '--- $1 UNTRUSTED EXTERNAL C\u200BONTENT');
-  return `--- BEGIN UNTRUSTED EXTERNAL CONTENT (source: ${safeUrl}) ---\n${safeResult}\n--- END UNTRUSTED EXTERNAL CONTENT ---`;
-}
-
-export const COMMAND_DESCRIPTIONS: Record<string, { category: string; description: string; usage?: string }> = {
-  // Navigation
-  'memory':  { category: 'Server', description: 'Snapshot Bun heap + per-tab JS heap + Chromium process tree + bounded buffer sizes. JSON output with --json.', usage: 'memory [--json]' },
-  'goto':    { category: 'Navigation', description: 'Navigate to URL (http://, https://, or file:// scoped to cwd/TEMP_DIR)', usage: 'goto <url>' },
-  'load-html': { category: 'Navigation', description: 'Load HTML via setContent. Accepts a file path under safe-dirs (validated), OR --from-file <payload.json> with {"html":"...","waitUntil":"..."} for large inline HTML (Windows argv safe).', usage: 'load-html <file> [--wait-until load|domcontentloaded|networkidle] [--tab-id <N>]  |  load-html --from-file <payload.json> [--tab-id <N>]' },
-  'back':    { category: 'Navigation', description: 'History back' },
-  'forward': { category: 'Navigation', description: 'History forward' },
-  'reload':  { category: 'Navigation', description: 'Reload page' },
-  'url':     { category: 'Navigation', description: 'Print current URL' },
-  // Reading
-  'text':    { category: 'Reading', description: 'Cleaned visible page text, or cleaned text for a CSS selector/@ref when one is provided', usage: 'text [selector|@ref]' },
-  'html':    { category: 'Reading', description: 'innerHTML of selector (throws if not found), or full page HTML if no selector given', usage: 'html [selector]' },
-  'links':   { category: 'Reading', description: 'All links as "text → href"' },
-  'forms':   { category: 'Reading', description: 'Form fields as JSON' },
-  'accessibility': { category: 'Reading', description: 'Full ARIA tree' },
-  'media':   { category: 'Reading', description: 'All media elements (images, videos, audio) with URLs, dimensions, types', usage: 'media [--images|--videos|--audio] [selector]' },
-  'data':    { category: 'Reading', description: 'Structured data: JSON-LD, Open Graph, Twitter Cards, meta tags', usage: 'data [--jsonld|--og|--meta|--twitter]' },
-  // Inspection
-  'js':      { category: 'Inspection', description: 'Run inline JavaScript expression in the page context and return result as string. Same JS sandbox as eval; the only difference is js takes an inline expr while eval reads from a file. With --out <file>, the result is written to disk instead of returned (a base64 data URL is decoded to raw bytes unless --raw is given) — ideal for rasterizing local renders to PNG without serializing megabytes back through the CLI. --out makes the invocation a WRITE (needs write scope, never allowed over the tunnel).', usage: 'js <expr> [--out <file>] [--raw]' },
-  'eval':    { category: 'Inspection', description: 'Run JavaScript from a file in the page context and return result as string. Path must resolve under /tmp or cwd (no traversal). Use eval for multi-line scripts; use js for one-liners. With --out <file>, the result is written to disk (base64 data URL decoded to bytes unless --raw); --out makes the invocation a WRITE (needs write scope, never allowed over the tunnel).', usage: 'eval <file> [--out <file>] [--raw]' },
-  'css':     { category: 'Inspection', description: 'Computed CSS value', usage: 'css <sel> <prop>' },
-  'attrs':   { category: 'Inspection', description: 'Element attributes as JSON', usage: 'attrs <sel|@ref>' },
-  'is':      { category: 'Inspection', description: 'State check on element. Valid <prop> values: visible, hidden, enabled, disabled, checked, editable, focused (case-sensitive). <sel> accepts a CSS selector OR an @ref token from a prior snapshot (e.g. @e3, @c1) — refs are interchangeable with selectors anywhere a selector is expected.', usage: 'is <prop> <sel|@ref>' },
-  'console': { category: 'Inspection', description: 'Console messages (--errors filters to error/warning)', usage: 'console [--clear|--errors]' },
-  'network': { category: 'Inspection', description: 'Captured network requests as lines with method, status, resource type, and URL. --clear empties the captured request buffer.', usage: 'network [--clear]' },
-  'dialog':  { category: 'Inspection', description: 'Captured alert/confirm/prompt messages as text/JSON events. --clear empties the dialog buffer.', usage: 'dialog [--clear]' },
-  'cookies': { category: 'Inspection', description: 'All cookies as JSON' },
-  'storage': { category: 'Inspection', description: 'Read both localStorage and sessionStorage as JSON. With "set <key> <value>", write to localStorage only (sessionStorage is read-only via this command — set it with `js sessionStorage.setItem(...)`).', usage: 'storage  |  storage set <key> <value>' },
-  'perf':    { category: 'Inspection', description: 'Page load timings as JSON-ish milliseconds for navigation/load phases' },
-  // Interaction
-  'click':   { category: 'Interaction', description: 'Click element', usage: 'click <sel>' },
-  'fill':    { category: 'Interaction', description: 'Fill input', usage: 'fill <sel> <val>' },
-  'select':  { category: 'Interaction', description: 'Select dropdown option by value, label, or visible text', usage: 'select <sel> <val>' },
-  'hover':   { category: 'Interaction', description: 'Hover element', usage: 'hover <sel>' },
-  'type':    { category: 'Interaction', description: 'Send keystrokes to the focused element, or to <sel> with --selector (focuses it first). Text that starts with -- goes after a -- separator.', usage: 'type [--selector <sel>] [--] <text>' },
-  'press':   { category: 'Interaction', description: 'Press a Playwright keyboard key against the focused element. Names are case-sensitive: Enter, Tab, Escape, ArrowUp/Down/Left/Right, Backspace, Delete, Home, End, PageUp, PageDown. Modifiers combine with +: Shift+Enter, Control+A, Meta+K. Single printable chars (a, A, 1) work too. Full key list: https://playwright.dev/docs/api/class-keyboard#keyboard-press', usage: 'press <key>' },
-  'scroll':  { category: 'Interaction', description: 'With a selector, smooth-scrolls the element into view. Without a selector, jumps to page bottom. No --by/--to amount option; for pixel-precise scrolling use `js window.scrollTo(0, N)`.', usage: 'scroll [sel|@ref]' },
-  'wait':    { category: 'Interaction', description: 'Wait for element, network idle, or page load (timeout: 15s)', usage: 'wait <sel|--networkidle|--load>' },
-  'upload':  { category: 'Interaction', description: 'Upload file(s)', usage: 'upload <sel> <file> [file2...]' },
-  'viewport':{ category: 'Interaction', description: 'Set viewport size and optional deviceScaleFactor (1-3, for retina screenshots). --scale requires a context rebuild. `auto` (alias `reset`) unpins: headed follows the window again, headless returns to 1280x720.', usage: 'viewport [<WxH>|auto] [--scale <n>]' },
-  'cookie':  { category: 'Interaction', description: 'Set cookie on current page domain', usage: 'cookie <name>=<value>' },
-  'cookie-import': { category: 'Interaction', description: 'Import cookies from JSON file', usage: 'cookie-import <json>' },
-  'cookie-import-browser': { category: 'Interaction', description: 'Copy cookies from chrome, chromium, brave, edge, Windows-only opera, opera-gx, or macOS-only comet, arc, dia. Omitted browser retains legacy comet; select the intended browser explicitly. --domain requires a matching current page; no scope flag opens the picker. --profile is the source directory; ambiguous profiles require selection. --all explicitly selects every non-expired cookie and cannot accompany --domain or --clear-storage. Storage is preserved unless --clear-storage resets captured-origin localStorage (shared across context tabs) and target-tab sessionStorage. --verify-auth requires daemon GSTACK_COOKIE_AUTH_SELECTOR and GSTACK_COOKIE_AUTH_EXPECTED_IDENTITY before startup; missing config rejects before mutation. Verified means an exact visible identity match, not cookie counts or HTTP 200. Windows native extraction remains disabled pending qualification.', usage: 'cookie-import-browser [browser] [--domain d] [--profile p] [--all] [--clear-storage] [--verify-auth]' },
-  'header':  { category: 'Interaction', description: 'Set custom request header (colon-separated, sensitive values auto-redacted)', usage: 'header <name>:<value>' },
-  'useragent': { category: 'Interaction', description: 'Set user agent', usage: 'useragent <string>' },
-  'dialog-accept': { category: 'Interaction', description: 'Auto-accept next alert/confirm/prompt. Optional text is sent as the prompt response', usage: 'dialog-accept [text]' },
-  'dialog-dismiss': { category: 'Interaction', description: 'Auto-dismiss next dialog' },
-  // Data extraction
-  'download': { category: 'Extraction', description: 'Download URL or media element to disk using browser cookies. Default path: <temp>/browse-download-<timestamp>.<ext>. --base64 returns a data:<mime>;base64,... string instead of writing, capped at 10MB. Use --navigate for URLs that trigger browser downloads (CDN redirects, Content-Disposition, anti-bot protected sites).', usage: 'download <url|@ref> [path] [--base64] [--navigate]' },
-  'scrape':   { category: 'Extraction', description: 'Bulk download all media from page to --dir (default: <temp>/browse-scrape-<timestamp>). Writes files plus manifest.json with source URL, size, type, success/failure counts. --limit defaults to 50 and caps at 200.', usage: 'scrape <images|videos|media> [--selector sel] [--dir path] [--limit N]' },
-  'archive':  { category: 'Extraction', description: 'Save complete page as MHTML via CDP. Default path: <temp>/browse-archive-<timestamp>.mhtml. Returns the saved path, size, and MHTML marker.', usage: 'archive [path]' },
-  // Visual
-  'screenshot': { category: 'Visual', description: 'Save screenshot. Default path: <temp>/browse-screenshot.png. Default capture is full-page; --viewport captures only the viewport. --selector targets a specific element; --clip uses x,y,width,height pixels. --base64 returns data:image/png;base64,... instead of writing, capped at 10MB. Positional selectors starting with ./#/@/[ still work.', usage: 'screenshot [--selector <css>] [--viewport] [--clip x,y,w,h] [--base64] [selector|@ref] [path]' },
-  'pdf':     { category: 'Visual', description: 'Save the current page as PDF. Default path: <temp>/browse-page.pdf. <dim> accepts CSS units like 1in, 72pt, 25mm, 2.54cm; bare numbers are pixels. Supports page layout (--format, --width, --height, --margins, --margin-*), structure (--toc waits briefly for Paged.js), branding (--header-template, --footer-template, --page-numbers), accessibility (--tagged, --outline), and --from-file <payload.json> for large payloads. Use --tab-id <N> to target a specific tab.', usage: 'pdf [path] [--format letter|a4|legal] [--width <dim> --height <dim>] [--margins <dim>] [--margin-top <dim> --margin-right <dim> --margin-bottom <dim> --margin-left <dim>] [--header-template <html>] [--footer-template <html>] [--page-numbers] [--tagged] [--outline] [--print-background] [--prefer-css-page-size] [--toc] [--tab-id <N>]  |  pdf --from-file <payload.json> [--tab-id <N>]' },
-  'responsive': { category: 'Visual', description: 'Screenshots at mobile (375x812), tablet (768x1024), desktop (1280x720). Saves as {prefix}-mobile.png etc.', usage: 'responsive [prefix]' },
-  'diff':    { category: 'Visual', description: 'Text diff between pages', usage: 'diff <url1> <url2>' },
-  // Tabs
-  'tabs':    { category: 'Tabs', description: 'List open tabs' },
-  'tab':     { category: 'Tabs', description: 'Switch to tab', usage: 'tab <id>' },
-  'newtab':  { category: 'Tabs', description: 'Open new tab. With --json, returns {"tabId":N,"url":...} for programmatic use (make-pdf).', usage: 'newtab [url] [--json]' },
-  'closetab':{ category: 'Tabs', description: 'Close tab', usage: 'closetab [id]' },
-  'tab-each':{ category: 'Tabs', description: 'Run a command on every open tab. Returns JSON with per-tab results.', usage: 'tab-each <command> [args...]' },
-  // Server
-  'status':  { category: 'Server', description: 'Health check' },
-  'stop':    { category: 'Server', description: 'Shutdown server' },
-  'restart': { category: 'Server', description: 'Restart server' },
-  // Meta
-  'snapshot':{ category: 'Snapshot', description: 'Accessibility tree with @e refs for element selection. Flags: -i interactive only, -c compact, -d N depth limit, -s sel scope, -D diff vs previous, -a annotated screenshot, -o path output, -C cursor-interactive @c refs', usage: 'snapshot [flags]' },
-  'chain':   { category: 'Meta', description: 'Run a sequence of commands from JSON on stdin. One JSON array of arrays, each inner array is [cmd, ...args]. Output is one JSON result per command. Pipe a JSON array (e.g. `[["goto","https://example.com"],["text","h1"]]`) to `$B chain` and it runs the goto then the text command in order. Stops at the first error.', usage: 'chain  (JSON via stdin)' },
-  // Handoff
-  'handoff': { category: 'Server', description: 'Open visible Chrome at current page for user takeover', usage: 'handoff [message]' },
-  'resume':  { category: 'Server', description: 'Re-snapshot after user takeover, return control to AI', usage: 'resume' },
-  // Headed mode
-  'connect': { category: 'Server', description: 'Launch headed Chromium with Chrome extension; --supervise keeps the CLI attached and respawns a crashed server', usage: 'connect [--supervise]' },
-  'disconnect': { category: 'Server', description: 'Disconnect headed browser, return to headless mode' },
-  'focus':   { category: 'Server', description: 'Bring headed browser window to foreground (macOS)', usage: 'focus [@ref]' },
-  // Inbox
-  'inbox':   { category: 'Meta', description: 'List sidebar inbox messages from the visible browser extension as JSON/text; --clear removes them after reading.', usage: 'inbox [--clear]' },
-  // Watch
-  'watch':   { category: 'Meta', description: 'Start passive observation mode: records periodic snapshots while the user browses and blocks mutation commands. Use watch stop to end observation and return the collected snapshot summary.', usage: 'watch [stop]' },
-  // State
-  'state':   { category: 'Server', description: 'Save/load browser state (cookies + URLs)', usage: 'state save|load <name>' },
-  // Frame
-  'frame':   { category: 'Meta', description: 'Switch command context to an iframe, or `main` to return to the top page. <sel> is CSS, @ref comes from snapshot, --name matches frame name exactly, and --url pattern is a substring match against frame URL.', usage: 'frame <sel|@ref|--name n|--url pattern|main>' },
-  // CSS Inspector
-  'inspect': { category: 'Inspection', description: 'Deep CSS inspection via CDP. Default inspects one selector and returns matching element, full rule cascade, box model, and computed styles. --all returns every inspectable element summary; --history returns prior style modifications/inspection state.', usage: 'inspect [selector] [--all] [--history]' },
-  'style':   { category: 'Interaction', description: 'Modify CSS property on element (with undo support)', usage: 'style <sel> <prop> <value> | style --undo [N]' },
-  'cleanup': { category: 'Interaction', description: 'Remove page clutter by hiding matched elements. With no flags, defaults to --all. --all includes ads, cookies, sticky, social, overlays, and clutter; individual flags limit the categories. Returns removed element count.', usage: 'cleanup [--ads] [--cookies] [--sticky] [--social] [--overlays] [--clutter] [--all]' },
-  'prettyscreenshot': { category: 'Visual', description: 'Clean screenshot with optional cleanup, scroll positioning, and element hiding', usage: 'prettyscreenshot [--scroll-to sel|text] [--cleanup] [--hide sel...] [--width px] [path]' },
-  // UX Audit
-  'ux-audit': { category: 'Inspection', description: 'Extract page structure for UX behavioral analysis — site ID, nav, headings, text blocks, interactive elements. Returns JSON for agent interpretation.', usage: 'ux-audit' },
-  // Domain skills (per-site notes the agent writes for itself)
-  'domain-skill': { category: 'Meta', description: 'Per-site notes the agent writes for itself. Host is derived from the active tab. Lifecycle: `save` adds a quarantined note → after N=3 successful uses without the prompt-injection classifier flagging it, the note auto-promotes to "active" → `promote-to-global` lifts it to the global tier (machine-wide, all projects). The classifier flag is set automatically by the L4 prompt-injection scan; agents do not set it manually. Use `list` / `show` to inspect, `edit` to revise, `rollback` to demote, `rm` to tombstone.', usage: 'domain-skill save|list|show|edit|promote-to-global|rollback|rm <host?>' },
-  // Browser-skills (hand-written or generated Playwright scripts the runtime spawns)
-  'skill':        { category: 'Meta', description: 'Run a browser-skill: deterministic Playwright script that drives the daemon over loopback HTTP. 3-tier lookup (project > global > bundled). Spawned scripts get a per-spawn scoped token (read+write only) — never the daemon root token.', usage: 'skill list|show|run|test|rm <name?> [--arg k=v]... [--timeout=Ns]' },
-  // CDP escape hatch (deny-default; see browse/src/cdp-allowlist.ts)
-  'cdp':          { category: 'Inspection', description: 'Raw Chrome DevTools Protocol method dispatch. Deny-default: only methods enumerated in `browse/src/cdp-allowlist.ts` (CDP_ALLOWLIST const) are reachable; any other method 403s. Each allowlist entry declares scope (tab vs browser) and output (trusted vs untrusted) — untrusted methods (data-exfil-shaped, e.g. Network.getResponseBody) get UNTRUSTED-envelope wrapped output. To discover allowed methods: read `browse/src/cdp-allowlist.ts`. Example: `$B cdp Page.getLayoutMetrics`.', usage: 'cdp <Domain.method> [json-params]' },
-};
-
-// Load-time validation: descriptions must cover exactly the command sets
-const allCmds = new Set([...READ_COMMANDS, ...WRITE_COMMANDS, ...META_COMMANDS]);
-const descKeys = new Set(Object.keys(COMMAND_DESCRIPTIONS));
-for (const cmd of allCmds) {
-  if (!descKeys.has(cmd)) throw new Error(`COMMAND_DESCRIPTIONS missing entry for: ${cmd}`);
-}
-for (const key of descKeys) {
-  if (!allCmds.has(key)) throw new Error(`COMMAND_DESCRIPTIONS has unknown command: ${key}`);
-}
-
-/**
- * Command aliases — user-friendly names that route to canonical commands.
- *
- * Single source of truth: server.ts dispatch and meta-commands.ts chain prevalidation
- * both import `canonicalizeCommand()`, so aliases resolve identically everywhere.
- *
- * When adding a new alias: keep the alias name guessable (e.g. setcontent → load-html
- * helps agents migrating from Puppeteer's page.setContent()).
- */
-export const COMMAND_ALIASES: Record<string, string> = {
-  'setcontent': 'load-html',
-  'set-content': 'load-html',
-  'setContent': 'load-html',
-};
-
-/** Resolve an alias to its canonical command name. Non-aliases pass through unchanged. */
-export function canonicalizeCommand(cmd: string): string {
-  return COMMAND_ALIASES[cmd] ?? cmd;
-}
-
-/**
- * Commands added in specific versions — enables future "this command was added in vX"
- * upgrade hints in unknown-command errors. Only helps agents on *newer* browse builds
- * that encounter typos of recently-added commands; does NOT help agents on old builds
- * that type a new command (they don't have this map).
- */
-export const NEW_IN_VERSION: Record<string, string> = {
-  'load-html': '0.19.0.0',
-};
-
-/**
- * Levenshtein distance (dynamic programming).
- * O(a.length * b.length) — fast for command name sizes (<20 chars).
- */
-function levenshtein(a: string, b: string): number {
-  if (a === b) return 0;
-  if (a.length === 0) return b.length;
-  if (b.length === 0) return a.length;
-  const m: number[][] = [];
-  for (let i = 0; i <= a.length; i++) m.push([i, ...Array(b.length).fill(0)]);
-  for (let j = 0; j <= b.length; j++) m[0][j] = j;
-  for (let i = 1; i <= a.length; i++) {
-    for (let j = 1; j <= b.length; j++) {
-      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-      m[i][j] = Math.min(m[i - 1][j] + 1, m[i][j - 1] + 1, m[i - 1][j - 1] + cost);
-    }
-  }
-  return m[a.length][b.length];
-}
-
-/**
- * Build an actionable error message for an unknown command.
- *
- * Pure function — takes the full command set + alias map + version map as args so tests
- * can exercise the synthetic "older-version" case without mutating any global state.
- *
- *   1. Always names the input.
- *   2. If Levenshtein distance ≤ 2 AND input.length ≥ 4, suggests the closest match
- *      (alphabetical tiebreak for determinism). Short-input guard prevents noisy
- *      suggestions for typos of 2-letter commands like 'js' or 'is'.
- *   3. If the input appears in newInVersion, appends an upgrade hint. Honesty caveat:
- *      this only fires on builds that have this handler AND the map entry; agents on
- *      older builds hitting a newly-added command won't see it. Net benefit compounds
- *      as more commands land.
- */
-export function buildUnknownCommandError(
-  command: string,
-  commandSet: Set<string>,
-  aliasMap: Record<string, string> = COMMAND_ALIASES,
-  newInVersion: Record<string, string> = NEW_IN_VERSION,
-): string {
-  let msg = `Unknown command: '${command}'.`;
-
-  // Suggestion via Levenshtein, gated on input length to avoid noisy short-input matches.
-  // Candidates are pre-sorted alphabetically, so strict "d < bestDist" gives us the
-  // closest match with alphabetical tiebreak for free — first equal-distance candidate
-  // wins because subsequent equal-distance candidates fail the strict-less check.
-  if (command.length >= 4) {
-    let best: string | undefined;
-    let bestDist = 3; // sentinel: distance 3 would be rejected by the <= 2 gate below
-    const candidates = [...commandSet, ...Object.keys(aliasMap)].sort();
-    for (const cand of candidates) {
-      const d = levenshtein(command, cand);
-      if (d <= 2 && d < bestDist) {
-        best = cand;
-        bestDist = d;
-      }
-    }
-    if (best) msg += ` Did you mean '${best}'?`;
-  }
-
-  if (newInVersion[command]) {
-    msg += ` This command was added in browse v${newInVersion[command]}. Upgrade: cd ~/.claude/skills/gstack && git pull && bun run build.`;
-  }
-
-  return msg;
-}

package/.agent/skills/gstack-browse/src/config.ts

@@ -1,307 +0,0 @@
-/**
- * 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';
-import { mkdirSecure } from './file-permissions';
-import { safeUnlinkQuiet } from './error-handling';
-import { readConfigKey, resolveStateRoot } from '../../lib/state-root';
-import { remoteSlug } from '../../lib/remote-identity';
-
-export interface BrowseConfig {
-  projectDir: string;
-  stateDir: string;
-  stateFile: string;
-  consoleLog: string;
-  networkLog: string;
-  dialogLog: string;
-  auditLog: 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'], {
-    windowsHide: true,
-      stdout: 'pipe',
-      stderr: 'pipe',
-      // Raised from 2s: under heavy machine load `git rev-parse` routinely
-      // takes >2s (measured 6.3s spikes). Timing out here returns null →
-      // resolveConfig falls back to process.cwd() → state files scatter across
-      // cwds (split-brain daemons; `goto` and `url` hit different servers). 8s
-      // still bounds a genuinely broken .git from hanging the CLI forever.
-      timeout: 8_000,
-    });
-    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'),
-    auditLog: path.join(stateDir, 'browse-audit.jsonl'),
-  };
-}
-
-function isIgnoredByGit(projectDir: string, relPath: string): boolean {
-  try {
-    const proc = Bun.spawnSync(['git', 'check-ignore', '-q', '--', relPath], {
-    windowsHide: true,
-      cwd: projectDir, stdout: 'pipe', stderr: 'pipe',
-      timeout: 2_000,
-    });
-    return proc.exitCode === 0;
-  } catch {
-    // git not found, timed out, or not a repo (exit 128). Fall through to
-    // the text-check path — appending is the safe default when unsure.
-    return false;
-  }
-}
-
-/**
- * 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 {
-    mkdirSecure(config.stateDir);
-  } 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;
-  }
-
-  // Load-bearing guard: a self-contained ignore INSIDE the state dir so its
-  // contents can NEVER be `git add`-ed, regardless of the project's own
-  // .gitignore (which may be absent, or the append below may silently fail).
-  // The state dir holds session-state.json (live cookies + localStorage/
-  // sessionStorage tokens) and browse-network.log / browse-audit.jsonl
-  // (captured request headers can carry bearer tokens). Written unconditionally,
-  // synchronously, before return — the project-.gitignore dance below is now
-  // redundant safety, kept so `.gstack/` still reads as ignored in git status.
-  try {
-    fs.writeFileSync(path.join(config.stateDir, '.gitignore'), '*\n');
-  } catch {
-    // Best-effort; the project-.gitignore path below is the fallback.
-  }
-
-  // Ensure .gstack/ is in the project's .gitignore
-  // First, check if git already ignores .gstack/ (via global excludes, .git/info/exclude, or parent .gitignore)
-  if (isIgnoredByGit(config.projectDir, '.gstack/')) return;
-
-  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 via the shared rule in
- * lib/remote-identity.ts (owner-repo; "<last-two>-<16 hex>" for 3+-segment
- * nested-group remotes, #3003), so browse files state where gstack-slug does.
- * 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'], {
-    windowsHide: true,
-      stdout: 'pipe',
-      stderr: 'pipe',
-      timeout: 2_000,
-    });
-    if (proc.exitCode !== 0) throw new Error('no remote');
-    const slug = remoteSlug(proc.stdout.toString().trim());
-    if (slug) return slug;
-    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;
-  }
-}
-
-/** The gstack state root: delegates to the shared chain in lib/state-root.ts. */
-export function resolveGstackHome(): string {
-  return resolveStateRoot();
-}
-
-/**
- * Read one key from the flat-YAML config store via readConfigKey (the same
- * reader bin/gstack-config uses, including the most-restrictive merge for
- * privacy keys such as telemetry). Tolerates optional single/double quotes
- * around the value and a trailing `# comment`. Returns the unquoted value
- * string, or null when the file is missing or unreadable or the key is absent.
- *
- * Single source of truth for flat-YAML key reads — isPairAgentEnabled
- * (pair_agent) and telemetry.ts (telemetry tier) both route through it so
- * the two consent gates can never drift on parsing semantics.
- */
-export function readGstackConfigYamlKey(key: string): string | null {
-  const raw = readConfigKey(key);
-  if (raw === null) return null;
-  return raw.replace(/\s*#.*$/, '').trim().replace(/^(['"])(.*)\1$/, '$2');
-}
-
-/**
- * Is the remote pair-agent (ngrok tunnel) surface opt-in enabled?
- *
- * Fail-closed: the tunnel exposes the local browser to the internet, so it
- * stays OFF unless the user explicitly ran `gstack-config set pair_agent on`
- * (the /pair-agent skill asks once on first use and sets it). Any read/parse
- * failure (missing config, malformed JSON) also resolves OFF. The tunnel
- * egress receipts cite this gate as their consent — it must exist and gate
- * every activation point (#B6, fork port wave 2).
- *
- * Env override `GSTACK_PAIR_AGENT=on|off` wins (used by tests and as an
- * emergency knob), mirroring the telemetry env-hint convention.
- */
-export function isPairAgentEnabled(): boolean {
-  const env = process.env.GSTACK_PAIR_AGENT;
-  if (env === 'on') return true;
-  if (env === 'off') return false;
-  // Canonical store: ~/.gstack/config.yaml (flat `key: value` lines, written
-  // by bin/gstack-config — which is what the /pair-agent consent step runs).
-  // The fork read config.json; porting that verbatim would have made the gate
-  // silently un-enableable on main. JSON kept as a fallback shape only.
-  // Anything other than exactly on/off (missing key, malformed value) falls
-  // through to the JSON fallback and ultimately fails closed.
-  const yamlValue = readGstackConfigYamlKey('pair_agent');
-  if (yamlValue === 'on') return true;
-  if (yamlValue === 'off') return false;
-  try {
-    const raw = fs.readFileSync(path.join(resolveGstackHome(), 'config.json'), 'utf-8');
-    return JSON.parse(raw)?.pair_agent === 'on';
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Resolve the headed Chromium profile directory.
- *
- * Resolution order:
- *   1. `explicit` arg (no production caller passes one today; kept for
- *      direct programmatic use)
- *   2. CHROMIUM_PROFILE env (used by gbrowser's gbd per-workspace)
- *   3. <project state dir>/chromium-profile (default; per project since D5,
- *      #2492 — a machine-wide profile let one project's headed launch kill
- *      another project's live browser)
- */
-export function resolveChromiumProfile(explicit?: string): string {
-  if (explicit && explicit.length > 0) return explicit;
-  const env = process.env.CHROMIUM_PROFILE;
-  if (env && env.length > 0) return env;
-  return path.join(resolveConfig().stateDir, 'chromium-profile');
-}
-
-/**
- * Pre-launch / shutdown cleanup of stale Chromium singleton lockfiles
- * (SingletonLock, SingletonSocket, SingletonCookie). Chromium's
- * ProcessSingleton refuses to start when these exist from a prior crash
- * (SIGKILL, hard crash, etc.) since they point at a PID that no longer exists.
- *
- * Defensive guard: refuses to operate unless ALL of these hold:
- *   1. `userDataDir` is an absolute path (no CWD-relative footguns)
- *   2. basename is exactly 'chromium-profile' OR the absolute path matches
- *      the absolute form of $CHROMIUM_PROFILE env value
- *
- * Prevents accidentally deleting lock files from an unrelated directory if
- * profile resolution is misconfigured upstream (CWD drift, env injection).
- *
- * Caller MUST ensure external coordination has already guaranteed no live
- * peer is using this profile (gbd.lock for gbrowser; single-instance CLI
- * check for gstack).
- */
-export function cleanSingletonLocks(userDataDir: string): void {
-  if (!path.isAbsolute(userDataDir)) {
-    console.warn(`[browse] cleanSingletonLocks: refusing relative path: ${userDataDir}`);
-    return;
-  }
-  const resolved = path.resolve(userDataDir);
-  const basename = path.basename(resolved);
-  const explicitProfile = process.env.CHROMIUM_PROFILE;
-  const explicitAbs = explicitProfile && path.isAbsolute(explicitProfile)
-    ? path.resolve(explicitProfile)
-    : null;
-  const isSafe = basename === 'chromium-profile' || (explicitAbs !== null && resolved === explicitAbs);
-  if (!isSafe) {
-    console.warn(`[browse] cleanSingletonLocks: refusing to clean unrecognized profile dir: ${resolved}`);
-    return;
-  }
-  for (const lockFile of ['SingletonLock', 'SingletonSocket', 'SingletonCookie']) {
-    safeUnlinkQuiet(path.join(resolved, lockFile));
-  }
-}