@bjesuiter/codex-switcher 1.3.0 → 1.5.0

package/README.md

@@ -6,20 +6,27 @@ Switch the coding-agents [pi](https://pi.dev/), [codex](https://developers.opena
 
 ## Latest Changes
 
-### 1.3.0
+### 1.5.0
 
 #### Features
 
-- Rename `cdx refresh` command to `cdx relogin`
+- Add shell completion support via `cdx complete <shell>` (with parse-completion handling for shell integrations).
+- Add configurable secret-store selection with `--secret-store <mode>` (`auto` or `legacy-keychain`) plus persisted config support.
+- Switch macOS `auto` secret storage to cross-keychain backend selection (prefers native backend, falls back when needed).
+- Add `cdx migrate-secrets` to migrate legacy macOS keychain entries to cross-keychain and update config.
+- Add optional macOS keychain ACL diagnostics in `cdx doctor --check-keychain-acl` to verify trusted runtime access.
+- Add doctor/runtime warnings when macOS keychain access is using legacy/CLI fallback paths where Touch ID prompts may not be offered.
+- Increase cross-keychain max password length handling (default `16384`) to support larger stored credential payloads.
 
 #### Fixes
 
-- Fix `cdx relogin` selector flow exiting early after account selection (now continues into OAuth browser login)
+- Keep `cdx doctor` fast by making keychain ACL checks opt-in and improving output with clearer guidance and progress feedback.
+- Remove Windows credential payload chunking now that larger payloads are supported directly in the secure store backend.
 
 #### Internal
 
-- Modularize CLI command wiring by moving command handlers into per-command modules under `lib/commands/`, keeping `cdx.ts` as a thin composition entrypoint
-- Update package dependencies and lockfile (`@clack/prompts`, `commander`, `tsdown`, `@types/bun`, `@types/node`)
+- Temporarily switch keyring dependency from `cross-keychain` to `@bjesuiter/cross-keychain@1.1.0-jb.0` until upstream support is available.
+- Add Windows CI coverage including shell smoke checks and expanded secure-store integration tests (including Windows CRUD coverage).
 
 see full changelog here: https://github.com/bjesuiter/codex-switcher/blob/main/CHANGELOG.md
 
@@ -41,9 +48,15 @@ So: switching between two $20 plans is the poor man's $100 plan for OpenAI. ^^
 
 ## Requirements
 
-- macOS (uses Keychain via the `security` command)
+- macOS (uses Keychain), Windows (uses Windows Credential Manager), **or** Linux (uses Secret Service/keyring)
 - [Bun](https://bun.sh) runtime
 
+## Platform Support Status
+
+- **macOS:** stable
+- **Windows:** beta
+- **Linux:** beta
+
 ## Install
 
 ```bash
@@ -54,63 +67,102 @@ This exposes the `cdx` binary globally.
 
 ## Usage
 
-### Add your first account
+### macOS (stable)
+
+1. Install [Bun](https://bun.sh)
+2. Install `cdx`
+3. Run and verify:
+   - `cdx login`
+   - `cdx status`
+   - `cdx switch`
+   - `cdx relogin <account-id-or-label>`
+4. Confirm auth files are written correctly after switching:
+   - `~/.local/share/opencode/auth.json` (or `$XDG_DATA_HOME/opencode/auth.json`)
+   - `~/.codex/auth.json`
+   - `~/.pi/agent/auth.json` (or `$PI_CODING_AGENT_DIR/auth.json`)
+5. Credentials are stored in macOS Keychain.
+
+### Windows (beta)
+
+Windows support is **test-ready** and suitable for friend/beta testing, but is not yet production-proven by broad real-world testing.
+
+1. Install [Bun](https://bun.sh)
+2. Install `cdx`
+3. Run and verify:
+   - `cdx login`
+   - `cdx status`
+   - `cdx switch`
+   - `cdx relogin <account-id-or-label>`
+4. Confirm auth files are written correctly after switching:
+   - `%LOCALAPPDATA%\\opencode\\auth.json`
+   - `%USERPROFILE%\\.codex\\auth.json`
+   - `%USERPROFILE%\\.pi\\agent\\auth.json` (or `%PI_CODING_AGENT_DIR%\\auth.json`)
+5. If prompted about secure-store fallback, explicitly choose whether to allow it for testing.
+   - Non-interactive override (if you accept the risk): `CDX_ALLOW_SECURE_STORE_FALLBACK=1`
+
+### Linux (beta)
+
+Linux support is **test-ready** and suitable for friend/beta testing, but is not yet production-proven by broad real-world testing.
+
+1. Install [Bun](https://bun.sh)
+2. Ensure a Secret Service backend is available (for example GNOME Keyring with `secret-tool`)
+3. Install `cdx`
+4. Run and verify:
+   - `cdx login`
+   - `cdx status`
+   - `cdx switch`
+   - `cdx relogin <account-id-or-label>`
+5. Confirm auth files are written correctly after switching:
+   - `~/.local/share/opencode/auth.json` (or `$XDG_DATA_HOME/opencode/auth.json`)
+   - `~/.codex/auth.json`
+   - `~/.pi/agent/auth.json` (or `$PI_CODING_AGENT_DIR/auth.json`)
+6. If prompted about secure-store fallback, explicitly choose whether to allow it for testing.
+   - Non-interactive override (if you accept the risk): `CDX_ALLOW_SECURE_STORE_FALLBACK=1`
+
+Please report the full command output and platform info (`cdx status`) for any failures.
+
+### Common command examples (all platforms)
+
+Add your first account:
 
 ```bash
 cdx login
 ```
 
-Opens your browser to authenticate with OpenAI. After successful login, your credentials are stored securely in macOS Keychain.
-
-### Switch between accounts
+Switch between accounts:
 
 ```bash
 cdx switch
-```
-
-Interactive picker to select an account. Writes credentials to:
-- `~/.local/share/opencode/auth.json` (OpenCode)
-- `~/.pi/agent/auth.json` (Pi agent, or `$PI_CODING_AGENT_DIR/auth.json` when `PI_CODING_AGENT_DIR` is set)
-- `~/.codex/auth.json` (Codex CLI; requires `id_token`)
-
-```bash
 cdx switch --next
+cdx switch <account-id-or-label>
 ```
 
-Cycles to the next configured account without prompting.
+Label accounts:
 
 ```bash
-cdx switch <account-id-or-label>
+cdx label
+cdx label <account> <new-label>
 ```
 
-Switch directly to a specific account by ID or label.
-
-### Label accounts
+Interactive mode:
 
 ```bash
-cdx label
+cdx
 ```
 
-Interactive prompt to assign a friendly name to an account.
+Use the legacy macOS keychain implementation (if needed):
 
 ```bash
-cdx label <account> <new-label>
+cdx --secret-store legacy-keychain switch
+cdx --secret-store legacy-keychain status
 ```
 
-Assign a label directly.
-
-### Interactive mode
+Migrate legacy macOS keychain entries to cross-keychain (`auto`) and update config:
 
 ```bash
-cdx
+cdx migrate-secrets
 ```
 
-Running `cdx` without arguments opens an interactive menu to:
-- List all configured accounts
-- Switch to a different account
-- Add a new account (OAuth login)
-- Remove an account
-
 ## Commands
 
 | Command | Description |
@@ -124,22 +176,71 @@ Running `cdx` without arguments opens an interactive menu to:
 | `cdx switch <id>` | Switch to specific account |
 | `cdx label` | Label an account (interactive) |
 | `cdx label <account> <label>` | Assign label directly |
-| `cdx status` | Show account status, token expiry, usage, and auth file state |
+| `cdx status` | Show account status, token expiry, and usage |
+| `cdx migrate-secrets` | Migrate macOS legacy keychain entries to cross-keychain and switch config to `auto` |
+| `cdx doctor` | Show auth file paths/state and runtime capabilities |
+| `cdx doctor --check-keychain-acl` | Run additional macOS keychain trusted-app/ACL checks (slow) |
 | `cdx usage` | Show usage overview for all accounts |
 | `cdx usage <account>` | Show detailed usage for a specific account |
 | `cdx help [command]` | Show help for all commands or one command |
+| `cdx complete <shell>` | Generate shell completion script (`zsh`, `bash`, `fish`, `powershell`) |
 | `cdx version` | Show CLI version |
 | `cdx --help` | Show help |
 | `cdx --version` | Show version |
+| `cdx --secret-store legacy-keychain <command>` | Override configured backend for this run (macOS legacy keychain) |
+
+### Shell completion
+
+Generate and source completion scripts:
+
+```bash
+# zsh
+source <(cdx complete zsh)
+
+# bash
+source <(cdx complete bash)
+```
+
+`cdx` also supports shell parse completion requests via `cdx complete -- ...`.
 
 ## How It Works
 
-- OAuth credentials are stored securely in macOS Keychain
-- Account list is stored in `~/.config/cdx/accounts.json`
-- Active account credentials are written to:
-  - `~/.local/share/opencode/auth.json`
-  - `~/.pi/agent/auth.json` (or `$PI_CODING_AGENT_DIR/auth.json`)
-  - `~/.codex/auth.json` (when `id_token` exists)
+### Secure credential storage
+
+- **macOS:** macOS Keychain
+- **Windows:** Windows Credential Manager
+- **Linux:** Secret Service/keyring
+- Default backend selection is automatic (`auto`).
+- You can persist a preferred backend in `accounts.json` via optional `"secretStore"` (`"auto"` or `"legacy-keychain"`).
+- `--secret-store <mode>` always overrides config for the current run.
+- If only a fallback secure-store backend is available on your platform, `cdx` asks for one-time explicit consent before the first credential write and explains the security trade-off.
+  - Non-interactive override (if you accept the risk): set `CDX_ALLOW_SECURE_STORE_FALLBACK=1`
+- On macOS, `cdx doctor --check-keychain-acl` performs an additional trusted-app/ACL check for configured account secrets. This check can be slow.
+- Cross-keychain payload size policy:
+  - Default max password length override is `16384`.
+  - Optional override: set `CDX_CROSS_KEYCHAIN_MAX_PASSWORD_LENGTH=<integer-above-4096>`.
+  - This currently relies on `@bjesuiter/cross-keychain@1.1.0-jb.0` until upstream support is released.
+
+### Account list path
+
+- **macOS/Linux:** `~/.config/cdx/accounts.json` (or `$XDG_CONFIG_HOME/cdx/accounts.json`)
+- **Windows:** `%APPDATA%\\cdx\\accounts.json`
+
+### Auth file paths
+
+#### macOS / Linux
+
+- **OpenCode:** `~/.local/share/opencode/auth.json` (or `$XDG_DATA_HOME/opencode/auth.json`)
+- **Codex CLI:** `~/.codex/auth.json`
+- **Pi Agent:** `~/.pi/agent/auth.json` (or `$PI_CODING_AGENT_DIR/auth.json`)
+
+#### Windows
+
+- **OpenCode:** `%LOCALAPPDATA%\\opencode\\auth.json`
+- **Codex CLI:** `%USERPROFILE%\\.codex\\auth.json`
+- **Pi Agent:** `%USERPROFILE%\\.pi\\agent\\auth.json` (or `%PI_CODING_AGENT_DIR%\\auth.json`)
+
+`cdx` writes Codex CLI auth only when `id_token` exists.
 
 ## For Developers
 
@@ -162,7 +263,7 @@ bun link
 
 ### Manual Configuration (Advanced)
 
-You can also manually add accounts to Keychain:
+You can also manually add accounts to Keychain (macOS only):
 
 ```bash
 security add-generic-password -a "ACCOUNT_ID" -s "cdx-openai-ACCOUNT_ID" -w '{"refresh":"REFRESH","access":"ACCESS","expires":1234567890,"accountId":"ACCOUNT_ID"}' -U
@@ -173,6 +274,7 @@ And create the accounts list manually:
 ```json
 {
   "current": 0,
+  "secretStore": "auto",
   "accounts": [
     { "accountId": "ACCOUNT_ID", "keychainService": "cdx-openai-ACCOUNT_ID" }
   ]