docs(03): create phase plan

Phase 03: Generate Node Refactor - 3 plans created - 9 total tasks defined - Ready for execution
6 months ago · 1bf6520d86
3 changed files with 462 additions and 0 deletions
--- a/.planning/phases/03-generate-node-refactor/03-01-PLAN.md
+++ b/.planning/phases/03-generate-node-refactor/03-01-PLAN.md
@ -0,0 +1,143 @@
+---
+phase: 03-generate-node-refactor
+plan: 01
+type: execute
+---
+
+<objective>
+Rename NanoBanana node to Generate and add multi-provider model selector.
+
+Purpose: Transform the hardcoded Gemini-only node into a generic generation node that can use any provider's models.
+Output: Generate node component with provider/model dropdown, updated types, store functions renamed.
+</objective>
+
+<execution_context>
+~/.claude/get-shit-done/workflows/execute-phase.md
+~/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+
+# Prior phase context:
+@.planning/phases/01-provider-infrastructure/01-02-SUMMARY.md
+@.planning/phases/02-model-discovery/02-03-SUMMARY.md
+
+# Key source files:
+@src/components/nodes/NanoBananaNode.tsx
+@src/types/index.ts
+@src/store/workflowStore.ts
+@src/lib/providers/types.ts
+
+**Tech stack available:** Zustand, React, ProviderModel interface, /api/models endpoint
+**Established patterns:** Provider self-registration, localStorage settings persistence
+**Constraining decisions:**
+- Keep nanoBanana node type internally for backward compatibility
+- Gemini models use internal names (nano-banana, nano-banana-pro)
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Update types for multi-provider model selection</name>
+  <files>src/types/index.ts</files>
+  <action>
+  1. Add new types for selected model:
+     - `SelectedModel` interface with { provider: ProviderType, modelId: string, displayName: string }
+     - Keep existing ModelType for backward compatibility
+
+  2. Update NanoBananaNodeData interface:
+     - Add optional `selectedModel?: SelectedModel` field
+     - Keep existing `model: ModelType` field for Gemini backward compatibility
+
+  3. Add "gemini" to ProviderType union if not already present (it should be the Gemini provider identifier)
+
+  WHY: NanoBananaNodeData needs to store either legacy Gemini model selection OR new multi-provider selection. The optional selectedModel field enables graceful migration.
+  </action>
+  <verify>npx tsc --noEmit passes</verify>
+  <done>Types compile, SelectedModel interface exists, NanoBananaNodeData has selectedModel field</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Rename component to GenerateNode with model selector UI</name>
+  <files>src/components/nodes/NanoBananaNode.tsx, src/components/nodes/index.ts</files>
+  <action>
+  1. Rename file from NanoBananaNode.tsx to GenerateNode.tsx
+
+  2. Rename component from NanoBananaNode to GenerateNode (keep function export name)
+
+  3. Add model selector UI that shows:
+     - Provider dropdown (gemini, replicate, fal) - only show enabled providers
+     - Model dropdown (fetched from /api/models for selected provider)
+     - For Gemini, show existing hardcoded models (Nano Banana, Nano Banana Pro)
+     - For other providers, fetch models dynamically
+
+  4. When provider/model changes:
+     - Update node data with selectedModel: { provider, modelId, displayName }
+     - For Gemini, also update legacy model field for backward compatibility
+
+  5. Keep existing aspect ratio/resolution controls for Gemini models
+     - Hide them for non-Gemini models (parameters will come from provider schema later)
+
+  6. Update index.ts to export GenerateNode and alias it as NanoBananaNode for backward compatibility:
+     ```typescript
+     export { GenerateNode } from "./GenerateNode";
+     export { GenerateNode as NanoBananaNode } from "./GenerateNode";
+     ```
+
+  WHY: The component rename reflects its new multi-provider purpose. The alias maintains backward compatibility with existing imports.
+  </action>
+  <verify>npm run build succeeds, component renders in browser</verify>
+  <done>GenerateNode.tsx exists, shows provider selector, model dropdown fetches from API for non-Gemini providers</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Update store and canvas references</name>
+  <files>src/store/workflowStore.ts, src/components/WorkflowCanvas.tsx</files>
+  <action>
+  1. In workflowStore.ts:
+     - Rename saveNanoBananaDefaults to saveGenerateDefaults (keep old name as alias)
+     - Rename loadNanoBananaDefaults to loadGenerateDefaults (keep old name as alias)
+     - Update localStorage key comment but keep actual key for migration
+     - Update createDefaultNodeData for "nanoBanana" case to include default selectedModel for Gemini
+
+  2. In WorkflowCanvas.tsx:
+     - Update nodeTypes registration to use GenerateNode
+     - Keep "nanoBanana" as the type key (internal type name unchanged)
+     - Update minimap color mapping if it references "nanoBanana"
+
+  3. In any file using NanoBananaNode import:
+     - Update import to use GenerateNode
+     - Files: ConnectionDropMenu.tsx, FloatingActionBar.tsx, etc.
+
+  WHY: Internal references update to new names while keeping the node type string "nanoBanana" for workflow file compatibility.
+  </action>
+  <verify>npm run build succeeds, existing workflows load correctly</verify>
+  <done>All imports updated, store functions renamed with aliases, workflows still load</done>
+</task>
+
+</tasks>
+
+<verification>
+Before declaring plan complete:
+- [ ] `npm run build` succeeds without errors
+- [ ] `npx tsc --noEmit` passes type checking
+- [ ] GenerateNode renders with provider dropdown
+- [ ] Gemini models show in model selector
+- [ ] Existing workflows with nanoBanana nodes still load
+</verification>
+
+<success_criteria>
+
+- All tasks completed
+- All verification checks pass
+- GenerateNode component exists with multi-provider UI
+- Types support both legacy Gemini and new multi-provider selection
+- Backward compatibility maintained for existing workflows
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/03-generate-node-refactor/03-01-SUMMARY.md`
+</output>
--- a/.planning/phases/03-generate-node-refactor/03-02-PLAN.md
+++ b/.planning/phases/03-generate-node-refactor/03-02-PLAN.md
@ -0,0 +1,165 @@
+---
+phase: 03-generate-node-refactor
+plan: 02
+type: execute
+---
+
+<objective>
+Add provider-specific execution logic to the generate API route.
+
+Purpose: Enable the generate endpoint to route requests to the correct provider (Gemini, Replicate, fal.ai) based on the selected model.
+Output: Updated /api/generate route that dispatches to provider-specific generation logic.
+</objective>
+
+<execution_context>
+~/.claude/get-shit-done/workflows/execute-phase.md
+~/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+
+# Prior plan context:
+@.planning/phases/03-generate-node-refactor/03-01-SUMMARY.md
+
+# Key source files:
+@src/app/api/generate/route.ts
+@src/lib/providers/types.ts
+@src/lib/providers/replicate.ts
+@src/lib/providers/fal.ts
+@src/lib/providers/index.ts
+
+**Tech stack available:** ProviderInterface with generate() method, provider registry
+**Established patterns:** API routes return { success, data/error }, provider self-registration
+**Constraining decisions:**
+- Gemini generation logic already works, preserve it
+- Provider implementations have generate() method defined in ProviderInterface
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Implement generate() method in Replicate provider</name>
+  <files>src/lib/providers/replicate.ts</files>
+  <action>
+  1. Implement the generate() method that currently throws "not implemented":
+     - Accept GenerationInput with model, prompt, images, parameters
+     - Call Replicate's prediction API: POST https://api.replicate.com/v1/predictions
+     - Handle input format: { version: model.id, input: { prompt, image?, ...parameters } }
+     - Poll for completion (Replicate is async) or use webhook pattern
+     - Return GenerationOutput with image/video data
+
+  2. Handle image input:
+     - If images provided, check if Replicate model expects URLs
+     - For now, skip image input (Phase 5 adds image URL server)
+     - Log warning if images provided but skipped
+
+  3. Fetch output:
+     - Poll GET /predictions/{id} until status is "succeeded" or "failed"
+     - Convert output URL to base64 data URL
+     - Return in GenerationOutput format
+
+  WHY: Replicate requires polling for async predictions. The generate() method encapsulates this complexity.
+  </action>
+  <verify>TypeScript compiles, generate() method exists and doesn't throw immediately</verify>
+  <done>Replicate provider has working generate() method that calls prediction API</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Implement generate() method in fal.ai provider</name>
+  <files>src/lib/providers/fal.ts</files>
+  <action>
+  1. Implement the generate() method:
+     - Accept GenerationInput with model, prompt, images, parameters
+     - Call fal.ai's run endpoint: POST https://fal.run/{model.id}
+     - Include prompt and parameters in request body
+     - fal.ai is synchronous (waits for result)
+
+  2. Handle auth:
+     - Use "Key {apiKey}" header format (already established)
+     - API key optional but rate limited without it
+
+  3. Parse response:
+     - Extract image/video URL from response
+     - Convert to base64 data URL for consistency
+     - Handle different output formats (images array, video URL, etc.)
+
+  WHY: fal.ai's synchronous API is simpler than Replicate. The generate() method normalizes the response format.
+  </action>
+  <verify>TypeScript compiles, generate() method exists</verify>
+  <done>fal.ai provider has working generate() method that calls fal.run endpoint</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Update generate API route to dispatch by provider</name>
+  <files>src/app/api/generate/route.ts</files>
+  <action>
+  1. Update request type to accept either:
+     - Legacy format: { model: ModelType, prompt, images, aspectRatio, resolution, useGoogleSearch }
+     - New format: { selectedModel: SelectedModel, prompt, images, parameters }
+
+  2. Add provider dispatch logic:
+     ```typescript
+     if (body.selectedModel) {
+       // New multi-provider path
+       const { provider, modelId } = body.selectedModel;
+       if (provider === "gemini") {
+         // Use existing Gemini logic
+       } else {
+         // Get provider and call generate()
+         const providerImpl = getProvider(provider);
+         const model = await providerImpl.getModel(modelId);
+         const result = await providerImpl.generate({
+           model,
+           prompt: body.prompt,
+           images: body.images,
+           parameters: body.parameters
+         });
+         return NextResponse.json(result);
+       }
+     } else {
+       // Legacy Gemini path (existing code)
+     }
+     ```
+
+  3. Extract Gemini-specific logic into helper function for clarity
+
+  4. Ensure API key handling:
+     - For Gemini: use GEMINI_API_KEY from env
+     - For Replicate/fal: get from provider.getApiKey() (localStorage via client header)
+
+  5. Add client headers for API keys:
+     - Accept X-Replicate-API-Key and X-Fal-API-Key headers
+     - Pass to provider implementations
+
+  WHY: The route becomes a dispatcher that preserves existing Gemini behavior while enabling new providers.
+  </action>
+  <verify>npm run build succeeds, existing Gemini generation still works</verify>
+  <done>Generate route dispatches to correct provider, Gemini still works as before</done>
+</task>
+
+</tasks>
+
+<verification>
+Before declaring plan complete:
+- [ ] `npm run build` succeeds without errors
+- [ ] Existing Gemini generation works (test with existing workflow)
+- [ ] Replicate provider generate() method implemented
+- [ ] fal.ai provider generate() method implemented
+- [ ] API route accepts both legacy and new request formats
+</verification>
+
+<success_criteria>
+
+- All tasks completed
+- All verification checks pass
+- Generate API routes to correct provider based on selectedModel
+- Gemini generation unchanged for backward compatibility
+- Replicate and fal.ai providers have generate() implementations
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/03-generate-node-refactor/03-02-SUMMARY.md`
+</output>
--- a/.planning/phases/03-generate-node-refactor/03-03-PLAN.md
+++ b/.planning/phases/03-generate-node-refactor/03-03-PLAN.md
@ -0,0 +1,154 @@
+---
+phase: 03-generate-node-refactor
+plan: 03
+type: execute
+---
+
+<objective>
+Ensure backward compatibility for existing workflows containing nanoBanana nodes.
+
+Purpose: Existing saved workflows must load and execute correctly without modification.
+Output: Migration logic, verified backward compatibility, updated workflow execution.
+</objective>
+
+<execution_context>
+~/.claude/get-shit-done/workflows/execute-phase.md
+~/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+
+# Prior plan context:
+@.planning/phases/03-generate-node-refactor/03-01-SUMMARY.md
+@.planning/phases/03-generate-node-refactor/03-02-SUMMARY.md
+
+# Key source files:
+@src/store/workflowStore.ts
+@src/types/index.ts
+@src/components/nodes/GenerateNode.tsx
+
+**Tech stack available:** Zustand, workflow JSON persistence
+**Established patterns:** Workflow load/save in workflowStore
+**Constraining decisions:**
+- Node type "nanoBanana" must remain unchanged in workflow files
+- Legacy ModelType ("nano-banana", "nano-banana-pro") must still work
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Add migration logic for loaded workflows</name>
+  <files>src/store/workflowStore.ts</files>
+  <action>
+  1. In loadWorkflow() or where workflow JSON is parsed, add migration:
+     - When loading a nanoBanana node without selectedModel field
+     - Automatically set selectedModel based on legacy model field:
+       ```typescript
+       if (node.type === "nanoBanana" && node.data.model && !node.data.selectedModel) {
+         node.data.selectedModel = {
+           provider: "gemini",
+           modelId: node.data.model,
+           displayName: node.data.model === "nano-banana" ? "Nano Banana" : "Nano Banana Pro"
+         };
+       }
+       ```
+
+  2. Keep legacy model field synced for saves:
+     - When selectedModel is Gemini, also update the model field
+     - This ensures old versions can still read the workflow
+
+  3. Add version field to workflow if not present:
+     - Set workflowVersion in saved JSON for future migrations
+     - Not strictly necessary but good practice
+
+  WHY: Migration on load allows old workflows to work without manual editing. Syncing both fields maintains bidirectional compatibility.
+  </action>
+  <verify>Load an existing workflow file, check node data has both model and selectedModel</verify>
+  <done>Old workflows load with selectedModel populated, new saves include both fields</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Update executeWorkflow for multi-provider generation</name>
+  <files>src/store/workflowStore.ts</files>
+  <action>
+  1. In executeWorkflow()'s nanoBanana case:
+     - Check if node has selectedModel
+     - If selectedModel exists and provider !== "gemini", pass API keys in headers:
+       ```typescript
+       const headers: Record<string, string> = {
+         "Content-Type": "application/json"
+       };
+       if (nodeData.selectedModel?.provider === "replicate") {
+         const settings = get().providerSettings;
+         const replicateConfig = settings.providers.find(p => p.id === "replicate");
+         if (replicateConfig?.apiKey) {
+           headers["X-Replicate-API-Key"] = replicateConfig.apiKey;
+         }
+       }
+       // Similar for fal
+       ```
+
+  2. Build request payload:
+     - Include selectedModel in request body for new providers
+     - Keep existing fields for Gemini backward compatibility
+
+  3. Handle response format:
+     - Provider generate() returns GenerationOutput with outputs array
+     - Extract first image/video output as outputImage
+     - For video outputs, store separately (Phase 6 handles video display)
+
+  WHY: The store's execution logic needs to pass provider API keys (stored client-side) to the server route.
+  </action>
+  <verify>Execute workflow with Gemini model, verify generation still works</verify>
+  <done>Workflow execution handles both legacy and new model selection formats</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Update GenerateNode to handle legacy data</name>
+  <files>src/components/nodes/GenerateNode.tsx</files>
+  <action>
+  1. When component mounts or data changes:
+     - If model exists but not selectedModel, derive selectedModel from model
+     - Display the correct provider/model in dropdowns
+
+  2. Ensure UI state reflects actual node data:
+     - Provider dropdown shows "gemini" for legacy nodes
+     - Model dropdown shows correct Gemini model name
+
+  3. When saving defaults, save in both formats:
+     - saveGenerateDefaults should save both model and selectedModel
+     - Ensures new nodes get correct defaults
+
+  WHY: The UI must correctly display legacy nodes that were migrated on load.
+  </action>
+  <verify>Open workflow with old nanoBanana node, verify dropdowns show correct selection</verify>
+  <done>GenerateNode displays correct provider/model for both legacy and new nodes</done>
+</task>
+
+</tasks>
+
+<verification>
+Before declaring plan complete:
+- [ ] `npm run build` succeeds without errors
+- [ ] Load existing workflow with nanoBanana nodes - nodes display correctly
+- [ ] Execute existing workflow - Gemini generation works
+- [ ] Create new Generate node - defaults are correct
+- [ ] Save and reload workflow - data persists correctly
+</verification>
+
+<success_criteria>
+
+- All tasks completed
+- All verification checks pass
+- Existing workflows load and execute without errors
+- Migration logic populates selectedModel from legacy model field
+- Both old and new format nodes work in same workflow
+- Phase 3 complete
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/03-generate-node-refactor/03-03-SUMMARY.md`
+</output>