strukto-ai--mirage/CONTRIBUTING.md

Contributing to Mirage

Thank you for your interest in contributing to Mirage. Mirage is a unified virtual filesystem for AI agents, with Python and TypeScript implementations in one repository.

Contribution Guidelines

We prefer small, well-tested contributions that solve real user problems.

• Open an issue or discussion before starting non-trivial features, API changes, or large refactors.
• Link related issues or discussions in your pull request.
• Keep pull requests focused. Split unrelated changes into separate PRs.
• Include tests for bug fixes and new behavior when practical.
• Update affected docs and examples when behavior changes.
• AI-assisted contributions are fine, but they must be reviewed, edited, and tested by a human before submission. Bulk low-signal generated submissions may be closed.

Repository Layout

• python/ contains the Python package, tests, pyproject.toml, and uv.lock.
• typescript/ contains the TypeScript monorepo and packages.
• docs/, examples/, and .github/ are shared across both implementations.

Run Python commands from python/. Run TypeScript commands from typescript/.

Development Setup

Install Python dependencies:

cd python
uv sync --all-extras

Install TypeScript dependencies:

cd typescript
pnpm install

Examples under examples/python/ load .env.development from the repository root. Run them from the root with the Python virtualenv interpreter:

./python/.venv/bin/python examples/python/s3/s3.py

Common Commands

Run Python tests:

cd python
uv run pytest

Run Python formatting and linting from the repository root:

./python/.venv/bin/pre-commit run --all-files

Run TypeScript checks:

cd typescript
pnpm typecheck
pnpm test
pnpm lint
pnpm format:check

Build TypeScript packages:

cd typescript
pnpm build

If you change Python dependencies, use uv add and commit the updated lock file. If you change TypeScript dependencies, use pnpm and commit the updated lock file.

Code Style

• Represent filesystem paths with PathSpec, not raw strings, in Python APIs.
• Keep imports at the top of files.
• Avoid circular imports. Fix the dependency direction instead of using lazy function-local imports.
• Do not silently swallow exceptions. Let unexpected errors propagate, or log clearly when an error is intentionally ignored.
• Do not call asyncio.run() from sync code that may run inside an existing event loop.
• Keep comments and docstrings useful and concise. When adding docstring Args, include argument types.

Pull Request Checklist

Before opening a PR:

• The change is scoped to one bug, feature, or documentation improvement.
• Related issues or discussions are linked.
• Tests were added or updated when relevant.
• Affected docs and examples were updated.
• Formatting, linting, and tests pass locally, or the PR explains why a check could not be run.

Useful PR title prefixes:

• feat: for new features
• fix: for bug fixes
• docs: for documentation changes
• refactor: for code restructuring
• test: for test-only changes
• chore: for maintenance work

Getting Help

Use GitHub issues for bugs, feature requests, and design discussions. For faster conversation, join the Mirage Discord linked from the README.