@foldkit/vite-plugin 0.24.0 → 0.25.0-canary.24f1c43eaaf7

package/dist/buildToken.js

@@ -1,38 +1,28 @@
+import MagicString from 'magic-string';
+import { randomUUID } from 'node:crypto';
+import { isFoldkitSingletonPackageSpecifier } from './foldkitPackages.js';
 // The build id names the deployment a page came from. The server stamps it on
 // the rendered root, the client carries it, and hydration refuses a page whose
 // id is not its own before it adopts any DOM.
 //
-// Per-view identities cannot answer that question. They move when the view they
-// name changes, but what a view renders also depends on the constants it
-// imports, the configuration it reads, the dependencies it calls, and the
-// arguments its caller passes. A component whose own source is untouched renders
-// something different when its caller changes, and its identity is the one that
-// wins on the element, so a stale page's `<input name="email">` can otherwise be
-// adopted for a new build's `<input name="ssn">`, carrying what a visitor typed
-// into a field that submits under a different name.
+// The aggregate plugin generates one opaque id when a Vite app build contains
+// both the client and ssr environments. The id lives on the ViteBuilder's
+// ResolvedConfig object, so concurrent builders cannot overwrite one another
+// and a later builder in the same process gets a fresh value. Separately
+// invoked builds have no shared session and must receive an explicit value.
 //
-// The id is supplied by the deployment rather than derived from the project.
-// Deriving it was tried and does not hold: a digest of the files under the Vite
-// root misses shared modules from elsewhere in a monorepo, untracked inputs, and
-// environment-derived configuration, so two deployments that render differently
-// can share an id; it moves when a build writes output the next build reads, so
-// one deployment can produce two ids; and hashing whatever files happen to sit
-// in the project turns a value published in HTML into an oracle for the secrets
-// among them. A value the deployment already has (a commit, a release tag, a
-// container digest) has none of those problems.
-//
-// This plugin only compiles the id into application code. Foldkit itself is an
-// ordinary dependency that Vite externalizes from a server build, where a
-// compile-time define never reaches it, so the id is handed to `renderToString`
-// and `Runtime.hydrate` explicitly rather than read from inside the framework.
-//
-// Development is compiled an id too. The dev SSR host renders through
-// `renderToString` like any other, and a hydratable render refuses to run
-// without one, so leaving development unnamed would fail every dev page
-// request.
+// Foldkit's own build-token module contains a placeholder call. This transform
+// replaces that call in both artifacts, which lets Runtime.hydrate and
+// renderToString consume the value without application forwarding. Installed
+// Foldkit must therefore participate in the server build; the aggregate plugin
+// configures that boundary and the post-build check refuses an artifact that
+// still imports Foldkit externally.
 const BUILD_ID_ENVIRONMENT_VARIABLE = 'FOLDKIT_BUILD_ID';
-/** The build id this build was given, from the plugin option or
- *  `FOLDKIT_BUILD_ID`, or `undefined` when the deployment supplied neither.
+const FRAMEWORK_BUILD_ID_PLACEHOLDER = 'foldkitBuildIdPlaceholder()';
+const buildIdentitySessions = new WeakMap();
+const developmentBuildIds = new WeakMap();
+/** The build id explicitly supplied through plugin configuration or the
+ *  environment, or `undefined` when neither supplied a nonempty value.
  *
  * @internal Exported for tests.
  */
@@ -45,19 +35,7 @@ export const resolveBuildId = (configured) => {
         ? fromEnvironment
         : undefined;
 };
-// The id development serves. Development is the one place a constant is right:
-// one live source session supplies both the server and client transforms rather
-// than producing independently deployable artifacts. A value that moved would
-// only make the dev server disagree with the tab already open against it. A
-// hydratable render still requires an id, so development has to be given one
-// rather than left without.
-//
-// It is exactly wrong for a build, which is why a build with no id is refused
-// rather than defaulted: two deployments sharing an id is the case the id
-// exists to catch.
-const DEVELOPMENT_BUILD_ID = 'development';
-/** The value `import.meta.env.FOLDKIT_BUILD_ID` compiles to, or `undefined`
- *  when a build was given no id and must refuse to render a hydratable page.
+/** The id a standalone plugin compiles for one Vite command.
  *
  * @internal Exported for tests.
  */
@@ -66,29 +44,140 @@ export const buildIdForCommand = (command, configured) => {
     if (resolved !== undefined) {
         return resolved;
     }
-    return command === 'serve' ? DEVELOPMENT_BUILD_ID : undefined;
+    return command === 'serve' ? 'development' : undefined;
+};
+const hasCoordinatedArtifacts = (builder) => builder.environments['client'] !== undefined &&
+    builder.environments['ssr'] !== undefined;
+const beginBuildIdentity = (builder, configuredBuildId, verifyFrameworkIdentity) => {
+    const isCoordinated = hasCoordinatedArtifacts(builder);
+    const buildId = configuredBuildId ?? (isCoordinated ? randomUUID() : undefined);
+    const session = {
+        buildId,
+        externalizedEnvironments: new Set(),
+        verifyFrameworkIdentity,
+    };
+    buildIdentitySessions.set(builder.config, session);
+    for (const environment of Object.values(builder.environments)) {
+        buildIdentitySessions.set(environment.config, session);
+        buildIdentitySessions.set(environment.getTopLevelConfig(), session);
+    }
+};
+const buildIdForConfig = (config, configuredBuildId) => {
+    if (config.command === 'build') {
+        return buildIdentitySessions.get(config)?.buildId ?? configuredBuildId;
+    }
+    const existing = developmentBuildIds.get(config);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const fresh = configuredBuildId ?? randomUUID();
+    developmentBuildIds.set(config, fresh);
+    return fresh;
+};
+const replaceAll = (source, code, search, replacement) => {
+    let didReplace = false;
+    let fromIndex = 0;
+    while (fromIndex < code.length) {
+        const index = code.indexOf(search, fromIndex);
+        if (index === -1) {
+            return didReplace;
+        }
+        source.overwrite(index, index + search.length, replacement);
+        didReplace = true;
+        fromIndex = index + search.length;
+    }
+    return didReplace;
 };
-/**
- * Compiles the deployment's build id into application code as
- * `import.meta.env.FOLDKIT_BUILD_ID`, for the client entry and the server entry
- * to hand to `Runtime.hydrate` and `renderToString`.
+const isFoldkitBuildTokenModule = (id) => {
+    const fileName = (id.split('?', 1)[0] ?? '').replaceAll('\\', '/');
+    return (fileName.endsWith('/foldkit/src/buildToken.ts') ||
+        fileName.endsWith('/foldkit/dist/buildToken.js'));
+};
+const hasExternalFoldkitSingletonImport = (imports, dynamicImports) => [...imports, ...dynamicImports].some(isFoldkitSingletonPackageSpecifier);
+const transformBuildIdentity = (code, id, config, configuredBuildId) => {
+    if (!isFoldkitBuildTokenModule(id) ||
+        !code.includes(FRAMEWORK_BUILD_ID_PLACEHOLDER)) {
+        return undefined;
+    }
+    const buildId = buildIdForConfig(config, configuredBuildId);
+    const replacement = buildId === undefined ? 'undefined' : JSON.stringify(buildId);
+    const transformed = new MagicString(code);
+    const transformedFramework = replaceAll(transformed, code, FRAMEWORK_BUILD_ID_PLACEHOLDER, replacement);
+    if (!transformedFramework) {
+        return undefined;
+    }
+    return {
+        code: transformed.toString(),
+        map: transformed.generateMap({ hires: 'boundary', source: id }),
+    };
+};
+const verifyBuildIdentity = (builder) => {
+    const session = buildIdentitySessions.get(builder.config);
+    if (session === undefined || !session.verifyFrameworkIdentity) {
+        return;
+    }
+    const externalized = [...session.externalizedEnvironments];
+    if (externalized.length === 0) {
+        return;
+    }
+    throw new Error('[foldkit] A Foldkit singleton package was externalized from the ' +
+        `${externalized.join(' and ')} ` +
+        `${externalized.length === 1 ? 'artifact' : 'artifacts'}, so it can ` +
+        'load a framework copy whose hydration build identity was not compiled. ' +
+        'Remove Foldkit packages from explicit SSR or Rolldown externalization ' +
+        'settings and let @foldkit/vite-plugin bundle them.');
+};
+/** Compiles one build identity into application entries and Foldkit itself.
  *
- * A build takes the id from the `buildId` option or `FOLDKIT_BUILD_ID` and
- * compiles nothing when it was given neither, so a hydratable render fails with
- * `MissingBuildId` rather than serving a page hydration cannot place.
- * Development serves a fixed id instead because one live source session
- * supplies both transforms and has no deployment identity to derive.
+ * @internal
  */
-export const foldkitBuildToken = (buildId) => ({
-    name: 'foldkit:build-token',
-    config: (_config, { command }) => {
-        const resolved = buildIdForCommand(command, buildId);
-        return resolved === undefined
-            ? {}
-            : {
-                define: {
-                    'import.meta.env.FOLDKIT_BUILD_ID': JSON.stringify(resolved),
+export const foldkitBuildToken = (buildId, verifyFrameworkIdentity = true) => {
+    const configuredBuildId = resolveBuildId(buildId);
+    return [
+        {
+            name: 'foldkit:build-token',
+            enforce: 'pre',
+            sharedDuringBuild: true,
+            config: (_config, { command }) => {
+                const legacyBuildId = configuredBuildId ?? (command === 'serve' ? 'development' : undefined);
+                return legacyBuildId === undefined
+                    ? {}
+                    : {
+                        define: {
+                            'import.meta.env.FOLDKIT_BUILD_ID': JSON.stringify(legacyBuildId),
+                        },
+                    };
+            },
+            buildApp: {
+                order: 'pre',
+                async handler(builder) {
+                    beginBuildIdentity(builder, configuredBuildId, verifyFrameworkIdentity);
                 },
-            };
-    },
-});
+            },
+            transform(code, id) {
+                const config = this.environment.getTopLevelConfig();
+                return transformBuildIdentity(code, id, config, configuredBuildId);
+            },
+            generateBundle(_options, bundle) {
+                const isExternalized = Object.values(bundle).some(output => output.type === 'chunk' &&
+                    hasExternalFoldkitSingletonImport(output.imports, output.dynamicImports));
+                if (!isExternalized) {
+                    return;
+                }
+                buildIdentitySessions
+                    .get(this.environment.getTopLevelConfig())
+                    ?.externalizedEnvironments.add(this.environment.name);
+            },
+        },
+        {
+            name: 'foldkit:verify-build-token',
+            sharedDuringBuild: true,
+            buildApp: {
+                order: 'post',
+                async handler(builder) {
+                    verifyBuildIdentity(builder);
+                },
+            },
+        },
+    ];
+};

package/dist/foldkitPackages.d.ts

@@ -0,0 +1,12 @@
+/** Tests whether an import refers to a package that must share Foldkit's
+ * runtime instance.
+ *
+ * @internal
+ */
+export declare const isFoldkitSingletonPackageSpecifier: (specifier: string) => boolean;
+/** Resolves the installed packages that must share Foldkit's runtime instance.
+ *
+ * @internal
+ */
+export declare const resolveInstalledFoldkitPackages: (root: string) => Array<string>;
+//# sourceMappingURL=foldkitPackages.d.ts.map

package/dist/foldkitPackages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foldkitPackages.d.ts","sourceRoot":"","sources":["../src/foldkitPackages.ts"],"names":[],"mappings":"AAUA;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,cAClC,MAAM,KAChB,OAKA,CAAA;AAEH;;;GAGG;AACH,eAAO,MAAM,+BAA+B,SACpC,MAAM,KACX,KAAK,CAAC,MAAM,CAmBd,CAAA"}

package/dist/foldkitPackages.js

@@ -0,0 +1,37 @@
+import { Array, Predicate } from 'effect';
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+const FOLDKIT_SINGLETON_PACKAGES = [
+    'foldkit',
+    '@foldkit/ui',
+    '@foldkit/devtools',
+];
+/** Tests whether an import refers to a package that must share Foldkit's
+ * runtime instance.
+ *
+ * @internal
+ */
+export const isFoldkitSingletonPackageSpecifier = (specifier) => Array.some(FOLDKIT_SINGLETON_PACKAGES, packageName => specifier === packageName || specifier.startsWith(`${packageName}/`));
+/** Resolves the installed packages that must share Foldkit's runtime instance.
+ *
+ * @internal
+ */
+export const resolveInstalledFoldkitPackages = (root) => {
+    // NOTE: Vite can supply a relative root before it resolves the config, while
+    // createRequire requires an absolute path.
+    const requireFromRoot = createRequire(resolve(root, 'noop.js'));
+    return Array.filter(FOLDKIT_SINGLETON_PACKAGES, packageName => {
+        try {
+            requireFromRoot.resolve(packageName);
+            return true;
+        }
+        catch (error) {
+            // NOTE: optional ESM-only packages can throw
+            // ERR_PACKAGE_PATH_NOT_EXPORTED even when installed. Only
+            // MODULE_NOT_FOUND proves this consumer does not have the package.
+            return !(error instanceof Error &&
+                Predicate.hasProperty(error, 'code') &&
+                error.code === 'MODULE_NOT_FOUND');
+        }
+    });
+};

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
@@ -35,25 +38,21 @@ export type FoldkitPluginOptions = Readonly<{
         build?: boolean | FoldkitBuildOptions;
     }>;
     /**
-     * The deployment this build belongs to, compiled into application code as
-     * `import.meta.env.FOLDKIT_BUILD_ID` for the entries to pass to
-     * `renderToString` and `Runtime.hydrate`. Hydration compares it against the id
-     * the server stamped and refuses a page from another deployment rather than
-     * adopting it: startup stops and the page is contained, with the document's
-     * body marked `inert`.
+     * An explicit identity for the deployment this build belongs to. Foldkit
+     * normally generates an opaque identity when one Vite app build coordinates
+     * the client and server artifacts, then compiles it into the framework in
+     * both. Hydration compares that value against the id the server stamped and
+     * refuses a page from another deployment before adopting its DOM.
      *
-     * Defaults to the `FOLDKIT_BUILD_ID` environment variable. Use a value the
-     * deployment already has, such as a commit or a release tag, and give the
-     * client build and the server build the same one. It is published in the
-     * page, so it must not be a secret.
+     * Set this when the client and server are built separately, or when the id
+     * should name a deployment in another system. The `FOLDKIT_BUILD_ID`
+     * environment variable supplies the same override when this option is
+     * absent. Give every artifact the same value. It is published in the page,
+     * so it must not be a secret.
      *
-     * Whatever supplies it has to answer with the same value every time it is
-     * asked, because Vite reads a config file once per environment it builds. A
-     * config that computes a fresh value on each read — `randomUUID()`, a
-     * timestamp — gives the browser bundle and the server bundle different ids
-     * within one build, and every page of that deployment is then refused at
-     * hydration. Read it from the environment, or store a generated fallback
-     * back into the environment so later reads resolve the same id.
+     * Reusing an override across deployments makes stale pages appear current.
+     * Use a value that changes whenever the deployment's rendering inputs can
+     * change.
      */
     buildId?: string;
 }>;

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":"AA6CA,OAAO,KAAK,EAEV,MAAM,EAIP,MAAM,MAAM,CAAA;AAOb,OAAO,EAAE,KAAK,mBAAmB,EAAgB,MAAM,YAAY,CAAA;AAKnE,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;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAC,CAAA;AAs6BF,eAAO,MAAM,OAAO,aAAa,oBAAoB,KAAQ,KAAK,CAAC,MAAM,CAuHxE,CAAA"}