@thejeetsingh/kalcode 2.0.0

package/src/proxy/server.ts

@@ -0,0 +1,128 @@
+import { API_URL } from "../constants.js";
+
+const PORT = parseInt(process.env.PORT || "8787", 10);
+const HOST = process.env.HOST || "0.0.0.0";
+const PROXY_TOKEN = process.env.KALCODE_PROXY_TOKEN || "";
+const NVIDIA_NIM_KEY = process.env.NVIDIA_NIM_KEY || "";
+const RATE_LIMIT_PER_MIN = Math.max(
+  1,
+  parseInt(process.env.KALCODE_PROXY_RATE_LIMIT_PER_MIN || "120", 10),
+);
+
+const requestTimestampsByClient = new Map<string, number[]>();
+
+function json(status: number, payload: Record<string, unknown>): Response {
+  return new Response(JSON.stringify(payload), {
+    status,
+    headers: {
+      "Content-Type": "application/json",
+    },
+  });
+}
+
+function getClientId(req: Request): string {
+  const forwardedFor = req.headers.get("x-forwarded-for");
+  if (forwardedFor) return forwardedFor.split(",")[0]!.trim();
+  return "unknown";
+}
+
+function isRateLimited(clientId: string): boolean {
+  const now = Date.now();
+  const windowStart = now - 60_000;
+  const timestamps = requestTimestampsByClient.get(clientId) || [];
+  const filtered = timestamps.filter((ts) => ts >= windowStart);
+
+  if (filtered.length >= RATE_LIMIT_PER_MIN) {
+    requestTimestampsByClient.set(clientId, filtered);
+    return true;
+  }
+
+  filtered.push(now);
+  requestTimestampsByClient.set(clientId, filtered);
+  return false;
+}
+
+function getBearerToken(req: Request): string {
+  const auth = req.headers.get("authorization") || "";
+  const m = auth.match(/^Bearer\s+(.+)$/i);
+  return m?.[1]?.trim() || "";
+}
+
+async function proxyCompletions(req: Request): Promise<Response> {
+  if (!NVIDIA_NIM_KEY) {
+    return json(500, {
+      error: {
+        message: "Server missing NVIDIA_NIM_KEY.",
+      },
+    });
+  }
+
+  if (PROXY_TOKEN) {
+    const incomingToken = getBearerToken(req);
+    if (!incomingToken || incomingToken !== PROXY_TOKEN) {
+      return json(401, {
+        error: {
+          message: "Unauthorized. Invalid proxy token.",
+        },
+      });
+    }
+  }
+
+  const clientId = getClientId(req);
+  if (isRateLimited(clientId)) {
+    return json(429, {
+      error: {
+        message: "Rate limit exceeded. Please retry shortly.",
+      },
+    });
+  }
+
+  const body = await req.text();
+  const upstream = await fetch(API_URL, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${NVIDIA_NIM_KEY}`,
+    },
+    body,
+  });
+
+  const headers = new Headers();
+  const contentType = upstream.headers.get("content-type");
+  if (contentType) headers.set("Content-Type", contentType);
+  const cacheControl = upstream.headers.get("cache-control");
+  if (cacheControl) headers.set("Cache-Control", cacheControl);
+
+  return new Response(upstream.body, {
+    status: upstream.status,
+    headers,
+  });
+}
+
+const server = Bun.serve({
+  hostname: HOST,
+  port: PORT,
+  async fetch(req: Request): Promise<Response> {
+    const url = new URL(req.url);
+
+    if (req.method === "GET" && url.pathname === "/health") {
+      return json(200, {
+        ok: true,
+      });
+    }
+
+    if (req.method === "POST" && url.pathname === "/v1/chat/completions") {
+      return proxyCompletions(req);
+    }
+
+    return json(404, {
+      error: {
+        message: "Not found.",
+      },
+    });
+  },
+});
+
+console.log(
+  `kalcode proxy listening on http://${server.hostname}:${server.port} (rate ${RATE_LIMIT_PER_MIN}/min/client)`,
+);

package/src/tools/edit-file.ts

@@ -0,0 +1,97 @@
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { resolve } from "path";
+import type { ToolHandler } from "../types.js";
+
+export const editFileTool: ToolHandler = {
+  definition: {
+    type: "function",
+    function: {
+      name: "editFile",
+      description:
+        "Make surgical edits to a file using search/replace pairs. Each edit finds an exact text match and replaces it. Read the file first to get the exact text to search for.",
+      parameters: {
+        type: "object",
+        properties: {
+          filePath: {
+            type: "string",
+            description: "Path to the file to edit",
+          },
+          edits: {
+            type: "array",
+            description: "Array of search/replace edit operations",
+            items: {
+              type: "object",
+              properties: {
+                search: {
+                  type: "string",
+                  description: "Exact text to search for in the file",
+                },
+                replace: {
+                  type: "string",
+                  description: "Text to replace the search text with",
+                },
+              },
+              required: ["search", "replace"],
+            },
+          },
+        },
+        required: ["filePath", "edits"],
+      },
+    },
+  },
+
+  async execute(args) {
+    const filePath = resolve(String(args.filePath));
+    const edits = args.edits as Array<{ search: string; replace: string }>;
+
+    if (!existsSync(filePath)) {
+      return `Error: File not found: ${filePath}`;
+    }
+
+    if (!Array.isArray(edits) || edits.length === 0) {
+      return "Error: edits must be a non-empty array of {search, replace} pairs";
+    }
+
+    try {
+      let content = readFileSync(filePath, "utf-8");
+      const results: string[] = [];
+
+      for (let i = 0; i < edits.length; i++) {
+        const edit = edits[i]!;
+        const search = String(edit.search);
+        const replace = String(edit.replace);
+
+        let idx = content.indexOf(search);
+        // Try trimming trailing whitespace per line if exact match fails
+        if (idx === -1) {
+          const searchNorm = search.split("\n").map(l => l.trimEnd()).join("\n");
+          const contentNorm = content.split("\n").map(l => l.trimEnd()).join("\n");
+          idx = contentNorm.indexOf(searchNorm);
+          if (idx !== -1) {
+            // Find the real position accounting for trailing whitespace diffs
+            const before = contentNorm.slice(0, idx);
+            const linesBefore = before.split("\n").length - 1;
+            const linesInSearch = searchNorm.split("\n").length;
+            const contentLines = content.split("\n");
+            const realBefore = contentLines.slice(0, linesBefore).join("\n") + (linesBefore > 0 ? "\n" : "");
+            const realMatch = contentLines.slice(linesBefore, linesBefore + linesInSearch).join("\n");
+            content = realBefore + replace + content.slice(realBefore.length + realMatch.length);
+            results.push(`Edit ${i + 1}: OK (fuzzy whitespace match)`);
+            continue;
+          }
+          results.push(`Edit ${i + 1}: FAILED - search text not found`);
+          continue;
+        }
+
+        // Only replace first occurrence
+        content = content.slice(0, idx) + replace + content.slice(idx + search.length);
+        results.push(`Edit ${i + 1}: OK`);
+      }
+
+      writeFileSync(filePath, content);
+      return `Edited ${filePath}:\n${results.join("\n")}`;
+    } catch (err: unknown) {
+      return `Error editing file: ${err instanceof Error ? err.message : String(err)}`;
+    }
+  },
+};

package/src/tools/glob-tool.ts

@@ -0,0 +1,59 @@
+import { resolve } from "path";
+import type { ToolHandler } from "../types.js";
+import { MAX_GLOB_RESULTS } from "../constants.js";
+
+export const globTool: ToolHandler = {
+  definition: {
+    type: "function",
+    function: {
+      name: "glob",
+      description:
+        "Find files matching a glob pattern. Returns matching file paths sorted by modification time.",
+      parameters: {
+        type: "object",
+        properties: {
+          pattern: {
+            type: "string",
+            description: "Glob pattern (e.g., '**/*.ts', 'src/**/*.json')",
+          },
+          path: {
+            type: "string",
+            description: "Base directory to search from. Default: current directory",
+          },
+        },
+        required: ["pattern"],
+      },
+    },
+  },
+
+  async execute(args) {
+    const pattern = String(args.pattern);
+    const basePath = resolve(String(args.path || "."));
+
+    try {
+      const glob = new Bun.Glob(pattern);
+      const matches: string[] = [];
+
+      for await (const entry of glob.scan({ cwd: basePath, dot: false })) {
+        // Skip common noise directories
+        if (entry.startsWith("node_modules/") || entry.startsWith(".git/")) continue;
+        matches.push(entry);
+        if (matches.length >= MAX_GLOB_RESULTS) break;
+      }
+
+      if (matches.length === 0) {
+        return `No files matching pattern: ${pattern} in ${basePath}`;
+      }
+
+      matches.sort();
+      let result = `Found ${matches.length} file(s) matching "${pattern}":\n`;
+      result += matches.join("\n");
+      if (matches.length >= MAX_GLOB_RESULTS) {
+        result += `\n... (results limited to ${MAX_GLOB_RESULTS})`;
+      }
+      return result;
+    } catch (err: unknown) {
+      return `Error searching for files: ${err instanceof Error ? err.message : String(err)}`;
+    }
+  },
+};

package/src/tools/grep.ts

@@ -0,0 +1,96 @@
+import type { ToolHandler } from "../types.js";
+import { MAX_GREP_RESULTS } from "../constants.js";
+
+export const grepTool: ToolHandler = {
+  definition: {
+    type: "function",
+    function: {
+      name: "grep",
+      description:
+        "Search file contents for a pattern. Uses ripgrep if available, otherwise falls back to grep. Returns matching lines with file paths and line numbers.",
+      parameters: {
+        type: "object",
+        properties: {
+          pattern: {
+            type: "string",
+            description: "Search pattern (regex supported)",
+          },
+          path: {
+            type: "string",
+            description: "Directory or file to search in. Default: current directory",
+          },
+          include: {
+            type: "string",
+            description: "File glob pattern to include (e.g., '*.ts')",
+          },
+          maxResults: {
+            type: "number",
+            description: `Maximum number of results. Default: ${MAX_GREP_RESULTS}`,
+          },
+        },
+        required: ["pattern"],
+      },
+    },
+  },
+
+  async execute(args) {
+    const pattern = String(args.pattern);
+    const searchPath = String(args.path || ".");
+    const include = args.include ? String(args.include) : null;
+    const maxResults = Number(args.maxResults) || MAX_GREP_RESULTS;
+
+    // Try ripgrep first, fall back to grep
+    const hasRg = await checkCommand("rg");
+
+    let cmd: string;
+    if (hasRg) {
+      cmd = `rg --line-number --max-count ${maxResults} --no-heading --glob '!node_modules' --glob '!.git'`;
+      if (include) cmd += ` --glob '${include}'`;
+      cmd += ` -- ${escapeShellArg(pattern)} ${escapeShellArg(searchPath)}`;
+    } else {
+      cmd = `grep -rn --max-count=${maxResults} --exclude-dir=node_modules --exclude-dir=.git`;
+      if (include) cmd += ` --include='${include}'`;
+      cmd += ` -- ${escapeShellArg(pattern)} ${escapeShellArg(searchPath)}`;
+    }
+
+    try {
+      const proc = Bun.spawn(["sh", "-c", cmd], {
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+
+      const stdout = await new Response(proc.stdout).text();
+      const stderr = await new Response(proc.stderr).text();
+      await proc.exited;
+
+      if (!stdout.trim()) {
+        return `No matches found for pattern: ${pattern}`;
+      }
+
+      // Limit results
+      const lines = stdout.trim().split("\n");
+      const limited = lines.slice(0, maxResults);
+      let result = limited.join("\n");
+      if (lines.length > maxResults) {
+        result += `\n... (${lines.length - maxResults} more matches)`;
+      }
+      return result;
+    } catch (err: unknown) {
+      return `Error searching: ${err instanceof Error ? err.message : String(err)}`;
+    }
+  },
+};
+
+async function checkCommand(cmd: string): Promise<boolean> {
+  try {
+    const proc = Bun.spawn(["which", cmd], { stdout: "pipe", stderr: "pipe" });
+    await proc.exited;
+    return proc.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+function escapeShellArg(arg: string): string {
+  return `'${arg.replace(/'/g, "'\\''")}'`;
+}

package/src/tools/list-directory.ts

@@ -0,0 +1,101 @@
+import { readdirSync, statSync, existsSync } from "fs";
+import { resolve, join } from "path";
+import type { ToolHandler } from "../types.js";
+import { MAX_DIR_ENTRIES, MAX_DIR_DEPTH } from "../constants.js";
+
+export const listDirectoryTool: ToolHandler = {
+  definition: {
+    type: "function",
+    function: {
+      name: "listDirectory",
+      description:
+        "List the contents of a directory. Shows file names, types, and sizes.",
+      parameters: {
+        type: "object",
+        properties: {
+          dirPath: {
+            type: "string",
+            description: "Path to the directory to list. Default: current directory",
+          },
+          recursive: {
+            type: "boolean",
+            description: "List recursively (max depth 3). Default: false",
+          },
+        },
+      },
+    },
+  },
+
+  async execute(args) {
+    const dirPath = resolve(String(args.dirPath || "."));
+    const recursive = Boolean(args.recursive);
+
+    if (!existsSync(dirPath)) {
+      return `Error: Directory not found: ${dirPath}`;
+    }
+
+    try {
+      const entries: string[] = [];
+      listDir(dirPath, "", recursive ? MAX_DIR_DEPTH : 0, entries);
+
+      if (entries.length === 0) {
+        return `Directory is empty: ${dirPath}`;
+      }
+
+      let result = `Contents of ${dirPath} (${entries.length} entries):\n`;
+      result += entries.join("\n");
+      if (entries.length >= MAX_DIR_ENTRIES) {
+        result += `\n... (limited to ${MAX_DIR_ENTRIES} entries)`;
+      }
+      return result;
+    } catch (err: unknown) {
+      return `Error listing directory: ${err instanceof Error ? err.message : String(err)}`;
+    }
+  },
+};
+
+function listDir(
+  basePath: string,
+  prefix: string,
+  depth: number,
+  entries: string[]
+): void {
+  if (entries.length >= MAX_DIR_ENTRIES) return;
+
+  let items: string[];
+  try {
+    items = readdirSync(join(basePath, prefix));
+  } catch {
+    return;
+  }
+
+  items.sort();
+
+  for (const item of items) {
+    if (entries.length >= MAX_DIR_ENTRIES) return;
+
+    const relPath = prefix ? `${prefix}/${item}` : item;
+    const fullPath = join(basePath, relPath);
+
+    try {
+      const stat = statSync(fullPath);
+      if (stat.isDirectory()) {
+        entries.push(`${relPath}/`);
+        if (depth > 0) {
+          listDir(basePath, relPath, depth - 1, entries);
+        }
+      } else {
+        const size = formatSize(stat.size);
+        entries.push(`${relPath} (${size})`);
+      }
+    } catch {
+      entries.push(`${relPath} (unreadable)`);
+    }
+  }
+}
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
+}

package/src/tools/read-file.ts

@@ -0,0 +1,71 @@
+import { readFileSync, statSync, existsSync } from "fs";
+import { resolve } from "path";
+import type { ToolHandler } from "../types.js";
+import { MAX_FILE_SIZE, DEFAULT_LINE_LIMIT } from "../constants.js";
+
+export const readFileTool: ToolHandler = {
+  definition: {
+    type: "function",
+    function: {
+      name: "readFile",
+      description:
+        "Read the contents of a file with line numbers. Returns line-numbered output. Use offset and limit to read specific portions of large files.",
+      parameters: {
+        type: "object",
+        properties: {
+          filePath: {
+            type: "string",
+            description: "Path to the file to read (absolute or relative to cwd)",
+          },
+          offset: {
+            type: "number",
+            description: "Line number to start reading from (1-based). Default: 1",
+          },
+          limit: {
+            type: "number",
+            description: `Maximum number of lines to read. Default: ${DEFAULT_LINE_LIMIT}`,
+          },
+        },
+        required: ["filePath"],
+      },
+    },
+  },
+
+  async execute(args) {
+    const filePath = resolve(String(args.filePath));
+    const offset = Math.max(1, Number(args.offset) || 1);
+    const limit = Number(args.limit) || DEFAULT_LINE_LIMIT;
+
+    if (!existsSync(filePath)) {
+      return `Error: File not found: ${filePath}`;
+    }
+
+    try {
+      const stat = statSync(filePath);
+      if (stat.isDirectory()) {
+        return `Error: Path is a directory, not a file: ${filePath}`;
+      }
+      if (stat.size > MAX_FILE_SIZE) {
+        return `Error: File too large (${(stat.size / 1024 / 1024).toFixed(1)}MB). Use offset/limit to read portions.`;
+      }
+
+      const content = readFileSync(filePath, "utf-8");
+      const lines = content.split("\n");
+      const startIdx = offset - 1;
+      const endIdx = Math.min(startIdx + limit, lines.length);
+      const slice = lines.slice(startIdx, endIdx);
+
+      const numbered = slice
+        .map((line, i) => {
+          const lineNum = String(startIdx + i + 1).padStart(4, " ");
+          return `${lineNum} | ${line}`;
+        })
+        .join("\n");
+
+      const header = `File: ${filePath} (${lines.length} lines total, showing ${offset}-${endIdx})`;
+      return `${header}\n${numbered}`;
+    } catch (err: unknown) {
+      return `Error reading file: ${err instanceof Error ? err.message : String(err)}`;
+    }
+  },
+};

package/src/tools/registry.ts

@@ -0,0 +1,41 @@
+import type { ToolDefinition, ToolHandler } from "../types.js";
+import { readFileTool } from "./read-file.js";
+import { writeFileTool } from "./write-file.js";
+import { editFileTool } from "./edit-file.js";
+import { runCommandTool } from "./run-command.js";
+import { grepTool } from "./grep.js";
+import { globTool } from "./glob-tool.js";
+import { listDirectoryTool } from "./list-directory.js";
+
+const tools: Map<string, ToolHandler> = new Map();
+
+function register(handler: ToolHandler): void {
+  tools.set(handler.definition.function.name, handler);
+}
+
+register(readFileTool);
+register(writeFileTool);
+register(editFileTool);
+register(runCommandTool);
+register(grepTool);
+register(globTool);
+register(listDirectoryTool);
+
+export function getToolHandler(name: string): ToolHandler | undefined {
+  return tools.get(name);
+}
+
+export function getAllDefinitions(): ToolDefinition[] {
+  return Array.from(tools.values()).map((t) => t.definition);
+}
+
+export function executeToolCall(
+  name: string,
+  args: Record<string, unknown>
+): Promise<string> {
+  const handler = tools.get(name);
+  if (!handler) {
+    return Promise.resolve(`Error: Unknown tool "${name}"`);
+  }
+  return handler.execute(args);
+}

package/src/tools/run-command.ts

@@ -0,0 +1,99 @@
+import { resolve } from "path";
+import type { ToolHandler } from "../types.js";
+import { DEFAULT_COMMAND_TIMEOUT, MAX_COMMAND_TIMEOUT, MAX_OUTPUT_BYTES } from "../constants.js";
+
+export const runCommandTool: ToolHandler = {
+  definition: {
+    type: "function",
+    function: {
+      name: "runCommand",
+      description:
+        "Execute a shell command and return its output. Default timeout is 30s and hard-capped at 45s. Output is truncated at 50KB.",
+      parameters: {
+        type: "object",
+        properties: {
+          command: {
+            type: "string",
+            description: "The shell command to execute",
+          },
+          cwd: {
+            type: "string",
+            description: "Working directory for the command. Default: current directory",
+          },
+          timeout: {
+            type: "number",
+            description: "Timeout in milliseconds. Default: 30000, max: 45000",
+          },
+        },
+        required: ["command"],
+      },
+    },
+  },
+
+  async execute(args) {
+    const command = String(args.command);
+    const cwd = args.cwd ? resolve(String(args.cwd)) : process.cwd();
+    const requestedTimeout = Number(args.timeout) || DEFAULT_COMMAND_TIMEOUT;
+    const timeout = Math.min(Math.max(1_000, requestedTimeout), MAX_COMMAND_TIMEOUT);
+
+    try {
+      const proc = Bun.spawn(["sh", "-c", command], {
+        stdout: "pipe",
+        stderr: "pipe",
+        cwd,
+        env: { ...process.env },
+      });
+
+      let timedOut = false;
+      const timer = setTimeout(() => {
+        timedOut = true;
+        try {
+          proc.kill(9);
+        } catch {
+          // Process may already have exited.
+        }
+      }, timeout);
+
+      const exitCode = await Promise.race([
+        proc.exited,
+        new Promise<number>((resolveTimeout) => {
+          setTimeout(() => resolveTimeout(-1), timeout + 250);
+        }),
+      ]);
+
+      clearTimeout(timer);
+
+      if (timedOut || exitCode === -1) {
+        return [
+          `Exit code: 124`,
+          `STDERR:`,
+          `Command timed out after ${Math.round(timeout / 1000)}s.`,
+          `Tip: use a shorter command, reduce scope, or run background/dev servers manually outside kalcode.`,
+        ].join("\n\n");
+      }
+
+      const [stdoutBuf, stderrBuf] = await Promise.all([
+        new Response(proc.stdout).arrayBuffer(),
+        new Response(proc.stderr).arrayBuffer(),
+      ]);
+
+      let stdout = new TextDecoder().decode(stdoutBuf);
+      let stderr = new TextDecoder().decode(stderrBuf);
+
+      if (stdout.length > MAX_OUTPUT_BYTES) {
+        stdout = stdout.slice(0, MAX_OUTPUT_BYTES) + "\n... (output truncated)";
+      }
+      if (stderr.length > MAX_OUTPUT_BYTES) {
+        stderr = stderr.slice(0, MAX_OUTPUT_BYTES) + "\n... (output truncated)";
+      }
+
+      let result = `Exit code: ${exitCode}`;
+      if (stdout.trim()) result += `\n\nSTDOUT:\n${stdout.trim()}`;
+      if (stderr.trim()) result += `\n\nSTDERR:\n${stderr.trim()}`;
+
+      return result;
+    } catch (err: unknown) {
+      return `Error running command: ${err instanceof Error ? err.message : String(err)}`;
+    }
+  },
+};