proxitor 0.9.0-beta.1 → 0.9.0-beta.3

package/README.md

@@ -266,9 +266,9 @@ Both `cacheControl` and `sessionId` support `auto` / `always` / `never` modes:
 
 | Mode | `cacheControl` | `sessionId` |
 | --- | --- | --- |
-| `auto` (default) | Anthropic models on `/v1/chat/completions`; all models on `/v1/messages` and `/v1/responses` | Use `X-Claude-Code-Session-Id` header if present; otherwise generate proxy UUID |
-| `always` | All models, all endpoints | Generate a proxy UUID for sticky routing |
-| `never` | Disabled | Disabled |
+| `auto` (default) | Anthropic models on `/v1/chat/completions`; all models on `/v1/messages` and `/v1/responses` | Passthrough client session ID if present; otherwise generate proxy UUID |
+| `always` | All models, all endpoints | Always generate proxy session ID, ignoring client-provided |
+| `never` | Disabled | Don't manage session headers — pass through as-is |
 
 `cacheControlTtl` values:
 
@@ -331,7 +331,7 @@ When both formats are present (e.g., OpenRouter relaying an Anthropic response),
 
 ## Interactive Config Manager
 
-Proxitor includes an interactive CLI for managing model overrides — search models, pick providers, and write to config without editing YAML by hand.
+Proxitor includes an interactive CLI for managing configuration — global settings, model overrides, and diagnostics — without editing YAML by hand.
 
 ### Setup wizard
 
@@ -345,13 +345,24 @@ The wizard asks for:
 
 - **OpenRouter API key** — stored in config or set as `OPENROUTER_API_KEY` env var
 - **Port** — default `8828` (avoids conflicts with common dev servers on 8080)
+- **Listen address** — all interfaces (`0.0.0.0`), localhost only (`127.0.0.1`), or a custom address (IP, hostname, or `unix:/path`)
 - **API base URL** — default `https://openrouter.ai/api`; change for self-hosted or custom endpoints
-- **Data URL** — separate URL for provider/model data fetching; falls back to OpenRouter automatically if the custom API doesn't support these endpoints
 - **Authentication type** — `bearer` (default) or `oauth`; use `oauth` for custom proxy providers that pass tokens in the `Authorization: OAuth ...` header
-- **Host** — all interfaces (`0.0.0.0`) or localhost only (`127.0.0.1`)
 - **Save location** — project directory, `~/.config/proxitor/`, or `$XDG_CONFIG_HOME/proxitor/`
 
-If a config already exists, the wizard shows its location and asks whether to reconfigure. Existing `modelOverrides`, `provider`, and other fields are preserved — only the wizard fields are updated.
+After collecting the key, base URL, and auth type, the wizard performs a **best-effort upstream probe** (3 s timeout) to verify connectivity. If the upstream is unreachable or the key is rejected, a warning is shown but the config is still saved — this is informational only.
+
+If a config already exists, the wizard shows its location and asks whether to reconfigure. All fields are **pre-filled** with current values — press Enter to keep, or type a new value. Existing `modelOverrides`, `provider`, and other fields are preserved — only the wizard fields are updated.
+
+### Config menu
+
+`proxitor config` (or `proxitor config menu`) opens an interactive menu that loops until you exit. From there you can manage all settings:
+
+- **Show current config** — display the resolved configuration
+- **API key & connection** — change API key, port, listen address, base URL, auth type
+- **Session routing** — set global `sessionId` mode (`auto` / `always` / `never`)
+- **Cache control** — set global `cacheControl` mode and TTL
+- **Model overrides** — add, edit, remove, list, or browse models
 
 ```sh
 proxitor config menu           # interactive menu
@@ -359,11 +370,20 @@ proxitor config add            # add a model override
 proxitor config edit           # edit existing override
 proxitor config remove         # remove override(s)
 proxitor config list           # show current overrides
+proxitor config list --json    # overrides as JSON
+proxitor config show           # print the resolved config (merged)
+proxitor config show --json    # same, machine-readable
 proxitor config browse         # explore models with pricing info
 proxitor config wizard         # interactive setup wizard
-proxitor config validate       # validate config file
+proxitor config validate       # validate config file (exit 0 ok, 1 invalid)
+proxitor config validate --json  # structured JSON result
+proxitor doctor                # diagnose environment + network + port + version
+proxitor doctor --json         # machine-readable diagnostic report
+proxitor doctor --offline      # skip network checks
 ```
 
+When adding or editing a model override, you can also configure per-model `sessionId` and `cacheControl` — useful for models that need different caching or routing behavior than the global default.
+
 ### Add override walkthrough
 
 ```sh
@@ -426,19 +446,92 @@ The interface uses live data from the OpenRouter API — model search with type-
 
 ---
 
+## Diagnostics
+
+When something doesn't work, `proxitor doctor` runs a battery of checks and prints a report. Sections cover:
+
+- **Environment** — Node version, platform, TTY
+- **Config** — discovery path, validity, override count
+- **API key** — resolution (env vs. file; never prints the key)
+- **Network** — upstream reachability (with configurable timeout)
+- **Port** — availability of the configured port
+- **Version** — installed version
+
+Statuses: `✓ ok` / `⚠ warn` / `✗ fail` / `ⓘ skip`. Exit code is `0` when no `fail`, `1` otherwise — scriptable from CI.
+
+```sh
+$ proxitor doctor
+
+▲ Proxitor Doctor
+│
+◇ Environment
+│  ✓ node-version — v22.4.1
+│  ✓ platform — darwin arm64
+│  ✓ tty — true
+│
+◇ Config
+│  ✓ config-found — /Users/u/proj/proxitor.config.yaml
+│  ✓ config-valid — 12 keys, 3 override(s)
+│
+◇ API key
+│  ✓ api-key — set (env: set, file: set)
+│
+◇ Network
+│  ✓ upstream — https://openrouter.ai/api — 200, 342 models
+│
+◇ Port
+│  ✓ port-8828 — 127.0.0.1:8828
+│
+◇ Version
+│  ✓ version — 0.9.0-beta.1
+
+└ Done. All checks passed.
+```
+
+Useful flags:
+
+```sh
+proxitor doctor --json         # structured JSON for CI / scripts
+proxitor doctor --offline      # skip network checks (no upstream, no npm)
+proxitor doctor --timeout 5000 # custom per-check network timeout (ms)
+```
+
+---
+
 ## CLI Options
 
+```sh
+proxitor                        # start the proxy (default command)
+proxitor start                  # same as above
+proxitor up                     # alias for start
+proxitor run                    # alias for start
+proxitor --port 9000            # override port
+proxitor ./team.yaml            # use an explicit config
+proxitor config show            # print the resolved config
+proxitor config show --json     # machine-readable config
+proxitor config list --json     # overrides as JSON
+proxitor config wizard          # interactive setup
+proxitor config validate        # check the current config (exit 0/1)
+proxitor config validate --json # structured JSON result
+proxitor doctor                 # diagnose environment, network, port, version
+proxitor doctor --offline       # skip network checks
+proxitor --help                 # full help
+proxitor --version              # print version
+```
+
 | Flag | Default | Description |
 |---|---|---|
-| `-p, --port <port>` | `8828` | Server port |
+| `-p, --port <port>` | `8828` | Server port (validated: 1-65535) |
 | `-h, --host <host>` | `0.0.0.0` | Server host |
-| `-c, --config <path>` | auto-discovered | Path to config file |
-| `--openrouter-key <key>` | `$OPENROUTER_API_KEY` | OpenRouter API key |
+| `-c, --config <path>` | auto-discovered | Path to config file (positional `[config-path]` also accepted) |
+| `--openrouter-key <key>` / `-k <key>` | `$OPENROUTER_API_KEY` | OpenRouter API key |
 | `--verbose` | `false` | Enable verbose logging |
 | `--no-config` | | Skip config file discovery |
 | `-v, --version` | | Print version |
 | `--help` | | Print help |
 
+Subcommands live under `proxitor config <subcommand>`. Run `proxitor config --help` for the full list, or see [Interactive Config Manager](#interactive-config-manager) for the walkthroughs.
+
 ---
 
 ## Development