@ecopages/core 0.2.0-beta.4 → 0.2.0-beta.40

package/src/services/runtime-state/server-invalidation-state.service.js

@@ -1,35 +1,43 @@
-class CounterServerInvalidationState {
-  serverInvalidationVersion = 0;
-  getServerInvalidationVersion() {
-    return this.serverInvalidationVersion;
-  }
-  invalidateServerModules(_changedFiles) {
-    this.serverInvalidationVersion += 1;
-  }
-  reset() {
-    this.serverInvalidationVersion += 1;
-  }
+/**
+ * Minimal app-local invalidation state backed by a single generation counter.
+ */
+export class CounterServerInvalidationState {
+    serverInvalidationVersion = 0;
+    getServerInvalidationVersion() {
+        return this.serverInvalidationVersion;
+    }
+    invalidateServerModules(_changedFiles) {
+        this.serverInvalidationVersion += 1;
+    }
+    reset() {
+        this.serverInvalidationVersion += 1;
+    }
 }
 function isLegacyServerInvalidationState(value) {
-  return Boolean(value) && typeof value === "object" && typeof value.getServerInvalidationVersion === "function" && typeof value.invalidateServerModules === "function" && typeof value.reset === "function";
+    return (Boolean(value) &&
+        typeof value === 'object' &&
+        typeof value.getServerInvalidationVersion === 'function' &&
+        typeof value.invalidateServerModules === 'function' &&
+        typeof value.reset === 'function');
 }
-function getAppServerInvalidationState(appConfig) {
-  if (appConfig.runtime?.serverInvalidationState) {
-    return appConfig.runtime.serverInvalidationState;
-  }
-  if (isLegacyServerInvalidationState(appConfig.runtime?.devGraphService)) {
-    return appConfig.runtime.devGraphService;
-  }
-  return new CounterServerInvalidationState();
+/**
+ * Returns the app-owned server invalidation state.
+ */
+export function getAppServerInvalidationState(appConfig) {
+    if (appConfig.runtime?.serverInvalidationState) {
+        return appConfig.runtime.serverInvalidationState;
+    }
+    if (isLegacyServerInvalidationState(appConfig.runtime?.devGraphService)) {
+        return appConfig.runtime.devGraphService;
+    }
+    return new CounterServerInvalidationState();
 }
-function setAppServerInvalidationState(appConfig, serverInvalidationState) {
-  appConfig.runtime = {
-    ...appConfig.runtime ?? {},
-    serverInvalidationState
-  };
+/**
+ * Installs the invalidation state used by one app instance.
+ */
+export function setAppServerInvalidationState(appConfig, serverInvalidationState) {
+    appConfig.runtime = {
+        ...(appConfig.runtime ?? {}),
+        serverInvalidationState,
+    };
 }
-export {
-  CounterServerInvalidationState,
-  getAppServerInvalidationState,
-  setAppServerInvalidationState
-};

package/src/services/validation/schema-validation-service.d.ts

@@ -113,10 +113,7 @@ export declare class SchemaValidationService {
     validateRequest(source: ValidationSource, schemas: ValidationSchemas): Promise<ValidationResult<ValidatedData>>;
     /**
      * 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
      */
+    private mapSchemaIssue;
     private validateWithSchema;
 }

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

@@ -24,3 +24,44 @@ That means it should reuse:
 - asset processing
 
 It should not invent a parallel rendering stack just for build mode.
+
+## Files
+
+| File                           | Role                                                                         |
+| ------------------------------ | ---------------------------------------------------------------------------- |
+| `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/cache/build-input-fingerprint.ts` and is shared with server-entry and unified-graph caches.
+
+## Incremental static export
+
+`ServerStaticBuilder.prepareExportDirectory()` decides whether to wipe `dist/`:
+
+1. `force: true` → always reset
+2. Any processor/integration reports `didChange()` → reset
+3. Route-module manifest lacks matching `configHash` + `buildInputsFingerprint` → reset
+
+When `dist/` is preserved (`preserveExportDirectory: true`), `StaticSiteGenerator.run()` prunes HTML files no longer in the active route set.
+
+Rendered HTML reuse is tracked in `.eco/.server-modules/.build-cache.json` under each route module's `renderedOutputs`. `canReuseStaticRender()` skips re-rendering when the source file, dependency hashes, and output path are unchanged.
+
+`clearProductionBuildCaches()` runs on `force` builds and removes all persisted `.eco` build manifests (route modules, server entry, unified pages graph).
+
+## Integration hooks
+
+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;