docs: introduce initial docs page

build.gradle.kts

@@ -4,11 +4,14 @@ plugins {
     id("com.gradleup.shadow") version "8.3.6"
     id("io.micronaut.openapi") version "4.5.3"
     id("org.graalvm.buildtools.native") version "0.10.6"
+    id("org.asciidoctor.jvm.convert") version "3.3.2"
 }
 
 version = project.properties["justserveCliVersion"]!!
 group = "org.justserve"
 
+apply(from="gradle/asciidoc.gradle")
+
 repositories {
     mavenCentral()
 }
@@ -30,13 +33,16 @@ dependencies {
 application {
     mainClass = "org.justserve.FulcrumCommand"
 }
+
 java {
     sourceCompatibility = JavaVersion.toVersion("21")
     targetCompatibility = JavaVersion.toVersion("21")
 }
-
-
-
+tasks.withType<Test>().configureEach {
+    // This makes the project version available as a system property to the test JVM.
+    // Micronaut can then read and inject it using @Value.
+    systemProperty("justserveCliVersion", version)
+}
 micronaut {
     testRuntime("spock2")
     openapi {

gradle/asciidoc.gradle

@@ -0,0 +1,22 @@
+asciidoctorj {
+    version '2.1.0'
+    modules {
+        diagram {
+            version '1.5.18'
+        }
+    }
+
+    options doctype: "book", ruby: "erubis"
+
+    attributes "sourcedir": "src/docs/asciidoc",
+            "source-highlighter": "coderay",
+            "toc": "left",
+            "idprefix": "",
+            "idseparator": "-",
+            "icons": "font",
+            "setanchors": "",
+            "listing-caption": "",
+            "imagesdir": "images",
+            "project-version": "$project.version",
+            "revnumber": "$project.version"
+}

src/docs/asciidoc/index.adoc

@@ -0,0 +1,84 @@
+= JustServe CLI User Guide
+:toc: left
+:toclevels: 2
+:sectnums:
+
+An administrative command-line tool for JustServe Specialists and administrators.
+
+== Prerequisites
+
+Before using the CLI, you must authenticate your session.
+
+. Set the `MICRONAUT_HTTP_SERVICES_JUSTSERVE_TOKEN` environment variable with a valid API token obtained from the JustServe platform.
++
+[source,powershell]
+----
+# For PowerShell (Windows)
+$env:MICRONAUT_HTTP_SERVICES_JUSTSERVE_TOKEN = "your_api_token_here"
+----
++
+[source,bash]
+----
+# For Bash (Linux/macOS)
+export MICRONAUT_HTTP_SERVICES_JUSTSERVE_TOKEN="your_api_token_here"
+----
++
+[NOTE]
+====
+This token is used to authorize your requests to the JustServe API. Ensure it has the necessary permissions for the operations you intend to perform.
+====
+
+== Usage
+
+The primary command is `justserve`. You can run it from your terminal once you have the executable file.
+
+=== Generating a Temporary Password
+
+The main function of this tool is to generate a new temporary password for a user, which is useful for resolving account access issues.
+
+To generate a password, use the `--email` or `-e` option, followed by the user's email address.
+
+.Command Syntax
+[source,bash]
+----
+./justserve --email <user_email>
+----
+
+.Example Request
+[source,bash]
+----
+./justserve --email user@example.com
+----
+
+If the request is successful, the tool will print the new temporary password directly to the console.
+
+.Example Success Output
+----
+t3mpP@ssw0rd!
+----
+
+=== Checking the Tool Version
+
+To display the current version of the `justserve-cli` tool, use the `--version` or `-v` flag. This is helpful for ensuring you are using the latest release.
+
+.Command Syntax
+[source,bash]
+----
+./justserve --version
+----
+
+.Example Output
+[source,text]
+----
+0.0.3-SNAPSHOT
+----
+
+== Error Handling
+
+If the tool encounters an issue—such as an invalid email, an authentication failure, or a server-side problem—it will print a descriptive error message to the standard error stream.
+
+.Example Error Output
+[source,text]
+----
+received an unexpected response from JustServe: 404 (Not Found)
+----

src/test/groovy/org/justserve/FulcrumCommandSpec.groovy

@@ -3,43 +3,66 @@ package org.justserve
 import io.micronaut.configuration.picocli.PicocliRunner
 import io.micronaut.context.ApplicationContext
 import io.micronaut.context.env.Environment
+import io.micronaut.test.extensions.spock.annotation.MicronautTest
 import spock.lang.Shared
 import spock.lang.Specification
+import spock.lang.Unroll
 
 import java.util.regex.Pattern
 
+@MicronautTest
 class FulcrumCommandSpec extends Specification {
 
     @Shared
-    Pattern versionRegex = Pattern.compile "^(\\d\\.){2}\\d\\s{1,2}\$"
+    String cliVersion
 
     @Shared
     Pattern blankRegex = Pattern.compile "^\\s*\$"
 
     @Shared
     Pattern errorRegex = Pattern.compile "^received an unexpected response from JustServe: \\d+ \\(.*\\)\\s*\$"
 
-    void "smoke test with command line options"() {
+    def setupSpec() {
+        def props = new Properties()
+        // Assumes tests are run from the project's root directory
+        new File('gradle.properties').withInputStream { stream ->
+            props.load(stream)
+        }
+        cliVersion = props.getProperty('justserveCliVersion')
+    }
+
+    @Unroll("command with args: #args prints version")
+    def "version command should print the correct version"() {
         when:
         def (outputStream, errorStream) = executeCommand(args)
 
         then:
-        outputStream.toString().matches(expectedOutputValue)
+        // The version command typically prints a newline, so we trim the output
+        outputStream.toString().trim() == cliVersion
+        errorStream.toString().matches(blankRegex)
+
+        where:
+        args                      | _
+        new String[]{"-v"}        | _
+        new String[]{"--version"} | _
+        new String[]{"version"}   | _
+
+    }
 
-        and:
+    @Unroll("command with args: #args produces expected output")
+    def "email option should produce expected output"() {
+        when:
+        def (outputStream, errorStream) = executeCommand(args)
+
+        then:
+        outputStream.toString().matches(expectedOutputValue)
         errorStream.toString().matches(expectedErrorOutput)
 
         where:
-        args                                           | expectedOutputValue                | expectedErrorOutput | _
-        new String[]{'-e', 'jimmy@justserve.org'}      | Pattern.compile("^\\w+\\s{1,2}\$") | blankRegex          | _
-        new String[]{'--email', 'jimmy@justserve.org'} | Pattern.compile("^\\w+\\s{1,2}\$") | blankRegex          | _
-        new String[]{'-v'}                             | versionRegex                       | blankRegex          | _
-        new String[]{"--version"}                      | versionRegex                       | blankRegex          | _
-        new String[]{"version"}                        | versionRegex                       | blankRegex          | _
-        new String[]{"-v"}                             | versionRegex                       | blankRegex          | _
-        //failures
-        new String[]{'-e', 'notanemail@mail.moc'}      | blankRegex                         | errorRegex          | _
-
+        args                                           | expectedOutputValue | expectedErrorOutput | _
+        new String[]{'-e', 'jimmy@justserve.org'}      | ~/^\w+\s*$/         | blankRegex          | _
+        new String[]{'--email', 'jimmy@justserve.org'} | ~/^\w+\s*$/         | blankRegex          | _
+        new String[]{'-e', 'notanemail@mail.moc'}      | blankRegex          | errorRegex          | _
     }
 
     /**
@@ -62,4 +85,3 @@ class FulcrumCommandSpec extends Specification {
         return new String[]{out, err}
     }
 }
-