@shipfox/client-shell 0.2.0 → 1.0.0

package/src/vite/evaluate-features.ts

@@ -1,13 +1,11 @@
-import {readFile, realpath} from 'node:fs/promises';
+import {randomUUID} from 'node:crypto';
+import {realpath} from 'node:fs/promises';
 import {createRequire} from 'node:module';
 import {resolve} from 'node:path';
-import {fileURLToPath, pathToFileURL} from 'node:url';
-import {createJiti} from 'jiti';
+import {register} from 'tsx/cjs/api';
 import type {ClientFeature} from '#contract.js';
 
 const require = createRequire(import.meta.url);
-const importPattern =
-  /(?:\b(?:import|export)\s+(?:[^'"]*?\s+from\s+)?|\bimport\s*\(\s*)['"]([^'"]+)['"]/g;
 const nodeModulesPathPattern = /[\\/]node_modules[\\/]/;
 
 export interface EvaluatedFeatures {
@@ -15,71 +13,91 @@ export interface EvaluatedFeatures {
   loadedFiles: readonly string[];
 }
 
-export function invalidateFeatures(loadedFiles: Iterable<string>): void {
-  for (const file of loadedFiles) delete require.cache[file];
-}
-
-function loadedModuleGraph(entry: string): string[] {
-  const files = new Set<string>();
+function loadedModuleGraph(namespaceQuery: string): {
+  cacheKeys: Set<string>;
+  loadedPaths: Set<string>;
+} {
+  const cacheKeys = new Set<string>();
+  const loadedPaths = new Set<string>();
+  const keysByModule = new Map<NodeJS.Module, string[]>();
 
-  function visit(file: string): void {
-    if (files.has(file)) return;
-    files.add(file);
-    for (const child of require.cache[file]?.children ?? []) visit(child.filename);
+  for (const [cacheKey, cachedModule] of Object.entries(require.cache)) {
+    if (!cachedModule) continue;
+    const keys = keysByModule.get(cachedModule) ?? [];
+    keys.push(cacheKey);
+    keysByModule.set(cachedModule, keys);
   }
 
-  visit(entry);
-  return [...files];
-}
+  const visited = new Set<NodeJS.Module>();
+  function visit(cachedModule: NodeJS.Module): void {
+    if (visited.has(cachedModule)) return;
+    visited.add(cachedModule);
 
-async function staticallyImportedModules(
-  entry: string,
-  jiti: ReturnType<typeof createJiti>,
-): Promise<string[]> {
-  const files = new Set<string>();
+    for (const cacheKey of keysByModule.get(cachedModule) ?? []) {
+      const path = cacheKey.endsWith(namespaceQuery)
+        ? cacheKey.slice(0, -namespaceQuery.length)
+        : cacheKey;
+      const isLocal = !nodeModulesPathPattern.test(path);
+      if (isLocal) loadedPaths.add(path);
+      if (isLocal || cacheKey.endsWith(namespaceQuery)) cacheKeys.add(cacheKey);
+    }
 
-  async function visit(file: string): Promise<void> {
-    const path = file.startsWith('file:') ? fileURLToPath(file) : file;
-    if (path.startsWith('node:') || nodeModulesPathPattern.test(path) || files.has(path)) return;
-    const resolvedPath = await realpath(path).catch(() => path);
-    files.add(resolvedPath);
-    const source = await readFile(resolvedPath, 'utf8').catch(() => undefined);
-    if (!source) return;
+    for (const child of cachedModule.children) visit(child);
+  }
 
-    for (const match of source.matchAll(importPattern)) {
-      const specifier = match[1];
-      if (!specifier) continue;
-      const dependency = jiti.esmResolve(specifier, {
-        parentURL: pathToFileURL(resolvedPath),
-        try: true,
-      });
-      if (dependency) await visit(dependency);
-    }
+  for (const [cacheKey, cachedModule] of Object.entries(require.cache)) {
+    if (cachedModule && cacheKey.endsWith(namespaceQuery)) visit(cachedModule);
   }
 
-  await visit(entry);
+  return {cacheKeys, loadedPaths};
+}
+
+async function localFiles(paths: Iterable<string>): Promise<string[]> {
+  const files = new Set<string>();
+  for (const path of paths) {
+    if (nodeModulesPathPattern.test(path)) continue;
+    files.add(await realpath(path).catch(() => path));
+  }
   return [...files];
 }
 
 export async function evaluateFeatures(featuresModule: string): Promise<EvaluatedFeatures> {
   const resolvedFeaturesModule = await realpath(resolve(featuresModule));
-  const jiti = createJiti(resolvedFeaturesModule, {interopDefault: false, tsconfigPaths: true});
+  const namespace = randomUUID();
+  const namespaceQuery = `?namespace=${namespace}`;
+  const loader = register({namespace});
+  const loadedPaths = new Set<string>([resolvedFeaturesModule]);
+  const cacheKeys = new Set<string>();
+  const initialCacheKeys = new Set(Object.keys(require.cache));
   let module: {default?: unknown; features?: unknown};
-  let loadedFiles: string[];
   try {
-    module = jiti(resolvedFeaturesModule) as {default?: unknown; features?: unknown};
-    loadedFiles = [
-      ...new Set([
-        ...loadedModuleGraph(resolvedFeaturesModule),
-        ...(await staticallyImportedModules(resolvedFeaturesModule, jiti)),
-      ]),
-    ];
+    module = loader.require(resolvedFeaturesModule, import.meta.url) as {
+      default?: unknown;
+      features?: unknown;
+    };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     throw new Error(
       `Failed to evaluate features module "${resolvedFeaturesModule}". Features modules must be Node-safe: ${message}`,
       {cause: error},
     );
+  } finally {
+    const graph = loadedModuleGraph(namespaceQuery);
+    for (const path of graph.loadedPaths) loadedPaths.add(path);
+    for (const cacheKey of graph.cacheKeys) cacheKeys.add(cacheKey);
+    for (const cacheKey of Object.keys(require.cache)) {
+      if (initialCacheKeys.has(cacheKey)) continue;
+      const path = cacheKey.endsWith(namespaceQuery)
+        ? cacheKey.slice(0, -namespaceQuery.length)
+        : cacheKey;
+      const isLocal = !nodeModulesPathPattern.test(path);
+      if (isLocal) loadedPaths.add(path);
+      if (isLocal || cacheKey.endsWith(namespaceQuery)) cacheKeys.add(cacheKey);
+    }
+    loader.unregister();
+    for (const cacheKey of cacheKeys) delete require.cache[cacheKey];
+    for (const cacheKey of Object.keys(require.cache))
+      if (cacheKey.endsWith(namespaceQuery)) delete require.cache[cacheKey];
   }
 
   const features = module.features ?? module.default;
@@ -89,5 +107,8 @@ export async function evaluateFeatures(featuresModule: string): Promise<Evaluate
     );
   }
 
-  return {features: features as readonly ClientFeature[], loadedFiles};
+  return {
+    features: features as readonly ClientFeature[],
+    loadedFiles: await localFiles(loadedPaths),
+  };
 }

package/src/vite/generate.ts

@@ -34,14 +34,14 @@ export function generateAppModule({
     routePath: routePathForAnchor(route.parent, route.path),
   }));
   const imports = routes
-    .map((route, index) => `import route${index}Impl from ${literal(route.impl)};`)
+    .map((route, index) => `import * as route${index}Module from ${literal(route.impl)};`)
     .join('\n');
   const routeDeclarations = generatedRoutes
     .map(
       (route, index) => `const route${index} = createRoute({
   getParentRoute: () => ${route.parent === 'root' ? 'skeleton.rootRoute' : `skeleton.${route.parent}`},
   path: ${literal(route.routePath)},
-  ...routeOptions(route${index}Impl, ${literal(route.impl)}, ${literal(route.path)}),
+  ...routeOptions(route${index}Module.default, ${literal(route.impl)}, ${literal(route.path)}),
 });`,
     )
     .join('\n\n');

package/src/vite/plugin.test.ts

@@ -2,7 +2,7 @@ import {mkdtemp, readFile, realpath, rm, writeFile} from 'node:fs/promises';
 import {tmpdir} from 'node:os';
 import {join} from 'node:path';
 import {fileURLToPath} from 'node:url';
-import type {Plugin, ResolvedConfig} from 'vite';
+import {type Plugin, type ResolvedConfig, build as viteBuild} from 'vite';
 import {shipfoxClientComposition} from './plugin.js';
 
 const fixtureFeatures = fileURLToPath(new URL('../../test/fixtures/features.ts', import.meta.url));
@@ -35,13 +35,12 @@ function resolveRouteImplementation(source: string): string | undefined {
   const files: Record<string, string> = {
     '#test/default-route-impl.js': join(testDirectory, 'default-route-impl.tsx'),
     '#test/named-route-impl.js': join(testDirectory, 'named-route-impl.tsx'),
-    '#test/not-route-impl.js': join(testDirectory, 'not-route-impl.ts'),
     '#test/search-route-impl.js': join(testDirectory, 'search-route-impl.tsx'),
   };
   return files[source];
 }
 
-function pluginContext() {
+function pluginContext(resolveImplementation = resolveRouteImplementation) {
   const watchedFiles: string[] = [];
   return {
     watchedFiles,
@@ -49,13 +48,13 @@ function pluginContext() {
       watchedFiles.push(file);
     },
     resolve(source: string) {
-      const id = resolveRouteImplementation(source);
+      const id = resolveImplementation(source);
       return Promise.resolve(id ? {id} : null);
     },
     environment: {
       pluginContainer: {
         resolveId(source: string) {
-          const id = resolveRouteImplementation(source);
+          const id = resolveImplementation(source);
           return Promise.resolve(id ? {id} : null);
         },
       },
@@ -95,7 +94,7 @@ describe('shipfoxClientComposition', () => {
     await build(plugin, context);
 
     await expect(readFile(out, 'utf8')).resolves.toContain(
-      'import route0Impl from "#test/search-route-impl.js";',
+      'import * as route0Module from "#test/search-route-impl.js";',
     );
     expect(context.watchedFiles).toContain(fixtureFeatures);
   });
@@ -118,18 +117,69 @@ describe('shipfoxClientComposition', () => {
     );
   });
 
-  test('rejects route implementations without a default export', async () => {
+  test('fails the Vite build when a route implementation cannot resolve', async () => {
     const features = join(directory, 'features.ts');
     await writeFile(
       features,
-      `export const features = [{id: 'acme.projects', routes: [{path: '/projects', parent: 'root', impl: '#test/not-route-impl.js'}]}];`,
+      `export const features = [{id: 'acme.projects', routes: [{path: '/projects', parent: 'root', impl: '#test/missing-route-impl.js'}]}];`,
     );
     const plugin = shipfoxClientComposition({features, out: join(directory, 'shipfox-app.gen.ts')});
     const context = pluginContext();
     configure(plugin);
 
     await expect(build(plugin, context)).rejects.toThrow(
-      'Route implementation "#test/not-route-impl.js" for "/projects" must export default defineRoute(...).',
+      'Could not resolve route implementation "#test/missing-route-impl.js" for "/projects".',
+    );
+  });
+
+  test('generates when Vite resolves a route implementation with a version query', async () => {
+    const out = join(directory, 'shipfox-app.gen.ts');
+    const plugin = shipfoxClientComposition({features: fixtureFeatures, out});
+    const context = pluginContext((source) => {
+      if (source === '#test/search-route-impl.js') {
+        return `${join(testDirectory, 'search-route-impl.tsx')}?v=abc123`;
+      }
+      return resolveRouteImplementation(source);
+    });
+    configure(plugin);
+
+    await build(plugin, context);
+
+    await expect(readFile(out, 'utf8')).resolves.toContain(
+      'import * as route0Module from "#test/search-route-impl.js";',
+    );
+  });
+
+  test('bundles a named-only route module so the runtime export guard can report it', async () => {
+    const features = join(directory, 'features.ts');
+    const implementation = join(directory, 'not-route-impl.ts');
+    const output = join(directory, 'shipfox-app.gen.ts');
+    const entry = join(directory, 'main.ts');
+    await Promise.all([
+      writeFile(
+        features,
+        `export const features = [{id: 'acme.projects', routes: [{path: '/projects', parent: 'root', impl: './not-route-impl.ts'}]}];`,
+      ),
+      writeFile(implementation, 'export const Route = () => null;'),
+      writeFile(entry, "import './shipfox-app.gen.ts';"),
+    ]);
+
+    await expect(
+      viteBuild({
+        root: process.cwd(),
+        logLevel: 'silent',
+        plugins: [shipfoxClientComposition({features, out: output})],
+        build: {
+          write: false,
+          rolldownOptions: {
+            input: entry,
+            external: ['@shipfox/client-shell/runtime', '@tanstack/react-router'],
+          },
+        },
+      }),
+    ).resolves.toBeDefined();
+    await expect(readFile(output, 'utf8')).resolves.toContain(
+      'routeOptions(route0Module.default, "./not-route-impl.ts", "/projects")',
     );
   });
 

package/src/vite/plugin.ts

@@ -6,11 +6,9 @@ import {mergeConfigShapes} from '#compose/merge-config.js';
 import {validateProviderIds} from '#compose/validate-providers.js';
 import {validateNavigation, validateSettingsSections} from '#compose/validate-registries.js';
 import {navigationEntries, settingsEntries} from '#runtime/registries.js';
-import {evaluateFeatures, invalidateFeatures} from './evaluate-features.js';
+import {evaluateFeatures} from './evaluate-features.js';
 import {generateAppModule} from './generate.js';
 
-const defaultExportPattern = /\bexport\s+default\b|\bexport\s*\{[\s\S]*?\bas\s+default\b[\s\S]*?\}/;
-
 export interface ShipfoxClientCompositionOptions {
   features: string;
   out?: string;
@@ -18,10 +16,6 @@ export interface ShipfoxClientCompositionOptions {
 
 type RouteResolver = (source: string, importer?: string) => Promise<{id: string} | null>;
 
-function hasDefaultExport(source: string): boolean {
-  return defaultExportPattern.test(source);
-}
-
 export function shipfoxClientComposition({
   features,
   out = './src/shipfox-app.gen.ts',
@@ -32,7 +26,7 @@ export function shipfoxClientComposition({
   const outputPath = () => resolve(config?.root ?? process.cwd(), out);
   const featuresPath = () => resolve(config?.root ?? process.cwd(), features);
 
-  async function assertDefaultRouteExports(
+  async function assertRoutesResolve(
     resolveRoute: RouteResolver,
     routes: ReturnType<typeof composeRoutes>,
   ): Promise<void> {
@@ -43,12 +37,6 @@ export function shipfoxClientComposition({
           `Could not resolve route implementation "${route.impl}" for "${route.path}".`,
         );
       }
-      const source = await readFile(resolvedRoute.id, 'utf8');
-      if (!hasDefaultExport(source)) {
-        throw new Error(
-          `Route implementation "${route.impl}" for "${route.path}" must export default defineRoute(...).`,
-        );
-      }
     }
   }
 
@@ -59,7 +47,6 @@ export function shipfoxClientComposition({
     addWatchFile(file: string): void;
     resolveRoute: RouteResolver;
   }): Promise<void> {
-    invalidateFeatures(watchedFiles);
     const evaluated = await evaluateFeatures(featuresPath());
     const routes = composeRoutes(evaluated.features);
     validateProviderIds(evaluated.features);
@@ -72,7 +59,7 @@ export function shipfoxClientComposition({
       routes.map((route) => route.path),
     );
     mergeConfigShapes(evaluated.features);
-    await assertDefaultRouteExports(resolveRoute, routes);
+    await assertRoutesResolve(resolveRoute, routes);
 
     watchedFiles = new Set(evaluated.loadedFiles);
     for (const file of watchedFiles) addWatchFile(file);

package/test/external/FINDINGS.md

@@ -1,53 +1,41 @@
 # External composition findings
 
-Both the linked iteration mode and packed-tarball exit gate passed on 2026-07-16. The verifier
-computed and installed a 12-package `@shipfox/*` runtime closure.
-
-## Declaration portability
-
-The packed consumer's `tsc --noEmit` accepted a typed `Link` and `useSearch` for the added
-`/workspaces/$wid/insights` route. The generated router also resolved the toy package's emitted
-default `defineRoute(...)` declarations and the shell's anchor return types from `dist`.
-
-The packed verifier also checks that every installed `#*` import map defaults to `./dist/*` and
-that representative shell and toy-feature public entrypoints resolve beneath `dist`. This keeps the
-proof valid even while the tarballs still include source files.
-
-The proof exposed two package-boundary gaps before it passed:
-
-- Compiled client packages still mapped internal `#*` imports directly to `src`. Their package
-  manifests now use `workspace-source` and `development` for source, and `default` for `dist`.
-- The inferred anchor declarations name `@tanstack/router-core`. The shell now declares that direct
-  dependency so isolated pnpm consumers can resolve it.
-
-The fixture did not need `@storybook/react` at runtime or during its consumer type-check. The
-`ShellProviders` declaration's type-only Storybook import is erased at runtime; the fixture uses the
-same `skipLibCheck` setting as the existing external-consumer verifier.
-
-## Development-mode coverage
-
-The gate intentionally proves production builds and default package resolution; it does not start a
-Vite development server. The `development` condition still resolves to the TypeScript source that
-the packages currently ship. Plugin watch and regeneration behavior remains covered by ENG-961's
-focused tests. If published packages stop including source, external development-mode support needs
-a separate product decision and proof rather than making this release gate longer.
-
-## Generated-file developer experience
-
-The generated file keeps both forms of route implementation specifier readable:
-
-- App-local implementations use a path relative to `src/shipfox-app.gen.ts`, such as
-  `./features/override-impl`.
-- Packaged implementations use an exported package subpath, such as
-  `@shipfox/client-shell-fixture-feature/routes/insights`.
-
-The app's Node-evaluated feature manifest imports local TypeScript modules without a `.js` suffix so
-jiti resolves the source file. Route implementation modules are never evaluated by jiti.
+The graduated fixture uses the production `@shipfox/client-features` default composition and the
+complete recursive client runtime closure from `publication-closure.json`. The external feature is
+application-local, so route implementations and generated types cross the same package boundary as
+a downstream distribution.
+
+## Contract proof
+
+The fixture proves that:
+
+- every default feature contributes its production routes to the generated application module;
+- an application-local settings route is added and the default login route is explicitly replaced;
+- two application-local providers receive the shell query client and Jotai store, then nest in
+  declaration order;
+- application navigation and settings data render through the shell-owned registries;
+- the external config fragment is required, merged, and readable by both providers and the route;
+- the generated router types an application-local `Link` and `useParams` call; and
+- the unapproved login collision fails with the exact normative diagnostic.
+
+## Distribution isolation
+
+Packed mode builds declarations and runtime files before creating tarballs, then productionizes a
+temporary copy of each package manifest like `release:publish` so source conditions cannot leak into
+the consumer artifact or mutate the worktree. The fixture declares only the documented client
+composition roots, plus `@shipfox/client-config` for its own config proof, while `file:` overrides
+keep every first-party runtime dependency in the full closure on its local tarball. It rejects
+registry-resolved Shipfox packages and `workspace:` ranges across every installed closure package,
+checks that generated package imports are direct fixture dependencies, and confirms full-closure
+runtime imports resolve through `dist` under default and `development` conditions while TypeScript
+checks every packed declaration graph. Linked mode keeps the
+minimal-consumer, generated-route, behavior, collision, and type checks for faster local iteration;
+its workspace packages intentionally resolve `development` to source.
 
 ## Collision diagnostic
 
-The rejected build returned this diagnostic and a non-zero status:
+The rejected build must return this diagnostic and a non-zero status:
 
 ```text
-Route "/workspaces/$wid/insights" is contributed by both features "fixture.toy-feature" and "fixture.unapproved-collision". Set override: true to replace it explicitly.
+Route "/auth/login" is contributed by both features "shipfox.auth" and "fixture.unapproved-collision". Set override: true to replace it explicitly.
 ```

package/test/external/README.md

@@ -1,39 +1,37 @@
 # External client runtime fixture
 
 This fixture packs the published client runtime closure into a Vite application outside the pnpm
-workspace. It is a manual structural gate and does not add a CI job.
+workspace. The application starts from `defaultFeatures()` and adds one external feature that
+replaces the login route, adds a settings route, appends providers, contributes navigation and
+settings entries, and merges a config fragment.
 
-## Prerequisites
+## Run the required packed gate
 
-Build runtime files, declarations, and the closure helper before running either mode:
+The package script builds runtime files and declarations from a clean checkout before packing the
+full client closure:
 
 ```sh
-turbo build type:emit \
-  --filter='./libs/client/**' \
-  --filter=@shipfox/application-release
+pnpm --filter=@shipfox/client-shell test:external
 ```
 
-## Run the fast linked mode
+The gate installs only the nine documented client composition roots, plus
+`@shipfox/client-config` used by the fixture's own config proof, as direct dependencies. It uses
+release-shaped local tarballs and overrides for the full `@shipfox/*` runtime closure. It verifies
+that generated package imports are declared direct dependencies, checks default and `development`
+condition resolution through `dist`, type-checks every packed declaration graph, generates the
+composed TanStack router, builds and type-checks the consumer, runs the behavioral fixture, and
+asserts the exact rejected-collision diagnostic. CI runs this command during static verification.
 
-```sh
-node libs/client/shell/test/external/verify.mjs --link
-```
-
-This copies the Vite template to a temporary directory and links the workspace-built closure. It
-runs a Vite build and resolves every non-pattern declaration entry point from the consumer.
-
-## Run the packed exit gate
+## Run the linked iteration mode
 
 ```sh
-node libs/client/shell/test/external/verify.mjs
+pnpm --filter=@shipfox/client-shell test:external -- --link
 ```
 
-This computes the runtime workspace closure from the client roots in
-`publication-closure.json`, packs every package, and installs only those tarballs for
-`@shipfox/*` dependencies. It repeats the linked checks against default `dist` exports and
-verifies no candidate package came from the workspace or registry.
+This copies the Vite template to a temporary directory and links the workspace-built closure. It
+runs the same minimal-consumer, generated-route, behavior, collision, and type assertions without
+packing tarballs. The packed-only `development` check is omitted because linked workspace packages
+intentionally resolve that condition to source.
 
 Both modes remove their temporary directories after completion. The behavioral composition fixture
-and required CI gate are part of ENG-995; neither mode needs browser E2E infrastructure or adds
-work to the normal CI test graph. Its source files and Vitest wiring remain in the fixture template
-for that follow-up.
+uses Vitest with JSDOM and does not need browser E2E infrastructure.

package/test/external/fixture/package.json

@@ -18,8 +18,7 @@
     "zod": "4.4.3"
   },
   "devDependencies": {
-    "@testing-library/jest-dom": "6.9.1",
-    "@testing-library/react": "16.3.2",
+    "@storybook/react": "10.4.6",
     "@types/node": "24.13.2",
     "@types/react": "19.2.17",
     "@types/react-dom": "19.2.3",