@decocms/runtime 1.0.0-alpha.5 → 1.0.0

package/src/asset-server/index.ts

@@ -1,44 +1,227 @@
-import { serveStatic } from "hono/bun";
-import { Hono } from "hono";
 import { devServerProxy } from "./dev-server-proxy";
-import { Handler } from "hono/types";
+import { resolve, dirname } from "path";
 
-interface AssetServerConfig {
-  env: "development" | "production" | "test";
-  localDevProxyUrl?: string | URL;
-  assetsDirectory?: string;
+export interface AssetServerConfig {
+  /**
+   * Environment mode. Determines whether to proxy to dev server or serve static files.
+   * @default process.env.NODE_ENV || "development"
+   */
+  env?: "development" | "production" | "test";
+
+  /**
+   * URL of the Vite dev server for development mode.
+   * @default "http://localhost:4000"
+   */
+  devServerUrl?: string | URL;
+
+  /**
+   * Directory containing the built client assets.
+   * For production bundles, use `resolveClientDir()` to get the correct path.
+   * @default "./dist/client"
+   */
+  clientDir?: string;
+
+  /**
+   * Function to check if a path should be handled by the API server.
+   * Return true for API routes, false for static files.
+   * If not provided, defaults to serving everything as static.
+   */
+  isServerPath?: (path: string) => boolean;
+}
+
+const DEFAULT_DEV_SERVER_URL = "http://localhost:4000";
+const DEFAULT_CLIENT_DIR = "./dist/client";
+
+/**
+ * Check if a resolved file path is safely within the allowed base directory.
+ * Prevents path traversal attacks (e.g., /../../../etc/passwd).
+ *
+ * @param filePath - The resolved absolute file path
+ * @param baseDir - The base directory that files must be within
+ * @returns true if the path is safe, false if it's a traversal attempt
+ *
+ * @example
+ * ```ts
+ * isPathWithinDirectory("/app/client/style.css", "/app/client") // true
+ * isPathWithinDirectory("/etc/passwd", "/app/client") // false
+ * ```
+ */
+export function isPathWithinDirectory(
+  filePath: string,
+  baseDir: string,
+): boolean {
+  const resolvedBase = resolve(baseDir);
+  const resolvedPath = resolve(filePath);
+  return (
+    resolvedPath === resolvedBase || resolvedPath.startsWith(resolvedBase + "/")
+  );
 }
 
-const DEFAULT_LOCAL_DEV_PROXY_URL = "http://localhost:4000";
-const DEFAULT_ASSETS_DIRECTORY = "./dist/client";
+export interface ResolveAssetPathOptions {
+  /** The decoded URL pathname (e.g., "/assets/style.css") */
+  requestPath: string;
+  /** The base directory containing static files */
+  clientDir: string;
+}
+
+/**
+ * Resolve a URL pathname to a file path, with path traversal protection.
+ * Returns null if the path is a traversal attempt.
+ *
+ * @returns File path, or null if unsafe
+ *
+ * @example
+ * ```ts
+ * resolveAssetPathWithTraversalCheck({ requestPath: "/style.css", clientDir: "/app/client" })
+ * // "/app/client/style.css"
+ *
+ * resolveAssetPathWithTraversalCheck({ requestPath: "/../../../etc/passwd", clientDir: "/app/client" })
+ * // null (blocked)
+ * ```
+ */
+export function resolveAssetPathWithTraversalCheck({
+  requestPath,
+  clientDir,
+}: ResolveAssetPathOptions): string | null {
+  const relativePath = requestPath.startsWith("/")
+    ? requestPath.slice(1)
+    : requestPath;
+  const filePath = resolve(clientDir, relativePath);
+
+  // Security: block path traversal attempts
+  if (!isPathWithinDirectory(filePath, clientDir)) {
+    return null;
+  }
+
+  return filePath;
+}
 
-interface HonoApp {
-  use: (path: string, handler: Handler) => void;
-  get: (path: string, handler: Handler) => void;
+/**
+ * Resolve the client directory path relative to the running script.
+ * Use this for production bundles where the script location differs from CWD.
+ *
+ * @param importMetaUrl - Pass `import.meta.url` from the calling module
+ * @param relativePath - Path relative to the script (default: "../client")
+ * @returns Absolute path to the client directory
+ *
+ * @example
+ * ```ts
+ * const clientDir = resolveClientDir(import.meta.url, "../client");
+ * ```
+ */
+export function resolveClientDir(
+  importMetaUrl: string,
+  relativePath = "../client",
+): string {
+  const scriptUrl = new URL(importMetaUrl);
+  const scriptDir = dirname(scriptUrl.pathname);
+  return resolve(scriptDir, relativePath);
 }
 
-export const applyAssetServerRoutes = (
-  app: HonoApp,
-  config: AssetServerConfig,
-) => {
-  const environment = config.env;
-  const localDevProxyUrl =
-    config.localDevProxyUrl ?? DEFAULT_LOCAL_DEV_PROXY_URL;
-  const assetsDirectory = config.assetsDirectory ?? DEFAULT_ASSETS_DIRECTORY;
-
-  if (environment === "development") {
-    app.use("*", devServerProxy(localDevProxyUrl));
-  } else if (environment === "production") {
-    app.use("/assets/*", serveStatic({ root: assetsDirectory }));
-    app.get("*", serveStatic({ path: `${assetsDirectory}/index.html` }));
+/**
+ * TODO(@camudo): make "modes" so we can for example try to serve the asset then fallback to api on miss
+ * or try to serve the api call then fallback to asset or index.html on 404
+ */
+
+/**
+ * Create an asset handler that works with Bun.serve.
+ *
+ * In development: Proxies requests to Vite dev server
+ * In production: Serves static files with SPA fallback
+ *
+ * @example
+ * ```ts
+ * const handleAssets = createAssetHandler({
+ *   env: process.env.NODE_ENV as "development" | "production",
+ *   clientDir: resolveClientDir(import.meta.url),
+ *   isServerPath: (path) => path.startsWith("/api/") || path.startsWith("/mcp/"),
+ * });
+ *
+ * Bun.serve({
+ *   fetch: async (request) => {
+ *     return await handleAssets(request) ?? app.fetch(request);
+ *   },
+ * });
+ * ```
+ */
+export function createAssetHandler(config: AssetServerConfig = {}) {
+  const {
+    env = (process.env.NODE_ENV as "development" | "production" | "test") ||
+      "development",
+    devServerUrl = DEFAULT_DEV_SERVER_URL,
+    clientDir = DEFAULT_CLIENT_DIR,
+    isServerPath = () => false,
+  } = config;
+
+  // Development: Create a proxy handler
+  if (env === "development") {
+    const proxyHandler = devServerProxy(devServerUrl);
+
+    return async function handleAssets(
+      request: Request,
+    ): Promise<Response | null> {
+      // In dev, proxy everything except server paths
+      const url = new URL(request.url);
+      if (isServerPath(url.pathname)) {
+        return null;
+      }
+
+      // Create a minimal Hono context for the proxy
+      const fakeContext = {
+        req: { raw: request, url: request.url },
+      };
+      return proxyHandler(fakeContext as any);
+    };
   }
-};
 
-export const createAssetServer = (config: AssetServerConfig) => {
-  const app = new Hono();
-  applyAssetServerRoutes(app, config);
-  return app;
-};
+  // Production: Serve static files
+  return async function handleAssets(
+    request: Request,
+  ): Promise<Response | null> {
+    // Only handle GET requests
+    if (request.method !== "GET") {
+      return null;
+    }
+
+    const requestUrl = new URL(request.url);
 
-export const createAssetServerFetcher = (config: AssetServerConfig) =>
-  createAssetServer(config).fetch;
+    // Decode the pathname to handle URL-encoded characters (e.g., %20 -> space)
+    // decodeURIComponent can throw URIError for malformed sequences (e.g., %E0%A4%A)
+    let path: string;
+    try {
+      path = decodeURIComponent(requestUrl.pathname);
+    } catch {
+      // Malformed URL encoding - return null to let API server handle or return 400
+      return null;
+    }
+
+    // Let API server handle its routes
+    if (isServerPath(path)) {
+      return null;
+    }
+
+    // Resolve path with traversal check
+    const filePath = resolveAssetPathWithTraversalCheck({
+      requestPath: path,
+      clientDir,
+    });
+    if (!filePath) {
+      return null; // Path traversal attempt blocked
+    }
+
+    // Try to serve the requested file, fall back to index.html for SPA routing
+    const indexPath = resolve(clientDir, "index.html");
+    for (const pathToTry of [filePath, indexPath]) {
+      try {
+        const file = Bun.file(pathToTry);
+        if (await file.exists()) {
+          return new Response(file);
+        }
+      } catch {
+        // Continue to next path
+      }
+    }
+
+    return null;
+  };
+}

package/src/bindings/binder.ts

@@ -1,14 +1,13 @@
 /* oxlint-disable no-explicit-any */
 import { z } from "zod";
 import type { MCPConnection } from "../connection.ts";
-import { createPrivateTool, createStreamableTool } from "../mastra.ts";
 import {
   createMCPFetchStub,
   type MCPClientFetchStub,
   type ToolBinder,
 } from "../mcp.ts";
+import { createPrivateTool, createStreamableTool } from "../tools.ts";
 import { CHANNEL_BINDING } from "./channels.ts";
-import { VIEW_BINDING } from "./views.ts";
 
 // ToolLike is a simplified version of the Tool interface that matches what we need for bindings
 export interface ToolLike<
@@ -89,12 +88,10 @@ export const bindingClient = <TDefinition extends readonly ToolBinder[]>(
   };
 };
 
-export type MCPBindingClient<T extends ReturnType<typeof bindingClient>> =
+export type MCPBindingClient<T extends ReturnType<typeof bindingClient<any>>> =
   ReturnType<T["forConnection"]>;
 
 export const ChannelBinding = bindingClient(CHANNEL_BINDING);
-export const ViewBinding = bindingClient(VIEW_BINDING);
-
 export type { Callbacks } from "./channels.ts";
 
 export const impl = <TBinder extends Binder>(

package/src/bindings/index.ts

@@ -1,16 +1,13 @@
 import { CHANNEL_BINDING } from "./channels.ts";
-import { VIEW_BINDING as VIEWS_BINDING } from "./views.ts";
 
 // Import new Resources 2.0 bindings function
 import { LANGUAGE_MODEL_BINDING } from "@decocms/bindings/llm";
-import { createResourceBindings } from "./resources/bindings.ts";
 
 // Export types and utilities from binder
 export {
   bindingClient,
   ChannelBinding,
   impl,
-  ViewBinding,
   type Binder,
   type BinderImplementation,
   type MCPBindingClient,
@@ -23,40 +20,10 @@ export * from "./channels.ts";
 // Export binding utilities
 export * from "./utils.ts";
 
-// Export views schemas
-export * from "./views.ts";
-
-// Re-export Resources bindings function for convenience
-export { createResourceBindings };
-
-// Export resources types and schemas
-export * from "./resources/bindings.ts";
-export * from "./resources/helpers.ts";
-export * from "./resources/schemas.ts";
-
-// Export deconfig helpers and types
-export {
-  getMetadataString as deconfigGetMetadataString,
-  getMetadataValue as deconfigGetMetadataValue,
-  normalizeDirectory as deconfigNormalizeDirectory,
-  ResourcePath,
-  ResourceUri,
-} from "./deconfig/helpers.ts";
-export { createDeconfigResource } from "./deconfig/index.ts";
-export type {
-  DeconfigClient,
-  DeconfigResourceOptions,
-  EnhancedResourcesTools,
-  ResourcesBinding,
-  ResourcesTools,
-} from "./deconfig/index.ts";
-export { deconfigTools } from "./deconfig/types.ts";
-
 export { streamToResponse } from "./language-model/utils.ts";
 
 export const WellKnownBindings = {
   Channel: CHANNEL_BINDING,
-  View: VIEWS_BINDING,
   LanguageModel: LANGUAGE_MODEL_BINDING,
   // Note: Resources is not included here since it's a generic function
   // Use createResourceBindings(dataSchema) directly for Resources 2.0

package/src/bindings/language-model/utils.ts

@@ -25,94 +25,3 @@ export function streamToResponse(
     },
   });
 }
-
-export function responseToStream(
-  response: Response,
-): ReadableStream<LanguageModelV2StreamPart> {
-  if (!response.body) {
-    throw new Error("Response body is null");
-  }
-
-  return response.body.pipeThrough(new TextDecoderStream()).pipeThrough(
-    new TransformStream<string, LanguageModelV2StreamPart>({
-      transform(chunk, controller) {
-        // Split by newlines and parse each line
-        const lines = chunk.split("\n");
-
-        for (const line of lines) {
-          if (line.trim()) {
-            try {
-              const parsed = JSON.parse(line) as LanguageModelV2StreamPart;
-              controller.enqueue(parsed);
-            } catch (error) {
-              console.error("Failed to parse stream chunk:", error);
-            }
-          }
-        }
-      },
-    }),
-  );
-}
-
-/**
- * Lazy promise wrapper that defers execution until the promise is awaited.
- * The factory function is only called when .then() is invoked for the first time.
- */
-class Lazy<T> implements PromiseLike<T> {
-  private promise: Promise<T> | null = null;
-
-  constructor(private factory: () => Promise<T>) {}
-
-  private getOrCreatePromise(): Promise<T> {
-    if (!this.promise) {
-      this.promise = this.factory();
-    }
-    return this.promise;
-  }
-
-  // eslint-disable-next-line no-thenable
-  then<TResult1 = T, TResult2 = never>(
-    onfulfilled?:
-      | ((value: T) => TResult1 | PromiseLike<TResult1>)
-      | null
-      | undefined,
-    onrejected?:
-      | ((reason: unknown) => TResult2 | PromiseLike<TResult2>)
-      | null
-      | undefined,
-  ): PromiseLike<TResult1 | TResult2> {
-    return this.getOrCreatePromise().then(onfulfilled, onrejected);
-  }
-
-  catch<TResult = never>(
-    onrejected?:
-      | ((reason: unknown) => TResult | PromiseLike<TResult>)
-      | null
-      | undefined,
-  ): Promise<T | TResult> {
-    return this.getOrCreatePromise().catch(onrejected);
-  }
-
-  finally(onfinally?: (() => void) | null | undefined): Promise<T> {
-    return this.getOrCreatePromise().finally(onfinally);
-  }
-}
-
-/**
- * Creates a lazy promise that only executes when awaited.
- *
- * @param factory - A function that returns a Promise<T>
- * @returns A Promise-like object that defers execution until .then() is called
- *
- * @example
- * ```ts
- * const lazyData = lazy(() => fetchExpensiveData());
- * // fetchExpensiveData() is NOT called yet
- *
- * const result = await lazyData;
- * // fetchExpensiveData() is called NOW
- * ```
- */
-export function lazy<T>(factory: () => Promise<T>): Promise<T> {
-  return new Lazy(factory) as unknown as Promise<T>;
-}