@ecopages/core 0.2.0-beta.8 → 0.2.0-rc.0

package/src/services/validation/schema-validation-service.js

@@ -1,101 +1,162 @@
-class SchemaValidationService {
-  /**
-   * Validates request data against provided schemas.
-   *
-   * Validates body, query parameters, and headers against their respective schemas.
-   * All validations are performed, and errors are aggregated from all sources.
-   *
-   * @param source - The data to validate (body, query, headers)
-   * @param schemas - The Standard Schema validators for each source
-   * @returns Validation result with validated data or aggregated errors
-   *
-   * @example
-   * ```typescript
-   * const result = await service.validateRequest(
-   *   { body: { name: 'John', age: 30 } },
-   *   { body: z.object({ name: z.string(), age: z.number() }) }
-   * );
-   *
-   * if (result.success) {
-   *   const validated = result.data.body;
-   * } else {
-   *   console.error(result.errors);
-   * }
-   * ```
-   */
-  async validateRequest(source, schemas) {
-    const validated = {};
-    const allErrors = [];
-    if (schemas.body && source.body !== void 0) {
-      const result = await this.validateWithSchema(schemas.body, source.body);
-      if (!result.success) {
-        allErrors.push(...result.errors || []);
-      } else {
-        validated.body = result.data;
-      }
+import { SchemaError, validateStandardSchema } from './validate-standard-schema.js';
+/**
+ * Service for validating request data using Standard Schema compliant validators.
+ *
+ * This service provides a unified interface for validating HTTP request data (body, query parameters, headers)
+ * using any validation library that implements the Standard Schema specification.
+ *
+ * @example Using with Zod
+ * ```typescript
+ * import { z } from 'zod';
+ * import { SchemaValidationService } from './schema-validation-service.js';
+ *
+ * const service = new SchemaValidationService();
+ * const result = await service.validateRequest(
+ *   { body: { title: 'Hello', count: 42 } },
+ *   { body: z.object({ title: z.string(), count: z.number() }) }
+ * );
+ *
+ * if (result.success) {
+ *   console.log(result.data.body);
+ * }
+ * ```
+ *
+ * @example Using with Valibot
+ * ```typescript
+ * import * as v from 'valibot';
+ *
+ * const result = await service.validateRequest(
+ *   { query: { page: '1' } },
+ *   { query: v.object({ page: v.string() }) }
+ * );
+ * ```
+ *
+ * @example Using with ArkType
+ * ```typescript
+ * import { type } from 'arktype';
+ *
+ * const result = await service.validateRequest(
+ *   { headers: { 'authorization': 'Bearer token' } },
+ *   { headers: type({ authorization: 'string' }) }
+ * );
+ * ```
+ *
+ * @example Multiple sources
+ * ```typescript
+ * const result = await service.validateRequest(
+ *   {
+ *     body: { title: 'Post' },
+ *     query: { format: 'json' },
+ *     headers: { 'content-type': 'application/json' }
+ *   },
+ *   {
+ *     body: z.object({ title: z.string() }),
+ *     query: v.object({ format: v.string() }),
+ *     headers: type({ 'content-type': 'string' })
+ *   }
+ * );
+ * ```
+ *
+ * Supported libraries: Zod, Valibot, ArkType, Effect Schema (with standardSchemaV1 wrapper)
+ */
+export class SchemaValidationService {
+    /**
+     * Validates request data against provided schemas.
+     *
+     * Validates body, query parameters, and headers against their respective schemas.
+     * All validations are performed, and errors are aggregated from all sources.
+     *
+     * @param source - The data to validate (body, query, headers)
+     * @param schemas - The Standard Schema validators for each source
+     * @returns Validation result with validated data or aggregated errors
+     *
+     * @example
+     * ```typescript
+     * const result = await service.validateRequest(
+     *   { body: { name: 'John', age: 30 } },
+     *   { body: z.object({ name: z.string(), age: z.number() }) }
+     * );
+     *
+     * if (result.success) {
+     *   const validated = result.data.body;
+     * } else {
+     *   console.error(result.errors);
+     * }
+     * ```
+     */
+    async validateRequest(source, schemas) {
+        const validated = {};
+        const allErrors = [];
+        if (schemas.body && source.body !== undefined) {
+            const result = await this.validateWithSchema(schemas.body, source.body);
+            if (!result.success) {
+                allErrors.push(...(result.errors || []));
+            }
+            else {
+                validated.body = result.data;
+            }
+        }
+        if (schemas.query && source.query) {
+            const result = await this.validateWithSchema(schemas.query, source.query);
+            if (!result.success) {
+                allErrors.push(...(result.errors || []));
+            }
+            else {
+                validated.query = result.data;
+            }
+        }
+        if (schemas.headers && source.headers) {
+            const result = await this.validateWithSchema(schemas.headers, source.headers);
+            if (!result.success) {
+                allErrors.push(...(result.errors || []));
+            }
+            else {
+                validated.headers = result.data;
+            }
+        }
+        if (schemas.params && source.params) {
+            const result = await this.validateWithSchema(schemas.params, source.params);
+            if (!result.success) {
+                allErrors.push(...(result.errors || []));
+            }
+            else {
+                validated.params = result.data;
+            }
+        }
+        if (allErrors.length > 0) {
+            return { success: false, errors: allErrors };
+        }
+        return { success: true, data: validated };
     }
-    if (schemas.query && source.query) {
-      const result = await this.validateWithSchema(schemas.query, source.query);
-      if (!result.success) {
-        allErrors.push(...result.errors || []);
-      } else {
-        validated.query = result.data;
-      }
-    }
-    if (schemas.headers && source.headers) {
-      const result = await this.validateWithSchema(schemas.headers, source.headers);
-      if (!result.success) {
-        allErrors.push(...result.errors || []);
-      } else {
-        validated.headers = result.data;
-      }
-    }
-    if (schemas.params && source.params) {
-      const result = await this.validateWithSchema(schemas.params, source.params);
-      if (!result.success) {
-        allErrors.push(...result.errors || []);
-      } else {
-        validated.params = result.data;
-      }
-    }
-    if (allErrors.length > 0) {
-      return { success: false, errors: allErrors };
-    }
-    return { success: true, data: validated };
-  }
-  /**
-   * Validates a single value against a Standard Schema.
-   *
-   * @param schema - The Standard Schema validator
-   * @param data - The data to validate
-   * @returns Validation result with validated data or errors
-   */
-  async validateWithSchema(schema, data) {
-    try {
-      const resultOrPromise = schema["~standard"].validate(data);
-      const result = resultOrPromise instanceof Promise ? await resultOrPromise : resultOrPromise;
-      if (result.issues) {
+    /**
+     * Validates a single value against a Standard Schema.
+     */
+    mapSchemaIssue(issue) {
         return {
-          success: false,
-          errors: result.issues.map((issue) => ({
             message: issue.message,
-            path: issue.path?.map((p) => typeof p === "object" && "key" in p ? p.key : p)
-          }))
+            path: issue.path?.map((p) => (typeof p === 'object' && 'key' in p ? p.key : p)),
         };
-      }
-      return { success: true, data: result.value };
-    } catch (error) {
-      return {
-        success: false,
-        errors: [
-          {
-            message: error instanceof Error ? error.message : "Validation failed"
-          }
-        ]
-      };
     }
-  }
+    async validateWithSchema(schema, data) {
+        try {
+            const value = await validateStandardSchema(schema, data);
+            return { success: true, data: value };
+        }
+        catch (error) {
+            if (error instanceof SchemaError) {
+                return {
+                    success: false,
+                    errors: error.issues.map((issue) => this.mapSchemaIssue(issue)),
+                };
+            }
+            return {
+                success: false,
+                errors: [
+                    {
+                        message: error instanceof Error ? error.message : 'Validation failed',
+                    },
+                ],
+            };
+        }
+    }
 }
-export {
-  SchemaValidationService
-};

package/src/services/validation/standard-schema.types.d.ts

@@ -1,65 +1,12 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
 /**
- * Standard Schema interface for universal validation.
- * Compatible with Zod, Valibot, ArkType, Effect Schema, and other validation libraries.
- *
+ * Ecopages aliases for the official Standard Schema V1 types.
  * @see https://standardschema.dev
- *
- * @example Using with Zod
- * ```typescript
- * import { z } from 'zod';
- *
- * const bodySchema = z.object({
- *   title: z.string().min(1),
- *   content: z.string()
- * });
- *
- * app.post('/posts', async (ctx) => {
- *   const { title, content } = ctx.body;
- *   return ctx.json({ id: 1, title, content });
- * }, {
- *   schema: { body: bodySchema }
- * });
- * ```
  */
-export interface StandardSchema<Input = unknown, Output = Input> {
-    readonly '~standard': {
-        readonly version: 1;
-        readonly vendor: string;
-        readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
-        readonly types?: {
-            readonly input: Input;
-            readonly output: Output;
-        };
-    };
-}
-/**
- * Result of Standard Schema validation.
- */
-export type StandardSchemaResult<Output> = StandardSchemaSuccessResult<Output> | StandardSchemaFailureResult;
-/**
- * Successful validation result.
- */
-export interface StandardSchemaSuccessResult<Output> {
-    readonly value: Output;
-    readonly issues?: undefined;
-}
-/**
- * Failed validation result.
- */
-export interface StandardSchemaFailureResult {
-    readonly value?: undefined;
-    readonly issues: ReadonlyArray<StandardSchemaIssue>;
-}
-/**
- * Validation issue details.
- */
-export interface StandardSchemaIssue {
-    readonly message: string;
-    readonly path?: ReadonlyArray<PropertyKey | {
-        key: PropertyKey;
-    }>;
-}
-/**
- * Infers the output type from a Standard Schema.
- */
-export type InferOutput<T extends StandardSchema> = T extends StandardSchema<any, infer O> ? O : never;
+export type StandardSchema<Input = unknown, Output = Input> = StandardSchemaV1<Input, Output>;
+export type StandardSchemaResult<Output> = StandardSchemaV1.Result<Output>;
+export type StandardSchemaSuccessResult<Output> = StandardSchemaV1.SuccessResult<Output>;
+export type StandardSchemaFailureResult = StandardSchemaV1.FailureResult;
+export type StandardSchemaIssue = StandardSchemaV1.Issue;
+export type InferOutput<T extends StandardSchemaV1> = StandardSchemaV1.InferOutput<T>;
+export type { StandardSchemaV1 } from '@standard-schema/spec';

package/src/services/validation/standard-schema.types.js

@@ -0,0 +1 @@
+export {};

package/src/services/validation/validate-standard-schema.d.ts

@@ -0,0 +1,7 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+export { SchemaError } from '@standard-schema/utils';
+/**
+ * Validates a value with any Standard Schema-compliant validator.
+ * Throws {@link SchemaError} when validation fails.
+ */
+export declare function validateStandardSchema<T>(schema: StandardSchemaV1<unknown, T>, value: unknown): Promise<T>;

package/src/services/validation/validate-standard-schema.js

@@ -0,0 +1,14 @@
+import { SchemaError } from '@standard-schema/utils';
+export { SchemaError } from '@standard-schema/utils';
+/**
+ * Validates a value with any Standard Schema-compliant validator.
+ * Throws {@link SchemaError} when validation fails.
+ */
+export async function validateStandardSchema(schema, value) {
+    const resultOrPromise = schema['~standard'].validate(value);
+    const result = resultOrPromise instanceof Promise ? await resultOrPromise : resultOrPromise;
+    if (result.issues) {
+        throw new SchemaError(result.issues);
+    }
+    return result.value;
+}

package/src/static-site-generator/README.md

@@ -29,11 +29,13 @@ It should not invent a parallel rendering stack just for build mode.
 
 | File                           | Role                                                                         |
 | ------------------------------ | ---------------------------------------------------------------------------- |
-| `static-site-generator.ts`     | Route enumeration, HTML artifact writes, integration export hooks            |
+| `static-site-generator.ts`     | Route enumeration, HTML artifact writes, integration export hooks, sitemap   |
 | `static-export-context.ts`     | Hook context type for `beforeStaticExport` / `afterStaticExport`             |
+| `sitemap.ts`                   | Pure sitemap.xml renderer                                                    |
+| `sitemap-routes.ts`            | Sitemap location assembly (`exclude`, `extraUrls`, dedupe)                   |
 | `static-build-invalidation.ts` | `dist/` reset policy, production cache clearing, static-render cache context |
 
-Build-input fingerprinting (`hashAppConfigFile`, `createBuildInputsFingerprint`) lives in `packages/core/src/build/build-input-fingerprint.ts` and is shared with server-entry and unified-graph caches.
+Build-input fingerprinting (`hashAppConfigFile`, `createBuildInputsFingerprint`) lives in `packages/core/src/build/cache/build-input-fingerprint.ts` and is shared with server-entry and unified-graph caches.
 
 ## Incremental static export
 
@@ -56,4 +58,10 @@ Integrations may implement:
 - `beforeStaticExport(context)` — runs after unified-graph prebuild, before page rendering
 - `afterStaticExport(context)` — runs in a `finally` block after generation completes
 
+When `appConfig.sitemap.enabled` is true, `sitemap.xml` is written **after** `afterStaticExport` so integration-generated URLs can be listed via `extraUrls`.
+
+Sitemap eligibility is decided during successful page export (`activeStaticPathnames` plus `robots.index !== false`, fail-closed on metadata errors). `resolveSitemapLocations` then applies `exclude` and appends `extraUrls`.
+
+`StaticExportContext.routes` is the unfiltered static-generation route list. Sitemap filtering is applied separately.
+
 See `StaticExportContext` in `static-export-context.ts`.

package/src/static-site-generator/production-page-browser-graph-prebuild.d.ts

@@ -0,0 +1,32 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { PageParams } from '../types/public-types.js';
+import type { PageRendererResolver } from '../route-renderer/route-renderer.js';
+export type ProductionPageBrowserGraphRouteInstance = {
+    routeFile: string;
+    params?: PageParams;
+};
+/**
+ * Returns whether production static export should warm Page Browser Graphs before rendering.
+ *
+ * @remarks
+ * True only when `NODE_ENV === 'production'`. Independent of `force` and of
+ * unified pages-graph env flags. Does not persist a disk manifest.
+ */
+export declare function shouldPrebuildProductionPageBrowserGraphs(): boolean;
+/**
+ * Clears in-memory production Page Browser Graph session records.
+ *
+ * @remarks
+ * Clears only the `'production'` policy so a failed or force export cannot
+ * reuse staged graph output. Development session records are left intact.
+ */
+export declare function clearProductionPageBrowserGraphSession(appConfig: EcoPagesAppConfig): void;
+/**
+ * Warms production Page Browser Graphs for the supplied static route instances.
+ *
+ * @remarks
+ * Deduplicates route file + params pairs, then calls each integration renderer's
+ * `prebuildProductionPageBrowserGraph` sequentially (activates integration runtime,
+ * then resolves into `page-browser-graph-session`). Does not persist a disk manifest.
+ */
+export declare function prebuildProductionPageBrowserGraphs(routeInstances: readonly ProductionPageBrowserGraphRouteInstance[], routeRendererFactory: PageRendererResolver): Promise<void>;

package/src/static-site-generator/production-page-browser-graph-prebuild.js

@@ -0,0 +1,57 @@
+import path from 'node:path';
+import { getAppPageBrowserGraphSession } from '../route-renderer/orchestration/page-browser-graph/page-browser-graph-session.js';
+import { createPageDependencyInstanceKey } from '../route-renderer/orchestration/page-browser-graph/route-instance-key.js';
+/**
+ * Returns whether production static export should warm Page Browser Graphs before rendering.
+ *
+ * @remarks
+ * True only when `NODE_ENV === 'production'`. Independent of `force` and of
+ * unified pages-graph env flags. Does not persist a disk manifest.
+ */
+export function shouldPrebuildProductionPageBrowserGraphs() {
+    return process.env.NODE_ENV === 'production';
+}
+/**
+ * Clears in-memory production Page Browser Graph session records.
+ *
+ * @remarks
+ * Clears only the `'production'` policy so a failed or force export cannot
+ * reuse staged graph output. Development session records are left intact.
+ */
+export function clearProductionPageBrowserGraphSession(appConfig) {
+    getAppPageBrowserGraphSession(appConfig).clearPolicyRecords('production');
+}
+function serializeProductionRouteInstance(instance) {
+    const routeFile = path.resolve(instance.routeFile);
+    const dependencyInstanceKey = createPageDependencyInstanceKey({ params: instance.params });
+    return JSON.stringify([routeFile, dependencyInstanceKey]);
+}
+/**
+ * Warms production Page Browser Graphs for the supplied static route instances.
+ *
+ * @remarks
+ * Deduplicates route file + params pairs, then calls each integration renderer's
+ * `prebuildProductionPageBrowserGraph` sequentially (activates integration runtime,
+ * then resolves into `page-browser-graph-session`). Does not persist a disk manifest.
+ */
+export async function prebuildProductionPageBrowserGraphs(routeInstances, routeRendererFactory) {
+    const uniqueRouteInstances = [
+        ...new Map(routeInstances.map((instance) => [serializeProductionRouteInstance(instance), instance])).values(),
+    ].sort((left, right) => serializeProductionRouteInstance(left).localeCompare(serializeProductionRouteInstance(right)));
+    const instancesByRenderer = new Map();
+    for (const routeInstance of uniqueRouteInstances) {
+        const renderer = routeRendererFactory.getPageRenderer(routeInstance.routeFile);
+        const instances = instancesByRenderer.get(renderer) ?? [];
+        instances.push(routeInstance);
+        instancesByRenderer.set(renderer, instances);
+    }
+    for (const [renderer, routeInstancesForRenderer] of instancesByRenderer) {
+        const groupedBuildPlan = await renderer.buildGroupedGraphBuildPlan(routeInstancesForRenderer);
+        for (const routeInstance of routeInstancesForRenderer) {
+            await renderer.prebuildProductionPageBrowserGraph(routeInstance.routeFile, {
+                params: routeInstance.params,
+                groupedBuildPlan,
+            });
+        }
+    }
+}

package/src/static-site-generator/sitemap-routes.d.ts

@@ -0,0 +1,14 @@
+import type { SitemapConfig } from '../types/public-types.js';
+/**
+ * Builds the ordered absolute locations for sitemap.xml.
+ *
+ * @remarks
+ * `eligiblePathnames` must already be successfully exported and robots-indexable.
+ * Filtering here is only `sitemap.exclude`, then `extraUrls` are appended.
+ * `extraUrls` always include (deduped) and are not subject to `exclude` or page robots.
+ */
+export declare function resolveSitemapLocations(input: {
+    eligiblePathnames: readonly string[];
+    sitemap: SitemapConfig;
+    baseUrl: string;
+}): string[];

package/src/static-site-generator/sitemap-routes.js

@@ -0,0 +1,36 @@
+import { matchesAnyPathPattern, normalizePathname } from '../utils/path-pattern.js';
+import { buildSitemapLocation } from './sitemap.js';
+/**
+ * Builds the ordered absolute locations for sitemap.xml.
+ *
+ * @remarks
+ * `eligiblePathnames` must already be successfully exported and robots-indexable.
+ * Filtering here is only `sitemap.exclude`, then `extraUrls` are appended.
+ * `extraUrls` always include (deduped) and are not subject to `exclude` or page robots.
+ */
+export function resolveSitemapLocations(input) {
+    const exclude = input.sitemap.exclude ?? [];
+    const locations = [];
+    const seen = new Set();
+    for (const pathname of input.eligiblePathnames) {
+        const normalized = normalizePathname(pathname);
+        if (matchesAnyPathPattern(normalized, exclude)) {
+            continue;
+        }
+        const location = buildSitemapLocation(input.baseUrl, normalized);
+        if (seen.has(location)) {
+            continue;
+        }
+        seen.add(location);
+        locations.push(location);
+    }
+    for (const extraUrl of input.sitemap.extraUrls ?? []) {
+        const location = buildSitemapLocation(input.baseUrl, extraUrl);
+        if (seen.has(location)) {
+            continue;
+        }
+        seen.add(location);
+        locations.push(location);
+    }
+    return locations;
+}

package/src/static-site-generator/sitemap.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Joins a base origin with a pathname or absolute URL into a sitemap `<loc>` value.
+ *
+ * @remarks
+ * Trailing slashes are stripped except for the site root (`/`). Absolute `http(s)`
+ * URLs in `extraUrls` are returned as-is (still slash-normalized).
+ */
+export declare function buildSitemapLocation(baseUrl: string, pathnameOrUrl: string): string;
+/**
+ * Renders a sitemap.org 0.9 urlset document from absolute location URLs.
+ *
+ * @remarks
+ * Callers are responsible for deduplication; this serializer preserves input order.
+ */
+export declare function renderSitemap(locations: readonly string[]): string;

package/src/static-site-generator/sitemap.js

@@ -0,0 +1,42 @@
+import { escapeXmlText } from '../utils/html-escaping.js';
+import { normalizePathname } from '../utils/path-pattern.js';
+/**
+ * Joins a base origin with a pathname or absolute URL into a sitemap `<loc>` value.
+ *
+ * @remarks
+ * Trailing slashes are stripped except for the site root (`/`). Absolute `http(s)`
+ * URLs in `extraUrls` are returned as-is (still slash-normalized).
+ */
+export function buildSitemapLocation(baseUrl, pathnameOrUrl) {
+    const trimmed = pathnameOrUrl.trim();
+    if (/^https?:\/\//i.test(trimmed)) {
+        return normalizeLocation(trimmed);
+    }
+    const origin = baseUrl.replace(/\/+$/, '');
+    const pathname = normalizePathname(trimmed);
+    return pathname === '/' ? `${origin}/` : `${origin}${pathname}`;
+}
+/**
+ * Renders a sitemap.org 0.9 urlset document from absolute location URLs.
+ *
+ * @remarks
+ * Callers are responsible for deduplication; this serializer preserves input order.
+ */
+export function renderSitemap(locations) {
+    const urls = locations
+        .map((loc) => `  <url>\n    <loc>${escapeXmlText(normalizeLocation(loc))}</loc>\n  </url>`)
+        .join('\n');
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+        urls,
+        '</urlset>',
+        '',
+    ].join('\n');
+}
+function normalizeLocation(location) {
+    if (/^https?:\/\/[^/]+\/?$/i.test(location)) {
+        return `${location.replace(/\/+$/, '')}/`;
+    }
+    return location.replace(/\/+$/, '');
+}

package/src/static-site-generator/static-build-invalidation.d.ts

@@ -1,7 +1,7 @@
 import type { EcoPagesAppConfig } from '../types/internal-types.js';
 import { type RouteModuleStaticRenderCacheContext } from '../services/module-loading/route-module-build-manifest.js';
-export type { BuildInputChangeContributor, IntegrationPlugin, Processor } from '../build/build-input-fingerprint.js';
-export { collectBuildInputContributors, createBuildInputsFingerprint, didBuildInputContributorChange, hashAppConfigFile, haveBuildInputsChanged, } from '../build/build-input-fingerprint.js';
+export type { BuildInputChangeContributor, IntegrationPlugin, Processor, } from '../build/cache/build-input-fingerprint.js';
+export { collectBuildInputContributors, createBuildInputsFingerprint, didBuildInputContributorChange, hashAppConfigFile, haveBuildInputsChanged, } from '../build/cache/build-input-fingerprint.js';
 /** Builds the static-render invalidation context for one app config. */
 export declare function createRouteModuleStaticRenderCacheContext(appConfig: EcoPagesAppConfig): RouteModuleStaticRenderCacheContext;
 /** Returns whether `dist/` should be wiped before the next static export. */