RedBear-OS/local/docs/CUB-PACKAGE-MANAGER.md

# Cub — Red Bear OS Package Manager

**Status:** Active (redesign complete 2026-05)
**Location:** `local/recipes/system/cub/`
**Type:** Runtime package manager (runs inside Red Bear OS)
**Dependencies:** `pkgutils` (redox-pkg), `pkgar`

## Overview

Cub is the Red Bear OS package manager — an AUR-inspired tool for searching, fetching,
building, installing, and managing packages. It serves as the bridge between Red Bear OS
and the Arch Linux AUR ecosystem, converting PKGBUILD recipes into Red Bear OS recipe.toml
files and producing pkgar packages.

Cub runs as a regular user inside Red Bear OS, managing packages in `~/.cub/` and
installing them via the `pkgar` system.

## Architecture

```
cub (workspace)
├── cub-lib/          ← Core library (13 modules)
│   ├── aur.rs        ← AUR RPC v5 client (search, info)
│   ├── storage.rs    ← ~/.cub/ user-local storage manager
│   ├── cook.rs       ← recipe cooking (shells out to repo cook)
│   ├── pkgbuild.rs   ← Enhanced AUR PKGBUILD parser
│   ├── recipe.rs     ← Unified recipe.toml generation
│   ├── converter.rs  ← Legacy PKGBUILD converter (preserved)
│   ├── cookbook.rs   ← recipe.toml generation from RBPKGBUILD
│   ├── rbpkgbuild.rs ← RBPKGBUILD TOML type definitions
│   ├── package.rs    ← pkgar archive creation
│   ├── sandbox.rs    ← Build sandbox environment
│   ├── deps.rs       ← Arch Linux → Redox dependency name mapping
│   ├── rbsrcinfo.rs  ← .RBSRCINFO metadata format
│   └── error.rs      ← CubError enum (11 variants)
├── cub-tui/          ← Terminal UI (ratatui 0.30 + termion)
│   ├── app.rs        ← TUI app struct and event loop
│   ├── theme.rs      ← Red Bear color theme
│   ├── views/        ← search, info, install, build, query
│   └── widgets/      ← Reusable TUI components
└── cub-cli/          ← CLI binary entry point
    └── main.rs       ← 14 Arch-style switches + TUI launcher
```

## CLI Reference

### Operation Modes

Cub supports three operation modes mirroring pacman:

| Mode | Flag | Description |
|------|------|-------------|
| Sync | `-S` | Install, search, refresh, upgrade packages |
| Query | `-Q` | Manage locally installed packages |
| Remove | `-R` | Uninstall packages |

### Sync Operations (`-S`)

```bash
cub -S <pkg>         # Install from official repo or BUR/AUR
cub -Ss <query>      # Search official repo + cached BUR + AUR
cub -Si <pkg>        # Show AUR package info (description, deps, votes)
cub -Sy              # Refresh BUR cache + verify AUR connectivity
cub -Syu             # Full system upgrade (sync + update all)
cub -Sua             # Update AUR packages only
cub -Sc              # Clean package caches
```

### Build Operations (`-B`, `-G`)

```bash
cub -B <dir>         # Build local RBPKGBUILD directory → pkgar + install
cub -G <pkg>         # Fetch AUR PKGBUILD, convert to recipe, save to ~/.cub/
```

### Query Operations (`-Q`)

```bash
cub -Q               # List all installed packages
cub -Qi <pkg>        # Show installed package details (version, deps, size)
cub -Ql <pkg>        # List files installed by a package
```

### Remove Operations (`-R`)

```bash
cub -R <pkg>         # Uninstall a package
```

### Other Commands

```bash
cub -Pi <target>     # Inspect installed package or local RBPKGBUILD
cub --import-aur <target>  # Import AUR package (clone + convert PKGBUILD)
cub -T, --no-tui     # Disable TUI mode (use CLI directly)
cub                  # No subcommand: launch TUI
```

## User Storage (`~/.cub/`)

Cub maintains all user-local data in `~/.cub/` with four subdirectories:

```
~/.cub/
├── recipes/          # Converted recipe.toml + RBPKGBUILD + patches
│   └── <pkgname>/
│       ├── recipe.toml    ← Generated cookbook recipe
│       ├── RBPKGBUILD     ← Red Bear PKGBUILD (TOML format)
│       ├── .RBSRCINFO     ← Metadata for dependency resolution
│       └── patches/       ← Local patches
├── sources/          # Cached source tarballs and git clones
├── repo/             # Built pkgar packages organized by target
│   └── x86_64-unknown-redox/
│       ├── <pkg>.pkgar    ← Signed package archive
│       └── <pkg>.toml     ← Package metadata
└── config/           # Cub configuration and keyring
```

## AUR Integration

Cub accesses the Arch User Repository via the AUR RPC v5 API:

| Endpoint | Method | Cub Function |
|----------|--------|-------------|
| `/rpc?v=5&type=search&arg=<q>` | GET | `AurClient::search(query)` |
| `/rpc?v=5&type=info&arg[]=<pkg>` | GET | `AurClient::info(pkgs)` |
| `https://aur.archlinux.org/<pkg>.git` | git clone | `-G <pkg>` (import) |

### PKGBUILD Conversion

When importing from AUR (`-G` or `--import-aur`):

1. Clone the AUR git repository
2. Parse `PKGBUILD` bash script — extracts `pkgname`, `pkgver`, `pkgrel`,
   `depends`, `makedepends`, `source`, `sha256sums`, `optdepends`
3. Detect build template (cargo, cmake, meson, configure, custom)
4. Map Arch dependencies to Redox equivalents (glibc→relibc, openssl→openssl3,
   systemd→removed, etc.)
5. Generate `RBPKGBUILD` (TOML format) and `.RBSRCINFO`
6. Generate `recipe.toml` compatible with the Red Bear cookbook
7. Save all files to `~/.cub/recipes/<pkgname>/`

### Dependency Mapping

Cub maintains a 44-entry mapping table (`deps.rs`) translating Arch Linux
package names to their Redox/Red Bear equivalents:

| Arch Package | Redox Mapping | Notes |
|---|---|---|
| `glibc` | `relibc` | Redox uses relibc instead of glibc |
| `openssl` | `openssl3` | Version-specific mapping |
| `gcc`, `make` | `build-base` | Meta-package for build tools |
| `systemd` | *(removed)* | Unavailable on Redox — warning issued |
| `libx11`, `libxcb` | *(mapped)* | X11 unavailable — manual port needed |
| `linux-api-headers` | *(removed)* | Linux-specific — not applicable |
| `wayland` | `wayland` | Direct 1:1 mapping when available |
| `qt6-base` | `qtbase` | Qt 6 base libraries |
| `dbus` | `dbus` | Direct 1:1 mapping |

Unknown dependencies are passed through unchanged with a warning.

## Build Flow

```
cub -B <dir>                    # Build local RBPKGBUILD
  │
  ├─ 1. Parse RBPKGBUILD        ← Validate TOML format
  ├─ 2. Create sandbox          ← .cub-sandbox/{build,stage,sysroot}
  ├─ 3. Generate recipe.toml    ← cookbook::generate_recipe()
  ├─ 4. repo cook <recipe_dir>  ← Shell out to cookbook (cook.rs)
  ├─ 5. Locate stage directory  ← Find populated stage dir
  ├─ 6. Create pkgar archive    ← pkgar::create_with_flags()
  ├─ 7. Generate .toml metadata ← Package name, version, deps
  └─ 8. Install via pkgutils    ← library.install() + apply()
```

### Sandbox Environment

The build sandbox sets these environment variables for `repo cook`:

| Variable | Value |
|----------|-------|
| `COOKBOOK_SOURCE` | Source directory path |
| `COOKBOOK_STAGE` | Stage (install) directory |
| `COOKBOOK_SYSROOT` | Sysroot with built dependencies |
| `COOKBOOK_TARGET` | `x86_64-unknown-redox` |
| `COOKBOOK_HOST_TARGET` | `x86_64-unknown-linux-gnu` |
| `COOKBOOK_MAKE_JOBS` | CPU core count |
| `DESTDIR` | Alias for COOKBOOK_STAGE |
| `TARGET` | `x86_64-unknown-redox` |
| `GNU_TARGET` | `x86_64-redox` |

## TUI (Terminal UI)

Cub launches a ratatui-based TUI by default when run without a subcommand.
Use `--no-tui` / `-T` for direct CLI operation.

### Views

| View | Description | Key Bindings |
|------|-------------|-------------|
| **Search** | Search AUR by name/description | Type query, Enter to search |
| **Info** | Detailed package view | Shows deps, version, votes, description |
| **Install** | Install progress with log output | Shows command output in real-time |
| **Build** | Build progress for local recipes | Shows stage/progress indicators |
| **Query** | Browse locally installed packages | Arrows to navigate, Enter for details |

### Global Keys

| Key | Action |
|-----|--------|
| `q` / `Esc` | Quit TUI |
| `/` | Focus search bar |
| `Tab` | Cycle between views |
| `↑` `↓` | Navigate lists |
| `Enter` | Select / confirm |

### Theme

Red Bear color theme:
- Background: dark (terminal default)
- Accent: red (#CC0000)
- Text: white
- Selected: red highlight on white text
- Borders: gray

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `CUB_BUR_REPO_URL` | `https://gitlab.redox-os.org/redox-os/bur.git` | BUR repository URL |
| `CUB_PKGAR_SECRET_KEY` | *(auto-detected)* | Path to pkgar secret key |
| `CUB_PKGAR_PUBKEY_DIR` | *(auto-detected)* | Directory containing public key |

### Key Locations

| Path | Purpose |
|------|---------|
| `~/.pkg/id_ed25519.toml` | Secret key (pkgar signing) |
| `/etc/pkg/id_ed25519.toml` | System secret key fallback |
| `/pkg/id_ed25519.toml` | System secret key fallback 2 |
| `~/.cub/config/` | Cub-specific configuration |

## Recipe Format

Cub generates standard Red Bear OS recipe.toml files compatible with the
`repo cook` command:

```toml
[source]
git = "https://github.com/user/repo.git"
branch = "main"
rev = "abc123"

[build]
template = "cargo"
dependencies = ["cargo", "pkg-config"]

[package]
dependencies = ["relibc", "openssl3"]
version = "1.0.0-1"
description = "Example package converted from AUR"
```

### Template Detection

Cub auto-detects the correct build template from PKGBUILD `build()` contents:

| PKGBUILD pattern | recipe.toml template |
|---|---|
| `cargo build`, `cargo install` | `cargo` |
| `cmake` | `cmake` |
| `meson setup`, ` meson ` | `meson` |
| `./configure`, ` configure ` | `configure` |
| Other | `custom` |

## Linuxism Detection

During PKGBUILD conversion, cub detects Linux-specific patterns and issues
warnings for manual intervention:

| Pattern | Warning |
|---------|---------|
| `systemctl` | systemctl not available on Redox |
| `/usr/lib/systemd` | Linux-specific paths |
| `systemd` as dependency | Dependency removed (unavailable) |
| `/proc` references | May require Redox-specific adaptation |

## Build Recipe

Cub is built as a standard Cargo workspace:

```toml
# local/recipes/system/cub/recipe.toml
[source]
path = "source"

[build]
template = "cargo"
cargopath = "cub-cli"

[package]
dependencies = ["pkgutils"]
```

The recipe builds `cub-cli` which depends on `cub-lib` and optionally `cub-tui`.
The `default-members` of the workspace is `cub-cli` (the binary).

## Protected Recipe

Cub is listed as a **protected recipe** in `src/cook/fetch.rs` — it cannot be
re-fetched online. Sources are archived in `sources/redbear-0.1.0/`.

## Error Handling

Cub uses an 11-variant `CubError` enum via `thiserror`:

| Variant | Description |
|---------|-------------|
| `Io` | Filesystem errors |
| `TomlParse` | recipe.toml parse failures |
| `TomlSerialize` | recipe.toml serialization failures |
| `InvalidPkgbuild` | Malformed RBPKGBUILD |
| `BuildFailed` | `repo cook` or build failures |
| `PackageNotFound` | Missing package in repo/BUR |
| `Conversion` | PKGBUILD conversion errors |
| `Dependency` | Dependency resolution failures |
| `Aur` | AUR RPC errors (HTTP, parse, rate limit) |
| `Storage` | `~/.cub/` storage errors |
| `Network` | General network failures |
| `Sandbox` | Build sandbox errors |

## Limitations

1. **Build tools required**: `repo cook` requires the build toolchain
   (cross-compiler, host tools) which is not yet available inside Red Bear OS.
   Until build tools are ported, `cub build` (cooking) only works on build
   hosts. Runtime-only operations (search, install, query, remove) work inside
   Red Bear OS.

2. **Single source support**: recipe.toml generation currently supports only one
   primary source per recipe (AUR packages with multiple sources need manual
   adjustment).

3. **No binary repository**: cub currently fetches from AUR (source-based) and
   BUR (Red Bear package recipes). There is no binary package repository — all
   packages must be built from source.

4. **AUR JSON parsing**: The AUR module uses a hand-written JSON parser to avoid
   adding `serde_json` as a dependency. This works for the AUR RPC response
   format but is less robust than `serde_json`.

5. **TUI test coverage**: The `cub-tui` crate has no unit tests. Views are
   rendering-only and verified via `cargo build`.

## Future Work

- Port build tools inside Red Bear OS to enable full cooking at runtime
- Add binary package repository support for pre-built packages
- Implement `serde_json` dependency for robust AUR JSON parsing
- Add TUI unit tests for view rendering
- Support multi-source PKGBUILDs in recipe.toml generation
- Add package signing verification on install
- Implement delta updates for large packages