baller-maester 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-05-21
+
+### Added
+- **Connector env-var seeding into MCP host registrations.** The Codex CLI writer now emits `env_vars = ["NAME", ...]` inside `[mcp_servers.maester]` (Codex's native shell pass-through). The Claude Code writer now emits an `env` block under `mcpServers.maester` with `"NAME": "${NAME:-}"` placeholders (Claude Code's native `${VAR}` expansion; the `:-` empty-default form prevents `.mcp.json` parse failures when a var is unset). Cursor — which has no working config-file pass-through — relies on its parent-process env inheritance instead; the installed Grand Maester Cursor rule now lists the required env-var names so users know what to export in the shell that launches Cursor. Closes the gap where a connector configured with `auth: { type: "token", envVar: "GITLAB_TOKEN" }` failed every tool call with `missing-env-var` even when the user had exported the variable in their shell.
+- **Union semantics for the maester block.** The framework owns the set of env-var names derived from `citadel.connectors[*].auth.envVar` and persists a small `_maester_managed_env_vars` (Codex) / `_maesterManagedEnv` (Claude Code) marker so the next refresh can distinguish framework-managed entries (which should be stripped when no connector still references them) from user-added entries (which are preserved verbatim across refreshes). De-duped and stable-sorted so output is byte-identical between refreshes. No env-var values are ever written to any file maester produces — names only.
+
 ## [0.4.2] - 2026-05-21
 
 ### Changed

package/dist/cli/main.js

@@ -1643,10 +1643,39 @@ function decideAction(existing, previousVersion, newVersion, newContent) {
   return "upgraded";
 }
 
+// src/core/mcp/registrations/env-vars.ts
+var EMPTY = { managed: [], invalid: [] };
+function collectConnectorEnvVars(connectors) {
+  if (!connectors || connectors.length === 0) return EMPTY;
+  const seen = /* @__PURE__ */ new Set();
+  const invalid = [];
+  for (const c of connectors) {
+    if (!c.auth || c.auth.type !== "token") continue;
+    const name = c.auth.envVar;
+    if (!ENV_VAR_RE.test(name)) {
+      invalid.push({ connector: c.name, envVar: name });
+      continue;
+    }
+    seen.add(name);
+  }
+  return { managed: Array.from(seen).sort(), invalid };
+}
+async function loadConnectorEnvVarsBestEffort(repoRoot) {
+  try {
+    const config = await loadCitadelConfig(repoRoot);
+    return collectConnectorEnvVars(config.connectors);
+  } catch (err) {
+    const code = err.code;
+    const message = err instanceof Error ? err.message : String(err);
+    if (code === "ENOENT" || /No citadel\.yaml/.test(message)) return EMPTY;
+    return { ...EMPTY, loadError: message };
+  }
+}
+
 // src/core/skill/templates/shells/cursor.ts
 var DESCRIPTION = "Citadel-aware guidance for reading aggregated documentation under the citadel base directory.";
 function renderCursorRuleBody(opts) {
-  return [
+  const sections = [
     "# Grand Maester (Cursor rule)",
     "",
     "This rule applies when the user asks about content under the citadel",
@@ -1659,6 +1688,25 @@ function renderCursorRuleBody(opts) {
     interpolate3(freshness_awareness_default, opts),
     "",
     interpolate3(connector_policy_default, opts)
+  ];
+  if (opts.requiredEnvVars && opts.requiredEnvVars.length > 0) {
+    sections.push("", renderRequiredEnvVarsNote(opts.requiredEnvVars));
+  }
+  return sections.join("\n");
+}
+function renderRequiredEnvVarsNote(envVars) {
+  const sorted = [...envVars].sort();
+  const list = sorted.map((v) => `\`${v}\``).join(", ");
+  return [
+    "## Required environment variables (Cursor)",
+    "",
+    `This citadel exposes connectors that require these env vars: ${list}.`,
+    "",
+    "Cursor inherits env vars from the shell that launches it, so export them in",
+    "that shell (e.g. in your `~/.zshrc` / `~/.bashrc` or by launching Cursor",
+    "from a terminal where they are already set). The maester MCP server reads",
+    "each value at tool-invocation time; if a var is unset, the call returns a",
+    "`missing-env-var` envelope naming the variable."
   ].join("\n");
 }
 function renderCursorRuleFile(body, opts) {
@@ -1691,7 +1739,11 @@ async function writeCursor(input) {
   await promises.mkdir(path8.dirname(filePath), { recursive: true });
   const existing = await readTextOrUndefined3(filePath);
   const previousVersion = existing ? extractMarkdownRegion(existing)?.version : void 0;
-  const body = renderCursorRuleBody({ baseDir: input.citadelBaseDir });
+  const envVars = await loadConnectorEnvVarsBestEffort(input.repoRoot);
+  const body = renderCursorRuleBody({
+    baseDir: input.citadelBaseDir,
+    requiredEnvVars: envVars.managed
+  });
   const next = existing ? replaceMarkdownRegion(existing, body, input.skillVersion) : `${renderCursorRuleFile(
     replaceMarkdownRegion(void 0, body, input.skillVersion).trimEnd(),
     {
@@ -1856,58 +1908,92 @@ function resolveMaesterLaunchCommand() {
 
 // src/core/mcp/registrations/claude-code.ts
 var MCP_FILE = ".mcp.json";
-function maesterEntry(launch) {
-  return { command: launch.command, args: [...launch.args] };
+var MANAGED_MARKER_KEY = "_maesterManagedEnv";
+function maesterEntry(launch, envObject, managed) {
+  const entry = { command: launch.command, args: [...launch.args] };
+  if (Object.keys(envObject).length > 0) entry.env = envObject;
+  if (managed.length > 0) entry[MANAGED_MARKER_KEY] = [...managed];
+  return entry;
 }
 async function writeClaudeCodeMcpEntry(repoRoot, options = {}) {
   const launch = options.launch ?? resolveMaesterLaunchCommand();
-  return writeJsonMcpFile(path8.join(repoRoot, MCP_FILE), launch);
+  return writeJsonMcpFile(path8.join(repoRoot, MCP_FILE), launch, options.connectorEnvVars ?? []);
 }
-async function writeJsonMcpFile(filePath, launch) {
+async function writeJsonMcpFile(filePath, launch, connectorEnvVars = []) {
   await promises.mkdir(path8.dirname(filePath), { recursive: true });
   const existingText = await readOrUndefined(filePath);
-  const newText = renderJsonWithMaesterEntry(existingText, launch);
+  const newText = renderJsonWithMaesterEntry(existingText, launch, connectorEnvVars);
   if (existingText === newText) {
     return { filePath, action: "unchanged" };
   }
   await promises.writeFile(filePath, newText, "utf8");
   return { filePath, action: "written" };
 }
-function renderJsonWithMaesterEntry(existingText, launch) {
+function renderJsonWithMaesterEntry(existingText, launch, connectorEnvVars = []) {
   const parsed = parseOrEmpty(existingText);
   const rebuilt = {};
   let placed = false;
   for (const [key, value] of Object.entries(parsed)) {
     if (key === "mcpServers") {
-      rebuilt[key] = mutateMcpServers(value, launch);
+      rebuilt[key] = mutateMcpServers(value, launch, connectorEnvVars);
       placed = true;
     } else {
       rebuilt[key] = value;
     }
   }
   if (!placed) {
-    rebuilt.mcpServers = mutateMcpServers(void 0, launch);
+    rebuilt.mcpServers = mutateMcpServers(void 0, launch, connectorEnvVars);
   }
   return `${JSON.stringify(rebuilt, null, 2)}
 `;
 }
-function mutateMcpServers(existing, launch) {
+function mutateMcpServers(existing, launch, connectorEnvVars) {
   const map = isPlainObject(existing) ? { ...existing } : {};
   const rebuilt = {};
+  const managedSorted = [...connectorEnvVars].sort();
   let placed = false;
   for (const [key, value] of Object.entries(map)) {
     if (key === "maester") {
-      rebuilt[key] = maesterEntry(launch);
+      const mergedEnv = mergeEnvObject(value, connectorEnvVars);
+      rebuilt[key] = maesterEntry(launch, mergedEnv, managedSorted);
       placed = true;
     } else {
       rebuilt[key] = value;
     }
   }
   if (!placed) {
-    rebuilt.maester = maesterEntry(launch);
+    const mergedEnv = mergeEnvObject(void 0, connectorEnvVars);
+    rebuilt.maester = maesterEntry(launch, mergedEnv, managedSorted);
   }
   return rebuilt;
 }
+function mergeEnvObject(existingMaesterEntry, connectorEnvVars) {
+  const result = {};
+  const managed = new Set(connectorEnvVars);
+  const previouslyManaged = readStringArray(
+    isPlainObject(existingMaesterEntry) ? existingMaesterEntry[MANAGED_MARKER_KEY] : void 0
+  );
+  const previouslyManagedSet = new Set(previouslyManaged);
+  const existingEnv = isPlainObject(existingMaesterEntry) ? existingMaesterEntry.env : void 0;
+  if (isPlainObject(existingEnv)) {
+    for (const [k, v] of Object.entries(existingEnv)) {
+      if (managed.has(k)) continue;
+      if (previouslyManagedSet.has(k)) continue;
+      if (typeof v === "string") result[k] = v;
+    }
+  }
+  for (const name of managed) result[name] = `\${${name}:-}`;
+  const sorted = {};
+  for (const k of Object.keys(result).sort()) {
+    const v = result[k];
+    if (v !== void 0) sorted[k] = v;
+  }
+  return sorted;
+}
+function readStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((v) => typeof v === "string" && v.length > 0);
+}
 function parseOrEmpty(text2) {
   if (!text2 || text2.trim().length === 0) return {};
   const parsed = JSON.parse(text2);
@@ -1928,28 +2014,51 @@ async function readOrUndefined(filePath) {
   }
 }
 var CONFIG_FILE = path8.join(".codex", "config.toml");
-function maesterBlock(launch) {
-  return { command: launch.command, args: [...launch.args] };
+var MANAGED_MARKER_KEY2 = "_maester_managed_env_vars";
+function maesterBlock(launch, envVars, managed) {
+  const block = { command: launch.command, args: [...launch.args] };
+  if (envVars.length > 0) block.env_vars = [...envVars];
+  if (managed.length > 0) block[MANAGED_MARKER_KEY2] = [...managed];
+  return block;
 }
 async function writeCodexMcpEntry(repoRoot, options = {}) {
   const filePath = path8.join(repoRoot, CONFIG_FILE);
   await promises.mkdir(path8.dirname(filePath), { recursive: true });
   const existingText = await readOrUndefined2(filePath);
   const launch = options.launch ?? resolveMaesterLaunchCommand();
-  const newText = renderTomlWithMaesterBlock(existingText, launch);
+  const newText = renderTomlWithMaesterBlock(existingText, launch, options.connectorEnvVars ?? []);
   if (existingText === newText) {
     return { filePath, action: "unchanged" };
   }
   await promises.writeFile(filePath, newText, "utf8");
   return { filePath, action: "written" };
 }
-function renderTomlWithMaesterBlock(existingText, launch) {
+function renderTomlWithMaesterBlock(existingText, launch, connectorEnvVars = []) {
   const parsed = existingText && existingText.trim().length > 0 ? TOML.parse(existingText) : {};
   const mcpServers = isJsonMap(parsed.mcp_servers) ? { ...parsed.mcp_servers } : {};
-  mcpServers.maester = maesterBlock(launch);
+  const existingMaester = isJsonMap(mcpServers.maester) ? mcpServers.maester : void 0;
+  const previouslyManaged = readStringArray2(existingMaester?.[MANAGED_MARKER_KEY2]);
+  const userAdded = userAddedEnvVars(existingMaester?.env_vars, previouslyManaged);
+  const mergedEnvVars = Array.from(/* @__PURE__ */ new Set([...connectorEnvVars, ...userAdded])).sort();
+  mcpServers.maester = maesterBlock(launch, mergedEnvVars, [...connectorEnvVars].sort());
   const next = { ...parsed, mcp_servers: mcpServers };
   return TOML.stringify(next);
 }
+function userAddedEnvVars(existing, previouslyManaged) {
+  if (!Array.isArray(existing)) return [];
+  const managedSet = new Set(previouslyManaged);
+  const result = [];
+  for (const entry of existing) {
+    if (typeof entry !== "string" || entry.length === 0) continue;
+    if (managedSet.has(entry)) continue;
+    result.push(entry);
+  }
+  return result;
+}
+function readStringArray2(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((v) => typeof v === "string" && v.length > 0);
+}
 function isJsonMap(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -1964,7 +2073,7 @@ async function readOrUndefined2(filePath) {
 var MCP_FILE2 = path8.join(".cursor", "mcp.json");
 async function writeCursorMcpEntry(repoRoot, options = {}) {
   const launch = options.launch ?? resolveMaesterLaunchCommand();
-  return writeJsonMcpFile(path8.join(repoRoot, MCP_FILE2), launch);
+  return writeJsonMcpFile(path8.join(repoRoot, MCP_FILE2), launch, []);
 }
 
 // src/core/mcp/registrations/index.ts
@@ -1972,13 +2081,15 @@ async function refreshMcpRegistrations(repoRoot, options = {}) {
   const targets = listSkillTargets().filter(
     (t) => isMcpHost(t.id) && (!options.scopeTo || options.scopeTo.includes(t.id))
   );
+  const envVars = await loadConnectorEnvVarsBestEffort(repoRoot);
+  surfaceEnvVarDiagnostics(envVars);
   const outcomes = [];
   for (const target of targets) {
     const installedVersion = await target.readInstalledVersion(repoRoot);
     if (installedVersion === void 0 && !options.scopeTo?.includes(target.id)) {
       continue;
     }
-    const outcome = await runWriter(target, repoRoot);
+    const outcome = await runWriter(target, repoRoot, envVars.managed);
     outcomes.push(outcome);
   }
   return outcomes;
@@ -1986,11 +2097,11 @@ async function refreshMcpRegistrations(repoRoot, options = {}) {
 function isMcpHost(id) {
   return id === "claude-code" || id === "cursor" || id === "codex";
 }
-async function runWriter(target, repoRoot) {
+async function runWriter(target, repoRoot, connectorEnvVars) {
   try {
     switch (target.id) {
       case "claude-code": {
-        const r = await writeClaudeCodeMcpEntry(repoRoot);
+        const r = await writeClaudeCodeMcpEntry(repoRoot, { connectorEnvVars });
         return { host: "claude-code", filePath: r.filePath, action: r.action };
       }
       case "cursor": {
@@ -1998,7 +2109,7 @@ async function runWriter(target, repoRoot) {
         return { host: "cursor", filePath: r.filePath, action: r.action };
       }
       case "codex": {
-        const r = await writeCodexMcpEntry(repoRoot);
+        const r = await writeCodexMcpEntry(repoRoot, { connectorEnvVars });
         return { host: "codex", filePath: r.filePath, action: r.action };
       }
       default:
@@ -2017,6 +2128,20 @@ async function runWriter(target, repoRoot) {
     };
   }
 }
+function surfaceEnvVarDiagnostics(envVars) {
+  if (envVars.loadError !== void 0) {
+    process.stderr.write(
+      `maester: warning: citadel.yaml could not be loaded for MCP env-var seeding (${envVars.loadError}); writing entries without connector env vars.
+`
+    );
+  }
+  for (const entry of envVars.invalid) {
+    process.stderr.write(
+      `maester: warning: connector '${entry.connector}' declares env-var '${entry.envVar}' which is not a valid name (uppercase letters, digits, underscore, starting with a letter); skipping.
+`
+    );
+  }
+}
 
 // src/cli/commands/connector.ts
 var EXIT_OK = 0;
@@ -2518,7 +2643,7 @@ function validateTag(value) {
 
 // package.json
 var package_default = {
-  version: "0.4.2"};
+  version: "0.5.0"};
 var PACKAGE_VERSION = package_default.version;
 
 // src/core/skill/version.ts