mega copilot-instructions.md

Mega – Repository Custom Instructions for GitHub Copilot

What this repo is

Mega is an unofficial open-source implementation of Google Piper: a monorepo/monolithic codebase management system with Git compatibility, FUSE mounting, and Buck2 integration. When proposing designs or code, optimize for very large repos, content-addressed storage, and Git internals (packfiles, MIDX, commit-graph, delta chains). License is Apache-2.0 + MIT; keep new files compatible with both.

Languages & defaults

• Prefer Rust (Edition 2021+). Use async/await with Tokio, and structured logging with tracing.
• Serialization: serde; CLI: clap; errors: thiserror (library) and anyhow (bin/tests/tools).
• Avoid unsafe unless there’s a measurable win (perf or FFI). If unsafe is required, add a // SAFETY: rationale comment and tests.
• For small utilities, you may use Python or Bash, but default to Rust when feasible.

Build & run

• Primary build: Buck2. Provide buck2 rules/macros and examples when adding code or docs.
• Crate local build: cargo build -p is welcomed for dev loops; ensure parity with Buck2 rules.
• When generating commands, prefer:

buck2 build //... for CI-style full builds
buck2 test //... for tests
cargo nextest run -p <crate> when suggesting fast local test runs

Key Components (Modules)

Crate	Role
mono	Server binary (HTTP REST, Git HTTP/SSH, Swagger)
ceres	Domain library: transport, application, HTTP DTOs
jupiter / callisto	Storage and SeaORM entities
jupiter-migrate	Database migrations
orion / orion-server / orion-scheduler	Build orchestration
saturn	Cedar policy
vault	Crypto and secrets
moon	Frontend (TypeScript)

See docs/architecture.md for the full workspace map.

Coding style & quality

• Run rustfmt defaults.
• Treat clippy warnings as errors for new/changed code; prefer #[must_use], #[deny(unsafe_op_in_unsafe_fn)] where appropriate.
• Return Result<T, E>; avoid unwrap()/expect() in library code except in tests or when invariant-proofed and documented.
• Prefer iterator and slice APIs to heap-allocating vectors in hot paths. Use SmallVec, bytes, or no_std-friendly patterns when beneficial.