@fragments-sdk/cli 0.10.1 → 0.12.1

package/src/viewer/__tests__/viewer-integration.test.ts

@@ -7,63 +7,101 @@ import { tmpdir } from "node:os";
 import { discoverInstalledFragments } from "../../core/discovery.js";
 
 /**
- * Integration tests for the consolidated viewer.
+ * Integration tests for the viewer architecture.
  *
- * After packages were merged into @fragments-sdk/cli, the viewer's
- * path resolution changed. These tests verify that:
- * - Viewer assets (HTML, TSX entry points) are found at the correct paths
- * - The @fragments-sdk/cli/core alias resolves to the consolidated core source
+ * After the viewer extraction (Delivery A), viewer UI code lives in
+ * packages/viewer/ while CLI keeps the Vite server and plugin.
+ * These tests verify:
+ * - Viewer assets (HTML, TSX entry points) are found in packages/viewer/
+ * - The CLI server/plugin reference the viewer package correctly
+ * - The @fragments-sdk/cli/core alias resolves to consolidated core source
  * - The virtual module generates valid import statements
- * - The Vite config references correct file system locations
  */
 
-// Simulate the same path resolution used in server.ts and vite-plugin.ts
-// At runtime, __dirname is dist/. In tests (vitest), it's the source dir.
 const testDir = dirname(fileURLToPath(import.meta.url));
 const viewerDir = resolve(testDir, "..");
 const cliPackageRoot = resolve(viewerDir, "../..");
+const packagesRoot = resolve(cliPackageRoot, "..");
+const viewerPackageRoot = resolve(packagesRoot, "viewer");
+const viewerSrc = resolve(viewerPackageRoot, "src");
 
-describe("viewer path resolution", () => {
-  it("viewerRoot resolves to a directory containing index.html", () => {
-    // server.ts: viewerRoot = resolve(cliPackageRoot, "src/viewer")
-    const viewerRoot = resolve(cliPackageRoot, "src/viewer");
-    expect(existsSync(resolve(viewerRoot, "index.html"))).toBe(true);
+describe("viewer package path resolution", () => {
+  it("viewer package root exists", () => {
+    expect(existsSync(viewerPackageRoot)).toBe(true);
   });
 
-  it("viewerRoot contains entry.tsx", () => {
-    const viewerRoot = resolve(cliPackageRoot, "src/viewer");
-    expect(existsSync(resolve(viewerRoot, "entry.tsx"))).toBe(true);
+  it("viewer package contains index.html at root", () => {
+    expect(existsSync(resolve(viewerPackageRoot, "index.html"))).toBe(true);
   });
 
-  it("viewerRoot contains preview-frame.html", () => {
-    const viewerRoot = resolve(cliPackageRoot, "src/viewer");
-    expect(existsSync(resolve(viewerRoot, "preview-frame.html"))).toBe(true);
+  it("viewer package contains entry.tsx", () => {
+    expect(existsSync(resolve(viewerSrc, "entry.tsx"))).toBe(true);
   });
 
-  it("viewerRoot contains preview-frame-entry.tsx", () => {
-    const viewerRoot = resolve(cliPackageRoot, "src/viewer");
-    expect(existsSync(resolve(viewerRoot, "preview-frame-entry.tsx"))).toBe(true);
+  it("viewer package contains preview-frame.html in src/", () => {
+    expect(existsSync(resolve(viewerSrc, "preview-frame.html"))).toBe(true);
   });
 
-  it("viewerRoot contains render-template.html", () => {
-    const viewerRoot = resolve(cliPackageRoot, "src/viewer");
-    expect(existsSync(resolve(viewerRoot, "render-template.html"))).toBe(true);
+  it("viewer package contains preview-frame-entry.tsx", () => {
+    expect(existsSync(resolve(viewerSrc, "preview-frame-entry.tsx"))).toBe(
+      true
+    );
+  });
+
+  it("viewer package contains render-template.html in src/", () => {
+    expect(existsSync(resolve(viewerSrc, "render-template.html"))).toBe(true);
   });
 
-  it("viewerRoot does not contain tailwind.config.js (removed in Tailwind→Fragments migration)", () => {
-    const viewerRoot = resolve(cliPackageRoot, "src/viewer");
-    expect(existsSync(resolve(viewerRoot, "tailwind.config.js"))).toBe(false);
+  it("viewer package contains shared/index.ts barrel", () => {
+    expect(existsSync(resolve(viewerSrc, "shared/index.ts"))).toBe(true);
   });
 
-  it("viewerRoot contains styles/globals.css", () => {
-    const viewerRoot = resolve(cliPackageRoot, "src/viewer");
-    expect(existsSync(resolve(viewerRoot, "styles/globals.css"))).toBe(true);
+  it("viewer package contains app/index.ts barrel", () => {
+    expect(existsSync(resolve(viewerSrc, "app/index.ts"))).toBe(true);
+  });
+});
+
+describe("CLI viewer server references viewer package", () => {
+  it("server.ts has resolveViewerRoot function for monorepo and npm resolution", async () => {
+    const serverPath = resolve(viewerDir, "server.ts");
+    const content = await readFile(serverPath, "utf-8");
+
+    expect(content).toContain("function resolveViewerRoot(nodeModulesDir: string)");
+    // Checks monorepo path first
+    expect(content).toContain('resolve(packagesRoot, "viewer")');
+    // Falls back to npm-installed path
+    expect(content).toContain("@fragments-sdk/viewer");
+  });
+
+  it("server.ts sets up viewer subpath aliases", async () => {
+    const serverPath = resolve(viewerDir, "server.ts");
+    const content = await readFile(serverPath, "utf-8");
+
+    expect(content).toContain("@fragments-sdk/viewer/shared");
+    expect(content).toContain("@fragments-sdk/viewer/app");
+  });
+
+  it("server.ts does not reference old resolveFragmentsPackage for core", async () => {
+    const serverPath = resolve(viewerDir, "server.ts");
+    const content = await readFile(serverPath, "utf-8");
+
+    expect(content).not.toContain('resolveFragmentsPackage("core"');
+  });
+
+  it("no source files import from @fragments-sdk/cli/core as a runtime dependency", async () => {
+    const serverPath = resolve(viewerDir, "server.ts");
+    const content = await readFile(serverPath, "utf-8");
+
+    const lines = content.split("\n");
+    const importLines = lines.filter(
+      (l) => l.startsWith("import") && l.includes("@fragments-sdk/cli/core")
+    );
+    expect(importLines).toHaveLength(0);
   });
 });
 
 describe("@fragments-sdk/cli/core alias resolution", () => {
   it("core/index.ts exists at the expected path", () => {
-    // server.ts: "@fragments-sdk/cli/core": resolve(cliPackageRoot, "src/core/index.ts")
     const corePath = resolve(cliPackageRoot, "src/core/index.ts");
     expect(existsSync(corePath)).toBe(true);
   });
@@ -71,19 +109,15 @@ describe("@fragments-sdk/cli/core alias resolution", () => {
   it("core/index.ts re-exports from @fragments-sdk/core", async () => {
     const corePath = resolve(cliPackageRoot, "src/core/index.ts");
     const content = await readFile(corePath, "utf-8");
-    // After core extraction, cli/core is a thin re-export shim
     expect(content).toContain("@fragments-sdk/core");
   });
 });
 
 describe("virtual module @fragments-sdk/cli/core import", () => {
   it("vite-plugin generates import from @fragments-sdk/cli/core (resolved via alias)", async () => {
-    // The virtual module template in vite-plugin.ts must import from @fragments-sdk/cli/core
-    // which is resolved by the Vite alias to the consolidated core source
     const pluginPath = resolve(viewerDir, "vite-plugin.ts");
     const content = await readFile(pluginPath, "utf-8");
 
-    // The generated virtual module string should reference @fragments-sdk/cli/core
     expect(content).toContain(
       'import { storyModuleToFragment, setPreviewConfig, checkStoryExclusion, isForceIncluded, isConfigExcluded } from "@fragments-sdk/cli/core"'
     );
@@ -93,43 +127,47 @@ describe("virtual module @fragments-sdk/cli/core import", () => {
     const serverPath = resolve(viewerDir, "server.ts");
     const content = await readFile(serverPath, "utf-8");
 
-    // The alias must resolve @fragments-sdk/cli/core to the CLI's core source
-    expect(content).toContain('"@fragments-sdk/cli/core": resolve(cliPackageRoot, "src/core/index.ts")');
+    expect(content).toContain(
+      '"@fragments-sdk/cli/core": resolve(cliPackageRoot, "src/core/index.ts")'
+    );
   });
 
   it("vite-plugin merges authored variant code from metadata fragments", async () => {
     const pluginPath = resolve(viewerDir, "vite-plugin.ts");
     const content = await readFile(pluginPath, "utf-8");
 
-    expect(content).toContain("if (metaVariant.code && !fragmentVariant.code)");
+    expect(content).toContain(
+      "if (metaVariant.code && !fragmentVariant.code)"
+    );
     expect(content).toContain("fragmentVariant.code = metaVariant.code;");
   });
 });
 
 describe("viewer HTML templates", () => {
   it("index.html contains entry.tsx script reference", async () => {
-    const htmlPath = resolve(viewerDir, "index.html");
+    const htmlPath = resolve(viewerPackageRoot, "index.html");
     const content = await readFile(htmlPath, "utf-8");
 
-    // The HTML references /src/entry.tsx which gets rewritten to an absolute path
     expect(content).toContain('src="/src/entry.tsx"');
   });
 
   it("preview-frame.html contains preview-frame-entry.tsx reference", async () => {
-    const htmlPath = resolve(viewerDir, "preview-frame.html");
+    const htmlPath = resolve(viewerSrc, "preview-frame.html");
     const content = await readFile(htmlPath, "utf-8");
 
     expect(content).toContain('src="/src/preview-frame-entry.tsx"');
   });
 
-  it("vite-plugin rewrites entry paths using viewerAssetsRoot", async () => {
+  it("vite-plugin resolves viewerAssetsRoot with npm fallback", async () => {
     const pluginPath = resolve(viewerDir, "vite-plugin.ts");
     const content = await readFile(pluginPath, "utf-8");
 
-    // The plugin must use viewerAssetsRoot (not __dirname or resolve(__dirname, ".."))
-    // to find viewer HTML and entry files
-    expect(content).toContain("const viewerAssetsRoot = resolve(__dirname,");
-    expect(content).toContain('const viewerRoot = viewerAssetsRoot');
+    // Tries monorepo path first
+    expect(content).toContain("monorepoViewerSrc");
+    // Falls back to npm-installed
+    expect(content).toContain("npmViewerSrc");
+    // Resolves to a final viewerAssetsRoot
+    expect(content).toContain("const viewerAssetsRoot =");
   });
 });
 
@@ -139,7 +177,6 @@ describe("discoverInstalledFragments", () => {
   beforeAll(async () => {
     tmpDir = await mkdtemp(resolve(tmpdir(), "fragments-test-"));
 
-    // Create a fake project with a dependency that has fragments
     await writeFile(
       resolve(tmpDir, "package.json"),
       JSON.stringify({
@@ -147,7 +184,6 @@ describe("discoverInstalledFragments", () => {
       })
     );
 
-    // @acme/ui declares fragments
     const acmeDir = resolve(tmpDir, "node_modules/@acme/ui");
     await mkdir(resolve(acmeDir, "src/components"), { recursive: true });
     await writeFile(
@@ -163,7 +199,6 @@ describe("discoverInstalledFragments", () => {
       "export default {};"
     );
 
-    // some-lib does NOT declare fragments
     const someLibDir = resolve(tmpDir, "node_modules/some-lib");
     await mkdir(resolve(someLibDir, "src"), { recursive: true });
     await writeFile(
@@ -209,27 +244,3 @@ describe("discoverInstalledFragments", () => {
     await rm(emptyDir, { recursive: true, force: true });
   });
 });
-
-describe("no stale @fragments/* package references", () => {
-  it("server.ts does not reference old resolveFragmentsPackage for core", async () => {
-    const serverPath = resolve(viewerDir, "server.ts");
-    const content = await readFile(serverPath, "utf-8");
-
-    // Should NOT try to resolve @fragments-sdk/cli/core from node_modules
-    expect(content).not.toContain('resolveFragmentsPackage("core"');
-  });
-
-  it("no source files import from @fragments-sdk/cli/core as a runtime dependency", async () => {
-    // All source-level imports should use relative paths (../core/).
-    // Only the generated virtual module string uses @fragments-sdk/cli/core (resolved via alias).
-    const serverPath = resolve(viewerDir, "server.ts");
-    const content = await readFile(serverPath, "utf-8");
-
-    // server.ts should import from relative paths, not @fragments-sdk/cli/core
-    const lines = content.split("\n");
-    const importLines = lines.filter(
-      (l) => l.startsWith("import") && l.includes("@fragments-sdk/cli/core")
-    );
-    expect(importLines).toHaveLength(0);
-  });
-});

package/src/viewer/server.ts

@@ -26,16 +26,38 @@ import { loadConfig, discoverFragmentFiles, discoverInstalledFragments } from ".
 import { fragmentsPlugin } from "./vite-plugin.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-// At runtime, __dirname is dist/. Viewer assets live in src/viewer/.
+// At runtime, __dirname is dist/.
 const cliPackageRoot = resolve(__dirname, "..");
-const viewerRoot = resolve(cliPackageRoot, "src/viewer");
 const packagesRoot = resolve(cliPackageRoot, "..");
 const localUiLibRoot = resolve(packagesRoot, "../libs/ui/src");
-const localSharedLibRoot = resolve(packagesRoot, "../libs/shared/src");
-const vendoredSharedLibRoot = resolve(viewerRoot, "vendor/shared/src");
 const localWebMCPRoot = resolve(packagesRoot, "webmcp/src");
 const localContextRoot = resolve(packagesRoot, "context/src");
 
+/**
+ * Resolve the viewer package root.
+ * Monorepo: sibling under packages/.
+ * npm-installed: node_modules/@fragments-sdk/viewer.
+ */
+function resolveViewerRoot(nodeModulesDir: string): string {
+  // Prefer monorepo sibling (dev mode)
+  const monorepoPath = resolve(packagesRoot, "viewer");
+  if (existsSync(join(monorepoPath, "src/shared/index.ts"))) {
+    return monorepoPath;
+  }
+  // Installed via npm — resolve from node_modules
+  const npmPath = join(nodeModulesDir, "@fragments-sdk/viewer");
+  if (existsSync(npmPath)) {
+    return npmPath;
+  }
+  // CLI's own node_modules as last resort
+  const cliNpmPath = join(cliPackageRoot, "node_modules/@fragments-sdk/viewer");
+  if (existsSync(cliNpmPath)) {
+    return cliNpmPath;
+  }
+  // Fallback to monorepo path (will error later with a clear message)
+  return monorepoPath;
+}
+
 /**
  * Resolve the @fragments/ui alias to the correct path.
  * In external projects: use the installed @fragments-sdk/ui package.
@@ -99,21 +121,11 @@ function resolveContextLib(nodeModulesDir: string): string {
 }
 
 /**
- * Resolve the @fragments-sdk/shared alias to either monorepo source
- * or vendored viewer fallback for npm installs.
+ * Resolve the @fragments-sdk/viewer src directory.
  */
-function resolveSharedLib(): string {
-  const localIndex = join(localSharedLibRoot, "index.ts");
-  if (existsSync(localIndex)) {
-    return localSharedLibRoot;
-  }
-
-  const vendoredIndex = join(vendoredSharedLibRoot, "index.ts");
-  if (existsSync(vendoredIndex)) {
-    return vendoredSharedLibRoot;
-  }
-
-  return localSharedLibRoot;
+function resolveViewerLib(nodeModulesDir: string): string {
+  const viewerRoot = resolveViewerRoot(nodeModulesDir);
+  return resolve(viewerRoot, "src");
 }
 
 /**
@@ -383,7 +395,8 @@ export async function createDevServer(
   // Find node_modules (handles monorepo setups)
   const nodeModulesPath = findNodeModules(projectRoot);
   const uiLibRoot = resolveUiLib(nodeModulesPath);
-  const sharedLibRoot = resolveSharedLib();
+  const viewerRoot = resolveViewerRoot(nodeModulesPath);
+  const viewerLibRoot = resolveViewerLib(nodeModulesPath);
   const webmcpLibRoot = resolveWebMCPLib(nodeModulesPath);
   const contextLibRoot = resolveContextLib(nodeModulesPath);
   // Detect whether resolved libs point to source (.ts) or dist (.js)
@@ -430,7 +443,7 @@ export async function createDevServer(
       fs: {
         // Allow serving files from viewer package, project, shared libs, node_modules root, and .storybook
         allow: [
-          viewerRoot, uiLibRoot, sharedLibRoot, webmcpLibRoot, contextLibRoot,
+          viewerRoot, uiLibRoot, viewerLibRoot, webmcpLibRoot, contextLibRoot,
           projectRoot, configDir, dirname(nodeModulesPath),
           ...(hasStorybookDir ? [storybookDir] : []),
           ...installedPkgRoots,
@@ -489,8 +502,10 @@ export async function createDevServer(
         ...storybookAliases,
         // Resolve @fragments-sdk/ui to local source or installed package
         "@fragments-sdk/ui": uiLibRoot,
-        // Resolve @fragments-sdk/shared to monorepo source or vendored fallback
-        "@fragments-sdk/shared": sharedLibRoot,
+        // Resolve @fragments-sdk/viewer subpaths to viewer package source
+        "@fragments-sdk/viewer/shared": join(viewerLibRoot, "shared/index.ts"),
+        "@fragments-sdk/viewer/app": join(viewerLibRoot, "app/index.ts"),
+        "@fragments-sdk/viewer/docs-data": join(viewerLibRoot, "shared/docs-data/index.ts"),
         // Resolve @fragments-sdk/webmcp subpaths to monorepo source or installed package
         "@fragments-sdk/webmcp/react": isWebMCPSource
           ? join(webmcpLibRoot, "react/index.ts")

package/src/viewer/vite-plugin.ts

@@ -16,6 +16,7 @@
 import type { Plugin, ViteDevServer, ResolvedConfig } from "vite";
 import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { transform } from "esbuild";
 import type { FragmentsConfig, CompiledFragment } from "../core/index.js";
@@ -101,8 +102,22 @@ interface CompareResponse {
 }
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-// At runtime, __dirname is dist/. Viewer assets live in src/viewer/.
-const viewerAssetsRoot = resolve(__dirname, "..", "src/viewer");
+// At runtime, __dirname is dist/. Try monorepo sibling first, then npm-installed.
+const monorepoViewerSrc = resolve(__dirname, "..", "..", "viewer", "src");
+const npmViewerSrc = (() => {
+  // Check CLI's own node_modules
+  const cliNm = resolve(__dirname, "..", "node_modules", "@fragments-sdk", "viewer", "src");
+  if (existsSync(cliNm)) return cliNm;
+  // Walk up to find a node_modules with the viewer
+  let dir = resolve(__dirname, "..");
+  for (let i = 0; i < 5; i++) {
+    const candidate = resolve(dir, "node_modules", "@fragments-sdk", "viewer", "src");
+    if (existsSync(candidate)) return candidate;
+    dir = resolve(dir, "..");
+  }
+  return null;
+})();
+const viewerAssetsRoot = existsSync(monorepoViewerSrc) ? monorepoViewerSrc : (npmViewerSrc ?? monorepoViewerSrc);
 
 // Store pending render requests (for internal render page to pick up)
 const pendingRenders = new Map<
@@ -2138,12 +2153,13 @@ async function loadFragmentsForContext(
  * Serve the viewer HTML page.
  */
 async function serveViewerHTML(res: any, server: ViteDevServer): Promise<void> {
-  const viewerRoot = viewerAssetsRoot;
-  const entryPath = resolve(viewerRoot, "entry.tsx");
+  const viewerSrc = viewerAssetsRoot;
+  const viewerPkgRoot = resolve(viewerSrc, "..");
+  const entryPath = resolve(viewerSrc, "entry.tsx");
 
   try {
-    // Read the viewer HTML template
-    let html = await readFile(resolve(viewerRoot, "index.html"), "utf-8");
+    // Read the viewer HTML template (index.html is at package root, not src/)
+    let html = await readFile(resolve(viewerPkgRoot, "index.html"), "utf-8");
 
     // Rewrite the entry.tsx path to use absolute path to viewer package
     html = html.replace("/src/entry.tsx", entryPath);
@@ -2165,12 +2181,12 @@ async function serveViewerHTML(res: any, server: ViteDevServer): Promise<void> {
  * This is used for iframe-based component preview with CSS isolation.
  */
 async function servePreviewFrameHTML(res: any, server: ViteDevServer): Promise<void> {
-  const viewerRoot = viewerAssetsRoot;
-  const entryPath = resolve(viewerRoot, "preview-frame-entry.tsx");
+  const viewerSrc = viewerAssetsRoot;
+  const entryPath = resolve(viewerSrc, "preview-frame-entry.tsx");
 
   try {
     // Read the preview frame HTML template
-    let html = await readFile(resolve(viewerRoot, "preview-frame.html"), "utf-8");
+    let html = await readFile(resolve(viewerSrc, "preview-frame.html"), "utf-8");
 
     // Rewrite the entry path to use absolute path to viewer package
     html = html.replace("/src/preview-frame-entry.tsx", entryPath);