brewsorted-cli 0.8.4__tar.gz → 0.8.5__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 (37) hide show
  1. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/INSTALL.md +55 -59
  2. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/PKG-INFO +56 -60
  3. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/brewsorted_cli.egg-info/PKG-INFO +56 -60
  4. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/pyproject.toml +1 -1
  5. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/src/brewsorted_cli/__init__.py +1 -1
  6. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/src/brewsorted_cli/oauth_login.py +4 -0
  7. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/tests/test_auth_state.py +7 -7
  8. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/tests/test_oauth_login.py +5 -2
  9. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/brewsorted_cli.egg-info/SOURCES.txt +0 -0
  10. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/brewsorted_cli.egg-info/dependency_links.txt +0 -0
  11. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/brewsorted_cli.egg-info/entry_points.txt +0 -0
  12. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/brewsorted_cli.egg-info/requires.txt +0 -0
  13. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/brewsorted_cli.egg-info/top_level.txt +0 -0
  14. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/setup.cfg +0 -0
  15. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/skills/brewsorted/SKILL.md +0 -0
  16. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/skills/brewsorted/__init__.py +0 -0
  17. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/skills/brewsorted/agents/openai.yaml +0 -0
  18. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/skills/brewsorted/references/cli.md +0 -0
  19. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/skills/brewsorted/tests/acceptance_scenarios.json +0 -0
  20. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/skills/brewsorted/tests/test_skill.py +0 -0
  21. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/src/brewsorted_cli/auth_state.py +0 -0
  22. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/src/brewsorted_cli/client.py +0 -0
  23. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/src/brewsorted_cli/http.py +0 -0
  24. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/src/brewsorted_cli/main.py +0 -0
  25. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/src/brewsorted_cli/oauth_discovery.py +0 -0
  26. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/src/brewsorted_cli/product_feedback.py +0 -0
  27. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/src/brewsorted_cli/skills.py +0 -0
  28. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/src/brewsorted_cli/updates.py +0 -0
  29. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/tests/test_anonymous_status.py +0 -0
  30. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/tests/test_cli.py +0 -0
  31. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/tests/test_oauth_discovery.py +0 -0
  32. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/tests/test_product_feedback.py +0 -0
  33. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/tests/test_protocol.py +0 -0
  34. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/tests/test_proxy.py +0 -0
  35. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/tests/test_ratio_workflow.py +0 -0
  36. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/tests/test_skills.py +0 -0
  37. {brewsorted_cli-0.8.4 → brewsorted_cli-0.8.5}/tests/test_updates.py +0 -0
@@ -1,23 +1,35 @@
1
- # BrewSorted client bundle
1
+ # BrewSorted CLI installation
2
2
 
3
- This archive contains the HTTP CLI and the canonical User skill. It is paired
4
- with its immutable service release by version, commit and archive SHA-256.
5
- Public downloads use `client-release.json` and the client-only `SHA256SUMS` at
6
- `https://downloads.brewsorted.com/index.json`; choose `production_recommended`,
7
- not the newest published version. The supported client target
8
- is Linux x86-64 with Python 3.12 or 3.13. Python 3.11 remains an internal
9
- compatibility target and is not publicly release-qualified.
3
+ The CLI and complete matching User skill are distributed together through
4
+ [PyPI](https://pypi.org/project/brewsorted-cli/). The public qualified target is
5
+ Linux x86-64 with Python 3.12 or 3.13; Python 3.11 remains internal compatibility
6
+ coverage. Source and coordinated service/client versions remain in the private
7
+ monorepo.
8
+
9
+ ## Select the production version
10
+
11
+ Read `https://brewsorted.com/api/capabilities` as JSON, require schema version 1,
12
+ and select its explicit `recommended_client_bundle_version` (`X.Y.Z`). Never
13
+ infer compatibility from PyPI's newest version. Before installing, inspect
14
+ `https://pypi.org/pypi/brewsorted-cli/X.Y.Z/json` for that exact version. Both
15
+ `brewsorted_cli-X.Y.Z-py3-none-any.whl` and `brewsorted_cli-X.Y.Z.tar.gz` must be
16
+ present with `yanked: false`. Missing, malformed, withdrawn or unavailable
17
+ metadata/files mean installation unavailable. Exact pins can still install
18
+ yanked files, so this check is required before invoking the installer.
19
+
20
+ Website archives and catalogs are retired. Historical service versions without
21
+ PyPI packages are not backfilled; recovery to one may have no fresh public CLI
22
+ installation path. Retained private immutable release assets are unchanged.
10
23
 
11
24
  ## PyPI installation
12
25
 
13
- For releases published to [PyPI](https://pypi.org/project/brewsorted-cli/), install
14
- that exact production-recommended version using uv (or pipx). Do not infer a
15
- recommendation from PyPI's latest version. If the exact registry release is not
16
- available yet, use its verified website archive below. The CLI and complete skill
17
- are packaged together; no private repository access is required.
26
+ The example below names this bundle's version. Use it only when it is the live
27
+ production recommendation and its exact PyPI release passes the checks above.
28
+ Install uv or pipx first if necessary; Python and ordinary package dependencies
29
+ are required. No private repository access is needed.
18
30
 
19
31
  ```bash
20
- client_version=0.8.4
32
+ client_version=0.8.5
21
33
  uv tool install --python python3.12 "brewsorted-cli==$client_version"
22
34
  # Alternative: pipx install --python python3.12 "brewsorted-cli==$client_version"
23
35
  brewsorted skills install --destination "$HOME/.codex/skills/brewsorted"
@@ -52,45 +64,30 @@ uv tool install --python python3.12 "verified/brewsorted_cli-$client_version-py3
52
64
 
53
65
  This verifies the CLI artifact's repository provenance, not every dependency or
54
66
  a security audit. Establish the expected repository identity independently of a
55
- disputed website. The public download catalog remains the compatibility authority.
67
+ disputed website. The production capability recommendation selects the version;
68
+ PyPI metadata establishes whether that exact release is available and not yanked.
56
69
 
57
- ## Archive installation
70
+ ## Private release archives
58
71
 
59
- After checking `SHA256SUMS`, retain the extracted immutable archive and install
60
- both the CLI and its exact User skill. These commands use the Codex skill
61
- directory; select the equivalent configured discovery directory for another
62
- supported agent:
72
+ Private immutable releases still retain their original client archives for
73
+ qualification and operator recovery evidence. They are not a public fallback.
74
+ An operator reinstall from an already verified private archive can use the
75
+ original `SHA256SUMS` before extracting it:
63
76
 
64
77
  ```bash
65
- client_version=0.8.4
66
- client_archive="brewsorted-client-${client_version}.tar.gz"
67
- client_release_root="$HOME/.local/share/brewsorted/releases"
68
- client_root="$client_release_root/brewsorted-client-${client_version}"
69
- agent_skill_root="$HOME/.codex/skills"
78
+ client_root="brewsorted-client-${client_version}"
70
79
  sha256sum --check SHA256SUMS || exit 1
71
- install -d -m 0700 "$client_release_root" "$agent_skill_root"
72
- test ! -e "$client_root" && test ! -L "$client_root"
73
- tar -xzf "$client_archive" -C "$client_release_root"
80
+ test ! -e "$client_root" && test ! -L "$client_root" || exit 1
81
+ tar -xzf "brewsorted-client-${client_version}.tar.gz"
74
82
  python3.13 -m venv "$client_root/.venv"
75
83
  "$client_root/.venv/bin/python" -m pip install "$client_root"
76
- test ! -e "$agent_skill_root/brewsorted" && test ! -L "$agent_skill_root/brewsorted"
77
- ln -s "$client_root/skills/brewsorted" "$agent_skill_root/brewsorted"
84
+ "$client_root/.venv/bin/brewsorted" skills install --destination "$HOME/.codex/skills/brewsorted"
78
85
  ```
79
86
 
80
- For an upgrade from CoffeeTrack, remove the old `coffeetrack` skill link and
81
- replace any shell or agent wrapper that invokes `coffeetrack` with the new
82
- `$client_root/.venv/bin/brewsorted` path. Move the non-secret service-origin
83
- setting from `COFFEETRACK_API_URL` to `BREWSORTED_API_URL`; use
84
- `https://brewsorted.com` for production or `https://staging.brewsorted.com`
85
- for synthetic staging. Use a separate credential file for each origin.
86
- Do not copy an old `~/.local/state/coffeetrack/auth.json` or other OAuth state
87
- into the BrewSorted state directory. The new realm has a different issuer and
88
- requires fresh User setup, browser sign-in, and Connection authorization.
89
-
90
- Do not copy only `SKILL.md`: the retained link keeps `references/cli.md` and the
91
- acceptance scenarios paired with the installed executable source. If the target
92
- link already exists, inspect and remove or rename it deliberately before linking
93
- the new archive; do not overwrite an unknown directory.
87
+ Follow the exact historical release's retained instructions when reconstructing
88
+ an old private environment. Do not rebuild or republish historical release bytes.
89
+
90
+ ## Authorize separately
94
91
 
95
92
  Create the OAuth state directory explicitly and keep it user-owned mode `0700`.
96
93
  The credential file becomes mode `0600` when login succeeds:
@@ -100,17 +97,15 @@ brewsorted_state_root="$HOME/.local/state/brewsorted"
100
97
  install -d -m 0700 "$brewsorted_state_root"
101
98
  export BREWSORTED_STATE_FILE="$brewsorted_state_root/auth.json"
102
99
  export BREWSORTED_API_URL=https://brewsorted.com
103
- unset COFFEETRACK_API_TOKEN COFFEETRACK_ACCESS_TOKEN COFFEETRACK_STATE_FILE
104
- "$client_root/.venv/bin/brewsorted" status
100
+ brewsorted status
105
101
  ```
106
102
 
107
- Remove legacy `COFFEETRACK_*` assignments from shell profiles, agent wrappers,
108
- and service configuration. `BREWSORTED_ACCESS_TOKEN` is only for an explicitly
109
- configured transient agent session; it does not transfer an old Connection.
103
+ Use a separate credential file for each exact service origin.
104
+ `BREWSORTED_ACCESS_TOKEN` is only for an explicitly configured transient agent session.
110
105
  Configure the exact HTTPS service origin outside chat as described in the skill.
111
106
 
112
107
  For a headless agent session, run
113
- `"$client_root/.venv/bin/brewsorted" login --device` and keep that process
108
+ `brewsorted login --device` and keep that process
114
109
  alive. Relay its exact verification URL and short code to the intended User, who
115
110
  authorizes it in their own browser. The agent never asks for SSH access, a
116
111
  password, access or refresh tokens, or a recovery link.
@@ -122,7 +117,7 @@ and keep it available for subsequent commands:
122
117
 
123
118
  ```bash
124
119
  export HTTPS_PROXY=http://proxy.example:8080
125
- "$client_root/.venv/bin/brewsorted" login --device
120
+ brewsorted login --device
126
121
  ```
127
122
 
128
123
  `HTTPS_PROXY` routes HTTPS service requests through the HTTP proxy; use
@@ -149,11 +144,12 @@ Treat each check as different evidence:
149
144
  complete returned Qualified ID, update and read it again, then delete that
150
145
  exact ID. This proves write/read-back separately from authentication.
151
146
 
152
- For recovery, deliberately select the production-recommended archive in the public
153
- catalog, check its identity and SHA-256 before extraction, and reinstall into its
154
- version-specific environment. An unavailable recommendation is a publication
155
- incident: do not infer compatibility from version order or use a withdrawn archive.
156
- The CLI's optional version hint is advisory, not an automatic updater. See
157
- `https://brewsorted.com/downloads.html` for download and update steps. HTTPS and
158
- matching hashes detect corruption but do not independently prove authenticity if
159
- the publication origin is compromised.
147
+ For updates, downgrades or reinstallations, re-read the production recommendation
148
+ and check the exact PyPI release again. Deliberately replace the executable with
149
+ `uv tool install --force --python python3.12 "brewsorted-cli==$client_version"`
150
+ (or the equivalent pipx command), inspect and move the old skill directory, then
151
+ install the complete matching skill again. Do not overwrite unknown paths or
152
+ use a withdrawn release. An unavailable recommendation is a publication incident,
153
+ not permission to infer compatibility. The CLI's optional version hint is
154
+ advisory and does not prove registry availability or update automatically.
155
+ See `https://brewsorted.com/downloads.html` for current installation guidance.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: brewsorted-cli
3
- Version: 0.8.4
3
+ Version: 0.8.5
4
4
  Summary: Portable HTTP client for the BrewSorted API
5
5
  Project-URL: Homepage, https://brewsorted.com
6
6
  Project-URL: Documentation, https://brewsorted.com/downloads.html
@@ -11,26 +11,38 @@ Requires-Dist: PyJWT[crypto]<3,>=2.14
11
11
  Provides-Extra: dev
12
12
  Requires-Dist: pytest<10,>=8; extra == "dev"
13
13
 
14
- # BrewSorted client bundle
14
+ # BrewSorted CLI installation
15
15
 
16
- This archive contains the HTTP CLI and the canonical User skill. It is paired
17
- with its immutable service release by version, commit and archive SHA-256.
18
- Public downloads use `client-release.json` and the client-only `SHA256SUMS` at
19
- `https://downloads.brewsorted.com/index.json`; choose `production_recommended`,
20
- not the newest published version. The supported client target
21
- is Linux x86-64 with Python 3.12 or 3.13. Python 3.11 remains an internal
22
- compatibility target and is not publicly release-qualified.
16
+ The CLI and complete matching User skill are distributed together through
17
+ [PyPI](https://pypi.org/project/brewsorted-cli/). The public qualified target is
18
+ Linux x86-64 with Python 3.12 or 3.13; Python 3.11 remains internal compatibility
19
+ coverage. Source and coordinated service/client versions remain in the private
20
+ monorepo.
21
+
22
+ ## Select the production version
23
+
24
+ Read `https://brewsorted.com/api/capabilities` as JSON, require schema version 1,
25
+ and select its explicit `recommended_client_bundle_version` (`X.Y.Z`). Never
26
+ infer compatibility from PyPI's newest version. Before installing, inspect
27
+ `https://pypi.org/pypi/brewsorted-cli/X.Y.Z/json` for that exact version. Both
28
+ `brewsorted_cli-X.Y.Z-py3-none-any.whl` and `brewsorted_cli-X.Y.Z.tar.gz` must be
29
+ present with `yanked: false`. Missing, malformed, withdrawn or unavailable
30
+ metadata/files mean installation unavailable. Exact pins can still install
31
+ yanked files, so this check is required before invoking the installer.
32
+
33
+ Website archives and catalogs are retired. Historical service versions without
34
+ PyPI packages are not backfilled; recovery to one may have no fresh public CLI
35
+ installation path. Retained private immutable release assets are unchanged.
23
36
 
24
37
  ## PyPI installation
25
38
 
26
- For releases published to [PyPI](https://pypi.org/project/brewsorted-cli/), install
27
- that exact production-recommended version using uv (or pipx). Do not infer a
28
- recommendation from PyPI's latest version. If the exact registry release is not
29
- available yet, use its verified website archive below. The CLI and complete skill
30
- are packaged together; no private repository access is required.
39
+ The example below names this bundle's version. Use it only when it is the live
40
+ production recommendation and its exact PyPI release passes the checks above.
41
+ Install uv or pipx first if necessary; Python and ordinary package dependencies
42
+ are required. No private repository access is needed.
31
43
 
32
44
  ```bash
33
- client_version=0.8.4
45
+ client_version=0.8.5
34
46
  uv tool install --python python3.12 "brewsorted-cli==$client_version"
35
47
  # Alternative: pipx install --python python3.12 "brewsorted-cli==$client_version"
36
48
  brewsorted skills install --destination "$HOME/.codex/skills/brewsorted"
@@ -65,45 +77,30 @@ uv tool install --python python3.12 "verified/brewsorted_cli-$client_version-py3
65
77
 
66
78
  This verifies the CLI artifact's repository provenance, not every dependency or
67
79
  a security audit. Establish the expected repository identity independently of a
68
- disputed website. The public download catalog remains the compatibility authority.
80
+ disputed website. The production capability recommendation selects the version;
81
+ PyPI metadata establishes whether that exact release is available and not yanked.
69
82
 
70
- ## Archive installation
83
+ ## Private release archives
71
84
 
72
- After checking `SHA256SUMS`, retain the extracted immutable archive and install
73
- both the CLI and its exact User skill. These commands use the Codex skill
74
- directory; select the equivalent configured discovery directory for another
75
- supported agent:
85
+ Private immutable releases still retain their original client archives for
86
+ qualification and operator recovery evidence. They are not a public fallback.
87
+ An operator reinstall from an already verified private archive can use the
88
+ original `SHA256SUMS` before extracting it:
76
89
 
77
90
  ```bash
78
- client_version=0.8.4
79
- client_archive="brewsorted-client-${client_version}.tar.gz"
80
- client_release_root="$HOME/.local/share/brewsorted/releases"
81
- client_root="$client_release_root/brewsorted-client-${client_version}"
82
- agent_skill_root="$HOME/.codex/skills"
91
+ client_root="brewsorted-client-${client_version}"
83
92
  sha256sum --check SHA256SUMS || exit 1
84
- install -d -m 0700 "$client_release_root" "$agent_skill_root"
85
- test ! -e "$client_root" && test ! -L "$client_root"
86
- tar -xzf "$client_archive" -C "$client_release_root"
93
+ test ! -e "$client_root" && test ! -L "$client_root" || exit 1
94
+ tar -xzf "brewsorted-client-${client_version}.tar.gz"
87
95
  python3.13 -m venv "$client_root/.venv"
88
96
  "$client_root/.venv/bin/python" -m pip install "$client_root"
89
- test ! -e "$agent_skill_root/brewsorted" && test ! -L "$agent_skill_root/brewsorted"
90
- ln -s "$client_root/skills/brewsorted" "$agent_skill_root/brewsorted"
97
+ "$client_root/.venv/bin/brewsorted" skills install --destination "$HOME/.codex/skills/brewsorted"
91
98
  ```
92
99
 
93
- For an upgrade from CoffeeTrack, remove the old `coffeetrack` skill link and
94
- replace any shell or agent wrapper that invokes `coffeetrack` with the new
95
- `$client_root/.venv/bin/brewsorted` path. Move the non-secret service-origin
96
- setting from `COFFEETRACK_API_URL` to `BREWSORTED_API_URL`; use
97
- `https://brewsorted.com` for production or `https://staging.brewsorted.com`
98
- for synthetic staging. Use a separate credential file for each origin.
99
- Do not copy an old `~/.local/state/coffeetrack/auth.json` or other OAuth state
100
- into the BrewSorted state directory. The new realm has a different issuer and
101
- requires fresh User setup, browser sign-in, and Connection authorization.
102
-
103
- Do not copy only `SKILL.md`: the retained link keeps `references/cli.md` and the
104
- acceptance scenarios paired with the installed executable source. If the target
105
- link already exists, inspect and remove or rename it deliberately before linking
106
- the new archive; do not overwrite an unknown directory.
100
+ Follow the exact historical release's retained instructions when reconstructing
101
+ an old private environment. Do not rebuild or republish historical release bytes.
102
+
103
+ ## Authorize separately
107
104
 
108
105
  Create the OAuth state directory explicitly and keep it user-owned mode `0700`.
109
106
  The credential file becomes mode `0600` when login succeeds:
@@ -113,17 +110,15 @@ brewsorted_state_root="$HOME/.local/state/brewsorted"
113
110
  install -d -m 0700 "$brewsorted_state_root"
114
111
  export BREWSORTED_STATE_FILE="$brewsorted_state_root/auth.json"
115
112
  export BREWSORTED_API_URL=https://brewsorted.com
116
- unset COFFEETRACK_API_TOKEN COFFEETRACK_ACCESS_TOKEN COFFEETRACK_STATE_FILE
117
- "$client_root/.venv/bin/brewsorted" status
113
+ brewsorted status
118
114
  ```
119
115
 
120
- Remove legacy `COFFEETRACK_*` assignments from shell profiles, agent wrappers,
121
- and service configuration. `BREWSORTED_ACCESS_TOKEN` is only for an explicitly
122
- configured transient agent session; it does not transfer an old Connection.
116
+ Use a separate credential file for each exact service origin.
117
+ `BREWSORTED_ACCESS_TOKEN` is only for an explicitly configured transient agent session.
123
118
  Configure the exact HTTPS service origin outside chat as described in the skill.
124
119
 
125
120
  For a headless agent session, run
126
- `"$client_root/.venv/bin/brewsorted" login --device` and keep that process
121
+ `brewsorted login --device` and keep that process
127
122
  alive. Relay its exact verification URL and short code to the intended User, who
128
123
  authorizes it in their own browser. The agent never asks for SSH access, a
129
124
  password, access or refresh tokens, or a recovery link.
@@ -135,7 +130,7 @@ and keep it available for subsequent commands:
135
130
 
136
131
  ```bash
137
132
  export HTTPS_PROXY=http://proxy.example:8080
138
- "$client_root/.venv/bin/brewsorted" login --device
133
+ brewsorted login --device
139
134
  ```
140
135
 
141
136
  `HTTPS_PROXY` routes HTTPS service requests through the HTTP proxy; use
@@ -162,11 +157,12 @@ Treat each check as different evidence:
162
157
  complete returned Qualified ID, update and read it again, then delete that
163
158
  exact ID. This proves write/read-back separately from authentication.
164
159
 
165
- For recovery, deliberately select the production-recommended archive in the public
166
- catalog, check its identity and SHA-256 before extraction, and reinstall into its
167
- version-specific environment. An unavailable recommendation is a publication
168
- incident: do not infer compatibility from version order or use a withdrawn archive.
169
- The CLI's optional version hint is advisory, not an automatic updater. See
170
- `https://brewsorted.com/downloads.html` for download and update steps. HTTPS and
171
- matching hashes detect corruption but do not independently prove authenticity if
172
- the publication origin is compromised.
160
+ For updates, downgrades or reinstallations, re-read the production recommendation
161
+ and check the exact PyPI release again. Deliberately replace the executable with
162
+ `uv tool install --force --python python3.12 "brewsorted-cli==$client_version"`
163
+ (or the equivalent pipx command), inspect and move the old skill directory, then
164
+ install the complete matching skill again. Do not overwrite unknown paths or
165
+ use a withdrawn release. An unavailable recommendation is a publication incident,
166
+ not permission to infer compatibility. The CLI's optional version hint is
167
+ advisory and does not prove registry availability or update automatically.
168
+ See `https://brewsorted.com/downloads.html` for current installation guidance.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: brewsorted-cli
3
- Version: 0.8.4
3
+ Version: 0.8.5
4
4
  Summary: Portable HTTP client for the BrewSorted API
5
5
  Project-URL: Homepage, https://brewsorted.com
6
6
  Project-URL: Documentation, https://brewsorted.com/downloads.html
@@ -11,26 +11,38 @@ Requires-Dist: PyJWT[crypto]<3,>=2.14
11
11
  Provides-Extra: dev
12
12
  Requires-Dist: pytest<10,>=8; extra == "dev"
13
13
 
14
- # BrewSorted client bundle
14
+ # BrewSorted CLI installation
15
15
 
16
- This archive contains the HTTP CLI and the canonical User skill. It is paired
17
- with its immutable service release by version, commit and archive SHA-256.
18
- Public downloads use `client-release.json` and the client-only `SHA256SUMS` at
19
- `https://downloads.brewsorted.com/index.json`; choose `production_recommended`,
20
- not the newest published version. The supported client target
21
- is Linux x86-64 with Python 3.12 or 3.13. Python 3.11 remains an internal
22
- compatibility target and is not publicly release-qualified.
16
+ The CLI and complete matching User skill are distributed together through
17
+ [PyPI](https://pypi.org/project/brewsorted-cli/). The public qualified target is
18
+ Linux x86-64 with Python 3.12 or 3.13; Python 3.11 remains internal compatibility
19
+ coverage. Source and coordinated service/client versions remain in the private
20
+ monorepo.
21
+
22
+ ## Select the production version
23
+
24
+ Read `https://brewsorted.com/api/capabilities` as JSON, require schema version 1,
25
+ and select its explicit `recommended_client_bundle_version` (`X.Y.Z`). Never
26
+ infer compatibility from PyPI's newest version. Before installing, inspect
27
+ `https://pypi.org/pypi/brewsorted-cli/X.Y.Z/json` for that exact version. Both
28
+ `brewsorted_cli-X.Y.Z-py3-none-any.whl` and `brewsorted_cli-X.Y.Z.tar.gz` must be
29
+ present with `yanked: false`. Missing, malformed, withdrawn or unavailable
30
+ metadata/files mean installation unavailable. Exact pins can still install
31
+ yanked files, so this check is required before invoking the installer.
32
+
33
+ Website archives and catalogs are retired. Historical service versions without
34
+ PyPI packages are not backfilled; recovery to one may have no fresh public CLI
35
+ installation path. Retained private immutable release assets are unchanged.
23
36
 
24
37
  ## PyPI installation
25
38
 
26
- For releases published to [PyPI](https://pypi.org/project/brewsorted-cli/), install
27
- that exact production-recommended version using uv (or pipx). Do not infer a
28
- recommendation from PyPI's latest version. If the exact registry release is not
29
- available yet, use its verified website archive below. The CLI and complete skill
30
- are packaged together; no private repository access is required.
39
+ The example below names this bundle's version. Use it only when it is the live
40
+ production recommendation and its exact PyPI release passes the checks above.
41
+ Install uv or pipx first if necessary; Python and ordinary package dependencies
42
+ are required. No private repository access is needed.
31
43
 
32
44
  ```bash
33
- client_version=0.8.4
45
+ client_version=0.8.5
34
46
  uv tool install --python python3.12 "brewsorted-cli==$client_version"
35
47
  # Alternative: pipx install --python python3.12 "brewsorted-cli==$client_version"
36
48
  brewsorted skills install --destination "$HOME/.codex/skills/brewsorted"
@@ -65,45 +77,30 @@ uv tool install --python python3.12 "verified/brewsorted_cli-$client_version-py3
65
77
 
66
78
  This verifies the CLI artifact's repository provenance, not every dependency or
67
79
  a security audit. Establish the expected repository identity independently of a
68
- disputed website. The public download catalog remains the compatibility authority.
80
+ disputed website. The production capability recommendation selects the version;
81
+ PyPI metadata establishes whether that exact release is available and not yanked.
69
82
 
70
- ## Archive installation
83
+ ## Private release archives
71
84
 
72
- After checking `SHA256SUMS`, retain the extracted immutable archive and install
73
- both the CLI and its exact User skill. These commands use the Codex skill
74
- directory; select the equivalent configured discovery directory for another
75
- supported agent:
85
+ Private immutable releases still retain their original client archives for
86
+ qualification and operator recovery evidence. They are not a public fallback.
87
+ An operator reinstall from an already verified private archive can use the
88
+ original `SHA256SUMS` before extracting it:
76
89
 
77
90
  ```bash
78
- client_version=0.8.4
79
- client_archive="brewsorted-client-${client_version}.tar.gz"
80
- client_release_root="$HOME/.local/share/brewsorted/releases"
81
- client_root="$client_release_root/brewsorted-client-${client_version}"
82
- agent_skill_root="$HOME/.codex/skills"
91
+ client_root="brewsorted-client-${client_version}"
83
92
  sha256sum --check SHA256SUMS || exit 1
84
- install -d -m 0700 "$client_release_root" "$agent_skill_root"
85
- test ! -e "$client_root" && test ! -L "$client_root"
86
- tar -xzf "$client_archive" -C "$client_release_root"
93
+ test ! -e "$client_root" && test ! -L "$client_root" || exit 1
94
+ tar -xzf "brewsorted-client-${client_version}.tar.gz"
87
95
  python3.13 -m venv "$client_root/.venv"
88
96
  "$client_root/.venv/bin/python" -m pip install "$client_root"
89
- test ! -e "$agent_skill_root/brewsorted" && test ! -L "$agent_skill_root/brewsorted"
90
- ln -s "$client_root/skills/brewsorted" "$agent_skill_root/brewsorted"
97
+ "$client_root/.venv/bin/brewsorted" skills install --destination "$HOME/.codex/skills/brewsorted"
91
98
  ```
92
99
 
93
- For an upgrade from CoffeeTrack, remove the old `coffeetrack` skill link and
94
- replace any shell or agent wrapper that invokes `coffeetrack` with the new
95
- `$client_root/.venv/bin/brewsorted` path. Move the non-secret service-origin
96
- setting from `COFFEETRACK_API_URL` to `BREWSORTED_API_URL`; use
97
- `https://brewsorted.com` for production or `https://staging.brewsorted.com`
98
- for synthetic staging. Use a separate credential file for each origin.
99
- Do not copy an old `~/.local/state/coffeetrack/auth.json` or other OAuth state
100
- into the BrewSorted state directory. The new realm has a different issuer and
101
- requires fresh User setup, browser sign-in, and Connection authorization.
102
-
103
- Do not copy only `SKILL.md`: the retained link keeps `references/cli.md` and the
104
- acceptance scenarios paired with the installed executable source. If the target
105
- link already exists, inspect and remove or rename it deliberately before linking
106
- the new archive; do not overwrite an unknown directory.
100
+ Follow the exact historical release's retained instructions when reconstructing
101
+ an old private environment. Do not rebuild or republish historical release bytes.
102
+
103
+ ## Authorize separately
107
104
 
108
105
  Create the OAuth state directory explicitly and keep it user-owned mode `0700`.
109
106
  The credential file becomes mode `0600` when login succeeds:
@@ -113,17 +110,15 @@ brewsorted_state_root="$HOME/.local/state/brewsorted"
113
110
  install -d -m 0700 "$brewsorted_state_root"
114
111
  export BREWSORTED_STATE_FILE="$brewsorted_state_root/auth.json"
115
112
  export BREWSORTED_API_URL=https://brewsorted.com
116
- unset COFFEETRACK_API_TOKEN COFFEETRACK_ACCESS_TOKEN COFFEETRACK_STATE_FILE
117
- "$client_root/.venv/bin/brewsorted" status
113
+ brewsorted status
118
114
  ```
119
115
 
120
- Remove legacy `COFFEETRACK_*` assignments from shell profiles, agent wrappers,
121
- and service configuration. `BREWSORTED_ACCESS_TOKEN` is only for an explicitly
122
- configured transient agent session; it does not transfer an old Connection.
116
+ Use a separate credential file for each exact service origin.
117
+ `BREWSORTED_ACCESS_TOKEN` is only for an explicitly configured transient agent session.
123
118
  Configure the exact HTTPS service origin outside chat as described in the skill.
124
119
 
125
120
  For a headless agent session, run
126
- `"$client_root/.venv/bin/brewsorted" login --device` and keep that process
121
+ `brewsorted login --device` and keep that process
127
122
  alive. Relay its exact verification URL and short code to the intended User, who
128
123
  authorizes it in their own browser. The agent never asks for SSH access, a
129
124
  password, access or refresh tokens, or a recovery link.
@@ -135,7 +130,7 @@ and keep it available for subsequent commands:
135
130
 
136
131
  ```bash
137
132
  export HTTPS_PROXY=http://proxy.example:8080
138
- "$client_root/.venv/bin/brewsorted" login --device
133
+ brewsorted login --device
139
134
  ```
140
135
 
141
136
  `HTTPS_PROXY` routes HTTPS service requests through the HTTP proxy; use
@@ -162,11 +157,12 @@ Treat each check as different evidence:
162
157
  complete returned Qualified ID, update and read it again, then delete that
163
158
  exact ID. This proves write/read-back separately from authentication.
164
159
 
165
- For recovery, deliberately select the production-recommended archive in the public
166
- catalog, check its identity and SHA-256 before extraction, and reinstall into its
167
- version-specific environment. An unavailable recommendation is a publication
168
- incident: do not infer compatibility from version order or use a withdrawn archive.
169
- The CLI's optional version hint is advisory, not an automatic updater. See
170
- `https://brewsorted.com/downloads.html` for download and update steps. HTTPS and
171
- matching hashes detect corruption but do not independently prove authenticity if
172
- the publication origin is compromised.
160
+ For updates, downgrades or reinstallations, re-read the production recommendation
161
+ and check the exact PyPI release again. Deliberately replace the executable with
162
+ `uv tool install --force --python python3.12 "brewsorted-cli==$client_version"`
163
+ (or the equivalent pipx command), inspect and move the old skill directory, then
164
+ install the complete matching skill again. Do not overwrite unknown paths or
165
+ use a withdrawn release. An unavailable recommendation is a publication incident,
166
+ not permission to infer compatibility. The CLI's optional version hint is
167
+ advisory and does not prove registry availability or update automatically.
168
+ See `https://brewsorted.com/downloads.html` for current installation guidance.
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "brewsorted-cli"
7
- version = "0.8.4"
7
+ version = "0.8.5"
8
8
  description = "Portable HTTP client for the BrewSorted API"
9
9
  readme = "INSTALL.md"
10
10
  requires-python = ">=3.11"
@@ -1,5 +1,5 @@
1
1
  """HTTP-only BrewSorted command-line client."""
2
2
 
3
- __version__ = "0.8.4"
3
+ __version__ = "0.8.5"
4
4
 
5
5
  USER_AGENT = f"BrewSorted-CLI/{__version__}"
@@ -183,6 +183,10 @@ class OAuthLogin:
183
183
  self.progress(f"Visit {complete_url} and confirm code {code}")
184
184
  else:
185
185
  self.progress(f"Visit {verification_url} and enter code {code}")
186
+ self.progress(
187
+ f"On another device, open {verification_url} and enter code {code}. "
188
+ "Use the original verification link, not a URL copied after opening it."
189
+ )
186
190
  deadline = time.monotonic() + lifetime
187
191
  while time.monotonic() < deadline:
188
192
  time.sleep(interval)
@@ -60,15 +60,15 @@ def test_state_file_modes_ownership_and_binding_are_checked(tmp_path):
60
60
  selected.read()
61
61
 
62
62
 
63
- def test_old_coffeetrack_connection_cannot_be_loaded_into_brewsorted_state():
64
- old_issuer = f"{ORIGIN}/id/realms/coffeetrack"
63
+ def test_connection_from_another_realm_cannot_be_loaded_into_brewsorted_state():
64
+ other_issuer = f"{ORIGIN}/id/realms/other-service"
65
65
  with pytest.raises(AuthStateError, match="issuer does not match"):
66
66
  AuthBinding(
67
- format_version=1, service_origin=ORIGIN, issuer=old_issuer,
68
- subject="immutable-subject", username="person", audience="coffeetrack-api",
69
- client_id="coffeetrack-cli",
70
- token_endpoint=f"{old_issuer}/protocol/openid-connect/token",
71
- revocation_endpoint=f"{old_issuer}/protocol/openid-connect/revoke",
67
+ format_version=1, service_origin=ORIGIN, issuer=other_issuer,
68
+ subject="immutable-subject", username="person", audience="other-service-api",
69
+ client_id="other-service-cli",
70
+ token_endpoint=f"{other_issuer}/protocol/openid-connect/token",
71
+ revocation_endpoint=f"{other_issuer}/protocol/openid-connect/revoke",
72
72
  access_token="old-access", refresh_token="old-refresh", expires_at=1,
73
73
  )
74
74
 
@@ -104,8 +104,11 @@ def test_device_login_requires_api_user_verification_before_saving(tmp_path, mon
104
104
  assert result == {"service_origin": ORIGIN, "username": "person", "connected": "yes"}
105
105
  assert state.read().subject == "subject-one"
106
106
  assert state.read().refresh_token == "rotating-secret"
107
- assert len(progress) == 1 and "ABCD-EFGH" in progress[0]
108
- assert "private-device-code" not in progress[0]
107
+ assert len(progress) == 2 and "ABCD-EFGH" in progress[0]
108
+ assert all("private-device-code" not in message for message in progress)
109
+ assert f"{ISSUER}/device" in progress[1]
110
+ assert "enter code ABCD-EFGH" in progress[1]
111
+ assert "URL copied after opening" in progress[1]
109
112
  if complete:
110
113
  assert f"{ISSUER}/device?user_code=ABCD-EFGH" in progress[0]
111
114
  assert calls[-1] == ("GET", f"{ORIGIN}/api/v1/auth/me")
File without changes