@ekzs/cli 0.3.3 → 0.3.5

package/README.md

@@ -1,43 +1,59 @@
 # @ekzs/cli
 
+**Version:** 0.3.5
+
 **Ekz** is a local coding agent for e-Kwanza Pagamento Integrado v2.4 — like Claude Code, but specialized for `@ekzs/connect`, GPO, EMIS ref, and Ticket integrations.
 
-Runs **in your repo** with Composer 2.5 Fast. Edits files directly.
+Runs **in your repo**. Edits files directly in **agent** or **plan** mode. You bring your own LLM key (BYOK) — Cursor, OpenAI, Anthropic, DeepSeek, and more.
 
 ## Install
 
 ```bash
 npm install -g @ekzs/cli
+ekz setup
 ```
 
-Clean install (~15 packages) — BYOK with OpenAI, Anthropic, DeepSeek, etc. Keys via `ekz providers`.
-
-**Cursor provider only** (optional — pulls native deps + npm deprecation noise from `@cursor/sdk`):
-
-```bash
-npm install -g @cursor/sdk
-```
+Clean install (~15 packages). Keys are configured locally via `ekz setup` or `ekz providers` — never committed to git.
 
-Or install both at once:
+**Cursor:** if you pick Cursor during `ekz setup`, Ekz checks for `@cursor/sdk` **before** asking for your API key and offers to run `npm install -g @cursor/sdk` for you. You can also install it yourself beforehand:
 
 ```bash
 npm install -g @ekzs/cli @cursor/sdk
 ```
 
-## Setup (BYOK)
+Other providers (OpenAI, Anthropic, etc.) need no extra packages.
 
-First run:
+## First run — `ekz setup`
 
 ```bash
 ekz setup
 # aliases: ekz configurar · ekz 设置
 ```
 
-Wizard steps: **language** → **your name** → **Configurar provedor** (or offline).
+Wizard steps:
+
+1. **Language** — Português · English · 中文  
+2. **Your name** — shown on the splash screen  
+3. **Provider or offline** — configure one LLM key, or skip to doctor/scan-only mode  
+
+When you configure a provider:
 
-Stored in `~/.ekz/config.json` (name, locale) and `~/.ekz/providers.json` (API keys).
+- Pick from the **numbered provider list**
+- **Cursor only:** Ekz checks for `@cursor/sdk` and offers to install it **before** the API key step
+- Paste your **API key**
+- Pick a **model from a predefined list** (Enter = default)  
+- Setup **finishes and exits** — then run `ekz` to start the agent  
 
-Without a provider, `ekz` shows:
+No base URL prompts — endpoints are predefined per provider.
+
+Stored in:
+
+| File | Contents |
+|------|----------|
+| `~/.ekz/config.json` | locale, name, offline flag, setup complete |
+| `~/.ekz/providers.json` | active provider, API keys, models (mode `600`) |
+
+Without setup or a provider, `ekz` shows:
 
 ```
 Setup required · Configuração necessária · 需要设置
@@ -47,78 +63,78 @@ Setup required · Configuração necessária · 需要设置
   zh: 运行 `ekz setup` 或 `ekz --offline`
 ```
 
-Supported providers: **Cursor**, **OpenAI**, **Anthropic**, **DeepSeek**, **Kimi**, **Groq**, **Mistral**, **Google Gemini**, **Ollama**.
-
-| Mode | BYOK behavior |
-|------|----------------|
-| `agent` | Cursor → local SDK; others → tool loop (read/write/run) |
-| `plan` | Same, plan-first instructions |
-| `ask` | Chat only (Cursor uses lightweight Cursor agent) |
-
-**Localized commands:** `ekz provedores` / `/provedores` (PT) · `ekz 供应商` / `/供应商` (ZH)
+### Supported providers
 
-Optional: `--api-key crsr_...` for a one-off Cursor override in agent/plan mode.
+| Provider | Example models |
+|----------|----------------|
+| **Cursor** | Requires `@cursor/sdk` (offered during setup) · `composer-2.5-fast`, `gpt-5.3-codex`, … |
+| **OpenAI** | `gpt-4o`, `gpt-4o-mini`, `o1`, `o3-mini`, … |
+| **Anthropic** | `claude-sonnet-4-20250514`, `claude-opus-4-20250514`, … |
+| **DeepSeek** | `deepseek-chat`, `deepseek-reasoner` |
+| **Kimi (Moonshot)** | `moonshot-v1-8k`, `moonshot-v1-32k`, … |
+| **Groq** | `llama-3.3-70b-versatile`, … |
+| **Mistral** | `mistral-large-latest`, `codestral-latest`, … |
+| **Google Gemini** | `gemini-2.0-flash`, `gemini-1.5-pro`, … |
+| **Ollama** | `llama3.2`, `qwen2.5`, … (local) |
 
-### Run from this repo
+Manage keys anytime:
 
 ```bash
-npm run build:cli
-
-# Option A — wrapper (no global install)
-./ekz                          # Git Bash / macOS / Linux
-.\ekz                          # PowerShell / cmd (resolves to ekz.cmd)
-npx ekz                        # any shell, from repo root
-
-# Option B — npm script
-npm run ekz                    # interactive REPL
-npm run ekz -- agent "fix webhook"
-
-# Option C — global command (once)
-npm run setup:cli              # build + npm link
-ekz                            # works everywhere
+ekz providers          # full menu — configure, switch, remove
+ekz provedores         # PT
+ekz 供应商              # ZH
 ```
 
-### Windows / PowerShell
+In the REPL: `/providers`, `/provedores`, `/供应商`
 
-From the repo root (after `npm run build:cli`):
+### Modes
 
-```powershell
-.\ekz                          # same as ekz.cmd — no extension needed
-npx ekz                        # works in PowerShell, cmd, Git Bash
-npm run setup:cli              # then `ekz` works globally
-```
+| Mode | Aliases | Behavior |
+|------|---------|----------|
+| **agent** | default, `agente`, `代理` | Edits files and runs commands |
+| **plan** | `plano`, `计划` | Plans before editing |
+| **ask** | `perguntar`, `问答`, `chat` | Q&A only — no file edits |
 
-Shell type is **detected at launch** (Cursor terminal settings, Git Bash, or Windows default PowerShell) and injected into every agent turn. Override with `EKZ_AGENT_SHELL=powershell|bash|cmd` if needed.
-
-When testing HTTP yourself in PowerShell, use `curl.exe -s "http://localhost:3000/..."` — bare `curl` is an alias for `Invoke-WebRequest` and will prompt for `Uri:`.
+| Mode | BYOK routing |
+|------|----------------|
+| **agent / plan** | Cursor → `@cursor/sdk`; others → tool loop (`read_file`, `write_file`, `run_command`) |
+| **ask** | Chat API (Cursor uses lightweight Cursor agent) |
 
-Prefer built-in CLI helpers over manual curls: `ekz doctor`, `ekz health`, `ekz webhook <url>`.
+Optional one-off override: `--api-key crsr_...` in agent/plan mode.
 
 ## Commands
 
 | Command | Description |
 |---------|-------------|
-| `ekz` / `ekz agent` | Interactive REPL (default mode: agent) |
+| `ekz setup` | First-run wizard — language, name, provider or offline |
+| `ekz` / `ekz agent` | Interactive REPL (default: agent mode) |
 | `ekz --mode plan` | Plan before editing files |
 | `ekz --mode ask` | BYOK Q&A, no file edits |
+| `ekz --offline` | Doctor/scan answers only — no LLM |
 | `ekz agent "fix webhook"` | One-shot task with file edits |
 | `ekz fix` | Full integration audit + auto-fix pass |
 | `ekz ask "…"` | BYOK Q&A only |
 | `ekz ask -i` | Interactive ask REPL |
-| `ekz providers` | Configure LLM API keys (BYOK) |
+| `ekz providers` | Manage LLM API keys (BYOK) |
 | `ekz agent --resume` | Continue last session (`.ekz/session.json`) |
-| `ekz doctor` | Env + OAuth health (free) |
-| `ekz health` | OAuth + rail health (free) |
-| `ekz scan` | Lint common mistakes (free) |
-| `ekz webhook <url>` | POST sample webhook (free) |
+| `ekz doctor` | Env + credential checks (**free**) |
+| `ekz health` | OAuth + rail health (**free**) |
+| `ekz scan` | Lint common integration mistakes (**free**) |
+| `ekz webhook <url>` | POST sample webhook (**free**) |
 
 ### REPL shortcuts
 
-Type `/help` in the REPL for the full list (modes, CLI commands, flags). Also: `/providers`, `/mode agent|plan|ask`, `/doctor`, `/scan`, `/lang pt|en|zh`, `/save`, `/resume`.
+Type `/help` in the REPL for the full list. Also:
+
+`/providers` · `/mode agent|plan|ask` · `/doctor` · `/scan` · `/lang pt|en|zh` · `/save` · `/resume`
 
 ## Examples
 
 ```bash
+# First time
+ekz setup
+ekz
+
 # Interactive — stay in your project and iterate
 ekz agent
 
@@ -130,19 +146,55 @@ ekz fix "Ticket webhook returns 401 on x-signature"
 
 # Plan before editing
 ekz --mode plan "Add emis_ref rail to checkout"
-# or shorthand:
-ekz agent --plan "Add emis_ref rail to checkout"
 
 # Ask mode (no local edits)
 ekz --mode ask "What env vars am I missing for Ticket?"
 
+# Free checks before touching the agent
+ekz doctor
+ekz scan
+ekz webhook http://localhost:3000/api/webhooks/ekwanza
+
 # Resume yesterday's session
 ekz agent --resume
 ```
 
 ## Billing
 
-You bring your own keys (BYOK). Usage bills through **your** provider account (Cursor, OpenAI, Anthropic, etc.). Free commands: `doctor`, `health`, `scan`, `webhook`.
+**BYOK only** — usage bills through your provider account (Cursor, OpenAI, Anthropic, etc.). Ekz does not resell LLM credits.
+
+Free commands (no API key): `doctor`, `health`, `scan`, `webhook`.
+
+## Run from this repo
+
+```bash
+npm run build:cli
+
+# Option A — wrapper (no global install)
+./ekz                          # Git Bash / macOS / Linux
+.\ekz                          # PowerShell / cmd
+npx ekz                        # any shell, from repo root
+
+# Option B — npm script
+npm run ekz
+npm run ekz -- agent "fix webhook"
+
+# Option C — global command
+npm run setup:cli              # build + npm link
+ekz
+```
+
+### Windows / PowerShell
+
+```powershell
+.\ekz                          # resolves to ekz.cmd
+npx ekz
+npm run setup:cli              # then `ekz` works globally
+```
+
+Shell type is detected at launch and injected into agent turns. Override with `EKZ_AGENT_SHELL=powershell|bash|cmd`.
+
+In PowerShell, use `curl.exe` for manual HTTP tests — bare `curl` is an alias for `Invoke-WebRequest`. Prefer `ekz doctor`, `ekz health`, `ekz webhook <url>`.
 
 ## Session file
 
@@ -150,35 +202,42 @@ You bring your own keys (BYOK). Usage bills through **your** provider account (C
 
 ## Agent skills
 
-Ekz ships a skill pack under `packages/cli/skills/` (orchestrator + architecture sub-skills). On build, skills sync to `.cursor/skills/` so Cursor picks them up locally.
+15 skills under `packages/cli/skills/`. On build, they sync to `.cursor/skills/` for local Cursor use.
 
 | Skill | Use when |
 |-------|----------|
-| `ekz-connect` | Orchestrator — always loaded |
-| `ekz-payment-core-architecture` | Payment primitives, state machines, ledger, idempotency |
-| `ekz-ekwanza-provider-adapter` | e-Kwanza auth, config, GPO, EMIS ref, Ticket API |
-| `ekz-webhook-normalization` | Callback normalization, x-signature, dedupe, routing |
-| `ekz-one-time-product-payments` | Products, orders, invoices, checkout links, fulfillment |
-| `ekz-ticket-invite-selling` | Reservations, invite/ticket issuance, QR/code ownership |
-| `ekz-subscription-billing` | Recurring one-time payment requests, grace, entitlements |
-| `ekz-overage-billing` | Metered usage, overage charges, settlement |
-| `ekz-integration-playbook` | Adapting payment patterns into any existing codebase |
+| `ekz-connect` | Orchestrator — SDK entry points |
+| `ekz-payment-core-architecture` | Primitives, state machines, idempotency |
+| `ekz-ekwanza-provider-adapter` | Auth, config, GPO, EMIS ref, Ticket API |
+| `ekz-webhook-normalization` | Callbacks, x-signature, dedupe, routing |
+| `ekz-one-time-product-payments` | Products, checkout links, fulfillment |
+| `ekz-ticket-invite-selling` | Reservations, invite/ticket issuance |
+| `ekz-subscription-billing` | Recurring payments, grace, entitlements |
+| `ekz-overage-billing` | Metered usage, overage charges |
+| `ekz-integration-playbook` | Adapting patterns into existing codebases |
 | `ekz-sdk-cli` | `@ekzs/connect`, `ekz doctor`, CLI |
+| `ekz-data-layer-design` | Store abstraction choices |
+| `ekz-data-postgres` | Supabase / Postgres |
+| `ekz-data-mysql` | MySQL |
+| `ekz-data-sqlite` | SQLite |
+| `ekz-data-mongo` | MongoDB |
 
 ```bash
-npm run sync:skills --prefix packages/cli   # copy to .cursor/skills/
+npm run sync:skills --prefix packages/cli
 ```
 
-The local agent loads project skills via `settingSources: ["project"]` and injects task-relevant skills into the prompt.
+## Language
 
-### Language
+Default replies: **Portuguese (Angola)**. Switch in the REPL with `/lang pt`, `/lang en`, `/lang zh`, or start with `ekz --lang en`.
 
-Default replies are in **Portuguese (Angola)**. Switch anytime in the REPL:
+## Publish (maintainers)
 
+```bash
+npm run build:cli
+npm run publish:cli
 ```
-/lang pt
-/lang en
-/ajuda
-```
 
-Or set `EKZ_LANG=pt` in `.env.local`, or start with `./ekz --lang en`.
+## Related
+
+- [`@ekzs/connect`](../sdk/README.md) — TypeScript SDK for v2.4  
+- [Full report](../../docs/EKZ-CONNECT-FULL-REPORT.md) — product + agent reference  

package/dist/index.js

@@ -13,6 +13,7 @@ import { runScan } from "./commands/scan.js";
 import { runProvidersCommand } from "./commands/providers.js";
 import { runSetupCommand } from "./commands/setup.js";
 import { runWebhookTest } from "./commands/webhook.js";
+import { packageVersion } from "./lib/version.js";
 const SUBCOMMANDS = new Set([
     "doctor",
     "health",
@@ -40,7 +41,7 @@ const program = new Command();
 program
     .name("ekz")
     .description("EKZ CONNECT — e-Kwanza v2.4 coding agent by Alberto Moisés")
-    .version("0.3.0");
+    .version(packageVersion());
 program
     .command("doctor")
     .description("Validate .env and run live credential checks (free)")

package/dist/lib/onboarding.js

@@ -5,7 +5,7 @@ import { parseLocale } from "./locale.js";
 import { formatSetupRequiredMessage } from "./setup-messages.js";
 import { info, ok } from "./output.js";
 import { ProviderSetupError, resolveActiveCredentials, resolveCredentialsWithOverride, } from "./providers/credentials.js";
-import { runProvidersInteractive } from "./providers/ui.js";
+import { runSetupProviderWizard } from "./providers/ui.js";
 import { c, muted } from "./theme.js";
 function t(locale, pt, en, zh) {
     if (locale === "pt")
@@ -80,8 +80,8 @@ async function providerStep(locale) {
         return "offline";
     }
     if (choice === "1" || choice === "p" || choice === "providers" || choice === "provedores" || choice === "供应商") {
-        await runProvidersInteractive(locale);
-        if (resolveActiveCredentials()) {
+        const configured = await runSetupProviderWizard(locale);
+        if (configured && resolveActiveCredentials()) {
             clearGlobalOffline();
             ok(t(locale, "Provedor configurado.", "Provider configured.", "Provider 已配置。"));
             return "configured";

package/dist/lib/providers/catalog.d.ts

@@ -5,11 +5,16 @@ export type ProviderDefinition = {
     name: string;
     kind: ProviderKind;
     description: string;
+    /** Default model when user presses Enter */
     defaultModel: string;
+    /** Predefined API base — never shown in UI */
     defaultBaseUrl?: string;
+    /** Selectable models in setup / providers menu */
+    models: string[];
     keyHint: string;
     docsUrl: string;
 };
 export declare const PROVIDER_CATALOG: ProviderDefinition[];
 export declare function getProviderDefinition(id: string): ProviderDefinition | undefined;
+export declare function resolveProviderModel(def: ProviderDefinition, storedModel?: string): string;
 //# sourceMappingURL=catalog.d.ts.map

package/dist/lib/providers/catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../src/lib/providers/catalog.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,mBAAmB,GAAG,WAAW,CAAC;AAExE,MAAM,MAAM,UAAU,GAClB,QAAQ,GACR,QAAQ,GACR,WAAW,GACX,UAAU,GACV,MAAM,GACN,MAAM,GACN,SAAS,GACT,QAAQ,GACR,QAAQ,CAAC;AAEb,MAAM,MAAM,kBAAkB,GAAG;IAC/B,EAAE,EAAE,UAAU,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,kBAAkB,EAyFhD,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAEhF"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../src/lib/providers/catalog.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,mBAAmB,GAAG,WAAW,CAAC;AAExE,MAAM,MAAM,UAAU,GAClB,QAAQ,GACR,QAAQ,GACR,WAAW,GACX,UAAU,GACV,MAAM,GACN,MAAM,GACN,SAAS,GACT,QAAQ,GACR,QAAQ,CAAC;AAEb,MAAM,MAAM,kBAAkB,GAAG;IAC/B,EAAE,EAAE,UAAU,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,kBAAkB,EAkHhD,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAEhF;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,kBAAkB,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAK1F"}

package/dist/lib/providers/catalog.js

@@ -5,6 +5,19 @@ export const PROVIDER_CATALOG = [
         kind: "cursor",
         description: "Composer local agent (@cursor/sdk)",
         defaultModel: "composer-2.5-fast",
+        models: [
+            "composer-2.5-fast",
+            "composer-2-fast",
+            "composer-2.5",
+            "composer-2",
+            "claude-4.6-sonnet-medium-thinking",
+            "claude-opus-4-7-thinking-xhigh",
+            "gemini-3-flash",
+            "gemini-3.1-pro",
+            "gpt-5.3-codex",
+            "gpt-5.5-medium",
+            "kimi-k2.5",
+        ],
         keyHint: "crsr_…",
         docsUrl: "https://cursor.com/dashboard/integrations",
     },
@@ -15,6 +28,7 @@ export const PROVIDER_CATALOG = [
         description: "GPT-4o, o-series",
         defaultModel: "gpt-4o",
         defaultBaseUrl: "https://api.openai.com/v1",
+        models: ["gpt-4o", "gpt-4o-mini", "gpt-4.1", "gpt-4.1-mini", "o1", "o1-mini", "o3-mini"],
         keyHint: "sk-…",
         docsUrl: "https://platform.openai.com/api-keys",
     },
@@ -24,6 +38,11 @@ export const PROVIDER_CATALOG = [
         kind: "anthropic",
         description: "Claude Sonnet / Opus",
         defaultModel: "claude-sonnet-4-20250514",
+        models: [
+            "claude-sonnet-4-20250514",
+            "claude-opus-4-20250514",
+            "claude-3-5-haiku-20241022",
+        ],
         keyHint: "sk-ant-…",
         docsUrl: "https://console.anthropic.com/settings/keys",
     },
@@ -34,6 +53,7 @@ export const PROVIDER_CATALOG = [
         description: "DeepSeek Chat / Reasoner",
         defaultModel: "deepseek-chat",
         defaultBaseUrl: "https://api.deepseek.com",
+        models: ["deepseek-chat", "deepseek-reasoner"],
         keyHint: "sk-…",
         docsUrl: "https://platform.deepseek.com/api_keys",
     },
@@ -44,6 +64,7 @@ export const PROVIDER_CATALOG = [
         description: "Moonshot AI",
         defaultModel: "moonshot-v1-8k",
         defaultBaseUrl: "https://api.moonshot.cn/v1",
+        models: ["moonshot-v1-8k", "moonshot-v1-32k", "moonshot-v1-128k"],
         keyHint: "sk-…",
         docsUrl: "https://platform.moonshot.cn/console/api-keys",
     },
@@ -54,6 +75,7 @@ export const PROVIDER_CATALOG = [
         description: "Fast inference",
         defaultModel: "llama-3.3-70b-versatile",
         defaultBaseUrl: "https://api.groq.com/openai/v1",
+        models: ["llama-3.3-70b-versatile", "llama-3.1-8b-instant", "mixtral-8x7b-32768"],
         keyHint: "gsk_…",
         docsUrl: "https://console.groq.com/keys",
     },
@@ -64,6 +86,7 @@ export const PROVIDER_CATALOG = [
         description: "Mistral Large",
         defaultModel: "mistral-large-latest",
         defaultBaseUrl: "https://api.mistral.ai/v1",
+        models: ["mistral-large-latest", "mistral-small-latest", "codestral-latest"],
         keyHint: "…",
         docsUrl: "https://console.mistral.ai/api-keys",
     },
@@ -71,9 +94,10 @@ export const PROVIDER_CATALOG = [
         id: "google",
         name: "Google Gemini",
         kind: "openai-compatible",
-        description: "Gemini via OpenAI-compatible endpoint",
+        description: "Gemini models",
         defaultModel: "gemini-2.0-flash",
         defaultBaseUrl: "https://generativelanguage.googleapis.com/v1beta/openai",
+        models: ["gemini-2.0-flash", "gemini-2.0-flash-lite", "gemini-1.5-pro", "gemini-1.5-flash"],
         keyHint: "AI…",
         docsUrl: "https://aistudio.google.com/apikey",
     },
@@ -84,6 +108,7 @@ export const PROVIDER_CATALOG = [
         description: "Local models",
         defaultModel: "llama3.2",
         defaultBaseUrl: "http://127.0.0.1:11434/v1",
+        models: ["llama3.2", "llama3.1", "qwen2.5", "mistral", "deepseek-r1"],
         keyHint: "ollama (optional)",
         docsUrl: "https://ollama.com",
     },
@@ -91,3 +116,11 @@ export const PROVIDER_CATALOG = [
 export function getProviderDefinition(id) {
     return PROVIDER_CATALOG.find((p) => p.id === id);
 }
+export function resolveProviderModel(def, storedModel) {
+    const trimmed = storedModel?.trim();
+    if (trimmed && def.models.includes(trimmed))
+        return trimmed;
+    if (trimmed && !def.models.includes(trimmed))
+        return trimmed;
+    return def.defaultModel;
+}

package/dist/lib/providers/cursor-sdk.d.ts

@@ -3,6 +3,13 @@ export declare class CursorSdkMissingError extends Error {
     constructor(locale?: EkzLocale);
 }
 type CursorSdkModule = typeof import("@cursor/sdk");
+export declare function clearCursorSdkCache(): void;
+export declare function probeCursorSdk(): Promise<boolean>;
 export declare function loadCursorSdk(locale?: EkzLocale): Promise<CursorSdkModule>;
+/**
+ * Before Cursor API key entry: ensure @cursor/sdk is installed.
+ * Offers to run `npm install -g @cursor/sdk` when missing.
+ */
+export declare function ensureCursorSdkReady(locale: EkzLocale): Promise<boolean>;
 export type { SDKAgent } from "@cursor/sdk";
 //# sourceMappingURL=cursor-sdk.d.ts.map

package/dist/lib/providers/cursor-sdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cursor-sdk.d.ts","sourceRoot":"","sources":["../../../src/lib/providers/cursor-sdk.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,MAAM,GAAE,SAAgB;CAWrC;AAED,KAAK,eAAe,GAAG,cAAc,aAAa,CAAC,CAAC;AAIpD,wBAAsB,aAAa,CAAC,MAAM,GAAE,SAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAQtF;AAED,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"cursor-sdk.d.ts","sourceRoot":"","sources":["../../../src/lib/providers/cursor-sdk.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAI9C,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,MAAM,GAAE,SAAgB;CAWrC;AAED,KAAK,eAAe,GAAG,cAAc,aAAa,CAAC,CAAC;AAoBpD,wBAAgB,mBAAmB,SAElC;AAED,wBAAsB,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC,CAOvD;AAED,wBAAsB,aAAa,CAAC,MAAM,GAAE,SAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAQtF;AAcD;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAwE9E;AAED,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC"}

package/dist/lib/providers/cursor-sdk.js

@@ -1,4 +1,8 @@
+import { spawn } from "child_process";
+import readline from "readline";
 import { providersCommandLabels } from "../commands-i18n.js";
+import { info, ok, warn } from "../output.js";
+import { muted } from "../theme.js";
 export class CursorSdkMissingError extends Error {
     constructor(locale = "en") {
         const p = providersCommandLabels(locale);
@@ -12,6 +16,34 @@ export class CursorSdkMissingError extends Error {
     }
 }
 let cached = null;
+function t(locale, pt, en, zh) {
+    if (locale === "pt")
+        return pt;
+    if (locale === "zh")
+        return zh;
+    return en;
+}
+async function askLine(prompt) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(prompt, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+export function clearCursorSdkCache() {
+    cached = null;
+}
+export async function probeCursorSdk() {
+    try {
+        await import("@cursor/sdk");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export async function loadCursorSdk(locale = "en") {
     if (cached)
         return cached;
@@ -23,3 +55,42 @@ export async function loadCursorSdk(locale = "en") {
         throw new CursorSdkMissingError(locale);
     }
 }
+async function runNpmInstallGlobal(packageName) {
+    const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+    return new Promise((resolve) => {
+        const child = spawn(npm, ["install", "-g", packageName], {
+            stdio: "inherit",
+            shell: process.platform === "win32",
+        });
+        child.on("error", () => resolve(false));
+        child.on("close", (code) => resolve(code === 0));
+    });
+}
+/**
+ * Before Cursor API key entry: ensure @cursor/sdk is installed.
+ * Offers to run `npm install -g @cursor/sdk` when missing.
+ */
+export async function ensureCursorSdkReady(locale) {
+    clearCursorSdkCache();
+    if (await probeCursorSdk()) {
+        return true;
+    }
+    console.log("");
+    info(t(locale, "Cursor usa o pacote @cursor/sdk para correr o agente local.", "Cursor uses @cursor/sdk to run the local agent.", "Cursor 使用 @cursor/sdk 运行本地 agent。"));
+    console.log(`  ${muted("npm install -g @cursor/sdk")}`);
+    console.log("");
+    const answer = await askLine(t(locale, "  Instalar agora? [Y/n]: ", "  Install now? [Y/n]: ", "  现在安装? [Y/n]: "));
+    if (answer && !["y", "yes", "s", "sim", "是", ""].includes(answer.toLowerCase())) {
+        warn(t(locale, "Instalação cancelada — escolhe outro provider ou corre npm install -g @cursor/sdk.", "Install skipped — pick another provider or run npm install -g @cursor/sdk.", "已跳过安装 — 请选择其他 provider 或运行 npm install -g @cursor/sdk。"));
+        return false;
+    }
+    info(t(locale, "A instalar @cursor/sdk…", "Installing @cursor/sdk…", "正在安装 @cursor/sdk…"));
+    const installed = await runNpmInstallGlobal("@cursor/sdk");
+    clearCursorSdkCache();
+    if (!installed || !(await probeCursorSdk())) {
+        warn(t(locale, "Instalação falhou. Tenta manualmente: npm install -g @cursor/sdk", "Install failed. Try manually: npm install -g @cursor/sdk", "安装失败。请手动运行: npm install -g @cursor/sdk"));
+        return false;
+    }
+    ok(t(locale, "@cursor/sdk instalado.", "@cursor/sdk installed.", "@cursor/sdk 已安装。"));
+    return true;
+}

package/dist/lib/providers/store.d.ts

@@ -17,5 +17,5 @@ export declare function setStoredProvider(id: ProviderId, entry: StoredProvider)
 export declare function removeStoredProvider(id: ProviderId): void;
 export declare function setActiveProvider(id: ProviderId): void;
 export declare function resolveModel(id: ProviderId, stored?: StoredProvider): string;
-export declare function resolveBaseUrl(id: ProviderId, stored?: StoredProvider): string | undefined;
+export declare function resolveBaseUrl(id: ProviderId, _stored?: StoredProvider): string | undefined;
 //# sourceMappingURL=store.d.ts.map

package/dist/lib/providers/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/lib/providers/store.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,UAAU,EAAyB,MAAM,cAAc,CAAC;AAGtE,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC;CACxD,CAAC;AAWF,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,wBAAgB,iBAAiB,IAAI,aAAa,CAcjD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,QAQpD;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI9C;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,UAAU,GAAG,cAAc,GAAG,SAAS,CAE5E;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,cAAc,QAOtE;AAED,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,UAAU,QAOlD;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,UAAU,QAO/C;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,MAAM,CAG5E;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAG1F"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/lib/providers/store.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,UAAU,EAAyB,MAAM,cAAc,CAAC;AAGtE,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC;CACxD,CAAC;AAWF,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,wBAAgB,iBAAiB,IAAI,aAAa,CAcjD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,QAQpD;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI9C;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,UAAU,GAAG,cAAc,GAAG,SAAS,CAE5E;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,cAAc,QAQtE;AAED,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,UAAU,QAOlD;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,UAAU,QAO/C;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,MAAM,CAM5E;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAE3F"}

package/dist/lib/providers/store.js

@@ -50,9 +50,9 @@ export function getStoredProvider(id) {
 }
 export function setStoredProvider(id, entry) {
     const file = loadProvidersFile();
-    file.providers[id] = entry;
-    if (!file.active)
-        file.active = id;
+    const { baseUrl: _ignored, ...rest } = entry;
+    file.providers[id] = rest;
+    file.active = id;
     saveProvidersFile(file);
     clearGlobalOffline();
     markSetupComplete();
@@ -75,10 +75,13 @@ export function setActiveProvider(id) {
 }
 export function resolveModel(id, stored) {
     const def = getProviderDefinition(id);
-    return stored?.model?.trim() || def?.defaultModel || "gpt-4o";
+    if (!def)
+        return stored?.model?.trim() || "gpt-4o";
+    const trimmed = stored?.model?.trim();
+    if (trimmed)
+        return trimmed;
+    return def.defaultModel;
 }
-export function resolveBaseUrl(id, stored) {
-    if (stored?.baseUrl?.trim())
-        return stored.baseUrl.trim();
+export function resolveBaseUrl(id, _stored) {
     return getProviderDefinition(id)?.defaultBaseUrl;
 }

package/dist/lib/providers/ui.d.ts

@@ -1,4 +1,6 @@
 import { type EkzLocale } from "../locale.js";
+/** One-shot provider pick + configure — used by `ekz setup`. */
+export declare function runSetupProviderWizard(locale?: EkzLocale): Promise<boolean>;
 export declare function runProvidersInteractive(locale?: EkzLocale): Promise<void>;
 export declare function formatActiveProviderLabel(locale: EkzLocale): string;
 //# sourceMappingURL=ui.d.ts.map

package/dist/lib/providers/ui.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../../src/lib/providers/ui.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AA+L9C,wBAAsB,uBAAuB,CAAC,MAAM,GAAE,SAAgB,iBAuDrE;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAMnE"}
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../../src/lib/providers/ui.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AA2N9C,gEAAgE;AAChE,wBAAsB,sBAAsB,CAAC,MAAM,GAAE,SAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAoBvF;AAED,wBAAsB,uBAAuB,CAAC,MAAM,GAAE,SAAgB,iBAuDrE;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAMnE"}

package/dist/lib/providers/ui.js

@@ -5,6 +5,7 @@ import { askWithPlaceholder, formatInputPrompt } from "../ui/prompt.js";
 import { PROVIDER_CATALOG, getProviderDefinition } from "./catalog.js";
 import { listProviderRows, resolveActiveCredentials, } from "./credentials.js";
 import { maskApiKey, providersFilePath, removeStoredProvider, setActiveProvider, setStoredProvider, } from "./store.js";
+import { ensureCursorSdkReady } from "./cursor-sdk.js";
 function providersTitle(locale) {
     if (locale === "pt")
         return "Provedores (BYOK)";
@@ -88,41 +89,67 @@ function printProviderList(rows, locale) {
     console.log(`  ${muted(t(locale, "[número] configurar · u usar · r remover · q sair", "[number] configure · u use · r remove · q quit", "[数字] 配置 · u 使用 · r 删除 · q 退出"))}`);
     console.log("");
 }
+function printCatalogPicker(locale) {
+    console.log("");
+    console.log(`  ${c.bold}${t(locale, "Escolhe o provedor", "Choose provider", "选择 provider")}${c.reset}`);
+    console.log("");
+    PROVIDER_CATALOG.forEach((def, index) => {
+        console.log(`  ${c.bold}${String(index + 1).padStart(2)}.${c.reset} ${def.name.padEnd(16)} ${muted(def.description)}`);
+    });
+    console.log("");
+}
+async function pickModel(id, locale) {
+    const def = getProviderDefinition(id);
+    if (!def)
+        return null;
+    const defaultIndex = Math.max(0, def.models.findIndex((m) => m === def.defaultModel));
+    const defaultNum = defaultIndex + 1;
+    console.log("");
+    console.log(`  ${c.bold}${t(locale, "Modelo", "Model", "模型")}${c.reset}`);
+    def.models.forEach((model, index) => {
+        const n = index + 1;
+        const tag = model === def.defaultModel
+            ? muted(t(locale, " · predefinição", " · default", " · 默认"))
+            : "";
+        console.log(`  ${c.bold}${String(n).padStart(2)}.${c.reset} ${model}${tag}`);
+    });
+    console.log("");
+    const prompt = t(locale, `  Escolha [${defaultNum}]: `, `  Choice [${defaultNum}]: `, `  选择 [${defaultNum}]: `);
+    const choice = await askLine(prompt);
+    if (!choice)
+        return def.defaultModel;
+    const num = Number(choice);
+    if (Number.isInteger(num) && num >= 1 && num <= def.models.length) {
+        return def.models[num - 1];
+    }
+    warn(t(locale, "Opção inválida — a usar predefinição.", "Invalid choice — using default.", "无效选项 — 使用默认。"));
+    return def.defaultModel;
+}
 async function configureProvider(id, locale) {
     const def = getProviderDefinition(id);
     if (!def)
-        return;
+        return false;
     console.log("");
     console.log(`  ${c.bold}${def.name}${c.reset} — ${muted(def.description)}`);
     console.log(`  ${muted(def.docsUrl)}`);
     console.log("");
+    if (id === "cursor") {
+        const sdkReady = await ensureCursorSdkReady(locale);
+        if (!sdkReady)
+            return false;
+    }
     const keyPrompt = t(locale, `Cola a API key (${def.keyHint}): `, `Paste API key (${def.keyHint}): `, `粘贴 API key (${def.keyHint}): `);
     const apiKey = await askLine(keyPrompt, true);
     if (!apiKey) {
         warn(t(locale, "Chave vazia — cancelado.", "Empty key — cancelled.", "密钥为空，已取消。"));
-        return;
-    }
-    const modelDefault = def.defaultModel;
-    const modelPrompt = t(locale, `Modelo [${modelDefault}]: `, `Model [${modelDefault}]: `, `模型 [${modelDefault}]: `);
-    const modelInput = await askLine(modelPrompt);
-    const model = modelInput || modelDefault;
-    let baseUrl;
-    if (def.kind === "openai-compatible" || def.defaultBaseUrl) {
-        const urlPrompt = t(locale, `Base URL [${def.defaultBaseUrl ?? "(default)"}]: `, `Base URL [${def.defaultBaseUrl ?? "(default)"}]: `, `Base URL [${def.defaultBaseUrl ?? "(default)"}]: `);
-        const urlInput = await askLine(urlPrompt);
-        if (urlInput)
-            baseUrl = urlInput;
-    }
-    setStoredProvider(id, { apiKey, model, baseUrl });
-    ok(t(locale, `Guardado ${def.name} (${maskApiKey(apiKey)})`, `Saved ${def.name} (${maskApiKey(apiKey)})`, `已保存 ${def.name} (${maskApiKey(apiKey)})`));
-    const active = resolveActiveCredentials();
-    if (!active || active.id !== id) {
-        const useNow = await askLine(t(locale, "Usar como provider activo? [Y/n]: ", "Use as active provider? [Y/n]: ", "设为当前 provider? [Y/n]: "), false);
-        if (!useNow || useNow.toLowerCase() === "y" || useNow.toLowerCase() === "s" || useNow === "") {
-            setActiveProvider(id);
-            ok(t(locale, `${def.name} activo.`, `${def.name} is now active.`, `${def.name} 已激活。`));
-        }
+        return false;
     }
+    const model = await pickModel(id, locale);
+    if (!model)
+        return false;
+    setStoredProvider(id, { apiKey, model });
+    ok(t(locale, `Guardado ${def.name} · ${model} (${maskApiKey(apiKey)})`, `Saved ${def.name} · ${model} (${maskApiKey(apiKey)})`, `已保存 ${def.name} · ${model} (${maskApiKey(apiKey)})`));
+    return true;
 }
 function resolveRowTarget(rows, target) {
     const trimmed = target.trim().toLowerCase();
@@ -132,6 +159,21 @@ function resolveRowTarget(rows, target) {
     }
     return rows.find((r) => r.definition.id === trimmed);
 }
+/** One-shot provider pick + configure — used by `ekz setup`. */
+export async function runSetupProviderWizard(locale = "pt") {
+    printCatalogPicker(locale);
+    const prompt = t(locale, "  Número do provedor (Enter cancelar): ", "  Provider number (Enter to cancel): ", "  Provider 编号 (Enter 取消): ");
+    const choice = (await askLine(prompt)).trim();
+    if (!choice)
+        return false;
+    const num = Number(choice);
+    if (!Number.isInteger(num) || num < 1 || num > PROVIDER_CATALOG.length) {
+        warn(t(locale, "Opção inválida.", "Invalid option.", "无效选项。"));
+        return false;
+    }
+    const def = PROVIDER_CATALOG[num - 1];
+    return configureProvider(def.id, locale);
+}
 export async function runProvidersInteractive(locale = "pt") {
     while (true) {
         const rows = listProviderRows();
@@ -184,5 +226,5 @@ export function formatActiveProviderLabel(locale) {
     if (!creds) {
         return t(locale, "sem provider", "no provider", "未配置");
     }
-    return `${creds.definition.name} · ${creds.maskedKey}`;
+    return `${creds.definition.name} · ${creds.model} · ${creds.maskedKey}`;
 }

package/dist/lib/version.d.ts

@@ -0,0 +1,2 @@
+export declare function packageVersion(): string;
+//# sourceMappingURL=version.d.ts.map

package/dist/lib/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/lib/version.ts"],"names":[],"mappings":"AAMA,wBAAgB,cAAc,IAAI,MAAM,CASvC"}

package/dist/lib/version.js

@@ -0,0 +1,13 @@
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+const here = dirname(fileURLToPath(import.meta.url));
+export function packageVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(join(here, "../../package.json"), "utf8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekzs/cli",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "CLI agent for e-Kwanza v2.4 — health checks, code scan, webhook tests, AI assistance",
   "type": "module",
   "bin": {