@almadar/runtime 2.1.1 → 2.2.0

package/dist/{OrbitalServerRuntime-CNyOL8XD.d.ts → OrbitalServerRuntime-YLqyxdjz.d.ts}

@@ -1,5 +1,5 @@
 import { Router } from 'express';
-import { I as IEventBus, i as RuntimeEvent, h as EventListener, U as Unsubscribe, E as EffectHandlers, g as Effect, T as TraitState } from './types-9hbY6RWC.js';
+import { I as IEventBus, i as RuntimeEvent, h as EventListener, U as Unsubscribe, E as EffectHandlers, g as Effect, T as TraitState } from './types-E5o2Jqe6.js';
 import { OrbitalSchema, Orbital, Trait } from '@almadar/core';
 
 /**
@@ -429,6 +429,11 @@ interface RuntimeOrbital {
         fields?: Array<{
             name: string;
             type: string;
+            relation?: {
+                entity?: string;
+                cardinality?: string;
+                onDelete?: string;
+            };
         }>;
         /** Pre-defined entity instances to seed on registration */
         instances?: Array<Record<string, unknown>>;
@@ -597,6 +602,7 @@ declare class OrbitalServerRuntime {
     private preprocessedCache;
     private entitySharingMap;
     private eventNamespaceMap;
+    private osHandlers;
     constructor(config?: OrbitalServerRuntimeConfig);
     /**
      * Register an OrbitalSchema for execution.
@@ -720,6 +726,17 @@ declare class OrbitalServerRuntime {
      * @param entityType - Entity type name
      * @param include - Relation field names to populate
      */
+    /**
+     * Validate that relation field values match their declared cardinality.
+     * Called before create/update to ensure data integrity.
+     */
+    private validateRelationCardinality;
+    /**
+     * Enforce onDelete rules for relation fields pointing to the entity being deleted.
+     * Scans all registered entities for relation fields targeting the given entity type,
+     * finds records referencing the ID being deleted, and applies cascade/nullify/restrict.
+     */
+    private enforceOnDeleteRules;
     private populateRelations;
     /**
      * Create Express router for orbital API endpoints

package/dist/OrbitalServerRuntime.d.ts

@@ -1,4 +1,4 @@
 import 'express';
-export { n as EffectResult, L as LoaderConfig, O as OrbitalEventRequest, c as OrbitalEventResponse, o as OrbitalServerRuntime, d as OrbitalServerRuntimeConfig, P as PersistenceAdapter, R as RuntimeOrbital, h as RuntimeOrbitalSchema, i as RuntimeTrait, q as RuntimeTraitTick, r as createOrbitalServerRuntime } from './OrbitalServerRuntime-CNyOL8XD.js';
-import './types-9hbY6RWC.js';
+export { n as EffectResult, L as LoaderConfig, O as OrbitalEventRequest, c as OrbitalEventResponse, o as OrbitalServerRuntime, d as OrbitalServerRuntimeConfig, P as PersistenceAdapter, R as RuntimeOrbital, h as RuntimeOrbitalSchema, i as RuntimeTrait, q as RuntimeTraitTick, r as createOrbitalServerRuntime } from './OrbitalServerRuntime-YLqyxdjz.js';
+import './types-E5o2Jqe6.js';
 import '@almadar/core';

package/dist/OrbitalServerRuntime.js

@@ -1,7 +1,10 @@
-import { EventBus, createUnifiedLoader, preprocessSchema, StateMachineManager, createContextFromBindings, EffectExecutor } from './chunk-UBXKXCSM.js';
+import { EventBus, createUnifiedLoader, preprocessSchema, StateMachineManager, createContextFromBindings, EffectExecutor } from './chunk-54P2HYHQ.js';
 import { Router } from 'express';
 import { evaluateGuard } from '@almadar/evaluator';
 import { faker } from '@faker-js/faker';
+import * as fs from 'fs';
+import * as net from 'net';
+import { execSync } from 'child_process';
 
 var MockPersistenceAdapter = class {
   stores = /* @__PURE__ */ new Map();
@@ -263,6 +266,258 @@ var MockPersistenceAdapter = class {
     return store.size;
   }
 };
+function globToRegex(glob) {
+  let regex = "";
+  let i = 0;
+  while (i < glob.length) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        regex += ".*";
+        i += 2;
+        if (glob[i] === "/") i++;
+        continue;
+      }
+      regex += "[^/]*";
+    } else if (c === "?") {
+      regex += "[^/]";
+    } else if (c === ".") {
+      regex += "\\.";
+    } else if (c === "/" || c === "-" || c === "_") {
+      regex += c;
+    } else if (/[{}()[\]^$+|\\]/.test(c)) {
+      regex += "\\" + c;
+    } else {
+      regex += c;
+    }
+    i++;
+  }
+  return new RegExp("^" + regex + "$");
+}
+function parseCronField(field, min, max) {
+  const values = /* @__PURE__ */ new Set();
+  for (const part of field.split(",")) {
+    if (part === "*") {
+      for (let i = min; i <= max; i++) values.add(i);
+    } else if (part.includes("/")) {
+      const [range, stepStr] = part.split("/");
+      const step = parseInt(stepStr, 10);
+      const start = range === "*" ? min : parseInt(range, 10);
+      for (let i = start; i <= max; i += step) values.add(i);
+    } else if (part.includes("-")) {
+      const [lo, hi] = part.split("-").map(Number);
+      for (let i = lo; i <= hi; i++) values.add(i);
+    } else {
+      values.add(parseInt(part, 10));
+    }
+  }
+  return values;
+}
+function parseCron(expression) {
+  const parts = expression.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    throw new Error(`Invalid cron expression (expected 5 fields): ${expression}`);
+  }
+  return {
+    minute: parseCronField(parts[0], 0, 59),
+    hour: parseCronField(parts[1], 0, 23),
+    day: parseCronField(parts[2], 1, 31),
+    month: parseCronField(parts[3], 1, 12),
+    weekday: parseCronField(parts[4], 0, 6)
+  };
+}
+function cronMatches(fields, date) {
+  return fields.minute.has(date.getMinutes()) && fields.hour.has(date.getHours()) && fields.day.has(date.getDate()) && fields.month.has(date.getMonth() + 1) && fields.weekday.has(date.getDay());
+}
+function createOsHandlers(ctx) {
+  const cwd = ctx.cwd ?? process.cwd();
+  const watchers = [];
+  const intervals = [];
+  const signalHandlers = [];
+  let httpWatchActive = false;
+  const debounceConfig = /* @__PURE__ */ new Map();
+  const debounceTimers = /* @__PURE__ */ new Map();
+  function debouncedEmit(eventType, payload) {
+    const ms = debounceConfig.get(eventType);
+    if (ms !== void 0 && ms > 0) {
+      const existing = debounceTimers.get(eventType);
+      if (existing) clearTimeout(existing);
+      debounceTimers.set(
+        eventType,
+        setTimeout(() => {
+          debounceTimers.delete(eventType);
+          ctx.emitEvent(eventType, payload);
+        }, ms)
+      );
+    } else {
+      ctx.emitEvent(eventType, payload);
+    }
+  }
+  const handlers = {
+    osWatchFiles: (glob, options) => {
+      const recursive = options.recursive !== false;
+      const pattern = globToRegex(glob);
+      try {
+        const watcher = fs.watch(cwd, { recursive }, (_event, filename) => {
+          if (filename && pattern.test(filename)) {
+            debouncedEmit("OS_FILE_MODIFIED", {
+              file: filename,
+              glob,
+              cwd
+            });
+          }
+        });
+        watchers.push(watcher);
+      } catch (err) {
+        console.warn("[os/watch-files] Failed to start watcher:", err);
+      }
+    },
+    osWatchProcess: (name, subcommand) => {
+      const searchTerm = subcommand ? `${name} ${subcommand}` : name;
+      let wasRunning = false;
+      const interval = setInterval(() => {
+        let isRunning = false;
+        try {
+          const result = execSync(`pgrep -f "${searchTerm}" 2>/dev/null`, {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"]
+          });
+          isRunning = result.trim().length > 0;
+        } catch {
+          isRunning = false;
+        }
+        if (isRunning && !wasRunning) {
+          debouncedEmit("OS_PROCESS_STARTED", { process: name, subcommand: subcommand ?? null });
+        } else if (!isRunning && wasRunning) {
+          debouncedEmit("OS_PROCESS_EXITED", { process: name, subcommand: subcommand ?? null });
+        }
+        wasRunning = isRunning;
+      }, 2e3);
+      intervals.push(interval);
+    },
+    osWatchPort: (port, protocol) => {
+      if (protocol !== "tcp") {
+        console.warn(`[os/watch-port] Only TCP is supported, got: ${protocol}`);
+        return;
+      }
+      let wasOpen = false;
+      const interval = setInterval(() => {
+        const socket = new net.Socket();
+        socket.setTimeout(1e3);
+        socket.on("connect", () => {
+          socket.destroy();
+          if (!wasOpen) {
+            wasOpen = true;
+            debouncedEmit("OS_PORT_OPENED", { port, protocol });
+          }
+        });
+        socket.on("error", () => {
+          socket.destroy();
+          if (wasOpen) {
+            wasOpen = false;
+            debouncedEmit("OS_PORT_CLOSED", { port, protocol });
+          }
+        });
+        socket.on("timeout", () => {
+          socket.destroy();
+          if (wasOpen) {
+            wasOpen = false;
+            debouncedEmit("OS_PORT_CLOSED", { port, protocol });
+          }
+        });
+        socket.connect(port, "127.0.0.1");
+      }, 3e3);
+      intervals.push(interval);
+    },
+    osWatchHttp: (urlPattern, method) => {
+      if (!httpWatchActive) {
+        httpWatchActive = true;
+        console.warn(
+          `[os/watch-http] HTTP interception is only supported in compiled mode. Pattern: ${urlPattern}${method ? `, method: ${method}` : ""}`
+        );
+      }
+    },
+    osWatchCron: (expression) => {
+      let fields;
+      try {
+        fields = parseCron(expression);
+      } catch (err) {
+        console.warn("[os/watch-cron] Invalid expression:", err);
+        return;
+      }
+      let lastFired = -1;
+      const interval = setInterval(() => {
+        const now = /* @__PURE__ */ new Date();
+        const minuteKey = now.getFullYear() * 1e8 + now.getMonth() * 1e6 + now.getDate() * 1e4 + now.getHours() * 100 + now.getMinutes();
+        if (minuteKey !== lastFired && cronMatches(fields, now)) {
+          lastFired = minuteKey;
+          debouncedEmit("OS_CRON_FIRE", {
+            expression,
+            firedAt: now.toISOString()
+          });
+        }
+      }, 1e3);
+      intervals.push(interval);
+    },
+    osWatchSignal: (signal) => {
+      const sig = signal.toUpperCase();
+      const handler = () => {
+        debouncedEmit(`OS_SIGNAL_${sig}`, { signal: sig });
+      };
+      try {
+        process.on(sig, handler);
+        signalHandlers.push({ signal: sig, handler });
+      } catch (err) {
+        console.warn(`[os/watch-signal] Cannot listen for ${sig}:`, err);
+      }
+    },
+    osWatchEnv: (variable) => {
+      let lastValue = process.env[variable];
+      const interval = setInterval(() => {
+        const current = process.env[variable];
+        if (current !== lastValue) {
+          const previous = lastValue;
+          lastValue = current;
+          debouncedEmit("OS_ENV_CHANGED", {
+            variable,
+            value: current ?? null,
+            previous: previous ?? null
+          });
+        }
+      }, 1e3);
+      intervals.push(interval);
+    },
+    osDebounce: (ms, eventType) => {
+      debounceConfig.set(eventType, ms);
+    }
+  };
+  function cleanup() {
+    for (const w of watchers) {
+      try {
+        w.close();
+      } catch {
+      }
+    }
+    watchers.length = 0;
+    for (const i of intervals) {
+      clearInterval(i);
+    }
+    intervals.length = 0;
+    for (const { signal, handler } of signalHandlers) {
+      try {
+        process.removeListener(signal, handler);
+      } catch {
+      }
+    }
+    signalHandlers.length = 0;
+    httpWatchActive = false;
+    for (const timer of debounceTimers.values()) {
+      clearTimeout(timer);
+    }
+    debounceTimers.clear();
+  }
+  return { handlers, cleanup };
+}
 
 // src/OrbitalServerRuntime.ts
 var InMemoryPersistence = class {
@@ -305,6 +560,7 @@ var OrbitalServerRuntime = class {
   preprocessedCache = /* @__PURE__ */ new Map();
   entitySharingMap = {};
   eventNamespaceMap = {};
+  osHandlers = null;
   constructor(config = {}) {
     this.config = {
       mode: "mock",
@@ -333,6 +589,13 @@ var OrbitalServerRuntime = class {
     } else {
       this.persistence = config.persistence || new InMemoryPersistence();
     }
+    this.osHandlers = createOsHandlers({
+      emitEvent: (type, payload) => this.eventBus.emit(type, payload)
+    });
+    this.config.effectHandlers = {
+      ...this.osHandlers.handlers,
+      ...this.config.effectHandlers
+    };
   }
   // ==========================================================================
   // Schema Registration
@@ -760,6 +1023,10 @@ var OrbitalServerRuntime = class {
     this.listenerCleanups = [];
     this.orbitals.clear();
     this.eventBus.clear();
+    if (this.osHandlers) {
+      this.osHandlers.cleanup();
+      this.osHandlers = null;
+    }
   }
   // ==========================================================================
   // Event Processing
@@ -952,6 +1219,9 @@ var OrbitalServerRuntime = class {
         const type = targetEntityType || entityType;
         let resultData;
         try {
+          if (action === "create" || action === "update") {
+            this.validateRelationCardinality(type, data || {});
+          }
           switch (action) {
             case "create": {
               const { id } = await this.persistence.create(type, data || {});
@@ -969,6 +1239,7 @@ var OrbitalServerRuntime = class {
             case "delete":
               if (data?.id || entityId) {
                 const deleteId = data?.id || entityId;
+                await this.enforceOnDeleteRules(type, deleteId);
                 await this.persistence.delete(type, deleteId);
                 resultData = { id: deleteId, deleted: true };
               }
@@ -1109,7 +1380,109 @@ var OrbitalServerRuntime = class {
    * @param entityType - Entity type name
    * @param include - Relation field names to populate
    */
-  async populateRelations(entities, entityType, include) {
+  /**
+   * Validate that relation field values match their declared cardinality.
+   * Called before create/update to ensure data integrity.
+   */
+  validateRelationCardinality(entityType, data) {
+    for (const [, registered] of this.orbitals) {
+      if (registered.schema.entity.name !== entityType) continue;
+      for (const field of registered.schema.entity.fields ?? []) {
+        if (field.type !== "relation") continue;
+        const value = data[field.name];
+        if (value === void 0 || value === null) continue;
+        const cardinality = field.relation?.cardinality || "one";
+        if (cardinality === "one" || cardinality === "many-to-one") {
+          if (Array.isArray(value)) {
+            throw new Error(
+              `Cardinality violation: ${entityType}.${field.name} has cardinality '${cardinality}' but received an array. Expected a single string ID.`
+            );
+          }
+        } else if (cardinality === "many" || cardinality === "many-to-many" || cardinality === "one-to-many") {
+          if (typeof value === "string") {
+            data[field.name] = [value];
+          } else if (Array.isArray(value)) {
+            const nonStrings = value.filter((v) => typeof v !== "string");
+            if (nonStrings.length > 0) {
+              throw new Error(
+                `Cardinality violation: ${entityType}.${field.name} has cardinality '${cardinality}' but array contains non-string values.`
+              );
+            }
+          }
+        }
+      }
+      break;
+    }
+  }
+  /**
+   * Enforce onDelete rules for relation fields pointing to the entity being deleted.
+   * Scans all registered entities for relation fields targeting the given entity type,
+   * finds records referencing the ID being deleted, and applies cascade/nullify/restrict.
+   */
+  async enforceOnDeleteRules(entityType, deletedId) {
+    for (const [, registered] of this.orbitals) {
+      const schema = registered.schema;
+      const fields = schema.entity.fields ?? [];
+      for (const field of fields) {
+        if (field.type !== "relation") continue;
+        if (field.relation?.entity !== entityType) continue;
+        const onDelete = field.relation.onDelete || "restrict";
+        const referringEntityType = schema.entity.name;
+        const allRecords = await this.persistence.list(referringEntityType);
+        const affectedRecords = allRecords.filter((record) => {
+          const fkValue = record[field.name];
+          if (typeof fkValue === "string") return fkValue === deletedId;
+          if (Array.isArray(fkValue)) return fkValue.includes(deletedId);
+          return false;
+        });
+        if (affectedRecords.length === 0) continue;
+        switch (onDelete) {
+          case "restrict":
+            throw new Error(
+              `Cannot delete ${entityType} ${deletedId}: ${affectedRecords.length} ${referringEntityType} record(s) reference it via ${field.name}. Rule: restrict.`
+            );
+          case "cascade":
+            for (const record of affectedRecords) {
+              const recordId = record.id;
+              if (recordId) {
+                await this.persistence.delete(referringEntityType, recordId);
+              }
+            }
+            if (this.config.debug) {
+              console.log(`[OrbitalRuntime] Cascade deleted ${affectedRecords.length} ${referringEntityType} records`);
+            }
+            break;
+          case "nullify":
+            for (const record of affectedRecords) {
+              const recordId = record.id;
+              if (recordId) {
+                const update = {};
+                const fkValue = record[field.name];
+                if (Array.isArray(fkValue)) {
+                  update[field.name] = fkValue.filter((id) => id !== deletedId);
+                } else {
+                  update[field.name] = null;
+                }
+                await this.persistence.update(referringEntityType, recordId, update);
+              }
+            }
+            if (this.config.debug) {
+              console.log(`[OrbitalRuntime] Nullified ${field.name} on ${affectedRecords.length} ${referringEntityType} records`);
+            }
+            break;
+        }
+      }
+    }
+  }
+  async populateRelations(entities, entityType, include, depth = 0, visited = /* @__PURE__ */ new Set()) {
+    const maxDepth = 2;
+    if (depth >= maxDepth || visited.has(entityType)) {
+      if (this.config.debug) {
+        console.log(`[OrbitalRuntime] Skipping populateRelations for ${entityType}: depth=${depth}, visited=${visited.has(entityType)}`);
+      }
+      return;
+    }
+    visited.add(entityType);
     let entityFields;
     for (const [, registered] of this.orbitals) {
       if (registered.schema.entity.name === entityType) {
@@ -1142,6 +1515,12 @@ var OrbitalServerRuntime = class {
         const fkValue = entity[foreignKeyField];
         if (fkValue && typeof fkValue === "string") {
           foreignKeyIds.add(fkValue);
+        } else if (Array.isArray(fkValue)) {
+          for (const id of fkValue) {
+            if (id && typeof id === "string") {
+              foreignKeyIds.add(id);
+            }
+          }
         }
       }
       if (foreignKeyIds.size === 0) continue;
@@ -1161,10 +1540,14 @@ var OrbitalServerRuntime = class {
       const populatedFieldName = includeField.endsWith("Id") ? includeField.slice(0, -2) : includeField;
       for (const entity of entities) {
         const fkValue = entity[foreignKeyField];
-        if (fkValue && relatedEntities.has(fkValue)) {
-          if (cardinality === "one") {
+        if (cardinality === "one" || cardinality === "many-to-one") {
+          if (typeof fkValue === "string" && relatedEntities.has(fkValue)) {
             entity[populatedFieldName] = relatedEntities.get(fkValue);
-          } else {
+          }
+        } else {
+          if (Array.isArray(fkValue)) {
+            entity[populatedFieldName] = fkValue.filter((id) => typeof id === "string").map((id) => relatedEntities.get(id)).filter(Boolean);
+          } else if (typeof fkValue === "string" && relatedEntities.has(fkValue)) {
             entity[populatedFieldName] = [relatedEntities.get(fkValue)];
           }
         }