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

package/README.md

@@ -0,0 +1,130 @@
+# 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
+
+## 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/issues](https://github.com/elaraai/East/issues)
+- **Email**: support@elara.ai
+
+---
+
+*Developed by [Elara AI Pty Ltd](https://elaraai.com/) - Powering the computational layer of AI-driven business optimization.*

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":"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"}

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"}