Contributing to Mezair Registry

Mezair Registry and Mezair Node Base are open source and accept contributions. The project is alpha, so sharp edges are expected. Honest documentation of limitations is preferred over optimistic silence.

Development setup

Requirements:

Node.js 22 LTS
pnpm 9+
Docker and Docker Compose (for local stack)
Git

Clone and install:

Terminal

git clone https://github.com/anthonyhumphreys/mezair.git
cd mezair/mezair-registry
pnpm install --ignore-scripts

The --ignore-scripts flag avoids running lifecycle scripts during development. This is intentional: Mezair is a security project, and we should eat our own cooking.

Workspace structure

Text

apps/gateway      # Fastify npm proxy
apps/worker       # Background analysis
apps/admin        # Next.js admin UI
apps/cli          # Command-line client
packages/         # Shared packages
infra/docker      # Docker Compose local stack
infra/sst         # AWS SST deployment
devcontainer-base # Mezair Node Base image

Common commands

Terminal

pnpm install --ignore-scripts    # Install dependencies
pnpm lint                        # ESLint across packages
pnpm typecheck                   # TypeScript checks
pnpm test                        # Vitest suite
pnpm build                       # Build all packages
pnpm smoke:local                 # Full local stack smoke test
pnpm smoke:clients               # npm client routing smoke test
pnpm smoke:analysis              # Analysis pipeline smoke test

Before changing code

Read docs/mezair-registry-spec.md for the relevant surface.
Read docs/mezair-node-base-spec.md for Node Base changes.
Keep changes scoped to one concern.
Add or update tests for policy, analysis, routing, or CLI behaviour.
Update docs in the same change.

Before opening a PR

Run the relevant checks:

Terminal

pnpm lint
pnpm typecheck
pnpm test
pnpm build
docker compose -f infra/docker/docker-compose.yml config

If a command is not yet available, add a sensible script or explain why it is not applicable.

Review priorities

When reviewing code, check in this order:

Correctness.
Security.
Auth and access control, when auth exists.
Data integrity.
Accessibility for UI work.
Production risk.

Then:

Maintainability.
Readability.
Performance.
Developer experience.

Prefer concrete fixes over decorative commentary.

Security research

If you are researching security vulnerabilities in Mezair Registry:

Do not test against public registries without permission.
Do not exploit the gateway, worker, or admin surfaces against real users.
Report vulnerabilities through the process described in SECURITY.md.
Safe local research in your own Docker Compose stack is encouraged.

Documentation rules

Update README.md for top-level orientation changes.
Update apps/cli/README.md for CLI command changes.
Update devcontainer-base/README.md for Node Base helper changes.
Update mezair-website/content/docs/registry/*.md (same repo) for public operator docs.
Update mezair-website/content/docs/node-base/*.md (same repo) for Node Base public docs.

Commit style

Use Conventional Commits:

Text

feat(gateway): add scoped upstream registry support
fix(worker): handle tarballs with unicode filenames
docs: explain policy reason codes in CLI output
test(policy-engine): add test for dependency addition in patch version

Keep scopes tied to the component: gateway, worker, admin, cli, policy-engine, package-analysis, node-base, etc.