ads-fe 0.0.1

package/skills/node/rules/graceful-shutdown.md

@@ -0,0 +1,204 @@
+---
+name: graceful-shutdown
+description: Graceful shutdown and signal handling
+metadata:
+  tags: shutdown, signals, cleanup, health-checks, close-with-grace
+---
+
+# Graceful Shutdown in Node.js
+
+## Use close-with-grace
+
+Always use [close-with-grace](https://github.com/fastify/close-with-grace) for handling graceful shutdowns:
+
+```typescript
+import closeWithGrace from 'close-with-grace';
+
+closeWithGrace({ delay: 10000 }, async ({ signal, err }) => {
+  if (err) {
+    console.error('Error triggered shutdown:', err);
+  }
+  console.log(`Received ${signal}, shutting down...`);
+
+  await server.close();
+  await db.end();
+});
+```
+
+## HTTP Server Shutdown
+
+Close HTTP servers gracefully with close-with-grace:
+
+```typescript
+import { createServer } from 'node:http';
+import closeWithGrace from 'close-with-grace';
+
+const server = createServer((req, res) => {
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ status: 'ok' }));
+});
+
+server.listen(3000, () => {
+  console.log('Server listening on port 3000');
+});
+
+closeWithGrace({ delay: 10000 }, async ({ signal, err }) => {
+  if (err) {
+    console.error('Shutdown error:', err);
+  }
+  console.log(`${signal} received, closing server...`);
+
+  await new Promise<void>((resolve, reject) => {
+    server.close((err) => (err ? reject(err) : resolve()));
+  });
+
+  console.log('Server closed');
+});
+```
+
+## Fastify Integration
+
+Fastify has built-in close-with-grace support:
+
+```typescript
+import Fastify from 'fastify';
+
+const app = Fastify({
+  logger: true,
+});
+
+// Fastify automatically handles graceful shutdown
+// Just register your cleanup in onClose hooks
+
+app.addHook('onClose', async () => {
+  await db.end();
+  await cache.quit();
+});
+
+await app.listen({ port: 3000 });
+```
+
+## Multiple Resources Cleanup
+
+Clean up multiple resources in order:
+
+```typescript
+import closeWithGrace from 'close-with-grace';
+import { createServer } from 'node:http';
+
+const server = createServer(handler);
+const db = await connectDatabase();
+const redis = await connectRedis();
+
+server.listen(3000);
+
+closeWithGrace({ delay: 15000 }, async ({ signal, err }) => {
+  if (err) {
+    console.error('Error:', err);
+  }
+  console.log(`${signal} received`);
+
+  // Close in reverse order of initialization
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+  console.log('HTTP server closed');
+
+  await redis.quit();
+  console.log('Redis connection closed');
+
+  await db.end();
+  console.log('Database connection closed');
+});
+```
+
+## Health Checks
+
+Implement health checks that respect shutdown state:
+
+```typescript
+import closeWithGrace from 'close-with-grace';
+
+let isShuttingDown = false;
+
+function healthHandler(req: Request, res: Response) {
+  if (isShuttingDown) {
+    return res.status(503).json({ status: 'shutting_down' });
+  }
+  return res.json({ status: 'healthy' });
+}
+
+function readinessHandler(req: Request, res: Response) {
+  if (isShuttingDown) {
+    return res.status(503).json({ ready: false });
+  }
+  return res.json({ ready: true });
+}
+
+closeWithGrace({ delay: 10000 }, async ({ signal }) => {
+  isShuttingDown = true;
+  console.log(`${signal} received, marked as shutting down`);
+
+  // Wait for load balancer to stop sending traffic
+  await new Promise((r) => setTimeout(r, 5000));
+
+  await cleanup();
+});
+```
+
+## Custom Delay for Kubernetes
+
+Use appropriate delays for container orchestration:
+
+```typescript
+import closeWithGrace from 'close-with-grace';
+
+// Kubernetes sends SIGTERM, then waits terminationGracePeriodSeconds (default 30s)
+// Set delay slightly lower to ensure clean exit
+closeWithGrace({ delay: 25000 }, async ({ signal }) => {
+  console.log(`${signal} received`);
+
+  // Mark as not ready immediately
+  isShuttingDown = true;
+
+  // Wait for in-flight requests (k8s stops sending new traffic after SIGTERM)
+  await new Promise((r) => setTimeout(r, 5000));
+
+  // Close resources
+  await server.close();
+  await db.end();
+});
+```
+
+## Manual Signal Handling (when close-with-grace is not available)
+
+If you cannot use close-with-grace, handle signals manually:
+
+```typescript
+const signals: NodeJS.Signals[] = ['SIGTERM', 'SIGINT'];
+let isShuttingDown = false;
+
+async function shutdown(signal: string): Promise<void> {
+  if (isShuttingDown) return;
+  isShuttingDown = true;
+
+  console.log(`${signal} received, shutting down...`);
+
+  const timeout = setTimeout(() => {
+    console.error('Shutdown timeout, forcing exit');
+    process.exit(1);
+  }, 10000);
+
+  try {
+    await cleanup();
+    clearTimeout(timeout);
+    process.exit(0);
+  } catch (error) {
+    console.error('Shutdown error:', error);
+    clearTimeout(timeout);
+    process.exit(1);
+  }
+}
+
+for (const signal of signals) {
+  process.on(signal, () => shutdown(signal));
+}
+```

package/skills/node/rules/logging.md

@@ -0,0 +1,205 @@
+---
+name: logging
+description: Logging and debugging patterns
+metadata:
+  tags: logging, debugging, observability, pino
+---
+
+# Logging in Node.js
+
+## Use Pino
+
+Use [pino](https://github.com/pinojs/pino) for fast, structured JSON logging:
+
+```typescript
+import pino from 'pino';
+
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+});
+
+logger.info({ userId: user.id }, 'User created');
+logger.error({ err, orderId: order.id }, 'Failed to process payment');
+```
+
+## Log Levels
+
+Use appropriate log levels:
+
+```typescript
+// DEBUG - detailed information for debugging
+logger.debug({ itemId: item.id, step: 'validation' }, 'Processing item');
+
+// INFO - general operational information
+logger.info({ userId: user.id }, 'User created');
+
+// WARN - unexpected but handled situations
+logger.warn({ currentRate: 95, limit: 100 }, 'Rate limit approaching');
+
+// ERROR - errors that need attention
+logger.error({ err, orderId: order.id }, 'Failed to process payment');
+```
+
+## Transports
+
+Pino uses transports to process logs outside the main thread. Transports handle formatting, filtering, and sending logs to external services.
+
+### Pretty Printing for Development
+
+Use [pino-pretty](https://github.com/pinojs/pino-pretty) for human-readable output during development:
+
+```bash
+node app.ts | pino-pretty
+```
+
+Or configure programmatically:
+
+```typescript
+import pino from 'pino';
+
+const logger = pino({
+  transport: {
+    target: 'pino-pretty',
+    options: {
+      colorize: true,
+    },
+  },
+});
+```
+
+### Multiple Transports
+
+Send logs to multiple destinations:
+
+```typescript
+import pino from 'pino';
+
+const logger = pino({
+  transport: {
+    targets: [
+      {
+        target: 'pino-pretty',
+        options: { colorize: true },
+        level: 'info',
+      },
+      {
+        target: 'pino/file',
+        options: { destination: '/var/log/app.log' },
+        level: 'error',
+      },
+    ],
+  },
+});
+```
+
+### Available Transports
+
+- [pino-pretty](https://github.com/pinojs/pino-pretty) - Human-readable formatting
+- [pino-elasticsearch](https://github.com/pinojs/pino-elasticsearch) - Send to Elasticsearch
+- [pino-loki](https://github.com/Julien-R44/pino-loki) - Send to Grafana Loki
+- [pino-datadog](https://github.com/ovhemert/pino-datadog) - Send to Datadog
+
+## Child Loggers
+
+Create child loggers with bound context:
+
+```typescript
+const requestLogger = logger.child({
+  requestId: req.id,
+  userId: req.user?.id,
+});
+
+requestLogger.info('Processing request');
+requestLogger.info({ itemId }, 'Item processed');
+```
+
+## Fastify Integration
+
+Fastify has built-in pino integration:
+
+```typescript
+import Fastify from 'fastify';
+
+const app = Fastify({
+  logger: {
+    level: 'info',
+    transport: {
+      target: 'pino-pretty',
+    },
+  },
+});
+
+app.get('/', async (request) => {
+  request.log.info('Handling request');
+  return { status: 'ok' };
+});
+```
+
+## Redaction
+
+Use pino's built-in redaction for sensitive fields:
+
+```typescript
+const logger = pino({
+  redact: ['password', 'token', 'apiKey', 'req.headers.authorization'],
+});
+
+// Sensitive values are replaced with [Redacted]
+logger.info({ password: 'secret123' }, 'User login');
+// Output: {"password":"[Redacted]","msg":"User login"...}
+```
+
+## Debug Module
+
+The [debug](https://github.com/debug-js/debug) module is useful for library and module authors to emit tracing information. It is not meant for application logging:
+
+```typescript
+import createDebug from 'debug';
+
+const debug = createDebug('mymodule:connection');
+
+debug('Connecting to %s:%d', host, port);
+debug('Query executed in %dms', duration);
+```
+
+Enable debug output with the `DEBUG` environment variable:
+
+```bash
+DEBUG=mymodule:* node app.ts
+```
+
+Use debug for internal module diagnostics; use pino for application logs.
+
+## Node.js Built-in Debugging
+
+Use `util.debuglog` for module tracing without external dependencies:
+
+```typescript
+import { debuglog } from 'node:util';
+
+const debug = debuglog('mymodule');
+
+debug('Starting operation %s', operationId);
+debug('Connection established to %s', host);
+```
+
+Enable with the `NODE_DEBUG` environment variable:
+
+```bash
+NODE_DEBUG=mymodule node app.ts
+NODE_DEBUG=mymodule,http,net node app.ts
+```
+
+This also works with Node.js internals (`NODE_DEBUG=http,net,tls`) for debugging core module behavior.
+
+## Avoid Logging Sensitive Data
+
+Never log credentials, tokens, or personal data:
+
+```typescript
+// BAD - logging sensitive data
+logger.info({ email, password }, 'User login');
+
+// GOOD - log only safe identifiers
+logger.info({ email }, 'User login');
+```

package/skills/node/rules/modules.md

@@ -0,0 +1,105 @@
+---
+name: modules
+description: ES Modules and CommonJS patterns
+metadata:
+  tags: modules, esm, commonjs, imports, exports
+---
+
+# Node.js Modules
+
+## Prefer ES Modules
+
+Use ES Modules (ESM) for new projects:
+
+```json
+// package.json
+{
+  "type": "module"
+}
+```
+
+```typescript
+// Named exports (preferred)
+export function processData(data: Data): Result {
+  // ...
+}
+
+export const CONFIG = {
+  timeout: 5000,
+};
+
+// Named imports
+import { processData, CONFIG } from './utils.js';
+```
+
+## File Extensions in ESM
+
+Always include file extensions in ESM imports:
+
+```typescript
+// GOOD - explicit extension
+import { helper } from './helper.js';
+import config from './config.json' with { type: 'json' };
+
+// BAD - missing extension (works in bundlers but not native ESM)
+import { helper } from './helper';
+```
+
+## Barrel Exports
+
+Use index files to simplify imports:
+
+```typescript
+// src/utils/index.ts
+export { formatDate, parseDate } from './date.js';
+export { formatCurrency } from './currency.js';
+export { validateEmail } from './validation.js';
+
+// Consumer
+import { formatDate, formatCurrency } from './utils/index.js';
+```
+
+## Default vs Named Exports
+
+Prefer named exports for better refactoring and tree-shaking:
+
+```typescript
+// GOOD - named exports
+export function createServer(config: Config): Server {
+  // ...
+}
+
+export function createClient(config: Config): Client {
+  // ...
+}
+
+// AVOID - default exports
+export default function createServer(config: Config): Server {
+  // ...
+}
+```
+
+## Dynamic Imports
+
+Use dynamic imports for code splitting and conditional loading:
+
+```typescript
+async function loadPlugin(name: string): Promise<Plugin> {
+  const module = await import(`./plugins/${name}.js`);
+  return module.default;
+}
+
+// Conditional loading
+const { default: heavy } = await import('./heavy-module.js');
+```
+
+## __dirname and __filename in ESM
+
+Use `import.meta.dirname` and `import.meta.filename` (Node.js 20.11+):
+
+```typescript
+import { join } from 'node:path';
+
+const configPath = join(import.meta.dirname, 'config.json');
+const currentFile = import.meta.filename;
+```

package/skills/node/rules/node-modules-exploration.md

@@ -0,0 +1,172 @@
+---
+name: node-modules-exploration
+description: Navigating and analyzing node_modules directories
+metadata:
+  tags: node, nodejs, npm, yarn, pnpm, dependencies, packages
+---
+
+# Exploring node_modules
+
+## When to Explore node_modules
+
+Explore node_modules when you need to:
+- Find specific packages and their versions
+- Analyze dependencies and dependency trees
+- Examine package contents
+- Investigate dependency conflicts
+- Understand how a package works internally
+
+## Core Techniques
+
+### Finding Package Versions
+
+```bash
+# Check actual installed version
+cat node_modules/fastify/package.json | grep '"version"'
+
+# For scoped packages
+cat node_modules/@fastify/cors/package.json | grep '"version"'
+
+# List all versions with npm
+npm ls fastify
+```
+
+### Navigating Directory Structure
+
+```bash
+# List package contents
+ls node_modules/fastify/
+
+# Find TypeScript definitions
+ls node_modules/fastify/*.d.ts
+ls node_modules/@types/node/
+
+# Check main entry point
+cat node_modules/fastify/package.json | grep '"main"\|"exports"'
+```
+
+### Understanding Package Manager Differences
+
+**npm/yarn (node_modules hoisting):**
+```
+node_modules/
+  fastify/
+  pino/          # hoisted from fastify's dependencies
+  @fastify/cors/
+```
+
+**pnpm (content-addressable storage):**
+```
+node_modules/
+  .pnpm/
+    fastify@4.0.0/
+      node_modules/
+        fastify/
+        pino/    # symlinked, not hoisted
+  fastify -> .pnpm/fastify@4.0.0/node_modules/fastify
+```
+
+## Finding Package READMEs
+
+**CRITICAL: Never use `find`, `grep`, or `rg` for locating READMEs. Follow this sequence:**
+
+1. **Direct Read attempts (try in order):**
+   ```
+   node_modules/[package-name]/README.md
+   node_modules/[package-name]/readme.md
+   node_modules/[package-name]/README
+   ```
+   For scoped packages: `node_modules/@scope/package-name/README.md`
+
+2. **If not found, list directory contents:**
+   ```bash
+   ls node_modules/[package-name]/
+   ```
+   Look for README files in output, then read the exact filename.
+
+3. **Alternative locations:**
+   ```
+   node_modules/[package-name]/docs/README.md
+   ```
+   Or check `readme` field in `package.json`.
+
+## Analyzing Dependency Trees
+
+```bash
+# See why a package is installed
+npm why lodash
+
+# Full dependency tree
+npm ls --all
+
+# Only production dependencies
+npm ls --prod
+
+# Find duplicates
+npm ls --all 2>&1 | grep -E "^\s+.*@[0-9]" | sort | uniq -d
+```
+
+## Investigating Conflicts
+
+### Peer Dependency Issues
+
+```bash
+# Check peer dependencies
+cat node_modules/some-plugin/package.json | grep -A 10 '"peerDependencies"'
+
+# See what's actually installed vs. what's expected
+npm ls react
+```
+
+### Duplicate Packages
+
+When the same package appears multiple times:
+
+```bash
+# Find all instances of a package
+find node_modules -name "package.json" -path "*/lodash/*" 2>/dev/null
+
+# Check for version mismatches
+npm ls lodash
+```
+
+## Examining Package Internals
+
+### Entry Points
+
+```bash
+# Check exports field (modern)
+node -e "console.log(JSON.stringify(require('./node_modules/fastify/package.json').exports, null, 2))"
+
+# Check main field (legacy)
+cat node_modules/fastify/package.json | grep '"main"'
+```
+
+### TypeScript Definitions
+
+```bash
+# Find type definitions
+ls node_modules/fastify/*.d.ts
+cat node_modules/fastify/package.json | grep '"types"\|"typings"'
+
+# For DefinitelyTyped packages
+ls node_modules/@types/
+```
+
+### Source Files
+
+```bash
+# Examine source structure
+ls node_modules/fastify/lib/
+head -50 node_modules/fastify/lib/server.js
+```
+
+## Debugging Module Resolution
+
+```bash
+# See how Node.js resolves a module
+node -e "console.log(require.resolve('fastify'))"
+
+# With full resolution paths
+node --print "require.resolve.paths('fastify')"
+```