@heyai-rules/pilo-masterkit 1.2.2 → 3.1.0

package/.agent/skills/nestjs-patterns/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: nestjs-patterns
+description: NestJS architecture patterns for modules, controllers, providers, DTO validation, guards, interceptors, config, and production-grade TypeScript backends.
+origin: ECC
+---
+
+# NestJS Development Patterns
+
+Production-grade NestJS patterns for modular TypeScript backends.
+
+## When to Activate
+
+- Building NestJS APIs or services
+- Structuring modules, controllers, and providers
+- Adding DTO validation, guards, interceptors, or exception filters
+- Configuring environment-aware settings and database integrations
+- Testing NestJS units or HTTP endpoints
+
+## Project Structure
+
+```text
+src/
+├── app.module.ts
+├── main.ts
+├── common/
+│   ├── filters/
+│   ├── guards/
+│   ├── interceptors/
+│   └── pipes/
+├── config/
+│   ├── configuration.ts
+│   └── validation.ts
+├── modules/
+│   ├── auth/
+│   │   ├── auth.controller.ts
+│   │   ├── auth.module.ts
+│   │   ├── auth.service.ts
+│   │   ├── dto/
+│   │   ├── guards/
+│   │   └── strategies/
+│   └── users/
+│       ├── dto/
+│       ├── entities/
+│       ├── users.controller.ts
+│       ├── users.module.ts
+│       └── users.service.ts
+└── prisma/ or database/
+```
+
+- Keep domain code inside feature modules.
+- Put cross-cutting filters, decorators, guards, and interceptors in `common/`.
+- Keep DTOs close to the module that owns them.
+
+## Bootstrap and Global Validation
+
+```ts
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule, { bufferLogs: true });
+
+  app.useGlobalPipes(
+    new ValidationPipe({
+      whitelist: true,
+      forbidNonWhitelisted: true,
+      transform: true,
+      transformOptions: { enableImplicitConversion: true },
+    }),
+  );
+
+  app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)));
+  app.useGlobalFilters(new HttpExceptionFilter());
+
+  await app.listen(process.env.PORT ?? 3000);
+}
+bootstrap();
+```
+
+- Always enable `whitelist` and `forbidNonWhitelisted` on public APIs.
+- Prefer one global validation pipe instead of repeating validation config per route.
+
+## Modules, Controllers, and Providers
+
+```ts
+@Module({
+  controllers: [UsersController],
+  providers: [UsersService],
+  exports: [UsersService],
+})
+export class UsersModule {}
+
+@Controller('users')
+export class UsersController {
+  constructor(private readonly usersService: UsersService) {}
+
+  @Get(':id')
+  getById(@Param('id', ParseUUIDPipe) id: string) {
+    return this.usersService.getById(id);
+  }
+
+  @Post()
+  create(@Body() dto: CreateUserDto) {
+    return this.usersService.create(dto);
+  }
+}
+
+@Injectable()
+export class UsersService {
+  constructor(private readonly usersRepo: UsersRepository) {}
+
+  async create(dto: CreateUserDto) {
+    return this.usersRepo.create(dto);
+  }
+}
+```
+
+- Controllers should stay thin: parse HTTP input, call a provider, return response DTOs.
+- Put business logic in injectable services, not controllers.
+- Export only the providers other modules genuinely need.
+
+## DTOs and Validation
+
+```ts
+export class CreateUserDto {
+  @IsEmail()
+  email!: string;
+
+  @IsString()
+  @Length(2, 80)
+  name!: string;
+
+  @IsOptional()
+  @IsEnum(UserRole)
+  role?: UserRole;
+}
+```
+
+- Validate every request DTO with `class-validator`.
+- Use dedicated response DTOs or serializers instead of returning ORM entities directly.
+- Avoid leaking internal fields such as password hashes, tokens, or audit columns.
+
+## Auth, Guards, and Request Context
+
+```ts
+@UseGuards(JwtAuthGuard, RolesGuard)
+@Roles('admin')
+@Get('admin/report')
+getAdminReport(@Req() req: AuthenticatedRequest) {
+  return this.reportService.getForUser(req.user.id);
+}
+```
+
+- Keep auth strategies and guards module-local unless they are truly shared.
+- Encode coarse access rules in guards, then do resource-specific authorization in services.
+- Prefer explicit request types for authenticated request objects.
+
+## Exception Filters and Error Shape
+
+```ts
+@Catch()
+export class HttpExceptionFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    const response = host.switchToHttp().getResponse<Response>();
+    const request = host.switchToHttp().getRequest<Request>();
+
+    if (exception instanceof HttpException) {
+      return response.status(exception.getStatus()).json({
+        path: request.url,
+        error: exception.getResponse(),
+      });
+    }
+
+    return response.status(500).json({
+      path: request.url,
+      error: 'Internal server error',
+    });
+  }
+}
+```
+
+- Keep one consistent error envelope across the API.
+- Throw framework exceptions for expected client errors; log and wrap unexpected failures centrally.
+
+## Config and Environment Validation
+
+```ts
+ConfigModule.forRoot({
+  isGlobal: true,
+  load: [configuration],
+  validate: validateEnv,
+});
+```
+
+- Validate env at boot, not lazily at first request.
+- Keep config access behind typed helpers or config services.
+- Split dev/staging/prod concerns in config factories instead of branching throughout feature code.
+
+## Persistence and Transactions
+
+- Keep repository / ORM code behind providers that speak domain language.
+- For Prisma or TypeORM, isolate transactional workflows in services that own the unit of work.
+- Do not let controllers coordinate multi-step writes directly.
+
+## Testing
+
+```ts
+describe('UsersController', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [UsersModule],
+    }).compile();
+
+    app = moduleRef.createNestApplication();
+    app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
+    await app.init();
+  });
+});
+```
+
+- Unit test providers in isolation with mocked dependencies.
+- Add request-level tests for guards, validation pipes, and exception filters.
+- Reuse the same global pipes/filters in tests that you use in production.
+
+## Production Defaults
+
+- Enable structured logging and request correlation ids.
+- Terminate on invalid env/config instead of booting partially.
+- Prefer async provider initialization for DB/cache clients with explicit health checks.
+- Keep background jobs and event consumers in their own modules, not inside HTTP controllers.
+- Make rate limiting, auth, and audit logging explicit for public endpoints.

package/.agent/skills/nextjs-turbopack/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: nextjs-turbopack
+description: Next.js 16+ and Turbopack — incremental bundling, FS caching, dev speed, and when to use Turbopack vs webpack.
+origin: ECC
+---
+
+# Next.js and Turbopack
+
+Next.js 16+ uses Turbopack by default for local development: an incremental bundler written in Rust that significantly speeds up dev startup and hot updates.
+
+## When to Use
+
+- **Turbopack (default dev)**: Use for day-to-day development. Faster cold start and HMR, especially in large apps.
+- **Webpack (legacy dev)**: Use only if you hit a Turbopack bug or rely on a webpack-only plugin in dev. Disable with `--webpack` (or `--no-turbopack` depending on your Next.js version; check the docs for your release).
+- **Production**: Production build behavior (`next build`) may use Turbopack or webpack depending on Next.js version; check the official Next.js docs for your version.
+
+Use when: developing or debugging Next.js 16+ apps, diagnosing slow dev startup or HMR, or optimizing production bundles.
+
+## How It Works
+
+- **Turbopack**: Incremental bundler for Next.js dev. Uses file-system caching so restarts are much faster (e.g. 5–14x on large projects).
+- **Default in dev**: From Next.js 16, `next dev` runs with Turbopack unless disabled.
+- **File-system caching**: Restarts reuse previous work; cache is typically under `.next`; no extra config needed for basic use.
+- **Bundle Analyzer (Next.js 16.1+)**: Experimental Bundle Analyzer to inspect output and find heavy dependencies; enable via config or experimental flag (see Next.js docs for your version).
+
+## Examples
+
+### Commands
+
+```bash
+next dev
+next build
+next start
+```
+
+### Usage
+
+Run `next dev` for local development with Turbopack. Use the Bundle Analyzer (see Next.js docs) to optimize code-splitting and trim large dependencies. Prefer App Router and server components where possible.
+
+## Best Practices
+
+- Stay on a recent Next.js 16.x for stable Turbopack and caching behavior.
+- If dev is slow, ensure you're on Turbopack (default) and that the cache isn't being cleared unnecessarily.
+- For production bundle size issues, use the official Next.js bundle analysis tooling for your version.

package/.agent/skills/nutrient-document-processing/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: nutrient-document-processing
+description: Process, convert, OCR, extract, redact, sign, and fill documents using the Nutrient DWS API. Works with PDFs, DOCX, XLSX, PPTX, HTML, and images.
+origin: ECC
+---
+
+# Nutrient Document Processing
+
+> **Note:** This skill integrates with the Nutrient commercial API. Review their terms before use.
+
+Process documents with the [Nutrient DWS Processor API](https://www.nutrient.io/api/). Convert formats, extract text and tables, OCR scanned documents, redact PII, add watermarks, digitally sign, and fill PDF forms.
+
+## Setup
+
+Get a free API key at **[nutrient.io](https://dashboard.nutrient.io/sign_up/?product=processor)**
+
+```bash
+export NUTRIENT_API_KEY="pdf_live_..."
+```
+
+All requests go to `https://api.nutrient.io/build` as multipart POST with an `instructions` JSON field.
+
+## Operations
+
+### Convert Documents
+
+```bash
+# DOCX to PDF
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F "document.docx=@document.docx" \
+  -F 'instructions={"parts":[{"file":"document.docx"}]}' \
+  -o output.pdf
+
+# PDF to DOCX
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F "document.pdf=@document.pdf" \
+  -F 'instructions={"parts":[{"file":"document.pdf"}],"output":{"type":"docx"}}' \
+  -o output.docx
+
+# HTML to PDF
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F "index.html=@index.html" \
+  -F 'instructions={"parts":[{"html":"index.html"}]}' \
+  -o output.pdf
+```
+
+Supported inputs: PDF, DOCX, XLSX, PPTX, DOC, XLS, PPT, PPS, PPSX, ODT, RTF, HTML, JPG, PNG, TIFF, HEIC, GIF, WebP, SVG, TGA, EPS.
+
+### Extract Text and Data
+
+```bash
+# Extract plain text
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F "document.pdf=@document.pdf" \
+  -F 'instructions={"parts":[{"file":"document.pdf"}],"output":{"type":"text"}}' \
+  -o output.txt
+
+# Extract tables as Excel
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F "document.pdf=@document.pdf" \
+  -F 'instructions={"parts":[{"file":"document.pdf"}],"output":{"type":"xlsx"}}' \
+  -o tables.xlsx
+```
+
+### OCR Scanned Documents
+
+```bash
+# OCR to searchable PDF (supports 100+ languages)
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F "scanned.pdf=@scanned.pdf" \
+  -F 'instructions={"parts":[{"file":"scanned.pdf"}],"actions":[{"type":"ocr","language":"english"}]}' \
+  -o searchable.pdf
+```
+
+Languages: Supports 100+ languages via ISO 639-2 codes (e.g., `eng`, `deu`, `fra`, `spa`, `jpn`, `kor`, `chi_sim`, `chi_tra`, `ara`, `hin`, `rus`). Full language names like `english` or `german` also work. See the [complete OCR language table](https://www.nutrient.io/guides/document-engine/ocr/language-support/) for all supported codes.
+
+### Redact Sensitive Information
+
+```bash
+# Pattern-based (SSN, email)
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F "document.pdf=@document.pdf" \
+  -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"redaction","strategy":"preset","strategyOptions":{"preset":"social-security-number"}},{"type":"redaction","strategy":"preset","strategyOptions":{"preset":"email-address"}}]}' \
+  -o redacted.pdf
+
+# Regex-based
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F "document.pdf=@document.pdf" \
+  -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"redaction","strategy":"regex","strategyOptions":{"regex":"\\b[A-Z]{2}\\d{6}\\b"}}]}' \
+  -o redacted.pdf
+```
+
+Presets: `social-security-number`, `email-address`, `credit-card-number`, `international-phone-number`, `north-american-phone-number`, `date`, `time`, `url`, `ipv4`, `ipv6`, `mac-address`, `us-zip-code`, `vin`.
+
+### Add Watermarks
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F "document.pdf=@document.pdf" \
+  -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"watermark","text":"CONFIDENTIAL","fontSize":72,"opacity":0.3,"rotation":-45}]}' \
+  -o watermarked.pdf
+```
+
+### Digital Signatures
+
+```bash
+# Self-signed CMS signature
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F "document.pdf=@document.pdf" \
+  -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"sign","signatureType":"cms"}]}' \
+  -o signed.pdf
+```
+
+### Fill PDF Forms
+
+```bash
+curl -X POST https://api.nutrient.io/build \
+  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
+  -F "form.pdf=@form.pdf" \
+  -F 'instructions={"parts":[{"file":"form.pdf"}],"actions":[{"type":"fillForm","formFields":{"name":"Jane Smith","email":"jane@example.com","date":"2026-02-06"}}]}' \
+  -o filled.pdf
+```
+
+## MCP Server (Alternative)
+
+For native tool integration, use the MCP server instead of curl:
+
+```json
+{
+  "mcpServers": {
+    "nutrient-dws": {
+      "command": "npx",
+      "args": ["-y", "@nutrient-sdk/dws-mcp-server"],
+      "env": {
+        "NUTRIENT_DWS_API_KEY": "YOUR_API_KEY",
+        "SANDBOX_PATH": "/path/to/working/directory"
+      }
+    }
+  }
+}
+```
+
+## When to Use
+
+- Converting documents between formats (PDF, DOCX, XLSX, PPTX, HTML, images)
+- Extracting text, tables, or key-value pairs from PDFs
+- OCR on scanned documents or images
+- Redacting PII before sharing documents
+- Adding watermarks to drafts or confidential documents
+- Digitally signing contracts or agreements
+- Filling PDF forms programmatically
+
+## Links
+
+- [API Playground](https://dashboard.nutrient.io/processor-api/playground/)
+- [Full API Docs](https://www.nutrient.io/guides/dws-processor/)
+- [npm MCP Server](https://www.npmjs.com/package/@nutrient-sdk/dws-mcp-server)

package/.agent/skills/nuxt4-patterns/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: nuxt4-patterns
+description: Nuxt 4 app patterns for hydration safety, performance, route rules, lazy loading, and SSR-safe data fetching with useFetch and useAsyncData.
+origin: ECC
+---
+
+# Nuxt 4 Patterns
+
+Use when building or debugging Nuxt 4 apps with SSR, hybrid rendering, route rules, or page-level data fetching.
+
+## When to Activate
+
+- Hydration mismatches between server HTML and client state
+- Route-level rendering decisions such as prerender, SWR, ISR, or client-only sections
+- Performance work around lazy loading, lazy hydration, or payload size
+- Page or component data fetching with `useFetch`, `useAsyncData`, or `$fetch`
+- Nuxt routing issues tied to route params, middleware, or SSR/client differences
+
+## Hydration Safety
+
+- Keep the first render deterministic. Do not put `Date.now()`, `Math.random()`, browser-only APIs, or storage reads directly into SSR-rendered template state.
+- Move browser-only logic behind `onMounted()`, `import.meta.client`, `ClientOnly`, or a `.client.vue` component when the server cannot produce the same markup.
+- Use Nuxt's `useRoute()` composable, not the one from `vue-router`.
+- Do not use `route.fullPath` to drive SSR-rendered markup. URL fragments are client-only, which can create hydration mismatches.
+- Treat `ssr: false` as an escape hatch for truly browser-only areas, not a default fix for mismatches.
+
+## Data Fetching
+
+- Prefer `await useFetch()` for SSR-safe API reads in pages and components. It forwards server-fetched data into the Nuxt payload and avoids a second fetch on hydration.
+- Use `useAsyncData()` when the fetcher is not a simple `$fetch()` call, when you need a custom key, or when you are composing multiple async sources.
+- Give `useAsyncData()` a stable key for cache reuse and predictable refresh behavior.
+- Keep `useAsyncData()` handlers side-effect free. They can run during SSR and hydration.
+- Use `$fetch()` for user-triggered writes or client-only actions, not top-level page data that should be hydrated from SSR.
+- Use `lazy: true`, `useLazyFetch()`, or `useLazyAsyncData()` for non-critical data that should not block navigation. Handle `status === 'pending'` in the UI.
+- Use `server: false` only for data that is not needed for SEO or the first paint.
+- Trim payload size with `pick` and prefer shallower payloads when deep reactivity is unnecessary.
+
+```ts
+const route = useRoute()
+
+const { data: article, status, error, refresh } = await useAsyncData(
+  () => `article:${route.params.slug}`,
+  () => $fetch(`/api/articles/${route.params.slug}`),
+)
+
+const { data: comments } = await useFetch(`/api/articles/${route.params.slug}/comments`, {
+  lazy: true,
+  server: false,
+})
+```
+
+## Route Rules
+
+Prefer `routeRules` in `nuxt.config.ts` for rendering and caching strategy:
+
+```ts
+export default defineNuxtConfig({
+  routeRules: {
+    '/': { prerender: true },
+    '/products/**': { swr: 3600 },
+    '/blog/**': { isr: true },
+    '/admin/**': { ssr: false },
+    '/api/**': { cache: { maxAge: 60 * 60 } },
+  },
+})
+```
+
+- `prerender`: static HTML at build time
+- `swr`: serve cached content and revalidate in the background
+- `isr`: incremental static regeneration on supported platforms
+- `ssr: false`: client-rendered route
+- `cache` or `redirect`: Nitro-level response behavior
+
+Pick route rules per route group, not globally. Marketing pages, catalogs, dashboards, and APIs usually need different strategies.
+
+## Lazy Loading and Performance
+
+- Nuxt already code-splits pages by route. Keep route boundaries meaningful before micro-optimizing component splits.
+- Use the `Lazy` prefix to dynamically import non-critical components.
+- Conditionally render lazy components with `v-if` so the chunk is not loaded until the UI actually needs it.
+- Use lazy hydration for below-the-fold or non-critical interactive UI.
+
+```vue
+<template>
+  <LazyRecommendations v-if="showRecommendations" />
+  <LazyProductGallery hydrate-on-visible />
+</template>
+```
+
+- For custom strategies, use `defineLazyHydrationComponent()` with a visibility or idle strategy.
+- Nuxt lazy hydration works on single-file components. Passing new props to a lazily hydrated component will trigger hydration immediately.
+- Use `NuxtLink` for internal navigation so Nuxt can prefetch route components and generated payloads.
+
+## Review Checklist
+
+- First SSR render and hydrated client render produce the same markup
+- Page data uses `useFetch` or `useAsyncData`, not top-level `$fetch`
+- Non-critical data is lazy and has explicit loading UI
+- Route rules match the page's SEO and freshness requirements
+- Heavy interactive islands are lazy-loaded or lazily hydrated