@jimhoyd/urlcode 0.5.6 → 0.5.8

package/dist/types/init-with.d.ts

@@ -1,7 +1,6 @@
-import type { ScaffoldResult } from './extensions.ts';
 import type { DependencyPin } from './project-dependencies.ts';
 import { type BundleTransport } from './extension-bundles.ts';
-export interface InitWithOptions {
+interface InitWithOptions {
     cwd?: string | undefined;
     /** Default true: record exact pins for core, the named extensions and their declared peers. */
     manifest?: boolean | undefined;
@@ -14,7 +13,7 @@ export interface InitWithOptions {
     /** Test-only transport injection; production uses GitHub attestation verification. */
     bundleTransport?: BundleTransport | undefined;
 }
-export interface InitWithResult {
+interface InitWithResult {
     directory: string;
     project: string;
     hostFile: string;
@@ -24,15 +23,10 @@ export interface InitWithResult {
     dependencies: DependencyPin[];
 }
 export declare function parseWithNames(value: string): string[];
-/**
- * Orders the requested set from the scaffolds' declared `requires`, `after`, `provides` and `conflicts`, never from
- * the `--with` spelling. Kahn's algorithm with the lexically smallest ready extension first, so the result is
- * deterministic and identical for every permutation. Refuses a missing requirement, a conflict or a cycle by name.
- */
-export declare function orderScaffolds(results: readonly ScaffoldResult[]): ScaffoldResult[];
 /**
  * `urlcode init <directory> --with a,b`: the starter under `app/`, every extension's fragments merged into one
  * `urlcode.yaml`, one `host.mjs`, one `README.md` and the extensions' own files. All packages are resolved and
  * their scaffolds computed before anything is written, so a refusal leaves no directory behind.
  */
 export declare function initProjectWith(destination: string, requested: readonly string[], { cwd, manifest, pins, acknowledgements, bundleRelease, bundleTransport }?: InitWithOptions): Promise<InitWithResult>;
+export {};

package/dist/types/logging.d.ts

@@ -1,9 +1,10 @@
-export type JsonLogger = (event: object) => void;
+export declare function createJsonLogger(stream?: LogSink, maxBufferBytes?: number): JsonLogger;
+type JsonLogger = (event: object) => void;
 /** What the logger needs from its sink: the members of a Writable it touches. process.stdout satisfies it. */
-export interface LogSink {
+interface LogSink {
     write(chunk: string): unknown;
     writableLength: number;
     destroyed?: boolean;
     on?(event: 'error', listener: () => void): unknown;
 }
-export declare function createJsonLogger(stream?: LogSink, maxBufferBytes?: number): JsonLogger;
+export {};

package/dist/types/match.d.ts

@@ -1,5 +1,5 @@
 export type ParameterLocation = 'path' | 'query' | 'header';
-export type ScalarType = 'string' | 'integer' | 'number' | 'boolean';
+type ScalarType = 'string' | 'integer' | 'number' | 'boolean';
 export type Scalar = string | number | boolean;
 /** A parsed scalar, a parsed array, or a schema default (which the schema may shape freely). */
 export type ParameterValue = Scalar | Scalar[] | unknown;
@@ -81,3 +81,4 @@ export declare function contextFor(route: MatchableRoute, path: Record<string, s
 export declare function redirectLocation(route: MatchableRoute & {
     redirect: RedirectSpec;
 }, context: RequestContext, query: URLSearchParams): string;
+export {};

package/dist/types/object-guards.d.ts

@@ -0,0 +1,7 @@
+export type UnknownRecord = Record<string, unknown>;
+/** True for a non-null, non-array object -- the shape most parsed JSON/YAML fields expect. */
+export declare const isRecord: (value: unknown) => value is UnknownRecord;
+/** True for a `key` that `object` itself declares (not inherited). */
+export declare const own: (object: object, key: string) => boolean;
+/** True when `error` is a Node `Error` carrying the given `code` (e.g. `'ENOENT'`). */
+export declare const isCode: (error: unknown, code: string) => boolean;

package/dist/types/pattern-guard.d.ts

@@ -1,4 +1,3 @@
-export declare const maxPatternLength = 128;
 export declare const maxPatternInputLength = 128;
 /**
  * Accepts an author regex only when it is conservatively safe to run on every

package/dist/types/policies/cache.d.ts

@@ -2,7 +2,7 @@ import type { HandlerResult, HeaderPair } from '../http-response.ts';
 import type { LogFn, PolicyContext, PolicyRequest, PolicyShared, PolicySupport, TargetName } from '../types.ts';
 export declare const name = "cache";
 export declare const phases: readonly string[];
-export type Strategy = 'no-store' | 'revalidate' | 'public' | 'immutable' | 'swr' | 'sie' | 'micro' | 'cdn-only' | 'private';
+type Strategy = 'no-store' | 'revalidate' | 'public' | 'immutable' | 'swr' | 'sie' | 'micro' | 'cdn-only' | 'private';
 export interface CacheConfig {
     strategy: Strategy;
     maxAge?: number;
@@ -17,7 +17,7 @@ export interface CacheConfig {
     force?: boolean;
 }
 /** A stored 200 representation: the result minus its body and headers, which are kept separately. */
-export interface CacheEntry {
+interface CacheEntry {
     result: Omit<HandlerResult, 'body' | 'headers'>;
     headers: HeaderPair[];
     body: Buffer;
@@ -25,7 +25,7 @@ export interface CacheEntry {
     revalidating: boolean;
 }
 /** The in-flight fill for one key; waiters share its promise up to MAX_WAITERS. */
-export interface Flight {
+interface Flight {
     waiters: number;
     promise: Promise<CacheEntry | null>;
     resolve: (entry: CacheEntry | null) => void;
@@ -80,3 +80,4 @@ export declare function onResponse(state: CacheState, req: PolicyRequest, result
 export declare function onError(state: CacheState, req: PolicyRequest, _error?: unknown): void;
 export declare function describe(state: CacheState): CacheDescription;
 export declare function close(shared: PolicyShared | undefined): Promise<void>;
+export {};

package/dist/types/policies/compression.d.ts

@@ -2,7 +2,7 @@ import type { HandlerResult } from '../http-response.ts';
 import type { AssetResult, PolicyContext, PolicyRequest, PolicyShared, PolicySupport, TargetName } from '../types.ts';
 export declare const name = "compression";
 export declare const phases: readonly string[];
-export type Coding = 'br' | 'gzip' | 'deflate' | 'zstd';
+type Coding = 'br' | 'gzip' | 'deflate' | 'zstd';
 export interface CompressionConfig {
     encodings?: Coding[];
     minBytes?: number;

package/dist/types/policies/throttle.d.ts

@@ -2,7 +2,7 @@ import type { HandlerResult } from '../http-response.ts';
 import type { LogFn, PolicyContext, PolicyRequest, PolicyShared, PolicySupport, TargetName } from '../types.ts';
 export declare const name = "throttle";
 export declare const phases: readonly string[];
-export type Partition = 'client' | 'route' | 'client-route';
+type Partition = 'client' | 'route' | 'client-route';
 export interface ThrottleConfig {
     quota: number;
     window: number;

package/dist/types/policy.d.ts

@@ -1,10 +1,10 @@
 import type { FunctionSources } from './function-sources.ts';
 import type { LoadedDocument } from './types.ts';
-export interface EgressGrants {
+interface EgressGrants {
     proxy?: string[];
     signals?: string[];
 }
-export interface RouteGrant {
+interface RouteGrant {
     env?: string[];
     secrets?: string[];
     egress?: EgressGrants;
@@ -16,7 +16,7 @@ export interface OperatorPolicy {
     routes: Record<string, RouteGrant>;
 }
 /** The function snapshot plus the hash operator grants are pinned to. */
-export interface FunctionSnapshot extends FunctionSources {
+interface FunctionSnapshot extends FunctionSources {
     projectSha256: string;
 }
 export declare function prepareFunctionSnapshot(loaded: LoadedDocument): Promise<FunctionSnapshot>;
@@ -30,3 +30,4 @@ export declare function authorizeEgress(loaded: LoadedDocument, projectSha256: s
     proxy: string[];
     signals: string[];
 };
+export {};

package/dist/types/project-dependencies.d.ts

@@ -1,43 +1,4 @@
-/**
- * Exact dependency pins for a generated application.
- *
- * `urlcode init --with` resolves whatever `@jimhoyd/urlcode-<name>` packages are already installed beside the
- * invoking directory. Without a manifest the generated site records nothing about which versions it was built
- * against, so a later `npm install @jimhoyd/urlcode-auth` in that site can resolve a different set (#212). This
- * module reads the versions that were actually resolved, validates the whole set against the packages' own
- * declared `peerDependencies`, and renders a `package.json` pinning every one of them exactly.
- *
- * It never runs a package manager: generating a lockfile stays an explicit `npm install` the operator runs after
- * reviewing the manifest. It also never imports an extension implementation -- only package metadata is read, by
- * a name the caller supplied -- so core's generic extension boundary is unchanged.
- */
-export declare const CORE_PACKAGE = "@jimhoyd/urlcode";
-interface Version {
-    major: number;
-    minor: number;
-    patch: number;
-    pre: readonly (string | number)[];
-}
-export declare function parseVersion(value: string): Version | null;
-export declare function compareVersions(a: Version, b: Version): number;
 export declare function satisfiesRange(version: string, range: string, context?: string): boolean;
-export interface InstalledPackage {
-    name: string;
-    version: string;
-    directory: string;
-    peers: Record<string, string>;
-    optionalPeers: ReadonlySet<string>;
-    node: string | undefined;
-}
-/**
- * Walks `node_modules` upwards from the invoking directory, exactly like Node's own resolution but reading the
- * package's manifest rather than its entry point. Reading the manifest directly (instead of resolving the entry)
- * means a package whose `exports` does not expose `./package.json` is still inspectable, and nothing in the
- * package is loaded or executed.
- */
-export declare function findInstalledPackage(name: string, from: string): Promise<InstalledPackage | null>;
-/** The version of the runtime executing this command; that is the version a generated site is pinned to. */
-export declare function runningCore(): Promise<InstalledPackage>;
 export interface DependencyPin {
     name: string;
     version: string;
@@ -56,7 +17,7 @@ export interface DependencySet {
     /** True when any pin points at a local path or tarball. */
     local: boolean;
 }
-export interface DependencyOptions {
+interface DependencyOptions {
     cwd?: string | undefined;
     /** `--pin <package>=<specifier>`: an operator-chosen specifier, for local tarballs and mirrors. */
     overrides?: ReadonlyMap<string, string> | undefined;

package/dist/types/proxy.d.ts

@@ -6,7 +6,7 @@ export interface ProxyDefinition {
     responseHeaders?: string[];
     headers?: Record<string, string>;
 }
-export interface ProxyInput {
+interface ProxyInput {
     method: string;
     url: string | URL;
     params: Record<string, unknown>;
@@ -19,3 +19,4 @@ export interface EgressTransport {
 }
 export declare function validateProxy(definition: ProxyDefinition): void;
 export declare function executeProxy(client: EgressTransport, definition: ProxyDefinition, input: ProxyInput): Promise<EgressResponse>;
+export {};

package/dist/types/readiness.d.ts

@@ -1,10 +1,9 @@
 import { Agent } from 'node:http';
 import type { AddressInfo } from 'node:net';
-import type { CompiledRedirect, CompiledRoute, LogFn, PlanInventoryEntry, PolicyInventory } from './types.ts';
+import type { CompiledRedirect, CompiledRoute, HandlerName, LogFn, PlanInventoryEntry, PolicyInventory } from './types.ts';
 import type { ComplianceOptions, ComplianceReport } from './compliance.ts';
 import type { CompiledRoutes } from './match.ts';
-export type { RouteState } from './types.ts';
-export type HandlerName = 'extension' | 'proxy' | 'conditional' | 'redirect' | 'function' | 'page' | 'static' | 'download' | 'respond';
+export type { RouteState, HandlerName } from './types.ts';
 /** One configured route as the inventory reports it: a PlanInventoryEntry with the handler kind named. */
 export interface RouteInventory extends PlanInventoryEntry {
     handler: HandlerName | undefined;
@@ -27,29 +26,28 @@ export interface RequestCase {
     capture?: Record<string, CaptureSpec> | undefined;
 }
 /** Where a captured value comes from: a dotted path into a JSON response body, or one response header. */
-export type CaptureSpec = {
+type CaptureSpec = {
     json: string;
 } | {
     header: string;
 };
 /** A step that closes and restarts the runtime on the same project and data directory. */
-export interface RestartStep {
+interface RestartStep {
     restart: true;
 }
 /** An ordered fixture: requests that share captured values, optionally with restarts between them. */
-export interface StepsFixture {
+interface StepsFixture {
     steps: (RequestCase | RestartStep)[];
 }
 export type Fixture = RequestCase | StepsFixture;
 export declare const isStepsFixture: (fixture: Fixture) => fixture is StepsFixture;
-export declare const isRestartable: (app: AuditableApp) => app is RestartableApp;
 export interface ProjectPlan {
     inventory: RouteInventory[];
     cases: RequestCase[];
     resolve: (path: string) => string | undefined;
 }
 /** `captured` holds values from a step's `capture`; callers use it for substitution only and never print it. */
-export interface HitResult {
+interface HitResult {
     pass: boolean;
     status: number;
     durationMs: number;
@@ -74,12 +72,12 @@ export interface RestartableApp extends AuditableApp {
     restart(): Promise<void>;
 }
 export type { ComplianceOptions, ComplianceReport } from './compliance.ts';
-export interface AuditOptions {
+interface AuditOptions {
     expectRoutes?: number | undefined;
     log?: LogFn | undefined;
     compliance?: ComplianceOptions | undefined;
 }
-export interface AuditReport {
+interface AuditReport {
     elapsedMs: number;
     ready: boolean;
     /** Empty when `ready`; otherwise one stable code per failed condition:
@@ -134,7 +132,7 @@ export interface AuditReport {
         message: string;
     }[];
 }
-export interface BenchmarkOptions {
+interface BenchmarkOptions {
     requests?: number | undefined;
     concurrency?: number | undefined;
     maxP95Ms?: number | undefined;
@@ -142,7 +140,7 @@ export interface BenchmarkOptions {
     warmup?: number | undefined;
     target?: string | undefined;
 }
-export interface BenchmarkReport {
+interface BenchmarkReport {
     pass: boolean;
     requested: number;
     completed: number;
@@ -174,17 +172,15 @@ export declare const hasRedirect: (route: CompiledRoute) => route is CompiledRou
 export declare const probeAgent = "Mozilla/5.0 (compatible; RouteProbe/0.1)";
 export declare function projectPlan(compiled: CompiledRoutes<CompiledRoute>): ProjectPlan;
 export declare function readFixtures(root: string, optional?: boolean): Promise<Fixture[]>;
-/** Single-request fixtures only: the benchmark replays these and cannot run ordered steps. */
-export declare function readCases(root: string, optional?: boolean): Promise<RequestCase[]>;
 /** One request a fixture run sent: `test` is the request as sent (captured values filled in), `original` as written. Print `original`, never `test`. */
-export interface FixtureStep {
+interface FixtureStep {
     case: number;
     fixture: number;
     test: RequestCase;
     original: RequestCase;
     result: HitResult;
 }
-export interface FixtureHost {
+interface FixtureHost {
     app: AuditableApp;
     agent: Agent;
     target?: BenchmarkTarget | undefined;

package/dist/types/review.d.ts

@@ -25,6 +25,4 @@ export interface ProjectReview {
     observations: ReviewObservation[];
     summary: Record<ReviewCategory, number>;
 }
-export declare const reviewModuleByteLimit = 1048576;
-export declare const reviewExcerptLimit = 240;
 export declare function reviewProject(project: string, options?: InspectOptions): Promise<ProjectReview>;

package/dist/types/route-diff.d.ts

@@ -1,6 +1,6 @@
 import type { PlanInventoryEntry } from './types.ts';
 /** One route as the diff sees it: the inventory entry plus its policy description from the `policies` map. */
-export interface RouteRecord extends PlanInventoryEntry {
+interface RouteRecord extends PlanInventoryEntry {
     policy?: Record<string, unknown>;
 }
 /** The parts of a `urlcode routes` report the diff reads. */
@@ -8,12 +8,12 @@ export interface RouteSnapshot {
     inventory: PlanInventoryEntry[];
     policies?: Record<string, Record<string, unknown>> | undefined;
 }
-export interface RouteChange {
+interface RouteChange {
     path: string;
     before: RouteRecord;
     after: RouteRecord;
 }
-export interface RouteDiff {
+interface RouteDiff {
     added: RouteRecord[];
     removed: RouteRecord[];
     changed: RouteChange[];
@@ -25,3 +25,4 @@ export declare function diffRoutes(before: RouteSnapshot, after: RouteSnapshot):
 export declare const hasRouteChanges: (diff: RouteDiff) => boolean;
 /** Renders a diff as Markdown: one table per nonempty section, or "No route changes". */
 export declare function renderRouteDiff(diff: RouteDiff): string;
+export {};

package/dist/types/router.d.ts

@@ -2,7 +2,7 @@ import type { RuntimeExtension } from './extensions.ts';
 import type { CompiledRouteTable, LoadedDocument } from './types.ts';
 export { parseTarget, matchRoute, contextFor, resolveValue, redirectLocation } from './match.ts';
 /** The grants compileRoutes consults: a validated OperatorPolicy (policy.ts) or nothing, which denies every binding. */
-export interface BindingPermissions {
+interface BindingPermissions {
     projectSha256?: string;
     routes?: Record<string, {
         env?: string[];

package/dist/types/server.d.ts

@@ -16,6 +16,28 @@ export interface ServerOptions extends Omit<RuntimeOptions, 'observers'> {
     observers?: Observer[] | undefined;
     metrics?: boolean | undefined;
     metricsIntervalMs?: number | undefined;
+    /** Expose build version and route count on `/_urlcode/health`. Off by default so an
+     * unauthenticated probe does not disclose deployment details; defaults to `metrics`
+     * so enabling the (also unauthenticated-by-default) metrics exposition keeps its
+     * existing level of disclosure. */
+    healthDetails?: boolean | undefined;
+    /** Milliseconds `close()` waits, with the listener still open and `/_urlcode/ready`
+     * already reporting unhealthy, before it stops accepting connections. Gives a load
+     * balancer time to notice the readiness change and stop routing new traffic here.
+     * `/_urlcode/health` (liveness) stays healthy during this window. 0 disables the delay. */
+    readinessDrainMs?: number | undefined;
+    /** Milliseconds `close()` gives in-flight HTTP connections to finish once it stops
+     * accepting new ones, before forcing them closed. Keep this below the process
+     * supervisor's stop grace period (Docker's `--stop-timeout`, Kubernetes'
+     * `terminationGracePeriodSeconds`) combined with `readinessDrainMs`, or the process
+     * can be SIGKILLed mid-drain. */
+    closeTimeoutMs?: number | undefined;
+    /** Milliseconds allowed to receive a request's headers before the socket is reset. */
+    headersTimeoutMs?: number | undefined;
+    /** Milliseconds allowed for an entire request (headers and body) before the socket is reset. */
+    requestTimeoutMs?: number | undefined;
+    /** Milliseconds an idle keep-alive connection is held open for reuse. */
+    keepAliveTimeoutMs?: number | undefined;
     /** Test helper. Directory the project may use for its own files, offered as the `URLCODE_DATA_DIR`
      * environment value (a route reads it through a declared `env` binding). Created if absent and
      * never deleted by `close()`, so a later server started on the same directory sees the same data. */

package/dist/types/signals.d.ts

@@ -3,12 +3,12 @@ export interface SignalDefinition {
     url: string;
     headers?: Record<string, string>;
 }
-export interface SignalEvent {
+interface SignalEvent {
     route: string;
     status: number;
     method: string;
 }
-export interface SignalStats {
+interface SignalStats {
     accepted: number;
     delivered: number;
     failed: number;
@@ -23,3 +23,4 @@ export declare class SignalBroker {
     emit(definition: SignalDefinition, event: SignalEvent): boolean;
     close(): Promise<void>;
 }
+export {};

package/dist/types/site.d.ts

@@ -1,5 +1,5 @@
 import type { LoadedDocument, LogFn, ProjectDocument, RouteConfig, SiteConfig } from './types.ts';
-export interface SiteOptions {
+interface SiteOptions {
     origin?: string | undefined;
     log?: LogFn;
     routes?: Record<string, RouteConfig>;
@@ -8,6 +8,5 @@ type SiteKey = keyof SiteConfig;
 export declare const generatedPaths: Readonly<Record<SiteKey, string>>;
 export declare function expandSite(document: ProjectDocument, root: string, { origin, log, routes }?: SiteOptions): Promise<Record<string, RouteConfig>>;
 export declare function applySite(loaded: LoadedDocument, options?: SiteOptions): Promise<Record<string, RouteConfig>>;
-export declare const notFoundInlineLimit = 65536;
 export declare function inlineNotFound(loaded: LoadedDocument): Promise<boolean>;
 export {};

package/dist/types/trusted-functions.d.ts

@@ -2,7 +2,7 @@ import type { FunctionRoute } from './function-sources.ts';
 import type { FunctionContext, FunctionResult } from './functions.ts';
 import type { GuestRequestPayload } from './guest-api.ts';
 import type { HandlerResult } from './http-response.ts';
-export interface TrustedFunctionsOptions {
+interface TrustedFunctionsOptions {
     timeoutMs?: number | undefined;
     maxBytes?: number | undefined;
 }

package/dist/types/types.d.ts

@@ -27,13 +27,13 @@ export interface ParameterConfig {
  * degrades to its literal default rather than failing); with no `default`, a missing grant
  * fails route compilation (docs/yaml/functions.md, "Host overrides").
  */
-export interface EnvBinding {
+interface EnvBinding {
     value?: string;
     env?: string;
     default?: string;
 }
 /** `secrets` binding: the `secret` name to read from the process environment. */
-export interface SecretBinding {
+interface SecretBinding {
     secret: string;
 }
 export interface FunctionConfig {
@@ -100,7 +100,7 @@ export interface RobotsConfig {
     sitemap?: boolean;
     extra?: string[];
 }
-export type Changefreq = 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+type Changefreq = 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
 export interface SitemapConfig {
     exclude?: string[];
     changefreq?: Changefreq;
@@ -124,11 +124,11 @@ export interface SiteConfig {
     notFound?: string;
 }
 /** One route as declared in YAML (plus `generated`, which site.ts stamps on the routes it adds). */
-export interface ConditionalReply {
+interface ConditionalReply {
     redirect?: RedirectConfig;
     respond?: RespondSpec;
 }
-export interface ConditionalConfig {
+interface ConditionalConfig {
     cases: (ConditionalReply & {
         match: RouteMatch;
     })[];
@@ -137,15 +137,15 @@ export interface ConditionalConfig {
 export type EgressHeaders = Record<string, string | {
     secret: string;
 }>;
-export interface ProxyConfig extends Omit<ProxyDefinition, 'headers'> {
+interface ProxyConfig extends Omit<ProxyDefinition, 'headers'> {
     headers?: EgressHeaders;
 }
-export interface SignalConfig {
+interface SignalConfig {
     url: string;
     headers?: EgressHeaders;
 }
 /** Route-level `auth` short form. Keys other than `required` mirror the auth extension's policy schema and expand to `policies.extensions.auth`. */
-export interface RouteAuthConfig {
+interface RouteAuthConfig {
     required?: boolean;
     role?: string;
     permission?: string;
@@ -202,6 +202,11 @@ export interface RouteConfig {
     /** Set by site.ts on a route it generated (`site.<key>`); never declared in YAML. */
     generated?: string;
 }
+/** The route-level fields that select a handler, in priority order for the rare case more than one is set. */
+export declare const handlerNames: readonly ["extension", "proxy", "conditional", "redirect", "function", "page", "static", "download", "respond"];
+export type HandlerName = typeof handlerNames[number];
+/** The first declared handler field's name, or `fallback` when the route (or, for a partial view such as `explain`'s route summary, the fields read) declares none. Shared by examples.ts and context.ts, whose only difference was this fallback string. */
+export declare function resolveHandlerName(route: Partial<Record<HandlerName, unknown>>, fallback: string): string;
 /** A named, reusable `request` and `response.headers` block a route selects with `use`. */
 export interface SharedBlock {
     request?: RouteConfig['request'];
@@ -225,12 +230,12 @@ export interface LoadedDocument {
     files: string[];
     version: string;
 }
-export interface CompiledFunction {
+interface CompiledFunction {
     source: string;
     export: string;
     args?: Record<string, ValueRef | Scalar>;
 }
-export interface CompiledMiddleware {
+interface CompiledMiddleware {
     source: string;
     export: string;
 }
@@ -389,7 +394,7 @@ export type PolicyInventory = {
     };
 };
 /** A module paired with the state it compiled for one route, in phase order. */
-export type PolicyEntry = [PolicyModule, unknown];
+type PolicyEntry = [PolicyModule, unknown];
 /** What compilePolicies returns for a route: ordered hook chains, the audit summary and each state by name. */
 export type PolicyChain = {
     request: PolicyEntry[];
@@ -423,3 +428,4 @@ export interface TestPlan {
     resolve?(path: string): string | undefined;
     policies?: Record<string, PolicyInventory>;
 }
+export {};

package/dist/types/vercel.d.ts

@@ -11,4 +11,5 @@ export interface VercelHandlerOptions {
     extensions?: RuntimeExtension[] | undefined;
 }
 export type VercelHandler = (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+export declare function forwardedClient(headers: Headers, headerCounts: Record<string, number>): string | undefined;
 export declare function createVercelHandler({ project, origin, environment, maxBodyBytes, plugins, extensions }?: VercelHandlerOptions): VercelHandler;

package/dist/types/verify-deployment.d.ts

@@ -3,7 +3,7 @@ import type { ComplianceOptions, ComplianceReport, Severity } from './compliance
 import type { LogFn } from './types.ts';
 export type { Severity } from './compliance.ts';
 export type FailOn = Severity | 'none';
-export type CheckName = 'probes' | 'fixtures' | 'security' | 'cache' | 'compression' | 'agents' | 'throttle' | 'site' | 'methods' | 'errors' | 'head' | 'transport';
+type CheckName = 'probes' | 'fixtures' | 'security' | 'cache' | 'compression' | 'agents' | 'throttle' | 'site' | 'methods' | 'errors' | 'head' | 'transport';
 export interface VerifyFinding {
     check: CheckName;
     severity: Severity;

package/dist/types.js

@@ -34,9 +34,9 @@
  * degrades to its literal default rather than failing); with no `default`, a missing grant
  * fails route compilation (docs/yaml/functions.md, "Host overrides").
  */
-                                                                              
+                                                                       
 /** `secrets` binding: the `secret` name to read from the process environment. */
-                                                 
+                                          
                                                                                                              
                                                                      
 /** A route as YAML may spell it before normalization: `function` and middleware entries may be short-form module paths. */
@@ -56,7 +56,7 @@
 /** The result of layering profiles and route keys: what compiles, per policy. */
                                                        
                                                                                                             
-                                                                                                   
+                                                                                            
                                                                                                  
                                     
                                                                                     
@@ -64,13 +64,13 @@
  
                                                                                                                                                                           
 /** One route as declared in YAML (plus `generated`, which site.ts stamps on the routes it adds). */
-                                                                                      
-                                                                                                                       
+                                                                               
+                                                                                                                
                                                                   
-                                                                                                
-                                                                    
+                                                                                         
+                                                             
 /** Route-level `auth` short form. Keys other than `required` mirror the auth extension's policy schema and expand to `policies.extensions.auth`. */
-                                                                                                                                                                                  
+                                                                                                                                                                           
                               
                                                    
                                                                                                                                              
@@ -102,6 +102,13 @@
                                                                                        
                      
  
+/** The route-level fields that select a handler, in priority order for the rare case more than one is set. */
+export const handlerNames = ['extension','proxy','conditional','redirect','function','page','static','download','respond']         ;
+                                                      
+/** The first declared handler field's name, or `fallback` when the route (or, for a partial view such as `explain`'s route summary, the fields read) declares none. Shared by examples.ts and context.ts, whose only difference was this fallback string. */
+export function resolveHandlerName(route                                       , fallback        )         {
+  return handlerNames.find(name => route[name] !== undefined) ?? fallback;
+}
 /** A named, reusable `request` and `response.headers` block a route selects with `use`. */
                                                                                                      
                                   
@@ -114,8 +121,8 @@
 // ---------------------------------------------------------------------------
 // Compiled routes and assets.
 
-                                                                                                              
-                                                                      
+                                                                                                       
+                                                               
 /** One file read into the asset snapshot; a static route holds a Map of them keyed by relative path. */
                         
                                                                                                             
@@ -199,7 +206,7 @@
 /** A route's policy inventory: each policy's describe() plus the support it got; a delegated policy carries only `target`. */
                                                                                                                  
 /** A module paired with the state it compiled for one route, in phase order. */
-                                                  
+                                           
 /** What compilePolicies returns for a route: ordered hook chains, the audit summary and each state by name. */