ads-fe 0.0.1

package/skills/node/rules/performance.md

@@ -0,0 +1,130 @@
+---
+name: performance
+description: Performance optimization techniques
+metadata:
+  tags: performance, optimization, memory, worker-threads
+---
+
+# Performance in Node.js
+
+## Avoid Blocking the Event Loop
+
+Never perform CPU-intensive operations synchronously:
+
+```typescript
+// BAD - blocks event loop
+function hashPasswordSync(password: string): string {
+  return crypto.pbkdf2Sync(password, salt, 100000, 64, 'sha512').toString('hex');
+}
+
+// GOOD - async operation
+function hashPassword(password: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    crypto.pbkdf2(password, salt, 100000, 64, 'sha512', (err, key) => {
+      if (err) reject(err);
+      else resolve(key.toString('hex'));
+    });
+  });
+}
+```
+
+## Worker Threads with Piscina
+
+Use [piscina](https://github.com/piscinajs/piscina) for CPU-intensive tasks:
+
+```typescript
+// worker.ts
+export default function heavyComputation(data: { input: string }): string {
+  // CPU-intensive work here
+  return result;
+}
+```
+
+```typescript
+// main.ts
+import Piscina from 'piscina';
+
+const piscina = new Piscina({
+  filename: new URL('./worker.ts', import.meta.url).href,
+});
+
+const result = await piscina.run({ input: 'data' });
+```
+
+Piscina handles worker pool management, task queuing, and load balancing automatically.
+
+## Connection Pooling
+
+Always use connection pools for databases:
+
+```typescript
+import { Pool } from 'pg';
+
+const pool = new Pool({
+  max: 20,
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 2000,
+});
+
+async function query<T>(sql: string, params: unknown[]): Promise<T[]> {
+  const client = await pool.connect();
+  try {
+    const result = await client.query(sql, params);
+    return result.rows;
+  } finally {
+    client.release();
+  }
+}
+```
+
+## Avoid Memory Leaks
+
+Common memory leak patterns to avoid:
+
+```typescript
+// BAD - unbounded cache
+const cache = new Map();
+function addToCache(key: string, value: unknown) {
+  cache.set(key, value); // Never cleaned up
+}
+
+// GOOD - LRU cache with max size
+import { LRUCache } from 'lru-cache';
+
+const cache = new LRUCache<string, unknown>({
+  max: 500,
+  ttl: 1000 * 60 * 5,
+});
+
+// BAD - listener leak
+function subscribe(emitter: EventEmitter) {
+  emitter.on('event', handler); // Never removed
+}
+
+// GOOD - cleanup listeners
+function subscribe(emitter: EventEmitter): () => void {
+  emitter.on('event', handler);
+  return () => emitter.off('event', handler);
+}
+```
+
+## Lazy Loading
+
+Load modules only when needed:
+
+```typescript
+let heavyModule: HeavyModule | null = null;
+
+async function getHeavyModule(): Promise<HeavyModule> {
+  if (!heavyModule) {
+    const { HeavyModule } = await import('./heavy-module.js');
+    heavyModule = new HeavyModule();
+  }
+  return heavyModule;
+}
+```
+
+## Related
+
+- [caching.md](./caching.md) - Caching patterns and libraries
+- [profiling.md](./profiling.md) - Profiling and benchmarking tools

package/skills/node/rules/profiling.md

@@ -0,0 +1,183 @@
+---
+name: profiling
+description: Profiling and benchmarking tools
+metadata:
+  tags: profiling, benchmarking, performance, flame-graphs
+---
+
+# Profiling in Node.js
+
+## Flame Graphs with @platformatic/flame
+
+Use [@platformatic/flame](https://github.com/platformatic/flame) for CPU profiling with flame graph visualization:
+
+```bash
+npx @platformatic/flame app.ts
+```
+
+This starts your application with profiling enabled and generates an interactive flame graph.
+
+### Markdown Output for AI Analysis
+
+flame can output markdown reports suitable for AI-assisted performance analysis:
+
+```bash
+npx @platformatic/flame --output markdown app.ts
+```
+
+This enables a fully agentic workflow where you can:
+1. Profile your application
+2. Get markdown output describing hotspots
+3. Feed the report to an AI assistant for optimization suggestions
+
+### Programmatic Usage
+
+```typescript
+import { profile } from '@platformatic/flame';
+
+const stop = await profile({
+  outputFile: 'profile.html',
+});
+
+// Run your workload
+await runBenchmark();
+
+await stop();
+```
+
+## Load Testing Tools
+
+### autocannon
+
+Use [autocannon](https://github.com/mcollina/autocannon) for HTTP benchmarking:
+
+```bash
+# Basic benchmark
+npx autocannon http://localhost:3000
+
+# With options
+npx autocannon -c 100 -d 30 -p 10 http://localhost:3000
+
+# POST request with body
+npx autocannon -m POST -H "Content-Type: application/json" -b '{"name":"test"}' http://localhost:3000/users
+```
+
+Options:
+- `-c` - Number of concurrent connections (default: 10)
+- `-d` - Duration in seconds (default: 10)
+- `-p` - Number of pipelined requests (default: 1)
+- `-m` - HTTP method
+- `-b` - Request body
+
+### Programmatic autocannon
+
+```typescript
+import autocannon from 'autocannon';
+
+const result = await autocannon({
+  url: 'http://localhost:3000',
+  connections: 100,
+  duration: 30,
+  pipelining: 10,
+});
+
+console.log(autocannon.printResult(result));
+```
+
+### wrk
+
+[wrk](https://github.com/wg/wrk) is a high-performance HTTP benchmarking tool:
+
+```bash
+# Basic benchmark
+wrk -t12 -c400 -d30s http://localhost:3000
+
+# With Lua script for custom requests
+wrk -t12 -c400 -d30s -s post.lua http://localhost:3000
+```
+
+Options:
+- `-t` - Number of threads
+- `-c` - Number of connections
+- `-d` - Duration
+- `-s` - Lua script for custom logic
+
+### k6
+
+[k6](https://k6.io/) is ideal for complex load testing scenarios:
+
+```javascript
+// load-test.js
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+
+export const options = {
+  vus: 100,
+  duration: '30s',
+};
+
+export default function () {
+  const res = http.get('http://localhost:3000');
+  check(res, {
+    'status is 200': (r) => r.status === 200,
+    'response time < 200ms': (r) => r.timings.duration < 200,
+  });
+  sleep(1);
+}
+```
+
+```bash
+k6 run load-test.js
+```
+
+## Built-in Node.js Profiling
+
+### CPU Profiling
+
+```bash
+# Generate V8 profiling log
+node --prof app.js
+
+# Process the log
+node --prof-process isolate-*.log > profile.txt
+```
+
+### Heap Snapshots
+
+```bash
+# Start with inspector
+node --inspect app.js
+
+# Then use Chrome DevTools (chrome://inspect) to:
+# - Take heap snapshots
+# - Record allocation timelines
+# - Find memory leaks
+```
+
+### Diagnostic Reports
+
+```bash
+# Generate report on signal
+node --report-on-signal app.js
+kill -SIGUSR2 <pid>
+
+# Generate report on uncaught exception
+node --report-on-fatalerror app.js
+```
+
+## Profiling Workflow
+
+1. **Establish baseline** - Run autocannon to get initial metrics
+2. **Profile** - Use @platformatic/flame to identify hotspots
+3. **Optimize** - Fix the identified bottlenecks
+4. **Verify** - Run autocannon again to measure improvement
+5. **Repeat** - Continue until performance goals are met
+
+## Tool Comparison
+
+| Tool | Best For |
+|------|----------|
+| @platformatic/flame | CPU profiling, flame graphs, AI-assisted analysis |
+| autocannon | Quick HTTP benchmarks, Node.js native |
+| wrk | Maximum throughput testing |
+| k6 | Complex scenarios, CI/CD integration, scripted tests |

package/skills/node/rules/streams.md

@@ -0,0 +1,213 @@
+---
+name: streams
+description: Working with Node.js streams
+metadata:
+  tags: streams, readable, writable, transform, pipeline
+---
+
+# Node.js Streams
+
+## High-signal triggers
+
+If the prompt mentions **CSV**, **ETL**, **ingestion**, **large files**, **transform streams**, **backpressure**, or **line-by-line processing**, prioritize `pipeline()` + explicit async-generator transforms.
+
+## Use pipeline for Stream Composition
+
+Always use `pipeline` instead of `.pipe()` for proper error handling:
+
+```typescript
+import { pipeline } from 'node:stream/promises';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { createGzip } from 'node:zlib';
+
+async function compressFile(input: string, output: string): Promise<void> {
+  await pipeline(
+    createReadStream(input),
+    createGzip(),
+    createWriteStream(output)
+  );
+}
+```
+
+### Async Generators in Pipeline
+
+Use async generators for transformation:
+
+```typescript
+import { pipeline } from 'node:stream/promises';
+import { createReadStream, createWriteStream } from 'node:fs';
+
+async function* toUpperCase(source: AsyncIterable<Buffer>): AsyncGenerator<string> {
+  for await (const chunk of source) {
+    yield chunk.toString().toUpperCase();
+  }
+}
+
+async function processFile(input: string, output: string): Promise<void> {
+  await pipeline(
+    createReadStream(input),
+    toUpperCase,
+    createWriteStream(output)
+  );
+}
+```
+
+### CSV/ETL pattern: pipeline + async transform + deduplicated enrichment
+
+For ingestion-style tasks, show an explicit `async function*` transform and integrate deduped async lookups:
+
+```typescript
+import { pipeline } from 'node:stream/promises';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { createCache } from 'async-cache-dedupe';
+
+const cache = createCache({
+  ttl: 60,
+  stale: 5,
+  storage: { type: 'memory' },
+});
+
+cache.define('lookupPlan', async (planId: string) => {
+  return await fetch(`https://billing.internal/plans/${planId}`).then(async (res) => await res.json());
+});
+
+async function* enrichCsvRows(source: AsyncIterable<Buffer>): AsyncGenerator<string> {
+  let tail = '';
+
+  for await (const chunk of source) {
+    tail += chunk.toString('utf8');
+    const lines = tail.split('\n');
+    tail = lines.pop() ?? '';
+
+    for (const line of lines) {
+      if (line.trim().length === 0) continue;
+      const [userId, planId] = line.split(',');
+      const plan = await cache.lookupPlan(planId); // concurrent requests dedupe by key
+      yield `${userId},${planId},${plan.tier}\n`;
+    }
+  }
+
+  if (tail.trim().length > 0) {
+    const [userId, planId] = tail.split(',');
+    const plan = await cache.lookupPlan(planId);
+    yield `${userId},${planId},${plan.tier}\n`;
+  }
+}
+
+await pipeline(
+  createReadStream('users.csv'),
+  enrichCsvRows,
+  createWriteStream('users-enriched.csv')
+);
+```
+
+### Multiple Transformations
+
+Chain multiple async generators:
+
+```typescript
+import { pipeline } from 'node:stream/promises';
+
+async function* parseLines(source: AsyncIterable<Buffer>): AsyncGenerator<string> {
+  let buffer = '';
+  for await (const chunk of source) {
+    buffer += chunk.toString();
+    const lines = buffer.split('\n');
+    buffer = lines.pop() ?? '';
+    for (const line of lines) {
+      yield line;
+    }
+  }
+  if (buffer) yield buffer;
+}
+
+async function* filterNonEmpty(source: AsyncIterable<string>): AsyncGenerator<string> {
+  for await (const line of source) {
+    if (line.trim()) {
+      yield line + '\n';
+    }
+  }
+}
+
+await pipeline(
+  createReadStream('input.txt'),
+  parseLines,
+  filterNonEmpty,
+  createWriteStream('output.txt')
+);
+```
+
+## Async Iterators with Streams
+
+Use async iterators for consuming streams:
+
+```typescript
+import { createReadStream } from 'node:fs';
+import { createInterface } from 'node:readline';
+
+async function processLines(filePath: string): Promise<void> {
+  const fileStream = createReadStream(filePath);
+  const rl = createInterface({
+    input: fileStream,
+    crlfDelay: Infinity,
+  });
+
+  for await (const line of rl) {
+    await processLine(line);
+  }
+}
+```
+
+## Readable.from for Creating Streams
+
+Create readable streams from iterables:
+
+```typescript
+import { Readable } from 'node:stream';
+
+async function* generateData(): AsyncGenerator<string> {
+  for (let i = 0; i < 100; i++) {
+    yield JSON.stringify({ id: i, timestamp: Date.now() }) + '\n';
+  }
+}
+
+const stream = Readable.from(generateData());
+```
+
+## Backpressure Handling
+
+Respect backpressure signals using `once` from events:
+
+```typescript
+import { Writable } from 'node:stream';
+import { once } from 'node:events';
+
+async function writeData(
+  writable: Writable,
+  data: string[]
+): Promise<void> {
+  for (const chunk of data) {
+    const canContinue = writable.write(chunk);
+    if (!canContinue) {
+      await once(writable, 'drain');
+    }
+  }
+}
+```
+
+## Stream Consumers (Node.js 18+)
+
+Use stream consumers for common operations:
+
+```typescript
+import { text, json, buffer } from 'node:stream/consumers';
+import { Readable } from 'node:stream';
+
+async function readStreamAsJson<T>(stream: Readable): Promise<T> {
+  return json(stream) as Promise<T>;
+}
+
+async function readStreamAsText(stream: Readable): Promise<string> {
+  return text(stream);
+}
+```

package/skills/node/rules/stuck-processes-and-tests.md

@@ -0,0 +1,124 @@
+---
+name: stuck-processes-and-tests
+description: Diagnosing Node.js processes that do not exit and tests that get stuck
+metadata:
+  tags: node, debugging, testing, hangs, open-handles, diagnostics
+---
+
+# Diagnosing Stuck Node.js Processes and Hanging Tests
+
+## Activation triggers (apply this rule immediately)
+
+Use this rule when prompts/logs include any of:
+- "`node --test` hangs" / "test run never exits"
+- "CI timed out" after tests appear done
+- "process is still running" / "did not exit cleanly"
+- "open handles" / "active handles"
+- "passes alone, hangs in full suite"
+
+## Non-negotiable checklist (all 5 required)
+
+1. **Isolate first**: reproduce with one file, then one test name.
+2. **Fail fast**: run with explicit timeout + reporter so hangs produce location context.
+3. **Capture handles**: run `why-is-node-running` and record the reported handle owner.
+4. **Patch teardown in the same scope that created the resource** (`t.after(...)`, await close/terminate/disconnect).
+5. **Verify stability**: repeat isolated test many times, then run full suite.
+
+Do **not** mark the issue fixed unless step 5 passes.
+
+## Command path (run in order)
+
+```bash
+# 1) Reproduce full command with fail-fast settings
+node --test --test-reporter=spec --test-timeout=15000
+
+# 2) Isolate file, then test name
+node --test --test-timeout=15000 path/to/file.test.ts
+node --test --test-timeout=15000 --test-name-pattern="should close resources" path/to/file.test.ts
+
+# 3) Dump active handles when hung
+node --import why-is-node-running/include --test path/to/file.test.ts
+# in another shell, send SIGUSR1 to printed PID
+kill -SIGUSR1 <pid>
+
+# 4) Stress rerun isolated repro (Linux: timeout, macOS: gtimeout)
+TIMEOUT_BIN="$(command -v timeout || command -v gtimeout)"
+for i in {1..30}; do
+  "$TIMEOUT_BIN" 30s node --test path/to/file.test.ts || { echo "failed on run $i"; break; }
+done
+```
+
+### `why-is-node-running` install note
+
+- ESM / modern Node: `npm i -D why-is-node-running`
+- older CommonJS projects: `npm i -D why-is-node-running@v2`
+
+Use it for diagnostics only; gate noisy output behind an environment flag in CI.
+
+## High-probability root causes
+
+- HTTP server started but never closed (`server.close()` not awaited)
+- `setInterval` left running (or timer not `unref()`ed when appropriate)
+- DB/Redis/Kafka clients not disconnected
+- worker threads, child processes, or message channels left alive
+- file watchers / readline interfaces still open
+- unresolved promises from fire-and-forget async code
+- teardown hooks that throw before cleanup completes
+
+## Integrated fix example (CI hangs after tests appear complete)
+
+**Symptom:** CI times out; local full-suite run hangs after most tests pass.
+
+### Step sequence
+
+1. Reproduce with:
+   ```bash
+   node --test --test-reporter=spec --test-timeout=15000
+   ```
+2. Isolate to one test using `--test-name-pattern`.
+3. Run with `--import why-is-node-running/include` and send `SIGUSR1`.
+4. Patch teardown where resource is created.
+5. Verify isolated 30x, then full suite.
+
+### Bad (common leak)
+
+```typescript
+it('serves requests', async () => {
+  const server = await startServer({ port: 0 });
+  const id = setInterval(() => {}, 1000);
+  // test body...
+  // ❌ no deterministic teardown
+});
+```
+
+### Good (deterministic teardown)
+
+```typescript
+import { once } from 'node:events';
+
+it('serves requests', async (t) => {
+  const server = await startServer({ port: 0 });
+  const id = setInterval(() => {}, 1000);
+
+  t.after(async () => {
+    clearInterval(id);
+    server.close();
+    await once(server, 'close');
+  });
+
+  // test body...
+});
+```
+
+## Definition of done (must all pass)
+
+- [ ] Isolated repro passes repeatedly (recommended: 30 runs) with no hangs
+- [ ] Full `node --test` run exits with code 0
+- [ ] CI completes with no timeout
+- [ ] `why-is-node-running` shows no unexpected leftover handles
+
+## Related rules
+
+- [flaky-tests.md](flaky-tests.md)
+- [testing.md](testing.md)
+- [graceful-shutdown.md](graceful-shutdown.md)