docs/guides/contributing.md

Contributing

This is the canonical contributor and development guide for PinchTab.

System Requirements

Minimum Requirements

Requirement	Version	Purpose
Go	1.25+	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

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: go version go1.25.0

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 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.25+ 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

Expected output:

🦀 PINCH! PINCH! port=9867
auth disabled (set PINCHTAB_TOKEN to enable)

Start (Headed Mode)

BRIDGE_HEADLESS=false ./pinchtab

Opens Chrome in the foreground.

Background

nohup ./pinchtab > pinchtab.log 2>&1 &
tail -f pinchtab.log  # Watch logs

---

Part 4: Quick Test

Health Check

curl http://localhost:9867/health

Try CLI

./pinchtab quick https://pinchtab.com
./pinchtab nav https://pinchtab.com
./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 E2E tests (curl + CLI)

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

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	Unit + E2E tests
test unit	Unit tests only
e2e	E2E tests (curl + CLI)
e2e curl	E2E curl tests only
e2e cli	E2E CLI tests only
build	Build & run (default)
run	Run the application
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

GitHub Actions automatically runs on push:

• Format checks (gofmt)
• Vet checks (go vet)
• Build verification
• Full test suite with coverage
• Linting (golangci-lint)

See .github/workflows/ for details.

---

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

• GitHub Repository: https://github.com/pinchtab/pinchtab
• Go Documentation: https://golang.org/doc/
• Chrome DevTools Protocol: https://chromedevtools.github.io/devtools-protocol/
• Chromedp Library: https://github.com/chromedp/chromedp

---

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"

• Install Go 1.25+ from https://go.dev/dl/
• Verify: go version

"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 use different port: BRIDGE_PORT=9868 ./pinchtab

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: tail -f pinchtab.log

See docs/ for guides and examples.