一键在 Manus 中运行任何 Skill

conventions

星标5

分支1

更新时间2026年6月13日 20:16

Quick reference for all Librariarr project conventions and patterns. Consult when writing or reviewing code to verify correct patterns.

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

在 Manus 中运行

来源

ahembree

ahembree/librariarr

打开 GitHub 仓库查看创作者相关仓库

下载

在 Manus 中运行

Librariarr Conventions Quick Reference

Import Rules

Module	Correct Import	WRONG
Prisma client	`import { prisma } from "@/lib/db"`	`@/lib/prisma`
Validation	`import { validateRequest, schema } from "@/lib/validation"`	Inline schemas
Zod	`import { z } from "zod/v4"`	`from "zod"`
Sanitize	`import { sanitize, sanitizeErrorDetail } from "@/lib/api/sanitize"`	—
Session	`import { getSession } from "@/lib/auth/session"`	—
Prisma types	`import type { X } from "@/generated/prisma/client"`	—

API Route Checklist

Every route handler must:

Check auth: getSession() + session.isLoggedIn
Validate mutations: validateRequest(request, schema) — schema from @/lib/validation
Verify ownership: include userId: session.userId! in all queries
Sanitize responses: wrap with sanitize() from @/lib/api/sanitize
Use sanitizeErrorDetail() for error messages from external services
Never send stored API keys to frontend — use [id]/test-connection endpoints

Security Rules

All responses with server/integration data: sanitize() (strips accessToken, apiKey, plexToken, passwordHash)
Media item queries: library: { mediaServer: { userId: session.userId } } ownership check
Auth endpoints: authRateLimiter — 10 attempts / 15 min, return 429 with Retry-After
Use findFirst with userId filter, NOT bare findUnique({ where: { id } })

Data Patterns

fileSize: stored as BigInt, serialize to string in API responses
LibraryType: "MOVIE" | "SERIES" | "MUSIC"
Dynamic params (Next.js 16): { params }: { params: Promise<{ id: string }> } — params is a Promise, must await
Pagination: N+1 trick (take: limit + 1, pop last if over), response: { items, pagination: { page, limit, hasMore } }
Multi-select filters: pipe-separated (?resolution=4K|1080P)

Testing Rules

Constructor mocks: use function() keyword, NOT arrow functions (Vitest 4 requirement)
vi.hoisted(): required when mock variables are referenced inside vi.mock() factory functions
Route imports: MUST come AFTER all vi.mock() calls
Standard mocks: @/lib/db → test DB, @/lib/logger → all 3 loggers suppressed (logger, apiLogger, dbLogger)
Session: setMockSession({ userId, plexToken: "tok", isLoggedIn: true })
Cleanup: cleanDatabase() + clearMockSession() in beforeEach, disconnectTestDb() in afterAll
Helpers: callRoute(), callRouteWithParams(), expectJson<T>(response, status)

Styling

Tailwind CSS v4 with OKLCH color model (not HSL)
Dark mode: hardcoded via className="dark" on <html>
shadcn/ui: "new-york" style variant
Theme accent colors: override CSS vars --primary, --ring, --sidebar-primary

Git Conventions

Conventional commits: type(scope): description
Types: feat, fix, refactor, test, docs, chore, style, perf
Pre-commit hook: pnpm exec eslint --quiet
Commit-msg hook: commitlint (@commitlint/config-conventional)

Database Conventions

Schema changes need migration files for production (prisma migrate deploy only reads migration files)
Dev iteration: pnpm docker:dev:db:push (no migration files needed)
Migration naming: sequential 0001_init, 0002_description, etc.
After schema changes: pnpm exec prisma generate to regenerate client

Key File Locations

Purpose	Path
Prisma singleton	`src/lib/db.ts`
All Zod schemas	`src/lib/validation.ts`
Response sanitization	`src/lib/api/sanitize.ts`
Session/auth	`src/lib/auth/session.ts`
Multi-server dedup	`src/lib/dedup/server-filter.ts`
Filter utilities	`src/lib/filters/build-where.ts`
Memory cache	`src/lib/cache/memory-cache.ts`
Rate limiter	`src/lib/rate-limit/rate-limiter.ts`
Test DB setup	`tests/setup/test-db.ts`
Test helpers/factories	`tests/setup/test-helpers.ts`
Session mocking	`tests/setup/mock-session.ts`

同仓库更多 Skills

同仓库

run-librariarr

ahembree/librariarr

Launch, build, run, start, screenshot, or smoke-test the Librariarr Next.js webapp end-to-end. Use when asked to run librariarr, bring up the dev stack, take a screenshot of the dashboard or any UI page, verify a change in the running app, or check that the app boots cleanly.

2026-06-245

api-route

ahembree/librariarr

Generate a new Next.js API route with project boilerplate (auth, validation, sanitize, Prisma). Use when creating new API endpoints.

2026-06-135

api-test

ahembree/librariarr

Generate an integration test for an API route with all required mocks and boilerplate. Use when creating tests for API endpoints.

2026-06-135

prisma-migration

ahembree/librariarr

Create a Prisma migration file for schema changes. Required for production — db push only works in dev. Use after modifying schema.prisma.

2026-06-135

scaffold-feature

ahembree/librariarr

Scaffold a complete new feature end-to-end (Prisma model, migration, schemas, API routes, tests). Use for new CRUD resources or features that span multiple layers.

2026-06-135

zod-schema

ahembree/librariarr

Add a new Zod validation schema to src/lib/validation.ts. All schemas MUST live in this file using zod/v4. Use when creating validation for new API endpoints.

2026-06-135

name	conventions
description	Quick reference for all Librariarr project conventions and patterns. Consult when writing or reviewing code to verify correct patterns.

Librariarr Conventions Quick Reference

Import Rules

Module	Correct Import	WRONG
Prisma client	`import { prisma } from "@/lib/db"`	`@/lib/prisma`
Validation	`import { validateRequest, schema } from "@/lib/validation"`	Inline schemas
Zod	`import { z } from "zod/v4"`	`from "zod"`
Sanitize	`import { sanitize, sanitizeErrorDetail } from "@/lib/api/sanitize"`	—
Session	`import { getSession } from "@/lib/auth/session"`	—
Prisma types	`import type { X } from "@/generated/prisma/client"`	—

API Route Checklist

Every route handler must:

Check auth: getSession() + session.isLoggedIn
Validate mutations: validateRequest(request, schema) — schema from @/lib/validation
Verify ownership: include userId: session.userId! in all queries
Sanitize responses: wrap with sanitize() from @/lib/api/sanitize
Use sanitizeErrorDetail() for error messages from external services
Never send stored API keys to frontend — use [id]/test-connection endpoints

Security Rules

All responses with server/integration data: sanitize() (strips accessToken, apiKey, plexToken, passwordHash)
Media item queries: library: { mediaServer: { userId: session.userId } } ownership check
Auth endpoints: authRateLimiter — 10 attempts / 15 min, return 429 with Retry-After
Use findFirst with userId filter, NOT bare findUnique({ where: { id } })

Data Patterns

fileSize: stored as BigInt, serialize to string in API responses
LibraryType: "MOVIE" | "SERIES" | "MUSIC"
Dynamic params (Next.js 16): { params }: { params: Promise<{ id: string }> } — params is a Promise, must await
Pagination: N+1 trick (take: limit + 1, pop last if over), response: { items, pagination: { page, limit, hasMore } }
Multi-select filters: pipe-separated (?resolution=4K|1080P)

Testing Rules

Constructor mocks: use function() keyword, NOT arrow functions (Vitest 4 requirement)
vi.hoisted(): required when mock variables are referenced inside vi.mock() factory functions
Route imports: MUST come AFTER all vi.mock() calls
Standard mocks: @/lib/db → test DB, @/lib/logger → all 3 loggers suppressed (logger, apiLogger, dbLogger)
Session: setMockSession({ userId, plexToken: "tok", isLoggedIn: true })
Cleanup: cleanDatabase() + clearMockSession() in beforeEach, disconnectTestDb() in afterAll
Helpers: callRoute(), callRouteWithParams(), expectJson<T>(response, status)

Styling

Tailwind CSS v4 with OKLCH color model (not HSL)
Dark mode: hardcoded via className="dark" on <html>
shadcn/ui: "new-york" style variant
Theme accent colors: override CSS vars --primary, --ring, --sidebar-primary

Git Conventions

Conventional commits: type(scope): description
Types: feat, fix, refactor, test, docs, chore, style, perf
Pre-commit hook: pnpm exec eslint --quiet
Commit-msg hook: commitlint (@commitlint/config-conventional)

Database Conventions

Schema changes need migration files for production (prisma migrate deploy only reads migration files)
Dev iteration: pnpm docker:dev:db:push (no migration files needed)
Migration naming: sequential 0001_init, 0002_description, etc.
After schema changes: pnpm exec prisma generate to regenerate client

Key File Locations

Purpose	Path
Prisma singleton	`src/lib/db.ts`
All Zod schemas	`src/lib/validation.ts`
Response sanitization	`src/lib/api/sanitize.ts`
Session/auth	`src/lib/auth/session.ts`
Multi-server dedup	`src/lib/dedup/server-filter.ts`
Filter utilities	`src/lib/filters/build-where.ts`
Memory cache	`src/lib/cache/memory-cache.ts`
Rate limiter	`src/lib/rate-limit/rate-limiter.ts`
Test DB setup	`tests/setup/test-db.ts`
Test helpers/factories	`tests/setup/test-helpers.ts`
Session mocking	`tests/setup/mock-session.ts`