High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: update
Luigi Agostie949d8adaf50
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.mdindex 1402d328..079ac0b8 100644--- a/CODE_OF_CONDUCT.md+++ b/CODE_OF_CONDUCT.md@@ -34,7 +34,7 @@ This Code of Conduct applies both within project spaces and in public spaces whe## Enforcement-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [INSERT EMAIL ADDRESS]. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [email protected]. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 050f9915..e104aa31 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -1,67 +1,21 @@-# Contributing to Pinchtab+# Contributing to PinchTab-## Setup+This repository keeps one detailed contributor guide:-```bash-git clone https://github.com/pinchtab/pinchtab.git-cd pinchtab-./dev doctor-```--Requires **Go 1.25+** and **Google Chrome**.+- [docs/guides/contributing.md](docs/guides/contributing.md)-## Development Workflow+Use that guide for setup, build commands, tests, hooks, and the day-to-day development workflow.-1. Make your changes-2. Run `./dev check`-3. Run `./dev test`-4. Commit — pre-commit hook runs checks automatically-5. Push: `git pull --rebase && git push`--### Creating a Pull Request--**Important:** When creating a PR, please keep the **"Allow edits from maintainers"** checkbox **enabled** (it's on by default). This lets us:--- Apply small fixes directly-- Resolve merge conflicts automatically-- Rebase and update your branch without asking--This significantly speeds up the merge process. Thank you! 🙏--## Checks and Tests+## Quick Start```bash-./dev doctor # setup environment and hooks-./dev check # format, vet, build, lint-./dev format dashboard-./dev test # unit + E2E tests-./dev test unit # unit tests only-./dev e2e # E2E tests (curl + CLI)-./dev e2e curl # curl tests only-./dev e2e cli # CLI tests only-```--If you want the raw commands instead of `dev`:--```bash-go test ./... -count=1 -v-./dev e2e+git clone https://github.com/pinchtab/pinchtab.git+cd pinchtab+./dev doctor+./dev check+./dev test unit```-## Style+## Pull Requests-- Adhere to **SOLID** principles, specifically using interfaces for dependency inversion.-- Handle all error returns explicitly.-- Lowercase error strings, wrap with `%w`.-- Tests should live in the same package as the source code.-- No new dependencies without significant technical justification.-- Comments when necessary--## Hooks--`./dev doctor` offers to install the git hooks. They enforce formatting and checks before commit.-You can also install them directly with:--```bash-./scripts/install-hooks.sh-```+Please keep GitHub's "Allow edits from maintainers" option enabled on your PRs. It makes small fixes, rebases, and merge-conflict resolution much faster.diff --git a/DEVELOPMENT.md b/DEVELOPMENT.mdindex 3f9a2584..778bdcc8 100644--- a/DEVELOPMENT.md+++ b/DEVELOPMENT.md@@ -1,251 +1,7 @@# Development Setup-## Prerequisites+This document has been consolidated into the main contributor guide:-- **Go 1.25+**-- **Git**-- **golangci-lint** (required for pre-commit hooks)+- [docs/guides/contributing.md](docs/guides/contributing.md)-## Quick Start--```bash-# 1. Clone-git clone https://github.com/pinchtab/pinchtab.git-cd pinchtab--# 2. Setup (checks environment, installs hooks, downloads deps)-./doctor.sh--# 3. Build and run-go build ./cmd/pinchtab-./pinchtab-```--**Example output:**-```-🩺 Pinchtab Doctor-Verifying and setting up development environment...--━━━ Go Backend Requirements ━━━--✅ Go 1.26.0-✅ golangci-lint 2.9.0-⚠️ Git hooks not installed- Installing git hooks...- ✅ Git hooks installed-✅ Go dependencies--━━━ Dashboard Requirements (React/TypeScript) ━━━--✅ Node.js 22.22.0-⚠️ Bun- Optional for dashboard. Install: curl -fsSL https://bun.sh/install | bash--━━━ Summary ━━━--✅ Setup complete! Auto-installed missing components.--Next steps:- go build ./cmd/pinchtab # Build pinchtab- go test ./... # Run tests-```--That's it! `doctor.sh` verifies your environment and auto-installs what it can (git hooks, dependencies). Git hooks will run automatically on every commit.--## Detailed Setup--### 1. Clone the repository--```bash-git clone https://github.com/pinchtab/pinchtab.git-cd pinchtab-```--### 2. Run doctor script--```bash-./doctor.sh-```--This will:-- **Check** Go 1.25+ and golangci-lint (tells you to install if missing)-- **Auto-install** git hooks (gofmt + golangci-lint checks before commit)-- **Auto-download** Go dependencies-- **Check** Node.js / Bun for dashboard (optional, warns if missing)--### 3. Install missing tools (if needed)--If doctor.sh finds missing critical tools, install them:--**Go 1.25+:**-- Download from https://go.dev/dl/--**golangci-lint (required for pre-commit hooks):**-```bash-# macOS/Linux-brew install golangci-lint--# Or via Go-go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest-```--After installing, run `./doctor.sh` again to verify.--## Before Committing--Git hooks automatically run on `git commit`. To manually check your code:--```bash-# Format code-gofmt -w .--# Run linter-golangci-lint run--# Run tests-go test ./...-```--## Common Issues--### "Git hooks not running on commit"--Re-run setup:-```bash-./scripts/install-hooks.sh-```--Verify hooks installed:-```bash-cat .git/hooks/pre-commit-```--### "golangci-lint: command not found" during commit--Hooks will warn but still allow commit. To fix:-```bash-brew install golangci-lint-# or-go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest-```--### gofmt fails in CI even though local commit worked--Run format before committing:-```bash-gofmt -w .-```--### Tests failing locally--```bash-# Run full test suite-go test ./...--# Run with verbose output-go test -v ./...--# Run specific test-go test -run TestName ./...-```--## Running Tests--```bash-# All tests-go test ./...--# Verbose output-go test -v ./...--# Specific test-go test -run TestName ./...--# With coverage-go test -cover ./...--# Generate coverage report-go test -coverprofile=coverage.out ./...-go tool cover -html=coverage.out-```--## Code Style--- **Format:** `gofmt` (automatic via git hook, or run `gofmt -w .`)-- **Lint:** `golangci-lint` (automatic via git hook, or run `golangci-lint run`)-- **Tests:** Must pass (`go test ./...`)--## Git Workflow--```bash-# 1. Create branch-git checkout -b feature/your-feature--# 2. Make changes-# ... edit files ...--# 3. Test your changes-go test ./...--# 4. Commit (git hooks run automatically: gofmt + lint)-git commit -m "feat: description"--# 5. Push-git push origin feature/your-feature--# 6. Create Pull Request on GitHub-```--**Note:** Git hooks automatically run `gofmt` and `golangci-lint` on staged files before each commit. If checks fail, the commit is blocked.--## Documentation--Update docs when adding features:--```bash-# Docs location-docs/-├── core-concepts.md-├── get-started.md-├── references/-├── architecture/-└── guides/-```--Validate docs: `./scripts/check-docs-json.sh`--## Useful Commands--```bash-# Setup & Verification-./doctor.sh # Check environment + auto-install hooks/deps-./scripts/install-hooks.sh # Manually re-install git hooks--# Build & Run-go build ./cmd/pinchtab # Build pinchtab binary-go run ./cmd/pinchtab # Build and run-go clean # Clean build cache--# Code Quality-gofmt -w . # Format all files-gofmt -l . # List files that need formatting-golangci-lint run # Run linter--# Testing-go test ./... # Run all tests-go test -v ./... # Verbose output-go test -run TestName ./... # Specific test-go test -cover ./... # With coverage--# Dependencies-go mod download # Download dependencies-go mod tidy # Clean up go.mod-go get -u ./... # Update dependencies-```--## Getting Help--- Read the [Overview](docs/overview.md)-- Check [Architecture](docs/architecture/pinchtab-architecture.md)-- See [API Reference](docs/references/instance-api.md)-- Browse [Guides](docs/guides/)+Use that page as the source of truth for environment setup, building, testing, hooks, and contributor workflow.diff --git a/README.md b/README.mdindex a99149f7..7fa0567a 100644--- a/README.md+++ b/README.md@@ -336,18 +336,17 @@ See [chrome-files.md](chrome-files.md) for technical details on how PinchTab man## Development-Want to contribute? See [DEVELOPMENT.md](DEVELOPMENT.md) for setup instructions.+Want to contribute? Start with [CONTRIBUTING.md](CONTRIBUTING.md).+The full setup and workflow guide lives at [docs/guides/contributing.md](docs/guides/contributing.md).**Quick start:**```bashgit clone https://github.com/pinchtab/pinchtab.gitcd pinchtab-./doctor.sh # Verifies environment, installs hooks/deps+./dev doctor # Verifies environment, offers hooks/deps setupgo build ./cmd/pinchtab # Build pinchtab binary```-See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.----## Licensediff --git a/docs/guides/contributing.md b/docs/guides/contributing.mdindex ace8b348..900fa3b1 100644--- a/docs/guides/contributing.md+++ b/docs/guides/contributing.md@@ -1,6 +1,6 @@# Contributing-Guide to build PinchTab from source and contribute to the project.+This is the canonical contributor and development guide for PinchTab.## System Requirements