Metadata-Version: 2.4
Name: forgepy-cli
Version: 1.0.0
Summary: Create structured Python projects and prepare their development tooling.
Author: Rendy Zou
License-Expression: MIT
Project-URL: Homepage, https://github.com/rzou89/ForgePy
Project-URL: Repository, https://github.com/rzou89/ForgePy
Project-URL: Issues, https://github.com/rzou89/ForgePy/issues
Keywords: python,project-generator,cli,windows
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# ForgePy

ForgePy is a Windows-focused command-line tool that creates structured Python projects and prepares their development tooling.

## What ForgePy Does

ForgePy generates a project from one of its built-in templates, creates a virtual environment, installs the generated requirements, writes VS Code configuration, and initializes the project as a Git repository with an initial commit. It also provides optional components that can add focused configuration files to an existing project.

## Requirements

- Windows 10 or Windows 11
- CPython 3.12 or newer
- Git, required for project creation and configured with the user name and email needed to create a commit

Other operating systems and alternative Python implementations are not officially supported for ForgePy v1.0.

Repository CI tests ForgePy on GitHub-hosted `windows-latest` runners using CPython 3.12, 3.13, and 3.14. This verifies compatibility with the hosted Windows environment; it does not literally test native Windows 10 and Windows 11 client installations.

## Installation

ForgePy is prepared for PyPI publication under the distribution name
`forgepy-cli`. After that first publication, install it with:

```powershell
python -m pip install forgepy-cli
```

The PyPI upload is still pending. Until it is completed, install from source as
described below or use the existing GitHub v1.0.0 release artifacts.

From a ForgePy source checkout, install the command with:

```powershell
python -m pip install .
```

For editable development work, use:

```powershell
python -m pip install -e .
```

## Quick Start

Check the installed versions and available templates:

```powershell
forgepy version
forgepy list
```

Create a basic project below an existing parent directory:

```powershell
forgepy create MyProject --location C:\Projects --template basic
cd C:\Projects\MyProject
```

The destination must not already exist. Omitting the project name or location starts the corresponding prompt; an omitted template uses the configured default and then falls back to `basic`.

## Available Templates

- `basic` - a basic application starter with a structured directory layout, `app.py`, project metadata, environment files, and generated requirements.
- `library` - a minimal reusable Python package with a normalized import-package directory and a `tests` package.
- `cli` - a minimal command-line package with `__main__.py`, an argparse interface, help and version behavior, and a `tests` package.

List the registered templates at any time with `forgepy list`.

## Components

Components add one focused configuration file to an explicitly supplied existing project directory. ForgePy records successful component installations in project-local state.

Available components are:

- `pytest` - adds `pytest.ini`.
- `ruff` - adds `ruff.toml`.
- `github-actions` - adds a minimal `.github/workflows/ci.yml` for the generated project.

Use the verified component commands:

```powershell
forgepy component list
forgepy component add pytest --project C:\Projects\MyProject
forgepy component installed --project C:\Projects\MyProject
```

Component installation refuses an owned target that already exists. The generated-project `github-actions` component is separate from ForgePy's own repository CI workflow.

## Configuration

ForgePy stores user configuration under `~/.forgepy/config.json`. Supported settings are `default_template`, `default_location`, `author`, and `license`.

```powershell
forgepy config show
forgepy config set default_template library
forgepy config set default_location C:\Projects
forgepy config reset
```

Only `default_template` and `default_location` currently affect project creation. `author` and `license` are persisted but are not applied to generated files.

Explicit `create` options take priority over configuration. See all supported syntax with:

```powershell
forgepy create --help
forgepy config --help
```

## Project Creation Lifecycle

A successful `forgepy create` runs these stages in order:

1. Generate the selected template.
2. Create `.venv`.
3. Update `pip`, `setuptools`, and `wheel` in that environment.
4. Install the generated `requirements.txt`.
5. Write VS Code configuration.
6. Run `git init`.
7. Run `git add .`.
8. Create the initial Git commit.
9. Report full success.

Git is a required part of successful project creation. Packaging-tool updates and dependency installation may require network access.

## Failure and Partial Projects

If creation fails after ForgePy creates the destination, later stages stop and full success is not reported. Files generated by earlier stages may remain in the destination because ForgePy does not automatically roll back or clean up a partial project.

Inspect the destination and remove it when appropriate before retrying. ForgePy project creation is not transactional or atomic.

## Development

Run the standard local validation from the repository root:

```powershell
python -m unittest discover -s tests -v
python -m compileall -q components cli templates core config builders models tests
```

Repository CI runs the test suite, compilation check, and packaging/support tests on `windows-latest` with CPython 3.12, 3.13, and 3.14. Its Python 3.12 job also builds and inspects the wheel and sdist, installs the wheel in isolation, and exercises the installed CLI.

See [CONTRIBUTING.md](CONTRIBUTING.md) for repository workflow and review expectations.

## Current Status

ForgePy v1.0.0 is the current stable Git tag and GitHub Release. The application
and command remain named ForgePy and `forgepy`; only the prepared PyPI
distribution name is `forgepy-cli`. Trusted Publishing is configured in the
repository, but the first PyPI upload has not occurred.

## License

ForgePy is licensed under the [MIT License](LICENSE).
