more comments

Author: icecrasher321

apps/sim/AGENTS.md

@@ -5,6 +5,7 @@ These rules apply to files under `apps/sim/` in addition to the repository root
 ## Architecture
 
 ### Core Principles
+
 1. **Single Responsibility**: Each component, hook, store has one clear purpose
 2. **Composition Over Complexity**: Break down complex logic into smaller pieces
 3. **Type Safety First**: TypeScript interfaces for all props, state, return types
@@ -47,6 +48,7 @@ feature/
 ```
 
 ### Naming Conventions
+
 - **Components**: PascalCase (`WorkflowList`)
 - **Hooks**: `use` prefix (`useWorkflowOperations`)
 - **Files**: kebab-case (`workflow-list.tsx`)
@@ -71,7 +73,7 @@ feature/
 
 ## API Contracts
 
-Boundary HTTP request and response shapes for all routes under `apps/sim/app/api/**` live in `apps/sim/lib/api/contracts/**` (one file per resource family). Routes never define route-local boundary Zod schemas, and clients never define ad-hoc wire types — both sides consume the same contract.
+Boundary HTTP request and response shapes for all routes under `apps/sim/app/api/`** live in `apps/sim/lib/api/contracts/**` (one file per resource family). Routes never define route-local boundary Zod schemas, and clients never define ad-hoc wire types — both sides consume the same contract.
 
 - Each contract is built with `defineRouteContract({ method, path, params?, query?, body?, headers?, response: { mode: 'json', schema } })` from `@/lib/api/contracts`.
 - Contracts export named schemas AND named TypeScript type aliases (e.g., `export type CreateFolderBody = z.input<typeof createFolderBodySchema>`). Clients import the named aliases — never `z.input<...>` / `z.output<...>` in hooks.
@@ -83,10 +85,10 @@ Boundary HTTP request and response shapes for all routes under `apps/sim/app/api
 
 A small number of legitimate exceptions to the boundary rules are tolerated when annotated. The audit script recognizes four annotation forms:
 
-- `// boundary-raw-fetch: <reason>` — placed on the line directly above a raw `fetch(` call inside `apps/sim/hooks/queries/**` or `apps/sim/hooks/selectors/**`. Use only for documented exceptions: streaming responses, binary downloads, multipart uploads, signed-URL flows, OAuth redirects, and external-origin requests.
+- `// boundary-raw-fetch: <reason>` — placed on the line directly above a raw `fetch(` call inside `apps/sim/hooks/queries/**`, `apps/sim/hooks/selectors/**`, or any other client/UI source under `apps/sim/**` that targets a same-origin `/api/...` URL. Use only for documented exceptions: streaming responses, binary downloads, multipart uploads, signed-URL flows, OAuth redirects, and external-origin requests.
 - `// double-cast-allowed: <reason>` — placed on the line directly above an `as unknown as X` cast outside test files.
-- `// boundary-raw-json: <reason>` — placed on the line directly above a raw `await request.json()` / `await req.json()` read in a route handler. Use only when the body is a JSON-RPC envelope, a tolerant `.catch(() => ({}))` parse, or otherwise cannot go through `parseRequest`.
-- `// untyped-response: <reason>` — placed on the line directly above a `schema: z.unknown()` response declaration in a contract file. Use only when the response body is genuinely opaque (user-supplied data, third-party passthrough).
+- `// boundary-raw-json: <reason>` — placed on the line directly above a raw `await request.json()` / `await req.json()` read (or the multi-line `await request.clone().json()` shim variant) in a route handler. Use only when the body is a JSON-RPC envelope, a tolerant `.catch(() => ({}))` parse, or otherwise cannot go through `parseRequest`.
+- `// untyped-response: <reason>` — placed on the line directly above a `schema: z.unknown()` / `schema: z.object({}).passthrough()` / `schema: z.record(z.string(), z.unknown())` response declaration (or a simple alias to one of those) in a contract file. Use only when the response body is genuinely opaque (user-supplied data, third-party passthrough).
 
 Placement rule: the annotation must immediately precede the call or cast. Up to three non-empty preceding comment lines are tolerated, so additional context comments above the annotation are fine. The reason must be non-empty after trimming — annotations with empty reasons fail strict mode (`annotationsMissingReason`).
 
@@ -104,6 +106,19 @@ const response = await fetch(`/api/copilot/chat/stream?chatId=${chatId}`, { sign
 const provider = config as unknown as LegacyProvider
 ```
 
+```ts
+// boundary-raw-json: shim pre-validates the mothership envelope before delegating to the copilot handler that consumes the body
+const body = await request
+  .clone()
+  .json()
+  .catch(() => undefined)
+```
+
+```ts
+// untyped-response: forwards firecrawl /v2/parse response unchanged for downstream tool consumers
+output: z.unknown(),
+```
+
 ## API Route Pattern
 
 Routes never `import { z } from 'zod'` and never define route-local boundary schemas. They consume the contract from `@/lib/api/contracts/**` and validate with canonical helpers from `@/lib/api/server`:
@@ -149,18 +164,18 @@ When adding a new route + client surface, follow this order. Each step has one p
 
 LLMs will write contracts that compile but are sloppy. The human reviewer should optimize attention on:
 
-- **`required` vs `optional` vs `nullable` is correct**. `optional()` allows omission; `nullable()` allows `null`; chaining both creates a tri-state that's almost never what you want.
+- `**required` vs `optional` vs `nullable` is correct**. `optional()` allows omission; `nullable()` allows `null`; chaining both creates a tri-state that's almost never what you want.
 - **Response schema matches the route's actual JSON output**. The most common drift bug — route emits a field the schema doesn't declare, or omits a required field. Walk every `NextResponse.json(...)` callsite against the schema.
 - **Error messages are descriptive**. `'fileName cannot be empty'` beats `'Required'`. Use the second arg of `min(1, '...')`, `nonempty('...')`, etc. For cross-field refines, use `superRefine` with a `path` and a message that names the failing field.
 - **Bounds are set** on arrays (`.min(1)`, `.max(N)`), strings (`.min(1).max(N)` for IDs/names), and numbers (`.min().max()` for limits/sizes).
-- **`z.unknown()` is a smell** unless the data is genuinely arbitrary (provider passthrough, user-defined tool result, JSON-RPC envelope). When kept, must be annotated `// untyped-response: <specific reason>` in a `schema:` slot.
+- `**z.unknown()` is a smell** unless the data is genuinely arbitrary (provider passthrough, user-defined tool result, JSON-RPC envelope). When kept, must be annotated `// untyped-response: <specific reason>` in a `schema:` slot.
 - **Discriminated unions over plain unions** when the wire has a discriminant field — gives clients exhaustive narrowing.
 
 CI (`bun run check:api-validation:strict`) catches structural violations (Zod imports in routes, raw `request.json()`, double casts, missing annotations). It does **not** catch these schema-quality judgments — that's the human's job in PR review.
 
 ## React Query Client Boundary
 
-Hooks in `apps/sim/hooks/queries/**` consume contracts the same way routes do. Every same-origin JSON call must go through `requestJson(contract, ...)` from `@/lib/api/client/request` instead of raw `fetch`:
+Hooks in `apps/sim/hooks/queries/`** consume contracts the same way routes do. Every same-origin JSON call must go through `requestJson(contract, ...)` from `@/lib/api/client/request` instead of raw `fetch`:
 
 - Hooks import named type aliases from `@/lib/api/contracts/**`. Never write `z.input<...>` / `z.output<...>` in hooks, and never `import { z } from 'zod'` in client code.
 - `requestJson` parses params, query, body, and headers against the contract on the way out and validates the JSON response on the way back. Hooks always forward `signal` for cancellation.
@@ -204,3 +219,4 @@ export function useEntityList(workspaceId?: string) {
 - **Create `utils.ts` when** 2+ files need the same helper
 - **Check existing sources** before duplicating (`lib/` has many utilities)
 - **Location**: `lib/` (app-wide) → `feature/utils/` (feature-scoped) → inline (single-use)
+

apps/sim/app/api/mothership/chat/abort/route.ts

@@ -1,9 +1,11 @@
 import type { NextRequest } from 'next/server'
 import { mothershipChatAbortEnvelopeSchema } from '@/lib/api/contracts/mothership-tasks'
 import { validationErrorResponse } from '@/lib/api/server'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { POST as copilotAbortPost } from '@/app/api/copilot/chat/abort/route'
 
-export async function POST(request: NextRequest) {
+export const POST = withRouteHandler(async (request: NextRequest) => {
+  // boundary-raw-json: shim pre-validates the mothership envelope before delegating to the copilot handler that consumes the body
   const body = await request
     .clone()
     .json()
@@ -14,4 +16,4 @@ export async function POST(request: NextRequest) {
   }
 
   return copilotAbortPost(request, undefined)
-}
+})

apps/sim/app/api/mothership/chat/resources/route.ts

@@ -1,13 +1,15 @@
 import type { NextRequest, NextResponse } from 'next/server'
 import { mothershipChatResourceEnvelopeSchema } from '@/lib/api/contracts/mothership-tasks'
 import { validationErrorResponse } from '@/lib/api/server'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import {
   DELETE as copilotResourcesDelete,
   PATCH as copilotResourcesPatch,
   POST as copilotResourcesPost,
 } from '@/app/api/copilot/chat/resources/route'
 
 async function validateResourceRequestEnvelope(request: NextRequest): Promise<NextResponse | null> {
+  // boundary-raw-json: shim pre-validates the mothership envelope before delegating to the copilot handler that consumes the body
   const body = await request
     .clone()
     .json()
@@ -19,23 +21,23 @@ async function validateResourceRequestEnvelope(request: NextRequest): Promise<Ne
   return null
 }
 
-export async function POST(request: NextRequest) {
+export const POST = withRouteHandler(async (request: NextRequest) => {
   const validationResponse = await validateResourceRequestEnvelope(request)
   if (validationResponse) return validationResponse
 
   return copilotResourcesPost(request, undefined)
-}
+})
 
-export async function PATCH(request: NextRequest) {
+export const PATCH = withRouteHandler(async (request: NextRequest) => {
   const validationResponse = await validateResourceRequestEnvelope(request)
   if (validationResponse) return validationResponse
 
   return copilotResourcesPatch(request, undefined)
-}
+})
 
-export async function DELETE(request: NextRequest) {
+export const DELETE = withRouteHandler(async (request: NextRequest) => {
   const validationResponse = await validateResourceRequestEnvelope(request)
   if (validationResponse) return validationResponse
 
   return copilotResourcesDelete(request, undefined)
-}
+})

apps/sim/app/api/mothership/chat/route.ts

@@ -1,9 +1,10 @@
-import type { NextRequest } from 'next/server'
+import { type NextRequest, NextResponse } from 'next/server'
 import {
   mothershipChatGetQuerySchema,
   mothershipChatPostEnvelopeSchema,
 } from '@/lib/api/contracts/mothership-tasks'
 import { validationErrorResponse } from '@/lib/api/server'
+import { getSession } from '@/lib/auth'
 import { handleUnifiedChatPost, maxDuration } from '@/lib/copilot/chat/post'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { GET as copilotChatGet } from '@/app/api/copilot/chat/queries'
@@ -21,6 +22,12 @@ export const GET = withRouteHandler((request: NextRequest) => {
 })
 
 export const POST = withRouteHandler(async (request: NextRequest) => {
+  const session = await getSession()
+  if (!session?.user?.id) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  // boundary-raw-json: shim pre-validates the mothership envelope before delegating to the copilot handler that consumes the body
   const body = await request
     .clone()
     .json()

apps/sim/app/api/mothership/chat/stop/route.ts

@@ -1,10 +1,11 @@
 import type { NextRequest } from 'next/server'
 import { mothershipChatStopEnvelopeSchema } from '@/lib/api/contracts/mothership-tasks'
 import { validationErrorResponse } from '@/lib/api/server'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { POST as copilotStopPost } from '@/app/api/copilot/chat/stop/route'
 
-// Unified stop route surface.
-export async function POST(request: NextRequest) {
+export const POST = withRouteHandler(async (request: NextRequest) => {
+  // boundary-raw-json: shim pre-validates the mothership envelope before delegating to the copilot handler that consumes the body
   const body = await request
     .clone()
     .json()
@@ -15,4 +16,4 @@ export async function POST(request: NextRequest) {
   }
 
   return copilotStopPost(request, undefined)
-}
+})

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

@@ -347,12 +347,22 @@ export const PUT = withRouteHandler(
         }
       }
 
-      // Update the workflow
       const [updatedWorkflow] = await db
         .update(workflow)
         .set(updateData)
         .where(eq(workflow.id, workflowId))
-        .returning()
+        .returning({
+          id: workflow.id,
+          name: workflow.name,
+          description: workflow.description,
+          color: workflow.color,
+          workspaceId: workflow.workspaceId,
+          folderId: workflow.folderId,
+          sortOrder: workflow.sortOrder,
+          createdAt: workflow.createdAt,
+          updatedAt: workflow.updatedAt,
+          archivedAt: workflow.archivedAt,
+        })
 
       const elapsed = Date.now() - startTime
       logger.info(`[${requestId}] Successfully updated workflow ${workflowId} in ${elapsed}ms`, {

apps/sim/app/api/workflows/route.ts

@@ -13,7 +13,7 @@ import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { captureServerEvent } from '@/lib/posthog/server'
 import { buildDefaultWorkflowArtifacts } from '@/lib/workflows/defaults'
 import { saveWorkflowToNormalizedTables } from '@/lib/workflows/persistence/utils'
-import { deduplicateWorkflowName, listWorkflows } from '@/lib/workflows/utils'
+import { deduplicateWorkflowName } from '@/lib/workflows/utils'
 import { getUserEntityPermissions, workspaceExists } from '@/lib/workspaces/permissions/utils'
 import { verifyWorkspaceMembership } from '@/app/api/workflows/utils'
 
@@ -69,10 +69,39 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
 
     let workflows
 
+    /**
+     * Project only the columns declared in `workflowListItemSchema` so the
+     * wire response matches the contract shape exactly. The full row is
+     * larger (`state`, `variables`, `apiKey`, `runCount`, etc.) and would
+     * be dropped client-side by Zod parse anyway — narrowing here saves
+     * bytes over the wire. Keep this list aligned with the contract.
+     */
+    const listColumns = {
+      id: workflow.id,
+      name: workflow.name,
+      description: workflow.description,
+      color: workflow.color,
+      workspaceId: workflow.workspaceId,
+      folderId: workflow.folderId,
+      sortOrder: workflow.sortOrder,
+      createdAt: workflow.createdAt,
+      updatedAt: workflow.updatedAt,
+      archivedAt: workflow.archivedAt,
+    } as const
     const orderByClause = [asc(workflow.sortOrder), asc(workflow.createdAt), asc(workflow.id)]
 
     if (workspaceId) {
-      workflows = await listWorkflows(workspaceId, { scope })
+      workflows = await db
+        .select(listColumns)
+        .from(workflow)
+        .where(
+          scope === 'all'
+            ? eq(workflow.workspaceId, workspaceId)
+            : scope === 'archived'
+              ? and(eq(workflow.workspaceId, workspaceId), sql`${workflow.archivedAt} IS NOT NULL`)
+              : and(eq(workflow.workspaceId, workspaceId), isNull(workflow.archivedAt))
+        )
+        .orderBy(...orderByClause)
     } else {
       const workspacePermissionRows = await db
         .select({ workspaceId: permissions.entityId })
@@ -83,7 +112,7 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
         return NextResponse.json({ data: [] }, { status: 200 })
       }
       workflows = await db
-        .select()
+        .select(listColumns)
         .from(workflow)
         .where(
           scope === 'all'

apps/sim/app/workspace/page.tsx

@@ -88,8 +88,7 @@ async function handleWorkflowRedirect(
     const workflowData = await requestJson(getWorkflowStateContract, {
       params: { id: workflowId },
     })
-    const data = workflowData.data as Record<string, unknown> | undefined
-    const workspaceId = typeof data?.workspaceId === 'string' ? data.workspaceId : undefined
+    const workspaceId = workflowData.data.workspaceId
     if (workspaceId) {
       logger.info(`Redirecting workflow ${workflowId} to workspace ${workspaceId}`)
       router.replace(`/workspace/${workspaceId}/w/${workflowId}`)

apps/sim/lib/api/contracts/logs.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { booleanQueryFlagSchema } from '@/lib/api/contracts/primitives'
 import { defineRouteContract } from '@/lib/api/contracts/types'
 
 const comparisonOperatorSchema = z.enum(['=', '>', '<', '>=', '<=', '!='])
@@ -131,8 +132,8 @@ export const v1ListLogsQuerySchema = z.object({
   maxCost: z.coerce.number().optional(),
   model: z.string().optional(),
   details: z.enum(['basic', 'full']).optional().default('basic'),
-  includeTraceSpans: z.coerce.boolean().optional().default(false),
-  includeFinalOutput: z.coerce.boolean().optional().default(false),
+  includeTraceSpans: booleanQueryFlagSchema.optional().default(false),
+  includeFinalOutput: booleanQueryFlagSchema.optional().default(false),
   limit: z.coerce.number().optional().default(100),
   cursor: z.string().optional(),
   order: z.enum(['desc', 'asc']).optional().default('desc'),

apps/sim/lib/api/contracts/primitives.ts

@@ -42,3 +42,31 @@ export const workspaceIdSchema = z.string().min(1, 'Workspace ID is required')
  * stable, human-readable message.
  */
 export const workflowIdSchema = z.string().min(1, 'Workflow ID is required')
+
+/**
+ * Boolean query-string primitive that correctly handles the literal strings
+ * `"true"` / `"false"` (case-insensitive) in addition to real booleans.
+ *
+ * Do NOT use `z.coerce.boolean()` for query parameters: it coerces any
+ * non-empty string to `true`, so `?flag=false` resolves to `true`. This
+ * primitive treats `"false"` / `"0"` / `""` as `false` and `"true"` / `"1"`
+ * as `true`, mirroring how query strings are commonly serialized by
+ * frontends and CLIs.
+ *
+ * Real boolean inputs (e.g. when `requestJson` serializes a JS `true`) pass
+ * through unchanged. Anything else fails validation with a clear message.
+ *
+ * Use `.optional()` / `.default(...)` at the call site, not here, so each
+ * query field controls its own omission/default semantics.
+ */
+export const booleanQueryFlagSchema = z.preprocess(
+  (value) => {
+    if (typeof value === 'boolean') return value
+    if (typeof value !== 'string') return value
+    const normalized = value.trim().toLowerCase()
+    if (normalized === 'true' || normalized === '1') return true
+    if (normalized === 'false' || normalized === '0' || normalized === '') return false
+    return value
+  },
+  z.boolean({ error: 'must be a boolean (true/false)' })
+)