stitchkit 0.1.0 → 0.3.0

package/dist/index-dpj1jcys.js

@@ -0,0 +1,677 @@
+import {
+  isWithinDir
+} from "./index-q6ja2qwq.js";
+import {
+  normalizeError,
+  validateHandlerOutput
+} from "./index-0t460v7k.js";
+import {
+  AppError,
+  badRequest
+} from "./index-kckky6zw.js";
+import {
+  extractIp,
+  getClientInfo,
+  parseQueryParams,
+  resolveSocketIp,
+  resolveTraceId
+} from "./index-mwmpw6j1.js";
+import {
+  isUnsafeKey,
+  safeJsonParse
+} from "./index-kzfs85xp.js";
+
+// src/server/multipart.ts
+var DEFAULT_MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
+async function readBodyCapped(req, maxBytes) {
+  const reader = req.body?.getReader();
+  if (!reader)
+    return new Uint8Array(0);
+  const chunks = [];
+  let total = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done)
+        break;
+      total += value.length;
+      if (total > maxBytes) {
+        await reader.cancel();
+        badRequest(`Upload exceeds the ${Math.round(maxBytes / 1024 / 1024)} MB limit`);
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const buffer = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    buffer.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return buffer;
+}
+async function parseMultipart(req, fileField, fieldsSchema, maxBytes = DEFAULT_MAX_UPLOAD_BYTES) {
+  const body = await readBodyCapped(req, maxBytes);
+  const contentType = req.headers.get("content-type") ?? "";
+  const formData = await new Response(body, {
+    headers: { "content-type": contentType }
+  }).formData();
+  const file = formData.get(fileField);
+  if (!file || !(file instanceof File)) {
+    badRequest(`Missing file field: ${fileField}`);
+  }
+  const fields = {};
+  for (const [key, value] of formData.entries()) {
+    if (key === fileField)
+      continue;
+    if (isUnsafeKey(key))
+      continue;
+    if (typeof value === "string") {
+      try {
+        fields[key] = safeJsonParse(value);
+      } catch {
+        fields[key] = value;
+      }
+    }
+  }
+  return { file, fields: fieldsSchema ? fieldsSchema.parse(fields) : fields };
+}
+
+// src/server/middleware/cors.ts
+function assertCorsConfig(config) {
+  if (config.credentials && (config.origin === undefined || config.origin === "*")) {
+    throw new Error("[stitchkit] cors: `credentials: true` cannot be combined with a wildcard origin. " + "Set `origin` to an explicit string or list.");
+  }
+}
+function resolveOrigin(config, requestOrigin) {
+  if (config.origin === undefined || config.origin === "*") {
+    return "*";
+  }
+  if (Array.isArray(config.origin)) {
+    if (!requestOrigin)
+      return;
+    const lower = requestOrigin.toLowerCase();
+    return config.origin.some((o) => o.toLowerCase() === lower) ? requestOrigin : undefined;
+  }
+  return config.origin;
+}
+function corsHeaders(config, requestOrigin) {
+  const allowOrigin = resolveOrigin(config, requestOrigin);
+  const headers = {
+    "Access-Control-Allow-Methods": config.methods ?? "GET, POST, PUT, PATCH, DELETE, OPTIONS",
+    "Access-Control-Allow-Headers": config.headers ?? "Content-Type, Authorization, X-Trace-Id"
+  };
+  if (allowOrigin !== undefined) {
+    headers["Access-Control-Allow-Origin"] = allowOrigin;
+    if (config.credentials) {
+      headers["Access-Control-Allow-Credentials"] = "true";
+    }
+  }
+  if (Array.isArray(config.origin)) {
+    headers.Vary = "Origin";
+  }
+  return headers;
+}
+function corsPreflightResponse(config, req) {
+  return new Response(null, {
+    status: 204,
+    headers: corsHeaders(config, req.headers.get("origin"))
+  });
+}
+
+// src/server/router.ts
+import { readFile, stat } from "node:fs/promises";
+import { extname, resolve } from "node:path";
+function joinPath(...parts) {
+  const joined = parts.filter(Boolean).map((part) => part.replace(/^\/+|\/+$/g, "")).filter(Boolean).join("/");
+  return `/${joined}`;
+}
+function matchSegments(patternSegments, requestSegments) {
+  if (patternSegments.length !== requestSegments.length)
+    return null;
+  const params = {};
+  for (const [i, pattern] of patternSegments.entries()) {
+    const actual = requestSegments[i];
+    if (actual === undefined)
+      return null;
+    if (pattern.startsWith(":")) {
+      params[pattern.slice(1)] = decodeURIComponent(actual);
+    } else if (pattern !== actual) {
+      return null;
+    }
+  }
+  return params;
+}
+function buildRouteMap(groups) {
+  const map = new Map;
+  for (const { prefix, service, hooks } of groups) {
+    for (const [, method] of Object.entries(service.methods)) {
+      if (method.expose && !method.expose.includes("HTTP"))
+        continue;
+      const servicePath = joinPath("/", service.prefix, method.path === "/" ? "" : method.path);
+      const fullPath = prefix ? joinPath(prefix, servicePath) : servicePath;
+      const segments = fullPath.split("/").filter(Boolean);
+      const entries = map.get(method.method) ?? [];
+      entries.push({ method, service, pattern: fullPath, segments, groupHooks: hooks });
+      map.set(method.method, entries);
+    }
+  }
+  for (const [, entries] of map) {
+    entries.sort((a, b) => {
+      const len = Math.min(a.segments.length, b.segments.length);
+      for (let i = 0;i < len; i++) {
+        const aIsParam = a.segments[i]?.startsWith(":");
+        const bIsParam = b.segments[i]?.startsWith(":");
+        if (aIsParam !== bIsParam)
+          return aIsParam ? 1 : -1;
+      }
+      return a.segments.length - b.segments.length;
+    });
+  }
+  return map;
+}
+function matchRoute(routeMap, httpMethod, pathname) {
+  const entries = routeMap.get(httpMethod);
+  if (!entries)
+    return null;
+  const requestSegments = pathname.split("/").filter(Boolean);
+  for (const entry of entries) {
+    const pathParams = matchSegments(entry.segments, requestSegments);
+    if (pathParams) {
+      return {
+        method: entry.method,
+        service: entry.service,
+        pathParams,
+        groupHooks: entry.groupHooks
+      };
+    }
+  }
+  return null;
+}
+function allowedMethods(routeMap, pathname) {
+  const requestSegments = pathname.split("/").filter(Boolean);
+  const methods = [];
+  for (const [method, entries] of routeMap) {
+    for (const entry of entries) {
+      if (matchSegments(entry.segments, requestSegments)) {
+        methods.push(method);
+        break;
+      }
+    }
+  }
+  return methods;
+}
+function validateRoutes(routeMap) {
+  for (const [method, entries] of routeMap) {
+    const seen = new Map;
+    for (const entry of entries) {
+      const normalized = entry.segments.map((s) => s.startsWith(":") ? ":param" : s).join("/");
+      const key = `${method} /${normalized}`;
+      const existing = seen.get(key);
+      if (existing) {
+        throw new Error(`Duplicate route: ${method} ${entry.pattern} conflicts with ${existing}`);
+      }
+      seen.set(key, entry.pattern);
+    }
+  }
+}
+function matchRawRoute(rawRoutes, httpMethod, pathname) {
+  for (const route of rawRoutes) {
+    if (route.method !== "ALL" && route.method !== httpMethod)
+      continue;
+    if (route.path.endsWith("/*")) {
+      const prefix = route.path.slice(0, -2);
+      if (pathname === prefix || pathname.startsWith(`${prefix}/`)) {
+        return { route, params: {} };
+      }
+      continue;
+    }
+    if (route.path.includes("/:")) {
+      const routeSegs = route.path.split("/").filter(Boolean);
+      const pathSegs = pathname.split("/").filter(Boolean);
+      const params = matchSegments(routeSegs, pathSegs);
+      if (params)
+        return { route, params };
+      continue;
+    }
+    if (route.path === pathname)
+      return { route, params: {} };
+  }
+  return null;
+}
+var STATIC_MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".woff2": "font/woff2",
+  ".txt": "text/plain; charset=utf-8"
+};
+function staticRoute(prefix, dir) {
+  const cleanPrefix = prefix.replace(/\/+$/, "");
+  const root = resolve(dir.replace(/\/+$/, ""));
+  return {
+    method: "GET",
+    path: `${cleanPrefix}/*`,
+    handler: async (req) => {
+      const pathname = new URL(req.url).pathname;
+      let rel;
+      try {
+        rel = decodeURIComponent(pathname.slice(cleanPrefix.length)).replace(/^\/+/, "");
+      } catch {
+        return new Response("Bad request", { status: 400 });
+      }
+      const target = resolve(root, rel);
+      if (!isWithinDir(root, target)) {
+        return new Response("Forbidden", { status: 403 });
+      }
+      const info = await stat(target).catch(() => null);
+      if (!info?.isFile()) {
+        return new Response("Not found", { status: 404 });
+      }
+      const body = await readFile(target);
+      return new Response(body, {
+        headers: {
+          "Content-Type": STATIC_MIME[extname(target).toLowerCase()] ?? "application/octet-stream",
+          "X-Content-Type-Options": "nosniff"
+        }
+      });
+    }
+  };
+}
+
+// src/server/context.ts
+var RESERVED_KEYS = new Set([
+  "params",
+  "input",
+  "source",
+  "req",
+  "url",
+  "headers",
+  "traceId",
+  "spanId",
+  "ipAddress",
+  "userAgent"
+]);
+async function readJsonBody(req) {
+  const text = await req.text();
+  if (text.trim() === "")
+    return {};
+  if (!req.headers.get("content-type")?.includes("application/json")) {
+    badRequest("Request body must be application/json");
+  }
+  try {
+    return safeJsonParse(text);
+  } catch {
+    badRequest("Invalid JSON body");
+  }
+}
+async function buildContext(req, url, method, pathParams, traceId, clientIp) {
+  const parsedParams = method.paramsSchema ? method.paramsSchema.parse(pathParams) : undefined;
+  let parsedInput;
+  let file;
+  if (method.multipart) {
+    const multipart = await parseMultipart(req, method.multipart, method.inputSchema);
+    parsedInput = multipart.fields;
+    file = multipart.file;
+  } else if (method.inputSchema) {
+    if (req.method === "GET") {
+      parsedInput = method.inputSchema.parse(parseQueryParams(url));
+    } else if (req.method === "DELETE") {
+      const ct = req.headers.get("content-type");
+      if (ct?.includes("application/json")) {
+        parsedInput = method.inputSchema.parse(await readJsonBody(req));
+      } else {
+        parsedInput = method.inputSchema.parse(parseQueryParams(url));
+      }
+    } else {
+      parsedInput = method.inputSchema.parse(await readJsonBody(req));
+    }
+  }
+  const safePathParams = {};
+  for (const [k, v] of Object.entries(pathParams)) {
+    if (!RESERVED_KEYS.has(k) && !isUnsafeKey(k))
+      safePathParams[k] = v;
+  }
+  return {
+    params: parsedParams,
+    input: parsedInput,
+    ...file && { file },
+    source: "http",
+    req,
+    url,
+    headers: req.headers,
+    ...safePathParams,
+    traceId,
+    ...getClientInfo(req, clientIp)
+  };
+}
+function buildErrorContext(req, url, traceId, clientIp) {
+  return {
+    params: undefined,
+    input: undefined,
+    source: "http",
+    req,
+    url,
+    headers: req.headers,
+    traceId,
+    ...getClientInfo(req, clientIp)
+  };
+}
+
+// src/server/logger.ts
+var c = {
+  reset: "\x1B[0m",
+  dim: "\x1B[2m",
+  red: "\x1B[31m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  blue: "\x1B[34m",
+  magenta: "\x1B[35m",
+  cyan: "\x1B[36m",
+  gray: "\x1B[90m"
+};
+var METHOD_COLOR = {
+  GET: c.green,
+  POST: c.yellow,
+  PUT: c.blue,
+  PATCH: c.cyan,
+  DELETE: c.red,
+  OPTIONS: c.gray
+};
+var isProd = false;
+function timestamp() {
+  const now = new Date;
+  const t = now.toLocaleTimeString("en-US", {
+    hour12: false,
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit"
+  });
+  return `${t}.${now.getMilliseconds().toString().padStart(3, "0")}`;
+}
+function elapsedMs(startTime) {
+  return performance.now() - startTime;
+}
+function safePath(pathname) {
+  return pathname.replace(/[-]/g, "");
+}
+function levelForStatus(status) {
+  if (status >= 500)
+    return "error";
+  if (status >= 400)
+    return "warn";
+  return "info";
+}
+function buildLogFields(method, path, status, durationMs, traceId) {
+  return { traceId, method, path, status, durationMs };
+}
+function formatMs(ms) {
+  if (ms >= 1000)
+    return `${(ms / 1000).toFixed(2)}s`;
+  if (ms >= 1)
+    return `${Math.round(ms)}ms`;
+  return `${Math.round(ms * 1000)}µs`;
+}
+function durationColor(ms) {
+  if (ms >= 1000)
+    return c.red;
+  if (ms > 300)
+    return c.yellow;
+  return c.green;
+}
+function statusColor(status) {
+  if (status >= 500)
+    return c.red;
+  if (status >= 400)
+    return c.yellow;
+  if (status >= 300)
+    return c.cyan;
+  return c.green;
+}
+function ipLabel(ip) {
+  if (!ip || ip === "::1" || ip === "127.0.0.1")
+    return `${c.magenta}local${c.reset}`;
+  return `${c.dim}${ip}${c.reset}`;
+}
+var SKIP_PREFIXES = ["/_bun/", "/_bundle", "/favicon"];
+function shouldLog(pathname, method) {
+  if (method === "OPTIONS")
+    return false;
+  return !SKIP_PREFIXES.some((prefix) => pathname.startsWith(prefix));
+}
+function logIncoming(req, pathname, traceId, ipAddress) {
+  const log = { traceId, startTime: performance.now() };
+  if (!isProd) {
+    const mc = METHOD_COLOR[req.method] ?? c.dim;
+    console.log(`${c.gray}[${timestamp()}]${c.reset} ${mc}${req.method}${c.reset} ${c.dim}${traceId}${c.reset} ${c.cyan}→${c.reset} ${safePath(pathname)} ${ipLabel(ipAddress ?? "")}`);
+  }
+  return log;
+}
+function logOutgoing(req, pathname, status, log, ipAddress) {
+  const ms = elapsedMs(log.startTime);
+  if (isProd) {
+    console.log(JSON.stringify({
+      ts: new Date().toISOString(),
+      level: levelForStatus(status),
+      msg: `${req.method} ${pathname} ${status}`,
+      ...buildLogFields(req.method, pathname, status, Math.round(ms), log.traceId),
+      ip: ipAddress
+    }));
+    return;
+  }
+  const mc = METHOD_COLOR[req.method] ?? c.dim;
+  console.log(`${c.gray}[${timestamp()}]${c.reset} ${mc}${req.method}${c.reset} ${c.dim}${log.traceId}${c.reset} ${c.cyan}←${c.reset} ${safePath(pathname)} ${statusColor(status)}${status}${c.reset} ${durationColor(ms)}${formatMs(ms)}${c.reset} ${ipLabel(ipAddress ?? "")}`);
+}
+
+// src/server/create.ts
+function createHandler(config) {
+  const { cors, hooks, logging = false, trustProxy = false } = config;
+  if (cors)
+    assertCorsConfig(cors);
+  const customLogger = typeof logging === "object" ? logging : null;
+  const useDefaultLog = logging === true;
+  const resolveId = config.traceId ?? resolveTraceId;
+  const routeMap = buildRouteMap(normalizeGroups(config));
+  validateRoutes(routeMap);
+  async function dispatch(req, url, traceId, server, clientIp) {
+    const shouldLogRequest = logging && shouldLog(url.pathname, req.method);
+    const ipAddress = extractIp(req, clientIp) || undefined;
+    let reqLog;
+    if (shouldLogRequest && useDefaultLog) {
+      reqLog = logIncoming(req, url.pathname, traceId, ipAddress);
+    }
+    if (shouldLogRequest && customLogger) {
+      customLogger.debug(`${req.method} ${url.pathname}`, {
+        traceId,
+        method: req.method,
+        path: url.pathname,
+        ip: ipAddress
+      });
+      reqLog = { traceId, startTime: performance.now() };
+    }
+    const logDone = (status) => {
+      if (!reqLog)
+        return;
+      if (useDefaultLog)
+        logOutgoing(req, url.pathname, status, reqLog, ipAddress);
+      if (customLogger) {
+        const durationMs = Math.round(elapsedMs(reqLog.startTime));
+        const level = levelForStatus(status);
+        customLogger[level](`${req.method} ${url.pathname} ${status} ${durationMs}ms`, buildLogFields(req.method, url.pathname, status, durationMs, reqLog.traceId));
+      }
+    };
+    const respondError = async (err, errCtx, endpoint) => {
+      if (hooks?.onError) {
+        try {
+          const response = await hooks.onError(errCtx ?? buildErrorContext(req, url, traceId, clientIp), err, endpoint);
+          if (response instanceof Response) {
+            const withCors = applyCors(response, cors, req);
+            logDone(withCors.status);
+            return withCors;
+          }
+        } catch {}
+      }
+      const appErr = normalizeError(err);
+      logDone(appErr.status);
+      return json(appErr.toJSON(), appErr.status, cors, req);
+    };
+    if (cors && req.method === "OPTIONS") {
+      const res = corsPreflightResponse(cors, req);
+      logDone(204);
+      return res;
+    }
+    if (hooks?.onRequest) {
+      const earlyResponse = await hooks.onRequest(req);
+      if (earlyResponse instanceof Response) {
+        logDone(earlyResponse.status);
+        return earlyResponse;
+      }
+    }
+    if (config.rawRoutes) {
+      const rawMatch = matchRawRoute(config.rawRoutes, req.method, url.pathname);
+      if (rawMatch) {
+        try {
+          const res = await rawMatch.route.handler(req, {
+            params: rawMatch.params,
+            server,
+            ipAddress
+          });
+          const withCors = applyCors(res, cors, req);
+          logDone(withCors.status);
+          return withCors;
+        } catch (err) {
+          return respondError(err);
+        }
+      }
+    }
+    const match = matchRoute(routeMap, req.method, url.pathname);
+    if (!match) {
+      const allow = allowedMethods(routeMap, url.pathname);
+      if (allow.length > 0) {
+        const res = await respondError(new AppError("METHOD_NOT_ALLOWED", `Method ${req.method} not allowed`, 405));
+        res.headers.set("Allow", allow.join(", "));
+        return res;
+      }
+      return respondError(new AppError("NOT_FOUND", "Not found", 404));
+    }
+    const { method, pathParams, groupHooks } = match;
+    let ctx;
+    try {
+      ctx = await buildContext(req, url, method, pathParams, traceId, clientIp);
+      if (hooks?.beforeHandle) {
+        await hooks.beforeHandle(ctx, method);
+      }
+      if (groupHooks?.beforeHandle) {
+        await groupHooks.beforeHandle(ctx, method);
+      }
+      let result = await method.handler(ctx);
+      if (groupHooks?.afterHandle) {
+        const transformed = await groupHooks.afterHandle(ctx, result, method);
+        if (transformed !== undefined)
+          result = transformed;
+      }
+      if (hooks?.afterHandle) {
+        const transformed = await hooks.afterHandle(ctx, result, method);
+        if (transformed !== undefined)
+          result = transformed;
+      }
+      if (method.outputSchema) {
+        const checked = validateHandlerOutput(method.outputSchema, result);
+        if (!checked.ok) {
+          throw new AppError("INTERNAL_SERVER_ERROR", checked.message, 500);
+        }
+        result = checked.data;
+      }
+      if (result === undefined || result === null) {
+        logDone(204);
+        return new Response(null, { status: 204, headers: corsHeaders2(cors, req) });
+      }
+      logDone(200);
+      return json(result, 200, cors, req);
+    } catch (err) {
+      return respondError(err, ctx, method);
+    }
+  }
+  return async (req, server) => {
+    const url = new URL(req.url, "http://localhost");
+    const traceId = resolveId(req);
+    const clientIp = {
+      trustProxy,
+      socketIp: resolveSocketIp(req, server)
+    };
+    const response = await dispatch(req, url, traceId, server, clientIp);
+    try {
+      response.headers.set("x-request-id", traceId);
+    } catch {}
+    return response;
+  };
+}
+function createServer(config) {
+  const { routes, websocket, development, bun: bunExtra, port = 3000, hostname } = config;
+  const fetch = createHandler(config);
+  return websocket ? Bun.serve({
+    ...bunExtra,
+    ...routes && { routes },
+    ...development && { development },
+    port,
+    hostname,
+    websocket,
+    fetch
+  }) : Bun.serve({
+    ...bunExtra,
+    ...development && { development },
+    port,
+    hostname,
+    fetch
+  });
+}
+function normalizeGroups(config) {
+  const result = [];
+  if (config.services) {
+    for (const service of config.services) {
+      result.push({ prefix: "", service });
+    }
+  }
+  if (config.groups) {
+    for (const group of config.groups) {
+      for (const service of group.services) {
+        result.push({ prefix: group.pathPrefix ?? "", service, hooks: group.hooks });
+      }
+    }
+  }
+  return result;
+}
+function corsHeaders2(cors, req) {
+  if (!cors)
+    return {};
+  return corsHeaders(cors, req.headers.get("origin"));
+}
+function applyCors(res, cors, req) {
+  const extra = corsHeaders2(cors, req);
+  if (Object.keys(extra).length === 0)
+    return res;
+  const headers = new Headers(res.headers);
+  for (const [key, value] of Object.entries(extra))
+    headers.set(key, value);
+  return new Response(res.body, {
+    status: res.status,
+    statusText: res.statusText,
+    headers
+  });
+}
+function json(data, status, cors, req) {
+  return Response.json(data, { status, headers: corsHeaders2(cors, req) });
+}
+
+export { parseMultipart, corsHeaders, corsPreflightResponse, staticRoute, createHandler, createServer };

package/dist/{index-7wfkbvss.js → index-kckky6zw.js}

@@ -3,11 +3,15 @@ var ALL_TRANSPORTS = ["HTTP", "MCP", "AGENT"];
 function defineContract(meta, endpoints) {
   const toolTransports = new Map;
   for (const [key, ep] of Object.entries(endpoints)) {
+    if (ep.desc.trim() === "") {
+      throw new Error(`Contract "${meta.prefix}": endpoint "${key}" has an empty desc`);
+    }
     if (!("toolName" in ep) || !ep.toolName)
       continue;
     const transports = new Set(ep.expose ? ep.expose.filter((t) => t !== "HTTP") : ["MCP", "AGENT"]);
-    if (transports.size === 0)
-      continue;
+    if (transports.size === 0) {
+      throw new Error(`Contract "${meta.prefix}": endpoint "${key}" sets toolName "${ep.toolName}" but is not exposed on any tool transport (MCP / AGENT)`);
+    }
     const existing = toolTransports.get(ep.toolName);
     if (existing) {
       for (const t of transports) {

package/dist/index-kzfs85xp.js

@@ -0,0 +1,9 @@
+// src/internal/safe-json.ts
+function isUnsafeKey(key) {
+  return key === "__proto__";
+}
+function safeJsonParse(text) {
+  return JSON.parse(text, (key, value) => isUnsafeKey(key) ? undefined : value);
+}
+
+export { isUnsafeKey, safeJsonParse };