From 27c2b5f4b1355dc130876297ec3bdc28a8689a82 Mon Sep 17 00:00:00 2001 From: fullsend-code <278716306+fullsend-ai-coder[bot]@users.noreply.github.com> Date: Thu, 10 Sep 2026 13:02:25 +0000 Subject: [PATCH 1/3] docs: populate empty AGENTS.md sections with RHDH domain context Fill in the three placeholder sections (Key Conventions, Architecture, Pattern References) with substantive content derived from the actual codebase. This gives review agents the domain context needed to catch design-level issues in PRs touching version resolution or CLI commands. Key Conventions documents the RHDH-to-Backstage version mapping model, the offline vs air-gapped distinction (RHDH_OFFLINE skips GitHub metadata but not manifest fetch), and the ExitCodeError convention for error signaling. Architecture documents the 3-tier version resolution engine in src/lib/rhdhVersion.ts, manifest caching in src/lib/backstageVersion.ts, the command directory structure under src/commands/, and the intent-based actions registration path. Pattern References points to src/commands/check-versions/command.ts as the reference for new CLI commands, src/lib/rhdhVersion.ts for version resolution patterns, src/lib/rhdhVersion.test.ts for test patterns with mocked fetch, and src/lib/backstageVersion.ts for manifest utilities. Closes #199 Assisted-by: claude-opus-4-6 --- AGENTS.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 73 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ca3e1a7..8d5eae4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,21 +13,85 @@ ## Key Conventions - +- **RHDH-to-Backstage version mapping.** RHDH releases map to specific + Backstage release versions. The primary lookup fetches + `build-metadata.json` from the `redhat-developer/rhdh` GitHub repo + (branch `release-X.Y`). When that fails (network error, missing + branch), a static compatibility matrix in `src/lib/rhdhVersion.ts` + (`RHDH_COMPATIBILITY_MATRIX`) provides the fallback. The matrix must + be updated manually each RHDH release cycle. Bare numeric versions + like `1.54.0` are treated as RHDH versions — to target a Backstage + version directly, users must use the `backstage:` prefix (e.g. + `backstage:1.54.0`). +- **Offline vs air-gapped.** `RHDH_OFFLINE=true` (or `--offline`) skips + only the GitHub metadata fetch (Tier 1 of version resolution). The + Backstage release manifest is still fetched from + `versions.backstage.io` (Tier 3). For true air-gapped environments, + users must also supply `--manifest-file` (or `BACKSTAGE_MANIFEST_FILE`) + pointing to a local copy of the manifest JSON. +- **Error signaling.** Command handlers signal non-zero exit by throwing + `ExitCodeError` from `src/lib/errors.ts`. The `lazy()` wrapper in + `src/commands/index.ts` catches these and calls `process.exit(code)`. + Do not call `process.exit()` directly from command handler code — + throw `ExitCodeError` instead so tests can assert on the error without + killing the process. ## Architecture - +- **Version resolution engine** (`src/lib/rhdhVersion.ts`). Core + abstraction that resolves an RHDH version alias (e.g. `2.1.0`, + `latest`, `next`) to its underlying Backstage release version and + package manifest. Uses a 3-tier strategy: + 1. **Remote metadata** — fetches `build-metadata.json` from the RHDH + GitHub repo for the matching release branch. + 2. **Static matrix** — `RHDH_COMPATIBILITY_MATRIX`, an embedded + `Record` mapping RHDH versions to Backstage + versions. Used when remote lookup fails or offline mode is active. + 3. **Backstage manifest** — fetches the release manifest from + `versions.backstage.io` (or a local file) using + `@backstage/release-manifests` to get the full package version map. + Results are cached by a composite key of version + base URL + offline + flag, so repeated calls within a session do not re-fetch. +- **Manifest caching** (`src/lib/backstageVersion.ts`). Caches the + Backstage release manifest keyed by version + `versionsBaseUrl`. + Supports `BACKSTAGE_MANIFEST_FILE` for local file override and + `BACKSTAGE_VERSIONS_BASE_URL` for custom manifest servers — + compatible with the upstream Backstage yarn plugin environment + variables. +- **Command structure** (`src/commands/`). Each CLI command is a + directory containing: + + - `command.ts` — exports the handler function (an + `async (opts: OptionValues) => Promise`) + - `index.ts` — re-exports `{ command }` from `command.ts` + - `command.test.ts` — co-located tests (when present) + + Commands are registered in `src/commands/index.ts` using Commander, + with options declared inline and the action wired via + `lazy(() => import('./command-dir').then(m => m.command))`. + +- **Intent-based actions** (`src/commands/intent-based-actions/`). + A separate registration path (`registerIntentCommands`) for + passthrough commands that delegate to the Backstage CLI. ## Pattern References - +- **New CLI command:** follow `src/commands/check-versions/command.ts` + for the handler pattern (option parsing, calling a library function, + formatting output, throwing `ExitCodeError` on failure) and + `src/commands/check-versions/index.ts` for the re-export convention. + Register the command in `src/commands/index.ts`. +- **Version resolution:** see `src/lib/rhdhVersion.ts` for the 3-tier + resolution pattern (remote → static matrix → manifest) and how to + extend the compatibility matrix. +- **Test patterns with mocked fetch:** see + `src/lib/rhdhVersion.test.ts` — uses `setupFetchMock()` to stub + `globalThis.fetch` with URL-based routing, `clearRhdhVersionCache()` + / `clearManifestCache()` in `beforeEach`, and restores the original + fetch in `afterEach`. +- **Backstage manifest utilities:** see + `src/lib/backstageVersion.ts` for manifest fetching, caching, and + `backstage:^` protocol resolution. ## PR Conventions From 9db1a7069de82d1dbd2147f0ba7563d23e71254a Mon Sep 17 00:00:00 2001 From: fullsend-fix <278716306+fullsend-ai-coder[bot]@users.noreply.github.com> Date: Thu, 10 Sep 2026 13:24:04 +0000 Subject: [PATCH 2/3] fix: correct factual inaccuracies in AGENTS.md documentation - Remove incorrect `(or --offline)` parenthetical: no `--offline` CLI flag exists; offline mode is activated via `RHDH_OFFLINE=true` env var only - Fix cache key description to include all 4 components (version + manifestFile + base URL + offline flag), matching the actual implementation in `src/lib/rhdhVersion.ts:312` Addresses #200 Assisted-by: claude-opus-4-6 --- AGENTS.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8d5eae4..49fa6ba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,7 @@ like `1.54.0` are treated as RHDH versions — to target a Backstage version directly, users must use the `backstage:` prefix (e.g. `backstage:1.54.0`). -- **Offline vs air-gapped.** `RHDH_OFFLINE=true` (or `--offline`) skips +- **Offline vs air-gapped.** `RHDH_OFFLINE=true` skips only the GitHub metadata fetch (Tier 1 of version resolution). The Backstage release manifest is still fetched from `versions.backstage.io` (Tier 3). For true air-gapped environments, @@ -50,8 +50,9 @@ 3. **Backstage manifest** — fetches the release manifest from `versions.backstage.io` (or a local file) using `@backstage/release-manifests` to get the full package version map. - Results are cached by a composite key of version + base URL + offline - flag, so repeated calls within a session do not re-fetch. + Results are cached by a composite key of version + manifestFile + + base URL + offline flag, so repeated calls within a session do not + re-fetch. - **Manifest caching** (`src/lib/backstageVersion.ts`). Caches the Backstage release manifest keyed by version + `versionsBaseUrl`. Supports `BACKSTAGE_MANIFEST_FILE` for local file override and From 71d2e9c5cedccaac685c7860f946f4f3a4a00655 Mon Sep 17 00:00:00 2001 From: fullsend-fix <278716306+fullsend-ai-coder[bot]@users.noreply.github.com> Date: Fri, 11 Sep 2026 12:26:45 +0000 Subject: [PATCH 3/3] docs: reduce AGENTS.md to navigational context, add RHIDP-16902 ref - Condense Architecture section to point at source files for implementation details (cache keys, fallback order) rather than duplicating them, keeping AGENTS.md as durable decision context that does not drift with implementation changes. - Add forward reference to RHIDP-16902 near the compatibility-matrix guidance (CI validation of supported entries, not auto-update). Addresses #200 Assisted-by: claude-opus-4-6 --- AGENTS.md | 33 +++++++++++++-------------------- 1 file changed, 13 insertions(+), 20 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 49fa6ba..b8edc2a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,7 +19,9 @@ (branch `release-X.Y`). When that fails (network error, missing branch), a static compatibility matrix in `src/lib/rhdhVersion.ts` (`RHDH_COMPATIBILITY_MATRIX`) provides the fallback. The matrix must - be updated manually each RHDH release cycle. Bare numeric versions + be updated manually each RHDH release cycle; RHIDP-16902 will add CI + validation that checks supported entries against authoritative RHDH + metadata and reports divergences. Bare numeric versions like `1.54.0` are treated as RHDH versions — to target a Backstage version directly, users must use the `backstage:` prefix (e.g. `backstage:1.54.0`). @@ -38,27 +40,18 @@ ## Architecture -- **Version resolution engine** (`src/lib/rhdhVersion.ts`). Core - abstraction that resolves an RHDH version alias (e.g. `2.1.0`, - `latest`, `next`) to its underlying Backstage release version and - package manifest. Uses a 3-tier strategy: - 1. **Remote metadata** — fetches `build-metadata.json` from the RHDH - GitHub repo for the matching release branch. - 2. **Static matrix** — `RHDH_COMPATIBILITY_MATRIX`, an embedded - `Record` mapping RHDH versions to Backstage - versions. Used when remote lookup fails or offline mode is active. - 3. **Backstage manifest** — fetches the release manifest from - `versions.backstage.io` (or a local file) using - `@backstage/release-manifests` to get the full package version map. - Results are cached by a composite key of version + manifestFile + - base URL + offline flag, so repeated calls within a session do not - re-fetch. -- **Manifest caching** (`src/lib/backstageVersion.ts`). Caches the - Backstage release manifest keyed by version + `versionsBaseUrl`. - Supports `BACKSTAGE_MANIFEST_FILE` for local file override and +- **Version resolution engine** (`src/lib/rhdhVersion.ts`). Resolves + an RHDH version alias (e.g. `2.1.0`, `latest`, `next`) to its + underlying Backstage release version and package manifest via a + 3-tier strategy: remote metadata → static matrix → Backstage + manifest. See the source and `src/lib/rhdhVersion.test.ts` for + caching semantics and fallback order. +- **Manifest caching** (`src/lib/backstageVersion.ts`). Fetches and + caches the Backstage release manifest. Supports + `BACKSTAGE_MANIFEST_FILE` for local file override and `BACKSTAGE_VERSIONS_BASE_URL` for custom manifest servers — compatible with the upstream Backstage yarn plugin environment - variables. + variables. See the source for cache-key composition. - **Command structure** (`src/commands/`). Each CLI command is a directory containing: