@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/codex/node-streams-pattern/SKILL.md

@@ -0,0 +1,163 @@
+# Node.js Streams Pattern
+
+> Process large data efficiently using Node.js Readable, Writable, and Transform streams
+
+## When to Use
+
+- Processing files or data too large to fit in memory
+- Building data pipelines that transform data in stages
+- Streaming HTTP responses or file uploads
+- Implementing backpressure-aware data processing
+
+## Instructions
+
+1. **Read a file as a stream:**
+
+```typescript
+import { createReadStream } from 'node:fs';
+import { pipeline } from 'node:stream/promises';
+
+const readable = createReadStream('large-file.csv', { encoding: 'utf-8' });
+
+for await (const chunk of readable) {
+  processChunk(chunk);
+}
+```
+
+2. **Pipeline for stream composition** (handles errors and cleanup):
+
+```typescript
+import { createReadStream, createWriteStream } from 'node:fs';
+import { createGzip } from 'node:zlib';
+import { pipeline } from 'node:stream/promises';
+
+await pipeline(createReadStream('input.json'), createGzip(), createWriteStream('output.json.gz'));
+```
+
+3. **Transform stream** for data processing:
+
+```typescript
+import { Transform } from 'node:stream';
+
+const uppercase = new Transform({
+  transform(chunk, encoding, callback) {
+    this.push(chunk.toString().toUpperCase());
+    callback();
+  },
+});
+
+await pipeline(createReadStream('input.txt'), uppercase, createWriteStream('output.txt'));
+```
+
+4. **Object mode streams** for JSON processing:
+
+```typescript
+import { Transform } from 'node:stream';
+
+const filterActive = new Transform({
+  objectMode: true,
+  transform(user, encoding, callback) {
+    if (user.isActive) this.push(user);
+    callback();
+  },
+});
+```
+
+5. **Readable from async generator:**
+
+```typescript
+import { Readable } from 'node:stream';
+
+async function* generateRecords() {
+  for (let i = 0; i < 1_000_000; i++) {
+    yield { id: i, value: Math.random() };
+  }
+}
+
+const readable = Readable.from(generateRecords());
+```
+
+6. **HTTP streaming response:**
+
+```typescript
+import { createReadStream } from 'node:fs';
+
+app.get('/download', (req, res) => {
+  res.setHeader('Content-Type', 'application/octet-stream');
+  const stream = createReadStream('large-file.zip');
+  stream.pipe(res);
+
+  stream.on('error', (err) => {
+    res.status(500).end('Error reading file');
+  });
+});
+```
+
+7. **Line-by-line processing:**
+
+```typescript
+import { createReadStream } from 'node:fs';
+import { createInterface } from 'node:readline';
+
+const rl = createInterface({
+  input: createReadStream('data.csv'),
+  crlfDelay: Infinity,
+});
+
+for await (const line of rl) {
+  const [name, email] = line.split(',');
+  await processUser({ name, email });
+}
+```
+
+8. **Always use `pipeline`** instead of `.pipe()` — `pipeline` handles error propagation and cleanup:
+
+```typescript
+// Bad: errors not propagated, streams not cleaned up
+readable.pipe(transform).pipe(writable);
+
+// Good: errors propagated, streams destroyed on error
+await pipeline(readable, transform, writable);
+```
+
+## Details
+
+Streams process data in chunks without loading the entire dataset into memory. A 10GB file can be processed with a 64KB buffer.
+
+**Stream types:**
+
+- **Readable** — source of data (file reads, HTTP responses, database cursors)
+- **Writable** — destination for data (file writes, HTTP requests, database inserts)
+- **Transform** — processes data in transit (compression, encryption, parsing)
+- **Duplex** — both readable and writable (network sockets, WebSocket connections)
+
+**Backpressure:** When a writable stream cannot consume data as fast as the readable produces it, Node.js automatically pauses the readable stream. This prevents memory exhaustion. `pipeline` handles backpressure correctly; manual `.pipe()` does not always.
+
+**`highWaterMark`:** Controls the internal buffer size (default 16KB for byte streams, 16 objects for object mode). Lower values reduce memory but increase I/O operations.
+
+**Trade-offs:**
+
+- Streams handle unlimited data sizes — but add complexity compared to simple `readFile`
+- `pipeline` handles errors and cleanup — but requires all streams to implement `destroy` correctly
+- Object mode is convenient for JSON processing — but disables backpressure optimization (each object is one "chunk")
+- Async generators create readable streams easily — but lose backpressure if the generator is compute-bound
+
+## Source
+
+https://nodejs.org/api/stream.html
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/codex/node-streams-pattern/skill.yaml

@@ -0,0 +1,41 @@
+name: node-streams-pattern
+version: "1.0.0"
+description: Process large data efficiently using Node.js Readable, Writable, and Transform streams
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/server/**"
+  - "**/routes/**"
+  - "**/*.mjs"
+  - "**/workers/**"
+  - "**/streams/**"
+related_skills:
+  - node-event-emitter
+  - ts-async-patterns
+stack_signals:
+  - nodejs
+  - typescript
+keywords:
+  - streams
+  - Readable
+  - Writable
+  - Transform
+  - pipeline
+  - backpressure
+metadata:
+  author: community
+  upstream: nodejs.org/en/docs/guides/backpressuring-in-streams
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/node-testing-patterns/SKILL.md

@@ -0,0 +1,205 @@
+# Node.js Testing Patterns
+
+> Test Node.js APIs and modules using supertest, nock, and test containers
+
+## When to Use
+
+- Testing Express/Fastify API endpoints with real HTTP requests
+- Mocking outbound HTTP requests to external services
+- Running integration tests against real databases in containers
+- Testing Node.js modules with file system or network dependencies
+
+## Instructions
+
+1. **Supertest for API endpoint testing:**
+
+```typescript
+import request from 'supertest';
+import { app } from '../app';
+
+describe('POST /api/users', () => {
+  it('creates a user and returns 201', async () => {
+    const response = await request(app)
+      .post('/api/users')
+      .send({ name: 'Alice', email: 'alice@test.com' })
+      .set('Authorization', `Bearer ${testToken}`)
+      .expect('Content-Type', /json/)
+      .expect(201);
+
+    expect(response.body).toMatchObject({
+      name: 'Alice',
+      email: 'alice@test.com',
+    });
+    expect(response.body.id).toBeDefined();
+  });
+
+  it('returns 400 for invalid input', async () => {
+    const response = await request(app).post('/api/users').send({ name: '' }).expect(400);
+
+    expect(response.body.errors).toBeDefined();
+  });
+});
+```
+
+2. **Nock for mocking external HTTP calls:**
+
+```typescript
+import nock from 'nock';
+
+beforeEach(() => {
+  nock('https://api.stripe.com')
+    .post('/v1/charges')
+    .reply(200, { id: 'ch_test', status: 'succeeded' });
+});
+
+afterEach(() => {
+  nock.cleanAll();
+});
+
+it('processes payment through Stripe', async () => {
+  const result = await paymentService.charge({
+    amount: 1000,
+    currency: 'usd',
+    source: 'tok_visa',
+  });
+
+  expect(result.status).toBe('succeeded');
+});
+```
+
+3. **Test containers for database integration:**
+
+```typescript
+import { PostgreSqlContainer } from '@testcontainers/postgresql';
+
+let container;
+let prisma;
+
+beforeAll(async () => {
+  container = await new PostgreSqlContainer().start();
+  process.env.DATABASE_URL = container.getConnectionUri();
+  // Run migrations
+  prisma = new PrismaClient();
+  await prisma.$executeRawUnsafe(migrationSQL);
+}, 60_000);
+
+afterAll(async () => {
+  await prisma.$disconnect();
+  await container.stop();
+});
+
+afterEach(async () => {
+  await prisma.user.deleteMany();
+});
+```
+
+4. **Test file system operations** with temporary directories:
+
+```typescript
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), 'test-'));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+it('writes and reads config file', async () => {
+  const configPath = join(tempDir, 'config.json');
+  await writeConfig(configPath, { port: 3000 });
+  const config = await readConfig(configPath);
+  expect(config.port).toBe(3000);
+});
+```
+
+5. **Test with dependency injection:**
+
+```typescript
+// Service accepts dependencies as constructor params
+class UserService {
+  constructor(
+    private db: Database,
+    private emailClient: EmailClient
+  ) {}
+
+  async createUser(data: CreateUserInput) {
+    const user = await this.db.user.create(data);
+    await this.emailClient.sendWelcome(user.email);
+    return user;
+  }
+}
+
+// In tests: inject mocks
+it('sends welcome email on user creation', async () => {
+  const mockEmail = { sendWelcome: vi.fn() };
+  const service = new UserService(testDb, mockEmail);
+
+  await service.createUser({ name: 'Alice', email: 'alice@test.com' });
+
+  expect(mockEmail.sendWelcome).toHaveBeenCalledWith('alice@test.com');
+});
+```
+
+6. **Nock with request matching:**
+
+```typescript
+nock('https://api.example.com')
+  .get('/users')
+  .query({ role: 'admin' })
+  .matchHeader('Authorization', /Bearer .+/)
+  .reply(200, [{ id: '1', name: 'Admin' }]);
+```
+
+7. **Verify all mocked requests were called:**
+
+```typescript
+afterEach(() => {
+  if (!nock.isDone()) {
+    nock.cleanAll();
+    throw new Error('Not all nock interceptors were used');
+  }
+});
+```
+
+## Details
+
+Node.js testing involves testing HTTP APIs, external service integrations, file operations, and database queries. The strategy combines supertest (HTTP testing), nock (HTTP mocking), and test containers (database isolation).
+
+**Supertest:** Creates an in-process HTTP connection to your Express/Fastify app without starting a real server. This is faster and more reliable than making real HTTP requests to a running server.
+
+**Nock:** Intercepts HTTP requests made by `http`/`https`/`fetch` and returns configured responses. Unlike MSW, nock operates at the Node.js HTTP module level, not the network level.
+
+**Nock vs MSW:** Nock patches Node.js HTTP internals; MSW uses a service worker (browser) or interceptor (Node). MSW is better for testing code that uses `fetch`; nock is better for code that uses `http`/`https` directly.
+
+**Trade-offs:**
+
+- Supertest tests the full middleware stack — but requires the app to be importable as a module
+- Nock isolates external services — but tightly couples tests to request shapes
+- Test containers provide real database behavior — but add 5-15 seconds of startup time
+- Dependency injection enables easy mocking — but requires structuring code for injectability
+
+## Source
+
+https://vitest.dev/guide/
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/codex/node-testing-patterns/skill.yaml

@@ -0,0 +1,41 @@
+name: node-testing-patterns
+version: "1.0.0"
+description: Test Node.js APIs and modules using supertest, nock, and test containers
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/server/**"
+  - "**/routes/**"
+  - "**/*.mjs"
+  - "**/workers/**"
+  - "**/streams/**"
+related_skills:
+  - test-integration-patterns
+  - test-mock-patterns
+  - test-msw-pattern
+stack_signals:
+  - nodejs
+  - typescript
+keywords:
+  - supertest
+  - nock
+  - test-containers
+  - mocking-http
+  - API-testing
+metadata:
+  author: community
+  upstream: vitest.dev/guide/
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/node-worker-threads/SKILL.md

@@ -0,0 +1,169 @@
+# Node.js Worker Threads
+
+> Offload CPU-intensive work to worker threads using MessageChannel and shared buffers
+
+## When to Use
+
+- Running CPU-intensive operations without blocking the event loop
+- Parallelizing computation across CPU cores
+- Processing large datasets (image processing, CSV parsing, cryptography)
+- When child processes are too heavyweight (worker threads share memory)
+
+## Instructions
+
+1. **Basic worker thread:**
+
+```typescript
+// main.ts
+import { Worker } from 'node:worker_threads';
+
+const worker = new Worker('./worker.ts', {
+  workerData: { input: [1, 2, 3, 4, 5] },
+});
+
+worker.on('message', (result) => {
+  console.log('Result:', result);
+});
+
+worker.on('error', (err) => {
+  console.error('Worker error:', err);
+});
+
+worker.on('exit', (code) => {
+  if (code !== 0) console.error(`Worker exited with code ${code}`);
+});
+```
+
+```typescript
+// worker.ts
+import { parentPort, workerData } from 'node:worker_threads';
+
+const result = workerData.input.map((n: number) => n * n);
+parentPort?.postMessage(result);
+```
+
+2. **Promise-based wrapper:**
+
+```typescript
+function runWorker<T>(workerPath: string, data: unknown): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const worker = new Worker(workerPath, { workerData: data });
+    worker.on('message', resolve);
+    worker.on('error', reject);
+    worker.on('exit', (code) => {
+      if (code !== 0) reject(new Error(`Worker exited with code ${code}`));
+    });
+  });
+}
+
+const result = await runWorker<number[]>('./worker.ts', { input: data });
+```
+
+3. **Worker pool** for reusing threads:
+
+```typescript
+import { Worker } from 'node:worker_threads';
+import os from 'node:os';
+
+class WorkerPool {
+  private workers: Worker[] = [];
+  private queue: Array<{ data: unknown; resolve: Function; reject: Function }> = [];
+  private available: Worker[] = [];
+
+  constructor(
+    private workerPath: string,
+    size = os.cpus().length
+  ) {
+    for (let i = 0; i < size; i++) {
+      const worker = new Worker(workerPath);
+      worker.on('message', (result) => {
+        this.available.push(worker);
+        this.processQueue();
+      });
+      this.workers.push(worker);
+      this.available.push(worker);
+    }
+  }
+
+  exec<T>(data: unknown): Promise<T> {
+    return new Promise((resolve, reject) => {
+      this.queue.push({ data, resolve, reject });
+      this.processQueue();
+    });
+  }
+
+  private processQueue() {
+    while (this.queue.length > 0 && this.available.length > 0) {
+      const worker = this.available.pop()!;
+      const { data, resolve } = this.queue.shift()!;
+      worker.once('message', resolve);
+      worker.postMessage(data);
+    }
+  }
+
+  async destroy() {
+    await Promise.all(this.workers.map((w) => w.terminate()));
+  }
+}
+```
+
+4. **SharedArrayBuffer** for zero-copy data sharing:
+
+```typescript
+// Share a buffer between main thread and worker
+const sharedBuffer = new SharedArrayBuffer(1024);
+const sharedArray = new Int32Array(sharedBuffer);
+
+const worker = new Worker('./worker.ts', {
+  workerData: { buffer: sharedBuffer },
+});
+
+// Worker can read/write sharedArray directly — no serialization
+```
+
+5. **Transfer large data** without copying:
+
+```typescript
+const buffer = new ArrayBuffer(1024 * 1024); // 1MB
+worker.postMessage({ buffer }, [buffer]); // Transfer, not copy
+// buffer is now detached in the main thread
+```
+
+## Details
+
+Worker threads run JavaScript in parallel OS threads within the same Node.js process. They share memory space but have separate V8 instances and event loops.
+
+**Worker threads vs child processes:**
+
+- Worker threads share memory (SharedArrayBuffer) and have lower startup cost
+- Child processes have full isolation (separate memory, separate process)
+- Use workers for CPU computation; use child processes for running external programs
+
+**Communication overhead:** `postMessage` serializes data using the structured clone algorithm. For large objects, this serialization can be slower than the computation itself. Use SharedArrayBuffer or transferable objects to avoid copying.
+
+**Trade-offs:**
+
+- Worker threads parallelize CPU work — but add complexity for inter-thread communication
+- SharedArrayBuffer enables zero-copy sharing — but requires Atomics for synchronization
+- Worker pools reuse threads — but require managing pool lifecycle and task queuing
+- Transferable objects avoid copying — but detach the original buffer
+
+## Source
+
+https://nodejs.org/api/worker_threads.html
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/codex/node-worker-threads/skill.yaml

@@ -0,0 +1,41 @@
+name: node-worker-threads
+version: "1.0.0"
+description: Offload CPU-intensive work to worker threads using MessageChannel and shared buffers
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/server/**"
+  - "**/routes/**"
+  - "**/*.mjs"
+  - "**/workers/**"
+  - "**/streams/**"
+related_skills:
+  - node-event-emitter
+  - ts-async-patterns
+stack_signals:
+  - nodejs
+  - typescript
+keywords:
+  - worker-threads
+  - Worker
+  - workerData
+  - MessageChannel
+  - SharedArrayBuffer
+  - thread-pool
+metadata:
+  author: community
+  upstream: nodejs.org/en/docs/worker_threads
+state:
+  persistent: false
+  files: []
+depends_on: []