feat(description): add deployment version descriptions

[waleedlatif1]

Summary

• Added description field to deployment versions
• Created description modal for viewing/editing descriptions
• Refactored to use TanStack Query mutations
• Removed useEffect anti-pattern using key prop

Type of Change

• New feature

Testing

Tested manually

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
docs	Skipped		Jan 28, 2026 9:52pm

[greptile-apps]

Greptile Overview

Greptile Summary

Added description field to deployment versions with AI generation capabilities. The implementation includes database migration, API endpoint updates, and a new modal UI for viewing/editing descriptions. Successfully refactored to use TanStack Query mutations, eliminating the useEffect anti-pattern by removing manual refetch logic in favor of automatic query invalidation.

Key changes:

• Database: Added nullable description text column to workflow_deployment_version table
• API: Extended PATCH endpoint to support updating both name and description with proper validation (max 500 chars)
• Frontend: New VersionDescriptionModal with AI generation via /api/wand endpoint
• Refactor: Replaced manual fetchVersions() with TanStack Query's automatic invalidation on mutations
• Comparison logic: Refactored hasWorkflowChanged to use new generateWorkflowDiffSummary for consistent diff detection used by AI description generator

Implementation notes:

• Description generation analyzes workflow diffs using formatDiffSummaryForDescription to produce concise change summaries
• Modal includes unsaved changes warning and streaming AI responses
• FileText icon button in versions table shows existing descriptions via tooltip

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• Clean implementation that follows established patterns, proper validation, good separation of concerns, and successfully removes anti-patterns
• No files require special attention

Important Files Changed

Filename	Overview
apps/sim/app/api/workflows/[id]/deployments/[version]/route.ts	Refactored PATCH endpoint to support updating both name and description, with proper validation
apps/sim/hooks/queries/deployments.ts	Added useUpdateDeploymentVersion and useGenerateVersionDescription TanStack Query mutations
apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/deploy/components/deploy-modal/components/general/components/version-description-modal.tsx	New modal component for editing/generating version descriptions with AI, includes unsaved changes warning
apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/deploy/components/deploy-modal/components/general/components/versions.tsx	Refactored to use TanStack Query mutations for renaming, added description button with tooltip, removed manual refetch
apps/sim/lib/workflows/comparison/compare.ts	Major refactor: hasWorkflowChanged now uses generateWorkflowDiffSummary, added formatDiffSummaryForDescription for AI description generation

Sequence Diagram

sequenceDiagram
    participant User
    participant VersionsUI as Versions Component
    participant Modal as VersionDescriptionModal
    participant Hook as useUpdateDeploymentVersion
    participant GenHook as useGenerateVersionDescription
    participant API as /api/workflows/[id]/deployments/[version]
    participant WandAPI as /api/wand
    participant CompareLib as compare.ts
    participant QueryClient as TanStack QueryClient
    participant DB as Database

    User->>VersionsUI: Click FileText icon or "Add description"
    VersionsUI->>Modal: Open modal with current description
    
    alt Generate Description
        User->>Modal: Click "Generate" button
        Modal->>GenHook: mutate({ workflowId, version })
        GenHook->>API: GET /deployments/{version} (current)
        API->>DB: Fetch current state
        DB-->>GenHook: Current workflow state
        GenHook->>API: GET /deployments/{version-1} (previous)
        API->>DB: Fetch previous state
        DB-->>GenHook: Previous workflow state
        GenHook->>CompareLib: generateWorkflowDiffSummary(current, previous)
        CompareLib-->>GenHook: WorkflowDiffSummary
        GenHook->>CompareLib: formatDiffSummaryForDescription(summary)
        CompareLib-->>GenHook: Formatted diff text
        GenHook->>WandAPI: POST /api/wand (streaming)
        loop Stream chunks
            WandAPI-->>Modal: Stream chunk
            Modal->>Modal: Update textarea with accumulated content
        end
        WandAPI-->>GenHook: Complete
    end
    
    User->>Modal: Edit description and click "Save"
    Modal->>Hook: mutate({ workflowId, version, description })
    Hook->>API: PATCH /deployments/{version}
    API->>DB: UPDATE workflow_deployment_version
    DB-->>API: Updated record
    API-->>Hook: Success response
    Hook->>QueryClient: invalidateQueries(deploymentKeys.versions)
    QueryClient->>VersionsUI: Auto-refetch versions
    Hook-->>Modal: onSuccess callback
    Modal->>Modal: Close modal
    Modal-->>VersionsUI: Update complete
    VersionsUI->>User: Show updated description in tooltip

Loading

[greptile-apps]

_{6 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Additional Comments (1)

apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/deploy/components/deploy-modal/components/general/components/versions.tsx
block and flex conflict - block display is overridden by flex

                      className={clsx('flex items-center gap-[4px] truncate', ROW_TEXT_CLASS)}

Prompt To Fix With AI

This is a comment left during a code review.
Path: apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/deploy/components/deploy-modal/components/general/components/versions.tsx
Line: 259:259

Comment:
`block` and `flex` conflict - `block` display is overridden by `flex`

```suggestion
                      className={clsx('flex items-center gap-[4px] truncate', ROW_TEXT_CLASS)}
```

How can I resolve this? If you propose a fix, please make it concise.

[waleedlatif1]

@greptile

[greptile-apps]

_{4 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[waleedlatif1]

@greptile

[greptile-apps]

_{5 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}