more improvements

Author: icecrasher321

.agents/skills/cleanup/SKILL.md

@@ -23,3 +23,8 @@ Run each of these skills in order on the specified scope, passing through the sc
 6. `/emcn-design-review $ARGUMENTS`
 
 After all skills have run, output a summary of what was found and fixed (or proposed) across all six passes.
+
+## Boundary Audit Guidance
+
+- When removing route-local Zod schemas, replacing raw `fetch(` calls in hooks, or removing `as unknown as X` casts, do not introduce `// boundary-raw-fetch: <reason>` or `// double-cast-allowed: <reason>` annotations to silence the audit. Fix the underlying call instead — adopt a contract from `@/lib/api/contracts/**` and use `requestJson(contract, ...)` from `@/lib/api/client/request`, or refine the type so the double cast is unnecessary.
+- Annotations are reserved for legitimate exceptions only: streaming responses, binary downloads, multipart uploads, signed-URL flows, OAuth redirects, external-origin requests, and double casts where no narrower type is available. Each annotation requires a non-empty reason; empty reasons fail `bun run check:api-validation:strict`.

.cursor/rules/sim-architecture.mdc

@@ -65,3 +65,5 @@ Boundary HTTP request and response shapes for all routes under `apps/sim/app/api
 - Clients call `requestJson(contract, ...)` from `apps/sim/lib/api/client/request.ts`; hooks import named type aliases from contracts, never `z.input/z.output`.
 - Routes under `apps/sim/app/api/v1/**` use `apps/sim/app/api/v1/middleware.ts` for shared auth, rate-limit, and workspace access. Compose contract validation inside that middleware.
 - `bun run check:api-validation` enforces this policy and must pass on PRs.
+
+`bun run check:api-validation:strict` is the strict CI gate and additionally fails on annotations with empty reasons. Two per-line opt-out forms are recognized: `// boundary-raw-fetch: <reason>` (placed immediately above a legitimate raw `fetch(` call in `apps/sim/hooks/queries/**` or `apps/sim/hooks/selectors/**` for stream/binary/multipart/signed-URL/OAuth-redirect/external-origin cases) and `// double-cast-allowed: <reason>` (placed immediately above an `as unknown as X` cast outside test files). The reason must be non-empty. Whole-file allowlists for routes that legitimately import Zod for non-boundary reasons go through `INDIRECT_ZOD_ROUTES` in `scripts/check-api-validation-contracts.ts`, not per-line annotations.

.cursor/rules/sim-queries.mdc

@@ -128,7 +128,7 @@ const handler = useCallback(() => {
 
 - Hooks must import named type aliases from `@/lib/api/contracts/**` (e.g., `import { listEntitiesContract, type EntityList } from '@/lib/api/contracts/entities'`). Never write `z.input<...>` or `z.output<...>` in hooks.
 - Hooks must not `import { z } from 'zod'`. Boundary types come from contract aliases; non-boundary helpers can stay in plain TypeScript.
-- For non-contract endpoints (multipart uploads, binary downloads, streaming responses, signed-URL flows, OAuth redirects, external origins), it is OK to keep raw `fetch`. Mark each raw `fetch` with a TSDoc comment explaining which exception applies.
+- For non-contract endpoints (multipart uploads, binary downloads, streaming responses, signed-URL flows, OAuth redirects, external origins), it is OK to keep raw `fetch`. Each legitimate raw `fetch(` call inside `apps/sim/hooks/queries/**` or `apps/sim/hooks/selectors/**` must be preceded by a `// boundary-raw-fetch: <reason>` annotation on the immediately preceding line (up to three non-empty preceding comment lines are tolerated). The reason must be non-empty — empty reasons fail strict mode. The audit script `scripts/check-api-validation-contracts.ts` (`bun run check:api-validation` / `bun run check:api-validation:strict`) enforces this.
 
 ## Naming
 

AGENTS.md

@@ -124,10 +124,33 @@ Boundary HTTP request and response shapes for all routes under `apps/sim/app/api
 - Contracts export named schemas (e.g., `createFolderBodySchema`) AND named TypeScript type aliases (e.g., `export type CreateFolderBody = z.input<typeof createFolderBodySchema>`)
 - Clients (hooks, utilities, components) import the named type aliases from the contract file. They must never write `z.input<...>` / `z.output<...>` themselves
 - Shared identifier schemas live in `apps/sim/lib/api/contracts/primitives.ts` (e.g., `workspaceIdSchema`, `workflowIdSchema`). Reuse these instead of redefining string-based ID schemas
-- Audit script: `bun run check:api-validation` enforces boundary policy and prints ratchet metrics for route Zod imports, route-local schema constructors, route `ZodError` references, client hook Zod imports, and related counters. It must pass on PRs
+- Audit script: `bun run check:api-validation` enforces boundary policy and prints ratchet metrics for route Zod imports, route-local schema constructors, route `ZodError` references, client hook Zod imports, and related counters. It must pass on PRs. `bun run check:api-validation:strict` is the strict CI gate and additionally fails on annotations with empty reasons
 
 Domain validators that are not HTTP boundaries — tools, blocks, triggers, connectors, realtime handlers, and internal helpers — may still use Zod directly. The contract rule is boundary-only.
 
+### Boundary annotations
+
+A small number of legitimate exceptions to the boundary rules are tolerated when annotated. The audit script recognizes two 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
+- `// double-cast-allowed: <reason>` — placed on the line directly above an `as unknown as X` cast outside test files
+
+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`).
+
+Whole-file allowlists for routes (legitimate non-boundary or auth-handled routes that legitimately import Zod for non-boundary reasons) go through `INDIRECT_ZOD_ROUTES` in `scripts/check-api-validation-contracts.ts`, not per-line annotations.
+
+Examples:
+
+```ts
+// boundary-raw-fetch: streaming SSE chunks must be processed as they arrive
+const response = await fetch(`/api/copilot/chat/stream?chatId=${chatId}`, { signal })
+```
+
+```ts
+// double-cast-allowed: legacy provider type lacks the discriminator field we need
+const provider = config as unknown as LegacyProvider
+```
+
 ## 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`:

CLAUDE.md

@@ -103,10 +103,33 @@ Boundary HTTP request and response shapes for all routes under `apps/sim/app/api
 - Contracts export named schemas (e.g., `createFolderBodySchema`) AND named TypeScript type aliases (e.g., `export type CreateFolderBody = z.input<typeof createFolderBodySchema>`)
 - Clients (hooks, utilities, components) import the named type aliases from the contract file. They must never write `z.input<...>` / `z.output<...>` themselves
 - Shared identifier schemas live in `apps/sim/lib/api/contracts/primitives.ts` (e.g., `workspaceIdSchema`, `workflowIdSchema`). Reuse these instead of redefining string-based ID schemas
-- Audit script: `bun run check:api-validation` enforces boundary policy and prints ratchet metrics for route Zod imports, route-local schema constructors, route `ZodError` references, client hook Zod imports, and related counters. It must pass on PRs
+- Audit script: `bun run check:api-validation` enforces boundary policy and prints ratchet metrics for route Zod imports, route-local schema constructors, route `ZodError` references, client hook Zod imports, and related counters. It must pass on PRs. `bun run check:api-validation:strict` is the strict CI gate and additionally fails on annotations with empty reasons
 
 Domain validators that are not HTTP boundaries — tools, blocks, triggers, connectors, realtime handlers, and internal helpers — may still use Zod directly. The contract rule is boundary-only.
 
+### Boundary annotations
+
+A small number of legitimate exceptions to the boundary rules are tolerated when annotated. The audit script recognizes two 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
+- `// double-cast-allowed: <reason>` — placed on the line directly above an `as unknown as X` cast outside test files
+
+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`).
+
+Whole-file allowlists for routes (legitimate non-boundary or auth-handled routes that legitimately import Zod for non-boundary reasons) go through `INDIRECT_ZOD_ROUTES` in `scripts/check-api-validation-contracts.ts`, not per-line annotations.
+
+Examples:
+
+```ts
+// boundary-raw-fetch: streaming SSE chunks must be processed as they arrive
+const response = await fetch(`/api/copilot/chat/stream?chatId=${chatId}`, { signal })
+```
+
+```ts
+// double-cast-allowed: legacy provider type lacks the discriminator field we need
+const provider = config as unknown as LegacyProvider
+```
+
 ## API Route Pattern
 
 Every API route handler must be wrapped with `withRouteHandler`. This sets up `AsyncLocalStorage`-based request context so all loggers in the request lifecycle automatically include the request ID.

README.md

@@ -141,7 +141,7 @@ See the [environment variables reference](https://docs.sim.ai/self-hosting/envir
 - **Runtime**: [Bun](https://bun.sh/)
 - **Database**: PostgreSQL with [Drizzle ORM](https://orm.drizzle.team)
 - **Authentication**: [Better Auth](https://better-auth.com)
-- **Schema Validation**: [Zod](https://zod.dev) (v4) — shared API contracts, request/response validation, and end-to-end client-server type safety
+- **Schema Validation**: [Zod](https://zod.dev)
 - **UI**: [Shadcn](https://ui.shadcn.com/), [Tailwind CSS](https://tailwindcss.com)
 - **Streaming Markdown**: [Streamdown](https://github.com/vercel/streamdown)
 - **State Management**: [Zustand](https://zustand-demo.pmnd.rs/), [TanStack Query](https://tanstack.com/query)

apps/sim/AGENTS.md

@@ -76,9 +76,32 @@ Boundary HTTP request and response shapes for all routes under `apps/sim/app/api
 - 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.
 - Shared identifier schemas live in `apps/sim/lib/api/contracts/primitives.ts` (e.g., `workspaceIdSchema`, `workflowIdSchema`).
-- Audit script: `bun run check:api-validation` enforces boundary policy and prints ratchet metrics for route Zod imports, route-local schema constructors, route `ZodError` references, client hook Zod imports, and related counters. It must pass on PRs.
+- Audit script: `bun run check:api-validation` enforces boundary policy and prints ratchet metrics for route Zod imports, route-local schema constructors, route `ZodError` references, client hook Zod imports, and related counters. It must pass on PRs. `bun run check:api-validation:strict` is the strict CI gate and additionally fails on annotations with empty reasons.
 - Domain validators that are not HTTP boundaries — tools, blocks, triggers, connectors, realtime handlers, and internal helpers — may still use Zod directly. The contract rule is boundary-only.
 
+### Boundary annotations
+
+A small number of legitimate exceptions to the boundary rules are tolerated when annotated. The audit script recognizes two 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.
+- `// double-cast-allowed: <reason>` — placed on the line directly above an `as unknown as X` cast outside test files.
+
+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`).
+
+Whole-file allowlists for routes (legitimate non-boundary or auth-handled routes that legitimately import Zod for non-boundary reasons) go through `INDIRECT_ZOD_ROUTES` in `scripts/check-api-validation-contracts.ts`, not per-line annotations.
+
+Examples:
+
+```ts
+// boundary-raw-fetch: streaming SSE chunks must be processed as they arrive
+const response = await fetch(`/api/copilot/chat/stream?chatId=${chatId}`, { signal })
+```
+
+```ts
+// double-cast-allowed: legacy provider type lacks the discriminator field we need
+const provider = config as unknown as LegacyProvider
+```
+
 ## 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`:

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

@@ -178,6 +178,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       name: data.name,
       profileImageUrl: data.profileImageUrl || null,
       details: Object.keys(details).length > 0 ? details : null,
+      verified: false,
       createdBy: session.user.id,
       createdAt: now,
       updatedAt: now,

apps/sim/app/api/knowledge/[id]/documents/[documentId]/tag-definitions/route.ts

@@ -117,9 +117,11 @@ export const POST = withRouteHandler(
       const validatedData = validation.data
 
       for (const def of validatedData.definitions) {
-        // Defense-in-depth runtime check: contract leaves `fieldType` as `z.string()`
-        // because tightening to the enum cascades into UI form state types. Cast here
-        // to allow `includes` to accept the wider input.
+        /**
+         * Defense-in-depth runtime check: the contract types `fieldType` as a plain
+         * string because tightening to the field-type enum cascades into UI form
+         * state types. Cast here to allow `includes` to accept the wider input.
+         */
         if (!(SUPPORTED_FIELD_TYPES as readonly string[]).includes(def.fieldType)) {
           return NextResponse.json(
             { error: 'Invalid request data', details: `Unsupported field type: ${def.fieldType}` },

apps/sim/app/api/mcp/copilot/.well-known/oauth-authorization-server/route.ts

@@ -1,11 +1,12 @@
 import type { NextRequest, NextResponse } from 'next/server'
-import { z } from 'zod'
+import { mcpOauthAuthorizationServerMetadataContract } from '@/lib/api/contracts/mcp-oauth'
+import { parseRequest } from '@/lib/api/server'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { createMcpAuthorizationServerMetadataResponse } from '@/lib/mcp/oauth-discovery'
 
-const metadataQuerySchema = z.record(z.string(), z.string())
-
-export async function GET(request: NextRequest): Promise<NextResponse> {
-  metadataQuerySchema.parse(Object.fromEntries(request.nextUrl.searchParams))
+export const GET = withRouteHandler(async (request: NextRequest): Promise<NextResponse> => {
+  const parsed = await parseRequest(mcpOauthAuthorizationServerMetadataContract, request, {})
+  if (!parsed.success) return parsed.response as NextResponse
 
   return createMcpAuthorizationServerMetadataResponse()
-}
+})