opencode-andev-rules 1.0.0 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thaiannguyen-05
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,56 +1,66 @@
-# @thaiannguyen-05/opencode-rules
+# opencode-andev-rules
 
-Global coding rules for TypeScript & NestJS. Plugin for opencode.
+Global coding rules for TypeScript & NestJS + AI agent skills.
 
-## Cài Plugin
+[![CI](https://github.com/thaiannguyen-05/rules-for-global-agents/actions/workflows/ci.yml/badge.svg)](https://github.com/thaiannguyen-05/rules-for-global-agents/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/opencode-andev-rules)](https://www.npmjs.com/package/opencode-andev-rules)
 
-```bash
-opencode plugin @thaiannguyen-05/opencode-rules
-```
-
-hoặc:
-
-```bash
-cd ~/.config/opencode
-npm install @thaiannguyen-05/opencode-rules
-```
-
-Thêm vào `opencode.json`:
+## Cài đặt
 
-```json
-{
-  "plugins": ["@thaiannguyen-05/opencode-rules"]
-}
-```
-
-## Cài Skill
+### Cách 1 — npm (khuyên dùng)
 
 ```bash
-npx @thaiannguyen-05/skills-cli add improve-codenase-systems
+npm install opencode-andev-rules
+# skills nằm ở node_modules/opencode-andev-rules/skills/
 ```
 
-hoặc:
+### Cách 2 — copy thủ công
 
 ```bash
-cp -r skills/improve-codenase-systems ~/.agents/skills/
+cp -r skills/enhance/improve-codenase-systems ~/.agents/skills/
+cp -r skills/backend/nestJS ~/.agents/skills/
+cp -r skills/infrastructure/prisma ~/.agents/skills/
 ```
 
-## Sử dụng
-
-### Rules
+## Skills
 
-Nói "follow the rule of andev" trong prompt.
+| Skill | Đường dẫn | Dùng khi |
+|-------|-----------|----------|
+| `improve-codenase-systems` | `skills/enhance/improve-codenase-systems/` | Muốn scan codebase tìm vấn đề kiến trúc — nói "scan codebase" hoặc "improve codebase" trong prompt |
+| `nestjs` | `skills/backend/nestJS/` | Viết/review code NestJS — module structure, Fastify, zod validation, DI |
+| `prisma` | `skills/infrastructure/prisma/` | Viết/review Prisma — client singleton, queries, transactions, migrations |
 
-### Skill
+Chi tiết từng skill xem file `SKILL.md` trong thư mục tương ứng. Danh mục đầy đủ: `skills/registry.json`.
 
-Nói "scan codebase" hoặc "improve codebase" trong prompt.
+## Cấu trúc repo
 
-## Rules
+```
+skills/
+├── backend/nestJS/                    # rules NestJS
+│   ├── SKILL.md
+│   └── references/nestjs-module.md
+├── infrastructure/prisma/             # rules Prisma
+│   ├── SKILL.md
+│   └── references/
+├── enhance/improve-codenase-systems/   # skill scan kiến trúc
+│   ├── SKILL.md
+│   ├── HTML-REPORT.md
+│   ├── meta.json
+│   └── agents/openai.yaml
+└── registry.json                      # danh mục skills (version top-level sync với package.json)
+scripts/
+├── validate.sh      # kiểm tra frontmatter SKILL.md + registry + npm pack --dry-run
+├── check-version.sh # kiểm tra version chưa tồn tại trên npm
+└── release.sh       # bump version an toàn (xem dưới)
+.github/workflows/
+├── ci.yml           # 3 jobs async song song (frontmatter/registry/pack) trên mỗi push/PR
+└── publish.yml      # nút Run workflow: tự bump version + publish lên npm
+```
 
-Xem `RULES.md` — covers TypeScript, NestJS, validation, error handling, database, security, API design, testing, and code style.
+## Đóng góp
 
-## Skills
+1. Sửa/thêm skill trong `skills/`, mỗi skill phải có `SKILL.md` với frontmatter `name:` + `description:`.
+2. Khai báo skill mới vào `skills/registry.json`.
+3. Chạy `npm run validate` trước khi push.
+4. **Không sửa version bằng tay** — version do workflow publish tự tăng (xem dưới).
 
-| Skill | Description |
-|-------|-------------|
-| `improve-codenase-systems` | Scan codebase for architecture issues |

package/package.json

@@ -1,25 +1,39 @@
 {
   "name": "opencode-andev-rules",
-  "version": "1.0.0",
-  "description": "On-demand rule injection plugin for opencode. Say 'follow the rule of andev' to load rules from GitHub.",
-  "type": "module",
-  "main": "plugin.js",
-  "exports": {
-    ".": "./plugin.js"
+  "version": "1.0.2",
+  "description": "Global coding rules for TypeScript & NestJS + AI agent skills.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thaiannguyen-05/rules-for-global-agents.git"
+  },
+  "bugs": {
+    "url": "https://github.com/thaiannguyen-05/rules-for-global-agents/issues"
+  },
+  "homepage": "https://github.com/thaiannguyen-05/rules-for-global-agents#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": [
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "validate": "bash scripts/validate.sh",
+    "check-version": "bash scripts/check-version.sh",
+    "release": "bash scripts/release.sh",
+    "pack": "npm pack --dry-run"
   },
   "keywords": [
-    "opencode",
-    "opencode-plugin",
     "rules",
     "nestjs",
-    "typescript"
+    "typescript",
+    "skills"
   ],
   "author": "thaiannguyen-05",
   "license": "MIT",
-  "peerDependencies": {
-    "@opencode-ai/plugin": ">=1.15.0"
-  },
-  "devDependencies": {
-    "@opencode-ai/plugin": "1.17.11"
+  "engines": {
+    "node": ">=18"
   }
 }

package/skills/backend/nestJS/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: nestjs
+description: NestJS backend rules — Fastify platform, module structure, zod validation. Use when building or reviewing NestJS code.
+---
+# NestJS Architecture
+
+## Purpose
+Structure NestJS applications with module-based architecture — domain modules, shared modules, dynamic modules, monorepo projects, and provider scoping.
+
+## Agent Protocol
+
+### Trigger
+User request includes: `NestJS module structure`, `NestJS architecture`, `NestJS project layout`, `NestJS DI`, `NestJS modules`, `NestJS monorepo`, `NestJS providers`.
+
+### Input Context
+- NestJS version (10+)
+- Architecture style (modular, monorepo, microservices)
+- Database (TypeORM, Prisma, MikroORM, Mongoose)
+- Transport (HTTP, WebSocket, TCP, RabbitMQ)
+
+### Output Artifact
+Module structure, provider registration, module exports, monorepo layout, DI setup.
+
+### Response Format
+Produce artifact directly. No preamble, no postamble, no explanations.
+
+### Completion Criteria
+- Root module imports feature modules
+- Each domain has its own module with controllers, services, repositories
+- Modules export only what other modules need
+- Global modules registered sparingly (shared infra only)
+- Dynamic modules configured with forRoot/forFeature
+
+### Max Response Length
+4096 tokens
+
+# NestJS Skill
+
+## Platform
+
+- Use Fastify — never Express.
+- Bootstrap with `FastifyAdapter` typed as `NestFastifyApplication` — never `NestFactory.create()` with the default Express platform.
+- Pass `{ trustProxy: true }` so client IPs stay correct behind a reverse proxy.
+- Never use Express-specific APIs (`@Res()` passthrough, `express-*` middleware) — use Fastify equivalents and `app.register()` plugins.
+- Configure CORS, body-parser limits, and global prefix on the Fastify instance in `main.ts`.
+
+```typescript
+// main.ts
+import { NestFactory } from '@nestjs/core';
+import {
+  FastifyAdapter,
+  NestFastifyApplication,
+} from '@nestjs/platform-fastify';
+
+const app = await NestFactory.create<NestFastifyApplication>(
+  AppModule,
+  new FastifyAdapter({ trustProxy: true }),
+);
+```
+
+## common/guards
+
+- Put only shared guards in `src/common/guards/` — auth, ownership checks reused across features.
+- Feature-specific guards belong in `module/{features}/guards/` — never in `common`.
+- Guards decide access only — no business logic, no DB writes inside guards.
+- Extract request props into explicitly typed locals (e.g., `const user: User | undefined = req.user`) — never branch on `req.*` inline; untyped access is unsafe.
+- Apply via `@UseGuards()` — never call guards manually in controllers or services.
+
+```typescript
+// common/guards/auth.guard.ts
+import { CanActivate, ExecutionContext, Injectable, UnauthorizedException } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { FastifyRequest } from 'fastify';
+import { User } from '../type';
+import { IS_PUBLIC_KEY } from '../decorator/public.decorator';
+
+@Injectable()
+export class AuthGuard implements CanActivate {
+  constructor(private readonly reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+    if (isPublic) return true;
+    const req = context.switchToHttp().getRequest<FastifyRequest>();
+    const user: User | undefined = req.user;
+    if (!user) throw new UnauthorizedException();
+    return true;
+  }
+}
+
+// usage: @UseGuards(AuthGuard)
+```
+
+## common/interceptor
+
+- Put only shared interceptors in `src/common/interceptor/` — logging, transformation, timeout.
+- Never put business logic inside interceptors.
+- Keep interceptors thin — one responsibility per interceptor.
+
+```typescript
+// common/interceptor/logging.interceptor.ts
+import { CallHandler, ExecutionContext, Injectable, Logger, NestInterceptor } from '@nestjs/common';
+import { FastifyRequest } from 'fastify';
+import { Observable, tap } from 'rxjs';
+
+@Injectable()
+export class LoggingInterceptor implements NestInterceptor {
+  private readonly logger = new Logger('HTTP');
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    const req = context.switchToHttp().getRequest<FastifyRequest>();
+    const start = Date.now();
+    return next.handle().pipe(
+      tap(() => this.logger.log(`${req.method} ${req.url} ${Date.now() - start}ms`)),
+    );
+  }
+}
+```
+
+## common/decorator
+
+- Put only shared decorators in `src/common/decorator/` — param decorators, metadata helpers.
+- Mark public routes with `@Public()` — AuthGuard skips them via Reflector; never bypass the guard manually.
+- Never put validation logic inside decorators that belongs in `dto/`.
+- Never put business logic inside decorators.
+
+```typescript
+// common/decorator/current-user.decorator.ts
+import { createParamDecorator, ExecutionContext } from '@nestjs/common';
+import { FastifyRequest } from 'fastify';
+import { User } from '../type';
+
+export const CurrentUser = createParamDecorator(
+  (key: keyof User | undefined, ctx: ExecutionContext) => {
+    const req = ctx.switchToHttp().getRequest<FastifyRequest>();
+    const user: User | undefined = req.user;
+    return key ? user?.[key] : user;
+  },
+);
+
+// usage: handler(@CurrentUser() user) or handler(@CurrentUser('id') id: string)
+```
+
+```typescript
+// common/decorator/public.decorator.ts
+import { SetMetadata } from '@nestjs/common';
+
+export const IS_PUBLIC_KEY = 'isPublic';
+export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);
+
+// usage: @Public() on a controller or route handler to skip AuthGuard
+```
+
+## common/exception
+
+- All exceptions and filters live in `src/common/exception/` — replaces the old `src/error/` location.
+- Define custom `AppException` classes here — never throw raw `Error` for domain failures.
+- `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 — never leak internal details to responses.
+- Feature helpers (e.g., `[domain]-error.helper.ts`) live here, not inside features.
+
+```typescript
+// common/exception/app.exception.ts
+import { HttpException, HttpStatus } from '@nestjs/common';
+
+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
+// common/exception/global-exception.filter.ts
+import { ArgumentsHost, Catch, ExceptionFilter, HttpException, Logger } from '@nestjs/common';
+import { FastifyReply } from 'fastify';
+
+@Catch()
+export class GlobalExceptionFilter implements ExceptionFilter {
+  private readonly logger = new Logger('Exception');
+
+  catch(exception: unknown, host: ArgumentsHost) {
+    const reply = host.switchToHttp().getResponse<FastifyReply>();
+    if (exception instanceof HttpException) {
+      return reply.status(exception.getStatus()).send(exception.getResponse());
+    }
+    this.logger.error(exception);
+    return reply.status(500).send({
+      statusCode: 500,
+      message: 'Internal server error',
+      timestamp: new Date().toISOString(),
+    });
+  }
+}
+
+// main.ts: app.useGlobalFilters(new GlobalExceptionFilter());
+```
+
+## common/middleware
+
+- Put only HTTP plumbing in `src/common/middleware/` — req/res preprocessing, correlation IDs.
+- Write them as Fastify plugins/hooks registered via `app.register()` — never Express-style `(req, res, next)` middleware.
+- Never put business logic inside middleware.
+- Prefer guards/interceptors over middleware when the concern fits them.
+
+```typescript
+// common/middleware/correlation-id.plugin.ts
+import { FastifyInstance } from 'fastify';
+import { randomUUID } from 'node:crypto';
+
+export async function correlationIdPlugin(app: FastifyInstance) {
+  app.addHook('onRequest', async (req) => {
+    req.headers['x-correlation-id'] ??= randomUUID();
+  });
+}
+
+// main.ts: await app.register(correlationIdPlugin);
+```
+
+## module/infrastructures (abstract)
+
+- `module/infrastructures/` holds tech adapters only — no business logic, no domain types.
+- Subfolders below are examples, not mandates — never hardcode the tech choice:
+  - `TypeOrm/` = example relational persistence adapter (entities, repositories, migrations glue).
+  - `message/` = example messaging adapter (producers, consumers, topic/queue names).
+- Name a subfolder after the adapter role — one folder per external system.
+- Adapters implement interfaces owned by features — features depend on abstractions, not on adapter internals.
+- Never import `module/{features}/` code into `infrastructures/` — dependency points inward to the abstraction.
+- Never let controllers or services import adapter internals directly — go through DI providers/tokens.
+- Never share state between adapters — no cross-imports between `TypeOrm/` and `message/`.
+- Write adapter code only after the tech is chosen — no placeholder implementations before the decision.
+
+## References
+
+- Feature slice layout, types, guards, dto, service, controller rules: `references/nestjs-module.md`.
+- Unit, integration, E2E testing strategies, TestContainers, mocking: `references/nestjs-testing.md`.

package/skills/backend/nestJS/references/nestjs-module.md

@@ -0,0 +1,212 @@
+# NestJS Module Structure Rules
+
+## Layout
+
+- Follow this tree exactly — no extra nesting, no renamed folders.
+- `src/common/` holds shared code only — never feature-specific code.
+- `src/module/` holds `infrastructures/` + one folder per feature.
+
+```
+src/
+├── common/
+│   ├── guards/
+│   ├── interceptor/
+│   ├── decorator/
+│   ├── exception/
+│   ├── middleware/
+│   └── type.ts
+└── module/
+    ├── infrastructures/
+    │   ├── TypeOrm/
+    │   └── message/
+    └── {features}/
+        ├── dto/
+        ├── guards/
+        ├── type.ts
+        ├── index.ts
+        ├── {features}.service.ts
+        ├── {features}.controller.ts
+        └── {features}.module.ts
+```
+
+## common/type.ts (shared)
+
+- Put only cross-feature types in `src/common/type.ts` — enums, interfaces, aliases used by 2+ features.
+- Never put feature-private types in `src/common/type.ts` — they belong in `module/{features}/type.ts`.
+- Never import from `module/{features}/type.ts` into `src/common/type.ts` — `common` never depends on `module/`.
+- Use `enum` for shared constants — no hardcoded strings in business logic.
+
+## Global setup (lives in `../SKILL.md`)
+
+- `common/interceptor`, `common/decorator`, `common/exception`, `common/middleware`, and `module/infrastructures/` rules are global — see `../SKILL.md`, not here.
+
+## module/{features}
+
+- One folder per feature (e.g., `users/`, `auth/`, `orders/`) — self-contained slice.
+- Never place feature code outside its folder — except shared code in `src/common/` and adapters in `infrastructures/`.
+- Never import deep paths across features (e.g., `../orders/type`) — import via the feature barrel (see `index.ts` below).
+
+### dto/
+
+- DTOs are zod schemas only — define `z.object(...)` in `dto/`, export the schema + `z.infer` type, no business logic.
+- Do NOT use `class-validator` decorators or `class-transformer` — zod replaces both (parsing + coercion via `z.coerce`).
+- Do NOT put shared types or constants in `dto/` — shared types belong in `type.ts`, constants in `enum`; derive DTO types via `z.infer`.
+- Validate nested objects with nested schemas — call `.strict()` to reject unknown fields.
+
+```typescript
+// module/users/dto/create-user.dto.ts
+import { z } from 'zod';
+
+export const CreateUserSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+  address: AddressSchema,
+}).strict();
+
+export type CreateUserDto = z.infer<typeof CreateUserSchema>;
+```
+
+### guards/
+
+- Put feature-specific guards here — guards used by one feature only.
+- Promote to `src/common/guards/` the moment a second feature needs it.
+- Same guard rules as global (`../SKILL.md`): access decisions only, applied via `@UseGuards()`.
+
+### type.ts + index.ts (private + barrel)
+
+- `module/{features}/type.ts` holds feature-private types — enums, interfaces, return types for this feature only.
+- Every feature must re-export its private types from its own `index.ts` barrel.
+- External features import via the barrel — never via a deep `type.ts` path.
+- Internal files import from `./type` — avoid self-importing through `./index` to prevent cycles.
+
+```typescript
+// module/users/type.ts
+export enum UserRole { ADMIN = 'admin', USER = 'user' }
+export interface User { id: string; name: string; }
+```
+
+```typescript
+// module/users/index.ts
+export * from './type';
+export * from './users.service';
+export * from './users.module';
+```
+
+### {features}.service.ts
+
+- Services hold business logic only — no HTTP, no req/res, no raw adapter imports.
+- Inject dependencies via constructor — never instantiate manually.
+- Run independent async work in parallel — never `await` sequentially when parallel is possible.
+- Use transactions for multi-step writes — no partial writes, keep scope small, no external calls inside.
+
+```typescript
+// module/users/users.service.ts
+import { Injectable } from '@nestjs/common';
+import type { CreateUserDto } from './dto/create-user.dto';
+import type { User } from './type';
+
+@Injectable()
+export class UsersService {
+  async create(dto: CreateUserDto): Promise<User> {
+    /* business logic only — persistence arrives via DI after the tech decision */
+    void dto;
+    throw new Error('not implemented');
+  }
+
+  async getById(id: string): Promise<User> {
+    /* ... */
+    void id;
+    throw new Error('not implemented');
+  }
+}
+```
+
+### {features}.controller.ts
+
+- Controllers handle HTTP only — routing, status codes, delegation to the service.
+- No business logic, no DB access, no adapter imports in controllers.
+- Controllers and services receive only valid data — all validation happens in `dto/` schemas + global `ZodValidationPipe` before them.
+
+```typescript
+// module/users/users.controller.ts
+import { Body, Controller, Get, Param, Post } from '@nestjs/common';
+import type { CreateUserDto } from './dto/create-user.dto';
+import { UsersService } from './users.service';
+
+@Controller('users')
+export class UsersController {
+  constructor(private readonly users: UsersService) {}
+
+  @Post()
+  create(@Body() dto: CreateUserDto) {
+    return this.users.create(dto);
+  }
+
+  @Get(':id')
+  getById(@Param('id') id: string) {
+    return this.users.getById(id);
+  }
+}
+```
+
+### {features}.module.ts
+
+- Modules wire only — `imports`, `providers`, `controllers`, `exports`, no logic.
+- Register feature providers here; export what other features need via the barrel.
+- Import direction is one-way — the sample below depends on users, never the reverse.
+
+```typescript
+// module/users/users.module.ts
+import { Module } from '@nestjs/common';
+import { UsersController } from './users.controller';
+import { UsersService } from './users.service';
+
+@Module({
+  controllers: [UsersController],
+  providers: [UsersService],
+  exports: [UsersService],
+})
+export class UsersModule {}
+```
+
+```typescript
+// module/orders/orders.module.ts — depends on users, never the reverse
+import { Module } from '@nestjs/common';
+import { UsersModule } from '../users';
+import { OrdersController } from './orders.controller';
+import { OrdersService } from './orders.service';
+
+@Module({
+  imports: [UsersModule],
+  controllers: [OrdersController],
+  providers: [OrdersService],
+})
+export class OrdersModule {}
+```
+
+### Cross-module imports (no circular DI)
+
+- Keep the import graph one-way — if A imports B, B never imports A.
+- Code needed by both sides moves to a third module (or `src/common/`) that both import.
+- Import the dependency's barrel (`../users`), never reach into its internals.
+- `forwardRef` only as last resort — wrap both module imports and both injections, and comment why the cycle cannot be broken.
+
+```typescript
+// module/orders/orders.service.ts — consumes the exported provider, no cycle
+import { Injectable } from '@nestjs/common';
+import { UsersService } from '../users';
+
+@Injectable()
+export class OrdersService {
+  constructor(private readonly users: UsersService) {}
+
+  async create(userId: string) {
+    const user = await this.users.getById(userId);
+    /* ... */
+  }
+}
+
+// last resort only — avoid if possible:
+// @Module({ imports: [forwardRef(() => BModule)] }) on BOTH modules, and
+// constructor(@Inject(forwardRef(() => BService)) ...) on BOTH sides, with a comment why.
+```