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.mdindex 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.gitcd 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 rungo 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:```bashgit clone https://github.com/pinchtab/pinchtab.gitcd 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.outgo 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 codegolangci-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 formattingTo 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 branchgit 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. Pushgit 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.## SupportIssues? Check:-1. Run `./doctor.sh` first+1. Run `./pdev doctor` first2. 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.mdindex 2cac802d..2f473ce6 100644--- a/docs/get-started.md+++ b/docs/get-started.md@@ -50,6 +50,7 @@ curl http://localhost:9867/health```bashgit clone https://github.com/pinchtab/pinchtab.gitcd pinchtab+./pdev doctor # Verify environment + install hooks/depsgo build -o pinchtab ./cmd/pinchtab./pinchtab --version```diff --git a/scripts/README.md b/scripts/README.mdindex 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 ||--------|---------|