@frontmcp/uipack 0.6.1

package/esm/validation/template-validator.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Template Validator
+ *
+ * Validates Handlebars templates against Zod schemas to catch
+ * references to non-existent fields.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+/**
+ * Validation error types.
+ */
+export type ValidationErrorType = 'missing_field' | 'invalid_path' | 'type_mismatch';
+/**
+ * Validation warning types.
+ */
+export type ValidationWarningType = 'optional_field' | 'array_access' | 'deep_path' | 'dynamic_path';
+/**
+ * A validation error for a missing or invalid field.
+ */
+export interface TemplateValidationError {
+    /** Error type */
+    type: ValidationErrorType;
+    /** The invalid path (e.g., "output.city") */
+    path: string;
+    /** The full Handlebars expression */
+    expression: string;
+    /** Line number in template */
+    line: number;
+    /** Column position */
+    column: number;
+    /** Human-readable error message */
+    message: string;
+    /** Suggested similar paths */
+    suggestions: string[];
+}
+/**
+ * A validation warning (non-blocking).
+ */
+export interface TemplateValidationWarning {
+    /** Warning type */
+    type: ValidationWarningType;
+    /** The path that triggered the warning */
+    path: string;
+    /** The full Handlebars expression */
+    expression: string;
+    /** Line number in template */
+    line: number;
+    /** Human-readable warning message */
+    message: string;
+}
+/**
+ * Result of template validation.
+ */
+export interface TemplateValidationResult {
+    /** Whether the template is valid (no errors) */
+    valid: boolean;
+    /** Validation errors (missing fields, etc.) */
+    errors: TemplateValidationError[];
+    /** Validation warnings (optional fields, etc.) */
+    warnings: TemplateValidationWarning[];
+    /** All paths found in the template */
+    templatePaths: string[];
+    /** All valid paths from the schema */
+    schemaPaths: string[];
+}
+/**
+ * Options for template validation.
+ */
+export interface ValidateTemplateOptions {
+    /** Schema for input.* paths (optional) */
+    inputSchema?: z.ZodTypeAny;
+    /** Warn when accessing optional fields without {{#if}} guard */
+    warnOnOptional?: boolean;
+    /** Suggest similar paths for typos */
+    suggestSimilar?: boolean;
+    /** Maximum Levenshtein distance for suggestions */
+    maxSuggestionDistance?: number;
+    /** Tool name for error messages */
+    toolName?: string;
+}
+/**
+ * Validate a Handlebars template against an output schema.
+ *
+ * @param template - The Handlebars template string
+ * @param outputSchema - Zod schema for the output
+ * @param options - Validation options
+ * @returns Validation result with errors and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = validateTemplate(
+ *   '<div>{{output.temperature}} in {{output.city}}</div>',
+ *   z.object({ temperature: z.number() })
+ * );
+ *
+ * if (!result.valid) {
+ *   console.warn('Template has issues:', result.errors);
+ * }
+ * ```
+ */
+export declare function validateTemplate(template: string, outputSchema: z.ZodTypeAny, options?: ValidateTemplateOptions): TemplateValidationResult;
+/**
+ * Format validation result as console warnings.
+ *
+ * @param result - Validation result
+ * @param toolName - Tool name for context
+ * @returns Formatted warning string
+ */
+export declare function formatValidationWarnings(result: TemplateValidationResult, toolName: string): string;
+/**
+ * Log validation warnings to console in development mode.
+ *
+ * @param result - Validation result
+ * @param toolName - Tool name for context
+ */
+export declare function logValidationWarnings(result: TemplateValidationResult, toolName: string): void;
+/**
+ * Validate template and throw if invalid.
+ *
+ * @param template - The template to validate
+ * @param outputSchema - Output schema
+ * @param toolName - Tool name for error message
+ * @throws Error if template has validation errors
+ */
+export declare function assertTemplateValid(template: string, outputSchema: z.ZodTypeAny, toolName: string): void;
+/**
+ * Quickly check if a template is valid against a schema.
+ *
+ * @param template - The template to validate
+ * @param outputSchema - Output schema
+ * @returns true if valid, false otherwise
+ */
+export declare function isTemplateValid(template: string, outputSchema: z.ZodTypeAny): boolean;
+/**
+ * Get missing fields from a template.
+ *
+ * @param template - The template to check
+ * @param outputSchema - Output schema
+ * @returns Array of missing field paths
+ */
+export declare function getMissingFields(template: string, outputSchema: z.ZodTypeAny): string[];
+//# sourceMappingURL=template-validator.d.ts.map

package/esm/validation/template-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-validator.d.ts","sourceRoot":"","sources":["../../../src/validation/template-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAoBxB;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,eAAe,GAAG,cAAc,GAAG,eAAe,CAAC;AAErF;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,gBAAgB,GAAG,cAAc,GAAG,WAAW,GAAG,cAAc,CAAC;AAErG;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,iBAAiB;IACjB,IAAI,EAAE,mBAAmB,CAAC;IAC1B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,mBAAmB;IACnB,IAAI,EAAE,qBAAqB,CAAC;IAC5B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,gDAAgD;IAChD,KAAK,EAAE,OAAO,CAAC;IACf,+CAA+C;IAC/C,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAClC,kDAAkD;IAClD,QAAQ,EAAE,yBAAyB,EAAE,CAAC;IACtC,sCAAsC;IACtC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,sCAAsC;IACtC,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,0CAA0C;IAC1C,WAAW,CAAC,EAAE,CAAC,CAAC,UAAU,CAAC;IAC3B,gEAAgE;IAChE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,sCAAsC;IACtC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mDAAmD;IACnD,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,CAAC,CAAC,UAAU,EAC1B,OAAO,GAAE,uBAA4B,GACpC,wBAAwB,CAsG1B;AA4HD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,wBAAwB,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CA0CnG;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,wBAAwB,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAK9F;AAMD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAOxG;AAMD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,UAAU,GAAG,OAAO,CAGrF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,UAAU,GAAG,MAAM,EAAE,CAGvF"}

package/esm/validation/wrapper.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @file wrapper.ts
+ * @description Validation wrapper utilities for component input validation.
+ *
+ * Provides functions to validate component options against Zod schemas
+ * and return either the validated data or an error box HTML string.
+ *
+ * @example
+ * ```typescript
+ * import { validateOptions } from '@frontmcp/ui';
+ * import { z } from 'zod';
+ *
+ * const schema = z.object({ variant: z.enum(['primary', 'secondary']) });
+ *
+ * const result = validateOptions(options, {
+ *   componentName: 'Button',
+ *   schema,
+ * });
+ *
+ * if (!result.success) return result.error; // Returns error box HTML
+ *
+ * // Use result.data safely
+ * ```
+ *
+ * @module @frontmcp/ui/validation/wrapper
+ */
+import { type ZodSchema } from 'zod';
+/**
+ * Configuration for validation
+ */
+export interface ValidationConfig {
+    /** Name of the component being validated */
+    componentName: string;
+    /** Zod schema to validate against */
+    schema: ZodSchema;
+}
+/**
+ * Result of validation - either success with data or failure with error HTML
+ */
+export type ValidationResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Validates input against a Zod schema
+ *
+ * Returns either:
+ * - `{ success: true, data: T }` with validated/parsed data
+ * - `{ success: false, error: string }` with error box HTML
+ *
+ * @param options - The options object to validate
+ * @param config - Validation configuration (component name and schema)
+ * @returns ValidationResult with either data or error HTML
+ *
+ * @example
+ * ```typescript
+ * const result = validateOptions({ variant: 'invalid' }, {
+ *   componentName: 'Button',
+ *   schema: ButtonOptionsSchema,
+ * });
+ *
+ * if (!result.success) {
+ *   return result.error; // Error box HTML
+ * }
+ *
+ * // result.data is typed and validated
+ * ```
+ */
+export declare function validateOptions<T>(options: unknown, config: ValidationConfig): ValidationResult<T>;
+/**
+ * Higher-order function to wrap a component function with validation
+ *
+ * Creates a new function that validates the options before calling the
+ * original component. If validation fails, returns the error box HTML
+ * instead of calling the component.
+ *
+ * @param componentFn - The original component function
+ * @param config - Validation configuration
+ * @returns Wrapped function that validates before calling
+ *
+ * @example
+ * ```typescript
+ * const buttonImpl = (text: string, opts: ButtonOptions) => `<button>...</button>`;
+ *
+ * const button = withValidation(buttonImpl, {
+ *   componentName: 'Button',
+ *   schema: ButtonOptionsSchema,
+ * });
+ *
+ * // button() now validates options before rendering
+ * ```
+ */
+export declare function withValidation<TInput, TOptions>(componentFn: (input: TInput, options: TOptions) => string, config: ValidationConfig): (input: TInput, options: unknown) => string;
+//# sourceMappingURL=wrapper.d.ts.map

package/esm/validation/wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrapper.d.ts","sourceRoot":"","sources":["../../../src/validation/wrapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,KAAK,CAAC;AAOrC;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,MAAM,EAAE,SAAS,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAiBjG;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAiBlG;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,QAAQ,EAC7C,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,KAAK,MAAM,EACzD,MAAM,EAAE,gBAAgB,GACvB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,MAAM,CAU7C"}

package/handlebars/expression-extractor.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Handlebars Expression Extractor
+ *
+ * Extracts variable paths from Handlebars templates for validation
+ * against schemas.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Type of Handlebars expression.
+ */
+export type ExpressionType = 'variable' | 'helper' | 'block' | 'block-close';
+/**
+ * Extracted expression with metadata.
+ */
+export interface ExtractedExpression {
+    /** The variable path (e.g., "output.temperature") */
+    path: string;
+    /** The full expression (e.g., "{{output.temperature}}") */
+    fullExpression: string;
+    /** Line number in template (1-indexed) */
+    line: number;
+    /** Column position (1-indexed) */
+    column: number;
+    /** Type of expression */
+    type: ExpressionType;
+    /** For helpers, the helper name */
+    helperName?: string;
+}
+/**
+ * Result of expression extraction.
+ */
+export interface ExtractionResult {
+    /** All extracted expressions */
+    expressions: ExtractedExpression[];
+    /** Unique variable paths */
+    paths: string[];
+    /** Paths starting with "output." */
+    outputPaths: string[];
+    /** Paths starting with "input." */
+    inputPaths: string[];
+    /** Paths starting with "structuredContent." */
+    structuredContentPaths: string[];
+}
+/**
+ * Extract all Handlebars expressions from a template.
+ *
+ * @param template - Handlebars template string
+ * @returns Array of extracted expressions with metadata
+ *
+ * @example
+ * ```typescript
+ * const expressions = extractExpressions('<div>{{output.name}}</div>');
+ * // [{ path: 'output.name', fullExpression: '{{output.name}}', ... }]
+ * ```
+ */
+export declare function extractExpressions(template: string): ExtractedExpression[];
+/**
+ * Extract all variable paths from a template.
+ *
+ * @param template - Handlebars template string
+ * @returns Array of unique variable paths
+ *
+ * @example
+ * ```typescript
+ * const paths = extractVariablePaths('<div>{{output.a}} {{input.b}}</div>');
+ * // ['output.a', 'input.b']
+ * ```
+ */
+export declare function extractVariablePaths(template: string): string[];
+/**
+ * Extract only output.* paths from a template.
+ *
+ * @param template - Handlebars template string
+ * @returns Array of unique output paths
+ *
+ * @example
+ * ```typescript
+ * const paths = extractOutputPaths('<div>{{output.temp}} {{input.city}}</div>');
+ * // ['output.temp']
+ * ```
+ */
+export declare function extractOutputPaths(template: string): string[];
+/**
+ * Extract only input.* paths from a template.
+ *
+ * @param template - Handlebars template string
+ * @returns Array of unique input paths
+ */
+export declare function extractInputPaths(template: string): string[];
+/**
+ * Extract only structuredContent.* paths from a template.
+ *
+ * @param template - Handlebars template string
+ * @returns Array of unique structuredContent paths
+ */
+export declare function extractStructuredContentPaths(template: string): string[];
+/**
+ * Comprehensive extraction returning all path categories.
+ *
+ * @param template - Handlebars template string
+ * @returns Extraction result with categorized paths
+ *
+ * @example
+ * ```typescript
+ * const result = extractAll('<div>{{output.a}} {{input.b}}</div>');
+ * // {
+ * //   expressions: [...],
+ * //   paths: ['output.a', 'input.b'],
+ * //   outputPaths: ['output.a'],
+ * //   inputPaths: ['input.b'],
+ * //   structuredContentPaths: []
+ * // }
+ * ```
+ */
+export declare function extractAll(template: string): ExtractionResult;
+/**
+ * Check if a template contains any Handlebars expressions with variable paths.
+ *
+ * @param template - Handlebars template string
+ * @returns true if template contains variable paths
+ */
+export declare function hasVariablePaths(template: string): boolean;
+/**
+ * Get expression details at a specific line and column.
+ *
+ * @param template - Handlebars template string
+ * @param line - Line number (1-indexed)
+ * @param column - Column number (1-indexed)
+ * @returns Expression at position or undefined
+ */
+export declare function getExpressionAt(template: string, line: number, column: number): ExtractedExpression | undefined;
+/**
+ * Normalize a path for comparison.
+ * Converts array index access to wildcard format.
+ *
+ * @param path - Variable path
+ * @returns Normalized path
+ *
+ * @example
+ * ```typescript
+ * normalizePath('output.items.0.name'); // 'output.items.[].name'
+ * normalizePath('output.data[0].value'); // 'output.data.[].value'
+ * ```
+ */
+export declare function normalizePath(path: string): string;
+//# sourceMappingURL=expression-extractor.d.ts.map

package/handlebars/expression-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expression-extractor.d.ts","sourceRoot":"","sources":["../../src/handlebars/expression-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,aAAa,CAAC;AAE7E;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,cAAc,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,IAAI,EAAE,cAAc,CAAC;IACrB,mCAAmC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gCAAgC;IAChC,WAAW,EAAE,mBAAmB,EAAE,CAAC;IACnC,4BAA4B;IAC5B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,oCAAoC;IACpC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mCAAmC;IACnC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,+CAA+C;IAC/C,sBAAsB,EAAE,MAAM,EAAE,CAAC;CAClC;AAwCD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAmE1E;AAgDD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAI/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAE7D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAExE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAW7D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAS/G;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQlD"}