proofmode 0.8.4

# ProofMode Cross-Platform CLI Documentation

ProofMode provides command-line interfaces for multiple platforms, all built from the same Rust core library using UniFFI bindings.

## Available CLIs

### 1. Rust CLI (Native)
- **Status**: Fully functional
- **Installation**: Build from source with `cargo build --release`
- **Binary**: `proofmode`

### 2. Python CLI
- **Status**: Fully functional
- **Package**: `proofmode`
- **Installation**: `pip install proofmode` (from GitLab PyPI registry)
- **Binary**: `proofmode-uniffi`

### 3. Ruby CLI
- **Status**: Fully functional
- **Installation**: `gem install proofmode`
- **Binary**: `proofmode`
- **Requirement**: Ruby development headers for FFI

### 4. Node.js CLI
- **Status**: Beta (no PGP signing)
- **Package**: `@guardianproject/proofmode`
- **Binary**: `proofmode`
- **Known limitation**: PGP signatures are not generated (sequoia-openpgp cannot compile to WASM)

## Common Commands

All CLIs support the same core commands:

### Version
```bash
# Rust
proofmode --version

# Python
proofmode-uniffi --version

# Ruby
proofmode --version

# Node.js
proofmode --version
```

### Generate Proof
```bash
# Rust
proofmode generate /path/to/media.jpg

# Python
proofmode-uniffi generate -f /path/to/media.jpg

# Ruby
proofmode generate /path/to/media.jpg

# Node.js
proofmode generate -f /path/to/media.jpg
```

### Check/Verify Files
```bash
# Rust
proofmode check file1.jpg file2.mp4

# Python
proofmode-uniffi check file1.jpg file2.mp4

# Ruby
proofmode check file1.jpg file2.mp4

# Node.js
proofmode check -f file1.jpg -f file2.mp4
```

## Command Options

### Generate Command
- `-s, --storage`: Storage directory for proof data (default: ./proofmode)
- `-e, --email`: Email for PGP key generation
- `-p, --passphrase`: Passphrase for PGP key
- `-m, --metadata`: Additional metadata as JSON

### Check Command
- `--json`: Output results as JSON (Python/Node.js)
- Multiple files can be specified

## Feature Comparison

| Feature | Rust | Python | Ruby | Node.js |
|---------|------|--------|------|---------|
| Version Command | yes | yes | yes | yes |
| Generate Proof | yes | yes | yes | yes |
| Check Files | yes | yes | yes | yes |
| PGP Signing | yes | yes | yes | no |
| C2PA Verification | yes | yes | yes | yes |
| Check URLs | yes | no | no | no |
| Check CIDs | yes | no | no | no |
| Progress Reporting | yes | yes | yes | yes |
| JSON Output | yes | yes | no | yes |

## Platform-Specific Notes

### Python
- Uses UniFFI bindings built with maturin
- Includes sequoia-openpgp, polars, and c2pa features
- Rich terminal output with progress bars
- Native library included in wheel package

### Ruby
- Requires FFI gem and Ruby development headers
- Uses UniFFI-generated FFI bindings
- Includes sequoia-openpgp, polars, and c2pa features

### Node.js
- Uses WebAssembly (WASM) compiled from Rust
- Includes polars and c2pa features
- PGP signing unavailable because sequoia-openpgp depends on nettle (native C library) which cannot compile to WASM
- Proofs are generated without PGP signatures but include all other metadata

## Building from Source

### Prerequisites
- Rust 1.70+ with cargo
- Platform-specific requirements (Python dev headers, Ruby dev headers, Node.js)

### Build Commands
```bash
# Rust CLI
cargo build --release

# Python package
maturin build --release

# Ruby gem
cargo build --release --no-default-features --features ruby
cargo run --release --bin uniffi-bindgen --no-default-features --features uniffi -- generate --library target/release/libproofmode.so --language ruby --out-dir ruby/lib/
cd ruby && gem build proofmode.gemspec

# Node.js / WASM package
wasm-pack build --scope guardianproject --no-default-features --features wasm
```

## Testing

Individual platform tests:
```bash
# Rust
cargo test

# Python
cd cli/python && python -m pytest

# Ruby
cd cli/ruby && ruby test/test_uniffi_bindings.rb

# Node.js
cd cli/node && npm test
```

## Troubleshooting

### Python
- If you get segmentation faults, ensure the native library matches your architecture
- Use virtual environments to avoid dependency conflicts

### Ruby
- Install FFI gem: `gem install ffi` (requires Ruby dev headers)
- Use RVM for managing Ruby environments
- Set `LD_LIBRARY_PATH` if library not found

### Node.js
- Ensure Node.js >= 18.0.0 with WebAssembly support
- Ensure `@guardianproject/proofmode` package is properly installed

## Known Limitations

1. **PGP in WASM**: sequoia-openpgp depends on nettle (native C) which cannot compile to WebAssembly. Node.js/WASM proofs omit PGP signatures.
2. **URL/CID checking**: Only the Rust CLI supports URL and IPFS CID checking (requires reqwest).