@jimhoyd/urlcode 0.4.0-alpha.3 → 0.4.1

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.1"
   },
   "plugins": [
     {

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

@@ -12,7 +12,9 @@ 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,8 +22,13 @@ 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, and all three have been released
+from this repository; that migration is
+[done](docs/OPEN-DECISIONS.md#done-the-monorepo-migration-is-complete) and its
+plan is [archived](docs/archive/2026-09-19/SPIKE-MONOREPO.md). The separate
+middleware package was withdrawn rather than migrated —
+`@jimhoyd/urlcode-middleware` is unpublished and its repository deleted — so
+there is nothing to move in and nothing to fold into core afterward.
 
 1. **Make the existing product coherent.** Keep docs, examples, generated LLM
    resources, installed skills and the standalone template consistent with their
@@ -42,14 +49,12 @@ folding it into core; coordinate the guidance cleanup with that migration.
    [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.
+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": "45b8adaae66a46e7b05067f1ced488b9dd7ccff8d15ba71e858459d76f5ddbb8",
     "dist/client-address.js": "9d0d01466aab23124330605c5a0e0f981f87c897858acfad909f546a63df165b",
     "dist/cloudflare.js": "17b43b0a6b6a0ef8a893415c989e4ae3976d97cc966adbf897b785f9adc472e3",
     "dist/compliance-rules/baseline.js": "6296dea6bcb9f9bb80ed6ed5ab2f456e7f74e6de2be5d2d98ca8c983fb4df3ab",
@@ -24,14 +24,14 @@
     "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/explain.js": "7fb632036cc68280701dd512c74d27d6e0f97b4848e9024b284d7c5393b35eb5",
     "dist/extensions.js": "0506ec6289fa0582399d8c6d27727ffeb629bd442264248c921c63cc5b46ff01",
     "dist/function-sources.js": "16fad4abc81c7ee07b6cbcef2d23a9fc50e97a17cb4dde1db53469bbb555c96f",
     "dist/function-worker.js": "35771790ada4e1b36d447d4967a5e6cf0b543f32944e4c904f5fbf8998e824a5",
@@ -39,27 +39,28 @@
     "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": "484c03cdf81f94116ec973feb70754298f8b1d5b3b42561969f8cce26b3c97c2",
     "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/prerender.js": "6210999e848ab86c87f265943960ef63716896da7a40e248221a6a30425c56b8",
+    "dist/project-dependencies.js": "b43a8f3125f62d38f0e71237b7813a785ef0613a83fcdec3fa8314f33758a534",
     "dist/project-tests.js": "445eaa139d2f1a2534369cfdeef081ef518de03218a467e7c5c2059caf840270",
     "dist/provider-verification.js": "ffcf9f05e8cb5f71ea46a97e279e8a613fdfdf9435ab02bd57af11e2680a9107",
     "dist/proxy.js": "34107e59ac0dbbea090efa3cf5badf3226c5302ba25e8f8ff9b2b5596ed80e50",
@@ -67,7 +68,7 @@
     "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",
@@ -75,7 +76,7 @@
     "dist/signals.js": "b55e54efc8fb6703e08f2a1e808ec8e011bda67738db8ceadf1b248f695795be",
     "dist/site.js": "c40a06a6f9e2d6d3bea94727783c115fed4309bb0190787f58434eed64cbde84",
     "dist/tooling.js": "7409db98422325cd4181d073d645ea57debca0e54cb151123474b85f4d4ed7dc",
-    "dist/trusted-functions.js": "befd256848be786f97e372c6af0e05ac08a0c93baed38bf2470ea49bc00dd3e4",
+    "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.1 — 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'},
@@ -149,6 +154,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 +273,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/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';
                                                                                    

package/dist/init-with.js

@@ -8,13 +8,21 @@ import { mcpConfigFile, renderMcpConfig } from './agents-guide.js';
 import { loadDocument, parseYaml, validateDocument } from './config.js';
 import { inspectExtensionRevision } from './extensions.js';
                                                                        
+import { collectDependencySet, installSteps, renderPackageManifest } from './project-dependencies.js';
+                                                                              
 import { ConfigError, assert } from './errors.js';
 
 /** Directory names inside the generated site. The route project lives under `app/`; everything else is operator-owned. */
-export const PROJECT_DIRECTORY = 'app', HOST_FILE = 'host.mjs', ROUTES_FILE = 'routes/extensions.yaml';
+const PROJECT_DIRECTORY = 'app', HOST_FILE = 'host.mjs', ROUTES_FILE = 'routes/extensions.yaml';
 const namePattern = /^[a-z][a-z0-9-]{0,63}$/;
-                                                             
-                                                                                                                                                          
+                                  
+                           
+                                                                                                 
+                                 
+                                                                                            
+                                                 
+ 
+                                                                                                                                                                                         
 
 export function parseWithNames(value        )           {
   const names = value.split(',').map(name => name.trim());
@@ -22,7 +30,7 @@ export function parseWithNames(value        )           {
   assert(new Set(names).size === names.length, 'Duplicate --with names');
   return names;
 }
-export const packageName = (name        )         => `@jimhoyd/urlcode-${name}`;
+const packageName = (name        )         => `@jimhoyd/urlcode-${name}`;
 const isCode = (error         , code        )          => error instanceof Error && 'code' in error && error.code === code;
 const strings = (value         )                    => Array.isArray(value) && value.every(item => typeof item === 'string');
 const record = (value         )                                   => value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -32,7 +40,7 @@ const record = (value         )                                   => value !== n
  * conditions), imports it, and calls its `scaffold` export. Nothing is bundled; core never imports these packages
  * at build time. Refuses a missing package or a package without `scaffold` before anything is written.
  */
-export async function loadScaffold(name        , request                 , cwd        )                          {
+async function loadScaffold(name        , request                 , cwd        )                          {
   const pkg = packageName(name);
   let entry        ;
   try { entry = createRequire(join(cwd, 'package.json')).resolve(pkg); }
@@ -68,7 +76,7 @@ async function write(target        , content                     , mode = 0o644)
   const file = await open(target, 'wx', mode);
   try { await file.writeFile(content); await file.sync(); } finally { await file.close(); }
 }
-export function renderHost(names                   , results                           )         {
+function renderHost(names                   , results                           )         {
   const lines = [`// Generated by urlcode init --with ${names.join(',')}. Trusted operator code: keep it outside ${PROJECT_DIRECTORY}/ and review before serving.`];
   for (const result of results) lines.push(...result.hostImports);
   lines.push('');
@@ -85,12 +93,23 @@ function demote(markdown        )         {
   let fence = false;
   return markdown.split('\n').map(line => { if (/^\s*(?:```|~~~)/.test(line)) fence = !fence; return !fence && /^#{1,5} /.test(line) ? `#${line}` : line; }).join('\n');
 }
-export function renderReadme(directory        , names                   , results                           , starter        , env                        , projectSha256        )         {
-  const steps = results.flatMap(result => result.nextSteps);
+function renderDependencySection(directory        , set               )         {
+  const rows = set.pins.map(pin => `- \`${pin.name}\` ${pin.version} (${pin.role})${pin.specifier === pin.version ? '' : ` installed from \`${pin.specifier}\``}`);
+  const lines = ['## Dependencies', '',
+    '`package.json` pins the runtime, every extension named in `--with` and their declared peers to the exact versions that were installed when this site was generated. Those versions were checked against each package\'s own `peerDependencies` as one set.', '',
+    ...rows, '',
+    ...installSteps(directory, set).flatMap(step => [step, '']),
+    set.local ? 'At least one pin is a local path or tarball rather than a registry version: reproducing this install needs that path to exist, so keep it under your control or replace the specifier before publishing the site.' : 'The pins are registry versions; `npm install` resolves them without the network only if your cache or mirror already holds them.', '',
+    'There is no upgrade command. Changing a pinned version today means editing `package.json` yourself and re-running `npm install`; review the extension changelogs first.', ''];
+  return lines.join('\n');
+}
+function renderReadme(directory        , names                   , results                           , starter        , env                        , projectSha256        , set                            )         {
+  const steps = [...(set ? installSteps(directory, set) : []), ...results.flatMap(result => result.nextSteps)];
   const parts = [`# ${basename(directory)}`, '',
     `Created with \`urlcode init ${basename(directory)} --with ${names.join(',')}\`. \`${PROJECT_DIRECTORY}/\` is the route project (\`urlcode.yaml\`, functions, tests); \`${HOST_FILE}\` is the trusted operator host that wires the installed extension packages; operator modules and private data stay outside the project. Run every command with \`--project ${PROJECT_DIRECTORY} --host-file "$PWD/${HOST_FILE}"\`.`, '',
     '## Starter', '', `The starter files live in \`${PROJECT_DIRECTORY}/\`; add \`--project ${PROJECT_DIRECTORY}\` and the host file to the commands below.`, '', demote(starter).trim(), ''];
   for (const result of results) parts.push(`## Extension: ${result.name}`, '', result.readme.trim(), '');
+  if (set) parts.push(renderDependencySection(directory, set));
   parts.push('## Next steps', '', ...steps.map((step, index) => `${index + 1}. ${step}`), '');
   if (Object.keys(env).length) parts.push('## Environment', '', ...Object.entries(env).map(([key, text]) => `- \`${key}\`: ${text}`), '');
   parts.push('## Project revision', '', `\`${PROJECT_DIRECTORY}/urlcode.yaml\` currently has revision \`${projectSha256}\` (\`inspectExtensionRevision\`). Review the project, then pin exactly that value where the host expects it; any change to extension YAML, policies or mounts changes it and needs a new explicit review.`, '');
@@ -102,7 +121,7 @@ export function renderReadme(directory        , names                   , result
  * `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 async function initProjectWith(destination        , names                   , { cwd = process.cwd() }                  = {})                          {
+export async function initProjectWith(destination        , names                   , { cwd = process.cwd(), manifest = true, pins }                  = {})                          {
   assert(names.length > 0, 'Provide at least one --with name');
   const directory = resolve(destination), project = join(directory, PROJECT_DIRECTORY), hostFile = join(directory, HOST_FILE);
   const request                  = { directory, project, hostFile, names };
@@ -120,6 +139,9 @@ export async function initProjectWith(destination        , names
       const seen = new Set        ();
       for (const file of result.files) { const path = filePath(directory, file.path); assert(!seen.has(path), `${result.name} scaffolds ${file.path} twice`); seen.add(path); }
     }
+    // Also resolved before the destination exists: an incompatible or incompletely installed set refuses with
+    // nothing written. It runs after the scaffold conflicts so a composition error is still reported as one.
+    const dependencies = manifest ? await collectDependencySet(names, names.map(packageName), { cwd, ...(pins === undefined ? {} : { overrides: pins }) }) : undefined;
     await mkdir(dirname(directory), { recursive: true });
     await mkdir(directory, { mode: 0o700 }); // refuses an existing destination
     try {
@@ -153,13 +175,16 @@ export async function initProjectWith(destination        , names
         await write(target, file.content, file.mode ?? 0o644); written.add(target);
       }
       await write(hostFile, renderHost(names, results), 0o600);
-      await write(join(directory, 'README.md'), renderReadme(directory, names, results, starter, env, projectSha256));
+      if (dependencies) await write(join(directory, 'package.json'), renderPackageManifest(directory, dependencies));
+      await write(join(directory, 'README.md'), renderReadme(directory, names, results, starter, env, projectSha256, dependencies));
       await write(join(directory, '.gitignore'), 'node_modules/\ndata/\n.env\n.env.*\n');
       // The read-only MCP server for agents opened at the site root; --host-file and --allow-authoring stay operator choices.
       await write(join(directory, mcpConfigFile), renderMcpConfig(PROJECT_DIRECTORY));
       // AGENTS.md: initProject writes the application-level file into app/ once it produces one (NEXT-STEPS 1.1);
       // nothing here overrides it. A site-level agent note would be assembled beside README.md at this point.
-      return { directory, project, hostFile, extensions: [...names], projectSha256, nextSteps: results.flatMap(result => result.nextSteps) };
+      return { directory, project, hostFile, extensions: [...names], projectSha256,
+        nextSteps: [...(dependencies ? installSteps(directory, dependencies) : []), ...results.flatMap(result => result.nextSteps)],
+        dependencies: dependencies?.pins ?? [] };
     } catch (error) { await rm(directory, { recursive: true, force: true }); throw error; }
   } finally { wipe(); }
 }

package/dist/manifest.js

@@ -111,5 +111,5 @@ export async function buildManifest(project       ,options               ={})
 }
 /** The manifest as `build` writes it: two-space JSON with a trailing newline. */
 export function renderManifest(manifest         )        {return JSON.stringify(manifest,null,2)+'\n';}
-export const manifestFileName='manifest.json';
+const manifestFileName='manifest.json';
 export function manifestPath(out       )        {return join(out,manifestFileName);}

package/dist/mcp-authoring.js

@@ -54,7 +54,7 @@ async function verdict(root       ,origin        ) {
  catch{return {valid:false         ,note:'Project does not validate; call run_validate for the CLI report.'};}
 }
 function object(value        )                                {return value!==null&&typeof value==='object'&&!Array.isArray(value);}
-function expandHandler(path       ,handler        )                        {
+function expandHandler(handler        )                        {
  if(object(handler))return handler;
  assert(typeof handler==='string','Handler must be a route object or a short form');
  if(/^https?:\/\//.test(handler))return {redirect:{url:handler}};
@@ -83,7 +83,7 @@ async function createRoute(root       ,args                       ,origin
  assert(file==='urlcode.yaml'||(loaded.document.includes??[]).includes(file),'file must be urlcode.yaml or an include listed in it');
  const target=await confinedPath(root,file);
  assert(!Object.hasOwn(loaded.routes,path),'Route already exists');
- const route={...expandHandler(path,args.handler)};
+ const route={...expandHandler(args.handler)};
  const middleware=expandMiddleware(args.middleware);if(middleware)route.middleware=middleware;
  const lockPath=join(root,'urlcode.yaml.lock'),lock=await open(lockPath,'wx',0o600);
  let temp                 ;

package/dist/mcp.js

@@ -78,7 +78,7 @@ export async function serveMcp(options           )               {
   if(message.method==='initialize') {
    if(initialized){await error(id,-32600,'Already initialized');return;}
    if(typeof params.protocolVersion!=='string'||!object(params.capabilities)||!object(params.clientInfo)||typeof params.clientInfo.name!=='string'||typeof params.clientInfo.version!=='string'){await error(id,-32602,'Invalid initialize params');return;}
-   initialized=true;await send({jsonrpc:'2.0',id,result:{protocolVersion,capabilities:{tools:{}},serverInfo:{name:'urlcode',version:'0.4.0-alpha.3'}}});return;
+   initialized=true;await send({jsonrpc:'2.0',id,result:{protocolVersion,capabilities:{tools:{}},serverInfo:{name:'urlcode',version:'0.4.1'}}});return;
   }
   if(message.method==='ping'){await send({jsonrpc:'2.0',id,result:{}});return;}
   if(!ready){await error(id,-32002,'Initialize first');return;}

package/dist/policies/cache.js

@@ -198,7 +198,7 @@ function bodyOf(result               )         { return result.body ? (Buffer.is
 
 // Conditional requests for results the handler did not validate itself:
 // assets answer 304 before this phase, so only 200 results are examined.
-function revalidate(state            , req               , result               )                {
+function revalidate(req               , result               )                {
   if (result.status !== 200 || (req.method !== 'GET' && req.method !== 'HEAD')) return result;
   let headers = result.headers, etag = header(headers, 'etag');
   if (!etag) {
@@ -249,7 +249,7 @@ export function onResponse(state            , req               , result
   // refusal produced ahead of the handler keeps its own headers.
   if (flight || state.statuses.has(result.status)) headers = mergeVary(headers, state.vary);
   let out                = { ...result, headers };
-  if (state.strategy === 'revalidate') out = revalidate(state, req, out);
+  if (state.strategy === 'revalidate') out = revalidate(req, out);
   if (!flight) return out;
   // Store decision for the request that reached the handler; waiters are
   // released either way, with the entry or with nothing.