@stigmer/cli 3.1.5 → 3.1.7

package/src/resources/connect/discover.test.ts

@@ -8,8 +8,9 @@
 import { create } from "@bufbuild/protobuf";
 import { McpServerSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
 import { fileURLToPath } from "node:url";
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
 import { localDiscover } from "./discover.js";
+import { PlaceholderResolutionError } from "../mcp/placeholder-resolver.js";
 
 const FIXTURE = fileURLToPath(new URL("./__fixtures__/stdio-server.mjs", import.meta.url));
 const CRASH_FIXTURE = fileURLToPath(new URL("./__fixtures__/stdio-crash.mjs", import.meta.url));
@@ -20,6 +21,15 @@ function stdioSpec(scriptPath: string) {
   });
 }
 
+// A spec whose args reference ${ALLOWED_DIR}, declared under spec.env — the shape
+// the seedpack filesystem server uses (issue #141).
+function stdioSpecWithPlaceholderArg(scriptPath: string) {
+  return create(McpServerSpecSchema, {
+    serverType: { case: "stdio", value: { command: process.execPath, args: [scriptPath, "${ALLOWED_DIR}"] } },
+    env: { ALLOWED_DIR: { isSecret: false, description: "Directory the server may access" } },
+  });
+}
+
 describe("localDiscover (stdio subprocess)", () => {
   it("discovers tools and resource templates and converts them to proto", async () => {
     const caps = await localDiscover(stdioSpec(FIXTURE), [], 10_000);
@@ -43,3 +53,32 @@ describe("localDiscover (stdio subprocess)", () => {
     await expect(localDiscover(stdioSpec(CRASH_FIXTURE), [], 10_000)).rejects.toThrow(/fixture boom: missing CONFIG/);
   }, 15_000);
 });
+
+describe("localDiscover (${VAR} argument expansion — issue #141)", () => {
+  const original = process.env;
+  afterEach(() => {
+    process.env = original;
+  });
+
+  it("expands a declared ${VAR} arg from --env into the spawned subprocess", async () => {
+    const caps = await localDiscover(stdioSpecWithPlaceholderArg(FIXTURE), ["ALLOWED_DIR=/tmp/allowed"], 10_000);
+    // The fixture echoes the argv it actually received; the resolved value must
+    // reach the subprocess, never the literal placeholder.
+    expect(caps.tools[0].description).toContain('args=["/tmp/allowed"]');
+    expect(caps.tools[0].description).not.toContain("${ALLOWED_DIR}");
+  }, 15_000);
+
+  it("expands a declared ${VAR} arg from the exported shell environment", async () => {
+    process.env = { ...original, ALLOWED_DIR: "/tmp/from-shell" };
+    const caps = await localDiscover(stdioSpecWithPlaceholderArg(FIXTURE), [], 10_000);
+    expect(caps.tools[0].description).toContain('args=["/tmp/from-shell"]');
+  }, 15_000);
+
+  it("rejects with a placeholder error before spawning when the declared var is unset", async () => {
+    process.env = { ...original };
+    delete process.env.ALLOWED_DIR;
+    await expect(localDiscover(stdioSpecWithPlaceholderArg(FIXTURE), [], 10_000)).rejects.toBeInstanceOf(
+      PlaceholderResolutionError,
+    );
+  }, 15_000);
+});

package/src/resources/connect/discover.ts

@@ -21,7 +21,8 @@ import {
 import type { JsonObject } from "@bufbuild/protobuf";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
-import { mergeProcessEnv } from "../mcp/runtime-env.js";
+import { mergeProcessEnv, resolveDeclaredEnvValues } from "../mcp/runtime-env.js";
+import { resolveHeaders, resolvePlaceholders } from "../mcp/placeholder-resolver.js";
 
 /** Discover an MCP server's capabilities locally without persisting to the backend. */
 export async function localDiscover(
@@ -79,13 +80,21 @@ interface BuiltTransport {
 }
 
 async function buildTransport(spec: McpServerSpec, envOverrides: readonly string[]): Promise<BuiltTransport> {
+  // ${VAR} placeholders in args/headers resolve against the exact same env the
+  // backend hands the runner for real connect (declared keys from the OS env +
+  // --env overrides) — so dry-run is a faithful preview. Resolution is strict:
+  // an unresolved placeholder throws before any subprocess is spawned, matching
+  // the proto contract (never pass a literal "${VAR}" to the server).
+  const resolutionEnv = resolveDeclaredEnvValues(spec.env ?? {}, envOverrides);
+
   if (spec.serverType?.case === "stdio") {
     const { command, args, workingDir } = spec.serverType.value;
     if (command === "") throw new Error("stdio transport requires a command");
+    const resolvedArgs = args.map((arg, i) => resolvePlaceholders(arg, resolutionEnv, `stdio arg[${i}]`));
     const { StdioClientTransport } = await import("@modelcontextprotocol/sdk/client/stdio.js");
     const transport = new StdioClientTransport({
       command,
-      args: [...args],
+      args: resolvedArgs,
       cwd: workingDir !== "" ? workingDir : undefined,
       env: mergeProcessEnv([...envOverrides, ...goRunEnvOverrides(command, args)]),
       // "pipe" exposes the child stderr as a PassThrough immediately, so we can
@@ -104,8 +113,11 @@ async function buildTransport(spec: McpServerSpec, envOverrides: readonly string
     const { url, headers } = spec.serverType.value;
     if (url === "") throw new Error("HTTP transport requires a URL");
     const { StreamableHTTPClientTransport } = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
-    const requestInit = Object.keys(headers).length > 0 ? { headers: { ...headers } } : undefined;
-    const transport = new StreamableHTTPClientTransport(new URL(url), requestInit ? { requestInit } : undefined);
+    const resolvedHeaders = Object.keys(headers).length > 0 ? resolveHeaders(headers, resolutionEnv) : undefined;
+    const transport = new StreamableHTTPClientTransport(
+      new URL(url),
+      resolvedHeaders ? { requestInit: { headers: resolvedHeaders } } : undefined,
+    );
     return { transport, readStderr: () => "" };
   }
 

package/src/resources/mcp/placeholder-resolver.test.ts

@@ -0,0 +1,71 @@
+// Unit tests for the strict ${VAR} placeholder resolver.
+
+import { describe, expect, it } from "vitest";
+import { PlaceholderResolutionError, resolveHeaders, resolvePlaceholders } from "./placeholder-resolver.js";
+
+describe("resolvePlaceholders", () => {
+  it("returns a string with no placeholders unchanged", () => {
+    expect(resolvePlaceholders("/tmp/data.sqlite", {})).toBe("/tmp/data.sqlite");
+  });
+
+  it("resolves a single placeholder from the env map", () => {
+    expect(resolvePlaceholders("${DIR}", { DIR: "/home/me" })).toBe("/home/me");
+  });
+
+  it("resolves a placeholder embedded in surrounding text", () => {
+    expect(resolvePlaceholders("${DB_PATH}/data.sqlite", { DB_PATH: "/var/lib" })).toBe("/var/lib/data.sqlite");
+  });
+
+  it("resolves multiple and adjacent placeholders", () => {
+    expect(resolvePlaceholders("${A}${B}-${A}", { A: "x", B: "y" })).toBe("xy-x");
+  });
+
+  it("resolves to an empty string when the value is empty", () => {
+    // An empty-but-present value is a resolved value, not a missing variable.
+    expect(resolvePlaceholders("[${X}]", { X: "" })).toBe("[]");
+  });
+
+  it("ignores $VAR without braces (only ${VAR} is a placeholder)", () => {
+    expect(resolvePlaceholders("$HOME/bin", { HOME: "/root" })).toBe("$HOME/bin");
+  });
+
+  it("throws PlaceholderResolutionError for an unresolved variable, carrying name + context", () => {
+    let caught: unknown;
+    try {
+      resolvePlaceholders("${MISSING}", { OTHER: "1" }, "stdio arg[2]");
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(PlaceholderResolutionError);
+    const e = caught as PlaceholderResolutionError;
+    expect(e.variableName).toBe("MISSING");
+    expect(e.context).toBe("stdio arg[2]");
+    expect(e.message).toContain("${MISSING}");
+    expect(e.message).toContain("stdio arg[2]");
+  });
+
+  it("throws on the first unresolved variable even when others resolve", () => {
+    expect(() => resolvePlaceholders("${A}-${B}", { A: "ok" })).toThrow(PlaceholderResolutionError);
+  });
+});
+
+describe("resolveHeaders", () => {
+  it("resolves placeholders in every header value", () => {
+    const resolved = resolveHeaders(
+      { Authorization: "Bearer ${TOKEN}", "X-Static": "v1" },
+      { TOKEN: "abc123" },
+    );
+    expect(resolved).toEqual({ Authorization: "Bearer abc123", "X-Static": "v1" });
+  });
+
+  it("throws with the offending header name in the context", () => {
+    let caught: unknown;
+    try {
+      resolveHeaders({ Authorization: "Bearer ${API_KEY}" }, {});
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(PlaceholderResolutionError);
+    expect((caught as PlaceholderResolutionError).message).toContain('header "Authorization"');
+  });
+});

package/src/resources/mcp/placeholder-resolver.ts

@@ -0,0 +1,63 @@
+// Strict placeholder resolver for ${VAR_NAME} syntax in MCP server configs.
+//
+// The MCP server spec (StdioServerConfig.args, HttpServerConfig.headers) allows
+// values to reference declared env vars with ${VAR_NAME}. The proto contract is
+// explicit that resolution is strict: a missing variable must produce a clear
+// error rather than passing a literal "${VAR}" to the subprocess/server.
+//
+// This mirrors the runner's shared resolver (backend/services/runner/src/shared/
+// placeholder-resolver.ts) so `connect --dry-run` (which discovers locally)
+// behaves identically to real connect (which resolves on the runner). Kept
+// intentionally dependency-free and semantically identical so the two can be
+// collapsed into one shared package later without any behavior change.
+
+const PLACEHOLDER_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+export class PlaceholderResolutionError extends Error {
+  constructor(
+    public readonly variableName: string,
+    public readonly context?: string,
+  ) {
+    const where = context ? ` in ${context}` : "";
+    super(
+      `Unresolved placeholder \${${variableName}}${where}: ` +
+        `variable is not present in the execution environment`,
+    );
+    this.name = "PlaceholderResolutionError";
+  }
+}
+
+/**
+ * Resolve all ${VAR_NAME} placeholders in a template string.
+ *
+ * @throws PlaceholderResolutionError if any placeholder cannot be resolved.
+ */
+export function resolvePlaceholders(
+  template: string,
+  envVars: Record<string, string>,
+  context?: string,
+): string {
+  return template.replace(PLACEHOLDER_RE, (_match, varName: string) => {
+    if (varName in envVars) {
+      return envVars[varName];
+    }
+    throw new PlaceholderResolutionError(varName, context);
+  });
+}
+
+/**
+ * Resolve placeholders in every value of a headers map.
+ *
+ * @throws PlaceholderResolutionError if any header value contains an
+ *   unresolvable placeholder.
+ */
+export function resolveHeaders(
+  headers: Record<string, string>,
+  envVars: Record<string, string>,
+): Record<string, string> {
+  const resolved: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    resolved[key] = resolvePlaceholders(value, envVars, `header "${key}"`);
+  }
+  return resolved;
+}

package/src/resources/mcp/runtime-env.test.ts

@@ -4,12 +4,18 @@ import { create } from "@bufbuild/protobuf";
 import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { UsageError } from "../../errors/index.js";
-import { buildRuntimeEnv, mergeProcessEnv, parseEnvOverrides } from "./runtime-env.js";
+import { buildRuntimeEnv, mergeProcessEnv, parseEnvOverrides, resolveDeclaredEnvValues } from "./runtime-env.js";
 
 function serverWithEnv(env: Record<string, { isSecret: boolean }>) {
   return create(McpServerSchema, { metadata: { id: "mcp_1" }, spec: { env } });
 }
 
+// resolveDeclaredEnvValues takes the raw declarations map; the tests only rely on
+// keys being present, so a minimal declaration object is sufficient.
+function decls(...keys: string[]) {
+  return Object.fromEntries(keys.map((k) => [k, { isSecret: false }]));
+}
+
 describe("parseEnvOverrides", () => {
   it("parses KEY=VALUE pairs, preserving '=' in the value", () => {
     expect(parseEnvOverrides(["A=1", "B=x=y"])).toEqual({ A: "1", B: "x=y" });
@@ -66,3 +72,31 @@ describe("mergeProcessEnv", () => {
     expect(merged.NEW).toBe("1");
   });
 });
+
+describe("resolveDeclaredEnvValues", () => {
+  const original = process.env;
+  beforeEach(() => {
+    process.env = { ...original, ALLOWED_DIR: "/from-os", EMPTY_VAR: "" };
+  });
+  afterEach(() => {
+    process.env = original;
+  });
+
+  it("pulls declared keys from the OS environment", () => {
+    expect(resolveDeclaredEnvValues(decls("ALLOWED_DIR"))).toEqual({ ALLOWED_DIR: "/from-os" });
+  });
+
+  it("skips declared keys that are unset or empty in the environment", () => {
+    expect(resolveDeclaredEnvValues(decls("EMPTY_VAR", "MISSING"))).toEqual({});
+  });
+
+  it("lets --env overrides win over the OS environment", () => {
+    expect(resolveDeclaredEnvValues(decls("ALLOWED_DIR"), ["ALLOWED_DIR=/override"])).toEqual({
+      ALLOWED_DIR: "/override",
+    });
+  });
+
+  it("includes an --env override even when the key is undeclared (matches buildRuntimeEnv)", () => {
+    expect(resolveDeclaredEnvValues(decls(), ["EXTRA=1"])).toEqual({ EXTRA: "1" });
+  });
+});

package/src/resources/mcp/runtime-env.ts

@@ -36,6 +36,39 @@ export function parseEnvOverrides(overrides: readonly string[]): Record<string,
   return result;
 }
 
+/**
+ * Resolve the values behind a server's declared env vars: declared keys pulled
+ * from the OS environment (non-empty only), with `--env` overrides layered on
+ * top (override wins; an undeclared override is still included).
+ *
+ * This is the single source of truth for "which env value is in play". It backs
+ * both the runtime_env sent to the backend (buildRuntimeEnv) and the ${VAR}
+ * placeholder resolution done locally for `--dry-run` (discover.ts), so the two
+ * can never drift: dry-run resolves against the exact same map the backend hands
+ * the runner (minus platform-injected infra vars, which a local machine cannot
+ * know).
+ *
+ * `declarations` is the server's `spec.env` map; only its keys (the declared
+ * variable names) are read, so any map keyed by those names is accepted.
+ */
+export function resolveDeclaredEnvValues(
+  declarations: Record<string, unknown>,
+  envOverrides: readonly string[] = [],
+): Record<string, string> {
+  const values: Record<string, string> = {};
+
+  for (const key of Object.keys(declarations)) {
+    const value = process.env[key];
+    if (value !== undefined && value !== "") values[key] = value;
+  }
+
+  for (const [key, value] of Object.entries(parseEnvOverrides(envOverrides))) {
+    values[key] = value;
+  }
+
+  return values;
+}
+
 /**
  * Build the runtime_env map for the Connect RPC from the OS environment and the
  * supplied --env overrides. Only keys with a non-empty value are emitted.
@@ -45,17 +78,10 @@ export function buildRuntimeEnv(
   envOverrides: readonly string[] = [],
 ): Record<string, ExecutionValue> {
   const declarations = server.spec?.env ?? {};
-  const overrides = parseEnvOverrides(envOverrides);
+  const values = resolveDeclaredEnvValues(declarations, envOverrides);
   const runtime: Record<string, ExecutionValue> = {};
 
-  for (const [key, decl] of Object.entries(declarations)) {
-    const value = process.env[key];
-    if (value !== undefined && value !== "") {
-      runtime[key] = create(ExecutionValueSchema, { value, isSecret: decl.isSecret });
-    }
-  }
-
-  for (const [key, value] of Object.entries(overrides)) {
+  for (const [key, value] of Object.entries(values)) {
     runtime[key] = create(ExecutionValueSchema, { value, isSecret: declarations[key]?.isSecret ?? false });
   }