aim/.architecture/roadmap.md

# UPM Roadmap

## Direction

The project is evolving from a focused AppImage manager into `upm`, a modular universal package manager. The target system manages multiple package-manager modules through a shared headless application core, keeps frontend crates thin, and leaves room for future GUI frontends.

The initial rename-and-extraction slice has now landed as a hard cutover: the runtime surface is `upm`, the shared core is `upm-core`, and AppImage support is beginning its transition into `upm-appimage` instead of remaining embedded directly into the core.

The near-term goal is a Linux-first platform with honest cross-platform architecture. Phase 2 will implement Linux package sources while establishing the abstractions needed for later macOS support and possible Windows support.

## Confirmed Product Decisions

- `aim-cli` becomes `upm`.
- `aim-core` stops being the all-in-one backend and is split.
- AppImage support becomes an installable module named `upm-appimage`.
- Shared orchestration, config, state, resolution, ranking, and frontend-facing APIs move into `upm-core`.
- The `upm` crate becomes a thin CLI frontend over `upm-core`.
- A future `upm-ui` crate will become a GUI frontend over the same `upm-core` application boundary.
- The rename is a hard cutover. Legacy `AIM_*` runtime interfaces are removed rather than preserved.
- The declarative package file starts in a hybrid mode and is intended to become the source of truth over time.
- Every `upm` invocation should detect drift between declared state and observed system state, then auto-sync metadata as needed.
- Phase 2 is Linux implementation first, with macOS-oriented provider abstractions and packaging seams designed now.
- Feature delivery should happen as vertical slices rather than a single large refactor.
- The `upm` branch is the effective trunk for this evolution work and should be treated as the integration base for future UPM feature branches and worktrees.

## Architectural Destination

### Workspace Shape

The intended workspace shape after the initial refactor is:

- `upm`: thin CLI frontend, ratatui config UI, command routing, presentation.
- `upm-ui`: future GUI frontend over the same application core.
- `upm-core`: headless application layer, public application facade, internal orchestration services, module registry, state model, declarative sync engine, ranking, policies, and frontend-agnostic APIs.
- `upm-appimage`: AppImage package-manager module extracted from the current `aim-core` implementation.
- future module crates: `upm-pacman`, `upm-aur`, `upm-flatpak`, `upm-cargo`, `upm-npm`, and later macOS or Windows-specific modules.

### Module Model

UPM should stay modular in both code and packaging:

- modules can be enabled or disabled by config
- providers can be ranked by user priority
- distro packaging can offer grouped installs such as `upm-full`
- lighter installs can ship only the core and selected modules

This means module capabilities, discovery, search, install, remove, inspect, and sync behavior need stable interfaces in `upm-core` rather than package-manager-specific branching in the CLI or GUI.

The public API shape should be one application facade in `upm-core`, backed by smaller internal services. Frontends should call the facade; they should not compose lower-level services or talk directly to modules.

### State Model

The long-term model is declarative and config-first, but Phase 2 begins with a hybrid approach:

- `upm`-managed actions update the declarative config directly
- `upm update` and normal command entrypoints can inspect live system state
- drift detection reconciles unmanaged or changed packages into the config representation
- over time the config becomes authoritative and reconciliation becomes stricter

## Phase 2 Milestones

### Milestone 0: Rename And Split Foundation

Deliver the naming and ownership transition without changing product scope yet.

Goals:

- rename workspace crates and package outputs from `aim` to `upm`
- create `upm-core` by extracting reusable infrastructure from `aim-core`
- reduce the CLI crate to a frontend over headless APIs
- isolate current AppImage-specific logic into `upm-appimage`
- remove direct AppImage composition from the CLI and move module composition into `upm-core`
- preserve current AppImage functionality and tests during the move

Exit criteria:

- `upm` binary replaces `aim`
- workspace builds under new crate names
- AppImage flows still work end-to-end through the new layering

### Milestone 1: AppImage On The New Core

Make the current AppImage implementation the first real package-manager module on the modular architecture.

Goals:

- establish `upm-core` as the sole application boundary for CLI and future GUI frontends
- validate the module contract using AppImage as the reference implementation
- move AppImage-specific acquisition backends behind `upm-appimage`
- prove the CLI can treat AppImage as just one enabled module

Exit criteria:

- AppImage support is no longer special-cased as the whole product
- CLI command paths run through the `upm-core` application facade
- AppImage acquisition minutia no longer lives as top-level application concepts in `upm-core`

### Milestone 2: Linux Native Sources

Add the first non-AppImage providers as Linux-focused vertical slices.

Initial supported sources:

- pacman
- AUR
- Flatpak
- cargo global installs
- npm global installs

Goals:

- implement provider discovery and capability coverage for each source
- normalize package identity, version, installed state, and update candidates across providers
- support search, inspect, install, remove, and update planning where each provider can do so safely
- capture provider limitations explicitly rather than faking uniformity

Exit criteria:

- multi-source search works across enabled providers
- installs and removals work through a consistent command model
- provider-specific metadata is normalized enough for ranking and sync

### Milestone 3: Provider Priority And Config UX

Expose modularity directly in the terminal interface.

Goals:

- build a ratatui configuration menu
- allow enablement and disablement per provider
- allow explicit search and install priority ordering
- allow configuration of module weight, source preference, and future policy toggles
- make search ranking obey configured priority instead of hard-coded source bias

Exit criteria:

- users can manage provider selection and ranking from the TUI
- search results are explainable in terms of configured preference order

### Milestone 4: Declarative Package State And Drift Sync

Introduce the nix-like experience incrementally.

Goals:

- define the declarative package file format in `config.toml` or a closely related managed file
- track installed packages by provider in a normalized state model
- implement `upm update` as both package refresh and state reconciliation
- scan currently installed packages from supported providers and build or refresh the declared package set
- auto-sync detected drift during any `upm` command invocation

Phase 2 intent:

- begin in hybrid mode
- move steadily toward config-first behavior
- avoid destructive reconciliation until provider semantics are trustworthy

Exit criteria:

- users can bootstrap a declarative package definition from the current machine state
- repeated `upm` runs keep declared and observed state aligned
- state drift is surfaced clearly and reconciled predictably

### Milestone 5: Packaging, Distribution, And Platform Seams

Make the modular architecture real at packaging time, not just in code.

Goals:

- define packaging layout for standalone core, selected modules, and full installs
- support distro-level grouped packages such as `upm-full`
- ensure unsupported modules degrade cleanly on the wrong OS or distro
- add macOS provider and packaging seams to `upm-core` even if Linux remains the only implemented provider set in Phase 2

Exit criteria:

- module packaging strategy is documented and testable
- cross-platform abstractions exist without blocking Linux delivery

## Phase 2 Non-Goals

The following are explicitly not required to complete Phase 2:

- full macOS module implementation
- Windows module implementation
- GUI frontend delivery
- forcing strict config-authoritative reconciliation before provider behavior is stable
- shipping every conceivable Linux package manager in the first expansion

## Success Criteria

Phase 2 is successful when the project can credibly be described as a modular package manager rather than an AppImage manager with extra adapters.

That means:

- the product name, workspace shape, and binary identity are all `upm`
- AppImage support is only one module among several
- Linux users can manage packages from the first targeted provider set
- ranking and enablement are user-controlled through config and TUI
- declarative state exists, is importable from the live system, and stays synchronized through normal use
- the architecture is ready for GUI and later platform expansion without another major rewrite

## Immediate Planning Order

Implementation plans should follow this order:

1. rename and crate extraction
2. application facade definition and AppImage migration behind a real module boundary
3. Linux provider onboarding in a stable order, likely `pacman` then `Flatpak`, then `AUR`, then `cargo`, then `npm`
4. ratatui configuration and ranking UX
5. declarative state model, drift detection, and `update` sync behavior
6. packaging layout and `upm-full` distribution strategy

This order keeps the refactor defensible, gives each slice a usable product outcome, and avoids locking future provider work into AppImage-era assumptions.