# Development Commands Usage Guide

## Overview
This document provides comprehensive usage examples for apt-ostree's development commands. These commands are hidden from normal help output and are intended for developers and system administrators debugging apt-ostree installations.

## Table of Contents
1. [testutils Commands](#testutils-commands)
2. [shlib-backend Commands](#shlib-backend-commands)
3. [internals Commands](#internals-commands)
4. [Common Use Cases](#common-use-cases)
5. [Troubleshooting](#troubleshooting)

## testutils Commands

### inject-pkglist
Inject a package list into an OSTree commit's metadata.

#### Basic Usage
```bash
# Inject a simple package list
sudo apt-ostree testutils inject-pkglist abc123 "apt,curl,nginx"

# Inject with specific commit and packages
sudo apt-ostree testutils inject-pkglist \
    debian/13/amd64/commit/2025-01-15T10:30:00Z \
    "apt,curl,nginx,postgresql-client"
```

#### Advanced Usage
```bash
# Inject from file
cat packages.txt | sudo apt-ostree testutils inject-pkglist abc123 -

# Inject with validation
sudo apt-ostree testutils inject-pkglist \
    --validate-dependencies \
    abc123 \
    "apt,curl,nginx"
```

#### Use Cases
- **Testing package management**: Verify package list injection works correctly
- **Development workflows**: Test package metadata handling
- **Debugging**: Investigate package list issues in commits

### script-shell
Execute a script in a bubblewrap container with various options.

#### Basic Usage
```bash
# Execute a simple script
sudo apt-ostree testutils script-shell /tmp/test.sh

# Execute with arguments
sudo apt-ostree testutils script-shell /tmp/install.sh --install-package nginx

# Execute in read-only mode
sudo apt-ostree testutils script-shell /tmp/check.sh --read-only
```

#### Advanced Options
```bash
# Execute with custom root path
sudo apt-ostree testutils script-shell \
    --rootpath /mnt/ostree/deploy/debian/13/amd64 \
    /tmp/deploy-check.sh

# Execute as specific user/group
sudo apt-ostree testutils script-shell \
    --user www-data \
    --group www-data \
    /tmp/web-test.sh

# Execute with custom working directory
sudo apt-ostree testutils script-shell \
    --cwd /var/www \
    /tmp/web-deploy.sh

# Execute with environment variables
sudo apt-ostree testutils script-shell \
    --env "DEBUG=1" \
    --env "TEST_MODE=1" \
    /tmp/debug-test.sh
```

#### Use Cases
- **Testing deployments**: Verify scripts work in isolated environments
- **Debugging**: Test scripts without affecting the main system
- **Development**: Develop and test deployment scripts safely

### generate-synthetic-upgrade
Generate a synthetic upgrade for testing purposes.

#### Basic Usage
```bash
# Generate basic synthetic upgrade
sudo apt-ostree testutils generate-synthetic-upgrade

# Generate with specific parameters
sudo apt-ostree testutils generate-synthetic-upgrade \
    --packages "apt,curl,nginx" \
    --version-increment "patch"
```

#### Advanced Usage
```bash
# Generate upgrade with custom metadata
sudo apt-ostree testutils generate-synthetic-upgrade \
    --metadata "test-mode=true" \
    --metadata "generated-by=test-suite"

# Generate upgrade for specific architecture
sudo apt-ostree testutils generate-synthetic-upgrade \
    --architecture amd64 \
    --os-version "debian/13"
```

#### Use Cases
- **Testing upgrade paths**: Verify upgrade mechanisms work correctly
- **Development testing**: Test upgrade logic without real packages
- **CI/CD pipelines**: Generate test data for automated testing

### integration-read-only
Run integration tests in read-only mode.

#### Basic Usage
```bash
# Run basic integration tests
sudo apt-ostree testutils integration-read-only

# Run with specific test categories
sudo apt-ostree testutils integration-read-only \
    --test-category "package-management" \
    --test-category "system-operations"
```

#### Advanced Usage
```bash
# Run with custom test parameters
sudo apt-ostree testutils integration-read-only \
    --test-timeout 300 \
    --verbose-output \
    --save-results /tmp/test-results.json
```

#### Use Cases
- **System validation**: Verify system state without making changes
- **Pre-deployment testing**: Test system before applying changes
- **Health checks**: Monitor system health and configuration

### c-units
Run C unit tests if available.

#### Basic Usage
```bash
# Run all available C unit tests
sudo apt-ostree testutils c-units

# Run specific test suite
sudo apt-ostree testutils c-units --suite "ostree-integration"

# Run with verbose output
sudo apt-ostree testutils c-units --verbose
```

#### Advanced Usage
```bash
# Run tests with custom compiler flags
sudo apt-ostree testutils c-units \
    --cflags "-O2 -g" \
    --ldflags "-L/usr/local/lib"

# Run tests in parallel
sudo apt-ostree testutils c-units --parallel --jobs 4
```

#### Use Cases
- **C library testing**: Test C library integrations
- **Performance testing**: Benchmark C-based operations
- **Compatibility testing**: Verify C library compatibility

### moo
Perform basic functionality tests.

#### Basic Usage
```bash
# Run basic functionality tests
sudo apt-ostree testutils moo

# Run specific test categories
sudo apt-ostree testutils moo --category "core-functions"
```

#### Use Cases
- **Quick health check**: Verify basic system functionality
- **Development testing**: Test during development cycles
- **Troubleshooting**: Identify basic system issues

## shlib-backend Commands

### get-basearch
Get the system's base architecture.

#### Basic Usage
```bash
# Get current system architecture
sudo apt-ostree shlib-backend get-basearch

# Get architecture for specific deployment
sudo apt-ostree shlib-backend get-basearch --deployment debian/13/amd64
```

#### Use Cases
- **Architecture detection**: Determine system architecture
- **Package selection**: Select appropriate packages for architecture
- **Deployment targeting**: Target deployments for specific architectures

### varsubst-basearch
Perform variable substitution for architecture-specific strings.

#### Basic Usage
```bash
# Substitute architecture variables
echo "arch={{arch}}" | sudo apt-ostree shlib-backend varsubst-basearch

# Substitute with custom source
sudo apt-ostree shlib-backend varsubst-basearch \
    "Package-{{arch}}-{{os}}-{{version}}.deb"
```

#### Advanced Usage
```bash
# Substitute multiple variables
sudo apt-ostree shlib-backend varsubst-basearch \
    "{{os}}-{{arch}}-{{version}}-{{flavor}}"

# Substitute with custom values
sudo apt-ostree shlib-backend varsubst-basearch \
    --custom-vars "os=debian,version=13,flavor=minimal" \
    "{{os}}-{{arch}}-{{version}}-{{flavor}}"
```

#### Use Cases
- **Template processing**: Process configuration templates
- **Package naming**: Generate architecture-specific package names
- **Deployment scripts**: Create architecture-aware deployment scripts

### packagelist-from-commit
Extract package list from an OSTree commit.

#### Basic Usage
```bash
# Extract package list from commit
sudo apt-ostree shlib-backend packagelist-from-commit abc123

# Extract with specific format
sudo apt-ostree shlib-backend packagelist-from-commit \
    --format json \
    abc123
```

#### Advanced Usage
```bash
# Extract with metadata
sudo apt-ostree shlib-backend packagelist-from-commit \
    --include-metadata \
    --metadata-keys "apt.packages,apt.dependencies" \
    abc123

# Extract to file
sudo apt-ostree shlib-backend packagelist-from-commit \
    --output /tmp/packages.txt \
    abc123
```

#### Use Cases
- **Package analysis**: Analyze packages in specific commits
- **Dependency tracking**: Track package dependencies across commits
- **Audit trails**: Create audit trails of package changes

## internals Commands

### diagnostics
Run comprehensive system diagnostics.

#### Basic Usage
```bash
# Run all diagnostics
sudo apt-ostree internals diagnostics

# Run specific diagnostic categories
sudo apt-ostree internals diagnostics \
    --category "ostree" \
    --category "apt" \
    --category "daemon"
```

#### Advanced Usage
```bash
# Run with custom parameters
sudo apt-ostree internals diagnostics \
    --timeout 600 \
    --output-format json \
    --save-report /tmp/diagnostics.json

# Run with specific checks
sudo apt-ostree internals diagnostics \
    --checks "repository-integrity,package-database,daemon-status"
```

#### Use Cases
- **System health check**: Comprehensive system health assessment
- **Problem diagnosis**: Identify system issues and misconfigurations
- **Pre-maintenance**: Verify system state before maintenance

### validate-state
Validate system state consistency.

#### Basic Usage
```bash
# Validate current system state
sudo apt-ostree internals validate-state

# Validate specific components
sudo apt-ostree internals validate-state \
    --component "ostree" \
    --component "apt"
```

#### Advanced Usage
```bash
# Validate with custom rules
sudo apt-ostree internals validate-state \
    --rules-file /etc/apt-ostree/validation-rules.toml \
    --strict-mode

# Validate and generate report
sudo apt-ostree internals validate-state \
    --generate-report \
    --report-format html \
    --output /tmp/validation-report.html
```

#### Use Cases
- **State verification**: Verify system state consistency
- **Configuration validation**: Validate configuration files and settings
- **Pre-deployment check**: Verify system state before deployments

### debug-dump
Dump comprehensive system information for debugging.

#### Basic Usage
```bash
# Dump all system information
sudo apt-ostree internals debug-dump

# Dump specific information categories
sudo apt-ostree internals debug-dump \
    --category "system-info" \
    --category "ostree-info" \
    --category "apt-info"
```

#### Advanced Usage
```bash
# Dump with custom format
sudo apt-ostree internals debug-dump \
    --format json \
    --output /tmp/debug-dump.json

# Dump with filtering
sudo apt-ostree internals debug-dump \
    --filter "error-only" \
    --include-logs \
    --log-level debug
```

#### Use Cases
- **Debugging**: Comprehensive debugging information
- **Support requests**: Generate information for support requests
- **System analysis**: Analyze system configuration and state

## Common Use Cases

### Development Workflow
```bash
# 1. Check system health
sudo apt-ostree internals diagnostics

# 2. Validate system state
sudo apt-ostree internals validate-state

# 3. Test new functionality
sudo apt-ostree testutils script-shell /tmp/test-feature.sh

# 4. Generate test data
sudo apt-ostree testutils generate-synthetic-upgrade

# 5. Verify results
sudo apt-ostree internals debug-dump
```

### Troubleshooting Workflow
```bash
# 1. Run comprehensive diagnostics
sudo apt-ostree internals diagnostics --verbose

# 2. Check specific components
sudo apt-ostree shlib-backend get-basearch
sudo apt-ostree testutils moo

# 3. Validate system state
sudo apt-ostree internals validate-state --strict-mode

# 4. Generate debug report
sudo apt-ostree internals debug-dump --output /tmp/troubleshoot.json
```

### Testing Workflow
```bash
# 1. Set up test environment
sudo apt-ostree testutils script-shell /tmp/setup-test-env.sh

# 2. Run integration tests
sudo apt-ostree testutils integration-read-only

# 3. Test package operations
sudo apt-ostree testutils inject-pkglist test-commit "test-package"

# 4. Verify test results
sudo apt-ostree internals debug-dump --category "test-results"
```

## Troubleshooting

### Common Issues

#### Permission Denied
```bash
# Check if running as root
sudo apt-ostree testutils moo

# Check Polkit policies
sudo polkit-policy-file-validate /usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy
```

#### Command Not Found
```bash
# Verify development features are enabled
cargo build --features development

# Check if binary includes development commands
cargo run --features development -- testutils --help
```

#### Bubblewrap Issues
```bash
# Check bubblewrap installation
which bubblewrap
bubblewrap --version

# Test bubblewrap functionality
bubblewrap --dev-bind / / --proc /proc -- echo "test"
```

#### OSTree Repository Issues
```bash
# Check repository status
sudo ostree show --repo=/ostree/repo

# Verify repository integrity
sudo ostree fsck --repo=/ostree/repo
```

### Debug Mode
```bash
# Enable debug logging
export APT_OSTREE_LOG_LEVEL=debug
export RUST_LOG=debug

# Run commands with verbose output
sudo apt-ostree testutils script-shell /tmp/test.sh --verbose
```

### Log Files
- **Daemon logs**: `/var/log/apt-ostreed.log`
- **System logs**: `sudo journalctl -u apt-ostreed`
- **OSTree logs**: `sudo ostree log --repo=/ostree/repo`

## Best Practices

### Security Considerations
- **Limited access**: Only authorized users should have access to development commands
- **Isolated execution**: Use script-shell with appropriate isolation options
- **Audit trails**: Log all development command usage for audit purposes

### Performance Considerations
- **Resource limits**: Set appropriate limits for development operations
- **Timeout handling**: Use appropriate timeouts for long-running operations
- **Resource cleanup**: Ensure proper cleanup after development operations

### Development Workflow
- **Testing**: Always test development commands in isolated environments
- **Documentation**: Document custom usage patterns and configurations
- **Version control**: Track changes to development command usage

---

*This guide covers the usage of apt-ostree development commands. For general usage, refer to the main User Guide.*