chore(utils): migrate to shared random/ID utilities and add enforcement linting (#4623)

* chore(utils): migrate to shared random/ID utilities and add enforcement linting

- Replace all Math.random(), crypto.randomUUID(), crypto.randomBytes(), nanoid, and uuid usages with shared @sim/utils/random and @sim/utils/id helpers across 72 files
- Add new @sim/utils exports: deepClone, omit, filterUndefined (object), truncate (string), backoffWithJitter, parseRetryAfter (retry), getErrorMessage (errors)
- Sweep all getErrorMessage, sleep, deepClone callsites across 500+ files to use shared utilities
- Add Biome noRestrictedImports rule to catch nanoid, uuid, and crypto named imports at lint time
- Add scripts/check-utils-enforcement.ts to catch Math.random and crypto.* global property access
- Add check:utils script to package.json

* chore(utils): replace deepClone wrapper with structuredClone built-in

deepClone() was a one-line wrapper around structuredClone(), which is
universally available in Node 17+ and all modern browsers. Removing the
abstraction reduces indirection and means contributors don't need to
learn a project-specific name for a well-known built-in.

- Remove deepClone from packages/utils/src/object.ts and index.ts
- Replace all 17 call sites with structuredClone() directly
- Update check:utils script suggestion text
- Update CLAUDE.md and global.md docs

* fix(utils): add missing biome noRestrictedImports rule and correct truncate docs

- Add noRestrictedImports to biome.json under style — bans nanoid and uuid
  package imports at lint time (crypto.randomUUID/randomBytes are caught by
  the check:utils grep script which handles global property access)
- Correct truncate() TSDoc and parameter name: sliceLength makes it clear
  that total output length is sliceLength + suffix.length, matching the
  behavior all callers were already written to expect

* fix(utils): add missing getErrorMessage imports at 4 call sites

The sweep agents added getErrorMessage calls without the corresponding
import in 4 files, causing test failures. Added the missing imports.

* fix(utils): fix build errors from getErrorMessage sweep and retry.ts Turbopack issue

- Fix retry.ts cross-file import: Turbopack cannot resolve './random.js' for
  internal package imports; inline the jitter crypto call directly
- Add missing getErrorMessage imports to 32 files where the sweep added calls
  without the corresponding import (caught by type-check and test runs)
- Remove accidental getErrorMessage import from crowdstrike/query/route.ts
  which has its own domain-specific getErrorMessage for parsing CrowdStrike's
  JSON error format
- Fix use-sub-block-value.ts type error from structuredClone narrowing:
  add 'as T' cast at emitValue callsite (safe — valueCopy is always a
  structural copy of newValue)

* fix(tools): use toError in crowdstrike catch block instead of local getErrorMessage

The catch block was calling the local getErrorMessage function which
parses CrowdStrike API JSON responses, not JavaScript Error objects.
Use toError(error).message to correctly extract the message from a
caught value in this context.

Author: waleedlatif1

.claude/rules/global.md

@@ -36,22 +36,31 @@ const tiny = generateShortId(8)
 ## Common Utilities
 Use shared helpers from `@sim/utils` instead of writing inline implementations:
 
-- `sleep(ms)` — async delay. Never write `new Promise(resolve => setTimeout(resolve, ms))`
-- `toError(value)` — normalize unknown caught values to `Error`. Never write `e instanceof Error ? e : new Error(String(e))`
-- `toError(value).message` — get error message safely. Never write `e instanceof Error ? e.message : String(e)`
+- `sleep(ms)` from `@sim/utils/helpers` — async delay. Never write `new Promise(resolve => setTimeout(resolve, ms))`
+- `toError(value)` from `@sim/utils/errors` — normalize unknown caught values to `Error`. Never write `e instanceof Error ? e : new Error(String(e))`
+- `getErrorMessage(value, fallback?)` from `@sim/utils/errors` — extract error message string. Never write `e instanceof Error ? e.message : 'fallback'`
+- `structuredClone(value)` — built-in deep clone, no import needed. Never write `JSON.parse(JSON.stringify(obj))`
+- `omit(obj, keys)` from `@sim/utils/object` — remove keys from object
+- `filterUndefined(obj)` from `@sim/utils/object` — strip undefined-valued keys. Never write `Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined))`
+- `truncate(str, maxLength, suffix?)` from `@sim/utils/string` — safe string truncation with ellipsis
+- `backoffWithJitter(attempt, retryAfterMs, options?)` from `@sim/utils/retry` — exponential backoff with jitter
+- `parseRetryAfter(header)` from `@sim/utils/retry` — parse HTTP `Retry-After` header to milliseconds
 
 ```typescript
 // ✗ Bad
 await new Promise(resolve => setTimeout(resolve, 1000))
-const msg = error instanceof Error ? error.message : String(error)
-const err = error instanceof Error ? error : new Error(String(error))
+const msg = error instanceof Error ? error.message : 'Unknown error'
+const clone = JSON.parse(JSON.stringify(obj))
+const filtered = Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined))
 
 // ✓ Good
 import { sleep } from '@sim/utils/helpers'
-import { toError } from '@sim/utils/errors'
+import { getErrorMessage, toError } from '@sim/utils/errors'
+import { filterUndefined } from '@sim/utils/object'
 await sleep(1000)
-const msg = toError(error).message
-const err = toError(error)
+const msg = getErrorMessage(error, 'Unknown error')
+const clone = structuredClone(obj)
+const filtered = filterUndefined(obj)
 ```
 
 ## Package Manager

CLAUDE.md

@@ -10,7 +10,14 @@ You are a professional software engineer. All code must follow best practices: a
 - **Comments**: Use TSDoc for documentation. No `====` separators. No non-TSDoc comments
 - **Styling**: Never update global styles. Keep all styling local to components
 - **ID Generation**: Never use `crypto.randomUUID()`, `nanoid`, or `uuid` package. Use `generateId()` (UUID v4) or `generateShortId()` (compact) from `@sim/utils/id`
-- **Common Utilities**: Use shared helpers from `@sim/utils` instead of inline implementations. `sleep(ms)` from `@sim/utils/helpers` for delays, `toError(e)` from `@sim/utils/errors` to normalize caught values.
+- **Common Utilities**: Use shared helpers from `@sim/utils` instead of inline implementations:
+  - `sleep(ms)` from `@sim/utils/helpers` — never `new Promise(resolve => setTimeout(resolve, ms))`
+  - `toError(e)` from `@sim/utils/errors` — normalize caught values to `Error`
+  - `getErrorMessage(e, fallback?)` from `@sim/utils/errors` — extract message string from unknown caught value; never write `e instanceof Error ? e.message : 'fallback'`
+  - `structuredClone(value)` — built-in deep clone; never `JSON.parse(JSON.stringify(...))`
+  - `omit(obj, keys)` / `filterUndefined(obj)` from `@sim/utils/object` — object trimming; never `Object.fromEntries(Object.entries(...).filter(...))`
+  - `truncate(str, maxLength, suffix?)` from `@sim/utils/string` — never inline slice + ellipsis
+  - `backoffWithJitter(attempt, retryAfterMs, options?)` / `parseRetryAfter(header)` from `@sim/utils/retry` — shared retry pacing; never reimplement exponential backoff inline
 - **Package Manager**: Use `bun` and `bunx`, not `npm` and `npx`
 
 ## Architecture

apps/realtime/src/database/operations.ts

@@ -13,6 +13,7 @@ import {
   VARIABLE_OPERATIONS,
   WORKFLOW_OPERATIONS,
 } from '@sim/realtime-protocol/constants'
+import { randomFloat } from '@sim/utils/random'
 import { getActiveWorkflowContext } from '@sim/workflow-authz'
 import { loadWorkflowFromNormalizedTablesRaw } from '@sim/workflow-persistence/load'
 import { mergeSubBlockValues } from '@sim/workflow-persistence/subblocks'
@@ -204,7 +205,7 @@ export async function persistWorkflowOperation(workflowId: string, operation: an
       throw new Error(`Workflow ${workflowId} is archived or unavailable`)
     }
 
-    if (op === BLOCK_OPERATIONS.UPDATE_POSITION && Math.random() < 0.01) {
+    if (op === BLOCK_OPERATIONS.UPDATE_POSITION && randomFloat() < 0.01) {
       logger.debug('Socket DB operation sample:', {
         operation: op,
         target,

apps/realtime/src/handlers/operations.ts

@@ -9,6 +9,7 @@ import {
   WORKFLOW_OPERATIONS,
 } from '@sim/realtime-protocol/constants'
 import { WorkflowOperationSchema } from '@sim/realtime-protocol/schemas'
+import { getErrorMessage } from '@sim/utils/errors'
 import { generateId } from '@sim/utils/id'
 import { assertWorkflowMutable, WorkflowLockedError } from '@sim/workflow-authz'
 import { ZodError } from 'zod'
@@ -205,7 +206,7 @@ export function setupOperationsHandlers(socket: AuthenticatedSocket, roomManager
           if (operationId) {
             socket.emit('operation-failed', {
               operationId,
-              error: error instanceof Error ? error.message : 'Database persistence failed',
+              error: getErrorMessage(error, 'Database persistence failed'),
               retryable: true,
             })
           }
@@ -247,7 +248,7 @@ export function setupOperationsHandlers(socket: AuthenticatedSocket, roomManager
           if (operationId) {
             socket.emit('operation-failed', {
               operationId,
-              error: error instanceof Error ? error.message : 'Database persistence failed',
+              error: getErrorMessage(error, 'Database persistence failed'),
               retryable: true,
             })
           }
@@ -587,7 +588,7 @@ export function setupOperationsHandlers(socket: AuthenticatedSocket, roomManager
         })
       }
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred'
+      const errorMessage = getErrorMessage(error, 'Unknown error occurred')
 
       if (operationId) {
         socket.emit('operation-failed', {

apps/realtime/src/handlers/subblocks.ts

@@ -2,6 +2,7 @@ import { db } from '@sim/db'
 import { workflow, workflowBlocks } from '@sim/db/schema'
 import { createLogger } from '@sim/logger'
 import { SUBBLOCK_OPERATIONS } from '@sim/realtime-protocol/constants'
+import { getErrorMessage } from '@sim/utils/errors'
 import { assertWorkflowMutable, WorkflowLockedError } from '@sim/workflow-authz'
 import { isWorkflowBlockProtected } from '@sim/workflow-types/workflow'
 import { and, eq } from 'drizzle-orm'
@@ -208,7 +209,7 @@ export function setupSubblocksHandlers(socket: AuthenticatedSocket, roomManager:
     } catch (error) {
       logger.error('Error handling subblock update:', error)
 
-      const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+      const errorMessage = getErrorMessage(error, 'Unknown error')
 
       if (operationId) {
         socket.emit('operation-failed', {
@@ -360,7 +361,7 @@ async function flushSubblockUpdate(
     pending.opToSocket.forEach((socketId, opId) => {
       io.to(socketId).emit('operation-failed', {
         operationId: opId,
-        error: error instanceof Error ? error.message : 'Unknown error',
+        error: getErrorMessage(error, 'Unknown error'),
         retryable: true,
       })
     })

apps/realtime/src/handlers/variables.ts

@@ -2,6 +2,7 @@ import { db } from '@sim/db'
 import { workflow } from '@sim/db/schema'
 import { createLogger } from '@sim/logger'
 import { VARIABLE_OPERATIONS } from '@sim/realtime-protocol/constants'
+import { getErrorMessage } from '@sim/utils/errors'
 import { assertWorkflowMutable, WorkflowLockedError } from '@sim/workflow-authz'
 import { eq } from 'drizzle-orm'
 import type { AuthenticatedSocket } from '@/middleware/auth'
@@ -195,7 +196,7 @@ export function setupVariablesHandlers(socket: AuthenticatedSocket, roomManager:
     } catch (error) {
       logger.error('Error handling variable update:', error)
 
-      const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+      const errorMessage = getErrorMessage(error, 'Unknown error')
 
       if (operationId) {
         socket.emit('operation-failed', {
@@ -326,7 +327,7 @@ async function flushVariableUpdate(
     pending.opToSocket.forEach((socketId, opId) => {
       io.to(socketId).emit('operation-failed', {
         operationId: opId,
-        error: error instanceof Error ? error.message : 'Unknown error',
+        error: getErrorMessage(error, 'Unknown error'),
         retryable: true,
       })
     })

apps/realtime/src/index.test.ts

@@ -5,6 +5,7 @@
  */
 import { createServer, request as httpRequest } from 'http'
 import { createMockLogger } from '@sim/testing'
+import { randomInt } from '@sim/utils/random'
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
 import { createSocketIOServer } from '@/config/socket'
 import { MemoryRoomManager } from '@/rooms'
@@ -95,7 +96,7 @@ describe('Socket Server Index Integration', () => {
   })
 
   beforeEach(async () => {
-    PORT = 3333 + Math.floor(Math.random() * 1000)
+    PORT = 3333 + randomInt(0, 1000)
 
     httpServer = createServer()
 
@@ -120,7 +121,7 @@ describe('Socket Server Index Integration', () => {
       httpServer.on('error', (err: any) => {
         clearTimeout(timeout)
         if (err.code === 'EADDRINUSE') {
-          PORT = 3333 + Math.floor(Math.random() * 1000)
+          PORT = 3333 + randomInt(0, 1000)
           httpServer.close(() => {
             httpServer.listen(PORT, '0.0.0.0', () => {
               resolve()

apps/sim/app/(auth)/login/login-form.tsx

@@ -2,6 +2,7 @@
 
 import { useEffect, useRef, useState } from 'react'
 import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
 import { Eye, EyeOff } from 'lucide-react'
 import Link from 'next/link'
 import { useRouter, useSearchParams } from 'next/navigation'
@@ -292,8 +293,7 @@ export default function LoginPage({
           },
         })
       } catch (requestError) {
-        let errorMessage =
-          requestError instanceof Error ? requestError.message : 'Failed to request password reset'
+        let errorMessage = getErrorMessage(requestError, 'Failed to request password reset')
 
         if (
           errorMessage.includes('Invalid body parameters') ||
@@ -325,7 +325,7 @@ export default function LoginPage({
       logger.error('Error requesting password reset:', { error })
       setResetStatus({
         type: 'error',
-        message: error instanceof Error ? error.message : 'Failed to request password reset',
+        message: getErrorMessage(error, 'Failed to request password reset'),
       })
     } finally {
       setIsSubmittingReset(false)

apps/sim/app/(auth)/reset-password/reset-password-content.tsx

@@ -2,6 +2,7 @@
 
 import { Suspense, useState } from 'react'
 import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
 import Link from 'next/link'
 import { useRouter, useSearchParams } from 'next/navigation'
 import { requestJson } from '@/lib/api/client/request'
@@ -53,7 +54,7 @@ function ResetPasswordContent() {
       logger.error('Error resetting password:', { error })
       setStatusMessage({
         type: 'error',
-        text: error instanceof Error ? error.message : 'Failed to reset password',
+        text: getErrorMessage(error, 'Failed to reset password'),
       })
     } finally {
       setIsSubmitting(false)

apps/sim/app/api/a2a/serve/[agentId]/route.ts

@@ -2,6 +2,7 @@ import type { Artifact, Message, PushNotificationConfig, TaskState } from '@a2a-
 import { db } from '@sim/db'
 import { a2aAgent, a2aPushNotificationConfig, a2aTask, workflow } from '@sim/db/schema'
 import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
 import { generateId } from '@sim/utils/id'
 import { and, eq, isNull } from 'drizzle-orm'
 import { type NextRequest, NextResponse } from 'next/server'
@@ -1394,7 +1395,7 @@ async function handleTaskResubscribe(
           logger.error('Error during SSE poll:', error)
           sendEvent('error', {
             code: A2A_ERROR_CODES.INTERNAL_ERROR,
-            message: error instanceof Error ? error.message : 'Polling failed',
+            message: getErrorMessage(error, 'Polling failed'),
           })
           cleanup()
           try {