@ranimontagna/agent-toolkit 0.1.3 → 0.1.5

package/setup-agent-toolkit.sh

@@ -13,7 +13,7 @@ CLI_ENTRYPOINT="$SCRIPT_DIR/dist/bin/agent-toolkit.js"
 
 if [[ ! -f "$CLI_ENTRYPOINT" ]]; then
   echo "Agent Toolkit build not found: dist/bin/agent-toolkit.js" >&2
-  echo "Run npm install && npm run build, then run this command again." >&2
+  echo "Run pnpm install && pnpm run build, then run this command again." >&2
   exit 1
 fi
 

package/skills/backend/fastify-best-practices/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matteo Collina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/backend/fastify-best-practices/NOTICE.md

@@ -0,0 +1,11 @@
+# Attribution
+
+This skill is copied from Matteo Collina's public `mcollina/skills` repository.
+
+- Source: https://github.com/mcollina/skills/tree/main/skills/fastify
+- Imported from commit: `5b2a81354b6d10325da0db9decc9ce5ecc714138`
+- Upstream package name: `mcollina/fastify-best-practices`
+- License: MIT
+- Copyright: Copyright (c) 2026 Matteo Collina
+
+The upstream MIT license text is preserved in `LICENSE`.

package/skills/backend/fastify-best-practices/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: fastify-best-practices
+description: "Guides development of Fastify Node.js backend servers and REST APIs using TypeScript or JavaScript. Use when building, configuring, or debugging a Fastify application — including defining routes, implementing plugins, setting up JSON Schema validation, handling errors, optimising performance, managing authentication, configuring CORS and security headers, integrating databases, working with WebSockets, and deploying to production. Covers the full Fastify request lifecycle (hooks, serialization, logging with Pino) and TypeScript integration via strip types. Trigger terms: Fastify, Node.js server, REST API, API routes, backend framework, fastify.config, server.ts, app.ts."
+metadata:
+  tags: fastify, nodejs, typescript, backend, api, server, http
+---
+
+## When to use
+
+Use this skill when you need to:
+- Develop backend applications using Fastify
+- Implement Fastify plugins and route handlers
+- Get guidance on Fastify architecture and patterns
+- Use TypeScript with Fastify (strip types)
+- Implement testing with Fastify's inject method
+- Configure validation, serialization, and error handling
+
+## Quick Start
+
+A minimal, runnable Fastify server to get started immediately:
+
+```ts
+import Fastify from 'fastify'
+
+const app = Fastify({ logger: true })
+
+app.get('/health', async (request, reply) => {
+  return { status: 'ok' }
+})
+
+const start = async () => {
+  await app.listen({ port: 3000, host: '0.0.0.0' })
+}
+start()
+```
+
+## Recommended Reading Order for Common Scenarios
+
+- **New to Fastify?** Start with `plugins.md` → `routes.md` → `schemas.md`
+- **Adding authentication:** `plugins.md` → `hooks.md` → `authentication.md`
+- **Improving performance:** `schemas.md` → `serialization.md` → `performance.md`
+- **Setting up testing:** `routes.md` → `testing.md`
+- **Going to production:** `logging.md` → `configuration.md` → `deployment.md`
+
+## How to use
+
+Read individual rule files for detailed explanations and code examples:
+
+- [rules/plugins.md](rules/plugins.md) - Plugin development and encapsulation
+- [rules/routes.md](rules/routes.md) - Route organization and handlers
+- [rules/schemas.md](rules/schemas.md) - JSON Schema validation
+- [rules/error-handling.md](rules/error-handling.md) - Error handling patterns
+- [rules/hooks.md](rules/hooks.md) - Hooks and request lifecycle
+- [rules/authentication.md](rules/authentication.md) - Authentication and authorization
+- [rules/testing.md](rules/testing.md) - Testing with inject()
+- [rules/performance.md](rules/performance.md) - Performance optimization
+- [rules/logging.md](rules/logging.md) - Logging with Pino
+- [rules/typescript.md](rules/typescript.md) - TypeScript integration
+- [rules/decorators.md](rules/decorators.md) - Decorators and extensions
+- [rules/content-type.md](rules/content-type.md) - Content type parsing
+- [rules/serialization.md](rules/serialization.md) - Response serialization
+- [rules/cors-security.md](rules/cors-security.md) - CORS and security headers
+- [rules/websockets.md](rules/websockets.md) - WebSocket support
+- [rules/database.md](rules/database.md) - Database integration patterns
+- [rules/configuration.md](rules/configuration.md) - Application configuration
+- [rules/deployment.md](rules/deployment.md) - Production deployment
+- [rules/http-proxy.md](rules/http-proxy.md) - HTTP proxying and reply.from()
+
+## Core Principles
+
+- **Encapsulation**: Fastify's plugin system provides automatic encapsulation
+- **Schema-first**: Define schemas for validation and serialization
+- **Performance**: Fastify is optimized for speed; use its features correctly
+- **Async/await**: All handlers and hooks support async functions
+- **Minimal dependencies**: Prefer Fastify's built-in features and official plugins

package/skills/backend/fastify-best-practices/rules/authentication.md

@@ -0,0 +1,521 @@
+---
+name: authentication
+description: Authentication and authorization patterns in Fastify
+metadata:
+  tags: auth, jwt, session, oauth, security, authorization
+---
+
+# Authentication and Authorization
+
+## JWT Authentication with @fastify/jwt
+
+Use `@fastify/jwt` for JSON Web Token authentication:
+
+```typescript
+import Fastify from 'fastify';
+import fastifyJwt from '@fastify/jwt';
+
+const app = Fastify();
+
+app.register(fastifyJwt, {
+  secret: process.env.JWT_SECRET,
+  sign: {
+    expiresIn: '1h',
+  },
+});
+
+// Decorate request with authentication method
+app.decorate('authenticate', async function (request, reply) {
+  try {
+    await request.jwtVerify();
+  } catch (err) {
+    reply.code(401).send({ error: 'Unauthorized' });
+  }
+});
+
+// Login route
+app.post('/login', {
+  schema: {
+    body: {
+      type: 'object',
+      properties: {
+        email: { type: 'string', format: 'email' },
+        password: { type: 'string' },
+      },
+      required: ['email', 'password'],
+    },
+  },
+}, async (request, reply) => {
+  const { email, password } = request.body;
+  const user = await validateCredentials(email, password);
+
+  if (!user) {
+    return reply.code(401).send({ error: 'Invalid credentials' });
+  }
+
+  const token = app.jwt.sign({
+    id: user.id,
+    email: user.email,
+    role: user.role,
+  });
+
+  return { token };
+});
+
+// Protected route
+app.get('/profile', {
+  onRequest: [app.authenticate],
+}, async (request) => {
+  return { user: request.user };
+});
+```
+
+## Refresh Tokens
+
+Implement refresh token rotation:
+
+```typescript
+import fastifyJwt from '@fastify/jwt';
+import { randomBytes } from 'node:crypto';
+
+app.register(fastifyJwt, {
+  secret: process.env.JWT_SECRET,
+  sign: {
+    expiresIn: '15m', // Short-lived access tokens
+  },
+});
+
+// Store refresh tokens (use Redis in production)
+const refreshTokens = new Map<string, { userId: string; expires: number }>();
+
+app.post('/auth/login', async (request, reply) => {
+  const { email, password } = request.body;
+  const user = await validateCredentials(email, password);
+
+  if (!user) {
+    return reply.code(401).send({ error: 'Invalid credentials' });
+  }
+
+  const accessToken = app.jwt.sign({ id: user.id, role: user.role });
+  const refreshToken = randomBytes(32).toString('hex');
+
+  refreshTokens.set(refreshToken, {
+    userId: user.id,
+    expires: Date.now() + 7 * 24 * 60 * 60 * 1000, // 7 days
+  });
+
+  return { accessToken, refreshToken };
+});
+
+app.post('/auth/refresh', async (request, reply) => {
+  const { refreshToken } = request.body;
+  const stored = refreshTokens.get(refreshToken);
+
+  if (!stored || stored.expires < Date.now()) {
+    refreshTokens.delete(refreshToken);
+    return reply.code(401).send({ error: 'Invalid refresh token' });
+  }
+
+  // Delete old token (rotation)
+  refreshTokens.delete(refreshToken);
+
+  const user = await db.users.findById(stored.userId);
+  const accessToken = app.jwt.sign({ id: user.id, role: user.role });
+  const newRefreshToken = randomBytes(32).toString('hex');
+
+  refreshTokens.set(newRefreshToken, {
+    userId: user.id,
+    expires: Date.now() + 7 * 24 * 60 * 60 * 1000,
+  });
+
+  return { accessToken, refreshToken: newRefreshToken };
+});
+
+app.post('/auth/logout', async (request, reply) => {
+  const { refreshToken } = request.body;
+  refreshTokens.delete(refreshToken);
+  return { success: true };
+});
+```
+
+## Role-Based Access Control
+
+Implement RBAC with decorators:
+
+```typescript
+type Role = 'admin' | 'user' | 'moderator';
+
+// Create authorization decorator
+app.decorate('authorize', function (...allowedRoles: Role[]) {
+  return async (request, reply) => {
+    await request.jwtVerify();
+
+    const userRole = request.user.role as Role;
+    if (!allowedRoles.includes(userRole)) {
+      return reply.code(403).send({
+        error: 'Forbidden',
+        message: `Role '${userRole}' is not authorized for this resource`,
+      });
+    }
+  };
+});
+
+// Admin only route
+app.get('/admin/users', {
+  onRequest: [app.authorize('admin')],
+}, async (request) => {
+  return db.users.findAll();
+});
+
+// Admin or moderator
+app.delete('/posts/:id', {
+  onRequest: [app.authorize('admin', 'moderator')],
+}, async (request) => {
+  await db.posts.delete(request.params.id);
+  return { deleted: true };
+});
+```
+
+## Permission-Based Authorization
+
+Fine-grained permission checks:
+
+```typescript
+interface Permission {
+  resource: string;
+  action: 'create' | 'read' | 'update' | 'delete';
+}
+
+const rolePermissions: Record<string, Permission[]> = {
+  admin: [
+    { resource: '*', action: 'create' },
+    { resource: '*', action: 'read' },
+    { resource: '*', action: 'update' },
+    { resource: '*', action: 'delete' },
+  ],
+  user: [
+    { resource: 'posts', action: 'create' },
+    { resource: 'posts', action: 'read' },
+    { resource: 'comments', action: 'create' },
+    { resource: 'comments', action: 'read' },
+  ],
+};
+
+function hasPermission(role: string, resource: string, action: string): boolean {
+  const permissions = rolePermissions[role] || [];
+  return permissions.some(
+    (p) =>
+      (p.resource === '*' || p.resource === resource) &&
+      p.action === action
+  );
+}
+
+app.decorate('checkPermission', function (resource: string, action: string) {
+  return async (request, reply) => {
+    await request.jwtVerify();
+
+    if (!hasPermission(request.user.role, resource, action)) {
+      return reply.code(403).send({
+        error: 'Forbidden',
+        message: `Not allowed to ${action} ${resource}`,
+      });
+    }
+  };
+});
+
+// Usage
+app.post('/posts', {
+  onRequest: [app.checkPermission('posts', 'create')],
+}, createPostHandler);
+
+app.delete('/posts/:id', {
+  onRequest: [app.checkPermission('posts', 'delete')],
+}, deletePostHandler);
+```
+
+## API Key / Bearer Token Authentication
+
+Use `@fastify/bearer-auth` for API key and bearer token authentication:
+
+```typescript
+import bearerAuth from '@fastify/bearer-auth';
+
+const validKeys = new Set([process.env.API_KEY]);
+
+app.register(bearerAuth, {
+  keys: validKeys,
+  errorResponse: (err) => ({
+    error: 'Unauthorized',
+    message: 'Invalid API key',
+  }),
+});
+
+// All routes are now protected
+app.get('/api/data', async (request) => {
+  return { data: [] };
+});
+```
+
+For database-backed API keys with custom validation:
+
+```typescript
+import bearerAuth from '@fastify/bearer-auth';
+
+app.register(bearerAuth, {
+  auth: async (key, request) => {
+    const apiKey = await db.apiKeys.findByKey(key);
+
+    if (!apiKey || !apiKey.active) {
+      return false;
+    }
+
+    // Track usage (fire and forget)
+    db.apiKeys.recordUsage(apiKey.id, {
+      ip: request.ip,
+      timestamp: new Date(),
+    });
+
+    request.apiKey = apiKey;
+    return true;
+  },
+  errorResponse: (err) => ({
+    error: 'Unauthorized',
+    message: 'Invalid API key',
+  }),
+});
+```
+
+## OAuth 2.0 Integration
+
+Integrate with OAuth providers using @fastify/oauth2:
+
+```typescript
+import fastifyOauth2 from '@fastify/oauth2';
+
+app.register(fastifyOauth2, {
+  name: 'googleOAuth2',
+  scope: ['profile', 'email'],
+  credentials: {
+    client: {
+      id: process.env.GOOGLE_CLIENT_ID,
+      secret: process.env.GOOGLE_CLIENT_SECRET,
+    },
+  },
+  startRedirectPath: '/auth/google',
+  callbackUri: 'http://localhost:3000/auth/google/callback',
+  discovery: {
+    issuer: 'https://accounts.google.com',
+  },
+});
+
+app.get('/auth/google/callback', async (request, reply) => {
+  const { token } = await app.googleOAuth2.getAccessTokenFromAuthorizationCodeFlow(request);
+
+  // Fetch user info from Google
+  const userInfo = await fetch('https://www.googleapis.com/oauth2/v2/userinfo', {
+    headers: { Authorization: `Bearer ${token.access_token}` },
+  }).then((r) => r.json());
+
+  // Find or create user
+  let user = await db.users.findByEmail(userInfo.email);
+  if (!user) {
+    user = await db.users.create({
+      email: userInfo.email,
+      name: userInfo.name,
+      provider: 'google',
+      providerId: userInfo.id,
+    });
+  }
+
+  // Generate JWT
+  const jwt = app.jwt.sign({ id: user.id, role: user.role });
+
+  // Redirect to frontend with token
+  return reply.redirect(`/auth/success?token=${jwt}`);
+});
+```
+
+## Session-Based Authentication
+
+Use @fastify/session for session management:
+
+```typescript
+import fastifyCookie from '@fastify/cookie';
+import fastifySession from '@fastify/session';
+import RedisStore from 'connect-redis';
+import { createClient } from 'redis';
+
+const redisClient = createClient({ url: process.env.REDIS_URL });
+await redisClient.connect();
+
+app.register(fastifyCookie);
+app.register(fastifySession, {
+  secret: process.env.SESSION_SECRET,
+  store: new RedisStore({ client: redisClient }),
+  cookie: {
+    secure: process.env.NODE_ENV === 'production',
+    httpOnly: true,
+    maxAge: 24 * 60 * 60 * 1000, // 1 day
+  },
+});
+
+app.post('/login', async (request, reply) => {
+  const { email, password } = request.body;
+  const user = await validateCredentials(email, password);
+
+  if (!user) {
+    return reply.code(401).send({ error: 'Invalid credentials' });
+  }
+
+  request.session.userId = user.id;
+  request.session.role = user.role;
+
+  return { success: true };
+});
+
+app.decorate('requireSession', async function (request, reply) {
+  if (!request.session.userId) {
+    return reply.code(401).send({ error: 'Not authenticated' });
+  }
+});
+
+app.get('/profile', {
+  onRequest: [app.requireSession],
+}, async (request) => {
+  const user = await db.users.findById(request.session.userId);
+  return { user };
+});
+
+app.post('/logout', async (request, reply) => {
+  await request.session.destroy();
+  return { success: true };
+});
+```
+
+## Resource-Based Authorization
+
+Check ownership of resources:
+
+```typescript
+app.decorate('checkOwnership', function (getResourceOwnerId: (request) => Promise<string>) {
+  return async (request, reply) => {
+    const ownerId = await getResourceOwnerId(request);
+
+    if (ownerId !== request.user.id && request.user.role !== 'admin') {
+      return reply.code(403).send({
+        error: 'Forbidden',
+        message: 'You do not own this resource',
+      });
+    }
+  };
+});
+
+// Check post ownership
+app.put('/posts/:id', {
+  onRequest: [
+    app.authenticate,
+    app.checkOwnership(async (request) => {
+      const post = await db.posts.findById(request.params.id);
+      return post?.authorId;
+    }),
+  ],
+}, updatePostHandler);
+
+// Alternative: inline check
+app.put('/posts/:id', {
+  onRequest: [app.authenticate],
+}, async (request, reply) => {
+  const post = await db.posts.findById(request.params.id);
+
+  if (!post) {
+    return reply.code(404).send({ error: 'Post not found' });
+  }
+
+  if (post.authorId !== request.user.id && request.user.role !== 'admin') {
+    return reply.code(403).send({ error: 'Forbidden' });
+  }
+
+  return db.posts.update(post.id, request.body);
+});
+```
+
+## Password Hashing
+
+Use secure password hashing with argon2:
+
+```typescript
+import { hash, verify } from '@node-rs/argon2';
+
+async function hashPassword(password: string): Promise<string> {
+  return hash(password, {
+    memoryCost: 65536,
+    timeCost: 3,
+    parallelism: 4,
+  });
+}
+
+async function verifyPassword(hash: string, password: string): Promise<boolean> {
+  return verify(hash, password);
+}
+
+app.post('/register', async (request, reply) => {
+  const { email, password } = request.body;
+
+  const hashedPassword = await hashPassword(password);
+  const user = await db.users.create({
+    email,
+    password: hashedPassword,
+  });
+
+  reply.code(201);
+  return { id: user.id, email: user.email };
+});
+
+app.post('/login', async (request, reply) => {
+  const { email, password } = request.body;
+  const user = await db.users.findByEmail(email);
+
+  if (!user || !(await verifyPassword(user.password, password))) {
+    return reply.code(401).send({ error: 'Invalid credentials' });
+  }
+
+  const token = app.jwt.sign({ id: user.id, role: user.role });
+  return { token };
+});
+```
+
+## Rate Limiting for Auth Endpoints
+
+Protect auth endpoints from brute force. **IMPORTANT: For production security, you MUST configure rate limiting with a Redis backend.** In-memory rate limiting is not safe for distributed deployments and can be bypassed.
+
+```typescript
+import fastifyRateLimit from '@fastify/rate-limit';
+import Redis from 'ioredis';
+
+const redis = new Redis(process.env.REDIS_URL);
+
+// Global rate limit with Redis backend
+app.register(fastifyRateLimit, {
+  max: 100,
+  timeWindow: '1 minute',
+  redis, // REQUIRED for production - ensures rate limiting works across all instances
+});
+
+// Stricter limit for auth endpoints
+app.register(async function authRoutes(fastify) {
+  await fastify.register(fastifyRateLimit, {
+    max: 5,
+    timeWindow: '1 minute',
+    redis, // REQUIRED for production
+    keyGenerator: (request) => {
+      // Rate limit by IP + email combination
+      const email = request.body?.email || '';
+      return `${request.ip}:${email}`;
+    },
+  });
+
+  fastify.post('/login', loginHandler);
+  fastify.post('/register', registerHandler);
+  fastify.post('/forgot-password', forgotPasswordHandler);
+}, { prefix: '/auth' });
+```