Hydrate real repo root path for direct preview generation writes - PR_26127_014-preview-generator-real-repo-root-hydration

Author: DavidQ

docs/dev/reports/PR_26127_014-preview-generator-real-repo-root-hydration.md

@@ -0,0 +1,35 @@
+# PR_26127_014-preview-generator-real-repo-root-hydration
+
+## Summary
+- Updated Preview Generator V2 status header order from `Status Clear +` to `Status + Clear`.
+- Hydrated Preview Generator V2 workspace launches with a real absolute filesystem `repoRoot` resolved by Workspace Manager V2.
+- Direct workspace preview generation now combines `repoRoot` with the manifest-relative generated preview target, logs the resolved paths, and writes to the validated absolute output path.
+- Display-only/non-absolute `repoRoot` values now fail workspace launch hydration, keep Generate Preview disabled, and do not silently fall back.
+
+## Repo Root Hydration Notes
+- Workspace Manager V2 resolves an absolute repo root for Preview Generator V2 launch context only.
+- Existing workspace manifests remain manifest-relative for `gameRoot`, `assetsPath`, and asset paths.
+- The Playwright repo server exposes the current absolute repo root for launch hydration and validates preview writes stay inside that repo root.
+
+## Direct Write Notes
+- Hydrated Asteroids launch resolves the generated preview target as `games/Asteroids/assets/images/preview.svg`.
+- Preview Generator V2 logs:
+  - resolved `repoRoot`
+  - resolved absolute preview output path
+  - direct write target
+  - direct write success or failure
+- If the launch context has `repoRoot: "HTML-JavaScript-Gaming"` or any other non-absolute display value, direct write remains disabled.
+
+## UI Notes
+- Preview Generator V2 status header now renders as `Status + Clear`.
+- The pre-generation preview image can still display the manifest-selected preview source such as `preview.png`; direct generation writes to the generated `preview.svg` target.
+
+## Validation
+- `npm run test:workspace-v2`
+- Result: PASS, 10 tests passed.
+- Validated Asteroids Preview Generator V2 workspace launch, absolute repo root hydration, direct write to `games/Asteroids/assets/images/preview.svg`, status path logging, and blocked non-absolute repoRoot handling.
+
+## 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 repo hydration scoped.

tests/helpers/playwrightRepoServer.mjs

@@ -17,15 +17,56 @@ function contentTypeForPath(filePath) {
   return "application/octet-stream";
 }
 
+function isInsideRepoRoot(absolutePath) {
+  const relativePath = path.relative(repoRoot, absolutePath);
+  return relativePath === "" || (!relativePath.startsWith("..") && !path.isAbsolute(relativePath));
+}
+
 export async function startRepoServer() {
   const previewWrites = new Map();
+  const previewAbsoluteWrites = new Map();
   const server = http.createServer(async (request, response) => {
     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"] || "");
+        const resolvedWritePath = path.resolve(absoluteWritePath);
+        const repoRelativePath = relativeWritePath
+          ? relativeWritePath.replaceAll("\\", "/").replace(/^\/+/, "")
+          : path.relative(repoRoot, resolvedWritePath).replaceAll("\\", "/");
+        if (!absoluteWritePath || !isInsideRepoRoot(resolvedWritePath)) {
+          response.statusCode = 403;
+          response.end("Preview write path must be inside the repo root.");
+          return;
+        }
+        if (!repoRelativePath || repoRelativePath.startsWith("..") || path.isAbsolute(repoRelativePath)) {
+          response.statusCode = 400;
+          response.end("Preview write relative path is invalid.");
+          return;
+        }
+        const bodyChunks = [];
+        for await (const chunk of request) {
+          bodyChunks.push(chunk);
+        }
+        const body = Buffer.concat(bodyChunks).toString("utf8");
+        previewWrites.set(repoRelativePath, body);
+        previewAbsoluteWrites.set(resolvedWritePath, body);
+        response.statusCode = 200;
+        response.setHeader("Content-Type", "text/plain; charset=utf-8");
+        response.end("OK");
+        return;
+      }
       const normalizedPath = path.normalize(decodedPath).replace(/^(\.\.[/\\])+/, "");
       const absolutePath = path.resolve(repoRoot, `.${normalizedPath}`);
-      if (!absolutePath.startsWith(repoRoot)) {
+      if (!isInsideRepoRoot(absolutePath)) {
         response.statusCode = 403;
         response.end("Forbidden");
         return;
@@ -71,6 +112,8 @@ export async function startRepoServer() {
 
   return {
     baseUrl: `http://127.0.0.1:${address.port}`,
+    repoRoot,
+    previewAbsoluteWrites,
     previewWrites,
     close: async () => {
       await new Promise((resolve, reject) => {

tests/playwright/tools/PreviewGeneratorV2Baseline.spec.mjs

@@ -383,6 +383,8 @@ test.describe("Preview Generator V2 baseline", () => {
 
       const statusHeader = page.locator('#statusAccordion .accordion-v2__header[aria-controls="statusAccordionContent"]');
       const statusContent = page.locator("#statusAccordionContent");
+      const statusHeaderOrder = await statusHeader.evaluate((header) => Array.from(header.querySelectorAll(":scope > span, :scope > div > span, :scope > div > button"), (element) => element.textContent.trim()));
+      expect(statusHeaderOrder).toEqual(["Status", "+", "Clear"]);
       await expect(statusHeader.locator("#clearLogBtn")).toBeVisible();
       await expect(statusHeader).toHaveAttribute("aria-expanded", "true");
       await expect(statusContent).toBeVisible();

tests/playwright/tools/WorkspaceManagerV2.spec.mjs

@@ -1,5 +1,6 @@
 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";
 
@@ -513,8 +514,6 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#paletteStatus")).toHaveText("Loaded active workspace palette Asteroids Palette.");
       await page.locator("#returnToWorkspaceButton").click();
       await expect(page).toHaveURL(/workspace-manager-v2\/index\.html\?hostContextId=workspace-manager-v2-/);
-      await page.locator("#activeGameSelect").selectOption("Pong");
-      await expect(page.locator("#activeGameSummary")).toContainText("games/Pong/");
       await expect(previewTile).toBeEnabled();
       await expect(previewTile).toContainText("Schema-valid manifest");
       await page.locator('[data-workspace-tool-id="preview-generator-v2"]').click();
@@ -524,40 +523,50 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       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("HTML-JavaScript-Gaming");
+      await expect(page.locator("#repoSelectedValue")).toHaveText(server.repoRoot);
       await expect(page.locator("#workspaceContextValue")).toHaveCount(0);
       await expect(page.locator("#repoDestinationContent")).not.toContainText("Workspace launch");
       await expect(page.locator("#targetTypeGames")).toBeChecked();
       await expect(page.locator('label[for="targetTypeGames"]')).toBeVisible();
       await expect(page.locator('label[for="targetTypeSamples"]')).toBeHidden();
       await expect(page.locator('label[for="targetTypeTools"]')).toBeHidden();
       await expect(page.locator("#assetFolder")).toHaveValue("assets/images");
-      await expect(page.locator("#sampleList")).toHaveValue("Pong");
-      await expect(page.locator("#previewTargetValue")).toHaveText("games/Pong/assets/images/preview.svg");
+      await expect(page.locator("#sampleList")).toHaveValue("Asteroids");
+      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/Pong/assets/images/preview.svg");
-      await expect(page.locator("#log")).toContainText("OK Workspace launch context hydrated for Pong.");
-      await expect(page.locator("#log")).toContainText("Repo selected from Workspace Manager V2 manifest repoRoot: HTML-JavaScript-Gaming.");
+      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("Asset folder: assets\\images");
-      await expect(page.locator("#log")).toContainText("Manifest preview asset: assets.image.preview.preview (image/svg)");
-      await expect(page.locator("#log")).toContainText("Manifest preview source: games/Pong/assets/images/preview.svg");
-      await expect(page.locator("#log")).toContainText("Generated preview target: games/Pong/assets/images/preview.svg");
-      await expect(page.locator("#log")).toContainText("Preview target: games/Pong/assets/images/preview.svg");
-      await expect(page.locator("#log")).toContainText("WARN Workspace background image role is missing; using manifest palette background color Background #05070A.");
+      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");
+      await expect(page.locator("#log")).toContainText("Generated preview target: games/Asteroids/assets/images/preview.svg");
+      await expect(page.locator("#log")).toContainText("Preview target: games/Asteroids/assets/images/preview.svg");
+      await expect(page.locator("#log")).toContainText("Workspace background source: assets.image.background.deluxe -> games/Asteroids/assets/images/deluxe.png");
+      await expect(page.locator("#log")).toContainText("Workspace background color: Space Black #020617 from palette-manager-v2 swatch.");
       await expect(page.locator("#log")).not.toContainText("FAIL Workspace background hydration");
-      await expect(page.locator("#log")).toContainText("OK Workspace manifest preview source is valid at games/Pong/assets/images/preview.svg.");
+      await expect(page.locator("#log")).toContainText("OK Workspace manifest preview source is valid at games/Asteroids/assets/images/preview.png.");
+      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/Pong/assets/images/preview.svg.", { timeout: 20000 });
-      await expect(page.locator("#log")).toContainText("Direct preview write target: games/Pong/assets/images/preview.svg", { timeout: 20000 });
-      await expect(page.locator("#log")).toContainText("OK   Pong", { timeout: 20000 });
+      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/Pong/assets/images/preview.svg")).toContain("<svg");
+      expect(server.previewWrites.get("games/Asteroids/assets/images/preview.svg")).toContain("<svg");
+      expect(server.previewAbsoluteWrites.get(absoluteAsteroidsPreviewPath)).toContain("<svg");
       await page.locator("#returnToWorkspaceButton").click();
       await expect(page).toHaveURL(/workspace-manager-v2\/index\.html\?hostContextId=workspace-manager-v2-/);
       expect(pageErrors).toEqual([]);
@@ -604,6 +613,36 @@ test.describe("Workspace Manager V2 bootstrap", () => {
     }
   });
 
+  test("blocks Preview Generator V2 workspace direct write when repoRoot is not absolute", async ({ page }) => {
+    const server = await startRepoServer();
+    const pageErrors = [];
+    const hostContextId = "workspace-manager-v2-display-root-context";
+    const displayRootManifest = JSON.parse(await readFile("games/Asteroids/game.manifest.json", "utf8"));
+    displayRootManifest.repoRoot = "HTML-JavaScript-Gaming";
+
+    page.on("pageerror", (error) => {
+      pageErrors.push(error.message);
+    });
+
+    await page.addInitScript(({ contextId, manifest }) => {
+      window.sessionStorage.setItem(contextId, JSON.stringify(manifest));
+    }, { contextId: hostContextId, manifest: displayRootManifest });
+    await coverageReporter.start(page);
+    await page.goto(`${server.baseUrl}/tools/preview-generator-v2/index.html?launch=workspace&fromTool=workspace-manager-v2&hostContextId=${hostContextId}`, { waitUntil: "networkidle" });
+
+    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");
+      expect(server.previewWrites.size).toBe(0);
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await coverageReporter.stop(page);
+      await server.close();
+    }
+  });
+
   test("loads Gravity Well and Pong manifests as current Workspace Manager V2 manifests", async ({ page }) => {
     const server = await openWorkspaceManagerV2(page);
     const pageErrors = [];