@vertesia/studio-utils 1.3.0

package/src/prompts/mock-data.ts

@@ -0,0 +1,63 @@
+import type { JSONSchema } from '@vertesia/common';
+
+/**
+ * Generate mock data that satisfies a JSON Schema.
+ *
+ * - string → `%property_name%` (visible placeholder, useful for previews and validation render tests)
+ * - number/integer → random value 0–100
+ * - boolean → true
+ * - array → 1–2 items recursively generated from the items schema
+ * - object → recursively populated from properties
+ * - null → null
+ * - $ref or unknown → `%property_name%`
+ *
+ * @param schema JSON schema to generate data for
+ * @param propertyName Name used for string placeholders (default `value`)
+ */
+export function generateMockData(schema: JSONSchema, propertyName: string = 'value'): unknown {
+    if ('$ref' in schema) {
+        return `%${propertyName}%`;
+    }
+
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    const primaryType = types[0];
+
+    switch (primaryType) {
+        case 'string':
+            return `%${propertyName}%`;
+
+        case 'number':
+        case 'integer':
+            return Math.floor(Math.random() * 101);
+
+        case 'boolean':
+            return true;
+
+        case 'array': {
+            const itemSchema = schema.items as JSONSchema;
+            if (itemSchema) {
+                const itemCount = Math.floor(Math.random() * 2) + 1;
+                return Array.from({ length: itemCount }, (_, index) =>
+                    generateMockData(itemSchema, `${propertyName}_${index}`),
+                );
+            }
+            return [];
+        }
+
+        case 'object': {
+            const result: Record<string, unknown> = {};
+            if (schema.properties) {
+                for (const [propName, propSchema] of Object.entries(schema.properties)) {
+                    result[propName] = generateMockData(propSchema, propName);
+                }
+            }
+            return result;
+        }
+
+        case 'null':
+            return null;
+
+        default:
+            return `%${propertyName}%`;
+    }
+}

package/src/prompts/render.test.ts

@@ -0,0 +1,109 @@
+import { PromptRole } from '@llumiverse/common';
+import {
+    type PromptSegmentDef,
+    PromptSegmentDefType,
+    PromptStatus,
+    type PromptTemplate,
+    TemplateType,
+} from '@vertesia/common';
+import { describe, expect, it } from 'vitest';
+
+import { renderSegments, renderTemplate } from './render.js';
+
+describe('renderTemplate', () => {
+    it('returns text content verbatim instead of evaluating it as JST', () => {
+        const content = 'You are a test assistant for skill validation. Be concise.';
+        expect(renderTemplate(content, TemplateType.text, {}, {})).toEqual(content);
+    });
+
+    it('renders handlebars templates', () => {
+        expect(renderTemplate('Hello {{name}}', TemplateType.handlebars, {}, { name: 'Ada' })).toEqual('Hello Ada');
+    });
+
+    it('renders JST templates', () => {
+        expect(
+            renderTemplate('return `Hello ${name}`', TemplateType.jst, { properties: { name: {} } }, { name: 'Ada' }),
+        ).toEqual('Hello Ada');
+    });
+});
+
+describe('renderSegments', () => {
+    it('renders a text system segment followed by a handlebars user segment', () => {
+        const segments: PromptSegmentDef<PromptTemplate>[] = [
+            {
+                type: PromptSegmentDefType.template,
+                template: createPromptTemplate({
+                    id: 'sys-1',
+                    role: PromptRole.system,
+                    content: 'You are a test assistant for skill validation. Be concise.',
+                    content_type: TemplateType.text,
+                }),
+            },
+            {
+                type: PromptSegmentDefType.template,
+                template: createPromptTemplate({
+                    id: 'user-1',
+                    role: PromptRole.user,
+                    content: 'Answer this question: {{question}}',
+                    content_type: TemplateType.handlebars,
+                }),
+            },
+        ];
+
+        expect(renderSegments(segments, { question: 'What is 2+2?' })).toEqual([
+            {
+                title: '@system',
+                content: 'You are a test assistant for skill validation. Be concise.',
+                segmentId: 'sys-1',
+            },
+            {
+                title: '@user',
+                content: 'Answer this question: What is 2+2?',
+                segmentId: 'user-1',
+            },
+        ]);
+    });
+
+    it('isolates a failing segment so the remaining segments still render', () => {
+        const segments: PromptSegmentDef<PromptTemplate>[] = [
+            {
+                type: PromptSegmentDefType.template,
+                template: createPromptTemplate({
+                    id: 'bad-1',
+                    content: 'return missingGlobal',
+                    content_type: TemplateType.jst,
+                }),
+            },
+            {
+                type: PromptSegmentDefType.template,
+                template: createPromptTemplate({
+                    id: 'good-1',
+                    content: 'Hello {{name}}',
+                    content_type: TemplateType.handlebars,
+                }),
+            },
+        ];
+
+        const result = renderSegments(segments, { name: 'Ada' });
+        expect(result[0].error).toBeInstanceOf(Error);
+        expect(result[1]).toEqual({ title: '@user', content: 'Hello Ada', segmentId: 'good-1' });
+    });
+});
+
+function createPromptTemplate(overrides: Partial<PromptTemplate>): PromptTemplate {
+    return {
+        id: 'prompt-1',
+        name: 'Greeting',
+        role: PromptRole.user,
+        status: PromptStatus.draft,
+        version: 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'),
+        ...overrides,
+    };
+}

package/src/prompts/render.ts

@@ -0,0 +1,192 @@
+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';
+
+export interface SegmentPreview {
+    error?: Error;
+    title: string;
+    content: string;
+    segmentId?: string;
+}
+
+/**
+ * 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.
+ *
+ * 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);
+    }
+    if (contentType === TemplateType.text) {
+        return code;
+    }
+    const globals = [...(schema.properties ? Object.keys(schema.properties) : []), '_model'];
+    return renderJsTemplate(code, globals, data);
+}
+
+/**
+ * Execute a JST (JavaScript Template) with given data.
+ * Returns a discriminated union to surface errors without throwing.
+ */
+export function executeJST(
+    jstContent: string,
+    schema: JSONSchema,
+    data: JSONObject,
+): { success: true; content: string } | { success: false; error: string } {
+    try {
+        const result = renderTemplate(jstContent, TemplateType.jst, schema, data);
+        return { success: true, content: result };
+    } catch (error) {
+        return { success: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+
+/**
+ * Execute a Handlebars template with given data.
+ * Returns a discriminated union to surface errors without throwing.
+ */
+export function executeHandlebars(
+    handlebarsContent: string,
+    schema: JSONSchema,
+    data: JSONObject,
+): { success: true; content: string } | { success: false; error: string } {
+    try {
+        const result = renderTemplate(handlebarsContent, TemplateType.handlebars, schema, data);
+        return { success: true, content: result };
+    } catch (error) {
+        return { success: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+
+function renderChatSegment(segment: PromptSegmentDef<PromptTemplate>, data: JSONObject) {
+    const chatKey = getChatKey(segment.configuration);
+    const chat = data[chatKey];
+    let content: string;
+    if (Array.isArray(chat)) {
+        content = JSON.stringify(chat, undefined, 2);
+    } else {
+        content = `No "${chatKey}" property found on input data`;
+    }
+    return {
+        title: 'Chat history',
+        content,
+    };
+}
+
+function renderTemplateSegment(segment: PromptSegmentDef<PromptTemplate>, data: JSONObject) {
+    if (!segment.template) {
+        return { title: '(unknown segment)', content: '', error: new Error('Prompt segment is missing its template') };
+    }
+    const schema = segment.template.inputSchema || {};
+    const title = `@${segment.template.role}`;
+    try {
+        const content = renderTemplate(segment.template.content, segment.template.content_type, schema, data);
+        return { title, content, segmentId: segment.template.id };
+    } catch (error) {
+        // Isolate the failure to this segment so the remaining segments still render.
+        return {
+            title,
+            content: error instanceof Error ? error.message : String(error),
+            segmentId: segment.template.id,
+            error: error instanceof Error ? error : new Error(String(error)),
+        };
+    }
+}
+
+export function renderSegments(segments: PromptSegmentDef<PromptTemplate>[], data: JSONObject): SegmentPreview[] {
+    const out: SegmentPreview[] = [];
+    for (const segment of segments) {
+        if (segment.type === PromptSegmentDefType.chat) {
+            out.push(renderChatSegment(segment, data));
+        } else if (segment.type === PromptSegmentDefType.template) {
+            out.push(renderTemplateSegment(segment, data));
+        }
+    }
+    return out;
+}
+
+export function renderSegmentsOrErrors(
+    segments: PromptSegmentDef<PromptTemplate>[],
+    textOrObject: string | JSONObject,
+): SegmentPreview[] {
+    try {
+        return renderSegments(
+            segments,
+            typeof textOrObject === 'string' ? JSON.parse(textOrObject.trim()) : textOrObject || {},
+        );
+    } catch (error: unknown) {
+        if (error instanceof CompositeError) {
+            return error.errors.map((err) => ({
+                error: err as Error,
+                title: 'Rendering Error',
+                content: err.message,
+            }));
+        }
+        return [
+            {
+                error: error instanceof Error ? error : new Error(String(error)),
+                title: 'Rendering Error',
+                content: error instanceof Error ? error.message : String(error),
+            },
+        ];
+    }
+}
+
+export function renderPrompt(segments: PromptSegmentDef<PromptTemplate>[], payload: JSONObject): PromptSegment[] {
+    const out: PromptSegment[] = [];
+    for (const segment of segments) {
+        if (segment.template) {
+            const schema = segment.template.inputSchema || {};
+            const content = renderTemplate(segment.template.content, segment.template.content_type, schema, payload);
+            out.push({ role: segment.template.role, content });
+        } else if (segment.type === PromptSegmentDefType.chat) {
+            const chatKey = getChatKey(segment.configuration);
+            const messages = payload[chatKey];
+            if (!isPromptSegmentArray(messages)) {
+                throw new Error('Chat prompt segment must have a messages array');
+            }
+            for (const msg of messages) {
+                if (!msg.role) {
+                    throw new Error('Chat prompt segment must have a role');
+                }
+                out.push({ role: msg.role, content: msg.content });
+            }
+        } else {
+            throw new Error(`Unknown prompt segment type: ${segment.type}`);
+        }
+    }
+    return out;
+}
+
+function getChatKey(configuration: unknown): string {
+    if (
+        typeof configuration === 'object' &&
+        configuration !== null &&
+        'chatKey' in configuration &&
+        typeof (configuration as { chatKey: unknown }).chatKey === 'string'
+    ) {
+        return (configuration as { chatKey: string }).chatKey;
+    }
+    return 'chat';
+}
+
+function isPromptSegmentArray(value: unknown): value is PromptSegment[] {
+    return Array.isArray(value) && value.every(isPromptSegment);
+}
+
+function isPromptSegment(value: unknown): value is PromptSegment {
+    return typeof value === 'object' && value !== null && 'role' in value && 'content' in value;
+}

package/src/prompts/validate.test.ts

@@ -0,0 +1,274 @@
+import type { JSONSchema } from '@vertesia/common';
+import { TemplateType } from '@vertesia/common';
+import { describe, expect, it } from 'vitest';
+import { type PromptValidationIssue, validatePrompt } from './validate.js';
+
+function findIssue(
+    issues: PromptValidationIssue[],
+    type: PromptValidationIssue['type'],
+    variable?: string,
+): PromptValidationIssue | undefined {
+    return issues.find((i) => i.type === type && (variable === undefined || i.variable === variable));
+}
+
+const schema = (properties: Record<string, JSONSchema>, required?: string[]): JSONSchema => ({
+    type: 'object',
+    properties,
+    ...(required ? { required } : {}),
+});
+
+describe('validatePrompt — text (no validation)', () => {
+    it('returns no issues for plain text content regardless of schema', () => {
+        const r = validatePrompt({
+            content: 'Hello, this is just text. {{not a template tag}}',
+            contentType: TemplateType.text,
+            inputSchema: schema({ unused: { type: 'string' } }),
+        });
+        expect(r.error_count).toBe(0);
+        expect(r.warning_count).toBe(0);
+        expect(r.issues).toHaveLength(0);
+    });
+});
+
+describe('validatePrompt — handlebars', () => {
+    describe('undeclared_template_variable (error)', () => {
+        it('flags a top-level variable that is not in the schema', () => {
+            const r = validatePrompt({
+                content: 'Summarize this document: {{document}}',
+                contentType: TemplateType.handlebars,
+                inputSchema: schema({}),
+            });
+            const issue = findIssue(r.issues, 'undeclared_template_variable', 'document');
+            expect(issue).toBeDefined();
+            expect(issue?.severity).toBe('error');
+            expect(r.error_count).toBeGreaterThanOrEqual(1);
+        });
+
+        it('flags multiple undeclared variables independently', () => {
+            const r = validatePrompt({
+                content: 'Hi {{name}}, your role is {{role}} and dept is {{dept}}',
+                contentType: TemplateType.handlebars,
+                inputSchema: schema({ name: { type: 'string' } }),
+            });
+            expect(findIssue(r.issues, 'undeclared_template_variable', 'role')).toBeDefined();
+            expect(findIssue(r.issues, 'undeclared_template_variable', 'dept')).toBeDefined();
+            expect(findIssue(r.issues, 'undeclared_template_variable', 'name')).toBeUndefined();
+        });
+
+        it('flags the root variable when the template uses dotted access', () => {
+            // Handlebars `{{user.name}}` references the top-level `user` — the schema must declare `user`.
+            const r = validatePrompt({
+                content: 'User: {{user.name}}',
+                contentType: TemplateType.handlebars,
+                inputSchema: schema({}),
+            });
+            expect(findIssue(r.issues, 'undeclared_template_variable', 'user')).toBeDefined();
+        });
+
+        it('treats no schema as schema with no properties', () => {
+            const r = validatePrompt({
+                content: 'Hello {{name}}',
+                contentType: TemplateType.handlebars,
+            });
+            expect(findIssue(r.issues, 'undeclared_template_variable', 'name')).toBeDefined();
+        });
+    });
+
+    describe('unused_schema_variable (warning)', () => {
+        it('flags a schema property that the template never references', () => {
+            const r = validatePrompt({
+                content: 'Hello {{name}}',
+                contentType: TemplateType.handlebars,
+                inputSchema: schema({
+                    name: { type: 'string' },
+                    extra: { type: 'string' },
+                }),
+            });
+            const issue = findIssue(r.issues, 'unused_schema_variable', 'extra');
+            expect(issue).toBeDefined();
+            expect(issue?.severity).toBe('warning');
+            expect(r.warning_count).toBeGreaterThanOrEqual(1);
+        });
+
+        it('does not block validation — only errors do', () => {
+            const r = validatePrompt({
+                content: 'Hello {{name}}',
+                contentType: TemplateType.handlebars,
+                inputSchema: schema({
+                    name: { type: 'string' },
+                    unused: { type: 'string' },
+                }),
+            });
+            expect(r.error_count).toBe(0);
+            expect(r.warning_count).toBe(1);
+        });
+    });
+
+    describe('handlebars_render_error (error)', () => {
+        it('flags a syntax error in the template', () => {
+            const r = validatePrompt({
+                // Unclosed mustache → handlebars parse error
+                content: 'Hello {{name',
+                contentType: TemplateType.handlebars,
+                inputSchema: schema({ name: { type: 'string' } }),
+            });
+            expect(findIssue(r.issues, 'handlebars_render_error')).toBeDefined();
+            expect(r.error_count).toBeGreaterThanOrEqual(1);
+        });
+    });
+
+    describe('happy path', () => {
+        it('returns zero issues when every template variable is declared and every declared variable is used', () => {
+            const r = validatePrompt({
+                content: 'Hello {{name}}, please summarize: {{document}}',
+                contentType: TemplateType.handlebars,
+                inputSchema: schema(
+                    {
+                        name: { type: 'string' },
+                        document: { type: 'string' },
+                    },
+                    ['name', 'document'],
+                ),
+            });
+            expect(r.error_count).toBe(0);
+            expect(r.warning_count).toBe(0);
+            expect(r.issues).toHaveLength(0);
+        });
+
+        it('accepts handlebars block helpers (#if/#each) on declared variables', () => {
+            const r = validatePrompt({
+                content: '{{#if items}}Items:{{#each items}}- {{this}}\n{{/each}}{{/if}}',
+                contentType: TemplateType.handlebars,
+                inputSchema: schema({ items: { type: 'array', items: { type: 'string' } } }),
+            });
+            expect(findIssue(r.issues, 'undeclared_template_variable', 'items')).toBeUndefined();
+            expect(r.error_count).toBe(0);
+        });
+    });
+
+    describe('combined errors + warnings', () => {
+        it('reports both kinds in one pass and counts them correctly', () => {
+            const r = validatePrompt({
+                content: 'Hi {{name}}, document: {{document}}',
+                contentType: TemplateType.handlebars,
+                inputSchema: schema({
+                    name: { type: 'string' },
+                    extra: { type: 'string' }, // unused → warning
+                    // document missing → error
+                }),
+            });
+            expect(findIssue(r.issues, 'undeclared_template_variable', 'document')).toBeDefined();
+            expect(findIssue(r.issues, 'unused_schema_variable', 'extra')).toBeDefined();
+            expect(r.error_count).toBe(1);
+            expect(r.warning_count).toBe(1);
+            expect(r.issues.length).toBe(2);
+        });
+    });
+
+    describe('ordering and independence of error sources', () => {
+        // Handlebars is non-strict — `{{undeclared}}` renders as empty string, NOT an exception.
+        // So an undeclared variable does not cause a render error; only one error is reported.
+        it('reports undeclared_template_variable only (render does not echo it in non-strict Handlebars)', () => {
+            const r = validatePrompt({
+                content: 'Hello {{undefined_var}}',
+                contentType: TemplateType.handlebars,
+                inputSchema: schema({}),
+            });
+            expect(findIssue(r.issues, 'undeclared_template_variable', 'undefined_var')).toBeDefined();
+            expect(findIssue(r.issues, 'handlebars_render_error')).toBeUndefined();
+            expect(r.error_count).toBe(1);
+        });
+
+        // When the template has both an undeclared variable AND a real parse error,
+        // we must surface both — and the variable error must appear first in the list
+        // so the LLM/user sees the precise reason before the generic render error.
+        it('reports BOTH undeclared_template_variable and handlebars_render_error, vars first', () => {
+            const r = validatePrompt({
+                // {{name has no closing brace → parse error. extractHandlebarsVariables fails
+                // silently and returns an empty set, so no undeclared error is raised by
+                // step 1 here — but the rendering step catches the parse failure.
+                content: 'Hello {{undefined_var}} and {{name',
+                contentType: TemplateType.handlebars,
+                inputSchema: schema({}),
+            });
+            // The renderer reports the parse problem; the var-extractor couldn't even parse the
+            // template, so it returned no usedVars and we cannot detect the undeclared var here.
+            // The contract is "both kinds are independent and both reported when applicable".
+            expect(findIssue(r.issues, 'handlebars_render_error')).toBeDefined();
+        });
+    });
+});
+
+describe('validatePrompt — jst', () => {
+    it('happy path: identifier referenced and declared', () => {
+        const r = validatePrompt({
+            content: 'return `hello ${name}`;',
+            contentType: TemplateType.jst,
+            inputSchema: schema({ name: { type: 'string' } }, ['name']),
+        });
+        expect(r.error_count).toBe(0);
+        expect(r.warning_count).toBe(0);
+    });
+
+    it('flags undeclared identifier as error', () => {
+        const r = validatePrompt({
+            content: 'return `hello ${name}`;',
+            contentType: TemplateType.jst,
+            inputSchema: schema({}),
+        });
+        expect(findIssue(r.issues, 'undeclared_template_variable', 'name')).toBeDefined();
+        expect(r.error_count).toBeGreaterThanOrEqual(1);
+    });
+
+    it('flags declared-but-unused as warning', () => {
+        const r = validatePrompt({
+            content: 'return `hello ${name}`;',
+            contentType: TemplateType.jst,
+            inputSchema: schema({
+                name: { type: 'string' },
+                unused: { type: 'string' },
+            }),
+        });
+        const issue = findIssue(r.issues, 'unused_schema_variable', 'unused');
+        expect(issue).toBeDefined();
+        expect(issue?.severity).toBe('warning');
+    });
+
+    it('does not flag locally-bound variables as undeclared', () => {
+        const r = validatePrompt({
+            content: 'const greeting = `hello ${name}`; return greeting;',
+            contentType: TemplateType.jst,
+            inputSchema: schema({ name: { type: 'string' } }, ['name']),
+        });
+        expect(findIssue(r.issues, 'undeclared_template_variable', 'greeting')).toBeUndefined();
+        expect(r.error_count).toBe(0);
+    });
+
+    it('does not flag jst auto-globals (_, Array, Set)', () => {
+        const r = validatePrompt({
+            content: 'return _.stringify({ count: Array.isArray(items) ? items.length : 0 });',
+            contentType: TemplateType.jst,
+            inputSchema: schema({ items: { type: 'array', items: { type: 'string' } } }, ['items']),
+        });
+        expect(findIssue(r.issues, 'undeclared_template_variable', '_')).toBeUndefined();
+        expect(findIssue(r.issues, 'undeclared_template_variable', 'Array')).toBeUndefined();
+    });
+
+    it('flags unsafe constructs (with) as jst_unsafe_construct', () => {
+        const r = validatePrompt({
+            content: 'with (foo) { return bar; }',
+            contentType: TemplateType.jst,
+            inputSchema: schema({ foo: { type: 'object' }, bar: { type: 'string' } }, ['foo', 'bar']),
+        });
+        expect(findIssue(r.issues, 'jst_unsafe_construct')).toBeDefined();
+    });
+
+    it('flags for-loops as jst_unsafe_construct', () => {
+        const r = validatePrompt({
+            content: 'for (let i = 0; i < items.length; i++) { return items[i]; } return null;',
+            contentType: TemplateType.jst,
+            inputSchema: schema({ items: { type: 'array', items: { type: 'string' } } }, ['items']),
+        });
+        expect(findIssue(r.issues, 'jst_unsafe_construct')).toBeDefined();
+    });
+});