From 47e20dd8a847481b08e1459cf9ce3c1ddf5046c1 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Mon, 14 Sep 2026 13:28:49 -0400 Subject: [PATCH] docs(plans): pending-updates design + plan (site artifact staleness, rail indicator, scrollable nav) Claude-Session: https://claude.ai/code/session_01Y5ef34iUUMjmwnMpL9xgmB --- .../2026-09-14-pending-updates-design.md | 127 ++++++++++ docs/plans/2026-09-14-pending-updates.md | 217 ++++++++++++++++++ .../2026-09-14-pending-updates.md.tasks.json | 104 +++++++++ 3 files changed, 448 insertions(+) create mode 100644 docs/plans/2026-09-14-pending-updates-design.md create mode 100644 docs/plans/2026-09-14-pending-updates.md create mode 100644 docs/plans/2026-09-14-pending-updates.md.tasks.json diff --git a/docs/plans/2026-09-14-pending-updates-design.md b/docs/plans/2026-09-14-pending-updates-design.md new file mode 100644 index 00000000..e6f4b6c3 --- /dev/null +++ b/docs/plans/2026-09-14-pending-updates-design.md @@ -0,0 +1,127 @@ +# Pending Updates: site artifact staleness, rail indicator, scrollable nav — Design + +**Date:** 2026-09-14 · **Status:** approved for implementation (plan: `2026-09-14-pending-updates.md`) + +## 1. Ask + +Three Central UI changes, requested together: + +1. The **Sites page** does not show whether a site's deployed **system-wide artifacts** (shared scripts, + external systems, DB connections, that site's data connections) are out of date. It should carry a + Stale / Current badge like the Topology (template-instance) page does for instances. +2. A **single "pending updates" indicator** in the rail footer, bottom-left just above the user name, + summarising both kinds of pending update: stale instances and sites with stale artifacts. +3. The expanding rail menu should sit in a **scroll pane** so a long nav never pushes the footer off-screen. + +## 2. Current state (verified 2026-09-14) + +- Instance staleness = `DeploymentService.GetDeploymentComparisonAsync` re-flattens the instance + (`validateScripts:false`) and compares `RevisionHash` with the `DeployedConfigSnapshot` (after the I-1 + List-value normalisation). Topology computes it per loaded page with bounded concurrency, off the + 15 s live timer, with a *Re-check staleness* button. There is **no aggregate** anywhere. +- Artifact deployment (`ArtifactDeploymentService`) builds one `DeployArtifactsCommand` per site and + persists a `SystemArtifactDeploymentRecord` with a per-site status JSON, but **records no revision of + what was sent**, so "are this site's artifacts current?" is currently unanswerable. +- The rail is the `ZB.MOM.WW.Theme` kit's `ThemeShell` (`nav.side-rail`, flex column; `.rail-foot` + has `margin-top:auto`; `#theme-rail` is sticky `100vh` on ≥ lg). The nav items are direct children + of `.side-rail`; nothing scrolls internally, so a long nav grows past the viewport. +- `SingleFlightMemo` + `KpiSnapshotCache` already give the process-level, per-TTL, single-flight + cache shape a polled aggregate needs. + +## 3. Design + +### 3.1 Site artifact revision (Commons + ConfigurationDatabase + DeploymentManager) + +- `Site` gains two nullable columns: `ArtifactRevisionHash` (`string?`, max 100) and + `ArtifactsDeployedAt` (`DateTimeOffset?`). Migration `AddSiteArtifactRevision`. Additive; a site that + has never had artifacts deployed stays `null` = **Never deployed**. +- New `ArtifactRevisionHashService` (DeploymentManager) computes a deterministic SHA-256 over a + canonical projection of a per-site `DeployArtifactsCommand`: every artifact class sorted by `Name` + (ordinal), `DeploymentId`/timestamp excluded, alphabetically-declared hashable records, camelCase + JSON, nulls omitted — the same determinism contract as `RevisionHashService`, pinned by a test. + Data-connection configuration is plaintext in memory (EF value converter), so a no-op re-save that + re-encrypts at rest does not change the hash. +- `ArtifactDeploymentService` stamps `ArtifactRevisionHash` + `ArtifactsDeployedAt` on the `Site` row + **only for a site whose deploy succeeded** (both `DeployCoreAsync` and `RetryForSiteAsync`). A failed + site keeps its previous stamp, so it keeps showing out of date. The stamp is written in the same + `SaveChanges` as the deployment record where possible. +- `ArtifactDeploymentService.ComputeCurrentArtifactHashesAsync(sites)` returns `siteId → hash` for the + *current* definitions, hoisting the global artifact queries once (same shape as `DeployCoreAsync`). +- **Transport does NOT carry the two columns.** They are environment-specific runtime state, exactly + like imported instances landing `NotDeployed`; the round-trip guard exclusion list names them with + that reason. An import that changes a site's data connections therefore makes the site read + *out of date* until artifacts are redeployed — the correct outcome. + +### 3.2 Pending-updates aggregate (DeploymentManager, cached in CentralUI) + +- `DeploymentService.GetInstanceStalenessAsync(instanceIds)` → `IReadOnlyDictionary`: + one shared `FlattenSession` for the batch (template chains walked once, as `DeploySiteAsync` does), + compares against a **projection read** of `(InstanceId, RevisionHash)` from `DeployedConfigSnapshot` + (new `IDeploymentManagerRepository.GetDeployedRevisionHashesAsync()` — never the fat + `ConfigurationJson` for the whole fleet). For a hash **mismatch only**, the full snapshot is read and + the I-1 normalised deployed hash recomputed, so the aggregate agrees exactly with the Topology badge + on old-form List snapshots. `null` = could not evaluate (flatten failed) — counted as *unknown*, never + as stale. +- `PendingUpdatesEvaluator` (scoped, DeploymentManager) → `PendingUpdatesSnapshot`: + `ComputedAt`, per site `SitePendingUpdates(SiteId, SiteIdentifier, SiteName, ArtifactState + {NeverDeployed|Current|OutOfDate}, ArtifactsDeployedAt, DeployedInstanceCount, StaleInstanceCount, + UnknownInstanceCount)`, plus totals `StaleInstanceCount` and `StaleArtifactSiteCount`. Instances are + those with a deployed snapshot (the same gate Topology uses: `State != NotDeployed`). +- `IPendingUpdatesCache` / `PendingUpdatesCache` (CentralUI, **singleton**, mirrors `KpiSnapshotCache`): + one `SingleFlightMemo` with TTL `DeploymentManagerOptions.PendingUpdatesCacheTtl` + (default 60 s, validated > 0), running the evaluator in its own DI scope. `GetAsync(forceRefresh)`. + Consequence: however many circuits poll, the fleet is flattened at most once per TTL, and not at + all when nobody is looking. +- Not in scope (register rows): a template-graph-watermark short-circuit so an unchanged fleet costs + no re-flatten; a `deploy` CLI/`Health` KPI surface for the counts. + +### 3.3 Sites page (Admin) + +- Each site card shows an **Artifacts** badge next to the identifier: `Current` (light), `Out of date` + (warning, `bi-exclamation-triangle`, tooltip = deployed-at UTC), `Never deployed` (secondary). Below + it a muted line `N of M instances out of date` (link to `/deployment/topology`) when M > 0, since the + snapshot already carries it. Badges match Topology's Bootstrap `.badge` convention (the kit's + `StatusPill` is unused in this app). +- Header gains *Re-check* (forces `GetAsync(forceRefresh:true)`, disabled while running) and an + *as of HH:mm:ss UTC* caption. A successful Deploy Artifacts (single or all) forces a refresh so the + badge flips to Current immediately. +- The snapshot is loaded after the site list, never blocking it: cards render with a *checking…* + placeholder until it arrives; a snapshot failure shows *unavailable* on the badge and logs. + +### 3.4 Rail indicator (`PendingUpdatesIndicator`, MainLayout `RailFooter`, above `.rail-user`) + +- Rendered only for a user holding **Deployer or Administrator** (the two roles that can act on it); + hidden otherwise. Polls `IPendingUpdatesCache.GetAsync()` every 30 s through `PollGate` (cache TTL + 60 s ⇒ polling is cheap), disposes its timer with the circuit, renders via `InvokeAsync`. +- States: *Checking for updates…* (first load) · *Up to date* (muted, check icon) · **Pending updates** + with a warning count pill and a breakdown line: `3 instances` (links to Topology when Deployer) · + `1 site` (links to `/admin/sites` when Administrator, plain text otherwise) · *Updates unavailable* + (error, tooltip has the message). Tooltip on the block: *as of HH:mm UTC*. +- Site-scoped users see only their permitted sites' counts (`SiteScopeService`), consistent with + Topology. + +### 3.5 Scrollable nav + +- `NavMenu.razor` wraps its items in `
`; `site.css` adds, ≥ lg only: + `#theme-rail > .side-rail { height: 100%; }` (fill the sticky 100 vh rail so `.rail-foot`'s + `margin-top:auto` actually pins) and `.rail-scroll { flex: 1 1 auto; min-height: 0; overflow-y: auto; + overscroll-behavior: contain; }`. Below lg the rail is inline and scrolls with the page, unchanged. + Kit untouched; a register row proposes upstreaming it into `ZB.MOM.WW.Theme` for the other consumers. + +## 4. Tests + +- Unit: hash determinism (order-insensitive, field-sensitive, alphabetical-declaration guard); stamping + on success only; `GetInstanceStalenessAsync` (shared session used once, mismatch-only normalisation, + null on flatten failure); evaluator totals; cache single-flight/TTL/force; bUnit for the indicator + (all states, role gating, scope filter), Sites page (badges, re-check, refresh-after-deploy), NavMenu + wrapper; Transport round-trip guard exclusions; migration snapshot. +- Rig: `docker/deploy.sh` (migration auto-applies), `docker/verify-pending-updates.sh` (CLI: site list + shows `artifactRevisionHash` null → deploy artifacts → set; edit a shared script → central UI shows + out of date; redeploy → current), plus a Playwright smoke for the indicator + Sites badge. + +## 5. Operational notes + +- Production/QA: the migration ships as a delta script (`dotnet ef migrations script + AddAlarmMesReportable AddSiteArtifactRevision`). After upgrade every site reads **Never deployed** + until artifacts are deployed once — deliberate; one *Deploy Artifacts to All Sites* clears it. +- Cost: one fleet flatten per `PendingUpdatesCacheTtl` while any Deployer/Admin circuit is open. diff --git a/docs/plans/2026-09-14-pending-updates.md b/docs/plans/2026-09-14-pending-updates.md new file mode 100644 index 00000000..162c4341 --- /dev/null +++ b/docs/plans/2026-09-14-pending-updates.md @@ -0,0 +1,217 @@ +# Pending Updates Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers-extended-cc:executing-plans to implement this plan task-by-task. + +**Goal:** Show on the Sites page whether each site's deployed artifacts are out of date, add one rail-footer indicator summarising pending updates (stale instances + stale-artifact sites), and put the rail nav in a scroll pane. + +**Architecture:** Two nullable columns on `Site` record the revision hash of the last successful artifact deploy (stamped by `ArtifactDeploymentService`); a new `PendingUpdatesEvaluator` (DeploymentManager) computes one `PendingUpdatesSnapshot` per fleet (artifact hash comparison per site + one shared-session instance-staleness batch), cached process-wide by a singleton `PendingUpdatesCache` (CentralUI, `SingleFlightMemo`) that the Sites page and the rail indicator both read. The scroll pane is an app-level wrapper + CSS; the theme kit is untouched. + +**Tech Stack:** .NET 10, EF Core (SQL Server migration), Blazor Server + Bootstrap 5 + bUnit, NSubstitute, Playwright, bash + `scadabridge` CLI on the docker rig. + +**Design:** `docs/plans/2026-09-14-pending-updates-design.md`. + +**Conventions for every task** (from `CLAUDE.md` + memory): +- Work in the dedicated worktree `/Users/dohertj2/Desktop/ScadaBridge-pending-updates` (Task 0). Use absolute paths in every command — Bash cwd drifts. +- Run **targeted** tests per task (`dotnet test --filter …`) and build the affected projects; the full solution build/test runs only in Task 11. +- Never `git stash` (shared across worktrees). Commit with pathspecs. End every commit message with + `Claude-Session: https://claude.ai/code/session_01Y5ef34iUUMjmwnMpL9xgmB`. +- Every public member needs an XML doc comment (`checkdocs` enforces it). +- Never `await` an audit write on a script path; never block on a Task from a Blazor lifecycle/event path. +- Bootstrap `.badge` markup for badges (matches Topology); no third-party component libraries. + +--- + +### Task 0: Worktree + +**Classification:** trivial · **Estimated implement time:** ~2 min · **Parallelizable with:** none + +```bash +cd /Users/dohertj2/Desktop/ScadaBridge +git worktree add -b feat/pending-updates ../ScadaBridge-pending-updates main +cd /Users/dohertj2/Desktop/ScadaBridge-pending-updates && dotnet build ZB.MOM.WW.ScadaBridge.slnx 2>&1 | tail -3 +``` +Expected: `0 Error(s)`. + +--- + +### Task 1: Site artifact revision columns, migration, repository projection, Transport guard + +**Classification:** high-risk (schema + data contract) · **Estimated implement time:** ~5 min · **Parallelizable with:** Task 8 + +**Files:** +- Modify: `src/ZB.MOM.WW.ScadaBridge.Commons/Entities/Sites/Site.cs` — add `public string? ArtifactRevisionHash { get; set; }` and `public DateTimeOffset? ArtifactsDeployedAt { get; set; }` with XML docs ("revision hash of the per-site artifact set last deployed successfully; null = never deployed; NOT transported"). +- Modify: `src/ZB.MOM.WW.ScadaBridge.ConfigurationDatabase/Configurations/SiteConfiguration.cs` — `ArtifactRevisionHash` `HasMaxLength(100)`. +- Create: migration `AddSiteArtifactRevision` in `src/ZB.MOM.WW.ScadaBridge.ConfigurationDatabase/Migrations/` — **build first, then** `dotnet ef migrations add AddSiteArtifactRevision --project src/ZB.MOM.WW.ScadaBridge.ConfigurationDatabase --startup-project src/ZB.MOM.WW.ScadaBridge.Host` (check how `AddAlarmMesReportable` was generated: `git log -1 --stat 4cfa645b^..` / the previous plan; NO `--no-build`). Verify the migration is non-empty (two `AddColumn`). +- Modify: `src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Repositories/IDeploymentManagerRepository.cs` — add `Task> GetDeployedRevisionHashesAsync(CancellationToken cancellationToken = default);` ("InstanceId → RevisionHash for every DeployedConfigSnapshot; a projection — never materialises ConfigurationJson"). +- Modify: `src/ZB.MOM.WW.ScadaBridge.ConfigurationDatabase/Repositories/DeploymentManagerRepository.cs` — implement with `.AsNoTracking().Select(s => new { s.InstanceId, s.RevisionHash })`. +- Modify: Transport round-trip guard exclusions (find with `grep -rn "GrpcNodeBAddress\|RoundTrip" tests/ZB.MOM.WW.ScadaBridge.Transport.Tests tests/ZB.MOM.WW.ScadaBridge.Transport.IntegrationTests`) — add the two new `Site` properties to the *deliberately-not-transported* list with the reason "environment-specific deploy state, like Instance.State". +- Test: `tests/ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Tests/` — a repository test for `GetDeployedRevisionHashesAsync` (SQLite in-memory pattern used by neighbouring tests): two snapshots → dictionary of two; empty → empty. + +**Steps:** write the failing repo test → implement → migration → run `dotnet test tests/ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Tests --filter "FullyQualifiedName~DeployedRevisionHashes"` and the Transport guard tests (`--filter "FullyQualifiedName~RoundTrip"`) → commit `feat(sites): record the artifact revision last deployed to a site`. + +--- + +### Task 2: ArtifactRevisionHashService + stamping on successful deploy + +**Classification:** standard · **Estimated implement time:** ~5 min · **Parallelizable with:** Task 3, Task 8 + +**Files:** +- Create: `src/ZB.MOM.WW.ScadaBridge.DeploymentManager/ArtifactRevisionHashService.cs` — `public sealed class ArtifactRevisionHashService { public string ComputeHash(DeployArtifactsCommand command) }`. Canonical projection: private `Hashable*` records with **alphabetically declared** properties, each artifact list `OrderBy(Name, StringComparer.Ordinal)`, `DeploymentId` and the timestamp excluded, `JsonNamingPolicy.CamelCase`, `WhenWritingNull`, SHA-256 hex (lower-case, like `RevisionHashService`). Cover every field of `SharedScriptArtifact`, `ExternalSystemArtifact`, `DatabaseConnectionArtifact`, `DataConnectionArtifact` (read the record definitions under `Commons/Messages/Artifacts/`). +- Modify: `src/ZB.MOM.WW.ScadaBridge.DeploymentManager/ArtifactDeploymentService.cs`: + - inject `ArtifactRevisionHashService`; + - `DeployCoreAsync`: after `Task.WhenAll`, for each site whose result `Success`, set `site.ArtifactRevisionHash = hash(siteCommands[site.Id])`, `site.ArtifactsDeployedAt = DateTimeOffset.UtcNow`, then persist through `ISiteRepository` (use its existing update + save methods — check the interface; the `Site` entities came from `_siteRepo.GetAllSitesAsync` and are tracked, so an `UpdateSiteAsync`/`SaveChangesAsync` pair is enough). Failed sites are NOT stamped. + - `RetryForSiteAsync`: same stamp on success (load the site by id). + - add `public async Task> ComputeCurrentArtifactHashesAsync(IReadOnlyList sites, CancellationToken ct)` — one `FetchGlobalArtifactsAsync`, then per site `BuildDeployArtifactsCommandAsync(site.Id, globals, ct, deploymentId: "current")` → hash. (`deploymentId` is excluded from the hash, so any constant is fine.) +- Modify: `src/ZB.MOM.WW.ScadaBridge.DeploymentManager/ServiceCollectionExtensions.cs` — register `ArtifactRevisionHashService` singleton. +- Modify: every test that constructs `ArtifactDeploymentService` directly (grep `new ArtifactDeploymentService(` under `tests/` — at least `tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests/Admin/SitesPageTests.cs` and the DeploymentManager tests) — pass `new ArtifactRevisionHashService()`. +- Test: `tests/ZB.MOM.WW.ScadaBridge.DeploymentManager.Tests/ArtifactRevisionHashServiceTests.cs` — same input twice → same hash; lists reordered → same hash; one field changed (per artifact class) → different hash; different `DeploymentId`/timestamp → same hash; `HashableRecords_PropertiesDeclaredAlphabetically` (reflection, mirror `RevisionHashServiceTests`). `ArtifactDeploymentServiceTests` — success stamps hash + timestamp; failure leaves the previous stamp; `ComputeCurrentArtifactHashesAsync` equals the hash stamped by a deploy of the same definitions. + +**Steps:** failing tests → implement → `dotnet test tests/ZB.MOM.WW.ScadaBridge.DeploymentManager.Tests --filter "FullyQualifiedName~ArtifactRevisionHash|FullyQualifiedName~ArtifactDeploymentService"` → commit `feat(deploy): hash the per-site artifact set and stamp it on a successful artifact deploy`. + +--- + +### Task 3: DeploymentService.GetInstanceStalenessAsync (shared session, mismatch-only normalisation) + +**Classification:** standard · **Estimated implement time:** ~5 min · **Parallelizable with:** Task 2, Task 8 + +**Files:** +- Modify: `src/ZB.MOM.WW.ScadaBridge.DeploymentManager/DeploymentService.cs`: + - extract from `GetDeploymentComparisonAsync` a private `string ComputeDeployedHash(DeployedConfigSnapshot snapshot, out FlattenedConfiguration? normalized)` that applies the I-1 List normalisation and recomputes the hash (returns `snapshot.RevisionHash` when the JSON cannot be deserialised) — `GetDeploymentComparisonAsync` must keep behaving byte-for-byte (its existing tests pin it). + - add `public async Task> GetInstanceStalenessAsync(IReadOnlyCollection instanceIds, CancellationToken cancellationToken = default)`: read `GetDeployedRevisionHashesAsync()` once; `var session = _flatteningPipeline.CreateSession();` for each id with a snapshot hash: `FlattenAndValidateAsync(id, ct, validateScripts:false, session)`; failure → `null`; equal hash → `false`; mismatch → read the full snapshot (`GetDeployedSnapshotByInstanceIdAsync`), `ComputeDeployedHash`, compare again → `true`/`false`. Ids without a snapshot are omitted from the result. Sequential (the repository DbContext is not thread-safe); add a doc comment saying so. +- Test: `tests/ZB.MOM.WW.ScadaBridge.DeploymentManager.Tests/DeploymentServiceStalenessTests.cs` (or extend the existing DeploymentService test class; check how it is constructed — `IFlatteningPipeline` is substitutable): shared session passed to every flatten call (`Received` with the same `FlattenSession` instance, `CreateSession` called once); equal → false; mismatch that normalises equal → false; real mismatch → true; flatten failure → null; no snapshot → absent. + +**Steps:** failing tests → implement → `dotnet test tests/ZB.MOM.WW.ScadaBridge.DeploymentManager.Tests --filter "FullyQualifiedName~Staleness|FullyQualifiedName~DeploymentComparison"` → commit `feat(deploy): batch instance staleness over one flatten session`. + +--- + +### Task 4: PendingUpdatesEvaluator + snapshot types + options + +**Classification:** standard · **Estimated implement time:** ~5 min · **Parallelizable with:** none (needs 2 + 3) + +**Files:** +- Create: `src/ZB.MOM.WW.ScadaBridge.DeploymentManager/PendingUpdates/PendingUpdatesSnapshot.cs` — `public enum ArtifactDeploymentState { NeverDeployed, Current, OutOfDate }`; `public sealed record SitePendingUpdates(int SiteId, string SiteIdentifier, string SiteName, ArtifactDeploymentState ArtifactState, DateTimeOffset? ArtifactsDeployedAt, int DeployedInstanceCount, int StaleInstanceCount, int UnknownInstanceCount)`; `public sealed record PendingUpdatesSnapshot(DateTimeOffset ComputedAt, IReadOnlyList Sites)` with computed `StaleInstanceCount`, `StaleArtifactSiteCount`, `HasPendingUpdates`, and `ForSites(IReadOnlySet siteIds)` returning a filtered copy (for site-scoped users). +- Create: `src/ZB.MOM.WW.ScadaBridge.DeploymentManager/PendingUpdates/IPendingUpdatesEvaluator.cs` + `PendingUpdatesEvaluator.cs` (scoped): `Task EvaluateAsync(CancellationToken)`. Reads all sites (`ISiteRepository.GetAllSitesAsync`), all instances (`ITemplateEngineRepository.GetAllInstancesAsync`), `ArtifactDeploymentService.ComputeCurrentArtifactHashesAsync(sites)`, `DeploymentService.GetInstanceStalenessAsync(ids of instances with State != NotDeployed)`. Artifact state: null stored hash → NeverDeployed; equal → Current; else OutOfDate. Per site: deployed = instances of that site present in the staleness result; stale = `true`; unknown = `null`. A per-site artifact-hash failure must not sink the whole snapshot — log and mark that site `OutOfDate`? **No:** mark it *unknown* is not a state we have; keep it simple: let the exception propagate (the cache discards faulted flights and the UI shows *unavailable*). +- Modify: `src/ZB.MOM.WW.ScadaBridge.DeploymentManager/DeploymentManagerOptions.cs` — `public TimeSpan PendingUpdatesCacheTtl { get; set; } = TimeSpan.FromSeconds(60);` + validation `> TimeSpan.Zero` wherever the other TimeSpans are validated (find the validator; §1.5 eager validation). +- Modify: `ServiceCollectionExtensions.cs` (DeploymentManager) — `services.AddScoped()`. +- Test: `tests/ZB.MOM.WW.ScadaBridge.DeploymentManager.Tests/PendingUpdatesEvaluatorTests.cs` — build with substitutes for the repositories and (if `DeploymentService`/`ArtifactDeploymentService` are not substitutable) small interface seams: prefer adding `IArtifactRevisionSource` / reuse the real services with substituted repos as `TopologyPageTests` does. Cases: never-deployed site; current; out-of-date; instance counts (2 deployed, 1 stale, 1 unknown); `ForSites` filter; options validation rejects zero TTL. + +**Steps:** failing tests → implement → `dotnet test tests/ZB.MOM.WW.ScadaBridge.DeploymentManager.Tests --filter "FullyQualifiedName~PendingUpdates"` → commit `feat(deploy): PendingUpdatesEvaluator — one fleet snapshot of stale instances and stale-artifact sites`. + +--- + +### Task 5: PendingUpdatesCache (CentralUI singleton) + +**Classification:** small · **Estimated implement time:** ~3 min · **Parallelizable with:** none (needs 4) + +**Files:** +- Create: `src/ZB.MOM.WW.ScadaBridge.CentralUI/Services/IPendingUpdatesCache.cs` — `Task GetAsync(bool forceRefresh = false, CancellationToken cancellationToken = default);` +- Create: `src/ZB.MOM.WW.ScadaBridge.CentralUI/Services/PendingUpdatesCache.cs` — mirrors `KpiSnapshotCache`: ctor `(IServiceScopeFactory, IOptions)`, one `SingleFlightMemo(options.Value.PendingUpdatesCacheTtl)`, factory opens a scope and resolves `IPendingUpdatesEvaluator`. +- Modify: `src/ZB.MOM.WW.ScadaBridge.CentralUI/ServiceCollectionExtensions.cs` — `services.AddSingleton();` next to `IKpiSnapshotCache`. +- Test: `tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests/Services/PendingUpdatesCacheTests.cs` — two concurrent `GetAsync` → evaluator invoked once; `forceRefresh:true` after completion → invoked again; a faulted evaluation is not cached (next call re-invokes). + +**Steps:** failing tests → implement → `dotnet test tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests --filter "FullyQualifiedName~PendingUpdatesCache"` → commit `feat(central-ui): process-wide single-flight cache for the pending-updates snapshot`. + +--- + +### Task 6: Rail indicator component + +**Classification:** standard · **Estimated implement time:** ~5 min · **Parallelizable with:** Task 7 + +**Files:** +- Create: `src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Layout/PendingUpdatesIndicator.razor` (+ `.razor.cs` if the file grows). Injects `IPendingUpdatesCache`, `SiteScopeService`, `AuthenticationStateProvider`, `ILogger<>`. Renders nothing unless the user has the `Deployer` or `Administrator` role claim (`JwtTokenService.RoleClaimType`, like `NavMenu`'s Notifications block). Markup (all inside `
`): + - loading: ` Checking for updates…` + - up to date: ` Up to date` + - pending: ` Pending updates N` (N = stale instances + stale-artifact sites) then `` with `X instance(s)` (an `` when Deployer, else text) · `Y site(s)` (an `` when Administrator, else text); omit a zero part. + - error: ` Updates unavailable`. + - Site-scoped user: `snapshot.ForSites(await SiteScope.PermittedSiteIdsAsync())` unless `IsSystemWideAsync()`. + - Poll: `System.Threading.Timer` every 30 s through a `PollGate`, first load in `OnInitializedAsync`; `IDisposable` disposes the timer and sets `_disposed`; every re-render via `InvokeAsync(StateHasChanged)` guarded by `_disposed`; catch `ObjectDisposedException`/`InvalidOperationException` from a torn-down circuit. +- Modify: `src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Layout/MainLayout.razor` — inside `` ``, place `` immediately **above** ``. +- Modify: `src/ZB.MOM.WW.ScadaBridge.CentralUI/wwwroot/css/site.css` — append a `/* ── Rail pending-updates indicator ── */` block: `.rail-updates { padding: 0 0.6rem 0.5rem; font-size: 0.8rem; display:flex; flex-direction:column; gap:0.15rem; }`, `.rail-updates-muted { color: var(--ink-faint); }`, `.rail-updates-head { font-weight: 600; color: var(--ink-soft); display:flex; align-items:center; gap:0.35rem; }`, `.rail-updates-detail { color: var(--ink-faint); }`, `.rail-updates a { color: inherit; text-decoration: underline dotted; }`. Use tokens only (dark mode follows). +- Test: `tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests/Layout/PendingUpdatesIndicatorTests.cs` — bUnit with `Substitute.For()`, `TestAuthStateProvider` (copy `NavMenuTests`' claims helper), a `SiteScopeService` over that provider: hidden for Viewer; "Up to date" for empty snapshot; "Pending updates" + `3` + links for Deployer+Admin; Deployer-only renders the site count as text (no `/admin/sites` href); faulted cache → "Updates unavailable"; scoped user sees filtered counts. Use `WaitForAssertion`. + +**Steps:** failing tests → implement → `dotnet test tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests --filter "FullyQualifiedName~PendingUpdatesIndicator"` → commit `feat(central-ui): rail-footer pending-updates indicator`. + +--- + +### Task 7: Sites page artifact badges, instance line, re-check + +**Classification:** standard · **Estimated implement time:** ~5 min · **Parallelizable with:** Task 6 + +**Files:** +- Modify: `src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Pages/Admin/Sites.razor`: + - `@inject IPendingUpdatesCache PendingUpdates`; fields `PendingUpdatesSnapshot? _updates; string? _updatesError; bool _recheckingUpdates;`. + - `LoadDataAsync` loads sites/connections as today, then (not blocking the card render) `await LoadUpdatesAsync(force:false)`; `LoadUpdatesAsync` catches, sets `_updatesError`, logs a Warning. + - Header: after the title, a small muted caption `Updates as of HH:mm:ss UTC` when `_updates` is set, and a `btn btn-outline-secondary btn-sm` **Re-check** button (spinner + disabled while `_recheckingUpdates`) calling `LoadUpdatesAsync(force:true)`. + - Card: next to `@site.SiteIdentifier` render `ArtifactBadge(site.Id)`: `_updates is null && _updatesError is null` → `Artifacts: checking…`; error → `Artifacts: unavailable`; else by state: `Current` → `bg-light text-dark`, `OutOfDate` → `bg-warning text-dark` with `` and `title="Artifacts deployed "`, `NeverDeployed` → `bg-secondary`. All carry `aria-label="Artifacts: "`. Text: `Artifacts current` / `Artifacts out of date` / `Artifacts never deployed`. + - Under the description: when the site's `DeployedInstanceCount > 0`, `
@stale of @deployed instances out of date — Topology
` (say `all current` when stale == 0 and unknown == 0; append `, N unknown` when unknown > 0). + - `DeployArtifacts` / `DeployArtifactsToAllSites`: on success call `LoadUpdatesAsync(force:true)`. +- Modify: `tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests/Admin/SitesPageTests.cs` — register `Substitute.For()` (and `ArtifactRevisionHashService` in the `ArtifactDeploymentService` ctor if Task 2 added it); new tests: badge text per state; instance line; Re-check calls `GetAsync(true)`; cache fault → "unavailable" and the site list still renders. + +**Steps:** failing tests → implement → `dotnet test tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests --filter "FullyQualifiedName~SitesPage"` → commit `feat(central-ui): Sites page shows whether a site's deployed artifacts are current`. + +--- + +### Task 8: Scrollable rail nav + +**Classification:** small · **Estimated implement time:** ~3 min · **Parallelizable with:** Task 1, 2, 3 (must land BEFORE Task 6 — both append to site.css) + +**Files:** +- Modify: `src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Layout/NavMenu.razor` — wrap everything (the Dashboard item and the ``) in `
…
`; extend the header comment (scroll pane rationale, kit untouched). +- Modify: `src/ZB.MOM.WW.ScadaBridge.CentralUI/wwwroot/css/site.css` — append: + ```css + /* ── Rail nav scroll pane ──────────────────────────────────────────────── + ThemeShell's nav.side-rail is a flex column inside the sticky 100vh + #theme-rail (lg+), but it never fills that height and nothing inside it + scrolls, so a long nav grows past the viewport and carries the footer + with it. Fill the rail and let the nav items scroll while the brand bar + and .rail-foot stay put. Below lg the rail is inline and scrolls with the + page, so the rule is scoped to lg+. The kit is untouched (deferred-work + register: upstream into ZB.MOM.WW.Theme). */ + @media (min-width: 992px) { + #theme-rail > .side-rail { height: 100%; } + .rail-scroll { flex: 1 1 auto; min-height: 0; overflow-y: auto; overscroll-behavior: contain; } + } + ``` +- Modify: `tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests/Layout/NavMenuTests.cs` — one test: markup contains `class="rail-scroll"` and the `rail-section` details sit inside it. + +**Steps:** test → change → `dotnet test tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests --filter "FullyQualifiedName~NavMenuTests"` → commit `fix(central-ui): rail nav scrolls in its own pane so the footer stays pinned`. + +--- + +### Task 9: Documentation + +**Classification:** small · **Estimated implement time:** ~4 min · **Parallelizable with:** Task 10 + +**Files:** +- `docs/requirements/Component-CentralUI.md`: *Site & Data Connection Management* — artifact badge, instance line, Re-check; *System-Wide Artifact Deployment* — "Track per-site deployment status" now includes the revision stamp + Current/Out of date/Never deployed; new bullet under *Technology* (or near the nav description) for the rail **Pending updates** indicator (roles, 30 s poll over the 60 s cache, scope filter) and the rail scroll pane. +- `docs/requirements/Component-DeploymentManager.md`: *Deployable Artifacts* — `ArtifactRevisionHashService`, stamping rule (success only), `ComputeCurrentArtifactHashesAsync`, `GetInstanceStalenessAsync` (shared session, mismatch-only normalisation), `PendingUpdatesEvaluator`, `PendingUpdatesCacheTtl` option, not transported. +- `docs/requirements/Component-ConfigurationDatabase.md`: migration list entry `AddSiteArtifactRevision` (mirror how `AddAlarmMesReportable` is listed). +- `CLAUDE.md` (repo root): one bullet under *Templates & Deployment* after the bulk-deploy bullet: the site artifact revision + pending-updates indicator (short; link the design doc). +- `docs/plans/2026-07-08-deferred-work-register.md`: rows 123 (upstream the rail scroll pane into `ZB.MOM.WW.Theme`), 124 (watermark short-circuit so an unchanged fleet costs no re-flatten), 125 (expose the pending-updates counts on the Health dashboard / CLI). +- `src/ZB.MOM.WW.ScadaBridge.CLI/README.md`: note that `site list --detail` now shows `artifactRevisionHash` / `artifactsDeployedAt` (only if the projection shows them; otherwise skip). + +Commit `docs: site artifact revision, pending-updates indicator, rail scroll pane`. + +--- + +### Task 10: Rig — rebuild, verify script, Playwright smoke + +**Classification:** standard · **Estimated implement time:** ~5 min (+ rig build time) · **Parallelizable with:** Task 9 + +**Files:** +- Create: `docker/verify-pending-updates.sh` — uses the rig CLI (see `.claude/skills/scadabridge-cluster-ops/SKILL.md` and `docker/verify-mes-alarm-demo.sh` for the conventions: management URL, `scadabridge` CLI invocation, PASS/FAIL counters). Steps: (A) `site list` → every site has `artifactRevisionHash` (null allowed on a fresh DB); (B) deploy artifacts to all sites via CLI (`artifact deploy` — find the command in the CLI README) → every site's hash non-null and `artifactsDeployedAt` recent; (C) create/update a throwaway shared script (`shared-script …`) → GET the Central UI `/admin/sites` is auth-gated, so instead verify via CLI: `site list` hashes unchanged **and** a fresh artifact deploy changes the hash (proves the hash tracks content); (D) delete the throwaway script, redeploy → hash returns to the value from (B). Print PASS/FAIL summary, exit non-zero on FAIL. +- Create: `tests/ZB.MOM.WW.ScadaBridge.CentralUI.PlaywrightTests/PendingUpdatesTests.cs` — copy the fixture-login pattern from `FlowDebuggerTests`: after login the rail contains either "Up to date" or "Pending updates"; `/admin/sites` renders an `aria-label^="Artifacts:"` badge per card and a Re-check button. +- Run: `bash docker/deploy.sh` (from the worktree — check the script builds from its own checkout), wait for `/health/ready`, `bash docker/verify-pending-updates.sh`, then the Playwright test (`dotnet test tests/ZB.MOM.WW.ScadaBridge.CentralUI.PlaywrightTests --filter "FullyQualifiedName~PendingUpdates"`). Also load `/admin/sites` and the rail once through the browser tools and confirm the indicator sits above the user name and the nav scrolls at a short viewport (record what was seen in the commit message). + +Commit `test(rig): verify-pending-updates.sh + Playwright smoke for the indicator and Sites badge`. + +--- + +### Task 11: Finish — sweep, review, merge, memory + +**Classification:** standard · **Estimated implement time:** ~5 min (+ test time) · **Parallelizable with:** none + +1. `dotnet build ZB.MOM.WW.ScadaBridge.slnx` → 0 warnings/0 errors; `dotnet test ZB.MOM.WW.ScadaBridge.slnx` (skip Playwright unless the rig is up) → all green; note any pre-existing flake by name. +2. Final code review of `git diff main..HEAD` (subagent). +3. Fast-forward merge into `main` in the primary checkout (`git -C /Users/dohertj2/Desktop/ScadaBridge merge --ff-only feat/pending-updates`), remove the worktree, delete the branch. +4. Update the plan's `.tasks.json`, memory (`pending-updates-state.md` + `MEMORY.md` index), and the ScadaBridge row of `../scadaproj/CLAUDE.md` (tip changed; NOT pushed unless asked). diff --git a/docs/plans/2026-09-14-pending-updates.md.tasks.json b/docs/plans/2026-09-14-pending-updates.md.tasks.json new file mode 100644 index 00000000..a5372924 --- /dev/null +++ b/docs/plans/2026-09-14-pending-updates.md.tasks.json @@ -0,0 +1,104 @@ +{ + "planPath": "docs/plans/2026-09-14-pending-updates.md", + "tasks": [ + { + "id": 0, + "subject": "Task 0: Worktree", + "status": "pending" + }, + { + "id": 1, + "subject": "Task 1: Site artifact revision columns, migration, repository projection, Transport guard", + "status": "pending", + "blockedBy": [ + 0 + ] + }, + { + "id": 2, + "subject": "Task 2: ArtifactRevisionHashService + stamping on successful deploy", + "status": "pending", + "blockedBy": [ + 1 + ] + }, + { + "id": 3, + "subject": "Task 3: DeploymentService.GetInstanceStalenessAsync", + "status": "pending", + "blockedBy": [ + 1 + ] + }, + { + "id": 4, + "subject": "Task 4: PendingUpdatesEvaluator + snapshot types + options", + "status": "pending", + "blockedBy": [ + 2, + 3 + ] + }, + { + "id": 5, + "subject": "Task 5: PendingUpdatesCache (CentralUI singleton)", + "status": "pending", + "blockedBy": [ + 4 + ] + }, + { + "id": 6, + "subject": "Task 6: Rail indicator component", + "status": "pending", + "blockedBy": [ + 5, + 8 + ] + }, + { + "id": 7, + "subject": "Task 7: Sites page artifact badges, instance line, re-check", + "status": "pending", + "blockedBy": [ + 5 + ] + }, + { + "id": 8, + "subject": "Task 8: Scrollable rail nav", + "status": "pending", + "blockedBy": [ + 0 + ] + }, + { + "id": 9, + "subject": "Task 9: Documentation", + "status": "pending", + "blockedBy": [ + 6, + 7 + ] + }, + { + "id": 10, + "subject": "Task 10: Rig \u2014 rebuild, verify script, Playwright smoke", + "status": "pending", + "blockedBy": [ + 6, + 7 + ] + }, + { + "id": 11, + "subject": "Task 11: Finish \u2014 sweep, review, merge, memory", + "status": "pending", + "blockedBy": [ + 9, + 10 + ] + } + ], + "lastUpdated": "2026-09-14T17:28:49Z" +} \ No newline at end of file