@cubis/foundry 0.3.10

package/Ai Agent Workflow/skills/nestjs-expert/references/secure-sessions.md

@@ -0,0 +1,56 @@
+# Secure Sessions (NestJS + Fastify)
+
+Use this guide when implementing cookie-based sessions for NestJS apps running with Fastify.
+
+## Session Baseline
+
+- Use `@fastify/cookie` and `@fastify/session`.
+- Register cookie plugin before session plugin.
+- Use a strong random session secret and rotate on schedule.
+- Keep cookie `httpOnly: true`.
+- Set `secure: true` in production.
+- Use explicit `sameSite` based on cross-site requirements.
+
+## Recommended Cookie Settings
+
+```ts
+cookie: {
+  httpOnly: true,
+  secure: process.env.NODE_ENV === 'production',
+  sameSite: 'lax',
+  path: '/',
+  maxAge: 1000 * 60 * 60 * 24, // 24h
+}
+```
+
+## Session Lifecycle
+
+1. Regenerate session ID at login to prevent fixation.
+2. Store only minimum identity context in session.
+3. Clear session and cookie on logout.
+4. Enforce idle timeout and absolute timeout.
+
+## What to Store
+
+- `userId`
+- `organizationId`
+- `role`
+
+Do not store tokens, passwords, raw PII, or authorization policy blobs.
+
+## CSRF and State-Changing Routes
+
+- Enable CSRF protection for cookie-authenticated forms and mutation routes.
+- Validate origin and referer where applicable.
+- Require `POST/PUT/PATCH/DELETE` requests to pass CSRF checks.
+
+## Operational Controls
+
+- Log auth/session failures with redaction.
+- Alert on unusual session churn and repeated invalid signatures.
+- Keep server clocks synchronized to avoid expiry drift.
+
+## Related
+
+- `references/authentication.md`
+- `references/services-di.md`

package/Ai Agent Workflow/skills/nestjs-expert/references/services-di.md

@@ -0,0 +1,143 @@
+# Services & Dependency Injection
+
+> Reference for: NestJS Expert
+> Load when: Creating services, dependency injection, providers
+
+## Service Pattern
+
+```typescript
+import { Injectable, Logger, NotFoundException, ConflictException } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+
+@Injectable()
+export class UsersService {
+  private readonly logger = new Logger(UsersService.name);
+
+  constructor(
+    @InjectRepository(User)
+    private readonly repo: Repository<User>,
+    private readonly emailService: EmailService,
+  ) {}
+
+  async create(dto: CreateUserDto): Promise<User> {
+    try {
+      const user = this.repo.create(dto);
+      const saved = await this.repo.save(user);
+      await this.emailService.sendWelcome(saved.email);
+      return saved;
+    } catch (error) {
+      if (error.code === '23505') {
+        throw new ConflictException('Email already exists');
+      }
+      this.logger.error(`Failed to create user: ${error.message}`);
+      throw error;
+    }
+  }
+
+  async findOne(id: string): Promise<User> {
+    const user = await this.repo.findOne({ where: { id } });
+    if (!user) {
+      throw new NotFoundException(`User ${id} not found`);
+    }
+    return user;
+  }
+
+  async update(id: string, dto: UpdateUserDto): Promise<User> {
+    const user = await this.findOne(id);
+    Object.assign(user, dto);
+    return this.repo.save(user);
+  }
+
+  async remove(id: string): Promise<void> {
+    const result = await this.repo.delete(id);
+    if (result.affected === 0) {
+      throw new NotFoundException(`User ${id} not found`);
+    }
+  }
+}
+```
+
+## Module with Providers
+
+```typescript
+@Module({
+  imports: [TypeOrmModule.forFeature([User])],
+  controllers: [UsersController],
+  providers: [UsersService],
+  exports: [UsersService],  // Make available to other modules
+})
+export class UsersModule {}
+```
+
+## Custom Providers
+
+```typescript
+// Value provider
+{ provide: 'API_KEY', useValue: process.env.API_KEY }
+
+// Factory provider
+{
+  provide: 'CONFIG',
+  useFactory: (configService: ConfigService) => ({
+    apiUrl: configService.get('API_URL'),
+  }),
+  inject: [ConfigService],
+}
+
+// Class provider
+{ provide: LoggerService, useClass: CustomLoggerService }
+
+// Async factory
+{
+  provide: 'DATABASE_CONNECTION',
+  useFactory: async () => {
+    const connection = await createConnection();
+    return connection;
+  },
+}
+```
+
+## Injection Patterns
+
+```typescript
+// Constructor injection (preferred)
+constructor(private readonly usersService: UsersService) {}
+
+// Token injection
+constructor(@Inject('API_KEY') private apiKey: string) {}
+
+// Optional injection
+constructor(@Optional() private readonly cache?: CacheService) {}
+
+// Property injection (use sparingly)
+@Inject() private readonly logger: Logger;
+```
+
+## Scope
+
+```typescript
+// Default: Singleton (shared across app)
+@Injectable()
+export class SharedService {}
+
+// Request-scoped: New instance per request
+@Injectable({ scope: Scope.REQUEST })
+export class RequestService {
+  constructor(@Inject(REQUEST) private request: Request) {}
+}
+
+// Transient: New instance every injection
+@Injectable({ scope: Scope.TRANSIENT })
+export class HelperService {}
+```
+
+## Quick Reference
+
+| Pattern | Use When |
+|---------|----------|
+| Constructor DI | Most cases (recommended) |
+| `@Inject(token)` | Non-class tokens |
+| `@Optional()` | Optional dependency |
+| Factory provider | Dynamic configuration |
+| Scope.REQUEST | Per-request state |

package/Ai Agent Workflow/skills/nestjs-expert/references/strangler-fig-pattern.md

@@ -0,0 +1,47 @@
+# Strangler Fig Pattern
+
+Use this pattern to migrate from legacy Express routes to NestJS incrementally without a big-bang rewrite.
+
+## Goal
+
+Move route groups from legacy to NestJS in controlled slices while preserving behavior and uptime.
+
+## Migration Flow
+
+1. Keep legacy and NestJS running side by side.
+2. Add an edge router that forwards requests by route prefix.
+3. Migrate one bounded module at a time.
+4. Verify parity with contract tests and traffic shadowing.
+5. Shift traffic gradually.
+6. Remove legacy routes after sustained stability.
+
+## Routing Strategy
+
+- Legacy example: `/api/users/*` -> Express
+- New module: `/api/v2/users/*` -> NestJS
+- Optional cutover: keep same route and switch backend behind gateway flags
+
+## Safety Gates Per Slice
+
+- Contract tests pass against both implementations.
+- Error rates and latency remain within agreed SLO bounds.
+- Rollback is immediate by flipping router rules.
+- Data migrations are idempotent and reversible when possible.
+
+## Common Risks
+
+- Hidden shared state in legacy middleware.
+- Inconsistent auth/session behavior across stacks.
+- Schema drift between old and new DTO/validation layers.
+
+## Required Controls
+
+- Single source of truth for auth/session policy.
+- Structured logging with correlation IDs across both paths.
+- Feature flags for route-level cutovers.
+- Post-cutover monitoring window before route deletion.
+
+## Related
+
+- `references/migration-from-express.md`
+- `references/authentication.md`

package/Ai Agent Workflow/skills/nestjs-expert/references/testing-patterns.md

@@ -0,0 +1,189 @@
+# Testing Patterns
+
+> Reference for: NestJS Expert
+> Load when: Writing tests, Jest, mocking, E2E testing
+
+## Unit Test Setup
+
+```typescript
+import { Test, TestingModule } from '@nestjs/testing';
+import { getRepositoryToken } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { NotFoundException } from '@nestjs/common';
+
+describe('UsersService', () => {
+  let service: UsersService;
+  let repo: jest.Mocked<Repository<User>>;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        UsersService,
+        {
+          provide: getRepositoryToken(User),
+          useValue: {
+            create: jest.fn(),
+            save: jest.fn(),
+            findOne: jest.fn(),
+            delete: jest.fn(),
+          },
+        },
+      ],
+    }).compile();
+
+    service = module.get(UsersService);
+    repo = module.get(getRepositoryToken(User));
+  });
+
+  afterEach(() => jest.clearAllMocks());
+});
+```
+
+## Service Tests
+
+```typescript
+describe('create', () => {
+  it('should create user', async () => {
+    const dto = { email: 'test@test.com', password: 'pass', name: 'Test' };
+    const user = { id: '1', ...dto };
+
+    repo.create.mockReturnValue(user as User);
+    repo.save.mockResolvedValue(user as User);
+
+    const result = await service.create(dto);
+
+    expect(repo.create).toHaveBeenCalledWith(dto);
+    expect(repo.save).toHaveBeenCalledWith(user);
+    expect(result).toEqual(user);
+  });
+});
+
+describe('findOne', () => {
+  it('should return user', async () => {
+    const user = { id: '1', email: 'test@test.com' };
+    repo.findOne.mockResolvedValue(user as User);
+
+    const result = await service.findOne('1');
+    expect(result).toEqual(user);
+  });
+
+  it('should throw NotFoundException', async () => {
+    repo.findOne.mockResolvedValue(null);
+    await expect(service.findOne('1')).rejects.toThrow(NotFoundException);
+  });
+});
+```
+
+## Controller Tests
+
+```typescript
+describe('UsersController', () => {
+  let controller: UsersController;
+  let service: jest.Mocked<UsersService>;
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      controllers: [UsersController],
+      providers: [
+        {
+          provide: UsersService,
+          useValue: {
+            create: jest.fn(),
+            findOne: jest.fn(),
+          },
+        },
+      ],
+    }).compile();
+
+    controller = module.get(UsersController);
+    service = module.get(UsersService);
+  });
+
+  it('should create user', async () => {
+    const dto = { email: 'test@test.com', password: 'pass', name: 'Test' };
+    const user = { id: '1', ...dto };
+    service.create.mockResolvedValue(user as User);
+
+    const result = await controller.create(dto);
+    expect(result).toEqual(user);
+  });
+});
+```
+
+## E2E Tests
+
+```typescript
+import { INestApplication } from '@nestjs/common';
+import * as request from 'supertest';
+
+describe('UsersController (e2e)', () => {
+  let app: INestApplication;
+  let authToken: string;
+
+  beforeAll(async () => {
+    const moduleFixture = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = moduleFixture.createNestApplication();
+    app.useGlobalPipes(new ValidationPipe({ whitelist: true }));
+    await app.init();
+
+    // Get auth token
+    const response = await request(app.getHttpServer())
+      .post('/auth/login')
+      .send({ email: 'test@test.com', password: 'password' });
+    authToken = response.body.access_token;
+  });
+
+  afterAll(() => app.close());
+
+  it('/users (POST)', () => {
+    return request(app.getHttpServer())
+      .post('/users')
+      .set('Authorization', `Bearer ${authToken}`)
+      .send({ email: 'new@test.com', password: 'Test1234', name: 'New' })
+      .expect(201)
+      .expect((res) => {
+        expect(res.body.email).toBe('new@test.com');
+      });
+  });
+
+  it('/users/:id (GET) - 404', () => {
+    return request(app.getHttpServer())
+      .get('/users/nonexistent-id')
+      .set('Authorization', `Bearer ${authToken}`)
+      .expect(404);
+  });
+});
+```
+
+## Mock Factory
+
+```typescript
+export const createMockRepository = <T>() => ({
+  create: jest.fn(),
+  save: jest.fn(),
+  find: jest.fn(),
+  findOne: jest.fn(),
+  update: jest.fn(),
+  delete: jest.fn(),
+  createQueryBuilder: jest.fn(() => ({
+    where: jest.fn().mockReturnThis(),
+    andWhere: jest.fn().mockReturnThis(),
+    getOne: jest.fn(),
+    getMany: jest.fn(),
+  })),
+});
+```
+
+## Quick Reference
+
+| Pattern | Use Case |
+|---------|----------|
+| `Test.createTestingModule()` | Create test module |
+| `jest.fn()` | Mock function |
+| `mockResolvedValue()` | Mock async return |
+| `mockReturnValue()` | Mock sync return |
+| `supertest` | E2E HTTP testing |
+| `beforeAll` / `afterAll` | Setup/teardown |

package/Ai Agent Workflow/skills/next-best-practices/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: next-best-practices
+description: "Rulebook for reviewing/generating Next.js code against Vercel best practices (conventions, RSC boundaries, async APIs, metadata, bundling). Not a migration or feature-implementation skill by itself."
+user-invocable: false
+---
+
+# Next.js Best Practices
+
+Apply these rules when writing or reviewing Next.js code.
+
+## File Conventions
+
+See [file-conventions.md](./file-conventions.md) for:
+- Project structure and special files
+- Route segments (dynamic, catch-all, groups)
+- Parallel and intercepting routes
+- Middleware rename in v16 (middleware → proxy)
+
+## RSC Boundaries
+
+Detect invalid React Server Component patterns.
+
+See [rsc-boundaries.md](./rsc-boundaries.md) for:
+- Async client component detection (invalid)
+- Non-serializable props detection
+- Server Action exceptions
+
+## Async Patterns
+
+Next.js 15+ async API changes.
+
+See [async-patterns.md](./async-patterns.md) for:
+- Async `params` and `searchParams`
+- Async `cookies()` and `headers()`
+- Migration codemod
+
+## Runtime Selection
+
+See [runtime-selection.md](./runtime-selection.md) for:
+- Default to Node.js runtime
+- When Edge runtime is appropriate
+
+## Directives
+
+See [directives.md](./directives.md) for:
+- `'use client'`, `'use server'` (React)
+- `'use cache'` (Next.js)
+
+## Functions
+
+See [functions.md](./functions.md) for:
+- Navigation hooks: `useRouter`, `usePathname`, `useSearchParams`, `useParams`
+- Server functions: `cookies`, `headers`, `draftMode`, `after`
+- Generate functions: `generateStaticParams`, `generateMetadata`
+
+## Error Handling
+
+See [error-handling.md](./error-handling.md) for:
+- `error.tsx`, `global-error.tsx`, `not-found.tsx`
+- `redirect`, `permanentRedirect`, `notFound`
+- `forbidden`, `unauthorized` (auth errors)
+- `unstable_rethrow` for catch blocks
+
+## Data Patterns
+
+See [data-patterns.md](./data-patterns.md) for:
+- Server Components vs Server Actions vs Route Handlers
+- Avoiding data waterfalls (`Promise.all`, Suspense, preload)
+- Client component data fetching
+
+## Route Handlers
+
+See [route-handlers.md](./route-handlers.md) for:
+- `route.ts` basics
+- GET handler conflicts with `page.tsx`
+- Environment behavior (no React DOM)
+- When to use vs Server Actions
+
+## Metadata & OG Images
+
+See [metadata.md](./metadata.md) for:
+- Static and dynamic metadata
+- `generateMetadata` function
+- OG image generation with `next/og`
+- File-based metadata conventions
+
+## Image Optimization
+
+See [image.md](./image.md) for:
+- Always use `next/image` over `<img>`
+- Remote images configuration
+- Responsive `sizes` attribute
+- Blur placeholders
+- Priority loading for LCP
+
+## Font Optimization
+
+See [font.md](./font.md) for:
+- `next/font` setup
+- Google Fonts, local fonts
+- Tailwind CSS integration
+- Preloading subsets
+
+## Bundling
+
+See [bundling.md](./bundling.md) for:
+- Server-incompatible packages
+- CSS imports (not link tags)
+- Polyfills (already included)
+- ESM/CommonJS issues
+- Bundle analysis
+
+## Scripts
+
+See [scripts.md](./scripts.md) for:
+- `next/script` vs native script tags
+- Inline scripts need `id`
+- Loading strategies
+- Google Analytics with `@next/third-parties`
+
+## Hydration Errors
+
+See [hydration-error.md](./hydration-error.md) for:
+- Common causes (browser APIs, dates, invalid HTML)
+- Debugging with error overlay
+- Fixes for each cause
+
+## Suspense Boundaries
+
+See [suspense-boundaries.md](./suspense-boundaries.md) for:
+- CSR bailout with `useSearchParams` and `usePathname`
+- Which hooks require Suspense boundaries
+
+## Parallel & Intercepting Routes
+
+See [parallel-routes.md](./parallel-routes.md) for:
+- Modal patterns with `@slot` and `(.)` interceptors
+- `default.tsx` for fallbacks
+- Closing modals correctly with `router.back()`
+
+## Self-Hosting
+
+See [self-hosting.md](./self-hosting.md) for:
+- `output: 'standalone'` for Docker
+- Cache handlers for multi-instance ISR
+- What works vs needs extra setup
+
+## Debug Tricks
+
+See [debug-tricks.md](./debug-tricks.md) for:
+- MCP endpoint for AI-assisted debugging
+- Rebuild specific routes with `--debug-build-paths`
+

package/Ai Agent Workflow/skills/next-best-practices/async-patterns.md

@@ -0,0 +1,87 @@
+# Async Patterns
+
+In Next.js 15+, `params`, `searchParams`, `cookies()`, and `headers()` are asynchronous.
+
+## Async Params and SearchParams
+
+Always type them as `Promise<...>` and await them.
+
+### Pages and Layouts
+
+```tsx
+type Props = { params: Promise<{ slug: string }> }
+
+export default async function Page({ params }: Props) {
+  const { slug } = await params
+}
+```
+
+### Route Handlers
+
+```tsx
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params
+}
+```
+
+### SearchParams
+
+```tsx
+type Props = {
+  params: Promise<{ slug: string }>
+  searchParams: Promise<{ query?: string }>
+}
+
+export default async function Page({ params, searchParams }: Props) {
+  const { slug } = await params
+  const { query } = await searchParams
+}
+```
+
+### Synchronous Components
+
+Use `React.use()` for non-async components:
+
+```tsx
+import { use } from 'react'
+
+type Props = { params: Promise<{ slug: string }> }
+
+export default function Page({ params }: Props) {
+  const { slug } = use(params)
+}
+```
+
+### generateMetadata
+
+```tsx
+type Props = { params: Promise<{ slug: string }> }
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug } = await params
+  return { title: slug }
+}
+```
+
+## Async Cookies and Headers
+
+```tsx
+import { cookies, headers } from 'next/headers'
+
+export default async function Page() {
+  const cookieStore = await cookies()
+  const headersList = await headers()
+
+  const theme = cookieStore.get('theme')
+  const userAgent = headersList.get('user-agent')
+}
+```
+
+## Migration Codemod
+
+```bash
+npx @next/codemod@latest next-async-request-api .
+```