Merge branch 'master' of github.com:commandbox-modules/commandbox-tem…

…plate

.github/workflows/ci.yml

@@ -35,7 +35,7 @@ jobs:
           java-version: "11"
 
       - name: Setup CommandBox
-        uses: elpete/[email protected]
+        uses: Ortus-Solutions/[email protected]
         with:
           forgeboxAPIKey: ${{ secrets.FORGEBOX_API_TOKEN }}
 
@@ -61,9 +61,8 @@ jobs:
         run: |
           # Create the CommandBox modules folder, for some reason it is not created
           mkdir -p ~/.CommandBox/cfml/modules
-          # Link up the module so we can do testing!
           box link --force
-          # Build Project
+          # Build Project with Tests Included
           box task run taskfile=build/Build :version=${{ env.VERSION }} :projectName=${{ env.MODULE_ID }} :buildID=${{ github.run_number }} :branch=${{ env.BRANCH }}
 
       - name: Failure Logs

.gitignore

@@ -1,7 +1,8 @@
 # Dependencies
 /docbox/**
+modules/**
 
 # Build Artifacts
 .tmp/**
 .artifacts/**
-changelog-latest.md
+changelog-latest.md

ModuleConfig.cfc

@@ -5,22 +5,21 @@
  */
 component {
 
-	this.cfmapping = "@module_slug@";
+	this.cfmapping      = "@module_slug@";
 	this.modelNamespace = "@module_slug@";
 
-	function configure() {
-
-		settings = {
-		}
+	function configure(){
+		settings = {}
 
 		interceptors = []
 	}
 
 	function onLoad(){
-		//log.info('Module loaded successfully.' );
+		// log.info('Module loaded successfully.' );
 	}
 
 	function onUnLoad(){
-		//log.info('Module unloaded successfully.' );
+		// log.info('Module unloaded successfully.' );
 	}
+
 }

README.md

@@ -1,36 +1,13 @@
 # Ortus CommandBox Module Template
 
-This template can be used to create Ortus based ColdBox Modules.  To configure the template for your module, just clone this repository and discard the `.git` folder.  Create your own repository with your own `module slug` and init the repository as follows:
+This template can be used to create CommandBox Modules with automation, testing and much more.  To use, just click the `Use this Template` button in the github repository: https://github.com/commandbox-modules/commandbox-template and run the setup task from where you cloned it.
 
 ```bash
-mkdir myModule
-cd mymodule
-git clone [email protected]:commandbox-modules/commandbox-template.git
-rm -Rf .git
-git init
-box task run taskFile=build/setupTemplate
+box run-script setupTemplate
 ```
 
 The `setupTemplate` task will ask you for your module name, id and description and configure the template for you! Enjoy!
 
-## LICENSE
-
-Apache License, Version 2.0.
-
-## SYSTEM REQUIREMENTS
-
-- CommandBox 5.1+
-
-## Installation
-
-Install the commands via CommandBox like so:
-
-```bash
-box install @module_slug@
-```
-
-----
-
 # Module Template
 
 This is a CommandBox based module template.  Here are some of the tokens to replace to make it your own:
@@ -39,33 +16,48 @@ This is a CommandBox based module template.  Here are some of the tokens to repl
 - `@module_slug@` - The module slug identifier
 - `@module_description@` - Module short description
 
-## Layout
+## Directory Layout
 
 Here is a description of the layout of a CommandBox module:
 
 - `.github` - Github workflows
-- `build` - Hosts a `Build.cfc` task runner that builds, tests and documents your module. You will have to add your tests via the `runRTests()` method.
+- `build/Build.cfc` - Task that builds, tests and documents your module.
+- `build/Tests.cfc` - This is your test harness. Add all your commands to test inside the `run()` method
 - `commands` - The commands for you to implement.
-- `changelog.md` - Your changelog file
+- `.cfformat.json` - A CFFormat using the Ortus Standards
+- `.cflintrc` - A CFLint configuration file according to Ortus Standards
+- `.editorconfig` - Smooth consistency between editors
+- `.gitattributes` - Git attributes
+- `.gitignore` - Basic ignores. Modify as needed.
+- `.markdownlint.json` - A linting file for markdown docs
+- `box.json` - The box.json for YOUR module.  Modify as needed.
+- `changelog.md` - A nice semantic parselog changelog tracking file
+- `ModuleConfig.cfc` - Your module's configuration. Modify as needed.
+- `readme.md` - Your module's readme. Modify as needed.
+
+## Package Scripts
+
+Your module template comes with several useful package scripts:
+
+| Script       		| Description |
+|-------------------|-----------|
+| `build:docs` 		| Build the API docs using DocBox |
+| `build:module` 	| Build the module distribution with Docs and tests |
+| `runTests` 		| Run the test task: `build/Tests.cfc` |
+| `setupTemplate` 	| Setup the template when cloning |
+| `format:check` 	| Check the formmating of your code |
+| `format:watch` 	| Watch for changes and format your code automatically |
+| `format` 			| Format your code|
+| `release` 		| Runs the `build/release.boxr` recipe, which merges `development` into `master`, tags, auto bumps and pushes to your repo |
 
 ## Github Actions Automation
 
 The github actions will clone, test, package, deploy your module to ForgeBox and the Ortus S3 accounts for API Docs and Artifacts.  So please make sure the following environment variables are set in your repository. ** Please note that most of them are already defined at the org level **
 
-* `FORGEBOX_TOKEN` - The Ortus ForgeBox API Token
-* `AWS_ACCESS_KEY` - The travis user S3 account
-* `AWS_ACCESS_SECRET` - The travis secret S3
-
-> Please contact the admins in the `#infrastructure` channel for these credentials if needed
-
-
-----
-
-
-# CREDITS & CONTRIBUTIONS
-
-I THANK GOD FOR HIS WISDOM FOR THIS PROJECT
+- `FORGEBOX_TOKEN` - The Ortus ForgeBox API Token
+- `AWS_ACCESS_KEY` - The travis user S3 account
+- `AWS_ACCESS_SECRET` - The travis secret S3
 
-## THE DAILY BREAD
+## API Docs
 
-"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" Jn 14:1-12
+The build task will take care of building API Docs using DocBox for you but **ONLY** for the `commands` folder in your module.  If you want to document more then make sure you modify the `build/Build.cfc` task.

box.json

@@ -1,16 +1,16 @@
 {
-    "name":"@module_name@",
+    "name":"@MODULE_NAME@",
     "version":"1.0.0",
-    "location":"https://downloads.ortussolutions.com/ortussolutions/commandbox-modules/@module_slug@/@build.version@/@module_slug@[email protected]@.zip",
-    "slug":"@module_slug@",
+    "location":"https://downloads.ortussolutions.com/ortussolutions/commandbox-modules/@MODULE_SLUG@/@build.version@/@MODULE_SLUG@[email protected]@.zip",
+    "slug":"@MODULE_SLUG@",
     "author":"Ortus Solutions, Corp",
-    "homepage":"https://www.forgebox.io/view/@module_slug@",
+    "homepage":"https://www.forgebox.io/view/@MODULE_SLUG@",
     "documentation":"https://github.com/commandbox-modules/wiki",
     "repository":{
         "type":"git",
-        "url":"https://github.com/commandbox-modules/@module_slug@"
+        "url":"https://github.com/commandbox-modules/@MODULE_SLUG@"
     },
-    "bugs":"https://github.com/commandbox-modules/@module_slug@/issues",
+    "bugs":"https://github.com/commandbox-modules/@MODULE_SLUG@/issues",
     "shortDescription":"@module_description@",
     "type":"commandbox-modules",
     "keywords": [],
@@ -23,19 +23,26 @@
     "contributors":[
     ],
 	"devDependencies":{
+		"commandbox-cfformat":"*",
         "commandbox-docbox":"*"
     },
     "dependencies":{
     },
     "installPaths":{
     },
+	"ignore":[
+        "**/.*",
+        "test-harness",
+		"/server*.json"
+    ],
     "scripts":{
-		"setupTemplate": "task run taskFile=build/SetupTemplate.cfc",
 		"build:module":"task run taskFile=build/Build.cfc :projectName=`package show slug` :version=`package show version`",
 		"build:docs":"task run taskFile=build/Build.cfc target=docs :projectName=`package show slug` :version=`package show version`",
-        "release":"recipe build/release.boxr",
         "format":"cfformat run commands,build,ModuleConfig.cfc ./.cfformat.json --overwrite",
         "format:watch":"cfformat watch commands,build,ModuleConfig.cfc ./.cfformat.json",
-        "format:check":"cfformat check commands,build,ModuleConfig.cfc ./.cfformat.json"
+        "format:check":"cfformat check commands,build,ModuleConfig.cfc ./.cfformat.json",
+        "release":"recipe build/release.boxr",
+        "setupTemplate": "task run taskFile=build/SetupTemplate.cfc"
+
     }
 }

build/Build.cfc

@@ -14,6 +14,7 @@ component {
 		variables.buildDir     = cwd & "/.tmp";
 		variables.apiDocsURL   = "http://localhost:60299/apidocs/";
 		variables.testRunner   = "http://localhost:60299/tests/runner.cfm";
+		variables.exportsDir   = "";
 
 		// Source Excludes Not Added to final binary: You can use REGEX
 		variables.excludes = [
@@ -37,10 +38,7 @@ component {
 		} );
 
 		// Create Project Dependency Mappings
-		//fileSystemUtil.createMapping(
-		//	"contentbox-cli",
-		//	variables.cwd
-		//);
+		fileSystemUtil.createMapping( "@module_name@", variables.cwd );
 
 		return this;
 	}
@@ -79,7 +77,7 @@ component {
 		latestChangelog();
 
 		// Finalize Message
-		print
+		variables.print
 			.line()
 			.boldMagentaLine( "Build Process is done! Enjoy your build!" )
 			.toConsole();
@@ -89,12 +87,29 @@ component {
 	 * Run the test suites
 	 */
 	function runTests(){
+		variables.print
+			.line()
+			.boldGreenLine( "------------------------------------------------" )
+			.boldGreenLine( "Starting to execute your tests..." )
+			.boldGreenLine( "------------------------------------------------" )
+			.toConsole();
+
+		var sTime = getTickCount();
+
 		// Tests First, if they fail then exit
-		print.blueLine( "Testing the package, please wait..." ).toConsole();
+		// Run your tests via the `command()` options here.
+		command( "task run build/Tests.cfc" ).run();
 
 		// Check Exit Code?
 		if ( shell.getExitCode() ) {
 			return error( "X Cannot continue building, tests failed!" );
+		} else {
+			variables.print
+				.line()
+				.boldGreenLine( "------------------------------------------------" )
+				.boldGreenLine( "All tests passed in #getTickCount() - sTime#ms! Ready to go, great job!" )
+				.boldGreenLine( "------------------------------------------------" )
+				.toConsole();
 		}
 	}
 
@@ -113,7 +128,7 @@ component {
 		branch  = "development"
 	){
 		// Build Notice ID
-		print
+		variables.print
 			.line()
 			.boldMagentaLine(
 				"Building #arguments.projectName# v#arguments.version#+#arguments.buildID# from #cwd# using the #arguments.branch# branch."
@@ -193,11 +208,12 @@ component {
 		print.greenLine( "Generating API Docs, please wait..." ).toConsole();
 		directoryCreate( arguments.outputDir, true, true );
 
+		// Generate the docs
 		command( "docbox generate" )
 			.params(
 				"source"                = "commands",
-				"excludes"				= "",
-				"mapping"               = "contentbox-cli",
+				"excludes"              = "",
+				"mapping"               = "@module_name@",
 				"strategy-projectTitle" = "#arguments.projectName# v#arguments.version#",
 				"strategy-outputDir"    = arguments.outputDir
 			)
@@ -231,8 +247,8 @@ component {
 			fileRead( variables.cwd & "changelog.md" ).split( "----" )[ 2 ].trim() & chr( 13 ) & chr( 10 )
 		);
 
-		print
-			.greenLine( "Latest changelog file created at `changelog-latest.md`" )
+		variables.print
+			.greenBoldLine( "  √ Latest changelog file created at `changelog-latest.md`" )
 			.line()
 			.line( fileRead( variables.cwd & "changelog-latest.md" ) );
 	}

build/SetupTemplate.cfc

@@ -24,15 +24,15 @@ component {
 		//command( "!git init" ).run();
 
 		var moduleName = ask( "What is the human readable name of your module?" );
-		if( !len( moduleName ) ){
+		if ( !len( moduleName ) ) {
 			error( "Module Name is required" );
 		}
 		var moduleSlug = ask( "What is the slug for your module?" );
-		if( !len( moduleSlug ) ){
+		if ( !len( moduleSlug ) ) {
 			error( "Module Slug is required" );
 		}
 		var moduleDescription = ask( "Short description of your module?" );
-		if( !len( moduleDescription ) ){
+		if ( !len( moduleDescription ) ) {
 			error( "Module Description is required" );
 		}
 

build/Tests.cfc

@@ -0,0 +1,13 @@
+/**
+ * This task is used to execute all of your test suite.
+ * No need to do try/catch we will do that for you.  Just write all the commands, assertions you need.
+ */
+component{
+
+	/**
+	 * Run my test suites
+	 */
+	function run(){
+		command( "hello help" ).run( returnOutput : true );
+	}
+}

commands/Hello/help.cfc

@@ -0,0 +1,13 @@
+component excludeFromHelp=true {
+
+	function run(){
+		print.line();
+		print.yellow( "The " );
+		print.boldYellow( "@module_name@" );
+		print.yellowLine(
+			"Type help before any command name to get additional information on how to call that specific command."
+		);
+		print.line();
+	}
+
+}