Add overwrite action to saved session cards and complete Session Library lifecycle - PR_11_270

DavidQ · DavidQ · commit 8637300b2a44 · 2026-05-02T12:55:44.000-04:00
diff --git a/docs/dev/reports/PR_11_270_workspace_v2_session_library_overwrite_action_report.md b/docs/dev/reports/PR_11_270_workspace_v2_session_library_overwrite_action_report.md
@@ -0,0 +1,52 @@
+# PR_11_270 Workspace V2 Session Library Overwrite Action Report
+
+## Scope
+Workspace V2 Session Library only.
+
+## Files Changed
+- tools/workspace-v2/index.js
+- tests/runtime/V2SessionLibraryCardOverwrite.test.mjs
+- tests/runtime/V2SessionLibraryActionCleanup.test.mjs
+- tests/runtime/V2SessionLibraryActions.test.mjs
+- docs/pr/PLAN_PR_11_270_WORKSPACE_V2_SESSION_LIBRARY_OVERWRITE_ACTION.md
+- docs/pr/BUILD_PR_11_270_WORKSPACE_V2_SESSION_LIBRARY_OVERWRITE_ACTION.md
+- docs/dev/reports/PR_11_270_workspace_v2_session_library_overwrite_action_report.md
+
+## Implementation Summary
+- Added card-level `Overwrite` button for each saved session entry.
+- Overwrite button enablement is active-session-gated:
+  - enabled only when active Workspace V2 session exists
+  - disabled otherwise
+- Added `overwriteSavedSessionById(sessionId)` row-authoritative action:
+  - requires existing saved session ID
+  - requires active Workspace V2 session payload
+  - replaces saved payload for that exact ID
+  - does not create a new saved session ID
+  - keeps saved session listed in place
+  - emits confirmation: `Saved session updated.`
+- Save behavior remains NEW-only:
+  - duplicate IDs blocked via Save
+  - overwrite is now available on saved-session cards
+
+## Validation Commands
+1. `node --check tools/workspace-v2/index.js`
+   - PASS
+2. `node --check tests/runtime/V2SessionLibraryCardOverwrite.test.mjs`
+   - PASS
+3. `node --check tests/runtime/V2SessionLibraryActionCleanup.test.mjs`
+   - PASS
+4. `node --check tests/runtime/V2SessionLibraryActions.test.mjs`
+   - PASS
+5. `node tests/runtime/V2SessionLibraryCardOverwrite.test.mjs`
+   - PASS
+   - Results: `tmp/v2-session-library-card-overwrite-results.json`
+6. `node tests/runtime/V2SessionLibraryActionCleanup.test.mjs`
+   - PASS
+   - Results: `tmp/v2-session-library-action-cleanup-results.json`
+7. `node tests/runtime/V2SessionLibraryActions.test.mjs`
+   - PASS
+   - Results: `tmp/v2-session-library-actions-results.json`
+
+## Full Samples Smoke Decision
+- Skipped full samples smoke test.
+- Reason: changes are restricted to Workspace V2 Session Library row action behavior and covered by targeted runtime tests.
diff --git a/docs/pr/BUILD_PR_11_270_WORKSPACE_V2_SESSION_LIBRARY_OVERWRITE_ACTION.md b/docs/pr/BUILD_PR_11_270_WORKSPACE_V2_SESSION_LIBRARY_OVERWRITE_ACTION.md
@@ -0,0 +1,34 @@
+# BUILD_PR_11_270_WORKSPACE_V2_SESSION_LIBRARY_OVERWRITE_ACTION
+
+## Purpose
+Implement card-level overwrite for existing saved sessions in Workspace V2 Session Library.
+
+## Files
+- tools/workspace-v2/index.js
+- tests/runtime/V2SessionLibraryCardOverwrite.test.mjs
+- tests/runtime/V2SessionLibraryActionCleanup.test.mjs
+- tests/runtime/V2SessionLibraryActions.test.mjs
+- docs/dev/reports/PR_11_270_workspace_v2_session_library_overwrite_action_report.md
+
+## Implementation
+1. Add `Overwrite` button to each saved session card.
+2. Gate row overwrite button enablement on active Workspace V2 session availability.
+3. Add `overwriteSavedSessionById(sessionId)` for row-authoritative overwrite behavior.
+4. Preserve existing session ID; replace saved payload only.
+5. Keep Save path new-only and duplicate-ID-blocked.
+6. Emit `Saved session updated.` on successful overwrite.
+
+## Acceptance
+- Card-level overwrite exists and is active-session-gated.
+- Overwrite updates saved payload in place with no new ID creation.
+- Save remains new-only; duplicate IDs blocked on Save.
+- Status text is current-state and non-stale.
+
+## Validation
+- node --check tools/workspace-v2/index.js
+- node --check tests/runtime/V2SessionLibraryCardOverwrite.test.mjs
+- node --check tests/runtime/V2SessionLibraryActionCleanup.test.mjs
+- node --check tests/runtime/V2SessionLibraryActions.test.mjs
+- node tests/runtime/V2SessionLibraryCardOverwrite.test.mjs
+- node tests/runtime/V2SessionLibraryActionCleanup.test.mjs
+- node tests/runtime/V2SessionLibraryActions.test.mjs
diff --git a/docs/pr/PLAN_PR_11_270_WORKSPACE_V2_SESSION_LIBRARY_OVERWRITE_ACTION.md b/docs/pr/PLAN_PR_11_270_WORKSPACE_V2_SESSION_LIBRARY_OVERWRITE_ACTION.md
@@ -0,0 +1,33 @@
+# PLAN_PR_11_270_WORKSPACE_V2_SESSION_LIBRARY_OVERWRITE_ACTION
+
+## Purpose
+Add a saved-session card overwrite action in Workspace V2 Session Library, aligned with new-only Save rules.
+
+## Scope
+- tools/workspace-v2/index.js
+- tests/runtime/V2SessionLibraryCardOverwrite.test.mjs
+- tests/runtime/V2SessionLibraryActionCleanup.test.mjs
+- tests/runtime/V2SessionLibraryActions.test.mjs
+- docs/report only
+
+## Goals
+- Add `Overwrite` on each saved session card.
+- Enable overwrite only when active Workspace V2 session exists.
+- Overwrite replaces payload for that saved session ID only.
+- Overwrite does not create new session ID or duplicate entry.
+- Show exact confirmation: `Saved session updated.`
+- Keep Save new-only and duplicate-save blocked.
+
+## Out of Scope
+- No schema changes
+- No merge/diff algorithm changes
+- No cross-tool changes
+
+## Validation
+- node --check tools/workspace-v2/index.js
+- node --check tests/runtime/V2SessionLibraryCardOverwrite.test.mjs
+- node --check tests/runtime/V2SessionLibraryActionCleanup.test.mjs
+- node --check tests/runtime/V2SessionLibraryActions.test.mjs
+- node tests/runtime/V2SessionLibraryCardOverwrite.test.mjs
+- node tests/runtime/V2SessionLibraryActionCleanup.test.mjs
+- node tests/runtime/V2SessionLibraryActions.test.mjs
diff --git a/tests/runtime/V2SessionLibraryActionCleanup.test.mjs b/tests/runtime/V2SessionLibraryActionCleanup.test.mjs
@@ -54,6 +54,7 @@ export function run() {
     'this.setLibraryStatus("That session ID already exists. Use the saved session card to Load, Overwrite, or Delete it.");',
     'Saved session created. Manage this session from its Saved Sessions card.',
     'loadButton.textContent = "Load";',
+    'overwriteButton.textContent = "Overwrite";',
     'deleteSavedButton.textContent = "Delete Saved";',
     'useInLibraryButton.textContent = "Use in Diff/Merge";'
   ];
diff --git a/tests/runtime/V2SessionLibraryActions.test.mjs b/tests/runtime/V2SessionLibraryActions.test.mjs
@@ -137,6 +137,7 @@ export function run() {
     "No active Workspace V2 session is available to overwrite from.",
     "Saved session not found. Use Save Session to create it first.",
     "Saved session overwritten.",
+    "Saved session updated.",
     "Enter a saved session ID before loading.",
     "Saved session loaded.",
     "Enter a saved session ID before deleting.",
diff --git a/tests/runtime/V2SessionLibraryCardOverwrite.test.mjs b/tests/runtime/V2SessionLibraryCardOverwrite.test.mjs
@@ -0,0 +1,112 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = path.resolve(__dirname, "..", "..");
+const jsPath = path.join(repoRoot, "tools", "workspace-v2", "index.js");
+const testPath = path.join(repoRoot, "tests", "runtime", "V2SessionLibraryCardOverwrite.test.mjs");
+const resultsPath = path.join(repoRoot, "tmp", "v2-session-library-card-overwrite-results.json");
+
+function checkSyntax(filePath) {
+  try {
+    execFileSync(process.execPath, ["--check", filePath], {
+      cwd: repoRoot,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    return { ok: true, error: "" };
+  } catch (error) {
+    return { ok: false, error: (error?.stderr || error?.stdout || error?.message || "").toString().trim() };
+  }
+}
+
+function overwriteSavedSession(library, sessionId, activePayload) {
+  const next = JSON.parse(JSON.stringify(library));
+  if (!sessionId || !Object.prototype.hasOwnProperty.call(next, sessionId)) {
+    return { ok: false, message: "Saved session not found. Use Save Session to create it first.", library: next };
+  }
+  if (!activePayload || typeof activePayload !== "object" || Array.isArray(activePayload)) {
+    return { ok: false, message: "No active Workspace V2 session is available to overwrite from.", library: next };
+  }
+  next[sessionId] = JSON.parse(JSON.stringify(activePayload));
+  return { ok: true, message: "Saved session updated.", library: next };
+}
+
+export function run() {
+  const failures = [];
+  const jsExists = fs.existsSync(jsPath);
+  const js = jsExists ? fs.readFileSync(jsPath, "utf8") : "";
+  const jsSyntax = checkSyntax(jsPath);
+  const testSyntax = checkSyntax(testPath);
+
+  if (!jsExists) failures.push("Missing tools/workspace-v2/index.js.");
+  if (!jsSyntax.ok) failures.push("tools/workspace-v2/index.js failed syntax check.");
+  if (!testSyntax.ok) failures.push("tests/runtime/V2SessionLibraryCardOverwrite.test.mjs failed syntax check.");
+
+  const requiredTokens = [
+    "overwriteButton.textContent = \"Overwrite\";",
+    "overwriteButton.disabled = !canOverwriteFromActiveSession;",
+    "overwriteSavedSessionById(sessionId)",
+    "No active Workspace V2 session is available to overwrite from.",
+    "Saved session updated."
+  ];
+  requiredTokens.forEach((token) => {
+    if (!js.includes(token)) failures.push(`Missing overwrite-card token/text: ${token}`);
+  });
+
+  const initialLibrary = {
+    "saved-1": { version: "v2", toolId: "palette-manager-v2", payloadJson: { original: true } },
+    "saved-2": { version: "v2", toolId: "asset-browser-v2", payloadJson: { untouched: true } }
+  };
+  const activePayload = { version: "v2", toolId: "palette-manager-v2", payloadJson: { updated: true } };
+
+  const noActive = overwriteSavedSession(initialLibrary, "saved-1", null);
+  if (noActive.ok || noActive.message !== "No active Workspace V2 session is available to overwrite from.") {
+    failures.push("Overwrite should be blocked without active session.");
+  }
+
+  const missingSaved = overwriteSavedSession(initialLibrary, "missing-id", activePayload);
+  if (missingSaved.ok || missingSaved.message !== "Saved session not found. Use Save Session to create it first.") {
+    failures.push("Overwrite should require an existing saved session ID.");
+  }
+
+  const overwritten = overwriteSavedSession(initialLibrary, "saved-1", activePayload);
+  if (!overwritten.ok || overwritten.message !== "Saved session updated.") {
+    failures.push("Overwrite should succeed and return update confirmation.");
+  }
+  if (!overwritten.library["saved-1"] || overwritten.library["saved-1"].payloadJson?.updated !== true) {
+    failures.push("Overwrite should replace saved payload with active payload.");
+  }
+  if (Object.keys(overwritten.library).length !== Object.keys(initialLibrary).length) {
+    failures.push("Overwrite should not create a new saved session entry.");
+  }
+  if (overwritten.library["saved-2"].payloadJson?.untouched !== true) {
+    failures.push("Overwrite should not mutate other saved session entries.");
+  }
+
+  fs.mkdirSync(path.dirname(resultsPath), { recursive: true });
+  fs.writeFileSync(resultsPath, `${JSON.stringify({
+    generatedAt: new Date().toISOString(),
+    failures,
+    checks: { jsExists, jsSyntax, testSyntax },
+    scenarios: { noActive, missingSaved, overwritten }
+  }, null, 2)}
+`, "utf8");
+
+  console.log(`v2 session-library-card-overwrite results: ${resultsPath}`);
+  assert.equal(failures.length, 0, `V2 session-library-card-overwrite failures: ${failures.join(" | ")}`);
+  return { failures };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const summary = run();
+    console.log(JSON.stringify(summary, null, 2));
+  } catch (error) {
+    console.error(error);
+    process.exitCode = 1;
+  }
+}
diff --git a/tools/workspace-v2/index.js b/tools/workspace-v2/index.js
@@ -986,6 +986,7 @@ class WorkspaceV2SessionProducer {
     this.sessionListNode.replaceChildren();
     this.libraryEmptyState.hidden = sessionNames.length > 0;
     this.libraryEmptyState.textContent = "No saved sessions in library.";
+    const canOverwriteFromActiveSession = this.hasActiveWorkspaceSessionForSave();
     sessionNames.forEach((sessionName) => {
       const item = document.createElement("li");
       const payload = library[sessionName];
@@ -996,6 +997,7 @@ class WorkspaceV2SessionProducer {
       const copyIdButton = document.createElement("button");
       const useInLibraryButton = document.createElement("button");
       const loadButton = document.createElement("button");
+      const overwriteButton = document.createElement("button");
       const deleteSavedButton = document.createElement("button");
       const readableLabel = payload && typeof payload.toolId === "string" && payload.toolId.trim()
         ? payload.toolId.trim()
@@ -1020,12 +1022,18 @@ class WorkspaceV2SessionProducer {
       loadButton.addEventListener("click", () => {
         this.loadSavedSessionById(sessionName);
       });
+      overwriteButton.type = "button";
+      overwriteButton.textContent = "Overwrite";
+      overwriteButton.disabled = !canOverwriteFromActiveSession;
+      overwriteButton.addEventListener("click", () => {
+        this.overwriteSavedSessionById(sessionName);
+      });
       deleteSavedButton.type = "button";
       deleteSavedButton.textContent = "Delete Saved";
       deleteSavedButton.addEventListener("click", () => {
         this.deleteSavedSessionById(sessionName);
       });
-      item.append(label, idLine, copyIdButton, useInLibraryButton, loadButton, deleteSavedButton);
+      item.append(label, idLine, copyIdButton, useInLibraryButton, loadButton, overwriteButton, deleteSavedButton);
       this.sessionListNode.appendChild(item);
     });
     this.renderSessionDiffInputs();
@@ -1073,6 +1081,30 @@ class WorkspaceV2SessionProducer {
     this.renderSessionLibrary();
   }
 
+  overwriteSavedSessionById(sessionId) {
+    if (typeof sessionId !== "string" || !sessionId.trim()) {
+      this.setLibraryStatus("Enter a saved session ID before overwriting.");
+      return;
+    }
+    const activePayload = this.readActiveSessionPayloadForLibraryActions();
+    if (!this.isValidSessionPayload(activePayload)) {
+      this.setLibraryStatus("No active Workspace V2 session is available to overwrite from.");
+      return;
+    }
+    const library = this.readSessionLibrary();
+    if (library === null) {
+      return;
+    }
+    if (!Object.prototype.hasOwnProperty.call(library, sessionId.trim())) {
+      this.setLibraryStatus("Saved session not found. Use Save Session to create it first.");
+      return;
+    }
+    library[sessionId.trim()] = activePayload;
+    this.writeSessionLibrary(library);
+    this.renderSessionLibrary();
+    this.setLibraryStatus("Saved session updated.");
+  }
+
   deleteSavedSessionById(sessionId) {
     if (typeof sessionId !== "string" || !sessionId.trim()) {
       this.setLibraryStatus("Enter a saved session ID before deleting.");
