proofmode 0.8.2

# 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-uniffi`
- **Installation**: `pip install dist/proofmode_uniffi-0.4.0-py3-none-any.whl`
- **Binary**: `proofmode-uniffi`

### 3. Ruby CLI
- **Status**: ✅ Functional (requires FFI gem)
- **Installation**: `gem install proofmode-*.gem`
- **Binary**: `proofmode`
- **Requirement**: Ruby development headers for FFI

### 4. Node.js CLI
- **Status**: ⚠️ WASM integration issues
- **Package**: `@guardianproject/proofmode-cli`
- **Binary**: `proofmode`
- **Known Issue**: WASM module initialization failure

## Common Commands

All CLIs support the same core commands:

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

# Python
proofmode-uniffi --version

# Ruby
proofmode --version

# Node.js (when working)
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 (when working)
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 (when working)
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 | ✅ | ✅ | ✅ | ⚠️ |
| Generate Proof | ✅ | ✅ | ✅ | ⚠️ |
| Check Files | ✅ | ✅ | ✅ | ⚠️ |
| PGP Signing | ✅ | ✅ | ✅ | ❌ |
| Check URLs | ✅ | ❌ | ❌ | ⚠️ |
| Check CIDs | ✅ | ❌ | ❌ | ⚠️ |
| Progress Reporting | ✅ | ✅ | ✅ | ✅ |
| JSON Output | ✅ | ✅ | ❌ | ✅ |

## Platform-Specific Notes

### Python
- Uses UniFFI bindings with async/await wrappers
- Rich terminal output with progress bars
- Includes native library in wheel package

### Ruby
- Requires FFI gem and Ruby development headers
- Uses UniFFI-generated FFI bindings
- May need RVM or similar for proper Ruby environment

### Node.js
- Uses WebAssembly (WASM) for browser compatibility
- Currently has initialization issues with externref tables
- PGP functionality must come from Rust library (not yet implemented in WASM)

## 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 --features cli

# Python package
cd python-uniffi
python setup.py bdist_wheel

# Ruby gem
cd ruby-uniffi
gem build proofmode.gemspec

# Node.js package
cargo make wasm-pack
cd npm
npm pack
```

## Testing

A cross-platform test suite is available:
```bash
./tests/cross_platform_cli_tests.sh
```

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

# Python
cd python-uniffi
python -m pytest

# Ruby
cd ruby-uniffi
ruby test/test_uniffi_bindings.rb

# Node.js
cd npm
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
- Current WASM initialization issue prevents functionality
- Check Node.js version supports required WebAssembly features
- Ensure `@guardianproject/proofmode` package is properly installed

## Known Limitations

1. **PGP in WASM**: The Node.js/WASM implementation expects JavaScript to provide PGP signing, but this should come from Rust
2. **Check command results**: Some platforms return empty results for the check command
3. **Platform features**: Not all platforms support all features (URLs, CIDs) yet

## Future Improvements

1. Fix Node.js WASM initialization issues
2. Implement internal PGP handling in WASM
3. Add URL and CID support to Python/Ruby CLIs
4. Improve error messages across all platforms
5. Add more comprehensive test coverage