@rhino-dev/rhino-nestjs 0.2.5

package/stubs/skills/rhino-bugfix.md

@@ -0,0 +1,117 @@
+---
+name: rhino-bugfix
+description: Fix a bug in an Rhino NestJS application using TDD — reproduce with a failing test, fix the root cause, verify.
+---
+
+You are fixing a bug in an Rhino NestJS application. Always reproduce the bug with a failing test before touching production code.
+
+## Step 1: Reproduce the Bug
+
+Before writing a fix, write a test that demonstrates the bug. The test MUST fail with the current code.
+
+Describe the bug as a test assertion:
+
+```typescript
+it('should [expected behavior] but [actual behavior]', async () => {
+  // Arrange: set up the exact conditions that trigger the bug
+  // Act: perform the action that causes the bug
+  // Assert: what SHOULD happen (not what currently happens)
+});
+```
+
+Run the test to confirm it fails:
+```bash
+npm test -- --testPathPattern=your-spec
+```
+
+If the test passes immediately, either the bug is already fixed or you have not reproduced the correct scenario. Do not proceed until the test fails.
+
+## Step 2: Diagnose the Root Cause
+
+Identify which layer the bug lives in:
+
+| Layer | File | Common bugs |
+|-------|------|-------------|
+| Model registration | `app.module.ts` | Wrong Prisma model name, missing filter/include |
+| Query builder | `query-builder.service.ts` | Filter/sort/include not applied correctly |
+| Resource service | `resource.service.ts` | Missing org scope, wrong castId, null not handled |
+| Validation | `validation.service.ts` | Wrong schema picked, forbidden fields logic wrong |
+| Policy | `policies/[model].policy.ts` | Wrong permission, missing role branch |
+| Policy guard | `guards/resource-policy.guard.ts` | Wrong action resolved from HTTP method/path |
+| Serializer | `services/serializer.service.ts` | Hidden column not stripped, wrong field returned |
+| Controller | `controllers/global.controller.ts` | Wrong status code, missing audit log call |
+
+Read the relevant file(s) to understand the logic flow.
+
+## Step 3: Common Bug Patterns
+
+### Bug: 404 on a valid record (wrong org scope)
+
+The model has `belongsToOrganization: true` but the record was created without `organizationId`, or the request uses the wrong org identifier.
+
+Check:
+- `orgFilter()` in `resource.service.ts` — is `organizationId` being set on create?
+- `ResolveOrganizationMiddleware` — is the org resolved from the correct URL param?
+- `multiTenant.organizationIdentifierColumn` — does it match the actual column in the DB?
+
+### Bug: 403 that should be 200 (permission check wrong)
+
+```bash
+# Debug: check what permission is being checked
+# Add temporary log in resource-policy.guard.ts:
+console.log('Checking permission:', `${modelSlug}.${action}`, 'user:', user?.permissions);
+```
+
+Verify:
+- The user actually has the correct permission in `user_roles.permissions`.
+- `resolveUserRoleSlug()` returns the correct role for the user+org combination.
+- The `resourceSlug` on the policy matches the key in `RhinoModule.forRoot()`.
+
+### Bug: `organizationId` appears in the response body
+
+The serializer is not stripping `organizationId`. This leaks tenant information.
+
+Check `serializer.service.ts` — is `organizationId` in `additionalHiddenColumns` or in the policy's `hiddenAttributesForShow()`?
+
+### Bug: Validation passes fields that should be forbidden
+
+Check `validation.service.ts` `resolvePermittedFields()` — is the policy's `permittedAttributesForCreate()` being called? Is `allowAllFields` (`permittedFields = ['*']`) being returned when it should not be?
+
+### Bug: Soft-deleted records appear in normal listing
+
+`resource.service.ts` `findAll()` should filter `where.deletedAt = null` unless `onlyTrashed` or `includeTrashed` is set. Check that `softDeletes: true` is set on the model registration.
+
+### Bug: Prisma error "model not found"
+
+`PrismaService.model(name)` tries: exact name → camelCase → lowercase. If your Prisma model is `BlogPost`, pass `model: 'blogPost'` (camelCase) in the registration.
+
+## Step 4: Apply the Fix
+
+Make the minimal change that fixes the bug. Do not refactor unrelated code in the same change.
+
+Run the test that was failing:
+```bash
+npm test -- --testPathPattern=your-spec
+```
+
+It should now pass.
+
+## Step 5: Run the Full Suite
+
+```bash
+npm test
+```
+
+All previously passing tests must still pass. If a new test failure appears, it means the fix has a side effect — investigate before proceeding.
+
+## Step 6: Add Regression Context
+
+Add a comment above the test that explains why the test exists:
+
+```typescript
+// Regression: bug where belongsToOrganization was not applied on findAll,
+// allowing cross-tenant data leakage. Fixed in resource.service.ts:orgFilter().
+it('scopes posts to the current organization', async () => { /* ... */ });
+```
+
+This ensures future contributors understand why the test must not be deleted.

package/stubs/skills/rhino-deploy.md

@@ -0,0 +1,5 @@
+# /rhino-deploy — Deployment Guide
+
+Guide for deploying an Rhino NestJS application: set required env vars (DATABASE_URL, JWT_SECRET),
+run `npx prisma migrate deploy`, build with `npm run build`, start with `node dist/main.js`,
+configure reverse proxy, and verify health endpoint.

package/stubs/skills/rhino-docs.md

@@ -0,0 +1,147 @@
+---
+name: rhino-docs
+description: Update documentation for an Rhino NestJS change — JSDoc, README, CLAUDE.md, and the Docusaurus docs site.
+---
+
+You are updating documentation for a change to an Rhino NestJS application or to the Rhino NestJS library itself.
+
+## Step 1: Identify What Changed
+
+Read the diff or ask the user what changed:
+- New feature added?
+- Existing behavior modified?
+- Config option added or renamed?
+- New CLI command?
+- Bug fixed that users might have been working around?
+
+## Step 2: Determine Which Docs Need Updates
+
+| What changed | Docs to update |
+|---|---|
+| New `ModelRegistration` property | `README.md` config reference, `docs/server/nestjs/models.md` |
+| New query parameter | `README.md` query conventions, `docs/server/nestjs/querying.md` |
+| New feature (any) | `README.md` feature table, `CLAUDE.md` feature table, relevant Docusaurus page |
+| Authorization behavior | `docs/server/nestjs/policies.md` |
+| Multi-tenant behavior | `docs/server/nestjs/multi-tenancy.md` |
+| Route group config | `docs/server/nestjs/route-groups.md` |
+| Soft delete behavior | `docs/server/nestjs/soft-deletes.md` |
+| Audit trail | `docs/server/nestjs/audit-trail.md` |
+| Nested operations | `docs/server/nestjs/nested-operations.md` |
+| Prisma migration flow | `docs/server/nestjs/models.md` |
+| CLI command | `README.md` CLI section, `docs/server/nestjs/getting-started.md` |
+| Blueprint YAML format | `docs/server/nestjs/blueprint.md` |
+| Validation/Zod | `docs/server/nestjs/validation.md` |
+| Request lifecycle | `docs/server/nestjs/request-lifecycle.md` |
+
+## Step 3: README.md Updates
+
+For new features, add a row to the feature summary table (keep the `#` numbering sequential):
+
+```markdown
+| 29 | **New Feature Name** | One-sentence description of what it does. |
+```
+
+For new `ModelRegistration` properties, add to the config reference section:
+
+```markdown
+| `newProperty` | `type` | Description of what it controls. |
+```
+
+For new query parameters, add to the query string conventions section with a `curl` example.
+
+## Step 4: CLAUDE.md Updates
+
+If the feature table in `CLAUDE.md` is affected, add a row:
+
+```markdown
+| 29 | **New Feature** | `new-service.ts`, `affected-controller.ts` |
+```
+
+If a development rule needs to be updated (e.g., new naming convention), update the relevant rule section.
+
+## Step 5: Docusaurus Docs
+
+The docs live at `../docs/docs/server/nestjs/`. Each file has a frontmatter block:
+
+```markdown
+---
+sidebar_position: N
+title: Page Title
+---
+```
+
+When updating a page:
+1. Find the correct page for the feature category.
+2. Update or add code examples — all examples must use TypeScript/NestJS syntax, not PHP/Laravel.
+3. Add `:::tip`, `:::info`, or `:::warning` callouts for important nuances.
+4. If adding a new page, match the `sidebar_position` to slot it in the right order.
+
+### Code Example Style
+
+All code examples must follow NestJS conventions:
+
+```typescript
+// ✓ Correct — TypeScript, Zod, Prisma
+const PostSchema = z.object({
+  title: z.string().max(255),
+  status: z.enum(['draft', 'published']),
+});
+
+posts: {
+  model: 'post',
+  validation: PostSchema,
+}
+```
+
+```php
+// ✗ Wrong — do not use PHP/Laravel examples in NestJS docs
+protected $validationRules = ['title' => 'string|max:255'];
+```
+
+### Docusaurus Admonitions
+
+```markdown
+:::tip
+Use `validationUpdate: schema.partial()` so all fields become optional on PUT requests.
+:::
+
+:::info
+The `belongsToOrganization` flag works at the query level — it does not validate FK chains.
+:::
+
+:::warning
+Never accept `organizationId` from the request body. Rhino strips it automatically.
+:::
+```
+
+## Step 6: JSDoc in Source Code
+
+For any changed service method, update or add JSDoc:
+
+```typescript
+/**
+ * Applies the registered policy's `permittedAttributesForCreate()` to strip
+ * forbidden fields and validates the remainder against the model's Zod schema.
+ *
+ * @throws never — returns a ValidationResult; caller decides how to respond.
+ */
+validateForAction<T>(data, reg, ctx): ValidationResult<T>
+```
+
+## Step 7: Verify Docs Build (Optional)
+
+If the Docusaurus site has a local dev server:
+```bash
+cd ../docs && npm run start
+```
+
+Check that the page renders correctly and the sidebar order is right.
+
+## Checklist
+
+- [ ] Feature table in `README.md` updated
+- [ ] Feature table in `CLAUDE.md` updated
+- [ ] Config reference in `README.md` updated if new option added
+- [ ] Relevant Docusaurus page(s) updated with NestJS code examples
+- [ ] JSDoc on changed public methods updated
+- [ ] No PHP/Laravel code examples in NestJS docs

package/stubs/skills/rhino-feature.md

@@ -0,0 +1,146 @@
+---
+name: rhino-feature
+description: Add a new feature to an Rhino NestJS application using TDD. Reads context, writes tests first, then implements.
+---
+
+You are adding a new feature to an Rhino NestJS application. Follow the TDD flow: understand → plan → test → implement → verify.
+
+## Step 1: Understand the Codebase
+
+Read the following files to understand the project structure before writing any code:
+
+1. `CLAUDE.md` — development rules, architecture overview, feature table.
+2. `src/app.module.ts` — which models are registered and how.
+3. `prisma/schema.prisma` — the data model.
+4. Any existing `*.spec.ts` files related to the feature area.
+
+Ask the user to clarify the feature if anything is ambiguous:
+- Which model(s) does this feature affect?
+- Which roles should have access?
+- What are the expected HTTP status codes for happy path and error cases?
+- Does it require a Prisma schema change?
+
+## Step 2: Plan Before Coding
+
+Write a brief plan in plain text (no code yet):
+
+- What Prisma schema changes are needed?
+- What `ModelRegistration` changes are needed (new `allowedFilters`, `allowedIncludes`, Zod schema, etc.)?
+- What policy changes are needed (`permittedAttributesForCreate`, etc.)?
+- What new service methods (if any) are needed?
+- What tests will you write and what will they verify?
+
+Show the plan to the user and wait for approval before proceeding.
+
+## Step 3: Write Tests First
+
+Create or update `*.spec.ts` files BEFORE touching implementation. Failing tests prove the feature is missing.
+
+Write tests for each scenario:
+
+```typescript
+// Happy path — 200 / 201
+it('allows admin to create a [resource]', async () => {
+  // Arrange: create org, user with admin role
+  // Act: POST /api/:org/resource with valid body
+  // Assert: 201, response matches expected shape
+});
+
+// Authorization denied — 403
+it('blocks viewer from creating a [resource]', async () => {
+  // Arrange: user with viewer role (no store permission)
+  // Act: same POST request
+  // Assert: 403
+});
+
+// Validation failure — 422
+it('returns 422 when required field is missing', async () => {
+  // Act: POST with empty body
+  // Assert: 422, errors object contains field key
+});
+
+// Not found — 404
+it('returns 404 for unknown resource id', async () => { /* ... */ });
+
+// Multi-tenant isolation
+it('does not return [resource] data from another organization', async () => {
+  // Create data in org A, request from org B, verify 404 or empty list
+});
+```
+
+Run tests to confirm they fail:
+```bash
+npm test -- --testPathPattern=your-spec-file
+```
+
+## Step 4: Implement
+
+Work in this order:
+
+1. **Prisma schema** — add/modify models in `prisma/schema.prisma`, then:
+   ```bash
+   npx prisma migrate dev --name add_[feature_name]
+   npx prisma generate
+   ```
+
+2. **Zod schema** — create or update validation:
+   ```typescript
+   // Base schema (used for both store and update)
+   export const PostSchema = z.object({
+     title: z.string().max(255),
+     status: z.enum(['draft', 'published']),
+   });
+
+   // Action-specific override (update makes all fields optional)
+   export const PostUpdateSchema = PostSchema.partial();
+   ```
+
+3. **Policy** — create or update a `ResourcePolicy` subclass:
+   ```typescript
+   export class PostPolicy extends ResourcePolicy {
+     permittedAttributesForCreate(user: any): string[] {
+       if (this.hasRole(user, 'admin', /* org */)) return ['*'];
+       return ['title', 'content'];
+     }
+     permittedAttributesForUpdate(user: any): string[] {
+       return this.permittedAttributesForCreate(user);
+     }
+   }
+   ```
+
+4. **Model registration** — update `RhinoModule.forRoot()`:
+   ```typescript
+   posts: {
+     model: 'post',
+     policy: PostPolicy,
+     validation: PostSchema,
+     validationUpdate: PostUpdateSchema,
+     allowedFilters: ['status'],
+     allowedSorts: ['createdAt', 'title'],
+     softDeletes: true,
+     belongsToOrganization: true,
+   }
+   ```
+
+5. **Service methods** — add to an existing service if the logic is beyond standard CRUD. Only create a new controller if the feature cannot be expressed through model registration.
+
+## Step 5: Verify
+
+```bash
+npm test -- --testPathPattern=your-spec-file  # New tests must pass
+npm test                                        # Full suite must stay green
+```
+
+Fix any regressions before declaring the feature done.
+
+## Step 6: Update Docs
+
+Update `docs/docs/server/nestjs/` — find the relevant page and update it with code examples. If this is a genuinely new concept, create a new doc page. Update `CLAUDE.md` if the features table changed.
+
+## Common Mistakes to Avoid
+
+- Do not include `organizationId` in the Zod schema — `ValidationService` strips it automatically.
+- Do not use `class-validator` decorators — use Zod schemas.
+- Do not create per-model controllers — all CRUD flows through `GlobalController`.
+- Do not read Prisma directly from controllers — use `ResourceService`.
+- Always test multi-tenant isolation, even if it seems obvious.

package/stubs/skills/rhino-migrate.md

@@ -0,0 +1,181 @@
+---
+name: rhino-migrate
+description: Create or update a Prisma migration in an Rhino NestJS project — schema change, registration update, validation update, and test run.
+---
+
+You are making a Prisma schema change in an Rhino NestJS application. Follow these steps to keep the schema, registration, validation, and tests in sync.
+
+## Step 1: Read Current State
+
+```bash
+cat prisma/schema.prisma
+npm test  # baseline — note pass/fail counts
+```
+
+Also read:
+- `src/app.module.ts` — model registrations affected by the schema change
+- The Zod schema file(s) for affected models
+- The policy file(s) for affected models
+
+## Step 2: Make the Schema Change
+
+Edit `prisma/schema.prisma`. Follow these conventions:
+- Field names: camelCase (`organizationId`, `createdAt`)
+- Model names: PascalCase singular (`BlogPost`)
+- Required fields do NOT have `?`; optional fields have `?`
+- Add `@default(now())` to `createdAt`, `@updatedAt` to `updatedAt`
+- Add `deletedAt DateTime?` for soft-delete models
+
+Common changes:
+
+**Add a new field:**
+```prisma
+model Post {
+  // existing fields...
+  featuredImageUrl String?   // new optional field
+  publishedAt      DateTime? // new optional timestamp
+}
+```
+
+**Add a new model:**
+```prisma
+model Tag {
+  id        Int     @id @default(autoincrement())
+  name      String
+  slug      String  @unique
+  posts     Post[]  @relation("PostTags")
+  createdAt DateTime @default(now())
+}
+```
+
+**Add a many-to-many relation:**
+```prisma
+model Post {
+  // ...
+  tags Tag[] @relation("PostTags")
+}
+```
+
+**Add an index:**
+```prisma
+model Post {
+  organizationId Int
+  @@index([organizationId])
+}
+```
+
+## Step 3: Run Migration
+
+```bash
+# Development (creates a new migration file)
+npx prisma migrate dev --name [descriptive_name]
+
+# Examples:
+npx prisma migrate dev --name add_published_at_to_posts
+npx prisma migrate dev --name create_tags_table
+npx prisma migrate dev --name add_featured_image_url_to_posts
+```
+
+Then regenerate the Prisma client:
+```bash
+npx prisma generate
+```
+
+## Step 4: Update Model Registration
+
+In `app.module.ts`, update the affected model's `ModelRegistration`:
+
+**New filterable/sortable fields:**
+```typescript
+posts: {
+  allowedFilters: ['status', 'userId', 'publishedAt'],  // add publishedAt
+  allowedSorts: ['createdAt', 'title', 'publishedAt'],  // add publishedAt
+}
+```
+
+**New includeable relationship:**
+```typescript
+posts: {
+  allowedIncludes: ['user', 'comments', 'tags'],  // add tags
+}
+```
+
+**New searchable field:**
+```typescript
+posts: {
+  allowedSearch: ['title', 'content', 'excerpt'],  // add excerpt
+}
+```
+
+## Step 5: Update Zod Validation Schema
+
+Add new fields to the validation schema(s). Match the Prisma types:
+
+| Prisma type | Zod equivalent |
+|---|---|
+| `String` | `z.string()` |
+| `String?` | `z.string().optional()` |
+| `Int` | `z.number().int()` |
+| `Int?` | `z.number().int().optional()` |
+| `Boolean` | `z.boolean()` |
+| `DateTime` | `z.string().datetime()` or `z.date()` |
+| `Json` | `z.any()` or a specific schema |
+| `Float` / `Decimal` | `z.number()` |
+
+```typescript
+export const PostSchema = z.object({
+  title: z.string().min(1).max(255),
+  content: z.string().optional(),
+  status: z.enum(['draft', 'published', 'archived']).optional(),
+  publishedAt: z.string().datetime().optional(),  // new field
+});
+```
+
+## Step 6: Update Policy (if needed)
+
+If the new field should be write-restricted by role, update `permittedAttributesForCreate` and `permittedAttributesForUpdate`:
+
+```typescript
+permittedAttributesForCreate(user: any): string[] {
+  if (this.hasRole(user, 'admin')) return ['*'];
+  // Editors can set publishedAt only if they have the publish role
+  if (this.hasRole(user, 'publisher')) {
+    return ['title', 'content', 'publishedAt'];
+  }
+  return ['title', 'content'];
+}
+```
+
+## Step 7: Run Tests
+
+```bash
+npm test
+```
+
+Fix any failures. Common failure causes after a migration:
+- Prisma client not regenerated (`npx prisma generate` again)
+- Test database needs migration (`npx prisma migrate dev` in the test env)
+- New required field not included in test seed data
+- TypeScript type errors after schema change (`npx tsc --noEmit`)
+
+## Step 8: Production Deployment Note
+
+For production deployments, use `prisma migrate deploy` (not `migrate dev`):
+
+```bash
+# In CI/CD pipeline — runs pending migrations without prompts
+npx prisma migrate deploy
+```
+
+Never run `migrate dev` in production. Document this in your deployment runbook.
+
+## Checklist
+
+- [ ] `prisma/schema.prisma` updated
+- [ ] `npx prisma migrate dev --name [...]` run successfully
+- [ ] `npx prisma generate` run to regenerate client
+- [ ] `ModelRegistration` updated (filters, sorts, includes, search)
+- [ ] Zod schema(s) updated with new fields
+- [ ] Policy updated if field-level permissions needed
+- [ ] All tests pass (`npm test`)
+- [ ] `npx tsc --noEmit` produces no errors