feat(app generator): add means to learn the current build's briefing …

…details

generators/app/index.js

@@ -395,6 +395,7 @@ var AppGenerator = generators.Base.extend(
 
                     ,   [ 'src/collections/api-services.coffee' ]
                     ,   'src/models/api-service.coffee'
+                    ,   'src/models/build-brief.coffee'
                     ,   [ 'src/models/settings-environment.coffee' ]
 
                         //  Style and Compass:
@@ -477,6 +478,7 @@ var AppGenerator = generators.Base.extend(
                     ,   'backbone.cocktail'
                     ,   ( 'jquery' + ( data.ie8 ? '@<2' : '' ))
                     ,   'madlib-settings'
+                    ,   'moment'
                     ,   'q'
                     ,   'underscore'
                     ]

generators/app/templates/src/collections/api-services.coffee

@@ -71,6 +71,32 @@
         new ApiServicesCollection(
 
             [
+                ###*
+                #   Absolute url path for retrieving the app's current build's {{#crossLink "BuildBrief"}}briefing data{{/crossLink}}.
+                #
+                #   This data includes:
+                #
+                #     * `buildNumber`
+                #     * `buildId`
+                #     * `revision`
+                #     * `grunted`
+                #     * `environment`
+                #     * `debugging`
+                #     * `name`
+                #     * `version`
+                #     * `timestamp`
+                #
+                #   @property       services.buildBrief
+                #   @type           String
+                #   @final
+                #
+                #   @default        '<app-base-url>/build.json'
+                ###
+
+                id:     'buildBrief'
+                url:    "#{appBaseUrl}build.json"
+
+            ,
                 ###*
                 #   Absolute url path for retrieving the app's {{#crossLink "SettingsEnvironment"}}target-environment settings{{/crossLink}}.
                 #

generators/app/templates/src/models/build-brief.coffee

@@ -0,0 +1,220 @@
+( ( factory ) ->
+    if typeof exports is 'object'
+        module.exports = factory(
+            require( 'backbone' )
+            require( 'madlib-settings' )
+            require( 'moment' )
+            require( 'q' )
+        )
+    else if typeof define is 'function' and define.amd
+        define( [
+            'backbone'
+            'madlib-settings'
+            'moment'
+            'q'
+        ], factory )
+    return
+)((
+    Backbone
+    settings
+    moment
+    Q
+) ->
+
+    ###*
+    #   @author         David Bouman
+    #   @module         App
+    #   @submodule      Models
+    ###
+
+    'use strict'
+
+
+    ##  Stamped logs
+    ##
+    log = ( args... ) -> console.log( '[BUILDINFO]', args... )
+
+
+    ###*
+    #   The current build's briefing information.
+    #
+    #   @class          BuildBrief
+    #   @extends        Backbone.Model
+    #   @static
+    ###
+
+    class BuildBriefModel extends Backbone.Model
+
+        ###*
+        #   List of [valid attribute names](#attrs).
+        #
+        #   @property       schema
+        #   @type           Array[String]
+        #   @static
+        #   @final
+        ###
+
+        ###*
+        #   The value of the `BUILD_NUMBER` environment variable at the time of build.
+        #   Expected to be provided from the ci/cd build job.
+        #   Expected to be a count of the number of these build jobs triggered so far.
+        #
+        #   If `BUILD_NUMBER` has not been set, this will instead be the number of builds triggered from a watched `grunt dev` run since invocation.
+        #
+        #   @attribute      buildNumber
+        #   @type           String
+        ###
+
+        ###*
+        #   The value of the `BUILD_ID` environment variable at the time of build.
+        #   Expected to be provided from the ci/cd build job.
+        #   Expected to be reference-id of the build job meaningful to your ci/cd.
+        #
+        #   @attribute      buildId
+        #   @type           String
+        ###
+
+        ###*
+        #   The value of the `GIT_COMMIT` environment variable at the time of build.
+        #   Expected to be provided from the ci/cd build job.
+        #   Expected to be the git commit hash that the ci/cd build job checked out.
+        #
+        #   If `GIT_COMMIT` has not been set, this will be the string `working dir` instead.
+        #
+        #   @attribute      revision
+        #   @type           String
+        ###
+
+        ###*
+        #   Human readable timestamp of when this build brief was generated. Indicative of when the build was run/completed.
+        #
+        #   @attribute      grunted
+        #   @type           String
+        ###
+
+        ###*
+        #   The build's target-environment's name.
+        #
+        #   Typically:
+        #       * `production`
+        #       * `acceptance`
+        #       * `testing`
+        #       * `local`
+        #
+        #   @attribute      environment
+        #   @type           String
+        ###
+
+        ###*
+        #   Flag for signalling wether this was debugging build.
+        #
+        #   @attribute      debugging
+        #   @type           Boolean
+        ###
+
+        ###*
+        #   The app's name as listed in its `package.json`.
+        #
+        #   @attribute      name
+        #   @type           String
+        ###
+
+        ###*
+        #   The app's version as listed in its `package.json`.
+        #
+        #   See also: http://semver.org/
+        #
+        #   @attribute      version
+        #   @type           Semver
+        ###
+
+        ###*
+        #   Unix timestamp of the build's run; equal to `grunted`
+        #
+        #   @attribute      timestamp
+        #   @type           Number
+        ###
+
+        schema: [
+
+            'buildNumber'
+            'buildId'
+            'revision'
+            'grunted'
+            'environment'
+            'debugging'
+            'name'
+            'version'
+            'timestamp'
+        ]
+
+
+        ###*
+        #   @property       url
+        #   @type           String
+        #   @static
+        #   @final
+        #
+        #   @default        'build.json'
+        ###
+
+        url:                settings.get( 'services.buildBrief' )
+
+
+        ###*
+        #   @method         initialize
+        #   @protected
+        ###
+
+        initialize: () ->
+
+            ###*
+            #   A `Promise` that the build's briefing data will have been loaded.
+            #
+            #   @property       initialized
+            #   @type           Promise
+            #   @final
+            ###
+
+            @initialized =
+                new Q( @fetch( cache: false ) ).then(
+
+                    ( attributes ) =>
+
+                        ### jshint unused:  false ###
+
+                        return @
+
+
+                    ( jqXHR ) ->
+
+                        ### jshint unused:  false ###
+
+                        message = 'Unable to load build briefing information.'
+
+                        log( message )
+
+                        throw new Error( message )
+                )
+
+            return
+
+
+        ###*
+        #   @method         parse
+        #   @protected
+        ###
+
+        parse: ( data ) ->
+
+            key         = 'timestamp'
+            data[ key ] = moment( data[ key ] )
+
+            return data
+
+
+    ##  Export singleton.
+    ##
+    return new BuildBriefModel()
+
+)