Crate pacsea 

Pacsea Crate Overview

Pacsea bundles the core event loop, data pipelines, and UI helpers that power the pacsea terminal application. Integration tests and downstream tooling can depend on this crate to drive the runtime without going through the binary entrypoint.

Why Pacsea?

TUI-first workflow: Navigate Arch + AUR results with instant filtering, modal install previews, and keyboard-first ergonomics.

Complete ecosystem coverage: Async workers query official repos, the AUR, mirrors, and Arch news so you can browse and act from one dashboard.

Aggressive caching & telemetry: Persistent caches (app::persist) and ranked searches (util::match_rank) keep navigation snappy while structured tracing calls expose bottlenecks.

Highlights

• TUI runtime (app::runtime) orchestrating async tasks, caches, and rendering.
• Modular subsystems for install flows, package index querying, and translation loading.
• Reusable helpers for theme paths, serialization, and UI composition.

Crate Layout

• app: runtime, caches, and persistence glue for the interactive TUI.
• events, logic, install: event handling and command execution pipelines.
• index, sources: Arch/AUR metadata fetchers plus enrichment.
• state, theme, ui, util: configuration, rendering, and misc helpers.

Quick Start

use pacsea::app;
use tracing_subscriber::EnvFilter;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let filter = EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("pacsea=info"));
    tracing_subscriber::fmt()
        .with_env_filter(filter)
        .with_target(false)
        .init();

    // Drive the full TUI runtime (set `true` for dry-run install previews)
    app::run(false).await?;
    Ok(())
}

See src/main.rs for the full CLI wiring (argument parsing, log file setup, and mode flags).

Subsystem Map

Module	Jump points	Responsibilities
app	app::run, app::sandbox_cache, app::services_cache	Terminal runtime orchestration, cache persistence, sandbox + service metadata.
events	events::search, events::recent	Keyboard/mouse dispatchers that mutate state::AppState.
logic	logic::send_query, logic::deps::resolve_dependencies	Core business rules for querying indices, ranking, and dependency analysis.
install	install::command, install::spawn_install, install::spawn_remove_all	Batch + single install orchestration, scan integrations, terminal helpers.
index	index::load_from_disk, index::all_official, index::save_to_disk	Persistent Arch index management and enrichment queues.
state	state::AppState, state::types::PackageItem	Shared UI/runtime data model and domain structs.
theme & ui	theme::settings, ui::middle, ui::details	Theme resolution, keymaps, and ratatui component tree.
util	util::match_rank, util::repo_order, util::ts_to_date	Pure helpers for scoring, formatting, and sorting.

Testing Hooks

• pacsea::global_test_mutex() / pacsea::global_test_mutex_lock() serialize tests that mutate global environment variables or touch shared caches.
• state::test_mutex() (private) is used inside state tests; prefer the crate-level guard for integration suites that spawn the runtime.

#[tokio::test]
async fn installs_are_serialized() {
    let _guard = pacsea::global_test_mutex_lock();
    std::env::set_var("PATH", "/tmp/pacsea-tests/bin");
    // run test body that mutates process globals
}

Common Tasks

Kick off a search programmatically

use pacsea::logic::send_query;
use pacsea::state::{AppState, QueryInput};
use tokio::sync::mpsc;

fn trigger_query(term: &str) {
    let mut app = AppState {
        input: term.to_string(),
        ..Default::default()
    };
    let (tx, _rx) = mpsc::unbounded_channel::<QueryInput>();
    send_query(&mut app, &tx);
}

Inject a fake official index during tests

use pacsea::index::{load_from_disk, OfficialIndex, OfficialPkg};
use std::collections::HashMap;
use std::path::PathBuf;

fn seed_index() {
    let mut tmp = PathBuf::from(std::env::temp_dir());
    tmp.push("pacsea_index_fixture.json");
    let snapshot = OfficialIndex {
        pkgs: vec![OfficialPkg {
            name: "pacsea-demo".into(),
            repo: "extra".into(),
            arch: "x86_64".into(),
            version: "1.0".into(),
            description: "fixture".into(),
        }],
        name_to_idx: HashMap::new(), // Skipped during serialization
    };
    std::fs::write(&tmp, serde_json::to_string(&snapshot).unwrap()).unwrap();
    load_from_disk(&tmp);
    let _ = std::fs::remove_file(tmp);
}

The modules listed below link to detailed documentation for each subsystem.

Modules

announcements

Announcement system supporting both version-embedded and remote announcements.

app

Pacsea application module (split from a single large file into submodules).

events

Event handling layer for Pacsea’s TUI (modularized).

i18n

Internationalization (i18n) module for Pacsea.

index

Official package index management, persistence, and enrichment.

install

Modular install subsystem.

logic

Core non-UI logic split into modular submodules.

sources

Network and system data retrieval module split into submodules.

state

Modularized state module.

theme

Theme system for Pacsea.

ui

TUI rendering for Pacsea.

util

Small utility helpers for encoding, JSON extraction, ranking, and time formatting.