@telorun/sdk 0.2.4 → 0.2.5

package/src/evaluation-context.ts

@@ -0,0 +1,337 @@
+import { evaluate } from "cel-js";
+import { ModuleContext } from "./module-context.js";
+import { ResourceInstance } from "./resource-instance.js";
+import { ResourceManifest } from "./resource-manifest.js";
+import { RuntimeError } from "./types.js";
+
+export type EmitEvent = (event: string, payload?: any) => void | Promise<void>;
+
+const TEMPLATE_REGEX = /\$\{\{\s*([^}]+?)\s*\}\}/g;
+const EXACT_TEMPLATE_REGEX = /^\s*\$\{\{\s*([^}]+?)\s*\}\}\s*$/;
+
+/** Four-stage resource lifecycle defined in resource-lifecycle.md */
+export type LifecycleState = "Pending" | "Validated" | "Initialized" | "Draining" | "Teardown";
+
+/**
+ * Creates a ResourceInstance for the given manifest, or returns null if not yet
+ * ready (e.g. a dependency is still initializing). Injected at construction so
+ * every EvaluationContext node owns its full resource lifecycle.
+ */
+export type InstanceFactory = (
+  moduleContext: ModuleContext,
+  resource: ResourceManifest,
+) => Promise<ResourceInstance | null>;
+
+/** Canonical key for a resource instance: "<module>.<kind>.<name>" */
+export function resourceKey(r: ResourceManifest): string {
+  return `${r.kind}.${r.metadata.name}`;
+}
+
+function redactSecrets(message: string, secretValues: Set<string>): string {
+  if (secretValues.size === 0) return message;
+  const sorted = Array.from(secretValues).sort((a, b) => b.length - a.length);
+  let result = message;
+  for (const secret of sorted) {
+    result = result.split(secret).join("[REDACTED]");
+  }
+  return result;
+}
+
+/**
+ * Base class for all evaluation contexts. Owns CEL evaluation, template
+ * expansion, secrets redaction, and the generic resource lifecycle tree.
+ *
+ * Every EvaluationContext node can:
+ *   - Hold its own resource instances (resourceInstances)
+ *   - Queue resources for initialization (pendingResources)
+ *   - Spawn child contexts (spawnChild) forming a lifecycle tree
+ *   - Run a multi-pass initialization loop (initializeResources)
+ *   - Cascade teardown depth-first through the tree (teardownResources)
+ */
+export class EvaluationContext {
+  readonly id = Math.random().toString(16).slice(2, 8);
+  protected _context: Record<string, unknown>;
+  protected _secretValues: Set<string>;
+  protected _createInstance: InstanceFactory;
+  readonly emit: EmitEvent;
+
+  /** Position in the lifecycle tree. */
+  parent: EvaluationContext | undefined = undefined;
+  readonly children: EvaluationContext[] = [];
+
+  /** Current lifecycle state of this context node. */
+  state: LifecycleState = "Pending";
+
+  /** Resource instances owned by this context node, keyed by resourceKey(). */
+  readonly resourceInstances = new Map<
+    string,
+    { resource: ResourceManifest; instance: ResourceInstance }
+  >();
+
+  /** Resources queued for initialization on this context node. */
+  private pendingResources: ResourceManifest[] = [];
+
+  constructor(
+    readonly source: string,
+    context: Record<string, unknown>,
+    createInstance: InstanceFactory = async () => null,
+    secretValues: Set<string>,
+    emit: EmitEvent,
+  ) {
+    this._context = context;
+    this._createInstance = createInstance;
+    this._secretValues = secretValues ?? new Set();
+    this.emit = emit;
+  }
+
+  get createInstance(): InstanceFactory {
+    return this._createInstance;
+  }
+
+  get context(): Record<string, unknown> {
+    return this._context;
+  }
+
+  get secretValues(): Set<string> {
+    return this._secretValues;
+  }
+
+  /**
+   * Queue a resource manifest for initialization on this context.
+   */
+  registerManifest(resource: ResourceManifest): void {
+    if (!resource.metadata) {
+      resource.metadata = { name: `__unnamed_${Math.random().toString(16).slice(2, 8)}` };
+    }
+    this.pendingResources.push(resource);
+  }
+
+  /**
+   * Attach a child context to this node. The child's parent is set to this
+   * context and the child is registered under the given name.
+   */
+  spawnChild<T extends EvaluationContext>(child: T): T {
+    child.parent = this;
+    this.children.push(child);
+    return child;
+  }
+
+  /**
+   * Multi-pass initialization loop. Processes pendingResources by calling the
+   * supplied instantiator for each resource, retrying failures across up to 10
+   * passes (handles dependency ordering without explicit topological sort).
+   *
+   * ERR_VISIBILITY_DENIED errors are fatal and re-thrown immediately.
+   * All other errors are tracked and retried until no progress is made.
+   */
+  async initializeResources(): Promise<void> {
+    const MAX_PASSES = 10;
+    let pass = 1;
+    const errors = new Map<string, string>();
+
+    do {
+      const handled: string[] = [];
+
+      for (const resource of [...this.pendingResources]) {
+        // const rkey = resourceKey(resource);
+        // const displayKey = rkey;
+        const name = resource.metadata.name;
+        if (this.resourceInstances.has(name)) continue;
+
+        try {
+          const instance = await this._createInstance(this as any, resource);
+          if (instance) {
+            this.resourceInstances.set(name, { resource, instance });
+            handled.push(name);
+            errors.delete(name);
+          }
+        } catch (error) {
+          if (error instanceof RuntimeError && error.code === "ERR_VISIBILITY_DENIED") throw error;
+          errors.set(name, error instanceof Error ? (error.stack ?? error.message) : String(error));
+        }
+      }
+
+      for (const name of handled) {
+        const resource = this.pendingResources.find((m) => m.metadata.name === name)!;
+        const idx = this.pendingResources.indexOf(resource);
+        if (idx >= 0) this.pendingResources.splice(idx, 1);
+      }
+
+      pass++;
+      if (handled.length === 0) break;
+    } while (pass <= MAX_PASSES);
+
+    if (this.pendingResources.length > 0) {
+      const unhandledList = this.pendingResources
+        .reverse()
+        .map((r) => `- ${r.metadata.name}: ${errors.get(r.metadata.name) ?? "Unknown error"}`)
+        .join("\n");
+
+      throw new RuntimeError(
+        "ERR_RESOURCE_INITIALIZATION_FAILED",
+        `Unable to process resources:\n\n${unhandledList}`,
+      );
+    }
+
+    this.state = "Initialized";
+  }
+
+  withManifests<T>(manifests: any[], fn: () => T): T {
+    const child = this.spawnChild(
+      new EvaluationContext(
+        this.source,
+        this._context,
+        this._createInstance,
+        this._secretValues,
+        this.emit,
+      ),
+    );
+    try {
+      for (const manifest of manifests) {
+        child.registerManifest(manifest);
+      }
+      return fn();
+    } finally {
+      // Tear down child context and its resources immediately after fn() completes.
+      // Note that this does NOT emit Kernel-level events (e.g. Teardown events) —
+      // they remain the Kernel's responsibility.
+      child.teardownResources();
+    }
+  }
+
+  /**
+   * Cascade teardown depth-first through the tree:
+   *   1. Tear down child contexts in reverse registration order.
+   *   2. Tear down own resource instances in reverse registration order.
+   *
+   * Note: Kernel-level events (e.g. Teardown events) are NOT emitted here —
+   * they remain the Kernel's responsibility.
+   */
+  async teardownResources(): Promise<void> {
+    this.state = "Draining";
+    for (const child of [...this.children].reverse()) {
+      await child.teardownResources();
+    }
+    const entries = [...this.resourceInstances.entries()].reverse();
+    for (const [key, { instance }] of entries) {
+      if (instance.teardown) await instance.teardown();
+      this.resourceInstances.delete(key);
+    }
+    this.state = "Teardown";
+  }
+
+  /**
+   * Invoke a resource by kind and name within this context's resourceInstances.
+   * Emits a scoped Invoked event via the injected emit callback after invocation.
+   */
+  async invoke(kind: string, name: string, ...args: any[]): Promise<any> {
+    const entry = this.resourceInstances.get(name);
+
+    if (entry) {
+      if (typeof entry.instance.invoke !== "function") {
+        throw new RuntimeError(
+          "ERR_RESOURCE_NOT_INVOKABLE",
+          `Resource ${kind}.${name} does not have an invoke method`,
+        );
+      }
+      const outputs = await entry.instance.invoke(args[0]);
+      await this.emit(`${kind}.${name}.Invoked`, { outputs });
+      return outputs;
+    }
+
+    throw new RuntimeError(
+      "ERR_RESOURCE_NOT_FOUND",
+      `Resource not found for invocation: ${kind}.${name}. Available resources: ${[...this.resourceInstances.keys()].join(", ")}`,
+    );
+  }
+
+  async run(name: string): Promise<void> {
+    const entry = this.resourceInstances.get(name);
+    if (entry && typeof entry.instance.run === "function") {
+      return entry.instance.run();
+    }
+    throw new RuntimeError(
+      "ERR_RESOURCE_NOT_RUNNABLE",
+      `Resource ${name} is not runnable or not found. Available resources: ${[...this.resourceInstances.keys()].join(", ")}`,
+    );
+  }
+
+  /**
+   * Evaluate a single CEL expression string against the context.
+   * Secret values are redacted from any thrown error message.
+   */
+  evaluate(expression: string): unknown {
+    try {
+      return evaluate(expression, this._context);
+    } catch (error) {
+      const raw = error instanceof Error ? error.message : String(error);
+      const safe = redactSecrets(raw, this._secretValues);
+      throw new Error(`CEL evaluation failed: "${expression}": ${safe}`);
+    }
+  }
+
+  /**
+   * Expand a value that may contain ${{ }} templates.
+   * Works recursively over strings, arrays, and objects.
+   * Templates whose identifiers are not present in the context are left
+   * unchanged (deferred) — they will be resolved at execution time when a
+   * richer ExecutionContext is available. All other CEL errors are propagated.
+   */
+  expand(value: unknown): unknown {
+    if (typeof value === "string") {
+      return this.expandString(value);
+    }
+    if (Array.isArray(value)) {
+      return value.map((entry) => this.expand(entry));
+    }
+    if (value !== null && typeof value === "object") {
+      const resolved: Record<string, unknown> = {};
+      for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+        resolved[key] = this.expand(entry);
+      }
+      return resolved;
+    }
+    return value;
+  }
+
+  /**
+   * Merge another context on top of this one.
+   * Returns a new base EvaluationContext — 'other' wins on key conflict.
+   */
+  merge(other: EvaluationContext | Record<string, unknown>): EvaluationContext {
+    const otherCtx = other instanceof EvaluationContext ? other.context : other;
+    const otherSecrets =
+      other instanceof EvaluationContext ? other.secretValues : new Set<string>();
+    const merged = Object.assign(Object.create(null), this._context, otherCtx) as Record<
+      string,
+      unknown
+    >;
+    const mergedSecrets = new Set<string>([...this._secretValues, ...otherSecrets]);
+    return new EvaluationContext(
+      this.source,
+      merged,
+      this._createInstance,
+      mergedSecrets,
+      this.emit,
+    );
+  }
+
+  private expandString(value: string): unknown {
+    if (!value.includes("${{")) {
+      return value;
+    }
+
+    const exact = value.match(EXACT_TEMPLATE_REGEX);
+    if (exact) {
+      return this.evaluate(exact[1]);
+    }
+
+    return value.replace(TEMPLATE_REGEX, (_match, expr: string) => {
+      const resolved = this.evaluate(expr);
+      if (resolved === null || resolved === undefined) {
+        return "";
+      }
+      return String(resolved);
+    });
+  }
+}

package/src/execution-context.ts

@@ -0,0 +1,21 @@
+import { EvaluationContext } from "./evaluation-context.js";
+import { ModuleContext } from "./module-context.js";
+
+/**
+ * The ephemeral, per-trigger context layer. Merges a ModuleContext with
+ * arbitrary execution-time properties (e.g. { request, inputs } for HTTP;
+ * any shape is valid — determined by the trigger type).
+ *
+ * Execution props overlay the module namespaces on key conflict.
+ */
+export class ExecutionContext extends EvaluationContext {
+  constructor(moduleCtx: ModuleContext, execProps: Record<string, unknown>) {
+    super(
+      moduleCtx.source,
+      Object.assign(Object.create(null), moduleCtx.context, execProps) as Record<string, unknown>,
+      moduleCtx.createInstance,
+      moduleCtx.secretValues,
+      moduleCtx.emit,
+    );
+  }
+}

package/src/index.ts

@@ -1,9 +1,15 @@
-export * from './controller-context.js';
-export * from './context-provider.js';
-export * from './resource-context.js';
-export * from './resource-instance.js';
-export * from './resource-manifest.js';
-export * from './runtime-error.js';
-export * from './runtime-event.js';
-export * from './runtime-resource.js';
+export * from "./capabilities/invokable.js";
+export * from "./capabilities/provider.js";
+export * from "./capabilities/runnable.js";
+export * from "./context-provider.js";
+export * from "./controller-context.js";
+export * from "./evaluation-context.js";
+export * from "./module-context.js";
+export * from "./resource-context.js";
+export * from "./resource-instance.js";
+export * from "./resource-manifest.js";
+export * from "./runtime-error.js";
+export * from "./runtime-event.js";
+export * from "./runtime-resource.js";
+export * from "./types.js";
 

package/src/module-context.ts

@@ -0,0 +1,187 @@
+import { Invokable } from "./capabilities/invokable.js";
+import { EmitEvent, EvaluationContext, InstanceFactory } from "./evaluation-context.js";
+
+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 {
+  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,
+  ) {
+    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();
+  }
+
+  /**
+   * 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;
+  }
+
+  getInvokable(name: string): Invokable {
+    const instance = this.getInstance(name);
+
+    if (
+      instance &&
+      typeof instance === "object" &&
+      "invoke" in instance &&
+      typeof instance.invoke !== "function"
+    ) {
+      throw new Error(`Resource '${name}' does not have an invoke() method.`);
+    }
+    return instance as Invokable;
+  }
+
+  /**
+   * 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._secretValues = collectSecretValues(this._secrets);
+  }
+
+  override async invoke(kind: string, name: string, ...args: any[]): Promise<any> {
+    const result = await super.invoke(kind, name, ...args);
+    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,4 +1,6 @@
 import { ControllerContext } from "./controller-context.js";
+import { EvaluationContext } from "./evaluation-context.js";
+import { ModuleContext } from "./module-context.js";
 import { RuntimeResource } from "./runtime-resource.js";
 
 export interface DataValidator {
@@ -20,22 +22,26 @@ export interface ResourceContext extends ControllerContext {
   acquireHold(reason?: string): () => void;
   emitEvent(event: string, payload?: any): Promise<void>;
   invoke(kind: string, name: string, ...args: any[]): Promise<any>;
+  run(kind: string, name: string): Promise<void>;
   getResources(kind: string): RuntimeResource[];
   getResourcesByName(kind: string, name: string): RuntimeResource | null;
   registerManifest(resource: any): void;
+  spawnChildContext(): EvaluationContext;
+  withManifests<T>(manifests: any[], fn: () => T): T;
   resolveChildren(resource: any, resourceName?: string): { kind: string; name: string };
   validateSchema(value: any, schema: any): void;
   createSchemaValidator(schema: any): DataValidator;
   registerSchema(name: string, schema: object): void;
   lookupSchema(name: string): object | undefined;
-  registerController(
-    moduleName: string,
-    kindName: string,
-    controllerInstance: any,
-  ): Promise<void>;
+  registerController(moduleName: string, kindName: string, controllerInstance: any): Promise<void>;
   registerDefinition(definition: any): void;
+  registerModuleImport(alias: string, targetModule: string, kinds: string[]): void;
   registerCapability(name: string, schema?: Record<string, any>): void;
   isCapabilityRegistered(name: string): boolean;
   getCapabilitySchema(name: string): Record<string, any> | null | undefined;
   teardownResource(kind: string, name: string): Promise<void>;
+  moduleContext: ModuleContext;
+  stdin: NodeJS.ReadableStream;
+  stdout: NodeJS.WritableStream;
+  stderr: NodeJS.WritableStream;
 }

package/src/resource-manifest.ts

@@ -5,7 +5,7 @@ export interface ResourceManifest {
   kind: string;
   metadata: {
     name: string;
-    module: string;
+    module?: string;
     [key: string]: any;
   };
   [key: string]: any;

package/src/runtime-error.ts

@@ -1,9 +1,12 @@
 export type RuntimeErrorCode =
-  | 'ERR_RESOURCE_NOT_FOUND'
-  | 'ERR_CONTROLLER_NOT_FOUND'
-  | 'ERR_CONTROLLER_INVALID'
-  | 'ERR_RESOURCE_NOT_INVOKABLE'
-  | 'ERR_DUPLICATE_RESOURCE'
-  | 'ERR_EXECUTION_FAILED'
-  | 'ERR_INVALID_VALUE'
-  | 'ERR_VISIBILITY_DENIED';
+  | "ERR_RESOURCE_NOT_FOUND"
+  | "ERR_RESOURCE_NOT_RUNNABLE"
+  | "ERR_CONTROLLER_NOT_FOUND"
+  | "ERR_CONTROLLER_INVALID"
+  | "ERR_RESOURCE_INITIALIZATION_FAILED"
+  | "ERR_RESOURCE_NOT_INVOKABLE"
+  | "ERR_RESOURCE_SCHEMA_VALIDATION_FAILED"
+  | "ERR_DUPLICATE_RESOURCE"
+  | "ERR_EXECUTION_FAILED"
+  | "ERR_INVALID_VALUE"
+  | "ERR_VISIBILITY_DENIED";