@plures/praxis 0.2.0

package/src/registry.ts

@@ -0,0 +1,223 @@
+/**
+ * Registry for managing rules and constraints in Praxis.
+ * Provides registration, retrieval, and execution capabilities.
+ */
+
+import type { PraxisState, PraxisEvent, Effect } from './types.js';
+import type { Rule, Constraint, ConstraintViolation } from './dsl.js';
+
+/**
+ * Registry for managing rules and constraints.
+ */
+export class Registry<
+  S extends PraxisState = PraxisState,
+  E extends PraxisEvent = PraxisEvent
+> {
+  private rules: Map<string, Rule<S, E>> = new Map();
+  private constraints: Map<string, Constraint<S>> = new Map();
+
+  /**
+   * Register a new rule.
+   * @throws Error if a rule with the same ID already exists
+   */
+  registerRule(rule: Rule<S, E>): void {
+    if (this.rules.has(rule.id)) {
+      throw new Error(`Rule with id '${rule.id}' already exists`);
+    }
+    this.rules.set(rule.id, rule);
+  }
+
+  /**
+   * Register multiple rules at once.
+   */
+  registerRules(rules: Rule<S, E>[]): void {
+    for (const rule of rules) {
+      this.registerRule(rule);
+    }
+  }
+
+  /**
+   * Unregister a rule by ID.
+   */
+  unregisterRule(id: string): boolean {
+    return this.rules.delete(id);
+  }
+
+  /**
+   * Get a rule by ID.
+   */
+  getRule(id: string): Rule<S, E> | undefined {
+    return this.rules.get(id);
+  }
+
+  /**
+   * Get all registered rules.
+   */
+  getAllRules(): Rule<S, E>[] {
+    return Array.from(this.rules.values());
+  }
+
+  /**
+   * Get rules that match a specific event type.
+   */
+  getRulesForEvent(eventType: string): Rule<S, E>[] {
+    return Array.from(this.rules.values()).filter(
+      (rule) => !rule.eventType || rule.eventType === eventType
+    );
+  }
+
+  /**
+   * Register a new constraint.
+   * @throws Error if a constraint with the same ID already exists
+   */
+  registerConstraint(constraint: Constraint<S>): void {
+    if (this.constraints.has(constraint.id)) {
+      throw new Error(`Constraint with id '${constraint.id}' already exists`);
+    }
+    this.constraints.set(constraint.id, constraint);
+  }
+
+  /**
+   * Register multiple constraints at once.
+   */
+  registerConstraints(constraints: Constraint<S>[]): void {
+    for (const constraint of constraints) {
+      this.registerConstraint(constraint);
+    }
+  }
+
+  /**
+   * Unregister a constraint by ID.
+   */
+  unregisterConstraint(id: string): boolean {
+    return this.constraints.delete(id);
+  }
+
+  /**
+   * Get a constraint by ID.
+   */
+  getConstraint(id: string): Constraint<S> | undefined {
+    return this.constraints.get(id);
+  }
+
+  /**
+   * Get all registered constraints.
+   */
+  getAllConstraints(): Constraint<S>[] {
+    return Array.from(this.constraints.values());
+  }
+
+  /**
+   * Evaluate all rules for a given state and event.
+   * Returns all effects produced by rules that fire.
+   */
+  evaluateRules(state: S, event: E): Effect[] {
+    const effects: Effect[] = [];
+    
+    // Get rules that match the event type
+    const applicableRules = this.getRulesForEvent(event.type);
+    
+    // Sort by priority (higher priority first)
+    const sortedRules = applicableRules.sort(
+      (a, b) => (b.priority ?? 0) - (a.priority ?? 0)
+    );
+
+    // Evaluate each rule
+    for (const rule of sortedRules) {
+      try {
+        if (rule.when(state, event)) {
+          const ruleEffects = rule.then(state, event);
+          effects.push(...ruleEffects);
+        }
+      } catch (error) {
+        console.error(`Error evaluating rule '${rule.id}':`, error);
+      }
+    }
+
+    return effects;
+  }
+
+  /**
+   * Check all constraints for a given state.
+   * Returns an array of violations (empty if all constraints pass).
+   */
+  checkConstraints(state: S): ConstraintViolation[] {
+    const violations: ConstraintViolation[] = [];
+
+    for (const constraint of this.constraints.values()) {
+      try {
+        if (!constraint.check(state)) {
+          violations.push({
+            constraintId: constraint.id,
+            message:
+              constraint.errorMessage ||
+              `Constraint '${constraint.id}' violated`,
+            state,
+          });
+        }
+      } catch (error) {
+        violations.push({
+          constraintId: constraint.id,
+          message: `Error checking constraint '${constraint.id}': ${error}`,
+          state,
+        });
+      }
+    }
+
+    return violations;
+  }
+
+  /**
+   * Clear all rules from the registry.
+   */
+  clearRules(): void {
+    this.rules.clear();
+  }
+
+  /**
+   * Clear all constraints from the registry.
+   */
+  clearConstraints(): void {
+    this.constraints.clear();
+  }
+
+  /**
+   * Clear all rules and constraints from the registry.
+   */
+  clear(): void {
+    this.clearRules();
+    this.clearConstraints();
+  }
+
+  /**
+   * Get statistics about the registry.
+   */
+  getStats(): {
+    ruleCount: number;
+    constraintCount: number;
+    rulesByEventType: Record<string, number>;
+  } {
+    const rulesByEventType: Record<string, number> = {};
+    
+    for (const rule of this.rules.values()) {
+      const eventType = rule.eventType || '*';
+      rulesByEventType[eventType] = (rulesByEventType[eventType] || 0) + 1;
+    }
+
+    return {
+      ruleCount: this.rules.size,
+      constraintCount: this.constraints.size,
+      rulesByEventType,
+    };
+  }
+}
+
+/**
+ * Create a new registry instance.
+ */
+export function createRegistry<
+  S extends PraxisState = PraxisState,
+  E extends PraxisEvent = PraxisEvent
+>(): Registry<S, E> {
+  return new Registry<S, E>();
+}

package/src/runtime/terminal-adapter.ts

@@ -0,0 +1,175 @@
+/**
+ * Terminal Node Runtime Adapter
+ * 
+ * Handles terminal command execution and state management.
+ * Integrates with pluresDB for state synchronization.
+ */
+
+import type { TerminalNodeProps } from '../core/schema/types.js';
+
+/**
+ * Terminal command execution result
+ */
+export interface TerminalExecutionResult {
+  /** Command that was executed */
+  command: string;
+  /** Output from the command */
+  output: string;
+  /** Exit code (0 for success) */
+  exitCode: number;
+  /** Execution timestamp */
+  timestamp: number;
+  /** Error message if execution failed */
+  error?: string;
+}
+
+/**
+ * Terminal node state
+ */
+export interface TerminalNodeState extends TerminalNodeProps {
+  /** Node identifier */
+  nodeId: string;
+  /** Current working directory */
+  cwd?: string;
+  /** Environment variables */
+  env?: Record<string, string>;
+}
+
+/**
+ * Terminal adapter options
+ */
+export interface TerminalAdapterOptions {
+  /** Node identifier */
+  nodeId: string;
+  /** Initial props */
+  props?: Partial<TerminalNodeProps>;
+  /** PluresDB path for input binding */
+  inputPath?: string;
+  /** PluresDB path for output binding */
+  outputPath?: string;
+}
+
+/**
+ * Terminal Runtime Adapter
+ * 
+ * Manages terminal node execution and state.
+ * 
+ * Note: PluresDB input/output path bindings will be implemented
+ * when pluresDB integration is complete.
+ */
+export class TerminalAdapter {
+  private state: TerminalNodeState;
+  private outputPath?: string;
+
+  constructor(options: TerminalAdapterOptions) {
+    this.state = {
+      nodeId: options.nodeId,
+      inputMode: options.props?.inputMode || 'text',
+      history: options.props?.history || [],
+      lastOutput: options.props?.lastOutput || null,
+    };
+    // TODO: Store inputPath when pluresDB integration is complete
+    // const inputPath = options.inputPath;
+    this.outputPath = options.outputPath;
+  }
+
+  /**
+   * Execute a terminal command
+   * 
+   * @param command - Command to execute
+   * @returns Execution result
+   */
+  async executeCommand(command: string): Promise<TerminalExecutionResult> {
+    // Add to history
+    this.state.history.push(command);
+
+    // TODO: Integrate with RuneBook execution model
+    // For now, return a stubbed response
+    const result: TerminalExecutionResult = {
+      command,
+      output: `[Stub] Command received: ${command}\nIntegration with RuneBook pending.`,
+      exitCode: 0,
+      timestamp: Date.now(),
+    };
+
+    // Update last output
+    this.state.lastOutput = result.output;
+
+    // TODO: Sync to pluresDB output path when integration is available
+    if (this.outputPath) {
+      await this.syncToPluresDB(this.outputPath, result);
+    }
+
+    return result;
+  }
+
+  /**
+   * Get current terminal state
+   */
+  getState(): Readonly<TerminalNodeState> {
+    return { ...this.state };
+  }
+
+  /**
+   * Update terminal props
+   */
+  updateProps(props: Partial<TerminalNodeProps>): void {
+    this.state = {
+      ...this.state,
+      ...props,
+    };
+  }
+
+  /**
+   * Clear command history
+   */
+  clearHistory(): void {
+    this.state.history = [];
+  }
+
+  /**
+   * Get command history
+   */
+  getHistory(): ReadonlyArray<string> {
+    return [...this.state.history];
+  }
+
+  /**
+   * Sync state to pluresDB (placeholder)
+   * 
+   * @param _path - PluresDB path (unused until integration is complete)
+   * @param _data - Data to sync (unused until integration is complete)
+   */
+  private async syncToPluresDB(_path: string, _data: unknown): Promise<void> {
+    // TODO: Implement pluresDB sync when integration is available
+    // When implemented, this will sync terminal output to the specified pluresDB path
+    // for reactive state management across the application
+  }
+}
+
+/**
+ * Create a terminal adapter instance
+ * 
+ * @param options - Terminal adapter options
+ * @returns Terminal adapter instance
+ */
+export function createTerminalAdapter(
+  options: TerminalAdapterOptions
+): TerminalAdapter {
+  return new TerminalAdapter(options);
+}
+
+/**
+ * Run a terminal command (convenience function)
+ * 
+ * @param nodeId - Terminal node identifier
+ * @param command - Command to execute
+ * @returns Execution result
+ */
+export async function runTerminalCommand(
+  nodeId: string,
+  command: string
+): Promise<TerminalExecutionResult> {
+  const adapter = createTerminalAdapter({ nodeId });
+  return adapter.executeCommand(command);
+}

package/src/step.ts

@@ -0,0 +1,151 @@
+/**
+ * Core step function implementation for Praxis.
+ * Pure function that transitions from one state to another given an event.
+ */
+
+import type { PraxisState, PraxisEvent, StepResult, StepFunction } from './types.js';
+import type { Registry } from './registry.js';
+
+/**
+ * Options for creating a step function.
+ */
+export interface StepOptions<
+  S extends PraxisState = PraxisState,
+  E extends PraxisEvent = PraxisEvent
+> {
+  /** Registry containing rules and constraints */
+  registry?: Registry<S, E>;
+  /** Whether to check constraints before and after state transitions */
+  checkConstraints?: boolean;
+  /** Custom reducer function for state transitions */
+  reducer?: (state: S, event: E) => S;
+}
+
+/**
+ * Create a step function that integrates with the registry.
+ * This is the main entry point for creating state transition logic.
+ */
+export function createStepFunction<
+  S extends PraxisState = PraxisState,
+  E extends PraxisEvent = PraxisEvent
+>(options: StepOptions<S, E> = {}): StepFunction<S, E> {
+  const { registry, checkConstraints = true, reducer } = options;
+
+  return (state: S, event: E): StepResult<S> => {
+    const errors: string[] = [];
+
+    // Check constraints before transition
+    if (checkConstraints && registry) {
+      const violations = registry.checkConstraints(state);
+      if (violations.length > 0) {
+        errors.push(
+          ...violations.map((v) => `Pre-condition: ${v.message}`)
+        );
+        // Return current state with errors
+        return { state, errors };
+      }
+    }
+
+    // Apply the reducer to get the new state
+    let newState: S;
+    if (reducer) {
+      try {
+        newState = reducer(state, event);
+      } catch (error) {
+        errors.push(`Reducer error: ${error}`);
+        return { state, errors };
+      }
+    } else {
+      // Default behavior: merge event data into facts
+      newState = {
+        ...state,
+        facts: {
+          ...state.facts,
+          ...(event.data || {}),
+        },
+        metadata: {
+          ...state.metadata,
+          lastUpdated: event.timestamp,
+          version: (state.metadata?.version || 0) + 1,
+        },
+      } as S;
+    }
+
+    // Evaluate rules to get effects
+    const effects = registry ? registry.evaluateRules(newState, event) : [];
+
+    // Check constraints after transition
+    if (checkConstraints && registry) {
+      const violations = registry.checkConstraints(newState);
+      if (violations.length > 0) {
+        errors.push(
+          ...violations.map((v) => `Post-condition: ${v.message}`)
+        );
+        // Return previous state with errors to maintain invariants
+        return { state, errors };
+      }
+    }
+
+    return {
+      state: newState,
+      effects,
+      errors: errors.length > 0 ? errors : undefined,
+    };
+  };
+}
+
+/**
+ * Simple step function that just applies a reducer.
+ * Useful for basic state transitions without rules or constraints.
+ */
+export function step<
+  S extends PraxisState = PraxisState,
+  E extends PraxisEvent = PraxisEvent
+>(reducer: (state: S, event: E) => S): StepFunction<S, E> {
+  return (state: S, event: E): StepResult<S> => {
+    try {
+      const newState = reducer(state, event);
+      return { state: newState };
+    } catch (error) {
+      return {
+        state,
+        errors: [`Step error: ${error}`],
+      };
+    }
+  };
+}
+
+/**
+ * Compose multiple step functions into a single step function.
+ * Each step function is applied in sequence, with the output of one
+ * becoming the input to the next.
+ */
+export function compose<
+  S extends PraxisState = PraxisState,
+  E extends PraxisEvent = PraxisEvent
+>(...steps: StepFunction<S, E>[]): StepFunction<S, E> {
+  return (state: S, event: E): StepResult<S> => {
+    let currentState = state;
+    const allEffects: StepResult<S>['effects'] = [];
+    const allErrors: string[] = [];
+
+    for (const stepFn of steps) {
+      const result = stepFn(currentState, event);
+      currentState = result.state;
+
+      if (result.effects) {
+        allEffects.push(...result.effects);
+      }
+
+      if (result.errors) {
+        allErrors.push(...result.errors);
+      }
+    }
+
+    return {
+      state: currentState,
+      effects: allEffects.length > 0 ? allEffects : undefined,
+      errors: allErrors.length > 0 ? allErrors : undefined,
+    };
+  };
+}

package/src/types.ts

@@ -0,0 +1,70 @@
+/**
+ * Core types for Praxis - A TypeScript library for typed, functional application logic.
+ * All types are designed to be JSON-friendly for serialization and interoperability.
+ */
+
+/**
+ * Base type for all Praxis events.
+ * Events represent things that have happened and trigger state transitions.
+ */
+export interface PraxisEvent {
+  /** Unique identifier for the event type */
+  type: string;
+  /** Timestamp when the event occurred */
+  timestamp: number;
+  /** Additional event data (must be JSON-serializable) */
+  data?: Record<string, unknown>;
+  /** Optional metadata for tracing and debugging */
+  metadata?: {
+    correlationId?: string;
+    source?: string;
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Base type for all Praxis state.
+ * State represents the current facts and context of the application.
+ */
+export interface PraxisState {
+  /** Current facts - immutable truths about the system */
+  facts: Record<string, unknown>;
+  /** Optional metadata for debugging and inspection */
+  metadata?: {
+    version?: number;
+    lastUpdated?: number;
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Result of a state transition step.
+ * Contains the new state and any side effects to be executed.
+ */
+export interface StepResult<S extends PraxisState = PraxisState> {
+  /** The new state after applying the event */
+  state: S;
+  /** Side effects to be executed (e.g., commands, events to emit) */
+  effects?: Effect[];
+  /** Optional errors or warnings that occurred during the step */
+  errors?: string[];
+}
+
+/**
+ * Represents a side effect to be executed outside the pure step function.
+ */
+export interface Effect {
+  /** Type of the effect */
+  type: string;
+  /** Effect payload (must be JSON-serializable) */
+  payload?: Record<string, unknown>;
+}
+
+/**
+ * A pure function that transitions from one state to another given an event.
+ * This is the core abstraction of Praxis.
+ */
+export type StepFunction<
+  S extends PraxisState = PraxisState,
+  E extends PraxisEvent = PraxisEvent
+> = (state: S, event: E) => StepResult<S>;