Metadata-Version: 2.4
Name: setup-wizard
Version: 0.1.5
Summary: Interactive project setup wizard for Python repos
Author-email: Your Name <you@example.com>
License: MIT
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.
