exa-policy-guardrails

Implement Exa lint rules, policy enforcement, and automated guardrails.Use when setting up code quality rules for Exa integrations, implementingpre-commit hooks, or configuring CI policy checks for Exa best practices.Trigger with phrases like "exa policy", "exa lint","exa guardrails", "exa best practices check", "exa eslint".

⭐920stars🔀111forks📁View on GitHub🕐Updated Jan 9, 2026⬇️1downloads

When & Why to Use This Skill

The Exa Policy & Guardrails skill provides a comprehensive framework for automating code quality, security enforcement, and architectural consistency within Exa integrations. It leverages industry-standard tools like ESLint, Pre-commit hooks, and Open Policy Agent (OPA) to implement robust guardrails. By automating secret detection, schema validation, and runtime protection, this skill ensures that developers can build secure, reliable, and high-performing AI-driven search applications while adhering to organizational best practices and safety standards.

Use Cases

  • Automated Secret Protection: Prevent the accidental exposure of sensitive Exa API keys by using custom ESLint rules and pre-commit hooks that scan for hardcoded credentials before code is committed.
  • CI/CD Policy Enforcement: Integrate automated policy-as-code checks into deployment pipelines to validate configurations, enforce minimum timeouts, and ensure mandatory retry logic for all Exa client instances.
  • Production Runtime Safety: Deploy runtime guardrails that intercept and block high-risk operations (such as data deletion or resets) in production environments and provide proactive rate-limit monitoring.
  • Standardizing AI Architecture: Enforce consistent development patterns across teams using TypeScript strict interfaces and Architecture Decision Records (ADRs) to ensure the Exa client is initialized and used correctly.
  • Type-Safe Integration Development: Utilize strict TypeScript patterns to eliminate the use of 'any' types in Exa configurations, ensuring data integrity and reducing runtime errors in complex search implementations.
nameexa-policy-guardrails
description|
allowed-toolsRead, Write, Edit, Bash(npx:*)
version1.0.0
licenseMIT
authorJeremy Longshore <jeremy@intentsolutions.io>

Exa Policy & Guardrails

Overview

Automated policy enforcement and guardrails for Exa integrations.

Prerequisites

  • ESLint configured in project
  • Pre-commit hooks infrastructure
  • CI/CD pipeline with policy checks
  • TypeScript for type enforcement

ESLint Rules

Custom Exa Plugin

// eslint-plugin-exa/rules/no-hardcoded-keys.js
module.exports = {
  meta: {
    type: 'problem',
    docs: {
      description: 'Disallow hardcoded Exa API keys',
    },
    fixable: 'code',
  },
  create(context) {
    return {
      Literal(node) {
        if (typeof node.value === 'string') {
          if (node.value.match(/^sk_(live|test)_[a-zA-Z0-9]{24,}/)) {
            context.report({
              node,
              message: 'Hardcoded Exa API key detected',
            });
          }
        }
      },
    };
  },
};

ESLint Configuration

// .eslintrc.js
module.exports = {
  plugins: ['exa'],
  rules: {
    'exa/no-hardcoded-keys': 'error',
    'exa/require-error-handling': 'warn',
    'exa/use-typed-client': 'warn',
  },
};

Pre-Commit Hooks

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: exa-secrets-check
        name: Check for Exa secrets
        entry: bash -c 'git diff --cached --name-only | xargs grep -l "sk_live_" && exit 1 || exit 0'
        language: system
        pass_filenames: false

      - id: exa-config-validate
        name: Validate Exa configuration
        entry: node scripts/validate-exa-config.js
        language: node
        files: '\.exa\.json$'

TypeScript Strict Patterns

// Enforce typed configuration
interface ExaStrictConfig {
  apiKey: string;  // Required
  environment: 'development' | 'staging' | 'production';  // Enum
  timeout: number;  // Required number, not optional
  retries: number;
}

// Disallow any in Exa code
// @ts-expect-error - Using any is forbidden
const client = new Client({ apiKey: any });

// Prefer this
const client = new ExaClient(config satisfies ExaStrictConfig);

Architecture Decision Records

ADR Template

# ADR-001: Exa Client Initialization

## Status
Accepted

## Context
We need to decide how to initialize the Exa client across our application.

## Decision
We will use the singleton pattern with lazy initialization.

## Consequences
- Pro: Single client instance, connection reuse
- Pro: Easy to mock in tests
- Con: Global state requires careful lifecycle management

## Enforcement
- ESLint rule: exa/use-singleton-client
- CI check: grep for "new ExaClient(" outside allowed files

Policy-as-Code (OPA)

# exa-policy.rego
package exa

# Deny production API keys in non-production environments
deny[msg] {
  input.environment != "production"
  startswith(input.apiKey, "sk_live_")
  msg := "Production API keys not allowed in non-production environment"
}

# Require minimum timeout
deny[msg] {
  input.timeout < 10000
  msg := sprintf("Timeout too low: %d < 10000ms minimum", [input.timeout])
}

# Require retry configuration
deny[msg] {
  not input.retries
  msg := "Retry configuration is required"
}

CI Policy Checks

# .github/workflows/exa-policy.yml
name: Exa Policy Check

on: [push, pull_request]

jobs:
  policy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check for hardcoded secrets
        run: |
          if grep -rE "sk_(live|test)_[a-zA-Z0-9]{24,}" --include="*.ts" --include="*.js" .; then
            echo "ERROR: Hardcoded Exa keys found"
            exit 1
          fi

      - name: Validate configuration schema
        run: |
          npx ajv validate -s exa-config.schema.json -d config/exa/*.json

      - name: Run ESLint Exa rules
        run: npx eslint --plugin exa --rule 'exa/no-hardcoded-keys: error' src/

Runtime Guardrails

// Prevent dangerous operations in production
const BLOCKED_IN_PROD = ['deleteAll', 'resetData', 'migrateDown'];

function guardExaOperation(operation: string): void {
  const isProd = process.env.NODE_ENV === 'production';

  if (isProd && BLOCKED_IN_PROD.includes(operation)) {
    throw new Error(`Operation '${operation}' blocked in production`);
  }
}

// Rate limit protection
function guardRateLimits(requestsInWindow: number): void {
  const limit = parseInt(process.env.EXA_RATE_LIMIT || '100');

  if (requestsInWindow > limit * 0.9) {
    console.warn('Approaching Exa rate limit');
  }

  if (requestsInWindow >= limit) {
    throw new Error('Exa rate limit exceeded - request blocked');
  }
}

Instructions

Step 1: Create ESLint Rules

Implement custom lint rules for Exa patterns.

Step 2: Configure Pre-Commit Hooks

Set up hooks to catch issues before commit.

Step 3: Add CI Policy Checks

Implement policy-as-code in CI pipeline.

Step 4: Enable Runtime Guardrails

Add production safeguards for dangerous operations.

Output

  • ESLint plugin with Exa rules
  • Pre-commit hooks blocking secrets
  • CI policy checks passing
  • Runtime guardrails active

Error Handling

Issue Cause Solution
ESLint rule not firing Wrong config Check plugin registration
Pre-commit skipped --no-verify Enforce in CI
Policy false positive Regex too broad Narrow pattern match
Guardrail triggered Actual issue Fix or whitelist

Examples

Quick ESLint Check

npx eslint --plugin exa --rule 'exa/no-hardcoded-keys: error' src/

Resources

Next Steps

For architecture blueprints, see exa-architecture-variants.