@telorun/kernel 0.2.4 → 0.2.6

package/src/boot-context-registry.ts

@@ -0,0 +1,169 @@
+import { RuntimeError } from "@telorun/sdk";
+
+/** Stored entry for a single context provider */
+interface ProviderEntry {
+  kind: string;
+  name: string;
+  module: string;
+  /**
+   * If defined, only resources whose `"${kind}/${name}"` is in this list may
+   * access this provider's context. `undefined` means unrestricted.
+   * An empty array means no consumer is allowed.
+   */
+  grants: string[] | undefined;
+  context: Record<string, unknown>;
+}
+
+/**
+ * Accumulates ContextProvider contributions during the AOT boot initialization
+ * multi-pass loop and enforces RBAC visibility rules.
+ *
+ * Lifecycle:
+ *   1. A provider resource is created + init()'d → kernel calls register().
+ *   2. Before a consumer resource is created → kernel calls buildContext() to
+ *      obtain a per-consumer CEL evaluation context.
+ *   3. buildContext() enforces grants and scans the raw manifest for unauthorized
+ *      references, throwing ERR_VISIBILITY_DENIED on violations.
+ */
+export class BootContextRegistry {
+  private providers: ProviderEntry[] = [];
+
+  /**
+   * Register a new context provider after its init() has completed.
+   * Called by the kernel for every resource instance that passes isContextProvider().
+   */
+  register(
+    kind: string,
+    name: string,
+    module: string,
+    grants: string[] | undefined,
+    context: Record<string, unknown>,
+  ): void {
+    this.providers.push({ kind, name, module, grants, context });
+  }
+
+  /**
+   * Returns true if at least one provider has been registered.
+   * Used by the kernel to skip context resolution when there are no providers yet.
+   */
+  hasProviders(): boolean {
+    return this.providers.length > 0;
+  }
+
+  /**
+   * Build a CEL evaluation context for a specific consumer resource, enforcing
+   * RBAC grants.
+   *
+   * For each registered provider:
+   *  - `grants === undefined` → unrestricted, always included.
+   *  - `grants` defined and consumer key in grants → included.
+   *  - `grants` defined and consumer key NOT in grants:
+   *      - Scan the raw manifest JSON for `${{ ... }}` expressions that reference
+   *        the provider's namespace prefix (`"${kind}.${name}."`).
+   *      - If a reference is found → throw ERR_VISIBILITY_DENIED immediately.
+   *      - If no reference → silently exclude the provider from the context.
+   *
+   * CEL context structure mirrors the kind hierarchy:
+   *   kind="Config", name="database"     → { Config: { database: { host, port } } }
+   *   kind="MyApp.Secrets", name="vault" → { MyApp: { Secrets: { vault: { ... } } } }
+   *
+   * @param consumerKind - kind of the resource being initialized (e.g. "MyApp.Api.Server")
+   * @param consumerName - name of the resource being initialized (e.g. "api")
+   * @param rawManifest  - the unresolved manifest object (used for namespace reference scan)
+   */
+  buildContext(
+    consumerKind: string,
+    consumerName: string,
+    rawManifest: Record<string, unknown>,
+  ): Record<string, unknown> {
+    const consumerKey = `${consumerKind}/${consumerName}`;
+    const celContext: Record<string, unknown> = {};
+    const manifestJson = JSON.stringify(rawManifest);
+
+    for (const provider of this.providers) {
+      const isGranted = provider.grants === undefined || provider.grants.includes(consumerKey);
+
+      if (!isGranted) {
+        const namespacePrefix = buildProviderNamespacePrefix(provider.kind, provider.name);
+        if (manifestReferencesNamespace(manifestJson, namespacePrefix)) {
+          throw new RuntimeError(
+            "ERR_VISIBILITY_DENIED",
+            `Resource "${consumerKind}/${consumerName}" references context from ` +
+              `provider "${provider.kind}/${provider.name}" but is not listed in its grants. ` +
+              `Add "${consumerKey}" to the provider's grants field to allow access.`,
+          );
+        }
+        // Not referenced and not granted — silently exclude
+        continue;
+      }
+
+      mergeProviderIntoContext(celContext, provider.kind, provider.name, provider.context);
+    }
+
+    return celContext;
+  }
+}
+
+/**
+ * Build the namespace prefix string that appears inside a `${{ }}` expression
+ * when a consumer references this provider.
+ *
+ * The trailing dot ensures we match the start of a property access without
+ * false-matching a shared prefix substring:
+ *   kind="Config", name="database"    → "Config.database."
+ *   kind="MyApp.Secrets", name="vault" → "MyApp.Secrets.vault."
+ */
+function buildProviderNamespacePrefix(kind: string, name: string): string {
+  return `${kind}.${name}.`;
+}
+
+/**
+ * Scan serialized manifest JSON for any `${{ expression }}` block that contains
+ * the provider's namespace prefix.
+ *
+ * Using JSON.stringify() as the scan target covers all nested fields uniformly.
+ * The approach cannot produce false positives from field names or non-template
+ * values because `${{` is not valid JSON syntax outside a string value.
+ */
+function manifestReferencesNamespace(manifestJson: string, namespacePrefix: string): boolean {
+  let searchFrom = 0;
+  while (true) {
+    const start = manifestJson.indexOf("${{", searchFrom);
+    if (start === -1) break;
+    const end = manifestJson.indexOf("}}", start + 3);
+    if (end === -1) break;
+    const expression = manifestJson.slice(start + 3, end);
+    if (expression.includes(namespacePrefix)) {
+      return true;
+    }
+    searchFrom = end + 2;
+  }
+  return false;
+}
+
+/**
+ * Place provider.context into the CEL context object under the path
+ * defined by the provider's kind segments and name.
+ *
+ *   kind="Config", name="database":
+ *     context.Config = { database: { host, port } }
+ *
+ *   kind="MyApp.Api", name="server":
+ *     context.MyApp = { Api: { server: { ... } } }
+ */
+function mergeProviderIntoContext(
+  celContext: Record<string, unknown>,
+  kind: string,
+  name: string,
+  providerData: Record<string, unknown>,
+): void {
+  const kindSegments = kind.split(".");
+  let cursor = celContext;
+  for (const segment of kindSegments) {
+    if (typeof cursor[segment] !== "object" || cursor[segment] === null) {
+      cursor[segment] = {};
+    }
+    cursor = cursor[segment] as Record<string, unknown>;
+  }
+  cursor[name] = providerData;
+}

package/src/controller-loader.ts

@@ -0,0 +1,299 @@
+import { ControllerInstance, RuntimeError } from "@telorun/sdk";
+import { execFile } from "child_process";
+import { createHash } from "crypto";
+import * as fs from "fs/promises";
+import * as os from "os";
+import { PackageURL } from "packageurl-js";
+import * as path from "path";
+import { promisify } from "util";
+
+const homedir = os.homedir();
+const cacheRoot = path.join(homedir, ".cache", "telo");
+const npmCacheRoot = path.join(cacheRoot, "npm");
+const isBun = typeof (globalThis as any).Bun !== "undefined";
+
+export class ControllerLoader {
+  /**
+   * Load controller instance from URI in format:
+   *
+   * <runtime>:<registry>:<path>@<version-spec>
+   */
+  async load(purlCandidates: string[], baseUri: string): Promise<ControllerInstance> {
+    if (!purlCandidates || purlCandidates.length === 0) {
+      throw new RuntimeError("ERR_CONTROLLER_NOT_FOUND", "Missing controller PURL candidates");
+    }
+    const purl = purlCandidates.find((p) => p.startsWith("pkg:npm"));
+    if (!purl) {
+      throw new RuntimeError(
+        "ERR_CONTROLLER_NOT_FOUND",
+        "Controller PURL candidates not applicable",
+      );
+    }
+    const [type, namespace, name, versionSpec, qualifiers, entry] = PackageURL.parseString(purl);
+
+    const localPath = (qualifiers as any)?.get("local_path");
+    const cacheKey = createHash("sha256").update(purlCandidates[0]).digest("hex").slice(0, 12);
+    const installDir = path.join(npmCacheRoot, cacheKey);
+
+    let packageRoot: string;
+    const isLocalManifest =
+      baseUri && !baseUri.startsWith("http://") && !baseUri.startsWith("https://");
+    if (localPath && isLocalManifest) {
+      const baseUriPath = baseUri.startsWith("file://") ? baseUri.slice("file://".length) : baseUri;
+      const manifestDir = path.dirname(baseUriPath);
+      const resolvedLocalPath = path.resolve(manifestDir, localPath);
+      if (await this.pathExists(resolvedLocalPath)) {
+        packageRoot = resolvedLocalPath;
+      } else {
+        const nodeModulesPath = await this.findInNodeModules(`${namespace}/${name}`);
+        if (nodeModulesPath) {
+          packageRoot = nodeModulesPath;
+        } else {
+          await this.ensureNpmPackageInstalled(installDir, `${namespace}/${name}@${versionSpec}`);
+          packageRoot = this.getInstalledPackageRoot(installDir, `${namespace}/${name}`);
+        }
+      }
+    } else {
+      const nodeModulesPath = await this.findInNodeModules(`${namespace}/${name}`);
+      if (nodeModulesPath) {
+        packageRoot = nodeModulesPath;
+      } else {
+        await this.ensureNpmPackageInstalled(installDir, `${namespace}/${name}@${versionSpec}`);
+        packageRoot = this.getInstalledPackageRoot(installDir, `${namespace}/${name}`);
+      }
+    }
+
+    const entryFile = await this.resolvePackageEntry(packageRoot, entry ? `./${entry}` : ".");
+    const instance = await import(entryFile);
+    if (!instance || (!instance.create && !instance.register)) {
+      throw new Error(
+        `Invalid controller loaded from "${purlCandidates[0]}": missing create or register function`,
+      );
+    }
+    return instance;
+  }
+
+  private async ensureNpmPackageInstalled(installDir: string, packageSpec: string): Promise<void> {
+    const packageName = this.getPackageName(
+      packageSpec.startsWith(".") || path.isAbsolute(packageSpec)
+        ? await this.getLocalPackageName(packageSpec)
+        : packageSpec,
+    );
+    const packageRoot = this.getInstalledPackageRoot(installDir, packageName);
+    const packageJsonPath = path.join(packageRoot, "package.json");
+    if (await this.pathExists(packageJsonPath)) {
+      return;
+    }
+
+    await fs.mkdir(installDir, { recursive: true });
+    const rootPackageJson = path.join(installDir, "package.json");
+    if (!(await this.pathExists(rootPackageJson))) {
+      await fs.writeFile(
+        rootPackageJson,
+        JSON.stringify({ name: "telo-cache", private: true }, null, 2),
+      );
+    }
+
+    const execFileAsync = promisify(execFile);
+    const args = [
+      "install",
+      "--no-audit",
+      "--no-fund",
+      "--silent",
+      "--prefix",
+      installDir,
+      packageSpec,
+    ];
+
+    await execFileAsync("npm", args);
+  }
+
+  private getPackageName(packageSpec: string): string {
+    if (packageSpec.startsWith("@")) {
+      const lastAt = packageSpec.lastIndexOf("@");
+      return lastAt > 0 ? packageSpec.slice(0, lastAt) : packageSpec;
+    }
+    const [name] = packageSpec.split("@");
+    return name;
+  }
+
+  private getInstalledPackageRoot(installDir: string, packageName: string): string {
+    const nameParts = packageName.split("/");
+    return path.join(installDir, "node_modules", ...nameParts);
+  }
+
+  private async getLocalPackageName(packagePath: string): Promise<string> {
+    const packageJsonPath = path.join(packagePath, "package.json");
+    if (!(await this.pathExists(packageJsonPath))) {
+      throw new Error(`Local package missing package.json: ${packagePath}`);
+    }
+    const content = await fs.readFile(packageJsonPath, "utf8");
+    const parsed = JSON.parse(content);
+    if (!parsed?.name) {
+      throw new Error(`Local package missing name in package.json: ${packagePath}`);
+    }
+    return parsed.name;
+  }
+
+  private async resolvePackageEntry(
+    packageRoot: string,
+    entry: string,
+    packageName?: string,
+  ): Promise<string> {
+    const packageJsonPath = path.join(packageRoot, "package.json");
+    let resolvedPackageName = packageName;
+    let packageJson: any = null;
+    if (!resolvedPackageName && (await this.pathExists(packageJsonPath))) {
+      const content = await fs.readFile(packageJsonPath, "utf8");
+      try {
+        packageJson = JSON.parse(content);
+        resolvedPackageName = packageJson?.name;
+      } catch {
+        resolvedPackageName = packageName;
+      }
+    } else if (await this.pathExists(packageJsonPath)) {
+      try {
+        packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8"));
+      } catch {
+        packageJson = null;
+      }
+    }
+
+    const entryValue = entry.trim();
+    const exportTarget = this.resolvePackageExportTarget(packageJson?.exports, entryValue);
+    if (exportTarget) {
+      const resolved = path.resolve(packageRoot, exportTarget);
+      if (await this.pathExists(resolved)) {
+        return this.resolveForRuntime(resolved, packageRoot);
+      }
+      if (!path.extname(resolved)) {
+        const withJs = `${resolved}.js`;
+        if (await this.pathExists(withJs)) {
+          return withJs;
+        }
+      }
+    }
+    if ((entryValue === "." || entryValue === "./") && packageJson) {
+      const mainFields = ["module", "main"];
+      for (const field of mainFields) {
+        const target = packageJson[field];
+        if (typeof target === "string") {
+          const resolved = path.resolve(packageRoot, target);
+          if (await this.pathExists(resolved)) {
+            return this.resolveForRuntime(resolved, packageRoot);
+          }
+          if (!path.extname(resolved)) {
+            const withJs = `${resolved}.js`;
+            if (await this.pathExists(withJs)) {
+              return withJs;
+            }
+          }
+        }
+      }
+    }
+
+    const directPath = path.resolve(packageRoot, entryValue);
+    if (await this.pathExists(directPath)) {
+      return this.resolveForRuntime(directPath, packageRoot);
+    }
+    if (!path.extname(directPath)) {
+      const withJs = `${directPath}.js`;
+      if (await this.pathExists(withJs)) {
+        return withJs;
+      }
+    }
+
+    throw new Error(`Controller entry "${entryValue}" could not be resolved in ${packageRoot}`);
+  }
+
+  private resolvePackageExportTarget(exportsField: any, entry: string): string | null {
+    if (!exportsField) {
+      return null;
+    }
+
+    const key = entry === "." || entry === "./" ? "." : entry;
+    const target = exportsField[key];
+    return this.resolveExportTargetValue(target);
+  }
+
+  private resolveExportTargetValue(target: any): string | null {
+    if (!target) {
+      return null;
+    }
+    if (typeof target === "string") {
+      return target;
+    }
+    if (Array.isArray(target)) {
+      for (const item of target) {
+        const resolved = this.resolveExportTargetValue(item);
+        if (resolved) {
+          return resolved;
+        }
+      }
+      return null;
+    }
+    if (typeof target === "object") {
+      const preferredKeys = isBun
+        ? ["bun", "import", "default", "require"]
+        : ["import", "default", "require"];
+      for (const key of preferredKeys) {
+        if (target[key]) {
+          const resolved = this.resolveExportTargetValue(target[key]);
+          if (resolved) {
+            return resolved;
+          }
+        }
+      }
+    }
+    return null;
+  }
+
+  /**
+   * For Node.js, resolve .ts paths to their compiled .js equivalents in dist/.
+   * Bun can load .ts directly, so it returns the path unchanged.
+   */
+  private async resolveForRuntime(resolvedPath: string, packageRoot: string): Promise<string> {
+    if (isBun || !resolvedPath.endsWith(".ts")) {
+      return resolvedPath;
+    }
+    // Try dist/ equivalent: src/foo.ts -> dist/foo.js
+    const relative = path.relative(packageRoot, resolvedPath);
+    const distEquivalent = path.resolve(
+      packageRoot,
+      relative.replace(/^src\//, "dist/").replace(/\.ts$/, ".js"),
+    );
+    if (await this.pathExists(distEquivalent)) {
+      return distEquivalent;
+    }
+    // Fallback: same location but .js
+    const jsPath = resolvedPath.replace(/\.ts$/, ".js");
+    if (await this.pathExists(jsPath)) {
+      return jsPath;
+    }
+    return resolvedPath;
+  }
+
+  private async findInNodeModules(packageName: string): Promise<string | null> {
+    const nameParts = packageName.split("/");
+    const candidates = [
+      path.join(process.cwd(), "node_modules", ...nameParts),
+      path.join(process.cwd(), "node_modules", ".pnpm", "node_modules", ...nameParts),
+    ];
+    for (const candidate of candidates) {
+      const packageJsonPath = path.join(candidate, "package.json");
+      if (await this.pathExists(packageJsonPath)) {
+        return candidate;
+      }
+    }
+    return null;
+  }
+
+  private async pathExists(filePath: string): Promise<boolean> {
+    try {
+      await fs.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/controller-registry.ts

@@ -0,0 +1,191 @@
+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();
+  /**
+   * 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;
+    // }
+    return {
+      schema: { type: "object", additionalProperties: false },
+    };
+    // 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);
+    const wrappedController: ControllerInstance = {
+      ...controller,
+      schema: controller.schema ?? definition?.schema,
+      inputSchema: controller.inputSchema,
+      outputSchema: controller.outputSchema,
+    };
+    this.controllersByKind.set(kind, wrappedController);
+  }
+
+  /**
+   * 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"))
+    );
+  }
+}