@checkstack/template-engine 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,114 @@
+# @checkstack/template-engine
+
+## 0.2.0
+
+### Minor Changes
+
+- 41c77f4: feat(automation): Phase 11 — editor primitives + context type generation
+
+  Lays the UI + type-generation groundwork for Phase 12's visual automation
+  editor. Every primitive reuses the existing Monaco wrapper / template
+  engine / `jsonSchemaToTypeScript` helper rather than building parallel
+  infrastructure.
+
+  **`@checkstack/automation-common` — `resolveVariableScope`**
+
+  Pure walker that returns the in-scope `{{ … }}` paths at a given action
+  position. Conservative scoping rules: linear-upstream variables /
+  artifacts only (no leaking across `choose` / `parallel` / `repeat`
+  branches), `repeat.index` / `repeat.item` exposed only inside a `repeat`,
+  and trigger.payload modelled as a **discriminated union over
+  `trigger.event`** — every payload field surfaces; ones that come from a
+  subset of subscribed triggers carry a `conditionalOnTriggers` annotation
+  so the picker can render an "Only when …" hint. Earlier draft used
+  schema-intersection; switched to discriminated unions per review
+  feedback so Monaco can narrow correctly inside event-gated branches.
+
+  **Condition-aware narrowing.** When the path descends through a
+  `choose-when`, the resolver parses the branch's `when:` expression and
+  statically pins `trigger.event` to the set the condition allows —
+  patterns covered are `trigger.event == "X"` (either operand order),
+  `trigger.event != "X"`, `||`/`&&` of those, and `{ and: [...] }` /
+  `{ or: [...] }` combinators. So an action inside
+  `when: 'trigger.event == "incident.created"'` sees only the
+  `incident.created` variant in scope, the `conditionalOnTriggers`
+  annotation disappears, and other-trigger fields drop out entirely.
+  Nested choose branches compound (intersection). Anything outside the
+  covered patterns falls back to the full union — better to show every
+  field than guess wrong.
+
+  **`@checkstack/template-engine`**
+
+  The expression AST (`Expr`, `BinaryExpr`, `MemberExpr`, etc.) is now a
+  public export — the resolver's condition-narrowing walker needs to
+  inspect parsed condition trees. `ParsedCondition.root` is tightened
+  from `unknown` to `Expr` so consumers don't need to cast.
+
+  **`@checkstack/automation-frontend` — `generateAutomationContextTypes`**
+
+  Consumes `resolveVariableScope`'s output + the trigger / artifact
+  registries and emits the `declare const context: { … }` TS declaration
+  that `integration-script.run_script`'s Monaco editor injects via
+  `addExtraLib`. The emitted shape:
+
+  ```ts
+  type AutomationTrigger =
+    | { event: "incident.created"; payload: { … } }
+    | { event: "incident.resolved"; payload: { … } };
+
+  declare const context: {
+    trigger: AutomationTrigger;
+    artifacts: { "jira.issue"?: { key: string; … }; … };
+    var: { foo?: string; … };
+    repeat: { index: number; item: unknown };  // only when inside a repeat
+  };
+  ```
+
+  `jsonSchemaToTypeScript` from `@checkstack/ui` is reused via a deep
+  import (rather than the barrel) so the bun test runner doesn't try to
+  load Monaco's Vite-only `?worker` modules during unit tests.
+
+  **`@checkstack/ui` — new editor primitives**
+
+  - `TemplateValueInput` — single-line `{{ }}` autocomplete input.
+    Extracted from `DynamicForm/KeyValueEditor`'s previously-private
+    `TemplateInput` so other editor surfaces can share it without
+    rebuilding the picker UX. `KeyValueEditor` is now a one-line
+    delegation; `detectTemplateContext` is also exported.
+  - `VariablePicker` — hierarchical popover for the explicit "fx" /
+    "Insert variable" workflow. Renders a filterable tree of
+    `VariableNode`s with type chips and `Only when …` hints sourced from
+    the resolver's `conditionalOnTriggers`. Defaults to a small "fx" pill
+    trigger; callers can pass a custom one.
+  - `TemplateInput` — high-level mode switcher: `text` mode delegates to
+    `TemplateValueInput`, all other modes (`code` / `bash` / `json` /
+    `yaml`) delegate to `CodeEditor` with the matching language so the
+    action editor can swap widgets purely from the action's
+    `x-editor-types` annotation without touching the consuming code.
+  - `TemplateInputToggle` — the small "fx" pill that flips a typed input
+    (number / select / date / …) into template mode and back. Auto-infers
+    template mode when the saved value already starts with `{{`, so
+    round-tripping a previously-templated automation works out of the
+    box. Render-prop API for the typed editor so consumers keep control
+    over their own input shape.
+  - `ActionCard` — collapsible card that hosts a single action in the
+    visual editor. Decoupled from `DynamicForm` so container blocks
+    (`ChooseBlock` / `ParallelBlock` / `RepeatBlock` in Phase 12) can use
+    it as a structural shell over their own children. Toggle / delete /
+    drag handle are conditionally rendered on their callback's presence.
+
+  Storybook stories shipped for each of the new primitives.
+
+  **`@checkstack/integration-script-backend`**
+
+  `ScriptContext` docstring and the `scriptRunConfigSchema.script` field
+  description now point at `generateAutomationContextTypes` so the Phase
+  12 editor wiring is unambiguous — the runtime payload type stays
+  `Record<string, unknown>` (the runner can't know the trigger schema),
+  but the **editor** narrows it per-automation from the subscribed
+  triggers' payload schemas.
+
+### Patch Changes
+
+- Updated dependencies [6d52276]
+  - @checkstack/common@0.12.0

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@checkstack/template-engine",
+  "version": "0.2.0",
+  "license": "Elastic-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@checkstack/common": "0.11.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@checkstack/scripts": "0.3.3",
+    "@checkstack/tsconfig": "0.0.7",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "typecheck": "tsgo -b",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0",
+    "test": "bun test"
+  },
+  "checkstack": {
+    "type": "common"
+  }
+}

package/src/__tests__/parser.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "bun:test";
+import { parseCondition, parseTemplate } from "../parser";
+import { TemplateParseError } from "../errors";
+
+describe("parseTemplate", () => {
+  it("parses pure literal text", () => {
+    const t = parseTemplate("hello world");
+    expect(t.nodes).toHaveLength(1);
+  });
+
+  it("parses a single expression", () => {
+    const t = parseTemplate("{{ foo.bar }}");
+    expect(t.nodes).toHaveLength(1);
+  });
+
+  it("parses interleaved text and expressions", () => {
+    const t = parseTemplate("Hello {{ name }}, you have {{ count }} messages.");
+    expect(t.nodes).toHaveLength(5);
+  });
+
+  it("rejects unterminated expression", () => {
+    expect(() => parseTemplate("hello {{ foo")).toThrow(TemplateParseError);
+  });
+
+  it("rejects unterminated string", () => {
+    expect(() => parseTemplate('{{ "unterminated }}')).toThrow(
+      TemplateParseError,
+    );
+  });
+
+  it("handles escape sequences in strings", () => {
+    const t = parseTemplate('{{ "line1\\nline2" }}');
+    expect(t.nodes).toHaveLength(1);
+  });
+
+  it("parses string-literal index access with hyphen and dot in the key", () => {
+    const t = parseTemplate(
+      '{{ artifacts["integration-jira.issue"].issueKey }}',
+    );
+    expect(t.nodes).toHaveLength(1);
+  });
+
+  it("rejects unbracketed hyphenated member access", () => {
+    expect(() =>
+      parseTemplate("{{ artifacts.integration-jira.issue }}"),
+    ).toThrow(TemplateParseError);
+  });
+});
+
+describe("parseCondition", () => {
+  it("parses a simple equality", () => {
+    const c = parseCondition("trigger.eventId == 'incident.created'");
+    expect(c.source).toBe("trigger.eventId == 'incident.created'");
+  });
+
+  it("parses logical expressions", () => {
+    const c = parseCondition("a && b || c");
+    expect(c).toBeDefined();
+  });
+
+  it("parses ternaries", () => {
+    const c = parseCondition("severity == 'critical' ? 'high' : 'normal'");
+    expect(c).toBeDefined();
+  });
+
+  it("parses pipes with filter calls", () => {
+    const c = parseCondition("title | truncate(40) | upper");
+    expect(c).toBeDefined();
+  });
+
+  it("rejects malformed input", () => {
+    expect(() => parseCondition("foo ==")).toThrow(TemplateParseError);
+  });
+});

package/src/__tests__/renderer.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, it } from "bun:test";
+import { parseCondition, parseTemplate } from "../parser";
+import {
+  evaluate,
+  evaluateBoolean,
+  render,
+} from "../renderer";
+import { TemplateRenderError, UnknownFilterError } from "../errors";
+
+describe("render", () => {
+  it("renders literal text unchanged", () => {
+    expect(render(parseTemplate("hello"), {})).toBe("hello");
+  });
+
+  it("substitutes simple identifiers", () => {
+    const out = render(parseTemplate("Hello {{ name }}!"), {
+      name: "Nico",
+    });
+    expect(out).toBe("Hello Nico!");
+  });
+
+  it("resolves nested member access", () => {
+    const out = render(parseTemplate("{{ trigger.payload.title }}"), {
+      trigger: { payload: { title: "Database down" } },
+    });
+    expect(out).toBe("Database down");
+  });
+
+  it("resolves array index access", () => {
+    const out = render(parseTemplate("{{ items[0] }}"), {
+      items: ["first", "second"],
+    });
+    expect(out).toBe("first");
+  });
+
+  it("resolves a numeric array index after a bracket-key chain", () => {
+    const out = render(
+      parseTemplate('{{ artifacts["x"].tags[0] }}'),
+      { artifacts: { x: { tags: ["first", "second"] } } },
+    );
+    expect(out).toBe("first");
+  });
+
+  it("resolves bracket access with string", () => {
+    const out = render(parseTemplate('{{ nodes["jira-create"].issueKey }}'), {
+      nodes: { "jira-create": { issueKey: "PROJ-42" } },
+    });
+    expect(out).toBe("PROJ-42");
+  });
+
+  it("renders empty string for missing references (non-strict)", () => {
+    const out = render(parseTemplate("Hello {{ missing }}!"), {});
+    expect(out).toBe("Hello !");
+  });
+
+  it("throws in strict mode for missing references", () => {
+    expect(() =>
+      render(parseTemplate("Hello {{ missing }}!"), {}, { strict: true }),
+    ).toThrow(TemplateRenderError);
+  });
+
+  it("supports filter pipes", () => {
+    const out = render(parseTemplate("{{ title | upper }}"), {
+      title: "fire",
+    });
+    expect(out).toBe("FIRE");
+  });
+
+  it("supports filter pipes with arguments", () => {
+    const out = render(parseTemplate('{{ x | default("none") }}'), {});
+    expect(out).toBe("none");
+  });
+
+  it("chains multiple filters", () => {
+    const out = render(parseTemplate("{{ x | default('fallback') | upper }}"), {});
+    expect(out).toBe("FALLBACK");
+  });
+
+  it("renders ternaries", () => {
+    const out = render(
+      parseTemplate("{{ severity == 'critical' ? 'PAGE' : 'log' }}"),
+      { severity: "critical" },
+    );
+    expect(out).toBe("PAGE");
+  });
+
+  it("renders objects as JSON", () => {
+    const out = render(parseTemplate("{{ obj }}"), {
+      obj: { a: 1, b: 2 },
+    });
+    expect(out).toBe('{"a":1,"b":2}');
+  });
+
+  it("throws UnknownFilterError for missing filters", () => {
+    expect(() => render(parseTemplate("{{ x | unknown_filter }}"), { x: 1 })).toThrow(
+      UnknownFilterError,
+    );
+  });
+
+  it("supports truncate filter", () => {
+    const out = render(parseTemplate("{{ msg | truncate(5) }}"), {
+      msg: "Hello World",
+    });
+    expect(out).toBe("Hello…");
+  });
+});
+
+describe("string-literal index access (frontend regression contract)", () => {
+  it("resolves a quoted index key containing a hyphen and dot", () => {
+    const out = render(
+      parseTemplate('{{ artifacts["integration-jira.issue"].issueKey }}'),
+      { artifacts: { "integration-jira.issue": { issueKey: "ABC-1" } } },
+    );
+    expect(out).toBe("ABC-1");
+  });
+
+  it("resolves dotted member access on variables", () => {
+    const out = render(parseTemplate("{{ variables.foo }}"), {
+      variables: { foo: "bar" },
+    });
+    expect(out).toBe("bar");
+  });
+
+  it("resolves the artifacts.<id>.<name>.<field> reference form", () => {
+    const out = render(
+      parseTemplate("{{ artifacts.create_issue.issue.issueKey }}"),
+      {
+        artifacts: {
+          create_issue: { issue: { issueKey: "PROJ-7" } },
+        },
+      },
+    );
+    expect(out).toBe("PROJ-7");
+  });
+});
+
+describe("evaluate / evaluateBoolean", () => {
+  it("evaluates equality conditions", () => {
+    expect(
+      evaluateBoolean(parseCondition("a == b"), { a: 1, b: 1 }),
+    ).toBe(true);
+  });
+
+  it("evaluates string equality with quoted RHS", () => {
+    expect(
+      evaluateBoolean(
+        parseCondition("trigger.eventId == 'incident.created'"),
+        { trigger: { eventId: "incident.created" } },
+      ),
+    ).toBe(true);
+  });
+
+  it("evaluates logical AND/OR short-circuit", () => {
+    expect(evaluateBoolean(parseCondition("false && missing.foo"), {})).toBe(
+      false,
+    );
+    expect(evaluateBoolean(parseCondition("true || missing.foo"), {})).toBe(
+      true,
+    );
+  });
+
+  it("evaluates negation", () => {
+    expect(evaluateBoolean(parseCondition("!enabled"), { enabled: false })).toBe(
+      true,
+    );
+  });
+
+  it("evaluates comparison operators", () => {
+    expect(evaluateBoolean(parseCondition("3 < 4"), {})).toBe(true);
+    expect(evaluateBoolean(parseCondition("4 >= 4"), {})).toBe(true);
+  });
+
+  it("returns raw value from evaluate", () => {
+    expect(evaluate(parseCondition("severity"), { severity: "critical" })).toBe(
+      "critical",
+    );
+  });
+
+  it("treats empty arrays and objects as falsy (consistent with truthiness rule)", () => {
+    expect(evaluateBoolean(parseCondition("items"), { items: [] })).toBe(false);
+    expect(evaluateBoolean(parseCondition("obj"), { obj: {} })).toBe(false);
+  });
+});

package/src/ast.ts

@@ -0,0 +1,101 @@
+import type { SourceRange } from "./types";
+
+/**
+ * AST node kinds for the expression sublanguage. Templates are made up of
+ * `TextNode` + `ExpressionNode` at the top level; expressions form their
+ * own tree of `Expr` nodes.
+ */
+export type TemplateNode = TextNode | ExpressionNode;
+
+export interface TextNode {
+  kind: "text";
+  value: string;
+  range: SourceRange;
+}
+
+export interface ExpressionNode {
+  kind: "expression";
+  expression: Expr;
+  range: SourceRange;
+}
+
+/**
+ * Expression AST. Discriminated union over `kind`. Every node carries a
+ * source range for error reporting.
+ */
+export type Expr =
+  | LiteralExpr
+  | IdentifierExpr
+  | MemberExpr
+  | IndexExpr
+  | TernaryExpr
+  | BinaryExpr
+  | UnaryExpr
+  | PipeExpr;
+
+export interface LiteralExpr {
+  kind: "literal";
+  value: string | number | boolean | null;
+  range: SourceRange;
+}
+
+export interface IdentifierExpr {
+  kind: "identifier";
+  name: string;
+  range: SourceRange;
+}
+
+export interface MemberExpr {
+  kind: "member";
+  object: Expr;
+  property: string;
+  range: SourceRange;
+}
+
+export interface IndexExpr {
+  kind: "index";
+  object: Expr;
+  index: Expr;
+  range: SourceRange;
+}
+
+export interface TernaryExpr {
+  kind: "ternary";
+  condition: Expr;
+  consequent: Expr;
+  alternate: Expr;
+  range: SourceRange;
+}
+
+export type BinaryOp =
+  | "=="
+  | "!="
+  | "<"
+  | ">"
+  | "<="
+  | ">="
+  | "&&"
+  | "||";
+
+export interface BinaryExpr {
+  kind: "binary";
+  op: BinaryOp;
+  left: Expr;
+  right: Expr;
+  range: SourceRange;
+}
+
+export interface UnaryExpr {
+  kind: "unary";
+  op: "!";
+  operand: Expr;
+  range: SourceRange;
+}
+
+export interface PipeExpr {
+  kind: "pipe";
+  value: Expr;
+  filter: string;
+  args: Expr[];
+  range: SourceRange;
+}

package/src/errors.ts

@@ -0,0 +1,74 @@
+import type { SourcePosition, SourceRange } from "./types";
+
+/**
+ * Base error for all template-engine failures. Always carries a source
+ * range so editors can render an inline marker.
+ */
+export class TemplateError extends Error {
+  readonly range: SourceRange;
+  readonly source: string;
+
+  constructor(args: {
+    message: string;
+    source: string;
+    range: SourceRange;
+  }) {
+    super(args.message);
+    this.name = "TemplateError";
+    this.range = args.range;
+    this.source = args.source;
+  }
+}
+
+export class TemplateParseError extends TemplateError {
+  constructor(args: {
+    message: string;
+    source: string;
+    range: SourceRange;
+  }) {
+    super(args);
+    this.name = "TemplateParseError";
+  }
+}
+
+export class TemplateRenderError extends TemplateError {
+  /** Path of access that failed, when the failure was a missing reference. */
+  readonly path?: string;
+
+  constructor(args: {
+    message: string;
+    source: string;
+    range: SourceRange;
+    path?: string;
+  }) {
+    super(args);
+    this.name = "TemplateRenderError";
+    this.path = args.path;
+  }
+}
+
+export class UnknownFilterError extends TemplateRenderError {
+  readonly filterName: string;
+
+  constructor(args: {
+    filterName: string;
+    source: string;
+    range: SourceRange;
+  }) {
+    super({
+      message: `Unknown filter "${args.filterName}"`,
+      source: args.source,
+      range: args.range,
+    });
+    this.name = "UnknownFilterError";
+    this.filterName = args.filterName;
+  }
+}
+
+/**
+ * Construct a single-point range — useful when the parser knows where
+ * something went wrong but not where the offending construct ended.
+ */
+export function pointRange(pos: SourcePosition): SourceRange {
+  return { start: pos, end: pos };
+}