- 01 install Download all vendor assets
- 02 setup Copy, rename, and patch vendor files. Install commit hook.
- 06 dev\_start Configure and start an HTTP server
- 07 dev\_test Ran all unit test suites found in test.d
- 08 dev\_lint Ran all lint tests (whitespace, TODO, eslint, strict)
- 09 dev\_cover Calculated and report coverage
- 11 build Minimized, obfuscated, and SuperPacked three apps
- 11 build Created a unique dist folder for each app with meta-data and build reports

After this initial run, many of these steps will not be repeated. The install and setup stages, for example, will not be needed again unless the installation changes. The code quality checks like linting will only be needed if code files change. These dependencies are resolved by bin/xhi as discussed below.

#### Goal dependencies
Goal dependencies are stages that are always run before before a target stage. For example, if we run bin/xhi dev_commit the dev_lint, and dev_test stages will always be run first to ensure the code quality is acceptable. If either requirement fails, bin/xhi exits immediately (with an exit code of 1) and the target stage is not attempted. Goal dependencies are defined in package.json.xhi_commandTable. Don't change these without careful consideration and testing.

#### Environment dependencies
Environment dependencies must be successfully completed in the development environment before the target stage. For example, if we run bin/xhi dev_commit but have not run bin/xhi install, the install stage will be run before the dev_commit stage. The success or failure of each stage is saved in the state file (run/xhi_state.json) and the next stage is run. If the install stage succeeds it will not be included in future steps for dev_commit as it will have been completed in the prior run. Environment dependencies are defined in package.json.xhi_commandTable. Don't change these without careful consideration and testing.

Previously completed environment dependencies may be invalidated. For example, if bin/xhi install or bin/xhi upgrade fail, the tool will mark the install stage as failed and the stage will be attempted again in the next invocation that requires this stage as a dependencies.

Explicitly requested stages will always run regardless of their last success status. For example, bin/xhi dev_lint may or may not run the install stage, but bin/xhi install,dev_lint will always run the install stage because it is explicitly listed. bin/xhi help-dev_lint will also run install since it is explicitly within the range provided (help-dev_lint). Reset the status by removing the stage_status_map from the run/xhi_state.json file.

$3

`
hi_score/
│
├── app-.html <= Development test page
│
├── css
│   └── app-/ <= CSS if needed (but consider PowerCSS)
│   └── .css
├── img
│   └── app-/ <= App-specific image files
│   └── ..svg
└── js
   └── app-/ <= Libraries (discussed below).
   └── .00_root.js
`


The Typebomb 2 app uses PowerCSS instead of an external CSS file. In addition, there are no external images as it uses embedded SVGs. Our files therefore are as shown below.

`
hi_score/
│
├── app-tb02.html <= Development test page
│
└── js
   └── app-tb02/ <= Libraries (discussed below).
   ├── tb02.00_root.js
├── tb02.01_util.js
└── ...
`

Leverage the xhi library

- All layers are order from most basic 00_root to highest abstraction 08_app.
- Each layer is created using a corresponding xhi library file.
- Data flows from the lowest layer 00_root to the highest 08_app.
- All method calls are made from higher levels to lower. Calls from 02_data to 01_util or 03_model to 01_util are expected. Calls from a high layer like 07_shell to a low layer like 02_data should be scrutinized because one probably be calling all intermediate layer to safe state. All method calls from a lower layer to a higher layer or across modules of the same level are not allowed.
- Use event registration to communicate changes up the stack. For example, the 03_model may communicate an online status by publishing event data. All registered feature modules may then update their display.
- Create feature modules that contain their own isolated data and models when appropriate. This is pragmatic and recognizes the fractal nature of MVC.

The Typebomb 2 app has files for each layer as shown below.

`
Module layers
========================================
tb02.00_root.js | ^ \
tb02.01_util.js load | |
tb02.02_data.js order | |
tb02.02_01_data_mock.js | | |
tb02.03_model.js | call, |
tb02.04_utilb.js | init > xhi library
tb02.05_02_css_base.js events order |
tb02.05_03_css_lb.js | | |
tb02.05_css.js | | |
tb02.06_lb.js | | |
tb02.07_shell.js | | |
tb02.08_app.js v | /
`

All these modules claim a slice of the application name-space (tb02) and use js/xhi libraries in one of three ways:

1. Create a configured instance and use as-is
1. Create an instance and decorate
1. Use the module to guide development

More specific notes about Typebomb 2 app are provide in README.app-tb02.md. One can omit unused layers for a given app. However, for illustrative purposes, we have included all layers here. One can copy these to a new name-space to create a new app and edit from there. One can easily create a generator to automate these steps, but we show them in full for now.

`bash
cd ~/Github/hi_score;
export _ns='mine'

cp /template/app-tb02.html "app-${_ns}.html"

mkdir "js/app-${_ns}"
cd "js/app-${_ns}"

cp ../app-tb02/tb02.00_root.js "${_ns}.00_root.js"
cp ../app-tb02/tb02.01_util.js "${_ns}.01_util.js"
cp ../app-tb02/tb02.02_data.js "${_ns}.02_data.js"
cp ../app-tb02/tb02.02_01_data_mock.js "${_ns}.02_01_data_mock.js"
cp ../app-tb02/tb02.03_model.js "${_ns}.03_model.js"
cp ../app-tb02/tb02.04_utilb.js "${_ns}.04_utilb.js"
cp ../app-tb02/tb02.05_02_css_base.js "${_ns}.05_02_css_base.js"
cp ../app-tb02/tb02.05_03_css_lb.js "${_ns}.05_03_css_lb.js"
cp ../app-tb02/tb02.05_css.js "${_ns}.05_css.js"
cp ../app-tb02/tb02.06_lb.js "${_ns}.06_lb.js"
cp ../app-tb02/tb02.07_shell.js "${_ns}.07_shell.js"
cp ../app-tb02/tb02.08_app.js "${_ns}.08_app.js"

git add .
`

There is a lot less duplicate code here than it may appear. For example, any 01_util layer is just a singleton instance of the js/xhi/01_util utilities. And any model almost certainly inherits and reuses state values and methods from an instance of the js/xhi/03_model.

We change all references from tb02 in these new files to our new name-space, ${_ns}. We also create a new build manifest in package.json using the xhi_11_BuildMatrix configuration for tb02 as a guide. Once we confirm our new app builds as expected using bin/xhi build (check the output in build/latest/dist/app-${_ns}.html) we proceed to customize it as desired.

---


Vendor assets

Assets are copied to their destination directory with their version number appended to their names. The .gitignore file instructs git to ignore all these files as their development management is external to our project. Every time bin/xhi setup is run the vendor directories are deleted and recreated.

$3

The jQuery name-space is changed to xhiJQ and the PowerCSS name-space is changed from pcss to xhiCSS. This avoids conflicts with other libraries. The naming may be updated by adjusting bin/rename-vendor-symbols. When coding, please use these symbol (xhiJQ and xhiCSS) instead of their usual names (jQuery and pcss). Also, we do not expect the $ symbol to represent jQuery. Rely on local mapping if we want that behavior, e.g. (function ($) { ... }( xhiJQ )).

#### Node JS libraries
NodeJS libraries are not copied to a vendor directory. We may change
this if we decide to create a server distribution. The following libraries are
installed:

- [clusterjs][_34]: Server multiplexer
- [express][_36]: Minimalist Sinatra HTTP server
- [mongodb][_34]: Official mongodb node client
- [mysql2][_35]: Faster mysql interface
- [websocket][_37]: Websockets interface

#### Development JS libraries
Development libraries are used for testing a building code. They are not
copied to a vendor directory. The following libraries are installed:

- [coveralls][_18]: Code coverage reporting
- [istanbul][_19]: Code coverage
- [jsdom][_20]: DOM mock for testing
- [eslint][_21]: Linting for commit hook
- [nodeunit][_22]: Unit testing
- [node-inspector][_23]: Debugging
- [uglifycss][_24]: CSS minification
- [uglifyjs][_25]: JS minification

$3

`bash
cd js/vendor
cp jquery-3.5.1.js jquery-3.5.1.js.O

Now change jquery-3.5.1.js as required

And create the diff