pypeline-runner 1.6.0__tar.gz → 1.8.0__tar.gz

{pypeline_runner-1.6.0 → pypeline_runner-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pypeline-runner
-Version: 1.6.0
+Version: 1.8.0
 Summary: Configure and execute pipelines with Python (similar to GitHub workflows or Jenkins pipelines).
 License: MIT
 Author: cuinixam
@@ -26,7 +26,13 @@ Project-URL: Documentation, https://pypeline-runner.readthedocs.io
 Project-URL: Repository, https://github.com/cuinixam/pypeline
 Description-Content-Type: text/markdown
 
-# Pypeline
+<p align="center">
+<a href="https://pypeline-runner.readthedocs.io">
+<img align="center" src="https://github.com/cuinixam/pypeline/raw/main/logo.png" width="400"/>
+</a>
+</p>
+
+# pypeline - Define Your CI/CD Pipeline Once, Run It Anywhere
 
 <p align="center">
   <a href="https://github.com/cuinixam/pypeline/actions/workflows/ci.yml?query=branch%3Amain">
@@ -58,28 +64,71 @@ Description-Content-Type: text/markdown
   <img src="https://img.shields.io/pypi/l/pypeline-runner.svg?style=flat-square" alt="License">
 </p>
 
-Pypeline is a Python application designed to streamline and automate the software development lifecycle, particularly the pipeline execution processes across various environments such as GitHub and Jenkins.
-The primary motivation for developing Pypeline stemmed from the need to unify and simplify the creation of build, test, and deployment pipelines that are traditionally defined separately across these platforms using GitHub workflows (YAML) and Jenkins pipelines (Jenkinsfile).
+Pypeline lets you define your build, test, and deployment pipeline in a single YAML file and run it _consistently_ across your local development environment and _any_ CI/CD platform (GitHub Actions, Jenkins, etc.). No more platform-specific configurations – write once, run anywhere.
 
 **Key Features**
 
 - **Unified Pipeline Definition**: Users can define their entire pipeline in a single YAML file, eliminating the need to switch between different syntaxes and configurations for different CI/CD tools.
 
-- **Extensibility**: Pypeline supports execution steps defined not only through local scripts but also from installed Python packages.
-
-- **Execution Context**: Each step in the pipeline receives an execution context that can be updated during step execution. This allows for the sharing of information and state between steps.
+- **Extensibility**: Pypeline supports execution steps defined not only through installed Python packages but also from local scripts.
 
-- **Dependency Handling**: Dependency management ensures that only the necessary steps are executed, reducing runtime and resource usage by avoiding unnecessary operations.
+- **Execution Context**: Allow sharing information and state between steps. Each step in the pipeline receives an execution context that can be updated during step execution.
 
-- **Ease of Use**: With Pypeline, setting up and running pipelines becomes more straightforward, enabling developers to focus more on coding and less on configuring pipeline specifics.
+- **Dependency Handling**: Every step can register its dependencies and will only be scheduled if anything has changed.
 
 ## Installation
 
-Install this via pip (or your favourite package manager):
+Use pipx (or your favorite package manager) to install and run it in an isolated environment:
+
+```shell
+pipx install pypeline-runner
+```
+
+This will install the `pypeline` command globally, which you can use to run your pipelines.
 
-`pip install pypeline-runner`
+> [!NOTE]
+> The Python package is called `pypeline-runner` because the name `pypeline` was already taken on PyPI.
+> The command-line interface is `pypeline`.
 
-## Start developing
+Documentation: [pypeline-runner.readthedocs.io](https://pypeline-runner.readthedocs.io)
+
+## Walkthrough: Getting Started with Pypeline
+
+To get started run the `init` command to create a sample project:
+
+```shell
+pypeline init --project-dir my-pipeline
+```
+
+The example project pipeline is defined in the `pipeline.yaml` file.
+
+```yaml
+pipeline:
+  - step: CreateVEnv
+    module: pypeline.steps.create_venv
+    config:
+      bootstrap_script: .bootstrap/bootstrap.py
+  - step: WestInstall
+    module: pypeline.steps.west_install
+    description: Download external modules
+  - step: MyStep
+    file: steps/my_step.py
+    description: Run a custom script
+```
+
+This pipeline consists of three steps:
+
+- `CreateVEnv`: This is a built-in step that creates a Python virtual environment.
+- `WestInstall`: This is a built-in step that downloads external modules using the `west` tool.
+- `MyStep`: This is a custom step that runs a script defined in the `steps/my_step.py` file.
+
+You can run the pipeline using the `run` command:
+
+```shell
+pypeline run --project-dir my-pipeline
+```
+
+## Contributing
 
 The project uses Poetry for dependencies management and packaging.
 Run the `bootstrap.ps1` script to install Python and create the virtual environment.
@@ -88,43 +137,22 @@ Run the `bootstrap.ps1` script to install Python and create the virtual environm
 .\bootstrap.ps1
 ```
 
-This will also generate a `poetry.lock` file, you should track this file in version control.
-
 To execute the test suite, call pytest inside Poetry's virtual environment via `poetry run`:
 
 ```shell
 .venv/Scripts/poetry run pytest
 ```
 
-Check out the Poetry documentation for more information on the available commands.
-
 For those using [VS Code](https://code.visualstudio.com/) there are tasks defined for the most common commands:
 
-- bootstrap
-- install dependencies
 - run tests
 - run all checks configured for pre-commit
 - generate documentation
 
 See the `.vscode/tasks.json` for more details.
 
-## Committing changes
-
 This repository uses [commitlint](https://github.com/conventional-changelog/commitlint) for checking if the commit message meets the [conventional commit format](https://www.conventionalcommits.org/en).
 
-## Contributors ✨
-
-Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
-
-<!-- prettier-ignore-start -->
-<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
-<!-- markdownlint-disable -->
-<!-- markdownlint-enable -->
-<!-- ALL-CONTRIBUTORS-LIST:END -->
-<!-- prettier-ignore-end -->
-
-This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
-
 ## Credits
 
 This package was created with [Copier](https://copier.readthedocs.io/) and the [cuinixam/pypackage-template](https://github.com/cuinixam/pypackage-template) project template.

{pypeline_runner-1.6.0 → pypeline_runner-1.8.0}/README.md

@@ -1,4 +1,10 @@
-# Pypeline
+<p align="center">
+<a href="https://pypeline-runner.readthedocs.io">
+<img align="center" src="https://github.com/cuinixam/pypeline/raw/main/logo.png" width="400"/>
+</a>
+</p>
+
+# pypeline - Define Your CI/CD Pipeline Once, Run It Anywhere
 
 <p align="center">
   <a href="https://github.com/cuinixam/pypeline/actions/workflows/ci.yml?query=branch%3Amain">
@@ -30,28 +36,71 @@
   <img src="https://img.shields.io/pypi/l/pypeline-runner.svg?style=flat-square" alt="License">
 </p>
 
-Pypeline is a Python application designed to streamline and automate the software development lifecycle, particularly the pipeline execution processes across various environments such as GitHub and Jenkins.
-The primary motivation for developing Pypeline stemmed from the need to unify and simplify the creation of build, test, and deployment pipelines that are traditionally defined separately across these platforms using GitHub workflows (YAML) and Jenkins pipelines (Jenkinsfile).
+Pypeline lets you define your build, test, and deployment pipeline in a single YAML file and run it _consistently_ across your local development environment and _any_ CI/CD platform (GitHub Actions, Jenkins, etc.). No more platform-specific configurations – write once, run anywhere.
 
 **Key Features**
 
 - **Unified Pipeline Definition**: Users can define their entire pipeline in a single YAML file, eliminating the need to switch between different syntaxes and configurations for different CI/CD tools.
 
-- **Extensibility**: Pypeline supports execution steps defined not only through local scripts but also from installed Python packages.
-
-- **Execution Context**: Each step in the pipeline receives an execution context that can be updated during step execution. This allows for the sharing of information and state between steps.
+- **Extensibility**: Pypeline supports execution steps defined not only through installed Python packages but also from local scripts.
 
-- **Dependency Handling**: Dependency management ensures that only the necessary steps are executed, reducing runtime and resource usage by avoiding unnecessary operations.
+- **Execution Context**: Allow sharing information and state between steps. Each step in the pipeline receives an execution context that can be updated during step execution.
 
-- **Ease of Use**: With Pypeline, setting up and running pipelines becomes more straightforward, enabling developers to focus more on coding and less on configuring pipeline specifics.
+- **Dependency Handling**: Every step can register its dependencies and will only be scheduled if anything has changed.
 
 ## Installation
 
-Install this via pip (or your favourite package manager):
+Use pipx (or your favorite package manager) to install and run it in an isolated environment:
+
+```shell
+pipx install pypeline-runner
+```
+
+This will install the `pypeline` command globally, which you can use to run your pipelines.
 
-`pip install pypeline-runner`
+> [!NOTE]
+> The Python package is called `pypeline-runner` because the name `pypeline` was already taken on PyPI.
+> The command-line interface is `pypeline`.
 
-## Start developing
+Documentation: [pypeline-runner.readthedocs.io](https://pypeline-runner.readthedocs.io)
+
+## Walkthrough: Getting Started with Pypeline
+
+To get started run the `init` command to create a sample project:
+
+```shell
+pypeline init --project-dir my-pipeline
+```
+
+The example project pipeline is defined in the `pipeline.yaml` file.
+
+```yaml
+pipeline:
+  - step: CreateVEnv
+    module: pypeline.steps.create_venv
+    config:
+      bootstrap_script: .bootstrap/bootstrap.py
+  - step: WestInstall
+    module: pypeline.steps.west_install
+    description: Download external modules
+  - step: MyStep
+    file: steps/my_step.py
+    description: Run a custom script
+```
+
+This pipeline consists of three steps:
+
+- `CreateVEnv`: This is a built-in step that creates a Python virtual environment.
+- `WestInstall`: This is a built-in step that downloads external modules using the `west` tool.
+- `MyStep`: This is a custom step that runs a script defined in the `steps/my_step.py` file.
+
+You can run the pipeline using the `run` command:
+
+```shell
+pypeline run --project-dir my-pipeline
+```
+
+## Contributing
 
 The project uses Poetry for dependencies management and packaging.
 Run the `bootstrap.ps1` script to install Python and create the virtual environment.
@@ -60,43 +109,22 @@ Run the `bootstrap.ps1` script to install Python and create the virtual environm
 .\bootstrap.ps1
 ```
 
-This will also generate a `poetry.lock` file, you should track this file in version control.
-
 To execute the test suite, call pytest inside Poetry's virtual environment via `poetry run`:
 
 ```shell
 .venv/Scripts/poetry run pytest
 ```
 
-Check out the Poetry documentation for more information on the available commands.
-
 For those using [VS Code](https://code.visualstudio.com/) there are tasks defined for the most common commands:
 
-- bootstrap
-- install dependencies
 - run tests
 - run all checks configured for pre-commit
 - generate documentation
 
 See the `.vscode/tasks.json` for more details.
 
-## Committing changes
-
 This repository uses [commitlint](https://github.com/conventional-changelog/commitlint) for checking if the commit message meets the [conventional commit format](https://www.conventionalcommits.org/en).
 
-## Contributors ✨
-
-Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
-
-<!-- prettier-ignore-start -->
-<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
-<!-- markdownlint-disable -->
-<!-- markdownlint-enable -->
-<!-- ALL-CONTRIBUTORS-LIST:END -->
-<!-- prettier-ignore-end -->
-
-This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
-
 ## Credits
 
 This package was created with [Copier](https://copier.readthedocs.io/) and the [cuinixam/pypackage-template](https://github.com/cuinixam/pypackage-template) project template.

{pypeline_runner-1.6.0 → pypeline_runner-1.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pypeline-runner"
-version = "1.6.0"
+version = "1.8.0"
 description = "Configure and execute pipelines with Python (similar to GitHub workflows or Jenkins pipelines)."
 authors = ["cuinixam <me@cuinixam.com>"]
 license = "MIT"
@@ -36,6 +36,7 @@ pytest = "^8.3"
 pytest-cov = "^6.0"
 pre-commit = "^4.0"
 ruff = "^0.9"
+west = "^1.3"
 
 [tool.poetry.group.docs.dependencies]
 myst-parser = ">=0.16"

pypeline_runner-1.8.0/src/pypeline/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.8.0"

{pypeline_runner-1.6.0 → pypeline_runner-1.8.0}/src/pypeline/domain/artifacts.py

@@ -10,13 +10,10 @@ CONFIG_FILENAME = "pypeline.yaml"
 class ProjectArtifactsLocator:
     """Provides paths to project artifacts."""
 
-    def __init__(
-        self,
-        project_root_dir: Path,
-    ) -> None:
+    def __init__(self, project_root_dir: Path, config_file: Optional[str] = None) -> None:
         self.project_root_dir = project_root_dir
         self.build_dir = project_root_dir / "build"
-        self.config_file = project_root_dir / CONFIG_FILENAME
+        self.config_file = project_root_dir.joinpath(config_file if config_file else CONFIG_FILENAME)
         self.external_dependencies_dir = self.build_dir / "external"
         scripts_dir = "Scripts" if sys.platform.startswith("win32") else "bin"
         self.venv_scripts_dir = self.project_root_dir.joinpath(".venv").joinpath(scripts_dir)

pypeline_runner-1.8.0/src/pypeline/domain/pipeline.py

@@ -0,0 +1,181 @@
+import importlib
+from abc import abstractmethod
+from dataclasses import dataclass
+from importlib.util import module_from_spec, spec_from_file_location
+from pathlib import Path
+from typing import (
+    Any,
+    Dict,
+    Generic,
+    Iterator,
+    List,
+    Optional,
+    OrderedDict,
+    Protocol,
+    Tuple,
+    Type,
+    TypeAlias,
+    TypeVar,
+    Union,
+)
+
+from mashumaro import DataClassDictMixin
+from py_app_dev.core.exceptions import UserNotificationException
+from py_app_dev.core.runnable import Runnable
+
+from .execution_context import ExecutionContext
+
+
+@dataclass
+class PipelineStepConfig(DataClassDictMixin):
+    #: Step name or class name if file is not specified
+    step: str
+    #: Path to file with step class
+    file: Optional[str] = None
+    #: Python module with step class
+    module: Optional[str] = None
+    #: Step class name
+    class_name: Optional[str] = None
+    #: Command to run. For simple steps that don't need a class. Example: run: [echo, 'Hello World!']
+    run: Optional[Union[str, List[str]]] = None
+    #: Step description
+    description: Optional[str] = None
+    #: Step timeout in seconds
+    timeout_sec: Optional[int] = None
+    #: Custom step configuration
+    config: Optional[Dict[str, Any]] = None
+
+
+PipelineConfig: TypeAlias = Union[List[PipelineStepConfig], OrderedDict[str, List[PipelineStepConfig]]]
+
+TPipelineStep = TypeVar("TPipelineStep", covariant=True)
+
+
+@dataclass
+class PipelineStepReference(Generic[TPipelineStep]):
+    """Once a Step is found, keep the Step class reference to be able to instantiate it later."""
+
+    group_name: Optional[str]
+    _class: Type[TPipelineStep]
+    config: Optional[Dict[str, Any]] = None
+
+    @property
+    def name(self) -> str:
+        return self._class.__name__
+
+
+class PipelineConfigIterator:
+    """
+    Iterates over the pipeline configuration, yielding group name and steps configuration.
+
+    This class abstracts the iteration logic for PipelineConfig, which can be:
+    - A list of steps (group name is None)
+    - An OrderedDict with group names as keys and lists of steps as values.
+
+    The iterator yields tuples of (group_name, steps).
+    """
+
+    def __init__(self, pipeline_config: PipelineConfig) -> None:
+        self._items = pipeline_config.items() if isinstance(pipeline_config, OrderedDict) else [(None, pipeline_config)]
+
+    def __iter__(self) -> Iterator[Tuple[Optional[str], List[PipelineStepConfig]]]:
+        """Return an iterator."""
+        yield from self._items
+
+
+class StepClassFactory(Generic[TPipelineStep], Protocol):
+    def create_step_class(self, step_config: PipelineStepConfig, project_root_dir: Path) -> Type[TPipelineStep]: ...
+
+
+class PipelineLoader(Generic[TPipelineStep]):
+    def __init__(self, pipeline_config: PipelineConfig, project_root_dir: Path, step_class_factory: Optional[StepClassFactory[TPipelineStep]] = None) -> None:
+        self.pipeline_config = pipeline_config
+        self.project_root_dir = project_root_dir
+        self.step_class_factory = step_class_factory
+
+    def load_steps_references(self) -> List[PipelineStepReference[TPipelineStep]]:
+        result = []
+        for group_name, steps_config in PipelineConfigIterator(self.pipeline_config):
+            result.extend(self._load_steps(group_name, steps_config, self.project_root_dir, self.step_class_factory))
+        return result
+
+    @staticmethod
+    def _load_steps(
+        group_name: Optional[str], steps_config: List[PipelineStepConfig], project_root_dir: Path, step_class_factory: Optional[StepClassFactory[TPipelineStep]] = None
+    ) -> List[PipelineStepReference[TPipelineStep]]:
+        result = []
+        for step_config in steps_config:
+            step_class_name = step_config.class_name or step_config.step
+            if step_config.module:
+                step_class = PipelineLoader[TPipelineStep]._load_module_step(step_config.module, step_class_name)
+            elif step_config.file:
+                step_class = PipelineLoader[TPipelineStep]._load_user_step(project_root_dir.joinpath(step_config.file), step_class_name)
+            else:
+                if step_class_factory:
+                    step_class = step_class_factory.create_step_class(step_config, project_root_dir)
+                else:
+                    raise UserNotificationException(
+                        f"Step '{step_class_name}' has no 'module' nor 'file' defined nor a custom step class factory was provided. Please check your pipeline configuration."
+                    )
+            result.append(PipelineStepReference(group_name, step_class, step_config.config))
+        return result
+
+    @staticmethod
+    def _load_user_step(python_file: Path, step_class_name: str) -> Type[TPipelineStep]:
+        # Create a module specification from the file path
+        spec = spec_from_file_location(f"user__{python_file.stem}", python_file)
+        if spec and spec.loader:
+            step_module = module_from_spec(spec)
+            # Import the module
+            spec.loader.exec_module(step_module)
+            try:
+                step_class = getattr(step_module, step_class_name)
+            except AttributeError:
+                raise UserNotificationException(f"Could not load class '{step_class_name}' from file '{python_file}'. Please check your pipeline configuration.") from None
+            return step_class
+        raise UserNotificationException(f"Could not load file '{python_file}'. Please check the file for any errors.")
+
+    @staticmethod
+    def _load_module_step(module_name: str, step_class_name: str) -> Type[TPipelineStep]:
+        try:
+            module = importlib.import_module(module_name)
+            step_class = getattr(module, step_class_name)
+        except ImportError:
+            raise UserNotificationException(f"Could not load module '{module_name}'. Please check your pipeline configuration.") from None
+        except AttributeError:
+            raise UserNotificationException(f"Could not load class '{step_class_name}' from module '{module_name}'. Please check your pipeline configuration.") from None
+        return step_class
+
+
+TExecutionContext = TypeVar("TExecutionContext", bound=ExecutionContext)
+
+
+class PipelineStep(Generic[TExecutionContext], Runnable):
+    """One can create subclasses of PipelineStep that specify the type of ExecutionContext they require."""
+
+    def __init__(self, execution_context: TExecutionContext, group_name: Optional[str], config: Optional[Dict[str, Any]] = None) -> None:
+        super().__init__(self.get_needs_dependency_management())
+        self.execution_context = execution_context
+        self.group_name = group_name
+        self.config = config
+        self.project_root_dir = self.execution_context.project_root_dir
+
+    @property
+    def output_dir(self) -> Path:
+        output_dir = self.execution_context.create_artifacts_locator().build_dir
+        if self.group_name:
+            output_dir = output_dir / self.group_name
+        return output_dir
+
+    @abstractmethod
+    def update_execution_context(self) -> None:
+        """
+        Even if the step does not need to run ( because it is not outdated ), it can still update the execution context.
+
+        A typical use case is for steps installing software that need to provide the install directories in the execution context even if all tools are already installed.
+        """
+        pass
+
+    def get_needs_dependency_management(self) -> bool:
+        """If false, the step executor will not check for outdated dependencies. This is useful for steps consisting of command lines which shall always run."""
+        return True

{pypeline_runner-1.6.0 → pypeline_runner-1.8.0}/src/pypeline/domain/project_slurper.py

@@ -1,4 +1,5 @@
 from pathlib import Path
+from typing import Optional
 
 from py_app_dev.core.exceptions import UserNotificationException
 from py_app_dev.core.logging import logger
@@ -8,9 +9,9 @@ from .config import PipelineConfig, ProjectConfig
 
 
 class ProjectSlurper:
-    def __init__(self, project_dir: Path) -> None:
+    def __init__(self, project_dir: Path, config_file: Optional[str] = None) -> None:
         self.logger = logger.bind()
-        self.artifacts_locator = ProjectArtifactsLocator(project_dir)
+        self.artifacts_locator = ProjectArtifactsLocator(project_dir, config_file)
         try:
             self.user_config: ProjectConfig = ProjectConfig.from_file(self.artifacts_locator.config_file)
         except FileNotFoundError:

{pypeline_runner-1.6.0 → pypeline_runner-1.8.0}/src/pypeline/kickstart/create.py

@@ -1,55 +1,55 @@
-import shutil
-from pathlib import Path
-from typing import List, Optional, Union
-
-from py_app_dev.core.exceptions import UserNotificationException
-from py_app_dev.core.logging import logger
-
-
-class ProjectBuilder:
-    def __init__(self, project_dir: Path, input_dir: Optional[Path] = None) -> None:
-        self.project_dir = project_dir
-        self.input_dir = input_dir if input_dir else Path(__file__).parent.joinpath("templates")
-
-        self.dirs: List[Path] = []
-        self.check_target_directory_flag = True
-
-    def with_disable_target_directory_check(self) -> "ProjectBuilder":
-        self.check_target_directory_flag = False
-        return self
-
-    def with_dir(self, dir: Union[Path, str]) -> "ProjectBuilder":
-        self.dirs.append(self.resolve_file_path(dir))
-        return self
-
-    def resolve_file_paths(self, files: List[Path | str]) -> List[Path]:
-        return [self.resolve_file_path(file) for file in files]
-
-    def resolve_file_path(self, file: Union[Path, str]) -> Path:
-        return self.input_dir.joinpath(file) if isinstance(file, str) else file
-
-    @staticmethod
-    def _check_target_directory(project_dir: Path) -> None:
-        if project_dir.is_dir() and any(project_dir.iterdir()):
-            raise UserNotificationException(f"Project directory '{project_dir}' is not empty. Use --force to override.")
-
-    def build(self) -> None:
-        if self.check_target_directory_flag:
-            self._check_target_directory(self.project_dir)
-        for dir in self.dirs:
-            shutil.copytree(dir, self.project_dir, dirs_exist_ok=True)
-
-
-class KickstartProject:
-    def __init__(self, project_dir: Path, force: bool = False) -> None:
-        self.logger = logger.bind()
-        self.project_dir = project_dir
-        self.force = force
-
-    def run(self) -> None:
-        self.logger.info(f"Kickstart new project in '{self.project_dir.absolute().as_posix()}'")
-        project_builder = ProjectBuilder(self.project_dir)
-        if self.force:
-            project_builder.with_disable_target_directory_check()
-        project_builder.with_dir("project")
-        project_builder.build()
+import shutil
+from pathlib import Path
+from typing import List, Optional, Union
+
+from py_app_dev.core.exceptions import UserNotificationException
+from py_app_dev.core.logging import logger
+
+
+class ProjectBuilder:
+    def __init__(self, project_dir: Path, input_dir: Optional[Path] = None) -> None:
+        self.project_dir = project_dir
+        self.input_dir = input_dir if input_dir else Path(__file__).parent.joinpath("templates")
+
+        self.dirs: List[Path] = []
+        self.check_target_directory_flag = True
+
+    def with_disable_target_directory_check(self) -> "ProjectBuilder":
+        self.check_target_directory_flag = False
+        return self
+
+    def with_dir(self, dir: Union[Path, str]) -> "ProjectBuilder":
+        self.dirs.append(self.resolve_file_path(dir))
+        return self
+
+    def resolve_file_paths(self, files: List[Path | str]) -> List[Path]:
+        return [self.resolve_file_path(file) for file in files]
+
+    def resolve_file_path(self, file: Union[Path, str]) -> Path:
+        return self.input_dir.joinpath(file) if isinstance(file, str) else file
+
+    @staticmethod
+    def _check_target_directory(project_dir: Path) -> None:
+        if project_dir.is_dir() and any(project_dir.iterdir()):
+            raise UserNotificationException(f"Project directory '{project_dir}' is not empty. Use --force to override.")
+
+    def build(self) -> None:
+        if self.check_target_directory_flag:
+            self._check_target_directory(self.project_dir)
+        for dir in self.dirs:
+            shutil.copytree(dir, self.project_dir, dirs_exist_ok=True)
+
+
+class KickstartProject:
+    def __init__(self, project_dir: Path, force: bool = False) -> None:
+        self.logger = logger.bind()
+        self.project_dir = project_dir
+        self.force = force
+
+    def run(self) -> None:
+        self.logger.info(f"Kickstart new project in '{self.project_dir.absolute().as_posix()}'")
+        project_builder = ProjectBuilder(self.project_dir)
+        if self.force:
+            project_builder.with_disable_target_directory_check()
+        project_builder.with_dir("project")
+        project_builder.build()