@almadar/runtime 2.1.2 → 2.2.1

package/LICENSE

@@ -1,21 +1,72 @@
-MIT License
-
-Copyright (c) 2026 Almadar Team
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Almadar FZE
+Licensed Work:        KFlow Builder / Almadar
+                      The Licensed Work is (c) 2025-2026 Almadar FZE.
+Additional Use Grant: You may make production use of the Licensed Work for
+                      non-commercial purposes and for internal evaluation.
+                      Production use for commercial purposes requires a
+                      commercial license from the Licensor.
+Change Date:          2030-02-01
+Change License:       Apache License, Version 2.0
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+---
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+ADDITIONAL TERMS:
+
+Documentation (builder/packages/website/docs/) is licensed under CC BY 4.0.
+
+TRADEMARKS:
+
+"Orbital", "KFlow", "Almadar", and the Almadar logo are trademarks of
+Almadar FZE. You may not use these trademarks without prior written
+permission from Almadar FZE.
+
+For licensing inquiries: licensing@almadar.io

package/README.md

@@ -22,4 +22,4 @@ import { /* ... */ } from '@almadar/runtime';
 
 ## License
 
-MIT
+BSL 1.1 (Business Source License). Converts to Apache 2.0 on 2030-02-01. Non-production use is free.

package/dist/{OrbitalServerRuntime-MBjDCrt8.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';
 
 /**
@@ -602,6 +602,7 @@ declare class OrbitalServerRuntime {
     private preprocessedCache;
     private entitySharingMap;
     private eventNamespaceMap;
+    private osHandlers;
     constructor(config?: OrbitalServerRuntimeConfig);
     /**
      * Register an OrbitalSchema for execution.

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-MBjDCrt8.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