forgepy-cli 1.0.0__tar.gz

forgepy_cli-1.0.0/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+This changelog records release-facing changes without assigning versions or dates that do not exist in repository history.
+
+## Unreleased
+
+### Changed
+
+- Prepared the first PyPI publication under the `forgepy-cli` distribution
+  name while preserving the ForgePy application name, `forgepy` command, and
+  canonical version `1.0.0`.
+- Updated current project URLs for `rzou89/ForgePy` and added a GitHub OIDC
+  Trusted Publishing workflow. No PyPI publication has occurred.
+
+## 1.0.0
+
+ForgePy 1.0.0 promotes the validated `1.0.0rc1` contents as the stable release
+without additional product changes. The `v1.0.0` tag and GitHub Release exist;
+no PyPI publication is claimed.
+
+## 1.0.0rc1
+
+This is the first ForgePy v1.0 release candidate, not the final v1.0.0
+release. It has not been published to PyPI.
+
+### Added
+
+- Added the `library` and `cli` templates alongside the existing `basic` starter.
+- Added project-local components for pytest, Ruff, and GitHub Actions, with explicit listing, installation, and installed-state commands.
+- Added persistent user configuration for default template and location selection.
+- Added standards-based setuptools packaging and the installed `forgepy` console command.
+- Added a public getting-started README and repository CI for CPython 3.12, 3.13, and 3.14 on GitHub-hosted Windows runners.
+- Added the maintainer-selected MIT License and corresponding package metadata.
+
+### Changed
+
+- Defined Windows 10 and Windows 11 on CPython 3.12+ as the intended v1.0 support contract.
+- Made Git initialization, staging, and the initial commit required for full project-creation success.
+- Ordered VS Code generation before Git so editor configuration is included in the initial commit.
+- Added finite timeouts and consistent operational failure reporting for external lifecycle commands.
+
+### Fixed
+
+- Hardened project-name, destination, symlink, junction, and component-state confinement checks.
+- Added package-name preflight so unusable library and CLI package identifiers fail before destination creation.
+- Stabilized CLI exit codes and handled-error output while preserving unexpected programming failures.
+- Made Windows tests compare equivalent resolved paths without weakening destination or state-safety assertions.
+
+## 0.6.0
+
+The repository tag `v0.6.0` marks this Sprint 6 baseline. Its tagged `config/version.py` still reported `0.4.0`, which is a historical metadata mismatch.
+
+- Established the tagged Sprint 6 baseline with the modular project generator, `basic` template, virtual-environment and requirements setup, VS Code configuration, and Git repository setup.

forgepy_cli-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rendy Zou
+
+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.

forgepy_cli-1.0.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include CHANGELOG.md
+prune tests
+prune utils

forgepy_cli-1.0.0/PKG-INFO

@@ -0,0 +1,176 @@
+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).

forgepy_cli-1.0.0/README.md

@@ -0,0 +1,153 @@
+# 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).

forgepy_cli-1.0.0/builders/base_builder.py

@@ -0,0 +1,17 @@
+"""
+==================================================
+ForgePy
+Module  : Base Builder
+==================================================
+"""
+
+
+class BaseBuilder:
+    """
+    Parent class seluruh Builder ForgePy.
+
+    Digunakan sebagai parent agar seluruh Builder
+    mempunyai struktur yang konsisten.
+    """
+
+    pass

forgepy_cli-1.0.0/builders/file_builder.py

@@ -0,0 +1,31 @@
+"""
+==================================================
+ForgePy
+Module  : File Builder
+==================================================
+"""
+
+from pathlib import Path
+
+from builders.base_builder import BaseBuilder
+
+
+class FileBuilder(BaseBuilder):
+
+    def write(
+        self,
+        path: Path,
+        content: str,
+    ) -> None:
+
+        path.parent.mkdir(
+            parents=True,
+            exist_ok=True,
+        )
+
+        path.write_text(
+            content,
+            encoding="utf-8",
+        )
+
+        print(f"[OK] File dibuat : {path}")

forgepy_cli-1.0.0/builders/folder_builder.py

@@ -0,0 +1,30 @@
+"""
+==================================================
+ForgePy
+Module  : Folder Builder
+==================================================
+"""
+
+from pathlib import Path
+
+from builders.base_builder import BaseBuilder
+
+
+class FolderBuilder(BaseBuilder):
+
+    def create(
+        self,
+        root: Path,
+        folders: list[str],
+    ) -> None:
+
+        for folder in folders:
+
+            path = root / folder
+
+            path.mkdir(
+                parents=True,
+                exist_ok=True,
+            )
+
+            print(f"[OK] Folder dibuat : {path}")

forgepy_cli-1.0.0/builders/python_tools_builder.py

@@ -0,0 +1,64 @@
+"""
+==================================================
+ForgePy
+Module  : Python Tools Builder
+==================================================
+"""
+
+import subprocess
+from pathlib import Path
+
+from builders.base_builder import BaseBuilder
+
+
+PACKAGE_TOOL_UPDATE_TIMEOUT_SECONDS = 300
+
+
+class PythonToolsBuilder(BaseBuilder):
+    """
+    Mengupdate pip, setuptools, dan wheel
+    pada Virtual Environment.
+    """
+
+    def update(
+        self,
+        project_path: Path,
+    ) -> None:
+
+        python = project_path / ".venv" / "Scripts" / "python.exe"
+
+        if not python.exists():
+            print("[WARNING] Virtual Environment belum tersedia.")
+            return
+
+        packages = [
+            "pip",
+            "setuptools",
+            "wheel",
+        ]
+
+        for package in packages:
+
+            print(f"[INFO] Mengupdate {package}...")
+
+            try:
+                subprocess.run(
+                    [
+                        str(python),
+                        "-m",
+                        "pip",
+                        "install",
+                        "--upgrade",
+                        package,
+                    ],
+                    check=True,
+                    timeout=PACKAGE_TOOL_UPDATE_TIMEOUT_SECONDS,
+                )
+            except subprocess.SubprocessError as error:
+                print(
+                    "[ERROR] Packaging-tool update failed for "
+                    f"'{package}': {error}"
+                )
+                raise
+
+            print(f"[OK] {package} berhasil diupdate.")

forgepy_cli-1.0.0/cli/__init__.py

@@ -0,0 +1,3 @@
+"""
+ForgePy CLI Package
+"""

forgepy_cli-1.0.0/cli/command.py

@@ -0,0 +1,52 @@
+"""
+==================================================
+ForgePy
+Module  : Base Command
+==================================================
+"""
+
+from abc import ABC, abstractmethod
+from argparse import ArgumentParser, Namespace
+
+
+class Command(ABC):
+    """
+    Kontrak dasar untuk seluruh command ForgePy.
+    """
+
+    name: str = ""
+    summary: str = ""
+    description: str = ""
+
+    def validate_registration(self) -> None:
+        """
+        Memastikan metadata command lengkap sebelum didaftarkan.
+        """
+
+        for field in (
+            "name",
+            "summary",
+            "description",
+        ):
+            if not getattr(self, field):
+                raise ValueError(
+                    f"Command '{type(self).__name__}' harus memiliki {field}."
+                )
+
+    def configure_parser(
+        self,
+        parser: ArgumentParser,
+    ) -> None:
+        """
+        Mendaftarkan argumen khusus command.
+
+        Command tanpa argumen dapat menggunakan implementasi default.
+        """
+        del parser
+
+    @abstractmethod
+    def execute(self, args: Namespace) -> int:
+        """
+        Menjalankan command dan mengembalikan status proses CLI.
+        """
+        raise NotImplementedError

forgepy_cli-1.0.0/cli/commands/__init__.py

@@ -0,0 +1,32 @@
+"""
+ForgePy Commands
+
+Seluruh command bawaan didaftarkan pada module ini.
+"""
+
+from cli.command import Command
+from cli.commands.component_command import ComponentCommand
+from cli.commands.config_command import ConfigCommand
+from cli.commands.create_command import CreateCommand
+from cli.commands.list_command import ListCommand
+from cli.commands.version_command import VersionCommand
+
+
+DEFAULT_COMMAND = "create"
+
+
+def create_commands() -> tuple[Command, ...]:
+    """
+    Membuat seluruh command bawaan dalam urutan tampilan CLI.
+
+    Command baru hanya perlu ditambahkan pada catalog ini agar parser
+    dan dispatcher menggunakan registrasi yang sama.
+    """
+
+    return (
+        CreateCommand(),
+        VersionCommand(),
+        ListCommand(),
+        ConfigCommand(),
+        ComponentCommand(),
+    )