Imported from just-jeb/angular-builders (scripts/AGENTS.md). Install upstream with npx skills add just-jeb/angular-builders --skill scripts. Copyright stays with the author.

Scripts

Build infrastructure utilities for CI test discovery, local test execution, and Angular version updates across the monorepo.

At a Glance

Navigation

• Parent: ../AGENTS.md
• Related: ../examples/AGENTS.md -- the test fixtures that these scripts discover and execute
• Related: ../packages/AGENTS.md -- packages whose integration tests are discovered here
• Related: ../AGENTS.md (CI Pipeline section) -- the GitHub Actions workflows that consume these scripts

Entry Points & Contracts

• discover-tests.js -- Scans all packages/*/tests/integration.js files, collects test definitions, and optionally filters by Turbo-affected packages.

  • CLI mode: Outputs JSON to stdout (consumed by CI workflow to build the GitHub Actions matrix)
  • Module mode: Exports { discoverTests, getAffectedPackages } (consumed by run-local-tests.js)
  • Affected filtering: If .turbo/runs/*.json exists, parses the most recent summary to find which @angular-builders/* packages were built, and filters tests to only those packages.

• run-local-tests.js -- Runs integration tests locally in parallel.

  • Flags: --package <name>, --id <test-id>, --concurrency <N>, --verbose
  • Guarantees: Runs each test in its example app directory via sh -c. Reports pass/fail with duration. Exit code 1 if any test fails.

• update-package.js -- Updates Angular dependency version ranges in a package's package.json.

  • Usage: yarn update:package <angular-major-version> (run from a package directory via the workspace script)
  • Knows: Which Angular packages use stable versioning (^{major}.0.0) vs pre-release versioning (>=0.{major}00.0 < 0.{major+1}00.0). This mapping is hardcoded in the script.
  • Also maintains root resolutions: rewrites the root package.json pins for @angular-devkit/architect and @angular-devkit/core (added in PR #2307 to force a single architect/core version — see root AGENTS.md). These need exact versions, so they are only rewritten when an explicit version with a minor/patch is passed (e.g. 22.1.0); a bare major (22) leaves them untouched and logs a notice. @angular-devkit/core gets the plain version (22.1.0); @angular-devkit/architect gets the 0.{major}{minor padded to 2}.{patch} form (22.1.0 → 0.2201.0, 22.0.3 → 0.2200.3, prerelease tags carried). The root path is resolved via __dirname/.., so it targets the same root regardless of which workspace package the script runs from (it runs once per builder package via yarn update:packages — idempotent).
  • Note: The goal is full automation of Angular version updates, but the process is not there yet. These scripts were created as steps toward that goal. (Source: SME interview, Jeb, 2026-02-16)

• update-example.js -- Updates Angular dependencies in example app package.json files for a new Angular version.

• default-registry.sh -- Called by the CI publish job for beta releases. Runs yarn lerna publish --dist-tag=next --preid=beta --conventional-prerelease --yes. Publishes to npm under the next tag. The graduate path (stable release) is handled directly in ci.yml via npm run graduate.

Invariants

MUST: Integration test definitions in packages/*/tests/integration.js must export an array of objects with { id: string, name: string, purpose: string, app: string, command: string }. id must be unique across all packages (used in CI matrix job names). app must be a valid path relative to repo root (e.g., 'examples/jest/simple-app'). command is run via spawn('sh', ['-c', command], { cwd }) from within the app directory. The discover-tests.js script (lines 50-62) loads each file via require(), spreads entries with { package: pkg, ...entry }, and outputs JSON for GitHub Actions matrix. (Source: code investigation, 2026-02-16)

MUST: The discover-tests.js affected-package filter relies on Turbo's --summarize flag being used during the build step. It expects Turbo output in .turbo/runs/*.json with structure: { tasks: [{ package: "@angular-builders/...", task: "..." }] }. Constraints (see discover-tests.js lines 5-38): files must be in .turbo/runs/ ending with .json, root object must have tasks as an array, each task needs a package property starting with @angular-builders/, and the most recent file by mtime is selected when multiple exist. Failure modes are graceful -- if dir/files/schema are missing or unparseable, all tests are included (no filtering). The .turbo/runs dir is cleared before each build (rm -rf .turbo/runs in package.json scripts). (Source: code investigation, 2026-02-16)

Pitfalls