@contextrail/code-review-agent 0.1.1-alpha.0

package/LICENSE

@@ -0,0 +1,26 @@
+Copyright (c) 2026 ContextRail. All rights reserved.
+
+Source-Available License
+
+You may:
+  - Use the Software for any purpose.
+  - Modify the Software for your own internal use.
+
+You may not, without prior written consent from ContextRail:
+  - Redistribute the Software (original or modified), in source or binary form.
+  - Use the Software to provide a competing product or service.
+  - Use the Software (including its source code, outputs, or documentation) to
+    train, fine-tune, or improve machine learning models (including large
+    language models or other AI systems), or allow third parties to do so.
+  - Use automated systems (including LLMs or other AI) to scrape, replicate, or
+    redistribute the Software or to create derivative works for distribution.
+
+Contact ContextRail contextrail@gmail.com for redistribution, commercial licensing, or ML/LLM use terms.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. IN NO EVENT SHALL
+CONTEXTRAIL OR ITS CONTRIBUTORS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MODEL_RECOMMENDATIONS.md

@@ -0,0 +1,178 @@
+# Model Recommendations for Code Review Agent
+
+This guide helps you choose cost-effective models that work well with structured output for code reviews.
+
+## Quick Reference: Low-Cost Models
+
+### ✅ Recommended Low-Cost Models (Structured Output Compatible)
+
+| Model                                | Cost (per 1M tokens) | Speed     | Quality   | Best For                          |
+| ------------------------------------ | -------------------- | --------- | --------- | --------------------------------- |
+| **google/gemini-2.0-flash-exp**      | ~$0.075              | Very Fast | Good      | Orchestrator, Synthesis, Decision |
+| **google/gemini-3-flash-preview**    | ~$0.075              | Very Fast | Good      | Orchestrator, Synthesis, Decision |
+| **anthropic/claude-haiku-4.5**       | ~$0.25               | Fast      | Excellent | Reviewers, Orchestrator (default) |
+| **anthropic/claude-sonnet-4.5**      | ~$3.00               | Medium    | Excellent | Critic, Complex Reviews           |
+| **meta-llama/llama-3.1-8b-instruct** | ~$0.05               | Fast      | Good      | Budget Reviews                    |
+
+### ⚠️ Models to Avoid (Structured Output Issues)
+
+- `deepseek/deepseek-v3.2` - Known to return empty responses with structured output
+- Models without explicit structured output support
+- Very old model versions
+
+## Cost Optimization Strategies
+
+### Strategy 1: Tiered Model Approach (Recommended)
+
+Use cheaper models for simpler tasks, more capable models for complex analysis:
+
+```bash
+# Orchestrator: Fast, cheap model
+export LLM_MODEL_ORCHESTRATOR="google/gemini-3-flash-preview"
+
+# Reviewers: Balanced cost/quality
+export LLM_MODEL_REVIEWER="anthropic/claude-haiku-4.5"
+
+# Critic: Higher quality for validation
+export LLM_MODEL_CRITIC="anthropic/claude-sonnet-4.5"
+```
+
+**Estimated cost per review**: ~$0.01-0.05 (depending on PR size)
+
+### Strategy 2: Ultra-Low-Cost (Budget)
+
+Use cheapest models throughout:
+
+```bash
+export LLM_MODEL_ORCHESTRATOR="google/gemini-2.0-flash-exp"
+export LLM_MODEL_REVIEWER="google/gemini-2.0-flash-exp"
+export LLM_MODEL_CRITIC="google/gemini-3-flash-preview"
+```
+
+**Estimated cost per review**: ~$0.005-0.02
+
+### Strategy 3: Quality-Focused (Higher Cost)
+
+Use Claude models throughout for best quality:
+
+```bash
+export LLM_MODEL_ORCHESTRATOR="anthropic/claude-haiku-4.5"
+export LLM_MODEL_REVIEWER="anthropic/claude-haiku-4.5"
+export LLM_MODEL_CRITIC="anthropic/claude-sonnet-4.5"
+```
+
+**Estimated cost per review**: ~$0.02-0.10
+
+## Model Selection Guide
+
+### For Orchestrator
+
+**Purpose**: Select reviewers, understand changes
+**Requirements**: Fast, reliable structured output
+**Recommendations**:
+
+- ✅ `google/gemini-3-flash-preview` (cheapest, fast)
+- ✅ `anthropic/claude-haiku-4.5` (default, reliable)
+- ⚠️ Avoid: Very slow models, models without structured output
+
+### For Reviewers
+
+**Purpose**: Analyze code, find issues
+**Requirements**: Good code understanding, structured output
+**Recommendations**:
+
+- ✅ `anthropic/claude-haiku-4.5` (default, excellent quality)
+- ✅ `google/gemini-3-flash-preview` (cheaper alternative)
+- ⚠️ Avoid: Models that struggle with code analysis
+
+### For Critic
+
+**Purpose**: Validate findings, reduce false positives
+**Requirements**: High quality reasoning, structured output
+**Recommendations**:
+
+- ✅ `anthropic/claude-sonnet-4.5` (default, best quality)
+- ✅ `anthropic/claude-haiku-4.5` (if cost is concern)
+- ⚠️ Avoid: Low-quality models (defeats purpose of critic)
+
+## Testing Model Compatibility
+
+If you want to try a new model, test it first:
+
+```bash
+# Test with a small PR
+export LLM_MODEL_REVIEWER="your-model-name"
+export DEBUG=1  # Enable debug logging
+
+# Run a review and check logs for:
+# - "[LLM] No structured output received" warnings
+# - Empty responses
+# - JSON parsing errors
+```
+
+## Cost Estimation
+
+Based on typical PR sizes:
+
+| PR Size             | Input Tokens | Output Tokens | Cost (Gemini Flash) | Cost (Claude Haiku) |
+| ------------------- | ------------ | ------------- | ------------------- | ------------------- |
+| Small (1-3 files)   | ~5K          | ~2K           | ~$0.0005            | ~$0.0018            |
+| Medium (5-10 files) | ~15K         | ~5K           | ~$0.0015            | ~$0.005             |
+| Large (20+ files)   | ~50K         | ~15K          | ~$0.005             | ~$0.016             |
+
+**Note**: Costs vary based on:
+
+- Number of reviewers selected
+- Number of iterations (if findings need validation)
+- Amount of context retrieved from ContextRail
+- Model pricing (check OpenRouter for current rates)
+
+## Finding Current Pricing
+
+1. Visit [OpenRouter Models](https://openrouter.ai/models)
+2. Filter by:
+    - `supported_parameters=structured_outputs`
+    - Sort by pricing (low to high)
+3. Check the model card for:
+    - Input/output token pricing
+    - Structured output support
+    - Speed/latency information
+
+## Troubleshooting Model Issues
+
+### Problem: Empty responses / "No object generated"
+
+**Symptoms**: Model consumes tokens but returns empty text
+**Solution**:
+
+- Try a different model (Gemini Flash or Claude Haiku)
+- Check model compatibility with structured output
+- Verify model name is correct
+
+### Problem: JSON parsing errors
+
+**Symptoms**: Model returns text but not valid JSON
+**Solution**:
+
+- Use a model with better structured output support
+- Check if model requires special formatting
+- Review debug logs for actual response
+
+### Problem: High costs
+
+**Solution**:
+
+- Switch to Gemini Flash models
+- Reduce `maxSteps` or `maxIterations`
+- Use fewer reviewers
+- Enable token caching if available
+
+## Default Configuration
+
+The agent defaults to:
+
+- **Orchestrator**: `anthropic/claude-haiku-4.5` (~$0.25/1M tokens)
+- **Reviewer**: `anthropic/claude-haiku-4.5` (~$0.25/1M tokens)
+- **Critic**: `anthropic/claude-sonnet-4.5` (~$3.00/1M tokens)
+
+These defaults balance cost and quality. For lower costs, switch to Gemini Flash models.

package/README.md

@@ -0,0 +1,177 @@
+---
+title: 'Code Review Agent Client Integration Guide'
+owner: platform-eng
+status: draft
+last_reviewed: 2026-02-10
+audience: developers integrating code-review-agent in client repositories
+purpose: Provide user-facing installation and execution guidance for npm-distributed code-review-agent.
+user_need: do
+doc_form: how-to-guide
+location: packages/code-review-agent/README.md
+---
+
+# [Context Rail](https://contextrail.app): Code Review Agent Client Integration Guide
+
+## Summary
+
+`@contextrail/code-review-agent` is a CLI for running structured, AI-assisted PR/code reviews in your repository.
+
+Use it to:
+
+- review a git diff (`--from` / `--to`)
+- review explicit files (`--files` / `--file`)
+- emit machine-readable review artifacts (`result.json`, reviewer logs, token metrics)
+
+## Install and Run
+
+Choose one:
+
+- **No install (recommended to start):**
+
+```bash
+npx -y @contextrail/code-review-agent review --help
+```
+
+- **Project dependency:**
+
+```bash
+npm i -D @contextrail/code-review-agent
+npx code-review-agent review --help
+```
+
+- **Global install:**
+
+```bash
+npm i -g @contextrail/code-review-agent
+code-review-agent review --help
+```
+
+## Required Environment Variables
+
+```bash
+export CONTEXTRAIL_MCP_SERVER_URL="https://<your-mcp-host>"
+export CONTEXTRAIL_MCP_JWT_TOKEN="<your-contextrail-jwt-token>"
+export OPENROUTER_API_KEY="<your-openrouter-key>"
+```
+
+### Getting Your ContextRail MCP Token
+
+To get your `CONTEXTRAIL_MCP_JWT_TOKEN`:
+
+1. **Sign up** at [https://contextrail.app](https://contextrail.app) (if you don't have an account)
+2. **Get your token** at [https://contextrail.app/settings/profile](https://contextrail.app/settings/profile)
+
+The token is used to authenticate with the ContextRail MCP server to retrieve your organization's review standards and contexts.
+
+Optional:
+
+```bash
+export LLM_MODEL_ORCHESTRATOR="google/gemini-3-flash-preview"
+export LLM_MODEL_REVIEWER="qwen/qwen3-coder-next"
+export LLM_MODEL_CRITIC="qwen/qwen3-coder-next"
+export REVIEW_DOMAINS="security,architecture"
+export PR_DESCRIPTION="Optional PR context"
+```
+
+## Run Against a PR Diff
+
+```bash
+git fetch origin
+BASE_SHA="$(git merge-base origin/main HEAD)"
+HEAD_SHA="$(git rev-parse HEAD)"
+
+npx -y @contextrail/code-review-agent review \
+  --repo . \
+  --from "$BASE_SHA" \
+  --to "$HEAD_SHA" \
+  --output ./.review
+```
+
+With optional domain focus:
+
+```bash
+npx -y @contextrail/code-review-agent review \
+  --repo . \
+  --from "$BASE_SHA" \
+  --to "$HEAD_SHA" \
+  --domains "security,architecture" \
+  --output ./.review
+```
+
+## Run Against Explicit Files
+
+```bash
+npx -y @contextrail/code-review-agent review \
+  --repo . \
+  --files "src/a.ts,src/b.ts" \
+  --output ./.review
+```
+
+or:
+
+```bash
+npx -y @contextrail/code-review-agent review \
+  --repo . \
+  --file src/a.ts \
+  --file src/b.ts \
+  --output ./.review
+```
+
+## Local Change Recipes
+
+Staged files:
+
+```bash
+FILES_CSV="$(git diff --name-only --cached | paste -sd, -)"
+[ -z "$FILES_CSV" ] && echo "No staged tracked files to review." && exit 1
+npx -y @contextrail/code-review-agent review --repo . --files "$FILES_CSV" --output ./.review
+```
+
+Unstaged files:
+
+```bash
+FILES_CSV="$(git diff --name-only | paste -sd, -)"
+[ -z "$FILES_CSV" ] && echo "No unstaged tracked files to review." && exit 1
+npx -y @contextrail/code-review-agent review --repo . --files "$FILES_CSV" --output ./.review
+```
+
+Tracked changes vs `HEAD`:
+
+```bash
+FILES_CSV="$(git diff --name-only HEAD | paste -sd, -)"
+[ -z "$FILES_CSV" ] && echo "No tracked local changes vs HEAD." && exit 1
+npx -y @contextrail/code-review-agent review --repo . --files "$FILES_CSV" --output ./.review
+```
+
+## Output and Exit Behavior
+
+Primary output:
+
+- `./.review/result.json`
+
+Additional artifacts:
+
+- `./.review/orchestrator/*`
+- `./.review/reviewers/<reviewer>/*`
+- `./.review/token-budget.json`
+
+Exit codes:
+
+- `0`: all reviewers validated and final decision is approve
+- `1`: reviewer validation failed and/or final decision is request-changes
+
+## Troubleshooting
+
+- **`Command "code-review-agent" not found`**
+    - use `npx -y @contextrail/code-review-agent ...` or install globally
+- **Missing required env vars**
+    - set `CONTEXTRAIL_MCP_SERVER_URL`, `CONTEXTRAIL_MCP_JWT_TOKEN`, and `OPENROUTER_API_KEY`
+- **One reviewer failed with structured-output/schema errors**
+    - inspect `./.review/reviewers/<reviewer>/failures.md`
+    - inspect `./.review/reviewers/<reviewer>/progress.json`
+
+## Related
+
+- contributor guide: `packages/code-review-agent/CONTRIBUTORS.md`
+- npm publishing guide: `packages/code-review-agent/NPM_PUBLISHING.md`
+- model cost guide: `packages/code-review-agent/MODEL_RECOMMENDATIONS.md`

package/dist/config/defaults.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Default model for orchestrator calls.
+ * Chosen for fast planning/synthesis while preserving structured-output reliability.
+ */
+export declare const DEFAULT_ORCHESTRATOR_MODEL = "google/gemini-3-flash-preview";
+/**
+ * Default model for reviewer iterations.
+ * Tuned for code-centric reasoning with acceptable latency/cost.
+ */
+export declare const DEFAULT_REVIEWER_MODEL = "qwen/qwen3-coder-next";
+/**
+ * Default critic model used when no critic model is explicitly configured.
+ */
+export declare const DEFAULT_CRITIC_MODEL = "google/gemini-3-flash-preview";
+/**
+ * Maximum tool/LLM steps per call for orchestrator/reviewer operations.
+ */
+export declare const DEFAULT_MAX_STEPS = 10;
+/**
+ * Maximum validation loops per reviewer (initial pass + critic pass).
+ */
+export declare const DEFAULT_MAX_ITERATIONS = 2;
+/**
+ * Maximum tool/LLM steps for synthesis and final decision generation.
+ */
+export declare const DEFAULT_AGGREGATION_MAX_STEPS = 5;
+/**
+ * Default temperature for structured output generation.
+ * Lower temperature (0-0.3) improves reliability and consistency for structured output.
+ */
+export declare const DEFAULT_TEMPERATURE = 0.2;
+/**
+ * Default timeout for LLM calls in milliseconds (2 minutes).
+ * Prevents hanging on slow or unresponsive models.
+ */
+export declare const DEFAULT_LLM_TIMEOUT_MS = 120000;
+/**
+ * Default max tokens for structured output generation.
+ * Ensures enough tokens for complete structured responses.
+ * Set to undefined to use model default (typically 4096-8192).
+ */
+export declare const DEFAULT_MAX_TOKENS: undefined;
+/**
+ * Get default critic model based on reviewer model.
+ * If reviewer uses haiku, critic uses sonnet (and vice versa).
+ * This ensures structural independence between review and critique.
+ */
+export declare const getDefaultCriticModel: (reviewerModel: string | undefined) => string;
+/**
+ * Default configuration for surrounding context extraction.
+ */
+export declare const DEFAULT_SURROUNDING_CONTEXT_CONFIG: {
+    readonly enabled: true;
+    readonly maxTokensPerFile: 20000;
+    readonly contextLines: 10;
+};
+/**
+ * Default file patterns to exclude from code review.
+ * These patterns match common build artifacts, lockfiles, and generated code.
+ * Uses glob patterns (minimatch) instead of regex to avoid ReDoS vulnerabilities.
+ */
+export declare const DEFAULT_EXCLUDE_PATTERNS: readonly ["**/*.lock", "**/package-lock.json", "**/pnpm-lock.yaml", "**/yarn.lock", "**/dist/**", "**/build/**", "**/out/**", "**/.next/**", "**/.turbo/**", "**/*.generated.*", "**/*.gen.*", "**/node_modules/**", "**/.vscode/**", "**/.idea/**", ".DS_Store", "**/coverage/**", "**/*.tmp", "**/*.temp"];
+/**
+ * Default thresholds for trivial PR triage.
+ * PRs meeting these criteria may skip full reviewer flow or use lightweight review.
+ */
+export declare const DEFAULT_TRIAGE_MAX_FILES = 3;
+export declare const DEFAULT_TRIAGE_MAX_TOTAL_LINES = 50;
+/**
+ * File extensions considered documentation-only for triage purposes.
+ */
+export declare const DEFAULT_TRIAGE_DOCS_ONLY_EXTENSIONS: readonly [".md", ".txt", ".rst", ".adoc", ".org"];

package/dist/config/defaults.js

@@ -0,0 +1,113 @@
+/**
+ * Default model for orchestrator calls.
+ * Chosen for fast planning/synthesis while preserving structured-output reliability.
+ */
+export const DEFAULT_ORCHESTRATOR_MODEL = 'google/gemini-3-flash-preview';
+/**
+ * Default model for reviewer iterations.
+ * Tuned for code-centric reasoning with acceptable latency/cost.
+ */
+export const DEFAULT_REVIEWER_MODEL = 'qwen/qwen3-coder-next';
+/**
+ * Default critic model used when no critic model is explicitly configured.
+ */
+export const DEFAULT_CRITIC_MODEL = 'google/gemini-3-flash-preview';
+/**
+ * Maximum tool/LLM steps per call for orchestrator/reviewer operations.
+ */
+export const DEFAULT_MAX_STEPS = 10;
+/**
+ * Maximum validation loops per reviewer (initial pass + critic pass).
+ */
+export const DEFAULT_MAX_ITERATIONS = 2;
+/**
+ * Maximum tool/LLM steps for synthesis and final decision generation.
+ */
+export const DEFAULT_AGGREGATION_MAX_STEPS = 5;
+/**
+ * Default temperature for structured output generation.
+ * Lower temperature (0-0.3) improves reliability and consistency for structured output.
+ */
+export const DEFAULT_TEMPERATURE = 0.2;
+/**
+ * Default timeout for LLM calls in milliseconds (2 minutes).
+ * Prevents hanging on slow or unresponsive models.
+ */
+export const DEFAULT_LLM_TIMEOUT_MS = 120_000;
+/**
+ * Default max tokens for structured output generation.
+ * Ensures enough tokens for complete structured responses.
+ * Set to undefined to use model default (typically 4096-8192).
+ */
+export const DEFAULT_MAX_TOKENS = undefined; // Use model default
+/**
+ * Get default critic model based on reviewer model.
+ * If reviewer uses haiku, critic uses sonnet (and vice versa).
+ * This ensures structural independence between review and critique.
+ */
+export const getDefaultCriticModel = (reviewerModel) => {
+    if (!reviewerModel) {
+        return DEFAULT_CRITIC_MODEL;
+    }
+    // If reviewer uses haiku, critic uses sonnet
+    if (reviewerModel.includes('haiku')) {
+        return reviewerModel.replace('haiku', 'sonnet');
+    }
+    // If reviewer uses sonnet, critic uses haiku
+    if (reviewerModel.includes('sonnet')) {
+        return reviewerModel.replace('sonnet', 'haiku');
+    }
+    // Default to sonnet for other models
+    return DEFAULT_CRITIC_MODEL;
+};
+/**
+ * Default configuration for surrounding context extraction.
+ */
+export const DEFAULT_SURROUNDING_CONTEXT_CONFIG = {
+    enabled: true,
+    maxTokensPerFile: 20_000,
+    contextLines: 10,
+};
+/**
+ * Default file patterns to exclude from code review.
+ * These patterns match common build artifacts, lockfiles, and generated code.
+ * Uses glob patterns (minimatch) instead of regex to avoid ReDoS vulnerabilities.
+ */
+export const DEFAULT_EXCLUDE_PATTERNS = [
+    // Lockfiles
+    '**/*.lock',
+    '**/package-lock.json',
+    '**/pnpm-lock.yaml',
+    '**/yarn.lock',
+    // Build artifacts
+    '**/dist/**',
+    '**/build/**',
+    '**/out/**',
+    '**/.next/**',
+    '**/.turbo/**',
+    // Generated code
+    '**/*.generated.*',
+    '**/*.gen.*',
+    // Dependencies
+    '**/node_modules/**',
+    // IDE/Editor files
+    '**/.vscode/**',
+    '**/.idea/**',
+    // OS files
+    '.DS_Store',
+    // Coverage reports
+    '**/coverage/**',
+    // Temporary files
+    '**/*.tmp',
+    '**/*.temp',
+];
+/**
+ * Default thresholds for trivial PR triage.
+ * PRs meeting these criteria may skip full reviewer flow or use lightweight review.
+ */
+export const DEFAULT_TRIAGE_MAX_FILES = 3;
+export const DEFAULT_TRIAGE_MAX_TOTAL_LINES = 50;
+/**
+ * File extensions considered documentation-only for triage purposes.
+ */
+export const DEFAULT_TRIAGE_DOCS_ONLY_EXTENSIONS = ['.md', '.txt', '.rst', '.adoc', '.org'];

package/dist/config/index.d.ts

@@ -0,0 +1,34 @@
+import { type LogLevel } from '../logging/logger.js';
+export type ReviewAgentConfig = {
+    mcpServerUrl?: string;
+    mcpAuthToken?: string;
+    openRouterApiKey?: string;
+    orchestratorModel?: string;
+    reviewerModel?: string;
+    criticModel?: string;
+    logLevel: LogLevel;
+    maxSteps?: number;
+    maxIterations?: number;
+    aggregationMaxSteps?: number;
+    maxTokensPerFile?: number;
+    contextLines?: number;
+    prDescription?: string;
+    reviewDomains?: string[];
+};
+export type ValidatedReviewAgentConfig = {
+    mcpServerUrl: string;
+    mcpAuthToken: string;
+    openRouterApiKey: string;
+    orchestratorModel?: string;
+    reviewerModel?: string;
+    criticModel?: string;
+    logLevel: LogLevel;
+    maxSteps: number;
+    maxIterations: number;
+    aggregationMaxSteps: number;
+    maxTokensPerFile: number;
+    contextLines: number;
+    reviewDomains?: string[];
+};
+export declare const loadConfig: () => ReviewAgentConfig;
+export declare const validateConfig: (config: ReviewAgentConfig) => ValidatedReviewAgentConfig;

package/dist/config/index.js

@@ -0,0 +1,89 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import dotenv from 'dotenv';
+import { parseLogLevel } from '../logging/logger.js';
+import { DEFAULT_AGGREGATION_MAX_STEPS, DEFAULT_MAX_ITERATIONS, DEFAULT_MAX_STEPS, DEFAULT_SURROUNDING_CONTEXT_CONFIG, getDefaultCriticModel, } from './defaults.js';
+// Only load .env file if not in test environment
+// Tests should use explicit env vars or test setup files
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+if (process.env.NODE_ENV !== 'test' && !process.env.VITEST) {
+    dotenv.config({ path: path.join(packageRoot, '.env') });
+}
+const getMissingRequiredEnvVars = (config) => {
+    const missing = [];
+    if (!config.mcpServerUrl?.trim()) {
+        missing.push('CONTEXTRAIL_MCP_SERVER_URL');
+    }
+    if (!config.mcpAuthToken?.trim()) {
+        missing.push('CONTEXTRAIL_MCP_JWT_TOKEN');
+    }
+    if (!config.openRouterApiKey?.trim()) {
+        missing.push('OPENROUTER_API_KEY');
+    }
+    return missing;
+};
+const normalizeOptionalString = (value) => {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+};
+const parseOptionalInt = (value, defaultValue) => {
+    if (!value) {
+        return defaultValue;
+    }
+    const parsed = parseInt(value, 10);
+    return Number.isNaN(parsed) ? defaultValue : parsed;
+};
+export const loadConfig = () => {
+    const reviewDomains = process.env.REVIEW_DOMAINS
+        ? process.env.REVIEW_DOMAINS.split(',')
+            .map((domain) => domain.trim())
+            .filter(Boolean)
+        : undefined;
+    const config = {
+        mcpServerUrl: normalizeOptionalString(process.env.CONTEXTRAIL_MCP_SERVER_URL),
+        mcpAuthToken: normalizeOptionalString(process.env.CONTEXTRAIL_MCP_JWT_TOKEN),
+        openRouterApiKey: normalizeOptionalString(process.env.OPENROUTER_API_KEY),
+        orchestratorModel: normalizeOptionalString(process.env.LLM_MODEL_ORCHESTRATOR),
+        reviewerModel: normalizeOptionalString(process.env.LLM_MODEL_REVIEWER),
+        criticModel: normalizeOptionalString(process.env.LLM_MODEL_CRITIC),
+        logLevel: parseLogLevel(normalizeOptionalString(process.env.DEBUG)),
+        maxSteps: parseOptionalInt(process.env.MAX_STEPS, DEFAULT_MAX_STEPS),
+        maxIterations: parseOptionalInt(process.env.MAX_ITERATIONS, DEFAULT_MAX_ITERATIONS),
+        aggregationMaxSteps: parseOptionalInt(process.env.AGGREGATION_MAX_STEPS, DEFAULT_AGGREGATION_MAX_STEPS),
+        maxTokensPerFile: parseOptionalInt(process.env.MAX_TOKENS_PER_FILE, DEFAULT_SURROUNDING_CONTEXT_CONFIG.maxTokensPerFile),
+        contextLines: parseOptionalInt(process.env.CONTEXT_LINES, DEFAULT_SURROUNDING_CONTEXT_CONFIG.contextLines),
+        prDescription: normalizeOptionalString(process.env.PR_DESCRIPTION),
+        reviewDomains,
+    };
+    // Fail fast when required environment variables are missing.
+    // Note: CLI --help bypasses loadConfig in src/index.ts so help remains accessible.
+    const missingRequired = getMissingRequiredEnvVars(config);
+    if (missingRequired.length > 0) {
+        throw new Error(`Missing required environment variables: ${missingRequired.join(', ')}`);
+    }
+    return config;
+};
+export const validateConfig = (config) => {
+    const mcpServerUrl = config.mcpServerUrl;
+    const mcpAuthToken = config.mcpAuthToken;
+    const openRouterApiKey = config.openRouterApiKey;
+    const missing = getMissingRequiredEnvVars(config);
+    if (missing.length > 0) {
+        throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
+    }
+    return {
+        mcpServerUrl: mcpServerUrl,
+        mcpAuthToken: mcpAuthToken,
+        openRouterApiKey: openRouterApiKey,
+        orchestratorModel: config.orchestratorModel,
+        reviewerModel: config.reviewerModel,
+        criticModel: config.criticModel ?? getDefaultCriticModel(config.reviewerModel),
+        logLevel: config.logLevel,
+        maxSteps: config.maxSteps ?? DEFAULT_MAX_STEPS,
+        maxIterations: config.maxIterations ?? DEFAULT_MAX_ITERATIONS,
+        aggregationMaxSteps: config.aggregationMaxSteps ?? DEFAULT_AGGREGATION_MAX_STEPS,
+        maxTokensPerFile: config.maxTokensPerFile ?? DEFAULT_SURROUNDING_CONTEXT_CONFIG.maxTokensPerFile,
+        contextLines: config.contextLines ?? DEFAULT_SURROUNDING_CONTEXT_CONFIG.contextLines,
+        reviewDomains: config.reviewDomains,
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};