@kalera/munin-runtime 1.2.5 → 1.2.6

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @kalera/munin-runtime@1.2.5 build /home/runner/work/munin-for-agents/munin-for-agents/packages/runtime
+> @kalera/munin-runtime@1.2.6 build /home/runner/work/munin-for-agents/munin-for-agents/packages/runtime
 > tsc -p tsconfig.json
 

package/dist/env.d.ts

@@ -10,5 +10,28 @@ export declare function resolveEncryptionKey(): string | undefined;
  * Upsert key=value pairs into a .env file.
  * - Existing keys are replaced.
  * - New keys are appended.
+ * - Keys are matched via string split (not regex) to prevent injection.
  */
 export declare function writeEnvFile(filename: string, vars: EnvVar[], cwd?: string): void;
+/**
+ * Resolve MUNIN_PROJECT from multiple sources, in priority order:
+ * 1. Explicit environment variable
+ * 2. .env.local in any ancestor directory (walk-up from CWD)
+ * 3. .env in any ancestor directory (walk-up from CWD)
+ */
+export declare function resolveProjectId(): string | undefined;
+export interface CliEnv {
+    baseUrl: string;
+    apiKey: string | undefined;
+    timeoutMs: number;
+    retries: number;
+    backoffMs: number;
+}
+export declare function loadCliEnv(): CliEnv;
+export declare function executeWithRetry<T>(task: () => Promise<T>, retries: number, backoffMs: number): Promise<T>;
+export declare function safeError(error: unknown): Record<string, unknown>;
+export declare function parseCliArgs(argv: string[], usage: string): {
+    action: string;
+    payload: Record<string, unknown>;
+};
+export * from "./mcp-server.js";

package/dist/env.js

@@ -1,34 +1,201 @@
 import * as fs from "fs";
 import * as path from "path";
+const REDACT_KEYS = ["apiKey", "authorization", "token", "secret", "password"];
 /**
  * Resolve the encryption key for E2EE projects from MUNIN_ENCRYPTION_KEY env var.
  */
 export function resolveEncryptionKey() {
     return process.env.MUNIN_ENCRYPTION_KEY;
 }
+/**
+ * Escape shell/metacharacters that could inject into a .env value.
+ * Escapes: $, backticks, \, and newlines — in addition to double quotes.
+ */
+function escapeEnvValue(value) {
+    return value
+        .replace(/\\/g, "\\\\") // escape backslashes first
+        .replace(/\n/g, "\\n") // escape newlines
+        .replace(/\r/g, "\\r") // escape carriage returns
+        .replace(/`/g, "\\`") // escape backticks
+        .replace(/\$/g, "\\$") // escape dollar signs
+        .replace(/"/g, '\\"'); // escape double quotes
+}
+/**
+ * Parse a .env line, returning { key, value } or null if not a valid assignment.
+ * Uses a string-based split instead of regex to avoid injection from .env content.
+ */
+function parseEnvLine(line) {
+    // Skip empty lines and comments
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#"))
+        return null;
+    const eqIndex = trimmed.indexOf("=");
+    if (eqIndex === -1)
+        return null;
+    const key = trimmed.slice(0, eqIndex).trim();
+    // Value is everything after the first '=' (unquoted, no regex)
+    const rawValue = trimmed.slice(eqIndex + 1);
+    return { key, value: rawValue };
+}
 /**
  * Upsert key=value pairs into a .env file.
  * - Existing keys are replaced.
  * - New keys are appended.
+ * - Keys are matched via string split (not regex) to prevent injection.
  */
 export function writeEnvFile(filename, vars, cwd = process.cwd()) {
     const filePath = path.resolve(cwd, filename);
-    let lines = [];
+    const lines = [];
     if (fs.existsSync(filePath)) {
-        lines = fs.readFileSync(filePath, "utf8").split("\n");
+        const content = fs.readFileSync(filePath, "utf8");
+        for (const line of content.split("\n")) {
+            const parsed = parseEnvLine(line);
+            // Remove lines that match any key we're about to upsert
+            if (parsed && vars.some((v) => v.key === parsed.key))
+                continue;
+            lines.push(line);
+        }
     }
     for (const { key, value } of vars) {
-        const escapedValue = value.replace(/"/g, '\\"');
-        const newLine = `${key}="${escapedValue}"`;
-        const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-        const regex = new RegExp(`^${escapedKey}\\s*=.+$`, "m");
-        const idx = lines.findIndex((l) => regex.test(l));
-        if (idx !== -1) {
-            lines[idx] = newLine;
+        const escapedValue = escapeEnvValue(value);
+        lines.push(`${key}="${escapedValue}"`);
+    }
+    fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+}
+/**
+ * Safe numeric env parser: returns defaultVal if value is missing or NaN.
+ */
+function safeParseInt(envVal, defaultVal) {
+    if (envVal === undefined)
+        return defaultVal;
+    const parsed = Number(envVal);
+    if (isNaN(parsed))
+        return defaultVal;
+    return parsed;
+}
+/**
+ * Walk up the directory tree from `startDir` (default CWD) toward root,
+ * searching each ancestor for `filename`. Returns the value of the first match.
+ * Stops at filesystem root or when a `.git` dir is found (project boundary).
+ */
+function resolveEnvFileUpward(filename, startDir) {
+    let current = startDir ?? process.cwd();
+    let last = "";
+    while (current !== last) {
+        last = current;
+        const filePath = path.join(current, filename);
+        try {
+            if (fs.existsSync(filePath)) {
+                const content = fs.readFileSync(filePath, "utf8");
+                for (const line of content.split("\n")) {
+                    const trimmed = line.trim();
+                    if (!trimmed.startsWith("MUNIN_PROJECT="))
+                        continue;
+                    return trimmed.slice("MUNIN_PROJECT=".length).trim();
+                }
+            }
         }
-        else {
-            lines.push(newLine);
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                console.error(`[munin-runtime] Failed to read ${filePath}:`, error);
+            }
         }
+        // Stop at git root (project boundary)
+        if (fs.existsSync(path.join(current, ".git")))
+            break;
+        current = path.dirname(current);
+    }
+    return undefined;
+}
+/**
+ * Resolve MUNIN_PROJECT from multiple sources, in priority order:
+ * 1. Explicit environment variable
+ * 2. .env.local in any ancestor directory (walk-up from CWD)
+ * 3. .env in any ancestor directory (walk-up from CWD)
+ */
+export function resolveProjectId() {
+    // 1. Explicit env var (highest priority)
+    if (process.env.MUNIN_PROJECT) {
+        return process.env.MUNIN_PROJECT;
+    }
+    // 2. Walk upward from CWD — find .env.local in any ancestor dir
+    const fromLocal = resolveEnvFileUpward(".env.local");
+    if (fromLocal)
+        return fromLocal;
+    // 3. Walk upward from CWD — find .env in any ancestor dir
+    const fromEnv = resolveEnvFileUpward(".env");
+    if (fromEnv)
+        return fromEnv;
+    return undefined;
+}
+export function loadCliEnv() {
+    return {
+        baseUrl: process.env.MUNIN_BASE_URL || "https://munin.kalera.dev",
+        apiKey: process.env.MUNIN_API_KEY,
+        timeoutMs: safeParseInt(process.env.MUNIN_TIMEOUT_MS, 15_000),
+        retries: safeParseInt(process.env.MUNIN_RETRIES, 3),
+        backoffMs: safeParseInt(process.env.MUNIN_BACKOFF_MS, 300),
+    };
+}
+export async function executeWithRetry(task, retries, backoffMs) {
+    let attempt = 0;
+    let lastError;
+    while (attempt < retries) {
+        try {
+            return await task();
+        }
+        catch (error) {
+            lastError = error;
+            attempt += 1;
+            if (attempt >= retries)
+                break;
+            const jitter = Math.floor(Math.random() * 100);
+            await sleep(backoffMs * 2 ** attempt + jitter);
+        }
+    }
+    throw lastError;
+}
+export function safeError(error) {
+    if (error instanceof Error) {
+        return {
+            name: error.name,
+            message: redactText(error.message),
+        };
+    }
+    return { message: redactText(String(error)) };
+}
+function redactText(text) {
+    return REDACT_KEYS.reduce((acc, key) => {
+        // Replace key=value patterns with key=[REDACTED] using simple string split
+        let result = acc;
+        let idx = result.indexOf(`${key}=`);
+        while (idx !== -1) {
+            const endIdx = result.indexOf(/[\s,;]/.test(result[idx + key.length + 1] ?? "")
+                ? result[idx + key.length + 1]
+                : "");
+            const end = endIdx === -1 ? result.length : endIdx;
+            const before = result.slice(0, idx + key.length + 1);
+            const after = result.slice(end);
+            result = `${before}[REDACTED]${after}`;
+            idx = result.indexOf(`${key}=`, idx + key.length + 1);
+        }
+        return result;
+    }, text);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function parseCliArgs(argv, usage) {
+    const [action, payloadRaw] = argv;
+    if (!action)
+        throw new Error(usage);
+    if (!payloadRaw)
+        return { action, payload: {} };
+    try {
+        return { action, payload: JSON.parse(payloadRaw) };
+    }
+    catch {
+        throw new Error("Payload must be valid JSON");
     }
-    fs.writeFileSync(filePath, lines.join("\n"), "utf8");
 }
+export * from "./mcp-server.js";

package/dist/index.d.ts

@@ -14,8 +14,8 @@ export declare function loadCliEnv(): CliEnv;
 /**
  * Resolve MUNIN_PROJECT from multiple sources, in priority order:
  * 1. Explicit environment variable
- * 2. .env.local in current working directory
- * 3. .env in current working directory
+ * 2. .env.local in any ancestor directory (walk-up from CWD)
+ * 3. .env in any ancestor directory (walk-up from CWD)
  */
 export declare function resolveProjectId(): string | undefined;
 export declare function executeWithRetry<T>(task: () => Promise<T>, retries: number, backoffMs: number): Promise<T>;

package/dist/index.js

@@ -21,68 +21,88 @@ export function loadCliEnv() {
     return {
         baseUrl: process.env.MUNIN_BASE_URL || "https://munin.kalera.dev",
         apiKey: process.env.MUNIN_API_KEY,
-        timeoutMs: Number(process.env.MUNIN_TIMEOUT_MS ?? 15000),
-        retries: Number(process.env.MUNIN_RETRIES ?? 3),
-        backoffMs: Number(process.env.MUNIN_BACKOFF_MS ?? 300),
+        timeoutMs: safeParseInt(process.env.MUNIN_TIMEOUT_MS, 15_000),
+        retries: safeParseInt(process.env.MUNIN_RETRIES, 3),
+        backoffMs: safeParseInt(process.env.MUNIN_BACKOFF_MS, 300),
     };
 }
+function safeParseInt(envVal, defaultVal) {
+    if (envVal === undefined)
+        return defaultVal;
+    const parsed = Number(envVal);
+    return isNaN(parsed) ? defaultVal : parsed;
+}
+/**
+ * Walk up the directory tree from `startDir` (default CWD) toward root,
+ * searching each ancestor for `filename`. Returns the value of the first match.
+ * Stops at filesystem root or when a `.git` dir is found (project boundary).
+ */
+function resolveEnvFileUpward(filename, startDir) {
+    const fs = require("fs");
+    const path = require("path");
+    let current = startDir ?? process.cwd();
+    let last = "";
+    while (current !== last) {
+        last = current;
+        const filePath = path.join(current, filename);
+        try {
+            if (fs.existsSync(filePath)) {
+                const content = fs.readFileSync(filePath, "utf8");
+                for (const line of content.split("\n")) {
+                    const trimmed = line.trim();
+                    if (!trimmed.startsWith("MUNIN_PROJECT="))
+                        continue;
+                    return trimmed.slice("MUNIN_PROJECT=".length).trim();
+                }
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                console.error(`[munin-runtime] Failed to read ${filePath}:`, error);
+            }
+        }
+        // Stop at git root (project boundary)
+        if (fs.existsSync(path.join(current, ".git")))
+            break;
+        current = path.dirname(current);
+    }
+    return undefined;
+}
 /**
  * Resolve MUNIN_PROJECT from multiple sources, in priority order:
  * 1. Explicit environment variable
- * 2. .env.local in current working directory
- * 3. .env in current working directory
+ * 2. .env.local in any ancestor directory (walk-up from CWD)
+ * 3. .env in any ancestor directory (walk-up from CWD)
  */
 export function resolveProjectId() {
     // 1. Explicit env var (highest priority)
     if (process.env.MUNIN_PROJECT) {
         return process.env.MUNIN_PROJECT;
     }
-    // 2. .env.local in CWD
-    const envLocal = resolveEnvFile(".env.local");
-    if (envLocal)
-        return envLocal;
-    // 3. .env in CWD
-    const envFile = resolveEnvFile(".env");
-    if (envFile)
-        return envFile;
-    return undefined;
-}
-/**
- * Read a .env file and extract MUNIN_PROJECT value.
- * Returns undefined if file doesn't exist or value not found.
- */
-function resolveEnvFile(filename) {
-    try {
-        const path = `${process.cwd()}/${filename}`;
-        const fs = require("fs");
-        if (!fs.existsSync(path))
-            return undefined;
-        const content = fs.readFileSync(path, "utf8");
-        const match = content.match(/^MUNIN_PROJECT\s*=\s*(.+)$/m);
-        if (match) {
-            return match[1].trim();
-        }
-    }
-    catch {
-        // Ignore errors — file might be unreadable
-    }
+    // 2. Walk upward from CWD — find .env.local in any ancestor dir
+    const fromLocal = resolveEnvFileUpward(".env.local");
+    if (fromLocal)
+        return fromLocal;
+    // 3. Walk upward from CWD — find .env in any ancestor dir
+    const fromEnv = resolveEnvFileUpward(".env");
+    if (fromEnv)
+        return fromEnv;
     return undefined;
 }
 export async function executeWithRetry(task, retries, backoffMs) {
     let attempt = 0;
     let lastError;
-    while (attempt <= retries) {
+    while (attempt < retries) {
         try {
             return await task();
         }
         catch (error) {
             lastError = error;
-            if (attempt === retries) {
+            attempt += 1;
+            if (attempt >= retries)
                 break;
-            }
             const jitter = Math.floor(Math.random() * 100);
             await sleep(backoffMs * 2 ** attempt + jitter);
-            attempt += 1;
         }
     }
     throw lastError;

package/dist/mcp-server.d.ts

@@ -1,6 +1,8 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { loadCliEnv } from "./index.js";
-export declare function createMcpServerInstance(env: ReturnType<typeof loadCliEnv>): Server<{
+export declare function createMcpServerInstance(env: ReturnType<typeof loadCliEnv>, opts?: {
+    allowMissingApiKey?: boolean;
+}): Server<{
     method: string;
     params?: {
         [x: string]: unknown;

package/dist/mcp-server.js

@@ -3,10 +3,13 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { MuninClient } from "@kalera/munin-sdk";
 import { loadCliEnv, resolveProjectId, resolveEncryptionKey, safeError } from "./index.js";
-export function createMcpServerInstance(env) {
+export function createMcpServerInstance(env, opts) {
+    if (!env.apiKey && !opts?.allowMissingApiKey) {
+        throw new Error("MUNIN_API_KEY is required. Set it in your environment or .env file.");
+    }
     const client = new MuninClient({
         baseUrl: env.baseUrl,
-        apiKey: env.apiKey || 'test-key',
+        apiKey: env.apiKey,
         timeoutMs: env.timeoutMs,
     });
     const server = new Server({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kalera/munin-runtime",
-  "version": "1.2.5",
+  "version": "1.2.6",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,7 +12,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "@kalera/munin-sdk": "1.2.5"
+    "@kalera/munin-sdk": "1.2.6"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/env.ts

@@ -6,6 +6,8 @@ export interface EnvVar {
   value: string;
 }
 
+const REDACT_KEYS = ["apiKey", "authorization", "token", "secret", "password"];
+
 /**
  * Resolve the encryption key for E2EE projects from MUNIN_ENCRYPTION_KEY env var.
  */
@@ -13,10 +15,44 @@ export function resolveEncryptionKey(): string | undefined {
   return process.env.MUNIN_ENCRYPTION_KEY;
 }
 
+/**
+ * Escape shell/metacharacters that could inject into a .env value.
+ * Escapes: $, backticks, \, and newlines — in addition to double quotes.
+ */
+function escapeEnvValue(value: string): string {
+  return value
+    .replace(/\\/g, "\\\\")       // escape backslashes first
+    .replace(/\n/g, "\\n")       // escape newlines
+    .replace(/\r/g, "\\r")       // escape carriage returns
+    .replace(/`/g, "\\`")        // escape backticks
+    .replace(/\$/g, "\\$")       // escape dollar signs
+    .replace(/"/g, '\\"');       // escape double quotes
+}
+
+/**
+ * Parse a .env line, returning { key, value } or null if not a valid assignment.
+ * Uses a string-based split instead of regex to avoid injection from .env content.
+ */
+function parseEnvLine(line: string): EnvVar | null {
+  // Skip empty lines and comments
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith("#")) return null;
+
+  const eqIndex = trimmed.indexOf("=");
+  if (eqIndex === -1) return null;
+
+  const key = trimmed.slice(0, eqIndex).trim();
+  // Value is everything after the first '=' (unquoted, no regex)
+  const rawValue = trimmed.slice(eqIndex + 1);
+
+  return { key, value: rawValue };
+}
+
 /**
  * Upsert key=value pairs into a .env file.
  * - Existing keys are replaced.
  * - New keys are appended.
+ * - Keys are matched via string split (not regex) to prevent injection.
  */
 export function writeEnvFile(
   filename: string,
@@ -24,25 +60,177 @@ export function writeEnvFile(
   cwd: string = process.cwd(),
 ): void {
   const filePath = path.resolve(cwd, filename);
-  let lines: string[] = [];
+  const lines: string[] = [];
 
   if (fs.existsSync(filePath)) {
-    lines = fs.readFileSync(filePath, "utf8").split("\n");
+    const content = fs.readFileSync(filePath, "utf8");
+    for (const line of content.split("\n")) {
+      const parsed = parseEnvLine(line);
+      // Remove lines that match any key we're about to upsert
+      if (parsed && vars.some((v) => v.key === parsed.key)) continue;
+      lines.push(line);
+    }
   }
 
   for (const { key, value } of vars) {
-    const escapedValue = value.replace(/"/g, '\\"');
-    const newLine = `${key}="${escapedValue}"`;
-    const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const regex = new RegExp(`^${escapedKey}\\s*=.+$`, "m");
-
-    const idx = lines.findIndex((l) => regex.test(l));
-    if (idx !== -1) {
-      lines[idx] = newLine;
-    } else {
-      lines.push(newLine);
-    }
+    const escapedValue = escapeEnvValue(value);
+    lines.push(`${key}="${escapedValue}"`);
   }
 
   fs.writeFileSync(filePath, lines.join("\n"), "utf8");
 }
+
+/**
+ * Safe numeric env parser: returns defaultVal if value is missing or NaN.
+ */
+function safeParseInt(envVal: string | undefined, defaultVal: number): number {
+  if (envVal === undefined) return defaultVal;
+  const parsed = Number(envVal);
+  if (isNaN(parsed)) return defaultVal;
+  return parsed;
+}
+
+/**
+ * Walk up the directory tree from `startDir` (default CWD) toward root,
+ * searching each ancestor for `filename`. Returns the value of the first match.
+ * Stops at filesystem root or when a `.git` dir is found (project boundary).
+ */
+function resolveEnvFileUpward(filename: string, startDir?: string): string | undefined {
+  let current = startDir ?? process.cwd();
+  let last = "";
+
+  while (current !== last) {
+    last = current;
+    const filePath = path.join(current, filename);
+    try {
+      if (fs.existsSync(filePath)) {
+        const content = fs.readFileSync(filePath, "utf8");
+        for (const line of content.split("\n")) {
+          const trimmed = line.trim();
+          if (!trimmed.startsWith("MUNIN_PROJECT=")) continue;
+          return trimmed.slice("MUNIN_PROJECT=".length).trim();
+        }
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+        console.error(`[munin-runtime] Failed to read ${filePath}:`, error);
+      }
+    }
+
+    // Stop at git root (project boundary)
+    if (fs.existsSync(path.join(current, ".git"))) break;
+
+    current = path.dirname(current);
+  }
+  return undefined;
+}
+
+/**
+ * Resolve MUNIN_PROJECT from multiple sources, in priority order:
+ * 1. Explicit environment variable
+ * 2. .env.local in any ancestor directory (walk-up from CWD)
+ * 3. .env in any ancestor directory (walk-up from CWD)
+ */
+export function resolveProjectId(): string | undefined {
+  // 1. Explicit env var (highest priority)
+  if (process.env.MUNIN_PROJECT) {
+    return process.env.MUNIN_PROJECT;
+  }
+
+  // 2. Walk upward from CWD — find .env.local in any ancestor dir
+  const fromLocal = resolveEnvFileUpward(".env.local");
+  if (fromLocal) return fromLocal;
+
+  // 3. Walk upward from CWD — find .env in any ancestor dir
+  const fromEnv = resolveEnvFileUpward(".env");
+  if (fromEnv) return fromEnv;
+
+  return undefined;
+}
+
+export interface CliEnv {
+  baseUrl: string;
+  apiKey: string | undefined;
+  timeoutMs: number;
+  retries: number;
+  backoffMs: number;
+}
+
+export function loadCliEnv(): CliEnv {
+  return {
+    baseUrl: process.env.MUNIN_BASE_URL || "https://munin.kalera.dev",
+    apiKey: process.env.MUNIN_API_KEY,
+    timeoutMs: safeParseInt(process.env.MUNIN_TIMEOUT_MS, 15_000),
+    retries: safeParseInt(process.env.MUNIN_RETRIES, 3),
+    backoffMs: safeParseInt(process.env.MUNIN_BACKOFF_MS, 300),
+  };
+}
+
+export async function executeWithRetry<T>(
+  task: () => Promise<T>,
+  retries: number,
+  backoffMs: number,
+): Promise<T> {
+  let attempt = 0;
+  let lastError: unknown;
+
+  while (attempt < retries) {
+    try {
+      return await task();
+    } catch (error) {
+      lastError = error;
+      attempt += 1;
+      if (attempt >= retries) break;
+      const jitter = Math.floor(Math.random() * 100);
+      await sleep(backoffMs * 2 ** attempt + jitter);
+    }
+  }
+
+  throw lastError;
+}
+
+export function safeError(error: unknown): Record<string, unknown> {
+  if (error instanceof Error) {
+    return {
+      name: error.name,
+      message: redactText(error.message),
+    };
+  }
+  return { message: redactText(String(error)) };
+}
+
+function redactText(text: string): string {
+  return REDACT_KEYS.reduce((acc, key) => {
+    // Replace key=value patterns with key=[REDACTED] using simple string split
+    let result = acc;
+    let idx = result.indexOf(`${key}=`);
+    while (idx !== -1) {
+      const endIdx = result.indexOf(/[\s,;]/.test(result[idx + key.length + 1] ?? "")
+        ? result[idx + key.length + 1]
+        : "");
+      const end = endIdx === -1 ? result.length : endIdx;
+      const before = result.slice(0, idx + key.length + 1);
+      const after = result.slice(end);
+      result = `${before}[REDACTED]${after}`;
+      idx = result.indexOf(`${key}=`, idx + key.length + 1);
+    }
+    return result;
+  }, text);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function parseCliArgs(argv: string[], usage: string): { action: string; payload: Record<string, unknown> } {
+  const [action, payloadRaw] = argv;
+  if (!action) throw new Error(usage);
+  if (!payloadRaw) return { action, payload: {} };
+  try {
+    return { action, payload: JSON.parse(payloadRaw) as Record<string, unknown> };
+  } catch {
+    throw new Error("Payload must be valid JSON");
+  }
+}
+
+export * from "./mcp-server.js";

package/src/index.ts

@@ -37,17 +37,61 @@ export function loadCliEnv(): CliEnv {
   return {
     baseUrl: process.env.MUNIN_BASE_URL || "https://munin.kalera.dev",
     apiKey: process.env.MUNIN_API_KEY,
-    timeoutMs: Number(process.env.MUNIN_TIMEOUT_MS ?? 15000),
-    retries: Number(process.env.MUNIN_RETRIES ?? 3),
-    backoffMs: Number(process.env.MUNIN_BACKOFF_MS ?? 300),
+    timeoutMs: safeParseInt(process.env.MUNIN_TIMEOUT_MS, 15_000),
+    retries: safeParseInt(process.env.MUNIN_RETRIES, 3),
+    backoffMs: safeParseInt(process.env.MUNIN_BACKOFF_MS, 300),
   };
 }
 
+function safeParseInt(envVal: string | undefined, defaultVal: number): number {
+  if (envVal === undefined) return defaultVal;
+  const parsed = Number(envVal);
+  return isNaN(parsed) ? defaultVal : parsed;
+}
+
+/**
+ * Walk up the directory tree from `startDir` (default CWD) toward root,
+ * searching each ancestor for `filename`. Returns the value of the first match.
+ * Stops at filesystem root or when a `.git` dir is found (project boundary).
+ */
+function resolveEnvFileUpward(filename: string, startDir?: string): string | undefined {
+  const fs = require("fs") as typeof import("fs");
+  const path = require("path") as typeof import("path");
+
+  let current = startDir ?? process.cwd();
+  let last = "";
+
+  while (current !== last) {
+    last = current;
+    const filePath = path.join(current, filename);
+    try {
+      if (fs.existsSync(filePath)) {
+        const content = fs.readFileSync(filePath, "utf8");
+        for (const line of content.split("\n")) {
+          const trimmed = line.trim();
+          if (!trimmed.startsWith("MUNIN_PROJECT=")) continue;
+          return trimmed.slice("MUNIN_PROJECT=".length).trim();
+        }
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+        console.error(`[munin-runtime] Failed to read ${filePath}:`, error);
+      }
+    }
+
+    // Stop at git root (project boundary)
+    if (fs.existsSync(path.join(current, ".git"))) break;
+
+    current = path.dirname(current);
+  }
+  return undefined;
+}
+
 /**
  * Resolve MUNIN_PROJECT from multiple sources, in priority order:
  * 1. Explicit environment variable
- * 2. .env.local in current working directory
- * 3. .env in current working directory
+ * 2. .env.local in any ancestor directory (walk-up from CWD)
+ * 3. .env in any ancestor directory (walk-up from CWD)
  */
 export function resolveProjectId(): string | undefined {
   // 1. Explicit env var (highest priority)
@@ -55,37 +99,17 @@ export function resolveProjectId(): string | undefined {
     return process.env.MUNIN_PROJECT;
   }
 
-  // 2. .env.local in CWD
-  const envLocal = resolveEnvFile(".env.local");
-  if (envLocal) return envLocal;
+  // 2. Walk upward from CWD — find .env.local in any ancestor dir
+  const fromLocal = resolveEnvFileUpward(".env.local");
+  if (fromLocal) return fromLocal;
 
-  // 3. .env in CWD
-  const envFile = resolveEnvFile(".env");
-  if (envFile) return envFile;
+  // 3. Walk upward from CWD — find .env in any ancestor dir
+  const fromEnv = resolveEnvFileUpward(".env");
+  if (fromEnv) return fromEnv;
 
   return undefined;
 }
 
-/**
- * Read a .env file and extract MUNIN_PROJECT value.
- * Returns undefined if file doesn't exist or value not found.
- */
-function resolveEnvFile(filename: string): string | undefined {
-  try {
-    const path = `${process.cwd()}/${filename}`;
-    const fs = require("fs") as typeof import("fs");
-    if (!fs.existsSync(path)) return undefined;
-
-    const content = fs.readFileSync(path, "utf8");
-    const match = content.match(/^MUNIN_PROJECT\s*=\s*(.+)$/m);
-    if (match) {
-      return match[1].trim();
-    }
-  } catch {
-    // Ignore errors — file might be unreadable
-  }
-  return undefined;
-}
 
 export async function executeWithRetry<T>(
   task: () => Promise<T>,
@@ -95,17 +119,15 @@ export async function executeWithRetry<T>(
   let attempt = 0;
   let lastError: unknown;
 
-  while (attempt <= retries) {
+  while (attempt < retries) {
     try {
       return await task();
     } catch (error) {
       lastError = error;
-      if (attempt === retries) {
-        break;
-      }
+      attempt += 1;
+      if (attempt >= retries) break;
       const jitter = Math.floor(Math.random() * 100);
       await sleep(backoffMs * 2 ** attempt + jitter);
-      attempt += 1;
     }
   }
 

package/src/mcp-server.ts

@@ -7,10 +7,19 @@ import {
 import { MuninClient } from "@kalera/munin-sdk";
 import { loadCliEnv, resolveProjectId, resolveEncryptionKey, safeError } from "./index.js";
 
-export function createMcpServerInstance(env: ReturnType<typeof loadCliEnv>) {
+export function createMcpServerInstance(
+  env: ReturnType<typeof loadCliEnv>,
+  opts?: { allowMissingApiKey?: boolean },
+) {
+  if (!env.apiKey && !opts?.allowMissingApiKey) {
+    throw new Error(
+      "MUNIN_API_KEY is required. Set it in your environment or .env file.",
+    );
+  }
+
   const client = new MuninClient({
     baseUrl: env.baseUrl,
-    apiKey: env.apiKey || 'test-key',
+    apiKey: env.apiKey,
     timeoutMs: env.timeoutMs,
   });