@ekzs/cli 0.2.0

package/dist/commands/local-agent.js

@@ -0,0 +1,450 @@
+import { resolve } from "path";
+import { Agent, AgentBusyError, CursorAgentError } from "@cursor/sdk";
+import { executeAskTurn } from "../commands/ask.js";
+import { runDoctor } from "../commands/doctor.js";
+import { runScan } from "../commands/scan.js";
+import { inputPlaceholder, printHelp, printLangSwitch, printModeSwitch, printWelcome } from "../lib/banner.js";
+import { loadProjectEnv } from "../lib/env.js";
+import { resolveReplMetaCommand } from "../lib/commands-i18n.js";
+import { buildAgentPrompt, buildBootstrapContext } from "../lib/context.js";
+import { resolveComposerModel } from "../lib/composer-model.js";
+import { parseLocale, uiStrings } from "../lib/locale.js";
+import { modeRequiresCursorAgent, parseMode } from "../lib/mode.js";
+import { loadPreferences, savePreferences } from "../lib/preferences.js";
+import { clearSession, getSessionByIndex, loadSession, persistSession, saveNamedSession, } from "../lib/session.js";
+import { fail, info, ok, warn } from "../lib/output.js";
+import { toolDone, toolError, toolRunning, turnDivider } from "../lib/theme.js";
+import { askWithPlaceholder, formatInputPrompt } from "../lib/ui/prompt.js";
+function getApiKey(override, cwd) {
+    if (cwd)
+        loadProjectEnv(cwd);
+    else
+        loadProjectEnv(process.cwd());
+    const key = override ?? process.env.CURSOR_API_KEY?.trim();
+    if (!key) {
+        throw new Error("CURSOR_API_KEY required. Add it to .env.local or export it — https://cursor.com/dashboard/integrations");
+    }
+    return key;
+}
+async function disposeAgent(agent) {
+    const disposer = agent[Symbol.asyncDispose];
+    if (typeof disposer === "function")
+        await disposer.call(agent);
+    else
+        agent.close();
+}
+async function streamRun(agent, prompt, locale, opts) {
+    const t = uiStrings(locale);
+    const sendOptions = {
+        onDelta: ({ update }) => {
+            if (update.type === "text-delta" && update.text) {
+                process.stdout.write(update.text);
+            }
+        },
+        ...(opts?.force ? { local: { force: true } } : {}),
+    };
+    let run;
+    try {
+        run = await agent.send(prompt, sendOptions);
+    }
+    catch (err) {
+        if (err instanceof AgentBusyError) {
+            warn(t.busyRun);
+            run = await agent.send(prompt, { ...sendOptions, local: { force: true } });
+        }
+        else {
+            throw err;
+        }
+    }
+    for await (const event of run.stream()) {
+        if (event.type === "tool_call" && event.status === "running") {
+            process.stdout.write(toolRunning(event.name));
+        }
+        if (event.type === "tool_call" && event.status === "completed") {
+            process.stdout.write(toolDone(event.name));
+        }
+        if (event.type === "tool_call" && event.status === "error") {
+            process.stdout.write(toolError(event.name));
+        }
+    }
+    const result = await run.wait();
+    if (result.status === "error") {
+        fail(`${t.agentFailed} (${result.id})`);
+        process.exitCode = 2;
+    }
+    return { status: result.status, result: result.result };
+}
+async function createOrResumeAgent(opts) {
+    const cwd = resolve(opts.cwd);
+    const apiKey = getApiKey(opts.apiKey, cwd);
+    const model = resolveComposerModel();
+    const usePlan = opts.mode === "plan" || Boolean(opts.plan);
+    if (opts.fresh)
+        clearSession(cwd);
+    const agentId = opts.resumeAgentId ??
+        (!opts.fresh && opts.resume ? loadSession(cwd)?.agentId : undefined);
+    if (agentId) {
+        const agent = await Agent.resume(agentId, {
+            apiKey,
+            model: { id: model.id, params: model.params },
+            local: { cwd, settingSources: ["project"] },
+        });
+        return { agent, resumed: true };
+    }
+    const agent = await Agent.create({
+        apiKey,
+        name: "Ekz Connect — e-Kwanza payments only",
+        model: { id: model.id, params: model.params },
+        local: { cwd, settingSources: ["project"] },
+        ...(usePlan ? { mode: "plan" } : {}),
+    });
+    return { agent, resumed: false };
+}
+async function recreateAgentForMode(cwd, current, mode, apiKey) {
+    if (!modeRequiresCursorAgent(mode))
+        return null;
+    if (current)
+        await disposeAgent(current);
+    const { agent } = await createOrResumeAgent({
+        cwd,
+        task: "",
+        fresh: true,
+        mode,
+        apiKey,
+    });
+    await persistAgent(cwd, agent);
+    return agent;
+}
+async function persistAgent(cwd, agent) {
+    const model = resolveComposerModel();
+    persistSession(cwd, {
+        agentId: agent.agentId,
+        cwd: resolve(cwd),
+        model: model.label,
+    });
+}
+function handleMetaCommand(line, locale, cwd, currentMode) {
+    const parts = line.trim().split(/\s+/);
+    const cmd = resolveReplMetaCommand(parts[0] ?? "");
+    if (cmd === "help") {
+        printHelp(locale, currentMode);
+        return { kind: "handled" };
+    }
+    if (cmd === "lang") {
+        const next = parseLocale(parts[1]);
+        if (!next) {
+            warn(uiStrings(locale).langInvalid);
+            return { kind: "handled" };
+        }
+        savePreferences(cwd, { locale: next });
+        printLangSwitch(next);
+        return { kind: "locale", locale: next };
+    }
+    if (cmd === "mode") {
+        const next = parseMode(parts[1]);
+        if (!next) {
+            warn(locale === "pt"
+                ? "Modo inválido. Usa: /mode agent|plan|ask"
+                : locale === "zh"
+                    ? "无效模式。请使用: /mode agent|plan|ask"
+                    : "Invalid mode. Use: /mode agent|plan|ask");
+            return { kind: "handled" };
+        }
+        savePreferences(cwd, { mode: next });
+        return { kind: "mode", mode: next };
+    }
+    if (cmd === "doctor") {
+        void runDoctor(cwd).then(() => console.log(""));
+        return { kind: "handled" };
+    }
+    if (cmd === "scan") {
+        void runScan(cwd).then(() => console.log(""));
+        return { kind: "handled" };
+    }
+    if (cmd === "resume") {
+        const idx = parts[1] ? Number(parts[1]) : 0;
+        const session = idx > 0 ? getSessionByIndex(cwd, idx) : loadSession(cwd);
+        if (!session) {
+            warn(locale === "pt" ? "Nenhuma sessão para retomar." : "No session to resume.");
+            return { kind: "handled" };
+        }
+        return { kind: "resume", agentId: session.agentId, name: session.name };
+    }
+    if (cmd === "save") {
+        const name = parts.slice(1).join(" ").trim();
+        if (!name) {
+            warn(locale === "pt" ? "Usa /guardar <nome>" : locale === "zh" ? "使用 /save <名称>" : "Use /save <name>");
+            return { kind: "handled" };
+        }
+        return { kind: "save", name };
+    }
+    return null;
+}
+async function resumeAgentInRepl(cwd, current, agentId, locale) {
+    if (current)
+        await disposeAgent(current);
+    const apiKey = getApiKey(undefined, cwd);
+    const model = resolveComposerModel();
+    const agent = await Agent.resume(agentId, {
+        apiKey,
+        model: { id: model.id, params: model.params },
+        local: { cwd: resolve(cwd), settingSources: ["project"] },
+    });
+    await persistAgent(cwd, agent);
+    ok(locale === "pt" ? "Sessão retomada." : "Session resumed.");
+    return agent;
+}
+export async function runLocalAgent(opts) {
+    const cwd = resolve(opts.cwd);
+    loadProjectEnv(cwd);
+    const model = resolveComposerModel();
+    const prefs = loadPreferences(cwd, opts.locale, opts.mode, opts.plan);
+    const mode = prefs.mode;
+    if (mode === "ask") {
+        printWelcome({ cwd, locale: prefs.locale, mode: "ask" });
+        if (opts.task.trim()) {
+            info(`${uiStrings(prefs.locale).workingOn}: ${opts.task.slice(0, 120)}${opts.task.length > 120 ? "…" : ""}\n`);
+            await executeAskTurn({
+                cwd,
+                question: opts.task.trim(),
+                apiKey: opts.askApiKey,
+                apiUrl: opts.askApiUrl,
+                offline: opts.askOffline,
+                quiet: true,
+            });
+            console.log("");
+        }
+        if (opts.interactive !== false) {
+            await runRepl({
+                agent: null,
+                cwd,
+                locale: prefs.locale,
+                mode: "ask",
+                apiKey: opts.apiKey,
+                askApiKey: opts.askApiKey,
+                askApiUrl: opts.askApiUrl,
+                askOffline: opts.askOffline,
+            });
+        }
+        return;
+    }
+    let agent;
+    let resumed = false;
+    try {
+        ({ agent, resumed } = await createOrResumeAgent({ ...opts, mode }));
+    }
+    catch (err) {
+        if (err instanceof CursorAgentError) {
+            fail(`Agent startup failed: ${err.message}`);
+            process.exitCode = 1;
+            return;
+        }
+        throw err;
+    }
+    printWelcome({
+        cwd,
+        model: model.label,
+        locale: prefs.locale,
+        mode,
+        resumed,
+        agentId: agent.agentId,
+    });
+    await persistAgent(cwd, agent);
+    savePreferences(cwd, { mode });
+    const bootstrap = await buildBootstrapContext(cwd);
+    const prompt = buildAgentPrompt(opts.task, bootstrap, prefs.locale);
+    const t = uiStrings(prefs.locale);
+    try {
+        info(`${t.workingOn}: ${opts.task.slice(0, 120)}${opts.task.length > 120 ? "…" : ""}\n`);
+        const outcome = await streamRun(agent, prompt, prefs.locale);
+        console.log("\n");
+        ok(`${t.done} (${outcome.status})`);
+        if (opts.interactive !== false) {
+            await runRepl({
+                agent,
+                cwd,
+                locale: prefs.locale,
+                mode,
+                apiKey: opts.apiKey,
+                askApiKey: opts.askApiKey,
+                askApiUrl: opts.askApiUrl,
+                askOffline: opts.askOffline,
+            });
+        }
+        else {
+            info(t.resumeHint);
+        }
+    }
+    finally {
+        await disposeAgent(agent);
+    }
+}
+export async function runInteractiveAgent(opts) {
+    const cwd = resolve(opts.cwd);
+    loadProjectEnv(cwd);
+    const model = resolveComposerModel();
+    const prefs = loadPreferences(cwd, opts.locale, opts.mode, opts.plan);
+    const mode = prefs.mode;
+    if (mode === "ask") {
+        printWelcome({ cwd, locale: prefs.locale, mode: "ask" });
+        await runRepl({
+            agent: null,
+            cwd,
+            locale: prefs.locale,
+            mode: "ask",
+            apiKey: opts.apiKey,
+            askApiKey: opts.askApiKey,
+            askApiUrl: opts.askApiUrl,
+            askOffline: opts.askOffline,
+        });
+        return;
+    }
+    let agent;
+    let resumed = false;
+    try {
+        ({ agent, resumed } = await createOrResumeAgent({ ...opts, task: "", mode }));
+    }
+    catch (err) {
+        if (err instanceof CursorAgentError) {
+            fail(`Agent startup failed: ${err.message}`);
+            process.exitCode = 1;
+            return;
+        }
+        throw err;
+    }
+    printWelcome({
+        cwd,
+        model: model.label,
+        locale: prefs.locale,
+        mode,
+        resumed,
+        agentId: agent.agentId,
+    });
+    await persistAgent(cwd, agent);
+    savePreferences(cwd, { mode });
+    try {
+        await runRepl({
+            agent,
+            cwd,
+            locale: prefs.locale,
+            mode,
+            apiKey: opts.apiKey,
+            askApiKey: opts.askApiKey,
+            askApiUrl: opts.askApiUrl,
+            askOffline: opts.askOffline,
+        });
+    }
+    finally {
+        await disposeAgent(agent);
+    }
+}
+async function runRepl(opts) {
+    let currentLocale = opts.locale;
+    let currentMode = opts.mode;
+    let currentAgent = opts.agent;
+    let turn = 0;
+    const t = () => uiStrings(currentLocale);
+    while (true) {
+        const line = (await askWithPlaceholder({
+            prompt: formatInputPrompt(),
+            placeholder: inputPlaceholder(currentLocale, turn),
+        })).trim();
+        if (!line || line === "exit" || line === "quit" || line === "sair" || line === "退出")
+            break;
+        const meta = handleMetaCommand(line, currentLocale, opts.cwd, currentMode);
+        if (meta?.kind === "handled")
+            continue;
+        if (meta?.kind === "locale") {
+            currentLocale = meta.locale;
+            continue;
+        }
+        if (meta?.kind === "mode") {
+            currentMode = meta.mode;
+            printModeSwitch(currentLocale, currentMode);
+            try {
+                if (currentMode === "ask") {
+                    if (currentAgent) {
+                        await disposeAgent(currentAgent);
+                        currentAgent = null;
+                    }
+                }
+                else {
+                    currentAgent = await recreateAgentForMode(opts.cwd, currentAgent, currentMode, opts.apiKey);
+                }
+            }
+            catch (err) {
+                fail(err instanceof Error ? err.message : String(err));
+            }
+            continue;
+        }
+        if (meta?.kind === "resume") {
+            if (currentMode === "ask") {
+                warn(currentLocale === "pt" ? "Sessões Cursor só em modo agent/plan." : "Cursor sessions only in agent/plan mode.");
+                continue;
+            }
+            try {
+                if (!currentAgent) {
+                    fail(currentLocale === "pt" ? "Sem agente activo." : "No active agent.");
+                    continue;
+                }
+                currentAgent = await resumeAgentInRepl(opts.cwd, currentAgent, meta.agentId, currentLocale);
+            }
+            catch (err) {
+                fail(err instanceof Error ? err.message : String(err));
+            }
+            continue;
+        }
+        if (meta?.kind === "save") {
+            if (!currentAgent) {
+                warn(currentLocale === "pt" ? "Guardar sessão só em modo agent/plan." : "Save session only in agent/plan mode.");
+                continue;
+            }
+            const model = resolveComposerModel();
+            saveNamedSession(opts.cwd, {
+                agentId: currentAgent.agentId,
+                cwd: resolve(opts.cwd),
+                model: model.label,
+                name: meta.name,
+            });
+            ok(currentLocale === "pt" ? `Sessão guardada: ${meta.name}` : `Session saved: ${meta.name}`);
+            continue;
+        }
+        console.log("");
+        process.stdout.write(turnDivider());
+        if (currentMode === "ask") {
+            await executeAskTurn({
+                cwd: opts.cwd,
+                question: line,
+                apiKey: opts.askApiKey,
+                apiUrl: opts.askApiUrl,
+                offline: opts.askOffline,
+                quiet: true,
+            });
+            console.log("\n");
+            turn++;
+            continue;
+        }
+        if (!currentAgent) {
+            fail(currentLocale === "pt" ? "Sem agente activo." : "No active agent.");
+            continue;
+        }
+        await persistAgent(opts.cwd, currentAgent);
+        const ctx = await buildBootstrapContext(opts.cwd);
+        const prompt = buildAgentPrompt(line, ctx, currentLocale);
+        try {
+            await streamRun(currentAgent, prompt, currentLocale);
+        }
+        catch (err) {
+            if (err instanceof CursorAgentError) {
+                fail(err.message);
+                turn++;
+                continue;
+            }
+            throw err;
+        }
+        console.log("\n");
+        await persistAgent(opts.cwd, currentAgent);
+        turn++;
+    }
+    ok(t().goodbye);
+}

package/dist/commands/scan.d.ts

@@ -0,0 +1,11 @@
+export type ScanFinding = {
+    file: string;
+    line: number;
+    rule: string;
+    message: string;
+    severity: "error" | "warn";
+};
+export declare function runScan(cwd: string, options?: {
+    quiet?: boolean;
+}): Promise<ScanFinding[]>;
+//# sourceMappingURL=scan.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../src/commands/scan.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;CAC5B,CAAC;AA2EF,wBAAsB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CA6ChG"}

package/dist/commands/scan.js

@@ -0,0 +1,119 @@
+import { readdirSync, readFileSync, statSync } from "fs";
+import { join, relative } from "path";
+import { fail, heading, info, ok, warn } from "../lib/output.js";
+const SKIP_DIRS = new Set([
+    "node_modules",
+    ".git",
+    ".next",
+    "dist",
+    "build",
+    ".turbo",
+    "coverage",
+]);
+const RULES = [
+    {
+        id: "deprecated-rail",
+        pattern: /paymentMethodKind\s*[:=]\s*["']reference["']/,
+        message: 'Use rail "emis_ref" or "ticket" instead of deprecated "reference"',
+        severity: "warn",
+    },
+    {
+        id: "missing-signature",
+        pattern: /operationCode|"code"/,
+        message: "Ticket webhook handler detected — ensure x-signature HMAC is verified",
+        severity: "warn",
+        ignore: /verifyTicketSignature|x-signature|validateTicketSignature/,
+    },
+    {
+        id: "hardcoded-secret",
+        pattern: /EKWANZA_(CLIENT_SECRET|API_KEY)\s*=\s*["'][^"']+["']/,
+        message: "Never hardcode e-Kwanza secrets in source files",
+        severity: "error",
+    },
+    {
+        id: "wrong-prefix-gpo",
+        pattern: /EKWANZA_PAYMENT_METHOD_GPO\s*=\s*["'](?!GPO_)/,
+        message: "GPO payment method should use GPO_ prefix",
+        severity: "warn",
+    },
+    {
+        id: "legacy-webhook-status",
+        pattern: /operationStatus\s*===\s*["']1["']/,
+        message: "operationStatus is numeric (1 = paid), not string",
+        severity: "warn",
+    },
+];
+const EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".py", ".env", ".env.local"]);
+function walk(dir, root, files = []) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return files;
+    }
+    for (const name of entries) {
+        if (SKIP_DIRS.has(name))
+            continue;
+        const full = join(dir, name);
+        try {
+            const st = statSync(full);
+            if (st.isDirectory())
+                walk(full, root, files);
+            else if (EXTENSIONS.has(name.slice(name.lastIndexOf(".")) || name))
+                files.push(full);
+        }
+        catch {
+            /* skip unreadable */
+        }
+    }
+    return files;
+}
+export async function runScan(cwd, options) {
+    if (!options?.quiet)
+        heading("Ekz scan");
+    const files = walk(cwd, cwd);
+    if (!options?.quiet)
+        info(`Scanning ${files.length} files…`);
+    const findings = [];
+    for (const file of files) {
+        let content;
+        try {
+            content = readFileSync(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const rel = relative(cwd, file);
+        const lines = content.split("\n");
+        for (const rule of RULES) {
+            if (rule.ignore && rule.ignore.test(content))
+                continue;
+            lines.forEach((line, i) => {
+                if (rule.pattern.test(line)) {
+                    findings.push({
+                        file: rel,
+                        line: i + 1,
+                        rule: rule.id,
+                        message: rule.message,
+                        severity: rule.severity,
+                    });
+                }
+            });
+        }
+    }
+    if (findings.length === 0) {
+        if (!options?.quiet)
+            ok("No integration issues detected");
+    }
+    else if (!options?.quiet) {
+        for (const f of findings) {
+            const fn = f.severity === "error" ? fail : warn;
+            fn(`${f.file}:${f.line} [${f.rule}] ${f.message}`);
+        }
+        const errors = findings.filter((f) => f.severity === "error").length;
+        if (errors > 0)
+            process.exitCode = 1;
+    }
+    return findings;
+}

package/dist/commands/webhook.d.ts

@@ -0,0 +1,10 @@
+type Rail = "gpo" | "ticket";
+export declare function runWebhookTest(url: string, rail: Rail, asJson: boolean): Promise<{
+    url: string;
+    rail: Rail;
+    status: number;
+    response: unknown;
+    normalized: import("@ekzs/connect").EkzNormalizedWebhook;
+}>;
+export {};
+//# sourceMappingURL=webhook.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../src/commands/webhook.ts"],"names":[],"mappings":"AAOA,KAAK,IAAI,GAAG,KAAK,GAAG,QAAQ,CAAC;AAE7B,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO;;;;;;GA4C5E"}

package/dist/commands/webhook.js

@@ -0,0 +1,42 @@
+import { SAMPLE_GPO_WEBHOOK, SAMPLE_TICKET_WEBHOOK, normalizeWebhookPayload, } from "@ekzs/connect";
+import { heading, info, json, ok } from "../lib/output.js";
+export async function runWebhookTest(url, rail, asJson) {
+    const payload = rail === "gpo" ? SAMPLE_GPO_WEBHOOK : SAMPLE_TICKET_WEBHOOK;
+    heading(`Webhook test → ${url}`);
+    info(`Rail: ${rail}`);
+    const normalized = normalizeWebhookPayload(payload);
+    info(`Normalized locally: status=${normalized.status}, rail=${normalized.rail}`);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(payload),
+        });
+    }
+    catch (err) {
+        throw new Error(`Request failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const text = await response.text();
+    let body = text;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        /* keep text */
+    }
+    const result = {
+        url,
+        rail,
+        status: response.status,
+        response: body,
+        normalized,
+    };
+    if (asJson) {
+        json(result);
+        return result;
+    }
+    ok(`HTTP ${response.status}`);
+    info(typeof body === "string" ? body : JSON.stringify(body));
+    return result;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}