johankit-runtime 0.0.1

package/README.md

@@ -0,0 +1,300 @@
+# Johankit Runtime
+
+A modular runtime built around **events**, **capabilities**, and **contracts**.  
+It allows systems to grow by composition instead of coupling, using self-contained packages that are discovered and wired automatically.
+
+This project is not a framework in the traditional sense.  
+It is an **execution model**.
+
+---
+
+## Why This Exists
+
+Most systems grow by accumulating integrations:
+- interfaces
+- protocols
+- adapters
+- glue code
+
+Johankit Runtime approaches this differently:
+
+> Everything is a **package**.  
+> Everything meaningful is an **event**, a **route**, or a **callable action**.
+
+No central registry.  
+No hard dependencies between packages.  
+No shared business logic.
+
+---
+
+## Core Concepts
+
+### Packages
+
+A package is an isolated unit of behavior living inside a workspace directory.
+
+A package may declare:
+- routes
+- event hooks
+- callable tools
+- predicates
+- middleware
+- startup logic
+
+Anything not explicitly declared is ignored.
+
+---
+
+### Discovery
+
+At startup, the runtime:
+1. Scans the workspace
+2. Loads packages
+3. Inspects exported functions
+4. Registers only what is explicitly annotated
+
+There is no manual wiring.
+
+---
+
+### Declarative Annotations
+
+Behavior is declared using structured comments.
+
+**Important rule: annotations must be inside the function body.**
+
+This is intentional.
+
+```js
+function example() {
+  /**
+   * @register_hook something
+   */
+}
+````
+
+Annotations outside the function will not be detected.
+
+This makes annotations part of the behavior, not part of the language.
+
+---
+
+## Execution Primitives
+
+### Events (Hooks)
+
+Events represent something that happened.
+
+```js
+/**
+ * @register_hook user_created
+ */
+function enrich(payload) {
+  return { ...payload, enriched: true }
+}
+```
+
+* Events are broadcast to all packages
+* Hooks run sequentially
+* Returned values replace the payload
+* `null` or `undefined` are ignored
+* Failures do not stop execution
+
+Events are **data pipelines**, not notifications.
+
+---
+
+### Routes
+
+Routes expose request handlers automatically.
+
+```js
+function status() {
+  /**
+   * @register_router status
+   * @method GET
+   */
+  return { ok: true }
+}
+```
+
+Routes are namespaced by package name and require no manual registration.
+
+---
+
+### Tools
+
+Tools are structured, callable actions.
+
+```js
+function calculate() {
+  /**
+   * @register_tool calculate
+   * @description Performs a calculation
+   * @param {number} x - first value
+   * @param {number?} y - optional value
+   */
+}
+```
+
+Tools:
+
+* expose their input schema
+* can be listed dynamically
+* can be invoked programmatically
+* can be exposed through control interfaces
+
+They are ideal for automation and orchestration.
+
+---
+
+### Predicates
+
+Predicates are named boolean checks.
+
+```js
+function isAdmin() {
+  /**
+   * @register_predicate is_admin
+   */
+  return true
+}
+```
+
+They do nothing by themselves, but enable conditional execution elsewhere.
+
+---
+
+### Middleware
+
+Middleware can be conditionally enabled using predicates.
+
+```js
+function guard() {
+  /**
+   * @register_middleware access_guard
+   * @predicate is_admin
+   */
+}
+```
+
+Only predicates that evaluate to `true` activate the middleware.
+
+---
+
+## Conditions
+
+Many declarations support optional conditions:
+
+```text
+@only web
+@never mobile
+@when authenticated
+```
+
+Conditions are **metadata**, not enforcement rules.
+They allow higher-level orchestration without hardcoding logic.
+
+---
+
+## Event Dispatching
+
+Events are dispatched explicitly:
+
+```js
+dispatchEvent('user_created', payload)
+```
+
+The runtime:
+
+* loads all packages
+* finds matching hooks
+* executes them safely
+* returns the final payload
+
+This enables cross-package collaboration without coupling.
+
+---
+
+## Tool Control Interface (MCP-style)
+
+The runtime can expose tools through a standardized control surface.
+
+Capabilities:
+
+* list tools
+* inspect schemas
+* invoke tools dynamically
+
+This makes the runtime suitable for:
+
+* automation systems
+* agents
+* orchestration layers
+* external controllers
+
+---
+
+## Bootstrapping
+
+The runtime is started by providing a workspace and optional interfaces.
+
+```js
+bootstrap({
+  workspace: './packages',
+  http: { enabled: true },
+  mcp: { enabled: true }
+})
+```
+
+The bootstrap process:
+
+* resolves the workspace
+* loads all packages
+* initializes declared interfaces
+* returns references to running components
+
+---
+
+## Design Principles
+
+* Explicit behavior over magic
+* Convention over configuration
+* Isolation between packages
+* Protocol-agnostic core
+* Graceful failure handling
+* Composition over inheritance
+
+---
+
+## What Fits Naturally
+
+Because the runtime is protocol-agnostic, it adapts well to:
+
+* real-time channels
+* background processing
+* schedulers
+* message streams
+* file watchers
+* control interfaces
+* agents and decision systems
+
+All of these are just **event translators**.
+
+---
+
+## What This Is Not
+
+* Not a monolithic framework
+* Not a dependency injection container
+* Not a plugin marketplace
+* Not a DSL
+
+It is a **runtime contract**.
+
+---
+
+## Project Status
+
+Early-stage, evolving by usage.
+APIs are intentionally minimal and may evolve as patterns emerge.

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "johankit-runtime",
+  "version": "0.0.1",
+  "description": "A pluggable runtime for any back-end",
+  "main": "src/index.js",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "express": "^5.2.1",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "vitest": "latest",
+    "@vitest/coverage-v8": "latest",
+    "typescript": "^5.4.0",
+    "@types/node": "^20.0.0",
+    "@types/express": "^4.17.21"
+  },
+  "peerDependencies": {
+    "express": "^4.x"
+  }
+}

package/src/app.ts

@@ -0,0 +1,18 @@
+import express, { Application } from 'express'
+import { registerPackages } from './core/register'
+
+type JohankitApp = Application & {
+  setup: () => Promise<void>
+}
+
+const app = express() as Application
+
+;(app as JohankitApp).setup = async () => {
+  try {
+    await registerPackages(app)
+  } catch (error: any) {
+    console.log(`Error registering packages: ${error.message}`, 'error')
+  }
+}
+
+export default app as JohankitApp

package/src/core/event/dispatch.js

@@ -0,0 +1,31 @@
+const { registerHooks } = require('../register/decorators');
+const { getPackages } = require('../package');
+
+async function dispatchEvent(eventName, payload) {
+    const packages = await getPackages();
+    let finalResult = payload;
+
+    for (const pkg of packages) {
+        try {
+            const hooks = await registerHooks(pkg.folder);
+            const relevant = hooks.filter(h => h.event === eventName);
+
+            for (const hook of relevant) {
+                try {
+                    const result = await hook.call(finalResult);
+                    if (result !== undefined && result !== null) {
+                        finalResult = result;
+                    }
+                } catch (err) {
+                    console.warn(`[Hook Error] Package ${pkg.folder} failed on event ${eventName}:`, err.message);
+                }
+            }
+        } catch (err) {
+            continue;
+        }
+    }
+
+    return finalResult;
+}
+
+module.exports = { dispatchEvent };

package/src/core/mcp/http-server.js

@@ -0,0 +1,52 @@
+const express = require('express');
+const bodyParser = require('body-parser');
+const { bootstrapMcp } = require('./tools-mcp');
+
+async function createMcpHttpServer(options = {}) {
+  const app = express();
+  const port = options.port || 3333;
+  const workspace = options.workspace || process.env.PACKAGES_PATH;
+
+  if (!workspace) {
+    throw new Error('PACKAGES_PATH or workspace option is required');
+  }
+
+  const mcp = await bootstrapMcp(workspace);
+
+  app.use(bodyParser.json());
+
+  app.get('/mcp', (req, res) => {
+    res.json({ protocol: mcp.protocol, version: mcp.version });
+  });
+
+  app.get('/mcp/tools', (req, res) => {
+    try {
+      res.json(mcp.listTools());
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  app.post('/mcp/call', async (req, res) => {
+    const { name, args } = req.body || {};
+
+    if (!name) {
+      return res.status(400).json({ error: 'Tool name is required' });
+    }
+
+    try {
+      const result = await mcp.callTool(name, args || {});
+      res.json({ result });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  const server = app.listen(port, () => {
+    console.log(`MCP HTTP server running on port ${port}`);
+  });
+
+  return { app, server, mcp };
+}
+
+module.exports = { createMcpHttpServer };

package/src/core/mcp/tools-mcp.js

@@ -0,0 +1,50 @@
+const { registerTools } = require('../register/decorators');
+
+function toolToMcp(tool) {
+  return {
+    name: tool.name,
+    description: tool.description || '',
+    inputSchema: tool.parameters || { type: 'object', properties: {} },
+    handler: async (args) => {
+      return await tool.call(args);
+    },
+    condition: tool.condition || null
+  };
+}
+
+async function loadMcpTools(agentFolder) {
+  const tools = await registerTools(agentFolder);
+  return tools.map(toolToMcp);
+}
+
+function createMcpServer(tools) {
+  return {
+    protocol: 'mcp',
+    version: '1.0.0',
+    listTools() {
+      return tools.map(t => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema
+      }));
+    },
+    async callTool(name, args) {
+      const tool = tools.find(t => t.name === name);
+      if (!tool) {
+        throw new Error(`Tool not found: ${name}`);
+      }
+      return await tool.handler(args);
+    }
+  };
+}
+
+async function bootstrapMcp(agentFolder) {
+  const tools = await loadMcpTools(agentFolder);
+  return createMcpServer(tools);
+}
+
+module.exports = {
+  loadMcpTools,
+  createMcpServer,
+  bootstrapMcp
+};

package/src/core/package.js

@@ -0,0 +1,79 @@
+const fs = require('fs');
+const path = require('path');
+
+const { log } = console;
+
+async function getPackage(folderName) {
+  try {
+    const pluginsPath = process.env.PACKAGES_PATH || path.join(__dirname, '..', 'packages');
+    const manifestPath = path.join(pluginsPath, folderName, 'package.json');
+    
+    let manifest = {};
+    
+    try {
+      if (fs.existsSync(manifestPath)) {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+      }
+    } catch (error) {
+      console.error(`Manifest not found in ${folderName}:`, error);
+      throw new Error(`Manifest not found in folder ${folderName}`);
+    }
+
+    return {
+      ...manifest,
+      folder: folderName,
+    };
+  } catch (error) {
+    throw error;
+  }
+}
+
+async function getPackages() {
+  try {
+    const pluginsPath = process.env.PACKAGES_PATH || path.join(__dirname, '..', 'packages');
+    const pluginFolders = fs.readdirSync(pluginsPath).filter(f => fs.statSync(path.join(pluginsPath, f)).isDirectory());
+
+    const folderPackages = await Promise.all(pluginFolders.map(async folderName => {
+      return await getPackage(folderName);
+    }));
+
+    return folderPackages;
+  } catch (error) {
+    throw error;
+  }
+}
+
+const registerPackage = async (app, pkg) => {
+  const basePackagesPath = process.env.PACKAGES_PATH || path.join(__dirname, '..', 'packages');
+  const packageDir = path.join(basePackagesPath, pkg.folder);
+  const manifestPath = path.join(packageDir, 'package.json');
+  pkg.dir = packageDir;
+
+  try {
+      if (!fs.existsSync(manifestPath)) {
+          return;
+      }
+
+      if (!fs.existsSync(path.join(packageDir, 'routes.js'))) {
+          return;
+      }
+
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+      const usePackage = manifest.entry ? require(path.join(packageDir, manifest.entry)) : () => { };
+
+      if (typeof usePackage !== 'function') {
+          log(`${pkg.name} invalid entry point. Expected a function.`, 'error');
+          return;
+      }
+
+      const packg = usePackage(app) ?? usePackage;
+      packg?.setup && packg.setup();
+
+      log(`${pkg.name} ${pkg.version ? `version ${pkg.version}` : ''} is running.\n`);
+  } catch (error) {
+      log(`Error with package ${pkg.name}: ${error.message}`, 'error');
+      log(`${pkg.name} ${pkg.version ? `version ${pkg.version}` : ''} isn't running.\n`);
+  }
+};
+
+module.exports = { getPackage, getPackages, registerPackage };

package/src/core/parse/cognites.js

@@ -0,0 +1,22 @@
+function parseCognite(fn) {
+    if (typeof fn !== 'function') return null;
+
+    const fnStr = fn.toString();
+
+    const docMatch = fnStr.match(/\/\*\*([\s\S]*?)\*\//);
+    if (!docMatch) return null;
+
+    const doc = docMatch[1];
+
+    const cogMatch = doc.match(/@register_cognite/);
+    if (!cogMatch) return null;
+
+    const name = fn.name || "anonymous";
+
+    return {
+        name,
+        execute: fn
+    };
+}
+
+module.exports = { parseCognite };

package/src/core/parse/hooks.js

@@ -0,0 +1,37 @@
+function parseHook(fn) {
+  if (typeof fn !== 'function') return null;
+
+  const fnStr = fn.toString();
+  const docMatch = fnStr.match(/\/\*\*([\s\S]*?)\*\//);
+  if (!docMatch) return null;
+
+  const doc = docMatch[1];
+
+  const hookMatch = doc.match(/@register_hook\s+([^\s]+)/);
+  if (!hookMatch) return null;
+
+  const event = hookMatch[1].trim();
+
+  const condition = { only: [], never: [], when: [] };
+
+  const onlyMatches = [...doc.matchAll(/@only\s+([^\s]+)/g)];
+  onlyMatches.forEach(m => condition.only.push(m[1]));
+
+  const neverMatches = [...doc.matchAll(/@never\s+([^\s]+)/g)];
+  neverMatches.forEach(m => condition.never.push(m[1]));
+
+  const whenMatches = [...doc.matchAll(/@when\s+([^\s]+)/g)];
+  whenMatches.forEach(m => condition.when.push(m[1]));
+
+  Object.keys(condition).forEach(k => {
+    if (condition[k].length === 0) delete condition[k];
+  });
+
+  return {
+    event,
+    call: fn,
+    condition
+  };
+}
+
+module.exports = { parseHook };

package/src/core/parse/middleware.js

@@ -0,0 +1,35 @@
+function parseMiddleware(fn) {
+    if (typeof fn !== 'function') return null;
+
+    const fnStr = fn.toString();
+
+    // 1. Extrai o corpo da função (entre { })
+    const bodyMatch = fnStr.match(/\{([\s\S]*)\}$/);
+    if (!bodyMatch) return null;
+
+    const body = bodyMatch[1];
+
+    // 2. Procura SOMENTE JSDoc dentro do corpo
+    const docMatch = body.match(/\/\*\*([\s\S]*?)\*\//);
+    if (!docMatch) return null;
+
+    const doc = docMatch[1];
+
+    // 3. Exige explicitamente o decorator
+    const registerMatch = doc.match(/@register_middleware\s+(\w+)/);
+    if (!registerMatch) return null;
+
+    const name = registerMatch[1];
+
+    // 4. Predicates (somente os declarados ali)
+    const predicates = [...doc.matchAll(/@predicate\s+(\w+)/g)]
+        .map(m => m[1]);
+
+    return {
+        name,
+        call: fn,
+        predicates
+    };
+}
+
+module.exports = { parseMiddleware };

package/src/core/parse/predicates.js

@@ -0,0 +1,19 @@
+function parsePredicate(fn) {
+    if (typeof fn !== 'function') return null;
+
+    const fnStr = fn.toString();
+    const docMatch = fnStr.match(/\/\*\*([\s\S]*?)\*\//);
+    if (!docMatch) return null;
+
+    const doc = docMatch[1];
+
+    const match = doc.match(/@register_predicate\s*(\w+)?/);
+    if (!match) return null;
+
+    const name = match[1] || fn.name || null;
+    if (!name) return null;
+
+    return { name, call: fn };
+}
+
+module.exports = { parsePredicate };

package/src/core/parse/routes.js

@@ -0,0 +1,27 @@
+function parseRouter(fn) {
+    if (typeof fn !== 'function') return null;
+  
+    const fnStr = fn.toString();
+  
+    const docMatch = fnStr.match(/\/\*\*([\s\S]*?)\*\//);
+    if (!docMatch) return null;
+  
+    const doc = docMatch[1];
+  
+    const routeMatch = doc.match(/@register_router\s+([^\s]+)/);
+    if (!routeMatch) return null;
+  
+    const path = routeMatch[1].trim();
+  
+    const methodMatch = doc.match(/@method\s+([^\s]+)/);
+    const method = methodMatch ? methodMatch[1].trim().toLowerCase() : "get";
+  
+    return {
+      path,
+      method,
+      handler: fn
+    };
+  }
+  
+  module.exports = { parseRouter };
+  

package/src/core/parse/tools.js

@@ -0,0 +1,82 @@
+function parseTool(fn) {
+  const meta = {
+    name: fn.name || null,
+    description: null,
+    parameters: [],
+    call: fn,
+    condition: { only: [], never: [], when: [] }
+  };
+
+  const fnString = fn.toString();
+  const jsdocMatch = fnString.match(/\/\*\*([\s\S]*?)\*\//);
+  if (!jsdocMatch) return null;
+
+  const lines = jsdocMatch[1].split('\n').map(l => l.trim().replace(/^\*\s?/, ''));
+
+  const registerLine = lines.find(l => l.startsWith('@register_tool'));
+  if (!registerLine) return null;
+
+  const registerMatch = registerLine.match(/@register_tool\s*(\S+)?/);
+  if (registerMatch && registerMatch[1]) {
+    meta.name = registerMatch[1];
+  } else if (!meta.name) {
+    meta.name = 'anonymousTool';
+  }
+
+  const paramMap = {};
+
+  const descriptionLine = lines.find(l => l.startsWith('@description'));
+  if (descriptionLine) meta.description = descriptionLine.replace('@description', '').trim();
+
+  lines.forEach(line => {
+    if (line.startsWith('@param')) {
+      const match = line.match(/@param {([\w\[\]\?]+)} (\S+) - (.+)/);
+      if (!match) return;
+
+      let [_, type, name, description] = match;
+      let required = !type.endsWith('?');
+      if (!required) type = type.slice(0, -1);
+
+      const cleanName = name.replace(/\[\]/g, '');
+      const isArray = name.includes('[]');
+      const isNested = cleanName.includes('.');
+
+      if (isNested) {
+        const parentName = cleanName.split('.')[0];
+        if (!paramMap[parentName]) {
+          const parent = {
+            name: parentName,
+            type: isArray ? 'array' : 'object',
+            description: `${parentName} object`,
+            required
+          };
+          meta.parameters.push(parent);
+          paramMap[parentName] = parent;
+        } else if (required) {
+          paramMap[parentName].required = true;
+        }
+      }
+
+      const param = { name, type, description, required };
+      meta.parameters.push(param);
+      paramMap[name] = param;
+    }
+
+    const onlyMatch = line.match(/@only\s+([^\s]+)/);
+    if (onlyMatch) meta.condition.only.push(onlyMatch[1]);
+
+    const neverMatch = line.match(/@never\s+([^\s]+)/);
+    if (neverMatch) meta.condition.never.push(neverMatch[1]);
+
+    const whenMatch = line.match(/@when\s+([^\s]+)/);
+    if (whenMatch) meta.condition.when.push(whenMatch[1]);
+  });
+
+  Object.keys(meta.condition).forEach(k => {
+    if (meta.condition[k].length === 0) delete meta.condition[k];
+  });
+
+  return meta;
+}
+
+module.exports = { parseTool };

package/src/core/register/decorators.js

@@ -0,0 +1,150 @@
+const path = require('path');
+const fs = require('fs').promises;
+
+const { parseTool } = require('../parse/tools');
+const { parseHook } = require('../parse/hooks');
+const { parseCognite } = require('../parse/cognites');
+const { parseRouter } = require('../parse/routes');
+const { parsePredicate } = require('../parse/predicates');
+const { parseMiddleware } = require('../parse/middleware');
+
+async function getJsFilesRecursively(dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const tasks = entries.map(async entry => {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) return getJsFilesRecursively(fullPath);
+    if (entry.isFile() && entry.name.endsWith('.js')) return [fullPath];
+    return [];
+  });
+  const results = await Promise.all(tasks);
+  return results.flat();
+}
+
+async function isRelevantFile(filePath) {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return content.includes('@register_');
+  } catch {
+    return false;
+  }
+}
+
+function extractExportedFunctions(mod) {
+  if (typeof mod === 'function') return [mod];
+  if (typeof mod === 'object' && mod !== null) return Object.values(mod);
+  return [];
+}
+
+async function registerGeneric(agentFolder, parser, mapFn) {
+  const baseDir = process.env.PACKAGES_PATH || path.resolve(__dirname, '..', '..', 'packages');
+  
+  let folderPath;
+  if (path.isAbsolute(String(agentFolder))) {
+    folderPath = agentFolder;
+  } else if (String(agentFolder).includes('packages')) {
+    const folderName = path.basename(agentFolder);
+    folderPath = path.join(baseDir, folderName);
+  } else {
+    folderPath = path.join(baseDir, String(agentFolder));
+  }
+
+  try {
+    await fs.access(folderPath);
+  } catch {
+    throw new Error(`Folder not found: ${folderPath}`);
+  }
+
+  const files = await getJsFilesRecursively(folderPath);
+
+  const results = await Promise.all(
+    files.map(async filePath => {
+      if (!(await isRelevantFile(filePath))) return [];
+      try {
+        const absolutePath = path.resolve(filePath);
+        delete require.cache[require.resolve(absolutePath)];
+        const mod = require(absolutePath);
+
+        return extractExportedFunctions(mod)
+          .map(fn => {
+            const meta = parser(fn);
+            if (!meta) return null;
+            return mapFn(meta);
+          })
+          .filter(Boolean);
+      } catch (err) {
+        console.warn(`Erro ao registrar em ${filePath}:`, err.message);
+        return [];
+      }
+    })
+  );
+
+  return results.flat();
+}
+
+function registerTools(agentFolder) {
+  return registerGeneric(agentFolder, parseTool, meta => {
+    const tool = {
+      name: meta.name,
+      description: meta.description,
+      parameters: {
+        type: 'object',
+        properties: (meta.parameters || []).reduce((acc, p) => {
+          acc[p.name] = { type: p.type === 'array' ? 'array' : p.type, description: p.description };
+          if (p.type === 'array') acc[p.name].items = { type: 'object' };
+          return acc;
+        }, {}),
+        required: (meta.parameters || []).filter(p => p.required).map(p => p.name),
+      },
+      call: meta.call,
+    };
+    if (meta.condition) tool.condition = meta.condition;
+    return tool;
+  });
+}
+
+function registerHooks(agentFolder) {
+  return registerGeneric(agentFolder, parseHook, meta => {
+    const hook = { event: meta.event, call: meta.call };
+    if (meta.condition) hook.condition = meta.condition;
+    return hook;
+  });
+}
+
+function registerCognites(agentFolder) {
+  return registerGeneric(agentFolder, parseCognite, meta => ({
+    name: meta.name,
+    description: meta.description,
+    execute: meta.execute,
+    options: meta.options || {},
+  }));
+}
+
+function registerRoutes(agentFolder) {
+  return registerGeneric(agentFolder, parseRouter, meta => ({
+    path: meta.path,
+    method: meta.method || 'get',
+    handler: meta.handler,
+  }));
+}
+
+async function registerPredicates(agentFolder) {
+  const preds = await registerGeneric(agentFolder, parsePredicate, meta => meta);
+  return Object.fromEntries(preds.map(p => [p.name, p.call]));
+}
+
+function registerMiddlewares(agentFolder) {
+  return registerGeneric(agentFolder, parseMiddleware, meta => ({
+    name: meta.name,
+    call: meta.call,
+    predicates: meta.predicates || []
+  }));
+}
+
+module.exports = {
+  registerTools,
+  registerHooks,
+  registerCognites,
+  registerRoutes,
+  registerPredicates,
+  registerMiddlewares
+};

package/src/core/register/decorators.test.js

@@ -0,0 +1,13 @@
+import { describe, it, expect, vi } from 'vitest';
+import fs from 'fs/promises';
+import path from 'path';
+const { registerTools } = require('./decorators');
+
+vi.mock('fs/promises');
+
+describe('decorators register', () => {
+  it('should throw error if folder does not exist', async () => {
+    fs.access.mockRejectedValue(new Error());
+    await expect(registerTools('invalid')).rejects.toThrow('Folder not found');
+  });
+});

package/src/core/register.js

@@ -0,0 +1,37 @@
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+const { getPackages, registerPackage } = require('./package');
+const { registerRoutes } = require('./routes');
+const { log } = console;
+
+const registerPackages = async (app) => {
+    try {
+        const packagesList = await getPackages();
+
+        for (const pkg of packagesList) {
+            const ymlPath = path.join(__dirname, '..', 'packages', pkg.folder, 'agent.yml');
+
+            const exists = fs.existsSync(ymlPath);
+            if (exists) {
+                try {
+                    const fileContents = fs.readFileSync(ymlPath, 'utf8');
+                    const ymlObject = yaml.load(fileContents);
+                    pkg.config = ymlObject;
+                    
+                    log(`Loaded YAML for package: ${JSON.stringify(pkg.config)}`);
+                } catch (err) {
+                    log(`Error reading YAML for ${pkg.folder}: ${err.message}`);
+                }
+            }
+
+            await registerRoutes(app, pkg);
+            await registerPackage(app, pkg);
+        }
+    } catch (err) {
+        log(JSON.stringify(err), "red");
+    }
+};
+
+module.exports = { registerPackages };

package/src/core/routes.js

@@ -0,0 +1,89 @@
+const path = require('path');
+const fs = require('fs');
+const { registerRoutes: routesDecorators, registerCognites, registerPredicates, registerMiddlewares } = require("./register/decorators");
+
+const { log } = console;
+
+const getRoutes = () => {
+    const routes = [];
+    const baseDir = process.env.PACKAGES_PATH || path.resolve(__dirname, '..', 'packages');
+
+    try {
+        fs.readdirSync(baseDir).forEach(packageDir => {
+            const routesPath = path.join(baseDir, packageDir, 'routes.js');
+
+            if (fs.existsSync(routesPath)) {
+                const routeModule = require(path.resolve(routesPath));
+                routeModule.map(router => router.dir = packageDir);
+
+                routes.push(...routeModule);
+            }
+        });
+    } catch (error) {
+        console.error("Error with Routes:", error);
+        return [];
+    }
+
+    return routes;
+};
+
+const registerRoutes = async (app, pkg) => {
+    const basePackagesPath = process.env.PACKAGES_PATH || path.resolve(__dirname, '..', 'packages');
+    const packageDir = path.join(basePackagesPath, pkg.folder);
+    const routesRegex = /^routes\.(js|tsx)$/;
+    const files = fs.readdirSync(packageDir);
+    const routesFile = files.find((file) => routesRegex.test(file));
+
+    const _routesDecorators = await routesDecorators(pkg.folder);
+
+    const predicates = await registerPredicates(pkg.folder);
+    const middlewares = await registerMiddlewares(pkg.folder);
+
+    let allow_middlewares = [];
+
+    middlewares.map(middleware => {
+        middleware.predicates.map(predicate => {
+            if (predicates[predicate]) {
+                try {
+                    if ( predicates[predicate]() ) {
+                        allow_middlewares.push( middleware.call );
+                    }
+                } catch(err) {
+                }
+            }
+        });
+    });
+
+    let _routesFile = [];
+
+    const allRoutes = [..._routesDecorators, ..._routesFile];
+
+    if (allRoutes.length === 0) {
+        return;
+    }
+
+    allRoutes.forEach((route) => {
+        if (route.handler && route.method && route.path) {
+            app[route.method](`/${pkg.folder}/${route.path}`, [...allow_middlewares, async (req, res, next) => {
+                try {
+                    const payload = await route.handler(req, res, next);
+                    const { status = 200, data = payload } = payload || {};
+                    res.status(status).json(data);
+                } catch (err) {
+                    next(err);
+                }
+            }]);
+
+            log(`${pkg.name ?? pkg.folder} registered decorator route [${route.method.toUpperCase()}] /${pkg.folder}/${route.path}`, 'gray');
+        } 
+        else if (route.call && route.method && route.router) {
+            app[route.method](`/${pkg.folder}/${route.router}`, route.call);
+            log(`${pkg.name} registered file route [${route.method.toUpperCase()}] /${pkg.folder}/${route.router}`, 'gray');
+        } 
+        else {
+            log(`Invalid route configuration for ${pkg.name}: ${JSON.stringify(route)}`, 'error');
+        }
+    });
+};
+
+module.exports = { getRoutes, registerRoutes }

package/src/index.ts

@@ -0,0 +1,42 @@
+import path from 'path'
+import http from 'http'
+import app from './app'
+import { dispatchEvent } from './core/event/dispatch'
+import type { BootstrapConfig, JohankitApp } from './types'
+
+export async function bootstrap(config: BootstrapConfig = {}) {
+  const customPath = config.workspace || path.join(__dirname, 'packages')
+  const resolvedWorkspace = path.isAbsolute(customPath)
+    ? customPath
+    : path.resolve(process.cwd(), customPath)
+
+  process.env.PACKAGES_PATH = resolvedWorkspace
+
+  const result: any = {}
+
+  await app.setup()
+  result.app = app as JohankitApp
+
+  if (config.mcp?.enabled) {
+    const { bootstrapMcp } = require('./core/mcp/tools-mcp')
+    result.mcp = await bootstrapMcp(resolvedWorkspace)
+  }
+
+  if (config.mcp?.http?.enabled) {
+    const { createMcpHttpServer } = require('./core/mcp/http-server')
+    result.mcpHttp = await createMcpHttpServer({
+      workspace: resolvedWorkspace,
+      port: config.mcp.http.port
+    })
+  }
+
+  if (config.http?.enabled !== false) {
+    const port = config.http?.port || (process.env.PORT ? Number(process.env.PORT) : 5040)
+    result.server = http.createServer(app)
+    result.server.listen(port)
+  }
+
+  return result
+}
+
+export { dispatchEvent }

package/src/server.ts

@@ -0,0 +1,15 @@
+import http from 'http'
+import app from './app'
+
+const port = process.env.PORT ? Number(process.env.PORT) : 5040
+
+app
+  .setup()
+  .then(() => {
+    http.createServer(app).listen(port, () => {
+      console.log(`Server is ready on port: ${port}.\n`)
+    })
+  })
+  .catch(err => {
+    console.error('Error during app setup:', err)
+  })

package/src/types.ts

@@ -0,0 +1,104 @@
+import type { Application, Request, Response, NextFunction } from 'express';
+
+export interface BootstrapConfig {
+  workspace?: string;
+  http?: {
+    enabled?: boolean;
+    port?: number;
+  };
+  mcp?: {
+    enabled?: boolean;
+    http?: {
+      enabled?: boolean;
+      port?: number;
+    };
+  };
+}
+
+export interface RoutePayload {
+  status?: number;
+  data?: any;
+}
+
+export type RouteHandler = (
+  req: Request,
+  res: Response,
+  next: NextFunction
+) => Promise<RoutePayload | any> | RoutePayload | any;
+
+export interface RegisteredRoute {
+  path: string;
+  method: string;
+  handler: RouteHandler;
+}
+
+export interface HookCondition {
+  only?: string[];
+  never?: string[];
+  when?: string[];
+}
+
+export interface RegisteredHook<T = any> {
+  event: string;
+  call: (payload: T) => Promise<T | void | null> | T | void | null;
+  condition?: HookCondition;
+}
+
+export interface RegisteredPredicate {
+  name: string;
+  call: () => boolean | Promise<boolean>;
+}
+
+export interface RegisteredMiddleware {
+  name: string;
+  call: (req: Request, res: Response, next: NextFunction) => any;
+  predicates?: string[];
+}
+
+export interface ToolParameter {
+  name: string;
+  type: string;
+  description?: string;
+  required?: boolean;
+}
+
+export interface RegisteredTool {
+  name: string;
+  description?: string;
+  parameters: {
+    type: 'object';
+    properties: Record<string, any>;
+    required?: string[];
+  };
+  call: (args: any) => any;
+  condition?: HookCondition;
+}
+
+export interface RegisteredCognite {
+  name: string;
+  execute: (...args: any[]) => any;
+  description?: string;
+  options?: Record<string, any>;
+}
+
+export interface PackageManifest {
+  name?: string;
+  version?: string;
+  entry?: string;
+  folder: string;
+  dir?: string;
+  config?: any;
+}
+
+export interface JohankitApp extends Application {
+  setup: () => Promise<void>;
+}
+
+export declare function bootstrap(
+  config?: BootstrapConfig
+): Promise<any>;
+
+export declare function dispatchEvent<T = any>(
+  eventName: string,
+  payload: T
+): Promise<T>;