@yawlabs/caddy-mcp 2.4.1 → 2.4.2

package/bin/caddy-mcp.mjs

@@ -28,8 +28,37 @@
  * For an MCP host config, point straight at oam and skip this file:
  *   { "command": "oam", "args": ["run", "<abs>/dist/index.js"] }
  *
+ * ALREADY RUNNING ON OAM
+ * A host can resolve this package's `bin` and launch `oam run <this file>`
+ * instead of `node <this file>` -- Yaw MCP does, and so does oam's sidecar
+ * regression matrix. This launcher used to discover oam and spawn it anyway,
+ * so one server cost two runtime boots: measured on Windows, oam.exe with a
+ * NESTED oam.exe + conhost.exe underneath it. Now, when `process.versions.oam`
+ * clears the same MINIMUM OAM VERSION a discovered binary has to, the server is
+ * imported into THIS process exactly as the Node fallback is -- no discovery,
+ * no `oam --version` probe, no second oam. OAM_BIN is a discovery input, so it
+ * is not consulted on that path: the host has already chosen which oam runs.
+ *
+ * Two cases still take the discovery path, deliberately. CADDY_MCP_SANDBOX=1,
+ * because `--permission` is a process-level flag that only a FRESH oam can
+ * apply -- serving in-process on the host would drop the sandbox without a
+ * word, a security downgrade dressed up as an optimisation. And a host oam
+ * below the floor, which takes the discovery path exactly as it always did.
+ *
+ * The sandbox asks for a spawn; it does not guarantee one. Discovery can still
+ * come up empty -- no oam binary, one below the floor or unreadable, a spawn
+ * that fails -- and under CADDY_MCP_RUNTIME=auto that falls back exactly as it
+ * does on Node: the server runs in THIS process WITHOUT `--permission`. No oam
+ * (and no .cmd shim) and a failed spawn fall back silently; the too-old or
+ * unreadable binary and .cmd-shim cases print a note that does not mention the
+ * sandbox. Only CADDY_MCP_RUNTIME=oam turns that miss into a hard failure, so
+ * pair it with CADDY_MCP_SANDBOX=1 when the sandbox has to hold.
+ * CADDY_MCP_RUNTIME=node ignores the sandbox entirely.
+ *
  * THE `--permission` SANDBOX (oam 0.9.0+, opt-in)
- * `CADDY_MCP_SANDBOX=1` runs the server under oam's permission model.
+ * `CADDY_MCP_SANDBOX=1` runs the server under oam's permission model when an
+ * oam binary is found and launched -- see ALREADY RUNNING ON OAM for the
+ * fallback that runs it unsandboxed, and how to refuse that instead.
  *
  * The admin API endpoint is DERIVED from CADDY_ADMIN_URL (default
  * http://localhost:2019 -- byte-identical to DEFAULT_URL in src/api.ts, see
@@ -68,9 +97,12 @@
  *
  * SELECTION
  *   CADDY_MCP_RUNTIME=oam    require oam; fail loudly if it is missing
+ *                            (already running on oam satisfies it, except
+ *                            under CADDY_MCP_SANDBOX=1)
  *   CADDY_MCP_RUNTIME=node   never use oam
  *   CADDY_MCP_RUNTIME=auto   prefer oam, silently fall back (default)
- *   CADDY_MCP_SANDBOX=1      run oam under --permission (oam 0.9.0+)
+ *   CADDY_MCP_SANDBOX=1      run oam under --permission (oam 0.9.0+); under
+ *                            auto a discovery miss still runs unsandboxed
  *   OAM_BIN=/path/to/oam     explicit binary, checked before any discovery
  */
 
@@ -143,17 +175,27 @@ function findOam() {
 }
 
 /**
- * `oam --version` -> [major, minor, patch], or null when it cannot be read.
+ * Version text -> [major, minor, patch], or null when it holds no version.
  * A pre-release suffix (0.9.0-rc.1) truncates to its base version.
+ *
+ * Shared by the two places a version is read -- a discovered binary's
+ * `oam --version` output ("oam 0.15.1") and the host's own
+ * `process.versions.oam` ("0.15.1") -- so they cannot disagree about what a
+ * version string means, or which floor it has to clear.
  */
+function parseVersion(text) {
+  const m = /(\d+)\.(\d+)\.(\d+)/.exec(text);
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+/** `oam --version` -> [major, minor, patch], or null when it cannot be read. */
 function oamVersion(cmd) {
   try {
     const out = execFileSync(cmd, ["--version"], {
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "ignore"],
     });
-    const m = /(\d+)\.(\d+)\.(\d+)/.exec(out);
-    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+    return parseVersion(out);
   } catch {
     // Not executable, wrong arch, or deleted since the stat. Caller degrades.
     return null;
@@ -170,6 +212,29 @@ function atLeast(v, min) {
   return true;
 }
 
+/**
+ * Where the server runs, decided BEFORE any discovery:
+ *   "in-process"  import it into THIS process
+ *   "discover"    find an oam binary, gate its version, spawn it -- or fall
+ *                 back to Node in-process when that fails
+ *
+ * `hostOam` is `process.versions.oam`: oam's own key, absent on Node, so on
+ * Node every mode but `node` is the discovery path it always was. `sandbox`
+ * is whether a spawn would carry flags only a fresh oam can apply; see ALREADY
+ * RUNNING ON OAM above for why that alone forces discovery -- and why discovery
+ * is not a guaranteed spawn, since its miss still falls back in-process. The
+ * floor is OAM_MIN itself, not a parameter, so a host oam and a discovered one
+ * can never be held to different minimums.
+ *
+ * Pure on purpose: every input is passed in, so the whole decision is testable
+ * without booting a runtime.
+ */
+function runtimePlan({ mode, hostOam, sandbox }) {
+  if (mode === "node") return "in-process";
+  if (sandbox) return "discover";
+  return atLeast(parseVersion(hostOam ?? ""), OAM_MIN) ? "in-process" : "discover";
+}
+
 /**
  * The `--permission` grant list, or [] when the sandbox is not requested.
  *
@@ -361,7 +426,12 @@ async function runInProcess() {
 
 const mode = (process.env.CADDY_MCP_RUNTIME ?? "auto").toLowerCase();
 
-if (mode === "node") {
+// The sandbox is read off the grant list rather than CADDY_MCP_SANDBOX, so
+// "would the spawn carry --permission" cannot drift from what the spawn below
+// actually passes.
+const plan = runtimePlan({ mode, hostOam: process.versions.oam, sandbox: sandboxFlags().length > 0 });
+
+if (plan === "in-process") {
   await runInProcess();
 } else {
   const oam = findOam();

package/dist/tools/operational.d.ts

@@ -10,10 +10,10 @@ export declare const METRICS_DEFAULT_MAX_LINES = 500;
  * metric name (blank lines, free-form `#` comments) are dropped when filtering.
  *
  * Truncation: if the resulting line count exceeds `maxLines`, output is cut at `maxLines` and a
- * trailing `# [truncated, N lines omitted -- use filter to narrow]` comment is appended. If the
- * input contained a `# EOF` end-of-file marker that would have been dropped by the cut, it is
- * re-appended after the truncation comment so strict downstream parsers still see a terminated
- * stream.
+ * trailing `# [truncated, N lines omitted; max_lines=M -- use filter or raise max_lines]` comment
+ * is appended, where N is the number of lines cut and M is `maxLines`. If the input contained a
+ * `# EOF` end-of-file marker that would have been dropped by the cut, it is re-appended after the
+ * truncation comment so strict downstream parsers still see a terminated stream.
  */
 export declare function applyMetricsControls(raw: string, filter: string | undefined, maxLines: number): string;
 export declare function registerOperationalTools(server: McpServer): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/caddy-mcp",
-  "version": "2.4.1",
+  "version": "2.4.2",
   "mcpName": "io.github.YawLabs/caddy-mcp",
   "description": "Caddy MCP server for Claude Code, Cursor, and any MCP client: admin API, config, routes, reverse proxy, TLS, PKI, metrics",
   "license": "MIT",