feat(blocks): add block visibility gating (preview blocks + AppConfig reveals)

.claude/commands/gate-block.md

@@ -0,0 +1,60 @@
+---
+description: Gate a block's visibility — ship an unreleased block as a preview (hidden until revealed via AppConfig/env), reveal it to admins/orgs, GA it, or kill-switch a shipped block
+argument-hint: <block-type>
+---
+
+# Gate Block Skill
+
+You manage **block visibility gating** in Sim — hiding blocks from every discovery surface (toolbar, cmd+K search, copilot @-mentions, agent tool picker, mothership VFS/metadata/tools, Access Control list, public docs/catalog) while **never** gating execution of already-placed instances.
+
+## The model
+
+Three levers, evaluated in `apps/sim/lib/core/config/block-visibility.ts` and folded into the registry accessors (`apps/sim/blocks/registry.ts`):
+
+1. **`preview: true`** on the `BlockConfig` (static, in code) — the block is default-hidden EVERYWHERE (hosted, self-hosted, dev, SSR) until revealed. Fail-closed.
+2. **The hosted `block-visibility` AppConfig document** — per-block rule keyed by the existing block type:
+
+   ```jsonc
+   {
+     "<block-type>": {
+       "enabled": false,        // required. true = GA (visible to everyone)
+       "orgIds": ["org_..."],   // optional allowlist clauses (any match reveals)
+       "userIds": ["user_..."],
+       "adminEnabled": true     // platform admins (user.role === 'admin')
+     }
+   }
+   ```
+
+3. **`PREVIEW_BLOCKS` env** (comma-separated block types) — the off-AppConfig reveal path for self-hosters and local dev.
+
+A revealed block that is not globally GA (`enabled !== true`, or env-revealed) renders with a **" (Preview)"** name suffix on discovery surfaces. `getBlock()` stays pure, so placed instances keep their canonical name and always execute.
+
+## Lifecycle of a preview block
+
+1. **Author** the block normally (`/add-block` etc.) and set `preview: true` on its `BlockConfig`. **Ship no `BlockMeta` and no docs until GA** — `check-block-registry` deliberately skips preview blocks in meta coverage, and `generate-docs` skips them at every gate.
+2. **Local dev:** set `PREVIEW_BLOCKS=<block-type>` in your env to see it (with the suffix).
+3. **Merge/deploy.** The block's code is live everywhere but visible nowhere — no AppConfig rule exists and self-hosters have no env entry.
+4. **Hosted preview:** add a rule to the `block-visibility` AppConfig document and start a deployment (no code deploy):
+   - Admins only: `{ "enabled": false, "adminEnabled": true }`
+   - Design-partner org: `{ "enabled": false, "orgIds": ["org_123"] }`
+   - GA via config (code cleanup pending): `{ "enabled": true }` — suffix disappears everywhere within ~30s (AppConfig TTL) + client refetch.
+
+   Same runbook as `feature-flags`: edit the hosted document, `aws appconfig start-deployment` with the `sim-<env>-fast` strategy (see the infra README).
+5. **GA cleanup:** delete `preview: true` from the block (now visible to self-hosters on their next upgrade), add its `BlockMeta` + regen docs, and drop the AppConfig entry. For a v2 upgrade, this is also when v1 gets `hideFromToolbar: true` (the superseded-version paradigm).
+
+## Kill switch (shipped blocks)
+
+To pull an already-GA block from discovery surfaces on hosted (incident, deprecation): add `{ "<block-type>": { "enabled": false } }` to the document. Allowlist clauses can carve out exceptions. **Execution is NOT stopped** — workflows already using the block keep running; the kill switch only prevents new placement/discovery.
+
+## Invariants (do not violate)
+
+- **Execution is never gated.** The executor, serializer, drop-naming, and `isBlockTypeAccessControlExempt` resolve via pure `getBlock`. Do not add visibility checks to execution paths.
+- **Clone-not-remove:** gated blocks stay in `getAllBlocks()` output as clones with `hideFromToolbar: true` — `.find`-by-type consumers rely on this. Never filter them out.
+- **Keys are registry block types.** Never `custom_block_*` (parse drops them — custom blocks have their own enabled/disabled lifecycle).
+- **The shared hidden-predicate is `isHiddenUnder`** (`apps/sim/blocks/visibility/context.ts`). Never restate the preview/disabled rule inline at a new consumer.
+- **Process-global caches stay ungated.** `getStaticComponentFiles` (VFS) and `getExposedIntegrationTools` build the ungated universe; per-viewer filtering happens at stamp/consumer time. Never move gating into a shared builder.
+- Gating is **surface hiding, not secrecy** — the full config ships in the client JS bundle. Anything truly secret cannot be a registered block.
+
+## Tests
+
+Evaluation semantics: `apps/sim/lib/core/config/block-visibility.test.ts`. Registry projection: `apps/sim/blocks/visibility/visibility.test.ts`. When gating behavior changes, extend those — mock `isPlatformAdmin` for the admin clause; use the local `withAppConfig` harness.

.cursor/commands/gate-block.md

@@ -0,0 +1,60 @@
+---
+description: Gate a block's visibility — ship an unreleased block as a preview (hidden until revealed via AppConfig/env), reveal it to admins/orgs, GA it, or kill-switch a shipped block
+argument-hint: <block-type>
+---
+
+# Gate Block Skill
+
+You manage **block visibility gating** in Sim — hiding blocks from every discovery surface (toolbar, cmd+K search, copilot @-mentions, agent tool picker, mothership VFS/metadata/tools, Access Control list, public docs/catalog) while **never** gating execution of already-placed instances.
+
+## The model
+
+Three levers, evaluated in `apps/sim/lib/core/config/block-visibility.ts` and folded into the registry accessors (`apps/sim/blocks/registry.ts`):
+
+1. **`preview: true`** on the `BlockConfig` (static, in code) — the block is default-hidden EVERYWHERE (hosted, self-hosted, dev, SSR) until revealed. Fail-closed.
+2. **The hosted `block-visibility` AppConfig document** — per-block rule keyed by the existing block type:
+
+   ```jsonc
+   {
+     "<block-type>": {
+       "enabled": false,        // required. true = GA (visible to everyone)
+       "orgIds": ["org_..."],   // optional allowlist clauses (any match reveals)
+       "userIds": ["user_..."],
+       "adminEnabled": true     // platform admins (user.role === 'admin')
+     }
+   }
+   ```
+
+3. **`PREVIEW_BLOCKS` env** (comma-separated block types) — the off-AppConfig reveal path for self-hosters and local dev.
+
+A revealed block that is not globally GA (`enabled !== true`, or env-revealed) renders with a **" (Preview)"** name suffix on discovery surfaces. `getBlock()` stays pure, so placed instances keep their canonical name and always execute.
+
+## Lifecycle of a preview block
+
+1. **Author** the block normally (`/add-block` etc.) and set `preview: true` on its `BlockConfig`. **Ship no `BlockMeta` and no docs until GA** — `check-block-registry` deliberately skips preview blocks in meta coverage, and `generate-docs` skips them at every gate.
+2. **Local dev:** set `PREVIEW_BLOCKS=<block-type>` in your env to see it (with the suffix).
+3. **Merge/deploy.** The block's code is live everywhere but visible nowhere — no AppConfig rule exists and self-hosters have no env entry.
+4. **Hosted preview:** add a rule to the `block-visibility` AppConfig document and start a deployment (no code deploy):
+   - Admins only: `{ "enabled": false, "adminEnabled": true }`
+   - Design-partner org: `{ "enabled": false, "orgIds": ["org_123"] }`
+   - GA via config (code cleanup pending): `{ "enabled": true }` — suffix disappears everywhere within ~30s (AppConfig TTL) + client refetch.
+
+   Same runbook as `feature-flags`: edit the hosted document, `aws appconfig start-deployment` with the `sim-<env>-fast` strategy (see the infra README).
+5. **GA cleanup:** delete `preview: true` from the block (now visible to self-hosters on their next upgrade), add its `BlockMeta` + regen docs, and drop the AppConfig entry. For a v2 upgrade, this is also when v1 gets `hideFromToolbar: true` (the superseded-version paradigm).
+
+## Kill switch (shipped blocks)
+
+To pull an already-GA block from discovery surfaces on hosted (incident, deprecation): add `{ "<block-type>": { "enabled": false } }` to the document. Allowlist clauses can carve out exceptions. **Execution is NOT stopped** — workflows already using the block keep running; the kill switch only prevents new placement/discovery.
+
+## Invariants (do not violate)
+
+- **Execution is never gated.** The executor, serializer, drop-naming, and `isBlockTypeAccessControlExempt` resolve via pure `getBlock`. Do not add visibility checks to execution paths.
+- **Clone-not-remove:** gated blocks stay in `getAllBlocks()` output as clones with `hideFromToolbar: true` — `.find`-by-type consumers rely on this. Never filter them out.
+- **Keys are registry block types.** Never `custom_block_*` (parse drops them — custom blocks have their own enabled/disabled lifecycle).
+- **The shared hidden-predicate is `isHiddenUnder`** (`apps/sim/blocks/visibility/context.ts`). Never restate the preview/disabled rule inline at a new consumer.
+- **Process-global caches stay ungated.** `getStaticComponentFiles` (VFS) and `getExposedIntegrationTools` build the ungated universe; per-viewer filtering happens at stamp/consumer time. Never move gating into a shared builder.
+- Gating is **surface hiding, not secrecy** — the full config ships in the client JS bundle. Anything truly secret cannot be a registered block.
+
+## Tests
+
+Evaluation semantics: `apps/sim/lib/core/config/block-visibility.test.ts`. Registry projection: `apps/sim/blocks/visibility/visibility.test.ts`. When gating behavior changes, extend those — mock `isPlatformAdmin` for the admin clause; use the local `withAppConfig` harness.

apps/sim/app/api/blocks/visibility/route.test.ts

@@ -0,0 +1,84 @@
+/**
+ * @vitest-environment node
+ */
+import { NextRequest } from 'next/server'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockGetSession, mockCheckWorkspaceAccess, mockIsPlatformAdmin, mockGetBlockVisibility } =
+  vi.hoisted(() => ({
+    mockGetSession: vi.fn(),
+    mockCheckWorkspaceAccess: vi.fn(),
+    mockIsPlatformAdmin: vi.fn(),
+    mockGetBlockVisibility: vi.fn(),
+  }))
+
+vi.mock('@/lib/auth', () => ({
+  auth: { api: { getSession: vi.fn() } },
+  getSession: mockGetSession,
+}))
+
+vi.mock('@/lib/workspaces/permissions/utils', () => ({
+  checkWorkspaceAccess: mockCheckWorkspaceAccess,
+}))
+
+vi.mock('@/lib/permissions/super-user', () => ({
+  isPlatformAdmin: mockIsPlatformAdmin,
+}))
+
+vi.mock('@/lib/core/config/block-visibility', () => ({
+  getBlockVisibility: mockGetBlockVisibility,
+}))
+
+import { GET } from '@/app/api/blocks/visibility/route'
+
+const WORKSPACE_ID = '11111111-2222-4333-8444-555555555555'
+
+function request(workspaceId = WORKSPACE_ID) {
+  return new NextRequest(`http://localhost/api/blocks/visibility?workspaceId=${workspaceId}`)
+}
+
+describe('GET /api/blocks/visibility', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockGetSession.mockResolvedValue({ user: { id: 'user-1' } })
+    mockCheckWorkspaceAccess.mockResolvedValue({
+      hasAccess: true,
+      workspace: { organizationId: 'org-1' },
+    })
+    mockIsPlatformAdmin.mockResolvedValue(false)
+    mockGetBlockVisibility.mockResolvedValue({
+      revealed: new Set(['gmail_v2']),
+      disabled: new Set(['slack']),
+      previewTagged: new Set(['gmail_v2']),
+    })
+  })
+
+  it('returns 401 without a session', async () => {
+    mockGetSession.mockResolvedValue(null)
+    const response = await GET(request())
+    expect(response.status).toBe(401)
+  })
+
+  it('returns 403 without workspace access', async () => {
+    mockCheckWorkspaceAccess.mockResolvedValue({ hasAccess: false, workspace: null })
+    const response = await GET(request())
+    expect(response.status).toBe(403)
+    expect(mockGetBlockVisibility).not.toHaveBeenCalled()
+  })
+
+  it('evaluates visibility for the session user, workspace org, and pre-resolved admin', async () => {
+    mockIsPlatformAdmin.mockResolvedValue(true)
+    const response = await GET(request())
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({
+      revealed: ['gmail_v2'],
+      disabled: ['slack'],
+      previewTagged: ['gmail_v2'],
+    })
+    expect(mockGetBlockVisibility).toHaveBeenCalledWith({
+      userId: 'user-1',
+      orgId: 'org-1',
+      isAdmin: true,
+    })
+  })
+})

apps/sim/app/api/blocks/visibility/route.ts

@@ -0,0 +1,46 @@
+import type { NextRequest } from 'next/server'
+import { NextResponse } from 'next/server'
+import { getBlockVisibilityContract } from '@/lib/api/contracts/block-visibility'
+import { parseRequest } from '@/lib/api/server'
+import { getSession } from '@/lib/auth'
+import { getBlockVisibility } from '@/lib/core/config/block-visibility'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { isPlatformAdmin } from '@/lib/permissions/super-user'
+import { checkWorkspaceAccess } from '@/lib/workspaces/permissions/utils'
+
+/**
+ * Evaluates the viewer's block-visibility projection for a workspace: which
+ * preview blocks are revealed (and preview-tagged) and which shipped blocks are
+ * kill-switched. Consumed by the client visibility overlay
+ * (`BlockVisibilityLoader`); discovery-only — execution is never gated.
+ */
+export const GET = withRouteHandler(async (request: NextRequest) => {
+  const session = await getSession()
+  if (!session?.user?.id) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const parsed = await parseRequest(getBlockVisibilityContract, request, {})
+  if (!parsed.success) return parsed.response
+
+  const userId = session.user.id
+  const { workspaceId } = parsed.data.query
+
+  const access = await checkWorkspaceAccess(workspaceId, userId)
+  if (!access.hasAccess) {
+    return NextResponse.json({ error: 'Access denied' }, { status: 403 })
+  }
+
+  const isAdmin = await isPlatformAdmin(userId)
+  const vis = await getBlockVisibility({
+    userId,
+    orgId: access.workspace?.organizationId,
+    isAdmin,
+  })
+
+  return NextResponse.json({
+    revealed: [...vis.revealed],
+    disabled: [...vis.disabled],
+    previewTagged: [...vis.previewTagged],
+  })
+})

apps/sim/app/workspace/[workspaceId]/layout.tsx

@@ -7,6 +7,7 @@ import { getQueryClient } from '@/app/_shell/providers/get-query-client'
 import { ImpersonationBanner } from '@/app/workspace/[workspaceId]/components/impersonation-banner'
 import { WorkspaceChrome } from '@/app/workspace/[workspaceId]/components/workspace-chrome'
 import { prefetchWorkspaceSidebar } from '@/app/workspace/[workspaceId]/prefetch'
+import { BlockVisibilityLoader } from '@/app/workspace/[workspaceId]/providers/block-visibility-loader'
 import { CustomBlocksLoader } from '@/app/workspace/[workspaceId]/providers/custom-blocks-loader'
 import { GlobalCommandsProvider } from '@/app/workspace/[workspaceId]/providers/global-commands-provider'
 import { ProviderModelsLoader } from '@/app/workspace/[workspaceId]/providers/provider-models-loader'
@@ -45,6 +46,7 @@ export default async function WorkspaceLayout({
         <SettingsLoader />
         <ProviderModelsLoader />
         <CustomBlocksLoader />
+        <BlockVisibilityLoader />
         <GlobalCommandsProvider>
           <div className='flex h-screen w-full flex-col overflow-hidden bg-[var(--surface-1)]'>
             <ImpersonationBanner />

apps/sim/app/workspace/[workspaceId]/providers/block-visibility-loader.tsx

@@ -0,0 +1,37 @@
+'use client'
+
+import { useEffect } from 'react'
+import { useParams } from 'next/navigation'
+import { hydrateBlockVisibility } from '@/blocks/visibility/client'
+import { useBlockVisibility } from '@/hooks/queries/block-visibility'
+
+/**
+ * Hydrates the client block-visibility overlay for the active workspace so the
+ * registry accessors project the viewer's revealed/disabled preview blocks.
+ * Mounted once in the workspace layout, next to `CustomBlocksLoader`.
+ *
+ * First paint needs no prefetch: `preview: true` blocks are fail-closed until
+ * this hydrate lands, so the fetch only ever reveals (benign pop-in) or applies
+ * a kill switch to an already-public block. Identical refetches are absorbed by
+ * the deep-equal guard inside `hydrateBlockVisibility`.
+ */
+export function BlockVisibilityLoader() {
+  const params = useParams()
+  const workspaceId = params?.workspaceId as string | undefined
+  const { data } = useBlockVisibility(workspaceId)
+
+  useEffect(() => {
+    // On a workspace switch the query key changes and `data` is undefined while
+    // the new projection loads — hydrate an EMPTY (fail-closed) state so the
+    // previous workspace's reveals/kill-switches never linger across orgs.
+    // The empty-while-null guard inside hydrateBlockVisibility makes the first
+    // mount free.
+    hydrateBlockVisibility({
+      revealed: new Set(data?.revealed),
+      disabled: new Set(data?.disabled),
+      previewTagged: new Set(data?.previewTagged),
+    })
+  }, [data])
+
+  return null
+}

apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/copilot/components/user-input/hooks/use-mention-data.ts

@@ -7,6 +7,7 @@ import { requestJson } from '@/lib/api/client/request'
 import { listCopilotChatsContract } from '@/lib/api/contracts/copilot'
 import { listKnowledgeBasesContract } from '@/lib/api/contracts/knowledge/base'
 import { listLogsContract } from '@/lib/api/contracts/logs'
+import { useCustomBlockOverlayVersion } from '@/blocks/custom/client-overlay'
 import { type IntegrationDescriptor, listIntegrations } from '@/blocks/integration-matcher'
 import { useWorkflows } from '@/hooks/queries/workflows'
 import { usePermissionConfig } from '@/hooks/use-permission-config'
@@ -130,9 +131,12 @@ export function useMentionData(props: UseMentionDataProps): MentionDataReturn {
   const [blocksList, setBlocksList] = useState<BlockItem[]>([])
   const [isLoadingBlocks, setIsLoadingBlocks] = useState(false)
 
+  // Reset on permission changes and on block-overlay bumps (custom-block or
+  // block-visibility hydrate) so late preview reveals refresh the folder.
+  const blockOverlayVersion = useCustomBlockOverlayVersion()
   useEffect(() => {
     setBlocksList([])
-  }, [config.allowedIntegrations])
+  }, [config.allowedIntegrations, blockOverlayVersion])
 
   const [logsList, setLogsList] = useState<LogItem[]>([])
   const [isLoadingLogs, setIsLoadingLogs] = useState(false)