Sealights Node.js Agent

#Preload Script

## Overview

The `preload.js` script serves as an automatic loader for the Sealights Node agent, eliminating the need to explicitly wrap your commands with `slnodejs run`. This script intercepts the normal Node.js execution flow and injects the necessary Sealights installation logic.

---

## Installation

First, install the Sealights Node.js package:

```bash
npm install slnodejs
```

The preload script will be available at:

```
./node_modules/slnodejs/lib/preload.js
```

---

## Usage

### Method 1: Using `-r` flag

```bash
node -r ./node_modules/slnodejs/lib/preload.js your-script.js
```

### Method 2: Using `NODE_OPTIONS`

```bash
export NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js"
node your-script.js
```

Or inline:

```bash
NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js" node your-script.js
```

> Using `NODE_OPTIONS` allows you to persist the preloader configuration across multiple Node.js executions without explicitly specifying the `-r` flag each time.

---

## Environment Variables Configuration

| Variable                   | Description                                 | Default                   |
| -------------------------- | ------------------------------------------- | ------------------------- |
| `SL_TOKEN`                 | Direct Sealights agent authentication token |                           |
| `SL_TOKEN_FILE`            | Path to file containing the Sealights token | `./sltoken.txt`           |
| `SL_BUILD_SESSION_ID`      | Direct build session ID                     |                           |
| `SL_BUILD_SESSION_ID_FILE` | Path to file containing build session ID    | `./buildSessionId`        |
| `SL_PROJECT_ROOT`          | Root directory of your project              | Current working directory |
| `SL_COLLECTOR_URL`         | URL to Sealights collector                  |                           |
| `SL_LAB_ID`                | Lab ID for test execution                   |                           |

---

## Error Handling

The script includes robust error handling mechanisms:

- **Primary Execution:** Attempts to run the target script with Sealights agent configuration
- **Fallback Mechanism:** If the primary execution fails, it falls back to running the original command
- **Uncaught Exception Handler:** Captures and logs any uncaught exceptions

---

## Examples

### Using `-r` Flag

```bash
node -r ./node_modules/slnodejs/lib/preload.js server.js
```

### Using `NODE_OPTIONS`

```bash
# Set for current session
export NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js"
node server.js

# Or inline
NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js" node server.js
```

### Using Environment Variables with `NODE_OPTIONS`

```bash
export NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js"
SL_TOKEN="your-token-here" node server.js
```

### Specifying Custom Paths with `NODE_OPTIONS`

```bash
export NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js"
SL_TOKEN_FILE="/custom/path/token.txt" SL_projectRoot="/path/to/project" node server.js
```

### Using Collector URL and Lab ID with `NODE_OPTIONS`

```bash
export NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js"
SL_TOKEN="your-token-here" SL_COLLECTOR_URL="https://your-collector-url.com" SL_LAB_ID="your-lab-id" node server.js
```

### Debug Mode with `NODE_OPTIONS`

```bash
export NODE_OPTIONS="-r ./node_modules/slnodejs/lib/preload.js"
NODE_DEBUG=sl node server.js
```

---

## Troubleshooting

If you encounter issues:

- Check if the token and build session ID files exist and are readable
- Verify environment variables are set correctly
- Check console output for error messages (turn on `NODE_DEBUG=sl`)
- Ensure the script has necessary permissions to execute

---

## Limitations

- **When using `-r` flag**: Must be explicitly included in each Node.js command
- **When using `NODE_OPTIONS`**: Affects all Node.js processes in the current environment

---

## Best Practices

### Choosing Between `-r` and `NODE_OPTIONS`

#### Use `-r` flag when:

- You want to explicitly control which scripts use the preloader
- You're running in an environment where global Node.js settings should not be modified
- You're running multiple Node.js applications with different configurations

#### Use `NODE_OPTIONS` when:

- You want to ensure all Node.js executions in your session include the preloader
- You're working in a dedicated development environment
- You want to reduce command verbosity
- You're setting up CI/CD pipelines where all Node.js executions should include the preloader and Sealights Agent