apt-ostree/docs/apt-ostree-daemon-plan/development-commands-analysis.md

# Development Commands Analysis: rpm-ostree Integration

## Overview

This document analyzes the missing development and debugging commands from rpm-ostree that should be integrated into apt-ostree. These commands are marked with `RPM_OSTREE_BUILTIN_FLAG_HIDDEN` and are essential for development, testing, and debugging purposes.

## Commands Analysis

### 1. testutils Command

**Purpose**: Development debugging tool for testing and development workflows.

**Flags**: `RPM_OSTREE_BUILTIN_FLAG_LOCAL_CMD | RPM_OSTREE_BUILTIN_FLAG_HIDDEN`

**Subcommands**:
- `inject-pkglist` - Inject package list metadata into OSTree commits
- `script-shell` - Run scripts in bubblewrap containers
- `generate-synthetic-upgrade` - Generate synthetic OS updates by modifying ELF files
- `integration-read-only` - Run integration tests on booted machine
- `c-units` - Run C unit tests
- `moo` - Test command for development verification

**Implementation Details**:

#### C++ Side (rpmostree-builtin-testutils.cxx)
```cpp
// inject-pkglist: Creates new commit with pkglist metadata
// - Reads existing commit
// - Creates RPM database package list
// - Writes new commit with pkglist metadata
// - Updates ref to point to new commit

// script-shell: Runs scripts in isolated containers
// - Uses bubblewrap for containerization
// - Mounts root filesystem
// - Executes test scripts safely
```

#### Rust Side (testutils.rs)
```rust
// generate-synthetic-upgrade: Modifies ELF binaries
// - Finds ELF files in system directories
// - Mutates specified percentage of binaries
// - Creates new OSTree commit with modified files
// - Useful for testing upgrade paths

// integration-read-only: Validates system state
// - Tests status JSON parsing
// - Validates package variants
// - Ensures client bindings work correctly
```

**Integration Plan for apt-ostree**:
1. Create `src/commands/testutils.rs` module
2. Implement all subcommands with APT equivalents
3. Add to CLI with hidden flag
4. Integrate with existing command structure

### 2. shlib-backend Command

**Purpose**: Shared library backend for IPC operations and package management.

**Flags**: `RPM_OSTREE_BUILTIN_FLAG_LOCAL_CMD | RPM_OSTREE_BUILTIN_FLAG_HIDDEN`

**Subcommands**:
- `get-basearch` - Get base architecture
- `varsubst-basearch` - Variable substitution for architecture
- `packagelist-from-commit` - Extract package list from OSTree commit

**Implementation Details**:
```cpp
// IPC-based communication using Unix domain sockets
// - Creates sealed memfd for data transfer
// - Uses DNF context for package operations
// - Integrates with OSTree repository operations
// - Handles package list extraction and formatting
```

**Integration Plan for apt-ostree**:
1. Create `src/commands/shlib_backend.rs` module
2. Replace DNF with APT equivalents
3. Implement IPC communication layer
4. Add architecture detection and variable substitution
5. Integrate with OSTree operations

### 3. internals Command

**Purpose**: Internal system commands for advanced operations.

**Status**: Referenced in header file but implementation not found in current rpm-ostree source.

**Flags**: Not specified (likely `RPM_OSTREE_BUILTIN_FLAG_LOCAL_CMD`)

**Integration Plan for apt-ostree**:
1. Research if this command exists in newer rpm-ostree versions
2. If not implemented, consider what internal operations would be useful
3. Implement as placeholder for future development
4. Add to CLI with appropriate flags

## Implementation Strategy

### Phase 1: Core Infrastructure
1. **Command Structure**: Add hidden command support to CLI
2. **Flag System**: Implement `APT_OSTREE_BUILTIN_FLAG_HIDDEN` equivalent
3. **Module Organization**: Create development commands module

### Phase 2: testutils Implementation
1. **inject-pkglist**: APT package list injection
2. **script-shell**: Bubblewrap container execution
3. **synthetic-upgrade**: ELF binary modification for testing
4. **integration-tests**: System validation and testing

### Phase 3: shlib-backend Implementation
1. **IPC Layer**: Unix domain socket communication
2. **Package Operations**: APT-based package management
3. **Architecture Detection**: Debian architecture handling
4. **Variable Substitution**: APT-specific variable handling

### Phase 4: Integration and Testing
1. **Command Registration**: Add to main command dispatch
2. **Hidden Flag Support**: Implement in CLI help system
3. **Testing Framework**: Integration with existing test suite
4. **Documentation**: Developer and testing guides

## Technical Considerations

### APT vs DNF Differences
- **Package Format**: DEB vs RPM
- **Database Structure**: APT cache vs DNF sack
- **Architecture Names**: Debian vs Red Hat conventions
- **Variable Substitution**: APT-specific variables

### OSTree Integration
- **Package Metadata**: APT package list format
- **Commit Structure**: OSTree commit metadata
- **Repository Operations**: OSTree repo integration
- **Deployment Management**: System deployment handling

### Security and Isolation
- **Bubblewrap**: Container execution for scripts
- **File Descriptors**: Secure IPC communication
- **Permission Handling**: Root and user operations
- **Resource Limits**: Memory and process constraints

## File Structure

```
src/commands/
├── testutils.rs           # Development testing utilities
├── shlib_backend.rs       # Shared library backend
└── internals.rs           # Internal system commands (future)

src/cli.rs                 # Add hidden command support
src/commands/mod.rs        # Register development commands
```

## CLI Integration

### Hidden Command Support
```rust
#[derive(Subcommand)]
pub enum Commands {
    // ... existing commands ...
    
    /// Development and debugging tools (hidden)
    #[command(hide = true)]
    Testutils(TestutilsArgs),
    
    /// Shared library backend (hidden)
    #[command(hide = true)]
    ShlibBackend(ShlibBackendArgs),
    
    /// Internal system commands (hidden)
    #[command(hide = true)]
    Internals(InternalsArgs),
}
```

### Flag System
```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CommandFlags {
    pub local_cmd: bool,
    pub hidden: bool,
    pub requires_root: bool,
    pub container_capable: bool,
    pub supports_pkg_installs: bool,
}
```

## Benefits of Integration

### Development Workflow
1. **Testing**: Automated testing and validation
2. **Debugging**: Package list inspection and modification
3. **Integration**: System state validation
4. **Scripting**: Safe script execution in containers

### Quality Assurance
1. **Package Management**: Validate APT integration
2. **OSTree Operations**: Test commit and deployment logic
3. **System Integration**: Verify daemon and client communication
4. **Error Handling**: Test edge cases and failure modes

### Maintenance and Support
1. **Troubleshooting**: Debug package and deployment issues
2. **Development**: Rapid iteration and testing
3. **Documentation**: Generate system state reports
4. **Validation**: Ensure system consistency

## Conclusion

Integrating these development commands from rpm-ostree into apt-ostree will provide essential tools for development, testing, and debugging. The commands are designed to be hidden from normal users while providing powerful capabilities for developers and system administrators.

The implementation should maintain the same logical structure and behavior as rpm-ostree while adapting to APT-specific package management and Debian system conventions. This will ensure that apt-ostree provides the same level of development support as the original rpm-ostree implementation.

## Next Steps

1. **Research**: Verify current rpm-ostree implementation status
2. **Design**: Create detailed implementation specifications
3. **Implementation**: Develop commands with proper testing
4. **Integration**: Add to CLI and command dispatch system
5. **Testing**: Validate functionality and performance
6. **Documentation**: Create developer and testing guides