@multiplatform.one/config 7.11.0 → 7.15.0

package/src/oxlintPreset.spec.ts

@@ -0,0 +1,65 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterAll, describe, expect, it } from "vitest";
+
+// MPO-23 ruling 2A (Clay, 2026-09-26): a consumer turns the convention rules
+// on with one `extends` line and no rules block of its own.
+const packageDir = join(dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8")) as {
+  exports: Record<string, unknown>;
+  files: string[];
+};
+const oxlintBin = join(
+  dirname(createRequire(import.meta.url).resolve("oxlint/package.json")),
+  "bin",
+  "oxlint",
+);
+
+const project = mkdtempSync(join(tmpdir(), "mpo-oxlint-preset-"));
+afterAll(() => rmSync(project, { recursive: true, force: true }));
+
+function lint(files: Record<string, string>): string {
+  mkdirSync(join(project, "node_modules", "@multiplatform.one"), { recursive: true });
+  try {
+    symlinkSync(packageDir, join(project, "node_modules", "@multiplatform.one", "config"));
+  } catch {
+    // already linked by an earlier case
+  }
+  writeFileSync(
+    join(project, ".oxlintrc.json"),
+    JSON.stringify({ extends: ["./node_modules/@multiplatform.one/config/oxlint.json"] }),
+  );
+  for (const [path, source] of Object.entries(files)) {
+    mkdirSync(dirname(join(project, path)), { recursive: true });
+    writeFileSync(join(project, path), source);
+  }
+  try {
+    return execFileSync(oxlintBin, ["-c", ".oxlintrc.json", ...Object.keys(files)], {
+      cwd: project,
+      encoding: "utf8",
+    });
+  } catch (error) {
+    return String((error as { stdout?: string }).stdout ?? "");
+  }
+}
+
+describe("oxlint preset (MPO-23 2A)", () => {
+  it("ships as ./oxlint.json and is in the published files", () => {
+    expect(pkg.exports["./oxlint.json"]).toBe("./oxlint.json");
+    expect(pkg.files).toContain("oxlint.json");
+  });
+
+  it("an extends line alone turns the hex rule on, and specs stay exempt", () => {
+    const out = lint({
+      "features/demo/Swatch.tsx": 'export const swatch = "#ff0000";\n',
+      "features/demo/Swatch.spec.tsx": 'export const fixture = "#00ff00";\n',
+    });
+    expect(out).toContain("mpo-conventions(no-hex-literals)");
+    expect(out).toContain("Swatch.tsx");
+    expect(out).not.toContain("Swatch.spec.tsx");
+  });
+});

package/src/publicConfig.spec.ts

@@ -0,0 +1,272 @@
+/**
+ * publicConfigFile (MPO-247): config.json is read, not imported, so an edit
+ * never restarts the dev server; the plugin inlines the bake, watches the file
+ * and reloads clients with the new keys instead.
+ */
+
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { loadConfigFromFile } from "vite";
+import type { Plugin, ViteDevServer } from "vite";
+import { publicConfigPlugin, readPublicConfigKeys } from "./publicConfig.js";
+
+const bakedKeys = "VITE_MP_PUBLIC_CONFIG_KEYS";
+const bakedValues = "VITE_MP_CONFIG";
+
+let dir: string;
+let file: string;
+
+beforeEach(() => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), "mpo-public-config-"));
+  file = path.join(dir, "config.json");
+  delete process.env[bakedKeys];
+  delete process.env[bakedValues];
+});
+
+afterEach(() => {
+  fs.rmSync(dir, { recursive: true, force: true });
+  delete process.env.MPO_SPEC_FOO;
+  delete process.env.MPO_SPEC_BAR;
+});
+
+function writeConfig(publicKeys: unknown, extra: Record<string, unknown> = {}) {
+  fs.writeFileSync(file, JSON.stringify({ private: ["SECRET"], public: publicKeys, ...extra }));
+}
+
+type FakeEnvironment = {
+  modules: Map<string, { id: string }>;
+  moduleGraph: {
+    getModuleById: (id: string) => unknown;
+    invalidateModule: ReturnType<typeof vi.fn>;
+  };
+  hot: { send: ReturnType<typeof vi.fn> };
+};
+
+function fakeServer() {
+  const watcher = Object.assign(new EventEmitter(), { add: vi.fn() });
+  const environment = (): FakeEnvironment => {
+    const modules = new Map<string, { id: string }>();
+    return {
+      modules,
+      moduleGraph: { getModuleById: (id: string) => modules.get(id), invalidateModule: vi.fn() },
+      hot: { send: vi.fn() },
+    };
+  };
+  const environments = { client: environment(), ssr: environment() };
+  const logger = { info: vi.fn(), warn: vi.fn() };
+  const server = { watcher, environments, config: { logger } };
+  return { server: server as unknown as ViteDevServer, watcher, environments, logger };
+}
+
+type TransformEnvironment = {
+  name: string;
+  config: { consumer: "client" | "server" };
+  depsOptimizer?: { isOptimizedDepFile: (id: string) => boolean };
+};
+
+async function transform(
+  plugin: Plugin,
+  environment: string | TransformEnvironment,
+  code: string,
+  id: string,
+) {
+  const hook = plugin.transform as (
+    this: { environment: TransformEnvironment },
+    code: string,
+    id: string,
+  ) => Promise<{ code: string } | undefined>;
+  const context =
+    typeof environment === "string"
+      ? {
+          name: environment,
+          config: { consumer: environment === "ssr" ? ("server" as const) : ("client" as const) },
+        }
+      : environment;
+  return await hook.call({ environment: context }, code, id);
+}
+
+function configureServer(plugin: Plugin, server: ViteDevServer) {
+  (plugin.configureServer as (server: ViteDevServer) => void)(server);
+}
+
+describe("readPublicConfigKeys", () => {
+  it("returns the public key names", () => {
+    writeConfig(["FRAPPE_ENABLED", "FRAPPE_URL"]);
+    expect(readPublicConfigKeys(file)).toEqual(["FRAPPE_ENABLED", "FRAPPE_URL"]);
+  });
+
+  it("drops anything that is not a key name and tolerates a missing list", () => {
+    writeConfig(["A", 1, "", null, "B"]);
+    expect(readPublicConfigKeys(file)).toEqual(["A", "B"]);
+    fs.writeFileSync(file, JSON.stringify({ private: ["SECRET"] }));
+    expect(readPublicConfigKeys(file)).toEqual([]);
+  });
+});
+
+describe("config.json as a vite config dependency", () => {
+  it("an imported config.json restarts the server on edit; a read one is not tracked at all", async () => {
+    writeConfig(["A"]);
+    const imported = path.join(dir, "imported.config.mjs");
+    const read = path.join(dir, "read.config.mjs");
+    fs.writeFileSync(
+      imported,
+      'import config from "./config.json" with { type: "json" };\n' +
+        "export default { define: { keys: config.public } };\n",
+    );
+    fs.writeFileSync(
+      read,
+      'import fs from "node:fs";\n' +
+        'const config = JSON.parse(fs.readFileSync(new URL("./config.json", import.meta.url), "utf-8"));\n' +
+        "export default { define: { keys: config.public } };\n",
+    );
+    const env = { command: "serve", mode: "development" } as const;
+    const viaImport = await loadConfigFromFile(env, imported, dir);
+    const viaRead = await loadConfigFromFile(env, read, dir);
+    expect(viaImport?.dependencies.some((dep) => dep.endsWith("config.json"))).toBe(true);
+    expect(viaRead?.dependencies.some((dep) => dep.endsWith("config.json"))).toBe(false);
+    expect(viaRead?.config.define).toEqual({ keys: ["A"] });
+  });
+});
+
+describe("publicConfigPlugin", () => {
+  it("bakes on construction and inlines exactly the two baked expressions", async () => {
+    writeConfig(["MPO_SPEC_FOO"]);
+    process.env.MPO_SPEC_FOO = "bar";
+    const plugin = publicConfigPlugin({ file, projectRoot: dir, keys: ["INLINE"] });
+    expect(plugin.apply).toBe("serve");
+    expect(JSON.parse(process.env[bakedKeys]!)).toEqual(["INLINE", "MPO_SPEC_FOO"]);
+    const out = await transform(
+      plugin,
+      "client",
+      "const a = process.env.VITE_MP_CONFIG;\n" +
+        "const b = process.env.VITE_MP_PUBLIC_CONFIG_KEYS;\n" +
+        "const c = process.env.VITE_MP_CONFIGX + process.env.OTHER;\n",
+      "/app/runtimeConfig.ts",
+    );
+    expect(out?.code).toBe(
+      `const a = ${JSON.stringify(JSON.stringify({ MPO_SPEC_FOO: "bar" }))};\n` +
+        `const b = ${JSON.stringify(JSON.stringify(["INLINE", "MPO_SPEC_FOO"]))};\n` +
+        "const c = process.env.VITE_MP_CONFIGX + process.env.OTHER;\n",
+    );
+    expect(await transform(plugin, "client", "const d = process.env.OTHER;", "/app/other.ts")).toBe(
+      undefined,
+    );
+    expect(
+      await transform(plugin, "client", '{"x":"process.env.VITE_MP_CONFIG"}', "/app/data.json"),
+    ).toBe(undefined);
+  });
+
+  it("replaces only real reads: strings, assignment targets and globalThis reads stay as written", async () => {
+    writeConfig(["MPO_SPEC_FOO"]);
+    process.env.MPO_SPEC_FOO = "bar";
+    const plugin = publicConfigPlugin({ file, projectRoot: dir });
+    const out = await transform(
+      plugin,
+      "ssr",
+      'const hint = "set process.env.VITE_MP_CONFIG first";\n' +
+        'globalThis.process.env.VITE_MP_CONFIG ??= "{}";\n' +
+        'process.env.VITE_MP_PUBLIC_CONFIG_KEYS = "[]";\n' +
+        "export const a = process?.env?.VITE_MP_CONFIG;\n",
+      "/app/runtimeConfig.ts",
+    );
+    expect(out?.code).toContain('"set process.env.VITE_MP_CONFIG first"');
+    expect(out?.code).toContain("globalThis.process.env.VITE_MP_CONFIG ??=");
+    expect(out?.code).toContain("process.env.VITE_MP_PUBLIC_CONFIG_KEYS =");
+    expect(out?.code).toContain(
+      `export const a = ${JSON.stringify(JSON.stringify({ MPO_SPEC_FOO: "bar" }))};`,
+    );
+  });
+
+  it("leaves browser-cached client files to vite's injected define and still inlines them for ssr", async () => {
+    writeConfig(["MPO_SPEC_FOO"]);
+    const plugin = publicConfigPlugin({ file, projectRoot: dir });
+    const code = "export const keys = process.env.VITE_MP_PUBLIC_CONFIG_KEYS;";
+    const inlined = `export const keys = ${JSON.stringify(JSON.stringify(["MPO_SPEC_FOO"]))};\n`;
+    const installed = "/proj/node_modules/@multiplatform.one/platform/lib/config/runtimeConfig.js";
+    const optimized = "/proj/.cache/vite/deps/@multiplatform__one_platform.js";
+    expect(await transform(plugin, "client", code, installed)).toBeUndefined();
+    expect((await transform(plugin, "ssr", code, installed))?.code).toBe(inlined);
+    const optimizer = { isOptimizedDepFile: (id: string) => id === optimized };
+    expect(
+      await transform(
+        plugin,
+        { name: "client", config: { consumer: "client" }, depsOptimizer: optimizer },
+        code,
+        optimized,
+      ),
+    ).toBeUndefined();
+    const source = await transform(
+      plugin,
+      { name: "client", config: { consumer: "client" }, depsOptimizer: optimizer },
+      code,
+      "/proj/apps/web/runtimeConfig.ts",
+    );
+    expect(source?.code).toBe(inlined);
+  });
+
+  it("watches the file and, when the keys change, rebakes, invalidates the inlined modules and reloads", async () => {
+    writeConfig(["MPO_SPEC_FOO"]);
+    process.env.MPO_SPEC_FOO = "bar";
+    const plugin = publicConfigPlugin({ file, projectRoot: dir });
+    const { server, watcher, environments, logger } = fakeServer();
+    configureServer(plugin, server);
+    expect(watcher.add).toHaveBeenCalledWith(file);
+
+    const code = "export const keys = process.env.VITE_MP_PUBLIC_CONFIG_KEYS;";
+    await transform(plugin, "client", code, "/app/runtimeConfig.ts");
+    await transform(plugin, "ssr", code, "/app/runtimeConfig.ts");
+    const clientModule = { id: "/app/runtimeConfig.ts" };
+    const ssrModule = { id: "/app/runtimeConfig.ts" };
+    environments.client.modules.set(clientModule.id, clientModule);
+    environments.ssr.modules.set(ssrModule.id, ssrModule);
+
+    fs.writeFileSync(path.join(dir, ".env"), "MPO_SPEC_BAR=from-dotenv\n");
+    writeConfig(["MPO_SPEC_FOO", "MPO_SPEC_BAR"]);
+    watcher.emit("change", file);
+
+    expect(JSON.parse(process.env[bakedKeys]!)).toEqual(["MPO_SPEC_FOO", "MPO_SPEC_BAR"]);
+    expect(JSON.parse(process.env[bakedValues]!)).toEqual({
+      MPO_SPEC_FOO: "bar",
+      MPO_SPEC_BAR: "from-dotenv",
+    });
+    expect(environments.client.moduleGraph.invalidateModule).toHaveBeenCalledWith(clientModule);
+    expect(environments.ssr.moduleGraph.invalidateModule).toHaveBeenCalledWith(ssrModule);
+    expect(environments.client.hot.send).toHaveBeenCalledWith({ type: "full-reload", path: "*" });
+    expect(environments.ssr.hot.send).toHaveBeenCalledWith({ type: "full-reload", path: "*" });
+    expect(logger.info).toHaveBeenCalledTimes(1);
+    expect((await transform(plugin, "client", code, "/app/runtimeConfig.ts"))?.code).toBe(
+      `export const keys = ${JSON.stringify(JSON.stringify(["MPO_SPEC_FOO", "MPO_SPEC_BAR"]))};\n`,
+    );
+  });
+
+  it("stays quiet when an edit leaves the public keys as they were", () => {
+    writeConfig(["MPO_SPEC_FOO"]);
+    const plugin = publicConfigPlugin({ file, projectRoot: dir });
+    const { server, watcher, environments } = fakeServer();
+    configureServer(plugin, server);
+    writeConfig(["MPO_SPEC_FOO"], { private: ["SECRET", "OTHER_SECRET"] });
+    watcher.emit("change", file);
+    watcher.emit("change", path.join(dir, "unrelated.json"));
+    expect(environments.client.hot.send).not.toHaveBeenCalled();
+    expect(environments.ssr.hot.send).not.toHaveBeenCalled();
+  });
+
+  it("keeps the previous keys through a half-written file and picks up the finished one", () => {
+    writeConfig(["MPO_SPEC_FOO"]);
+    const plugin = publicConfigPlugin({ file, projectRoot: dir });
+    const { server, watcher, environments, logger } = fakeServer();
+    configureServer(plugin, server);
+    fs.writeFileSync(file, '{ "public": ["MPO_SPEC_FOO", ');
+    watcher.emit("change", file);
+    expect(logger.warn).toHaveBeenCalledTimes(1);
+    expect(JSON.parse(process.env[bakedKeys]!)).toEqual(["MPO_SPEC_FOO"]);
+    expect(environments.client.hot.send).not.toHaveBeenCalled();
+    writeConfig(["MPO_SPEC_FOO", "MPO_SPEC_BAR"]);
+    watcher.emit("add", file);
+    expect(JSON.parse(process.env[bakedKeys]!)).toEqual(["MPO_SPEC_FOO", "MPO_SPEC_BAR"]);
+    expect(environments.client.hot.send).toHaveBeenCalledTimes(1);
+  });
+});

package/src/publicConfig.ts

@@ -0,0 +1,170 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveConfig } from "@multiplatform.one/utils/dev";
+import dotenv from "dotenv";
+import { transformWithOxc } from "vite";
+import type { Environment, Plugin, ViteDevServer } from "vite";
+
+export const bakedConfigEnvKey = "VITE_MP_CONFIG";
+export const publicConfigKeysEnvKey = "VITE_MP_PUBLIC_CONFIG_KEYS";
+
+/**
+ * The `public` key names of a config.json, read rather than imported: a
+ * static import puts the file on Vite's configFileDependencies, and every
+ * edit then restarts the dev server, re-optimizes deps and 504s each open tab
+ * (MPO-247). A read keeps it off that list.
+ */
+export function readPublicConfigKeys(file: string): string[] {
+  const parsed: unknown = JSON.parse(fs.readFileSync(file, "utf-8"));
+  const keys = parsed && typeof parsed === "object" ? (parsed as { public?: unknown }).public : [];
+  if (!Array.isArray(keys)) return [];
+  return keys.filter((key): key is string => typeof key === "string" && key.length > 0);
+}
+
+export function mergePublicConfigKeys(...lists: string[][]): string[] {
+  return [...new Set(lists.flat())];
+}
+
+/**
+ * Put the bake on process.env: the values resolved from the environment under
+ * VITE_MP_CONFIG and the key NAMES under VITE_MP_PUBLIC_CONFIG_KEYS. Names,
+ * never a value, is what lets the SSR node process resolve them from its own
+ * environment at request time (@multiplatform.one/platform runtimeConfig.ts).
+ */
+export function bakePublicConfig(keys: string[]): void {
+  process.env[bakedConfigEnvKey] = JSON.stringify(resolveConfig(keys));
+  process.env[publicConfigKeysEnvKey] = JSON.stringify(keys);
+}
+
+export interface PublicConfigPluginOptions {
+  /** Absolute path of the config.json whose `public` array names the keys. */
+  file: string;
+  /** Directory holding the `.env` the values are resolved from. */
+  projectRoot: string;
+  /** Keys the config declares inline, kept alongside the file's. */
+  keys?: string[];
+}
+
+const bakedExpression = /\bprocess\??\.env\??\.(?:VITE_MP_CONFIG|VITE_MP_PUBLIC_CONFIG_KEYS)\b/;
+const nonScriptRequest = /\.(?:json|css|html)(?:$|\?)/;
+const nodeModulesPath = /[\\/]node_modules[\\/]/;
+
+/**
+ * The same replacement vite:define makes, done through oxc so only real
+ * `process.env.<KEY>` reads change: a string, an assignment target or a
+ * `globalThis.process.env.<KEY>` is left as written.
+ */
+function bakedDefine(): Record<string, string> {
+  return Object.fromEntries(
+    [bakedConfigEnvKey, publicConfigKeysEnvKey].map((key) => [
+      `process.env.${key}`,
+      JSON.stringify(process.env[key] ?? ""),
+    ]),
+  );
+}
+
+/**
+ * The browser caches node_modules files and optimized deps as immutable under
+ * a ?v= hash that no define value feeds, so a value inlined there would
+ * outlive every reload and restart. Those keep reading the defines vite
+ * injects through /@vite/env instead.
+ */
+function browserCached(environment: Environment | undefined, id: string): boolean {
+  if (!environment || environment.config.consumer === "server") return false;
+  if (nodeModulesPath.test(id)) return true;
+  return "depsOptimizer" in environment && !!environment.depsOptimizer?.isOptimizedDepFile(id);
+}
+
+/**
+ * Dev-server half of `publicConfigFile`. vite:define freezes its replacement
+ * table per environment when the server starts, so this plugin inlines the
+ * two baked expressions itself (it runs ahead of vite:define), remembers the
+ * modules that carried them, and when config.json changes rebakes,
+ * invalidates those modules and reloads every environment. The server never
+ * restarts, so the dep optimizer never runs again.
+ */
+export function publicConfigPlugin(options: PublicConfigPluginOptions): Plugin {
+  const file = path.resolve(options.file);
+  const envFile = path.resolve(options.projectRoot, ".env");
+  const inlineKeys = options.keys ?? [];
+  const bakedModules = new Map<string, Set<string>>();
+
+  function readKeys(): string[] {
+    return mergePublicConfigKeys(inlineKeys, readPublicConfigKeys(file));
+  }
+
+  function bake(next: string[]) {
+    dotenv.config({ path: envFile, quiet: true });
+    bakePublicConfig(next);
+  }
+
+  let keys = readKeys();
+  bake(keys);
+
+  function refresh(server: ViteDevServer) {
+    const label = path.relative(process.cwd(), file);
+    let next: string[];
+    try {
+      next = readKeys();
+    } catch (err) {
+      server.config.logger.warn(
+        `${label}: ${(err as Error).message}; keeping the previous public keys`,
+        { timestamp: true },
+      );
+      return;
+    }
+    if (next.length === keys.length && next.every((key, i) => key === keys[i])) return;
+    keys = next;
+    bake(keys);
+    for (const [name, ids] of bakedModules) {
+      const environment = server.environments[name];
+      if (!environment) continue;
+      for (const id of ids) {
+        const mod = environment.moduleGraph.getModuleById(id);
+        if (mod) environment.moduleGraph.invalidateModule(mod);
+      }
+    }
+    for (const environment of Object.values(server.environments)) {
+      environment.hot.send({ type: "full-reload", path: "*" });
+    }
+    server.config.logger.info(`${label} changed, reloading with public keys ${keys.join(", ")}`, {
+      timestamp: true,
+    });
+  }
+
+  return {
+    name: "multiplatform-public-config",
+    apply: "serve",
+    async transform(code, id) {
+      if (nonScriptRequest.test(id) || !bakedExpression.test(code)) return;
+      if (browserCached(this.environment, id)) return;
+      let result: Awaited<ReturnType<typeof transformWithOxc>>;
+      try {
+        result = await transformWithOxc(code, id, {
+          lang: "js",
+          sourceType: "module",
+          define: bakedDefine(),
+          tsconfig: false,
+        });
+      } catch {
+        return;
+      }
+      const name = this.environment?.name ?? "client";
+      let ids = bakedModules.get(name);
+      if (!ids) {
+        ids = new Set();
+        bakedModules.set(name, ids);
+      }
+      ids.add(id);
+      return { code: result.code, map: result.map };
+    },
+    configureServer(server) {
+      server.watcher.add(file);
+      const onChange = (changed: string) => {
+        if (path.resolve(changed) === file) refresh(server);
+      };
+      server.watcher.on("change", onChange);
+      server.watcher.on("add", onChange);
+    },
+  };
+}

package/src/singletonDepAliases.spec.ts

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import { createRequire } from "node:module";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
 import { createStorybookViteConfig } from "./storybook";
@@ -180,8 +181,59 @@ describe("CONTEXT_SINGLETONS membership, measured rather than recited (MPO-288)"
     expect(aliases["@tanstack/db"]).toBeTruthy();
     expect(subscribesExternalStore("@tanstack/store")).toBe(false);
   });
+
+  it("leaves react-query off while it subscribes the hook (MPO-290)", () => {
+    expect(subscribesExternalStore("@tanstack/react-query")).toBe(true);
+    expect(aliases["@tanstack/react-query"]).toBeUndefined();
+  });
+
+  it("resolves react-query to one directory from every package that declares it (MPO-290)", () => {
+    const declarers = workspacePackageDirs().filter((dir) =>
+      declares(dir, "@tanstack/react-query"),
+    );
+    expect(declarers.length).toBeGreaterThan(1);
+    const records = new Set(
+      declarers.map((dir) =>
+        fs.realpathSync(
+          path.dirname(
+            createRequire(path.join(dir, "package.json")).resolve(
+              "@tanstack/react-query/package.json",
+            ),
+          ),
+        ),
+      ),
+    );
+    expect([...records]).toHaveLength(1);
+  });
+
+  it("locks react-query to one snapshot, so the isolated layout has one copy too (MPO-290)", () => {
+    const lockfile = fs.readFileSync(path.join(workspaceRoot, "pnpm-lock.yaml"), "utf8");
+    const snapshots = lockfile.split(/^snapshots:$/m)[1] ?? "";
+    const keys = [...snapshots.matchAll(/^ {2}'(@tanstack\/react-query@[^']+)':$/gm)].map(
+      (match) => match[1],
+    );
+    expect(keys).toHaveLength(1);
+  });
 });
 
+function workspacePackageDirs(): string[] {
+  const dirs = [path.join(workspaceRoot, "features")];
+  for (const group of ["apps", "packages", "public"]) {
+    const groupDir = path.join(workspaceRoot, group);
+    for (const entry of fs.readdirSync(groupDir, { withFileTypes: true })) {
+      if (entry.isDirectory()) dirs.push(path.join(groupDir, entry.name));
+    }
+  }
+  return dirs.filter((dir) => fs.existsSync(path.join(dir, "package.json")));
+}
+
+function declares(dir: string, pkgName: string): boolean {
+  const manifest = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+  return ["dependencies", "devDependencies", "peerDependencies"].some(
+    (field) => manifest[field]?.[pkgName] !== undefined,
+  );
+}
+
 /**
  * Whether an installed package references `useSyncExternalStore` in anything
  * it ships. The cheap half of the membership rule, re-run against the tree so

package/src/singletonDepAliases.ts

@@ -74,9 +74,16 @@ import path from "node:path";
  * clause and not the whole rule: `@tanstack/db` references the hook nowhere
  * and is pinned anyway, for the collection registry it holds at module scope.
  *
- * `@tanstack/react-query` references the hook in 25 shipped files and is not
- * listed. That is recorded rather than settled — no split has been observed
- * there, and pinning it reaches further than this measurement does.
+ * MPO-290. `@tanstack/react-query` references the hook in 25 shipped files
+ * and is deliberately NOT listed. It passes the grep, but a pin only earns its
+ * place where a second record can exist, and here none does. Measured at
+ * 5.100.7 on 0af30157c: seven workspace packages declare it and the lockfile
+ * resolves all seven to one snapshot, `5.100.7(react@19.2.5)`. The hoisted
+ * install holds one physical copy. So does the isolated layout an unset
+ * NPM_AUTH_TOKEN produced while .npmrc held the linker keys, rebuilt by
+ * stripping them from pnpm-workspace.yaml: fourteen links, one realpath. The
+ * spec re-checks both halves, so a second version or peer set fails there
+ * before it splits an app.
  */
 const CONTEXT_SINGLETONS: readonly string[] = [
   "react-cookie",