opencode-andev-rules 1.0.0 → 1.0.2

package/skills/infrastructure/prisma/references/prisma-schema.md

@@ -0,0 +1,126 @@
+# Prisma Schema Structure Rules
+
+## Layout
+
+- Follow this tree exactly — schema, migrations, and seed stay under `prisma/`.
+- Split the schema per domain under `prisma/schema/` — never one giant `schema.prisma`.
+
+```
+prisma/
+├── schema/
+│   ├── base.prisma
+│   ├── user.prisma
+│   └── order.prisma
+├── seed.ts
+└── migrations/
+    └── 20240101000000_init/
+        └── migration.sql
+```
+
+- `base.prisma` holds only `generator` + `datasource` — never models or enums in it.
+- One file per domain (`user.prisma`, `order.prisma`, ...) holding its models + enums — never split one model across files.
+- Cross-file relations reference the model by name — Prisma merges all files, no imports needed.
+- One model per table — never two models over the same table.
+
+## Models
+
+- Model names PascalCase singular with `@@map` to the snake_case table (e.g., `model User ... @@map("users")`).
+- Field names camelCase; map to snake_case columns with `@map` when the database uses snake_case.
+- Every model has a primary key, `createdAt`, and `updatedAt` — never a model without a PK.
+- Primary keys are `String @id @default(uuid())` — never auto-increment ints for IDs.
+- Soft-delete with `deletedAt DateTime?` — always filter it in queries, never return soft-deleted rows by default.
+- Put DB-level defaults in the schema (`@default`, `@updatedAt`) — never rely on application code for timestamps.
+
+```prisma
+model User {
+  id        String    @id @default(uuid())
+  email     String    @unique
+  name      String
+  role      Role      @default(USER)
+  createdAt DateTime  @default(now())
+  updatedAt DateTime  @updatedAt
+  deletedAt DateTime?
+
+  @@map("users")
+}
+```
+
+## Enums
+
+- Fixed sets (status, role) are Prisma enums — never free strings for status-like fields.
+- Map enum values explicitly when the database stores different labels.
+
+```prisma
+enum Role {
+  ADMIN
+  USER
+}
+```
+
+## Relations
+
+- Confirm FK/PK mode first (decision gate in `SKILL.md`) — the rules below assume DB-enforced foreign keys.
+- No-FK mode: skip DB constraints and `onDelete`, enforce integrity in code with existence checks + transactions.
+- Name relations explicitly when two models link more than once — never leave ambiguous relations unnamed.
+- Set `onDelete` deliberately per relation (`Cascade`, `Restrict`, `SetNull`) — never accept the default without thinking; dangerous cascades stay out.
+- Use an explicit relation table for many-to-many that carries extra fields — never overload a pure join with payload columns.
+- Index every foreign key — Prisma does not auto-index all relation columns on every provider.
+
+```prisma
+// WITH FK/PK — database enforces the relation
+// schema/user.prisma
+model User {
+  id    String @id @default(uuid())
+  email String @unique
+  posts Post[]
+
+  @@map("users")
+}
+
+// schema/post.prisma
+model Post {
+  id       String @id @default(uuid())
+  title    String
+  authorId String
+  author   User   @relation(fields: [authorId], references: [id], onDelete: Cascade)
+
+  @@index([authorId])
+  @@map("posts")
+}
+```
+
+```prisma
+// WITHOUT FK/PK — Prisma emulates the relation, DB has no constraints
+// schema/base.prisma
+datasource db {
+  provider     = "postgresql"
+  url          = env("DATABASE_URL")
+  relationMode = "prisma"
+}
+
+// schema/post.prisma
+model Post {
+  id       String @id @default(uuid())
+  title    String
+  authorId String // plain scalar — no FK constraint in the DB
+  author   User   @relation(fields: [authorId], references: [id])
+
+  @@index([authorId])
+  @@map("posts")
+}
+// integrity (author must exist) enforced in code + transactions — see SKILL.md
+```
+
+## Indexes & Constraints
+
+- Add `@@index` for frequently filtered/sorted fields and composite `@@index([a, b])` for common multi-field queries.
+- Add `@@unique` / `@unique` for data that must be unique (email, slug) — enforce in the database, not only in code.
+- Never duplicate or redundant indexes — one index per access pattern.
+- Keep nullable/required aligned across schema, DTO validation, and application types — inconsistent nullability is a bug source.
+
+## Migrations
+
+- Name migrations after what they do (`add_user_role`, not `update`) — one logical change per migration.
+- Schema changes that need existing rows rewritten ship with a data migration — never lose rows silently.
+- Changing a field type or dropping a column requires a backfill/dual-write plan when the table has data.
+- Never hand-edit `migration.sql` of an applied migration — revert with a new migration instead.

package/skills/registry.json

@@ -1,15 +1,57 @@
 {
   "name": "andev-skills",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "AI agent skills by thaiannguyen-05",
   "skills": [
     {
       "name": "improve-codenase-systems",
       "description": "Scan codebase for architecture issues and deepening opportunities",
       "version": "1.0.0",
-      "tags": ["architecture", "review", "nestjs", "react", "codebase"],
-      "path": "skills/improve-codenase-systems",
-      "files": ["SKILL.md", "HTML-REPORT.md", "agents/openai.yaml"]
+      "tags": [
+        "architecture",
+        "review",
+        "nestjs",
+        "react",
+        "codebase"
+      ],
+      "path": "skills/enhance/improve-codenase-systems",
+      "files": [
+        "SKILL.md",
+        "HTML-REPORT.md",
+        "agents/openai.yaml"
+      ]
+    },
+    {
+      "name": "nestjs",
+      "description": "NestJS backend rules — Fastify platform, module structure, zod validation",
+      "version": "1.0.0",
+      "tags": [
+        "nestjs",
+        "backend",
+        "typescript"
+      ],
+      "path": "skills/backend/nestJS",
+      "files": [
+        "SKILL.md",
+        "references/nestjs-module.md",
+        "references/nestjs-testing.md"
+      ]
+    },
+    {
+      "name": "prisma",
+      "description": "Prisma ORM rules — client setup, queries, errors, transactions, migrations",
+      "version": "1.0.0",
+      "tags": [
+        "prisma",
+        "database",
+        "orm"
+      ],
+      "path": "skills/infrastructure/prisma",
+      "files": [
+        "SKILL.md",
+        "references/prisma-queries.md",
+        "references/prisma-schema.md"
+      ]
     }
   ]
 }

package/RULES.md

@@ -1,253 +0,0 @@
-# Rules for TypeScript & NestJS
-
-## TypeScript
-
-- Use `strict: true` in `tsconfig.json`
-- No `any` type — use `unknown` and narrow with type guards
-- Use `interface` for object shapes, `type` for unions/intersections
-- Prefer `readonly` for immutable data
-- Avoid type assertions (`as`) — use type guards or `satisfies` instead
-- Use `!` non-null assertion only when value is guaranteed (add comment why)
-- Export types from barrel files (`index.ts`)
-
-## NestJS
-
-- Use CLI to generate: `nest g module`, `nest g controller`, `nest g service`
-- One module per feature (e.g., `users/`, `auth/`, `orders/`)
-- Controllers handle HTTP — no business logic in controllers
-- Services handle business logic — no HTTP concerns in services
-- Use `@nestjs/swagger` decorators on DTOs and controllers
-- Inject dependencies via constructor — never instantiate manually
-- Use `@InjectRepository()` for TypeORM/Prisma repositories
-- Use guards for auth (`@UseGuards`), interceptors for logging/transformation
-- Use `ConfigModule` for environment variables — no `process.env` in code
-- Use `@nestjs/schedule` for cron jobs — no `setInterval`
-
-## Types
-
-- Every module must have a `types.ts` file for module-specific types
-- Export all types from `types.ts` — import from there in other files
-- Use `type.ts` for: enums, interfaces, type aliases, return types
-- Do NOT put types in `dto/` — DTOs are for validation, types are for contracts
-- Import pattern: `import { UserRole } from './types'`
-- Put constants in `types.ts`: event names, URLs, status codes, config values
-- Use `enum` for constants — no hardcoded strings in business logic
-
-```typescript
-// types.ts
-export enum EventName {
-  CREATED = 'user.created',
-  UPDATED = 'user.updated',
-  DELETED = 'user.deleted',
-}
-
-export enum ApiUrl {
-  BASE = '/api/v1',
-  USERS = '/api/v1/users',
-}
-
-export interface User { id: string; name: string; }
-```
-
-## Validation
-
-- Handle ALL validation before controller and service
-- Use global `ValidationPipe` in `main.ts` — reject invalid requests early
-- Use `class-validator` decorators on DTOs
-- Use `class-transformer` with `ValidationPipe` globally
-- Validate nested objects with `@ValidateNested()`
-- Use `@IsString()`, `@IsNumber()`, `@IsEmail()`, `@IsOptional()` etc.
-- Controllers and services receive only valid data — no validation logic inside
-- Use `WhitelistStrategy` + `ForbidNonWhitelisted` to reject unknown fields
-- Use `TransformPipe` to auto-transform payloads to DTO instances
-
-```typescript
-// main.ts
-app.useGlobalPipes(
-  new ValidationPipe({
-    whitelist: true,
-    forbidNonWhitelisted: true,
-    transform: true,
-  }),
-);
-```
-
-## Error Handling
-
-- Handle errors with exceptions — use custom `AppException` classes
-- Create `src/error/` directory with exception classes and global filter
-- `errorCode` = uppercase snake_case (e.g., `RESOURCE_NOT_FOUND`)
-- Always return consistent JSON: `{ statusCode, timestamp, path, message, errorCode?, details? }`
-- Log unhandled (non-HttpException) errors with logger
-- Create helper files for domain-specific error scenarios
-
-```typescript
-// app.exception.ts
-export class AppException extends HttpException {
-  constructor(
-    message: string,
-    statusCode: HttpStatus,
-    public readonly errorCode?: string,
-    public readonly details?: unknown,
-  ) {
-    super({ message, errorCode, details, timestamp: new Date().toISOString() }, statusCode);
-  }
-}
-
-export class ResourceNotFoundException extends AppException {
-  constructor(resourceType: string, identifier: string | number) {
-    super(`${resourceType} with identifier ${identifier} not found`, HttpStatus.NOT_FOUND, 'RESOURCE_NOT_FOUND');
-  }
-}
-```
-
-```typescript
-// main.ts
-app.useGlobalFilters(new GlobalExceptionFilter(logger));
-```
-
-## Database
-
-- Use Prisma or TypeORM — pick one, don't mix
-- Keep migrations in `prisma/migrations` or `src/migrations`
-- Use repositories or Prisma client for data access
-- Never write raw SQL unless performance-critical (add comment why)
-- Use `select` when only a subset of fields is required — don't over-fetch
-- Avoid N+1 queries — use `include` or joins, not loops
-- Run independent queries in parallel — don't `await` sequentially
-- Use `findFirst` only when `findUnique` is possible
-- Paginate `findMany` — never return unbounded results
-- Use cursor pagination for large datasets, offset for small
-- Always `orderBy` deterministic fields for pagination
-- Handle Prisma errors — never leak raw Prisma errors to API responses
-- Use transactions for multi-step operations — no partial writes
-- Keep transaction scope small — no external calls inside transactions
-- Race conditions on read-modify-write — use transactions or locks
-- Add unique constraints for data that must be unique
-- Soft-delete: always filter `deletedAt` in queries
-- Avoid `include` for large relation collections — paginate or select
-
-## Testing
-
-- Use Jest (built into NestJS)
-- Unit tests: `*.spec.ts` next to source files
-- E2E tests: `test/*.e2e-spec.ts`
-- Mock dependencies with `@nestjs/testing` `Test.createTestingModule()`
-- Test controllers and services separately
-- Use `supertest` for HTTP assertions in e2e
-
-## Async & Concurrency
-
-- Run independent async operations in parallel — don't `await` sequentially
-- Always handle promise rejections — no fire-and-forget without error handling
-- Add timeout for external service calls
-- Use idempotency keys for retryable operations
-- Retry with limits and exponential backoff
-- Never retry non-idempotent operations unsafely
-- Race conditions: use transactions or locks for read-modify-write
-
-## Security
-
-- Never hardcode secrets or credentials — use `ConfigModule`
-- Never expose sensitive data in API responses
-- Validate and sanitize all user input
-- Prevent IDOR — check resource ownership
-- Use parameterized queries — no raw SQL concatenation
-- Validate file uploads: size, type, content
-- Never trust client-provided file metadata
-- Secure CORS configuration — no wildcard in production
-- Rate limit sensitive endpoints (login, register, password reset)
-- Never log sensitive data (passwords, tokens, PII)
-- Use guards for auth — no manual auth checks in controllers
-
-## API Design
-
-- Consistent REST naming: plural nouns, HTTP verbs for actions
-- Consistent error response format: `{ statusCode, message, errorCode }`
-- Paginate all list endpoints — no unbounded responses
-- Filter and limit query parameters
-- Version API when making breaking changes
-- Use appropriate HTTP status codes (201 for create, 204 for delete)
-- Never expose internal implementation details in responses
-
-## Observability
-
-- Use structured logging (nestjs-pino)
-- Never log sensitive data
-- Propagate request/correlation IDs
-- Add health check endpoints for critical dependencies
-- Handle graceful shutdown — clean up connections
-- Clean up timers, listeners, subscriptions
-- Handle background job failures
-
-## File Structure
-
-```
-andev-skill-agent/
-├── .git/
-├── package.json        # @thaiannguyen-05/opencode-rules
-├── plugin.js           # trigger detection + GitHub fetch
-├── README.md           # usage docs
-└── RULES.md            # this file — rules for agents
-```
-
-### NestJS Project Structure
-
-```
-src/
-├── app.module.ts
-├── main.ts
-├── config/
-│   └── configuration.ts
-├── common/
-│   ├── guards/
-│   ├── interceptors/
-│   ├── pipes/
-│   └── decorators/
-├── error/
-│   ├── app.exception.ts
-│   ├── global.exception.ts
-│   └── [domain]-error.helper.ts
-├── modules/
-│   ├── users/
-│   │   ├── users.module.ts
-│   │   ├── users.controller.ts
-│   │   ├── users.service.ts
-│   │   ├── types.ts
-│   │   ├── dto/
-│   │   └── entities/
-│   ├── auth/
-│   │   ├── auth.module.ts
-│   │   ├── auth.controller.ts
-│   │   ├── auth.service.ts
-│   │   ├── types.ts
-│   │   ├── dto/
-│   │   └── entities/
-│   └── orders/
-│       ├── orders.module.ts
-│       ├── orders.controller.ts
-│       ├── orders.service.ts
-│       ├── types.ts
-│       ├── dto/
-│       └── entities/
-```
-
-## Code Style
-
-- Use Prettier for formatting
-- Use ESLint with `@typescript-eslint` rules
-- Max 300 lines per file — split if超过
-- One export per file — no barrel exports in middle of file
-- Sort imports: node builtins → external → internal → relative
-- Use `path aliases` (`@/`) for clean imports
-- Prefer `async/await` over `.then()` chains
-- Use `enum` for constants — no hardcoded strings
-
-```json
-// .eslintrc
-{
-  "rules": {
-    "max-lines": ["error", { "max": 300, "skipBlankLines": true, "skipComments": true }]
-  }
-}
-```

package/plugin.js

@@ -1,96 +0,0 @@
-// @thaiannguyen-05/opencode-rules
-//
-// On-demand rule injection plugin for opencode.
-// When user says "follow the rule of andev" (or similar), fetches RULES.md
-// from GitHub and injects it into the system prompt.
-//
-// Hooks:
-//   - chat.message: detect trigger phrase in user input
-//   - experimental.chat.system.transform: inject rules into system prompt
-
-const RULES_URL = 'https://raw.githubusercontent.com/thaiannguyen-05/rules-for-global-agents/main/RULES.md';
-
-// Trigger patterns — case-insensitive
-const TRIGGER_PATTERNS = [
-  /follow\s+(the\s+)?rules?\s+of\s+andev/i,
-  /follow\s+andev\s+rules?/i,
-  /use\s+andev\s+rules?/i,
-  /apply\s+andev\s+rules?/i,
-  /andev\s+rules/i,
-];
-
-// In-memory cache: rules text per session
-let cachedRules = null;
-let fetchFailed = false;
-
-function detectTrigger(text) {
-  if (!text) return false;
-  return TRIGGER_PATTERNS.some((pattern) => pattern.test(text));
-}
-
-async function fetchRules() {
-  // Return cache if available
-  if (cachedRules !== null) return cachedRules;
-
-  // Don't retry if fetch already failed
-  if (fetchFailed) return null;
-
-  try {
-    const response = await fetch(RULES_URL, {
-      headers: { Accept: 'text/plain' },
-    });
-
-    if (!response.ok) {
-      fetchFailed = true;
-      return null;
-    }
-
-    const text = await response.text();
-
-    if (!text || text.trim().length === 0) {
-      fetchFailed = true;
-      return null;
-    }
-
-    cachedRules = text;
-    return cachedRules;
-  } catch {
-    fetchFailed = true;
-    return null;
-  }
-}
-
-export const AndevRulesPlugin = async (_ctx) => {
-  let triggerDetected = false;
-
-  return {
-    // Detect trigger phrase in user messages
-    'chat.message': async (_input, output) => {
-      if (!output || !output.parts) return;
-
-      for (const part of output.parts) {
-        if (part && part.type === 'text' && part.text) {
-          if (detectTrigger(part.text)) {
-            triggerDetected = true;
-          }
-        }
-      }
-    },
-
-    // Inject rules into system prompt when trigger was detected
-    'experimental.chat.system.transform': async (_input, output) => {
-      if (!output || !Array.isArray(output.system)) return;
-      if (!triggerDetected) return;
-
-      const rules = await fetchRules();
-      if (rules) {
-        output.system.push(`## Rules from andev (follow these rules)\n\n${rules}`);
-      }
-
-      // Reset trigger for next message
-      triggerDetected = false;
-    },
-  };
-};
-
-export default AndevRulesPlugin;