@telorun/kernel 0.11.1 → 0.13.0

package/dist/snapshot-serializer.js

@@ -0,0 +1,164 @@
+import * as fs from "fs/promises";
+import * as YAML from "js-yaml";
+import * as path from "path";
+/**
+ * Serializes runtime state into YAML snapshots
+ * Captures resource definitions, instances, and custom state
+ * Recursively includes nested resources based on generationDepth
+ */
+export class SnapshotSerializer {
+    /**
+     * Take a snapshot of runtime state
+     * @param resources Map of resources organized by kind
+     * @param resourceInstances Map of resource instances to include custom snapshots
+     * @param filePath Optional file path to write snapshot to
+     * @returns Snapshot data object
+     */
+    async takeSnapshot(resources, resourceInstances, filePath) {
+        const snapshot = {
+            timestamp: new Date().toISOString(),
+            resources: [],
+        };
+        // Get all resources organized by generation depth (0 = first level)
+        // Start with depth 0 (directly loaded resources) and recursively include nested ones
+        const resourcesByDepth = this.groupByGenerationDepth(resources);
+        // Process resources starting from depth 0
+        for (const depth of Array.from(resourcesByDepth.keys()).sort((a, b) => a - b)) {
+            const resourcesAtDepth = resourcesByDepth.get(depth) || [];
+            for (const resource of resourcesAtDepth) {
+                const resourceEntry = await this.serializeResource(resource, resourceInstances);
+                snapshot.resources.push(resourceEntry);
+            }
+        }
+        // Write to file if path provided
+        if (filePath) {
+            await this.writeSnapshotToFile(snapshot, filePath);
+        }
+        return snapshot;
+    }
+    /**
+     * Serialize a single resource
+     */
+    async serializeResource(resource, resourceInstances) {
+        const { kind, metadata, ...data } = resource;
+        const { name } = metadata;
+        const resourceEntry = {
+            kind,
+            name,
+            metadata: this.serializeMetadata(metadata),
+            data: this.serializeData(data),
+        };
+        // Include custom snapshot if resource instance has snapshot() method
+        if (resourceInstances) {
+            const key = this.getResourceKey(kind, name);
+            const instanceData = resourceInstances.get(key);
+            if (instanceData && instanceData.instance) {
+                const snapshotData = await this.getInstanceSnapshot(instanceData.instance);
+                if (snapshotData) {
+                    resourceEntry.snapshot = snapshotData;
+                }
+            }
+        }
+        return resourceEntry;
+    }
+    /**
+     * Get snapshot from resource instance if it implements snapshot() method
+     */
+    async getInstanceSnapshot(instance) {
+        const instanceAny = instance;
+        // Check if snapshot method exists
+        if (typeof instanceAny.snapshot === "function") {
+            try {
+                const result = await Promise.resolve(instanceAny.snapshot(instance));
+                return result;
+            }
+            catch (error) {
+                console.error("Error calling snapshot() on resource instance:", error);
+                return null;
+            }
+        }
+        return null;
+    }
+    /**
+     * Serialize metadata, filtering out circular references and functions
+     */
+    serializeMetadata(metadata) {
+        const serialized = {};
+        for (const [key, value] of Object.entries(metadata)) {
+            if (typeof value === "function") {
+                continue;
+            }
+            try {
+                serialized[key] = JSON.parse(JSON.stringify(value));
+            }
+            catch {
+                // Skip non-serializable values
+            }
+        }
+        return serialized;
+    }
+    /**
+     * Serialize resource data, filtering out circular references and functions
+     */
+    serializeData(data) {
+        const serialized = {};
+        for (const [key, value] of Object.entries(data)) {
+            if (typeof value === "function") {
+                continue;
+            }
+            try {
+                serialized[key] = JSON.parse(JSON.stringify(value));
+            }
+            catch {
+                // Skip non-serializable values
+            }
+        }
+        return serialized;
+    }
+    /**
+     * Group resources by generation depth for hierarchical ordering
+     */
+    groupByGenerationDepth(resources) {
+        const grouped = new Map();
+        for (const kindMap of resources.values()) {
+            for (const resource of kindMap.values()) {
+                const depth = resource.metadata.generationDepth ?? 0;
+                if (!grouped.has(depth)) {
+                    grouped.set(depth, []);
+                }
+                grouped.get(depth).push(resource);
+            }
+        }
+        return grouped;
+    }
+    /**
+     * Write snapshot to YAML file
+     */
+    async writeSnapshotToFile(snapshot, filePath) {
+        // Ensure directory exists
+        const dir = path.dirname(filePath);
+        if (dir !== "." && dir !== "") {
+            await fs.mkdir(dir, { recursive: true });
+        }
+        // Convert to YAML
+        const yaml = YAML.dump(snapshot, {
+            indent: 2,
+            lineWidth: 0,
+        });
+        await fs.writeFile(filePath, yaml, "utf-8");
+    }
+    /**
+     * Generate resource key for instance lookup
+     */
+    getResourceKey(kind, name) {
+        return `${kind}:${name}`;
+    }
+    /**
+     * Load snapshot from YAML file
+     */
+    async loadSnapshotFromFile(filePath) {
+        const content = await fs.readFile(filePath, "utf-8");
+        return YAML.load(content);
+    }
+}
+//# sourceMappingURL=snapshot-serializer.js.map

package/dist/snapshot-serializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-serializer.js","sourceRoot":"","sources":["../src/snapshot-serializer.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,65 @@
+import type { ControllerContext, ResourceContext, ResourceInstance, ResourceManifest, RuntimeErrorCode, RuntimeResource } from "@telorun/sdk";
+import type { ModuleContext } from "./module-context.js";
+export type { ControllerContext, ResourceContext, ResourceInstance, ResourceManifest } from "@telorun/sdk";
+export interface KernelContext {
+    kernel: Kernel;
+}
+export interface ExecContext {
+    execute(urn: string, input: any): Promise<any>;
+    [key: string]: any;
+}
+export type ResourceCapability = string;
+export interface ResourceDefinition {
+    kind: string;
+    metadata: {
+        name: string;
+        module: string;
+    };
+    schema: Record<string, any>;
+    capabilities: ResourceCapability[];
+    events?: string[];
+    controllers?: Array<{
+        runtime: string;
+        entry: string;
+    }>;
+}
+/**
+ * Controller definition for a resource kind.
+ * Maps a fully-qualified resource kind to its controller implementation for a specific runtime.
+ */
+export interface ControllerDefinition {
+    kind: string;
+    runtime: string;
+    entry: string;
+    controller?: any;
+}
+/**
+ * Controller instance - runtime representation of a controller that handles resource instances.
+ */
+export interface ControllerInstance {
+    execute?(name: string, inputs: any, ctx: ExecContext): Promise<any>;
+    compile?(resource: ResourceManifest, ctx: ResourceContext): RuntimeResource | Promise<RuntimeResource>;
+    register?(ctx: ControllerContext): void | Promise<void>;
+    create?(resource: ResourceManifest, ctx: ResourceContext): ResourceInstance | null | Promise<ResourceInstance | null>;
+    schema: any;
+}
+export interface Kernel {
+    loadFromConfig(runtimeYamlPath: string): Promise<void>;
+    start(): Promise<void>;
+    acquireHold(reason?: string): () => void;
+    waitForIdle(): Promise<void>;
+    requestExit(code: number): void;
+    readonly exitCode: number;
+    teardownResource(module: string, kind: string, name: string): Promise<void>;
+    registerChildManifest(parentKey: string, resource: ResourceManifest): void;
+    getSourceFiles(): string[];
+    reloadSource(sourcePath: string): Promise<void>;
+    shutdown(): void;
+    registerModuleContext(moduleName: string, variables: Record<string, unknown>, secrets: Record<string, unknown>): void;
+    getModuleContext(moduleName: string): ModuleContext;
+}
+export declare class RuntimeError extends Error {
+    code: RuntimeErrorCode;
+    constructor(code: RuntimeErrorCode, message: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,8 @@
+export class RuntimeError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "RuntimeError";
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA0FA,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YACS,IAAsB,EAC7B,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHR,SAAI,GAAJ,IAAI,CAAkB;QAI7B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF"}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@telorun/kernel",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "description": "Telo Runtime - A lightweight, polyglot execution host.",
   "keywords": [
-    "digly",
+    "telo",
     "runtime",
     "execution",
     "manifest"
@@ -47,8 +47,8 @@
   "dependencies": {
     "@marcbachmann/cel-js": "^7.5.3",
     "@sinclair/typebox": "^0.34.48",
-    "@telorun/analyzer": "0.10.1",
-    "@telorun/sdk": "0.11.1",
+    "@telorun/analyzer": "0.12.0",
+    "@telorun/templating": "0.3.0",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "minimatch": "^10.2.5",
@@ -60,11 +60,14 @@
     "typescript": "^5.0.0",
     "vitest": "^2.1.8"
   },
+  "peerDependencies": {
+    "@telorun/sdk": "0.12.0"
+  },
   "overrides": {
     "@marcbachmann/cel-js": "$@marcbachmann/cel-js",
     "@sinclair/typebox": "$@sinclair/typebox",
     "@telorun/analyzer": "$@telorun/analyzer",
-    "@telorun/sdk": "$@telorun/sdk",
+    "@telorun/templating": "$@telorun/templating",
     "ajv": "$ajv",
     "ajv-formats": "$ajv-formats",
     "minimatch": "$minimatch",
@@ -72,7 +75,7 @@
     "yaml": "$yaml"
   },
   "scripts": {
-    "build": "tsc && node ../../scripts/generate-runtime-deps.mjs .",
+    "build": "tsc",
     "dev": "tsc --watch",
     "test": "vitest run",
     "test:watch": "vitest"

package/src/application-env.ts

@@ -0,0 +1,216 @@
+import { residualEntrySchema } from "@telorun/analyzer";
+import { RuntimeError } from "@telorun/sdk";
+import { SchemaValidator } from "./schema-validator.js";
+
+type EntryType = "string" | "integer" | "number" | "boolean" | "object" | "array";
+
+interface EnvEntry {
+  env: string;
+  type: EntryType;
+  default?: unknown;
+  [key: string]: unknown;
+}
+
+export interface EnvResolutionResult {
+  variables: Record<string, unknown>;
+  secrets: Record<string, unknown>;
+}
+
+/**
+ * Populate the root Application's `variables` / `secrets` namespaces from
+ * host environment variables, per the per-field `env:` mapping declared on
+ * each entry.
+ *
+ * Implements the polyglot env-resolution spec from
+ * kernel/nodejs/plans/application-env-variables.md: read the env var, coerce
+ * per `entry.type`, validate the coerced value (or the declared default, when
+ * the env var is unset) against the entry's residual schema, and aggregate
+ * every failure into a single `ERR_MANIFEST_VALIDATION_FAILED` error so all
+ * problems surface before any controller initializes.
+ *
+ * This must run BEFORE any Telo.Import controller initializes — imports may
+ * pass `${{ variables.X }}` as their `variables:` inputs, so the root scope
+ * has to be populated by the time the import controller evaluates those
+ * expressions.
+ */
+export function resolveApplicationEnv(
+  manifest: Record<string, any>,
+  env: Record<string, string | undefined>,
+  validator: SchemaValidator,
+): EnvResolutionResult {
+  const errors: string[] = [];
+  const variables = resolveBlock(
+    manifest.variables ?? {},
+    env,
+    validator,
+    errors,
+    false,
+  );
+  const secrets = resolveBlock(
+    manifest.secrets ?? {},
+    env,
+    validator,
+    errors,
+    true,
+  );
+  if (errors.length > 0) {
+    throw new RuntimeError(
+      "ERR_MANIFEST_VALIDATION_FAILED",
+      `Application environment validation failed:\n` +
+        errors.map((e) => `  - ${e}`).join("\n"),
+    );
+  }
+  return { variables, secrets };
+}
+
+function resolveBlock(
+  block: Record<string, EnvEntry> | unknown,
+  env: Record<string, string | undefined>,
+  validator: SchemaValidator,
+  errors: string[],
+  isSecret: boolean,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (!block || typeof block !== "object" || Array.isArray(block)) {
+    return out;
+  }
+  for (const [name, entry] of Object.entries(block as Record<string, EnvEntry>)) {
+    if (!entry || typeof entry !== "object") continue;
+    const envKey = entry.env;
+    const raw = env[envKey];
+    const residual = residualEntrySchema(entry as Record<string, unknown>);
+
+    if (raw === undefined || raw === null) {
+      if (entry.default !== undefined) {
+        const validation = validateResidual(entry.default, residual, validator);
+        if (validation) {
+          errors.push(`${name}: ${validation}`);
+        } else {
+          out[name] = entry.default;
+        }
+        continue;
+      }
+      errors.push(`${name}: environment variable ${envKey} is not set (no default)`);
+      continue;
+    }
+
+    let coerced: unknown;
+    try {
+      coerced = coerce(raw, entry.type, envKey, isSecret);
+    } catch (e) {
+      errors.push(`${name}: ${(e as Error).message}`);
+      continue;
+    }
+
+    const validation = validateResidual(coerced, residual, validator);
+    if (validation) {
+      errors.push(`${name}: ${validation}`);
+      continue;
+    }
+
+    out[name] = coerced;
+  }
+  return out;
+}
+
+/** Render a raw env value for inclusion in an error message. Secret values
+ *  are masked so coercion / schema diagnostics don't leak secret material
+ *  into logs (the env-var name and the failure reason still surface). */
+function renderRawForError(raw: string, isSecret: boolean): string {
+  return isSecret ? "<redacted>" : `"${raw}"`;
+}
+
+function coerce(
+  raw: string,
+  type: EntryType,
+  envKey: string,
+  isSecret: boolean,
+): unknown {
+  switch (type) {
+    case "string":
+      return raw;
+    case "integer": {
+      const trimmed = raw.trim();
+      if (!/^-?\d+$/.test(trimmed)) {
+        throw new Error(
+          `environment variable ${envKey}: value ${renderRawForError(raw, isSecret)} is not a valid integer`,
+        );
+      }
+      return parseInt(trimmed, 10);
+    }
+    case "number": {
+      const n = parseFloat(raw);
+      if (Number.isNaN(n)) {
+        throw new Error(
+          `environment variable ${envKey}: value ${renderRawForError(raw, isSecret)} is not a valid number`,
+        );
+      }
+      return n;
+    }
+    case "boolean":
+      if (raw === "true") return true;
+      if (raw === "false") return false;
+      throw new Error(
+        `environment variable ${envKey}: value ${renderRawForError(raw, isSecret)} is not a valid boolean (expected "true" or "false")`,
+      );
+    case "object": {
+      const parsed = parseJson(raw, envKey, isSecret);
+      if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(
+          `environment variable ${envKey}: expected JSON object, got ${describeJsonType(parsed)}`,
+        );
+      }
+      return parsed;
+    }
+    case "array": {
+      const parsed = parseJson(raw, envKey, isSecret);
+      if (!Array.isArray(parsed)) {
+        throw new Error(
+          `environment variable ${envKey}: expected JSON array, got ${describeJsonType(parsed)}`,
+        );
+      }
+      return parsed;
+    }
+  }
+}
+
+function parseJson(raw: string, envKey: string, isSecret: boolean): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    // Node's JSON.parse error embeds the offending character / position; for
+    // secrets, swallow the parser detail and surface only the env var name.
+    const detail = isSecret ? "value is not valid JSON" : (e as Error).message;
+    throw new Error(`environment variable ${envKey}: ${isSecret ? detail : `value is not valid JSON: ${detail}`}`);
+  }
+}
+
+function describeJsonType(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
+function validateResidual(
+  value: unknown,
+  residual: Record<string, unknown>,
+  validator: SchemaValidator,
+): string | null {
+  try {
+    validator.compile(residual as any).validate(value);
+    return null;
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    // Strip SchemaValidator's "Invalid value passed: <JSON>. Error: " prefix
+    // so the JSON-stringified value (which can be secret material for entries
+    // under `secrets:`) never reaches the caller. The split is anchored on
+    // the literal ". Error: " delimiter — a `[^.]*` regex would have leaked
+    // any value containing a dot (URLs, versions, paths).
+    const sentinel = ". Error: ";
+    const idx = msg.indexOf(sentinel);
+    if (msg.startsWith("Invalid value passed:") && idx !== -1) {
+      return msg.slice(idx + sentinel.length);
+    }
+    return msg;
+  }
+}