@telorun/templating 0.10.0 → 0.11.0

package/README.md

@@ -23,7 +23,7 @@ Built to be language-agnostic and infinitely extensible.
 
 ```bash
 # Reconcile your manifest into a running backend
-$ telo ./examples/hello-api.yaml
+$ telo ./examples/hello-api
 
 {"level":30,"time":1771610393008,"pid":1310178,"hostname":"dev","msg":"Server listening at http://127.0.0.1:8844"}
 ```
@@ -44,146 +44,7 @@ $ telo ./examples/hello-api.yaml
 
 ## Example manifest
 
-Here is an example Telo application that defines a simple HTTP API:
-
-```yaml
-kind: Telo.Application
-metadata:
-  name: feedback
-  version: 1.0.0
-  description: |
-    A complete feedback collection REST API — no code, pure YAML.
-    Persists entries to SQLite and serves them over HTTP.
-imports:
-  Http: std/http-server@0.11.0
-  Sql: std/sql@0.9.0
-targets:
-  - !ref Migrations
-  - !ref Server
----
-# SQLite database — swap driver/host/database for PostgreSQL with zero YAML changes
-kind: Sql.Connection
-metadata:
-  name: Db
-driver: sqlite
-file: ./tmp/feedback.db
----
-# Migrations: applied automatically before the server starts
-kind: Sql.Migrations
-metadata:
-  name: Migrations
-connection: !ref Db
----
-kind: Sql.Migration
-metadata:
-  name: Migration_20260413_182154_CreateFeedback
-version: 20260413_182154_CreateFeedback
-sql: |
-  CREATE TABLE IF NOT EXISTS feedback (
-    id        INTEGER PRIMARY KEY AUTOINCREMENT,
-    text      TEXT    NOT NULL,
-    source    TEXT,
-    score     INTEGER NOT NULL DEFAULT 0,
-    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-  )
----
-kind: Http.Server
-metadata:
-  name: Server
-baseUrl: http://localhost:8844
-port: 8844
-logger: true
-openapi:
-  info:
-    title: Feedback API
-    version: 1.0.0
-mounts:
-  - path: /v1
-    mount: !ref FeedbackRoutes
----
-kind: Http.Api
-metadata:
-  name: FeedbackRoutes
-routes:
-  # POST /v1/feedback — insert a new entry, score derived from body length heuristic
-  - request:
-      path: /feedback
-      method: POST
-      schema:
-        body:
-          type: object
-          properties:
-            text:
-              type: string
-              minLength: 1
-            source:
-              type: string
-          required: [ text ]
-    handler:
-      kind: Sql.Exec
-      connection: !ref Db
-    inputs:
-      sql: "INSERT INTO feedback (text, source, score) VALUES (?, ?, ?)"
-      bindings:
-        - "${{ request.body.text }}"
-        - "${{ request.body.source }}"
-        - "${{ size(request.body.text) }}"
-    response:
-      - status: 201
-        headers:
-          Content-Type: application/json
-        body:
-          ok: true
-          message: Feedback received
-
-  # GET /v1/feedback — list all entries, newest first
-  - request:
-      path: /feedback
-      method: GET
-    handler:
-      kind: Sql.Select
-      connection: !ref Db
-      from: feedback
-      columns: [ id, text, source, score, created_at ]
-      orderBy:
-        - { column: created_at, direction: desc }
-    response:
-      - status: 200
-        headers:
-          Content-Type: application/json
-        body: "${{ result.rows }}"
-
-  # GET /v1/feedback/{id} — fetch a single entry
-  - request:
-      path: /feedback/{id}
-      method: GET
-      schema:
-        params:
-          type: object
-          properties:
-            id:
-              type: integer
-          required: [ id ]
-    handler:
-      kind: Sql.Select
-      connection: !ref Db
-      from: feedback
-      columns: [ id, text, source, score, created_at ]
-      where:
-        - { column: id, op: "=", value: "${{ request.params.id }}" }
-    response:
-      - status: 200
-        when: "size(result.rows) > 0"
-        headers:
-          Content-Type: application/json
-        body: "${{ result.rows[0] }}"
-      - status: 404
-        headers:
-          Content-Type: application/json
-        body:
-          ok: false
-          message: Not found
-```
+See [examples/](./examples/) for a list of working applications.
 
 ## Status
 

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

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/cel/catalog.ts"],"names":[],"mappings":"AAGA;;;0DAG0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9B,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3B,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC5B,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9B,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IAClE,YAAY,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,YAAY,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC;CAClC;AA2CD,MAAM,MAAM,mBAAmB,GAC3B,YAAY,GACZ,MAAM,GACN,MAAM,GACN,QAAQ,GACR,MAAM,GACN,YAAY,GACZ,MAAM,GACN,UAAU,GACV,SAAS,GACT,MAAM,CAAC;AAEX;;;qBAGqB;AACrB,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;0EACsE;IACtE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;yDAIqD;IACrD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;wBACoB;IACpB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC;2EACuE;IACvE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC;CACjE;AAED,wEAAwE;AACxE,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;AAyE5D,eAAO,MAAM,aAAa,EAAE,SAAS,cAAc,EA8elD,CAAC;AAEF,oEAAoE;AACpE,wBAAgB,kBAAkB,IAAI,eAAe,EAAE,CAEtD"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/cel/catalog.ts"],"names":[],"mappings":"AAGA;;;0DAG0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9B,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3B,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC5B,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9B,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IAClE,YAAY,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,YAAY,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC;CAClC;AA2CD,MAAM,MAAM,mBAAmB,GAC3B,YAAY,GACZ,MAAM,GACN,MAAM,GACN,QAAQ,GACR,MAAM,GACN,YAAY,GACZ,MAAM,GACN,UAAU,GACV,SAAS,GACT,MAAM,CAAC;AAEX;;;qBAGqB;AACrB,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;0EACsE;IACtE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;yDAIqD;IACrD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;wBACoB;IACpB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC;2EACuE;IACvE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC;CACjE;AAED,wEAAwE;AACxE,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;AAyE5D,eAAO,MAAM,aAAa,EAAE,SAAS,cAAc,EAogBlD,CAAC;AAEF,oEAAoE;AACpE,wBAAgB,kBAAkB,IAAI,eAAe,EAAE,CAEtD"}

package/dist/cel/catalog.js

@@ -358,6 +358,26 @@ export const CEL_FUNCTIONS = [
         hostBacked: false,
         build: () => (list) => minMax(list, false),
     },
+    {
+        name: "sum",
+        signature: "sum(list): double",
+        category: "math",
+        summary: "Sum of a list's numeric elements; 0 for an empty list.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (list) => Array.isArray(list) ? list.reduce((acc, x) => acc + num(x), 0) : 0,
+    },
+    {
+        name: "avg",
+        signature: "avg(list): dyn",
+        category: "math",
+        summary: "Arithmetic mean of a list's numeric elements; null for an empty list.",
+        deterministic: true,
+        hostBacked: false,
+        build: () => (list) => Array.isArray(list) && list.length > 0
+            ? list.reduce((acc, x) => acc + num(x), 0) / list.length
+            : null,
+    },
     // JSON
     {
         name: "json",

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

@@ -1 +1 @@
-{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/cel/compile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,eAAO,MAAM,cAAc,QAA8B,CAAC;AAC1D,eAAO,MAAM,oBAAoB,QAAqC,CAAC;AAEvE;;2CAE2C;AAC3C,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,aAAa,CAO/E;AAED;;;;+DAI+D;AAC/D,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAwBlE;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B;IAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,CAAA;CAAE,CAsB5C"}
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/cel/compile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGxD,eAAO,MAAM,cAAc,QAA8B,CAAC;AAC1D,eAAO,MAAM,oBAAoB,QAAqC,CAAC;AAgBvE;;2CAE2C;AAC3C,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,aAAa,CAQ/E;AAED;;;;+DAI+D;AAC/D,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CA8BlE;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B;IAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,CAAA;CAAE,CAsB5C"}

package/dist/cel/compile.js

@@ -1,6 +1,22 @@
 import { isCompiledValue } from "@telorun/sdk";
+import { extractAccessChains } from "./analyze.js";
 export const TEMPLATE_REGEX = /\$\{\{\s*([^}]+?)\s*\}\}/g;
 export const EXACT_TEMPLATE_REGEX = /^\s*\$\{\{\s*([^}]+?)\s*\}\}\s*$/;
+/** Root variable identifiers an expression reads, from its parsed AST — the
+ *  first element of every member-access chain (`self.table` → `self`). Returns
+ *  undefined when the parse result carries no AST so consumers can tell "no
+ *  refs" from "unknown". */
+function rootRefs(parsed) {
+    const ast = parsed.ast;
+    if (!ast)
+        return undefined;
+    const roots = new Set();
+    for (const chain of extractAccessChains(ast)) {
+        if (chain.length > 0)
+            roots.add(chain[0]);
+    }
+    return [...roots];
+}
 /** 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. */
@@ -9,6 +25,7 @@ export function compileExpression(expr, env) {
     return {
         __compiled: true,
         source: expr,
+        refs: rootRefs(fn),
         call: (ctx) => fn(ctx),
     };
 }
@@ -34,10 +51,17 @@ export function compileString(s, env) {
     }
     if (last < s.length)
         parts.push(s.slice(last));
+    const refs = new Set();
+    for (const p of parts) {
+        if (typeof p !== "string" && p.refs)
+            for (const r of p.refs)
+                refs.add(r);
+    }
     return {
         __compiled: true,
         source: s,
         parts,
+        refs: [...refs],
         call: (ctx) => parts.map((p) => (typeof p === "string" ? p : String(p.call(ctx) ?? ""))).join(""),
     };
 }

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;AAEnD,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAE/D,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAoBhD;;;;;;;;;;;;;;;yDAeyD;AACzD;;;;;wBAKwB;AACxB,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAyB5D;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,WAAW,CAcpF"}
+{"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;;;;;wBAKwB;AACxB,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAyB5D;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,WAAW,CAkBpF"}

package/dist/cel/environment.js

@@ -68,7 +68,11 @@ export function deriveSignatures(signature) {
 }
 export function buildCelEnvironment(handlers = {}) {
     const h = { ...STUB_HANDLERS, ...handlers };
-    let env = new Environment({ unlistedVariablesAreDyn: true, enableOptionalTypes: true });
+    // cel-go defaults HomogeneousAggregateLiterals OFF: heterogeneous list/map
+    // literals unify to `dyn` rather than erroring. cel-js flips that default to
+    // strict; we align with cel-go so manifests (dyn-heavy: request, rows, …)
+    // don't hit false positives the runtime evaluates fine.
+    let env = new Environment({ unlistedVariablesAreDyn: true, enableOptionalTypes: true, homogeneousAggregateLiterals: false });
     for (const fn of CEL_FUNCTIONS) {
         const impl = fn.build(h);
         // `register` lists one cel-js signature per arity (overloaded functions).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/templating",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Telo Templating - Engine registry and shared CEL core for Telo manifests.",
   "keywords": [
     "telo",
@@ -45,7 +45,7 @@
     "@types/uuid": "^10.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.26.0"
+    "@telorun/sdk": "0.50.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/cel/catalog.ts

@@ -428,6 +428,28 @@ export const CEL_FUNCTIONS: readonly CelFunctionDoc[] = [
     hostBacked: false,
     build: () => (list: unknown[]) => minMax(list, false),
   },
+  {
+    name: "sum",
+    signature: "sum(list): double",
+    category: "math",
+    summary: "Sum of a list's numeric elements; 0 for an empty list.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (list: unknown[]) =>
+      Array.isArray(list) ? list.reduce((acc: number, x) => acc + num(x), 0) : 0,
+  },
+  {
+    name: "avg",
+    signature: "avg(list): dyn",
+    category: "math",
+    summary: "Arithmetic mean of a list's numeric elements; null for an empty list.",
+    deterministic: true,
+    hostBacked: false,
+    build: () => (list: unknown[]) =>
+      Array.isArray(list) && list.length > 0
+        ? list.reduce((acc: number, x) => acc + num(x), 0) / list.length
+        : null,
+  },
   // JSON
   {
     name: "json",

package/src/cel/compile.ts

@@ -1,9 +1,24 @@
 import { isCompiledValue, type CompiledValue } from "@telorun/sdk";
 import type { Environment } from "@marcbachmann/cel-js";
+import { extractAccessChains } from "./analyze.js";
 
 export const TEMPLATE_REGEX = /\$\{\{\s*([^}]+?)\s*\}\}/g;
 export const EXACT_TEMPLATE_REGEX = /^\s*\$\{\{\s*([^}]+?)\s*\}\}\s*$/;
 
+/** Root variable identifiers an expression reads, from its parsed AST — the
+ *  first element of every member-access chain (`self.table` → `self`). Returns
+ *  undefined when the parse result carries no AST so consumers can tell "no
+ *  refs" from "unknown". */
+function rootRefs(parsed: unknown): readonly string[] | undefined {
+  const ast = (parsed as { ast?: unknown }).ast;
+  if (!ast) return undefined;
+  const roots = new Set<string>();
+  for (const chain of extractAccessChains(ast as never)) {
+    if (chain.length > 0) roots.add(chain[0]!);
+  }
+  return [...roots];
+}
+
 /** 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. */
@@ -12,6 +27,7 @@ export function compileExpression(expr: string, env: Environment): CompiledValue
   return {
     __compiled: true,
     source: expr,
+    refs: rootRefs(fn),
     call: (ctx: Record<string, unknown>) => fn(ctx),
   };
 }
@@ -38,10 +54,16 @@ export function compileString(s: string, env: Environment): unknown {
   }
   if (last < s.length) parts.push(s.slice(last));
 
+  const refs = new Set<string>();
+  for (const p of parts) {
+    if (typeof p !== "string" && p.refs) for (const r of p.refs) refs.add(r);
+  }
+
   return {
     __compiled: true,
     source: s,
     parts,
+    refs: [...refs],
     call: (ctx: Record<string, unknown>) =>
       parts.map((p) => (typeof p === "string" ? p : String(p.call(ctx) ?? ""))).join(""),
   } satisfies CompiledValue;

package/src/cel/environment.ts

@@ -73,7 +73,11 @@ export function deriveSignatures(signature: string): string[] {
 
 export function buildCelEnvironment(handlers: Partial<CelHandlers> = {}): Environment {
   const h: CelHandlers = { ...STUB_HANDLERS, ...handlers };
-  let env = new Environment({ unlistedVariablesAreDyn: true, enableOptionalTypes: true });
+  // cel-go defaults HomogeneousAggregateLiterals OFF: heterogeneous list/map
+  // literals unify to `dyn` rather than erroring. cel-js flips that default to
+  // strict; we align with cel-go so manifests (dyn-heavy: request, rows, …)
+  // don't hit false positives the runtime evaluates fine.
+  let env = new Environment({ unlistedVariablesAreDyn: true, enableOptionalTypes: true, homogeneousAggregateLiterals: false });
   for (const fn of CEL_FUNCTIONS) {
     const impl = fn.build(h);
     // `register` lists one cel-js signature per arity (overloaded functions).