SDK Interface

// Reads .aipkg archives
public sealed class AipkgReader : IDisposable
{
    public AipkgReader(Stream stream);
    public AipkgReader(string filePath);

    // Reads the manifest without extracting the full archive
    public AipkgManifest ReadManifest();

    // Lists all entries in the archive
    public IReadOnlyList<AipkgEntry> GetEntries();

    // Opens a specific entry for reading
    public Stream OpenEntry(string entryPath);

    // Extracts files for a given APM, applying fallback resolution
    public IReadOnlyDictionary<string, Stream> ExtractForPlatform(string apmMoniker);
}

public sealed record AipkgEntry(
    string Path,
    long CompressedSize,
    long UncompressedSize,
    string Section  // "shared", "apm/{moniker}", "root", "reserved"
);

// Creates .aipkg archives
public sealed class AipkgWriter : IDisposable
{
    public AipkgWriter(Stream outputStream);
    public AipkgWriter(string outputFilePath);

    // Must be called first
    public void WriteManifest(AipkgManifest manifest);

    // Adds a file to shared/
    public void AddSharedFile(string relativePath, Stream content);

    // Adds a file to apm/{moniker}/
    public void AddPlatformFile(string moniker, string relativePath, Stream content);

    // Adds icon, README, LICENSE at archive root
    public void AddRootFile(string filename, Stream content);

    public void Finalize();
}

public sealed class PlatformCompatibilityService
{
    // e.g. "claude-code" → ["apm/claude-code", "apm/claude", "apm/ai", "shared"]
    public IReadOnlyList<string> GetFallbackChain(string moniker);

    public string? GetParent(string moniker);

    public bool IsCompatible(IReadOnlyList<string> packageTargets, string targetMoniker);

    public string? GetInstallPath(string moniker, OperatingSystem os);

    public IReadOnlyList<ApmInfo> GetAllPlatforms();

    public bool IsKnown(string moniker);
}

public sealed record ApmInfo(
    string Moniker,
    string DisplayName,
    string? Parent,
    string? InstallPath,
    string Stability  // "stable", "provisional", "deprecated"
);

public sealed class AipkgValidator
{
    public ValidationResult ValidateManifest(AipkgManifest manifest);
    public ValidationResult ValidateArchive(Stream archiveStream);
}

public sealed class ValidationResult
{
    public bool IsValid { get; }
    public IReadOnlyList<ValidationError> Errors { get; }
    public IReadOnlyList<ValidationWarning> Warnings { get; }
}

public sealed record ValidationError(string Code, string Message, string? Field = null);
public sealed record ValidationWarning(string Code, string Message, string? Field = null);

// SemVer 2.0.0 — compatible with NuGet versioning
public sealed class AipkgVersion : IComparable<AipkgVersion>
{
    public static AipkgVersion Parse(string version);
    public static bool TryParse(string version, out AipkgVersion result);
    public bool SatisfiesRange(string versionRange);
}

{
  "$schema": "https://aipkg.org/schemas/lock/1.0.0",
  "version": 1,
  "platform": "claude-code",
  "packages": [
    {
      "id": "git-helpers",
      "resolved": "1.0.0",
      "contentHash": "sha256:abc123...",
      "downloadUrl": "https://aipkg.org/v3/flatcontainer/git-helpers/1.0.0/git-helpers.1.0.0.aipkg",
      "installedFiles": [
        ".claude/skills/git-helpers.md",
        ".claude/prompts/git-base.md"
      ],
      "dependencies": []
    }
  ]
}

{
  "defaultSource": "https://aipkg.org/v3/index.json",
  "defaultPlatform": "claude-code",
  "globalInstallPath": "~/.aipkg/global/",
  "httpTimeout": 300
}