@jimhoyd/urlcode 0.4.0-alpha.3 → 0.4.1

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/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/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. */

package/dist/types/config.d.ts

@@ -1,4 +1,4 @@
-import type { AuthoredRouteConfig, LoadedDocument, ProjectDocument, RouteConfig } from './types.ts';
+import type { LoadedDocument, ProjectDocument, RouteConfig } from './types.ts';
 /** What config-worker.ts posts back: the loaded document, or the ConfigError message. */
 export type ConfigWorkerResult = {
     value: LoadedDocument;
@@ -17,14 +17,6 @@ export declare const SHORT_FORM_PATH_SCHEMA: {
     readonly minLength: 1;
     readonly maxLength: 128;
 };
-/**
- * Expands the YAML short forms into the canonical long form. `function: functions/x.mjs`
- * becomes `{source, args}` with an argument per `{param}` in the path, declaring any
- * parameter the route does not declare itself; a string middleware entry becomes `{source}`;
- * 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 declare function normalizeRoute(pattern: string, route: AuthoredRouteConfig | RouteConfig): RouteConfig;
 export declare function safeFile(root: string, file: unknown): Promise<string>;
 export declare function loadDocument(project: string, { timeoutMs }?: {
     timeoutMs?: number;

package/dist/types/explain.d.ts

@@ -95,7 +95,6 @@ export interface ExplainOptions {
     projectSha256?: string | undefined;
     now?: number | undefined;
 }
-export declare function routeState(route: CompiledRoute, now: number): RouteState;
 /** Describe one compiled route. `chain` is the policy chain compiled for it, when the project declares policies. */
 export declare function explainCompiledRoute(loaded: LoadedDocument, route: CompiledRoute, chain: PolicyChain | undefined, options?: ExplainOptions): RouteExplanation;
 export declare function nearestRoutes(target: string, patterns: Iterable<string>, limit?: number): string[];

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

@@ -32,7 +32,6 @@ export interface ResponseWriter {
     end(body?: ResponseBody): unknown;
     destroy(): unknown;
 }
-export declare const forbiddenHeaders: Set<string>;
 export declare function prepareResponse(result: HandlerResult, { requestId, method }: ResponseOptions): PreparedResponse;
 export declare function writeResponse(res: ResponseWriter, result: HandlerResult, options: ResponseOptions): number;
 export declare function errorResponse(error: unknown, { requestId, method, headers }: ResponseOptions & {

package/dist/types/index.d.ts

@@ -38,4 +38,5 @@ export { scaffoldProject } from './scaffold.ts';
 export type { ScaffoldReport, Unresolved as ScaffoldUnresolved } from './scaffold.ts';
 export { initProject, addRedirect } from './authoring.ts';
 export { initProjectWith } from './init-with.ts';
+export { collectDependencySet, renderPackageManifest, installSteps } from './project-dependencies.ts';
 export type { ScaffoldRequest, ScaffoldResult, ScaffoldFile } from './extensions.ts';

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

@@ -1,8 +1,10 @@
-import type { ScaffoldRequest, ScaffoldResult } from './extensions.ts';
-/** Directory names inside the generated site. The route project lives under `app/`; everything else is operator-owned. */
-export declare const PROJECT_DIRECTORY = "app", HOST_FILE = "host.mjs", ROUTES_FILE = "routes/extensions.yaml";
+import type { DependencyPin } from './project-dependencies.ts';
 export interface InitWithOptions {
     cwd?: string | undefined;
+    /** Default true: record exact pins for core, the named extensions and their declared peers. */
+    manifest?: boolean | undefined;
+    /** `--pin <package>=<specifier>` overrides, for local tarballs, checkouts and mirrors. */
+    pins?: ReadonlyMap<string, string> | undefined;
 }
 export interface InitWithResult {
     directory: string;
@@ -11,20 +13,12 @@ export interface InitWithResult {
     extensions: string[];
     projectSha256: string;
     nextSteps: string[];
+    dependencies: DependencyPin[];
 }
 export declare function parseWithNames(value: string): string[];
-export declare const packageName: (name: string) => string;
-/**
- * Resolves the extension package from the invoking directory (Node's package resolution with the default
- * 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 declare function loadScaffold(name: string, request: ScaffoldRequest, cwd: string): Promise<ScaffoldResult>;
-export declare function renderHost(names: readonly string[], results: readonly ScaffoldResult[]): string;
-export declare function renderReadme(directory: string, names: readonly string[], results: readonly ScaffoldResult[], starter: string, env: Record<string, string>, projectSha256: string): string;
 /**
  * `urlcode init <directory> --with a,b`: the starter under `app/`, every extension's fragments merged into one
  * `urlcode.yaml`, one `host.mjs`, one `README.md` and the extensions' own files. All packages are resolved and
  * their scaffolds computed before anything is written, so a refusal leaves no directory behind.
  */
-export declare function initProjectWith(destination: string, names: readonly string[], { cwd }?: InitWithOptions): Promise<InitWithResult>;
+export declare function initProjectWith(destination: string, names: readonly string[], { cwd, manifest, pins }?: InitWithOptions): Promise<InitWithResult>;

package/dist/types/manifest.d.ts

@@ -79,5 +79,4 @@ export interface Manifest {
 export declare function buildManifest(project: string, options?: InspectOptions): Promise<Manifest>;
 /** The manifest as `build` writes it: two-space JSON with a trailing newline. */
 export declare function renderManifest(manifest: Manifest): string;
-export declare const manifestFileName = "manifest.json";
 export declare function manifestPath(out: string): string;

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

@@ -0,0 +1,78 @@
+/**
+ * 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 declare const CORE_PACKAGE = "@jimhoyd/urlcode";
+interface Version {
+    major: number;
+    minor: number;
+    patch: number;
+    pre: readonly (string | number)[];
+}
+export declare function parseVersion(value: string): Version | null;
+export declare function compareVersions(a: Version, b: Version): number;
+export declare function satisfiesRange(version: string, range: string, context?: string): boolean;
+export interface InstalledPackage {
+    name: string;
+    version: string;
+    directory: string;
+    peers: Record<string, string>;
+    optionalPeers: ReadonlySet<string>;
+    node: string | undefined;
+}
+/**
+ * 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 declare function findInstalledPackage(name: string, from: string): Promise<InstalledPackage | null>;
+/** The version of the runtime executing this command; that is the version a generated site is pinned to. */
+export declare function runningCore(): Promise<InstalledPackage>;
+export interface DependencyPin {
+    name: string;
+    version: string;
+    specifier: string;
+    /** True when the specifier is a local path or tarball rather than a registry version. */
+    local: boolean;
+    /** `runtime` is core, `extension` was named in --with, `peer` was pulled in by a package's peerDependencies. */
+    role: 'runtime' | 'extension' | 'peer';
+}
+export interface DependencySet {
+    pins: DependencyPin[];
+    /** Exactly what goes into the generated `dependencies` block, sorted by name. */
+    dependencies: Record<string, string>;
+    /** Highest recognized `engines.node` floor across the set, or undefined when none was expressed as `>=x.y.z`. */
+    node: string | undefined;
+    /** True when any pin points at a local path or tarball. */
+    local: boolean;
+}
+export interface DependencyOptions {
+    cwd?: string | undefined;
+    /** `--pin <package>=<specifier>`: an operator-chosen specifier, for local tarballs and mirrors. */
+    overrides?: ReadonlyMap<string, string> | undefined;
+}
+export declare function parsePin(value: string): [string, string];
+/**
+ * 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 declare function collectDependencySet(names: readonly string[], packageNames: readonly string[], { cwd, overrides }?: DependencyOptions): Promise<DependencySet>;
+/** The generated manifest: private, module type, exact pins, and nothing that runs a package manager. */
+export declare function renderPackageManifest(directory: string, set: DependencySet): string;
+/**
+ * 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 declare function installSteps(directory: string, set: DependencySet): string[];
+export {};

package/dist/types/trusted-functions.d.ts

@@ -2,11 +2,9 @@ import type { FunctionRoute } from './function-sources.ts';
 import type { FunctionContext, FunctionResult } from './functions.ts';
 import type { GuestRequestPayload } from './guest-api.ts';
 import type { HandlerResult } from './http-response.ts';
-import type { LogFn } from './types.ts';
 export interface TrustedFunctionsOptions {
     timeoutMs?: number | undefined;
     maxBytes?: number | undefined;
-    log?: LogFn | undefined;
 }
 interface TrustedDefinition {
     source: string;
@@ -16,9 +14,8 @@ export type TrustedRoute = FunctionRoute<TrustedDefinition>;
 export declare class TrustedFunctions {
     timeoutMs: number;
     maxBytes: number;
-    log: LogFn;
     private readonly epoch;
-    constructor({ timeoutMs, maxBytes, log }?: TrustedFunctionsOptions);
+    constructor({ timeoutMs, maxBytes }?: TrustedFunctionsOptions);
     start(routes: TrustedRoute[]): Promise<this>;
     private loadExport;
     execute(route: TrustedRoute, request: GuestRequestPayload, context: FunctionContext, native: HandlerResult | undefined): Promise<FunctionResult>;

package/docs/AI-AUTHORING.md

@@ -25,7 +25,11 @@ fields or bypass target limits or operator grants. See [the design principle](PR
 6. [Readiness](READINESS.md), [capacity](CAPACITY.md), [DDoS/recovery](RESILIENCE.md).
 7. [The framework](FRAMEWORK.md) for accounts, administration and presentation:
    `extensions.<name>` blocks and `extension` mounts are the only YAML those
-   packages need; their configuration is documented in their own repositories.
+   packages need. [Composing a site](COMPOSING-A-SITE.md) is the map of what a
+   consumer may then change: the `config` each package accepts, the
+   presentation overrides under `ui/`, the project functions its lifecycle
+   hooks call, and when a requirement instead needs a new extension in
+   TypeScript.
 
 The root [llms.txt](../llms.txt) is a compact discovery index; the generated
 [llms-full.txt](../llms-full.txt) concatenates the authoring documents above in

package/docs/AWS.md

@@ -11,6 +11,15 @@ self-hosted Node lifecycle, and a `sandbox: true` route would pay worker and
 WASM startup on every cold start. Both are refused at activation with the route
 named, never per request, trusted or sandboxed alike.
 
+That refusal is a settled position, not a gap awaiting an adapter: per-route
+Lambda compilation was considered and declined
+([the decision](OPEN-DECISIONS.md#accepted-one-node-deployment-per-project),
+[the analysis behind it](archive/2026-09-19/SPIKE-LAMBDA-COMPILE.md)). A project that uses
+`function` or `middleware` deploys instead as one trusted Node process — a
+container or a VM running the project as it runs locally — which supports every
+route type today. That process can run on AWS: ECS, EC2 and App Runner all
+serve it. The decision is about the execution model, not about avoiding AWS.
+
 A working project is in [`examples/aws/`](../examples/aws/).
 
 ## Set it up

package/docs/CI-FOLLOWUP-2026-09-19.md

@@ -68,7 +68,7 @@ extra shards would add setup and runner pressure.
   quality check or claim measured savings from a workflow with no prior runs.
 - The manual signed candidate builds all four tarballs and installs them together
   in a temporary consumer outside the workspace. It verifies the peer dependency
-  tree, installed versions, public imports, and `init --with auth,admin,ui`.
+  tree, installed versions, public imports, and `init --with ui,auth,admin`.
   `train.json` records package SHA-512 integrity and the source commit; the
   candidate manifest/checksums and provenance include the extension archives.
   Failure stops the candidate before attestation/upload. Nothing is published.

package/docs/CODEBASE-AUDIT-2026-09-20.md

@@ -1,3 +1,9 @@
+<!-- trust-model-prose: historical-file -->
+<!-- This report quotes the defective wording it is reporting -- including the
+     pre-trusted-default claims in finding 4 -- so the prose gate would read the
+     quotations as the guidance itself. The file is a dated review of one
+     commit and is not edited as the defects are fixed. -->
+
 # Codebase, tooling and documentation audit — 2026-09-20
 
 Reviewed commit: `bca8ac7` (core 0.4.0-alpha.2, auth 0.1.0-alpha.5,