Dev

.github/workflows/build_and_publish.yaml

@@ -7,6 +7,7 @@ on:
   pull_request:
     branches:
       - master
+      - dev
 
 jobs:
   build:
@@ -32,6 +33,7 @@ jobs:
       - name: Install dependencies
         run: |
           cd ${{ matrix.pkg-dir }}
+          poetry lock
           poetry install --no-cache -vv
 
       - name: Lint with flake8

README.md

@@ -1,245 +1,213 @@
 <p align="center">
-    <a href="https://github.com/swarmauri/swarmauri-sdk/"><img src="https://res.cloudinary.com/dbjmpekvl/image/upload/v1730099724/Swarmauri-logo-lockup-2048x757_hww01w.png" alt="Swamauri Logo"/></a>
-    <br />
-    <a href="https://hits.sh/github.com/swarmauri/soliloquy/"><img src="https://hits.sh/github.com/swarmauri/soliloquy.svg" alt="Hits"/></a>
-    <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License"/></a>
-    <a href="https://pypi.org/project/soliloquy/"><img src="https://img.shields.io/pypi/v/soliloquy?label=soliloquy" alt="PyPI - soliloquy Version"/></a>
-    <a href="https://pypi.org/project/soliloquy/"><img src="https://img.shields.io/pypi/dm/soliloquy?label=soliloquy%20Downloads" alt="PyPI - soliloquy Downloads"/></a>
-    <br />
-    <img src="https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&labelColor=black" alt="Python"/>
+  <a href="https://github.com/swarmauri/swarmauri-sdk/">
+    <img src="https://res.cloudinary.com/dbjmpekvl/image/upload/v1730099724/Swarmauri-logo-lockup-2048x757_hww01w.png" alt="Swamauri Logo"/>
+  </a>
+  <br />
+  <a href="https://hits.sh/github.com/swarmauri/soliloquy/">
+    <img src="https://hits.sh/github.com/swarmauri/soliloquy.svg" alt="Hits"/>
+  </a>
+  <a href="https://opensource.org/licenses/Apache-2.0">
+    <img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License"/>
+  </a>
+  <a href="https://pypi.org/project/soliloquy/">
+    <img src="https://img.shields.io/pypi/v/soliloquy?label=soliloquy" alt="PyPI - soliloquy Version"/>
+  </a>
+  <a href="https://pypi.org/project/soliloquy/">
+    <img src="https://img.shields.io/pypi/dm/soliloquy?label=soliloquy%20Downloads" alt="PyPI - soliloquy Downloads"/>
+  </a>
+  <br />
+  <img src="https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&labelColor=black" alt="Python"/>
 </p>
 
-
 # Soliloquy
 
 **Soliloquy** is a unified command-line tool for managing a Python monorepo that contains multiple standalone packages—each with its own `pyproject.toml`. It consolidates common tasks such as dependency management, version bumping, remote dependency resolution, test execution and analysis, and project configuration updates into one robust CLI.
 
-## Features
-
-- **Dependency Management**  
-  - **Lock:** Generate a `poetry.lock` file.
-  - **Install:** Install dependencies with options for extras and development dependencies.
-  - **Show Freeze:** (Available as an internal command) Display installed packages using `pip freeze`.
-
-- **Build Operations**  
-  - **Build:** Recursively build packages based on local (path) dependencies as specified in your `pyproject.toml` files.
-
-- **Version Management**  
-  - **Version:** Bump (major, minor, patch, finalize) or explicitly set package versions in `pyproject.toml`.
-
-- **Remote Operations**  
-  - **Remote Fetch:** Fetch the version from a remote GitHub repository’s `pyproject.toml`.
-  - **Remote Update:** Update a local `pyproject.toml` file with version information fetched from remote Git dependencies.
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Commands](#commands)
+    - [Prepare](#prepare)
+    - [Install](#install)
+    - [Validate](#validate)
+    - [Release](#release)
+- [Configuration](#configuration)
+- [Examples](#examples)
+- [Contributing](#contributing)
+- [License](#license)
+- [Contact](#contact)
 
-- **Testing and Analysis**  
-  - **Test:** Run your tests using pytest. Optionally, run tests in parallel (supports [pytest‑xdist](https://pypi.org/project/pytest-xdist/)).
-  - **Analyze:** Analyze test results provided in a JSON file by displaying summary statistics and evaluating threshold conditions for passed/skipped tests.
+## Features
 
-- **Pyproject Operations**  
-  - **Pyproject:** Extract both local (path) and Git-based dependencies from a `pyproject.toml` file and, optionally, update dependency versions.
+- **Version Management:** Automatically bump or set versions (major, minor, patch, or finalize) across projects.
+- **Dependency Management:** Lock and install dependencies from single or multiple `pyproject.toml` files.
+- **Validation:** Build, test, and analyze code with configurable test modes and parallel execution support.
+- **Release Workflow:** Validate, update remote dependencies, and publish to PyPI with a single command.
+- **Recursive Discovery:** Automatically scan directories (and subdirectories) to find `pyproject.toml` files.
 
 ## Installation
 
-Install via pip:
+Install Soliloquy directly from PyPI:
 
 ```bash
 pip install soliloquy
 ```
 
-_This command installs the `soliloquy` CLI, which is provided via the entry point `soliloquy`, into your system PATH._
+Alternatively, install from source:
+
+```bash
+git clone https://github.com/swarmauri/soliloquy.git
+cd soliloquy
+pip install .
+```
 
 ## Usage
 
-After installation, run the following command to see a list of available commands:
+After installation, you can run Soliloquy from the command line:
 
 ```bash
 soliloquy --help
 ```
 
-### Command Examples
+This command displays the available commands and options.
 
-#### 1. Lock Dependencies
+### Commands
 
-Generate a `poetry.lock` file by specifying either a directory or a file path containing a `pyproject.toml`:
+Soliloquy includes several commands for different stages of your workflow:
 
-```bash
-# Lock using a directory:
-soliloquy lock --directory ./packages/package1
+#### Prepare
 
-# Lock using an explicit pyproject.toml file:
-soliloquy lock --file ./packages/package1/pyproject.toml
-```
+Bump or set version numbers, lint your code, and commit changes.
 
-#### 2. Install Dependencies
+**Options:**
 
-Install dependencies with options for extras and including development dependencies:
+- `-f`, `--file`: Specify a single `pyproject.toml` file.
+- `-d`, `--directory`: Specify a directory containing one or more `pyproject.toml` files.
+- `-R`, `--recursive`: Recursively find `pyproject.toml` files.
+- `--bump`: Select the type of version bump (`major`, `minor`, `patch`, or `finalize`).
+- `--set-ver`: Explicitly set a version (e.g., `2.0.0.dev1`).
+- `--commit-msg`: Set the Git commit message (default: `"chore: prepare changes"`).
 
-```bash
-# Basic installation:
-soliloquy install --directory ./packages/package1
+**Example:**
 
-# Using an explicit pyproject.toml file:
-soliloquy install --file ./packages/package1/pyproject.toml
+```bash
+soliloquy prepare --bump patch -d ./packages
+```
 
-# Install including development dependencies:
-soliloquy install --directory ./packages/package1 --dev
+#### Install
 
-# Install including extras (e.g., extras named "full"):
-soliloquy install --directory ./packages/package2 --extras full
+Lock dependencies and install packages across your projects.
 
-# Install including all extras:
-soliloquy install --directory ./packages/package2 --all-extras
-```
+**Options:**
 
-#### 3. Build Packages
+- `-f`, `--file`: Specify a single `pyproject.toml` file.
+- `-d`, `--directory`: Specify a directory with multiple projects or an aggregator.
+- `-R`, `--recursive`: Recursively find `pyproject.toml` files.
 
-Recursively build packages based on their local dependency paths defined in their `pyproject.toml` files:
+**Example:**
 
 ```bash
-# Build packages using a directory containing a master pyproject.toml:
-soliloquy build --directory .
-
-# Build packages using an explicit pyproject.toml file:
-soliloquy build --file ./packages/package1/pyproject.toml
+soliloquy install -d ./projects --recursive
 ```
 
-#### 4. Version Management
-
-Bump or explicitly set the version in a package's `pyproject.toml`:
+#### Validate
 
-```bash
-# Bump the patch version (e.g., from 1.2.3.dev1 to 1.2.3.dev2):
-soliloquy version ./packages/package1/pyproject.toml --bump patch
-
-# Finalize a development version (remove the .dev suffix):
-soliloquy version ./packages/package1/pyproject.toml --bump finalize
+Build, test, and analyze your code.
 
-# Set an explicit version:
-soliloquy version ./packages/package1/pyproject.toml --set 2.0.0.dev1
-```
+**Options:**
 
-#### 5. Remote Operations
+- `-f`, `--file`: Specify a single `pyproject.toml` file.
+- `-d`, `--directory`: Specify a directory with multiple projects.
+- `-R`, `--recursive`: Recursively find `pyproject.toml` files.
+- `--test-mode`: Choose the test mode (`single`, `monorepo`, or `each`; default: `single`).
+- `--num-workers`: Number of parallel pytest workers (default: `1`).
+- `--results-json`: Path to a JSON file with test results for analysis.
+- `--required-passed`: Set a requirement for passed tests (e.g., `ge:80`).
+- `--required-skipped`: Set a requirement for skipped tests (e.g., `lt:10`).
+- `--no-cleanup`: Prevent cleanup of temporary test directories for Git-based dependencies.
 
-Fetch remote version information and update your local dependency configuration:
+**Example:**
 
 ```bash
-# Fetch the version from a remote GitHub repository's pyproject.toml:
-soliloquy remote fetch --git-url https://github.com/YourOrg/YourRepo.git --branch main --subdir "src/"
-
-# Update a local pyproject.toml with remote-resolved versions:
-# (If --output is omitted, the input file is overwritten.)
-soliloquy remote update --input ./packages/package1/pyproject.toml --output ./packages/package1/pyproject.updated.toml
+soliloquy validate -d ./src --test-mode monorepo --num-workers 4
 ```
 
-#### 6. Testing and Analysis
-
-Run your tests using pytest and analyze test results from a JSON report:
-
-- **Run Tests:**  
-  Execute tests within a specified directory. Use the `--num-workers` flag for parallel execution (requires pytest‑xdist):
+#### Release
 
-  ```bash
-  # Run tests sequentially:
-  soliloquy test --directory ./tests
-
-  # Run tests in parallel using 4 workers:
-  soliloquy test --directory ./tests --num-workers 4
-  ```
-
-- **Analyze Test Results:**  
-  Analyze a JSON test report and enforce thresholds for passed and skipped tests:
+Validate, update remote dependencies, and publish your package to PyPI.
 
-  ```bash
-  # Analyze test results without thresholds:
-  soliloquy analyze test-results.json
-
-  # Analyze test results with thresholds (e.g., passed tests > 75% and skipped tests < 20%):
-  soliloquy analyze test-results.json --required-passed gt:75 --required-skipped lt:20
-  ```
+**Options:**
 
-#### 7. Pyproject Operations
+- `-f`, `--file`: Specify a single `pyproject.toml` file.
+- `-d`, `--directory`: Specify a directory with multiple projects.
+- `-R`, `--recursive`: Recursively find `pyproject.toml` files.
+- `--test-mode`: Choose the test mode (default: `single`).
+- `--num-workers`: Number of parallel pytest workers (default: `1`).
+- `--results-json`: Path to a JSON file with test results.
+- `--required-passed`: Set a requirement for passed tests.
+- `--required-skipped`: Set a requirement for skipped tests.
+- `--publish-password`: Provide your PyPI password for publishing.
+- `--no-cleanup`: Prevent cleanup of temporary test directories.
 
-Extract and update dependency information from a `pyproject.toml` file:
+**Example:**
 
 ```bash
-# Extract local (path) and Git-based dependencies:
-soliloquy pyproject --pyproject ./packages/package1/pyproject.toml
-
-# Update local dependency versions to 2.0.0 (updates the parent file and, if possible, each dependency's own pyproject.toml):
-soliloquy pyproject --pyproject ./packages/package1/pyproject.toml --update-version 2.0.0
+soliloquy release -d ./myproject --publish-password YOUR_PYPI_PASSWORD
 ```
 
-## Workflow Example in GitHub Actions
+## Configuration
+
+Soliloquy leverages the configuration defined in your `pyproject.toml` files. To get the most out of Soliloquy, ensure that each project within your monorepo is correctly configured. For more details on configuration options and best practices, please refer to the [official documentation](https://github.com/swarmauri/soliloquy).
+
+## Examples
 
-Here's an example GitHub Actions workflow that uses **soliloquy** to lock, build, install, test, bump the patch version, and publish:
+Here are some practical use cases:
 
-```yaml
-name: Release Workflow
+- **Prepare a release by bumping the patch version:**
 
-on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
+  ```bash
+  soliloquy prepare --bump patch -d ./packages
+  ```
 
-jobs:
-  release:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v3
+- **Install dependencies across all projects recursively:**
 
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: '3.9'
+  ```bash
+  soliloquy install -d ./monorepo --recursive
+  ```
 
-      - name: Install soliloquy Tools
-        run: pip install "soliloquy@git+https://github.com/swarmauri/soliloquy.git@master"
+- **Run tests in monorepo mode with multiple workers:**
 
-      - name: Lock Dependencies
-        run: soliloquy lock --directory .
+  ```bash
+  soliloquy validate -d ./src --test-mode monorepo --num-workers 4
+  ```
 
-      - name: Build Packages
-        run: soliloquy build --directory .
+- **Release your package after validation:**
 
-      - name: Install Dependencies
-        run: soliloquy install --directory .
+  ```bash
+  soliloquy release -d ./myproject --publish-password YOUR_PYPI_PASSWORD
+  ```
 
-      - name: Run Tests
-        run: soliloquy test --directory ./tests --num-workers 4
+## Contributing
 
-      - name: Bump Patch Version
-        run: soliloquy version ./packages/package1/pyproject.toml --bump patch
+Contributions are welcome! If you’d like to contribute:
 
-      - name: Publish Packages
-        env:
-          PYPI_USERNAME: ${{ secrets.PYPI_USERNAME }}
-          PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
-        run: soliloquy publish --directory . --username "$PYPI_USERNAME" --password "$PYPI_PASSWORD"
-```
+1. **Fork the Repository:** Create your own fork on GitHub.
+2. **Create a Branch:** Work on a new feature or bugfix.
+3. **Write Tests:** Ensure your changes are covered by tests.
+4. **Submit a Pull Request:** Provide a detailed description of your changes.
 
-## Development
+Please review our [CONTRIBUTING.md](CONTRIBUTING.md) for more details on our contribution process.
 
-### Project Structure
+## License
 
-```
-soliloquy/
-├── __init__.py
-├── cli.py            # Main CLI entry point
-├── poetry_ops.py     # Poetry operations (lock, install, build, publish, run tests, etc.)
-├── version_ops.py    # Version bumping and setting operations
-├── remote_ops.py     # Remote Git dependency version fetching/updating
-├── test_ops.py       # Test result analysis operations
-└── pyproject_ops.py  # pyproject.toml dependency extraction and updates
-pyproject.toml        # Package configuration file containing metadata
-README.md             # This file
-```
+This project is licensed under the [Apache 2.0 License](https://opensource.org/licenses/Apache-2.0).
 
-## Contributing
+## Contact
 
-Contributions are welcome! Please open issues or submit pull requests for improvements or bug fixes.
+For questions, suggestions, or further information, please open an issue on [GitHub](https://github.com/swarmauri/soliloquy) or reach out directly.
 
-## License
+---
 
-This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+Happy coding with Soliloquy! 🚀