browsercontrol 0.1.3__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (175) hide show
  1. browsercontrol-0.3.0/.claude-plugin/marketplace.json +21 -0
  2. browsercontrol-0.3.0/.claude-plugin/plugin.json +32 -0
  3. browsercontrol-0.3.0/.github/ISSUE_TEMPLATE/bug_report.md +28 -0
  4. browsercontrol-0.3.0/.github/ISSUE_TEMPLATE/config.yml +5 -0
  5. browsercontrol-0.3.0/.github/ISSUE_TEMPLATE/feature_request.md +13 -0
  6. browsercontrol-0.3.0/.github/ISSUE_TEMPLATE/question.md +11 -0
  7. browsercontrol-0.3.0/.github/PULL_REQUEST_TEMPLATE.md +11 -0
  8. browsercontrol-0.3.0/.github/dco.yml +2 -0
  9. browsercontrol-0.3.0/.github/workflows/ci.yml +101 -0
  10. browsercontrol-0.3.0/.github/workflows/dependency-review.yml +39 -0
  11. browsercontrol-0.3.0/.github/workflows/docs.yml +97 -0
  12. browsercontrol-0.3.0/.github/workflows/pr-checks.yml +56 -0
  13. browsercontrol-0.3.0/.github/workflows/release.yml +143 -0
  14. browsercontrol-0.3.0/.gitignore +35 -0
  15. {browsercontrol-0.1.3 → browsercontrol-0.3.0}/.pre-commit-config.yaml +37 -11
  16. browsercontrol-0.3.0/AGENTS.md +4 -0
  17. browsercontrol-0.3.0/CHANGELOG.md +62 -0
  18. browsercontrol-0.3.0/CLAUDE.md +209 -0
  19. {browsercontrol-0.1.3 → browsercontrol-0.3.0}/CONTRIBUTING.md +13 -5
  20. browsercontrol-0.3.0/Makefile +43 -0
  21. browsercontrol-0.3.0/PKG-INFO +203 -0
  22. browsercontrol-0.3.0/README.es-ES.md +176 -0
  23. browsercontrol-0.3.0/README.md +176 -0
  24. browsercontrol-0.3.0/assets/demo-dark.gif +0 -0
  25. browsercontrol-0.3.0/assets/demo-light.gif +0 -0
  26. browsercontrol-0.3.0/assets/logo-main.png +0 -0
  27. browsercontrol-0.3.0/assets/som-demo.gif +0 -0
  28. {browsercontrol-0.1.3 → browsercontrol-0.3.0}/browsercontrol/__init__.py +1 -1
  29. browsercontrol-0.3.0/browsercontrol/__main__.py +71 -0
  30. browsercontrol-0.3.0/browsercontrol/browser.py +721 -0
  31. browsercontrol-0.3.0/browsercontrol/codegen.py +363 -0
  32. browsercontrol-0.3.0/browsercontrol/config.py +118 -0
  33. browsercontrol-0.3.0/browsercontrol/elements.py +388 -0
  34. browsercontrol-0.3.0/browsercontrol/emulation.py +102 -0
  35. browsercontrol-0.3.0/browsercontrol/resources.py +116 -0
  36. browsercontrol-0.3.0/browsercontrol/server.py +192 -0
  37. browsercontrol-0.3.0/browsercontrol/session.py +262 -0
  38. {browsercontrol-0.1.3 → browsercontrol-0.3.0}/browsercontrol/tools/__init__.py +14 -0
  39. browsercontrol-0.3.0/browsercontrol/tools/_summary.py +68 -0
  40. browsercontrol-0.3.0/browsercontrol/tools/batch.py +187 -0
  41. {browsercontrol-0.1.3 → browsercontrol-0.3.0}/browsercontrol/tools/content.py +30 -34
  42. {browsercontrol-0.1.3 → browsercontrol-0.3.0}/browsercontrol/tools/devtools.py +60 -91
  43. browsercontrol-0.3.0/browsercontrol/tools/emulate.py +213 -0
  44. browsercontrol-0.3.0/browsercontrol/tools/extract.py +288 -0
  45. browsercontrol-0.3.0/browsercontrol/tools/forms.py +222 -0
  46. browsercontrol-0.3.0/browsercontrol/tools/interaction.py +354 -0
  47. {browsercontrol-0.1.3 → browsercontrol-0.3.0}/browsercontrol/tools/navigation.py +25 -31
  48. browsercontrol-0.3.0/browsercontrol/tools/network.py +358 -0
  49. browsercontrol-0.3.0/browsercontrol/tools/recording.py +205 -0
  50. browsercontrol-0.3.0/browsercontrol/tools/search.py +205 -0
  51. browsercontrol-0.3.0/browsercontrol/tools/sessions.py +136 -0
  52. {browsercontrol-0.1.3 → browsercontrol-0.3.0}/browsercontrol/tools/tabs.py +4 -4
  53. browsercontrol-0.3.0/browsercontrol/tools/waiting.py +122 -0
  54. browsercontrol-0.3.0/docs/.vitepress/config.mts +229 -0
  55. browsercontrol-0.3.0/docs/.vitepress/theme/Layout.vue +68 -0
  56. browsercontrol-0.3.0/docs/.vitepress/theme/components/Card.vue +64 -0
  57. browsercontrol-0.3.0/docs/.vitepress/theme/components/CardGrid.vue +12 -0
  58. browsercontrol-0.3.0/docs/.vitepress/theme/components/InstallBox.vue +212 -0
  59. browsercontrol-0.3.0/docs/.vitepress/theme/components/Mark.vue +36 -0
  60. browsercontrol-0.3.0/docs/.vitepress/theme/components/ToolExplorer.vue +387 -0
  61. browsercontrol-0.3.0/docs/.vitepress/theme/components/home/AgentSection.vue +291 -0
  62. browsercontrol-0.3.0/docs/.vitepress/theme/components/home/FeatureGrid.vue +732 -0
  63. browsercontrol-0.3.0/docs/.vitepress/theme/components/home/HomePage.vue +716 -0
  64. browsercontrol-0.3.0/docs/.vitepress/theme/components/home/MarksDemo.vue +778 -0
  65. browsercontrol-0.3.0/docs/.vitepress/theme/index.ts +49 -0
  66. browsercontrol-0.3.0/docs/.vitepress/theme/redirects.ts +51 -0
  67. browsercontrol-0.3.0/docs/.vitepress/theme/reveal.ts +49 -0
  68. browsercontrol-0.3.0/docs/.vitepress/theme/style/base.css +133 -0
  69. browsercontrol-0.3.0/docs/.vitepress/theme/style/docs.css +359 -0
  70. browsercontrol-0.3.0/docs/.vitepress/theme/style/vars.css +63 -0
  71. browsercontrol-0.3.0/docs/.vitepress/theme/tools.data.ts +38 -0
  72. browsercontrol-0.3.0/docs/concepts/comparison.md +55 -0
  73. browsercontrol-0.3.0/docs/concepts/how-it-works.md +79 -0
  74. browsercontrol-0.3.0/docs/concepts/sessions.md +58 -0
  75. browsercontrol-0.3.0/docs/concepts/set-of-marks.md +83 -0
  76. browsercontrol-0.3.0/docs/concepts/settling.md +63 -0
  77. browsercontrol-0.3.0/docs/guide/agent-skill.md +69 -0
  78. browsercontrol-0.3.0/docs/guide/clients.md +187 -0
  79. browsercontrol-0.3.0/docs/guide/first-session.md +67 -0
  80. browsercontrol-0.3.0/docs/guide/http.md +58 -0
  81. browsercontrol-0.3.0/docs/guide/index.md +59 -0
  82. browsercontrol-0.3.0/docs/guide/installation.md +81 -0
  83. browsercontrol-0.3.0/docs/guide/quickstart.md +56 -0
  84. browsercontrol-0.3.0/docs/help/faq.md +46 -0
  85. browsercontrol-0.3.0/docs/help/troubleshooting.md +120 -0
  86. browsercontrol-0.3.0/docs/index.md +24 -0
  87. browsercontrol-0.3.0/docs/package-lock.json +4043 -0
  88. browsercontrol-0.3.0/docs/package.json +20 -0
  89. browsercontrol-0.3.0/docs/project/about.md +33 -0
  90. browsercontrol-0.3.0/docs/project/changelog.md +6 -0
  91. browsercontrol-0.3.0/docs/project/contributing.md +87 -0
  92. browsercontrol-0.3.0/docs/public/images/annotated-web-form.webp +0 -0
  93. browsercontrol-0.3.0/docs/public/images/favicon.svg +20 -0
  94. browsercontrol-0.3.0/docs/public/logo-mascot.png +0 -0
  95. browsercontrol-0.3.0/docs/public/mascot.png +0 -0
  96. browsercontrol-0.3.0/docs/public/og-card.png +0 -0
  97. browsercontrol-0.3.0/docs/public/tools.json +1463 -0
  98. browsercontrol-0.3.0/docs/recipes/debug.md +96 -0
  99. browsercontrol-0.3.0/docs/recipes/edge-states.md +86 -0
  100. browsercontrol-0.3.0/docs/recipes/extract-data.md +74 -0
  101. browsercontrol-0.3.0/docs/recipes/fill-a-form.md +49 -0
  102. browsercontrol-0.3.0/docs/recipes/index.md +32 -0
  103. browsercontrol-0.3.0/docs/recipes/record-tests.md +83 -0
  104. browsercontrol-0.3.0/docs/recipes/research.md +57 -0
  105. browsercontrol-0.3.0/docs/recipes/responsive.md +52 -0
  106. browsercontrol-0.3.0/docs/recipes/tabs.md +49 -0
  107. browsercontrol-0.3.0/docs/recipes/upload-a-file.md +50 -0
  108. browsercontrol-0.3.0/docs/recipes/your-chrome.md +91 -0
  109. browsercontrol-0.3.0/docs/reference/configuration.md +152 -0
  110. browsercontrol-0.3.0/docs/reference/content.md +110 -0
  111. browsercontrol-0.3.0/docs/reference/devtools.md +210 -0
  112. browsercontrol-0.3.0/docs/reference/emulation.md +133 -0
  113. browsercontrol-0.3.0/docs/reference/extraction.md +92 -0
  114. browsercontrol-0.3.0/docs/reference/forms.md +87 -0
  115. browsercontrol-0.3.0/docs/reference/index.md +83 -0
  116. browsercontrol-0.3.0/docs/reference/interaction.md +249 -0
  117. browsercontrol-0.3.0/docs/reference/navigation.md +136 -0
  118. browsercontrol-0.3.0/docs/reference/network.md +123 -0
  119. browsercontrol-0.3.0/docs/reference/recording.md +117 -0
  120. browsercontrol-0.3.0/docs/reference/resources.md +27 -0
  121. browsercontrol-0.3.0/docs/reference/sessions.md +116 -0
  122. browsercontrol-0.3.0/docs/reference/tabs.md +85 -0
  123. browsercontrol-0.3.0/docs/reference/waiting.md +82 -0
  124. browsercontrol-0.3.0/docs/scripts/check-links.mjs +68 -0
  125. browsercontrol-0.3.0/docs/superpowers/plans/2026-11-21-project-foundation.md +116 -0
  126. browsercontrol-0.3.0/docs/superpowers/specs/2026-11-21-project-foundation-design.md +43 -0
  127. browsercontrol-0.3.0/mcp.json +14 -0
  128. browsercontrol-0.3.0/opencode/plugin.js +48 -0
  129. browsercontrol-0.3.0/package.json +21 -0
  130. browsercontrol-0.3.0/plugin.json +27 -0
  131. {browsercontrol-0.1.3 → browsercontrol-0.3.0}/pyproject.toml +28 -5
  132. browsercontrol-0.3.0/scripts/checks/check_max_lines.py +34 -0
  133. browsercontrol-0.3.0/scripts/gen_tools_json.py +147 -0
  134. browsercontrol-0.3.0/skills/browsercontrol/SKILL.md +162 -0
  135. browsercontrol-0.3.0/tach.toml +18 -0
  136. {browsercontrol-0.1.3 → browsercontrol-0.3.0}/tests/conftest.py +6 -0
  137. browsercontrol-0.3.0/tests/test_agent_features.py +261 -0
  138. browsercontrol-0.3.0/tests/test_browser.py +522 -0
  139. browsercontrol-0.3.0/tests/test_check_max_lines.py +42 -0
  140. browsercontrol-0.3.0/tests/test_config.py +46 -0
  141. {browsercontrol-0.1.3 → browsercontrol-0.3.0}/tests/test_content.py +45 -20
  142. {browsercontrol-0.1.3 → browsercontrol-0.3.0}/tests/test_devtools.py +101 -23
  143. browsercontrol-0.3.0/tests/test_docs.py +59 -0
  144. browsercontrol-0.3.0/tests/test_element_summary.py +90 -0
  145. browsercontrol-0.3.0/tests/test_elements.py +252 -0
  146. browsercontrol-0.3.0/tests/test_features_real_browser.py +548 -0
  147. browsercontrol-0.3.0/tests/test_forms.py +396 -0
  148. browsercontrol-0.3.0/tests/test_interaction.py +320 -0
  149. {browsercontrol-0.1.3 → browsercontrol-0.3.0}/tests/test_navigation.py +9 -9
  150. browsercontrol-0.3.0/tests/test_plugin_manifest.py +38 -0
  151. browsercontrol-0.3.0/tests/test_recording.py +166 -0
  152. browsercontrol-0.3.0/tests/test_server.py +42 -0
  153. browsercontrol-0.3.0/tests/test_som_real_browser.py +399 -0
  154. {browsercontrol-0.1.3 → browsercontrol-0.3.0}/tests/test_tabs.py +9 -9
  155. browsercontrol-0.3.0/uv.lock +2230 -0
  156. browsercontrol-0.1.3/.gitignore +0 -13
  157. browsercontrol-0.1.3/CODE_QUALITY.md +0 -81
  158. browsercontrol-0.1.3/PKG-INFO +0 -615
  159. browsercontrol-0.1.3/README.md +0 -589
  160. browsercontrol-0.1.3/assets/logo.png +0 -0
  161. browsercontrol-0.1.3/browsercontrol/__main__.py +0 -19
  162. browsercontrol-0.1.3/browsercontrol/browser.py +0 -499
  163. browsercontrol-0.1.3/browsercontrol/config.py +0 -55
  164. browsercontrol-0.1.3/browsercontrol/server.py +0 -96
  165. browsercontrol-0.1.3/browsercontrol/tools/forms.py +0 -139
  166. browsercontrol-0.1.3/browsercontrol/tools/interaction.py +0 -211
  167. browsercontrol-0.1.3/browsercontrol/tools/recording.py +0 -230
  168. browsercontrol-0.1.3/node_modules/.cache/prettier/.prettier-caches/91665f0f9d7600991a6f27263bd495571952d52f.json +0 -1
  169. browsercontrol-0.1.3/tests/test_browser.py +0 -232
  170. browsercontrol-0.1.3/tests/test_forms.py +0 -140
  171. browsercontrol-0.1.3/tests/test_interaction.py +0 -222
  172. browsercontrol-0.1.3/tests/test_recording.py +0 -114
  173. browsercontrol-0.1.3/uv.lock +0 -2001
  174. {browsercontrol-0.1.3 → browsercontrol-0.3.0}/LICENSE +0 -0
  175. {browsercontrol-0.1.3 → browsercontrol-0.3.0}/tests/__init__.py +0 -0
@@ -0,0 +1,21 @@
1
+ {
2
+ "name": "browsercontrol",
3
+ "owner": {
4
+ "name": "Aditya Sasidhar",
5
+ "url": "https://github.com/adityasasidhar"
6
+ },
7
+ "metadata": {
8
+ "description": "BrowserControl: vision-first browser automation for Claude Code."
9
+ },
10
+ "plugins": [
11
+ {
12
+ "name": "browsercontrol",
13
+ "source": "./",
14
+ "description": "Vision-first browser automation: every action returns a screenshot with numbered boxes over interactive elements, so Claude clicks by number instead of by selector. Bundles the BrowserControl MCP server and its usage skill.",
15
+ "version": "0.3.0",
16
+ "category": "development",
17
+ "homepage": "https://adityasasidhar.github.io/browsercontrol/",
18
+ "license": "MIT"
19
+ }
20
+ ]
21
+ }
@@ -0,0 +1,32 @@
1
+ {
2
+ "name": "browsercontrol",
3
+ "version": "0.3.0",
4
+ "description": "Vision-first browser automation: every action returns a screenshot with numbered boxes over interactive elements, so Claude clicks by number instead of by selector. Bundles the BrowserControl MCP server and its usage skill.",
5
+ "author": {
6
+ "name": "Aditya Sasidhar",
7
+ "url": "https://github.com/adityasasidhar"
8
+ },
9
+ "homepage": "https://adityasasidhar.github.io/browsercontrol/",
10
+ "repository": "https://github.com/adityasasidhar/browsercontrol",
11
+ "license": "MIT",
12
+ "keywords": [
13
+ "browser",
14
+ "automation",
15
+ "playwright",
16
+ "mcp",
17
+ "set-of-marks",
18
+ "screenshots",
19
+ "testing"
20
+ ],
21
+ "icon": "assets/logo-main.png",
22
+ "mcpServers": {
23
+ "browsercontrol": {
24
+ "command": "uvx",
25
+ "args": [
26
+ "--from",
27
+ "${CLAUDE_PLUGIN_ROOT}",
28
+ "browsercontrol"
29
+ ]
30
+ }
31
+ }
32
+ }
@@ -0,0 +1,28 @@
1
+ ---
2
+ name: Bug report
3
+ about: Something is broken or behaves unexpectedly
4
+ labels: bug
5
+ ---
6
+
7
+ ## Describe the bug
8
+
9
+ <!-- A clear description of what went wrong. -->
10
+
11
+ ## Steps to reproduce
12
+
13
+ 1.
14
+ 2.
15
+ 3.
16
+
17
+ ## Expected behavior
18
+
19
+ ## Environment
20
+
21
+ - BrowserControl version:
22
+ - OS:
23
+ - Python version:
24
+ - MCP client (Claude Code, Cursor, ...):
25
+
26
+ ## Logs
27
+
28
+ <!-- Run with LOG_LEVEL=DEBUG and paste relevant output. Remove any secrets. -->
@@ -0,0 +1,5 @@
1
+ blank_issues_enabled: false
2
+ contact_links:
3
+ - name: Documentation
4
+ url: https://adityasasidhar.github.io/browsercontrol/
5
+ about: Read the docs and troubleshooting guide before opening an issue.
@@ -0,0 +1,13 @@
1
+ ---
2
+ name: Feature request
3
+ about: Suggest a new tool or improvement
4
+ labels: enhancement
5
+ ---
6
+
7
+ ## Problem
8
+
9
+ <!-- What are you trying to do that is hard or impossible today? -->
10
+
11
+ ## Proposed solution
12
+
13
+ ## Alternatives considered
@@ -0,0 +1,11 @@
1
+ ---
2
+ name: Question
3
+ about: Ask how to use BrowserControl
4
+ labels: question
5
+ ---
6
+
7
+ ## Question
8
+
9
+ <!-- Please check the docs and troubleshooting page first. -->
10
+
11
+ ## What you have tried
@@ -0,0 +1,11 @@
1
+ ## Summary
2
+
3
+ <!-- What user-visible change does this make, and why? Link related issues: Fixes #123 -->
4
+
5
+ ## Checklist
6
+
7
+ - [ ] PR title follows Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:` ...)
8
+ - [ ] Commits are signed off (`git commit -s`)
9
+ - [ ] Tests added or updated
10
+ - [ ] Docs and the `server.py` instructions updated if a tool interface changed
11
+ - [ ] `make check` passes (ruff, mypy, pytest)
@@ -0,0 +1,2 @@
1
+ allowRemediationCommits:
2
+ individual: true
@@ -0,0 +1,101 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+
9
+ env:
10
+ # Pin the interpreter: without it uv picks the newest one on the runner
11
+ # (Homebrew Python 3.15 on macOS), which our dependencies don't support yet.
12
+ UV_PYTHON: "3.12"
13
+
14
+ jobs:
15
+ lint:
16
+ runs-on: ubuntu-latest
17
+ steps:
18
+ - name: Checkout
19
+ uses: actions/checkout@v4
20
+ with:
21
+ fetch-depth: 0
22
+
23
+ - name: Install uv
24
+ uses: astral-sh/setup-uv@v3
25
+ with:
26
+ version: "latest"
27
+
28
+ - name: Install dependencies
29
+ run: uv sync
30
+
31
+ - name: Run pre-commit hooks
32
+ run: uv run pre-commit run --all-files
33
+
34
+ - name: Run ruff check
35
+ run: uv run ruff check .
36
+
37
+ - name: Run ruff format check
38
+ run: uv run ruff format --check .
39
+
40
+ test:
41
+ needs: lint
42
+ strategy:
43
+ fail-fast: false
44
+ matrix:
45
+ os: [ubuntu-latest, windows-latest, macos-latest]
46
+ python-version: ["3.12", "3.14"]
47
+ runs-on: ${{ matrix.os }}
48
+ env:
49
+ UV_PYTHON: ${{ matrix.python-version }}
50
+ steps:
51
+ - name: Checkout
52
+ uses: actions/checkout@v4
53
+
54
+ - name: Install uv
55
+ uses: astral-sh/setup-uv@v3
56
+ with:
57
+ version: "latest"
58
+
59
+ - name: Install dependencies
60
+ run: uv sync
61
+
62
+ - name: Run tests
63
+ run: uv run pytest -v
64
+
65
+ security:
66
+ runs-on: ubuntu-latest
67
+ needs: lint
68
+ steps:
69
+ - name: Checkout
70
+ uses: actions/checkout@v4
71
+ with:
72
+ fetch-depth: 0
73
+
74
+ - name: Install uv
75
+ uses: astral-sh/setup-uv@v3
76
+ with:
77
+ version: "latest"
78
+
79
+ - name: Install dependencies
80
+ run: uv sync
81
+
82
+ - name: Run bandit security checks
83
+ run: uv run bandit -c pyproject.toml -r . --exclude ./tests,./.venv
84
+
85
+ type-check:
86
+ runs-on: ubuntu-latest
87
+ needs: lint
88
+ steps:
89
+ - name: Checkout
90
+ uses: actions/checkout@v4
91
+
92
+ - name: Install uv
93
+ uses: astral-sh/setup-uv@v3
94
+ with:
95
+ version: "latest"
96
+
97
+ - name: Install dependencies
98
+ run: uv sync
99
+
100
+ - name: Run mypy
101
+ run: uv run mypy browsercontrol/
@@ -0,0 +1,39 @@
1
+ # Dependency Review Action
2
+ #
3
+ # This Action will scan dependency manifest files that change as part of a Pull Request,
4
+ # surfacing known-vulnerable versions of the packages declared or updated in the PR.
5
+ # Once installed, if the workflow run is marked as required, PRs introducing known-vulnerable
6
+ # packages will be blocked from merging.
7
+ #
8
+ # Source repository: https://github.com/actions/dependency-review-action
9
+ # Public documentation: https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#dependency-review-enforcement
10
+ name: "Dependency review"
11
+ on:
12
+ pull_request:
13
+ branches: ["main"]
14
+
15
+ # If using a dependency submission action in this workflow this permission will need to be set to:
16
+ #
17
+ # permissions:
18
+ # contents: write
19
+ #
20
+ # https://docs.github.com/en/enterprise-cloud@latest/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api
21
+ permissions:
22
+ contents: read
23
+ # Write permissions for pull-requests are required for using the `comment-summary-in-pr` option, comment out if you aren't using this option
24
+ pull-requests: write
25
+
26
+ jobs:
27
+ dependency-review:
28
+ runs-on: ubuntu-latest
29
+ steps:
30
+ - name: "Checkout repository"
31
+ uses: actions/checkout@v4
32
+ - name: "Dependency Review"
33
+ uses: actions/dependency-review-action@v4
34
+ # Commonly enabled options, see https://github.com/actions/dependency-review-action#configuration-options for all available options.
35
+ with:
36
+ comment-summary-in-pr: always
37
+ # fail-on-severity: moderate
38
+ # deny-licenses: GPL-1.0-or-later, LGPL-2.0-or-later
39
+ # retry-on-snapshot-warnings: true
@@ -0,0 +1,97 @@
1
+ name: Docs
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+ workflow_dispatch:
9
+
10
+ permissions:
11
+ contents: read
12
+
13
+ concurrency:
14
+ group: docs-${{ github.ref }}
15
+ cancel-in-progress: true
16
+
17
+ jobs:
18
+ build:
19
+ name: Build docs
20
+ runs-on: ubuntu-latest
21
+ steps:
22
+ - name: Checkout
23
+ uses: actions/checkout@v4
24
+ with:
25
+ fetch-depth: 0 # full history for "last updated" dates
26
+
27
+ - name: Install uv
28
+ uses: astral-sh/setup-uv@v5
29
+
30
+ - name: Check the tool catalog is current
31
+ run: uv run --frozen python scripts/gen_tools_json.py --check
32
+
33
+ - name: Set up Node
34
+ uses: actions/setup-node@v4
35
+ with:
36
+ node-version: 22
37
+ cache: npm
38
+ cache-dependency-path: docs/package-lock.json
39
+
40
+ - name: Install docs dependencies
41
+ working-directory: docs
42
+ run: npm ci
43
+
44
+ - name: Build site
45
+ working-directory: docs
46
+ run: npm run build
47
+
48
+ - name: Check internal links and anchors
49
+ working-directory: docs
50
+ run: npm run check:links
51
+
52
+ - name: Upload site
53
+ uses: actions/upload-pages-artifact@v3
54
+ with:
55
+ path: docs/.vitepress/dist
56
+
57
+ deploy:
58
+ name: Deploy to GitHub Pages
59
+ needs: build
60
+ if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
61
+ runs-on: ubuntu-latest
62
+ permissions:
63
+ pages: write
64
+ id-token: write
65
+ environment:
66
+ name: github-pages
67
+ url: ${{ steps.deployment.outputs.page_url }}
68
+ steps:
69
+ - name: Detect whether GitHub Pages is enabled
70
+ id: pages-status
71
+ env:
72
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
73
+ GH_REPO: ${{ github.repository }}
74
+ GH_API: ${{ github.api_url }}
75
+ run: |
76
+ # actions/configure-pages fails with "Not Found" when Pages is off in
77
+ # the repo settings, so probe /pages first and skip cleanly if needed.
78
+ status=$(curl -sS -o /dev/null -w "%{http_code}" \
79
+ -H "Authorization: Bearer ${GH_TOKEN}" \
80
+ -H "Accept: application/vnd.github+json" \
81
+ -H "X-GitHub-Api-Version: 2022-11-28" \
82
+ "${GH_API}/repos/${GH_REPO}/pages")
83
+ if [ "${status}" = "200" ]; then
84
+ echo "enabled=true" >> "${GITHUB_OUTPUT}"
85
+ else
86
+ echo "enabled=false" >> "${GITHUB_OUTPUT}"
87
+ echo "::warning::GitHub Pages is not enabled for ${GH_REPO} (HTTP ${status}). Enable it under Settings -> Pages -> Build and deployment: GitHub Actions."
88
+ fi
89
+
90
+ - name: Setup Pages
91
+ if: steps.pages-status.outputs.enabled == 'true'
92
+ uses: actions/configure-pages@v5
93
+
94
+ - name: Deploy
95
+ if: steps.pages-status.outputs.enabled == 'true'
96
+ id: deployment
97
+ uses: actions/deploy-pages@v4
@@ -0,0 +1,56 @@
1
+ name: PR checks
2
+
3
+ on:
4
+ pull_request:
5
+ types: [opened, edited, synchronize, reopened]
6
+
7
+ permissions:
8
+ contents: read
9
+
10
+ concurrency:
11
+ group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
12
+ cancel-in-progress: true
13
+
14
+ jobs:
15
+ pr-title:
16
+ name: Conventional commit title
17
+ runs-on: ubuntu-latest
18
+ steps:
19
+ - name: Validate PR title
20
+ env:
21
+ PR_TITLE: ${{ github.event.pull_request.title }}
22
+ run: |
23
+ pattern='^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?: .+'
24
+ if ! [[ "$PR_TITLE" =~ $pattern ]]; then
25
+ echo "PR title must follow Conventional Commits, e.g. 'feat(tools): add x'."
26
+ echo "Got: $PR_TITLE"
27
+ exit 1
28
+ fi
29
+
30
+ dco:
31
+ name: DCO sign-off
32
+ runs-on: ubuntu-latest
33
+ steps:
34
+ - name: Checkout
35
+ uses: actions/checkout@v4
36
+ with:
37
+ fetch-depth: 0
38
+
39
+ - name: Check Signed-off-by trailers
40
+ env:
41
+ BASE_REF: ${{ github.event.pull_request.base.ref }}
42
+ run: |
43
+ status=0
44
+ for sha in $(git rev-list --no-merges "origin/${BASE_REF}..HEAD"); do
45
+ author_email=$(git log -1 --format='%ae' "$sha")
46
+ author_name=$(git log -1 --format='%an' "$sha")
47
+ case "$author_name" in *"[bot]") continue ;; esac
48
+ if ! git log -1 --format='%B' "$sha" | grep -qi '^Signed-off-by: .*<.*>'; then
49
+ echo "Commit $sha by $author_email is missing a Signed-off-by line."
50
+ status=1
51
+ fi
52
+ done
53
+ if [ "$status" -ne 0 ]; then
54
+ echo "Fix with: git rebase --signoff origin/${BASE_REF} && git push --force-with-lease"
55
+ fi
56
+ exit $status
@@ -0,0 +1,143 @@
1
+ name: Release
2
+
3
+ on:
4
+ push:
5
+ tags: ["v*"]
6
+
7
+ # Least privilege by default; individual jobs widen this where needed.
8
+ permissions:
9
+ contents: read
10
+
11
+ concurrency:
12
+ group: release-${{ github.ref }}
13
+ cancel-in-progress: false
14
+
15
+ jobs:
16
+ verify:
17
+ name: Verify tag and gate on tests
18
+ runs-on: ubuntu-latest
19
+ outputs:
20
+ version: ${{ steps.version.outputs.version }}
21
+ steps:
22
+ - name: Checkout
23
+ uses: actions/checkout@v4
24
+ with:
25
+ fetch-depth: 0
26
+
27
+ - name: Install uv
28
+ uses: astral-sh/setup-uv@v3
29
+ with:
30
+ version: "latest"
31
+
32
+ - name: Check tag matches the version in pyproject.toml
33
+ id: version
34
+ run: |
35
+ set -euo pipefail
36
+ tag="${GITHUB_REF_NAME#v}"
37
+ project=$(python3 -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
38
+ echo "tag version: ${tag}"
39
+ echo "project version: ${project}"
40
+ if [ "${tag}" != "${project}" ]; then
41
+ echo "::error::Tag ${GITHUB_REF_NAME} does not match pyproject.toml version ${project}. Bump the version and re-tag."
42
+ exit 1
43
+ fi
44
+ echo "version=${project}" >> "${GITHUB_OUTPUT}"
45
+
46
+ - name: Refuse to re-release an existing PyPI version
47
+ run: |
48
+ set -euo pipefail
49
+ version="${{ steps.version.outputs.version }}"
50
+ status=$(curl -sS -o /dev/null -w "%{http_code}" "https://pypi.org/pypi/browsercontrol/${version}/json")
51
+ if [ "${status}" = "200" ]; then
52
+ echo "::error::browsercontrol ${version} is already on PyPI. PyPI does not allow overwriting a release; bump the version."
53
+ exit 1
54
+ fi
55
+ echo "Version ${version} is not yet on PyPI; continuing."
56
+
57
+ - name: Install dependencies
58
+ run: uv sync
59
+
60
+ - name: Lint
61
+ run: |
62
+ uv run ruff check .
63
+ uv run ruff format --check .
64
+
65
+ - name: Type-check
66
+ run: uv run mypy browsercontrol/
67
+
68
+ - name: Security scan
69
+ run: uv run bandit -c pyproject.toml -r . --exclude ./tests,./.venv
70
+
71
+ - name: Run tests
72
+ run: uv run pytest -v
73
+
74
+ build:
75
+ name: Build distributions
76
+ needs: verify
77
+ runs-on: ubuntu-latest
78
+ steps:
79
+ - name: Checkout
80
+ uses: actions/checkout@v4
81
+ with:
82
+ fetch-depth: 0
83
+
84
+ - name: Install uv
85
+ uses: astral-sh/setup-uv@v3
86
+ with:
87
+ version: "latest"
88
+
89
+ - name: Build sdist and wheel
90
+ run: uv build
91
+
92
+ - name: Check distribution metadata
93
+ run: uvx twine check dist/*
94
+
95
+ - name: Upload distributions
96
+ uses: actions/upload-artifact@v4
97
+ with:
98
+ name: dist
99
+ path: dist/
100
+ if-no-files-found: error
101
+
102
+ publish:
103
+ name: Publish to PyPI
104
+ needs: build
105
+ runs-on: ubuntu-latest
106
+ environment:
107
+ name: pypi
108
+ url: https://pypi.org/p/browsercontrol
109
+ permissions:
110
+ # Required for PyPI Trusted Publishing (OIDC). No API token is stored.
111
+ id-token: write
112
+ steps:
113
+ - name: Download distributions
114
+ uses: actions/download-artifact@v4
115
+ with:
116
+ name: dist
117
+ path: dist/
118
+
119
+ - name: Publish
120
+ uses: pypa/gh-action-pypi-publish@release/v1
121
+
122
+ github-release:
123
+ name: Create GitHub Release
124
+ needs: [verify, publish]
125
+ runs-on: ubuntu-latest
126
+ permissions:
127
+ contents: write
128
+ steps:
129
+ - name: Download distributions
130
+ uses: actions/download-artifact@v4
131
+ with:
132
+ name: dist
133
+ path: dist/
134
+
135
+ - name: Create release with generated notes
136
+ env:
137
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
138
+ run: |
139
+ gh release create "${GITHUB_REF_NAME}" \
140
+ --repo "${GITHUB_REPOSITORY}" \
141
+ --title "${GITHUB_REF_NAME}" \
142
+ --generate-notes \
143
+ dist/*
@@ -0,0 +1,35 @@
1
+ # IDE
2
+ .idea/
3
+ .vscode/
4
+ *.iml
5
+
6
+ # Python
7
+ */__pycache__/*
8
+ *.py[cod]
9
+ dist/
10
+ .pytest_cache/
11
+ .coverage
12
+
13
+ # Virtual environments
14
+ .venv/
15
+ .ruff_cache/
16
+ .pytest_cache/
17
+
18
+ # Docs site (VitePress)
19
+ docs/node_modules/
20
+ docs/.vitepress/dist/
21
+ docs/.vitepress/cache/
22
+
23
+ # Locally captured screenshots (not referenced by the docs site)
24
+ /assets/live/
25
+
26
+ # Local scratch directories (not committed)
27
+ .claude/
28
+ .test-tmp/
29
+
30
+ # OS
31
+ .DS_Store
32
+ Thumbs.db
33
+
34
+ # Internal hiring documents (not published)
35
+ /internal/
@@ -1,7 +1,9 @@
1
+ fail_fast: true
2
+
1
3
  repos:
2
4
  # Ruff - Fast Python linter and formatter
3
5
  - repo: https://github.com/astral-sh/ruff-pre-commit
4
- rev: v0.8.4
6
+ rev: v0.17.6
5
7
  hooks:
6
8
  # Run the linter
7
9
  - id: ruff
@@ -11,11 +13,12 @@ repos:
11
13
 
12
14
  # General file checks
13
15
  - repo: https://github.com/pre-commit/pre-commit-hooks
14
- rev: v5.0.0
16
+ rev: v6.0.0
15
17
  hooks:
16
18
  - id: trailing-whitespace
17
19
  - id: end-of-file-fixer
18
20
  - id: check-yaml
21
+ args: [--unsafe]
19
22
  - id: check-toml
20
23
  - id: check-json
21
24
  - id: check-added-large-files
@@ -25,23 +28,46 @@ repos:
25
28
  - id: mixed-line-ending
26
29
  args: [--fix=lf]
27
30
 
28
- # Markdown formatting
29
- - repo: https://github.com/pre-commit/mirrors-prettier
30
- rev: v4.0.0-alpha.8
31
- hooks:
32
- - id: prettier
33
- types_or: [markdown, yaml, json]
34
- exclude: ^(uv\.lock|\.vscode/)
35
-
36
31
  # Python security checks
37
32
  - repo: https://github.com/PyCQA/bandit
38
- rev: 1.8.0
33
+ rev: 1.9.4
39
34
  hooks:
40
35
  - id: bandit
41
36
  args: [-c, pyproject.toml]
42
37
  additional_dependencies: ["bandit[toml]"]
43
38
  exclude: ^tests/
44
39
 
40
+ # GitHub Actions workflow checks
41
+ - repo: https://github.com/rhysd/actionlint
42
+ rev: v1.7.12
43
+ hooks:
44
+ - id: actionlint
45
+
46
+ # Keep uv.lock in sync with pyproject.toml
47
+ - repo: https://github.com/astral-sh/uv-pre-commit
48
+ rev: 0.13.9
49
+ hooks:
50
+ - id: uv-lock
51
+
52
+ # Local checks
53
+ - repo: local
54
+ hooks:
55
+ - id: tach
56
+ name: Check Python import boundaries
57
+ entry: tach check
58
+ language: python
59
+ additional_dependencies: ["tach==0.35.3"]
60
+ files: '^(browsercontrol/.*\.py|tach\.toml)$'
61
+ pass_filenames: false
62
+
63
+ - id: max-lines
64
+ name: Check max lines per file
65
+ entry: python3 scripts/checks/check_max_lines.py
66
+ args: [--max-lines=800]
67
+ language: system
68
+ files: '\.(py|md|yml|yaml|toml)$'
69
+ exclude: '^(uv\.lock|docs/llms\.txt)$'
70
+
45
71
  # CI configuration
46
72
  ci:
47
73
  autofix_commit_msg: |
@@ -0,0 +1,4 @@
1
+ # Repository Guidelines
2
+
3
+ Agent guidance for this repository lives in [CLAUDE.md](CLAUDE.md): commands, architecture,
4
+ testing conventions, and contribution rules. Read it before making changes.