@ultrst-armada/krnl 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# Krnl Framework
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Krnl**: Backend Service Framework for Skipo — a modular TypeScript framework for authoring, composing, executing, and validating backend services, facades, protocols, and workflows.
+
+---
+
+## 🚀 Overview
+
+In the **Skipo** ecosystem, services are the foundational backend modules. **Krnl** provides the kernel architecture, lifecycle hooks, transport gateways, protocol decoders, and validation engine for building robust, decoupled backend services.
+
+- **Modular Service Architecture**: Define pure, stateful, and protocol-enabled backend service facades.
+- **Workflow & Flow Execution**: Compose multi-service pipelines and background execution boundaries.
+- **AST Purity & Validation**: Enforce 4-layer function purity, contract standards, and architecture rules via `ts-morph`.
+- **Protocol & Network Ingress**: Support REST, WebSocket, RPC, and MCP protocol bindings out of the box.
+- **Universal Backend Readiness**: Run seamlessly across Local FS, Local-Hosted, and Serverless environments.
+
+---
+
+## 🚀 Quickstart: Starting a Fresh Workspace
+
+### 1. Scaffold a New Project
+Run the official interactive project generator:
+
+```bash
+# Using npm
+npm create krnl my-service-app
+
+# Using npx
+npx create-krnl my-service-app
+
+# Using pnpm
+pnpm dlx create-krnl my-service-app
+```
+
+This generates a fully configured Krnl backend workspace:
+- `krnl.json` (Workspace manifest & provider bindings)
+- `package.json` & `tsconfig.json`
+- `src/services/` (Backend service definitions & facades)
+- `src/libraries/` (Layer 0 pure concept libraries)
+- `docs/HISTORY.md` (Project intent & architectural memory)
+
+---
+
+### 2. Run and Validate Services
+
+```bash
+cd my-service-app
+
+# Start Krnl service dev server
+krnl dev
+
+# Run deep AST 4-layer service purity validation
+krnl validate
+
+# Build production bundle
+krnl build
+```
+
+---
+
+### 3. CLI Commands Reference
+
+```bash
+# Start Krnl service dev server & boot service entrypoint
+krnl dev
+
+# Run deep AST 4-layer function purity audit
+krnl validate
+
+# Validate and build production bundle into dist/
+krnl build
+
+# Generate ambient TypeScript declarations for auto-discovery
+krnl watch
+
+# Scaffold architectural primitives via CLI
+krnl generate entity UserSystem
+krnl generate functionality UserSystem CreateProfile
+krnl generate library BillingConcepts
+krnl generate subapp OrderEngine
+```
+
+---
+
+## 🏛️ Monorepo Framework Packages
+
+- **[`@ultrst-armada/krnl`](packages/core)**: Core runtime engine, Service facades, Protocols, Transports, Registry, Lifecycle, and Execution flows.
+- **[`@dinilmusick/krnl-validate`](packages/validate)**: `ts-morph` AST engine enforcing 4-layer function purity, backend contracts, and line limits.
+- **[`@dinilmusick/eslint-plugin-krnl`](packages/eslint-plugin)**: ESLint rules with auto-fixers for Krnl backend service standards.
+- **[`@dinilmusick/krnl-cli`](packages/cli)**: Unified `krnl` binary for running, building, and validating backend services.
+- **[`create-krnl`](packages/create-krnl)**: Interactive project scaffolder for Krnl backend service modules.
+
+---
+
+## 📜 License
+MIT © Dinil Palackal

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "@ultrst-armada/krnl",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "private": false,
+  "description": "Krnl: Backend Service Framework for Skipo — authoring, executing, and validating modular backend services, facades, and workflows",
+  "type": "module",
+  "main": "./packages/core/dist/index.js",
+  "module": "./packages/core/dist/index.js",
+  "types": "./packages/core/dist/index.d.ts",
+  "files": [
+    "packages/*/dist/**",
+    "packages/*/package.json"
+  ],
+  "exports": {
+    ".": {
+      "types": "./packages/core/dist/index.d.ts",
+      "import": "./packages/core/dist/index.js",
+      "require": "./packages/core/dist/index.cjs",
+      "default": "./packages/core/dist/index.js"
+    },
+    "./validate": {
+      "types": "./packages/validate/dist/index.d.ts",
+      "import": "./packages/validate/dist/index.js",
+      "require": "./packages/validate/dist/index.cjs",
+      "default": "./packages/validate/dist/index.js"
+    },
+    "./cli": {
+      "types": "./packages/cli/dist/index.d.ts",
+      "import": "./packages/cli/dist/index.js",
+      "require": "./packages/cli/dist/index.cjs",
+      "default": "./packages/cli/dist/index.js"
+    }
+  },
+  "bin": {
+    "krnl": "./packages/cli/dist/bin/krnl.js",
+    "krnlts-watch": "./packages/cli/dist/bin/krnl.js",
+    "krnlts-validate": "./packages/cli/dist/bin/krnl.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "pnpm --filter @dinilmusick/krnl-core run build",
+    "test": "vitest run",
+    "validate": "node packages/cli/dist/bin/krnl.js validate",
+    "dev": "node packages/cli/dist/bin/krnl.js dev",
+    "watch": "node packages/cli/dist/bin/krnl.js watch"
+  },
+  "keywords": [
+    "krnl",
+    "skipo",
+    "service-framework",
+    "backend",
+    "backend-modules",
+    "services",
+    "service-facades",
+    "protocols",
+    "workflows",
+    "ast-purity"
+  ],
+  "author": "Dinil Palackal",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/node": "^25.6.0",
+    "better-sqlite3": "^13.0.3",
+    "protobufjs": "^8.7.1",
+    "tsup": "^8.4.0",
+    "turbo": "^2.4.4",
+    "typescript": "^5.7.3",
+    "vitest": "^3.1.0",
+    "ws": "^8.20.0",
+    "zod": "3.24.1",
+    "zod-to-json-schema": "3.24.1"
+  }
+}

package/packages/cli/dist/K_ENT_Entity-PQ5MURQY-ZG6FZXXX.js

@@ -0,0 +1,13 @@
+import {
+  Entity
+} from "./chunk-RJNYUXZD.js";
+import "./chunk-BOXWWXQG.js";
+import "./chunk-FDNCADFE.js";
+import "./chunk-5JDK35TG.js";
+import "./chunk-Q45257P6.js";
+import "./chunk-XIRFOO3H.js";
+import "./chunk-JTLSTO25.js";
+import "./chunk-X5LOIFM7.js";
+export {
+  Entity
+};

package/packages/cli/dist/K_LIB_Krnl_Aiko_Client-OPZAVZCW-K4CRQYA5.js

@@ -0,0 +1,8 @@
+import {
+  KrnlAikoClient
+} from "./chunk-3TRM6CYL.js";
+import "./chunk-XIRFOO3H.js";
+import "./chunk-X5LOIFM7.js";
+export {
+  KrnlAikoClient
+};

package/packages/cli/dist/K_LIB_Krnl_Ep_Tools-ROOE2TQF-LNPXZYOE.js

@@ -0,0 +1,110 @@
+import "./chunk-X5LOIFM7.js";
+
+// ../core/dist/K_LIB_Krnl_Ep_Tools-ROOE2TQF.js
+var KrnlEpTools = {
+  calculator: {
+    id: "calculator",
+    description: "eval arith-expr(str) \u2192 num. use-when: derive numeric val from schema fields.",
+    schema: {
+      input: { expression: "str: arith expr. ops: +,-,*,/,(). e.g. '(a+b)*c'" },
+      output: "num"
+    },
+    examples: [
+      { input: { expression: "10 + 5 * 2" }, output: 20 },
+      { input: { expression: "(100-30)/7" }, output: 10 }
+    ],
+    execute: (expression) => {
+      const sanitized = expression.replace(/[^0-9+\-*/().\s]/g, "");
+      try {
+        const result = new Function(`return (${sanitized});`)();
+        if (typeof result === "number") return result;
+        throw new Error("Result is not a number");
+      } catch (e) {
+        throw new Error(`Math evaluation failed: ${e.message}`);
+      }
+    }
+  },
+  jsonCreator: {
+    id: "jsonCreator",
+    description: "parse(jsonStr) \u2192 obj | merge(obj,base) \u2192 merged. use-when: validate/build payload.",
+    schema: {
+      input: { jsonStr: "str: valid JSON", mergeWith: "obj? base to merge into" },
+      output: "obj"
+    },
+    examples: [
+      { input: { jsonStr: '{"a":1}' }, output: { a: 1 } },
+      { input: { jsonStr: '{"b":2}', mergeWith: { a: 1 } }, output: { a: 1, b: 2 } }
+    ],
+    execute: (jsonStr, mergeWith) => {
+      try {
+        const parsed = JSON.parse(jsonStr);
+        if (mergeWith && typeof mergeWith === "object") {
+          return { ...mergeWith, ...parsed };
+        }
+        return parsed;
+      } catch (e) {
+        throw new Error(`JSON validation/parsing failed: ${e.message}`);
+      }
+    }
+  },
+  textFormatter: {
+    id: "textFormatter",
+    description: "render(template,vars) \u2192 str. use-when: replace placeholders in templates.",
+    schema: {
+      input: { template: "str w/ {{key}} placeholders", variables: "obj mapping keys \u2192 values" },
+      output: "str"
+    },
+    examples: [
+      { input: { template: "hello {{name}}", variables: { name: "alice" } }, output: "hello alice" }
+    ],
+    execute: (template, variables) => {
+      let result = template;
+      for (const [key, value] of Object.entries(variables)) {
+        result = result.replace(new RegExp(`{{\\s*${key}\\s*}}`, "g"), String(value));
+      }
+      return result;
+    }
+  },
+  endpointCaller: {
+    id: "endpointCaller",
+    description: "call(endpointId,payload) \u2192 res. use-when: invoke sibling endpoint in same system.",
+    schema: {
+      input: { endpointId: "str: target endpoint", payload: "obj: input matching target schema" },
+      output: "any"
+    },
+    examples: [
+      { input: { endpointId: "StoreKey", payload: { name: "test", value: "val" } }, output: { status: "success" } }
+    ],
+    execute: async (system, endpointId, payload) => {
+      if (!system || typeof system.call !== "function") {
+        throw new Error("System host entity not available or invalid.");
+      }
+      return await system.call(endpointId, payload, { unwrap: true });
+    }
+  },
+  healthChecker: {
+    id: "healthChecker",
+    description: "ping(peerId) \u2192 status. use-when: verify component/sibling system is alive.",
+    schema: {
+      input: { peerId: "str: peer system identifier" },
+      output: "obj"
+    },
+    examples: [
+      { input: { peerId: "Aiko" }, output: { status: "alive" } }
+    ],
+    execute: async (system, peerId) => {
+      if (!system) throw new Error("System host entity not available.");
+      const peer = system.getRemoteEntity ? system.getRemoteEntity(peerId) : null;
+      if (peer) {
+        return await peer.call("heartbeat", {});
+      }
+      if (system.localFunctionalities?.has("heartbeat")) {
+        return await system.call("heartbeat", {});
+      }
+      throw new Error(`Peer or heartbeat endpoint not found for: ${peerId}`);
+    }
+  }
+};
+export {
+  KrnlEpTools
+};

package/packages/cli/dist/K_LIB_Krnl_Frontend_Builder-2ZDUH6PF-3ALZPNX4.js

@@ -0,0 +1,11 @@
+import {
+  KrnlFrontendBuilder,
+  init_K_LIB_Krnl_Frontend_Builder
+} from "./chunk-GDLRMDAN.js";
+import "./chunk-X5LOIFM7.js";
+
+// ../core/dist/K_LIB_Krnl_Frontend_Builder-2ZDUH6PF.js
+init_K_LIB_Krnl_Frontend_Builder();
+export {
+  KrnlFrontendBuilder
+};

package/packages/cli/dist/K_LIB_Krnl_Frontend_Generator-UYNRNX2X-PJTICYSW.js

@@ -0,0 +1,11 @@
+import {
+  KrnlFrontendGenerator,
+  init_K_LIB_Krnl_Frontend_Generator
+} from "./chunk-JULBBJ27.js";
+import "./chunk-X5LOIFM7.js";
+
+// ../core/dist/K_LIB_Krnl_Frontend_Generator-UYNRNX2X.js
+init_K_LIB_Krnl_Frontend_Generator();
+export {
+  KrnlFrontendGenerator
+};

package/packages/cli/dist/K_LIB_Krnl_Registry_Client-NXV6D2QW-M5TYU55O.js

@@ -0,0 +1,8 @@
+import {
+  KrnlRegistryClient
+} from "./chunk-SRTOPJ5W.js";
+import "./chunk-JTLSTO25.js";
+import "./chunk-X5LOIFM7.js";
+export {
+  KrnlRegistryClient
+};

package/packages/cli/dist/K_LIB_Krnl_SubApp_Engine-7HR5HWW2-H6STOXRK.js

@@ -0,0 +1,20 @@
+import {
+  DefaultEventRegistrar,
+  DefaultOperationRegistrar,
+  DefaultServiceContainer,
+  KrnlSubAppDiscovery,
+  KrnlSubAppLifecycle,
+  KrnlSubAppValidator,
+  createHttpsAppAdapter
+} from "./chunk-BOXWWXQG.js";
+import "./chunk-JTLSTO25.js";
+import "./chunk-X5LOIFM7.js";
+export {
+  DefaultEventRegistrar,
+  DefaultOperationRegistrar,
+  DefaultServiceContainer,
+  KrnlSubAppDiscovery,
+  KrnlSubAppLifecycle,
+  KrnlSubAppValidator,
+  createHttpsAppAdapter
+};

package/packages/cli/dist/K_LIB_Krnl_SubApp_Registry-7XYGDKJK-XPJXSF7D.js

@@ -0,0 +1,19 @@
+import {
+  KrnlSubAppLoader
+} from "./chunk-6NIKAMUZ.js";
+import "./chunk-P2PCLEKX.js";
+import "./chunk-FDNCADFE.js";
+import "./chunk-PJQIUOX2.js";
+import "./chunk-GDLRMDAN.js";
+import "./chunk-I74QIQOD.js";
+import "./chunk-ZAAV3JXQ.js";
+import "./chunk-5JDK35TG.js";
+import "./chunk-Q45257P6.js";
+import "./chunk-3TRM6CYL.js";
+import "./chunk-XIRFOO3H.js";
+import "./chunk-JTLSTO25.js";
+import "./chunk-JULBBJ27.js";
+import "./chunk-X5LOIFM7.js";
+export {
+  KrnlSubAppLoader
+};

package/packages/cli/dist/K_LIB_Krnl_SubApp_Worker_Host-CQVTGGG7-CUYGTWOW.js

@@ -0,0 +1,7 @@
+import {
+  KrnlSubAppWorkerHost
+} from "./chunk-OHVMVRBP.js";
+import "./chunk-X5LOIFM7.js";
+export {
+  KrnlSubAppWorkerHost
+};

package/packages/cli/dist/K_LIB_Krnl_System_App_Adapter-M6FJKLGU-VR6T4N6J.js

@@ -0,0 +1,17 @@
+import {
+  KrnlNonKrnlAppAdapter
+} from "./chunk-EG7T2IAD.js";
+import "./chunk-PJQIUOX2.js";
+import "./chunk-GDLRMDAN.js";
+import "./chunk-I74QIQOD.js";
+import "./chunk-ZAAV3JXQ.js";
+import "./chunk-5JDK35TG.js";
+import "./chunk-Q45257P6.js";
+import "./chunk-3TRM6CYL.js";
+import "./chunk-XIRFOO3H.js";
+import "./chunk-JTLSTO25.js";
+import "./chunk-JULBBJ27.js";
+import "./chunk-X5LOIFM7.js";
+export {
+  KrnlNonKrnlAppAdapter
+};

package/packages/cli/dist/K_LIB_Krnl_System_Base_Functionality_APIs-ZZUZ6ZG5-RLJ4QWDP.js

@@ -0,0 +1,58 @@
+import {
+  adminCommandApi,
+  aiOrchestrationApi,
+  buildEndpointDefinition,
+  deregisterAppApi,
+  discoverPeersApi,
+  findFreePortsApi,
+  getAikoCatalogApi,
+  getEndpointDefinitionsApi,
+  getFullDocumentationApi,
+  getIngressNetworkTopologyApi,
+  getLastActionDocsApi,
+  getManifestApi,
+  getSiblingNetworkTopologyApi,
+  getSubAppTopologyApi,
+  getTaskListApi,
+  getTelemetryLogApi,
+  getUsedPortsApi,
+  heartbeatApi,
+  heartbeatAppApi,
+  listAppsApi,
+  lookupAppApi,
+  registerAppApi,
+  setEndpointDefinitionApi,
+  shutdownApi,
+  systemCommandsCollectorHandler,
+  telemetryApi
+} from "./chunk-I74QIQOD.js";
+import "./chunk-Q45257P6.js";
+import "./chunk-X5LOIFM7.js";
+export {
+  adminCommandApi,
+  aiOrchestrationApi,
+  buildEndpointDefinition,
+  deregisterAppApi,
+  discoverPeersApi,
+  findFreePortsApi,
+  getAikoCatalogApi,
+  getEndpointDefinitionsApi,
+  getFullDocumentationApi,
+  getIngressNetworkTopologyApi,
+  getLastActionDocsApi,
+  getManifestApi,
+  getSiblingNetworkTopologyApi,
+  getSubAppTopologyApi,
+  getTaskListApi,
+  getTelemetryLogApi,
+  getUsedPortsApi,
+  heartbeatApi,
+  heartbeatAppApi,
+  listAppsApi,
+  lookupAppApi,
+  registerAppApi,
+  setEndpointDefinitionApi,
+  shutdownApi,
+  systemCommandsCollectorHandler,
+  telemetryApi
+};

package/packages/cli/dist/K_LIB_Krnl_System_Magnetic_Loader-XBQO2KXF-BOQGUASC.js

@@ -0,0 +1,22 @@
+import {
+  KrnlMagneticLoader,
+  magneticStorage,
+  subappLocalStorage
+} from "./chunk-P2PCLEKX.js";
+import "./chunk-FDNCADFE.js";
+import "./chunk-PJQIUOX2.js";
+import "./chunk-GDLRMDAN.js";
+import "./chunk-I74QIQOD.js";
+import "./chunk-ZAAV3JXQ.js";
+import "./chunk-5JDK35TG.js";
+import "./chunk-Q45257P6.js";
+import "./chunk-3TRM6CYL.js";
+import "./chunk-XIRFOO3H.js";
+import "./chunk-JTLSTO25.js";
+import "./chunk-JULBBJ27.js";
+import "./chunk-X5LOIFM7.js";
+export {
+  KrnlMagneticLoader,
+  magneticStorage,
+  subappLocalStorage
+};

package/packages/cli/dist/K_LIB_Krnl_System_Unified_Http_Adapter-RCEGP3OG-XJI7KIT5.js

@@ -0,0 +1,8 @@
+import {
+  krnlUnifiedHttpAdapter
+} from "./chunk-ZAAV3JXQ.js";
+import "./chunk-JTLSTO25.js";
+import "./chunk-X5LOIFM7.js";
+export {
+  krnlUnifiedHttpAdapter
+};

package/packages/cli/dist/K_LIB_Krnl_Telemetry-77FRZ3KV-K5VCWAFW.js

@@ -0,0 +1,9 @@
+import {
+  KrnlTelemetry,
+  telemetry
+} from "./chunk-Q45257P6.js";
+import "./chunk-X5LOIFM7.js";
+export {
+  KrnlTelemetry,
+  telemetry
+};