@claude-flow/plugin-gastown-bridge 0.1.3 → 0.1.4

package/dist/formula.d.ts

@@ -0,0 +1,317 @@
+import { EventEmitter } from 'events';
+import { b as FormulaType, S as Step, x as CookedFormula, F as Formula } from './types-CMoOZXrm.js';
+import { G as GtBridge } from './gt-bridge-B7hZz5vC.js';
+import 'zod';
+
+/**
+ * Gas Town Formula Executor - Hybrid WASM/CLI Implementation
+ *
+ * Provides formula execution with:
+ * - WASM acceleration for parsing and cooking (352x faster)
+ * - CLI bridge fallback for I/O operations
+ * - Progress tracking with event emission
+ * - Step dependency resolution
+ * - Molecule generation from cooked formulas
+ * - Cancellation support
+ *
+ * @module v3/plugins/gastown-bridge/formula/executor
+ */
+
+/**
+ * WASM loader interface for formula operations
+ */
+interface IWasmLoader {
+    /** Check if WASM is initialized */
+    isInitialized(): boolean;
+    /** Parse TOML formula content to AST */
+    parseFormula(content: string): Formula;
+    /** Cook formula with variable substitution */
+    cookFormula(formula: Formula, vars: Record<string, string>): CookedFormula;
+    /** Batch cook multiple formulas */
+    batchCook(formulas: Formula[], varsArray: Record<string, string>[]): CookedFormula[];
+    /** Resolve step dependencies (topological sort) */
+    resolveStepDependencies(steps: Step[]): Step[];
+    /** Detect cycles in step dependencies */
+    detectCycle(steps: Step[]): {
+        hasCycle: boolean;
+        cycleSteps?: string[];
+    };
+}
+/**
+ * Execution options
+ */
+interface ExecuteOptions {
+    /** Target agent for execution */
+    targetAgent?: string;
+    /** Whether to run in dry-run mode (no actual execution) */
+    dryRun?: boolean;
+    /** Timeout per step in milliseconds */
+    stepTimeout?: number;
+    /** Maximum parallel steps */
+    maxParallel?: number;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Custom step handler */
+    stepHandler?: (step: Step, context: StepContext) => Promise<StepResult>;
+}
+/**
+ * Step execution context
+ */
+interface StepContext {
+    /** Execution ID */
+    executionId: string;
+    /** Formula being executed */
+    formula: CookedFormula;
+    /** Current step index */
+    stepIndex: number;
+    /** Total steps */
+    totalSteps: number;
+    /** Variables available to the step */
+    variables: Record<string, string>;
+    /** Results from previous steps */
+    previousResults: Map<string, StepResult>;
+    /** Abort signal */
+    signal?: AbortSignal;
+    /** Execution start time */
+    startTime: Date;
+}
+/**
+ * Step execution result
+ */
+interface StepResult {
+    /** Step ID */
+    stepId: string;
+    /** Whether step succeeded */
+    success: boolean;
+    /** Step output data */
+    output?: unknown;
+    /** Error message if failed */
+    error?: string;
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Step metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Molecule - Generated work unit from cooked formula
+ */
+interface Molecule {
+    /** Unique molecule ID */
+    id: string;
+    /** Parent formula name */
+    formulaName: string;
+    /** Molecule title */
+    title: string;
+    /** Molecule description */
+    description: string;
+    /** Molecule type (from formula type) */
+    type: FormulaType;
+    /** Associated step or leg */
+    sourceId: string;
+    /** Assigned agent */
+    agent?: string;
+    /** Dependencies (other molecule IDs) */
+    dependencies: string[];
+    /** Execution order */
+    order: number;
+    /** Molecule metadata */
+    metadata: Record<string, unknown>;
+    /** Creation timestamp */
+    createdAt: Date;
+}
+/**
+ * Execution progress
+ */
+interface ExecutionProgress {
+    /** Execution ID */
+    executionId: string;
+    /** Formula name */
+    formulaName: string;
+    /** Current status */
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+    /** Total steps/legs */
+    totalSteps: number;
+    /** Completed steps */
+    completedSteps: number;
+    /** Failed steps */
+    failedSteps: number;
+    /** Current step being executed */
+    currentStep?: string;
+    /** Start time */
+    startTime: Date;
+    /** End time (if completed) */
+    endTime?: Date;
+    /** Step results */
+    stepResults: StepResult[];
+    /** Error message (if failed) */
+    error?: string;
+    /** Progress percentage (0-100) */
+    percentage: number;
+}
+/**
+ * Executor events
+ */
+interface ExecutorEvents {
+    'execution:start': (executionId: string, formula: CookedFormula) => void;
+    'execution:progress': (progress: ExecutionProgress) => void;
+    'execution:complete': (executionId: string, results: StepResult[]) => void;
+    'execution:error': (executionId: string, error: Error) => void;
+    'execution:cancelled': (executionId: string) => void;
+    'step:start': (executionId: string, step: Step) => void;
+    'step:complete': (executionId: string, result: StepResult) => void;
+    'step:error': (executionId: string, stepId: string, error: Error) => void;
+    'molecule:created': (molecule: Molecule) => void;
+}
+/**
+ * Logger interface
+ */
+interface ExecutorLogger {
+    debug: (msg: string, meta?: Record<string, unknown>) => void;
+    info: (msg: string, meta?: Record<string, unknown>) => void;
+    warn: (msg: string, meta?: Record<string, unknown>) => void;
+    error: (msg: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * Hybrid Formula Executor
+ *
+ * Uses WASM for fast parsing and cooking operations,
+ * falls back to CLI bridge for I/O operations.
+ *
+ * @example
+ * ```typescript
+ * const executor = new FormulaExecutor(gtBridge, wasmLoader);
+ *
+ * // Full execution
+ * const results = await executor.execute('my-formula', { feature: 'auth' });
+ *
+ * // Just cook (WASM-accelerated)
+ * const cooked = await executor.cook('my-formula', { feature: 'auth' });
+ *
+ * // Generate molecules
+ * const molecules = await executor.generateMolecules(cooked);
+ * ```
+ */
+declare class FormulaExecutor extends EventEmitter {
+    private readonly gtBridge;
+    private readonly wasmLoader;
+    private readonly logger;
+    private readonly jsFallback;
+    /** Active executions for progress tracking */
+    private readonly executions;
+    /** Cancellation controllers */
+    private readonly cancellations;
+    /** Debounced progress emitters per execution */
+    private readonly progressEmitters;
+    /** Default max parallel workers */
+    private readonly defaultMaxParallel;
+    constructor(gtBridge: GtBridge, wasmLoader?: IWasmLoader, logger?: ExecutorLogger);
+    /**
+     * Execute a formula with full lifecycle
+     *
+     * @param formulaName - Name of the formula to execute
+     * @param vars - Variables for substitution
+     * @param options - Execution options
+     * @returns Array of step results
+     */
+    execute(formulaName: string, vars: Record<string, string>, options?: ExecuteOptions): Promise<StepResult[]>;
+    /**
+     * Cook a formula with variable substitution (WASM-accelerated)
+     *
+     * @param formulaName - Name of the formula or TOML content
+     * @param vars - Variables for substitution
+     * @returns Cooked formula with substituted variables
+     */
+    cook(formulaName: string, vars: Record<string, string>): Promise<CookedFormula>;
+    /**
+     * Generate molecules from a cooked formula
+     *
+     * Molecules are executable work units derived from formula steps/legs.
+     * Uses object pooling for reduced allocations.
+     *
+     * @param cookedFormula - The cooked formula to generate molecules from
+     * @returns Array of molecules
+     */
+    generateMolecules(cookedFormula: CookedFormula): Promise<Molecule[]>;
+    /**
+     * Run a single step
+     *
+     * @param step - Step to execute
+     * @param context - Execution context
+     * @param options - Execution options
+     * @returns Step result
+     */
+    runStep(step: Step, context: StepContext, options?: ExecuteOptions): Promise<StepResult>;
+    /**
+     * Get execution progress
+     *
+     * @param executionId - Execution ID to get progress for
+     * @returns Execution progress or undefined
+     */
+    getProgress(executionId: string): ExecutionProgress | undefined;
+    /**
+     * Cancel an execution
+     *
+     * @param executionId - Execution ID to cancel
+     * @returns Whether cancellation was initiated
+     */
+    cancel(executionId: string): boolean;
+    /**
+     * List all active executions
+     */
+    getActiveExecutions(): ExecutionProgress[];
+    /**
+     * Check if WASM is available for acceleration
+     */
+    isWasmAvailable(): boolean;
+    /**
+     * Get cache statistics for performance monitoring
+     */
+    getCacheStats(): {
+        stepResultCache: {
+            entries: number;
+            sizeBytes: number;
+        };
+        cookCache: {
+            entries: number;
+            sizeBytes: number;
+        };
+    };
+    /**
+     * Clear all executor caches
+     */
+    clearCaches(): void;
+    /**
+     * Parse formula content using WASM or JS fallback
+     */
+    private parseFormula;
+    /**
+     * Fetch formula from CLI
+     */
+    private fetchFormula;
+    /**
+     * Validate required variables are provided
+     */
+    private validateVariables;
+    /**
+     * Resolve step dependencies using WASM or JS fallback
+     */
+    private resolveStepDependencies;
+    /**
+     * Get ordered execution units (steps or legs) from formula
+     */
+    private getOrderedExecutionUnits;
+    /**
+     * Execute step via CLI bridge
+     */
+    private executeStepViaCli;
+    /**
+     * Merge multiple abort signals
+     */
+    private mergeSignals;
+}
+/**
+ * Create a new FormulaExecutor instance
+ */
+declare function createFormulaExecutor(gtBridge: GtBridge, wasmLoader?: IWasmLoader, logger?: ExecutorLogger): FormulaExecutor;
+
+export { type ExecuteOptions, type ExecutionProgress, type ExecutorEvents, type ExecutorLogger, FormulaExecutor, type IWasmLoader, type Molecule, type StepContext, type StepResult, createFormulaExecutor, FormulaExecutor as default };

package/dist/formula.js

@@ -0,0 +1,2 @@
+export{a as FormulaExecutor,b as createFormulaExecutor,c as default}from'./chunk-2KNTWGUX.js';//# sourceMappingURL=formula.js.map
+//# sourceMappingURL=formula.js.map

package/dist/formula.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"formula.js"}

package/dist/gt-bridge-B7hZz5vC.d.cts

@@ -0,0 +1,291 @@
+import { z } from 'zod';
+
+/**
+ * Gas Town CLI Bridge
+ *
+ * Provides a secure wrapper around the `gt` (Gas Town) CLI tool.
+ * Implements command execution with proper input sanitization,
+ * argument validation, and error handling.
+ *
+ * Security Features:
+ * - All inputs validated with Zod schemas
+ * - No shell execution (uses execFile)
+ * - Command allowlist enforcement
+ * - Argument sanitization
+ *
+ * @module v3/plugins/gastown-bridge/bridges/gt-bridge
+ */
+
+/**
+ * Safe string pattern - no shell metacharacters
+ */
+declare const SafeStringSchema: z.ZodEffects<z.ZodString, string, string>;
+/**
+ * Safe identifier pattern - alphanumeric with underscore/hyphen
+ */
+declare const IdentifierSchema: z.ZodString;
+/**
+ * Gas price schema
+ */
+declare const GasPriceSchema: z.ZodNumber;
+/**
+ * Gas limit schema
+ */
+declare const GasLimitSchema: z.ZodNumber;
+/**
+ * Transaction hash schema (0x prefixed hex)
+ */
+declare const TxHashSchema: z.ZodString;
+/**
+ * Address schema (0x prefixed hex)
+ */
+declare const AddressSchema: z.ZodString;
+/**
+ * Network schema
+ */
+declare const NetworkSchema: z.ZodEnum<["mainnet", "goerli", "sepolia", "polygon", "arbitrum", "optimism", "base", "local"]>;
+/**
+ * GT command argument schema
+ */
+declare const GtArgumentSchema: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+/**
+ * Gas Town executor configuration
+ */
+interface GtBridgeConfig {
+    /**
+     * Path to gt executable
+     * Default: 'gt' (assumes in PATH)
+     */
+    gtPath?: string;
+    /**
+     * Working directory for execution
+     */
+    cwd?: string;
+    /**
+     * Execution timeout in milliseconds
+     * Default: 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Maximum buffer size for output
+     * Default: 10MB
+     */
+    maxBuffer?: number;
+    /**
+     * Environment variables
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Default network
+     */
+    defaultNetwork?: z.infer<typeof NetworkSchema>;
+}
+/**
+ * Gas estimation result
+ */
+interface GasEstimate {
+    gasLimit: number;
+    gasPrice: string;
+    maxFeePerGas?: string;
+    maxPriorityFeePerGas?: string;
+    estimatedCost: string;
+    estimatedCostUsd?: number;
+}
+/**
+ * Transaction status
+ */
+interface TxStatus {
+    hash: string;
+    status: 'pending' | 'confirmed' | 'failed' | 'dropped';
+    blockNumber?: number;
+    confirmations?: number;
+    gasUsed?: number;
+    effectiveGasPrice?: string;
+    error?: string;
+}
+/**
+ * Network status
+ */
+interface NetworkStatus {
+    network: string;
+    chainId: number;
+    blockNumber: number;
+    baseFee?: string;
+    gasPrice?: string;
+    connected: boolean;
+}
+/**
+ * GT execution result
+ */
+interface GtResult<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    command: string;
+    args: string[];
+    durationMs: number;
+}
+/**
+ * Logger interface
+ */
+interface GtLogger {
+    debug: (msg: string, meta?: Record<string, unknown>) => void;
+    info: (msg: string, meta?: Record<string, unknown>) => void;
+    warn: (msg: string, meta?: Record<string, unknown>) => void;
+    error: (msg: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * Gas Town bridge error codes
+ */
+type GtErrorCode = 'COMMAND_NOT_FOUND' | 'EXECUTION_FAILED' | 'TIMEOUT' | 'INVALID_ARGUMENT' | 'INVALID_OUTPUT' | 'NETWORK_ERROR' | 'VALIDATION_ERROR';
+/**
+ * Gas Town bridge error
+ */
+declare class GtBridgeError extends Error {
+    readonly code: GtErrorCode;
+    readonly command?: string | undefined;
+    readonly args?: string[] | undefined;
+    readonly cause?: Error | undefined;
+    constructor(message: string, code: GtErrorCode, command?: string | undefined, args?: string[] | undefined, cause?: Error | undefined);
+}
+/**
+ * Gas Town CLI Bridge
+ *
+ * Secure wrapper around the `gt` CLI tool for gas estimation
+ * and transaction management.
+ *
+ * @example
+ * ```typescript
+ * const gtBridge = new GtBridge({ gtPath: '/usr/local/bin/gt' });
+ * await gtBridge.initialize();
+ *
+ * const estimate = await gtBridge.estimateGas({
+ *   to: '0x...',
+ *   data: '0x...',
+ *   network: 'mainnet',
+ * });
+ * ```
+ */
+declare class GtBridge {
+    private config;
+    private logger;
+    private initialized;
+    /** Commands that can be cached (read-only, no side effects) */
+    private static readonly CACHEABLE_COMMANDS;
+    /** Commands that should use longer cache (static data) */
+    private static readonly STATIC_COMMANDS;
+    constructor(config?: GtBridgeConfig, logger?: GtLogger);
+    /**
+     * Initialize the bridge and verify gt is available
+     */
+    initialize(): Promise<void>;
+    /**
+     * Execute a gt command with validated arguments
+     *
+     * @param args - Command arguments (validated and sanitized)
+     * @returns Command output
+     */
+    execGt(args: string[], skipCache?: boolean): Promise<GtResult<string>>;
+    /**
+     * Parse JSON output from gt command
+     *
+     * @param output - Raw command output
+     * @returns Parsed JSON object
+     */
+    parseGtOutput<T>(output: string): T;
+    /**
+     * Estimate gas for a transaction
+     */
+    estimateGas(params: {
+        to: string;
+        data?: string;
+        value?: string;
+        from?: string;
+        network?: z.infer<typeof NetworkSchema>;
+    }): Promise<GasEstimate>;
+    /**
+     * Get transaction status
+     */
+    getTxStatus(txHash: string, network?: z.infer<typeof NetworkSchema>): Promise<TxStatus>;
+    /**
+     * Get network status
+     */
+    getNetworkStatus(network?: z.infer<typeof NetworkSchema>): Promise<NetworkStatus>;
+    /**
+     * Get current gas price
+     */
+    getGasPrice(network?: z.infer<typeof NetworkSchema>): Promise<{
+        gasPrice: string;
+        maxFeePerGas?: string;
+        maxPriorityFeePerGas?: string;
+        baseFee?: string;
+    }>;
+    /**
+     * Simulate a transaction
+     */
+    simulate(params: {
+        to: string;
+        data: string;
+        value?: string;
+        from?: string;
+        network?: z.infer<typeof NetworkSchema>;
+        blockNumber?: number;
+    }): Promise<{
+        success: boolean;
+        returnData?: string;
+        gasUsed?: number;
+        logs?: unknown[];
+        error?: string;
+    }>;
+    /**
+     * Decode transaction data
+     */
+    decode(data: string, abi?: string): Promise<{
+        method: string;
+        args: unknown[];
+        signature: string;
+    }>;
+    /**
+     * Validate and sanitize command arguments
+     */
+    private validateAndSanitizeArgs;
+    /**
+     * Ensure bridge is initialized
+     */
+    private ensureInitialized;
+    /**
+     * Check if bridge is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Get current configuration
+     */
+    getConfig(): Readonly<Required<GtBridgeConfig>>;
+    /**
+     * Get cache statistics for performance monitoring
+     */
+    getCacheStats(): {
+        resultCache: {
+            entries: number;
+            sizeBytes: number;
+        };
+        staticCache: {
+            entries: number;
+            sizeBytes: number;
+        };
+        parsedCache: {
+            entries: number;
+            sizeBytes: number;
+        };
+    };
+    /**
+     * Clear all caches (useful for testing or memory pressure)
+     */
+    clearCaches(): void;
+}
+/**
+ * Create a new Gas Town bridge instance
+ */
+declare function createGtBridge(config?: GtBridgeConfig, logger?: GtLogger): GtBridge;
+
+export { AddressSchema as A, GtBridge as G, IdentifierSchema as I, NetworkSchema as N, SafeStringSchema as S, TxHashSchema as T, type GasEstimate as a, GasLimitSchema as b, GasPriceSchema as c, GtArgumentSchema as d, type GtBridgeConfig as e, GtBridgeError as f, type GtErrorCode as g, type GtLogger as h, type GtResult as i, type NetworkStatus as j, type TxStatus as k, createGtBridge as l };