nip/docs/enhanced-cli-interface.md

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# Verify packages
nip verify
nip verify nginx --deep

# System diagnosis
nip diagnose
nip diagnose --integrity --json

Automation Integration

# 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.