@hieplp/pi-account-switcher 0.2.0

package/INSTALL_AS_PI_PACKAGE.md

@@ -0,0 +1,78 @@
+# Install Pi Account Switcher as a Pi Package
+
+This repo can be installed by Pi from GitHub now, and can be installed with `pi install npm:@hieplp/pi-account-switcher` after it is published to npm.
+
+## Install from GitHub
+
+Install globally:
+
+```bash
+pi install git:github.com/hieplp/pi-account-switcher
+```
+
+Or test for one Pi run without permanently installing:
+
+```bash
+pi -e git:github.com/hieplp/pi-account-switcher
+```
+
+Install project-locally, writing to `.pi/settings.json`:
+
+```bash
+pi install -l git:github.com/hieplp/pi-account-switcher
+```
+
+Then inside Pi, add your first account:
+
+```txt
+/reload
+/accounts:add
+```
+
+## Install like `pi install npm:@hieplp/pi-account-switcher`
+
+The package is configured for npm publishing with:
+
+- `keywords: ["pi-package", "pi-extension", ...]`
+- `pi.extensions: ["./src/extension.ts"]`
+- Pi core packages in `peerDependencies`
+- runtime dependency `zod` in `dependencies`
+- package files limited to `src`, `README.md`, `USAGE.md`, and this install guide
+
+### Publish to npm
+
+Login to npm:
+
+```bash
+npm login
+```
+
+Optional: verify what will be published:
+
+```bash
+npm pack --dry-run
+```
+
+Publish (scoped packages require `--access public`):
+
+```bash
+npm publish --access public
+```
+
+After publishing, users can install globally with:
+
+```bash
+pi install npm:@hieplp/pi-account-switcher
+```
+
+Or install project-locally with:
+
+```bash
+pi install -l npm:@hieplp/pi-account-switcher
+```
+
+To test without permanently installing:
+
+```bash
+pi -e npm:@hieplp/pi-account-switcher
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hieplp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,214 @@
+# Pi Account Switcher
+
+> Switch between multiple API keys and accounts — per provider — inside Pi. No more manual env-var juggling.
+
+```
+claude/work  ·  claude/personal  ·  openai/team  ·  gemini/testing
+```
+
+---
+
+## Install
+
+**From GitHub (recommended)**
+
+```bash
+pi install git:github.com/hieplp/pi-account-switcher
+```
+
+**From npm**
+
+```bash
+pi install npm:@hieplp/pi-account-switcher
+```
+
+**Test without installing**
+
+```bash
+pi -e git:github.com/hieplp/pi-account-switcher
+```
+
+**Project-local install** (writes to `.pi/settings.json`)
+
+```bash
+pi install -l git:github.com/hieplp/pi-account-switcher
+```
+
+**Run from a local checkout**
+
+```bash
+npm install
+pi -e ./src/extension.ts
+```
+
+After installing, reload Pi and add your first account:
+
+```
+/reload
+/accounts:add
+```
+
+---
+
+## Commands
+
+### Accounts
+
+| Command | Description |
+|---|---|
+| `/accounts:add` | Add a new account interactively |
+| `/accounts:list` | List all accounts and activate the selected one |
+| `/accounts:switch` | Switch to another account within the current provider |
+| `/accounts:edit` | Edit label, provider, id, or credential source |
+| `/accounts:remove` | Delete an account |
+| `/accounts:oauth` | Import the current Pi `/login` OAuth session as a named account |
+
+### Providers
+
+| Command | Description |
+|---|---|
+| `/providers:add` | Add a reusable custom provider |
+| `/providers:list` | List custom providers |
+| `/providers:edit` | Edit a custom provider |
+| `/providers:remove` | Remove an unused custom provider |
+
+### Models
+
+| Command | Description |
+|---|---|
+| `/models:list` | List all available models and switch to the selected one |
+| `/models:add` | Add a custom model config to the current provider |
+| `/models:remove` | Remove a custom model config |
+
+### System
+
+| Command | Description |
+|---|---|
+| `/system:reset` | Delete all accounts, providers, and state |
+
+---
+
+## Adding Accounts
+
+Run `/accounts:add` and the wizard will ask for:
+
+1. **Provider** — pick a built-in or custom provider
+2. **Label** — a friendly display name (e.g. `Claude — Work`)
+3. **Account ID** — a unique slug (e.g. `claude-work`)
+4. **Credential env var** — e.g. `ANTHROPIC_API_KEY`
+5. **Secret source** — one of:
+   - Pasted API key (stored in plaintext — prefer the options below)
+   - Existing environment variable
+   - File path
+   - Shell command
+   - 1Password `op://` reference
+
+If the account ID already exists, Pi will ask whether to replace it, enter a new ID, or cancel.
+
+---
+
+## OAuth Accounts (Claude, Codex, etc.)
+
+For subscription providers, use Pi's built-in login first, then import it as a named account:
+
+```
+/login
+```
+
+Complete browser/device login, then:
+
+```
+/accounts:oauth
+```
+
+Give it a label like `Claude — Work`. Repeat for as many accounts as you need — each gets its own saved credentials. Switch between them any time with `/accounts:list`.
+
+OAuth credentials are read from `~/.pi/agent/auth.json` and written back to Pi's live auth storage on switch.
+
+---
+
+## Custom Providers
+
+Define a provider once, reuse it across accounts:
+
+```
+/providers:add
+```
+
+Custom providers are stored at `~/.pi/account-switcher/providers.json` and support all Pi model-provider fields:
+
+```json
+{
+  "providers": {
+    "acme": {
+      "name": "Acme AI",
+      "baseUrl": "https://api.acme.test/v1",
+      "api": "openai-completions",
+      "apiKey": "ACME_API_KEY",
+      "envKeys": ["ACME_API_KEY"],
+      "aliases": ["acme-ai"],
+      "models": [{ "id": "acme-coder", "name": "Acme Coder" }]
+    }
+  }
+}
+```
+
+> Removing a provider is blocked while any account uses it — edit or remove those accounts first.
+
+---
+
+## Config Reference
+
+### Accounts — `~/.pi/account-switcher/accounts.json`
+
+```json
+{
+  "switchMode": "env",
+  "accounts": [
+    {
+      "id": "claude-work",
+      "label": "Claude — Work",
+      "provider": "anthropic",
+      "env": {
+        "ANTHROPIC_API_KEY": { "type": "env", "name": "ANTHROPIC_WORK_API_KEY" }
+      }
+    },
+    {
+      "id": "openai-personal",
+      "label": "OpenAI — Personal",
+      "provider": "openai",
+      "env": {
+        "OPENAI_API_KEY": { "type": "file", "path": "~/.keys/openai-personal.txt" }
+      }
+    }
+  ]
+}
+```
+
+### Secret Sources
+
+```json
+{ "type": "literal", "value": "sk-..." }
+{ "type": "env",     "name": "MY_API_KEY" }
+{ "type": "file",    "path": "~/.keys/key.txt" }
+{ "type": "command", "command": "op read op://AI/Claude/api-key" }
+{ "type": "op",      "reference": "op://AI/Claude/api-key" }
+```
+
+A plain string is treated as a literal; strings starting with `op://` are resolved via `op read`.
+
+### State — `~/.pi/account-switcher/state.json`
+
+Tracks the selected account and model across sessions. Restored automatically on `session_start`.
+
+---
+
+## Credential Caching
+
+On switch, the extension updates `process.env`, Pi's live API-key overrides, and Pi's OAuth auth storage. If a provider still uses old credentials, run `/reload` or restart Pi.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).