@mastra/deployer 1.0.0-beta.8 → 1.0.0

package/dist/server/index.js

@@ -1,16 +1,18 @@
+import { normalizeStudioBase } from '../chunk-QAOUDKHK.js';
 import { readFile } from 'fs/promises';
 import * as https from 'https';
-import { join } from 'path/posix';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
 import { createServer } from 'http';
 import { Http2ServerRequest } from 'http2';
 import { Writable, Readable } from 'stream';
 import crypto from 'crypto';
 import { getMimeType } from 'hono/utils/mime';
 import { existsSync, createReadStream, lstatSync } from 'fs';
-import { join as join$1 } from 'path';
 import { html } from 'hono/html';
 import { Tool } from '@mastra/core/tools';
-import { MastraServer as MastraServer$1, redactStreamChunk } from '@mastra/server/server-adapter';
+import { formatZodError } from '@mastra/server/handlers/error';
+import { MastraServer as MastraServer$1, normalizeQueryParams, redactStreamChunk } from '@mastra/server/server-adapter';
 import util from 'util';
 import { Buffer as Buffer$1 } from 'buffer';
 import { isDevPlaygroundRequest, isProtectedPath, canAccessPublicly, checkRules, defaultAuthConfig } from '@mastra/server/auth';
@@ -57,7 +59,7 @@ var newHeadersFromIncoming = (incoming) => {
   }
   return new Headers(headerRecord);
 };
-var wrapBodyStream = Symbol("wrapBodyStream");
+var wrapBodyStream = /* @__PURE__ */ Symbol("wrapBodyStream");
 var newRequestFromIncoming = (method, url, headers, incoming, abortController) => {
   const init = {
     method,
@@ -105,13 +107,13 @@ var newRequestFromIncoming = (method, url, headers, incoming, abortController) =
   }
   return new Request2(url, init);
 };
-var getRequestCache = Symbol("getRequestCache");
-var requestCache = Symbol("requestCache");
-var incomingKey = Symbol("incomingKey");
-var urlKey = Symbol("urlKey");
-var headersKey = Symbol("headersKey");
-var abortControllerKey = Symbol("abortControllerKey");
-var getAbortController = Symbol("getAbortController");
+var getRequestCache = /* @__PURE__ */ Symbol("getRequestCache");
+var requestCache = /* @__PURE__ */ Symbol("requestCache");
+var incomingKey = /* @__PURE__ */ Symbol("incomingKey");
+var urlKey = /* @__PURE__ */ Symbol("urlKey");
+var headersKey = /* @__PURE__ */ Symbol("headersKey");
+var abortControllerKey = /* @__PURE__ */ Symbol("abortControllerKey");
+var getAbortController = /* @__PURE__ */ Symbol("getAbortController");
 var requestPrototype = {
   get method() {
     return this[incomingKey].method || "GET";
@@ -202,9 +204,9 @@ var newRequest = (incoming, defaultHostname) => {
   req[urlKey] = url.href;
   return req;
 };
-var responseCache = Symbol("responseCache");
-var getResponseCache = Symbol("getResponseCache");
-var cacheKey = Symbol("cache");
+var responseCache = /* @__PURE__ */ Symbol("responseCache");
+var getResponseCache = /* @__PURE__ */ Symbol("getResponseCache");
+var cacheKey = /* @__PURE__ */ Symbol("cache");
 var GlobalResponse = global.Response;
 var Response2 = class _Response {
   #body;
@@ -346,7 +348,7 @@ global.fetch = (info, init) => {
   };
   return webFetch(info, init);
 };
-var outgoingEnded = Symbol("outgoingEnded");
+var outgoingEnded = /* @__PURE__ */ Symbol("outgoingEnded");
 var handleRequestError = () => new Response(null, {
   status: 400
 });
@@ -627,14 +629,14 @@ var serveStatic = (options = { root: "" }) => {
         return next();
       }
     }
-    let path = join$1(
+    let path = join(
       root,
       !optionPath && options.rewriteRequestPath ? options.rewriteRequestPath(filename, c) : filename
     );
     let stats = getStats(path);
     if (stats && stats.isDirectory()) {
       const indexFile = options.index ?? "index.html";
-      path = join$1(path, indexFile);
+      path = join(path, indexFile);
       stats = getStats(path);
     }
     if (!stats) {
@@ -1000,12 +1002,12 @@ var ERR_STREAM_WRITE_AFTER_END = class extends Error {
 };
 
 // ../../node_modules/.pnpm/fetch-to-node@2.1.0/node_modules/fetch-to-node/dist/fetch-to-node/http-incoming.js
-var kHeaders = Symbol("kHeaders");
-var kHeadersDistinct = Symbol("kHeadersDistinct");
-var kHeadersCount = Symbol("kHeadersCount");
-var kTrailers = Symbol("kTrailers");
-var kTrailersDistinct = Symbol("kTrailersDistinct");
-var kTrailersCount = Symbol("kTrailersCount");
+var kHeaders = /* @__PURE__ */ Symbol("kHeaders");
+var kHeadersDistinct = /* @__PURE__ */ Symbol("kHeadersDistinct");
+var kHeadersCount = /* @__PURE__ */ Symbol("kHeadersCount");
+var kTrailers = /* @__PURE__ */ Symbol("kTrailers");
+var kTrailersDistinct = /* @__PURE__ */ Symbol("kTrailersDistinct");
+var kTrailersCount = /* @__PURE__ */ Symbol("kTrailersCount");
 var FetchIncomingMessage = class extends Readable {
   get socket() {
     return null;
@@ -1371,8 +1373,8 @@ function isUint8Array(value) {
 }
 
 // ../../node_modules/.pnpm/fetch-to-node@2.1.0/node_modules/fetch-to-node/dist/fetch-to-node/internal-http.js
-var kNeedDrain = Symbol("kNeedDrain");
-var kOutHeaders = Symbol("kOutHeaders");
+var kNeedDrain = /* @__PURE__ */ Symbol("kNeedDrain");
+var kOutHeaders = /* @__PURE__ */ Symbol("kOutHeaders");
 function utcDate() {
   return (/* @__PURE__ */ new Date()).toUTCString();
 }
@@ -1392,14 +1394,14 @@ function checkInvalidHeaderChar(val) {
   return headerCharRegex.test(val);
 }
 var chunkExpression = /(?:^|\W)chunked(?:$|\W)/i;
-var kCorked = Symbol("corked");
-var kChunkedBuffer = Symbol("kChunkedBuffer");
-var kChunkedLength = Symbol("kChunkedLength");
-var kUniqueHeaders = Symbol("kUniqueHeaders");
-var kBytesWritten = Symbol("kBytesWritten");
-var kErrored = Symbol("errored");
-var kHighWaterMark = Symbol("kHighWaterMark");
-var kRejectNonStandardBodyWrites = Symbol("kRejectNonStandardBodyWrites");
+var kCorked = /* @__PURE__ */ Symbol("corked");
+var kChunkedBuffer = /* @__PURE__ */ Symbol("kChunkedBuffer");
+var kChunkedLength = /* @__PURE__ */ Symbol("kChunkedLength");
+var kUniqueHeaders = /* @__PURE__ */ Symbol("kUniqueHeaders");
+var kBytesWritten = /* @__PURE__ */ Symbol("kBytesWritten");
+var kErrored = /* @__PURE__ */ Symbol("errored");
+var kHighWaterMark = /* @__PURE__ */ Symbol("kHighWaterMark");
+var kRejectNonStandardBodyWrites = /* @__PURE__ */ Symbol("kRejectNonStandardBodyWrites");
 var nop = () => {
 };
 var RE_CONN_CLOSE = /(?:^|\W)close(?:$|\W)/i;
@@ -2666,11 +2668,21 @@ function toFetchResponse(res) {
 var HTTPException = class extends Error {
   res;
   status;
+  /**
+   * Creates an instance of `HTTPException`.
+   * @param status - HTTP status code for the exception. Defaults to 500.
+   * @param options - Additional options for the exception.
+   */
   constructor(status = 500, options) {
     super(options?.message, { cause: options?.cause });
     this.res = options?.res;
     this.status = status;
   }
+  /**
+   * Returns the response object associated with the exception.
+   * If a response object is not provided, a new response is created with the error message and status code.
+   * @returns The response object.
+   */
   getResponse() {
     if (this.res) {
       const newResponse = new Response(this.res.body, {
@@ -2745,7 +2757,13 @@ var StreamingApi = class {
   writable;
   abortSubscribers = [];
   responseReadable;
+  /**
+   * Whether the stream has been aborted.
+   */
   aborted = false;
+  /**
+   * Whether the stream has been closed normally.
+   */
   closed = false;
   constructor(writable, _readable) {
     this.writable = writable;
@@ -2797,6 +2815,10 @@ var StreamingApi = class {
   onAbort(listener) {
     this.abortSubscribers.push(listener);
   }
+  /**
+   * Abort the stream.
+   * You can call this method when stream is aborted by external event.
+   */
   abort() {
     if (!this.aborted) {
       this.aborted = true;
@@ -2841,6 +2863,209 @@ var stream = (c, cb, onError3) => {
   })();
   return c.newResponse(stream2.responseReadable);
 };
+var util2;
+(function(util22) {
+  util22.assertEqual = (_) => {
+  };
+  function assertIs(_arg) {
+  }
+  util22.assertIs = assertIs;
+  function assertNever(_x) {
+    throw new Error();
+  }
+  util22.assertNever = assertNever;
+  util22.arrayToEnum = (items) => {
+    const obj = {};
+    for (const item of items) {
+      obj[item] = item;
+    }
+    return obj;
+  };
+  util22.getValidEnumValues = (obj) => {
+    const validKeys = util22.objectKeys(obj).filter((k) => typeof obj[obj[k]] !== "number");
+    const filtered = {};
+    for (const k of validKeys) {
+      filtered[k] = obj[k];
+    }
+    return util22.objectValues(filtered);
+  };
+  util22.objectValues = (obj) => {
+    return util22.objectKeys(obj).map(function(e) {
+      return obj[e];
+    });
+  };
+  util22.objectKeys = typeof Object.keys === "function" ? (obj) => Object.keys(obj) : (object) => {
+    const keys = [];
+    for (const key in object) {
+      if (Object.prototype.hasOwnProperty.call(object, key)) {
+        keys.push(key);
+      }
+    }
+    return keys;
+  };
+  util22.find = (arr, checker) => {
+    for (const item of arr) {
+      if (checker(item))
+        return item;
+    }
+    return void 0;
+  };
+  util22.isInteger = typeof Number.isInteger === "function" ? (val) => Number.isInteger(val) : (val) => typeof val === "number" && Number.isFinite(val) && Math.floor(val) === val;
+  function joinValues(array, separator = " | ") {
+    return array.map((val) => typeof val === "string" ? `'${val}'` : val).join(separator);
+  }
+  util22.joinValues = joinValues;
+  util22.jsonStringifyReplacer = (_, value) => {
+    if (typeof value === "bigint") {
+      return value.toString();
+    }
+    return value;
+  };
+})(util2 || (util2 = {}));
+var objectUtil;
+(function(objectUtil2) {
+  objectUtil2.mergeShapes = (first, second) => {
+    return {
+      ...first,
+      ...second
+      // second overwrites first
+    };
+  };
+})(objectUtil || (objectUtil = {}));
+util2.arrayToEnum([
+  "string",
+  "nan",
+  "number",
+  "integer",
+  "float",
+  "boolean",
+  "date",
+  "bigint",
+  "symbol",
+  "function",
+  "undefined",
+  "null",
+  "array",
+  "object",
+  "unknown",
+  "promise",
+  "void",
+  "never",
+  "map",
+  "set"
+]);
+util2.arrayToEnum([
+  "invalid_type",
+  "invalid_literal",
+  "custom",
+  "invalid_union",
+  "invalid_union_discriminator",
+  "invalid_enum_value",
+  "unrecognized_keys",
+  "invalid_arguments",
+  "invalid_return_type",
+  "invalid_date",
+  "invalid_string",
+  "too_small",
+  "too_big",
+  "invalid_intersection_types",
+  "not_multiple_of",
+  "not_finite"
+]);
+var ZodError = class _ZodError extends Error {
+  get errors() {
+    return this.issues;
+  }
+  constructor(issues) {
+    super();
+    this.issues = [];
+    this.addIssue = (sub) => {
+      this.issues = [...this.issues, sub];
+    };
+    this.addIssues = (subs = []) => {
+      this.issues = [...this.issues, ...subs];
+    };
+    const actualProto = new.target.prototype;
+    if (Object.setPrototypeOf) {
+      Object.setPrototypeOf(this, actualProto);
+    } else {
+      this.__proto__ = actualProto;
+    }
+    this.name = "ZodError";
+    this.issues = issues;
+  }
+  format(_mapper) {
+    const mapper = _mapper || function(issue) {
+      return issue.message;
+    };
+    const fieldErrors = { _errors: [] };
+    const processError = (error) => {
+      for (const issue of error.issues) {
+        if (issue.code === "invalid_union") {
+          issue.unionErrors.map(processError);
+        } else if (issue.code === "invalid_return_type") {
+          processError(issue.returnTypeError);
+        } else if (issue.code === "invalid_arguments") {
+          processError(issue.argumentsError);
+        } else if (issue.path.length === 0) {
+          fieldErrors._errors.push(mapper(issue));
+        } else {
+          let curr = fieldErrors;
+          let i = 0;
+          while (i < issue.path.length) {
+            const el = issue.path[i];
+            const terminal = i === issue.path.length - 1;
+            if (!terminal) {
+              curr[el] = curr[el] || { _errors: [] };
+            } else {
+              curr[el] = curr[el] || { _errors: [] };
+              curr[el]._errors.push(mapper(issue));
+            }
+            curr = curr[el];
+            i++;
+          }
+        }
+      }
+    };
+    processError(this);
+    return fieldErrors;
+  }
+  static assert(value) {
+    if (!(value instanceof _ZodError)) {
+      throw new Error(`Not a ZodError: ${value}`);
+    }
+  }
+  toString() {
+    return this.message;
+  }
+  get message() {
+    return JSON.stringify(this.issues, util2.jsonStringifyReplacer, 2);
+  }
+  get isEmpty() {
+    return this.issues.length === 0;
+  }
+  flatten(mapper = (issue) => issue.message) {
+    const fieldErrors = {};
+    const formErrors = [];
+    for (const sub of this.issues) {
+      if (sub.path.length > 0) {
+        const firstEl = sub.path[0];
+        fieldErrors[firstEl] = fieldErrors[firstEl] || [];
+        fieldErrors[firstEl].push(mapper(sub));
+      } else {
+        formErrors.push(mapper(sub));
+      }
+    }
+    return { formErrors, fieldErrors };
+  }
+  get formErrors() {
+    return this.flatten();
+  }
+};
+ZodError.create = (issues) => {
+  const error = new ZodError(issues);
+  return error;
+};
 var authenticationMiddleware = async (c, next) => {
   const mastra = c.get("mastra");
   const authConfig = mastra.getServer()?.auth;
@@ -2984,8 +3209,6 @@ var MastraServer = class extends MastraServer$1 {
       c.set("mastra", this.mastra);
       c.set("tools", this.tools || {});
       c.set("taskStore", this.taskStore);
-      c.set("playground", this.playground === true);
-      c.set("isDev", this.isDev === true);
       c.set("abortSignal", c.req.raw.signal);
       c.set("customRouteAuthConfig", this.customRouteAuthConfig);
       return next();
@@ -3033,16 +3256,51 @@ var MastraServer = class extends MastraServer$1 {
   }
   async getParams(route, request) {
     const urlParams = request.param();
-    const queryParams = request.query();
+    const queryParams = normalizeQueryParams(request.queries());
     let body;
     if (route.method === "POST" || route.method === "PUT" || route.method === "PATCH") {
-      try {
-        body = await request.json();
-      } catch {
+      const contentType = request.header("content-type") || "";
+      if (contentType.includes("multipart/form-data")) {
+        try {
+          const formData = await request.formData();
+          body = await this.parseFormData(formData);
+        } catch (error) {
+          console.error("Failed to parse multipart form data:", error);
+          if (error instanceof Error && error.message.toLowerCase().includes("size")) {
+            throw error;
+          }
+        }
+      } else {
+        try {
+          body = await request.json();
+        } catch (error) {
+          console.error("Failed to parse JSON body:", error);
+        }
       }
     }
     return { urlParams, queryParams, body };
   }
+  /**
+   * Parse FormData into a plain object, converting File objects to Buffers.
+   */
+  async parseFormData(formData) {
+    const result = {};
+    for (const [key, value] of formData.entries()) {
+      if (value instanceof File) {
+        const arrayBuffer = await value.arrayBuffer();
+        result[key] = Buffer.from(arrayBuffer);
+      } else if (typeof value === "string") {
+        try {
+          result[key] = JSON.parse(value);
+        } catch {
+          result[key] = value;
+        }
+      } else {
+        result[key] = value;
+      }
+    }
+    return result;
+  }
   async sendResponse(route, response, result) {
     if (route.responseType === "json") {
       return response.json(result, 200);
@@ -3114,10 +3372,13 @@ var MastraServer = class extends MastraServer$1 {
             params.queryParams = await this.parseQueryParams(route, params.queryParams);
           } catch (error) {
             console.error("Error parsing query params", error);
+            if (error instanceof ZodError) {
+              return c.json(formatZodError(error, "query parameters"), 400);
+            }
             return c.json(
               {
                 error: "Invalid query parameters",
-                details: error instanceof Error ? error.message : "Unknown error"
+                issues: [{ field: "unknown", message: error instanceof Error ? error.message : "Unknown error" }]
               },
               400
             );
@@ -3128,10 +3389,13 @@ var MastraServer = class extends MastraServer$1 {
             params.body = await this.parseBody(route, params.body);
           } catch (error) {
             console.error("Error parsing body:", error instanceof Error ? error.message : String(error));
+            if (error instanceof ZodError) {
+              return c.json(formatZodError(error, "request body"), 400);
+            }
             return c.json(
               {
                 error: "Invalid request body",
-                details: error instanceof Error ? error.message : "Unknown error"
+                issues: [{ field: "unknown", message: error instanceof Error ? error.message : "Unknown error" }]
               },
               400
             );
@@ -3180,8 +3444,8 @@ var MastraServer = class extends MastraServer$1 {
   }
 };
 
-// ../../node_modules/.pnpm/hono-openapi@1.1.1_@hono+standard-validator@0.2.0_@standard-schema+spec@1.0.0_hono@4.10_dee62e986c04f5a510cb45dc6cf3f0e3/node_modules/hono-openapi/dist/index.js
-var uniqueSymbol = Symbol("openapi");
+// ../../node_modules/.pnpm/hono-openapi@1.1.1_@hono+standard-validator@0.2.1_@standard-schema+spec@1.1.0_hono@4.11_9131e3cfc9e6aabf665461e37801bbee/node_modules/hono-openapi/dist/index.js
+var uniqueSymbol = /* @__PURE__ */ Symbol("openapi");
 function describeRoute(spec) {
   const middleware2 = async (_c, next) => {
     await next();
@@ -3262,6 +3526,126 @@ async function restartAllActiveWorkflowRunsHandler(c) {
   }
 }
 
+// src/server/handlers/root.ts
+async function rootHandler(c) {
+  const baseUrl = new URL(c.req.url).origin;
+  return c.html(
+    /* html */
+    `
+    <!doctype html>
+    <html lang="en">
+      <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>Mastra API</title>
+        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/inter-ui/3.19.3/inter.min.css" />
+        <style>
+          body {
+            margin: 0;
+            padding: 0;
+            background-color: #0d0d0d;
+            color: #ffffff;
+            font-family:
+              'Inter',
+              -apple-system,
+              BlinkMacSystemFont,
+              system-ui,
+              sans-serif;
+            min-height: 100vh;
+            display: flex;
+            flex-direction: column;
+          }
+
+          main {
+            flex: 1;
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            justify-content: center;
+            padding: 2rem;
+            text-align: center;
+          }
+
+          h1 {
+            font-size: 4rem;
+            font-weight: 600;
+            margin: 0 0 1rem 0;
+            background: linear-gradient(to right, #fff, #ccc);
+            -webkit-background-clip: text;
+            -webkit-text-fill-color: transparent;
+            line-height: 1.2;
+          }
+
+          .subtitle {
+            color: #9ca3af;
+            font-size: 1.25rem;
+            max-width: 600px;
+            margin: 0 auto 3rem auto;
+            line-height: 1.6;
+          }
+
+          .link {
+            color: #ffffff;
+          }
+
+          .link:hover {
+            text-decoration: none;
+          }
+
+          .docs-link {
+            background-color: #1a1a1a;
+            padding: 1rem 2rem;
+            border-radius: 0.5rem;
+            display: flex;
+            align-items: center;
+            gap: 1rem;
+            font-family: monospace;
+            font-size: 1rem;
+            color: #ffffff;
+            text-decoration: none;
+            transition: background-color 0.2s;
+          }
+
+          .docs-link:hover {
+            background-color: #252525;
+          }
+
+          .arrow-icon {
+            transition: transform 0.2s;
+          }
+
+          .docs-link:hover .arrow-icon {
+            transform: translateX(4px);
+          }
+        </style>
+      </head>
+      <body>
+        <main>
+          <h1>Welcome to the Mastra API</h1>
+          <p class="subtitle">
+            Discover all available endpoints through Swagger UI. You can also define your own <a href="https://mastra.ai/docs/server-db/custom-api-routes" target="_blank" class="link">API routes</a>.
+          </p>
+          <a href="${baseUrl}/swagger-ui" target="_blank" class="docs-link">
+            Browse Swagger UI
+            <svg
+              class="arrow-icon"
+              width="20"
+              height="20"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+            >
+              <path d="M5 12h14M12 5l7 7-7 7" />
+            </svg>
+          </a>
+        </main>
+      </body>
+    </html>
+    `
+  );
+}
+
 // src/server/welcome.ts
 var html2 = `
 <!doctype html>
@@ -3370,6 +3754,18 @@ var html2 = `
 `;
 
 // src/server/index.ts
+var getStudioPath = () => {
+  if (process.env.MASTRA_STUDIO_PATH) {
+    return process.env.MASTRA_STUDIO_PATH;
+  }
+  let __dirname = ".";
+  if (import.meta.url) {
+    const __filename = fileURLToPath(import.meta.url);
+    __dirname = dirname(__filename);
+  }
+  const studioPath = process.env.MASTRA_STUDIO_PATH || join(__dirname, "studio");
+  return studioPath;
+};
 function getToolExports(tools) {
   try {
     return tools.reduce((acc, toolModule) => {
@@ -3405,7 +3801,13 @@ async function createHonoServer(mastra, options = {
       customRouteAuthConfig.set(routeKey, requiresAuth);
     }
   }
-  app.onError((err, c) => errorHandler(err, c, options.isDev));
+  const customOnError = server?.onError;
+  app.onError((err, c) => {
+    if (customOnError) {
+      return customOnError(err, c);
+    }
+    return errorHandler(err, c, options.isDev);
+  });
   const bodyLimitOptions = {
     maxSize: server?.bodySizeLimit ?? 4.5 * 1024 * 1024,
     // 4.5 MB,
@@ -3416,10 +3818,8 @@ async function createHonoServer(mastra, options = {
     mastra,
     tools: options.tools,
     taskStore: a2aTaskStore,
-    playground: options.playground,
-    isDev: options.isDev,
     bodyLimitOptions,
-    openapiPath: "/openapi.json",
+    openapiPath: options?.isDev || server?.build?.openAPIDocs ? "/openapi.json" : void 0,
     customRouteAuthConfig
   });
   honoServerAdapter.registerContextMiddleware();
@@ -3456,6 +3856,21 @@ async function createHonoServer(mastra, options = {
     }),
     healthHandler
   );
+  if (options?.isDev || server?.build?.swaggerUI) {
+    app.get(
+      "/api",
+      describeRoute({
+        description: "API Welcome Page",
+        tags: ["system"],
+        responses: {
+          200: {
+            description: "Success"
+          }
+        }
+      }),
+      rootHandler
+    );
+  }
   honoServerAdapter.registerAuthMiddleware();
   if (server?.middleware) {
     const normalizedMiddlewares = Array.isArray(server.middleware) ? server.middleware : [server.middleware];
@@ -3482,18 +3897,11 @@ async function createHonoServer(mastra, options = {
         middlewares.push(describeRoute(route.openapi));
       }
       const handler = "handler" in route ? route.handler : await route.createHandler({ mastra });
-      if (route.method === "GET") {
-        app.get(route.path, ...middlewares, handler);
-      } else if (route.method === "POST") {
-        app.post(route.path, ...middlewares, handler);
-      } else if (route.method === "PUT") {
-        app.put(route.path, ...middlewares, handler);
-      } else if (route.method === "DELETE") {
-        app.delete(route.path, ...middlewares, handler);
-      } else if (route.method === "PATCH") {
-        app.patch(route.path, ...middlewares, handler);
-      } else if (route.method === "ALL") {
-        app.all(route.path, ...middlewares, handler);
+      const allHandlers = [...middlewares, handler];
+      if (route.method === "ALL") {
+        app.all(route.path, allHandlers[0], ...allHandlers.slice(1));
+      } else {
+        app.on(route.method, route.path, allHandlers[0], ...allHandlers.slice(1));
       }
     }
   }
@@ -3502,6 +3910,12 @@ async function createHonoServer(mastra, options = {
   }
   await honoServerAdapter.registerRoutes();
   if (options?.isDev || server?.build?.swaggerUI) {
+    if (!options?.isDev && server?.build?.swaggerUI && !server?.build?.openAPIDocs) {
+      const logger2 = mastra.getLogger();
+      logger2.warn(
+        "Swagger UI is enabled but OpenAPI documentation is disabled. The Swagger UI will not function properly without the OpenAPI endpoint. Please enable openAPIDocs in your server.build configuration:\n  server: { build: { swaggerUI: true, openAPIDocs: true } }"
+      );
+    }
     app.get(
       "/swagger-ui",
       describeRoute({
@@ -3519,23 +3933,25 @@ async function createHonoServer(mastra, options = {
       restartAllActiveWorkflowRunsHandler
     );
   }
-  if (options?.playground) {
+  const serverOptions = mastra.getServer();
+  const studioBasePath = normalizeStudioBase(serverOptions?.studioBase ?? "/");
+  if (options?.studio) {
     app.get(
-      "/refresh-events",
+      `${studioBasePath}/refresh-events`,
       describeRoute({
         hide: true
       }),
       handleClientsRefresh
     );
     app.post(
-      "/__refresh",
+      `${studioBasePath}/__refresh`,
       describeRoute({
         hide: true
       }),
       handleTriggerClientsRefresh
     );
     app.get(
-      "/__hot-reload-status",
+      `${studioBasePath}/__hot-reload-status`,
       describeRoute({
         hide: true
       }),
@@ -3546,48 +3962,66 @@ async function createHonoServer(mastra, options = {
         });
       }
     );
-    app.use("/assets/*", async (c, next) => {
-      const path = c.req.path;
-      if (path.endsWith(".js")) {
-        c.header("Content-Type", "application/javascript");
-      } else if (path.endsWith(".css")) {
-        c.header("Content-Type", "text/css");
-      }
-      await next();
-    });
+    const studioPath = getStudioPath();
     app.use(
-      "/assets/*",
+      `${studioBasePath}/assets/*`,
       serveStatic({
-        root: "./playground/assets"
+        root: join(studioPath, "assets"),
+        rewriteRequestPath: (path) => {
+          let rewritten = path;
+          if (studioBasePath && rewritten.startsWith(studioBasePath)) {
+            rewritten = rewritten.slice(studioBasePath.length);
+          }
+          if (rewritten.startsWith("/assets")) {
+            rewritten = rewritten.slice("/assets".length);
+          }
+          return rewritten;
+        }
       })
     );
   }
   app.get("*", async (c, next) => {
-    if (c.req.path.startsWith("/api/") || c.req.path.startsWith("/swagger-ui") || c.req.path.startsWith("/openapi.json")) {
+    const requestPath = c.req.path;
+    if (requestPath === "/api" || requestPath.startsWith("/api/") || requestPath.startsWith("/swagger-ui") || requestPath.startsWith("/openapi.json")) {
       return await next();
     }
-    const path = c.req.path;
-    if (path.includes(".") && !path.endsWith(".html")) {
+    if (requestPath.includes(".") && !requestPath.endsWith(".html")) {
       return await next();
     }
-    if (options?.playground) {
-      let indexHtml = await readFile(join(process.cwd(), "./playground/index.html"), "utf-8");
-      const serverOptions = mastra.getServer();
+    const isStudioRoute = studioBasePath === "" || requestPath === studioBasePath || requestPath.startsWith(`${studioBasePath}/`);
+    if (options?.studio && isStudioRoute) {
+      const studioPath = getStudioPath();
+      let indexHtml = await readFile(join(studioPath, "index.html"), "utf-8");
       const port = serverOptions?.port ?? (Number(process.env.PORT) || 4111);
       const hideCloudCta = process.env.MASTRA_HIDE_CLOUD_CTA === "true";
       const host = serverOptions?.host ?? "localhost";
+      const key = serverOptions?.https?.key ?? (process.env.MASTRA_HTTPS_KEY ? Buffer.from(process.env.MASTRA_HTTPS_KEY, "base64") : void 0);
+      const cert = serverOptions?.https?.cert ?? (process.env.MASTRA_HTTPS_CERT ? Buffer.from(process.env.MASTRA_HTTPS_CERT, "base64") : void 0);
+      const protocol = key && cert ? "https" : "http";
+      const cloudApiEndpoint = process.env.MASTRA_CLOUD_API_ENDPOINT || "";
       indexHtml = indexHtml.replace(`'%%MASTRA_SERVER_HOST%%'`, `'${host}'`);
       indexHtml = indexHtml.replace(`'%%MASTRA_SERVER_PORT%%'`, `'${port}'`);
       indexHtml = indexHtml.replace(`'%%MASTRA_HIDE_CLOUD_CTA%%'`, `'${hideCloudCta}'`);
+      indexHtml = indexHtml.replace(`'%%MASTRA_SERVER_PROTOCOL%%'`, `'${protocol}'`);
+      indexHtml = indexHtml.replace(`'%%MASTRA_CLOUD_API_ENDPOINT%%'`, `'${cloudApiEndpoint}'`);
+      indexHtml = indexHtml.replaceAll("%%MASTRA_STUDIO_BASE_PATH%%", studioBasePath);
       return c.newResponse(indexHtml, 200, { "Content-Type": "text/html" });
     }
     return c.newResponse(html2, 200, { "Content-Type": "text/html" });
   });
-  if (options?.playground) {
+  if (options?.studio) {
+    const studioRootPath = getStudioPath();
+    const studioPath = studioBasePath ? `${studioBasePath}/*` : "*";
     app.use(
-      "*",
+      studioPath,
       serveStatic({
-        root: "./playground"
+        root: studioRootPath,
+        rewriteRequestPath: (path) => {
+          if (studioBasePath && path.startsWith(studioBasePath)) {
+            return path.slice(studioBasePath.length);
+          }
+          return path;
+        }
       })
     );
   }
@@ -3617,9 +4051,10 @@ async function createNodeServer(mastra, options = { tools: {} }) {
     },
     () => {
       const logger2 = mastra.getLogger();
-      logger2.info(` Mastra API running on port ${protocol}://${host}:${port}/api`);
-      if (options?.playground) {
-        const studioUrl = `${protocol}://${host}:${port}`;
+      logger2.info(` Mastra API running on ${protocol}://${host}:${port}/api`);
+      if (options?.studio) {
+        const studioBasePath = normalizeStudioBase(serverOptions?.studioBase ?? "/");
+        const studioUrl = `${protocol}://${host}:${port}${studioBasePath}`;
         logger2.info(`\u{1F468}\u200D\u{1F4BB} Studio available at ${studioUrl}`);
       }
       if (process.send) {