@vertesia/studio-utils 1.6.0-dev.20260918.115658Z → 1.6.0-dev.20261004.085740Z

package/lib/conditions/index.d.ts

@@ -1,2 +1,3 @@
 export { matchConditions, matchLike, resolveConditions, resolvePath } from './match.js';
+export { buildPrincipalContext, type MergedUserFields, type MergeSource, mergeUserFields, } from './principal-context.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/conditions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/conditions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/conditions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,EACH,qBAAqB,EACrB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,eAAe,GAClB,MAAM,wBAAwB,CAAC"}

package/lib/conditions/index.js

@@ -1,2 +1,3 @@
 export { matchConditions, matchLike, resolveConditions, resolvePath } from './match.js';
+export { buildPrincipalContext, mergeUserFields, } from './principal-context.js';
 //# sourceMappingURL=index.js.map

package/lib/conditions/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/conditions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/conditions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,EACH,qBAAqB,EAGrB,eAAe,GAClB,MAAM,wBAAwB,CAAC"}

package/lib/conditions/principal-context.d.ts

@@ -0,0 +1,55 @@
+import type { AbacPrincipalContext, PrincipalKind } from '@vertesia/common';
+/**
+ * The shared principal-context builder, consumed by both the token server (JWT `$principal.*`
+ * resolution at mint time) and studio-server (the `/iam/users/identity` endpoint). It is the single
+ * home for logic that used to be duplicated in `apps/token-server` and `apps/studio-server` and kept
+ * in sync by hand; the produced {@link AbacPrincipalContext} is exactly the shape ABAC rules resolve
+ * against.
+ *
+ * Browser-safe (pure, no Node built-ins): the UI condition editor lives downstream of the same
+ * `@vertesia/common` shape, and this package must stay loadable in the browser bundle.
+ */
+/**
+ * A user, group, or api-key record as it comes out of Mongo, where every optional field can be null
+ * as well as absent — which the inferred persistence types say out loud. The merge treats null and
+ * absent identically, so nothing about the resulting context changes; what changes is that the
+ * nullability is handled rather than asserted away at the call site.
+ */
+export interface MergeSource {
+    properties?: Record<string, unknown> | null;
+    clearance?: number | null;
+    compartments?: string[] | null;
+    tags?: string[] | null;
+}
+export interface MergedUserFields {
+    properties?: Record<string, unknown>;
+    clearance?: number;
+    compartments?: string[];
+    tags?: string[];
+}
+/**
+ * Merge properties, clearance, compartments, and tags from groups + the principal.
+ *
+ * - properties: array values are deduplicated union, scalars use last-write-wins (principal wins)
+ * - clearance: max across all defined values (most permissive wins)
+ * - compartments / tags: deduplicated union of all arrays
+ *
+ * Used for the user token path (user + covering groups). The api-key path has no groups to merge and
+ * passes the key document straight to {@link buildPrincipalContext} as `fields`.
+ */
+export declare function mergeUserFields(groups: MergeSource[], user: MergeSource): MergedUserFields;
+/**
+ * Build the {@link AbacPrincipalContext} consumed by ResourceSet/PrincipalSet condition evaluation
+ * and mirrored into the JWT for runtime `$principal.*` resolution.
+ *
+ * - user:   pass `mergeUserFields(groups, user)` as fields, the user's email, and the user id
+ * - apikey: pass the api key document itself (it carries optional properties/clearance/compartments)
+ *   and the api key id
+ *
+ * Defaults are applied so condition operators have well-defined behaviour when the principal has no
+ * merged value: clearance → 0, compartments → [], tags → [], properties → {}, id → '', email → ''.
+ * `email` is published optional on the wire but defaulted to '' here so `$principal.email` resolves
+ * to a string rather than undefined during rule evaluation.
+ */
+export declare function buildPrincipalContext(kind: PrincipalKind, fields: MergeSource, email?: string | null, id?: string): AbacPrincipalContext;
+//# sourceMappingURL=principal-context.d.ts.map

package/lib/conditions/principal-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal-context.d.ts","sourceRoot":"","sources":["../../src/conditions/principal-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE5E;;;;;;;;;GASG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5C,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC/B,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,WAAW,GAAG,gBAAgB,CAgD1F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACjC,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,WAAW,EACnB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,EACrB,EAAE,CAAC,EAAE,MAAM,GACZ,oBAAoB,CAUtB"}

package/lib/conditions/principal-context.js

@@ -0,0 +1,81 @@
+/**
+ * Merge properties, clearance, compartments, and tags from groups + the principal.
+ *
+ * - properties: array values are deduplicated union, scalars use last-write-wins (principal wins)
+ * - clearance: max across all defined values (most permissive wins)
+ * - compartments / tags: deduplicated union of all arrays
+ *
+ * Used for the user token path (user + covering groups). The api-key path has no groups to merge and
+ * passes the key document straight to {@link buildPrincipalContext} as `fields`.
+ */
+export function mergeUserFields(groups, user) {
+    const mergedProps = {};
+    let maxClearance;
+    const allCompartments = new Set();
+    const allTags = new Set();
+    for (const source of [...groups, user]) {
+        if (source.properties) {
+            for (const [key, value] of Object.entries(source.properties)) {
+                if (Array.isArray(value)) {
+                    const existing = mergedProps[key];
+                    if (Array.isArray(existing)) {
+                        const set = new Set([...existing, ...value]);
+                        mergedProps[key] = Array.from(set);
+                    }
+                    else {
+                        mergedProps[key] = [...value];
+                    }
+                }
+                else {
+                    mergedProps[key] = value;
+                }
+            }
+        }
+        // `!= null` rather than `!== undefined`: a stored null means "no clearance recorded", the
+        // same as an absent field, and must not reach Math.max where it would read as 0.
+        if (source.clearance != null) {
+            maxClearance = maxClearance !== undefined ? Math.max(maxClearance, source.clearance) : source.clearance;
+        }
+        if (source.compartments) {
+            for (const c of source.compartments) {
+                allCompartments.add(c);
+            }
+        }
+        if (source.tags) {
+            for (const t of source.tags) {
+                allTags.add(t);
+            }
+        }
+    }
+    return {
+        properties: Object.keys(mergedProps).length > 0 ? mergedProps : undefined,
+        clearance: maxClearance,
+        compartments: allCompartments.size > 0 ? Array.from(allCompartments) : undefined,
+        tags: allTags.size > 0 ? Array.from(allTags) : undefined,
+    };
+}
+/**
+ * Build the {@link AbacPrincipalContext} consumed by ResourceSet/PrincipalSet condition evaluation
+ * and mirrored into the JWT for runtime `$principal.*` resolution.
+ *
+ * - user:   pass `mergeUserFields(groups, user)` as fields, the user's email, and the user id
+ * - apikey: pass the api key document itself (it carries optional properties/clearance/compartments)
+ *   and the api key id
+ *
+ * Defaults are applied so condition operators have well-defined behaviour when the principal has no
+ * merged value: clearance → 0, compartments → [], tags → [], properties → {}, id → '', email → ''.
+ * `email` is published optional on the wire but defaulted to '' here so `$principal.email` resolves
+ * to a string rather than undefined during rule evaluation.
+ */
+export function buildPrincipalContext(kind, fields, email, id) {
+    return {
+        kind,
+        id: id ?? '',
+        clearance: fields.clearance ?? 0,
+        compartments: fields.compartments ?? [],
+        email: email ?? '',
+        tags: fields.tags ?? [],
+        properties: fields.properties ?? {},
+    };
+}
+//# sourceMappingURL=principal-context.js.map

package/lib/conditions/principal-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal-context.js","sourceRoot":"","sources":["../../src/conditions/principal-context.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts

@@ -1,5 +1,6 @@
+export { describeTemplateSystemVariables, HANDLEBARS_HELPER_NAMES, isTemplateSystemVariable, TEMPLATE_SYSTEM_VARIABLE_NAMES, TEMPLATE_SYSTEM_VARIABLES, type TemplateSystemContext, type TemplateSystemVariable, type TemplateSystemVariableName, withTemplateSystemVariables, } from '@vertesia/jst';
 export { substituteEndpoints } from './apps/index.js';
-export { extractHandlebarsVariables } from './prompts/extract-vars.js';
+export { analyzeHandlebarsTemplate, extractHandlebarsVariables, type HandlebarsHelperMisuse, type HandlebarsTemplateAnalysis, type HandlebarsVariableReference, } from './prompts/extract-vars.js';
 export { generateMockData } from './prompts/mock-data.js';
 export { executeHandlebars, executeJST, renderPrompt, renderSegments, renderSegmentsOrErrors, renderTemplate, type SegmentPreview, } from './prompts/render.js';
 export { type PromptValidationInput, type PromptValidationIssue, type PromptValidationIssueSeverity, type PromptValidationIssueType, type PromptValidationResult, validatePrompt, } from './prompts/validate.js';

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EACH,iBAAiB,EACjB,UAAU,EACV,YAAY,EACZ,cAAc,EACd,sBAAsB,EACtB,cAAc,EACd,KAAK,cAAc,GACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACH,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,6BAA6B,EAClC,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAC3B,cAAc,GACjB,MAAM,uBAAuB,CAAC;AAC/B,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACH,+BAA+B,EAC/B,uBAAuB,EACvB,wBAAwB,EACxB,8BAA8B,EAC9B,yBAAyB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,EAC/B,2BAA2B,GAC9B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EACH,yBAAyB,EACzB,0BAA0B,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,EAC/B,KAAK,2BAA2B,GACnC,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EACH,iBAAiB,EACjB,UAAU,EACV,YAAY,EACZ,cAAc,EACd,sBAAsB,EACtB,cAAc,EACd,KAAK,cAAc,GACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACH,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,6BAA6B,EAClC,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAC3B,cAAc,GACjB,MAAM,uBAAuB,CAAC;AAC/B,cAAc,kBAAkB,CAAC"}

package/lib/index.js

@@ -1,5 +1,8 @@
+// The template runtime's registry, re-exported so consumers validating or documenting prompts
+// read the same names the renderer uses.
+export { describeTemplateSystemVariables, HANDLEBARS_HELPER_NAMES, isTemplateSystemVariable, TEMPLATE_SYSTEM_VARIABLE_NAMES, TEMPLATE_SYSTEM_VARIABLES, withTemplateSystemVariables, } from '@vertesia/jst';
 export { substituteEndpoints } from './apps/index.js';
-export { extractHandlebarsVariables } from './prompts/extract-vars.js';
+export { analyzeHandlebarsTemplate, extractHandlebarsVariables, } from './prompts/extract-vars.js';
 export { generateMockData } from './prompts/mock-data.js';
 export { executeHandlebars, executeJST, renderPrompt, renderSegments, renderSegmentsOrErrors, renderTemplate, } from './prompts/render.js';
 export { validatePrompt, } from './prompts/validate.js';

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EACH,iBAAiB,EACjB,UAAU,EACV,YAAY,EACZ,cAAc,EACd,sBAAsB,EACtB,cAAc,GAEjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAMH,cAAc,GACjB,MAAM,uBAAuB,CAAC;AAC/B,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,yCAAyC;AACzC,OAAO,EACH,+BAA+B,EAC/B,uBAAuB,EACvB,wBAAwB,EACxB,8BAA8B,EAC9B,yBAAyB,EAIzB,2BAA2B,GAC9B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EACH,yBAAyB,EACzB,0BAA0B,GAI7B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EACH,iBAAiB,EACjB,UAAU,EACV,YAAY,EACZ,cAAc,EACd,sBAAsB,EACtB,cAAc,GAEjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAMH,cAAc,GACjB,MAAM,uBAAuB,CAAC;AAC/B,cAAc,kBAAkB,CAAC"}

package/lib/prompts/extract-vars.d.ts

@@ -1,19 +1,51 @@
+/** 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[];
+}
 /**
- * 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)
+ * 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.
  *
- * 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.
+ * Returns null when the template does not parse; the render check reports the syntax error.
+ */
+export declare function analyzeHandlebarsTemplate(template: string): HandlebarsTemplateAnalysis | null;
+/**
+ * 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 — callers should also run a syntactic render check
- * (e.g. `executeHandlebars`) to surface parse errors separately.
+ * Returns an empty set on parse failure.
  */
 export declare function extractHandlebarsVariables(template: string): Set<string>;
 //# sourceMappingURL=extract-vars.d.ts.map

package/lib/prompts/extract-vars.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract-vars.d.ts","sourceRoot":"","sources":["../../src/prompts/extract-vars.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CA6FxE"}
+{"version":3,"file":"extract-vars.d.ts","sourceRoot":"","sources":["../../src/prompts/extract-vars.ts"],"names":[],"mappings":"AAGA,gDAAgD;AAChD,MAAM,WAAW,2BAA2B;IACxC,sGAAsG;IACtG,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,GAAG,EAAE,MAAM,CAAC;CACf;AAED,4DAA4D;AAC5D,MAAM,WAAW,sBAAsB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,EAAE,eAAe,GAAG,mBAAmB,CAAC;IAC/C,GAAG,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,0BAA0B;IACvC,UAAU,EAAE,2BAA2B,EAAE,CAAC;IAC1C,aAAa,EAAE,sBAAsB,EAAE,CAAC;CAC3C;AAyCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,0BAA0B,GAAG,IAAI,CA2J7F;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAGxE"}

package/lib/prompts/extract-vars.js

@@ -1,114 +1,201 @@
+import { HANDLEBARS_CONTEXT_HELPERS, isHandlebarsHelper, isTemplateSystemVariable } from '@vertesia/jst';
 import Handlebars from 'handlebars';
+function isPath(node) {
+    return !!node && typeof node === 'object' && node.type === 'PathExpression';
+}
+/** `this.x`, `./x` and `this` read the context explicitly — Handlebars never treats them as helpers. */
+function isScoped(path) {
+    return /^\.|this\b/.test(path.original);
+}
+/** A single bare identifier — the only form Handlebars may resolve to a helper. */
+function isSimpleId(path) {
+    return path.parts.length === 1 && !isScoped(path) && !path.data && path.depth === 0;
+}
+function lineOffsets(template) {
+    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.
- *
- * - `{{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)
+ * 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`).
  *
- * 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) {
+export function analyzeHandlebarsTemplate(template) {
     let ast;
     try {
         ast = Handlebars.parse(template);
     }
     catch {
-        return new Set();
+        return null;
     }
-    const variables = new Set();
-    const localScopes = [];
-    const isLocal = (name) => localScopes.some((scope) => scope.has(name));
+    const offsets = lineOffsets(template);
+    const tagAt = (loc) => {
+        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 references = [];
+    const helperMisuses = [];
+    const contexts = ['root'];
+    const blockParams = [];
+    let tag = '';
+    const isBlockParam = (name) => blockParams.some((scope) => scope.has(name));
+    /** Record a data read of `path`, if it reads the root input. */
+    const readData = (path) => {
+        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 });
+    };
+    /** A path in argument position (params, hash values): Handlebars reads data, never calls a helper. */
+    const visitArgument = (node) => {
+        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);
+    };
+    const visitCall = (n) => {
+        const params = n.params ?? [];
+        for (const p of params)
+            visitArgument(p);
+        const pairs = n.hash?.pairs ?? [];
+        for (const pair of pairs)
+            visitArgument(pair.value);
+    };
+    const hasArguments = (n) => (n.params?.length ?? 0) > 0 ||
+        (n.hash?.pairs?.length ?? 0) > 0;
     const visit = (node) => {
         if (!node || typeof node !== 'object')
             return;
         const n = node;
         switch (n.type) {
             case 'Program': {
-                const body = n.body;
-                if (body)
-                    for (const stmt of body)
-                        visit(stmt);
+                for (const stmt of n.body ?? [])
+                    visit(stmt);
+                break;
+            }
+            case 'MustacheStatement': {
+                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);
+                }
                 break;
             }
             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;
-                if (params)
-                    for (const p of params)
-                        visit(p);
-                visit(n.hash);
-                // Track `as |x y|` block params — these are local bindings, not variables.
+                tag = tagAt(n.loc);
+                const path = n.path;
+                const helper = isPath(path) && isSimpleId(path) ? path.parts[0] : undefined;
+                let itemContext;
+                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;
                 const inverse = n.inverse;
-                const scope = new Set([...(program?.blockParams ?? []), ...(inverse?.blockParams ?? [])]);
-                localScopes.push(scope);
+                blockParams.push(new Set(program?.blockParams ?? []));
+                contexts.push(itemContext ? 'item' : contexts[contexts.length - 1]);
                 visit(n.program);
+                contexts.pop();
+                blockParams.pop();
+                // `{{else}}` renders with the enclosing context.
+                blockParams.push(new Set(inverse?.blockParams ?? []));
                 visit(n.inverse);
-                localScopes.pop();
-                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;
-                const hash = n.hash;
-                const isHelperCall = (params?.length ?? 0) > 0 || (hash?.pairs?.length ?? 0) > 0;
-                // The renderer registers _now as a zero-argument helper. Only the bare
-                // helper invocation is implicit; paths such as this._now remain data reads.
-                const path = n.path;
-                if (!isHelperCall && path?.original !== '_now') {
-                    visit(n.path);
-                }
-                if (params)
-                    for (const p of params)
-                        visit(p);
-                visit(hash);
+                blockParams.pop();
                 break;
             }
             case 'SubExpression': {
-                // (helper arg1 arg2) — helper name in path is skipped, args carry variables.
-                const params = n.params;
-                if (params)
-                    for (const p of params)
-                        visit(p);
-                visit(n.hash);
+                // `(helper arg)`: the head is a call, like a bare `{{helper}}`.
+                visitCall(n);
                 break;
             }
-            case 'PathExpression': {
-                if (n.data)
-                    break; // `@-data` references (@index, @key, etc.)
-                const parts = n.parts;
-                if (!parts || parts.length === 0)
-                    break; // `this` / `.`
-                const root = parts[0];
-                if (isLocal(root))
-                    break;
-                variables.add(root);
-                break;
-            }
-            case 'Hash': {
-                const pairs = n.pairs;
-                if (pairs)
-                    for (const pair of pairs)
-                        visit(pair.value);
-                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) {
+    const analysis = analyzeHandlebarsTemplate(template);
+    return new Set(analysis?.references.map((r) => r.name) ?? []);
 }
 //# sourceMappingURL=extract-vars.js.map

package/lib/prompts/extract-vars.js.map

@@ -1 +1 @@
-{"version":3,"file":"extract-vars.js","sourceRoot":"","sources":["../../src/prompts/extract-vars.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"extract-vars.js","sourceRoot":"","sources":["../../src/prompts/extract-vars.ts"],"names":[],"mappings":"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"}

package/lib/prompts/render.d.ts

@@ -1,5 +1,6 @@
 import type { JSONObject, JSONSchema, PromptSegment } from '@llumiverse/common';
 import { type PromptSegmentDef, type PromptTemplate, TemplateType } from '@vertesia/common';
+import { type TemplateSystemContext } from '@vertesia/jst';
 export interface SegmentPreview {
     error?: Error;
     title: string;
@@ -9,21 +10,18 @@ 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 declare function renderTemplate(code: string, contentType: TemplateType, schema: JSONSchema, data: JSONObject): string;
+export declare function renderTemplate(code: string, contentType: TemplateType, schema: JSONSchema, data: JSONObject, system?: TemplateSystemContext): string;
 /**
  * Execute a JST (JavaScript Template) with given data.
  * Returns a discriminated union to surface errors without throwing.