gencli-agents 0.0.1__tar.gz

gencli_agents-0.0.1/LICENSE

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

gencli_agents-0.0.1/PKG-INFO

@@ -0,0 +1,307 @@
+Metadata-Version: 2.4
+Name: gencli-agents
+Version: 0.0.1
+Summary: General-purpose CLI: a library of functions exposed as commands, built for agents to use and extend
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,typer,agents,tooling
+Author: gustavo.polleti
+Author-email: gustavo.polleti@gmail.com
+Requires-Python: >=3.9,<4.0
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: rich (>=14.0.0,<15.0.0)
+Requires-Dist: shellingham (>=1.5.0,<2.0.0)
+Requires-Dist: typer (>=0.17.0,<0.18.0)
+Project-URL: Documentation, https://gpadpoll.github.io/general-cli/
+Project-URL: Homepage, https://github.com/gpadpoll/general-cli
+Project-URL: Repository, https://github.com/gpadpoll/general-cli
+Description-Content-Type: text/markdown
+
+# gencli
+
+A general-purpose CLI: a library of functions exposed as commands, built for
+agents to use and extend. Every tool is implemented as a small set of pure
+functions with a thin Typer command wrapper, so the same logic works both as
+a shell command and as a plain Python import (from a script, a notebook, or
+another agent's tool).
+
+See [`AGENTS.md`](./AGENTS.md) for the SDLC every new tool must follow
+(pure functions, tests, and a documentation notebook per feature).
+
+## Get Started
+
+See the Docs page: https://gpadpoll.github.io/general-cli/
+
+## Important: Poetry Version
+
+To avoid compatibility errors (such as TypeError related to canonicalize_version), ensure you are using an up-to-date version of Poetry:
+
+   ```bash
+   pip install --upgrade poetry
+   ```
+
+If you encounter installation issues, upgrading Poetry usually resolves them.
+
+## Quick Start
+
+1. **Environment**: create (or verify) the conda environment for this project
+   ```bash
+   make conda-env
+   ```
+
+2. **Installation**: install the package in development mode
+   ```bash
+   make install
+   ```
+
+3. **Basic Usage**: try the built-in commands
+   ```bash
+   gencli config list
+   gencli config set theme dark
+   gencli config get theme
+
+   gencli example slug "Hello, World!"
+   gencli example word-count "to be or not to be"
+   gencli example reverse "the quick brown fox"
+   ```
+
+## CLI Commands
+
+- `gencli config` — manage CLI configuration (`set`, `get`, `list`, `reset`),
+  stored as JSON at `~/.gencli_config.json` (override with
+  `GENCLI_CONFIG_PATH`).
+- `gencli example` — reference tool (`slug`, `word-count`, `reverse`). This
+  is the template to copy when adding a new tool: see
+  `gencli/commands/example.py`, its tests in `tests/test_example.py`, and
+  its notebook in `docs/notebooks/example.ipynb`.
+
+## Adding a new tool
+
+1. Create `gencli/commands/<tool>.py`. Implement the tool's logic as pure
+   functions (no I/O, no side effects, deterministic), and thin Typer
+   commands that call them.
+2. Register the sub-app in `gencli/main.py`.
+3. Write unit tests in `tests/test_<tool>.py`: direct tests for the pure
+   functions, plus a couple of `CliRunner` tests for the CLI wiring.
+4. Document the pure functions as a Jupyter notebook in
+   `docs/notebooks/<tool>.ipynb` (copy `docs/notebooks/example.ipynb` as a
+   starting point) and list it in `docs/docs/index.md`.
+5. Run `make format`, `make check`, `make test`, and the pre-commit hooks
+   before opening a PR.
+
+Full guidelines: [`AGENTS.md`](./AGENTS.md).
+
+## Development
+
+### Prerequisites
+
+This project uses [Poetry](https://python-poetry.org/) for dependency management, inside a dedicated conda environment.
+
+```bash
+make conda-env   # create/verify the conda env and install dependencies
+```
+
+### Setup
+
+1. **Install dependencies**:
+   ```bash
+   make install
+   ```
+   This installs the package and all development dependencies using Poetry.
+
+2. **Install pre-commit hooks**:
+   ```bash
+   make pre-commit
+   ```
+
+### Testing
+
+Run the comprehensive test suite:
+
+```bash
+make test
+```
+
+Or run tests directly with Poetry:
+
+```bash
+poetry run pytest -vvv
+```
+
+### Documentation
+
+1. **Install docs dependencies**:
+   ```bash
+   make docs
+   ```
+
+2. **Serve docs locally**:
+   ```bash
+   make serve-docs
+   ```
+   Or run directly with Poetry:
+   ```bash
+   poetry run mkdocs serve -f docs/mkdocs.yml
+   ```
+
+3. **View documentation**: Open http://localhost:8000
+
+### Code Quality
+
+- **Format code**: `make format` or `poetry run black .`
+- **Check formatting**: `make check` or `poetry run black --check --diff .`
+- **Run linting**: `poetry run flake8`
+- **Type checking**: `poetry run mypy .`
+- **Clean artifacts**: `make clean`
+
+### Docker Testing
+
+Test the CLI in a clean container environment:
+
+1. **Build image**:
+   ```bash
+   make docker-image
+   ```
+
+2. **Run commands**:
+   ```bash
+   docker run --rm gencli --help
+   docker run --rm gencli config list
+   docker run --rm gencli example slug "Hello, World!"
+   ```
+
+## Configuration Storage
+
+- **Default location**: `~/.gencli_config.json`
+- **Custom location**: Set `GENCLI_CONFIG_PATH` environment variable
+- **Format**: JSON with automatic type preservation
+- **Default values**: Includes theme, output_format, auto_save, and debug settings
+
+## Distribution
+
+### PyPI Publishing (automated, recommended)
+
+`.github/workflows/publish.yml` builds and publishes to PyPI whenever a
+GitHub Release is published (or the workflow is run manually). It uses
+[PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC)
+— there is no API token to generate or store as a secret.
+
+The PyPI distribution name is `gencli-agents` — the plain name `gencli`
+is already taken by an unrelated project (`gen-cli`, which normalizes to
+the same name once PyPI strips hyphens). The import name and CLI command
+are unaffected and remain `gencli`.
+
+**One-time setup** (do this before the first release):
+
+1. On PyPI, go to "Add a new pending publisher"
+   (https://pypi.org/manage/account/publishing/, and the equivalent on
+   https://test.pypi.org/manage/account/publishing/ if you want to dry-run
+   via TestPyPI first) and add a trusted publisher with:
+   - PyPI Project Name: `gencli-agents`
+   - Owner: `gpadpoll`
+   - Repository: `general-cli`
+   - Workflow file: `publish.yml`
+   - Environment name: `pypi` (or `testpypi` on test.pypi.org)
+2. The `pypi` and `testpypi` GitHub environments already exist on the repo
+   (Settings → Environments) — created for this workflow; add required
+   reviewers there if you want a manual approval gate before a publish
+   runs.
+
+**To cut a release:**
+
+1. Bump `version` in `pyproject.toml`.
+2. Commit, then tag: `git tag vX.Y.Z && git push --tags`.
+3. Create a GitHub Release from that tag. This triggers the workflow,
+   which verifies the tag matches the `pyproject.toml` version, builds the
+   sdist/wheel, and publishes them to PyPI.
+
+### PyPI Publishing (manual)
+
+> **NOTE**: Ensure you have a [PyPI account](https://pypi.org/account/register/) before publishing.
+
+1. **Create distributions**:
+   ```bash
+   make distributions
+   ```
+   This builds the package using Poetry.
+
+2. **Upload to PyPI**:
+   ```bash
+   poetry publish
+   ```
+   Or use twine:
+   ```bash
+   twine upload dist/*
+   ```
+
+### Project layout
+
+```text
+.
+├── AGENTS.md                # SDLC guidelines for agents adding/changing tools
+├── Dockerfile                # container image build steps
+├── Makefile                  # convenience commands (install, test, docs, conda-env, etc.)
+├── pyproject.toml            # project metadata and dependencies (Poetry)
+├── README.md                 # this file
+├── .github/workflows/
+│   ├── docs.yml               # builds+deploys the MkDocs site to GitHub Pages
+│   └── publish.yml            # builds+publishes to PyPI on GitHub Release
+├── scripts/
+│   └── setup_conda_env.sh    # creates/verifies the conda environment
+├── docs/                     # MkDocs site and notebook resources
+│   ├── mkdocs.yml
+│   ├── docs/
+│   │   └── index.md
+│   └── notebooks/
+│       └── example.ipynb     # documents the `example` tool's pure functions
+├── gencli/                   # main package code
+│   ├── __init__.py
+│   ├── constants.py
+│   ├── main.py                # top-level Typer app, registers command modules
+│   ├── utils.py                # shared pure helpers
+│   └── commands/               # one module per tool (Typer sub-app)
+│       ├── __init__.py
+│       ├── config.py           # configuration management commands
+│       └── example.py          # reference tool: pure functions + CLI wrapper
+└── tests/
+    ├── test_config.py
+    └── test_example.py
+```
+
+## Architecture
+
+Built with modern Python CLI best practices:
+
+- **[Poetry](https://python-poetry.org/)** - Modern dependency management
+- **[Typer](https://typer.tiangolo.com/)** - Type-based CLI framework
+- **[Rich](https://rich.readthedocs.io/)** - Beautiful terminal output
+- **[Pytest](https://pytest.org/)** - Reliable testing framework
+- **[MkDocs](https://mkdocs.org/)** - Professional documentation
+- **[Black](https://black.readthedocs.io/)** - Code formatting
+- **[Pre-commit](https://pre-commit.com/)** - Git hooks for quality
+
+## Help
+
+View all available make commands:
+
+```bash
+make help
+```
+
+Get CLI help:
+
+```bash
+gencli --help
+gencli config --help
+gencli example --help
+```
+

gencli_agents-0.0.1/README.md

@@ -0,0 +1,278 @@
+# gencli
+
+A general-purpose CLI: a library of functions exposed as commands, built for
+agents to use and extend. Every tool is implemented as a small set of pure
+functions with a thin Typer command wrapper, so the same logic works both as
+a shell command and as a plain Python import (from a script, a notebook, or
+another agent's tool).
+
+See [`AGENTS.md`](./AGENTS.md) for the SDLC every new tool must follow
+(pure functions, tests, and a documentation notebook per feature).
+
+## Get Started
+
+See the Docs page: https://gpadpoll.github.io/general-cli/
+
+## Important: Poetry Version
+
+To avoid compatibility errors (such as TypeError related to canonicalize_version), ensure you are using an up-to-date version of Poetry:
+
+   ```bash
+   pip install --upgrade poetry
+   ```
+
+If you encounter installation issues, upgrading Poetry usually resolves them.
+
+## Quick Start
+
+1. **Environment**: create (or verify) the conda environment for this project
+   ```bash
+   make conda-env
+   ```
+
+2. **Installation**: install the package in development mode
+   ```bash
+   make install
+   ```
+
+3. **Basic Usage**: try the built-in commands
+   ```bash
+   gencli config list
+   gencli config set theme dark
+   gencli config get theme
+
+   gencli example slug "Hello, World!"
+   gencli example word-count "to be or not to be"
+   gencli example reverse "the quick brown fox"
+   ```
+
+## CLI Commands
+
+- `gencli config` — manage CLI configuration (`set`, `get`, `list`, `reset`),
+  stored as JSON at `~/.gencli_config.json` (override with
+  `GENCLI_CONFIG_PATH`).
+- `gencli example` — reference tool (`slug`, `word-count`, `reverse`). This
+  is the template to copy when adding a new tool: see
+  `gencli/commands/example.py`, its tests in `tests/test_example.py`, and
+  its notebook in `docs/notebooks/example.ipynb`.
+
+## Adding a new tool
+
+1. Create `gencli/commands/<tool>.py`. Implement the tool's logic as pure
+   functions (no I/O, no side effects, deterministic), and thin Typer
+   commands that call them.
+2. Register the sub-app in `gencli/main.py`.
+3. Write unit tests in `tests/test_<tool>.py`: direct tests for the pure
+   functions, plus a couple of `CliRunner` tests for the CLI wiring.
+4. Document the pure functions as a Jupyter notebook in
+   `docs/notebooks/<tool>.ipynb` (copy `docs/notebooks/example.ipynb` as a
+   starting point) and list it in `docs/docs/index.md`.
+5. Run `make format`, `make check`, `make test`, and the pre-commit hooks
+   before opening a PR.
+
+Full guidelines: [`AGENTS.md`](./AGENTS.md).
+
+## Development
+
+### Prerequisites
+
+This project uses [Poetry](https://python-poetry.org/) for dependency management, inside a dedicated conda environment.
+
+```bash
+make conda-env   # create/verify the conda env and install dependencies
+```
+
+### Setup
+
+1. **Install dependencies**:
+   ```bash
+   make install
+   ```
+   This installs the package and all development dependencies using Poetry.
+
+2. **Install pre-commit hooks**:
+   ```bash
+   make pre-commit
+   ```
+
+### Testing
+
+Run the comprehensive test suite:
+
+```bash
+make test
+```
+
+Or run tests directly with Poetry:
+
+```bash
+poetry run pytest -vvv
+```
+
+### Documentation
+
+1. **Install docs dependencies**:
+   ```bash
+   make docs
+   ```
+
+2. **Serve docs locally**:
+   ```bash
+   make serve-docs
+   ```
+   Or run directly with Poetry:
+   ```bash
+   poetry run mkdocs serve -f docs/mkdocs.yml
+   ```
+
+3. **View documentation**: Open http://localhost:8000
+
+### Code Quality
+
+- **Format code**: `make format` or `poetry run black .`
+- **Check formatting**: `make check` or `poetry run black --check --diff .`
+- **Run linting**: `poetry run flake8`
+- **Type checking**: `poetry run mypy .`
+- **Clean artifacts**: `make clean`
+
+### Docker Testing
+
+Test the CLI in a clean container environment:
+
+1. **Build image**:
+   ```bash
+   make docker-image
+   ```
+
+2. **Run commands**:
+   ```bash
+   docker run --rm gencli --help
+   docker run --rm gencli config list
+   docker run --rm gencli example slug "Hello, World!"
+   ```
+
+## Configuration Storage
+
+- **Default location**: `~/.gencli_config.json`
+- **Custom location**: Set `GENCLI_CONFIG_PATH` environment variable
+- **Format**: JSON with automatic type preservation
+- **Default values**: Includes theme, output_format, auto_save, and debug settings
+
+## Distribution
+
+### PyPI Publishing (automated, recommended)
+
+`.github/workflows/publish.yml` builds and publishes to PyPI whenever a
+GitHub Release is published (or the workflow is run manually). It uses
+[PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC)
+— there is no API token to generate or store as a secret.
+
+The PyPI distribution name is `gencli-agents` — the plain name `gencli`
+is already taken by an unrelated project (`gen-cli`, which normalizes to
+the same name once PyPI strips hyphens). The import name and CLI command
+are unaffected and remain `gencli`.
+
+**One-time setup** (do this before the first release):
+
+1. On PyPI, go to "Add a new pending publisher"
+   (https://pypi.org/manage/account/publishing/, and the equivalent on
+   https://test.pypi.org/manage/account/publishing/ if you want to dry-run
+   via TestPyPI first) and add a trusted publisher with:
+   - PyPI Project Name: `gencli-agents`
+   - Owner: `gpadpoll`
+   - Repository: `general-cli`
+   - Workflow file: `publish.yml`
+   - Environment name: `pypi` (or `testpypi` on test.pypi.org)
+2. The `pypi` and `testpypi` GitHub environments already exist on the repo
+   (Settings → Environments) — created for this workflow; add required
+   reviewers there if you want a manual approval gate before a publish
+   runs.
+
+**To cut a release:**
+
+1. Bump `version` in `pyproject.toml`.
+2. Commit, then tag: `git tag vX.Y.Z && git push --tags`.
+3. Create a GitHub Release from that tag. This triggers the workflow,
+   which verifies the tag matches the `pyproject.toml` version, builds the
+   sdist/wheel, and publishes them to PyPI.
+
+### PyPI Publishing (manual)
+
+> **NOTE**: Ensure you have a [PyPI account](https://pypi.org/account/register/) before publishing.
+
+1. **Create distributions**:
+   ```bash
+   make distributions
+   ```
+   This builds the package using Poetry.
+
+2. **Upload to PyPI**:
+   ```bash
+   poetry publish
+   ```
+   Or use twine:
+   ```bash
+   twine upload dist/*
+   ```
+
+### Project layout
+
+```text
+.
+├── AGENTS.md                # SDLC guidelines for agents adding/changing tools
+├── Dockerfile                # container image build steps
+├── Makefile                  # convenience commands (install, test, docs, conda-env, etc.)
+├── pyproject.toml            # project metadata and dependencies (Poetry)
+├── README.md                 # this file
+├── .github/workflows/
+│   ├── docs.yml               # builds+deploys the MkDocs site to GitHub Pages
+│   └── publish.yml            # builds+publishes to PyPI on GitHub Release
+├── scripts/
+│   └── setup_conda_env.sh    # creates/verifies the conda environment
+├── docs/                     # MkDocs site and notebook resources
+│   ├── mkdocs.yml
+│   ├── docs/
+│   │   └── index.md
+│   └── notebooks/
+│       └── example.ipynb     # documents the `example` tool's pure functions
+├── gencli/                   # main package code
+│   ├── __init__.py
+│   ├── constants.py
+│   ├── main.py                # top-level Typer app, registers command modules
+│   ├── utils.py                # shared pure helpers
+│   └── commands/               # one module per tool (Typer sub-app)
+│       ├── __init__.py
+│       ├── config.py           # configuration management commands
+│       └── example.py          # reference tool: pure functions + CLI wrapper
+└── tests/
+    ├── test_config.py
+    └── test_example.py
+```
+
+## Architecture
+
+Built with modern Python CLI best practices:
+
+- **[Poetry](https://python-poetry.org/)** - Modern dependency management
+- **[Typer](https://typer.tiangolo.com/)** - Type-based CLI framework
+- **[Rich](https://rich.readthedocs.io/)** - Beautiful terminal output
+- **[Pytest](https://pytest.org/)** - Reliable testing framework
+- **[MkDocs](https://mkdocs.org/)** - Professional documentation
+- **[Black](https://black.readthedocs.io/)** - Code formatting
+- **[Pre-commit](https://pre-commit.com/)** - Git hooks for quality
+
+## Help
+
+View all available make commands:
+
+```bash
+make help
+```
+
+Get CLI help:
+
+```bash
+gencli --help
+gencli config --help
+gencli example --help
+```

gencli_agents-0.0.1/gencli/__init__.py

@@ -0,0 +1,12 @@
+"""
+Object initialization for CLI
+"""
+
+from rich.console import Console
+
+console = Console()
+
+
+def hello() -> None:
+    """Print a friendly greeting confirming the package is importable."""
+    console.print("Hello from gencli!")

gencli_agents-0.0.1/gencli/commands/config.py

@@ -0,0 +1,224 @@
+"""
+Configuration management command for the CLI.
+
+This module provides commands to manage configuration settings stored in a JSON file.
+The configuration file location can be customized via the GENCLI_CONFIG_PATH environment variable.
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+app = typer.Typer(
+    no_args_is_help=True,
+    help="Manage configuration settings for the CLI application.",
+)
+
+console = Console()
+
+# Default configuration values
+DEFAULT_CONFIG = {
+    "theme": "default",
+    "output_format": "table",
+    "auto_save": True,
+    "debug": False,
+}
+
+
+def get_config_path() -> Path:
+    """
+    Get the configuration file path.
+
+    Returns the path from GENCLI_CONFIG_PATH environment variable if set,
+    otherwise returns the default path ~/.gencli_config.json.
+
+    Returns:
+        Path: The configuration file path.
+    """
+    config_path = os.getenv("GENCLI_CONFIG_PATH")
+    if config_path:
+        return Path(config_path)
+    return Path.home() / ".gencli_config.json"
+
+
+def load_config() -> Dict[str, Any]:
+    """
+    Load configuration from the JSON file.
+
+    If the file doesn't exist, returns the default configuration.
+
+    Returns:
+        Dict[str, Any]: The configuration dictionary.
+
+    Raises:
+        typer.Exit: If the configuration file is corrupted.
+    """
+    config_path = get_config_path()
+
+    if not config_path.exists():
+        return DEFAULT_CONFIG.copy()
+
+    try:
+        with open(config_path, "r") as f:
+            config = json.load(f)
+        return config
+    except json.JSONDecodeError:
+        console.print(
+            f"[red]Error: Configuration file {config_path} is corrupted.[/red]"
+        )
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Error reading configuration file: {e}[/red]")
+        raise typer.Exit(1)
+
+
+def save_config(config: Dict[str, Any]) -> None:
+    """
+    Save configuration to the JSON file.
+
+    Args:
+        config: The configuration dictionary to save.
+
+    Raises:
+        typer.Exit: If the configuration file cannot be written.
+    """
+    config_path = get_config_path()
+
+    try:
+        # Ensure the directory exists
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with open(config_path, "w") as f:
+            json.dump(config, f, indent=2)
+
+        console.print(f"[green]Configuration saved to {config_path}[/green]")
+    except Exception as e:
+        console.print(f"[red]Error saving configuration file: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@app.command()
+def set(
+    key: str = typer.Argument(..., help="Configuration key to set"),
+    value: Optional[str] = typer.Argument(
+        None, help="Configuration value to set (will prompt if not provided)"
+    ),
+) -> None:
+    """
+    Set a configuration value.
+
+    If the value is not provided as an argument, you will be prompted to enter it interactively.
+    The value will be automatically converted to the appropriate type (bool, int, float, or string).
+
+    Examples:
+        gencli config set theme dark
+        gencli config set debug true
+        gencli config set timeout 30
+    """
+    config = load_config()
+
+    if value is None:
+        value = typer.prompt(f"Enter value for '{key}'")
+
+    # Try to convert value to appropriate type
+    converted_value: Any = value
+    if value.lower() in ("true", "false"):
+        converted_value = value.lower() == "true"
+    elif value.isdigit():
+        converted_value = int(value)
+    elif value.replace(".", "").isdigit():
+        try:
+            converted_value = float(value)
+        except ValueError:
+            pass  # Keep as string
+
+    config[key] = converted_value
+    save_config(config)
+
+    console.print(f"[green]Set {key} = {converted_value}[/green]")
+
+
+@app.command()
+def get(
+    key: str = typer.Argument(..., help="Configuration key to retrieve"),
+) -> None:
+    """
+    Retrieve a configuration value.
+
+    Shows the value of the specified configuration key. If the key doesn't exist,
+    an error message is displayed and the command exits with status 1.
+
+    Examples:
+        gencli config get theme
+        gencli config get debug
+    """
+    config = load_config()
+
+    if key not in config:
+        console.print(
+            f"[red]Error: Configuration key '{key}' not found.[/red]"
+        )
+        raise typer.Exit(1)
+
+    value = config[key]
+    console.print(f"{key} = {value}")
+
+
+@app.command()
+def list() -> None:
+    """
+    Display all configuration values in a formatted table.
+
+    Shows all current configuration settings in a rich-formatted table,
+    making it easy to see all settings at a glance.
+
+    The table includes the configuration key, current value, and the value type.
+    """
+    config = load_config()
+
+    if not config:
+        console.print("[yellow]No configuration settings found.[/yellow]")
+        return
+
+    table = Table(title="Configuration Settings")
+    table.add_column("Key", style="cyan", no_wrap=True)
+    table.add_column("Value", style="green")
+    table.add_column("Type", style="blue")
+
+    for key, value in sorted(config.items()):
+        table.add_row(key, str(value), type(value).__name__)
+
+    console.print(table)
+
+
+@app.command()
+def reset() -> None:
+    """
+    Reset configuration to default values.
+
+    This command will restore all configuration settings to their default values.
+    A confirmation prompt is shown before proceeding to prevent accidental resets.
+
+    Default values:
+        - theme: default
+        - output_format: table
+        - auto_save: true
+        - debug: false
+    """
+    if not typer.confirm(
+        "Are you sure you want to reset all configuration to defaults?"
+    ):
+        console.print("[yellow]Reset cancelled.[/yellow]")
+        return
+
+    save_config(DEFAULT_CONFIG.copy())
+    console.print("[green]Configuration reset to defaults.[/green]")
+
+
+if __name__ == "__main__":
+    app()

gencli_agents-0.0.1/gencli/commands/example.py

@@ -0,0 +1,119 @@
+"""
+Example command module.
+
+This module is the reference template for adding new tools to the CLI.
+It demonstrates the pattern every command module should follow:
+
+1. Pure functions hold all the logic. They take plain values in, return
+   plain values out, and have no side effects (no I/O, no printing, no
+   mutation of arguments or module state). These are the functions an
+   agent or another module would import and call directly.
+2. Typer commands are thin adapters. They parse CLI arguments/options,
+   call the pure functions, and handle the only side effects allowed at
+   this layer: reading input and printing/writing output.
+
+See AGENTS.md for the full SDLC guidelines (tests + notebook docs are
+required for every new pure function exposed here).
+"""
+
+import re
+from collections import Counter
+from typing import Dict
+
+import typer
+from rich.console import Console
+
+app = typer.Typer(
+    no_args_is_help=True,
+    help="Example text utilities. Reference implementation for new tools.",
+)
+
+console = Console()
+
+_WORD_RE = re.compile(r"[A-Za-z0-9']+")
+
+
+# --------------------------------------------------------------------------
+# Pure functions (no I/O, no side effects, deterministic output for a given
+# input). These are what should be imported and unit-tested directly, and
+# what should be demonstrated in a docs notebook.
+# --------------------------------------------------------------------------
+
+
+def slugify(text: str) -> str:
+    """
+    Convert arbitrary text into a URL/filename-friendly slug.
+
+    Lowercases the text, strips characters that are not alphanumeric,
+    and joins words with hyphens.
+    """
+    words = _WORD_RE.findall(text.lower())
+    return "-".join(words)
+
+
+def word_count(text: str) -> Dict[str, int]:
+    """
+    Count occurrences of each word in ``text``.
+
+    Words are matched case-insensitively and punctuation is ignored.
+    Returns a plain dict mapping word -> count.
+    """
+    words = _WORD_RE.findall(text.lower())
+    return dict(Counter(words))
+
+
+def reverse_words(text: str) -> str:
+    """Reverse the order of whitespace-separated words in ``text``."""
+    return " ".join(reversed(text.split()))
+
+
+# --------------------------------------------------------------------------
+# Typer commands (thin I/O adapters over the pure functions above).
+# --------------------------------------------------------------------------
+
+
+@app.command()
+def slug(
+    text: str = typer.Argument(..., help="Text to convert into a slug"),
+) -> None:
+    """
+    Print a URL/filename-friendly slug for TEXT.
+
+    Example:
+        gencli example slug "Hello, World!"
+    """
+    console.print(slugify(text))
+
+
+@app.command(name="word-count")
+def word_count_command(
+    text: str = typer.Argument(..., help="Text to count words in"),
+) -> None:
+    """
+    Print word occurrence counts for TEXT, most frequent first.
+
+    Example:
+        gencli example word-count "to be or not to be"
+    """
+    counts = word_count(text)
+    for word, count in sorted(counts.items(), key=lambda kv: (-kv[1], kv[0])):
+        console.print(f"{word}: {count}")
+
+
+@app.command()
+def reverse(
+    text: str = typer.Argument(
+        ..., help="Text whose word order should be reversed"
+    ),
+) -> None:
+    """
+    Print TEXT with its word order reversed.
+
+    Example:
+        gencli example reverse "the quick brown fox"
+    """
+    console.print(reverse_words(text))
+
+
+if __name__ == "__main__":
+    app()

gencli_agents-0.0.1/gencli/constants.py

@@ -0,0 +1,7 @@
+"""
+Constants for the CLI.
+"""
+
+WELCOME_MESSAGE = (
+    "Welcome to [bold green]gencli!![/bold green] Your CLI is working!"
+)

gencli_agents-0.0.1/gencli/main.py

@@ -0,0 +1,29 @@
+"""
+Entrypoint for CLI.
+
+This is the main entry point for the gencli CLI application. It wires up
+each command module (a Typer sub-app) under a top-level name. Add new
+tools by creating a module in `gencli/commands/`, implementing the tool's
+logic as pure functions with thin Typer command wrappers (see
+`gencli/commands/example.py`), and registering it here.
+"""
+
+import typer
+
+from gencli.commands import config, example
+
+app = typer.Typer(
+    no_args_is_help=True,
+    help="General-purpose CLI: a library of functions exposed as commands.",
+    rich_markup_mode="rich",
+)
+app.add_typer(config.app, name="config", help="manage configuration settings")
+app.add_typer(example.app, name="example", help="reference text utilities")
+
+
+def gencli() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    app()

gencli_agents-0.0.1/gencli/utils.py

@@ -0,0 +1,8 @@
+"""
+Utility functions for the CLI.
+
+Keep this module for small, pure, reusable helpers shared across commands
+(formatting, parsing, path handling, etc). Command modules should import
+from here rather than duplicating logic. See AGENTS.md for the functional
+programming conventions new helpers should follow.
+"""

gencli_agents-0.0.1/pyproject.toml

@@ -0,0 +1,87 @@
+[project]
+name = "gencli-agents"
+version = "0.0.1"
+description = "General-purpose CLI: a library of functions exposed as commands, built for agents to use and extend"
+authors = [
+    {name = "gustavo.polleti", email = "gustavo.polleti@gmail.com"},
+]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.9,<4.0"
+keywords = ["cli", "typer", "agents", "tooling"]
+classifiers = [
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "typer (>=0.17.0,<0.18.0)",
+    "rich (>=14.0.0,<15.0.0)",
+    "shellingham (>=1.5.0,<2.0.0)",
+]
+
+[project.urls]
+Homepage = "https://github.com/gpadpoll/general-cli"
+Repository = "https://github.com/gpadpoll/general-cli"
+Documentation = "https://gpadpoll.github.io/general-cli/"
+
+[project.scripts]
+gencli = "gencli.main:gencli"
+
+[tool.poetry]
+packages = [{include = "gencli"}]
+
+[tool.poetry.group.dev.dependencies]
+pre-commit = "*"
+tox = "*"
+flake8 = "*"
+black = "*"
+mypy = "*"
+
+[tool.poetry.group.docs.dependencies]
+mkdocs-material = "^9.6.0"
+mkdocs-markdownextradata-plugin = "^0.2.6"
+# Needed to convert notebooks to markdown for inclusion in the MkDocs site
+jupyter = "*"
+nbconvert = "*"
+
+[tool.poetry.group.test.dependencies]
+pytest = "^8.4.0"
+
+[tool.poetry.group.publish.dependencies]
+twine = "^6.0.0"
+
+[build-system]
+requires = ["poetry-core>=2.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 79
+target-version = ['py39', 'py310', 'py311', 'py312', 'py313']
+include = '\.pyi?$'
+exclude = '''
+/(
+    \.eggs
+  | \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \venv
+  | \.venv
+  | _build
+  | buck-out
+  | build
+  | dist
+  # The following are specific to Black, you probably don't want those.
+  | blib2to3
+  | tests/data
+  | profiling
+)/
+'''