Widen scratch iteration 011 with fixture-backed integrations QA

2026-03-14 03:11:45 +02:00
parent 3b1b7dad80
commit bd78523564
40 changed files with 3478 additions and 2173 deletions
--- a/docs/INSTALL_GUIDE.md
+++ b/docs/INSTALL_GUIDE.md
@@ -40,6 +40,7 @@ The fastest way to get running. The setup scripts validate prerequisites, config
 ```powershell
 .\scripts\setup.ps1              # full setup
 .\scripts\setup.ps1 -InfraOnly   # infrastructure only (PostgreSQL, Valkey, RustFS, Rekor, Zot)
+.\scripts\setup.ps1 -QaIntegrationFixtures # full setup plus Harbor/GitHub App QA fixtures
 ```

 **Linux / macOS:**
@@ -47,6 +48,7 @@ The fastest way to get running. The setup scripts validate prerequisites, config
 ```bash
 ./scripts/setup.sh               # full setup
 ./scripts/setup.sh --infra-only  # infrastructure only
+./scripts/setup.sh --qa-integration-fixtures # full setup plus Harbor/GitHub App QA fixtures
 ```

 The scripts will:
@@ -57,6 +59,7 @@ The scripts will:
 5. Create or reuse the external frontdoor Docker network from `.env` (`FRONTDOOR_NETWORK`, default `stellaops_frontdoor`)
 6. Stop repo-local host-run Stella services that would lock build outputs, then build repo-owned .NET solutions and publish backend services locally into small Docker contexts before building hardened runtime images (vendored or generated trees such as `node_modules`, `dist`, `coverage`, and `output` are excluded)
 7. Launch the full platform with health checks, perform one bounded restart pass for services that stay unhealthy after first boot, wait for the first-user frontdoor bootstrap path (`/welcome`, `/envsettings.json`, OIDC discovery, `/connect/authorize`), then complete an authenticated convergence gate that proves topology inventory, notifications administration overrides, and promotion bootstrap flows load cleanly before reporting success
+8. If `-QaIntegrationFixtures` / `--qa-integration-fixtures` is enabled, start deterministic Harbor and GitHub App fixtures and verify them so the local Integrations Hub can be exercised with successful UI onboarding

 Open **https://stella-ops.local** when setup completes.

@@ -85,6 +88,8 @@ Stella Ops services bind to unique loopback IPs so all can use port 443 without

 Runtime URL convention remains `*.stella-ops.local`; `hosts.stellaops.local` is the template file name only.

+The same template also carries the optional `harbor-fixture.stella-ops.local` and `github-app-fixture.stella-ops.local` aliases used by the fixture-backed integrations QA lane.
+
 - **Windows:** `C:\Windows\System32\drivers\etc\hosts` (run editor as Administrator)
 - **Linux / macOS:** `sudo sh -c 'cat devops/compose/hosts.stellaops.local >> /etc/hosts'`

--- a/docs/dev/DEV_ENVIRONMENT_SETUP.md
+++ b/docs/dev/DEV_ENVIRONMENT_SETUP.md
@@ -17,6 +17,7 @@ Setup scripts validate prerequisites, build solutions and Docker images, and lau
 .\scripts\setup.ps1 -SkipBuild   # skip .NET builds, build images and start platform
 .\scripts\setup.ps1 -SkipImages  # build .NET but skip Docker images
 .\scripts\setup.ps1 -ImagesOnly  # only build Docker images
+.\scripts\setup.ps1 -QaIntegrationFixtures # full setup plus Harbor/GitHub App QA fixtures for real UI onboarding checks
 ```

 **Linux / macOS:**
@@ -27,9 +28,10 @@ Setup scripts validate prerequisites, build solutions and Docker images, and lau
 ./scripts/setup.sh --skip-build  # skip .NET builds
 ./scripts/setup.sh --skip-images # skip Docker image builds
 ./scripts/setup.sh --images-only # only build Docker images
+./scripts/setup.sh --qa-integration-fixtures # full setup plus Harbor/GitHub App QA fixtures
 ```

-The scripts will check for required tools (dotnet 10.x, node 20+, npm 10+, docker, git), warn about missing hosts file entries, copy `.env` from the example if needed, and stop repo-local host-run Stella services before the solution build so scratch bootstraps do not fail on locked `bin/Debug` outputs. Solution discovery is limited to repo-owned sources and skips generated trees such as `dist`, `coverage`, and `output`, so copied docs samples do not break scratch setup. A full setup now also performs one bounded restart pass for services that stay unhealthy after the first compose boot, waits for the first-user frontdoor bootstrap path (`/welcome`, `/envsettings.json`, OIDC discovery, `/connect/authorize`), and then runs an authenticated readiness probe that proves the topology inventory, notifications administration overrides, and promotion bootstrap routes load cleanly before the script prints success. See the manual steps below for details on each stage.
+The scripts will check for required tools (dotnet 10.x, node 20+, npm 10+, docker, git), warn about missing hosts file entries, copy `.env` from the example if needed, and stop repo-local host-run Stella services before the solution build so scratch bootstraps do not fail on locked `bin/Debug` outputs. Solution discovery is limited to repo-owned sources and skips generated trees such as `dist`, `coverage`, and `output`, so copied docs samples do not break scratch setup. A full setup now also performs one bounded restart pass for services that stay unhealthy after the first compose boot, waits for the first-user frontdoor bootstrap path (`/welcome`, `/envsettings.json`, OIDC discovery, `/connect/authorize`), and then runs an authenticated readiness probe that proves the topology inventory, notifications administration overrides, and promotion bootstrap routes load cleanly before the script prints success. When `-QaIntegrationFixtures` / `--qa-integration-fixtures` is enabled, setup also starts deterministic Harbor and GitHub App fixtures and smoke-checks them so the Integrations Hub can be verified with successful UI onboarding, not just failure-path cards. See the manual steps below for details on each stage.

 On Windows and Linux, the backend image builder now publishes each selected .NET service locally and builds the hardened runtime image from a small temporary context. That avoids repeatedly streaming the whole monorepo into Docker during scratch setup.

@@ -121,7 +123,7 @@ Full details: [`docs/technical/architecture/port-registry.md`](../technical/arch

 ### Automated (recommended)

-The setup scripts (`scripts/setup.ps1` / `scripts/setup.sh`) will detect missing entries and offer to install them automatically.
+The setup scripts (`scripts/setup.ps1` / `scripts/setup.sh`) will detect missing entries and offer to install them automatically. The host template now also includes `harbor-fixture.stella-ops.local` and `github-app-fixture.stella-ops.local` for the optional fixture-backed integrations QA lane.

 ### Manual

--- a/docs/implplan/SPRINT_20260313_006_Platform_scratch_iteration_011_full_route_action_audit.md
+++ b/docs/implplan/SPRINT_20260313_006_Platform_scratch_iteration_011_full_route_action_audit.md
@@ -0,0 +1,77 @@
+# Sprint 20260313_006 - Platform Scratch Iteration 011 Full Route Action Audit
+
+## Topic & Scope
+- Wipe Stella-owned runtime state again and rerun the documented setup path from zero state.
+- Re-enter the application as a first-time user after bootstrap and rerun the full route, page-load, and page-action audit with Playwright.
+- Convert any newly discovered manual route, page-load, or action gap into retained Playwright coverage before the iteration is considered complete.
+- Group any fresh failures by root cause before implementing fixes so the commit closes a full iteration rather than isolated page patches.
+- Working directory: `.`.
+- Expected evidence: wipe proof, setup convergence proof, fresh Playwright route/page/action evidence, retained scenario updates, grouped defect analysis, focused tests, and rebuilt-stack retest results.
+
+## Dependencies & Concurrency
+- Depends on local commit `3b1b7dad8` as the closed baseline from scratch iteration 010.
+- Safe parallelism: none during wipe/setup because the environment reset is global to the machine.
+
+## Documentation Prerequisites
+- `AGENTS.md`
+- `docs/INSTALL_GUIDE.md`
+- `docs/dev/DEV_ENVIRONMENT_SETUP.md`
+- `docs/qa/feature-checks/FLOW.md`
+
+## Delivery Tracker
+
+### PLATFORM-SCRATCH-ITER11-001 - Rebuild from zero Stella runtime state
+Status: DONE
+Dependency: none
+Owners: QA, 3rd line support
+Task description:
+- Remove Stella-only containers, images, volumes, and the frontdoor network, then rerun the documented setup entrypoint from zero Stella state.
+
+Completion criteria:
+- [x] Stella-only Docker state is removed.
+- [x] `scripts/setup.ps1` is rerun from zero state.
+- [x] The first setup outcome is captured before UI verification starts.
+
+### PLATFORM-SCRATCH-ITER11-002 - Re-run the first-user full route/page/action audit
+Status: DONE
+Dependency: PLATFORM-SCRATCH-ITER11-001
+Owners: QA
+Task description:
+- After scratch setup converges, rerun the canonical route sweep plus the full route/page/action audit suite, including changed-surface, user-reported, and ownership checks, and enumerate every newly exposed issue before repair work begins.
+
+Completion criteria:
+- [x] Fresh route sweep evidence is captured on the rebuilt stack.
+- [x] Fresh route/page/action evidence is captured across the full aggregate suite, including changed-surface and ownership checks.
+- [x] Newly exposed defects are grouped and any new manual findings are queued into retained Playwright scenarios before any fix commit is prepared.
+
+### PLATFORM-SCRATCH-ITER11-003 - Repair the grouped defects exposed by the fresh audit
+Status: DONE
+Dependency: PLATFORM-SCRATCH-ITER11-002
+Owners: 3rd line support, Architect, Developer
+Task description:
+- Diagnose the grouped failures exposed by the fresh audit, choose the clean product/architecture-conformant fix, implement it, add retained Playwright coverage for the new behavior when needed, and rerun the affected verification slices plus the aggregate audit before committing.
+
+Completion criteria:
+- [x] Root causes are recorded for the grouped failures.
+- [x] Fixes land with focused regression coverage and retained Playwright scenario updates where practical.
+- [x] The rebuilt stack is retested before the iteration commit.
+
+## Execution Log
+| Date (UTC) | Update | Owner |
+| --- | --- | --- |
+| 2026-03-13 | Sprint created immediately after local commit `3b1b7dad8` closed scratch iteration 010. | QA |
+| 2026-03-14 | Rebuilt iteration 011 from a fresh Stella state and widened the audit scope beyond prior route checks by adding fixture-backed successful Harbor and GitHub App onboarding to the retained Playwright aggregate. | QA |
+| 2026-03-14 | The fresh first-user audit exposed a grouped integrations root cause: GitHub App enterprise endpoints were tested with leading-slash requests that dropped the `/api/v3` base and returned non-JSON responses during `Test Connection`. | 3rd line support |
+| 2026-03-14 | Fixed the connector path normalization, expanded retained Playwright for both failed-path and success-path onboarding, and reran the rebuilt-stack aggregate audit clean at `24/24` suites passed with `111/111` canonical routes still green. | Architect / Developer / QA |
+
+## Decisions & Risks
+- Decision: the iteration remains a strict wipe -> setup -> full route/page/action audit -> grouped remediation loop; no fixes start until the fresh-stack audit defect set is collected.
+- Decision: any new manual route, page, or action discovered during QA must become retained Playwright coverage before iteration 011 may close.
+- Risk: scratch rebuilds remain expensive, so verification stays Playwright-first with focused backend and Angular regression slices after the browser audit identifies the grouped defect set.
+- Decision: iteration 011 widened the first-user audit baseline itself rather than accepting a clean rerun; successful Harbor and GitHub App onboarding is now part of retained scratch QA instead of an ad hoc follow-up.
+- Decision: the grouped defect fix stayed at the provider contract layer in the GitHub connector instead of adding UI workarounds around malformed enterprise API bases.
+- Evidence: `dotnet test src/Integrations/__Tests/StellaOps.Integrations.Plugin.Tests/StellaOps.Integrations.Plugin.Tests.csproj -v minimal` passed `12/12`; `dotnet test src/Integrations/__Tests/StellaOps.Integrations.Tests/StellaOps.Integrations.Tests.csproj -v minimal` passed `57/57`; the rebuilt-stack aggregate audit passed `24/24` suites with only one runtime-only first-pass retry that stabilized cleanly.
+
+## Next Checkpoints
+- Start scratch iteration 012 from a fresh Stella wipe with the fixture-enabled setup lane available and continue widening retained coverage only when the full first-user audit exposes a real new gap.
+- Keep route/page/action discovery ahead of fixes; no narrowed page-only commit should close the next iteration unless the full defect set truly contains one grouped root cause.
--- a/docs/implplan/SPRINT_20260314_001_Platform_integration_success_path_fixtures.md
+++ b/docs/implplan/SPRINT_20260314_001_Platform_integration_success_path_fixtures.md
@@ -0,0 +1,80 @@
+# Sprint 20260314_001 - Platform Integration Success Path Fixtures
+
+## Topic & Scope
+- Add deterministic local external-service fixtures for the UI-exposed integration providers so scratch setup can prove successful onboarding, not just graceful failure handling.
+- Wire the fixture lane into the documented setup path as an explicit opt-in QA mode instead of relying on ad hoc manual containers.
+- Extend retained Playwright coverage so Harbor and GitHub App onboarding can be verified from the real UI with successful test-connection and health outcomes.
+- Working directory: `devops/compose`.
+- Cross-module edits allowed for `scripts/setup.ps1`, `scripts/setup.sh`, `scripts/run-clean-scratch-iterations.ps1`, `src/Web/StellaOps.Web/scripts/**`, `docs/**`, `NOTICE.md`, and `docs/legal/THIRD-PARTY-DEPENDENCIES.md`.
+- Expected evidence: compose fixture definitions, hosts/docs updates, setup wiring, retained Playwright success-path evidence, and scratch-loop adoption notes.
+
+## Dependencies & Concurrency
+- Depends on the currently active scratch iteration proving the integrations UI/runtime path is contract-correct before fixture-based success-path work is layered on top.
+- Safe parallelism: fixture compose/docs work may proceed while unrelated product slices continue, but setup script edits should be serialized.
+
+## Documentation Prerequisites
+- `AGENTS.md`
+- `src/Integrations/AGENTS.md`
+- `docs/dev/DEV_ENVIRONMENT_SETUP.md`
+- `docs/INSTALL_GUIDE.md`
+- `devops/compose/README.md`
+- `docs/modules/integrations/architecture.md`
+
+## Delivery Tracker
+
+### PLATFORM-INTEGRATION-FIXTURES-001 - Define deterministic external integration fixtures
+Status: DONE
+Dependency: none
+Owners: Architect, Developer
+Task description:
+- Add lightweight deterministic fixture services for Harbor and GitHub App style APIs so the locally visible onboarding providers have a success-path target during scratch QA.
+
+Completion criteria:
+- [x] Fixture compose file exists with deterministic Harbor and GitHub App endpoints.
+- [x] Local hostnames/ports are documented and added to the compose host template.
+- [x] License/notice updates are recorded for any newly introduced infrastructure image.
+
+### PLATFORM-INTEGRATION-FIXTURES-002 - Wire fixture mode into documented setup
+Status: DONE
+Dependency: PLATFORM-INTEGRATION-FIXTURES-001
+Owners: Developer, Documentation author
+Task description:
+- Extend setup scripts and setup docs with an explicit fixture-enabled QA mode so scratch rebuilds can include the success-path integrations lane without ad hoc manual steps.
+
+Completion criteria:
+- [x] `setup.ps1` and `setup.sh` can start fixture services in a documented QA mode.
+- [x] Scratch iteration tooling can opt into the fixture mode.
+- [x] Install/dev docs explain when and how to use the fixture lane.
+
+### PLATFORM-INTEGRATION-FIXTURES-003 - Add retained Playwright success-path coverage
+Status: DONE
+Dependency: PLATFORM-INTEGRATION-FIXTURES-002
+Owners: QA, Test Automation
+Task description:
+- Add retained Playwright that onboards Harbor and GitHub App from the real UI against the deterministic fixtures, verifies successful test-connection/health behavior, and folds the scenario into the aggregate scratch audit.
+
+Completion criteria:
+- [x] Retained Playwright success-path scripts exist for the fixture-backed onboarding flows.
+- [x] Aggregate audit includes the new success-path suite(s).
+- [x] Scratch QA evidence shows successful UI onboarding and cleanup for both providers.
+
+## Execution Log
+| Date (UTC) | Update | Owner |
+| --- | --- | --- |
+| 2026-03-14 | Sprint created after the integrations onboarding iteration proved contract-correct UI flow but exposed a remaining QA gap: success-path external fixtures do not yet exist for the UI-exposed Harbor and GitHub App providers. | Architect / QA |
+| 2026-03-14 | Added deterministic Harbor and GitHub App fixture compose services, documented their host aliases, and recorded the NGINX image license/notice updates required by the BUSL dependency gate. | Architect / Developer |
+| 2026-03-14 | Wired explicit `-QaIntegrationFixtures` / `--qa-integration-fixtures` setup modes into the documented setup entrypoints and scratch runner, and hardened fixture smoke checks to use loopback bindings when the host file cannot be elevated on the local machine. | Developer / Documentation author |
+| 2026-03-14 | Added retained Playwright success-path onboarding for Harbor and GitHub App, discovered the GitHub App `/api/v3` path normalization bug during real UI test-connection, fixed it at the connector layer, and reverified the full aggregate audit clean at `24/24` suites passed. | QA / 3rd line support / Developer |
+
+## Decisions & Risks
+- Decision: fixture-backed success-path onboarding is a QA infrastructure requirement, not a product shortcut; the product still keeps real provider contracts and AuthRef behavior.
+- Decision: fixture mode stays explicit and opt-in so the default local product setup remains production-shaped.
+- Risk: adding third-party infrastructure images triggers the repo license gate and doc updates; this must be handled inside the same slice.
+- Decision: setup host verification now checks the complete `devops/compose/hosts.stellaops.local` alias set instead of treating any `stella-ops.local` entry as sufficient; partial host-file state was masking fixture readiness gaps.
+- Decision: optional fixture smoke probes use fixed loopback bindings (`127.1.1.6`, `127.1.1.7`) during setup so the documented setup path remains verifiable in a non-elevated shell even when Windows host-file writes are blocked.
+- Decision: GitHub App endpoints are normalized to exactly one API root; GitHub Cloud uses `https://api.github.com/`, while GHES accepts either the appliance root or an explicit `/api/v3` base without duplicating or stripping the API prefix.
+- Docs: [DEV_ENVIRONMENT_SETUP.md](/C:/dev/New%20folder/git.stella-ops.org/docs/dev/DEV_ENVIRONMENT_SETUP.md), [INSTALL_GUIDE.md](/C:/dev/New%20folder/git.stella-ops.org/docs/INSTALL_GUIDE.md), [architecture.md](/C:/dev/New%20folder/git.stella-ops.org/docs/modules/integrations/architecture.md), [README.md](/C:/dev/New%20folder/git.stella-ops.org/devops/compose/README.md)
+
+## Next Checkpoints
+- Fold the fixture-enabled setup lane into the next zero-state scratch iteration so the widened integration discovery becomes part of the normal first-user audit baseline.
+- Expand the same approach only if additional providers become UI-exposed in later iterations.
--- a/docs/legal/THIRD-PARTY-DEPENDENCIES.md
+++ b/docs/legal/THIRD-PARTY-DEPENDENCIES.md
@@ -17,7 +17,7 @@ This document provides a comprehensive inventory of all third-party dependencies
 | NuGet (Dev/Test) | ~50+ | MIT, Apache-2.0 |
 | npm (Runtime) | ~15 | MIT, Apache-2.0, ISC, 0BSD |
 | npm (Dev) | ~30+ | MIT, Apache-2.0 |
-| Infrastructure | 6 | PostgreSQL, MPL-2.0, BSD-3-Clause, Apache-2.0 |
+| Infrastructure | 7 | PostgreSQL, MPL-2.0, BSD-2-Clause, BSD-3-Clause, Apache-2.0 |

 ### Canonical License Declarations

@@ -290,6 +290,7 @@ Components required for deployment but not bundled with StellaOps source.
 | Valkey | ≥7.2 | BSD-3-Clause | BSD-3-Clause | Separate | Optional cache (Redis fork) for StellaOps and Rekor |
 | Rekor v2 (rekor-tiles) | v2 (tiles) | Apache-2.0 | Apache-2.0 | Separate | Optional transparency log (POSIX tiles backend) |
 | Docker | ≥24 | Apache-2.0 | Apache-2.0 | Tooling | Container runtime |
+| NGINX | 1.27-alpine | BSD-2-Clause | BSD-2-Clause | Separate | Optional local QA fixture image for Harbor and GitHub App onboarding success-path checks |
 | OCI Registry | - | Varies | - | External | Harbor (Apache-2.0), Docker Hub, etc. |
 | Kubernetes | ≥1.28 | Apache-2.0 | Apache-2.0 | Orchestration | Optional |
 | all-MiniLM-L6-v2 embedding model | - | Apache-2.0 | Apache-2.0 | Optional runtime asset | Local semantic embedding model for AdvisoryAI (`VectorEncoderType=onnx`) |
--- a/docs/modules/integrations/architecture.md
+++ b/docs/modules/integrations/architecture.md
@@ -96,6 +96,11 @@ public interface IIntegrationPlugin
 - **Harbor** - Robot account authentication, project and repository enumeration
 - **InMemory** - Deterministic test double for integration tests and offline development

+### Provider endpoint contracts
+
+- **GitHub App** - Operators provide either the GitHub Cloud root (`https://github.com`), a GitHub Enterprise Server root, or an explicit `/api/v3` base. The connector normalizes the endpoint to a single API root and probes relative `app` / `rate_limit` paths so GitHub Enterprise onboarding never falls back to origin-root `/app`.
+- **Harbor** - Operators provide the Harbor base URL. Stella Ops probes the provider-specific `/api/v2.0/health` route for connection tests and health checks.
+
 ## Security Considerations

 - **AuthRef URI credential model:** Credentials are stored in an external vault (e.g., HashiCorp Vault, Azure Key Vault). The integration catalog stores only the URI reference (`authref://vault/path/to/secret`), never the raw secret.