frontmcp 1.1.0 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontmcp",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "FrontMCP command line interface",
   "author": "AgentFront <info@agentfront.dev>",
   "homepage": "https://docs.agentfront.dev",
@@ -22,6 +22,7 @@
     "url": "https://github.com/agentfront/frontmcp/issues"
   },
   "main": "./src/index.js",
+  "types": "./index.d.js",
   "bin": {
     "frontmcp": "./src/core/cli.js"
   },
@@ -30,9 +31,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.10.0",
-    "@frontmcp/lazy-zod": "1.1.0",
-    "@frontmcp/utils": "1.1.0",
-    "@frontmcp/skills": "1.1.0",
+    "@frontmcp/lazy-zod": "1.1.1",
+    "@frontmcp/utils": "1.1.1",
+    "@frontmcp/skills": "1.1.1",
     "commander": "^13.0.0",
     "tslib": "^2.3.0",
     "vectoriadb": "^2.2.0",
@@ -48,6 +49,5 @@
     "@types/yauzl": "^2.10.3",
     "@types/yazl": "^2.4.5"
   },
-  "types": "./index.d.js",
   "type": "commonjs"
 }

package/src/commands/build/adapters/cloudflare.js

@@ -72,8 +72,36 @@ module.exports = {
   }
 };
 `,
+    // #375 — fail the build when the user's @FrontMcp config references
+    // Node-only storage providers that can't run on Workers. Conditional
+    // (env-gated) usage still passes; only unconditional declarations throw.
+    validate: (decoratorConfig) => {
+        if (!decoratorConfig)
+            return;
+        const sqlite = decoratorConfig['sqlite'];
+        const redis = decoratorConfig['redis'];
+        const errors = [];
+        if (sqlite && typeof sqlite === 'object') {
+            errors.push('sqlite storage is not supported on --target cloudflare (no fs / native modules on Workers). ' +
+                'Use Cloudflare KV / Durable Objects, or gate the sqlite branch behind a build-time `define` ' +
+                'so the bundler can dead-code-eliminate it.');
+        }
+        if (redis && typeof redis === 'object') {
+            errors.push('ioredis-style `redis` storage is not supported on --target cloudflare (no Node net). ' +
+                'Use Vercel KV / Upstash Redis (HTTP), or move the redis config to a runtime branch ' +
+                'gated on `globalThis.process?.env`.');
+        }
+        if (errors.length) {
+            throw new Error(`[--target cloudflare] config incompatible with Cloudflare Workers:\n  - ${errors.join('\n  - ')}`);
+        }
+    },
+    // #374 — always write wrangler.toml from the build output. Skipping when
+    // the file already exists left users with a wrangler.toml that pointed at
+    // dist/index.js while the build emitted dist/cloudflare/index.js, and
+    // wrangler deploy silently failed.
+    alwaysWriteConfig: true,
     getConfig: (_cwd) => `name = "frontmcp-worker"
-main = "dist/index.js"
+main = "dist/cloudflare/index.js"
 compatibility_date = "2024-01-01"
 `,
     configFileName: 'wrangler.toml',

package/src/commands/build/adapters/cloudflare.js.map

@@ -1 +1 @@
-{"version":3,"file":"cloudflare.js","sourceRoot":"","sources":["../../../../../src/commands/build/adapters/cloudflare.ts"],"names":[],"mappings":";;;AAEA;;;;;GAKG;AACU,QAAA,iBAAiB,GAAoB;IAChD,YAAY,EAAE,UAAU;IAExB,gBAAgB,EAAE,CAAC,cAAsB,EAAE,EAAE,CAAC;;;;;WAKrC,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyDxB;IAEC,SAAS,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC;;;CAG9B;IAEC,cAAc,EAAE,eAAe;CAChC,CAAC","sourcesContent":["import type { AdapterTemplate } from '../types';\n\n/**\n * Cloudflare Workers adapter - edge deployment on Cloudflare.\n * Compiles to CommonJS and adapts the Express app to Cloudflare's fetch API.\n *\n * @see https://developers.cloudflare.com/workers/\n */\nexport const cloudflareAdapter: AdapterTemplate = {\n  moduleFormat: 'commonjs',\n\n  getEntryTemplate: (mainModulePath: string) => `// Auto-generated Cloudflare Workers entry point\n// Generated by: frontmcp build --target cloudflare\nprocess.env.FRONTMCP_SERVERLESS = '1';\nprocess.env.FRONTMCP_DEPLOYMENT_MODE = 'serverless';\n\nrequire('${mainModulePath}');\nconst { getServerlessHandlerAsync } = require('@frontmcp/sdk');\n\nlet app = null;\n\nasync function handleRequest(request) {\n  if (!app) {\n    app = await getServerlessHandlerAsync();\n  }\n\n  // Convert Cloudflare Request to Node.js format\n  const url = new URL(request.url);\n  const req = {\n    method: request.method,\n    url: url.pathname + url.search,\n    headers: Object.fromEntries(request.headers),\n    body: request.body,\n  };\n\n  return new Promise((resolve) => {\n    const res = {\n      statusCode: 200,\n      headers: {},\n      body: '',\n      status(code) { this.statusCode = code; return this; },\n      setHeader(key, value) { this.headers[key] = value; },\n      json(data) {\n        this.headers['Content-Type'] = 'application/json';\n        this.body = JSON.stringify(data);\n        resolve(new Response(this.body, {\n          status: this.statusCode,\n          headers: this.headers,\n        }));\n      },\n      send(data) {\n        this.body = data;\n        resolve(new Response(this.body, {\n          status: this.statusCode,\n          headers: this.headers,\n        }));\n      },\n      end() {\n        resolve(new Response(this.body, {\n          status: this.statusCode,\n          headers: this.headers,\n        }));\n      },\n    };\n    app(req, res);\n  });\n}\n\nmodule.exports = {\n  async fetch(request, env, ctx) {\n    return handleRequest(request);\n  }\n};\n`,\n\n  getConfig: (_cwd: string) => `name = \"frontmcp-worker\"\nmain = \"dist/index.js\"\ncompatibility_date = \"2024-01-01\"\n`,\n\n  configFileName: 'wrangler.toml',\n};\n"]}
+{"version":3,"file":"cloudflare.js","sourceRoot":"","sources":["../../../../../src/commands/build/adapters/cloudflare.ts"],"names":[],"mappings":";;;AAEA;;;;;GAKG;AACU,QAAA,iBAAiB,GAAoB;IAChD,YAAY,EAAE,UAAU;IAExB,gBAAgB,EAAE,CAAC,cAAsB,EAAE,EAAE,CAAC;;;;;WAKrC,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyDxB;IAEC,oEAAoE;IACpE,qEAAqE;IACrE,yEAAyE;IACzE,QAAQ,EAAE,CAAC,eAAe,EAAE,EAAE;QAC5B,IAAI,CAAC,eAAe;YAAE,OAAO;QAC7B,MAAM,MAAM,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;QACzC,MAAM,KAAK,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;QACvC,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YACzC,MAAM,CAAC,IAAI,CACT,8FAA8F;gBAC5F,8FAA8F;gBAC9F,4CAA4C,CAC/C,CAAC;QACJ,CAAC;QACD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACvC,MAAM,CAAC,IAAI,CACT,uFAAuF;gBACrF,qFAAqF;gBACrF,qCAAqC,CACxC,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CACb,2EAA2E,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CACnG,CAAC;QACJ,CAAC;IACH,CAAC;IAED,yEAAyE;IACzE,0EAA0E;IAC1E,sEAAsE;IACtE,mCAAmC;IACnC,iBAAiB,EAAE,IAAI;IAEvB,SAAS,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC;;;CAG9B;IAEC,cAAc,EAAE,eAAe;CAChC,CAAC","sourcesContent":["import type { AdapterTemplate } from '../types';\n\n/**\n * Cloudflare Workers adapter - edge deployment on Cloudflare.\n * Compiles to CommonJS and adapts the Express app to Cloudflare's fetch API.\n *\n * @see https://developers.cloudflare.com/workers/\n */\nexport const cloudflareAdapter: AdapterTemplate = {\n  moduleFormat: 'commonjs',\n\n  getEntryTemplate: (mainModulePath: string) => `// Auto-generated Cloudflare Workers entry point\n// Generated by: frontmcp build --target cloudflare\nprocess.env.FRONTMCP_SERVERLESS = '1';\nprocess.env.FRONTMCP_DEPLOYMENT_MODE = 'serverless';\n\nrequire('${mainModulePath}');\nconst { getServerlessHandlerAsync } = require('@frontmcp/sdk');\n\nlet app = null;\n\nasync function handleRequest(request) {\n  if (!app) {\n    app = await getServerlessHandlerAsync();\n  }\n\n  // Convert Cloudflare Request to Node.js format\n  const url = new URL(request.url);\n  const req = {\n    method: request.method,\n    url: url.pathname + url.search,\n    headers: Object.fromEntries(request.headers),\n    body: request.body,\n  };\n\n  return new Promise((resolve) => {\n    const res = {\n      statusCode: 200,\n      headers: {},\n      body: '',\n      status(code) { this.statusCode = code; return this; },\n      setHeader(key, value) { this.headers[key] = value; },\n      json(data) {\n        this.headers['Content-Type'] = 'application/json';\n        this.body = JSON.stringify(data);\n        resolve(new Response(this.body, {\n          status: this.statusCode,\n          headers: this.headers,\n        }));\n      },\n      send(data) {\n        this.body = data;\n        resolve(new Response(this.body, {\n          status: this.statusCode,\n          headers: this.headers,\n        }));\n      },\n      end() {\n        resolve(new Response(this.body, {\n          status: this.statusCode,\n          headers: this.headers,\n        }));\n      },\n    };\n    app(req, res);\n  });\n}\n\nmodule.exports = {\n  async fetch(request, env, ctx) {\n    return handleRequest(request);\n  }\n};\n`,\n\n  // #375 — fail the build when the user's @FrontMcp config references\n  // Node-only storage providers that can't run on Workers. Conditional\n  // (env-gated) usage still passes; only unconditional declarations throw.\n  validate: (decoratorConfig) => {\n    if (!decoratorConfig) return;\n    const sqlite = decoratorConfig['sqlite'];\n    const redis = decoratorConfig['redis'];\n    const errors: string[] = [];\n    if (sqlite && typeof sqlite === 'object') {\n      errors.push(\n        'sqlite storage is not supported on --target cloudflare (no fs / native modules on Workers). ' +\n          'Use Cloudflare KV / Durable Objects, or gate the sqlite branch behind a build-time `define` ' +\n          'so the bundler can dead-code-eliminate it.',\n      );\n    }\n    if (redis && typeof redis === 'object') {\n      errors.push(\n        'ioredis-style `redis` storage is not supported on --target cloudflare (no Node net). ' +\n          'Use Vercel KV / Upstash Redis (HTTP), or move the redis config to a runtime branch ' +\n          'gated on `globalThis.process?.env`.',\n      );\n    }\n    if (errors.length) {\n      throw new Error(\n        `[--target cloudflare] config incompatible with Cloudflare Workers:\\n  - ${errors.join('\\n  - ')}`,\n      );\n    }\n  },\n\n  // #374 — always write wrangler.toml from the build output. Skipping when\n  // the file already exists left users with a wrangler.toml that pointed at\n  // dist/index.js while the build emitted dist/cloudflare/index.js, and\n  // wrangler deploy silently failed.\n  alwaysWriteConfig: true,\n\n  getConfig: (_cwd: string) => `name = \"frontmcp-worker\"\nmain = \"dist/cloudflare/index.js\"\ncompatibility_date = \"2024-01-01\"\n`,\n\n  configFileName: 'wrangler.toml',\n};\n"]}

package/src/commands/build/adapters/distributed.js

@@ -23,7 +23,10 @@ process.env.FRONTMCP_DEPLOYMENT_MODE = 'distributed';
 `,
     getEntryTemplate: (mainModulePath) => `// Auto-generated distributed entry point
 // Generated by: frontmcp build --target distributed
-require('./ha-setup.js');
+// The build emits the HA bootstrap as serverless-setup.js (shared name across
+// all serverless/distributed adapters); requiring ha-setup.js used to crash at
+// runtime because that filename was never written.
+require('./serverless-setup.js');
 require('${mainModulePath}');
 `,
 };

package/src/commands/build/adapters/distributed.js.map

@@ -1 +1 @@
-{"version":3,"file":"distributed.js","sourceRoot":"","sources":["../../../../../src/commands/build/adapters/distributed.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;GAYG;AACU,QAAA,kBAAkB,GAAoB;IACjD,YAAY,EAAE,UAAU;IAExB,gBAAgB,EAAE,GAAG,EAAE,CAAC;;;;CAIzB;IAEC,gBAAgB,EAAE,CAAC,cAAsB,EAAE,EAAE,CAAC;;;WAGrC,cAAc;CACxB;CACA,CAAC","sourcesContent":["import type { AdapterTemplate } from '../types';\n\n/**\n * Distributed adapter - multi-pod Node.js deployment with HA.\n * Compiles to CommonJS with an HA setup file that sets FRONTMCP_DEPLOYMENT_MODE.\n *\n * The setup file runs before any imports to ensure the deployment mode\n * is detected before @FrontMcp decorators execute. This enables:\n * - Session heartbeat and takeover\n * - Cross-pod notification relay via Redis pub/sub\n * - LB affinity via __frontmcp_node cookie\n * - Machine ID from K8s HOSTNAME or os.hostname()\n *\n * Requires Redis configuration in @FrontMcp() for session persistence.\n */\nexport const distributedAdapter: AdapterTemplate = {\n  moduleFormat: 'commonjs',\n\n  getSetupTemplate: () => `// Distributed HA setup - MUST be imported first\n// Sets FRONTMCP_DEPLOYMENT_MODE before any decorators run\n// Enables heartbeat, session takeover, and notification relay\nprocess.env.FRONTMCP_DEPLOYMENT_MODE = 'distributed';\n`,\n\n  getEntryTemplate: (mainModulePath: string) => `// Auto-generated distributed entry point\n// Generated by: frontmcp build --target distributed\nrequire('./ha-setup.js');\nrequire('${mainModulePath}');\n`,\n};\n"]}
+{"version":3,"file":"distributed.js","sourceRoot":"","sources":["../../../../../src/commands/build/adapters/distributed.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;GAYG;AACU,QAAA,kBAAkB,GAAoB;IACjD,YAAY,EAAE,UAAU;IAExB,gBAAgB,EAAE,GAAG,EAAE,CAAC;;;;CAIzB;IAEC,gBAAgB,EAAE,CAAC,cAAsB,EAAE,EAAE,CAAC;;;;;;WAMrC,cAAc;CACxB;CACA,CAAC","sourcesContent":["import type { AdapterTemplate } from '../types';\n\n/**\n * Distributed adapter - multi-pod Node.js deployment with HA.\n * Compiles to CommonJS with an HA setup file that sets FRONTMCP_DEPLOYMENT_MODE.\n *\n * The setup file runs before any imports to ensure the deployment mode\n * is detected before @FrontMcp decorators execute. This enables:\n * - Session heartbeat and takeover\n * - Cross-pod notification relay via Redis pub/sub\n * - LB affinity via __frontmcp_node cookie\n * - Machine ID from K8s HOSTNAME or os.hostname()\n *\n * Requires Redis configuration in @FrontMcp() for session persistence.\n */\nexport const distributedAdapter: AdapterTemplate = {\n  moduleFormat: 'commonjs',\n\n  getSetupTemplate: () => `// Distributed HA setup - MUST be imported first\n// Sets FRONTMCP_DEPLOYMENT_MODE before any decorators run\n// Enables heartbeat, session takeover, and notification relay\nprocess.env.FRONTMCP_DEPLOYMENT_MODE = 'distributed';\n`,\n\n  getEntryTemplate: (mainModulePath: string) => `// Auto-generated distributed entry point\n// Generated by: frontmcp build --target distributed\n// The build emits the HA bootstrap as serverless-setup.js (shared name across\n// all serverless/distributed adapters); requiring ha-setup.js used to crash at\n// runtime because that filename was never written.\nrequire('./serverless-setup.js');\nrequire('${mainModulePath}');\n`,\n};\n"]}

package/src/commands/build/exec/cli-runtime/extract-public-message.snippet.d.ts

@@ -0,0 +1,18 @@
+/**
+ * CLI-bundle source for `_extractPublicMessage` / `_exitWithError`.
+ *
+ * The SEA CLI bundle has to be self-contained — it can't reach into
+ * `@frontmcp/sdk` at runtime — so we duplicate the SDK's
+ * `extractPublicMessage` walker into the generated source. To prevent the
+ * two implementations from drifting, the duplicated source lives in this
+ * file as a string constant and is shared by:
+ *
+ *   - `generateCliEntry.ts`           (embeds it in the generated CLI source)
+ *   - `extract-public-message-parity.spec.ts` (parity-tests it against
+ *      the SDK's TS implementation using shared fixtures)
+ *
+ * Keep the function bodies free of TS / ESM-only syntax — the resulting
+ * string is concatenated into a CommonJS bundle and `Function('return …')`
+ * compiles it as plain ES2020.
+ */
+export declare const EXTRACT_PUBLIC_MESSAGE_SNIPPET: string;

package/src/commands/build/exec/cli-runtime/extract-public-message.snippet.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXTRACT_PUBLIC_MESSAGE_SNIPPET = void 0;
+/**
+ * CLI-bundle source for `_extractPublicMessage` / `_exitWithError`.
+ *
+ * The SEA CLI bundle has to be self-contained — it can't reach into
+ * `@frontmcp/sdk` at runtime — so we duplicate the SDK's
+ * `extractPublicMessage` walker into the generated source. To prevent the
+ * two implementations from drifting, the duplicated source lives in this
+ * file as a string constant and is shared by:
+ *
+ *   - `generateCliEntry.ts`           (embeds it in the generated CLI source)
+ *   - `extract-public-message-parity.spec.ts` (parity-tests it against
+ *      the SDK's TS implementation using shared fixtures)
+ *
+ * Keep the function bodies free of TS / ESM-only syntax — the resulting
+ * string is concatenated into a CommonJS bundle and `Function('return …')`
+ * compiles it as plain ES2020.
+ */
+exports.EXTRACT_PUBLIC_MESSAGE_SNIPPET = `
+// Walk an error chain (cause / originalError) and return the most user-friendly
+// message — prefers PublicMcpError.getPublicMessage() over wrapped wrappers like
+// "Tool 'X' execution failed: Unknown error". Mirrors @frontmcp/sdk's
+// extractPublicMessage so the SEA bundle stays self-contained. Cycles in the
+// chain are short-circuited via a WeakSet of already-visited error objects.
+function _extractPublicMessage(err) {
+  return _extractPublicMessageImpl(err, new WeakSet());
+}
+function _extractPublicMessageImpl(err, visited) {
+  if (err && typeof err === 'object') {
+    if (visited.has(err)) return 'Unknown error';
+    visited.add(err);
+  }
+  if (err == null) return 'Unknown error';
+  if (typeof err === 'string') return err;
+  // Direct PublicMcpError (has isPublic === true and a non-default message)
+  if (err && err.isPublic === true && err.message) return err.message;
+  // Wrapped: try originalError, then cause.
+  var inner = err && (err.originalError || err.cause);
+  if (inner) {
+    var innerMsg = _extractPublicMessageImpl(inner, visited);
+    if (innerMsg && innerMsg !== 'Unknown error') return innerMsg;
+  }
+  // Fallback: own .message, but skip generic wrappers when we have nothing better.
+  if (err.message) return err.message;
+  return String(err);
+}
+// Print an error with the best available public message and set the appropriate
+// exit code (1 = runtime error, 2 = usage error). Centralized so every action
+// handler reports the same shape.
+function _exitWithError(err, code) {
+  var msg = _extractPublicMessage(err);
+  console.error('Error: ' + msg);
+  process.exitCode = code || 1;
+}
+`.trim();
+//# sourceMappingURL=extract-public-message.snippet.js.map

package/src/commands/build/exec/cli-runtime/extract-public-message.snippet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-public-message.snippet.js","sourceRoot":"","sources":["../../../../../../src/commands/build/exec/cli-runtime/extract-public-message.snippet.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;GAgBG;AACU,QAAA,8BAA8B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoC7C,CAAC,IAAI,EAAE,CAAC","sourcesContent":["/**\n * CLI-bundle source for `_extractPublicMessage` / `_exitWithError`.\n *\n * The SEA CLI bundle has to be self-contained — it can't reach into\n * `@frontmcp/sdk` at runtime — so we duplicate the SDK's\n * `extractPublicMessage` walker into the generated source. To prevent the\n * two implementations from drifting, the duplicated source lives in this\n * file as a string constant and is shared by:\n *\n *   - `generateCliEntry.ts`           (embeds it in the generated CLI source)\n *   - `extract-public-message-parity.spec.ts` (parity-tests it against\n *      the SDK's TS implementation using shared fixtures)\n *\n * Keep the function bodies free of TS / ESM-only syntax — the resulting\n * string is concatenated into a CommonJS bundle and `Function('return …')`\n * compiles it as plain ES2020.\n */\nexport const EXTRACT_PUBLIC_MESSAGE_SNIPPET = `\n// Walk an error chain (cause / originalError) and return the most user-friendly\n// message — prefers PublicMcpError.getPublicMessage() over wrapped wrappers like\n// \"Tool 'X' execution failed: Unknown error\". Mirrors @frontmcp/sdk's\n// extractPublicMessage so the SEA bundle stays self-contained. Cycles in the\n// chain are short-circuited via a WeakSet of already-visited error objects.\nfunction _extractPublicMessage(err) {\n  return _extractPublicMessageImpl(err, new WeakSet());\n}\nfunction _extractPublicMessageImpl(err, visited) {\n  if (err && typeof err === 'object') {\n    if (visited.has(err)) return 'Unknown error';\n    visited.add(err);\n  }\n  if (err == null) return 'Unknown error';\n  if (typeof err === 'string') return err;\n  // Direct PublicMcpError (has isPublic === true and a non-default message)\n  if (err && err.isPublic === true && err.message) return err.message;\n  // Wrapped: try originalError, then cause.\n  var inner = err && (err.originalError || err.cause);\n  if (inner) {\n    var innerMsg = _extractPublicMessageImpl(inner, visited);\n    if (innerMsg && innerMsg !== 'Unknown error') return innerMsg;\n  }\n  // Fallback: own .message, but skip generic wrappers when we have nothing better.\n  if (err.message) return err.message;\n  return String(err);\n}\n// Print an error with the best available public message and set the appropriate\n// exit code (1 = runtime error, 2 = usage error). Centralized so every action\n// handler reports the same shape.\nfunction _exitWithError(err, code) {\n  var msg = _extractPublicMessage(err);\n  console.error('Error: ' + msg);\n  process.exitCode = code || 1;\n}\n`.trim();\n"]}

package/src/commands/build/exec/cli-runtime/generate-cli-entry.d.ts

@@ -2,8 +2,8 @@
  * Generates the CLI entry point TypeScript/JavaScript source code.
  * This creates a commander.js-based CLI where each MCP tool is a subcommand.
  */
-import { CliConfig, OAuthConfig } from '../config';
-import { ExtractedSchema } from './schema-extractor';
+import { type CliConfig, type OAuthConfig } from '../config';
+import { type ExtractedSchema } from './schema-extractor';
 export declare const RESERVED_COMMANDS: Set<string>;
 export interface CliEntryOptions {
     appName: string;

package/src/commands/build/exec/cli-runtime/generate-cli-entry.js

@@ -8,6 +8,7 @@ exports.RESERVED_COMMANDS = void 0;
 exports.resolveToolCommandName = resolveToolCommandName;
 exports.generateCliEntry = generateCliEntry;
 exports.extractTemplateParams = extractTemplateParams;
+const extract_public_message_snippet_1 = require("./extract-public-message.snippet");
 const schema_extractor_1 = require("./schema-extractor");
 const schema_to_commander_1 = require("./schema-to-commander");
 exports.RESERVED_COMMANDS = new Set([
@@ -15,6 +16,9 @@ exports.RESERVED_COMMANDS = new Set([
     'login', 'logout', 'connect', 'serve', 'daemon',
     'doctor', 'install', 'uninstall', 'sessions', 'help', 'version',
     'skills', 'job', 'workflow',
+    // Reserved by the symmetric `prompt get <name>` / `resource read <uri>`
+    // sub-API; included so a user-defined entry can never shadow them.
+    'get', 'list', 'read',
 ]);
 /**
  * Resolve tool command name, appending '-tool' suffix if it conflicts with a built-in command.
@@ -193,7 +197,31 @@ async function closeClient() {
 // Flag set by long-running commands (serve, daemon) to prevent the footer from calling process.exit().
 var _isLongRunning = false;
 
+${extract_public_message_snippet_1.EXTRACT_PUBLIC_MESSAGE_SNIPPET}
+
 var program = new Command();
+// Make Commander's own usage errors (unknown subcommand, missing required option,
+// invalid value) exit with code 2 instead of the default 0 — matches POSIX
+// convention and lets shell scripts/CI distinguish runtime failures from usage.
+//
+// Sets process.exitCode and re-throws so the parseAsync() footer can run
+// closeClient() / native-addon teardown before the actual exit. Calling
+// process.exit() directly here would skip that and could leave better-sqlite3
+// / ONNX / file handles in a corrupt state for short-lived runs.
+program.exitOverride(function(err) {
+  if (err.code === 'commander.helpDisplayed' || err.code === 'commander.help' || err.code === 'commander.version') {
+    process.exitCode = 0;
+  } else if (err.code === 'commander.unknownCommand' || err.code === 'commander.unknownOption' ||
+      err.code === 'commander.missingArgument' || err.code === 'commander.missingMandatoryOptionValue' ||
+      err.code === 'commander.invalidArgument' || err.code === 'commander.optionMissingArgument' ||
+      err.code === 'commander.invalidOptionArgument' || err.code === 'commander.excessArguments') {
+    process.exitCode = 2;
+  } else {
+    process.exitCode = 1;
+  }
+  // Re-throw so parseAsync().catch in the footer runs cleanup before exit.
+  throw err;
+});
 program
   .name(${JSON.stringify(appName)})
   .version(${JSON.stringify(appVersion)})
@@ -280,16 +308,28 @@ ${optionLines}
       var result = await client.callTool(${JSON.stringify(tool.name)}, args);
       var mode = program.opts().output || ${JSON.stringify('text')};
       console.log(fmt.formatToolResult(result, mode));
+      // The SDK converts thrown errors into a CallToolResult with isError:true
+      // (so HTTP/JSON-RPC clients still get a structured response). Detect
+      // that here and map to a non-zero exit code so shell scripts can gate
+      // on success — Zod input validation errors → exit 2 (usage), all
+      // other tool errors → exit 1 (runtime).
+      if (result && result.isError === true) {
+        var rmeta = (result && result._meta) || {};
+        process.exitCode = (rmeta.code === 'INVALID_INPUT') ? 2 : 1;
+      }
     } catch (err) {
       var meta = err && err._meta ? err._meta : (err && err.data && err.data._meta ? err.data._meta : null);
       if (meta && meta.authorization_required) {
         console.error('Authorization required' + (meta.app ? ' for ' + meta.app : ''));
         if (meta.auth_url) console.error('Authorize at: ' + meta.auth_url);
         console.error('Or run: ' + ${JSON.stringify(appName)} + ' login');
+        process.exitCode = 1;
       } else {
-        console.error('Error:', err.message || err);
+        // Thrown error path (transport / DI / pre-flow failure) — same
+        // mapping as the isError result path above.
+        var isUsage = err && err.code === 'INVALID_INPUT';
+        _exitWithError(err, isUsage ? 2 : 1);
       }
-      process.exitCode = 1;
     }
   });`;
     });
@@ -362,8 +402,7 @@ resourceCmd
         });
       }
     } catch (err) {
-      console.error('Error:', err.message || err);
-      process.exitCode = 1;
+      _exitWithError(err, 1);
     }
   });
 
@@ -377,8 +416,7 @@ resourceCmd
       var mode = program.opts().output || 'text';
       console.log(fmt.formatResourceResult(result, mode));
     } catch (err) {
-      console.error('Error:', err.message || err);
-      process.exitCode = 1;
+      _exitWithError(err, 1);
     }
   });`;
 }
@@ -412,8 +450,7 @@ ${optionLines}
       var mode = program.opts().output || 'text';
       console.log(fmt.formatResourceResult(result, mode));
     } catch (err) {
-      console.error('Error:', err.message || err);
-      process.exitCode = 1;
+      _exitWithError(err, 1);
     }
   });`;
     });
@@ -437,14 +474,25 @@ templateCmd
         });
       }
     } catch (err) {
-      console.error('Error:', err.message || err);
-      process.exitCode = 1;
+      _exitWithError(err, 1);
     }
   });
 
 ${subcommands.join('\n\n')}`;
 }
 function generatePromptCommands(prompts) {
+    // Map known prompts → option specs so `prompt get <name>` knows which flags
+    // to accept per prompt. Unknown prompt names still call getPrompt() and
+    // surface the server's error to the user.
+    const promptArgsMap = prompts.map((p) => {
+        const args = (p.arguments || []).map((a) => ({
+            name: a.name,
+            kebab: (0, schema_to_commander_1.camelToKebab)(a.name),
+            camel: kebabToCamel((0, schema_to_commander_1.camelToKebab)(a.name)),
+            required: !!a.required,
+        }));
+        return `${JSON.stringify(p.name)}: ${JSON.stringify(args)}`;
+    }).join(',\n      ');
     const subcommands = prompts.map((prompt) => {
         const cmdName = (0, schema_to_commander_1.camelToKebab)(prompt.name).replace(/_/g, '-');
         const argOptions = (prompt.arguments || [])
@@ -458,7 +506,7 @@ function generatePromptCommands(prompts) {
             .join('\n');
         return `promptCmd
   .command(${JSON.stringify(cmdName)})
-  .description(${JSON.stringify(prompt.description || '')})
+  .description(${JSON.stringify((prompt.description || '') + ' (deprecated alias — use `prompt get ' + cmdName + '`)')})
 ${argOptions}
   .action(async function(opts) {
     try {
@@ -473,8 +521,7 @@ ${argOptions}
       var mode = program.opts().output || 'text';
       console.log(fmt.formatPromptResult(result, mode));
     } catch (err) {
-      console.error('Error:', err.message || err);
-      process.exitCode = 1;
+      _exitWithError(err, 1);
     }
   });`;
     });
@@ -498,8 +545,83 @@ promptCmd
         });
       }
     } catch (err) {
-      console.error('Error:', err.message || err);
-      process.exitCode = 1;
+      _exitWithError(err, 1);
+    }
+  });
+
+// Symmetric \`prompt get <name>\` to mirror \`resource read <uri>\`. Looks up
+// per-prompt argument metadata from \`promptArgs\` and forwards as MCP
+// \`prompts/get\` request arguments. Unknown / missing required flags exit 2.
+//
+// Robust flag parser supports:
+//   --key value         (canonical form)
+//   --key=value         (single-token form)
+//   --bool              (boolean — value defaults to "true")
+//   --                  (end-of-options marker; everything after is ignored)
+// Unknown flags fail-fast with exit 2 instead of being silently dropped.
+var promptArgs = {
+      ${promptArgsMap}
+    };
+var _getCmd = promptCmd
+  .command('get <name>')
+  .description('Render a prompt by name')
+  .allowUnknownOption(true)
+  .action(async function(name) {
+    try {
+      var spec = promptArgs[name];
+      if (!spec) {
+        console.error('Error: Unknown prompt: ' + name);
+        process.exitCode = 1;
+        return;
+      }
+      var rawTokens = this.args.slice(1);
+      var args = {};
+      var unknown = [];
+      var byKebab = {};
+      for (var s = 0; s < spec.length; s++) byKebab[spec[s].kebab] = spec[s];
+      for (var i = 0; i < rawTokens.length; i++) {
+        var tok = rawTokens[i];
+        if (tok === '--') break;
+        if (typeof tok !== 'string' || tok.indexOf('--') !== 0) continue;
+        var keyAndVal = tok.slice(2);
+        var key, val;
+        var eq = keyAndVal.indexOf('=');
+        if (eq >= 0) {
+          key = keyAndVal.slice(0, eq);
+          val = keyAndVal.slice(eq + 1);
+        } else {
+          key = keyAndVal;
+          var next = (i + 1 < rawTokens.length) ? rawTokens[i + 1] : undefined;
+          if (typeof next === 'string' && next.indexOf('--') !== 0) {
+            val = next;
+            i++;
+          } else {
+            val = 'true';
+          }
+        }
+        var match = byKebab[key];
+        if (!match) { unknown.push('--' + key); continue; }
+        args[match.name] = val;
+      }
+      if (unknown.length > 0) {
+        console.error('Error: unknown option(s) for prompt "' + name + '": ' + unknown.join(', '));
+        process.exitCode = 2;
+        return;
+      }
+      // Validate required args
+      for (var r = 0; r < spec.length; r++) {
+        if (spec[r].required && args[spec[r].name] === undefined) {
+          console.error('Error: missing required option --' + spec[r].kebab);
+          process.exitCode = 2;
+          return;
+        }
+      }
+      var client = await getClient();
+      var result = await client.getPrompt(name, args);
+      var mode = program.opts().output || 'text';
+      console.log(fmt.formatPromptResult(result, mode));
+    } catch (err) {
+      _exitWithError(err, 1);
     }
   });
 
@@ -535,8 +657,7 @@ skillsCmd
         console.log("  Use '" + program.name() + " skills load <name>' to load a skill.\\n");
       }
     } catch (err) {
-      console.error('Error:', err.message || err);
-      process.exitCode = 1;
+      _exitWithError(err, 1);
     }
   });
 
@@ -557,8 +678,7 @@ skillsCmd
         }
       }
     } catch (err) {
-      console.error('Error:', err.message || err);
-      process.exitCode = 1;
+      _exitWithError(err, 1);
     }
   });
 
@@ -594,8 +714,7 @@ skillsCmd
         console.log("  Load: " + program.name() + " skills load " + name + '\\n');
       }
     } catch (err) {
-      console.error('Error:', err.message || err);
-      process.exitCode = 1;
+      _exitWithError(err, 1);
     }
   });
 
@@ -623,8 +742,7 @@ skillsCmd
         console.log("  Use '" + program.name() + " skills read <name>' for full details.\\n");
       }
     } catch (err) {
-      console.error('Error:', err.message || err);
-      process.exitCode = 1;
+      _exitWithError(err, 1);
     }
   });`;
 }
@@ -659,8 +777,7 @@ ${optionLines}
         }
       }
     } catch (err) {
-      console.error('Error:', err.message || err);
-      process.exitCode = 1;
+      _exitWithError(err, 1);
     }
   });`;
         }
@@ -690,8 +807,7 @@ ${optionLines}
         }
       }
     } catch (err) {
-      console.error('Error:', err.message || err);
-      process.exitCode = 1;
+      _exitWithError(err, 1);
     }
   });`;
     });
@@ -721,8 +837,7 @@ ${optionLines}
         }
       }
     } catch (err) {
-      console.error('Error:', err.message || err);
-      process.exitCode = 1;
+      _exitWithError(err, 1);
     }
   });`;
     return `var jobCmd = program.command('job').description('Job operations');
@@ -749,8 +864,7 @@ jobCmd
         }
       }
     } catch (err) {
-      console.error('Error:', err.message || err);
-      process.exitCode = 1;
+      _exitWithError(err, 1);
     }
   });
 
@@ -782,8 +896,7 @@ ${jobs.length > 0 ? genericRun : `jobRunCmd
         }
       }
     } catch (err) {
-      console.error('Error:', err.message || err);
-      process.exitCode = 1;
+      _exitWithError(err, 1);
     }
   });`}
 
@@ -801,8 +914,7 @@ jobCmd
         console.log('Status: ' + (result.status || JSON.stringify(result)));
       }
     } catch (err) {
-      console.error('Error:', err.message || err);
-      process.exitCode = 1;
+      _exitWithError(err, 1);
     }
   });`;
 }
@@ -831,8 +943,7 @@ workflowCmd
         }
       }
     } catch (err) {
-      console.error('Error:', err.message || err);
-      process.exitCode = 1;
+      _exitWithError(err, 1);
     }
   });
 
@@ -861,8 +972,7 @@ workflowCmd
         }
       }
     } catch (err) {
-      console.error('Error:', err.message || err);
-      process.exitCode = 1;
+      _exitWithError(err, 1);
     }
   });
 
@@ -880,8 +990,7 @@ workflowCmd
         console.log('Status: ' + (result.status || JSON.stringify(result)));
       }
     } catch (err) {
-      console.error('Error:', err.message || err);
-      process.exitCode = 1;
+      _exitWithError(err, 1);
     }
   });`;
 }
@@ -933,8 +1042,7 @@ subscribeCmd
       setInterval(function() {}, 2147483647);
       await new Promise(function() {});
     } catch (err) {
-      console.error('Error:', err.message || err);
-      process.exitCode = 1;
+      _exitWithError(err, 1);
     }
   });
 
@@ -962,8 +1070,7 @@ subscribeCmd
       setInterval(function() {}, 2147483647);
       await new Promise(function() {});
     } catch (err) {
-      console.error('Error:', err.message || err);
-      process.exitCode = 1;
+      _exitWithError(err, 1);
     }
   });`;
 }
@@ -1521,9 +1628,20 @@ program.parseAsync(process.argv).then(async function() {
   // (ONNX runtime, etc.) can release mutexes before V8 tears down.
   setImmediate(function() { process.exit(process.exitCode || 0); });
 }).catch(async function(err) {
-  console.error('Fatal:', err.message || err);
+  // Commander errors come through exitOverride with the code already set on
+  // process.exitCode. They are user-facing usage errors, not fatals — don't
+  // re-print "Fatal:" / "Unknown error" for them.
+  var isCommanderErr = err && typeof err.code === 'string' && err.code.indexOf('commander.') === 0;
+  if (!isCommanderErr) {
+    console.error('Fatal:', err.message || err);
+  }
   await closeClient();
-  process.exit(1);
+  // Use the exit code set by exitOverride (which can legitimately be 0 for
+  // --help / --version). Only fall back to 1 when no code was set.
+  setImmediate(function() {
+    var code = (typeof process.exitCode === 'number') ? process.exitCode : 1;
+    process.exit(code);
+  });
 });`;
 }
 /**