@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/dist/types/extensions.d.ts

@@ -0,0 +1,177 @@
+import type { HandlerResult } from './http-response.ts';
+import type { ProjectDocument, RouteConfig, TargetName } from './types.ts';
+export type { HandlerResult } from './http-response.ts';
+export interface ExtensionDeclaration {
+    version: '1';
+    config: Record<string, unknown>;
+}
+export type ExtensionPolicies = Record<string, Record<string, unknown> | false>;
+/**
+ * `root` is the project's resolved absolute directory (the same value
+ * `loadDocument()` computes and `functionFile()`/router.ts resolves
+ * `function`/`middleware` `source` entries against). It is not the process's
+ * `cwd()`: `--project`/`--host-file` are independent paths, a server can be
+ * started from any working directory, and the JS API can load a project
+ * programmatically with no relationship to `cwd()` at all. An extension that
+ * resolves project-relative paths of its own (for example, an alternative
+ * middleware source it loads by convention rather than through core's native
+ * `middleware:` array) must resolve them against this field, never `cwd()`.
+ */
+export interface ExtensionActivation {
+    origin: string;
+    target: TargetName;
+    projectSha256: string;
+    mounts: readonly string[];
+    root: string;
+}
+export interface ExtensionRequest {
+    method: string;
+    target: string;
+    path: string;
+    query: URLSearchParams;
+    headers: Headers;
+    headerCounts: Record<string, number>;
+    body: Uint8Array;
+    origin: string;
+    route: string;
+    mount: string | null;
+    client: string | null;
+}
+export interface ExtensionInstance {
+    handle(request: ExtensionRequest): HandlerResult | Promise<HandlerResult>;
+    authorize?(requirement: Readonly<Record<string, unknown>>, request: ExtensionRequest): HandlerResult | undefined | Promise<HandlerResult | undefined>;
+    /**
+     * Wrap semantics, not gate semantics: attached the same way as `authorize`
+     * (policies.extensions.<name> on a route, `config` the same validated
+     * per-route value `authorize`'s `requirement` receives), but given `next`,
+     * a callable invoking the rest of the pipeline for this route (any other
+     * declared extension `middleware()` after this one, then the route's own
+     * native `middleware:` chain and handler) at most once. Calling it lets
+     * this hook run code before and after the rest of the pipeline, inspecting
+     * or mutating the `HandlerResult` it resolves to; skipping it short-circuits
+     * the rest of the pipeline entirely, the same way `authorize` can. Never
+     * touches the native `middleware:` array or its own sandboxed/trusted
+     * dispatch, and never runs before `authorize` on the same route.
+     */
+    middleware?(config: Readonly<Record<string, unknown>>, request: ExtensionRequest, next: () => Promise<HandlerResult>): HandlerResult | Promise<HandlerResult>;
+    close?(): void | Promise<void>;
+}
+/** Trusted operator code only. YAML declares names/configuration, never modules. */
+/**
+ * Content-hashed assets under `<mount><prefix>/` may be cached publicly. The
+ * extension owns the hashed filename; the runtime only relaxes its no-store floor
+ * for a GET/HEAD 200/304 that carries a strong ETag, sets no cookie and does not
+ * vary on credentials. Everything else under the mount stays no-store.
+ */
+export interface ExtensionImmutableAssets {
+    prefix: string;
+}
+export interface RuntimeExtension {
+    name: string;
+    version: '1';
+    projectSha256: string;
+    targets: TargetName[];
+    schema: object;
+    policySchema?: object;
+    credentialHeaders?: string[];
+    immutableAssets?: ExtensionImmutableAssets;
+    /**
+     * Reviewed, operator-declared cache sensitivity for `policies.extensions.<name>`
+     * routes (never for an `extension:` mount, which is always treated as
+     * sensitive). Omitted or `true`: the current, safe default — the runtime
+     * forces `Cache-Control: no-store`, disables compression and applies the
+     * 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
+     * `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
+     * does. A route naming more than one extension is treated as sensitive if
+     * any of them is (or leaves this unset) — this can only relax the no-store
+     * floor, never weaken it, and it never changes whether `authorize()` runs.
+     */
+    cacheSensitive?: boolean;
+    activate(config: Readonly<Record<string, unknown>>, context: ExtensionActivation): ExtensionInstance | Promise<ExtensionInstance>;
+}
+/** `urlcode init --with <name>` contract: what core hands `@jimhoyd/urlcode-<name>`'s `scaffold` export. Nothing is written by `scaffold`. */
+export interface ScaffoldRequest {
+    /** Absolute site directory core creates; `files` paths in the result are relative to it. */
+    directory: string;
+    /** Absolute route project directory (holds urlcode.yaml), `<directory>/app`. */
+    project: string;
+    /** Absolute path of the combined host module core writes, `<directory>/host.mjs`. */
+    hostFile: string;
+    /** Every extension name being scaffolded together, in `--with` order, including this one. */
+    names: readonly string[];
+}
+export interface ScaffoldFile {
+    path: string;
+    content: string | Uint8Array;
+    mode?: number;
+}
+export interface ScaffoldResult {
+    /** Must equal the requested name. */
+    name: string;
+    /** Fragments merged into the project's top-level `extensions` and `routes`; duplicate keys are refused. */
+    extensions: Record<string, unknown>;
+    routes: Record<string, unknown>;
+    /** Host module lines: imports, then setup statements, then entries of the `extensions` array, then `close` statements. */
+    hostImports: string[];
+    hostSetup: string[];
+    hostEntries: string[];
+    hostClose?: 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 `--with` order. */
+    readme: string;
+    nextSteps: string[];
+    /** Environment variables the host reads, with one-line descriptions. */
+    env?: Record<string, string>;
+}
+export interface ActiveExtension {
+    instance: ExtensionInstance;
+    policies: Map<string, Readonly<Record<string, unknown>>>;
+    assetPrefixes: readonly string[];
+}
+/** What the runtime knows about the request when it applies the privacy floor. */
+export interface ExtensionAssetContext {
+    method: string;
+    path: string;
+    prefixes: readonly string[];
+}
+export interface ExtensionRegistry {
+    entries: Map<string, ActiveExtension>;
+    credentialHeaders: string[];
+    close(): Promise<void>;
+}
+export declare const immutableCacheControl = "public, max-age=31536000, immutable";
+/** Inspection alone grants nothing; operators must explicitly pin the returned revision. */
+export declare function inspectExtensionRevision(project: string): Promise<string>;
+export declare function effectiveExtensionPolicies(document: ProjectDocument, route: Pick<RouteConfig, 'policies'>): Record<string, Record<string, unknown>>;
+export declare function hasExtensionPolicy(document: ProjectDocument, route: Pick<RouteConfig, 'policies'>): boolean;
+/**
+ * Whether a route naming these `policies.extensions` names must be treated as
+ * confidential (forced no-store, no compression, extension response caps).
+ * `names` with no entries is never confidential. Without a `registrations`
+ * list to consult (a build path with no operator host loaded), every name is
+ * treated as sensitive: the safe default this can only relax, never weaken.
+ * A name whose registration is missing, or declares no `cacheSensitive` (or
+ * `true`), counts as sensitive; only an explicit `cacheSensitive: false`
+ * excuses it, and one sensitive name among several makes the whole route
+ * confidential.
+ */
+export declare function isSensitiveExtensionPolicy(names: readonly string[], registrations?: readonly Pick<RuntimeExtension, 'name' | 'cacheSensitive'>[]): boolean;
+export declare function prepareExtensions(document: ProjectDocument, routes: Record<string, RouteConfig>, registrations: RuntimeExtension[] | undefined, context: Omit<ExtensionActivation, 'mounts'>): {
+    activate(): Promise<ExtensionRegistry>;
+};
+/**
+ * The runtime decides; the extension cannot opt in from a response alone. The
+ * declared prefix, the GET/HEAD method, a 200/304 status, one strong ETag, no
+ * Set-Cookie and no Vary on Cookie/Authorization are all required. A stricter
+ * Cache-Control the extension set (no-store, no-cache, private or a shorter
+ * max-age) is preserved.
+ */
+export declare function immutableAssetResponse(result: HandlerResult, asset: ExtensionAssetContext | undefined): boolean;
+/** Mandatory privacy floor after trusted response hooks, with bounded output. */
+export declare function extensionResponse(result: HandlerResult, asset?: ExtensionAssetContext): HandlerResult;

package/dist/types/function-sources.d.ts

@@ -17,5 +17,14 @@ export interface FunctionSources {
     /** Absolute source path to module name. */
     names: Map<string, string>;
 }
+/** Snapshot budgets: what one set of guest modules may cost. Deliberate bounds
+ * of the sandbox contract (docs/FUNCTION-SECURITY.md), not tuning knobs. */
+export declare const MODULE_LIMIT = 128;
+export declare const MODULE_BYTE_LIMIT = 1048576;
+export declare const TOTAL_BYTE_LIMIT = 4194304;
 export declare function routeFunctions<D>(route: FunctionRoute<D>): D[];
+export declare function collectTrustedSources(routes: FunctionRoute[], root: string): Promise<Record<string, string>>;
+export declare function collectSourcesFor(definitions: FunctionDefinition[], root: string): Promise<FunctionSources>;
+/** Route-shaped convenience over `collectSourcesFor`: every existing caller (policy.ts,
+ * prerender.ts, typescript-authoring.ts) keeps working unchanged from `FunctionRoute[]`. */
 export declare function collectFunctionSources(routes: FunctionRoute[], root: string): Promise<FunctionSources>;

package/dist/types/functions.d.ts

@@ -1,12 +1,28 @@
 import { Worker } from 'node:worker_threads';
-import type { FunctionRoute, FunctionSources } from './function-sources.ts';
+import type { FunctionDefinition, FunctionRoute, FunctionSources } from './function-sources.ts';
 import type { HandlerResult, HeaderPair } from './http-response.ts';
 import type { ParameterValue, RequestContext } from './match.ts';
 import type { LogFn } from './types.ts';
 import type { GuestRequestPayload } from './guest-api.ts';
 export type { FunctionDefinition, FunctionRoute } from './function-sources.ts';
 export type { GuestRequestPayload, GuestResponsePayload } from './guest-api.ts';
-export interface FunctionPoolOptions {
+/** A module entry point the sandbox must load: an absolute source file path
+ * (already resolved and validated, e.g. via `functionFile()`) plus which
+ * export of it needs to be reachable. The same shape a `FunctionDefinition`
+ * already uses for `function`/`middleware` routes. */
+export type SandboxEntry = FunctionDefinition;
+/** What one `SandboxPool.execute()` call invokes: the same `{source, export}`
+ * shape as a `SandboxEntry`, naming one of the pool's declared entries. */
+export type SandboxTarget = FunctionDefinition;
+/** `entry` runs last (the route's `function`/handler); `chain` runs first, in
+ * order, each with `(request, context, next)` — the same wrap/middleware
+ * semantics `__invokePipeline` already gives sandboxed routes. Neither is
+ * required: an empty invocation with a `native` reply just returns it. */
+export interface SandboxInvocation {
+    entry?: SandboxTarget | undefined;
+    chain?: SandboxTarget[] | undefined;
+}
+export interface SandboxPoolOptions {
     root?: string | undefined;
     snapshot?: FunctionSources | undefined;
     workers?: number | undefined;
@@ -14,6 +30,7 @@ export interface FunctionPoolOptions {
     maxBytes?: number | undefined;
     log?: LogFn | undefined;
 }
+export type FunctionPoolOptions = SandboxPoolOptions;
 export interface FunctionWorkerData {
     sources: Record<string, string>;
     dependencies: Record<string, string[]>;
@@ -52,6 +69,7 @@ export type FunctionWorkerMessage = {
     headers: HeaderPair[];
     body: Uint8Array;
     nativeBody: boolean;
+    contentLength?: number;
 } | {
     id: string;
     error: true;
@@ -67,9 +85,9 @@ interface Slot {
     ready: boolean;
     pending: Pending | null;
 }
-export declare class FunctionPool {
+export declare class SandboxPool {
     root: string | undefined;
-    routes: FunctionRoute[];
+    entries: SandboxEntry[];
     preparedSnapshot: FunctionSources | undefined;
     snapshot: FunctionSources | undefined;
     restarts: Map<number, number>;
@@ -81,12 +99,37 @@ export declare class FunctionPool {
     size: number;
     slots: (Slot | undefined)[];
     closed: boolean;
-    constructor(routes: FunctionRoute[], { root, snapshot, workers, timeoutMs, maxBytes, log }?: FunctionPoolOptions);
+    constructor(entries: SandboxEntry[], { root, snapshot, workers, timeoutMs, maxBytes, log }?: SandboxPoolOptions);
     start(): Promise<this>;
     spawn(index: number): Promise<void>;
     report(status: string, index: number, extra?: object): void;
     scheduleRespawn(index: number): void;
     get healthy(): boolean;
+    /** `invocation.entry` runs last (chain-wrapped), `invocation.chain` first, in
+     * declared order — the same `__invokePipeline` wrap/middleware discipline
+     * (`next()` callable at most once) the sandboxed route path already
+     * enforces; there is no second dispatch mechanism for this. Every entry and
+     * chain source named here must already be one of this pool's declared
+     * `entries` (constructor), or the worker's own module allowlist denies it. */
+    execute(invocation: SandboxInvocation, request: GuestRequestPayload, context: FunctionContext, native: HandlerResult | undefined): Promise<FunctionResult>;
+    close(): Promise<void>;
+}
+export declare class FunctionPool {
+    routes: FunctionRoute[];
+    private pool;
+    constructor(routes: FunctionRoute[], options?: FunctionPoolOptions);
+    start(): Promise<this>;
     execute(route: FunctionRoute, request: GuestRequestPayload, context: FunctionContext, native: HandlerResult | undefined): Promise<FunctionResult>;
+    scheduleRespawn(index: number): void;
     close(): Promise<void>;
+    get healthy(): boolean;
+    get restarts(): Map<number, number>;
+    get restartTimers(): Set<NodeJS.Timeout>;
+    get slots(): (Slot | undefined)[];
+    get size(): number;
+    get closed(): boolean;
+    get snapshot(): FunctionSources | undefined;
+    get log(): LogFn;
+    get timeoutMs(): number;
+    get maxBytes(): number;
 }

package/dist/types/guest-api.d.ts

@@ -12,5 +12,6 @@ export interface GuestResponsePayload {
     headers: HeaderPair[];
     body: string;
     nativeBody?: boolean;
+    contentLength?: number;
 }
 export declare const guestBootstrap: string;

package/dist/types/index.d.ts

@@ -1,11 +1,41 @@
 export { createRuntime } from './runtime.ts';
-export type { Runtime, RuntimeOptions, RuntimeRequest, RequestTrace, LinkReader, LinkStoreBinding, HostPlugin, Observer, TestPlan } from './runtime.ts';
+export type { Runtime, RuntimeOptions, RuntimeRequest, RequestTrace, HostPlugin, Observer, TestPlan } from './runtime.ts';
 export { startServer } from './server.ts';
 export type { Server, ServerOptions } from './server.ts';
 export { loadDocument, validateDocument, parseYaml } from './config.ts';
-export { openLinkStore } from './link-store.ts';
-export type { LinkStore, LinkRow, LinkStoreOptions } from './link-store.ts';
-export { startLinkApi } from './link-api.ts';
-export type { LinkApi, LinkApiOptions } from './link-api.ts';
-export type { LinkEvent, LinkObserverOptions, LinkObserverStats } from './link-events.ts';
 export { events as observabilityEvents, validateObservers, createObserverSink, createMetrics, renderPrometheus } from './observability.ts';
+export { getCapabilities, routeCapabilities, analyzeProjectCapabilities, analyzeCompiledCapabilities, assertTargetCompatibility, normalizeCapabilityTarget } from './capabilities.ts';
+export { capabilityDetails } from './capabilities.ts';
+export type { CapabilityTarget, CapabilityName, CapabilityKind, CapabilityDetail, CapabilitySupport, CapabilityDecision, CapabilityRequirement, CapabilityCatalog, CompatibilityReport } from './capabilities.ts';
+export { importRoutes, exportRoutes } from './interchange.ts';
+export type { InterchangeFormat, ConversionDiagnostic, ConversionCounts, ConversionReport, ImportRoutesOptions, ExportRoutesOptions } from './interchange.ts';
+export { listRecipes, searchRecipes, showRecipe, addRecipe } from './recipes.ts';
+export type { RecipeSummary, Recipe, RecipeAddReport, RecipeSearchResult } from './recipes.ts';
+export { listExamples, searchExamples } from './examples.ts';
+export type { ExampleSummary, ExampleSearchResult, RouteIndex, RouteIndexEntry } from './examples.ts';
+export type { CatalogMetadata, TargetVerdict, Complexity } from './catalog.ts';
+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 } from './tooling.ts';
+export type { InspectOptions, RouteExplanation, RouteMiss, ExplainedHandler, ExplainedCache, ExplainedExtensionRequirement, ExtensionProvider, TargetSupport, CapabilityEntry, CapabilityUsage, SchemaFragment, ExtensionInspection, ContextOptions, ProjectContext, ContextSection } 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';
+export type { McpOptions } from './mcp.ts';
+export { providerConformanceCases, runProviderConformance, verifyProviderDeployment } from './provider-verification.ts';
+export type { VerificationTarget, ProviderProbe, ProviderAnswer, ProviderTransport, ProviderVerificationOptions, ProviderFinding, ProviderVerificationReport } from './provider-verification.ts';
+export { normalizeMatch, assertDisjointMatches, matchesRoute } from './conditions.ts';
+export type { RouteMatch, ConditionRequest } from './conditions.ts';
+export { buildCloudflare } from './build-cloudflare.ts';
+export type { BuildOptions as CloudflareBuildOptions, BuildReport as CloudflareBuildReport } from './build-cloudflare.ts';
+export { buildStatic } from './build-static.ts';
+export type { BuildOptions as StaticBuildOptions, BuildReport as StaticBuildReport, StaticRedirect, StaticObject, RedirectManifest, ObjectManifest } from './build-static.ts';
+export { runProjectTests } from './project-tests.ts';
+export type { ProjectTestOptions, ProjectTestResult } from './project-tests.ts';
+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 type { ScaffoldRequest, ScaffoldResult, ScaffoldFile } from './extensions.ts';

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

@@ -0,0 +1,30 @@
+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";
+export interface InitWithOptions {
+    cwd?: string | undefined;
+}
+export interface InitWithResult {
+    directory: string;
+    project: string;
+    hostFile: string;
+    extensions: string[];
+    projectSha256: string;
+    nextSteps: string[];
+}
+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>;

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

@@ -0,0 +1,16 @@
+import type { ConversionReport } from './interchange.ts';
+interface InterchangeCliOptions {
+    project: string;
+    target?: string | undefined;
+    format?: string | undefined;
+    out?: string | undefined;
+    report?: string | undefined;
+    dryRun?: boolean | undefined;
+    acceptProviderDifferences?: boolean | undefined;
+}
+export declare function readConversionInput(file: string): Promise<string>;
+export declare function runInterchange(command: 'import' | 'export', args: string[], options: InterchangeCliOptions): Promise<{
+    report: ConversionReport;
+    text: string;
+}>;
+export {};

package/dist/types/interchange.d.ts

@@ -0,0 +1,42 @@
+import type { ProjectDocument } from './types.ts';
+export type InterchangeFormat = 'csv' | 'json' | 'yaml' | 'netlify' | 'cloudflare' | 'vercel' | 'netlify-toml';
+export interface ConversionDiagnostic {
+    severity: 'error' | 'warning';
+    code: string;
+    source: string;
+    row?: number;
+    path?: string;
+    message: string;
+}
+export interface ConversionCounts {
+    convertedRoutes: number;
+    nativeEquivalentRoutes: number;
+    runtimeRequiredRoutes: number;
+    unsupportedRows: number;
+    providerDifferenceRoutes: number;
+    fullyScanned: boolean;
+}
+export interface ConversionReport {
+    counts: ConversionCounts;
+    ok: boolean;
+    lossless: boolean;
+    routeCount: number;
+    diagnostics: ConversionDiagnostic[];
+    document?: ProjectDocument;
+    output?: string;
+}
+export interface ImportRoutesOptions {
+    format: InterchangeFormat;
+    text: string;
+    source?: string;
+    acceptProviderDifferences?: boolean;
+}
+export interface ExportRoutesOptions {
+    format: InterchangeFormat;
+    document: ProjectDocument;
+    source?: string;
+    acceptProviderDifferences?: boolean;
+}
+/** Pure conversion: does not read projects, resolve bindings, execute guests or write files. */
+export declare function importRoutes(options: ImportRoutesOptions): Promise<ConversionReport>;
+export declare function exportRoutes(options: ExportRoutesOptions): Promise<ConversionReport>;

package/dist/types/manifest.d.ts

@@ -0,0 +1,79 @@
+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 interface ManifestRoute {
+    path: string;
+    methods: string[];
+    handler: RouteExplanation['handler'];
+    enabled: boolean;
+    expires?: string;
+    generated?: string;
+    description?: string;
+    middleware: {
+        source: string;
+        export: string;
+    }[];
+    parameters: RouteExplanation['inputs']['parameters'];
+    body?: RouteExplanation['inputs']['body'];
+    policies: string[];
+    extensions: Record<string, Record<string, unknown>>;
+    cache: RouteExplanation['cache'];
+    bindings: {
+        env: string[];
+        secrets: string[];
+    };
+    egress: RouteExplanation['egress'];
+    capabilities: CapabilityName[];
+    targets: Record<CapabilityTarget, boolean>;
+}
+export interface ManifestModule {
+    source: string;
+    export: string;
+    routes: string[];
+}
+export interface RecipeProvenance {
+    id: string;
+    description?: string;
+    version?: string;
+    source?: string;
+}
+export interface Manifest {
+    schemaVersion: typeof MANIFEST_SCHEMA_VERSION;
+    urlcode: string;
+    entry: string;
+    files: string[];
+    revision: string;
+    configVersion: string;
+    routeCount: number;
+    routes: ManifestRoute[];
+    capabilities: CapabilityName[];
+    extensions: Record<string, {
+        version: string;
+        configKeys: string[];
+        mounts: string[];
+        protectedRoutes: string[];
+    }>;
+    recipes: RecipeProvenance[];
+    external: {
+        env: string[];
+        secrets: string[];
+        egress: {
+            proxy: string[];
+            signals: string[];
+        };
+        extensions: string[];
+    };
+    functions: ManifestModule[];
+    middleware: ManifestModule[];
+    targets: Record<CapabilityTarget, {
+        compatible: boolean;
+        issues: number;
+    }>;
+}
+/** Build the semantic manifest for a project from its compiled IR. Deterministic for a given project. */
+export declare function buildManifest(project: string, options?: InspectOptions): Promise<Manifest>;
+/** The manifest as `build` writes it: two-space JSON with a trailing newline. */
+export declare function renderManifest(manifest: Manifest): string;
+export declare const manifestFileName = "manifest.json";
+export declare function manifestPath(out: string): string;

package/dist/types/match.d.ts

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

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

@@ -0,0 +1,92 @@
+export declare const authoringDefinitions: ({
+    name: string;
+    description: string;
+    properties: {
+        path: {
+            type: string;
+            maxLength: number;
+        };
+        handler: {
+            anyOf: ({
+                type: string;
+                maxLength: number;
+            } | {
+                type: string;
+                maxLength?: never;
+            })[];
+        };
+        middleware: {
+            type: string;
+            maxItems: number;
+            items: {
+                anyOf: ({
+                    type: string;
+                    maxLength: number;
+                } | {
+                    type: string;
+                    maxLength?: never;
+                })[];
+            };
+        };
+        file: {
+            type: string;
+            maxLength: number;
+        };
+        name?: never;
+        destination?: never;
+        dryRun?: never;
+    };
+    required: string[];
+} | {
+    name: string;
+    description: string;
+    properties: {
+        name: {
+            type: string;
+            maxLength: number;
+        };
+        destination: {
+            type: string;
+            maxLength: number;
+        };
+        dryRun: {
+            type: string;
+        };
+        path?: never;
+        handler?: never;
+        middleware?: never;
+        file?: never;
+    };
+    required: string[];
+} | {
+    name: string;
+    description: string;
+    properties: {
+        dryRun: {
+            type: string;
+        };
+        path?: never;
+        handler?: never;
+        middleware?: never;
+        file?: never;
+        name?: never;
+        destination?: never;
+    };
+    required: never[];
+} | {
+    name: string;
+    description: string;
+    properties: {
+        path?: never;
+        handler?: never;
+        middleware?: never;
+        file?: never;
+        name?: never;
+        destination?: never;
+        dryRun?: never;
+    };
+    required: never[];
+})[];
+/** A project-relative path an authoring tool may create or replace: no absolute, `..`, hidden (`.env*`, `.git`), credential or operator names, and no symlink anywhere on the walk. */
+export declare function confinedPath(root: string, path: unknown): Promise<string>;
+export declare function callAuthoringTool(root: string, name: string, args: Record<string, unknown>, origin?: string): Promise<unknown>;

package/dist/types/mcp.d.ts

@@ -0,0 +1,12 @@
+import type { Readable, Writable } from 'node:stream';
+/** `allowAuthoring` and `hostFile` are set only by the `--allow-authoring` and `--host-file` command-line flags; tool arguments and the environment never enable them. */
+export interface McpOptions {
+    project: string;
+    input?: Readable;
+    output?: Writable;
+    origin?: string;
+    allowAuthoring?: boolean;
+    hostFile?: string;
+}
+/** Operator selects the only project root. Read tools have no path, credential, write or execution authority; authoring tools write inside that root only. */
+export declare function serveMcp(options: McpOptions): Promise<void>;