gstack/skills/qa/references/legacy/setup-browser-cookies.md

Host-neutral runtime bindings

These assignments select stable paths only; they do not install anything or grant consent:

GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
GSTACK_ROOT="$GSTACK_HOME"
GSTACK_STATE_ROOT="$GSTACK_HOME"
GSTACK_BIN="$GSTACK_HOME/bin"
BUN_CMD="$GSTACK_BIN/bun"
B="$GSTACK_BIN/browse"
D="$GSTACK_BIN/gstack-design"
P="$GSTACK_BIN/make-pdf"

Visible-browser point-of-use gate

This workflow may require internal browser-visible because it reaches a headed browser, extension, interactive cookie picker, or browser handoff. Do not offer visible Chromium during ordinary headless QA.

At the first actual visible-browser step, ask whether the user wants to check official setup options and exact sizes. Disclose that an uncached preview makes one public GitHub signed-manifest request and sends no repository/private data, then STOP. Only after that approval run node references/support/runtime-bootstrap.mjs preview --capability browser-visible. It expands to core + browser-code + browser-visible for a first install, but an existing verified headless runtime downloads only missing browser-visible; it never requires browser-headless. Show the exact missing components and summed incremental compressed bytes, then STOP again for separate install approval. Only after install approval run node references/support/runtime-bootstrap.mjs install --capability browser-visible --yes, recheck readiness, and resume the interrupted step.

Setup Browser Cookies

Import logged-in sessions from your real Chromium browser into the headless browse session.

CDP mode check

First, check if browse is already connected to the user's real browser:

$B status 2>/dev/null | grep -q "Mode: cdp" && echo "CDP_MODE=true" || echo "CDP_MODE=false"

If CDP_MODE=true: tell the user "Not needed — you're connected to your real browser via CDP. Your cookies and sessions are already available." and stop. No cookie import needed.

How it works

1. Find the browse binary
2. Run cookie-import-browser to detect installed browsers and open the picker UI
3. User selects which cookie domains to import in their browser
4. Cookies are decrypted and loaded into the Playwright session

Steps

1. Find the browse binary

SETUP (run this check BEFORE any browse command)

_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
B=""
[ -n "$_ROOT" ] && [ -x "$GSTACK_BIN/browse" ] && B="$GSTACK_BIN/browse"
[ -z "$B" ] && B="${GSTACK_HOME:-$HOME/.gstack}/bin/browse"
if [ -x "$B" ]; then
  echo "READY: $B"
else
  echo "NEEDS_SETUP"
fi

If NEEDS_SETUP:

1. Tell the user: "The optional managed headless browser capability is missing. Do you want to preview its exact dependency-closed component plan and compressed bytes now?" Then STOP and wait.
2. Read references/RUNTIME.md and follow its explicit capability bootstrap. Never assume a standard-installed skill directory contains ./setup.
3. The approved managed runtime includes its own pinned Bun at $GSTACK_BIN/bun; never download or install another Bun from a skill workflow.

2. Open the cookie picker

$B cookie-import-browser

This auto-detects installed Chromium browsers and opens an interactive picker UI in your default browser where you can:

• Switch between installed browsers
• Search domains
• Click "+" to import a domain's cookies
• Click trash to remove imported cookies

Tell the user: "Cookie picker opened — select the domains you want to import in your browser, then tell me when you're done."

3. Direct import (alternative)

If the user specifies a domain directly (e.g., $qa --mode Report --module setup-browser-cookies github.com), skip the UI:

$B cookie-import-browser comet --domain github.com

Replace comet with the appropriate browser if specified.

4. Verify

After the user confirms they're done:

$B cookies

Show the user a summary of imported cookies (domain counts).

Notes

• On macOS, the first import per browser may trigger a Keychain dialog — click "Allow" / "Always Allow"
• On Linux, v11 cookies may require secret-tool/libsecret access; v10 cookies use Chromium's standard fallback key
• Cookie picker is served on the same port as the browse server (no extra process)
• Only domain names and cookie counts are shown in the UI — no cookie values are exposed
• The browse session persists cookies between commands, so imported cookies work immediately

Upstream judgment port: PR #679

Match the user language

User-language rule

Write questions, progress updates, reports, and artifacts in the language used by the user. Source material, code identifiers, commands, and quotations may remain in their original language when translating them would reduce accuracy.