Metadata-Version: 2.4
Name: setup-wizard
Version: 0.1.6
Summary: Interactive project setup wizard for Python repos
Author-email: Your Name <you@example.com>
License: MIT License
        
        Copyright (c) 2025 Mirco Domenicale
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to
        deal in the Software without restriction, including without limitation the
        rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
        sell copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in
        all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
        FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
        DEALINGS IN THE SOFTWARE.
License-File: LICENSE
Keywords: bootstrap,cli,devtools,setup
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# setup-wizard

`setup-wizard` is a small, configurable CLI that bootstraps a Python project’s local dev environment:

- picks a suitable Python interpreter (e.g. 3.14),
- creates/reuses a virtualenv,
- installs dependencies,
- ensures a `.env` file exists,
- optionally installs dev tools (Black, Ruff, …),
- wires up VS Code launch configuration,
- runs a basic health check,
- and gives you a clear summary of what happened.

You define what it should do for each repo in a simple `setup_wizard.json` file, and then run:

```bash
setup-wizard
```

from the project root.

---

## Installation

You can install `setup-wizard` either as a global CLI (via `pipx`) or into a Python environment (via `pip`).

### Option 1: Global CLI with `pipx` (recommended)

```bash
pipx install setup-wizard
```

After that, the `setup-wizard` command is available globally:

```bash
setup-wizard --help
```

### Option 2: With `pip`

Inside any Python environment:

```bash
pip install setup-wizard
setup-wizard --help
```

---

## How it works (high level)

When you run `setup-wizard` inside a project directory, it:

1. **Loads configuration** from `./setup_wizard.json` (or uses defaults if missing).
2. **Finds a Python interpreter** that satisfies `min_python` (prefers `preferred_python` if available).
3. **Creates or reuses a virtualenv** in `venv_dir` (e.g. `.venv`), using `virtualenv` if available, falling back to stdlib `venv`.
4. **Installs dependencies** from `requirements` into that venv.
5. **Ensures a `.env` file** exists, copying from `env_example` if present.
6. Optionally **installs dev tools** (e.g. Black, Ruff) into the venv.
7. Optionally **updates `.vscode/launch.json`** by *appending* a debug configuration (without removing your existing ones) and can set Black as VS Code formatter.
8. Runs a **health check** by importing your configured application module (e.g. `am.app`), adding `./src` to `PYTHONPATH` if it exists.
9. Optionally **opens your project README** at the end.
10. Prints a **setup summary** with ✅ / ⚠️ / ❌ for each step.

All steps are interactive by default: the wizard explains what it’s about to do and asks for confirmation.

---

## Basic usage in a project

### 1. Add a `setup_wizard.json` to your repo

In your **project root**, create `setup_wizard.json`, for example:

```json
{
  "project_name": "my-service",
  "runtime": {
    "min_python": "3.11",
    "preferred_python": "3.14"
  },
  "paths": {
    "venv_dir": ".venv",
    "env_file": ".env",
    "env_example": ".env.example",
    "requirements": "requirements.txt",
    "app_import": "my_service.app",
    "readme": "README.md"
  },
  "dev_tools": [
    "black",
    "ruff"
  ],
  "vscode": {
    "enable_launch": true,
    "entry_module": "my_service.app",
    "debug_name": "my-service",
    "use_black_formatter": true,
    "extra_env": {
      "PYTHONPATH": "${workspaceFolder}/src"
    },
    "cwd": "${workspaceFolder}"
  }
}
```

Then document this in your project’s `README.md`:

## Local setup

This project uses the shared **setup-wizard** to set up a local dev environment.

```bash
setup-wizard
```

The wizard will create a virtualenv, install dependencies, ensure `.env` exists,
set up VS Code debug configuration, and run a small health check.

### 2. Run the wizard

From your project root:

```bash
setup-wizard
```

If you keep the config in a different location (e.g. `bootstrap/setup_wizard.json`):

```bash
setup-wizard --config bootstrap/setup_wizard.json
```

---

## Configuration reference (`setup_wizard.json`)

`setup_wizard.json` is a simple JSON file in the project directory. All fields are optional; sensible defaults are used when omitted.

### Top-level

```json
{
  "project_name": "my-service",
  "runtime": { },
  "paths": { },
  "dev_tools": [ ],
  "vscode": { }
}
```

#### `project_name` (string)

Human-readable name used in logs and as a default for VS Code debug config names (if `vscode.debug_name` is not set).

---

### `runtime` section

```json
"runtime": {
  "min_python": "3.11",
  "preferred_python": "3.14"
}
```

- `min_python` – minimum Python version required (major.minor); the wizard will refuse interpreters older than this.
- `preferred_python` – preferred version; if multiple interpreters satisfy `min_python`, the wizard tries to pick the highest, favoring this version when available.

---

### `paths` section

```json
"paths": {
  "venv_dir": ".venv",
  "env_file": ".env",
  "env_example": ".env.example",
  "requirements": "requirements.txt",
  "app_import": "my_service.app",
  "readme": "README.md"
}
```

- `venv_dir` – where to create/reuse the virtualenv.
- `env_file` – path to the `.env` file for local configuration.
- `env_example` – example env file to copy from if `.env` doesn’t exist.
- `requirements` – pip requirements file to install from.
- `app_import` – Python module path to import in the health check (`importlib.import_module(app_import)`).
- `readme` – path to your README file (used when optionally opening it at the end).

---

### `dev_tools` section

```json
"dev_tools": [
  "black",
  "ruff"
]
```

List of extra development tools to install into the venv. Common examples:

- formatters: `black`
- linters: `ruff`, `flake8`
- test tools: `pytest`, `pytest-cov`

The wizard will ask before installing them.

---

### `vscode` section

```json
"vscode": {
  "enable_launch": true,
  "entry_module": "my_service.app",
  "debug_name": "my-service",
  "use_black_formatter": true,
  "extra_env": {
    "PYTHONPATH": "${workspaceFolder}/src"
  },
  "cwd": "${workspaceFolder}"
}
```

- `enable_launch` (bool) – enable VS Code integration.
- `entry_module` (string) – module to run in debug mode (e.g. `my_service.app`).
- `debug_name` (string, optional) – name of the debug configuration in `launch.json`.  
  If omitted, defaults to `project_name`, or `"Python: Run app"` as a fallback.
- `use_black_formatter` (bool) – if true, configure VS Code to use Black as formatter and enable `editor.formatOnSave`.
- `extra_env` (object, optional) – extra environment variables to set in the debug config (e.g. `PYTHONPATH`).
- `cwd` (string, optional) – working directory for the debug config (e.g. `${workspaceFolder}`).

> The wizard **merges** into existing `.vscode/launch.json`:
>
> - it **preserves** existing configurations,
> - and **appends** its own config if one with the same `name` doesn’t already exist.  
> It will only offer to overwrite the file if it’s not valid JSON.

---

## CLI reference

```bash
setup-wizard [OPTIONS]
```

Options:

- `--config PATH`  
  Use a specific config file instead of `./setup_wizard.json`.

- `--python PATH_OR_CMD`  
  Force the target Python interpreter for the virtualenv, e.g.  
  `--python /usr/bin/python3.14` or `--python C:\Python314\python.exe`.

- `--check-only`  
  Run only the health checks, assuming the environment is already set up.  
  No venv creation, no dependency installation.

- `-y`, `--yes`  
  Non-interactive / “auto-yes” mode for non-destructive steps. The wizard will still log what it does, but won’t prompt for each confirmation.

---

## Notes & limitations

- The wizard cannot “activate” the virtualenv in your current shell (that’s a shell concern). It will create and use the venv for its own steps and then tell you how to activate it, e.g.:

  ```bash
  # PowerShell
  .\.venv\Scripts\Activate.ps1

  # cmd
  .\.venv\Scripts\activate.bat

  # bash/zsh
  source .venv/bin/activate
  ```

- For `src/`-style layouts (e.g. `src/my_service/app.py`), using:

  ```json
  "app_import": "my_service.app",
  "vscode": {
    "extra_env": {
      "PYTHONPATH": "${workspaceFolder}/src"
    }
  }
  ```

  lets both the health check and VS Code debug work out of the box.

---

If you run into something you’d like the wizard to automate (e.g. migrations, pre-commit install, docs preview), you can add new steps in your own fork or open an issue/PR to extend the core tool.
