Add manifest repoPath support for Preview Generator direct writes - PR_26127_016-preview-generator-manifest-repo-path

Author: DavidQ

docs/dev/reports/PR_26127_016-preview-generator-manifest-repo-path.md

@@ -0,0 +1,38 @@
+# PR_26127_016-preview-generator-manifest-repo-path
+
+## Summary
+- Added optional `repoPath` support to `tools/schemas/workspace.manifest.schema.json`.
+- Added `repoPath` to `games/Asteroids/game.manifest.json` as the absolute filesystem repo path for direct preview writes.
+- Kept `repoRoot` as the display label.
+- Workspace Manager V2 now reads `repoPath`, surfaces `Select Repo` when it is missing, and passes manifest/session context through to launched tools.
+- Preview Generator V2 now hides `Pick Repo Folder` during Workspace Manager launches and uses manifest `repoPath` for direct writes.
+
+## Manifest Repo Path Notes
+- `repoPath` is optional in the schema so existing manifests without it can still validate.
+- When `repoPath` is present and absolute, Preview Generator V2 enables Generate Preview after preview target validation.
+- When `repoPath` is missing or invalid, Preview Generator V2 opens, logs an actionable status message, and keeps Generate Preview disabled.
+- `/__workspace-manager-v2/repo-root` is not called or restored.
+
+## Preview Generator Notes
+- Workspace launch logs now distinguish:
+  - workspace launch hydrated
+  - `repoRoot` display label available
+  - `repoPath` available or missing
+  - resolved absolute preview output path
+  - direct write success/failure
+- Asteroids Workspace Manager launch writes generated preview output to `games/Asteroids/assets/images/preview.svg` using `repoPath`.
+
+## Workspace Manager Notes
+- Preview Generator V2 tile shows `Schema-valid manifest` when `repoPath` is available.
+- Preview Generator V2 tile shows `Select Repo` when `repoPath` is missing.
+- Asset Manager V2 workspace context validation accepts the new root-level `repoPath` manifest field.
+
+## Validation
+- `npm run test:workspace-v2`
+- Result: PASS, 10 tests passed.
+- Validated manifest `repoPath`, Preview Generator workspace launch with direct write enabled, missing `repoPath` disabled/actionable state, hidden Pick Repo Folder, and no `/__workspace-manager-v2/repo-root` dependency.
+
+## 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 manifest repo path and Preview Generator launch scoped.

games/Asteroids/game.manifest.json

@@ -9,6 +9,7 @@
   "gameRoot": "games/Asteroids/",
   "assetsPath": "games/Asteroids/assets",
   "repoRoot": "HTML-JavaScript-Gaming",
+  "repoPath": "C:\\Users\\davidq\\Documents\\GitHub\\HTML-JavaScript-Gaming",
   "tools": {
     "palette-manager-v2": {
       "$schema": "tools/schemas/tools/palette-manager-v2.schema.json",

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";
 
@@ -234,6 +235,7 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#workspaceContextOutput")).toHaveValue(/"gameRoot": "games\/Asteroids\/"/);
       await expect(page.locator("#workspaceContextOutput")).toHaveValue(/"assetsPath": "games\/Asteroids\/assets"/);
       await expect(page.locator("#workspaceContextOutput")).toHaveValue(/"repoRoot": "HTML-JavaScript-Gaming"/);
+      expect(JSON.parse(await page.locator("#workspaceContextOutput").inputValue()).repoPath).toBe(server.repoRoot);
       await expect(page.locator("#workspaceContextOutput")).not.toHaveValue(/"previewImagePath"/);
       await expect(page.locator("#workspaceContextOutput")).toHaveValue(/"assets.image.bezel.bezel"/);
       await expect(page.locator("#workspaceContextOutput")).toHaveValue(/"assets.image.preview.preview"/);
@@ -311,6 +313,7 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       expect(savedManifest.documentKind).toBe("workspace-manifest");
       expect(Object.keys(savedManifest.tools).sort()).toEqual(["asset-manager-v2", "palette-manager-v2", "vector-map-editor"]);
       expect(savedManifest.repoRoot).toBe("HTML-JavaScript-Gaming");
+      expect(savedManifest.repoPath).toBe(server.repoRoot);
       expect(savedManifest.tools["palette-manager-v2"].swatches.length).toBeGreaterThan(0);
       expect(Object.keys(savedManifest.tools["asset-manager-v2"].assets)).toHaveLength(14);
       expect(savedManifest.tools["asset-manager-v2"].previewImagePath).toBeUndefined();
@@ -387,6 +390,7 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       expect(storedContext.gameRoot).toBe("games/Asteroids/");
       expect(storedContext.assetsPath).toBe("games/Asteroids/assets");
       expect(storedContext.repoRoot).toBe("HTML-JavaScript-Gaming");
+      expect(storedContext.repoPath).toBe(server.repoRoot);
       expect(storedContext.tools["palette-manager-v2"].swatches.length).toBeGreaterThan(0);
       expect(Object.keys(storedContext.tools["asset-manager-v2"].assets)).toHaveLength(14);
       expect(storedContext.tools["asset-manager-v2"].previewImagePath).toBeUndefined();
@@ -521,8 +525,9 @@ 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")).toBeDisabled();
-      await expect(page.locator("#repoSelectedValue")).toHaveText("HTML-JavaScript-Gaming");
+      await expect(page.locator("#executeBtn")).toBeEnabled();
+      await expect(page.locator("#repoSelectedValue")).toHaveText(server.repoRoot);
+      await expect(page.locator("#pickRepoBtn")).toBeHidden();
       await expect(page.locator("#workspaceContextValue")).toHaveCount(0);
       await expect(page.locator("#repoDestinationContent")).not.toContainText("Workspace launch");
       await expect(page.locator("#targetTypeGames")).toBeChecked();
@@ -534,10 +539,13 @@ 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("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")).toContainText(`Workspace repoPath available: ${server.repoRoot}.`);
+      await expect(page.locator("#log")).toContainText(`Resolved repoPath: ${server.repoRoot}`);
+      await expect(page.locator("#log")).toContainText(`Resolved absolute preview output path: ${absoluteAsteroidsPreviewPath}`);
+      await expect(page.locator("#log")).not.toContainText("Direct preview write unavailable");
       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");
@@ -552,9 +560,21 @@ 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")).toBeDisabled();
-      expect(server.previewWrites.size).toBe(0);
-      expect(server.previewAbsoluteWrites.size).toBe(0);
+      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 page.locator("#returnToWorkspaceButton").click();
       await expect(page).toHaveURL(/workspace-manager-v2\/index\.html\?hostContextId=workspace-manager-v2-/);
       expect(pageErrors).toEqual([]);
@@ -607,6 +627,7 @@ test.describe("Workspace Manager V2 bootstrap", () => {
     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";
+    delete displayRootManifest.repoPath;
 
     page.on("pageerror", (error) => {
       pageErrors.push(error.message);
@@ -620,12 +641,14 @@ test.describe("Workspace Manager V2 bootstrap", () => {
 
     try {
       await expect(page.locator("#repoSelectedValue")).toHaveText("HTML-JavaScript-Gaming");
+      await expect(page.locator("#pickRepoBtn")).toBeHidden();
       await expect(page.locator("#executeBtn")).toBeDisabled();
       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")).toContainText("Workspace repoPath missing.");
+      await expect(page.locator("#log")).toContainText("WARN Manifest repoPath is missing or invalid for workspace launch; repoRoot is display-only: HTML-JavaScript-Gaming.");
+      await expect(page.locator("#log")).toContainText("Direct preview write unavailable until manifest repoPath is an absolute filesystem path.");
       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);
@@ -664,13 +687,15 @@ test.describe("Workspace Manager V2 bootstrap", () => {
 
       await page.locator("#activeGameSelect").selectOption("GravityWell");
       await expect(page.locator("#activeGameSummary")).toContainText("games/GravityWell/");
+      await expect(page.locator("#activeGameSummary")).toContainText("Select Repo");
       await expect(page.locator("#workspaceContextOutput")).toHaveValue(/"gameRoot": "games\/GravityWell\/"/);
       await expect(page.locator("#workspaceContextOutput")).toHaveValue(/"assetsPath": "games\/GravityWell\/assets"/);
       await expect(page.locator("#workspaceContextOutput")).toHaveValue(/"assets.image.preview.preview"/);
       await expect(page.locator("#workspaceContextOutput")).not.toHaveValue(/"assets.image.background.preview"/);
       await expect(page.locator("#workspaceContextOutput")).not.toHaveValue(/"asset-browser"|"palette-browser"|"vector-map-editor"/);
       await expect(page.locator('[data-workspace-tool-id="asset-manager-v2"]')).toContainText("1 managed assets");
       await expect(page.locator('[data-workspace-tool-id="palette-manager-v2"]')).toContainText("10 palette swatches");
+      await expect(page.locator('[data-workspace-tool-id="preview-generator-v2"]')).toContainText("Select Repo");
       const gravityManifest = JSON.parse(await page.locator("#workspaceContextOutput").inputValue());
       expect(Object.keys(gravityManifest.tools).sort()).toEqual(["asset-manager-v2", "palette-manager-v2"]);
       expect(gravityManifest.tools["asset-manager-v2"].assets["assets.image.preview.preview"]).toEqual({
@@ -684,13 +709,15 @@ test.describe("Workspace Manager V2 bootstrap", () => {
 
       await page.locator("#activeGameSelect").selectOption("Pong");
       await expect(page.locator("#activeGameSummary")).toContainText("games/Pong/");
+      await expect(page.locator("#activeGameSummary")).toContainText("Select Repo");
       await expect(page.locator("#workspaceContextOutput")).toHaveValue(/"gameRoot": "games\/Pong\/"/);
       await expect(page.locator("#workspaceContextOutput")).toHaveValue(/"assetsPath": "games\/Pong\/assets"/);
       await expect(page.locator("#workspaceContextOutput")).toHaveValue(/"assets.image.preview.preview"/);
       await expect(page.locator("#workspaceContextOutput")).not.toHaveValue(/"assets.image.background.preview"/);
       await expect(page.locator("#workspaceContextOutput")).not.toHaveValue(/"asset-browser"|"palette-browser"|"vector-map-editor"/);
       await expect(page.locator('[data-workspace-tool-id="asset-manager-v2"]')).toContainText("1 managed assets");
       await expect(page.locator('[data-workspace-tool-id="palette-manager-v2"]')).toContainText("8 palette swatches");
+      await expect(page.locator('[data-workspace-tool-id="preview-generator-v2"]')).toContainText("Select Repo");
       const pongManifest = JSON.parse(await page.locator("#workspaceContextOutput").inputValue());
       expect(Object.keys(pongManifest.tools).sort()).toEqual(["asset-manager-v2", "palette-manager-v2"]);
       expect(pongManifest.tools["asset-manager-v2"].assets["assets.image.preview.preview"]).toEqual({
@@ -792,7 +819,7 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator('[data-workspace-tool-id="asset-manager-v2"]')).toContainText("0 managed assets");
       await expect(page.locator('[data-workspace-tool-id="workspace-manager-v2"]')).toHaveCount(0);
       await expect(page.locator('[data-workspace-tool-id="palette-manager-v2"]')).toContainText("3 palette swatches");
-      await expect(page.locator('[data-workspace-tool-id="preview-generator-v2"]')).toContainText("Schema-valid manifest");
+      await expect(page.locator('[data-workspace-tool-id="preview-generator-v2"]')).toContainText("Select Repo");
       await expect(page.locator("#workspaceContextOutput")).toHaveValue(/"id": "workspace-manager-v2-UAT-template"/);
       await expect(page.locator("#workspaceContextOutput")).toHaveValue(/"gameRoot": "games\/_template\/"/);
       await expect(page.locator("#workspaceContextOutput")).toHaveValue(/"assetsPath": "games\/_template\/assets"/);

tools/asset-manager-v2/js/services/WorkspaceBridge.js

@@ -74,7 +74,7 @@ export class WorkspaceBridge {
       return { ok: false, message: "Workspace Manager V2 launch no longer accepts wrapper context JSON." };
     }
     const unsupportedManifestKeys = Object.keys(workspaceManifest)
-      .filter((key) => !["$schema", "documentKind", "schema", "version", "id", "name", "gameId", "gameRoot", "assetsPath", "repoRoot", "tools"].includes(key));
+      .filter((key) => !["$schema", "documentKind", "schema", "version", "id", "name", "gameId", "gameRoot", "assetsPath", "repoRoot", "repoPath", "tools"].includes(key));
     if (unsupportedManifestKeys.length) {
       return { ok: false, message: `Workspace Manager V2 manifest includes fields not allowed by the workspace manifest schema: ${unsupportedManifestKeys.join(", ")}.` };
     }