beddel 0.2.3 → 1.0.0

package/package.json

@@ -1,123 +1,36 @@
 {
-  "name": "beddel",
-  "version": "0.2.3",
-  "description": "Beddel - A secure YAML parser and OpenAPI endpoint manager for Node.js applications",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist",
-    "src",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+    "name": "beddel",
+    "version": "1.0.0",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        },
+        "./server": {
+            "import": "./dist/server.js",
+            "types": "./dist/server.d.ts"
+        },
+        "./client": {
+            "import": "./dist/client.js",
+            "types": "./dist/client.d.ts"
+        }
     },
-    "./server": {
-      "types": "./dist/server/index.d.ts",
-      "default": "./dist/server/index.js"
+    "scripts": {
+        "build": "tsc",
+        "dev": "tsc --watch"
     },
-    "./server/*": {
-      "types": "./dist/server/*.d.ts",
-      "default": "./dist/server/*.js"
+    "dependencies": {
+        "ai": "^6.0.3",
+        "@ai-sdk/google": "^3.0.1",
+        "zod": "^3.23.8",
+        "js-yaml": "^4.1.0"
     },
-    "./server/api/graphql": {
-      "types": "./dist/server/api/graphql.d.ts",
-      "default": "./dist/server/api/graphql.js"
-    },
-    "./client": {
-      "types": "./dist/client/index.d.ts",
-      "default": "./dist/client/index.js"
-    },
-    "./shared": {
-      "types": "./dist/shared/index.d.ts",
-      "default": "./dist/shared/index.js"
-    },
-    "./agents": {
-      "types": "./dist/agents/index.d.ts",
-      "default": "./dist/agents/index.js"
-    },
-    "./agents/*": {
-      "types": "./dist/agents/*/index.d.ts",
-      "default": "./dist/agents/*/index.js"
-    }
-  },
-  "scripts": {
-    "prepublishOnly": "npm run build",
-    "build": "tsc -p tsconfig.build.json && npm run copy-yaml",
-    "copy-yaml": "find src/agents -name '*.yaml' -exec sh -c 'mkdir -p dist/agents/$(dirname \"{}\" | sed \"s|src/agents/||\") && cp \"{}\" dist/agents/$(dirname \"{}\" | sed \"s|src/agents/||\")/$(basename \"{}\")' \\;",
-    "dev": "tsc -p tsconfig.build.json --watch",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage",
-    "lint": "eslint src --ext .ts",
-    "lint:fix": "eslint src --ext .ts --fix",
-    "version:patch": "npm version patch",
-    "version:minor": "npm version minor",
-    "version:major": "npm version major"
-  },
-  "keywords": [
-    "yaml",
-    "agents",
-    "ai-agents",
-    "declarative",
-    "secure",
-    "sandbox",
-    "isolated-vm",
-    "multi-tenant",
-    "gemini",
-    "genkit",
-    "workflow",
-    "nodejs"
-  ],
-  "author": "Beddel Contributors",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/botanarede/beddel.git"
-  },
-  "bugs": {
-    "url": "https://github.com/botanarede/beddel/issues"
-  },
-  "homepage": "https://github.com/botanarede/beddel#readme",
-  "dependencies": {
-    "@ai-sdk/google": "^2.0.23",
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "@upstash/redis": "^1.34.3",
-    "ai": "^5.0.70",
-    "chromadb": "^3.1.8",
-    "eventsource": "^2.0.2",
-    "graphql": "^16.10.0",
-    "graphql-yoga": "^5.13.5",
-    "isolated-vm": "5.0.1",
-    "js-yaml": "^4.1.1",
-    "server-only": "^0.0.1",
-    "zod": "^4.1.12"
-  },
-  "peerDependencies": {
-    "firebase-admin": ">=12.0.0"
-  },
-  "peerDependenciesMeta": {
-    "firebase-admin": {
-      "optional": true
+    "devDependencies": {
+        "typescript": "^5.6.3",
+        "@types/node": "^22.10.2",
+        "@types/js-yaml": "^4.0.9"
     }
-  },
-  "devDependencies": {
-    "@types/eventsource": "^1.1.15",
-    "@types/jest": "^29.5.12",
-    "@types/js-yaml": "^4.0.9",
-    "@types/node": "^22.0.0",
-    "@typescript-eslint/eslint-plugin": "^8.0.0",
-    "@typescript-eslint/parser": "^8.0.0",
-    "eslint": "^9.0.0",
-    "jest": "^29.0.0",
-    "ts-jest": "^29.0.0",
-    "typescript": "^5.0.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+}

package/src/client.ts

@@ -0,0 +1,18 @@
+/**
+ * Beddel Protocol - Client Bundle
+ * 
+ * This entry point exports ONLY types and utilities safe for client-side use.
+ * No Node.js dependencies (fs, crypto, etc.) are included here.
+ * 
+ * Usage: import type { ParsedYaml } from 'beddel/client';
+ */
+
+// Types only - safe for client bundles
+export type {
+    ParsedYaml,
+    WorkflowStep,
+    StepConfig,
+    YamlMetadata,
+    ExecutionContext,
+    PrimitiveHandler,
+} from './types';

package/src/core/parser.ts

@@ -0,0 +1,36 @@
+/**
+ * Beddel Protocol - Secure YAML Parser
+ * Uses FAILSAFE_SCHEMA to prevent code execution attacks
+ */
+
+import { readFile } from 'fs/promises';
+import yaml, { FAILSAFE_SCHEMA } from 'js-yaml';
+import type { ParsedYaml } from '../types';
+
+/**
+ * Load and parse a YAML workflow file securely.
+ * 
+ * Security: Uses FAILSAFE_SCHEMA which only allows:
+ * - Strings
+ * - Arrays (sequences)
+ * - Plain objects (mappings)
+ * 
+ * This completely blocks dangerous YAML tags:
+ * - !!js/function (arbitrary code execution)
+ * - !!js/regexp (ReDoS vulnerabilities)
+ * - !!js/undefined
+ * - Custom tags
+ * 
+ * @param path - Absolute or relative path to YAML file
+ * @returns Parsed YAML as typed ParsedYaml object
+ * @throws Error if file cannot be read or YAML is invalid
+ */
+export async function loadYaml(path: string): Promise<ParsedYaml> {
+    const content = await readFile(path, 'utf-8');
+
+    // FAILSAFE_SCHEMA is the most restrictive schema in js-yaml
+    // No custom constructors, no type coercion, maximum security
+    const parsed = yaml.load(content, { schema: FAILSAFE_SCHEMA }) as ParsedYaml;
+
+    return parsed;
+}

package/src/core/variable-resolver.ts

@@ -0,0 +1,114 @@
+/**
+ * Beddel Protocol - Variable Resolver
+ * 
+ * Resolves template variables in step configurations.
+ * Patterns: $input.path.to.value, $stepResult.path.to.value
+ * 
+ * Server-only: Used within WorkflowExecutor during step execution.
+ */
+
+import type { ExecutionContext } from '../types';
+
+/**
+ * Resolve a path like "foo.bar.baz" on an object.
+ * Returns undefined if path doesn't exist.
+ */
+function resolvePath(obj: unknown, path: string): unknown {
+    const parts = path.split('.');
+    let current: unknown = obj;
+
+    for (const part of parts) {
+        if (current === null || current === undefined) {
+            return undefined;
+        }
+        if (typeof current === 'object') {
+            current = (current as Record<string, unknown>)[part];
+        } else {
+            return undefined;
+        }
+    }
+
+    return current;
+}
+
+/**
+ * Resolve variable references in a template value.
+ * 
+ * Supports:
+ * - "$input.messages" → context.input.messages
+ * - "$stepResult.llmOutput.text" → context.variables.get('llmOutput').text
+ * - Nested objects/arrays are resolved recursively
+ * 
+ * @param template - Value to resolve (string, object, array, or primitive)
+ * @param context - Execution context with input and variables
+ * @returns Resolved value with all variable references replaced
+ */
+export function resolveVariables(template: unknown, context: ExecutionContext): unknown {
+    // Handle null/undefined
+    if (template === null || template === undefined) {
+        return template;
+    }
+
+    // Handle string patterns
+    if (typeof template === 'string') {
+        // Check for $input.* pattern
+        if (template.startsWith('$input.')) {
+            const path = template.slice(7); // Remove "$input."
+            return resolvePath(context.input, path);
+        }
+
+        // Check for $stepResult.* pattern (references step.result names)
+        if (template.startsWith('$stepResult.')) {
+            const fullPath = template.slice(12); // Remove "$stepResult."
+            const dotIndex = fullPath.indexOf('.');
+
+            if (dotIndex === -1) {
+                // Just the variable name, e.g., "$stepResult.llmOutput"
+                return context.variables.get(fullPath);
+            }
+
+            // Variable name + path, e.g., "$stepResult.llmOutput.text"
+            const varName = fullPath.slice(0, dotIndex);
+            const restPath = fullPath.slice(dotIndex + 1);
+            const varValue = context.variables.get(varName);
+            return resolvePath(varValue, restPath);
+        }
+
+        // Check for legacy $varName.* pattern (direct variable reference)
+        if (template.startsWith('$') && !template.startsWith('$$')) {
+            const fullPath = template.slice(1); // Remove "$"
+            const dotIndex = fullPath.indexOf('.');
+
+            if (dotIndex === -1) {
+                // Just the variable name, e.g., "$llmOutput"
+                return context.variables.get(fullPath);
+            }
+
+            // Variable name + path, e.g., "$llmOutput.text"
+            const varName = fullPath.slice(0, dotIndex);
+            const restPath = fullPath.slice(dotIndex + 1);
+            const varValue = context.variables.get(varName);
+            return resolvePath(varValue, restPath);
+        }
+
+        // No pattern match, return as-is
+        return template;
+    }
+
+    // Handle arrays - resolve each element
+    if (Array.isArray(template)) {
+        return template.map(item => resolveVariables(item, context));
+    }
+
+    // Handle objects - resolve each value
+    if (typeof template === 'object') {
+        const resolved: Record<string, unknown> = {};
+        for (const [key, value] of Object.entries(template)) {
+            resolved[key] = resolveVariables(value, context);
+        }
+        return resolved;
+    }
+
+    // Primitives (number, boolean) - return as-is
+    return template;
+}

package/src/core/workflow.ts

@@ -0,0 +1,77 @@
+/**
+ * Beddel Protocol - Workflow Executor
+ * 
+ * Sequential pipeline executor that iterates over workflow steps.
+ * 
+ * Server-only: Uses primitives that may call external APIs.
+ * 
+ * CRITICAL BEHAVIOR:
+ * - If a handler returns a Response instance (streaming), execution stops
+ *   and that Response is returned immediately to the client.
+ * - Non-Response results are stored in context.variables for subsequent steps.
+ */
+
+import type { ParsedYaml, WorkflowStep, ExecutionContext, StepConfig } from '../types';
+import { handlerRegistry } from '../primitives';
+
+export class WorkflowExecutor {
+    private steps: WorkflowStep[];
+
+    /**
+     * Create a new WorkflowExecutor from parsed YAML.
+     * @param yaml - Parsed YAML document containing workflow steps
+     */
+    constructor(yaml: ParsedYaml) {
+        this.steps = yaml.workflow;
+    }
+
+    /**
+     * Execute the workflow pipeline.
+     * 
+     * @param input - Input data (e.g., { messages: [...] } for chat)
+     * @returns Response if streaming, or accumulated variables object
+     * 
+     * @example
+     * ```typescript
+     * const executor = new WorkflowExecutor(yaml);
+     * const result = await executor.execute({ messages });
+     * if (result instanceof Response) {
+     *   return result; // Stream to client
+     * }
+     * return Response.json(result);
+     * ```
+     */
+    async execute(input: unknown): Promise<Response | Record<string, unknown>> {
+        const context: ExecutionContext = {
+            input,
+            variables: new Map(),
+        };
+
+        for (const step of this.steps) {
+            const handler = handlerRegistry[step.type];
+
+            if (!handler) {
+                throw new Error(
+                    `[Beddel] Unknown step type: "${step.type}" in step "${step.id}". ` +
+                    `Registered types: ${Object.keys(handlerRegistry).join(', ') || '(none)'}`
+                );
+            }
+
+            // Execute the handler with step config and context
+            const result = await handler(step.config as StepConfig, context);
+
+            // CRITICAL: If handler returns Response (streaming), return immediately
+            if (result instanceof Response) {
+                return result;
+            }
+
+            // Store result for subsequent steps (if step.result is defined)
+            if (step.result) {
+                context.variables.set(step.result, result);
+            }
+        }
+
+        // No streaming occurred - return accumulated variables as object
+        return Object.fromEntries(context.variables);
+    }
+}

package/src/index.ts

@@ -1,168 +1,34 @@
 /**
- * Beddel - Parser YAML seguro com FAILSAFE_SCHEMA e Runtime Isolado
- *
- * Open source package para parsing YAML com foco máximo em segurança
- * Implementa FAILSAFE_SCHEMA, validações rigorosas, runtime isolado e multi-tenant isolation
+ * Beddel Protocol - Streaming Pipeline Edition
+ * Server Entry Point
+ * 
+ * This is the main entry point for server-side usage.
+ * Contains Node.js dependencies (fs) - DO NOT import in client code.
+ * 
+ * For client-safe types, use: import type { ... } from 'beddel/client';
  */
 
-// YAML Parser exports
-export {
-  SecureYamlParser,
-  createSecureYamlParser,
-  parseSecureYaml,
-} from "./parser/secure-yaml-parser";
+// Core (server-only)
+export { loadYaml } from './core/parser';
+export { WorkflowExecutor } from './core/workflow';
+export { resolveVariables } from './core/variable-resolver';
+export { createBeddelHandler } from './server/handler';
 
-// Runtime Isolado exports
-export {
-  IsolatedRuntimeManager,
-  runtimeManager,
-} from "./runtime/isolatedRuntime";
-export type {
-  ExecutionOptions,
-  ExecutionResult,
-  RuntimeContext,
-} from "./runtime/isolatedRuntime";
-
-// Simple Runtime exports
-export {
-  SimpleIsolatedRuntimeManager,
-  runtimeManager as simpleRuntimeManager,
-  IsolatedRuntimeError as SimpleRuntimeError,
-} from "./runtime/simpleRuntime";
-export type {
-  ExecutionOptions as SimpleExecutionOptions,
-  ExecutionResult as SimpleExecutionResult,
-} from "./runtime/simpleRuntime";
-
-// Declarative runtime exports
-export {
-  DeclarativeAgentInterpreter,
-  declarativeInterpreter,
-} from "./runtime/declarativeAgentRuntime";
-export type {
-  YamlAgentDefinition,
-  YamlAgentInterpreterOptions,
-  YamlExecutionResult,
-} from "./runtime/declarativeAgentRuntime";
-export {
-  DeclarativeSchemaCompiler,
-  DeclarativeSchemaValidationError,
-  SchemaCompilationError,
-} from "./runtime/schemaCompiler";
-
-// Agent registry exports
-export { AgentRegistry, agentRegistry } from "./agents/registry";
-export type { AgentRegistration } from "./agents/registry";
-
-// Configuration exports
-export {
-  runtimeConfig,
-  securityProfiles,
-  performanceTargets,
-  auditConfig,
-} from "./config";
-export type {
-  RuntimeConfig,
-  SecurityProfile,
-  PerformanceTarget,
-  AuditConfig,
-} from "./config";
-
-// Error exports
-export {
-  YAMLBaseError,
-  YAMLParseError,
-  YAMLSecurityError,
-  YAMLPerformanceError,
-} from "./errors";
 
-// Security exports
-export { SecurityScanner } from "./security/scanner";
-export { SecurityScore } from "./security/score";
-export {
-  SecurityManager,
-  SecurityMonitor,
-  securityMonitor,
-  SecurityDashboard,
-  securityDashboard,
-  ThreatDetectionEngine,
-  AnomalyDetector,
-  ThreatMLModel,
-} from "./security";
-export type {
-  AlertLevel,
-  SecurityEvent,
-  ThreatAnalysis,
-  DashboardConfig,
-  SecurityMetric,
-} from "./security";
-export { AuditService } from "./runtime/audit";
+// Primitives registry (for custom handler registration)
+export { handlerRegistry, registerPrimitive } from './primitives';
 
-// Performance exports
-export { PerformanceMonitor } from "./performance/monitor";
-export { default as AutoScaler } from "./performance/autoscaling";
+// Tools registry (for custom tool registration)
+export { toolRegistry, registerTool } from './tools';
+export type { ToolImplementation } from './tools';
 
-// Agnostic Multi-Tenant exports
-export {
-  TenantManager,
-  ProviderRegistry,
-  createProvider,
-  isValidProviderType,
-  isBuiltInProviderType,
-  getSupportedProviders,
-  getBuiltInProviders,
-  InMemoryTenantProvider,
-  TenantError,
-  ValidationError,
-  NotFoundError,
-  NotSupportedError,
-  TenantAlreadyExistsError,
-} from "./tenant";
+// Types (re-exported for convenience, also available via beddel/client)
 export type {
-  TenantConfig,
-  TenantIsolationResult,
-  ProviderType,
-  BuiltInProviderType,
-  FirebaseProviderConfig,
-  MemoryProviderConfig,
-  ITenantProvider,
-  ITenantApp,
-  ITenantDatabase,
-  ITenantCollection,
-  ITenantDocument,
-} from "./tenant";
-
-// Compliance exports
-export { GDPRCompliance } from "./compliance/gdprEngine";
-export { LGPDCompliance } from "./compliance/lgpdEngine";
-export type { GDPRConfig, GDPRComplianceResult } from "./compliance/gdprEngine";
-export type { LGPDConfig, LGPDComplianceResult } from "./compliance/lgpdEngine";
-
-// Integration: Secure YAML Parser with Isolated Runtime
-export { SecureYamlRuntime } from "./integration/secure-yaml-runtime";
-
-// Shared types
-export type { ExecutionContext } from "./types/executionContext";
-
-// Shared agent types (client-safe)
-export type {
-  AgentMetadata,
-  AgentResponse,
-  ExecutionStep,
-  WorkflowStepType,
-  AgentCategory,
-} from "./shared/types/agent.types";
-
-// Chat agent exports (client-safe)
-export type {
-  ChatHandlerParams,
-  ChatHandlerResult,
-  ChatMetadata,
-} from "./agents/chat/chat.types";
-export { chatMetadata } from "./agents/chat";
-
-// RAG types (client-safe)
-export type { ConversationMessage } from "./agents/rag/rag.types";
+    ParsedYaml,
+    WorkflowStep,
+    StepConfig,
+    YamlMetadata,
+    ExecutionContext,
+    PrimitiveHandler,
+} from './types';
 
-// Server/runtime exports
-export * as Server from "./server";

package/src/primitives/index.ts

@@ -0,0 +1,83 @@
+/**
+ * Beddel Protocol - Primitive Handler Registry
+ * 
+ * This registry maps step types to their handler implementations.
+ * Following Expansion Pack Pattern from BMAD-METHOD™ for extensibility.
+ * See: https://github.com/bmadcode/bmad-method
+ * 
+ * Server-only: Handlers may use Node.js APIs and external services.
+ */
+
+import type { PrimitiveHandler, StepConfig, ExecutionContext } from '../types';
+import { llmPrimitive } from './llm';
+import { outputPrimitive } from './output';
+
+// Re-export llm exports for consumer access
+export { llmPrimitive, registerCallback, callbackRegistry } from './llm';
+
+/**
+ * Placeholder handler for primitives not yet implemented.
+ * Returns config and context for debugging purposes.
+ */
+const placeholderHandler: PrimitiveHandler = async (
+    config: StepConfig,
+    context: ExecutionContext
+): Promise<Record<string, unknown>> => {
+    console.warn('[Beddel] Placeholder handler invoked. Implement the actual primitive.');
+    return {
+        _placeholder: true,
+        config,
+        input: context.input,
+        variableCount: context.variables.size,
+    };
+};
+
+/**
+ * Registry of primitive handlers keyed by step type.
+ * 
+ * MVP Primitives:
+ * - 'llm': Wrapper for streamText/generateText (Task 2.2)
+ * - 'output-generator': Deterministic variable mapping (Task 2.3)
+ * - 'call-agent': Sub-agent invocation (future)
+ */
+export const handlerRegistry: Record<string, PrimitiveHandler> = {
+    /**
+     * LLM Primitive - Dual-mode AI text generation.
+     * Supports streaming (streamText) and blocking (generateText) modes.
+     */
+    'llm': llmPrimitive,
+
+    /**
+     * Output Generator Primitive - Deterministic JSON transform.
+     * Resolves variable references in templates.
+     */
+    'output-generator': outputPrimitive,
+
+    /**
+     * Call Agent Primitive - Placeholder
+     * Enables recursive workflow execution via sub-agents.
+     */
+    'call-agent': placeholderHandler,
+};
+
+/**
+ * Register a custom primitive handler in the registry.
+ * Allows consumers to extend Beddel with domain-specific primitives.
+ * 
+ * @param type - Step type identifier (e.g., 'my-custom-primitive')
+ * @param handler - PrimitiveHandler function
+ * 
+ * @example
+ * import { registerPrimitive } from 'beddel';
+ * 
+ * registerPrimitive('http-fetch', async (config, context) => {
+ *   const response = await fetch(config.url);
+ *   return { data: await response.json() };
+ * });
+ */
+export function registerPrimitive(type: string, handler: PrimitiveHandler): void {
+    if (handlerRegistry[type]) {
+        console.warn(`[Beddel] Primitive '${type}' already registered, overwriting.`);
+    }
+    handlerRegistry[type] = handler;
+}