/run-nx-checks

name: run-nx-checks
description: Run nx format, lint, typecheck, test, and build on affected or specified projects, then fix unambiguous failures
context: fork
allowed-tools: Bash, Read, Edit, Write, Grep, Glob
license: MIT
metadata:
  version: "1.10"

Run Nx Checks

Run format, lint, typecheck, test, build. Fix unambiguous failures. Report anything judgment-laden and every file you changed.

Arguments

`$ARGUMENTS` — optional, space-separated: `[cpuCount] [projectName] [--remote-cache]`. Number token → `cpuCount`. Non-number, non-flag token → `projectName`. `--remote-cache` flag → opt back into the remote cache by dropping the remote-cache-off prefix. Default `cpuCount` = cores - 4 (min 1); count cores with `node -p 'os.cpus().length'`. Default project scope = affected. Default remote-cache state = off (see Steps).

`$base`, `$cpuCount`, `$projectName` and `$snap` in the commands below are placeholders: substitute their values (a fresh shell per Bash tool call holds none of them).

Workspace

Run nx commands from wherever `nx.json` lives in this repo (commonly the root; in some repos a subdirectory).

Setup (before step 1)

Keep the Nx daemon warm so the project graph is reused across targets:

NX_DAEMON=true npx nx daemon --start >/dev/null 2>&1 || true

Snapshot the dirty files, so the final report can name every file the run changes (`hash-object` without `-w` writes nothing); substitute the printed path for `$snap` there:

snap=$(mktemp -d "${TMPDIR:-/tmp}/nx-checks.XXXXXX") && git ls-files -z -mo --exclude-standard | while IFS= read -r -d '' f; do echo "$(git hash-object "$f" 2>/dev/null) $f"; done > "$snap/before.txt" && echo "snap=$snap"

Affected base

`nx affected` and `format:write` diff against the *local* default branch, which is often stale or missing. `$projectName` replaces only the `affected` commands, so resolve the base in both modes. `NX_BASE` set: skip this section and omit `--base` from every command below; Nx reads it and a deliberate env setting wins. Otherwise resolve the remote-tracking ref once and substitute the printed ref for `$base` in every `affected`, `format:write` and `show projects --affected` command below:

base=$(node -p 'const j=require("./nx.json"); j.defaultBase ?? j.affected?.defaultBase ?? "main"' 2>/dev/null || echo main)
base=${base#remotes/}; [[ $base == */* ]] || base="origin/$base"
GIT_TERMINAL_PROMPT=0 GIT_SSH_COMMAND='ssh -o BatchMode=yes -o ConnectTimeout=15' git fetch --quiet "${base%%/*}" "${base#*/}" || echo "fetch failed: base may be stale"
git rev-parse --verify --quiet "$base" >/dev/null && echo "base=$base" || echo "no such ref: omit --base"

• Omit `--base` when the ref is missing (Nx falls back to `defaultBase`).
• **Never pass `--head`.** With both flags Nx diffs two commits and ignores uncommitted and

untracked files, so an agent's unstaged edits vanish and every check passes vacuously.

• A failed fetch is not a failure: continue on the current ref, flag "base may be stale" in the

final report, and never retry outside the sandbox for it.

Why: [affected-base-rationale.md](affected-base-rationale.md).

Fix rule

• Apply only mechanical/unambiguous fixes: lint auto-fix output, missing imports/types, obvious type

errors, test expectations that mirror a clear code change. An assertion or snapshot update is mechanical only when the failing expectation names a value the working-tree diff changed on purpose; edit that expectation by hand. Never pass `-u`/`--updateSnapshot` to a target.

• Never guess on anything judgment-laden: test failure that could be a real bug vs. an outdated

assertion, errors pointing at unrelated areas, pre-existing failures unrelated to recent work, anything where multiple plausible fixes exist. Running forked, you can't ask mid-run: leave such failures unfixed and carry them, with your analysis, into the final report.

• Keep changes minimal and scoped to the failure. No drive-by refactors.
• After fixing, re-run the same step command; the local cache replays the untouched projects.

Repeat until clean or only judgment-laden failures remain.

Affected scope — sanity-check before step 1

Affected runs only (no `$projectName`); they can balloon. Before step 1, check scope with the graph-only `npx nx show projects --affected --base=$base` (fast, no build):

• **Sandbox `.env` false positives.** The sandbox denies reading `**/.env`; `nx affected` hashes

changed files, so an unreadable `.env` reads as *changed* and marks its project affected. Repos with `.env`-bearing apps (e.g. `apps/*-api`) thus drag those into every affected run and build them for nothing. Tell-tale: run `git status`; it prints `<path>/.env: Operation not permitted` for exactly those projects. Fix: add `--exclude=<their project names>` to every `affected` command (`format:write` takes none) and list them as excluded in the final report, naming any real edits they hold. Never re-run them outside the sandbox yourself; the user can, to include them.

• **Large fan-out.** Large = more than half of `npx nx show projects | wc -l` or more than 20

projects, whichever is lower, counting affected projects after the `.env` exclusions (e.g. a widely-shared lib change rippling across the workspace). Don't build the world unprompted: skip steps 3–5 and report the project count and list in the final report so the user can re-run with `$projectName`.

Steps

**Scope is mandatory — never narrow it yourself.** With no `$projectName` argument, *every* target runs at full scope — `nx affected` for lint/typecheck/test/build, whole-changeset `format:write`. The single-project forms in the steps below apply **only** when the user explicitly passed `$projectName`. Never substitute `nx run <proj>:<target>`, `nx <target> <changedLib>`, or file-scoped `format --files` for the affected sweep: that skips every other affected project — exactly where a shared-lib change