browseable 0.1.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 (16) hide show
  1. browseable-0.1.0/PKG-INFO +128 -0
  2. browseable-0.1.0/README.md +120 -0
  3. browseable-0.1.0/browseable/__init__.py +5 -0
  4. browseable-0.1.0/browseable/__main__.py +5 -0
  5. browseable-0.1.0/browseable/cli.py +455 -0
  6. browseable-0.1.0/browseable/client.py +49 -0
  7. browseable-0.1.0/browseable/config.py +48 -0
  8. browseable-0.1.0/browseable/daemon_server.py +583 -0
  9. browseable-0.1.0/browseable.egg-info/PKG-INFO +128 -0
  10. browseable-0.1.0/browseable.egg-info/SOURCES.txt +14 -0
  11. browseable-0.1.0/browseable.egg-info/dependency_links.txt +1 -0
  12. browseable-0.1.0/browseable.egg-info/entry_points.txt +2 -0
  13. browseable-0.1.0/browseable.egg-info/requires.txt +1 -0
  14. browseable-0.1.0/browseable.egg-info/top_level.txt +1 -0
  15. browseable-0.1.0/pyproject.toml +19 -0
  16. browseable-0.1.0/setup.cfg +4 -0
browseable-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,128 @@
1
+ Metadata-Version: 2.4
2
+ Name: browseable
3
+ Version: 0.1.0
4
+ Summary: CLI for browser sessions and interactable element actions
5
+ Requires-Python: >=3.8
6
+ Description-Content-Type: text/markdown
7
+ Requires-Dist: playwright<2,>=1.42.0
8
+
9
+ # browseable
10
+
11
+ `browseable` is a Unix-style CLI backed by a local daemon that keeps browser sessions alive between commands.
12
+
13
+ ## What it does
14
+
15
+ - API 1 (`elements`): given a session, list interactable form/navigation elements.
16
+ - API 2 (`action`): given a session, perform an action (`click`, `type`, or `interact`).
17
+
18
+ The daemon holds browser + page state so each CLI command is short-lived.
19
+
20
+ ## Install
21
+
22
+ ```bash
23
+ uv sync
24
+ uv run playwright install chromium
25
+ ```
26
+
27
+ ## Quick start
28
+
29
+ ```bash
30
+ # Optional convenience.
31
+ alias browseable='uv run browseable'
32
+
33
+ # 1) start daemon
34
+ browseable daemon start
35
+
36
+ # 2) create a session (returns session ID)
37
+ browseable session create https://example.com/signup
38
+
39
+ # 3) list elements for that session
40
+ browseable elements <session_id>
41
+
42
+ # 4) focus an element
43
+ browseable action <session_id> click 2
44
+
45
+ # 5) type into an element
46
+ browseable action <session_id> type 3 "my@email.com"
47
+
48
+ # 6) open interactive browser window for the same session
49
+ browseable action <session_id> interact
50
+
51
+ # 7) close session + stop daemon
52
+ browseable session close <session_id>
53
+ browseable daemon stop
54
+ ```
55
+
56
+ ## Commands
57
+
58
+ ```text
59
+ browseable daemon start|run|status|stop
60
+ browseable session create <url>
61
+ browseable session close <session_id>
62
+ browseable elements <session_id> [--json]
63
+ browseable action <session_id> click <element_or_index> [--timeout-ms]
64
+ browseable action <session_id> type <element_or_index> <text> [--timeout-ms]
65
+ browseable action <session_id> interact [--timeout-ms]
66
+ ```
67
+
68
+ `interact` focuses the session in a real browser window. If daemon started headless, `interact` promotes the session into a headed browser context.
69
+
70
+ `BROWSEABLE_DAEMON_URL` can override the daemon address if needed.
71
+
72
+ ## Daemon JSON API
73
+
74
+ The daemon exposes local HTTP endpoints:
75
+
76
+ - `POST /sessions` with `{"url":"..."}` -> create session.
77
+ - `GET /sessions/<session_id>/elements` -> list interactable elements.
78
+ - `POST /sessions/<session_id>/actions` with `{"action":"click"|"type","element_id":"...","text":"..."}`.
79
+ - `POST /sessions/<session_id>/actions` with `{"action":"interact"}` -> promote/focus session in a headed browser window.
80
+ - `DELETE /sessions/<session_id>` -> close session.
81
+
82
+ ## E2E Example
83
+
84
+ Run the telemetry register flow:
85
+
86
+ ```bash
87
+ uv run scripts/e2e_telemetry_register.sh
88
+ ```
89
+
90
+ ## GitHub Workflows
91
+
92
+ - `/.github/workflows/ci.yml`: compile + CLI smoke checks on `push`/`pull_request`.
93
+ - `/.github/workflows/publish-testpypi.yml`: manual publish to TestPyPI.
94
+ - `/.github/workflows/publish-pypi.yml`: publish to PyPI on `v*` tags (or manual dispatch).
95
+
96
+ ## How to Publish to PyPI
97
+
98
+ 1. Create package projects:
99
+ - [https://test.pypi.org/](https://test.pypi.org/)
100
+ - [https://pypi.org/](https://pypi.org/)
101
+ 2. Configure Trusted Publishing on each project:
102
+ - Owner/repo: your GitHub repo.
103
+ - Workflow file:
104
+ - TestPyPI: `.github/workflows/publish-testpypi.yml`
105
+ - PyPI: `.github/workflows/publish-pypi.yml`
106
+ - Environment name:
107
+ - TestPyPI: `testpypi`
108
+ - PyPI: `pypi`
109
+ 3. Test release on TestPyPI by running `Publish to TestPyPI` (workflow dispatch).
110
+ 4. Release to PyPI:
111
+ - Bump version in `pyproject.toml`.
112
+ - Commit and push.
113
+ - Tag and push `vX.Y.Z` (must match `pyproject.toml` version).
114
+ 5. Verify install:
115
+
116
+ ```bash
117
+ python -m pip install browseable==0.1.1
118
+ ```
119
+
120
+ ### Optional Manual Publish (No GitHub Actions)
121
+
122
+ ```bash
123
+ uv build
124
+ uvx twine check dist/*
125
+ uvx twine upload dist/*
126
+ ```
127
+
128
+ For manual upload, create a PyPI API token and use `TWINE_USERNAME=__token__` and `TWINE_PASSWORD=<token>` (or `~/.pypirc`).
browseable-0.1.0/README.md ADDED
@@ -0,0 +1,120 @@
1
+ # browseable
2
+
3
+ `browseable` is a Unix-style CLI backed by a local daemon that keeps browser sessions alive between commands.
4
+
5
+ ## What it does
6
+
7
+ - API 1 (`elements`): given a session, list interactable form/navigation elements.
8
+ - API 2 (`action`): given a session, perform an action (`click`, `type`, or `interact`).
9
+
10
+ The daemon holds browser + page state so each CLI command is short-lived.
11
+
12
+ ## Install
13
+
14
+ ```bash
15
+ uv sync
16
+ uv run playwright install chromium
17
+ ```
18
+
19
+ ## Quick start
20
+
21
+ ```bash
22
+ # Optional convenience.
23
+ alias browseable='uv run browseable'
24
+
25
+ # 1) start daemon
26
+ browseable daemon start
27
+
28
+ # 2) create a session (returns session ID)
29
+ browseable session create https://example.com/signup
30
+
31
+ # 3) list elements for that session
32
+ browseable elements <session_id>
33
+
34
+ # 4) focus an element
35
+ browseable action <session_id> click 2
36
+
37
+ # 5) type into an element
38
+ browseable action <session_id> type 3 "my@email.com"
39
+
40
+ # 6) open interactive browser window for the same session
41
+ browseable action <session_id> interact
42
+
43
+ # 7) close session + stop daemon
44
+ browseable session close <session_id>
45
+ browseable daemon stop
46
+ ```
47
+
48
+ ## Commands
49
+
50
+ ```text
51
+ browseable daemon start|run|status|stop
52
+ browseable session create <url>
53
+ browseable session close <session_id>
54
+ browseable elements <session_id> [--json]
55
+ browseable action <session_id> click <element_or_index> [--timeout-ms]
56
+ browseable action <session_id> type <element_or_index> <text> [--timeout-ms]
57
+ browseable action <session_id> interact [--timeout-ms]
58
+ ```
59
+
60
+ `interact` focuses the session in a real browser window. If daemon started headless, `interact` promotes the session into a headed browser context.
61
+
62
+ `BROWSEABLE_DAEMON_URL` can override the daemon address if needed.
63
+
64
+ ## Daemon JSON API
65
+
66
+ The daemon exposes local HTTP endpoints:
67
+
68
+ - `POST /sessions` with `{"url":"..."}` -> create session.
69
+ - `GET /sessions/<session_id>/elements` -> list interactable elements.
70
+ - `POST /sessions/<session_id>/actions` with `{"action":"click"|"type","element_id":"...","text":"..."}`.
71
+ - `POST /sessions/<session_id>/actions` with `{"action":"interact"}` -> promote/focus session in a headed browser window.
72
+ - `DELETE /sessions/<session_id>` -> close session.
73
+
74
+ ## E2E Example
75
+
76
+ Run the telemetry register flow:
77
+
78
+ ```bash
79
+ uv run scripts/e2e_telemetry_register.sh
80
+ ```
81
+
82
+ ## GitHub Workflows
83
+
84
+ - `/.github/workflows/ci.yml`: compile + CLI smoke checks on `push`/`pull_request`.
85
+ - `/.github/workflows/publish-testpypi.yml`: manual publish to TestPyPI.
86
+ - `/.github/workflows/publish-pypi.yml`: publish to PyPI on `v*` tags (or manual dispatch).
87
+
88
+ ## How to Publish to PyPI
89
+
90
+ 1. Create package projects:
91
+ - [https://test.pypi.org/](https://test.pypi.org/)
92
+ - [https://pypi.org/](https://pypi.org/)
93
+ 2. Configure Trusted Publishing on each project:
94
+ - Owner/repo: your GitHub repo.
95
+ - Workflow file:
96
+ - TestPyPI: `.github/workflows/publish-testpypi.yml`
97
+ - PyPI: `.github/workflows/publish-pypi.yml`
98
+ - Environment name:
99
+ - TestPyPI: `testpypi`
100
+ - PyPI: `pypi`
101
+ 3. Test release on TestPyPI by running `Publish to TestPyPI` (workflow dispatch).
102
+ 4. Release to PyPI:
103
+ - Bump version in `pyproject.toml`.
104
+ - Commit and push.
105
+ - Tag and push `vX.Y.Z` (must match `pyproject.toml` version).
106
+ 5. Verify install:
107
+
108
+ ```bash
109
+ python -m pip install browseable==0.1.1
110
+ ```
111
+
112
+ ### Optional Manual Publish (No GitHub Actions)
113
+
114
+ ```bash
115
+ uv build
116
+ uvx twine check dist/*
117
+ uvx twine upload dist/*
118
+ ```
119
+
120
+ For manual upload, create a PyPI API token and use `TWINE_USERNAME=__token__` and `TWINE_PASSWORD=<token>` (or `~/.pypirc`).
browseable-0.1.0/browseable/__init__.py ADDED
@@ -0,0 +1,5 @@
1
+ """browseable package."""
2
+
3
+ __all__ = ["__version__"]
4
+
5
+ __version__ = "0.1.0"
browseable-0.1.0/browseable/__main__.py ADDED
@@ -0,0 +1,5 @@
1
+ from browseable.cli import main
2
+
3
+
4
+ if __name__ == "__main__":
5
+ raise SystemExit(main())