Develop a CloudSmith module

using CloudSmith.Core.Modules;

public interface ICloudSmithModule
{
    /// <summary>Module ID — must match the catalog entry (e.g., "monitoring").</summary>
    string Id { get; }

    /// <summary>Human-readable display name.</summary>
    string Name { get; }

    /// <summary>SemVer version string (e.g., "1.2.0").</summary>
    string Version { get; }

    /// <summary>
    /// Called once when the module is loaded. Use this to validate configuration,
    /// register background services, and perform any one-time setup.
    /// Throw to abort module load and prevent the module from becoming active.
    /// </summary>
    Task InitializeAsync(ICloudSmithModuleContext context, CancellationToken cancellationToken);

    /// <summary>
    /// Called repeatedly on a platform-defined schedule (default: every 30 seconds).
    /// Perform recurring work here — polling, health checks, data collection.
    /// This method must return promptly; use background tasks for long-running work.
    /// </summary>
    Task ExecuteAsync(ICloudSmithModuleContext context, CancellationToken cancellationToken);

    /// <summary>
    /// Called when the module is unloaded (platform shutdown or explicit uninstall).
    /// Release resources, cancel background tasks, flush buffers.
    /// </summary>
    ValueTask DisposeAsync();
}

public interface ICloudSmithModuleContext
{
    /// <summary>Logger scoped to this module.</summary>
    ILogger Logger { get; }

    /// <summary>Key/value configuration for the module (from appsettings or environment).</summary>
    IConfiguration Configuration { get; }

    /// <summary>
    /// Access to registered clusters. Use to enumerate clusters, nodes, and run jobs.
    /// </summary>
    IClusterRepository Clusters { get; }

    /// <summary>Job scheduler for submitting operations to cluster nodes.</summary>
    IJobScheduler Jobs { get; }

    /// <summary>Platform event bus — publish and subscribe to CloudSmith domain events.</summary>
    IEventBus Events { get; }

    /// <summary>
    /// Persistent key/value store scoped to this module.
    /// Use for state that must survive module restarts.
    /// </summary>
    IModuleStateStore State { get; }
}

public interface ICloudSmithModuleCatalog
{
    /// <summary>
    /// List all modules available in this catalog source.
    /// </summary>
    Task<IReadOnlyList<ModuleCatalogEntry>> ListAsync(CancellationToken cancellationToken);

    /// <summary>
    /// Get a specific module by ID.
    /// </summary>
    Task<ModuleCatalogEntry?> GetAsync(string moduleId, CancellationToken cancellationToken);

    /// <summary>
    /// Download a module artifact for installation.
    /// Return a stream containing the OCI layer tar archive.
    /// </summary>
    Task<Stream> DownloadAsync(string moduleId, string version, CancellationToken cancellationToken);
}

public record ModuleCatalogEntry(
    string Id,
    string Name,
    string Version,
    string Description,
    string ImageReference,   // e.g., "ghcr.io/cloudsmith-cloud/module-monitoring:1.2.0"
    bool   IsVerified        // true if cosign signature is valid
);

// In Program.cs or a service registration extension
using CloudSmith.Core.Modules;

builder.Services.AddCloudSmithModuleCatalog<MyCustomModuleCatalog>();

builder.Services.AddCloudSmithModuleCatalog<GhcrModuleCatalog>();   // default
builder.Services.AddCloudSmithModuleCatalog<PrivateModuleCatalog>(); // appended

using CloudSmith.Core.Modules;

[CloudSmithModule]
public class InventoryCollectorModule : ICloudSmithModule
{
    public string Id      => "inventory-collector";
    public string Name    => "Inventory Collector";
    public string Version => "1.0.0";

    private PeriodicTimer? _timer;

    public async Task InitializeAsync(ICloudSmithModuleContext context, CancellationToken cancellationToken)
    {
        context.Logger.LogInformation("Inventory Collector initializing.");
        // Validate required config, register event subscriptions, etc.
        await Task.CompletedTask;
    }

    public async Task ExecuteAsync(ICloudSmithModuleContext context, CancellationToken cancellationToken)
    {
        var clusters = await context.Clusters.ListAsync(cancellationToken);
        foreach (var cluster in clusters)
        {
            var job = await context.Jobs.SubmitAsync(new JobRequest
            {
                ClusterId = cluster.Id,
                Type      = "InvokeScript",
                Payload   = new { Script = "Get-VM | Select-Object Name, State | ConvertTo-Json" }
            }, cancellationToken);

            context.Logger.LogInformation("Submitted inventory job {JobId} for cluster {ClusterId}",
                job.Id, cluster.Id);
        }
    }

    public ValueTask DisposeAsync()
    {
        _timer?.Dispose();
        return ValueTask.CompletedTask;
    }
}