@jimhoyd/urlcode 0.4.0-alpha.2 → 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/readiness.js

@@ -17,6 +17,8 @@ import { runCompliance } from './compliance.js';
 /** One configured route as the inventory reports it: a PlanInventoryEntry with the handler kind named. */
                                                             
                                    
+                                                                                     
+                   
                                                                                
                                                                                  
                         
@@ -74,6 +76,7 @@ export function projectPlan(compiled                               )
   const now = Date.now();
   const inventory                   = routes.map(route => { const advisories = routeAdvisories(route); return { path:route.pattern, handler:handlers.find(key => route[key]), methods:route.methods, middleware:route.middleware?.length || 0,
     policies:[...(route.policy ? Object.keys(route.policy.describe) : []),...(route.extensionPolicyNames??[]).map(name=>`extensions.${name}`)],
+    sandbox:route.sandbox === true, ...(route.sandboxReason ? { sandboxReason:route.sandboxReason } : {}),
     ...(route.generated ? { generated:route.generated } : {}),
     ...(advisories.length ? { advisories } : {}),
     state:route.enabled === false ? 'disabled' : route.expiresAt && now >= route.expiresAt ? 'expired' : 'active' }; });

package/dist/route-diff.js

@@ -17,7 +17,7 @@ const isStrings = (value         )                    => Array.isArray(value) &&
 function entry(value         , index        )                     {
   const fail = (what        )        => { throw new ConfigError(`Route report inventory[${index}] ${what}`); };
   if (!isRecord(value)) return fail('is not an object');
-  const { path, handler, methods, middleware, policies, generated, state } = value;
+  const { path, handler, methods, middleware, policies, generated, state, sandbox, sandboxReason } = value;
   if (typeof path !== 'string' || !path) return fail('needs a path');
   if (handler !== undefined && typeof handler !== 'string') return fail('has an invalid handler');
   if (!isStrings(methods)) return fail('needs methods');
@@ -25,7 +25,13 @@ function entry(value         , index        )                     {
   if (!isStrings(policies)) return fail('needs policies');
   if (generated !== undefined && typeof generated !== 'string') return fail('has an invalid generated marker');
   if (typeof state !== 'string' || !states.includes(state              )) return fail('needs a state');
-  return { path, handler, methods, middleware, policies, ...(generated !== undefined ? { generated } : {}), state:state               };
+  // `sandbox`/`sandboxReason` postdate the report format, so an older report
+  // omits them: absent is carried through as absent rather than defaulted to
+  // `false`, which would read as a trust change that never happened.
+  if (sandbox !== undefined && typeof sandbox !== 'boolean') return fail('has an invalid sandbox flag');
+  if (sandboxReason !== undefined && typeof sandboxReason !== 'string') return fail('has an invalid sandboxReason');
+  return { path, handler, methods, middleware, policies, ...(generated !== undefined ? { generated } : {}), state:state              ,
+    ...(sandbox !== undefined ? { sandbox } : {}), ...(sandboxReason !== undefined ? { sandboxReason } : {}) };
 }
 /** Validates a parsed `urlcode routes` JSON report (a child-process or file boundary) into a snapshot. */
 export function parseRouteSnapshot(value         )                {
@@ -71,7 +77,7 @@ export function diffRoutes(before               , after               )
 }
 export const hasRouteChanges = (diff           )          => diff.added.length + diff.removed.length + diff.changed.length > 0;
 
-const fields = ['handler','methods','state','middleware','policies','generated','policy']         ;
+const fields = ['handler','methods','state','sandbox','sandboxReason','middleware','policies','generated','policy']         ;
                                    
 const cell = (value         )         => {
   const text = value === undefined ? '' : Array.isArray(value) && value.every(item => typeof item === 'string') ? value.join(', ') : typeof value === 'string' ? value : canonical(value);
@@ -82,12 +88,13 @@ const code = (value        )         => `\`${value.replace(/\\/g, '\\\\').replac
 function table(headers          , rows            )           {
   return [`| ${headers.join(' | ')} |`, `|${headers.map(() => '---').join('|')}|`, ...rows.map(row => `| ${row.join(' | ')} |`)];
 }
-const routeRow = (record             )           => [code(record.path), cell(record.handler), cell(record.methods), cell(record.state), String(record.middleware), cell(record.policies), cell(record.generated)];
+const routeRow = (record             )           => [code(record.path), cell(record.handler), cell(record.methods), cell(record.state),
+  cell(record.sandbox), cell(record.sandboxReason), String(record.middleware), cell(record.policies), cell(record.generated)];
 /** Renders a diff as Markdown: one table per nonempty section, or "No route changes". */
 export function renderRouteDiff(diff           )         {
   if (!hasRouteChanges(diff)) return 'No route changes\n';
   const lines           = [];
-  const routeHeaders = ['Route','Handler','Methods','State','Middleware','Policies','Generated'];
+  const routeHeaders = ['Route','Handler','Methods','State','Sandbox','Sandbox reason','Middleware','Policies','Generated'];
   const section = (title        , list               ) => {
     if (!list.length) return;
     lines.push(`### ${title} (${list.length})`, '', ...table(routeHeaders, list.map(routeRow)), '');

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

@@ -55,6 +55,12 @@ export interface RouteExplanation {
         source: string;
         export: string;
     }[];
+    /** Execution mode for this route's whole `function`/`middleware` chain: `true` for the
+     * QuickJS sandbox, `false` for trusted in-process execution. Route-level, not handler-level:
+     * a native handler with `middleware` runs project code too, and its mode has to be reviewable.
+     * Reported for every route, including those that run no project code at all. */
+    sandbox: boolean;
+    sandboxReason?: string;
     inputs: {
         parameters: ExplainedParameter[];
         body?: RequestBodyPolicy;
@@ -89,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/extensions.d.ts

@@ -83,7 +83,7 @@ export interface RuntimeExtension {
      * extension response's header/size caps, exactly like `authorize`-gating
      * auth/admin extensions. `false` is an explicit, reviewed opt-in a generic,
      * cache-transparent extension (pure request/response middleware with no
-     * gating semantics of its own, like `urlcode-middleware`) makes to say its
+     * gating semantics of its own) makes to say its
      * `middleware()` hook never depends on withholding the response from
      * shared caches: the wrapped route's own declared cache headers pass
      * through unchanged, exactly as the native `middleware:` array already

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

@@ -1,7 +1,7 @@
 import type { CapabilityName, CapabilityTarget } from './capabilities.ts';
 import type { InspectOptions } from './tooling.ts';
 import type { RouteExplanation } from './explain.ts';
-export declare const MANIFEST_SCHEMA_VERSION = 2;
+export declare const MANIFEST_SCHEMA_VERSION = 3;
 export interface ManifestRoute {
     path: string;
     methods: string[];
@@ -10,6 +10,10 @@ export interface ManifestRoute {
     expires?: string;
     generated?: string;
     description?: string;
+    /** Execution mode for the route's whole `function`/`middleware` chain: `true` for the
+     * QuickJS sandbox, `false` for trusted in-process execution. */
+    sandbox: boolean;
+    sandboxReason?: string;
     middleware: {
         source: string;
         export: string;
@@ -75,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;