# stella CLI - Build and Distribution Matrix

**Sprint:** SPRINT_4100_0006_0006 - CLI Documentation Overhaul

## Overview

StellaOps CLI is distributed in **four regional variants** to comply with export control regulations and cryptographic standards. Each distribution includes different cryptographic plugins based on regional requirements.

**Key Principles:**
1. **Build-time Selection**: Crypto plugins are conditionally compiled based on build flags
2. **Export Compliance**: Each distribution complies with export control laws
3. **Deterministic Builds**: Same source + flags = same binary (reproducible builds)
4. **Validation**: Automated validation ensures correct plugin inclusion

---

## Distribution Matrix

| Distribution | Crypto Plugins | Build Flag | Target Audience | Export Restrictions |
|--------------|----------------|------------|-----------------|---------------------|
| **stella-international** | Default (.NET, BouncyCastle) | None | Global (unrestricted) | ✅ No restrictions |
| **stella-russia** | Default + GOST | `StellaOpsEnableGOST=true` | Russia, CIS states | ⚠️  Russia/CIS only |
| **stella-eu** | Default + eIDAS | `StellaOpsEnableEIDAS=true` | European Union | ⚠️  EU/EEA only |
| **stella-china** | Default + SM | `StellaOpsEnableSM=true` | China | ⚠️  China only |

---

## Crypto Provider Matrix

| Provider | International | Russia | EU | China |
|----------|---------------|--------|-----|-------|
| **.NET Crypto** (RSA, ECDSA, EdDSA) | ✅ | ✅ | ✅ | ✅ |
| **BouncyCastle** (Extended algorithms) | ✅ | ✅ | ✅ | ✅ |
| **GOST** (R 34.10-2012, R 34.11-2012) | ❌ | ✅ | ❌ | ❌ |
| **eIDAS** (QES, AES, AdES) | ❌ | ❌ | ✅ | ❌ |
| **SM** (SM2, SM3, SM4) | ❌ | ❌ | ❌ | ✅ |

---

## Build Instructions

### Prerequisites

- .NET 10 SDK
- Git
- Docker (for Linux builds on Windows/macOS)

### Build Environment Setup

```bash
# Clone repository
git clone https://git.stella-ops.org/stella-ops.org/git.stella-ops.org
cd git.stella-ops.org

# Verify .NET SDK
dotnet --version
# Expected: 10.0.0 or later
```

---

## Building Regional Distributions

### 1. International Distribution (Default)

**Includes:** Default crypto providers only (no regional algorithms)

**Build Command:**
```bash
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime linux-x64 \
  --self-contained true \
  --output dist/stella-international-linux-x64
```

**Supported Platforms:**
- `linux-x64` - Linux x86_64
- `linux-arm64` - Linux ARM64
- `osx-x64` - macOS Intel
- `osx-arm64` - macOS Apple Silicon
- `win-x64` - Windows x64

**Example (all platforms):**
```bash
# Linux x64
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime linux-x64 \
  --self-contained true \
  --output dist/stella-international-linux-x64

# Linux ARM64
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime linux-arm64 \
  --self-contained true \
  --output dist/stella-international-linux-arm64

# macOS Intel
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime osx-x64 \
  --self-contained true \
  --output dist/stella-international-osx-x64

# macOS Apple Silicon
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime osx-arm64 \
  --self-contained true \
  --output dist/stella-international-osx-arm64

# Windows x64
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime win-x64 \
  --self-contained true \
  --output dist/stella-international-win-x64
```

---

### 2. Russia Distribution (GOST)

**Includes:** Default + GOST crypto providers

**Build Command:**
```bash
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime linux-x64 \
  --self-contained true \
  -p:StellaOpsEnableGOST=true \
  -p:DefineConstants="STELLAOPS_ENABLE_GOST" \
  --output dist/stella-russia-linux-x64
```

**Important:** The build flag `StellaOpsEnableGOST=true` conditionally includes GOST plugin projects, and `DefineConstants` enables `#if STELLAOPS_ENABLE_GOST` preprocessor directives.

**Multi-platform Example:**
```bash
#!/bin/bash
# build-russia.sh - Build all Russia distributions

set -e

RUNTIMES=("linux-x64" "linux-arm64" "osx-x64" "osx-arm64" "win-x64")

for runtime in "${RUNTIMES[@]}"; do
  echo "Building stella-russia for $runtime..."
  dotnet publish src/Cli/StellaOps.Cli \
    --configuration Release \
    --runtime "$runtime" \
    --self-contained true \
    -p:StellaOpsEnableGOST=true \
    -p:DefineConstants="STELLAOPS_ENABLE_GOST" \
    --output "dist/stella-russia-$runtime"
done

echo "All Russia distributions built successfully"
```

---

### 3. EU Distribution (eIDAS)

**Includes:** Default + eIDAS crypto providers

**Build Command:**
```bash
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime linux-x64 \
  --self-contained true \
  -p:StellaOpsEnableEIDAS=true \
  -p:DefineConstants="STELLAOPS_ENABLE_EIDAS" \
  --output dist/stella-eu-linux-x64
```

**Multi-platform Example:**
```bash
#!/bin/bash
# build-eu.sh - Build all EU distributions

set -e

RUNTIMES=("linux-x64" "linux-arm64" "osx-x64" "osx-arm64" "win-x64")

for runtime in "${RUNTIMES[@]}"; do
  echo "Building stella-eu for $runtime..."
  dotnet publish src/Cli/StellaOps.Cli \
    --configuration Release \
    --runtime "$runtime" \
    --self-contained true \
    -p:StellaOpsEnableEIDAS=true \
    -p:DefineConstants="STELLAOPS_ENABLE_EIDAS" \
    --output "dist/stella-eu-$runtime"
done

echo "All EU distributions built successfully"
```

---

### 4. China Distribution (SM)

**Includes:** Default + SM crypto providers

**Build Command:**
```bash
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime linux-x64 \
  --self-contained true \
  -p:StellaOpsEnableSM=true \
  -p:DefineConstants="STELLAOPS_ENABLE_SM" \
  --output dist/stella-china-linux-x64
```

**Multi-platform Example:**
```bash
#!/bin/bash
# build-china.sh - Build all China distributions

set -e

RUNTIMES=("linux-x64" "linux-arm64" "osx-x64" "osx-arm64" "win-x64")

for runtime in "${RUNTIMES[@]}"; do
  echo "Building stella-china for $runtime..."
  dotnet publish src/Cli/StellaOps.Cli \
    --configuration Release \
    --runtime "$runtime" \
    --self-contained true \
    -p:StellaOpsEnableSM=true \
    -p:DefineConstants="STELLAOPS_ENABLE_SM" \
    --output "dist/stella-china-$runtime"
done

echo "All China distributions built successfully"
```

---

## Build All Distributions

**Automated build script:**

```bash
#!/bin/bash
# build-all.sh - Build all distributions for all platforms

set -e

DISTRIBUTIONS=("international" "russia" "eu" "china")
RUNTIMES=("linux-x64" "linux-arm64" "osx-x64" "osx-arm64" "win-x64")

build_distribution() {
    local dist=$1
    local runtime=$2
    local flags=""

    case $dist in
        "russia")
            flags="-p:StellaOpsEnableGOST=true -p:DefineConstants=STELLAOPS_ENABLE_GOST"
            ;;
        "eu")
            flags="-p:StellaOpsEnableEIDAS=true -p:DefineConstants=STELLAOPS_ENABLE_EIDAS"
            ;;
        "china")
            flags="-p:StellaOpsEnableSM=true -p:DefineConstants=STELLAOPS_ENABLE_SM"
            ;;
    esac

    echo "Building stella-$dist for $runtime..."

    dotnet publish src/Cli/StellaOps.Cli \
        --configuration Release \
        --runtime "$runtime" \
        --self-contained true \
        $flags \
        --output "dist/stella-$dist-$runtime"

    # Create tarball (except Windows)
    if [[ ! $runtime =~ ^win ]]; then
        tar -czf "dist/stella-$dist-$runtime.tar.gz" -C "dist/stella-$dist-$runtime" .
        echo "✅ Created dist/stella-$dist-$runtime.tar.gz"
    else
        # Create zip for Windows
        (cd "dist/stella-$dist-$runtime" && zip -r "../stella-$dist-$runtime.zip" .)
        echo "✅ Created dist/stella-$dist-$runtime.zip"
    fi
}

for dist in "${DISTRIBUTIONS[@]}"; do
    for runtime in "${RUNTIMES[@]}"; do
        build_distribution "$dist" "$runtime"
    done
done

echo ""
echo "🎉 All distributions built successfully!"
echo "See dist/ directory for artifacts"
```

---

## Distribution Validation

### Automated Validation Script

```bash
#!/bin/bash
# validate-distribution.sh - Validate distribution has correct plugins

set -e

DISTRIBUTION=$1  # international, russia, eu, china
BINARY_PATH=$2

if [ -z "$DISTRIBUTION" ] || [ -z "$BINARY_PATH" ]; then
    echo "Usage: $0 <distribution> <binary-path>"
    echo "Example: $0 russia dist/stella-russia-linux-x64/stella"
    exit 1
fi

echo "Validating $DISTRIBUTION distribution: $BINARY_PATH"
echo ""

# Function to check for symbol in binary
has_symbol() {
    local symbol=$1
    if command -v objdump &> /dev/null; then
        objdump -p "$BINARY_PATH" 2>/dev/null | grep -q "$symbol"
    elif command -v nm &> /dev/null; then
        nm "$BINARY_PATH" 2>/dev/null | grep -q "$symbol"
    else
        # Fallback: check if binary contains string
        strings "$BINARY_PATH" 2>/dev/null | grep -q "$symbol"
    fi
}

# Validation rules
validate_international() {
    echo "Checking International distribution..."

    # Should NOT contain regional plugins
    if has_symbol "GostCryptoProvider" || \
       has_symbol "EidasCryptoProvider" || \
       has_symbol "SmCryptoProvider"; then
        echo "❌ FAIL: International distribution contains restricted plugins"
        return 1
    fi

    echo "✅ PASS: International distribution valid (no restricted plugins)"
    return 0
}

validate_russia() {
    echo "Checking Russia distribution..."

    # Should contain GOST
    if ! has_symbol "GostCryptoProvider"; then
        echo "❌ FAIL: Russia distribution missing GOST plugin"
        return 1
    fi

    # Should NOT contain eIDAS or SM
    if has_symbol "EidasCryptoProvider" || has_symbol "SmCryptoProvider"; then
        echo "❌ FAIL: Russia distribution contains non-GOST regional plugins"
        return 1
    fi

    echo "✅ PASS: Russia distribution valid (GOST included, no other regional plugins)"
    return 0
}

validate_eu() {
    echo "Checking EU distribution..."

    # Should contain eIDAS
    if ! has_symbol "EidasCryptoProvider"; then
        echo "❌ FAIL: EU distribution missing eIDAS plugin"
        return 1
    fi

    # Should NOT contain GOST or SM
    if has_symbol "GostCryptoProvider" || has_symbol "SmCryptoProvider"; then
        echo "❌ FAIL: EU distribution contains non-eIDAS regional plugins"
        return 1
    fi

    echo "✅ PASS: EU distribution valid (eIDAS included, no other regional plugins)"
    return 0
}

validate_china() {
    echo "Checking China distribution..."

    # Should contain SM
    if ! has_symbol "SmCryptoProvider"; then
        echo "❌ FAIL: China distribution missing SM plugin"
        return 1
    fi

    # Should NOT contain GOST or eIDAS
    if has_symbol "GostCryptoProvider" || has_symbol "EidasCryptoProvider"; then
        echo "❌ FAIL: China distribution contains non-SM regional plugins"
        return 1
    fi

    echo "✅ PASS: China distribution valid (SM included, no other regional plugins)"
    return 0
}

# Run validation
case $DISTRIBUTION in
    "international")
        validate_international
        ;;
    "russia")
        validate_russia
        ;;
    "eu")
        validate_eu
        ;;
    "china")
        validate_china
        ;;
    *)
        echo "❌ ERROR: Unknown distribution '$DISTRIBUTION'"
        echo "Valid distributions: international, russia, eu, china"
        exit 1
        ;;
esac

exit $?
```

**Usage:**
```bash
# Validate Russia distribution
./validate-distribution.sh russia dist/stella-russia-linux-x64/stella

# Output:
# Validating russia distribution: dist/stella-russia-linux-x64/stella
#
# Checking Russia distribution...
# ✅ PASS: Russia distribution valid (GOST included, no other regional plugins)
```

---

### Runtime Validation

Verify correct plugins are available at runtime:

```bash
# International distribution
./stella crypto providers
# Expected output:
# Available Crypto Providers:
# - default (.NET Crypto, BouncyCastle)

# Russia distribution
./stella crypto providers
# Expected output:
# Available Crypto Providers:
# - default (.NET Crypto, BouncyCastle)
# - gost (GOST R 34.10-2012, GOST R 34.11-2012)

# EU distribution
./stella crypto providers
# Expected output:
# Available Crypto Providers:
# - default (.NET Crypto, BouncyCastle)
# - eidas (QES, AES, AdES)

# China distribution
./stella crypto providers
# Expected output:
# Available Crypto Providers:
# - default (.NET Crypto, BouncyCastle)
# - sm (SM2, SM3, SM4)
```

---

## Packaging

### Tarball Creation

```bash
#!/bin/bash
# package.sh - Create distribution tarballs

DIST=$1  # stella-russia-linux-x64
OUTPUT_DIR="dist"

cd "$OUTPUT_DIR/$DIST"

# Create tarball
tar -czf "../$DIST.tar.gz" .

echo "✅ Created $OUTPUT_DIR/$DIST.tar.gz"
```

### Checksums

```bash
#!/bin/bash
# checksums.sh - Generate checksums for all distributions

cd dist

for tarball in *.tar.gz *.zip; do
    if [ -f "$tarball" ]; then
        sha256sum "$tarball" >> checksums.txt
    fi
done

echo "✅ Checksums written to dist/checksums.txt"
cat dist/checksums.txt
```

---

## CI/CD Integration

### GitHub Actions / Gitea Actions

```yaml
name: Build and Release CLI

on:
  push:
    tags:
      - 'v*'

jobs:
  build-matrix:
    strategy:
      matrix:
        distribution: [international, russia, eu, china]
        runtime: [linux-x64, linux-arm64, osx-x64, osx-arm64, win-x64]

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '10.0.x'

      - name: Build Distribution
        run: |
          FLAGS=""
          case "${{ matrix.distribution }}" in
            "russia")
              FLAGS="-p:StellaOpsEnableGOST=true -p:DefineConstants=STELLAOPS_ENABLE_GOST"
              ;;
            "eu")
              FLAGS="-p:StellaOpsEnableEIDAS=true -p:DefineConstants=STELLAOPS_ENABLE_EIDAS"
              ;;
            "china")
              FLAGS="-p:StellaOpsEnableSM=true -p:DefineConstants=STELLAOPS_ENABLE_SM"
              ;;
          esac

          dotnet publish src/Cli/StellaOps.Cli \
            --configuration Release \
            --runtime ${{ matrix.runtime }} \
            --self-contained true \
            $FLAGS \
            --output dist/stella-${{ matrix.distribution }}-${{ matrix.runtime }}

      - name: Validate Distribution
        run: |
          chmod +x scripts/validate-distribution.sh
          ./scripts/validate-distribution.sh \
            ${{ matrix.distribution }} \
            dist/stella-${{ matrix.distribution }}-${{ matrix.runtime }}/stella

      - name: Create Tarball
        if: ${{ !contains(matrix.runtime, 'win') }}
        run: |
          cd dist/stella-${{ matrix.distribution }}-${{ matrix.runtime }}
          tar -czf ../stella-${{ matrix.distribution }}-${{ matrix.runtime }}.tar.gz .

      - name: Upload Artifact
        uses: actions/upload-artifact@v4
        with:
          name: stella-${{ matrix.distribution }}-${{ matrix.runtime }}
          path: dist/stella-${{ matrix.distribution }}-${{ matrix.runtime }}.tar.gz
```

---

## Distribution Deployment

### Release Structure

```
releases/
├── v2.1.0/
│   ├── stella-international-linux-x64.tar.gz
│   ├── stella-international-linux-arm64.tar.gz
│   ├── stella-international-osx-x64.tar.gz
│   ├── stella-international-osx-arm64.tar.gz
│   ├── stella-international-win-x64.zip
│   ├── stella-russia-linux-x64.tar.gz
│   ├── stella-russia-linux-arm64.tar.gz
│   ├── stella-russia-osx-x64.tar.gz
│   ├── stella-russia-osx-arm64.tar.gz
│   ├── stella-russia-win-x64.zip
│   ├── stella-eu-linux-x64.tar.gz
│   ├── stella-eu-linux-arm64.tar.gz
│   ├── stella-eu-osx-x64.tar.gz
│   ├── stella-eu-osx-arm64.tar.gz
│   ├── stella-eu-win-x64.zip
│   ├── stella-china-linux-x64.tar.gz
│   ├── stella-china-linux-arm64.tar.gz
│   ├── stella-china-osx-x64.tar.gz
│   ├── stella-china-osx-arm64.tar.gz
│   ├── stella-china-win-x64.zip
│   ├── checksums.txt
│   └── RELEASE_NOTES.md
└── latest -> v2.1.0
```

---

## Download Links

**Public Release Server:**
```
https://releases.stella-ops.org/cli/
├── latest/
│   ├── stella-international-linux-x64.tar.gz
│   ├── stella-russia-linux-x64.tar.gz
│   ├── stella-eu-linux-x64.tar.gz
│   └── stella-china-linux-x64.tar.gz
├── v2.1.0/
├── v2.0.0/
└── checksums.txt
```

**User Installation:**
```bash
# International (unrestricted)
wget https://releases.stella-ops.org/cli/latest/stella-international-linux-x64.tar.gz

# Russia (GOST)
wget https://releases.stella-ops.org/cli/russia/latest/stella-russia-linux-x64.tar.gz

# EU (eIDAS)
wget https://releases.stella-ops.org/cli/eu/latest/stella-eu-linux-x64.tar.gz

# China (SM)
wget https://releases.stella-ops.org/cli/china/latest/stella-china-linux-x64.tar.gz
```

---

## Legal & Export Control

### Export Control Statement

> StellaOps CLI regional distributions contain cryptographic software subject to export control laws.
>
> - **stella-international**: No export restrictions (standard commercial crypto)
> - **stella-russia**: Authorized for Russia and CIS states only
> - **stella-eu**: Authorized for EU/EEA member states only
> - **stella-china**: Authorized for China only
>
> Unauthorized export, re-export, or transfer may violate applicable laws. Users are responsible for compliance with export control regulations in their jurisdiction.

### License Compliance

All distributions are licensed under **AGPL-3.0-or-later**, with regional plugins subject to additional vendor licenses (e.g., CryptoPro CSP requires commercial license).

---

## See Also

- [CLI Overview](README.md) - Installation and quick start
- [CLI Architecture](architecture.md) - Plugin architecture
- [Command Reference](command-reference.md) - Command usage
- [Compliance Guide](compliance-guide.md) - Regional compliance requirements
- [Crypto Plugins](crypto-plugins.md) - Plugin development
- [Troubleshooting](troubleshooting.md) - Build and validation issues