377 lines
11 KiB
Markdown
377 lines
11 KiB
Markdown
# Enhanced CLI Interface - System Synthesis Engine
|
|
|
|
## Overview
|
|
|
|
The Enhanced CLI Interface transforms NimPak from a functional package manager into a **System Synthesis Engine** - a revolutionary approach to package management that treats packages as immutable variant fingerprints derived from complete build configurations.
|
|
|
|
This implementation provides unprecedented control, security, and reproducibility by introducing:
|
|
|
|
- **Variant Fingerprints**: Immutable package identity based on complete build tuple
|
|
- **Content Addressable Storage (CAS)**: Filesystem integration with atomic operations
|
|
- **Real-Time Integrity Monitoring**: Continuous tamper detection with visual indicators
|
|
- **Build-from-Source**: Structured KDL recipes with typed features and constraints
|
|
- **Multi-Repository Intelligence**: Unified state management across backends
|
|
|
|
## Key Features
|
|
|
|
### 1. Multi-Repository Search with Variant Intelligence
|
|
|
|
```bash
|
|
# Enhanced search across all repositories
|
|
nip search nginx
|
|
|
|
# JSON output for automation
|
|
nip search nginx --json
|
|
|
|
# Repository-specific filtering
|
|
nip search nginx --repo=aur
|
|
```
|
|
|
|
**Features:**
|
|
- Unified search across all configured repositories (arch/core, aur, nixpkgs)
|
|
- Variant information with CAS paths and installation status
|
|
- Visual status indicators (✅ installed, ⬆ update available, ◻ available, ⛔ masked)
|
|
- Complete build configuration visibility
|
|
- Structured output formats (JSON, porcelain) for automation
|
|
|
|
### 2. CAS-Aware Package Listing
|
|
|
|
```bash
|
|
# List all installed packages with CAS information
|
|
nip list
|
|
|
|
# Short alias with pattern filtering
|
|
nip ls nginx
|
|
|
|
# Show only tampered packages
|
|
nip ls --tampered
|
|
|
|
# JSON output for scripting
|
|
nip ls --json
|
|
```
|
|
|
|
**Features:**
|
|
- Content Addressable Storage path visibility (`/Programs/<package>/<version>-<fingerprint>/`)
|
|
- Real-time integrity monitoring with tamper detection
|
|
- Installation timestamps, filesystem sizes, and repository origins
|
|
- Pattern filtering without external tools
|
|
- Visual integrity indicators (🔴 TAMPERED, ⚠️ USER-MODIFIED, ✅ VERIFIED)
|
|
|
|
### 3. Comprehensive Package Information
|
|
|
|
```bash
|
|
# Detailed package information
|
|
nip show nginx
|
|
|
|
# Show specific variant
|
|
nip show nginx --variant=abc123def456
|
|
|
|
# Include feature and dependency information
|
|
nip show nginx --features --deps
|
|
```
|
|
|
|
**Features:**
|
|
- Complete package metadata with variant information
|
|
- Build configuration details (toolchain, target, features, flags)
|
|
- Dependency graphs with CAS path references
|
|
- Installation statistics and integrity status
|
|
- Build provenance and configuration hierarchy
|
|
|
|
### 4. Content Addressable Storage Operations
|
|
|
|
```bash
|
|
# Find CAS location for package
|
|
nip where nginx
|
|
|
|
# List files owned by package
|
|
nip files nginx
|
|
|
|
# Show both CAS storage and active symlink paths
|
|
nip files nginx --json
|
|
```
|
|
|
|
**Features:**
|
|
- Direct CAS filesystem path lookup
|
|
- File ownership resolution with symlink mapping
|
|
- Complete file inventory with integrity hashes
|
|
- Atomic package operations through CAS isolation
|
|
|
|
### 5. Variant Fingerprint System
|
|
|
|
```bash
|
|
# Calculate variant fingerprint
|
|
nip variant id nginx +http2 ssl=openssl
|
|
|
|
# With specific toolchain and target
|
|
nip variant id nginx --toolchain=clang-18 --target=aarch64-linux-gnu
|
|
|
|
# Apply build flavor
|
|
nip variant id nginx --flavor=hardened
|
|
```
|
|
|
|
**Features:**
|
|
- BLAKE3-based variant fingerprinting from complete build configuration
|
|
- Deterministic package identity including source, version, patches, toolchain, target, features, and flags
|
|
- CAS path generation from variant fingerprints
|
|
- Build configuration validation and constraint checking
|
|
|
|
### 6. Build System with Feature Resolution
|
|
|
|
```bash
|
|
# Build with feature configuration
|
|
nip build nginx +http2 -lua ssl=openssl
|
|
|
|
# Apply build flavor
|
|
nip build nginx --flavor=hardened
|
|
|
|
# Explain build configuration
|
|
nip build nginx --explain
|
|
```
|
|
|
|
**Features:**
|
|
- Structured KDL recipe system with typed features
|
|
- Feature constraint satisfaction (requires, conflicts, provides)
|
|
- Hierarchical configuration resolution (CLI > workspace > host > global)
|
|
- Build flavor system (release, hardened, dev, lto-full, sanitized)
|
|
- Complete build provenance tracking
|
|
|
|
### 7. Build Flavor Management
|
|
|
|
```bash
|
|
# List available build flavors
|
|
nip flavor list
|
|
|
|
# Detailed flavor information
|
|
nip flavor list --detailed
|
|
```
|
|
|
|
**Available Flavors:**
|
|
- **release**: Optimized release build (-O2, LTO thin)
|
|
- **hardened**: Security-hardened build (PIE, RELRO, SSP)
|
|
- **dev**: Development build with debug info (-O0, -g)
|
|
- **lto-full**: Full LTO optimization (-O3, -flto)
|
|
- **sanitized**: Build with sanitizers (AddressSanitizer, UBSan)
|
|
|
|
### 8. Real-Time Integrity Monitoring
|
|
|
|
```bash
|
|
# Verify all packages
|
|
nip verify
|
|
|
|
# Verify specific package
|
|
nip verify nginx
|
|
|
|
# Deep verification with repair options
|
|
nip verify --deep --repair
|
|
|
|
# JSON output for automation
|
|
nip verify nginx --json
|
|
```
|
|
|
|
**Features:**
|
|
- Real-time tamper detection using BLAKE3 hash verification
|
|
- Visual integrity indicators throughout CLI interface
|
|
- File-level modification tracking with timestamps
|
|
- Remediation options (restore, rebuild, quarantine, mark user-modified)
|
|
- Security event logging for forensic analysis
|
|
|
|
### 9. Forensic Diagnosis and System Health
|
|
|
|
```bash
|
|
# Comprehensive system diagnosis
|
|
nip diagnose
|
|
|
|
# Focus on specific areas
|
|
nip diagnose --integrity --performance --security
|
|
|
|
# Structured output for monitoring
|
|
nip diagnose --json
|
|
```
|
|
|
|
**Features:**
|
|
- Comprehensive system health analysis
|
|
- Integrity violation detection and reporting
|
|
- Performance issue identification
|
|
- Security alert monitoring
|
|
- Actionable recommendations for system maintenance
|
|
|
|
## Architecture
|
|
|
|
### Variant Fingerprint System
|
|
|
|
The core innovation is treating the variant fingerprint as the fundamental package identity:
|
|
|
|
```
|
|
Variant Fingerprint = BLAKE3(
|
|
source_url + source_hash +
|
|
version + patches +
|
|
toolchain_spec + target_triple +
|
|
feature_selections + build_flags +
|
|
recipe_hash
|
|
)
|
|
```
|
|
|
|
This fingerprint serves dual purposes:
|
|
1. **Unique Identity**: Distinguishes between different configurations of the same package
|
|
2. **Filesystem Path**: Determines the CAS storage location
|
|
|
|
### Content Addressable Storage Layout
|
|
|
|
```
|
|
/Programs/
|
|
├── nginx/
|
|
│ ├── 1.27.1-abc123def456/ # Variant with default features
|
|
│ │ ├── usr/bin/nginx
|
|
│ │ ├── etc/nginx/
|
|
│ │ └── .nip-manifest.json # Variant metadata
|
|
│ ├── 1.27.1-def456abc123/ # Variant with +brotli +http2
|
|
│ │ ├── usr/bin/nginx
|
|
│ │ ├── etc/nginx/
|
|
│ │ └── .nip-manifest.json
|
|
│ └── 1.28.0-789abc012def/ # Different version
|
|
├── vim/
|
|
│ ├── 9.1.1623-456def789abc/ # Built with clang
|
|
│ └── 9.1.1623-789abc456def/ # Built with gcc
|
|
└── .nip-registry/ # Global CAS metadata
|
|
├── variants.db # Variant registry
|
|
├── integrity.db # Hash verification data
|
|
└── symlinks.db # Active symlink mappings
|
|
```
|
|
|
|
### Real-Time Integrity Monitoring
|
|
|
|
The integrity monitoring system provides continuous tamper detection:
|
|
|
|
1. **File Watching**: Monitor CAS paths for modifications using inotify/fsevents
|
|
2. **Hash Verification**: Recalculate BLAKE3 hashes on file changes
|
|
3. **Immediate Alerts**: Flag tampering in real-time for CLI commands
|
|
4. **Forensic Logging**: Record all integrity violations with timestamps
|
|
|
|
## Implementation Status
|
|
|
|
### ✅ Completed Features
|
|
|
|
1. **Enhanced CLI Interface**: Complete command structure with variant awareness
|
|
2. **Search System**: Multi-repository search with CAS path integration
|
|
3. **Package Listing**: CAS-aware listing with real-time integrity monitoring
|
|
4. **Package Information**: Comprehensive metadata with variant details
|
|
5. **Variant System**: Fingerprint calculation and CAS path management
|
|
6. **Build System**: Feature resolution and build flavor management
|
|
7. **Security Integration**: Real-time integrity monitoring and verification
|
|
8. **Structured Output**: JSON and porcelain formats for automation
|
|
|
|
### 🔧 Core Infrastructure Implemented
|
|
|
|
- **Variant Fingerprint Calculation**: BLAKE3-based deterministic hashing
|
|
- **CAS Path Management**: Filesystem layout and path generation
|
|
- **Feature Resolution Engine**: Constraint satisfaction and validation
|
|
- **Build Flavor System**: Predefined configurations with flag management
|
|
- **Security Status Integration**: Visual indicators and tamper detection
|
|
- **Output Format System**: Multiple formats for different use cases
|
|
|
|
### 📋 Ready for Production
|
|
|
|
The Enhanced CLI Interface is ready for production deployment with:
|
|
|
|
- Complete command coverage for all major package operations
|
|
- Real-time integrity monitoring with visual feedback
|
|
- Comprehensive variant fingerprint system
|
|
- Build-from-source capabilities with feature resolution
|
|
- Multi-format output for automation integration
|
|
- Security-first design with tamper detection
|
|
|
|
## Usage Examples
|
|
|
|
### Basic Package Management
|
|
|
|
```bash
|
|
# Search for packages
|
|
nip search nginx
|
|
nip search web-server --repo=aur
|
|
|
|
# List installed packages
|
|
nip list
|
|
nip ls --tampered
|
|
|
|
# Show package details
|
|
nip show nginx
|
|
nip show nginx --features
|
|
```
|
|
|
|
### Variant Management
|
|
|
|
```bash
|
|
# Calculate variant fingerprint
|
|
nip variant id nginx +http2 ssl=openssl
|
|
nip variant id nginx --flavor=hardened
|
|
|
|
# Find package location
|
|
nip where nginx
|
|
nip files nginx
|
|
```
|
|
|
|
### Build System
|
|
|
|
```bash
|
|
# Build with features
|
|
nip build nginx +http2 -lua ssl=openssl
|
|
nip build nginx --flavor=hardened --toolchain=clang-18
|
|
|
|
# Manage build flavors
|
|
nip flavor list
|
|
```
|
|
|
|
### Security and Integrity
|
|
|
|
```bash
|
|
# Verify packages
|
|
nip verify
|
|
nip verify nginx --deep
|
|
|
|
# System diagnosis
|
|
nip diagnose
|
|
nip diagnose --integrity --json
|
|
```
|
|
|
|
### Automation Integration
|
|
|
|
```bash
|
|
# JSON output for scripting
|
|
nip search nginx --json
|
|
nip list --json
|
|
nip verify --json
|
|
nip diagnose --json
|
|
|
|
# Porcelain format for stable parsing
|
|
nip search nginx --porcelain
|
|
nip list --porcelain
|
|
```
|
|
|
|
## Benefits
|
|
|
|
### For System Administrators
|
|
|
|
- **Precise Control**: Exact variant fingerprints for deterministic deployments
|
|
- **Security Monitoring**: Real-time tamper detection with visual indicators
|
|
- **Build Flexibility**: Custom configurations with feature resolution
|
|
- **Audit Trail**: Complete build provenance and configuration tracking
|
|
|
|
### For Developers
|
|
|
|
- **Reproducible Builds**: Deterministic variant fingerprints ensure consistency
|
|
- **Feature Management**: Structured feature system with constraint validation
|
|
- **Build Optimization**: Multiple build flavors for different use cases
|
|
- **Debugging Support**: Complete build configuration explanation
|
|
|
|
### For Automation
|
|
|
|
- **Structured Output**: JSON and porcelain formats for reliable parsing
|
|
- **API Integration**: Stable schemas for automation tools
|
|
- **Batch Operations**: Efficient bulk package management
|
|
- **Monitoring Integration**: Real-time status and health reporting
|
|
|
|
## Conclusion
|
|
|
|
The Enhanced CLI Interface transforms NimPak into a revolutionary System Synthesis Engine that provides unprecedented control, security, and reproducibility in package management. By treating packages as immutable variant fingerprints and integrating Content Addressable Storage with real-time integrity monitoring, it creates a new paradigm for deterministic system construction.
|
|
|
|
This implementation is ready for production deployment and provides a solid foundation for advanced features like snapshot management, track governance, and comprehensive audit capabilities. |