@telorun/kernel 0.2.6 → 0.2.8

package/src/kernel.ts

@@ -1,23 +1,35 @@
-import { AnalysisRegistry, StaticAnalyzer } from "@telorun/analyzer";
+import { AnalysisRegistry, DEFAULT_MANIFEST_FILENAME, Loader, StaticAnalyzer } from "@telorun/analyzer";
 import {
-    ControllerContext,
-    Kernel as IKernel,
-    ModuleContext,
-    ResourceContext,
-    ResourceDefinition,
-    ResourceInstance,
-    ResourceManifest,
-    RuntimeError,
-    RuntimeEvent,
-    isCompiledValue,
+  ControllerContext,
+  Kernel as IKernel,
+  ResourceContext,
+  ResourceDefinition,
+  ResourceInstance,
+  ResourceManifest,
+  RuntimeError,
+  RuntimeEvent,
+  isCompiledValue,
+  type EvaluationContext as IEvaluationContext,
+  type ModuleContext as IModuleContext,
+  type ParsedArgs,
 } from "@telorun/sdk";
+import { ModuleContext } from "./module-context.js";
 import * as path from "path";
+import { parseArgs } from "util";
 import { ControllerRegistry } from "./controller-registry.js";
 import { EventStream } from "./event-stream.js";
 import { EventBus } from "./events.js";
-import { Loader } from "./loader.js";
+import { LocalFileAdapter } from "./manifest-adapters/local-file-adapter.js";
 import { ResourceContextImpl } from "./resource-context.js";
-import { SchemaValidator } from "./schema-valiator.js";
+import { SchemaValidator } from "./schema-validator.js";
+
+export interface KernelOptions {
+  stdin?: NodeJS.ReadableStream;
+  stdout?: NodeJS.WritableStream;
+  stderr?: NodeJS.WritableStream;
+  env?: Record<string, string | undefined>;
+  argv?: string[];
+}
 
 /**
  * Kernel: Central orchestrator managing lifecycle and message bus
@@ -27,26 +39,30 @@ export class Kernel implements IKernel {
   private readonly loader = new Loader();
   private readonly analyzer = new StaticAnalyzer();
   private readonly registry = new AnalysisRegistry();
-  // private manifests: ManifestRegistry = new ManifestRegistry();
   private controllers: ControllerRegistry = new ControllerRegistry();
   private eventBus: EventBus = new EventBus();
   private eventStream: EventStream = new EventStream();
-  // private snapshotSerializer: SnapshotSerializer = new SnapshotSerializer();
-  // private runtimeManifests: ResourceManifest[] | null = null;
-  // private resourceInstances: Map<
-  //   string,
-  //   { resource: ResourceManifest; instance: ResourceInstance }
-  // > = new Map();
 
   private holdCount = 0;
   private idleResolvers: Array<() => void> = [];
   private _exitCode = 0;
-  // private bootContextRegistry = new BootContextRegistry();
   private readonly sharedSchemaValidator = new SchemaValidator();
   private rootContext!: ModuleContext;
   private staticManifests: ResourceManifest[] = [];
 
-  constructor() {
+  readonly stdin: NodeJS.ReadableStream;
+  readonly stdout: NodeJS.WritableStream;
+  readonly stderr: NodeJS.WritableStream;
+  readonly env: Record<string, string | undefined>;
+  readonly argv: string[];
+
+  constructor(options: KernelOptions = {}) {
+    this.stdin = options.stdin ?? process.stdin;
+    this.stdout = options.stdout ?? process.stdout;
+    this.stderr = options.stderr ?? process.stderr;
+    this.env = options.env ?? process.env;
+    this.argv = options.argv ?? [];
+    this.loader.register(new LocalFileAdapter());
     this.setupEventStreaming();
   }
 
@@ -125,11 +141,8 @@ export class Kernel implements IKernel {
    * Load from runtime configuration file
    */
   async loadFromConfig(runtimeYamlPath: string): Promise<void> {
-    // Resolve directory paths to their module.yaml so that relative imports
-    // (e.g. ../../modules/foo) use the correct base directory.
-    const sourceUrl = await this.loader.resolveEntryPoint(
-      new URL(runtimeYamlPath, `file://${process.cwd()}/`).href,
-    );
+    const resolvedUrl = new URL(runtimeYamlPath, `file://${process.cwd()}/`).href;
+    const sourceUrl = await this.loader.resolveEntryPoint(resolvedUrl);
     this.rootContext = new ModuleContext(
       sourceUrl,
       {},
@@ -138,7 +151,7 @@ export class Kernel implements IKernel {
       [],
       this._createInstance.bind(this),
       (event, payload) => this.eventBus.emit(event, payload),
-      process.env,
+      this.env,
     );
     // Initialize built-in Runtime definitions first
     await this.loadBuiltinDefinitions();
@@ -205,7 +218,7 @@ export class Kernel implements IKernel {
    * @deprecated Use loadFromConfig instead
    */
   async loadDirectory(dirPath: string): Promise<void> {
-    const configYamlPath = path.join(dirPath, "module.yaml");
+    const configYamlPath = path.join(dirPath, DEFAULT_MANIFEST_FILENAME);
 
     await this.loadFromConfig(configYamlPath);
   }
@@ -350,18 +363,68 @@ export class Kernel implements IKernel {
     };
   }
 
+  /**
+   * Walk up the parent chain from a given evaluation context to find the nearest
+   * ModuleContext ancestor. Falls back to rootContext if none found.
+   */
+  private findModuleContext(ctx: IEvaluationContext): IModuleContext {
+    let current: IEvaluationContext | undefined = ctx;
+    while (current) {
+      if (current instanceof ModuleContext) return current;
+      current = current.parent;
+    }
+    return this.rootContext;
+  }
+
   private createResourceContext(
-    moduleContext: ModuleContext,
+    moduleContext: IModuleContext,
     resource: ResourceManifest,
+    args?: ParsedArgs,
   ): ResourceContext {
     return new ResourceContextImpl(
       this,
       moduleContext,
       resource.metadata,
       this.sharedSchemaValidator,
+      this.stdin,
+      this.stdout,
+      this.stderr,
+      args,
     );
   }
 
+  /**
+   * Parse kernel.argv using a controller's args spec (if present).
+   * If the controller exports no args spec, does a generic parse.
+   */
+  private parseArgsForController(controller: any): ParsedArgs {
+    if (this.argv.length === 0) return { _: [] };
+
+    const argSpec = controller.args;
+    if (argSpec) {
+      const options: Record<string, { type: "string" | "boolean"; short?: string }> = {};
+      for (const [name, def] of Object.entries(argSpec) as [string, any][]) {
+        options[name] = { type: def.type ?? "string" };
+        if (def.alias) options[name].short = def.alias;
+      }
+      const { values, positionals } = parseArgs({
+        args: this.argv,
+        options,
+        allowPositionals: true,
+        strict: false,
+      });
+      return { ...values, _: positionals } as ParsedArgs;
+    }
+
+    // Generic parse: no spec, best-effort
+    const { values, positionals } = parseArgs({
+      args: this.argv,
+      allowPositionals: true,
+      strict: false,
+    });
+    return { ...values, _: positionals } as ParsedArgs;
+  }
+
   /**
    * Create phase only: resolves the controller, validates the schema, and calls
    * controller.create(). Returns { instance, ctx } so initializeResources can
@@ -369,7 +432,7 @@ export class Kernel implements IKernel {
    * is not yet registered (retry signal).
    */
   private async _createInstance(
-    evalContext: ModuleContext,
+    evalContext: IEvaluationContext,
     resource: ResourceManifest,
   ): Promise<{ instance: ResourceInstance; ctx: ResourceContext } | null> {
     const kind = resource.kind;
@@ -434,7 +497,9 @@ export class Kernel implements IKernel {
         ) as ResourceManifest)
       : resource;
 
-    const ctx = this.createResourceContext(evalContext, processedResource);
+    const parsedArgs = this.parseArgsForController(controller);
+    const moduleCtx = this.findModuleContext(evalContext);
+    const ctx = this.createResourceContext(moduleCtx, processedResource, parsedArgs);
     const instance = await controller.create(processedResource, ctx);
     if (!instance) return null;
 
@@ -529,20 +594,61 @@ function placeholderForSchema(schema: Record<string, unknown>): unknown {
   }
 }
 
+/** Resolve a `$ref` (only `#/$defs/...` form) against the root schema. */
+function resolveSchemaRef(
+  schema: Record<string, unknown>,
+  root: Record<string, unknown>,
+): Record<string, unknown> {
+  if (schema.$ref && typeof schema.$ref === "string" && (schema.$ref as string).startsWith("#/$defs/")) {
+    const defName = (schema.$ref as string).slice("#/$defs/".length);
+    const defs = root.$defs as Record<string, Record<string, unknown>> | undefined;
+    const resolved = defs?.[defName];
+    if (resolved) return resolved;
+  }
+  return schema;
+}
+
+/** Collect property schemas from top-level `properties` and all `oneOf`/`anyOf` sub-schemas. */
+function collectSchemaProperties(
+  schema: Record<string, unknown>,
+): Record<string, Record<string, unknown>> {
+  const props: Record<string, Record<string, unknown>> = {
+    ...((schema.properties ?? {}) as Record<string, Record<string, unknown>>),
+  };
+  for (const sub of (schema.oneOf ?? schema.anyOf ?? []) as Record<string, unknown>[]) {
+    if (sub && typeof sub === "object" && sub.properties) {
+      for (const [k, v] of Object.entries(sub.properties as Record<string, Record<string, unknown>>)) {
+        if (!(k in props)) props[k] = v;
+      }
+    }
+  }
+  return props;
+}
+
 /** Replaces CompiledValue wrappers with schema-appropriate placeholders for schema validation.
  *  Template strings were compiled from YAML at load time; this restores a shape
  *  that AJV can validate without evaluating expressions. */
-function stripCompiledValues(v: unknown, schema: Record<string, unknown> = {}): unknown {
-  if (isCompiledValue(v)) return placeholderForSchema(schema);
+function stripCompiledValues(
+  v: unknown,
+  schema: Record<string, unknown> = {},
+  rootSchema?: Record<string, unknown>,
+): unknown {
+  const root = rootSchema ?? schema;
+  const resolved = resolveSchemaRef(schema, root);
+
+  if (isCompiledValue(v)) return placeholderForSchema(resolved);
   if (Array.isArray(v)) {
-    const itemSchema = (schema.items ?? {}) as Record<string, unknown>;
-    return v.map((item) => stripCompiledValues(item, itemSchema));
+    const itemSchema = resolveSchemaRef(
+      (resolved.items ?? {}) as Record<string, unknown>,
+      root,
+    );
+    return v.map((item) => stripCompiledValues(item, itemSchema, root));
   }
   if (v !== null && typeof v === "object") {
-    const props = (schema.properties ?? {}) as Record<string, Record<string, unknown>>;
+    const props = collectSchemaProperties(resolved);
     const out: Record<string, unknown> = {};
     for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
-      out[k] = stripCompiledValues(val, props[k] ?? {});
+      out[k] = stripCompiledValues(val, props[k] ?? {}, root);
     }
     return out;
   }

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

@@ -1,4 +1,4 @@
-import type { ManifestAdapter } from "@telorun/analyzer";
+import { DEFAULT_MANIFEST_FILENAME, type ManifestAdapter } from "@telorun/analyzer";
 import * as fs from "fs/promises";
 import * as path from "path";
 
@@ -19,7 +19,7 @@ export class LocalFileAdapter implements ManifestAdapter {
       : pathOrUrl;
     const resolvedPath = path.resolve(normalizedPath);
     const stat = await fs.stat(resolvedPath);
-    const filePath = stat.isDirectory() ? path.join(resolvedPath, "module.yaml") : resolvedPath;
+    const filePath = stat.isDirectory() ? path.join(resolvedPath, DEFAULT_MANIFEST_FILENAME) : resolvedPath;
     const text = await fs.readFile(filePath, "utf-8");
     return { text, source: `file://${filePath}` };
   }

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

@@ -17,7 +17,7 @@ export interface ManifestAdapter {
   /**
    * Read a single manifest entry point.
    * - File path or URL → read that file/URL.
-   * - Directory path → find and read `module.yaml` within it.
+   * - Directory path → find and read `telo.yaml` within it.
    */
   read(pathOrUrl: string): Promise<ManifestSourceData>;
   /**

package/src/module-context.ts

@@ -0,0 +1,211 @@
+import type { Invocable, ModuleContext as IModuleContext } from "@telorun/sdk";
+import type { EmitEvent, InstanceFactory } from "@telorun/sdk";
+import { EvaluationContext } from "./evaluation-context.js";
+
+/** Wraps process.env so that missing keys return null instead of throwing in CEL.
+ * cel-js uses Object.hasOwn(obj, key) before accessing obj[key], so we must
+ * intercept getOwnPropertyDescriptor to report every string key as "own". */
+function lenientEnv(env: Record<string, string | undefined>): Record<string, string | null> {
+  return new Proxy(env as Record<string, string | null>, {
+    get(target, key) {
+      if (typeof key !== "string") return (target as any)[key];
+      return key in target ? (target[key] ?? null) : null;
+    },
+    has() {
+      return true;
+    },
+    getOwnPropertyDescriptor(target, key) {
+      if (typeof key !== "string") return Object.getOwnPropertyDescriptor(target, key);
+      const value = key in target ? (target[key] ?? null) : null;
+      return { configurable: true, enumerable: true, writable: true, value };
+    },
+  });
+}
+
+function collectSecretValues(secrets: Record<string, unknown>): Set<string> {
+  const values = new Set<string>();
+  for (const value of Object.values(secrets)) {
+    if (typeof value === "string" && value.length > 0) {
+      values.add(value);
+    }
+  }
+  return values;
+}
+
+/**
+ * Persistent, module-scoped context. Three reserved CEL namespaces:
+ * variables, secrets, resources.
+ *
+ * Unlike the base EvaluationContext, ModuleContext is stateful and mutable:
+ * variables/secrets/resources accumulate during multi-pass initialization and
+ * the context record is rebuilt on each mutation. Import aliases are tracked
+ * here for alias-prefixed kind resolution (e.g. MyImport.Http.Route).
+ *
+ * Imported modules are surfaced under resources.<alias> alongside local
+ * resources — no separate imports namespace needed.
+ */
+export class ModuleContext extends EvaluationContext implements IModuleContext {
+  private _variables: Record<string, unknown>;
+  private _secrets: Record<string, unknown>;
+  private _resources: Record<string, unknown>;
+
+  /** Maps import alias → real module name for kind resolution. */
+  readonly importAliases = new Map<string, string>();
+
+  /** Maps import alias → allowed kind names. Absent entry = unrestricted (e.g. Kernel). */
+  private readonly importedKinds = new Map<string, Set<string>>();
+
+  constructor(
+    source: string,
+    variables: Record<string, unknown> = {},
+    secrets: Record<string, unknown> = {},
+    resources: Record<string, unknown> = {},
+    private targets: string[] = [],
+    createInstance: InstanceFactory = async () => null,
+    emit: EmitEvent,
+    private readonly _hostEnv?: Record<string, string | undefined>,
+  ) {
+    super(source, {}, createInstance, new Set(), emit);
+    this._variables = variables;
+    this._secrets = secrets;
+    this._resources = resources;
+    this._rebuildContext();
+  }
+
+  get variables(): Record<string, unknown> {
+    return this._variables;
+  }
+
+  get secrets(): Record<string, unknown> {
+    return this._secrets;
+  }
+
+  get resources(): Record<string, unknown> {
+    return this._resources;
+  }
+
+  setVariables(vars: Record<string, unknown>): void {
+    this._variables = vars;
+    this._rebuildContext();
+  }
+
+  setTargets(vars: string[]): void {
+    this.targets = vars;
+  }
+
+  setSecrets(secrets: Record<string, unknown>): void {
+    this._secrets = secrets;
+    this._rebuildContext();
+  }
+
+  setResource(name: string, props: Record<string, unknown>): void {
+    this._resources = { ...this._resources, [name]: props };
+    this._rebuildContext();
+  }
+
+  protected override onResourceSnapshotted(name: string, snap: Record<string, unknown>): void {
+    this.setResource(name, snap);
+  }
+
+  /**
+   * Register an imported module under the given alias, with the list of kind names
+   * it exports. An empty kinds array means no restriction (used for built-ins like Kernel).
+   */
+  registerImport(alias: string, targetModule: string, kinds: string[]): void {
+    this.importAliases.set(alias, targetModule);
+    if (kinds.length > 0) {
+      this.importedKinds.set(alias, new Set(kinds));
+    }
+  }
+
+  getInstance(name: string): unknown {
+    const entry = this.resourceInstances.get(name);
+    if (!entry) {
+      throw new Error(
+        `Resource '${name}' not found in module context. Available resources: ${[...this.resourceInstances.keys()].join(", ")}`,
+      );
+    }
+    return entry?.instance;
+  }
+
+  getInvocable<TInput = Record<string, any>, TOutput = any>(
+    name: string,
+  ): Invocable<TInput, TOutput> {
+    const instance = this.getInstance(name);
+
+    if (typeof (instance as any)?.invoke !== "function") {
+      throw new Error(`Resource '${name}' does not have an invoke() method.`);
+    }
+    return instance as Invocable<TInput, TOutput>;
+  }
+
+  /**
+   * Resolve a fully-qualified kind like "Http.Server" to its real kind "http-server.Server".
+   * Splits on the first dot, looks up the prefix in importAliases, validates against
+   * importedKinds (if set), and reconstructs the resolved kind.
+   * Throws with a clear message if the alias is unknown or the kind is not exported.
+   */
+  resolveKind(kind: string): string {
+    const dot = kind.indexOf(".");
+    if (dot === -1) {
+      throw new Error(`Kind '${kind}' must be fully qualified (e.g. 'Module.KindName')`);
+    }
+    const prefix = kind.slice(0, dot);
+    const suffix = kind.slice(dot + 1);
+    const realModule = this.importAliases.get(prefix);
+    if (!realModule) {
+      const known = [...this.importAliases.keys()].join(", ") || "(none)";
+      throw new Error(
+        `Kind '${kind}': no module imported with alias '${prefix}'. Known aliases: ${known}`,
+      );
+    }
+    const allowed = this.importedKinds.get(prefix);
+    if (allowed !== undefined && !allowed.has(suffix)) {
+      throw new Error(
+        `Kind '${suffix}' is not exported by module '${realModule}' (imported as '${prefix}'). ` +
+          `Exported kinds: ${[...allowed].join(", ")}`,
+      );
+    }
+    return `${realModule}.${suffix}`;
+  }
+
+  private _rebuildContext(): void {
+    this._context = {
+      variables: this._variables,
+      secrets: this._secrets,
+      resources: this._resources,
+      ...(this._hostEnv ? { env: lenientEnv(this._hostEnv) } : {}),
+    };
+    this._secretValues = collectSecretValues(this._secrets);
+  }
+
+  override async invoke<TInputs>(kind: string, name: string, inputs: TInputs): Promise<any> {
+    const result = await super.invoke(kind, name, inputs);
+    const entry = this.resourceInstances.get(name);
+    if (entry && typeof (entry.instance as any).snapshot === "function") {
+      const snap = await Promise.resolve((entry.instance as any).snapshot());
+      this.setResource(name, snap as Record<string, unknown>);
+    }
+    return result;
+  }
+
+  async run(name: string) {
+    const resource = this.resourceInstances.get(name);
+    if (!resource) {
+      throw new Error(
+        `Target resource ${name} not found in module context. Available resources: ${[...this.resourceInstances.keys()].join(", ")}`,
+      );
+    }
+    if (typeof resource.instance.run === "function") {
+      await resource.instance.run();
+    } else {
+      throw new Error(`Target resource ${name} does not have a run() method.`);
+    }
+  }
+
+  async runTargets() {
+    for (const target of this.targets) {
+      await this.run(target);
+    }
+  }
+}

package/src/resource-context.ts

@@ -1,31 +1,44 @@
 import {
-  EvaluationContext,
-  ModuleContext,
   NoopValidator,
   ResourceContext,
   RuntimeError,
   RuntimeResource,
   isCompiledValue,
+  type EvaluationContext as IEvaluationContext,
+  type ModuleContext,
+  type ParsedArgs,
+  type TypeRule,
 } from "@telorun/sdk";
+import { EvaluationContext } from "./evaluation-context.js";
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
 import { Kernel } from "./kernel.js";
 import { formatAjvErrors } from "./manifest-schemas.js";
-import { SchemaValidator } from "./schema-valiator.js";
+import { SchemaValidator } from "./schema-validator.js";
 
 const Ajv = AjvModule.default ?? AjvModule;
 
 export class ResourceContextImpl implements ResourceContext {
+  readonly stdin: NodeJS.ReadableStream;
+  readonly stdout: NodeJS.WritableStream;
+  readonly stderr: NodeJS.WritableStream;
+  readonly args: ParsedArgs;
+
   constructor(
     readonly kernel: Kernel,
     readonly moduleContext: ModuleContext,
     private readonly metadata: Record<string, any>,
     private readonly validator: SchemaValidator = new SchemaValidator(),
-  ) {}
-
-  stdin: NodeJS.ReadableStream = process.stdin;
-  stdout: NodeJS.WritableStream = process.stdout;
-  stderr: NodeJS.WritableStream = process.stderr;
+    stdin?: NodeJS.ReadableStream,
+    stdout?: NodeJS.WritableStream,
+    stderr?: NodeJS.WritableStream,
+    args?: ParsedArgs,
+  ) {
+    this.stdin = stdin ?? process.stdin;
+    this.stdout = stdout ?? process.stdout;
+    this.stderr = stderr ?? process.stderr;
+    this.args = args ?? { _: [] };
+  }
 
   createSchemaValidator(schema: any) {
     if (!schema) {
@@ -42,6 +55,48 @@ export class ResourceContextImpl implements ResourceContext {
     return this.validator.getSchema(name);
   }
 
+  registerTypeRules(name: string, rules: TypeRule[]): void {
+    this.validator.addTypeRules(name, rules);
+  }
+
+  lookupTypeRules(name: string): TypeRule[] | undefined {
+    return this.validator.getTypeRules(name);
+  }
+
+  createTypeValidator(typeRef: string | Record<string, any> | undefined) {
+    if (!typeRef) return new NoopValidator();
+
+    // String reference: look up registered type schema by name
+    if (typeof typeRef === "string") {
+      const schema = this.validator.getSchema(typeRef);
+      if (!schema) {
+        throw new RuntimeError(
+          "ERR_TYPE_NOT_FOUND",
+          `Type "${typeRef}" not found in schema registry`,
+        );
+      }
+      const base = this.validator.compile(schema);
+      const rules = this.validator.getTypeRules(typeRef);
+      if (rules && rules.length > 0) {
+        return this.validator.composeWithRules(base, typeRef, rules);
+      }
+      return base;
+    }
+
+    // Inline schema object: if it has a `schema` property, it's a type resource shape
+    if (typeRef.schema && typeof typeRef.schema === "object") {
+      const base = this.validator.compile(typeRef.schema);
+      const rules = Array.isArray(typeRef.rules) ? typeRef.rules : [];
+      if (rules.length > 0) {
+        return this.validator.composeWithRules(base, "inline", rules);
+      }
+      return base;
+    }
+
+    // Raw JSON Schema object (direct schema, not wrapped in type resource)
+    return this.validator.compile(typeRef);
+  }
+
   validateSchema(value: any, schema: any) {
     const ajv = new Ajv({
       removeAdditional: true,
@@ -210,10 +265,10 @@ export class ResourceContextImpl implements ResourceContext {
 
   /**
    * Create a child EvaluationContext attached to the current module context.
-   * Queue resources on the returned context with pendingResources.push(), then
-   * call initializeChildContext() to initialize them in isolation.
+   * Register resources on the returned context with registerManifest(), then
+   * call initializeResources() to initialize them in isolation.
    */
-  spawnChildContext(): EvaluationContext {
+  spawnChildContext(): IEvaluationContext {
     const child = new EvaluationContext(
       this.moduleContext.source,
       this.moduleContext.context,
@@ -224,7 +279,7 @@ export class ResourceContextImpl implements ResourceContext {
     return this.moduleContext.spawnChild(child);
   }
 
-  transientChild(context: Record<string, any>): EvaluationContext {
+  transientChild(context: Record<string, any>): IEvaluationContext {
     return this.moduleContext.transientChild(context);
   }