Metadata-Version: 2.1
Name: nerdcore
Version: 1.0.1
Summary: Nerd CLI is a Fivable-specific and highly configurable CLI tool for creating/running deployments, commands, and more.
Home-page: https://bitbucket.org/fivable/nerdcore.git
Author: David Wallace Cooley Jr
Author-email: david@fivable.com
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# nerdcore

Python framework for building CLI tools with commands, deployments, and entity management.

nerdcore provides the runtime, discovery, and utilities. Projects like [nerdcli](../nerdcli) provide the actual command implementations.

## Installation

```bash
# Editable install (development)
pip install -e ~/local-git/nerdcore

# Package install
pip install nerdcore
```

## Concepts

### Commands

Single-operation tools. Inherit from `Command`, declare arguments as class attributes, implement `run()`.

```python
from nerdcore.base_entities.command_class import Command

class MyCommand(Command):
    required_arg_keys = ['name']
    name: str = None

    def run(self):
        print(f"Hello, {self.name}")
```

### Deployments

Multi-step orchestrations with config profile support. Inherit from `Deployment`.

```python
from nerdcore.base_entities.deployment_class import Deployment

class MyDeploy(Deployment):
    app_name = 'myapp'
    required_config_keys = ['DEPLOY_TYPE']

    def run(self):
        # self.nerd_config has the loaded profile
        ...
```

### Entity Discovery

Entities are Python files in `commands/` and `deployments/` directories. nerdcore discovers them by filename using fuzzy matching (Levenshtein distance). Running `nerd deploy-lead` finds `deployments/deploy-lead.py`.

### Configuration

- **NerdConfig**: Singleton loaded from `config/nerd-manifest.yaml`. Profiles define deployment parameters.
- **ENV**: Environment variables loaded from `.env` via a project-specific env class.

### Error Handling

- `NerdUserError` — user-facing errors (bad input, missing config). Clean message, no traceback.
- `NerdError` — internal errors. Message + traceback.

Both are defined in `nerdcore.errors` (import-free module to prevent circular dependencies).

### Help System

nerdcore provides a dynamic, categorized help system:

- **`nerd help`** — Scans `commands/` and `deployments/` directories, extracts `help_text` and `category` from each entity class via `ast.parse()` (no imports needed), and displays a categorized listing.
- **`nerd help <command>`** — Imports the entity, reads class attributes (`unnamed_arg_keys`, `named_arg_keys`, `required_arg_keys`), type hints, defaults, and docstrings to display detailed per-command help.
- **`nerd list`** — All commands; `nerd list --all` includes nerdcore built-in commands.

Commands control their help output by setting class attributes: `help_text`, `category`.

### Terminal Output

- **`print_t(message, style)`** — Themed output with emoji prefix and text wrapping. Use for operational messages.
- **`apply_t(text, color)`** — Returns a themed string without printing. Use with `print()` for structured output (help pages, tables) where you need precise formatting without emoji prefixes or wrapping.

Both are in `nerdcore.utils.nerd.theme_functions`.

## Creating a New Project

After setup, `nerd-new` is available at `.venv/bin/nerd-new`:

```bash
.venv/bin/nerd-new my-project
```

This scaffolds the standard directory structure:

```
my-project/
├── abilities/
├── commands/
├── config/
│   └── framework/
├── deployments/
├── tasks/
├── stor/temp/
├── .env
├── .gitignore
├── requirements.txt
└── README.md
```

## Entry Points

nerdcore registers three console_scripts via `setup.py` entry_points:

| Command | Entry Point |
|---------|-------------|
| `nerd` | `nerdcore.cli.main:main` |
| `nerd-new` | `nerdcore.cli.nerd_new:main` |
| `nerdcore` | `nerdcore.__main__:main` |

## Publishing

```bash
bump2version patch    # or minor, major
git push && git push --tags
# Triggers CI pipeline for PyPI publishing
```
