Metadata-Version: 2.4
Name: jdi-blacksmith
Version: 0.4.0
Summary: A cross-platform CLI tool for installing development and cybersecurity tools
Author-email: jimididit <jimi.did.it@protonmail.com>
License-Expression: Apache-2.0
Keywords: cli,package-manager,development-tools,cybersecurity
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: pyyaml>=6.0
Dynamic: license-file

<h1 align="center">Blacksmith</h1>

<p align="center">
  Cross-platform CLI that installs curated development and cybersecurity<br>
  tool sets after a fresh OS install.
</p>

<p align="center">
  <a href="https://github.com/jimididit/blacksmith/actions/workflows/ci.yml"><img src="https://github.com/jimididit/blacksmith/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.8+-blue.svg" alt="Python 3.8+"></a>
  <a href="https://github.com/jimididit/blacksmith/releases"><img src="https://img.shields.io/badge/version-0.4.0-blue.svg" alt="Version 0.4.0"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-green.svg" alt="Apache 2.0"></a>
  <a href="https://github.com/jimididit/blacksmith"><img src="https://img.shields.io/badge/platform-Linux%20%7C%20Windows%20%7C%20macOS-lightgrey.svg" alt="Platform"></a>
</p>

<p align="center">
  <a href="#install">Install</a>
  &nbsp;&middot;&nbsp;
  <a href="#quick-start">Quick start</a>
  &nbsp;&middot;&nbsp;
  <a href="#commands">Commands</a>
  &nbsp;&middot;&nbsp;
  <a href="#configuration">Configuration</a>
  &nbsp;&middot;&nbsp;
  <a href="#package-managers">Package managers</a>
  &nbsp;&middot;&nbsp;
  <a href="#trust">Trust</a>
  &nbsp;&middot;&nbsp;
  <a href="#troubleshooting">Troubleshooting</a>
  &nbsp;&middot;&nbsp;
  <a href="#contributing">Contributing</a>
  &nbsp;&middot;&nbsp;
  <a href="SECURITY.md">Security</a>
</p>

## Features

- Pre-made sets: `development`, `cybersecurity`, `minimal` - see [Quick start](#quick-start)
- Custom YAML sets and a create wizard - see [Configuration](#configuration)
- Multiple package managers on Linux, Windows, and macOS - see [Package managers](#package-managers)
- Smart manager selection with OS preferences and fallback
- Automation flags: `--yes`, `--dry-run`, `--fail-fast` - see [Commands](#commands)
- Package ID allowlist for argv safety (not upstream existence or content trust) - see [Trust](#trust)
- Export to native manager formats - see [Commands](#commands)

## Install

Requires Python 3.8+ and at least one [supported package manager](#package-managers).

```bash
pip install jdi-blacksmith
blacksmith --version
```

### Virtualenv (recommended)

Linux / macOS:

```bash
python3 -m venv ~/.blacksmith-venv
source ~/.blacksmith-venv/bin/activate
pip install jdi-blacksmith
```

Windows (PowerShell):

```powershell
python -m venv $env:USERPROFILE\.blacksmith-venv
$env:USERPROFILE\.blacksmith-venv\Scripts\Activate.ps1
pip install jdi-blacksmith
```

From source: `git clone` the repo, then `pip install -e .`.

PATH or permission problems: [Troubleshooting](#troubleshooting).

## Quick start

```bash
blacksmith list
blacksmith install minimal --dry-run
blacksmith install minimal --yes
```

| Set | Focus |
|-----|-------|
| `development` | Git, Docker, editors, language toolchains |
| `cybersecurity` | Security and pentest tooling |
| `minimal` | Essentials (includes `brew:` IDs for macOS) |

Custom YAML and create wizard: [Configuration](#configuration). Flags and policy: [Commands](#commands). Shared files: [Trust](#trust).

## Commands

| Command | Purpose |
|---------|---------|
| `blacksmith` | Interactive menu |
| `blacksmith list` | List sets |
| `blacksmith info <set>` | Set details |
| `blacksmith install <set>` | Install a set |
| `blacksmith install <set> --dry-run` | Preview plan only |
| `blacksmith install <set> --yes` | Non-interactive (required without a TTY) |
| `blacksmith install <set> --fail-fast` | Stop on first package failure |
| `blacksmith install --file path.yaml --yes` | Install custom YAML ([untrusted](#trust)) |
| `blacksmith create` / `create --advanced` | Create a set |
| `blacksmith search <query> [--manager name]` | Search managers |
| `blacksmith export <set> --format <fmt>` | Export (`winget`, `chocolatey`, `apt`, `pacman`, `scoop`) |
| `blacksmith validate <path>` | Schema + ID allowlist check |
| `blacksmith uninstall [--yes]` | Remove Blacksmith |

Other install flags: `--skip-installed`, `--prefer <mgr>`, `--force` (ignore `target_os` mismatch).

**Policy:** default is best-effort continue after failures (no rollback). Each package installs individually.

**Privileges:** on Linux, apt / pacman / yum|dnf / snap may prompt for sudo. Flatpak and Homebrew do not use that path.

**Search note:** Snap and Flatpak support install, but `search` does not query them yet.

## Configuration

```yaml
name: "My Custom Set"
description: "My favorite tools"
target_os: ["windows", "linux", "macos"]
preferred_managers:
  windows: ["winget", "chocolatey"]
  linux: ["apt", "flatpak"]
  macos: ["brew"]
packages:
  - name: git
    managers:
      apt: git
      brew: git
      winget: Git.Git
      chocolatey: git
```

| Field | Required | Notes |
|-------|----------|-------|
| `name` | yes | Set name |
| `description` | no | Short summary |
| `target_os` | no | `windows`, `linux`, `macos` / `darwin` |
| `preferred_managers` | no | Per-OS manager order |
| `managers_supported` | no | Limit which managers are considered |
| `packages` | yes | Manager IDs must pass the [argv allowlist](#trust) |

Validate: `blacksmith validate path/to/config.yaml` (structure and allowlist only - not upstream existence).

## Package managers

| OS | Managers |
|----|----------|
| Linux | apt, yum/dnf, pacman, snap, flatpak |
| Windows | winget, chocolatey, scoop |
| macOS | brew (Homebrew formulas and casks) |

Selection uses set `preferred_managers` when present, otherwise OS defaults (winget then chocolatey then scoop on Windows; brew on macOS), then any other available managers.

macOS: Darwin is detected; Homebrew is registered when `brew` is on `PATH`. The `minimal` set includes `brew:` IDs. Broader brew coverage across other sets, MacPorts, and brew export are later work. Install Homebrew: https://brew.sh

## Trust

Treat set YAML like code you are willing to run. Package ID allowlists block shell metacharacters; they do not prove packages are safe or exist upstream. Third-party `--file` YAML is untrusted - review it, prefer `--dry-run`, then `--yes`.

Threat model, reporting vulnerabilities, and a safe review workflow: [SECURITY.md](SECURITY.md).

```bash
blacksmith validate path/to/set.yaml
blacksmith install --file path/to/set.yaml --dry-run
blacksmith install --file path/to/set.yaml --yes
```

## Troubleshooting

**Command not found after install**

- Prefer a [virtualenv](#install) so the entry point stays on PATH while activated.
- Linux/macOS user install: add `$HOME/.local/bin` to `PATH`.
- Windows user install: add the user `Scripts` directory from `python -m site --user-base` to PATH.
- Fallback: `python -m blacksmith --version`

**Permission errors**

Use `pip install --user jdi-blacksmith` instead of `sudo pip` / admin installs.

## Contributing

Do not push directly to `main`. Use a feature branch and a PR; merge only when the required **CI** check is green.

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow.

## License

Apache 2.0 - see [LICENSE](LICENSE).

## Changelog

See [CHANGELOG.md](CHANGELOG.md).

## Author

**jimididit**

- GitHub: [@jimididit](https://github.com/jimididit)
- Website: [www.jimididit.com](https://jimididit.com)
- Discord: [Nokturnal Community](https://jimididit.com/discord)
