App update available notice on first run of the day - no upgrade command (#503)

Once a day, on first command run, the CLI will check if a newer version
of the CLI is available and show a notification at the top of the
command output if so.

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Nikola Metulev <nmetulev@users.noreply.github.com>

Author: 4 people

docs/usage.md

@@ -937,6 +937,30 @@ $env:WINAPP_CLI_CACHE_DIRECTORY=d:\temp\.winapp
 ```
 
 Winapp will create this directory automatically when you run commands like `init` or `restore`.
+
+### Update Checks
+
+The winapp CLI periodically checks for new versions and displays a one-line notice when an update is available. This check runs in the background and adds no latency to commands.
+
+Update checks are automatically disabled in CI environments (GitHub Actions, Azure Pipelines, etc.).
+
+To manually disable update checks, set the `WINAPP_CLI_UPDATE_CHECK` environment variable to `0`.
+
+In **cmd**:
+```cmd
+set WINAPP_CLI_UPDATE_CHECK=0
+```
+
+In **PowerShell** and **pwsh**:
+```pwsh
+$env:WINAPP_CLI_UPDATE_CHECK = "0"
+```
+
+To make this permanent:
+```powershell
+[System.Environment]::SetEnvironmentVariable('WINAPP_CLI_UPDATE_CHECK', '0', 'User')
+```
+
 ### ui
 
 Inspect and interact with running Windows app UIs using UI Automation (UIA).

src/winapp-CLI/WinApp.Cli.Tests/UpdateNotificationGatingTests.cs

@@ -0,0 +1,156 @@
+// Copyright (c) Microsoft Corporation and Contributors. All rights reserved.
+// Licensed under the MIT License.
+
+using System.Globalization;
+
+namespace WinApp.Cli.Tests;
+
+/// <summary>
+/// Integration tests verifying that the Program-level gating logic correctly
+/// suppresses update notifications for --json, --quiet, and --cli-schema modes,
+/// and that --caller plumbs through to the notification hint text.
+/// Tests that exercise suppression invoke Program.Main directly.
+/// Tests that verify notification content use the service layer with env vars
+/// matching what Program.Main would set.
+/// </summary>
+[TestClass]
+[DoNotParallelize] // Modifies static Console streams and environment variables
+public class UpdateNotificationGatingTests
+{
+    private string _tempCacheDir = null!;
+    private string? _savedCacheDir;
+    private string? _savedCaller;
+    private string? _savedUpdateCheck;
+
+    [TestInitialize]
+    public void Setup()
+    {
+        // Create temp cache directory and seed with a "newer" version
+        _tempCacheDir = Path.Combine(Path.GetTempPath(), $"winapp_gating_test_{Guid.NewGuid():N}");
+        Directory.CreateDirectory(_tempCacheDir);
+        SeedUpdateCheckCache("99.0.0");
+
+        // Create first-run marker so FirstRunService doesn't trigger logging
+        File.Create(Path.Combine(_tempCacheDir, ".first-run-complete")).Dispose();
+
+        // Save and override env vars
+        _savedCacheDir = Environment.GetEnvironmentVariable("WINAPP_CLI_CACHE_DIRECTORY");
+        _savedCaller = Environment.GetEnvironmentVariable("WINAPP_CLI_CALLER");
+        _savedUpdateCheck = Environment.GetEnvironmentVariable("WINAPP_CLI_UPDATE_CHECK");
+
+        Environment.SetEnvironmentVariable("WINAPP_CLI_CACHE_DIRECTORY", _tempCacheDir);
+        Environment.SetEnvironmentVariable("WINAPP_CLI_CALLER", null);
+        Environment.SetEnvironmentVariable("WINAPP_CLI_UPDATE_CHECK", null);
+
+        // Clear CI vars to avoid suppression
+        Environment.SetEnvironmentVariable("CI", null);
+        Environment.SetEnvironmentVariable("GITHUB_ACTIONS", null);
+        Environment.SetEnvironmentVariable("TF_BUILD", null);
+    }
+
+    [TestCleanup]
+    public void Cleanup()
+    {
+        Environment.SetEnvironmentVariable("WINAPP_CLI_CACHE_DIRECTORY", _savedCacheDir);
+        Environment.SetEnvironmentVariable("WINAPP_CLI_CALLER", _savedCaller);
+        Environment.SetEnvironmentVariable("WINAPP_CLI_UPDATE_CHECK", _savedUpdateCheck);
+
+        try { Directory.Delete(_tempCacheDir, recursive: true); } catch { /* best effort */ }
+    }
+
+    [TestMethod]
+    public async Task JsonMode_SuppressesUpdateNotice_StdoutHasNoNotice()
+    {
+        var (stdout, stderr, _) = await InvokeProgramAsync(["get-winapp-path", "--global", "--json"]);
+
+        Assert.IsFalse(stdout.Contains("available", StringComparison.OrdinalIgnoreCase),
+            $"--json stdout must not contain update notice. Got stdout: {stdout}");
+        Assert.IsFalse(stderr.Contains("available", StringComparison.OrdinalIgnoreCase),
+            $"--json stderr must not contain update notice. Got stderr: {stderr}");
+    }
+
+    [TestMethod]
+    public async Task QuietMode_SuppressesUpdateNotice()
+    {
+        var (stdout, stderr, _) = await InvokeProgramAsync(["get-winapp-path", "--global", "--quiet"]);
+
+        Assert.IsFalse(stdout.Contains("available", StringComparison.OrdinalIgnoreCase),
+            $"--quiet stdout must not contain update notice. Got stdout: {stdout}");
+        Assert.IsFalse(stderr.Contains("available", StringComparison.OrdinalIgnoreCase),
+            $"--quiet stderr must not contain update notice. Got stderr: {stderr}");
+    }
+
+    [TestMethod]
+    public async Task CliSchemaMode_SuppressesUpdateNotice()
+    {
+        var (stdout, stderr, _) = await InvokeProgramAsync(["--cli-schema"]);
+
+        Assert.IsFalse(stdout.Contains("available", StringComparison.OrdinalIgnoreCase),
+            $"--cli-schema stdout must not contain update notice. Got stdout: {stdout}");
+        Assert.IsFalse(stderr.Contains("available", StringComparison.OrdinalIgnoreCase),
+            $"--cli-schema stderr must not contain update notice. Got stderr: {stderr}");
+    }
+
+    [TestMethod]
+    public async Task NormalMode_ShowsUpdateNotice_OnStderr()
+    {
+        // Invoke through the real entrypoint — the notification should appear on stderr,
+        // never stdout. We capture stderr via Console.SetError.
+        var (stdout, stderr, _) = await InvokeProgramAsync(["get-winapp-path", "--global"]);
+
+        Assert.IsFalse(stdout.Contains("available", StringComparison.OrdinalIgnoreCase),
+            $"Update notice must not appear on stdout. Got stdout: {stdout}");
+        Assert.IsTrue(stderr.Contains("available", StringComparison.OrdinalIgnoreCase),
+            $"Update notice should appear on stderr in normal mode. Got stderr: {stderr}");
+    }
+
+    [TestMethod]
+    public async Task CallerNpm_ProducesNpmHint()
+    {
+        // --caller npm should set WINAPP_CLI_CALLER=npm which makes the update notice
+        // include the npm update hint.
+        var (_, stderr, _) = await InvokeProgramAsync(["get-winapp-path", "--global", "--caller", "npm"]);
+
+        Assert.IsTrue(stderr.Contains("npm update", StringComparison.OrdinalIgnoreCase),
+            $"With --caller npm, notice should contain npm update hint. Got stderr: {stderr}");
+    }
+
+    /// <summary>
+    /// Seeds the .update-check file with a timestamp (now) and a specified "latest" version
+    /// so the notification fires immediately without needing network access.
+    /// </summary>
+    private void SeedUpdateCheckCache(string version)
+    {
+        var content = $"{DateTimeOffset.UtcNow.ToString("O", CultureInfo.InvariantCulture)}\n{version}\n";
+        File.WriteAllText(Path.Combine(_tempCacheDir, ".update-check"), content);
+    }
+
+    /// <summary>
+    /// Invokes Program.Main with captured stdout/stderr.
+    /// Writers are intentionally not disposed to avoid ObjectDisposedException from
+    /// Spectre.Console's static AnsiConsole.Console which may reference them after return.
+    /// </summary>
+    private static async Task<(string Stdout, string Stderr, int ExitCode)> InvokeProgramAsync(string[] args)
+    {
+        var originalOut = Console.Out;
+        var originalErr = Console.Error;
+
+        var stdoutWriter = new StringWriter();
+        var stderrWriter = new StringWriter();
+
+        try
+        {
+            Console.SetOut(stdoutWriter);
+            Console.SetError(stderrWriter);
+
+            var exitCode = await Program.Main(args);
+
+            return (stdoutWriter.ToString(), stderrWriter.ToString(), exitCode);
+        }
+        finally
+        {
+            Console.SetOut(originalOut);
+            Console.SetError(originalErr);
+        }
+    }
+}