Unblock Preview Generator V2 launch when repo root endpoint is unavailable - PR_26127_015-preview-generator-repo-root-resolution-fix

Author: DavidQ

docs/dev/reports/PR_26127_015-preview-generator-repo-root-resolution-fix.md

@@ -0,0 +1,32 @@
+# PR_26127_015-preview-generator-repo-root-resolution-fix
+
+## Summary
+- Removed the Workspace Manager V2 pre-launch absolute repoRoot resolution fetch.
+- Removed the `/__workspace-manager-v2/repo-root` test-server path so launch no longer depends on that endpoint.
+- Workspace Manager V2 now passes the existing validated session/manifest context through to Preview Generator V2.
+- Preview Generator V2 now hydrates workspace launch even when manifest `repoRoot` is only a display label.
+
+## Repo Root Resolution Notes
+- Display-only repo roots such as `HTML-JavaScript-Gaming` no longer block Preview Generator V2 from opening.
+- Preview Generator V2 status distinguishes:
+  - workspace launch hydrated
+  - repoRoot display label available
+  - absolute repoRoot missing
+  - direct preview write unavailable until a real writable repo root is selected
+- Generate Preview remains disabled when workspace launch has no absolute/writable repo root.
+- No hidden fallback behavior was added.
+
+## Launch Behavior Notes
+- Workspace Manager V2 launch behavior is preserved for other tools.
+- Preview Generator V2 still preserves manifest-relative paths such as `games/Asteroids/assets/images/preview.svg`.
+- Direct write support remains available only when an absolute repoRoot is present and validated.
+
+## Validation
+- `npm run test:workspace-v2`
+- Result: PASS, 10 tests passed.
+- Validated Preview Generator V2 launches from Workspace Manager V2 with display-only repoRoot, shows actionable status, keeps Generate Preview disabled, and does not call `/__workspace-manager-v2/repo-root`.
+
+## Out Of Scope
+- Deprecated `tools/workspace-v2` was not modified.
+- Sample JSON was not modified.
+- Full samples smoke test was skipped because this PR is Preview Generator launch unblock scoped.

tests/helpers/playwrightRepoServer.mjs

@@ -29,12 +29,6 @@ export async function startRepoServer() {
     try {
       const requestUrl = new URL(request.url || "/", "http://127.0.0.1");
       const decodedPath = decodeURIComponent(requestUrl.pathname);
-      if (request.method === "GET" && decodedPath === "/__workspace-manager-v2/repo-root") {
-        response.statusCode = 200;
-        response.setHeader("Content-Type", "application/json; charset=utf-8");
-        response.end(JSON.stringify({ repoRoot }));
-        return;
-      }
       if (request.method === "PUT" && decodedPath === "/__workspace-manager-v2/write-preview") {
         const absoluteWritePath = String(request.headers["x-workspace-preview-absolute-path"] || "");
         const relativeWritePath = String(request.headers["x-workspace-preview-relative-path"] || "");

tests/playwright/tools/WorkspaceManagerV2.spec.mjs

@@ -1,6 +1,5 @@
 import { expect, test } from "@playwright/test";
 import { readFile } from "node:fs/promises";
-import path from "node:path";
 import { startRepoServer } from "../../helpers/playwrightRepoServer.mjs";
 import { workspaceV2CoverageReporter as coverageReporter } from "../../helpers/workspaceV2CoverageReporter.mjs";
 
@@ -522,8 +521,8 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator('[data-launch-mode-nav="workspace"]')).toBeVisible();
       await expect(page.locator('[data-launch-mode-nav="workspace"] button')).toHaveText(["Generate Image", "Return to Workspace"]);
       await expect(page.locator("#executeBtn")).toBeVisible();
-      await expect(page.locator("#executeBtn")).toBeEnabled();
-      await expect(page.locator("#repoSelectedValue")).toHaveText(server.repoRoot);
+      await expect(page.locator("#executeBtn")).toBeDisabled();
+      await expect(page.locator("#repoSelectedValue")).toHaveText("HTML-JavaScript-Gaming");
       await expect(page.locator("#workspaceContextValue")).toHaveCount(0);
       await expect(page.locator("#repoDestinationContent")).not.toContainText("Workspace launch");
       await expect(page.locator("#targetTypeGames")).toBeChecked();
@@ -535,11 +534,12 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#previewTargetValue")).toHaveText("games/Asteroids/assets/images/preview.svg");
       await expect(page.locator("#lastGeneratedImagePreview")).toBeVisible();
       await expect(page.locator("#lastGeneratedImageMeta")).toHaveText("Preview target: games/Asteroids/assets/images/preview.png");
-      const absoluteAsteroidsPreviewPath = path.join(server.repoRoot, "games", "Asteroids", "assets", "images", "preview.svg");
       await expect(page.locator("#log")).toContainText("OK Workspace launch context hydrated for Asteroids.");
-      await expect(page.locator("#log")).toContainText(`Repo selected from Workspace Manager V2 manifest repoRoot: ${server.repoRoot}.`);
-      await expect(page.locator("#log")).toContainText(`Resolved repoRoot: ${server.repoRoot}`);
-      await expect(page.locator("#log")).toContainText(`Resolved absolute preview output path: ${absoluteAsteroidsPreviewPath}`);
+      await expect(page.locator("#log")).toContainText("Workspace repoRoot display label available: HTML-JavaScript-Gaming.");
+      await expect(page.locator("#log")).toContainText("WARN Absolute repoRoot missing for workspace launch; manifest repoRoot is display-only: HTML-JavaScript-Gaming.");
+      await expect(page.locator("#log")).toContainText("Direct preview write unavailable until a real writable repo root is selected.");
+      await expect(page.locator("#log")).not.toContainText("Unable to resolve absolute repoRoot");
+      await expect(page.locator("#log")).not.toContainText("/__workspace-manager-v2/repo-root");
       await expect(page.locator("#log")).toContainText("Asset folder: assets\\images");
       await expect(page.locator("#log")).toContainText("Manifest preview asset: assets.image.preview.preview (image/png)");
       await expect(page.locator("#log")).toContainText("Manifest preview source: games/Asteroids/assets/images/preview.png");
@@ -552,21 +552,9 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       const previewStatusHeaderOrder = await page.locator(".preview-generator-v2__status-accordion-header").evaluate((header) => Array.from(header.querySelectorAll(":scope > span, :scope > div > span, :scope > div > button"), (element) => element.textContent.trim()));
       expect(previewStatusHeaderOrder).toEqual(["Status", "+", "Clear"]);
       await page.locator("#baseUrl").fill(server.baseUrl);
-      await expect(page.locator("#executeBtn")).toBeEnabled();
-      let previewDownloadOpened = false;
-      page.on("download", () => {
-        previewDownloadOpened = true;
-      });
-      await page.locator("#executeBtn").click();
-      await expect(page.locator("#log")).toContainText("Workspace launch direct preview write target: games/Asteroids/assets/images/preview.svg.", { timeout: 20000 });
-      await expect(page.locator("#log")).toContainText(`Workspace launch absolute preview output path: ${absoluteAsteroidsPreviewPath}.`, { timeout: 20000 });
-      await expect(page.locator("#log")).toContainText("Direct preview write target: games/Asteroids/assets/images/preview.svg", { timeout: 20000 });
-      await expect(page.locator("#log")).toContainText(`Direct preview absolute path: ${absoluteAsteroidsPreviewPath}`, { timeout: 20000 });
-      await expect(page.locator("#log")).toContainText(`OK Direct preview write completed: ${absoluteAsteroidsPreviewPath}`, { timeout: 20000 });
-      await expect(page.locator("#log")).toContainText("OK   Asteroids", { timeout: 20000 });
-      expect(previewDownloadOpened).toBe(false);
-      expect(server.previewWrites.get("games/Asteroids/assets/images/preview.svg")).toContain("<svg");
-      expect(server.previewAbsoluteWrites.get(absoluteAsteroidsPreviewPath)).toContain("<svg");
+      await expect(page.locator("#executeBtn")).toBeDisabled();
+      expect(server.previewWrites.size).toBe(0);
+      expect(server.previewAbsoluteWrites.size).toBe(0);
       await page.locator("#returnToWorkspaceButton").click();
       await expect(page).toHaveURL(/workspace-manager-v2\/index\.html\?hostContextId=workspace-manager-v2-/);
       expect(pageErrors).toEqual([]);
@@ -613,7 +601,7 @@ test.describe("Workspace Manager V2 bootstrap", () => {
     }
   });
 
-  test("blocks Preview Generator V2 workspace direct write when repoRoot is not absolute", async ({ page }) => {
+  test("opens Preview Generator V2 workspace launch with display-only repoRoot and actionable status", async ({ page }) => {
     const server = await startRepoServer();
     const pageErrors = [];
     const hostContextId = "workspace-manager-v2-display-root-context";
@@ -633,8 +621,13 @@ test.describe("Workspace Manager V2 bootstrap", () => {
     try {
       await expect(page.locator("#repoSelectedValue")).toHaveText("HTML-JavaScript-Gaming");
       await expect(page.locator("#executeBtn")).toBeDisabled();
-      await expect(page.locator("#log")).toContainText("FAIL Workspace launch context hydration: repoRoot must be an absolute filesystem path, received HTML-JavaScript-Gaming.");
-      await expect(page.locator("#log")).not.toContainText("OK Workspace launch context hydrated");
+      await expect(page.locator("#previewTargetValue")).toHaveText("games/Asteroids/assets/images/preview.svg");
+      await expect(page.locator("#log")).toContainText("OK Workspace launch context hydrated for Asteroids.");
+      await expect(page.locator("#log")).toContainText("Workspace repoRoot display label available: HTML-JavaScript-Gaming.");
+      await expect(page.locator("#log")).toContainText("WARN Absolute repoRoot missing for workspace launch; manifest repoRoot is display-only: HTML-JavaScript-Gaming.");
+      await expect(page.locator("#log")).toContainText("Direct preview write unavailable until a real writable repo root is selected.");
+      await expect(page.locator("#log")).not.toContainText("/__workspace-manager-v2/repo-root");
+      await expect(page.locator("#log")).not.toContainText("FAIL Workspace launch context hydration");
       expect(server.previewWrites.size).toBe(0);
       expect(pageErrors).toEqual([]);
     } finally {

tools/preview-generator-v2/PreviewGeneratorV2App.js

@@ -20,6 +20,7 @@ let isGenerating = false;
 let workspacePreviewAssetFolder = "";
 let workspacePreviewFileValid = false;
 let workspacePreviewGameId = "";
+let workspaceLaunchHydrated = false;
 let workspaceRepoRootHydrated = false;
 let workspaceRepoRootName = "";
 let workspaceResolvedRepoRoot = "";
@@ -394,7 +395,7 @@ function updateWriteFolderSampleLabel() {
 }
 
 function getWorkspacePreviewTargetDisplayPath() {
-  if (isWorkspaceManagerLaunch() && (repoDirHandle || workspaceRepoRootHydrated) && workspaceGeneratedPreviewPath) {
+  if (isWorkspaceManagerLaunch() && workspaceLaunchHydrated && workspaceGeneratedPreviewPath) {
     return workspaceGeneratedPreviewPath;
   }
   return workspaceManifestPreviewPath;
@@ -667,7 +668,7 @@ function isPreviewWriteError(error) {
 
 function validateWorkspacePreviewWritePath(entry) {
   if (!isWorkspaceManagerLaunch() || !workspaceRepoRootHydrated || !workspacePreviewFileValid) {
-    throw previewWriteError("Workspace preview write path is unavailable because launch hydration is incomplete.");
+    throw previewWriteError("Workspace direct preview write is unavailable until an absolute repo root is selected.");
   }
   const targetPath = normalizeWorkspacePath(getWorkspacePreviewTargetDisplayPath());
   if (!targetPath) {
@@ -739,7 +740,7 @@ async function processOne(entry, baseUrl, waitMs) {
     : null;
   const decision = targetDirHandle
     ? await shouldRewrite(targetDirHandle)
-    : { rewrite: true, reason: "workspace-launch-hydrated-repo-root" };
+    : { rewrite: true, reason: "workspace-launch-absolute-repo-root" };
 
   ui.outputSummary.setWriteFolderActual(getWriteFolderDisplayPath(entry));
   const label = entry.targetType === "samples" ? entry.id : entry.name;
@@ -1028,6 +1029,7 @@ class PreviewGeneratorV2App {
     }
     logger.log("Workspace launch context hydration started.");
     workspacePreviewFileValid = false;
+    workspaceLaunchHydrated = false;
     workspaceRepoRootHydrated = false;
     workspaceResolvedRepoRoot = "";
     workspaceManifestPreviewPath = "";
@@ -1048,45 +1050,39 @@ class PreviewGeneratorV2App {
       return;
     }
 
-    const resolvedRepoRoot = String(manifest.repoRoot || "").trim();
-    if (!isAbsoluteFilesystemPath(resolvedRepoRoot)) {
-      repoDisplayName = resolvedRepoRoot;
-      workspaceRepoRootName = resolvedRepoRoot;
-      ui.setRepoDestinationDisplayName(resolvedRepoRoot || "not selected");
-      logger.log(`FAIL Workspace launch context hydration: repoRoot must be an absolute filesystem path, received ${resolvedRepoRoot || "(empty)"}.`);
-      this.syncGeneratePreviewButton();
-      return;
-    }
-
-    let resolvedPreviewOutputPath = "";
-    try {
-      resolvedPreviewOutputPath = resolveWorkspaceAbsolutePreviewOutputPath(resolvedRepoRoot, previewTarget.generatedPreviewPath);
-    } catch (error) {
-      logger.log(`FAIL Workspace launch context hydration: ${error.message}`);
-      this.syncGeneratePreviewButton();
-      return;
-    }
-
-    repoDisplayName = resolvedRepoRoot;
+    const manifestRepoRoot = String(manifest.repoRoot || "").trim();
+    repoDisplayName = manifestRepoRoot;
     repoDirHandle = null;
-    workspaceRepoRootHydrated = true;
-    workspaceRepoRootName = resolvedRepoRoot;
-    workspaceResolvedRepoRoot = resolvedRepoRoot;
+    workspaceLaunchHydrated = true;
+    workspaceRepoRootName = manifestRepoRoot;
     workspacePreviewAssetFolder = previewTarget.previewAssetFolder;
     workspacePreviewGameId = manifest.gameId;
     workspaceManifestPreviewPath = previewTarget.manifestPreviewPath;
     workspaceGeneratedPreviewPath = previewTarget.generatedPreviewPath;
-    workspaceAbsolutePreviewOutputPath = resolvedPreviewOutputPath;
+    if (isAbsoluteFilesystemPath(manifestRepoRoot)) {
+      try {
+        workspaceAbsolutePreviewOutputPath = resolveWorkspaceAbsolutePreviewOutputPath(manifestRepoRoot, previewTarget.generatedPreviewPath);
+        workspaceRepoRootHydrated = true;
+        workspaceResolvedRepoRoot = manifestRepoRoot;
+      } catch (error) {
+        logger.log(`WARN Workspace direct preview write unavailable: ${error.message}`);
+      }
+    }
     ui.setRepoDestinationDisplayName(repoDisplayName);
     ui.targetSource.setSelectedTargetType("games");
     ui.targetSource.showWorkspaceGamesOnly();
     ui.assetFolder.setValue(workspacePreviewAssetFolder);
     ui.pathsOrIds.setValue(manifest.gameId);
     await updatePathPreviewLabels();
     logger.log(`OK Workspace launch context hydrated for ${manifest.gameId}.`);
-    logger.log(`Repo selected from Workspace Manager V2 manifest repoRoot: ${repoDisplayName}.`);
-    logger.log(`Resolved repoRoot: ${workspaceResolvedRepoRoot}`);
-    logger.log(`Resolved absolute preview output path: ${workspaceAbsolutePreviewOutputPath}`);
+    logger.log(`Workspace repoRoot display label available: ${repoDisplayName}.`);
+    if (workspaceRepoRootHydrated) {
+      logger.log(`Resolved repoRoot: ${workspaceResolvedRepoRoot}`);
+      logger.log(`Resolved absolute preview output path: ${workspaceAbsolutePreviewOutputPath}`);
+    } else {
+      logger.log(`WARN Absolute repoRoot missing for workspace launch; manifest repoRoot is display-only: ${repoDisplayName || "(empty)"}.`);
+      logger.log("Direct preview write unavailable until a real writable repo root is selected.");
+    }
     logger.log("Target source: games");
     logger.log(`Asset folder: ${getAssetFolderDisplayPath()}`);
     logger.log(`Manifest preview asset: ${previewTarget.previewAssetId} (${previewTarget.previewAssetType}/${previewTarget.previewAssetKind})`);

tools/workspace-manager-v2/js/WorkspaceManagerV2App.js

@@ -150,17 +150,9 @@ export class WorkspaceManagerV2App {
       this.statusLog.fail(`Launch blocked: ${validation.message}`);
       return;
     }
-    const launchContextResult = await this.contextService.buildLaunchContextForTool(this.activeContext, toolId);
-    if (!launchContextResult.ok) {
-      this.statusLog.fail(`Launch blocked: ${launchContextResult.message}`);
-      return;
-    }
-    if (launchContextResult.repoRoot) {
-      this.statusLog.ok(`Resolved Workspace Manager V2 launch repoRoot: ${launchContextResult.repoRoot}`);
-    }
     const hostContextId = this.activeHostContextId
-      ? this.contextService.writePersistedContext(this.activeHostContextId, launchContextResult.context)
-      : this.contextService.persistContext(launchContextResult.context);
+      ? this.contextService.writePersistedContext(this.activeHostContextId, this.activeContext)
+      : this.contextService.persistContext(this.activeContext);
     this.activeHostContextId = hostContextId;
     this.statusLog.ok(`Stored Workspace Manager V2 schema-valid manifest ${hostContextId} for ${toolId}.`);
     this.contextService.launchTool(toolId, hostContextId, { workspaceMode: this.activeWorkspaceMode });

tools/workspace-manager-v2/js/services/WorkspaceManagerV2ContextService.js

@@ -1,9 +1,7 @@
 const HOST_CONTEXT_STORAGE_KEY = "workspace-manager-v2-active-host-context-id";
 const WORKSPACE_MANIFEST_SCHEMA_PATH = "/tools/schemas/workspace.manifest.schema.json";
-const WORKSPACE_REPO_ROOT_ENDPOINT = "/__workspace-manager-v2/repo-root";
 const ASSET_MANAGER_V2_TOOL_KEY = "asset-manager-v2";
 const PALETTE_MANAGER_V2_TOOL_KEY = "palette-manager-v2";
-const PREVIEW_GENERATOR_V2_TOOL_KEY = "preview-generator-v2";
 const TEMPORARY_UAT_MANIFEST_PATH = "/games/_template/workspace-manager-v2-UAT.manifest.json";
 const WORKSPACE_LAUNCHABLE_TOOLS = Object.freeze([
   Object.freeze({
@@ -66,13 +64,6 @@ function makeHostContextId() {
   return `workspace-manager-v2-${Date.now().toString(36)}`;
 }
 
-function isAbsoluteFilesystemPath(value) {
-  const pathValue = String(value || "").trim();
-  return /^[A-Za-z]:[\\/]/.test(pathValue)
-    || pathValue.startsWith("/")
-    || pathValue.startsWith("\\\\");
-}
-
 function temporaryUatGameFromManifest(workspaceManifest) {
   if (workspaceManifest?.gameId !== "_template"
     || workspaceManifest?.gameRoot !== "games/_template/"
@@ -361,47 +352,6 @@ export class WorkspaceManagerV2ContextService {
     };
   }
 
-  async resolveAbsoluteRepoRoot() {
-    if (typeof this.fetchRef !== "function") {
-      return { ok: false, message: "Fetch API is unavailable; Workspace Manager V2 cannot resolve the absolute repoRoot." };
-    }
-    try {
-      const response = await this.fetchRef(WORKSPACE_REPO_ROOT_ENDPOINT, { cache: "no-store" });
-      if (!response.ok) {
-        return { ok: false, message: `Unable to resolve absolute repoRoot from ${WORKSPACE_REPO_ROOT_ENDPOINT}: ${response.status}` };
-      }
-      const payload = await response.json();
-      const repoRoot = String(payload?.repoRoot || "").trim();
-      if (!repoRoot) {
-        return { ok: false, message: `${WORKSPACE_REPO_ROOT_ENDPOINT} did not return repoRoot.` };
-      }
-      if (!isAbsoluteFilesystemPath(repoRoot)) {
-        return { ok: false, message: `Resolved repoRoot must be an absolute filesystem path; received ${repoRoot}.` };
-      }
-      return { ok: true, repoRoot };
-    } catch (error) {
-      return { ok: false, message: `Unable to resolve absolute repoRoot from ${WORKSPACE_REPO_ROOT_ENDPOINT}: ${error.message}` };
-    }
-  }
-
-  async buildLaunchContextForTool(workspaceManifest, toolId) {
-    const launchContext = clone(workspaceManifest);
-    let resolvedRepoRoot = "";
-    if (toolId === PREVIEW_GENERATOR_V2_TOOL_KEY) {
-      const repoRootResult = await this.resolveAbsoluteRepoRoot();
-      if (!repoRootResult.ok) {
-        return repoRootResult;
-      }
-      launchContext.repoRoot = repoRootResult.repoRoot;
-      resolvedRepoRoot = repoRootResult.repoRoot;
-    }
-    const validation = await this.validateGeneratedManifest(launchContext);
-    if (!validation.ok) {
-      return validation;
-    }
-    return { ok: true, context: launchContext, repoRoot: resolvedRepoRoot };
-  }
-
   async loadWorkspaceManifestSchema() {
     if (typeof this.fetchRef !== "function") {
       return { ok: false, message: "Fetch API is unavailable; Workspace Manager V2 cannot validate workspace manifests." };