codex-workspaces 0.3.0__tar.gz → 0.3.2__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 (36) hide show
  1. codex_workspaces-0.3.2/CHANGELOG.md +97 -0
  2. {codex_workspaces-0.3.0/src/codex_workspaces.egg-info → codex_workspaces-0.3.2}/PKG-INFO +84 -3
  3. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/README.MD +83 -2
  4. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/README.zh-CN.md +83 -2
  5. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/docs/DESIGN.zh-CN.md +27 -4
  6. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/docs/RELEASE.zh-CN.md +2 -2
  7. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/docs/TESTING.zh-CN.md +55 -3
  8. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/pyproject.toml +1 -1
  9. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/src/codex_workspaces/__init__.py +1 -1
  10. codex_workspaces-0.3.2/src/codex_workspaces/auth_inspector.py +125 -0
  11. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/src/codex_workspaces/cli.py +183 -9
  12. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/src/codex_workspaces/config.py +11 -0
  13. codex_workspaces-0.3.2/src/codex_workspaces/core.py +2958 -0
  14. codex_workspaces-0.3.2/src/codex_workspaces/private_api/__init__.py +10 -0
  15. codex_workspaces-0.3.2/src/codex_workspaces/private_api/auth.py +45 -0
  16. codex_workspaces-0.3.2/src/codex_workspaces/private_api/client.py +150 -0
  17. codex_workspaces-0.3.2/src/codex_workspaces/private_api/errors.py +52 -0
  18. codex_workspaces-0.3.2/src/codex_workspaces/private_api/models.py +95 -0
  19. codex_workspaces-0.3.2/src/codex_workspaces/stats.py +311 -0
  20. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/src/codex_workspaces/store.py +53 -2
  21. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2/src/codex_workspaces.egg-info}/PKG-INFO +84 -3
  22. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/src/codex_workspaces.egg-info/SOURCES.txt +6 -0
  23. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/tests/test_cli.py +66 -6
  24. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/tests/test_core.py +559 -6
  25. codex_workspaces-0.3.0/CHANGELOG.md +0 -46
  26. codex_workspaces-0.3.0/src/codex_workspaces/core.py +0 -1560
  27. codex_workspaces-0.3.0/src/codex_workspaces/stats.py +0 -170
  28. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/MANIFEST.in +0 -0
  29. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/setup.cfg +0 -0
  30. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/src/codex_workspaces/__main__.py +0 -0
  31. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/src/codex_workspaces/errors.py +0 -0
  32. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/src/codex_workspaces/platforms.py +0 -0
  33. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/src/codex_workspaces.egg-info/dependency_links.txt +0 -0
  34. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/src/codex_workspaces.egg-info/entry_points.txt +0 -0
  35. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/src/codex_workspaces.egg-info/requires.txt +0 -0
  36. {codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/src/codex_workspaces.egg-info/top_level.txt +0 -0
codex_workspaces-0.3.2/CHANGELOG.md ADDED
@@ -0,0 +1,97 @@
1
+ # Changelog
2
+
3
+ All notable changes to `codex-workspaces` will be documented in this file.
4
+
5
+ This project follows a simple changelog format while it is still pre-release.
6
+
7
+ ## 0.3.2 - 2026-07-04
8
+
9
+ ### Added
10
+
11
+ - Added best-effort local `auth.json` metadata inspection for account email, account ID, user ID, organization ID, plan, and auth hash without private API calls.
12
+ - Added `accounts refresh-meta <account>|--all [--overwrite]` for manually refreshing parsed account metadata.
13
+ - Added `accounts export` and `accounts import` backup support with meta-only exports by default, explicit `--include-auth` credential export, dry-run import plans, conflict renaming, overwrite with pre-import backup, auth hash validation, and unsafe tar path rejection.
14
+ - Added enhanced local `stats` views for summary, daily usage, top models, workspace aggregation, account aggregation, JSON output, and Markdown output.
15
+ - Added experimental private API provider scaffolding for realtime account quota lookup.
16
+ - Added `quota` for the current active account and `accounts quota <account>` for a specific managed account.
17
+ - Added `accounts list -a` / `accounts list --all-with-quota` for realtime quota display across managed accounts.
18
+ - Added `accounts refresh [account|--all]` for refreshing remote account metadata and quota cache without modifying `auth.json`.
19
+ - Added `config get/set experimental_private_api.*` for explicitly enabling and configuring experimental private API behavior.
20
+ - Added quota cache with TTL and auth-hash invalidation under `~/.codex-workspaces/cache/quota/`.
21
+
22
+ ### Changed
23
+
24
+ - Improved account list/info metadata enrichment while keeping auth parsing optional and non-blocking.
25
+ - Improved local stats presentation while keeping all statistics local and read-only.
26
+ - Updated README, design, testing, release, and changelog docs for the 0.3.2 workflow.
27
+
28
+ ### Security
29
+
30
+ - Added explicit warnings for exports that include `auth.json` credentials.
31
+ - Added backup archive validation against path traversal, symlinks, device files, and auth hash mismatches during import.
32
+ - Kept auth inspection local-only: no token refresh, no private API calls, no network requests, and no sensitive token-like fields in normal output.
33
+ - Private API quota/refresh features are disabled by default and must be explicitly enabled.
34
+ - Sensitive auth material is redacted from private API errors, command output, and quota cache.
35
+ - Quota cache stores no tokens, cookies, authorization headers, or raw `auth.json`.
36
+
37
+ ### Notes
38
+
39
+ - Realtime quota and refresh depend on experimental private Codex/OpenAI interfaces and may break when upstream behavior changes.
40
+ - `stats` remains local historical usage; `quota` is realtime remote lookup and is intentionally separate.
41
+
42
+ ## 0.3.1 - 2026-07-04
43
+
44
+ ### Added
45
+
46
+ - Added `accounts add <account> --login` and `accounts login-temp <account>` to create an isolated temporary login workspace, save the new auth snapshot, and restore the previous workspace.
47
+ - Added `accounts cleanup-login-temp` for stale temporary login workspaces.
48
+ - Added enhanced `accounts list` and `accounts info` output with auth status, current/default markers, workspace references, orphan/active-only status, notes, paths, and auth hashes.
49
+ - Added account-focused `doctor` checks for missing account references, workspace auth without defaults, orphan accounts, permission issues, and legacy directory leftovers.
50
+ - Added final migration report summaries for migrated workspaces, created accounts, imported accounts, renamed account conflicts, and skipped special files.
51
+ - Added `codex-workspaces info <workspace>` for workspace metadata inspection.
52
+ - Added `CODEX_WORKSPACES_RESTORE_POLICY` with `workspace-default`, `last-active`, and `keep-current`.
53
+
54
+ ### Changed
55
+
56
+ - Updated README, design, testing, and release docs for the 0.3.1 account and restore-policy workflow.
57
+
58
+ ## 0.3.0 - 2026-07-04
59
+
60
+ ### Added
61
+
62
+ - Added the cross-platform Python 3 package with the `codex-workspaces` console script.
63
+ - Added Linux/macOS symlink switching and Windows symlink/junction support.
64
+ - Added Python unit tests for workspace validation, creation, migration, switching, CLI dispatch, and platform safety behavior.
65
+ - Added `doctor` diagnostics for platform, path, link, and Codex terminal status.
66
+ - Added workspace size and modified-time metadata to `list`.
67
+ - Added workspace `rename`, guarded `delete --force`, and local `note` management.
68
+ - Added read-only local SQLite token usage stats with `stats`.
69
+ - Added the unified `~/.codex-workspaces/` root with workspace metadata, account snapshots, and default-account restore behavior.
70
+ - Added legacy workspace migration with `migrate`, `migrate --dry-run`, and `init <workspace> --migrate-current`.
71
+ - Added legacy account import with `accounts import-legacy` and workspace auth import with `accounts import-workspaces`.
72
+ - Added account `rename`, guarded `delete --force`, and account `note` management.
73
+ - Added `pyproject.toml`, package metadata, editable install support, and PyPI-ready build configuration.
74
+ - Added GitHub Actions CI for Linux, macOS, Windows, and Python 3.9/3.11/3.13.
75
+ - Added GitHub Actions Trusted Publishing workflow for PyPI releases.
76
+ - Added design, testing, and release documentation under `docs/`.
77
+ - Added the `codex-workspaces` macOS shell script for managing multiple Codex workspace directories.
78
+ - Added workspace listing with active workspace detection.
79
+ - Added current workspace inspection.
80
+ - Added workspace switching through the active `~/.codex` symlink.
81
+ - Added Codex app stop, start, and restart commands.
82
+ - Added workspace initialization with `codex-workspaces init <workspace>`.
83
+ - Added self-install support with `codex-workspaces install [directory]`.
84
+ - Added English and Chinese command output, controlled by system language or `CODEX_WORKSPACES_LANG`.
85
+ - Renamed the command, package, module, docs, and environment variables to `codex-workspaces` / `CODEX_WORKSPACES_*`.
86
+ - Added English and Simplified Chinese README files.
87
+
88
+ ### Safety
89
+
90
+ - Refuses to switch workspaces when `~/.codex` exists but is not a symlink.
91
+ - Delegates stop, switch, and restart commands to Terminal.app when they are run from a detected Codex terminal environment.
92
+ - Refuses start and migration commands when they are run from a detected Codex terminal environment.
93
+ - Backs up legacy workspace/account sources before migration and never deletes old directories automatically.
94
+ - Keeps migration non-interactive; new account login is handled separately through the login-temp workflow.
95
+ - Saves live `auth.json` before account or workspace switches when an active account is configured.
96
+ - Uses a lock file under `~/.codex-workspaces/lock` for account and workspace switching.
97
+ - Limits workspace names to letters, numbers, dots, underscores, and hyphens.
{codex_workspaces-0.3.0/src/codex_workspaces.egg-info → codex_workspaces-0.3.2}/PKG-INFO RENAMED
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: codex-workspaces
3
- Version: 0.3.0
3
+ Version: 0.3.2
4
4
  Summary: Cross-platform Codex workspace switcher with a preserved macOS shell workflow.
5
5
  Author: blockchain-project-lives
6
6
  Project-URL: Homepage, https://github.com/blockchain-project-lives/codex-workspaces
@@ -45,10 +45,14 @@ On macOS, the Python CLI preserves the original app workflow: stop Codex App, sw
45
45
  - Manage account snapshots under `~/.codex-workspaces/accounts/`.
46
46
  - Switch the active `~/.codex` symlink or directory link.
47
47
  - Initialize workspace directories with metadata.
48
+ - Add a new account through an isolated temporary login workspace with `accounts add --login`.
48
49
  - Temporarily switch the current workspace account with `accounts use`, then restore the workspace default account.
50
+ - Best-effort parse local `auth.json` metadata such as email/account identifiers without network calls.
51
+ - Export and import account snapshot backups with explicit warnings for credential-bearing archives.
52
+ - Inspect workspace/account metadata and run account-focused `doctor` diagnostics.
49
53
  - Migrate older `~/.codex-<name>` workspaces and import legacy `~/.codex-accounts` auth snapshots.
50
54
  - Keep macOS Codex App stop/start/restart support.
51
- - Show local token usage stats from Codex `state_*.sqlite` in read-only mode.
55
+ - Show local token usage stats from Codex `state_*.sqlite` in read-only mode, including daily, model, workspace, account, JSON, and Markdown views.
52
56
  - Block unsafe operations from a detected Codex built-in terminal when they cannot be delegated safely.
53
57
  - Support English and Chinese output through `CODEX_WORKSPACES_LANG`.
54
58
  - Package as a Python project with tests, CI, and PyPI publishing workflow.
@@ -149,6 +153,27 @@ codex-workspaces accounts init research
149
153
  codex-workspaces accounts save research
150
154
  ```
151
155
 
156
+ To add a new account without logging out of the current workspace account, use a temporary login workspace:
157
+
158
+ ```bash
159
+ codex-workspaces accounts add research --login
160
+ ```
161
+
162
+ This switches `~/.codex` to a temporary `login-<account>` workspace, lets you log in, saves the generated `auth.json` as `acct_<account>`, and restores the previous workspace. If login is interrupted, clean stale temporary workspaces with `codex-workspaces accounts cleanup-login-temp`.
163
+
164
+ Account metadata such as `email`, `account_id`, `user_id`, `organization_id`, and `plan` is parsed from local `auth.json` on a best-effort basis. Parsing failures are ignored, sensitive token-like fields are never printed, and no private API or network request is used.
165
+
166
+ Export or import account backups:
167
+
168
+ ```bash
169
+ codex-workspaces accounts export accounts.tar.gz --all
170
+ codex-workspaces accounts export accounts-with-auth.tar.gz --all --include-auth --yes
171
+ codex-workspaces accounts import accounts-with-auth.tar.gz --dry-run
172
+ codex-workspaces accounts import accounts-with-auth.tar.gz --rename-conflicts
173
+ ```
174
+
175
+ Backups created with `--include-auth` contain Codex credentials from `auth.json`. Store them securely and never commit them to git. Without `--include-auth`, export writes metadata only.
176
+
152
177
  Import legacy `codex-accounts` AUTH-mode snapshots:
153
178
 
154
179
  ```bash
@@ -174,11 +199,65 @@ Inspect workspaces:
174
199
  ```bash
175
200
  codex-workspaces list
176
201
  codex-workspaces current
202
+ codex-workspaces info work
177
203
  codex-workspaces doctor
178
204
  codex-workspaces stats
205
+ codex-workspaces stats summary --days 30
206
+ codex-workspaces stats daily --format markdown
207
+ codex-workspaces stats models --format json
208
+ codex-workspaces stats workspaces
209
+ codex-workspaces stats accounts
179
210
  codex-workspaces stats work --days 14
180
211
  ```
181
212
 
213
+ `stats` only reads local SQLite state. Missing or unrecognized workspace/account/model data is shown as `unknown`; results are best-effort and depend on the local Codex files available in each workspace.
214
+
215
+ ## Experimental Realtime Quota
216
+
217
+ `codex-workspaces` can optionally query realtime quota for managed accounts through an experimental private API provider.
218
+
219
+ This feature is disabled by default. It may break when upstream Codex/OpenAI internals change, may return `401`/`403`/`429`, and is not required for workspace or account switching.
220
+
221
+ Enable explicitly:
222
+
223
+ ```bash
224
+ codex-workspaces config set experimental_private_api.enabled true
225
+ codex-workspaces config set experimental_private_api.quota_enabled true
226
+ codex-workspaces config set experimental_private_api.refresh_enabled true
227
+ ```
228
+
229
+ Query current account quota:
230
+
231
+ ```bash
232
+ codex-workspaces quota
233
+ codex-workspaces quota --json
234
+ ```
235
+
236
+ Query a specific managed account:
237
+
238
+ ```bash
239
+ codex-workspaces accounts quota acct_work
240
+ ```
241
+
242
+ Query all accounts with quota:
243
+
244
+ ```bash
245
+ codex-workspaces accounts list -a
246
+ codex-workspaces accounts list --all-with-quota --json
247
+ ```
248
+
249
+ Refresh remote account metadata and quota cache:
250
+
251
+ ```bash
252
+ codex-workspaces accounts refresh
253
+ codex-workspaces accounts refresh acct_work
254
+ codex-workspaces accounts refresh --all --json
255
+ ```
256
+
257
+ Realtime quota uses explicit experimental configuration, timeout, serial account iteration, and a local TTL cache under `~/.codex-workspaces/cache/quota/`. The cache stores quota summaries and auth hashes only; it does not store tokens, cookies, authorization headers, or raw `auth.json`.
258
+
259
+ `stats` and `quota` are different: `stats` is local historical usage from SQLite, while `quota` is a realtime remote lookup. Quota failures do not affect local workspace/account switching.
260
+
182
261
  Switch accounts within the current workspace:
183
262
 
184
263
  ```bash
@@ -186,7 +265,7 @@ codex-workspaces accounts use acct_personal
186
265
  codex-workspaces accounts restore-default
187
266
  ```
188
267
 
189
- `accounts use` only changes the current workspace `active_account_id`; it does not change `default_account_id`. Entering a workspace with `codex-workspaces use <workspace>` restores that workspace's default account when one is configured.
268
+ `accounts use` only changes the current workspace `active_account_id`; it does not change `default_account_id`. Entering a workspace uses `CODEX_WORKSPACES_RESTORE_POLICY`: `workspace-default` restores the workspace default account, `last-active` restores that workspace's last active account, and `keep-current` keeps the account you were just using when possible.
190
269
 
191
270
  `auth.json` contains credentials. Do not commit workspace directories, account snapshots, SQLite state, sessions, or shell snapshots to git; the project `.gitignore` excludes these patterns for local checkouts.
192
271
 
@@ -194,6 +273,7 @@ Manage account metadata and snapshots:
194
273
 
195
274
  ```bash
196
275
  codex-workspaces accounts note acct_research "lab account"
276
+ codex-workspaces accounts info acct_research
197
277
  codex-workspaces accounts rename acct_research acct_lab
198
278
  codex-workspaces accounts delete acct_lab --force
199
279
  ```
@@ -226,6 +306,7 @@ codex-workspaces restart
226
306
  | `CODEX_QUIT_TIMEOUT` | `20` | Seconds to wait for app exit. |
227
307
  | `CODEX_WORKSPACES_LINK` | `$HOME/.codex` | Active workspace link path. |
228
308
  | `CODEX_WORKSPACES_ROOT` | `$HOME/.codex-workspaces` | Managed root for workspaces, accounts, backups, and lock file. |
309
+ | `CODEX_WORKSPACES_RESTORE_POLICY` | `workspace-default` | Account restore policy when entering a workspace: `workspace-default`, `last-active`, or `keep-current`. |
229
310
  | `CODEX_WORKSPACES_LANG` | auto | Force output language with `en` or `zh`. |
230
311
 
231
312
  Only the `CODEX_WORKSPACES_*` variables are used for workspace-specific configuration.
{codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/README.MD RENAMED
@@ -17,10 +17,14 @@ On macOS, the Python CLI preserves the original app workflow: stop Codex App, sw
17
17
  - Manage account snapshots under `~/.codex-workspaces/accounts/`.
18
18
  - Switch the active `~/.codex` symlink or directory link.
19
19
  - Initialize workspace directories with metadata.
20
+ - Add a new account through an isolated temporary login workspace with `accounts add --login`.
20
21
  - Temporarily switch the current workspace account with `accounts use`, then restore the workspace default account.
22
+ - Best-effort parse local `auth.json` metadata such as email/account identifiers without network calls.
23
+ - Export and import account snapshot backups with explicit warnings for credential-bearing archives.
24
+ - Inspect workspace/account metadata and run account-focused `doctor` diagnostics.
21
25
  - Migrate older `~/.codex-<name>` workspaces and import legacy `~/.codex-accounts` auth snapshots.
22
26
  - Keep macOS Codex App stop/start/restart support.
23
- - Show local token usage stats from Codex `state_*.sqlite` in read-only mode.
27
+ - Show local token usage stats from Codex `state_*.sqlite` in read-only mode, including daily, model, workspace, account, JSON, and Markdown views.
24
28
  - Block unsafe operations from a detected Codex built-in terminal when they cannot be delegated safely.
25
29
  - Support English and Chinese output through `CODEX_WORKSPACES_LANG`.
26
30
  - Package as a Python project with tests, CI, and PyPI publishing workflow.
@@ -121,6 +125,27 @@ codex-workspaces accounts init research
121
125
  codex-workspaces accounts save research
122
126
  ```
123
127
 
128
+ To add a new account without logging out of the current workspace account, use a temporary login workspace:
129
+
130
+ ```bash
131
+ codex-workspaces accounts add research --login
132
+ ```
133
+
134
+ This switches `~/.codex` to a temporary `login-<account>` workspace, lets you log in, saves the generated `auth.json` as `acct_<account>`, and restores the previous workspace. If login is interrupted, clean stale temporary workspaces with `codex-workspaces accounts cleanup-login-temp`.
135
+
136
+ Account metadata such as `email`, `account_id`, `user_id`, `organization_id`, and `plan` is parsed from local `auth.json` on a best-effort basis. Parsing failures are ignored, sensitive token-like fields are never printed, and no private API or network request is used.
137
+
138
+ Export or import account backups:
139
+
140
+ ```bash
141
+ codex-workspaces accounts export accounts.tar.gz --all
142
+ codex-workspaces accounts export accounts-with-auth.tar.gz --all --include-auth --yes
143
+ codex-workspaces accounts import accounts-with-auth.tar.gz --dry-run
144
+ codex-workspaces accounts import accounts-with-auth.tar.gz --rename-conflicts
145
+ ```
146
+
147
+ Backups created with `--include-auth` contain Codex credentials from `auth.json`. Store them securely and never commit them to git. Without `--include-auth`, export writes metadata only.
148
+
124
149
  Import legacy `codex-accounts` AUTH-mode snapshots:
125
150
 
126
151
  ```bash
@@ -146,11 +171,65 @@ Inspect workspaces:
146
171
  ```bash
147
172
  codex-workspaces list
148
173
  codex-workspaces current
174
+ codex-workspaces info work
149
175
  codex-workspaces doctor
150
176
  codex-workspaces stats
177
+ codex-workspaces stats summary --days 30
178
+ codex-workspaces stats daily --format markdown
179
+ codex-workspaces stats models --format json
180
+ codex-workspaces stats workspaces
181
+ codex-workspaces stats accounts
151
182
  codex-workspaces stats work --days 14
152
183
  ```
153
184
 
185
+ `stats` only reads local SQLite state. Missing or unrecognized workspace/account/model data is shown as `unknown`; results are best-effort and depend on the local Codex files available in each workspace.
186
+
187
+ ## Experimental Realtime Quota
188
+
189
+ `codex-workspaces` can optionally query realtime quota for managed accounts through an experimental private API provider.
190
+
191
+ This feature is disabled by default. It may break when upstream Codex/OpenAI internals change, may return `401`/`403`/`429`, and is not required for workspace or account switching.
192
+
193
+ Enable explicitly:
194
+
195
+ ```bash
196
+ codex-workspaces config set experimental_private_api.enabled true
197
+ codex-workspaces config set experimental_private_api.quota_enabled true
198
+ codex-workspaces config set experimental_private_api.refresh_enabled true
199
+ ```
200
+
201
+ Query current account quota:
202
+
203
+ ```bash
204
+ codex-workspaces quota
205
+ codex-workspaces quota --json
206
+ ```
207
+
208
+ Query a specific managed account:
209
+
210
+ ```bash
211
+ codex-workspaces accounts quota acct_work
212
+ ```
213
+
214
+ Query all accounts with quota:
215
+
216
+ ```bash
217
+ codex-workspaces accounts list -a
218
+ codex-workspaces accounts list --all-with-quota --json
219
+ ```
220
+
221
+ Refresh remote account metadata and quota cache:
222
+
223
+ ```bash
224
+ codex-workspaces accounts refresh
225
+ codex-workspaces accounts refresh acct_work
226
+ codex-workspaces accounts refresh --all --json
227
+ ```
228
+
229
+ Realtime quota uses explicit experimental configuration, timeout, serial account iteration, and a local TTL cache under `~/.codex-workspaces/cache/quota/`. The cache stores quota summaries and auth hashes only; it does not store tokens, cookies, authorization headers, or raw `auth.json`.
230
+
231
+ `stats` and `quota` are different: `stats` is local historical usage from SQLite, while `quota` is a realtime remote lookup. Quota failures do not affect local workspace/account switching.
232
+
154
233
  Switch accounts within the current workspace:
155
234
 
156
235
  ```bash
@@ -158,7 +237,7 @@ codex-workspaces accounts use acct_personal
158
237
  codex-workspaces accounts restore-default
159
238
  ```
160
239
 
161
- `accounts use` only changes the current workspace `active_account_id`; it does not change `default_account_id`. Entering a workspace with `codex-workspaces use <workspace>` restores that workspace's default account when one is configured.
240
+ `accounts use` only changes the current workspace `active_account_id`; it does not change `default_account_id`. Entering a workspace uses `CODEX_WORKSPACES_RESTORE_POLICY`: `workspace-default` restores the workspace default account, `last-active` restores that workspace's last active account, and `keep-current` keeps the account you were just using when possible.
162
241
 
163
242
  `auth.json` contains credentials. Do not commit workspace directories, account snapshots, SQLite state, sessions, or shell snapshots to git; the project `.gitignore` excludes these patterns for local checkouts.
164
243
 
@@ -166,6 +245,7 @@ Manage account metadata and snapshots:
166
245
 
167
246
  ```bash
168
247
  codex-workspaces accounts note acct_research "lab account"
248
+ codex-workspaces accounts info acct_research
169
249
  codex-workspaces accounts rename acct_research acct_lab
170
250
  codex-workspaces accounts delete acct_lab --force
171
251
  ```
@@ -198,6 +278,7 @@ codex-workspaces restart
198
278
  | `CODEX_QUIT_TIMEOUT` | `20` | Seconds to wait for app exit. |
199
279
  | `CODEX_WORKSPACES_LINK` | `$HOME/.codex` | Active workspace link path. |
200
280
  | `CODEX_WORKSPACES_ROOT` | `$HOME/.codex-workspaces` | Managed root for workspaces, accounts, backups, and lock file. |
281
+ | `CODEX_WORKSPACES_RESTORE_POLICY` | `workspace-default` | Account restore policy when entering a workspace: `workspace-default`, `last-active`, or `keep-current`. |
201
282
  | `CODEX_WORKSPACES_LANG` | auto | Force output language with `en` or `zh`. |
202
283
 
203
284
  Only the `CODEX_WORKSPACES_*` variables are used for workspace-specific configuration.
{codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/README.zh-CN.md RENAMED
@@ -17,10 +17,14 @@
17
17
  - 管理 `~/.codex-workspaces/accounts/` 下的账号快照。
18
18
  - 切换当前 `~/.codex` 软链接或目录链接。
19
19
  - 初始化带元数据的工作区目录。
20
+ - 通过隔离的临时登录工作区执行 `accounts add --login`，新增账号而不退出当前账号。
20
21
  - 通过 `accounts use` 临时切换当前工作区账号，并可恢复工作区默认账号。
22
+ - 从本地 `auth.json` best-effort 解析 email/account 等元信息，不发网络请求。
23
+ - 导出和导入账号快照备份包；包含 auth 的备份会明确提示凭据风险。
24
+ - 查看工作区/账号元数据，并通过 `doctor` 做账号诊断。
21
25
  - 迁移旧版 `~/.codex-<name>` 工作区，并导入旧 `~/.codex-accounts` 账号快照。
22
26
  - 保留 macOS 上 Codex App 的 `stop`、`start`、`restart`。
23
- - 以只读方式读取 Codex `state_*.sqlite`，展示本地 token 用量统计。
27
+ - 以只读方式读取 Codex `state_*.sqlite`，展示每日、模型、工作区、账号、JSON 和 Markdown 形式的本地 token 统计。
24
28
  - 在检测到 Codex 内置 Terminal 且无法安全转交时，阻止危险操作。
25
29
  - 支持中英文输出，可通过 `CODEX_WORKSPACES_LANG` 指定。
26
30
  - 提供 Python 包、测试、GitHub CI 和 PyPI 发布工作流。
@@ -121,6 +125,27 @@ codex-workspaces accounts init research
121
125
  codex-workspaces accounts save research
122
126
  ```
123
127
 
128
+ 如果要新增账号，但不想退出当前工作区账号，可以用临时登录工作区：
129
+
130
+ ```bash
131
+ codex-workspaces accounts add research --login
132
+ ```
133
+
134
+ 它会把 `~/.codex` 临时切到 `login-<账号>` 工作区，让你登录新账号；登录生成 `auth.json` 后保存为 `acct_<账号>`，再恢复原工作区。如果登录中断，可用 `codex-workspaces accounts cleanup-login-temp` 清理残留临时工作区。
135
+
136
+ 账号元信息如 `email`、`account_id`、`user_id`、`organization_id`、`plan` 会从本地 `auth.json` best-effort 解析。解析失败不会影响账号功能，不会打印 token/secret/cookie 等敏感字段，也不会调用私有接口或发起网络请求。
137
+
138
+ 导出或导入账号备份：
139
+
140
+ ```bash
141
+ codex-workspaces accounts export accounts.tar.gz --all
142
+ codex-workspaces accounts export accounts-with-auth.tar.gz --all --include-auth --yes
143
+ codex-workspaces accounts import accounts-with-auth.tar.gz --dry-run
144
+ codex-workspaces accounts import accounts-with-auth.tar.gz --rename-conflicts
145
+ ```
146
+
147
+ 使用 `--include-auth` 创建的备份包包含 `auth.json` 里的 Codex 凭据，必须安全保存，不能提交到 git。不带 `--include-auth` 时只导出 meta，不包含 auth。
148
+
124
149
  导入旧 `codex-accounts` 的 AUTH 模式账号快照：
125
150
 
126
151
  ```bash
@@ -146,11 +171,65 @@ codex-workspaces work --no-stop --no-start
146
171
  ```bash
147
172
  codex-workspaces list
148
173
  codex-workspaces current
174
+ codex-workspaces info work
149
175
  codex-workspaces doctor
150
176
  codex-workspaces stats
177
+ codex-workspaces stats summary --days 30
178
+ codex-workspaces stats daily --format markdown
179
+ codex-workspaces stats models --format json
180
+ codex-workspaces stats workspaces
181
+ codex-workspaces stats accounts
151
182
  codex-workspaces stats work --days 14
152
183
  ```
153
184
 
185
+ `stats` 只读取本地 SQLite 状态文件。无法识别的 workspace/account/model 会显示为 `unknown`；统计结果取决于各工作区里实际存在的 Codex 本地文件。
186
+
187
+ ## 实验性实时额度查询
188
+
189
+ `codex-workspaces` 可以通过实验性 private API provider 查询已管理账号的实时额度。
190
+
191
+ 该功能默认关闭，依赖 Codex/OpenAI 内部接口，可能随上游变化而失效，也可能返回 `401`/`403`/`429`。它不是 workspace/account 本地切换的依赖。
192
+
193
+ 显式开启：
194
+
195
+ ```bash
196
+ codex-workspaces config set experimental_private_api.enabled true
197
+ codex-workspaces config set experimental_private_api.quota_enabled true
198
+ codex-workspaces config set experimental_private_api.refresh_enabled true
199
+ ```
200
+
201
+ 查询当前账号额度：
202
+
203
+ ```bash
204
+ codex-workspaces quota
205
+ codex-workspaces quota --json
206
+ ```
207
+
208
+ 查询指定账号额度：
209
+
210
+ ```bash
211
+ codex-workspaces accounts quota acct_work
212
+ ```
213
+
214
+ 查询所有账号额度：
215
+
216
+ ```bash
217
+ codex-workspaces accounts list -a
218
+ codex-workspaces accounts list --all-with-quota --json
219
+ ```
220
+
221
+ 刷新账号远端信息和 quota cache：
222
+
223
+ ```bash
224
+ codex-workspaces accounts refresh
225
+ codex-workspaces accounts refresh acct_work
226
+ codex-workspaces accounts refresh --all --json
227
+ ```
228
+
229
+ 实时额度能力使用显式实验配置、请求超时、串行账号遍历和本地 TTL 缓存，缓存目录为 `~/.codex-workspaces/cache/quota/`。缓存只保存额度摘要和 auth hash，不保存 token、cookie、authorization header 或原始 `auth.json`。
230
+
231
+ `stats` 和 `quota` 不同：`stats` 是本地 SQLite 历史统计，`quota` 是实时远端查询。额度查询失败不会影响本地 workspace/account 切换。
232
+
154
233
  在当前工作区临时切换账号：
155
234
 
156
235
  ```bash
@@ -158,7 +237,7 @@ codex-workspaces accounts use acct_personal
158
237
  codex-workspaces accounts restore-default
159
238
  ```
160
239
 
161
- `accounts use` 只修改当前工作区的 `active_account_id`，不会修改 `default_account_id`。执行 `codex-workspaces use <工作区>` 进入某个工作区时，如果配置了默认账号，会恢复该工作区默认账号。
240
+ `accounts use` 只修改当前工作区的 `active_account_id`，不会修改 `default_account_id`。进入工作区时按 `CODEX_WORKSPACES_RESTORE_POLICY` 恢复账号：`workspace-default` 恢复工作区默认账号，`last-active` 恢复该工作区上次活跃账号，`keep-current` 尽量沿用刚才正在使用的账号。
162
241
 
163
242
  `auth.json` 包含认证凭据，不要提交到 git。工作区目录、账号快照、SQLite 状态、sessions 和 shell snapshots 已在本项目 `.gitignore` 中排除。
164
243
 
@@ -166,6 +245,7 @@ codex-workspaces accounts restore-default
166
245
 
167
246
  ```bash
168
247
  codex-workspaces accounts note acct_research "实验室账号"
248
+ codex-workspaces accounts info acct_research
169
249
  codex-workspaces accounts rename acct_research acct_lab
170
250
  codex-workspaces accounts delete acct_lab --force
171
251
  ```
@@ -198,6 +278,7 @@ codex-workspaces restart
198
278
  | `CODEX_QUIT_TIMEOUT` | `20` | 等待 App 退出的秒数。 |
199
279
  | `CODEX_WORKSPACES_LINK` | `$HOME/.codex` | 当前工作区链接路径。 |
200
280
  | `CODEX_WORKSPACES_ROOT` | `$HOME/.codex-workspaces` | workspaces、accounts、backups 和 lock 所在管理根目录。 |
281
+ | `CODEX_WORKSPACES_RESTORE_POLICY` | `workspace-default` | 进入工作区时的账号恢复策略：`workspace-default`、`last-active` 或 `keep-current`。 |
201
282
  | `CODEX_WORKSPACES_LANG` | 自动 | 强制输出语言，可设为 `en` 或 `zh`。 |
202
283
 
203
284
  工作区相关配置只使用 `CODEX_WORKSPACES_*` 变量。
{codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/docs/DESIGN.zh-CN.md RENAMED
@@ -80,15 +80,24 @@ Windows：
80
80
  ## 安全设计
81
81
 
82
82
  - 如果 `~/.codex` 存在且不是链接，`switch` 拒绝执行，避免覆盖真实目录。
83
- - 旧 `~/.codex-<name>` 工作区迁移和旧 `~/.codex-accounts` 导入已支持；login-temp 登录流程仍留到后续阶段。
83
+ - 旧 `~/.codex-<name>` 工作区迁移和旧 `~/.codex-accounts` 导入已支持。
84
+ - `accounts add <account> --login` 使用临时 `login-<account>` 工作区登录新账号，保存账号快照后恢复原工作区。
84
85
  - 切换 workspace 前会保存当前 live `auth.json` 到 `active_account_id` 对应账号快照。
85
86
  - `accounts use` 只修改当前 workspace 的 `active_account_id`，不修改 `default_account_id`。
86
- - 进入 workspace 时默认恢复该 workspace 的默认账号。
87
+ - 进入 workspace 时按策略恢复账号：`workspace-default` 恢复默认账号，`last-active` 恢复该 workspace 上次活跃账号，`keep-current` 尽量沿用刚才正在使用的账号。
88
+ - `auth.json` 元信息解析只做本地 best-effort 递归扫描，用于补全 email/account_id/user_id/organization_id/plan/auth_hash；解析失败不影响切换和账号功能。
89
+ - auth 解析不会打印 token、secret、credential、authorization、refresh、access、cookie 等敏感字段，不刷新 token，不调用私有接口，不发网络请求。
90
+ - `accounts export` 默认只导出 meta；必须显式 `--include-auth` 并确认后才导出 `auth.json` 凭据。
91
+ - `accounts import` 解包前校验 tar 条目，拒绝路径穿越、绝对路径、symlink、硬链接和设备文件；导入 auth 后保持 0600 权限，覆盖前写入备份。
87
92
  - `migrate --dry-run` 只打印计划，不创建目录、不写元数据。
88
93
  - `migrate` 会先备份当前 `~/.codex`、旧 workspace 和旧账号目录，再复制到统一目录；旧目录不会被自动删除。
89
94
  - 如果当前 `~/.codex` 是真实目录，批量 `migrate` 会拒绝覆盖；应使用 `init <name> --migrate-current` 显式迁移当前目录。
90
95
  - `stats` 只以 read-only SQLite URI 读取 `state_*.sqlite`，不写入 Codex 数据库。
91
- - 不实现 `quota`/`refresh` 这类依赖私有接口或私有行为的功能。
96
+ - `stats` 聚合每日、模型、workspace、account 维度；无法推断的 workspace/account/model 显示为 `unknown`。
97
+ - 默认不启用 `quota`/`refresh` 这类依赖私有接口或私有行为的能力；只作为显式开启的实验功能提供。
98
+ - 实验性 `quota` / `accounts list -a` / `accounts refresh` 是显式开启的 private API capability；默认关闭，失败隔离，不参与 workspace/account 切换。
99
+ - private API provider 只在配置中开启且配置 endpoint 或注入 provider 后使用；请求有 timeout，错误会脱敏，输出和 cache 不包含 token/cookie/authorization。
100
+ - quota cache 存放在 `~/.codex-workspaces/cache/quota/`，按 TTL 和 auth_hash 失效，只保存 quota 摘要。
92
101
  - macOS 上迁移前必须确认 Codex App 未运行。
93
102
  - Codex 内置 Terminal 中的危险命令要么转交外部 Terminal，要么拒绝。
94
103
  - 任何切换都只替换 active link，不删除 workspace 目录。
@@ -97,13 +106,27 @@ Windows：
97
106
 
98
107
  工作区相关环境变量：
99
108
 
100
- - 变量：`CODEX_WORKSPACES_ROOT`、`CODEX_WORKSPACES_LINK`、`CODEX_WORKSPACES_WORKSPACES_DIR`、`CODEX_WORKSPACES_ACCOUNTS_DIR`、`CODEX_WORKSPACES_LANG`。
109
+ - 变量：`CODEX_WORKSPACES_ROOT`、`CODEX_WORKSPACES_LINK`、`CODEX_WORKSPACES_WORKSPACES_DIR`、`CODEX_WORKSPACES_ACCOUNTS_DIR`、`CODEX_WORKSPACES_RESTORE_POLICY`、`CODEX_WORKSPACES_LANG`。
110
+ - `CODEX_WORKSPACES_RESTORE_POLICY` 可选 `workspace-default`、`last-active`、`keep-current`；无效值回退到 `workspace-default`。
101
111
 
102
112
  迁移相关命令：
103
113
 
104
114
  - `codex-workspaces migrate --dry-run`
105
115
  - `codex-workspaces migrate [--from-prefix ~/.codex-] [--from-accounts ~/.codex-accounts]`
106
116
  - `codex-workspaces init <workspace> --migrate-current`
117
+ - `codex-workspaces info <workspace>`
118
+ - `codex-workspaces accounts add <account> --login`
119
+ - `codex-workspaces accounts login-temp <account>`
120
+ - `codex-workspaces accounts cleanup-login-temp`
121
+ - `codex-workspaces accounts refresh-meta <account>|--all [--overwrite]`
122
+ - `codex-workspaces accounts export <backup.tar.gz> [--all|--account <account>] [--include-auth] [--yes]`
123
+ - `codex-workspaces accounts import <backup.tar.gz> [--dry-run] [--rename-conflicts|--overwrite]`
124
+ - `codex-workspaces stats [summary|daily|models|workspaces|accounts] [--format table|json|markdown]`
125
+ - `codex-workspaces config get/set experimental_private_api.*`
126
+ - `codex-workspaces quota [--json] [--no-cache]`
127
+ - `codex-workspaces accounts quota <account> [--json] [--no-cache]`
128
+ - `codex-workspaces accounts list -a [--json] [--no-cache] [--verbose]`
129
+ - `codex-workspaces accounts refresh [account|--all] [--json]`
107
130
  - `codex-workspaces accounts import-workspaces`
108
131
  - `codex-workspaces accounts import-legacy <legacy_accounts_dir>`
109
132
 
{codex_workspaces-0.3.0 → codex_workspaces-0.3.2}/docs/RELEASE.zh-CN.md RENAMED
@@ -88,9 +88,9 @@ permissions:
88
88
  1. 更新版本号和 `CHANGELOG.md`。
89
89
  2. 本地执行测试和构建检查。
90
90
  3. 合并到 `main`。
91
- 4. 创建 Git tag，例如 `v0.3.0`，触发 `Publish to TestPyPI`。
91
+ 4. 创建 Git tag，例如 `v0.3.2`，触发 `Publish to TestPyPI`。
92
92
  5. 确认 TestPyPI 上传和安装正常。
93
- 6. 从同一个提交创建并推送正式发布分支，例如 `release/v0.3.0`，触发 `Publish to PyPI`。
93
+ 6. 从同一个提交创建并推送正式发布分支，例如 `release/v0.3.2`，触发 `Publish to PyPI`。
94
94
  7. 如果 `pypi` Environment 配置了 Required reviewers，在 GitHub Actions 里批准部署。
95
95
  8. 在 PyPI 页面确认 wheel、sdist 和 README 渲染正常。
96
96