Pacsea Roadmap

August 8, 2026 · View on GitHub

Last updated: 2026-07-31 (arch-toolkit migration reconciled against local/remote 0.3.0 source; other roadmap baselines unchanged)

This is the master tracking document for planned implementations. It replaces and consolidates former planning docs (FEATURE_PRIORITY.md, CLI_POSSIBLE_COMMANDS.md, CLI_LIBRARY_INTEGRATORS.md, IMPLEMENTATION_PLAN_arch-toolkit.md, IMPLEMENTATION_PLAN_tui_integrated_config_editing.md, improvement_suggestions.md, pacsea_soname_plan.md, PERFORMANCE_IMPLEMENTATION_PRIORITY.md, REFACTORING_EVALUATION.md, ARCHITECTURE_OTHER.md), keeping only open work. Shipped items were dropped; see CHANGELOG.md for release history. Large initiatives may have one canonical execution plan under plans/planned/; this roadmap links to that plan instead of duplicating its TODOs.

How to track:

Check off roadmap items (and note the release/PR) when they ship.
Items carry a priority tier and, where one exists, a GitHub issue link.
Detail sections hold concise context or a pointer to the initiative's sole canonical plan.

Priority tiers

Tier	Meaning	Horizon
🔴 P1	High impact, reasonable complexity, core UX/CLI correctness	Next 1–2 releases
🟠 P2	Good value, moderate complexity, extends existing systems	Next 3–4 releases
🟡 P3	Valuable for specific use cases, medium effort	Roadmap items
🟢 P4	Niche or higher complexity, community-driven	Future consideration
🔵 P5	Major architectural change, long-term vision	Future major version

Master tracking list

🔴 P1 — Next 1–2 releases

CLI --update respects settings.conf — --mirrors opt-in mirror refresh uses selected_countries/mirror_count; new aur_helper settings key honored by all CLI helper resolution (historic bug #57, closed; shipped for v0.8.3 in PR #163 / dev/RELEASES/RELEASE_v0.8.3.md)
CLI -R / remove-from-file — implemented with -I parity (#93, closed; shipped for v0.8.3 in PR #163 / dev/RELEASES/RELEASE_v0.8.3.md)
Honor --config-dir — process-wide override in theme::paths covering config resolvers, caches (lists), and logs (shipped for v0.8.3 in PR #163 / dev/RELEASES/RELEASE_v0.8.3.md)
Global --json output — schema_version envelope for --search, --list, --news (shipped for v0.8.3 in PR #163 / dev/RELEASES/RELEASE_v0.8.3.md; updates check still future) → CLI §C5
Preflight guardrails — pacman db-lock (blocks, CLI + TUI), disk space and sync-db staleness warnings with actionable fixes (shipped for v0.8.3 in PR #163 / dev/RELEASES/RELEASE_v0.8.3.md; richer dry-run/confirm UX remains P2) → UX §U1
Refactor: unify command execution — shared util::command runner (CommandRunner/SystemCommandRunner/CommandError + run_capture + binary_available); logic/preflight, logic/services, and util/pacman delegate; duplicated paru/yay probes consolidated (shipped for v0.8.3 in PR #163 / dev/RELEASES/RELEASE_v0.8.3.md; interactive/PTY spawns intentionally stay separate) → Refactoring §R1
Refactor: consolidate cache modules — shared app/cache_common.rs (match modes, load/save, signatures); the four cache modules and persist.rs flush fns are thin wrappers, on-disk format unchanged (shipped for v0.8.3 in PR #163 / dev/RELEASES/RELEASE_v0.8.3.md) → Refactoring §R1

🟠 P2 — Next 3–4 releases

🟡 P3 — Roadmap items

🟢 P4 — Future consideration

Dependency conflict resolution wizard — interactive conflict handling (part of #134) → Features §F5
Custom upgrade commands / pre-post hooks (part of #134) → Features §F5
System tray / panel integration (#129) → Features §F7
AUR maintainer tools — PKGBUILD updates, pushing, co-maintainers (part of #130)
CLI niche commands — config get|set|validate, theme show, keybinds list, --print-default-config, man, --locale, unlock (heavily gated) → CLI §C4
Architecture: Command enum + query layer — explicit user-action command routing (undo/macro-friendly), memoized computed properties → Refactoring §R2
Config editor Phase 4 — polish: reset row (Ctrl+Z), mtime conflict warning, effective-config export (Ctrl+E), help-overlay section — shipped in PR #161 → Config editing §E1
Soname Layer 2 (early) — repo-wide provided-sonames database, reverse dependency index, cascade calculator → Soname §S2

🔵 P5 — Long-term vision

v1.0.0 stable release — polish, stability, documentation, community feedback pass
Embedded Arch wiki viewer (part of #130)
Multi package manager support — apt, dnf, Flatpak behind a PackageManager trait; Flatpak first since it coexists with pacman (#130, v2.0 scale)
Subcommand-first CLI redesign — pacsea pkg|aur|repo|cache|config … with legacy flags as hidden aliases → CLI §C4
Soname Layer 2 (late) — mirror-sync watcher with automated cascade reporting; optional makechrootpkg build verification → Soname §S2
UI: incremental/dirty-region rendering — architectural change → Performance §P1
Architecture: TEA / CQRS-lite re-evaluation — only if a large refactor is approved; event sourcing / full Redux / component frameworks remain not recommended → Refactoring §R2

GitHub issue cross-reference (open, last synced 2026-07-03; shipped issues removed 2026-07-05)

Issue	Topic	Tier
#145	Mirror search/selection UI	🟡 P3
#140	Focus/hover discoverability (tooltips)	🟠 P2
#134	Upgrades, rebuilds, conflicts umbrella	🟡 P3 / 🟢 P4
#131	Distro-specific news	🟠 P2
#130	AUR maintainer tools, embedded wiki, multi-PM	🟢 P4 / 🔵 P5
#129	Accessibility themes + system tray	🟡 P3 / 🟢 P4
#104	Update GitHub-tracked packages	🟡 P3
#102	Optional-dependency descriptions	🟡 P3
#99	Service restart logic	🟡 P3
#98	Transaction abort logic	🟡 P3
#97	Config value validation	🟡 P3
#95	Sequential multi-package scans	🟡 P3
#94	`parse_update_entry` tests	🟡 P3
#159	Executable bits on helper scripts	🟡 P3

Recently shipped (for context): v0.8.3 release notes cover PR #163's CLI JSON / -R file / --config-dir / guardrail / command-cache refactor batch (dev/RELEASES/RELEASE_v0.8.3.md); PR #161 completed integrated config editing Phases 1–4; PR #164 refreshed Hungarian translations. Earlier: custom repos + PKGBUILD checks + AUR voting (v0.8.0, #132/#133/#137); adjustable pane heights and pane order via main_pane_order + per-role min/max (v0.8.2, #135/#136).

Detail sections

Features

F2. Tooltips

Tooltip component appearing after ~500 ms hover/focus, positioned near the focused element, descriptions pulled from the i18n system. Help overlay (?) already covers keybinds.

F3. Distro news

Add RSS URLs per distro (EOS, Manjaro, Garuda, CachyOS); detect current distro from /etc/os-release (already in src/logic/distro.rs); allow switching source or combined feed; handle per-source date formats. Infrastructure: src/sources/news.rs.

F4. Mirror browser

Modal over existing mirror data (src/index/mirrors.rs, repository/mirrors.json): search, country/speed filtering, last-sync/protocol columns, multi-select with ranking.

F5. Upgrades umbrella (#134)

Criticality grouping: classify critical packages (linux, systemd, glibc, …), group/sort in the update modal, visual indicators, reboot recommendation.
Service restart guidance (#99): identify units needing restart after updates; show a restart plan (dry-run capable).
Transaction abort (#98): cancellation UX for running transactions.
Conflict wizard (P4): parse pacman conflict output, offer interactive resolution; risky — design carefully.
Custom upgrade commands (P4): user-defined pre/post hooks; mind arbitrary-command security.

F6. Smaller tracked features

Sequential multi-package AUR scans (#95)
Optional-dep descriptions (#102) — fetch/show descriptions for optional dependencies from ALPM/AUR metadata.
GitHub-tracked package updates (#104)
Config value validation (#97) — validate settings.conf/theme.conf/keybinds.conf/repos.conf values on load with clear diagnostics.
parse_update_entry tests (#94)
Helper script executable bits (#159)

F7. Accessibility (#129)

theme-high-contrast.conf with WCAG-compliant colors, ASCII alternatives to Unicode symbols, screen-reader testing where terminals allow. System tray / panel integration tracked in the same issue (P4).

CLI

Current implemented surface lives in src/args/definition.rs + handlers under src/args/. Note: src/args/args.rs duplicates the Args struct (incl. an unexported --refresh); treat as historical until reconciled.

C2. Scripting & parity subcommands (P2)

C3. Roadmap subcommands (P3)

Extended pkg queries (files, owns, deps, provides, conflicts, orphans, foreign, native, group, required-by, structured search); news fetch|list|show|mark-read|mark-unread and advisories list; files pacnew|pacsave|merge, backup list|create, db sync-status; services affected / services restart --dry-run (#99); sandbox analyze, security advisories --installed; repo apply [--all], repo key-fetch, repo foreign-overlap; aur scan batch (#95), aur comments|pkgbuild fetch|srcinfo|vote-status; transaction helpers sync, upgrade --aur-only, downgrade, reinstall, clean — all respecting --dry-run.

C4. Niche commands (P4) and structural redesign (P5)

C5. Integrator contracts

For crate consumers (src/lib.rs) and subprocess integrators:

Single JSON envelope with top-level schema_version, bumped on breaking changes.
Parseable payloads only on stdout; diagnostics on stderr (--json-errors for structured errors: stable {"error":{"code","message","detail"}}).
--output-format json|jsonl (jsonl for large streams); optional PACSEA_JSON=1 env inherit.
No TTY assumptions; respect NO_COLOR / --no-color.
Introspection (P2/P3): api version (binary/crate version, json_schema_version, target triple), api capabilities (tool presence, OS family, effective privilege_tool/helper), api paths (resolved config/cache/log dirs), api exit-codes (documented exit-code map).

Prioritization axes when picking CLI work: scripting value → TUI parity → low coupling (thin wrappers over logic::*) → safety (--dry-run + privilege rules for anything touching pacman.conf, keys, or systemctl).

UX / workflow improvements

Diagrams: dev/WORKFLOWS/developer/*.mmd (mirrored under manager/).

U1. Cross-cutting preflight

Disk space check before install/remove/update with actionable hints (logic/preflight/guardrails.rs)
Mirror health check + fix guidance before risky operations (sync-db staleness heuristic; deeper mirror-status checks can build on it)
Pacman db-lock detection + what to do (wait, remove stale lock, …) — blocks CLI and TUI transactions with guidance
Richer dry-run: conflicts, reverse deps/orphans, rough size/time estimate
Unified "what will happen" confirm + optional per-item overrides
Resilience: lock-aware retry, mirror/helper fallback UX (beyond silent paru/yay fallback), links to structured logs
State recovery: resumable batches, rollback hints after partial failure

U2. Per-flow improvements

Removal (batch): base/protected-package guard with typed confirm or hard block; orphan cleanup preview + staged cleanup; blocked-item reasons surfaced with guided retry; parallel dry-run dep checks where safe. System update: optional pre-snapshot/rollback note + disk/mirror pre-checks; conflict auto-scope/assist; guided retry (alternate helper/mirror) with log reference; reboot scheduling (now / later / remind). Install (batch): continue-on-failure toggle + retry actions; stronger parallel prefetch/reuse of resolved deps; optional post-install hooks or checklist. Install (direct from results): clear metadata errors with retry/alternate source; inline dry-run deps/conflicts when bypassing full preflight; explicit UI retry keeping selection. Downgrade (batch): cache versions/signatures + provenance/integrity before confirm; rollback/package-hold guidance after success; pre-download + verify before mutation; skip/unhold suggestions when the target is unavailable. App startup: single blocking popup queue ordered by priority; remember modal dismissals per session; stale-cache notice with last refresh + optional background refresh; offline notice with limited actions + retry timer.

Performance

P1. Open optimizations

OfficialIndex.pkgs: Vec → map/B-tree keyed structure only if profiling shows benefit (repeated sorts today)
Stream/progressively expose search results to the UI (currently collect-then-render; network latency dominates — low priority)
Stronger lazy/on-demand index loading (beyond "load from disk when empty")
Tighten remaining .iter().any() / retain patterns in installed/removal lists
Optional trie/BK-tree for fuzzy search (low priority — SkimMatcherV2 acceptable)
Incremental/dirty-region UI rendering (architectural, P5)
criterion benches for hot paths before optimizing (seed 1K/10K/100K packages; watch for O(n²) scaling)

Already implemented (kept out of the list): name-index HashMap, list HashSets, search result memoization, sort-cache O(n) reordering, LRU recent searches, PKGBUILD parse disk-LRU, incremental PKGBUILD highlighting, ring prefetch, PKGBUILD fetch rate limits.

Refactoring & architecture

R1. Priority refactors

Unify command execution (P1): ✅ shipped. Shared abstraction in util/command.rs; logic/preflight/command.rs re-exports it, logic/services/command.rs and util/pacman.rs delegate, capability probes use binary_available. Remaining inline Command::new query sites (e.g. args/package.rs) can migrate opportunistically; interactive/PTY/platform-gated spawns stay separate by design.
Consolidate cache modules (P1): ✅ shipped. Shared app/cache_common.rs (signatures, exact/subset/intersection match modes, load/save, generic flush); the four cache modules are thin wrappers with unchanged public APIs and byte-compatible files.
Dedupe package validation (P2): six similar validators in args/package.rs.
util/config.rs (P2): adopt the existing string helpers in the 13 files with inline parsing, or delete the unused module.
Lower-effort items (P3+): modal/handler structure and event-routing cleanup; JSON load/save helpers; temp-path test utility; handler HashSet extraction.

R2. Architecture backlog

Incremental, none mandated:

Short-term: split AppState into domain substates (search, install, preflight, ui, …) without breaking runtime/message flow; group preflight channels into a struct; extract pure business logic from fat handlers into testable modules.
Medium-term: explicit user-action Command enum routing all mutations (undo/macro-friendly); query layer / memoized computed properties on hot paths.
Long-term (optional): revisit TEA vs CQRS-lite only if a large refactor is approved. Event sourcing, full Redux, and component frameworks were evaluated and are not recommended.

arch-toolkit migration

The sole active checklist is plans/planned/arch-toolkit-0.3.0-integration.md. It targets the newest 0.3.0 source line, reconciles the deleted historical plan and the archived toolkit Phase 6 handoff, and replaces the stale v0.2.x, repos-apply, and system::privilege assumptions previously recorded here. This section intentionally contains no duplicate TODOs.

Integrated config editing (TUI)

Let users view/change configuration in-app. Current state: dedicated AppMode::ConfigEditor with file list, searchable key list, details pane, and edit popups; settings.conf, keybinds.conf, and theme.conf are editable end-to-end, while repos.conf is visible but still disabled as follow-up work. Preserve comments and unknown keys (line-oriented patch strategy); respect dry-run (no writes, clear message). Raw buffer editing remains a later option. Key code: src/state/config_editor.rs, src/events/modals/config_editor.rs, src/ui/modals/config_editor/, src/theme/config/{schema,patch,settings_save,skeletons,theme_loader}.rs, src/theme/settings/parse_keybinds.rs, src/theme/types.rs.

E1. Phased rollout

Phase 1 — editor shell (ConfigEditor state + keybind), General tab over existing save_* helpers, read-only display of active config paths, dry-run gating + error surfacing
Phase 2 — keybinds tab: render from Settings.keymap, capture mode (swallow keys until chord/Esc; conflict validation), persist to keybinds.conf with round-trip tests
Phase 3 — theme tab: edit canonical keys, validate via try_load_theme_from_content before save, keep last good theme in memory; optional revert-to-skeleton (per-row reset via Ctrl+Z shipped instead)
Phase 4 — polish: undo/reset row, mtime-changed warning, export effective config, help overlay entries for new keybinds

Shipped support: static editable-schema tables, line-oriented patch helpers, dry-run no-write behavior, key-capture validation, same-scope keybind conflict checks, theme pre-commit validation, mtime conflict warning/explicit overwrite, row reset, help-overlay entries, and effective-config export.

E2. Follow-up work

Enable repos.conf/Advanced editing only after apply safety, path validation, and dry-run semantics are specified for repository mutations.
Make live-apply/reload behavior explicit per setting family (theme already validates before commit and reloads the palette; remaining settings/keybind behavior should be documented in schema/UI copy).
Gate or warn on privilege/security-sensitive settings such as auth_mode and privilege-tool related keys.
Decide whether raw buffer editing is still worth adding after the structured editor shipped.

Soname-aware dependency checking

Detect DT_NEEDED vs on-disk SONAME mismatches before transactions commit. Linux-only (#[cfg(target_os = "linux")]). No soname module exists yet; goblin not in Cargo.toml. Primary integration point: Modal::Preflight (src/state/modal.rs, src/ui/modals/preflight/, src/events/preflight/) — new Soname tab or Summary panel, reusing the lazy tab-sync pattern. Never run ldd on untrusted paths (it executes loaders); parse ELF in-process.

S1. Layer 1 — end-user protection

goblin-based DT_NEEDED/DT_SONAME readers (src/soname/), unit tests on fixture ELFs incl. malformed/non-ELF; skip linux-vdso.so.1-style virtuals; path-safety consistent with is_safe_abs_path invariants
On-disk soname map: walk /usr/lib, /usr/lib32 (std read_dir is enough), handle symlink chains, multilib arch-tagging, duplicate providers
Post-transaction SONAME extraction from /var/cache/pacman/pkg/*.pkg.tar.zst (needs tar+zstd/xz deps or controlled subprocess) — unlocks sound WillBreakAfterUpdate; reuse find_aur_package_file scan logic in src/logic/preflight/metadata.rs
Consumer selection: pacman -Ql/-Qo strategy with aggressive per-session caching
Preflight tab + i18n + event wiring; severity chips matching existing patterns; dry-run safe
SystemUpdate flow parity decision (route through Preflight or inline warning)

S2. Layer 2 — ecosystem tooling

Repo-wide provided-sonames database (scan local mirror .pkg.tar.*, or ingest Arch's sogrep links DBs; SQLite/flat index refreshed post-rsync)
Reverse dependency index (soname → dependent packages; richer than per-query sogrep)
Cascade calculator (BFS/DFS over soname edges; complements arch-rebuild-order's syncdb view)
Mirror-sync watcher + automated soname-bump reports (the novel piece)
Build verification via makechrootpkg (stretch; separate daemon/subcommand territory)

Deps to pin at implementation time: goblin (verify elf32/elf64/endian_fd features), tar + zstd/xz, optional rusqlite for Layer 2.

Update this file whenever roadmap work ships or new work is planned. Security remediation work is tracked separately in SECURITY_REMEDIATION_GUIDE.md (mandated by CLAUDE.md); demo storyboard in dev/pacsea_demo_storyboard.md; current architecture reference in dev/ARCHITECTURE_CURRENT.md.