@stonepandastudio/cairn 0.4.1 → 0.5.0

package/presets/drizzle/slots/architect-mandatory-docs.md

@@ -0,0 +1,4 @@
+<!-- cairn preset: drizzle — appended to the framework preset's
+     architect-mandatory-docs slot on `--stack <framework>,drizzle`. -->
+- `ai/infrastructure/DATABASE_SCHEMA.md`
+- `lib/db/schema.ts` — the current Drizzle schema

package/presets/drizzle/slots/implementation-reference.md

@@ -0,0 +1,17 @@
+<!-- cairn preset: drizzle — appended to the framework preset's
+     implementation-reference slot on `--stack <framework>,drizzle`. -->
+
+### Schema
+- All tables in `lib/db/schema.ts`, Drizzle syntax; snake_case columns, camelCase fields
+- Relations declared with `relations(...)` so typed joins work
+- No RLS in the schema module — that goes in the migration
+
+### Migrations
+- `pnpm exec drizzle-kit generate` for mechanical diffs
+- Hand-write the `.sql` only for RLS policies, functions, triggers, backfills
+- One commit = schema edit + its migration
+
+### Access
+- Server: the Drizzle client in `lib/db/client.ts` (service-role, never in `"use client"`)
+- Browser: the Supabase client only, bounded by RLS
+- Reads select named columns; multi-step writes go in `db.transaction(...)`

package/presets/drizzle/slots/key-patterns.md

@@ -0,0 +1,7 @@
+<!-- cairn preset: drizzle — appended to the framework preset's key-patterns slot
+     on `--stack <framework>,drizzle`. -->
+
+Database schema: **`lib/db/schema.ts`** (single Drizzle module) and
+**`ai/infrastructure/DATABASE_SCHEMA.md`** — keep both current with every migration.
+
+Migration and RLS conventions: **`ai/infrastructure/code-guidelines.md`** § Drizzle.

package/presets/drizzle/slots/review-checklist.md

@@ -0,0 +1,10 @@
+<!-- cairn preset: drizzle — appended to the framework preset's review-checklist
+     slot on `--stack <framework>,drizzle`. -->
+
+| No raw SQL in application code — only the Drizzle query builder, or `sql` for expressions it can't model | any `.ts` outside `supabase/migrations/` |
+| Schema change committed together with its `drizzle-kit` migration | `lib/db/schema.ts` + `supabase/migrations/` |
+| Generated migration reviewed — no accidental drop or type change | the migration `.sql` |
+| RLS policy declared in a migration, not assumed | `supabase/migrations/` |
+| Server Drizzle client not imported from a `"use client"` module | client components |
+| Multi-step write wrapped in `db.transaction(...)` | service / action files |
+| `ai/infrastructure/DATABASE_SCHEMA.md` updated to match | that file |

package/presets/nestjs/code-guidelines.md

@@ -0,0 +1,273 @@
+# Code Guidelines
+
+<!-- cairn preset: nestjs. Composes with presets/typeorm for TypeORM-backed services. -->
+
+## General TypeScript Guidelines
+
+* Use TypeScript strict mode
+* Prefer `const` over `let`, never use `var`
+* Avoid using `any` type - use proper TypeScript types
+* Use async/await instead of raw promises
+* Handle all error cases explicitly
+* Use proper error types from NestJS (`NotFoundException`, `BadRequestException`, etc.)
+
+## NestJS Module Structure
+
+* Separate business logic (feature modules in `src/feature/`) from API layer (API modules in `src/api/modules/`)
+* Use proper dependency injection with `@Injectable()`, `@Module()` decorators
+* Register providers, imports, and exports correctly in module files
+* Keep controllers thin - delegate business logic to services
+
+## File Naming Conventions
+
+* Use kebab-case (dash-case) for all file names
+* Modules: `feature-name.module.ts`
+* Services: `feature-name.service.ts`
+* Controllers: `feature-name.controller.ts`
+* Entities: `feature-name.entity.ts`
+* Interfaces: `interface-name.interface.ts` (stored in `interfaces/` folder)
+* Tests: `feature-name.service.spec.ts`, `feature-name.controller.spec.ts`
+
+DTO file naming follows the validation stack:
+
+{{> slot: dto-naming }}
+
+## File Organization
+
+Every utility function, model, constant, DTO, or mapping function should be in a separated file.
+
+Files should be placed in appropriate folders within modules (see `ai/infrastructure/project-structure.md` for module details):
+
+* **constants/** - Constants specific to the module
+* **enums/** - Enums specific to the module
+* **interfaces/** - TypeScript interfaces (one per file)
+* **dtos/** - Data Transfer Objects for request/response
+* **entities/** - Database entities
+* **services/** - Business logic services
+* **controllers/** - HTTP controllers
+* **mappers/** - Mapping functions for transforming data
+
+## Interfaces
+
+**IMPORTANT**: Store interfaces separately from code in dedicated interface files.
+
+**Rules**:
+* Each interface gets its own file in `src/feature/[feature-name]/interfaces/` folder
+* File naming: convert interface name to kebab-case + `.interface.ts`
+  - E.g., `CreateUserData` → `create-user-data.interface.ts`
+  - E.g., `RegisterOwnerResult` → `register-owner-result.interface.ts`
+* One interface per file — no mixing multiple interfaces
+* Interfaces are NOT exported from barrel files unless necessary
+
+**Examples**:
+```typescript
+// src/feature/user/interfaces/create-user-data.interface.ts
+export interface CreateUserData {
+  companyId: string;
+  email: string;
+  name: string;
+  passwordHash: string;
+  role?: TenantRole;
+}
+
+// src/feature/user/interfaces/register-owner-result.interface.ts
+export interface RegisterOwnerResult {
+  user: User;
+  company: Company;
+}
+```
+
+## Controllers
+
+* Keep controllers thin - only handle HTTP concerns
+* Use proper HTTP method decorators: `@Get()`, `@Post()`, `@Put()`, `@Delete()`, `@Patch()`
+* Use parameter decorators: `@Body()`, `@Param()`, `@Query()`, `@Headers()`
+* Use `@UseGuards()` for authentication and authorization
+* Return consistent response structures
+* Let NestJS exception filters handle errors
+
+Response typing and serialization are stack-specific:
+
+{{> slot: controller-response }}
+
+## Services
+
+* Implement all business logic in services
+* Use dependency injection for all dependencies
+* Mark services with `@Injectable()` decorator
+* Handle database transactions properly
+* Throw appropriate NestJS exceptions
+* Keep methods focused and single-purpose
+* Use async/await for all asynchronous operations
+
+## DTOs (Data Transfer Objects)
+
+* Create separate DTOs for different operations:
+    - `create-*.dto.ts` for POST requests
+    - `update-*.dto.ts` for PUT/PATCH requests
+    - `*-response.dto.ts` for responses
+    - `*-query.dto.ts` for query parameters
+
+{{> slot: dto-definition }}
+
+## Validation
+
+* Validate at API boundaries (in controllers via DTOs)
+* Provide clear, user-friendly validation error messages
+
+{{> slot: validation-stack }}
+
+## Error Handling
+
+* Use NestJS built-in exceptions:
+    - `NotFoundException` - Resource not found (404)
+    - `BadRequestException` - Invalid input (400)
+    - `UnauthorizedException` - Not authenticated (401)
+    - `ForbiddenException` - Not authorized (403)
+    - `ConflictException` - Resource conflict (409)
+* Create custom exception classes for domain-specific errors
+* Use exception filters for global error handling
+* Log errors appropriately (use NestJS Logger)
+* Never expose sensitive information in error messages
+* Never expose stack traces in production
+
+## Error Codes
+
+**MANDATORY**: Every thrown exception **must** include a machine-readable `code` from `ERROR_CODES`.
+
+**Why**: Frontend uses `code` to display localized messages. String-matching on `message` is forbidden.
+
+**Constants file**: `src/common/constants/error-codes.constant.ts` — single source of truth for all codes.
+Add new codes here before using them. Never use inline strings.
+
+**Throw pattern**:
+```typescript
+// Correct
+import { ERROR_CODES } from '@common/constants/error-codes.constant';
+throw new NotFoundException({ message: 'User not found', code: ERROR_CODES.USER_NOT_FOUND });
+
+// Incorrect — missing code
+throw new NotFoundException('User not found');
+```
+
+**Naming convention**: `SCREAMING_SNAKE_CASE`, format `[DOMAIN]_[REASON]`
+- `USER_NOT_FOUND`, `USER_DEACTIVATED`
+- `INVITATION_NOT_FOUND`, `USER_LIMIT_REACHED`
+- `INVALID_CREDENTIALS`, `CONFIRMATION_TOKEN_EXPIRED`
+
+**Exceptions to this rule** (do NOT add codes):
+- Validation pipe errors — these carry a per-field `code` in the `errors` array instead
+- Bare `UnauthorizedException()` in the JWT strategy — no info leak on invalid token by design
+
+## Response Transformation
+
+{{> slot: response-transformation }}
+
+## Pagination
+
+Use a shared `paginatedResponseSchema` helper for all list endpoints that return paginated data.
+
+**Rules**:
+* Query params always use `page`/`pageSize` — never expose `skip`/`take` to the client
+* Response always uses the `{ items, total, skip, take }` shape — never `page`/`pageSize`
+* `pageSize` max is 100; default is 50
+* Always use `getManyAndCount()` so `total` is accurate
+
+**Service** — convert `page`/`pageSize` to `skip`/`take` and return the envelope:
+
+```typescript
+async list(params: { page: number; pageSize: number }): Promise<{ items: Foo[]; total: number; skip: number; take: number }> {
+  const skip = (params.page - 1) * params.pageSize;
+  const take = params.pageSize;
+  const [items, total] = await qb.skip(skip).take(take).getManyAndCount();
+  return { items, total, skip, take };
+}
+```
+
+Query-param coercion and response-DTO declaration are stack-specific:
+
+{{> slot: pagination-dtos }}
+
+## Security
+
+* Sanitize all user input
+* Use parameterized queries (the ORM handles this automatically)
+* Implement authentication with Guards (`@UseGuards(AuthGuard)`)
+* Implement authorization checks for protected resources
+* Validate file uploads (type, size, content)
+* Never commit secrets, API keys, or credentials to version control
+* Use environment variables for configuration
+* Hash passwords with bcrypt
+* Use HTTPS in production
+
+## Constants
+
+File name template: `xx-yy.constant.ts` for `XxYy` constant
+
+Files with constants should be placed in the `constants/` folder within the corresponding module (see
+`ai/infrastructure/project-structure.md` for module details)
+
+## Enums
+
+File name template: `xx-yy.enum.ts` for `XxYy` enum
+
+Files with enums should be placed in the `enums/` folder within the corresponding module (see `ai/infrastructure/project-structure.md` for
+module details)
+
+## No Magic Strings or Numbers
+
+**MANDATORY**: Never use raw string or number literals where a named constant or enum value can be used instead. Magic values scatter meaning across the codebase, make refactoring error-prone, and produce silent bugs when a value changes in one place but not another.
+
+**Rules**:
+* Any string or number that carries domain meaning and appears in more than one place **must** be a constant or enum
+* Any string or number that carries domain meaning and appears in only one place **should still** be a constant or enum if it is likely to be referenced elsewhere in the future (e.g. audit action names, entity type labels, JWT token types)
+* Raw string comparisons against domain values are always wrong — use the enum
+
+**Enums** for closed sets of values (token types, roles, statuses, entity types, action names):
+```typescript
+// ✅ Correct
+export enum JwtType {
+  USER = 'user',
+  ADMIN = 'admin',
+  IMPERSONATION = 'impersonation',
+}
+
+if (payload.type === JwtType.IMPERSONATION) { ... }
+
+// ❌ Incorrect
+if (payload.type === 'impersonation') { ... }
+```
+
+**Constants** for single values with no closed set (limits, expiry defaults, config keys):
+```typescript
+// ✅ Correct — src/feature/user/constants/max-invitation-attempts.constant.ts
+export const MAX_INVITATION_ATTEMPTS = 5;
+
+// ❌ Incorrect
+if (attempts > 5) { ... }
+```
+
+**Where to place them**:
+* Enums belong in `enums/` within the owning module — see **Enums** section above
+* Constants belong in `constants/` within the owning module — see **Constants** section above
+* Cross-cutting enums/constants (e.g. `JwtType`, `ERROR_CODES`) belong in `src/common/`
+
+**Common categories that always require an enum or constant**:
+* JWT `type` field values
+* Audit action names and entity type labels
+* Platform and tenant role values
+* Any status value with a closed set
+* Any HTTP header name, cookie name, or metadata key used in multiple places
+
+## Code Quality
+
+* Follow SOLID principles
+* Keep functions small and focused (single responsibility)
+* Use meaningful variable and function names
+* Add comments only where logic is complex or non-obvious
+* Remove commented-out code before committing
+* Use TypeScript features: interfaces, types, generics, decorators
+* Prefer composition over inheritance
+* Use dependency injection for loose coupling
+* Write self-documenting code
+* Keep code DRY (Don't Repeat Yourself)

package/presets/nestjs/slots/architect-discussion-topics.md

@@ -0,0 +1,4 @@
+<!-- cairn preset: nestjs — fills {{> stack/architect-discussion-topics }} (A.3).
+     `--stack nestjs,typeorm` also appends the typeorm slot (schema, migrations). -->
+- **API design questions** — endpoint naming, request/response shape, pagination or filtering needs
+- **Layering** — what belongs in the feature module vs. the API module

package/presets/nestjs/slots/architect-mandatory-docs.md

@@ -0,0 +1,5 @@
+<!-- cairn preset: nestjs — fills {{> stack/architect-mandatory-docs }} (A.2).
+     `--stack nestjs,typeorm` also appends the typeorm slot (DATABASE_SCHEMA.md). -->
+- `ai/infrastructure/code-guidelines.md`
+- `ai/infrastructure/project-structure.md`
+- `ai/infrastructure/mappers.md`

package/presets/nestjs/slots/architect-references.md

@@ -0,0 +1,5 @@
+<!-- cairn preset: nestjs — fills {{> stack/architect-references }} (A.1).
+     Primary-stack-only, not concatenated. -->
+- Backend source files (modules, services, entities, DTOs, controllers)
+- Context docs in `ai/contexts/**` — entity definitions, business logic, feature docs
+- The frontend repo's context docs, if the task touches an API shape the frontend consumes

package/presets/nestjs/slots/implementation-reference.md

@@ -0,0 +1,45 @@
+<!-- cairn preset: nestjs — fills {{> stack/implementation-reference }} in the core
+     developer. Framework areas only. `--stack nestjs,typeorm` also appends
+     presets/typeorm/slots/implementation-reference.md (entities, migrations,
+     repositories). From snap-proof/backend/ai/agents/node-developer.md. -->
+
+Quick reminders for the most common implementation areas. The authoritative source
+is always `ai/infrastructure/code-guidelines.md`.
+
+### Module structure
+- Feature modules in `src/feature/<name>/` — business logic and services
+- API modules in `src/api/modules/<name>/` — HTTP layer only (controllers, API-layer services, request/response DTOs)
+- Register providers, imports, and exports explicitly in every module file
+
+### Controllers
+- Thin controllers: delegate all business logic to services
+- `@Get()` / `@Post()` / `@Put()` / `@Patch()` / `@Delete()` with explicit route paths
+- Bind inputs with `@Body()`, `@Param()`, `@Query()`
+- Apply `@UsePipes(ValidationPipe)` and `@UseGuards()` where required
+- Return consistent response shapes; use response DTOs and mappers
+
+### Services
+- All business logic in feature services; API-layer services handle HTTP concerns only
+- Throw NestJS built-in exceptions: `NotFoundException`, `BadRequestException`, `UnauthorizedException`, …
+- async/await throughout
+
+### DTOs
+- One file per DTO, `.dto.ts` suffix; validation decorators for every property (per the validation-stack variant)
+- `@ApiProperty()` from `@nestjs/swagger` on every property
+- Request DTOs in `src/api/dtos/`; shared/internal DTOs in `src/feature/dtos/`
+
+### Error handling
+- Use NestJS exceptions — never expose raw DB errors or stack traces
+- Custom exceptions extend `HttpException` only when no built-in fits
+- Log errors at service level; never log sensitive data
+
+### Testing
+- Unit tests for services: `feature-name.service.spec.ts`
+- `Test.createTestingModule()` for NestJS context; mock dependencies
+- Cover happy paths, not-found cases, and validation failures
+
+### File naming
+- `feature-name.module.ts` / `.service.ts` / `.controller.ts`
+- DTOs: `create-feature.dto.ts`, `update-feature.dto.ts`, `feature-response.dto.ts`
+- Tests: `feature-name.service.spec.ts`
+- All kebab-case

package/presets/nestjs/slots/key-patterns.md

@@ -0,0 +1,11 @@
+<!-- cairn preset: nestjs — fills {{> stack/key-patterns }} in the core architect
+     and developer. `--stack nestjs,typeorm` also appends the typeorm slot. -->
+
+Module and layer conventions: **`ai/infrastructure/project-structure.md`** — feature
+modules (`src/feature/`) vs. API modules (`src/api/modules/`), service/repository
+placement. Plans should follow the same shape.
+
+Code conventions (naming, DTOs, validation, decorators, error handling):
+**`ai/infrastructure/code-guidelines.md`**.
+
+Mapper conventions: **`ai/infrastructure/mappers.md`**.

package/presets/nestjs/slots/plan-step-ordering.md

@@ -0,0 +1,12 @@
+<!-- cairn preset: nestjs — fills {{> stack/plan-step-ordering }} in the core
+     architect's Plan format. This slot is *not* concatenated across stack entries
+     — it is one coherent sequence, taken from the primary stack (stack[0]). It
+     assumes an ORM in step 1; a bare `--stack nestjs` repo trims that step.
+     From node-architect.md. -->
+1. Entity / migration changes
+2. Feature module — service and repository setup
+3. DTOs and validation decorators
+4. API module — controller and endpoint implementation
+5. Error handling and edge cases
+6. Unit and integration test hooks
+7. Context doc updates

package/presets/nestjs/slots/review-checklist.md

@@ -0,0 +1,12 @@
+<!-- cairn preset: nestjs — fills {{> stack/review-checklist }} in the core reviewer.
+     Framework rules only. A repo on `--stack nestjs,typeorm` also gets the ORM
+     rows from presets/typeorm/slots/review-checklist.md (the renderer concatenates
+     this slot from every stack entry). Response-mapping and validation-decorator
+     rows come from the chosen validation-stack variant, not here. -->
+
+| No `any` type — use proper TypeScript types | All changed files |
+| Enums in `enums/` folder, constants in `constants/` folder, kebab-case filenames | Feature module |
+| No magic strings — use enum values or named constants | Anywhere |
+| API modules contain no business logic (thin controllers, delegate to feature services) | Controller / API service files |
+| Feature modules export only the services that API modules need | Module files |
+| NestJS built-in exceptions used for errors (`NotFoundException`, `BadRequestException`, …) | Service and controller files |

package/presets/nestjs/variants/validation-class-validator.md

@@ -0,0 +1,120 @@
+<!-- cairn variant: validation-stack = class-validator. Fills the dto-naming,
+     dto-definition, validation-stack, controller-response,
+     response-transformation and pagination-dtos slots in
+     presets/node/code-guidelines.md.
+     In use by: snap-backend. Requires `class-validator` + `class-transformer`
+     and the project's own `@ResponseMapper` decorator. -->
+
+## slot: dto-naming
+
+* Use operation-prefixed names for incoming request data:
+    - `CreateProjectDto`, `UpdateUserDto`
+    - File: `create-feature.dto.ts`, `update-feature.dto.ts`
+* Use the `Response` suffix for server response shapes:
+    - `UserResponse`, `ProjectListResponse`
+    - File: `feature-response.dto.ts`
+
+## slot: dto-definition
+
+* Use class-validator decorators: `@IsString()`, `@IsNumber()`, `@IsEmail()`, `@IsOptional()`, `@IsNotEmpty()`
+* Use class-transformer decorators: `@Type()`, `@Exclude()`, `@Expose()`
+* Add Swagger documentation: `@ApiProperty()`, `@ApiPropertyOptional()`
+* Provide validation error messages where appropriate
+
+## slot: validation-stack
+
+* Use class-validator decorators on all DTO properties
+* Use `ValidationPipe` globally or per-controller
+* Create custom validators for complex validation logic
+
+## slot: controller-response
+
+* Apply `@UsePipes(ValidationPipe)` for automatic DTO validation
+* Annotate the response shape with `@ResponseMapper(ResponseDtoClass)` on every endpoint that returns data
+
+## slot: response-transformation
+
+**IMPORTANT**: The `@ResponseMapper(ResponseDtoClass)` decorator automatically handles entity-to-DTO transformation using class-transformer.
+
+**How it works**:
+* The decorator uses `@Expose()` decorators in the response DTO to pick which fields to include
+* The decorator uses `@Type()` decorators to handle nested object transformations
+* You **DO NOT** need to manually create mapper functions to pick fields
+
+**Best Practices**:
+* Return entities or plain objects from service methods
+* Only perform minimal transformations needed for data structure (e.g., flattening nested properties)
+* Let `@ResponseMapper` handle field selection and type transformation
+* Do **NOT** create separate mapper functions just to pick fields - the decorator does this automatically
+
+**Example - Correct approach**:
+```typescript
+// Service method - minimal transformation
+async getDevicesByProjects() {
+  const devices = await this.siteDeviceService.getDevicesByProjects();
+
+  // Only flatten nested structures that don't match DTO
+  return devices.map(device => ({
+    ...device,
+    site: device.site ? {
+      ...device.site,
+      city: device.site.city?.name || null  // Flatten CityEntity to string
+    } : null,
+  }));
+}
+
+// Controller - @ResponseMapper handles field picking
+@Get('by-projects')
+@ResponseMapper(DeviceWithProjectsResponse)
+async getDevicesByProjects(@Query() query: QueryDto) {
+  return this.service.getDevicesByProjects(query);
+}
+
+// Response DTO - @Expose() picks fields automatically
+export class DeviceWithProjectsResponse {
+  @Expose() id: string;
+  @Expose() description: string;
+  // Only exposed fields will be returned
+}
+```
+
+**Example - Incorrect approach** (avoid this):
+```typescript
+// ❌ DON'T create mapper functions just to pick fields
+function mapToResponse(device) {
+  return {
+    id: device.id,              // @ResponseMapper does this
+    description: device.description,  // automatically
+  };
+}
+```
+
+## slot: pagination-dtos
+
+**Query params** — declare `page` and `pageSize` with `@Type(() => Number)` so query strings coerce:
+
+```typescript
+export class FooListQuery {
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page = 1;
+
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  pageSize = 50;
+}
+```
+
+**Response DTO** — expose the envelope fields and type the items:
+
+```typescript
+export class FooListResponse {
+  @Expose() @Type(() => FooResponse) items: FooResponse[];
+  @Expose() total: number;
+  @Expose() skip: number;
+  @Expose() take: number;
+}
+```