Repository Guidelines

Project Structure & Module Organization

This is a pnpm workspace. The React Router web runtime lives in apps/web, with source in apps/web/app and static assets in apps/web/public. API and worker runtimes live in apps/api and apps/worker. Shared packages live under packages/*, including @toolctrl/db, @toolctrl/config, @toolctrl/url, @toolctrl/foundation, and UI/view-model packages. Prisma schema and migrations are in prisma/. Repository scripts and verification gates are in scripts/.

Before substantial feature work, read docs/agent-entrypoints.md. If a change adds or imports a feature, changes admin-managed behavior, provider credentials, workers, or proprietary logic, update the relevant docs/feature-manifests/*.json first.

Build, Test, and Development Commands

pnpm install: install workspace dependencies.
pnpm run dev: start the web runtime through @toolctrl/web.
pnpm run typecheck: generate Prisma/types and run TypeScript project checks.
pnpm run lint: run ESLint across TypeScript and TSX files.
pnpm run test: run the root Vitest/script test suite in non-watch mode.
pnpm run build: generate Prisma and build the web client/server.
API/worker changes also need pnpm --filter @toolctrl/api build or pnpm --filter @toolctrl/worker build.
pnpm run verify:i18n, pnpm run verify:phase-c-boundaries, pnpm run test:hot-swap: run focused Phase C gates.
pnpm run verify:api-inventory, pnpm run verify:openapi-security: check API route and OpenAPI drift.
pnpm run verify:deploy-workflow, pnpm run verify:docker-baseline, pnpm run verify:production-seed-artifact: verify deploy workflow, Docker baseline, and seed artifact contracts before deploy changes are pushed.
pnpm exec vitest run apps/api/src/route-access-inventory.test.ts apps/api/src/route-access-inventory-doc.test.ts: verify API access docs after route changes.
pnpm exec vitest run apps/web/app/utils/session.server.test.ts apps/web/app/utils/session-csrf-sweep.test.ts apps/api/src/csrf-inventory.test.ts: verify CSRF inventory after mutating route changes.
pnpm run verify:permission-matrix: verify role and permission documentation after permission catalog changes.

Coding Style & Naming Conventions

Use TypeScript and React Router conventions already present in apps/web/app. Prefer workspace package boundaries over direct cross-runtime imports. Use @toolctrl/* package names for shared modules. Route and UI links must use canonical host-aware helpers from @toolctrl/url or local wrappers such as appPath, adminPath, apiPath, and cross-host helpers. Use UrlUtils.getModulePath(...) for internal tenant module navigation only.

Boundary defaults: server DB access goes through @toolctrl/db/client.server; environment reads go through @toolctrl/config; queue names and payloads come from @toolctrl/queue; API app composition stays in apps/api/src/app.ts; worker processors stay in apps/worker.

Testing Guidelines

Tests use Vitest and Testing Library. Keep tests next to the code they cover with names like *.test.ts or *.test.tsx. Add focused tests for routing, permissions, boundaries, idempotency, and tenant-scope behavior when changing those areas.

For new or changed POST, PATCH, or DELETE web/API routes, update docs/security/csrf-inventory.md when the protection surface changes. Role or permission changes should update docs/roles-matrix.md and the relevant seed/package tests.

Commit & Pull Request Guidelines

Use concise imperative commit messages such as fix: canonicalize tenant routes or feat: add foundation audit boundary. Keep commits logically scoped. PRs should describe behavior changes, list verification commands run, mention migrations or config changes, and include screenshots for visible UI changes.

Security & Configuration Tips

Do not read secrets directly in UI code. Use @toolctrl/config loaders and server-only boundaries. Tenant-scoped data access must flow through explicit DB/package helpers and preserve tenant filters.

4.0 KiB Raw Blame History