Contributing

Setup

git clone https://github.com/cdot65/prisma-airs-cursor-hooks.git
cd prisma-airs-cursor-hooks
npm install

Development Workflow

Source Changes

Edit TypeScript in src/. After changes:

npm run build      # compile to dist/
npm test           # run all tests
npm run typecheck  # type check

Development Mode Hooks

For rapid iteration, point hooks.json at TypeScript source (no rebuild needed):

{
  "command": "npx tsx \"/path/to/src/hooks/before-submit-prompt.ts\""
}

This adds ~1.5s per invocation. Switch back to compiled JS for production:

npm run build
npm run install-hooks -- --global

Running Tests

npm test              # all tests once
npm run test:watch    # watch mode

Tests include:

• Unit tests: config, scanner, airs-client, tool-routing, code-extractor, circuit-breaker, DLP masking, content limits, tool-name-parser, logger, log rotation
• Integration tests: end-to-end hook execution via npx tsx and compiled node with piped JSON

Adding a Test

Tests live in test/ and use vitest. Each module has a corresponding test file:

src/scanner.ts     → test/scanner.test.ts
src/config.ts      → test/config.test.ts

Project Structure

src/                           TypeScript source
  hooks/
    run-hook.ts                Shared hook harness (stdin/parse/config/fail-open)
    before-submit-prompt.ts    Cursor beforeSubmitPrompt entry point
    before-mcp-execution.ts    Cursor beforeMCPExecution entry point
    post-tool-use.ts           Cursor postToolUse entry point
    after-agent-response.ts    Cursor afterAgentResponse entry point
  cli.ts                       CLI entry point (prisma-airs-hooks command)
  config.ts                    Config loader (project → global fallback)
  airs-client.ts               executeScan seam: SDK transport + circuit breaker
  scanner.ts                   Scan orchestration, content limits, UX messages
  tool-routing.ts              postToolUse routing (which scan per tool)
  code-extractor.ts            Separates code from natural language
  logger.ts                    JSON Lines logging with rotation
  circuit-breaker.ts           Failure tracking with cooldown bypass
  dlp-masking.ts               Per-service enforcement actions
  content-limits.ts            Configurable skip/truncate thresholds
  tool-name-parser.ts          Parse MCP:server:tool format
  log-rotation.ts              Rotate logs at 10MB
  types.ts                     TypeScript interfaces
dist/                          Compiled JS (production hooks point here)
scripts/
  install-hooks.ts             Write .cursor/hooks.json (points at dist/)
  uninstall-hooks.ts           Remove AIRS entries from hooks.json
  verify-hooks.ts              Tamper detection
  validate-connection.ts       Test AIRS connectivity
  validate-detection.ts        Verify detection works
  validate-config.ts           Validate airs-config.json without API calls
  doctor.ts                    Diagnose and repair the installation
  airs-stats.ts                Scan statistics CLI
  airs-logs.ts                 Tail recent scan log entries
  rotate-log.ts                Force log rotation
test/                          Vitest test suites
docs-site/                     Docusaurus documentation site

Pull Request Guidelines

• Branch from main
• Ensure npm test and npm run typecheck pass
• Include tests for new functionality
• Run npm run build to verify compilation