@mimikkai/opencode-mimikkai-connect 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shatyuka
+
+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,128 @@
+# MimikkAi Connect for OpenCode
+
+OpenCode plugin for MimikkAi — device authorization flow + LiteLLM gateway integration.
+
+## Prerequisites
+
+- [OpenCode](https://opencode.ai) installed
+- [Bun](https://bun.sh) for building
+- A MimikkAi account (register at [panel.mimikkai.ru](https://panel.mimikkai.ru))
+
+## Installation
+
+```shell
+bun install
+bun run build
+```
+
+## Configuration
+
+Add the plugin to your `opencode.json`:
+
+```json
+{
+  "plugin": ["opencode-mimikkai-connect"]
+}
+```
+
+## Authentication Flow
+
+```
+User runs `opencode auth login`
+         │
+         ▼
+┌─────────────────────────────┐
+│  Device Authorization      │
+│  POST /api/auth/device/     │
+│  authorize                  │
+└────────────┬────────────────┘
+             │
+             ▼
+    Browser opens:
+    panel.mimikkai.ru/device?code=AB12-CD34
+             │
+             ▼
+┌─────────────────────────────┐
+│  Poll for token             │
+│  POST /api/auth/device/     │
+│  token (every 5s)           │
+│  202 → pending              │
+│  200 → { token, user }      │
+└────────────┬────────────────┘
+             │
+             ▼
+┌─────────────────────────────┐
+│  Fetch LiteLLM virtual key  │
+│  GraphQL → userViewer       │
+│  → litellmVirtualKey (sk-)  │
+└────────────┬────────────────┘
+             │
+             ▼
+┌─────────────────────────────┐
+│  Save to storage            │
+│  ~/.config/opencode/        │
+│  mimikkai.json              │
+└────────────┬────────────────┘
+             │
+             ▼
+┌─────────────────────────────┐
+│  Register provider + models │
+│  @ai-sdk/openai-compatible  │
+│  → litellm.mimikkai.ru/v1   │
+│  → /model/info              │
+└─────────────────────────────┘
+```
+
+## Usage
+
+1. Run `opencode auth login` and select **Device Authorization**
+2. A browser opens — confirm the displayed code
+3. The plugin fetches your LiteLLM virtual key and syncs available models
+4. Select a MimikkAi model in OpenCode's model picker
+
+## Architecture
+
+```
+src/
+├── constants.ts    ← Mimikkai endpoints (service, panel, litellm)
+├── mimikkai.ts     ← API client (device auth, GraphQL, /model/info)
+├── storage.ts      ← Token storage (~/.config/opencode/mimikkai.json)
+├── logger.ts       ← Configurable structured logging (LOG_LEVEL env)
+├── index.ts        ← Plugin entry (auth hook + config hook + dispose)
+└── test/
+    ├── mimikkai.test.ts   ← API client tests (24 tests)
+    └── storage.test.ts    ← Storage tests (8 tests)
+```
+
+### Key Design Decisions
+
+- **Sanctum token → LiteLLM key exchange**: The Sanctum token (`1|abc...`) from auth is exchanged for a LiteLLM virtual key (`sk-...`) via GraphQL. Only the `sk-` key is used for API requests.
+- **Key refresh on every config hook**: The `config` hook re-fetches the LiteLLM key on each invocation using the stored Sanctum token, falling back to the cached key if the refresh fails.
+- **Token validation on startup**: The `loader` validates the Sanctum token via `userViewer` GraphQL query before using the stored LiteLLM key.
+- **Far-future expiry**: The OAuth callback returns a 1-year expiry since Sanctum tokens don't have a known short TTL.
+
+## Troubleshooting
+
+### "LiteLLM virtual key is missing or masked"
+
+The backend returned a masked key (containing `...`). This happens when the key hasn't been fully provisioned. Try logging out and back in:
+
+```shell
+rm ~/.config/opencode/mimikkai.json
+opencode auth login
+```
+
+### No models appear
+
+The plugin couldn't fetch models from `litellm.mimikkai.ru/model/info`. Check:
+1. Your LiteLLM key is valid (`sk-` prefix)
+2. Network connectivity to `litellm.mimikkai.ru`
+3. Set `LOG_LEVEL=debug` for verbose logging
+
+### Token expired
+
+If the Sanctum token expires, the `loader` will detect it and return empty, forcing re-authentication. Run `opencode auth login` again.
+
+## License
+
+MIT License.