@ayoxx/kundex 0.1.7

package/README.md

@@ -0,0 +1,36 @@
+# Kundex CLI & SDK
+
+The Kundex terminal AI coding agent — usable as a global CLI (`kundex`) or as
+an SDK (`import { ... } from "kundex"`).
+
+## Install
+
+```bash
+npm install -g kundex
+```
+
+## Usage
+
+```bash
+kundex login          # store your kdx_live_... API key
+kundex                # start an interactive agent session
+```
+
+## Publishing (maintainers)
+
+This export ships a GitHub Actions workflow at
+`.github/workflows/publish-cli.yml` that publishes to npm whenever you push a
+git tag matching `cli-v*` (e.g. `v0.2.0`):
+
+1. Push this directory to a GitHub repo.
+2. In the repo's Settings > Secrets and variables > Actions, add an
+   `NPM_TOKEN` secret (an npm automation token with publish rights).
+3. Bump `version` in `package.json`, commit, then:
+   ```bash
+   git tag v0.2.0
+   git push origin v0.2.0
+   ```
+4. The workflow installs dependencies, type-checks, and runs `npm publish`.
+
+Update the `repository` field in `package.json` to point at your repo before
+publishing.

package/bin/kundex.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// Thin launcher: re-execs node with tsx's ESM loader registered via --import,
+// so we can run the TypeScript source directly without a separate build
+// step, then hands off to the real entrypoint.
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const entry = path.join(here, "..", "src", "index.ts");
+
+const result = spawnSync(
+  process.execPath,
+  ["--import", "tsx/esm", entry, ...process.argv.slice(2)],
+  { stdio: "inherit" },
+);
+
+process.exit(result.status ?? 0);

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@ayoxx/kundex",
+  "version": "0.1.7",
+  "description": "Kundex — a terminal-based AI coding agent CLI and SDK, powered by Groq.",
+  "type": "module",
+  "bin": {
+    "kundex": "./bin/kundex.mjs"
+  },
+  "exports": {
+    ".": "./src/sdk.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "start": "node ./bin/kundex.mjs"
+  },
+  "dependencies": {
+    "tsx": "^4.20.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.29",
+    "typescript": "^5.9.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ayoistooslick/kundex.git"
+  },
+  "license": "MIT",
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ]
+}

package/src/config.ts

@@ -0,0 +1,40 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+export interface KundexConfig {
+  apiKey: string | null;
+  baseUrl: string | null;
+  defaultModel: string | null;
+}
+
+const CONFIG_DIR = path.join(os.homedir(), ".kundex");
+const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
+
+const EMPTY_CONFIG: KundexConfig = {
+  apiKey: null,
+  baseUrl: null,
+  defaultModel: null,
+};
+
+export function loadConfig(): KundexConfig {
+  try {
+    const raw = fs.readFileSync(CONFIG_PATH, "utf-8");
+    return { ...EMPTY_CONFIG, ...JSON.parse(raw) };
+  } catch {
+    return { ...EMPTY_CONFIG };
+  }
+}
+
+export function saveConfig(config: Partial<KundexConfig>): KundexConfig {
+  const merged = { ...loadConfig(), ...config };
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(merged, null, 2));
+  return merged;
+}
+
+export const KUNDEX_BASE_URL = "https://kundex-api.onrender.com";
+
+export function resolveBaseUrl(_config: KundexConfig): string | null {
+  return KUNDEX_BASE_URL;
+}

package/src/index.ts

@@ -0,0 +1,41 @@
+import { loadConfig, resolveBaseUrl } from "./config";
+import { runLogin } from "./login";
+import { runRepl } from "./repl";
+
+async function main(): Promise<void> {
+  const [, , command] = process.argv;
+
+  if (command === "login") {
+    await runLogin();
+    return;
+  }
+
+  if (command === "help" || command === "--help" || command === "-h") {
+    console.log(
+      [
+        "kundeX — terminal AI coding agent.",
+        "",
+        "Usage:",
+        "  kundex login   Save your API key and API base URL",
+        "  kundex         Start the agent REPL in the current directory",
+      ].join("\n"),
+    );
+    return;
+  }
+
+  const config = loadConfig();
+  const baseUrl = resolveBaseUrl(config);
+
+  if (!config.apiKey || !baseUrl) {
+    console.error('Not logged in. Run "kundex login" first.');
+    process.exitCode = 1;
+    return;
+  }
+
+  await runRepl(config, config.apiKey, baseUrl);
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exitCode = 1;
+});

package/src/login.ts

@@ -0,0 +1,21 @@
+import readline from "node:readline/promises";
+import { saveConfig } from "./config";
+
+export async function runLogin(): Promise<void> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  try {
+    const apiKeyAnswer = await rl.question("Kundex API key (from the dashboard's API Keys page): ");
+    const apiKey = apiKeyAnswer.trim();
+    if (!apiKey) {
+      console.error("An API key is required.");
+      process.exitCode = 1;
+      return;
+    }
+
+    saveConfig({ apiKey });
+    console.log("Saved. Run `kundex` in a project directory to start the agent.");
+  } finally {
+    rl.close();
+  }
+}

package/src/repl.ts

@@ -0,0 +1,97 @@
+import readline from "node:readline/promises";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import { Kundex, type AgentTurn } from "./sdk";
+import { executeToolCall } from "./tools";
+import type { KundexConfig } from "./config";
+
+const HELP = `Commands:
+  /help    Show this help
+  /model   Show the model this session is using
+  /clear   Start a new agent session
+  /exit    Quit
+Anything else is sent to the agent as a message.`;
+
+function safeGitStatus(cwd: string): string | undefined {
+  try {
+    return execSync("git status --porcelain=v1 -b", { cwd, timeout: 5000 }).toString();
+  } catch {
+    return undefined;
+  }
+}
+
+async function handleTurn(
+  kundex: Kundex,
+  cwd: string,
+  sessionId: number,
+  turn: AgentTurn,
+): Promise<void> {
+  let current = turn;
+
+  while (!current.done && current.toolCalls && current.toolCalls.length > 0) {
+    for (const call of current.toolCalls) {
+      console.log(`\n\u2192 ${call.name}(${call.arguments})`);
+      const { result, isError } = await executeToolCall(cwd, call);
+      console.log(isError ? `  error: ${result}` : `  ${result.slice(0, 2000)}`);
+
+      current = await kundex.agent.submitToolResult({
+        sessionId,
+        toolCallId: call.id,
+        result,
+        isError,
+      });
+    }
+  }
+
+  if (current.reply) {
+    console.log(`\nkundex: ${current.reply}\n`);
+  }
+}
+
+export async function runRepl(config: KundexConfig, apiKey: string, baseUrl: string): Promise<void> {
+  const cwd = process.cwd();
+  const kundex = new Kundex({ apiKey, baseUrl });
+  const model = config.defaultModel ?? "openai/gpt-oss-120b";
+
+  console.log(`Kundex agent — cwd: ${cwd}, model: ${model}`);
+  console.log("Type /help for commands.\n");
+
+  let session = await kundex.agent.createSession({ cwd, model });
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  try {
+    for (;;) {
+      const input = (await rl.question("> ")).trim();
+      if (!input) continue;
+
+      if (input === "/exit") break;
+      if (input === "/help") {
+        console.log(HELP);
+        continue;
+      }
+      if (input === "/model") {
+        console.log(`Model: ${session.model}`);
+        continue;
+      }
+      if (input === "/clear") {
+        session = await kundex.agent.createSession({ cwd, model });
+        console.log("Started a new session.");
+        continue;
+      }
+
+      try {
+        const turn = await kundex.agent.sendMessage({
+          sessionId: session.id,
+          message: input,
+          context: { gitStatus: safeGitStatus(cwd), openFiles: [] },
+        });
+        await handleTurn(kundex, cwd, session.id, turn);
+      } catch (err) {
+        console.error(`Error: ${(err as Error).message}`);
+      }
+    }
+  } finally {
+    rl.close();
+  }
+}

package/src/sdk.ts

@@ -0,0 +1,178 @@
+export interface KundexChatMessage {
+  role: "system" | "user" | "assistant" | "tool";
+  content?: string | null;
+  name?: string | null;
+  tool_call_id?: string | null;
+  tool_calls?: Array<{ id: string; name: string; arguments: string }> | null;
+}
+
+export interface KundexToolDefinition {
+  name: string;
+  description: string;
+  parametersJsonSchema: string;
+}
+
+export interface ChatUsage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+}
+
+export interface ModelInfo {
+  id: string;
+  name: string;
+  contextWindow: number;
+  inputPricePerMTok: number;
+  outputPricePerMTok: number;
+}
+
+export interface AgentTurn {
+  sessionId: number;
+  reply: string | null;
+  toolCalls: Array<{ id: string; name: string; arguments: string }> | null;
+  done: boolean;
+  usage: ChatUsage | null;
+}
+
+export interface KundexOptions {
+  apiKey: string;
+  baseUrl: string;
+}
+
+/**
+ * Minimal programmatic SDK for the Kundex API. Used by the CLI and
+ * importable directly for building custom integrations:
+ *
+ *   import { Kundex } from "kundex";
+ *   const kundex = new Kundex({ apiKey, baseUrl });
+ *   const result = await kundex.chat.create({ model, messages });
+ */
+export class Kundex {
+  private apiKey: string;
+  private baseUrl: string;
+
+  constructor(opts: KundexOptions) {
+    if (!opts.apiKey) throw new Error("Kundex: apiKey is required");
+    if (!opts.baseUrl) throw new Error("Kundex: baseUrl is required");
+    this.apiKey = opts.apiKey;
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+  }
+
+  private async request<T>(pathname: string, body: unknown): Promise<T> {
+    const res = await fetch(`${this.baseUrl}${pathname}`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`Kundex API error (${res.status}): ${text || res.statusText}`);
+    }
+
+    return (await res.json()) as T;
+  }
+
+  models = {
+    list: async (): Promise<ModelInfo[]> => {
+      const res = await fetch(`${this.baseUrl}/v1/models`);
+      if (!res.ok) throw new Error(`Kundex API error (${res.status})`);
+      return (await res.json()) as ModelInfo[];
+    },
+  };
+
+  chat = {
+    /** Non-streaming chat completion. */
+    create: (params: {
+      model: string;
+      messages: KundexChatMessage[];
+      temperature?: number;
+      tools?: KundexToolDefinition[];
+    }) =>
+      this.request<{
+        id: string;
+        model: string;
+        message: KundexChatMessage;
+        finishReason: string;
+        usage: ChatUsage;
+      }>("/v1/chat/completions", { ...params, stream: false }),
+
+    /** Streaming chat completion; invokes onDelta as tokens arrive. */
+    stream: async (
+      params: {
+        model: string;
+        messages: KundexChatMessage[];
+        temperature?: number;
+        tools?: KundexToolDefinition[];
+      },
+      onDelta: (text: string) => void,
+    ): Promise<{ finishReason: string; usage: ChatUsage | null }> => {
+      const res = await fetch(`${this.baseUrl}/v1/chat/completions`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.apiKey}`,
+        },
+        body: JSON.stringify({ ...params, stream: true }),
+      });
+
+      if (!res.ok || !res.body) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`Kundex API error (${res.status}): ${text || res.statusText}`);
+      }
+
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      let finishReason = "stop";
+      let usage: ChatUsage | null = null;
+
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed.startsWith("data:")) continue;
+          const payload = trimmed.slice(5).trim();
+          if (!payload) continue;
+          const json = JSON.parse(payload);
+          if (json.delta) onDelta(json.delta);
+          if (json.done) {
+            finishReason = json.finishReason ?? finishReason;
+            usage = json.usage ?? usage;
+          }
+        }
+      }
+
+      return { finishReason, usage };
+    },
+  };
+
+  agent = {
+    createSession: (params: { cwd: string; model?: string }) =>
+      this.request<{ id: number; cwd: string; model: string; createdAt: string }>(
+        "/v1/agent/session",
+        params,
+      ),
+
+    sendMessage: (params: {
+      sessionId: number;
+      message: string;
+      context?: { fileTree?: string; gitStatus?: string; openFiles?: string[] };
+    }) => this.request<AgentTurn>("/v1/agent/message", params),
+
+    submitToolResult: (params: {
+      sessionId: number;
+      toolCallId: string;
+      result: string;
+      isError?: boolean;
+    }) => this.request<AgentTurn>("/v1/agent/tool-result", params),
+  };
+}

package/src/tools.ts

@@ -0,0 +1,105 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { exec } from "node:child_process";
+import readline from "node:readline/promises";
+
+export interface ToolCall {
+  id: string;
+  name: string;
+  arguments: string;
+}
+
+export interface ToolResult {
+  result: string;
+  isError: boolean;
+}
+
+async function confirm(prompt: string): Promise<boolean> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question(`${prompt} [y/N] `);
+    return answer.trim().toLowerCase().startsWith("y");
+  } finally {
+    rl.close();
+  }
+}
+
+function resolveInCwd(cwd: string, relPath: string): string {
+  const resolved = path.resolve(cwd, relPath);
+  if (!resolved.startsWith(path.resolve(cwd))) {
+    throw new Error("Path escapes the working directory");
+  }
+  return resolved;
+}
+
+async function readFileTool(cwd: string, args: { path: string }): Promise<string> {
+  const full = resolveInCwd(cwd, args.path);
+  return fs.readFile(full, "utf-8");
+}
+
+async function writeFileTool(cwd: string, args: { path: string; content: string }): Promise<string> {
+  const approved = await confirm(`Write ${args.content.length} bytes to "${args.path}"?`);
+  if (!approved) return "User declined to write this file.";
+  const full = resolveInCwd(cwd, args.path);
+  await fs.mkdir(path.dirname(full), { recursive: true });
+  await fs.writeFile(full, args.content, "utf-8");
+  return `Wrote ${args.content.length} bytes to ${args.path}`;
+}
+
+async function runCommandTool(cwd: string, args: { command: string }): Promise<string> {
+  const approved = await confirm(`Run shell command: "${args.command}"?`);
+  if (!approved) return "User declined to run this command.";
+  return new Promise((resolve) => {
+    exec(args.command, { cwd, timeout: 60_000, maxBuffer: 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) {
+        resolve(`Command failed (${err.message}):\n${stdout}\n${stderr}`);
+      } else {
+        resolve(stdout || stderr || "(no output)");
+      }
+    });
+  });
+}
+
+async function gitTool(cwd: string, args: { args: string[] }): Promise<string> {
+  const isMutating = !["status", "diff", "log", "show", "branch"].includes(args.args[0]);
+  if (isMutating) {
+    const approved = await confirm(`Run: git ${args.args.join(" ")}?`);
+    if (!approved) return "User declined to run this git command.";
+  }
+  return new Promise((resolve) => {
+    exec(`git ${args.args.join(" ")}`, { cwd, timeout: 30_000, maxBuffer: 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) {
+        resolve(`git command failed (${err.message}):\n${stdout}\n${stderr}`);
+      } else {
+        resolve(stdout || stderr || "(no output)");
+      }
+    });
+  });
+}
+
+/** Executes a single tool call locally, matching the server's AGENT_TOOLS contract. */
+export async function executeToolCall(cwd: string, call: ToolCall): Promise<ToolResult> {
+  let args: any;
+  try {
+    args = JSON.parse(call.arguments);
+  } catch {
+    return { result: "Invalid JSON arguments from model.", isError: true };
+  }
+
+  try {
+    switch (call.name) {
+      case "read_file":
+        return { result: await readFileTool(cwd, args), isError: false };
+      case "write_file":
+        return { result: await writeFileTool(cwd, args), isError: false };
+      case "run_command":
+        return { result: await runCommandTool(cwd, args), isError: false };
+      case "git":
+        return { result: await gitTool(cwd, args), isError: false };
+      default:
+        return { result: `Unknown tool: ${call.name}`, isError: true };
+    }
+  } catch (err) {
+    return { result: (err as Error).message, isError: true };
+  }
+}