@almadar/cli 0.3.2 → 1.0.3

package/shells/typescript-shell/packages/client/src/evaluator/context.ts

@@ -0,0 +1,196 @@
+/**
+ * Evaluation Context
+ *
+ * Defines the context for evaluating S-expressions at runtime.
+ * This context provides access to entity data, payload, state, and effect handlers.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * User context for @user bindings (role-based UI).
+ */
+export interface UserContext {
+  /** User's unique ID */
+  id: string;
+  /** User's email */
+  email?: string;
+  /** User's display name */
+  name?: string;
+  /** User's role (for RBAC) */
+  role?: string;
+  /** User's permissions */
+  permissions?: string[];
+  /** Additional custom profile fields */
+  [key: string]: unknown;
+}
+
+/**
+ * Evaluation context for S-expression evaluation.
+ * Provides all bindings and effect handlers needed at runtime.
+ */
+export interface EvaluationContext {
+  /** Entity data for @entity bindings */
+  entity: Record<string, unknown>;
+
+  /** Payload data for @payload bindings */
+  payload: Record<string, unknown>;
+
+  /** Current state for @state binding */
+  state: string;
+
+  /** Current timestamp for @now binding (defaults to Date.now()) */
+  now: number;
+
+  /** User data for @user bindings (role-based UI) */
+  user?: UserContext;
+
+  /** Singleton entities for @EntityName bindings */
+  singletons: Map<string, Record<string, unknown>>;
+
+  /** Local variables from 'let' bindings */
+  locals?: Map<string, unknown>;
+
+  // ============================================================================
+  // Effect Handlers (for executing side effects)
+  // ============================================================================
+
+  /** Mutate entity fields */
+  mutateEntity?: (changes: Record<string, unknown>) => void;
+
+  /** Emit an event */
+  emit?: (event: string, payload?: unknown) => void;
+
+  /** Navigate to a route */
+  navigate?: (route: string, params?: Record<string, unknown>) => void;
+
+  /** Persist data (create/update/delete) */
+  persist?: (action: 'create' | 'update' | 'delete', data?: Record<string, unknown>) => Promise<void>;
+
+  /** Show a notification */
+  notify?: (message: string, type?: 'success' | 'error' | 'warning' | 'info') => void;
+
+  /** Spawn a new entity instance */
+  spawn?: (entityType: string, props?: Record<string, unknown>) => void;
+
+  /** Despawn an entity instance */
+  despawn?: (entityId?: string) => void;
+
+  /** Call an external service */
+  callService?: (service: string, method: string, params?: Record<string, unknown>) => Promise<unknown>;
+
+  /** Render UI to a slot */
+  renderUI?: (slot: string, pattern: unknown, props?: Record<string, unknown>, priority?: number) => void;
+}
+
+/**
+ * Create a minimal evaluation context for testing/guards.
+ * Only includes bindings, no effect handlers.
+ */
+export function createMinimalContext(
+  entity: Record<string, unknown> = {},
+  payload: Record<string, unknown> = {},
+  state: string = 'initial'
+): EvaluationContext {
+  return {
+    entity,
+    payload,
+    state,
+    now: Date.now(),
+    singletons: new Map(),
+  };
+}
+
+/**
+ * Create a context with effect handlers.
+ * Used for runtime evaluation where effects need to execute.
+ */
+export function createEffectContext(
+  base: EvaluationContext,
+  handlers: Partial<Pick<EvaluationContext,
+    'mutateEntity' | 'emit' | 'navigate' | 'persist' | 'notify' | 'spawn' | 'despawn' | 'callService' | 'renderUI'
+  >>
+): EvaluationContext {
+  return {
+    ...base,
+    ...handlers,
+  };
+}
+
+/**
+ * Create a child context with additional local bindings.
+ * Used for 'let' expressions.
+ */
+export function createChildContext(
+  parent: EvaluationContext,
+  locals: Map<string, unknown>
+): EvaluationContext {
+  // Merge parent locals with new locals
+  const mergedLocals = new Map(parent.locals);
+  locals.forEach((value, key) => mergedLocals.set(key, value));
+
+  return {
+    ...parent,
+    locals: mergedLocals,
+  };
+}
+
+/**
+ * Resolve a binding in the context.
+ *
+ * @param binding - Binding string (e.g., "@entity.health", "@payload.amount")
+ * @param ctx - Evaluation context
+ * @returns Resolved value or undefined
+ */
+export function resolveBinding(binding: string, ctx: EvaluationContext): unknown {
+  if (!binding.startsWith('@')) {
+    return undefined;
+  }
+
+  const withoutPrefix = binding.slice(1);
+  const parts = withoutPrefix.split('.');
+  const root = parts[0];
+  const path = parts.slice(1);
+
+  let value: unknown;
+
+  // Check locals first
+  if (ctx.locals?.has(root)) {
+    value = ctx.locals.get(root);
+  } else {
+    // Core bindings
+    switch (root) {
+      case 'entity':
+        value = ctx.entity;
+        break;
+      case 'payload':
+        value = ctx.payload;
+        break;
+      case 'state':
+        return ctx.state; // @state has no path
+      case 'now':
+        return ctx.now; // @now has no path
+      case 'user':
+        value = ctx.user;
+        break;
+      default:
+        // Singleton entity reference (@EntityName.field)
+        value = ctx.singletons.get(root);
+        break;
+    }
+  }
+
+  // Navigate path
+  for (const segment of path) {
+    if (value === null || value === undefined) {
+      return undefined;
+    }
+    if (typeof value === 'object') {
+      value = (value as Record<string, unknown>)[segment];
+    } else {
+      return undefined;
+    }
+  }
+
+  return value;
+}

package/shells/typescript-shell/packages/client/src/evaluator/index.ts

@@ -0,0 +1,52 @@
+/**
+ * S-Expression Evaluator Module
+ *
+ * Runtime interpreter for S-expressions.
+ * Provides evaluation of guards and execution of effects.
+ *
+ * This is the source of truth for S-expression evaluation.
+ * Other packages (builder, shells) should import from here.
+ *
+ * @packageDocumentation
+ */
+
+// Types
+export type { SExpr, SExprAtom, Expression, ParsedBinding, CoreBinding } from './types/expression.js';
+export {
+  isSExpr,
+  isSExprAtom,
+  isBinding,
+  isSExprCall,
+  parseBinding,
+  isValidBinding,
+  getOperator,
+  getArgs,
+  sexpr,
+  walkSExpr,
+  collectBindings,
+  SExprSchema,
+  ExpressionSchema,
+  CORE_BINDINGS,
+} from './types/expression.js';
+
+// Context
+export {
+  type EvaluationContext,
+  createMinimalContext,
+  createEffectContext,
+  createChildContext,
+  resolveBinding,
+} from './context.js';
+
+// Evaluator
+export {
+  SExpressionEvaluator,
+  evaluator,
+  evaluate,
+  evaluateGuard,
+  executeEffect,
+  executeEffects,
+} from './SExpressionEvaluator.js';
+
+// Operators (for advanced use cases)
+export * from './operators/index.js';

package/shells/typescript-shell/packages/client/src/evaluator/operators/arithmetic.ts

@@ -0,0 +1,120 @@
+/**
+ * Arithmetic Operator Implementations
+ *
+ * Implements: +, -, *, /, %, abs, min, max, floor, ceil, round, clamp
+ */
+
+import type { SExpr } from '../types/expression.js';
+import type { EvaluationContext } from '../context.js';
+
+type Evaluator = (expr: SExpr, ctx: EvaluationContext) => unknown;
+
+/**
+ * Evaluate addition: ["+", a, b, ...]
+ */
+export function evalAdd(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): number {
+  return args.reduce((sum: number, arg) => sum + toNumber(evaluate(arg, ctx)), 0);
+}
+
+/**
+ * Evaluate subtraction: ["-", a] (negate) or ["-", a, b] (subtract)
+ */
+export function evalSubtract(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): number {
+  if (args.length === 1) {
+    return -toNumber(evaluate(args[0], ctx));
+  }
+  return toNumber(evaluate(args[0], ctx)) - toNumber(evaluate(args[1], ctx));
+}
+
+/**
+ * Evaluate multiplication: ["*", a, b, ...]
+ */
+export function evalMultiply(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): number {
+  return args.reduce((product: number, arg) => product * toNumber(evaluate(arg, ctx)), 1);
+}
+
+/**
+ * Evaluate division: ["/", a, b]
+ */
+export function evalDivide(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): number {
+  const dividend = toNumber(evaluate(args[0], ctx));
+  const divisor = toNumber(evaluate(args[1], ctx));
+  if (divisor === 0) {
+    return dividend >= 0 ? Infinity : -Infinity;
+  }
+  return dividend / divisor;
+}
+
+/**
+ * Evaluate modulo: ["%", a, b]
+ */
+export function evalModulo(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): number {
+  return toNumber(evaluate(args[0], ctx)) % toNumber(evaluate(args[1], ctx));
+}
+
+/**
+ * Evaluate absolute value: ["abs", a]
+ */
+export function evalAbs(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): number {
+  return Math.abs(toNumber(evaluate(args[0], ctx)));
+}
+
+/**
+ * Evaluate minimum: ["min", a, b, ...]
+ */
+export function evalMin(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): number {
+  const values = args.map((arg) => toNumber(evaluate(arg, ctx)));
+  return Math.min(...values);
+}
+
+/**
+ * Evaluate maximum: ["max", a, b, ...]
+ */
+export function evalMax(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): number {
+  const values = args.map((arg) => toNumber(evaluate(arg, ctx)));
+  return Math.max(...values);
+}
+
+/**
+ * Evaluate floor: ["floor", a]
+ */
+export function evalFloor(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): number {
+  return Math.floor(toNumber(evaluate(args[0], ctx)));
+}
+
+/**
+ * Evaluate ceiling: ["ceil", a]
+ */
+export function evalCeil(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): number {
+  return Math.ceil(toNumber(evaluate(args[0], ctx)));
+}
+
+/**
+ * Evaluate round: ["round", a]
+ */
+export function evalRound(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): number {
+  return Math.round(toNumber(evaluate(args[0], ctx)));
+}
+
+/**
+ * Evaluate clamp: ["clamp", value, min, max]
+ */
+export function evalClamp(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): number {
+  const value = toNumber(evaluate(args[0], ctx));
+  const min = toNumber(evaluate(args[1], ctx));
+  const max = toNumber(evaluate(args[2], ctx));
+  return Math.max(min, Math.min(max, value));
+}
+
+/**
+ * Convert a value to a number, defaulting to 0 for non-numbers.
+ */
+function toNumber(value: unknown): number {
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string') {
+    const parsed = parseFloat(value);
+    return isNaN(parsed) ? 0 : parsed;
+  }
+  if (typeof value === 'boolean') return value ? 1 : 0;
+  return 0;
+}

package/shells/typescript-shell/packages/client/src/evaluator/operators/collections.ts

@@ -0,0 +1,177 @@
+/**
+ * Collection Operator Implementations
+ *
+ * Implements: map, filter, find, count, sum, first, last, nth, concat, includes, empty
+ */
+
+import type { SExpr } from '../types/expression.js';
+import type { EvaluationContext } from '../context.js';
+import { createChildContext } from '../context.js';
+
+type Evaluator = (expr: SExpr, ctx: EvaluationContext) => unknown;
+
+/**
+ * Evaluate map: ["map", collection, ["fn", varName, body]]
+ */
+export function evalMap(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): unknown[] {
+  const collection = toArray(evaluate(args[0], ctx));
+  const fnExpr = args[1] as SExpr[];
+
+  // Get function params and body
+  const params = fnExpr[1];
+  const body = fnExpr[2];
+  const varName = typeof params === 'string' ? params : (params as SExpr[])[0] as string;
+
+  return collection.map((item) => {
+    const locals = new Map<string, unknown>();
+    locals.set(varName, item);
+    const childCtx = createChildContext(ctx, locals);
+    return evaluate(body, childCtx);
+  });
+}
+
+/**
+ * Evaluate filter: ["filter", collection, ["fn", varName, predicate]]
+ */
+export function evalFilter(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): unknown[] {
+  const collection = toArray(evaluate(args[0], ctx));
+  const fnExpr = args[1] as SExpr[];
+
+  const params = fnExpr[1];
+  const body = fnExpr[2];
+  const varName = typeof params === 'string' ? params : (params as SExpr[])[0] as string;
+
+  return collection.filter((item) => {
+    const locals = new Map<string, unknown>();
+    locals.set(varName, item);
+    const childCtx = createChildContext(ctx, locals);
+    return Boolean(evaluate(body, childCtx));
+  });
+}
+
+/**
+ * Evaluate find: ["find", collection, ["fn", varName, predicate]]
+ */
+export function evalFind(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): unknown {
+  const collection = toArray(evaluate(args[0], ctx));
+  const fnExpr = args[1] as SExpr[];
+
+  const params = fnExpr[1];
+  const body = fnExpr[2];
+  const varName = typeof params === 'string' ? params : (params as SExpr[])[0] as string;
+
+  return collection.find((item) => {
+    const locals = new Map<string, unknown>();
+    locals.set(varName, item);
+    const childCtx = createChildContext(ctx, locals);
+    return Boolean(evaluate(body, childCtx));
+  });
+}
+
+/**
+ * Evaluate count: ["count", collection]
+ */
+export function evalCount(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): number {
+  const collection = toArray(evaluate(args[0], ctx));
+  return collection.length;
+}
+
+/**
+ * Evaluate sum: ["sum", collection] or ["sum", collection, ["fn", varName, mapper]]
+ */
+export function evalSum(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): number {
+  const collection = toArray(evaluate(args[0], ctx));
+
+  if (args.length === 1) {
+    // Direct sum
+    return collection.reduce((sum: number, item) => sum + toNumber(item), 0);
+  }
+
+  // Sum with mapper function
+  const fnExpr = args[1] as SExpr[];
+  const params = fnExpr[1];
+  const body = fnExpr[2];
+  const varName = typeof params === 'string' ? params : (params as SExpr[])[0] as string;
+
+  return collection.reduce((sum: number, item) => {
+    const locals = new Map<string, unknown>();
+    locals.set(varName, item);
+    const childCtx = createChildContext(ctx, locals);
+    return sum + toNumber(evaluate(body, childCtx));
+  }, 0);
+}
+
+/**
+ * Evaluate first: ["first", collection]
+ */
+export function evalFirst(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): unknown {
+  const collection = toArray(evaluate(args[0], ctx));
+  return collection.length > 0 ? collection[0] : undefined;
+}
+
+/**
+ * Evaluate last: ["last", collection]
+ */
+export function evalLast(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): unknown {
+  const collection = toArray(evaluate(args[0], ctx));
+  return collection.length > 0 ? collection[collection.length - 1] : undefined;
+}
+
+/**
+ * Evaluate nth: ["nth", collection, index]
+ */
+export function evalNth(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): unknown {
+  const collection = toArray(evaluate(args[0], ctx));
+  const index = toNumber(evaluate(args[1], ctx));
+  return collection[index];
+}
+
+/**
+ * Evaluate concat: ["concat", collection1, collection2, ...]
+ */
+export function evalConcat(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): unknown[] {
+  const result: unknown[] = [];
+  for (const arg of args) {
+    const collection = toArray(evaluate(arg, ctx));
+    result.push(...collection);
+  }
+  return result;
+}
+
+/**
+ * Evaluate includes: ["includes", collection, element]
+ */
+export function evalIncludes(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): boolean {
+  const collection = toArray(evaluate(args[0], ctx));
+  const element = evaluate(args[1], ctx);
+  return collection.includes(element);
+}
+
+/**
+ * Evaluate empty: ["empty", collection]
+ */
+export function evalEmpty(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): boolean {
+  const collection = toArray(evaluate(args[0], ctx));
+  return collection.length === 0;
+}
+
+/**
+ * Convert a value to an array.
+ */
+function toArray(value: unknown): unknown[] {
+  if (Array.isArray(value)) return value;
+  if (value === null || value === undefined) return [];
+  return [value];
+}
+
+/**
+ * Convert a value to a number.
+ */
+function toNumber(value: unknown): number {
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string') {
+    const parsed = parseFloat(value);
+    return isNaN(parsed) ? 0 : parsed;
+  }
+  return 0;
+}

package/shells/typescript-shell/packages/client/src/evaluator/operators/comparison.ts

@@ -0,0 +1,130 @@
+/**
+ * Comparison Operator Implementations
+ *
+ * Implements: =, !=, <, >, <=, >=
+ */
+
+import type { SExpr } from '../types/expression.js';
+import type { EvaluationContext } from '../context.js';
+
+type Evaluator = (expr: SExpr, ctx: EvaluationContext) => unknown;
+
+/**
+ * Evaluate equality: ["=", a, b]
+ * Uses strict equality (===) for type safety.
+ */
+export function evalEqual(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): boolean {
+  const left = evaluate(args[0], ctx);
+  const right = evaluate(args[1], ctx);
+  return deepEqual(left, right);
+}
+
+/**
+ * Evaluate not-equal: ["!=", a, b]
+ */
+export function evalNotEqual(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): boolean {
+  const left = evaluate(args[0], ctx);
+  const right = evaluate(args[1], ctx);
+  return !deepEqual(left, right);
+}
+
+/**
+ * Evaluate less-than: ["<", a, b]
+ */
+export function evalLessThan(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): boolean {
+  const left = evaluate(args[0], ctx);
+  const right = evaluate(args[1], ctx);
+  return toComparable(left) < toComparable(right);
+}
+
+/**
+ * Evaluate greater-than: [">", a, b]
+ */
+export function evalGreaterThan(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): boolean {
+  const left = evaluate(args[0], ctx);
+  const right = evaluate(args[1], ctx);
+  return toComparable(left) > toComparable(right);
+}
+
+/**
+ * Evaluate less-than-or-equal: ["<=", a, b]
+ */
+export function evalLessThanOrEqual(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): boolean {
+  const left = evaluate(args[0], ctx);
+  const right = evaluate(args[1], ctx);
+  return toComparable(left) <= toComparable(right);
+}
+
+/**
+ * Evaluate greater-than-or-equal: [">=", a, b]
+ */
+export function evalGreaterThanOrEqual(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): boolean {
+  const left = evaluate(args[0], ctx);
+  const right = evaluate(args[1], ctx);
+  return toComparable(left) >= toComparable(right);
+}
+
+/**
+ * Evaluate regex match: ["matches", subject, pattern]
+ * Returns true if subject matches the regex pattern.
+ */
+export function evalMatches(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): boolean {
+  const subject = evaluate(args[0], ctx);
+  const pattern = evaluate(args[1], ctx);
+
+  if (typeof subject !== 'string' || typeof pattern !== 'string') {
+    return false;
+  }
+
+  try {
+    const regex = new RegExp(pattern);
+    return regex.test(subject);
+  } catch {
+    // Invalid regex pattern
+    return false;
+  }
+}
+
+/**
+ * Deep equality check for objects and arrays.
+ */
+function deepEqual(a: unknown, b: unknown): boolean {
+  // Primitive equality
+  if (a === b) return true;
+
+  // Null/undefined checks
+  if (a === null || b === null) return a === b;
+  if (a === undefined || b === undefined) return a === b;
+
+  // Type checks
+  if (typeof a !== typeof b) return false;
+
+  // Array equality
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    return a.every((val, idx) => deepEqual(val, b[idx]));
+  }
+
+  // Object equality
+  if (typeof a === 'object' && typeof b === 'object') {
+    const keysA = Object.keys(a as object);
+    const keysB = Object.keys(b as object);
+    if (keysA.length !== keysB.length) return false;
+    return keysA.every((key) =>
+      deepEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key])
+    );
+  }
+
+  return false;
+}
+
+/**
+ * Convert to a comparable value for ordering operations.
+ */
+function toComparable(value: unknown): number | string {
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string') return value;
+  if (typeof value === 'boolean') return value ? 1 : 0;
+  if (value === null || value === undefined) return 0;
+  return String(value);
+}