@objectstack/service-automation 3.0.7

package/src/engine.ts

@@ -0,0 +1,257 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { FlowParsed, FlowNodeParsed } from '@objectstack/spec/automation';
+import type { AutomationContext, AutomationResult, IAutomationService } from '@objectstack/spec/contracts';
+import type { Logger } from '@objectstack/spec/contracts';
+import { FlowSchema } from '@objectstack/spec/automation';
+
+// ─── Node Executor Interface (Plugin Extension Point) ───────────────
+
+/**
+ * Each node type corresponds to a NodeExecutor.
+ * Third-party plugins only need to implement this interface and register
+ * it with the engine to extend automation capabilities.
+ */
+export interface NodeExecutor {
+    /** Corresponds to FlowNodeAction enum value */
+    readonly type: string;
+
+    /**
+     * Execute a node
+     * @param node - Current node definition
+     * @param variables - Flow variable context (read/write)
+     * @param context - Trigger context
+     * @returns Execution result (may include output data, branch conditions, etc.)
+     */
+    execute(
+        node: FlowNodeParsed,
+        variables: Map<string, unknown>,
+        context: AutomationContext,
+    ): Promise<NodeExecutionResult>;
+}
+
+export interface NodeExecutionResult {
+    success: boolean;
+    output?: Record<string, unknown>;
+    error?: string;
+    /** Used by decision nodes — returns the selected branch label */
+    branchLabel?: string;
+}
+
+// ─── Trigger Interface (Plugin Extension Point) ─────────────────────
+
+/**
+ * Trigger interface. Schedule/Event/API triggers are registered via plugins.
+ */
+export interface FlowTrigger {
+    readonly type: string;
+    start(flowName: string, callback: (ctx: AutomationContext) => Promise<void>): void;
+    stop(flowName: string): void;
+}
+
+// ─── Core Automation Engine ─────────────────────────────────────────
+
+export class AutomationEngine implements IAutomationService {
+    private flows = new Map<string, FlowParsed>();
+    private nodeExecutors = new Map<string, NodeExecutor>();
+    private triggers = new Map<string, FlowTrigger>();
+    private logger: Logger;
+
+    constructor(logger: Logger) {
+        this.logger = logger;
+    }
+
+    // ── Plugin Extension API ──────────────────────────────
+
+    /** Register a node executor (called by plugins) */
+    registerNodeExecutor(executor: NodeExecutor): void {
+        if (this.nodeExecutors.has(executor.type)) {
+            this.logger.warn(`Node executor '${executor.type}' replaced`);
+        }
+        this.nodeExecutors.set(executor.type, executor);
+        this.logger.info(`Node executor registered: ${executor.type}`);
+    }
+
+    /** Unregister a node executor (hot-unplug) */
+    unregisterNodeExecutor(type: string): void {
+        this.nodeExecutors.delete(type);
+        this.logger.info(`Node executor unregistered: ${type}`);
+    }
+
+    /** Register a trigger (called by plugins) */
+    registerTrigger(trigger: FlowTrigger): void {
+        this.triggers.set(trigger.type, trigger);
+        this.logger.info(`Trigger registered: ${trigger.type}`);
+    }
+
+    /** Unregister a trigger (hot-unplug) */
+    unregisterTrigger(type: string): void {
+        this.triggers.delete(type);
+        this.logger.info(`Trigger unregistered: ${type}`);
+    }
+
+    /** Get all registered node types */
+    getRegisteredNodeTypes(): string[] {
+        return [...this.nodeExecutors.keys()];
+    }
+
+    /** Get all registered trigger types */
+    getRegisteredTriggerTypes(): string[] {
+        return [...this.triggers.keys()];
+    }
+
+    // ── IAutomationService Contract Implementation ────────
+
+    registerFlow(name: string, definition: unknown): void {
+        const parsed = FlowSchema.parse(definition);
+        this.flows.set(name, parsed);
+        this.logger.info(`Flow registered: ${name}`);
+    }
+
+    unregisterFlow(name: string): void {
+        this.flows.delete(name);
+        this.logger.info(`Flow unregistered: ${name}`);
+    }
+
+    async listFlows(): Promise<string[]> {
+        return [...this.flows.keys()];
+    }
+
+    async execute(flowName: string, context?: AutomationContext): Promise<AutomationResult> {
+        const startTime = Date.now();
+        const flow = this.flows.get(flowName);
+
+        if (!flow) {
+            return { success: false, error: `Flow '${flowName}' not found` };
+        }
+
+        // Initialize variable context
+        const variables = new Map<string, unknown>();
+        if (flow.variables) {
+            for (const v of flow.variables) {
+                if (v.isInput && context?.params?.[v.name] !== undefined) {
+                    variables.set(v.name, context.params[v.name]);
+                }
+            }
+        }
+        // Inject trigger record
+        if (context?.record) {
+            variables.set('$record', context.record);
+        }
+
+        try {
+            // Find the start node
+            const startNode = flow.nodes.find(n => n.type === 'start');
+            if (!startNode) {
+                return { success: false, error: 'Flow has no start node' };
+            }
+
+            // DAG traversal execution
+            await this.executeNode(startNode, flow, variables, context ?? {});
+
+            // Collect output variables
+            const output: Record<string, unknown> = {};
+            if (flow.variables) {
+                for (const v of flow.variables) {
+                    if (v.isOutput) {
+                        output[v.name] = variables.get(v.name);
+                    }
+                }
+            }
+
+            return {
+                success: true,
+                output,
+                durationMs: Date.now() - startTime,
+            };
+        } catch (err: unknown) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+
+            // Error handling strategy
+            if (flow.errorHandling?.strategy === 'retry') {
+                return this.retryExecution(flowName, context, startTime, flow.errorHandling);
+            }
+            return {
+                success: false,
+                error: errorMessage,
+                durationMs: Date.now() - startTime,
+            };
+        }
+    }
+
+    // ── DAG Traversal Core ──────────────────────────────────
+
+    private async executeNode(
+        node: FlowNodeParsed,
+        flow: FlowParsed,
+        variables: Map<string, unknown>,
+        context: AutomationContext,
+    ): Promise<void> {
+        if (node.type === 'end') return;
+
+        // Find executor
+        const executor = this.nodeExecutors.get(node.type);
+        if (!executor) {
+            // start node without executor is fine — just skip
+            if (node.type !== 'start') {
+                throw new Error(`No executor registered for node type '${node.type}'`);
+            }
+        } else {
+            // Execute node
+            const result = await executor.execute(node, variables, context);
+            if (!result.success) {
+                throw new Error(`Node '${node.id}' failed: ${result.error}`);
+            }
+            // Write back output variables
+            if (result.output) {
+                for (const [key, value] of Object.entries(result.output)) {
+                    variables.set(`${node.id}.${key}`, value);
+                }
+            }
+        }
+
+        // Find next nodes (filter by edge conditions)
+        const outEdges = flow.edges.filter(e => e.source === node.id);
+        for (const edge of outEdges) {
+            if (edge.condition && !this.evaluateCondition(edge.condition, variables)) {
+                continue;
+            }
+            const nextNode = flow.nodes.find(n => n.id === edge.target);
+            if (nextNode) {
+                await this.executeNode(nextNode, flow, variables, context);
+            }
+        }
+    }
+
+    private evaluateCondition(expression: string, variables: Map<string, unknown>): boolean {
+        // MVP: Simple template replacement + expression evaluation.
+        // Flow definitions are authored by trusted developers/admins.
+        // TODO: Replace with safe expression evaluator (e.g., jexl) for production.
+        let resolved = expression;
+        for (const [key, value] of variables) {
+            resolved = resolved.split(`{${key}}`).join(String(value));
+        }
+        try {
+            return new Function(`return (${resolved})`)() as boolean;
+        } catch {
+            return false;
+        }
+    }
+
+    private async retryExecution(
+        flowName: string,
+        context: AutomationContext | undefined,
+        startTime: number,
+        errorHandling: { maxRetries?: number; retryDelayMs?: number },
+    ): Promise<AutomationResult> {
+        const maxRetries = errorHandling.maxRetries ?? 3;
+        const delay = errorHandling.retryDelayMs ?? 1000;
+
+        for (let i = 0; i < maxRetries; i++) {
+            await new Promise(r => setTimeout(r, delay));
+            const result = await this.execute(flowName, context);
+            if (result.success) return result;
+        }
+        return { success: false, error: 'Max retries exceeded', durationMs: Date.now() - startTime };
+    }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+// Core engine
+export { AutomationEngine } from './engine.js';
+export type { NodeExecutor, NodeExecutionResult, FlowTrigger } from './engine.js';
+
+// Kernel plugin
+export { AutomationServicePlugin } from './plugin.js';
+export type { AutomationServicePluginOptions } from './plugin.js';
+
+// Node plugins
+export { CrudNodesPlugin } from './plugins/crud-nodes-plugin.js';
+export { LogicNodesPlugin } from './plugins/logic-nodes-plugin.js';
+export { HttpConnectorPlugin } from './plugins/http-connector-plugin.js';

package/src/plugin.ts

@@ -0,0 +1,80 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Plugin, PluginContext } from '@objectstack/core';
+import { AutomationEngine } from './engine.js';
+
+/**
+ * Configuration options for the AutomationServicePlugin.
+ */
+export interface AutomationServicePluginOptions {
+    /** Enable debug logging for flow execution */
+    debug?: boolean;
+}
+
+/**
+ * AutomationServicePlugin — Core engine plugin
+ *
+ * Responsibilities:
+ * 1. init phase: Create engine instance, register as 'automation' service
+ * 2. start phase: Trigger 'automation:ready' hook for node plugin registration
+ * 3. destroy phase: Clean up resources
+ *
+ * Does NOT implement any specific nodes — nodes are registered by other plugins
+ * via the engine's extension API.
+ *
+ * @example
+ * ```ts
+ * import { LiteKernel } from '@objectstack/core';
+ * import { AutomationServicePlugin } from '@objectstack/service-automation';
+ *
+ * const kernel = new LiteKernel();
+ * kernel.use(new AutomationServicePlugin());
+ * await kernel.bootstrap();
+ *
+ * const automation = kernel.getService('automation');
+ * ```
+ */
+export class AutomationServicePlugin implements Plugin {
+    name = 'com.objectstack.service-automation';
+    version = '1.0.0';
+    type = 'standard' as const;
+    dependencies: string[] = [];
+
+    private engine?: AutomationEngine;
+    private readonly options: AutomationServicePluginOptions;
+
+    constructor(options: AutomationServicePluginOptions = {}) {
+        this.options = options;
+    }
+
+    async init(ctx: PluginContext): Promise<void> {
+        this.engine = new AutomationEngine(ctx.logger);
+
+        // Register as global service — other plugins access via ctx.getService('automation')
+        ctx.registerService('automation', this.engine);
+
+        if (this.options.debug) {
+            ctx.hook('automation:beforeExecute', async (flowName: string) => {
+                ctx.logger.debug(`[Automation] Before execute: ${flowName}`);
+            });
+        }
+
+        ctx.logger.info('[Automation] Engine initialized');
+    }
+
+    async start(ctx: PluginContext): Promise<void> {
+        if (!this.engine) return;
+
+        // Trigger hook to notify engine is ready — other plugins can start registering nodes
+        await ctx.trigger('automation:ready', this.engine);
+
+        const nodeTypes = this.engine.getRegisteredNodeTypes();
+        ctx.logger.info(
+            `[Automation] Engine started with ${nodeTypes.length} node types: ${nodeTypes.join(', ') || '(none)'}`,
+        );
+    }
+
+    async destroy(): Promise<void> {
+        this.engine = undefined;
+    }
+}

package/src/plugins/crud-nodes-plugin.ts

@@ -0,0 +1,68 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Plugin, PluginContext } from '@objectstack/core';
+import type { AutomationEngine } from '../engine.js';
+
+/**
+ * CRUD Node Plugin — Provides get_record / create_record / update_record / delete_record
+ *
+ * Dependencies: service-automation (engine)
+ *
+ * In a full runtime environment these nodes would delegate to ObjectQL (data layer).
+ * This MVP implementation provides the extension point structure.
+ */
+export class CrudNodesPlugin implements Plugin {
+    name = 'com.objectstack.automation.crud-nodes';
+    version = '1.0.0';
+    type = 'standard' as const;
+    dependencies = ['com.objectstack.service-automation'];
+
+    async init(ctx: PluginContext): Promise<void> {
+        const engine = ctx.getService<AutomationEngine>('automation');
+
+        // get_record node executor
+        engine.registerNodeExecutor({
+            type: 'get_record',
+            async execute(node, _variables, _context) {
+                const config = node.config as Record<string, unknown> | undefined;
+                // In production, this would query via ObjectQL:
+                // const ql = ctx.getService('objectql');
+                // const records = await ql.find(config.object, config.filters);
+                return {
+                    success: true,
+                    output: { records: [], object: config?.object },
+                };
+            },
+        });
+
+        // create_record node executor
+        engine.registerNodeExecutor({
+            type: 'create_record',
+            async execute(node, _variables, _context) {
+                const config = node.config as Record<string, unknown> | undefined;
+                return {
+                    success: true,
+                    output: { id: 'new-record-id', object: config?.object },
+                };
+            },
+        });
+
+        // update_record node executor
+        engine.registerNodeExecutor({
+            type: 'update_record',
+            async execute(_node, _variables, _context) {
+                return { success: true };
+            },
+        });
+
+        // delete_record node executor
+        engine.registerNodeExecutor({
+            type: 'delete_record',
+            async execute(_node, _variables, _context) {
+                return { success: true };
+            },
+        });
+
+        ctx.logger.info('[CRUD Nodes] 4 node executors registered');
+    }
+}

package/src/plugins/http-connector-plugin.ts

@@ -0,0 +1,70 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Plugin, PluginContext } from '@objectstack/core';
+import type { AutomationEngine } from '../engine.js';
+
+/**
+ * HTTP + Connector Node Plugin — Provides http_request / connector_action nodes
+ *
+ * Dependencies: service-automation (engine)
+ */
+export class HttpConnectorPlugin implements Plugin {
+    name = 'com.objectstack.automation.http-connector';
+    version = '1.0.0';
+    type = 'standard' as const;
+    dependencies = ['com.objectstack.service-automation'];
+
+    async init(ctx: PluginContext): Promise<void> {
+        const engine = ctx.getService<AutomationEngine>('automation');
+
+        // http_request node executor
+        engine.registerNodeExecutor({
+            type: 'http_request',
+            async execute(node, _variables, _context) {
+                const config = node.config as Record<string, unknown> | undefined;
+                const url = config?.url as string | undefined;
+                const method = (config?.method as string) ?? 'GET';
+                const headers = config?.headers as Record<string, string> | undefined;
+                const body = config?.body;
+
+                if (!url) {
+                    return { success: false, error: 'http_request: url is required' };
+                }
+
+                const response = await fetch(url, {
+                    method,
+                    headers,
+                    body: body ? JSON.stringify(body) : undefined,
+                });
+                const data = await response.json();
+
+                return {
+                    success: response.ok,
+                    output: { response: data, status: response.status },
+                    error: response.ok ? undefined : `HTTP ${response.status}`,
+                };
+            },
+        });
+
+        // connector_action node — calls a registered connector
+        engine.registerNodeExecutor({
+            type: 'connector_action',
+            async execute(node, _variables, _context) {
+                const connectorConfig = node.connectorConfig;
+                if (!connectorConfig) {
+                    return { success: false, error: 'connector_action: connectorConfig is required' };
+                }
+
+                ctx.logger.info(
+                    `Connector action: ${connectorConfig.connectorId}.${connectorConfig.actionId}`,
+                );
+
+                // In production, this would look up the connector from a registry
+                // and execute the specified action with the mapped inputs
+                return { success: true, output: { connectorResult: {} } };
+            },
+        });
+
+        ctx.logger.info('[HTTP Connector] 2 node executors registered');
+    }
+}

package/src/plugins/logic-nodes-plugin.ts

@@ -0,0 +1,78 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Plugin, PluginContext } from '@objectstack/core';
+import type { AutomationEngine } from '../engine.js';
+
+/**
+ * Logic Node Plugin — Provides decision / assignment / loop nodes
+ *
+ * Dependencies: service-automation (engine)
+ */
+export class LogicNodesPlugin implements Plugin {
+    name = 'com.objectstack.automation.logic-nodes';
+    version = '1.0.0';
+    type = 'standard' as const;
+    dependencies = ['com.objectstack.service-automation'];
+
+    async init(ctx: PluginContext): Promise<void> {
+        const engine = ctx.getService<AutomationEngine>('automation');
+
+        // decision node — conditional branching
+        engine.registerNodeExecutor({
+            type: 'decision',
+            async execute(node, variables, _context) {
+                const config = node.config as Record<string, unknown> | undefined;
+                const conditions = (config?.conditions ?? []) as Array<{ label: string; expression: string }>;
+
+                for (const cond of conditions) {
+                    // MVP: Simple template replacement + expression evaluation.
+                    // Flow definitions are authored by trusted developers/admins.
+                    // TODO: Replace with safe expression evaluator (e.g., jexl) for production.
+                    let expr = cond.expression;
+                    for (const [k, v] of variables) {
+                        expr = expr.split(`{${k}}`).join(String(v));
+                    }
+                    try {
+                        if (new Function(`return (${expr})`)()) {
+                            return { success: true, branchLabel: cond.label };
+                        }
+                    } catch {
+                        // Continue to next condition
+                    }
+                }
+                return { success: true, branchLabel: 'default' };
+            },
+        });
+
+        // assignment node — set variables
+        engine.registerNodeExecutor({
+            type: 'assignment',
+            async execute(node, variables, _context) {
+                const config = (node.config ?? {}) as Record<string, unknown>;
+                for (const [key, value] of Object.entries(config)) {
+                    variables.set(key, value);
+                }
+                return { success: true };
+            },
+        });
+
+        // loop node — iterate over a collection
+        engine.registerNodeExecutor({
+            type: 'loop',
+            async execute(node, variables, _context) {
+                const config = node.config as Record<string, unknown> | undefined;
+                const collectionName = config?.collection as string | undefined;
+                if (collectionName) {
+                    const collection = variables.get(collectionName);
+                    if (Array.isArray(collection)) {
+                        variables.set('$loopItems', collection);
+                        variables.set('$loopIndex', 0);
+                    }
+                }
+                return { success: true };
+            },
+        });
+
+        ctx.logger.info('[Logic Nodes] 3 node executors registered');
+    }
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}