perf(tools): guard the tool-registry client boundary in CI

.agents/skills/tool-registry-boundary/SKILL.md

@@ -60,6 +60,13 @@ vi.mock('@/tools/metadata', () => toolsMetadataMock) // params / outputs / name
 ```
 
 Both are backed by the same `mockToolConfigs`, so mocking both gives one consistent tool universe. If you are unsure whether a mock is load-bearing, change a fixture value to a sentinel and confirm the test fails.
+## The guard
+
+`bun run check:tool-registry-boundary` (CI: "Tool registry client-boundary audit") walks the module graph from each workspace route and fails if `@/tools/registry` is reachable, printing the exact import chain that reintroduced it.
+
+If it fails, do not add the entry to an allowlist — there isn't one. Find the symbol the offending file actually needs and move it to a registry-free module, exactly as `mergeToolParameters` and `formatParameterLabel` were.
+
+Run it with `--verbose` to print per-route module counts, which is also the quickest way to see whether a change moved the graph.
 
 ## How to verify an edge actually got cut
 

.claude/commands/tool-registry-boundary.md

@@ -59,6 +59,13 @@ vi.mock('@/tools/metadata', () => toolsMetadataMock) // params / outputs / name
 ```
 
 Both are backed by the same `mockToolConfigs`, so mocking both gives one consistent tool universe. If you are unsure whether a mock is load-bearing, change a fixture value to a sentinel and confirm the test fails.
+## The guard
+
+`bun run check:tool-registry-boundary` (CI: "Tool registry client-boundary audit") walks the module graph from each workspace route and fails if `@/tools/registry` is reachable, printing the exact import chain that reintroduced it.
+
+If it fails, do not add the entry to an allowlist — there isn't one. Find the symbol the offending file actually needs and move it to a registry-free module, exactly as `mergeToolParameters` and `formatParameterLabel` were.
+
+Run it with `--verbose` to print per-route module counts, which is also the quickest way to see whether a change moved the graph.
 
 ## How to verify an edge actually got cut
 

.cursor/commands/tool-registry-boundary.md

@@ -55,6 +55,13 @@ vi.mock('@/tools/metadata', () => toolsMetadataMock) // params / outputs / name
 ```
 
 Both are backed by the same `mockToolConfigs`, so mocking both gives one consistent tool universe. If you are unsure whether a mock is load-bearing, change a fixture value to a sentinel and confirm the test fails.
+## The guard
+
+`bun run check:tool-registry-boundary` (CI: "Tool registry client-boundary audit") walks the module graph from each workspace route and fails if `@/tools/registry` is reachable, printing the exact import chain that reintroduced it.
+
+If it fails, do not add the entry to an allowlist — there isn't one. Find the symbol the offending file actually needs and move it to a registry-free module, exactly as `mergeToolParameters` and `formatParameterLabel` were.
+
+Run it with `--verbose` to print per-route module counts, which is also the quickest way to see whether a change moved the graph.
 
 ## How to verify an edge actually got cut
 

.github/workflows/test-build.yml

@@ -153,6 +153,9 @@ jobs:
  - name: Verify realtime prune graph
  run: bun run check:realtime-prune
 
+ - name: Tool registry client-boundary audit
+ run: bun run check:tool-registry-boundary
+
  - name: Verify generated tool metadata is in sync
  run: bun run tool-metadata:check
 

package.json

@@ -30,6 +30,7 @@
  "check:api-validation": "bun run scripts/check-api-validation-contracts.ts --check",
  "check:api-validation:strict": "bun run scripts/check-api-validation-contracts.ts --check --enforce-boundary-baseline",
  "check:realtime-prune": "bun run scripts/check-realtime-prune-graph.ts",
+ "check:tool-registry-boundary": "bun run scripts/check-tool-registry-boundary.ts",
  "check:zustand-v5": "bun run scripts/check-zustand-v5-selectors.ts",
  "check:react-query": "bun run scripts/check-react-query-patterns.ts --check",
  "check:client-boundary": "bun run scripts/check-client-boundary-imports.ts --check",

scripts/check-tool-registry-boundary.ts

@@ -0,0 +1,204 @@
+#!/usr/bin/env bun
+/**
+ * Fails if a workspace route can reach the executable tool registry.
+ *
+ * `@/tools/registry` is a barrel over 4,300+ tools whose `ToolConfig`s hold
+ * closures (`request.headers`, `transformResponse`, `directExecution`). Those
+ * closures reach every integration's SDK client and parser, so reaching the
+ * barrel costs ~4,700 modules — it was 71-82% of every workspace route's module
+ * graph until those edges were cut.
+ *
+ * Client-reachable code reads `@/tools/metadata`, `@/tools/metadata-outputs` or
+ * `@/tools/tool-ids` instead. See
+ * `.agents/skills/tool-registry-boundary/SKILL.md`.
+ *
+ * This regresses silently and cheaply: any file under a route can import one
+ * helper from a module that happens to import `getTool`, and the whole registry
+ * comes back. That is exactly how it got there — `providers/utils.ts` pulled it
+ * in through `mergeToolParameters`, and `mcp-dynamic-args.tsx` through
+ * `formatParameterLabel`. Neither import looks remotely suspicious at the call
+ * site, which is why this is a lint and not a convention.
+ *
+ * Usage:
+ * bun run scripts/check-tool-registry-boundary.ts
+ * bun run scripts/check-tool-registry-boundary.ts --verbose # print counts
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url))
+const ROOT = resolve(SCRIPT_DIR, '..')
+const APP = join(ROOT, 'apps/sim')
+
+/** Module no client-reachable entry may reach. */
+const FORBIDDEN = join(APP, 'tools/registry.ts')
+
+/**
+ * Root the guard walks: every `page.tsx` and `layout.tsx` under the workspace app.
+ *
+ * Discovered rather than listed. A hardcoded list goes stale silently — the
+ * first version of this guard named `app/workspace/layout.tsx` as "the shared
+ * shell", but that file only wraps `SocketProvider`; the real shell is
+ * `app/workspace/[workspaceId]/layout.tsx`, which was never checked.
+ *
+ * Layouts must be enumerated separately because Next.js composes them by
+ * convention — a page does not `import` its layout, so walking pages alone never
+ * reaches layout modules even though every route pays for them.
+ */
+const ENTRY_ROOT = 'app/workspace'
+const ENTRY_FILENAMES = new Set(['page.tsx', 'layout.tsx'])
+
+function collectEntries(dir: string, found: string[] = []): string[] {
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ const full = join(dir, entry.name)
+ if (entry.isDirectory()) collectEntries(full, found)
+ else if (ENTRY_FILENAMES.has(entry.name)) found.push(relative(APP, full))
+ }
+ return found
+}
+
+const EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs']
+
+/**
+ * Matches value imports and re-exports, skipping `import type` and
+ * `export type` — a type-only edge is erased at compile time and costs nothing.
+ *
+ * `REEXPORT_RE` allows an alias after the star so `export * as ns from` is not
+ * missed, and `DYNAMIC_IMPORT_RE` covers `import('…')`. A dynamic import splits
+ * the registry into its own chunk rather than the route's initial one, but it
+ * still puts 4,300 tools' worth of executable config on a client path, so it
+ * counts as reaching it — and the settings route's registry edge hid behind
+ * exactly such an import.
+ *
+ * `REQUIRE_RE` matters for the same reason: this codebase uses lazy
+ * `require('@/…')` to break import cycles (`tools/params.ts` reaches `@/blocks`
+ * that way), and those edges are as real as static ones.
+ */
+const IMPORT_RE = /(?:^|\n)\s*import\s+(?!type\b)(?:[\s\S]*?from\s*)?['"]([^'"]+)['"]/g
+const REEXPORT_RE =
+ /(?:^|\n)\s*export\s+(?!type\b)(?:\*(?:\s+as\s+[\w$]+)?|\{[\s\S]*?\})\s*from\s*['"]([^'"]+)['"]/g
+const DYNAMIC_IMPORT_RE = /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g
+const REQUIRE_RE = /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g
+
+/** Resolves `@/` and relative specifiers. Bare package specifiers are ignored. */
+function resolveSpecifier(specifier: string, importer: string): string | null {
+ let base: string
+ if (specifier.startsWith('@/')) base = join(APP, specifier.slice(2))
+ else if (specifier.startsWith('.')) base = resolve(dirname(importer), specifier)
+ else return null
+
+ // An already-extensioned specifier (`@/tools/registry.ts`) resolves as-is.
+ // Probing only `base + ext` would miss it and silently drop the edge — and
+ // extensionful `@/` imports do exist in this repo.
+ if (existsSync(base) && statSync(base).isFile()) return base
+
+ for (const ext of EXTENSIONS) {
+ if (existsSync(base + ext)) return base + ext
+ }
+ if (existsSync(base) && statSync(base).isDirectory()) {
+ for (const ext of EXTENSIONS) {
+ const indexPath = join(base, `index${ext}`)
+ if (existsSync(indexPath)) return indexPath
+ }
+ }
+ return null
+}
+
+interface Walk {
+ reachable: Set<string>
+ importedBy: Map<string, string>
+}
+
+function walk(entry: string): Walk {
+ const reachable = new Set<string>()
+ const importedBy = new Map<string, string>()
+ const queue = [entry]
+ reachable.add(entry)
+
+ while (queue.length > 0) {
+ const file = queue.pop() as string
+ let source: string
+ try {
+ source = readFileSync(file, 'utf8')
+ } catch {
+ continue
+ }
+ for (const pattern of [IMPORT_RE, REEXPORT_RE, DYNAMIC_IMPORT_RE, REQUIRE_RE]) {
+ pattern.lastIndex = 0
+ let match = pattern.exec(source)
+ while (match !== null) {
+ const resolved = resolveSpecifier(match[1], file)
+ if (resolved && !reachable.has(resolved)) {
+ reachable.add(resolved)
+ importedBy.set(resolved, file)
+ queue.push(resolved)
+ }
+ match = pattern.exec(source)
+ }
+ }
+ }
+
+ return { reachable, importedBy }
+}
+
+/** Walks parent links back to the entry so the offending edge is obvious. */
+function explainChain({ importedBy }: Walk, target: string): string[] {
+ const chain: string[] = []
+ let current: string | undefined = target
+ while (current) {
+ chain.push(relative(ROOT, current))
+ current = importedBy.get(current)
+ }
+ return chain.reverse()
+}
+
+function main() {
+ const verbose = process.argv.includes('--verbose')
+ const failures: string[] = []
+
+ const entryRoot = join(APP, ENTRY_ROOT)
+ if (!existsSync(entryRoot)) {
+ console.error(`❌ ${ENTRY_ROOT} no longer exists — update ENTRY_ROOT in this script.`)
+ process.exit(1)
+ }
+ const entries = collectEntries(entryRoot).sort()
+ if (entries.length === 0) {
+ console.error(
+ `❌ No page/layout entries found under ${ENTRY_ROOT}. Refusing to pass vacuously.`
+ )
+ process.exit(1)
+ }
+
+ for (const entry of entries) {
+ const entryPath = join(APP, entry)
+ const result = walk(entryPath)
+ if (result.reachable.has(FORBIDDEN)) {
+ failures.push(entry)
+ console.error(`\n❌ ${entry} can reach @/tools/registry via:`)
+ for (const step of explainChain(result, FORBIDDEN)) {
+ console.error(` ${step}`)
+ }
+ } else if (verbose) {
+ console.log(`✓ ${entry} — ${result.reachable.size} modules, registry unreachable`)
+ }
+ }
+
+ if (failures.length > 0) {
+ console.error(
+ `\n${failures.length} route(s) reach the executable tool registry, which adds ~4,700 modules to each.`
+ )
+ console.error(
+ 'Read the metadata instead: `@/tools/metadata` (params), `@/tools/metadata-outputs`'
+ )
+ console.error(
+ '(outputs), or `@/tools/tool-ids` (existence/resolution). Only code that executes a tool'
+ )
+ console.error('may import `getTool`. See .agents/skills/tool-registry-boundary/SKILL.md.')
+ process.exit(1)
+ }
+
+ console.log(`✓ tool registry stays out of ${entries.length} workspace page/layout graphs`)
+}
+
+main()