@ekzs/cli 0.2.0 → 0.3.3

package/README.md

@@ -8,19 +8,56 @@ Runs **in your repo** with Composer 2.5 Fast. Edits files directly.
 
 ```bash
 npm install -g @ekzs/cli
-# or from this monorepo:
-npm run build --prefix packages/cli
 ```
 
-## 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
+```
+
+Or install both at once:
 
 ```bash
-export CURSOR_API_KEY=crsr_...   # https://cursor.com/dashboard/integrations
-# or add CURSOR_API_KEY to .env.local in your project
-export EKZ_AGENT_MODEL=composer-2.5-fast   # optional; maps to fast param
+npm install -g @ekzs/cli @cursor/sdk
 ```
 
-Loads `.env.local` / `.env` from your project automatically.
+## Setup (BYOK)
+
+First run:
+
+```bash
+ekz setup
+# aliases: ekz configurar · ekz 设置
+```
+
+Wizard steps: **language** → **your name** → **Configurar provedor** (or offline).
+
+Stored in `~/.ekz/config.json` (name, locale) and `~/.ekz/providers.json` (API keys).
+
+Without a provider, `ekz` shows:
+
+```
+Setup required · Configuração necessária · 需要设置
+
+  pt: Corre `ekz setup` ou `ekz --offline`
+  en: Run `ekz setup` or `ekz --offline`
+  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)
+
+Optional: `--api-key crsr_...` for a one-off Cursor override in agent/plan mode.
 
 ### Run from this repo
 
@@ -63,11 +100,12 @@ Prefer built-in CLI helpers over manual curls: `ekz doctor`, `ekz health`, `ekz
 |---------|-------------|
 | `ekz` / `ekz agent` | Interactive REPL (default mode: agent) |
 | `ekz --mode plan` | Plan before editing files |
-| `ekz --mode ask` | Remote Q&A, no file edits |
+| `ekz --mode ask` | BYOK Q&A, no file edits |
 | `ekz agent "fix webhook"` | One-shot task with file edits |
 | `ekz fix` | Full integration audit + auto-fix pass |
-| `ekz ask "…"` | Remote Q&A only (Ekz Connect API) |
+| `ekz ask "…"` | BYOK Q&A only |
 | `ekz ask -i` | Interactive ask REPL |
+| `ekz providers` | Configure 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) |
@@ -76,7 +114,7 @@ Prefer built-in CLI helpers over manual curls: `ekz doctor`, `ekz health`, `ekz
 
 ### REPL shortcuts
 
-Type `/help` in the REPL for the full list (modes, CLI commands, flags). Also: `/mode agent|plan|ask`, `/doctor`, `/scan`, `/lang pt|en|zh`, `/save`, `/resume`.
+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`.
 
 ## Examples
 
@@ -104,9 +142,7 @@ ekz agent --resume
 
 ## Billing
 
-Local agent runs bill through your **Cursor account** (Composer usage). Free commands: `doctor`, `health`, `scan`, `webhook`.
-
-Remote `ekz ask` uses **EKZ_AGENT_API_KEY** credits on Ekz Connect.
+You bring your own keys (BYOK). Usage bills through **your** provider account (Cursor, OpenAI, Anthropic, etc.). Free commands: `doctor`, `health`, `scan`, `webhook`.
 
 ## Session file
 

package/dist/commands/agent.d.ts

@@ -4,8 +4,6 @@ export declare function runAgentCommand(opts: {
     cwd: string;
     question?: string;
     apiKey?: string;
-    askApiKey?: string;
-    askApiUrl?: string;
     askOffline?: boolean;
     resume?: boolean;
     fresh?: boolean;
@@ -17,8 +15,6 @@ export declare function runAgentCommand(opts: {
 export declare function runFixCommand(opts: {
     cwd: string;
     apiKey?: string;
-    askApiKey?: string;
-    askApiUrl?: string;
     askOffline?: boolean;
     resume?: boolean;
     fresh?: boolean;

package/dist/commands/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/commands/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAK3C,OAAO,EAAE,eAAe,EAAE,CAAC;AAE3B,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,iBAiCA;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,iBAmBA"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/commands/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAK3C,OAAO,EAAE,eAAe,EAAE,CAAC;AAE3B,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,iBA6BA;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,iBAiBA"}

package/dist/commands/agent.js

@@ -8,8 +8,6 @@ export async function runAgentCommand(opts) {
         await runInteractiveAgent({
             cwd: opts.cwd,
             apiKey: opts.apiKey,
-            askApiKey: opts.askApiKey,
-            askApiUrl: opts.askApiUrl,
             askOffline: opts.askOffline,
             resume: opts.resume,
             fresh: opts.fresh,
@@ -23,8 +21,6 @@ export async function runAgentCommand(opts) {
         cwd: opts.cwd,
         task: opts.question.trim(),
         apiKey: opts.apiKey,
-        askApiKey: opts.askApiKey,
-        askApiUrl: opts.askApiUrl,
         askOffline: opts.askOffline,
         resume: opts.resume,
         fresh: opts.fresh,
@@ -42,8 +38,6 @@ export async function runFixCommand(opts) {
         cwd: opts.cwd,
         task,
         apiKey: opts.apiKey,
-        askApiKey: opts.askApiKey,
-        askApiUrl: opts.askApiUrl,
         askOffline: opts.askOffline,
         resume: opts.resume,
         fresh: opts.fresh,

package/dist/commands/ask.d.ts

@@ -1,19 +1,17 @@
+import { type EkzLocale } from "../lib/locale.js";
 export type AskOptions = {
     cwd: string;
     question: string;
-    apiKey?: string;
-    apiUrl?: string;
     offline?: boolean;
     quiet?: boolean;
+    locale?: EkzLocale;
 };
-/** Remote Q&A via Ekz Connect API (no local edits). */
+/** Q&A via BYOK provider (no local file edits). */
 export declare function executeAskTurn(options: AskOptions): Promise<boolean>;
 export declare function runAsk(options: Omit<AskOptions, "quiet">): Promise<void>;
 export declare function runInteractiveAsk(opts: {
     cwd: string;
     locale?: string;
-    apiKey?: string;
-    apiUrl?: string;
     offline?: boolean;
 }): Promise<void>;
 export declare function resolveQuestion(arg?: string): Promise<string | undefined>;

package/dist/commands/ask.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../src/commands/ask.ts"],"names":[],"mappings":"AAkCA,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,uDAAuD;AACvD,wBAAsB,cAAc,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CA2C1E;AAED,wBAAsB,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,iBAK9D;AAgDD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,iBAuDA;AAED,wBAAsB,eAAe,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAM/E"}
+{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../src/commands/ask.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,SAAS,EAA0B,MAAM,kBAAkB,CAAC;AAyC1E,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB,CAAC;AAEF,mDAAmD;AACnD,wBAAsB,cAAc,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CA0B1E;AAED,wBAAsB,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,iBAO9D;AAgDD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,iBAwEA;AAED,wBAAsB,eAAe,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAM/E"}

package/dist/commands/ask.js

@@ -1,14 +1,19 @@
 import { printHelp, printWelcome } from "../lib/banner.js";
-import { resolveReplMetaCommand } from "../lib/commands-i18n.js";
+import { isProvidersMetaCommand, providersCommandLabels, resolveReplMetaCommand } from "../lib/commands-i18n.js";
 import { buildBootstrapContext } from "../lib/context.js";
 import { parseLocale, uiStrings } from "../lib/locale.js";
 import { parseMode } from "../lib/mode.js";
 import { fail, heading, info, ok } from "../lib/output.js";
 import { loadPreferences, savePreferences } from "../lib/preferences.js";
+import { ensureAgentReady, offlineModelLabel } from "../lib/onboarding.js";
+import { executeByokAskTurn } from "../lib/providers/chat.js";
+import { executeCursorAskTurn } from "../lib/providers/cursor-runner.js";
+import { isCursorProvider, requireActiveCredentials, ProviderSetupError, } from "../lib/providers/credentials.js";
+import { runProvidersInteractive } from "../lib/providers/ui.js";
 import { redactText } from "../lib/redact.js";
 import { askWithPlaceholder, formatInputPrompt } from "../lib/ui/prompt.js";
 import { inputPlaceholder } from "../lib/ui/splash.js";
-function deterministicAnswer(question, ctx) {
+function deterministicAnswer(question, ctx, locale) {
     const lines = ["## Ekz assistant (offline)", "", question, ""];
     if (ctx.doctor.issues.length) {
         lines.push("### Issues", ...ctx.doctor.issues.map((i) => `- ${i}`), "");
@@ -16,48 +21,41 @@ function deterministicAnswer(question, ctx) {
     if (ctx.scan.length) {
         lines.push("### Scan", ...ctx.scan.slice(0, 8).map((f) => `- \`${f.file}:${f.line}\` · ${f.message}`), "");
     }
-    lines.push("### Next steps", "- Set EKZ_AGENT_API_KEY for remote answers", "- Or run `ekz --mode agent` for local file edits");
+    lines.push("### Next steps", "- Run `ekz setup` to configure language, name, and provider", "- Or `ekz --offline` for doctor/scan only");
     return lines.join("\n");
 }
-/** Remote Q&A via Ekz Connect API (no local edits). */
+/** Q&A via BYOK provider (no local file edits). */
 export async function executeAskTurn(options) {
-    const { cwd, question, apiKey, apiUrl, offline, quiet } = options;
-    const ctx = await buildBootstrapContext(cwd);
-    const key = apiKey ?? process.env.EKZ_AGENT_API_KEY;
-    const baseUrl = apiUrl ?? process.env.EKZ_AGENT_API_URL ?? process.env.EKZ_CONNECT_URL ?? "http://localhost:3000";
-    if (offline || !key) {
+    const { cwd, question, offline, quiet, locale = "pt" } = options;
+    if (offline) {
+        const ctx = await buildBootstrapContext(cwd);
         if (!quiet)
             info("Ask mode (offline) · no file edits.\n");
-        console.log("\n" + deterministicAnswer(question, ctx));
+        console.log("\n" + deterministicAnswer(question, ctx, locale));
         return true;
     }
-    const res = await fetch(`${baseUrl.replace(/\/$/, "")}/api/developers/agent`, {
-        method: "POST",
-        headers: {
-            "Content-Type": "application/json",
-            Authorization: `Bearer ${key}`,
-        },
-        body: JSON.stringify({
-            question,
-            context: { doctor: ctx.doctor, scan: ctx.scan, env: ctx.env },
-        }),
-    });
-    const data = (await res.json().catch(() => ({})));
-    if (!res.ok) {
-        fail(data.error ?? `API error (${res.status})`);
-        return false;
+    let creds;
+    try {
+        creds = requireActiveCredentials(locale);
+    }
+    catch (err) {
+        if (err instanceof ProviderSetupError) {
+            fail(err.message);
+            return false;
+        }
+        throw err;
     }
-    if (!quiet)
-        ok(`${data.mode ?? "online"}${data.model ? ` · ${data.model}` : ""}`);
-    if (data.creditsRemaining !== undefined)
-        info(`Credits: ${data.creditsRemaining}`);
-    console.log("\n" + (data.answer ?? ""));
-    return true;
+    if (isCursorProvider(creds)) {
+        return executeCursorAskTurn({ cwd, question, creds, locale });
+    }
+    return executeByokAskTurn({ cwd, question, locale, creds, quiet });
 }
 export async function runAsk(options) {
+    const locale = options.locale ?? "pt";
+    const p = providersCommandLabels(locale);
     heading("Ekz ask");
-    info("Remote Q&A mode · no file edits. Use `ekz --mode agent` for local fixes.\n");
-    const okResult = await executeAskTurn({ ...options, quiet: false });
+    info(`BYOK Q&A · configure keys with \`${p.cli}\` or \`${p.repl}\`.\n`);
+    const okResult = await executeAskTurn({ ...options, quiet: false, locale });
     if (!okResult)
         process.exitCode = 1;
 }
@@ -96,10 +94,23 @@ function handleAskMeta(line, locale) {
 export async function runInteractiveAsk(opts) {
     const prefs = loadPreferences(opts.cwd, opts.locale, "ask");
     let currentLocale = prefs.locale;
+    let askOffline = Boolean(opts.offline);
+    try {
+        const ready = await ensureAgentReady({
+            locale: currentLocale,
+            offlineFlag: opts.offline,
+        });
+        askOffline = ready.offline || askOffline;
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+        return;
+    }
     printWelcome({
         cwd: opts.cwd,
         locale: currentLocale,
         mode: "ask",
+        model: askOffline ? offlineModelLabel(currentLocale) : undefined,
     });
     let turn = 0;
     while (true) {
@@ -109,6 +120,10 @@ export async function runInteractiveAsk(opts) {
         })).trim();
         if (!line)
             continue;
+        if (isProvidersMetaCommand(line.trim().split(/\s+/)[0] ?? "")) {
+            await runProvidersInteractive(currentLocale);
+            continue;
+        }
         const meta = handleAskMeta(line, currentLocale);
         if (meta?.kind === "handled")
             continue;
@@ -132,10 +147,9 @@ export async function runInteractiveAsk(opts) {
         await executeAskTurn({
             cwd: opts.cwd,
             question: line,
-            apiKey: opts.apiKey,
-            apiUrl: opts.apiUrl,
-            offline: opts.offline,
+            offline: askOffline,
             quiet: true,
+            locale: currentLocale,
         });
         console.log("");
         turn++;

package/dist/commands/local-agent.d.ts

@@ -3,8 +3,6 @@ export type LocalAgentOptions = {
     cwd: string;
     task: string;
     apiKey?: string;
-    askApiKey?: string;
-    askApiUrl?: string;
     askOffline?: boolean;
     resume?: boolean;
     fresh?: boolean;

package/dist/commands/local-agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-agent.d.ts","sourceRoot":"","sources":["../../src/commands/local-agent.ts"],"names":[],"mappings":"AAWA,OAAO,EAAsC,KAAK,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAalF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAkOF,wBAAsB,aAAa,CAAC,IAAI,EAAE,iBAAiB,iBAuF1D;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,IAAI,CAAC,iBAAiB,EAAE,MAAM,GAAG,aAAa,CAAC,iBA4D9F"}
+{"version":3,"file":"local-agent.d.ts","sourceRoot":"","sources":["../../src/commands/local-agent.ts"],"names":[],"mappings":"AAWA,OAAO,EAAsC,KAAK,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAsBlF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AA2PF,wBAAsB,aAAa,CAAC,IAAI,EAAE,iBAAiB,iBA0I1D;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,IAAI,CAAC,iBAAiB,EAAE,MAAM,GAAG,aAAa,CAAC,iBAmG9F"}