@telorun/kernel 0.2.4 → 0.2.5

package/src/loader.ts

@@ -0,0 +1,245 @@
+import { ResourceManifest, RuntimeResource } from "@telorun/sdk";
+import { compile } from "@telorun/yaml-cel-templating";
+import * as path from "path";
+import { HttpAdapter } from "./manifest-adapters/http-adapter.js";
+import { LocalFileAdapter } from "./manifest-adapters/local-file-adapter.js";
+import type { ManifestAdapter, ManifestSourceData } from "./manifest-adapters/manifest-adapter.js";
+import { RegistryAdapter } from "./manifest-adapters/registry-adapter.js";
+import { formatAjvErrors, validateRuntimeResource } from "./manifest-schemas.js";
+
+/**
+ * Loader: Ingests resolved YAML manifests from disk or remote URLs into memory
+ */
+export class Loader {
+  private static projectRoot: string | null = null;
+
+  private readonly adapters: ManifestAdapter[] = [
+    new HttpAdapter(),
+    new RegistryAdapter(),
+    new LocalFileAdapter(),
+  ];
+
+  private getAdapter(pathOrUrl: string): ManifestAdapter {
+    const adapter = this.adapters.find((a) => a.supports(pathOrUrl));
+    if (!adapter) {
+      throw new Error(`No manifest adapter found for: ${pathOrUrl}`);
+    }
+    return adapter;
+  }
+
+  private static ensureProjectRoot(baseDir: string): void {
+    if (!Loader.projectRoot) {
+      Loader.projectRoot = path.resolve(baseDir);
+    }
+  }
+
+  resolvePath(base: string, relative: string): string {
+    return this.getAdapter(base).resolveRelative(base, relative);
+  }
+
+  async loadDirectory(pathOrUrl: string): Promise<ResourceManifest[]> {
+    const files = await this.getAdapter(pathOrUrl).readAll(pathOrUrl);
+    Loader.ensureProjectRoot(files[0]?.baseDir ?? process.cwd());
+    const resources: RuntimeResource[] = [];
+    for (const file of files) {
+      await this.processFile(file, resources, { env: process.env });
+    }
+    return this.orderResourcesByKindDependencies(resources);
+  }
+
+  async loadManifest(
+    pathOrUrl: string,
+    baseUrl: string,
+    compileContext: Record<string, unknown> = {},
+  ): Promise<ResourceManifest[]> {
+    if (!baseUrl) {
+      throw new Error("Base URL is required to load target manifest");
+    }
+    const url = new URL(pathOrUrl, baseUrl).toString();
+    const file = await this.getAdapter(url).read(url);
+    if (!Loader.projectRoot) {
+      Loader.ensureProjectRoot(file.baseDir);
+    }
+
+    const resolved: ResourceManifest[] = [];
+    for (const rawDoc of file.documents) {
+      let compiled: any;
+      try {
+        compiled = compile(rawDoc, { context: compileContext });
+      } catch (error) {
+        throw new Error(
+          `Failed to compile manifest in ${file.source}: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+      const compiledDocs = Array.isArray(compiled) ? compiled : [compiled];
+      for (const manifest of compiledDocs) {
+        if (manifest === null) {
+          // Ignore empty documents
+          continue;
+        }
+        const resource: ResourceManifest = {
+          ...manifest,
+          metadata: {
+            ...manifest.metadata,
+            source: file.source,
+          },
+        };
+        resolved.push(resource);
+      }
+    }
+
+    // Auto-assign metadata.module from the file's Kernel.Module declaration to
+    // any resource that doesn't explicitly declare one. This matches the implicit
+    // convention that resources in the same file belong to the declared module.
+    const moduleName = resolved.find((m) => m.kind === "Kernel.Module")?.metadata?.name;
+    if (moduleName) {
+      for (const manifest of resolved) {
+        if (manifest.kind !== "Kernel.Module" && !manifest.metadata?.module) {
+          manifest.metadata = { ...manifest.metadata, module: moduleName };
+        }
+      }
+    }
+
+    return resolved;
+  }
+
+  private async processFile(
+    file: ManifestSourceData,
+    resources: RuntimeResource[],
+    compileContext: Record<string, unknown> = {},
+  ): Promise<void> {
+    const documents = file.documents;
+
+    for (const rawDoc of documents) {
+      let compiled: any;
+      try {
+        compiled = compile(rawDoc, { context: compileContext });
+      } catch (error) {
+        throw new Error(
+          `Failed to compile manifest in ${file.source}: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+      const compiledDocs = Array.isArray(compiled) ? compiled : [compiled];
+      for (const doc of compiledDocs) {
+        const resource = this.normalizeResource(doc);
+        if (!resource) {
+          continue;
+        }
+        if (!validateRuntimeResource(resource)) {
+          const kind = (resource as any).kind;
+          const name = (resource as any).metadata?.name;
+          throw new Error(
+            `Resource validation failed for ${kind}.${name}: ${formatAjvErrors(validateRuntimeResource.errors)}`,
+          );
+        }
+
+        const { kind, name } = resource.metadata;
+        resource.metadata.source = file.source;
+        resource.metadata.uri = `${file.uriBase}#${kind}.${name}`;
+        resource.metadata.generationDepth = 0;
+
+        resources.push(resource);
+      }
+    }
+  }
+
+  private normalizeResource(doc: any): RuntimeResource | null {
+    if (!doc || typeof doc !== "object" || typeof doc.kind !== "string") {
+      return null;
+    }
+
+    // Already in correct format
+    if (doc.metadata && typeof doc.metadata === "object" && typeof doc.metadata.name === "string") {
+      return doc as RuntimeResource;
+    }
+
+    return null;
+  }
+
+  // Validation handled by TypeBox + Ajv schemas.
+
+  private orderResourcesByKindDependencies(resources: RuntimeResource[]): RuntimeResource[] {
+    if (resources.length <= 1) {
+      return resources;
+    }
+
+    const indicesByName = new Map<string, number[]>();
+    for (let i = 0; i < resources.length; i += 1) {
+      const name = resources[i]?.metadata?.name;
+      if (!name) {
+        continue;
+      }
+      const list = indicesByName.get(name);
+      if (list) {
+        list.push(i);
+      } else {
+        indicesByName.set(name, [i]);
+      }
+    }
+
+    const edges = new Map<number, Set<number>>();
+    const indegree = new Map<number, number>();
+    for (let i = 0; i < resources.length; i += 1) {
+      indegree.set(i, 0);
+    }
+
+    for (let i = 0; i < resources.length; i += 1) {
+      const kind = resources[i]?.kind;
+      if (!kind) {
+        continue;
+      }
+      const definers = indicesByName.get(kind);
+      if (!definers) {
+        continue;
+      }
+      for (const definerIndex of definers) {
+        if (definerIndex === i) {
+          continue;
+        }
+        let set = edges.get(definerIndex);
+        if (!set) {
+          set = new Set();
+          edges.set(definerIndex, set);
+        }
+        if (!set.has(i)) {
+          set.add(i);
+          indegree.set(i, (indegree.get(i) || 0) + 1);
+        }
+      }
+    }
+
+    const ready: number[] = [];
+    for (let i = 0; i < resources.length; i += 1) {
+      if ((indegree.get(i) || 0) === 0) {
+        ready.push(i);
+      }
+    }
+    ready.sort((a, b) => a - b);
+
+    const ordered: RuntimeResource[] = [];
+    while (ready.length > 0) {
+      const index = ready.shift() as number;
+      ordered.push(resources[index]);
+      const next = edges.get(index);
+      if (!next) {
+        continue;
+      }
+      for (const dependent of next) {
+        const count = (indegree.get(dependent) || 0) - 1;
+        indegree.set(dependent, count);
+        if (count === 0) {
+          ready.push(dependent);
+        }
+      }
+      if (ready.length > 1) {
+        ready.sort((a, b) => a - b);
+      }
+    }
+
+    if (ordered.length !== resources.length) {
+      throw new Error("Resource dependency cycle detected");
+    }
+
+    return ordered;
+  }
+}

package/src/manifest-adapters/http-adapter.ts

@@ -0,0 +1,35 @@
+import * as yaml from "js-yaml";
+import type { ManifestAdapter, ManifestSourceData } from "./manifest-adapter.js";
+
+export class HttpAdapter implements ManifestAdapter {
+  supports(pathOrUrl: string): boolean {
+    return pathOrUrl.startsWith("http://") || pathOrUrl.startsWith("https://");
+  }
+
+  async read(url: string): Promise<ManifestSourceData> {
+    return (await this.readAll(url))[0];
+  }
+
+  async readAll(url: string): Promise<ManifestSourceData[]> {
+    const fetchUrl = url.includes(".yaml") ? url : url + "/module.yaml";
+    const response = await fetch(fetchUrl);
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch manifest from ${fetchUrl}: ${response.status} ${response.statusText}`,
+      );
+    }
+    return [
+      {
+        documents: yaml.loadAll(await response.text()),
+        source: fetchUrl,
+        baseDir: process.cwd(),
+        uriBase: url,
+      },
+    ];
+  }
+
+  resolveRelative(base: string, relative: string): string {
+    const baseWithSlash = base.endsWith("/") ? base : `${base}/`;
+    return new URL(relative, baseWithSlash).href;
+  }
+}

package/src/manifest-adapters/local-file-adapter.ts

@@ -0,0 +1,69 @@
+import * as fs from "fs/promises";
+import * as yaml from "js-yaml";
+import * as path from "path";
+import type { ManifestAdapter, ManifestSourceData } from "./manifest-adapter.js";
+
+export class LocalFileAdapter implements ManifestAdapter {
+  supports(pathOrUrl: string): boolean {
+    return (
+      pathOrUrl.startsWith("file://") ||
+      pathOrUrl.startsWith("/") ||
+      pathOrUrl.startsWith("./") ||
+      pathOrUrl.startsWith("../")
+    );
+  }
+
+  async read(pathOrUrl: string): Promise<ManifestSourceData> {
+    const normalizedPath = pathOrUrl.startsWith("file://")
+      ? pathOrUrl.replace("file://", "")
+      : pathOrUrl;
+    const stat = await fs.stat(normalizedPath);
+    const filePath = stat.isDirectory() ? path.join(normalizedPath, "module.yaml") : normalizedPath;
+    return this.readFile(filePath);
+  }
+
+  async readAll(pathOrUrl: string): Promise<ManifestSourceData[]> {
+    const normalizedPath = pathOrUrl.startsWith("file://")
+      ? pathOrUrl.replace("file://", "")
+      : pathOrUrl;
+    const stat = await fs.stat(normalizedPath);
+    if (stat.isDirectory()) {
+      const results: ManifestSourceData[] = [];
+      await this.collectYamlFiles(normalizedPath, results);
+      return results;
+    }
+    return [await this.readFile(normalizedPath)];
+  }
+
+  resolveRelative(base: string, relative: string): string {
+    const basePath = base.startsWith("file://") ? base.slice("file://".length) : base;
+    return `file://${path.resolve(basePath, relative)}`;
+  }
+
+  private async readFile(filePath: string): Promise<ManifestSourceData> {
+    const content = await fs.readFile(filePath, "utf-8");
+
+    return {
+      documents: yaml.loadAll(content),
+      source: `file://${filePath}`,
+      baseDir: path.dirname(filePath),
+      uriBase: `file://localhost${filePath.replace(/\\/g, "/")}`,
+    };
+  }
+
+  private async collectYamlFiles(dirPath: string, results: ManifestSourceData[]): Promise<void> {
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dirPath, entry.name);
+      if (entry.isDirectory()) {
+        await this.collectYamlFiles(fullPath, results);
+      } else if (entry.isFile() && this.isYamlFile(entry.name)) {
+        results.push(await this.readFile(fullPath));
+      }
+    }
+  }
+
+  private isYamlFile(filename: string): boolean {
+    return filename.endsWith(".yaml") || filename.endsWith(".yml");
+  }
+}

package/src/manifest-adapters/manifest-adapter.ts

@@ -0,0 +1,33 @@
+export interface ManifestSourceData {
+  /** Parsed YAML documents (result of yaml.loadAll) */
+  documents: any[];
+  /** Stored as metadata.source (file path or URL) */
+  source: string;
+  /** Base directory for resolving relative controller entrypoints */
+  baseDir: string;
+  /** URI prefix — full resource URI is `${uriBase}#${kind}.${name}` */
+  uriBase: string;
+}
+
+export interface ManifestAdapter {
+  /** Returns true if this adapter can handle the given path/URL */
+  supports(pathOrUrl: string): boolean;
+  /**
+   * Read a single manifest entry point.
+   * - File path or URL → read that file/URL.
+   * - Directory path → find and read `module.yaml` within it.
+   */
+  read(pathOrUrl: string): Promise<ManifestSourceData>;
+  /**
+   * Read all manifest files reachable from the given path/URL.
+   * Used for module imports.
+   * - Directory path → recursive walk, one entry per .yaml/.yml file found.
+   * - File path or URL → single-item array.
+   */
+  readAll(pathOrUrl: string): Promise<ManifestSourceData[]>;
+  /**
+   * Resolve a potentially relative path/URL against a base directory/URL.
+   * For absolute inputs the base is ignored.
+   */
+  resolveRelative(base: string, relative: string): string;
+}

package/src/manifest-adapters/registry-adapter.ts

@@ -0,0 +1,56 @@
+import * as yaml from "js-yaml";
+import type { ManifestAdapter, ManifestSourceData } from "./manifest-adapter.js";
+
+const REGISTRY_BASE = "https://registry.telo.run";
+
+export class RegistryAdapter implements ManifestAdapter {
+  supports(pathOrUrl: string): boolean {
+    // Matches "owner/module@version" — has @ and /, but not an http/https URL or local path
+    return (
+      !pathOrUrl.startsWith("http://") &&
+      !pathOrUrl.startsWith("https://") &&
+      !pathOrUrl.startsWith("/") &&
+      !pathOrUrl.startsWith(".") &&
+      pathOrUrl.includes("@") &&
+      pathOrUrl.includes("/")
+    );
+  }
+
+  async read(moduleRef: string): Promise<ManifestSourceData> {
+    return (await this.readAll(moduleRef))[0];
+  }
+
+  async readAll(moduleRef: string): Promise<ManifestSourceData[]> {
+    const url = this.toRegistryUrl(moduleRef);
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch manifest ${moduleRef}: ${response.status} ${response.statusText}`,
+      );
+    }
+    return [
+      {
+        documents: yaml.loadAll(await response.text()),
+        source: url,
+        baseDir: process.cwd(),
+        uriBase: url.replace("/module.yaml", ""),
+      },
+    ];
+  }
+
+  resolveRelative(base: string, relative: string): string {
+    const baseUrl = this.supports(base)
+      ? this.toRegistryUrl(base).replace("/module.yaml", "")
+      : base;
+    const baseWithSlash = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+    return new URL(relative, baseWithSlash).href;
+  }
+
+  private toRegistryUrl(moduleRef: string): string {
+    const atIdx = moduleRef.lastIndexOf("@");
+    const path = moduleRef.slice(0, atIdx); // "example/module"
+    const version = moduleRef.slice(atIdx + 1); // "1.2.3" or "v1.2.3"
+    const versionSegment = version.startsWith("v") ? version.substring(1) : version;
+    return `${REGISTRY_BASE}/${path}/${versionSegment}/module.yaml`;
+  }
+}

package/src/manifest-schemas.ts

@@ -0,0 +1,49 @@
+import { Type } from "@sinclair/typebox";
+import AjvModule, { ErrorObject } from "ajv";
+import addFormats from "ajv-formats";
+const Ajv = AjvModule.default ?? AjvModule;
+
+export const RuntimeResourceSchema = Type.Object(
+  {
+    kind: Type.String(),
+    metadata: Type.Object({ name: Type.String() }, { additionalProperties: true }),
+  },
+  { additionalProperties: true },
+);
+
+export const ResourceDefinitionSchema = Type.Object(
+  {
+    kind: Type.Literal("Kernel.Definition"),
+    metadata: Type.Object(
+      {
+        name: Type.String(),
+        module: Type.Optional(Type.String()),
+      },
+      { additionalProperties: true },
+    ),
+    schema: Type.Object({}, { additionalProperties: true }),
+    capabilities: Type.Array(Type.String(), { minItems: 1 }),
+    events: Type.Optional(Type.Array(Type.String())),
+    controllers: Type.Optional(Type.Array(Type.String())),
+  },
+  { additionalProperties: true },
+);
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+addFormats.default(ajv);
+
+export const validateRuntimeResource = ajv.compile(RuntimeResourceSchema);
+export const validateResourceDefinition = ajv.compile(ResourceDefinitionSchema);
+
+export function formatAjvErrors(errors: ErrorObject[] | null | undefined): string {
+  if (!errors || errors.length === 0) {
+    return "Unknown schema error";
+  }
+  return errors
+    .map((err) => {
+      const path = err.instancePath && err.instancePath.length > 0 ? err.instancePath : "/";
+      const message = err.message || "is invalid";
+      return `${path} ${message}`;
+    })
+    .join("; ");
+}

package/src/registry.ts

@@ -0,0 +1,137 @@
+import { ResourceManifest, RuntimeError, RuntimeResource } from "@telorun/sdk";
+import { ResourceURI } from "./resource-uri.js";
+
+/**
+ * Registry: Indexes resources by composite key of Kind and Name
+ * Maintains URI-based lookup for tracking resource origins and lineage
+ */
+export class ManifestRegistry {
+  private resources: Map<string, Map<string, ResourceManifest>> = new Map();
+  private kindInheritance: Map<string, string> = new Map(); // derivedKind -> parentKind
+  private uriIndex: Map<string, ResourceManifest> = new Map(); // URI -> Resource
+  private sourceIndex: Map<string, ResourceManifest[]> = new Map(); // source path -> Resources
+  private depthIndex: Map<number, ResourceManifest[]> = new Map(); // generation depth -> Resources
+
+  register(resource: RuntimeResource): void {
+    const { kind, metadata } = resource;
+    const { name } = metadata;
+    console.log("Registering resource:", kind, name);
+    if (!this.resources.has(kind)) {
+      this.resources.set(kind, new Map());
+    }
+
+    const kindMap = this.resources.get(kind)!;
+
+    if (kindMap.has(name)) {
+      throw new RuntimeError("ERR_DUPLICATE_RESOURCE", `Duplicate resource: ${kind}.${name}`);
+    }
+
+    kindMap.set(name, resource);
+
+    // Index by URI if available
+    if (metadata.uri) {
+      this.uriIndex.set(metadata.uri, resource);
+
+      // Index by source file/path
+      try {
+        const uri = ResourceURI.parse(metadata.uri);
+        if (uri.isFileSource()) {
+          const sourcePath = uri.path;
+          if (!this.sourceIndex.has(sourcePath)) {
+            this.sourceIndex.set(sourcePath, []);
+          }
+          this.sourceIndex.get(sourcePath)!.push(resource);
+        }
+      } catch {
+        // URI parsing failed, skip indexing
+      }
+    }
+
+    // Index by generation depth
+    const depth = metadata.generationDepth ?? 0;
+    if (!this.depthIndex.has(depth)) {
+      this.depthIndex.set(depth, []);
+    }
+    this.depthIndex.get(depth)!.push(resource);
+
+    // Check if this is a Kernel.KindDefinition that creates a new kind
+    // if (kind === 'Kernel.KindDefinition') {
+    //   const newKind = name;
+    //   const parentKind = resource?.extends;
+    //   if (parentKind) {
+    //     this.kindInheritance.set(newKind, parentKind);
+    //   }
+    // }
+  }
+
+  getParentKind(kind: string): string | undefined {
+    return this.kindInheritance.get(kind);
+  }
+
+  resolveKindChain(kind: string): string[] {
+    const chain: string[] = [kind];
+    let current = kind;
+    while (this.kindInheritance.has(current)) {
+      current = this.kindInheritance.get(current)!;
+      chain.push(current);
+    }
+    return chain;
+  }
+
+  get(kind: string, name: string): ResourceManifest | undefined {
+    return this.resources.get(kind)?.get(name);
+  }
+
+  getByKind(kind: string): ResourceManifest[] {
+    const kindMap = this.resources.get(kind);
+    return kindMap ? Array.from(kindMap.values()) : [];
+  }
+
+  /**
+   * Get resource by its URI
+   */
+  getByUri(uri: string): ResourceManifest | undefined {
+    return this.uriIndex.get(uri);
+  }
+
+  /**
+   * Get all resources from a specific source file
+   */
+  getBySourceFile(sourceFilePath: string): ResourceManifest[] {
+    return this.sourceIndex.get(sourceFilePath) ?? [];
+  }
+
+  /**
+   * Get all resources at a specific generation depth
+   * 0 = directly from files, 1+ = template-generated
+   */
+  getByGenerationDepth(depth: number): ResourceManifest[] {
+    return this.depthIndex.get(depth) ?? [];
+  }
+
+  /**
+   * Get all template-generated resources (depth > 0)
+   */
+  getTemplateGenerated(): ResourceManifest[] {
+    const results: ResourceManifest[] = [];
+    for (const [depth, resources] of this.depthIndex) {
+      if (depth > 0) {
+        results.push(...resources);
+      }
+    }
+    return results;
+  }
+
+  /**
+   * Get all directly-loaded resources (depth = 0)
+   */
+  getDirectlyLoaded(): ResourceManifest[] {
+    return this.depthIndex.get(0) ?? [];
+  }
+
+  getAll(): ResourceManifest[] {
+    return Array.from(this.resources.values())
+      .map((kindMap) => Array.from(kindMap.values()))
+      .flat();
+  }
+}