Metadata-Version: 2.4
Name: pkgsmart
Version: 0.1.0
Summary: Smart cross-source package installer for Linux
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rapidfuzz
Requires-Dist: rich
Requires-Dist: typer
Dynamic: license-file

pkgsmart — From Optimized Script to Installable CLI (Step-by-Step Guide)

This document walks you through taking your optimized "pkgsmart" script and turning it into a fast, installable, and distributable CLI tool.

---

## Implementation Overview

The repository now reflects phases 2 through 6 as an actual package rather than only a script:

1. The CLI implementation lives in [pkgsmart/cli.py](pkgsmart/cli.py) and uses Typer for clean command-based argument parsing.
2. The package entry point is declared in [pyproject.toml](pyproject.toml) as `pkgsmart = "pkgsmart.cli:run"`.
3. The project includes a license file and can be installed in editable mode or via `pipx`.
4. The CLI supports subcommands: `pkgsmart rebuild`, `pkgsmart install <query>`, and `pkgsmart self-test`.
5. The build flow uses standard packaging tools so a wheel and source distribution can be generated locally.
6. Typer provides automatic help text and shell completion support.

---

🧭 OVERVIEW

You will go through 4 major phases:

1. Optimize your current script further
2. Restructure into a proper Python package
3. Install and test as a CLI tool
4. Prepare and publish for others to use

---

⚡ PHASE 1 — FINAL OPTIMIZATIONS (Before Packaging)

1. Precompute normalized fields (important)

Problem:

You currently normalize text during every search → unnecessary repeated work.

Fix (in index build step):

When building your index, store normalized values:

pkg = {
    "source": "APT",
    "name": name,
    "desc": desc,
    "name_n": normalize(name),
    "desc_n": normalize(desc)
}

Then update scoring:

name_n = pkg["name_n"]
desc_n = pkg["desc_n"]

Result:

- Faster searches
- Lower CPU usage

---

2. Add source bias (Mint-friendly)

APT should be preferred slightly.

In scoring:

if pkg["source"] == "APT":
    s += 5

---

3. Avoid ProcessPool overhead for small datasets

Wrap your search logic:

if len(index) < 5000:
    # run scoring in a simple loop
else:
    # use ProcessPoolExecutor

---

4. Add install history (optional but powerful)

Create:

~/.cache/pkgsmart/history.json

Store:

{
  "vscode": "APT"
}

Boost scoring:

if pkg["source"] == preferred_source:
    s += 10

---

📦 PHASE 2 — CONVERT INTO A PACKAGE

Status: implemented.

1. Create project structure

[pkgsmart/](pkgsmart)
├── [__init__.py](pkgsmart/__init__.py)
└── [cli.py](pkgsmart/cli.py)
[pyproject.toml](pyproject.toml)
[README.md](README.md)
[LICENSE](LICENSE)

---

2. Move your script

Move your code into:

[pkgsmart/cli.py](pkgsmart/cli.py)

---

3. Add entry function

At the bottom of "cli.py":

def run():
    main()

if __name__ == "__main__":
    run()

---

4. Create "pyproject.toml"

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "pkgsmart"
version = "0.1.0"
description = "Smart cross-source package installer for Linux"
authors = [
  { name="Your Name", email="you@example.com" }
]
readme = "README.md"
requires-python = ">=3.8"

dependencies = [
  "rapidfuzz",
  "rich"
]

[project.scripts]
pkgsmart = "pkgsmart.cli:run"

---

🚀 PHASE 3 — INSTALL & TEST LOCALLY

Status: implemented.

1. Install in development mode

`pip install -e .`

Test:

`pkgsmart install vscode`
`pkgsmart rebuild`

---

2. Install using pipx (recommended)

`sudo apt install pipx`
`pipx ensurepath`
`pipx install .`

Now your tool is globally available:

`pkgsmart install browser`

---

🧹 PHASE 4 — CLI POLISH (OPTIONAL BUT RECOMMENDED)

Status: implemented.

Upgrade to a proper CLI framework

Install:

`pip install typer`

Implementation:

The CLI now uses Typer with structured subcommands instead of manual argument parsing.

Commands:

- `pkgsmart install <query>` — Search for and install a package
- `pkgsmart rebuild` — Rebuild the local package index
- `pkgsmart self-test` — Verify ranking behavior

Features:

- Auto-generated `--help` for each command
- Shell completion support via `--install-completion`
- Type-safe argument validation

---

📝 PHASE 5 — DOCUMENTATION

Status: implemented.

The README now documents the package layout and usage instead of only the pre-packaging script flow.

Basic example:

`# pkgsmart`

Smart Linux package installer across APT, Flatpak, and Snap.

## Features
- Fast local indexing
- Fuzzy search
- Multi-source support

## Install
`pipx install pkgsmart`

## Usage
`pkgsmart install vscode`
`pkgsmart install browser --sources flatpak,snap`
`pkgsmart rebuild`
`pkgsmart self-test`

---

📦 PHASE 6 — BUILD PACKAGE

Status: implemented.

Install build tools:

`pip install build twine`

Build:

`python -m build`

This creates:

`dist/`
├── `pkgsmart-0.1.0.tar.gz`
└── `pkgsmart-0.1.0-py3-none-any.whl`

---

🌍 PHASE 7 — PUBLISH TO PYPI

1. Create account

Go to:
https://pypi.org

---

2. Upload package

twine upload dist/*

---

3. Install globally (test)

pipx install pkgsmart

---

🚀 FINAL RESULT

You now have:

- A fast indexed package search engine
- A global CLI tool ("pkgsmart")
- Cross-source installer (APT + Flatpak + Snap)
- Publicly installable tool via PyPI

---

🧠 NEXT-LEVEL IMPROVEMENTS (FUTURE)

After publishing, consider:

1. Web fallback

- Query APIs when no local match

2. Popularity ranking

- Use download stats

3. Config file

~/.config/pkgsmart/config.json

4. Shell integration

- Auto-suggest fixes for failed installs

---

🧭 SUMMARY

You’ve progressed from:

- Script → Optimized engine → Installable CLI → Distributable tool

This is a complete pipeline used in real-world CLI software development.

---

Follow these steps sequentially and you’ll end up with a polished, usable tool others can install and benefit from.
