@jimhoyd/urlcode 0.4.8 → 0.5.5

package/dist/router.js

@@ -73,7 +73,10 @@ export async function compileRoutes(loaded                , bindings
     const parts = segments(pattern);
     assert(!pattern.startsWith('/_urlcode'), 'The /_urlcode prefix is reserved for runtime operations');
     const names = parts.map(parameterName).filter((name)                 => Boolean(name));
-    assert(!pattern.includes('*') || ((config.static || config.extension) && pattern.endsWith('/*') && parts.filter(p => p.includes('*')).length === 1 && parts.at(-1) === '*' && !names.length), 'Only static or extension routes support a terminal /* wildcard');
+    // `/prefix/**` is the redirect-only suffix wildcard: a literal prefix, one terminal `**`, no path parameters.
+    const wildcardRedirect = Boolean(config.redirect) && pattern.endsWith('/**');
+    if (wildcardRedirect) assert(pattern !== '/**' && pattern.indexOf('*') === pattern.length - 2 && parts.at(-1) === '**' && !names.length && !config.conditional, 'A /** wildcard redirect needs a literal prefix, one terminal **, no path parameters and no conditional');
+    assert(wildcardRedirect || !pattern.includes('*') || ((config.static || config.extension) && pattern.endsWith('/*') && parts.filter(p => p.includes('*')).length === 1 && parts.at(-1) === '*' && !names.length), 'Only static or extension routes support a terminal /* wildcard; a redirect uses a terminal /** instead');
     assert(!config.static || pattern.endsWith('/*'), 'Static routes require a terminal /* wildcard');
     if (config.page || config.download || config.static) assert((config.methods || methodsDefault).every(m => methodsDefault.includes(m)), 'Asset routes support only GET and HEAD');
     assert(new Set(names).size === names.length, 'Duplicate path parameter');
@@ -137,8 +140,21 @@ export async function compileRoutes(loaded                , bindings
     }
     assert(names.every(name => route.parameters.some(p => p.in === 'path' && p.name === name)), 'Every path placeholder requires an input declaration');
     for (const [alias, ref] of Object.entries(config.env || {})) {
-      if (ref.env) assert(permissions.projectSha256 === projectSha256 && permissions.routes?.[pattern]?.env?.includes(ref.env), 'Environment binding denied by operator policy');
-      const value = own(ref, 'value') ? ref.value : bindings[ref.env ];
+      // `env` always requires an operator grant for that route/name. A missing grant is not
+      // fatal when a `default` is declared: the binding just degrades to its literal default
+      // and never reads the host (issue #258). With no `default`, a missing grant still fails
+      // route compilation, as before. `value`-only bindings are plain literals and never
+      // consult the grant or the host environment.
+      let value                    ;
+      if (ref.env) {
+        const granted = permissions.projectSha256 === projectSha256 && permissions.routes?.[pattern]?.env?.includes(ref.env);
+        assert(granted || ref.default !== undefined, 'Environment binding denied by operator policy');
+        const hostValue = bindings[ref.env];
+        const hostSet = ref.default !== undefined ? typeof hostValue === 'string' && hostValue.length > 0 : hostValue !== undefined;
+        value = granted ? (hostSet ? hostValue : ref.default) : ref.default;
+      } else {
+        value = ref.value;
+      }
       assert(typeof value === 'string', 'Missing required environment binding');
       route.env[alias] = value;
     }
@@ -167,14 +183,21 @@ export async function compileRoutes(loaded                , bindings
     if (declaredRedirect) {
       const value = declaredRedirect.url;
       assert(!/[\u0000-\u0020\u007f\\]/u.test(value), 'Redirect URL contains unsafe characters');
+      // A root-relative destination (`/profiles/{id}`) stays on this site: a single leading slash, so never `//host`, and no dot segments.
+      const relative = value.startsWith('/') && !value.startsWith('//');
       let dest     ;
-      try { dest = new URL(value); } catch { assert(false, 'Redirect URL must be absolute HTTP(S)'); }
-      assert(['http:', 'https:'].includes(dest.protocol) && !dest.username && !dest.password, 'Redirect must use HTTP(S) without credentials');
-      const authority = value.match(/^https?:\/\/([^/?#]+)/i)?.[1];
-      assert(authority && !/[{}]/.test(authority) && !/[{}]/.test(dest.search + dest.hash), 'Redirect placeholders are allowed only in path segments');
+      try { dest = new URL(value, relative ? 'https://relative.invalid' : undefined); } catch { assert(false, 'Redirect URL must be an absolute HTTP(S) URL or a root-relative path'); }
+      if (relative) assert(dest.origin === 'https://relative.invalid' && !value.split(/[?#]/, 1)[0] .split('/').some(part => part === '.' || part === '..'), 'Root-relative redirect must be a plain path without dot segments');
+      else {
+        assert(['http:', 'https:'].includes(dest.protocol) && !dest.username && !dest.password, 'Redirect must use HTTP(S) without credentials');
+        const authority = value.match(/^https?:\/\/([^/?#]+)/i)?.[1];
+        assert(authority && !/[{}]/.test(authority), 'Redirect placeholders are allowed only in path segments');
+      }
+      assert(!/[{}]/.test(dest.search + dest.hash), 'Redirect placeholders are allowed only in path segments');
       const placeholders = [...value.matchAll(/\{([^}]+)\}/g)].map(m => m[1] );
-      assert(placeholders.every(n => token.test(n) && names.includes(n)), 'Redirect placeholder must reference a declared path input');
-      assert(!/[{}]/.test(value.replace(/\{[A-Za-z_][A-Za-z0-9_]*\}/g, '')), 'Invalid redirect placeholder');
+      assert(placeholders.every(n => (n === '**' && wildcardRedirect) || (token.test(n) && names.includes(n))), 'Redirect placeholder must reference a declared path input');
+      assert(placeholders.filter(n => n === '**').length <= 1, '{**} may appear once in a redirect destination');
+      assert(!/[{}]/.test(value.replace(/\{(?:[A-Za-z_][A-Za-z0-9_]*|\*\*)\}/g, '')), 'Invalid redirect placeholder');
       const query = declaredRedirect.query || {};
       const reserved = new Set(dest.searchParams.keys());
       for (const [key, ref] of Object.entries(query.map || {})) {
@@ -195,7 +218,8 @@ export async function compileRoutes(loaded                , bindings
       route.function = { ...declaredFunction, source, export: declaredFunction.export || 'default' };
       for (const ref of Object.values(declaredFunction.args || {})) referenceCheck(ref, route, true);
     }
-    if (config.static || config.extension) { route.prefix = pattern.slice(0, -1); mounts.push(route); }
+    if (wildcardRedirect) { route.prefix = pattern.slice(0, -2); route.wildcard = true; mounts.push(route); }
+    else if (config.static || config.extension) { route.prefix = pattern.slice(0, -1); mounts.push(route); }
     else if (!names.length) exact.set(pattern, route);
     else {
       assert(dynamic.length < 1000, 'Maximum 1000 parameterized routes per snapshot');
@@ -215,6 +239,7 @@ export async function compileRoutes(loaded                , bindings
     byLength.get(route.parts.length) .push(route);
   }
   for(const mount of mounts.filter(route=>route.extension)){const base=mount.parts.slice(0,-1);for(const candidate of [...exact.values(),...dynamic,...mounts]){if(candidate===mount)continue;const parts=candidate.parts;const shared=Math.min(base.length,parts.length-(candidate.prefix?1:0));const compatible=base.slice(0,shared).every((part,index)=>part===parts[index]||parameterName(parts[index] ));assert(!compatible||(!candidate.prefix&&parts.length<base.length),'Extension mount overlaps another route');}}
+  assert(new Set(mounts.map(mount => mount.prefix)).size === mounts.length, 'A /** wildcard redirect cannot share its prefix with a static or extension mount');
   mounts.sort((a,b) => b.prefix .length - a.prefix .length);
   assert(performance.now()<deadline, 'Route compilation deadline exceeded');
   return { exact, byLength, mounts, modules: [...modules.keys()], count: exact.size + dynamic.length + mounts.length };

package/dist/runtime.js

@@ -299,6 +299,7 @@ export async function createRuntime(project        , rawOptions
         }
         if (native && !route.middleware.length) return await finishResponse(native);
         context.args = Object.fromEntries(Object.entries(route.function?.args || {}).map(([key, ref]) => [key, resolveValue(ref, context)]));
+        context.route = { pattern: route.pattern };
         // Uniform for `function` and `middleware` alike: a route dispatches
         // through the sandboxed worker pool only when it declares
         // `sandbox: true`; every other route runs trusted, in-process

package/dist/tooling.js

@@ -23,7 +23,11 @@ export {getSchemaFragment,schemaPathNames} from './schema-query.js';
 export {listRecipes,showRecipe,searchRecipes,listExamples,searchExamples};
 export {buildContext,renderContext,estimateTokens,documentationTokens,buildTaskContext,renderTaskContext,contextTasks} from './context.js';
                                                                                                                  
+export {planFeature,featurePlanMaxBytes,featurePlanMaxGoalLength} from './feature-plan.js';
+                                                                      
                                                                                                                                                  
+export {reviewProject} from './review.js';
+                                                                                             
 /** `extensions` are operator registrations from a host file; explain reports whether each requirement has a provider. Nothing is activated. */
                                                                                                                                      
 function routesOf(table                                          )                 {return [...table.exact.values(),...[...table.byLength.values()].flat(),...table.mounts];}

package/dist/types/agents-guide.d.ts

@@ -5,8 +5,13 @@ export declare const mcpConfigFile = ".mcp.json";
 /**
  * Renders `.mcp.json` registering the read-only `urlcode mcp` server for the project at `project`, relative
  * to the file. `--allow-authoring` is deliberately absent: the operator adds it by hand when they want it.
+ * `local` is for a project whose package.json pins the runtime: the server is then launched through `npx --no`,
+ * which uses the installed copy and refuses to fetch anything (a bare `urlcode` is not on PATH for a local-only install,
+ * and `npx urlcode` would resolve an unrelated registry package). Without a pin the bare command is kept for global installs.
  */
-export declare function renderMcpConfig(project?: string): string;
+export declare function renderMcpConfig(project?: string, { local }?: {
+    local?: boolean;
+}): string;
 /**
  * The application-level AGENTS.md written by `urlcode init`. Built from the
  * installed runtime's capability catalog, so it names only the handlers,

package/dist/types/authoring.d.ts

@@ -6,7 +6,9 @@ export interface InitOptions {
      */
     manifest?: DependencySet | undefined;
     /** `default` (function, middleware, redirect) or `page`: urlcode.yaml, public/index.html, a README and fixtures only. */
-    template?: 'default' | 'page' | undefined;
+    template?: 'default' | 'page' | 'redirects' | undefined;
 }
+/** Adds what the starter needs to an existing package.json and changes nothing else; a conflicting script is refused, never overwritten. */
+export declare function mergePackageJson(text: string, scripts: Record<string, string>, dependency: string, version: string): string;
 export declare function initProject(destination: string, { manifest, template }?: InitOptions): Promise<string>;
 export declare function addRedirect(project: string, destination: string, alias?: string | undefined): Promise<string>;

package/dist/types/context.d.ts

@@ -79,11 +79,23 @@ export interface TaskShape {
 }
 /** Established by running `urlcode validate` and `urlcode test` on each shape; test/context.test.ts compiles every `yaml` entry so this cannot drift from the runtime. */
 export declare const redirectShapes: TaskShape[];
+/** A complete, paste-ready project skeleton: every supported shape merged into one urlcode.yaml, plus the start script. */
+export interface TaskStarter {
+    file: string;
+    yaml: string;
+    /** Files the yaml references that must exist, with minimal content. */
+    companions: Record<string, string>;
+    packageScripts: Record<string, string>;
+    note: string;
+}
+/** Merges every supported shape's YAML; test/context-task.test.ts compiles the result, so it cannot drift from the runtime. */
+export declare function redirectStarter(): TaskStarter;
 export interface TaskContext {
     urlcode: string;
     schema: '1';
     task: ContextTask;
     shapes?: TaskShape[];
+    starter?: TaskStarter;
     project?: {
         entry: string;
         routes: number;

package/dist/types/explain.d.ts

@@ -76,6 +76,9 @@ export interface RouteExplanation {
             env: string;
         } | {
             literal: true;
+        } | {
+            env: string;
+            default: string;
         }>;
         secrets: Record<string, {
             secret: string;

package/dist/types/extension-artifacts.d.ts

@@ -1,3 +1,4 @@
+import { type ReleaseAsset } from './extension-transport.ts';
 /** Offline, declarative extension bundles. These are deliberately not Node packages. */
 export declare const ARTIFACT_REPOSITORY = "jimhoyd-com/urlcode";
 export declare const ARTIFACT_WORKFLOW = "jimhoyd-com/urlcode/.github/workflows/extension-artifacts.yml";
@@ -30,14 +31,24 @@ export interface ExtensionLock {
 }
 /** Parse an untrusted catalog only after its GitHub attestation was verified by the caller. */
 export declare function parseCatalog(bytes: Uint8Array, requestedTag: string): Catalog;
+export interface TarFile {
+    path: string;
+    bytes: Uint8Array;
+}
+export interface ArchiveLimits {
+    archive: number;
+    expanded: number;
+    files: number;
+    file: number;
+    label: string;
+}
+/** A minimal tar reader: only regular files are accepted, before any write occurs. */
+export declare function readBoundedTgz(source: Uint8Array, limits: ArchiveLimits): TarFile[];
 export declare function extractArtifact(bytes: Uint8Array, entry: ArtifactEntry, destination: string): Promise<void>;
 export declare function readLock(project: string): Promise<ExtensionLock>;
 export declare function writeLock(project: string, lock: ExtensionLock): Promise<void>;
 export declare function cachePath(project: string, sha256: string): string;
-export interface ReleaseAsset {
-    name: string;
-    url: string;
-}
+export type { ReleaseAsset };
 export interface ArtifactTransport {
     release(tag: string): Promise<ReleaseAsset[]>;
     download(url: string): Promise<Uint8Array>;

package/dist/types/extension-bundles.d.ts

@@ -0,0 +1,49 @@
+/** Verified, executable first-party bundles. Unlike extension artifacts, these are trusted operator code. */
+export declare const BUNDLE_REPOSITORY = "jimhoyd-com/urlcode";
+export declare const BUNDLE_WORKFLOW = "jimhoyd-com/urlcode/.github/workflows/extension-bundles.yml";
+export interface BundleEntry {
+    name: string;
+    version: string;
+    asset: string;
+    sha256: string;
+    entry: string;
+}
+export interface BundleCatalog {
+    format: 1;
+    tag: string;
+    commit: string;
+    coreVersion: string;
+    bundles: BundleEntry[];
+    revoked: {
+        sha256: string;
+        reason: string;
+    }[];
+}
+export interface LockedBundle extends BundleEntry {
+    catalog: {
+        tag: string;
+        commit: string;
+    };
+    coreVersion: string;
+}
+export interface BundleLock {
+    format: 1;
+    bundles: LockedBundle[];
+}
+export interface BundleTransport {
+    release(tag: string): Promise<{
+        name: string;
+        url: string;
+    }[]>;
+    download(url: string): Promise<Uint8Array>;
+    attest(path: string, release: string): Promise<void>;
+}
+/** Parse only a catalog whose attestation was already verified against the requested immutable tag. */
+export declare function parseBundleCatalog(bytes: Uint8Array, requested: string): BundleCatalog;
+export declare function extractBundle(bytes: Uint8Array, item: Pick<LockedBundle, 'name' | 'version' | 'entry' | 'sha256' | 'coreVersion'>, destination: string): Promise<void>;
+export declare function bundleCachePath(project: string, sha256: string): string;
+export declare function readBundleLock(project: string): Promise<BundleLock>;
+export declare const githubBundleTransport: BundleTransport;
+export declare function installBundle(project: string, release: string, bundleName: string, transport?: BundleTransport): Promise<BundleLock>;
+/** Explicit host-only loader. It never reads project YAML, downloads, updates, or discovers code. */
+export declare function loadExtensionBundle(project: string, bundleName: string): Promise<Record<string, unknown>>;

package/dist/types/extension-transport.d.ts

@@ -0,0 +1,31 @@
+/** Shared GitHub release/cache/lockfile plumbing for extension-artifacts.ts and extension-bundles.ts. No opinion on what content is allowed or executable; that trust boundary stays local to each caller (#441). */
+export type UnknownRecord = Record<string, unknown>;
+export declare const isRecord: (v: unknown) => v is UnknownRecord;
+export declare const digestHex: (bytes: Uint8Array) => string;
+export declare function textField(value: unknown, what: string): string;
+export declare function exactKeys(value: UnknownRecord, expected: readonly string[], what: string): void;
+/** Sorted, recursive listing of an extension cache directory; refuses links and special files. */
+export declare function listCachedFiles(root: string, itemLabel: string, prefix?: string): Promise<string[]>;
+/** Atomic write-then-rename for a JSON lockfile, refusing to clobber a concurrent writer. */
+export declare function writeLockAtomic(path: string, temporary: string, data: unknown): Promise<void>;
+export interface ReleaseAsset {
+    name: string;
+    url: string;
+}
+export interface GithubTransport {
+    release(tag: string): Promise<ReleaseAsset[]>;
+    download(url: string): Promise<Uint8Array>;
+    attest(path: string, release: string): Promise<void>;
+}
+export interface GithubTransportConfig {
+    repository: string;
+    workflow: string;
+    tagPattern: RegExp;
+    exampleTag: string;
+    maxAssetSize: number;
+    itemLabel: string;
+}
+/** A transport that accepts only GitHub Release asset URLs and verifies every downloaded subject. */
+export declare function createGithubTransport(config: GithubTransportConfig): GithubTransport;
+/** Downloads one named release asset and has the transport attest it before returning its bytes. */
+export declare function verifiedReleaseAsset(assets: ReleaseAsset[], asset: string, release: string, transport: GithubTransport, itemLabel: string, tempPrefix: string): Promise<Uint8Array>;

package/dist/types/extensions.d.ts

@@ -185,6 +185,8 @@ export interface ScaffoldRequest {
     hostFile: string;
     /** Every extension name being scaffolded together, including this one, in a canonical (sorted) order that is independent of the `--with` spelling. */
     names: readonly string[];
+    /** `npm` resolves extension packages from the operator's install; `bundle` resolves only already-verified, locked release bundles. */
+    distribution?: 'npm' | 'bundle';
     /**
      * Operator acknowledgements from repeated `--ack <extension>:<id>` flags, sorted and de-duplicated; empty when none. Core treats
      * them as opaque strings and never invents one. An extension reads only the ones qualified with its own name. To require one, throw
@@ -224,6 +226,8 @@ export interface ScaffoldResult {
     hostSetup: string[];
     hostEntries: string[];
     hostClose?: string[];
+    /** Named exports core may bind from this extension's already-verified executable bundle. Required for bundle distribution; never a project-controlled module reference. */
+    hostBundleExports?: string[];
     /** Files written relative to `directory` with their modes; never inside the project, never overwriting. */
     files: ScaffoldFile[];
     /** Markdown appended to README.md under a heading core adds; the numbered steps merged in the resolved order. */

package/dist/types/feature-plan.d.ts

@@ -0,0 +1,67 @@
+import type { CapabilityName, CapabilityTarget } from './capabilities.ts';
+import type { RuntimeExtension } from './extensions.ts';
+/** The planner is deliberately a small, local projection. It never treats goal
+ * text as instructions, opens a host, or reads extension/project source. */
+export declare const featurePlanMaxBytes = 32768;
+export declare const featurePlanMaxGoalLength = 512;
+export interface FeaturePlanOptions {
+    target?: string;
+    extensions?: readonly RuntimeExtension[] | undefined;
+}
+export interface FeaturePlan {
+    format: 1;
+    goalTerms: string[];
+    target: CapabilityTarget;
+    project: {
+        routes: number;
+        extensions: string[];
+    };
+    applicable: {
+        capabilities: {
+            name: CapabilityName;
+            support: string;
+            reason: string;
+        }[];
+        recipes: {
+            name: string;
+            description: string;
+            matched: string[];
+        }[];
+    };
+    extensions: {
+        required: {
+            name: string;
+            reason: string;
+            declared: boolean;
+            registered: boolean;
+            target: string;
+            artifact: 'none' | 'cached' | 'missing' | 'invalid';
+        }[];
+        ordering: {
+            status: 'operator-resolved';
+            names: string[];
+            note: string;
+        };
+    };
+    outline: {
+        kind: string;
+        note: string;
+    }[];
+    applicationCode: {
+        requirement: string;
+        reason: string;
+    }[];
+    unsupported: {
+        requirement: string;
+        reason: string;
+    }[];
+    next: string[];
+    estimatedTokens: number;
+}
+/**
+ * Plans only from the current compiled project, package-owned catalogs, locked
+ * inert artifacts, and registrations passed by the already-opened operator
+ * session. It intentionally has no filesystem path, host-file, binding, or
+ * execution argument.
+ */
+export declare function planFeature(project: string, goal: string, options?: FeaturePlanOptions): Promise<FeaturePlan>;

package/dist/types/functions.d.ts

@@ -36,8 +36,12 @@ export interface FunctionWorkerData {
     dependencies: Record<string, string[]>;
     entries: [string, string][];
 }
+/** `route.pattern` is the route key that matched, so one module can serve several routes without reading `request.url`. */
 export type FunctionContext = RequestContext & {
     args?: Record<string, ParameterValue>;
+    route?: {
+        pattern: string;
+    };
 };
 export interface FunctionWorkerRequest {
     id: string;

package/dist/types/index.d.ts

@@ -18,8 +18,8 @@ export { buildTypeScriptProject } from './typescript-authoring.ts';
 export type { TypeScriptBuildReport } from './typescript-authoring.ts';
 export { importBulkProject } from './bulk.ts';
 export type { BulkFormat, BulkFilePlan, BulkImportReport } from './bulk.ts';
-export { inspectProject, validateProject, explainRoute, explainProject, previewImport, previewExport, getCapability, getSchemaFragment, schemaPathNames, inspectExtensions, describeExtensions, buildContext, renderContext, estimateTokens, documentationTokens, buildTaskContext, renderTaskContext, contextTasks } from './tooling.ts';
-export type { InspectOptions, RouteExplanation, RouteMiss, ExplainedHandler, ExplainedCache, ExplainedExtensionRequirement, ExtensionProvider, TargetSupport, CapabilityEntry, CapabilityUsage, SchemaFragment, ExtensionInspection, ContextOptions, ProjectContext, ContextSection, ContextTask, TaskContext, TaskShape } from './tooling.ts';
+export { inspectProject, validateProject, explainRoute, explainProject, previewImport, previewExport, getCapability, getSchemaFragment, schemaPathNames, inspectExtensions, describeExtensions, buildContext, renderContext, estimateTokens, documentationTokens, buildTaskContext, renderTaskContext, contextTasks, planFeature, featurePlanMaxBytes, featurePlanMaxGoalLength } from './tooling.ts';
+export type { InspectOptions, RouteExplanation, RouteMiss, ExplainedHandler, ExplainedCache, ExplainedExtensionRequirement, ExtensionProvider, TargetSupport, CapabilityEntry, CapabilityUsage, SchemaFragment, ExtensionInspection, ContextOptions, ProjectContext, ContextSection, ContextTask, TaskContext, TaskShape, FeaturePlan, FeaturePlanOptions } from './tooling.ts';
 export { buildManifest, renderManifest, MANIFEST_SCHEMA_VERSION } from './manifest.ts';
 export type { Manifest, ManifestRoute, ManifestModule, RecipeProvenance } from './manifest.ts';
 export { serveMcp } from './mcp.ts';
@@ -40,3 +40,5 @@ 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';
+export { installBundle, loadExtensionBundle, readBundleLock, parseBundleCatalog } from './extension-bundles.ts';
+export type { BundleCatalog, BundleEntry, BundleLock, LockedBundle, BundleTransport } from './extension-bundles.ts';

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

@@ -1,5 +1,6 @@
 import type { ScaffoldResult } from './extensions.ts';
 import type { DependencyPin } from './project-dependencies.ts';
+import { type BundleTransport } from './extension-bundles.ts';
 export interface InitWithOptions {
     cwd?: string | undefined;
     /** Default true: record exact pins for core, the named extensions and their declared peers. */
@@ -8,6 +9,10 @@ export interface InitWithOptions {
     pins?: ReadonlyMap<string, string> | undefined;
     /** `--ack <extension>:<id>`, repeatable: opaque qualified acknowledgements handed to every scaffold. Core refuses one that no scaffold consumed. */
     acknowledgements?: readonly string[] | undefined;
+    /** Immutable signed release used instead of resolving executable extension packages from npm. */
+    bundleRelease?: string | undefined;
+    /** Test-only transport injection; production uses GitHub attestation verification. */
+    bundleTransport?: BundleTransport | undefined;
 }
 export interface InitWithResult {
     directory: string;
@@ -30,4 +35,4 @@ export declare function orderScaffolds(results: readonly ScaffoldResult[]): Scaf
  * `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, requested: readonly string[], { cwd, manifest, pins, acknowledgements }?: InitWithOptions): Promise<InitWithResult>;
+export declare function initProjectWith(destination: string, requested: readonly string[], { cwd, manifest, pins, acknowledgements, bundleRelease, bundleTransport }?: InitWithOptions): Promise<InitWithResult>;

package/dist/types/match.d.ts

@@ -37,6 +37,7 @@ export interface MatchableRoute {
     pattern: string;
     parts: string[];
     prefix?: string;
+    wildcard?: boolean;
     extension?: string;
     parameters: CompiledParameter[];
     env: Record<string, string>;

package/dist/types/review.d.ts

@@ -0,0 +1,30 @@
+import type { InspectOptions } from './tooling.ts';
+export type ReviewCategory = 'native-alternative' | 'extension-alternative' | 'gap' | 'manual-review';
+export type ReviewSignal = 'manual-body-validation' | 'manual-cookie-session' | 'global-mutable-state' | 'outbound-network-call' | 'method-dispatch' | 'manual-rate-limit' | 'manual-security-headers';
+export interface ReviewObservation {
+    category: ReviewCategory;
+    signal: ReviewSignal;
+    routes: string[];
+    source: string;
+    line: number;
+    confidence: 'low' | 'medium';
+    reason: string;
+    excerpt: string;
+    capability?: 'request.body' | 'proxy' | 'methods' | 'policies.throttle' | 'policies.security';
+    extension?: string;
+    note: string;
+    /** Set only for an extension-alternative observation when the caller supplied operator registrations (InspectOptions.extensions): whether that extension is actually registered, and, if so, whether the registration is pinned to this project's current revision. Absent when registration state could not be determined (no registrations supplied), in which case `note` stays with the conservative "declared, setup unconfirmed" wording. */
+    registered?: boolean;
+    revisionPinned?: boolean;
+}
+export interface ProjectReview {
+    format: 1;
+    projectSha256: string;
+    routeCount: number;
+    moduleCount: number;
+    observations: ReviewObservation[];
+    summary: Record<ReviewCategory, number>;
+}
+export declare const reviewModuleByteLimit = 1048576;
+export declare const reviewExcerptLimit = 240;
+export declare function reviewProject(project: string, options?: InspectOptions): Promise<ProjectReview>;

package/dist/types/tooling.d.ts

@@ -12,7 +12,11 @@ export type { SchemaFragment } from './schema-query.ts';
 export { listRecipes, showRecipe, searchRecipes, listExamples, searchExamples };
 export { buildContext, renderContext, estimateTokens, documentationTokens, buildTaskContext, renderTaskContext, contextTasks } from './context.ts';
 export type { ContextOptions, ProjectContext, ContextSection, ContextTask, TaskContext, TaskShape } from './context.ts';
+export { planFeature, featurePlanMaxBytes, featurePlanMaxGoalLength } from './feature-plan.ts';
+export type { FeaturePlan, FeaturePlanOptions } from './feature-plan.ts';
 export type { RouteExplanation, ExplainedHandler, ExplainedCache, ExplainedExtensionRequirement, ExtensionProvider, TargetSupport } from './explain.ts';
+export { reviewProject } from './review.ts';
+export type { ProjectReview, ReviewObservation, ReviewCategory, ReviewSignal } from './review.ts';
 /** `extensions` are operator registrations from a host file; explain reports whether each requirement has a provider. Nothing is activated. */
 export interface InspectOptions {
     origin?: string;

package/dist/types/types.d.ts

@@ -19,10 +19,18 @@ export interface ParameterConfig {
     required?: boolean;
     schema: ParameterSchema;
 }
-/** `env` binding: a literal `value`, or the `env` name to read from the process environment. */
+/**
+ * `env` binding: a plain literal `value` (always reviewable, never overridden); or the `env`
+ * name to read from the process environment, with an optional `default` used when that
+ * variable is unset. `env` always requires an operator grant for that route/name — if the
+ * grant is missing, a declared `default` is used with no host read attempted (the binding
+ * degrades to its literal default rather than failing); with no `default`, a missing grant
+ * fails route compilation (docs/yaml/functions.md, "Host overrides").
+ */
 export interface EnvBinding {
     value?: string;
     env?: string;
+    default?: string;
 }
 /** `secrets` binding: the `secret` name to read from the process environment. */
 export interface SecretBinding {
@@ -264,6 +272,7 @@ export interface CompiledRoute extends Omit<RouteConfig, 'methods' | 'parameters
     reply?: Reply;
     expiresAt?: number;
     prefix?: string;
+    wildcard?: boolean;
     middleware: CompiledMiddleware[];
     function?: CompiledFunction;
     respond?: RespondSpec;

package/dist/types.js

@@ -26,8 +26,15 @@
 
 /** One declared input: a path placeholder, a query parameter or a request header. */
                                                                                                                      
-/** `env` binding: a literal `value`, or the `env` name to read from the process environment. */
-                                                            
+/**
+ * `env` binding: a plain literal `value` (always reviewable, never overridden); or the `env`
+ * name to read from the process environment, with an optional `default` used when that
+ * variable is unset. `env` always requires an operator grant for that route/name — if the
+ * grant is missing, a declared `default` is used with no host read attempted (the binding
+ * degrades to its literal default rather than failing); with no `default`, a missing grant
+ * fails route compilation (docs/yaml/functions.md, "Host overrides").
+ */
+                                                                              
 /** `secrets` binding: the `secret` name to read from the process environment. */
                                                  
                                                                                                              
@@ -127,7 +134,7 @@
                                                                                                                                                                             
                                                                                             
                                                                                                 
-                                                                                                                 
+