From cb728d3dfede88817463f6f9227f7a6ff5ea4a49 Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Sun, 15 Feb 2026 01:09:29 -0800 Subject: [PATCH] =?UTF-8?q?docs:=20update=20agent=20docs=20=E2=80=94=20add?= =?UTF-8?q?=20missing=20packages,=20fix=20stale=20service=20refs,=20update?= =?UTF-8?q?=20test=20counts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .clinerules | 4 ++-- .cursorrules | 16 ++++++++++------ .windsurfrules | 4 ++-- AGENTS.md | 38 +++++++++++++++++++++----------------- 4 files changed, 35 insertions(+), 27 deletions(-) diff --git a/.clinerules b/.clinerules index b9d6083f..ef76fe16 100644 --- a/.clinerules +++ b/.clinerules @@ -17,7 +17,7 @@ Architecture: pnpm monorepo with @bytelyst/* packages + @lysnrai/* Fastify servi 10. After changes, verify: `pnpm build && pnpm test` ## Key File Locations -- Packages: `packages/` (@bytelyst/errors, cosmos, config, auth, api-client, react-auth, design-tokens) -- Services: `services/` (platform-service, billing-service, growth-service, tracker-service) +- Packages: `packages/` (@bytelyst/errors, cosmos, config, auth, api-client, fastify-core, react-auth, logger, testing, blob, extraction, monitoring, design-tokens) +- Services: `services/` (platform-service :4003, extraction-service :4005) - Base config: `tsconfig.base.json` - Full guide: `AGENTS.md` diff --git a/.cursorrules b/.cursorrules index f7120ecc..0cedaf1c 100644 --- a/.cursorrules +++ b/.cursorrules @@ -13,15 +13,19 @@ ## Monorepo Structure - packages/errors/ → Typed HTTP errors (400–429) - packages/cosmos/ → Azure Cosmos DB client singleton -- packages/config/ → Zod env loader + product identity +- 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/ → 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/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 @@ -58,7 +62,7 @@ ## Key Commands - pnpm build → build all packages + services -- pnpm test → run all tests (165+) +- 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 diff --git a/.windsurfrules b/.windsurfrules index 450c5120..75bc7d55 100644 --- a/.windsurfrules +++ b/.windsurfrules @@ -12,8 +12,8 @@ Stack: TypeScript, ESM, pnpm workspace, Fastify 5, Vitest, Azure Cosmos DB - Package manager: pnpm — NEVER use npm ## Key Paths -- Packages: packages/ (@bytelyst/errors, cosmos, config, auth, api-client, react-auth, design-tokens) -- Services: services/ (platform 4003, billing 4002, growth 4001, tracker 4004) +- Packages: packages/ (@bytelyst/errors, cosmos, config, auth, api-client, fastify-core, react-auth, logger, testing, blob, extraction, monitoring, design-tokens) +- Services: services/ (platform-service 4003, extraction-service 4005) - Base TS config: tsconfig.base.json (ES2022, NodeNext, strict) - Workspace: pnpm-workspace.yaml diff --git a/AGENTS.md b/AGENTS.md index 7814ce59..25e9b883 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,13 +26,16 @@ learning_ai_common_plat/ ├── packages/ # @bytelyst/* shared libraries │ ├── errors/ # Typed HTTP service errors (400–429) │ ├── cosmos/ # Azure Cosmos DB client singleton + container registry -│ ├── config/ # Zod-based env loader + product identity (loadProductIdentity) +│ ├── config/ # Zod-based env loader + product identity + AKV resolver │ ├── auth/ # JWT utilities, auth middleware, password hashing │ ├── api-client/ # Configurable fetch wrapper with auth token injection │ ├── fastify-core/ # createServiceApp() factory + startService() helper │ ├── react-auth/ # React auth context factory (typed provider + hook) -│ ├── logger/ # Structured logging wrapper +│ ├── logger/ # Structured logging wrapper (pino-based) │ ├── testing/ # Shared test mocks, fixtures, Fastify inject helpers +│ ├── blob/ # Azure Blob Storage client + SAS token helpers +│ ├── extraction/ # createExtractionClient(), shared types for extraction consumers +│ ├── monitoring/ # Health-check utilities, Loki/Grafana helpers │ └── design-tokens/ # Cross-platform tokens (JSON → CSS/TS/Kotlin/Swift) │ ├── tokens/bytelyst.tokens.json # ← CANONICAL SOURCE │ ├── scripts/generate.ts # Token generator @@ -159,7 +162,7 @@ pnpm install # ── Build all packages + services ────────────────── pnpm build -# ── Run all tests (277 tests across all workspaces) ─ +# ── Run all tests ──────────────────────────────── pnpm test # ── Type-check everything ────────────────────────── @@ -169,10 +172,8 @@ pnpm typecheck pnpm clean # ── Run a specific service in dev mode ───────────── -pnpm --filter @lysnrai/platform-service dev -pnpm --filter @lysnrai/billing-service dev -pnpm --filter @lysnrai/growth-service dev -pnpm --filter @lysnrai/tracker-service dev +pnpm --filter @lysnrai/platform-service dev # port 4003 +pnpm --filter @lysnrai/extraction-service dev # port 4005 # ── Run tests for one workspace ──────────────────── pnpm --filter @lysnrai/platform-service test @@ -265,16 +266,19 @@ DEFAULT_PRODUCT_ID=lysnrai ``` @bytelyst/errors ← no deps (foundation) @bytelyst/cosmos ← peers: @azure/cosmos -@bytelyst/config ← peers: zod +@bytelyst/config ← peers: zod; includes AKV resolver (resolveKeyVaultSecrets) @bytelyst/auth ← peers: jose, bcryptjs @bytelyst/api-client ← no deps @bytelyst/react-auth ← deps: @bytelyst/api-client; peers: react +@bytelyst/blob ← peers: @azure/storage-blob +@bytelyst/extraction ← no deps (types + client factory) +@bytelyst/monitoring ← no deps (health-check utilities) +@bytelyst/fastify-core ← deps: fastify; createServiceApp() + startService() +@bytelyst/logger ← deps: pino +@bytelyst/testing ← deps: vitest; shared mocks + Fastify inject helpers @bytelyst/design-tokens ← no deps (standalone generator) -@lysnrai/platform-service ← @bytelyst/{config, cosmos, errors} -@lysnrai/billing-service ← @bytelyst/{config, cosmos, errors} -@lysnrai/growth-service ← @bytelyst/{config, cosmos, errors} -@lysnrai/tracker-service ← @bytelyst/{config, cosmos, errors} +@lysnrai/platform-service ← @bytelyst/{fastify-core, config, cosmos, errors, auth, blob} @lysnrai/extraction-service ← @bytelyst/{fastify-core, config, cosmos, errors, auth} ``` @@ -295,12 +299,12 @@ Build order: packages first (they have no inter-deps), then services. `pnpm buil | Service / Package | Tests | Runner | | ------------------ | -------- | ------ | -| platform-service | 55 | vitest | -| tracker-service | 45 | vitest | +| platform-service | 158 | vitest | | extraction-service | 46 | vitest | -| growth-service | 33 | vitest | -| billing-service | 32 | vitest | -| **Total** | **211+** | | +| packages (various) | ~30 | vitest | +| **Total** | **234+** | | + +> Note: billing-service, growth-service, and tracker-service were consolidated into platform-service (Feb 2026). ## 12. Common Pitfalls