opencode-switch-cli 1.0.0

package/README.md

@@ -0,0 +1,376 @@
+# opencode-switch
+
+CLI and programmatic utilities for managing OpenCode providers, model mappings, and API key aliases.
+
+`opencode-switch` keeps your real OpenCode provider configuration in sync while storing its own management metadata separately. It is useful when you want to:
+
+- register multiple OpenCode-compatible vendors
+- map stable model types such as `gpt-5.4` and `gemini` to real upstream model IDs
+- maintain multiple API keys per vendor/model pair
+- switch the active vendor or active key without editing JSON files by hand
+
+## Features
+
+- interactive shortcuts for common workflows
+- explicit `vendor`, `model`, and `key` subcommands for scripting
+- deterministic updates to OpenCode `model` and `small_model` pointers
+- separate metadata storage for active vendor, managed models, and key aliases
+- programmatic API exports for embedding the workflow in your own tools
+
+## Requirements
+
+- Node.js `>= 18.18.0`
+- An existing OpenCode setup, or permission to create files under `~/.config/opencode`
+
+## Installation
+
+Install globally:
+
+```bash
+npm install -g opencode-switch-cli
+```
+
+Or run without installing:
+
+```bash
+npx opencode-switch-cli vendor list
+```
+
+## Files managed by the CLI
+
+`opencode-switch` manages two files under `~/.config/opencode`:
+
+### `opencode.json`
+
+This is the real OpenCode config file. Providers are written under:
+
+```json
+{
+  "provider": {
+    "duck": {
+      "name": "duck",
+      "npm": "@ai-sdk/openai-compatible",
+      "options": {
+        "baseURL": "https://duck.example.com/v1",
+        "apiKey": "duck-key"
+      },
+      "models": {
+        "gpt-5.4": {
+          "name": "duck/gpt-5.4"
+        }
+      }
+    }
+  },
+  "model": "duck/gpt-5.4",
+  "small_model": "duck/gemini"
+}
+```
+
+### `opencode-switch.json`
+
+This file stores switch-specific metadata such as:
+
+- active vendor
+- managed providers
+- managed model registry
+- active key alias per model
+- stored key aliases and credentials
+
+## Quick start
+
+### 1. Add a vendor
+
+```bash
+opencode-switch vendor add duck \
+  --npm @ai-sdk/openai-compatible \
+  --base-url https://duck.example.com/v1 \
+  --api-key duck-key
+```
+
+### 2. Add models for that vendor
+
+Supported model types are currently:
+
+- `gpt-5.4`
+- `gemini`
+
+```bash
+opencode-switch model add duck gpt-5.4 --model duck/gpt-5.4
+opencode-switch model add duck gemini --model google/gemini-2.5-flash
+```
+
+### 3. Add one or more key aliases
+
+```bash
+opencode-switch key add duck gpt-5.4 project-a --api-key duck-project-a-key
+opencode-switch key add duck gpt-5.4 project-b --api-key duck-project-b-key
+```
+
+The first key added for a `vendor + modelType` becomes the active key by default.
+
+### 4. Switch the active vendor
+
+```bash
+opencode-switch vendor use duck
+```
+
+This updates OpenCode pointers deterministically:
+
+- `model` prefers `vendor/gpt-5.4` when available
+- `small_model` prefers `vendor/gemini` when available
+- if the active primary model has an active key alias, the provider `apiKey` is updated too
+
+## Interactive shortcuts
+
+These commands are useful for manual day-to-day operations:
+
+```bash
+opencode-switch ls
+opencode-switch add duck https://duck.example.com/v1
+opencode-switch rm
+opencode-switch addk
+opencode-switch switch
+opencode-switch rmk
+```
+
+### Shortcut behavior
+
+- `ls` shows vendors in a dashboard-style list.
+- `add <name> <url>` adds a vendor using the default npm package `@ai-sdk/openai`.
+- `rm` opens an interactive vendor picker and confirmation step.
+- `addk` walks through vendor -> model -> new key creation, and can create a missing model first.
+- `switch` walks through vendor -> model -> existing key selection and activates the chosen key.
+- `rmk` walks through vendor -> model -> key selection before deletion.
+
+## Command reference
+
+### Vendor commands
+
+Add a vendor:
+
+```bash
+opencode-switch vendor add <vendorName> \
+  --npm <npmPackage> \
+  [--base-url <baseUrl>] \
+  [--api-key <apiKey>]
+```
+
+Example:
+
+```bash
+opencode-switch vendor add duck \
+  --npm @ai-sdk/openai-compatible \
+  --base-url https://duck.example.com/v1 \
+  --api-key duck-key
+```
+
+List vendors:
+
+```bash
+opencode-switch vendor list
+```
+
+Switch the active vendor:
+
+```bash
+opencode-switch vendor use duck
+```
+
+Remove a vendor:
+
+```bash
+opencode-switch vendor remove duck
+```
+
+### Model commands
+
+Add a model mapping:
+
+```bash
+opencode-switch model add <vendorName> <modelType> --model <realModel>
+```
+
+Examples:
+
+```bash
+opencode-switch model add duck gpt-5.4 --model duck/gpt-5.4
+opencode-switch model add duck gemini --model google/gemini-2.5-flash
+```
+
+List models for a vendor:
+
+```bash
+opencode-switch model list duck
+```
+
+Remove a model mapping:
+
+```bash
+opencode-switch model remove duck gpt-5.4
+```
+
+### Key commands
+
+Add a key alias:
+
+```bash
+opencode-switch key add <vendorName> <modelType> <keyAlias> --api-key <apiKey> [--base-url <baseUrl>]
+```
+
+Example:
+
+```bash
+opencode-switch key add duck gpt-5.4 project-a --api-key duck-project-a-key
+```
+
+List keys for a vendor/model pair:
+
+```bash
+opencode-switch key list duck gpt-5.4
+```
+
+Switch the active key alias:
+
+```bash
+opencode-switch key use duck gpt-5.4 project-a
+```
+
+Remove a key alias:
+
+```bash
+opencode-switch key remove duck gpt-5.4 project-a
+```
+
+## Behavior notes
+
+- Unsupported model types are rejected. Right now only `gpt-5.4` and `gemini` are valid.
+- `model list <vendorName>` includes the active key alias when one is set.
+- `key use` changes the active key only for the selected `vendor + modelType` pair.
+- `vendor use` updates OpenCode's default pointers based on available managed models.
+- Removing a vendor also removes its switch metadata and clears OpenCode pointers that referenced it.
+- Existing provider options and model template metadata are preserved where possible.
+
+## Programmatic API
+
+The package also exports reusable functions from `dist/index.js` / `dist/index.mjs`.
+
+### Exported functions
+
+```ts
+import {
+  createJsonFileStore,
+  createModelService,
+  createOpencodeRepository,
+  createSwitchRepository,
+  createVendorService,
+  executeCli,
+  SUPPORTED_MODEL_TYPES,
+} from 'opencode-switch-cli';
+```
+
+### Example: create repositories and services
+
+```ts
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  createJsonFileStore,
+  createModelService,
+  createOpencodeRepository,
+  createSwitchRepository,
+  createVendorService,
+} from 'opencode-switch-cli';
+
+const homeDir = os.homedir();
+const configDir = path.join(homeDir, '.config', 'opencode');
+const jsonStore = createJsonFileStore();
+
+const opencodeRepository = createOpencodeRepository({
+  filePath: path.join(configDir, 'opencode.json'),
+  jsonStore,
+});
+
+const switchRepository = createSwitchRepository({
+  filePath: path.join(configDir, 'opencode-switch.json'),
+  jsonStore,
+});
+
+const vendorService = createVendorService({
+  opencodeRepository,
+  switchRepository,
+});
+
+const modelService = createModelService({
+  opencodeRepository,
+  switchRepository,
+});
+
+await vendorService.addVendor({
+  vendorName: 'duck',
+  npm: '@ai-sdk/openai-compatible',
+  baseURL: 'https://duck.example.com/v1',
+});
+
+await modelService.addModel({
+  vendorName: 'duck',
+  modelType: 'gpt-5.4',
+  realModel: 'duck/gpt-5.4',
+});
+```
+
+### Example: execute the CLI programmatically
+
+```ts
+import { executeCli } from 'opencode-switch-cli';
+
+const result = await executeCli(['vendor', 'list']);
+
+console.log(result.exitCode);
+console.log(result.stdout);
+console.error(result.stderr);
+```
+
+## Local development
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Run the CLI in development mode:
+
+```bash
+npm run dev -- vendor list
+```
+
+Run verification:
+
+```bash
+npm test
+npm run typecheck
+npm run build
+```
+
+## Publishing to npm
+
+The package is already configured with a `prepublishOnly` script:
+
+```bash
+npm run test && npm run typecheck && npm run build
+```
+
+When you are ready to release:
+
+```bash
+npm login
+npm version patch
+npm publish
+```
+
+If this is the first release for the package name, make sure the package name is available and that you are logged into the correct npm account before publishing.
+
+## License
+
+MIT

package/dist/bin.d.mts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+
+export {  }