ai-ops-cli 0.1.24 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-ops-cli",
-  "version": "0.1.24",
+  "version": "0.2.0",
   "description": "CLI for ai-ops scaffolding — manage AI tool rules and presets",
   "license": "MIT",
   "repository": {

package/data/rules/ai-llm-python.yaml

@@ -1,35 +0,0 @@
-id: ai-llm-python
-category: domain
-tags:
-  - python
-  - llm
-  - ai
-priority: 28
-content:
-  constraints:
-    - 'DO NOT parse model outputs with regex/split when schema output is required. Use structured output (Pydantic + response_format/function calling/instructor).'
-    - 'DO NOT hardcode prompts inline. Keep prompts versioned in files or managed storage.'
-    - 'DO NOT call sync SDK methods from async app paths.'
-    - 'DO NOT ignore token limits. Estimate and chunk/truncate input before requests.'
-    - 'DO NOT log raw responses containing PII.'
-  guidelines:
-    - 'Use Pydantic models with instructor or native response_format JSON schema mode.'
-    - 'Apply retry with exponential backoff for 429/5xx transient errors.'
-    - 'Centralize provider routing via LiteLLM (or equivalent abstraction).'
-    - 'Track model, input/output tokens, and latency per call for cost/perf monitoring.'
-    - 'Version prompts and include prompt version in request logs.'
-    - 'Stream user-facing responses when possible; keep non-streaming for strict structured extraction flows.'
-    - 'Define fallback model chains for rate limits or provider outages.'
-  decision_table:
-    - when: 'Output must match a strict schema'
-      then: 'Use structured output with Pydantic schema validation'
-      avoid: 'Regex parsing on free-text responses'
-    - when: 'Selecting a model'
-      then: 'Use the smallest model that meets quality requirements'
-      avoid: 'Defaulting to the largest model for all tasks'
-    - when: 'Input exceeds context window'
-      then: 'Chunk with overlap and aggregate results'
-      avoid: 'Silent SDK truncation'
-    - when: 'Multiple providers are required'
-      then: 'Use a unified provider abstraction (e.g., LiteLLM)'
-      avoid: 'Scattered provider-specific call sites'

package/data/rules/data-pipeline-python.yaml

@@ -1,34 +0,0 @@
-id: data-pipeline-python
-category: domain
-tags:
-  - python
-  - data-engineering
-  - polars
-  - duckdb
-priority: 33
-content:
-  constraints:
-    - 'DO NOT iterate DataFrame rows in Python loops for transformations.'
-    - 'DO NOT use Pandas .apply(axis=1). It runs at Python speed; use vectorized expressions or Polars.'
-    - 'DO NOT load datasets larger than memory in one shot.'
-    - 'DO NOT rely on implicit dtype inference for production pipelines.'
-    - 'DO NOT mutate DataFrames in-place.'
-  guidelines:
-    - 'Prefer Polars for new pipelines, especially lazy mode for query pushdown and parallel execution.'
-    - 'Use DuckDB for local SQL analytics on Parquet/CSV and out-of-core workloads.'
-    - 'Use streaming/chunked reads for large sources (scan_*, batched readers, out-of-core SQL).'
-    - 'Write partitioned Parquet outputs for downstream pruning and faster reads.'
-    - 'Enforce explicit schemas at I/O boundaries.'
-  decision_table:
-    - when: 'Transforming tables up to medium-large scale'
-      then: 'Use Polars lazy pipelines'
-      avoid: 'Row-wise pandas patterns'
-    - when: 'Ad-hoc SQL analysis on local files is needed'
-      then: 'Use DuckDB directly on source files'
-      avoid: 'Load-all-then-filter in pandas'
-    - when: 'Data exceeds available memory'
-      then: 'Use Polars scan_* or DuckDB out-of-core execution'
-      avoid: 'Full-memory pandas reads'
-    - when: 'Custom per-row Python logic is unavoidable'
-      then: 'Use vectorized expressions or controlled map APIs'
-      avoid: 'General-purpose iter_rows for core pipelines'

package/data/rules/engineering-standards.yaml

@@ -1,39 +0,0 @@
-id: engineering-standards
-category: standard
-tags:
-  - general
-  - api
-  - data-format
-  - cross-cutting
-priority: 70
-content:
-  constraints:
-    - 'DO NOT use floating-point for money. Use minor-unit integers with ISO 4217 currency (e.g., { amount: 1099, currency: "USD" }).'
-    - 'DO NOT expose sequential IDs in external APIs. Use UUIDs (prefer UUID v7).'
-    - 'DO NOT store or transmit timezone-naive timestamps. Use ISO 8601 UTC (e.g., "2024-01-15T09:30:00Z").'
-    - 'DO NOT use magic numbers or strings inline. Extract constants or config.'
-    - 'DO NOT return inconsistent error shapes. Use { code: string, message: string, details?: unknown[] }.'
-    - 'DO NOT accept unbounded input. Enforce body, array, and string size limits at the API boundary.'
-  guidelines:
-    - 'Use UTC end-to-end: TIMESTAMPTZ in DB, ISO 8601 UTC in API/logs, local conversion only in the presentation layer.'
-    - 'Wrap API responses in a consistent envelope: { data: T | null, error: ErrorEnvelope | null, meta: { requestId: string, timestamp: string } }.'
-    - 'Propagate X-Request-Id across gateway, service, logs, DB comments, and outbound calls.'
-    - 'Validate environment variables at startup (e.g., Zod parse) and fail fast with all missing/invalid keys.'
-    - 'Use domain error codes in DOMAIN_ACTION_REASON format (e.g., PAYMENT_CHARGE_INSUFFICIENT_FUNDS).'
-    - 'Support Idempotency-Key for POST/PATCH and replay the cached response for duplicate keys within TTL.'
-    - 'Expose GET /health (liveness) and GET /ready (readiness) separately.'
-    - 'Return empty collections ([] or {}) instead of null.'
-    - 'Handle SIGTERM gracefully: stop intake, drain in-flight requests, close resources, then exit.'
-  decision_table:
-    - when: 'A new entity needs a primary key'
-      then: 'Use UUID v7'
-      avoid: 'Auto-increment IDs or UUID v4 by default'
-    - when: 'An endpoint returns an error'
-      then: 'Return the standard error envelope'
-      avoid: 'Ad-hoc error fields (e.g., { success: false, msg })'
-    - when: 'Systems exchange timestamps'
-      then: 'Use ISO 8601 UTC in API/logs and TIMESTAMPTZ in DB; Unix epoch is acceptable in compact token formats (e.g., JWT exp/iat)'
-      avoid: 'Timezone-naive strings or mixed local-time storage'
-    - when: 'An API needs versioning'
-      then: 'Use URL versioning (/v1, /v2)'
-      avoid: 'Header-only versioning by default'

package/data/rules/fastapi.yaml

@@ -1,34 +0,0 @@
-id: fastapi
-category: framework
-tags:
-  - python
-  - fastapi
-  - backend
-priority: 42
-content:
-  constraints:
-    - 'DO NOT use plain dict/TypedDict as request or response models. Use Pydantic BaseModel with Field constraints.'
-    - 'DO NOT run blocking I/O in async handlers. Use async clients or offload to executors.'
-    - 'DO NOT return ad-hoc error dicts from handlers. Raise HTTPException/custom exceptions and centralize handlers.'
-    - 'DO NOT place business logic in routers. Keep routers thin and inject services via Depends().'
-    - 'DO NOT hardcode CORS origins. Load from validated settings.'
-  guidelines:
-    - 'Use reusable Depends() providers for DB session, auth context, and services.'
-    - 'Use APIRouter per domain with clear prefixes/tags and mount in the main app.'
-    - 'Set response_model on endpoints for output filtering and OpenAPI correctness.'
-    - 'Use Annotated[T, Depends(...)] for typed dependency injection.'
-    - 'Use Pydantic Settings for startup-time environment validation.'
-    - 'Use lifespan context manager for startup/shutdown lifecycle management.'
-  decision_table:
-    - when: 'Endpoint is CPU-bound'
-      then: 'Use sync def and let FastAPI run it in the threadpool'
-      avoid: 'async def with blocking code'
-    - when: 'Endpoint is I/O-bound'
-      then: 'Use async def with async drivers (asyncpg, httpx, aiofiles)'
-      avoid: 'Sync driver calls on hot paths'
-    - when: 'Shared resources need setup/teardown'
-      then: 'Use lifespan async context manager'
-      avoid: '@app.on_event startup/shutdown hooks'
-    - when: 'Post-response background work is required'
-      then: 'Use BackgroundTasks for light jobs, Celery/TaskIQ for heavy/retriable jobs'
-      avoid: 'Awaiting long tasks inside the request handler'

package/data/rules/flutter.yaml

@@ -1,40 +0,0 @@
-id: flutter
-category: framework
-tags:
-  - dart
-  - flutter
-  - riverpod
-  - mobile
-priority: 30
-content:
-  constraints:
-    - 'DO NOT use dynamic as a default type. Prefer concrete types, Object, or sealed unions.'
-    - 'DO NOT put business logic in Widget build(). Keep widgets declarative.'
-    - 'DO NOT use StatefulWidget for shared or long-lived state. Use Riverpod providers.'
-    - 'DO NOT use GlobalKey to reach into child state for app data flow.'
-    - 'DO NOT keep mutable model fields. Prefer immutable classes with copyWith/freezed.'
-    - 'DO NOT run heavy synchronous work on the UI thread. Use compute or Isolate.'
-  guidelines:
-    - 'Use Riverpod with @riverpod code generation and feature-local providers.'
-    - 'Use feature-first directories: lib/features/<feature>/{view,model,provider,logic} and shared code in lib/core.'
-    - 'Use sealed classes and pattern matching for Result/Async state handling.'
-    - 'Prefer const constructors where possible for rebuild efficiency.'
-    - 'Use go_router for declarative routes and deep-link handling.'
-    - 'Use freezed for immutable models and generated equality/copy/JSON methods.'
-    - 'Write widget tests with ProviderScope.overrides and unit-test pure logic separately.'
-    - 'Profile with DevTools before optimization; use RepaintBoundary where repaint isolation is needed.'
-    - 'Handle async states explicitly with AsyncValue or a Result type (loading/success/failure). Set a global error boundary to catch unhandled exceptions before they reach the UI.'
-    - 'Access external APIs/storage via repositories; providers should depend on repository interfaces.'
-  decision_table:
-    - when: 'State is local and ephemeral (focus, small toggle)'
-      then: 'Use StatefulWidget or flutter_hooks state'
-      avoid: 'Creating global/shared providers for trivial local state'
-    - when: 'State is shared or must outlive a widget'
-      then: 'Use Riverpod Notifier/AsyncNotifier'
-      avoid: 'Prop-drilling callback chains'
-    - when: 'A model needs equality/copy/JSON generation'
-      then: 'Use @freezed + build_runner'
-      avoid: 'Manual ==/hashCode/copyWith implementations'
-    - when: 'Navigation and deep links are needed'
-      then: 'Use GoRouter route configuration'
-      avoid: 'Imperative Navigator-only architecture'

package/data/rules/graphql-client-app.yaml

@@ -1,29 +0,0 @@
-id: graphql-client-app
-category: api
-tags:
-  - graphql
-  - frontend
-  - flutter
-priority: 46
-content:
-  constraints:
-    - 'DO NOT call GraphQL endpoints directly from widgets. Route operations through provider/repository layers to avoid rebuild-driven duplicate requests and side effects.'
-    - 'DO NOT parse GraphQL response maps in UI code. Convert payloads to typed freezed/json_serializable models in the data layer to prevent runtime cast/null errors.'
-    - 'DO NOT treat HTTP 200 as success when GraphQL errors[] exists. Map GraphQL errors to typed domain failures.'
-    - 'DO NOT create ad-hoc Dio instances for GraphQL calls. Reuse the shared DI-injected client with auth interceptors.'
-  guidelines:
-    - 'Use Riverpod providers as the boundary between presentation and GraphQL data access.'
-    - 'Generate GraphQL DTO/union models with the same build_runner pipeline used for other app models.'
-    - 'Map __typename-based unions to freezed union types to force exhaustive handling.'
-    - 'Keep optimistic update and cache invalidation logic in repositories/providers, not in widgets.'
-    - 'Log operationName with redacted variables for debugging failed GraphQL operations.'
-  decision_table:
-    - when: 'A widget needs GraphQL data'
-      then: 'Read a Riverpod provider that delegates to repository/use-case'
-      avoid: 'Calling Dio/GraphQL requests directly inside build() or event handlers'
-    - when: 'A mutation returns data plus business errors'
-      then: 'Preserve successful fields and map typed errors into UI state'
-      avoid: 'Treating the full response as fatal failure'
-    - when: 'New GraphQL documents are added'
-      then: 'Run build_runner to regenerate typed models before commit'
-      avoid: 'Manual map access against dynamic JSON payloads'

package/data/rules/graphql-client-web.yaml

@@ -1,30 +0,0 @@
-id: graphql-client-web
-category: api
-tags:
-  - graphql
-  - frontend
-  - nextjs
-  - apollo
-priority: 47
-content:
-  constraints:
-    - 'DO NOT call /graphql with ad-hoc fetch wrappers in Next.js App Router features. Use the shared Apollo client stack to preserve auth links and normalized cache behavior.'
-    - 'DO NOT handwrite GraphQL operation/result types or cast payloads with as assertions. Use generated TypedDocumentNode artifacts.'
-    - 'DO NOT treat HTTP 200 as success when GraphQL errors[] exists. Handle partial-success responses explicitly.'
-    - 'DO NOT create per-feature ApolloClient instances. Reuse one configured provider to preserve auth/cache/link behavior.'
-  guidelines:
-    - 'Use @apollo/client with @apollo/experimental-nextjs-app-support and mount ApolloNextAppProvider once at the app root.'
-    - 'Use GraphQL Codegen client-preset and import generated graphql(...) documents from feature modules.'
-    - 'Set fetchPolicy explicitly per operation (cache-first, network-only, no-cache) based on freshness requirements.'
-    - 'Co-locate .graphql documents and fragments with feature code, and keep fragment names feature-prefixed.'
-    - 'Normalize GraphQL errors/extensions into a shared UI error model before rendering.'
-  decision_table:
-    - when: 'GraphQL data fetching is needed in App Router'
-      then: 'Use the shared ApolloNextAppProvider + generated documents'
-      avoid: 'Ad-hoc raw fetch cache wiring in components'
-    - when: 'A mutation can return both data and business errors'
-      then: 'Render partial-success data and surface typed errors from the same response'
-      avoid: 'Throwing away data whenever errors[] is present'
-    - when: 'A new query document is added'
-      then: 'Regenerate codegen artifacts before committing'
-      avoid: 'Shipping stale generated types/documents'

package/data/rules/graphql-core.yaml

@@ -1,31 +0,0 @@
-id: graphql-core
-category: api
-tags:
-  - graphql
-  - api
-  - schema-contract
-priority: 48
-content:
-  constraints:
-    - 'DO NOT rely on implicit nullability. Mark every field intentionally (prefer non-null by default).'
-    - 'DO NOT return unbounded lists. Every collection must provide pagination arguments and a stable cursor.'
-    - 'DO NOT expose internal implementation details in enum values. Use semantic SCREAMING_SNAKE_CASE names that remain stable across refactors.'
-    - 'DO NOT rename/remove published fields or types in the same release. Deprecate first, then remove in the next major.'
-  guidelines:
-    - 'Follow naming conventions: PascalCase for types/enums, camelCase for fields/arguments, SCREAMING_SNAKE_CASE for enum values.'
-    - 'Prefer cursor pagination (first/after) for user-facing lists; use offset only for bounded admin tables.'
-    - 'Define typed FilterInput/OrderByInput for filtering and sorting instead of JSON-like free-form arguments.'
-    - 'Document scalar contracts (DateTime, UUID, JSON) with accepted formats and timezone policy.'
-  decision_table:
-    - when: 'A field returns a collection'
-      then: 'Use cursor pagination with a stable cursor and deterministic ordering'
-      avoid: 'Returning unbounded [Node!]! lists'
-    - when: 'A field or type must be renamed/removed'
-      then: 'Mark it as @deprecated with a migration reason, keep compatibility for at least one release, remove in next major'
-      avoid: 'Immediate rename/removal that breaks existing client operations'
-    - when: 'A schema change is high-risk (widely used field, auth/payment domain)'
-      then: 'Add pre-release usage checks (operation usage, top callers), publish rollback criteria, and keep a revert path that restores the previous contract'
-      avoid: 'Shipping a contract change without usage visibility or rollback plan'
-    - when: 'Filtering or sorting is complex'
-      then: 'Define typed FilterInput/OrderByInput types'
-      avoid: 'Accepting raw JSON blobs or ad-hoc string filters'

package/data/rules/graphql-server.yaml

@@ -1,33 +0,0 @@
-id: graphql-server
-category: api
-tags:
-  - graphql
-  - api
-  - backend
-priority: 44
-content:
-  constraints:
-    - 'DO NOT perform mutations in Query resolvers. Reads belong to Query, writes belong to Mutation.'
-    - 'DO NOT throw top-level GraphQL errors for expected business failures. Return typed domain errors in payloads.'
-    - 'DO NOT issue per-parent DB queries from field resolvers. Use request-scoped batching (DataLoader or equivalent).'
-    - 'DO NOT accept multiple scalar mutation arguments. Standardize on one input object (mutation X($input: XInput!)).'
-    - 'DO NOT expose unauthenticated subscription/live update endpoints in production.'
-  guidelines:
-    - 'Keep resolvers thin and delegate business logic to service/use-case layers.'
-    - 'Use payload types that carry both success data and typed userErrors for partial success handling.'
-    - 'Apply query depth/complexity limits and operation timeout guards to prevent expensive nested queries.'
-    - 'Record operationName and requestId in structured logs for mutation/subscription debugging.'
-    - 'Document idempotency expectations for side-effecting mutations (payment, provisioning, outbound integrations).'
-  decision_table:
-    - when: 'A mutation can fail due to business validation'
-      then: 'Return payload data + typed userErrors and keep top-level errors for unexpected faults only'
-      avoid: 'Throwing generic Error for expected business branches'
-    - when: 'A field resolver loads related entities'
-      then: 'Batch and cache per-request with DataLoader (or equivalent)'
-      avoid: 'Repository call per parent row (N+1)'
-    - when: 'A new subscription is introduced'
-      then: 'Require auth/tenant checks and choose production-safe PubSub transport'
-      avoid: 'Unauthenticated or in-memory-only subscription setup in production'
-    - when: 'A mutation triggers irreversible side effects (billing, provisioning, partner API)'
-      then: 'Verify pre-conditions first, require idempotency keys, and define compensating/rollback actions before execution'
-      avoid: 'Calling external side effects before validation or without replay/rollback strategy'

package/data/rules/libs-backend-python.yaml

@@ -1,35 +0,0 @@
-id: libs-backend-python
-category: tooling
-tags:
-  - python
-  - backend
-priority: 22
-content:
-  constraints:
-    - 'DO NOT use requirements.txt as the primary dependency spec. Use pyproject.toml with uv (preferred) or Poetry, and commit the lock file.'
-    - 'DO NOT use print() for logging. Use structured JSON logging (structlog).'
-    - 'DO NOT use unittest.TestCase. Use pytest with fixtures.'
-    - 'DO NOT rely on bare assert in production code. Raise explicit exceptions.'
-  guidelines:
-    - 'Use uv for environment and dependency management (uv sync, uv run).'
-    - 'Use pytest + pytest-asyncio + pytest-cov for tests.'
-    - 'Use httpx for sync/async HTTP and ASGITransport for FastAPI integration tests.'
-    - 'Use structlog and bind request_id/user_id in context.'
-    - 'Use ruff for lint + format and enforce it in CI.'
-    - 'Use mypy or pyright in strict mode.'
-    - 'Use pydantic-settings for env loading/validation.'
-    - 'Use tenacity for retry/backoff around transient external calls.'
-    - 'Use pandera or Great Expectations for data quality validation in pipelines.'
-  decision_table:
-    - when: 'Package management is needed'
-      then: 'Use uv + pyproject.toml + lock file'
-      avoid: 'pip-only requirements.txt workflows'
-    - when: 'Lint/format tooling is needed'
-      then: 'Use ruff as the default toolchain'
-      avoid: 'Split flake8/black/isort stacks'
-    - when: 'Data quality checks are needed'
-      then: 'Use pandera or Great Expectations with explicit checks'
-      avoid: 'Scattered inline asserts with no reporting'
-    - when: 'HTTP client is needed'
-      then: 'Use httpx'
-      avoid: 'Mixing requests/aiohttp across services'

package/data/rules/libs-backend-ts.yaml

@@ -1,36 +0,0 @@
-id: libs-backend-ts
-category: tooling
-tags:
-  - typescript
-  - nestjs
-  - backend
-priority: 25
-content:
-  constraints:
-    - 'DO NOT use moment/dayjs. Standardize on date-fns with named imports.'
-    - 'DO NOT use jsonwebtoken. Use jose 6+.'
-    - 'DO NOT handle Express req/res directly in NestJS handlers.'
-    - 'DO NOT import lodash as a full bundle. Prefer native APIs or per-function imports.'
-    - 'DO NOT use node-fetch/got in NestJS services. Use @nestjs/axios HttpModule or native fetch().'
-    - 'DO NOT use winston/morgan/console.log for app logs. Use pino via nestjs-pino.'
-  guidelines:
-    - 'Use class-validator + class-transformer DTO validation with ValidationPipe({ whitelist: true }).'
-    - 'Use jose for JWT sign/verify and JWKS workflows.'
-    - 'Use pino + nestjs-pino as the default structured logger.'
-    - 'Use rxjs operators for NestJS interceptors, guards, and event streams.'
-    - 'Use Vitest + @nestjs/testing + supertest for unit/e2e tests.'
-    - 'Use zod for schema validation outside DTOs (env, external payloads).'
-    - 'Keep TypeScript strict mode enabled.'
-  decision_table:
-    - when: 'JWT auth is needed'
-      then: 'Use jose (SignJWT, jwtVerify, createRemoteJWKSet)'
-      avoid: 'jsonwebtoken'
-    - when: 'Date handling is needed'
-      then: 'Use date-fns named imports'
-      avoid: 'moment/dayjs'
-    - when: 'Utility helpers are needed (clone/groupBy)'
-      then: 'Use native JS first; fallback to scoped lodash imports only'
-      avoid: 'import _ from "lodash"'
-    - when: 'Structured logging is needed'
-      then: 'Use pino via nestjs-pino LoggerModule.forRoot()'
-      avoid: 'console.log or mixed logging stacks'

package/data/rules/libs-frontend-app.yaml

@@ -1,39 +0,0 @@
-id: libs-frontend-app
-category: tooling
-tags:
-  - dart
-  - flutter
-  - frontend
-priority: 15
-content:
-  constraints:
-    - 'DO NOT use http for API calls. Standardize on dio 5+.'
-    - 'DO NOT use Provider or Bloc. Standardize on flutter_riverpod with code generation.'
-    - 'DO NOT handwrite data classes (==, hashCode, copyWith, toJson). Use freezed.'
-    - 'DO NOT use Navigator 1.0 push/pop APIs for app routing. Use go_router.'
-    - 'DO NOT manually implement JSON serialization for models. Use json_serializable/freezed generation.'
-  guidelines:
-    - 'Use @riverpod with riverpod_generator and build_runner for provider generation.'
-    - 'Use freezed for immutable models and unions.'
-    - 'Define routes in a central GoRouter config and navigate with context.go()/push().'
-    - 'Create one shared Dio instance via Riverpod DI with interceptors and auth headers.'
-    - 'Use shared_preferences for non-sensitive keys and flutter_secure_storage for secrets.'
-    - 'Use cached_network_image for network image caching and placeholders.'
-    - 'Use very_good_analysis and treat warnings as CI failures.'
-    - 'Use intl/easy_localization with ARB-based translations.'
-  decision_table:
-    - when: 'HTTP API calls are needed'
-      then: 'Use DI-injected central Dio client'
-      avoid: 'Per-feature ad-hoc http clients'
-    - when: 'Simple local persistence is needed'
-      then: 'Use shared_preferences or flutter_secure_storage by data sensitivity'
-      avoid: 'SQLite/Hive for plain key-value settings'
-    - when: 'Network images are rendered'
-      then: 'Use cached_network_image with placeholder/error states'
-      avoid: 'Bare Image.network everywhere'
-    - when: 'Test mocking is needed'
-      then: 'Use mocktail (class-based, no code generation required)'
-      avoid: 'mockito with @GenerateMocks annotation boilerplate'
-    - when: 'Code generation is required'
-      then: 'Run build_runner watch in dev and build in CI'
-      avoid: 'Manually editing generated files'

package/data/rules/libs-frontend-web.yaml

@@ -1,39 +0,0 @@
-id: libs-frontend-web
-category: tooling
-tags:
-  - typescript
-  - react
-  - nextjs
-  - frontend
-priority: 20
-content:
-  constraints:
-    - 'DO NOT use moment.js or dayjs. Standardize on date-fns with named imports.'
-    - 'DO NOT use react-icons. Use lucide-react named imports only.'
-    - 'DO NOT use axios in browser code. Use native fetch() for Next.js cache/revalidate integration.'
-    - 'DO NOT build conditional className strings manually. Use cn() and cva().'
-    - 'DO NOT install parallel UI kits (MUI, Ant, Chakra) alongside shadcn/ui.'
-    - 'DO NOT use Redux/Recoil/MobX for local UI state. Use zustand for client UI state.'
-  guidelines:
-    - 'Keep styling on Tailwind + design tokens (CSS variables) and cva variants.'
-    - 'Use next-intl for i18n and next-themes for theme switching.'
-    - 'Render Recharts inside client components only.'
-    - 'Mount one Sonner <Toaster /> at the app root and call toast() from features.'
-    - 'Sanitize user HTML with isomorphic-dompurify before dangerouslySetInnerHTML.'
-    - 'Use Vitest + Testing Library; prefer userEvent over fireEvent.'
-  decision_table:
-    - when: 'Date handling is needed'
-      then: 'Use date-fns named imports'
-      avoid: 'moment/dayjs'
-    - when: 'Icons are needed'
-      then: 'Use lucide-react named imports'
-      avoid: 'react-icons or inline SVG'
-    - when: 'Form validation is needed'
-      then: 'Use zod + react-hook-form + zod resolver'
-      avoid: 'Manual validation in component event handlers'
-    - when: 'User-generated HTML must be rendered'
-      then: 'Sanitize with isomorphic-dompurify first, then dangerouslySetInnerHTML'
-      avoid: 'Rendering unsanitized HTML (XSS risk)'
-    - when: 'Client UI state is needed (modals, wizard step, sidebar)'
-      then: 'Use a zustand slice'
-      avoid: 'Global Redux/Recoil for simple UI state'

package/data/rules/nestjs-graphql.yaml

@@ -1,31 +0,0 @@
-id: nestjs-graphql
-category: framework
-tags:
-  - typescript
-  - nestjs
-  - graphql
-priority: 43
-content:
-  constraints:
-    - 'DO NOT put business logic in Resolvers. Keep resolvers thin and delegate to Services.'
-    - 'DO NOT access raw GraphQL args/context manually when typed decorators are available. Use @Args() with typed DTOs.'
-    - 'DO NOT query the DB directly inside @ResolveField(). Use request-scoped DataLoaders.'
-    - 'DO NOT expose unauthenticated @Subscription() endpoints. Protect with guards and subscriber checks.'
-    - 'DO NOT maintain manual SDL in code-first projects. TypeScript decorators are the source of truth.'
-  guidelines:
-    - 'Use one resolver per domain entity with @Resolver(), @Query(), @Mutation(), and @ResolveField() responsibilities clearly separated.'
-    - 'Register DataLoaders as request-scoped providers to enable per-request batching without cross-request leakage.'
-    - 'Add decorator descriptions for public schema types and fields to keep generated SDL self-documenting.'
-    - 'Enforce query depth/complexity limits to prevent expensive nested query abuse.'
-    - 'Define and register custom scalars (DateTime, UUID, JSON) consistently in GraphQL module config.'
-    - 'Reuse Guards/Interceptors from REST and adapt context via GqlExecutionContext.'
-  decision_table:
-    - when: 'A field resolver loads related data (e.g., user.posts)'
-      then: 'Use @ResolveField() + request-scoped DataLoader batching'
-      avoid: 'Repository call per parent row (N+1)'
-    - when: 'Real-time push is required'
-      then: 'Use @Subscription() with Redis PubSub for multi-instance deployments'
-      avoid: 'In-memory PubSub in production'
-    - when: 'Resolver auth is required'
-      then: 'Apply @UseGuards(GqlAuthGuard) and read user from GqlExecutionContext'
-      avoid: 'Manual JWT parsing inside resolver methods'

package/data/rules/nestjs.yaml

@@ -1,26 +0,0 @@
-id: nestjs
-category: framework
-tags:
-  - typescript
-  - nestjs
-priority: 45
-content:
-  constraints:
-    - 'DO NOT use @Res() or @Response() for manual response handling in normal routes. Return values and let Nest handle serialization/interceptors.'
-    - 'DO NOT put business logic in Controllers. Delegate to Services.'
-    - 'DO NOT use forwardRef() as a default fix for circular dependencies. Refactor module boundaries.'
-    - 'DO NOT read process.env directly in services/controllers. Use ConfigService with validated schema.'
-    - 'DO NOT use console.log for app logging. Use Nest Logger or a DI-managed logger (e.g., pino).'
-  guidelines:
-    - 'Organize by feature module and co-locate controller/service/DTO files by domain.'
-    - 'Use class-validator DTOs for request boundaries and avoid exposing persistence entities directly.'
-    - 'Register global ValidationPipe, filters, and guards in main.ts bootstrap.'
-    - 'Use custom HttpException types for domain/business failures.'
-    - 'Use @nestjs/swagger decorators for REST APIs; GraphQL schema serves as contract for GraphQL APIs.'
-  decision_table:
-    - when: 'A cross-cutting check needs handler metadata (auth/roles)'
-      then: 'Use Guards'
-      avoid: 'Middleware for authorization logic'
-    - when: 'You need response transform/caching/timing'
-      then: 'Use Interceptors'
-      avoid: 'Middleware for response-layer behavior'

package/data/rules/nextjs.yaml

@@ -1,34 +0,0 @@
-id: nextjs
-category: framework
-tags:
-  - typescript
-  - react
-  - nextjs
-  - app-router
-priority: 50
-content:
-  constraints:
-    - "DO NOT import server-only code into Client Components. Enforce with 'server-only'."
-    - 'DO NOT store secrets in NEXT_PUBLIC_ variables. Only NEXT_PUBLIC_ vars are exposed to the browser bundle.'
-    - 'DO NOT use next/router in App Router projects. Use next/navigation APIs.'
-  guidelines:
-    - 'Follow App Router file conventions (page.tsx, layout.tsx, loading.tsx, error.tsx, not-found.tsx).'
-    - "Keep Server Actions in dedicated files (e.g., actions.ts) with 'use server'."
-    - 'Use next/image with explicit dimensions or fill + sizes.'
-    - 'Use next/font in root layout and apply through CSS variables.'
-    - 'Use middleware.ts only for cross-cutting concerns (auth redirect, locale, header policy).'
-    - 'Export metadata (or generateMetadata) for public pages with title/description/OpenGraph.'
-    - 'Add JSON-LD structured data for public pages when SEO/GEO matters.'
-  decision_table:
-    - when: 'A component needs browser APIs, state hooks, or event handlers'
-      then: "Add 'use client' at the smallest leaf component"
-      avoid: "Marking high-level parent trees as 'use client'"
-    - when: 'Page data is needed for initial render'
-      then: 'Fetch in Server Components with async/await'
-      avoid: 'Client-side useEffect fetch for primary page data'
-    - when: 'Internal form mutation is needed'
-      then: 'Use Server Actions'
-      avoid: 'route.ts endpoints for simple internal form writes'
-    - when: 'External API/webhook endpoint is needed'
-      then: 'Use route.ts with explicit HTTP method exports'
-      avoid: 'Server Actions for public API integration points'

package/data/rules/prisma-postgresql.yaml

@@ -1,30 +0,0 @@
-id: prisma-postgresql
-category: database
-tags:
-  - typescript
-  - prisma
-  - postgresql
-priority: 40
-content:
-  constraints:
-    - 'DO NOT interpolate strings in $queryRawUnsafe. Use $queryRaw tagged templates or parameterized placeholders.'
-    - 'DO NOT return Prisma models directly from APIs. Use select or DTO mapping to avoid leaking sensitive fields.'
-    - 'DO NOT define mutable models without updatedAt DateTime @updatedAt.'
-    - 'DO NOT use $use() middleware. Use Client Extensions ($extends) in Prisma v7+.'
-    - 'DO NOT use prisma db push in production. Use prisma migrate deploy with versioned migrations.'
-  guidelines:
-    - 'Use generator client { provider = "prisma-client"; output = "./generated/prisma/client" }.'
-    - 'Use @prisma/adapter-pg and set explicit pool/timeout values for your environment.'
-    - 'Add indexes for frequent where/orderBy/join patterns, including composite indexes where needed.'
-    - 'Set explicit timeout and maxWait for interactive transactions.'
-    - 'Centralize datasource and migration settings in prisma.config.ts.'
-    - 'Implement soft delete with a Client Extension query hook that injects deletedAt: null filtering.'
-    - 'Prefer cursor pagination over deep skip/take for large tables.'
-    - 'Use an external pooler (e.g., PgBouncer) or explicit adapter connection limits in serverless/container workloads.'
-  decision_table:
-    - when: 'A query needs PostgreSQL features Prisma API cannot express well'
-      then: 'Use $queryRaw with tagged templates and typed result mapping'
-      avoid: 'Unsafe string-built SQL'
-    - when: 'A transaction has dependent steps'
-      then: 'Use interactive $transaction(async (tx) => ...) with explicit timeout/maxWait'
-      avoid: 'Batch $transaction([...]) for interdependent operations'

package/data/rules/python.yaml

@@ -1,31 +0,0 @@
-id: python
-category: language
-tags:
-  - python
-priority: 55
-content:
-  constraints:
-    - 'DO NOT use Any in type hints. Use object or concrete generics instead.'
-    - 'DO NOT use mutable default arguments. Use None + factory inside the function.'
-    - 'DO NOT use bare except or broad except Exception. Catch specific exception types.'
-    - 'DO NOT use wildcard imports.'
-    - 'DO NOT use type(x) == T checks. Prefer isinstance() or protocol-based checks.'
-    - 'DO NOT use # type: ignore without an explicit error code.'
-  guidelines:
-    - 'Annotate all function parameters and return types, including -> None.'
-    - 'Use Pydantic v2 BaseModel for DTO/config schemas; use field_validator/model_validator APIs.'
-    - 'Use TypeAlias, TypeVar, ParamSpec, TypedDict, and Literal to model intent clearly.'
-    - 'Keep business logic in pure *_logic.py modules; keep routers/services thin.'
-    - 'Use @dataclass(frozen=True) for immutable value objects that do not need runtime validation.'
-    - 'Use pathlib.Path for filesystem paths.'
-    - 'Use f-strings for string formatting.'
-  decision_table:
-    - when: 'Structured input/output needs validation or serialization'
-      then: 'Use Pydantic v2 models'
-      avoid: 'Unvalidated dict payloads'
-    - when: 'Immutable value object without runtime validation is enough'
-      then: 'Use @dataclass(frozen=True)'
-      avoid: 'Using Pydantic where validation is unnecessary'
-    - when: 'Runtime type narrowing is needed'
-      then: 'Use isinstance() or model_validate()'
-      avoid: 'Fragile type()/hasattr() checks'