Contributing

Miravo is open source and welcomes contributions.

Prerequisites

• Bun (latest)
• Git

Setup

git clone https://github.com/amine-amaach/miravo.git
cd miravo
bun install

Monorepo Structure

miravo/
  packages/
    cli/            # CLI entry point (Commander.js)
    core/           # Engine, scheduler, generators, twin runtime
    shared/         # Zod schemas, types, constants
    content/        # Built-in models and templates
    console/        # Web dashboard (React + shadcn/ui + Vite)
    protocols/
      mqtt/         # MQTT adapter (aedes embedded + mqtt.js external)
      opcua/        # OPC UA adapter (node-opcua)
    web/            # Documentation site (Astro + Starlight)
  tests/fixtures/   # Stress templates
  scripts/          # Build and release scripts

Packages use "workspace:*" for inter-package dependencies.

Development Commands

Run the CLI in dev mode:

bun run dev

Run all tests:

bun run test

Run tests for a specific package:

bun run test --cwd packages/core

Type check (required — Bun does not typecheck):

bun run typecheck

Lint:

bun run lint

Lint and auto-fix:

bun run lint:fix

Format:

bun run format

Type Checking

Bun transpiles TypeScript but does not type check. Always run:

bun run typecheck

This runs tsc -b (build mode) which follows project references. Do not use tsc --noEmit — it checks nothing with the monorepo’s root config.

Testing Conventions

• Test files: *.test.ts colocated next to source files
• Import from bun:test: import { describe, test, expect } from "bun:test"
• Tests must assert specific values, not that code runs without throwing
• Never modify a failing test to make it pass — fix the implementation
• Never mock the thing being tested

Run a single test file:

bun run test packages/core/src/scheduler.test.ts

Linting

Miravo uses Biome for linting and formatting (not ESLint/Prettier):

Check:

bun run lint

Auto-fix:

bun run lint:fix

Format all files:

bun run format

Code Style

• ES modules only (import/export)
• Use import type { X } for type-only imports
• Prefer Bun APIs over Node.js (Bun.write() over writeFile)
• No any — use unknown and narrow with Zod or type guards
• Prefer interface over type for object shapes
• Zod schemas are the single source of truth — derive types with z.infer<>

Definition of Done

A task is complete when:

bun run typecheck && bun run test && bun run lint

All three must pass with zero failures.

Branch Naming

• feat/ — New features
• fix/ — Bug fixes
• refactor/ — Code restructuring
• docs/ — Documentation changes

Commit Messages

Use conventional commits:

feat: add transport-delay generator
fix: correct lifecycle stage transition timing
refactor: extract generator input resolution
docs: update MQTT adapter reference