@ayoxx/kundex 0.1.7 → 1.0.0

package/README.md

@@ -1,12 +1,12 @@
 # Kundex CLI & SDK
 
 The Kundex terminal AI coding agent — usable as a global CLI (`kundex`) or as
-an SDK (`import { ... } from "kundex"`).
+an SDK (`import { ... } from "@ayoxx/kundex"`).
 
 ## Install
 
 ```bash
-npm install -g kundex
+npm install -g @ayoxx/kundex
 ```
 
 ## Usage
@@ -20,15 +20,15 @@ kundex                # start an interactive agent session
 
 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`):
+git tag matching `cli-v*` (e.g. `cli-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
+   git tag cli-v0.2.0
+   git push origin cli-v0.2.0
    ```
 4. The workflow installs dependencies, type-checks, and runs `npm publish`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ayoxx/kundex",
-  "version": "0.1.7",
+  "version": "1.0.0",
   "description": "Kundex — a terminal-based AI coding agent CLI and SDK, powered by Groq.",
   "type": "module",
   "bin": {

package/src/config.ts

@@ -33,8 +33,24 @@ export function saveConfig(config: Partial<KundexConfig>): KundexConfig {
   return merged;
 }
 
-export const KUNDEX_BASE_URL = "https://kundex-api.onrender.com";
+export const KUNDEX_BASE_URL = "https://api.kundex.com.ng";
 
-export function resolveBaseUrl(_config: KundexConfig): string | null {
-  return KUNDEX_BASE_URL;
+/**
+ * Resolves the base URL to use for API calls.
+ *
+ * Priority:
+ *   1. KUNDEX_BASE_URL environment variable (useful for local dev)
+ *   2. Stored baseUrl from config (~/.kundex/config.json)
+ *   3. Hard-coded default: https://api.kundex.com.ng
+ *
+ * Previously, this function ignored the stored baseUrl completely.
+ * That made `kundex config set baseUrl <url>` a no-op, which broke
+ * local development and self-hosted deployments.
+ */
+export function resolveBaseUrl(config: KundexConfig): string | null {
+  return (
+    process.env.KUNDEX_BASE_URL?.trim() ||
+    config.baseUrl?.trim() ||
+    KUNDEX_BASE_URL
+  );
 }

package/src/index.ts

@@ -1,41 +1,575 @@
-import { loadConfig, resolveBaseUrl } from "./config";
+import { loadConfig, saveConfig, resolveBaseUrl } from "./config";
 import { runLogin } from "./login";
 import { runRepl } from "./repl";
+import { Kundex } from "./sdk";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const VERSION = "0.2.0";
+
+// ─── Help text ────────────────────────────────────────────────────────────────
+
+const HELP = `
+\x1b[1m\x1b[36mkundex\x1b[0m — AI coding agent CLI  v${VERSION}
+
+\x1b[1mUsage:\x1b[0m
+  kundex [command] [options]
+
+\x1b[1mAuthentication:\x1b[0m
+  login                            Save your Kundex API key
+  logout                           Remove saved credentials
+
+\x1b[1mAgent:\x1b[0m
+  (no command)                     Start the interactive AI coding agent REPL
+  run <message>                    Run a single agent turn (non-interactive)
+
+\x1b[1mWorkspaces:\x1b[0m
+  workspace list                   List all your agent workspaces
+  workspace new [cwd]              Create a new workspace (default: current dir)
+  workspace delete <id>            Delete a workspace
+
+\x1b[1mFiles:\x1b[0m
+  files list <wsId>                List files in a workspace
+  files get <wsId> <path>          Print a file's content to stdout
+  files push <wsId> <localPath>    Upload a local file to a workspace
+  files push <wsId> <localPath> <remotePath>
+  files pull <wsId> <remotePath>   Download a workspace file to stdout (or --out)
+
+\x1b[1mModels:\x1b[0m
+  models                           List available models
+
+\x1b[1mConfiguration:\x1b[0m
+  config show                      Show current configuration
+  config set <key> <val>           Set a config value
+    Keys: model, baseUrl
+
+\x1b[1mOther:\x1b[0m
+  help, --help, -h                 Show this help
+  version, --version, -v           Show version
+
+\x1b[1mExamples:\x1b[0m
+  kundex login
+  kundex                                       # start REPL in current directory
+  kundex run "Fix all TypeScript errors"
+  kundex models
+  kundex workspace list
+  kundex workspace new /path/to/project
+  kundex workspace delete 42
+  kundex files list 17
+  kundex files get 17 src/index.ts
+  kundex files push 17 ./README.md
+  kundex files pull 17 src/index.ts --out ./downloaded.ts
+  kundex config set model openai/gpt-oss-120b
+  kundex config set baseUrl https://api.kundex.com.ng
+`.trim();
+
+// ─── Colour helpers ───────────────────────────────────────────────────────────
+
+const c = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+};
+
+function ok(msg: string) { console.log(`${c.green}${c.bold}  ✓${c.reset} ${msg}`); }
+function errMsg(msg: string) { console.error(`${c.red}${c.bold}  ✗${c.reset} ${msg}`); }
+function dim(msg: string) { console.log(`${c.dim}  ${msg}${c.reset}`); }
+function header(msg: string) { console.log(`\n${c.bold}${c.cyan}  ${msg}${c.reset}`); }
+
+// ─── Commands ─────────────────────────────────────────────────────────────────
+
+const PROVIDER_DISPLAY: Record<string, string> = {
+  heavstal: "Heavstal",
+  gemini:   "Gemini",
+  groq:     "Groq",
+  mistral:  "Mistral",
+};
+
+async function cmdModels(config: ReturnType<typeof loadConfig>, baseUrl: string) {
+  const kundex = new Kundex({ apiKey: config.apiKey!, baseUrl });
+  header("Available models");
+  try {
+    const models = await kundex.models.list();
+    if (!models.length) { dim("No models found."); return; }
+    const nameWidth     = Math.max(...models.map((m) => m.name.length), 4);
+    const idWidth       = Math.max(...models.map((m) => m.id.length), 2);
+    const providerWidth = Math.max(...models.map((m) => (m.provider?.length ?? 0)), 8);
+    console.log(`\n  ${c.dim}${"Name".padEnd(nameWidth)}  ${"ID".padEnd(idWidth)}  ${"Provider".padEnd(providerWidth)}  Context${c.reset}`);
+    console.log(`  ${c.dim}${"─".repeat(nameWidth + idWidth + providerWidth + 18)}${c.reset}`);
+
+    // Group by provider for cleaner output
+    const grouped: Record<string, typeof models> = {};
+    const order: string[] = [];
+    for (const m of models) {
+      const p = m.provider ?? "other";
+      if (!grouped[p]) { grouped[p] = []; order.push(p); }
+      grouped[p].push(m);
+    }
+
+    for (const provider of order) {
+      for (const m of grouped[provider]) {
+        const ctx = m.contextWindow >= 1_000_000
+          ? `${(m.contextWindow / 1_000_000).toFixed(1)}M`
+          : m.contextWindow >= 1000
+            ? `${(m.contextWindow / 1000).toFixed(0)}k`
+            : String(m.contextWindow);
+        const providerLabel = (PROVIDER_DISPLAY[m.provider ?? ""] ?? m.provider ?? "").padEnd(providerWidth);
+        console.log(
+          `  ${c.bold}${m.name.padEnd(nameWidth)}${c.reset}` +
+          `  ${c.dim}${m.id.padEnd(idWidth)}${c.reset}` +
+          `  ${c.cyan}${providerLabel}${c.reset}` +
+          `  ${c.dim}${ctx}${c.reset}`,
+        );
+      }
+    }
+    console.log();
+  } catch (e) {
+    errMsg(`Failed to list models: ${(e as Error).message}`);
+    process.exitCode = 1;
+  }
+}
+
+async function cmdWorkspaceList(config: ReturnType<typeof loadConfig>, baseUrl: string) {
+  const kundex = new Kundex({ apiKey: config.apiKey!, baseUrl });
+  header("Workspaces");
+  try {
+    const sessions = await kundex.agent.listSessions();
+
+    if (!sessions.length) {
+      dim("No workspaces yet. Create one with: kundex workspace new <directory>");
+      return;
+    }
+
+    console.log(`\n  ${c.dim}${"ID".padEnd(6)}  ${"Name".padEnd(28)}  ${"Directory".padEnd(34)}  Model${c.reset}`);
+    console.log(`  ${c.dim}${"─".repeat(90)}${c.reset}`);
+    for (const s of sessions) {
+      const cwd = (s.cwd ?? "").length > 32 ? `…${s.cwd.slice(-31)}` : (s.cwd ?? "");
+      const name = (s.name ?? `Workspace #${s.id}`).slice(0, 26);
+      console.log(`  ${c.bold}${String(s.id).padEnd(6)}${c.reset}  ${name.padEnd(28)}  ${c.dim}${cwd.padEnd(34)}  ${s.model}${c.reset}`);
+    }
+    console.log();
+  } catch (e) {
+    errMsg(`Failed to list workspaces: ${(e as Error).message}`);
+    process.exitCode = 1;
+  }
+}
+
+async function cmdWorkspaceNew(
+  config: ReturnType<typeof loadConfig>,
+  baseUrl: string,
+  args: string[],
+) {
+  const cwd = args[0] ?? process.cwd();
+
+  // Parse optional flags: --model <model>, --name <name>
+  let model = config.defaultModel ?? "openai/gpt-oss-120b";
+  let name: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--model" && args[i + 1]) { model = args[++i]; }
+    else if (args[i] === "--name" && args[i + 1]) { name = args[++i]; }
+  }
+
+  const kundex = new Kundex({ apiKey: config.apiKey!, baseUrl });
+
+  try {
+    const session = await kundex.agent.createSession({ cwd, model, name });
+    ok(`Created workspace #${session.id}`);
+    dim(`Name:      ${session.name}`);
+    dim(`Directory: ${cwd}`);
+    dim(`Model:     ${session.model}`);
+    console.log();
+  } catch (e) {
+    errMsg(`Failed to create workspace: ${(e as Error).message}`);
+    process.exitCode = 1;
+  }
+}
+
+async function cmdWorkspaceDelete(
+  config: ReturnType<typeof loadConfig>,
+  baseUrl: string,
+  idStr: string,
+) {
+  const id = Number(idStr);
+  if (!Number.isFinite(id) || id <= 0) {
+    errMsg("Usage: kundex workspace delete <id>");
+    process.exitCode = 1;
+    return;
+  }
+
+  const kundex = new Kundex({ apiKey: config.apiKey!, baseUrl });
+
+  try {
+    await kundex.agent.deleteSession(id);
+    ok(`Deleted workspace #${id}`);
+  } catch (e) {
+    errMsg(`Failed to delete workspace: ${(e as Error).message}`);
+    process.exitCode = 1;
+  }
+}
+
+// ── Files ─────────────────────────────────────────────────────────────────────
+
+async function cmdFilesList(
+  config: ReturnType<typeof loadConfig>,
+  baseUrl: string,
+  wsIdStr: string,
+) {
+  const wsId = Number(wsIdStr);
+  if (!Number.isFinite(wsId) || wsId <= 0) {
+    errMsg("Usage: kundex files list <wsId>");
+    process.exitCode = 1;
+    return;
+  }
+
+  const kundex = new Kundex({ apiKey: config.apiKey!, baseUrl });
+  header(`Files in workspace #${wsId}`);
+
+  try {
+    const { files } = await kundex.files.list(wsId);
+    if (!files.length) {
+      dim("No files yet.");
+      return;
+    }
+
+    console.log(`\n  ${c.dim}${"Path".padEnd(44)}  ${"Size".padEnd(10)}  MIME${c.reset}`);
+    console.log(`  ${c.dim}${"─".repeat(80)}${c.reset}`);
+    for (const f of files) {
+      const size = f.size < 1024 ? `${f.size} B`
+        : f.size < 1024 * 1024 ? `${(f.size / 1024).toFixed(1)} KB`
+        : `${(f.size / 1024 / 1024).toFixed(1)} MB`;
+      const displayPath = f.path.length > 42 ? `…${f.path.slice(-41)}` : f.path;
+      console.log(`  ${displayPath.padEnd(44)}  ${size.padEnd(10)}  ${c.dim}${f.mimeType}${c.reset}`);
+    }
+    console.log();
+  } catch (e) {
+    errMsg(`Failed to list files: ${(e as Error).message}`);
+    process.exitCode = 1;
+  }
+}
+
+async function cmdFilesGet(
+  config: ReturnType<typeof loadConfig>,
+  baseUrl: string,
+  wsIdStr: string,
+  remotePath: string,
+) {
+  const wsId = Number(wsIdStr);
+  if (!Number.isFinite(wsId) || wsId <= 0 || !remotePath) {
+    errMsg("Usage: kundex files get <wsId> <path>");
+    process.exitCode = 1;
+    return;
+  }
+
+  const kundex = new Kundex({ apiKey: config.apiKey!, baseUrl });
+
+  try {
+    const file = await kundex.files.get(wsId, remotePath);
+    process.stdout.write(file.content ?? "");
+  } catch (e) {
+    errMsg(`Failed to get file: ${(e as Error).message}`);
+    process.exitCode = 1;
+  }
+}
+
+async function cmdFilesPush(
+  config: ReturnType<typeof loadConfig>,
+  baseUrl: string,
+  wsIdStr: string,
+  localPath: string,
+  remotePath?: string,
+) {
+  const wsId = Number(wsIdStr);
+  if (!Number.isFinite(wsId) || wsId <= 0 || !localPath) {
+    errMsg("Usage: kundex files push <wsId> <localPath> [remotePath]");
+    process.exitCode = 1;
+    return;
+  }
+
+  const kundex = new Kundex({ apiKey: config.apiKey!, baseUrl });
+  const destPath = remotePath ?? path.basename(localPath);
+
+  try {
+    const content = await fs.readFile(localPath, "utf-8");
+    const name = path.basename(destPath);
+    await kundex.files.upsert(wsId, { path: destPath, name, content });
+    ok(`Pushed ${localPath} → workspace #${wsId}:${destPath}`);
+  } catch (e) {
+    errMsg(`Failed to push file: ${(e as Error).message}`);
+    process.exitCode = 1;
+  }
+}
+
+async function cmdFilesPull(
+  config: ReturnType<typeof loadConfig>,
+  baseUrl: string,
+  wsIdStr: string,
+  remotePath: string,
+  outPath?: string,
+) {
+  const wsId = Number(wsIdStr);
+  if (!Number.isFinite(wsId) || wsId <= 0 || !remotePath) {
+    errMsg("Usage: kundex files pull <wsId> <remotePath> [--out <localPath>]");
+    process.exitCode = 1;
+    return;
+  }
+
+  const kundex = new Kundex({ apiKey: config.apiKey!, baseUrl });
+
+  try {
+    const file = await kundex.files.get(wsId, remotePath);
+    const content = file.content ?? "";
+
+    if (outPath) {
+      await fs.mkdir(path.dirname(outPath), { recursive: true });
+      await fs.writeFile(outPath, content, "utf-8");
+      ok(`Saved ${remotePath} → ${outPath} (${content.length} bytes)`);
+    } else {
+      process.stdout.write(content);
+    }
+  } catch (e) {
+    errMsg(`Failed to pull file: ${(e as Error).message}`);
+    process.exitCode = 1;
+  }
+}
+
+// ── Run (single-turn non-interactive) ─────────────────────────────────────────
+
+async function cmdRun(
+  config: ReturnType<typeof loadConfig>,
+  baseUrl: string,
+  message: string,
+  args: string[],
+) {
+  if (!message) {
+    errMsg("Usage: kundex run <message>");
+    process.exitCode = 1;
+    return;
+  }
+
+  // Parse optional flags: --model, --workspace, --cwd
+  let model = config.defaultModel ?? "openai/gpt-oss-120b";
+  let wsId: number | null = null;
+  let cwd = process.cwd();
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--model" && args[i + 1]) model = args[++i];
+    else if ((args[i] === "--workspace" || args[i] === "-w") && args[i + 1]) wsId = Number(args[++i]);
+    else if (args[i] === "--cwd" && args[i + 1]) cwd = args[++i];
+  }
+
+  const kundex = new Kundex({ apiKey: config.apiKey!, baseUrl });
+  let sessionId: number;
+
+  try {
+    if (wsId !== null && Number.isFinite(wsId)) {
+      sessionId = wsId;
+    } else {
+      const session = await kundex.agent.createSession({ cwd, model });
+      sessionId = session.id;
+    }
+
+    process.stdout.write(`\n`);
+    const { executeToolCall } = await import("./tools");
+
+    let turn = await kundex.agent.streamMessage(
+      { sessionId, message },
+      (delta) => process.stdout.write(delta),
+    );
+
+    // Handle tool calls in a loop until the turn is done
+    while (!turn.done && turn.toolCalls && turn.toolCalls.length > 0) {
+      for (const call of turn.toolCalls) {
+        const { result, isError } = await executeToolCall(cwd, call);
+        turn = await kundex.agent.submitToolResult(
+          { sessionId, toolCallId: call.id, result, isError },
+          (delta) => process.stdout.write(delta),
+        );
+      }
+    }
+
+    process.stdout.write("\n");
+  } catch (e) {
+    errMsg(`Agent error: ${(e as Error).message}`);
+    process.exitCode = 1;
+  }
+}
+
+// ─── Config commands ──────────────────────────────────────────────────────────
+
+function cmdConfigShow(config: ReturnType<typeof loadConfig>, baseUrl: string) {
+  header("Current configuration");
+  console.log();
+  const rows = [
+    ["API key",  config.apiKey ? `${config.apiKey.slice(0, 8)}…` : "(not set)"],
+    ["Base URL", baseUrl],
+    ["Model",    config.defaultModel ?? "(default)"],
+  ];
+  for (const [k, v] of rows) {
+    console.log(`  ${c.dim}${k.padEnd(12)}${c.reset}  ${c.bold}${v}${c.reset}`);
+  }
+  console.log();
+}
+
+function cmdConfigSet(key: string, value: string) {
+  const allowed = ["model", "baseUrl"];
+  if (!allowed.includes(key)) {
+    errMsg(`Unknown config key "${key}". Allowed keys: ${allowed.join(", ")}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const map: Record<string, keyof ReturnType<typeof loadConfig>> = {
+    model: "defaultModel",
+    baseUrl: "baseUrl",
+  };
+
+  saveConfig({ [map[key]]: value });
+  ok(`Set ${key} = ${value}`);
+}
+
+function cmdLogout() {
+  saveConfig({ apiKey: null, baseUrl: null, defaultModel: null });
+  ok("Logged out. Run `kundex login` to authenticate again.");
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
 
 async function main(): Promise<void> {
-  const [, , command] = process.argv;
+  const args = process.argv.slice(2);
+  const [command, sub, ...rest] = args;
 
-  if (command === "login") {
-    await runLogin();
+  // Version
+  if (command === "version" || command === "--version" || command === "-v") {
+    console.log(`kundex v${VERSION}`);
     return;
   }
 
+  // Help
   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"),
-    );
+    console.log(HELP);
+    return;
+  }
+
+  // No command — drop into REPL if logged in, else show help
+  if (!command) {
+    const config = loadConfig();
+    const baseUrl = resolveBaseUrl(config);
+    if (config.apiKey && baseUrl) {
+      await runRepl(config, config.apiKey, baseUrl);
+      return;
+    }
+    console.log(HELP);
+    console.log(`\n${c.yellow}  Run \`kundex login\` to get started.${c.reset}\n`);
+    return;
+  }
+
+  // Login / logout
+  if (command === "login") {
+    await runLogin();
+    return;
+  }
+  if (command === "logout") {
+    cmdLogout();
     return;
   }
 
+  // Load config — required for all remaining commands
   const config = loadConfig();
   const baseUrl = resolveBaseUrl(config);
 
   if (!config.apiKey || !baseUrl) {
-    console.error('Not logged in. Run "kundex login" first.');
+    errMsg('Not logged in. Run "kundex login" first.');
     process.exitCode = 1;
     return;
   }
 
-  await runRepl(config, config.apiKey, baseUrl);
+  // Models
+  if (command === "models") {
+    await cmdModels(config, baseUrl);
+    return;
+  }
+
+  // Config
+  if (command === "config") {
+    if (sub === "show" || !sub) {
+      cmdConfigShow(config, baseUrl);
+    } else if (sub === "set") {
+      const [key, value] = rest;
+      if (!key || !value) {
+        errMsg("Usage: kundex config set <key> <value>");
+        process.exitCode = 1;
+      } else {
+        cmdConfigSet(key, value);
+      }
+    } else {
+      errMsg(`Unknown config subcommand "${sub}". Use: show, set`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  // Workspace
+  if (command === "workspace") {
+    if (sub === "list" || !sub) {
+      await cmdWorkspaceList(config, baseUrl);
+    } else if (sub === "new") {
+      await cmdWorkspaceNew(config, baseUrl, rest);
+    } else if (sub === "delete") {
+      await cmdWorkspaceDelete(config, baseUrl, rest[0]);
+    } else {
+      errMsg(`Unknown workspace subcommand "${sub}". Use: list, new, delete`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  // Files
+  if (command === "files") {
+    if (sub === "list") {
+      await cmdFilesList(config, baseUrl, rest[0]);
+    } else if (sub === "get") {
+      await cmdFilesGet(config, baseUrl, rest[0], rest[1]);
+    } else if (sub === "push") {
+      await cmdFilesPush(config, baseUrl, rest[0], rest[1], rest[2]);
+    } else if (sub === "pull") {
+      // Support --out flag
+      let outPath: string | undefined;
+      const remaining: string[] = [];
+      for (let i = 0; i < rest.length; i++) {
+        if (rest[i] === "--out" && rest[i + 1]) { outPath = rest[++i]; }
+        else remaining.push(rest[i]);
+      }
+      await cmdFilesPull(config, baseUrl, remaining[0], remaining[1], outPath);
+    } else {
+      errMsg(`Unknown files subcommand "${sub}". Use: list, get, push, pull`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  // Run (single-turn agent)
+  if (command === "run") {
+    // "kundex run <message>" — join remaining args as the message
+    const allArgs = [sub, ...rest].filter(Boolean);
+    // Find message (everything before the first -- flag or flag-like arg)
+    const flagStart = allArgs.findIndex((a) => a.startsWith("--"));
+    const messageParts = flagStart >= 0 ? allArgs.slice(0, flagStart) : allArgs;
+    const flagArgs = flagStart >= 0 ? allArgs.slice(flagStart) : [];
+    const message = messageParts.join(" ").trim();
+
+    await cmdRun(config, baseUrl, message, flagArgs);
+    return;
+  }
+
+  // Unknown command — suggest help
+  errMsg(`Unknown command "${command}". Run \`kundex help\` to see available commands.`);
+  process.exitCode = 1;
 }
 
-main().catch((err) => {
-  console.error(err instanceof Error ? err.message : err);
+main().catch((e) => {
+  console.error(`${c.red}  Fatal: ${e instanceof Error ? e.message : e}${c.reset}`);
   process.exitCode = 1;
 });