ads-fe 0.0.1

package/skills/node/rules/assets/graceful-server.ts

@@ -0,0 +1,80 @@
+import { createServer, IncomingMessage, ServerResponse, Server } from 'node:http';
+import closeWithGrace from 'close-with-grace';
+
+/**
+ * Example of a graceful HTTP server using close-with-grace.
+ * Demonstrates proper shutdown handling without connection tracking.
+ */
+
+let isShuttingDown = false;
+
+function createHandler() {
+  return (req: IncomingMessage, res: ServerResponse) => {
+    // During shutdown, disable keep-alive to drain connections
+    if (isShuttingDown) {
+      res.setHeader('Connection', 'close');
+    }
+
+    // Health check endpoint
+    if (req.url === '/health') {
+      if (isShuttingDown) {
+        res.writeHead(503, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ status: 'shutting_down' }));
+        return;
+      }
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ status: 'healthy' }));
+      return;
+    }
+
+    // Default response
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ message: 'Hello, World!' }));
+  };
+}
+
+function closeServer(server: Server): Promise<void> {
+  return new Promise((resolve, reject) => {
+    // Close idle connections immediately
+    server.closeIdleConnections();
+
+    server.close((err) => {
+      if (err && err.message !== 'Server is not running') {
+        reject(err);
+        return;
+      }
+      resolve();
+    });
+
+    // Force close all connections after timeout
+    setTimeout(() => {
+      server.closeAllConnections();
+    }, 5000);
+  });
+}
+
+export async function main(): Promise<void> {
+  const server = createServer(createHandler());
+
+  server.listen(3000, '0.0.0.0', () => {
+    console.log('Server listening on http://0.0.0.0:3000');
+  });
+
+  closeWithGrace({ delay: 10000 }, async ({ signal, err }) => {
+    if (err) {
+      console.error('Error triggered shutdown:', err);
+    }
+
+    console.log(`${signal} received, starting graceful shutdown...`);
+    isShuttingDown = true;
+
+    await closeServer(server);
+    console.log('Server closed successfully');
+  });
+}
+
+// Run if executed directly
+const isMain = process.argv[1]?.endsWith('graceful-server.ts') ?? false;
+if (isMain) {
+  main().catch(console.error);
+}

package/skills/node/rules/async-patterns.md

@@ -0,0 +1,136 @@
+---
+name: async-patterns
+description: Async/await and Promise patterns
+metadata:
+  tags: async, await, promises, concurrency
+---
+
+# Async Patterns in Node.js
+
+## Always Prefer async/await
+
+Use async/await over raw Promises for readability:
+
+```typescript
+// GOOD
+async function processItems(items: Item[]): Promise<Result[]> {
+  const results: Result[] = [];
+  for (const item of items) {
+    const result = await processItem(item);
+    results.push(result);
+  }
+  return results;
+}
+
+// AVOID - callback-style Promise chains
+function processItems(items: Item[]): Promise<Result[]> {
+  return Promise.resolve([])
+    .then((results) => {
+      return items.reduce((chain, item) => {
+        return chain.then((r) => processItem(item).then((res) => [...r, res]));
+      }, Promise.resolve(results));
+    });
+}
+```
+
+## Parallel Execution with Promise.all
+
+Use Promise.all for independent operations:
+
+```typescript
+async function fetchAllData(ids: string[]): Promise<Data[]> {
+  const promises = ids.map((id) => fetchData(id));
+  return Promise.all(promises);
+}
+```
+
+## Controlled Concurrency
+
+Limit concurrent operations to prevent resource exhaustion and extreme memory usage. Use [p-limit](https://github.com/sindresorhus/p-limit) or [p-map](https://github.com/sindresorhus/p-map):
+
+```typescript
+import pLimit from 'p-limit';
+
+const limit = pLimit(5); // Max 5 concurrent operations
+
+const results = await Promise.all(
+  items.map((item) => limit(() => processItem(item)))
+);
+```
+
+Or use p-map for cleaner syntax:
+
+```typescript
+import pMap from 'p-map';
+
+const results = await pMap(items, processItem, { concurrency: 5 });
+```
+
+## Promise.allSettled for Fault Tolerance
+
+Use Promise.allSettled when some failures are acceptable:
+
+```typescript
+async function fetchMultiple(urls: string[]): Promise<Map<string, string | Error>> {
+  const results = await Promise.allSettled(
+    urls.map((url) => fetch(url).then((r) => r.text()))
+  );
+
+  const map = new Map<string, string | Error>();
+  urls.forEach((url, i) => {
+    const result = results[i];
+    map.set(
+      url,
+      result.status === 'fulfilled' ? result.value : result.reason
+    );
+  });
+
+  return map;
+}
+```
+
+## Avoid Async in Constructors
+
+Constructors cannot be async. Use factory functions instead:
+
+```typescript
+// BAD - constructor cannot await
+class Database {
+  constructor() {
+    // Cannot use await here
+  }
+}
+
+// GOOD - factory function
+class Database {
+  private constructor(private connection: Connection) {}
+
+  static async create(config: Config): Promise<Database> {
+    const connection = await connect(config);
+    return new Database(connection);
+  }
+}
+
+// Usage
+const db = await Database.create(config);
+```
+
+## AbortController for Cancellation
+
+Use AbortController to cancel long-running operations:
+
+```typescript
+async function fetchWithTimeout(
+  url: string,
+  timeoutMs: number
+): Promise<Response> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    return await fetch(url, { signal: controller.signal });
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+```

package/skills/node/rules/caching.md

@@ -0,0 +1,198 @@
+---
+name: caching
+description: Caching patterns and libraries
+metadata:
+  tags: caching, memoization, performance, async-cache-dedupe
+---
+
+# Caching in Node.js
+
+## High-signal triggers
+
+If prompts mention **repeated async lookups**, **duplicate concurrent requests**, **CSV enrichment**, **ETL transforms**, **N+1 remote calls**, or **cache hot keys**, select a cache strategy explicitly and justify it.
+
+## Cache selection quick guide
+
+- Use **`lru-cache`** for process-local, bounded in-memory reuse where deduplicating concurrent requests is not the main concern.
+- Use **`async-cache-dedupe`** when multiple concurrent calls can request the same key and you want one in-flight request per key.
+- In stream/ETL scenarios, prefer `async-cache-dedupe` for enrichment calls inside an `async function*` transform.
+
+## Memoization with mnemoist
+
+Use [mnemoist](https://github.com/Yomguithereal/mnemonist) for synchronous memoization:
+
+```typescript
+import { LRUCache } from 'mnemonist';
+
+const cache = new LRUCache<string, User>(1000);
+
+function getUser(id: string): User | undefined {
+  if (cache.has(id)) {
+    return cache.get(id);
+  }
+  const user = fetchUserSync(id);
+  cache.set(id, user);
+  return user;
+}
+```
+
+## Async Caching with async-cache-dedupe
+
+Use [async-cache-dedupe](https://github.com/mcollina/async-cache-dedupe) for async operations with request deduplication:
+
+```typescript
+import { createCache } from 'async-cache-dedupe';
+
+const cache = createCache({
+  ttl: 60, // seconds
+  stale: 5, // serve stale while revalidating
+  storage: { type: 'memory' },
+});
+
+cache.define('getUser', async (id: string) => {
+  return await db.users.findById(id);
+});
+
+cache.define('getPost', {
+  ttl: 300,
+  stale: 30,
+}, async (id: string) => {
+  return await db.posts.findById(id);
+});
+
+// Usage - concurrent calls are deduplicated
+const user = await cache.getUser('123');
+const post = await cache.getPost('456');
+```
+
+### Request Deduplication
+
+async-cache-dedupe automatically deduplicates concurrent requests:
+
+```typescript
+// These three concurrent calls result in only ONE database query
+const [user1, user2, user3] = await Promise.all([
+  cache.getUser('123'),
+  cache.getUser('123'),
+  cache.getUser('123'),
+]);
+```
+
+### Stream/ETL enrichment example
+
+Use deduplicated async cache inside an `async function*` transform when rows repeatedly reference the same key:
+
+```typescript
+import { createCache } from 'async-cache-dedupe';
+
+const cache = createCache({ ttl: 120, stale: 10, storage: { type: 'memory' } });
+
+cache.define('getPlan', async (planId: string) => {
+  return await db.plans.findById(planId);
+});
+
+async function* enrichRows(source: AsyncIterable<{ userId: string, planId: string }>) {
+  for await (const row of source) {
+    const plan = await cache.getPlan(row.planId); // one in-flight call per planId
+    yield { ...row, planName: plan.name };
+  }
+}
+```
+
+### Redis Storage
+
+For distributed caching across multiple instances:
+
+```typescript
+import { createCache } from 'async-cache-dedupe';
+import Redis from 'ioredis';
+
+const redis = new Redis();
+
+const cache = createCache({
+  ttl: 60,
+  storage: {
+    type: 'redis',
+    options: { client: redis },
+  },
+});
+```
+
+## LRU Cache
+
+Use [lru-cache](https://github.com/isaacs/node-lru-cache) for bounded in-memory caching:
+
+```typescript
+import { LRUCache } from 'lru-cache';
+
+const cache = new LRUCache<string, User>({
+  max: 500,           // Maximum items
+  ttl: 1000 * 60 * 5, // 5 minutes
+  updateAgeOnGet: true,
+});
+
+cache.set('user:123', user);
+const cached = cache.get('user:123');
+```
+
+## Cache Invalidation Patterns
+
+### Time-Based Expiration
+
+```typescript
+const cache = createCache({
+  ttl: 60,    // Fresh for 60 seconds
+  stale: 30,  // Serve stale for 30 more seconds while revalidating
+});
+```
+
+### Manual Invalidation
+
+```typescript
+// Invalidate single entry
+await cache.invalidate('getUser', '123');
+
+// Invalidate all entries for a function
+await cache.clear('getUser');
+
+// Clear entire cache
+await cache.clear();
+```
+
+### Reference-Based Invalidation
+
+```typescript
+const cache = createCache({
+  ttl: 60,
+  storage: { type: 'memory' },
+});
+
+cache.define('getUser', {
+  references: (args, key, result) => [`user:${result.id}`],
+}, async (id: string) => {
+  return await db.users.findById(id);
+});
+
+cache.define('getUserPosts', {
+  references: (args, key, result) => [`user:${args[0]}`],
+}, async (userId: string) => {
+  return await db.posts.findByUserId(userId);
+});
+
+// Invalidate all cache entries referencing this user
+await cache.invalidateAll(`user:123`);
+```
+
+## When to Cache
+
+- Database query results
+- External API responses
+- Computed values that are expensive to calculate
+- Configuration that rarely changes
+
+## When NOT to Cache
+
+- User-specific sensitive data (without proper isolation)
+- Rapidly changing data
+- Data that must always be consistent
+- Large objects that would exhaust memory

package/skills/node/rules/environment.md

@@ -0,0 +1,253 @@
+---
+name: environment
+description: Environment configuration and secrets management
+metadata:
+  tags: environment, configuration, env, secrets
+---
+
+# Environment Configuration in Node.js
+
+## Loading Environment Files
+
+Use Node.js built-in `--env-file` flag to load environment variables:
+
+```bash
+# Load from .env file
+node --env-file=.env app.ts
+
+# Load multiple env files (later files override earlier ones)
+node --env-file=.env --env-file=.env.local app.ts
+```
+
+### Programmatic API
+
+Load environment files programmatically with `process.loadEnvFile()`:
+
+```typescript
+import { loadEnvFile } from 'node:process';
+
+// Load .env from current directory
+loadEnvFile();
+
+// Load specific file
+loadEnvFile('.env.local');
+```
+
+## Environment Variables Validation
+
+### Using env-schema with TypeBox
+
+Use [env-schema](https://github.com/fastify/env-schema) with [TypeBox](https://github.com/sinclairzx81/typebox) for type-safe environment validation:
+
+```typescript
+import { envSchema } from 'env-schema';
+import { Type, Static } from '@sinclair/typebox';
+
+const schema = Type.Object({
+  PORT: Type.Number({ default: 3000 }),
+  DATABASE_URL: Type.String(),
+  API_KEY: Type.String({ minLength: 1 }),
+  LOG_LEVEL: Type.Union([
+    Type.Literal('debug'),
+    Type.Literal('info'),
+    Type.Literal('warn'),
+    Type.Literal('error'),
+  ], { default: 'info' }),
+});
+
+type Env = Static<typeof schema>;
+
+export const env = envSchema<Env>({ schema });
+```
+
+### Using Zod
+
+Alternatively, use [Zod](https://github.com/colinhacks/zod) for validation:
+
+```typescript
+import { z } from 'zod';
+
+const EnvSchema = z.object({
+  PORT: z.coerce.number().default(3000),
+  DATABASE_URL: z.string().url(),
+  API_KEY: z.string().min(1),
+  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+});
+
+type Env = z.infer<typeof EnvSchema>;
+
+function loadEnv(): Env {
+  const result = EnvSchema.safeParse(process.env);
+
+  if (!result.success) {
+    console.error('Invalid environment variables:');
+    console.error(result.error.format());
+    process.exit(1);
+  }
+
+  return result.data;
+}
+
+export const env = loadEnv();
+```
+
+## Avoid NODE_ENV
+
+`NODE_ENV` is an antipattern. It conflates multiple concerns into a single variable:
+
+- **Environment detection** (development vs production vs staging)
+- **Behavior toggling** (verbose logging, debug features)
+- **Optimization flags** (minification, caching)
+- **Security settings** (strict validation, HTTPS)
+
+This leads to problems:
+
+```typescript
+// BAD - NODE_ENV conflates concerns
+if (process.env.NODE_ENV === 'development') {
+  enableDebugLogging();    // logging concern
+  disableRateLimiting();   // security concern
+  useMockDatabase();       // infrastructure concern
+}
+```
+
+Instead, use explicit environment variables for each concern:
+
+```typescript
+// GOOD - explicit variables for each concern
+const config = {
+  logging: {
+    level: process.env.LOG_LEVEL || 'info',
+    pretty: process.env.LOG_PRETTY === 'true',
+  },
+  security: {
+    rateLimitEnabled: process.env.RATE_LIMIT_ENABLED !== 'false',
+    httpsOnly: process.env.HTTPS_ONLY === 'true',
+  },
+  database: {
+    url: process.env.DATABASE_URL,
+  },
+};
+```
+
+This approach:
+- Makes configuration explicit and discoverable
+- Allows fine-grained control per environment
+- Avoids hidden behavior changes
+- Makes testing easier (toggle individual features)
+
+## Configuration Object Pattern
+
+Create a typed configuration object:
+
+```typescript
+interface Config {
+  server: {
+    port: number;
+    host: string;
+  };
+  database: {
+    url: string;
+    poolSize: number;
+  };
+  auth: {
+    jwtSecret: string;
+    jwtExpiresIn: string;
+  };
+  features: {
+    enableMetrics: boolean;
+    enableTracing: boolean;
+  };
+}
+
+function createConfig(): Config {
+  return {
+    server: {
+      port: parseInt(process.env.PORT || '3000', 10),
+      host: process.env.HOST || '0.0.0.0',
+    },
+    database: {
+      url: requireEnv('DATABASE_URL'),
+      poolSize: parseInt(process.env.DB_POOL_SIZE || '10', 10),
+    },
+    auth: {
+      jwtSecret: requireEnv('JWT_SECRET'),
+      jwtExpiresIn: process.env.JWT_EXPIRES_IN || '1h',
+    },
+    features: {
+      enableMetrics: process.env.ENABLE_METRICS === 'true',
+      enableTracing: process.env.ENABLE_TRACING === 'true',
+    },
+  };
+}
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${name}`);
+  }
+  return value;
+}
+
+export const config = createConfig();
+```
+
+## .env File Structure
+
+Organize .env files properly:
+
+```bash
+# .env.example - committed to git, documents all variables
+PORT=3000
+DATABASE_URL=postgresql://user:pass@localhost:5432/db
+API_KEY=your-api-key-here
+
+# .env - local development, NOT committed
+PORT=3000
+DATABASE_URL=postgresql://dev:dev@localhost:5432/myapp
+API_KEY=sk-dev-key-123
+
+# .env.test - test environment
+DATABASE_URL=postgresql://test:test@localhost:5432/myapp_test
+```
+
+## Secrets in Production
+
+Never commit secrets to version control. Use a secrets management service appropriate for your infrastructure:
+
+**Cloud Provider Services:**
+- [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/)
+- [Google Cloud Secret Manager](https://cloud.google.com/secret-manager)
+- [Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault)
+
+**Infrastructure Tools:**
+- [HashiCorp Vault](https://www.vaultproject.io/)
+- [Doppler](https://www.doppler.com/)
+- [Infisical](https://infisical.com/)
+
+**Container Orchestration:**
+- Kubernetes Secrets
+- Docker Swarm Secrets
+
+**CI/CD Platforms:**
+- GitHub Actions Secrets
+- GitLab CI/CD Variables
+- CircleCI Contexts
+
+These services inject secrets as environment variables at runtime, keeping them out of your codebase and version history.
+
+## Feature Flags
+
+Implement feature flags via environment:
+
+```typescript
+const features = {
+  newDashboard: process.env.FEATURE_NEW_DASHBOARD === 'true',
+  betaApi: process.env.FEATURE_BETA_API === 'true',
+  darkMode: process.env.FEATURE_DARK_MODE === 'true',
+};
+
+export function isFeatureEnabled(feature: keyof typeof features): boolean {
+  return features[feature] ?? false;
+}
+```