Skip to content

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

docs: update scripts and building docs for pdev

Data68e2419d9d3f
diff --git a/docs/architecture/building.md b/docs/architecture/building.md
index ca82b23c..42e3d9eb 100644
--- a/docs/architecture/building.md
+++ b/docs/architecture/building.md
@@ -30,8 +30,8 @@ Guide to build PinchTab from source and contribute to the project.
git clone https://github.com/pinchtab/pinchtab.git
cd pinchtab
-# 2. Run doctor (verifies environment + auto-installs hooks/deps)
-./doctor.sh
+# 2. Run doctor (verifies environment, prompts before installing anything)
+./pdev doctor
# 3. Build and run
go build ./cmd/pinchtab
@@ -40,38 +40,32 @@ go build ./cmd/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
+ πŸ¦€ 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.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
+The doctor asks for confirmation before installing anything.
+If you decline, it shows the manual install command instead.
---
@@ -138,20 +132,21 @@ sudo yum install -y chromium
### Automated Setup
-After installing Go and golangci-lint, run:
+After cloning, run doctor to verify and set up your environment:
```bash
git clone https://github.com/pinchtab/pinchtab.git
cd pinchtab
-./doctor.sh
+./pdev doctor
```
-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)
+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)
-You can run `./doctor.sh` anytime to verify or fix your environment.
+Run `./pdev doctor` anytime to verify or fix your environment.
---
@@ -236,44 +231,76 @@ go test ./... -v -coverprofile=coverage.out
go tool cover -html=coverage.out # View coverage
```
+### Developer Toolkit (`pdev`)
+
+All dev scripts are accessible through `./pdev`:
+
+```bash
+./pdev # Interactive picker (uses gum if installed, numbered fallback)
+./pdev check # Run directly by name
+./pdev --help # List all commands
+```
+
+**Available commands:**
+
+| Command | Description |
+|---------|-------------|
+| `check` | Run pre-push checks (format, vet, build, test, lint) |
+| `dev` | Build & run with dashboard |
+| `doctor` | Verify & setup dev environment |
+| `dashboard` | Build React dashboard |
+| `security` | Run gosec security scan |
+| `docs` | Check docs JSON structure |
+| `hooks` | Install git hooks |
+
+For the fancy interactive picker, install [gum](https://github.com/charmbracelet/gum): `brew install gum`
+
+**Tip:** Add this to `~/.zshrc` to use `pdev` without `./`:
+```bash
+pdev() { if [ -x "./pdev" ]; then ./pdev "$@"; else echo "pdev not found in current directory"; return 1; fi }
+```
+
### Code Quality
```bash
+./pdev check # Full pre-push checks (recommended)
gofmt -w . # Format code
golangci-lint run # Lint
-./doctor.sh # Verify environment
+./pdev doctor # Verify environment
```
### Git Hooks
-Git hooks are auto-installed by `./doctor.sh`. They run on every commit:
+Git hooks are installed by `./pdev doctor` (or `./scripts/install-hooks.sh`). They run on every commit:
- `gofmt` β€” Format check
- `golangci-lint` β€” Linting
+- `prettier` β€” Dashboard formatting
To manually reinstall hooks:
```bash
-./scripts/install-hooks.sh
+./pdev hooks
```
### Development Workflow
```bash
-# 1. Create feature branch
+# 1. Setup (first time)
+./pdev doctor
+
+# 2. Create feature branch
git checkout -b feat/my-feature
-# 2. Make changes
+# 3. Make changes
# ... edit files ...
-# 3. Test
-go test ./...
+# 4. Run checks before pushing
+./pdev check
-# 4. Commit (hooks run automatically)
+# 5. Commit (hooks run automatically)
git commit -m "feat: description"
-# 5. Push
+# 6. Push
git push origin feat/my-feature
-
-# 6. Create PR on GitHub
```
**Note:** Git hooks will automatically format and lint your code on commit. If checks fail, the commit is blocked.
@@ -347,8 +374,8 @@ This will tell you exactly what's missing or misconfigured.
- 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)
+- Run: `./pdev hooks`
+- Or: `./pdev doctor` (prompts to install)
**"Chrome not found"**
- Install Chromium: `brew install chromium` (macOS)
@@ -368,7 +395,7 @@ This will tell you exactly what's missing or misconfigured.
## Support
Issues? Check:
-1. Run `./doctor.sh` first
+1. Run `./pdev doctor` first
2. All dependencies installed and correct versions?
3. Port 9867 available?
4. Check logs: `tail -f pinchtab.log`
diff --git a/docs/get-started.md b/docs/get-started.md
index 2cac802d..2f473ce6 100644
--- a/docs/get-started.md
+++ b/docs/get-started.md
@@ -50,6 +50,7 @@ curl http://localhost:9867/health
```bash
git clone https://github.com/pinchtab/pinchtab.git
cd pinchtab
+./pdev doctor # Verify environment + install hooks/deps
go build -o pinchtab ./cmd/pinchtab
./pinchtab --version
```
diff --git a/scripts/README.md b/scripts/README.md
index de90edb7..b285a404 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -2,6 +2,8 @@
Development and CI scripts for PinchTab.
+> **Tip:** Use `./pdev` from the repo root for an interactive command picker (or `./pdev <command>` to run directly).
+
## Build & Run
| Script | Purpose |
@@ -9,31 +11,23 @@ Development and CI scripts for PinchTab.
| `build-dashboard.sh` | Generate TS types (tygo) + build React dashboard + copy to Go embed |
| `dev.sh` | Full build (dashboard + Go) and run |
-## CI Scripts
-
-Used by GitHub Actions workflows:
-
-| Script | Workflow | Purpose |
-|--------|----------|---------|
-| `build-dashboard.sh` | `go-verify.yml` | Build dashboard before lint |
-
## Quality
| Script | Purpose |
|--------|---------|
-| `check-docs-json.sh` | `docs-verify.yml` | Validate docs/index.json |
| `check.sh` | Local pre-push checks (mirrors CI: gofmt, vet, build, test, lint, integration) |
-| `check-gosec.sh` | Security scan with gosec just to reproduce CI|
-| `pre-commit` | Pre-commit hook (format, lint) |
-| `doctor.sh` | Check requirements |
+| `check-gosec.sh` | Security scan with gosec (reproduces CI security job) |
+| `check-docs-json.sh` | Validate `docs/index.json` structure |
+| `pre-commit` | Git pre-commit hook (format + lint) |
-## Hooks
+## Setup
| Script | Purpose |
|--------|---------|
-| `install-hooks.sh` | Install git hooks |
+| `doctor.sh` | Verify & setup dev environment (interactive β€” prompts before installing) |
+| `install-hooks.sh` | Install git pre-commit hook |
-## Scripts / Testing
+## Testing
| Script | Purpose |
|--------|---------|