@telorun/templating 0.2.0

package/dist/engine.d.ts

@@ -0,0 +1,47 @@
+import type { Environment } from "@marcbachmann/cel-js";
+import type { CompiledValue } from "@telorun/sdk";
+/** Compile-time environment passed to `engine.compile`. Engines that need to
+ *  parse against a CEL environment (the `cel` engine) read it from `celEnv`;
+ *  engines that resolve fully at compile time (`literal`) ignore it. */
+export interface CompileEnv {
+    readonly celEnv: Environment;
+}
+/** Analyze-time environment passed to `engine.analyze`. The walker resolves
+ *  the path-specific effective context (kernel globals merged in, x-telo-context
+ *  applied) and hands the engine a single closed schema. The engine validates
+ *  member-access chains against it. `null` means "open context" — no chain
+ *  validation possible. */
+export interface AnalyzeEnv {
+    readonly celEnv: Environment;
+    readonly contextSchema: Record<string, unknown> | null;
+}
+/** A single static-analysis finding produced by an engine. Stable codes match
+ *  the analyzer's existing diagnostic codes so downstream filtering keeps
+ *  working unchanged across the engine boundary. */
+export interface EngineDiagnostic {
+    readonly message: string;
+    readonly code?: string;
+}
+/** Per-property templating engine. Matches a YAML tag (`!<name>`); the kernel
+ *  and analyzer dispatch through the registry rather than knowing about
+ *  specific engines. */
+export interface TemplatingEngine {
+    /** Registry key matching the YAML tag name (without `!`). */
+    readonly name: string;
+    /** Optional Monaco language id for editor syntax highlighting. Currently
+     *  unread — the editor's CelFieldWrapper uses a plain `<input>`. Wiring
+     *  this through to a Monaco editor instance is tracked separately; the
+     *  field is documented intent so engine authors don't have to revisit
+     *  the interface when Monaco lands.
+     *  TODO(editor): consume `engine.language` from the field renderer. */
+    readonly language?: string;
+    /** Convert a tagged source string into a runtime value. Called once at
+     *  precompile. Returns either a CompiledValue (engines that defer evaluation
+     *  to a runtime EvalContext, like `cel`) or a plain value (engines like
+     *  `literal` that resolve fully at compile time). */
+    compile(source: string, env: CompileEnv): CompiledValue | unknown;
+    /** Static analysis hook. Engines that can't statically check (e.g. `literal`)
+     *  return []. The walker accumulates diagnostics across all values. */
+    analyze(source: string, env: AnalyzeEnv): readonly EngineDiagnostic[];
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;wEAEwE;AACxE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED;;;;2BAI2B;AAC3B,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACxD;AAED;;oDAEoD;AACpD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;wBAEwB;AACxB,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;2EAKuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;;yDAGqD;IACrD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,aAAa,GAAG,OAAO,CAAC;IAElE;2EACuE;IACvE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,SAAS,gBAAgB,EAAE,CAAC;CACvE"}

package/dist/engine.js

@@ -0,0 +1 @@
+export {};

package/dist/engines/cel.d.ts

@@ -0,0 +1,7 @@
+import type { TemplatingEngine } from "../engine.js";
+/** The `!cel` engine. Treats the entire tagged scalar as a single CEL
+ *  expression — no `${{ }}` wrapping. Analysis runs the same chain validator
+ *  as the untagged path: parse → extract member-access chains → validate each
+ *  chain against the effective context schema. */
+export declare const celEngine: TemplatingEngine;
+//# sourceMappingURL=cel.d.ts.map

package/dist/engines/cel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cel.d.ts","sourceRoot":"","sources":["../../src/engines/cel.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAoB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEvE;;;kDAGkD;AAClD,eAAO,MAAM,SAAS,EAAE,gBA+BvB,CAAC"}

package/dist/engines/cel.js

@@ -0,0 +1,36 @@
+import { extractAccessChains, validateChainAgainstSchema } from "../cel/analyze.js";
+import { compileExpression } from "../cel/compile.js";
+/** The `!cel` engine. Treats the entire tagged scalar as a single CEL
+ *  expression — no `${{ }}` wrapping. Analysis runs the same chain validator
+ *  as the untagged path: parse → extract member-access chains → validate each
+ *  chain against the effective context schema. */
+export const celEngine = {
+    name: "cel",
+    language: "cel",
+    compile(source, env) {
+        return compileExpression(source, env.celEnv);
+    },
+    analyze(source, env) {
+        const out = [];
+        let parsed;
+        try {
+            parsed = env.celEnv.parse(source);
+        }
+        catch (e) {
+            out.push({
+                code: "CEL_SYNTAX_ERROR",
+                message: e instanceof Error ? e.message : String(e),
+            });
+            return out;
+        }
+        if (!env.contextSchema)
+            return out;
+        const chains = extractAccessChains(parsed.ast);
+        for (const chain of chains) {
+            const err = validateChainAgainstSchema(chain, env.contextSchema);
+            if (err)
+                out.push({ code: "CEL_UNKNOWN_FIELD", message: err });
+        }
+        return out;
+    },
+};

package/dist/engines/literal.d.ts

@@ -0,0 +1,6 @@
+import type { TemplatingEngine } from "../engine.js";
+/** The `!literal` engine. Treats the tagged scalar as opaque text — no CEL
+ *  interpolation, no analysis. Returns the source string verbatim at compile
+ *  time so the runtime sees a plain string. */
+export declare const literalEngine: TemplatingEngine;
+//# sourceMappingURL=literal.d.ts.map

package/dist/engines/literal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"literal.d.ts","sourceRoot":"","sources":["../../src/engines/literal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD;;+CAE+C;AAC/C,eAAO,MAAM,aAAa,EAAE,gBAU3B,CAAC"}

package/dist/engines/literal.js

@@ -0,0 +1,12 @@
+/** The `!literal` engine. Treats the tagged scalar as opaque text — no CEL
+ *  interpolation, no analysis. Returns the source string verbatim at compile
+ *  time so the runtime sees a plain string. */
+export const literalEngine = {
+    name: "literal",
+    compile(source) {
+        return source;
+    },
+    analyze() {
+        return [];
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { buildCelEnvironment, type CelHandlers } from "./cel/environment.js";
+export { compileExpression, compileString, TEMPLATE_REGEX, EXACT_TEMPLATE_REGEX, } from "./cel/compile.js";
+export { extractAccessChains, validateChainAgainstSchema } from "./cel/analyze.js";
+export { walkCelExpressions } from "./cel/walk.js";
+export { celEngine } from "./engines/cel.js";
+export { literalEngine } from "./engines/literal.js";
+export { TemplatingEngineRegistry } from "./registry.js";
+export { builtinEngines, createDefaultRegistry, defaultRegistry } from "./builtins.js";
+export type { AnalyzeEnv, CompileEnv, EngineDiagnostic, TemplatingEngine, } from "./engine.js";
+export { isTaggedSentinel, makeTaggedSentinel, type TaggedSentinel } from "./sentinel.js";
+export { buildCustomTags, defaultCustomTags } from "./yaml-tags.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AACnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACvF,YAAY,EACV,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAC1F,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+export { buildCelEnvironment } from "./cel/environment.js";
+export { compileExpression, compileString, TEMPLATE_REGEX, EXACT_TEMPLATE_REGEX, } from "./cel/compile.js";
+export { extractAccessChains, validateChainAgainstSchema } from "./cel/analyze.js";
+export { walkCelExpressions } from "./cel/walk.js";
+export { celEngine } from "./engines/cel.js";
+export { literalEngine } from "./engines/literal.js";
+export { TemplatingEngineRegistry } from "./registry.js";
+export { builtinEngines, createDefaultRegistry, defaultRegistry } from "./builtins.js";
+export { isTaggedSentinel, makeTaggedSentinel } from "./sentinel.js";
+export { buildCustomTags, defaultCustomTags } from "./yaml-tags.js";

package/dist/registry.d.ts

@@ -0,0 +1,10 @@
+import type { TemplatingEngine } from "./engine.js";
+export declare class TemplatingEngineRegistry {
+    private readonly engines;
+    register(engine: TemplatingEngine): void;
+    get(name: string): TemplatingEngine | undefined;
+    has(name: string): boolean;
+    /** All registered engines in registration order. */
+    list(): readonly TemplatingEngine[];
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAE/D,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAOxC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAI/C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,oDAAoD;IACpD,IAAI,IAAI,SAAS,gBAAgB,EAAE;CAGpC"}

package/dist/registry.js

@@ -0,0 +1,19 @@
+export class TemplatingEngineRegistry {
+    engines = new Map();
+    register(engine) {
+        if (this.engines.has(engine.name)) {
+            throw new Error(`Templating engine '${engine.name}' is already registered.`);
+        }
+        this.engines.set(engine.name, engine);
+    }
+    get(name) {
+        return this.engines.get(name);
+    }
+    has(name) {
+        return this.engines.has(name);
+    }
+    /** All registered engines in registration order. */
+    list() {
+        return [...this.engines.values()];
+    }
+}

package/dist/sentinel.d.ts

@@ -0,0 +1,14 @@
+/** Sentinel object produced by the YAML loader for a tagged scalar (e.g. `!cel
+ *  'variables.port'`). Travels through the manifest tree as the parsed value;
+ *  precompile and the analyzer key off `__tagged === true` to dispatch to the
+ *  right engine. The object is intentionally a plain JSON-shaped record so it
+ *  survives `Document.toJSON()` and `JSON.parse(JSON.stringify(...))` without
+ *  loss. */
+export interface TaggedSentinel {
+    readonly __tagged: true;
+    readonly engine: string;
+    readonly source: string;
+}
+export declare function isTaggedSentinel(v: unknown): v is TaggedSentinel;
+export declare function makeTaggedSentinel(engine: string, source: string): TaggedSentinel;
+//# sourceMappingURL=sentinel.d.ts.map

package/dist/sentinel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentinel.d.ts","sourceRoot":"","sources":["../src/sentinel.ts"],"names":[],"mappings":"AAAA;;;;;YAKY;AACZ,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,cAAc,CAQhE;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,CAEjF"}

package/dist/sentinel.js

@@ -0,0 +1,10 @@
+export function isTaggedSentinel(v) {
+    return (v !== null &&
+        typeof v === "object" &&
+        v.__tagged === true &&
+        typeof v.engine === "string" &&
+        typeof v.source === "string");
+}
+export function makeTaggedSentinel(engine, source) {
+    return { __tagged: true, engine, source };
+}

package/dist/yaml-tags.d.ts

@@ -0,0 +1,28 @@
+import type { ScalarTag } from "yaml";
+import type { TemplatingEngineRegistry } from "./registry.js";
+/** Build the `customTags` array passed to `yaml`'s `parseAllDocuments` /
+ *  `Document` from the registered engines. Each engine contributes one
+ *  ScalarTag whose `resolve` produces a `TaggedSentinel`, and whose
+ *  `identify` + `stringify` round-trip the sentinel back to its original
+ *  `!<engine> "<source>"` form when the document is re-serialized.
+ *
+ *  Without `stringify`, `Document.toString()` would emit the sentinel as a
+ *  YAML mapping (`{__tagged: true, engine: cel, source: ...}`), corrupting
+ *  the file on the editor's first save. Without `identify`, the serializer
+ *  wouldn't know to use the custom tag at all and would fall through to
+ *  default object serialization.
+ *
+ *  Single source of truth: every `parseAllDocuments` call site in the repo
+ *  calls this factory so the parse-side configuration cannot drift between
+ *  hosts. Each host passes its own registry (in practice always
+ *  `createDefaultRegistry()`), keeping the door open for future
+ *  test-only registries. */
+export declare function buildCustomTags(registry: TemplatingEngineRegistry): ScalarTag[];
+/** Returns `customTags` built from the default registry, freshly each call.
+ *  Every `parseAllDocuments` call site in the repo calls this so they all
+ *  parse the same set of tags. Built from `defaultRegistry()` (the same
+ *  singleton precompile + the analyzer use) so registering a new engine on
+ *  the default registry propagates to YAML parsing on the next call. The
+ *  rebuild cost is negligible (one array of N small ScalarTag objects). */
+export declare function defaultCustomTags(): ScalarTag[];
+//# sourceMappingURL=yaml-tags.d.ts.map

package/dist/yaml-tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml-tags.d.ts","sourceRoot":"","sources":["../src/yaml-tags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAItC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAE9D;;;;;;;;;;;;;;;;4BAgB4B;AAC5B,wBAAgB,eAAe,CAAC,QAAQ,EAAE,wBAAwB,GAAG,SAAS,EAAE,CAE/E;AAED;;;;;2EAK2E;AAC3E,wBAAgB,iBAAiB,IAAI,SAAS,EAAE,CAE/C"}

package/dist/yaml-tags.js

@@ -0,0 +1,61 @@
+import { stringifyString } from "yaml/util";
+import { defaultRegistry } from "./builtins.js";
+import { isTaggedSentinel, makeTaggedSentinel } from "./sentinel.js";
+/** Build the `customTags` array passed to `yaml`'s `parseAllDocuments` /
+ *  `Document` from the registered engines. Each engine contributes one
+ *  ScalarTag whose `resolve` produces a `TaggedSentinel`, and whose
+ *  `identify` + `stringify` round-trip the sentinel back to its original
+ *  `!<engine> "<source>"` form when the document is re-serialized.
+ *
+ *  Without `stringify`, `Document.toString()` would emit the sentinel as a
+ *  YAML mapping (`{__tagged: true, engine: cel, source: ...}`), corrupting
+ *  the file on the editor's first save. Without `identify`, the serializer
+ *  wouldn't know to use the custom tag at all and would fall through to
+ *  default object serialization.
+ *
+ *  Single source of truth: every `parseAllDocuments` call site in the repo
+ *  calls this factory so the parse-side configuration cannot drift between
+ *  hosts. Each host passes its own registry (in practice always
+ *  `createDefaultRegistry()`), keeping the door open for future
+ *  test-only registries. */
+export function buildCustomTags(registry) {
+    return registry.list().map((engine) => buildTagForEngine(engine.name));
+}
+/** Returns `customTags` built from the default registry, freshly each call.
+ *  Every `parseAllDocuments` call site in the repo calls this so they all
+ *  parse the same set of tags. Built from `defaultRegistry()` (the same
+ *  singleton precompile + the analyzer use) so registering a new engine on
+ *  the default registry propagates to YAML parsing on the next call. The
+ *  rebuild cost is negligible (one array of N small ScalarTag objects). */
+export function defaultCustomTags() {
+    return buildCustomTags(defaultRegistry());
+}
+function buildTagForEngine(engineName) {
+    const tagId = `!${engineName}`;
+    return {
+        tag: tagId,
+        resolve: (value) => makeTaggedSentinel(engineName, value),
+        identify: (v) => isTaggedSentinel(v) && v.engine === engineName,
+        stringify(item, ctx, onComment, onChompKeep) {
+            // Two paths reach this function:
+            // 1. Parsed-then-serialized: the resolver produced a TaggedSentinel
+            //    and we recover the original `source` from it; the original
+            //    Scalar carries the user's chosen quoting style on `item.type`,
+            //    which we pass through so single-quoted stays single-quoted.
+            // 2. setTag applied to an existing scalar: the underlying value is a
+            //    plain primitive (string/number/boolean) — coerce to string and
+            //    let yaml's stringifier pick a safe default style.
+            // Either way, delegate to yaml's `stringifyString` so newlines, tabs,
+            // control characters, leading-whitespace lines, and multi-line content
+            // are all escaped/quoted correctly. The yaml lib emits the tag prefix
+            // itself; this only returns the scalar body.
+            const value = item.value;
+            const source = isTaggedSentinel(value)
+                ? value.source
+                : value === null || value === undefined
+                    ? ""
+                    : String(value);
+            return stringifyString({ value: source, type: item.type }, ctx, onComment, onChompKeep);
+        },
+    };
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@telorun/templating",
+  "version": "0.2.0",
+  "description": "Telo Templating - Engine registry and shared CEL core for Telo manifests.",
+  "keywords": [
+    "telo",
+    "templating",
+    "cel",
+    "yaml"
+  ],
+  "author": "Bartosz Pasiński <bartosz.pasinski@codenet.pl>",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/telorun/telo.git",
+    "directory": "templating/nodejs"
+  },
+  "homepage": "https://github.com/telorun/telo#readme",
+  "bugs": {
+    "url": "https://github.com/telorun/telo/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**",
+    "src/**"
+  ],
+  "dependencies": {
+    "@marcbachmann/cel-js": "^7.5.3",
+    "yaml": "^2.8.3",
+    "@telorun/sdk": "0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.lib.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/builtins.ts

@@ -0,0 +1,33 @@
+import { celEngine } from "./engines/cel.js";
+import { literalEngine } from "./engines/literal.js";
+import { TemplatingEngineRegistry } from "./registry.js";
+import type { TemplatingEngine } from "./engine.js";
+
+/** Single source of truth for the built-in templating engines. Every host
+ *  (kernel, analyzer, editor, vscode extension) calls `createDefaultRegistry`
+ *  so the parse-side YAML tag set, the precompile dispatch, and the analyzer
+ *  agree on which engines exist. Per-host à-la-carte registration would let
+ *  a manifest validate clean in one host (e.g. `cel` only) and crash in
+ *  another (e.g. `cel + literal`); always ship the same set. */
+export const builtinEngines: readonly TemplatingEngine[] = [celEngine, literalEngine];
+
+export function createDefaultRegistry(): TemplatingEngineRegistry {
+  const registry = new TemplatingEngineRegistry();
+  for (const engine of builtinEngines) {
+    registry.register(engine);
+  }
+  return registry;
+}
+
+let defaultRegistryCache: TemplatingEngineRegistry | undefined;
+
+/** Memoized singleton: returns the default registry. Hosts that don't need
+ *  per-instance isolation (precompile, the analyzer's tagged-value walker)
+ *  should use this so they share the same registry instance the YAML tag
+ *  factory uses. */
+export function defaultRegistry(): TemplatingEngineRegistry {
+  if (!defaultRegistryCache) {
+    defaultRegistryCache = createDefaultRegistry();
+  }
+  return defaultRegistryCache;
+}

package/src/cel/analyze.ts

@@ -0,0 +1,125 @@
+import type { ASTNode } from "@marcbachmann/cel-js";
+
+/**
+ * Extract all member-access chains from a CEL AST.
+ * Returns arrays like ["request", "query", "name"] for `request.query.name`.
+ * Chains that start with a call or non-identifier root are ignored.
+ * Bound variables in comprehension macros (filter, map, exists, all, exists_one) are excluded.
+ */
+export function extractAccessChains(node: ASTNode): string[][] {
+  const chains: string[][] = [];
+  visitNode(node, chains, new Set());
+  return chains;
+}
+
+const COMPREHENSION_METHODS = new Set(["filter", "map", "exists", "all", "exists_one"]);
+
+function visitNode(node: ASTNode, chains: string[][], boundVars: Set<string>): void {
+  const chain = extractChain(node, boundVars);
+  if (chain !== null) {
+    chains.push(chain);
+    return;
+  }
+
+  if (
+    node.op === "rcall" &&
+    Array.isArray(node.args) &&
+    typeof node.args[0] === "string" &&
+    COMPREHENSION_METHODS.has(node.args[0])
+  ) {
+    const receiver = node.args[1];
+    const comprehensionArgs = node.args[2];
+    if (isASTNode(receiver)) visitNode(receiver, chains, boundVars);
+    if (
+      Array.isArray(comprehensionArgs) &&
+      comprehensionArgs.length >= 2 &&
+      isASTNode(comprehensionArgs[0]) &&
+      (comprehensionArgs[0] as ASTNode).op === "id"
+    ) {
+      const newBoundVars = new Set(boundVars);
+      newBoundVars.add((comprehensionArgs[0] as ASTNode).args as string);
+      for (let i = 1; i < comprehensionArgs.length; i++) {
+        const arg = comprehensionArgs[i];
+        if (isASTNode(arg)) visitNode(arg as ASTNode, chains, newBoundVars);
+      }
+    }
+    return;
+  }
+
+  const args = node.args;
+  if (Array.isArray(args)) {
+    for (const arg of args) {
+      if (isASTNode(arg)) {
+        visitNode(arg, chains, boundVars);
+      } else if (Array.isArray(arg)) {
+        for (const item of arg) {
+          if (isASTNode(item)) visitNode(item, chains, boundVars);
+        }
+      }
+    }
+  }
+}
+
+function isASTNode(v: unknown): v is ASTNode {
+  return v !== null && typeof v === "object" && "op" in (v as object);
+}
+
+const INDEX_SEGMENT = "[*]";
+
+function extractChain(node: ASTNode, boundVars: Set<string>): string[] | null {
+  if (node.op === "id") {
+    const name = node.args as string;
+    if (boundVars.has(name)) return null;
+    return [name];
+  }
+  if (node.op === ".") {
+    const [obj, field] = node.args as [ASTNode, string];
+    const parent = extractChain(obj, boundVars);
+    if (parent !== null) return [...parent, field];
+  }
+  if (node.op === "[]") {
+    const [obj] = node.args as [ASTNode, ASTNode];
+    const parent = extractChain(obj, boundVars);
+    if (parent !== null) return [...parent, INDEX_SEGMENT];
+  }
+  return null;
+}
+
+/**
+ * Check whether a member-access chain accesses only fields declared in a JSON Schema.
+ * Returns an error string if a field is unknown in a schema that declares explicit
+ * properties without `additionalProperties: true`, or if the chain attempts to
+ * reach inside an `x-telo-stream: true` property.
+ * Returns null when the chain is valid or the schema is too open to judge.
+ */
+export function validateChainAgainstSchema(
+  chain: string[],
+  schema: Record<string, any>,
+): string | null {
+  let current: Record<string, any> = schema;
+  for (let i = 0; i < chain.length; i++) {
+    const key = chain[i]!;
+    if (!current || typeof current !== "object") return null;
+    const props: Record<string, any> | undefined = current.properties;
+    if (!props) return null;
+    if (key in props) {
+      const propSchema = props[key];
+      if (
+        propSchema &&
+        typeof propSchema === "object" &&
+        propSchema["x-telo-stream"] === true &&
+        i < chain.length - 1
+      ) {
+        const path = chain.slice(0, i + 1).join(".");
+        return `'${path}' yields a stream — pipe it through an Encoder or iterate in a JS.Script step (no member access on stream-typed values)`;
+      }
+      current = propSchema;
+      continue;
+    }
+    if (current.additionalProperties === true) return null;
+    const path = chain.slice(0, i + 1).join(".");
+    const available = Object.keys(props).join(", ");
+    return `'${path}' is not defined (available: ${available})`;
+  }
+  return null;
+}

package/src/cel/compile.ts

@@ -0,0 +1,47 @@
+import type { CompiledValue } from "@telorun/sdk";
+import type { Environment } from "@marcbachmann/cel-js";
+
+export const TEMPLATE_REGEX = /\$\{\{\s*([^}]+?)\s*\}\}/g;
+export const EXACT_TEMPLATE_REGEX = /^\s*\$\{\{\s*([^}]+?)\s*\}\}\s*$/;
+
+/** Compile a single CEL expression (no `${{ }}` wrapping) into a CompiledValue.
+ *  Throws on syntax errors. Used by the `!cel` engine where the entire tagged
+ *  scalar is treated as one expression. */
+export function compileExpression(expr: string, env: Environment): CompiledValue {
+  const fn = env.parse(expr);
+  return {
+    __compiled: true,
+    source: expr,
+    call: (ctx: Record<string, unknown>) => fn(ctx),
+  };
+}
+
+/** Compile a string that may contain `${{ }}`-delimited CEL segments. If the
+ *  string is exactly one expression, returns a single CompiledValue. If it
+ *  contains interpolations, returns a CompiledValue that joins literal parts
+ *  with stringified expression results. If no expressions are present, returns
+ *  the input string unchanged. Throws on CEL syntax errors. */
+export function compileString(s: string, env: Environment): unknown {
+  if (!s.includes("${{")) return s;
+
+  const exact = s.match(EXACT_TEMPLATE_REGEX);
+  if (exact) {
+    return compileExpression(exact[1].trim(), env);
+  }
+
+  const parts: Array<string | CompiledValue> = [];
+  let last = 0;
+  for (const m of s.matchAll(TEMPLATE_REGEX)) {
+    if (m.index! > last) parts.push(s.slice(last, m.index));
+    parts.push(compileExpression(m[1].trim(), env));
+    last = m.index! + m[0].length;
+  }
+  if (last < s.length) parts.push(s.slice(last));
+
+  return {
+    __compiled: true,
+    source: s,
+    call: (ctx: Record<string, unknown>) =>
+      parts.map((p) => (typeof p === "string" ? p : String(p.call(ctx) ?? ""))).join(""),
+  } satisfies CompiledValue;
+}

package/src/cel/environment.ts

@@ -0,0 +1,50 @@
+import { Environment } from "@marcbachmann/cel-js";
+import { Stream } from "@telorun/sdk";
+
+export interface CelHandlers {
+  sha256: (s: string) => string;
+  json: (value: unknown) => string;
+}
+
+const stub = (name: string) => () => {
+  throw new Error(
+    `${name}() is not available in this environment. ` +
+      `Construct StaticAnalyzer or Loader with celHandlers to enable it.`,
+  );
+};
+
+const STUB_HANDLERS: CelHandlers = {
+  sha256: stub("sha256"),
+  json: stub("json"),
+};
+
+/** Build a CEL `Environment` with Telo's stdlib of functions. Always registers the
+ *  same function signatures (so `env.check()` succeeds for type-inference) — the
+ *  handlers govern what the function does when called at runtime. Analyzer-only
+ *  callers can omit handlers; runtime callers (kernel) must supply real ones.
+ *
+ *  Also registers the `Stream` object type, backed by the `Stream` class from
+ *  `@telorun/sdk`. CEL's type-checker rejects values whose constructor isn't
+ *  Object/Map/Array/Set/registered; producers that need to expose an
+ *  `AsyncIterable` through a stream-typed property must wrap the iterable in
+ *  `new Stream(...)` so its constructor is the registered class. The type has
+ *  no fields, so terminal access (passing the value through CEL) succeeds but
+ *  member access raises a CEL error at runtime — matching the analyzer's
+ *  static check on `x-telo-stream`-marked properties. */
+export function buildCelEnvironment(handlers: CelHandlers = STUB_HANDLERS): Environment {
+  return new Environment({ unlistedVariablesAreDyn: true, enableOptionalTypes: true })
+    .registerFunction("join(list, string): string", (list: unknown[], sep: string) =>
+      list.map(String).join(sep),
+    )
+    .registerFunction("keys(map): list", (map: unknown) => {
+      if (map instanceof Map) return [...map.keys()];
+      return Object.keys(map as Record<string, unknown>);
+    })
+    .registerFunction("values(map): list", (map: unknown) => {
+      if (map instanceof Map) return [...map.values()];
+      return Object.values(map as Record<string, unknown>);
+    })
+    .registerFunction("sha256(string): string", (s: string) => handlers.sha256(s))
+    .registerFunction("json(dyn): string", (value: unknown) => handlers.json(value))
+    .registerType("Stream", Stream as unknown as new (...args: unknown[]) => unknown);
+}