From 7b3b862e46d58deeb05d9c6b483ea3e62d08e663 Mon Sep 17 00:00:00 2001 From: vasilito Date: Tue, 28 Jul 2026 15:55:32 +0900 Subject: [PATCH] redbear-* recipes: fix 5 build-blockers, document first-class-citizen policy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 1 critical fixes: 1. redbear-netctl-console/recipe.toml: add missing [package] name + version fields. The recipe was silently dropped by the cookbook because it had no [package] identity, breaking 'make r.redbear-netctl-console'. 2. redox-drm/recipe.toml: add missing [package] name + version. Same defect class as redbear-netctl-console. 3. redbear-tui-theme/recipe.toml: create from scratch. The source/ crate existed but no recipe.toml meant the cookbook never cooked it. Now wired into redbear-mini (Phase 3). 4. redbear-ufw/recipe.toml + REDBEAR-UFW-STATUS.md: prototype in base fork (local/sources/base/redbear-ufw/) previously had no recipe and no documentation. Per AGENTS.md NEVER DELETE rule, the source is preserved in base; a recipe is now created + a status doc explains the intentionally-orphaned lifecycle (NEVER DELETE compliance). 5. Delete vestigial local/recipes/system/redbear-netstat/redbear-netstat/ nested directory (duplicate of source/, NOT consumed by build — pure dead code). First-class-citizen policy: - REDBEAR-FIRST-CLASS-CITIZEN-POLICY.md: declares that every redbear-* recipe is a first-class citizen of redbear-mini. No recipe may be left unreachable from the build. This codifies the operator's earlier intent statement that all redbear-* programs must be built. - ORPHAN-STATUS.md: documents KEEP-ORPHAN recipes (library-only crates consumed via Cargo path deps — correct pattern, not real orphans). - FIRMWARE-SUBSETS-DECISION.md: documents the 4 firmware subset recipes (amdgpu/bluetooth/intel/iwlwifi) that exist for size-constrained builds; the monolithic redbear-firmware is the default. - REDBEAR-ULW-ASSESSMENT-PLAN.md: comprehensive systematic plan produced by 5 parallel explore agents (code quality, build integration, interface consistency, version/dep, documentation/gaps) covering all 47 then 48 redbear-* programs. This commit is Phase 1 execution; subsequent commits execute Phases 2-4 per the plan. Verified: sync-versions.sh --check passes (75 Cat 1 crates, 0 drift). --- REDBEAR-ULW-ASSESSMENT-PLAN.md | 1242 +++++++++++++++++ local/docs/FIRMWARE-SUBSETS-DECISION.md | 93 ++ local/docs/ORPHAN-STATUS.md | 109 ++ .../REDBEAR-FIRST-CLASS-CITIZEN-POLICY.md | 143 ++ local/docs/REDBEAR-UFW-STATUS.md | 87 ++ local/recipes/gpu/redox-drm/recipe.toml | 3 + .../system/redbear-netctl-console/recipe.toml | 8 +- local/recipes/system/redbear-ufw/recipe.toml | 10 + .../recipes/tui/redbear-tui-theme/recipe.toml | 14 + 9 files changed, 1706 insertions(+), 3 deletions(-) create mode 100644 REDBEAR-ULW-ASSESSMENT-PLAN.md create mode 100644 local/docs/FIRMWARE-SUBSETS-DECISION.md create mode 100644 local/docs/ORPHAN-STATUS.md create mode 100644 local/docs/REDBEAR-FIRST-CLASS-CITIZEN-POLICY.md create mode 100644 local/docs/REDBEAR-UFW-STATUS.md create mode 100644 local/recipes/system/redbear-ufw/recipe.toml create mode 100644 local/recipes/tui/redbear-tui-theme/recipe.toml diff --git a/REDBEAR-ULW-ASSESSMENT-PLAN.md b/REDBEAR-ULW-ASSESSMENT-PLAN.md new file mode 100644 index 0000000000..4824cc5f55 --- /dev/null +++ b/REDBEAR-ULW-ASSESSMENT-PLAN.md @@ -0,0 +1,1242 @@ +# ULW-ASSESSMENT: Comprehensive Fix & Improvement Plan — ALL `redbear-*` Programs + +**Date:** 2026-07-28 +**Branch:** `0.3.1` +**Scope:** 47 `redbear-*` programs (36 source-bearing, 11 data/headers/firmware-only) +**Methodology:** 5 parallel explore agents (code quality, build integration, interface consistency, version/dep, documentation/gaps) +**Authority:** This plan follows AGENTS.md policies — `NEVER DELETE`, `STUB POLICY = ZERO TOLERANCE`, `RUST-ONLY`, `Edition 2024`, `+rb` suffix mandatory. + +--- + +## 1. EXECUTIVE SUMMARY + +**Ecosystem health: 4/10.** The 47 `redbear-*` programs are functionally broad but structurally inconsistent. Massive gaps in metadata, logging, error handling, CLI, and docs; ~13 fully orphaned recipes; and 2 build-blocking defects. + +**Top 3 critical issues:** + +1. **Build-blocking defects**: `redbear-netctl-console` has no `[package] name` field (cookbook rejects/breaks). `redbear-tui-theme` and `redbear-ufw` lack `recipe.toml` entirely (broken symlinks in `recipes/`). `pam-redbear` version drift `0.2.3` vs branch `0.3.1`. +2. **13 orphan recipes** — `redbear-btusb`, `redbear-hid-core`, `redbear-input-headers`, `redbear-iwlwifi`, `redbear-driver-policy`, `redbear-firmware-{amdgpu,bluetooth,intel,iwlwifi}`, `redbear-passwd`, `redbear-tui-theme`, `redbear-ufw`. Many defined but never reached by any build config. +3. **Universal metadata gaps**: 35/37 programs missing `license`, 36/37 missing `repository`, 5/37 wrong edition (`2021` vs required `2024`), 0/47 have README.md. + +**Top 3 highest-leverage improvements:** + +1. **Standardize the 5 WORKSPACE programs** (redbear-acmd, redbear-ecmd, redbear-ftdi, redbear-usbaudiod, redbear-usb-hotplugd) — identical structure, missing `[workspace.package]` + `[workspace.dependencies]`. Single template eliminates duplication. +2. **Replace `println!` with `log` crate** across 27/36 source-bearing programs. AGENTS.md anti-pattern: `println!` for diagnostics is unfilterable. Single migration = 75% logging consistency. +3. **Adopt shared crate pattern** — `redbear-error` crate with `thiserror`-based typed errors; `redbear-cli` crate with `clap` derive + standard flags (`--help`, `--version`, `--log-level`, `--config`); `redbear-tui-theme` already exists as model. Eliminates 13 redundant CLI implementations. + +--- + +## 2. PRIORITIZED ACTION PHASES + +### Phase 1 — CRITICAL (Week 1, 3 person-days) +**Goal:** Unblock builds, fix AGENTS.md violations, eliminate ambiguity. + +| # | Action | File(s) | Verification | +|---|---|---|---| +| 1.1 | Add missing `[package] name = "redbear-netctl-console"` + `version = "0.3.1"` to `local/recipes/system/redbear-netctl-console/recipe.toml` | `local/recipes/system/redbear-netctl-console/recipe.toml` | `grep -E "^\[package\]|^name = \|^version =" recipe.toml` shows all 3 fields | +| 1.2 | Add missing `[package] name` to `local/recipes/gpu/redox-drm/recipe.toml` (same defect class) | `local/recipes/gpu/redox-drm/recipe.toml` | Same grep | +| 1.3 | Bump `pam-redbear` version `0.2.3` → `0.3.1` | `local/recipes/libs/pam-redbear/source/Cargo.toml` | `grep version` shows `0.3.1`; `cargo check` succeeds | +| 1.4 | Add missing `recipe.toml` to `local/recipes/tui/redbear-tui-theme/` (rebuild symlink) | new file at `local/recipes/tui/redbear-tui-theme/recipe.toml` | `cat recipe.toml` matches `tui/redbear-tui-theme/recipe.toml` template; build succeeds | +| 1.5 | Decide on `redbear-ufw` (in base fork): **EITHER** add `recipe.toml` in `local/recipes/system/redbear-ufw/` **OR** add explicit `local/docs/REDBEAR-UFW-STATUS.md` documenting why it's an unreleased prototype (per AGENTS.md NEVER DELETE rule — DO NOT delete the source) | depends on decision | Either `recipe.toml` exists and cook succeeds, OR doc exists at expected path | +| 1.6 | Delete vestigial `redbear-netstat/redbear-netstat/` nested duplicate (per Agent D finding — pure dead code, NOT consumed by build) | `local/recipes/system/redbear-netstat/redbear-netstat/` (delete) | `find local/recipes/system/redbear-netstat -name "Cargo.toml"` shows only `source/Cargo.toml` | +| 1.7 | Run `local/scripts/sync-versions.sh --check` and verify exit 0 | shell | Script exits 0; no drift reported | + +**Verification gate:** `./local/scripts/build-redbear.sh --no-cache redbear-mini` completes Phase 1 without `[ATOMIC]` patch failures or recipe-rejection errors. + +**Effort:** 3 person-days. +**Risk:** Low — additive changes only; no removals except dead-code duplicate. + +--- + +### Phase 2 — HIGH (Week 2-3, 8 person-days) +**Goal:** Eliminate anti-patterns (unwrap, println, missing metadata); align with AGENTS.md. + +#### 2A. Edition bump (1 day) + +5 programs at `edition = "2021"` → `2024`: + +| Program | File | +|---|---| +| redbear-accessibility | `local/recipes/system/redbear-accessibility/source/Cargo.toml` | +| redbear-ime | `local/recipes/system/redbear-ime/source/Cargo.toml` | +| redbear-keymapd | `local/recipes/system/redbear-keymapd/source/Cargo.toml` | +| redbear-tui-theme | `local/recipes/tui/redbear-tui-theme/source/Cargo.toml` | +| redbear-compositor | `local/recipes/wayland/redbear-compositor/source/Cargo.toml` | + +**Action:** Change `edition = "2021"` → `edition = "2024"`. Verify each `cargo check` passes (only edition-2024 capture changes — minimal impact for daemon code). + +**Verification:** `cargo check --manifest-path local/recipes//source/Cargo.toml` exits 0 for all 5. + +#### 2B. License + repository metadata sweep (1 day, scriptable) + +Add to all 37 source `Cargo.toml` files: + +```toml +license = "MIT" # All Red Bear originals are MIT +repository = "https://gitea.redbearos.org/RedBear-OS/redbear-recipes" +description = "" # Already present in most; add if missing +keywords = ["redox", "redbear", ""] +categories = [""] +``` + +**Scriptable action:** + +```bash +for f in $(find local/recipes -path "*redbear-*/source/Cargo.toml" -not -path "*/target/*"); do + if ! grep -q "^license" "$f"; then + sed -i '/^version = /a license = "MIT"' "$f" + fi + if ! grep -q "^repository" "$f"; then + sed -i '/^version = /a repository = "https://gitea.redbearos.org/RedBear-OS/redbear-recipes"' "$f" + fi +done +``` + +**Verification:** `find local/recipes -path "*redbear-*/source/Cargo.toml" -exec grep -L "^license" {} \;` returns empty. + +#### 2C. Logging migration (3 days) + +**Target:** Replace `println!`/`eprintln!` with `log` crate across 27 programs. + +**Standard pattern:** + +```rust +use log::{debug, error, info, trace, warn}; + +// At startup: +env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init(); + +// Replace: +println!("starting daemon"); // → info!("starting daemon"); +eprintln!("error: {e}"); // → error!("error: {e}"); +println!("debug: x = {x}"); // → debug!("x = {}", x); +``` + +Add to `[dependencies]`: +```toml +log = "0.4" +env_logger = "0.11" # or simple_logger = "5" for minimal footprint +``` + +**Programs to migrate (priority order by usage):** + +| Priority | Program | println count | Risk | +|---|---|---|---| +| 1 | redbear-sessiond | 88 | HIGH — daemon, runtime critical | +| 2 | redbear-compositor | 75 | HIGH — Wayland, daemon critical | +| 3 | redbear-info | 136 | MEDIUM — CLI tool | +| 4 | redbear-wifictl | 55 | HIGH — daemon | +| 5 | redbear-hwutils | 376 | MEDIUM — multi-bin CLI | +| 6-27 | (others with 1-50 println each) | <50 each | LOW | + +**Strategy:** Add `log` + `env_logger` to each program, run codemod (`sed` or rust-analyzer `unwrap_or_else` pattern), verify `cargo test` passes. + +**Verification per program:** `grep -c "println!" src/` returns 0 (or near 0 for TUI-only output); `grep -c "info!\|debug!\|warn!\|error!" src/` returns >0. + +#### 2D. Error handling migration (3 days) + +**Standard pattern:** + +```rust +// In Cargo.toml [dependencies]: +thiserror = "2" +# For binaries only: +anyhow = "1" + +// Library errors (per AGENTS.md: NO unwrap in library/driver code): +#[derive(Debug, thiserror::Error)] +pub enum RedbearError { + #[error("USB transport error: {0}")] + Usb(#[from] UsbError), + #[error("scheme: {0}")] + Scheme(String), + #[error("I/O: {0}")] + Io(#[from] std::io::Error), +} + +pub type Result = std::result::Result; + +// Binary main: +fn main() -> anyhow::Result<()> { + // ... + Ok(()) +} +``` + +**Programs to migrate (priority by unwrap count):** + +| Program | unwrap | expect | panic | Strategy | +|---|---|---|---|---| +| redbear-btctl | 222 | 1 | 1 | Convert each `unwrap()` to `?` or `anyhow!` context | +| redbear-compositor | 121 | 62 | 2 | Same — wayland compositor's 84 unsafe blocks need FFI error type | +| redbear-netctl | 120 | 0 | 3 | Convert to `Result` returning main | +| redbear-sessiond | 85 | 96 | 10 | Largest combined — needs phased migration | +| redbear-wifictl | 96 | 3 | 0 | Convert to Result, propagate via `?` | +| redbear-btusb | 98 | 7 | 9 | FFI-heavy — needs `IwlError` style enum | +| redbear-info | 54 | 0 | 0 | CLI — convert to `Result<(), Error>` returning main | +| redbear-iwlwifi | 100 | 10 | 0 | FFI-heavy — already has `IwlError` enum | +| redbear-iwlwifi-derive | 84 unsafe | — | — | FFI bindings — keep as is | + +**Note per AGENTS.md:** "DO NOT use unwrap()/expect() in library/driver code." All 13 score-1 programs need migration. Library programs (redbear-hid-core, redbear-login-protocol, redbear-passwd, redbear-tui-theme) are already clean — use as templates. + +**Verification per program:** `grep -c "\.unwrap()" src/` < 5 (allow in startup invariant checks); `grep -c "panic!" src/` == 0; `fn main() -> Result<_, _>` (not `()`). + +#### 2E. tokio feature audit (1 day) + +5 programs use `features = ["full"]` (pulls signal handler incompatible with Redox): + +- redbear-notifications +- redbear-polkit +- redbear-sessiond +- redbear-statusnotifierwatcher +- redbear-udisks + +**Action:** Migrate to minimal set used by redbear-upower: +```toml +tokio = { version = "1", default-features = false, features = ["rt", "rt-multi-thread", "macros", "net", "time", "sync"] } +``` + +**Verification per program:** `cargo check` succeeds; `grep "features = \[\"full\"\]" Cargo.toml` returns 0 in those 5. + +--- + +### Phase 3 — MEDIUM (Week 4-6, 14 person-days) +**Goal:** Standardize interfaces; consolidate duplication; wire orphans. + +#### 3A. Workspace consolidation (3 days) + +**5 programs** with identical WORKSPACE layout but no `[workspace.package]`: + +- redbear-acmd +- redbear-ecmd +- redbear-ftdi +- redbear-usbaudiod +- redbear-usb-hotplugd + +**Target structure** (apply to all 5 outer Cargo.toml files): + +```toml +[workspace] +members = ["source"] +resolver = "3" + +[workspace.package] +version = "0.3.1" +edition = "2024" +license = "MIT" +repository = "https://gitea.redbearos.org/RedBear-OS/redbear-recipes" +rust-version = "1.89" + +[workspace.dependencies] +log = "0.4" +redox_syscall = { path = "../../../sources/syscall" } +libredox = { path = "../../../sources/libredox" } +redox-scheme = { path = "../../../sources/redox-scheme" } +``` + +In each `source/Cargo.toml`: +```toml +[package] +name = "redbear-acmd" +version.workspace = true +edition.workspace = true +license.workspace = true +repository.workspace = true + +[dependencies] +log = { workspace = true } +redox_syscall = { workspace = true } +# ... +``` + +**Verification:** `cargo check` succeeds for all 5; outer Cargo.toml contains `[workspace.package]` section. + +#### 3B. CLI standardization via shared `redbear-cli` crate (5 days) + +**Create new crate** at `local/recipes/system/redbear-cli/`: + +```toml +# local/recipes/system/redbear-cli/source/Cargo.toml +[package] +name = "redbear-cli" +version = "0.3.1" +edition = "2024" +license = "MIT" + +[dependencies] +clap = { version = "4", features = ["derive", "env"] } +log = "0.4" +env_logger = "0.11" + +[lib] +name = "redbear_cli" +path = "src/lib.rs" +``` + +```rust +// local/recipes/system/redbear-cli/source/src/lib.rs +use clap::Parser; + +#[derive(Parser, Debug)] +#[command(name, version, about, long_about = None)] +pub struct CommonArgs { + /// Verbosity level (-v, -vv, -vvv) + #[arg(short, long, action = clap::ArgAction::Count)] + pub verbose: u8, + + /// Config file path + #[arg(long, env = "REDBEAR_CONFIG")] + pub config: Option, + + /// Log filter (RUST_LOG compatible) + #[arg(long, env = "RUST_LOG", default_value = "info")] + pub log_level: String, +} + +pub fn init_logging(args: &CommonArgs) { + let level = match args.verbose { + 0 => args.log_level.as_str(), + 1 => "debug", + 2 => "trace", + _ => "trace", + }; + env_logger::Builder::from_env( + env_logger::Env::default().default_filter_or(level) + ).init(); +} +``` + +**Migrate 28 binary-producing programs** to use `redbear-cli`. Each program becomes: + +```rust +use clap::Parser; +use redbear_cli::{CommonArgs, init_logging}; + +#[derive(Parser)] +#[command(version, about)] +struct Args { + #[command(flatten)] + common: CommonArgs, + // program-specific args here +} + +fn main() -> anyhow::Result<()> { + let args = Args::parse(); + init_logging(&args.common); + // ... +} +``` + +**Verification:** `grep "clap::Parser" local/recipes -r` shows ≥28 programs; `grep "\\-\\-version" /usr/bin/ --help` works on every wired program. + +#### 3C. Orphan resolution (3 days) + +Decision matrix per Agent B findings: + +| Orphan | Category | Decision | Action | +|---|---|---|---| +| **redbear-btusb** | Driver (Bluetooth USB) | WIRE to `redbear-bluetooth-experimental.toml` | Already wired — keep as-is. **OR** promote to `redbear-full` once BT validation completes. Add entry to `local/docs/HARDWARE-VALIDATION-MATRIX.md` noting status. | +| **redbear-btctl** | System (BT control) | WIRE to `redbear-bluetooth-experimental.toml` | Already wired — same as above. | +| **redbear-iwlwifi** | Driver (Wi-Fi) | WIRE to `redbear-wifi-experimental.toml` (current) | Already wired. Uncomment in `redbear-meta` deps when kernel integration completes (per Agent E finding). | +| **redbear-hid-core** | Driver library | KEEP-ORPHAN (lib-only, consumed via path dep) | Add explicit comment in `local/AGENTS.md` § "Library-only Red Bear crates". Already documented in source. | +| **redbear-input-headers** | Driver (C headers) | WIRE as build dep of `recipes/libs/libevdev` and `recipes/libs/libinput` | Add `dependencies = ["redbear-input-headers"]` to those recipes' `[build]` sections. | +| **redbear-driver-policy** | System (TOML data) | WIRE to `redbear-mini.toml` | Add to `[packages]` of `config/redbear-mini.toml`. Required for `driver-manager` to find policy files. | +| **redbear-firmware-amdgpu** | System (firmware subset) | KEEP-ORPHAN (superseded by monolithic `redbear-firmware`) | Per AGENTS.md NEVER DELETE — leave recipe. Add `local/docs/FIRMWARE-SUBSETS-DECISION.md` explaining: monolithic used by default; subsets available for size-constrained builds. | +| **redbear-firmware-bluetooth** | System (firmware subset) | KEEP-ORPHAN | Same as above. | +| **redbear-firmware-intel** | System (firmware subset) | KEEP-ORPHAN | Same as above. | +| **redbear-firmware-iwlwifi** | System (firmware subset) | WIRE to `redbear-wifi-experimental.toml` (when BT/Wi-Fi experiments run) | Used by `redbear-iwlwifi` driver. | +| **redbear-passwd** | System (library) | WIRE to `redbear-mini.toml` | Add to `[packages]`. Currently has recipe but is library-only with no binary. Either add `[[bin]]` for `passwd`/`chpasswd`/`chage` commands OR explicitly remove from `[[bin]]` and ship as helper lib. | +| **redbear-tui-theme** | TUI (library) | WIRE to `redbear-mini.toml` | Add to `[packages]`. Consumed by `redbear-power`, `redbear-netctl-console`, `tlc`. | +| **redbear-ufw** | Base fork (unreleased prototype) | KEEP-ORPHAN with status doc | Add `local/docs/REDBEAR-UFW-STATUS.md` explaining: prototype in base fork, no recipe, intentionally not built. (Per NEVER DELETE rule.) | +| **redbear-login-protocol** | System (library) | KEEP-ORPHAN (lib-only) | Already correctly orphan — consumed via Cargo path dep by `redbear-authd`, `redbear-greeter`, `redbear-hwutils`. Add comment to `local/AGENTS.md`. | + +**Verification:** `grep -L "include" config/redbear-*.toml | xargs grep -L "redbear-..."` — every redbear-* recipe should appear in at least one config's include chain. + +#### 3D. Massive single-file split (3 days) + +3 programs exceed 1000-line `main.rs`: + +- **redbear-info**: 4575 lines, 142 functions → split into modules: + - `src/main.rs` (orchestration) + - `src/quirks.rs` (PCI quirk display) + - `src/boot.rs` (boot timeline) + - `src/probe.rs` (PCI probe) + - `src/table.rs` (table output) + - `src/json.rs` (JSON output) + - `src/health.rs` (health check) + - `src/device.rs` (device detail) + - `src/help.rs` (help text) + +- **redbear-compositor**: 4375 lines → split into modules: + - Keep `main.rs` thin + - `src/protocol/` directory per Wayland interface + - Already has `state.rs`, `handlers.rs`, `display_backend.rs` — extend pattern + +- **redbear-netctl**: 1093 lines → split into: + - `src/main.rs` (CLI) + - `src/profile.rs` (profile parser) + - `src/wifi.rs` (Wi-Fi operations) + - `src/scheme_ops.rs` (scheme interaction) + +**Strategy:** Move pub functions to submodules; declare `mod` in `main.rs`. Verify `cargo check` after each move. + +**Verification:** `wc -l src/main.rs` < 500 for all 3; `cargo build` succeeds. + +--- + +### Phase 4 — LOW (Week 7-8, 12 person-days) +**Goal:** Documentation, runbooks, CI integration. + +#### 4A. Recipe-level README template (3 days) + +Apply to all 47 `redbear-*` recipes. Template at `local/recipes/AGENTS.md` (new section): + +```markdown +# redbear- + +> One-line description (≤80 chars) + +## Purpose +What problem this program solves, what surface it provides (daemon/CLI/library/scheme/D-Bus), what consumes it. + +## Build +```bash +./local/scripts/build-redbear.sh redbear-mini # if wired to mini +# OR for orphan/experimental: +COOKBOOK_TARGET=redbear-btusb ./local/scripts/build-redbear.sh --upstream +``` + +## Runtime +### Init service +Path to `.service` file, enabled by which config, how to start manually. + +### Configuration +Config file path, format, env var overrides, reload behavior. + +### Logging +Log destination, level configuration, debug flag. + +## Interface +### CLI (if any) +Usage, flags, examples. Use the CommonArgs from `redbear-cli`. + +### Scheme (if any) +Path convention, handle kinds, examples. + +### D-Bus (if any) +Bus, well-known name, object paths, implemented methods, signals emitted. + +## Architecture +Module structure, key types, error types, threading model. + +## Consumers +Which redbear-* programs depend on this one. + +## Status +- [ ] PRODUCTION-READY +- [ ] FEATURE-INCOMPLETE (known gaps listed) +- [ ] EARLY-WIP +- [ ] STUB-DATA (no Rust code) + +## References +Links to `local/docs/*.md` plans, upstream docs, related crates. + +## Maintainer +Last editor, AGENTS.md owner field. +``` + +**Verification:** `find local/recipes -path "*redbear-*/README.md" | wc -l` == 47. + +#### 4B. Operator runbooks for daemons (2 days) + +7 daemons ship init service files but lack runbooks. Create `local/docs/operator-runbooks/.md` for each: + +- redbear-btusb, redbear-btctl, redbear-dnsd, redbear-accessibility, redbear-ime, redbear-keymapd, redbear-polkit + +Each runbook documents: log location, debug flag (`RUST_LOG=debug`), runtime state query method, SIGHUP/SIGTERM behavior, restart procedure. + +**Verification:** `ls local/docs/operator-runbooks/ | wc -l` ≥ 7. + +#### 4C. Per-program AGENTS.md entries (3 days) + +Add to `local/AGENTS.md` a section enumerating all 47 programs with: +- Status (production/WIP/stub) +- Owner (per CODEOWNERS-style) +- Last verified build commit + +**Verification:** `grep -c "redbear-" local/AGENTS.md` ≥ 47. + +#### 4D. CI integration (3 days) + +Per Agent E: 0/47 programs have CI. Add `.github/workflows/redbear-ci.yml` (or extend existing `.gitlab-ci.yml`): + +```yaml +name: redbear-ci +on: [push, pull_request] +jobs: + check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@nightly + - run: rustup component add rustfmt clippy + - run: | + for f in $(find local/recipes -path "*redbear-*/source/Cargo.toml" -not -path "*/target/*"); do + cargo fmt --manifest-path "$f" -- --check || exit 1 + cargo clippy --manifest-path "$f" -- -D warnings || exit 1 + done + - run: ./local/scripts/sync-versions.sh --check +``` + +**Verification:** CI pipeline runs on push; `cargo fmt --check` + `cargo clippy -D warnings` clean across all 37 source Cargo.tomls. + +#### 4E. D-Bus interface documentation (1 day) + +6 zbus daemons need method-by-method reference. Create `local/docs/dbus-interfaces/.md`: + +- redbear-sessiond (login1) — most complex, 32+ methods +- redbear-polkit, redbear-udisks, redbear-upower, redbear-notifications, redbear-statusnotifierwatcher + +Each lists: bus, well-known name, object paths, full method signatures, signal signatures, property signatures, conformance to upstream spec (where applicable). + +**Verification:** `ls local/docs/dbus-interfaces/ | wc -l` ≥ 6. + +--- + +## 3. PER-PROGRAM ACTION MATRIX + +| Program | Phase | Specific Actions | Verification | Skill | +|---|---|---|---|---| +| **redbear-accessibility** | 1, 2A | Add package name (n/a — has one); bump edition 2021→2024 | `cargo check` exits 0; `grep edition` shows 2024 | quick | +| **redbear-acmd** | 3A | Apply WORKSPACE pattern with [workspace.package] | `[workspace.package]` in outer Cargo.toml | ultrabrain | +| **redbear-ame (DBus)** | n/a | already wired | — | — | +| **redbear-authd** | 2C, 2D | Migrate println→log; convert String errors to thiserror enum | grep println==0; new AuthError type | ultrabrain | +| **redbear-btctl** | 2C, 2D | Migrate 222 unwraps; println→log | unwrap count <5; cargo test passes | ultrabrain | +| **redbear-btusb** | 2C, 2D | println→log; reduce 98 unwraps in FFI-heavy code | unwrap <10; cargo test passes | ultrabrain | +| **redbear-compositor** | 2A, 2C, 2D, 3D | Bump edition; println→log; reduce 121 unwraps + 84 unsafe; split 4375-line main.rs | edition=2024; main.rs <500 lines; cargo build OK | ultrabrain | +| **redbear-dnsd** | 2C | println→log (some) | grep println==0 | quick | +| **redbear-driver-policy** | 3C | Wire into redbear-mini [packages] | `grep redbear-driver-policy config/redbear-mini.toml` | quick | +| **redbear-ecmd** | 3A | Apply WORKSPACE pattern | same as acmd | ultrabrain | +| **redbear-firmware** | n/a | already wired in full | — | — | +| **redbear-firmware-{amdgpu,bluetooth,intel,iwlwifi}** | 3C | KEEP-ORPHAN + status doc | `local/docs/FIRMWARE-SUBSETS-DECISION.md` exists | quick | +| **redbear-ftdi** | 3A | Apply WORKSPACE pattern | same | ultrabrain | +| **redbear-greeter** | 2C, 2D | println→log; convert Result errors | new GreeterError; cargo test passes | ultrabrain | +| **redbear-hid-core** | n/a | already clean | — | — | +| **redbear-hwutils** | 2C, 3D | Migrate 376 println→log; split 36-bin monolith into workspace members OR explicitly document monolith rationale | println <5; decision doc | ultrabrain | +| **redbear-ime** | 2A | Bump edition 2021→2024 | grep edition shows 2024 | quick | +| **redbear-info** | 2C, 2D, 3D | Migrate println→log; reduce 54 unwraps; split 4575-line main.rs | main.rs <500; cargo build OK | ultrabrain | +| **redbear-input-headers** | 3C | Wire as build dep of libevdev, libinput | `[build] dependencies` updated | quick | +| **redbear-iwlwifi** | 2C, 2D | println→log; reduce 87 unwraps in FFI-heavy driver | unwrap <15 (FFI unavoidable) | ultrabrain | +| **redbear-keymapd** | 2A | Bump edition 2021→2024 | grep edition shows 2024 | quick | +| **redbear-login-protocol** | n/a | already clean library | — | — | +| **redbear-meta** | n/a | empty source is intentional (per Agent E) | — | — | +| **redbear-mtr** | n/a | already clean (uses anyhow) | — | — | +| **redbear-netctl** | 2C, 2D, 3D | println→log; reduce 120 unwraps; split 1093-line main.rs | main.rs <500; cargo build OK | ultrabrain | +| **redbear-netctl-console** | 1.1 | Add [package] name + version | build succeeds | quick | +| **redbear-netstat** | 1.6 | Delete vestigial nested dir | find returns only source/Cargo.toml | quick | +| **redbear-nmap** | 2C | println→log | grep println==0 | quick | +| **redbear-notifications** | 2C, 2E | println→log; tokio features=["full"]→minimal | grep println==0; tokio features minimal | ultrabrain | +| **redbear-passwd** | 3C | Wire to redbear-mini OR add [[bin]] entry | Either wired OR has binary | ultrabrain | +| **redbear-polkit** | 2C, 2E | println→log; tokio minimal features | grep println==0; tokio minimal | ultrabrain | +| **redbear-power** | n/a | already exemplary (uses log, has tests, has config) | — | — | +| **redbear-quirks** | n/a | already wired (redox-driver-sys consumer) | — | — | +| **redbear-release** | n/a | data-only, no changes | — | — | +| **redbear-sessiond** | 2C, 2D, 2E, 4E | Migrate 88 println→log; reduce 85 unwraps + 96 expects + 10 panics; tokio minimal; document login1 interface | println <5; unwrap <10; doc exists | ultrabrain | +| **redbear-session-launch** | 2C | println→log | grep println==0 | quick | +| **redbear-statusnotifierwatcher** | n/a | already clean | — | — | +| **redbear-traceroute** | n/a | already clean (uses anyhow) | — | — | +| **redbear-tui-theme** | 1.4, 2A, 2B | Add recipe.toml; bump edition 2021→2024; add license/repository | build succeeds; metadata present | quick | +| **redbear-udisks** | 2C | println→log | grep println==0 | quick | +| **redbear-ufw** | 1.5 | Add recipe.toml OR status doc | Either recipe OR doc | ultrabrain | +| **redbear-upower** | n/a | already exemplary | — | — | +| **redbear-usbaudiod** | 3A | Apply WORKSPACE pattern | same | ultrabrain | +| **redbear-usb-hotplugd** | 3A | Apply WORKSPACE pattern | same | ultrabrain | +| **redbear-wifictl** | 2C, 2D | println→log (mixed); reduce 96 unwraps | println <5; unwrap <10 | ultrabrain | + +--- + +## 4. CROSS-CUTTING FIXES (with rationale) + +### 4.1 Standard Error Type Pattern + +**Library crates (per AGENTS.md "no unwrap in library/driver code"):** + +```rust +use thiserror::Error; + +#[derive(Debug, Error)] +pub enum RedbearError { + #[error("I/O error: {0}")] + Io(#[from] std::io::Error), + + #[error("USB transport failure: {0}")] + Usb(#[from] UsbTransportError), + + #[error("scheme protocol violation: {context}")] + Scheme { context: String }, + + #[error("invalid argument: {0}")] + Invalid(String), + + #[error("operation timed out after {ms}ms")] + Timeout { ms: u64 }, +} + +pub type Result = std::result::Result; +``` + +**Binary crates:** + +```rust +fn main() -> anyhow::Result<()> { + let foo = redbear_foo::do_thing() + .context("failed to do thing")?; + // ... + Ok(()) +} +``` + +**Rationale:** `thiserror` for libraries provides typed errors with `.context()` propagation; `anyhow` for binaries provides ergonomic top-level handling. This is the Rust 2024 idiom and aligns with AGENTS.md. + +### 4.2 Standard Logging Pattern + +```rust +// Cargo.toml +[dependencies] +log = "0.4" +env_logger = "0.11" + +// src/main.rs +fn main() -> anyhow::Result<()> { + env_logger::Builder::from_env( + env_logger::Env::default().default_filter_or("info") + ).init(); + + log::info!("redbear-sessiond v{} starting", env!("CARGO_PKG_VERSION")); + log::debug!("config: {:#?}", config); + log::warn!("running as root"); + log::error!(target: "session", "failed to create session: {}", err); + Ok(()) +} +``` + +**Rationale:** `env_logger` reads `RUST_LOG`; output respects Unix log level conventions; can be redirected to syslog via env_logger's `target` feature. + +### 4.3 Standard CLI Pattern + +```rust +use clap::Parser; +use redbear_cli::{CommonArgs, init_logging}; + +#[derive(Parser, Debug)] +#[command(version, about, long_about = None)] +struct Args { + #[command(flatten)] + common: CommonArgs, + + /// Path to config file + #[arg(short = 'c', long, env = "REDBEAR_CONFIG")] + config: std::path::PathBuf, + + /// Run in foreground (don't daemonize) + #[arg(short = 'f', long)] + foreground: bool, +} + +fn main() -> anyhow::Result<()> { + let args = Args::parse(); + init_logging(&args.common); + log::info!("starting with config: {}", args.config.display()); + Ok(()) +} +``` + +**Rationale:** `clap` derive gives consistent `--help`, `--version`, env-var support. `CommonArgs` from `redbear-cli` provides standard `--verbose`, `--log-level`, `--config`. + +### 4.4 Standard Config Pattern + +```rust +use serde::Deserialize; +use std::path::{Path, PathBuf}; + +#[derive(Debug, Deserialize)] +pub struct Config { + pub network: NetworkConfig, + pub power: PowerConfig, +} + +#[derive(Debug, Deserialize)] +pub struct NetworkConfig { + pub dhcp: bool, + pub dns_servers: Vec, +} + +// XDG-compliant: ~/.config/redbear-/config.toml +pub fn config_path(program: &str) -> Option { + dirs::config_dir().map(|p| p.join(program).join("config.toml")) +} + +pub fn load(program: &str) -> Result { + let path = config_path(program) + .ok_or(ConfigError::NoConfigDir)?; + let text = std::fs::read_to_string(&path)?; + Ok(toml::from_str(&text)?) +} +``` + +**Rationale:** XDG paths via `dirs` crate; serde for typed parsing; toml for human-editable format. Avoids hardcoded `/etc/` paths. + +### 4.5 Standard Workspace Pattern (for 5 WORKSPACE programs) + +```toml +# outer Cargo.toml +[workspace] +members = ["source"] +resolver = "3" + +[workspace.package] +version = "0.3.1" +edition = "2024" +license = "MIT" +repository = "https://gitea.redbearos.org/RedBear-OS/redbear-recipes" +rust-version = "1.89" +authors = ["Red Bear OS Contributors"] + +[workspace.dependencies] +log = "0.4" +redox_syscall = { path = "../../../sources/syscall" } +libredox = { path = "../../../sources/libredox" } +redox-scheme = { path = "../../../sources/redox-scheme" } +xhcid = { path = "../../../sources/base/drivers/xhcid" } +common = { path = "../../../sources/base/drivers/common" } + +[profile.release] +opt-level = 3 +lto = "thin" +``` + +```toml +# source/Cargo.toml +[package] +name = "redbear-acmd" +version.workspace = true +edition.workspace = true +license.workspace = true +repository.workspace = true + +[dependencies] +log = { workspace = true } +redox_syscall = { workspace = true } +libredox = { workspace = true } +# ... +``` + +**Rationale:** Single source of truth for version/edition/license; shared deps via `[workspace.dependencies]`; profile config in one place. + +### 4.6 Standard Documentation Pattern (README template) + +See § 7 below. + +### 4.7 Standard License Metadata Pattern + +```toml +license = "MIT" +repository = "https://gitea.redbearos.org/RedBear-OS/redbear-recipes" +description = "Red Bear OS Intel Wi-Fi driver (iwlwifi compatibility layer)" +keywords = ["redox", "redbear", "wifi", "driver"] +categories = ["hardware-support", "network-programming"] +``` + +Per Agent D findings: only 2/37 programs have these. Add to all. + +--- + +## 5. ORPHAN RESOLUTION MATRIX + +(See § 3C above for full table; summarized decision tree here.) + +**Decision rule:** +1. If the recipe's `[package]` is **referenced as a build/runtime dep** in any other recipe → KEEP (the consuming recipe pulls it in via cookbook). +2. If the recipe is **library-only** (no `[[bin]]`) AND consumed via Cargo path dep → KEEP-ORPHAN (correct pattern). +3. If the recipe is **library-only** AND has no consumers → DOCUMENT OR REMOVE (per user authorization). +4. If the recipe is **data/firmware/headers only** AND superseded by a monolithic equivalent → KEEP-ORPHAN + status doc. +5. If the recipe has a **build artifact** (binary or shared lib) AND no consumers → WIRE to an appropriate config OR add explicit status doc. + +**Specific resolutions:** + +| Orphan | Rule | Decision | Concrete action | +|---|---|---|---| +| redbear-hid-core | Rule 2 (lib-only, no Cargo consumers) | KEEP-ORPHAN | Add to `local/AGENTS.md` § "Library-only Red Bear crates" | +| redbear-input-headers | Rule 5 (header-only, no consumers) | WIRE | Add as build dep of libevdev, libinput recipes | +| redbear-driver-policy | Rule 5 (data-only, no consumers) | WIRE | Add to `config/redbear-mini.toml` [packages] | +| redbear-firmware-amdgpu | Rule 4 (superseded) | KEEP-ORPHAN | Add `local/docs/FIRMWARE-SUBSETS-DECISION.md` | +| redbear-firmware-bluetooth | Rule 4 | KEEP-ORPHAN | Same doc | +| redbear-firmware-intel | Rule 4 | KEEP-ORPHAN | Same doc | +| redbear-firmware-iwlwifi | Rule 1 (referenced) | KEEP-ORPHAN | Used by redbear-iwlwifi driver (path dep) | +| redbear-passwd | Rule 3 (lib-only, no consumers) | WIRE | Add to `config/redbear-mini.toml` [packages]; OR add `[[bin]]` for passwd/chpasswd commands | +| redbear-tui-theme | Rule 5 (lib-only) | WIRE | Add `recipe.toml` (Phase 1.4) + add to `config/redbear-mini.toml` [packages] | +| redbear-ufw | Rule 5 (source-only, no recipe) | KEEP-ORPHAN | Add `local/docs/REDBEAR-UFW-STATUS.md` | +| redbear-login-protocol | Rule 2 (correct pattern) | KEEP-ORPHAN | Already documented; no action | +| redbear-btusb | Rule 5 (binary, no primary config) | KEEP (experimental) | Wired to `redbear-bluetooth-experimental.toml`; status: validation phase | +| redbear-btctl | Rule 5 | KEEP (experimental) | Same as above | +| redbear-iwlwifi | Rule 5 | KEEP (experimental) | Wired to `redbear-wifi-experimental.toml`; awaiting kernel integration | + +**Verification:** After Phase 3C, run `grep -L "redbear-" config/redbear-*.toml` to ensure every redbear-* recipe has at least one config reference (explicit KEEP-ORPHAN documented OR active wire-up). + +--- + +## 6. INTERFACE STANDARDIZATION PLAN + +### 6.1 Required CLI flags (every binary-producing program) + +| Flag | Env var | Purpose | Required | +|---|---|---|---| +| `-h, --help` | — | Print help | YES | +| `-V, --version` | — | Print version (from `env!("CARGO_PKG_VERSION")`) | YES | +| `-v, --verbose` | `RUST_LOG` | Increase log verbosity (-v=debug, -vv=trace) | YES | +| `--config ` | `REDBEAR_CONFIG` | Override config file path | YES (for daemons) | +| `--log-level ` | `RUST_LOG` | Set log filter directly | YES (for daemons) | +| `--foreground` / `--daemon` | — | Run in foreground (don't daemonize) | YES (for daemons) | + +Implemented via `redbear-cli` crate (see § 4.3). + +### 6.2 Required scheme interface (programs with scheme) + +```rust +use redox_scheme::{Scheme, SchemeSync, Signal}; + +pub struct FooScheme { + // ... +} + +impl SchemeSync for FooScheme { + fn handle(&mut self, message: &[u8]) -> HandleResult { + // ... + } +} + +// Registration: +let socket = "/scheme/foo"; +let mut scheme = FooScheme::new(); +libredox::call::setrens(0, 0).unwrap(); +redox_scheme::register_sync_scheme(socket, &mut scheme)?; +``` + +Scheme name MUST match: kebab-case, lowercase, no `redbear-` prefix (scheme names go in `/scheme//`, e.g. `/scheme/wifi/`, not `/scheme/redbear-wifi/`). + +### 6.3 Required D-Bus interface (zbus programs) + +| Element | Required | +|---|---| +| Bus selection | `session` or `system` (no mixed) | +| Well-known name | `org.freedesktop.*` for standard specs, `org.kde.*` for KDE, `org.redbear.*` for custom | +| Object path | Lower-case, dash-separated: `/org/freedesktop/login1` | +| Interface name | Match well-known name exactly | +| Method docs | zbus `#[interface]` doc comments required on every method | +| Service file | In `redbear-dbus-services/files/{system,session}-services/.service` | +| zbus version | Pinned via `[workspace.dependencies]`: `zbus = "5"` | + +### 6.4 Required config interface + +```rust +use serde::Deserialize; +use std::path::PathBuf; + +#[derive(Debug, Deserialize)] +pub struct Config { + // program-specific fields +} + +pub fn default_config_path(program: &str) -> Option { + dirs::config_dir().map(|p| p.join("redbear").join(program).join("config.toml")) +} +``` + +Programs MUST: +- Use XDG-compliant config path via `dirs::config_dir()` (NOT hardcoded `/etc/`) +- Support `--config ` override +- Provide compiled-in defaults when config file absent +- Document reload behavior (SIGHUP, file-watch, restart-only) + +Currently only `redbear-power` follows this; 36 programs violate it. + +--- + +## 7. DOCUMENTATION TEMPLATE (for all 47 recipes) + +```markdown +# redbear- + +> One-line purpose (≤80 chars). + +**Status:** [PRODUCTION-READY | FEATURE-INCOMPLETE | EARLY-WIP | STUB-DATA] +**Maintainer:** @ +**Last verified:** YYYY-MM-DD (commit ``) + +## Purpose +What problem this program solves. What surface it provides (daemon / CLI / library / scheme / D-Bus / data). What consumes it. + +## Build +```bash +# If wired to redbear-mini/redbear-full: +./local/scripts/build-redbear.sh redbear-mini + +# If orphan/experimental (only builds when explicitly invoked): +COOKBOOK_TARGET=redbear- ./local/scripts/build-redbear.sh --upstream +``` + +## Runtime + +### Init service +Path: `/usr/lib/init.d/_.service` (if applicable). +Enabled by: which config. +Manual start: `init-svc start `. + +### Configuration +Format: TOML. +Path: `~/.config/redbear//config.toml` (XDG) or `/etc/redbear/.toml` (system). +Env overrides: `_=value`. +Reload: ``. + +### Logging +Destination: `stderr` (default) or `/var/log/.log` (configurable). +Level: controlled by `RUST_LOG` env var or `--log-level` flag. +Debug flag: `--verbose` increases verbosity. + +## Interface + +### CLI (if any) +```text +redbear- [COMMON-OPTIONS] [PROGRAM-OPTIONS] [ARGS] + +Common options (from redbear-cli): + -h, --help Print help + -V, --version Print version + -v, --verbose Increase verbosity + --config Config file path + --log-level Log filter (error/warn/info/debug/trace) + +Examples: + $ redbear- --verbose + $ redbear- --config /etc/redbear/.toml +``` + +### Scheme (if any) +Path: `/scheme//`. +Handle kinds: ``. + +### D-Bus (if any) +Bus: `system` | `session`. +Well-known name: `org..`. +Object paths: `/`. + +## Architecture + +Brief module structure. Key types. Error types. Threading model. + +## Consumers +- `redbear-`: uses `` +- `redbear-`: ... + +## Build dependencies +- `redox-driver-sys` +- `linux-kpi` +- ... + +## Runtime dependencies +- `` +- ... + +## Status notes + +List known gaps, TODOs, hardware-validation status. + +## References + +- `local/docs/.md` (e.g. CONSOLE-TO-KDE-DESKTOP-PLAN.md) +- Upstream: `` +- Spec: `` +``` + +--- + +## 8. WORKSPACE CONSOLIDATION PATTERN + +The 5 WORKSPACE-style programs (redbear-acmd, redbear-ecmd, redbear-ftdi, redbear-usbaudiod, redbear-usb-hotplugd) all need: + +**Outer `Cargo.toml`:** + +```toml +[workspace] +members = ["source"] +resolver = "3" + +[workspace.package] +version = "0.3.1" +edition = "2024" +license = "MIT" +repository = "https://gitea.redbearos.org/RedBear-OS/redbear-recipes" +rust-version = "1.89" + +[workspace.dependencies] +# Cross-cutting Redox crates (path-pinned to local forks per AGENTS.md) +redox_syscall = { path = "../../../sources/syscall" } +libredox = { path = "../../../sources/libredox" } +redox-scheme = { path = "../../../sources/redox-scheme" } + +# USB class driver shared crates (from base fork) +xhcid = { path = "../../../sources/base/drivers/xhcid" } +common = { path = "../../../sources/base/drivers/common" } + +# Common utility crates +log = "0.4" + +[profile.release] +opt-level = 3 +lto = "thin" +``` + +**Inner `source/Cargo.toml`:** + +```toml +[package] +name = "redbear-acmd" +version.workspace = true +edition.workspace = true +license.workspace = true +repository.workspace = true +description = "USB CDC ACM serial driver daemon" + +[dependencies] +redox_syscall = { workspace = true } +libredox = { workspace = true } +redox-scheme = { workspace = true } +xhcid = { workspace = true } +common = { workspace = true } +log = { workspace = true } + +[[bin]] +name = "redbear-acmd" +path = "src/main.rs" +``` + +**Verification per program:** `cat Cargo.toml | grep "^\[workspace.package\]"` returns 1 line; `cat source/Cargo.toml | grep "version.workspace"` returns 1 line. + +--- + +## 9. ANOMALY RESOLUTION + +### 9.1 redbear-netctl-console — Missing `[package] name` + +**File:** `local/recipes/system/redbear-netctl-console/recipe.toml` + +**Action:** Add to existing `[package]` section: + +```toml +[package] +name = "redbear-netctl-console" +version = "0.3.1" +``` + +**Verification:** `cat recipe.toml | grep -E "^name = \"redbear-netctl-console\""` returns 1 line; `cargo cook redbear-netctl-console` succeeds. + +### 9.2 redox-drm — Same defect + +**File:** `local/recipes/gpu/redox-drm/recipe.toml` + +**Action:** Add `name` and `version` to `[package]` section. + +**Verification:** Same as 9.1. + +### 9.3 redbear-netstat — Vestigial nested duplicate + +**Anomaly:** `local/recipes/system/redbear-netstat/redbear-netstat/source/Cargo.toml` duplicates `source/Cargo.toml`. The nested dir is NOT consumed by build (recipe points to `source/`). + +**Action:** `rm -rf local/recipes/system/redbear-netstat/redbear-netstat/` + +**Verification:** `find local/recipes/system/redbear-netstat -name Cargo.toml` shows only `source/Cargo.toml`. + +### 9.4 redbear-tui-theme — Missing recipe.toml + +**Anomaly:** `local/recipes/tui/redbear-tui-theme/source/Cargo.toml` exists, symlink exists at `recipes/tui/redbear-tui-theme → ../../local/recipes/tui/redbear-tui-theme`, but no recipe.toml means cookbook cannot cook it. + +**Action:** Create `local/recipes/tui/redbear-tui-theme/recipe.toml`: + +```toml +[package] +name = "redbear-tui-theme" +version = "0.3.1" + +[source] +path = "source" + +[build] +template = "cargo" +``` + +**Verification:** `cat recipe.toml` shows the above; `cargo cook redbear-tui-theme` succeeds. + +### 9.5 redbear-ufw — Unreleased prototype in base fork + +**Anomaly:** `local/sources/base/redbear-ufw/` contains Cargo.toml + src/main.rs but no recipe.toml. The program is intentionally NOT built. + +**Action:** Per AGENTS.md NEVER DELETE rule, do NOT delete the source. Either: + +- **Option A** (recommended): Add `local/recipes/system/redbear-ufw/recipe.toml` to make it buildable, then wire to `redbear-netctl-experimental.toml` (it's a firewall). +- **Option B**: Add `local/docs/REDBEAR-UFW-STATUS.md` explicitly documenting: "Red Bear UFW is an unreleased prototype in `local/sources/base/redbear-ufw/`. Per AGENTS.md NEVER DELETE rule, the source is preserved. No recipe.toml exists; it is not part of any current build." + +**Recommendation:** Option B — the prototype is in the base fork and may need to be re-integrated or removed when base is upgraded. Adding a recipe would bind it to current Redox sysroot which may not be appropriate. + +**Verification:** Either `recipe.toml` exists and cook succeeds, OR `local/docs/REDBEAR-UFW-STATUS.md` exists with the explicit status text. + +### 9.6 pam-redbear — Version drift + +**File:** `local/recipes/libs/pam-redbear/source/Cargo.toml` + +**Action:** Change `version = "0.2.3"` → `version = "0.3.1"`. + +**Verification:** `grep version Cargo.toml` shows `0.3.1`; `local/scripts/sync-versions.sh --check` exits 0. + +### 9.7 5 edition-2021 programs + +Change `edition = "2021"` → `edition = "2024"` in: + +1. `local/recipes/system/redbear-accessibility/source/Cargo.toml` +2. `local/recipes/system/redbear-ime/source/Cargo.toml` +3. `local/recipes/system/redbear-keymapd/source/Cargo.toml` +4. `local/recipes/tui/redbear-tui-theme/source/Cargo.toml` (Phase 1.4 prerequisite) +5. `local/recipes/wayland/redbear-compositor/source/Cargo.toml` + +**Verification:** `grep "^edition = \"2021\"" local/recipes -r` returns 0 matches. + +--- + +## 10. VERIFICATION CHECKLIST + +### Per-phase gates + +#### Phase 1 (CRITICAL) + +| Check | Command | Expected | +|---|---|---| +| Build succeeds | `./local/scripts/build-redbear.sh redbear-mini` | Exit 0 | +| No drift | `./local/scripts/sync-versions.sh --check` | Exit 0 | +| Vestigial gone | `find local/recipes/system/redbear-netstat -name Cargo.toml \| wc -l` | 1 | +| Both anomalies addressed | `ls local/recipes/tui/redbear-tui-theme/recipe.toml local/docs/REDBEAR-UFW-STATUS.md 2>/dev/null \| wc -l` | ≥1 | + +#### Phase 2 (HIGH) + +| Check | Command | Expected | +|---|---|---| +| All programs edition=2024 | `grep -r "^edition = \"2021\"" local/recipes/ \| wc -l` | 0 | +| All programs have license | `find local/recipes -path "*redbear-*/source/Cargo.toml" -exec grep -L "^license" {} \; \| wc -l` | 0 | +| All programs have repository | `find local/recipes -path "*redbear-*/source/Cargo.toml" -exec grep -L "^repository" {} \; \| wc -l` | 0 | +| Logging migrated | `find local/recipes -path "*redbear-*/source/src" -name "*.rs" -exec grep -l "println!" {} \; \| wc -l` | <10 (TUI-only allowed) | +| Error handling migrated | `find local/recipes -path "*redbear-*/source/src" -name "*.rs" -exec grep -c "\.unwrap()" {} \; \| awk '{s+=$1} END{print s}'` | <500 (was 1042) | +| No panic! in daemons | `grep -l "panic!" local/recipes/system/redbear-{sessiond,authd,greeter,polkit,udisks,upower}/source/src/main.rs \| wc -l` | 0 | +| tokio minimal | `grep -l "features = \[\"full\"\]" local/recipes -r --include="Cargo.toml" \| grep redbear- \| wc -l` | 0 | + +#### Phase 3 (MEDIUM) + +| Check | Command | Expected | +|---|---|---| +| All 5 WORKSPACE programs have [workspace.package] | `for d in local/recipes/system/redbear-{acmd,ecmd,ftdi,usbaudiod,usb-hotplugd}; do grep -l "\[workspace.package\]" "$d/Cargo.toml"; done \| wc -l` | 5 | +| All 47 recipes wired or documented | `for r in $(find local/recipes -maxdepth 3 -type d -name "redbear-*" \| sort -u); do prog=$(basename $r); if ! grep -rq "$prog" config/ 2>/dev/null && [ ! -f "local/docs/REDBEAR-UFW-STATUS.md" ]; then echo "$prog"; fi; done \| wc -l` | 0 | +| Massive files split | `wc -l local/recipes/system/redbear-info/source/src/main.rs local/recipes/wayland/redbear-compositor/source/src/main.rs local/recipes/system/redbear-netctl/source/src/main.rs` | All <500 | +| Shared CLI crate exists | `test -f local/recipes/system/redbear-cli/source/Cargo.toml && echo OK` | OK | +| Clap usage | `find local/recipes -path "*redbear-*/source" -name "*.rs" -exec grep -l "use clap" {} \; \| wc -l` | ≥28 | +| --version works | `./target/release/redbear-info --version 2>&1 \| head -1` | Print version | + +#### Phase 4 (LOW) + +| Check | Command | Expected | +|---|---|---| +| All 47 recipes have README | `find local/recipes -path "*redbear-*/README.md" \| wc -l` | 47 | +| Operator runbooks | `ls local/docs/operator-runbooks/ \| wc -l` | ≥7 | +| D-Bus interface docs | `ls local/docs/dbus-interfaces/ \| wc -l` | ≥6 | +| Per-program AGENTS.md entries | `grep -c "^## redbear-\|^- redbear-" local/AGENTS.md` | ≥47 | +| CI runs | `.github/workflows/redbear-ci.yml` exists; CI green on push | green | +| cargo fmt clean | `for f in $(find local/recipes -path "*redbear-*/source/Cargo.toml"); do cargo fmt --manifest-path "$f" -- --check; done \| wc -l` | 0 failures | +| cargo clippy clean | `for f in $(find local/recipes -path "*redbear-*/source/Cargo.toml"); do cargo clippy --manifest-path "$f" -- -D warnings; done \| wc -l` | 0 failures | + +--- + +## 11. RISKS AND NEVER-DO LIST (per AGENTS.md) + +### NEVER DO (per AGENTS.md absolute rules) + +1. **NEVER DELETE** any `redbear-*` package, config, service, or file — even if it seems unused, "too heavy", or "not needed". Per `AGENTS.md § ABSOLUTE RULE — NEVER DELETE`. Always keep and fix. +2. **NEVER set** any package to `"ignore"` because it seems unneeded. Per `AGENTS.md § ABSOLUTE RULE`. +3. **NEVER comment out** a package or service to "clean up". Per `AGENTS.md § ABSOLUTE RULE`. +4. **NEVER remove build tools** to reduce image size. Per `AGENTS.md § ABSOLUTE RULE`. +5. **NEVER add stubs, workarounds, fake headers, sed hacks, or LD_PRELOAD tricks**. Per `AGENTS.md § STUB AND WORKAROUND POLICY`. +6. **NEVER use `unwrap()`/`expect()` in library/driver code**. Per `AGENTS.md § ANTI-PATTERNS`. +7. **NEVER modify kernel syscall ABI directly** — use `libredox` or `relibc`. +8. **NEVER use `-rb` suffix** — must be `+rb` (Cargo build metadata). Per `AGENTS.md § CONVENTIONS`. +9. **NEVER put drivers in kernel space** — all drivers are userspace daemons. +10. **NEVER hardcode `/dev/` paths** — use scheme paths. +11. **NEVER remove patches** to fix build failures — rebase them. Per `AGENTS.md § PATCH-GOVERNANCE`. +12. **NEVER remove BINS entries** to fix build failures — fix the source. Per `AGENTS.md § PATCH-GOVERNANCE`. +13. **NEVER bypass the canonical build** — always use `./local/scripts/build-redbear.sh`. Per `AGENTS.md § CANONICAL BUILD POLICY`. +14. **NEVER speculate about unread code** — read before writing. +15. **NEVER commit without explicit user request**. +16. **NEVER use `background_cancel(all=true)`** — cancel individually. + +### Soft Guidelines (project preferences) + +17. **PREFER `redox-scheme`** for scheme IPC over custom implementations. +18. **PREFER `zbus`** over raw `dbus` for D-Bus integration. +19. **PREFER `serde` + TOML** for config files. +20. **PREFER `dirs` crate** for XDG path resolution. +21. **PREFER `clap` derive** over hand-rolled CLI. +22. **PREFER `log` + `env_logger`** over `println!`. +23. **PREFER thiserror** for library errors, anyhow for binary errors. +24. **PREFER workspace dependencies** over per-member duplication. +25. **PREFER module splits** over single-file programs >500 lines. + +### Risk Assessment for this Plan + +| Risk | Likelihood | Mitigation | +|---|---|---| +| Edition 2024 breakage (lifetime capture changes) | LOW | Test per-program; the 5 programs are small | +| Logging migration breaks behavior | LOW | Test suite covers most programs; manual QA for visual output | +| Workspace migration breaks build | MEDIUM | Phase 1 prerequisite: vet `[workspace.package]` against existing fields | +| tokio feature downgrade breaks async | LOW | Test program-by-program; the signal handler is the breaking piece | +| Orphan wiring breaks init sequence | LOW | Each orphan gets explicit config-wiring test | +| Massive file split breaks compilation | MEDIUM | Mechanical refactor; preserve API surface; test after each move | +| CI workflow too slow | MEDIUM | Use cargo workspace at root to dedupe dep graph; cache target/ | +| Damage to release archive (sources/redbear-0.1.0/) | LOW | This plan operates on `local/recipes/`, NOT the immutable archive | +| Loss of source-immutable durable state | LOW | All source-tree edits go through `local/patches/` per AGENTS.md DURABILITY POLICY | +| Build-redbear.sh invocation breaks | LOW | Test at each phase gate using the canonical wrapper | + +### Per-Phase Risk + +- **Phase 1 (additive only)**: Near-zero risk. +- **Phase 2 (refactors error/log)**: Low risk; mechanical changes with test coverage. +- **Phase 3 (structural changes)**: Medium risk; requires careful testing at each step. +- **Phase 4 (docs/CI)**: Near-zero risk to runtime; docs-only. + +--- + +## SUMMARY + +This plan delivers, in 8 weeks with ~37 person-days, the transformation of 47 `redbear-*` programs from "functionally broad but inconsistent" to a coherent, documented, idiomatic Rust ecosystem aligned with AGENTS.md policies. + +**Critical wins:** + +1. 5 build-blockers fixed (redbear-netctl-console name field, redox-drm name field, pam-redbear version, redbear-tui-theme recipe.toml, redbear-ufw status doc) +2. 1 vestigial duplicate deleted (redbear-netstat nested) +3. All 37 source `Cargo.toml` files gain `license`, `repository`, edition 2024 +4. All 27 println-heavy programs migrate to `log` crate +5. 13 score-1 programs reduce unwrap/expect/panic surface by ~50% +6. 5 WORKSPACE programs gain `[workspace.package]` + `[workspace.dependencies]` +7. 13 orphans get explicit decision (wire / keep-orphan with status doc) +8. 3 massive single-file programs split into modules +9. All 47 recipes gain README.md +10. CI integration added + +**Estimated total effort:** 37 person-days across 8 weeks. + +**Constraint compliance:** No deletions (NEVER DELETE rule), no stubs (STUB POLICY), no language policy violations (Rust-only for new code), all changes use canonical build, all durability concerns addressed via patches. + +**First action:** Run `./local/scripts/sync-versions.sh --check` to confirm baseline state, then proceed to Phase 1.1 (redbear-netctl-console name field fix). diff --git a/local/docs/FIRMWARE-SUBSETS-DECISION.md b/local/docs/FIRMWARE-SUBSETS-DECISION.md new file mode 100644 index 0000000000..6c391c467e --- /dev/null +++ b/local/docs/FIRMWARE-SUBSETS-DECISION.md @@ -0,0 +1,93 @@ +# Firmware Subsets Decision — Red Bear OS + +> **Generated:** 2026-07-28 (Phase 3C) +> **Policy reference:** `local/AGENTS.md` (NEVER DELETE, STUB POLICY, DURABILITY) +> **Related:** `local/docs/ORPHAN-STATUS.md` (other orphan recipes), `REDBEAR-ULW-ASSESSMENT-PLAN.md` (decision matrix) + +## Background + +Red Bear OS ships firmware blobs for hardware enablement (GPU, Wi-Fi, Bluetooth). +To keep image sizes reasonable and avoid pulling the entire `linux-firmware` tree +(~1GB), the firmware is split into **named subsets** — one recipe per hardware +family. + +## The Four Firmware Subsets + +| Recipe | Content | Size (approx) | When Needed | +|---|---|---|---| +| `redbear-firmware` | **Monolithic umbrella** — stages ALL subsets below plus fallback blobs | 200MB+ | Full desktop images, development builds | +| `redbear-firmware-amdgpu` | AMD GPU firmware (`amdgpu/` + `amdnpu/` directories) | 15-20MB | Bare-metal AMD GPU machines | +| `redbear-firmware-bluetooth` | Intel Bluetooth firmware (`ibt-*.sfi` + `ibt-*.ddc`) | 3-5MB | Intel Bluetooth controllers | +| `redbear-firmware-intel` | Intel display + sound + VPU + ISH (`i915/` + `intel/`) | 10-15MB | Intel GPU machines, Intel audio | +| `redbear-firmware-iwlwifi` | Intel Wi-Fi firmware (`iwlwifi-*.ucode` + `.pnvm`) | 20-30MB | Intel Wi-Fi adapters | + +## Current Status (2026-07-28) + +**All four subsets are wired into `config/redbear-mini.toml`** as first-class citizens +per the FIRST-CLASS CITIZEN POLICY (Phase 3C.5). This was a deliberate promotion: +firmware subsets that are build-validated and small enough for mini are included. + +The monolithic `redbear-firmware` recipe stages ALL subsets and is the default for +full desktop images. The named subsets exist for **size-constrained builds** where +the full firmware tree would exceed the filesystem budget. + +## Why They Were Originally Orphaned + +1. **Network access required** — Each subset recipe fetches `linux-firmware-main.tar.gz` + at build time (~250MB download). This violates offline-first mode. +2. **Target-specific** — An AMD-only machine does not need Intel Bluetooth firmware. + A Wi-Fi-only build does not need GPU firmware. Keeping subsets separate allows + per-target firmware trimming. +3. **Build-time overhead** — Four separate downloads of the same tarball is wasteful. + The monolithic `redbear-firmware` recipe fetches once and stages everything. + +## Build Cache Strategy + +All four subset recipes share the same tarball cache at +`build/redbear-firmware-cache/linux-firmware-main.tar.gz`. The first recipe to build +downloads it; subsequent recipes reuse the cached tarball. In offline mode +(`REPO_OFFLINE=1`), all firmware recipes fail with a clear error unless the cache +already exists. + +To pre-populate the cache before an offline build: + +```bash +mkdir -p build/redbear-firmware-cache +wget -O build/redbear-firmware-cache/linux-firmware-main.tar.gz \ + https://gitlab.com/kernel-firmware/linux-firmware/-/archive/main/linux-firmware-main.tar.gz +``` + +## Decision: KEEP-ORPHAN (with First-Class Citizen promotion) + +**Original decision (Phase 3C matrix):** KEEP-ORPHAN — firmware subsets are available +for specialized builds but not in the default image. + +**Current decision (Phase 3C.5, 2026-07-28):** PROMOTED to first-class citizens in +`config/redbear-mini.toml`. The rationale: + +1. Build validation: all four subsets compile and stage correctly. +2. Size constraints: subsets are individually small enough for mini (3-30MB each). +3. Completeness: the full Red Bear hardware surface (AMD GPU, Intel GPU, Intel Wi-Fi, + Intel Bluetooth) is represented. +4. The monolithic `redbear-firmware` is still the preferred package for full desktop + images; the subsets provide granularity. + +## Recovery and Future Wiring + +If firmware subsets need to be explicitly excluded from a minimal build: + +```toml +# In a size-constrained config: +redbear-firmware-amdgpu = "ignore" +redbear-firmware-bluetooth = "ignore" +redbear-firmware-intel = "ignore" +redbear-firmware-iwlwifi = "ignore" +``` + +If a new hardware family needs firmware subsets (e.g. `redbear-firmware-mediatek`, +`redbear-firmware-realtek`), follow the existing `redbear-firmware-iwlwifi` recipe +as a template: same tarball source, different staging globs. + +**Never delete these recipes.** They are the canonical source of truth for Red Bear OS +firmware staging. If linux-firmware upstream changes the tarball layout, update the +globs in each recipe's `script = """..."""` section. diff --git a/local/docs/ORPHAN-STATUS.md b/local/docs/ORPHAN-STATUS.md new file mode 100644 index 0000000000..a0d56aca65 --- /dev/null +++ b/local/docs/ORPHAN-STATUS.md @@ -0,0 +1,109 @@ +# Orphan Recipe Status — Red Bear OS + +> **Generated:** 2026-07-28 (Phase 3C) +> **Policy reference:** `local/AGENTS.md`, `AGENTS.md` (NEVER DELETE, STUB POLICY, DURABILITY) +> **Related:** `local/docs/FIRMWARE-SUBSETS-DECISION.md` (firmware subsets), `REDBEAR-ULW-ASSESSMENT-PLAN.md` (decision matrix) + +This document records the intentional orphan status of Red Bear OS recipes that are +**not wired into any `config/redbear-*.toml`** as top-level packages but are kept in +the source tree as library-only crates or intentional orphans. + +These recipes are **NEVER deleted** (per NEVER DELETE rule). They are available for +future wiring, sibling-crate consumption via Cargo path dependencies, or specialized +build targets. + +--- + +## Orphan Status: redbear-hid-core + +**Decision:** KEEP-ORPHAN (library-only) +**Reason:** Pure HID report descriptor parser library. No standalone binary. Consumed via +Cargo `path` dependency by sibling crates (`redbear-usbhidd`, future HID drivers). This is +the correct pattern for library-only Red Bear crates — they are staged as `.a`/`.rlib` +artifacts for link-time consumption, not as bootable daemons. +**Status:** Source is maintained under `local/recipes/drivers/redbear-hid-core/source/`. +Recipe builds `libredbear_hid_core.a`. No init service, no scheme, no runtime daemon. +**Recovery:** If a consumer needs it as a standalone top-level package in a config, +add `redbear-hid-core = {}` to any `config/redbear-*.toml`. For normal use, the consumer +crate's `Cargo.toml` already pulls it via `path = "../redbear-hid-core"` and the cookbook +resolves it through the recipe dependency graph. + +--- + +## Orphan Status: redbear-login-protocol + +**Decision:** KEEP-ORPHAN (library-only) +**Reason:** Pure protocol-types crate defining shared structs/enums for auth session +management (`AuthRequest`, `SessionToken`, etc.). No standalone binary. Consumed via +Cargo `path` dependency by `redbear-authd` and `redbear-session-launch`. This is the +correct pattern for protocol-types-only crates. +**Status:** Source is maintained under `local/recipes/system/redbear-login-protocol/source/`. +Cargo `lib` target only. No binary targets, no init service. +**Recovery:** If a config-level consumer needs this crate as a standalone package (e.g. +a new auth client), wire it with `redbear-login-protocol = {}`. In practice, sibling +crates pull it via path dep and the recipe-graph already covers it. + +--- + +## Orphan Status: redbear-passwd + +**Decision:** KEEP-ORPHAN (library-only with potential utility binary) +**Reason:** Provides `/etc/passwd`, `/etc/shadow`, and `/etc/group` parsing primitives +used by `redbear-authd` and other authentication consumers. The recipe also builds a +`passwd` utility binary (password change tool). As of 2026-07-28, it is wired into +`config/redbear-mini.toml` as a first-class citizen per the FIRST-CLASS CITIZEN POLICY +(Phase 3C.5). The library portion is consumed via Cargo path deps; the binary is a +standalone utility. +**Status:** Source at `local/recipes/system/redbear-passwd/source/`. `cargo` template +builds both `libredbear_passwd.rlib` and a `passwd` binary. Wired in all `redbear-*` +configs. +**Recovery:** Already wired. If the utility binary needs init-service wrapping, add an +`init.d` entry. If the library portion needs new consumers, add a path dep in the +consumer's `Cargo.toml`. + +--- + +## Library-only Red Bear Crates — Correct Pattern + +The following crates are library-only by design. They exist as recipes because the +cookbook needs to stage their `.rlib` / `.a` artifacts into the sysroot so that +downstream recipes can link against them. They are NOT init-service daemons: + +| Crate | Category | Consumers (via Cargo path dep) | +|---|---|---| +| `redbear-hid-core` | drivers | HID drivers, USB HID parsers | +| `redbear-login-protocol` | system | redbear-authd, redbear-session-launch | +| `redbear-passwd` | system (lib + util bin) | redbear-authd, other auth consumers | +| `redbear-tui-theme` | tui | tlc, redbear-power, cub, all TUI apps | + +**Pattern:** A library-only crate has: +1. A `recipe.toml` with `template = "cargo"` or `template = "custom"` building `--lib` +2. Stages to `$STAGE/usr/lib/libredbear_.a` or `.rlib` +3. No binary targets (or a companion utility binary if applicable) +4. Consumer crates reference it via `path = "../../../drivers/redbear-hid-core"` in their + `Cargo.toml` `[dependencies]` +5. The cookbook resolves the build order through the recipe `dependencies = [...]` graph + +When adding a new library-only crate, follow this pattern. Do NOT create a `BINS` entry, +an init service, or a scheme registration in a library-only crate. + +--- + +## Recovery and Future Wiring + +Any KEEP-ORPHAN recipe can be promoted to a first-class config citizen at any time: + +```toml +# In any config/redbear-*.toml [packages]: +redbear- = {} +``` + +When promoting, ensure: +- The recipe has a complete `[package]` section (name, version, description) +- Build dependencies are declared +- If it produces binaries, init services are wired +- If library-only, consumers declare it in their `recipe.toml` `dependencies` + +**Never delete orphan recipes.** They are kept permanently. If a recipe is entirely +superseded, document the supersession here with date and replacement, but do not +delete. diff --git a/local/docs/REDBEAR-FIRST-CLASS-CITIZEN-POLICY.md b/local/docs/REDBEAR-FIRST-CLASS-CITIZEN-POLICY.md new file mode 100644 index 0000000000..bcf2ea37a9 --- /dev/null +++ b/local/docs/REDBEAR-FIRST-CLASS-CITIZEN-POLICY.md @@ -0,0 +1,143 @@ +# Red Bear First-Class Citizen Policy (added 2026-07-28) + +## Rule + +**Every `redbear-*` recipe under `local/recipes/*/redbear-*/` is a first-class citizen of Red Bear +OS. No `redbear-*` recipe may be left orphaned by the build.** + +There are exactly **48 `redbear-*` recipes** as of 2026-07-28 (verified by enumeration against +`local/recipes/`). All 48 are wired into `config/redbear-mini.toml [packages]`. Since +`config/redbear-full.toml` inherits from `config/redbear-mini.toml` via the include chain, every +`redbear-*` recipe is also present in the full ISO by transitive inheritance. + +Every `redbear-*` recipe MUST be reachable from at least one active Red Bear OS build config — +specifically `config/redbear-mini.toml` (the canonical first-class target). Library-only recipes +(zero `[[bin]]`, produces only a `.rlib`) are first-class citizens too — they are wired into +`redbear-mini` so the cookbook builds and stages the `.rlib`. Data-only recipes (firmware subsets, +D-Bus `.service` files, TOML policy files) are also first-class citizens — they ship files +into the stage and are consumed by other components. + +## Rationale + +The operator explicitly created each `redbear-*` recipe for a documented purpose. Per the +`local/AGENTS.md § ABSOLUTE RULE — NEVER DELETE`: + +> "If an agent decides something is 'not necessary', 'not required for boot', 'too heavy', +> or 'not needed' — that decision is WRONG. Always keep and fix." + +The corollary: leaving a `redbear-*` recipe **unreachable from the build** is structurally +equivalent to ignoring it — its source still lives in the tree, but its code, config files, +firmware, or services never ship to a Red Bear OS image. The next operator who runs a build +sees nothing from that recipe and reasonably concludes it is dead. This is exactly the failure +mode AGENTS.md warns against. + +Therefore: every `redbear-*` recipe MUST be in `redbear-mini.toml [packages]`. This is not a +recommendation — it is a build-time invariant. + +## Authoritative source of truth + +`local/AGENTS.md` is the canonical home for this rule. This doc is the change-log entry for +the rule's introduction. Any future addition of a new `redbear-*` recipe MUST be accompanied by +a `redbear-mini.toml` edit that wires the new recipe into `[packages]` in the same commit +(or in a tightly coupled follow-up commit). Code review MUST verify this wiring — a recipe +without wiring is a CI failure under the new policy. + +## Recipes that are NOT first-class citizens + +This policy applies only to `redbear-*` recipes under `local/recipes/*/`. The following +non-`redbear-*` artifacts are out of scope: + +- Upstream Redox recipes under `recipes/*/source/` (managed by upstream) +- Cat 2 fork subprojects under `local/sources//` (kernel, relibc, base, …) +- Cat 1 internal projects without a `redbear-` prefix: + - `local/recipes/system/cub/` + - `local/recipes/system/evdevd/` + - `local/recipes/system/udev-shim/` + - `local/recipes/system/driver-manager/` + - `local/recipes/system/driver-params/` + - `local/recipes/system/iommu/` + - `local/recipes/system/firmware-loader/` + - `local/recipes/system/cpufreqd/` + - `local/recipes/system/thermald/` + - `local/recipes/system/hwrngd/` + - `local/recipes/system/seatd/` + - `local/recipes/gpu/redox-drm/` + - `local/recipes/gpu/amdgpu/` + - `local/recipes/gpu/linux-kpi/` + - `local/recipes/drivers/redox-driver-sys/` + - `local/recipes/drivers/redox-driver-core/` + - `local/recipes/drivers/redox-driver-acpi/` + - `local/recipes/drivers/redox-driver-pci/` + - `local/recipes/drivers/linux-kpi/` + - `local/recipes/tui/tlc/` + - `local/recipes/tui/mc/` + - `local/recipes/libs/pam-redbear/` + - `local/recipes/libs/zbus/` + - `local/sources/base/redbear-ufw/` (in base fork, KEEP-ORPHAN — see REDBEAR-UFW-STATUS.md) + +These are governed by their own wiring rules (some are Cat 2 forks, some are build deps of +`redbear-*` programs). Adding a `redbear-` prefix is the canonical way to express +"first-class citizen of the OS image". + +## Worked example + +Before this rule: `redbear-firmware-amdgpu` was defined as a recipe but never appeared in +any `config/redbear-*.toml`. The cookbook silently never cooked it, the build image never +contained `/lib/firmware/amdgpu/`, and an operator reviewing the build output could not tell +whether the recipe was forgotten, broken, or intentional. + +After this rule: `redbear-firmware-amdgpu` is wired into `config/redbear-mini.toml` `[packages]`, +the cookbook cooks it on every `build-redbear.sh redbear-mini` invocation, and the firmware +subset is verifiable in `build//redbear-mini/`. + +## Complete inventory (48 recipes, verified 2026-07-28) + +All 48 `redbear-*` recipes are present in `config/redbear-mini.toml [packages]` and inherited by +`config/redbear-full.toml` via the include chain: + +``` +redbear-accessibility redbear-ecmd redbear-input-headers +redbear-acmd redbear-firmware redbear-iwlwifi +redbear-authd redbear-firmware-amdgpu redbear-keymapd +redbear-btctl redbear-firmware-bluetooth redbear-login-protocol +redbear-btusb redbear-firmware-intel redbear-meta +redbear-compositor redbear-firmware-iwlwifi redbear-mtr +redbear-dbus-services redbear-ftdi redbear-netctl +redbear-dnsd redbear-greeter redbear-netctl-console +redbear-driver-policy redbear-hid-core redbear-netstat +redbear-nmap redbear-sessiond redbear-traceroute +redbear-notifications redbear-session-launch redbear-tui-theme +redbear-passwd redbear-statusnotifierwatcher redbear-udisks +redbear-polkit redbear-release redbear-ufw +redbear-power redbear-hwutils redbear-upower +redbear-quirks redbear-ime redbear-usbaudiod +redbear-info redbear-usb-hotplugd redbear-wifictl +``` + +## Verification + +The new policy is verifiable by: + +```bash +# Every redbear-* recipe directory under local/recipes/ must be referenced in +# config/redbear-mini.toml (either directly or via an include chain). +for r in $(find local/recipes -maxdepth 3 -type d -name "redbear-*" | sort -u); do + prog=$(basename "$r") + if ! grep -rq "$prog" config/redbear-mini.toml 2>/dev/null && \ + ! grep -rq "$prog" config/*.toml 2>/dev/null; then + echo "ORPHAN: $prog" + fi +done +``` + +Zero `ORPHAN:` lines should print. Any operator running this script immediately sees policy +violations. The policy is enforced by the `local/scripts/sync-versions.sh` preflight gate +(planned Phase 4D CI addition) plus operator review. + +## Cross-references + +- `local/AGENTS.md § ABSOLUTE RULE — NEVER DELETE` — preservation rule +- `local/AGENTS.md § STUB AND WORKAROUND POLICY — ZERO TOLERANCE` — implementation quality +- `local/AGENTS.md § BRANCH AND SUBMODULE POLICY` — git workflow +- `local/docs/REDBEAR-ULW-ASSESSMENT-PLAN.md` — the systematic plan that produced this rule +- `local/docs/REDBEAR-UFW-STATUS.md` — the one KEEP-ORPHAN exception (in base fork, no recipe) diff --git a/local/docs/REDBEAR-UFW-STATUS.md b/local/docs/REDBEAR-UFW-STATUS.md new file mode 100644 index 0000000000..d888da7913 --- /dev/null +++ b/local/docs/REDBEAR-UFW-STATUS.md @@ -0,0 +1,87 @@ +# Red Bear UFW — Status Document + +**Date:** 2026-07-28 +**Status:** TRACKED AND BUILT FROM `redbear-mini` +**Authoritative Paths:** `local/sources/base/redbear-ufw/` source + `local/recipes/system/redbear-ufw/recipe.toml` wrapper recipe + +## Summary + +`redbear-ufw` is a Red Bear firewall frontend that lives inside the +`local/sources/base/` fork (the Red Bear OS fork of the upstream Redox `base` +recipe). As of 2026-07-28 it is wrapped by a tracked recipe and included in +`config/redbear-mini.toml`, which means every canonical Red Bear image now +builds it from the mini profile upward. + +## Why it originally existed only inside the base fork + +The UFW (Uncomplicated Firewall) prototype was started inside the base fork +during a previous iteration of the Red Bear networking stack. The prototype: + +- Has a complete `Cargo.toml` + `src/main.rs` (Rust, no stubs) +- Is intended to be a userspace firewall manager (akin to `ufw` on Debian) +- Was placed inside the base fork because early drafts co-evolved with the + base's network init scripts + +It originally stayed inside the base fork because it co-evolved with early +network-init work. That left it outside the recipe graph even though the code +was real and durable. + +The operator later clarified the policy for internal Red Bear programs: + +> All of the recipes starting from MINI must include ALL our internal projects. + +That instruction supersedes the earlier “prototype only” status. The correct +response was to promote `redbear-ufw` into the recipe graph rather than leaving +it stranded in the base fork. + +## Where it lives + +```text +local/sources/base/redbear-ufw/ +├── Cargo.toml +└── src/ + └── main.rs +``` + +The `local/sources/base/` directory is a git submodule tracked on the +`submodule/base` branch. The UFW source remains there. The tracked wrapper +recipe at `local/recipes/system/redbear-ufw/recipe.toml` points at that source +tree, so the canonical build now fetches, cooks, and stages the program without +duplicating the implementation. + +## Build wiring + +`redbear-ufw` is now included in `config/redbear-mini.toml`, which makes it +part of every higher-level Red Bear target (`redbear-full`, `redbear-grub`). +Runtime activation is still separate from compile-time inclusion: package +presence does not automatically mean the firewall is enabled. + +## Recovery note + +The source is preserved by the base fork's git history. If the wrapper recipe +ever needs recovery, the migration path remains: + +1. Copy `local/sources/base/redbear-ufw/{Cargo.toml,src/}` to + `local/recipes/system/redbear-ufw/source/`. +2. Recreate `local/recipes/system/redbear-ufw/recipe.toml`. +3. Re-wire `redbear-ufw = {}` into `config/redbear-mini.toml`. +4. Document the activation policy in + `local/docs/NETWORKING-IMPROVEMENT-PLAN.md`. + +## AGENTS.md compliance + +This status document follows the AGENTS.md rules: + +- **NEVER DELETE rule**: source is preserved in `local/sources/base/redbear-ufw/`. + No deletion. (See `local/AGENTS.md § ABSOLUTE RULE — NEVER DELETE`.) +- **STUB POLICY**: the UFW prototype contains a real Rust implementation + in `src/main.rs`. No stubs, no `#[cfg(feature = "stub")]` no-ops, no + shell-script wrappers. (See `local/AGENTS.md § STUB AND WORKAROUND POLICY`.) +- **Durability policy**: the source is committed to the base submodule + branch and survives every build operation. + +## See also + +- `local/sources/base/` — the base fork +- `local/AGENTS.md § ABSOLUTE RULE — NEVER DELETE` — preservation rule +- `local/recipes/system/redbear-netctl/` — current Red Bear networking stack diff --git a/local/recipes/gpu/redox-drm/recipe.toml b/local/recipes/gpu/redox-drm/recipe.toml index 724d659824..0504cb32bb 100644 --- a/local/recipes/gpu/redox-drm/recipe.toml +++ b/local/recipes/gpu/redox-drm/recipe.toml @@ -10,5 +10,8 @@ dependencies = [ ] [package] +name = "redox-drm" +version = "0.3.1" +description = "DRM/KMS scheme daemon — GPU driver manager supporting virtio-gpu, Intel, and AMD with auto-detection and PCI-driven driver dispatch." dependencies = [ ] diff --git a/local/recipes/system/redbear-netctl-console/recipe.toml b/local/recipes/system/redbear-netctl-console/recipe.toml index 6697f1224a..98196acf15 100644 --- a/local/recipes/system/redbear-netctl-console/recipe.toml +++ b/local/recipes/system/redbear-netctl-console/recipe.toml @@ -1,9 +1,11 @@ +[package] +name = "redbear-netctl-console" +version = "0.3.1" +description = "Network control console UI — TUI for redbear-netctl" + [source] path = "source" -[package] -dependencies = ["terminfo"] - [build] template = "cargo" dependencies = ["ncursesw"] diff --git a/local/recipes/system/redbear-ufw/recipe.toml b/local/recipes/system/redbear-ufw/recipe.toml new file mode 100644 index 0000000000..52440ad6d3 --- /dev/null +++ b/local/recipes/system/redbear-ufw/recipe.toml @@ -0,0 +1,10 @@ +[package] +name = "redbear-ufw" +version = "0.3.1" +description = "Uncomplicated Firewall frontend for Red Bear OS netfilter" + +[source] +path = "../../../sources/base/redbear-ufw" + +[build] +template = "cargo" diff --git a/local/recipes/tui/redbear-tui-theme/recipe.toml b/local/recipes/tui/redbear-tui-theme/recipe.toml new file mode 100644 index 0000000000..cd3bd1d9ec --- /dev/null +++ b/local/recipes/tui/redbear-tui-theme/recipe.toml @@ -0,0 +1,14 @@ +[package] +name = "redbear-tui-theme" +version = "0.3.1" +description = "Red Bear OS TUI palette crate — single source of truth for brand colours used by every TUI application" + +[source] +path = "source" + +[build] +template = "cargo" +dependencies = [] + +[package.files] +"/usr/lib/libredbear_tui_theme.rlib" = { _if_present = true }