@ultrst-armada/kloks 1.4.3 → 1.4.4

package/packages/services/dist/index.js

@@ -1,4 +1,4 @@
-// ../../node_modules/.pnpm/@ultrst-armada+krnl@1.0.2/node_modules/@ultrst-armada/krnl/packages/core/dist/index.js
+// ../../node_modules/.pnpm/@ultrst-armada+krnl@1.0.3/node_modules/@ultrst-armada/krnl/packages/core/dist/index.js
 import http from "http";
 var ServiceStateStore = class {
   state;
@@ -53,17 +53,37 @@ var ServiceEventBus = class {
     this.handlers.clear();
   }
 };
+var TRANSITIONS = {
+  uninitialized: ["initializing"],
+  initializing: ["ready", "uninitialized"],
+  ready: ["starting"],
+  starting: ["running", "ready"],
+  running: ["stopping"],
+  stopping: ["stopped", "running"],
+  stopped: ["starting"]
+};
 var LifecycleManager = class {
   status = "uninitialized";
   getStatus() {
     return this.status;
   }
-  setStatus(next) {
+  canTransitionTo(next) {
+    return TRANSITIONS[this.status].includes(next);
+  }
+  transitionTo(next) {
+    if (!this.canTransitionTo(next)) {
+      throw new Error("[Lifecycle] Invalid transition '" + this.status + "' -> '" + next + "'.");
+    }
     this.status = next;
   }
+  setStatus(next) {
+    this.transitionTo(next);
+  }
   assertRunning(serviceName) {
     if (this.status !== "running") {
-      throw new Error(`[Service:${serviceName}] Cannot invoke operation while status is '${this.status}' (expected 'running').`);
+      throw new Error(
+        "[Service:" + serviceName + "] Cannot invoke operation while status is '" + this.status + "' (expected 'running')."
+      );
     }
   }
 };
@@ -75,7 +95,7 @@ var ServiceInstance = class {
     this.version = definition.version;
     this.lifecycle = new LifecycleManager();
     this.eventBus = new ServiceEventBus();
-    if (definition.state?.initial) {
+    if (definition.state) {
       this.stateStore = new ServiceStateStore(definition.state.initial);
     }
   }
@@ -86,46 +106,76 @@ var ServiceInstance = class {
   stateStore;
   eventBus;
   lifecycle;
+  initialized = false;
+  disposed = false;
   getDefinition() {
     return this.definition;
   }
+  getStatus() {
+    return this.lifecycle.getStatus();
+  }
   async start() {
-    this.lifecycle.setStatus("starting");
-    if (this.definition.lifecycle?.onInit) {
-      await this.definition.lifecycle.onInit();
+    if (this.disposed) throw new Error("[Service:" + this.name + "] Cannot start a disposed service.");
+    const current = this.lifecycle.getStatus();
+    if (current === "running") return;
+    if (current === "initializing" || current === "starting" || current === "stopping") {
+      throw new Error("[Service:" + this.name + "] Cannot start while status is '" + current + "'.");
+    }
+    if (!this.initialized) {
+      this.lifecycle.transitionTo("initializing");
+      try {
+        await this.definition.lifecycle?.onInit?.();
+        this.initialized = true;
+        this.lifecycle.transitionTo("ready");
+      } catch (error) {
+        this.lifecycle.transitionTo("uninitialized");
+        throw error;
+      }
     }
-    if (this.definition.lifecycle?.onStart) {
-      await this.definition.lifecycle.onStart();
+    this.lifecycle.transitionTo("starting");
+    try {
+      await this.definition.lifecycle?.onStart?.();
+      this.lifecycle.transitionTo("running");
+    } catch (error) {
+      this.lifecycle.transitionTo("ready");
+      throw error;
     }
-    this.lifecycle.setStatus("running");
   }
   async stop() {
-    this.lifecycle.setStatus("stopping");
-    if (this.definition.lifecycle?.onStop) {
-      await this.definition.lifecycle.onStop();
+    const current = this.lifecycle.getStatus();
+    if (current === "stopped") return;
+    if (current !== "running") {
+      throw new Error("[Service:" + this.name + "] Cannot stop while status is '" + current + "'.");
     }
-    if (this.definition.lifecycle?.onDispose) {
-      await this.definition.lifecycle.onDispose();
+    this.lifecycle.transitionTo("stopping");
+    try {
+      await this.definition.lifecycle?.onStop?.();
+      this.lifecycle.transitionTo("stopped");
+    } catch (error) {
+      this.lifecycle.transitionTo("running");
+      throw error;
     }
-    this.lifecycle.setStatus("stopped");
+  }
+  async dispose() {
+    if (this.disposed) return;
+    if (this.lifecycle.getStatus() === "running") await this.stop();
+    await this.definition.lifecycle?.onDispose?.();
+    this.disposed = true;
   }
   async call(op, input, ctx = {}) {
     this.lifecycle.assertRunning(this.name);
     const operation = this.definition.operations[op];
     if (!operation) {
-      throw new Error(`[Service:${this.name}] Operation '${op}' not found.`);
+      throw new Error("[Service:" + this.name + "] Operation '" + op + "' not found.");
     }
     return await operation.handler(input, ctx);
   }
   getState() {
-    if (!this.stateStore) {
-      return Object.freeze({});
-    }
-    return this.stateStore.getState();
+    return this.stateStore?.getState() ?? Object.freeze({});
   }
   setState(mutation) {
     if (!this.stateStore) {
-      this.stateStore = new ServiceStateStore(mutation);
+      this.stateStore = new ServiceStateStore({ ...mutation });
       return;
     }
     this.stateStore.setState(mutation);
@@ -142,10 +192,19 @@ var ServiceProxy = class {
     this.definition = definition;
     this.adapter = adapter;
     this.endpoint = endpoint;
+    if (!definition) {
+      throw new Error("[ServiceProxy] Missing service definition.");
+    }
+    if (!adapter || typeof adapter.send !== "function") {
+      throw new Error("[ServiceProxy:" + (definition.name || "unknown") + "] Missing or invalid protocol adapter.");
+    }
+    if (!endpoint || typeof endpoint.address !== "string" || endpoint.address.length === 0) {
+      throw new Error("[ServiceProxy:" + (definition.name || "unknown") + "] Missing or invalid endpoint descriptor.");
+    }
     this.id = definition.id;
     this.name = definition.name;
     this.version = definition.version;
-    this.stateCache = definition.state?.initial || {};
+    this.stateCache = { ...definition.state?.initial ?? {} };
   }
   definition;
   adapter;
@@ -155,19 +214,56 @@ var ServiceProxy = class {
   version;
   stateCache;
   eventHandlers = /* @__PURE__ */ new Map();
+  lifecycle = new LifecycleManager();
+  disposed = false;
   getDefinition() {
     return this.definition;
   }
+  getStatus() {
+    return this.lifecycle.getStatus();
+  }
   async start() {
+    if (this.disposed) {
+      throw new Error("[ServiceProxy:" + this.name + "] Cannot start a disposed service proxy.");
+    }
+    const status = this.lifecycle.getStatus();
+    if (status === "running") return;
+    if (status === "stopping" || status === "starting" || status === "initializing") {
+      throw new Error("[ServiceProxy:" + this.name + "] Cannot start while status is '" + status + "'.");
+    }
+    if (status === "uninitialized") {
+      this.lifecycle.transitionTo("initializing");
+      this.lifecycle.transitionTo("ready");
+    }
+    this.lifecycle.transitionTo("starting");
+    this.lifecycle.transitionTo("running");
   }
   async stop() {
+    const status = this.lifecycle.getStatus();
+    if (status === "stopped") return;
+    if (status !== "running") {
+      throw new Error("[ServiceProxy:" + this.name + "] Cannot stop while status is '" + status + "'.");
+    }
+    this.lifecycle.transitionTo("stopping");
+    this.lifecycle.transitionTo("stopped");
+  }
+  async dispose() {
+    if (this.disposed) return;
+    if (this.lifecycle.getStatus() === "running") await this.stop();
+    this.disposed = true;
   }
   async call(op, input, ctx = {}) {
+    if (!this.definition.operations[op]) {
+      throw new Error("[ServiceProxy:" + this.name + "] Operation '" + op + "' not found.");
+    }
+    if (this.lifecycle.getStatus() !== "running") {
+      await this.start();
+    }
     if (!this.adapter.send) {
-      throw new Error(`[ServiceProxy:${this.name}] Adapter does not support send().`);
+      throw new Error("[ServiceProxy:" + this.name + "] Adapter does not support send().");
     }
     const envelope = {
-      id: `req-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
+      id: "req-" + Date.now() + "-" + Math.random().toString(36).slice(2, 7),
       type: "request",
       operation: op,
       payload: input,
@@ -175,7 +271,7 @@ var ServiceProxy = class {
     };
     const response = await this.adapter.send(this.endpoint, envelope);
     if (response.error) {
-      throw new Error(`[ServiceProxy:${this.name}] Remote error: ${response.error}`);
+      throw new Error("[ServiceProxy:" + this.name + "] Remote error: " + response.error);
     }
     return response.payload;
   }
@@ -186,33 +282,93 @@ var ServiceProxy = class {
     this.stateCache = { ...this.stateCache, ...mutation };
   }
   on(event, handler) {
-    if (!this.eventHandlers.has(event)) {
-      this.eventHandlers.set(event, /* @__PURE__ */ new Set());
-    }
+    if (!this.eventHandlers.has(event)) this.eventHandlers.set(event, /* @__PURE__ */ new Set());
     const handlers = this.eventHandlers.get(event);
     handlers.add(handler);
-    return () => {
-      handlers.delete(handler);
-    };
+    return () => handlers.delete(handler);
   }
   emit(event, payload) {
     const handlers = this.eventHandlers.get(event);
-    if (handlers) {
-      for (const handler of Array.from(handlers)) {
+    if (!handlers) return;
+    for (const handler of Array.from(handlers)) {
+      try {
         handler(payload);
+      } catch (error) {
+        console.error("[ServiceProxy:" + this.name + "] Event handler error for '" + event + "':", error);
       }
     }
   }
 };
-function createServiceDefinition(definition) {
+function assertRecord(value, field) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("[KrnlTS] Invalid service definition: '" + field + "' must be an object.");
+  }
+}
+function assertNonEmptyString(value, field) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error("[KrnlTS] Invalid service definition: '" + field + "' must be a non-empty string.");
+  }
+}
+function validateServiceDefinition(definition) {
+  if (!definition || typeof definition !== "object") {
+    throw new Error("[KrnlTS] Invalid service definition: expected an object.");
+  }
+  assertNonEmptyString(definition.id, "id");
+  assertNonEmptyString(definition.name, "name");
+  assertNonEmptyString(definition.version, "version");
+  if (!definition.operations || typeof definition.operations !== "object") {
+    throw new Error("[Service:" + definition.name + "] Invalid operations: expected an object.");
+  }
+  for (const [key, operation] of Object.entries(definition.operations)) {
+    if (!operation || typeof operation !== "object") {
+      throw new Error("[Service:" + definition.name + "] Invalid operation '" + key + "'.");
+    }
+    assertNonEmptyString(operation.id, "operations." + key + ".id");
+    assertNonEmptyString(operation.name, "operations." + key + ".name");
+    if (operation.inputSchema !== void 0) assertRecord(operation.inputSchema, "operations." + key + ".inputSchema");
+    if (operation.outputSchema !== void 0) assertRecord(operation.outputSchema, "operations." + key + ".outputSchema");
+    if (typeof operation.handler !== "function") {
+      throw new Error("[Service:" + definition.name + "] Operation '" + key + "' must define a handler.");
+    }
+  }
+  for (const [key, event] of Object.entries(definition.events ?? {})) {
+    if (!event || typeof event !== "object") {
+      throw new Error("[Service:" + definition.name + "] Invalid event '" + key + "'.");
+    }
+    assertNonEmptyString(event.name, "events." + key + ".name");
+  }
+  for (const [key, schema] of Object.entries(definition.inputs ?? {})) assertRecord(schema, "inputs." + key);
+  for (const [key, schema] of Object.entries(definition.outputs ?? {})) assertRecord(schema, "outputs." + key);
+  if (definition.state?.schema !== void 0) assertRecord(definition.state.schema, "state.schema");
+  for (const capability of definition.capabilities ?? []) {
+    assertNonEmptyString(capability.id, "capability.id");
+    assertNonEmptyString(capability.name, "capability.name");
+    if (!Array.isArray(capability.protocols)) {
+      throw new Error("[Service:" + definition.name + "] Capability '" + capability.name + "' protocols must be an array.");
+    }
+  }
+  for (const dependency of definition.dependencies ?? []) {
+    assertNonEmptyString(dependency.serviceId, "dependency.serviceId");
+  }
   return definition;
 }
+function createServiceDefinition(definition) {
+  return validateServiceDefinition(definition);
+}
 function createService(definition) {
-  return new ServiceInstance(definition);
+  return new ServiceInstance(validateServiceDefinition(definition));
 }
 function createServiceProxy(definition, adapter, endpoint) {
+  validateServiceDefinition(definition);
+  if (!adapter || typeof adapter.send !== "function") {
+    throw new Error("[ServiceProxy:" + definition.name + "] Adapter must implement send().");
+  }
+  if (!endpoint || typeof endpoint.address !== "string" || endpoint.address.length === 0) {
+    throw new Error("[ServiceProxy:" + definition.name + "] Endpoint must have an address.");
+  }
   return new ServiceProxy(definition, adapter, endpoint);
 }
+var asyncHooks = globalThis.process?.getBuiltinModule?.("node:async_hooks");
 var HttpProtocolAdapter = class {
   protocol = "http";
   capabilities = {
@@ -1585,6 +1741,12 @@ var SystemDbClientServiceFacade = {
     return systemDbClientInstance.call(op, input);
   }
 };
+var krnlAuthClientServiceDefinition = AuthClientServiceDefinition;
+var krnlAuthClientServiceFacade = AuthClientServiceFacade;
+var krnlStorageClientServiceDefinition = StorageClientServiceDefinition;
+var krnlStorageClientServiceFacade = StorageClientServiceFacade;
+var krnlSystemDbClientServiceDefinition = SystemDbClientServiceDefinition;
+var krnlSystemDbClientServiceFacade = SystemDbClientServiceFacade;
 
 // src/index.ts
 var ServiceADefinition = createServiceDefinition({
@@ -1747,6 +1909,14 @@ var ServiceDDefinition = createServiceDefinition({
         protocol: ctx.protocol ?? "memory",
         timestamp: Date.now()
       })
+    },
+    uppercase: {
+      id: "ServiceD.uppercase",
+      name: "uppercase",
+      protocols: ["http", "ws", "udp", "p2p"],
+      handler: async (input) => ({
+        result: (typeof input === "string" ? input : input?.text ?? "").toUpperCase()
+      })
     }
   }
 });
@@ -1785,6 +1955,17 @@ var ServiceDFacade = {
     return defaultServiceD.call(op, input);
   }
 };
+var krnlServiceADefinition = ServiceADefinition;
+var krnlServiceAFacade = ServiceAFacade;
+var krnlServiceBDefinition = ServiceBDefinition;
+var krnlServiceBFacade = ServiceBFacade;
+var krnlCreateServiceB = createServiceB;
+var krnlServiceCDefinition = ServiceCDefinition;
+var krnlServiceCFacade = ServiceCFacade;
+var krnlCreateServiceC = createServiceC;
+var krnlServiceDDefinition = ServiceDDefinition;
+var krnlServiceDFacade = ServiceDFacade;
+var krnlExposeServiceD = exposeServiceD;
 export {
   AuthClientServiceDefinition,
   AuthClientServiceFacade,
@@ -1817,6 +1998,23 @@ export {
   deleteWorkspace,
   exposeServiceD,
   fetchWorkspaces,
+  krnlAuthClientServiceDefinition,
+  krnlAuthClientServiceFacade,
+  krnlCreateServiceB,
+  krnlCreateServiceC,
+  krnlExposeServiceD,
+  krnlServiceADefinition,
+  krnlServiceAFacade,
+  krnlServiceBDefinition,
+  krnlServiceBFacade,
+  krnlServiceCDefinition,
+  krnlServiceCFacade,
+  krnlServiceDDefinition,
+  krnlServiceDFacade,
+  krnlStorageClientServiceDefinition,
+  krnlStorageClientServiceFacade,
+  krnlSystemDbClientServiceDefinition,
+  krnlSystemDbClientServiceFacade,
   loadDatabase,
   loginAdmin,
   loginUser,

package/packages/services/kloks.manifest.json

@@ -14,17 +14,21 @@
         "export": "AuthClientServiceFacade",
         "facade": "AuthClientServiceFacade"
       },
-      "ui": {
-        "requirementMode": "required",
-        "schema": "AuthServiceUISchema",
-        "page": "Auth.ui",
-        "section": "Auth.ui.LoginSection",
-        "component": "AuthPage",
-        "package": "@ultrst-armada/floks",
-        "export": "ui"
+      "modes": [
+        "client",
+        "backend"
+      ],
+      "targets": {
+        "backend": [
+          "BackendFacade.services"
+        ]
       },
-      "modes": ["client", "backend"],
-      "targets": { "backend": ["BackendFacade.services"] }
+      "defaultFrontend": {
+        "component": "AuthPage",
+        "package": "@ultrst-armada/floks/ui",
+        "relationship": "recommended",
+        "requirementMode": "required"
+      }
     },
     {
       "id": "kloks.service.storage",
@@ -36,17 +40,21 @@
         "export": "StorageClientServiceFacade",
         "facade": "StorageClientServiceFacade"
       },
-      "ui": {
-        "requirementMode": "optional",
-        "schema": "StorageServiceUISchema",
-        "page": "Storage.ui",
-        "section": "Storage.ui.TilesSection",
-        "component": "WorkspaceTilesMenu",
-        "package": "@ultrst-armada/floks",
-        "export": "ui"
+      "modes": [
+        "client",
+        "backend"
+      ],
+      "targets": {
+        "backend": [
+          "BackendFacade.services"
+        ]
       },
-      "modes": ["client", "backend"],
-      "targets": { "backend": ["BackendFacade.services"] }
+      "defaultFrontend": {
+        "component": "WorkspaceTilesMenu",
+        "package": "@ultrst-armada/floks/ui",
+        "relationship": "recommended",
+        "requirementMode": "optional"
+      }
     },
     {
       "id": "kloks.service.systemDb",
@@ -58,11 +66,15 @@
         "export": "SystemDbClientServiceFacade",
         "facade": "SystemDbClientServiceFacade"
       },
-      "ui": {
-        "requirementMode": "none"
-      },
-      "modes": ["client", "backend"],
-      "targets": { "backend": ["BackendFacade.services"] }
+      "modes": [
+        "client",
+        "backend"
+      ],
+      "targets": {
+        "backend": [
+          "BackendFacade.services"
+        ]
+      }
     },
     {
       "id": "service-a",
@@ -74,8 +86,14 @@
         "export": "ServiceAFacade",
         "facade": "ServiceAFacade"
       },
-      "modes": ["backend"],
-      "targets": { "backend": ["BackendFacade.services"] }
+      "modes": [
+        "backend"
+      ],
+      "targets": {
+        "backend": [
+          "BackendFacade.services"
+        ]
+      }
     },
     {
       "id": "service-b",
@@ -87,8 +105,14 @@
         "export": "ServiceBFacade",
         "facade": "ServiceBFacade"
       },
-      "modes": ["backend"],
-      "targets": { "backend": ["BackendFacade.services"] }
+      "modes": [
+        "backend"
+      ],
+      "targets": {
+        "backend": [
+          "BackendFacade.services"
+        ]
+      }
     },
     {
       "id": "service-c",
@@ -100,8 +124,14 @@
         "export": "ServiceCFacade",
         "facade": "ServiceCFacade"
       },
-      "modes": ["backend"],
-      "targets": { "backend": ["BackendFacade.services"] }
+      "modes": [
+        "backend"
+      ],
+      "targets": {
+        "backend": [
+          "BackendFacade.services"
+        ]
+      }
     },
     {
       "id": "service-d",
@@ -113,8 +143,14 @@
         "export": "ServiceDFacade",
         "facade": "ServiceDFacade"
       },
-      "modes": ["backend"],
-      "targets": { "backend": ["BackendFacade.services"] }
+      "modes": [
+        "backend"
+      ],
+      "targets": {
+        "backend": [
+          "BackendFacade.services"
+        ]
+      }
     }
   ]
 }

package/packages/services/package.json

@@ -29,6 +29,6 @@
     "@kloks/state-graph": "workspace:*"
   },
   "devDependencies": {
-    "@ultrst-armada/krnl": "^1.0.2"
+    "@ultrst-armada/krnl": "^1.0.3"
   }
 }

package/packages/state-graph/dist/{BaseGraph-BvkSYOTw.d.ts → BaseGraph-Bd5F1NMP.d.ts}

@@ -1,4 +1,4 @@
-import { N as NodePosition, a as NodeSize, b as BaseNode } from './BaseNode-DTcd3K1B.js';
+import { N as NodePosition, a as NodeSize, b as BaseNode } from './BaseNode-DKpGXMy8.js';
 import { B as BaseConnection } from './BaseConnection-CMRrL6Fe.js';
 
 type DynamicState = 'INACTIVE' | 'ACTIVE' | 'PINNED_LIVE';

package/packages/state-graph/dist/{BaseNode-DTcd3K1B.d.ts → BaseNode-DKpGXMy8.d.ts}

@@ -74,6 +74,12 @@ interface NodeDefinition {
     type: string;
     label: string;
     description?: string;
+    /** Automatic node-menu grouping category. */
+    category?: string;
+    /** Controls whether this node is discoverable from generic graph spawn menus. */
+    menu?: {
+        visible?: boolean;
+    };
     inputs?: HandleDefinition[];
     outputs?: HandleDefinition[];
     views?: string[];

package/packages/state-graph/dist/{CompatibilityMatrix-Dj-tCWUA.d.ts → CompatibilityMatrix-TiEJ3j3_.d.ts}

@@ -1,4 +1,4 @@
-import { B as BaseHandle, H as HandleCategory } from './BaseNode-DTcd3K1B.js';
+import { B as BaseHandle, H as HandleCategory } from './BaseNode-DKpGXMy8.js';
 
 interface CompatibilityRule {
     sourceCategory: HandleCategory;

package/packages/state-graph/dist/domain/index.d.ts

@@ -1,8 +1,8 @@
-import { b as BaseNode, B as BaseHandle, e as BaseNodeProps, D as DataHandle, N as NodePosition } from '../BaseNode-DTcd3K1B.js';
-export { d as BaseHandleProps, C as ConnectionMode, f as CustomNode, H as HandleCategory, g as HandleDefinition, c as HandleDirection, h as HandleOffset, i as HandlePosition, j as NodeDefinition, a as NodeSize, V as ViewHandle } from '../BaseNode-DTcd3K1B.js';
+import { b as BaseNode, B as BaseHandle, e as BaseNodeProps, D as DataHandle, N as NodePosition } from '../BaseNode-DKpGXMy8.js';
+export { d as BaseHandleProps, C as ConnectionMode, f as CustomNode, H as HandleCategory, g as HandleDefinition, c as HandleDirection, h as HandleOffset, i as HandlePosition, j as NodeDefinition, a as NodeSize, V as ViewHandle } from '../BaseNode-DKpGXMy8.js';
 import { B as BaseConnection } from '../BaseConnection-CMRrL6Fe.js';
 export { a as BaseConnectionProps, S as SolidConnection, b as SolidConnectionProps, V as ViewLink, c as ViewLinkProps } from '../BaseConnection-CMRrL6Fe.js';
-export { B as BaseGraph, a as BaseViewWindow, b as BaseViewWindowProps, C as CustomGraph, c as CustomViewWindow, D as DEFAULT_GRAPH_SETTINGS, d as DynamicState, G as GraphSettings, e as GraphView, f as Group, L as Landmark } from '../BaseGraph-BvkSYOTw.js';
+export { B as BaseGraph, a as BaseViewWindow, b as BaseViewWindowProps, C as CustomGraph, c as CustomViewWindow, D as DEFAULT_GRAPH_SETTINGS, d as DynamicState, G as GraphSettings, e as GraphView, f as Group, L as Landmark } from '../BaseGraph-Bd5F1NMP.js';
 
 interface GroupNodeProps extends Partial<BaseNodeProps> {
     innerNodes?: BaseNode[];

package/packages/state-graph/dist/domain/index.js

@@ -22,7 +22,6 @@ import {
   SolidConnection,
   ViewLink
 } from "../chunk-OYN4ZEZC.js";
-import "../chunk-3RG5ZIWI.js";
 export {
   BaseConnection,
   BaseGraph,