Skip to content

AGENTS.md

Latest commit

 

History

History
101 lines (77 loc) · 4.76 KB

AGENTS.md

File metadata and controls

101 lines (77 loc) · 4.76 KB
Raw

AGENTS.md

Guidance for AI coding agents working in the moon repository. moon is a repository management, organization, orchestration, and notification tool for the web ecosystem. The core is written in Rust and ships alongside a set of @moonrepo/* npm packages. moon is built with moon, so every npm package is itself a moon project.

Repository layout

Path Contents
.moon/ moon workspace config (workspace.yml, toolchains.yml, tasks/)
crates/* Rust crates; crates/cli is the default binary
packages/* TypeScript npm packages; @moonrepo/* scope
wasm/* Test WASM plugins built for wasm32-wasip1
website/ Documentation site (also a moon project)

Prerequisites

  • Rust >= 1.97 (pinned in rust-toolchain.toml, edition 2024)
  • Cargo — Rust toolchain
  • Node.js >= 22.18
  • Yarn >= 4
  • Just — Rust task runner
  • Vite+ — JavaScript toolchain
  • Git >= 2.28

First-time setup:

just init     # installs cargo-nextest, cargo-insta, cargo-llvm-cov, etc.
just build    # builds the `moon` binary (required for the JS workflow)
vp install    # installs node modules

Rust workflow

Use just for all Rust tasks. Always run format, lint, and test before finishing a change.

  • just build - Builds all Rust crates.
  • just build-wasm - Builds test related WASM plugins (required for tests).
  • just check - Checks all Rust crates without producing binaries.
  • just format - Formats all Rust code with rustfmt.
  • just lint - Lints all Rust code with clippy (treats warnings as errors).
  • just test - Runs all Rust tests with cargo nextest.
  • just test <filter> - Runs all Rust tests matching the filter.
  • just test-package - Runs tests for a single package/crate by name.
  • just cov - Runs Rust tests with LLVM coverage (slow).

Conventions:

  • Shared target cache. When running Cargo or any Just commands, the $CARGO_TARGET_DIR environment variable MUST be defined. If it's not provided by the shell, it should default to ~/.cargo/shared-target.
  • No warnings. Clippy runs with -D warnings; treat every warning as an error.
  • No std hash collections. std::collections::HashMap/HashSet are disallowed via clippy.toml. Use rustc_hash::{FxHashMap, FxHashSet} instead.
  • Snapshots use insta; review changes with cargo insta review.
  • Tests run under nextest. Tests must pass with MOON_TEST=true and STARBASE_TEST=true (the just test recipe sets these for you).
  • Applicable crates are published independently using cargo release. Never automate this!

JavaScript workflow

This repo is powered by moon, so each npm package under packages/* is a moon project. If the moon binary has been built, the yarn moon command can be used, otherwise use cargo run --.

The following tasks can be run for each package:

  • {cmd} run <project>:build - Builds the package.
  • {cmd} run <project>:test - Runs unit tests.
  • {cmd} run <project>:typecheck - Runs the type-checker.

While the following tasks are ran at the root level and apply to all packages:

  • {cmd} run root:format - Formats all code.
  • {cmd} run root:lint - Lints all code.

Drop the project name to run a task across all projects.

Tooling and conventions:

  • Type checking with TypeScript — run it first; valid types lead to valid tests and lints.
  • Testing with Vitest. Every function/class gets a sibling *.test.ts in the package's tests/ folder. Write unit tests, not integration tests.
  • Linting with oxlint. Errors must be fixed; leave warnings alone — they are informational (browser differences, polyfill hints), not actionable.
  • Formatting with oxfmt, ideally via format-on-save in your editor. Indentation is tabs.

Pull requests

  • Target master for bug fixes; target develop-x.x for new features / breaking changes.
  • Code on master must stay compatible with the latest stable release (no breaking changes).
  • npm package version bumps use Yarn's release workflow — CI fails if a package was modified without a declared bump.
  • Make sure the build passes locally (format, lint, test for both Rust and JS) before opening a PR.

See CONTRIBUTING.md for the full contributor guide.