@jimhoyd/urlcode 0.4.0-alpha.3 → 0.4.2

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.2'}}});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.

package/dist/policy.js

@@ -32,6 +32,22 @@ export async function prepareFunctionSnapshot(loaded                )
     if (route.sandbox) { for (const definition of [...middleware, ...(fn ? [fn] : [])]) sandboxed.push({pattern,function:definition}); }
     else trusted.push({middleware, function: fn});
   }
+  // Extension hooks are a core primitive even though their names and payloads
+  // belong to each extension. Include every declared entry module in the
+  // reviewed project revision, so editing trusted hook code invalidates the
+  // operator's extension pin just like editing a trusted route function.
+  for(const [extension,declaration] of Object.entries(loaded.document.extensions??{})){
+    const hooks=declaration.config.hooks;
+    if(hooks===undefined)continue;
+    assert(hooks&&typeof hooks==='object'&&!Array.isArray(hooks),`Extension ${extension} hooks must be an object`);
+    for(const [name,raw] of Object.entries(hooks                          )){
+      assert(typeof raw==='string'||raw&&typeof raw==='object'&&!Array.isArray(raw),`Invalid extension hook: ${extension}.${name}`);
+      const reference=typeof raw==='string'?{source:raw}:raw                                     ;
+      assert(typeof reference.source==='string',`Invalid extension hook: ${extension}.${name}`);
+      assert(reference.export===undefined||typeof reference.export==='string',`Invalid extension hook: ${extension}.${name}`);
+      trusted.push({function:await resolveOne({source:reference.source,...(reference.export===undefined?{}:{export:reference.export          })})});
+    }
+  }
   const collected = await collectFunctionSources(sandboxed,loaded.root);
   const trustedSources = await collectTrustedSources(trusted,loaded.root);
   // The hash operator grants pin to still covers trusted routes' own source, so

package/dist/project-dependencies.js

@@ -0,0 +1,305 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ConfigError, assert } from './errors.js';
+
+/**
+ * Exact dependency pins for a generated application.
+ *
+ * `urlcode init --with` resolves whatever `@jimhoyd/urlcode-<name>` packages are already installed beside the
+ * invoking directory. Without a manifest the generated site records nothing about which versions it was built
+ * against, so a later `npm install @jimhoyd/urlcode-auth` in that site can resolve a different set (#212). This
+ * module reads the versions that were actually resolved, validates the whole set against the packages' own
+ * declared `peerDependencies`, and renders a `package.json` pinning every one of them exactly.
+ *
+ * It never runs a package manager: generating a lockfile stays an explicit `npm install` the operator runs after
+ * reviewing the manifest. It also never imports an extension implementation -- only package metadata is read, by
+ * a name the caller supplied -- so core's generic extension boundary is unchanged.
+ */
+
+export const CORE_PACKAGE = '@jimhoyd/urlcode';
+const namePattern = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+
+                                                                                                    
+const versionPattern = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+
+export function parseVersion(value        )                 {
+  const match = versionPattern.exec(value.trim());
+  if (!match) return null;
+  const pre = match[4] === undefined ? [] : match[4].split('.').map(part => /^\d+$/.test(part) ? Number(part) : part);
+  return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]), pre };
+}
+function comparePre(a                              , b                              )         {
+  // A version with a prerelease is lower than the same version without one.
+  if (!a.length || !b.length) return a.length === b.length ? 0 : a.length ? -1 : 1;
+  for (let index = 0; index < Math.max(a.length, b.length); index++) {
+    const left = a[index], right = b[index];
+    if (left === undefined) return -1;
+    if (right === undefined) return 1;
+    if (left === right) continue;
+    if (typeof left === 'number' && typeof right === 'number') return left < right ? -1 : 1;
+    if (typeof left === 'number') return -1; // numeric identifiers rank lower than alphanumeric ones
+    if (typeof right === 'number') return 1;
+    return left < right ? -1 : 1;
+  }
+  return 0;
+}
+export function compareVersions(a         , b         )         {
+  for (const key of ['major', 'minor', 'patch']         ) if (a[key] !== b[key]) return a[key] < b[key] ? -1 : 1;
+  return comparePre(a.pre, b.pre);
+}
+                                                                                  
+/**
+ * A deliberately small subset of the range grammar: `*`, exact versions, the comparators, `^` and `~` over a
+ * complete `x.y.z`, whitespace for AND and `||` for OR. Anything else refuses rather than guessing, so an
+ * unrecognized peer range surfaces as a refusal instead of a silently wrong compatibility answer.
+ */
+function parseComparatorSet(text        , context        )                       {
+  const tokens = text.trim().split(/\s+/).filter(Boolean);
+  if (!tokens.length || tokens.every(token => token === '*' || token === 'x' || token === 'X')) return 'any';
+  const comparators               = [];
+  for (const token of tokens) {
+    const match = /^(>=|<=|>|<|=|\^|~)?\s*(.+)$/.exec(token);
+    const version = match ? parseVersion(match[2] ) : null;
+    if (!match || !version) throw new ConfigError(`Unsupported version range ${JSON.stringify(text)} (${context}); supported forms are *, x.y.z, >=, >, <, <=, = and ^ or ~ over a complete x.y.z`);
+    const operator = (match[1] ?? '=')                                      ;
+    if (operator === '^' || operator === '~') {
+      // ^0.x is minor-bounded, ^0.0.x is patch-bounded, ^x is major-bounded; ~ is always minor-bounded.
+      const upper = operator === '~' || version.major === 0
+        ? (operator === '^' && version.major === 0 && version.minor === 0
+          ? { major: 0, minor: 0, patch: version.patch + 1, pre: [] }
+          : { major: version.major, minor: version.minor + 1, patch: 0, pre: [] })
+        : { major: version.major + 1, minor: 0, patch: 0, pre: [] };
+      comparators.push({ operator: '>=', version }, { operator: '<', version: upper });
+      continue;
+    }
+    comparators.push({ operator, version });
+  }
+  return comparators;
+}
+function satisfiesComparators(version         , comparators              )          {
+  // npm's prerelease rule: a prerelease version only satisfies a set that itself names a prerelease of the same
+  // x.y.z, so 0.5.0-alpha.1 never slips past `<0.5.0`.
+  if (version.pre.length && !comparators.some(item => item.version.pre.length && item.version.major === version.major && item.version.minor === version.minor && item.version.patch === version.patch)) return false;
+  return comparators.every(item => {
+    const order = compareVersions(version, item.version);
+    switch (item.operator) {
+      case '>': return order > 0;
+      case '>=': return order >= 0;
+      case '<': return order < 0;
+      case '<=': return order <= 0;
+      default: return order === 0;
+    }
+  });
+}
+export function satisfiesRange(version        , range        , context = 'peer range')          {
+  const parsed = parseVersion(version);
+  if (!parsed) throw new ConfigError(`Unsupported version ${JSON.stringify(version)} (${context})`);
+  return range.split('||').some(part => {
+    const set = parseComparatorSet(part, context);
+    return set === 'any' || satisfiesComparators(parsed, set);
+  });
+}
+
+                                   
+                                                   
+                                                                                              
+ 
+                                                                                                                                          
+const record = (value         )                                   => value !== null && typeof value === 'object' && !Array.isArray(value);
+const strings = (value         )                         => {
+  const out                         = {};
+  if (record(value)) for (const [key, item] of Object.entries(value)) if (typeof item === 'string') out[key] = item;
+  return out;
+};
+async function readManifest(file        )                                   {
+  let parsed             ;
+  try { parsed = JSON.parse(await readFile(file, 'utf8'))               ; }
+  catch { return null; }
+  if (typeof parsed.name !== 'string' || typeof parsed.version !== 'string') return null;
+  const optional = new Set        ();
+  if (record(parsed.peerDependenciesMeta)) for (const [key, value] of Object.entries(parsed.peerDependenciesMeta)) if (record(value) && value.optional === true) optional.add(key);
+  const engines = record(parsed.engines) && typeof parsed.engines.node === 'string' ? parsed.engines.node : undefined;
+  return { name: parsed.name, version: parsed.version, directory: dirname(file), peers: strings(parsed.peerDependencies), optionalPeers: optional, node: engines };
+}
+/**
+ * Walks `node_modules` upwards from the invoking directory, exactly like Node's own resolution but reading the
+ * package's manifest rather than its entry point. Reading the manifest directly (instead of resolving the entry)
+ * means a package whose `exports` does not expose `./package.json` is still inspectable, and nothing in the
+ * package is loaded or executed.
+ */
+export async function findInstalledPackage(name        , from        )                                   {
+  assert(namePattern.test(name), `Invalid package name: ${name}`);
+  let directory = resolve(from);
+  for (;;) {
+    const found = await readManifest(join(directory, 'node_modules', ...name.split('/'), 'package.json'));
+    if (found && found.name === name) return found;
+    const parent = dirname(directory);
+    if (parent === directory) return null;
+    directory = parent;
+  }
+}
+/** The version of the runtime executing this command; that is the version a generated site is pinned to. */
+export async function runningCore()                            {
+  const file = fileURLToPath(new URL('../package.json', import.meta.url));
+  const manifest = await readManifest(file);
+  assert(manifest && manifest.name === CORE_PACKAGE, `Could not read the running runtime manifest at ${file}`);
+  return manifest;
+}
+
+/**
+ * `resolved`/`link` entries from npm's hidden lockfile, used only to notice that a package was installed from a
+ * local directory or tarball. Such a package's version number is not installable from a registry, so the manifest
+ * has to record the local specifier instead of the exact version for the site to install offline.
+ */
+async function localSpecifiers(cwd        )                               {
+  const out = new Map                ();
+  let parsed         ;
+  try { parsed = JSON.parse(await readFile(join(cwd, 'node_modules', '.package-lock.json'), 'utf8')); }
+  catch { return out; }
+  if (!record(parsed) || !record(parsed.packages)) return out;
+  for (const [key, value] of Object.entries(parsed.packages)) {
+    const index = key.lastIndexOf('node_modules/');
+    if (index !== 0 || !record(value)) continue; // nested installs belong to another package's tree
+    const name = key.slice('node_modules/'.length);
+    const resolvedTo = typeof value.resolved === 'string' ? value.resolved : '';
+    if (value.link === true) { if (resolvedTo) out.set(name, 'file:' + resolve(cwd, resolvedTo)); continue; }
+    if (resolvedTo.startsWith('file:')) out.set(name, 'file:' + resolve(cwd, resolvedTo.slice('file:'.length)));
+  }
+  return out;
+}
+
+                                
+                                                   
+                                                                                           
+                 
+                                                                                                                  
+                                         
+ 
+                                
+                        
+                                                                                   
+                                       
+                                                                                                                   
+                           
+                                                             
+                 
+ 
+                                    
+                           
+                                                                                                     
+                                                      
+ 
+export function parsePin(value        )                   {
+  const index = value.indexOf('=');
+  assert(index > 0, 'Use --pin <package>=<specifier>, for example --pin @jimhoyd/urlcode-auth=file:/abs/path/urlcode-auth.tgz');
+  const name = value.slice(0, index).trim(), specifier = value.slice(index + 1).trim();
+  assert(namePattern.test(name), `Invalid --pin package name: ${name}`);
+  assert(specifier.length > 0 && specifier.length <= 512 && !/[\s\0]/.test(specifier), `Invalid --pin specifier for ${name}`);
+  return [name, specifier];
+}
+function nodeFloor(ranges                                 )                     {
+  let best                     ;
+  for (const range of ranges) {
+    // Only a plain `>=x.y.z` floor is recognized; anything else is left out rather than reinterpreted.
+    const match = range === undefined ? null : /^>=\s*(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)$/.exec(range.trim());
+    const version = match ? parseVersion(match[1] ) : null;
+    if (version && (!best || compareVersions(version, best) > 0)) best = version;
+  }
+  return best ? `>=${best.major}.${best.minor}.${best.patch}${best.pre.length ? '-' + best.pre.join('.') : ''}` : undefined;
+}
+
+/**
+ * Resolves core plus every named extension and their declared peers, then validates the whole set against every
+ * declared peer range before returning. Compatibility is judged as a set: a mismatch anywhere refuses, listing
+ * every mismatch rather than the first.
+ */
+export async function collectDependencySet(names                   , packageNames                   , { cwd = process.cwd(), overrides }                    = {})                         {
+  assert(names.length === packageNames.length, 'Each extension name needs its package name');
+  const core = await runningCore();
+  const resolved = new Map                          ([[CORE_PACKAGE, core]]);
+  const roles = new Map                               ([[CORE_PACKAGE, 'runtime']]);
+  const missing           = [];
+  const pending           = [];
+  for (const pkg of packageNames) { roles.set(pkg, 'extension'); pending.push(pkg); }
+  // A copy of core installed beside the project would be resolved by the generated site, not the one running
+  // here; pinning one version while the other is installed is exactly the inconsistency this refuses to record.
+  const installedCore = await findInstalledPackage(CORE_PACKAGE, cwd);
+  if (installedCore && installedCore.version !== core.version)
+    throw new ConfigError(`${CORE_PACKAGE} ${installedCore.version} is installed in ${cwd} but this command is ${core.version}; run the matching CLI or align the installed runtime before recording pins`);
+  while (pending.length) {
+    const name = pending.shift() ;
+    if (resolved.has(name)) continue;
+    const found = await findInstalledPackage(name, cwd);
+    if (!found) { missing.push(name); continue; }
+    resolved.set(name, found);
+    for (const peer of Object.keys(found.peers)) {
+      if (resolved.has(peer) || found.optionalPeers.has(peer)) continue;
+      if (!roles.has(peer)) roles.set(peer, 'peer');
+      pending.push(peer);
+    }
+  }
+  if (missing.length) {
+    const required = missing.map(name => {
+      const source = [...resolved.values()].find(pkg => Object.hasOwn(pkg.peers, name));
+      return source ? `${name} (required by ${source.name} ${source.peers[name]})` : name;
+    });
+    throw new ConfigError(`Cannot record exact pins: ${required.join(', ')} ${missing.length > 1 ? 'are' : 'is'} not installed in ${cwd}. Install the missing package(s) there, or pass --no-manifest to generate the site without a dependency manifest.`);
+  }
+  const conflicts           = [];
+  for (const pkg of resolved.values())
+    for (const [peer, range] of Object.entries(pkg.peers)) {
+      const installed = resolved.get(peer);
+      if (!installed) continue; // optional peer that is not installed
+      if (!satisfiesRange(installed.version, range, `${pkg.name} peerDependencies.${peer}`)) conflicts.push(`${pkg.name} ${pkg.version} requires ${peer} ${range}, but ${installed.version} is installed`);
+    }
+  if (conflicts.length) throw new ConfigError(`Incompatible versions: ${conflicts.join('; ')}`);
+  const locals = await localSpecifiers(cwd);
+  const pins                  = [...resolved.values()]
+    .map(pkg => {
+      const override = overrides?.get(pkg.name);
+      const local = locals.get(pkg.name);
+      const specifier = override ?? local ?? pkg.version;
+      return { name: pkg.name, version: pkg.version, specifier, local: specifier !== pkg.version, role: roles.get(pkg.name) ?? 'peer' };
+    })
+    .sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+  for (const [name] of overrides ?? []) assert(pins.some(pin => pin.name === name), `--pin ${name} names a package that is not part of this project's dependency set`);
+  const dependencies                         = {};
+  for (const pin of pins) dependencies[pin.name] = pin.specifier;
+  return { pins, dependencies, node: nodeFloor([...resolved.values()].map(pkg => pkg.node)), local: pins.some(pin => pin.local) };
+}
+
+const TRIMMED = '._-';
+const manifestName = (directory        )         => {
+  const mapped = (directory.split(/[\\/]/).pop() ?? 'urlcode-site').toLowerCase().replace(/[^a-z0-9._-]+/g, '-');
+  // Trimmed with indices rather than /^[._-]+|[-._]+$/: an anchored quantifier
+  // over a repeated character is retried from every start position, which is
+  // quadratic on a directory name of many dashes (CodeQL js/polynomial-redos).
+  let start = 0, end = mapped.length;
+  while (start < end && TRIMMED.includes(mapped[start] ?? '')) start += 1;
+  while (end > start && TRIMMED.includes(mapped[end - 1] ?? '')) end -= 1;
+  const base = mapped.slice(start, end);
+  return base.length ? base.slice(0, 214) : 'urlcode-site';
+};
+/** The generated manifest: private, module type, exact pins, and nothing that runs a package manager. */
+export function renderPackageManifest(directory        , set               )         {
+  return JSON.stringify({
+    name: manifestName(directory),
+    private: true,
+    version: '0.0.0',
+    type: 'module',
+    ...(set.node ? { engines: { node: set.node } } : {}),
+    dependencies: set.dependencies,
+  }, null, 2) + '\n';
+}
+/**
+ * The install step is printed, never run: generating `package-lock.json` executes a package manager, which
+ * resolves and downloads code, so it stays the operator's explicit action after reviewing the manifest.
+ */
+export function installSteps(directory        , set               )           {
+  const where = isAbsolute(directory) ? directory : resolve(directory);
+  return [
+    `Review ${join(where, 'package.json')}; it pins ${set.pins.map(pin => `${pin.name}@${pin.version}`).join(', ')}.`,
+    `Run \`npm install\` in ${where} to install those exact versions and generate package-lock.json${set.local ? ' (add `--offline` when the local paths are your only source)' : ''}. urlcode never runs a package manager for you.`,
+  ];
+}

package/dist/readiness.js

@@ -37,6 +37,9 @@ import { runCompliance } from './compliance.js';
                                                                                                                                         
                               
                                     
+                                                                         
+                                                                                               
+                            
                                                                                                                        
                                                                                                                                     
                                                                                                                                                             
@@ -188,7 +191,8 @@ export async function auditProject(app              , {expectRoutes,log=()=>{},c
   const advisories=plan.inventory.flatMap(route=>(route.advisories??[]).map(message=>({route:route.path,message})));
   // The per-route capability table: which policies apply and whether this
   // host enforces, compiles or delegates each one. Refusals never get here.
-  return {elapsedMs:performance.now()-began,ready:countMatches && !failed && !uncovered.length && counts.active>0,counts,expectedRoutes:expectRoutes ?? null,countMatches,checks:cases.length,passed,failed,coveredRouteMethods:covered.size,unassertedCases,uncovered,policies:plan.policies ?? {},compliance:compliance?await runCompliance(app,compliance):null,advisories};
+  const notReadyReasons=[...(counts.active>0?[]:['no-active-routes']),...(countMatches?[]:['route-count-mismatch']),...(failed?['failed-checks']:[]),...(uncovered.length?['uncovered-route-methods']:[])];
+  return {elapsedMs:performance.now()-began,ready:!notReadyReasons.length,notReadyReasons,counts,expectedRoutes:expectRoutes ?? null,countMatches,checks:cases.length,passed,failed,coveredRouteMethods:covered.size,unassertedCases,uncovered,policies:plan.policies ?? {},compliance:compliance?await runCompliance(app,compliance):null,advisories};
 }
 export async function benchmarkProject(app              ,{requests=1000,concurrency=2,maxP95Ms,seconds=30,warmup=0,target}                  ={})                           {
   assert(Number.isInteger(requests)&&requests>=1&&requests<=100000,'Requests must be 1–100000');

package/dist/runtime.js

@@ -117,7 +117,7 @@ export async function createRuntime(project        , rawOptions
   // route is trusted-by-default and dispatches through `trusted` below,
   // in-process, with no worker or WASM engine involved at all.
   const pool=await new FunctionPool(routes.filter(route=>route.sandbox===true), { root:loaded.root, snapshot, log:options.log, workers:options.workers, timeoutMs:options.timeoutMs, maxBytes:options.maxBytes }).start();
-  const trusted = new TrustedFunctions({ timeoutMs: options.timeoutMs, maxBytes: options.maxBytes, log: options.log });
+  const trusted = new TrustedFunctions({ timeoutMs: options.timeoutMs, maxBytes: options.maxBytes });
   // Eagerly validated up front, exactly like the sandboxed pool above: a
   // trusted route with a broken module or a missing export fails activation
   // here rather than on its first request.

package/dist/tooling.js

@@ -68,7 +68,7 @@ export async function previewImport(options                    ) {return importR
 export async function previewExport(project       ,format                  ,acceptProviderDifferences=false) {const loaded=await loadDocument(project);const {includes:_includes,...document}=loaded.document;return exportRoutes({format,document:{...document,routes:loaded.routes},acceptProviderDifferences});}
                                       
                                                               
-                                                                                                                                                                                                            
+                                                                                                                                                                                                                           
                                                                                                   
  
 /** Reports registered extension contracts against the project's declarations. Never activates an extension. */
@@ -84,6 +84,7 @@ export async function describeExtensions(project       ,registrations
   name:String(registration.name),version:String(registration.version),targets:Array.isArray(registration.targets)?registration.targets.map(String):[],
   credentialHeaders:Array.isArray(registration.credentialHeaders)?registration.credentialHeaders.map(String):[],
   schema:structuredClone(registration.schema??{}),policySchema:registration.policySchema?structuredClone(registration.policySchema):null,
+  hooks:structuredClone(registration.hooks??[])            ,
   declared:Object.hasOwn(loaded.document.extensions??{},registration.name),revisionPinned:registration.projectSha256===projectSha256,
   mounts:mountsOf(registration.name),policyRoutes:policyRoutesOf(registration.name),
  }));

package/dist/trusted-functions.js

@@ -33,16 +33,15 @@ import { routeFunctions } from './function-sources.js';
                                                                       
                                                           
                                                                     
-                                        
 
-                                                                                                                                   
+                                                                                                          
                                                               
                                                             
                                                                                                    
                                                                                                                                      
 
 export class TrustedFunctions {
-  timeoutMs        ; maxBytes        ; log       ;
+  timeoutMs        ; maxBytes        ;
   // Node's ESM loader caches a resolved module forever by URL, unlike a
   // sandboxed worker, which gets a genuinely fresh module registry on every
   // reload/restart. A snapshot reload constructs a brand-new TrustedFunctions
@@ -51,8 +50,8 @@ export class TrustedFunctions {
   // sandboxed pool's "new workers, new snapshot" reload contract, while a
   // single instance still only imports each module once per process.
                    epoch = randomUUID();
-  constructor({ timeoutMs = 5000, maxBytes = 1048576, log = () => {} }                          = {}) {
-    this.timeoutMs = timeoutMs; this.maxBytes = maxBytes; this.log = log;
+  constructor({ timeoutMs = 5000, maxBytes = 1048576 }                          = {}) {
+    this.timeoutMs = timeoutMs; this.maxBytes = maxBytes;
   }
   // Eagerly imports and validates every declared export exists as a function,
   // the same guarantee FunctionPool.start() gives the sandboxed path: a

package/dist/types/authoring.d.ts

@@ -1,2 +1,10 @@
-export declare function initProject(destination: string): Promise<string>;
+import type { DependencySet } from './project-dependencies.ts';
+export interface InitOptions {
+    /**
+     * When given, a `package.json` pinning exactly these versions is written beside `urlcode.yaml`. Route-only
+     * initialization stays the default: a project whose runtime is managed elsewhere gets no manifest at all.
+     */
+    manifest?: DependencySet | undefined;
+}
+export declare function initProject(destination: string, { manifest }?: InitOptions): Promise<string>;
 export declare function addRedirect(project: string, destination: string, alias?: string | undefined): Promise<string>;

package/dist/types/capability-query.d.ts

@@ -17,7 +17,6 @@ export interface CapabilityEntry extends CapabilityDetail {
     recipes: CapabilityUsage[];
     cookbook: CapabilityUsage[];
 }
-export declare function capabilityNameList(): readonly CapabilityName[];
 /** One catalog entry with its schema fragments and bundled usage. No project, credentials or network are read. */
 export declare function getCapability(name: string): CapabilityEntry;
 export declare function formatCapability(entry: CapabilityEntry): string;

package/dist/types/catalog.d.ts

@@ -46,10 +46,6 @@ export interface SearchHit<T extends CatalogMetadata> {
     score: number;
     matched: string[];
 }
-export declare const metadataFiles: {
-    readonly recipe: "recipe.yaml";
-    readonly 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 declare function readMetadata(root: string, id: string, file: 'recipe.yaml' | 'example.yaml'): Promise<CatalogMetadata>;
 /** Preflight only: loads the project, expands site routes and asks the capability analysis for every target. No bindings, code or activation. */