Metadata-Version: 2.1
Name: nerdcore
Version: 1.0.0
Home-page: https://bitbucket.org/fivable/nerd-cli.git
Author: David Wallace Cooley Jr
Author-email: david@fivable.com
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.6
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).

## Creating a New Project

```bash
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
```
