High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
chore: ci and docs
Luigi Agosti8ebfbf067701
diff --git a/.github/DEFINITION_OF_DONE.md b/.github/DEFINITION_OF_DONE.mdnew file mode 100644index 00000000..0b172eb2--- /dev/null+++ b/.github/DEFINITION_OF_DONE.md@@ -0,0 +1,53 @@+# Definition of Done (PR Checklist)++## Automated ✅ (CI/GitHub enforces these)+These run automatically via `ci.yml`. If your PR fails them, fix and re-push.+- [ ] Go formatting & linting passes (gofmt, vet, golangci-lint)+- [ ] Unit + integration tests pass (`go test ./...`)+- [ ] Build succeeds (`go build`)+- [ ] CodeQL security scan passes+- [ ] Branch naming follows convention++## Manual — Code Quality (Required)+- [ ] **Error handling explicit** — All errors wrapped with `%w`, no silent failures+- [ ] **No regressions** — Verify stealth, token efficiency, session persistence work (test locally if unsure)+- [ ] **SOLID principles** — Functions do one thing, testable, no unnecessary deps+- [ ] **No redundant comments** — Comments explain *why* or *context*, not *what* the code does+ - ❌ Bad: `// Loop through items` above `for _, item := range items`+ - ❌ Bad: `// Return error` above `return err`+ - ✅ Good: `// Prioritize chromium-browser on ARM64 (Raspberry Pi default)`+ - ✅ Good: `// Chrome may not be installed in CI, so empty result is valid`++## Manual — Testing (Required)+- [ ] **New/changed functionality has tests** — Same-package unit tests preferred; use mockBridge for integration+- [ ] **Integration tests run locally** — If you modified handlers/bridge/tabs, run: `go test -tags integration ./tests/integration`+- [ ] **npm commands work** (if npm wrapper touched):+ - `npm pack` in `/npm/` produces valid tarball+ - `npm install -g pinchtab` (or from local tarball) succeeds+ - `pinchtab --version` + basic commands work after install++## Manual — Documentation (Required)+- [ ] **README.md updated** — If user-facing changes (CLI, API, env vars, install)+- [ ] **/docs/ updated** — If API/architecture/perf changed (optional for small fixes)++## Manual — Review (Required)+- [ ] **PR description explains what + why** — Especially stealth/perf/compatibility impact+- [ ] **Commits are atomic** — Logical grouping, good messages+- [ ] **No breaking changes to npm** — Unless explicitly major version bump++## Conditional (Only if applicable)+- [ ] Headed-mode tested (if dashboard/UI changes)+- [ ] Breaking changes documented in PR description (if any)++---++## Quick Checklist (Copy/Paste for PRs)+```markdown+## Definition of Done+- [ ] Unit/integration tests added & passing+- [ ] Error handling explicit (wrapped with %w)+- [ ] No regressions in stealth/perf/persistence+- [ ] No redundant comments (explain why, not what)+- [ ] README/docs updated (if user-facing)+- [ ] npm install works (if npm changes)+```diff --git a/.github/DOCUMENTATION_REVIEW.md b/.github/DOCUMENTATION_REVIEW.mdnew file mode 100644index 00000000..6ae253de--- /dev/null+++ b/.github/DOCUMENTATION_REVIEW.md@@ -0,0 +1,398 @@+# Documentation Review Guide++## Purpose++Code is the source of truth. This guide helps agents audit, validate, and maintain documentation to ensure it stays in sync with the codebase.++Use this document when asking agents to review documentation for accuracy, completeness, and consistency.++---++## Quick Summary++When asked to review documentation, an agent should:++1. **Verify all examples match current code behavior**+2. **Check doc structure against actual codebase**+3. **Update or remove outdated content**+4. **Report findings and improvements**++---++## Detailed Review Process++### Phase 1: Code-to-Docs Validation++#### 1.1 Check All Examples++For **every code example** in `/docs`:++- [ ] **Run the example** (if it's executable)+ - Does it produce the expected output?+ - Does it work with current API/CLI?+ - Are environment variables correct?++- [ ] **Verify API endpoints**+ - Do endpoints still exist? (`GET /snapshot`, `POST /action`, etc.)+ - Do request/response formats match?+ - Are all parameters documented?+ - Are deprecated endpoints removed?++- [ ] **Verify CLI commands**+ - Do commands still exist? (`pinchtab config set`, `pinchtab health`, etc.)+ - Do they work as documented?+ - Are flags/options correct?+ - Are deprecated commands removed?++- [ ] **Verify configuration values**+ - Do env vars still exist? (`CHROME_EXTENSION_PATHS`, `BRIDGE_PORT`, etc.)+ - Are default values correct?+ - Are deprecated config options removed?++#### 1.2 Check Content Accuracy++For **every paragraph, section, and claim** in `/docs`:++- [ ] **API behavior** — Does it accurately describe current behavior?+- [ ] **Performance notes** — Are benchmarks/timings still valid?+- [ ] **Stealth/security claims** — Do they match current implementation?+- [ ] **Feature availability** — Is feature still implemented?+- [ ] **Limitations** — Are noted limitations still present?+- [ ] **Requirements** — Are tool versions, Chrome versions, etc. correct?++#### 1.3 Cross-Check Against Code++Use the code as reference:++```+For each doc section:+1. Find the corresponding code file(s)+2. Compare doc description with actual implementation+3. If different → docs are WRONG+4. If missing → docs are INCOMPLETE+5. If outdated → docs are STALE+```++**Example:**+- Doc says: "fill action with refs sets the input value"+- Code says: `FillByNodeID()` exists → docs are CORRECT ✅+- Code says: no `FillByNodeID()` → docs are WRONG ❌++---++### Phase 2: Structure Review++#### 2.1 Check Documentation Structure++**File structure should match codebase organization:**++```+docs/+├── api/+│ ├── endpoints/+│ │ ├── navigation.md+│ │ ├── snapshot.md+│ │ ├── actions.md+│ │ ├── find.md+│ │ ├── evaluate.md+│ │ └── ...+│ └── ...+├── cli/+│ ├── management.md+│ ├── config.md+│ └── ...+├── architecture/+│ └── ...+└── index.json+```++**Verify:**+- [ ] All major API endpoints documented?+- [ ] All CLI commands documented?+- [ ] Organization makes sense?+- [ ] Groups reflect actual functionality?+- [ ] No duplicate content?+- [ ] No orphaned docs (not linked from index)?++#### 2.2 Check index.json++**Verify index.json structure:**++```json+{+ "sections": [+ {+ "title": "API",+ "path": "api/",+ "items": [+ {+ "title": "Endpoints",+ "path": "api/endpoints/",+ "items": [+ { "title": "Navigation", "path": "api/endpoints/navigation.md" },+ { "title": "Snapshot", "path": "api/endpoints/snapshot.md" },+ ...+ ]+ }+ ]+ }+ ]+}+```++**Checks:**+- [ ] All sections map to actual directories?+- [ ] All items map to actual files?+- [ ] No broken paths?+- [ ] Nesting depth reasonable (not too deep)?+- [ ] Titles are accurate and clear?+- [ ] Order makes sense (API before examples)?++---++### Phase 3: Report Findings++#### If Changes Were Made++**Create a PR with:**++1. **Summary of fixes**+ ```markdown+ ## Documentation Fixes++ - Updated /docs/api/endpoints/fill.md to document FillByNodeID support (fixes #114)+ - Removed deprecated /docs/api/endpoints/old-nav.md (no longer exists in code)+ - Fixed /docs/cli/config.md examples to use new config set syntax+ - Updated Chrome requirement from 144 to 145+ for extension support+ ```++2. **List of possible improvements** (as comments in PR)+ ```markdown+ ## Suggested Improvements++ - [ ] /docs/architecture/ could use a "bridge lifecycle" diagram+ - [ ] /docs/api/endpoints/actions.md could add more examples+ - [ ] /docs/cli/config.md could show YAML format examples+ ```++3. **PR description**+ ```markdown+ ## Documentation Review — Code Alignment++ Verified all examples, API endpoints, CLI commands, and config values against current code.++ ### Changes Made+ - X examples updated to match current API+ - X endpoints documented/updated+ - X CLI commands verified+ - X deprecated content removed++ ### No Changes Needed+ - API behavior accurate+ - Structure organized+ - Examples working++ ### Improvements Suggested+ See comments in PR for enhancement requests.+ ```++#### If No Changes Needed but Improvements Found++**Create a GitHub issue:**++```markdown+Title: docs: enhancement - add examples for [feature]++Body:+## Suggestion++The documentation could be improved by:++1. Adding example for feature X (current docs only show basic usage)+2. Adding "Common Patterns" section to endpoint Y+3. Adding troubleshooting section to CLI guide++## Reasoning++Users asking "how do I..." suggests these are common use cases.++## References++- See /docs/api/endpoints/[endpoint].md+- See /docs/cli/[command].md+```++---++## Checklist for Agents++When given the task "Review documentation", verify:++### Code Accuracy+- [ ] All examples are tested and working+- [ ] All API endpoints documented correctly+- [ ] All CLI commands documented correctly+- [ ] All config options documented correctly+- [ ] No deprecated content remains+- [ ] All current features documented++### Structure+- [ ] index.json paths are correct+- [ ] Directory structure makes sense+- [ ] No orphaned docs+- [ ] Grouping still makes sense+- [ ] Navigation depth reasonable++### Output+- [ ] If changes: Create PR with summary + improvements list+- [ ] If no changes but improvements: Create GitHub issue with enhancement request+- [ ] Always: Note which docs were spot-checked and results++---++## Common Documentation Mistakes to Fix++❌ **Outdated examples:**+```bash+# OLD (deprecated)+pinchtab nav https://example.com # ← This command was removed++# NEW (correct)+curl -X POST http://localhost:9867/navigate \+ -d '{"url":"https://example.com"}'+```++❌ **Wrong API format:**+```javascript+// OLD (incorrect)+response = await fetch('/action', {+ body: JSON.stringify({action: 'click', ref: 'e5'})+})++// NEW (correct)+response = await fetch('/action', {+ body: JSON.stringify({kind: 'click', ref: 'e5'})+})+```++❌ **Missing new features:**+```markdown+<!-- Missing in docs -->+<!-- Code has FillByNodeID support for fills with refs -->+<!-- Docs should say: "fill supports both selectors and refs" -->+```++❌ **Incorrect config examples:**+```bash+# OLD (deprecated env var name)+export BRIDGE_NAV_TIMEOUT=30++# NEW (correct)+export PINCHTAB_NAVIGATE_TIMEOUT=30+```++---++## Documentation File Locations++**Root docs location:** `/docs`++**Key files to check:**++- `/docs/index.json` — Navigation/structure+- `/docs/README.md` — Overview+- `/docs/api/endpoints/*.md` — API documentation+- `/docs/cli/*.md` — CLI documentation+- `/docs/configuration.md` — Configuration reference+- `/docs/architecture/*.md` — Architecture/design docs+- `/docs/examples/*.md` — Usage examples++---++## When to Ask for Documentation Review++**Ask for review:**+- After major feature additions (new endpoints, CLI commands)+- After refactoring (config structure changes, API changes)+- After bug fixes affecting documented behavior+- Periodically (every quarter) for general sync-up+- Before major releases (ensure nothing is stale)++**Example requests:**++> "Review documentation against current code. Check all API examples, CLI commands, and config values. Update docs to match code or remove outdated content. Create a PR with a summary of changes."++> "Audit /docs for accuracy. Update any incorrect examples, remove deprecated features, fix broken index.json paths. Create an issue with improvement suggestions if no changes needed."++---++## Quality Gates++A documentation review is **complete** when:++✅ All examples are tested and working+✅ All API endpoints match code implementation+✅ All CLI commands match code implementation+✅ All config options match code implementation+✅ No deprecated content remains+✅ index.json structure is accurate+✅ Documentation structure reflects codebase+✅ Either: PR with fixes submitted, OR Issue with improvements created++---++## Example Review Output (PR)++```markdown+## Documentation Review — Code Alignment++All examples, endpoints, and CLI commands verified against current codebase.++### ✅ Changes Made (3 files)++1. **docs/api/endpoints/actions.md**+ - Updated fill example to show ref support (new in PR #119)+ - Added FillByNodeID code path documentation++2. **docs/cli/config.md**+ - Fixed config set examples (new syntax with PR #120)+ - Added YAML output format example++3. **docs/api/endpoints/find.md**+ - Added Find endpoint documentation (new in feat/allocation-strategies)++### ✅ Verified (No Changes Needed)++- All navigate endpoint examples working+- All snapshot filters documented correctly+- All action kinds (click, type, press, etc.) verified+- Config sections (server, chrome, orchestrator) accurate+- Environment variable names current++### 💡 Suggested Improvements++See comments below for enhancement requests (low priority):+- [ ] Add "common patterns" section to actions.md+- [ ] Add troubleshooting FAQ to cli/config.md+- [ ] Create /docs/examples/multi-step-workflow.md++### Review Stats++- Examples tested: 12/12 ✅+- Endpoints checked: 8/8 ✅+- CLI commands checked: 5/5 ✅+- Config sections checked: 4/4 ✅+- Deprecated content found: 0 ✅+- Structure issues found: 0 ✅+```++---++## Related Documents++- [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md) — PR checklist+- [LABELING_GUIDE.md](./LABELING_GUIDE.md) — Issue labeling guide++---++Last updated: 2026-03-04diff --git a/.github/LABELING_GUIDE.md b/.github/LABELING_GUIDE.mdnew file mode 100644index 00000000..c2a882ad--- /dev/null+++ b/.github/LABELING_GUIDE.md@@ -0,0 +1,246 @@+# Labeling Guide++This document describes the labeling system used for issues and PRs in pinchtab. Use this guide when triaging tickets or asking agents to review open issues.++---++## Quick Reference++Every issue should have:+1. **Exactly one Type label** (bug, enhancement, documentation, question, etc.)+2. **One Status label** (ready, in-progress, blocked, fixed-unreleased, needs-investigation)+3. **One Priority label** (high, medium, low) — optional for documentation or questions++---++## Tier 1: Issue Type (Mandatory)++Choose **exactly one**:++| Label | Color | Usage |+|-------|-------|-------|+| `bug` | 🔴 Red | Something isn't working correctly |+| `enhancement` | 🔵 Cyan | New feature or capability request |+| `documentation` | 🔵 Blue | Improvements/additions to README, docs, or code comments |+| `question` | 🟣 Purple | Request for clarification or information |+| `good first issue` | 🟣 Purple | Good for newcomers (in addition to type label) |+| `help wanted` | 🟢 Green | Needs extra attention or expertise |+| `dependencies` | 🔵 Blue | Dependency updates (PR label) |+| `invalid` | 🟡 Yellow | Doesn't seem right; requires clarification |+| `duplicate` | ⚪ Gray | Already exists (close and reference original) |+| `wontfix` | ⚪ White | Deliberate decision not to fix |++### Examples++- **Bug:** "fill action silently no-ops when using refs" → `bug`+- **Enhancement:** "Add CHROME_EXTENSION_PATHS support" → `enhancement`+- **Documentation:** "Update README with new CLI commands" → `documentation`+- **Question:** "How do I configure stealth mode?" → `question`++---++## Tier 2: Status (Recommended)++Choose **one** to show current state:++| Label | Color | Meaning | When to Use |+|-------|-------|---------|------------|+| `status: ready` | 🔵 Blue | Ready to start work | Issue is fully understood, no blockers, waiting for someone to pick it up |+| `status: in-progress` | 🟡 Yellow | Actively being worked on | Someone has claimed the issue and is working on a fix/feature |+| `status: blocked` | 🔴 Red | Blocked by something | Waiting on external dependency, another issue, or decision |+| `status: fixed-unreleased` | 🟢 Green | Fix merged, not in release | PR is merged but feature/fix isn't in a released version yet |+| `status: needs-investigation` | 🔴 Red | Needs debugging/research | Not enough info; requires investigation before work can start |++### Workflow++```+New Issue+ ↓+[Triage] Add Type + Status+ ↓+status: needs-investigation (if unclear) or status: ready (if clear)+ ↓+Developer picks it up+ ↓+status: in-progress+ ↓+PR submitted+ ↓+PR merged+ ↓+status: fixed-unreleased (for bugs) or remove status (for features)+ ↓+Release cut+ ↓+Remove status label (feature is released)+```++---++## Tier 3: Priority (Optional, for bugs/enhancements)++Choose **one** to indicate urgency:++| Label | Color | Level | When to Use |+|-------|-------|-------|------------|+| `priority: high` | 🔴 Red | Critical; blocks users | Security vulnerability, critical bug, high-demand feature |+| `priority: medium` | 🟡 Yellow | Normal; important for roadmap | Important bug or feature; should be done soon |+| `priority: low` | 🟢 Green | Nice to have; can defer | Minor improvement, polish, or edge case |++### Examples++- **High:** "SafePath() fails to block path traversal" (security) → `bug` + `priority: high`+- **Medium:** "Snapshot doesn't work inside iframes" (affects users) → `bug` + `priority: medium`+- **Low:** "Consider migrating to PINCHTAB_* env vars" (nice refactor) → `enhancement` + `priority: low`++---++## Special Labels++### `good first issue`+Add this **in addition to the type label** for issues that are good entry points for new contributors.++**Criteria:**+- Clear problem statement+- Solution is straightforward+- Doesn't require deep knowledge of codebase+- Estimated effort: <4 hours++**Example:** "documentation: Add /find endpoint example to README" → `documentation` + `good first issue`++### `help wanted`+Indicates the issue needs expertise or has been stalled.++**When to use:**+- Needs specific expertise (e.g., "needs Windows testing")+- Issue has been open >2 weeks without progress+- Complex problem that benefits from external input++---++## Decision Tree for Triage++```+New issue arrives+ ↓+1. Is it a valid issue?+ NO → `invalid` + close+ YES ↓+2. What is it?+ → Bug? `bug` + assess severity → `priority: high|medium|low`+ → New feature? `enhancement` + assess importance → `priority: high|medium|low`+ → Docs missing? `documentation` + no priority needed+ → Unclear? `question` + no priority needed+ ↓+3. Can we start work immediately?+ YES → `status: ready`+ NO ↓+4. Why not?+ → Need info → `status: needs-investigation`+ → Waiting on something → `status: blocked`+ → Already fixed → `status: fixed-unreleased`+```++---++## Guidelines for Agents++When reviewing open issues, follow this checklist:++- [ ] **Each issue has exactly one Type label** (bug, enhancement, documentation, question)+- [ ] **Bugs have Priority labels** (high, medium, low)+- [ ] **Enhancements have Priority labels** (high, medium, low)+- [ ] **Each issue has a Status label** (ready, in-progress, blocked, fixed-unreleased, needs-investigation)+- [ ] **No duplicate labels** (e.g., two type labels on one issue)+- [ ] **Status matches reality** (e.g., `status: in-progress` has an active PR)+- [ ] **Stale issues reviewed** (e.g., `status: blocked` for >2 weeks should note why)++---++## Current Label Inventory++**Type labels (10):**+- bug, enhancement, documentation, question, good first issue, help wanted, dependencies, invalid, duplicate, wontfix++**Status labels (5):**+- status: ready, status: in-progress, status: blocked, status: fixed-unreleased, status: needs-investigation++**Priority labels (3):**+- priority: high, priority: medium, priority: low++**Code labels (1):**+- javascript++---++## Examples of Well-Labeled Issues++### Example 1: Security Bug+```+Title: SafePath() fails to block path traversal on Windows+Labels: bug, priority: high, status: ready+```+**Why:** Critical security issue, ready to work on, high priority.++### Example 2: Feature Request (Ready)+```+Title: feat: Resource Pool with pluggable allocation strategies+Labels: enhancement, priority: medium, status: ready+```+**Why:** Enhancement, medium priority (important for roadmap), ready to start.++### Example 3: Feature (Blocked)+```+Title: feat: Semantic Element Selection via NLP (/find endpoint)+Labels: enhancement, priority: medium, status: blocked+```+**Why:** Enhancement, medium priority, but blocked (perhaps waiting on design decision).++### Example 4: Bug (Not Ready)+```+Title: click and humanClick fail to trigger Bootstrap dropdown+Labels: bug, priority: medium, status: needs-investigation+```+**Why:** Bug, medium priority, but needs investigation (reproduction steps unclear).++### Example 5: Already Fixed+```+Title: Installation issue+Labels: bug, priority: high, status: fixed-unreleased+```+**Why:** Critical bug, but fix is already merged and waiting for release.++---++## Common Mistakes++❌ **Don't do this:**++| Mistake | Why | Fix |+|---------|-----|-----|+| Two Type labels on one issue | Ambiguous; what is it really? | Choose one type only |+| Status label on closed issue | Status should reflect open work | Remove status label when closing |+| No Priority on bugs | Can't triage effectively | Add priority: high/medium/low to all bugs |+| `status: in-progress` with no PR | Misleading; is someone actually working on it? | Only use when work is actively underway |+| Forgetting Status labels | No visibility into progress | Always add a status label during triage |++---++## Related Documents++- [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md) — Checklist for PRs before merge+- [CONTRIBUTING.md](../CONTRIBUTING.md) — Contribution guidelines (if present)++---++## Last Updated++2026-03-04++---++## Summary++**For agents:** Use this guide to understand and apply labels when triaging issues. Ensure every issue has Type + Status + Priority (if applicable).++**For maintainers:** Review labels during triage and ensure consistency. Use the Decision Tree above as a quick reference.diff --git a/.github/README.md b/.github/README.mdnew file mode 100644index 00000000..0634ea3c--- /dev/null+++ b/.github/README.md@@ -0,0 +1,85 @@+# GitHub Governance Documents++This directory contains pinchtab's governance and workflow documents referenced by developers and automated agents.++## Documents++### [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md)+**Purpose:** PR checklist for code quality, testing, and documentation before merging.++**For:** All contributors submitting PRs+**How to use:** Check this list before submitting a PR, or ask agents to verify PRs against it.++**Key sections:**+- Automated checks (CI enforces)+- Manual code quality requirements+- Testing requirements+- Documentation requirements+- Quick checklist for copy/paste++---++### [LABELING_GUIDE.md](./LABELING_GUIDE.md)+**Purpose:** Reference guide for issue and PR labeling to maintain consistent triage.++**For:** Maintainers triaging issues, agents reviewing tickets+**How to use:** Point agents to this guide when asking them to review and label open issues.++**Key sections:**+- 3-tier labeling system (Type → Status → Priority)+- Decision tree for triage+- Guidelines for agents+- Examples of well-labeled issues+- Common mistakes to avoid++---++### [DOCUMENTATION_REVIEW.md](./DOCUMENTATION_REVIEW.md)+**Purpose:** Guide for auditing documentation to ensure it stays in sync with code (code is source of truth).++**For:** Agents maintaining documentation, quality assurance+**How to use:** Point agents to this guide when asking them to audit docs for accuracy and consistency.++**Key sections:**+- Code-to-docs validation (examples, endpoints, commands, config)+- Structure review (organization, index.json, grouping)+- Output requirements (PR with fixes or GitHub issue with improvements)+- Common documentation mistakes to fix+- Quality gates for completion++---++## Quick Reference++| Document | Audit For | Used By |+|----------|-----------|---------|+| DEFINITION_OF_DONE.md | PR quality before merge | Developers, agents, reviewers |+| LABELING_GUIDE.md | Consistent issue triage | Maintainers, agents |+| DOCUMENTATION_REVIEW.md | Documentation accuracy vs code | Agents, QA |++---++## How Agents Use These++When asking an agent to help with PRs, issues, or documentation:++**For PR review:**+> "Review this PR against `.github/DEFINITION_OF_DONE.md` and ensure it meets all requirements."++**For issue triage:**+> "Review open issues and apply labels according to `.github/LABELING_GUIDE.md`. Ensure Type + Status + Priority are consistent."++**For documentation audit:**+> "Review documentation against current code using `.github/DOCUMENTATION_REVIEW.md`. Verify all examples match code, update or remove outdated content, report changes in a PR or improvements in a GitHub issue."++---++## Maintenance++- **DEFINITION_OF_DONE.md** — Update when code quality standards change+- **LABELING_GUIDE.md** — Update when new labels are added or workflow changes+- This **README.md** — Update when new governance documents are added++---++Last updated: 2026-03-04diff --git a/.github/workflows/integration.yml b/.github/workflows/integration.ymlindex e2a1f069..df321dba 100644--- a/.github/workflows/integration.yml+++ b/.github/workflows/integration.yml@@ -28,7 +28,7 @@ jobs:changes:name: Detect Changesruns-on: ubuntu-latest- if: github.event.pull_request.draft == false+ if: github.event_name != 'pull_request' || github.event.pull_request.draft == falseoutputs:go: ${{ steps.filter.outputs.go }}steps:@@ -45,28 +45,85 @@ jobs:- 'internal/**'- 'tests/integration/**'- integration:- name: Integration Tests+ integration-core:+ name: Integration Tests (Core)needs: changesruns-on: ubuntu-latest- timeout-minutes: 25+ timeout-minutes: 12+ if: needs.changes.outputs.go == 'true'+ env:+ CORE_REGEX: '^Test(Health|Orchestrator_|Navigate_|Tabs_|Config_|Metrics_|Cookies_|Error_|Eval_|Upload_|Screenshot_)'steps:- - name: Skip if no Go changes- if: needs.changes.outputs.go != 'true'+ - uses: actions/checkout@v4++ - uses: actions/setup-go@v5+ with:+ go-version: '1.26'++ - name: Install Google Chrome (deb, avoids snap hangs)run: |- echo "⏭️ No Go files changed, skipping integration tests"- echo "This is expected for docs/workflow-only changes"+ wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add -+ echo 'deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main' | sudo tee /etc/apt/sources.list.d/google-chrome.list+ sudo apt-get update+ sudo apt-get install -y google-chrome-stable+ echo "CHROME_BINARY=/usr/bin/google-chrome" >> $GITHUB_ENV+ - name: Install gotestsum+ run: go install gotest.tools/gotestsum@latest++ - name: 🧪 Run core integration tests+ run: |+ echo "::group::Core Integration Tests Output"+ gotestsum --format testname --jsonfile core-events.json -- \+ -tags integration -v -timeout 10m -count=1 \+ -run "$CORE_REGEX" ./tests/integration/+ echo "::endgroup::"+ env:+ CI: "true"+ BRIDGE_HEADLESS: "true"+ BRIDGE_NO_RESTORE: "true"+ PINCHTAB_TEST_PORT: "19867"+ PINCHTAB_TEST_RETRY: "true"++ - name: 📋 Add summary+ if: always()+ run: |+ total=0+ pass=0+ fail=0+ skip=0++ if [ -s core-events.json ]; then+ read total pass fail skip <<<"$(jq -r 'select(.Test != null and (.Action == "pass" or .Action == "fail" or .Action == "skip")) | [.Package, .Test, .Action] | @tsv' core-events.json \+ | awk -F'\t' 'NF == 3 { key = $1 "\t" $2; status[key] = $3 } END { for (k in status) { t++; if (status[k] == "pass") p++; else if (status[k] == "fail") f++; else if (status[k] == "skip") s++; } printf "%d %d %d %d\n", t + 0, p + 0, f + 0, s + 0 }')"+ fi++ echo "### ✅ Integration Core Tests" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Status**: ${{ job.status }}" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Runner**: ubuntu-latest" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Port**: 19867" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Regex**: \`$CORE_REGEX\`" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Total tests**: $total" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Passed**: $pass" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Failed**: $fail" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Skipped**: $skip" >> "$GITHUB_STEP_SUMMARY"++ integration-rest:+ name: Integration Tests (Rest)+ needs: changes+ runs-on: ubuntu-latest+ timeout-minutes: 15+ if: needs.changes.outputs.go == 'true'+ env:+ CORE_REGEX: '^Test(Health|Orchestrator_|Navigate_|Tabs_|Config_|Metrics_|Cookies_|Error_|Eval_|Upload_|Screenshot_)'+ steps:- uses: actions/checkout@v4- if: needs.changes.outputs.go == 'true'- uses: actions/setup-go@v5- if: needs.changes.outputs.go == 'true'with:go-version: '1.26'- name: Install Google Chrome (deb, avoids snap hangs)- if: needs.changes.outputs.go == 'true'run: |wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add -echo 'deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main' | sudo tee /etc/apt/sources.list.d/google-chrome.list@@ -74,12 +131,43 @@ jobs:sudo apt-get install -y google-chrome-stableecho "CHROME_BINARY=/usr/bin/google-chrome" >> $GITHUB_ENV- - name: Run integration tests- if: needs.changes.outputs.go == 'true'- run: go test -tags integration -v -timeout 20m -count=1 ./tests/integration/+ - name: Install gotestsum+ run: go install gotest.tools/gotestsum@latest++ - name: 🧪 Run rest integration tests+ run: |+ echo "::group::Rest Integration Tests Output"+ gotestsum --format testname --jsonfile rest-events.json -- \+ -tags integration -v -timeout 12m -count=1 \+ -run '^Test' -skip "$CORE_REGEX" ./tests/integration/+ echo "::endgroup::"env:CI: "true"BRIDGE_HEADLESS: "true"BRIDGE_NO_RESTORE: "true"- PINCHTAB_TEST_PORT: "19867"+ PINCHTAB_TEST_PORT: "19868"PINCHTAB_TEST_RETRY: "true"++ - name: 📋 Add summary+ if: always()+ run: |+ total=0+ pass=0+ fail=0+ skip=0++ if [ -s rest-events.json ]; then+ read total pass fail skip <<<"$(jq -r 'select(.Test != null and (.Action == "pass" or .Action == "fail" or .Action == "skip")) | [.Package, .Test, .Action] | @tsv' rest-events.json \+ | awk -F'\t' 'NF == 3 { key = $1 "\t" $2; status[key] = $3 } END { for (k in status) { t++; if (status[k] == "pass") p++; else if (status[k] == "fail") f++; else if (status[k] == "skip") s++; } printf "%d %d %d %d\n", t + 0, p + 0, f + 0, s + 0 }')"+ fi++ echo "### ✅ Integration Rest Tests" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Status**: ${{ job.status }}" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Runner**: ubuntu-latest" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Port**: 19868" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Selection**: all integration tests with core tests skipped" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Skip regex**: \`$CORE_REGEX\`" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Total tests**: $total" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Passed**: $pass" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Failed**: $fail" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Skipped**: $skip" >> "$GITHUB_STEP_SUMMARY"