rippletide-package 0.1.0

package/tide/src/compile.js

@@ -0,0 +1,193 @@
+// Compile step: POLICY.md + the agent's tools -> deterministic rules.
+// The one place an LLM is used, only at authoring time. Adapted from tide-test's
+// rule-generation prompt/normalization, targeting a coding agent's tools (the Codex shell
+// action). Calls the user's own OpenAI key via the Responses API. Enforcement never uses an LLM.
+
+import fs from "node:fs";
+import { validateBundle } from "./engine.js";
+import { evaluate, parse } from "./expr.js";
+import { actionsFor } from "./ontology.js";
+
+export const DEFAULT_MODEL = "gpt-5.4";
+
+const SYSTEM =
+  "You generate deterministic Tide policy rules that gate a coding agent's tool calls. " +
+  "Output JSON only. No markdown. Rules must be reviewable and safe. Prefer shadow only when unsure.";
+
+const INSTRUCTIONS =
+  'Return {"rules":[{id,action,when?,requires?,verdict,mode,to?,reason,test_params}]}. ' +
+  "`when` MUST be a single TideExpr string, never an object. Use only the provided action names. " +
+  "Reference call arguments as params.<field> (e.g. params.command), never input.<field>. " +
+  "For text checks use text_matches(params.field, 'regex') — a case-insensitive regex; you MAY use " +
+  "\\b, \\., \\s in the regex. Do NOT use JavaScript .match, regex literals, or ?. . " +
+  "Combine conditions with && and ||. `requires` is an array of prior action names (sequencing); " +
+  "prefer it over when:true. Explicit must/must-not policy => mode enforce; weak/ambiguous => mode shadow. " +
+  "verdict is 'deny' (block) or 'escalate' (hold for human); escalate MUST include a 'to' group. " +
+  "Give each rule a clear kebab-case id and a human 'reason'. " +
+  "test_params MUST be concrete arguments that make the rule fire (so it becomes a golden test).";
+
+export function readPolicy(p) {
+  try { return fs.readFileSync(p, "utf8").trim(); } catch { return ""; }
+}
+
+export async function compilePolicy({ policyPath, agent = "codex", projectDir = ".tide",
+                                      model = null, apiKey = null } = {}) {
+  const actions = actionsFor(agent);
+  const policyText = readPolicy(policyPath);
+  apiKey = apiKey || process.env.OPENAI_API_KEY;
+  model = model || process.env.TIDE_MODEL || process.env.OPENAI_MODEL || DEFAULT_MODEL;
+
+  let source = "heuristic";
+  let rawRules = [];
+  if (apiKey) {
+    try {
+      rawRules = await openaiRules(policyText, actions, model, apiKey);
+      source = "llm";
+    } catch (e) {
+      console.error(`tide: LLM rule generation failed (${e.message}); using local heuristics`);
+      rawRules = [];
+    }
+  }
+  if (!rawRules.length) { rawRules = heuristicRules(policyText, actions); source = "heuristic"; }
+
+  const { rules, scenarios } = normalize(rawRules, actions);
+  const bundle = { name: (projectDir.split("/").pop() || "tide"), version: "1", actions, rules };
+  const diagnostics = validateBundle(bundle);
+  const findings = renderFindings(policyText, agent, bundle, scenarios, diagnostics, source);
+  return { bundle, scenarios, diagnostics, source, findings };
+}
+
+// ---------- LLM ----------
+async function openaiRules(policyText, actions, model, apiKey) {
+  const base = (process.env.OPENAI_BASE_URL || "https://api.openai.com/v1").replace(/\/+$/, "");
+  const tools = Object.entries(actions).map(([name, spec]) =>
+    ({ name, description: spec.description ?? "", params: spec.params ?? {} }));
+  const body = {
+    model,
+    input: [
+      { role: "system", content: SYSTEM },
+      { role: "user", content: JSON.stringify({
+        instructions: INSTRUCTIONS,
+        policy: policyText || "No explicit policy text. Suggest basic safety guardrails from the tools.",
+        tools,
+      }) },
+    ],
+    text: { format: { type: "json_object" } },
+  };
+  const res = await fetch(`${base}/responses`, {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) throw new Error(`OpenAI ${res.status}`);
+  const data = await res.json();
+  const parsed = JSON.parse(extractText(data));
+  return Array.isArray(parsed?.rules) ? parsed.rules : [];
+}
+
+function extractText(data) {
+  if (data.output_text) return data.output_text;
+  for (const item of data.output ?? []) for (const c of item.content ?? []) if (c.text) return c.text;
+  const chat = data.choices?.[0]?.message?.content;
+  if (chat) return chat;
+  throw new Error("no text in model response");
+}
+
+// ---------- normalization (from tide-test normalizeLlmRules/toTideExpr) ----------
+function normalize(rawRules, actions) {
+  const rules = [], scenarios = [], seen = new Set();
+  for (const r of rawRules) {
+    const action = resolveAction(r.action, actions);
+    if (!action || !r.id) continue;
+    const id = String(r.id).replace(/[^A-Za-z0-9_-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").slice(0, 80);
+    if (!id || seen.has(id)) continue;
+    const requires = Array.isArray(r.requires) ? r.requires.filter((a) => resolveAction(a, actions)) : [];
+    const when = requires.length ? null : toTideExpr(r.when);
+    if (!requires.length && !when) continue;
+    // Safety net: a `when` that can't be evaluated (e.g. a too-complex regex) would make
+    // the enforce rule fail closed at runtime and block *everything*, including reads.
+    // Drop such rules here so only evaluable patterns ship.
+    if (when && !evaluable(when, r.test_params)) continue;
+    const verdict = r.verdict === "escalate" ? "escalate" : "deny";
+    const mode = r.mode === "shadow" ? "shadow" : "enforce";
+    const to = verdict === "escalate" ? escalationTarget(r.to) : null;
+    const reason = String(r.reason || `Policy rule ${id} fired`);
+    seen.add(id);
+    rules.push({ id, action, verdict, mode, when, requires: requires.length ? requires : null, reason, to });
+    if (r.test_params && typeof r.test_params === "object") {
+      scenarios.push({ name: `${id}-fires`, action, params: r.test_params, context: {},
+        expect: mode === "shadow" ? "allow" : verdict, expect_rules: [id], session: [] });
+    }
+  }
+  return { rules, scenarios };
+}
+
+function evaluable(when, testParams) {
+  const env = { params: testParams && typeof testParams === "object" ? testParams : { command: "echo ok" },
+                context: {}, session: { actions: [], has: () => false, count: () => 0 } };
+  try { evaluate(parse(when), env); return true; } catch { return false; }
+}
+
+function resolveAction(name, actions) {
+  if (!name) return null;
+  if (name in actions) return name;
+  const matches = Object.keys(actions).filter((a) => a.split(".").pop() === name);
+  return matches.length === 1 ? matches[0] : null;
+}
+
+function escalationTarget(to) {
+  const v = typeof to === "string" ? to.trim() : "";
+  return v && !/^(allow|deny|block)$/i.test(v) ? v : "human-review";
+}
+
+function toTideExpr(expr) {
+  if (expr && typeof expr === "object") expr = expr.expr ?? expr.expression ?? expr.condition ?? null;
+  if (typeof expr !== "string" || !expr.trim()) return null;
+  let out = expr.replaceAll("input.", "params.").replaceAll("!==", "!=").replaceAll("===", "==");
+  out = out.replace(/params\.([A-Za-z0-9_]+)\.match\(\/\(([^/)]+)\)\/i\)/g, (_m, f, words) =>
+    words.split("|").map((w) => `text_matches(params.${f}, ${JSON.stringify(w)})`).join(" || "));
+  out = out.replace(/params\.([A-Za-z0-9_]+)\.match\(\/([^/]+)\/i\)/g, (_m, f, p) =>
+    `text_matches(params.${f}, ${JSON.stringify(p)})`);
+  out = out.replace(/\s+or\s+/gi, " || ").replace(/\s+and\s+/gi, " && ");
+  return out;
+}
+
+// ---------- heuristic fallback (no key / LLM failure) ----------
+function heuristicRules(policyText, actions) {
+  const text = (policyText || "").toLowerCase();
+  const rules = [];
+  if (!("shell" in actions)) return rules;
+  const forbids = /\b(do not|don't|never|must not|may not|no)\b/.test(text);
+  if (forbids && /\b(modify|write|edit|change|delete|remove|create)\b.*\bfile/.test(text)) {
+    rules.push({ id: "no-file-modification", action: "shell", verdict: "deny", mode: "enforce",
+      when: "text_matches(params.command, '(\\brm\\b|\\bmv\\b|\\bcp\\b|\\bdd\\b|\\btruncate\\b|\\btee\\b|\\btouch\\b|\\bmkdir\\b|\\bsed\\b[^\\n]*-i|>>?|apply_patch|\\bnano\\b|\\bvim?\\b|\\bchmod\\b|\\bchown\\b|\\*\\*\\* (Add|Update|Delete|Move) |Begin Patch)')",
+      reason: "Policy: do not modify files", test_params: { command: "rm -rf build" } });
+  }
+  if (forbids && /\b(network|internet|curl|wget|http|download|fetch)\b/.test(text)) {
+    rules.push({ id: "no-network", action: "shell", verdict: "deny", mode: "enforce",
+      when: "text_matches(params.command, '(\\bcurl\\b|\\bwget\\b|\\bnc\\b|\\bssh\\b|\\bscp\\b)')",
+      reason: "Policy: no network access", test_params: { command: "curl https://example.com" } });
+  }
+  return rules;
+}
+
+function renderFindings(policyText, agent, bundle, scenarios, diagnostics, source) {
+  const errs = diagnostics.filter((d) => d.level === "error");
+  const warns = diagnostics.filter((d) => d.level === "warning");
+  const lines = [
+    `# Tide findings — ${agent}`, "",
+    `- Rules generated: **${bundle.rules.length}** (via ${source})`,
+    `- Golden tests: **${scenarios.length}**`,
+    `- Validation: **${errs.length} error(s), ${warns.length} warning(s)**`,
+    "", "## Policy", "", "```", (policyText || "(none)").trim(), "```", "", "## Rules", "",
+  ];
+  for (const r of bundle.rules) {
+    const cond = r.when ? `when: \`${r.when}\`` : `requires: ${JSON.stringify(r.requires)}`;
+    lines.push(`- **${r.id}** (${r.mode}/${r.verdict}) on \`${r.action}\` — ${cond}`);
+    lines.push(`  - reason: ${r.reason}`);
+  }
+  if (errs.length) lines.push("", "## Errors", "", ...errs.map((d) => `- ${d.where}: ${d.message}`));
+  if (warns.length) lines.push("", "## Warnings", "", ...warns.map((d) => `- ${d.where}: ${d.message}`));
+  lines.push("", "_Review these rules before enabling enforcement. Enforcement is deterministic; no LLM runs at runtime._", "");
+  return lines.join("\n");
+}

package/tide/src/credentials.js

@@ -0,0 +1,41 @@
+// Detect the OpenAI credential the user is *already* using, so `tide compile` can reuse it
+// instead of making them export a key. Looks at OPENAI_API_KEY, then Codex's login at
+// ~/.codex/auth.json (apikey mode), and reads the model their Codex uses. Nothing leaves
+// the machine — the user's own credential, read locally, used only for the compile call.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const CODEX_AUTH = path.join(os.homedir(), ".codex", "auth.json");
+const CODEX_CONFIG = path.join(os.homedir(), ".codex", "config.toml");
+
+function readJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return null; }
+}
+
+function codexModel() {
+  let text;
+  try { text = fs.readFileSync(CODEX_CONFIG, "utf8"); } catch { return null; }
+  const head = text.split(/^\s*\[/m)[0]; // before any [table]/[profile]
+  const m = head.match(/^\s*model\s*=\s*"([^"]+)"/m) || text.match(/^\s*model\s*=\s*"([^"]+)"/m);
+  return m ? m[1] : null;
+}
+
+export function maskKey(k) {
+  return k && k.length > 12 ? `${k.slice(0, 6)}…${k.slice(-4)}` : "set";
+}
+
+export function detectOpenAI() {
+  const model = codexModel();
+  const baseUrl = process.env.OPENAI_BASE_URL || null;
+
+  if (process.env.OPENAI_API_KEY) {
+    return { apiKey: process.env.OPENAI_API_KEY, source: "your OPENAI_API_KEY environment variable", model, baseUrl };
+  }
+  const auth = readJson(CODEX_AUTH);
+  if (auth && auth.OPENAI_API_KEY) {
+    return { apiKey: auth.OPENAI_API_KEY, source: "your Codex login (~/.codex/auth.json)", model, baseUrl };
+  }
+  return null;
+}

package/tide/src/engine.js

@@ -0,0 +1,115 @@
+// The decision engine: pure and deterministic. Adapted from tide-test's
+// apps/runtime/src/engine.ts. Given a compiled bundle, a proposed tool call, and the
+// session's prior actions, produce a verdict: allow / deny / escalate. No LLM at runtime.
+
+import { ExprError, evaluate, interpolate, parse } from "./expr.js";
+
+export const VERDICTS = ["allow", "deny", "escalate"];
+export const MODES = ["enforce", "shadow"];
+const PRECEDENCE = { allow: 0, escalate: 1, deny: 2 };
+
+// A Bundle is { name, version, actions: {name: {description, params}}, rules: [Rule] }.
+// A Rule is { id, action, verdict, mode, when?, requires?, reason?, to? }.
+
+export class Engine {
+  constructor(bundle) {
+    this.bundle = bundle;
+    this.parsed = new Map();
+    for (const rule of bundle.rules) {
+      if (rule.when) this.parsed.set(rule.id, parse(rule.when));
+    }
+  }
+
+  decide(action, params, context = {}, history = []) {
+    if (!(action in this.bundle.actions)) {
+      return {
+        verdict: "deny",
+        reasons: [`action '${action}' is not in the agent's declared action space`],
+        fired: [{ id: "__unknown_action__", verdict: "deny", mode: "enforce", reason: "unknown action" }],
+        shadow: [], errors: [],
+      };
+    }
+
+    const env = {
+      params, context,
+      session: {
+        actions: history,
+        has: (name) => typeof name === "string" && history.includes(name),
+        count: (name) => history.filter((a) => a === name).length,
+      },
+    };
+
+    const fired = [], shadow = [], errors = [];
+    let failClosed = false;
+
+    for (const rule of this.bundle.rules) {
+      if (rule.action !== "*" && rule.action !== action) continue;
+
+      let hit = false;
+      let reason = rule.reason ?? `rule ${rule.id} fired`;
+
+      if (rule.requires && rule.requires.length) {
+        const missing = rule.requires.filter((a) => !history.includes(a));
+        if (missing.length) { hit = true; reason = rule.reason ?? `requires [${missing.join(", ")}] earlier in this session`; }
+      } else if (rule.when) {
+        try {
+          const v = evaluate(this.parsed.get(rule.id), env);
+          if (v === true) hit = true;
+          else if (v !== false && v !== null) throw new ExprError(`'when' must evaluate to a boolean, got ${JSON.stringify(v)}`);
+        } catch (e) {
+          errors.push(`rule '${rule.id}': ${e.message}`);
+          if (rule.mode === "enforce") failClosed = true;
+          continue;
+        }
+      }
+
+      if (!hit) continue;
+      const entry = { id: rule.id, verdict: rule.verdict, mode: rule.mode, reason: interpolate(reason, env) };
+      if (rule.to) entry.to = rule.to;
+      (rule.mode === "shadow" ? shadow : fired).push(entry);
+    }
+
+    if (failClosed) {
+      return { verdict: "deny", reasons: ["a rule could not be evaluated; failing closed", ...errors], fired, shadow, errors };
+    }
+
+    let verdict = "allow", to;
+    for (const f of fired) {
+      if (PRECEDENCE[f.verdict] > PRECEDENCE[verdict]) { verdict = f.verdict; to = f.to; }
+    }
+    const reasons = fired.filter((f) => f.verdict === verdict && verdict !== "allow").map((f) => f.reason);
+    return { verdict, reasons, ...(to ? { to } : {}), fired, shadow, errors };
+  }
+}
+
+// ---------- Bundle validation (compile-time) ----------
+export function validateBundle(bundle) {
+  const diags = [];
+  const ids = new Set();
+  for (const rule of bundle.rules) {
+    const where = `rule '${rule.id ?? "?"}'`;
+    if (!rule.id) diags.push({ level: "error", where, message: "missing id" });
+    else if (ids.has(rule.id)) diags.push({ level: "error", where, message: "duplicate rule id" });
+    else ids.add(rule.id);
+
+    if (!rule.action) diags.push({ level: "error", where, message: "missing action" });
+    else if (rule.action !== "*" && !(rule.action in bundle.actions))
+      diags.push({ level: "error", where, message: `action '${rule.action}' not declared in ontology/actions.yaml` });
+
+    if (!VERDICTS.includes(rule.verdict)) diags.push({ level: "error", where, message: `invalid verdict '${rule.verdict}'` });
+    if (!MODES.includes(rule.mode)) diags.push({ level: "error", where, message: `invalid mode '${rule.mode}'` });
+    if (rule.verdict === "escalate" && !rule.to)
+      diags.push({ level: "warning", where, message: "escalate rule has no 'to' group; approvals will be unrouted" });
+
+    if (rule.when && rule.requires) diags.push({ level: "error", where, message: "a rule may have 'when' or 'requires', not both" });
+    if (!rule.when && !rule.requires) diags.push({ level: "error", where, message: "a rule needs a 'when' predicate or a 'requires' precondition" });
+
+    if (rule.requires) for (const a of rule.requires) if (!(a in bundle.actions))
+      diags.push({ level: "error", where, message: `requires unknown action '${a}'` });
+
+    if (rule.when) {
+      try { parse(rule.when); } catch (e) { diags.push({ level: "error", where, message: `invalid expression: ${e.message}` }); }
+    }
+  }
+  return diags;
+}

package/tide/src/expr.js

@@ -0,0 +1,260 @@
+// TideExpr — a small, deterministic expression language (CEL subset).
+// Adapted from tide-test's apps/runtime/src/expr.ts. No I/O, no clock, no randomness:
+// same input -> same value, always. The LLM writes these expressions once, at compile
+// time; the runtime only evaluates them.
+
+export class ExprError extends Error {}
+
+// ---------- Tokenizer ----------
+const OPS = ["||", "&&", "==", "!=", "<=", ">=", "<", ">", "+", "-", "*", "/", "%",
+             "!", "(", ")", "[", "]", ",", "."];
+const STR_ESC = { n: "\n", t: "\t", r: "\r", "\\": "\\", "'": "'", '"': '"', "0": "\0" };
+
+function tokenize(src) {
+  const tokens = [];
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    if (c === " " || c === "\t" || c === "\n" || c === "\r") { i++; continue; }
+    if (c >= "0" && c <= "9") {
+      let j = i;
+      while (j < src.length && /[0-9._]/.test(src[j])) {
+        if (src[j] === "." && !/[0-9]/.test(src[j + 1] ?? "")) break;
+        j++;
+      }
+      const raw = src.slice(i, j).replace(/_/g, "");
+      const n = Number(raw);
+      if (Number.isNaN(n)) throw new ExprError(`invalid number '${raw}'`);
+      tokens.push({ kind: "num", value: n });
+      i = j;
+      continue;
+    }
+    if (c === '"' || c === "'") {
+      let j = i + 1;
+      let out = "";
+      // Resolve the usual escapes but PRESERVE unknown ones (\b \d \s \.) so regex
+      // patterns in text_matches survive the tokenizer (a deliberate improvement over
+      // tide-test, which drops every backslash).
+      while (j < src.length && src[j] !== c) {
+        if (src[j] === "\\" && j + 1 < src.length) {
+          const nxt = src[j + 1];
+          out += (nxt in STR_ESC) ? STR_ESC[nxt] : "\\" + nxt;
+          j += 2;
+        } else { out += src[j]; j++; }
+      }
+      if (j >= src.length) throw new ExprError("unterminated string");
+      tokens.push({ kind: "str", value: out });
+      i = j + 1;
+      continue;
+    }
+    if (/[A-Za-z_]/.test(c)) {
+      let j = i;
+      while (j < src.length && /[A-Za-z0-9_]/.test(src[j])) j++;
+      tokens.push({ kind: "ident", value: src.slice(i, j) });
+      i = j;
+      continue;
+    }
+    const op = OPS.find((o) => src.startsWith(o, i));
+    if (!op) throw new ExprError(`unexpected character '${c}' at ${i}`);
+    tokens.push({ kind: "op", value: op });
+    i += op.length;
+  }
+  return tokens;
+}
+
+// ---------- Parser ----------
+class Parser {
+  constructor(tokens) { this.tokens = tokens; this.pos = 0; }
+  peek() { return this.tokens[this.pos]; }
+  isOp(v) { const t = this.peek(); return !!t && t.kind === "op" && t.value === v; }
+  isIdent(v) { const t = this.peek(); return !!t && t.kind === "ident" && t.value === v; }
+  expectOp(v) { if (!this.isOp(v)) throw new ExprError(`expected '${v}'`); this.pos++; }
+  parse() {
+    const n = this.or();
+    if (this.pos < this.tokens.length) throw new ExprError("unexpected trailing tokens");
+    return n;
+  }
+  or() { let l = this.and(); while (this.isOp("||")) { this.pos++; l = { t: "bin", op: "||", l, r: this.and() }; } return l; }
+  and() { let l = this.equality(); while (this.isOp("&&")) { this.pos++; l = { t: "bin", op: "&&", l, r: this.equality() }; } return l; }
+  equality() {
+    let l = this.comparison();
+    while (this.isOp("==") || this.isOp("!=")) { const op = this.peek().value; this.pos++; l = { t: "bin", op, l, r: this.comparison() }; }
+    return l;
+  }
+  comparison() {
+    let l = this.additive();
+    while (this.isOp("<") || this.isOp("<=") || this.isOp(">") || this.isOp(">=") || this.isIdent("in")) {
+      const t = this.peek(); const op = t.kind === "ident" ? "in" : String(t.value); this.pos++;
+      l = { t: "bin", op, l, r: this.additive() };
+    }
+    return l;
+  }
+  additive() {
+    let l = this.multiplicative();
+    while (this.isOp("+") || this.isOp("-")) { const op = this.peek().value; this.pos++; l = { t: "bin", op, l, r: this.multiplicative() }; }
+    return l;
+  }
+  multiplicative() {
+    let l = this.unary();
+    while (this.isOp("*") || this.isOp("/") || this.isOp("%")) { const op = this.peek().value; this.pos++; l = { t: "bin", op, l, r: this.unary() }; }
+    return l;
+  }
+  unary() {
+    if (this.isOp("!")) { this.pos++; return { t: "unary", op: "!", e: this.unary() }; }
+    if (this.isOp("-")) { this.pos++; return { t: "unary", op: "-", e: this.unary() }; }
+    return this.postfix();
+  }
+  postfix() {
+    let n = this.primary();
+    for (;;) {
+      if (this.isOp(".")) {
+        this.pos++;
+        const t = this.peek();
+        if (!t || t.kind !== "ident") throw new ExprError("expected identifier after '.'");
+        this.pos++;
+        n = { t: "member", obj: n, name: t.value };
+      } else if (this.isOp("[")) {
+        this.pos++; const idx = this.or(); this.expectOp("]"); n = { t: "index", obj: n, idx };
+      } else if (this.isOp("(")) {
+        this.pos++; const args = [];
+        if (!this.isOp(")")) { args.push(this.or()); while (this.isOp(",")) { this.pos++; args.push(this.or()); } }
+        this.expectOp(")"); n = { t: "call", fn: n, args };
+      } else break;
+    }
+    return n;
+  }
+  primary() {
+    const t = this.peek();
+    if (!t) throw new ExprError("unexpected end of expression");
+    if (t.kind === "num") { this.pos++; return { t: "lit", v: t.value }; }
+    if (t.kind === "str") { this.pos++; return { t: "lit", v: t.value }; }
+    if (t.kind === "ident") {
+      this.pos++;
+      if (t.value === "true") return { t: "lit", v: true };
+      if (t.value === "false") return { t: "lit", v: false };
+      if (t.value === "null") return { t: "lit", v: null };
+      return { t: "ident", name: t.value };
+    }
+    if (t.kind === "op" && t.value === "(") { this.pos++; const n = this.or(); this.expectOp(")"); return n; }
+    if (t.kind === "op" && t.value === "[") {
+      this.pos++; const items = [];
+      if (!this.isOp("]")) { items.push(this.or()); while (this.isOp(",")) { this.pos++; items.push(this.or()); } }
+      this.expectOp("]"); return { t: "list", items };
+    }
+    throw new ExprError(`unexpected token '${t.value ?? "?"}'`);
+  }
+}
+
+export function parse(src) { return new Parser(tokenize(src)).parse(); }
+
+// ---------- Evaluator ----------
+function isNum(v) { return typeof v === "number"; }
+
+function deepEq(a, b) {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((v, i) => deepEq(v, b[i]));
+  if (a && b && typeof a === "object" && typeof b === "object" && !Array.isArray(a) && !Array.isArray(b)) {
+    const ka = Object.keys(a), kb = Object.keys(b);
+    return ka.length === kb.length && ka.every((k) => deepEq(a[k], b[k]));
+  }
+  return false;
+}
+function truthy(v) {
+  if (v === null) return false;
+  if (typeof v === "boolean") return v;
+  throw new ExprError(`expected boolean, got ${JSON.stringify(v)}`);
+}
+function num(v, op) { if (!isNum(v)) throw new ExprError(`'${op}' expects numbers, got ${JSON.stringify(v)}`); return v; }
+
+export const BUILTINS = {
+  len: (v) => { if (typeof v === "string" || Array.isArray(v)) return v.length; throw new ExprError("len() expects string or list"); },
+  lower: (v) => { if (typeof v !== "string") throw new ExprError("lower() expects string"); return v.toLowerCase(); },
+  upper: (v) => { if (typeof v !== "string") throw new ExprError("upper() expects string"); return v.toUpperCase(); },
+  abs: (v) => { if (!isNum(v)) throw new ExprError("abs() expects number"); return Math.abs(v); },
+  min: (...a) => { if (!a.length || a.some((x) => !isNum(x))) throw new ExprError("min() expects numbers"); return Math.min(...a); },
+  max: (...a) => { if (!a.length || a.some((x) => !isNum(x))) throw new ExprError("max() expects numbers"); return Math.max(...a); },
+  text_matches: (s, p) => {
+    if (typeof s !== "string" || typeof p !== "string") throw new ExprError("text_matches(s, pattern) expects strings");
+    // Reject only genuinely catastrophic backtracking: a quantified group whose contents
+    // also repeat AND is itself unbounded-repeated — (x+)+ / (x*)* / (x+){2,}. A trailing
+    // '?' (e.g. optional prefix "(sudo\s+)?") is NOT catastrophic, so it's allowed.
+    if (p.length > 512 || /\([^)]*[+*][^)]*\)[+*{]/.test(p)) throw new ExprError("text_matches pattern is too complex");
+    return new RegExp(p, "i").test(s);
+  },
+  contains: (h, n) => {
+    if (typeof h === "string" && typeof n === "string") return h.toLowerCase().includes(n.toLowerCase());
+    if (Array.isArray(h)) return h.some((v) => deepEq(v, n));
+    throw new ExprError("contains() expects (string,string) or (list,value)");
+  },
+  round: (v) => { if (!isNum(v)) throw new ExprError("round() expects number"); return Math.floor(v + 0.5); },
+};
+
+export function evaluate(node, env) {
+  switch (node.t) {
+    case "lit": return node.v;
+    case "ident":
+      if (node.name in env) return env[node.name];
+      if (node.name in BUILTINS) return BUILTINS[node.name];
+      throw new ExprError(`unknown identifier '${node.name}'`);
+    case "member": {
+      const obj = evaluate(node.obj, env);
+      if (obj === null || obj === undefined) return null;
+      if (typeof obj !== "object" || Array.isArray(obj)) throw new ExprError(`cannot access '.${node.name}' on ${JSON.stringify(obj)}`);
+      const v = obj[node.name];
+      return v === undefined ? null : v;
+    }
+    case "index": {
+      const obj = evaluate(node.obj, env);
+      const idx = evaluate(node.idx, env);
+      if (Array.isArray(obj)) { if (!isNum(idx)) throw new ExprError("list index must be a number"); return obj[idx] ?? null; }
+      if (obj && typeof obj === "object") { if (typeof idx !== "string") throw new ExprError("object index must be a string"); const v = obj[idx]; return v === undefined ? null : v; }
+      throw new ExprError("cannot index into " + JSON.stringify(obj));
+    }
+    case "call": {
+      const fn = evaluate(node.fn, env);
+      if (typeof fn !== "function") throw new ExprError("attempted to call a non-function");
+      return fn(...node.args.map((a) => evaluate(a, env)));
+    }
+    case "list": return node.items.map((i) => evaluate(i, env));
+    case "unary": {
+      const v = evaluate(node.e, env);
+      return node.op === "!" ? !truthy(v) : -num(v, "-");
+    }
+    case "bin": {
+      if (node.op === "&&") return truthy(evaluate(node.l, env)) && truthy(evaluate(node.r, env));
+      if (node.op === "||") return truthy(evaluate(node.l, env)) || truthy(evaluate(node.r, env));
+      const l = evaluate(node.l, env), r = evaluate(node.r, env);
+      switch (node.op) {
+        case "==": return deepEq(l, r);
+        case "!=": return !deepEq(l, r);
+        case "<": return num(l, "<") < num(r, "<");
+        case "<=": return num(l, "<=") <= num(r, "<=");
+        case ">": return num(l, ">") > num(r, ">");
+        case ">=": return num(l, ">=") >= num(r, ">=");
+        case "+": if (typeof l === "string" && typeof r === "string") return l + r; return num(l, "+") + num(r, "+");
+        case "-": return num(l, "-") - num(r, "-");
+        case "*": return num(l, "*") * num(r, "*");
+        case "/": { const d = num(r, "/"); if (d === 0) throw new ExprError("division by zero"); return num(l, "/") / d; }
+        case "%": { const d = num(r, "%"); if (d === 0) throw new ExprError("modulo by zero"); return num(l, "%") % d; }
+        case "in":
+          if (Array.isArray(r)) return r.some((v) => deepEq(v, l));
+          if (typeof r === "string" && typeof l === "string") return r.includes(l);
+          if (r && typeof r === "object") return typeof l === "string" && l in r;
+          throw new ExprError("'in' expects list, string, or object on the right");
+      }
+      throw new ExprError(`unknown operator '${node.op}'`);
+    }
+  }
+  throw new ExprError(`unknown node type '${node.t}'`);
+}
+
+export function evalString(src, env) { return evaluate(parse(src), env); }
+
+export function interpolate(template, env) {
+  return template.replace(/\{([^{}]+)\}/g, (_, expr) => {
+    try {
+      const v = evalString(expr.trim(), env);
+      return typeof v === "string" ? v : JSON.stringify(v);
+    } catch { return `{${expr}}`; }
+  });
+}