@yawlabs/lemonsqueezy-mcp 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,7 +1,26 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.12.0] — 2026-08-07
+
+### Added
+- Runtime launcher at `bin/lemonsqueezy-mcp.mjs`: the published `lemonsqueezy-mcp` command now prefers the [oam](https://oamjs.org) runtime and falls back to Node. `LEMONSQUEEZY_MCP_RUNTIME` selects (`auto` / `oam` / `node`) and `OAM_BIN` overrides discovery. Both paths verified against the MCP surface — handshake plus all 64 tools — and behave identically. The fallback does **not** re-exec Node: npm has already started Node to run the launcher, so it is an in-process `import()` with no extra spawn.
+
+### Changed
+- `.gitignore` excludes `bin/*` rather than `bin/`, so the launcher can be re-included with a negation. A negation cannot undo a directory-level exclusion — that trap shipped a broken `bin` in postgres-mcp, where the launcher was untracked and absent from every fresh clone.
+- `scripts/build-binary.mjs` pins the CLI source entry instead of deriving it from `bin`'s value, which would have resolved to `bin/lemonsqueezy-mcp.ts` once `bin` moved to the launcher — the breakage postgres-mcp shipped in its 0.9.0.
+
 All notable changes to `@yawlabs/lemonsqueezy-mcp` are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and versioning follows [SEMVER.md](./SEMVER.md).
 
+## [0.11.1] -- 2026-08-07
+
+### Fixed
+
+- **A 4xx whose error envelope carries no `detail` no longer dumps raw JSON at the caller.** LemonSqueezy's real 404 is `{"jsonapi":{"version":"1.0"},"errors":[{"status":"404","title":"Not Found"}]}` -- `title`, no `detail`. The message chain read `detail` then the License API's bare `error`, so this shape fell all the way through to the raw response body and an agent asking for a missing store got a JSON blob instead of a reason. `title` is now read between the two.
+
+  Long-standing, not new in 0.11.0, and invisible to the unit suite because every fixture in it (and every one added during the 0.11.0 audit) used `detail`. Caught by a read-only call against the live API. Both shapes are now pinned, including the precedence when `detail` and `title` are both present.
+
 ## [0.11.0] -- 2026-08-07
 
 ### Security
@@ -472,6 +491,7 @@ Hardening pass for unattended automation against live billing flows.
 Initial release. 59 tools covering all 17 LemonSqueezy API resources.
 
 [Unreleased]: https://github.com/YawLabs/lemonsqueezy-mcp/compare/v0.10.9...HEAD
+[0.11.1]: https://github.com/YawLabs/lemonsqueezy-mcp/compare/v0.11.0...v0.11.1
 [0.11.0]: https://github.com/YawLabs/lemonsqueezy-mcp/compare/v0.10.13...v0.11.0
 [0.10.13]: https://github.com/YawLabs/lemonsqueezy-mcp/compare/v0.10.12...v0.10.13
 [0.10.12]: https://github.com/YawLabs/lemonsqueezy-mcp/compare/v0.10.11...v0.10.12

package/bin/lemonsqueezy-mcp.mjs

@@ -0,0 +1,169 @@
+#!/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"] }
+ *
+ * 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)
+ *   OAM_BIN=/path/to/oam     explicit binary, checked before any discovery
+ */
+
+import { 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";
+
+// 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%oamin 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.
+  const pathExt = isWin ? (process.env.PATHEXT ?? ".EXE").split(";").filter(Boolean) : [""];
+  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+    if (!dir) continue;
+    for (const ext of isWin ? pathExt : [""]) {
+      const candidate = join(dir, isWin ? `oam${ext.toLowerCase()}` : "oam");
+      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();
+
+  if (!oam) {
+    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 oam binary was found.\n" +
+          "Install from https://oamjs.org, set OAM_BIN=/path/to/oam, or use LEMONSQUEEZY_MCP_RUNTIME=node.\n",
+      );
+      process.exit(1);
+    }
+    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.
+    const child = spawn(oam, ["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,
+    });
+
+    // 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;
+      if (mode === "oam") {
+        process.stderr.write(`lemonsqueezy-mcp: failed to launch oam (${err.message})\n`);
+        process.exit(1);
+      }
+      void runInProcess();
+    });
+
+    // Forward termination so the server's own shutdown path runs in the child
+    // rather than the child being orphaned. No-op on Windows, harmless to add.
+    for (const sig of ["SIGINT", "SIGTERM"]) {
+      process.on(sig, () => {
+        if (!child.killed) child.kill(sig);
+      });
+    }
+
+    child.on("exit", (code, signal) => {
+      // 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);
+    });
+  }
+}

package/dist/index.js

@@ -21626,11 +21626,15 @@ function buildQuery(params) {
 function decorateError(error2, requestId) {
   return requestId ? `${error2} (request_id: ${requestId})` : error2;
 }
+function extractErrorMessage(parsed) {
+  const first = parsed.errors?.[0];
+  return first?.detail ?? first?.title ?? parsed.error ?? null;
+}
 async function handleErrorResponse(res, route, latency_ms, requestId) {
   const errorBody = await res.text();
   try {
     const parsed = JSON.parse(errorBody);
-    const detail = parsed.errors?.[0]?.detail ?? parsed.error ?? errorBody;
+    const detail = extractErrorMessage(parsed) ?? errorBody;
     logEvent({
       event: "http_call",
       method: route.method,
@@ -23789,7 +23793,7 @@ function readAuditLogResource(uri) {
 }
 
 // src/index.ts
-var version2 = true ? "0.11.0" : createRequire(import.meta.url)("../package.json").version;
+var version2 = true ? "0.12.0" : createRequire(import.meta.url)("../package.json").version;
 var subcommand = process.argv[2];
 if (subcommand === "version" || subcommand === "--version") {
   console.log(version2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/lemonsqueezy-mcp",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "mcpName": "io.github.YawLabs/lemonsqueezy-mcp",
   "description": "LemonSqueezy MCP server for managing your store from AI assistants",
   "license": "MIT",
@@ -22,9 +22,10 @@
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "lemonsqueezy-mcp": "dist/index.js"
+    "lemonsqueezy-mcp": "bin/lemonsqueezy-mcp.mjs"
   },
   "files": [
+    "bin/lemonsqueezy-mcp.mjs",
     "dist/index.js",
     "CHANGELOG.md"
   ],