spm-cli 0.1.0

Soft Package Manager - Universal cross-platform metapackage manager

                                      ███████╗██████╗ ███╗   ███╗
                                      ██╔════╝██╔══██╗████╗ ████║
                                      ███████╗██████╔╝██╔████╔██║
                                      ╚════██║██╔═══╝ ██║╚██╔╝██║
                                      ███████║██║     ██║ ╚═╝ ██║
                                      ╚══════╝╚═╝     ╚═╝     ╚═╝

Soft Package Manager — The ultimate offline-first, cross-platform metapackage manager written in Rust.

---

[!WARNING] DEMO VERSION (v0.1 Beta) This utility is currently a working prototype/demo. It has been extensively tested and heavily optimized for Windows (combining Winget, Chocolatey, and Scoop into a flawless experience).

Linux & macOS Support: While SPM technically runs and works fine on macOS and Linux (via apt, brew, pacman), it currently doesn't fully unleash its potential there. The primary focus of this release is solving the fragmented package ecosystem on Windows. In the long-term, massive updates are planned to bring full first-class native parity to Linux and macOS!

📖 What is SPM?

SPM (Soft Package Manager) is a lightning-fast, universal abstraction layer over your system's native package managers. Instead of remembering the exact commands and package names for winget, scoop, chocolatey, apt, pacman, or brew, you interact with a single, unified interface.

SPM intelligently routes your commands to the best native package manager on your system, maintaining a centralized SQLite database to track what you have installed, regardless of how it was installed.

Key Features

• 🚀 Blazing Fast: Written in pure Rust. Zero bloat, zero runtime overhead.
• 🔌 Universal Native Binding: Automatically detects and uses winget, scoop, apt, brew, pacman, and choco.
• 🧠 Offline Match Engine: Resolves common aliases (e.g., discord, vscode) to their true native IDs (e.g., Discord.Discord) instantly, without querying external REST APIs.
• 💾 Centralized State: Maintains an ACID-compliant SQLite database of all your apps.
• 🛠️ Data-Driven Plugins: Extend SPM with 0 lines of code by writing simple TOML templates that use Regex to parse CLI output.

---

⚡ Installation

SPM is built for everyone and distributed across all major packaging hubs. Choose your favorite engine to install it globally.

Cargo (Rust Native)

cargo install spm-cli

PyPI (Python)

pip install spm-cli

NPM (Node.js)

npm install -g spm-cli

Homebrew (MacOS/Linux)

brew install spm-cli/tap/spm

Paru / Yay (Arch Linux)

paru -S spm-cli-bin

Setup Script (Curl)

curl -fsSL https://spm.sh/install | bash

---

🏗️ Architecture

SPM features a highly decoupled, modern CLI architecture:

1. The Match Engine: An embedded offline database of 30,000+ app definitions. When you type spm install vlc, the Match Engine instantly translates it into absolute native targets (e.g., VideoLAN.VLC).
2. The Planner: SPM ranks available package managers heuristically. pacman and winget receive top priority, while slower engines fall back gracefully. The Planner generates a transaction sequence before touching your system.
3. Async Native Adapters: All package manager wrappers implement an asynchronous PackageManager trait. Instead of recreating the wheel, SPM acts as an intelligent orchestrator directly streaming native outputs to your terminal.
4. SQLite State Management: Upon successful execution, the transaction is committed to ~/.config/spm/spm.db (or %APPDATA%), allowing unified lists and instant removals.

---

🕹️ Command Reference

SPM uses standard, intuitive verbs for all operations.

📦 Smart Installation

Automatically resolve the best ID and install via the optimal manager.

spm install obsidian

Tip: append --dry-run to see the Execution Plan without acting on it.

🧹 Unified Removal

Remove applications tracked across any package manager effortlessly.

spm remove obsidian

🔄 Global Updates

Update a single app, or trigger a massive, concurrent update across all package managers at once.

spm update

📋 Tracked List

Display a brilliantly formatted ASCII table of all tracked applications across the OS.

spm list

🩺 System Diagnostics

Run a health check on your active native environments and plugins.

spm doctor

🌐 Self-Update

Pull the absolute latest release instantly without re-invoking pip/npm/cargo.

spm self-update

---

🧩 TOML Plugin System (v1.0)

Forget writing messy Python or Lua wrappers. SPM introduces Data-Driven Plugins. By placing a simple .toml file in ~/.config/spm/plugins/, you can teach SPM how to command any CLI tool using internal Regex parsing.

Example cargo.toml plugin mapping:

name = "cargo"
is_available_cmd = "cargo --version"
install_cmd = "cargo install {pkg}"
remove_cmd = "cargo uninstall {pkg}"
update_all_cmd = "cargo install-update -a"
update_pkg_cmd = "cargo install {pkg} --force"
list_cmd = "cargo install --list"
list_regex = "(?P<name>[\\w-]+) v(?P<version>[\\d\\.]+):"

Place the file, type spm doctor, and within 100 milliseconds SPM has synthesized an active, native rust-equivalent driver!

---

📜 License

Distributed under the MIT License. Build beautiful things.