@deepstorm/cli 0.9.3 → 0.10.1

package/dist/registry.json

@@ -104,7 +104,7 @@
                     "buildTool": "pnpm:*",
                     "formatCmd": "pnpm",
                     "fileExt": "*.component.ts / *.service.ts / *.ts",
-                    "sourcePath": "src/main/web/",
+                    "sourcePath": "client/src/",
                     "styleRef": "→ 参考 [Angular 前端速查](quick-reference.md)"
                   },
                   "affectedTemplates": [
@@ -355,6 +355,9 @@
                 "sourcePath": "src/main/java/ src/test/java/",
                 "styleRef": "→ 参考 [Java 后端速查](quick-reference.md)"
               },
+              "availableAiFrameworks": [
+                "spring-ai"
+              ],
               "affectedTemplates": [
                 "skills/reef-style-backend/SKILL.md.tmpl",
                 "agents/reef-review-backend.md.tmpl",
@@ -380,6 +383,7 @@
                 "styleRef": "→ 参考 [Python FastAPI 后瑞速查](quick-reference.md)",
                 "isPython": "true"
               },
+              "availableAiFrameworks": [],
               "affectedTemplates": [
                 "skills/reef-style-backend/SKILL.md.tmpl",
                 "agents/reef-review-backend.md.tmpl",
@@ -393,6 +397,33 @@
                 "python/security-redlines"
               ]
             },
+            {
+              "value": "nodejs",
+              "label": "Node.js / NestJS",
+              "template": {
+                "label": "NestJS + TypeScript + Prisma",
+                "buildTool": "pnpm:*",
+                "formatCmd": "npx eslint",
+                "fileExt": "*.ts",
+                "sourcePath": "server/src/ server/test/",
+                "styleRef": "→ 参考 [Node.js NestJS 后端速查](quick-reference.md)"
+              },
+              "availableAiFrameworks": [
+                "claude-agent-sdk"
+              ],
+              "affectedTemplates": [
+                "skills/reef-style-backend/SKILL.md.tmpl",
+                "agents/reef-review-backend.md.tmpl",
+                "skills/reef-review/SKILL.md.tmpl",
+                "skills/reef-gen-backend/SKILL.md.tmpl"
+              ],
+              "fragments": [
+                "nodejs/api-spec",
+                "nodejs/dependency-management",
+                "nodejs/exception-handling",
+                "nodejs/security-redlines"
+              ]
+            },
             {
               "value": "none",
               "label": "不使用后端",
@@ -790,6 +821,143 @@
             }
           ]
         },
+        {
+          "key": "reef.backend.nodejs.details",
+          "label": "Node.js 框架选型",
+          "description": "选择需要使用的 Node.js 框架和技术",
+          "type": "group",
+          "dependsOn": {
+            "key": "reef.backend.language",
+            "value": "nodejs"
+          },
+          "questions": [
+            {
+              "key": "reef.backend.nodejs.framework",
+              "label": "Web 框架",
+              "type": "select",
+              "options": [
+                {
+                  "value": "nestjs",
+                  "label": "NestJS",
+                  "template": {
+                    "styleRef": "→ 参考 [NestJS 后端速查](quick-reference.md)"
+                  },
+                  "affectedTemplates": [
+                    "skills/reef-style-backend/SKILL.md.tmpl"
+                  ],
+                  "fragments": [
+                    "nodejs/framework/nestjs"
+                  ]
+                },
+                {
+                  "value": "none",
+                  "label": "不使用",
+                  "template": {},
+                  "affectedTemplates": [
+                    "skills/reef-style-backend/SKILL.md.tmpl"
+                  ]
+                }
+              ]
+            },
+            {
+              "key": "reef.backend.nodejs.orm",
+              "label": "ORM",
+              "type": "select",
+              "options": [
+                {
+                  "value": "prisma",
+                  "label": "Prisma",
+                  "template": {
+                    "styleRef": "→ 参考 [Prisma 规范](prisma.md)"
+                  },
+                  "affectedTemplates": [
+                    "skills/reef-style-backend/SKILL.md.tmpl"
+                  ],
+                  "fragments": [
+                    "nodejs/orm/prisma"
+                  ]
+                },
+                {
+                  "value": "none",
+                  "label": "不使用",
+                  "template": {},
+                  "affectedTemplates": [
+                    "skills/reef-style-backend/SKILL.md.tmpl"
+                  ]
+                }
+              ]
+            },
+            {
+              "key": "reef.backend.nodejs.ai",
+              "label": "AI 集成",
+              "type": "select",
+              "options": [
+                {
+                  "value": "claude-agent-sdk",
+                  "label": "Claude Agent SDK",
+                  "template": {
+                    "styleRef": "→ 参考 [Claude Agent SDK 规范](claude-agent-sdk.md)"
+                  },
+                  "affectedTemplates": [
+                    "skills/reef-style-backend/SKILL.md.tmpl"
+                  ],
+                  "fragments": [
+                    "nodejs/ai/claude-agent-sdk"
+                  ]
+                },
+                {
+                  "value": "none",
+                  "label": "不使用",
+                  "template": {},
+                  "affectedTemplates": [
+                    "skills/reef-style-backend/SKILL.md.tmpl"
+                  ]
+                }
+              ]
+            },
+            {
+              "key": "reef.backend.nodejs.test",
+              "label": "单元测试",
+              "type": "select",
+              "options": [
+                {
+                  "value": "jest",
+                  "label": "Jest",
+                  "template": {
+                    "styleRef": "→ 参考 [Jest 规范](jest-testing.md)"
+                  },
+                  "affectedTemplates": [
+                    "skills/reef-style-backend/SKILL.md.tmpl"
+                  ],
+                  "fragments": [
+                    "nodejs/test/jest"
+                  ]
+                },
+                {
+                  "value": "vitest",
+                  "label": "Vitest",
+                  "template": {
+                    "styleRef": "→ 参考 [Vitest 规范](vitest-testing.md)"
+                  },
+                  "affectedTemplates": [
+                    "skills/reef-style-backend/SKILL.md.tmpl"
+                  ],
+                  "fragments": [
+                    "nodejs/test/vitest"
+                  ]
+                },
+                {
+                  "value": "none",
+                  "label": "不使用",
+                  "template": {},
+                  "affectedTemplates": [
+                    "skills/reef-style-backend/SKILL.md.tmpl"
+                  ]
+                }
+              ]
+            }
+          ]
+        },
         {
           "key": "reef.formatter",
           "label": "格式化增强配置",

package/dist/skills/reef-gen-backend/variants/nodejs/steps.md

@@ -0,0 +1,53 @@
+# Node.js / NestJS 后端编码步骤
+
+按以下顺序逐块编写，依赖关系由前向后：
+
+1. **Prisma Schema** — 定义数据模型（`prisma/schema.prisma`），**先于所有代码**，因为它决定类型结构
+2. **DTO** — 数据传输对象（请求/响应），使用 `class-validator` + `@nestjs/swagger` 装饰器
+3. **Entity** — Prisma 生成的 TypeScript 类型，必要时封装为 Entity 类（可选）
+4. **PrismaService** — 数据库访问服务（`PrismaModule` + `PrismaService`），如果尚未创建
+5. **Service** — 业务逻辑层，依赖 `PrismaService`，事务处理
+6. **Controller** — REST API，请求/响应，参数校验
+7. **Module** — NestJS 模块，将 Controller/Service 注册到 DI 容器
+
+每完成一块对照 `reef:reef-style-backend` 中对应章节检查。
+
+## 注释要求
+
+每类文件必须包含以下注释（缺少则视为未完成）：
+
+| 文件类型 | 注释要求 |
+|---------|---------|
+| **Prisma Schema** | 每个 model 加 `/// 注释` 描述实体用途；每个字段加 `/// 注释` |
+| **DTO** | 类 JSDoc `/** 用途说明 */`；字段通过 `@ApiProperty({ description: '...' })` 提供文档 |
+| **Service** | 每个 public 方法加 JSDoc `/** 功能、@param、@returns */`；复杂逻辑内联注释说明 |
+| **Controller** | 每个端点加 `@ApiOperation({ summary: '...', description: '...' })` |
+| **Module** | 类 JSDoc `/** 模块职责 */` |
+
+## 安全红线
+
+- 所有环境变量通过 `ConfigService` 读取，禁止 `process.env` 直读
+- 敏感字段（密码、Token）在 API 响应前使用 `select` 或 `@Exclude()` 排除
+- 禁止在 TypeScript 代码中硬编码 API Key / Token
+- Prisma 条件查询使用参数化查询（Prisma 默认安全），禁止手动拼接 `where` 条件
+- API 端点需添加 `@ApiBearerAuth()` 和 `@UseGuards(AuthGuard())`
+
+## 构建命令
+
+```bash
+# 依赖安装（在项目根目录执行）
+pnpm install
+
+# Prisma 客户端生成（在 server/ 目录执行）
+cd server && npx prisma generate
+
+# 代码检查
+cd server && npx eslint src/ --ext .ts
+cd server && npx prettier --check src/
+
+# 测试
+cd server && npx jest
+
+# 构建
+cd server && npx nest build
+```

package/dist/skills/reef-style-backend/fragments/nodejs/eslint-config.json

@@ -0,0 +1,30 @@
+{
+  "root": true,
+  "env": {
+    "node": true,
+    "jest": true
+  },
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "project": "tsconfig.json",
+    "sourceType": "module"
+  },
+  "plugins": ["@typescript-eslint/eslint-plugin"],
+  "extends": [
+    "plugin:@typescript-eslint/recommended",
+    "plugin:prettier/recommended"
+  ],
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "error",
+    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
+    "@typescript-eslint/explicit-function-return-type": "off",
+    "@typescript-eslint/explicit-module-boundary-types": "off",
+    "no-console": "warn",
+    "prefer-const": "error",
+    "no-var": "error",
+    "eqeqeq": ["error", "always"],
+    "curly": ["error", "all"],
+    "no-throw-literal": "error",
+    "prefer-promise-reject-errors": "error"
+  }
+}

package/dist/skills/reef-style-backend/fragments/nodejs/nestjs-structure.md

@@ -0,0 +1,58 @@
+# NestJS 项目结构规范
+
+## 顶层目录
+
+```
+src/
+├── main.ts               # 入口（Bootstrap）
+├── app.module.ts         # 根模块
+├── app.controller.ts     # 健康检查
+└── app.service.ts        # 全局服务
+```
+
+## 模块目录规范
+
+```
+src/modules/{module-name}/
+├── {module-name}.module.ts         # Module 定义
+├── {module-name}.controller.ts     # REST Controller
+├── {module-name}.service.ts        # 业务逻辑
+├── dto/
+│   ├── create-{entity}.dto.ts      # 创建 DTO
+│   └── update-{entity}.dto.ts      # 更新 DTO（PartialType）
+└── entities/
+    └── {entity}.entity.ts          # Prisma 封装类型（可选）
+```
+
+## 公共目录
+
+```
+src/
+├── prisma/
+│   ├── prisma.module.ts
+│   └── prisma.service.ts
+├── common/
+│   ├── filters/
+│   │   └── http-exception.filter.ts
+│   ├── pipes/
+│   │   └── validation.pipe.ts
+│   ├── interceptors/
+│   │   ├── transform.interceptor.ts
+│   │   └── logging.interceptor.ts
+│   └── guards/
+│       └── auth.guard.ts
+└── config/
+    └── configuration.ts
+```
+
+## 命名规范
+
+| 类型 | 命名规则 | 示例 |
+|------|---------|------|
+| Module 类 | PascalCase + Module | `UsersModule` |
+| Controller 类 | PascalCase + Controller | `UsersController` |
+| Service 类 | PascalCase + Service | `UsersService` |
+| DTO 类 | PascalCase + Dto | `CreateUserDto` |
+| Module 目录 | kebab-case | `src/modules/user-roles/` |
+| DTO 文件 | kebab-case | `create-user-role.dto.ts` |
+| 配置键 | UPPER_SNAKE_CASE | `DATABASE_URL` |

package/dist/skills/reef-style-backend/fragments/nodejs/prettier-config.json

@@ -0,0 +1,19 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "quoteProps": "as-needed",
+  "overrides": [
+    {
+      "files": "*.prisma",
+      "options": {
+        "tabWidth": 2
+      }
+    }
+  ]
+}

package/dist/skills/reef-style-backend/variants/nodejs/examples/module-example.md

@@ -0,0 +1,166 @@
+# NestJS Module 示例 — Users 模块
+
+```typescript
+// users.module.ts
+import { Module } from '@nestjs/common';
+import { UsersController } from './users.controller';
+import { UsersService } from './users.service';
+import { PrismaModule } from '../prisma/prisma.module';
+
+/**
+ * 用户管理模块
+ * 提供用户 CRUD 操作和权限管理
+ */
+@Module({
+  imports: [PrismaModule],
+  controllers: [UsersController],
+  providers: [UsersService],
+  exports: [UsersService],
+})
+export class UsersModule {}
+```
+
+```typescript
+// users.controller.ts
+import {
+  Controller, Get, Post, Body, Param, Put, Delete,
+  ParseIntPipe,
+} from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiBearerAuth } from '@nestjs/swagger';
+import { UsersService } from './users.service';
+import { CreateUserDto } from './dto/create-user.dto';
+import { UpdateUserDto } from './dto/update-user.dto';
+
+@ApiTags('Users')
+@Controller('users')
+@ApiBearerAuth()
+export class UsersController {
+  constructor(private readonly usersService: UsersService) {}
+
+  @Post()
+  @ApiOperation({ summary: '创建用户', description: '创建一个新的系统用户' })
+  create(@Body() createUserDto: CreateUserDto) {
+    return this.usersService.create(createUserDto);
+  }
+
+  @Get()
+  @ApiOperation({ summary: '查询用户列表' })
+  findAll() {
+    return this.usersService.findAll();
+  }
+
+  @Get(':id')
+  @ApiOperation({ summary: '查询单个用户' })
+  findOne(@Param('id', ParseIntPipe) id: number) {
+    return this.usersService.findOne(id);
+  }
+
+  @Put(':id')
+  @ApiOperation({ summary: '更新用户信息' })
+  update(
+    @Param('id', ParseIntPipe) id: number,
+    @Body() updateUserDto: UpdateUserDto,
+  ) {
+    return this.usersService.update(id, updateUserDto);
+  }
+
+  @Delete(':id')
+  @ApiOperation({ summary: '删除用户' })
+  remove(@Param('id', ParseIntPipe) id: number) {
+    return this.usersService.remove(id);
+  }
+}
+```
+
+```typescript
+// users.service.ts
+import { Injectable, Logger, NotFoundException } from '@nestjs/common';
+import { PrismaService } from '../prisma/prisma.service';
+import { CreateUserDto } from './dto/create-user.dto';
+import { UpdateUserDto } from './dto/update-user.dto';
+
+@Injectable()
+export class UsersService {
+  private readonly logger = new Logger(UsersService.name);
+
+  constructor(private readonly prisma: PrismaService) {}
+
+  /**
+   * 创建用户
+   * @param createUserDto 用户创建参数
+   * @returns 创建的用户记录
+   */
+  async create(createUserDto: CreateUserDto) {
+    return this.prisma.user.create({ data: createUserDto });
+  }
+
+  /** 查询所有用户 */
+  async findAll() {
+    return this.prisma.user.findMany();
+  }
+
+  /**
+   * 根据 ID 查询用户
+   * @param id 用户 ID
+   * @throws NotFoundException 用户不存在
+   */
+  async findOne(id: number) {
+    const user = await this.prisma.user.findUnique({ where: { id } });
+    if (!user) throw new NotFoundException(`User #${id} not found`);
+    return user;
+  }
+
+  /**
+   * 更新用户信息
+   * @param id 用户 ID
+   * @param updateUserDto 更新参数
+   */
+  async update(id: number, updateUserDto: UpdateUserDto) {
+    await this.findOne(id);
+    return this.prisma.user.update({
+      where: { id },
+      data: updateUserDto,
+    });
+  }
+
+  /**
+   * 删除用户
+   * @param id 用户 ID
+   */
+  async remove(id: number) {
+    await this.findOne(id);
+    return this.prisma.user.delete({ where: { id } });
+  }
+}
+```
+
+```typescript
+// dto/create-user.dto.ts
+import { ApiProperty } from '@nestjs/swagger';
+import { IsString, IsEmail, IsOptional, IsBoolean } from 'class-validator';
+
+/** 创建用户请求 DTO */
+export class CreateUserDto {
+  @ApiProperty({ description: '用户名', example: 'john_doe' })
+  @IsString()
+  name!: string;
+
+  @ApiProperty({ description: '邮箱地址', example: 'john@example.com' })
+  @IsEmail()
+  email!: string;
+
+  @ApiProperty({ description: '是否激活', required: false, default: true })
+  @IsOptional()
+  @IsBoolean()
+  active?: boolean;
+}
+```
+
+```typescript
+// dto/update-user.dto.ts
+import { PartialType } from '@nestjs/swagger';
+import { CreateUserDto } from './create-user.dto';
+
+/** 更新用户请求 DTO — 所有字段可选 */
+export class UpdateUserDto extends PartialType(CreateUserDto) {}
+```

package/dist/skills/reef-style-backend/variants/nodejs/examples/prisma-example.md

@@ -0,0 +1,115 @@
+# Prisma Service 与 Schema 示例
+
+## Prisma Schema
+
+```prisma
+// prisma/schema.prisma
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+/// 系统用户
+model User {
+  id        Int      @id @default(autoincrement())
+  name      String
+  email     String   @unique
+  active    Boolean  @default(true)
+  posts     Post[]
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@map("users")
+}
+
+/// 文章
+model Post {
+  id        Int      @id @default(autoincrement())
+  title     String
+  content   String
+  published Boolean  @default(false)
+  author    User     @relation(fields: [authorId], references: [id], onDelete: Cascade)
+  authorId  Int
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@map("posts")
+}
+```
+
+## Prisma Module & Service
+
+```typescript
+// prisma/prisma.module.ts
+import { Global, Module } from '@nestjs/common';
+import { PrismaService } from './prisma.service';
+
+/**
+ * Prisma 全局模块
+ * 作为 Global 模块，所有其他模块无需 imports 即可注入 PrismaService
+ */
+@Global()
+@Module({
+  providers: [PrismaService],
+  exports: [PrismaService],
+})
+export class PrismaModule {}
+```
+
+```typescript
+// prisma/prisma.service.ts
+import { Injectable, Logger, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
+import { PrismaClient } from '@prisma/client';
+
+/**
+ * Prisma 数据库服务
+ * 封装 PrismaClient，提供数据库连接生命周期管理
+ */
+@Injectable()
+export class PrismaService extends PrismaClient implements OnModuleInit, OnModuleDestroy {
+  private readonly logger = new Logger(PrismaService.name);
+
+  async onModuleInit() {
+    await this.$connect();
+    this.logger.log('Database connected');
+  }
+
+  async onModuleDestroy() {
+    await this.$disconnect();
+    this.logger.log('Database disconnected');
+  }
+}
+```
+
+## Prisma 查询最佳实践
+
+```typescript
+// 使用事务：多个原子操作
+const [user, post] = await this.prisma.$transaction([
+  this.prisma.user.create({ data: { name: 'Alice', email: 'alice@test.com' } }),
+  this.prisma.post.create({ data: { title: 'Hello', content: 'World', authorId: 1 } }),
+]);
+
+// 使用 select 限制返回字段，避免 N+1
+const users = await this.prisma.user.findMany({
+  select: {
+    id: true,
+    name: true,
+    email: true,
+    posts: {
+      select: { title: true, published: true },
+      where: { published: true },
+    },
+  },
+});
+
+// 使用 findFirstOrThrow 简化判空
+const user = await this.prisma.user.findFirstOrThrow({
+  where: { email: 'alice@test.com' },
+});
+```