Add explicit resolved output path logging to Preview Generator V2 writes - PR_26128_030-preview-generator-write-path-logging

Author: DavidQ

docs/dev/reports/playwright_preview_generator_write_path_logging.md

@@ -0,0 +1,23 @@
+# Playwright Preview Generator V2 Write Path Logging
+
+## Commands
+- `npx playwright test tests/playwright/tools/WorkspaceManagerV2.spec.mjs --project=playwright --workers=1 --reporter=list -g "exports manifests and launches tools from fixed Workspace Manager V2 tiles|logs actionable Preview Generator V2 output path resolution failures"`
+- `npm run test:workspace-v2`
+
+## Results
+- Focused Preview Generator V2 write logging coverage: passed 2/2.
+- Workspace Manager V2 suite: passed 17/17.
+
+## Targeted Coverage
+- Generated a Preview Generator V2 workspace preview image.
+- Verified the log shows `OK WRITE Asteroids`.
+- Verified the log shows resolved relative output path `games/Asteroids/assets/images/preview.svg`.
+- Verified the log shows handle-exposed absolute output path `HTML-JavaScript-Gaming/games/Asteroids/assets/images/preview.svg`.
+- Verified the log identifies source resolution context as `workspace.tools.preview-generator-v2.data`, selected game `Asteroids`, and resolved `assets/images` target.
+- Verified summary counts remain present after generation.
+- Verified failed target-directory resolution logs actionable `FAIL PATH` details.
+- Verified failed resolution logs relative output path, absolute output path state, and source resolution context.
+- Verified failed resolution increments the summary `Failed` count while preserving `Written` and `Skipped` counts.
+
+## Skipped
+- Full samples smoke test was skipped by request. The relevant Preview Generator V2 successful write, path logging, failure logging, and Workspace Manager V2 launch paths are covered by `tests/playwright/tools/WorkspaceManagerV2.spec.mjs`.

docs/dev/reports/preview_generator_write_path_logging.md

@@ -0,0 +1,48 @@
+# Preview Generator V2 Write Path Logging
+
+## Scope
+- Added explicit per-write path logging to Preview Generator V2.
+- Successful writes now log `OK WRITE` with:
+  - target label/game name
+  - resolved relative output path
+  - absolute output path when the repo handle exposes one
+  - source resolution context
+- Preserved existing per-item `RUN`, `OUT`, `OK`, `WARN`, `FAIL`, and `SKIP` logging.
+- Preserved summary counts for:
+  - `Written`
+  - `Warnings`
+  - `Failed`
+  - `Skipped`
+
+## Successful Write Logging
+- Workspace-launched Preview Generator V2 writes now identify:
+  - `workspace.tools.preview-generator-v2.data`
+  - selected game
+  - resolved `assets/images` target
+  - resolved relative preview path
+  - handle-exposed absolute preview path when available.
+- The Asteroids workspace flow logs:
+  - `OK WRITE Asteroids`
+  - `Resolved relative output path: games/Asteroids/assets/images/preview.svg`
+  - `Absolute output path: HTML-JavaScript-Gaming/games/Asteroids/assets/images/preview.svg`
+  - `Source resolution context: workspace.tools.preview-generator-v2.data; selected game: Asteroids; resolved assets/images target: assets/images; target type: games`
+
+## Failure Logging
+- Output path resolution now fails before capture/write when the target directory cannot be resolved.
+- Failure logs include:
+  - `FAIL PATH`
+  - target label
+  - exact target directory error
+  - relative output path resolution state
+  - absolute output path resolution state when available
+  - source resolution context.
+- Failed path resolution contributes to the existing summary `Failed` count.
+
+## Guardrails
+- No hidden fallback output paths were added.
+- No sample JSON was modified.
+- No roadmap content was modified.
+- Existing batch logging and summary sections are preserved.
+
+## Skipped
+- Full samples smoke test was skipped by request. The changed surface is Preview Generator V2 write logging and is covered by the focused successful-write and failed-path-resolution Playwright coverage inside `npm run test:workspace-v2`.

tests/playwright/tools/WorkspaceManagerV2.spec.mjs

@@ -18,6 +18,13 @@ async function openAssetManagerV2(page, query = "") {
   return server;
 }
 
+async function openPreviewGeneratorV2(page, query = "") {
+  const server = await startRepoServer();
+  await coverageReporter.start(page);
+  await page.goto(`${server.baseUrl}/tools/preview-generator-v2/index.html${query}`, { waitUntil: "networkidle" });
+  return server;
+}
+
 async function openToolsIndex(page) {
   const server = await startRepoServer();
   await coverageReporter.start(page);
@@ -186,6 +193,58 @@ async function readWorkspaceSessionHydration(page) {
   });
 }
 
+async function installMissingGamePreviewRepoPicker(page) {
+  await page.addInitScript(() => {
+    function makeDirectoryHandle(name, children = {}, path = name) {
+      return {
+        children,
+        kind: "directory",
+        name,
+        path,
+        async getDirectoryHandle(childName, options = {}) {
+          const child = children[childName];
+          if (child?.kind === "directory") {
+            return child;
+          }
+          if (options.create) {
+            const created = makeDirectoryHandle(childName, {}, `${path}/${childName}`);
+            children[childName] = created;
+            return created;
+          }
+          throw new Error(`Missing directory: ${path}/${childName}`);
+        },
+        async getFileHandle(childName, options = {}) {
+          const child = children[childName];
+          if (child?.kind === "file") {
+            return child;
+          }
+          if (options.create) {
+            const created = {
+              kind: "file",
+              name: childName,
+              path: `${path}/${childName}`,
+              async createWritable() {
+                return {
+                  async write() {},
+                  async close() {}
+                };
+              }
+            };
+            children[childName] = created;
+            return created;
+          }
+          throw new Error(`Missing file: ${path}/${childName}`);
+        }
+      };
+    }
+
+    window.showDirectoryPicker = async () => makeDirectoryHandle("HTML-JavaScript-Gaming", {
+      games: makeDirectoryHandle("games", {}, "HTML-JavaScript-Gaming/games"),
+      tools: makeDirectoryHandle("tools", {}, "HTML-JavaScript-Gaming/tools")
+    });
+  });
+}
+
 async function expectSessionInspectorV2AccordionToggles(page, contentId) {
   const header = page.locator(`.accordion-v2__header[aria-controls="${contentId}"]`);
   const content = page.locator(`#${contentId}`);
@@ -1819,7 +1878,6 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#log")).toContainText("Workspace launch repo context resolved from session storage; independent repo selection is not required.");
       await expect(page.locator("#log")).not.toContainText("Direct preview write");
       await expect(page.locator("#log")).not.toContainText("Resolved repoPath");
-      await expect(page.locator("#log")).not.toContainText("absolute preview output path");
       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")).not.toContainText("/__workspace-manager-v2/write-preview");
@@ -1838,6 +1896,10 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#log")).toContainText("Starting execution...", { timeout: 20000 });
       await expect(page.locator("#log")).toContainText("RUN  Asteroids", { timeout: 20000 });
       await expect(page.locator("#log")).toContainText("OUT  games\\Asteroids\\assets\\images\\preview.svg", { timeout: 20000 });
+      await expect(page.locator("#log")).toContainText("OK WRITE Asteroids", { timeout: 20000 });
+      await expect(page.locator("#log")).toContainText("Resolved relative output path: games/Asteroids/assets/images/preview.svg", { timeout: 20000 });
+      await expect(page.locator("#log")).toContainText("Absolute output path: HTML-JavaScript-Gaming/games/Asteroids/assets/images/preview.svg", { timeout: 20000 });
+      await expect(page.locator("#log")).toContainText("Source resolution context: workspace.tools.preview-generator-v2.data; selected game: Asteroids; resolved assets/images target: assets/images; target type: games", { timeout: 20000 });
       await expect(page.locator("#log")).toContainText("OK   Asteroids", { timeout: 20000 });
       await expect(page.locator("#log")).toContainText("Done.", { timeout: 20000 });
       await expect(page.locator("#lastGeneratedImageMeta")).toHaveText("Last generated: Asteroids");
@@ -2046,6 +2108,41 @@ test.describe("Workspace Manager V2 bootstrap", () => {
     }
   });
 
+  test("logs actionable Preview Generator V2 output path resolution failures", async ({ page }) => {
+    await installMissingGamePreviewRepoPicker(page);
+    const server = await openPreviewGeneratorV2(page);
+    const pageErrors = [];
+
+    page.on("pageerror", (error) => {
+      pageErrors.push(error.message);
+    });
+
+    try {
+      await page.locator("#pickRepoBtn").click();
+      await expect(page.locator("#repoSelectedValue")).toHaveText("HTML-JavaScript-Gaming");
+      await page.locator("#targetTypeGames").check();
+      await page.locator("#baseUrl").fill(server.baseUrl);
+      await page.locator("#sampleList").fill("MissingGame");
+      await expect(page.locator("#executeBtn")).toBeEnabled();
+
+      await page.locator("#executeBtn").click();
+      const log = page.locator("#log");
+      await expect(log).toContainText("FAIL PATH MissingGame", { timeout: 10000 });
+      await expect(log).toContainText("Unable to resolve target directory: Missing directory: HTML-JavaScript-Gaming/games/MissingGame", { timeout: 10000 });
+      await expect(log).toContainText("relative output path: games/MissingGame/assets/images/preview.svg", { timeout: 10000 });
+      await expect(log).toContainText("absolute output path: HTML-JavaScript-Gaming/games/MissingGame/assets/images/preview.svg", { timeout: 10000 });
+      await expect(log).toContainText("source resolution context: preview-generator-v2 form controls; selected game: MissingGame; resolved assets/images target: assets/images; target type: games", { timeout: 10000 });
+      await expect(log).toContainText("Written: 0", { timeout: 10000 });
+      await expect(log).toContainText("Failed: 1", { timeout: 10000 });
+      await expect(log).toContainText("Skipped: 0", { timeout: 10000 });
+      await expect(log).toContainText("Done.", { timeout: 10000 });
+      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 = [];

tools/preview-generator-v2/PreviewGeneratorV2App.js

@@ -72,6 +72,10 @@ function normalizeWorkspacePath(value) {
     .replace(/^\/+|\/+$/g, "");
 }
 
+function normalizeOutputPath(value) {
+  return normalizeWorkspacePath(value);
+}
+
 function repoRootNameMatches(selectedRepoName, expectedRepoRoot) {
   const expected = String(expectedRepoRoot || "").trim();
   if (!expected) {
@@ -424,6 +428,59 @@ function getFullOutputPath(entry) {
   return `${getWriteFolderDisplayPath(entry)}\\${OUTPUT_NAME}`;
 }
 
+function getFullOutputRelativePath(entry) {
+  return normalizeOutputPath(`${getWriteFolderRelativePath(entry)}/${OUTPUT_NAME}`);
+}
+
+function outputSourceContext(entry) {
+  const selectedGame = entry.targetType === "games"
+    ? String(entry.name || workspacePreviewGameId || "").trim()
+    : String(workspacePreviewGameId || "").trim();
+  return [
+    isWorkspaceManagerLaunch() ? `${WORKSPACE_PREVIEW_GENERATOR_SESSION_KEY}.data` : "preview-generator-v2 form controls",
+    `selected game: ${selectedGame || "(not a game target)"}`,
+    `resolved assets/images target: ${getAssetFolderRelativePath() || "(empty)"}`,
+    `target type: ${entry.targetType || "(unknown)"}`
+  ].join("; ");
+}
+
+function resolveOutputPathState(entry) {
+  try {
+    const relativeOutputPath = getFullOutputRelativePath(entry);
+    const repoRootPath = normalizeOutputPath(repoDirHandle?.path);
+    return {
+      ok: true,
+      absoluteOutputPath: repoRootPath ? normalizeOutputPath(`${repoRootPath}/${relativeOutputPath}`) : "",
+      relativeOutputPath,
+      sourceContext: outputSourceContext(entry)
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      absoluteOutputPath: "",
+      message: error.message,
+      relativeOutputPath: "",
+      sourceContext: outputSourceContext(entry)
+    };
+  }
+}
+
+function absoluteOutputPathFromWrite(fileHandle, pathState) {
+  return normalizeOutputPath(fileHandle?.path) || pathState.absoluteOutputPath || "";
+}
+
+function logWritePath(label, pathState, writeResult) {
+  logger.log(`OK WRITE ${label}`);
+  logger.log(`Resolved relative output path: ${pathState.relativeOutputPath}`);
+  const absoluteOutputPath = writeResult.absoluteOutputPath || pathState.absoluteOutputPath;
+  logger.log(`Absolute output path: ${absoluteOutputPath || "unavailable (repo handle does not expose an absolute path)"}`);
+  logger.log(`Source resolution context: ${pathState.sourceContext}`);
+}
+
+function logOutputPathFailure(label, pathState, reason) {
+  logger.log(`FAIL PATH ${label}  (${reason}; relative output path: ${pathState.relativeOutputPath || "(unresolved)"}; absolute output path: ${pathState.absoluteOutputPath || "(unavailable)"}; source resolution context: ${pathState.sourceContext})`);
+}
+
 function updateWriteFolderSampleLabel() {
   const assetFolder = getAssetFolderDisplayPath() || "assets/images";
   const targetType = ui.getSelectedTargetType();
@@ -703,7 +760,7 @@ async function shouldRewrite(targetDirHandle) {
   return { rewrite: false, reason: "existing-preview-without-capture-timeout" };
 }
 
-async function writePreview(targetDirHandle, svgContent) {
+async function writePreview(targetDirHandle, svgContent, pathState) {
   const relativeOutputFolder = getAssetFolderRelativePath();
 
   const targetDir = relativeOutputFolder
@@ -714,14 +771,32 @@ async function writePreview(targetDirHandle, svgContent) {
   const writable = await fileHandle.createWritable();
   await writable.write(svgContent);
   await writable.close();
+  return {
+    absoluteOutputPath: absoluteOutputPathFromWrite(fileHandle, pathState),
+    relativeOutputPath: pathState.relativeOutputPath
+  };
 }
 
 async function processOne(entry, baseUrl, waitMs) {
-  const targetDirHandle = await getTargetDirHandle(repoDirHandle, entry);
+  const label = entry.targetType === "samples" ? entry.id : entry.name;
+  const pathState = resolveOutputPathState(entry);
+  if (!pathState.ok) {
+    logOutputPathFailure(label, pathState, pathState.message);
+    logger.log("");
+    return { id: label, status: "failed", reason: `output-path-resolution-failed: ${pathState.message}` };
+  }
+
+  let targetDirHandle;
+  try {
+    targetDirHandle = await getTargetDirHandle(repoDirHandle, entry);
+  } catch (error) {
+    logOutputPathFailure(label, pathState, `Unable to resolve target directory: ${error.message}`);
+    logger.log("");
+    return { id: label, status: "failed", reason: `output-path-resolution-failed: ${error.message}` };
+  }
   const decision = await shouldRewrite(targetDirHandle);
 
   ui.outputSummary.setWriteFolderActual(getWriteFolderDisplayPath(entry));
-  const label = entry.targetType === "samples" ? entry.id : entry.name;
 
   if (!decision.rewrite) {
     logger.log(`SKIP ${label}  (${decision.reason})`);
@@ -750,7 +825,8 @@ async function processOne(entry, baseUrl, waitMs) {
     }
 
     const svgContent = await capture.extractSvgFromFrame();
-    await writePreview(targetDirHandle, svgContent);
+    const writeResult = await writePreview(targetDirHandle, svgContent, pathState);
+    logWritePath(label, pathState, writeResult);
     ui.setLastGeneratedImage(svgContent, label);
 
     const stillHasTimeout = svgContent.includes(CAPTURE_TIMEOUT_MARKER);
@@ -766,7 +842,7 @@ async function processOne(entry, baseUrl, waitMs) {
   } catch (error) {
     const fallback = capture.buildFallbackSvg(`${CAPTURE_TIMEOUT_MARKER}: ${error.message}`);
     try {
-      await writePreview(targetDirHandle, fallback);
+      await writePreview(targetDirHandle, fallback, pathState);
     } catch (writeError) {
       const reason = `${error.message}; fallback write failed: ${writeError.message}`;
       logger.log(`FAIL ${label}  (${reason})`);