@goreal-ai/echo-pdk 0.1.0

package/dist/plugins/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview Plugin System - Load and manage Echo plugins
+ *
+ * This module handles loading and registering plugins for Echo.
+ * Plugins can add custom operators, validators, and transformations.
+ *
+ * IMPLEMENTATION GUIDE:
+ *
+ * 1. PLUGIN LOADING
+ *    - Load from npm packages: @goreal-ai/echo-pdk-validators
+ *    - Load from local paths: ./plugins/my-plugin.ts
+ *    - Validate plugin structure
+ *
+ * 2. OPERATOR REGISTRATION
+ *    - Merge plugin operators with built-ins
+ *    - Handle conflicts (plugin can override built-in)
+ *
+ * 3. LIFECYCLE HOOKS
+ *    - onLoad: Called when plugin is loaded
+ *    - Future: onRender, onValidate, etc.
+ */
+import type { EchoPlugin, OperatorDefinition } from '../types.js';
+/**
+ * Plugin registry managing all loaded plugins.
+ */
+export interface PluginRegistry {
+    /** All loaded plugins */
+    plugins: EchoPlugin[];
+    /** Merged operator definitions from all plugins */
+    operators: Map<string, OperatorDefinition>;
+}
+/**
+ * Create a new plugin registry.
+ */
+export declare function createPluginRegistry(): PluginRegistry;
+/**
+ * Load a plugin into the registry.
+ *
+ * @param registry - The plugin registry
+ * @param plugin - The plugin to load
+ */
+export declare function loadPlugin(registry: PluginRegistry, plugin: EchoPlugin): Promise<void>;
+/**
+ * Load a plugin from a path (npm package or local file).
+ *
+ * @param registry - The plugin registry
+ * @param path - Path to the plugin
+ */
+export declare function loadPluginFromPath(_registry: PluginRegistry, path: string): Promise<void>;
+/**
+ * Validate a plugin structure.
+ *
+ * @param plugin - The plugin to validate
+ * @throws If the plugin is invalid
+ */
+export declare function validatePlugin(plugin: unknown): asserts plugin is EchoPlugin;
+/**
+ * Helper function for creating plugins with type safety.
+ * Re-exported from main index.ts
+ */
+export declare function definePlugin(plugin: EchoPlugin): EchoPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugins/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAMlE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,mDAAmD;IACnD,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAC5C;AAMD;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,CAKrD;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,cAAc,EACzB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAiBf;AAMD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,IAAI,UAAU,CAyB5E;AA+BD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAI3D"}

package/dist/plugins/index.js

@@ -0,0 +1,170 @@
+/**
+ * @fileoverview Plugin System - Load and manage Echo plugins
+ *
+ * This module handles loading and registering plugins for Echo.
+ * Plugins can add custom operators, validators, and transformations.
+ *
+ * IMPLEMENTATION GUIDE:
+ *
+ * 1. PLUGIN LOADING
+ *    - Load from npm packages: @goreal-ai/echo-pdk-validators
+ *    - Load from local paths: ./plugins/my-plugin.ts
+ *    - Validate plugin structure
+ *
+ * 2. OPERATOR REGISTRATION
+ *    - Merge plugin operators with built-ins
+ *    - Handle conflicts (plugin can override built-in)
+ *
+ * 3. LIFECYCLE HOOKS
+ *    - onLoad: Called when plugin is loaded
+ *    - Future: onRender, onValidate, etc.
+ */
+// =============================================================================
+// PLUGIN REGISTRY
+// =============================================================================
+/**
+ * Create a new plugin registry.
+ */
+export function createPluginRegistry() {
+    return {
+        plugins: [],
+        operators: new Map(),
+    };
+}
+/**
+ * Load a plugin into the registry.
+ *
+ * @param registry - The plugin registry
+ * @param plugin - The plugin to load
+ */
+export async function loadPlugin(registry, plugin) {
+    // Validate plugin structure
+    validatePlugin(plugin);
+    // Register operators
+    if (plugin.operators) {
+        for (const [name, definition] of Object.entries(plugin.operators)) {
+            registry.operators.set(name, definition);
+        }
+    }
+    // Call onLoad hook
+    if (plugin.onLoad) {
+        await plugin.onLoad();
+    }
+    // Add to registry
+    registry.plugins.push(plugin);
+}
+/**
+ * Load a plugin from a path (npm package or local file).
+ *
+ * @param registry - The plugin registry
+ * @param path - Path to the plugin
+ */
+export async function loadPluginFromPath(_registry, path) {
+    // TODO: Implement plugin loading from path
+    //
+    // IMPLEMENTATION:
+    //
+    // 1. DETERMINE PATH TYPE
+    //    - If starts with @, ., or / -> resolve as module path
+    //    - Otherwise -> resolve as npm package
+    //
+    // 2. DYNAMIC IMPORT
+    //    const module = await import(resolvedPath);
+    //    const plugin = module.default;
+    //
+    // 3. LOAD PLUGIN
+    //    await loadPlugin(registry, plugin);
+    throw new Error(`Plugin loading not implemented: ${path}`);
+}
+// =============================================================================
+// VALIDATION
+// =============================================================================
+/**
+ * Validate a plugin structure.
+ *
+ * @param plugin - The plugin to validate
+ * @throws If the plugin is invalid
+ */
+export function validatePlugin(plugin) {
+    if (!plugin || typeof plugin !== 'object') {
+        throw new Error('Plugin must be an object');
+    }
+    const p = plugin;
+    if (typeof p.name !== 'string' || p.name.length === 0) {
+        throw new Error('Plugin must have a name');
+    }
+    if (typeof p.version !== 'string') {
+        throw new Error('Plugin must have a version');
+    }
+    if (p.operators !== undefined) {
+        if (typeof p.operators !== 'object') {
+            throw new Error('Plugin operators must be an object');
+        }
+        // Validate each operator
+        for (const [name, def] of Object.entries(p.operators)) {
+            validateOperatorDefinition(name, def);
+        }
+    }
+}
+/**
+ * Validate an operator definition.
+ */
+function validateOperatorDefinition(name, def) {
+    if (!def || typeof def !== 'object') {
+        throw new Error(`Operator ${name} must be an object`);
+    }
+    const d = def;
+    if (!['comparison', 'unary', 'ai'].includes(d.type)) {
+        throw new Error(`Operator ${name} must have type: comparison, unary, or ai`);
+    }
+    if (typeof d.handler !== 'function') {
+        throw new Error(`Operator ${name} must have a handler function`);
+    }
+    if (typeof d.description !== 'string') {
+        throw new Error(`Operator ${name} must have a description`);
+    }
+}
+// =============================================================================
+// PLUGIN CREATION HELPER
+// =============================================================================
+/**
+ * Helper function for creating plugins with type safety.
+ * Re-exported from main index.ts
+ */
+export function definePlugin(plugin) {
+    // Validate at definition time
+    validatePlugin(plugin);
+    return plugin;
+}
+// =============================================================================
+// IMPLEMENTATION NOTES
+// =============================================================================
+/*
+NEXT STEPS TO IMPLEMENT:
+
+1. PATH RESOLUTION
+   - Handle npm packages (@goreal-ai/echo-pdk-foo)
+   - Handle relative paths (./foo)
+   - Handle absolute paths (/path/to/foo)
+
+2. HOT RELOADING (FUTURE)
+   For development mode, support reloading plugins without restart.
+
+3. PLUGIN DISCOVERY
+   - Scan node_modules for echo-pdk plugins
+   - Read from echo.config.yaml
+
+4. LIFECYCLE HOOKS
+   Add more hooks:
+   - onValidate: Custom validation rules
+   - onBeforeRender: Transform AST before render
+   - onAfterRender: Transform output after render
+
+5. TESTS
+   Create plugins.test.ts with tests for:
+   - Plugin validation
+   - Operator registration
+   - Path loading
+   - Lifecycle hooks
+*/
+//# sourceMappingURL=index.js.map

package/dist/plugins/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/plugins/index.ts"],"names":[],"mappings":"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"}

package/dist/renderer/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Renderer module exports
+ */
+export { render, renderTemplate } from './renderer.js';
+export type { RenderOptions } from './renderer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/renderer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/renderer/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACvD,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/renderer/index.js

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Renderer module exports
+ */
+export { render, renderTemplate } from './renderer.js';
+//# sourceMappingURL=index.js.map

package/dist/renderer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/renderer/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/dist/renderer/renderer.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview Echo Renderer - AST to text output
+ *
+ * This file implements the renderer for Echo DSL.
+ * The renderer traverses the evaluated AST and produces the final text output.
+ *
+ * By the time the renderer runs:
+ * 1. All conditions have been evaluated
+ * 2. Only the nodes that should be rendered are in the AST
+ * 3. AI judges have been resolved
+ *
+ * The renderer's job is to:
+ * 1. Walk the AST
+ * 2. For text nodes: output the text as-is
+ * 3. For variable nodes: substitute the value from context
+ * 4. Preserve whitespace (prompts are whitespace-sensitive)
+ */
+import type { ASTNode, EchoConfig, OperatorDefinition } from '../types.js';
+/**
+ * Options for the renderer.
+ */
+export interface RenderOptions {
+    /** Variable context */
+    context: Record<string, unknown>;
+    /** Echo configuration */
+    config?: EchoConfig;
+    /** Trim leading/trailing whitespace from output */
+    trim?: boolean;
+    /** Collapse multiple newlines into one */
+    collapseNewlines?: boolean;
+}
+/**
+ * Render an evaluated AST to a string.
+ *
+ * @param ast - The evaluated AST nodes
+ * @param options - Render options
+ * @returns The rendered string
+ *
+ * @example
+ * ```typescript
+ * const output = render(evaluatedAst, {
+ *   context: { name: 'Alice' },
+ *   trim: true,
+ * });
+ * ```
+ */
+export declare function render(ast: ASTNode[], options: RenderOptions): string;
+/**
+ * Full render pipeline: parse -> evaluate -> render.
+ *
+ * This is the main entry point for rendering a template.
+ *
+ * @param template - The Echo template string
+ * @param context - Variable context
+ * @param config - Echo configuration
+ * @param operators - Custom operators from plugins
+ * @returns The rendered string
+ *
+ * @example
+ * ```typescript
+ * const output = await renderTemplate(
+ *   'Hello {{name}}!',
+ *   { name: 'Alice' }
+ * );
+ * // Output: "Hello Alice!"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const template = `
+ * [#IF {{tier}} #equals(premium)]
+ *   Welcome, premium user!
+ * [ELSE]
+ *   Upgrade to premium for more features.
+ * [END IF]
+ * `;
+ *
+ * const output = await renderTemplate(template, { tier: 'premium' });
+ * // Output: "  Welcome, premium user!\n"
+ * ```
+ */
+export declare function renderTemplate(template: string, context: Record<string, unknown>, config?: EchoConfig, operators?: Map<string, OperatorDefinition>): Promise<string>;
+/**
+ * Format errors with source context for display.
+ *
+ * @param template - The original template
+ * @param errors - Parse or evaluation errors
+ * @returns Formatted error string
+ */
+export declare function formatErrors(template: string, errors: {
+    message: string;
+    location?: {
+        startLine: number;
+        startColumn: number;
+    };
+}[]): string;
+//# sourceMappingURL=renderer.d.ts.map

package/dist/renderer/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../src/renderer/renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EACV,OAAO,EAGP,UAAU,EACV,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAQrB;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,yBAAyB;IACzB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,mDAAmD;IACnD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,CAsBrE;AAiID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,GAAE,UAAe,EACvB,SAAS,GAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAa,GACrD,OAAO,CAAC,MAAM,CAAC,CAwBjB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,EAAE,GACnF,MAAM,CAwBR"}

package/dist/renderer/renderer.js

@@ -0,0 +1,243 @@
+/**
+ * @fileoverview Echo Renderer - AST to text output
+ *
+ * This file implements the renderer for Echo DSL.
+ * The renderer traverses the evaluated AST and produces the final text output.
+ *
+ * By the time the renderer runs:
+ * 1. All conditions have been evaluated
+ * 2. Only the nodes that should be rendered are in the AST
+ * 3. AI judges have been resolved
+ *
+ * The renderer's job is to:
+ * 1. Walk the AST
+ * 2. For text nodes: output the text as-is
+ * 3. For variable nodes: substitute the value from context
+ * 4. Preserve whitespace (prompts are whitespace-sensitive)
+ */
+import { parse } from '../parser/parser.js';
+import { evaluate, resolveVariable } from '../evaluator/evaluator.js';
+// =============================================================================
+// RENDERER
+// =============================================================================
+/**
+ * Render an evaluated AST to a string.
+ *
+ * @param ast - The evaluated AST nodes
+ * @param options - Render options
+ * @returns The rendered string
+ *
+ * @example
+ * ```typescript
+ * const output = render(evaluatedAst, {
+ *   context: { name: 'Alice' },
+ *   trim: true,
+ * });
+ * ```
+ */
+export function render(ast, options) {
+    const parts = [];
+    for (const node of ast) {
+        const rendered = renderNode(node, options);
+        if (rendered !== undefined) {
+            parts.push(rendered);
+        }
+    }
+    let result = parts.join('');
+    // Apply post-processing
+    if (options.collapseNewlines) {
+        result = collapseNewlines(result);
+    }
+    if (options.trim) {
+        result = result.trim();
+    }
+    return result;
+}
+/**
+ * Render a single AST node.
+ *
+ * @param node - The node to render
+ * @param options - Render options
+ * @returns The rendered string or undefined if nothing to render
+ */
+function renderNode(node, options) {
+    switch (node.type) {
+        case 'text':
+            return renderText(node);
+        case 'variable':
+            return renderVariable(node, options);
+        case 'conditional':
+            // By the time we render, conditionals should have been evaluated
+            // This shouldn't happen, but handle gracefully
+            return render(node.consequent, options);
+        case 'section':
+            // Section definitions are not rendered inline
+            // They're stored for [#INCLUDE] references
+            return undefined;
+        case 'import':
+            // Imports should be resolved before rendering
+            // If we see one here, it means it wasn't resolved
+            if (options.config?.strict) {
+                throw new Error(`Unresolved import: ${node.path}`);
+            }
+            return undefined;
+        case 'include':
+            // Includes should be resolved before rendering
+            if (options.config?.strict) {
+                throw new Error(`Unresolved include: ${node.name}`);
+            }
+            return undefined;
+        default: {
+            // Exhaustiveness check
+            const _exhaustive = node;
+            throw new Error(`Unknown node type: ${_exhaustive.type}`);
+        }
+    }
+}
+/**
+ * Render a text node.
+ */
+function renderText(node) {
+    return node.value;
+}
+/**
+ * Render a variable node.
+ *
+ * @param node - The variable node
+ * @param options - Render options
+ * @returns The variable value as string
+ */
+function renderVariable(node, options) {
+    const value = resolveVariable(node.path, options.context, {
+        strict: options.config?.strict,
+    });
+    // Handle undefined
+    if (value === undefined || value === null) {
+        // Use default value if provided
+        if (node.defaultValue !== undefined) {
+            return node.defaultValue;
+        }
+        // In strict mode, throw
+        if (options.config?.strict) {
+            throw new Error(`Undefined variable: ${node.path}`);
+        }
+        // Lenient mode: render empty string
+        return '';
+    }
+    // Convert to string
+    return stringify(value);
+}
+/**
+ * Convert a value to string for rendering.
+ *
+ * @param value - The value to stringify
+ * @returns String representation
+ */
+function stringify(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map(stringify).join(', ');
+    }
+    if (typeof value === 'object' && value !== null) {
+        return JSON.stringify(value);
+    }
+    return String(value);
+}
+// =============================================================================
+// POST-PROCESSING
+// =============================================================================
+/**
+ * Collapse multiple consecutive newlines into a maximum of two.
+ *
+ * This is useful for cleaning up output when conditionals
+ * leave empty lines.
+ */
+function collapseNewlines(text) {
+    return text.replace(/\n{3,}/g, '\n\n');
+}
+// =============================================================================
+// FULL RENDER PIPELINE
+// =============================================================================
+/**
+ * Full render pipeline: parse -> evaluate -> render.
+ *
+ * This is the main entry point for rendering a template.
+ *
+ * @param template - The Echo template string
+ * @param context - Variable context
+ * @param config - Echo configuration
+ * @param operators - Custom operators from plugins
+ * @returns The rendered string
+ *
+ * @example
+ * ```typescript
+ * const output = await renderTemplate(
+ *   'Hello {{name}}!',
+ *   { name: 'Alice' }
+ * );
+ * // Output: "Hello Alice!"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const template = `
+ * [#IF {{tier}} #equals(premium)]
+ *   Welcome, premium user!
+ * [ELSE]
+ *   Upgrade to premium for more features.
+ * [END IF]
+ * `;
+ *
+ * const output = await renderTemplate(template, { tier: 'premium' });
+ * // Output: "  Welcome, premium user!\n"
+ * ```
+ */
+export async function renderTemplate(template, context, config = {}, operators = new Map()) {
+    // Step 1: Parse the template to AST
+    const parseResult = parse(template);
+    if (!parseResult.success || !parseResult.ast) {
+        const formattedErrors = formatErrors(template, parseResult.errors);
+        throw new Error(`Parse error:\n${formattedErrors}`);
+    }
+    // Step 2: Evaluate the AST
+    const { ast: evaluatedAst } = await evaluate(parseResult.ast, context, config, operators);
+    // Step 3: Render the evaluated AST
+    return render(evaluatedAst, {
+        context,
+        config,
+        trim: false, // Preserve whitespace by default
+        collapseNewlines: true, // Clean up empty lines from conditionals
+    });
+}
+/**
+ * Format errors with source context for display.
+ *
+ * @param template - The original template
+ * @param errors - Parse or evaluation errors
+ * @returns Formatted error string
+ */
+export function formatErrors(template, errors) {
+    const lines = template.split('\n');
+    const formatted = [];
+    for (const error of errors) {
+        formatted.push(`Error: ${error.message}`);
+        if (error.location) {
+            const { startLine, startColumn } = error.location;
+            const lineIndex = startLine - 1;
+            if (lineIndex >= 0 && lineIndex < lines.length) {
+                const sourceLine = lines[lineIndex];
+                const pointer = ' '.repeat(startColumn - 1) + '^';
+                formatted.push(`  ${startLine} | ${sourceLine}`);
+                formatted.push(`    | ${pointer}`);
+            }
+        }
+        formatted.push('');
+    }
+    return formatted.join('\n');
+}
+//# sourceMappingURL=renderer.js.map

package/dist/renderer/renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.js","sourceRoot":"","sources":["../../src/renderer/renderer.ts"],"names":[],"mappings":"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"}