donobu 5.60.8 → 5.61.0

package/dist/utils/TemplateInterpolator.js

@@ -1,6 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TEMPLATE_DATA_PATTERN = void 0;
+exports.ENV_VALUE_FILTERS = exports.TEMPLATE_DATA_PATTERN = void 0;
+exports.parseFilteredExpression = parseFilteredExpression;
+exports.applyEnvValueFilters = applyEnvValueFilters;
+exports.envValueForms = envValueForms;
+exports.extractEnvVarReferences = extractEnvVarReferences;
 exports.resolveExpression = resolveExpression;
 exports.interpolateString = interpolateString;
 exports.interpolateObject = interpolateObject;
@@ -31,6 +35,136 @@ function formatValue(value) {
     // Default case
     return String(value);
 }
+/**
+ * Allow-listed, pure string transforms usable as `{{ <path> | <filter> }}` in a
+ * template (e.g. `{{$.env.NAV | title}}`). They let a single env value render in
+ * the various forms it takes across a page (a tab text "Contact" vs an href
+ * "/contact" vs a slug "some-tab") while a recorded selector keeps the
+ * placeholder instead of a frozen literal.
+ *
+ * Keep this set SMALL and deterministic: it is the single source of truth used
+ * both at replay (to render a value) and at record time (to recognize that an
+ * on-page literal is a transformed form of an env value). Each is a total
+ * `string -> string` function — no arguments, no side effects.
+ */
+exports.ENV_VALUE_FILTERS = {
+    lower: (s) => s.toLowerCase(),
+    upper: (s) => s.toUpperCase(),
+    capitalize: (s) => (s.length ? s.charAt(0).toUpperCase() + s.slice(1) : s),
+    title: (s) => s.replace(/(^|\s)(\S)/g, (_, sp, c) => sp + c.toUpperCase()),
+    trim: (s) => s.trim(),
+    kebab: (s) => s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, ''),
+    snake: (s) => s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, ''),
+    urlEncode: (s) => encodeURIComponent(s),
+};
+/**
+ * Split a template expression into its JSONPath part and any trailing
+ * `| filter | filter` chain. Splits only on top-level `|` — pipes inside
+ * brackets/parens or quotes (e.g. a JSONPath filter `[?(@.x == "a|b")]`) are left
+ * intact. The custom {@link queryJsonPath} dialect never uses `|`, so a top-level
+ * `|` is unambiguously a filter delimiter.
+ */
+function parseFilteredExpression(content) {
+    const segments = [];
+    let current = '';
+    let depth = 0;
+    let quote = null;
+    for (const ch of content) {
+        if (quote) {
+            current += ch;
+            if (ch === quote) {
+                quote = null;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            current += ch;
+        }
+        else if (ch === '[' || ch === '(') {
+            depth++;
+            current += ch;
+        }
+        else if (ch === ']' || ch === ')') {
+            depth--;
+            current += ch;
+        }
+        else if (ch === '|' && depth === 0) {
+            segments.push(current);
+            current = '';
+        }
+        else {
+            current += ch;
+        }
+    }
+    segments.push(current);
+    const trimmed = segments.map((segment) => segment.trim());
+    return {
+        path: trimmed[0],
+        filters: trimmed.slice(1).filter((name) => name.length > 0),
+    };
+}
+/**
+ * Apply a chain of {@link ENV_VALUE_FILTERS} to a string, left to right. Throws
+ * on an unknown filter name so the caller (interpolation) leaves the original
+ * `{{...}}` placeholder in place rather than silently emitting a wrong value.
+ */
+function applyEnvValueFilters(value, filters) {
+    let result = value;
+    for (const name of filters) {
+        const filter = exports.ENV_VALUE_FILTERS[name];
+        if (!filter) {
+            throw new Error(`Unknown interpolation filter: '${name}'`);
+        }
+        result = filter(result);
+    }
+    return result;
+}
+/**
+ * The distinct forms an env value can take via the allow-listed filters — the
+ * identity form plus each filter applied. Used at record time to recognize that
+ * an on-page literal (e.g. "Contact") is a transformed form of an env value
+ * (e.g. "contact") so the recorded selector can keep `{{$.env.X | title}}`.
+ *
+ * Identity comes first; duplicate forms (a filter that doesn't change the value)
+ * are dropped, preferring the simplest (earliest) producer.
+ */
+function envValueForms(value) {
+    const forms = [];
+    const seen = new Set();
+    const add = (filter, form) => {
+        if (form.length > 0 && !seen.has(form)) {
+            seen.add(form);
+            forms.push({ filter, form });
+        }
+    };
+    add(null, value);
+    for (const [name, filter] of Object.entries(exports.ENV_VALUE_FILTERS)) {
+        add(name, filter(value));
+    }
+    return forms;
+}
+/**
+ * Extract the env var NAMES referenced (via `{{$.env.NAME}}`, with or without a
+ * `| filter` suffix) anywhere in a template string. Centralizes the filter-aware
+ * parsing so callers don't re-derive names by naive substring math (which breaks
+ * once an expression carries a filter, e.g. `$.env.NAV | title`).
+ */
+function extractEnvVarReferences(template) {
+    const prefix = '$.env.';
+    const names = extractInterpolationExpressions(template)
+        .map((expression) => parseFilteredExpression(expression).path)
+        .filter((path) => path.startsWith(prefix))
+        .map((path) => path.substring(prefix.length).trim())
+        .filter((name) => name.length > 0);
+    return [...new Set(names)];
+}
 /**
  * Resolve a JSONPath expression against the context
  * @param expression - The JSONPath expression to evaluate
@@ -118,10 +252,17 @@ function interpolateString(template, dataSource, recursionDepth = 0, maxRecursio
             try {
                 // If the expression contains nested templates, process it first, passing along depth info
                 const processedExpression = interpolateString(expressionContent, dataSource, recursionDepth + 1, maxRecursionDepth, new Set(processed));
-                // Then resolve the processed expression
-                const value = resolveExpression(processedExpression, dataSource);
-                // If the value is undefined, keep the original expression
-                const replacement = value !== undefined ? formatValue(value) : `{{${expressionContent}}}`;
+                // Split any trailing `| filter` chain off the (nested-resolved)
+                // expression, resolve the JSONPath part, then apply the filters to the
+                // rendered value.
+                const { path, filters } = parseFilteredExpression(processedExpression);
+                const value = resolveExpression(path, dataSource);
+                // If the value is undefined, keep the original expression (filters and
+                // all). An unknown filter throws and is caught below, also leaving the
+                // original placeholder intact rather than emitting a wrong value.
+                const replacement = value !== undefined
+                    ? applyEnvValueFilters(formatValue(value), filters)
+                    : `{{${expressionContent}}}`;
                 // Store the replacement for later
                 processedSegments.push([openIndex, closeIndex, replacement]);
                 i = closeIndex;

package/dist/utils/envReferencePromptSection.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared prompt guidance instructing the model to emit `{{$.env.NAME}}`
+ * placeholders — rather than baking the resolved literal — when a field's value
+ * comes from an env var the user referenced, so cached artifacts stay valid
+ * across runs with different env values. Includes the `| filter` transforms so
+ * the model can express a value that renders in a transformed form on the page.
+ *
+ * Shared by the locate and assert subsystems (each appends its own
+ * representation-specific rules/examples). Returns '' when no referenced env vars
+ * are in play, which keeps the prompt small for the common case.
+ */
+export declare function buildEnvReferencePromptSection(options: {
+    /** Noun for the user's input, e.g. 'assertion' or 'description'. */
+    artifactNoun: string;
+    /** The raw, uninterpolated user input (caller decides any quoting). */
+    rawArtifact: string;
+    /**
+     * Where placeholders may be emitted, e.g.
+     * "any LocatorStep `text`, `name`, or `testId` field".
+     */
+    fieldGuidance: string;
+    /** Referenced env vars and their current resolved values. */
+    referencedEnvEntries: Array<[string, string]>;
+}): string;
+//# sourceMappingURL=envReferencePromptSection.d.ts.map

package/dist/utils/envReferencePromptSection.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildEnvReferencePromptSection = buildEnvReferencePromptSection;
+const TemplateInterpolator_1 = require("./TemplateInterpolator");
+/**
+ * Shared prompt guidance instructing the model to emit `{{$.env.NAME}}`
+ * placeholders — rather than baking the resolved literal — when a field's value
+ * comes from an env var the user referenced, so cached artifacts stay valid
+ * across runs with different env values. Includes the `| filter` transforms so
+ * the model can express a value that renders in a transformed form on the page.
+ *
+ * Shared by the locate and assert subsystems (each appends its own
+ * representation-specific rules/examples). Returns '' when no referenced env vars
+ * are in play, which keeps the prompt small for the common case.
+ */
+function buildEnvReferencePromptSection(options) {
+    const { artifactNoun, rawArtifact, fieldGuidance, referencedEnvEntries } = options;
+    if (referencedEnvEntries.length === 0) {
+        return '';
+    }
+    const mapping = referencedEnvEntries
+        .map(([name, value]) => `  - {{$.env.${name}}} = ${JSON.stringify(value)}`)
+        .join('\n');
+    const filters = Object.keys(TemplateInterpolator_1.ENV_VALUE_FILTERS).join(', ');
+    return `
+
+The user's original ${artifactNoun} contains environment variable references using
+the syntax \`{{$.env.NAME}}\`. To keep cached results valid across runs with
+different env values, you MUST emit those same placeholders in ${fieldGuidance}
+whose contents come from an env var. Do NOT bake the literal current value in.
+
+When the on-page text is a deterministic transform of the value (different case,
+spaces vs dashes, etc.), append a filter: \`{{$.env.NAME | filter}}\`. Available
+filters: ${filters} (e.g. value "contact" shown as "Contact" -> {{$.env.NAME | capitalize}}).
+
+Original (uninterpolated) ${artifactNoun}: ${rawArtifact}
+
+Current env mapping (use these to identify which substrings on the page came from
+which env var, then emit the placeholder rather than the literal):
+${mapping}`;
+}
+//# sourceMappingURL=envReferencePromptSection.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "donobu",
-  "version": "5.60.8",
+  "version": "5.61.0",
   "description": "Create browser automations with an LLM agent and replay them as Playwright scripts.",
   "main": "dist/main.js",
   "module": "dist/esm/main.js",