@telorun/kernel 0.2.4 → 0.2.6

package/src/loader.ts

@@ -0,0 +1,134 @@
+import { Loader as BaseLoader } from "@telorun/analyzer";
+import { ResourceManifest, RuntimeResource } from "@telorun/sdk";
+import * as path from "path";
+import { LocalFileAdapter } from "./manifest-adapters/local-file-adapter.js";
+import { formatAjvErrors, validateRuntimeResource } from "./manifest-schemas.js";
+
+export class Loader extends BaseLoader {
+  private static projectRoot: string | null = null;
+  private readonly localAdapter: LocalFileAdapter;
+
+  constructor() {
+    super();
+    this.localAdapter = new LocalFileAdapter();
+    this.register(this.localAdapter);
+  }
+
+  private static ensureProjectRoot(baseDir: string): void {
+    if (!Loader.projectRoot) {
+      Loader.projectRoot = path.resolve(baseDir);
+    }
+  }
+
+  resolvePath(base: string, relative: string): string {
+    return this.localAdapter.resolveRelative(base, relative);
+  }
+
+  /**
+   * Resolve a path-or-URL to its canonical file source URL.
+   * If the path refers to a directory, returns the URL of module.yaml inside it.
+   */
+  async resolveEntryPoint(pathOrUrl: string): Promise<string> {
+    const { source } = await this.localAdapter.read(pathOrUrl);
+    return source;
+  }
+
+  async loadDirectory(pathOrUrl: string): Promise<ResourceManifest[]> {
+    const sources = await this.localAdapter.readAll(pathOrUrl);
+    const firstPath = sources[0] ? new URL(sources[0]).pathname : process.cwd();
+    Loader.ensureProjectRoot(path.dirname(firstPath));
+    const resources: RuntimeResource[] = [];
+    for (const source of sources) {
+      const manifests = await this.loadModule(source);
+      for (const m of manifests) {
+        if (!m.metadata?.name) continue;
+        const resource = m as RuntimeResource;
+        if (!validateRuntimeResource(resource)) {
+          throw new Error(
+            `Resource validation failed for ${m.kind}.${m.metadata.name}: ${formatAjvErrors(validateRuntimeResource.errors)}`,
+          );
+        }
+        const filePath = new URL(m.metadata.source as string).pathname;
+        const uriBase = `file://localhost${filePath.replace(/\\/g, "/")}`;
+        resource.metadata.uri = `${uriBase}#${m.kind}.${m.metadata.name as string}`;
+        resource.metadata.generationDepth = 0;
+        resources.push(resource);
+      }
+    }
+    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();
+    if (!Loader.projectRoot) {
+      Loader.ensureProjectRoot(path.dirname(new URL(url).pathname));
+    }
+    return this.loadModule(url, { compile: true });
+  }
+
+  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++) {
+      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++) indegree.set(i, 0);
+
+    for (let i = 0; i < resources.length; i++) {
+      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++) {
+      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/local-file-adapter.ts

@@ -0,0 +1,62 @@
+import type { ManifestAdapter } from "@telorun/analyzer";
+import * as fs from "fs/promises";
+import * as path from "path";
+
+export class LocalFileAdapter implements ManifestAdapter {
+  supports(pathOrUrl: string): boolean {
+    return (
+      pathOrUrl.startsWith("file://") ||
+      pathOrUrl.startsWith("/") ||
+      pathOrUrl.startsWith("./") ||
+      pathOrUrl.startsWith("../") ||
+      (!pathOrUrl.includes("://") && !pathOrUrl.includes("@"))
+    );
+  }
+
+  async read(pathOrUrl: string): Promise<{ text: string; source: string }> {
+    const normalizedPath = pathOrUrl.startsWith("file://")
+      ? new URL(pathOrUrl).pathname
+      : pathOrUrl;
+    const resolvedPath = path.resolve(normalizedPath);
+    const stat = await fs.stat(resolvedPath);
+    const filePath = stat.isDirectory() ? path.join(resolvedPath, "module.yaml") : resolvedPath;
+    const text = await fs.readFile(filePath, "utf-8");
+    return { text, source: `file://${filePath}` };
+  }
+
+  async readAll(pathOrUrl: string): Promise<string[]> {
+    const normalizedPath = pathOrUrl.startsWith("file://")
+      ? new URL(pathOrUrl).pathname
+      : pathOrUrl;
+    const resolvedPath = path.resolve(normalizedPath);
+    const stat = await fs.stat(resolvedPath);
+    if (stat.isDirectory()) {
+      return this.collectYamlSources(resolvedPath);
+    }
+    return [`file://${resolvedPath}`];
+  }
+
+  resolveRelative(base: string, relative: string): string {
+    const basePath = base.startsWith("file://") ? new URL(base).pathname : base;
+    const baseDir = basePath.endsWith("/") ? basePath : path.dirname(basePath);
+    return `file://${path.resolve(baseDir, relative)}`;
+  }
+
+  private async collectYamlSources(dirPath: string): Promise<string[]> {
+    const sources: string[] = [];
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dirPath, entry.name);
+      if (entry.isDirectory()) {
+        sources.push(...(await this.collectYamlSources(fullPath)));
+      } else if (entry.isFile() && this.isYamlFile(entry.name)) {
+        sources.push(`file://${fullPath}`);
+      }
+    }
+    return sources;
+  }
+
+  private isYamlFile(filename: string): boolean {
+    return filename.endsWith(".yaml") || filename.endsWith(".yml");
+  }
+}

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

@@ -0,0 +1,35 @@
+export interface ManifestSourceData {
+  /** Raw YAML text */
+  text: string;
+  /** 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-schemas.ts

@@ -0,0 +1,85 @@
+import { Type } from "@sinclair/typebox";
+import AjvModule 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 },
+);
+
+const metadataSchema = {
+  type: "object",
+  required: ["name"],
+  properties: {
+    name: { type: "string" },
+    module: { type: "string" },
+  },
+  additionalProperties: true,
+};
+
+const baseDefinition = {
+  type: "object",
+  required: ["kind", "metadata"],
+  properties: {
+    kind: { const: "Kernel.Definition" },
+    metadata: metadataSchema,
+    capability: { type: "string" },
+    schema: { type: "object", additionalProperties: true },
+    controllers: { type: "array", items: { type: "string" } },
+  },
+  unevaluatedProperties: false,
+};
+
+const KNOWN_CAPABILITIES = [
+  "Kernel.Service",
+  "Kernel.Runnable",
+  "Kernel.Invocable",
+  "Kernel.Provider",
+  "Kernel.Type",
+  "Kernel.Mount",
+] as const;
+
+export const ResourceDefinitionSchema = {
+  ...baseDefinition,
+  oneOf: [
+    { required: ["capability"], properties: { capability: { const: "Kernel.Service" } } },
+    { required: ["capability"], properties: { capability: { const: "Kernel.Runnable" } } },
+    { required: ["capability"], properties: { capability: { const: "Kernel.Invocable" } } },
+    { required: ["capability"], properties: { capability: { const: "Kernel.Provider" } } },
+    { required: ["capability"], properties: { capability: { const: "Kernel.Type" } } },
+    {
+      required: ["capability"],
+      properties: {
+        capability: { const: "Kernel.Mount" },
+      },
+    },
+    // Unknown/absent capability: open schema for third-party extensibility
+    {
+      not: {
+        required: ["capability"],
+        properties: { capability: { enum: KNOWN_CAPABILITIES } },
+      },
+      unevaluatedProperties: 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: any[] | null | undefined): string {
+  if (!errors || errors.length === 0) return "Unknown schema error";
+  return errors
+    .map((err) => {
+      const p = err.instancePath || "/";
+      return `${p} ${err.message ?? "is invalid"}`;
+    })
+    .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();
+  }
+}