@vertesia/studio-utils 1.5.0 → 1.5.1

package/src/prompts/extract-vars.ts

@@ -1,110 +1,254 @@
+import { HANDLEBARS_CONTEXT_HELPERS, isHandlebarsHelper, isTemplateSystemVariable } from '@vertesia/jst';
 import Handlebars from 'handlebars';
 
+/** A read of a root-level template variable. */
+export interface HandlebarsVariableReference {
+    /** Root identifier: `customer` for `{{customer.name}}`, `{{../customer}}` or `{{@root.customer}}`. */
+    name: string;
+    /** The path as written, e.g. `customer.name`. */
+    expression: string;
+    /** True when the path reads a property of the variable (`customer.name`). */
+    hasPath: boolean;
+    /** Source of the tag that contains the read, e.g. `{{#if customer}}`. */
+    tag: string;
+}
+
+/** A helper name used where Handlebars will not call it. */
+export interface HandlebarsHelperMisuse {
+    helper: string;
+    /**
+     * - `used_as_value`: passed as an argument (`{{#if stringify}}`), where Handlebars reads the data.
+     * - `missing_arguments`: called bare (`{{stringify}}`) with none of the arguments it needs.
+     */
+    problem: 'used_as_value' | 'missing_arguments';
+    tag: string;
+}
+
+export interface HandlebarsTemplateAnalysis {
+    references: HandlebarsVariableReference[];
+    helperMisuses: HandlebarsHelperMisuse[];
+}
+
+interface PathNode {
+    type: 'PathExpression';
+    original: string;
+    parts: string[];
+    depth: number;
+    data: boolean;
+}
+
+interface SourceLocation {
+    start: { line: number; column: number };
+}
+
+type Node = { type: string; loc?: SourceLocation } & Record<string, unknown>;
+
+/** Context a template section renders with: the input root, or an item whose shape is unknown. */
+type ContextKind = 'root' | 'item';
+
+function isPath(node: unknown): node is PathNode {
+    return !!node && typeof node === 'object' && (node as Node).type === 'PathExpression';
+}
+
+/** `this.x`, `./x` and `this` read the context explicitly — Handlebars never treats them as helpers. */
+function isScoped(path: PathNode): boolean {
+    return /^\.|this\b/.test(path.original);
+}
+
+/** A single bare identifier — the only form Handlebars may resolve to a helper. */
+function isSimpleId(path: PathNode): boolean {
+    return path.parts.length === 1 && !isScoped(path) && !path.data && path.depth === 0;
+}
+
+function lineOffsets(template: string): number[] {
+    const offsets = [0];
+    for (let i = 0; i < template.length; i++) {
+        if (template[i] === '\n') offsets.push(i + 1);
+    }
+    return offsets;
+}
+
 /**
- * Extract the set of root-level variable names referenced by a Handlebars template.
+ * Analyze the variables and helpers a Handlebars template uses, resolving names the way the
+ * prompt renderer does (helpers and system variables come from `@vertesia/jst`).
  *
- * - `{{foo}}` → `foo`
- * - `{{obj.bar.baz}}` → `obj` (only the root identifier; nested access doesn't add `bar` or `baz`)
- * - `{{#if cond}}{{name}}{{/if}}` → `cond`, `name`
- * - `{{#each items as |item|}}{{item.name}}{{/each}}` → `items` (NOT `item` — bound by `as |item|`)
- * - `{{lookup obj key}}` → `obj`, `key` (helper name skipped)
- * - `{{@index}}`, `{{this}}` → ignored (built-in data vars / self)
- *
- * Helper names in mustaches and block heads (`{{customHelper x}}`, `{{#if x}}`) are NOT added to
- * the set — only the arguments and inner template references are. This matches the typical use
- * case for prompt validation: detect which schema properties the template actually reads.
+ * Scoping rules:
+ * - Inside `{{#each}}` / `{{#with}}` (and `{{#section}}` over data), bare names read the current item,
+ *   whose shape the input schema does not describe — they are not reported. `../x` and `@root.x`
+ *   read the enclosing or root context and are reported.
+ * - `as |x|` block params are local bindings, not variables.
+ * - `{{@index}}` and other `@`-data (except `@root.x`) are runtime values, not variables.
  *
- * Returns an empty set on parse failure — callers should also run a syntactic render check
- * (e.g. `executeHandlebars`) to surface parse errors separately.
+ * Returns null when the template does not parse; the render check reports the syntax error.
  */
-export function extractHandlebarsVariables(template: string): Set<string> {
+export function analyzeHandlebarsTemplate(template: string): HandlebarsTemplateAnalysis | null {
     let ast: hbs.AST.Program;
     try {
         ast = Handlebars.parse(template);
     } catch {
-        return new Set();
+        return null;
     }
 
-    const variables = new Set<string>();
-    const localScopes: Array<Set<string>> = [];
+    const offsets = lineOffsets(template);
+    const tagAt = (loc: SourceLocation | undefined): string => {
+        if (!loc) return '';
+        const start = (offsets[loc.start.line - 1] ?? 0) + loc.start.column;
+        const end = template.indexOf('}}', start);
+        if (end < 0) return template.slice(start);
+        return template.slice(start, template[end + 2] === '}' ? end + 3 : end + 2);
+    };
 
-    const isLocal = (name: string): boolean => localScopes.some((scope) => scope.has(name));
+    const references: HandlebarsVariableReference[] = [];
+    const helperMisuses: HandlebarsHelperMisuse[] = [];
+    const contexts: ContextKind[] = ['root'];
+    const blockParams: Array<Set<string>> = [];
+    let tag = '';
 
-    const visit = (node: unknown): void => {
-        if (!node || typeof node !== 'object') return;
-        const n = node as { type: string } & Record<string, unknown>;
+    const isBlockParam = (name: string): boolean => blockParams.some((scope) => scope.has(name));
 
-        switch (n.type) {
-            case 'Program': {
-                const body = n.body as unknown[] | undefined;
-                if (body) for (const stmt of body) visit(stmt);
-                break;
+    /** Record a data read of `path`, if it reads the root input. */
+    const readData = (path: PathNode): void => {
+        if (path.data) {
+            // `@root.x` reads the input root; `@index`, `@key`, ... are runtime values.
+            if (path.parts[0] === 'root' && path.parts.length > 1) {
+                references.push({
+                    name: path.parts[1],
+                    expression: path.original,
+                    hasPath: path.parts.length > 2,
+                    tag,
+                });
             }
+            return;
+        }
+        if (path.parts.length === 0) return; // `this` / `.`
+        const root = path.parts[0];
+        if (path.depth === 0 && !isScoped(path) && isBlockParam(root)) return;
+        // Handlebars stops at the root context when `../` goes past it.
+        const context = contexts[Math.max(0, contexts.length - 1 - path.depth)];
+        if (context !== 'root') return;
+        references.push({ name: root, expression: path.original, hasPath: path.parts.length > 1, tag });
+    };
 
-            case 'BlockStatement': {
-                // n.path is the helper name (`#if`, `#each`, `#customBlock`) — never a variable.
-                // Visit params + hash to capture variables passed to the block helper.
-                const params = n.params as unknown[] | undefined;
-                if (params) for (const p of params) visit(p);
-                visit(n.hash);
+    /** A path in argument position (params, hash values): Handlebars reads data, never calls a helper. */
+    const visitArgument = (node: unknown): void => {
+        if (isPath(node)) {
+            const name = node.parts[0];
+            // System variables are injected as data too, so they resolve as arguments.
+            if (
+                isSimpleId(node) &&
+                !isBlockParam(name) &&
+                isHandlebarsHelper(name) &&
+                !isTemplateSystemVariable(name)
+            ) {
+                helperMisuses.push({ helper: name, problem: 'used_as_value', tag });
+                return;
+            }
+            readData(node);
+            return;
+        }
+        visit(node);
+    };
 
-                // Track `as |x y|` block params — these are local bindings, not variables.
-                const program = n.program as { blockParams?: string[] } | undefined;
-                const inverse = n.inverse as { blockParams?: string[] } | undefined;
-                const scope = new Set<string>([...(program?.blockParams ?? []), ...(inverse?.blockParams ?? [])]);
-                localScopes.push(scope);
+    const visitCall = (n: Node): void => {
+        const params = (n.params as unknown[] | undefined) ?? [];
+        for (const p of params) visitArgument(p);
+        const pairs = (n.hash as { pairs?: Array<{ value: unknown }> } | undefined)?.pairs ?? [];
+        for (const pair of pairs) visitArgument(pair.value);
+    };
 
-                visit(n.program);
-                visit(n.inverse);
+    const hasArguments = (n: Node): boolean =>
+        ((n.params as unknown[] | undefined)?.length ?? 0) > 0 ||
+        ((n.hash as { pairs?: unknown[] } | undefined)?.pairs?.length ?? 0) > 0;
 
-                localScopes.pop();
+    const visit = (node: unknown): void => {
+        if (!node || typeof node !== 'object') return;
+        const n = node as Node;
+
+        switch (n.type) {
+            case 'Program': {
+                for (const stmt of (n.body as unknown[] | undefined) ?? []) visit(stmt);
                 break;
             }
 
             case 'MustacheStatement': {
-                // Bare mustache (no params, no hash) → it's a variable reference.
-                // With params/hash, it's a helper call — skip the path (helper name), visit args.
-                const params = n.params as unknown[] | undefined;
-                const hash = n.hash as { pairs?: unknown[] } | undefined;
-                const isHelperCall = (params?.length ?? 0) > 0 || (hash?.pairs?.length ?? 0) > 0;
-                if (!isHelperCall) {
-                    visit(n.path);
+                tag = tagAt(n.loc);
+                const path = n.path;
+                if (hasArguments(n)) {
+                    // `{{helper arg}}`: the head is a helper name (a missing one fails the render check).
+                    visitCall(n);
+                } else if (isPath(path)) {
+                    // A bare `{{name}}` calls a helper of that name when there is one, else reads data.
+                    // System variables are helpers returning their injected value, meant to be used bare.
+                    const name = path.parts[0];
+                    if (isSimpleId(path) && !isBlockParam(name) && isHandlebarsHelper(name)) {
+                        if (!isTemplateSystemVariable(name)) {
+                            helperMisuses.push({ helper: name, problem: 'missing_arguments', tag });
+                        }
+                    } else {
+                        readData(path);
+                    }
+                } else {
+                    visit(path);
                 }
-                if (params) for (const p of params) visit(p);
-                visit(hash);
                 break;
             }
 
-            case 'SubExpression': {
-                // (helper arg1 arg2) — helper name in path is skipped, args carry variables.
-                const params = n.params as unknown[] | undefined;
-                if (params) for (const p of params) visit(p);
-                visit(n.hash);
-                break;
-            }
+            case 'BlockStatement': {
+                tag = tagAt(n.loc);
+                const path = n.path;
+                const helper = isPath(path) && isSimpleId(path) ? path.parts[0] : undefined;
+                let itemContext: boolean;
+                if (hasArguments(n) || (helper && isHandlebarsHelper(helper))) {
+                    visitCall(n);
+                    itemContext = !!helper && HANDLEBARS_CONTEXT_HELPERS.includes(helper);
+                } else {
+                    // `{{#section}}…{{/section}}` over data: iterates or enters `section`.
+                    if (isPath(path)) readData(path);
+                    itemContext = true;
+                }
+
+                const program = n.program as { blockParams?: string[] } | undefined;
+                const inverse = n.inverse as { blockParams?: string[] } | undefined;
+                blockParams.push(new Set(program?.blockParams ?? []));
+                contexts.push(itemContext ? 'item' : contexts[contexts.length - 1]);
+                visit(n.program);
+                contexts.pop();
+                blockParams.pop();
 
-            case 'PathExpression': {
-                if (n.data) break; // `@-data` references (@index, @key, etc.)
-                const parts = n.parts as string[] | undefined;
-                if (!parts || parts.length === 0) break; // `this` / `.`
-                const root = parts[0];
-                if (isLocal(root)) break;
-                variables.add(root);
+                // `{{else}}` renders with the enclosing context.
+                blockParams.push(new Set(inverse?.blockParams ?? []));
+                visit(n.inverse);
+                blockParams.pop();
                 break;
             }
 
-            case 'Hash': {
-                const pairs = n.pairs as Array<{ value: unknown }> | undefined;
-                if (pairs) for (const pair of pairs) visit(pair.value);
+            case 'SubExpression': {
+                // `(helper arg)`: the head is a call, like a bare `{{helper}}`.
+                visitCall(n);
                 break;
             }
 
-            // ContentStatement, CommentStatement, *Literal, PartialStatement — no variables to extract.
+            // ContentStatement, CommentStatement, literals, partials — no variables.
             default:
                 break;
         }
     };
 
     visit(ast);
-    return variables;
+    return { references, helperMisuses };
+}
+
+/**
+ * Extract the set of root-level input variable names a Handlebars template reads.
+ *
+ * - `{{foo}}` → `foo`; `{{obj.bar.baz}}` → `obj`
+ * - `{{#each items as |item|}}{{item.name}}{{/each}}` → `items` (`item` is a block param)
+ * - `{{lookup obj key}}` → `obj`, `key` (helper name skipped)
+ * - `{{@index}}`, `{{this}}`, and bare names inside `#each`/`#with` → ignored
+ *
+ * Returns an empty set on parse failure.
+ */
+export function extractHandlebarsVariables(template: string): Set<string> {
+    const analysis = analyzeHandlebarsTemplate(template);
+    return new Set(analysis?.references.map((r) => r.name) ?? []);
 }

package/src/prompts/render.test.ts

@@ -25,6 +25,16 @@ describe('renderTemplate', () => {
             renderTemplate('return `Hello ${name}`', TemplateType.jst, { properties: { name: {} } }, { name: 'Ada' }),
         ).toEqual('Hello Ada');
     });
+
+    it('supplies system variables to both template languages', () => {
+        const system = { model: 'test-model', now: new Date('2026-01-02T03:04:05.000Z') };
+        expect(renderTemplate('{{#if _now}}{{_now}}{{/if}} {{_model}}', TemplateType.handlebars, {}, {}, system)).toBe(
+            '2026-01-02T03:04:05.000Z test-model',
+        );
+        expect(renderTemplate('return `${_now} ${_model}`', TemplateType.jst, {}, {}, system)).toBe(
+            '2026-01-02T03:04:05.000Z test-model',
+        );
+    });
 });
 
 describe('renderSegments', () => {
@@ -97,13 +107,14 @@ function createPromptTemplate(overrides: Partial<PromptTemplate>): PromptTemplat
         role: PromptRole.user,
         status: PromptStatus.draft,
         version: 1,
+        edit_revision: 1,
         content: '',
         content_type: TemplateType.jst,
         project: 'project-1',
         created_by: 'user-1',
         updated_by: 'user-1',
-        created_at: new Date('2026-01-01T00:00:00.000Z'),
-        updated_at: new Date('2026-01-01T00:00:00.000Z'),
+        created_at: '2026-01-01T00:00:00.000Z',
+        updated_at: '2026-01-01T00:00:00.000Z',
         ...overrides,
     };
 }

package/src/prompts/render.ts

@@ -1,6 +1,12 @@
 import type { JSONObject, JSONSchema, PromptSegment } from '@llumiverse/common';
 import { type PromptSegmentDef, PromptSegmentDefType, type PromptTemplate, TemplateType } from '@vertesia/common';
-import { CompositeError, renderHandlebarsTemplate, renderJsTemplate } from '@vertesia/jst';
+import {
+    CompositeError,
+    renderHandlebarsTemplate,
+    renderJsTemplate,
+    type TemplateSystemContext,
+    withTemplateSystemVariables,
+} from '@vertesia/jst';
 
 export interface SegmentPreview {
     error?: Error;
@@ -12,29 +18,32 @@ export interface SegmentPreview {
 /**
  * Render a prompt template with the given input data.
  *
- * Handlebars templates use {{variable}} interpolation against `data`.
- * JST (JavaScript template) bodies evaluate against `data` with the schema's top-level
- * property names exposed as globals, plus `_model` — the active model id, which the
- * studio-server executor injects into the input as `{ ..._model: run.modelId }` when
- * executing an interaction (see `apps/studio-server/src/executor/ExecutionRequest.ts`
- * and `apps/studio-server/src/executor/rendering/template.ts`). Listing it here keeps
- * the Playground preview and `validatePrompt` in sync with runtime resolution — a JST
- * template referencing `_model` validates fine here and renders fine in production.
+ * Handlebars templates use {{variable}} interpolation against `data`. JST (JavaScript template)
+ * bodies evaluate against `data` with the schema's top-level property names exposed as globals.
+ * Both see the system variables (`TEMPLATE_SYSTEM_VARIABLES` in `@vertesia/jst`), added here the
+ * same way the studio-server executor adds them, so a preview renders what an execution would.
+ * `_model` is only set when the caller passes `system.model` or the data already carries it.
  *
  * For `TemplateType.text`, the content is returned verbatim — it is static text, not a
  * template — matching the studio-server executor (see `apps/studio-server/src/executor/
  * rendering/template.ts`). Routing it through the JST evaluator would compile the prose as
  * JavaScript and throw on any plain sentence (e.g. "You are a helpful assistant.").
  */
-export function renderTemplate(code: string, contentType: TemplateType, schema: JSONSchema, data: JSONObject): string {
-    if (contentType === TemplateType.handlebars) {
-        return renderHandlebarsTemplate(code, data);
-    }
+export function renderTemplate(
+    code: string,
+    contentType: TemplateType,
+    schema: JSONSchema,
+    data: JSONObject,
+    system?: TemplateSystemContext,
+): string {
     if (contentType === TemplateType.text) {
         return code;
     }
-    const globals = [...(schema.properties ? Object.keys(schema.properties) : []), '_model'];
-    return renderJsTemplate(code, globals, data);
+    const input = withTemplateSystemVariables(data, system);
+    if (contentType === TemplateType.handlebars) {
+        return renderHandlebarsTemplate(code, input);
+    }
+    return renderJsTemplate(code, schema.properties ? Object.keys(schema.properties) : [], input);
 }
 
 /**

package/src/prompts/validate.test.ts

@@ -284,3 +284,118 @@ describe('validatePrompt — jst', () => {
         expect(findIssue(r.issues, 'jst_unsafe_construct')).toBeDefined();
     });
 });
+
+describe('system variables', () => {
+    const errors = (
+        content: string,
+        contentType = TemplateType.handlebars,
+        properties: Record<string, JSONSchema> = {},
+    ) =>
+        validatePrompt({ content, contentType, inputSchema: schema(properties) }).issues.filter(
+            (i) => i.severity === 'error',
+        );
+
+    // Every position a variable can appear in. `{{#if _now}}` is the reported bug: it failed
+    // because `_now` was only a helper, which Handlebars never calls in argument position.
+    it.each([
+        '{{_now}}',
+        '{{{_now}}}',
+        '{{#if _now}}{{_now}}{{/if}}',
+        '{{#unless _model}}none{{/unless}}',
+        '{{stringify _now}}',
+        '{{stringify (_now)}}',
+        '{{stringify (_model)}}',
+        '{{this._now}}',
+        '{{@root._model}}',
+    ])('accepts %s without a declaration', (content) => {
+        expect(errors(content)).toEqual([]);
+    });
+
+    it('accepts system variables inside #each and #with', () => {
+        const content = '{{#each items}}{{../_now}} {{@root._model}}{{/each}}{{#with obj}}{{_now}}{{/with}}';
+        expect(errors(content, TemplateType.handlebars, { items: { type: 'array' }, obj: { type: 'object' } })).toEqual(
+            [],
+        );
+    });
+
+    it.each(['return _now;', 'return `${_model}`;'])('accepts JST %s without a declaration', (content) => {
+        expect(errors(content, TemplateType.jst)).toEqual([]);
+    });
+
+    it.each(['{{_now.foo}}', '{{#if _model.name}}x{{/if}}'])('rejects property access on a string: %s', (content) => {
+        const result = validatePrompt({ content, contentType: TemplateType.handlebars, inputSchema: schema({}) });
+        expect(findIssue(result.issues, 'system_variable_property_access')).toBeDefined();
+        expect(findIssue(result.issues, 'undeclared_template_variable')).toBeUndefined();
+    });
+
+    it('warns when the schema declares a system variable', () => {
+        const result = validatePrompt({
+            content: '{{_now}}',
+            contentType: TemplateType.handlebars,
+            inputSchema: schema({ _now: { type: 'string' } }),
+        });
+        expect(result.error_count).toBe(0);
+        expect(findIssue(result.issues, 'reserved_variable_declared', '_now')).toBeDefined();
+        expect(findIssue(result.issues, 'unused_schema_variable')).toBeUndefined();
+    });
+
+    it('still rejects ordinary undeclared variables, and lists the system variables in the message', () => {
+        const [issue] = errors('{{#if customer}}x{{/if}}');
+        expect(issue.type).toBe('undeclared_template_variable');
+        expect(issue.variable).toBe('customer');
+        expect(issue.message).toContain('in {{#if customer}}');
+        expect(issue.message).toContain('_now');
+        expect(issue.message).toContain('_model');
+    });
+});
+
+describe('handlebars scopes and helpers', () => {
+    it.each([
+        ['{{#with obj}}{{k}}{{/with}}', { obj: { type: 'object' } }],
+        ['{{#each items}}{{name}}{{/each}}', { items: { type: 'array' } }],
+        ['{{#items}}{{name}}{{/items}}', { items: { type: 'array' } }],
+        ['{{#each items as |it|}}{{it.name}}{{/each}}', { items: { type: 'array' } }],
+    ] as const)('does not report item fields inside %s', (content, properties) => {
+        const result = validatePrompt({
+            content,
+            contentType: TemplateType.handlebars,
+            inputSchema: schema(properties),
+        });
+        expect(result.error_count).toBe(0);
+        expect(result.warning_count).toBe(0);
+    });
+
+    it.each([
+        ['{{#each items}}{{../customer}}{{/each}}', 'customer'],
+        ['{{#with obj}}{{@root.customer}}{{/with}}', 'customer'],
+        ['{{#each items}}x{{else}}{{customer}}{{/each}}', 'customer'],
+    ])('reports root reads from inside a block: %s', (content, variable) => {
+        const result = validatePrompt({
+            content,
+            contentType: TemplateType.handlebars,
+            inputSchema: schema({ items: { type: 'array' }, obj: { type: 'object' } }),
+        });
+        expect(findIssue(result.issues, 'undeclared_template_variable', variable)).toBeDefined();
+    });
+
+    it('counts @root reads as usage', () => {
+        const result = validatePrompt({
+            content: '{{#with obj}}{{@root.customer}}{{/with}}',
+            contentType: TemplateType.handlebars,
+            inputSchema: schema({ obj: { type: 'object' }, customer: { type: 'string' } }),
+        });
+        expect(result.issues).toEqual([]);
+    });
+
+    it('rejects a helper passed as an argument', () => {
+        const result = validatePrompt({ content: '{{#if stringify}}x{{/if}}', contentType: TemplateType.handlebars });
+        expect(findIssue(result.issues, 'helper_used_as_value', 'stringify')).toBeDefined();
+        expect(findIssue(result.issues, 'undeclared_template_variable')).toBeUndefined();
+    });
+
+    it('rejects a helper called without arguments', () => {
+        const result = validatePrompt({ content: '{{stringify}}', contentType: TemplateType.handlebars });
+        expect(findIssue(result.issues, 'helper_missing_arguments', 'stringify')).toBeDefined();
+        expect(findIssue(result.issues, 'undeclared_template_variable')).toBeUndefined();
+    });
+});