@frontmcp/uipack 0.6.1

package/validation/index.js

@@ -0,0 +1,583 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// libs/uipack/src/validation/index.ts
+var validation_exports = {};
+__export(validation_exports, {
+  assertTemplateValid: () => assertTemplateValid,
+  extractSchemaPaths: () => extractSchemaPaths,
+  formatValidationWarnings: () => formatValidationWarnings,
+  getMissingFields: () => getMissingFields,
+  getPathInfo: () => getPathInfo,
+  getRootFieldNames: () => getRootFieldNames,
+  getSchemaPathStrings: () => getSchemaPathStrings,
+  getTypeAtPath: () => getTypeAtPath,
+  getTypeDescription: () => getTypeDescription,
+  isTemplateValid: () => isTemplateValid,
+  isValidSchemaPath: () => isValidSchemaPath,
+  logValidationWarnings: () => logValidationWarnings,
+  validateOptions: () => validateOptions,
+  validateTemplate: () => validateTemplate,
+  validationErrorBox: () => validationErrorBox
+});
+module.exports = __toCommonJS(validation_exports);
+
+// libs/uipack/src/utils/escape-html.ts
+function escapeHtml(str) {
+  if (str === null || str === void 0) {
+    return "";
+  }
+  const s = String(str);
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+
+// libs/uipack/src/validation/error-box.ts
+var errorIcon = `<svg class="w-5 h-5 flex-shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+  <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"/>
+</svg>`;
+function validationErrorBox(options) {
+  const { componentName, invalidParam } = options;
+  return `<div
+  class="validation-error flex items-start gap-3 p-4 bg-red-50 border border-red-200 text-red-800 rounded-lg"
+  role="alert"
+  data-testid="validation-error"
+  data-component="${escapeHtml(componentName)}"
+  data-param="${escapeHtml(invalidParam)}"
+>
+  ${errorIcon}
+  <div class="min-w-0">
+    <p class="font-semibold text-sm">${escapeHtml(componentName)}: Invalid Configuration</p>
+    <p class="text-sm opacity-90 mt-0.5">The "${escapeHtml(invalidParam)}" parameter is invalid.</p>
+  </div>
+</div>`;
+}
+
+// libs/uipack/src/validation/wrapper.ts
+function getFirstInvalidPath(error) {
+  const firstError = error.issues[0];
+  if (!firstError || firstError.path.length === 0) {
+    return "options";
+  }
+  return firstError.path.map(String).join(".");
+}
+function validateOptions(options, config) {
+  const result = config.schema.safeParse(options);
+  if (result.success) {
+    return { success: true, data: result.data };
+  }
+  const invalidParam = getFirstInvalidPath(result.error);
+  return {
+    success: false,
+    error: validationErrorBox({
+      componentName: config.componentName,
+      invalidParam
+    })
+  };
+}
+
+// libs/uipack/src/validation/schema-paths.ts
+var import_zod = require("zod");
+function extractSchemaPaths(schema, prefix = "output", options = {}) {
+  const { maxDepth = 10, includeArrayItems = true } = options;
+  const paths = [];
+  const visited = /* @__PURE__ */ new Set();
+  function recurse(currentSchema, currentPath, depth, isOptional, isNullable, isArrayItem) {
+    if (depth > maxDepth) return;
+    const pathKey = `${currentPath}:${depth}`;
+    if (visited.has(pathKey)) return;
+    visited.add(pathKey);
+    const description = currentSchema.description;
+    const innerType = unwrapType(currentSchema);
+    paths.push({
+      path: currentPath,
+      zodType: currentSchema,
+      optional: isOptional,
+      nullable: isNullable,
+      isArrayItem,
+      description
+    });
+    if (innerType instanceof import_zod.z.ZodObject) {
+      const shape = innerType.shape;
+      for (const [key, value] of Object.entries(shape)) {
+        const childSchema = value;
+        const childOptional = isOptional || isOptionalType(childSchema);
+        const childNullable = isNullable || isNullableType(childSchema);
+        recurse(childSchema, `${currentPath}.${key}`, depth + 1, childOptional, childNullable, false);
+      }
+    } else if (innerType instanceof import_zod.z.ZodArray && includeArrayItems) {
+      const itemSchema = innerType.element;
+      recurse(itemSchema, `${currentPath}.[]`, depth + 1, isOptional, isNullable, true);
+    } else if (innerType instanceof import_zod.z.ZodUnion || innerType instanceof import_zod.z.ZodDiscriminatedUnion) {
+      const options2 = "options" in innerType ? innerType.options : [];
+      for (const option of options2) {
+        recurse(option, currentPath, depth, isOptional, isNullable, isArrayItem);
+      }
+    } else if (innerType instanceof import_zod.z.ZodIntersection) {
+      recurse(innerType._def.left, currentPath, depth, isOptional, isNullable, isArrayItem);
+      recurse(innerType._def.right, currentPath, depth, isOptional, isNullable, isArrayItem);
+    } else if (innerType instanceof import_zod.z.ZodRecord) {
+      const valueSchema = innerType._def.valueType;
+      recurse(valueSchema, `${currentPath}.[]`, depth + 1, isOptional, isNullable, true);
+    } else if (innerType instanceof import_zod.z.ZodTuple) {
+      const items = innerType._def.items;
+      items.forEach((item, index) => {
+        recurse(item, `${currentPath}.${index}`, depth + 1, isOptional, isNullable, true);
+      });
+    }
+  }
+  recurse(schema, prefix, 0, false, false, false);
+  const seen = /* @__PURE__ */ new Set();
+  return paths.filter((p) => {
+    if (seen.has(p.path)) return false;
+    seen.add(p.path);
+    return true;
+  });
+}
+function unwrapType(schema) {
+  if (schema instanceof import_zod.z.ZodOptional) {
+    return unwrapType(schema.unwrap());
+  }
+  if (schema instanceof import_zod.z.ZodNullable) {
+    return unwrapType(schema.unwrap());
+  }
+  if (schema instanceof import_zod.z.ZodDefault) {
+    return unwrapType(schema._def.innerType);
+  }
+  if (schema instanceof import_zod.z.ZodCatch && "innerType" in schema._def) {
+    return unwrapType(schema._def.innerType);
+  }
+  return schema;
+}
+function isOptionalType(schema) {
+  if (schema instanceof import_zod.z.ZodOptional) return true;
+  if (schema instanceof import_zod.z.ZodDefault) return true;
+  if (schema instanceof import_zod.z.ZodNullable) return isOptionalType(schema.unwrap());
+  return false;
+}
+function isNullableType(schema) {
+  if (schema instanceof import_zod.z.ZodNullable) return true;
+  if (schema instanceof import_zod.z.ZodOptional) return isNullableType(schema.unwrap());
+  return false;
+}
+function getSchemaPathStrings(schema, prefix = "output") {
+  const paths = extractSchemaPaths(schema, prefix);
+  return new Set(paths.map((p) => p.path));
+}
+function isValidSchemaPath(schema, path) {
+  const prefix = path.split(".")[0];
+  const paths = getSchemaPathStrings(schema, prefix);
+  if (paths.has(path)) return true;
+  const normalizedPath = normalizePath(path);
+  if (paths.has(normalizedPath)) return true;
+  const pathParts = path.split(".");
+  for (let i = pathParts.length - 1; i >= 0; i--) {
+    const part = pathParts[i];
+    if (/^\d+$/.test(part)) {
+      const parentPath = pathParts.slice(0, i).join(".");
+      const wildcardPath = `${parentPath}.[]`;
+      if (paths.has(wildcardPath)) {
+        const restPath = pathParts.slice(i + 1).join(".");
+        if (restPath) {
+          const fullWildcardPath = `${wildcardPath}.${restPath}`;
+          const normalizedFullPath = normalizePath(fullWildcardPath);
+          if (paths.has(normalizedFullPath)) return true;
+        } else {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+function normalizePath(path) {
+  return path.replace(/\.\d+\./g, ".[].").replace(/\.\d+$/g, ".[]").replace(/\[\d+\]/g, ".[]");
+}
+function getTypeAtPath(schema, path) {
+  const prefix = path.split(".")[0];
+  const paths = extractSchemaPaths(schema, prefix);
+  let schemaPath = paths.find((p) => p.path === path);
+  if (!schemaPath) {
+    const normalizedPath = normalizePath(path);
+    schemaPath = paths.find((p) => p.path === normalizedPath);
+  }
+  return schemaPath?.zodType;
+}
+function getPathInfo(schema, path) {
+  const prefix = path.split(".")[0];
+  const paths = extractSchemaPaths(schema, prefix);
+  let schemaPath = paths.find((p) => p.path === path);
+  if (!schemaPath) {
+    const normalizedPath = normalizePath(path);
+    schemaPath = paths.find((p) => p.path === normalizedPath);
+  }
+  return schemaPath;
+}
+function getRootFieldNames(schema) {
+  const unwrapped = unwrapType(schema);
+  if (unwrapped instanceof import_zod.z.ZodObject) {
+    return Object.keys(unwrapped.shape);
+  }
+  return [];
+}
+function getTypeDescription(schema, path) {
+  const zodType = getTypeAtPath(schema, path);
+  if (!zodType) return "unknown";
+  return describeZodType(zodType);
+}
+function describeZodType(schema) {
+  const inner = unwrapType(schema);
+  if (inner instanceof import_zod.z.ZodString) return "string";
+  if (inner instanceof import_zod.z.ZodNumber) return "number";
+  if (inner instanceof import_zod.z.ZodBoolean) return "boolean";
+  if (inner instanceof import_zod.z.ZodDate) return "Date";
+  if (inner instanceof import_zod.z.ZodBigInt) return "bigint";
+  if (inner instanceof import_zod.z.ZodSymbol) return "symbol";
+  if (inner instanceof import_zod.z.ZodUndefined) return "undefined";
+  if (inner instanceof import_zod.z.ZodNull) return "null";
+  if (inner instanceof import_zod.z.ZodVoid) return "void";
+  if (inner instanceof import_zod.z.ZodAny) return "any";
+  if (inner instanceof import_zod.z.ZodUnknown) return "unknown";
+  if (inner instanceof import_zod.z.ZodNever) return "never";
+  if (inner instanceof import_zod.z.ZodLiteral) return `literal(${JSON.stringify(inner.value)})`;
+  if (inner instanceof import_zod.z.ZodEnum) return `enum(${inner.options.join(" | ")})`;
+  if (inner instanceof import_zod.z.ZodArray) return `${describeZodType(inner.element)}[]`;
+  if (inner instanceof import_zod.z.ZodObject) return "object";
+  if (inner instanceof import_zod.z.ZodUnion) return "union";
+  if (inner instanceof import_zod.z.ZodDiscriminatedUnion) return "discriminatedUnion";
+  if (inner instanceof import_zod.z.ZodIntersection) return "intersection";
+  if (inner instanceof import_zod.z.ZodTuple) return "tuple";
+  if (inner instanceof import_zod.z.ZodRecord) return `Record<string, ${describeZodType(inner._def.valueType)}>`;
+  if (inner instanceof import_zod.z.ZodMap) return "Map";
+  if (inner instanceof import_zod.z.ZodSet) return "Set";
+  if (inner instanceof import_zod.z.ZodFunction) return "function";
+  if (inner instanceof import_zod.z.ZodPromise) return "Promise";
+  if (schema instanceof import_zod.z.ZodOptional) {
+    return `${describeZodType(schema.unwrap())}?`;
+  }
+  if (schema instanceof import_zod.z.ZodNullable) {
+    return `${describeZodType(schema.unwrap())} | null`;
+  }
+  return "unknown";
+}
+
+// libs/uipack/src/handlebars/expression-extractor.ts
+var EXPRESSION_REGEX = /\{\{\{?(?!!)(#|\/)?([^}]+?)\}?\}\}/g;
+var PATH_REGEX = /\b(output|input|structuredContent)(\.[a-zA-Z_$][a-zA-Z0-9_$]*|\.\[[^\]]+\])+/g;
+var KEYWORDS = /* @__PURE__ */ new Set(["this", "else", "@index", "@key", "@first", "@last", "@root"]);
+function extractExpressions(template) {
+  const expressions = [];
+  const lines = template.split("\n");
+  const positionMap = buildPositionMap(template);
+  let match;
+  EXPRESSION_REGEX.lastIndex = 0;
+  while ((match = EXPRESSION_REGEX.exec(template)) !== null) {
+    const fullExpression = match[0];
+    const prefix = match[1];
+    const content = match[2].trim();
+    const position = positionMap.get(match.index) ?? { line: 1, column: 1 };
+    let type = "variable";
+    let helperName;
+    if (prefix === "/") {
+      type = "block-close";
+      helperName = content;
+    } else if (prefix === "#") {
+      type = "block";
+      const parts = content.split(/\s+/);
+      helperName = parts[0];
+    } else {
+      const parts = content.split(/\s+/);
+      if (parts.length > 1 && !content.startsWith("(")) {
+        const firstToken = parts[0];
+        if (!firstToken.includes(".") && !KEYWORDS.has(firstToken)) {
+          type = "helper";
+          helperName = firstToken;
+        }
+      }
+    }
+    const paths = extractPathsFromContent(content);
+    for (const path of paths) {
+      expressions.push({
+        path,
+        fullExpression,
+        line: position.line,
+        column: position.column,
+        type,
+        helperName
+      });
+    }
+    if (paths.length === 0 && type === "variable") {
+      const cleanContent = content.trim();
+      if (!KEYWORDS.has(cleanContent) && !cleanContent.includes(" ") && !cleanContent.startsWith("(")) {
+      }
+    }
+  }
+  return expressions;
+}
+function extractPathsFromContent(content) {
+  const paths = [];
+  let match;
+  const regex = new RegExp(PATH_REGEX.source, "g");
+  while ((match = regex.exec(content)) !== null) {
+    paths.push(match[0]);
+  }
+  return paths;
+}
+function buildPositionMap(template) {
+  const map = /* @__PURE__ */ new Map();
+  let line = 1;
+  let column = 1;
+  for (let i = 0; i < template.length; i++) {
+    map.set(i, { line, column });
+    if (template[i] === "\n") {
+      line++;
+      column = 1;
+    } else {
+      column++;
+    }
+  }
+  return map;
+}
+function extractAll(template) {
+  const expressions = extractExpressions(template);
+  const paths = [...new Set(expressions.map((e) => e.path))];
+  return {
+    expressions,
+    paths,
+    outputPaths: paths.filter((p) => p.startsWith("output.")),
+    inputPaths: paths.filter((p) => p.startsWith("input.")),
+    structuredContentPaths: paths.filter((p) => p.startsWith("structuredContent."))
+  };
+}
+function normalizePath2(path) {
+  return path.replace(/\.\d+\./g, ".[].").replace(/\.\d+$/g, ".[]").replace(/\[\d+\]/g, ".[]");
+}
+
+// libs/uipack/src/validation/template-validator.ts
+function validateTemplate(template, outputSchema, options = {}) {
+  const { inputSchema, warnOnOptional = true, suggestSimilar = true, maxSuggestionDistance = 3 } = options;
+  const errors = [];
+  const warnings = [];
+  const extraction = extractAll(template);
+  const expressions = extractExpressions(template);
+  const outputPaths = getSchemaPathStrings(outputSchema, "output");
+  const inputPaths = inputSchema ? getSchemaPathStrings(inputSchema, "input") : /* @__PURE__ */ new Set();
+  const outputPathInfos = extractSchemaPaths(outputSchema, "output");
+  const inputPathInfos = inputSchema ? extractSchemaPaths(inputSchema, "input") : [];
+  const pathInfoMap = /* @__PURE__ */ new Map();
+  for (const info of [...outputPathInfos, ...inputPathInfos]) {
+    pathInfoMap.set(info.path, info);
+  }
+  for (const expr of expressions) {
+    const { path, fullExpression, line, column } = expr;
+    let validPaths;
+    let allPaths;
+    if (path.startsWith("output.")) {
+      validPaths = outputPaths;
+      allPaths = Array.from(outputPaths);
+    } else if (path.startsWith("input.")) {
+      if (!inputSchema) {
+        continue;
+      }
+      validPaths = inputPaths;
+      allPaths = Array.from(inputPaths);
+    } else if (path.startsWith("structuredContent.")) {
+      continue;
+    } else {
+      continue;
+    }
+    const normalizedPath = normalizePath2(path);
+    const isValid = validPaths.has(path) || validPaths.has(normalizedPath);
+    if (!isValid) {
+      const isArrayAccess = checkArrayAccess(path, validPaths);
+      if (!isArrayAccess) {
+        const suggestions = suggestSimilar ? findSimilarPaths(path, allPaths, maxSuggestionDistance) : [];
+        errors.push({
+          type: "missing_field",
+          path,
+          expression: fullExpression,
+          line,
+          column,
+          message: `Field '${getFieldName(path)}' does not exist in ${getSchemaName(path)} schema`,
+          suggestions
+        });
+      }
+    } else {
+      const pathInfo = pathInfoMap.get(path) ?? pathInfoMap.get(normalizedPath);
+      if (pathInfo && warnOnOptional) {
+        if (pathInfo.optional && expr.type === "variable") {
+          const hasGuard = hasConditionalGuard(template, path);
+          if (!hasGuard) {
+            warnings.push({
+              type: "optional_field",
+              path,
+              expression: fullExpression,
+              line,
+              message: `Accessing optional field '${getFieldName(path)}' without {{#if}} guard`
+            });
+          }
+        }
+      }
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    templatePaths: extraction.paths,
+    schemaPaths: [...outputPaths, ...inputPaths]
+  };
+}
+function checkArrayAccess(path, validPaths) {
+  const parts = path.split(".");
+  for (let i = 0; i < parts.length; i++) {
+    if (/^\d+$/.test(parts[i])) {
+      const wildcardParts = [...parts];
+      wildcardParts[i] = "[]";
+      const wildcardPath = wildcardParts.join(".");
+      if (validPaths.has(wildcardPath)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function getFieldName(path) {
+  const parts = path.split(".");
+  return parts[parts.length - 1];
+}
+function getSchemaName(path) {
+  if (path.startsWith("output.")) return "output";
+  if (path.startsWith("input.")) return "input";
+  if (path.startsWith("structuredContent.")) return "structuredContent";
+  return "unknown";
+}
+function hasConditionalGuard(template, path) {
+  const guardPattern = new RegExp(`\\{\\{#if\\s+${escapeRegex(path)}`, "i");
+  return guardPattern.test(template);
+}
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function findSimilarPaths(path, validPaths, maxDistance) {
+  const fieldName = getFieldName(path);
+  const prefix = path.substring(0, path.lastIndexOf(".") + 1);
+  const suggestions = [];
+  for (const validPath of validPaths) {
+    if (!validPath.startsWith(prefix)) continue;
+    const validFieldName = getFieldName(validPath);
+    const distance = levenshteinDistance(fieldName, validFieldName);
+    if (distance <= maxDistance && distance > 0) {
+      suggestions.push({ path: validPath, distance });
+    }
+  }
+  return suggestions.sort((a, b) => a.distance - b.distance).slice(0, 3).map((s) => s.path);
+}
+function levenshteinDistance(a, b) {
+  const matrix = [];
+  for (let i = 0; i <= a.length; i++) {
+    matrix[i] = [i];
+  }
+  for (let j = 0; j <= b.length; j++) {
+    matrix[0][j] = j;
+  }
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      matrix[i][j] = Math.min(
+        matrix[i - 1][j] + 1,
+        // deletion
+        matrix[i][j - 1] + 1,
+        // insertion
+        matrix[i - 1][j - 1] + cost
+        // substitution
+      );
+    }
+  }
+  return matrix[a.length][b.length];
+}
+function formatValidationWarnings(result, toolName) {
+  if (result.valid && result.warnings.length === 0) {
+    return "";
+  }
+  const lines = [];
+  if (result.errors.length > 0) {
+    lines.push(`[FrontMCP] Template validation warnings for tool "${toolName}":`);
+    lines.push("");
+    for (const error of result.errors) {
+      lines.push(`  Line ${error.line}: ${error.expression}`);
+      lines.push(`    ${error.message}`);
+      if (error.suggestions.length > 0) {
+        lines.push(`    Did you mean: ${error.suggestions.join(", ")}?`);
+      }
+      lines.push("");
+    }
+    const outputFields = result.schemaPaths.filter((p) => p.startsWith("output.") && p.split(".").length === 2).map((p) => p.replace("output.", ""));
+    if (outputFields.length > 0) {
+      lines.push(`  Available output fields: ${outputFields.join(", ")}`);
+    }
+  }
+  if (result.warnings.length > 0) {
+    if (lines.length > 0) lines.push("");
+    lines.push(`  Warnings:`);
+    for (const warning of result.warnings) {
+      lines.push(`    Line ${warning.line}: ${warning.message}`);
+    }
+  }
+  return lines.join("\n");
+}
+function logValidationWarnings(result, toolName) {
+  const formatted = formatValidationWarnings(result, toolName);
+  if (formatted) {
+    console.warn(formatted);
+  }
+}
+function assertTemplateValid(template, outputSchema, toolName) {
+  const result = validateTemplate(template, outputSchema);
+  if (!result.valid) {
+    const formatted = formatValidationWarnings(result, toolName);
+    throw new Error(`Template validation failed for tool "${toolName}":
+${formatted}`);
+  }
+}
+function isTemplateValid(template, outputSchema) {
+  const result = validateTemplate(template, outputSchema);
+  return result.valid;
+}
+function getMissingFields(template, outputSchema) {
+  const result = validateTemplate(template, outputSchema);
+  return result.errors.map((e) => e.path);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  assertTemplateValid,
+  extractSchemaPaths,
+  formatValidationWarnings,
+  getMissingFields,
+  getPathInfo,
+  getRootFieldNames,
+  getSchemaPathStrings,
+  getTypeAtPath,
+  getTypeDescription,
+  isTemplateValid,
+  isValidSchemaPath,
+  logValidationWarnings,
+  validateOptions,
+  validateTemplate,
+  validationErrorBox
+});

package/validation/schema-paths.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Schema Path Extractor
+ *
+ * Extracts valid paths from Zod schemas for template validation.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+/**
+ * Information about a path in a schema.
+ */
+export interface SchemaPath {
+    /** The full path (e.g., "output.user.name") */
+    path: string;
+    /** The Zod type at this path */
+    zodType: z.ZodTypeAny;
+    /** Whether this path is optional */
+    optional: boolean;
+    /** Whether this path is nullable */
+    nullable: boolean;
+    /** Whether this is an array item path (contains []) */
+    isArrayItem: boolean;
+    /** Description from .describe() if present */
+    description?: string;
+}
+/**
+ * Options for path extraction.
+ */
+export interface ExtractPathsOptions {
+    /** Maximum depth to recurse (default: 10) */
+    maxDepth?: number;
+    /** Include array item paths with [] notation */
+    includeArrayItems?: boolean;
+}
+/**
+ * Extract all valid paths from a Zod schema.
+ *
+ * @param schema - The Zod schema to extract paths from
+ * @param prefix - Path prefix (default: "output")
+ * @param options - Extraction options
+ * @returns Array of schema paths with metadata
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   temperature: z.number(),
+ *   user: z.object({
+ *     name: z.string(),
+ *     email: z.string().optional(),
+ *   }),
+ * });
+ *
+ * const paths = extractSchemaPaths(schema, 'output');
+ * // [
+ * //   { path: 'output', ... },
+ * //   { path: 'output.temperature', ... },
+ * //   { path: 'output.user', ... },
+ * //   { path: 'output.user.name', ... },
+ * //   { path: 'output.user.email', optional: true, ... },
+ * // ]
+ * ```
+ */
+export declare function extractSchemaPaths(schema: z.ZodTypeAny, prefix?: string, options?: ExtractPathsOptions): SchemaPath[];
+/**
+ * Get just the path strings from a schema.
+ *
+ * @param schema - The Zod schema
+ * @param prefix - Path prefix (default: "output")
+ * @returns Set of valid path strings
+ */
+export declare function getSchemaPathStrings(schema: z.ZodTypeAny, prefix?: string): Set<string>;
+/**
+ * Check if a path exists in a schema.
+ *
+ * @param schema - The Zod schema
+ * @param path - The path to check
+ * @returns true if the path exists
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({ name: z.string() });
+ * isValidSchemaPath(schema, 'output.name'); // true
+ * isValidSchemaPath(schema, 'output.age');  // false
+ * ```
+ */
+export declare function isValidSchemaPath(schema: z.ZodTypeAny, path: string): boolean;
+/**
+ * Get the Zod type at a specific path.
+ *
+ * @param schema - The Zod schema
+ * @param path - The path to look up
+ * @returns The Zod type or undefined if not found
+ */
+export declare function getTypeAtPath(schema: z.ZodTypeAny, path: string): z.ZodTypeAny | undefined;
+/**
+ * Get schema path info at a specific path.
+ *
+ * @param schema - The Zod schema
+ * @param path - The path to look up
+ * @returns SchemaPath info or undefined if not found
+ */
+export declare function getPathInfo(schema: z.ZodTypeAny, path: string): SchemaPath | undefined;
+/**
+ * Get all field names at the root level of a schema.
+ *
+ * @param schema - The Zod schema (should be ZodObject)
+ * @returns Array of field names
+ */
+export declare function getRootFieldNames(schema: z.ZodTypeAny): string[];
+/**
+ * Get a human-readable type description for a path.
+ *
+ * @param schema - The Zod schema
+ * @param path - The path to describe
+ * @returns Human-readable type string
+ */
+export declare function getTypeDescription(schema: z.ZodTypeAny, path: string): string;
+//# sourceMappingURL=schema-paths.d.ts.map