tooling-and-dependencies

# Tooling and Dependencies ## Toolchain (proto) - Tool versions (bun, pnpm, node, moon, gh) are pinned in `.prototools` and managed by [proto](https://moonrepo.dev/docs/proto); its shims put the pinned versions on PATH inside the repo. `proto use` installs everything after a pin changes. - Bump a tool by editing `.prototools` only — never install tools globally or pin versions elsewhere. moon's version is additionally enforced by `versionConstraint` in `.moon/workspace.yml` and mirrored as the `@moonrepo/cli` catalog entry (for Vercel builders without proto); keep all three in sync. - CI and local shells resolve the same toolchain: CI installs it with `moonrepo/setup-toolchain`, which runs `proto install` against the same `.prototools`. ## Package Manager and Runtime - Use `pnpm` for package operations: install, add, remove, dedupe, lockfile, package-runner, and publish work. - Do not use `bun`, `npm`, `yarn`, `npx`, or other package runners for package operations unless there is a specific documented reason. - Bun remains the direct TypeScript runtime and Bun test runner where current moon tasks use it. Local scripts may still be `.ts` files without a separate compile step. ## Dependency Catalog This monorepo uses the `catalog` in `pnpm-workspace.yaml`. - Never add a version directly to an individual package's `package.json` by default. - To add a dependency: 1. Add the exact version to `pnpm-workspace.yaml` under `catalog`, for example `"new-package": "1.2.3"`. 2. Reference it from the package with `"new-package": "catalog:"`. - Do not run `pnpm add <package>` inside a package directory; it writes direct versions and breaks the catalog pattern unless you manually normalize them. - Published packages may intentionally use ranges for end-user compatibility. `apps/docs` should use catalog versions; published packages such as `packages/diffs` may use ranges only when that is intentional. ## Tasks - All build/dev/test/lint entrypoints are moon tasks; package.json scripts exist only for npm lifecycle hooks (`prepublishOnly`). Never add task scripts back to a package.json. - Tasks are defined in `.moon/tasks/*.yml` (inherited) and each project's `moon.yml`. Repo-wide tooling (format, lint, icons, clean) lives on the `root` project. - Run tasks from anywhere in the repo: ```bash moon run <project>:<task> moonx <project>:<task> # same engine; shorthand for moon exec moonx <project>:<task> -- --flags # forward arguments after -- moon run :test # a task across every project that has it moon tasks <project> # discover a project's tasks ``` `moon run` and `moonx` (an alias binary for `moon exec`) execute the same action pipeline: identical dependency resolution, caching, and affected support. Use them interchangeably; docs write `moon run` for canonical commands and `moonx` in interactive examples. The one practical difference: `moonx`/`moon exec` exposes CI-behavior overrides (`--ignore-ci-checks`, `--ci <bool>`) that `moon run` lacks. `moon ci` is a third thing — the affected-aware orchestrator used only by `.github/workflows/ci.yml`; never reach for it locally. moon builds dependency projects first (`deps: ['^:build']`), caches outputs, and skips tasks whose inputs have not changed. Local-only tasks set explicit options instead of moon presets (presets force `runInCI: skip`, which moon refuses to run in CI-detected shells; agent harnesses export `CI=1`): - No graph edges at all (formatters, benchmarks, wt, servers spawned by playwright): use `runInCI: 'always'` — runnable everywhere, and never in the CI pipeline because a task with no deps or dependents is never affected through the graph. - Connected to the build graph (dev/prod, e2e variants, publish guards): keep `runInCI: 'skip'` — `moon ci --include-relations` runs affected runInCI-enabled tasks even when unrequested, which would pull them into CI. Run them in CI-marked shells with `moonx <target> --ignore-ci-checks` (works regardless of the shell's CI env). For non-moon commands that CI-gate themselves, unset the var instead: `CI= pnpm publish --dry-run`.