Merge pull request #43 from itsflaid/codex/openrouter-provider

Add OpenRouter as an MVP AI provider

Author: itsflaid

CHANGELOG.md

@@ -12,12 +12,16 @@ All notable changes to DevMap are documented in this file.
 
 ### Added
 
+- OpenRouter provider support with interactive provider selection, API-key
+  validation, streaming responses, and user-selected free or paid models
 - `ts-morph` analysis for JavaScript and TypeScript behind a normalized
   analyzer registry with heuristic and fallback analyzers
 - Lightweight `.devmap/index.json` and per-feature navigation maps for agents
 
 ### Changed
 
+- `devmap init` defaults OpenRouter to `openrouter/free` on Enter and explains
+  how to change the stored model with `devmap config model <model-id>`
 - Feature detection now separates documentation, landing UI, CLI commands,
   analysis, snapshot, and AI roles before assigning technical features
 - Generated agent guidance now uses index-first navigation and treats the full

PRD.md

@@ -265,6 +265,7 @@ Setup wizard. Runs once per machine/project.
 
 - Ask for AI provider
 - Ask for API key
+- Ask for an OpenRouter model, defaulting to `openrouter/free` on Enter
 - Validate API key
 - Save global config to `~/.devmap/config.json`
 - Create `.devmap/` project folder if needed
@@ -459,7 +460,8 @@ JSON mode rules:
 - stdout contains exactly one valid JSON document
 - no ANSI colors, Markdown rendering, box drawing, or progress text
 - runtime errors use a stable `{ "status": "error", "error": "...", "hint": "..." }` shape
-- `init --json` is non-interactive and requires `GROQ_API_KEY` or existing config
+- `init --json` is non-interactive and requires `GROQ_API_KEY`,
+  `OPENROUTER_API_KEY`, or existing config
 - AI responses are buffered instead of streamed
 - human-readable output remains the default
 - package-manager wrappers may still write their own warnings to stderr
@@ -579,16 +581,17 @@ For current project structure, use `.devmap/snapshot.json` if available.
 
 ## 11. AI Strategy
 
-### MVP Provider
+### MVP Providers
 
-**Groq only.**
+**Groq and OpenRouter.**
 
 Reasons:
 
 - Fast inference
 - Accessible globally
 - User provides their own API key
 - No DevMap backend required
+- OpenRouter users can choose any model their account can access
 
 ### Provider Abstraction
 
@@ -631,6 +634,13 @@ Model availability changes over time. Before changing the default routing,
 verify the current Groq model list and lifecycle status. Preview models must
 not be used as a primary default for a public DevMap release.
 
+OpenRouter setup asks for a model ID after validating the API key. Pressing
+Enter selects `openrouter/free`; entering another free or paid model stores
+that exact model as the user's preferred model. Explicit user selections take
+priority and are not replaced by DevMap's Groq routing chain. Users can change
+the selection later with `devmap config model <model-id>`; setting `auto` on
+OpenRouter restores the safe `openrouter/free` default.
+
 ### User API Key Principle
 
 - Users provide their own API keys

README.md

@@ -257,6 +257,11 @@ AI features require a provider API key. DevMap uses Groq by default — analysis
 | OpenAI     | Planned   |
 | Gemini     | Planned   |
 
+`devmap init` lets you choose Groq or OpenRouter with the arrow keys. For
+OpenRouter, pressing Enter at `OpenRouter model [openrouter/free]:` keeps the
+free router; typing another model ID uses that free or paid model instead.
+Change it later with `devmap config model <model-id>`.
+
 API keys are stored locally:
 
 ```txt

docs/architecture.md

@@ -608,9 +608,10 @@ All AI interactions go through a provider abstraction.
 
 Commands should not call provider APIs directly.
 
-### MVP Provider
-
-* Groq
+### MVP Providers
+
+* Groq
+* OpenRouter
 
 ### Future Providers
 
@@ -649,15 +650,21 @@ on 2026-06-20. Recheck provider lifecycle status before publishing a release.
 
 Users can override automatic routing with `devmap config model <model>`.
 Running `devmap config model auto` restores the defaults above.
+
+OpenRouter does not use the Groq command-routing table. During `devmap init`,
+Enter accepts `openrouter/free`, while a typed model ID is stored and used
+exactly as the user selected it. Explicit OpenRouter model choices receive no
+hidden DevMap fallback. The OpenRouter adapter supports the provider's native
+ordered `models` request when a caller explicitly supplies fallbacks.
 
 Raw provider errors should not be shown directly to users.
 
 ---
 
 ## Streaming AI Output
 
-Groq chat completions use server-sent events for human-readable `analyze` and
-`ask` output. The provider adapter reconstructs the complete response while
+Groq and OpenRouter chat completions use server-sent events for human-readable
+`analyze` and `ask` output. Each provider adapter reconstructs the response while
 emitting incremental deltas to the output layer.
 
 Terminal Markdown is buffered to paragraph boundaries before rendering. This

docs/commands.md

@@ -42,10 +42,11 @@ devmap init
 
 ### Responsibilities
 
-* Confirm AI provider
-* Input API key or read environment variable
-* Validate API key
-* Save global configuration to `~/.devmap/config.json`
+* Confirm AI provider
+* Input API key or read environment variable
+* Validate API key
+* Ask for an OpenRouter model; Enter defaults to `openrouter/free`
+* Save global configuration to `~/.devmap/config.json`
 * Detect current project framework
 * Create `.devmap/`
 * Add `.devmap/` to `.gitignore`
@@ -582,6 +583,16 @@ devmap config model auto
 * `analyze` uses `openai/gpt-oss-20b`
 * `analyze --deep` uses `openai/gpt-oss-120b`
 
+For OpenRouter, `devmap init` prompts with:
+
+```txt
+OpenRouter model [openrouter/free]:
+```
+
+Press Enter for the free router, or type any free or paid OpenRouter model ID.
+The typed model is stored as the primary choice and is not silently replaced.
+`devmap config model auto` restores `openrouter/free` for OpenRouter.
+
 Automatic routing also uses ordered fallback chains:
 
 * `ask`: `qwen/qwen3.6-27b`, `llama-3.3-70b-versatile`, then `openai/gpt-oss-20b`
@@ -646,8 +657,8 @@ Contract:
 * progress sections and Markdown rendering are omitted
 * AI responses are buffered instead of streamed
 * runtime failures return a JSON object with `status`, `error`, and optional `hint`
-* `init --json` never prompts and therefore requires `GROQ_API_KEY` or an
-  existing API key
+* `init --json` never prompts and therefore requires `GROQ_API_KEY`,
+  `OPENROUTER_API_KEY`, or an existing API key
 * package-manager wrapper warnings may appear on stderr and are not part of the
   DevMap JSON document
 

docs/for-me-personal/PROGRESS.md

@@ -4,6 +4,21 @@ Terakhir diperbarui: 2026-06-20
 
 ## Update 2026-06-20
 
+### OpenRouter MVP Provider
+
+- `devmap init` sekarang menampilkan selector panah untuk Groq dan OpenRouter.
+- Setup OpenRouter memvalidasi API key lalu meminta model dengan default
+  `openrouter/free` ketika user langsung menekan Enter.
+- Model OpenRouter yang diketik user, baik gratis maupun berbayar, disimpan dan
+  selalu diprioritaskan tanpa hidden fallback dari DevMap.
+- `devmap config model <model-id>` dapat mengganti pilihan; `auto` pada
+  OpenRouter kembali ke `openrouter/free`.
+- `ask`, `analyze`, dan `doctor` sekarang memakai provider factory berdasarkan
+  config, bukan membuat Groq client secara langsung.
+- OpenRouter completion, streaming SSE, usage normalization, validasi key, dan
+  native ordered `models` request sudah memiliki regression tests.
+- Focused tests dan full CLI unit suite lulus dengan 116 test.
+
 ### Standalone React Detection
 
 - Framework detector sekarang mengenali standalone React dari dependency

docs/for-me-personal/TEST.md

@@ -15,6 +15,43 @@ Ada beberapa versi DevMap yang dapat diuji:
 | npm link | CLI global sementara | Menguji command `devmap` dari folder mana pun |
 | CI/runtime | OS dan versi Node berbeda | Verifikasi lintas platform sebelum release |
 
+## OpenRouter Provider
+
+Focused automated tests:
+
+```powershell
+pnpm --filter devmap exec tsx --test test/init-and-errors.test.ts test/openrouter-client.test.ts test/doctor.test.ts
+```
+
+Manual source test sebaiknya dijalankan dari project fixture atau project luar,
+karena `init` menulis `.devmap/`, `DEVMAP.md`, dan kemungkinan `AGENTS.md`:
+
+```powershell
+pnpm dev:cli -- init
+```
+
+Expected interactive flow:
+
+1. Pilih `OpenRouter` dengan tombol panah lalu tekan Enter.
+2. Masukkan OpenRouter API key; key tidak boleh dicetak ulang.
+3. Pada `OpenRouter model [openrouter/free]:`, tekan Enter untuk free router
+   atau ketik model ID gratis/berbayar yang ingin diuji.
+4. Pastikan output menjelaskan command
+   `devmap config model <model-id>` untuk mengganti model nanti.
+5. Jalankan `devmap doctor`, `devmap analyze`, dan `devmap ask` lalu pastikan
+   provider serta model yang tampil sesuai config.
+
+Non-interactive setup dapat memakai:
+
+```powershell
+$env:OPENROUTER_API_KEY="your-key"
+pnpm dev:cli -- init --json
+Remove-Item Env:OPENROUTER_API_KEY
+```
+
+Jangan simpan atau menyalin API key nyata ke repository, snapshot, output test,
+atau dokumentasi debugging.
+
 ## Ts-Morph Dan Agent Navigation
 
 Focused tests:

docs/roadmap.md

@@ -33,7 +33,7 @@ adding AI on top. If the foundation is wrong, AI output will be wrong too.
 **Goal:** Users can understand projects faster with AI interpretation.
 
 **Tasks:**
-- Groq integration with provider abstraction layer
+- Groq and OpenRouter integration through the provider abstraction layer
 - Prompt templates for analyze and ask
 - Context Builder — keyword search + file ranking
 - [x] Streaming output for human `analyze` and `ask` responses
@@ -87,12 +87,12 @@ accuracy must be near 100% or developers won't trust it.
 ---
 
 ## Phase 5 — Multi-Provider
-**Goal:** Users can choose their preferred AI provider.
+**Goal:** Expand beyond the Groq and OpenRouter MVP providers.
 
 **Tasks:**
 - OpenAI adapter (GPT-4o mini as default)
 - Gemini adapter (1.5 Flash as default)
-- Provider selection in `devmap init`
+- [x] Provider selection in `devmap init` for Groq and OpenRouter
 - Per-project provider override in `.devmap/config.json`
 - Provider-specific model recommendations
 

packages/cli/README.md

@@ -2,7 +2,7 @@
 
 Understand any codebase in minutes, not days.
 
-DevMap is a CLI that combines static analysis with optional Groq-powered
+DevMap is a CLI that combines static analysis with optional AI-powered
 interpretation. It maps project structure, generates reusable context, and
 answers focused questions without sending an entire repository to an AI model.
 
@@ -23,7 +23,7 @@ npx devmap --help
 ## Requirements
 
 - Node.js 18 or newer
-- A Groq API key for AI-powered analysis and answers
+- A Groq or OpenRouter API key for AI-powered analysis and answers
 
 Static analysis still works when AI is not configured.
 
@@ -39,18 +39,30 @@ devmap onboarding
 devmap doctor
 ```
 
-`devmap init` validates the Groq key, stores configuration locally, prepares
+`devmap init` selects a provider, validates its key, stores configuration locally, prepares
 `.devmap/`, generates `DEVMAP.md`, and integrates with `AGENTS.md` safely.
 
-## Groq Setup
+## AI Provider Setup
 
-Create a key at https://console.groq.com/keys, then either enter it during:
+Choose Groq or OpenRouter with the arrow keys during:
 
 ```bash
 devmap init
 ```
 
-Or provide it to the current shell before non-interactive setup:
+Groq keys are available at https://console.groq.com/keys. OpenRouter keys are
+available at https://openrouter.ai/keys.
+
+For OpenRouter, DevMap prompts:
+
+```txt
+OpenRouter model [openrouter/free]:
+```
+
+Press Enter to use the free router, or type any free or paid OpenRouter model
+ID. The selected model is saved and used as the primary choice.
+
+For non-interactive Groq setup:
 
 ```bash
 GROQ_API_KEY="your-key" devmap init
@@ -64,8 +76,15 @@ devmap init
 Remove-Item Env:GROQ_API_KEY
 ```
 
+For non-interactive OpenRouter setup:
+
+```bash
+OPENROUTER_API_KEY="your-key" devmap init
+```
+
 The key is stored locally in `~/.devmap/config.json`. Requests go directly from
-your machine to Groq. DevMap does not send the key to a DevMap-owned server.
+your machine to the selected provider. DevMap does not send the key to a
+DevMap-owned server.
 
 ## Commands
 
@@ -81,11 +100,12 @@ devmap doctor
 devmap config model auto
 ```
 
-Automatic model routing uses a fast model for focused questions and larger
-models for architecture analysis. Override it with:
+Groq automatic routing uses a fast model for focused questions and larger
+models for architecture analysis. OpenRouter uses the model selected during
+init. Change either provider's model with:
 
 ```bash
-devmap config model <groq-model-id>
+devmap config model <model-id>
 devmap config model auto
 ```
 
@@ -131,7 +151,7 @@ support promise.
 ## Privacy
 
 - Project analysis runs locally before AI interpretation.
-- Full repository source is not sent to Groq.
+- Full repository source is not sent to the selected provider.
 - `ask` selects a small set of relevant files.
 - `.env` files and common generated directories are ignored.
 - API keys are stored locally and should never be committed.

packages/cli/package.json

@@ -30,7 +30,8 @@
     "developer-tools",
     "static-analysis",
     "architecture",
-    "groq"
+    "groq",
+    "openrouter"
   ],
   "author": "Muhammad Fadil",
   "license": "MIT",