@telorun/kernel 0.2.4 → 0.2.6

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

@@ -0,0 +1,143 @@
+import { DiagnosticSeverity, Loader, StaticAnalyzer } from "@telorun/analyzer";
+import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import { EvaluationContext, RuntimeError } from "@telorun/sdk";
+import { LocalFileAdapter } from "../../manifest-adapters/local-file-adapter.js";
+
+export async function create(resource: any, ctx: ResourceContext): Promise<ResourceInstance> {
+  const alias = resource.metadata.name as string;
+  const loader = new Loader([new LocalFileAdapter()]);
+
+  const moduleSource: string = resource.module ?? resource.source;
+
+  // Validate the imported module and all its transitive imports before loading for runtime.
+  // loadManifests() follows Kernel.Import chains so definitions from sub-imports are present,
+  // preventing false UNDEFINED_KIND errors for kinds that come from the module's own imports.
+  const resolvedUrl = new URL(moduleSource, ctx.moduleContext.source).toString();
+  const analysisManifests = await loader.loadManifests(resolvedUrl);
+  const diagnostics = new StaticAnalyzer().analyze(analysisManifests);
+  const errors = diagnostics.filter((d) => d.severity === DiagnosticSeverity.Error);
+  if (errors.length > 0) {
+    throw new RuntimeError(
+      "ERR_MANIFEST_VALIDATION_FAILED",
+      errors.map((d) => d.message).join("\n"),
+    );
+  }
+
+  // Load target module manifests for runtime. 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.loadModule(
+    new URL(moduleSource, ctx.moduleContext.source).toString(),
+    {
+      compile: true,
+    },
+  );
+  // 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 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: ctx.expandValue(resource.variables, {}) ?? {},
+      secrets: ctx.expandValue(resource.secrets, {}) ?? {},
+    }),
+    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" },
+        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,16 @@
+import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+
+export async function create(resource: any, ctx: ResourceContext): Promise<ResourceInstance> {
+  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, {});
+      }
+    },
+  };
+}
+

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

@@ -0,0 +1,86 @@
+import type {
+  ControllerContext,
+  ResourceContext,
+  ResourceInstance,
+  RuntimeResource,
+} from "@telorun/sdk";
+import { ControllerLoader } from "../../controller-loader.js";
+import { formatAjvErrors, validateResourceDefinition } from "../../manifest-schemas.js";
+import { createTemplateController } from "./resource-template-controller.js";
+
+type ResourceDefinitionResource = RuntimeResource & {
+  kind: "Kernel.Definition";
+  metadata: {
+    [key: string]: any;
+    name: string;
+    module?: string;
+  };
+  schema: Record<string, any>;
+  capability?: 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) {
+    if (!this.resource.controllers?.length) {
+      const controllerInstance = createTemplateController(this.resource as any);
+      ctx.registerDefinition(this.resource);
+      await ctx.registerController(
+        this.resource.metadata.module,
+        this.resource.metadata.name,
+        controllerInstance,
+      );
+      return;
+    }
+    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 unknown 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"]
+}

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

@@ -0,0 +1,138 @@
+import type { ControllerInstance, ResourceContext, ResourceInstance } from "@telorun/sdk";
+import { isCompiledValue } from "@telorun/sdk";
+
+export function createTemplateController(definition: {
+  schema: Record<string, any>;
+  resources?: any[];
+  invoke?: string | { kind?: string; name: string; inputs?: Record<string, any> };
+  run?: string;
+}): ControllerInstance {
+  return {
+    schema: definition.schema ?? { type: "object", additionalProperties: true },
+
+    create: async (resource: any, ctx: ResourceContext): Promise<ResourceInstance> => {
+      const self = { ...resource, name: resource.metadata.name };
+
+      // Old string form: invoke is a plain string or a CompiledValue (after precompile).
+      // New object form: invoke is a plain object (non-CompiledValue) with at least `name`.
+      const objectInvoke =
+        definition.invoke !== null &&
+        typeof definition.invoke === "object" &&
+        !isCompiledValue(definition.invoke)
+          ? (definition.invoke as { kind?: string; name: string; inputs?: Record<string, any> })
+          : null;
+      const invokeNameTemplate = objectInvoke ? objectInvoke.name : (definition.invoke ?? null);
+      const invokeTarget = invokeNameTemplate
+        ? (ctx.moduleContext.expandWith(invokeNameTemplate, { self }) as string)
+        : null;
+      const runTarget = definition.run
+        ? (ctx.moduleContext.expandWith(definition.run, { self }) as string)
+        : null;
+
+      const persistentManifests: any[] = [];
+      let ephemeralTemplate: any = null;
+
+      for (const template of definition.resources ?? []) {
+        const expandedName = ctx.moduleContext.expandWith(template.metadata?.name ?? "", {
+          self,
+        }) as string;
+        const isTarget = expandedName === invokeTarget || expandedName === runTarget;
+        if (isTarget) {
+          ephemeralTemplate = template;
+        } else {
+          persistentManifests.push(ctx.moduleContext.expandWith(template, { self }));
+        }
+      }
+
+      const childContext = ctx.spawnChildContext();
+
+      // Registers an ephemeral manifest on ctx.moduleContext so it shares the same
+      // resource scope (and can access connections, etc. via getInstance).
+      // Tears down and removes the resource after fn() completes.
+      const withEphemeral = async (expandedManifest: any, fn: (name: string) => Promise<any>) => {
+        const uniqueName = `${expandedManifest.metadata?.name ?? "eph"}__${Math.random().toString(16).slice(2, 8)}`;
+        const manifest = {
+          ...expandedManifest,
+          metadata: {
+            ...expandedManifest.metadata,
+            name: uniqueName,
+            module: resource.metadata.module,
+          },
+        };
+        ctx.moduleContext.registerManifest(manifest);
+        await ctx.moduleContext.initializeResources();
+        const entry = ctx.moduleContext.resourceInstances.get(uniqueName);
+        try {
+          return await fn(uniqueName);
+        } finally {
+          if (entry?.instance?.teardown) await entry.instance.teardown();
+          ctx.moduleContext.resourceInstances.delete(uniqueName);
+        }
+      };
+
+      return {
+        init: async () => {
+          for (const m of persistentManifests) childContext.registerManifest(m);
+          await childContext.initializeResources();
+        },
+
+        ...(invokeTarget && {
+          invoke: async (inputs: any) => {
+            if (!ephemeralTemplate) {
+              throw new Error(
+                `Template '${resource.metadata.name}': no ephemeral resource for invoke target '${invokeTarget}'`,
+              );
+            }
+            const extraContext = { self, inputs };
+            const expanded = ctx.moduleContext.expandWith(
+              ctx.moduleContext.expandWith(ephemeralTemplate, extraContext),
+              extraContext,
+            ) as any;
+            return withEphemeral(expanded, async (name) => {
+              const entry = ctx.moduleContext.resourceInstances.get(name);
+              if (!entry?.instance?.invoke) {
+                throw new Error(`Ephemeral resource '${name}' is not invocable`);
+              }
+              // New object form: expand objectInvoke.inputs with invoke context and pass as arg.
+              // Old string form: the manifest inputs were computed during template expansion;
+              // pass expanded.inputs so Sql.Exec/Query controllers receive { sql, bindings }.
+              const invokeInputs = objectInvoke?.inputs != null
+                ? ctx.moduleContext.expandWith(
+                    ctx.moduleContext.expandWith(objectInvoke.inputs, extraContext),
+                    extraContext,
+                  )
+                : expanded.inputs ?? inputs;
+              return entry.instance.invoke(invokeInputs);
+            });
+          },
+        }),
+
+        ...(runTarget && {
+          run: async () => {
+            if (!ephemeralTemplate) {
+              throw new Error(
+                `Template '${resource.metadata.name}': no ephemeral resource for run target '${runTarget}'`,
+              );
+            }
+            const extraContext = { self };
+            const expanded = ctx.moduleContext.expandWith(
+              ctx.moduleContext.expandWith(ephemeralTemplate, extraContext),
+              extraContext,
+            );
+            return withEphemeral(expanded, async (name) => {
+              const entry = ctx.moduleContext.resourceInstances.get(name);
+              if (!entry?.instance?.run) {
+                throw new Error(`Ephemeral resource '${name}' is not runnable`);
+              }
+              return entry.instance.run();
+            });
+          },
+        }),
+
+        teardown: async () => {
+          await childContext.teardownResources();
+        },
+      };
+    },
+  };
+}

package/src/event-stream.ts

@@ -0,0 +1,121 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+/**
+ * Streaming event log for debugging and testing
+ * Records all events in JSONL format (one JSON object per line)
+ * Useful for observing runtime execution, testing, and debugging
+ */
+export class EventStream {
+  private filePath: string;
+  private isEnabled: boolean = false;
+
+  constructor(filePath?: string) {
+    this.filePath = filePath || '';
+    this.isEnabled = !!filePath;
+  }
+
+  /**
+   * Enable event streaming to a file
+   */
+  async enable(filePath: string): Promise<void> {
+    this.filePath = filePath;
+    this.isEnabled = true;
+
+    // Ensure directory exists
+    const dir = path.dirname(filePath);
+    if (dir !== '.' && dir !== '') {
+      await fs.mkdir(dir, { recursive: true });
+    }
+
+    // Initialize file (truncate if exists)
+    await fs.writeFile(filePath, '', 'utf-8');
+  }
+
+  /**
+   * Log an event to the stream
+   */
+  async log(
+    event: string,
+    payload?: any,
+    metadata?: {
+      namespace?: string;
+      resource?: string;
+      kind?: string;
+      name?: string;
+    },
+  ): Promise<void> {
+    if (!this.isEnabled) {
+      return;
+    }
+
+    const logEntry = {
+      timestamp: new Date().toISOString(),
+      event,
+      payload,
+      ...metadata,
+    };
+
+    try {
+      const line = JSON.stringify(logEntry) + '\n';
+      await fs.appendFile(this.filePath, line, 'utf-8');
+    } catch (error) {
+      console.error('Failed to write event to stream:', error);
+    }
+  }
+
+  /**
+   * Read all events from the stream as an array
+   * Useful for testing
+   */
+  async readAll(): Promise<Array<Record<string, any>>> {
+    if (!this.isEnabled || !this.filePath) {
+      return [];
+    }
+
+    try {
+      const content = await fs.readFile(this.filePath, 'utf-8');
+      if (!content.trim()) {
+        return [];
+      }
+      return content
+        .trim()
+        .split('\n')
+        .map((line) => JSON.parse(line));
+    } catch (error) {
+      console.error('Failed to read event stream:', error);
+      return [];
+    }
+  }
+
+  /**
+   * Filter events by type
+   */
+  async getEventsByType(
+    eventType: string,
+  ): Promise<Array<Record<string, any>>> {
+    const all = await this.readAll();
+    return all.filter((e) => e.event === eventType);
+  }
+
+  /**
+   * Get the file path for the event stream
+   */
+  getFilePath(): string {
+    return this.filePath;
+  }
+
+  /**
+   * Check if event streaming is enabled
+   */
+  isEnabledStream(): boolean {
+    return this.isEnabled;
+  }
+
+  /**
+   * Disable event streaming
+   */
+  disable(): void {
+    this.isEnabled = false;
+  }
+}

package/src/events.ts

@@ -0,0 +1,99 @@
+import { RuntimeEvent } from "@telorun/sdk";
+
+type EventHandler = (payload?: any) => void | Promise<void>;
+
+export class EventBus {
+  private handlers: Map<string, Set<EventHandler>> = new Map();
+
+  private validateEventName(event: string): void {
+    if (
+      event === "" ||
+      !/^(\*|[A-Za-z_][A-Za-z0-9_]*)(\.(\*|[A-Za-z_][A-Za-z0-9_]*))*$/.test(event)
+    ) {
+      throw new Error(`Invalid event name "${event}". Expected format "Text.Text" with no spaces.`);
+    }
+  }
+
+  private matchesPattern(pattern: string, event: string): boolean {
+    if (pattern === "*") {
+      return true;
+    }
+    if (pattern === event) {
+      return true;
+    }
+    if (!pattern.includes("*")) {
+      return false;
+    }
+    const patternParts = pattern.split(".");
+    const eventParts = event.split(".");
+    if (patternParts.length !== eventParts.length) {
+      return false;
+    }
+    for (let i = 0; i < patternParts.length; i += 1) {
+      const part = patternParts[i];
+      if (part === "*") {
+        continue;
+      }
+      if (part !== eventParts[i]) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  on(event: string, handler: EventHandler): void {
+    this.validateEventName(event);
+    const set = this.handlers.get(event) || new Set();
+    set.add(handler);
+    this.handlers.set(event, set);
+  }
+
+  once(event: string, handler: EventHandler): void {
+    this.validateEventName(event);
+    const wrapper: EventHandler = async (payload?: any) => {
+      this.off(event, wrapper);
+      await handler(payload);
+    };
+    this.on(event, wrapper);
+  }
+
+  off(event: string, handler: EventHandler): void {
+    this.validateEventName(event);
+    const set = this.handlers.get(event);
+    if (!set) {
+      return;
+    }
+    set.delete(handler);
+    if (set.size === 0) {
+      this.handlers.delete(event);
+    }
+  }
+
+  async emit(event: string, payload?: any, metadata?: any): Promise<void> {
+    const handlers: EventHandler[] = [];
+    for (const [pattern, set] of this.handlers.entries()) {
+      if (!this.matchesPattern(pattern, event)) {
+        continue;
+      }
+      for (const handler of set) {
+        handlers.push(handler);
+      }
+    }
+    if (handlers.length === 0) {
+      return;
+    }
+    const evt: RuntimeEvent = { name: event, payload, metadata };
+    for (const handler of handlers) {
+      await handler(evt);
+    }
+  }
+
+  hasHandlers(event: string): boolean {
+    for (const [pattern, set] of this.handlers.entries()) {
+      if (set.size > 0 && this.matchesPattern(pattern, event)) {
+        return true;
+      }
+    }
+    return false;
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export { ControllerRegistry } from "./controller-registry.js";
+export { EventStream } from "./event-stream.js";
+export { Kernel } from "./kernel.js";
+export { ManifestRegistry as Registry } from "./registry.js";
+export { ResourceURI } from "./resource-uri.js";
+export type { RuntimeDiagnostic } from "@telorun/sdk";
+