@jimhoyd/urlcode 0.4.0-alpha.3 → 0.4.2

package/.claude/skills/urlcode-authoring/SKILL.md

@@ -30,6 +30,11 @@ Start with `urlcode context --project <dir> --budget 4000`, then retrieve the
 capability, schema fragment, recipe or example relevant to the change. Use the
 read-only MCP equivalents when available. `llms.txt` is the index; read the
 matching task guide from `docs/` when a query needs more explanation.
+When the project has an operator host file, inspect `urlcode extensions
+--project <dir> --host-file <absolute-file> --json` (MCP: `get_extensions`)
+before writing extension configuration or project hooks. The report is the
+machine-readable source for config/policy schemas and hook names, purposes and
+input/output schemas.
 `docs/SPECIFICATION.md` and `schemas/urlcode.schema.json` resolve contract
 questions. Archived plans are historical, not valid YAML guidance.
 
@@ -49,6 +54,11 @@ questions. Archived plans are historical, not valid YAML guidance.
 - Create every referenced module, page and asset **before** validating. All
   source paths resolve from the project root. Trusted modules can import Node built-ins and npm packages;
   only `sandbox: true` modules are restricted to the relative snapshotted graph.
+- Customize installed extensions in this order: declarative configuration;
+  `urlcode-ui` copy, theme, template and CSS overrides; a hook declared by the
+  extension; a new extension only when the installed contract cannot express
+  the behavior. Extension hooks run trusted in-process and reject `sandbox:
+  true` in contract v1.
 - Write exact response fixtures for success and failure, covering every active
   method, middleware behavior, HEAD, and any range or cache semantics.
 - Follow `docs/BEST-PRACTICES.md` for layout and readability as the project grows.

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude plugins published from the URLCode repository.",
-    "version": "0.4.0-alpha.3"
+    "version": "0.4.2"
   },
   "plugins": [
     {

package/CONTRIBUTING.md

@@ -79,6 +79,42 @@ A behavior change that a reader depends on is not finished until the matching
 page in `docs/` is updated. Put both in the **same** pull request so review can
 see both halves and neither can land alone.
 
+### Maintain existing pages first
+
+Before creating a page, search the docs and update the existing home for the
+reader's task. A new page needs a distinct purpose and a link from the relevant
+guide or index. Routine task summaries and verification transcripts belong in
+the pull request, not a new permanent report.
+
+Keep each kind of information in its authoritative home:
+
+| Information | Home |
+|---|---|
+| Implemented behavior and accepted fields | Specification, topic contracts and generated schema reference |
+| How to accomplish a task | The existing guide or executable recipe |
+| Current versions and publication state | Manifests and the commands in [version alignment](docs/VERSION-ALIGNMENT.md) |
+| Actionable bugs and proposed work | GitHub issues; the roadmap links to priorities rather than copying task lists |
+| Unresolved design choices | [Open decisions](docs/OPEN-DECISIONS.md), linked to the relevant issue |
+| Security and operational evidence | Dated, scoped evidence records and the readiness register |
+| Completed or superseded plans | [Archive](docs/archive/README.md), with a link to the current owner of any remaining work |
+
+Link to these sources instead of copying changing status or entire explanations.
+Examples and brief task-specific explanations are useful; a second maintained
+version table or backlog is not. Do not treat archiving a plan as closing its
+unperformed security or deployment checks.
+
+When a decision is implemented, update the reader-facing guide and remove its
+obsolete next steps. Preserve useful rationale and evidence with an explicit
+status; do not leave historical proposals presenting themselves as current
+instructions. Avoid moving files only for tidiness: existing links and anchors
+are part of the documentation interface.
+
+Run `npm run check:docs` after documentation changes. It checks local links,
+retired repository references, guidance claims and generated resources. These
+checks cannot prove prose is current: review the affected facts against code
+and evidence too. Reviewers should ask which page owns the changed information
+and whether this PR introduced a competing explanation.
+
 `urlcode-docs` was deleted on 2026-09-19. It held its own copy of most of these
 pages and had drifted from them; the content that was ahead has been brought
 across, and the repository was retired rather than reconciled page by page.

package/README.md

@@ -32,8 +32,10 @@ compiles it once, and refuses anything a target cannot enforce with the route
 named. Functions and middleware run trusted, in-process, with full Node
 access by default; a route opts into an isolated QuickJS/WebAssembly sandbox
 with a fresh heap per call and no Node, filesystem or network by declaring
-`sandbox: true`. Either way, secrets reach them only through operator grants
-pinned to the project revision.
+`sandbox: true`. Either way, the `env`/`secrets` the runtime *hands* a route
+come only from operator grants pinned to the project revision; grants govern
+that injected context, not the ambient Node environment a trusted, in-process
+module can reach on its own like any other code in the host.
 
 URLCode is not a URL shortener: stored short links are an operator-installed
 extension, not core's job. It is not a
@@ -53,16 +55,17 @@ an AI agent must follow are in [the framework](docs/FRAMEWORK.md).
 
 | Package | Adds | Status |
 |---|---|---|
-| [urlcode](https://github.com/jimhoyd-com/urlcode) (this repository) | Runtime, CLI, policies, provider adapters, extension contract | `0.4.0-alpha.2` (alpha) on top of the `0.3.0` release, Apache-2.0 |
-| [urlcode-ui](packages/ui) (in this repository) | Shared presentation: escaped templates, shadcn/ui partials, themes, translations | `0.1.0-alpha.5` on npm, alpha: review pending |
-| [urlcode-auth](packages/auth) (in this repository) | Accounts: password, passkeys, OIDC, email codes, TOTP, sessions, roles, account page | `0.1.0-alpha.3` on npm, alpha: review pending |
-| [urlcode-admin](packages/admin) (in this repository) | Administration: users, sessions, roles, audit, approvals, cases, impersonation | `0.1.0-alpha.3` on npm, alpha: review pending |
-
-Every version in this table is the one published to npm under the `alpha`
-dist-tag, and they are released together in the order core → ui → auth →
-admin. The authoritative cross-repository register, including each
-package's declared peer ranges and the rules that keep them consistent, is
-[docs/VERSION-ALIGNMENT.md](docs/VERSION-ALIGNMENT.md).
+| [urlcode](https://github.com/jimhoyd-com/urlcode) (this repository) | Runtime, CLI, policies, provider adapters, extension contract | `0.4.1` stable release target, Apache-2.0 |
+| [urlcode-ui](packages/ui) (in this repository) | Shared presentation: escaped templates, shadcn/ui partials, themes, translations | `0.4.1` stable release target; review pending |
+| [urlcode-auth](packages/auth) (in this repository) | Accounts: password, passkeys, OIDC, email codes, TOTP, sessions, roles, account page | `0.4.1` stable release target; review pending |
+| [urlcode-admin](packages/admin) (in this repository) | Administration: users, sessions, roles, audit, approvals, cases, impersonation | `0.4.1` stable release target; review pending |
+
+This release aligns all four packages at `0.4.1`, with publication to npm's
+`latest` channel in the order core → ui → auth → admin. The table describes
+the release target; confirm publication with `npm run release:status` before
+installing it. Matching numbers do not establish a permanent fixed-version
+policy. Peer ranges, channel rules and generated application pins are documented
+in [package and channel alignment](docs/VERSION-ALIGNMENT.md).
 
 `urlcode-dynamic-link` and `urlcode-short` were published once as
 `0.1.0-alpha.1` and have since been retired: both were unpublished from npm and
@@ -103,8 +106,9 @@ it. Cross-repository acceptance is tracked in
 
 ## Status
 
-`0.4.0-alpha.2` is the current release of the extension contract and the
-agent tooling, on top of the `0.3.0` self-hosted release. `0.4.0-alpha.1`
+The `0.4.1` release line brings core, UI, auth and admin to matching stable
+versions. A stable version selects the npm `latest` channel; it does not close
+the review and deployment evidence gaps below. `0.4.0-alpha.1`
 added the extension contract, capabilities and provider conformance, strict
 redirect interchange, bulk import, recipes and search, TypeScript guest
 authoring, conditions, bounded proxy and signals, and the MCP read and
@@ -174,7 +178,8 @@ SQLite build requirement, unverified from this repository.
 ## Try it
 
 ```sh
-npm install --global @jimhoyd/urlcode     # or: brew tap jimhoyd-com/urlcode && brew install urlcode
+# After the 0.4.1 release has been published:
+npm install --global @jimhoyd/urlcode@0.4.1
 urlcode init my-urls && cd my-urls
 urlcode dev
 ```

package/ROADMAP.md

@@ -7,12 +7,14 @@ principles; [the specification](docs/SPECIFICATION.md) owns implemented behavior
 
 ## What works now
 
-The source at `db375bf` provides declarative routing, responses, assets, policies,
+The current source provides declarative routing, responses, assets, policies,
 conditions, proxy/signals, trusted Node functions and middleware, and opt-in
 `sandbox: true` isolation. Target support differs: use `urlcode capabilities`
 before promising a deployment. Stored short links have no supported package.
 
-Auth, admin, UI and middleware are separate optional packages. Auth/admin already
+Auth, admin and UI are optional packages, developed in this repository under
+`packages/` and released independently. Middleware is not a package: per-route
+`middleware:` is native to core. Auth/admin already
 render through the shared UI kit when configured. Core includes scaffolding,
 searchable recipes/examples, compact context, schema queries, a semantic manifest,
 and MCP inspection with separately enabled authoring. These are implemented,
@@ -20,14 +22,19 @@ not future phases. See [the framework](docs/FRAMEWORK.md).
 
 ## Next work
 
-Monorepo work is starting now. Move middleware in as a separate package before
-folding it into core; coordinate the guidance cleanup with that migration.
+Auth, admin and UI are workspace packages here, released from this repository;
+the migration is [done](docs/archive/2026-09-20/OPEN-DECISIONS-COMPLETED.md) and
+its plan is [archived](docs/archive/2026-09-19/SPIKE-MONOREPO.md). The separate
+middleware package was withdrawn rather than migrated
+([the decision](docs/OPEN-DECISIONS.md#accepted-middleware-withdrawn-rather-than-consolidated)).
+Versions and channels are in [version alignment](docs/VERSION-ALIGNMENT.md) and
+`npm run release:status`, not in this page.
 
 1. **Make the existing product coherent.** Keep docs, examples, generated LLM
    resources, installed skills and the standalone template consistent with their
    runtime version. Resolve the [open decisions](docs/OPEN-DECISIONS.md).
-   [Issue 168](https://github.com/jimhoyd-com/urlcode/issues/168) tracks checking
-   schema-invalid documentation examples beyond the existing prose checks.
+   Schema-invalid YAML examples in Markdown are now checked
+   (`scripts/check-guidance-claims.ts`; issue 168 is closed).
    [Issue 174](https://github.com/jimhoyd-com/urlcode/issues/174) retains the
    extension-schema retrieval proposal.
 2. **Measure the agent experience.** The benchmark harness and authoring evals
@@ -40,16 +47,18 @@ folding it into core; coordinate the guidance cleanup with that migration.
    independent security review, deployed recovery/soak tests and real provider
    verification remain distinct from source implementation and local tests.
    [Issue 58](https://github.com/jimhoyd-com/urlcode/issues/58) and
-   [release readiness](docs/RELEASE-READINESS.md) retain those gates. Live
-   Google/Apple/SES checks remain explicitly deferred.
-4. **After the monorepo move, consolidate middleware into core.** Move the
-   existing middleware package first, preserving behavior.
-   [issue 172](https://github.com/jimhoyd-com/urlcode/issues/172) tracks the later consolidation
-   and consumer migration; package retirement is not part of the initial move. Static targets continue rejecting
-   request-time middleware.
-5. **Choose expansion from evidence.** Collections, a business application suite,
-   and per-route Lambda compilation are proposals,
-   not available features. Decide scope before implementing them.
+   [release readiness](docs/RELEASE-READINESS.md) retain those gates; a stable
+   release or green CI does not close them. Live Google/Apple/SES checks remain
+   explicitly deferred. [Issue 185](https://github.com/jimhoyd-com/urlcode/issues/185)
+   (CI lane measurement and release-train validation) and
+   [issue 202](https://github.com/jimhoyd-com/urlcode/issues/202) (Windows auth
+   worker startup timeout) are also still open.
+4. **Choose expansion from evidence.** Collections and a business application
+   suite are proposals, not available features. Decide scope before implementing
+   them. Per-route Lambda compilation is **decided against**: projects using
+   `function` or `middleware` deploy as one trusted Node process, and serverless
+   targets keep refusing those routes at activation
+   ([the decision](docs/OPEN-DECISIONS.md#accepted-one-node-deployment-per-project)).
 
 ## Records and ownership
 

package/dist/BUILD-MANIFEST.json

@@ -6,15 +6,15 @@
     "dist/agents-guide.js": "0b19909aee3f8a1039c34c43ff58116ec1bc3f1875e3dbc34b3b01655273201c",
     "dist/assets.js": "0833b093d2fe457ce68281110dc07d47914992753607741c13b339d92c76cf5c",
     "dist/authoring-files.js": "ad32814f9ae9c549c6247396f982aa700d13a293cc0a589609eccc68f8965550",
-    "dist/authoring.js": "ec5240e8686c124f4601229b45f89ce112d9eeb9d35e3059fe55e93056c45209",
+    "dist/authoring.js": "5fe1e871ff216ef1f7d2f490f74397b81b1de4edfe31cdb6115907296aa1c652",
     "dist/aws.js": "7d8e3a97b4f6dbefbd68da058f05192469d1efcaed5458b284863ebe462e060e",
     "dist/build-cloudflare.js": "af4f49ad45287d7c4105bb84b1592b5b8e76c930f7159505338298f7c5fd5651",
     "dist/build-static.js": "fe01ef4fcc66d83d8be7a787538b55974e84fd3d7c89e26f0a2f1a152762d565",
     "dist/bulk.js": "aac88d422bd9a7a341a421fb4e29ff5580b28d39250b7f1f5315ba20ae92da8a",
     "dist/capabilities.js": "28dba05b3851b8b12b3c1b809af87b732f84d601c737afe9225abe429886e691",
-    "dist/capability-query.js": "ba148b27c6a60f8c895f13f26468b16c18ae0a5cddea26b602965c8efbba90ae",
-    "dist/catalog.js": "ab1c01c9296cc277d2bd4fd682aeb053656a7d9f91c61974f4b78feea0211de8",
-    "dist/cli.js": "ff3e583bd43044bdc06122e33c6137f400f677967ebff1ab49900b517682531c",
+    "dist/capability-query.js": "9f68bc94901451d7b9ecdd3aee8c3376dca7f0b890e31d8205306cf8120dea86",
+    "dist/catalog.js": "c378ef9bfd63b940790f6975f7db54557c2459722b65a7c170b97df24184bc52",
+    "dist/cli.js": "76d3741fa476ff20c9dae2daff56bc5c51701c7fdd61ac924ed0f3e2809928ca",
     "dist/client-address.js": "9d0d01466aab23124330605c5a0e0f981f87c897858acfad909f546a63df165b",
     "dist/cloudflare.js": "17b43b0a6b6a0ef8a893415c989e4ae3976d97cc966adbf897b785f9adc472e3",
     "dist/compliance-rules/baseline.js": "6296dea6bcb9f9bb80ed6ed5ab2f456e7f74e6de2be5d2d98ca8c983fb4df3ab",
@@ -24,58 +24,59 @@
     "dist/compliance.js": "29a18da3cefea94802ac7d817d1ab4e3674abd5c3ac4ef893cb8b01c6a23fb61",
     "dist/conditions.js": "ff25e97da550a3bdd80af55522045669438aa31a77d2bc83ad602bcefdee0475",
     "dist/config-worker.js": "bc2170d60c35f8d5de227cbfc4c5067dc61d7cbc5b98aed88e68a11797072da5",
-    "dist/config.js": "0cd82b4c407848f9c66e804a6dd4bf9a8a8503264e51584456578073e0f01921",
+    "dist/config.js": "8a0fde242b4658c522031a15d89daed25f8b77761f5c4204f295d5e311ac8ff7",
     "dist/context.js": "549a53e4738b9c20a1ec55614027f758026fb5860bf4ac962ce22d7029e48df0",
     "dist/ecosystem-cli.js": "1e71bacd53d6fa8c7857cfcce3c3012ce054771a434b78d1f39e892e32642edd",
     "dist/egress.js": "2ae29fe2cb4590fd2f715abe6817db47fed2f50dd31f37946ecf42eafbb0dd9e",
     "dist/errors.js": "a908e66496afebbdd632a8c159a6e14d23f8f38798a0b4342ca122f2511c6cde",
     "dist/examples.js": "89ae2b764a688fe52acfb9b94d3d262d7742401ebd0ef10c9ebfc76edfa5631c",
     "dist/explain-cli.js": "f0f8f3b5046430d03c6abb629b38651c9c734b03456040735ce9d7e582b2bcd5",
-    "dist/explain.js": "dff1ed9a1bd818906ea867f4fb6d4601397943f9bdc4fceccf1809a365f95168",
-    "dist/extensions.js": "0506ec6289fa0582399d8c6d27727ffeb629bd442264248c921c63cc5b46ff01",
+    "dist/explain.js": "7fb632036cc68280701dd512c74d27d6e0f97b4848e9024b284d7c5393b35eb5",
+    "dist/extensions.js": "07ae8888a5944372ee452b58fb0b6de226b0bc6ed73c5d5a198c1788e1a55fd6",
     "dist/function-sources.js": "16fad4abc81c7ee07b6cbcef2d23a9fc50e97a17cb4dde1db53469bbb555c96f",
     "dist/function-worker.js": "35771790ada4e1b36d447d4967a5e6cf0b543f32944e4c904f5fbf8998e824a5",
     "dist/functions.js": "0f09d1bd27eb655ceb5900a4a5e2b760d2028b02cb637a6a89a4eb5940828008",
     "dist/guest-api.js": "49aec9ed72733ad119e63bcfcee18158dcc8ceb951e1823b8947f6407ff24afc",
     "dist/header-validation.js": "465181dbb08ff05f52defdd29fda025c0c64589bf319fa87fa6d3ab4b68216d5",
     "dist/http-policy.js": "4cb187642269078ddf3460a3f1813dc57878a616a6f8132ef8f8d3b4b91ebb56",
-    "dist/http-response.js": "5fc3bb9eb932a3fd2fbc72c361416a5f1439b8bf45b2be37baca1c6446abf40c",
-    "dist/index.js": "7e9f6ec8a125e2dfd4230b2ecd17ac513c0153d778a57bbcee7a1a9cd9681f81",
-    "dist/init-with.js": "8371f568867ebdc6ab8e9aa762234ae2aa015865f46aa901254528e20d69b791",
+    "dist/http-response.js": "62f5da2e08bfe7ecff07464a49aaf910aa55770308a59118be9372390c2df9a1",
+    "dist/index.js": "8d7532ae0a31f9439ebb62e7b01a2748aee00f350262ff55d1226121d206c1ed",
+    "dist/init-with.js": "bf43b3aa4b421e9a31c5227e6afdf4956aba70d836ffddde96176a772d79e09b",
     "dist/interchange-cli.js": "35bd70ba8077af5c3e39404ff0e5d28707632090a59a90645141252449fd3f04",
     "dist/interchange.js": "26789420af33344d9a08c00fe6b2708aa71994224df527b3075295be2151611e",
     "dist/logging.js": "8ec57fea26983aa071b05fe15d680d6550b03488101163ed9666da674118cf31",
-    "dist/manifest.js": "aa450ff88d44b184ed1ad3331d1f81005a844a9f971e9e12dfa039952839bc75",
+    "dist/manifest.js": "83eed0d59621039ef364cf6e7b54c5bd47e0d8cf0a5abe7b07344bfc1db56ed8",
     "dist/match.js": "53ebcc2cda529a8d07fb83f8cb69a1446036ffc1641af3c4bd45a55851bded28",
-    "dist/mcp-authoring.js": "4987b0ba08999309e07aea1b8bb31f4600cec22d79998e6982e56f765070587a",
-    "dist/mcp.js": "fa44f5f9e0bc4ca9790d1d1eb461147673c1539cf1704a4daae9bad30e4120eb",
+    "dist/mcp-authoring.js": "1183a56c5decb99ecb67a5da7bd91d1b494bc17a2965051aa63c4a7e291462b5",
+    "dist/mcp.js": "4b818de2567ae8fb03adf3e5984931672ee2b469bc7ae9586388552846dae15e",
     "dist/observability.js": "f4b1ab496f051fe3ef2ed36b2b2e469c63a8940700e2df852e6ff2d9cccdd5ae",
     "dist/operator-host.js": "e3dac9d43a83beb775202b4ab9eeeba7ac63cebfc5dcc669be38d825be587bd0",
     "dist/plugins.js": "a61aa933cd9e1b41020b86fae78aa3a7f45f5313124aa11b50cb57898722385e",
     "dist/policies/agents.js": "c1dbc1e90339f472eeeb2372f7f4637f59a5d210797ea680ac8120a02aa20c10",
-    "dist/policies/cache.js": "03f79b91694bb78a98de4473384e5110e1ae1c3c83d46f929495d03af04d9da1",
+    "dist/policies/cache.js": "d08184e50b0ecb7331b29e4145aaefacb23b64ddaf3555d579743762f90c1629",
     "dist/policies/compression.js": "800f3ae3b1a4c1fe58c3d9908364ea9d78f655ff50c7f7589f584378e7f194b0",
     "dist/policies/security.js": "2b3bfdf82140156fea4b162adc28ee43ccd85c402fb200680dbb8d8706417420",
     "dist/policies/throttle.js": "bbb0cb1c24cf70d0a1ac32fc0618efb6c44e5b5d42564842f9c585ff7e501603",
     "dist/policies.js": "3750a7032ec7326aa544f4808683ad9eb91d4f2c5afe79904420cd8a355710a9",
-    "dist/policy.js": "33c527008fafe4af18243ba668d069517c20659150f9f1d1a5a1d076e8724f89",
+    "dist/policy.js": "2da95b3f1f77249b1e9f399a06b88909b68594fdbc958176075e91ff23104a7c",
     "dist/prerender.js": "6210999e848ab86c87f265943960ef63716896da7a40e248221a6a30425c56b8",
+    "dist/project-dependencies.js": "b43a8f3125f62d38f0e71237b7813a785ef0613a83fcdec3fa8314f33758a534",
     "dist/project-tests.js": "445eaa139d2f1a2534369cfdeef081ef518de03218a467e7c5c2059caf840270",
     "dist/provider-verification.js": "ffcf9f05e8cb5f71ea46a97e279e8a613fdfdf9435ab02bd57af11e2680a9107",
     "dist/proxy.js": "34107e59ac0dbbea090efa3cf5badf3226c5302ba25e8f8ff9b2b5596ed80e50",
-    "dist/readiness.js": "90b54bc0cf60dd155d05789a1aad767bd67483d5fa6064ae8b1143f8cf9e06b2",
+    "dist/readiness.js": "28b1ade5addbc3c7427fe6a52b93850001904187c0e03c1552cbb77d8fb8572d",
     "dist/recipes.js": "11853f23e63c3c65c5bed03a278cde0349d28c9fa23266c9907a2df318bb5fc3",
     "dist/route-diff.js": "8d71d50d332ffaaed588656bd32aa36763260d1ad87bb62d7ea1c8fb23383969",
     "dist/router.js": "cf831025d5ed6778d1d6a0e541177799794e76766c82084ded81d3e87317ca1e",
-    "dist/runtime.js": "0470dcab0774d2da3336e9ce76a4853757bf96081e52bd741f6b44c1bdd4161f",
+    "dist/runtime.js": "2346d4630d178ee52caa7a94d4289f9b16f4b8ee467070b39fdd05742ed4513f",
     "dist/sandbox.js": "c88c5aa5dd95b4f55f1ba62da7969ad66dbd97c30f72e5b5f2817a2098ac1c65",
     "dist/scaffold.js": "3ef243aceca7ddf2780aa2c8c04ae17edd07682d3a418fd5d65ba00f5c762f14",
     "dist/schema-query.js": "bfd1844acd8d54ac361115191fcfbaf828a67e223b9ec6e9c22f158761af149b",
     "dist/server.js": "d878bc8f0d6a05f8fd25997cace3150e2ff4d44ee9c8f4b5530e29601e164be1",
     "dist/signals.js": "b55e54efc8fb6703e08f2a1e808ec8e011bda67738db8ceadf1b248f695795be",
     "dist/site.js": "c40a06a6f9e2d6d3bea94727783c115fed4309bb0190787f58434eed64cbde84",
-    "dist/tooling.js": "7409db98422325cd4181d073d645ea57debca0e54cb151123474b85f4d4ed7dc",
-    "dist/trusted-functions.js": "befd256848be786f97e372c6af0e05ac08a0c93baed38bf2470ea49bc00dd3e4",
+    "dist/tooling.js": "191d88eda3bf174f7000fa34995c940f3cf7e9ceafeb4b813e16eb0006767055",
+    "dist/trusted-functions.js": "f3800c75f45ce90faf85ba6664398ad9031c5a9ac51d5ce42bdcff08a497d48e",
     "dist/types.js": "2fe7664dbb5695ec72114197abde72de4031df9c3b211740eacefa68e9b21844",
     "dist/typescript-authoring.js": "2e98498a15bdbb76f36fbee84afb7c42ca95bbf80a2e6dd4040147f3b1642a29",
     "dist/vercel.js": "a0da20c095d0c7fa8f579ed4dd5951e7a34191f8a72a57c5e782c9eab39f6f08",

package/dist/authoring.js

@@ -8,9 +8,18 @@ import { renderAgentsGuide, renderMcpConfig, mcpConfigFile } from './agents-guid
 import { compileRoutes } from './router.js';
 import { prepareFunctionSnapshot, requestedPermissions } from './policy.js';
 import { assert } from './errors.js';
+import { renderPackageManifest } from './project-dependencies.js';
+                                                               
                                                  
 
-export async function initProject(destination        )                  {
+                              
+     
+                                                                                                             
+                                                                                                            
+     
+                                       
+ 
+export async function initProject(destination        , { manifest }              = {})                  {
   const target = resolve(destination);
   await mkdir(dirname(target), { recursive: true });
   // Reserve destination before copying; never merge into existing user files.
@@ -30,6 +39,11 @@ export async function initProject(destination        )                  {
     // .mcp.json registers the read-only server for repository-aware agents; the starter carries the same bytes.
     const mcp = await open(join(target,mcpConfigFile), 'wx', 0o644);
     try { await mcp.writeFile(renderMcpConfig('.')); } finally { await mcp.close(); }
+    if (manifest) {
+      // Exclusive create: the starter ships no package.json, so this never merges into or overwrites one.
+      const pkg = await open(join(target,'package.json'), 'wx', 0o644);
+      try { await pkg.writeFile(renderPackageManifest(target, manifest)); } finally { await pkg.close(); }
+    }
   } catch (error) { await rm(target, { recursive: true, force: true }); throw error; }
   return target;
 }

package/dist/capability-query.js

@@ -44,7 +44,6 @@ function usage(base       ,files         ,name               )
   }
   return result;
 }
-export function capabilityNameList()                           {return capabilityNames;}
 /** One catalog entry with its schema fragments and bundled usage. No project, credentials or network are read. */
 export function getCapability(name       )                 {
   if(typeof name!=='string'||!(capabilityNames                     ).includes(name))throw new ConfigError('Unknown capability; valid names: '+capabilityNames.join(', '));

package/dist/catalog.js

@@ -36,7 +36,6 @@ async function validate()                     {
   }
   return validator;
 }
-export const metadataFiles={recipe:'recipe.yaml',example:'example.yaml'}         ;
 /** Reads and schema-validates one metadata file; the id must equal the directory name, and file lists stay authoring-safe paths. */
 export async function readMetadata(root        ,id        ,file                              )                           {
   const text=(await readAuthoringFile(root,file,65536)).toString('utf8');

package/dist/cli.js

@@ -14,6 +14,7 @@ import { startServer } from './server.js';
 import {scaffoldProject} from './scaffold.js';
 import { initProject, addRedirect } from './authoring.js';
 import { initProjectWith, parseWithNames } from './init-with.js';
+import { collectDependencySet, installSteps, parsePin } from './project-dependencies.js';
 import { runProjectTests } from './project-tests.js';
 import { verifyDeployment, failLevels } from './verify-deployment.js';
                                                      
@@ -27,8 +28,11 @@ import { loadComplianceRules, profileNames as complianceProfiles } from './compl
 import { parseRouteSnapshot, diffRoutes, renderRouteDiff } from './route-diff.js';
 import { readFile } from 'node:fs/promises';
 
-const usage = `URLCode 0.4.0-alpha.3 — local/self-hosted runtime
-  urlcode init <directory> [--with auth,admin]  # --with: layered site from installed @jimhoyd/urlcode-<name> packages
+const usage = `URLCode 0.4.2 — local/self-hosted runtime
+  urlcode init <directory> [--with ui,auth,admin] [--manifest|--no-manifest] [--pin @scope/pkg=specifier]
+    # --with: layered site from installed @jimhoyd/urlcode-<name> packages, with a package.json pinning them exactly; name ui first
+    # --manifest: also pin the runtime for a route-only project; --no-manifest: --with without a package.json
+    # --pin: record a local path or tarball instead of the registry version; repeatable. No install is ever run for you.
   urlcode scaffold [--project directory] [--dry-run]
   urlcode validate [--project directory] [--local] [--origin https://links.example]  # origin: absolute URLs in site.* files
   urlcode dev [--project directory] [--port 3000] [--host 127.0.0.1]
@@ -80,6 +84,7 @@ const print = (value         )          => process.stdout.write(typeof value ===
 const options = {
   json:{ type:'boolean' }, yaml:{ type:'boolean' }, report:{type:'string'}, 'accept-provider-differences':{type:'boolean'},
   project:{ type:'string', default:'.' }, 'host-file':{type:'string'}, with:{type:'string'},
+  manifest:{type:'boolean'}, 'no-manifest':{type:'boolean'}, pin:{type:'string', multiple:true},
   port:{ type:'string' }, host:{ type:'string', default:'127.0.0.1' },
   'expect-routes':{type:'string'}, requests:{type:'string'}, concurrency:{type:'string'}, seconds:{type:'string'}, 'max-p95-ms':{type:'string'}, warmup:{type:'string'}, target:{type:'string'},
   workers:{type:'string'}, 'function-timeout-ms':{type:'string'}, 'max-response-bytes':{type:'string'}, 'max-body-bytes':{type:'string'},
@@ -130,6 +135,7 @@ function formatExtensions(report                     )         {
   if (!report.declared.length) lines.push('Declared: (none)');
   for (const item of report.extensions) lines.push(`Registered: ${item.name} (contract ${item.version}; targets ${item.targets.join(', ') || '(none)'}; ${item.declared ? 'declared' : 'not declared'}; revision ${item.revisionPinned ? 'pinned' : 'NOT pinned'})`,
     `  mounts: ${item.mounts.join(', ') || '(none)'}`, `  policy routes: ${item.policyRoutes.join(', ') || '(none)'}`, `  credential headers: ${item.credentialHeaders.join(', ') || '(none)'}`,
+    `  hooks: ${item.hooks.length ? item.hooks.map(hook => `${String((hook                   ).name)} (${String((hook                   ).kind)})`).join(', ') : '(none)'}`,
     `  configuration schema: ${JSON.stringify(item.schema)}`, `  policy schema: ${item.policySchema ? JSON.stringify(item.policySchema) : '(none)'}`);
   lines.push(report.note);
   return lines.join('\n') + '\n';
@@ -149,6 +155,8 @@ try {
       if (command !== 'mcp' && command !== 'context') operatorHost = await loadOperatorHost(values['host-file'], values.project);
     }
     if (values.with !== undefined && command !== 'init') throw new ConfigError('--with is only supported by init');
+    if ((values.manifest || values['no-manifest'] || values.pin !== undefined) && command !== 'init') throw new ConfigError('--manifest/--no-manifest/--pin are only supported by init');
+    if (values.manifest && values['no-manifest']) throw new ConfigError('Use either --manifest or --no-manifest');
     if (values['allow-authoring'] && command !== 'mcp') throw new ConfigError('--allow-authoring is only supported by mcp');
     const hostOptions = { extensions: operatorHost.extensions, plugins: operatorHost.plugins };
     if ((!['import','recipes','recipe','examples','example','bulk-import'].includes(command) && extra.length) || (!['init','add','import','recipes','recipe','examples','example','bulk-import','explain','capabilities','schema'].includes(command) && arg)) throw new ConfigError('Unexpected positional arguments');
@@ -266,14 +274,23 @@ try {
           const loaded = await loadDocument(values.project);
           print(requestedPermissions(loaded,await prepareFunctionSnapshot(loaded))); break;
         }
-        case 'init':
+        case 'init': {
           if (!arg) throw new ConfigError('Provide a new project directory');
-          if (values.with === undefined) { await initProject(arg); print({ event:'created' }); break; }
-          {
-            const created = await initProjectWith(arg, parseWithNames(values.with));
-            print({ event:'created', ...created, review:`Review ${created.project}/urlcode.yaml and pin its revision explicitly (for example PROJECT_SHA256=${created.projectSha256}); re-review after any project change` });
+          // Pins are opt-in for a route-only project (its runtime may be managed elsewhere) and the default for
+          // --with, which has just resolved the very packages the generated site depends on.
+          const wanted = values.with === undefined ? values.manifest === true : !values['no-manifest'];
+          const pins = new Map((values.pin ?? []).map(parsePin));
+          if (pins.size && !wanted) throw new ConfigError('--pin needs a manifest; drop --no-manifest or add --manifest');
+          if (values.with === undefined) {
+            const set = wanted ? await collectDependencySet([], [], { overrides: pins }) : undefined;
+            const created = await initProject(arg, { manifest: set });
+            print(set ? { event:'created', dependencies:set.pins, nextSteps:installSteps(created, set) } : { event:'created' });
+            break;
           }
+          const created = await initProjectWith(arg, parseWithNames(values.with), { manifest: wanted, pins });
+          print({ event:'created', ...created, review:`Review ${created.project}/urlcode.yaml and pin its revision explicitly (for example PROJECT_SHA256=${created.projectSha256}); re-review after any project change` });
           break;
+        }
         case 'validate': {
           const runtime = await createRuntime(values.project, { ...hostOptions, local:values.local, permissions, origin:values.origin });
           print({ event:'valid', routes:runtime.count, version:runtime.version }); await runtime.close(); break;

package/dist/config.js

@@ -74,7 +74,7 @@ function modulePath(pattern        , kind                           , file
  * a route-level `cache` becomes `policies.cache` (refused alongside a direct `policies.cache`).
  * Everything downstream (routes, audit, the compiled table) sees only the long form.
  */
-export function normalizeRoute(pattern        , route                                   )              {
+function normalizeRoute(pattern        , route                                   )              {
   const authored = route                       ;
   const needsFunction = typeof authored.function === 'string';
   const needsMiddleware = authored.middleware?.some(entry => typeof entry === 'string') ?? false;

package/dist/explain.js

@@ -94,7 +94,7 @@ function targetsOf(loaded               ,route              ,options
   }
   return result;
 }
-export function routeState(route              ,now       )            {return route.enabled===false?'disabled':route.expiresAt&&now>=route.expiresAt?'expired':'active';}
+function routeState(route              ,now       )            {return route.enabled===false?'disabled':route.expiresAt&&now>=route.expiresAt?'expired':'active';}
 /** Describe one compiled route. `chain` is the policy chain compiled for it, when the project declares policies. */
 export function explainCompiledRoute(loaded               ,route              ,chain                      ,options               ={})                  {
   const root=loaded.root,declared=loaded.routes[route.pattern];

package/dist/extensions.js

@@ -1,6 +1,8 @@
 import Ajv from 'ajv/dist/2020.js';
+import { randomUUID } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
 import { assert, HttpError } from './errors.js';
-import { loadDocument } from './config.js';
+import { functionFile, loadDocument } from './config.js';
 import { prepareFunctionSnapshot } from './policy.js';
 import { validateHeaderName, validateHeaderValue } from './header-validation.js';
                                                         
@@ -52,9 +54,76 @@ import { validateHeaderName, validateHeaderValue } from './header-validation.js'
  * vary on credentials. Everything else under the mount stays no-store.
  */
                                                            
+                                                                                                                  
+                                                              
+                                                
+/** Machine-readable contract for one project hook an extension exposes. */
+                                        
+              
+                         
+                     
+                     
+                       
+ 
+                                                                                                      
+/** Shared schema for project hook references. Omission means trusted execution. */
+export const extensionHookReferenceSchema={
+  oneOf:[
+    {type:'string',minLength:1,maxLength:1024},
+    {type:'object',additionalProperties:false,required:['source'],properties:{
+      source:{type:'string',minLength:1,maxLength:1024},
+      export:{type:'string',pattern:'^[A-Za-z_][A-Za-z0-9_]*$'},
+      sandbox:{type:'boolean'},
+      sandboxReason:{type:'string',minLength:1,maxLength:512},
+    }},
+  ],
+}         ;
+/** Builds the strict `config.hooks` schema from an extension's declared hook names. */
+export function extensionHooksSchema(contracts                                 )        {
+  return {type:'object',additionalProperties:false,properties:Object.fromEntries(contracts.map(contract=>[contract.name,extensionHookReferenceSchema]))};
+}
+/**
+ * Loads project hooks once per activation. Project hooks are trusted first-party
+ * code by default, matching function/middleware routes. Sandboxed arbitrary-value
+ * hooks are not part of contract v1 and are refused rather than run trusted.
+ */
+export async function loadExtensionHooks                  (config                                           ,contracts                                 ,context                                 )                                  {
+  const known=new Map(contracts.map(contract=>[contract.name,contract]));
+  const hooks                                        =Object.create(null)                                           ;
+  if(config===undefined)return hooks                           ;
+  assert(config&&typeof config==='object'&&!Array.isArray(config),'Extension hooks must be an object');
+  const epoch=randomUUID();
+  for(const [name,raw] of Object.entries(config)){
+    const contract=known.get(name);assert(contract,`Unknown extension hook: ${name}`);
+    assert(typeof raw==='string'||raw&&typeof raw==='object'&&!Array.isArray(raw),`Invalid extension hook: ${name}`);
+    const reference                       =typeof raw==='string'?{source:raw}:raw                          ;
+    if(reference.sandbox===true)throw new Error(`hook ${name}: sandbox: true is not supported for extension hooks; hooks run trusted by default`);
+    const exportName=reference.export??'default';
+    let modulePath       ;
+    try{modulePath=await functionFile(context.root,reference.source);}
+    catch(error){throw new Error(`hook ${name}: failed to load module "${reference.source}"`,{cause:error});}
+    let module                       ;
+    try{module=await import(pathToFileURL(modulePath).href+'?urlcode-extension-hook-epoch='+epoch)                          ;}
+    catch(error){throw new Error(`hook ${name}: failed to load module "${reference.source}"`,{cause:error});}
+    const fn=module[exportName];
+    if(typeof fn!=='function')throw new Error(`hook ${name}: export "${exportName}" in "${reference.source}" is not a function`);
+    const ajv=new Ajv.default({strict:false,allErrors:false});
+    const validateInput=ajv.compile(contract.inputSchema);
+    const validateOutput=contract.outputSchema?ajv.compile(contract.outputSchema):undefined;
+    hooks[name]=(input        )        =>{
+      assert(validateInput(input),`Invalid extension hook input: ${name}`);
+      const validate=(output        )        =>{if(validateOutput)assert(validateOutput(output),`Invalid extension hook output: ${name}`);return output;};
+      const output=(fn                            )(input);
+      return output instanceof Promise?output.then(validate):validate(output);
+    };
+  }
+  return hooks                           ;
+}
                                    
                                                                        
                                                                                                               
+                                                                                 
+                                          
      
                                                                                    
                                                                         
@@ -105,6 +174,7 @@ import { validateHeaderName, validateHeaderValue } from './header-validation.js'
                                                                                                  
                                                                                                                              
 const namePattern=/^[a-z][a-z0-9-]{0,63}$/;
+const hookNamePattern=/^[a-z][A-Za-z0-9]{0,63}$/;
 const cacheHeaders=new Set(['cache-control','cdn-cache-control','vercel-cdn-cache-control','surrogate-control']);
 const segmentPattern=/^[A-Za-z0-9_-][A-Za-z0-9._-]{0,63}$/;
 export const immutableCacheControl='public, max-age=31536000, immutable';
@@ -153,6 +223,13 @@ export function prepareExtensions(document                ,routes
     assert(registration.version==='1'&&typeof registration.activate==='function','Invalid extension version or activation hook');
     assert(Array.isArray(registration.targets)&&registration.targets.every(target=>['node','aws','vercel'].includes(target)),'Extension targets must be node, aws or vercel');
     assert(typeof registration.projectSha256==='string'&&/^[a-f0-9]{64}$/.test(registration.projectSha256),'Extension requires an explicit operator revision pin');
+    const hookNames=new Set        ();
+    for(const hook of registration.hooks??[]){
+      assert(hook&&typeof hook==='object'&&hookNamePattern.test(hook.name)&&!hookNames.has(hook.name),'Invalid extension hook contract');
+      assert(['filter','action'].includes(hook.kind)&&typeof hook.description==='string'&&hook.description.length>=1&&hook.description.length<=512,'Invalid extension hook contract');
+      assert(hook.inputSchema&&typeof hook.inputSchema==='object'&&(!hook.outputSchema||typeof hook.outputSchema==='object'),'Invalid extension hook contract');
+      hookNames.add(hook.name);
+    }
     provided.set(registration.name,registration);
   }
   const declarations=document.extensions??{};

package/dist/http-response.js

@@ -16,7 +16,7 @@ import { HttpError } from './errors.js';
  
 
 // Hop-by-hop and runtime-owned headers a handler must never set on the wire.
-export const forbiddenHeaders = new Set(['connection','keep-alive','transfer-encoding','content-length','upgrade','trailer','proxy-authenticate','proxy-authorization','te']);
+const forbiddenHeaders = new Set(['connection','keep-alive','transfer-encoding','content-length','upgrade','trailer','proxy-authenticate','proxy-authorization','te']);
 
 // One place decides what a URLCode response *is*, independent of how a host
 // delivers it. A Node server writes it to a socket; a Lambda returns it as

package/dist/index.js

@@ -42,4 +42,5 @@ export {scaffoldProject} from './scaffold.js';
                                                                                     
 export {initProject, addRedirect} from './authoring.js';
 export {initProjectWith} from './init-with.js';
+export {collectDependencySet,renderPackageManifest,installSteps} from './project-dependencies.js';