🐛 Bugfix: Why did the entire Vitto Studio live preview pipeline silent...

Date: 2026-03-18
Time: 00:00:23 UTC
Session: gspace1-231.6
Agent: backend
Confidence: 98%
Status: ✅ Documented

📋 Decision Context

Question:

Why did the entire Vitto Studio live preview pipeline silently fail — showing 'Ready when you are' even with 5 modules generated?

Task: Fix Vitto Studio live preview showing 'Ready when you are' with generated modules

🎯 Decision Made

Chosen:

Three-layer fix: (1) forkJoin to emit modulesLoaded$ after ALL file contents fetched, (2) correct GitLab type mapping blob→file in listFilesRecursive, (3) clear loadedModuleSlugs on VFS re-init. Root cause was the type mapping: GitLab returns type:'blob', code checked type==='file', so every file was misidentified as directory. Zero files ever entered VFS.

Options Considered:

1. Fix only the timing (forkJoin) — would not have worked alone
2. Fix only the type mapping — would have worked but timing race remained
3. Fix all three layers (chosen) — addresses root cause + timing + caching

💭 Reasoning

The failure was invisible because every layer had catchError() swallowing exceptions silently. The type mapping chain crossed 3 services (gitlab-provider → git-provider.controller → studio-repo.controller → flattenFileNodes) with each layer transforming types and none validating the output. The blob→file mapping was a TypeScript cast ('as file') that didn't transform the actual runtime value. This is a class of bug where TypeScript's type system gives false safety — the cast makes the compiler happy but the runtime value is still 'blob'. The forkJoin fix was necessary but insufficient alone because the timer(1500) workaround was masking the real type-mapping bug. Early warning: any time you see a type cast on API response data, verify the runtime value matches the expected domain type.

📁 Files Involved

• APIs/backend-api/src/app/git-provider/gitlab-provider.service.ts
• libs/libs-structural/vitto-studio/src/lib/services/vfs-sync.service.ts
• APIs/backend-ai-api/src/app/module-files/studio-repo.controller.ts

🔗 Related

• Decision ID: dev_1773792023405_je0rexn
• Session: 231
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation