browsercontrol 0.1.4__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 (171) 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.1.4 → browsercontrol-0.3.0}/.github/workflows/ci.yml +19 -53
  10. browsercontrol-0.3.0/.github/workflows/docs.yml +97 -0
  11. browsercontrol-0.3.0/.github/workflows/pr-checks.yml +56 -0
  12. browsercontrol-0.3.0/.github/workflows/release.yml +143 -0
  13. browsercontrol-0.3.0/.gitignore +35 -0
  14. {browsercontrol-0.1.4 → browsercontrol-0.3.0}/.pre-commit-config.yaml +37 -3
  15. browsercontrol-0.3.0/AGENTS.md +4 -0
  16. browsercontrol-0.3.0/CHANGELOG.md +62 -0
  17. browsercontrol-0.3.0/CLAUDE.md +209 -0
  18. {browsercontrol-0.1.4 → browsercontrol-0.3.0}/CONTRIBUTING.md +13 -5
  19. browsercontrol-0.3.0/Makefile +43 -0
  20. browsercontrol-0.3.0/PKG-INFO +203 -0
  21. browsercontrol-0.3.0/README.es-ES.md +176 -0
  22. browsercontrol-0.3.0/README.md +176 -0
  23. browsercontrol-0.3.0/assets/demo-dark.gif +0 -0
  24. browsercontrol-0.3.0/assets/demo-light.gif +0 -0
  25. browsercontrol-0.3.0/assets/som-demo.gif +0 -0
  26. browsercontrol-0.3.0/browsercontrol/__main__.py +71 -0
  27. browsercontrol-0.3.0/browsercontrol/browser.py +721 -0
  28. browsercontrol-0.3.0/browsercontrol/codegen.py +363 -0
  29. browsercontrol-0.3.0/browsercontrol/config.py +118 -0
  30. browsercontrol-0.3.0/browsercontrol/elements.py +388 -0
  31. browsercontrol-0.3.0/browsercontrol/emulation.py +102 -0
  32. browsercontrol-0.3.0/browsercontrol/resources.py +116 -0
  33. browsercontrol-0.3.0/browsercontrol/server.py +192 -0
  34. browsercontrol-0.3.0/browsercontrol/session.py +262 -0
  35. {browsercontrol-0.1.4 → browsercontrol-0.3.0}/browsercontrol/tools/__init__.py +14 -0
  36. browsercontrol-0.3.0/browsercontrol/tools/_summary.py +68 -0
  37. browsercontrol-0.3.0/browsercontrol/tools/batch.py +187 -0
  38. {browsercontrol-0.1.4 → browsercontrol-0.3.0}/browsercontrol/tools/content.py +27 -28
  39. {browsercontrol-0.1.4 → browsercontrol-0.3.0}/browsercontrol/tools/devtools.py +31 -40
  40. browsercontrol-0.3.0/browsercontrol/tools/emulate.py +213 -0
  41. browsercontrol-0.3.0/browsercontrol/tools/extract.py +288 -0
  42. browsercontrol-0.3.0/browsercontrol/tools/forms.py +222 -0
  43. browsercontrol-0.3.0/browsercontrol/tools/interaction.py +354 -0
  44. {browsercontrol-0.1.4 → browsercontrol-0.3.0}/browsercontrol/tools/navigation.py +25 -36
  45. browsercontrol-0.3.0/browsercontrol/tools/network.py +358 -0
  46. {browsercontrol-0.1.4 → browsercontrol-0.3.0}/browsercontrol/tools/recording.py +46 -7
  47. browsercontrol-0.3.0/browsercontrol/tools/search.py +205 -0
  48. browsercontrol-0.3.0/browsercontrol/tools/sessions.py +136 -0
  49. {browsercontrol-0.1.4 → browsercontrol-0.3.0}/browsercontrol/tools/tabs.py +4 -4
  50. browsercontrol-0.3.0/browsercontrol/tools/waiting.py +122 -0
  51. browsercontrol-0.3.0/docs/.vitepress/config.mts +229 -0
  52. browsercontrol-0.3.0/docs/.vitepress/theme/Layout.vue +68 -0
  53. browsercontrol-0.3.0/docs/.vitepress/theme/components/Card.vue +64 -0
  54. browsercontrol-0.3.0/docs/.vitepress/theme/components/CardGrid.vue +12 -0
  55. browsercontrol-0.3.0/docs/.vitepress/theme/components/InstallBox.vue +212 -0
  56. browsercontrol-0.3.0/docs/.vitepress/theme/components/Mark.vue +36 -0
  57. browsercontrol-0.3.0/docs/.vitepress/theme/components/ToolExplorer.vue +387 -0
  58. browsercontrol-0.3.0/docs/.vitepress/theme/components/home/AgentSection.vue +291 -0
  59. browsercontrol-0.3.0/docs/.vitepress/theme/components/home/FeatureGrid.vue +732 -0
  60. browsercontrol-0.3.0/docs/.vitepress/theme/components/home/HomePage.vue +716 -0
  61. browsercontrol-0.3.0/docs/.vitepress/theme/components/home/MarksDemo.vue +778 -0
  62. browsercontrol-0.3.0/docs/.vitepress/theme/index.ts +49 -0
  63. browsercontrol-0.3.0/docs/.vitepress/theme/redirects.ts +51 -0
  64. browsercontrol-0.3.0/docs/.vitepress/theme/reveal.ts +49 -0
  65. browsercontrol-0.3.0/docs/.vitepress/theme/style/base.css +133 -0
  66. browsercontrol-0.3.0/docs/.vitepress/theme/style/docs.css +359 -0
  67. browsercontrol-0.3.0/docs/.vitepress/theme/style/vars.css +63 -0
  68. browsercontrol-0.3.0/docs/.vitepress/theme/tools.data.ts +38 -0
  69. browsercontrol-0.3.0/docs/concepts/comparison.md +55 -0
  70. browsercontrol-0.3.0/docs/concepts/how-it-works.md +79 -0
  71. browsercontrol-0.3.0/docs/concepts/sessions.md +58 -0
  72. browsercontrol-0.3.0/docs/concepts/set-of-marks.md +83 -0
  73. browsercontrol-0.3.0/docs/concepts/settling.md +63 -0
  74. browsercontrol-0.3.0/docs/guide/agent-skill.md +69 -0
  75. browsercontrol-0.3.0/docs/guide/clients.md +187 -0
  76. browsercontrol-0.3.0/docs/guide/first-session.md +67 -0
  77. browsercontrol-0.3.0/docs/guide/http.md +58 -0
  78. browsercontrol-0.3.0/docs/guide/index.md +59 -0
  79. browsercontrol-0.3.0/docs/guide/installation.md +81 -0
  80. browsercontrol-0.3.0/docs/guide/quickstart.md +56 -0
  81. browsercontrol-0.3.0/docs/help/faq.md +46 -0
  82. browsercontrol-0.3.0/docs/help/troubleshooting.md +120 -0
  83. browsercontrol-0.3.0/docs/index.md +24 -0
  84. browsercontrol-0.3.0/docs/package-lock.json +4043 -0
  85. browsercontrol-0.3.0/docs/package.json +20 -0
  86. browsercontrol-0.3.0/docs/project/about.md +33 -0
  87. browsercontrol-0.3.0/docs/project/changelog.md +6 -0
  88. browsercontrol-0.3.0/docs/project/contributing.md +87 -0
  89. browsercontrol-0.3.0/docs/public/images/annotated-web-form.webp +0 -0
  90. browsercontrol-0.3.0/docs/public/images/favicon.svg +20 -0
  91. browsercontrol-0.3.0/docs/public/logo-mascot.png +0 -0
  92. browsercontrol-0.3.0/docs/public/mascot.png +0 -0
  93. browsercontrol-0.3.0/docs/public/og-card.png +0 -0
  94. browsercontrol-0.3.0/docs/public/tools.json +1463 -0
  95. browsercontrol-0.3.0/docs/recipes/debug.md +96 -0
  96. browsercontrol-0.3.0/docs/recipes/edge-states.md +86 -0
  97. browsercontrol-0.3.0/docs/recipes/extract-data.md +74 -0
  98. browsercontrol-0.3.0/docs/recipes/fill-a-form.md +49 -0
  99. browsercontrol-0.3.0/docs/recipes/index.md +32 -0
  100. browsercontrol-0.3.0/docs/recipes/record-tests.md +83 -0
  101. browsercontrol-0.3.0/docs/recipes/research.md +57 -0
  102. browsercontrol-0.3.0/docs/recipes/responsive.md +52 -0
  103. browsercontrol-0.3.0/docs/recipes/tabs.md +49 -0
  104. browsercontrol-0.3.0/docs/recipes/upload-a-file.md +50 -0
  105. browsercontrol-0.3.0/docs/recipes/your-chrome.md +91 -0
  106. browsercontrol-0.3.0/docs/reference/configuration.md +152 -0
  107. browsercontrol-0.3.0/docs/reference/content.md +110 -0
  108. browsercontrol-0.3.0/docs/reference/devtools.md +210 -0
  109. browsercontrol-0.3.0/docs/reference/emulation.md +133 -0
  110. browsercontrol-0.3.0/docs/reference/extraction.md +92 -0
  111. browsercontrol-0.3.0/docs/reference/forms.md +87 -0
  112. browsercontrol-0.3.0/docs/reference/index.md +83 -0
  113. browsercontrol-0.3.0/docs/reference/interaction.md +249 -0
  114. browsercontrol-0.3.0/docs/reference/navigation.md +136 -0
  115. browsercontrol-0.3.0/docs/reference/network.md +123 -0
  116. browsercontrol-0.3.0/docs/reference/recording.md +117 -0
  117. browsercontrol-0.3.0/docs/reference/resources.md +27 -0
  118. browsercontrol-0.3.0/docs/reference/sessions.md +116 -0
  119. browsercontrol-0.3.0/docs/reference/tabs.md +85 -0
  120. browsercontrol-0.3.0/docs/reference/waiting.md +82 -0
  121. browsercontrol-0.3.0/docs/scripts/check-links.mjs +68 -0
  122. browsercontrol-0.3.0/docs/superpowers/plans/2026-11-21-project-foundation.md +116 -0
  123. browsercontrol-0.3.0/docs/superpowers/specs/2026-11-21-project-foundation-design.md +43 -0
  124. browsercontrol-0.3.0/mcp.json +14 -0
  125. browsercontrol-0.3.0/opencode/plugin.js +48 -0
  126. browsercontrol-0.3.0/package.json +21 -0
  127. browsercontrol-0.3.0/plugin.json +27 -0
  128. {browsercontrol-0.1.4 → browsercontrol-0.3.0}/pyproject.toml +8 -5
  129. browsercontrol-0.3.0/scripts/checks/check_max_lines.py +34 -0
  130. browsercontrol-0.3.0/scripts/gen_tools_json.py +147 -0
  131. browsercontrol-0.3.0/skills/browsercontrol/SKILL.md +162 -0
  132. browsercontrol-0.3.0/tach.toml +18 -0
  133. {browsercontrol-0.1.4 → browsercontrol-0.3.0}/tests/conftest.py +6 -0
  134. browsercontrol-0.3.0/tests/test_agent_features.py +261 -0
  135. {browsercontrol-0.1.4 → browsercontrol-0.3.0}/tests/test_browser.py +203 -48
  136. browsercontrol-0.3.0/tests/test_check_max_lines.py +42 -0
  137. browsercontrol-0.3.0/tests/test_config.py +46 -0
  138. {browsercontrol-0.1.4 → browsercontrol-0.3.0}/tests/test_content.py +36 -11
  139. {browsercontrol-0.1.4 → browsercontrol-0.3.0}/tests/test_devtools.py +68 -0
  140. browsercontrol-0.3.0/tests/test_docs.py +59 -0
  141. browsercontrol-0.3.0/tests/test_element_summary.py +90 -0
  142. browsercontrol-0.3.0/tests/test_elements.py +252 -0
  143. browsercontrol-0.3.0/tests/test_features_real_browser.py +548 -0
  144. browsercontrol-0.3.0/tests/test_forms.py +396 -0
  145. browsercontrol-0.3.0/tests/test_interaction.py +320 -0
  146. browsercontrol-0.3.0/tests/test_plugin_manifest.py +38 -0
  147. {browsercontrol-0.1.4 → browsercontrol-0.3.0}/tests/test_recording.py +8 -10
  148. browsercontrol-0.3.0/tests/test_server.py +42 -0
  149. browsercontrol-0.3.0/tests/test_som_real_browser.py +399 -0
  150. {browsercontrol-0.1.4 → browsercontrol-0.3.0}/tests/test_tabs.py +4 -4
  151. {browsercontrol-0.1.4 → browsercontrol-0.3.0}/uv.lock +326 -181
  152. browsercontrol-0.1.4/.claude/settings.local.json +0 -10
  153. browsercontrol-0.1.4/.gitignore +0 -15
  154. browsercontrol-0.1.4/CLAUDE.md +0 -114
  155. browsercontrol-0.1.4/CODE_QUALITY.md +0 -81
  156. browsercontrol-0.1.4/PKG-INFO +0 -763
  157. browsercontrol-0.1.4/README.md +0 -737
  158. browsercontrol-0.1.4/browsercontrol/__main__.py +0 -19
  159. browsercontrol-0.1.4/browsercontrol/browser.py +0 -546
  160. browsercontrol-0.1.4/browsercontrol/config.py +0 -57
  161. browsercontrol-0.1.4/browsercontrol/server.py +0 -97
  162. browsercontrol-0.1.4/browsercontrol/tools/forms.py +0 -156
  163. browsercontrol-0.1.4/browsercontrol/tools/interaction.py +0 -232
  164. browsercontrol-0.1.4/tests/test_forms.py +0 -151
  165. browsercontrol-0.1.4/tests/test_interaction.py +0 -235
  166. {browsercontrol-0.1.4 → browsercontrol-0.3.0}/.github/workflows/dependency-review.yml +0 -0
  167. {browsercontrol-0.1.4 → browsercontrol-0.3.0}/LICENSE +0 -0
  168. {browsercontrol-0.1.4 → browsercontrol-0.3.0}/assets/logo-main.png +0 -0
  169. {browsercontrol-0.1.4 → browsercontrol-0.3.0}/browsercontrol/__init__.py +0 -0
  170. {browsercontrol-0.1.4 → browsercontrol-0.3.0}/tests/__init__.py +0 -0
  171. {browsercontrol-0.1.4 → browsercontrol-0.3.0}/tests/test_navigation.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
@@ -6,6 +6,11 @@ on:
6
6
  pull_request:
7
7
  branches: [main]
8
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
+
9
14
  jobs:
10
15
  lint:
11
16
  runs-on: ubuntu-latest
@@ -21,7 +26,7 @@ jobs:
21
26
  version: "latest"
22
27
 
23
28
  - name: Install dependencies
24
- run: uv sync --all-extras
29
+ run: uv sync
25
30
 
26
31
  - name: Run pre-commit hooks
27
32
  run: uv run pre-commit run --all-files
@@ -33,30 +38,15 @@ jobs:
33
38
  run: uv run ruff format --check .
34
39
 
35
40
  test:
36
- runs-on: ubuntu-latest
37
- needs: lint
38
- steps:
39
- - name: Checkout
40
- uses: actions/checkout@v4
41
-
42
- - name: Install uv
43
- uses: astral-sh/setup-uv@v3
44
- with:
45
- version: "latest"
46
-
47
- - name: Install dependencies
48
- run: uv sync --all-extras
49
-
50
- - name: Install Playwright browsers
51
- run: uv run playwright install chromium --with-deps
52
-
53
- - name: Run tests
54
- run: uv run pytest -v
55
-
56
- # Test on Windows and macOS as well
57
- test-windows:
58
- runs-on: windows-latest
59
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 }}
60
50
  steps:
61
51
  - name: Checkout
62
52
  uses: actions/checkout@v4
@@ -67,31 +57,7 @@ jobs:
67
57
  version: "latest"
68
58
 
69
59
  - name: Install dependencies
70
- run: uv sync --all-extras
71
-
72
- - name: Install Playwright browsers
73
- run: uv run playwright install chromium
74
-
75
- - name: Run tests
76
- run: uv run pytest -v
77
-
78
- test-macos:
79
- runs-on: macos-latest
80
- needs: lint
81
- steps:
82
- - name: Checkout
83
- uses: actions/checkout@v4
84
-
85
- - name: Install uv
86
- uses: astral-sh/setup-uv@v3
87
- with:
88
- version: "latest"
89
-
90
- - name: Install dependencies
91
- run: uv sync --all-extras
92
-
93
- - name: Install Playwright browsers
94
- run: uv run playwright install chromium
60
+ run: uv sync
95
61
 
96
62
  - name: Run tests
97
63
  run: uv run pytest -v
@@ -111,7 +77,7 @@ jobs:
111
77
  version: "latest"
112
78
 
113
79
  - name: Install dependencies
114
- run: uv sync --all-extras
80
+ run: uv sync
115
81
 
116
82
  - name: Run bandit security checks
117
83
  run: uv run bandit -c pyproject.toml -r . --exclude ./tests,./.venv
@@ -129,7 +95,7 @@ jobs:
129
95
  version: "latest"
130
96
 
131
97
  - name: Install dependencies
132
- run: uv sync --all-extras
98
+ run: uv sync
133
99
 
134
- - name: Run mypy (if type hints are used)
135
- run: uv run mypy browsercontrol/ || echo "No mypy configuration found"
100
+ - name: Run mypy
101
+ run: uv run mypy browsercontrol/
@@ -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
@@ -27,13 +30,44 @@ repos:
27
30
 
28
31
  # Python security checks
29
32
  - repo: https://github.com/PyCQA/bandit
30
- rev: 1.8.0
33
+ rev: 1.9.4
31
34
  hooks:
32
35
  - id: bandit
33
36
  args: [-c, pyproject.toml]
34
37
  additional_dependencies: ["bandit[toml]"]
35
38
  exclude: ^tests/
36
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
+
37
71
  # CI configuration
38
72
  ci:
39
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.