@jimhoyd/urlcode 0.4.2 → 0.4.6

package/dist/types/config.d.ts

@@ -1,4 +1,5 @@
-import type { LoadedDocument, ProjectDocument, RouteConfig } from './types.ts';
+import type { ErrorObject } from 'ajv';
+import type { LoadedDocument, ProjectDocument, RouteConfig, SharedBlock } from './types.ts';
 /** What config-worker.ts posts back: the loaded document, or the ConfigError message. */
 export type ConfigWorkerResult = {
     value: LoadedDocument;
@@ -10,7 +11,14 @@ export interface ConfigWorkerData {
 }
 export declare const MAX_CONFIG_BYTES: number;
 export declare function parseYaml(text: string): unknown;
-export declare function validateDocument(data: unknown): ProjectDocument;
+/**
+ * One line for the first schema violation. Closed-key-set failures name the offending key and the keys the
+ * schema allows, and required failures name the missing key, because a bare keyword sends the reader hunting.
+ * Only key names, which come from the schema or the author's own mapping keys, are echoed, never values
+ * (values may hold secrets), and never more than MAX_NAMED_KEY characters of a key.
+ */
+export declare function describeSchemaError(e: ErrorObject): string;
+export declare function validateDocument(data: unknown, inherited?: Record<string, SharedBlock>): ProjectDocument;
 /** The input declaration a short-form function gets for each `{param}` it does not declare itself. */
 export declare const SHORT_FORM_PATH_SCHEMA: {
     readonly type: "string";

package/dist/types/context.d.ts

@@ -62,5 +62,5 @@ export declare function estimateTokens(text: string): number;
 export declare function renderContext(context: ProjectContext): string;
 /** Derived only from the compiled project and the capability catalog, never from prose. Key order is fixed. */
 export declare function buildContext(project: string, options?: ContextOptions): Promise<ProjectContext>;
-/** Estimated size of the shipped documentation (docs/*.md and llms.txt), for comparison with an emitted context. */
+/** Estimated size of the shipped offline documentation bundle, for comparison with an emitted context. */
 export declare function documentationTokens(): Promise<number>;

package/dist/types/errors.d.ts

@@ -2,6 +2,14 @@ export declare class ConfigError extends Error {
 }
 export declare class HttpError extends Error {
     readonly status: number;
-    constructor(status: number, message: string);
+    /** A pre-rendered, fixed-content answer that replaces the plain-text message (used for negotiated 422 bodies). */
+    readonly answer: {
+        contentType: string;
+        text: string;
+    } | undefined;
+    constructor(status: number, message: string, answer?: {
+        contentType: string;
+        text: string;
+    });
 }
 export declare function assert(condition: unknown, message: string): asserts condition;

package/dist/types/examples.d.ts

@@ -31,7 +31,7 @@ export interface ExampleSearchResult {
         matchedRoutes: RouteIndexEntry[];
     })[];
 }
-export declare const exampleNames: readonly ["assets", "aws", "cloudflare", "compliance", "conditions", "cookbook", "egress", "extensions", "monitoring", "prerender", "provider-conformance", "tunnel", "vercel"];
+export declare const exampleNames: readonly ["assets", "aws", "body-validation", "cloudflare", "compliance", "conditions", "cookbook", "coverage-waiver", "data-dir", "egress", "extensions", "lifecycle", "monitoring", "not-found", "prerender", "provider-conformance", "shared-blocks", "tunnel", "vercel"];
 export declare const routeIndexFile = "route-index.json";
 export declare function listExamples(): Promise<ExampleSummary[]>;
 /**

package/dist/types/extensions.d.ts

@@ -82,6 +82,27 @@ export interface ExtensionHookContract {
     inputSchema: object;
     outputSchema?: object;
 }
+export type ExtensionAuthoringKind = 'configuration' | 'theme' | 'copy' | 'component' | 'template' | 'stylesheet' | 'hook' | 'extension';
+/** One project-owned customization surface, shown to people and authoring agents by CLI/MCP inspection. */
+export interface ExtensionAuthoringSurface {
+    kind: ExtensionAuthoringKind;
+    name: string;
+    description: string;
+    /** Project-relative convention or configuration path, when the surface has one. */
+    path?: string;
+    /** A bounded local command that discovers, previews or checks the surface. */
+    command?: string;
+}
+/**
+ * Machine-readable guidance for changing an installed extension without
+ * copying its behavior into the application. This is descriptive only: it
+ * grants nothing and is never executed by the runtime.
+ */
+export interface ExtensionAuthoringContract {
+    description: string;
+    surfaces: readonly ExtensionAuthoringSurface[];
+    fastChecks?: readonly string[];
+}
 export type LoadedExtensionHooks<T extends string = string> = Partial<Record<T, (input: unknown) => unknown>>;
 /** Shared schema for project hook references. Omission means trusted execution. */
 export declare const extensionHookReferenceSchema: {
@@ -133,6 +154,8 @@ export interface RuntimeExtension {
     immutableAssets?: ExtensionImmutableAssets;
     /** Project customization points, exposed by CLI/MCP for authors and agents. */
     hooks?: readonly ExtensionHookContract[];
+    /** Supported project-owned customization surfaces, exposed by CLI/MCP. */
+    authoring?: ExtensionAuthoringContract;
     /**
      * Reviewed, operator-declared cache sensitivity for `policies.extensions.<name>`
      * routes (never for an `extension:` mount, which is always treated as
@@ -160,8 +183,15 @@ export interface ScaffoldRequest {
     project: string;
     /** Absolute path of the combined host module core writes, `<directory>/host.mjs`. */
     hostFile: string;
-    /** Every extension name being scaffolded together, in `--with` order, including this one. */
+    /** Every extension name being scaffolded together, including this one, in a canonical (sorted) order that is independent of the `--with` spelling. */
     names: readonly string[];
+    /**
+     * Operator acknowledgements from repeated `--ack <extension>:<id>` flags, sorted and de-duplicated; empty when none. Core treats
+     * them as opaque strings and never invents one. An extension reads only the ones qualified with its own name. To require one, throw
+     * an Error carrying `acknowledgement: '<name>:<id>'` whose message states the risk; core appends the exact re-run command with
+     * `--ack <name>:<id>`. List each one the scaffold used in `ScaffoldResult.acknowledged`.
+     */
+    acknowledgements: readonly string[];
 }
 export interface ScaffoldFile {
     path: string;
@@ -171,6 +201,21 @@ export interface ScaffoldFile {
 export interface ScaffoldResult {
     /** Must equal the requested name. */
     name: string;
+    /**
+     * Declarative composition contract; `--with` is an unordered set and core derives the host, activation and README order from these.
+     * `provides`: capability names this extension offers (a name must not equal an extension name). `requires`: extensions or
+     * capabilities that must be in the set and are placed before this one; a missing one refuses. `after`: the same ordering
+     * without requiring presence. `conflicts`: extensions or capabilities that must not be in the set. A cycle refuses. Core never
+     * adds an extension or infers policy from these lists.
+     */
+    provides?: string[];
+    requires?: string[];
+    after?: string[];
+    conflicts?: string[];
+    /** The `<name>:<id>` acknowledgements this scaffold consumed. Core refuses any passed `--ack` that no scaffold lists here, so an acknowledgement cannot be passed with no effect. */
+    acknowledged?: string[];
+    /** One-line notes written as comments above this extension's routes in the route fragment (for example the selected access model). */
+    routeNotes?: string[];
     /** Fragments merged into the project's top-level `extensions` and `routes`; duplicate keys are refused. */
     extensions: Record<string, unknown>;
     routes: Record<string, unknown>;
@@ -181,7 +226,7 @@ export interface ScaffoldResult {
     hostClose?: string[];
     /** Files written relative to `directory` with their modes; never inside the project, never overwriting. */
     files: ScaffoldFile[];
-    /** Markdown appended to README.md under a heading core adds; the numbered steps merged in `--with` order. */
+    /** Markdown appended to README.md under a heading core adds; the numbered steps merged in the resolved order. */
     readme: string;
     nextSteps: string[];
     /** Environment variables the host reads, with one-line descriptions. */

package/dist/types/http-policy.d.ts

@@ -1,5 +1,6 @@
 import type { HandlerResult, HeaderPair } from './http-response.ts';
 import type { HeadersLike } from './match.ts';
+import type { BodySchema } from './body-schema.ts';
 export interface RespondSpec {
     status?: number;
     json?: unknown;
@@ -10,6 +11,7 @@ export interface RequestBodyPolicy {
     required?: boolean;
     contentTypes?: string[];
     format?: 'json' | 'text';
+    schema?: BodySchema;
 }
 /** A static reply compiled from `respond`; the body is bytes so every host, including the Worker, shares the type. */
 export interface Reply {
@@ -32,6 +34,7 @@ export interface HttpRoute {
     responseHeaders?: HeaderPair[];
     reply?: Reply | undefined;
 }
+export declare const reservedResponseHeaders: Set<string>;
 export declare function compileHttp(route: HttpRoute): void;
 export declare function checkRequest(route: HttpRoute, body: Uint8Array, headers: HeadersLike, counts?: Record<string, number>): void;
 export declare function decorateResponse(route: HttpRoute & {

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

@@ -1,3 +1,4 @@
+import type { ScaffoldResult } from './extensions.ts';
 import type { DependencyPin } from './project-dependencies.ts';
 export interface InitWithOptions {
     cwd?: string | undefined;
@@ -5,6 +6,8 @@ export interface InitWithOptions {
     manifest?: boolean | undefined;
     /** `--pin <package>=<specifier>` overrides, for local tarballs, checkouts and mirrors. */
     pins?: ReadonlyMap<string, string> | undefined;
+    /** `--ack <extension>:<id>`, repeatable: opaque qualified acknowledgements handed to every scaffold. Core refuses one that no scaffold consumed. */
+    acknowledgements?: readonly string[] | undefined;
 }
 export interface InitWithResult {
     directory: string;
@@ -16,9 +19,15 @@ 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, names: readonly string[], { cwd, manifest, pins }?: InitWithOptions): Promise<InitWithResult>;
+export declare function initProjectWith(destination: string, requested: readonly string[], { cwd, manifest, pins, acknowledgements }?: InitWithOptions): Promise<InitWithResult>;

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

@@ -0,0 +1,10 @@
+export declare const maxPatternLength = 128;
+export declare const maxPatternInputLength = 128;
+/**
+ * Accepts an author regex only when it is conservatively safe to run on every
+ * request in the host process. Node has no linear-time engine, so this refuses
+ * the constructs that make backtracking blow up — repeated groups, lookaround
+ * and backreferences — and caps unbounded quantifiers. It is a restriction, not
+ * a proof: callers must also bound the input length to `maxPatternInputLength`.
+ */
+export declare function assertSafePattern(pattern: string): void;

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

@@ -1,4 +1,5 @@
 import type { ServerOptions } from './server.ts';
+import type { RestartableApp } from './readiness.ts';
 import type { LogFn } from './types.ts';
 export interface ProjectTestOptions {
     extensions?: ServerOptions['extensions'];
@@ -11,4 +12,12 @@ export interface ProjectTestResult {
     total: number;
     failed: number;
 }
+/**
+ * A server that fixture `restart` steps can close and start again on the same project and the
+ * same data directory. The data directory is fresh and empty, offered to the project as
+ * `URLCODE_DATA_DIR`, and removed by `close()`; on a filesystem where it cannot be created, none is offered. `restart()` gets a new port; read `address` after it.
+ */
+export declare function startRestartable(options: ServerOptions): Promise<RestartableApp & {
+    close(): Promise<void>;
+}>;
 export declare function runProjectTests(project: string, { log, permissions, origin, extensions, plugins }?: ProjectTestOptions): Promise<ProjectTestResult>;

package/dist/types/readiness.d.ts

@@ -23,17 +23,38 @@ export interface RequestCase {
     body?: string | undefined;
     expectHeaders?: Record<string, string> | undefined;
     expectBody?: string | undefined;
+    /** Only inside `steps`: values kept from this step's response for later steps' `{{name}}` references. */
+    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 = {
+    json: string;
+} | {
+    header: string;
+};
+/** A step that closes and restarts the runtime on the same project and data directory. */
+export interface RestartStep {
+    restart: true;
+}
+/** An ordered fixture: requests that share captured values, optionally with restarts between them. */
+export 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 {
     pass: boolean;
     status: number;
     durationMs: number;
     error?: string;
+    captured?: Record<string, string>;
 }
 export interface BenchmarkTarget {
     protocol: string;
@@ -48,6 +69,10 @@ export interface AuditableApp {
         policies?: Record<string, PolicyInventory>;
     };
 }
+/** An app that can also close and restart itself on the same project and data directory (fixture `restart` steps). */
+export interface RestartableApp extends AuditableApp {
+    restart(): Promise<void>;
+}
 export type { ComplianceOptions, ComplianceReport } from './compliance.ts';
 export interface AuditOptions {
     expectRoutes?: number | undefined;
@@ -60,8 +85,12 @@ export interface AuditReport {
     /** Empty when `ready`; otherwise one stable code per failed condition:
      * `no-active-routes`, `route-count-mismatch`, `failed-checks`, `uncovered-route-methods`. */
     notReadyReasons: string[];
+    /** `configured` is every route in the table, including routes generated from `site` keys; `--expect-routes` compares against it.
+     * `declared` + `generated` always equals `configured`. */
     counts: {
         configured: number;
+        declared: number;
+        generated: number;
         active: number;
         disabled: number;
         expired: number;
@@ -78,6 +107,24 @@ export interface AuditReport {
         route: string;
         method: string;
     }[];
+    /** Route/method pairs excused by a `coveredElsewhere` waiver, with the reason. Shown even when `ready`. */
+    waivedRouteMethods: {
+        route: string;
+        method: string;
+        reason: string;
+    }[];
+    /** Waivers not honored (the route has no normally covered method, e.g. an error-only function route); their pairs stay in `uncovered`. */
+    ignoredWaivers: {
+        route: string;
+        method: string;
+        reason: string;
+    }[];
+    /** Waivers whose pair already has a passing normal-response fixture: remove them. Never blocks `ready`. */
+    redundantWaivers: {
+        route: string;
+        method: string;
+        reason: string;
+    }[];
     policies: Record<string, PolicyInventory>;
     compliance: ComplianceReport | null;
     /** Non-blocking `audit` observations, e.g. a route that looks webhook-shaped
@@ -126,7 +173,28 @@ 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 {
+    case: number;
+    fixture: number;
+    test: RequestCase;
+    original: RequestCase;
+    result: HitResult;
+}
+export interface FixtureHost {
+    app: AuditableApp;
+    agent: Agent;
+    target?: BenchmarkTarget | undefined;
+    /** Close and restart the runtime on the same project and data directory. Absent: the host cannot restart. */
+    restart?: (() => Promise<void>) | undefined;
+    /** Called with the 1-based fixture number and a reason when a fixture with a restart step is skipped because the host cannot restart. Absent: such a fixture is refused with an error. */
+    skipped?: ((fixture: number, reason: string) => void) | undefined;
+}
+/** Runs every fixture in file order. A step after a failed step in the same fixture is reported failed with error `skipped` and never sent, so a broken chain cannot pass. */
+export declare function runFixtures(fixtures: Fixture[], host: FixtureHost, visit: (step: FixtureStep) => void | Promise<void>, firstCase?: number): Promise<void>;
 export declare function benchmarkTarget(value: string): BenchmarkTarget;
 export declare function hit(app: AuditableApp, test: RequestCase, agent: Agent, target?: BenchmarkTarget): Promise<HitResult>;
 export declare function auditProject(app: AuditableApp, { expectRoutes, log, compliance }?: AuditOptions): Promise<AuditReport>;

package/dist/types/recipes.d.ts

@@ -20,7 +20,7 @@ export interface RecipeSearchResult {
         matched: string[];
     })[];
 }
-export declare const recipeNames: readonly ["redirect", "json-api", "typescript", "middleware", "health-page", "static-plus-api", "cors-api", "webhook-receiver", "contact-form", "authenticated-json-api", "protected-download"];
+export declare const recipeNames: readonly ["redirect", "json-api", "typescript", "middleware", "health-page", "static-page", "static-plus-api", "cors-api", "webhook-receiver", "contact-form", "authenticated-json-api", "protected-download", "store-crud"];
 export declare function listRecipes(): Promise<RecipeSummary[]>;
 /** Matches id, description, tags and capabilities locally; no service is consulted. */
 export declare function searchRecipes(text: string): Promise<RecipeSearchResult>;

package/dist/types/runtime.d.ts

@@ -34,6 +34,10 @@ export interface RuntimeOptions {
      * whole project denies every binding it grants. Prerendering uses it to render a
      * project too large for one function snapshot in passes (docs/PRERENDER.md). */
     only?: readonly string[] | undefined;
+    /** Test harness only (set by `startServer` when it is given a data directory): also grant every
+     * route's `{env: URLCODE_DATA_DIR}` binding, and only that name, for this project revision. The value
+     * is the harness's own directory, not an ambient secret. Never supplied by project YAML or guest code. */
+    grantDataDir?: boolean | undefined;
 }
 /** Per-request facts the host may read after handle() settles; never request text. */
 export interface RequestTrace {

package/dist/types/server.d.ts

@@ -16,6 +16,12 @@ export interface ServerOptions extends Omit<RuntimeOptions, 'observers'> {
     observers?: Observer[] | undefined;
     metrics?: boolean | undefined;
     metricsIntervalMs?: 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. */
+    dataDir?: string | undefined;
+    /** Test helper. Create a fresh empty data directory, offer it as `URLCODE_DATA_DIR`, and remove it on `close()`. Exclusive with `dataDir`. */
+    isolateData?: boolean | undefined;
 }
 export interface Server {
     server: http.Server;
@@ -31,4 +37,6 @@ export interface Server {
     origin: string;
     close(): Promise<void>;
 }
-export declare function startServer({ project, host, port, watch, local, log, maxBodyBytes, maxInFlightRequests, maxInFlightHealthRequests, requestLog, trustRequestId, origin, trustedProxies, observers, metrics, metricsIntervalMs, ...runtimeOptions }?: ServerOptions): Promise<Server>;
+/** Starts the server. `port: 0` picks a free port, so this is also the in-process helper for tests:
+ * `startServer({ project, port: 0, local: true, isolateData: true })`. */
+export declare function startServer(options?: ServerOptions): Promise<Server>;

package/dist/types/tooling.d.ts

@@ -94,6 +94,7 @@ export interface ExtensionInspection {
         schema: object;
         policySchema: object | null;
         hooks: object[];
+        authoring: object | null;
         declared: boolean;
         revisionPinned: boolean;
         mounts: string[];

package/dist/types/types.d.ts

@@ -113,6 +113,7 @@ export interface SiteConfig {
     favicon?: string;
     securityTxt?: SecurityTxtConfig;
     llms?: string;
+    notFound?: string;
 }
 /** One route as declared in YAML (plus `generated`, which site.ts stamps on the routes it adds). */
 export interface ConditionalReply {
@@ -169,6 +170,8 @@ export interface RouteConfig {
      * Never inferred or enforced: the trust decision remains the author's judgment call
      * (docs/AI-AUTHORING.md, "Deciding when a route needs sandbox: true"). */
     sandboxReason?: string;
+    /** Per-method `audit` coverage waiver: method to a non-empty reason. Project file only (docs/READINESS.md). */
+    coveredElsewhere?: Record<string, string>;
     parameters?: ParameterConfig[];
     redirect?: RedirectConfig;
     function?: FunctionConfig;
@@ -186,9 +189,16 @@ export interface RouteConfig {
     respond?: RespondSpec;
     middleware?: MiddlewareConfig[];
     policies?: PoliciesConfig;
+    /** Name of a top-level `shared` block; expanded away at load time, so nothing downstream sees it. */
+    use?: string;
     /** Set by site.ts on a route it generated (`site.<key>`); never declared in YAML. */
     generated?: string;
 }
+/** A named, reusable `request` and `response.headers` block a route selects with `use`. */
+export interface SharedBlock {
+    request?: RouteConfig['request'];
+    response?: RouteConfig['response'];
+}
 export interface ProjectDocument {
     version: '1';
     extensions?: Record<string, ExtensionDeclaration>;
@@ -196,6 +206,7 @@ export interface ProjectDocument {
     includes?: string[];
     policies?: PoliciesConfig;
     profiles?: Record<string, PolicyLayer>;
+    shared?: Record<string, SharedBlock>;
     site?: SiteConfig;
 }
 /** What config.ts returns: the entry document, the merged route table and the files it came from. */
@@ -394,6 +405,8 @@ export interface PlanInventoryEntry {
     sandbox?: boolean;
     /** The route's declared `sandboxReason`, when it has one. */
     sandboxReason?: string;
+    /** The route's declared `coveredElsewhere` audit waivers (method to reason), when it has any. */
+    coveredElsewhere?: Record<string, string>;
 }
 export interface TestPlan {
     inventory: PlanInventoryEntry[];

package/dist/types.js

@@ -55,7 +55,7 @@
                                                                                     
                                                                              
  
-                                                                                                                                                       
+                                                                                                                                                                          
 /** One route as declared in YAML (plus `generated`, which site.ts stamps on the routes it adds). */
                                                                                       
                                                                                                                        
@@ -83,17 +83,23 @@
                                                                                       
                                                                             
                          
+                                                                                                                 
+                                            
                                                                                        
                                                                             
                                                                       
                                                                                                      
                                                                                     
+                                                                                                       
+               
                                                                                        
                      
  
+/** A named, reusable `request` and `response.headers` block a route selects with `use`. */
+                                                                                                     
                                   
                                                                                                                           
-                                                                                       
+                                                                                                                             
  
 /** What config.ts returns: the entry document, the merged route table and the files it came from. */
                                                                                                                                                   
@@ -209,6 +215,8 @@
                     
                                                                
                          
+                                                                                                   
+                                            
  
                            
                                                                                                 

package/dist/typescript-authoring.js

@@ -7,7 +7,7 @@ import {stringify} from 'yaml';
 import {loadDocument} from './config.js';
 import {collectFunctionSources,routeFunctions} from './function-sources.js';
 import {authoringPath,authoringFile,readAuthoringFile,publishAuthoringProject} from './authoring-files.js';
-import {assert} from './errors.js';
+import {assert,ConfigError} from './errors.js';
 
                                                                                                                                   
 const emitted=(path        )=>path.replace(/\.ts$/,'.js');
@@ -22,7 +22,9 @@ const SANDBOX_MODULE_LIMIT=128,SANDBOX_MODULE_BYTE_LIMIT=1048576,SANDBOX_TOTAL_B
  * plugins, package resolution, subprocesses or guest code execution are used. */
 export async function buildTypeScriptProject(project        ,output        ,{dryRun=false}                              ={})                                 {
   const root=await realpath(project),loaded=await loadDocument(root),files=new Map                      (),modules=new Map               ();
-  const {default:ts}=await import('typescript');
+  const ts=await import('typescript').then(module=>module.default).catch(()=>{
+    throw new ConfigError('TypeScript authoring requires the optional typescript package (npm install --save-dev --save-exact typescript@6.0.3)');
+  });
   // Which trust levels a module has already been visited under, so a graph
   // reachable from both a sandboxed and a trusted route is validated under each
   // route's own rules exactly once instead of being refused outright. The
@@ -128,7 +130,7 @@ export async function buildTypeScriptProject(project        ,output        ,{dry
     for(const ref of [route.page,route.download])if(ref)await asset(ref.file);
     if(route.static)await directory(route.static.directory);
   }
-  for(const ref of [loaded.document.site?.favicon,loaded.document.site?.llms])if(ref)await asset(ref);
+  for(const ref of [loaded.document.site?.favicon,loaded.document.site?.llms,loaded.document.site?.notFound])if(ref)await asset(ref);
   // Request fixtures describe behavior the emitted project must keep, so they travel with it.
   try{await asset('tests/requests.json');}catch(error){if(!(error instanceof Error && 'code' in error && error.code==='ENOENT'))throw error;}
   // Flatten includes using the loader's duplicate-checked route table. Original

package/dist/verify-deployment.js

@@ -5,7 +5,7 @@ import { randomBytes } from 'node:crypto';
 import { assert } from './errors.js';
 import { createRuntime } from './runtime.js';
                                                    
-import { benchmarkTarget, hit, readCases, probeAgent } from './readiness.js';
+import { benchmarkTarget, hit, readFixtures, runFixtures, isStepsFixture, probeAgent } from './readiness.js';
                                                                                  
 import { runCompliance, severities } from './compliance.js';
                                                                                      
@@ -45,7 +45,7 @@ const CONCURRENCY = 4;
 const MAX_REQUESTS = 10000;
 const BODY_LIMIT = 1048576;
 const SNIPPET = 200;
-const siteTypes                         = { 'site.robots': 'text/plain', 'site.sitemap': 'application/xml', 'site.securityTxt': 'text/plain', 'site.llms': 'text/plain' };
+const siteTypes                         = { 'site.robots': 'text/plain', 'site.sitemap': 'application/xml', 'site.securityTxt': 'text/plain', 'site.llms': 'text/plain', 'site.notFound': 'text/html' };
 const isRecord = (value         )                                   => value !== null && typeof value === 'object' && !Array.isArray(value);
 const snippet = (body        )         => body.length > SNIPPET ? `${body.length} bytes: ${body.subarray(0, SNIPPET).toString('utf8')}` : body.toString('utf8');
 const tlsCode = /CERT|TLS|SSL|SELF_SIGNED/;
@@ -129,12 +129,12 @@ export async function verifyDeployment(project        , { target, origin, expect
   const routes                         = { local: runtime.count, observed: null, expected: expectRoutes ?? null };
   let complianceReport                          = null;
   try {
-    const plan = runtime.testPlan(), fixtures = await readCases(runtime.root, true);
+    const plan = runtime.testPlan(), fixtures = await readFixtures(runtime.root, true);
     const loaded = await loadDocument(runtime.root);
     await applySite(loaded, { origin: publicOrigin, log: () => {} });
-    const cases                = [...plan.cases, ...fixtures];
+    const fixtureRequests = fixtures.reduce((sum, fixture) => sum + (isStepsFixture(fixture) ? fixture.steps.filter(step => !('restart' in step)).length : 1), 0);
     const literal = plan.inventory.filter(route => route.state === 'active' && !route.path.includes('{'));
-    assert(4 + cases.length + literal.length * 4 <= MAX_REQUESTS, `Verification would send more than ${MAX_REQUESTS} requests`);
+    assert(4 + plan.cases.length + fixtureRequests + literal.length * 4 <= MAX_REQUESTS, `Verification would send more than ${MAX_REQUESTS} requests`);
     check(expectRoutes === undefined || plan.inventory.length === expectRoutes, { check: 'probes', severity: 'high', message: 'configured route count differs from --expect-routes', expected: String(expectRoutes), observed: String(plan.inventory.length) });
 
     // 1. Probes. A transport failure on the health probe ends the run: nothing
@@ -162,13 +162,19 @@ export async function verifyDeployment(project        , { target, origin, expect
     // 2. Fixtures and generated cases, exactly as `urlcode test --target`
     // would send them: sequentially, through hit(), against the target.
     const stub               = { address: { address: '127.0.0.1', family: 'IPv4', port: 0 }, root: runtime.root, testPlan: () => plan };
-    for (const [i, test] of cases.entries()) {
-      requests++;
-      const result = await hit(stub, test, agent, destination);
+    // A fixture with a restart step cannot run here: a live deployment is not ours to close and
+    // start. It is skipped as a whole, never partly, and named in the report and the log.
+    const record = (n        , source        , test             , original             , result                                 )       => {
       let route                    ; try { route = plan.resolve(test.path); } catch { /* an invalid-path negative fixture */ }
-      const label = `${i < plan.cases.length ? 'generated' : 'fixture'} case ${i + 1} ${test.method ?? 'GET'} ${test.path}`;
+      // The label prints the fixture as written: a substituted path may hold a captured value.
+      const label = `${source} case ${n} ${original.method ?? 'GET'} ${original.path}`;
       check(result.pass, { check: 'fixtures', severity: 'high', ...(route === undefined ? {} : { route }), message: result.error ? `${label}: ${result.error} error` : `${label}: response did not match the case`, expected: String(test.status), observed: String(result.status) });
-    }
+    };
+    for (const [i, test] of plan.cases.entries()) { requests++; record(i + 1, 'generated', test, test, await hit(stub, test, agent, destination)); }
+    await runFixtures(fixtures, {
+      app: stub, agent, target: destination,
+      skipped: (fixture, reason) => { notes.push(`fixture ${fixture} ${reason}; none of its requests were sent and it was not verified`); log({ event: 'skipped', check: 'fixtures', fixture, reason: 'restart' }); },
+    }, step => { if (step.result.error !== 'skipped' && step.result.error !== 'unresolved') requests++; record(step.case, 'fixture', step.test, step.original, step.result); }, plan.cases.length + 1);
 
     // 3. Declared versus observed, per active literal route.
     await each(literal, async route => {

package/examples/body-validation/README.md

@@ -0,0 +1,16 @@
+# Body validation
+
+Declares the shape of a JSON request body and two input formats in YAML, so a
+route needs no hand-written validation code.
+
+- `request.body.schema` accepts a small JSON Schema subset. A body that breaks it
+  answers **422**; malformed JSON is still 400 and a wrong media type 415.
+- Parameter `format: uuid` and `pattern` reject bad path and query values with 400.
+- `pattern` must set `maxLength` (at most 128) and is refused when it repeats a
+  group, uses lookaround or a backreference, or has more than three unbounded
+  quantifiers. See [HTTP configuration](../../docs/HTTP.md).
+
+The 422 answer is plain text listing only paths the schema declares; it never
+echoes what the client sent. A client that sends `Accept: application/json`
+receives a structured body instead, with each issue's `pointer`, `keyword` and
+expected constraint (never the value); `*/*` and browsers keep the text.

package/examples/body-validation/example.yaml

@@ -0,0 +1,17 @@
+id: body-validation
+description: Declarative JSON body validation with request.body.schema, and parameter format uuid and a bounded pattern, with no validation code.
+tags: [request, body, validation, schema, json, parameters, uuid, pattern, "422"]
+complexity: intermediate
+capabilities: [enabled, methods, parameters, request.body, respond]
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: compatible, static: refused}
+routes: 3
+files: [urlcode.yaml, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - urlcode validate --local --project examples/body-validation
+    - urlcode test --project examples/body-validation
+    - urlcode audit --project examples/body-validation --expect-routes 3
+behavior:
+  - POST /todos with a valid JSON body answers 201; a body that breaks the schema answers 422 with the declared paths that failed; malformed JSON answers 400; a wrong media type answers 415
+  - a path id that is not a uuid, or a slug that does not match the declared pattern, answers 400