@synergenius/flow-weaver 0.2.0

package/dist/plugin/PluginPanel.d.ts

@@ -0,0 +1,12 @@
+/**
+ * PluginPanel — standalone component for external plugins.
+ *
+ * At runtime, `evaluateClientCode()` in pluginClientManager intercepts
+ * `require('@synergenius/flow-weaver/plugin')` and provides the real
+ * component from src/plugin-system/external/components.tsx. This file
+ * exists for TypeScript compile-time resolution only.
+ */
+import React from 'react';
+import type { TPluginComponentProps } from './types.js';
+export declare const PluginPanel: React.FC<TPluginComponentProps>;
+//# sourceMappingURL=PluginPanel.d.ts.map

package/dist/plugin/PluginPanel.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+export const PluginPanel = ({ children }) => {
+    return _jsx("div", { className: "plugin-panel", children: children });
+};
+//# sourceMappingURL=PluginPanel.js.map

package/dist/plugin/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @synergenius/flow-weaver/plugin
+ *
+ * Public API for external plugin development.
+ */
+export type { TPluginComponentArea, TPluginComponentConfig, TPluginComponentApi, TPluginComponentProps, TPluginUI, TPluginInitializer, TPluginInitializerResult, TPluginSystemModule, TPluginCapabilities, TPluginDefinition, } from './types.js';
+export { PluginPanel } from './PluginPanel.js';
+/**
+ * Convenience wrapper — marks a function as a plugin initializer.
+ * At runtime this is a passthrough; it exists for discoverability and typing.
+ */
+export declare function createPlugin(fn: () => import('./types.js').TPluginInitializerResult): () => import("./types.js").TPluginInitializerResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/plugin/index.js

@@ -0,0 +1,14 @@
+/**
+ * @synergenius/flow-weaver/plugin
+ *
+ * Public API for external plugin development.
+ */
+export { PluginPanel } from './PluginPanel.js';
+/**
+ * Convenience wrapper — marks a function as a plugin initializer.
+ * At runtime this is a passthrough; it exists for discoverability and typing.
+ */
+export function createPlugin(fn) {
+    return fn;
+}
+//# sourceMappingURL=index.js.map

package/dist/plugin/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * External plugin types — pure TypeScript interfaces (no zod).
+ *
+ * These mirror the zod schemas in src/plugin-system/externalTypes.ts
+ * but are dependency-free so external plugin authors only need this package.
+ */
+import type { ReactNode } from 'react';
+export type TPluginComponentArea = 'sidebar' | 'main' | 'toolbar' | 'modal' | 'panel';
+export interface TPluginComponentConfig {
+    name: string;
+    displayName: string;
+    description?: string;
+    icon?: string;
+    area: TPluginComponentArea;
+}
+export interface TPluginComponentApi {
+    call: (pluginName: string, method: string, payload?: unknown) => Promise<unknown>;
+}
+export interface TPluginComponentProps {
+    pluginName: string;
+    componentName: string;
+    config: TPluginComponentConfig;
+    children?: ReactNode;
+    api: TPluginComponentApi;
+}
+export interface TPluginUI {
+    components: Record<string, React.ComponentType<TPluginComponentProps>>;
+    config: Record<string, TPluginComponentConfig>;
+}
+export interface TPluginInitializerResult {
+    initialize?: () => Promise<void>;
+    ui?: TPluginUI;
+}
+export type TPluginInitializer = () => TPluginInitializerResult;
+export interface TPluginSystemModule {
+    initialize?: () => Promise<void> | void;
+    methods: Record<string, (...args: unknown[]) => unknown>;
+    cleanup?: () => Promise<void> | void;
+}
+export interface TPluginCapabilities {
+    filesystem?: {
+        allowed: boolean;
+        paths?: string[];
+        operations?: Array<'read' | 'write' | 'delete'>;
+    };
+    network?: {
+        allowed: boolean;
+        domains?: string[];
+        protocols?: Array<'http' | 'https' | 'ws' | 'wss'>;
+    };
+    process?: {
+        allowed: boolean;
+        maxMemory?: number;
+        timeout?: number;
+    };
+    interop?: {
+        allowed: boolean;
+        plugins?: string[];
+    };
+}
+export interface TPluginDefinition {
+    name: string;
+    version: string;
+    description: string;
+    entry: {
+        client: string;
+        system?: string;
+    };
+    dependencies?: {
+        plugins?: string[];
+        system?: string[];
+    };
+    capabilities: TPluginCapabilities;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/plugin/types.js

@@ -0,0 +1,8 @@
+/**
+ * External plugin types — pure TypeScript interfaces (no zod).
+ *
+ * These mirror the zod schemas in src/plugin-system/externalTypes.ts
+ * but are dependency-free so external plugin authors only need this package.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/resolve-package-types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Resolve a package specifier to the absolute path of its `.d.ts` type declarations.
+ *
+ * Resolution order:
+ * 1. Find `node_modules/<pkg>/package.json` and read `types` or `typings` field
+ * 2. Check `exports` field for types (modern packages use conditional exports)
+ * 3. Fall back to `@types/<pkg>/index.d.ts`
+ * 4. Fall back to `<pkg>/index.d.ts`
+ * 5. Return `null` if nothing found
+ *
+ * @param packageSpecifier - The npm package name (e.g., 'date-fns', '@scope/pkg')
+ * @param fromDir - Directory to start searching from (walks up to find node_modules)
+ * @param nodeModulesOverride - Optional explicit node_modules path (for testing)
+ * @returns Absolute path to the `.d.ts` file, or null
+ */
+export declare function resolvePackageTypesPath(packageSpecifier: string, fromDir: string, nodeModulesOverride?: string): string | null;
+//# sourceMappingURL=resolve-package-types.d.ts.map

package/dist/resolve-package-types.js

@@ -0,0 +1,123 @@
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+/**
+ * Resolve a package specifier to the absolute path of its `.d.ts` type declarations.
+ *
+ * Resolution order:
+ * 1. Find `node_modules/<pkg>/package.json` and read `types` or `typings` field
+ * 2. Check `exports` field for types (modern packages use conditional exports)
+ * 3. Fall back to `@types/<pkg>/index.d.ts`
+ * 4. Fall back to `<pkg>/index.d.ts`
+ * 5. Return `null` if nothing found
+ *
+ * @param packageSpecifier - The npm package name (e.g., 'date-fns', '@scope/pkg')
+ * @param fromDir - Directory to start searching from (walks up to find node_modules)
+ * @param nodeModulesOverride - Optional explicit node_modules path (for testing)
+ * @returns Absolute path to the `.d.ts` file, or null
+ */
+export function resolvePackageTypesPath(packageSpecifier, fromDir, nodeModulesOverride) {
+    const nodeModulesDirs = nodeModulesOverride
+        ? [nodeModulesOverride]
+        : findNodeModulesDirs(fromDir);
+    for (const nmDir of nodeModulesDirs) {
+        const result = resolveInNodeModules(packageSpecifier, nmDir);
+        if (result)
+            return result;
+    }
+    return null;
+}
+/**
+ * Walk up from `fromDir` collecting all `node_modules` directories.
+ */
+function findNodeModulesDirs(fromDir) {
+    const dirs = [];
+    let current = path.resolve(fromDir);
+    const root = path.parse(current).root;
+    while (current !== root) {
+        const candidate = path.join(current, 'node_modules');
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
+            dirs.push(candidate);
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return dirs;
+}
+/**
+ * Resolve types path from the exports field in package.json.
+ * Handles conditional exports like: { ".": { "types": "./lib/index.d.ts" } }
+ */
+function resolveExportsTypes(exports, pkgDir) {
+    if (typeof exports !== 'object' || exports === null)
+        return null;
+    const exportsObj = exports;
+    // Check root export "."
+    const root = exportsObj['.'];
+    if (root && typeof root === 'object' && root !== null) {
+        const rootObj = root;
+        if (typeof rootObj.types === 'string') {
+            const typesPath = path.resolve(pkgDir, rootObj.types);
+            if (fs.existsSync(typesPath)) {
+                return typesPath;
+            }
+        }
+    }
+    // Check direct types field in exports (less common but valid)
+    if (typeof exportsObj.types === 'string') {
+        const typesPath = path.resolve(pkgDir, exportsObj.types);
+        if (fs.existsSync(typesPath)) {
+            return typesPath;
+        }
+    }
+    return null;
+}
+/**
+ * Try to resolve a package's .d.ts within a single node_modules directory.
+ */
+function resolveInNodeModules(packageSpecifier, nmDir) {
+    // Extract the bare package name (without sub-path) for scoped packages
+    const pkgDir = path.join(nmDir, packageSpecifier);
+    // 1. Check package.json types/typings field
+    const pkgJsonPath = path.join(pkgDir, 'package.json');
+    if (fs.existsSync(pkgJsonPath)) {
+        try {
+            const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+            const typesField = pkgJson.types || pkgJson.typings;
+            if (typesField) {
+                const typesPath = path.resolve(pkgDir, typesField);
+                if (fs.existsSync(typesPath)) {
+                    return typesPath;
+                }
+            }
+            // 1b. Check exports field for types (modern packages)
+            if (pkgJson.exports) {
+                const exportsTypesPath = resolveExportsTypes(pkgJson.exports, pkgDir);
+                if (exportsTypesPath) {
+                    return exportsTypesPath;
+                }
+            }
+        }
+        catch {
+            // ignore malformed package.json
+        }
+    }
+    // 2. Fall back to @types/<pkg>/index.d.ts
+    // For scoped packages @scope/pkg, DefinitelyTyped uses @types/scope__pkg
+    // but also check the plain name for non-scoped packages
+    const atTypesName = packageSpecifier.startsWith('@')
+        ? packageSpecifier.replace('@', '').replace('/', '__')
+        : packageSpecifier;
+    const atTypesPath = path.join(nmDir, '@types', atTypesName, 'index.d.ts');
+    if (fs.existsSync(atTypesPath)) {
+        return atTypesPath;
+    }
+    // 3. Fall back to <pkg>/index.d.ts
+    const indexDtsPath = path.join(pkgDir, 'index.d.ts');
+    if (fs.existsSync(indexDtsPath)) {
+        return indexDtsPath;
+    }
+    return null;
+}
+//# sourceMappingURL=resolve-package-types.js.map

package/dist/runtime/CancellationError.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Error thrown when workflow execution is cancelled via AbortSignal.
+ */
+export declare class CancellationError extends Error {
+    readonly executionIndex: number;
+    readonly nodeId?: string | undefined;
+    readonly timestamp: number;
+    constructor(message?: string, executionIndex?: number, nodeId?: string | undefined, timestamp?: number);
+    static isCancellationError(error: unknown): error is CancellationError;
+}
+//# sourceMappingURL=CancellationError.d.ts.map

package/dist/runtime/CancellationError.js

@@ -0,0 +1,20 @@
+/**
+ * Error thrown when workflow execution is cancelled via AbortSignal.
+ */
+export class CancellationError extends Error {
+    executionIndex;
+    nodeId;
+    timestamp;
+    constructor(message = "Workflow execution cancelled", executionIndex = 0, nodeId, timestamp = Date.now()) {
+        super(message);
+        this.executionIndex = executionIndex;
+        this.nodeId = nodeId;
+        this.timestamp = timestamp;
+        this.name = "CancellationError";
+    }
+    static isCancellationError(error) {
+        return (error instanceof CancellationError ||
+            (error instanceof Error && error.name === "CancellationError"));
+    }
+}
+//# sourceMappingURL=CancellationError.js.map

package/dist/runtime/ExecutionContext.d.ts

@@ -0,0 +1,146 @@
+import type { TDebugger, TStatusType, TVariableIdentification } from './events.js';
+/**
+ * Address for accessing a variable in the execution context
+ *
+ * Variables are stored with key format: `nodeName:portName:executionIndex`
+ *
+ * @example
+ * ```typescript
+ * const address: VariableAddress = {
+ *   nodeName: 'adder1',
+ *   portName: 'result',
+ *   executionIndex: 0,
+ *   nodeTypeName: 'Add'
+ * };
+ * const value = await ctx.getVariable(address);
+ * // Key used internally: "adder1:result:0"
+ * ```
+ */
+export interface VariableAddress {
+    id: string;
+    portName: string;
+    executionIndex: number;
+    nodeTypeName?: string | undefined;
+}
+export interface ExecutionInfo {
+    id: string;
+    index: number;
+    parentIndex?: number | undefined;
+    scopeName?: string | undefined;
+}
+type VariableValue = unknown | (() => unknown) | (() => Promise<unknown>);
+/**
+ * Runtime execution context for generated workflows
+ *
+ * Manages variable storage, execution tracking, and pull execution (lazy evaluation).
+ * This class is used internally by generated workflow code.
+ *
+ * Key Features:
+ * - Variable storage with execution-scoped addressing
+ * - Pull execution support (lazy evaluation)
+ * - Debug event emission
+ * - Async and sync execution modes
+ *
+ * @example
+ * ```typescript
+ * const ctx = new GeneratedExecutionContext(true, debugger);
+ * const execIndex = ctx.addExecution('node1');
+ * ctx.setVariable({ nodeName: 'node1', portName: 'result', executionIndex: execIndex }, 42);
+ * const value = await ctx.getVariable({ nodeName: 'node1', portName: 'result', executionIndex: execIndex });
+ * ```
+ */
+export declare class GeneratedExecutionContext {
+    private variables;
+    private executions;
+    private executionCounter;
+    private isAsync;
+    private flowWeaverDebugger?;
+    private pullExecutors;
+    private nodeExecutionIndices;
+    private abortSignal?;
+    /**
+     * Create a new execution context
+     * @param isAsync - Whether the workflow runs in async mode (default: true)
+     * @param flowWeaverDebugger - Optional debugger for emitting execution events
+     * @param abortSignal - Optional AbortSignal for cancellation support
+     */
+    constructor(isAsync?: boolean, flowWeaverDebugger?: TDebugger, abortSignal?: AbortSignal);
+    registerPullExecutor(id: string, executor: () => void | Promise<void>): void;
+    addExecution(id: string, parentIndex?: number, scopeName?: string): number;
+    setVariable(address: VariableAddress, value: VariableValue): void | Promise<void>;
+    getVariable(address: VariableAddress): unknown | Promise<unknown>;
+    private retrieveVariable;
+    hasVariable(address: VariableAddress): boolean;
+    getExecution(id: string, index: number): ExecutionInfo | undefined;
+    /**
+     * Create an isolated execution scope for container nodes
+     *
+     * Scopes provide isolated variable storage for nodes like ForEach loops.
+     * Child nodes execute within the scope, then variables are merged back.
+     *
+     * @param _parentNodeName - ID of the container node creating the scope
+     * @param _parentIndex - Execution index of the container
+     * @param _scopeName - Name of the scope (e.g., 'iteration')
+     * @param cleanScope - If true, create fresh scope without parent variables (per-port scopes). If false, inherit parent variables (node-level scopes).
+     * @returns New ExecutionContext for the scoped execution
+     *
+     * @example
+     * ```typescript
+     * // Per-port scope (clean=true): isolated variables
+     * const scopedCtx = ctx.createScope('forEach1', 0, 'iteration', true);
+     *
+     * // Node-level scope (clean=false): inherited variables
+     * const scopedCtx = ctx.createScope('container1', 0, 'block', false);
+     * ```
+     */
+    createScope(_parentNodeName: string, _parentIndex: number, _scopeName: string, cleanScope?: boolean): GeneratedExecutionContext;
+    /**
+     * Merge a scoped execution context back into the parent context
+     *
+     * Copies all variables and execution info from the scoped context to this context.
+     * Updates the execution counter to maintain unique execution indices.
+     *
+     * @param scopedContext - The scoped context to merge
+     */
+    mergeScope(scopedContext: GeneratedExecutionContext): void;
+    private getVariableKey;
+    private getExecutionKey;
+    getExecutionCount(): number;
+    reset(): void;
+    /**
+     * Check if the workflow has been aborted
+     */
+    isAborted(): boolean;
+    /**
+     * Throw CancellationError if the workflow has been aborted
+     * @param nodeId - Optional node ID to include in the error
+     */
+    checkAborted(nodeId?: string): void;
+    sendStatusChangedEvent(args: {
+        nodeTypeName: string;
+        id: string;
+        scope?: string;
+        side?: 'start' | 'exit';
+        executionIndex: number;
+        status: TStatusType;
+    }): void;
+    sendVariableSetEvent(args: {
+        identifier: TVariableIdentification;
+        value: unknown;
+    }): void;
+    sendLogErrorEvent(args: {
+        nodeTypeName: string;
+        id: string;
+        scope?: string;
+        side?: 'start' | 'exit';
+        executionIndex: number;
+        error: string;
+    }): void;
+    sendWorkflowCompletedEvent(args: {
+        executionIndex: number;
+        status: 'SUCCEEDED' | 'FAILED' | 'CANCELLED';
+        result?: unknown;
+    }): void;
+}
+export {};
+//# sourceMappingURL=ExecutionContext.d.ts.map