feat(workflows): IDE-style reference viewer for workflows (#5854)

* feat(workflows): add IDE-style reference viewer for workflows

Adds a "Show references" viewer so you can see how workflows connect:
which workflows call a given workflow ("Used by") and which workflows it
calls ("Uses"), rendered as recursive, clickable trees.

- Opened via Cmd/Ctrl+click on a sidebar workflow row and a "Show
  references" context-menu item.
- Resolves references through both the workflow / workflow_input blocks
  (reusing isWorkflowBlockType) and published custom blocks
  (custom_block_* -> source workflow), scoped to the workspace.
- Builds the whole workspace reference graph once from live workflow_blocks
  state; cycle-safe DFS marks A->B->A loops as (cycle) leaves.
- Contract-bound GET /api/workflows/[id]/references with workspace-level
  authz; React Query hook gated to fetch only when the modal opens.
- Unit tests for the pure graph/tree logic (cycles, self-refs, dangling
  drop, custom-block + workflow_input resolution) and route tests
  (401/400/403/200).

* fix(workflows): correct reference resolution for active mode, cycles, cache, and graph size

Addresses review findings on the reference viewer:

- Resolve the workflow-block child via resolveActiveCanonicalValue (the
  shared SOT) instead of basic-first `||`, so an advanced-mode block whose
  old basic workflowId value lingers resolves to the active manual value.
- Keep self-references (A -> A) and render them as a cycle leaf instead of
  dropping the edge, matching the cycle-safe viewer's purpose.
- Set the references query staleTime to 0 so reopening the always-mounted
  modal refetches live editor state instead of serving a stale cached graph.
- Bound converging paths: a node already expanded elsewhere in the tree is
  emitted once more as a plain leaf (edge stays visible) rather than
  re-expanded, so a densely reconverging graph can't grow exponentially.

* improvement(workflows): align reference viewer auth, coverage, and UI with platform conventions

- authorize via authorizeWorkflowByWorkspacePermission and derive the
  workspace server-side (404/403 semantics; drops the client-supplied
  workspaceId query param from the contract, hook, and modal)
- add workflow-tool call edges: workflow_input tools inside tool-input
  sub-blocks now appear in both trees; non-call selector shapes stay
  deliberately excluded (documented against remap-internal-ids)
- restore native cmd/ctrl+click open-in-new-tab on sidebar workflow rows;
  references stay reachable from the context menu
- mount ReferencesModal on demand per row, deleting the prevIsOpen reset,
  the enabled knob, and the staleTime-0 workaround (now 30s)
- align the tree with design tokens (--text-icon, --surface-hover, px-4
  text gutter) and drop the hardcoded brand hex
- escape LIKE wildcards in the custom_block_ prefix match; import
  MAX_CALL_CHAIN_DEPTH instead of mirroring it; remove dead fallbacks,
  the duplicate not-found scan, and the redundant custom-block row map

* improvement(workflows): final polish on the reference viewer

- drop the vestigial isOpen prop (conditional mount owns visibility)
- unify on the emcn Workflow icon in tree rows
- inline the static className and derive nodes without an annotation
- remove one restating test comment

* fix(workflows): resolve tool references by active canonical mode and keep the reference cache live

- workflow_input tools inside tool-input now resolve basic/advanced via the
  index-scoped canonicalModes override, mirroring execution (Cursor finding)
- staleTime back to 0: no mutation invalidates this key, so a reopen must
  background-refetch; on-demand mounting keeps the cached tree painting
  instantly (Greptile P1)
- modal header uses the em-dash label-entity convention; tree items carry
  aria-level instead of a static aria-selected

* fix(workflows): cover legacy workflow-typed tools and retry depth-truncated expansions

- toolInputCallees matches both workflow tool type spellings via
  isWorkflowBlockType and passes the tool's own type as the legacy
  canonicalModes fallback, matching providers/utils resolution
- a depth-capped expansion no longer poisons the expanded set, so a
  shallower path re-expands the node in full (Cursor finding)
- the allowed-but-workspaceless auth branch now returns 403, not the
  authz result's 200
- tests: legacy tool type + per-tool index-scope isolation, diamond
  re-expansion with a real subtree, depth ceiling, shallow-path retry

---------

Co-authored-by: Marcus Chandra <mzxchandra@gmail.com>

Author: waleedlatif1

apps/sim/app/api/workflows/[id]/references/route.test.ts

@@ -0,0 +1,94 @@
+/**
+ * @vitest-environment node
+ */
+import { createMockRequest } from '@sim/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockGetSession, mockAuthorizeWorkflow, mockGetWorkflowReferences } = vi.hoisted(() => ({
+  mockGetSession: vi.fn(),
+  mockAuthorizeWorkflow: vi.fn(),
+  mockGetWorkflowReferences: vi.fn(),
+}))
+
+vi.mock('@/lib/auth', () => ({
+  getSession: mockGetSession,
+}))
+
+vi.mock('@sim/platform-authz/workflow', () => ({
+  authorizeWorkflowByWorkspacePermission: mockAuthorizeWorkflow,
+}))
+
+vi.mock('@/lib/workflows/references/operations', () => ({
+  getWorkflowReferences: mockGetWorkflowReferences,
+}))
+
+import { GET } from '@/app/api/workflows/[id]/references/route'
+
+const REFERENCES = {
+  callers: [{ id: 'b', name: 'B', cycle: false, children: [] }],
+  callees: [],
+}
+
+function callRoute(id = 'wf-1') {
+  const url = `http://localhost:3000/api/workflows/${id}/references`
+  return GET(createMockRequest('GET', undefined, {}, url), { params: Promise.resolve({ id }) })
+}
+
+describe('GET /api/workflows/[id]/references', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockGetSession.mockResolvedValue({ user: { id: 'user-1' } })
+    mockAuthorizeWorkflow.mockResolvedValue({
+      allowed: true,
+      status: 200,
+      workflow: { id: 'wf-1', workspaceId: 'ws-1' },
+      workspacePermission: 'read',
+    })
+    mockGetWorkflowReferences.mockResolvedValue(REFERENCES)
+  })
+
+  it('returns 401 without a session', async () => {
+    mockGetSession.mockResolvedValue(null)
+    const response = await callRoute()
+    expect(response.status).toBe(401)
+    expect(mockGetWorkflowReferences).not.toHaveBeenCalled()
+  })
+
+  it('returns 404 when the workflow does not exist', async () => {
+    mockAuthorizeWorkflow.mockResolvedValue({
+      allowed: false,
+      status: 404,
+      message: 'Workflow not found',
+      workflow: null,
+      workspacePermission: null,
+    })
+    const response = await callRoute()
+    expect(response.status).toBe(404)
+    expect(mockGetWorkflowReferences).not.toHaveBeenCalled()
+  })
+
+  it('returns 403 when the user cannot read the workflow', async () => {
+    mockAuthorizeWorkflow.mockResolvedValue({
+      allowed: false,
+      status: 403,
+      message: 'Unauthorized: Access denied to read this workflow',
+      workflow: { id: 'wf-1', workspaceId: 'ws-1' },
+      workspacePermission: null,
+    })
+    const response = await callRoute()
+    expect(response.status).toBe(403)
+    expect(mockGetWorkflowReferences).not.toHaveBeenCalled()
+  })
+
+  it('returns the reference trees scoped to the workflow workspace', async () => {
+    const response = await callRoute()
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual(REFERENCES)
+    expect(mockAuthorizeWorkflow).toHaveBeenCalledWith({
+      workflowId: 'wf-1',
+      userId: 'user-1',
+      action: 'read',
+    })
+    expect(mockGetWorkflowReferences).toHaveBeenCalledWith('ws-1', 'wf-1')
+  })
+})

apps/sim/app/api/workflows/[id]/references/route.ts

@@ -0,0 +1,37 @@
+import { authorizeWorkflowByWorkspacePermission } from '@sim/platform-authz/workflow'
+import type { NextRequest } from 'next/server'
+import { NextResponse } from 'next/server'
+import { getWorkflowReferencesContract } from '@/lib/api/contracts/workflow-references'
+import { parseRequest } from '@/lib/api/server'
+import { getSession } from '@/lib/auth'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { getWorkflowReferences } from '@/lib/workflows/references/operations'
+
+type RouteContext = { params: Promise<{ id: string }> }
+
+export const GET = withRouteHandler(async (request: NextRequest, context: RouteContext) => {
+  const session = await getSession()
+  if (!session?.user?.id) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const parsed = await parseRequest(getWorkflowReferencesContract, request, context)
+  if (!parsed.success) return parsed.response
+
+  const { id } = parsed.data.params
+
+  const auth = await authorizeWorkflowByWorkspacePermission({
+    workflowId: id,
+    userId: session.user.id,
+    action: 'read',
+  })
+  if (!auth.allowed || !auth.workflow?.workspaceId) {
+    return NextResponse.json(
+      { error: auth.message ?? 'Access denied' },
+      { status: auth.allowed ? 403 : auth.status }
+    )
+  }
+
+  const references = await getWorkflowReferences(auth.workflow.workspaceId, id)
+  return NextResponse.json(references)
+})

apps/sim/app/workspace/[workspaceId]/w/components/sidebar/components/workflow-list/components/context-menu/context-menu.tsx

@@ -22,6 +22,7 @@ import {
   SquareArrowUpRight,
   Trash,
   Unlock,
+  Workflow,
 } from '@sim/emcn/icons'
 import { Pin, PinOff } from 'lucide-react'
 
@@ -31,6 +32,7 @@ interface ContextMenuProps {
   menuRef: React.RefObject<HTMLDivElement | null>
   onClose: () => void
   onOpenInNewTab?: () => void
+  onFindReferences?: () => void
   onMarkAsRead?: () => void
   onMarkAsUnread?: () => void
   onTogglePin?: () => void
@@ -53,6 +55,7 @@ interface ContextMenuProps {
   onExport?: () => void
   onDelete: () => void
   showOpenInNewTab?: boolean
+  showFindReferences?: boolean
   showMarkAsRead?: boolean
   showMarkAsUnread?: boolean
   showPin?: boolean
@@ -93,6 +96,7 @@ export function ContextMenu({
   menuRef,
   onClose,
   onOpenInNewTab,
+  onFindReferences,
   onMarkAsRead,
   onMarkAsUnread,
   onTogglePin,
@@ -104,6 +108,7 @@ export function ContextMenu({
   onExport,
   onDelete,
   showOpenInNewTab = false,
+  showFindReferences = false,
   showMarkAsRead = false,
   showMarkAsUnread = false,
   showPin = false,
@@ -133,7 +138,8 @@ export function ContextMenu({
   showUploadLogo = false,
   disableUploadLogo = false,
 }: ContextMenuProps) {
-  const hasNavigationSection = showOpenInNewTab && onOpenInNewTab
+  const hasNavigationSection =
+    (showOpenInNewTab && onOpenInNewTab) || (showFindReferences && onFindReferences)
   const hasStatusSection =
     (showMarkAsRead && onMarkAsRead) ||
     (showMarkAsUnread && onMarkAsUnread) ||
@@ -195,6 +201,17 @@ export function ContextMenu({
             Open in new tab
           </DropdownMenuItem>
         )}
+        {showFindReferences && onFindReferences && (
+          <DropdownMenuItem
+            onSelect={() => {
+              onFindReferences()
+              onClose()
+            }}
+          >
+            <Workflow />
+            Show references
+          </DropdownMenuItem>
+        )}
         {hasNavigationSection && (hasStatusSection || hasEditSection || hasCopySection) && (
           <DropdownMenuSeparator />
         )}

apps/sim/app/workspace/[workspaceId]/w/components/sidebar/components/workflow-list/components/references-modal/components/reference-tree/reference-tree.tsx

@@ -0,0 +1,68 @@
+'use client'
+
+import { Workflow } from '@sim/emcn/icons'
+import type { ReferenceNode } from '@/lib/api/contracts/workflow-references'
+
+const CONFIG = {
+  /** Horizontal indent added per tree level, in pixels. */
+  INDENT_PER_LEVEL: 16,
+  /** Base row padding: lands depth-0 content on the modal's px-4 text gutter. */
+  BASE_INDENT: 8,
+} as const
+
+interface ReferenceTreeProps {
+  nodes: ReferenceNode[]
+  /** Invoked with a workflow id when a row is activated. */
+  onNavigate: (workflowId: string) => void
+}
+
+interface ReferenceTreeItemProps {
+  node: ReferenceNode
+  depth: number
+  onNavigate: (workflowId: string) => void
+}
+
+function ReferenceTreeItem({ node, depth, onNavigate }: ReferenceTreeItemProps) {
+  return (
+    <div role='treeitem' aria-level={depth + 1}>
+      <button
+        type='button'
+        onClick={() => onNavigate(node.id)}
+        style={{ paddingLeft: CONFIG.BASE_INDENT + depth * CONFIG.INDENT_PER_LEVEL }}
+        className='flex w-full min-w-0 items-center gap-2 rounded-md py-1.5 pr-2 text-left transition-colors hover:bg-[var(--surface-hover)]'
+      >
+        <Workflow className='size-[14px] shrink-0 text-[var(--text-icon)]' />
+        <span className='min-w-0 truncate text-[var(--text-body)] text-sm'>{node.name}</span>
+        {node.cycle && (
+          <span className='shrink-0 text-[var(--text-muted)] text-caption'>(cycle)</span>
+        )}
+      </button>
+      {node.children.length > 0 && (
+        <div role='group'>
+          {node.children.map((child) => (
+            <ReferenceTreeItem
+              key={child.id}
+              node={child}
+              depth={depth + 1}
+              onNavigate={onNavigate}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+
+/**
+ * Read-only recursive tree of workflow references. Each row navigates to its
+ * workflow on click; cyclic leaves are marked and render no children.
+ */
+export function ReferenceTree({ nodes, onNavigate }: ReferenceTreeProps) {
+  return (
+    <div role='tree' className='flex flex-col'>
+      {nodes.map((node) => (
+        <ReferenceTreeItem key={node.id} node={node} depth={0} onNavigate={onNavigate} />
+      ))}
+    </div>
+  )
+}

apps/sim/app/workspace/[workspaceId]/w/components/sidebar/components/workflow-list/components/references-modal/references-modal.tsx

@@ -0,0 +1,74 @@
+'use client'
+
+import { useState } from 'react'
+import { ChipModal, ChipModalBody, ChipModalHeader, ChipModalTabs } from '@sim/emcn'
+import { useRouter } from 'next/navigation'
+import { ReferenceTree } from '@/app/workspace/[workspaceId]/w/components/sidebar/components/workflow-list/components/references-modal/components/reference-tree/reference-tree'
+import { useWorkflowReferences } from '@/hooks/queries/workflow-references'
+
+type ReferencesTab = 'callers' | 'callees'
+
+const TABS = [
+  { value: 'callers', label: 'Used by' },
+  { value: 'callees', label: 'Uses' },
+] as const
+
+const EMPTY_MESSAGE: Record<ReferencesTab, string> = {
+  callers: 'No workflows call this workflow.',
+  callees: "This workflow doesn't call any other workflows.",
+}
+
+interface ReferencesModalProps {
+  onClose: () => void
+  workspaceId: string
+  workflowId: string
+  workflowName: string
+}
+
+/**
+ * IDE-style reference viewer for a workflow. "Used by" lists the workflows that
+ * call it (inbound); "Uses" lists the workflows it calls (outbound). Both are
+ * recursive trees whose rows navigate to the referenced workflow. Mounted on
+ * demand by the owning row, so state initializes fresh per open.
+ */
+export function ReferencesModal({
+  onClose,
+  workspaceId,
+  workflowId,
+  workflowName,
+}: ReferencesModalProps) {
+  const router = useRouter()
+  const [activeTab, setActiveTab] = useState<ReferencesTab>('callers')
+
+  const { data, isPending, isError } = useWorkflowReferences(workflowId)
+
+  const handleNavigate = (targetId: string) => {
+    router.push(`/workspace/${workspaceId}/w/${targetId}`)
+    onClose()
+  }
+
+  const nodes = data?.[activeTab] ?? []
+
+  return (
+    <ChipModal open onOpenChange={(next) => !next && onClose()} srTitle='References'>
+      <ChipModalHeader onClose={onClose}>References — {workflowName}</ChipModalHeader>
+      <ChipModalBody>
+        <ChipModalTabs
+          tabs={TABS}
+          value={activeTab}
+          onChange={(value) => setActiveTab(value as ReferencesTab)}
+          aria-label='Reference direction'
+        />
+        {isPending ? (
+          <p className='px-2 text-[var(--text-muted)] text-sm'>Loading references…</p>
+        ) : isError ? (
+          <p className='px-2 text-[var(--text-error)] text-sm'>Failed to load references.</p>
+        ) : nodes.length === 0 ? (
+          <p className='px-2 text-[var(--text-muted)] text-sm'>{EMPTY_MESSAGE[activeTab]}</p>
+        ) : (
+          <ReferenceTree nodes={nodes} onNavigate={handleNavigate} />
+        )}
+      </ChipModalBody>
+    </ChipModal>
+  )
+}