Merge pull request stride3d#3244 from xen2/feature/upgrade-backup

Backup modified files before upgrade

Author: xen2

sources/assets/Stride.AssetCompiler/PackageBuilderApp.cs

@@ -117,6 +117,7 @@ public int Run(string[] args)
                 { "pack-asset-assembly=", "Host-loadable asset assembly (package-relative path) to declare in the packed sdpkg; repeat for each", v => options.PackAssetAssemblies.Add(v) },
                 { "t|threads=", "Number of threads to create. Default value is the number of hardware threads available.", v => options.ThreadCount = int.Parse(v) },
                 { "test=", "Run a test session.", v => options.TestName = v },
+                { "no-backup", "Upgrade verb only: skip backing up the files the upgrade overwrites (backup is on by default).", v => options.NoBackup = v != null },
                 { "property:", "Properties. Format is name1=value1;name2=value2", v =>
                 {
                     if (!string.IsNullOrEmpty(v))
@@ -347,13 +348,22 @@ public int Run(string[] args)
                         PackageUpgradeRequested = (pkg, upgrades) => PackageUpgradeRequestedAnswer.UpgradeAll,
                         // Whole-solution upgrade may start mixed (e.g. a shared pack already bumped); tolerate the transient NU1605.
                         AllowUpgradeDowngradeRestore = true,
+                        // Snapshot every file the upgrade overwrites into a timestamped backup folder unless opted out.
+                        BackupBeforeUpgrade = !options.NoBackup,
                     };
 
                     var sessionResult = PackageSession.Load(upgradeTarget, loadParameters);
                     sessionResult.CopyTo(options.Logger);
-                    if (sessionResult.HasErrors || sessionResult.Session == null)
+                    if (sessionResult.Session == null)
                         return (int)BuildResultCode.BuildError;
 
+                    // Be lenient like Game Studio: load errors (e.g. a project that won't build against the new
+                    // version, so its script-referencing assets load as IUnloadable) don't abort the upgrade.
+                    // Reconcile and save whatever loaded — IUnloadable round-trips its original YAML, so nothing
+                    // is lost — and let the exit code below still report the errors.
+                    if (sessionResult.HasErrors)
+                        options.Logger.Warning("The session loaded with errors; upgrading and saving the assets that loaded. Fix the errors and re-run for a complete upgrade.");
+
                     ReconcileBases(sessionResult.Session, options.Logger);
 
                     sessionResult.Session.Save(options.Logger);

sources/assets/Stride.AssetCompiler/PackageBuilderOptions.cs

@@ -15,6 +15,8 @@ public class PackageBuilderOptions
 
         public bool Verbose = false;
         public bool Debug = false;
+        // Upgrade verb only: skip the copy-on-write backup of files the in-place upgrade overwrites (on by default).
+        public bool NoBackup { get; set; }
         // This should not be a list
         public bool DisableAutoCompileProjects { get; set; }
         public string ProjectConfiguration { get; set; }

sources/assets/Stride.Core.Assets/CodeUpgrade/CodeUpgradeRunner.cs

@@ -26,8 +26,9 @@ public interface ICodeUpgradeRunner
 {
     /// <param name="solutionPath">The solution to open (already restored at the old versions), or <c>null</c> for a standalone project.</param>
     /// <param name="pending">The projects pending source migration, with the upgrader that declared rules and the version each is upgraded from.</param>
+    /// <param name="backup">The copy-on-write backup to snapshot each source file into before overwriting it, or <c>null</c> when no backup is requested.</param>
     /// <param name="log">The logger.</param>
-    void Run(UFile? solutionPath, IReadOnlyList<PendingCodeUpgrade> pending, ILogger log);
+    void Run(UFile? solutionPath, IReadOnlyList<PendingCodeUpgrade> pending, UpgradeBackup? backup, ILogger log);
 }
 
 /// <summary>

sources/assets/Stride.Core.Assets/PackageLoadParameters.cs

@@ -135,6 +135,13 @@ public PackageLoadParameters()
     /// </summary>
     public bool AllowUpgradeDowngradeRestore { get; set; }
 
+    /// <summary>
+    /// When set, an in-place upgrade snapshots each original file into a timestamped backup folder right before
+    /// it overwrites it (copy-on-write — only modified files are copied), so the upgrade stays recoverable.
+    /// Front-ends opt in (the asset compiler and GameStudio default it on); off for normal loads.
+    /// </summary>
+    public bool BackupBeforeUpgrade { get; set; }
+
     /// <summary>
     /// Occurs when an asset is about to be loaded, if false is returned the asset will be ignored and not loaded.
     /// </summary>

sources/assets/Stride.Core.Assets/PackageSession.cs

@@ -494,6 +494,13 @@ public UFile SolutionPath
 
     public AssemblyContainer AssemblyContainer { get; }
 
+    /// <summary>
+    /// The copy-on-write backup armed for an in-place upgrade (see <see cref="PackageLoadParameters.BackupBeforeUpgrade"/>),
+    /// or <c>null</c> when no backup is requested. The upgrade write points call <see cref="UpgradeBackup.Snapshot"/>
+    /// on it before overwriting a file.
+    /// </summary>
+    public UpgradeBackup? UpgradeBackup { get; private set; }
+
     /// <summary>
     /// The targeted visual studio version (if specified by the loaded package)
     /// </summary>
@@ -903,6 +910,26 @@ public void LoadMissingReferences(ILogger log, PackageLoadParameters? loadParame
         LoadMissingAssets(log, [.. Packages], loadParameters);
     }
 
+    // Constructs the copy-on-write upgrade backup the first time an upgrade-enabled load runs, mirroring the
+    // solution directory (or, for a standalone project upgrade with no solution, the project's directory).
+    private void ArmUpgradeBackup(PackageLoadParameters loadParameters, ILogger log)
+    {
+        if (!loadParameters.BackupBeforeUpgrade || UpgradeBackup is not null)
+            return;
+
+        var root = SolutionPath is not null
+            ? Path.GetDirectoryName(SolutionPath.ToOSPath())
+            : Projects.OfType<SolutionProject>().Select(x => Path.GetDirectoryName(x.FullPath.ToOSPath())).FirstOrDefault();
+        if (!string.IsNullOrEmpty(root))
+            UpgradeBackup = new UpgradeBackup(root, DateTime.Now, log);
+    }
+
+    /// <summary>
+    /// Disarms the upgrade backup so subsequent saves no longer snapshot files. <see cref="Save"/> does this
+    /// automatically after persisting an upgrade; a front-end also calls it for a clean load where no save runs.
+    /// </summary>
+    public void DisarmUpgradeBackup() => UpgradeBackup = null;
+
     /// <summary>
     /// Make sure packages have their dependencies loaded.
     /// </summary>
@@ -914,6 +941,10 @@ public void LoadMissingDependencies(ILogger log, PackageLoadParameters? loadPara
 
         var cancelToken = loadParameters.CancelToken;
 
+        // Arm the copy-on-write backup once, before any upgrade write point runs. Copy-on-write keeps this
+        // safe to arm eagerly: the backup folder is only created if an upgrade actually overwrites a file.
+        ArmUpgradeBackup(loadParameters, log);
+
         try
         {
             // Restore the whole solution once up front (one project-graph evaluation) instead of one
@@ -944,7 +975,7 @@ public void LoadMissingDependencies(ILogger log, PackageLoadParameters? loadPara
                 {
                     var pendingCodeUpgrades = DetectPendingCodeUpgrades(log, loadParameters);
                     if (pendingCodeUpgrades.Count > 0)
-                        codeUpgradeRunner.Run(SolutionPath, pendingCodeUpgrades, log);
+                        codeUpgradeRunner.Run(SolutionPath, pendingCodeUpgrades, UpgradeBackup, log);
                 }
                 catch (NotImplementedException)
                 {
@@ -1057,6 +1088,23 @@ public void Save(ILogger log, PackageSaveParameters? saveParameters = null)
                 return;
             }
 
+            // Copy-on-write backup of the files this save is about to overwrite during an upgrade: the dirty
+            // packages and their dirty assets. No-op outside an upgrade (UpgradeBackup is null); copy-once.
+            if (UpgradeBackup is { } upgradeBackup)
+            {
+                foreach (var package in LocalPackages)
+                {
+                    if (package.IsDirty && package.FullPath is not null)
+                        upgradeBackup.Snapshot(package.FullPath.ToOSPath());
+
+                    foreach (var assetItem in package.Assets)
+                    {
+                        if (assetItem.IsDirty)
+                            upgradeBackup.Snapshot(assetItem.FullPath.ToOSPath());
+                    }
+                }
+            }
+
             // Suspend tracking when saving as we don't want to receive
             // all notification events
             dependencies?.BeginSavingSession();
@@ -1148,17 +1196,22 @@ public void Save(ILogger log, PackageSaveParameters? saveParameters = null)
             dependencies?.EndSavingSession();
 
             // Once all packages and assets have been saved, we can save the solution (as we need to have fullpath to
-            // be setup for the packages). Skip when the session wasn't loaded from a .sln (empty FullPath).
+            // be setup for the packages). Skip when the session wasn't loaded from a .sln (empty FullPath). The
+            // callback snapshots the .sln only when Save actually rewrites it.
             if (packagesSaved && !string.IsNullOrEmpty(VSSolution.FullPath))
             {
-                VSSolution.Save();
+                VSSolution.Save(path => UpgradeBackup?.Snapshot(path));
             }
             saveCompletion?.SetResult(0);
             saveCompletion = null;
         }
 
         //System.Diagnostics.Trace.WriteLine("Elapsed saved: " + clock.ElapsedMilliseconds);
         IsDirty = packagesDirty;
+
+        // The backup (armed only during an upgrade) has done its job for this save; disarm so later saves of
+        // this session don't snapshot. Normal saves run with it already null, so this is a no-op.
+        DisarmUpgradeBackup();
     }
 
     private Dictionary<UFile, AssetItem> BuildAssetsOrPackagesToRemove()
@@ -1483,6 +1536,11 @@ private bool TryLoadAssemblies(PackageSession session, ILogger log, Package pack
                         packageUpgradeAllowed = true;
                     if (upgradeAllowed == PackageUpgradeRequestedAnswer.DoNotUpgradeAny)
                         packageUpgradeAllowed = false;
+
+                    // The confirmation callback may have opted out of the backup (e.g. the GameStudio dialog's
+                    // checkbox); disarm so the upgrade writes that follow this point don't snapshot.
+                    if (!loadParameters.BackupBeforeUpgrade)
+                        DisarmUpgradeBackup();
                 }
 
                 if (!PackageLoadParameters.ShouldUpgrade(upgradeAllowed))

sources/assets/Stride.Core.Assets/UpgradeBackup.cs

@@ -0,0 +1,92 @@
+// Copyright (c) .NET Foundation and Contributors (https://dotnetfoundation.org/ & https://stride3d.net)
+// Distributed under the MIT license. See the LICENSE.md file in the project root for more information.
+
+using System;
+using System.Collections.Generic;
+using System.IO;
+using Stride.Core.Diagnostics;
+
+namespace Stride.Core.Assets;
+
+/// <summary>
+/// Copy-on-write snapshot of the files an in-place upgrade is about to overwrite. Armed by
+/// <see cref="PackageLoadParameters.BackupBeforeUpgrade"/> and called from each upgrade write point right
+/// before it overwrites a file. The timestamped backup folder is created lazily on the first real snapshot
+/// (so nothing is written when an upgrade modifies no files), and each original is copied at most once
+/// (a file may be touched by several upgraders).
+/// </summary>
+public sealed class UpgradeBackup
+{
+    private readonly string rootDirectory;
+    private readonly string backupFolderName;
+    private readonly ILogger? log;
+    private readonly object lockObject = new();
+    private readonly HashSet<string> snapshotted = new(StringComparer.OrdinalIgnoreCase);
+    private string? backupDirectory;
+
+    /// <param name="rootDirectory">
+    /// The folder the backup mirrors — each file is stored under it preserving its path relative to this
+    /// root. Usually the solution directory (the project directory for a standalone upgrade).
+    /// </param>
+    /// <param name="timestamp">The upgrade start time, used to name the backup folder.</param>
+    /// <param name="log">Logger that receives a single notice when the backup folder is first created.</param>
+    public UpgradeBackup(string rootDirectory, DateTime timestamp, ILogger? log = null)
+    {
+        this.rootDirectory = Path.GetFullPath(rootDirectory);
+        backupFolderName = $".stride-backup-{timestamp:yyyyMMdd-HHmmss}";
+        this.log = log;
+    }
+
+    /// <summary>
+    /// Copies <paramref name="originalFullPath"/> into the backup folder (preserving its path relative to the
+    /// backup root) the first time it is seen. No-op if the file doesn't exist, lies outside the root, or sits
+    /// under <c>bin/</c>, <c>obj/</c>, or the backup folder. Safe to call repeatedly for the same file.
+    /// </summary>
+    public void Snapshot(string originalFullPath)
+    {
+        if (string.IsNullOrEmpty(originalFullPath))
+            return;
+
+        var fullPath = Path.GetFullPath(originalFullPath);
+
+        var relative = Path.GetRelativePath(rootDirectory, fullPath);
+        // Outside the root (relative escapes with "..") or excluded build/backup output: skip.
+        if (relative.StartsWith("..", StringComparison.Ordinal) || Path.IsPathRooted(relative))
+            return;
+        if (relative.StartsWith(".stride-backup", StringComparison.Ordinal)
+            || ContainsSegment(relative, "bin")
+            || ContainsSegment(relative, "obj"))
+            return;
+
+        lock (lockObject)
+        {
+            if (!snapshotted.Add(fullPath))
+                return;
+
+            if (!File.Exists(fullPath))
+                return;
+
+            if (backupDirectory is null)
+            {
+                // First file actually backed up: announce the folder once. Covers every upgrade write point
+                // (source, project, assets) and entry point (compiler, Game Studio) since all funnel here.
+                backupDirectory = Path.Combine(rootDirectory, backupFolderName);
+                if (log is not null)
+                    log.Info($"Upgrade: backing up the originals of modified files to [{backupDirectory}]. Review the changes before building.");
+            }
+            var target = Path.Combine(backupDirectory, relative);
+            Directory.CreateDirectory(Path.GetDirectoryName(target)!);
+            File.Copy(fullPath, target, overwrite: true);
+        }
+    }
+
+    private static bool ContainsSegment(string relativePath, string segment)
+    {
+        foreach (var part in relativePath.Split(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar))
+        {
+            if (string.Equals(part, segment, StringComparison.OrdinalIgnoreCase))
+                return true;
+        }
+        return false;
+    }
+}

sources/core/Stride.Core.Design/Solutions/Solution.cs

@@ -140,18 +140,20 @@ public Solution Clone()
     /// <summary>
     /// Saves this instance to the <see cref="FullPath"/> path.
     /// </summary>
-    public void Save()
+    /// <param name="onBeforeOverwrite">Invoked with the path just before an existing file is overwritten (only when its content changed).</param>
+    public void Save(Action<string>? onBeforeOverwrite = null)
     {
-        SaveAs(FullPath);
+        SaveAs(FullPath, onBeforeOverwrite);
     }
 
     /// <summary>
     /// Saves this instance to the specified path.
     /// </summary>
     /// <param name="solutionPath">The solution path.</param>
-    public void SaveAs(string solutionPath)
+    /// <param name="onBeforeOverwrite">Invoked with the path just before an existing file is overwritten (only when its content changed).</param>
+    public void SaveAs(string solutionPath, Action<string>? onBeforeOverwrite = null)
     {
-        SolutionSerialization.Write(this, solutionPath);
+        SolutionSerialization.Write(this, solutionPath, onBeforeOverwrite);
     }
 
     /// <summary>

sources/core/Stride.Core.Design/Solutions/SolutionSerialization.cs

@@ -52,7 +52,7 @@ public static Solution Read(string solutionFullPath, Stream stream)
         return ToSolution(model, solutionFullPath);
     }
 
-    public static void Write(Solution solution, string outputPath)
+    public static void Write(Solution solution, string outputPath, Action<string>? onBeforeOverwrite = null)
     {
         // Behave like Visual Studio: a solution loaded from disk keeps everything it had (platforms, build
         // configurations, solution folders, projects Stride doesn't manage) and only its project list is
@@ -76,7 +76,10 @@ public static void Write(Solution solution, string outputPath)
         {
             serializer.SaveAsync(tempPath, model, CancellationToken.None).GetAwaiter().GetResult();
             if (!File.ReadAllBytes(outputPath).AsSpan().SequenceEqual(File.ReadAllBytes(tempPath)))
+            {
+                onBeforeOverwrite?.Invoke(outputPath);
                 File.Copy(tempPath, outputPath, overwrite: true);
+            }
         }
         finally
         {