refactor(web): import dialect code through @foxschema/ui-shared

[huyplb]

Why

The web frontend imported @foxschema/sql directly from 65 files. That package is the dialect engine the server, the CLI and the driver layer share, so what the browser depended on was spread across features and grew with every new import.

What

• New package packages/ui-shared (@foxschema/ui-shared). One index.ts that names each @foxschema/sql export the frontend uses (183 values, 127 types, grouped by area) and re-exports it by reference. No code moves and nothing is wrapped.
• apps/web depends on @foxschema/ui-shared instead of @foxschema/sql. All 78 frontend import lines were re-pointed one for one. Aliases were added to apps/web/vite.config.ts, apps/web/tsconfig.json and the root vitest.config.ts. The lockfile change only adds the workspace link; no third-party versions change.
• Guards
  • apps/web/src/frontend/architecture.test.ts fails on any frontend import of @foxschema/sql.
  • packages/ui-shared/src/ui-shared.test.ts checks three things:
    • every export is the @foxschema/sql object itself, so the browser and the server cannot drift apart;
    • the package imports nothing but @foxschema/sql;
    • it never uses export *, so the browser taking on more of the engine shows up in review.
  • packages/shared/src/naming.test.ts now recognises a kebab-case frontend facade by its @foxschema/ui-shared import, and includes the new package in its kebab-case check.
• Docs. ARCHITECTURE.md, CODE_MAP.md (import rules, plus a "Where does my change go?" row), CONVENTIONS.md and CONTRIBUTING.md are updated.

To use something new from the engine in the browser, add it to packages/ui-shared/src/index.ts.

Verification

• cd apps/web && npx tsc --noEmit: clean.
• npx vitest run (Node 24): 479 files passed, 8 skipped; 5858 tests passed.
• npx eslint on the changed files: clean.
• I broke each guard rule on purpose to confirm the tests catch it:
  • a direct @foxschema/sql import;
  • a copied function in place of a re-export;
  • an export *;
  • a node:fs import.
• The bundle is unchanged. npm run build -w @foxschema/web produces the same 102 JS chunks, with the same hashes and total size, as main. npm run bundle:first-load reports 140.3 KB gzip, within the 170 KB budget.

🤖 Generated with Claude Code

https://claude.ai/code/session_016PyNv48vpYUw2HhpjYFNUi

---

Generated by Claude Code

---

Note

Low Risk
Import-path and package-boundary refactor with tests and docs; runtime behavior and bundle are unchanged per verification.

Overview
Introduces @foxschema/ui-shared as the web app’s single entry for dialect engine APIs: a named, by-reference re-export of @foxschema/sql (no wrappers or moved code). apps/web drops a direct @foxschema/sql dependency and re-points frontend imports and shared facades to @foxschema/ui-shared, with matching Vite/tsconfig/Vitest aliases.

Enforcement and docs: architecture.test.ts fails on any frontend @foxschema/sql import; ui-shared.test.ts checks same-object re-exports, no extra deps, and no export *. CONTRIBUTING, ARCHITECTURE, CODE_MAP, and CONVENTIONS describe the new boundary; naming.test.ts treats @foxschema/ui-shared facades correctly.

Workflow for browser use: add exports to packages/ui-shared/src/index.ts instead of importing the engine package from features.

^{Reviewed by Cursor Bugbot for commit fd6ef58. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: 73afb744-23d7-4fdd-a2f1-1ee411fbfd3b)