@papicandela/mcx-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,568 @@
+import { z } from 'zod';
+export { z } from 'zod';
+
+/**
+ * Configuration for an adapter method parameter
+ */
+interface AdapterMethodParameter {
+    name: string;
+    type: "string" | "number" | "boolean" | "object" | "array";
+    description?: string;
+    required?: boolean;
+    default?: unknown;
+}
+/**
+ * Configuration for an adapter method
+ */
+interface AdapterMethodConfig {
+    name: string;
+    description?: string;
+    parameters?: AdapterMethodParameter[];
+    handler: (...args: unknown[]) => unknown | Promise<unknown>;
+}
+/**
+ * A method exposed by an adapter
+ */
+interface AdapterMethod {
+    name: string;
+    description?: string;
+    parameters: AdapterMethodParameter[];
+    execute: (...args: unknown[]) => unknown | Promise<unknown>;
+}
+/**
+ * Configuration for defining an adapter
+ */
+interface AdapterConfig<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {
+    name: string;
+    description?: string;
+    version?: string;
+    configSchema?: TSchema;
+    methods: AdapterMethodConfig[];
+}
+/**
+ * A registered adapter instance
+ */
+interface Adapter {
+    name: string;
+    description?: string;
+    version: string;
+    methods: Map<string, AdapterMethod>;
+    config?: unknown;
+}
+/**
+ * Configuration for the sandbox execution environment
+ */
+interface SandboxConfig {
+    /** Timeout in milliseconds (default: 5000) */
+    timeout?: number;
+    /** Memory limit in MB (default: 128) */
+    memoryLimit?: number;
+    /** Whether to allow async/await (default: true) */
+    allowAsync?: boolean;
+    /** Custom global variables to inject */
+    globals?: Record<string, unknown>;
+}
+/**
+ * Result from sandbox code execution
+ */
+interface SandboxResult<T = unknown> {
+    success: boolean;
+    value?: T;
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    logs: string[];
+    executionTime: number;
+}
+/**
+ * Skill run function signature
+ */
+type SkillRunFunction = (ctx: Record<string, unknown>) => Promise<unknown> | unknown;
+/**
+ * Configuration for defining a skill
+ */
+interface SkillConfig {
+    name: string;
+    description?: string;
+    version?: string;
+    /** Required adapters for this skill */
+    adapters?: string[];
+    /** The skill code to execute (sandbox mode) */
+    code?: string;
+    /** Direct run function (native mode) */
+    run?: SkillRunFunction;
+    /** Sandbox configuration overrides */
+    sandbox?: SandboxConfig;
+}
+/**
+ * A registered skill instance
+ */
+interface Skill {
+    name: string;
+    description?: string;
+    version: string;
+    adapters: string[];
+    /** Code string for sandbox execution */
+    code?: string;
+    /** Direct run function for native execution */
+    run?: SkillRunFunction;
+    sandboxConfig: SandboxConfig;
+}
+/**
+ * Main MCX framework configuration
+ */
+interface MCXConfig {
+    /** Adapters to load */
+    adapters?: Adapter[];
+    /** Skills to register */
+    skills?: Skill[];
+    /** Default sandbox configuration */
+    sandbox?: SandboxConfig;
+    /** Path to adapters directory */
+    adaptersDir?: string;
+    /** Path to skills directory */
+    skillsDir?: string;
+}
+/**
+ * Context passed to sandbox execution
+ */
+interface ExecutionContext {
+    /** Registered adapters accessible in sandbox */
+    adapters: Record<string, Record<string, (...args: unknown[]) => unknown | Promise<unknown>>>;
+    /** Custom variables */
+    variables?: Record<string, unknown>;
+}
+
+/**
+ * Interface for sandbox implementations
+ *
+ * Sandboxes provide isolated code execution environments
+ * with configurable resource limits and adapter injection.
+ */
+interface ISandbox {
+    /**
+     * Execute code in the sandbox
+     *
+     * @param code - JavaScript code to execute
+     * @param context - Execution context with adapters and variables
+     * @returns Result containing the value, logs, and execution metadata
+     */
+    execute<T = unknown>(code: string, context: ExecutionContext): Promise<SandboxResult<T>>;
+    /**
+     * Get the current sandbox configuration
+     */
+    getConfig(): SandboxConfig;
+    /**
+     * Update sandbox configuration
+     *
+     * @param config - New configuration options to merge
+     */
+    configure(config: Partial<SandboxConfig>): void;
+    /**
+     * Dispose of sandbox resources
+     */
+    dispose(): void;
+}
+/**
+ * Factory function type for creating sandbox instances
+ */
+type SandboxFactory = (config?: SandboxConfig) => ISandbox;
+
+/**
+ * Isolated-vm based sandbox implementation.
+ * Provides secure code execution with memory limits, timeouts, and isolation.
+ *
+ * Note: This uses isolated-vm's Context.eval() API which runs code in a
+ * completely isolated V8 instance - this is the secure sandboxing mechanism,
+ * not the dangerous global eval().
+ */
+declare class IsolatedVMSandbox implements ISandbox {
+    private config;
+    private isolate;
+    constructor(config?: SandboxConfig);
+    /**
+     * Get the current sandbox configuration.
+     */
+    getConfig(): SandboxConfig;
+    /**
+     * Update sandbox configuration.
+     */
+    configure(config: Partial<SandboxConfig>): void;
+    /**
+     * Execute code within the isolated VM sandbox.
+     */
+    execute<T = unknown>(code: string, context: ExecutionContext): Promise<SandboxResult<T>>;
+    /**
+     * Inject adapters into the sandbox context.
+     */
+    private injectAdapters;
+    /**
+     * Dispose of the current isolate.
+     */
+    private disposeIsolate;
+    /**
+     * Dispose of sandbox resources.
+     */
+    dispose(): void;
+}
+/**
+ * Create a new IsolatedVMSandbox instance.
+ */
+declare function createSandbox(config?: SandboxConfig): ISandbox;
+
+/**
+ * Define an adapter with type-safe configuration and zod validation.
+ *
+ * @example
+ * ```ts
+ * const fileAdapter = defineAdapter({
+ *   name: 'file',
+ *   description: 'File system operations',
+ *   configSchema: z.object({
+ *     basePath: z.string().default('./'),
+ *   }),
+ *   methods: [
+ *     {
+ *       name: 'read',
+ *       parameters: [
+ *         { name: 'path', type: 'string', required: true },
+ *       ],
+ *       handler: (path: string) => fs.readFileSync(path, 'utf-8'),
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+declare function defineAdapter<TSchema extends z.ZodTypeAny = z.ZodTypeAny>(config: AdapterConfig<TSchema>, adapterConfig?: z.infer<TSchema>): Adapter;
+/**
+ * Type helper for creating strongly-typed adapter configurations.
+ */
+type InferAdapterConfig<T extends AdapterConfig> = T extends AdapterConfig<infer TSchema> ? z.infer<TSchema> : never;
+/**
+ * Create an adapter factory that can be configured later.
+ *
+ * @example
+ * ```ts
+ * const createFileAdapter = createAdapterFactory({
+ *   name: 'file',
+ *   configSchema: z.object({ basePath: z.string() }),
+ *   methods: [...],
+ * });
+ *
+ * const adapter = createFileAdapter({ basePath: '/data' });
+ * ```
+ */
+declare function createAdapterFactory<TSchema extends z.ZodTypeAny>(config: AdapterConfig<TSchema>): (adapterConfig: z.infer<TSchema>) => Adapter;
+
+/**
+ * Define a skill with configuration.
+ *
+ * Skills are executable code snippets that run in a sandboxed environment
+ * with access to registered adapters.
+ *
+ * @example
+ * ```ts
+ * const mySkill = defineSkill({
+ *   name: 'process-data',
+ *   description: 'Processes data using file and http adapters',
+ *   adapters: ['file', 'http'],
+ *   code: `
+ *     const data = await adapters.file.read('input.json');
+ *     const result = await adapters.http.post('/api/process', { body: data });
+ *     return result;
+ *   `,
+ *   sandbox: {
+ *     timeout: 10000,
+ *   },
+ * });
+ * ```
+ */
+declare function defineSkill(config: SkillConfig): Skill;
+/**
+ * Define multiple skills at once.
+ *
+ * @example
+ * ```ts
+ * const skills = defineSkills([
+ *   { name: 'skill1', code: '...' },
+ *   { name: 'skill2', code: '...' },
+ * ]);
+ * ```
+ */
+declare function defineSkills(configs: SkillConfig[]): Skill[];
+/**
+ * Create a skill builder for fluent skill definition.
+ *
+ * @example
+ * ```ts
+ * const skill = skillBuilder('my-skill')
+ *   .description('Does something useful')
+ *   .requires('file', 'http')
+ *   .timeout(10000)
+ *   .code(`
+ *     // skill code here
+ *   `)
+ *   .build();
+ * ```
+ */
+declare function skillBuilder(name: string): SkillBuilder;
+/**
+ * Fluent builder for skill configuration.
+ */
+declare class SkillBuilder {
+    private config;
+    constructor(name: string);
+    /**
+     * Set the skill description.
+     */
+    description(description: string): this;
+    /**
+     * Set the skill version.
+     */
+    version(version: string): this;
+    /**
+     * Specify required adapters.
+     */
+    requires(...adapters: string[]): this;
+    /**
+     * Set the execution timeout in milliseconds.
+     */
+    timeout(ms: number): this;
+    /**
+     * Set the memory limit in MB.
+     */
+    memoryLimit(mb: number): this;
+    /**
+     * Set the skill code.
+     */
+    code(code: string): this;
+    /**
+     * Set custom sandbox configuration.
+     */
+    sandbox(config: SandboxConfig): this;
+    /**
+     * Build the skill.
+     */
+    build(): Skill;
+}
+
+/**
+ * Define the MCX framework configuration.
+ *
+ * This is typically used in an `mcx.config.ts` file at the root of your project.
+ *
+ * @example
+ * ```ts
+ * // mcx.config.ts
+ * import { defineConfig } from '@mcx/core';
+ * import { fileAdapter } from './adapters/file';
+ * import { httpAdapter } from './adapters/http';
+ *
+ * export default defineConfig({
+ *   adapters: [fileAdapter, httpAdapter],
+ *   skills: [],
+ *   sandbox: {
+ *     timeout: 10000,
+ *     memoryLimit: 256,
+ *   },
+ * });
+ * ```
+ */
+declare function defineConfig(config: MCXConfig): MCXConfig;
+/**
+ * Configuration builder for fluent MCX configuration.
+ *
+ * @example
+ * ```ts
+ * const config = configBuilder()
+ *   .adapter(fileAdapter)
+ *   .adapter(httpAdapter)
+ *   .skill(processSkill)
+ *   .sandbox({ timeout: 10000 })
+ *   .build();
+ * ```
+ */
+declare function configBuilder(): MCXConfigBuilder;
+/**
+ * Fluent builder for MCX configuration.
+ */
+declare class MCXConfigBuilder {
+    private config;
+    /**
+     * Add an adapter to the configuration.
+     */
+    adapter(adapter: Adapter): this;
+    /**
+     * Add multiple adapters to the configuration.
+     */
+    adapters(...adapters: Adapter[]): this;
+    /**
+     * Add a skill to the configuration.
+     */
+    skill(skill: Skill): this;
+    /**
+     * Add multiple skills to the configuration.
+     */
+    skills(...skills: Skill[]): this;
+    /**
+     * Set the sandbox configuration.
+     */
+    sandbox(config: SandboxConfig): this;
+    /**
+     * Set the adapters directory path.
+     */
+    adaptersDir(path: string): this;
+    /**
+     * Set the skills directory path.
+     */
+    skillsDir(path: string): this;
+    /**
+     * Build the configuration.
+     */
+    build(): MCXConfig;
+}
+/**
+ * Merge multiple configurations together.
+ * Later configurations override earlier ones.
+ */
+declare function mergeConfigs(...configs: MCXConfig[]): MCXConfig;
+
+/**
+ * Options for executor initialization.
+ */
+interface ExecutorOptions {
+    /** Path to the mcx.config.ts file */
+    configPath?: string;
+    /** Initial configuration (merged with loaded config) */
+    config?: MCXConfig;
+    /** Custom sandbox factory */
+    sandboxFactory?: (config?: SandboxConfig) => ISandbox;
+}
+/**
+ * Main MCX executor class.
+ *
+ * Manages adapters, skills, and code execution in a sandboxed environment.
+ *
+ * @example
+ * ```ts
+ * const executor = new MCXExecutor();
+ * await executor.loadConfig('./mcx.config.ts');
+ *
+ * // Execute raw code
+ * const result = await executor.execute(`
+ *   const data = await adapters.file.read('input.txt');
+ *   return data.toUpperCase();
+ * `);
+ *
+ * // Run a registered skill
+ * const skillResult = await executor.runSkill('process-data');
+ * ```
+ */
+declare class MCXExecutor {
+    private adapters;
+    private skills;
+    private sandboxConfig;
+    private sandboxFactory;
+    private configPath?;
+    constructor(options?: ExecutorOptions);
+    /**
+     * Load configuration from an mcx.config.ts file.
+     *
+     * @param configPath - Path to the configuration file
+     */
+    loadConfig(configPath?: string): Promise<void>;
+    /**
+     * Register an adapter.
+     *
+     * @param adapter - The adapter to register
+     */
+    registerAdapter(adapter: Adapter): void;
+    /**
+     * Unregister an adapter.
+     *
+     * @param name - The adapter name
+     * @returns Whether the adapter was removed
+     */
+    unregisterAdapter(name: string): boolean;
+    /**
+     * Get a registered adapter by name.
+     *
+     * @param name - The adapter name
+     */
+    getAdapter(name: string): Adapter | undefined;
+    /**
+     * Get all registered adapter names.
+     */
+    getAdapterNames(): string[];
+    /**
+     * Register a skill.
+     *
+     * @param skill - The skill to register
+     */
+    registerSkill(skill: Skill): void;
+    /**
+     * Unregister a skill.
+     *
+     * @param name - The skill name
+     * @returns Whether the skill was removed
+     */
+    unregisterSkill(name: string): boolean;
+    /**
+     * Get a registered skill by name.
+     *
+     * @param name - The skill name
+     */
+    getSkill(name: string): Skill | undefined;
+    /**
+     * Get all registered skill names.
+     */
+    getSkillNames(): string[];
+    /**
+     * Execute code in the sandbox.
+     *
+     * @param code - The code to execute
+     * @param options - Execution options
+     */
+    execute<T = unknown>(code: string, options?: {
+        /** Override sandbox config for this execution */
+        sandbox?: Partial<SandboxConfig>;
+        /** Specific adapters to include (default: all) */
+        adapters?: string[];
+        /** Additional context variables */
+        variables?: Record<string, unknown>;
+    }): Promise<SandboxResult<T>>;
+    /**
+     * Run a registered skill by name.
+     *
+     * @param name - The skill name
+     * @param options - Execution options
+     */
+    runSkill<T = unknown>(name: string, options?: {
+        /** Additional context variables */
+        variables?: Record<string, unknown>;
+    }): Promise<SandboxResult<T>>;
+    /**
+     * Update the default sandbox configuration.
+     */
+    configureSandbox(config: Partial<SandboxConfig>): void;
+    /**
+     * Build the execution context for the sandbox.
+     */
+    private buildExecutionContext;
+}
+/**
+ * Create a new MCXExecutor instance.
+ *
+ * @example
+ * ```ts
+ * const executor = createExecutor({
+ *   configPath: './mcx.config.ts',
+ * });
+ * await executor.loadConfig();
+ * ```
+ */
+declare function createExecutor(options?: ExecutorOptions): MCXExecutor;
+
+export { type Adapter, type AdapterConfig, type AdapterMethod, type AdapterMethodConfig, type AdapterMethodParameter, type ExecutionContext, type ExecutorOptions, type ISandbox, type InferAdapterConfig, IsolatedVMSandbox, type MCXConfig, MCXExecutor, type SandboxConfig, type SandboxFactory, type SandboxResult, type Skill, type SkillConfig, configBuilder, createAdapterFactory, createExecutor, createSandbox, defineAdapter, defineConfig, defineSkill, defineSkills, mergeConfigs, skillBuilder };