ai-ops-cli 0.1.11 → 0.1.14

package/data/presets.yaml

@@ -11,6 +11,7 @@ frontend-web:
     - react-typescript
     - shadcn-ui
     - nextjs
+    - graphql
     - libs-frontend-web
 
 frontend-app:
@@ -23,6 +24,7 @@ frontend-app:
     - naming-convention
     - engineering-standards
     - flutter
+    - graphql
     - libs-frontend-app
 
 backend-ts:

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

@@ -0,0 +1,29 @@
+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

@@ -0,0 +1,30 @@
+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

@@ -0,0 +1,31 @@
+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

@@ -0,0 +1,33 @@
+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-ts.yaml

@@ -15,8 +15,6 @@ content:
     - '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 @nestjs/graphql + @nestjs/apollo code-first for GraphQL APIs.'
-    - 'Use GraphQL Codegen for operation/result type generation.'
     - '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.'

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

@@ -15,8 +15,6 @@ content:
     - '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:
-    - 'Use @apollo/client with @apollo/experimental-nextjs-app-support for GraphQL in App Router.'
-    - 'Use GraphQL Codegen client-preset to generate TypedDocumentNode types at build time.'
     - '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.'
@@ -24,9 +22,6 @@ content:
     - 'Sanitize user HTML with isomorphic-dompurify before dangerouslySetInnerHTML.'
     - 'Use Vitest + Testing Library; prefer userEvent over fireEvent.'
   decision_table:
-    - when: 'GraphQL data fetching is needed in App Router'
-      then: 'Use ApolloNextAppProvider with @apollo/client'
-      avoid: 'Ad-hoc raw fetch cache wiring'
     - when: 'Date handling is needed'
       then: 'Use date-fns named imports'
       avoid: 'moment/dayjs'