@telorun/kernel 0.2.4 → 0.2.5

package/src/controller-registry.ts

@@ -0,0 +1,206 @@
+import { ControllerInstance, ResourceDefinition, RuntimeResource } from "@telorun/sdk";
+import * as path from "path";
+
+/**
+ * ControllerRegistry: Manages controller loading and dispatch
+ * Maps fully-qualified resource kinds to their controller implementations
+ */
+export class ControllerRegistry {
+  private controllersByKind: Map<string, ControllerInstance> = new Map();
+  private definitionsByKind: Map<string, ResourceDefinition> = new Map();
+  private controllerLoaders: Map<string, () => Promise<ControllerInstance>> = new Map();
+  private capabilitySchemas: Map<string, Record<string, any> | null> = new Map();
+
+  registerCapability(name: string, schema?: Record<string, any>): void {
+    this.capabilitySchemas.set(name, schema ?? null);
+  }
+
+  isCapabilityRegistered(name: string): boolean {
+    return this.capabilitySchemas.has(name);
+  }
+
+  getCapabilitySchema(name: string): Record<string, any> | null | undefined {
+    return this.capabilitySchemas.get(name);
+  }
+
+  /**
+   * Register a controller definition
+   */
+  registerDefinition(
+    definition: ResourceDefinition,
+    // baseDir?: string,
+    // namespace?: string | null,
+  ): void {
+    // Construct fully qualified kind: Namespace.Name
+    // Only add namespace if name is not already qualified (doesn't contain a dot)
+    const namespace = definition.metadata.module;
+    const baseDir = null;
+    const name = definition.metadata.name;
+    const kind = namespace && !name.includes(".") ? `${namespace}.${name}` : name;
+
+    this.definitionsByKind.set(kind, definition);
+
+    // If definition has controllers, register loader for them
+    if (definition.controllers && definition.controllers.length > 0 && baseDir) {
+      this.registerControllerLoader(kind, definition, baseDir);
+    }
+  }
+
+  /**
+   * Get a controller instance for a kind
+   * Lazy-loads controller code on first access
+   * Throws if controller not found
+   */
+  getController(kind: string): ControllerInstance {
+    // Return cached instance if available
+    if (this.controllersByKind.has(kind)) {
+      return this.controllersByKind.get(kind)!;
+    }
+
+    // Load controller if loader is registered
+    // const loader = this.controllerLoaders.get(kind);
+    // if (loader) {
+    //   const controller = await loader();
+    //   this.controllersByKind.set(kind, controller);
+    //   return controller;
+    // }
+
+    throw new Error(`No controller registered for kind: ${kind}`);
+  }
+
+  /**
+   * Safe get - returns undefined if controller not found
+   */
+  getControllerOrUndefined(kind: string): ControllerInstance | undefined {
+    // Return cached instance if available
+    if (this.controllersByKind.has(kind)) {
+      return this.controllersByKind.get(kind);
+    }
+    return undefined;
+  }
+
+  /**
+   * Check if a controller exists for this kind (definition or directly registered)
+   */
+  hasController(kind: string): boolean {
+    return this.controllersByKind.has(kind) || this.definitionsByKind.has(kind);
+  }
+
+  /**
+   * Get definition for a kind
+   */
+  getDefinition(kind: string): ResourceDefinition | undefined {
+    return this.definitionsByKind.get(kind);
+  }
+
+  /**
+   * Get all registered kinds
+   */
+  getKinds(): string[] {
+    return Array.from(this.definitionsByKind.keys());
+  }
+
+  getControllerKinds(): string[] {
+    return Array.from(this.controllersByKind.keys());
+  }
+
+  /**
+   * Create a resource instance using its controller
+   */
+  async create(kind: string, resource: RuntimeResource, ctx: any): Promise<any | null> {
+    const controller = this.getController(kind);
+    if (!controller || !controller.create) {
+      return null;
+    }
+    return controller.create(resource, ctx);
+  }
+
+  /**
+   * Register a controller for a kind
+   */
+  registerController(kind: string, controller: ControllerInstance): void {
+    if (!this.definitionsByKind.has(kind)) {
+      throw new Error(`Cannot register controller for kind ${kind} without definition`);
+    }
+    // Ensure controller has schema from definition
+    const definition = this.definitionsByKind.get(kind);
+    if (definition?.schema && !controller.schema) {
+      // Wrap controller to add schema without mutating the original
+      const wrappedController: ControllerInstance = {
+        ...controller,
+        schema: definition.schema,
+      };
+      this.controllersByKind.set(kind, wrappedController);
+    } else {
+      this.controllersByKind.set(kind, controller);
+    }
+  }
+
+  /**
+   * Private: Register controller loader
+   */
+  private registerControllerLoader(
+    kind: string,
+    definition: ResourceDefinition,
+    moduleDir: string,
+  ): void {
+    const controllerDef = definition.controllers?.[0]; // Use first matching controller for now
+    if (!controllerDef) return;
+
+    this.controllerLoaders.set(kind, async () => {
+      const modulePath = path.resolve(moduleDir, controllerDef.entry);
+      const moduleRuntime = await import(modulePath);
+      const exported = moduleRuntime.default || moduleRuntime.Module || moduleRuntime;
+
+      const registerFn =
+        typeof moduleRuntime.register === "function"
+          ? moduleRuntime.register
+          : typeof exported === "function" && !this.isModuleClass(exported)
+            ? exported
+            : null;
+
+      const createFn =
+        typeof moduleRuntime.create === "function"
+          ? moduleRuntime.create
+          : typeof exported?.create === "function"
+            ? exported.create
+            : null;
+
+      const executeFn =
+        typeof moduleRuntime.execute === "function"
+          ? moduleRuntime.execute
+          : typeof exported?.execute === "function"
+            ? exported.execute
+            : null;
+
+      const compileFn =
+        typeof moduleRuntime.compile === "function"
+          ? moduleRuntime.compile
+          : typeof exported?.compile === "function"
+            ? exported.compile
+            : null;
+
+      if (!registerFn && !executeFn && !createFn && !compileFn) {
+        throw new Error(`Controller for "${kind}" exports no usable handlers`);
+      }
+
+      if (!definition.schema) {
+        throw new Error(`Definition for "${kind}" does not have schema`);
+      }
+
+      return {
+        register: registerFn ?? undefined,
+        create: createFn ?? undefined,
+        execute: executeFn ?? undefined,
+        compile: compileFn ?? undefined,
+        schema: definition.schema,
+      };
+    });
+  }
+
+  private isModuleClass(obj: any): boolean {
+    return (
+      typeof obj === "function" && (obj.name === "Controller" || obj.toString().includes("class"))
+    );
+  }
+}

package/src/controllers/capability/capability-controller.ts

@@ -0,0 +1,41 @@
+import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+
+type CapabilityResource = {
+  kind: string;
+  metadata: {
+    name: string;
+    [key: string]: any;
+  };
+  schema?: Record<string, any>;
+};
+
+class Capability implements ResourceInstance {
+  constructor(private readonly resource: CapabilityResource) {}
+
+  async init(ctx: ResourceContext) {
+    ctx.registerCapability(this.resource.metadata.name, this.resource.schema);
+  }
+}
+
+export async function create(resource: any, _ctx: ResourceContext): Promise<Capability> {
+  return new Capability(resource as CapabilityResource);
+}
+
+export const schema = {
+  type: "object",
+  properties: {
+    metadata: {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+      },
+      required: ["name"],
+    },
+    schema: {
+      type: "object",
+      additionalProperties: true,
+    },
+  },
+  required: ["metadata"],
+  additionalProperties: true,
+};

package/src/controllers/module/import-controller.ts

@@ -0,0 +1,143 @@
+import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import { EvaluationContext } from "@telorun/sdk";
+import { Loader } from "../../loader.js";
+
+export async function create(resource: any, ctx: ResourceContext): Promise<ResourceInstance> {
+  const alias = resource.metadata.name as string;
+  const declaringModule: string = resource.metadata.module ?? "default";
+  const loader = new Loader();
+
+  // Load target module manifests. Inject variables/secrets as compile context so that
+  // ${{ variables.x }} / ${{ secrets.y }} templates in the child module resolve correctly.
+  // No env — child modules are isolated from host environment.
+  const manifests = await loader.loadManifest(resource.source as string, ctx.moduleContext.source, {
+    // Potentially not needed
+    variables: (resource.variables as Record<string, unknown>) ?? {},
+    secrets: (resource.secrets as Record<string, unknown>) ?? {},
+  });
+  // Find the kind: Module manifest to learn the target module name and contract.
+  const moduleManifest = manifests.find((m: any) => m.kind === "Kernel.Module");
+  if (!moduleManifest) {
+    throw new Error(`No kind: Module manifest found in source "${resource.source as string}"`);
+  }
+  const targetModule: string = moduleManifest.metadata.name;
+
+  // Validate that every non-module manifest's metadata.module (when explicitly set)
+  // matches the target module name.  A mismatch means the author put the wrong module
+  // name in a resource's metadata, which would silently give it an empty context and
+  // produce a confusing CEL "Identifier not found" error at runtime.
+  for (const manifest of manifests) {
+    if (manifest.kind === "Kernel.Module") continue;
+    const declaredModule: string | undefined = manifest.metadata?.module;
+    if (declaredModule && declaredModule !== targetModule) {
+      throw new Error(
+        `Resource '${manifest.metadata?.name ?? "(unnamed)"}' (kind: ${manifest.kind}) inside module '${targetModule}' ` +
+          `has metadata.module: '${declaredModule}', but the module is named '${targetModule}'. ` +
+          `Update metadata.module to '${targetModule}'.`,
+      );
+    }
+  }
+
+  // Validate required inputs before injecting.
+  validateRequiredInputs(moduleManifest.variables ?? {}, resource.variables ?? {}, "variables");
+  validateRequiredInputs(moduleManifest.secrets ?? {}, resource.secrets ?? {}, "secrets");
+
+  // Create child context with the imported variables/secrets baked in, so that
+  // ${{ variables.x }} / ${{ secrets.y }} templates resolve correctly at runtime.
+  const child = ctx.moduleContext.spawnChild(
+    new EvaluationContext(
+      ctx.moduleContext.source,
+      {
+        variables: (resource.variables as Record<string, unknown>) ?? {},
+        secrets: (resource.secrets as Record<string, unknown>) ?? {},
+        resources: {},
+      },
+      ctx.moduleContext.createInstance,
+      ctx.moduleContext.secretValues,
+      ctx.moduleContext.emit,
+    ),
+  );
+
+  for (const manifest of manifests) {
+    child.registerManifest(manifest);
+  }
+
+  // Link the target module context as a child of the declaring module context in
+  // the lifecycle tree. This enables cascading teardown (parent → child order)
+  // and makes the import hierarchy visible at runtime.
+  // const declaringCtx: ModuleContext = ctx.getModuleContext(declaringModule);
+  // const targetCtx: ModuleContext = (ctx as any).getModuleContext(targetModule);
+  // if (!targetCtx.parent) {
+  //   declaringCtx.spawnChild(targetCtx);
+  // }
+
+  // Try to evaluate the target module's exports.
+  // Throws if resources.X is not yet populated — the kernel retry loop catches this and retries.
+  // const evaluatedExports: any = child.expand(moduleManifest.exports ?? {});
+
+  const exportedKinds: string[] = moduleManifest.exports?.kinds ?? [];
+  ctx.registerModuleImport(alias, targetModule, exportedKinds);
+  // Return a ResourceInstance whose snapshot() surfaces the exported values.
+  // The kernel's generic setResource() call stores them under resources.<alias>
+  // in the declaring module's evaluation context — no separate imports namespace needed.
+  return {
+    snapshot: () => ({
+      variables: (resource.variables as Record<string, unknown>) ?? {},
+      secrets: (resource.secrets as Record<string, unknown>) ?? {},
+    }),
+    run: async () => {
+      // Proxy run to target module
+      for (const target of (moduleManifest.targets as string[]) ?? []) {
+        await child.run(target);
+      }
+    },
+    invoke: async () => {
+      // Proxy run to target module
+      // for (const target of (moduleManifest.targets as string[]) ?? []) {
+      //   child.invoke(target);
+      // }
+      console.log("invoking");
+    },
+    init: async () => {
+      await child.initializeResources();
+    },
+    teardown: async () => {
+      await child.teardownResources();
+    },
+  };
+}
+
+function validateRequiredInputs(
+  schemaDefs: Record<string, any>,
+  provided: Record<string, unknown>,
+  kind: "variables" | "secrets",
+): void {
+  for (const [key, def] of Object.entries(schemaDefs)) {
+    const isRequired = typeof def === "object" && def !== null && !("default" in def);
+    if (isRequired && !(key in provided)) {
+      throw new Error(`Required ${kind} input "${key}" not provided for module import`);
+    }
+  }
+}
+
+export const schema = {
+  type: "object",
+  properties: {
+    kind: { type: "string" },
+    metadata: {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        source: { type: "string" },
+        module: { type: "string" },
+      },
+      required: ["name"],
+      additionalProperties: true,
+    },
+    source: { type: "string" },
+    variables: { type: "object" },
+    secrets: { type: "object" },
+  },
+  required: ["metadata", "source"],
+  additionalProperties: false,
+};

package/src/controllers/module/module-controller.ts

@@ -0,0 +1,67 @@
+import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import { Loader } from "../../loader.js";
+
+export async function create(resource: any, ctx: ResourceContext): Promise<ResourceInstance> {
+  const moduleName = resource.metadata.name as string;
+  const loader = new Loader();
+
+  for (const includePath of (resource.include as string[]) ?? []) {
+    const manifests = await loader.loadManifest(
+      includePath,
+      resource.metadata.source as string,
+      {},
+    );
+    for (const manifest of manifests) {
+      if (manifest.kind === "Kernel.Module") {
+        throw new Error(`Included file "${includePath}" must not declare kind: Module`);
+      }
+      if (!manifest.metadata.module) {
+        manifest.metadata.module = moduleName;
+      }
+      ctx.registerManifest(manifest);
+    }
+  }
+
+  return {
+    run: async () => {
+      for (const target of (resource.targets as string[]) ?? []) {
+        const [kind, name] = target.split(".");
+        if (!kind || !name) {
+          throw new Error(`Invalid target format: "${target}". Expected "Kind.Name"`);
+        }
+        await ctx.invoke(kind, name, {});
+      }
+    },
+  };
+}
+
+export const schema = {
+  type: "object",
+  properties: {
+    kind: { type: "string" },
+    metadata: {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        version: { type: "string" },
+        source: { type: "string" },
+        module: { type: "string" },
+      },
+      required: ["name"],
+      additionalProperties: true,
+    },
+    include: { type: "array", items: { type: "string" } },
+    variables: { type: "object" },
+    secrets: { type: "object" },
+    targets: { type: "array", items: { type: "string" } },
+    exports: {
+      type: "object",
+      properties: {
+        kinds: { type: "array", items: { type: "string" } },
+      },
+      additionalProperties: true,
+    },
+  },
+  required: ["metadata"],
+  additionalProperties: false,
+};

package/src/controllers/module/module.json

@@ -0,0 +1,48 @@
+{
+  "type": "object",
+  "properties": {
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        }
+      },
+      "required": ["name"]
+    },
+    "imports": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Paths to other modules to import"
+    },
+    "definitions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Paths to ResourceDefinition files"
+    },
+    "resources": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "path": {
+                "type": "string"
+              }
+            }
+          }
+        ]
+      },
+      "description": "Paths to resource instance files to load"
+    }
+  },
+  "required": ["metadata"]
+}

package/src/controllers/resource-definition/resource-definition-controller.ts

@@ -0,0 +1,87 @@
+import type {
+  ControllerContext,
+  ResourceContext,
+  ResourceInstance,
+  RuntimeResource,
+} from "@telorun/sdk";
+import { ControllerLoader } from "../../controller-loader.js";
+import { formatAjvErrors, validateResourceDefinition } from "../../manifest-schemas.js";
+
+type ResourceDefinitionResource = RuntimeResource & {
+  kind: "Definition";
+  metadata: {
+    [key: string]: any;
+    name: string;
+    module?: string;
+  };
+  schema: Record<string, any>;
+  capabilities: string[];
+  events?: string[];
+  controllers: Array<string>;
+};
+
+/**
+ * ResourceDefinition resource - acts as metadata holder for resource type definitions
+ * Validates incoming definitions against schema and maintains definition metadata
+ */
+class ResourceDefinition implements ResourceInstance {
+  readonly kind: "ResourceDefinition" = "ResourceDefinition";
+
+  constructor(
+    readonly resource: ResourceDefinitionResource,
+    private controllerLoader: ControllerLoader,
+  ) {}
+
+  async init(ctx: ResourceContext) {
+    for (const cap of this.resource.capabilities) {
+      if (!ctx.isCapabilityRegistered(cap)) {
+        throw new Error(
+          `Capability "${cap}" is not registered. Declare it as a Kernel.Capability resource.`,
+        );
+      }
+      const capSchema = ctx.getCapabilitySchema(cap);
+      if (capSchema) {
+        ctx.validateSchema(this.resource, capSchema);
+      }
+    }
+    ctx.emit("ControllerLoading", { controllers: this.resource.controllers });
+    try {
+      const controllerInstance = await this.controllerLoader.load(
+        this.resource.controllers,
+        this.resource.metadata.source,
+      );
+      ctx.emit("ControllerLoaded", { schema: controllerInstance.schema });
+      ctx.registerDefinition(this.resource);
+      await ctx.registerController(
+        this.resource.metadata.module,
+        this.resource.metadata.name,
+        controllerInstance,
+      );
+    } catch (err) {
+      ctx.emit("ControllerLoadFailed", { error: (err as Error).message });
+      throw err;
+    }
+  }
+}
+
+export function register(ctx: ControllerContext): void {
+  // ResourceDefinition is a passive resource - no registration needed
+}
+
+export async function create(resource: any, ctx: ResourceContext): Promise<ResourceDefinition> {
+  // Validate incoming resource definition against schema
+  if (!validateResourceDefinition(resource)) {
+    throw new Error(
+      `Invalid ResourceDefinition "${resource.metadata.name}": ${formatAjvErrors(validateResourceDefinition.errors)}`,
+    );
+  }
+
+  // Return a fully-formed ResourceDefinition instance
+  const definition = resource as ResourceDefinitionResource;
+  return new ResourceDefinition(definition, new ControllerLoader());
+}
+
+export const schema = {
+  type: "object",
+  additionalProperties: true,
+};

package/src/controllers/resource-definition/resource-definition.json

@@ -0,0 +1,18 @@
+{
+  "type": "object",
+  "properties": {
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        }
+      },
+      "required": ["name"]
+    },
+    "schema": {
+      "type": "object"
+    }
+  },
+  "required": ["metadata", "schema"]
+}