@ultrst-armada/krnl 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,85 @@
-# 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**: High-Performance Full-Stack TypeScript Framework with Direct-DOM VanJS Reactivity, ts-morph AST Purity Gates, Autonomous Code Evolution, and the **Krnl Studio Visual Node IDE**.
+
+---
+
+## 🚀 Quickstart: Starting a Fresh Workspace
+
+### 1. Scaffold a New Project
+Run the official interactive project generator:
+
+```bash
+# Using npm
+npm create krnl my-app
+
+# Using npx
+npx create-krnl my-app
+
+# Using pnpm
+pnpm dlx create-krnl my-app
+```
+
+This generates a fully configured Krnl workspace:
+- `krnl.json` (Workspace manifest & provider bindings)
+- `package.json` & `tsconfig.json`
+- `src/entities/App/` (Root entity with magnetic auto-discovery)
+- `src/entities/App/functionalities/Hello/` (Sample Quad-Unit functionality)
+- `src/libraries/AppConcepts.ts` (Layer 0 pure concept library)
+- `docs/HISTORY.md` (Project intent & architectural memory)
+
+---
+
+### 2. Launch Krnl Studio (Visual Node IDE)
+
+```bash
+cd my-app
+krnl dev
+```
+Open **`http://localhost:8080`** in your browser (Brave, Chrome, Safari).
+
+Krnl Studio provides three visual canvases switchable via the bottom dock:
+- **🏗️ Architecture Canvas**: Node graph for visually adding Entities, Quad-Unit Functionalities, and Concept Libraries (surgically writing `.ts` code to disk).
+- **🎨 UI Composer Canvas**: Drag-and-drop palette of KrnlUI atoms (`KrnlButton`, `KrnlTextInput`, `KrnlDropdown`, `KrnlTile`, `KrnlDock`) with real-time **Monaco TypeScript** code generation.
+- **🧪 Live Test Console**: Sandboxed per-function execution in isolated worker threads with **Monaco JSON Editor** inputs and latency benchmarking.
+
+---
+
+### 3. CLI Commands Reference
+
+```bash
+# Start Visual Node IDE and dev server
+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
+
+- **[`@dinilmusick/krnl-core`](packages/core)**: Entity hierarchy, Flow builder, MagneticLoader, Universal Backend suite.
+- **[`@dinilmusick/krnl-ui`](packages/ui)**: Direct-DOM VanJS reactive atoms with Neo-Brutalist 2.5D theme and Monaco editor.
+- **[`@dinilmusick/krnl-validate`](packages/validate)**: `ts-morph` AST engine enforcing 4-layer function purity and 200-line limits.
+- **[`@dinilmusick/eslint-plugin-krnl`](packages/eslint-plugin)**: 6 ESLint rules with auto-fixers for Krnl paradigms.
+- **[`@dinilmusick/krnl-studio`](packages/studio)**: Visual Node IDE, UI Composer, and Live Test Console.
+- **[`@dinilmusick/krnl-cli`](packages/cli)**: Unified `krnl` binary.
+- **[`create-krnl`](packages/create-krnl)**: Interactive project scaffolder.
+
+---
+
+## 📜 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.0",
+  "private": false,
+  "description": "Krnl: Full-Stack Multiplatform Framework with Direct-DOM Reactivity, AST Purity Gates, Code Evolution, and Visual Node IDE",
+  "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",
+    "framework",
+    "full-stack",
+    "multiplatform",
+    "vanjs",
+    "code-evolution",
+    "visual-ide",
+    "node-editor",
+    "ast-purity",
+    "orchestrator"
+  ],
+  "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
+};