genoai 1.0.1
A command-line tool for generating and managing project structures
Requires Python: >=3.8

# GenoAI Project Generator

GenoAI is a command-line tool for generating and managing project structures. It provides a simple interface for initializing, building, and deploying projects with best practices built-in.

## Prerequisites

- [Python 3.8+](https://www.python.org/downloads/)
- [pip](https://pip.pypa.io/en/stable/installation/)

## Installation

### Quick Start

```bash
# Download the script
curl -L https://raw.githubusercontent.com/yourusername/genoai/main/genoai -o genoai
chmod +x genoai

# Make it available system-wide (optional)
sudo mv genoai /usr/local/bin/
```

### From Source

1. **Clone the repository**:
   ```bash
   git clone https://github.com/yourusername/genoai.git
   cd genoai
   chmod +x genoai
   ```

2. **Install pipenv** (if not already installed):
   ```bash
   pip install pipenv
   ```

3. **Install dependencies**:
   ```bash
   pipenv install --dev
   ```

4. **Activate the virtual environment**:
   ```bash
   pipenv shell
   ```

5. **Set up AWS credentials** (if not already configured):
   ```bash
   aws configure
   ```

## Setup

1. **Configure Environments**: The `config/` directory contains YAML files for each environment. Before deploying, you **must** update the `aws_profile` in these files to match the AWS CLI profiles you have configured on your machine.

   - `config/dev.yaml`
   - `config/stage.yaml`
   - `config/prod.yaml`

   **Example `config/dev.yaml`:**
   ```yaml
   # Development Environment Configuration
   aws_region: us-east-1
   aws_profile: my-dev-profile # <-- Change this to your development profile
   ```

## Usage

The script is driven by the `--env` flag, which tells it which configuration file to use.

### Creating a Deployment

To create a new application and prepare it for deployment, use `genoai` and specify the environment.

**Example: Initialize a `dev` project**
```bash
./genoai init --env dev
```

The CLI will prompt you for the application name and destination directory. It will use the `aws_region` and `aws_profile` from `config/dev.yaml`.

**Example: Deploy the current project to `prod`**
```bash
./genoai deploy --env prod
```
This uses the settings from `config/prod.yaml` and deploys a stack named `<app-name>-prod-stack`.

### Generating Micronaut controllers from an API config

You can provide a YAML API config that defines a service package and a set of routes. The CLI will parse it and generate Micronaut controllers, and configure SAM for proxy-all routing.

Example (no API key required by default):
```bash
./genoai init --env dev --api-config ./config/example_api.yaml
```

The example config lives at `config/example_api.yaml`.

### Requiring an API key

By default, deployments do not require an API key. To require an API key for all routes, pass `--requires-key`:

```bash
./genoai init --env dev --api-config ./config/example_api.yaml --requires-key
```

When `--requires-key` is set, the SAM template includes API Gateway API key resources and the output will include the generated API key value. Without the flag, the stack omits API key resources and the API is publicly accessible (consider adding authorizers for real authentication).

## CLI Architecture

The CLI has been refactored into a modular architecture for better maintainability and extensibility:

### **GenoAI CLI**
```bash
./genoai init --env dev --api-config ./config/example_api.yaml --requires-key
./genoai deploy --env dev
```

### **Module Structure**
- **`cli/main.py`** - CLI orchestrator and argument parsing
- **`cli/config.py`** - Configuration management and validation
- **`cli/project.py`** - Micronaut project generation and setup
- **`cli/build.py`** - Build operations (Gradle, JAR, SAM template)
- **`cli/deploy.py`** - AWS deployment and stack management
- **`cli/utils.py`** - Shared utilities and helpers

## Version Management

The CLI uses semantic versioning with Git tags:

```bash
# Check current version
genoai --version

# List all version tags
make list-tags

# Create a new release (for maintainers)
make release VERSION=1.2.3
make release-dry-run VERSION=1.2.3  # Preview changes
```

## GitHub Actions Integration

This repository includes GitHub Actions workflows that automatically deploy Micronaut APIs to AWS when API configuration files are changed.

### Automatic Deployment

The workflow triggers on:
- **Push to main** with changes to `config/*.yaml` files
- **Pull requests** with config changes (deploys to dev for testing)
- **Manual dispatch** for custom deployments

### Setup

1. **Configure AWS Secrets** (see [.github/SECRETS.md](.github/SECRETS.md)):
   - `AWS_ACCESS_KEY_ID`
   - `AWS_SECRET_ACCESS_KEY` 
   - `AWS_REGION`

2. **Create or modify API configs** in the `config/` directory

3. **Push changes** - the workflow will automatically:
   - Generate Micronaut project from your config
   - Build and test the application
   - Deploy to AWS Lambda + API Gateway
   - Comment deployment details on PRs

### Manual Deployment

Use the **Deploy Micronaut API** workflow with custom parameters:

```yaml
api_config: config/my-api.yaml
environment: prod
requires_key: true
```

### Workflow Features

- **Multi-environment support** (dev/stage/prod)
- **Automatic testing** of deployed endpoints
- **Artifact uploads** (JAR files, reports)
- **PR comments** with deployment URLs and test commands
- **Matrix builds** for multiple API configs

### Deleting a Deployment

To delete a deployed stack, specify the environment and either the app name or project path.

**Example: Delete the `dev` stack (by app name)**
```bash
./genoai delete-stack my-cool-app --env dev
```

To delete the stack **and** remove the project directory from your local machine, use the `delete-all` command.

**Example: Delete the `prod` stack and all local files**
```bash
./genoai delete-all ./my-cool-app --env prod
```

## Shell Completion

Enable shell completion for easier CLI use:

```bash
# Bash
eval "$(_GENOAI_COMPLETE=bash_source genoai)"

# Zsh
eval "$(_GENOAI_COMPLETE=zsh_source genoai)"

# Fish
eval ( _GENOAI_COMPLETE=fish_source genoai )
```