Add ToolCacheIndexStore.EvictAsync

Removes a single package's pinned state from _index.json so the next
resolve falls through to a fresh NuGet metadata query, ignoring the
CachedWithRefresh TTL for that package only. The rest of the cache is
preserved.

Motivated by host UIs that want to expose a manual 'update to latest'
button — clearing one pin lets users bypass the 24h cache wait without
flushing the entire index. Before this, callers had to reach for
UpdateAsync(mutator) and reproduce internal schema details: lower-case
the key themselves, build an OrdinalIgnoreCase Dictionary, construct
ToolPackageState, set SchemaVersion. EvictAsync owns all of that.

Semantics:
- Case-insensitive on packageId (the index normalizes to lower-case;
  forcing callers to do the same was a trap every consumer hit).
- Idempotent: missing entry returns false without throwing, so the
  manual-update UX can call this unconditionally before reconnecting.
- Atomic write inherited from UpdateAsync — partial reads can't observe
  a half-evicted state.

Three new unit tests cover the happy path, case-insensitivity, and the
missing-entry no-op. Existing five tests untouched; full suite still
green on both net8.0 and net10.0 (8/8).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: diluculo

src/FieldCure.ToolHost/ToolCacheIndexStore.cs

@@ -124,6 +124,45 @@ public async Task<ToolCacheIndex> UpdateAsync(Func<ToolCacheIndex, ToolCacheInde
         return next;
     }
 
+    /// <summary>
+    /// Removes a single package's cached state from the index so the next resolve for that
+    /// package falls through to a fresh NuGet metadata query regardless of TTL. Idempotent:
+    /// a missing entry is a no-op. The lookup is case-insensitive — callers don't have to
+    /// know the index normalizes ids to lowercase.
+    /// </summary>
+    /// <remarks>
+    /// Intended for host UIs that surface a manual "Update to latest" action: clearing one
+    /// pin without flushing the entire index lets users bypass the
+    /// <see cref="ToolVersionPolicy.CachedWithRefresh"/> wait without affecting unrelated
+    /// packages or losing the rest of the cache.
+    /// </remarks>
+    /// <param name="packageId">NuGet package id (case-insensitive).</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns><see langword="true"/> if an entry was removed; <see langword="false"/> if no entry existed.</returns>
+    public async Task<bool> EvictAsync(string packageId, CancellationToken ct = default)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(packageId);
+
+        var key = packageId.ToLowerInvariant();
+        var removed = false;
+
+        _ = await UpdateAsync(current =>
+        {
+            if (!current.Packages.ContainsKey(key))
+                return current;
+
+            var next = new Dictionary<string, ToolPackageState>(current.Packages, StringComparer.OrdinalIgnoreCase);
+            removed = next.Remove(key);
+            return new ToolCacheIndex
+            {
+                SchemaVersion = ToolCacheIndex.CurrentSchemaVersion,
+                Packages = next,
+            };
+        }, ct).ConfigureAwait(false);
+
+        return removed;
+    }
+
     /// <summary>Releases the synchronization primitive backing concurrent access.</summary>
     public void Dispose() => _gate.Dispose();
 }

tests/FieldCure.ToolHost.Tests/ToolCacheIndexStoreTests.cs

@@ -118,4 +118,64 @@ public async Task UpdateAsync_AppliesMutatorAndPersists()
         var reloaded = await store.LoadAsync();
         _ = reloaded.Packages.Should().ContainKey("new.pkg");
     }
+
+    [Xunit.Fact]
+    public async Task EvictAsync_RemovesEntryAndReturnsTrue()
+    {
+        using ToolCacheIndexStore store = new(_indexPath);
+        await SavePackageAsync(store, "Demo.Tool", "1.1.0");
+
+        var removed = await store.EvictAsync("Demo.Tool");
+
+        _ = removed.Should().BeTrue();
+        var reloaded = await store.LoadAsync();
+        _ = reloaded.Packages.Should().NotContainKey("demo.tool");
+    }
+
+    [Xunit.Fact]
+    public async Task EvictAsync_IsCaseInsensitive()
+    {
+        // Persisted keys are lower-cased; the caller shouldn't have to know that. Mixed-case
+        // input must still hit the entry — otherwise the manual "Update to latest" UX breaks
+        // for anyone who happens to type the package id with its display casing.
+        using ToolCacheIndexStore store = new(_indexPath);
+        await SavePackageAsync(store, "Demo.Tool", "1.1.0");
+
+        var removed = await store.EvictAsync("DEMO.TOOL");
+
+        _ = removed.Should().BeTrue();
+        var reloaded = await store.LoadAsync();
+        _ = reloaded.Packages.Should().BeEmpty();
+    }
+
+    [Xunit.Fact]
+    public async Task EvictAsync_MissingEntry_ReturnsFalseAndPreservesOthers()
+    {
+        using ToolCacheIndexStore store = new(_indexPath);
+        await SavePackageAsync(store, "keep.me", "2.0.0");
+
+        var removed = await store.EvictAsync("not.cached");
+
+        _ = removed.Should().BeFalse();
+        var reloaded = await store.LoadAsync();
+        _ = reloaded.Packages.Should().ContainKey("keep.me");
+    }
+
+    /// <summary>Persists a single package entry into the index for test setup.</summary>
+    private static Task SavePackageAsync(ToolCacheIndexStore store, string packageId, string version)
+    {
+        return store.SaveAsync(new ToolCacheIndex
+        {
+            SchemaVersion = ToolCacheIndex.CurrentSchemaVersion,
+            Packages = new Dictionary<string, ToolPackageState>(StringComparer.OrdinalIgnoreCase)
+            {
+                [packageId.ToLowerInvariant()] = new()
+                {
+                    KnownCachedVersions = new[] { version },
+                    PinnedVersion = version,
+                    LastLatestCheckUtc = DateTimeOffset.UtcNow,
+                },
+            },
+        });
+    }
 }