File: Agents\AspireSkills\AspireSkillsRemoteConfiguration.cs
Web Access
Project: src\src\Aspire.Cli\Aspire.Cli.csproj (aspire)
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
 
using System.Globalization;
using System.Text.Json.Nodes;
using Aspire.Cli.Resources;
 
namespace Aspire.Cli.Agents.AspireSkills;
 
/// <summary>
/// Aspire plugin and OpenCode catalog registration without acquiring their content.
/// </summary>
internal static class AspireSkillsRemoteConfiguration
{
    internal const string MarketplaceName = "aspire-skills";
    internal const string PluginName = "aspire@aspire-skills";
    internal const string Repository = "microsoft/aspire-skills";
    internal const string RepositoryUrl = "https://github.com/" + Repository;
 
    public static bool HasPluginRegistration(IEnumerable<string> settings, IReadOnlyList<SkillSource> sources)
    {
        // Disabling new registrations does not disable a plugin already active in an agent.
        var pluginNames = sources.SelectMany(source => source.GetPluginNames()).Prepend(PluginName).Distinct(StringComparer.Ordinal).ToArray();
        var enabled = new HashSet<string>(StringComparer.Ordinal);
        foreach (var path in settings)
        {
            // A JSON null registers nothing, so it reads like a missing key. Other wrong types still throw
            // InvalidOperationException from AsObject or GetValue.
            if (AgentConfiguration.ReadObject(path)?["enabledPlugins"] is { } pluginsNode)
            {
                var plugins = pluginsNode.AsObject();
                foreach (var pluginName in pluginNames)
                {
                    if (plugins[pluginName] is { } valueNode)
                    {
                        if (valueNode.GetValue<bool>())
                        {
                            enabled.Add(pluginName);
                        }
                        else
                        {
                            enabled.Remove(pluginName);
                        }
                    }
                }
            }
        }
 
        return enabled.Count > 0;
    }
 
    public static void ApplyOpenCodeCatalog(JsonObject root, IEnumerable<JsonObject> configs, IReadOnlyList<SkillSource> skillSources)
    {
        var target = ReadOpenCodeSkills(root);
        var settings = configs.ToArray();
        foreach (var source in skillSources)
        {
            var catalog = root["skills"] is JsonArray
                ? source.OpenCodeV2Catalog ?? source.OpenCodeV1Catalog
                : source.OpenCodeV1Catalog ?? source.OpenCodeV2Catalog;
            if (catalog is null)
            {
                continue;
            }
            string? preferred = null;
            foreach (var config in settings)
            {
                var sources = ReadOpenCodeSkills(config);
                if (sources?.Select(String).FirstOrDefault(value => IsOpenCodeCatalog(value, source)) is { } existing &&
                    (preferred is null || preferred.Contains("/main/opencode/", StringComparison.Ordinal)))
                {
                    preferred = existing;
                }
            }
 
            // V2 accepts V1 skills objects and native arrays independently of MCP.
            // Catalog URLs identify content and pins, not the surrounding JSON syntax.
            // https://github.com/anomalyco/opencode/blob/52a10f573f1da5103c85990da9341e3645a39365/services/www/src/docs/content/migrate-v1.mdx#skills
            preferred ??= catalog;
            if (target is null)
            {
                // With no skills setting, use the object form supported by both clients.
                target = new JsonArray();
                Object(root, "skills")["urls"] = target;
            }
            if (!target.Any(value => IsOpenCodeCatalog(String(value), source)))
            {
                target.Add((JsonNode?)preferred);
            }
        }
    }
 
    public static bool HasOpenCodeCatalog(JsonObject root, IReadOnlyList<SkillSource> sources)
        => ReadOpenCodeSkills(root)?.Any(value =>
            IsOpenCodeCatalog(String(value), SkillSource.BuiltIn) ||
            sources.Any(source => IsOpenCodeCatalog(String(value), source))) is true;
 
    internal static JsonArray? ReadOpenCodeSkills(JsonObject root)
    {
        if (!root.TryGetPropertyValue("skills", out var skills))
        {
            return null;
        }
 
        if (skills is JsonObject v1)
        {
            OptionalStrings(v1, "paths");
            return OptionalStrings(v1, "urls");
        }
        ArgumentNullException.ThrowIfNull(skills);
        return Strings(skills.AsArray());
    }
 
    internal static bool IsOpenCodeCatalog(string? source, SkillSource configuration)
    {
        if (source is null)
        {
            return false;
        }
        if (source == configuration.OpenCodeV1Catalog || source == configuration.OpenCodeV2Catalog)
        {
            return true;
        }
        // Recognize existing official release/commit pins only when using the built-in
        // catalog. Custom catalog URLs are identities and must match exactly.
        if (configuration.OpenCodeV1Catalog != SkillSource.DefaultV1Catalog &&
            configuration.OpenCodeV2Catalog != SkillSource.DefaultV2Catalog)
        {
            return false;
        }
        if (!Uri.TryCreate(source, UriKind.Absolute, out var uri) || uri.Scheme != Uri.UriSchemeHttps ||
            !uri.Host.Equals("raw.githubusercontent.com", StringComparison.OrdinalIgnoreCase) ||
            !uri.AbsolutePath.StartsWith("/microsoft/aspire-skills/", StringComparison.OrdinalIgnoreCase))
        {
            return false;
        }
 
        var path = uri.AbsolutePath.TrimEnd('/');
        return configuration.OpenCodeV1Catalog == SkillSource.DefaultV1Catalog && path.EndsWith("/opencode/v1", StringComparison.Ordinal) ||
            configuration.OpenCodeV2Catalog == SkillSource.DefaultV2Catalog && path.EndsWith("/opencode/v2", StringComparison.Ordinal);
    }
 
    public static async Task ApplyPluginAsync(
        JsonObject root, IEnumerable<string> settingsPaths, string targetPath,
        AgentConfiguration edit, IReadOnlyList<SkillSource> sources, CancellationToken cancellationToken)
    {
        if (sources.Count == 0)
        {
            return;
        }
        var settings = await ReadSettingsAsync(settingsPaths, targetPath, edit, cancellationToken);
        // Leave marketplace policy enforcement to the client rather than matching its rules.
        foreach (var config in settings.Append(root))
        {
            foreach (var policy in new[] { "strictKnownMarketplaces", "blockedMarketplaces" })
            {
                if (config.ContainsKey(policy))
                {
                    throw ExistingConfiguration(policy);
                }
            }
        }
        foreach (var skillSource in sources)
        {
            ApplyPlugin(root, settings, skillSource);
        }
    }
 
    private static void ApplyPlugin(JsonObject root, IReadOnlyList<JsonObject> settings, SkillSource skillSource)
    {
        var marketplaceName = skillSource.Marketplace!;
        var pluginNames = skillSource.GetPluginNames().ToArray();
        JsonObject? selectedSource = null;
        foreach (var config in settings.Append(root))
        {
            var plugins = OptionalObject(config, "enabledPlugins");
            foreach (var pluginName in pluginNames)
            {
                if (plugins is not null && Boolean(plugins, pluginName) is false)
                {
                    throw ExistingConfiguration($"enabledPlugins.{pluginName}");
                }
            }
 
            var marketplaces = OptionalObject(config, "extraKnownMarketplaces");
            if (marketplaces is not null && marketplaces.TryGetPropertyValue(marketplaceName, out var marketplaceNode))
            {
                ArgumentNullException.ThrowIfNull(marketplaceNode);
                var source = OptionalObject(marketplaceNode.AsObject(), "source");
                ArgumentNullException.ThrowIfNull(source);
 
                if (!IsMatchingSource(source, skillSource))
                {
                    throw ExistingConfiguration($"extraKnownMarketplaces.{marketplaceName}.source");
                }
 
                // Keep inherited release/commit pins unless the destination declares its own source.
                if (ReferenceEquals(config, root) || source.ContainsKey("ref") || source.ContainsKey("sha") || selectedSource is null)
                {
                    selectedSource = source;
                }
            }
        }
 
        if (selectedSource is null)
        {
            selectedSource = SkillSource.IsGitHubRepository(skillSource.Repository!)
                ? new JsonObject { ["source"] = "github", ["repo"] = skillSource.Repository }
                : new JsonObject { ["source"] = "git", ["url"] = skillSource.Repository };
            if (skillSource.Ref is not null)
            {
                selectedSource["ref"] = skillSource.Ref;
            }
        }
 
        var targetMarketplaces = Object(root, "extraKnownMarketplaces");
        if (!targetMarketplaces.ContainsKey(marketplaceName))
        {
            targetMarketplaces[marketplaceName] = new JsonObject
            {
                ["source"] = selectedSource.DeepClone()
            };
        }
 
        // No autoUpdate opt-in and no installedPlugins/cache metadata: registration is not
        // acquisition. Existing entries, including explicit false, were checked above.
        var targetPlugins = Object(root, "enabledPlugins");
        foreach (var pluginName in pluginNames)
        {
            if (!targetPlugins.ContainsKey(pluginName))
            {
                targetPlugins[pluginName] = true;
            }
        }
    }
 
    public static async Task<IReadOnlyList<JsonObject>> ReadSettingsAsync(
        IEnumerable<string> paths, string targetPath, AgentConfiguration edit, CancellationToken cancellationToken)
    {
        var settings = new List<JsonObject>();
        foreach (var path in paths.Distinct(StringComparers.FileSystemPath))
        {
            if (!string.Equals(path, targetPath, StringComparisons.FileSystemPath) &&
                await edit.ReadObjectForEditAsync(path, cancellationToken) is { } root)
            {
                settings.Add(root);
            }
        }
 
        return settings;
    }
 
    public static JsonObject? OptionalObject(JsonObject parent, string key)
    {
        if (!parent.TryGetPropertyValue(key, out var node))
        {
            return null;
        }
 
        ArgumentNullException.ThrowIfNull(node, key);
        return node.AsObject();
    }
 
    public static JsonObject Object(JsonObject parent, string key)
    {
        var value = OptionalObject(parent, key);
        if (value is null)
        {
            value = new JsonObject();
            parent[key] = value;
        }
 
        return value;
    }
 
    public static JsonArray? OptionalStrings(JsonObject parent, string key)
    {
        if (!parent.TryGetPropertyValue(key, out var node))
        {
            return null;
        }
 
        ArgumentNullException.ThrowIfNull(node, key);
        return Strings(node.AsArray());
    }
 
    public static JsonArray Strings(JsonArray array)
    {
        foreach (var value in array)
        {
            ArgumentNullException.ThrowIfNull(value);
            _ = value.GetValue<string>();
        }
 
        return array;
    }
 
    public static string? String(JsonNode? node)
        => node is JsonValue value && value.TryGetValue<string>(out var text) ? text : null;
 
    public static bool? Boolean(JsonObject parent, string key)
    {
        if (!parent.TryGetPropertyValue(key, out var node))
        {
            return null;
        }
 
        ArgumentNullException.ThrowIfNull(node, key);
        return node.GetValue<bool>();
    }
 
    internal static InvalidOperationException ExistingConfiguration(string key)
        => new(string.Format(CultureInfo.CurrentCulture, AgentCommandStrings.InitCommand_ExistingConfigurationConflict, key));
 
    private static bool IsMatchingSource(JsonObject source, SkillSource configuration)
    {
        return String(source["source"]) switch
        {
            "github" => String(source["repo"]) is { } repository &&
                string.Equals(NormalizeRepositoryUrl($"https://github.com/{repository}"),
                    NormalizeRepositoryUrl(configuration.GetRepositoryUrl()), StringComparison.OrdinalIgnoreCase),
            "git" => String(source["url"]) is { } url &&
                string.Equals(NormalizeRepositoryUrl(url), NormalizeRepositoryUrl(configuration.GetRepositoryUrl()),
                    Uri.TryCreate(configuration.GetRepositoryUrl(), UriKind.Absolute, out var repositoryUri) &&
                        repositoryUri.Scheme == Uri.UriSchemeHttps && repositoryUri.Host.Equals("github.com", StringComparison.OrdinalIgnoreCase)
                        ? StringComparison.OrdinalIgnoreCase : StringComparison.Ordinal),
            _ => false
        };
    }
 
    internal static string NormalizeRepositoryUrl(string url)
    {
        if (Uri.TryCreate(url, UriKind.Absolute, out var uri) && uri.Scheme is "https" or "ssh")
        {
            // AbsoluteUri normalizes HTTPS://GIT.EXAMPLE.COM/team/skills to lowercase scheme/host,
            // preserving case-sensitive repository paths and SSH usernames.
            // https://www.rfc-editor.org/rfc/rfc3986#section-6.2.2.1
            url = uri.AbsoluteUri;
        }
 
        url = url.TrimEnd('/');
        return url.EndsWith(".git", StringComparison.OrdinalIgnoreCase) ? url[..^4] : url;
    }
}