### Run Gradle Tests in Demo Project

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/test-suite-helloworld-cli/README.md

Navigate into the generated project directory and run the tests using Gradle. This verifies the project setup and added features.

```bash
cd demo
./gradlew test
```

--------------------------------

### Implement Options Interface for Project Generation

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/src/main/docs/guide/demo/defineOptions.adoc

Implement the `api:projectgen.core.options.Options` interface to define custom project generation options. This example shows a basic implementation.

```java
package io.micronaut.projectgen.demo;

import io.micronaut.projectgen.core.options.Options;
import io.micronaut.projectgen.core.options.OptionsFactory;
import jakarta.inject.Singleton;

@Singleton
public class OptionsFactory implements OptionsFactory {

    @Override
    public Options create() {
        return new Options() {
            @Override
            public String getName() {
                return "demo";
            }

            @Override
            public String getDescription() {
                return "A demo project";
            }
        };
    }
}
```

--------------------------------

### Features Endpoint Response Example

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Example JSON response from the `/api/v1/features` endpoint, listing available features with their details.

```json
{
  "features": [
    {
      "name": "graalvm",
      "title": "GraalVM Native Image",
      "description": "Support for compiling Micronaut applications to native images using GraalVM.",
      "preview": false,
      "community": false
    },
    {
      "name": "http-server",
      "title": "Micronaut HTTP Server",
      "description": "Adds Netty-based HTTP server support.",
      "preview": false,
      "community": false
    }
  ]
}
```

--------------------------------

### Micronaut CLI Project Generation Example

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/src/main/docs/guide/demo/cli.adoc

Use this Java code to create a Micronaut CLI application that generates a project. It leverages the ProjectGenerator API to create a project in a specified directory.

```java
package io.micronaut.projectgen.demo;

import io.micronaut.core.annotation.NonNull;
import io.micronaut.core.annotation.Nullable;
import io.micronaut.inject.cli.Command;
import io.micronaut.projectgen.core.generator.ProjectGenerator;
import io.micronaut.projectgen.core.model.ProjectModel;
import jakarta.inject.Inject;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;

@Command(name = "create", description = "Create a new project")
public class CreateCommand {

    @Inject
    private ProjectGenerator projectGenerator;

    @Command
    public void create(@NonNull String name, @Nullable Path directory) throws IOException {
        if (directory == null) {
            directory = Path.of(System.getProperty("user.dir"));
        }
        if (!Files.exists(directory)) {
            Files.createDirectories(directory);
        }
        ProjectModel project = ProjectModel.builder(name).build();
        projectGenerator.generate(project, directory);
        System.out.println("Project " + name + " generated in " + directory.toAbsolutePath());
    }
}

```

--------------------------------

### Language Enum Usage

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Illustrates the use of the `Language` enum for supported JVM programming languages. Shows how to get language extensions, source directories, and generate full file paths for source and test files. Also demonstrates utility methods for retrieving all extensions and source directories.

```java
import io.micronaut.projectgen.core.options.Language;

Language lang = Language.of("kotlin").orElseThrow();

System.out.println(lang.getExtension());    // → "kt"
System.out.println(lang.getSrcDir());       // → "src/main/kotlin"
System.out.println(lang.getTestSrcDir());   // → "src/test/kotlin"

// Full file path helpers
String srcPath = lang.getSourcePath("/com/example/App");
// → "src/main/kotlin/com/example/App.kt"

String testPath = lang.getTestSourcePath("/com/example/AppTest");
// → "src/test/kotlin/com/example/AppTest.kt"

// Aggregate utilities
String[] allExtensions = Language.extensions(); // ["py", "java", "groovy", "kt"]
String[] allSrcDirs    = Language.srcDirs();    // ["src/main/python", ...]
```

--------------------------------

### Publish Micronaut to Maven Local

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/CONTRIBUTING.md

Run this task to get a local development version of Micronaut XXX working. You can then reference the version specified in `gradle.properties` in a test project.

```bash
./gradlew pTML
```

--------------------------------

### Get Inline Diff via HTTP API

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Use `POST /api/v1/diff` to retrieve the project diff inline as `text/plain`. Requires a `FeatureDiffer` bean in the context.

```bash
# Inline diff
curl -X POST http://localhost:8080/api/v1/diff \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "name=demo&lang=java&build=gradle&java=21&features=graalvm"
```

--------------------------------

### Configure Project Generation Options

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Demonstrates how to configure project generation options using `GenericOptionsBuilder`. Shows how to set project name, package, build tools, language, JDK version, test framework, and features. Also illustrates accessing computed defaults for source paths and build tools.

```java
import io.micronaut.projectgen.core.options.*;
import io.micronaut.projectgen.core.buildtools.BuildTool;
import io.micronaut.projectgen.core.buildtools.gradle.GradleDsl;

// Build Options for a Kotlin + Gradle Kotlin DSL project targeting JDK 21
Options options = GenericOptionsBuilder.builder()
    .name("my-service")
    .packageName("com.example")
    .group("com.example")
    .artifact("my-service")
    .version("0.1")
    .language(Language.KOTLIN)
    .buildTools(List.of(BuildTool.GRADLE))
    .gradleDsl(GradleDsl.KOTLIN)
    .java(JdkVersion.JDK_21)
    .testFramework(TestFramework.KOTEST)
    .features(List.of("graalvm", "http-client"))
    .build();

// Access computed defaults
String sourcePath = options.language().getSourcePath("/com/example/Application");
// → "src/main/kotlin/com/example/Application.kt"

String testPath = options.testFramework().getSourcePath("/com/example/MyService", options.language());
// → "src/test/kotlin/com/example/MyServiceTest.kt"

BuildTool primary = options.getBuildTool(); // → BuildTool.GRADLE
```

--------------------------------

### Create Project Directory

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/test-suite-helloworld-cli/README.md

Create a new directory where the project will be generated. Ensure this directory is empty.

```bash
mkdir demo
```

--------------------------------

### Add Sample Java Code

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/src/main/docs/guide/demo/addCode.adoc

Demonstrates adding a basic Java source file to the generated project. This is useful for including starter code or utility classes.

```java
package io.micronaut.projectgen.demo;

public class SampleCode {

    public String hello() {
        return "Hello World!";
    }
}
```

--------------------------------

### Run Maven Tests in Demo Project

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/test-suite-helloworld-cli/README.md

Navigate into the generated project directory and run the tests using Maven. This provides an alternative way to verify the project.

```bash
cd demo
./mvnw test
```

--------------------------------

### Build test-suite-helloworld-cli Module

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/test-suite-helloworld-cli/README.md

Build the specified module in the project. This is a prerequisite for using the CLI.

```bash
./gradlew :test-suite-helloworld-cli:build
```

--------------------------------

### Test Project Generation

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/src/main/docs/guide/demo/test.adoc

This Java code snippet demonstrates how to test the project generation functionality. It includes necessary imports and a test method.

```java
package io.micronaut.projectgen.demo;

import io.micronaut.projectgen.ProjectGenerator;
import org.junit.jupiter.api.Test;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;

import static org.junit.jupiter.api.Assertions.assertTrue;

class ProjectGenTest {

    @Test
    void testProjectGeneration() throws IOException {
        Path tempDir = Files.createTempDirectory("micronaut-projectgen-test");
        ProjectGenerator generator = new ProjectGenerator(tempDir);
        generator.generate("my-app");

        Path appPath = tempDir.resolve("my-app");
        assertTrue(Files.exists(appPath));
        assertTrue(Files.isDirectory(appPath));

        // Further assertions can be added here to check the generated project structure and files
    }
}

```

--------------------------------

### Inspect OpenRewrite Recipes with RecipeFetcher

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Use `RecipeFetcher` to retrieve dependencies, properties, and files declared in OpenRewrite recipes. This Java code demonstrates how to fetch Gradle and Maven dependencies, application and bootstrap properties, files, and documentation links associated with a given recipe name.

```java
import io.micronaut.projectgen.core.openrewrite.RecipeFetcher;
import io.micronaut.projectgen.core.buildtools.BuildTool;
import jakarta.inject.Inject;

@Singleton
public class RecipeInspector {

    @Inject RecipeFetcher recipeFetcher;

    public void inspect(String recipeName) {
        // Retrieve dependencies declared in the recipe for Gradle
        var gradleDeps = recipeFetcher.findAllByRecipeNameAndBuildTool(recipeName, BuildTool.GRADLE);
        gradleDeps.forEach(d -> System.out.printf("Gradle: %s:%s%n", d.getGroupId(), d.getArtifactId()));

        // Maven variant
        var mavenDeps = recipeFetcher.findAllByRecipeNameAndBuildTool(recipeName, BuildTool.MAVEN);

        // Application properties added by the recipe
        recipeFetcher.findPropertiesByRecipeName(recipeName)
            .ifPresent(props -> props.forEach((k, v) -> System.out.printf("%s=%s%n", k, v)));

        // Bootstrap properties
        recipeFetcher.findBootstrapPropertiesByRecipeName(recipeName)
            .ifPresent(props -> props.forEach((k, v) -> System.out.printf("bootstrap.%s=%s%n", k, v)));

        // Files created by the recipe (e.g. XML files)
        recipeFetcher.findAllFilesByRecipeName(recipeName)
            .forEach(fc -> System.out.println("File: " + fc.relativeFileName()));

        // Documentation links
        recipeFetcher.findFrameworkDocumentationByRecipeName(recipeName)
            .ifPresent(link -> System.out.println("Docs: " + link));
    }
}
```

--------------------------------

### Generate New Project with CLI

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/test-suite-helloworld-cli/README.md

Use the built CLI tool to generate a new project in the specified output directory. This command assumes the CLI JAR is in the correct location.

```bash
java -jar test-suite-helloworld-cli/build/libs/test-suite-helloworld-cli-0.1-all.jar create --output demo
```

--------------------------------

### Generate Gradle build file (build.gradle.kts)

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/src/main/docs/guide/demo.adoc

This Kotlin script configures the Gradle build for a Java application, including dependencies and main class.

```kotlin
plugins {
    id("java")
    id("application")
}
group = "io.micronaut.projectgen"
version = "1.0.0"
repositories {
    mavenCentral()
}
dependencies {
    testImplementation("org.junit.jupiter:junit-jupiter:5.10.2")
}
java {
    sourceCompatibility = JavaVersion.VERSION_21
    targetCompatibility = JavaVersion.VERSION_21
}
tasks.test {
    useJUnitPlatform()
}

application {
    mainClass.set("com.example.HelloWorld")
}
```

--------------------------------

### Generate Maven build file (pom.xml)

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/src/main/docs/guide/demo.adoc

This XML configuration sets up the Maven build for a Java project, specifying plugins, dependencies, and the main class.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>io.micronaut.projectgen</groupId>
  <artifactId>demo-project</artifactId>
  <version>1.0.0</version>
  <properties>
    <maven.compiler.source>21</maven.compiler.source>
    <maven.compiler.target>21</maven.compiler.target>
  </properties>
  <dependencies>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>5.10.2</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.1.2</version>
      </plugin>
      <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-jar-plugin</artifactId>
          <version>3.3.0</version>
          <configuration>
              <archive>
                  <manifest>
                      <mainClass>com.example.HelloWorld</mainClass>
                  </manifest>
              </archive>
          </configuration>
      </plugin>
    </plugins>
  </build>
</project>
```

--------------------------------

### Download Project Diff via API

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Use this curl command to download a project diff. Specify project name, language, build tool, Java version, and desired features.

```bash
curl -X POST http://localhost:8080/api/v1/diff/download \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "name=demo&lang=java&build=gradle&java=21&features=graalvm" \
  -o demo.diff
```

--------------------------------

### Project Download Controller

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/src/main/docs/guide/demo/httpServerDemo.adoc

This Java controller handles requests to download a ZIP file containing a generated project. It utilizes Micronaut Views for server-side HTML rendering.

```java
package io.micronaut.projectgen.demo;

import io.micronaut.core.annotation.Nullable;
import io.micronaut.http.HttpRequest;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.server.types.files.StreamedFile;
import io.micronaut.projectgen.ProjectGenerator;
import io.micronaut.projectgen.model.ProjectRequest;
import io.micronaut.views.ViewsRenderer;

import java.io.ByteArrayInputStream;
import java.util.Map;

@Controller
public class HomeController {

    private final ViewsRenderer viewsRenderer;
    private final ProjectGenerator projectGenerator;

    public HomeController(ViewsRenderer viewsRenderer, ProjectGenerator projectGenerator) {
        this.viewsRenderer = viewsRenderer;
        this.projectGenerator = projectGenerator;
    }

    @Get
    public StreamedFile index(HttpRequest<?> request, @Nullable String feature) {
        return new StreamedFile(new ByteArrayInputStream(viewsRenderer.render("index", Map.of("features", ProjectGenerator.FEATURES, "feature", feature == null ? "" : feature)).getBytes()), "text/html");
    }

    @Get("/download")
    public StreamedFile download(HttpRequest<?> request) {
        ProjectRequest projectRequest = new ProjectRequest();
        projectRequest.setFeatures(request.getParameters().values().stream().toList());
        return new StreamedFile(projectGenerator.generate(projectRequest), "application/zip");
    }
}
```

--------------------------------

### Download Project ZIP via HTTP API

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Use the `POST /api/v1/download/zip` endpoint to generate and download a project as a ZIP file. Accepts form-urlencoded data for project configuration.

```bash
# Generate a Micronaut Kotlin + Gradle project with GraalVM support
curl -X POST http://localhost:8080/api/v1/download/zip \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "name=my-app&lang=kotlin&build=gradle&gradleDsl=KOTLIN&java=21&testFramework=kotest&features=graalvm,http-server&packageName=com.example" \
  -o my-app.zip

# Verify the archive contents
unzip -l my-app.zip
# Archive:  my-app.zip
#   Length      Date    Time    Name
# ---------  ---------- -----   ----
#      ...   2025-04-28 00:00   my-app/build.gradle.kts
#      ...   2025-04-28 00:00   my-app/settings.gradle.kts
#      ...   2025-04-28 00:00   my-app/src/main/kotlin/com/example/Application.kt
#      ...   ... 

```

--------------------------------

### List Available Features via HTTP API

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Query available features for project generation using `POST /api/v1/features`. This is useful for populating UI feature selectors.

```bash
curl -X POST http://localhost:8080/api/v1/features \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "lang=java&build=gradle&java=21" | jq .
```

--------------------------------

### Publish test-suite-openrewrite to Maven Local

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/test-suite-helloworld-cli/README.md

Publish the OpenRewrite recipes module to your local Maven repository. This is necessary for the CLI to access the recipes.

```bash
./gradlew publishToMavenLocal
```

--------------------------------

### BuildTool Enum Usage

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Shows how to use the `BuildTool` enum to identify build tools like Gradle and Maven. Demonstrates obtaining a `BuildTool` instance from a string, accessing its conventional JAR directory and display title, and using the default option.

```java
import io.micronaut.projectgen.core.buildtools.BuildTool;

BuildTool tool = BuildTool.of("gradle").orElseThrow();
// tool == BuildTool.GRADLE

System.out.println(tool.getJarDirectory()); // → "build/libs"
System.out.println(tool.getTitle());         // → "Gradle"
System.out.println(BuildTool.DEFAULT_OPTION); // → BuildTool.GRADLE

BuildTool maven = BuildTool.MAVEN;
System.out.println(maven.getJarDirectory()); // → "target"
```

--------------------------------

### Generate Projects to a Directory with ProjectGenerator

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Use ProjectGenerator.writeTo() to generate project files directly into a specified filesystem directory. Ensure the Options object is configured with project details.

```java
import io.micronaut.projectgen.core.generator.ProjectGenerator;
import io.micronaut.projectgen.core.io.FileSystemOutputHandler;
import io.micronaut.projectgen.core.io.ConsoleOutput;
import io.micronaut.projectgen.core.options.*;
import io.micronaut.projectgen.core.buildtools.BuildTool;
import jakarta.inject.Inject;
import java.io.File;
import java.util.List;

@Singleton
public class GenerationService {

    @Inject ProjectGenerator projectGenerator;

    // Generate directly to a filesystem directory
    public void generateToDirectory(File outputDir) {
        Options options = GenericOptionsBuilder.builder()
            .name("demo-app")
            .packageName("com.example")
            .language(Language.JAVA)
            .buildTools(List.of(BuildTool.GRADLE))
            .java(JdkVersion.JDK_21)
            .testFramework(TestFramework.JUNIT)
            .features(List.of("http-server", "graalvm"))
            .build();

        projectGenerator.writeTo(options, outputDir);
        // → writes all project files under outputDir/demo-app/
    }

    // Generate using a custom OutputHandler with console logging
    public void generateWithHandler(OutputHandler handler) throws Exception {
        Options options = GenericOptionsBuilder.builder()
            .name("demo-app")
            .packageName("com.example")
            .language(Language.KOTLIN)
            .buildTools(List.of(BuildTool.MAVEN))
            .java(JdkVersion.JDK_21)
            .testFramework(TestFramework.JUNIT)
            .build();

        projectGenerator.generate(options, handler, msg -> System.out.println("[WARN] " + msg));
    }
}
```

--------------------------------

### Add Maven Surefire Plugin

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/src/main/docs/guide/demo/addMavenPlugin.adoc

This code snippet shows how to integrate the Maven Surefire Plugin into your project.

```java
package io.micronaut.projectgen.demo;

import io.micronaut.projectgen.ProjectGenerator;
import io.micronaut.projectgen.buildtools.maven.MavenPlugin;

public class MavenSurefirePlugin {

    public static void main(String[] args) {
        ProjectGenerator.generate(project -> {
            project.getBuildTools().getMaven().addPlugin(MavenPlugin.builder()
                    .groupId("org.apache.maven.plugins")
                    .artifactId("maven-surefire-plugin")
                    .version("3.1.2")
                    .build());
        });
    }
}
```

--------------------------------

### Generate Project Diff with FeatureDiffer

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Use `FeatureDiffer` to generate a unified diff string showing file changes when applying specific features. Requires `Options` to be configured.

```java
import io.micronaut.projectgen.core.diff.FeatureDiffer;
import io.micronaut.projectgen.core.options.*;
import io.micronaut.projectgen.core.buildtools.BuildTool;
import jakarta.inject.Inject;
import java.util.List;

@Singleton
public class DiffService {

    @Inject FeatureDiffer featureDiffer;

    public String getDiff() throws Exception {
        Options options = GenericOptionsBuilder.builder()
            .name("demo")
            .packageName("com.example")
            .language(Language.JAVA)
            .buildTools(List.of(BuildTool.GRADLE))
            .java(JdkVersion.JDK_21)
            .features(List.of("graalvm"))
            .build();

        String diff = featureDiffer.diff(options);
        System.out.println(diff);
        // Output: unified diff text showing new/modified files when graalvm feature is added
        return diff;
    }
}
```

--------------------------------

### Configure Download ZIP Endpoint

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Customize the path and enabled state of the download ZIP endpoint using `application.yml` configuration.

```yaml
projectgen:
  controllers:
    download-zip:
      enabled: true
      path: /api/v1/download/zip   # default
```

--------------------------------

### Configure Controller Paths and Enablement

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

This YAML configuration allows overriding controller paths and enabling/disabling them. It defines settings for download-zip, features, and diff controllers.

```yaml
# application.yml — override all controller paths and toggle them individually
projectgen:
  controllers:
    download-zip:
      enabled: true
      path: /api/v1/download/zip     # POST → returns project ZIP
    features:
      enabled: true
      path: /api/v1/features         # POST → returns available features JSON

project:
  controllers:
    diff:
      enabled: true
      path: /api/v1/diff             # POST → returns diff as text/plain
```

--------------------------------

### Configure Maven Local Repository for Gradle

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/CONTRIBUTING.md

If you use Gradle, add the `mavenLocal` repository to your project's `build.gradle` file to reference local Micronaut versions. Maven automatically handles this.

```gradle
repositories {
    mavenLocal()
    mavenCentral()
}
```

--------------------------------

### Add Maven Jar Plugin

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/src/main/docs/guide/demo/addMavenPlugin.adoc

Use this code to add the Maven Jar Plugin to your project configuration.

```java
package io.micronaut.projectgen.demo;

import io.micronaut.projectgen.ProjectGenerator;
import io.micronaut.projectgen.buildtools.maven.MavenPlugin;

public class MavenJarPluginFeature {

    public static void main(String[] args) {
        ProjectGenerator.generate(project -> {
            project.getBuildTools().getMaven().addPlugin(MavenPlugin.builder()
                    .groupId("org.apache.maven.plugins")
                    .artifactId("maven-jar-plugin")
                    .version("3.3.0")
                    .build());
        });
    }
}
```

--------------------------------

### Define Root Feature for Project Generation

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/src/main/docs/guide/demo/root.adoc

This Java code defines a root feature for project generation. It demonstrates how a feature can apply other features by implementing the `DefaultFeature` interface and its `shouldApply` method.

```java
package io.micronaut.projectgen.demo;

import io.micronaut.core.annotation.NonNull;
import io.micronaut.core.annotation.Nullable;
import io.micronaut.projectgen.core.feature.DefaultFeature;
import io.micronaut.projectgen.core.feature.Feature;
import io.micronaut.projectgen.core.project.ProjectGenerationContext;

import jakarta.inject.Singleton;

@Singleton
public class Root implements DefaultFeature {

    @Override
    @NonNull
    public String getName() {
        return "root";
    }

    @Override
    @Nullable
    public Feature[] getFeatures() {
        return new Feature[]{ new HelloWorldFeature() };
    }

    @Override
    public boolean shouldApply(@NonNull ProjectGenerationContext context) {
        return true;
    }
}

```

--------------------------------

### Add Gradle Java Plugin

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/src/main/docs/guide/demo/addGradlePlugins.adoc

Use this feature to include the Gradle Java Plugin in your project. Ensure the necessary ProjectGen API is available.

```java
package io.micronaut.projectgen.demo;

import io.micronaut.projectgen.core.buildtools.gradle.GradlePlugin;
import io.micronaut.projectgen.core.buildtools.gradle.GradlePluginConfiguration;
import io.micronaut.projectgen.core.buildtools.gradle.GradlePluginConfiguration.PluginType;
import io.micronaut.projectgen.core.feature.Feature;

public class GradleJavaPluginFeature implements Feature {

    @Override
    public void apply(FeatureContext context) {
        context.getBuildTools().getGradle().addPlugin(GradlePlugin.builder()
                .id("java")
                .configuration(GradlePluginConfiguration.builder()
                        .type(PluginType.CORE)
                        .build())
                .build());
    }
}
```

--------------------------------

### JDK Version: `JdkVersion`

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Represents a major JDK release. Predefined constants exist from JDK 8 to JDK 23. Arbitrary versions can be parsed from a string or integer.

```java
import io.micronaut.projectgen.core.options.JdkVersion;

// From constant
JdkVersion jdk21 = JdkVersion.JDK_21;
System.out.println(jdk21.majorVersion()); // → 21
System.out.println(jdk21.name());         // → "JDK_21"
System.out.println(jdk21.asString());     // → "21"

// From string (supports "21" or "JDK_21")
JdkVersion parsed = JdkVersion.valueOf("17");
System.out.println(parsed.majorVersion()); // → 17

// Version comparison
boolean isModern = jdk21.greaterThanEqual(JdkVersion.JDK_17); // → true

// List all known versions
JdkVersion.JDKS.forEach(v -> System.out.println(v.name()));
// JDK_8, JDK_9, ..., JDK_23
```

--------------------------------

### Run Checkstyle for a Module

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/CONTRIBUTING.md

Execute Checkstyle for a specific module to ensure code adheres to Micronaut's standards for organization, Javadoc, and style. The configuration is defined in `config/checkstyle/checkstyle.xml`.

```bash
./gradlew <module-name>:checkstyleMain
```

--------------------------------

### Configure Features Endpoint

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Control the enabled state and path of the features endpoint via `application.yml` configuration.

```yaml
projectgen:
  controllers:
    features:
      enabled: true
      path: /api/v1/features   # default
```

--------------------------------

### Default Feature Interface: `DefaultFeature` Implementation

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Extends `Feature` with a `shouldApply` predicate for automatic inclusion based on conditions. Implement this for features that should be applied by default when specific criteria are met.

```java
import io.micronaut.projectgen.core.feature.*;
import io.micronaut.projectgen.core.options.Options;
import io.micronaut.projectgen.core.options.Language;
import jakarta.inject.Singleton;
import java.util.Set;

@Singleton
public class KotlinStdlibFeature implements DefaultFeature {

    @Override
    public String getName() { return "kotlin-stdlib"; }

    @Override
    public boolean shouldApply(Options options, Set<Feature> selectedFeatures) {
        // Automatically apply when the selected language is Kotlin
        return options.language() == Language.KOTLIN;
    }

    @Override
    public void apply(io.micronaut.projectgen.core.generator.GeneratorContext ctx) {
        ctx.getRootModule().addDependency(
            io.micronaut.projectgen.core.buildtools.dependencies.Dependency.builder()
                .groupId("org.jetbrains.kotlin")
                .artifactId("kotlin-stdlib-jdk8")
                .compile()
                .build()
        );
    }
}
```

--------------------------------

### Generate Project ZIP Archive with ZipGenerator

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Use ZipGenerator.zip() to create an in-memory ZIP archive of a generated project. The result is a Micronaut Writable, suitable for streaming or writing to disk.

```java
import io.micronaut.projectgen.core.io.zip.ZipGenerator;
import io.micronaut.projectgen.core.options.*;
import io.micronaut.projectgen.core.buildtools.BuildTool;
import jakarta.inject.Inject;
import java.io.*;
import java.nio.file.*;
import java.util.List;

@Singleton
public class DownloadService {

    @Inject ZipGenerator zipGenerator;

    public byte[] downloadProjectZip() throws IOException {
        Options options = GenericOptionsBuilder.builder()
            .name("my-project")
            .packageName("org.example")
            .language(Language.GROOVY)
            .buildTools(List.of(BuildTool.GRADLE))
            .java(JdkVersion.JDK_17)
            .testFramework(TestFramework.SPOCK)
            .build();

        var writable = zipGenerator.zip(options);
        ByteArrayOutputStream baos = new ByteArrayOutputStream();
        writable.writeTo(new OutputStreamWriter(baos));
        return baos.toByteArray();
        // → ZIP bytes containing the generated project structure
    }
}
```

--------------------------------

### Test Framework Enum: `TestFramework`

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Models supported test frameworks, understanding language constraints, source path conventions, and file-name suffixes. Use `TestFramework.of()` for custom frameworks.

```java
import io.micronaut.projectgen.core.options.TestFramework;
import io.micronaut.projectgen.core.options.Language;

// JUnit works with Java, Kotlin, and Groovy
TestFramework junit = TestFramework.JUNIT;
System.out.println(junit.getTestFrameworkSuffix()); // → "Test."
System.out.println(junit.getSupportedLanguages());   // → [JAVA, KOTLIN, GROOVY]

// Spock requires Groovy
TestFramework spock = TestFramework.SPOCK;
System.out.println(spock.getDefaultLanguage());       // → GROOVY
System.out.println(spock.getTestFrameworkSuffix());   // → "Spec."
System.out.println(spock.getSourcePath("/com/example/MyService", Language.GROOVY));
// → "src/test/groovy/com/example/MyServiceSpec.groovy"

// Kotest requires Kotlin
TestFramework kotest = TestFramework.of("kotest").orElseThrow();
System.out.println(kotest.isKotlinTestFramework()); // → true
```

--------------------------------

### Build Dependencies with Dependency.builder()

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Use Dependency.builder() to create dependency objects. Supports standard JVM scopes for Gradle and Maven. Versions can be explicit or resolved from a BOM.

```java
import io.micronaut.projectgen.core.buildtools.dependencies.Dependency;

// Explicit coordinates
Dependency compileLib = Dependency.builder()
    .groupId("io.micronaut.data")
    .artifactId("micronaut-data-jdbc")
    .version("4.10.0")
    .compile()
    .build();
```

```java
// BOM-managed (version resolved from CoordinateResolver)
Dependency bomDep = Dependency.builder()
    .lookupArtifactId("micronaut-data-processor")
    .annotationProcessor()
    .build();
```

```java
// Annotation processor with priority flag
Dependency apPriority = Dependency.builder()
    .lookupArtifactId("micronaut-inject-java")
    .annotationProcessor(true)
    .build();
```

```java
// POM import
Dependency bom = Dependency.builder()
    .groupId("io.micronaut.platform")
    .artifactId("micronaut-platform")
    .version("4.7.0")
    .pom()
    .compile()
    .build();
```

```java
// Test runtime with exclusion
Dependency testRuntime = Dependency.builder()
    .groupId("ch.qos.logback")
    .artifactId("logback-classic")
    .testRuntime()
    .exclude(Dependency.builder().groupId("org.slf4j").artifactId("slf4j-api").build())
    .build();
```

--------------------------------

### Feature Interface: `Feature` Implementation

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

The primary extension point for features. Implement this interface to declare a unique name, optional ordering, and lifecycle hooks for processing and applying features.

```java
import io.micronaut.projectgen.core.feature.*;
import io.micronaut.projectgen.core.generator.GeneratorContext;
import io.micronaut.projectgen.core.options.Options;
import io.micronaut.projectgen.core.buildtools.dependencies.Dependency;
import io.micronaut.projectgen.core.buildtools.Scope;
import jakarta.inject.Singleton;

@Singleton
public class MyDatabaseFeature implements Feature {

    @Override
    public String getName() { return "my-database"; }

    @Override
    public String getTitle() { return "My Database"; }

    @Override
    public String getDescription() { return "Adds My Database support."; }

    @Override
    public int getOrder() { return FeaturePhase.DEFAULT.getOrder(); }

    @Override
    public boolean supports(Options options) {
        // Only for Gradle projects
        return options.getBuildTool() != null;
    }

    @Override
    public void apply(GeneratorContext ctx) {
        // Add a compile-time dependency
        ctx.getRootModule().addDependency(
            Dependency.builder()
                .groupId("com.example")
                .artifactId("my-db-driver")
                .version("1.0.0")
                .compile()
                .build()
        );
        // Add application config
        ctx.getRootModule().getConfiguration().addNested("datasources.default.url", "jdbc:mydb://localhost/mydb");
    }
}
```

--------------------------------

### ModuleContext: Manage Dependencies, Templates, and Configuration

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

ModuleContext is used to accumulate project artifacts per module. Add dependencies, templates, build plugins, and configure application settings.

```java
import io.micronaut.projectgen.core.generator.ModuleContext;
import io.micronaut.projectgen.core.buildtools.dependencies.Dependency;
import io.micronaut.projectgen.core.buildtools.BuildPlugin;
import io.micronaut.projectgen.core.template.StringTemplate;
import io.micronaut.context.env.Environment;

ModuleContext module = ctx.getRootModule();

// --- Dependencies ---
module.addDependency(
    Dependency.builder()
        .groupId("io.micronaut")
        .artifactId("micronaut-http-server-netty")
        .compile()
        .build()
);
module.addDependency(
    Dependency.builder()
        .lookupArtifactId("micronaut-test-junit5")  // resolved from BOM
        .test()
        .build()
);

// --- Templates ---
module.addTemplate("readme", new StringTemplate("README.md", "# My Project\n"));
module.addHelpLink("Micronaut Docs", "https://docs.micronaut.io");

// --- Configuration (application.yml / properties) ---
module.getConfiguration().addNested("micronaut.application.name", "my-app");
module.devConfiguration().addNested("micronaut.server.port", 8080);
module.testConfiguration().addNested("micronaut.environments", "test");

// --- Environment-specific config ---
module.getConfigurationByEnvironment(Environment.DEVELOPMENT)
     .addNested("datasources.default.url", "jdbc:h2:mem:devDb");

// --- Build plugins ---
// module.addBuildPlugin(GradlePlugin.builder().id("com.google.cloud.tools.jib").build());

// --- Dependency lookup by recipe (OpenRewrite integration) ---
module.addDependenciesByRecipeName(options, "io.micronaut.starter.add-http-client");
module.addConfigurationByRecipeName("io.micronaut.starter.add-http-client");

```

--------------------------------

### Features Endpoint

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Retrieves a list of available features for a given set of project options. Useful for populating UI feature selectors.

```APIDOC
## POST /api/v1/features

### Description
Returns a JSON list of features available for the given options payload. Useful for populating a UI feature selector.

### Method
POST

### Endpoint
/api/v1/features

### Parameters
#### Request Body
- **lang** (string) - Required - The programming language (e.g., `java`, `kotlin`).
- **build** (string) - Required - The build tool (e.g., `gradle`, `maven`).
- **java** (string) - Optional - The Java version (e.g., `21`).

### Request Example
```bash
curl -X POST http://localhost:8080/api/v1/features \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "lang=java&build=gradle&java=21" | jq .
```

### Response
#### Success Response (200)
- **features** (array) - A list of available features.
  - **name** (string) - The internal name of the feature.
  - **title** (string) - The display name of the feature.
  - **description** (string) - A description of the feature.
  - **preview** (boolean) - Indicates if the feature is in preview.
  - **community** (boolean) - Indicates if the feature is community-contributed.

### Response Example
```json
{
  "features": [
    {
      "name": "graalvm",
      "title": "GraalVM Native Image",
      "description": "Support for compiling Micronaut applications to native images using GraalVM.",
      "preview": false,
      "community": false
    },
    {
      "name": "http-server",
      "title": "Micronaut HTTP Server",
      "description": "Adds Netty-based HTTP server support.",
      "preview": false,
      "community": false
    }
  ]
}
```
```

--------------------------------

### GeneratorContext: Inspect Project and Features

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Use GeneratorContext to access project metadata, environment details, and feature information. It allows resolving coordinates and checking feature presence.

```java
import io.micronaut.projectgen.core.generator.GeneratorContext;
import io.micronaut.projectgen.core.feature.Feature;

// Inside Feature.apply(GeneratorContext ctx):
@Override
public void apply(GeneratorContext ctx) {
    // Inspect options and environment
    ctx.getLanguage();          // Language enum
    ctx.getJdkVersion();        // JdkVersion
    ctx.getTestFramework();     // TestFramework enum
    ctx.getBuildTool();         // BuildTool (primary)

    // Feature detection
    boolean hasGraal = ctx.isFeaturePresent(GraalVMFeature.class);
    ctx.getFeature(SomeFeature.class).ifPresent(f -> { /* ... */ });

    // Resolve a coordinate from the BOM catalog
    var coord = ctx.resolveCoordinate("micronaut-http");

    // Check source path using current language
    String path = ctx.getSourcePath("/com/example/MyApp");

    // Work on the root module
    var module = ctx.getRootModule();
    module.addDependency(...);
    module.getConfiguration().addNested("micronaut.application.name", ctx.getProject().getName());

    // Work on a named sub-module (multi-module projects)
    var api = ctx.getModuleByName("api");
    api.addTemplate("readme", new StringTemplate("README.md", "# API Module"));
}
```

--------------------------------

### Download ZIP File

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/src/main/docs/guide/modules/httpServer/downloadZip.adoc

This endpoint allows you to download a ZIP file using a POST request with `application/x-www-form-urlencoded` content type.

```APIDOC
## POST /download/zip

### Description
Allows downloading a ZIP file.

### Method
POST

### Endpoint
/download/zip

### Parameters
#### Request Body
- **contentType** (string) - Required - The content type for the request, expected to be `application/x-www-form-urlencoded`.
- **fileName** (string) - Required - The name of the file to be downloaded as a ZIP.

### Request Example
```
POST /download/zip HTTP/1.1
Host: localhost:8080
Content-Type: application/x-www-form-urlencoded

fileName=my-archive.zip
```

### Response
#### Success Response (200)
- **file** (byte[]) - The content of the ZIP file.
```

--------------------------------

### Add Feature to Existing Project

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/test-suite-helloworld-cli/README.md

Add a new feature to an existing project generated by the CLI. This command will run OpenRewrite recipes to modify the project.

```bash
java -jar test-suite-helloworld-cli/build/libs/test-suite-helloworld-cli-0.1-all.jar add --project demo
```

--------------------------------

### Create Generator Context with ContextFactory

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Utilize `ContextFactory` to create `GeneratorContext` and `FeatureContext` objects. It resolves available features, applies defaults, validates constraints, and allows manual feature application.

```java
import io.micronaut.projectgen.core.generator.*;
import io.micronaut.projectgen.core.feature.*;
import io.micronaut.projectgen.core.options.*;
import jakarta.inject.Inject;
import java.util.List;

@Singleton
public class CustomGenerationService {

    @Inject ContextFactory contextFactory;
    @Inject List<AvailableFeatures> availableFeaturesList;

    public GeneratorContext buildContext(Options options) {
        // Resolves available features, applies defaults, validates constraints
        GeneratorContext ctx = contextFactory.createGeneratorContext(
            availableFeaturesList,
            options,
            warning -> System.err.println("[WARN] " + warning)
        );

        // Inspect the final resolved feature set
        ctx.getFeatures().getFeatures().forEach(f ->
            System.out.println("Feature: " + f.getName())
        );

        // Manually apply features and inspect module output
        ctx.applyFeatures();
        System.out.println("Dependencies: " + ctx.getRootModule().getDependencies().size());
        return ctx;
    }
}
```

--------------------------------

### Download ZIP Endpoint

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Generates and downloads a Micronaut project as a ZIP file. Accepts form-urlencoded data for project configuration.

```APIDOC
## POST /api/v1/download/zip

### Description
Accepts a `application/x-www-form-urlencoded` body and returns the generated project as a ZIP file attachment.

### Method
POST

### Endpoint
/api/v1/download/zip

### Parameters
#### Request Body
- **name** (string) - Required - The name of the project.
- **lang** (string) - Required - The programming language (e.g., `java`, `kotlin`).
- **build** (string) - Required - The build tool (e.g., `gradle`, `maven`).
- **gradleDsl** (string) - Optional - The Gradle DSL to use (e.g., `kotlin`, `groovy`).
- **java** (string) - Optional - The Java version (e.g., `21`).
- **testFramework** (string) - Optional - The test framework (e.g., `kotest`).
- **features** (string) - Optional - A comma-separated list of features to include (e.g., `graalvm,http-server`).
- **packageName** (string) - Optional - The package name for the project.

### Request Example
```bash
curl -X POST http://localhost:8080/api/v1/download/zip \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "name=my-app&lang=kotlin&build=gradle&gradleDsl=KOTLIN&java=21&testFramework=kotest&features=graalvm,http-server&packageName=com.example" \
  -o my-app.zip
```

### Response
- **Success Response (200)**: Returns a ZIP file attachment containing the generated project.
```

--------------------------------

### FeatureContext: Add, Exclude, and Check Features

Source: https://context7.com/micronaut-projects/micronaut-projectgen/llms.txt

Use FeatureContext to manage the list of features during selection. Add or exclude features based on conditions, and inspect existing features.

```java
import io.micronaut.projectgen.core.feature.*;

// Inside Feature.processSelectedFeatures(FeatureContext ctx):
@Override
public void processSelectedFeatures(FeatureContext ctx) {
    // Add a companion feature if not already present
    ctx.addFeatureIfNotPresent(SomeOtherFeature.class, new SomeOtherFeature());

    // Exclude an incompatible feature
    ctx.exclude(feature -> feature instanceof IncompatibleFeature);

    // Check presence before acting
    if (ctx.isPresent(SecurityFeature.class)) {
        ctx.addFeature(new OAuthFeature());
    }

    // Inspect current options
    Language lang = ctx.getLanguage();      // e.g. Language.JAVA
    TestFramework tf = ctx.getTestFramework(); // e.g. TestFramework.JUNIT
}
```

--------------------------------

### Add Gradle Application Plugin

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/src/main/docs/guide/demo/addGradlePlugins.adoc

This feature adds the Gradle Application Plugin to your project. It requires access to the ProjectGen API for build tool configuration.

```java
package io.micronaut.projectgen.demo;

import io.micronaut.projectgen.core.buildtools.gradle.GradlePlugin;
import io.micronaut.projectgen.core.buildtools.gradle.GradlePluginConfiguration;
import io.micronaut.projectgen.core.buildtools.gradle.GradlePluginConfiguration.PluginType;
import io.micronaut.projectgen.core.feature.Feature;

public class GradleApplicationPluginFeature implements Feature {

    @Override
    public void apply(FeatureContext context) {
        context.getBuildTools().getGradle().addPlugin(GradlePlugin.builder()
                .id("application")
                .configuration(GradlePluginConfiguration.builder()
                        .type(PluginType.CORE)
                        .build())
                .build());
    }
}
```

--------------------------------

### Add JUnit Jupiter Dependency

Source: https://github.com/micronaut-projects/micronaut-projectgen/blob/0.0.x/src/main/docs/guide/demo/addDependency.adoc

Use the Dependency API to add the JUnit Jupiter dependency to your project. This is typically done when configuring build tools.

```java
package io.micronaut.projectgen.demo;

import io.micronaut.projectgen.core.buildtools.dependencies.Dependency;
import io.micronaut.projectgen.core.buildtools.dependencies.DependencyScope;
import io.micronaut.projectgen.core.buildtools.dependencies.DependencyType;

public class JunitJupiter {

    public static Dependency junitJupiter() {
        return Dependency.builder()
                .groupId("org.junit.jupiter")
                .artifactId("junit-jupiter-api")
                .scope(DependencyScope.TEST)
                .type(DependencyType.ANNOTATION_PROCESSOR)
                .build();
    }
}
```