word-stress 1.0.0

package/.env.example

@@ -0,0 +1,8 @@
+##
+# .env.example
+#
+# Example environment configuration file
+# Copy this file to .env and modify the values as needed
+#
+LOG_LEVEL=info
+DOTENV_CONFIG_QUIET=true

package/.instructions.md

@@ -0,0 +1,361 @@
+# word-stress Project Instructions
+
+## Project Overview
+
+**word-stress** is a command-line tool for stress-testing WordPress and WooCommerce sites. It measures two critical performance metrics:
+
+1. **Steady-State Throughput**: Maximum sustained request rate with multiple parallel clients polling periodically
+2. **Burst Capacity**: Maximum instantaneous load the server can handle
+
+This helps identify performance bottlenecks, saturation points, and failure thresholds.
+
+---
+
+## Architecture & Design
+
+### Test Modes
+
+#### 1. Steady-State Testing (Default)
+Multiple clients make periodic requests at a fixed interval over a duration.
+
+**Parameters:**
+- `--clients` (default: 5) - Number of parallel clients
+- `--interval` (default: 1000) - Milliseconds between each client's requests
+- `--duration` (default: 60) - Test duration in seconds
+- `--endpoint` (default: `/`) - URL path to test
+- `--method` (default: GET) - HTTP method
+- `--https` (default: on) - Enable/disable HTTPS
+
+**Behavior:**
+Each client independently:
+1. Makes a request
+2. Waits for response (or timeout)
+3. Waits until interval has elapsed since request start
+4. Repeats until duration expires
+
+**Example:**
+```bash
+# 5 clients × 60 requests (1000ms interval × 60s) = ~300 total requests
+word-stress example.com
+
+# WooCommerce AJAX endpoint
+word-stress --clients=10 --interval=500 \
+  --endpoint='/?wc-ajax=get_refreshed_fragments' --method=POST example.com
+```
+
+#### 2. Burst Testing
+Simultaneous requests to measure peak instantaneous capacity.
+
+**Parameters:**
+- `--mode=burst` - Enable burst testing
+- `--burst-clients` (required) - Number of simultaneous requests
+- `--endpoint` (default: `/`) - URL path to test
+- `--method` (default: GET) - HTTP method
+- `--https` (default: on) - Enable/disable HTTPS
+
+**Behavior:**
+1. Launch all requests simultaneously
+2. Measure response times and status codes
+3. Record timeouts and errors
+4. Report aggregate metrics
+
+**Example:**
+```bash
+# 50 simultaneous requests
+word-stress --mode=burst --burst-clients=50 example.com
+
+# 1000 simultaneous AJAX requests
+word-stress --mode=burst --burst-clients=1000 \
+  --endpoint='/?wc-ajax=get_refreshed_fragments' --method=POST example.com
+```
+
+#### 3. Spike-and-Decay Testing (Future Enhancement)
+Simulates traffic spikes that gradually tail off to a higher steady state. Useful for real-world patterns like flash sales or viral content.
+
+### Global Parameters
+
+- `--timeout` (default: 30000) - Request timeout in milliseconds
+- `--follow-redirects` (default: true) - Follow HTTP redirects
+- `--output` (default: table | options: json, csv) - Output format
+- `--https` (default: on) - Enable/disable HTTPS
+
+---
+
+## CLI Framework Design
+
+### Technology Stack
+
+**Command Parsing:**
+- `commander` - Industry standard, simple API, excellent for subcommands
+
+**Interactive Prompts:**
+- `inquirer` - For future interactive configuration setup
+
+**Terminal Output:**
+- `chalk` - Terminal string styling and colors
+- `ora` - Progress spinners
+- `cli-table3` - Pretty unicode tables for results
+
+**Configuration:**
+- `dotenv` - Load environment variables from .env files
+
+**HTTP Requests:**
+- Node.js built-in **Fetch API** - For HTTP requests (no axios needed initially)
+
+**Logging:**
+- Simple custom logger wrapping `console.log()` and `console.error()`
+
+### Command Structure
+
+```
+word-stress <domain> [options]
+
+Commands:
+  word-stress help          Show help
+  word-stress --version     Show version
+
+Options:
+  Steady-State Mode:
+    --clients <n>         Number of parallel clients (default: 5)
+    --interval <ms>       Request interval in ms (default: 1000)
+    --duration <s>        Test duration in seconds (default: 60)
+  
+  Burst Mode:
+    --mode=burst          Enable burst testing
+    --burst-clients <n>   Number of simultaneous requests (required)
+  
+  Common:
+    --endpoint <path>     URL path to test (default: /)
+    --method <METHOD>     HTTP method (default: GET)
+    --https <on|off>      Use HTTPS (default: on)
+    --timeout <ms>        Request timeout (default: 30000)
+    --output <format>     Output format: table|json|csv (default: table)
+```
+
+### Centralized Configuration
+
+All environment variables and defaults are normalized in a single config module:
+- Loads and validates configuration at startup
+- Provides type-safe configuration object
+- Makes testing easier (mock config, not `process.env`)
+- Clear defaults visible in one place
+
+**Example structure:**
+```javascript
+// src/config.js
+module.exports = {
+  // Test parameters
+  clients: process.env.WS_CLIENTS || 5,
+  interval: process.env.WS_INTERVAL || 1000,
+  duration: process.env.WS_DURATION || 60,
+  // ...
+};
+```
+
+---
+
+## Metrics & Collection
+
+### Per-Request Metrics
+- Response time (ms)
+- HTTP status code
+- Response size (bytes)
+- Error type (timeout, network error, etc.)
+
+### Aggregate Metrics
+- Total requests sent
+- Successful responses (2xx, 4xx, 5xx counts and percentages)
+- Timeout count
+- Response time percentiles (min, max, avg, median, P95, P99)
+- Requests per second (actual throughput)
+- Total data transferred
+- Test duration
+
+### Future Enhancements
+- Time-series data (response times over time)
+- Error rate degradation patterns
+- Throughput trends
+
+---
+
+## Output Format
+
+### Default: Console Tables
+
+Pretty-formatted output showing:
+- Test configuration summary
+- Status code distribution table
+- Response time statistics table
+- Throughput metrics
+
+**Example:**
+```
+═══════════════════════════════════════════════════════
+  Stress Test Results
+═══════════════════════════════════════════════════════
+
+Target: https://example.com
+Test Mode: Steady-State
+Duration: 60.2s
+Clients: 5
+Interval: 1000ms
+Total Requests: 300
+
+┌─────────────────────┬──────────────┐
+│ Metric              │ Value        │
+├─────────────────────┼──────────────┤
+│ Successful (2xx)    │ 298 (99.3%)  │
+│ Client Error (4xx)  │ 0 (0%)       │
+│ Server Error (5xx)  │ 2 (0.7%)     │
+│ Timeouts            │ 0 (0%)       │
+└─────────────────────┴──────────────┘
+
+Response Times (ms):
+┌─────────┬──────────┐
+│ Min     │ 89       │
+│ Max     │ 2156     │
+│ Avg     │ 245      │
+│ Median  │ 198      │
+│ P95     │ 567      │
+│ P99     │ 1234     │
+└─────────┴──────────┘
+
+Throughput: 4.98 req/s
+Data Transferred: 2.1 MB
+```
+
+### JSON Export
+Machine-readable format for analysis tools and spreadsheets.
+
+### CSV Export
+For spreadsheet analysis and comparing multiple test runs.
+
+---
+
+## Implementation Decisions
+
+### Decision: Fetch API over Axios
+**Rationale:** Node.js now has built-in Fetch API support. Start with built-in to minimize dependencies. Switch to axios only if we need advanced features (interceptors, request/response transformation).
+
+### Decision: Simple Logger over Winston/Pino
+**Rationale:** Avoid heavy logging frameworks. Implement a simple custom logger wrapping `console.log()` and `console.error()` with `LOG_LEVEL` support. Keeps the project lightweight.
+
+### Decision: Table Output First, Live UI Later
+**Rationale:** Start with simple final-report tables using `cli-table3`. Live updating UI deferred to future enhancement. Reduces initial complexity while still providing useful output.
+
+### Decision: No Authentication in Phase 1
+**Rationale:** Test AJAX endpoints and public endpoints without authentication. Authentication support (basic auth, cookies, tokens) deferred to future phases.
+
+### Decision: Metrics Streaming, Not Stored
+**Rationale:** Don't store full response bodies or all request details in memory. Calculate percentiles and aggregate metrics incrementally. Save memory for long-running tests.
+
+---
+
+## Development Workflows
+
+### Adding a New Test Mode
+
+1. Add mode to CLI with `commander` in `src/cli/commands.js`
+2. Create test mode class in `src/test-modes/` (e.g., `SpikeDayTestMode.js`)
+3. Implement `run()` method that:
+   - Spawns clients/requests
+   - Collects metrics
+   - Returns aggregated results
+4. Add test mode to factory in `src/test-modes/factory.js`
+5. Document in `.instructions.md` and `dev-notes/02-stress-test-requirements.md`
+
+### Adding a New Output Format
+
+1. Create formatter in `src/formatters/` (e.g., `XMLFormatter.js`)
+2. Implement `format(results)` method
+3. Add formatter to factory in `src/formatters/factory.js`
+4. Update CLI `--output` options
+
+### Adding Metrics Collection
+
+1. Update `MetricsCollector` class
+2. Add per-request metric calculation
+3. Update aggregate calculation
+4. Update output formatters to display new metrics
+
+---
+
+## Module Structure (Planned)
+
+```
+src/
+├── bin/word-stress              # Executable entry point
+├── cli/
+│   ├── commands.js             # Commander.js setup
+│   └── help.js                 # Help text
+├── config.js                   # Centralized configuration
+├── test-modes/
+│   ├── SteadyStateTestMode.js  # Steady-state implementation
+│   ├── BurstTestMode.js        # Burst implementation
+│   └── factory.js              # Test mode factory
+├── http/
+│   └── client.js               # HTTP request handling
+├── metrics/
+│   └── MetricsCollector.js     # Metrics aggregation
+├── formatters/
+│   ├── TableFormatter.js       # Pretty table output
+│   ├── JsonFormatter.js        # JSON export
+│   ├── CsvFormatter.js         # CSV export
+│   └── factory.js              # Formatter factory
+├── logger.js                   # Custom logger
+└── main.js                     # Application entry point
+```
+
+---
+
+## Error Handling
+
+### Request Errors
+- Network errors → Record as "Network Error"
+- Timeouts → Record as timeout, increment timeout counter
+- HTTP errors (4xx, 5xx) → Record status code, count by category
+
+### Behavior
+- Continue testing even if individual requests fail
+- Never abort test due to errors
+- Track and report error patterns
+
+### Reporting
+- Distinguish error types in output
+- Report error percentages
+- Highlight concerning error patterns (e.g., >10% error rate)
+
+---
+
+## Testing & Quality
+
+### Unit Tests
+- Test metrics calculation (percentiles, aggregates)
+- Test formatters with sample data
+- Test configuration validation
+
+### Integration Tests
+- Mock HTTP requests, test full test-mode flow
+- Test CLI parameter parsing
+- Test output formatting
+
+### Manual Testing
+- Run against local WordPress/WooCommerce installation
+- Verify steady-state behavior matches expectations
+- Verify burst requests all send simultaneously
+- Verify output formatting accuracy
+
+---
+
+## Next Steps
+
+1. ✅ Define requirements and test modes
+2. ✅ Select dependencies
+3. ✅ Design CLI interface
+4. → Set up CLI framework with commander
+5. → Implement HTTP client with Fetch API
+6. → Implement steady-state test mode
+7. → Implement burst test mode
+8. → Build metrics collector
+9. → Create output formatters
+10. → Add comprehensive testing

package/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-01-07
+
+### Added - Phase 1: Project Setup
+- Initial project scaffolding with proper directory structure
+- Git repository initialization with comprehensive .gitignore
+- npm package configuration with Node.js 21+ requirement
+- AI instruction files (.github/copilot-instructions.md, .instructions.md)
+
+### Added - Phase 2: CLI Framework
+- Commander.js CLI with full parameter parsing and validation
+- Centralized configuration module with environment variable support
+- Custom logger with LOG_LEVEL support
+- Comprehensive help and version output
+- All CLI parameters: clients, interval, duration, mode, burst-clients, endpoint, method, https, timeout, follow-redirects, output, verbose
+
+### Added - Phase 3: HTTP Client
+- Native Fetch API HTTP client with timeout handling (AbortController)
+- Request methods: GET, POST, PUT, DELETE, PATCH
+- Error classification: network errors, timeouts, HTTP errors
+- Response size tracking and calculation
+- Response time measurement in milliseconds
+- Redirect handling support
+
+### Added - Phase 4: Metrics Collection
+- MetricsCollector class with per-request and aggregate metrics
+- Response time statistics: min, max, average, median, P95, P99
+- Status code distribution tracking (2xx, 3xx, 4xx, 5xx)
+- Error tracking and classification
+- Throughput calculation (requests/second)
+- Data transferred measurement
+- Success rate calculation
+
+### Added - Phase 5: Steady-State Test Mode
+- Multiple concurrent clients with independent request scheduling
+- Fixed interval-based request timing (configurable milliseconds)
+- Duration-based testing (configurable seconds)
+- Graceful handling of timing and request synchronization
+- Full integration with HTTP client and metrics collection
+
+### Added - Phase 6: Burst Test Mode
+- Simultaneous request launching with Promise.all()
+- Peak capacity measurement
+- Concurrent request handling without timing constraints
+- Error tracking during burst loads
+
+### Added - Phase 7: Output Formatters
+- TableFormatter: Beautiful ASCII tables using cli-table3
+  - Summary metrics table
+  - Response time statistics table with percentiles
+  - Status code distribution table
+  - Error details table (when applicable)
+- JsonFormatter: Pretty-printed JSON output for programmatic parsing
+- CsvFormatter: CSV format with proper escaping for spreadsheet import
+
+### Added - User Agent Support
+- Browser presets: Firefox, Chrome, Safari with realistic user agent strings
+- Custom user agent support via --user-agent parameter
+- user-agents npm package for up-to-date browser user agents
+- Proper User-Agent header in all HTTP requests
+
+### Added - Code Quality
+- ESLint with recommended rules for Node.js
+- Prettier for automatic code formatting
+- npm scripts: format, format:check, lint, lint:fix, test, audit
+- All code passing linting and formatting standards
+- Zero security vulnerabilities
+
+### Added - Documentation
+- Comprehensive README with usage examples
+- Portable Node.js CLI development standards in .github/copilot-instructions.md
+- Architecture and design documentation in .instructions.md
+- Project tracker in dev-notes/00-project-tracker.md
+
+### Testing
+- Tested against local WordPress installation (http://leyland.local/)
+- Burst testing: 90+ req/s throughput with 100% success rate
+- Steady-state testing: Proper interval-based scheduling verified
+- All three output formats tested and working
+- User agent headers verified in server access logs
+
+[1.0.0]: https://github.com/headwalluk/word-stress/releases/tag/v1.0.0

package/PUBLISHING.md

@@ -0,0 +1,103 @@
+# Publishing to npm
+
+This guide explains how to publish `word-stress` to the npm registry.
+
+## Prerequisites
+
+1. Node.js 21+ installed
+2. npm account (you have one at https://www.npmjs.com/~headwall)
+3. Git repository with all changes committed
+
+## Publishing Steps
+
+### 1. Ensure You're Logged Into npm
+
+```bash
+npm login
+# Enter your npm username: headwall
+# Enter your password: [your npm password]
+# Enter your email: [your registered email]
+```
+
+### 2. Verify Package Details
+
+Before publishing, verify the package information:
+
+```bash
+# Check the package will be published correctly
+npm publish --dry-run
+
+# Review what files will be included
+npm pack --dry-run
+```
+
+### 3. Publish to npm Registry
+
+```bash
+npm publish
+```
+
+This will:
+- Upload `word-stress` to npm registry
+- Make it available at https://www.npmjs.com/package/word-stress
+- Allow users to install via: `npm install -g word-stress` or `npx word-stress`
+
+### 4. Verify Publication
+
+After publishing, verify it's available:
+
+```bash
+npm info word-stress
+npm view word-stress versions
+```
+
+### 5. Test Installation via npx
+
+After publication, anyone with Node.js 21+ can run:
+
+```bash
+npx word-stress --duration 10 example.com
+```
+
+## Updating the Package
+
+To release a new version:
+
+1. Update version in `package.json`:
+   ```bash
+   npm version patch  # for bugfixes (1.0.0 → 1.0.1)
+   npm version minor  # for features (1.0.0 → 1.1.0)
+   npm version major  # for breaking changes (1.0.0 → 2.0.0)
+   ```
+
+2. Create git tag:
+   ```bash
+   git tag -a v1.0.1 -m "Release version 1.0.1"
+   git push origin main --tags
+   ```
+
+3. Publish new version:
+   ```bash
+   npm publish
+   ```
+
+## Package Size Optimization
+
+The `.npmignore` file ensures minimal package size by excluding:
+- Development configuration files
+- Development notes
+- Tests
+- GitHub workflows
+- IDE configuration
+
+Current estimated package size: ~50KB (with dependencies ~500KB installed)
+
+## Reverting a Publication
+
+If you need to unpublish a version within 72 hours of publication:
+
+```bash
+npm unpublish word-stress@1.0.0
+```
+
+For production packages, it's better to release a patch version instead of unpublishing.

package/README.md

@@ -0,0 +1,120 @@
+# word-stress
+
+A command-line tool for stress-testing WordPress and WooCommerce sites.
+
+## Overview
+
+`word-stress` is a performance testing tool designed to identify bottlenecks, saturation points, and failure thresholds in WordPress and WooCommerce installations. It sends configurable parallel requests to measure server capacity and response degradation under load.
+
+## Project Status
+
+✅ **Version 1.0.0** - Feature complete and production ready!
+
+## Features
+
+- ✅ Steady-state load testing with multiple concurrent clients
+- ✅ Burst capacity testing with simultaneous requests
+- ✅ Configurable intervals, durations, and timeouts
+- ✅ WordPress and WooCommerce endpoint testing (GET/POST/PUT/DELETE/PATCH)
+- ✅ Comprehensive metrics: response times, percentiles (P95, P99), throughput, success rate
+- ✅ Realistic user agent support (Chrome, Firefox, Safari, or custom)
+- ✅ Beautiful ASCII table output
+- ✅ JSON and CSV export formats
+- ✅ HTTP/HTTPS with redirect handling
+- ✅ Request timeout support
+- ✅ Detailed error classification and tracking
+
+## Installation
+
+```bash
+npm install
+```
+
+## Usage
+
+### Steady-State Testing
+Tests with multiple parallel clients making periodic requests.
+
+```bash
+# Default: 5 clients, 1000ms interval, 60 second duration
+./bin/word-stress example.com
+
+# 10 clients with 500ms interval
+./bin/word-stress --clients=10 --interval=500 example.com
+
+# WooCommerce AJAX endpoint
+./bin/word-stress --clients=20 --interval=1000 \
+  --endpoint='/?wc-ajax=get_refreshed_fragments' --method=POST example.com
+
+# Test local development site without HTTPS
+./bin/word-stress --clients=5 --https=off example.dev
+```
+
+### Burst Testing
+Tests with many simultaneous requests to measure peak capacity.
+
+```bash
+# 50 simultaneous requests
+./bin/word-stress --mode=burst --burst-clients=50 example.com
+
+# 1000 simultaneous AJAX requests
+./bin/word-stress --mode=burst --burst-clients=1000 \
+  --endpoint='/?wc-ajax=get_refreshed_fragments' --method=POST example.com
+```
+
+### Output Formats
+
+```bash
+# Pretty table output (default)
+./bin/word-stress example.com
+
+# JSON export
+./bin/word-stress --output=json example.com
+
+# CSV export
+./bin/word-stress --output=csv example.com
+```
+
+### Help
+
+```bash
+./bin/word-stress --help
+./bin/word-stress --version
+```
+
+See [dev-notes/02-stress-test-requirements.md](dev-notes/02-stress-test-requirements.md) for detailed usage examples and requirements.
+
+## Documentation
+
+- [docs/](./docs) - Public-facing documentation
+- [dev-notes/](./dev-notes) - Development notes and requirements
+- [.github/copilot-instructions.md](.github/copilot-instructions.md) - AI coding standards
+
+## Development
+
+### Dependencies
+
+- **commander** - Command-line interface
+- **chalk** - Terminal colors
+- **ora** - Progress spinners
+- **cli-table3** - Result tables
+- **dotenv** - Environment configuration
+
+### Node Version
+
+Requires Node.js 21 or greater for Fetch API support.
+
+### Project Structure
+
+- `src/` - Source code (config, CLI setup, HTTP client, metrics, test modes, formatters)
+- `bin/` - Executable entry point
+- `dev-notes/` - Development notes and requirements
+- [.instructions.md](.instructions.md) - Project architecture and design decisions
+
+### Contributing
+
+See [.github/copilot-instructions.md](.github/copilot-instructions.md) for coding standards and best practices.
+
+## License
+
+MIT

package/bin/word-stress

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+/**
+ * word-stress CLI executable
+ * Entry point for the command-line tool
+ */
+
+const { setupCli } = require('../src/cli/commands');
+const { main } = require('../src/main');
+
+async function run() {
+  const program = setupCli();
+
+  program.action((domain, options) => {
+    // Parse arguments and pass to main
+    const args = {
+      domain,
+      ...options,
+    };
+    main(args);
+  });
+
+  program.parse(process.argv);
+}
+
+run().catch(error => {
+  console.error('Unexpected error:', error.message);
+  process.exit(1);
+});