AI-Studio/app/MindWork AI Studio/Tools/Services/AssistantPluginInstallService.cs

using System.Text;
using AIStudio.Settings;
using AIStudio.Tools.AssistantSessions;
using AIStudio.Tools.Media;
using AIStudio.Tools.PluginSystem;
using AIStudio.Tools.PluginSystem.Assistants;
using AIStudio.Tools.Rust;

namespace AIStudio.Tools.Services;

public sealed class AssistantPluginInstallService
{
    private static string TB(string fallbackEN) => I18N.I.T(fallbackEN, typeof(AssistantPluginInstallService).Namespace, nameof(AssistantPluginInstallService));
    
    private const string PLUGIN_FILE_NAME = "plugin.lua";
    private const string ASSISTANT_BUILDER_DIRECTORY_PREFIX = "assistant-builder";
    private const string DELETE_BACKUP_DIRECTORY = ".plugin-delete-backups";
    private const string INSTALL_BACKUP_DIRECTORY = ".plugin-install-backups";
    private const int DIRECTORY_PREFIX_MAX_LEN = 80;
    
    private readonly ILogger<AssistantPluginInstallService> logger;
    private readonly SettingsManager settingsManager;
    private readonly AssistantSessionService assistantSessionService;
    private readonly MediaTranscriptionService mediaTranscriptionService;
    private readonly SemaphoreSlim installSemaphore = new(1, 1);
    
    private static AssistantPluginInstallResult Error(string issue) => new(false, Guid.Empty, string.Empty, string.Empty, false, issue);

    private static AssistantPluginInstallResult CancelledByUser() => new(false, Guid.Empty, string.Empty, string.Empty, false, string.Empty, true);
    
    private static AssistantPluginCheckResult CheckError(string issue) => new(false, Guid.Empty, string.Empty, issue);
    
    private static AssistantPluginDeleteResult DeleteError(IPluginMetadata plugin, string pluginDirectory, string issue) => new(false, plugin.Id, plugin.Name, pluginDirectory, issue);

    private static AssistantPluginUpdateResult UpdateError(IPluginMetadata plugin, string pluginDirectory, string issue) => new(false, plugin.Id, plugin.Name, pluginDirectory, issue);

    public AssistantPluginInstallService(ILogger<AssistantPluginInstallService> logger, SettingsManager settingsManager, AssistantSessionService assistantSessionService, MediaTranscriptionService mediaTranscriptionService)
    {
        this.logger = logger;
        this.settingsManager = settingsManager;
        this.assistantSessionService = assistantSessionService;
        this.mediaTranscriptionService = mediaTranscriptionService;
        this.logger.LogInformation("The assistant plugin install service has been initialized.");
    }

    /// <summary>
    /// Checks whether a local plugin is an Assistant Builder generated assistant that users may delete.
    /// </summary>
    public static bool CanDeleteInstalledAssistant(IAvailablePlugin plugin) => string.IsNullOrWhiteSpace(GetAssistantDeletionEligibilityIssue(plugin));

    /// <summary>
    /// Checks whether an assistant still owns running or canceling background work.
    /// </summary>
    public bool HasActiveAssistantWork(Guid pluginId)
    {
        var instanceId = pluginId.ToString();
        if (this.assistantSessionService.GetSnapshots().Any(snapshot => snapshot.IsActive && string.Equals(snapshot.Key.InstanceId, instanceId, StringComparison.Ordinal)))
            return true;

        var ownerIdSuffix = $":{instanceId}";
        return this.mediaTranscriptionService.GetSnapshots().Any(snapshot =>
            snapshot is { IsBusy: true, Owner.Kind: MediaImportOwnerKind.ASSISTANT } &&
            snapshot.Owner.Id.EndsWith(ownerIdSuffix, StringComparison.Ordinal));
    }

    /// <summary>
    /// Checks whether generated Lua assistant plugin code can be loaded and installed.
    /// The plugin is written to a temporary staging directory and validated through the
    /// normal plugin loader, but it is not moved into the user plugin directory.
    /// </summary>
    /// <param name="lua">The full generated <c>plugin.lua</c> content.</param>
    /// <param name="token">A cancellation token for file IO and Lua validation.</param>
    /// <returns>
    /// Check result that contains success state, plugin metadata, and a user-facing issue when validation failed.
    /// </returns>
    public async Task<AssistantPluginCheckResult> CheckInstallabilityAsync(string lua, CancellationToken token)
    {
        if (!TryGetAssistantPluginsRoot(out var assistantPluginsRoot, out var rootIssue))
            return CheckError(rootIssue);

        await this.installSemaphore.WaitAsync(token);
        var stagingDirectory = string.Empty;
        try
        {
            var validation = await this.ValidateIntoStagingAsync(lua, token);
            if (!validation.Success || validation.AssistantPlugin is null)
                return CheckError(validation.Issue);

            stagingDirectory = validation.StagingDirectory;
            var finalDirectory = DetermineFinalDirectory(assistantPluginsRoot, validation.AssistantPlugin);
            if (!IsPathInsideDirectory(assistantPluginsRoot, finalDirectory))
                return CheckError(TB("The resolved plugin directory is outside the assistant plugin directory."));

            return new(true, validation.AssistantPlugin.Id, validation.AssistantPlugin.Name, string.Empty);
        }
        finally
        {
            this.TryDeleteStagingDirectory(stagingDirectory);
            this.installSemaphore.Release();
        }
    }

    /// <summary>
    /// Installs generated Lua assistant plugin code into the user plugin directory.
    /// Writes the plugin into a temporary staging directory first, validates it through the
    /// normal plugin loader, then moves into <c>data/plugins/assistants</c>.
    /// If plugin with same ID already exists, the existing directory is moved
    /// aside as backup and restored when replacement fails.
    /// </summary>
    /// <param name="lua">The full generated <c>plugin.lua</c> content.</param>
    /// <param name="token">A cancellation token for file IO, Lua validation, and plugin reload.</param>
    /// <returns>
    /// Installation result that contains success state, installed plugin metadata, final directory,
    /// whether an existing plugin was replaced, and user-facing issue when installation failed.
    /// </returns>
    public async Task<AssistantPluginInstallResult> InstallAsync(string lua, CancellationToken token)
    {
        if (!TryGetAssistantPluginsRoot(out var assistantPluginsRoot, out var rootIssue))
            return Error(rootIssue);

        await this.installSemaphore.WaitAsync(token);
        try
        {
            var validation = await this.ValidateIntoStagingAsync(lua, token);
            if (!validation.Success || validation.AssistantPlugin is null)
                return Error(validation.Issue);

            return await this.InstallStagedAssistantAsync(assistantPluginsRoot, validation, token);
        }
        finally
        {
            this.installSemaphore.Release();
        }
    }

    /// <summary>
    /// Installs an assistant plugin archive that contains exactly one <c>plugin.lua</c> file.
    /// Companion files are validated from and moved with the same staging directory.
    /// </summary>
    /// <param name="archivePath">The local <c>.mwplugin</c> or <c>.zip</c> archive path.</param>
    /// <param name="confirmAsync">
    /// Asks the user whether the validated archive may be installed. It is called after all checks
    /// passed and before anything gets written. Returning false aborts the installation.
    /// </param>
    /// <param name="token">Cancellation token for extraction, validation, file IO, and plugin reload.</param>
    /// <returns>Installation result that contains success state, installed plugin metadata, and a user-facing issue when installation failed.</returns>
    public async Task<AssistantPluginInstallResult> InstallArchiveAsync(string archivePath, Func<PluginImportPreview, Task<bool>> confirmAsync, CancellationToken token)
    {
        if (!this.settingsManager.ConfigurationData.App.AllowUserToImportPlugins)
            return Error(TB("Your organization has disabled importing plugins."));

        if (!FileTypes.IsAllowedPath(archivePath, FileTypes.PLUGIN_ARCHIVE))
            return Error(TB("Please select a plugin archive with the extension .mwplugin or .zip."));

        if (!File.Exists(archivePath))
            return Error(TB("The selected plugin archive does not exist."));

        if (!TryGetAssistantPluginsRoot(out var assistantPluginsRoot, out var rootIssue))
            return Error(rootIssue);

        if (!PluginFactory.IsInitialized)
            return Error(TB("The plugin system is not initialized yet."));

        await this.installSemaphore.WaitAsync(token);
        var stagingDirectory = Path.Join(Path.GetTempPath(), $"assistant-plugin-import.staging-{Guid.NewGuid():N}");
        try
        {
            try
            {
                token.ThrowIfCancellationRequested();
                PluginArchive.Extract(archivePath, stagingDirectory);

                var pluginFiles = Directory.EnumerateFiles(stagingDirectory, PLUGIN_FILE_NAME, SearchOption.AllDirectories).ToArray();
                if (pluginFiles.Length != 1)
                    return Error(TB("The plugin archive must contain exactly one plugin.lua file."));

                var pluginFile = pluginFiles[0];
                var pluginDirectory = Path.GetDirectoryName(pluginFile)!;
                var pluginCode = await File.ReadAllTextAsync(pluginFile, Encoding.UTF8, token);
                var validation = await ValidateAssistantPluginCodeAsync(
                    pluginDirectory,
                    pluginCode.Trim(),
                    TB("Currently, only assistant plugins can be imported."),
                    TB("The imported assistant plugin is invalid. Issue: {0}"),
                    TB("The imported assistant plugin uses the ID of another installed plugin."),
                    token);

                if (!validation.Success || validation.AssistantPlugin is null)
                    return Error(validation.Issue);

                // A plugin the user imports by hand never comes from a config server. We reject such
                // archives because AI Studio trusts this self-declared flag: an imported plugin
                // claiming it would be neither replaceable nor deletable through the user interface:
                if (validation.AssistantPlugin.IsManagedByConfigServer)
                    return Error(TB("This plugin archive declares itself as managed by a config server. Only the IT department of your organization might deploy such plugins."));

                // The archive would replace an existing plugin: reject it when that plugin belongs
                // to the IT department. We check this before asking the user, so that the
                // confirmation never offers something we would refuse afterwards anyway:
                var replacementIssue = GetAssistantReplacementIssue(validation.AssistantPlugin.Id);
                if (!string.IsNullOrEmpty(replacementIssue))
                    return Error(replacementIssue);

                // Everything is validated, but nothing was written yet. This is the point where the
                // user decides, because the plugin code comes from an untrusted source:
                if (!await confirmAsync(CreateImportPreview(validation.AssistantPlugin)))
                    return CancelledByUser();

                return await this.InstallStagedAssistantAsync(assistantPluginsRoot, validation with { StagingDirectory = pluginDirectory }, token);
            }
            catch (Exception e) when (e is not OperationCanceledException)
            {
                this.logger.LogError(e, "Failed to extract or validate assistant plugin archive '{ArchivePath}'.", archivePath);
                return Error(string.Format(TB("Unexpected error: {0}"), e.Message));
            }
        }
        finally
        {
            this.TryDeleteStagingDirectory(stagingDirectory);
            this.installSemaphore.Release();
        }
    }

    /// <summary>
    /// Checks whether edited assistant plugin code can replace an installed local assistant plugin
    /// without writing the file.
    /// </summary>
    /// <param name="plugin">The installed local assistant plugin to validate against.</param>
    /// <param name="lua">The edited <c>plugin.lua</c> content.</param>
    /// <param name="token">Cancellation token for Lua validation.</param>
    /// <returns>Check result that contains success state, plugin metadata, and a user-facing issue when validation failed.</returns>
    public async Task<AssistantPluginCheckResult> CheckInstalledAssistantUpdateAsync(IAvailablePlugin plugin, string lua, CancellationToken token)
    {
        if (plugin.Type is not PluginType.ASSISTANT)
            return CheckError(TB("Only assistant plugins can be edited."));

        if (plugin.IsInternal)
            return CheckError(TB("Internal assistant plugins cannot be edited."));

        if (string.IsNullOrWhiteSpace(plugin.LocalPath))
            return CheckError(TB("The assistant plugin has no local directory."));

        if (!TryGetAssistantPluginsRoot(out var assistantPluginsRoot, out var rootIssue))
            return CheckError(rootIssue);

        var pluginDirectory = plugin.LocalPath;
        if (!IsPathInsideDirectory(assistantPluginsRoot, pluginDirectory) || IsSameDirectory(assistantPluginsRoot, pluginDirectory))
            return CheckError(TB("The assistant plugin directory is outside the local assistant plugin directory."));

        if (!Directory.Exists(pluginDirectory))
            return CheckError(TB("The assistant plugin directory does not exist."));

        await this.installSemaphore.WaitAsync(token);
        try
        {
            var validation = await this.ValidateInPluginDirectoryAsync(lua, pluginDirectory, token);
            if (!validation.Success || validation.AssistantPlugin is null)
                return CheckError(validation.Issue);

            var assistantPlugin = validation.AssistantPlugin;
            return assistantPlugin.Id != plugin.Id
                ? CheckError(TB("The edited assistant plugin must keep the same plugin ID."))
                : new(true, assistantPlugin.Id, assistantPlugin.Name, string.Empty);
        }
        finally
        {
            this.installSemaphore.Release();
        }
    }

    /// <summary>
    /// Deletes installed local assistant plugin directories.
    /// The directory gets moved to a backup dir outside the plugin root so the
    /// plugin loader cannot discover it during reload. On failure, the directory
    /// and related assistant settings are restored.
    /// </summary>
    /// <param name="plugin">Assistant plugin metadata</param>
    /// <param name="token">Cancellation token for settings storage and plugin reload</param>
    /// <returns>
    /// Delete result that contains success state, deleted plugin metadata, the original plugin directory,
    /// and a user-facing issue when deletion failed.
    /// </returns>
    public async Task<AssistantPluginDeleteResult> DeleteInstalledAssistantAsync(IAvailablePlugin plugin, CancellationToken token)
    {
        var eligibilityIssue = GetAssistantDeletionEligibilityIssue(plugin);
        if (!string.IsNullOrEmpty(eligibilityIssue))
            return DeleteError(plugin, plugin.LocalPath, eligibilityIssue);

        if (this.HasActiveAssistantWork(plugin.Id))
            return DeleteError(plugin, plugin.LocalPath, TB("The assistant cannot be deleted while background work is still running."));

        await this.installSemaphore.WaitAsync(token);
        var pluginDirectory = plugin.LocalPath;
        var backupDirectory = string.Empty;
        var wasEnabled = false;
        var removedAudits = new List<PluginAssistantAudit>();

        try
        {
            eligibilityIssue = GetAssistantDeletionEligibilityIssue(plugin);
            if (!string.IsNullOrEmpty(eligibilityIssue))
                return DeleteError(plugin, pluginDirectory, eligibilityIssue);

            if (this.HasActiveAssistantWork(plugin.Id))
                return DeleteError(plugin, pluginDirectory, TB("The assistant cannot be deleted while background work is still running."));

            backupDirectory = CreateDeleteBackupDirectory(plugin);
            Directory.CreateDirectory(Path.GetDirectoryName(backupDirectory)!);
            Directory.Move(pluginDirectory, backupDirectory);

            wasEnabled = this.settingsManager.ConfigurationData.EnabledPlugins.Remove(plugin.Id);
            removedAudits =
            [
                .. this.settingsManager.ConfigurationData.AssistantPluginAudits.Where(audit => audit.PluginId == plugin.Id)
            ];

            if (removedAudits.Count > 0)
                this.settingsManager.ConfigurationData.AssistantPluginAudits.RemoveAll(audit => audit.PluginId == plugin.Id);

            await this.settingsManager.StoreSettings();
            await PluginFactory.LoadAll(token);

            TryDeleteDirectory(backupDirectory, "assistant plugin delete backup", this.logger);
            this.logger.LogInformation($"Deleted assistant plugin '{plugin.Name}' ({plugin.Id}) from '{pluginDirectory}'.");
            return new(true, plugin.Id, plugin.Name, pluginDirectory, string.Empty);
        }
        catch (Exception e)
        {
            this.logger.LogError(e, $"Failed to delete assistant plugin '{plugin.Name}' ({plugin.Id}) from '{pluginDirectory}'.");

            await this.TryRestoreDeletedAssistantPluginAsync(plugin, pluginDirectory, backupDirectory, wasEnabled, removedAudits, token);
            return DeleteError(plugin, pluginDirectory, string.Format(TB("Unexpected error: {0}"), e.Message));
        }
        finally
        {
            this.installSemaphore.Release();
        }
    }

    /// <summary>
    /// Updates installed assistant plugin <c>plugin.lua</c> file.
    /// The edited Lua code is validated from the provided string before it is written,
    /// but validation uses existing plugin directory as loader context so
    /// <c>require(...)</c> can resolve companion files such as <c>icon.lua</c>.
    /// After successful validation, the current <c>plugin.lua</c> is backed up,
    /// replaced atomically through a temporary file in the plugin directory, and
    /// restored when the plugin reload fails.
    /// </summary>
    /// <param name="plugin">The installed local assistant plugin to update.</param>
    /// <param name="lua">The edited <c>plugin.lua</c> content.</param>
    /// <param name="token">Cancellation token for Lua validation, file IO, and plugin reload.</param>
    /// <returns>
    /// Update result that contains success state, updated plugin metadata, the plugin directory,
    /// and a user-facing issue when the update failed.
    /// </returns>
    public async Task<AssistantPluginUpdateResult> UpdateInstalledAssistantAsync(IAvailablePlugin plugin, string lua, CancellationToken token)
    {
        if (plugin.Type is not PluginType.ASSISTANT)
            return UpdateError(plugin, plugin.LocalPath, TB("Only assistant plugins can be edited."));

        if (plugin.IsInternal)
            return UpdateError(plugin, plugin.LocalPath, TB("Internal assistant plugins cannot be edited."));

        if (string.IsNullOrWhiteSpace(plugin.LocalPath))
            return UpdateError(plugin, string.Empty, TB("The assistant plugin has no local directory."));

        if (!TryGetAssistantPluginsRoot(out var assistantPluginsRoot, out var rootIssue))
            return UpdateError(plugin, plugin.LocalPath, rootIssue);

        var pluginDirectory = plugin.LocalPath;
        if (!IsPathInsideDirectory(assistantPluginsRoot, pluginDirectory) || IsSameDirectory(assistantPluginsRoot, pluginDirectory))
            return UpdateError(plugin, pluginDirectory, TB("The assistant plugin directory is outside the local assistant plugin directory."));

        if (!Directory.Exists(pluginDirectory))
            return UpdateError(plugin, pluginDirectory, TB("The assistant plugin directory does not exist."));

        var pluginFile = Path.Join(pluginDirectory, PLUGIN_FILE_NAME);
        if (!IsPathInsideDirectory(pluginDirectory, pluginFile))
            return UpdateError(plugin, pluginDirectory, TB("The plugin file is outside the assistant plugin directory."));

        await this.installSemaphore.WaitAsync(token);
        var tempFile = string.Empty;
        var backupFile = string.Empty;

        try
        {
            var validation = await this.ValidateInPluginDirectoryAsync(lua, pluginDirectory, token);
            if (!validation.Success || validation.AssistantPlugin is null)
                return UpdateError(plugin, pluginDirectory, validation.Issue);

            var assistantPlugin = validation.AssistantPlugin;
            if (assistantPlugin.Id != plugin.Id)
                return UpdateError(plugin, pluginDirectory, TB("The edited assistant plugin must keep the same plugin ID."));

            var pluginCode = lua.Trim();
            tempFile = Path.Join(pluginDirectory, $"{PLUGIN_FILE_NAME}.tmp-{Guid.NewGuid():N}");
            backupFile = Path.Join(pluginDirectory, $"{PLUGIN_FILE_NAME}.backup-{Guid.NewGuid():N}");

            await File.WriteAllTextAsync(tempFile, pluginCode, Encoding.UTF8, token);

            if (File.Exists(pluginFile))
                File.Replace(tempFile, pluginFile, backupFile);
            else
                File.Move(tempFile, pluginFile);

            try
            {
                await PluginFactory.LoadAll(token);
                if (File.Exists(backupFile))
                    File.Delete(backupFile);

                this.logger.LogInformation($"Updated assistant plugin '{assistantPlugin.Name}' ({assistantPlugin.Id}) at '{pluginFile}'.");
                return new(true, assistantPlugin.Id, assistantPlugin.Name, pluginDirectory, string.Empty);
            }
            catch (Exception reloadException)
            {
                this.logger.LogError(reloadException, $"Failed to reload plugins after editing assistant plugin '{plugin.Name}' ({plugin.Id}).");
                await this.TryRestoreEditedAssistantPluginAsync(pluginFile, backupFile, token);
                return UpdateError(plugin, pluginDirectory, string.Format(TB("Unexpected error: {0}"), reloadException.Message));
            }
        }
        catch (Exception e)
        {
            this.logger.LogError(e, $"Failed to update assistant plugin '{plugin.Name}' ({plugin.Id}) at '{pluginDirectory}'.");
            await this.TryRestoreEditedAssistantPluginAsync(pluginFile, backupFile, token);
            return UpdateError(plugin, pluginDirectory, string.Format(TB("Unexpected error: {0}"), e.Message));
        }
        finally
        {
            this.TryDeleteFile(tempFile, "assistant plugin edit temp file");

            this.installSemaphore.Release();
        }
    }

    private async Task<AssistantPluginInstallResult> InstallStagedAssistantAsync(string assistantPluginsRoot, AssistantPluginValidationResult validation, CancellationToken token)
    {
        var stagingDirectory = validation.StagingDirectory;
        var assistantPlugin = validation.AssistantPlugin!;
        string? backupDirectory = null;
        string? finalDirectory = null;
        var replacedExisting = false;
        var movedIntoPlace = false;

        try
        {
            Directory.CreateDirectory(assistantPluginsRoot);
            finalDirectory = DetermineFinalDirectory(assistantPluginsRoot, assistantPlugin);
            if (!IsPathInsideDirectory(assistantPluginsRoot, finalDirectory))
                return Error(TB("The resolved plugin directory is outside the assistant plugin directory."));

            var replacementIssue = GetAssistantReplacementIssue(assistantPlugin.Id);
            if (!string.IsNullOrWhiteSpace(replacementIssue))
                return Error(replacementIssue);

            if (Directory.Exists(finalDirectory))
            {
                replacedExisting = true;

                // The backup goes to a directory outside the plugin root, so the plugin loader
                // cannot discover it during the reload below. Otherwise, the previous version
                // would be loaded a second time, next to the version we are installing:
                backupDirectory = CreateInstallBackupDirectory(assistantPlugin);
                Directory.CreateDirectory(Path.GetDirectoryName(backupDirectory)!);
                Directory.Move(finalDirectory, backupDirectory);
            }

            Directory.Move(stagingDirectory, finalDirectory);
            movedIntoPlace = true;
            await PluginFactory.LoadAll(token);

            if (!string.IsNullOrWhiteSpace(backupDirectory))
                TryDeleteDirectory(backupDirectory, "assistant plugin backup", this.logger);

            this.logger.LogInformation("Installed assistant plugin '{PluginName}' ({PluginId}) to '{PluginDirectory}'.", assistantPlugin.Name, assistantPlugin.Id, finalDirectory);
            return new(true, assistantPlugin.Id, assistantPlugin.Name, finalDirectory, replacedExisting, string.Empty);
        }
        catch (Exception e)
        {
            this.logger.LogError(e, "Failed to install assistant plugin.");

            // Only remove the target directory when this installation actually moved the plugin
            // there. Otherwise, when moving the previous plugin into the backup directory failed,
            // we would delete the still intact previous plugin:
            if (movedIntoPlace && !string.IsNullOrWhiteSpace(finalDirectory) && Directory.Exists(finalDirectory))
                TryDeleteDirectory(finalDirectory, "failed assistant plugin installation", this.logger);

            if (!string.IsNullOrWhiteSpace(backupDirectory) && Directory.Exists(backupDirectory) && !string.IsNullOrWhiteSpace(finalDirectory) && !Directory.Exists(finalDirectory))
            {
                try
                {
                    Directory.Move(backupDirectory, finalDirectory);
                    await PluginFactory.LoadAll(CancellationToken.None);
                }
                catch (Exception restoreException)
                {
                    this.logger.LogError(restoreException, "Failed to restore the previous assistant plugin after a failed installation.");
                }
            }

            return Error(string.Format(TB("Unexpected error: {0}"), e.Message));
        }
        finally
        {
            this.TryDeleteStagingDirectory(stagingDirectory);
        }
    }

    private async Task<AssistantPluginValidationResult> ValidateIntoStagingAsync(string lua, CancellationToken token)
    {
        if (string.IsNullOrWhiteSpace(lua))
            return AssistantPluginValidationResult.Failure(TB("No Lua plugin code was generated."));

        if (!PluginFactory.IsInitialized)
            return AssistantPluginValidationResult.Failure(TB("The plugin system is not initialized yet."));

        var pluginCode = lua.Trim();
        var stagingDirectory = Path.Join(Path.GetTempPath(), $"{ASSISTANT_BUILDER_DIRECTORY_PREFIX}.staging-{Guid.NewGuid():N}");

        try
        {
            Directory.CreateDirectory(stagingDirectory);
            var stagedPluginFile = Path.Join(stagingDirectory, PLUGIN_FILE_NAME);
            await File.WriteAllTextAsync(stagedPluginFile, pluginCode, Encoding.UTF8, token);

            var validation = await ValidateAssistantPluginCodeAsync(
                stagingDirectory,
                pluginCode,
                TB("The generated plugin is not an assistant plugin. Issue: {0}"),
                TB("The generated assistant plugin is invalid. Issue: {0}"),
                TB("The generated assistant plugin uses the ID of another installed plugin."),
                token);

            if (!validation.Success || validation.AssistantPlugin is null)
                this.TryDeleteStagingDirectory(stagingDirectory);

            return validation with { StagingDirectory = stagingDirectory };
        }
        catch (Exception e)
        {
            this.logger.LogError(e, "Failed to validate generated assistant plugin.");
            this.TryDeleteStagingDirectory(stagingDirectory);
            return AssistantPluginValidationResult.Failure(string.Format(TB("Unexpected error: {0}"), e.Message));
        }
    }

    private async Task<AssistantPluginValidationResult> ValidateInPluginDirectoryAsync(string lua, string pluginDirectory, CancellationToken token)
    {
        if (string.IsNullOrWhiteSpace(lua))
            return AssistantPluginValidationResult.Failure(TB("No Lua plugin code was generated."));

        if (!PluginFactory.IsInitialized)
            return AssistantPluginValidationResult.Failure(TB("The plugin system is not initialized yet."));

        try
        {
            return await ValidateAssistantPluginCodeAsync(
                pluginDirectory,
                lua.Trim(),
                TB("The edited plugin is not an assistant plugin. Issue: {0}"),
                TB("The edited assistant plugin is invalid. Issue: {0}"),
                TB("The edited assistant plugin uses the ID of another installed plugin."),
                token);
        }
        catch (Exception e)
        {
            this.logger.LogError(e, "Failed to validate edited assistant plugin.");
            return AssistantPluginValidationResult.Failure(string.Format(TB("Unexpected error: {0}"), e.Message));
        }
    }

    private static async Task<AssistantPluginValidationResult> ValidateAssistantPluginCodeAsync(string pluginDirectory, string pluginCode,
        string notAssistantIssue, string invalidAssistantIssue, string conflictingPluginIdIssue, CancellationToken token)
    {
        // The plugin is not installed yet: it sits in a staging directory outside the installed
        // plugins directory. We allow that directory as the module base, so the plugin can load its
        // own Lua modules, e.g., an icon.lua, while we validate it:
        var plugin = await PluginFactory.Load(pluginDirectory, pluginCode, token, pluginDirectory);
        if (plugin is not PluginAssistants assistantPlugin)
            return AssistantPluginValidationResult.Failure(string.Format(notAssistantIssue, string.Join("; ", plugin.Issues)));

        if (!assistantPlugin.IsValid)
            return AssistantPluginValidationResult.Failure(string.Format(invalidAssistantIssue, string.Join("; ", assistantPlugin.Issues)));

        // Plugin IDs must be unique across all plugin types: several lookups resolve a plugin by its
        // ID alone, e.g., the base language plugin in PluginFactory.Starting. An assistant plugin
        // carrying the ID of a language or configuration plugin would break those lookups. Reusing
        // the ID of another local assistant plugin stays allowed: that is how updating one works.
        if (PluginFactory.AvailablePlugins.Any(availablePlugin => availablePlugin.Id == assistantPlugin.Id && (availablePlugin.IsInternal || availablePlugin.Type is not PluginType.ASSISTANT)))
            return AssistantPluginValidationResult.Failure(conflictingPluginIdIssue);

        return new(true, string.Empty, assistantPlugin, string.Empty);
    }

    private static bool TryGetAssistantPluginsRoot(out string assistantPluginsRoot, out string issue)
    {
        assistantPluginsRoot = string.Empty;
        issue = string.Empty;

        var dataDirectory = SettingsManager.DataDirectory;
        if (string.IsNullOrWhiteSpace(dataDirectory))
        {
            issue = TB("The AI Studio data directory is not initialized yet.");
            return false;
        }

        assistantPluginsRoot = Path.Join(dataDirectory, "plugins", PluginType.ASSISTANT.GetDirectory());
        return true;
    }

    private static string GetAssistantDeletionEligibilityIssue(IAvailablePlugin plugin)
    {
        if (plugin.Type is not PluginType.ASSISTANT)
            return TB("Only assistant plugins can be deleted.");

        if (plugin.IsInternal)
            return TB("Internal assistant plugins cannot be deleted.");

        if (plugin.IsManagedByConfigServer)
            return TB("Config Server managed assistant plugins cannot be deleted.");

        if (string.IsNullOrWhiteSpace(plugin.LocalPath))
            return TB("The assistant plugin has no local directory.");

        var assistantPlugin = PluginFactory.RunningPlugins
            .OfType<PluginAssistants>()
            .FirstOrDefault(candidate => candidate.Id == plugin.Id && IsSameDirectory(candidate.PluginPath, plugin.LocalPath));
        
        if (assistantPlugin is null || assistantPlugin.IsInternal || !assistantPlugin.IsAssistantBuilderGenerated)
            return TB("Only assistants generated by the Assistant Builder can be deleted.");

        if (assistantPlugin.IsManagedByConfigServer)
            return TB("Config Server managed assistant plugins cannot be deleted.");

        if (!TryGetAssistantPluginsRoot(out var assistantPluginsRoot, out var rootIssue))
            return rootIssue;

        if (!IsPathInsideDirectory(assistantPluginsRoot, plugin.LocalPath) || IsSameDirectory(assistantPluginsRoot, plugin.LocalPath))
            return TB("The assistant plugin directory is outside the local assistant plugin directory.");

        return Directory.Exists(plugin.LocalPath)
            ? string.Empty
            : TB("The assistant plugin directory does not exist.");
    }

    private void TryDeleteStagingDirectory(string stagingDirectory) => TryDeleteDirectory(stagingDirectory, "assistant plugin staging", this.logger);

    private static string DetermineFinalDirectory(string assistantPluginsRoot, PluginAssistants assistantPlugin)
    {
        var existingPlugin = FindReplaceableAssistantPlugin(assistantPlugin.Id);
        return existingPlugin is not null
            ? existingPlugin.LocalPath
            : Path.Join(assistantPluginsRoot, CreatePluginDirectoryName(assistantPlugin));
    }

    /// <summary>
    /// Finds the local assistant plugin that an installation with the given ID would replace.
    /// </summary>
    /// <param name="pluginId">The ID of the assistant plugin about to be installed.</param>
    /// <returns>The plugin that would be replaced, or null when the installation adds a new plugin.</returns>
    private static IAvailablePlugin? FindReplaceableAssistantPlugin(Guid pluginId) => PluginFactory.AvailablePlugins
        .OfType<IAvailablePlugin>()
        .FirstOrDefault(plugin => plugin.Type is PluginType.ASSISTANT && plugin.Id == pluginId && !plugin.IsInternal);

    /// <summary>
    /// Collects the metadata an archive declares about itself, together with the information about
    /// the installed plugin it would replace.
    /// </summary>
    /// <param name="assistantPlugin">The validated assistant plugin from the archive.</param>
    /// <returns>The preview shown to the user before the installation starts.</returns>
    private static PluginImportPreview CreateImportPreview(PluginAssistants assistantPlugin) => new(assistantPlugin, FindReplaceableAssistantPlugin(assistantPlugin.Id));

    /// <summary>
    /// Checks whether an installation may replace the assistant plugin that currently uses the given ID.
    /// Plugins deployed by a Config Server belong to the organization's IT, so neither an import nor
    /// the Assistant Builder may overwrite them.
    /// </summary>
    /// <param name="pluginId">The ID of the assistant plugin about to be installed.</param>
    /// <returns>A user-facing issue when the existing plugin must not be replaced, an empty string otherwise.</returns>
    private static string GetAssistantReplacementIssue(Guid pluginId)
    {
        var existingPlugin = FindReplaceableAssistantPlugin(pluginId);
        if (existingPlugin is null)
            return string.Empty;

        if (existingPlugin.IsManagedByConfigServer)
            return TB("Config server managed assistant plugins cannot be replaced.");

        if (string.IsNullOrWhiteSpace(existingPlugin.LocalPath))
            return string.Empty;

        // The metadata above and the running plugin read the same Lua field. We check both, though,
        // just like the deletion path does:
        var runningPlugin = PluginFactory.RunningPlugins
            .OfType<PluginAssistants>()
            .FirstOrDefault(candidate => candidate.Id == pluginId && IsSameDirectory(candidate.PluginPath, existingPlugin.LocalPath));

        return runningPlugin?.IsManagedByConfigServer is true
            ? TB("Config server managed assistant plugins cannot be replaced.")
            : string.Empty;
    }

    private static string CreatePluginDirectoryName(PluginAssistants assistantPlugin)
    {
        var safeName = CreateSafeDirectoryNamePart(assistantPlugin.Name);
        return $"{safeName}-{assistantPlugin.Id:N}";
    }

    private static string CreateSafeDirectoryNamePart(string name)
    {
        var sb = new StringBuilder();
        var invalidChars = Path.GetInvalidFileNameChars().ToHashSet();

        foreach (var character in name.Trim())
        {
            if (char.IsLetterOrDigit(character))
            {
                sb.Append(char.ToLowerInvariant(character));
                continue;
            }

            if (character is '-' or '_' or '.' && !invalidChars.Contains(character))
            {
                sb.Append(character);
                continue;
            }

            AppendSeparator();
        }

        var safeName = sb.ToString().Trim('-', '.');
        if (safeName.Length > DIRECTORY_PREFIX_MAX_LEN)
            safeName = safeName[..DIRECTORY_PREFIX_MAX_LEN].Trim('-', '.');

        return string.IsNullOrWhiteSpace(safeName)
            ? ASSISTANT_BUILDER_DIRECTORY_PREFIX
            : safeName;

        void AppendSeparator()
        {
            if (sb.Length == 0 || sb[^1] == '-')
                return;

            sb.Append('-');
        }
    }

    private static bool IsPathInsideDirectory(string parentDirectory, string path)
    {
        var parentPath = Path.GetFullPath(parentDirectory).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar) + Path.DirectorySeparatorChar;
        var childPath = Path.GetFullPath(path).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar) + Path.DirectorySeparatorChar;
        return childPath.StartsWith(parentPath, StringComparison.OrdinalIgnoreCase);
    }

    private static bool IsSameDirectory(string firstDirectory, string secondDirectory)
    {
        var firstPath = Path.GetFullPath(firstDirectory).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
        var secondPath = Path.GetFullPath(secondDirectory).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
        return string.Equals(firstPath, secondPath, StringComparison.OrdinalIgnoreCase);
    }

    private static string CreateDeleteBackupDirectory(IAvailablePlugin plugin)
    {
        var backupRoot = Path.Join(SettingsManager.DataDirectory, DELETE_BACKUP_DIRECTORY);
        return Path.Join(backupRoot, $"assistant-{plugin.Id:N}-{Guid.NewGuid():N}");
    }

    private static string CreateInstallBackupDirectory(IPluginMetadata plugin)
    {
        var backupRoot = Path.Join(SettingsManager.DataDirectory, INSTALL_BACKUP_DIRECTORY);
        return Path.Join(backupRoot, $"assistant-{plugin.Id:N}-{Guid.NewGuid():N}");
    }

    private async Task TryRestoreDeletedAssistantPluginAsync(IAvailablePlugin plugin, string pluginDirectory, string backupDirectory, bool wasEnabled, List<PluginAssistantAudit> removedAudits, CancellationToken token)
    {
        try
        {
            if (!Directory.Exists(pluginDirectory) && Directory.Exists(backupDirectory))
                Directory.Move(backupDirectory, pluginDirectory);

            if (wasEnabled && !this.settingsManager.ConfigurationData.EnabledPlugins.Contains(plugin.Id))
                this.settingsManager.ConfigurationData.EnabledPlugins.Add(plugin.Id);

            if (removedAudits.Count > 0)
            {
                this.settingsManager.ConfigurationData.AssistantPluginAudits.RemoveAll(audit => audit.PluginId == plugin.Id);
                this.settingsManager.ConfigurationData.AssistantPluginAudits.AddRange(removedAudits);
            }

            await this.settingsManager.StoreSettings();
            await PluginFactory.LoadAll(token);
        }
        catch (Exception restoreException)
        {
            this.logger.LogError(restoreException, $"Failed to restore assistant plugin '{plugin.Name}' ({plugin.Id}) after a failed delete.");
        }
    }

    private async Task TryRestoreEditedAssistantPluginAsync(string pluginFile, string backupFile, CancellationToken token)
    {
        try
        {
            if (string.IsNullOrWhiteSpace(backupFile) || !File.Exists(backupFile))
                return;

            if (File.Exists(pluginFile))
                File.Delete(pluginFile);

            File.Move(backupFile, pluginFile);
            await PluginFactory.LoadAll(token);
        }
        catch (Exception restoreException)
        {
            this.logger.LogError(restoreException, $"Failed to restore assistant plugin file '{pluginFile}' after a failed edit.");
        }
    }

    private static void TryDeleteDirectory(string directory, string directoryDescription, ILogger logger)
    {
        if (!Directory.Exists(directory))
            return;

        try
        {
            Directory.Delete(directory, true);
        }
        catch (Exception e)
        {
            logger.LogError(e, $"Failed to delete {directoryDescription} directory '{directory}'.");
        }
    }

    private void TryDeleteFile(string filePath, string fileDescription)
    {
        if (string.IsNullOrWhiteSpace(filePath) || !File.Exists(filePath))
            return;

        try
        {
            File.Delete(filePath);
        }
        catch (Exception e)
        {
            this.logger.LogError(e, $"Failed to delete {fileDescription} '{filePath}'.");
        }
    }

    private sealed record AssistantPluginValidationResult(bool Success, string StagingDirectory, PluginAssistants? AssistantPlugin, string Issue)
    {
        public static AssistantPluginValidationResult Failure(string issue) => new(false, string.Empty, null, issue);
    }
}