Fix Tags API setup error handling

Author: ToolboxAid

docs_build/dev/reports/PR_26178_ALFA_001-fix-tags-local-api-crash_branch-validation.md

@@ -0,0 +1,19 @@
+# PR_26178_ALFA_001 Branch Validation
+
+## Gate Results
+- Current branch: PASS - PR_26178_ALFA_001-fix-tags-local-api-crash
+- Started from main: PASS - branch was created after main was fast-forwarded from origin/main.
+- Worktree scope: PASS - only Tags service, Tags service test, and required reports are changed.
+- start_of_day unchanged: PASS.
+
+## Validation Result
+- PR-scoped branch validation: PASS.
+
+## Commands
+- `node --check src/dev-runtime/toolbox-api/alfa-tool-services.mjs` - PASS
+- `node --check tests/dev-runtime/TagsApiService.test.mjs` - PASS
+- `node ./scripts/run-node-test-files.mjs tests/dev-runtime/TagsApiService.test.mjs` - PASS
+
+## Out-of-Scope Observation
+- `node ./scripts/run-node-test-files.mjs tests/dev-runtime/DevRuntimeBoundary.test.mjs` - FAIL on an existing router assertion for `parts[1] === "local-db"`.
+- No code in this branch changes that router route, so it is documented as an unrelated validation observation.

docs_build/dev/reports/PR_26178_ALFA_001-fix-tags-local-api-crash_manual-validation-notes.md

@@ -0,0 +1,15 @@
+# PR_26178_ALFA_001 Manual Validation Notes
+
+## Review Notes
+- Confirmed the Tags read path remains server/API owned and still requires the configured API database adapter.
+- Confirmed no Tags page, browser-owned product data, local storage product source, MEM DB, or page-local product arrays were added.
+- Confirmed the public failure message no longer exposes raw missing-table details such as `relation "project_tags" does not exist`.
+- Confirmed the operator diagnostic still carries the raw cause for developer troubleshooting.
+
+## Expected Manual Behavior
+- With the Tags database schema applied, opening Tags and invoking the repository snapshot/list path should load seeded flat Tags from the API database.
+- If account, Game Hub, or Tags database setup is missing, Tags API requests should fail with a 503 setup message telling the operator to verify the API database connection and apply setup.
+- The service should not return fake data or silently treat missing schema as an empty Tags list.
+
+## Packaging
+- Repo-structured delta ZIP: `tmp/PR_26178_ALFA_001-fix-tags-local-api-crash_delta.zip`

docs_build/dev/reports/PR_26178_ALFA_001-fix-tags-local-api-crash_report.md

@@ -0,0 +1,27 @@
+# PR_26178_ALFA_001-fix-tags-local-api-crash Report
+
+## Scope
+- Branch: PR_26178_ALFA_001-fix-tags-local-api-crash
+- Purpose: recover the Tags API service read path so `listTags` does not crash Node when `readTables` encounters missing API database setup.
+- Runtime boundary: Browser -> API -> Database remains the only active product-data path.
+
+## Changes
+- Added `TagsApiSetupError` wrapping in `src/dev-runtime/toolbox-api/alfa-tool-services.mjs`.
+- Wrapped the shared Tags `readTables` flow used by `listTags`, snapshots, and tag write preflight reads.
+- Preserved raw database/schema details in `operatorDiagnostic` while returning Creator-safe actionable error text through the API error message.
+- Added `tests/dev-runtime/TagsApiService.test.mjs` for the Tags service read path.
+
+## Non-Goals
+- No browser-owned product data.
+- No silent fallback, MEM DB, fake data, page-local arrays, or JSON source of truth.
+- No start_of_day changes.
+- No individual Tags page changes.
+
+## Validation Summary
+- PASS: `node --check src/dev-runtime/toolbox-api/alfa-tool-services.mjs`
+- PASS: `node --check tests/dev-runtime/TagsApiService.test.mjs`
+- PASS: `node ./scripts/run-node-test-files.mjs tests/dev-runtime/TagsApiService.test.mjs`
+- INFO: `node ./scripts/run-node-test-files.mjs tests/dev-runtime/DevRuntimeBoundary.test.mjs` was attempted and exposed an existing unrelated router assertion around the legacy `local-db` route. This branch does not modify `src/dev-runtime/server/local-api-router.mjs`.
+
+## Result
+PR-scoped validation is PASS. The Tags service now fails safely with actionable setup guidance when the API database adapter or Tags schema is missing.

docs_build/dev/reports/PR_26178_ALFA_001-fix-tags-local-api-crash_requirement-checklist.md

@@ -0,0 +1,14 @@
+# PR_26178_ALFA_001 Requirement Checklist
+
+- PASS - Hard stop if not started from main: main was verified, fast-forwarded, and the PR branch was created from latest main.
+- PASS - Investigate `readTables` failure during `listTags`: the Tags service `readTables` path was reviewed and fixed.
+- PASS - Fix Local API/service-layer issue: `readTables` now wraps adapter/schema failures in `TagsApiSetupError`.
+- PASS - No browser-owned product data: no browser runtime or page state was added.
+- PASS - No silent fallback: the service throws an actionable setup error instead of returning fake or empty data.
+- PASS - No MEM DB, fake data, or page-local arrays: no runtime fallback store or page-local product source was added.
+- PASS - Tags reads use API/Database contract: the service still reads via the injected database adapter and product tables.
+- PASS - Missing setup fails safely: public error text is actionable, status code is 503, raw cause is operator-only diagnostic.
+- PASS - Targeted tests cover `listTags`/`readTables`: new Node tests cover success, missing schema, and missing adapter paths.
+- PASS - Required reports produced under `docs_build/dev/reports/`.
+- PASS - Repo-structured ZIP produced under `tmp/`.
+- PASS - No `start_of_day` folders modified.

docs_build/dev/reports/PR_26178_ALFA_001-fix-tags-local-api-crash_validation-lane.md

@@ -0,0 +1,19 @@
+# PR_26178_ALFA_001 Validation Lane
+
+## Lane
+Focused Tags API service validation.
+
+## Commands Run
+- `node --check src/dev-runtime/toolbox-api/alfa-tool-services.mjs`
+- `node --check tests/dev-runtime/TagsApiService.test.mjs`
+- `node ./scripts/run-node-test-files.mjs tests/dev-runtime/TagsApiService.test.mjs`
+- `node ./scripts/run-node-test-files.mjs tests/dev-runtime/DevRuntimeBoundary.test.mjs`
+
+## Results
+- PASS - Tags service syntax check.
+- PASS - Tags service test syntax check.
+- PASS - Tags service targeted Node test, 3 subtests.
+- INFO/OUT-OF-SCOPE FAIL - DevRuntimeBoundary exposes an existing router assertion for `parts[1] === "local-db"` in `src/dev-runtime/server/local-api-router.mjs`. This branch does not change that file or route.
+
+## Playwright
+Playwright was not run for this service-layer crash because the targeted failure is inside `createTagsApiService().listTags()` and the new Node test validates the exact API service read path without requiring live database availability.

docs_build/dev/reports/codex_changed_files.txt

@@ -1,22 +1,9 @@
-docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md
-docs_build/dev/ProjectInstructions/README.txt
-docs_build/dev/ProjectInstructions/TEAM_START_COMMANDS.md
-docs_build/dev/ProjectInstructions/addendums/branch_context_governance.md
-docs_build/dev/ProjectInstructions/addendums/branch_lock_governance.md
-docs_build/dev/ProjectInstructions/addendums/codex_artifact_and_reporting_standard.md
-docs_build/dev/ProjectInstructions/addendums/codex_project_instructions_startup.md
-docs_build/dev/ProjectInstructions/addendums/environment_configuration_standards.md
-docs_build/dev/ProjectInstructions/addendums/multi_team.md
-docs_build/dev/ProjectInstructions/addendums/pr_workflow.md
-docs_build/dev/ProjectInstructions/addendums/team_backlog_sod_eod_standard.md
-docs_build/dev/ProjectInstructions/addendums/tool_mvp_stacked_pr_standard.md
-docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md
-docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md
-docs_build/dev/ProjectInstructions/team_assignments/team_ownership.md
-docs_build/dev/reports/PR_26177_OWNER_012-project-instructions-cleanup-backlog-canonicalization.md
-docs_build/dev/reports/PR_26177_OWNER_012-project-instructions-cleanup-backlog-canonicalization_branch-validation.md
-docs_build/dev/reports/PR_26177_OWNER_012-project-instructions-cleanup-backlog-canonicalization_manual-validation-notes.md
-docs_build/dev/reports/PR_26177_OWNER_012-project-instructions-cleanup-backlog-canonicalization_requirements-checklist.md
-docs_build/dev/reports/PR_26177_OWNER_012-project-instructions-cleanup-backlog-canonicalization_validation-lane.md
-docs_build/dev/reports/codex_changed_files.txt
-docs_build/dev/reports/codex_review.diff
+A	docs_build/dev/reports/PR_26178_ALFA_001-fix-tags-local-api-crash_branch-validation.md
+A	docs_build/dev/reports/PR_26178_ALFA_001-fix-tags-local-api-crash_manual-validation-notes.md
+A	docs_build/dev/reports/PR_26178_ALFA_001-fix-tags-local-api-crash_report.md
+A	docs_build/dev/reports/PR_26178_ALFA_001-fix-tags-local-api-crash_requirement-checklist.md
+A	docs_build/dev/reports/PR_26178_ALFA_001-fix-tags-local-api-crash_validation-lane.md
+M	src/dev-runtime/toolbox-api/alfa-tool-services.mjs
+A	tests/dev-runtime/TagsApiService.test.mjs
+A	 docs_build/dev/reports/codex_changed_files.txt
+A	 docs_build/dev/reports/codex_review.diff

docs_build/dev/reports/codex_review.diff

@@ -265,6 +265,19 @@ function databaseAdapter(options, action) {
   throw new Error(`${action} requires the configured API database adapter.`);
 }
 
+function tagsApiSetupError(action, error) {
+  if (error?.name === "TagsApiSetupError") {
+    return error;
+  }
+  const message = `${action} failed because the Tags API database setup is unavailable. Verify the API database connection and apply the account, Game Hub, and Tags database setup before using Tags.`;
+  const wrapped = new Error(message);
+  wrapped.name = "TagsApiSetupError";
+  wrapped.statusCode = typeof error?.statusCode === "number" ? error.statusCode : 503;
+  wrapped.operatorDiagnostic = `${message} Cause: ${error instanceof Error ? error.message : String(error || "Unknown database error.")}`;
+  wrapped.cause = error;
+  return wrapped;
+}
+
 function activeGameFromWorkspace(repository, overrideId = "") {
   if (overrideId && typeof repository?.openGame === "function") {
     repository.openGame(overrideId);
@@ -359,44 +372,49 @@ export function createTagsApiService(options = {}) {
   const seededProjectKeys = new Set();
 
   async function readTables(seed = true) {
-    const adapter = databaseAdapter(options, "Reading project tags");
-    const project = activeProject();
-    await ensureGameRecord(adapter, project, activeUserKey(options));
-    let tags = await adapter.requestTable("project_tags");
-    if (seed) {
-      const existingSlugs = new Set(tags.map((tag) => normalizeText(tag.slug)));
-      const missingRows = STARTER_TAGS
-        .map(starterTagRow)
-        .filter((row) => !existingSlugs.has(row.slug));
-      if (missingRows.length) {
-        await adapter.upsertProductTable("project_tags", missingRows);
-        tags = await adapter.requestTable("project_tags");
+    const action = "Reading project tags";
+    try {
+      const adapter = databaseAdapter(options, action);
+      const project = activeProject();
+      await ensureGameRecord(adapter, project, activeUserKey(options));
+      let tags = await adapter.requestTable("project_tags");
+      if (seed) {
+        const existingSlugs = new Set(tags.map((tag) => normalizeText(tag.slug)));
+        const missingRows = STARTER_TAGS
+          .map(starterTagRow)
+          .filter((row) => !existingSlugs.has(row.slug));
+        if (missingRows.length) {
+          await adapter.upsertProductTable("project_tags", missingRows);
+          tags = await adapter.requestTable("project_tags");
+        }
       }
-    }
-    let assignments = await adapter.requestTable("project_tag_assignments");
-    if (seed && !seededProjectKeys.has(project.key)) {
-      const projectAssignments = assignments.filter((assignment) => assignment.projectKey === project.key);
-      if (!projectAssignments.length) {
-        const starterTagKeys = tags
-          .filter((tag) => ["fantasy", "platformer"].includes(normalizeText(tag.slug)))
-          .map((tag) => tag.key);
-        if (starterTagKeys.length) {
-          await adapter.upsertProductTable("project_tag_assignments", starterTagKeys.map((tagKey) => ({
-            key: adapter.createRecordKey(),
-            projectKey: project.key,
-            tagKey,
-            ...auditFields(SYSTEM_USER_KEY),
-          })));
-          assignments = await adapter.requestTable("project_tag_assignments");
+      let assignments = await adapter.requestTable("project_tag_assignments");
+      if (seed && !seededProjectKeys.has(project.key)) {
+        const projectAssignments = assignments.filter((assignment) => assignment.projectKey === project.key);
+        if (!projectAssignments.length) {
+          const starterTagKeys = tags
+            .filter((tag) => ["fantasy", "platformer"].includes(normalizeText(tag.slug)))
+            .map((tag) => tag.key);
+          if (starterTagKeys.length) {
+            await adapter.upsertProductTable("project_tag_assignments", starterTagKeys.map((tagKey) => ({
+              key: adapter.createRecordKey(),
+              projectKey: project.key,
+              tagKey,
+              ...auditFields(SYSTEM_USER_KEY),
+            })));
+            assignments = await adapter.requestTable("project_tag_assignments");
+          }
         }
+        seededProjectKeys.add(project.key);
       }
-      seededProjectKeys.add(project.key);
+      lastTables = {
+        project_tag_assignments: assignments,
+        project_tags: tags,
+      };
+      return lastTables;
+    } catch (error) {
+      throw tagsApiSetupError(action, error);
     }
-    lastTables = {
-      project_tag_assignments: assignments,
-      project_tags: tags,
-    };
-    return lastTables;
   }
 
   function activeProject() {

src/dev-runtime/toolbox-api/alfa-tool-services.mjs

@@ -0,0 +1,155 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  createTagsApiService,
+  gameWorkspaceGameKeyForApi,
+} from "../../src/dev-runtime/toolbox-api/alfa-tool-services.mjs";
+import { SEED_DB_KEYS, makeSeedUlid } from "../../src/dev-runtime/seed/seed-db-keys.mjs";
+
+function cloneRows(rows) {
+  return rows.map((row) => ({ ...row }));
+}
+
+function createGameWorkspaceRepository() {
+  return {
+    getActiveGame() {
+      return {
+        id: "demo-game",
+        name: "Demo Game",
+        purpose: "Game",
+        status: "Under Construction",
+      };
+    },
+  };
+}
+
+class TagsServiceTestAdapter {
+  constructor(options = {}) {
+    this.calls = [];
+    this.failTable = options.failTable || "";
+    this.failAction = options.failAction || "requestTable";
+    this.recordIndex = 0;
+    this.tables = {
+      game_workspace_games: [],
+      project_tag_assignments: [],
+      project_tags: [],
+      users: [],
+    };
+  }
+
+  createRecordKey() {
+    this.recordIndex += 1;
+    return makeSeedUlid(9800 + this.recordIndex);
+  }
+
+  async requestTable(tableName, options = {}) {
+    this.calls.push(["requestTable", tableName, options.method || "GET"]);
+    if (this.failAction === "requestTable" && tableName === this.failTable) {
+      throw new Error(`relation "${tableName}" does not exist`);
+    }
+    if (!Object.hasOwn(this.tables, tableName)) {
+      throw new Error(`relation "${tableName}" does not exist`);
+    }
+    if (options.method === "DELETE") {
+      const key = String(options.query || "").match(/key=eq\.([^&]+)/)?.[1] || "";
+      const decodedKey = decodeURIComponent(key);
+      const deletedRows = this.tables[tableName].filter((row) => row.key === decodedKey);
+      this.tables[tableName] = this.tables[tableName].filter((row) => row.key !== decodedKey);
+      return cloneRows(deletedRows);
+    }
+    return cloneRows(this.tables[tableName]);
+  }
+
+  async upsertProductTable(tableName, rows) {
+    this.calls.push(["upsertProductTable", tableName, rows.length]);
+    if (this.failAction === "upsertProductTable" && tableName === this.failTable) {
+      throw new Error(`permission denied for table "${tableName}"`);
+    }
+    this.#upsert(tableName, rows);
+  }
+
+  async upsertTable(tableName, rows) {
+    this.calls.push(["upsertTable", tableName, rows.length]);
+    this.#upsert(tableName, rows);
+  }
+
+  #upsert(tableName, rows) {
+    if (!Object.hasOwn(this.tables, tableName)) {
+      throw new Error(`relation "${tableName}" does not exist`);
+    }
+    rows.forEach((row) => {
+      const index = this.tables[tableName].findIndex((candidate) => candidate.key === row.key);
+      if (index >= 0) {
+        this.tables[tableName][index] = { ...this.tables[tableName][index], ...row };
+      } else {
+        this.tables[tableName].push({ ...row });
+      }
+    });
+  }
+}
+
+function createService(adapter) {
+  return createTagsApiService({
+    databaseAdapter: () => adapter,
+    gameWorkspaceRepository: createGameWorkspaceRepository(),
+    sessionUserKey: SEED_DB_KEYS.users.user1,
+  });
+}
+
+test("Tags list reads and seeds through the API database adapter", async () => {
+  const adapter = new TagsServiceTestAdapter();
+  const service = createService(adapter);
+
+  const tags = await service.listTags();
+
+  assert.deepEqual(
+    tags.map((tag) => tag.label).sort(),
+    ["boss-fight", "fantasy", "kids", "medium", "pixel-art", "platformer"]
+  );
+  assert.equal(adapter.tables.project_tags.length, 6);
+  assert.equal(adapter.tables.game_workspace_games[0].key, gameWorkspaceGameKeyForApi("demo-game"));
+  assert.equal(adapter.tables.game_workspace_games[0].ownerKey, SEED_DB_KEYS.users.user1);
+  assert.equal(adapter.tables.project_tag_assignments.length, 2);
+  assert.equal(adapter.tables.project_tag_assignments.every((row) => row.projectKey === gameWorkspaceGameKeyForApi("demo-game")), true);
+  assert.equal(adapter.tables.project_tags.every((row) => row.createdAt && row.updatedAt && row.createdBy && row.updatedBy), true);
+  assert.equal(adapter.calls.some(([action, table]) => action === "requestTable" && table === "project_tags"), true);
+  assert.equal(adapter.calls.some(([action, table]) => action === "upsertProductTable" && table === "project_tags"), true);
+  assert.equal(adapter.calls.some(([action, table]) => action === "upsertProductTable" && table === "project_tag_assignments"), true);
+});
+
+test("Tags list reports an actionable setup error when readTables cannot read the schema", async () => {
+  const adapter = new TagsServiceTestAdapter({ failTable: "project_tags" });
+  const service = createService(adapter);
+
+  await assert.rejects(
+    () => service.listTags(),
+    (error) => {
+      assert.equal(error.name, "TagsApiSetupError");
+      assert.equal(error.statusCode, 503);
+      assert.match(error.message, /Tags API database setup is unavailable/);
+      assert.match(error.message, /apply the account, Game Hub, and Tags database setup/);
+      assert.doesNotMatch(error.message, /relation "project_tags"/);
+      assert.match(error.operatorDiagnostic, /relation "project_tags" does not exist/);
+      return true;
+    }
+  );
+});
+
+test("Tags list reports an actionable setup error when the API database adapter is missing", async () => {
+  const service = createTagsApiService({
+    gameWorkspaceRepository: createGameWorkspaceRepository(),
+    sessionUserKey: SEED_DB_KEYS.users.user1,
+  });
+
+  await assert.rejects(
+    () => service.listTags(),
+    (error) => {
+      assert.equal(error.name, "TagsApiSetupError");
+      assert.equal(error.statusCode, 503);
+      assert.match(error.message, /Tags API database setup is unavailable/);
+      assert.doesNotMatch(error.message, /requires the configured API database adapter/);
+      assert.match(error.operatorDiagnostic, /requires the configured API database adapter/);
+      return true;
+    }
+  );
+});