Skip to content

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

docs: update building.md to use doctor.sh workflow

Datade5296d210fb
diff --git a/docs/architecture/building.md b/docs/architecture/building.md
index f0471607..65d41264 100644
--- a/docs/architecture/building.md
+++ b/docs/architecture/building.md
@@ -9,6 +9,7 @@ Guide to build PinchTab from source and contribute to the project.
| 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 |
@@ -20,6 +21,31 @@ Guide to build PinchTab from source and contribute to the project.
---
+## Quick Start
+
+**Fastest way to get started:**
+
+```bash
+# 1. Clone
+git clone https://github.com/pinchtab/pinchtab.git
+cd pinchtab
+
+# 2. Run doctor (verifies environment + auto-installs hooks/deps)
+./doctor.sh
+
+# 3. Build and run
+go build ./cmd/pinchtab
+./pinchtab
+```
+
+The `doctor.sh` script will:
+- ✅ Check Go 1.25+ (tells you to install if missing)
+- ✅ Check golangci-lint (tells you to install if missing)
+- 🔧 Auto-install git hooks
+- 🔧 Auto-download Go dependencies
+
+---
+
## Part 1: Prerequisites
### Install Go
@@ -43,6 +69,27 @@ 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:**
+```bash
+brew install golangci-lint
+```
+
+**Or via Go:**
+```bash
+go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
+```
+
+Verify:
+```bash
+golangci-lint --version
+```
+
### Install Chrome/Chromium
**macOS (Homebrew):**
@@ -60,29 +107,22 @@ sudo apt install -y chromium-browser
sudo yum install -y chromium
```
-### Verify Installations
+### Automated Setup
-```bash
-go version # go version go1.25.0 darwin/arm64
-git --version # git version 2.39.0
-chromium --version # Chromium 120.0.6099.xx
-```
-
-### Install Dependencies
-
-Clone the repository and download Go modules:
+After installing Go and golangci-lint, run:
```bash
git clone https://github.com/pinchtab/pinchtab.git
cd pinchtab
-go mod download
+./doctor.sh
```
-Verify:
-```bash
-go mod verify # Verifies all checksums
-go list -m all # List all dependencies
-```
+This verifies your environment and automatically:
+- Installs git hooks (gofmt + golangci-lint on commit)
+- Downloads Go modules
+- Checks for optional tools (Node/Bun for dashboard)
+
+You can run `./doctor.sh` anytime to verify or fix your environment.
---
@@ -161,27 +201,31 @@ curl http://localhost:9867/health
### Run Tests
```bash
-go test ./... -v
+go test ./... # All tests
+go test ./... -v # Verbose
go test ./... -v -coverprofile=coverage.out
-go tool cover -html=coverage.out # View coverage
+go tool cover -html=coverage.out # View coverage
```
### Code Quality
```bash
-gofmt -w . # Format code
-golangci-lint run ./... # Lint (install if needed)
-./scripts/check.sh # Run all checks
+gofmt -w . # Format code
+golangci-lint run # Lint
+./doctor.sh # Verify environment
```
-### Pre-Commit Hook
+### Git Hooks
+Git hooks are auto-installed by `./doctor.sh`. They run on every commit:
+- `gofmt` — Format check
+- `golangci-lint` — Linting
+
+To manually reinstall hooks:
```bash
-./scripts/setup-hooks.sh
+./scripts/install-hooks.sh
```
-Automatically runs checks before committing.
-
### Development Workflow
```bash
@@ -192,22 +236,19 @@ git checkout -b feat/my-feature
# ... edit files ...
# 3. Test
-go test ./... -v
-
-# 4. Format & lint
-gofmt -w .
-golangci-lint run ./...
+go test ./...
-# 5. Commit
-git add .
+# 4. Commit (hooks run automatically)
git commit -m "feat: description"
-# 6. Push
+# 5. Push
git push origin feat/my-feature
-# 7. Create PR on GitHub
+# 6. Create PR on GitHub
```
+**Note:** Git hooks will automatically format and lint your code on commit. If checks fail, the commit is blocked.
+
---
## Continuous Integration
@@ -255,11 +296,51 @@ pinchtab --version
---
+## Troubleshooting
+
+### Environment Issues
+
+**First step:** Run doctor to verify your setup:
+```bash
+./doctor.sh
+```
+
+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: `./doctor.sh` (auto-installs)
+
+**"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. All dependencies installed?
-2. Go and Chrome versions correct?
+1. Run `./doctor.sh` first
+2. All dependencies installed and correct versions?
3. Port 9867 available?
4. Check logs: `tail -f pinchtab.log`