Skip to content

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

feat: add automated development setup with Makefile

Datab12ff5ae7557
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 4a73455e..f32377f7 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -3,77 +3,107 @@
## Prerequisites
- **Go 1.25+**
-- **Python 3.8+** (for pre-commit)
- **Git**
+- **golangci-lint** (optional, for local linting)
-## Setup
-
-### 1. Clone the repository
+## Quick Start
```bash
+# 1. Clone
git clone https://github.com/pinchtab/pinchtab.git
cd pinchtab
+
+# 2. Setup (installs git hooks, downloads deps)
+make setup
+
+# 3. Build and run
+make build
+./pinchtab
```
-### 2. Install pre-commit hooks
+That's it! Git hooks are installed automatically and will run on every commit.
-This ensures gofmt and linting checks run **before** you commit.
+## Detailed Setup
+
+### 1. Clone the repository
```bash
-# Install pre-commit framework (one-time)
-pip install pre-commit
-# or: brew install pre-commit
+git clone https://github.com/pinchtab/pinchtab.git
+cd pinchtab
+```
-# Setup git hooks in this repo
-pre-commit install
+### 2. Run automated setup
-# (Optional) Run hooks on all files to verify setup
-pre-commit run --all-files
+```bash
+make setup
```
-### 3. Verify Go environment
+This will:
+- Install git hooks (gofmt + golangci-lint checks before commit)
+- Download Go dependencies
+- Verify your environment
+
+### 3. (Optional) Install golangci-lint
+
+For local linting (recommended):
```bash
-go version # Should be 1.25+
-go mod download
+# macOS/Linux
+brew install golangci-lint
+
+# Or via Go
+go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
```
+Without golangci-lint, commits will still work but won't check linting locally.
+
## Before Committing
-The pre-commit hooks will automatically run on `git commit`. If you need to manually format:
+Git hooks automatically run on `git commit`. To manually check your code:
```bash
-# Format all Go code
-./scripts/format.sh
+# Format code
+make fmt
+
+# Run linter
+make lint
-# Or directly
-gofmt -w .
+# Run tests
+make test
-# Run linters manually
-pre-commit run --all-files
+# All checks (format + lint + test)
+make check
```
## Common Issues
-### "pre-commit: command not found"
+### "Git hooks not running on commit"
-Install pre-commit:
+Re-run setup:
```bash
-pip install pre-commit
-# or
-brew install pre-commit
+make install-hooks
```
-Then setup hooks:
+Verify hooks installed:
```bash
-pre-commit install
+cat .git/hooks/pre-commit
```
-### gofmt fails in CI even though pre-commit passed locally
+### "golangci-lint: command not found" during commit
-- Ensure you ran `pre-commit install` (not just installed the tool)
-- Verify hooks are installed: `cat .git/hooks/pre-commit`
-- Try updating: `pre-commit autoupdate`
+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
+make fmt
+```
### Tests failing locally
@@ -92,21 +122,25 @@ go test -run TestName ./...
```bash
# All tests
-go test ./...
+make test
-# With coverage
-go test -cover ./...
+# With coverage report
+make test-cover
+# Opens coverage.html in browser
+```
-# Generate coverage report
-go test -coverprofile=coverage.out ./...
-go tool cover -html=coverage.out
+Or directly with Go:
+```bash
+go test ./... # All tests
+go test -v ./... # Verbose
+go test -run TestName ./... # Specific test
```
## Code Style
-- **Format:** `gofmt` (automatic via pre-commit)
-- **Lint:** `golangci-lint` (automatic via pre-commit)
-- **Docs:** Files in `docs/` should follow Markdown standards (checked via pre-commit)
+- **Format:** `gofmt` (automatic via git hook, or run `make fmt`)
+- **Lint:** `golangci-lint` (automatic via git hook, or run `make lint`)
+- **Tests:** Must pass (`make test`)
## Git Workflow
@@ -117,11 +151,10 @@ git checkout -b feature/your-feature
# 2. Make changes
# ... edit files ...
-# 3. Format and test
-./scripts/format.sh
-go test ./...
+# 3. Check your work (optional, hooks will run on commit)
+make check
-# 4. Commit (pre-commit hooks run automatically)
+# 4. Commit (git hooks run automatically: gofmt + lint)
git commit -m "feat: description"
# 5. Push
@@ -130,6 +163,8 @@ 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:
@@ -149,23 +184,25 @@ Validate docs: `./scripts/check-docs-json.sh`
## Useful Commands
```bash
-# Format without committing
-gofmt -w .
-
-# Check what would be formatted
-gofmt -l .
-
-# Run specific linter
-golangci-lint run
-
-# Clean build artifacts
-go clean
-
-# Update dependencies
-go get -u ./...
-
-# List all test functions
-go test -list .
+# Development
+make setup # Setup dev environment (run once)
+make build # Build pinchtab binary
+make run # Build and run
+make fmt # Format code
+make lint # Run linter
+make test # Run tests
+make test-cover # Run tests with coverage
+make check # Format + lint + test
+make clean # Remove build artifacts
+make help # Show all commands
+
+# Direct Go commands
+gofmt -w . # Format all files
+gofmt -l . # List files that need formatting
+go test ./... # Run all tests
+go test -v ./... # Verbose tests
+go clean # Clean build cache
+go get -u ./... # Update dependencies
```
## Getting Help
diff --git a/Makefile b/Makefile
new file mode 100644
index 00000000..cdbd25f9
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,85 @@
+.PHONY: setup install-hooks test lint fmt check build clean help
+
+## Setup (run once after clone)
+setup: install-hooks
+ @echo "✅ Development environment ready!"
+ @echo ""
+ @echo "Next steps:"
+ @echo " make test # Run tests"
+ @echo " make build # Build pinchtab"
+ @echo " make fmt # Format code"
+
+## Install git hooks
+install-hooks:
+ @echo "Installing git hooks..."
+ @./scripts/install-hooks.sh
+
+## Run tests
+test:
+ go test ./...
+
+## Run tests with coverage
+test-cover:
+ go test -cover ./...
+ go test -coverprofile=coverage.out ./...
+ go tool cover -html=coverage.out -o coverage.html
+ @echo "Coverage report: coverage.html"
+
+## Run linter
+lint:
+ @if command -v golangci-lint >/dev/null 2>&1; then \
+ golangci-lint run --timeout=5m; \
+ else \
+ echo "⚠️ golangci-lint not installed"; \
+ echo "Install: brew install golangci-lint"; \
+ echo "Or: go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest"; \
+ fi
+
+## Format code
+fmt:
+ gofmt -w .
+ @echo "✅ Code formatted"
+
+## Check code (fmt + lint + test)
+check: fmt lint test
+ @echo "✅ All checks passed"
+
+## Build pinchtab binary
+build:
+ go build -o pinchtab ./cmd/pinchtab
+
+## Build for release
+build-release:
+ CGO_ENABLED=0 go build -ldflags="-s -w" -o pinchtab ./cmd/pinchtab
+
+## Clean build artifacts
+clean:
+ go clean
+ rm -f pinchtab coverage.out coverage.html
+
+## Run pinchtab
+run: build
+ ./pinchtab
+
+## Show help
+help:
+ @echo "Pinchtab Development Commands"
+ @echo ""
+ @echo "Setup:"
+ @echo " make setup Setup development environment (run once)"
+ @echo " make install-hooks Install git hooks"
+ @echo ""
+ @echo "Development:"
+ @echo " make fmt Format code with gofmt"
+ @echo " make lint Run golangci-lint"
+ @echo " make test Run tests"
+ @echo " make test-cover Run tests with coverage report"
+ @echo " make check Run fmt + lint + test"
+ @echo ""
+ @echo "Build:"
+ @echo " make build Build pinchtab binary"
+ @echo " make build-release Build optimized release binary"
+ @echo " make run Build and run pinchtab"
+ @echo ""
+ @echo "Cleanup:"
+ @echo " make clean Remove build artifacts"
diff --git a/README.md b/README.md
index 9dd1509d..2de95ba5 100644
--- a/README.md
+++ b/README.md
@@ -173,9 +173,25 @@ curl http://localhost:9869/text?tabId=Y # Bob's instance
---
+## Development
+
+Want to contribute? See [DEVELOPMENT.md](DEVELOPMENT.md) for setup instructions.
+
+**Quick start:**
+```bash
+git clone https://github.com/pinchtab/pinchtab.git
+cd pinchtab
+make setup # Installs git hooks, downloads deps
+make build # Build pinchtab binary
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
+
+---
+
## License
-MIT — Free and open source.
+Apache 2.0 — Free and open source.
---