@telorun/templating 0.4.1 → 0.6.0

package/dist/cel/environment.d.ts

@@ -1,12 +1,13 @@
 import { Environment } from "@marcbachmann/cel-js";
-export interface CelHandlers {
-    sha256: (s: string) => string;
-    json: (value: unknown) => string;
-}
-/** 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.
+import { type CelHandlers } from "./catalog.js";
+export type { CelHandlers } from "./catalog.js";
+/** Build a CEL `Environment` with Telo's stdlib. Every function comes from the
+ *  single-source catalog (`CEL_FUNCTIONS`), so registration and the documented
+ *  surface (`telo cel functions`) can never drift. Always registers the same
+ *  signatures (so `env.check()` succeeds for type-inference); the host-injected
+ *  handlers govern what `hostBacked` functions do at runtime. Analyzer-only
+ *  callers can omit handlers (the stubs throw if such a function is evaluated);
+ *  runtime callers (kernel) 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
@@ -16,5 +17,5 @@ export interface CelHandlers {
  *  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 declare function buildCelEnvironment(handlers?: CelHandlers): Environment;
+export declare function buildCelEnvironment(handlers?: Partial<CelHandlers>): Environment;
 //# sourceMappingURL=environment.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/cel/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGnD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9B,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC;CAClC;AAcD;;;;;;;;;;;;yDAYyD;AACzD,wBAAgB,mBAAmB,CAAC,QAAQ,GAAE,WAA2B,GAAG,WAAW,CAgBtF"}
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/cel/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAE/D,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAoBhD;;;;;;;;;;;;;;;yDAeyD;AACzD,wBAAgB,mBAAmB,CAAC,QAAQ,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,WAAW,CAYpF"}

package/dist/cel/environment.js

@@ -1,17 +1,27 @@
 import { Environment } from "@marcbachmann/cel-js";
 import { Stream } from "@telorun/sdk";
+import { CEL_FUNCTIONS } from "./catalog.js";
 const stub = (name) => () => {
     throw new Error(`${name}() is not available in this environment. ` +
         `Construct StaticAnalyzer or Loader with celHandlers to enable it.`);
 };
 const STUB_HANDLERS = {
     sha256: stub("sha256"),
+    md5: stub("md5"),
+    sha1: stub("sha1"),
+    sha512: stub("sha512"),
+    hmac: stub("hmac"),
+    base64Encode: stub("base64Encode"),
+    base64Decode: stub("base64Decode"),
     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.
+/** Build a CEL `Environment` with Telo's stdlib. Every function comes from the
+ *  single-source catalog (`CEL_FUNCTIONS`), so registration and the documented
+ *  surface (`telo cel functions`) can never drift. Always registers the same
+ *  signatures (so `env.check()` succeeds for type-inference); the host-injected
+ *  handlers govern what `hostBacked` functions do at runtime. Analyzer-only
+ *  callers can omit handlers (the stubs throw if such a function is evaluated);
+ *  runtime callers (kernel) 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
@@ -21,20 +31,16 @@ const STUB_HANDLERS = {
  *  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 = STUB_HANDLERS) {
-    return new Environment({ unlistedVariablesAreDyn: true, enableOptionalTypes: true })
-        .registerFunction("join(list, string): string", (list, sep) => list.map(String).join(sep))
-        .registerFunction("keys(map): list", (map) => {
-        if (map instanceof Map)
-            return [...map.keys()];
-        return Object.keys(map);
-    })
-        .registerFunction("values(map): list", (map) => {
-        if (map instanceof Map)
-            return [...map.values()];
-        return Object.values(map);
-    })
-        .registerFunction("sha256(string): string", (s) => handlers.sha256(s))
-        .registerFunction("json(dyn): string", (value) => handlers.json(value))
-        .registerType("Stream", Stream);
+export function buildCelEnvironment(handlers = {}) {
+    const h = { ...STUB_HANDLERS, ...handlers };
+    let env = new Environment({ unlistedVariablesAreDyn: true, enableOptionalTypes: true });
+    for (const fn of CEL_FUNCTIONS) {
+        const impl = fn.build(h);
+        // `register` lists one cel-js signature per arity (overloaded functions);
+        // it falls back to `signature` for the single-arity common case.
+        for (const sig of fn.register ?? [fn.signature]) {
+            env = env.registerFunction(sig, impl);
+        }
+    }
+    return env.registerType("Stream", Stream);
 }

package/dist/engines/cel.d.ts

@@ -1,4 +1,10 @@
-import type { TemplatingEngine } from "../engine.js";
+import type { AnalyzeEnv, EngineDiagnostic, TemplatingEngine } from "../engine.js";
+/** Statically analyze one CEL expression against the effective context schema:
+ *  parse → extract member-access chains → validate each chain → flag nullable
+ *  access. Single source of truth shared by the `!cel` engine (one expression)
+ *  and the `!sql` engine (one per `${{ }}` interpolation), so diagnostic wording
+ *  can't drift between them. */
+export declare function analyzeCelExpression(source: string, env: AnalyzeEnv): EngineDiagnostic[];
 /** 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

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

@@ -1 +1 @@
-{"version":3,"file":"cel.d.ts","sourceRoot":"","sources":["../../src/engines/cel.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAoB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEvE;;;kDAGkD;AAClD,eAAO,MAAM,SAAS,EAAE,gBA4CvB,CAAC"}
+{"version":3,"file":"cel.d.ts","sourceRoot":"","sources":["../../src/engines/cel.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEnF;;;;gCAIgC;AAChC,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,gBAAgB,EAAE,CAmCxF;AAED;;;kDAGkD;AAClD,eAAO,MAAM,SAAS,EAAE,gBAWvB,CAAC"}

package/dist/engines/cel.js

@@ -1,5 +1,42 @@
 import { extractAccessChains, findNullableAccessIssues, validateChainAgainstSchema, } from "../cel/analyze.js";
 import { compileExpression } from "../cel/compile.js";
+/** Statically analyze one CEL expression against the effective context schema:
+ *  parse → extract member-access chains → validate each chain → flag nullable
+ *  access. Single source of truth shared by the `!cel` engine (one expression)
+ *  and the `!sql` engine (one per `${{ }}` interpolation), so diagnostic wording
+ *  can't drift between them. */
+export function analyzeCelExpression(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 });
+    }
+    for (const issue of findNullableAccessIssues(parsed.ast, env.contextSchema)) {
+        // Index access (member "[index]") attaches without a dot; a named field
+        // attaches with one — so the suggested CEL stays valid either way.
+        const access = issue.member === "[index]" ? issue.member : `.${issue.member}`;
+        out.push({
+            code: "CEL_NULLABLE_ACCESS",
+            message: `'${issue.path}' may be null — guard it (e.g. '${issue.path} != null && …' or '${issue.path} == null ? … : ${issue.path}${access}') before accessing '${access}'`,
+        });
+    }
+    return out;
+}
 /** 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
@@ -11,35 +48,6 @@ export const celEngine = {
         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 });
-        }
-        for (const issue of findNullableAccessIssues(parsed.ast, env.contextSchema)) {
-            // Index access (member "[index]") attaches without a dot; a named field
-            // attaches with one — so the suggested CEL stays valid either way.
-            const access = issue.member === "[index]" ? issue.member : `.${issue.member}`;
-            out.push({
-                code: "CEL_NULLABLE_ACCESS",
-                message: `'${issue.path}' may be null — guard it (e.g. '${issue.path} != null && …' or '${issue.path} == null ? … : ${issue.path}${access}') before accessing '${access}'`,
-            });
-        }
-        return out;
+        return analyzeCelExpression(source, env);
     },
 };

package/dist/engines/sql.d.ts

@@ -0,0 +1,11 @@
+import { isParameterizedSql, type ParameterizedSql } from "@telorun/sdk";
+import type { TemplatingEngine } from "../engine.js";
+export { isParameterizedSql, type ParameterizedSql };
+/** The `!sql` engine. Treats the tagged scalar as a SQL string with `${{ }}`
+ *  interpolations whose values are *bound*, not spliced. Unlike `!cel` (one bare
+ *  expression) it keeps the literal text and each interpolation separate: at
+ *  runtime `call()` returns a {@link ParameterizedSql} the consumer turns into a
+ *  parameterized query. Generic expansion passes that object through untouched
+ *  (it is the `call()` result), so it survives the step-level input expansion. */
+export declare const sqlEngine: TemplatingEngine;
+//# sourceMappingURL=sql.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../../src/engines/sql.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAsB,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAG7F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,EAAE,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,CAAC;AAErD;;;;;kFAKkF;AAClF,eAAO,MAAM,SAAS,EAAE,gBAqBvB,CAAC"}

package/dist/engines/sql.js

@@ -0,0 +1,38 @@
+import { isParameterizedSql } from "@telorun/sdk";
+import { analyzeCelExpression } from "./cel.js";
+import { compileString, toParameterized, TEMPLATE_REGEX } from "../cel/compile.js";
+export { isParameterizedSql };
+/** The `!sql` engine. Treats the tagged scalar as a SQL string with `${{ }}`
+ *  interpolations whose values are *bound*, not spliced. Unlike `!cel` (one bare
+ *  expression) it keeps the literal text and each interpolation separate: at
+ *  runtime `call()` returns a {@link ParameterizedSql} the consumer turns into a
+ *  parameterized query. Generic expansion passes that object through untouched
+ *  (it is the `call()` result), so it survives the step-level input expansion. */
+export const sqlEngine = {
+    name: "sql",
+    language: "sql",
+    compile(source, env) {
+        const inner = compileString(source, env.celEnv);
+        return {
+            __compiled: true,
+            source,
+            call: (ctx) => {
+                const { fragments, values } = toParameterized(inner, ctx);
+                return { __teloParameterized: true, fragments, values };
+            },
+        };
+    },
+    analyze(source, env) {
+        // Each `${{ }}` interpolation is its own CEL expression; reuse the shared
+        // per-expression analyzer so diagnostics match the `!cel` engine exactly.
+        return expressionsOf(source).flatMap((expr) => analyzeCelExpression(expr, env));
+    },
+};
+/** Extract each `${{ expr }}` body from a `!sql` template source. */
+function expressionsOf(source) {
+    const exprs = [];
+    for (const m of source.matchAll(TEMPLATE_REGEX)) {
+        exprs.push(m[1].trim());
+    }
+    return exprs;
+}

package/dist/index.d.ts

@@ -1,10 +1,12 @@
 export { buildCelEnvironment, type CelHandlers } from "./cel/environment.js";
-export { compileExpression, compileString, TEMPLATE_REGEX, EXACT_TEMPLATE_REGEX, } from "./cel/compile.js";
+export { celFunctionCatalog, CEL_FUNCTIONS, type CelFunctionInfo, type CelFunctionDoc, type CelFunctionCategory, } from "./cel/catalog.js";
+export { compileExpression, compileString, toParameterized, TEMPLATE_REGEX, EXACT_TEMPLATE_REGEX, } from "./cel/compile.js";
 export { extractAccessChains, findNullableAccessIssues, INDEX_SEGMENT, validateChainAgainstSchema, } from "./cel/analyze.js";
 export { walkCelExpressions } from "./cel/walk.js";
 export { celEngine } from "./engines/cel.js";
 export { literalEngine } from "./engines/literal.js";
 export { refEngine } from "./engines/ref.js";
+export { sqlEngine, isParameterizedSql, type ParameterizedSql } from "./engines/sql.js";
 export { TemplatingEngineRegistry } from "./registry.js";
 export { builtinEngines, createDefaultRegistry, defaultRegistry } from "./builtins.js";
 export type { AnalyzeEnv, CompileEnv, EngineDiagnostic, TemplatingEngine, } from "./engine.js";

package/dist/index.d.ts.map

@@ -1 +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,EACL,mBAAmB,EACnB,wBAAwB,EACxB,aAAa,EACb,0BAA0B,GAC3B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C,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,aAAa,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACzG,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC"}
+{"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,kBAAkB,EAClB,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,cAAc,EACd,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,aAAa,EACb,0BAA0B,GAC3B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAExF,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,aAAa,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACzG,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -1,10 +1,12 @@
 export { buildCelEnvironment } from "./cel/environment.js";
-export { compileExpression, compileString, TEMPLATE_REGEX, EXACT_TEMPLATE_REGEX, } from "./cel/compile.js";
+export { celFunctionCatalog, CEL_FUNCTIONS, } from "./cel/catalog.js";
+export { compileExpression, compileString, toParameterized, TEMPLATE_REGEX, EXACT_TEMPLATE_REGEX, } from "./cel/compile.js";
 export { extractAccessChains, findNullableAccessIssues, INDEX_SEGMENT, validateChainAgainstSchema, } from "./cel/analyze.js";
 export { walkCelExpressions } from "./cel/walk.js";
 export { celEngine } from "./engines/cel.js";
 export { literalEngine } from "./engines/literal.js";
 export { refEngine } from "./engines/ref.js";
+export { sqlEngine, isParameterizedSql } from "./engines/sql.js";
 export { TemplatingEngineRegistry } from "./registry.js";
 export { builtinEngines, createDefaultRegistry, defaultRegistry } from "./builtins.js";
 export { isRefSentinel, isTaggedSentinel, makeTaggedSentinel } from "./sentinel.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/templating",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Telo Templating - Engine registry and shared CEL core for Telo manifests.",
   "keywords": [
     "telo",
@@ -36,13 +36,15 @@
   ],
   "dependencies": {
     "@marcbachmann/cel-js": "^7.5.3",
+    "uuid": "^10.0.0",
     "yaml": "^2.8.3"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
+    "@types/uuid": "^10.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.16.0"
+    "@telorun/sdk": "0.21.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/builtins.ts

@@ -1,6 +1,7 @@
 import { celEngine } from "./engines/cel.js";
 import { literalEngine } from "./engines/literal.js";
 import { refEngine } from "./engines/ref.js";
+import { sqlEngine } from "./engines/sql.js";
 import { TemplatingEngineRegistry } from "./registry.js";
 import type { TemplatingEngine } from "./engine.js";
 
@@ -10,7 +11,12 @@ import type { TemplatingEngine } from "./engine.js";
  *  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, refEngine];
+export const builtinEngines: readonly TemplatingEngine[] = [
+  celEngine,
+  literalEngine,
+  refEngine,
+  sqlEngine,
+];
 
 export function createDefaultRegistry(): TemplatingEngineRegistry {
   const registry = new TemplatingEngineRegistry();