From d39c447c52da1dcbb6ea434d57b5474082163be7 Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Thu, 12 Feb 2026 12:55:32 -0800 Subject: [PATCH] docs: add .cursorrules and .github/copilot-instructions.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Completes the AI agent config set for the common platform repo: - .cursorrules — Cursor inline completions + chat rules - .github/copilot-instructions.md — GitHub Copilot code generation patterns Both reference AGENTS.md for full instructions and are tailored to the @bytelyst/* packages + @lysnrai/* services structure. --- .cursorrules | 71 +++++++++++++++++++++++++++++++++ .github/copilot-instructions.md | 45 +++++++++++++++++++++ 2 files changed, 116 insertions(+) create mode 100644 .cursorrules create mode 100644 .github/copilot-instructions.md diff --git a/.cursorrules b/.cursorrules new file mode 100644 index 00000000..f7120ecc --- /dev/null +++ b/.cursorrules @@ -0,0 +1,71 @@ +# 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 +- packages/auth/ → JWT, middleware, password hashing +- packages/api-client/ → Fetch wrapper with auth injection +- packages/react-auth/ → React auth context factory +- packages/design-tokens/ → Cross-platform tokens (JSON → CSS/TS/Kotlin/Swift) +- services/platform-service/ → Auth, audit, flags, blob (port 4003) +- services/billing-service/ → Subscriptions, Stripe, usage (port 4002) +- services/growth-service/ → Invitations, referrals, promos (port 4001) +- services/tracker-service/ → Items, comments, votes, public roadmap (port 4004) +- 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 (165+) +- 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 diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..a215a1a9 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,45 @@ +# GitHub Copilot Instructions — @bytelyst Common Platform + +> For full agent instructions, read [`AGENTS.md`](../../AGENTS.md) at the repo root. + +## Project Context + +Shared `@bytelyst/*` packages and `@lysnrai/*` microservices for the ByteLyst ecosystem. Product-agnostic — consumed by LysnrAI and MindLyst. + +## Code Generation Rules + +### Always +- Import `PRODUCT_ID` from `@bytelyst/config` (`loadProductIdentity()`) — never hardcode `"lysnrai"` +- Include `productId` field in every Cosmos DB document +- Validate inputs with Zod schemas +- Use `req.log` / `app.log` for Fastify logging +- Use ESM imports (`import ... from "./file.js"` with `.js` extension) +- Follow the module pattern: `types.ts` → `repository.ts` → `routes.ts` +- Propagate `x-request-id` headers in service-to-service calls +- Use `peerDependencies` for heavy deps in packages +- Use `workspace:*` for inter-package dependencies + +### Never +- `console.log` in production code +- `any` type in TypeScript +- `Math.random()` for IDs in loops without an index suffix +- Hardcoded secrets or API keys +- `npm` commands (use `pnpm`) +- Edit generated token files directly (edit `bytelyst.tokens.json` instead) + +### Suggestions Context + +When suggesting code in these directories, follow these patterns: + +| Directory | Framework | Key Pattern | +|-----------|-----------|-------------| +| `packages/*/src/` | TypeScript library | Export from `index.ts`, `peerDependencies` for heavy deps | +| `services/*/src/modules/` | Fastify 5 + Zod | `types.ts` → `repository.ts` → `routes.ts` | +| `services/*/src/lib/` | Re-exports | Re-export from `@bytelyst/*` packages | +| `packages/design-tokens/` | Token generator | Edit `bytelyst.tokens.json`, run `generate.ts` | + +### Commit Messages + +Format: `type(scope): description` + +Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`