Skip to content

refactor(runs): runs' client.ts, and routes enter a module through four doors - #928

Open
ddteeter wants to merge 7 commits into
mainfrom
refactor/w16-client-door
Open

ddteeter wants to merge 7 commits into
mainfrom
refactor/w16-client-door

Conversation

@ddteeter

Copy link
Copy Markdown
Owner

Summary

Design 255 (docs/designs/255-client-door.md, ruled on by the owner 2026-11-20). Each module whose helpers routes import gets a second, client-safe door, client.ts, and two dependency-cruiser rules hold the line at commit instead of after a build.

  • Nine client.ts doors (account, auth, closet, feed, notifications, onboarding, ops, runs, safety). Each re-exports what a route uses at module scope: search schemas, gates, redirects and hooks. The helpers stay where they live.
  • client-side-reaches-no-server: from every client.ts and every components/ folder, nothing reachable in src/env/, src/lib/sql/, src/db/, drizzle-orm or cloudflare:.
  • routes-enter-through-doors: a route reaches a module only through functions.ts, a components/ file, client.ts or a door (index.ts, the module's or a sub-module's).
  • Server-route code goes through a door. It is used only inside server.handlers, which Start strips. That covers the photo, export, unsubscribe and public-kit responses, runs/strava's webhook and connect redirect, and ops' default OG card. Doors gain those names.
  • The module ratchet counts routes: a route import past those four entries is past the door (budget 0), and each client.ts counts toward door width.
  • Renames and moves:
    • auth/client.ts (Better Auth's browser client) is now auth/auth-client.ts, so the door can take the name.
    • auth/auth-page.tsx and auth/google-button.tsx move into auth/components/.
  • Docs: .claude/rules/routes.md gains "How a route reaches a module", and design 255 gains "What the build found".

About 50 route import paths change; no behaviour changes.

Grants (owner, 2026-11-20, #888)

  • .dependency-cruiser.cjs: the two rules above.
  • eslint.config.js: the primitiveExemptions key for the Google button is re-keyed to its new path under auth/components/, with the same exemption (pills).

What the build found

  • runs/strava/webhook.ts imports node:crypto, so it is server-route code and goes through runs/strava's door.
  • ops' defaultCardResponse reaches no env, so the reachability rule let it into ops/client.ts. But it imports the card fonts as .woff.bin, and npm run build failed on that. It goes through ops/public-web's door instead. check:bundle and the build stay the check for anything the client build cannot load.

Testing

  • Both rules were tested with planted imports against the real config, then removed:
    • a route importing runs/not-found.ts directly fails routes-enter-through-doors;
    • runs/client.ts re-exporting from env fails client-side-reaches-no-server, naming the lib/sql and env files it reaches;
    • imports through client.ts, a door, a component or functions.ts pass (the whole tree, 0 violations).
  • test/scripts/module-shape.test.ts: new tests: a route's import of a file that is no door counts; a module's client.ts counts as a door of its own; a client.ts deeper than a module's folder is a plain file; neither client.ts nor a components/ helper counts as past the door.
  • test/architecture/mutation-config.test.ts: the new client.ts files join their stryker.conf.json scopes.
  • npm run lint, npm run typecheck, npm test and npm run diagrams:check pass.
  • npm run build passes: check:bundle is clean, with the entry chunk at 275,668 of 280,000 bytes.
  • npm run e2e:ci and sanctions-check pass locally.

No demo: nothing a user sees changes. No diagram changes (diagrams:generate redrew nothing, and diagrams:stale lists no story).

The mutation shards may run cold: stryker.conf.json changes, and the moves touch files across most modules.

Closes #888

🤖 Generated with Claude Code

https://claude.ai/code/session_01GFN3djXF7GKhGZYopfh9ML

ddteeter and others added 7 commits November 20, 2026 21:14
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GFN3djXF7GKhGZYopfh9ML
…onents

Design 255 (#888): a route reaches a module's components through
components/ only, and these two were the components outside it. Granted
by the owner on 2026-11-20: eslint.config.js' primitiveExemptions entry
for google-button.tsx follows it, path prefix only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GFN3djXF7GKhGZYopfh9ML
…scope

Design 255 (#888). Eight modules get a client.ts beside index.ts that
re-exports the client-side helpers their routes import (search schemas,
gates, redirects, hooks), and the routes import it instead of the files.
The server code routes call only inside server.handlers goes through a
door: account/data, closet, email, feed/entries and feed/public-web each
export one or two more names. runs follows once its move (#887) lands.

auth's Better Auth browser client moves from auth/client.ts to
auth/auth-client.ts, so the door can take the name.

New rule, granted by the owner on 2026-11-20:
client-side-reaches-no-server. From every client.ts and every
components/ folder, nothing reachable may be in env, lib/sql, db,
drizzle-orm or cloudflare:. 0 violations; planted ones in a client.ts
and a component are refused.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GFN3djXF7GKhGZYopfh9ML
Design 255 (#888): now that routes have client.ts, a route's import past
a module's doors counts toward past the door (budget 0), as anyone
else's does. A module's client.ts is a door, and its width is counted
under feed/client.ts. A file in a components/ folder is not past the
door, whatever its extension, matching routes-enter-through-doors.

Until runs' routes go through its doors (after #887), runs reads 10
here; this branch lands only with that rewrite.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GFN3djXF7GKhGZYopfh9ML
…ur doors

runs gets its client.ts (inputs.ts' search schemas, not-found.ts' gates).
The Strava webhook and connect routes reach webhook.ts and oauth.ts
through runs/strava's door, since webhook.ts imports node:crypto.
routes-enter-through-doors refuses any other route import into a
module: functions.ts, components/, client.ts or an index.ts only.

ops' defaultCardResponse leaves ops/client.ts for ops/public-web's door:
its .woff.bin font imports fail the client build. The new client.ts
files join their mutation scopes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GFN3djXF7GKhGZYopfh9ML

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

A client-safe door for the helpers routes import past a barrel

1 participant