Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
157 lines (107 loc) · 5.68 KB

CONTRIBUTING.md

File metadata and controls

157 lines (107 loc) · 5.68 KB

Contributing to IronCurtain

Thank you for your interest in contributing to IronCurtain! This is an early-stage research project and contributions are welcome.

Getting Started

  1. Fork and clone the repository:

    git clone https://github.com/provos/ironcurtain.git
cd ironcurtain
npm install

  2. (Recommended) Install Aikido Safe Chain to protect against supply chain attacks during development. It intercepts package installations and validates them against a threat intelligence database in real-time:

    npm install -g @aikidosec/safe-chain
safe-chain setup

  3. Create a .env file with your LLM API key:

    echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

  4. Install the pre-commit hook (runs format:check and lint before each commit):

    npm run setup-hooks

  5. Run the tests to verify your setup:

    npm test

Development Workflow

npm run build          # TypeScript compilation + copy config assets to dist/
npm test               # Run all tests (vitest)
npm run lint           # Run ESLint
npm run format         # Format code with Prettier
npm start "task"       # Run the agent with a task (dev mode, uses tsx)

Run a single test file or test by name:

npm test -- test/policy-engine.test.ts
npx test -- -t "denies delete_file"

See TESTING.md for the full testing guide, including environment flags for LLM and Docker integration tests.

Project Structure

src/
├── agent/              # LLM agent using AI SDK v6
├── config/             # Configuration loading, constitution, MCP server definitions
├── pipeline/           # Constitution -> policy compilation pipeline
├── sandbox/            # V8 isolated execution environment (UTCP Code Mode)
├── session/            # Multi-turn session management, budgets, loop detection
├── trusted-process/    # Policy engine, MCP proxy, audit log, escalation
└── types/              # Shared type definitions

Key Conventions

  • ESM modules throughout (.js extensions in imports)
  • TypeScript strict mode
  • stderr for diagnostic output, stdout for agent responses
  • Integration tests spawn real MCP server processes and need ~30s timeout

Testing on Linux (from macOS)

IronCurtain uses different transport mechanisms on Linux (UDS + --network=none) vs macOS (TCP + internal bridge network). If you develop on macOS, use the provided script to test in a Linux environment via Docker-in-Docker:

# One-time setup: create a separate clone for Linux (avoids native module conflicts)
git clone [email protected]:provos/ironcurtain ~/src/ironcurtain-linux

# Launch a Linux dev shell (builds the DinD image on first run)
./scripts/linux-dev.sh

# Or run a specific command
./scripts/linux-dev.sh npm test

The script automatically syncs your current branch to the Linux clone, installs dependencies with Linux-native binaries, and starts a Docker daemon inside the container. Push your changes before running the script so the Linux clone can pick them up.

To rebuild the image (e.g. after changing the Dockerfile in the script):

./scripts/linux-dev.sh --rebuild

Pre-commit Hook

The project includes a pre-commit hook that automatically runs format:check and lint before each commit. Install it with:

npm run setup-hooks

This copies .hooks/pre-commit into .git/hooks/. The hook prevents commits that have formatting or lint errors. To bypass it in exceptional cases, use git commit --no-verify (not recommended).

If the hook blocks your commit, fix the issues first:

npm run format     # Auto-fix formatting
npm run lint       # Check lint errors (fix manually)

Workspace Dependencies

This project uses npm workspaces to manage local packages under packages/. When the root package.json depends on a workspace package (e.g., @provos/memory-mcp-server), use a normal semver range like "^0.1.3" — not "workspace:*".

The workspace:* protocol is pnpm-specific and causes npm install -g and npx to fail with EUNSUPPORTEDPROTOCOL. npm workspaces automatically resolves matching local packages during development, so the standard version range works for both local dev and published installs.

When publishing a new version of a workspace package, update the version range in the root package.json to match.

Submitting Changes

  1. Create a feature branch from main.
  2. Make your changes. Add tests for new functionality.
  3. Ensure the pre-commit hook is installed (npm run setup-hooks).
  4. Ensure all tests pass (npm test), lint is clean (npm run lint), and code is formatted (npm run format:check).
  5. Submit a pull request with a clear description of the change and its motivation.

Areas Where Help is Welcome

  • Testing -- More test scenarios, edge cases, and integration tests.
  • MCP servers -- Adding support for new MCP servers and argument roles.
  • Constitution examples -- Real-world constitution examples and templates.
  • Documentation -- Improving guides, adding examples, fixing inaccuracies.
  • Security review -- Analyzing the trust boundaries and finding gaps.

Reporting Issues

Please open an issue on GitHub with:

  • A clear description of the problem or suggestion
  • Steps to reproduce (for bugs)
  • Expected vs. actual behavior

Code of Conduct

Be respectful and constructive. This is a research project -- we're all learning.

License

By contributing, you agree that your contributions will be licensed under the Apache-2.0 License.