@foldkit/vite-plugin 0.23.0 → 0.24.0-canary.63949f4e9660

package/README.md

@@ -110,13 +110,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,26 +68,12 @@ 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.
- *
- * 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.
+ * The decoded shape of `foldkit.build.json`.
  *
- * 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;
 export declare const manifestPath: (root: string, directory: string, pathApi?: typeof nodePath) => string;
@@ -102,11 +85,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;
 //# 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;AAcnE,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;AA4GD;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,gBACV,MAAM,YACV,mBAAmB,KAC3B,MAqOF,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,6 @@ 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'])),
 });
 const MANIFEST_SCHEMA_VERSION = 1;
 // Relative and POSIX so the manifest describes a layout rather than this
@@ -59,6 +50,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';
@@ -212,7 +204,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,11 +212,10 @@ 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 clientOutDir = options.clientOutDir ?? DEFAULT_CLIENT_OUT_DIR;
@@ -274,7 +265,6 @@ export const foldkitBuild = (serverEntry, options = {}) => {
             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}`);
@@ -307,7 +297,7 @@ 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;
         };
@@ -318,7 +308,6 @@ export const foldkitBuild = (serverEntry, options = {}) => {
         name: 'foldkit:build',
         apply: 'build',
         api: {
-            host: 'fetch',
             serverEntry,
             fetchModuleId: FOLDKIT_FETCH_MODULE_ID,
         },
@@ -336,23 +325,26 @@ export const foldkitBuild = (serverEntry, options = {}) => {
             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) {
+                const state = captured(this.environment.config.root);
+                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

@@ -8,12 +8,15 @@ export { type ViewIdentityTransformResult, foldkitViewIdentity, transformViewIde
 /** 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,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,12 +1,18 @@
-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';
@@ -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.63949f4e9660",
   "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.63949f4e9660",
     "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.63949f4e9660"
   },
   "keywords": [
     "vite",