npm package: @mhaderka/cli-ai-plugin
Description: A plugin to generate light modules for Magnolia CMS using AI.
Author: Martin Haderka
Latest version: 1.0.1

# AI Plugin for Magnolia CLI

## Important Note

**This plugin is experimental.** Outputs generated by the plugin should be reviewed for accuracy and completeness before use. Prompts and data are sent to OpenAI’s API for processing, so **avoid including sensitive or confidential information.** As an experimental tool, it may produce unexpected results.

## Descript

This plugin integrates AI capabilities into Magnolia CMS by leveraging OpenAI’s embeddings and completions. With this plugin, you can generate fully functional light modules (such as content types, apps, components, and pages) guided by natural language prompts. The result is a streamlined development process that allows developers and content creators to quickly bootstrap Magnolia artifacts.

## Features

- **Magnolia CMS Integration:** Generates Magnolia light modules directly into your project’s configured `lightModulesPath`.
- **AI-Assisted Generation:** Uses an AI backend to create YAML-based Magnolia artifacts from human-readable prompts.
- **Configurable Types:** Supports Magnolia light module types including `contentType`, `app`, `component`, and `page`.
- **Availability Injection:** Easily add component dialogs to page availability through a command-line option.

## Requirements

- **Node.js:** Version 16+ recommended.
- **NPM:** Comes with Node.js by default.
- **OpenAI API Key & Backend:** The plugin expects a running backend (like the `prompt-plugin-backend` or a similar API) to handle embedding and generation logic.
- **Magnolia CMS Knowledge:** Familiarity with Magnolia light modules, YAML files, and project structure is beneficial but not required.

## Setup

1. **Install Dependencies:**
   ```bash
   npm install
   ```
2. **Build the Project:**
   ```bash
   npm run build
   ```
3. **Configure Magnolia Project:**
   Ensure your `mgnl.config.js` file has both `lightModule` and `lightModulesPath` set. For example:
   ```bash
   export default {
     lightModule: "my-light-module",
     lightModulesPath: "./light-modules"
   };
   ```
   
   **Note:**
      * lightModule: The name of the specific light module to which new artifacts will be added.
      * lightModulesPath: The path to the directory containing all your light modules.

4. **Backend URL:**

    The plugin currently sends requests to:
    ```bash
    https://prompt-plugin-backend.azurewebsites.net/prompt
    ```
    Make sure you have a running backend at this endpoint that can handle the requests. Update the code or environment if a different endpoint is needed
    
## Running the Plugin

Use the following command format to generate a new Magnolia artifact:
```bash
npm run mgnl -- ai-prompt <type> "<prompt>"
```

**Arguments:**

* \<type>: One of contentType, app, component, or page.
* \<prompt>: A textual description of what you want to build. For example: "to manage car inventory".

Example:
```bash
npm run mgnl -- ai-prompt app "to manage cars including color, model, year and other fields typical for vehicles"
```

**Availability Option:**
* Use `-a` or `--available` followed by `path-to-page[@area]` to automatically add component availability to a page area:
  ```bash
  npm run mgnl -- ai-prompt component "a testimonial component" -a templates/pages/home[@main]
  ```

## Testing
Run the tests with:
```bash
npm run test
```

## Configuration & Customization
* Backend Endpoint: If you need to point to a different backend, update the `axios.post()` URL in `ai-plugin.ts`.
* Logging & Internationalization: This plugin uses `winston` for logging and `i18next` for localization. Adjust configurations as needed in the `lib` folder or in `mgnl.config.js`.

## Project Structure
* `ai-plugin.ts`: The main plugin logic that sends prompts to the backend and writes results to the file system.
* `index.ts`: Exports the plugin’s entry point.
* `lib/`: Helper utilities and modules, including i18n and availability logic.
* `types/`: Type definitions for plugin arguments and options.
* `jest.config.js` & `tsconfig.json`: Project-specific testing and TypeScript configurations.

## Usage Example

1. **Create a New Magnolia Project**  
   Create a project folder and initialize it with a Magnolia template by running the following command:  
   ```bash
   npx @magnolia/cli@5 jumpstart -pt "https://raw.githubusercontent.com/hader00/project-template-ai-plugin/refs/heads/main/projectTemplates.json" -t "ai-plugin-example"
   ```

2. **Verify Plugin Installation**  
   After the project setup is complete, confirm that the AI-driven plugin is installed by running:  
   ```bash
   npm run mgnl -- ai-prompt -h
   ```

3. **Generate a Light Module folder**  
   Use the create-light-module-plugin to generate a Magnolia light module:  
   ```bash
   npm run mgnl -- create-light-module "my-lm"
   ```
   
3. **Generate a New Artifact**  
   Use the plugin to generate a Magnolia light module artifact. For example, to create a new app, execute:  
   ```bash
   npm run mgnl -- ai-prompt app "to manage cars including color, model, year and other fields typical for vehicles"
   ```

4. **Inspect the Generated Output**  
   Navigate to the `light-modules` folder in your project directory to view the generated YAML configuration for the app.

5. **Start Magnolia CMS**  
   Start Magnolia CMS locally to explore and interact with the generated content type. This will allow you to observe how the custom configuration behaves within the CMS environment.
   ```bash
   npm run mgnl -- start
   ```