Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

12.1 KB
Raw Blame

Contributing

This is the canonical contributor and development guide for PinchTab.

System Requirements

Minimum Requirements

Requirement Version Purpose
Go 1.26+ (go.mod) Build language
golangci-lint Latest Linting (required for pre-commit hooks)
Chrome/Chromium Latest Browser automation
macOS, Linux, or WSL2 Current OS support

For dashboard work, use Bun 1.2+. Older Bun releases fail on the checked-in dashboard/bun.lock during clean installs with --frozen-lockfile.

Recommended Setup

  • macOS: Homebrew for package management
  • Linux: apt (Debian/Ubuntu) or yum (RHEL/CentOS)
  • WSL2: Full Linux environment (not WSL1)

Quick Start

Fastest way to get started:

# 1. Clone
git clone https://github.com/pinchtab/pinchtab.git
cd pinchtab

# 2. Run doctor (verifies environment, prompts before installing anything)
./dev doctor

# 3. Build and run
go build ./cmd/pinchtab
./pinchtab server

Example output:

  πŸ¦€ Pinchtab Doctor
  Verifying and setting up development environment...

Go Backend
  βœ“ Go 1.26.0
  βœ— golangci-lint
    Required for pre-commit hooks and CI.
    Install golangci-lint via brew? [y/N] y
    βœ“ golangci-lint installed
  βœ“ Git hooks
  βœ“ Go dependencies

Dashboard (React/TypeScript)
  βœ“ Node.js 22.15.1
  Β· Bun not found
    Optional β€” used for fast dashboard builds.
    Install Bun? [y/N] n
    curl -fsSL https://bun.sh/install | bash

Summary

  Β· 1 warning(s)

The doctor asks for confirmation before installing anything. If you decline, it shows the manual install command instead.


Part 1: Prerequisites

Install Go

macOS (Homebrew):

brew install go
go version  # Verify: go1.26.0 or newer

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install -y golang-go git build-essential
go version

Linux (RHEL/CentOS):

sudo yum install -y golang git
go version

Or download from: https://go.dev/dl/

Install golangci-lint (Required)

Required for pre-commit hooks:

macOS/Linux:

brew install golangci-lint

Or via Go:

go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

Verify:

golangci-lint --version

Install gotestsum (Recommended)

Recommended for the cleaner local unit test output used by ./dev test unit:

go install gotest.tools/gotestsum@latest

Install Chrome/Chromium

macOS (Homebrew):

brew install chromium

Linux (Ubuntu/Debian):

sudo apt install -y chromium-browser

Linux (RHEL/CentOS):

sudo yum install -y chromium

Automated Setup

After cloning, run doctor to verify and set up your environment:

git clone https://github.com/pinchtab/pinchtab.git
cd pinchtab
./dev doctor

Doctor checks your environment and asks before installing anything:

  • Go 1.26+ and golangci-lint (offers brew install or go install)
  • Git hooks (copies pre-commit hook)
  • Go dependencies (go mod download)
  • Node.js, Bun, and dashboard deps (optional, for dashboard development)

Run ./dev doctor anytime to verify or fix your environment.


Part 2: Build the Project

Simple Build

go build -o pinchtab ./cmd/pinchtab

What it does:

  • Compiles Go source code
  • Produces binary: ./pinchtab
  • Takes ~30-60 seconds

Note: This builds the Go server only. The dashboard will show a "not built" placeholder. To include the full React dashboard, use ./dev build instead β€” it builds the dashboard, compiles Go, and runs the server in one step. Or run ./scripts/build-dashboard.sh before go build.

Verify:

ls -la pinchtab
./pinchtab --version

Part 3: Run the Server

Start (Headless)

./pinchtab server

The server listens on 127.0.0.1:9867 and requires the server.token from your config on every request (./pinchtab config token --stdout prints it). Add -v for the full startup banner.

Start (Headed Mode)

./pinchtab server --headed

Opens Chrome in the foreground for the default instance.

Background

./pinchtab server --background        # spawns detached, prints JSON with pid/url/token
./pinchtab server -b                  # short form

The --background flag forks a properly detached server process and returns {"pid": ..., "url": ..., "token": ...} on stdout, so scripts can capture the URL/token without log scraping. For a longer-lived install, use pinchtab daemon install instead.


Part 4: Quick Test

Health Check

./pinchtab health
# or, with the token:
curl -H "Authorization: Bearer $(./pinchtab config token --stdout)" http://localhost:9867/health

Try CLI

./pinchtab nav https://pinchtab.com --snap
./pinchtab snap

Development

Run Tests

go test ./...                              # Unit tests only
go test ./... -v                           # Verbose
go test ./... -v -coverprofile=coverage.out
go tool cover -html=coverage.out           # View coverage
./dev e2e                                 # Run the default extended E2E suite
./dev e2e basic                           # Run API + CLI + Infra basic tests
./dev e2e smoke                           # Run CI smoke scenarios + host Docker smoke checks
./dev smoke                               # Run all local smoke categories
./dev smoke --browser=cloak              # Run all local CloakBrowser smoke categories
./dev e2e api                             # Run API basic tests
./dev e2e cli                             # Run CLI basic tests
./dev e2e infra                           # Run Infra basic tests
./dev e2e api-extended                    # Run API extended (multi-instance)
./dev e2e cli-extended                    # Run CLI extended tests
./dev e2e infra-extended                  # Run Infra extended (multi-instance)

Developer Toolkit (dev)

All dev scripts are accessible through ./dev:

./dev              # Interactive picker (uses gum if installed, numbered fallback)
./dev check        # Run a command directly
./dev test unit    # Subcommands supported
./dev --help       # List all commands

dev interactive menu

Available commands:

Command Description
check All checks (Go + Dashboard)
check go Go checks only
check dashboard Dashboard checks only
check security Gosec security scan
check docs Validate docs JSON
format dashboard Run Prettier on dashboard sources
test Run all tests
test unit Unit tests only
test dashboard Dashboard tests only
e2e Run the default extended E2E suite
e2e basic Run the PR E2E suite (api + cli + infra basic tests)
e2e smoke Run smoke scenarios plus host Docker smoke checks
smoke cloakbrowser Run opt-in CloakBrowser Docker smoke using tests/tools/docker/cloakbrowser-smoke.Dockerfile
e2e api Run API basic tests
e2e cli Run CLI basic tests
e2e infra Run Infra basic tests
e2e api-extended Run API extended tests (multi-instance)
e2e cli-extended Run CLI extended tests
e2e infra-extended Run Infra extended tests (multi-instance)
build Build the application
dev Build and run the application
run Run the application
binary Build the local release-style binary
doctor Setup dev environment

For the fancy interactive picker, install gum: brew install gum

Tip: Add this to ~/.zshrc to use dev without ./:

dev() { if [ -x "./dev" ]; then ./dev "$@"; else echo "dev not found in current directory"; return 1; fi }

Code Quality

./dev check              # Full non-test checks (recommended)
./dev format dashboard   # Fix dashboard formatting
gofmt -w .                # Format code
golangci-lint run         # Lint
./dev doctor             # Verify environment

Git Hooks

Git hooks are installed by ./dev doctor (or ./scripts/install-hooks.sh). They run on every commit:

  • gofmt β€” Format check
  • golangci-lint β€” Linting
  • prettier β€” Dashboard formatting

To manually reinstall hooks:

./scripts/install-hooks.sh

Development Workflow

# 1. Setup (first time)
./dev doctor

# 2. Create feature branch
git checkout -b feat/my-feature

# 3. Make changes
# ... edit files ...

# 4. Run checks before pushing
./dev check

# 5. Commit (hooks run automatically)
git commit -m "feat: description"

# 6. Push
git push origin feat/my-feature

Note: Git hooks will automatically format and lint your code on commit. If checks fail, the commit is blocked.


Continuous Integration

Workflows follow a naming convention:

Prefix Purpose Example
ci-* Automatic checks on PR/push ci-go.yml β†’ CI / Go
reusable-* Building blocks (workflow_call only) reusable-e2e.yml β†’ Reusable / E2E
release-* Release pipeline release.yml β†’ Release

CI Checks

Run automatically on pull requests and/or push to main:

Workflow Triggers What it checks
CI / Go PR + push gofmt, vet, build, tests, coverage, lint, security
CI / Dashboard PR + push (dashboard paths) TypeScript, ESLint, Prettier, tests, build
CI / Docs PR + push (docs paths) docs.json reference validation
CI / npm PR (npm paths) + tag push npm package verification
CI / E2E PR basic suites + manual extended/smoke suites Docker-based end-to-end tests
CI / Branch Naming PR Branch name convention enforcement

Release Pipeline

Workflow Trigger What it does
Release Manual Runs all checks + E2E β†’ manual approval gate β†’ creates tag β†’ publishes binaries, npm, Docker, and skill
Release / Manual Publish Manual Publishes an existing tag as a recovery path

In Release, E2E and smoke failures are non-blocking β€” they surface in the approval summary so you can decide whether to proceed. Core checks (Go, Dashboard, Docs, npm, publish dry-run) must pass for the approval gate to appear.


Installation as CLI

From Source

go build -o ~/go/bin/pinchtab ./cmd/pinchtab

Then use anywhere:

pinchtab help
pinchtab --version

Via npm (released builds)

npm install -g pinchtab
pinchtab --version

Resources


Troubleshooting

Environment Issues

First step: Run doctor to verify your setup:

./dev doctor

This will tell you exactly what's missing or misconfigured.

Common Issues

"Go version too old"

"golangci-lint: command not found"

  • Install: brew install golangci-lint
  • Or: go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

"Git hooks not running on commit"

  • Run: ./scripts/install-hooks.sh
  • Or: ./dev doctor (prompts to install)

"Chrome not found"

  • Install Chromium: brew install chromium (macOS)
  • Or: sudo apt install chromium-browser (Linux)

"Port 9867 already in use"

  • Check: lsof -i :9867
  • Stop other instance or change the port via config: pinchtab config set server.port 9868

Build fails

  1. Verify dependencies: go mod download
  2. Clean cache: go clean -cache
  3. Rebuild: go build ./cmd/pinchtab

Support

Issues? Check:

  1. Run ./dev doctor first
  2. All dependencies installed and correct versions?
  3. Port 9867 available?
  4. Check logs: a foreground server logs to its terminal; pinchtab server --background writes <server.stateDir>/server.log; the daemon writes ~/.pinchtab/logs/daemon.err.log

See docs/ for guides and examples.