@yawlabs/lemonsqueezy-mcp 0.13.2 → 0.13.4

package/bin/lemonsqueezy-mcp.mjs

@@ -1,435 +1,500 @@
-#!/usr/bin/env node
-/**
- * Runtime launcher for @yawlabs/lemonsqueezy-mcp.
- *
- * Prefers the oam runtime (https://oamjs.org) and falls back to the Node
- * process already running this file.
- *
- *
- * WHY THE FALLBACK COSTS NOTHING
- * npm has already started Node to run this launcher, so falling back is a
- * plain `import()` of the server into THIS process: no extra spawn, no extra
- * startup, byte-identical to invoking dist/index.js directly. Discovery is
- * stat-only -- never a subprocess -- so the miss case stays sub-millisecond.
- *
- * WHAT THE OAM PATH COSTS
- * Reaching oam through an npm `bin` means Node boots first and oam boots
- * second, so the launcher is slower than either runtime alone. Measured on
- * npmjs-mcp (windows-arm64, n=12 medians, spawn to first MCP initialize):
- * oam 116ms, node 172ms, launcher 243ms. oam is the fastest runtime and the
- * launcher is the slowest path -- it exists for `npx` convenience.
- *
- * For an MCP host config, point straight at oam and skip this file:
- *   { "command": "oam", "args": ["run", "<abs>/dist/index.js"] }
- *
- * THE `--permission` SANDBOX (oam 0.9.0+, opt-in)
- * `LEMONSQUEEZY_MCP_SANDBOX=1` runs the server under oam's permission model:
- * network limited to api.lemonsqueezy.com, filesystem denied outright.
- *
- * LEMONSQUEEZY_SINK_URL is operator-configured, so its host is parsed out and
- * added to the grant when set rather than assumed. Child-process stays denied
- * UNLESS LEMONSQUEEZY_API_KEY_COMMAND is configured -- that feature shells out
- * to fetch the key, so the grant is tied to the feature instead of handed over
- * unconditionally.
- *
- * Opt-in, not default, because a wrong grant does not fail loudly. oam denies a
- * non-granted environment variable by making it ABSENT from process.env rather
- * than throwing, so an under-granted LEMONSQUEEZY_API_KEY reads as
- * "unauthenticated" rather than "denied". The env list is derived from what the
- * shipped bundle actually reads -- keep it in step with the bundle.
- *
- * MINIMUM OAM VERSION
- * 0.9.0. Below it `child_process.execFile` ran its arguments through a SHELL,
- * `exec` accepted `timeout` and ignored it, `spawnSync` truncated at
- * `maxBuffer` while reporting success, and `stdio: 'inherit'`/`'ignore'` both
- * behaved as `'pipe'`. This server shells out only when
- * LEMONSQUEEZY_API_KEY_COMMAND is configured, so the execFile bug was reachable
- * on exactly that path -- the command's arguments were re-split by a shell.
- * An older oam is not an error: the launcher falls back to Node and says so on
- * stderr. Pinning the floor here is what makes that fallback automatic.
- *
- * SELECTION
- *   LEMONSQUEEZY_MCP_RUNTIME=oam    require oam; fail loudly if it is missing
- *   LEMONSQUEEZY_MCP_RUNTIME=node   never use oam
- *   LEMONSQUEEZY_MCP_RUNTIME=auto   prefer oam, silently fall back (default)
- *   LEMONSQUEEZY_MCP_SANDBOX=1      run oam under --permission (oam 0.9.0+)
- *   OAM_BIN=/path/to/oam     explicit binary, checked before any discovery
- */
-
-import { execFileSync, spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { constants, homedir } from "node:os";
-import { delimiter, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-/** Oldest oam whose `child_process` matches Node. See MINIMUM OAM VERSION above. */
-const OAM_MIN = [0, 9, 0];
-
-// Two forms, deliberately. `import()` on Windows REJECTS a bare `C:\...` path
-// with ERR_UNSUPPORTED_ESM_URL_SCHEME (it reads `c:` as a protocol), so the
-// in-process fallback must use the file:// URL. spawn() needs a real path.
-const SERVER_URL = new URL("../dist/index.js", import.meta.url);
-const SERVER_ENTRY = fileURLToPath(SERVER_URL);
-const isWin = process.platform === "win32";
-const exe = isWin ? "oam.exe" : "oam";
-
-/** Locate an oam binary, or null. Every branch is a stat, never a subprocess. */
-function findOam() {
-  // 1. Explicit override wins and is never second-guessed.
-  const override = process.env.OAM_BIN;
-  if (override) return existsSync(override) ? override : null;
-
-  // 2. Installed locations, BEFORE PATH. Someone who develops oam itself
-  //    usually has oam/target/release on PATH, and a build directory is the
-  //    wrong thing for a user-facing launcher to bind to: cargo replaces the
-  //    binary underneath running processes, and the dev build is not the
-  //    release the user installed. Preferring the installed copy makes the
-  //    default path "what a normal user has", and OAM_BIN remains the way to
-  //    point deliberately at a dev build.
-  //
-  //    Both forms are checked on Windows: the installer defaults to
-  //    %LOCALAPPDATA%\oam\bin there, but oam's docs name ~/.oam/bin first and
-  //    OAM_INSTALL_DIR can pick either, so checking one silently misses a real
-  //    install.
-  const installed = [join(homedir(), ".oam", "bin", exe)];
-  if (isWin) {
-    installed.unshift(join(process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "oam", "bin", exe));
-  }
-  for (const candidate of installed) {
-    if (existsSync(candidate)) return candidate;
-  }
-
-  // 3. PATH, resolved manually rather than by spawning `which`/`where`, which
-  //    would cost a subprocess on every launch just to decide whether to spawn.
-  // Windows: `.exe` ONLY -- deliberately narrower than PATHEXT. Node refuses to
-  // run a .cmd/.bat through execFile/spawn without `shell: true` (EINVAL, and
-  // for spawn it throws SYNCHRONOUSLY rather than emitting 'error'), so walking
-  // the full PATHEXT list would hand back a path this launcher cannot execute.
-  // Discovery has to agree with execution. A skipped shim is still reported --
-  // see findOamShim.
-  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
-    if (!dir) continue;
-    const candidate = join(dir, exe);
-    if (existsSync(candidate)) return candidate;
-  }
-
-  return null;
-}
-
-/**
- * `oam --version` -> [major, minor, patch], or null when it cannot be read.
- * A pre-release suffix (0.9.0-rc.1) truncates to its base version.
- */
-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;
-  } catch {
-    // Not executable, wrong arch, or deleted since the stat. Caller degrades.
-    return null;
-  }
-}
-
-/** True when `v` is at least `min`, comparing major/minor/patch in order. */
-function atLeast(v, min) {
-  if (!v) return false;
-  for (let i = 0; i < min.length; i++) {
-    if (v[i] > min[i]) return true;
-    if (v[i] < min[i]) return false;
-  }
-  return true;
-}
-
-/**
- * The `--permission` grant list, or [] when the sandbox is not requested.
- *
- * These are oam's PROCESS-level flags: they belong before the `run` subcommand,
- * not after it. `oam run --permission file.js` is rejected outright, which is a
- * good failure but only because it is loud -- ordering here is load-bearing.
- *
- * Net grants prefix-match `host` for fetch and `host:port` for sockets.
- * A denied environment variable is ABSENT from process.env rather than throwing,
- * so the env list below is derived from what the bundle actually reads; trimming
- * it produces silent misbehaviour, not a clear denial.
- */
-function sandboxFlags() {
-  if (process.env.LEMONSQUEEZY_MCP_SANDBOX !== "1") return [];
-
-  const hosts = ["api.lemonsqueezy.com"];
-  // LEMONSQUEEZY_SINK_URL is operator-configured, so its host has to be learned, not assumed.
-  if (process.env.LEMONSQUEEZY_SINK_URL) {
-    try {
-      const { hostname } = new URL(process.env.LEMONSQUEEZY_SINK_URL);
-      if (hostname && !hosts.includes(hostname)) hosts.push(hostname);
-    } catch {
-      // Malformed URL: the feature is already broken on its own terms; adding
-      // nothing here keeps the grant honest rather than guessing a host.
-    }
-  }
-  const netFlag = `--allow-net=${hosts.join(",")}`;
-
-  const env = [
-    "LEMONSQUEEZY_ALLOWED_STORE_IDS",
-    "LEMONSQUEEZY_API_KEY",
-    "LEMONSQUEEZY_API_KEY_COMMAND",
-    "LEMONSQUEEZY_DESTRUCTIVE_RATE_LIMIT",
-    "LEMONSQUEEZY_DISABLE_CLASSES",
-    "LEMONSQUEEZY_LOG",
-    "LEMONSQUEEZY_MAX_REFUND_AMOUNT_CENTS",
-    "LEMONSQUEEZY_RATE_LIMIT_PER_CLASS",
-    "LEMONSQUEEZY_SINK_ADMIN_TOKEN",
-    "LEMONSQUEEZY_SINK_URL",
-    "LEMONSQUEEZY_TEST_API_KEY",
-    "PATH",
-  ];
-
-  const flags = ["--permission", netFlag, `--allow-env=${env.join(",")}`];
-  // Tied to the feature that needs it, not granted unconditionally.
-  if (process.env.LEMONSQUEEZY_API_KEY_COMMAND) flags.push("--allow-child-process");
-  return flags;
-}
-
-/**
- * Write a diagnostic to stderr synchronously, so a following process.exit
- * cannot truncate it.
- *
- * Not a bare writeSync: that call can short-write (it returns a byte count) and
- * on macOS it can throw EAGAIN, because Node makes a piped stderr non-blocking
- * there rather than blocking the write. Loop over the remaining bytes, and if
- * stderr turns out to be unusable give up quietly -- failing to print a
- * diagnostic is not worth crashing a stdio server over.
- */
-async function errSync(message) {
-  const { writeSync } = await import("node:fs");
-  const buf = Buffer.from(message);
-  let off = 0;
-  for (let attempts = 0; off < buf.length && attempts < 1000; attempts++) {
-    try {
-      off += writeSync(2, buf, off, buf.length - off);
-    } catch (err) {
-      if (err?.code !== "EAGAIN") return;
-      // Pipe is full and the reader has not drained yet -- retry.
-    }
-  }
-}
-
-/**
- * An oam-named .cmd/.bat on PATH: a real install in a shape this launcher
- * cannot spawn. Reported rather than ignored, because "no oam binary was found"
- * reads as "install oam" -- the one thing that will not help. Windows only;
- * there is no such shim concept on POSIX.
- */
-function findOamShim() {
-  if (!isWin) return null;
-  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
-    if (!dir) continue;
-    for (const ext of [".cmd", ".bat"]) {
-      const candidate = join(dir, `oam${ext}`);
-      if (existsSync(candidate)) return candidate;
-    }
-  }
-  return null;
-}
-
-/** Run the server in THIS process. The zero-overhead fallback. */
-async function runInProcess() {
-  // A server may gate its bootstrap on being the process ENTRY POINT --
-  // `import.meta.url === pathToFileURL(process.argv[1]).href` -- so that its own
-  // test file can import the module for unit tests without connecting a stdio
-  // transport. aws-mcp does exactly this. Importing the server here would leave
-  // argv[1] pointing at THIS launcher, the guard would read false, and the
-  // server would load but never serve: the MCP handshake just hangs.
-  //
-  // Point argv[1] at the server first, so the in-process path is
-  // indistinguishable from having executed the file directly. The spawn path
-  // needs no equivalent -- there argv[1] is already the server.
-  process.argv[1] = SERVER_ENTRY;
-  await import(SERVER_URL.href);
-}
-
-const mode = (process.env.LEMONSQUEEZY_MCP_RUNTIME ?? "auto").toLowerCase();
-
-if (mode === "node") {
-  await runInProcess();
-} else {
-  const oam = findOam();
-  // Read the version ONCE, and only when discovery found something: the gate
-  // below has to tell "too old" apart from "could not be read at all", and
-  // re-probing inside the branch would cost a second subprocess.
-  //
-  // This is the first subprocess the launcher runs -- discovery itself is
-  // stat-only. Paid on every launch that finds an oam, including the ones
-  // that go on to fall back to Node.
-  const found = oam ? oamVersion(oam) : null;
-
-  if (!oam) {
-    // An oam-named .cmd/.bat on PATH is a real install in a shape this
-    // launcher cannot spawn. Naming it turns "no oam binary was found" --
-    // which reads as "install oam", the one thing that will not help --
-    // into something the user can act on.
-    const oamShim = findOamShim();
-    const shimNote = oamShim
-      ? `Found ${oamShim}, but Node cannot execute a .cmd/.bat directly.\n` +
-        "Install the native oam binary, or point OAM_BIN at one.\n"
-      : "";
-    if (mode === "oam") {
-      // Explicitly demanded, so this is a real misconfiguration. writeSync
-      // because stderr is async for TTYs/pipes on Windows and process.exit
-      // truncates pending writes.
-      const { writeSync } = await import("node:fs");
-      writeSync(
-        2,
-        "lemonsqueezy-mcp: LEMONSQUEEZY_MCP_RUNTIME=oam but no runnable oam binary was found.\n" +
-          shimNote +
-          "Install from https://oamjs.org, set OAM_BIN=/path/to/oam, or use LEMONSQUEEZY_MCP_RUNTIME=node.\n",
-      );
-      process.exit(1);
-    }
-    // auto: falling back is correct, but silence is how someone never learns
-    // their oam install is a shape this launcher skips.
-    if (oamShim) await errSync(`lemonsqueezy-mcp: ${shimNote}Using Node instead.\n`);
-    await runInProcess();
-  } else if (!atLeast(found, OAM_MIN)) {
-    const min = OAM_MIN.join(".");
-    // Two different causes reach this branch and they need different
-    // remedies. `found === null` is NOT "old": oamVersion returns null when
-    // the binary could not be run at all (not executable, wrong arch, a
-    // .cmd/.bat Node refuses, deleted between the stat and the probe) or
-    // when its --version output did not parse. Telling that user to
-    // `oam self-update` sends them after the one cause it definitely is not.
-    const detail = found
-      ? `${oam} is oam ${found.join(".")}, older than ${min}`
-      : `${oam} could not be run, or did not report a version this launcher understands`;
-    const remedy = found
-      ? "Run `oam self-update`, or use LEMONSQUEEZY_MCP_RUNTIME=node.\n"
-      : "Check that it is an executable oam binary for this platform, or use LEMONSQUEEZY_MCP_RUNTIME=node.\n";
-    if (mode === "oam") {
-      await errSync(`lemonsqueezy-mcp: LEMONSQUEEZY_MCP_RUNTIME=oam but ${detail}.\n${remedy}`);
-      process.exit(1);
-    }
-    // auto: neither cause is worth failing over -- prefer Node. Say so,
-    // because a silent downgrade is how someone keeps running an oam they
-    // meant to update, or never learns their oam is unexecutable.
-    await errSync(`lemonsqueezy-mcp: ${detail}; using Node instead.\n`);
-    await runInProcess();
-  } else {
-    // `--` separates oam's own flags from the script's argv, so `lemonsqueezy-mcp
-    // --version` and any host-supplied flags survive the hop unchanged.
-    // Every "oam could not be executed" outcome lands here: the synchronous
-    // throw from spawn() and the async 'error' event mean the same thing and
-    // must degrade the same way, so the handling lives in one place.
-    // errSync rather than process.stderr.write because stderr is async for
-    // TTYs and pipes on Windows and the process.exit below truncates pending
-    // writes.
-    const launchFailed = async (err) => {
-      if (mode === "oam") {
-        await errSync(`lemonsqueezy-mcp: failed to launch oam (${err?.message ?? err})\n`);
-        process.exit(1);
-      }
-      await runInProcess();
-    };
-
-    // ONE reporter shared by both launchFailed call sites, so the sync-throw
-    // path and the 'error'-event path cannot drift apart. Either can reject:
-    // runInProcess() is a bare import() that rejects when dist/index.js is
-    // missing, and at ESM top level an unhandled rejection is an uncaught
-    // exception -- the exact failure this handling exists to prevent.
-    const fallbackFailed = (e) => {
-      process.stderr.write(`lemonsqueezy-mcp: fallback to Node failed (${e?.message ?? e})\n`);
-      process.exitCode = 1;
-    };
-
-    let child = null;
-    try {
-      child = spawn(oam, [...sandboxFlags(), "run", SERVER_ENTRY, "--", ...process.argv.slice(2)], {
-        // inherit keeps the SAME fds, so MCP's newline-delimited JSON framing on
-        // stdin/stdout is untouched and the host's stdin-close still reaches the
-        // server's shutdown path.
-        stdio: "inherit",
-        env: process.env,
-        windowsHide: true,
-      });
-    } catch (err) {
-      // spawn() THROWS for some failures instead of emitting 'error', and the
-      // 'error' listener is registered AFTER this call, so it can never observe
-      // one -- an uncaught throw here kills the launcher with a raw stack trace
-      // instead of falling back to Node.
-      await launchFailed(err).catch(fallbackFailed);
-    }
-
-    if (child) {
-      // If oam cannot be executed at all (deleted between the stat and the spawn,
-      // wrong arch, permission), fall back rather than failing the whole server.
-      // `spawned` prevents falling back AFTER the child started, which would
-      // double-start the server on the same stdio.
-      let spawned = false;
-      child.on("spawn", () => {
-        spawned = true;
-      });
-      child.on("error", (err) => {
-        if (spawned) return;
-        // Handle the rejection instead of discarding it: a failing in-process
-        // fallback would otherwise escape as an unhandled rejection, replacing
-        // this launcher's diagnostic with a raw stack trace.
-        launchFailed(err).catch(fallbackFailed);
-      });
-
-      // Forward termination so the server's own shutdown path runs in the child
-      // rather than the child being orphaned.
-      //
-      // Registering ANY handler for these suppresses Node's default
-      // terminate-on-signal, so the parent's exit has to be arranged explicitly.
-      // `child.killed` only records that kill() was CALLED, never that the child
-      // is gone, so gating on it swallows every signal after the first and wedges
-      // the launcher with no escape hatch.
-      //
-      // Escalation is driven by a TIMER, not by counting signals. Counting is
-      // ambiguous: a supervisor routinely sends SIGINT then SIGTERM milliseconds
-      // apart, and a terminal Ctrl-C reaches the whole process group, so reading
-      // "a second signal" as impatience hard-kills a child that is already
-      // shutting down cleanly. A timer makes the count irrelevant -- ONE press is
-      // enough, and a wedged child dies on schedule. setTimeout is monotonic, so
-      // a wall-clock step cannot mis-gate the window either.
-      //
-      // POSIX vs Windows, and why we do NOT forward on Windows.
-      // On POSIX child.kill(sig) delivers a real, catchable signal, so forwarding
-      // is what lets the child run its shutdown. On Windows there are no POSIX
-      // signals: child.kill IGNORES the name and calls TerminateProcess -- an
-      // immediate hard kill (verified: a child with a SIGTERM handler never runs
-      // it and dies with code=null, signal=SIGTERM). Forwarding there ABORTS the
-      // graceful shutdown the console's own Ctrl-C just started, skipping the
-      // child's process.on("exit") cleanup. The console has already notified the
-      // child, so on Windows the timer below is the only kill we issue.
-      const ESCALATE_AFTER_MS = 2000;
-      let escalation = null;
-      for (const sig of ["SIGINT", "SIGTERM"]) {
-        process.on(sig, () => {
-          // No try/catch: kill() on an already-exited child returns false, it does
-          // not throw. It throws only for a signal the platform does not know,
-          // which SIGINT/SIGTERM/SIGKILL never are.
-          if (!isWin) child.kill(sig);
-          if (escalation) return; // already counting down; further signals are noise
-          escalation = setTimeout(() => {
-            // Still here after its grace window. Stop waiting on it.
-            child.kill("SIGKILL");
-            process.exit(128 + (constants.signals[sig] ?? 15));
-          }, ESCALATE_AFTER_MS);
-        });
-      }
-
-      child.on("exit", (code, signal) => {
-        if (escalation) clearTimeout(escalation);
-        // Mirror the child's fate: a signal death becomes 128+n so callers see a
-        // conventional shell exit status rather than a bare 0.
-        if (signal) {
-          process.exit(128 + (constants.signals[signal] ?? 15));
-        }
-        process.exit(code ?? 0);
-      });
-    }
-  }
-}
+#!/usr/bin/env node
+/**
+ * Runtime launcher for @yawlabs/lemonsqueezy-mcp.
+ *
+ * Prefers the oam runtime (https://oamjs.org) and falls back to the Node
+ * process already running this file.
+ *
+ *
+ * WHY THE FALLBACK COSTS NOTHING
+ * npm has already started Node to run this launcher, so falling back is a
+ * plain `import()` of the server into THIS process: no extra spawn, no extra
+ * startup, byte-identical to invoking dist/index.js directly. Discovery is
+ * stat-only -- never a subprocess -- so the miss case stays sub-millisecond.
+ *
+ * WHAT THE OAM PATH COSTS
+ * Reaching oam through an npm `bin` means Node boots first and oam boots
+ * second, so the launcher is slower than either runtime alone. Measured on
+ * npmjs-mcp (windows-arm64, n=12 medians, spawn to first MCP initialize):
+ * oam 116ms, node 172ms, launcher 243ms. oam is the fastest runtime and the
+ * launcher is the slowest path -- it exists for `npx` convenience.
+ *
+ * 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 instead, deliberately.
+ * LEMONSQUEEZY_MCP_SANDBOX=1, because `--permission` is a process-level flag
+ * that only a FRESH oam can apply -- skipping straight to in-process there
+ * 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 discovery path PREFERS a fresh oam; it does not guarantee one. If it
+ * fails -- no binary found, one below the floor or unreadable, or a spawn that
+ * errors -- the fallback below still serves in-process WITHOUT `--permission`
+ * under LEMONSQUEEZY_MCP_RUNTIME=auto, with a stderr note only when a binary
+ * was found too old or unreadable, or a .cmd/.bat shim was skipped. That is how
+ * a requested sandbox behaved before this path existed, and only
+ * LEMONSQUEEZY_MCP_RUNTIME=oam turns it into a failure.
+ *
+ * THE `--permission` SANDBOX (oam 0.9.0+, opt-in)
+ * `LEMONSQUEEZY_MCP_SANDBOX=1` runs the server under oam's permission model:
+ * network limited to api.lemonsqueezy.com, filesystem denied outright.
+ *
+ * LEMONSQUEEZY_SINK_URL is operator-configured, so its host is parsed out and
+ * added to the grant when set rather than assumed. Child-process stays denied
+ * UNLESS LEMONSQUEEZY_API_KEY_COMMAND is configured -- that feature shells out
+ * to fetch the key, so the grant is tied to the feature instead of handed over
+ * unconditionally.
+ *
+ * Opt-in, not default, because a wrong grant does not fail loudly. oam denies a
+ * non-granted environment variable by making it ABSENT from process.env rather
+ * than throwing, so an under-granted LEMONSQUEEZY_API_KEY reads as
+ * "unauthenticated" rather than "denied". The env list is derived from what the
+ * shipped bundle actually reads -- keep it in step with the bundle.
+ *
+ * MINIMUM OAM VERSION
+ * 0.9.0. Below it `child_process.execFile` ran its arguments through a SHELL,
+ * `exec` accepted `timeout` and ignored it, `spawnSync` truncated at
+ * `maxBuffer` while reporting success, and `stdio: 'inherit'`/`'ignore'` both
+ * behaved as `'pipe'`. This server shells out only when
+ * LEMONSQUEEZY_API_KEY_COMMAND is configured, so the execFile bug was reachable
+ * on exactly that path -- the command's arguments were re-split by a shell.
+ * An older oam is not an error: the launcher falls back to Node and says so on
+ * stderr. Pinning the floor here is what makes that fallback automatic.
+ *
+ * SELECTION
+ *   LEMONSQUEEZY_MCP_RUNTIME=oam    require oam; fail loudly if it is missing
+ *                                   (already running on oam satisfies it)
+ *   LEMONSQUEEZY_MCP_RUNTIME=node   never use oam
+ *   LEMONSQUEEZY_MCP_RUNTIME=auto   prefer oam, silently fall back (default)
+ *   LEMONSQUEEZY_MCP_SANDBOX=1      run oam under --permission (oam 0.9.0+)
+ *   OAM_BIN=/path/to/oam     explicit binary, checked before any discovery
+ */
+
+import { execFileSync, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { constants, homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Oldest oam whose `child_process` matches Node. See MINIMUM OAM VERSION above. */
+const OAM_MIN = [0, 9, 0];
+
+// Two forms, deliberately. `import()` on Windows REJECTS a bare `C:\...` path
+// with ERR_UNSUPPORTED_ESM_URL_SCHEME (it reads `c:` as a protocol), so the
+// in-process fallback must use the file:// URL. spawn() needs a real path.
+const SERVER_URL = new URL("../dist/index.js", import.meta.url);
+const SERVER_ENTRY = fileURLToPath(SERVER_URL);
+const isWin = process.platform === "win32";
+const exe = isWin ? "oam.exe" : "oam";
+
+/** Locate an oam binary, or null. Every branch is a stat, never a subprocess. */
+function findOam() {
+  // 1. Explicit override wins and is never second-guessed.
+  const override = process.env.OAM_BIN;
+  if (override) return existsSync(override) ? override : null;
+
+  // 2. Installed locations, BEFORE PATH. Someone who develops oam itself
+  //    usually has oam/target/release on PATH, and a build directory is the
+  //    wrong thing for a user-facing launcher to bind to: cargo replaces the
+  //    binary underneath running processes, and the dev build is not the
+  //    release the user installed. Preferring the installed copy makes the
+  //    default path "what a normal user has", and OAM_BIN remains the way to
+  //    point deliberately at a dev build.
+  //
+  //    Both forms are checked on Windows: the installer defaults to
+  //    %LOCALAPPDATA%\oam\bin there, but oam's docs name ~/.oam/bin first and
+  //    OAM_INSTALL_DIR can pick either, so checking one silently misses a real
+  //    install.
+  const installed = [join(homedir(), ".oam", "bin", exe)];
+  if (isWin) {
+    installed.unshift(join(process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "oam", "bin", exe));
+  }
+  for (const candidate of installed) {
+    if (existsSync(candidate)) return candidate;
+  }
+
+  // 3. PATH, resolved manually rather than by spawning `which`/`where`, which
+  //    would cost a subprocess on every launch just to decide whether to spawn.
+  // Windows: `.exe` ONLY -- deliberately narrower than PATHEXT. Node refuses to
+  // run a .cmd/.bat through execFile/spawn without `shell: true` (EINVAL, and
+  // for spawn it throws SYNCHRONOUSLY rather than emitting 'error'), so walking
+  // the full PATHEXT list would hand back a path this launcher cannot execute.
+  // Discovery has to agree with execution. A skipped shim is still reported --
+  // see findOamShim.
+  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+    if (!dir) continue;
+    const candidate = join(dir, exe);
+    if (existsSync(candidate)) return candidate;
+  }
+
+  return null;
+}
+
+/**
+ * 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"],
+    });
+    return parseVersion(out);
+  } catch {
+    // Not executable, wrong arch, or deleted since the stat. Caller degrades.
+    return null;
+  }
+}
+
+/** True when `v` is at least `min`, comparing major/minor/patch in order. */
+function atLeast(v, min) {
+  if (!v) return false;
+  for (let i = 0; i < min.length; i++) {
+    if (v[i] > min[i]) return true;
+    if (v[i] < min[i]) return false;
+  }
+  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 the discovery path, and why
+ * that path can still end in-process without them. 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.
+ *
+ * These are oam's PROCESS-level flags: they belong before the `run` subcommand,
+ * not after it. `oam run --permission file.js` is rejected outright, which is a
+ * good failure but only because it is loud -- ordering here is load-bearing.
+ *
+ * Net grants prefix-match `host` for fetch and `host:port` for sockets.
+ * A denied environment variable is ABSENT from process.env rather than throwing,
+ * so the env list below is derived from what the bundle actually reads; trimming
+ * it produces silent misbehaviour, not a clear denial.
+ */
+function sandboxFlags() {
+  if (process.env.LEMONSQUEEZY_MCP_SANDBOX !== "1") return [];
+
+  const hosts = ["api.lemonsqueezy.com"];
+  // LEMONSQUEEZY_SINK_URL is operator-configured, so its host has to be learned, not assumed.
+  if (process.env.LEMONSQUEEZY_SINK_URL) {
+    try {
+      const { hostname } = new URL(process.env.LEMONSQUEEZY_SINK_URL);
+      if (hostname && !hosts.includes(hostname)) hosts.push(hostname);
+    } catch {
+      // Malformed URL: the feature is already broken on its own terms; adding
+      // nothing here keeps the grant honest rather than guessing a host.
+    }
+  }
+  const netFlag = `--allow-net=${hosts.join(",")}`;
+
+  const env = [
+    "LEMONSQUEEZY_ALLOWED_STORE_IDS",
+    "LEMONSQUEEZY_API_KEY",
+    "LEMONSQUEEZY_API_KEY_COMMAND",
+    "LEMONSQUEEZY_DESTRUCTIVE_RATE_LIMIT",
+    "LEMONSQUEEZY_DISABLE_CLASSES",
+    "LEMONSQUEEZY_LOG",
+    "LEMONSQUEEZY_MAX_REFUND_AMOUNT_CENTS",
+    "LEMONSQUEEZY_RATE_LIMIT_PER_CLASS",
+    "LEMONSQUEEZY_SINK_ADMIN_TOKEN",
+    "LEMONSQUEEZY_SINK_URL",
+    "LEMONSQUEEZY_TEST_API_KEY",
+    "PATH",
+  ];
+
+  const flags = ["--permission", netFlag, `--allow-env=${env.join(",")}`];
+  // Tied to the feature that needs it, not granted unconditionally.
+  if (process.env.LEMONSQUEEZY_API_KEY_COMMAND) flags.push("--allow-child-process");
+  return flags;
+}
+
+/**
+ * Write a diagnostic to stderr synchronously, so a following process.exit
+ * cannot truncate it.
+ *
+ * Not a bare writeSync: that call can short-write (it returns a byte count) and
+ * on macOS it can throw EAGAIN, because Node makes a piped stderr non-blocking
+ * there rather than blocking the write. Loop over the remaining bytes, and if
+ * stderr turns out to be unusable give up quietly -- failing to print a
+ * diagnostic is not worth crashing a stdio server over.
+ */
+async function errSync(message) {
+  const { writeSync } = await import("node:fs");
+  const buf = Buffer.from(message);
+  let off = 0;
+  for (let attempts = 0; off < buf.length && attempts < 1000; attempts++) {
+    try {
+      off += writeSync(2, buf, off, buf.length - off);
+    } catch (err) {
+      if (err?.code !== "EAGAIN") return;
+      // Pipe is full and the reader has not drained yet -- retry.
+    }
+  }
+}
+
+/**
+ * An oam-named .cmd/.bat on PATH: a real install in a shape this launcher
+ * cannot spawn. Reported rather than ignored, because "no oam binary was found"
+ * reads as "install oam" -- the one thing that will not help. Windows only;
+ * there is no such shim concept on POSIX.
+ */
+function findOamShim() {
+  if (!isWin) return null;
+  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+    if (!dir) continue;
+    for (const ext of [".cmd", ".bat"]) {
+      const candidate = join(dir, `oam${ext}`);
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+/** Run the server in THIS process. The zero-overhead fallback. */
+async function runInProcess() {
+  // A server may gate its bootstrap on being the process ENTRY POINT --
+  // `import.meta.url === pathToFileURL(process.argv[1]).href` -- so that its own
+  // test file can import the module for unit tests without connecting a stdio
+  // transport. aws-mcp does exactly this. Importing the server here would leave
+  // argv[1] pointing at THIS launcher, the guard would read false, and the
+  // server would load but never serve: the MCP handshake just hangs.
+  //
+  // Point argv[1] at the server first, so the in-process path is
+  // indistinguishable from having executed the file directly. The spawn path
+  // needs no equivalent -- there argv[1] is already the server.
+  process.argv[1] = SERVER_ENTRY;
+  await import(SERVER_URL.href);
+}
+
+const mode = (process.env.LEMONSQUEEZY_MCP_RUNTIME ?? "auto").toLowerCase();
+
+// The sandbox is read off the grant list rather than LEMONSQUEEZY_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();
+  // Read the version ONCE, and only when discovery found something: the gate
+  // below has to tell "too old" apart from "could not be read at all", and
+  // re-probing inside the branch would cost a second subprocess.
+  //
+  // This is the first subprocess the launcher runs -- discovery itself is
+  // stat-only. Paid on every launch that finds an oam, including the ones
+  // that go on to fall back to Node.
+  const found = oam ? oamVersion(oam) : null;
+
+  if (!oam) {
+    // An oam-named .cmd/.bat on PATH is a real install in a shape this
+    // launcher cannot spawn. Naming it turns "no oam binary was found" --
+    // which reads as "install oam", the one thing that will not help --
+    // into something the user can act on.
+    const oamShim = findOamShim();
+    const shimNote = oamShim
+      ? `Found ${oamShim}, but Node cannot execute a .cmd/.bat directly.\n` +
+        "Install the native oam binary, or point OAM_BIN at one.\n"
+      : "";
+    if (mode === "oam") {
+      // Explicitly demanded, so this is a real misconfiguration. writeSync
+      // because stderr is async for TTYs/pipes on Windows and process.exit
+      // truncates pending writes.
+      const { writeSync } = await import("node:fs");
+      writeSync(
+        2,
+        "lemonsqueezy-mcp: LEMONSQUEEZY_MCP_RUNTIME=oam but no runnable oam binary was found.\n" +
+          shimNote +
+          "Install from https://oamjs.org, set OAM_BIN=/path/to/oam, or use LEMONSQUEEZY_MCP_RUNTIME=node.\n",
+      );
+      process.exit(1);
+    }
+    // auto: falling back is correct, but silence is how someone never learns
+    // their oam install is a shape this launcher skips.
+    if (oamShim) await errSync(`lemonsqueezy-mcp: ${shimNote}Using Node instead.\n`);
+    await runInProcess();
+  } else if (!atLeast(found, OAM_MIN)) {
+    const min = OAM_MIN.join(".");
+    // Two different causes reach this branch and they need different
+    // remedies. `found === null` is NOT "old": oamVersion returns null when
+    // the binary could not be run at all (not executable, wrong arch, a
+    // .cmd/.bat Node refuses, deleted between the stat and the probe) or
+    // when its --version output did not parse. Telling that user to
+    // `oam self-update` sends them after the one cause it definitely is not.
+    const detail = found
+      ? `${oam} is oam ${found.join(".")}, older than ${min}`
+      : `${oam} could not be run, or did not report a version this launcher understands`;
+    const remedy = found
+      ? "Run `oam self-update`, or use LEMONSQUEEZY_MCP_RUNTIME=node.\n"
+      : "Check that it is an executable oam binary for this platform, or use LEMONSQUEEZY_MCP_RUNTIME=node.\n";
+    if (mode === "oam") {
+      await errSync(`lemonsqueezy-mcp: LEMONSQUEEZY_MCP_RUNTIME=oam but ${detail}.\n${remedy}`);
+      process.exit(1);
+    }
+    // auto: neither cause is worth failing over -- prefer Node. Say so,
+    // because a silent downgrade is how someone keeps running an oam they
+    // meant to update, or never learns their oam is unexecutable.
+    await errSync(`lemonsqueezy-mcp: ${detail}; using Node instead.\n`);
+    await runInProcess();
+  } else {
+    // `--` separates oam's own flags from the script's argv, so `lemonsqueezy-mcp
+    // --version` and any host-supplied flags survive the hop unchanged.
+    // Every "oam could not be executed" outcome lands here: the synchronous
+    // throw from spawn() and the async 'error' event mean the same thing and
+    // must degrade the same way, so the handling lives in one place.
+    // errSync rather than process.stderr.write because stderr is async for
+    // TTYs and pipes on Windows and the process.exit below truncates pending
+    // writes.
+    const launchFailed = async (err) => {
+      if (mode === "oam") {
+        await errSync(`lemonsqueezy-mcp: failed to launch oam (${err?.message ?? err})\n`);
+        process.exit(1);
+      }
+      await runInProcess();
+    };
+
+    // ONE reporter shared by both launchFailed call sites, so the sync-throw
+    // path and the 'error'-event path cannot drift apart. Either can reject:
+    // runInProcess() is a bare import() that rejects when dist/index.js is
+    // missing, and at ESM top level an unhandled rejection is an uncaught
+    // exception -- the exact failure this handling exists to prevent.
+    const fallbackFailed = (e) => {
+      process.stderr.write(`lemonsqueezy-mcp: fallback to Node failed (${e?.message ?? e})\n`);
+      process.exitCode = 1;
+    };
+
+    let child = null;
+    try {
+      child = spawn(oam, [...sandboxFlags(), "run", SERVER_ENTRY, "--", ...process.argv.slice(2)], {
+        // inherit keeps the SAME fds, so MCP's newline-delimited JSON framing on
+        // stdin/stdout is untouched and the host's stdin-close still reaches the
+        // server's shutdown path.
+        stdio: "inherit",
+        env: process.env,
+        windowsHide: true,
+      });
+    } catch (err) {
+      // spawn() THROWS for some failures instead of emitting 'error', and the
+      // 'error' listener is registered AFTER this call, so it can never observe
+      // one -- an uncaught throw here kills the launcher with a raw stack trace
+      // instead of falling back to Node.
+      await launchFailed(err).catch(fallbackFailed);
+    }
+
+    if (child) {
+      // If oam cannot be executed at all (deleted between the stat and the spawn,
+      // wrong arch, permission), fall back rather than failing the whole server.
+      // `spawned` prevents falling back AFTER the child started, which would
+      // double-start the server on the same stdio.
+      let spawned = false;
+      child.on("spawn", () => {
+        spawned = true;
+      });
+      child.on("error", (err) => {
+        if (spawned) return;
+        // Handle the rejection instead of discarding it: a failing in-process
+        // fallback would otherwise escape as an unhandled rejection, replacing
+        // this launcher's diagnostic with a raw stack trace.
+        launchFailed(err).catch(fallbackFailed);
+      });
+
+      // Forward termination so the server's own shutdown path runs in the child
+      // rather than the child being orphaned.
+      //
+      // Registering ANY handler for these suppresses Node's default
+      // terminate-on-signal, so the parent's exit has to be arranged explicitly.
+      // `child.killed` only records that kill() was CALLED, never that the child
+      // is gone, so gating on it swallows every signal after the first and wedges
+      // the launcher with no escape hatch.
+      //
+      // Escalation is driven by a TIMER, not by counting signals. Counting is
+      // ambiguous: a supervisor routinely sends SIGINT then SIGTERM milliseconds
+      // apart, and a terminal Ctrl-C reaches the whole process group, so reading
+      // "a second signal" as impatience hard-kills a child that is already
+      // shutting down cleanly. A timer makes the count irrelevant -- ONE press is
+      // enough, and a wedged child dies on schedule. setTimeout is monotonic, so
+      // a wall-clock step cannot mis-gate the window either.
+      //
+      // POSIX vs Windows, and why we do NOT forward on Windows.
+      // On POSIX child.kill(sig) delivers a real, catchable signal, so forwarding
+      // is what lets the child run its shutdown. On Windows there are no POSIX
+      // signals: child.kill IGNORES the name and calls TerminateProcess -- an
+      // immediate hard kill (verified: a child with a SIGTERM handler never runs
+      // it and dies with code=null, signal=SIGTERM). Forwarding there ABORTS the
+      // graceful shutdown the console's own Ctrl-C just started, skipping the
+      // child's process.on("exit") cleanup. The console has already notified the
+      // child, so on Windows the timer below is the only kill we issue.
+      const ESCALATE_AFTER_MS = 2000;
+      let escalation = null;
+      for (const sig of ["SIGINT", "SIGTERM"]) {
+        process.on(sig, () => {
+          // No try/catch: kill() on an already-exited child returns false, it does
+          // not throw. It throws only for a signal the platform does not know,
+          // which SIGINT/SIGTERM/SIGKILL never are.
+          if (!isWin) child.kill(sig);
+          if (escalation) return; // already counting down; further signals are noise
+          escalation = setTimeout(() => {
+            // Still here after its grace window. Stop waiting on it.
+            child.kill("SIGKILL");
+            process.exit(128 + (constants.signals[sig] ?? 15));
+          }, ESCALATE_AFTER_MS);
+        });
+      }
+
+      child.on("exit", (code, signal) => {
+        if (escalation) clearTimeout(escalation);
+        // Mirror the child's fate: a signal death becomes 128+n so callers see a
+        // conventional shell exit status rather than a bare 0.
+        if (signal) {
+          process.exit(128 + (constants.signals[signal] ?? 15));
+        }
+        process.exit(code ?? 0);
+      });
+    }
+  }
+}