@rhino-dev/rhino-nestjs 0.2.5

package/stubs/skills/rhino-model.md

@@ -0,0 +1,180 @@
+---
+name: rhino-model
+description: Create a new Rhino model definition — Prisma schema, registration, Zod validation, and policy skeleton.
+---
+
+You are creating a new model in an Rhino NestJS application. Follow these steps in order.
+
+## Step 1: Read Context
+
+Before creating anything, read:
+- `prisma/schema.prisma` — existing models and conventions.
+- `src/app.module.ts` — how models are currently registered.
+- `CLAUDE.md` — project conventions.
+
+Ask the user for:
+- Model name (PascalCase singular, e.g., `BlogPost`)
+- Fields and their types
+- Relationships to existing models
+- Whether it needs multi-tenancy (`belongsToOrganization`)
+- Whether it needs soft deletes, audit trail, or UUID primary key
+- Which roles should have access and what they can do
+
+## Step 2: Prisma Schema
+
+Add the model to `prisma/schema.prisma`. Follow existing casing conventions (camelCase fields):
+
+```prisma
+model BlogPost {
+  id             Int           @id @default(autoincrement())
+  title          String
+  content        String?
+  status         String        @default("draft")
+  organizationId Int?
+  userId         Int
+  deletedAt      DateTime?
+  createdAt      DateTime      @default(now())
+  updatedAt      DateTime      @updatedAt
+
+  organization   Organization? @relation(fields: [organizationId], references: [id])
+  user           User          @relation(fields: [userId], references: [id])
+}
+```
+
+Run migration:
+```bash
+npx prisma migrate dev --name create_blog_posts
+npx prisma generate
+```
+
+## Step 3: Zod Validation Schema
+
+Create `src/schemas/blog-post.schema.ts`:
+
+```typescript
+import { z } from 'zod';
+
+export const BlogPostSchema = z.object({
+  title: z.string().min(1).max(255),
+  content: z.string().optional(),
+  status: z.enum(['draft', 'published', 'archived']).optional(),
+  userId: z.number().int().positive(),
+});
+
+// Update allows all fields optional (partial)
+export const BlogPostUpdateSchema = BlogPostSchema.partial();
+
+// Role-keyed schemas (optional — use when roles need different required fields)
+export const BlogPostStoreByRole = {
+  admin: BlogPostSchema,
+  '*': BlogPostSchema.omit({ status: true }),
+};
+```
+
+## Step 4: Policy
+
+Create `src/policies/blog-post.policy.ts`:
+
+```typescript
+import { ResourcePolicy } from '@rhino-dev/rhino-nestjs';
+
+export class BlogPostPolicy extends ResourcePolicy {
+  // Control which fields each role can write
+  permittedAttributesForCreate(user: any): string[] {
+    if (this.hasRole(user, 'admin')) return ['*'];
+    if (this.hasRole(user, 'editor')) return ['title', 'content'];
+    return [];
+  }
+
+  permittedAttributesForUpdate(user: any): string[] {
+    return this.permittedAttributesForCreate(user);
+  }
+
+  // Control which fields each role can read in responses
+  permittedAttributesForShow(user: any): string[] {
+    return ['*'];
+  }
+
+  hiddenAttributesForShow(user: any): string[] {
+    if (this.hasRole(user, 'admin')) return [];
+    return ['internalNotes'];
+  }
+}
+```
+
+## Step 5: Register in AppModule
+
+Add to `RhinoModule.forRoot({ models: { ... } })`:
+
+```typescript
+'blog-posts': {
+  model: 'blogPost',               // matches Prisma client key
+  policy: BlogPostPolicy,
+  validation: BlogPostSchema,
+  validationUpdate: BlogPostUpdateSchema,
+
+  // Query capabilities
+  allowedFilters: ['status', 'userId'],
+  allowedSorts: ['createdAt', 'title', 'updatedAt'],
+  defaultSort: '-createdAt',
+  allowedIncludes: ['user'],
+  allowedSearch: ['title', 'content'],
+
+  // Features
+  softDeletes: true,
+  belongsToOrganization: true,
+  hasAuditTrail: true,
+  paginationEnabled: true,
+  perPage: 25,
+}
+```
+
+## Step 6: Write Tests
+
+Create `src/services/blog-post.spec.ts` (or `test/e2e/blog-post.e2e-spec.ts`):
+
+```typescript
+describe('BlogPost endpoints', () => {
+  it('returns 201 when admin creates a blog post', async () => { /* ... */ });
+  it('returns 403 when viewer tries to create a blog post', async () => { /* ... */ });
+  it('returns 422 when title is missing', async () => { /* ... */ });
+  it('scopes blog posts to the current organization', async () => { /* ... */ });
+  it('soft deletes the blog post on DELETE', async () => { /* ... */ });
+});
+```
+
+Run:
+```bash
+npm test
+```
+
+## Step 7: Verify Route Table
+
+Check that the model is generating the expected routes:
+
+```typescript
+import { describeRoutes } from '@rhino-dev/rhino-nestjs';
+// In a test or startup log:
+console.log(describeRoutes(configService));
+```
+
+Expected routes for `blog-posts`:
+```
+GET    /api/:org/blog-posts
+POST   /api/:org/blog-posts
+GET    /api/:org/blog-posts/:id
+PUT    /api/:org/blog-posts/:id
+DELETE /api/:org/blog-posts/:id
+GET    /api/:org/blog-posts/trashed
+POST   /api/:org/blog-posts/:id/restore
+DELETE /api/:org/blog-posts/:id/force-delete
+```
+
+## Checklist
+
+- [ ] Prisma schema added and migrated
+- [ ] Zod schema created (store + update variants)
+- [ ] Policy created with `permittedAttributesForCreate/Update/Show`
+- [ ] Model registered in `RhinoModule.forRoot()`
+- [ ] Tests written and passing
+- [ ] `CLAUDE.md` features table updated if this adds a new capability

package/stubs/skills/rhino-plan.md

@@ -0,0 +1,5 @@
+# /rhino-plan — Plan Before Coding
+
+Guide for planning a new Rhino NestJS feature before writing code: identify affected models,
+policies, routes, and Prisma schema changes; list edge cases and multi-tenant implications;
+draft the blueprint YAML; outline required tests; then get approval before implementing.

package/stubs/skills/rhino-policy.md

@@ -0,0 +1,183 @@
+---
+name: rhino-policy
+description: Create or update an Rhino ResourcePolicy for a NestJS model — action permissions, attribute permissions, and role-based logic.
+---
+
+You are creating or updating an authorization policy for an Rhino NestJS model.
+
+## Step 1: Understand the Permission Model
+
+Rhino policies check `{slug}.{action}` permissions. The base `ResourcePolicy` class handles this automatically. You only need to subclass it to:
+
+1. Restrict which fields users can **write** (`permittedAttributesForCreate` / `permittedAttributesForUpdate`)
+2. Restrict which fields users can **read** (`permittedAttributesForShow` / `hiddenAttributesForShow`)
+3. Add custom authorization logic beyond permission checks (e.g., "only the author can edit")
+
+Read the following before writing any code:
+- `src/policies/resource-policy.ts` — the base class
+- `src/utils/permission-matcher.ts` — how `userHasPermission` and `resolveUserRoleSlug` work
+- `prisma/schema.prisma` — understand the model's fields
+- Existing policy files in `src/policies/`
+
+## Step 2: Identify the Permission Matrix
+
+Ask the user (or read the blueprint YAML) to define:
+
+| Role | index | show | store | update | destroy | Hidden fields | Create fields | Update fields |
+|------|-------|------|-------|--------|---------|---------------|---------------|---------------|
+| admin | ✓ | ✓ | ✓ | ✓ | ✓ | none | `*` | `*` |
+| editor | ✓ | ✓ | ✓ | ✓ | — | none | `[title, content]` | `[title, content]` |
+| viewer | ✓ | ✓ | — | — | — | `[cost]` | — | — |
+
+## Step 3: Create the Policy File
+
+Create `src/policies/[model].policy.ts`:
+
+```typescript
+import { ResourcePolicy } from '@rhino-dev/rhino-nestjs';
+
+export class PostPolicy extends ResourcePolicy {
+  // ── Action Authorization ──────────────────────────────────────
+  // Only needed if you want custom logic BEYOND the {slug}.{action} check.
+  // The base class already handles standard permission checks.
+
+  // Example: restrict update to the record's owner (plus admin)
+  update(user: any, model: any, organization?: any): boolean {
+    if (!super.update(user, model, organization)) return false;
+    if (this.hasRole(user, 'admin', organization)) return true;
+    return model?.userId === user?.id;
+  }
+
+  // ── Field-Level Write Permissions ─────────────────────────────
+  permittedAttributesForCreate(user: any): string[] {
+    if (this.hasRole(user, 'admin')) return ['*'];
+    if (this.hasRole(user, 'editor')) return ['title', 'content', 'categoryId'];
+    return [];
+  }
+
+  permittedAttributesForUpdate(user: any): string[] {
+    if (this.hasRole(user, 'admin')) return ['*'];
+    if (this.hasRole(user, 'editor')) return ['title', 'content'];
+    return [];
+  }
+
+  // ── Field-Level Read Permissions ──────────────────────────────
+  // Return ['*'] to allow all fields (default).
+  // Return a specific list to whitelist.
+  permittedAttributesForShow(user: any): string[] {
+    return ['*'];
+  }
+
+  // Return fields to ALWAYS hide for non-admin users.
+  hiddenAttributesForShow(user: any): string[] {
+    if (this.hasRole(user, 'admin')) return [];
+    return ['costPrice', 'internalNotes'];
+  }
+}
+```
+
+## Step 4: Register the Policy
+
+In `app.module.ts`, add `policy: PostPolicy` to the model registration:
+
+```typescript
+posts: {
+  model: 'post',
+  policy: PostPolicy,   // ← Add this
+  // ... rest of config
+}
+```
+
+## Step 5: Seed Permissions
+
+Permissions are stored as JSON on `users.permissions` (non-tenant) or `user_roles.permissions` (tenant).
+
+```typescript
+// Non-tenant: assign directly on user
+await prisma.user.update({
+  where: { id: adminUser.id },
+  data: { permissions: ['*'] },
+});
+
+// Tenant: assign via user_roles
+await prisma.userRole.create({
+  data: {
+    userId: editorUser.id,
+    organizationId: org.id,
+    roleSlug: 'editor',
+    permissions: ['posts.index', 'posts.show', 'posts.store', 'posts.update'],
+  },
+});
+```
+
+## Step 6: Write Policy Tests
+
+Create a unit test file `src/policies/post.policy.spec.ts`:
+
+```typescript
+describe('PostPolicy', () => {
+  let policy: PostPolicy;
+
+  beforeEach(() => {
+    policy = new PostPolicy();
+    policy.resourceSlug = 'posts';
+  });
+
+  describe('permittedAttributesForCreate', () => {
+    it('returns * for admin', () => {
+      const user = makeUserWithRole('admin', org.id);
+      expect(policy.permittedAttributesForCreate(user)).toEqual(['*']);
+    });
+
+    it('returns restricted fields for editor', () => {
+      const user = makeUserWithRole('editor', org.id);
+      expect(policy.permittedAttributesForCreate(user)).toEqual(
+        expect.arrayContaining(['title', 'content'])
+      );
+      expect(policy.permittedAttributesForCreate(user)).not.toContain('status');
+    });
+
+    it('returns empty array for viewer', () => {
+      const user = makeUserWithRole('viewer', org.id);
+      expect(policy.permittedAttributesForCreate(user)).toEqual([]);
+    });
+  });
+
+  describe('hiddenAttributesForShow', () => {
+    it('hides costPrice for non-admin', () => {
+      const user = makeUserWithRole('viewer', org.id);
+      expect(policy.hiddenAttributesForShow(user)).toContain('costPrice');
+    });
+
+    it('reveals all fields for admin', () => {
+      const user = makeUserWithRole('admin', org.id);
+      expect(policy.hiddenAttributesForShow(user)).toEqual([]);
+    });
+  });
+});
+```
+
+Run:
+```bash
+npm test -- --testPathPattern=post.policy
+```
+
+## Common Mistakes
+
+- Do not forget to call `super.update(...)` etc. in overridden action methods — skipping it bypasses the permission check entirely.
+- `hasRole(user, 'admin')` checks the role in the current organization context stored on the user object. If organization context is not set, it returns false.
+- Return `['*']` (not `[]`) from `permittedAttributesForShow` when all fields should be visible — `[]` means nothing is visible.
+- The `resourceSlug` on the policy must match the key in `RhinoModule.forRoot({ models: { [slug]: ... } })`.
+
+## Permission Reference
+
+| Action | Permission checked | Policy method |
+|--------|-------------------|---------------|
+| GET (list) | `{slug}.index` | `viewAny` |
+| GET (single) | `{slug}.show` | `view` |
+| POST | `{slug}.store` | `create` |
+| PUT/PATCH | `{slug}.update` | `update` |
+| DELETE | `{slug}.destroy` | `delete` |
+| GET trashed | `{slug}.trashed` | `viewTrashed` |
+| POST restore | `{slug}.restore` | `restore` |
+| DELETE force | `{slug}.forceDelete` | `forceDelete` |

package/stubs/skills/rhino-refactor.md

@@ -0,0 +1,147 @@
+---
+name: rhino-refactor
+description: Safely refactor Rhino NestJS code — establish baseline, apply incremental changes, verify tests pass at each step.
+---
+
+You are refactoring code in an Rhino NestJS project. The goal is to improve structure without changing observable behavior.
+
+## Step 1: Establish Baseline
+
+Before touching any code:
+
+```bash
+npm test
+```
+
+Note the exact test count and which tests pass. This is your baseline. Every test that currently passes must still pass after the refactor.
+
+Read the code to be refactored and identify:
+- What is the current structure?
+- What specific problem does the refactor solve? (readability, performance, duplication, etc.)
+- What is the target structure?
+
+## Step 2: Identify the Scope
+
+Clarify with the user what is in scope:
+- Which files are affected?
+- Are public interfaces (API config shape, service method signatures) changing?
+- Does this touch any of these critical paths?
+  - `resource.service.ts` — any change here affects all CRUD operations
+  - `resource-policy.guard.ts` — any change here affects authorization
+  - `validation.service.ts` — any change here affects input validation
+  - `query-builder.service.ts` — any change here affects all queries
+
+If public interfaces are changing, plan a migration path before starting.
+
+## Step 3: Refactor Incrementally
+
+Work in small steps. After each step, run the tests:
+
+```bash
+npm test
+```
+
+Common refactor patterns in Rhino NestJS:
+
+### Extract a service method
+
+If controller code is doing logic that belongs in a service:
+
+```typescript
+// Before: logic in controller
+@Post(':modelSlug')
+async store(...) {
+  const orgFilter = ...;  // logic here
+  const record = await ...;
+}
+
+// After: logic in ResourceService
+async create(modelSlug: string, data: any, ctx: ResourceContext) {
+  // moved logic
+}
+```
+
+### Consolidate repeated Zod schemas
+
+```typescript
+// Before: duplicated schema fragments
+const StoreSchema = z.object({ title: z.string(), status: z.enum([...]) });
+const UpdateSchema = z.object({ title: z.string().optional(), status: z.enum([...]).optional() });
+
+// After: derived from base
+const BaseSchema = z.object({ title: z.string(), status: z.enum(['draft', 'published']) });
+const StoreSchema = BaseSchema;
+const UpdateSchema = BaseSchema.partial();
+```
+
+### Extract repeated policy logic
+
+```typescript
+// Before: repeated hasRole checks
+permittedAttributesForCreate(user: any) {
+  if (this.hasRole(user, 'admin') || this.hasRole(user, 'owner')) return ['*'];
+  // ...
+}
+permittedAttributesForUpdate(user: any) {
+  if (this.hasRole(user, 'admin') || this.hasRole(user, 'owner')) return ['*'];
+  // ...
+}
+
+// After: extracted helper
+private isPrivileged(user: any) {
+  return this.hasRole(user, 'admin') || this.hasRole(user, 'owner');
+}
+```
+
+### Consolidate model registration config
+
+```typescript
+// Before: scattered constants
+const POST_FILTERS = ['status', 'userId'];
+const POST_SORTS = ['createdAt', 'title'];
+
+// After: co-located config object
+export const PostModelConfig: ModelRegistration = {
+  model: 'post',
+  allowedFilters: ['status', 'userId'],
+  allowedSorts: ['createdAt', 'title'],
+  // ...
+};
+```
+
+## Step 4: Update Types
+
+If method signatures changed, update:
+- All call sites
+- TypeScript interfaces in `src/interfaces/`
+- Type exports in `src/index.ts`
+
+Run:
+```bash
+npx tsc --noEmit
+```
+
+Fix all type errors before running tests.
+
+## Step 5: Verify
+
+```bash
+npm test         # Full suite — must match baseline exactly
+npx tsc --noEmit # No type errors
+```
+
+If any test fails that was passing before, fix the code (not the test). Only modify tests if the test was genuinely wrong.
+
+## Step 6: Document Changes
+
+If the refactor changed any public API:
+- Update `CLAUDE.md`
+- Update `README.md` if the config shape changed
+- Update the relevant Docusaurus doc page
+
+## Rules
+
+- Never comment out a passing test to make a refactor work.
+- Never change behavior while refactoring — separate refactor commits from behavior changes.
+- If you discover a bug during refactoring, note it but do not fix it in the same change. Fix it separately with a test first.
+- Keep commits small. One logical change per commit.

package/stubs/skills/rhino-review.md

@@ -0,0 +1,113 @@
+---
+name: rhino-review
+description: Review Rhino NestJS code for correctness, security, and alignment with conventions. Produces a structured findings report.
+---
+
+You are reviewing code in an Rhino NestJS project. Produce a structured report with findings grouped by severity.
+
+## Step 1: Gather Context
+
+Read the following before reviewing:
+- `CLAUDE.md` — development rules and conventions
+- `src/app.module.ts` — model registrations
+- `prisma/schema.prisma` — data model
+- The specific file(s) the user asked you to review
+
+## Step 2: Run the Tests First
+
+```bash
+npm test
+```
+
+Note any failing tests. Do not proceed with fixes until you have the test baseline.
+
+## Step 3: Review Checklist
+
+Work through each category and note findings. Severity: **Critical** (security / data loss), **Major** (bug / missing behavior), **Minor** (convention / style).
+
+### Security
+
+- [ ] No `organizationId` accepted from request body — `ValidationService` must strip it.
+- [ ] Permissions checked before data access — `ResourcePolicyGuard` applied.
+- [ ] Cross-tenant isolation — `belongsToOrganization: true` set on models that need it.
+- [ ] No raw SQL queries that could be injected.
+- [ ] JWT secret comes from env (`process.env.JWT_SECRET`), not hardcoded.
+- [ ] Sensitive fields (`password`, `rememberToken`) in `auditExclude` and in `additionalHiddenColumns`.
+
+### Model Registration
+
+- [ ] Every field that should be filterable is in `allowedFilters`.
+- [ ] Every field that should be sortable is in `allowedSorts`.
+- [ ] `defaultSort` is set (avoid undefined ordering).
+- [ ] `allowedIncludes` lists only relationships that exist on the Prisma model.
+- [ ] `allowedSearch` fields are string columns (not IDs or JSON).
+- [ ] `softDeletes: true` is set if the Prisma model has a `deletedAt` field.
+- [ ] `hasAuditTrail: true` if audit logging is required.
+- [ ] `paginationEnabled` explicitly set if the model returns large datasets.
+
+### Policy
+
+- [ ] `permittedAttributesForCreate` and `permittedAttributesForUpdate` implemented.
+- [ ] `permittedAttributesForShow` and `hiddenAttributesForShow` implemented.
+- [ ] Every role in the permission matrix is covered (no missing `else` branches).
+- [ ] `hasRole(user, role)` is used correctly — it checks role within org context.
+- [ ] Overridden action methods (`update`, `delete`, etc.) call `super.method()`.
+- [ ] `resourceSlug` is set correctly (must match the model key in `RhinoModule.forRoot`).
+
+### Zod Validation
+
+- [ ] `validationStore` schema marks required fields as required.
+- [ ] `validationUpdate` schema makes all fields optional (`.partial()` or equivalent).
+- [ ] Enum values in the Zod schema match the valid values in Prisma schema / docs.
+- [ ] FK fields validated as positive integers (not strings).
+- [ ] No `organizationId` / `organization_id` in the Zod schema.
+- [ ] Role-keyed schemas (`Record<string, ZodSchema>`) have a `'*'` fallback.
+
+### Tests
+
+- [ ] Happy path (200/201) tests exist for each CRUD action.
+- [ ] 403 tests for each role that should be denied.
+- [ ] 422 test for missing required field on store.
+- [ ] 404 test for non-existent ID.
+- [ ] Multi-tenant isolation test (org A data not visible to org B).
+- [ ] Soft delete tests (trashed, restore, force-delete) if `softDeletes: true`.
+- [ ] Audit log created for creates, updates, and deletes if `hasAuditTrail: true`.
+
+### Code Style
+
+- [ ] No `class-validator` decorators — Zod only.
+- [ ] No per-model controllers — all CRUD through `GlobalController`.
+- [ ] Business logic in services, not controllers.
+- [ ] No direct `prisma.client.[model]` calls in controllers — use `ResourceService`.
+- [ ] `@Injectable()` decorator on all services.
+- [ ] All method parameters and return types explicitly typed.
+
+## Step 4: Produce Report
+
+Format your findings as:
+
+```
+## Code Review Report — [filename or feature]
+
+### Critical
+1. [Finding]: [file:line] — [explanation and fix]
+
+### Major
+1. [Finding]: [file:line] — [explanation and fix]
+
+### Minor
+1. [Finding]: [file:line] — [explanation and fix]
+
+### Passed Checks
+- Security: organizationId stripped ✓
+- Tests: multi-tenant isolation ✓
+- ...
+```
+
+## Step 5: Apply Fixes (if requested)
+
+If the user asks you to fix the findings:
+1. Fix Critical issues first.
+2. Write regression tests for any bugs found.
+3. Run `npm test` after each fix to confirm nothing breaks.
+4. Summarize what was changed.