veryfront 0.1.502 → 0.1.503

package/src/src/data/schemas/data.schema.ts

@@ -1,47 +1,70 @@
-import { z } from "zod";
+import { defineSchema } from "../../schemas/index.js";
+import type { InferSchema } from "../../extensions/schema/index.js";
 
 /** Context passed to data fetching functions */
-export const DataContextSchema = z.object({
-  params: z.record(z.string(), z.union([z.string(), z.array(z.string())])),
-  query: z.instanceof(URLSearchParams),
-  request: z.instanceof(Request),
-  url: z.instanceof(URL),
-});
-
-export const RedirectSchema = z.object({
-  destination: z.string(),
-  permanent: z.boolean().optional(),
-});
+export const getDataContextSchema = defineSchema((v) =>
+  v.object({
+    params: v.record(v.string(), v.union([v.string(), v.array(v.string())])),
+    query: v.instanceof(URLSearchParams),
+    request: v.instanceof(Request),
+    url: v.instanceof(URL),
+  })
+);
+
+export const getRedirectSchema = defineSchema((v) =>
+  v.object({
+    destination: v.string(),
+    permanent: v.boolean().optional(),
+  })
+);
 
 /** Result returned from data fetching functions */
-export const DataResultSchema = z.object({
-  props: z.unknown().optional(),
-  redirect: RedirectSchema.optional(),
-  notFound: z.boolean().optional(),
-  revalidate: z.union([z.number(), z.literal(false)]).optional(),
-});
-
-export const StaticPathEntrySchema = z.object({
-  params: z.record(z.string(), z.union([z.string(), z.array(z.string())])),
-});
-
-export const StaticPathsResultSchema = z.object({
-  paths: z.array(StaticPathEntrySchema),
-  fallback: z.union([z.boolean(), z.literal("blocking")]),
-});
-
-export const CacheEntrySchema = z.object({
-  data: DataResultSchema,
-  timestamp: z.number(),
-  revalidate: z.union([z.number(), z.literal(false)]).optional(),
-});
+export const getDataResultSchema = defineSchema((v) =>
+  v.object({
+    props: v.unknown().optional(),
+    redirect: getRedirectSchema().optional(),
+    notFound: v.boolean().optional(),
+    revalidate: v.union([v.number(), v.literal(false)]).optional(),
+  })
+);
+
+export const getStaticPathEntrySchema = defineSchema((v) =>
+  v.object({
+    params: v.record(v.string(), v.union([v.string(), v.array(v.string())])),
+  })
+);
+
+export const getStaticPathsResultSchema = defineSchema((v) =>
+  v.object({
+    paths: v.array(getStaticPathEntrySchema()),
+    fallback: v.union([v.boolean(), v.literal("blocking")]),
+  })
+);
+
+export const getCacheEntrySchema = defineSchema((v) =>
+  v.object({
+    data: getDataResultSchema(),
+    timestamp: v.number(),
+    revalidate: v.union([v.number(), v.literal(false)]).optional(),
+  })
+);
 
 // Inferred types
-export type DataContext = z.infer<typeof DataContextSchema>;
-export type Redirect = z.infer<typeof RedirectSchema>;
-export type DataResult<T = unknown> = z.infer<typeof DataResultSchema> & { props?: T };
-export type StaticPathEntry = z.infer<typeof StaticPathEntrySchema>;
-export type StaticPathsResult = z.infer<typeof StaticPathsResultSchema>;
-export type CacheEntry<T = unknown> = z.infer<typeof CacheEntrySchema> & {
+export type DataContext = InferSchema<ReturnType<typeof getDataContextSchema>>;
+export type Redirect = InferSchema<ReturnType<typeof getRedirectSchema>>;
+export type DataResult<T = unknown> = InferSchema<ReturnType<typeof getDataResultSchema>> & {
+  props?: T;
+};
+export type StaticPathEntry = InferSchema<ReturnType<typeof getStaticPathEntrySchema>>;
+export type StaticPathsResult = InferSchema<ReturnType<typeof getStaticPathsResultSchema>>;
+export type CacheEntry<T = unknown> = InferSchema<ReturnType<typeof getCacheEntrySchema>> & {
   data: DataResult<T>;
 };
+
+// Backward compat aliases
+export const DataContextSchema = getDataContextSchema();
+export const RedirectSchema = getRedirectSchema();
+export const DataResultSchema = getDataResultSchema();
+export const StaticPathEntrySchema = getStaticPathEntrySchema();
+export const StaticPathsResultSchema = getStaticPathsResultSchema();
+export const CacheEntrySchema = getCacheEntrySchema();

package/src/src/extensions/builtin-extensions.ts

@@ -10,6 +10,7 @@ import extBabel from "../../extensions/ext-parser-babel/src/index.js";
 import extMdx from "../../extensions/ext-transform-mdx/src/index.js";
 import extTailwind from "../../extensions/ext-css-tailwind/src/index.js";
 import extNodeCompat from "../../extensions/ext-node-compatibility/src/index.js";
+import extZod from "../../extensions/ext-zod/src/index.js";
 
 type BuiltinLLMProviderDefinition = {
   extensionName: string;
@@ -94,6 +95,14 @@ function createBuiltinLLMProviderExtension(
 
 export function createBuiltinExtensions(): ResolvedExtension[] {
   return [
+    // ext-zod registers SchemaValidator. Listed FIRST so any subsequent
+    // builtin whose setup() builds schemas via defineSchema() finds the
+    // contract resolved.
+    {
+      source: "builtin",
+      origin: "veryfront/ext-zod",
+      extension: extZod(),
+    },
     {
       source: "builtin",
       origin: "veryfront/ext-bundler-esbuild",

package/src/src/extensions/schema/index.ts

@@ -8,8 +8,11 @@
 import "../../../_dnt.polyfills.js";
 
 export type {
+  InferInput,
   InferSchema,
   InferShape,
+  JsonSchema,
+  RefinementCtx,
   SchemaFactory,
   ValidationResult,
 } from "./schema-validator.js";

package/src/src/extensions/schema/json-schema.ts

@@ -0,0 +1,23 @@
+/**
+ * Minimal JSON Schema type used by the `SchemaValidator` contract for
+ * `toJsonSchema()`. Kept in the extensions/schema category so the contract
+ * can reference it without depending on any non-leaf module.
+ *
+ * @module extensions/schema/json-schema
+ */
+
+export type JsonSchema = {
+  type?: "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
+  description?: string;
+  enum?: unknown[];
+  const?: unknown;
+  default?: unknown;
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+  items?: JsonSchema;
+  additionalProperties?: boolean | JsonSchema;
+  anyOf?: JsonSchema[];
+  prefixItems?: JsonSchema[];
+  minItems?: number;
+  maxItems?: number;
+};

package/src/src/extensions/schema/schema-validator.ts

@@ -11,6 +11,8 @@
  * @module extensions/schema/schema-validator
  */
 
+import type { JsonSchema } from "./json-schema.js";
+
 /**
  * An opaque schema definition that validates and infers type `T`.
  *
@@ -25,20 +27,38 @@ export interface Schema<T = unknown> {
   optional(): Schema<T | undefined>;
   nullable(): Schema<T | null>;
   nullish(): Schema<T | null | undefined>;
-  default(value: T | (() => T)): Schema<T>;
+  default(
+    value: Exclude<T, undefined> | (() => Exclude<T, undefined>),
+  ): Schema<Exclude<T, undefined>>;
   describe(description: string): Schema<T>;
   refine(check: (value: T) => boolean, message?: string | { message?: string }): Schema<T>;
+  /**
+   * Multi-issue refinement. The callback receives the parsed value and a
+   * `RefinementCtx` it can use to emit one or more issues via `addIssue`.
+   * Mirrors zod's `.superRefine`.
+   */
+  superRefine(check: (value: T, ctx: RefinementCtx) => void): Schema<T>;
   transform<U>(fn: (value: T) => U): Schema<U>;
 
   // Object-level chainables (no-op / type-preserving on non-object schemas;
   // implementations should only call these on object schemas).
   strict(): Schema<T>;
-  passthrough(): Schema<T>;
+  /**
+   * Strip unknown keys from object inputs (zod's default behavior). Exposed
+   * for parity with `.strict()` / `.passthrough()` so call sites can be
+   * explicit about their intent.
+   */
+  strip(): Schema<T>;
+  passthrough(): Schema<T & Record<string, unknown>>;
   partial(): Schema<Partial<T>>;
   extend<U extends Record<string, Schema<unknown>>>(
     shape: U,
   ): Schema<T & { [K in keyof U]: InferSchema<U[K]> }>;
   merge<U>(other: Schema<U>): Schema<T & U>;
+  /** Drop the listed keys from an object schema. Mirrors zod's `.omit({k: true})`. */
+  omit<K extends keyof T>(keys: { [P in K]?: true }): Schema<Omit<T, K>>;
+  /** Keep only the listed keys from an object schema. Mirrors zod's `.pick({k: true})`. */
+  pick<K extends keyof T>(keys: { [P in K]?: true }): Schema<Pick<T, K>>;
 
   // String-level chainables
   min(value: number, message?: string): Schema<T>;
@@ -52,18 +72,52 @@ export interface Schema<T = unknown> {
   uuid(message?: string): Schema<T>;
   datetime(message?: string): Schema<T>;
 
+  /**
+   * Feed parsed output into another schema for further validation/refinement.
+   * Mirrors zod's `.pipe(otherSchema)`.
+   */
+  pipe<U>(next: Schema<U>): Schema<U>;
+
   // Validation
   parse(data: unknown): T;
   safeParse(data: unknown): ValidationResult<T>;
 }
 
+/**
+ * Context passed to a `superRefine` callback. Provides `addIssue` to emit
+ * one or more validation issues and `path` to locate the current value.
+ *
+ * Mirrors the subset of zod's `RefinementCtx` we actually use.
+ */
+export interface RefinementCtx {
+  /** Emit a validation issue against the parsed value. */
+  addIssue(issue: { code?: string; message: string; path?: (string | number)[] }): void;
+  /** Path to the current value within its parent — used when emitting issues. */
+  readonly path: (string | number)[];
+}
+
 /** Extracts the inferred output type `T` from a `Schema<T>`. */
 export type InferSchema<S> = S extends Schema<infer T> ? T : never;
 
-/** Maps a raw object shape to its inferred object type. */
-export type InferShape<S extends Record<string, Schema<unknown>>> = {
-  [K in keyof S]: InferSchema<S[K]>;
-};
+/**
+ * Extracts the inferred *input* type from a `Schema<T>`.
+ *
+ * Today the contract DSL does not formally model input/output divergence
+ * (zod's `.transform()` is the canonical case where they differ), so this
+ * is an alias of `InferSchema`. Reserved as a separate type for forward
+ * compatibility — callers migrating from `z.input<typeof S>` should use
+ * this name.
+ */
+export type InferInput<S> = InferSchema<S>;
+
+/** Maps a raw object shape to its inferred object type, preserving optionality. */
+export type InferShape<S extends Record<string, Schema<unknown>>> =
+  & {
+    [K in keyof S as undefined extends InferSchema<S[K]> ? never : K]: InferSchema<S[K]>;
+  }
+  & {
+    [K in keyof S as undefined extends InferSchema<S[K]> ? K : never]?: InferSchema<S[K]>;
+  };
 
 /** A single validation issue with location context. */
 export interface ValidationIssue {
@@ -120,12 +174,17 @@ export interface SchemaValidator {
   date(): Schema<Date>;
   null(): Schema<null>;
   unknown(): Schema<unknown>;
+  bigint(): Schema<bigint>;
   // deno-lint-ignore no-explicit-any -- `any` constructor intentionally mirrors zod
   any(): Schema<any>;
+  function(): Schema<(...args: unknown[]) => unknown>;
 
   // Composite constructors
   object<S extends Record<string, Schema<unknown>>>(shape: S): Schema<InferShape<S>>;
   array<T>(element: Schema<T>): Schema<T[]>;
+  tuple<T extends readonly Schema<unknown>[]>(
+    items: T,
+  ): Schema<{ [K in keyof T]: T[K] extends Schema<infer U> ? U : never }>;
   record<K extends string | number | symbol, V>(
     keys: Schema<K>,
     values: Schema<V>,
@@ -143,6 +202,25 @@ export interface SchemaValidator {
   literal<T extends string | number | boolean | null>(value: T): Schema<T>;
   enum<T extends readonly [string, ...string[]]>(values: T): Schema<T[number]>;
 
+  /**
+   * Defer schema construction — used for recursive shapes. The thunk is
+   * called on first access; the result is cached. Mirrors `z.lazy`.
+   */
+  lazy<T>(factory: () => Schema<T>): Schema<T>;
+
+  /**
+   * Validates that input is an instance of the given constructor. Mirrors
+   * `z.instanceof`.
+   */
+  instanceof<T>(ctor: new (...args: never[]) => T): Schema<T>;
+
+  /**
+   * Loosely-typed escape hatch: accept input when `check` returns `true`.
+   * The runtime contract is the predicate; the type parameter `T` is purely
+   * structural and is trusted from the call site. Mirrors `z.custom<T>`.
+   */
+  custom<T>(check?: (value: unknown) => boolean, message?: string): Schema<T>;
+
   /** Coercing constructors — accept any input and coerce to the target. */
   coerce: SchemaValidatorCoerce;
 
@@ -152,7 +230,28 @@ export interface SchemaValidator {
    * earlier revisions of this contract.
    */
   validate<T>(schema: Schema<T>, data: unknown): ValidationResult<T>;
+
+  /**
+   * Convert an opaque `Schema<T>` to a JSON Schema document.
+   *
+   * Used by the tool/MCP layer to expose tool input schemas to AI providers
+   * and MCP clients. Implementations unwrap the contract `Schema<T>` back to
+   * their native validator (e.g. zod) and emit a JSON Schema representation.
+   *
+   * Returns a permissive `{type: "object"}` for kinds the implementation
+   * cannot represent.
+   */
+  toJsonSchema(schema: Schema<unknown>): JsonSchema;
+
+  /**
+   * Returns `true` when the schema permits `undefined` (i.e. was constructed
+   * via `.optional()`/`.nullish()`). Used by tool input-schema introspection
+   * to mark JSON Schema properties as not required.
+   */
+  isOptional(schema: Schema<unknown>): boolean;
 }
 
+export type { JsonSchema };
+
 /** Factory type accepted by `defineSchema`. */
 export type SchemaFactory<T> = (v: SchemaValidator) => Schema<T>;

package/src/src/html/html-shell-generator.ts

@@ -165,7 +165,7 @@ async function generateHTMLShellPartsImpl(
       ? getProjectCSS(projectSlug, stylesheetContent, candidates, {
         minify: true,
         environment: options.environment,
-        buildMode: options.mode,
+        buildMode: options.mode as "development" | "production",
       })
       : Promise.resolve(null));
 

package/src/src/html/hydration-script-builder/hydration-data-generator.ts

@@ -61,10 +61,10 @@ export function generateHydrationData(
     pagePath: options.pagePath
       ? toProjectRelativePath(options.pagePath, options.projectDir)
       : undefined,
-    pageType: options.pageType || inferPageType(options.pagePath),
+    pageType: (options.pageType || inferPageType(options.pagePath)) as any,
     clientModuleStrategy: determineClientModuleStrategy({
       isLocalProject: options.isLocalProject,
-      environment: options.environment,
+      environment: options.environment as any,
     }),
     frontmatter: options.frontmatter,
     layoutProps: options.layoutProps,

package/src/src/html/schemas/html.schema.ts

@@ -1,72 +1,88 @@
-import { z } from "zod";
+import { defineSchema } from "../../schemas/index.js";
+import type { InferSchema } from "../../extensions/schema/index.js";
 
-export const colorSchemeSchema = z.enum(["light", "dark"]);
+export const getColorSchemeSchema = defineSchema((v) => v.enum(["light", "dark"]));
 
-export const environmentSchema = z.enum(["preview", "production"]);
+export const getEnvironmentSchema = defineSchema((v) => v.enum(["preview", "production"]));
 
-export const pageTypeSchema = z.enum(["mdx", "md", "tsx", "jsx", "ts", "js"]);
-export const clientModuleStrategySchema = z.enum(["fs", "rsc-module"]);
+export const getPageTypeSchema = defineSchema((v) =>
+  v.enum(["mdx", "md", "tsx", "jsx", "ts", "js"])
+);
+export const getClientModuleStrategySchema = defineSchema((v) => v.enum(["fs", "rsc-module"]));
 
-export const HTMLGenerationOptionsSchema = z.object({
-  mode: z.enum(["development", "production"]),
-  config: z.any(), // VeryfrontConfig is complex, use any
-  importMap: z.record(z.string(), z.string()).optional(),
-  nestedLayouts: z
-    .array(
-      z.object({
-        kind: z.string(),
-        path: z.string().optional(),
-        componentPath: z.string().optional(),
-      }),
-    )
-    .optional(),
-  appPath: z.string().optional(),
-  pagePath: z.string().optional(),
-  pageType: pageTypeSchema.optional(),
-  nonce: z.string().optional(),
-  projectDir: z.string().optional(),
-  globalCSS: z.string().optional(),
-  frontmatter: z.record(z.string(), z.unknown()).optional(),
-  layoutProps: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
-  studioEmbed: z.boolean().optional(),
-  projectId: z.string().optional(),
-  projectSlug: z.string().optional(),
-  pageId: z.string().optional(),
-  sourceHash: z.string().optional(),
-  colorScheme: colorSchemeSchema.optional(),
-  colorSchemeFromParam: z.boolean().optional(),
-  colorSchemeFromHeader: z.boolean().optional(),
-  environment: environmentSchema.optional(),
-  headings: z
-    .array(
-      z.object({
-        id: z.string(),
-        text: z.string(),
-        level: z.number().int().positive(),
-      }),
-    )
-    .optional(),
-  projectClasses: z.set(z.string()).optional(),
-  isLocalProject: z.boolean().optional(),
-  noHmr: z.boolean().optional(),
-  forceProductionScripts: z.boolean().optional(),
-});
+export const getHTMLGenerationOptionsSchema = defineSchema((v) =>
+  v.object({
+    mode: v.enum(["development", "production"]),
+    // deno-lint-ignore no-explicit-any -- VeryfrontConfig is complex, use any
+    config: v.any(), // VeryfrontConfig is complex, use any
+    importMap: v.record(v.string(), v.string()).optional(),
+    nestedLayouts: v
+      .array(
+        v.object({
+          kind: v.string(),
+          path: v.string().optional(),
+          componentPath: v.string().optional(),
+        }),
+      )
+      .optional(),
+    appPath: v.string().optional(),
+    pagePath: v.string().optional(),
+    pageType: getPageTypeSchema().optional(),
+    nonce: v.string().optional(),
+    projectDir: v.string().optional(),
+    globalCSS: v.string().optional(),
+    frontmatter: v.record(v.string(), v.unknown()).optional(),
+    layoutProps: v.record(v.string(), v.record(v.string(), v.unknown())).optional(),
+    studioEmbed: v.boolean().optional(),
+    projectId: v.string().optional(),
+    projectSlug: v.string().optional(),
+    pageId: v.string().optional(),
+    sourceHash: v.string().optional(),
+    colorScheme: getColorSchemeSchema().optional(),
+    colorSchemeFromParam: v.boolean().optional(),
+    colorSchemeFromHeader: v.boolean().optional(),
+    environment: getEnvironmentSchema().optional(),
+    headings: v
+      .array(
+        v.object({
+          id: v.string(),
+          text: v.string(),
+          level: v.number().int().positive(),
+        }),
+      )
+      .optional(),
+    projectClasses: v.custom<Set<string>>((val) => val instanceof Set).optional(),
+    isLocalProject: v.boolean().optional(),
+    noHmr: v.boolean().optional(),
+    forceProductionScripts: v.boolean().optional(),
+  })
+);
 
-export const HydrationDataSchema = z.object({
-  slug: z.string(),
-  props: z.record(z.string(), z.unknown()),
-  params: z.record(z.string(), z.union([z.string(), z.array(z.string())])),
-  layouts: z.array(
-    z.object({
-      kind: z.string(),
-      path: z.string().optional(),
-    }),
-  ),
-  appPath: z.string().optional(),
-  pagePath: z.string().optional(),
-  clientModuleStrategy: clientModuleStrategySchema.optional(),
-});
+export const getHydrationDataSchema = defineSchema((v) =>
+  v.object({
+    slug: v.string(),
+    props: v.record(v.string(), v.unknown()),
+    params: v.record(v.string(), v.union([v.string(), v.array(v.string())])),
+    layouts: v.array(
+      v.object({
+        kind: v.string(),
+        path: v.string().optional(),
+      }),
+    ),
+    appPath: v.string().optional(),
+    pagePath: v.string().optional(),
+    clientModuleStrategy: getClientModuleStrategySchema().optional(),
+  })
+);
 
 // Inferred types
-export type HTMLGenerationOptions = z.infer<typeof HTMLGenerationOptionsSchema>;
-export type HydrationData = z.infer<typeof HydrationDataSchema>;
+export type HTMLGenerationOptions = InferSchema<ReturnType<typeof getHTMLGenerationOptionsSchema>>;
+export type HydrationData = InferSchema<ReturnType<typeof getHydrationDataSchema>>;
+
+// Backward compat aliases
+export const colorSchemeSchema = getColorSchemeSchema();
+export const environmentSchema = getEnvironmentSchema();
+export const pageTypeSchema = getPageTypeSchema();
+export const clientModuleStrategySchema = getClientModuleStrategySchema();
+export const HTMLGenerationOptionsSchema = getHTMLGenerationOptionsSchema();
+export const HydrationDataSchema = getHydrationDataSchema();

package/src/src/html/utils.ts

@@ -289,7 +289,10 @@ export async function buildImportMapJson(
   if (mode === "self-hosted") {
     imports = getSelfHostedImportMap(versions);
   } else {
-    imports = getCdnImportMap(versions, config?.client?.cdn?.provider ?? "esm.sh");
+    imports = getCdnImportMap(
+      versions,
+      (config?.client?.cdn?.provider ?? "esm.sh") as CdnProvider,
+    );
   }
 
   imports["@/"] = "/_vf_modules/";