@kirrosh/zond 0.12.7 → 0.13.0

package/CHANGELOG.md

@@ -50,6 +50,16 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 
+- **Extended YAML test format** — 12 new assertion operators, flow control, and data transforms:
+  - **Assertion operators**: `not_equals`, `not_contains`, `gte`, `lte`, `length`, `length_gt/gte/lt/lte`
+  - **Array assertions**: `each` (every element matches), `contains_item` (at least one matches), `set_equals` (order-independent comparison)
+  - **Flow control**: `skip_if` (conditional skip with expression evaluator), `retry_until` (retry with condition/max_attempts/delay_ms), `for_each` (iterate over array)
+  - **Data transforms**: `set` steps with directives — `concat`, `append`, `length`, `get`, `first`, `map_field`
+  - **Generator**: `{{$isoTimestamp}}` — ISO 8601 timestamp string
+  - **Expression evaluator**: supports `==`, `!=`, `>`, `<`, `>=`, `<=` for skip_if/retry_until conditions
+  - Guide-builder YAML cheatsheet updated with all new features
+  - Full backward compatibility — all existing tests continue to work unchanged
+
 - **MCP feedback improvements**
   - `diagnose_failure` now includes `response_headers` in failure output (e.g. `X-Ably-ErrorMessage`)
   - `generate_tests_guide`: annotates `any`-typed request bodies with a warning comment

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirrosh/zond",
-  "version": "0.12.7",
+  "version": "0.13.0",
   "description": "API testing platform — define tests in YAML, run from CLI or WebUI, generate from OpenAPI specs",
   "license": "MIT",
   "module": "index.ts",

package/src/core/generator/guide-builder.ts

@@ -120,7 +120,7 @@ Use \`json:\` for JSON request bodies. Do NOT use \`body:\` — it is not a vali
 For form-encoded: use \`form:\` instead of \`json:\`.
 
 ### Built-in generators
-\`{{$uuid}}\`, \`{{$randomInt}}\`, \`{{$timestamp}}\`, \`{{$randomName}}\`, \`{{$randomEmail}}\`, \`{{$randomString}}\`
+\`{{$uuid}}\`, \`{{$randomInt}}\`, \`{{$timestamp}}\`, \`{{$isoTimestamp}}\`, \`{{$randomName}}\`, \`{{$randomEmail}}\`, \`{{$randomString}}\`
 
 ### Variable capture & interpolation
 \`\`\`yaml
@@ -139,6 +139,58 @@ For form-encoded: use \`form:\` instead of \`json:\`.
       id: { equals: "{{created_id}}" }
 \`\`\`
 
+### Array assertions
+\`\`\`yaml
+items:
+  each:                          # every element must match
+    status: { not_equals: "deleted" }
+    id: { type: integer }
+
+items:
+  contains_item:                 # at least one element matches
+    name: { contains: "test" }
+
+ids:
+  set_equals: [1, 2, 3]         # same elements, order-independent
+\`\`\`
+
+### Flow control
+\`\`\`yaml
+  # skip_if — skip step when condition is true (after variable substitution)
+  - name: Delete only if exists
+    DELETE: /items/{{item_id}}
+    skip_if: "{{item_id}} == 0"
+    expect:
+      status: 204
+
+  # retry_until — repeat request until condition met
+  - name: Wait for processing
+    GET: /jobs/{{job_id}}
+    retry_until:
+      condition: "{{status}} == completed"
+      max_attempts: 5
+      delay_ms: 1000
+    expect:
+      status: 200
+
+  # for_each — repeat step for each item in array
+  - name: Delete item
+    DELETE: /items/{{id}}
+    for_each:
+      var: id
+      in: "{{item_ids}}"
+    expect:
+      status: [200, 204]
+
+  # set — transform variables without HTTP request
+  - name: Extract IDs
+    set:
+      all_ids: { map_field: ["{{items}}", "id"] }
+      count: { length: "{{items}}" }
+      first_item: { first: "{{items}}" }
+      merged: { concat: ["{{list_a}}", "{{list_b}}"] }
+\`\`\`
+
 ### Coverage matching
 Use spec paths with \`{param}\` placeholders in the path for coverage to match:
 - Spec says \`GET /products/{id}\` → write \`GET: /products/1\` (hardcode the value)

package/src/core/generator/serializer.ts

@@ -93,17 +93,53 @@ export function serializeSuite(suite: RawSuite): string {
       serializeValue(test.query, 3, lines);
     }
 
-    // expect
-    lines.push("    expect:");
-    if (test.expect.status !== undefined) {
-      lines.push(`      status: ${test.expect.status}`);
+    // skip_if
+    if (test.skip_if) {
+      lines.push(`    skip_if: ${yamlScalar(String(test.skip_if))}`);
+    }
+
+    // retry_until
+    if (test.retry_until && typeof test.retry_until === "object") {
+      const rt = test.retry_until as Record<string, unknown>;
+      lines.push("    retry_until:");
+      if (rt.condition !== undefined) lines.push(`      condition: ${yamlScalar(String(rt.condition))}`);
+      if (rt.max_attempts !== undefined) lines.push(`      max_attempts: ${rt.max_attempts}`);
+      if (rt.delay_ms !== undefined) lines.push(`      delay_ms: ${rt.delay_ms}`);
     }
-    if (test.expect.body) {
-      lines.push("      body:");
-      for (const [key, rule] of Object.entries(test.expect.body)) {
-        lines.push(`        ${key}:`);
-        for (const [rk, rv] of Object.entries(rule)) {
-          lines.push(`          ${rk}: ${yamlScalar(String(rv))}`);
+
+    // for_each
+    if (test.for_each && typeof test.for_each === "object") {
+      const fe = test.for_each as Record<string, unknown>;
+      lines.push("    for_each:");
+      if (fe.var !== undefined) lines.push(`      var: ${yamlScalar(String(fe.var))}`);
+      if (fe.in !== undefined) lines.push(`      in: ${yamlScalar(String(fe.in))}`);
+    }
+
+    // set
+    if (test.set && typeof test.set === "object") {
+      lines.push("    set:");
+      serializeValue(test.set, 3, lines);
+    }
+
+    // expect
+    const hasExpect = test.expect && (test.expect.status !== undefined || test.expect.body);
+    if (hasExpect) {
+      lines.push("    expect:");
+      if (test.expect.status !== undefined) {
+        lines.push(`      status: ${test.expect.status}`);
+      }
+      if (test.expect.body) {
+        lines.push("      body:");
+        for (const [key, rule] of Object.entries(test.expect.body)) {
+          lines.push(`        ${key}:`);
+          for (const [rk, rv] of Object.entries(rule)) {
+            if (typeof rv === "object" && rv !== null) {
+              lines.push(`          ${rk}:`);
+              serializeValue(rv, 6, lines);
+            } else {
+              lines.push(`          ${rk}: ${yamlScalar(String(rv))}`);
+            }
+          }
         }
       }
     }

package/src/core/parser/schema.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { TestSuite, TestStep, AssertionRule, TestStepExpect, SuiteConfig } from "./types.ts";
+import type { TestSuite, TestStep, AssertionRule, TestStepExpect, SuiteConfig, RetryUntil, ForEach } from "./types.ts";
 
 const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const;
 
@@ -26,11 +26,19 @@ function extractMethodAndPath(raw: unknown): unknown {
     return { ...rest, method: foundMethod, path };
   }
 
+  // set-only step: no HTTP method required
+  if (obj.set && !obj.method) {
+    return { ...obj, method: "GET", path: "" };
+  }
+
   return raw;
 }
 
 const ASSERTION_KEYS = new Set([
-  "capture", "type", "equals", "contains", "matches", "gt", "lt", "exists",
+  "capture", "type", "equals", "not_equals", "contains", "not_contains",
+  "matches", "gt", "lt", "gte", "lte", "exists",
+  "length", "length_gt", "length_gte", "length_lt", "length_lte",
+  "each", "contains_item", "set_equals",
 ]);
 
 /**
@@ -68,7 +76,7 @@ export function flattenBodyAssertions(body: Record<string, unknown>): Record<str
   return result;
 }
 
-const AssertionRuleSchema: z.ZodType<AssertionRule> = z.preprocess(
+const AssertionRuleSchemaInner: z.ZodType<AssertionRule> = z.preprocess(
   (val) => {
     if (typeof val === "string") return { type: val };
     if (val === null || val === undefined) return { exists: true };
@@ -86,14 +94,28 @@ const AssertionRuleSchema: z.ZodType<AssertionRule> = z.preprocess(
     capture: z.string().optional(),
     type: z.enum(["string", "integer", "number", "boolean", "array", "object"]).optional(),
     equals: z.unknown().optional(),
+    not_equals: z.unknown().optional(),
     contains: z.string().optional(),
+    not_contains: z.string().optional(),
     matches: z.string().optional(),
     gt: z.number().optional(),
     lt: z.number().optional(),
+    gte: z.number().optional(),
+    lte: z.number().optional(),
     exists: z.boolean().optional(),
+    length: z.number().int().optional(),
+    length_gt: z.number().int().optional(),
+    length_gte: z.number().int().optional(),
+    length_lt: z.number().int().optional(),
+    length_lte: z.number().int().optional(),
+    each: z.record(z.string(), z.lazy(() => AssertionRuleSchemaInner)).optional(),
+    contains_item: z.record(z.string(), z.lazy(() => AssertionRuleSchemaInner)).optional(),
+    set_equals: z.unknown().optional(),
   }),
 ) as z.ZodType<AssertionRule>;
 
+const AssertionRuleSchema = AssertionRuleSchemaInner;
+
 const TestStepExpectSchema: z.ZodType<TestStepExpect> = z.preprocess(
   (val) => {
     if (typeof val !== "object" || val === null) return val;
@@ -117,8 +139,29 @@ const TestStepExpectSchema: z.ZodType<TestStepExpect> = z.preprocess(
   }),
 ) as z.ZodType<TestStepExpect>;
 
+const RetryUntilSchema: z.ZodType<RetryUntil> = z.object({
+  condition: z.string(),
+  max_attempts: z.number().int().positive(),
+  delay_ms: z.number().int().nonnegative(),
+});
+
+const ForEachSchema: z.ZodType<ForEach> = z.object({
+  var: z.string(),
+  in: z.unknown(),
+});
+
 const TestStepSchema: z.ZodType<TestStep> = z.preprocess(
-  extractMethodAndPath,
+  (raw) => {
+    const obj = extractMethodAndPath(raw);
+    // Make expect optional for set-only steps
+    if (typeof obj === "object" && obj !== null) {
+      const o = obj as Record<string, unknown>;
+      if (o.set && !o.expect) {
+        o.expect = {};
+      }
+    }
+    return obj;
+  },
   z.object({
     name: z.string(),
     method: z.enum(HTTP_METHODS),
@@ -128,6 +171,10 @@ const TestStepSchema: z.ZodType<TestStep> = z.preprocess(
     form: z.record(z.string(), z.string()).optional(),
     query: z.record(z.string(), z.string()).optional(),
     expect: TestStepExpectSchema,
+    skip_if: z.string().optional(),
+    retry_until: RetryUntilSchema.optional(),
+    for_each: ForEachSchema.optional(),
+    set: z.record(z.string(), z.unknown()).optional(),
   }),
 ) as z.ZodType<TestStep>;
 

package/src/core/parser/types.ts

@@ -4,11 +4,23 @@ export interface AssertionRule {
   capture?: string;
   type?: "string" | "integer" | "number" | "boolean" | "array" | "object";
   equals?: unknown;
+  not_equals?: unknown;
   contains?: string;
+  not_contains?: string;
   matches?: string;
   gt?: number;
   lt?: number;
+  gte?: number;
+  lte?: number;
   exists?: boolean;
+  length?: number;
+  length_gt?: number;
+  length_gte?: number;
+  length_lt?: number;
+  length_lte?: number;
+  each?: Record<string, AssertionRule>;
+  contains_item?: Record<string, AssertionRule>;
+  set_equals?: unknown;
 }
 
 export interface TestStepExpect {
@@ -18,6 +30,17 @@ export interface TestStepExpect {
   duration?: number;
 }
 
+export interface RetryUntil {
+  condition: string;
+  max_attempts: number;
+  delay_ms: number;
+}
+
+export interface ForEach {
+  var: string;
+  in: unknown;
+}
+
 export interface TestStep {
   name: string;
   method: HttpMethod;
@@ -27,6 +50,10 @@ export interface TestStep {
   form?: Record<string, string>;
   query?: Record<string, string>;
   expect: TestStepExpect;
+  skip_if?: string;
+  retry_until?: RetryUntil;
+  for_each?: ForEach;
+  set?: Record<string, unknown>;
 }
 
 export interface SuiteConfig {

package/src/core/parser/variables.ts

@@ -19,6 +19,7 @@ function randomChars(len: number): string {
 export const GENERATORS: Record<string, () => string | number> = {
   "$uuid": () => crypto.randomUUID(),
   "$timestamp": () => Math.floor(Date.now() / 1000),
+  "$isoTimestamp": () => new Date().toISOString(),
   "$randomName": () => randomFrom(NAMES),
   "$randomEmail": () => `${randomChars(8).toLowerCase()}@test.com`,
   "$randomInt": () => Math.floor(Math.random() * 10000),

package/src/core/runner/assertions.ts

@@ -90,6 +90,132 @@ function checkRule(path: string, rule: AssertionRule, actual: unknown): Assertio
     });
   }
 
+  if (rule.not_equals !== undefined) {
+    results.push({
+      field, rule: `not_equals ${JSON.stringify(rule.not_equals)}`,
+      passed: !deepEquals(actual, rule.not_equals), actual, expected: rule.not_equals,
+    });
+  }
+
+  if (rule.not_contains !== undefined) {
+    const passed = typeof actual === "string" && !actual.includes(rule.not_contains);
+    results.push({
+      field, rule: `not_contains "${rule.not_contains}"`,
+      passed, actual, expected: rule.not_contains,
+    });
+  }
+
+  if (rule.gte !== undefined) {
+    const passed = typeof actual === "number" && actual >= rule.gte;
+    results.push({
+      field, rule: `gte ${rule.gte}`,
+      passed, actual, expected: rule.gte,
+    });
+  }
+
+  if (rule.lte !== undefined) {
+    const passed = typeof actual === "number" && actual <= rule.lte;
+    results.push({
+      field, rule: `lte ${rule.lte}`,
+      passed, actual, expected: rule.lte,
+    });
+  }
+
+  if (rule.length !== undefined) {
+    const hasLength = (Array.isArray(actual) || typeof actual === "string");
+    const passed = hasLength && (actual as string | unknown[]).length === rule.length;
+    results.push({
+      field, rule: `length ${rule.length}`,
+      passed, actual: hasLength ? (actual as string | unknown[]).length : describeType(actual), expected: rule.length,
+    });
+  }
+
+  if (rule.length_gt !== undefined) {
+    const hasLength = (Array.isArray(actual) || typeof actual === "string");
+    const passed = hasLength && (actual as string | unknown[]).length > rule.length_gt;
+    results.push({
+      field, rule: `length_gt ${rule.length_gt}`,
+      passed, actual: hasLength ? (actual as string | unknown[]).length : describeType(actual), expected: rule.length_gt,
+    });
+  }
+
+  if (rule.length_gte !== undefined) {
+    const hasLength = (Array.isArray(actual) || typeof actual === "string");
+    const passed = hasLength && (actual as string | unknown[]).length >= rule.length_gte;
+    results.push({
+      field, rule: `length_gte ${rule.length_gte}`,
+      passed, actual: hasLength ? (actual as string | unknown[]).length : describeType(actual), expected: rule.length_gte,
+    });
+  }
+
+  if (rule.length_lt !== undefined) {
+    const hasLength = (Array.isArray(actual) || typeof actual === "string");
+    const passed = hasLength && (actual as string | unknown[]).length < rule.length_lt;
+    results.push({
+      field, rule: `length_lt ${rule.length_lt}`,
+      passed, actual: hasLength ? (actual as string | unknown[]).length : describeType(actual), expected: rule.length_lt,
+    });
+  }
+
+  if (rule.length_lte !== undefined) {
+    const hasLength = (Array.isArray(actual) || typeof actual === "string");
+    const passed = hasLength && (actual as string | unknown[]).length <= rule.length_lte;
+    results.push({
+      field, rule: `length_lte ${rule.length_lte}`,
+      passed, actual: hasLength ? (actual as string | unknown[]).length : describeType(actual), expected: rule.length_lte,
+    });
+  }
+
+  if (rule.each !== undefined) {
+    if (!Array.isArray(actual)) {
+      results.push({ field, rule: "each", passed: false, actual: describeType(actual), expected: "array" });
+    } else {
+      for (let i = 0; i < actual.length; i++) {
+        for (const [subPath, subRule] of Object.entries(rule.each)) {
+          const subActual = getByPath(actual[i], subPath);
+          const subResults = checkRule(`${path}[${i}].${subPath}`, subRule, subActual);
+          results.push(...subResults);
+        }
+      }
+    }
+  }
+
+  if (rule.contains_item !== undefined) {
+    if (!Array.isArray(actual)) {
+      results.push({ field, rule: "contains_item", passed: false, actual: describeType(actual), expected: "array" });
+    } else {
+      const found = actual.some((item) => {
+        for (const [subPath, subRule] of Object.entries(rule.contains_item!)) {
+          const subActual = getByPath(item, subPath);
+          const subResults = checkRule("", subRule, subActual);
+          if (subResults.some(r => !r.passed)) return false;
+        }
+        return true;
+      });
+      results.push({
+        field, rule: "contains_item",
+        passed: found, actual: `array(${actual.length})`, expected: "at least one matching item",
+      });
+    }
+  }
+
+  if (rule.set_equals !== undefined) {
+    if (!Array.isArray(actual) || !Array.isArray(rule.set_equals)) {
+      results.push({
+        field, rule: "set_equals",
+        passed: false, actual: describeType(actual), expected: "both must be arrays",
+      });
+    } else {
+      const actualSet = new Set(actual.map(v => JSON.stringify(v)));
+      const expectedSet = new Set((rule.set_equals as unknown[]).map(v => JSON.stringify(v)));
+      const passed = actualSet.size === expectedSet.size && [...actualSet].every(v => expectedSet.has(v));
+      results.push({
+        field, rule: "set_equals",
+        passed, actual, expected: rule.set_equals,
+      });
+    }
+  }
+
   return results;
 }
 

package/src/core/runner/executor.ts

@@ -1,8 +1,10 @@
-import type { TestSuite, Environment } from "../parser/types.ts";
+import type { TestSuite, TestStep, Environment } from "../parser/types.ts";
 import { substituteString, substituteStep, substituteDeep, extractVariableReferences } from "../parser/variables.ts";
 import type { TestRunResult, StepResult, HttpRequest } from "./types.ts";
 import { executeRequest, type FetchOptions } from "./http-client.ts";
 import { checkAssertions, extractCaptures } from "./assertions.ts";
+import { evaluateExpr } from "./expr-eval.ts";
+import { applyTransform } from "./transforms.ts";
 
 function buildUrl(baseUrl: string | undefined, path: string, query?: Record<string, string>): string {
   let url = baseUrl ? `${baseUrl.replace(/\/+$/, "")}${path}` : path;
@@ -38,7 +40,61 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
     follow_redirects: suite.config.follow_redirects,
   };
 
-  for (const step of suite.tests) {
+  // Expand steps lazily (for_each needs current variables)
+  let stepIndex = 0;
+  const rawSteps = [...suite.tests];
+
+  while (stepIndex < rawSteps.length) {
+    const step = rawSteps[stepIndex]!;
+    stepIndex++;
+
+    // Expand for_each: insert expanded steps and skip current
+    if (step.for_each) {
+      const resolvedIn = substituteDeep(step.for_each.in, variables);
+      const items = Array.isArray(resolvedIn) ? resolvedIn : [];
+      const expanded: TestStep[] = [];
+      for (const item of items) {
+        const { for_each: _, ...rest } = step;
+        expanded.push({ ...rest, name: `${step.name} [${step.for_each.var}=${JSON.stringify(item)}]` } as TestStep);
+        // We'll inject the variable right before executing each expanded step
+        // Store the var assignment via a set field
+      }
+      // Insert expanded steps at current position
+      rawSteps.splice(stepIndex, 0, ...expanded);
+      // Set the for_each variable for each expanded step
+      for (let i = 0; i < items.length; i++) {
+        const expandedStep = rawSteps[stepIndex + i]!;
+        // Temporarily inject into variables when we reach this step
+        // We need a way to pass the variable — use a hidden _for_each_vars
+        (expandedStep as Record<string, unknown>).__for_each_var = { key: step.for_each.var, value: items[i] };
+      }
+      continue;
+    }
+
+    // Inject for_each variable if present
+    const forEachData = (step as Record<string, unknown>).__for_each_var as { key: string; value: unknown } | undefined;
+    if (forEachData) {
+      variables[forEachData.key] = forEachData.value;
+      delete (step as Record<string, unknown>).__for_each_var;
+    }
+
+    // Handle set-only steps (no HTTP request)
+    if (step.set && step.path === "") {
+      for (const [key, rawDirective] of Object.entries(step.set)) {
+        const substituted = substituteDeep(rawDirective, variables);
+        variables[key] = applyTransform(substituted);
+      }
+      steps.push({
+        name: step.name,
+        status: "pass",
+        duration_ms: 0,
+        request: { method: "", url: "", headers: {} },
+        assertions: [],
+        captures: {},
+      });
+      continue;
+    }
+
     // Skip check: if step references a failed capture variable, skip it
     const referencedVars = extractVariableReferences(step);
     const missingCapture = referencedVars.find((v) => failedCaptures.has(v));
@@ -47,6 +103,15 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
       continue;
     }
 
+    // skip_if evaluation
+    if (step.skip_if) {
+      const exprAfterSubst = String(substituteString(step.skip_if, variables));
+      if (evaluateExpr(exprAfterSubst)) {
+        steps.push(makeSkippedResult(step.name, `Skipped: ${step.skip_if}`));
+        continue;
+      }
+    }
+
     // Substitute variables
     const resolved = substituteStep(step, variables);
 
@@ -104,6 +169,59 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
       continue;
     }
 
+    // retry_until wrapper
+    if (step.retry_until) {
+      const rt = step.retry_until;
+      let lastStepResult: StepResult | undefined;
+      for (let attempt = 0; attempt < rt.max_attempts; attempt++) {
+        try {
+          const response = await executeRequest(request, fetchOptions);
+          const captures = extractCaptures(resolved.expect.body, response.body_parsed);
+          const assertions = checkAssertions(resolved.expect, response);
+          const allPassed = assertions.every((a) => a.passed);
+
+          lastStepResult = {
+            name: step.name,
+            status: allPassed ? "pass" : "fail",
+            duration_ms: response.duration_ms,
+            request,
+            response,
+            assertions,
+            captures,
+          };
+
+          // Evaluate condition with response context
+          const condVars: Record<string, unknown> = { ...variables, ...captures, status: response.status };
+          if (response.body_parsed && typeof response.body_parsed === "object") {
+            for (const [k, v] of Object.entries(response.body_parsed as Record<string, unknown>)) {
+              condVars[k] = v;
+            }
+          }
+          const condStr = String(substituteString(rt.condition, condVars));
+          if (evaluateExpr(condStr)) {
+            Object.assign(variables, captures);
+            break;
+          }
+
+          if (attempt < rt.max_attempts - 1) {
+            await new Promise((resolve) => setTimeout(resolve, rt.delay_ms));
+          }
+        } catch (err) {
+          lastStepResult = {
+            name: step.name,
+            status: "error",
+            duration_ms: 0,
+            request,
+            assertions: [],
+            captures: {},
+            error: err instanceof Error ? err.message : String(err),
+          };
+        }
+      }
+      if (lastStepResult) steps.push(lastStepResult);
+      continue;
+    }
+
     try {
       const response = await executeRequest(request, fetchOptions);
 

package/src/core/runner/expr-eval.ts

@@ -0,0 +1,41 @@
+const OPERATORS = ["!=", "==", ">=", "<=", ">", "<"] as const;
+
+export function evaluateExpr(expr: string): boolean {
+  const trimmed = expr.trim();
+  if (trimmed === "") return false;
+
+  for (const op of OPERATORS) {
+    const idx = trimmed.indexOf(op);
+    if (idx !== -1) {
+      const left = trimmed.slice(0, idx).trim();
+      const right = trimmed.slice(idx + op.length).trim();
+      return compareValues(left, right, op);
+    }
+  }
+
+  // No operator — truthiness
+  return isTruthy(trimmed);
+}
+
+function compareValues(left: string, right: string, op: string): boolean {
+  const lNum = Number(left);
+  const rNum = Number(right);
+  const numeric = !isNaN(lNum) && !isNaN(rNum) && left !== "" && right !== "";
+
+  switch (op) {
+    case "==": return numeric ? lNum === rNum : left === right;
+    case "!=": return numeric ? lNum !== rNum : left !== right;
+    case ">":  return numeric ? lNum > rNum : left > right;
+    case "<":  return numeric ? lNum < rNum : left < right;
+    case ">=": return numeric ? lNum >= rNum : left >= right;
+    case "<=": return numeric ? lNum <= rNum : left <= right;
+    default: return false;
+  }
+}
+
+function isTruthy(value: string): boolean {
+  if (value === "" || value === "0" || value === "false" || value === "null" || value === "undefined") {
+    return false;
+  }
+  return true;
+}

package/src/core/runner/transforms.ts

@@ -0,0 +1,65 @@
+const DIRECTIVES = new Set(["concat", "append", "length", "get", "first", "map_field"]);
+
+export function applyTransform(directive: unknown): unknown {
+  if (typeof directive !== "object" || directive === null || Array.isArray(directive)) {
+    return directive;
+  }
+
+  const obj = directive as Record<string, unknown>;
+  const keys = Object.keys(obj);
+
+  if (keys.length !== 1 || !DIRECTIVES.has(keys[0]!)) {
+    return directive;
+  }
+
+  const op = keys[0]!;
+  const arg = obj[op];
+
+  switch (op) {
+    case "concat": {
+      if (!Array.isArray(arg)) return directive;
+      const result: unknown[] = [];
+      for (const item of arg) {
+        if (Array.isArray(item)) result.push(...item);
+        else result.push(item);
+      }
+      return result;
+    }
+    case "append": {
+      if (!Array.isArray(arg) || arg.length < 2) return directive;
+      const arr = Array.isArray(arg[0]) ? [...arg[0]] : [];
+      return [...arr, ...arg.slice(1)];
+    }
+    case "length": {
+      if (Array.isArray(arg)) return arg.length;
+      if (typeof arg === "string") return arg.length;
+      return 0;
+    }
+    case "get": {
+      if (!Array.isArray(arg) || arg.length < 2) return directive;
+      const [source, index] = arg;
+      if (Array.isArray(source) && typeof index === "number") return source[index];
+      if (typeof source === "object" && source !== null && typeof index === "string") {
+        return (source as Record<string, unknown>)[index];
+      }
+      return undefined;
+    }
+    case "first": {
+      if (Array.isArray(arg)) return arg[0];
+      return undefined;
+    }
+    case "map_field": {
+      if (!Array.isArray(arg) || arg.length < 2) return directive;
+      const [items, field] = arg;
+      if (!Array.isArray(items) || typeof field !== "string") return directive;
+      return items.map((item) => {
+        if (typeof item === "object" && item !== null) {
+          return (item as Record<string, unknown>)[field];
+        }
+        return undefined;
+      });
+    }
+    default:
+      return directive;
+  }
+}