@harness-engineering/cli 1.23.1 → 1.24.0

package/dist/agents/skills/codex/node-environment-config/SKILL.md

@@ -0,0 +1,145 @@
+# Node.js Environment Config
+
+> Manage environment configuration with process.env, dotenv, and validation for 12-factor apps
+
+## When to Use
+
+- Loading configuration from environment variables
+- Validating that all required environment variables are present at startup
+- Managing different configurations for development, staging, and production
+- Following 12-factor app principles for configuration
+
+## Instructions
+
+1. **Load `.env` files** with `dotenv` (or Node.js 20.6+ built-in):
+
+```typescript
+// Node.js 20.6+: use --env-file flag
+// node --env-file=.env app.js
+
+// Or with dotenv package
+import 'dotenv/config';
+```
+
+2. **Validate with Zod** at startup — fail fast on missing config:
+
+```typescript
+import { z } from 'zod';
+
+const EnvSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  PORT: z.coerce.number().default(3000),
+  DATABASE_URL: z.string().url(),
+  REDIS_URL: z.string().url().optional(),
+  API_KEY: z.string().min(1),
+  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+});
+
+export const env = EnvSchema.parse(process.env);
+// Throws at startup if any required variable is missing or invalid
+```
+
+3. **Type-safe access** after validation:
+
+```typescript
+// env.PORT is number, env.DATABASE_URL is string
+// No more process.env.PORT! (which is always string | undefined)
+const server = app.listen(env.PORT);
+```
+
+4. **Structure `.env` files:**
+
+```bash
+# .env — defaults for local development (committed)
+NODE_ENV=development
+PORT=3000
+LOG_LEVEL=debug
+
+# .env.local — local overrides and secrets (gitignored)
+DATABASE_URL=postgresql://localhost:5432/myapp
+API_KEY=dev-key-123
+```
+
+5. **Use `.env.example`** as documentation:
+
+```bash
+# .env.example — committed, shows all required variables
+NODE_ENV=development
+PORT=3000
+DATABASE_URL=postgresql://user:pass@host:5432/db
+API_KEY=your-api-key-here
+```
+
+6. **Environment-specific configs:**
+
+```typescript
+const config = {
+  development: {
+    logLevel: 'debug',
+    corsOrigin: '*',
+  },
+  production: {
+    logLevel: 'info',
+    corsOrigin: 'https://myapp.com',
+  },
+  test: {
+    logLevel: 'error',
+    corsOrigin: '*',
+  },
+}[env.NODE_ENV];
+```
+
+7. **Never hardcode secrets.** Use environment variables for:
+   - Database connection strings
+   - API keys and tokens
+   - Encryption keys
+   - Third-party service credentials
+
+8. **Add to `.gitignore`:**
+
+```
+.env.local
+.env.*.local
+.env.production
+```
+
+## Details
+
+The 12-factor app methodology recommends storing configuration in environment variables. This separates config from code and enables different configurations per deployment without code changes.
+
+**`process.env` limitations:**
+
+- All values are `string | undefined` — no numbers, booleans, or arrays
+- Missing variables are `undefined`, not errors — code can run with missing config and fail later
+- No validation — typos in variable names are silent
+
+**Validation at startup** with Zod solves all three problems. The application fails immediately with a clear error message if any required variable is missing.
+
+**Node.js 20.6+ `--env-file`:** Built-in `.env` loading without the `dotenv` package. Supports multiple files: `node --env-file=.env --env-file=.env.local app.js`.
+
+**Trade-offs:**
+
+- Env vars are simple and universal — but offer no structure (no nesting, no types)
+- Zod validation catches issues at startup — but adds a dependency
+- `.env` files are convenient for development — but should never be used in production (use the deployment platform's secrets management)
+- `process.env` is global — consider dependency injection for testability
+
+## Source
+
+https://nodejs.org/api/process.html#processenv
+
+## 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-environment-config/skill.yaml

@@ -0,0 +1,39 @@
+name: node-environment-config
+version: "1.0.0"
+description: Manage environment configuration with process.env, dotenv, and validation for 12-factor apps
+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:
+  - ts-zod-integration
+  - ts-strict-mode
+stack_signals:
+  - nodejs
+  - typescript
+keywords:
+  - process.env
+  - dotenv
+  - env-validation
+  - 12-factor
+  - configuration
+metadata:
+  author: community
+  upstream: nodejs.org/api/process.html#processenv
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/node-error-handling/SKILL.md

@@ -0,0 +1,183 @@
+# Node.js Error Handling
+
+> Handle uncaught exceptions, promise rejections, and errors across async Node.js code
+
+## When to Use
+
+- Setting up global error handling for a Node.js application
+- Preventing the process from crashing on unhandled errors
+- Implementing structured error handling across async code
+- Logging and recovering from errors in production
+
+## Instructions
+
+1. **Handle uncaught exceptions** — log and exit:
+
+```typescript
+process.on('uncaughtException', (error, origin) => {
+  console.error('Uncaught exception:', error);
+  console.error('Origin:', origin);
+  // Perform synchronous cleanup, then exit
+  process.exit(1);
+});
+```
+
+2. **Handle unhandled promise rejections:**
+
+```typescript
+process.on('unhandledRejection', (reason, promise) => {
+  console.error('Unhandled rejection at:', promise, 'reason:', reason);
+  // In Node.js 15+, unhandled rejections crash the process by default
+});
+```
+
+3. **Always catch async errors:**
+
+```typescript
+// Express: wrap async handlers
+function asyncHandler(fn: (req: Request, res: Response, next: NextFunction) => Promise<void>) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    fn(req, res, next).catch(next);
+  };
+}
+
+app.get(
+  '/users',
+  asyncHandler(async (req, res) => {
+    const users = await getUsers(); // Errors are caught
+    res.json(users);
+  })
+);
+```
+
+4. **Custom error classes:**
+
+```typescript
+class AppError extends Error {
+  constructor(
+    message: string,
+    public statusCode: number = 500,
+    public code: string = 'INTERNAL_ERROR',
+    public isOperational: boolean = true
+  ) {
+    super(message);
+    this.name = 'AppError';
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+class NotFoundError extends AppError {
+  constructor(resource: string, id: string) {
+    super(`${resource} ${id} not found`, 404, 'NOT_FOUND');
+  }
+}
+```
+
+5. **Centralized error handler:**
+
+```typescript
+function errorHandler(err: Error, req: Request, res: Response, next: NextFunction) {
+  if (err instanceof AppError) {
+    res.status(err.statusCode).json({
+      error: { code: err.code, message: err.message },
+    });
+    return;
+  }
+
+  // Unexpected error — log full details, return generic message
+  console.error('Unexpected error:', err);
+  res.status(500).json({
+    error: { code: 'INTERNAL_ERROR', message: 'An unexpected error occurred' },
+  });
+}
+
+app.use(errorHandler);
+```
+
+6. **Operational vs programmer errors:**
+
+```typescript
+// Operational: expected, recoverable (invalid input, network timeout)
+throw new AppError('Email already exists', 400, 'DUPLICATE_EMAIL', true);
+
+// Programmer: unexpected, should crash (null reference, type error)
+// Let these propagate to uncaughtException handler
+```
+
+7. **Graceful shutdown on fatal errors:**
+
+```typescript
+async function gracefulShutdown(signal: string) {
+  console.log(`Received ${signal}, shutting down gracefully`);
+  server.close(() => {
+    db.$disconnect();
+    process.exit(0);
+  });
+
+  setTimeout(() => {
+    console.error('Forced shutdown');
+    process.exit(1);
+  }, 10_000);
+}
+
+process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+```
+
+8. **Error handling in streams:**
+
+```typescript
+import { pipeline } from 'node:stream/promises';
+
+try {
+  await pipeline(readable, transform, writable);
+} catch (err) {
+  // Pipeline handles cleanup of all streams on error
+  console.error('Pipeline failed:', err);
+}
+```
+
+## Details
+
+Node.js error handling spans synchronous throws, async rejections, event emitter errors, and process-level handlers. A comprehensive strategy covers all four.
+
+**Error propagation layers:**
+
+1. `try/catch` — synchronous and `async/await` code
+2. `.catch()` — Promise chains
+3. `'error'` event — EventEmitter instances (streams, servers)
+4. `process.on('uncaughtException')` — last resort for synchronous throws
+5. `process.on('unhandledRejection')` — last resort for unhandled promises
+
+**Operational vs programmer errors:**
+
+- Operational: expected failures that the application can handle (validation errors, timeouts, 404s)
+- Programmer: bugs in the code (null dereference, wrong arguments, logic errors)
+- Operational errors should be caught and handled; programmer errors should crash the process (in production, use a process manager like PM2 to restart)
+
+**Trade-offs:**
+
+- Global error handlers catch everything — but should only log and exit, not attempt recovery
+- Custom error classes enable structured handling — but add code for each error type
+- Graceful shutdown preserves data integrity — but adds shutdown complexity
+- `process.exit(1)` is immediate — but skips cleanup. Use `server.close()` first
+
+## Source
+
+https://nodejs.org/api/process.html#event-uncaughtexception
+
+## 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-error-handling/skill.yaml

@@ -0,0 +1,40 @@
+name: node-error-handling
+version: "1.0.0"
+description: Handle uncaught exceptions, promise rejections, and errors across async Node.js code
+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:
+  - ts-error-handling-types
+  - ts-async-patterns
+  - node-event-emitter
+stack_signals:
+  - nodejs
+  - typescript
+keywords:
+  - uncaughtException
+  - unhandledRejection
+  - error-propagation
+  - process-errors
+  - async-errors
+metadata:
+  author: community
+  upstream: nodejs.org/api/process.html#event-uncaughtexception
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -0,0 +1,149 @@
+# Node.js ESM Patterns
+
+> Write Node.js ES modules correctly using import.meta.url, package.json type, and CJS interop
+
+## When to Use
+
+- Setting up a Node.js project with ES modules
+- Converting CommonJS code to ES modules
+- Handling `__dirname` and `__filename` equivalents in ESM
+- Interoperating between ESM and CommonJS modules
+
+## Instructions
+
+1. **Enable ESM** in `package.json`:
+
+```json
+{ "type": "module" }
+```
+
+All `.js` files are now ESM. Use `.cjs` extension for CommonJS files.
+
+2. **Replace `__dirname` and `__filename`:**
+
+```typescript
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const configPath = join(__dirname, 'config.json');
+```
+
+3. **Dynamic imports:**
+
+```typescript
+const { default: chalk } = await import('chalk');
+
+// Conditional imports
+const db =
+  process.env.DB === 'postgres' ? await import('./db/postgres.js') : await import('./db/sqlite.js');
+```
+
+4. **Import JSON** with import assertions:
+
+```typescript
+import config from './config.json' with { type: 'json' };
+// Or dynamically
+const pkg = await import('./package.json', { with: { type: 'json' } });
+```
+
+5. **Import CommonJS modules from ESM:**
+
+```typescript
+// Default import for CJS modules
+import express from 'express';
+
+// Named imports may not work for all CJS modules
+// Use default import + destructure instead
+import pkg from 'lodash';
+const { pick, omit } = pkg;
+```
+
+6. **Top-level await:**
+
+```typescript
+// Works at module top level in ESM (not in CJS)
+const config = await loadConfig();
+const db = await connectDatabase(config.dbUrl);
+
+export { db, config };
+```
+
+7. **File extensions are required** in imports:
+
+```typescript
+// CJS: works without extension
+const { foo } = require('./utils');
+
+// ESM: extension required
+import { foo } from './utils.js'; // .js even for .ts files with Node16 module resolution
+```
+
+8. **Configure TypeScript for ESM:**
+
+```json
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "ES2022"
+  }
+}
+```
+
+## Details
+
+ES modules are the standard module system for JavaScript. Node.js supports them natively since v12 (stable since v14). ESM is statically analyzable, supports tree-shaking, and uses `import`/`export` syntax.
+
+**ESM vs CJS differences:**
+
+- ESM: `import`/`export`, static analysis, async loading, strict mode by default
+- CJS: `require`/`module.exports`, dynamic, synchronous, non-strict by default
+- ESM can import CJS; CJS cannot `require()` ESM (use dynamic `import()` instead)
+
+**`import.meta`:** ESM-only global with module metadata:
+
+- `import.meta.url` — file URL of the current module (`file:///path/to/module.js`)
+- `import.meta.resolve()` — resolve a module specifier relative to the current module
+
+**Dual package publishing:** Libraries can support both ESM and CJS consumers:
+
+```json
+{
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  }
+}
+```
+
+**Trade-offs:**
+
+- ESM enables tree-shaking — but requires file extensions in imports
+- Top-level await is convenient — but blocks module loading for all importers
+- Static imports enable bundler optimizations — but dynamic imports are needed for conditional loading
+- CJS interop mostly works — but named imports from CJS can fail depending on how the CJS module exports
+
+## Source
+
+https://nodejs.org/api/esm.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-esm-patterns/skill.yaml

@@ -0,0 +1,39 @@
+name: node-esm-patterns
+version: "1.0.0"
+description: Write Node.js ES modules correctly using import.meta.url, package.json type, and CJS interop
+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:
+  - ts-module-patterns
+  - ts-config-patterns
+stack_signals:
+  - nodejs
+  - typescript
+keywords:
+  - ES-modules
+  - import.meta.url
+  - __dirname-equivalent
+  - package-type
+  - CJS-interop
+metadata:
+  author: community
+  upstream: nodejs.org/api/esm.html
+state:
+  persistent: false
+  files: []
+depends_on: []