@viewdo/dxp-story-cli/README.md

README.md

# DXP Story CLI

## Installation
The DXP Story CLI uses *Node 8+* and is installed using NPM. It works best when installed globally.

    $ npm i -g @viewdo/dxp-story-cli

## Getting Started
The first thing the tool needs to do is initialize a workspace on the filesystem. 

To manage a single, existing story:
  
    $ storyctl init <story-key> -e <your email>

or, to manage an existing organization

    $ storyctl init -k <org-key> -e <email>

or, if this is a new story and org:

    $ storyctl init -e <email>

Like NPM, the init function will prompt the developer about basic settings and hold them in three small files at the root of the workspace:

* [dxp-config.json](####Config)
* [.auth](###Auth)
* [.env](####ENV)

#### Config
The Story CLI requires a **dxp-config.json** file to exist. This file defines how the assets are named in the repository.

#### Auth
The **.auth** file holds your token and email address. This file should NEVER be added to Git and should only live in your own file-system.

#### ENV
The **.env** file, holds environment variables. The CLI tool expects a 'NAMESPACE' environment variable to tell it which platform instance to use.


### Authenticate
We need to make sure this tool can only be used by authorized StoryAdmins (w/AssetManagement grant in production). This means we need to authenticate the user or server for a token with permission to update the assets.

    $ dxp-story login


## Usage & Global Options

Usage: 

    $ dxp-story [options] [command]

Options:

    -V, --version                               output the version number
    -h, --help                                  output usage information

## Commands:
|command |Description |
|---|---|
|[init](##INIT)        | Set up the namespace variables for a working output |
|[login](##LOGIN)        | Authenticate to the output using email verification code |
|[scaffold](##SCAFFOLD)     | Create all the asset files and folders for brand new story |
|[pull](##PULL)         | Pull down all the assets for a given set of organization keys |
|[push](##PUSH)         | Pushes all the associated assets to a given story |
|[check](##CHECK)        | Checks to see what files are different on disc from the platform |
|[validate](##VALIDATE)     | Validate tokens in local files using the configured story |
|[json-yaml]    | Convert JSON to YAML |
|[yaml-json]    | Convert YAML to JSON 
|[strip-html]   | Strip HTML from JSON to "./json-html/**.html" |
|[restore-html] | Return HTML to JSON from "./json-html/**.html" files |
|[help] | Get help on all these commands |

## INIT
Set up the required configuration files for using the CLI within a folder. 

Usage: 

  $ dxp-story init|i [options] [keys...]

Options:

    -v, --verbose         Verbose logging.
    -n, --namespace <ns>  Namespace to use against [local|dev|stage]
    -e, --email <email>   Email address of the current user
    -o, --output <dir>    Folder for bundled story files, used to sync with the platform
    -h, --help            output usage information

### Namespace
The namespace determines which DXP environment endpoints to use.
* local
* develop
* \<dynamic\>
* default *

\* Production (default) is only available in the *non-interactive* authentication mode. The tool will allow you to push straight from the workstation to the platform in local, dev and stage, but production MUST go through a build-deployment from TeamCity. This way, we can be nimble in staging namespaces and once the story looks good, a check in (after pull-request) is needed to get the assets up to the platform.


## LOGIN  

Usage: 

    $ login|a [options] [email] [keys...]

Options:

    -v, --verbose         Verbose logging.
    -n, --namespace <ns>  Namespace to use against [local|dev|stage]
    -E, --email <email>   Your email address (for authentication)
    -t, --token <token>   An existing token to write to the output
    -f, --force           Force new authentication
    -h, --help            output usage information

### Mode: Interactive
By default, this tool requires user credentials with permission to update the story assets. Login will prompt the user into the login-flow below, using the passwordless-email option in Auth0. No passwords will ever be transmitted or collected. However, the tokens should be saved in a location that allows the token to be reused if the command is run again.

    $ dxp-story login

### Mode: Application
If we initialize Auth0 as Machine-to-Machine application and provide environment variables for the ClientID and ClientSecret for the client, this tool can authenticate as itself from the build-server with the special permissions needed to push assets to production.

*Namespace Variables:*
* AUTH0_CLIENT_ID
* AUTH0_CLIENT_SECRET
* NAMESPACE=default

## PULL : Download Existing Story Assets
The quickest way to get set up on an existing story is to pull all assets for a story using this command. It assumes the convention configuration mode and downloads the assets according to the file structure above.

    $ dxp-story pull|p [options] [keys...]

    Pull down all the associated assets for a given story

  Options:

    -v, --verbose              Debug output.
    -n, --namespace [env]  Namespace to use against [local|dev|stage] (default: dev)
    -p, --path <path>        Output for this project (if not the root where the command is execute from)
    -k, --key <key>          Story key to pull assets from
    -x, --explicit           Write all file locations in the dxp-config.json file.
    -a, --all                Pull all stories without prompting
    -h, --help               output usage information
    -i, --client_id <id>     Auth0 Client ID
    -s, --client_secret <id> Auth0 Client Secret

## SCAFFOLD : New Story Assets
If this is a brand new repository for a new story. You can scaffold the folder structure along with empty files to get you started.

    $ dxp-story scaffold|s [options] [keys...]

    Scaffolds out the root output for story assets

  Options:

    -v, --verbose              Debug output.
    -n, --namespace [env]  Namespace to use against [local|dev|stage] (default: dev)
    -p, --path <path>        Output for this project (if not the root where the command is execute from)
    -k, --key <key>          Scaffold using this story key
    -x, --explicit           Write all file locations in the dxp-config.json file.
    -h, --help               Output usage information

## CHECK : Compare Story Assets on disc to the Story on the iVX Platform
The check command will compare the contents of the assets on the platform with the contents of the files on disc. This gives the user a quick way of seeing the impact a push might have.

    $ dxp-story check|c [options] [keys...]

    Checks to see what files are different on disc from the platform

  Options:

    -v, --verbose              Debug output.
    -n, --namespace [env]  Namespace to use against [local|dev|stage] (default: dev)
    -p, --path <path>        Output for this project (if not the root where the command is execute from)
    -k, --key <key>          Story key to push (default: null)
    -a, --all                Push all stories without prompting
    -i, --client_id <id>     Auth0 Client ID
    -s, --client_secret <id> Auth0 Client Secret

## VALIDATE : Validate tokens in local asset files
The validate command will validate the contents of the assets on the platform to ensure all tokens are valid.

    $ dxp-story validate|v [options] [keys...]

    Checks to see what files are different on disc from the platform

  Options:

    -v, --verbose              Debug output.
    -n, --namespace [env]  Namespace to use against [local|dev|stage] (default: dev)
    -p, --path <path>        Output for this project (if not the root where the command is execute from)
    -k, --key <key>          Story key to push (default: null)
    -a, --all                Push all stories without prompting
    -i, --client_id <id>     Auth0 Client ID
    -s, --client_secret <id> Auth0 Client Secret

## PUSH : Upload Story Assets to the Story on the iVX Platform
The deployment command executes differently depending on the authenticating mode. For interactive clients, if not yet logged in, you are prompted first. Then the *plan* command is executed first with a prompt to continue. Then the *validate* command is executed. If no errors exist, the user is prompted to push.

    $ dxp-story push|u [options] [keys...]

    Pushes all the associated assets to a given story

  Options:

    -v, --verbose              Debug output.
    -n, --namespace [env]  Namespace to use against [local|dev|stage] (default: dev)
    -p, --path <path>        Output for this project (if not the root where the command is execute from)
    -k, --key <key>          Story key to push (default: null)
    -a, --all                Push all stories without prompting
    -i, --client_id <id>     Auth0 Client ID
    -s, --client_secret <id> Auth0 Client Secret

## Configuration

## Folder & File Conventions
This application works best when the folder and file conventions are used. This method reduces the amount of configuration necessary for deployments. The following illustrates the convention for a given story.

#### Story Folder:

    [root]
    dxp-config.json
    📁<story-key>
      /story.json
      /story.js
      /story.css
      /story-intro.html
      📁html-templates
        /<file-key>.html
      📁text-templates
        /<file-key>.txt|json|js|css|less|csv|xml
      📁email-templates
        /<email-key>.cshtml
      📁episodes
        📁<episode-key>
          /story.json
          /story.css
          /story.js

### Simple Configuration : /dxp-config.json
    {
      "output": "./", // optional
      "stories": {      // not optional
        "testing": {
          "name": "Sample Story"
        }
      }
    }

### Explicit Configuration : /dxp-config.json
    {
      "output": "/src/stories",
      "stories": {
          "testing": {
            "name": "Sample Story",
            "intro_html_file": "/testing/story-intro.html",
            "js_file": "/testing/story.json",
            "json_file": "/testing/story.js",
            "css_file": "/testing/story.css",
            "episodes": {
                "test-episode": {
                    "json_file": "/testing/episodes/test-episode/story.json",
                    "css_file": "/testing/episodes/test-episode/story.css",
                    "js_file": "/testing/episodes/test-episode/story.js",
                }
            },
            "email_templates": {
                "example": "/testing/email-templates/example.cshtml"
            },
            "html_templates": {
                "example": "/testing/html-templates/example.html"
            },
            "text_templates": {
                "example": "/testing/text-templates/example.js"
            }
          }
        }
    }

----

## Unpack: Unpacks iVXjs Config/Story Files into settings files in the source
Due to some Story Player Stories using the iVXjs library being rather large and complex, this command breaks apart these large JSON files into smaller settings js files that can be built/pack using 
DXP Story CLI's command. 

    $ dxp-story unpack|un [options] [keys...]

    Unpacks story json files in the output folder into settings js files in the source to be used with the build command.

  Options:

    -v, --verbose         Debug output.
    -p, --path <path>   Output for this project (if not the root where the command is execute from)
    -k, --key <key>     Unpack only this story key
    -a, --all           Unpacks all stories without prompting
    -o, --output <dir>  Which output holds the unpack story
    -s, --source <dir>  Folder for source files to unpack the stories
    -h, --help          output usage information

## Validate : Check files against story configuration
This is another important part of all interactive deployments. It gives the user a chance to validate all file contents within the configuration, whether it was by convention or declaration. This command shows server validation for each file, including token errors.

    $ dxp-story validate|v [options] [keys...]

# FUTURE

## Build : Build from Source
## Watch : Build and Watch Source Files
## Preview : Preview w/Story Player
## Forge : Use Story Forge

## Sync : Synchronize All Assets
This command will use the local-configuration as the source of truth, creating any assets missing on the platform as well as removing any not found locally on disc.

    $ dxp-story sync|s [options] [keys...]