@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/dist/tooling.js

@@ -0,0 +1,96 @@
+import {loadDocument} from './config.js';
+import {applySite} from './site.js';
+import {prepareFunctionSnapshot,requestedPermissions} from './policy.js';
+import {compileRoutes,matchRoute,parseTarget} from './router.js';
+import {compilePolicies,closePolicies} from './policies.js';
+import {analyzeCompiledCapabilities,routeCapabilities} from './capabilities.js';
+                                                           
+import {importRoutes,exportRoutes} from './interchange.js';
+                                                                            
+import {listRecipes,showRecipe,searchRecipes} from './recipes.js';
+import {listExamples,searchExamples} from './examples.js';
+                                                                       
+import {effectiveExtensionPolicies} from './extensions.js';
+                                                      
+import {loadOperatorHost} from './operator-host.js';
+import {explainCompiledRoute,nearestRoutes} from './explain.js';
+                                                   
+export {getCapabilities} from './capabilities.js';
+export {getCapability} from './capability-query.js';
+                                                                           
+export {getSchemaFragment,schemaPathNames} from './schema-query.js';
+                                                      
+export {listRecipes,showRecipe,searchRecipes,listExamples,searchExamples};
+export {buildContext,renderContext,estimateTokens,documentationTokens} from './context.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];}
+export async function prepare(project       ,options               ={}) {
+ const loaded=await loadDocument(project);await applySite(loaded,{...(options.origin?{origin:options.origin}:{})});
+ const snapshot=await prepareFunctionSnapshot(loaded),bindings                      =Object.create(null);
+ for(const route of Object.values(loaded.routes)) {for(const ref of Object.values(route.env||{}))if(ref.env)bindings[ref.env]='validation-only';for(const ref of Object.values(route.secrets||{}))bindings[ref.secret]='validation-only';}
+ const compiled=await compileRoutes(loaded,bindings,requestedPermissions(loaded,snapshot),snapshot.projectSha256),routes=routesOf(compiled);
+ const shared             ={target:'node',routes:routes.length,log:()=>{}};
+ // The same policy inventory the runtime attaches (src/runtime.ts): compiled for every route when the project declares any.
+ const anyPolicy=Boolean(loaded.document.policies)||routes.some(route=>route.policies),chains=new Map                    ();
+ try {for(const route of routes){const chain=await compilePolicies(loaded.document,route,{route,shared,target:'node',root:loaded.root});if(anyPolicy)chains.set(route.pattern,chain);}}finally{await closePolicies(shared);}
+ return {loaded,compiled,routes,chains,projectSha256:snapshot.projectSha256};
+}
+function compatibilitySummary(report                    ) {return {target:report.target,compatible:report.compatible,deployment:report.deployment,requirementCount:report.requirements.length,issueCount:report.issues.length};}
+/** Semantic authoring inspection; no binding reads, sandbox execution or runtime activation. */
+export async function inspectProject(project       ,options               ={}) {
+ const offset=options.offset??0,limit=options.limit??100;
+ if(!Number.isSafeInteger(offset)||offset<0||!Number.isSafeInteger(limit)||limit<1||limit>1000)throw new Error('Invalid inspection page');
+ const {loaded,compiled,routes,projectSha256}=await prepare(project,options);
+ const report=analyzeCompiledCapabilities(loaded.document,compiled,options.target??'self-hosted');
+ return {format:1,projectSha256,routeCount:compiled.count,offset,limit,routes:routes.slice(offset,offset+limit).map(route=>({path:route.pattern,methods:route.methods,enabled:route.enabled!==false,capabilities:routeCapabilities(route,loaded.document)})),compatibility:{...compatibilitySummary(report),offset,limit,hasMore:offset+limit<report.issues.length,issues:report.issues.slice(offset,offset+limit)}};
+}
+export async function validateProject(project       ,options               ={}) {
+ const result=await inspectProject(project,{...options,offset:0,limit:1});
+ const {target,compatible,deployment,requirementCount,issueCount,issues}=result.compatibility;
+ return {valid:true,projectSha256:result.projectSha256,routeCount:result.routeCount,compatibility:{target,compatible,deployment,requirementCount,issueCount,firstIssue:issues[0]??null}};
+}
+                                                                       
+/** Explain the route a path selects from the compiled IR: effective methods, handler, middleware, inputs, policies, cache outcome, bindings and target support. Nothing executes and no binding is read. */
+export async function explainRoute(project       ,target       ,options               ={})                                     {
+ const {loaded,compiled,chains,projectSha256}=await prepare(project,options),match=matchRoute(compiled,parseTarget(target));
+ if(!match)return {matched:false,nearest:nearestRoutes(target,routesOf(compiled).map(route=>route.pattern)),note:'No route selects this path.'};
+ return explainCompiledRoute(loaded,match.route,chains.get(match.route.pattern),{extensions:options.extensions,projectSha256});
+}
+/** Every route's explanation, in the router's precedence order. */
+export async function explainProject(project       ,options               ={})                                                                             {
+ const {loaded,routes,chains,projectSha256}=await prepare(project,options);
+ return {projectSha256,routeCount:routes.length,routes:routes.map(route=>explainCompiledRoute(loaded,route,chains.get(route.pattern),{extensions:options.extensions,projectSha256}))};
+}
+export async function previewImport(options                    ) {return importRoutes(options);}
+export async function previewExport(project       ,format                  ,acceptProviderDifferences=false) {const loaded=await loadDocument(project);const {includes:_includes,...document}=loaded.document;return exportRoutes({format,document:{...document,routes:loaded.routes},acceptProviderDifferences});}
+                                      
+                                                              
+                                                                                                                                                                                                            
+                                                                                                  
+ 
+/** Reports registered extension contracts against the project's declarations. Never activates an extension. */
+export async function describeExtensions(project       ,registrations                             )                              {
+ const loaded=await loadDocument(project),{projectSha256}=await prepareFunctionSnapshot(loaded),routes=Object.entries(loaded.routes);
+ const declarations=Object.entries(loaded.document.extensions??{});
+ const mountsOf=(name       )=>routes.filter(([,route])=>route.extension===name).map(([path])=>path.endsWith('/*')?path.slice(0,-2):path);
+ const policyRoutesOf=(name       )=>routes.filter(([,route])=>Object.hasOwn(effectiveExtensionPolicies(loaded.document,route),name)).map(([path])=>path);
+ const registered=new Set((registrations??[]).map(registration=>registration.name));
+ const declared=declarations.map(([name,declaration])=>({name,version:String(declaration.version),registered:registered.has(name),mounts:mountsOf(name),policyRoutes:policyRoutesOf(name)}));
+ if(registrations===undefined)return {format:1,projectSha256,hostLoaded:false,note:'Configuration and policy schemas come from the operator host file; supply --host-file to print them.',extensions:[],declared};
+ const extensions=registrations.map(registration=>({
+  name:String(registration.name),version:String(registration.version),targets:Array.isArray(registration.targets)?registration.targets.map(String):[],
+  credentialHeaders:Array.isArray(registration.credentialHeaders)?registration.credentialHeaders.map(String):[],
+  schema:structuredClone(registration.schema??{}),policySchema:registration.policySchema?structuredClone(registration.policySchema):null,
+  declared:Object.hasOwn(loaded.document.extensions??{},registration.name),revisionPinned:registration.projectSha256===projectSha256,
+  mounts:mountsOf(registration.name),policyRoutes:policyRoutesOf(registration.name),
+ }));
+ return {format:1,projectSha256,hostLoaded:true,note:'Schemas describe operator-installed contracts; inspection activates nothing and grants no revision.',extensions,declared};
+}
+/** Executes the trusted operator host file to read its registrations, then releases it. */
+export async function inspectExtensions(options                                  )                              {
+ const host=await loadOperatorHost(options.hostFile,options.project);
+ try{return await describeExtensions(options.project,options.hostFile===undefined?undefined:host.extensions??[]);}finally{await host.close?.();}
+}

package/dist/types/adapters.d.ts

@@ -1,12 +1,15 @@
+import type { RuntimeExtension } from './extensions.ts';
 import type { HostPlugin, OperatorPolicy, Runtime } from './runtime.ts';
-import type { TargetName } from './types.ts';
 /** The subset of process.env a hosted adapter reads. */
 export type Environment = Record<string, string | undefined>;
-export interface NativeOnlyOptions {
-    target?: TargetName | undefined;
+interface NativeOnlyOptions {
+    target: 'aws' | 'vercel';
     plugins?: HostPlugin[] | undefined;
+    extensions?: RuntimeExtension[] | undefined;
+    origin?: string | undefined;
 }
 export declare function readPolicyFromEnvironment(environment: Environment): OperatorPolicy | undefined;
-export declare function activateNativeOnly(project: string, environment: Environment, { target, plugins }?: NativeOnlyOptions): Promise<Runtime>;
+export declare function activateNativeOnly(project: string, environment: Environment, { target, plugins, extensions, origin }: NativeOnlyOptions): Promise<Runtime>;
 export declare function lazyRuntime<T>(activate: () => Promise<T>): () => Promise<T>;
 export declare function resolveOrigin(origin: string | undefined, environment: Environment, platformVariables: string[]): string | undefined;
+export {};

package/dist/types/agent-lists.d.ts

@@ -1,5 +1,4 @@
 import type { AgentEntry, AgentsConfig } from './policies/agents.ts';
-export declare const MAX_LIST_ENTRIES = 4096;
 export declare function loadListFile(root: string, reference: string, routePattern?: string): Promise<AgentEntry[]>;
 export declare function loadListFiles(references: string[], root: string | undefined, routePattern: string): Promise<Record<string, AgentEntry[]>>;
 export declare function resolveLists(config: AgentsConfig | undefined, root: string, routePattern?: string): Promise<AgentsConfig | undefined>;

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

@@ -0,0 +1,17 @@
+/** Where the packaged agent skill lives, relative to the installed @jimhoyd/urlcode package. */
+export declare const skillPath = "skills/urlcode/SKILL.md";
+/** The MCP registration file `urlcode init` writes beside the project (Claude Code and Codex read this shape). */
+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.
+ */
+export declare function renderMcpConfig(project?: string): string;
+/**
+ * The application-level AGENTS.md written by `urlcode init`. Built from the
+ * installed runtime's capability catalog, so it names only the handlers,
+ * policies and site keys this version implements. Under 80 lines by design.
+ */
+export declare function renderAgentsGuide({ routes }: {
+    routes: number;
+}): string;

package/dist/types/authoring-files.d.ts

@@ -0,0 +1,10 @@
+/** Authoring output never copies hidden state, package hooks, or credential files. */
+export declare function authoringPath(path: string): string;
+export declare function authoringFile(root: string, path: string, directory?: boolean): Promise<string>;
+export declare function readAuthoringFile(root: string, path: string, limit: number): Promise<Buffer>;
+/** Reserve a fresh directory exclusively, then publish the entry config last.
+ * Failed writes remove only the directory created by this invocation. No existing
+ * directory (even an empty one) is accepted; consumers see no activatable project
+ * until every dependency has been written. Callers must own the output parent.
+ */
+export declare function publishAuthoringProject(output: string, files: ReadonlyMap<string, Buffer | string>, dryRun?: boolean): Promise<string>;

package/dist/types/aws.d.ts

@@ -1,3 +1,4 @@
+import type { RuntimeExtension } from './extensions.ts';
 import type { Environment } from './adapters.ts';
 import type { HostPlugin } from './runtime.ts';
 export interface LambdaHandlerOptions {
@@ -6,6 +7,7 @@ export interface LambdaHandlerOptions {
     environment?: Environment | undefined;
     maxBodyBytes?: number | undefined;
     plugins?: HostPlugin[] | undefined;
+    extensions?: RuntimeExtension[] | undefined;
 }
 /** A Lambda payload format 2.0 event, as far as this adapter reads it. */
 export interface LambdaEvent {
@@ -32,4 +34,4 @@ export interface LambdaResponse {
     isBase64Encoded: true;
 }
 export type LambdaHandler = (event: unknown) => Promise<LambdaResponse>;
-export declare function createLambdaHandler({ project, origin, environment, maxBodyBytes, plugins }?: LambdaHandlerOptions): LambdaHandler;
+export declare function createLambdaHandler({ project, origin, environment, maxBodyBytes, plugins, extensions }?: LambdaHandlerOptions): LambdaHandler;

package/dist/types/build-cloudflare.d.ts

@@ -10,5 +10,6 @@ export interface BuildReport {
     version: string;
     routes: number;
     validators: number;
+    manifest: string;
 }
 export declare function buildCloudflare(project: string, { out, origin, log }?: BuildOptions): Promise<BuildReport>;

package/dist/types/bulk.d.ts

@@ -0,0 +1,27 @@
+import type { ConversionDiagnostic } from './interchange.ts';
+export type BulkFormat = 'csv' | 'json' | 'yaml';
+export interface BulkFilePlan {
+    path: string;
+    routeCount: number;
+    firstPath?: string;
+    lastPath?: string;
+}
+export interface BulkImportReport {
+    ok: boolean;
+    dryRun: boolean;
+    output?: string;
+    routeCount: number;
+    diagnostics: ConversionDiagnostic[];
+    files: BulkFilePlan[];
+    source: {
+        name: string;
+        format: BulkFormat;
+        sha256: string;
+    };
+}
+/** Import ordinary redirect rows into small, portable include files. There is no
+ * merge mode: duplicate rules and existing output directories are refused. */
+export declare function importBulkProject(text: string, format: BulkFormat, output: string, { dryRun, source }?: {
+    dryRun?: boolean | undefined;
+    source?: string | undefined;
+}): Promise<BulkImportReport>;

package/dist/types/capabilities.d.ts

@@ -0,0 +1,55 @@
+import type { CompiledRoute, CompiledRouteTable, LoadedDocument, PolicySupport, ProjectDocument, RouteConfig } from './types.ts';
+export declare const capabilityTargets: readonly ["self-hosted", "cloudflare", "aws", "vercel"];
+export type CapabilityTarget = typeof capabilityTargets[number];
+export type CapabilitySupport = PolicySupport | 'conditional' | 'unknown';
+export declare const capabilityNames: readonly ["extension", "policies.extensions", "proxy", "signals", "conditional", "conditions", "redirect", "respond", "page", "static", "download", "function", "middleware", "link", "dynamicLinks", "parameters", "methods", "enabled", "expires", "request.body", "response.headers", "bindings", "policies.agents", "policies.security", "policies.cache", "policies.compression", "policies.throttle"];
+export type CapabilityName = typeof capabilityNames[number];
+export interface CapabilityDecision {
+    support: CapabilitySupport;
+    reason: string;
+}
+export interface CapabilityRequirement extends CapabilityDecision {
+    path: string;
+    capability: CapabilityName;
+}
+export interface CompatibilityReport {
+    target: CapabilityTarget;
+    compatible: boolean;
+    requirements: CapabilityRequirement[];
+    issues: CapabilityRequirement[];
+    deployment: 'local-runtime' | 'unverified';
+}
+export interface CapabilityCatalog {
+    format: 1;
+    targets: {
+        target: CapabilityTarget;
+        deployment: CompatibilityReport['deployment'];
+    }[];
+    capabilities: {
+        capability: CapabilityName;
+        targets: Partial<Record<CapabilityTarget, CapabilityDecision>>;
+    }[];
+}
+export declare function normalizeCapabilityTarget(target: string): CapabilityTarget;
+/** Catalog, not a claim that every configuration or provider deployment works. */
+export declare function getCapabilities(target?: string): CapabilityCatalog;
+/** A safe projection shared by declaration preflight and the existing compiled IR. No values escape. */
+export declare function routeCapabilities(route: RouteConfig | CompiledRoute, document: ProjectDocument): CapabilityName[];
+/** Preflight only: call after schema validation/site expansion, before resolving bindings. */
+export declare function analyzeProjectCapabilities(loaded: LoadedDocument, target: string): CompatibilityReport;
+/** Analyze normalized route semantics without exporting validators, resources or resolved secrets. */
+export declare function analyzeCompiledCapabilities(document: ProjectDocument, compiled: CompiledRouteTable, target: string): CompatibilityReport;
+export declare function assertTargetCompatibility(report: CompatibilityReport): void;
+export declare function formatCapabilities(catalog: CapabilityCatalog): string;
+export type CapabilityKind = 'handler' | 'policy' | 'routing' | 'request' | 'binding' | 'egress' | 'middleware' | 'project';
+export interface CapabilityDetail {
+    kind: CapabilityKind;
+    summary: string;
+    /** Dotted schema paths (`urlcode schema <path>`) whose fragments describe this capability's YAML. */
+    schema: string[];
+    constraints: string[];
+    /** Operator authority the capability needs at activation; never binding values. */
+    grants: string[];
+}
+/** Static facts about each catalog entry. Per-target support stays in `decision`; recipe and cookbook usage is scanned by `getCapability`. */
+export declare const capabilityDetails: Record<CapabilityName, CapabilityDetail>;

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

@@ -0,0 +1,24 @@
+import { formatCapabilities } from './capabilities.ts';
+import type { CapabilityDecision, CapabilityDetail, CapabilityName, CapabilityTarget } from './capabilities.ts';
+import type { SchemaFragment } from './schema-query.ts';
+export interface CapabilityUsage {
+    file: string;
+    routes: string[];
+}
+export interface CapabilityEntry extends CapabilityDetail {
+    format: 1;
+    name: CapabilityName;
+    schemaFragments: SchemaFragment[];
+    targets: Record<CapabilityTarget, CapabilityDecision>;
+    refused: {
+        target: CapabilityTarget;
+        reason: string;
+    }[];
+    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;
+export { formatCapabilities };

package/dist/types/catalog.d.ts

@@ -0,0 +1,65 @@
+import type { CapabilityName, CapabilityTarget } from './capabilities.ts';
+/**
+ * The metadata shape shared by recipes/NAME/recipe.yaml and examples/NAME/example.yaml
+ * (schemas/recipe.schema.json). The catalog entries are fixed package data: names
+ * come from a list in code, never from a directory scan, a registry or an argument.
+ */
+export type TargetVerdict = 'compatible' | 'conditional' | 'refused' | 'unknown';
+export type Complexity = 'starter' | 'intermediate' | 'advanced';
+export interface CatalogMetadata {
+    id: string;
+    description: string;
+    tags: string[];
+    complexity: Complexity;
+    runnable?: boolean;
+    capabilities?: string[];
+    targets?: Record<CapabilityTarget, TargetVerdict>;
+    routes?: number;
+    services?: {
+        name: string;
+        description: string;
+    }[];
+    grants?: {
+        kind: string;
+        description: string;
+    }[];
+    inputs?: {
+        name: string;
+        file: string;
+        description: string;
+    }[];
+    files: string[];
+    tests?: {
+        fixtures?: string;
+        commands: string[];
+    };
+    behavior?: string[];
+}
+/** The fields the capability preflight determines; `npm run check` refuses hand-written values that differ. */
+export interface DerivedMetadata {
+    capabilities: CapabilityName[];
+    targets: Record<CapabilityTarget, TargetVerdict>;
+    routes: number;
+}
+export interface SearchHit<T extends CatalogMetadata> {
+    entry: T;
+    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. */
+export declare function deriveMetadata(root: string): Promise<DerivedMetadata>;
+/** Reports where hand-written derived fields disagree with the preflight; empty means consistent. */
+export declare function derivedDifferences(metadata: CatalogMetadata, derived: DerivedMetadata): string[];
+export declare function searchTerms(text: string): string[];
+/**
+ * Local search over id, description, tags and capabilities: every term must match
+ * somewhere; the score prefers whole-tag and id hits over description substrings.
+ * Ties keep catalog order, so the smallest entry wins when a caller sorts by size first.
+ */
+export declare function searchMetadata<T extends CatalogMetadata>(entries: readonly T[], text: string, extraText?: (entry: T) => string[]): SearchHit<T>[];

package/dist/types/client-address.d.ts

@@ -4,6 +4,5 @@ export interface Cidr {
 }
 export declare function parseCidr(text: string): Cidr;
 export declare function compileTrustedProxies(list?: string | string[]): Cidr[];
-export declare function isTrustedProxy(address: string, trusted: Cidr[]): boolean;
 export declare function resolveClient(peer: string | undefined, forwarded: string | undefined, trusted: Cidr[]): string | undefined;
 export declare function normalizeAddress(address: unknown): string | undefined;

package/dist/types/compliance-rules/baseline.d.ts

@@ -1,12 +1,4 @@
-import type { ComplianceRule, ProjectRule, RouteRule } from '../compliance.ts';
+import type { ComplianceRule, ProjectRule } from '../compliance.ts';
 export declare const profile = "baseline";
-export declare const securityHeaders: RouteRule;
-export declare const hstsOrigin: ProjectRule;
-export declare const secretsCompression: RouteRule;
-export declare const secretsNoStore: RouteRule;
-export declare const cacheControlDeclared: RouteRule;
-export declare const throttleFunctions: RouteRule;
 export declare const robots: ProjectRule;
-export declare const expiredRoutes: ProjectRule;
-export declare const managementPrivate: ProjectRule;
 export declare const rules: readonly ComplianceRule[];

package/dist/types/compliance-rules/privacy.d.ts

@@ -1,6 +1,3 @@
-import type { ComplianceRule, ProjectRule, RouteRule } from '../compliance.ts';
+import type { ComplianceRule } from '../compliance.ts';
 export declare const profile = "privacy";
-export declare const requestLogMinimal: ProjectRule;
-export declare const linkEventsOff: ProjectRule;
-export declare const detailedParameters: RouteRule;
 export declare const rules: readonly ComplianceRule[];

package/dist/types/compliance-rules/strict.d.ts

@@ -1,9 +1,4 @@
 import type { ComplianceRule, RouteRule } from '../compliance.ts';
 export declare const profile = "strict";
-export declare const headerBudgetBytes = 8192;
 export declare const csp: RouteRule;
-export declare const throttleAll: RouteRule;
-export declare const listsPinned: RouteRule;
-export declare const redirectHttps: RouteRule;
-export declare const headerBudget: RouteRule;
 export declare const rules: readonly ComplianceRule[];

package/dist/types/conditions.d.ts

@@ -0,0 +1,19 @@
+/** Bounded conjunction of exact string comparisons; no regex or implicit detection. */
+export interface RouteMatch {
+    query?: Record<string, string>;
+    headers?: Record<string, string>;
+    cookies?: Record<string, string>;
+    host?: string;
+    method?: string;
+}
+export interface ConditionRequest {
+    query: URLSearchParams;
+    headers: Headers;
+    method: string;
+    origin: string;
+    headerCounts?: Record<string, number> | undefined;
+}
+export declare function normalizeMatch(match: RouteMatch): RouteMatch;
+/** Cases must be disjoint: at least one shared fact must demand different values. */
+export declare function assertDisjointMatches(matches: RouteMatch[]): void;
+export declare function matchesRoute(match: RouteMatch, request: ConditionRequest): boolean;

package/dist/types/config.d.ts

@@ -1,4 +1,4 @@
-import type { LoadedDocument, ProjectDocument } from './types.ts';
+import type { AuthoredRouteConfig, LoadedDocument, ProjectDocument, RouteConfig } from './types.ts';
 /** What config-worker.ts posts back: the loaded document, or the ConfigError message. */
 export type ConfigWorkerResult = {
     value: LoadedDocument;
@@ -11,11 +11,29 @@ export interface ConfigWorkerData {
 export declare const MAX_CONFIG_BYTES: number;
 export declare function parseYaml(text: string): unknown;
 export declare function validateDocument(data: unknown): ProjectDocument;
+/** The input declaration a short-form function gets for each `{param}` it does not declare itself. */
+export declare const SHORT_FORM_PATH_SCHEMA: {
+    readonly type: "string";
+    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}`.
+ * 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 const MAX_PROJECT_CONFIG_BYTES: number;
 export declare function loadDocument(project: string, { timeoutMs }?: {
     timeoutMs?: number;
 }): Promise<LoadedDocument>;
+/**
+ * Expands the route-level `auth` short form into the canonical `policies.extensions.auth` requirement so every
+ * downstream consumer (compiler, routes, audit, explain, revision hash) sees one form. `auth: {required: false}`
+ * documents intent and emits nothing. Refuses routes that use both forms or lack an `extensions.auth` declaration.
+ */
+export declare function normalizeRouteAuth(document: Pick<ProjectDocument, 'extensions'>, routes: Record<string, RouteConfig>): void;
 export declare function loadDocumentInWorker(project: string): Promise<LoadedDocument>;
 export declare function loadBindings(root: string, local?: boolean, environment?: Record<string, string | undefined>): Promise<Record<string, string | undefined>>;
 export declare function functionFile(root: string, file: string): Promise<string>;

package/dist/types/context.d.ts

@@ -0,0 +1,65 @@
+export interface ContextOptions {
+    /** Restrict the target table to one capability target. */
+    target?: string | undefined;
+    /** Absolute path to a trusted operator host module outside the project; its extensions and plugins are counted, never run. */
+    hostFile?: string | undefined;
+    /** Estimated token budget; sections are dropped in a fixed order until the YAML rendering fits. */
+    budget?: number | undefined;
+    /** What `--project` should say in the emitted commands; defaults to the project argument itself. */
+    projectFlag?: string | undefined;
+}
+export type ContextSection = 'routes' | 'targets' | 'constraintNotes' | 'files' | 'commands' | 'summary';
+export interface ProjectContext {
+    urlcode: string;
+    schema: '1';
+    project: {
+        entry: string;
+        routes: number;
+        handlers: Record<string, number>;
+        extensions: string[];
+        policies: {
+            project: string[];
+            routes: Record<string, number>;
+        };
+        bindings: {
+            env: string[];
+            secrets: string[];
+        };
+        dynamicLinks: boolean;
+        site: string[];
+        files?: {
+            includes: string[];
+            functions: string[];
+            middleware: string[];
+        };
+        host?: {
+            extensions: string[];
+            plugins: number;
+        };
+    };
+    routes?: {
+        path: string;
+        methods: string[];
+        handler: string;
+    }[];
+    constraints: Record<string, boolean | string | {
+        value: boolean | string;
+        note: string;
+    }>;
+    targets?: Record<string, {
+        deployment: string;
+        supported: string[];
+        conditional: string[];
+        refused: string[];
+        unknown: string[];
+    }>;
+    commands?: Record<string, string>;
+    omitted?: ContextSection[];
+}
+/** Characters divided by four, rounded up: an estimate, not a tokenizer. */
+export declare function estimateTokens(text: string): number;
+export declare function renderContext(context: ProjectContext): string;
+/** Derived only from the compiled project and the capability catalog, never from prose. Key order is fixed. */
+export declare function buildContext(project: string, options?: ContextOptions): Promise<ProjectContext>;
+/** Estimated size of the shipped documentation (docs/*.md and llms.txt), for comparison with an emitted context. */
+export declare function documentationTokens(): Promise<number>;

package/dist/types/ecosystem-cli.d.ts

@@ -0,0 +1,17 @@
+interface Options {
+    json?: boolean | undefined;
+    project: string;
+    out?: string | undefined;
+    format?: string | undefined;
+    input?: string | undefined;
+    target?: string | undefined;
+    origin?: string | undefined;
+    'dry-run'?: boolean | undefined;
+    'timeout-ms'?: string | undefined;
+    release?: string | undefined;
+    'git-commit'?: string | undefined;
+    'allow-authoring'?: boolean | undefined;
+    'host-file'?: string | undefined;
+}
+export declare function runEcosystemCommand(command: string, args: string[], options: Options, print: (value: unknown) => unknown): Promise<void>;
+export {};

package/dist/types/egress.d.ts

@@ -0,0 +1,46 @@
+import { request } from 'node:https';
+export declare const EGRESS_DNS_LIMIT = 64;
+export interface EgressRequest {
+    url: string;
+    method: string;
+    headers?: Record<string, string>;
+    body?: Uint8Array;
+    signal?: AbortSignal;
+}
+export interface EgressResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: Buffer;
+}
+export interface EgressOptions {
+    grantOrigins: string[];
+    timeoutMs?: number;
+    maxRequestBytes?: number;
+    maxResponseBytes?: number;
+    maxHeaderBytes?: number;
+    concurrency?: number;
+}
+type EgressErrorCode = 'denied' | 'busy' | 'closed' | 'aborted' | 'timeout' | 'limit' | 'upstream';
+export declare class EgressError extends Error {
+    readonly code: EgressErrorCode;
+    constructor(code: EgressErrorCode);
+}
+/** Conservative public-unicast filter. IPv4-mapped IPv6 and transition mechanisms are denied. */
+export declare function isPublicAddress(address: string): boolean;
+export declare function egressUrl(value: string): URL;
+export declare function safeEgressHeaders(headers: Record<string, string>, maxBytes?: number): Record<string, string>;
+/** Operator-owned transport. Never exposed to guests. Each request has its own nonpooled socket. */
+export interface EgressDependencies {
+    resolve?: (hostname: string) => Promise<{
+        address: string;
+        family: number;
+    }[]>;
+    request?: typeof request;
+}
+export declare class EgressClient {
+    #private;
+    constructor(options: EgressOptions, dependencies?: EgressDependencies);
+    request(input: EgressRequest): Promise<EgressResponse>;
+    close(): Promise<void>;
+}
+export {};

package/dist/types/examples.d.ts

@@ -0,0 +1,50 @@
+import type { CatalogMetadata } from './catalog.ts';
+/** example.yaml, the same schema as recipe.yaml; `name` repeats `id`. */
+export interface ExampleSummary extends CatalogMetadata {
+    name: string;
+}
+/** One cookbook route in the generated tag index (examples/cookbook/route-index.json). */
+export interface RouteIndexEntry {
+    path: string;
+    file: string;
+    handler: string;
+    methods: string[];
+    tags: string[];
+    description: string;
+}
+export interface RouteIndex {
+    format: 1;
+    project: string;
+    routes: number;
+    entries: RouteIndexEntry[];
+}
+export interface ExampleSearchResult {
+    query: string;
+    count: number;
+    /** The smallest matching runnable example, and its best matching cookbook route when the cookbook is that example. */
+    best: (ExampleSummary & {
+        route?: RouteIndexEntry;
+    }) | null;
+    results: (ExampleSummary & {
+        score: number;
+        matched: string[];
+        matchedRoutes: RouteIndexEntry[];
+    })[];
+}
+export declare const exampleNames: readonly ["assets", "aws", "cloudflare", "compliance", "conditions", "cookbook", "egress", "extensions", "live-links", "monitoring", "prerender", "provider-conformance", "tunnel", "vercel"];
+export declare const routeIndexFile = "route-index.json";
+export declare function listExamples(): Promise<ExampleSummary[]>;
+/**
+ * Derives the per-route tag index of one project from its loaded routes: handler,
+ * methods, capabilities, policy names and middleware module names. The file each
+ * route comes from is read from the entry and its includes; routes that neither
+ * declares were generated by `site`.
+ */
+export declare function buildRouteIndex(project: string, label: string): Promise<RouteIndex>;
+export declare function readRouteIndex(name: string): Promise<RouteIndex>;
+/**
+ * Searches example.yaml files and the cookbook's per-route index locally. Results
+ * are ordered smallest runnable example first, so `best` is the least code that
+ * demonstrates the match; cookbook hits carry their matching routes.
+ */
+export declare function searchExamples(text: string): Promise<ExampleSearchResult>;