@papicandela/mcx-core 0.1.0 → 0.2.0

package/src/type-generator.ts

@@ -0,0 +1,172 @@
+/**
+ * Type Generator for MCX Adapters
+ *
+ * Generates TypeScript type declarations from adapter definitions.
+ * Used to provide LLM context with minimal tokens (Cloudflare pattern).
+ *
+ * @example
+ * ```ts
+ * const types = generateTypes(adapters, { includeDescriptions: true });
+ * // Output:
+ * // declare const myAdapter: {
+ * //   getData(params: { id: string }): Promise<unknown>;
+ * // }
+ * ```
+ */
+
+import type { Adapter, ParameterDefinition } from "./types.js";
+
+/**
+ * Options for type generation
+ */
+export interface TypeGeneratorOptions {
+  /** Include JSDoc descriptions in output (default: true) */
+  includeDescriptions?: boolean;
+  /** Use async return types (default: true) */
+  asyncResults?: boolean;
+  /** Namespace prefix for declarations (default: none) */
+  namespace?: string;
+}
+
+/**
+ * Generate TypeScript type declarations from adapters.
+ *
+ * @param adapters - Array of adapters to generate types for
+ * @param options - Generation options
+ * @returns TypeScript declaration string
+ */
+export function generateTypes(
+  adapters: Adapter[],
+  options: TypeGeneratorOptions = {}
+): string {
+  const { includeDescriptions = true, asyncResults = true } = options;
+  const lines: string[] = [];
+
+  for (const adapter of adapters) {
+    const safeName = sanitizeIdentifier(adapter.name);
+
+    // Generate input interface for each tool with parameters
+    for (const [toolName, tool] of Object.entries(adapter.tools)) {
+      if (tool.parameters && Object.keys(tool.parameters).length > 0) {
+        const inputTypeName = `${capitalize(safeName)}_${capitalize(toolName)}_Input`;
+        lines.push(generateInputInterface(inputTypeName, tool.parameters, includeDescriptions));
+        lines.push("");
+      }
+    }
+
+    // Generate adapter declaration
+    if (includeDescriptions && adapter.description) {
+      lines.push(`/** ${adapter.description} */`);
+    }
+    lines.push(`declare const ${safeName}: {`);
+
+    for (const [toolName, tool] of Object.entries(adapter.tools)) {
+      const safeToolName = sanitizeIdentifier(toolName);
+      const hasParams = tool.parameters && Object.keys(tool.parameters).length > 0;
+      const inputTypeName = `${capitalize(safeName)}_${capitalize(toolName)}_Input`;
+
+      if (includeDescriptions && tool.description) {
+        lines.push(`  /** ${tool.description} */`);
+      }
+
+      const paramStr = hasParams ? `params: ${inputTypeName}` : "";
+      const returnType = asyncResults ? "Promise<unknown>" : "unknown";
+      lines.push(`  ${safeToolName}(${paramStr}): ${returnType};`);
+    }
+
+    lines.push("};");
+    lines.push("");
+  }
+
+  return lines.join("\n").trim();
+}
+
+/**
+ * Generate a compact type summary for token-constrained contexts.
+ * Returns a condensed one-liner per adapter.
+ *
+ * @param adapters - Array of adapters
+ * @returns Compact summary string
+ */
+export function generateTypesSummary(adapters: Adapter[]): string {
+  return adapters
+    .map((adapter) => {
+      const methods = Object.keys(adapter.tools).join(", ");
+      return `${adapter.name}: { ${methods} }`;
+    })
+    .join("\n");
+}
+
+/**
+ * Generate input interface for a tool's parameters
+ */
+function generateInputInterface(
+  typeName: string,
+  parameters: Record<string, ParameterDefinition>,
+  includeDescriptions: boolean
+): string {
+  const lines: string[] = [`interface ${typeName} {`];
+
+  for (const [paramName, param] of Object.entries(parameters)) {
+    if (includeDescriptions && param.description) {
+      lines.push(`  /** ${param.description} */`);
+    }
+
+    const tsType = paramTypeToTS(param.type);
+    const optional = param.required === false ? "?" : "";
+    lines.push(`  ${paramName}${optional}: ${tsType};`);
+  }
+
+  lines.push("}");
+  return lines.join("\n");
+}
+
+/**
+ * Convert parameter type to TypeScript type
+ */
+function paramTypeToTS(type: string): string {
+  const typeMap: Record<string, string> = {
+    string: "string",
+    number: "number",
+    boolean: "boolean",
+    object: "Record<string, unknown>",
+    array: "unknown[]",
+  };
+  return typeMap[type] || "unknown";
+}
+
+/**
+ * Sanitize a string to be a valid JavaScript identifier
+ */
+export function sanitizeIdentifier(name: string): string {
+  // Replace invalid characters with underscores
+  let safe = name.replace(/[^a-zA-Z0-9_$]/g, "_");
+
+  // Prefix with underscore if starts with number
+  if (/^[0-9]/.test(safe)) {
+    safe = "_" + safe;
+  }
+
+  // Handle reserved words
+  const reserved = [
+    "break", "case", "catch", "continue", "debugger", "default", "delete",
+    "do", "else", "finally", "for", "function", "if", "in", "instanceof",
+    "new", "return", "switch", "this", "throw", "try", "typeof", "var",
+    "void", "while", "with", "class", "const", "enum", "export", "extends",
+    "import", "super", "implements", "interface", "let", "package", "private",
+    "protected", "public", "static", "yield",
+  ];
+
+  if (reserved.includes(safe)) {
+    safe = safe + "_";
+  }
+
+  return safe;
+}
+
+/**
+ * Capitalize first letter of a string
+ */
+function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}

package/src/types.ts

@@ -1,7 +1,48 @@
 import type { z } from "zod";
 
+// ============================================================================
+// Unified Adapter Types (compatible with @papicandela/mcx-adapters)
+// ============================================================================
+
+/**
+ * Parameter definition for adapter tools
+ */
+export interface ParameterDefinition {
+  type: "string" | "number" | "boolean" | "object" | "array";
+  description?: string;
+  required?: boolean;
+  default?: unknown;
+}
+
+/**
+ * Adapter tool definition (unified interface)
+ */
+export interface AdapterTool<TParams = unknown, TResult = unknown> {
+  description: string;
+  parameters?: Record<string, ParameterDefinition>;
+  execute: (params: TParams) => Promise<TResult> | TResult;
+}
+
 /**
- * Configuration for an adapter method parameter
+ * A registered adapter instance (unified interface)
+ *
+ * This is the canonical adapter interface used throughout MCX.
+ * Compatible with both core and adapters package.
+ */
+export interface Adapter<TTools extends Record<string, AdapterTool> = Record<string, AdapterTool>> {
+  name: string;
+  description?: string;
+  version?: string;
+  tools: TTools;
+  dispose?: () => Promise<void> | void;
+}
+
+// ============================================================================
+// Legacy Types (deprecated - use unified types above)
+// ============================================================================
+
+/**
+ * @deprecated Use ParameterDefinition instead
  */
 export interface AdapterMethodParameter {
   name: string;
@@ -12,7 +53,7 @@ export interface AdapterMethodParameter {
 }
 
 /**
- * Configuration for an adapter method
+ * @deprecated Use AdapterTool instead
  */
 export interface AdapterMethodConfig {
   name: string;
@@ -22,7 +63,7 @@ export interface AdapterMethodConfig {
 }
 
 /**
- * A method exposed by an adapter
+ * @deprecated Use AdapterTool instead
  */
 export interface AdapterMethod {
   name: string;
@@ -32,7 +73,7 @@ export interface AdapterMethod {
 }
 
 /**
- * Configuration for defining an adapter
+ * @deprecated Use Adapter with tools: Record<> instead
  */
 export interface AdapterConfig<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {
   name: string;
@@ -43,9 +84,9 @@ export interface AdapterConfig<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {
 }
 
 /**
- * A registered adapter instance
+ * @deprecated Legacy adapter interface - use Adapter instead
  */
-export interface Adapter {
+export interface LegacyAdapter {
   name: string;
   description?: string;
   version: string;
@@ -53,18 +94,41 @@ export interface Adapter {
   config?: unknown;
 }
 
+import type { NetworkPolicy } from "./sandbox/network-policy.js";
+import type { AnalysisConfig } from "./sandbox/analyzer/index.js";
+
 /**
- * Configuration for the sandbox execution environment
+ * Configuration for the sandbox execution environment.
+ *
+ * @example
+ * ```ts
+ * const config: SandboxConfig = {
+ *   timeout: 10000,
+ *   networkPolicy: { mode: 'blocked' },
+ *   normalizeCode: true,
+ *   analysis: {
+ *     enabled: true,
+ *     blockOnError: true,
+ *     rules: { 'no-infinite-loop': 'error' }
+ *   }
+ * };
+ * ```
  */
 export interface SandboxConfig {
   /** Timeout in milliseconds (default: 5000) */
   timeout?: number;
-  /** Memory limit in MB (default: 128) */
+  /** Memory limit in MB (default: 128, not enforced in Bun Workers) */
   memoryLimit?: number;
   /** Whether to allow async/await (default: true) */
   allowAsync?: boolean;
-  /** Custom global variables to inject */
+  /** Custom global variables to inject into sandbox */
   globals?: Record<string, unknown>;
+  /** Network access policy - blocked, allowed (whitelist), or unrestricted (default: blocked) */
+  networkPolicy?: NetworkPolicy;
+  /** Normalize code before execution - auto-add return, syntax validation (default: true) */
+  normalizeCode?: boolean;
+  /** Pre-execution analysis - detects infinite loops, dangerous patterns (default: enabled) */
+  analysis?: AnalysisConfig;
 }
 
 /**
@@ -133,6 +197,8 @@ export interface MCXConfig {
   adaptersDir?: string;
   /** Path to skills directory */
   skillsDir?: string;
+  /** Environment variables to inject into sandbox */
+  env?: Record<string, string | undefined>;
 }
 
 /**
@@ -143,4 +209,6 @@ export interface ExecutionContext {
   adapters: Record<string, Record<string, (...args: unknown[]) => unknown | Promise<unknown>>>;
   /** Custom variables */
   variables?: Record<string, unknown>;
+  /** Environment variables accessible in sandbox */
+  env?: Record<string, string | undefined>;
 }