@checkstack/template-engine 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @checkstack/template-engine
 
+## 0.3.0
+
+### Minor Changes
+
+- 270ef29: Add live state in scope plus duration helpers to the automation sensing layer (Wave 2 Phase 14).
+
+  - `@checkstack/template-engine` ships four pure, synchronous duration filters: `minutes` and `hours` (number to milliseconds), `duration_since` (ms elapsed since an ISO timestamp), and `older_than(thresholdMs)` (boolean dwell check). They compute against real time at call time, so "now" is fresh per evaluation. Fail-safe on null/unparseable input.
+  - The dispatch engine pre-resolves live health state into scope before any condition or template evaluation (the engine is synchronous, so inline state queries are impossible). State is folded under a `health` namespace - `health.system.*` for the trigger's context system and `health.systems[<id>]` for ids listed in the automation's new `uses_state` field. One batched `getBulkHealthState` query per evaluation, wired at the fresh-run, resume, and trigger-gate sites. Fail-open: a missing client or provider error yields an empty namespace and a warning, never wedging unrelated automations.
+  - New `automationFilterExtensionPoint` lets plugins contribute pure template filters without forking the engine's default registry. Name collisions with built-ins are skipped with a warning.
+  - The editor variable-scope resolver and autocomplete catalogue now surface the `health.*` namespace and the new duration filters.
+
+  With this phase alone, an operator can build "notify me when a system has been unhealthy for 30 minutes" using an interval trigger plus a single `health.*` condition - no dwell timer required (the precise event-driven path lands in Phase 15).
+
 ## 0.2.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/template-engine",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "Elastic-2.0",
   "type": "module",
   "exports": {
@@ -10,11 +10,11 @@
     }
   },
   "dependencies": {
-    "@checkstack/common": "0.11.0",
+    "@checkstack/common": "0.12.0",
     "zod": "^4.0.0"
   },
   "devDependencies": {
-    "@checkstack/scripts": "0.3.3",
+    "@checkstack/scripts": "0.3.4",
     "@checkstack/tsconfig": "0.0.7",
     "typescript": "^5.7.2"
   },

package/src/__tests__/duration-filters.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "bun:test";
+import { parseCondition } from "../parser";
+import { evaluate, evaluateBoolean } from "../renderer";
+import { createDefaultFilterRegistry } from "../filters";
+
+const registry = createDefaultFilterRegistry();
+
+function evalExpr(src: string, scope: Record<string, unknown>): unknown {
+  return evaluate(parseCondition(src), scope, { filters: registry });
+}
+
+function evalBool(src: string, scope: Record<string, unknown>): boolean {
+  return evaluateBoolean(parseCondition(src), scope, { filters: registry });
+}
+
+describe("minutes / hours filters", () => {
+  it("minutes converts a number to milliseconds", () => {
+    expect(evalExpr("30 | minutes", {})).toBe(30 * 60_000);
+  });
+
+  it("hours converts a number to milliseconds", () => {
+    expect(evalExpr("2 | hours", {})).toBe(2 * 3_600_000);
+  });
+
+  it("minutes coerces numeric strings", () => {
+    expect(evalExpr('"15" | minutes', {})).toBe(15 * 60_000);
+  });
+
+  it("minutes passes through non-numeric input as NaN-safe 0", () => {
+    expect(evalExpr('"abc" | minutes', {})).toBe(0);
+  });
+});
+
+describe("duration_since filter", () => {
+  it("returns ms elapsed since the given ISO timestamp", () => {
+    const since = new Date(Date.now() - 5 * 60_000).toISOString();
+    const ms = evalExpr("ts | duration_since", { ts: since });
+    expect(typeof ms).toBe("number");
+    // ~5 minutes, allow a small execution window
+    expect(ms as number).toBeGreaterThanOrEqual(5 * 60_000 - 1000);
+    expect(ms as number).toBeLessThanOrEqual(5 * 60_000 + 5000);
+  });
+
+  it("returns 0 for null / undefined (fail-safe, not negative)", () => {
+    expect(evalExpr("missing | duration_since", {})).toBe(0);
+    expect(evalExpr("ts | duration_since", { ts: null })).toBe(0);
+  });
+
+  it("returns 0 for an unparseable value", () => {
+    expect(evalExpr("ts | duration_since", { ts: "not-a-date" })).toBe(0);
+  });
+
+  it("accepts a Date instance", () => {
+    const since = new Date(Date.now() - 60_000);
+    const ms = evalExpr("ts | duration_since", { ts: since });
+    expect(ms as number).toBeGreaterThanOrEqual(60_000 - 1000);
+  });
+});
+
+describe("older_than filter", () => {
+  it("is true when the timestamp is older than the threshold", () => {
+    const since = new Date(Date.now() - 31 * 60_000).toISOString();
+    expect(evalBool("ts | older_than(30 | minutes)", { ts: since })).toBe(true);
+  });
+
+  it("is false when the timestamp is newer than the threshold", () => {
+    const since = new Date(Date.now() - 10 * 60_000).toISOString();
+    expect(evalBool("ts | older_than(30 | minutes)", { ts: since })).toBe(
+      false,
+    );
+  });
+
+  it("is false (fail-safe) for null / unknown timestamps", () => {
+    expect(evalBool("missing | older_than(30 | minutes)", {})).toBe(false);
+    expect(evalBool("ts | older_than(30 | minutes)", { ts: null })).toBe(false);
+  });
+
+  it("composes in a realistic dwell condition", () => {
+    const since = new Date(Date.now() - 45 * 60_000).toISOString();
+    const scope = {
+      health: { system: { status: "unhealthy", in_status_since: since } },
+    };
+    const expr =
+      "health.system.status == 'unhealthy' && (health.system.in_status_since | older_than(30 | minutes))";
+    expect(evalBool(expr, scope)).toBe(true);
+  });
+});

package/src/filters.ts

@@ -42,6 +42,10 @@ export function createDefaultFilterRegistry(): FilterRegistry {
   registry.register("join", filterJoin);
   registry.register("replace", filterReplace);
   registry.register("not", filterNot);
+  registry.register("minutes", filterMinutes);
+  registry.register("hours", filterHours);
+  registry.register("duration_since", filterDurationSince);
+  registry.register("older_than", filterOlderThan);
   return registry;
 }
 
@@ -130,6 +134,68 @@ function filterNot(value: unknown): unknown {
   return !isTruthy(value);
 }
 
+// ─── Duration helpers ────────────────────────────────────────────────────
+//
+// All pure and synchronous (no DB, no async). `duration_since` /
+// `older_than` compute against `Date.now()` at call time, so "now" is
+// fresh per evaluation rather than the run-start `now` in scope. This is
+// deliberate: dwell re-checks and time-of-day logic must use real time,
+// not the frozen scope timestamp.
+
+/** Coerce an unknown to a finite number, or 0. */
+function toFiniteNumber(value: unknown): number {
+  const n = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(n) ? n : 0;
+}
+
+/** Parse an unknown into epoch-ms, or null when unparseable. */
+function toEpochMs(value: unknown): number | null {
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? null : value.getTime();
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : null;
+  }
+  if (typeof value === "string") {
+    const ms = new Date(value).getTime();
+    return Number.isNaN(ms) ? null : ms;
+  }
+  return null;
+}
+
+/** `{{ 30 | minutes }}` -> 1_800_000 (a number of minutes to ms). */
+function filterMinutes(value: unknown): unknown {
+  return toFiniteNumber(value) * 60_000;
+}
+
+/** `{{ 2 | hours }}` -> 7_200_000 (a number of hours to ms). */
+function filterHours(value: unknown): unknown {
+  return toFiniteNumber(value) * 3_600_000;
+}
+
+/**
+ * `{{ someIso | duration_since }}` -> milliseconds elapsed since the
+ * given timestamp. Fail-safe: null/undefined/unparseable -> 0 (never
+ * negative, never throws). Clamped at 0 to absorb clock skew.
+ */
+function filterDurationSince(value: unknown): unknown {
+  const ms = toEpochMs(value);
+  if (ms === null) return 0;
+  return Math.max(0, Date.now() - ms);
+}
+
+/**
+ * `{{ someIso | older_than(30 | minutes) }}` -> boolean. True when the
+ * timestamp is at least `thresholdMs` in the past. Fail-safe: a
+ * null/unparseable timestamp returns false (an unknown age is never
+ * "older than" a threshold).
+ */
+function filterOlderThan(value: unknown, thresholdMs: unknown): unknown {
+  const ms = toEpochMs(value);
+  if (ms === null) return false;
+  return Date.now() - ms >= toFiniteNumber(thresholdMs);
+}
+
 /**
  * Centralised truthiness rule. Mirrors JavaScript's notion plus: empty
  * string is falsy, empty arrays are falsy, empty plain objects are falsy.