@foldkit/vite-plugin 0.23.0 → 0.24.0-canary.5be04ac25e5a

package/README.md

@@ -65,6 +65,52 @@ With this set, the dev server converts HTML page requests to Web `Request` value
 
 Vite retains ownership of configured proxy routes before Foldkit handles application requests. Vite's `server.cors` option applies to Vite-owned source modules, assets, and HMR. It does not add headers to application responses or answer their preflights. Preflight ownership follows `Access-Control-Request-Method`, so a preflight for an application `POST` reaches `renderPage` even when its path looks like an asset. An `OPTIONS` request without both `Origin` and `Access-Control-Request-Method` is not a preflight and also reaches `renderPage`. Define application CORS in `renderPage`, where development and the deployed host share one policy. Vite's `allowedHosts` check runs before proxy and application handling, including `OPTIONS` and methods the Web `Request` API cannot represent.
 
+## Completed build metadata
+
+Deployment tools that run Vite in process can read `foldkit:build` through Vite's standard plugin `api` field. Await the full application build before reading:
+
+```typescript
+import type { FoldkitBuildApi } from '@foldkit/vite-plugin'
+import { createBuilder } from 'vite'
+
+const builder = await createBuilder()
+await builder.buildApp()
+
+const plugin = builder.config.plugins.find(
+  plugin => plugin.name === 'foldkit:build',
+)
+
+if (plugin !== undefined) {
+  const api: FoldkitBuildApi | undefined = plugin.api
+
+  if (typeof api?.getBuildMetadata !== 'function') {
+    throw new Error('This Foldkit version does not expose build metadata')
+  }
+
+  const metadata = api.getBuildMetadata()
+  console.log(metadata.serverEntry)
+  console.log(metadata.manifest.prerendered)
+}
+```
+
+`FoldkitBuildApi` preserves `serverEntry` (the configured source entry) and `fetchModuleId` (the virtual fetch module). Its `getBuildMetadata()` method returns `FoldkitBuildMetadata`, exported as a Schema and inferred type:
+
+| Field             | Meaning                                                 |
+| ----------------- | ------------------------------------------------------- |
+| `root`            | Absolute resolved application root                      |
+| `clientDirectory` | Absolute resolved client output directory               |
+| `serverDirectory` | Absolute resolved server output directory               |
+| `serverEntry`     | Absolute path to the emitted fetch handler              |
+| `manifest`        | The version-1 data also written to `foldkit.build.json` |
+
+The snapshot, manifest, and prerendered route array are frozen. The data can be serialized to another process. The manifest keeps its portable relative POSIX paths; the outer path fields describe the local build machine. Output paths reflect the resolved Vite environments, including overrides made by a host plugin.
+
+A client-only build has no `foldkit:build` plugin. A present plugin without the accessor needs a Foldkit upgrade. The accessor throws before Foldkit finalizes, while another client or server build is running, or after its build fails. Always await `builder.buildApp()` successfully: another plugin can fail after Foldkit has finalized. An environment's `writeBundle` and another plugin's post-order `buildApp` hook do not establish this completion boundary.
+
+Create a fresh Foldkit plugin set for each independent builder. The build plugin uses Vite's `sharedDuringBuild` to share captures across its environments. Concurrent builders must not reuse the same plugin object. This API does not add watch-mode support.
+
+Prerendered pages and `foldkit.build.json` are finalized after the environment bundles. A separate deployment process that consumes an existing build can continue reading the disk manifest. An integration that runs the build in a child process can read the API there and transfer the serialized metadata in its child result.
+
 ## Build id
 
 The build id does not make hydration correct. It makes hydration refuse when it would otherwise be incorrect.
@@ -110,13 +156,23 @@ To include the overlay in production, list `@foldkit/devtools` in regular `depen
 
 ## DevTools MCP relay
 
-Pass `devToolsMcpPort` to enable the relay that exposes your running Foldkit app to AI agents via the [`@foldkit/devtools-mcp`](https://www.npmjs.com/package/@foldkit/devtools-mcp) MCP server:
+During development, the plugin starts a WebSocket relay for the [`@foldkit/devtools-mcp`](https://www.npmjs.com/package/@foldkit/devtools-mcp) server. Through the relay, an AI agent can inspect a running Foldkit app and dispatch Messages.
+
+By default, the relay uses the dev server's listener at `/__foldkit/devtools-mcp`. The plugin publishes its address to a registry private to your user, and the MCP server finds it by project. You do not need to coordinate a port between them. The registry lives under `XDG_RUNTIME_DIR` when that is set, or under the operating system's temporary directory. `FOLDKIT_DEVTOOLS_RELAY_DIRECTORY` selects another directory.
+
+The relay follows Vite's `server.host` setting. If you expose the dev server with `--host`, a client still needs the random token in the published address to inspect a Model or dispatch a Message. The plugin will not publish that token into a registry directory owned by another user or readable by other users. It reports the problem in the console.
+
+In middleware mode, the relay uses a free loopback port because there is no HTTP server to share. It also uses a free loopback port for HTTPS dev servers, whose self-signed certificates the MCP server cannot verify. The plugin publishes these addresses for discovery in the same way.
+
+To use a fixed port, set `devToolsMcpPort` in your Vite config:
 
 ```typescript
 plugins: [foldkit({ devToolsMcpPort: 9988 })]
 ```
 
-When set, the plugin opens a separate WebSocket server on the given port. The MCP server connects to it and forwards typed `Request` and `Response` frames between AI agents and your Runtime. Without `devToolsMcpPort` (the default), the relay is not started and the plugin behaves exactly as before.
+Set `FOLDKIT_DEVTOOLS_MCP_PORT` to the same value for the MCP server. A fixed port opens a separate socket on every interface and does not require a token. Use this setting on platforms where directory ownership cannot be verified, including Windows, because the plugin cannot publish a relay address there.
+
+`devToolsMcpPort: false` disables the relay. The relay does not start during Vitest runs or in production builds.
 
 See the [DevTools MCP documentation](https://foldkit.dev/ai/mcp) for setup, the available tools, and how dispatch validation works.
 

package/dist/build.d.ts

@@ -9,9 +9,10 @@ export type FoldkitPrerenderOptions = Readonly<{
      */
     paths?: ReadonlyArray<string>;
     /**
-     * The origin the entry sees as `Request.url` while generating, such as
-     * `'https://app.example'`. It reaches canonical URLs and Open Graph URLs, so
-     * a deployment that publishes those should set the origin it publishes.
+     * The origin used for `Request.url` while generating, such as
+     * `'https://app.example'`. This option does not set canonical or Open Graph
+     * metadata. It affects those fields only when the server entry derives them
+     * from `Request.url`, in which case it should match the published origin.
      */
     origin?: string;
     /**
@@ -42,15 +43,11 @@ export type FoldkitBuildOptions = Readonly<{
 /** Vite module id of the fetch handler Foldkit emits as the server entry. */
 export declare const FOLDKIT_FETCH_MODULE_ID = "virtual:foldkit/fetch";
 /**
- * What the build produced, written beside the server bundle for whatever
- * deploys it.
+ * What an `ssr.build` build produced, written beside the server bundle.
  *
- * A host has to decide what the asset layer does with a request that matches no
- * file, and that answer follows from the build rather than from taste: an
- * application with generated pages and no others wants a miss to stay a miss,
- * one with a server wants a miss to reach it, and one with neither wants the
- * template. Reading it here is how a deployment target gets that right without
- * asking its user to configure it twice.
+ * An SSR host serves generated paths as files and sends requests without a
+ * matching file to the server entry. A static-only SSG host serves the files
+ * and leaves other paths as misses.
  */
 export declare const FoldkitBuildManifest: Schema.Struct<{
     /**
@@ -71,28 +68,61 @@ export declare const FoldkitBuildManifest: Schema.Struct<{
     readonly serverEntry: Schema.String;
     /** Every path this build generated a page for, in the order it generated. */
     readonly prerendered: Schema.$Array<Schema.String>;
-    /**
-     * How a request-time host should run the server entry. Always `'fetch'`:
-     * the entry is a Web `fetch` handler, not a Node process.
-     */
-    readonly host: Schema.optional<Schema.Literals<readonly ["fetch"]>>;
 }>;
 /**
- * What the build produced, written beside the server bundle for whatever
- * deploys it.
+ * The decoded shape of `foldkit.build.json`.
  *
- * A host has to decide what the asset layer does with a request that matches no
- * file, and that answer follows from the build rather than from taste: an
- * application with generated pages and no others wants a miss to stay a miss,
- * one with a server wants a miss to reach it, and one with neither wants the
- * template. Reading it here is how a deployment target gets that right without
- * asking its user to configure it twice.
- *
- * It is a file on disk that something else writes the next time it builds, so a
- * consumer decodes it with this Schema and fails closed rather than trusting
- * the shape it happens to find.
+ * A deployment host decodes the manifest before using it. The Schema rejects
+ * unknown versions rather than letting the host read missing fields.
  */
 export type FoldkitBuildManifest = typeof FoldkitBuildManifest.Type;
+/** Completed application build data for an in-process deployment integration. */
+export declare const FoldkitBuildMetadata: Schema.Struct<{
+    /** Absolute resolved Vite application root. */
+    readonly root: Schema.String;
+    /** Absolute resolved browser output directory. */
+    readonly clientDirectory: Schema.String;
+    /** Absolute resolved server output directory. */
+    readonly serverDirectory: Schema.String;
+    /** Absolute path to the emitted fetch handler. */
+    readonly serverEntry: Schema.String;
+    /** Portable data also written to `foldkit.build.json`. */
+    readonly manifest: Schema.Struct<{
+        /**
+         * The shape of this document. A consumer decodes before reading and refuses
+         * a version it does not know, so a manifest written by a newer Foldkit is a
+         * clear refusal rather than a field silently read as undefined.
+         */
+        readonly schemaVersion: Schema.Literals<readonly [1]>;
+        /**
+         * Where the browser build was written, as a POSIX path relative to the Vite
+         * root. Relative and normalized so a manifest survives being moved with the
+         * build it describes.
+         */
+        readonly client: Schema.String;
+        /** Where the server build was written, on the same terms as {@link client}. */
+        readonly server: Schema.String;
+        /** The server build's entry file, relative to `server`. */
+        readonly serverEntry: Schema.String;
+        /** Every path this build generated a page for, in the order it generated. */
+        readonly prerendered: Schema.$Array<Schema.String>;
+    }>;
+}>;
+/** The serializable, frozen snapshot of a completed Foldkit build. */
+export type FoldkitBuildMetadata = typeof FoldkitBuildMetadata.Type;
+/** The `foldkit:build` plugin's public integration API. */
+export type FoldkitBuildApi = Readonly<{
+    /** Configured application source entry. */
+    serverEntry: string;
+    /** Virtual module used to bundle the fetch handler. */
+    fetchModuleId: typeof FOLDKIT_FETCH_MODULE_ID;
+    /**
+     * Read after a successful `await builder.buildApp()`. Throws before Foldkit
+     * finalizes or after another client or server build starts. Later plugin failures
+     * still require callers to await the full build successfully.
+     */
+    getBuildMetadata: () => FoldkitBuildMetadata;
+}>;
 export declare const manifestPath: (root: string, directory: string, pathApi?: typeof nodePath) => string;
 export declare const renderTargetFor: (clientDirectory: string, path: string, origin: string, pathApi?: typeof nodePath) => Readonly<{
     url: URL;
@@ -102,11 +132,10 @@ export declare const renderTargetFor: (clientDirectory: string, path: string, or
  * Builds a Web `fetch` handler alongside the browser build, and generates
  * static HTML from the server entry, inside one `vite build`.
  *
- * Vite drives both environments and every host plugin composes with them, so a
- * deployment target that runs `vite build` gets the whole application rather
- * than the browser half. The generated pages take their template from the
- * browser build's own output, so generating twice over one build produces the
- * same pages. The server bundle's default export is `{ fetch }`.
+ * Vite builds both environments, so a deployment target that runs `vite build`
+ * gets the browser and server bundles. The `fetch` handler and generated pages
+ * use the HTML emitted by the browser build, but the unrendered template is not
+ * published with the assets. The server bundle's default export is `{ fetch }`.
  */
-export declare const foldkitBuild: (serverEntry: string, options?: FoldkitBuildOptions) => Plugin;
+export declare const foldkitBuild: (serverEntry: string, options?: FoldkitBuildOptions) => Plugin<FoldkitBuildApi>;
 //# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,MAAM,EAAE,MAAM,QAAQ,CAAA;AAGtC,OAAO,QAA8B,MAAM,WAAW,CAAA;AAEtD,OAAO,KAAK,EAGV,MAAM,EAEP,MAAM,MAAM,CAAA;AAEb,mEAAmE;AACnE,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C;;;OAGG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC7B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAC,CAAA;AAEF,4EAA4E;AAC5E,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,uBAAuB,CAAA;CAC9C,CAAC,CAAA;AAEF,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,0BAA0B,CAAA;AAE9D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB;IAC/B;;;;OAIG;;IAEH;;;;OAIG;;IAEH,+EAA+E;;IAE/E,2DAA2D;;IAE3D,6EAA6E;;IAE7E;;;OAGG;;EAEH,CAAA;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,IAAI,CAAA;AAcnE,eAAO,MAAM,YAAY,SACjB,MAAM,aACD,MAAM,YACR,OAAO,QAAQ,KACvB,MAQF,CAAA;AAwFD,eAAO,MAAM,eAAe,oBACT,MAAM,QACjB,MAAM,UACJ,MAAM,YACL,OAAO,QAAQ,KACvB,QAAQ,CAAC;IAAE,GAAG,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA0CrC,CAAA;AA4GD;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,gBACV,MAAM,YACV,mBAAmB,KAC3B,MAoOF,CAAA"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAG/B,OAAO,QAA8B,MAAM,WAAW,CAAA;AAEtD,OAAO,KAAK,EAGV,MAAM,EAEP,MAAM,MAAM,CAAA;AAEb,mEAAmE;AACnE,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C;;;OAGG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC7B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAC,CAAA;AAEF,4EAA4E;AAC5E,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,uBAAuB,CAAA;CAC9C,CAAC,CAAA;AAEF,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,0BAA0B,CAAA;AAE9D;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB;IAC/B;;;;OAIG;;IAEH;;;;OAIG;;IAEH,+EAA+E;;IAE/E,2DAA2D;;IAE3D,6EAA6E;;EAE7E,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,IAAI,CAAA;AAEnE,iFAAiF;AACjF,eAAO,MAAM,oBAAoB;IAC/B,+CAA+C;;IAE/C,kDAAkD;;IAElD,iDAAiD;;IAEjD,kDAAkD;;IAElD,0DAA0D;;QAtC1D;;;;WAIG;;QAEH;;;;WAIG;;QAEH,+EAA+E;;QAE/E,2DAA2D;;QAE3D,6EAA6E;;;EAwB7E,CAAA;AAEF,sEAAsE;AACtE,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,IAAI,CAAA;AAEnE,2DAA2D;AAC3D,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAA;IACnB,uDAAuD;IACvD,aAAa,EAAE,OAAO,uBAAuB,CAAA;IAC7C;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;CAC7C,CAAC,CAAA;AAcF,eAAO,MAAM,YAAY,SACjB,MAAM,aACD,MAAM,YACR,OAAO,QAAQ,KACvB,MAQF,CAAA;AAyFD,eAAO,MAAM,eAAe,oBACT,MAAM,QACjB,MAAM,UACJ,MAAM,YACL,OAAO,QAAQ,KACvB,QAAQ,CAAC;IAAE,GAAG,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA0CrC,CAAA;AAsFD;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,gBACV,MAAM,YACV,mBAAmB,KAC3B,MAAM,CAAC,eAAe,CAmPxB,CAAA"}

package/dist/build.js

@@ -1,19 +1,15 @@
-import { Array, Schema } from 'effect';
+import { Schema } from 'effect';
 import { mkdir, writeFile } from 'node:fs/promises';
 import nodePath, { dirname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 /** Vite module id of the fetch handler Foldkit emits as the server entry. */
 export const FOLDKIT_FETCH_MODULE_ID = 'virtual:foldkit/fetch';
 /**
- * What the build produced, written beside the server bundle for whatever
- * deploys it.
+ * What an `ssr.build` build produced, written beside the server bundle.
  *
- * A host has to decide what the asset layer does with a request that matches no
- * file, and that answer follows from the build rather than from taste: an
- * application with generated pages and no others wants a miss to stay a miss,
- * one with a server wants a miss to reach it, and one with neither wants the
- * template. Reading it here is how a deployment target gets that right without
- * asking its user to configure it twice.
+ * An SSR host serves generated paths as files and sends requests without a
+ * matching file to the server entry. A static-only SSG host serves the files
+ * and leaves other paths as misses.
  */
 export const FoldkitBuildManifest = Schema.Struct({
     /**
@@ -34,11 +30,19 @@ export const FoldkitBuildManifest = Schema.Struct({
     serverEntry: Schema.String,
     /** Every path this build generated a page for, in the order it generated. */
     prerendered: Schema.Array(Schema.String),
-    /**
-     * How a request-time host should run the server entry. Always `'fetch'`:
-     * the entry is a Web `fetch` handler, not a Node process.
-     */
-    host: Schema.optional(Schema.Literals(['fetch'])),
+});
+/** Completed application build data for an in-process deployment integration. */
+export const FoldkitBuildMetadata = Schema.Struct({
+    /** Absolute resolved Vite application root. */
+    root: Schema.String,
+    /** Absolute resolved browser output directory. */
+    clientDirectory: Schema.String,
+    /** Absolute resolved server output directory. */
+    serverDirectory: Schema.String,
+    /** Absolute path to the emitted fetch handler. */
+    serverEntry: Schema.String,
+    /** Portable data also written to `foldkit.build.json`. */
+    manifest: FoldkitBuildManifest,
 });
 const MANIFEST_SCHEMA_VERSION = 1;
 // Relative and POSIX so the manifest describes a layout rather than this
@@ -59,6 +63,7 @@ export const manifestPath = (root, directory, pathApi = nodePath) => {
     return related.split(pathApi.sep).join('/');
 };
 const MANIFEST_FILE_NAME = 'foldkit.build.json';
+const TEMPLATE_FILE_NAME = 'index.html';
 const DEFAULT_CLIENT_OUT_DIR = 'dist/client';
 const DEFAULT_SERVER_OUT_DIR = 'dist/server';
 const DEFAULT_PRERENDER_ORIGIN = 'http://localhost';
@@ -162,26 +167,6 @@ const prerenderOptionsFrom = (prerender) => {
     }
     return prerender === true ? {} : prerender;
 };
-// Keyed by Vite root plus the output layout, so concurrent builds of different
-// projects in one process never read each other's output.
-//
-// NOTE: the registry hangs off a global symbol rather than module scope. Vite
-// re-bundles a config file for each environment it resolves, and every bundle
-// is a fresh copy of this module with its own module scope, so what the client
-// build recorded would be invisible to the instance that finalizes. The symbol
-// is one registry for the process no matter how many copies of this module it
-// loads.
-const CAPTURES = Symbol.for('foldkit/vite-plugin:build-captures');
-const captures = (() => {
-    const registry = globalThis;
-    const existing = registry[CAPTURES];
-    if (existing instanceof Map) {
-        return existing;
-    }
-    const fresh = new Map();
-    registry[CAPTURES] = fresh;
-    return fresh;
-})();
 const fetchModuleSource = (serverEntry, template, containerId) => {
     const containerLiteral = containerId === undefined ? 'undefined' : JSON.stringify(containerId);
     // NOTE: `export *` re-exports whatever the application entry actually names,
@@ -212,7 +197,7 @@ const fetchModuleSource = (serverEntry, template, containerId) => {
 // page which cannot hydrate, from a build that reported success.
 const templateForFetchModule = (capturedTemplate) => {
     if (capturedTemplate === undefined) {
-        throw new Error('[foldkit] the browser build has not emitted index.html, so the fetch handler has no template to render into. Build the "client" environment before "ssr", and give the client an HTML entry.');
+        throw new Error(`[foldkit] the browser build has not emitted ${TEMPLATE_FILE_NAME}, so the fetch handler has no template to render into. Build the "client" environment before "ssr", and give the client an HTML entry.`);
     }
     return capturedTemplate;
 };
@@ -220,13 +205,14 @@ const templateForFetchModule = (capturedTemplate) => {
  * Builds a Web `fetch` handler alongside the browser build, and generates
  * static HTML from the server entry, inside one `vite build`.
  *
- * Vite drives both environments and every host plugin composes with them, so a
- * deployment target that runs `vite build` gets the whole application rather
- * than the browser half. The generated pages take their template from the
- * browser build's own output, so generating twice over one build produces the
- * same pages. The server bundle's default export is `{ fetch }`.
+ * Vite builds both environments, so a deployment target that runs `vite build`
+ * gets the browser and server bundles. The `fetch` handler and generated pages
+ * use the HTML emitted by the browser build, but the unrendered template is not
+ * published with the assets. The server bundle's default export is `{ fetch }`.
  */
 export const foldkitBuild = (serverEntry, options = {}) => {
+    const state = {};
+    let metadata;
     const clientOutDir = options.clientOutDir ?? DEFAULT_CLIENT_OUT_DIR;
     const serverOutDir = options.serverOutDir ?? DEFAULT_SERVER_OUT_DIR;
     const prerender = prerenderOptionsFrom(options.prerender ?? false);
@@ -235,12 +221,11 @@ export const foldkitBuild = (serverEntry, options = {}) => {
     // with the build's own privileges. That module is the application's own code
     // and its dependencies, built from the configured entry, and is trusted on
     // exactly those terms. Nothing here is imported when prerendering is off.
-    const generatePages = async (builder, template, serverDirectory, entryFileName) => {
+    const generatePages = async (builder, template, clientDirectory, serverDirectory, entryFileName) => {
         if (prerender === undefined) {
             return [];
         }
         const origin = prerender.origin ?? DEFAULT_PRERENDER_ORIGIN;
-        const clientDirectory = resolve(builder.config.root, clientOutDir);
         const entryFile = resolve(serverDirectory, entryFileName);
         const contained = resolve(serverDirectory);
         if (!entryFile.startsWith(`${contained}${nodePath.sep}`)) {
@@ -267,39 +252,12 @@ export const foldkitBuild = (serverEntry, options = {}) => {
         }
         return paths;
     };
-    const writeManifest = async (builder, serverDirectory, entryFileName, prerendered) => {
-        const manifest = Schema.encodeSync(FoldkitBuildManifest)({
-            schemaVersion: MANIFEST_SCHEMA_VERSION,
-            client: manifestPath(builder.config.root, clientOutDir),
-            server: manifestPath(builder.config.root, serverOutDir),
-            serverEntry: entryFileName,
-            prerendered,
-            host: 'fetch',
-        });
-        await writeFile(resolve(serverDirectory, MANIFEST_FILE_NAME), `${JSON.stringify(manifest, undefined, 2)}\n`);
-        builder.config.logger.info(`  wrote ${MANIFEST_FILE_NAME}`);
-    };
-    // What each environment emitted, recorded as it is emitted.
-    //
-    // Vite resolves the config once per environment unless `sharedConfigBuild` is
-    // on, so the plugin that finalizes is not necessarily the instance that saw a
-    // given environment build. Keying the record by the output layout it
-    // describes is what lets the finalizing instance read what the others
-    // emitted, and what lets finalization work whether this plugin orchestrates
-    // the environments or a host does.
-    const key = [clientOutDir, serverOutDir, serverEntry].join('\u0000');
-    const captured = (root) => {
-        const existing = captures.get(`${root}\u0000${key}`);
-        if (existing !== undefined) {
-            return existing;
-        }
-        const fresh = {};
-        captures.set(`${root}\u0000${key}`, fresh);
-        return fresh;
-    };
     const finalize = async (builder) => {
-        const state = captured(builder.config.root);
-        const serverDirectory = resolve(builder.config.root, serverOutDir);
+        metadata = undefined;
+        const client = environmentNamed(builder, 'client');
+        const server = environmentNamed(builder, 'ssr');
+        const clientDirectory = resolve(client.config.root, client.config.build.outDir);
+        const serverDirectory = resolve(server.config.root, server.config.build.outDir);
         if (state.serverEntryFile === undefined) {
             throw new Error('[foldkit] the server environment produced no entry chunk, so there is nothing to deploy or generate from.');
         }
@@ -307,20 +265,58 @@ export const foldkitBuild = (serverEntry, options = {}) => {
         // nothing has no use for an HTML entry and must not require one.
         const template = () => {
             if (state.template === undefined) {
-                throw new Error('[foldkit] the browser build emitted no index.html to generate pages from. Prerendering needs an HTML entry.');
+                throw new Error(`[foldkit] the browser build emitted no ${TEMPLATE_FILE_NAME} to generate pages from. Prerendering needs an HTML entry.`);
             }
             return state.template;
         };
-        const prerendered = await generatePages(builder, template, serverDirectory, state.serverEntryFile);
-        await writeManifest(builder, serverDirectory, state.serverEntryFile, prerendered);
+        const prerendered = await generatePages(builder, template, clientDirectory, serverDirectory, state.serverEntryFile);
+        const manifest = FoldkitBuildManifest.make({
+            schemaVersion: MANIFEST_SCHEMA_VERSION,
+            client: manifestPath(builder.config.root, clientDirectory),
+            server: manifestPath(builder.config.root, serverDirectory),
+            serverEntry: state.serverEntryFile,
+            prerendered: [...prerendered],
+        });
+        await writeFile(resolve(serverDirectory, MANIFEST_FILE_NAME), `${JSON.stringify(Schema.encodeSync(FoldkitBuildManifest)(manifest), undefined, 2)}\n`);
+        builder.config.logger.info(`  wrote ${MANIFEST_FILE_NAME}`);
+        const completedMetadata = FoldkitBuildMetadata.make({
+            root: builder.config.root,
+            clientDirectory,
+            serverDirectory,
+            serverEntry: resolve(serverDirectory, state.serverEntryFile),
+            manifest,
+        });
+        Object.freeze(completedMetadata.manifest.prerendered);
+        Object.freeze(completedMetadata.manifest);
+        metadata = Object.freeze(completedMetadata);
     };
     return {
         name: 'foldkit:build',
         apply: 'build',
+        sharedDuringBuild: true,
         api: {
-            host: 'fetch',
             serverEntry,
             fetchModuleId: FOLDKIT_FETCH_MODULE_ID,
+            getBuildMetadata: () => {
+                if (metadata === undefined) {
+                    throw new Error('[foldkit] build metadata is not available. Read it after a successful builder.buildApp().');
+                }
+                return metadata;
+            },
+        },
+        buildStart: {
+            order: 'pre',
+            handler() {
+                if (this.environment.name === 'client') {
+                    delete state.template;
+                    delete state.serverEntryFile;
+                    metadata = undefined;
+                }
+                else if (this.environment.name === 'ssr') {
+                    delete state.serverEntryFile;
+                    metadata = undefined;
+                }
+            },
         },
         resolveId(id) {
             if (id === FOLDKIT_FETCH_MODULE_ID) {
@@ -332,27 +328,28 @@ export const foldkitBuild = (serverEntry, options = {}) => {
             if (id !== RESOLVED_FETCH_MODULE_ID) {
                 return;
             }
-            const state = captured(this.environment.config.root);
             const template = templateForFetchModule(state.template);
             return fetchModuleSource(serverEntry, template, containerId);
         },
-        // NOTE: `writeBundle` rather than `generateBundle`: Vite's own HTML plugin
-        // emits `index.html` from a `generateBundle` hook of its own, and hook
-        // order between plugins decides whether that asset exists yet. By
-        // `writeBundle` the bundle is whatever the environment actually produced.
-        writeBundle(_options, bundle) {
-            const state = captured(this.environment.config.root);
-            const outputs = Object.values(bundle);
-            if (this.environment.name === 'client') {
-                const html = Array.findFirst(outputs, file => file.type === 'asset' && file.fileName === 'index.html');
-                if (html._tag === 'Some' && html.value.type === 'asset') {
-                    state.template = String(html.value.source);
+        // NOTE: `order: 'post'` because Vite's own HTML plugin emits `index.html`
+        // from a `generateBundle` of its own; post is guaranteed to run after it.
+        generateBundle: {
+            order: 'post',
+            handler(_options, bundle) {
+                if (this.environment.name === 'ssr') {
+                    state.serverEntryFile = serverEntryFile(Object.values(bundle), FETCH_CHUNK_NAME);
+                    return;
                 }
-                return;
-            }
-            if (this.environment.name === 'ssr') {
-                state.serverEntryFile = serverEntryFile(outputs, FETCH_CHUNK_NAME);
-            }
+                if (this.environment.name !== 'client') {
+                    return;
+                }
+                const html = bundle[TEMPLATE_FILE_NAME];
+                if (html === undefined || html.type !== 'asset') {
+                    return;
+                }
+                state.template = String(html.source);
+                delete bundle[TEMPLATE_FILE_NAME];
+            },
         },
         config: userConfig => {
             const client = {

package/dist/index.d.ts

@@ -2,18 +2,21 @@ import type { Plugin } from 'vite';
 import { type FoldkitBuildOptions } from './build.js';
 import { type FoldkitSsrOptions } from './ssr.js';
 export { type BrandDistResult, brandDistDirectory } from './brandDist.js';
-export { FOLDKIT_FETCH_MODULE_ID, FoldkitBuildManifest, type FoldkitBuildOptions, type FoldkitPrerenderOptions, foldkitBuild, } from './build.js';
+export { FOLDKIT_FETCH_MODULE_ID, FoldkitBuildManifest, FoldkitBuildMetadata, type FoldkitBuildApi, type FoldkitBuildOptions, type FoldkitPrerenderOptions, foldkitBuild, } from './build.js';
 export { type FoldkitSsrOptions, foldkitSsr } from './ssr.js';
 export { type ViewIdentityTransformResult, foldkitViewIdentity, transformViewIdentity, } from './viewIdentity.js';
 /** Options for the `foldkit` Vite plugin. */
 export type FoldkitPluginOptions = Readonly<{
     /**
-     * Port for the WebSocket server that exposes the DevTools relay to an
-     * external MCP server. When `undefined` (the default), no MCP relay is
-     * started. When set, the plugin listens on this port for connections from
-     * the Foldkit DevTools MCP server.
+     * By default, the dev server hosts the DevTools MCP relay and publishes its
+     * address for the MCP server to find. Middleware and HTTPS servers use a
+     * separate loopback listener. Published addresses carry an access token.
+     *
+     * A number starts an unauthenticated listener on that port on every
+     * interface; set `FOLDKIT_DEVTOOLS_MCP_PORT` in the MCP server to match.
+     * `false` disables the relay. Vitest never starts it.
      */
-    devToolsMcpPort?: number;
+    devToolsMcpPort?: number | false;
     /**
      * Serve server-rendered pages from the Vite dev server, and, with
      * `ssr.build`, emit a Web `fetch` handler as the server bundle. When

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EACV,MAAM,EAIP,MAAM,MAAM,CAAA;AAGb,OAAO,EAAE,KAAK,mBAAmB,EAAgB,MAAM,YAAY,CAAA;AAGnE,OAAO,EAAE,KAAK,iBAAiB,EAAc,MAAM,UAAU,CAAA;AAG7D,OAAO,EAAE,KAAK,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACzE,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,YAAY,GACb,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,KAAK,iBAAiB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC7D,OAAO,EACL,KAAK,2BAA2B,EAChC,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,mBAAmB,CAAA;AAE1B,6CAA6C;AAC7C,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,SAAS,GAAG,gBAAgB,CAAC,GACzD,QAAQ,CAAC;QACP;;;;;;;;WAQG;QACH,KAAK,CAAC,EAAE,OAAO,GAAG,mBAAmB,CAAA;KACtC,CAAC,CAAA;IACJ;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAC,CAAA;AAonBF,eAAO,MAAM,OAAO,aAAa,oBAAoB,KAAQ,KAAK,CAAC,MAAM,CAuFxE,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA+CA,OAAO,KAAK,EAEV,MAAM,EAIP,MAAM,MAAM,CAAA;AAOb,OAAO,EAAE,KAAK,mBAAmB,EAAgB,MAAM,YAAY,CAAA;AAInE,OAAO,EAAE,KAAK,iBAAiB,EAAc,MAAM,UAAU,CAAA;AAG7D,OAAO,EAAE,KAAK,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACzE,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,YAAY,GACb,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,KAAK,iBAAiB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC7D,OAAO,EACL,KAAK,2BAA2B,EAChC,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,mBAAmB,CAAA;AAE1B,6CAA6C;AAC7C,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IAChC;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,SAAS,GAAG,gBAAgB,CAAC,GACzD,QAAQ,CAAC;QACP;;;;;;;;WAQG;QACH,KAAK,CAAC,EAAE,OAAO,GAAG,mBAAmB,CAAA;KACtC,CAAC,CAAA;IACJ;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAC,CAAA;AAw8BF,eAAO,MAAM,OAAO,aAAa,oBAAoB,KAAQ,KAAK,CAAC,MAAM,CA+FxE,CAAA"}

package/dist/index.js

@@ -1,16 +1,22 @@
-import { Array, Console, Data, Duration, Effect, Exit, Fiber, HashMap, HashSet, Match, Option, Predicate, Queue, Ref, Schedule, Schema, Stream, pipe, } from 'effect';
-import { Event as DevToolsEvent, EventFrame, RequestFrame, Response, ResponseFrame, } from 'foldkit/devtools-protocol';
+import { Array, Clock, ConfigProvider, Console, Crypto, Data, Duration, Effect, Exit, Fiber, HashMap, HashSet, Layer, Match, Option, Predicate, Queue, Ref, Schedule, Schema, Stream, pipe, } from 'effect';
+import { Event as DevToolsEvent, EventFrame, RELAY_RECORD_VERSION, RequestFrame, Response, ResponseFrame, } from 'foldkit/devtools-protocol';
 import { PreserveModelMessage, RequestModelMessage, RestoreModelMessage, } from 'foldkit/model-preservation';
+import { timingSafeEqual } from 'node:crypto';
+import { createServer as createHttpServer, } from 'node:http';
 import { createRequire } from 'node:module';
 import { resolve } from 'node:path';
 import { WebSocketServer } from 'ws';
+import * as NodeCrypto from '@effect/platform-node/NodeCrypto';
+import * as NodeFileSystem from '@effect/platform-node/NodeFileSystem';
+import * as NodePath from '@effect/platform-node/NodePath';
 import { foldkitBuild } from './build.js';
 import { foldkitBuildToken } from './buildToken.js';
 import { devToolsOverlayPlugin } from './devToolsOverlay.js';
+import { publishRelayRecord, retireRelayRecord } from './relayRegistry.js';
 import { foldkitSsr } from './ssr.js';
 import { foldkitViewIdentity } from './viewIdentity.js';
 export { brandDistDirectory } from './brandDist.js';
-export { FOLDKIT_FETCH_MODULE_ID, FoldkitBuildManifest, foldkitBuild, } from './build.js';
+export { FOLDKIT_FETCH_MODULE_ID, FoldkitBuildManifest, FoldkitBuildMetadata, foldkitBuild, } from './build.js';
 export { foldkitSsr } from './ssr.js';
 export { foldkitViewIdentity, transformViewIdentity, } from './viewIdentity.js';
 // NOTE: Vite's dep optimizer scans the consumer's source for `effect`
@@ -249,18 +255,24 @@ const registerViteWsHandlers = (server, state, enqueue) => Effect.sync(() => {
     server.ws.on('foldkit:devTools:response', (data) => enqueue(Event.BrowserResponseFrameReceived({ data })));
 });
 // MCP RELAY
-// NOTE: Restarting a dev server briefly leaves two of them alive. Vite builds
-// the replacement, which binds its relay, before closing the server it
-// replaces, which still owns the port. The bind loses that race and has to
-// wait for the outgoing server to release the port, so it retries for four
-// seconds before reporting the port as taken.
+// NOTE: Vite starts a replacement server before closing the old one. A
+// configured relay port can stay occupied during the overlap, so binding
+// retries for four seconds.
 const RELAY_BIND_RETRY_DELAY = Duration.millis(100);
 const RELAY_BIND_RETRY_COUNT = 40;
+const RELAY_PATH = '/__foldkit/devtools-mcp';
+const RELAY_LOOPBACK_HOST = '127.0.0.1';
+const RELAY_CONFIGURED_PORT_HOST = 'localhost';
+const RELAY_TOKEN_PARAMETER = 'token';
+const RELAY_TOKEN_BYTES = 32;
 class RelayBindFailed extends Data.TaggedError('RelayBindFailed') {
 }
 const isPortInUse = (error) => Predicate.hasProperty(error, 'code') && error.code === 'EADDRINUSE';
-const bindMcpRelay = (port, enqueue) => Effect.callback(resume => {
-    const wss = new WebSocketServer({ port });
+const relayId = Effect.gen(function* () {
+    const crypto = yield* Crypto.Crypto;
+    return yield* crypto.randomUUIDv4.pipe(Effect.orDie);
+});
+const attachRelayHandlers = (wss, enqueue) => {
     wss.on('connection', client => {
         enqueue(Event.McpClientConnected({ client }));
         client.on('message', raw => enqueue(Event.McpRequestReceived({ client, raw: raw.toString() })));
@@ -269,45 +281,206 @@ const bindMcpRelay = (port, enqueue) => Effect.callback(resume => {
             console.error('[foldkit:devTools] MCP client error', error);
         });
     });
+};
+const parseRequestUrl = Option.liftThrowable((request) => new URL(request.url ?? '/', 'http://relay'));
+const boundPort = (address) => address === null || Predicate.isString(address)
+    ? Option.none()
+    : Option.some(address.port);
+const relayHasNoBoundPort = () => new Error('[foldkit:devTools] the MCP relay listener has no bound port');
+const relayToken = Effect.gen(function* () {
+    const crypto = yield* Crypto.Crypto;
+    const bytes = yield* crypto.randomBytes(RELAY_TOKEN_BYTES).pipe(Effect.orDie);
+    return Buffer.from(bytes).toString('hex');
+});
+const relayUrlForLog = (url) => {
+    const parsed = new URL(url);
+    parsed.search = '';
+    return parsed.toString();
+};
+const withRelayToken = (url, token) => {
+    url.search = '';
+    url.searchParams.set(RELAY_TOKEN_PARAMETER, token);
+    return url.toString();
+};
+const requestPresentsToken = (url, token) => {
+    const maybePresented = Option.fromNullishOr(url.searchParams.get(RELAY_TOKEN_PARAMETER));
+    const expected = Buffer.from(token, 'utf8');
+    return Option.exists(maybePresented, presented => {
+        const actual = Buffer.from(presented, 'utf8');
+        return (expected.length === actual.length && timingSafeEqual(expected, actual));
+    });
+};
+const refuseUpgrade = (socket) => {
+    socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n');
+    socket.destroy();
+};
+// NOTE: Vite resolves `server.resolvedUrls` in a listener it prepends to
+// `listening`, so they are set by the time the relay's own listener runs.
+const hostedRelayUrl = (server, token) => (httpServer) => {
+    const maybeResolvedUrl = pipe(Option.fromNullishOr(server.resolvedUrls), Option.flatMap(resolvedUrls => Option.orElse(Array.head(resolvedUrls.local), () => Array.head(resolvedUrls.network))));
+    const url = new URL(pipe(maybeResolvedUrl, Option.orElse(() => Option.map(boundPort(httpServer.address()), port => `http://${RELAY_LOOPBACK_HOST}:${port}/`)), Option.getOrThrowWith(relayHasNoBoundPort)));
+    url.protocol = 'ws:';
+    url.pathname = RELAY_PATH;
+    return withRelayToken(url, token);
+};
+const loopbackRelayUrl = (token) => (httpServer) => {
+    const port = Option.getOrThrowWith(boundPort(httpServer.address()), relayHasNoBoundPort);
+    const url = new URL(`ws://${RELAY_LOOPBACK_HOST}:${port}${RELAY_PATH}`);
+    return withRelayToken(url, token);
+};
+const hostRelayOnServer = (httpServer, id, token, toUrl, enqueue) => Effect.callback(resume => {
+    const wss = new WebSocketServer({ noServer: true });
+    attachRelayHandlers(wss, enqueue);
+    const onUpgrade = (request, socket, head) => {
+        const maybeUrl = parseRequestUrl(request);
+        if (Option.isNone(maybeUrl)) {
+            socket.destroy();
+            return;
+        }
+        const url = maybeUrl.value;
+        if (url.pathname !== RELAY_PATH) {
+            return;
+        }
+        if (!requestPresentsToken(url, token)) {
+            refuseUpgrade(socket);
+            return;
+        }
+        wss.handleUpgrade(request, socket, head, client => {
+            wss.emit('connection', client, request);
+        });
+    };
+    httpServer.on('upgrade', onUpgrade);
+    const detach = () => {
+        httpServer.off('upgrade', onUpgrade);
+        httpServer.off('listening', onListening);
+    };
+    const onListening = () => {
+        resume(Effect.sync(() => ({ id, wss, url: toUrl(httpServer), detach })));
+    };
+    if (httpServer.listening) {
+        onListening();
+    }
+    else {
+        httpServer.once('listening', onListening);
+    }
+    return Effect.sync(detach);
+});
+const bindLoopbackHttpServer = Effect.callback(resume => {
+    const httpServer = createHttpServer();
+    const onBindFailed = (cause) => {
+        httpServer.close();
+        resume(Effect.fail(new RelayBindFailed({ maybePort: Option.none(), cause })));
+    };
+    httpServer.once('error', onBindFailed);
+    httpServer.listen(0, RELAY_LOOPBACK_HOST, () => {
+        httpServer.off('error', onBindFailed);
+        httpServer.on('error', error => {
+            console.error('[foldkit:devTools] MCP relay error', error);
+        });
+        resume(Effect.succeed(httpServer));
+    });
+    return Effect.sync(() => {
+        httpServer.close();
+    });
+});
+const bindLoopbackRelay = (id, token, enqueue) => Effect.gen(function* () {
+    const httpServer = yield* bindLoopbackHttpServer;
+    const relay = yield* hostRelayOnServer(httpServer, id, token, loopbackRelayUrl(token), enqueue);
+    return {
+        ...relay,
+        detach: () => {
+            relay.detach();
+            httpServer.close();
+        },
+    };
+});
+const bindStandaloneRelay = (port, id, enqueue) => Effect.callback(resume => {
+    const wss = new WebSocketServer({ port });
+    attachRelayHandlers(wss, enqueue);
     const onListening = () => {
         wss.off('error', onBindFailed);
         wss.on('error', error => {
             console.error('[foldkit:devTools] MCP relay error', error);
         });
-        console.log(`[foldkit:devTools] MCP relay listening on ws://localhost:${port}`);
-        resume(Effect.succeed(wss));
+        const listeningPort = Option.getOrThrowWith(boundPort(wss.address()), relayHasNoBoundPort);
+        resume(Effect.succeed({
+            id,
+            wss,
+            url: `ws://${RELAY_CONFIGURED_PORT_HOST}:${listeningPort}`,
+            detach: () => undefined,
+        }));
     };
     const onBindFailed = (cause) => {
         wss.off('listening', onListening);
         wss.close();
-        resume(Effect.fail(new RelayBindFailed({ cause })));
+        resume(Effect.fail(new RelayBindFailed({ maybePort: Option.some(port), cause })));
     };
     wss.once('listening', onListening);
     wss.once('error', onBindFailed);
 });
-const reportRelayBindFailed = (port, cause) => {
-    if (isPortInUse(cause)) {
-        return Console.error(`\n[foldkit:devTools] Port ${port} is already in use, so the DevTools MCP relay could not start.\n` +
-            `[foldkit:devTools] This usually means another Foldkit project is already running and bound to this port.\n` +
-            `[foldkit:devTools] Until the port is freed, agents will not be able to connect to this app via the Foldkit DevTools MCP server.\n` +
-            `[foldkit:devTools] Stop the other project, or set a different \`devToolsMcpPort\` in this project's vite config.\n` +
-            `[foldkit:devTools] If you change \`devToolsMcpPort\`, also set \`FOLDKIT_DEVTOOLS_MCP_PORT\` to the same value for your MCP server.\n`);
+const reportRelayBindFailed = (maybePort, cause) => {
+    const where = Option.match(maybePort, {
+        onNone: () => 'an assigned loopback port',
+        onSome: port => `port ${port}`,
+    });
+    if (Option.isSome(maybePort) && isPortInUse(cause)) {
+        const port = maybePort.value;
+        return Console.error(`\n[foldkit:devTools] Port ${port} is in use; the MCP relay did not start.\n` +
+            `[foldkit:devTools] Stop the process using that port, or remove \`devToolsMcpPort\` from your Vite config to use automatic discovery.\n` +
+            `[foldkit:devTools] If you choose another fixed port, set \`FOLDKIT_DEVTOOLS_MCP_PORT\` to match.\n`);
     }
     else {
-        return Console.error(`[foldkit:devTools] MCP relay failed to start on port ${port}; continuing without the relay`, cause);
+        return Console.error(`[foldkit:devTools] MCP relay failed to start on ${where}; continuing without the relay`, cause);
     }
 };
-const startMcpRelay = (port, enqueue) => Effect.acquireRelease(bindMcpRelay(port, enqueue), wss => Effect.gen(function* () {
-    for (const client of wss.clients) {
-        client.terminate();
-    }
-    wss.close();
-    yield* Console.log('[foldkit:devTools] MCP relay stopped');
-})).pipe(Effect.retry({
-    while: ({ cause }) => isPortInUse(cause),
-    times: RELAY_BIND_RETRY_COUNT,
-    schedule: Schedule.spaced(RELAY_BIND_RETRY_DELAY),
-}), Effect.catchTag('RelayBindFailed', ({ cause }) => reportRelayBindFailed(port, cause)));
+const unpublishedRelayMessage = (reason) => `[foldkit:devTools] Cannot publish the MCP relay address: ${reason}. Set matching devToolsMcpPort and FOLDKIT_DEVTOOLS_MCP_PORT values for MCP access, or set FOLDKIT_DEVTOOLS_RELAY_DIRECTORY to a private directory on a platform that verifies ownership.`;
+const publishRelay = (root, relay) => Effect.gen(function* () {
+    const startedAt = yield* Clock.currentTimeMillis;
+    yield* publishRelayRecord({
+        version: RELAY_RECORD_VERSION,
+        id: relay.id,
+        root,
+        url: relay.url,
+        pid: process.pid,
+        startedAt,
+    });
+}).pipe(Effect.catchTag('RelayRegistryDirectoryRefused', ({ directory, reason }) => Console.error(unpublishedRelayMessage(`the registry directory ${directory} ${reason}`))), Effect.catch(error => Console.error(unpublishedRelayMessage('the registry could not be written'), error)));
+const startMcpRelay = (server, devToolsMcpPort, enqueue) => {
+    const root = server.config.root;
+    // NOTE: The MCP server cannot verify a development HTTPS certificate, so
+    // HTTPS uses a separate loopback listener.
+    const maybeHttpServer = Option.filter(Option.fromNullishOr(server.httpServer), () => server.config.server.https === undefined);
+    // NOTE: A configured port keeps the previous unauthenticated behavior.
+    // An assigned port binds only to loopback and is found through the registry.
+    const acquire = Effect.gen(function* () {
+        const id = yield* relayId;
+        if (devToolsMcpPort !== undefined) {
+            return yield* bindStandaloneRelay(devToolsMcpPort, id, enqueue);
+        }
+        const token = yield* relayToken;
+        return yield* Option.match(maybeHttpServer, {
+            onNone: () => bindLoopbackRelay(id, token, enqueue),
+            onSome: httpServer => hostRelayOnServer(httpServer, id, token, hostedRelayUrl(server, token), enqueue),
+        });
+    });
+    return Effect.acquireRelease(acquire.pipe(Effect.tap(relay => Console.log(`[foldkit:devTools] MCP relay listening at ${relayUrlForLog(relay.url)}`)), Effect.tap(relay => publishRelay(root, relay))), relay => Effect.gen(function* () {
+        relay.detach();
+        for (const client of relay.wss.clients) {
+            client.terminate();
+        }
+        relay.wss.close();
+        yield* retireRelayRecord(root, relay.id);
+        yield* Console.log('[foldkit:devTools] MCP relay stopped');
+    })).pipe(Effect.retry({
+        while: ({ cause }) => isPortInUse(cause),
+        times: RELAY_BIND_RETRY_COUNT,
+        schedule: Schedule.spaced(RELAY_BIND_RETRY_DELAY),
+    }), Effect.catchTag('RelayBindFailed', ({ maybePort, cause }) => reportRelayBindFailed(maybePort, cause)));
+};
+// NOTE: A Vitest run can override its mode, but still carries Vitest plugins.
+// Starting a relay there can contend with the project's dev server.
+const isTestRun = (server) => server.config.mode === 'test' ||
+    server.config.plugins.some(plugin => plugin.name === 'vitest' || plugin.name.startsWith('vitest:'));
 // PROGRAM
 const main = (server, events, options) => Effect.gen(function* () {
     const state = yield* makeState;
@@ -320,8 +493,8 @@ const main = (server, events, options) => Effect.gen(function* () {
     // gives up on its boot-time model request in well under a second, so
     // sequencing the dispatch loop behind the bind would cost model
     // preservation whenever the port is contended.
-    if (options.devToolsMcpPort !== undefined) {
-        yield* Effect.forkScoped(startMcpRelay(options.devToolsMcpPort, enqueue));
+    if (options.devToolsMcpPort !== false && !isTestRun(server)) {
+        yield* Effect.forkScoped(startMcpRelay(server, options.devToolsMcpPort, enqueue));
     }
     yield* Stream.fromQueue(events).pipe(Stream.runForEach(event => dispatchEvent(server, state, event)));
 });
@@ -354,21 +527,19 @@ const withContainerId = (build, containerId) => {
         prerender: { containerId, ...prerender },
     };
 };
+const relayRegistryLayer = Layer.mergeAll(NodeFileSystem.layer, NodePath.layer, NodeCrypto.layer);
 export const foldkit = (options = {}) => {
-    const events = Effect.runSync(Queue.unbounded());
-    // NOTE: One plugin instance can serve more than one dev server, and on
-    // restart Vite builds the replacement, running `configureServer` again,
-    // before closing the server being replaced. Keying by resolved config keeps
-    // each server's shutdown pointed at its own fiber.
-    const mainFibers = new WeakMap();
+    // NOTE: During a Vite restart, old and new servers overlap. Separate queues
+    // and fibers keep their events and shutdowns attached to the right server.
+    const mainRuns = new WeakMap();
     const stopMain = (config) => Effect.suspend(() => {
-        const fiber = mainFibers.get(config);
-        mainFibers.delete(config);
-        if (fiber === undefined) {
+        const run = mainRuns.get(config);
+        mainRuns.delete(config);
+        if (run === undefined) {
             return Effect.void;
         }
         else {
-            return Fiber.interrupt(fiber);
+            return Fiber.interrupt(run.fiber);
         }
     });
     const reloadPlugin = {
@@ -383,13 +554,14 @@ export const foldkit = (options = {}) => {
             },
         }),
         configureServer: server => {
-            const fiber = Effect.runFork(Effect.scoped(main(server, events, options)));
-            mainFibers.set(server.config, fiber);
+            const events = Effect.runSync(Queue.unbounded());
+            // NOTE: The default ConfigProvider snapshots the environment. Create a
+            // fresh one so a restarted server sees current values.
+            const fiber = Effect.runFork(Effect.scoped(main(server, events, options)).pipe(Effect.provide(relayRegistryLayer), Effect.provideService(ConfigProvider.ConfigProvider, ConfigProvider.fromEnv())));
+            mainRuns.set(server.config, { events, fiber });
         },
-        // NOTE: Vite awaits `closeBundle` when the dev server closes, once per
-        // environment plugin container. Hanging shutdown off `server.httpServer`
-        // instead would never run in middleware mode, which is how Vitest and
-        // other embedders run Vite, and the relay would outlive the server.
+        // NOTE: Middleware mode has no HTTP server to close. Vite still calls
+        // `closeBundle`, so relay cleanup belongs here.
         closeBundle() {
             return Effect.runPromise(stopMain(this.environment.getTopLevelConfig()));
         },
@@ -398,7 +570,10 @@ export const foldkit = (options = {}) => {
                 return;
             }
             server.ws.send({ type: 'full-reload' });
-            Queue.offerUnsafe(events, Event.HotUpdateFired());
+            const run = mainRuns.get(server.config);
+            if (run !== undefined) {
+                Queue.offerUnsafe(run.events, Event.HotUpdateFired());
+            }
             return [];
         },
     };

package/dist/relayRegistry.d.ts

@@ -0,0 +1,17 @@
+import { Crypto, Effect, FileSystem, Option, Path, type PlatformError } from 'effect';
+import { RelayRecord } from 'foldkit/devtools-protocol';
+export type RelayPublisherServices = FileSystem.FileSystem | Path.Path | Crypto.Crypto;
+declare const RelayRegistryDirectoryRefused_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "RelayRegistryDirectoryRefused";
+} & Readonly<A>;
+export declare class RelayRegistryDirectoryRefused extends RelayRegistryDirectoryRefused_base<{
+    readonly directory: string;
+    readonly reason: string;
+}> {
+}
+export declare const relayRegistryDirectoryRefusal: (info: FileSystem.File.Info, maybeCurrentUid: Option.Option<number>) => Option.Option<string>;
+export declare const publishRelayRecord: (record: RelayRecord) => Effect.Effect<void, PlatformError.PlatformError | RelayRegistryDirectoryRefused, RelayPublisherServices>;
+export declare const readRelayRecord: (root: string) => Effect.Effect<Option.Option<RelayRecord>, never, RelayPublisherServices>;
+export declare const retireRelayRecord: (root: string, id: string) => Effect.Effect<void, never, RelayPublisherServices>;
+export {};
+//# sourceMappingURL=relayRegistry.d.ts.map

package/dist/relayRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relayRegistry.d.ts","sourceRoot":"","sources":["../src/relayRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,MAAM,EAEN,MAAM,EAEN,UAAU,EACV,MAAM,EACN,IAAI,EACJ,KAAK,aAAa,EAEnB,MAAM,QAAQ,CAAA;AACf,OAAO,EAGL,WAAW,EACZ,MAAM,2BAA2B,CAAA;AAYlC,MAAM,MAAM,sBAAsB,GAC9B,UAAU,CAAC,UAAU,GACrB,IAAI,CAAC,IAAI,GACT,MAAM,CAAC,MAAM,CAAA;;;;AAEjB,qBAAa,6BAA8B,SAAQ,mCAEjD;IACA,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB,CAAC;CAAG;AA0CL,eAAO,MAAM,6BAA6B,SAClC,UAAU,CAAC,IAAI,CAAC,IAAI,mBACT,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KACrC,MAAM,CAAC,MAAM,CAAC,MAAM,CAkBnB,CAAA;AAiCJ,eAAO,MAAM,kBAAkB,WACrB,WAAW,KAClB,MAAM,CAAC,MAAM,CACd,IAAI,EACJ,aAAa,CAAC,aAAa,GAAG,6BAA6B,EAC3D,sBAAsB,CAapB,CAAA;AAWJ,eAAO,MAAM,eAAe,SACpB,MAAM,KACX,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,sBAAsB,CAChB,CAAA;AAE1D,eAAO,MAAM,iBAAiB,SACtB,MAAM,MACR,MAAM,KACT,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,sBAAsB,CAkChD,CAAA"}

package/dist/relayRegistry.js

@@ -0,0 +1,101 @@
+import { Config, Crypto, Data, Effect, Exit, FileSystem, Option, Path, Schema, } from 'effect';
+import { RELAY_REGISTRY_DIRECTORY_NAME, RELAY_REGISTRY_DIRECTORY_VARIABLE, RelayRecord, } from 'foldkit/devtools-protocol';
+import { tmpdir } from 'node:os';
+const RUNTIME_DIRECTORY_VARIABLE = 'XDG_RUNTIME_DIR';
+const RECORD_FILE_EXTENSION = '.json';
+const REGISTRY_DIRECTORY_MODE = 0o700;
+const RECORD_FILE_MODE = 0o600;
+const PERMISSIONS_BEYOND_OWNER = 0o077;
+const PENDING_RECORD_SUFFIX = '.pending';
+const RETIRING_RECORD_SUFFIX = '.retiring';
+export class RelayRegistryDirectoryRefused extends Data.TaggedError('RelayRegistryDirectoryRefused') {
+}
+const decodeRelayRecord = Schema.decodeUnknownOption(Schema.fromJsonString(RelayRecord));
+const encodeRelayRecord = Schema.encodeUnknownSync(Schema.fromJsonString(RelayRecord));
+const relayRegistryDirectory = Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const maybeConfigured = yield* Config.option(Config.String(RELAY_REGISTRY_DIRECTORY_VARIABLE));
+    const maybeRuntimeDirectory = yield* Config.option(Config.String(RUNTIME_DIRECTORY_VARIABLE));
+    return Option.getOrElse(maybeConfigured, () => path.join(Option.getOrElse(maybeRuntimeDirectory, tmpdir), RELAY_REGISTRY_DIRECTORY_NAME));
+}).pipe(Effect.orDie);
+const relayRecordPath = (root) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const crypto = yield* Crypto.Crypto;
+    const directory = yield* relayRegistryDirectory;
+    const digest = yield* crypto
+        .digest('SHA-1', new TextEncoder().encode(root))
+        .pipe(Effect.orDie);
+    return path.join(directory, `${Buffer.from(digest).toString('hex')}${RECORD_FILE_EXTENSION}`);
+});
+export const relayRegistryDirectoryRefusal = (info, maybeCurrentUid) => Option.match(maybeCurrentUid, {
+    onNone: () => Option.some('has ownership that cannot be verified'),
+    onSome: currentUid => {
+        if (Option.isNone(info.uid)) {
+            return Option.some('has ownership that cannot be verified');
+        }
+        if (info.uid.value !== currentUid) {
+            return Option.some('is owned by another user');
+        }
+        if ((info.mode & PERMISSIONS_BEYOND_OWNER) !== 0) {
+            return Option.some('is readable or writable by other users');
+        }
+        return Option.none();
+    },
+});
+const maybeProcessUid = Option.map(Option.fromNullishOr(process.getuid), getuid => getuid());
+const ensurePrivateRegistryDirectory = (directory) => Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+    yield* fileSystem.makeDirectory(directory, {
+        recursive: true,
+        mode: REGISTRY_DIRECTORY_MODE,
+    });
+    const info = yield* fileSystem.stat(directory);
+    const maybeRefusal = relayRegistryDirectoryRefusal(info, maybeProcessUid);
+    if (Option.isSome(maybeRefusal)) {
+        return yield* Effect.fail(new RelayRegistryDirectoryRefused({
+            directory,
+            reason: maybeRefusal.value,
+        }));
+    }
+});
+export const publishRelayRecord = (record) => Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const directory = yield* relayRegistryDirectory;
+    yield* ensurePrivateRegistryDirectory(directory);
+    const recordPath = yield* relayRecordPath(record.root);
+    const pendingPath = `${recordPath}.${record.id}${PENDING_RECORD_SUFFIX}`;
+    yield* fileSystem.writeFileString(pendingPath, encodeRelayRecord(record), {
+        mode: RECORD_FILE_MODE,
+    });
+    yield* fileSystem.rename(pendingPath, recordPath);
+});
+const readRelayRecordAt = (recordPath) => Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const raw = yield* fileSystem.readFileString(recordPath);
+    return decodeRelayRecord(raw);
+}).pipe(Effect.orElseSucceed(() => Option.none()));
+export const readRelayRecord = (root) => Effect.flatMap(relayRecordPath(root), readRelayRecordAt);
+export const retireRelayRecord = (root, id) => Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const recordPath = yield* relayRecordPath(root);
+    const retiringPath = `${recordPath}.${id}${RETIRING_RECORD_SUFFIX}`;
+    const maybeRecord = yield* readRelayRecordAt(recordPath);
+    const isPublishedByRelay = Option.exists(maybeRecord, record => record.id === id);
+    if (!isPublishedByRelay) {
+        return;
+    }
+    // NOTE: A replacement may publish between the first read and rename. A
+    // hard link restores its record only if no newer record occupies the path.
+    const renameResult = yield* fileSystem
+        .rename(recordPath, retiringPath)
+        .pipe(Effect.exit);
+    if (Exit.isFailure(renameResult)) {
+        return;
+    }
+    const maybeRetiringRecord = yield* readRelayRecordAt(retiringPath);
+    const isReplacement = Option.exists(maybeRetiringRecord, record => record.id !== id);
+    if (isReplacement) {
+        yield* fileSystem.link(retiringPath, recordPath).pipe(Effect.ignore);
+    }
+    yield* fileSystem.remove(retiringPath, { force: true }).pipe(Effect.ignore);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldkit/vite-plugin",
-  "version": "0.23.0",
+  "version": "0.24.0-canary.5be04ac25e5a",
   "description": "Vite plugin for Foldkit with state-preserving live reload",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,25 +16,27 @@
     "dist"
   ],
   "peerDependencies": {
-    "effect": "4.0.0-rc.115",
-    "foldkit": ">=0.159.0",
+    "effect": "4.0.0-rc.116",
+    "foldkit": "0.163.0-canary.5be04ac25e5a",
     "vite": "^8.0.0"
   },
   "dependencies": {
+    "@effect/platform-node": "4.0.0-rc.116",
     "magic-string": "^1.2.3",
     "ws": "^8.21.3"
   },
   "devDependencies": {
     "@types/node": "^26.4.0",
     "@types/ws": "^8.18.1",
-    "effect": "4.0.0-rc.115",
+    "@vitejs/plugin-basic-ssl": "^2.3.0",
+    "effect": "4.0.0-rc.116",
     "happy-dom": "^20.11.13",
     "rimraf": "^6.1.3",
     "typescript": "^7.0.2",
     "vite": "^8.2.2",
     "vite-host": "npm:vite@8.2.1",
     "vitest": "^4.1.11",
-    "foldkit": "0.161.0"
+    "foldkit": "0.163.0-canary.5be04ac25e5a"
   },
   "keywords": [
     "vite",