proofmode 0.9.0

# ProofMode Package Distribution

This document describes how ProofMode packages are built and distributed through GitLab CI/CD.

## Supported Package Registries

GitLab Package Registry supports the following package types that ProofMode uses:

1. **PyPI (Python)** - Python packages
2. **NPM (Node.js)** - JavaScript/TypeScript packages  
3. **Maven (Android)** - Android AAR packages
4. **Container Registry (Docker)** - Docker images

## Package Installation

### Python Package

Install from GitLab PyPI registry:

```bash
# Configure pip to use GitLab registry
pip install --index-url https://gitlab.com/api/v4/projects/PROJECT_ID/packages/pypi/simple proofmode

# Or add to requirements.txt
--index-url https://gitlab.com/api/v4/projects/PROJECT_ID/packages/pypi/simple
proofmode
```

### NPM Package

Install from GitLab NPM registry:

```bash
# Configure npm to use GitLab registry
npm config set @guardianproject:registry https://gitlab.com/api/v4/projects/PROJECT_ID/packages/npm/

# Install the package
npm install @guardianproject/proofmode

# Or add to package.json
"dependencies": {
  "@guardianproject/proofmode": "^0.8.0"
}
```

### Android AAR (Maven)

Add to your `build.gradle`:

```gradle
repositories {
    maven {
        url "https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven"
        credentials(HttpHeaderCredentials) {
            name = "Private-Token"
            value = "YOUR_PERSONAL_ACCESS_TOKEN"
        }
        authentication {
            header(HttpHeaderAuthentication)
        }
    }
}

dependencies {
    implementation 'org.guardianproject.proofmode:proofmode-android:0.8.4'
}
```

### Docker Image

Pull from GitLab Container Registry:

```bash
# Login to GitLab registry
docker login registry.gitlab.com

# Pull the image
docker pull registry.gitlab.com/guardianproject/proofmode/proofmode-rust:latest

# Or use a specific version
docker pull registry.gitlab.com/guardianproject/proofmode/proofmode-rust:latest
```

## Additional Package Registries

### Ruby Gem

Ruby gems are automatically published to RubyGems.org on tagged releases.

```bash
gem install proofmode
```

### Rust Crate

Rust crates are automatically published to crates.io on tagged releases.

```bash
cargo install proofmode
```

## CI/CD Pipeline

The GitLab CI pipeline automatically:

1. **On every push to main**:
   - Builds Rust, Python, Ruby, NPM, and Docker packages
   - Runs tests and linting

2. **On tagged releases**:
   - All of the above
   - Builds Android AAR (4 architectures)
   - Publishes to all registries (PyPI, NPM, Maven, crates.io, RubyGems.org, Container Registry)
   - Creates a GitLab release with artifacts

## Authentication

### For Public Packages

Most packages can be installed without authentication if the project is public.

### For Private Projects

You'll need a GitLab personal access token with appropriate scopes:

1. Go to GitLab → User Settings → Access Tokens
2. Create a token with `read_package_registry` scope
3. Use this token for authentication

### In CI/CD

The CI pipeline uses the built-in `CI_JOB_TOKEN` for authentication, which has automatic access to the project's package registry.

## Version Management

Package versions follow this scheme:

- **Tagged releases**: Use the tag version (e.g., `v0.8.4` -> `0.8.4`)

## Package Contents

Each package includes:

- **Python**: Full Python bindings with UniFFI-generated code
- **NPM**: WASM module with TypeScript definitions
- **Android**: AAR with Kotlin bindings and native libraries for all architectures
- **Docker**: Complete ProofMode CLI environment
- **Ruby**: Gem with FFI bindings published to RubyGems.org
- **Rust**: Crate published to crates.io

## Troubleshooting

### Authentication Issues

If you get 401 Unauthorized errors:
- Ensure your access token has the correct scopes
- Check that the token hasn't expired
- Verify the project ID in the registry URL

### Package Not Found

If packages aren't available:
- Check the CI pipeline succeeded
- Verify you're using the correct registry URL
- Ensure the package was published (check Package Registry in GitLab)

### Version Conflicts

If you have version conflicts:
- Clear your local package cache
- Use exact version specifications
- Check for conflicting registry configurations

## Local Development

To test packages locally before publishing:

```bash
# Python
cd cli/python
python setup.py sdist bdist_wheel
pip install dist/proofmode-*.whl

# Ruby
cd ruby
gem build proofmode.gemspec
gem install proofmode-*.gem

# NPM
cd pkg
npm pack
npm install guardianproject-proofmode-*.tgz

# Android
cd target/aar
# Copy to your Android project's libs folder
```