@elaraai/east-node-cli 0.0.1-beta.10

package/README.md

@@ -0,0 +1,157 @@
+# East Node CLI
+
+> Command-line interface for running East IR programs with Node.js
+
+[![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE.md)
+[![Node Version](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org)
+
+**East Node CLI** provides a command-line interface for executing compiled [East](https://github.com/elaraai/East) IR programs using Node.js platform implementations.
+
+## Installation
+
+```bash
+# Install the CLI
+npm install -g @elaraai/east-node-cli
+
+# Install platform packages (required)
+npm install @elaraai/east-node-std
+npm install @elaraai/east-node-io  # if using I/O functions
+```
+
+## Usage
+
+### Running Programs
+
+```bash
+# Run with standard platform
+east-node run ./program.beast2 -p @elaraai/east-node-std
+
+# Run with multiple platforms
+east-node run ./db-query.beast2 \
+    -p @elaraai/east-node-std \
+    -p @elaraai/east-node-io
+
+# Run with input files
+east-node run ./transform.beast2 \
+    -p @elaraai/east-node-std \
+    -i input.json \
+    -i config.east
+
+# Run with output file
+east-node run ./process.beast2 \
+    -p @elaraai/east-node-std \
+    -i input.beast2 \
+    -o result.json
+
+# Verbose mode
+east-node run ./program.beast2 -p @elaraai/east-node-std -v
+```
+
+### Version Information
+
+```bash
+# Show CLI version
+east-node version
+
+# Show CLI and platform versions
+east-node version -p @elaraai/east-node-std -p @elaraai/east-node-io
+```
+
+## CLI Reference
+
+### `east-node run`
+
+Execute an East IR program.
+
+```
+east-node run <ir_file> [options]
+
+Arguments:
+  ir_file                    Path to IR file (.beast2, .beast, .east, or .json)
+
+Options:
+  -p, --package <package>    Platform package to load (can be repeated)
+  -i, --input <file>         Input data file (can be repeated)
+  -o, --output <file>        Output file path for result
+  -v, --verbose              Enable verbose output
+  -h, --help                 Display help
+```
+
+### `east-node version`
+
+Show version information.
+
+```
+east-node version [options]
+
+Options:
+  -p, --package <package>    Platform package to check (can be repeated)
+```
+
+## Supported File Formats
+
+| Extension | Format |
+|-----------|--------|
+| `.beast2`, `.beast` | Binary East format |
+| `.east` | Text East format |
+| `.json` | JSON format |
+
+## Platform Packages
+
+Platform packages provide the runtime implementations for East platform functions:
+
+- **[@elaraai/east-node-std](https://www.npmjs.com/package/@elaraai/east-node-std)** - Standard platform (console, filesystem, crypto, time, etc.)
+- **[@elaraai/east-node-io](https://www.npmjs.com/package/@elaraai/east-node-io)** - I/O platform (SQL, S3, FTP, Redis, MongoDB, etc.)
+
+## Creating Platform Packages
+
+Any npm package can provide platform functions by following this convention:
+
+1. Export a `./platform` subpath that default-exports `PlatformFunction[]`
+2. Export `./package.json` for version discovery
+
+See the [design document](../../docs/east-node-cli-design.md) for details.
+
+## License
+
+Dual-licensed:
+- **Open Source**: [AGPL-3.0](LICENSE.md) - Free for open source use
+- **Commercial**: Available for proprietary use - contact support@elara.ai
+
+
+### Ecosystem
+
+- **[East Node](https://github.com/elaraai/east-node)**: Node.js platform functions for I/O, databases, and system operations. Connect East programs to filesystems, SQL/NoSQL databases, cloud storage, and network services.
+  - [@elaraai/east-node-std](https://www.npmjs.com/package/@elaraai/east-node-std): Filesystem, console, HTTP fetch, crypto, random distributions, timestamps
+  - [@elaraai/east-node-io](https://www.npmjs.com/package/@elaraai/east-node-io): SQLite, PostgreSQL, MySQL, MongoDB, S3, FTP, SFTP
+  - [@elaraai/east-node-cli](https://www.npmjs.com/package/@elaraai/east-node-cli): CLI for running East IR programs in Node.js
+
+- **[East Python](https://github.com/elaraai/east-py)**: Python runtime and platform functions for data science and machine learning. Execute East programs with access to optimization solvers, gradient boosting, neural networks, and model explainability.
+  - [@elaraai/east-py-datascience](https://www.npmjs.com/package/@elaraai/east-py-datascience): TypeScript types for optimization, gradient boosting, neural networks, explainability
+
+- **[East UI](https://github.com/elaraai/east-ui)**: East types and expressions for building dashboards and interactive layouts. Define UIs as data structures that render consistently across React, web, and other environments.
+  - [@elaraai/east-ui](https://www.npmjs.com/package/@elaraai/east-ui): 50+ typed UI components for layouts, forms, charts, tables, dialogs
+  - [@elaraai/east-ui-components](https://www.npmjs.com/package/@elaraai/east-ui-components): React renderer with Chakra UI styling
+
+- **[e3 - East Execution Engine](https://github.com/elaraai/e3)**: Durable execution engine for running East pipelines at scale. Features Git-like content-addressable storage, automatic memoization, task queuing, and real-time monitoring.
+  - [@elaraai/e3](https://www.npmjs.com/package/@elaraai/e3): SDK for authoring e3 packages with typed tasks and pipelines
+  - [@elaraai/e3-core](https://www.npmjs.com/package/@elaraai/e3-core): Git-like object store, task queue, result caching
+  - [@elaraai/e3-types](https://www.npmjs.com/package/@elaraai/e3-types): Shared type definitions for e3 packages
+  - [@elaraai/e3-cli](https://www.npmjs.com/package/@elaraai/e3-cli): `e3 init`, `e3 run`, `e3 logs` commands for managing and monitoring tasks
+  - [@elaraai/e3-api-client](https://www.npmjs.com/package/@elaraai/e3-api-client): HTTP client for remote e3 servers
+  - [@elaraai/e3-api-server](https://www.npmjs.com/package/@elaraai/e3-api-server): REST API server for e3 repositories
+
+## Links
+
+- **Website**: [https://elaraai.com/](https://elaraai.com/)
+- **East Repository**: [https://github.com/elaraai/East](https://github.com/elaraai/East)
+- **Issues**: [https://github.com/elaraai/east-node/issues](https://github.com/elaraai/east-node/issues)
+- **Email**: support@elara.ai
+
+## About Elara
+
+East is developed by [Elara AI Pty Ltd](https://elaraai.com/), an AI-powered platform that creates economic digital twins of businesses that optimize performance. Elara combines business objectives, decisions and data to help organizations make data-driven decisions across operations, purchasing, sales and customer engagement, and project and investment planning. East powers the computational layer of Elara solutions, enabling the expression of complex business logic and data in a simple, type-safe and portable language.
+
+---
+
+*Developed by [Elara AI Pty Ltd](https://elaraai.com/)*

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+export declare function main(): void;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuFH,wBAAgB,IAAI,IAAI,IAAI,CAyB3B"}

package/dist/cli.js

@@ -0,0 +1,85 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { Command } from 'commander';
+import { createRequire } from 'module';
+import { loadPlatforms, loadPlatformWithMetadata } from './loader.js';
+import { runProgram } from './runner.js';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+async function cmdRun(irFile, options) {
+    const packages = options.package ?? [];
+    if (packages.length === 0) {
+        console.error('Error: At least one platform package is required.');
+        console.error('Example: east-node run program.beast2 -p @elaraai/east-node-std');
+        process.exit(1);
+    }
+    try {
+        if (options.verbose) {
+            console.error(`Loading ${packages.length} platform package(s)...`);
+        }
+        const platformFns = await loadPlatforms(packages);
+        if (options.verbose) {
+            console.error(`Loaded ${platformFns.length} platform function(s)`);
+            console.error(`Running: ${irFile}`);
+        }
+        const result = await runProgram(irFile, platformFns, options.input ?? [], options.output, options.verbose ?? false);
+        // If no output file specified, print result to stdout
+        if (!options.output && result !== undefined && result !== null) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+}
+async function cmdVersion(options) {
+    console.log(`${pkg.name} ${pkg.version}`);
+    // Try to get east version
+    try {
+        const eastPkg = require('@elaraai/east/package.json');
+        console.log(`@elaraai/east ${eastPkg.version}`);
+    }
+    catch {
+        // east package not found or no package.json export
+    }
+    const packages = options.package ?? [];
+    if (packages.length > 0) {
+        console.log('');
+        console.log('Platforms:');
+        for (const pkgName of packages) {
+            try {
+                const meta = await loadPlatformWithMetadata(pkgName);
+                console.log(`  ${meta.name} ${meta.version} (${meta.fns.length} platform functions)`);
+            }
+            catch (err) {
+                console.log(`  ${pkgName}: ${err.message}`);
+            }
+        }
+    }
+}
+export function main() {
+    const program = new Command();
+    program
+        .name('east-node')
+        .description('Run East IR programs with Node.js platform functions')
+        .version(pkg.version);
+    program
+        .command('run')
+        .description('Run an East IR program')
+        .argument('<ir_file>', 'Path to IR file (.beast2, .beast, .east, or .json)')
+        .option('-p, --package <package...>', 'Platform packages to load (can be repeated)')
+        .option('-i, --input <file...>', 'Input data files (order matches function parameters)')
+        .option('-o, --output <file>', 'Output file path for result')
+        .option('-v, --verbose', 'Enable verbose output')
+        .action(cmdRun);
+    program
+        .command('version')
+        .description('Show version information')
+        .option('-p, --package <package...>', 'Platform packages to check')
+        .action(cmdVersion);
+    program.parse();
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { main } from './cli.js';
+export declare const __version__: string;
+export { main };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AASH,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAKhC,eAAO,MAAM,WAAW,QAAc,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * East Node CLI - Command-line interface for running East IR programs.
+ *
+ * @packageDocumentation
+ */
+import { createRequire } from 'module';
+import { main } from './cli.js';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+export const __version__ = pkg.version;
+export { main };
+main();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAEhC,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,CAAwB,CAAC;AAE9D,MAAM,CAAC,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,CAAC;AAEhB,IAAI,EAAE,CAAC"}

package/dist/loader.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { type EastTypeValue } from '@elaraai/east';
+import type { PlatformFunction, IR, ValueTypeOf } from '@elaraai/east/internal';
+/**
+ * Metadata about a loaded platform package.
+ */
+export interface PlatformMetadata {
+    /** Package name */
+    name: string;
+    /** Package version */
+    version: string;
+    /** Platform functions exported by the package */
+    fns: PlatformFunction[];
+}
+/**
+ * Loads platform functions from a package.
+ *
+ * The package must export a `./platform` subpath with a default export
+ * of `PlatformFunction[]`.
+ *
+ * @param packageName - The npm package name (e.g., "@elaraai/east-node-std")
+ * @returns Array of platform functions
+ * @throws Error if package cannot be loaded or doesn't follow convention
+ */
+export declare function loadPlatform(packageName: string): Promise<PlatformFunction[]>;
+/**
+ * Loads platform functions with metadata from a package.
+ *
+ * @param packageName - The npm package name
+ * @returns Platform metadata including name, version, and functions
+ */
+export declare function loadPlatformWithMetadata(packageName: string): Promise<PlatformMetadata>;
+/**
+ * Loads platform functions from multiple packages.
+ *
+ * @param packageNames - Array of npm package names
+ * @returns Combined array of all platform functions
+ */
+export declare function loadPlatforms(packageNames: string[]): Promise<PlatformFunction[]>;
+/**
+ * Loads an IR file and returns the parsed IR.
+ *
+ * Supports the following formats:
+ * - `.beast2`, `.beast` - Binary East format (self-describing)
+ * - `.east` - Text East format
+ * - `.json` - JSON format
+ *
+ * @param filePath - Path to the IR file
+ * @returns Parsed IR (FunctionIR or AsyncFunctionIR)
+ */
+export declare function loadIR(filePath: string): ValueTypeOf<IR>;
+/**
+ * Loads input data from a file.
+ *
+ * The type of the input must be provided to decode correctly.
+ *
+ * @param filePath - Path to the input file
+ * @param type - The expected East type of the input
+ * @returns Decoded value
+ */
+export declare function loadInput(filePath: string, type: EastTypeValue): unknown;
+//# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAMH,KAAK,aAAa,EACrB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,gBAAgB,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAahF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,GAAG,EAAE,gBAAgB,EAAE,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAoCnF;AAED;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgB7F;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CASvF;AAmDD;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC,CAgCxD;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAoBxE"}

package/dist/loader.js

@@ -0,0 +1,200 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { readFileSync } from 'fs';
+import { createRequire } from 'module';
+import { extname } from 'path';
+import { IRType, decodeBeast2For, decodeBeast2, decodeEastFor, decodeJSONFor, } from '@elaraai/east';
+const require = createRequire(import.meta.url);
+// Decoder for IR from beast2 format (self-describing)
+const decodeIRFromBeast2 = decodeBeast2For(IRType);
+// Decoder for IR from east text format
+const decodeIRFromEast = decodeEastFor(IRType);
+// Decoder for IR from JSON format
+const decodeIRFromJSON = decodeJSONFor(IRType);
+/**
+ * Loads platform functions from a package.
+ *
+ * The package must export a `./platform` subpath with a default export
+ * of `PlatformFunction[]`.
+ *
+ * @param packageName - The npm package name (e.g., "@elaraai/east-node-std")
+ * @returns Array of platform functions
+ * @throws Error if package cannot be loaded or doesn't follow convention
+ */
+export async function loadPlatform(packageName) {
+    try {
+        // Dynamic import of the platform subpath
+        const platformModule = await import(`${packageName}/platform`);
+        const fns = platformModule.default;
+        // Validate the export
+        if (!Array.isArray(fns)) {
+            throw new Error(`Package "${packageName}" does not export a valid platform. ` +
+                `Expected default export of PlatformFunction[], got ${typeof fns}.`);
+        }
+        // Validate each platform function structurally
+        for (let i = 0; i < fns.length; i++) {
+            const fn = fns[i];
+            if (!isValidPlatformFunction(fn)) {
+                throw new Error(`Package "${packageName}" exports invalid platform function at index ${i}. ` +
+                    `Expected { name: string, inputs: EastTypeValue[], output: EastTypeValue, type: 'sync' | 'async', fn: Function }.`);
+            }
+        }
+        return fns;
+    }
+    catch (err) {
+        if (err.code === 'ERR_MODULE_NOT_FOUND' ||
+            err.code === 'MODULE_NOT_FOUND') {
+            throw new Error(`Could not load platform package "${packageName}". ` +
+                `Make sure it is installed: npm install ${packageName}`);
+        }
+        throw err;
+    }
+}
+/**
+ * Loads platform functions with metadata from a package.
+ *
+ * @param packageName - The npm package name
+ * @returns Platform metadata including name, version, and functions
+ */
+export async function loadPlatformWithMetadata(packageName) {
+    const fns = await loadPlatform(packageName);
+    // Load package.json for version info
+    let name = packageName;
+    let version = 'unknown';
+    try {
+        const pkgJson = require(`${packageName}/package.json`);
+        name = pkgJson.name ?? packageName;
+        version = pkgJson.version ?? 'unknown';
+    }
+    catch {
+        // Package doesn't export package.json, use defaults
+    }
+    return { name, version, fns };
+}
+/**
+ * Loads platform functions from multiple packages.
+ *
+ * @param packageNames - Array of npm package names
+ * @returns Combined array of all platform functions
+ */
+export async function loadPlatforms(packageNames) {
+    const allFns = [];
+    for (const pkgName of packageNames) {
+        const fns = await loadPlatform(pkgName);
+        allFns.push(...fns);
+    }
+    return allFns;
+}
+/**
+ * Validates that a value looks like a PlatformFunction.
+ * We use structural validation since PlatformFunction contains JS functions.
+ */
+function isValidPlatformFunction(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const fn = value;
+    // Check required string fields
+    if (typeof fn.name !== 'string')
+        return false;
+    if (fn.type !== 'sync' && fn.type !== 'async')
+        return false;
+    // Check fn is a function
+    if (typeof fn.fn !== 'function')
+        return false;
+    // Check inputs is an array
+    if (!Array.isArray(fn.inputs))
+        return false;
+    // Check output exists (we trust the type structure)
+    if (fn.output === undefined)
+        return false;
+    return true;
+}
+/**
+ * Determines the file format from extension.
+ */
+function getFileFormat(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    switch (ext) {
+        case '.beast2':
+        case '.beast':
+            return 'beast2';
+        case '.east':
+            return 'east';
+        case '.json':
+            return 'json';
+        default:
+            throw new Error(`Unsupported file extension "${ext}". ` +
+                `Supported extensions: .beast2, .beast, .east, .json`);
+    }
+}
+/**
+ * Loads an IR file and returns the parsed IR.
+ *
+ * Supports the following formats:
+ * - `.beast2`, `.beast` - Binary East format (self-describing)
+ * - `.east` - Text East format
+ * - `.json` - JSON format
+ *
+ * @param filePath - Path to the IR file
+ * @returns Parsed IR (FunctionIR or AsyncFunctionIR)
+ */
+export function loadIR(filePath) {
+    const format = getFileFormat(filePath);
+    const data = readFileSync(filePath);
+    let ir;
+    switch (format) {
+        case 'beast2': {
+            // Beast2 is self-describing, includes type info in the file
+            ir = decodeIRFromBeast2(data);
+            break;
+        }
+        case 'east': {
+            // East text format, decode using IR type
+            ir = decodeIRFromEast(data);
+            break;
+        }
+        case 'json': {
+            // JSON format, decode using IR type
+            ir = decodeIRFromJSON(data);
+            break;
+        }
+    }
+    // Validate that the IR is a function
+    if (ir.type !== 'Function' && ir.type !== 'AsyncFunction') {
+        throw new Error(`IR file must contain a function or async function, got "${ir.type}"`);
+    }
+    return ir;
+}
+/**
+ * Loads input data from a file.
+ *
+ * The type of the input must be provided to decode correctly.
+ *
+ * @param filePath - Path to the input file
+ * @param type - The expected East type of the input
+ * @returns Decoded value
+ */
+export function loadInput(filePath, type) {
+    const format = getFileFormat(filePath);
+    const data = readFileSync(filePath);
+    switch (format) {
+        case 'beast2': {
+            // For inputs, we use decodeBeast2 which is self-describing
+            // This allows loading data without knowing the exact type
+            const result = decodeBeast2(data);
+            return result.value;
+        }
+        case 'east': {
+            const decoder = decodeEastFor(type);
+            return decoder(data);
+        }
+        case 'json': {
+            const decoder = decodeJSONFor(type);
+            return decoder(data);
+        }
+    }
+}
+//# sourceMappingURL=loader.js.map

package/dist/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/B,OAAO,EACH,MAAM,EACN,eAAe,EACf,YAAY,EACZ,aAAa,EACb,aAAa,GAEhB,MAAM,eAAe,CAAC;AAGvB,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE/C,sDAAsD;AACtD,MAAM,kBAAkB,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;AAEnD,uCAAuC;AACvC,MAAM,gBAAgB,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;AAE/C,kCAAkC;AAClC,MAAM,gBAAgB,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;AAc/C;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,WAAmB;IAClD,IAAI,CAAC;QACD,yCAAyC;QACzC,MAAM,cAAc,GAAG,MAAM,MAAM,CAAC,GAAG,WAAW,WAAW,CAAC,CAAC;QAC/D,MAAM,GAAG,GAAG,cAAc,CAAC,OAAO,CAAC;QAEnC,sBAAsB;QACtB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CACX,YAAY,WAAW,sCAAsC;gBAC7D,sDAAsD,OAAO,GAAG,GAAG,CACtE,CAAC;QACN,CAAC;QAED,+CAA+C;QAC/C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAClC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;YAClB,IAAI,CAAC,uBAAuB,CAAC,EAAE,CAAC,EAAE,CAAC;gBAC/B,MAAM,IAAI,KAAK,CACX,YAAY,WAAW,gDAAgD,CAAC,IAAI;oBAC5E,kHAAkH,CACrH,CAAC;YACN,CAAC;QACL,CAAC;QAED,OAAO,GAAG,CAAC;IACf,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACX,IAAK,GAA6B,CAAC,IAAI,KAAK,sBAAsB;YAC7D,GAA6B,CAAC,IAAI,KAAK,kBAAkB,EAAE,CAAC;YAC7D,MAAM,IAAI,KAAK,CACX,oCAAoC,WAAW,KAAK;gBACpD,0CAA0C,WAAW,EAAE,CAC1D,CAAC;QACN,CAAC;QACD,MAAM,GAAG,CAAC;IACd,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,WAAmB;IAC9D,MAAM,GAAG,GAAG,MAAM,YAAY,CAAC,WAAW,CAAC,CAAC;IAE5C,qCAAqC;IACrC,IAAI,IAAI,GAAG,WAAW,CAAC;IACvB,IAAI,OAAO,GAAG,SAAS,CAAC;IAExB,IAAI,CAAC;QACD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,WAAW,eAAe,CAAwC,CAAC;QAC9F,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,WAAW,CAAC;QACnC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,SAAS,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACL,oDAAoD;IACxD,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,YAAsB;IACtD,MAAM,MAAM,GAAuB,EAAE,CAAC;IAEtC,KAAK,MAAM,OAAO,IAAI,YAAY,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC,CAAC;QACxC,MAAM,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;IACxB,CAAC;IAED,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,SAAS,uBAAuB,CAAC,KAAc;IAC3C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,MAAM,EAAE,GAAG,KAAgC,CAAC;IAE5C,+BAA+B;IAC/B,IAAI,OAAO,EAAE,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9C,IAAI,EAAE,CAAC,IAAI,KAAK,MAAM,IAAI,EAAE,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,KAAK,CAAC;IAE5D,yBAAyB;IACzB,IAAI,OAAO,EAAE,CAAC,EAAE,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IAE9C,2BAA2B;IAC3B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IAE5C,oDAAoD;IACpD,IAAI,EAAE,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAE1C,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,SAAS,aAAa,CAAC,QAAgB;IACnC,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;IAE5C,QAAQ,GAAG,EAAE,CAAC;QACV,KAAK,SAAS,CAAC;QACf,KAAK,QAAQ;YACT,OAAO,QAAQ,CAAC;QACpB,KAAK,OAAO;YACR,OAAO,MAAM,CAAC;QAClB,KAAK,OAAO;YACR,OAAO,MAAM,CAAC;QAClB;YACI,MAAM,IAAI,KAAK,CACX,+BAA+B,GAAG,KAAK;gBACvC,qDAAqD,CACxD,CAAC;IACV,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,MAAM,CAAC,QAAgB;IACnC,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IAEpC,IAAI,EAAmB,CAAC;IAExB,QAAQ,MAAM,EAAE,CAAC;QACb,KAAK,QAAQ,CAAC,CAAC,CAAC;YACZ,4DAA4D;YAC5D,EAAE,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;YAC9B,MAAM;QACV,CAAC;QACD,KAAK,MAAM,CAAC,CAAC,CAAC;YACV,yCAAyC;YACzC,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;YAC5B,MAAM;QACV,CAAC;QACD,KAAK,MAAM,CAAC,CAAC,CAAC;YACV,oCAAoC;YACpC,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;YAC5B,MAAM;QACV,CAAC;IACL,CAAC;IAED,qCAAqC;IACrC,IAAI,EAAE,CAAC,IAAI,KAAK,UAAU,IAAI,EAAE,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CACX,2DAA2D,EAAE,CAAC,IAAI,GAAG,CACxE,CAAC;IACN,CAAC;IAED,OAAO,EAAE,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,IAAmB;IAC3D,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IAEpC,QAAQ,MAAM,EAAE,CAAC;QACb,KAAK,QAAQ,CAAC,CAAC,CAAC;YACZ,2DAA2D;YAC3D,0DAA0D;YAC1D,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;YAClC,OAAO,MAAM,CAAC,KAAK,CAAC;QACxB,CAAC;QACD,KAAK,MAAM,CAAC,CAAC,CAAC;YACV,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;YACpC,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC;QACD,KAAK,MAAM,CAAC,CAAC,CAAC;YACV,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;YACpC,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC;IACL,CAAC;AACL,CAAC"}

package/dist/runner.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import type { PlatformFunction } from '@elaraai/east/internal';
+/**
+ * Runs an East IR program.
+ *
+ * @param irPath - Path to the IR file
+ * @param platformFns - Platform functions to use for execution
+ * @param inputPaths - Paths to input data files (order matches function parameters)
+ * @param outputPath - Optional path to write the result
+ * @param verbose - Enable verbose logging
+ * @returns The result of execution (or undefined if written to file)
+ */
+export declare function runProgram(irPath: string, platformFns: PlatformFunction[], inputPaths: string[], outputPath?: string, verbose?: boolean): Promise<unknown>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,OAAO,KAAK,EAAE,gBAAgB,EAA4C,MAAM,wBAAwB,CAAC;AAGzG;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAC5B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,gBAAgB,EAAE,EAC/B,UAAU,EAAE,MAAM,EAAE,EACpB,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,GAAE,OAAe,GACzB,OAAO,CAAC,OAAO,CAAC,CAsElB"}