Add IgnoreStopIfOnceExists setting for write-only deployments (#879)

* Initial plan

* Add IgnoreStopIfOnceExists setting to support write-only deployments

Co-authored-by: KevinJump <[email protected]>

* Refactor: improve readability of import decision logic

Co-authored-by: KevinJump <[email protected]>

* Add XML documentation for method parameters

Co-authored-by: KevinJump <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: KevinJump <[email protected]>

Author: Copilot

uSync.BackOffice.Targets/appsettings-schema.usync.json

@@ -84,6 +84,11 @@
           "description": "location of the once file (relative to the uSync folder)\n            ",
           "default": "usync.once"
         },
+        "IgnoreStopIfOnceExists": {
+          "type": "boolean",
+          "description": "When enabled, the presence of a once file will override the stop file, allowing import to proceed\n            ",
+          "default": false
+        },
         "LockRootTypes": {
           "type": "array",
           "description": "lock specific types at root so they can't be changed in child sites. \n            ",

uSync.BackOffice/Configuration/uSyncSettings.cs

@@ -50,6 +50,12 @@ public class uSyncSettings
     [DefaultValue("usync.once")]
     public string OnceFile { get; set; } = "usync.once";
 
+    /// <summary>
+    ///  When enabled, the presence of a once file will override the stop file, allowing import to proceed
+    /// </summary>
+    [DefaultValue(false)]
+    public bool IgnoreStopIfOnceExists { get; set; } = false;
+
     /// <summary>
     ///  lock specific types at root so they can't be changed in child sites. 
     /// </summary>

uSync.BackOffice/Notifications/uSyncApplicationStartingHandler.cs

@@ -129,14 +129,18 @@ private async Task InituSyncAsync()
                 {
                     _logger.LogInformation("uSync: Running Import at startup {group}", _uSyncConfig.Settings.ImportAtStartup);
 
-                    if (!HasStopFile(_uSyncConfig.GetWorkingFolder()))
+                    var workingFolder = _uSyncConfig.GetWorkingFolder();
+                    var hasStopFile = HasStopFile(workingFolder);
+                    var hasOnceFile = HasOnceFile(workingFolder);
+
+                    if (ShouldProceedWithImport(hasStopFile, hasOnceFile))
                     {
                         await _uSyncService.StartupImportAsync(_uSyncConfig.GetFolders(), false, new SyncHandlerOptions
                         {
                             Group = _uSyncConfig.Settings.ImportAtStartup
                         });
 
-                        await ProcessOnceFileAsync(_uSyncConfig.GetWorkingFolder());
+                        await ProcessOnceFileAsync(workingFolder);
                     }
                     else
                     {
@@ -178,6 +182,30 @@ private bool HasSyncFolders()
     private bool HasStopFile(string folder)
             => _syncFileService.FileExists($"{folder}/{_uSyncConfig.Settings.StopFile}");
 
+    /// <summary>
+    ///  Does the uSync folder contain a uSync.once file?
+    /// </summary>
+    private bool HasOnceFile(string folder)
+            => _syncFileService.FileExists($"{folder}/{_uSyncConfig.Settings.OnceFile}");
+
+    /// <summary>
+    ///  Determines if the import should proceed based on the presence of stop and once files.
+    /// </summary>
+    /// <param name="hasStopFile">Whether a stop file exists in the working folder</param>
+    /// <param name="hasOnceFile">Whether a once file exists in the working folder</param>
+    /// <returns>True if import should proceed, false otherwise</returns>
+    private bool ShouldProceedWithImport(bool hasStopFile, bool hasOnceFile)
+    {
+        // If there's no stop file, proceed with import
+        if (!hasStopFile) return true;
+
+        // If stop file exists and IgnoreStopIfOnceExists is enabled, check for once file
+        if (_uSyncConfig.Settings.IgnoreStopIfOnceExists && hasOnceFile) return true;
+
+        // Otherwise, stop file blocks the import
+        return false;
+    }
+
     /// <summary>
     ///  Process the once file (if it exists we rename it to usync.stop).
     /// </summary>