@jimhoyd/urlcode 0.4.7 → 0.4.8

package/dist/site.js

@@ -1,4 +1,4 @@
-import { stat, readdir, lstat } from 'node:fs/promises';
+import { stat, readdir, lstat, readFile } from 'node:fs/promises';
 import { join, extname } from 'node:path';
 import { assert, ConfigError } from './errors.js';
 import { safeFile } from './config.js';
@@ -233,3 +233,21 @@ export async function applySite(loaded                , options              = {
   for (const [path, route] of Object.entries(generated)) loaded.routes[path] = route;
   return generated;
 }
+
+// The Worker has no filesystem and no asset binding, so the one not-found page
+// is read here and carried inline as a respond route at /404.html. The page is
+// bounded and static: no templating, no request data. It is text/html; the
+// artifact is JSON, which does the escaping, and a body that is not valid
+// UTF-8 is refused rather than silently altered.
+export const notFoundInlineLimit = 65536;
+export async function inlineNotFound(loaded                )                   {
+  const site = loaded.document.site, path = generatedPaths.notFound;
+  const route = loaded.routes[path];
+  if (!site?.notFound || route?.generated !== 'site.notFound') return false;
+  const file = await safeFile(loaded.root, route.page?.file);
+  assert((await stat(file)).size <= notFoundInlineLimit, `site.notFound exceeds ${notFoundInlineLimit} bytes; the Cloudflare Worker carries it inline, so keep the page under 64 KiB`);
+  let text        ;
+  try { text = new TextDecoder('utf-8', { fatal: true }).decode(await readFile(file)); } catch { throw new ConfigError('site.notFound must be valid UTF-8 to be carried inline in the Worker'); }
+  loaded.routes[path] = { respond: { text }, response: { headers: { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' } }, description: route.description ?? 'generated by site.notFound', generated: 'site.notFound' };
+  return true;
+}

package/dist/tooling.js

@@ -21,8 +21,8 @@ export {getCapability} from './capability-query.js';
 export {getSchemaFragment,schemaPathNames} from './schema-query.js';
                                                       
 export {listRecipes,showRecipe,searchRecipes,listExamples,searchExamples};
-export {buildContext,renderContext,estimateTokens,documentationTokens} from './context.js';
-                                                                               
+export {buildContext,renderContext,estimateTokens,documentationTokens,buildTaskContext,renderTaskContext,contextTasks} from './context.js';
+                                                                                                                 
                                                                                                                                                  
 /** `extensions` are operator registrations from a host file; explain reports whether each requirement has a provider. Nothing is activated. */
                                                                                                                                      

package/dist/types/cloudflare.d.ts

@@ -39,6 +39,7 @@ export interface Artifact {
     policies?: {
         security: SecurityConfig;
     };
+    notFound?: true;
 }
 export type Validator = (value: unknown) => boolean;
 export type Validators = Record<string, Validator | undefined>;

package/dist/types/context.d.ts

@@ -64,3 +64,47 @@ export declare function renderContext(context: ProjectContext): string;
 export declare function buildContext(project: string, options?: ContextOptions): Promise<ProjectContext>;
 /** Estimated size of the shipped offline documentation bundle, for comparison with an emitted context. */
 export declare function documentationTokens(): Promise<number>;
+/** Tasks `--task` / MCP `get_context` accept. Each is fixed guidance plus the project's own facts for that task. */
+export declare const contextTasks: readonly ["redirects"];
+export type ContextTask = typeof contextTasks[number];
+export interface TaskShape {
+    need: string;
+    support: 'supported' | 'gap';
+    /** Exact YAML to merge into urlcode.yaml (`routes` entries or `site`); absent for a gap. */
+    yaml?: Record<string, unknown>;
+    /** The rule that applies, or the exact validation error a gap produces. */
+    note?: string;
+    /** For a gap: the tested declarative alternative. */
+    workaround?: string;
+}
+/** Established by running `urlcode validate` and `urlcode test` on each shape; test/context.test.ts compiles every `yaml` entry so this cannot drift from the runtime. */
+export declare const redirectShapes: TaskShape[];
+export interface TaskContext {
+    urlcode: string;
+    schema: '1';
+    task: ContextTask;
+    shapes?: TaskShape[];
+    project?: {
+        entry: string;
+        routes: number;
+        redirects: {
+            path: string;
+            status: number;
+            url: string;
+        }[];
+        site: string[];
+    };
+    recipe?: string;
+    commands?: Record<string, string>;
+    omitted?: string[];
+}
+export declare function renderTaskContext(context: TaskContext): string;
+/**
+ * One bounded call for a task: fixed guidance plus this project's facts for that task. Same compiler as buildContext;
+ * a directory without urlcode.yaml still gets the guidance, any other load failure propagates.
+ */
+export declare function buildTaskContext(project: string, task: string, options?: {
+    budget?: number | undefined;
+    hostFile?: string | undefined;
+    projectFlag?: string | undefined;
+}): Promise<TaskContext>;

package/dist/types/extension-artifacts.d.ts

@@ -0,0 +1,74 @@
+/** Offline, declarative extension bundles. These are deliberately not Node packages. */
+export declare const ARTIFACT_REPOSITORY = "jimhoyd-com/urlcode";
+export declare const ARTIFACT_WORKFLOW = "jimhoyd-com/urlcode/.github/workflows/extension-artifacts.yml";
+export interface ArtifactEntry {
+    name: string;
+    version: string;
+    asset: string;
+    sha256: string;
+    kind: 'declarative';
+}
+export interface Catalog {
+    format: 1;
+    tag: string;
+    commit: string;
+    artifacts: ArtifactEntry[];
+    revoked: {
+        sha256: string;
+        reason: string;
+    }[];
+}
+export interface LockedArtifact extends ArtifactEntry {
+    catalog: {
+        tag: string;
+        commit: string;
+    };
+}
+export interface ExtensionLock {
+    format: 1;
+    artifacts: LockedArtifact[];
+}
+/** Parse an untrusted catalog only after its GitHub attestation was verified by the caller. */
+export declare function parseCatalog(bytes: Uint8Array, requestedTag: string): Catalog;
+export declare function extractArtifact(bytes: Uint8Array, entry: ArtifactEntry, destination: string): Promise<void>;
+export declare function readLock(project: string): Promise<ExtensionLock>;
+export declare function writeLock(project: string, lock: ExtensionLock): Promise<void>;
+export declare function cachePath(project: string, sha256: string): string;
+export interface ReleaseAsset {
+    name: string;
+    url: string;
+}
+export interface ArtifactTransport {
+    release(tag: string): Promise<ReleaseAsset[]>;
+    download(url: string): Promise<Uint8Array>;
+    attest(path: string, release: string): Promise<void>;
+}
+/** The default transport accepts only GitHub Release asset URLs and verifies every downloaded subject. */
+export declare const githubTransport: ArtifactTransport;
+export declare function resolveCatalog(release: string, transport?: ArtifactTransport): Promise<{
+    catalog: Catalog;
+    assets: ReleaseAsset[];
+}>;
+export declare function installArtifact(project: string, release: string, artifactName: string, transport?: ArtifactTransport): Promise<ExtensionLock>;
+export declare function inspectArtifacts(project: string): Promise<{
+    lock: ExtensionLock;
+    cached: string[];
+    missing: string[];
+    invalid: string[];
+}>;
+/** Read-only inventory for authoring tools. Paths come from the verified archive, never from an arbitrary filesystem argument. */
+export declare function describeArtifactCache(project: string): Promise<{
+    format: 1;
+    artifacts: (LockedArtifact & {
+        status: 'cached' | 'missing' | 'invalid';
+        files: string[];
+    })[];
+}>;
+/** Return one bounded text/JSON member from a verified cached artifact for MCP/agent consumers. */
+export declare function readArtifactMember(project: string, artifactName: string, path: string): Promise<{
+    format: 1;
+    artifact: LockedArtifact;
+    path: string;
+    mediaType: 'application/json' | 'text/markdown';
+    content: unknown;
+}>;

package/dist/types/index.d.ts

@@ -18,8 +18,8 @@ export { buildTypeScriptProject } from './typescript-authoring.ts';
 export type { TypeScriptBuildReport } from './typescript-authoring.ts';
 export { importBulkProject } from './bulk.ts';
 export type { BulkFormat, BulkFilePlan, BulkImportReport } from './bulk.ts';
-export { inspectProject, validateProject, explainRoute, explainProject, previewImport, previewExport, getCapability, getSchemaFragment, schemaPathNames, inspectExtensions, describeExtensions, buildContext, renderContext, estimateTokens, documentationTokens } from './tooling.ts';
-export type { InspectOptions, RouteExplanation, RouteMiss, ExplainedHandler, ExplainedCache, ExplainedExtensionRequirement, ExtensionProvider, TargetSupport, CapabilityEntry, CapabilityUsage, SchemaFragment, ExtensionInspection, ContextOptions, ProjectContext, ContextSection } from './tooling.ts';
+export { inspectProject, validateProject, explainRoute, explainProject, previewImport, previewExport, getCapability, getSchemaFragment, schemaPathNames, inspectExtensions, describeExtensions, buildContext, renderContext, estimateTokens, documentationTokens, buildTaskContext, renderTaskContext, contextTasks } from './tooling.ts';
+export type { InspectOptions, RouteExplanation, RouteMiss, ExplainedHandler, ExplainedCache, ExplainedExtensionRequirement, ExtensionProvider, TargetSupport, CapabilityEntry, CapabilityUsage, SchemaFragment, ExtensionInspection, ContextOptions, ProjectContext, ContextSection, ContextTask, TaskContext, TaskShape } from './tooling.ts';
 export { buildManifest, renderManifest, MANIFEST_SCHEMA_VERSION } from './manifest.ts';
 export type { Manifest, ManifestRoute, ManifestModule, RecipeProvenance } from './manifest.ts';
 export { serveMcp } from './mcp.ts';

package/dist/types/site.d.ts

@@ -8,4 +8,6 @@ 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/tooling.d.ts

@@ -10,8 +10,8 @@ export type { CapabilityEntry, CapabilityUsage } from './capability-query.ts';
 export { getSchemaFragment, schemaPathNames } from './schema-query.ts';
 export type { SchemaFragment } from './schema-query.ts';
 export { listRecipes, showRecipe, searchRecipes, listExamples, searchExamples };
-export { buildContext, renderContext, estimateTokens, documentationTokens } from './context.ts';
-export type { ContextOptions, ProjectContext, ContextSection } from './context.ts';
+export { buildContext, renderContext, estimateTokens, documentationTokens, buildTaskContext, renderTaskContext, contextTasks } from './context.ts';
+export type { ContextOptions, ProjectContext, ContextSection, ContextTask, TaskContext, TaskShape } from './context.ts';
 export type { RouteExplanation, ExplainedHandler, ExplainedCache, ExplainedExtensionRequirement, ExtensionProvider, TargetSupport } from './explain.ts';
 /** `extensions` are operator registrations from a host file; explain reports whether each requirement has a provider. Nothing is activated. */
 export interface InspectOptions {

package/llms-full.txt

@@ -1,5 +1,5 @@
 <!-- Generated by scripts/build-llms-full.ts (npm run docs:llms). Do not edit; edit the source documents. -->
-<!-- Consolidated URLCode authoring reference: 16 documents, about 57,753 tokens (estimate: characters / 4). -->
+<!-- Consolidated URLCode authoring reference: 16 documents, about 59,492 tokens (estimate: characters / 4). -->
 
 <!-- urlcode-current-version:start -->
 # URLCode
@@ -7,7 +7,7 @@
 > A portable runtime for programmable URL behavior, and the framework that grows
 > from it: routes in YAML, functions and middleware, then accounts, administration and
 > stored links as operator-installed extensions. Stable project format
-> `version: "1"`. Core is Apache-2.0; this revision is `0.4.7`. `function`/`middleware`
+> `version: "1"`. Core is Apache-2.0; this revision is `0.4.8`. `function`/`middleware`
 > routes are trusted by default with `sandbox: true` as the per-route opt-in. The
 > auth, admin and ui extension packages in this repository are versioned at the same
 > revision; confirm what is published with `npm run release:status`.
@@ -199,6 +199,12 @@ and the MCP `get_extensions` tool report those surfaces and their fast checks,
 so people and agents can discover the supported path instead of replacing
 package behavior.
 
+A signed declarative artifact is a separate, optional authoring input, not a
+fifth way to compose executable behavior. A project may lock an attested
+schema/example bundle and expose it through MCP `get_extension_artifacts` and
+`get_extension_artifact`; the npm package and operator host remain the only
+executable extension path. See [signed declarative artifacts](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md#signed-declarative-artifacts).
+
 ```sh
 urlcode serve --project /absolute/site --host-file /absolute/operator/host.mjs --origin https://site.example
 ```
@@ -301,7 +307,10 @@ Make the first retrieval one bounded query: the MCP tool `get_context` when the
 `urlcode capabilities NAME` (MCP `get_capability`) for one capability's limits,
 `get_schema` for one YAML fragment, `urlcode recipes search TEXT`
 (`search_recipes`), `explain` for a route's effective behavior and, when the
-operator supplies a host file, `get_extensions`. Context is a summary with the
+operator supplies a host file, `get_extensions`. If the project has a committed
+`urlcode.extensions.lock.json`, use `get_extension_artifacts` to verify and
+inventory its inert data and `get_extension_artifact` to retrieve only the
+needed schema, example or README. Context is a summary with the
 constraints and exact commands, not a schema dump, and it never hides a
 capability limit: ask `capabilities NAME` before promising a feature.
 
@@ -356,7 +365,15 @@ teaches how to retrieve the minimum reference through `urlcode capabilities`,
 the documentation whole. For a host-composed application, `get_extensions`
 adds each extension's schemas, hooks, supported authoring surfaces and fast
 checks. Agents should use those surfaces before generating replacement package
-behavior. Neither file replaces the schema; both defer to it.
+behavior. A committed artifact lock is a separate offline authoring input:
+`get_extension_artifacts` validates its cache and lists allowlisted files;
+`get_extension_artifact` reads one bounded JSON or Markdown member from its
+verified archive. The CLI fallback is `urlcode extension-artifacts inspect
+--project DIR --json`. An artifact never installs or activates an npm package,
+registers a host extension or grants authority. Agents must not fetch or update
+one unless the user explicitly requests that project change and names the
+immutable `extensions@v…` release. Neither guide nor artifact replaces the
+runtime schema; all defer to the pinned implementation.
 
 Treat core, installed extensions and product UI as one application with
 different owners. Keep auth/admin security and workflow behavior package-owned;
@@ -482,8 +499,21 @@ Before writing a function, check whether a declarative feature already covers th
 need. Security headers are the usual miss: a project that declares nothing sends
 only the runtime's defaults (`nosniff`, `no-store`, a request ID).
 
+Building only redirects? `urlcode context --project DIR --task redirects` (MCP
+`get_context {"task":"redirects"}`) is a bounded, redirect-only call: every row
+below with the exact YAML, the two gaps with their exact validation error, and
+this project's own redirects — cheaper than this table or the recipe catalog.
+
 | I need | Declare | Reference |
 |---|---|---|
+| Fixed redirect (301/302/303/307/308, 302 default) | `redirect: {url, status}` | [redirects](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/redirects.md) |
+| Parameterized path redirect (`/users/{id}` to `/profiles/{id}`) | `{name}` placeholder in `redirect.url` naming a declared path parameter | [redirects](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/redirects.md) |
+| Fixed-depth suffix redirect (`/legacy/a/b` to `/modern/a/b`) | one route per depth, one placeholder per segment | [redirects](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/redirects.md) |
+| Redirect that preserves query keys | `redirect.query.pass` (explicit allowlist) or `query.map` | [redirects](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/redirects.md) |
+| Redirect that keeps the method/body (POST) | `methods` plus `status: 307` or `308` | [redirects](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/redirects.md) |
+| 404 for unmatched paths | `site.notFound` (a project-relative `.html` file) | [site](https://github.com/jimhoyd-com/urlcode/blob/main/docs/SITE.md) |
+| Wildcard/suffix redirect (`/legacy/*` to `/modern/*`, any depth) — **gap** | not expressible; terminal `/*` and `{rest...}` are refused on `redirect` | [open decision](https://github.com/jimhoyd-com/urlcode/blob/main/docs/OPEN-DECISIONS.md) |
+| Host-based, scheme-based or relative-URL redirect — **gap** | not expressible; destination must be a literal absolute `https://host/path` | [open decision](https://github.com/jimhoyd-com/urlcode/blob/main/docs/OPEN-DECISIONS.md) |
 | Security headers (CSP, HSTS, frame and referrer policy) | `policies.security: {headers: oshp}` or `policies.profile: hardened` | [security](https://github.com/jimhoyd-com/urlcode/blob/main/docs/policies/security.md) |
 | Cache headers on a page, download or static mount | `cacheControl`: `no-cache` (default), `no-store`, `public, max-age=3600` or `public, max-age=31536000, immutable`; nothing else validates | [assets](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/assets.md) |
 | A cache strategy on any route | `policies.cache` | [cache](https://github.com/jimhoyd-com/urlcode/blob/main/docs/policies/cache.md) |
@@ -727,7 +757,7 @@ programmatic compatibility analysis and provider verification limits.
 Source: https://github.com/jimhoyd-com/urlcode/blob/main/docs/YAML-GUIDE.md
 
 <!-- urlcode-current-version:start -->
-This guide targets URLCode 0.4.7. Start with the function example below,
+This guide targets URLCode 0.4.8. Start with the function example below,
 then add only the fields your route needs. The authoritative machine-readable
 shape is [JSON Schema](https://github.com/jimhoyd-com/urlcode/blob/main/schemas/urlcode.schema.json); semantic rules are in the
 [specification](https://github.com/jimhoyd-com/urlcode/blob/main/docs/SPECIFICATION.md). Unsupported fields fail validation.
@@ -2551,15 +2581,19 @@ as the not-found page instead. The page answers every unknown URL, so it cannot
 
 `urlcode build --target static` writes it as the object `404.html` (see
 [static hosting](https://github.com/jimhoyd-com/urlcode/blob/main/docs/STATIC.md)); point the host's error document at that key.
-Cloudflare refuses it like any `page` route (no asset binding); the Worker
-has no per-request fallback page, so use the platform's own 404 asset there.
+Cloudflare inlines it: the page is small, singular and static, so the build
+reads it (64 KiB cap, must decode as UTF-8) and carries it in the artifact as a
+`respond` route at `/404.html`, answering the same status, headers and method
+rules as every other target. See [`docs/CLOUDFLARE.md`](https://github.com/jimhoyd-com/urlcode/blob/main/docs/CLOUDFLARE.md#site-notfound-is-inlined).
+`favicon` and `llms` stay refused there like any other `page` route (no asset
+binding).
 
 ### Per-target support
 
-| Target | `robots`, `sitemap`, `securityTxt` (`respond`) | `favicon`, `llms`, `notFound` (`page`) |
-| --- | --- | --- |
-| self-hosted, Vercel, AWS | served | served |
-| Cloudflare | compiled into the artifact (`build --origin` for absolute URLs) | refused at build time like any `page` route: the target has no asset binding; serve them from the platform's static assets |
+| Target | `robots`, `sitemap`, `securityTxt` (`respond`) | `favicon`, `llms` (`page`) | `notFound` |
+| --- | --- | --- | --- |
+| self-hosted, Vercel, AWS | served | served | served |
+| Cloudflare | compiled into the artifact (`build --origin` for absolute URLs) | refused at build time like any `page` route: the target has no asset binding; serve them from the platform's static assets | inlined into the artifact (64 KiB cap, UTF-8) |
 
 ### Not in this release
 
@@ -3218,6 +3252,64 @@ Serving the result is the usual explicit host binding:
 urlcode validate --project app --host-file "$PWD/host.mjs" --origin https://site.example
 ```
 
+### Signed declarative artifacts
+
+Core remains the npm-distributed runtime. The workspace extensions are not an
+alternate npm channel. A release can additionally carry a small, **data-only**
+extension artifact for tooling that understands its declared format. It is not
+a Node module and cannot activate an extension, run a hook, replace a trusted
+operator host, or grant a route any authority.
+
+Install an artifact only from its immutable `extensions@v…` GitHub Release.
+For example, after the first release is published, its inert store configuration
+schema snapshot can be installed with:
+
+```sh
+urlcode extension-artifacts install store-schema --artifact-release extensions@v1.0.0 --project app
+urlcode extension-artifacts update store-schema --artifact-release extensions@v1.1.0 --project app
+urlcode extension-artifacts inspect --project app
+```
+
+The command downloads the signed `extensions-catalog.json`, verifies its
+GitHub attestation against the dedicated artifact workflow in
+`jimhoyd-com/urlcode` and the exact requested tag ref, then verifies the selected
+`.tgz` the same way. Self-hosted-runner attestations are refused. The catalog
+pins its release tag, source commit, filename and SHA-256; a catalog revocation
+refuses installation. `gh` with support for attestation source-ref verification
+is therefore a required local dependency for this command.
+
+The resulting `urlcode.extensions.lock.json` is the reproducibility boundary:
+commit it with the project. Every locked artifact records its own catalog tag
+and source commit, so updating one artifact cannot silently relabel another as
+coming from a newer release. Extracted files live under
+`app/.urlcode/extensions/<sha256>/` and are checked before extraction. Archives
+are size- and file-count-bounded, reject links and traversal, and may contain
+only `extension.json`, JSON configuration/schema data, and an optional README.
+Any JavaScript, package manifest, install hook, native module, or unknown file
+causes refusal. `inspect` re-hashes the cached archive and every extracted file,
+reporting an entry as missing or invalid rather than trusting its directory
+name. Updates are never automatic: review a newer immutable release and run
+`update` explicitly.
+
+Agent tooling can consume a committed lock without gaining write or execution
+authority. MCP `get_extension_artifacts` validates the lock and cache and lists
+the signed member paths; `get_extension_artifact {name, path}` returns one
+verified, bounded JSON or Markdown member directly from the cached archive.
+The CLI fallback is `urlcode extension-artifacts inspect --project app --json`.
+Neither MCP tool performs a network request, installs or updates an artifact,
+loads a host file, or activates code. A missing or modified cache is reported
+as missing/invalid and its contents are not returned.
+
+This does not relax the existing host boundary. `--host-file` is still the only
+way to load trusted operator extension code, and artifact files are never
+imported by `serve`, `validate`, `init --with`, or the runtime.
+
+Artifact versions are independent from npm package versions. The initial
+`store-schema` artifact is a reviewed configuration-schema snapshot and example,
+not the `@jimhoyd/urlcode-store` implementation. Installing it does not install
+or activate that package. Its README names the separate executable and operator
+requirements.
+
 ---
 
 # Composing a site from ui, auth and admin

package/llms.txt

@@ -4,7 +4,7 @@
 > A portable runtime for programmable URL behavior, and the framework that grows
 > from it: routes in YAML, functions and middleware, then accounts, administration and
 > stored links as operator-installed extensions. Stable project format
-> `version: "1"`. Core is Apache-2.0; this revision is `0.4.7`. `function`/`middleware`
+> `version: "1"`. Core is Apache-2.0; this revision is `0.4.8`. `function`/`middleware`
 > routes are trusted by default with `sandbox: true` as the per-route opt-in. The
 > auth, admin and ui extension packages in this repository are versioned at the same
 > revision; confirm what is published with `npm run release:status`.
@@ -18,6 +18,25 @@ grants. Unsupported features fail with the route named; nothing degrades silentl
 Agents that explicitly want the complete consolidated reference in one fetch should read
 [llms-full.txt](llms-full.txt), generated from the documents below (about 50k tokens, estimated).
 
+## Building only redirects? Start here
+
+Run `urlcode context --project DIR --task redirects` (MCP `get_context {"task":"redirects"}`)
+first: one bounded call returning every supported shape below with exact YAML, the
+gaps with their exact validation error, and this project's own redirects — cheaper
+than reading this file or the recipe catalog. `urlcode recipes search redirect` and
+`urlcode recipes show redirect` give a runnable starting project.
+
+| Shape | Supported? | Use |
+|---|---|---|
+| Fixed redirect, any of 301/302/303/307/308 (302 default) | Yes | `redirect: {url, status}` — [redirects](docs/yaml/redirects.md) |
+| Parameterized path (`/users/{id}` to `/profiles/{id}`) | Yes | `{name}` placeholder in `redirect.url`, naming a declared path parameter |
+| Fixed-depth suffix (`/legacy/a/b` to `/modern/a/b`) | Yes, one route per depth | same as above with one placeholder per segment |
+| Query-string preservation | Yes, opt-in only | `redirect.query.pass` (explicit allowlist) / `query.map` |
+| Method-preserving redirect (keep POST body) | Yes | `methods` plus `status: 307` or `308` |
+| 404 for unmatched paths | Yes | `site.notFound` (a project-relative `.html` file) |
+| Wildcard/suffix redirect (`/legacy/*` to `/modern/*`, any depth) | No | terminal `/*` and `{rest...}` are refused on `redirect`; report the gap ([open decision](docs/OPEN-DECISIONS.md)) |
+| Host-based, scheme-based or relative-URL redirect | No | destination must be a literal absolute `https://host/path`; report the gap |
+
 ## Declarative-first default
 
 > Use URLCode's highest-level declarative features whenever possible. Generate custom code only when the framework cannot express the requirement.
@@ -105,6 +124,7 @@ publish or comment on an issue without the user's explicit approval.
 
 ## Extensions (accounts, administration, presentation)
 - [Extensions](docs/EXTENSIONS.md): `extensions.<name>` blocks, mounts, policies, operator registration, the shared trusted hook primitive and its machine-readable hook contracts. UI/auth/admin project hooks run trusted in-process; contract v1 rejects `sandbox: true`.
+- [Signed declarative artifacts](docs/EXTENSIONS.md#signed-declarative-artifacts): project-pinned, attested JSON/Markdown data for offline tooling. MCP `get_extension_artifacts` verifies/inventories a committed lock and `get_extension_artifact` reads one bounded member; neither installs or activates an npm extension.
 - [Composing a site](docs/COMPOSING-A-SITE.md): what `urlcode init site --with ui,auth,admin` wires, which `--with` combinations are supported, the presentation override paths under `ui/`, and per-package lifecycle hook input, verdict, timing and failure semantics. Separates declarative configuration, project functions and the TypeScript a new extension needs.
 - [urlcode-auth](packages/auth): npm: @jimhoyd/urlcode-auth; accounts, sessions, MFA, roles, account page; its own llms.txt. Lives in this repository as a workspace package.
 - [urlcode-admin](packages/admin): npm: @jimhoyd/urlcode-admin; users, sessions, roles, audit, cases; its own llms.txt. Lives in this repository as a workspace package.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jimhoyd/urlcode",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "description": "Portable runtime for programmable URL behavior",
   "type": "module",
   "workspaces": [
@@ -89,7 +89,8 @@
     "test": "node --conditions=development --test test/*.test.ts",
     "lint": "eslint .",
     "check": "npm run check:code && npm run check:docs",
-    "check:code": "node scripts/check.ts && node scripts/check-release-tags.ts && node scripts/check-workspace-links.ts && npm run release:check",
+    "check:code": "node scripts/check.ts && node scripts/check-release-tags.ts && node scripts/check-workspace-links.ts && node scripts/check-issue-labels.ts && npm run release:check",
+    "test:workerd": "node scripts/workerd-parity.ts",
     "verify": "npm run lint && npm run typecheck && npm run check && npm run build && npm test && npm run verify:workspaces",
     "workspace:styles": "npm run styles --workspace @jimhoyd/urlcode-ui",
     "verify:workspaces": "npm run verify --workspace @jimhoyd/urlcode-ui && npm run verify --workspace @jimhoyd/urlcode-auth && npm run verify --workspace @jimhoyd/urlcode-admin && npm run verify --workspace @jimhoyd/urlcode-store && npm run audit:packages && npm run test:workspace-integration",
@@ -108,6 +109,7 @@
     "docs:plugin": "node scripts/generate-claude-plugin.ts",
     "docs:llms": "node scripts/build-llms-full.ts",
     "docs:cookbook-index": "node scripts/build-cookbook-index.ts",
+    "artifacts:prepare": "node --disable-warning=ExperimentalWarning scripts/prepare-extension-artifacts.ts",
     "check:downstream-skills": "node scripts/check-downstream-skill-drift.ts",
     "sync:agents": "node scripts/sync-agent-lists.ts",
     "check:docs": "node scripts/check-trust-model-prose.ts && node scripts/check-version-statements.ts && node scripts/check-local-links.ts && node scripts/check-guidance-claims.ts && node scripts/generate-yaml-reference.ts --check && node scripts/build-llms-full.ts --check && node scripts/build-cookbook-index.ts --check && node scripts/generate-claude-plugin.ts --check",
@@ -119,6 +121,7 @@
     "release:run": "node scripts/release-run.ts",
     "release:peers": "node scripts/release.ts peers",
     "release:check": "node scripts/release.ts check && node scripts/release-prepare.ts --check",
+    "rehearse:release": "node --conditions=development --test test/release-rehearsal.test.ts",
     "ci:history": "node scripts/ci-history.ts",
     "ci:report": "node scripts/ci-report.ts",
     "test:workspace-integration": "node --test test/workspace-scaffold.integration.ts",

package/recipes/redirect/README.md

@@ -1,7 +1,21 @@
-# Permanent documentation redirect
+# Redirects: fixed, parameterized, query-preserving and 404
 
 Run `urlcode validate --local --project .` and `urlcode serve --project .`.
-`/docs?campaign=launch&private=discarded` redirects to
-`https://example.com/documentation?campaign=launch` with status 301.
-Replace the example destination before deploying. Incoming query parameters are
-not forwarded unless explicitly allowlisted.
+
+- `/docs?campaign=launch&private=discarded` redirects (301) to
+  `https://example.com/documentation?campaign=launch`. Only the declared
+  `campaign` key is forwarded; everything else, including `private`, is
+  dropped. Replace the example destination before deploying.
+- `/users/{id}` redirects (308, method- and body-preserving) to
+  `https://example.com/profiles/{id}`, substituting the declared path
+  parameter into the destination.
+- Any other path, such as `/missing` or `/users/42/extra`, answers the
+  runtime's default 404. `DELETE /docs` answers 405 (only GET/HEAD match by
+  default). Add top-level `site: {notFound: 404.html}` for a custom 404 page
+  instead of the plain default.
+
+For the shapes this recipe does not cover — a wildcard/suffix redirect that
+matches any depth (`/legacy/*`), or a host/scheme-based redirect — run
+`urlcode context --project . --task redirects` (MCP `get_context
+{"task":"redirects"}`) for the exact supported alternative and the exact
+validation error, or see [docs/OPEN-DECISIONS.md](../../docs/OPEN-DECISIONS.md).

package/recipes/redirect/recipe.yaml

@@ -1,25 +1,27 @@
 id: redirect
-description: Permanent redirect that forwards only an allowlisted query key.
-tags: [redirect, permanent, "301", query, passthrough, documentation, native]
+description: Fixed, parameterized and query-preserving redirects, and the default 404 for everything else.
+tags: [redirect, permanent, "301", "308", parameterized, query, passthrough, "404", documentation, native]
 complexity: starter
-capabilities: [enabled, methods, redirect]
-targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: compatible, static: compatible}
-routes: 1
+capabilities: [enabled, methods, parameters, redirect]
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: compatible, static: refused}
+routes: 2
 inputs:
   - name: destination
     file: urlcode.yaml
-    description: Replace https://example.com/documentation with the real target.
+    description: Replace https://example.com/documentation and https://example.com/profiles with the real targets.
   - name: query.pass
     file: urlcode.yaml
-    description: The query keys forwarded to the destination; everything else is dropped.
+    description: The query keys forwarded to the /docs destination; everything else is dropped.
 files: [urlcode.yaml, tests/requests.json, README.md]
 tests:
   fixtures: tests/requests.json
   commands:
     - urlcode validate --local --project .
     - urlcode test --project .
-    - urlcode audit --project . --expect-routes 1
+    - urlcode audit --project . --expect-routes 2
 behavior:
   - GET /docs?campaign=launch&private=x answers 301 to https://example.com/documentation?campaign=launch
-  - HEAD answers the same status with an empty body
-  - unknown paths answer 404
+  - HEAD /docs answers the same status with an empty body
+  - DELETE /docs answers 405
+  - GET /users/42 answers 308 (method- and body-preserving) to https://example.com/profiles/42
+  - unknown paths, including /users/42/extra and /missing, answer the runtime's default 404

package/recipes/redirect/tests/requests.json

@@ -12,8 +12,30 @@
     "status": 301,
     "expectBody": ""
   },
+  {
+    "path": "/users/42",
+    "status": 308,
+    "expectHeaders": {
+      "location": "https://example.com/profiles/42"
+    }
+  },
+  {
+    "path": "/users/42/extra",
+    "status": 404
+  },
+  {
+    "path": "/users/42",
+    "method": "HEAD",
+    "status": 308,
+    "expectBody": ""
+  },
   {
     "path": "/missing",
     "status": 404
+  },
+  {
+    "path": "/docs",
+    "method": "DELETE",
+    "status": 405
   }
 ]

package/recipes/redirect/urlcode.yaml

@@ -1,9 +1,19 @@
 version: "1"
 routes:
   /docs:
-    description: Move documentation and preserve only the declared campaign key.
+    description: Permanent move, forwarding only the declared campaign key.
     redirect:
       url: https://example.com/documentation
       status: 301
       query:
         pass: [campaign]
+  /users/{id}:
+    description: Parameterized redirect; the id segment carries straight through.
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema: {type: string, minLength: 1, maxLength: 64}
+    redirect:
+      url: https://example.com/profiles/{id}
+      status: 308

package/skills/urlcode/SKILL.md

@@ -34,6 +34,8 @@ When the MCP server was started with an operator host file, `get_extensions`
 returns installed extension configuration/policy schemas, declared project
 hook contracts, supported authoring surfaces and fast checks. Otherwise use `urlcode extensions --project DIR --host-file
 ABSOLUTE_HOST --json` when the operator has supplied that host file.
+If the project commits `urlcode.extensions.lock.json`, call `get_extension_artifacts`, then `get_extension_artifact` for only the locked schema, example or README needed; without MCP, run `urlcode extension-artifacts inspect --project DIR --json` before reading its cache.
+These are verified, inert authoring inputs, not proof of an installed executable extension. Fetch or update one only when the user requests that project change and names an immutable `extensions@v…` release.
 Without the server, run the CLI equivalents and read only the output:
 
 ```sh

package/starters/default/AGENTS.md

@@ -22,7 +22,7 @@ static serving and authentication. Read this file before changing anything.
 
 When present, `.mcp.json` registers the read-only `urlcode mcp` server; prefer its
 tools (also `get_manifest`) to reading documents. Inspect `get_extensions` before
-replacing extension behavior. `--allow-authoring` is an operator opt-in; never add it.
+replacing extension behavior. `--allow-authoring` is an operator opt-in; never add it. For a committed artifact lock, use `get_extension_artifacts`/`get_extension_artifact`; they expose verified inert data and never activate an extension.
 
 ## What the runtime provides (this version)