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 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.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 the default E2E release suite
./dev e2e docker                          # Build the local image and run Docker smoke
./dev e2e pr                              # Run API fast + CLI fast
./dev e2e api-full                        # Run the multi-instance API suite
./dev e2e cli-full                        # Run the single-instance CLI full suite

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`	Run all tests
`test unit`	Unit tests only
`test dashboard`	Dashboard tests only
`e2e`	Run the default E2E release suite (`api-full` + `cli-full`)
`e2e docker`	Build the local image and run the Docker smoke test
`e2e pr`	Run the PR E2E suite (`api-fast` + `cli-fast`)
`e2e api-fast`	Run the fast API E2E suite on the single-instance stack
`e2e cli-fast`	Run the fast CLI E2E suite on the single-instance stack
`e2e api-full`	Run the full API E2E suite on the multi-instance stack
`e2e cli-full`	Run the full CLI E2E suite on the single-instance stack
`e2e release`	Run the release E2E meta-suite
`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 (fast suites) + manual (full 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 Docker 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

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

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

Support

Issues? Check:

Run ./dev doctor first
All dependencies installed and correct versions?
Port 9867 available?
Check logs: tail -f pinchtab.log

See docs/ for guides and examples.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Contributing

System Requirements

Minimum Requirements

Recommended Setup

Quick Start

Part 1: Prerequisites

Install Go

Install golangci-lint (Required)

Install gotestsum (Recommended)

Install Chrome/Chromium

Automated Setup

Part 2: Build the Project

Simple Build

Part 3: Run the Server

Start (Headless)

Start (Headed Mode)

Background

Part 4: Quick Test

Health Check

Try CLI

Development

Run Tests

Developer Toolkit (`dev`)

Code Quality

Git Hooks

Development Workflow

Continuous Integration

CI Checks

Release Pipeline

Installation as CLI

From Source

Via npm (released builds)

Resources

Troubleshooting

Environment Issues

Common Issues

Support

FilesExpand file tree

contributing.md

Latest commit

History

contributing.md

File metadata and controls

Contributing

System Requirements

Minimum Requirements

Recommended Setup

Quick Start

Part 1: Prerequisites

Install Go

Install golangci-lint (Required)

Install gotestsum (Recommended)

Install Chrome/Chromium

Automated Setup

Part 2: Build the Project

Simple Build

Part 3: Run the Server

Start (Headless)

Start (Headed Mode)

Background

Part 4: Quick Test

Health Check

Try CLI

Development

Run Tests

Developer Toolkit (dev)

Code Quality

Git Hooks

Development Workflow

Continuous Integration

CI Checks

Release Pipeline

Installation as CLI

From Source

Via npm (released builds)

Resources

Troubleshooting

Environment Issues

Common Issues

Support

Developer Toolkit (`dev`)