Waman

A command-line tool for installing and launching web applications (PWAs) on Linux using Chromium-based browsers.

Features

• Install web apps from any URL with automatic manifest detection
• Launch installed apps quickly from the command line
• Manage app registry to track all your installed web applications
• Support for managed PWAs via Chrome policies (requires root for system-wide installation)
• Simple app windows for per-user installations (no root required)
• Manual icon selection with tips for finding icons at dashboardicons.com
• Quality gate enforcement to maintain code quality

Installation

cargo build --release

The binary will be available at target/release/waman.

Usage

Install a web app

# Install from URL
waman install https://example.com

# Install with custom name
waman install https://example.com --name "My App"

# Install with timeout (for slow connections)
waman install https://example.com --timeout 60

# Install from a local manifest file (requires --app-url)
waman install path/to/manifest.json --app-url https://example.com

# Dry run - show what would be installed without making changes
waman install https://example.com --dry-run

# Non-interactive mode - requires all inputs via arguments
waman install https://example.com --name "My App" --non-interactive

Launch an installed app

# Launch by name
waman launch "My App"

# Interactive selection
waman launch

List installed apps

waman list

Remove an app

# Remove by name
waman remove "My App"

# Interactive selection
waman remove

Architecture

This project follows Clean Architecture principles with clear separation of concerns:

Project Structure

src/
├── main.rs              # CLI entry point and command dispatch
├── domain/              # Pure domain types and logic (no I/O)
│   ├── app_kind.rs      # AppKind enum (ManagedPwa, AppWindow)
│   ├── browser.rs       # Browser struct
│   ├── desktop_candidate.rs  # DesktopCandidate for scanning
│   ├── manifest.rs      # ManifestInfo from web app manifest
│   ├── registry.rs      # AppEntry and Registry types
│   └── util.rs          # Pure utility functions
├── infra/               # I/O operations (side effects isolated)
│   ├── browser.rs       # Browser detection
│   ├── desktop.rs       # Desktop file operations
│   ├── filesystem.rs    # Filesystem utilities
│   ├── http.rs          # HTTP client operations
│   ├── policy.rs        # Chrome policy management
│   ├── registry.rs      # Registry persistence
│   ├── registry_cache.rs # Cached registry for performance
│   └── system_limits.rs # System resource detection
└── app/                 # Application use cases (orchestration)
    ├── install.rs       # Install flow and helpers
    ├── launch.rs        # Launch flow
    ├── list.rs          # List flow
    ├── ports.rs         # Infrastructure traits/ports
    └── remove.rs        # Remove flow

Design Principles

1. Domain-Driven Design: Domain types are pure data structures with no side effects
2. Dependency Inversion: Application layer depends on domain, infrastructure implements interfaces
3. Single Responsibility: Each module has one reason to change
4. Testability: Pure functions are easily unit tested; I/O is mocked via traits

Quality Gate

This project enforces code quality through an automated quality gate:

# Run quality gate (must pass before merging)
WAMAN_QUALITY_GATE=1 cargo build

Thresholds:

• Cyclomatic complexity: ≤15
• Cognitive complexity: ≤20
• Function arguments: ≤6

Quality reports are generated in target/debug/metrics/ with timestamped reports.

Configuration

Environment Variables

• WAMAN_VERBOSE=1 - Enable verbose (debug) output
• WAMAN_DEV=1 - Enable development mode
• RUST_LOG=debug - Set tracing log level

Tracing

This project uses the tracing crate for structured logging:

# Enable debug logging
RUST_LOG=debug waman install https://example.com

# Enable trace logging (very verbose)
RUST_LOG=trace waman install https://example.com

Development

Running Tests

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

Code Quality

# Check formatting
cargo fmt -- --check

# Run clippy
cargo clippy --all-features -- -D warnings

# Run quality gate
WAMAN_QUALITY_GATE=1 cargo build

Supported Browsers

• Google Chrome (stable, beta, unstable)
• Chromium
• Brave
• Vivaldi
• Microsoft Edge
• Opera
• Iridium
• Yandex Browser

Known Limitations

Flatpak/Snap browsers are not yet supported. Browsers installed via Flatpak or Snap run in sandboxed environments with different paths and execution models. Support for these installation methods is planned for a future release. For now, please use natively installed browsers (e.g., from your distribution's package manager or official .deb/.rpm packages).

AI Disclaimer

This project was largely generated using OpenCode Go with the Kimi K2 and DeepSeek models. All code has been reviewed and tested for correctness.

License

MIT

Contributing

1. Ensure all tests pass: cargo test
2. Ensure quality gate passes: WAMAN_QUALITY_GATE=1 cargo build
3. Ensure no clippy warnings: cargo clippy --all-features -- -D warnings
4. Make atomic commits with clear messages