refactor(web): route remaining API calls through TanStack Query

[Nether403]

Summary

Phase 4 gap #3. Sweeps the two remaining imperative API call sites out of components into the useApi hook family so every component consumes the API through TanStack Query.

Migrations

Site	Before	After
StackBuilderPage.tsx	useState + useEffect + imperative loadCatalog()	useStackBuilderCatalog() hook
ExportDialog.tsx	Local isGenerating/exportData/error state + imperative apiClient.generateScaffold()	useGenerateScaffold() mutation with mutateAsync on open

New hooks in useApi.ts:

• useCatalog() — raw /api/v1/catalog payload for components that already have the tools and rules they need (used by the compatibility matrix).
• useStackBuilderCatalog() — wraps lib/catalog-loader's loadCatalog() so the Stack Builder keeps its localStorage-cached static-fallback behavior when the API is down. The loader is the queryFn; TanStack Query owns staleness / retry / deduplication.

Intentional exceptions

Two apiClient. call sites are kept outside TanStack Query on purpose:

1. useRulesEngine.ts — the stack-analysis hook already owns a custom debounce + sequence-token race guard + deterministic fallback to the local rules-engine worker. Those guarantees don't map onto query/mutation lifecycles cleanly, and it's always been a hook so components never see the call directly.
2. lib/catalog-loader.ts — this is the query function; its localStorage cache persists catalog data across full page reloads, complementing TSQ's in-memory cache.

Evidence

New Playwright test loads the Stack Builder catalog via TanStack Query confirms the refactored page renders the catalog (waits for Next.js to appear on /stack-builder).

Full E2E suite:

5 passed (1.0m)
 ok searches the tool catalog (1.6s)
 ok loads the Stack Builder catalog via TanStack Query (1.7s)
 ok analyzes pairwise compatibility (1.4s)
 ok shows a basic migration path (723ms)
 ok generates an idea-to-stack blueprint (29.0s)

Quality gate (local)

• pnpm -r type-check — 0 errors
• pnpm -r lint — 0 errors
• pnpm -r test — 60 unit/API tests pass
• pnpm -r build — web + api + packages
• pnpm test:e2e — 5/5 passed

Notes

• Bumped the blueprint E2E timeout to 120s / 60s to match PRs feat(web): convert Blueprint Builder to 4-step wizard #2 and feat(web): add compatibility matrix heatmap view #3 (parallel AI fan-out can exceed the config's 30s per-test default). Will merge cleanly once one of the three Phase 4 PRs lands.
• Branched off main; does not conflict with PR feat(web): convert Blueprint Builder to 4-step wizard #2 or feat(web): add compatibility matrix heatmap view #3 at the file level apart from the shared E2E timeout bump.

---

---

Summary by cubic

Routes the last direct API calls through @tanstack/react-query by moving them into useApi hooks. Unifies data fetching/caching and keeps the Stack Builder’s offline/static fallback.

• Refactors
  • Added useCatalog() (raw /api/v1/catalog) and useStackBuilderCatalog() (wraps loadCatalog() with localStorage/static fallback, plus stale time/retry).
  • StackBuilderPage now uses useStackBuilderCatalog and the query client for cache invalidation; removed local state/effects; Retry shows refetching state.
  • ExportDialog now uses useGenerateScaffold mutation (runs on open, resets on close); separates download errors and disables actions during work.
  • Left imperative calls in useRulesEngine.ts and lib/catalog-loader.ts by design.
  • Tests: added E2E check for catalog loading via TanStack Query; increased blueprint test timeout for stability.

^{Written for commit 55eb30f. Summary will update on new commits.}

[devin-ai-integration]

Devin Review found 1 potential issue.

View 3 additional findings in Devin Review.

[devin-ai-integration]

🔴 useEffect missing scaffoldError guard causes infinite API retry loop on failure

When generateScaffold fails, the useEffect at line 54 re-fires and retriggers the mutation in an infinite loop. After failure: open is true, exportData is undefined, and isGenerating is false — so the guard if (!open || exportData || isGenerating) return does not stop execution. Since scaffoldError is never checked, generateScaffold is called again immediately, which fails again, and so on. This is further aggravated by selectedTools (ExportDialog.tsx:40) being a new array reference on every render (via Array.from() in SelectionsContext.tsx:125), which means the effect's dependency array always appears changed, causing the effect to re-run on every render even without other state changes.

Suggested change

	useEffect(() => {
	if (!open || exportData || isGenerating) return;
	generateScaffold({
	toolIds: selectedTools.map((tool) => tool.id),
	projectName: 'stackfast-app',
	}).catch(() => {
	// Error surfaced via scaffoldError below; nothing to do here.
	});
	}, [open, exportData, isGenerating, generateScaffold, selectedTools]);
	// Generate the scaffold once when the dialog first opens.
	useEffect(() => {
	if (!open || exportData || isGenerating || scaffoldError) return;
	generateScaffold({
	toolIds: selectedTools.map((tool) => tool.id),
	projectName: 'stackfast-app',
	}).catch(() => {
	// Error surfaced via scaffoldError below; nothing to do here.
	});
	}, [open, exportData, isGenerating, scaffoldError, generateScaffold, selectedTools]);

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[cubic-dev-ai]

2 issues found across 4 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/web/src/components/ExportDialog.tsx">

<violation number="1" location="apps/web/src/components/ExportDialog.tsx:62">
P1: The scaffold-generation effect depends on an unstable array (`selectedTools`), which can trigger repeated mutation calls (especially after errors) and cause an unintended request loop.</violation>
</file>

<file name="apps/web/src/pages/StackBuilderPage.tsx">

<violation number="1" location="apps/web/src/pages/StackBuilderPage.tsx:30">
P2: `invalidateQueries` already refetches active catalog queries, so calling `refetch()` immediately after causes duplicate refresh work. Use a single targeted invalidation (or only `refetch`) to avoid double query execution.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P1: The scaffold-generation effect depends on an unstable array (selectedTools), which can trigger repeated mutation calls (especially after errors) and cause an unintended request loop.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/web/src/components/ExportDialog.tsx, line 62:

<comment>The scaffold-generation effect depends on an unstable array (`selectedTools`), which can trigger repeated mutation calls (especially after errors) and cause an unintended request loop.</comment>

<file context>
@@ -36,71 +36,75 @@ export function ExportDialog({
+    }).catch(() => {
+      // Error surfaced via scaffoldError below; nothing to do here.
+    });
+  }, [open, exportData, isGenerating, generateScaffold, selectedTools]);
 
   // Download as archive
</file context>

[cubic-dev-ai]

P2: invalidateQueries already refetches active catalog queries, so calling refetch() immediately after causes duplicate refresh work. Use a single targeted invalidation (or only refetch) to avoid double query execution.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/web/src/pages/StackBuilderPage.tsx, line 30:

<comment>`invalidateQueries` already refetches active catalog queries, so calling `refetch()` immediately after causes duplicate refresh work. Use a single targeted invalidation (or only `refetch`) to avoid double query execution.</comment>

<file context>
@@ -1,63 +1,34 @@
-    } finally {
-      setIsLoading(false);
-    }
+    await queryClient.invalidateQueries({ queryKey: ["catalog"] });
+    await refetch();
   };
</file context>