Fix Admin Operations export and backup action feedback - PR_26168_245-admin-operations-action-feedback-fix & Add server-side Postgres backup foundation for Admin Operations - PR_26168_245-postgres-backup-foundation

Author: ToolboxAid

.env.example

@@ -18,6 +18,7 @@ GAMEFOUNDRY_SUPABASE_ANON_KEY=
 # Do not expose these values to browser JavaScript, HTML, reports, or screenshots.
 GAMEFOUNDRY_SUPABASE_SERVICE_ROLE_KEY=
 GAMEFOUNDRY_DATABASE_URL=
+GAMEFOUNDRY_DB_BACKUP_DIR=
 
 # Server-only project asset storage configuration.
 # Browser uploads must go through the server API and must not receive these secrets.

assets/theme-v2/js/admin-operations.js

@@ -146,6 +146,64 @@ class AdminOperationsController {
         this.resultRows.prepend(row);
     }
 
+    artifactForResult(result = {}) {
+        if (result.actionId === "export-project-package") {
+            return {
+                bytesBase64: result.package?.packageBytesBase64,
+                fileName: result.package?.filename,
+                missingMessage: "Export Project Package completed without downloadable .gfsp package bytes. Restore the Local API package response before retrying.",
+                mimeType: "application/octet-stream",
+            };
+        }
+        return null;
+    }
+
+    decodeBase64(base64Value) {
+        const binary = atob(base64Value);
+        const bytes = new Uint8Array(binary.length);
+        for (let index = 0; index < binary.length; index += 1) {
+            bytes[index] = binary.charCodeAt(index);
+        }
+        return bytes;
+    }
+
+    downloadArtifact(artifact) {
+        if (!artifact?.fileName || !artifact?.bytesBase64) {
+            throw new Error(artifact?.missingMessage || "Downloadable artifact bytes were not returned.");
+        }
+        const blob = new Blob([this.decodeBase64(artifact.bytesBase64)], { type: artifact.mimeType || "application/octet-stream" });
+        const url = URL.createObjectURL(blob);
+        const link = document.createElement("a");
+        link.download = artifact.fileName;
+        link.href = url;
+        link.rel = "noopener";
+        document.body.append(link);
+        link.click();
+        link.remove();
+        window.setTimeout(() => URL.revokeObjectURL(url), 0);
+    }
+
+    applyArtifactFeedback(result = {}) {
+        const artifact = this.artifactForResult(result);
+        if (!artifact || result.status !== "PASS" || result.executed !== true) {
+            return result;
+        }
+        try {
+            this.downloadArtifact(artifact);
+            return {
+                ...result,
+                message: `${result.message || "Admin operation completed."} Download started: ${artifact.fileName}.`,
+            };
+        } catch (error) {
+            return {
+                ...result,
+                executed: false,
+                message: error instanceof Error ? error.message : "Artifact download failed before it could start.",
+                status: "FAIL",
+            };
+        }
+    }
+
     async readFileAsBase64(file) {
         const bytes = new Uint8Array(await file.arrayBuffer());
         const chunkSize = 32768;
@@ -210,11 +268,19 @@ class AdminOperationsController {
         try {
             this.setStatus("SKIP", `Running ${action.label || action.id || "Admin Operation"} through the Local API.`);
             const options = await this.collectActionOptions(action);
-            const result = runAdminOperationAction(action.id, options);
+            const result = this.applyArtifactFeedback(runAdminOperationAction(action.id, options));
             this.appendResult(result);
             this.setStatus(result.status || "SKIP", result.message || "Admin operation returned no message.");
         } catch (error) {
-            this.setStatus("FAIL", error instanceof Error ? error.message : "Admin operation failed.");
+            const result = {
+                actionId: action.id,
+                actionLabel: action.label,
+                executed: false,
+                message: error instanceof Error ? error.message : "Admin operation failed.",
+                status: "FAIL",
+            };
+            this.appendResult(result);
+            this.setStatus(result.status, result.message);
         }
     }
 }

docs_build/dev/reports/PR_26168_245-postgres-backup-foundation.md

@@ -0,0 +1,57 @@
+# PR_26168_245-postgres-backup-foundation
+
+## Branch Validation
+- PASS: Current branch was `main`.
+- Expected branch: `main`.
+- Local branches found: `main`.
+
+## Summary
+- Create Backup now routes through Admin Operations to the Local API and runs a server-side Postgres backup foundation.
+- The Local API validates the configured database connection with a lightweight Postgres query before attempting backup.
+- Backup execution uses `pg_dump --format=custom` and writes to `GAMEFOUNDRY_DB_BACKUP_DIR` on the server side.
+- Backup filenames use `gamefoundry-<environment>-db-<YYJJJ>-<sequence>.dump`.
+- Browser backup downloads/storage were removed from Create Backup; the UI shows the Local API PASS/FAIL result only.
+- Restore From Backup is guarded scaffold-only and does not apply browser-uploaded backup data.
+
+## Requirement Checklist
+- PASS: Hard stop guard passed on `main`.
+- PASS: Admin Operations Create Backup button calls the Local API action route.
+- PASS: Local API Create Backup validates DB connection before `pg_dump`.
+- PASS: Local API backup service runs `pg_dump --format=custom` for backups.
+- PASS: Backup filename format implemented as `gamefoundry-<environment>-db-<YYJJJ>-<sequence>.dump`.
+- PASS: Backup output is directed to `GAMEFOUNDRY_DB_BACKUP_DIR`; repo `tmp/` backup targets are rejected.
+- PASS: `.env.example` includes `GAMEFOUNDRY_DB_BACKUP_DIR=`.
+- PASS: `.env.dev`, `.env.ist`, `.env.uat`, and `.env.prd` were updated locally with `GAMEFOUNDRY_DB_BACKUP_DIR=`; they are gitignored and contain private values, so they are not included in review artifacts or ZIP output.
+- PASS: No real backup files or `.dump` files were created in the repo.
+- PASS: Missing `GAMEFOUNDRY_DB_BACKUP_DIR` returns visible FAIL diagnostics.
+- PASS: Missing `pg_dump` returns visible FAIL diagnostics.
+- PASS: Successful backup reports PASS with filename, size, and timestamp.
+- PASS: DB passwords and secrets are not exposed in UI results, reports, command args, or ZIP artifacts.
+- PASS: Restore From Backup remains guarded scaffold-only.
+- PASS: Export Project Package still shows visible feedback and fails visibly if package bytes are missing.
+- PASS: No inline scripts, inline styles, style blocks, script blocks, or inline event handlers were added.
+- PASS: No unrelated import, migration, reseed, or Project Workspace behavior was added.
+
+## Validation Lane Report
+- PASS: `node --check src/dev-runtime/database/postgres-backup-service.mjs`
+- PASS: `node --check src/dev-runtime/server/local-api-router.mjs`
+- PASS: `node --check assets/theme-v2/js/admin-operations.js`
+- PASS: `node --check tests/dev-runtime/PostgresBackupService.test.mjs`
+- PASS: `node --check tests/playwright/tools/AdminPlatformToolsWireframes.spec.mjs`
+- PASS: `rg --pcre2 -n "<script(?![^>]+src=)|<style|\s(onclick|onchange|oninput|onsubmit|onkeydown|onkeyup|onload)=" admin/operations.html` returned no matches.
+- PASS: `node --test tests/dev-runtime/PostgresBackupService.test.mjs`
+  - 5 passed.
+  - Covered filename format, missing backup dir, unavailable `pg_dump`, repo `tmp/` rejection, and successful custom-format dump command construction.
+- PASS: `npx playwright test tests/playwright/tools/AdminPlatformToolsWireframes.spec.mjs --grep "Admin Operations" --reporter=line`
+  - 4 passed.
+  - Covered Create Backup visible PASS/FAIL behavior, Export Project Package visible feedback, no silent no-op behavior, no secret exposure, Admin Operations section order, DEV reseed gating, and non-admin access blocking.
+- PASS: Playwright V8 coverage report generated at `docs_build/dev/reports/playwright_v8_coverage_report.txt`.
+
+## Manual Validation Notes
+- Create Backup success path now reports the server-side `.dump` filename, byte size, timestamp, and current environment.
+- Create Backup failure paths are visible and actionable for missing backup directory, disallowed repo `tmp/` target, unavailable `pg_dump`, invalid database config, failed database connection validation, and failed `pg_dump`.
+- The service passes the DB password to `pg_dump` through `PGPASSWORD`; it is not included in command arguments or browser-visible results.
+- Actual live backup creation requires a real `.env` with `GAMEFOUNDRY_DB_BACKUP_DIR`, a reachable Postgres database, and PostgreSQL client tools installed on the Local API host.
+
+## Full Samples Decision
+- SKIP: Full samples smoke was not run because this PR only changes Admin Operations backup feedback, Local API backup service behavior, env placeholders, and targeted tests. No sample JSON or sample runtime surface was touched.

docs_build/dev/reports/codex_changed_files.txt

@@ -1,54 +1,26 @@
 # git status --short
-M admin/infrastructure.html
- M admin/operations.html
- M assets/theme-v2/js/admin-infrastructure.js
+M .env.example
  M assets/theme-v2/js/admin-operations.js
- M assets/theme-v2/js/gamefoundry-partials.js
- M docs_build/codex/decisions/project-packages.md
  M docs_build/dev/reports/codex_changed_files.txt
  M docs_build/dev/reports/codex_review.diff
  M docs_build/dev/reports/playwright_v8_coverage_report.txt
  M src/dev-runtime/server/local-api-router.mjs
- M src/engine/api/admin-operations-api-client.js
  M tests/playwright/tools/AdminPlatformToolsWireframes.spec.mjs
- M tests/playwright/tools/GameWorkspaceMockRepository.spec.mjs
- M toolbox/game-workspace/game-workspace.js
- M toolbox/game-workspace/index.html
-?? docs_build/dev/reports/PR_26168_237-admin-ia-cleanup.md
-?? docs_build/dev/reports/PR_26168_238-r2-assets-end-to-end-validation.md
-?? docs_build/dev/reports/PR_26168_239-gfsp-package-foundation.md
-?? docs_build/dev/reports/PR_26168_240-project-package-export.md
-?? docs_build/dev/reports/PR_26168_241-project-package-validation.md
-?? docs_build/dev/reports/PR_26168_242-project-package-import.md
-?? docs_build/dev/reports/PR_26168_243-backup-recovery-foundation.md
-?? docs_build/dev/reports/PR_26168_244-project-workspace-real-project-flow.md
-?? src/dev-runtime/project-packages/
+?? docs_build/dev/reports/PR_26168_245-postgres-backup-foundation.md
+?? src/dev-runtime/database/
+?? tests/dev-runtime/PostgresBackupService.test.mjs
 
 # git ls-files --others --exclude-standard
-docs_build/dev/reports/PR_26168_237-admin-ia-cleanup.md
-docs_build/dev/reports/PR_26168_238-r2-assets-end-to-end-validation.md
-docs_build/dev/reports/PR_26168_239-gfsp-package-foundation.md
-docs_build/dev/reports/PR_26168_240-project-package-export.md
-docs_build/dev/reports/PR_26168_241-project-package-validation.md
-docs_build/dev/reports/PR_26168_242-project-package-import.md
-docs_build/dev/reports/PR_26168_243-backup-recovery-foundation.md
-docs_build/dev/reports/PR_26168_244-project-workspace-real-project-flow.md
-src/dev-runtime/project-packages/project-package-service.mjs
+docs_build/dev/reports/PR_26168_245-postgres-backup-foundation.md
+src/dev-runtime/database/postgres-backup-service.mjs
+tests/dev-runtime/PostgresBackupService.test.mjs
 
 # git diff --stat
-admin/infrastructure.html                          |   28 +-
- admin/operations.html                              |    8 +-
- assets/theme-v2/js/admin-infrastructure.js         |   42 +-
- assets/theme-v2/js/admin-operations.js             |  107 +-
- assets/theme-v2/js/gamefoundry-partials.js         |    3 -
- docs_build/codex/decisions/project-packages.md     |   24 +
- docs_build/dev/reports/codex_changed_files.txt     |  125 +-
- docs_build/dev/reports/codex_review.diff           | 4579 +++++++++++---------
- .../dev/reports/playwright_v8_coverage_report.txt  |   37 +-
- src/dev-runtime/server/local-api-router.mjs        |  361 +-
- src/engine/api/admin-operations-api-client.js      |    4 +-
- .../tools/AdminPlatformToolsWireframes.spec.mjs    |  155 +-
- .../tools/GameWorkspaceMockRepository.spec.mjs     |   15 +-
- toolbox/game-workspace/game-workspace.js           |   11 +-
- toolbox/game-workspace/index.html                  |   10 +-
- 15 files changed, 3314 insertions(+), 2195 deletions(-)
+.env.example                                       |    1 +
+ assets/theme-v2/js/admin-operations.js             |   70 +-
+ docs_build/dev/reports/codex_changed_files.txt     |   54 +-
+ docs_build/dev/reports/codex_review.diff           | 7098 +-------------------
+ .../dev/reports/playwright_v8_coverage_report.txt  |   48 +-
+ src/dev-runtime/server/local-api-router.mjs        |  126 +-
+ .../tools/AdminPlatformToolsWireframes.spec.mjs    |  156 +-
+ 7 files changed, 606 insertions(+), 6947 deletions(-)