76 lines
3.4 KiB
Plaintext
76 lines
3.4 KiB
Plaintext
# Cursor Rules — @bytelyst Common Platform
|
||
|
||
# For full agent instructions, read AGENTS.md at the repo root.
|
||
|
||
## Project
|
||
- Repo: learning_ai_common_plat — shared packages + microservices
|
||
- Library scope: @bytelyst/* (packages/)
|
||
- Service scope: @lysnrai/* (services/)
|
||
- Consumers: LysnrAI (voice dictation), MindLyst (multimodal memory)
|
||
- Product-agnostic: every Cosmos document MUST include a productId field
|
||
- Package manager: pnpm — NEVER use npm
|
||
|
||
## Monorepo Structure
|
||
- packages/errors/ → Typed HTTP errors (400–429)
|
||
- packages/cosmos/ → Azure Cosmos DB client singleton
|
||
- packages/config/ → Zod env loader + product identity + AKV resolver
|
||
- packages/auth/ → JWT, middleware, password hashing
|
||
- packages/api-client/ → Fetch wrapper with auth injection
|
||
- packages/fastify-core/ → createServiceApp() + startService()
|
||
- packages/react-auth/ → React auth context factory
|
||
- packages/logger/ → Structured logging (pino)
|
||
- packages/testing/ → Test mocks, Fastify inject helpers
|
||
- packages/blob/ → Azure Blob Storage client + SAS
|
||
- packages/extraction/ → createExtractionClient(), shared types
|
||
- packages/monitoring/ → Health-check utilities
|
||
- packages/design-tokens/ → Cross-platform tokens (JSON → CSS/TS/Kotlin/Swift)
|
||
- services/platform-service/ → Consolidated: auth, audit, flags, blob, subscriptions, stripe, usage, plans, licenses, invitations, referrals, promos, items, comments, votes, public (port 4003)
|
||
- services/extraction-service/ → Text extraction + Python sidecar (port 4005)
|
||
- services/monitoring/ → Loki + Grafana, health-check
|
||
|
||
## TypeScript Rules
|
||
- ESM everywhere ("type": "module")
|
||
- Target: ES2022, moduleResolution: NodeNext
|
||
- All packages/services extend ../../tsconfig.base.json
|
||
- Fastify 5 with Zod validation for all inputs
|
||
- Module pattern: types.ts → repository.ts → routes.ts
|
||
- Auth: JWT via jose — platform-service issues, all others validate
|
||
- Database: Azure Cosmos DB via @azure/cosmos
|
||
- Tests: Vitest (passWithNoTests at root)
|
||
- NEVER use console.log — use req.log or app.log in Fastify
|
||
- NEVER use any type — use Zod inference or explicit types
|
||
|
||
## Package Rules
|
||
- Export from src/index.ts → dist/index.js
|
||
- Use exports field in package.json (not just main)
|
||
- Heavy deps in peerDependencies, not dependencies
|
||
- Workspace deps: "@bytelyst/errors": "workspace:*"
|
||
|
||
## Service Rules
|
||
- Services re-export @bytelyst/* in src/lib/ for clean internal imports
|
||
- Services use self-contained Zod config schemas in src/lib/config.ts
|
||
- Health: GET /health → { status: "ok", service, requestId }
|
||
- Propagate x-request-id headers across all services
|
||
|
||
## Conventions
|
||
- Commit messages: type(scope): description (feat, fix, docs, refactor, test, chore)
|
||
- Fix source code, not tests (unless the test itself is wrong)
|
||
- Never delete existing comments/documentation unless asked
|
||
- Never add emojis unless asked
|
||
- Never hardcode secrets or API keys
|
||
- Never modify generated token files directly — edit bytelyst.tokens.json
|
||
|
||
## Key Commands
|
||
- pnpm build → build all packages + services
|
||
- pnpm test → run all tests (234+)
|
||
- pnpm typecheck → type-check everything
|
||
- pnpm --filter @lysnrai/platform-service dev → run one service
|
||
- pnpm --filter @bytelyst/design-tokens generate → regen tokens
|
||
|
||
## Key Documents
|
||
- AGENTS.md — Full AI agent instructions
|
||
- README.md — Quick start + consuming packages
|
||
- docs/ECOSYSTEM_ARCHITECTURE.md — Full architecture
|
||
- docs/ROADMAP.md — Phased extraction plan
|
||
- .env.example — Required environment variables
|