diff --git a/build.gradle.kts b/build.gradle.kts index 9c43e45..4029a62 100644 --- a/build.gradle.kts +++ b/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().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 { diff --git a/gradle/asciidoc.gradle b/gradle/asciidoc.gradle new file mode 100644 index 0000000..fe171c7 --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/src/docs/asciidoc/index.adoc b/src/docs/asciidoc/index.adoc new file mode 100644 index 0000000..0582388 --- /dev/null +++ b/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 +---- + +.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) +---- \ No newline at end of file diff --git a/src/test/groovy/org/justserve/FulcrumCommandSpec.groovy b/src/test/groovy/org/justserve/FulcrumCommandSpec.groovy index 2bff562..1ae78af 100644 --- a/src/test/groovy/org/justserve/FulcrumCommandSpec.groovy +++ b/src/test/groovy/org/justserve/FulcrumCommandSpec.groovy @@ -3,15 +3,18 @@ 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*\$" @@ -19,27 +22,47 @@ class FulcrumCommandSpec extends Specification { @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} } } -