# Developer Setup Guide

This guide describes how to configure your local development environment to modify, extend, and test the RAVENSTRIKE codebase.

## Prerequisites

- **Node.js**: Version 20 or newer (download from [nodejs.org](https://nodejs.org/))
- **npm**: Version 10 or newer (comes with Node.js)
- **Git** or **GitHub Desktop**: For version control

Verify Node.js and npm are available in your path:

```powershell
node --version
npm --version
```

---

## Getting the Code

### Option A: Using GitHub Desktop

1. Open GitHub Desktop and click **File > Clone repository...**
2. Choose the **URL** tab.
3. Enter `https://github.com/purnanandiboina/RAVENSTRIKE.git`.
4. Choose your local directory path and select **Clone**.
5. Once cloned, go to the top menu and select **Repository > Open in Terminal** (PowerShell or cmd).

### Option B: Using Git CLI

Run the following commands in your shell:

```bash
git clone https://github.com/purnanandiboina/RAVENSTRIKE.git
cd RAVENSTRIKE
```

---

## Installing Development Dependencies

To install all dependencies required for development and testing, run:

```powershell
npm ci
```

> [!NOTE]
> `npm ci` is preferred over `npm install` for local development because it installs the exact dependency versions locked in `package.json` and `package-lock.json`, preventing deviation.

---

## Running Development & Verification Checks

Before pushing any changes or publishing, verify the codebase using the built-in scripts:

### 1. Run Automated Unit Tests
RAVENSTRIKE uses Node.js's built-in test runner. To execute the tests, run:
```powershell
npm test
```

### 2. Run Output Schema Validations
To validate the sample JSON structures and schemas:
```powershell
npm run validate
```

### 3. Run Public Repository Check
To inspect file structures, ensure no sensitive data or temporary files are queued for publishing:
```powershell
npm run check:public
```

### 4. Run Combined Verification Suite
To execute tests, validations, and repository safety checks in one go:
```powershell
npm run check
```

---

## Development Environment Configuration

### OpenAI Adapter Setup

The default adapter is `mock`, which requires no API key and returns heuristic responses. To test integration with actual LLM generation, set up your local environment variables:

```powershell
# In PowerShell:
$env:RAVENSTRIKE_LLM_PROVIDER = "openai"
$env:OPENAI_API_KEY = "your-actual-api-key"
$env:RAVENSTRIKE_OPENAI_MODEL = "gpt-4.1-mini"
$env:RAVENSTRIKE_LLM_TIMEOUT_MS = "30000"
```

For bash/zsh environments:

```bash
export RAVENSTRIKE_LLM_PROVIDER="openai"
export OPENAI_API_KEY="your-actual-api-key"
export RAVENSTRIKE_OPENAI_MODEL="gpt-4.1-mini"
export RAVENSTRIKE_LLM_TIMEOUT_MS="30000"
```

> [!WARNING]
> Never commit API keys or sensitive credentials to the repository. The `.env` file and local test environment files are explicitly ignored in `.gitignore`.

---

## Troubleshooting

- **PowerShell Script Policy Issues**: On Windows, if running `npm` commands fails with execution policy errors (e.g., `Scripts disabled on this system`), try running `npm.cmd` directly or bypass the execution policy:
  ```powershell
  powershell -ExecutionPolicy Bypass -Command "npm run check"
  ```
- **Module Resolution / Dependency errors**: If you encounter `ERR_MODULE_NOT_FOUND` errors, delete your `node_modules` folder and reinstall using `npm ci`.
- **Terminal UI (Blessed) rendering issues**: If the interactive dashboard (`npm run dash`) displays incorrectly, ensure your terminal emulator supports ANSI escape sequences (such as Windows Terminal or VS Code integrated terminal). Alternatively, use the CLI non-interactive mode.