=====================================================================
tl;dr
=====================================================================

You can get this by running jex --help

COMMANDS:
  man             show the manual
  dwim-           init, pull, build
  dwim+           init, pull, build, mindist, push
  cfgbarf         barf out the jex.eterms file (mostly to make sure it parses correctly)
  echo home       echo $HOME
  echo jexdir     echo $HOME/.jex
  echo devdir     echo $HOME/.jex/dev
  echo pkgname    name of current package
  echo pkgdir     echo $HOME/.jex/dev/realm-name-X.Y.Z
  echo deps       list dependencies of current package
  echo pathof PKG list the path to PKG or 
  init            mkdir -p $HOME/.jex/dev
  build           tsc && cp -r ./src/jex_include ./dist/
      -w, --weak      continue building even if tsc fails
      -f, --force     use cp -rf instead of cp -r
  mindist         mkdir jex_mindist && cp -r src jex_mindist && cp -r dist jex_mindist && rm -r jex_mindist/src/jex_include
      -f, --force     use cp -rf instead of cp -r
  push            rsync -a jex_mindist/ PKGDIR
  ls              ls $HOME/.jex/dev
  tree            tree $HOME/.jex/
  rmpkg PKG       rm -r $HOME/.jex/dev/PKG
  pull            pull each dependency into src/jx_include


=====================================================================
JEX MANUAL
=====================================================================

Jex is a simple packaging/dependency system for TypeScript/JavaScript
projects.

As of now, Jex is a glorified shell script that automates a lot of
the tedium in building sidekick, JR, etc.  Jex is very much a work in
progress, so these instructions are subject to change.

Jex is currently hyper-specialized to our use cases inside of
Vanillae, and is probably (currently) unsuitable for your use case.
For instance, Jex assumes you are running a UNIX-like system with
standard UNIX programs installed (e.g. tree, rsync, tar, etc).  It
also makes very strong assumptions about your project structure and
how you want to distribute your project.

Our long-term goal is to build Jex out into a proper secure packaging
system, and completely remove any dependency on NPM.  NPM comes with
a lot of unfixable security issues that present an unacceptable risk
in a business context.  Developing software for the business context
is the focus of the Vanillae project.

You'll see how it works and what the philosophy is if you keep
reading.


=====================================================================
HOW IT WORKS
=====================================================================

To start off, we run `jex init`

    [~] % jex init
    $ mkdir -p /home/pharpend/.jex/dev

As I said above, jex is currently a glorified shell script. Much like
`make`, jex prints the command it's running with a `$` at the
beginning of the line.

We can get a sense of what will go in this directory by running `jex
tree` (yours will not look like this):

    [~] % jex tree
    $ tree /home/pharpend/.jex
    /home/pharpend/.jex
    └── dev
        ├── local-awcp-0.1.0
        │   ├── dist
        │   │   ├── awcp.d.ts
        │   │   ├── awcp.js
        │   │   ├── awcp.js.map
        │   │   └── jex_include
        │   └── src
        │       └── awcp.ts
        ├── local-parasite-0.1.0
        │   ├── dist
        │   │   ├── ae_compiler.d.ts
        │   │   ├── ae_compiler.js
        │   │   ├── ae_compiler.js.map
        │   │   ├── ae_node.d.ts
        │   │   ├── ae_node.js
        │   │   ├── ae_node.js.map
        │   │   ├── jex_include
        │   │   ├── net.d.ts
        │   │   ├── net.js
        │   │   └── net.js.map
        │   └── src
        │       ├── ae_compiler.ts
        │       ├── ae_node.ts
        │       └── net.ts
        └── local-sidekick-0.1.0
            ├── dist
            │   ├── jex_include
            │   │   └── local-awcp-0.1.0
            │   │       ├── dist
            │   │       │   ├── awcp.d.ts
            │   │       │   ├── awcp.js
            │   │       │   ├── awcp.js.map
            │   │       │   └── jex_include
            │   │       └── src
            │   │           └── awcp.ts
            │   ├── sidekick.d.ts
            │   ├── sidekick.js
            │   └── sidekick.js.map
            └── src
                └── sidekick.ts

    17 directories, 24 files

Currently, Jex is managing 3 packages for me:

1. awcp
2. parasite
3. sidekick

In a secure context, we want to avoid opaque rewrites whenever
possible. This rules out bundling or minifying tools such as
browserify.  We want the code that is running in the user's browser
to be human-readable and to have a straightforward mapping to
the original source.

Let's start with the simplest package which is `awcp`.  This is the
source directory listing

    [v/libs pharpend/develop] % tree awcp
    awcp
    ├── dist
    │   ├── awcp.d.ts
    │   ├── awcp.js
    │   ├── awcp.js.map
    │   └── jex_include
    ├── erl_crash.dump
    ├── jex.eterms
    ├── jex_mindist
    │   ├── dist
    │   │   ├── awcp.d.ts
    │   │   ├── awcp.js
    │   │   ├── awcp.js.map
    │   │   └── jex_include
    │   └── src
    │       └── awcp.ts
    ├── LICENSE
    ├── Makefile
    ├── README.md
    ├── src
    │   ├── awcp.ts
    │   └── jex_include
    └── tsconfig.json

    8 directories, 14 files

There is only one source file: `/src/awcp.ts`. There is a directory
called `/src/jex_include/` which is empty.  If awcp had dependencies,
this is where they would go.

The file tree that ends up in `~/.jex/dev` is the `jex_mindist`
directory. Let's focus on that

    [v/libs pharpend/develop] % tree awcp/jex_mindist
    awcp/jex_mindist
    ├── dist
    │   ├── awcp.d.ts
    │   ├── awcp.js
    │   ├── awcp.js.map
    │   └── jex_include
    └── src
        └── awcp.ts

    3 directories, 4 files

As you can see, it's the same tree

    [v/libs pharpend/develop] % tree ~/.jex/dev/local-awcp-0.1.0
    /home/pharpend/.jex/dev/local-awcp-0.1.0
    ├── dist
    │   ├── awcp.d.ts
    │   ├── awcp.js
    │   ├── awcp.js.map
    │   └── jex_include
    └── src
        └── awcp.ts

    3 directories, 4 files

Briefly, jex is built around the assumptions that you want simplicity,
transparency, and composability, possibly at the expense of some
duplication.

It's assumed that you are developing JS to execute in the context of
a website, that you are writing only a small amount of JS (i.e. NOT
framework JS or a single-page-application), and that serving a
JavaScript file tree does not present a bandwidth issue.  Everything
has a version number, so that you can properly take advantage of
caching.

The idea is that you want to be able to take that file tree above,
make it into a tarball, drop it on your server, and have it "just
work".  Or, you can drop the whole tree into your existing project
and have it "just work".  We want the source map to work properly, so
the TypeScript source is included in the bundle.

Let's switch over to the Sidekick project. Sidekick depends on AWCP.

    [src/v pharpend/develop] % tree sidekick/src
    sidekick/src
    ├── jex_include
    │   └── local-awcp-0.1.0
    │       ├── dist
    │       │   ├── awcp.d.ts
    │       │   ├── awcp.js
    │       │   ├── awcp.js.map
    │       │   └── jex_include
    │       └── src
    │           └── awcp.ts
    └── sidekick.ts

    5 directories, 5 files

To import AWCP, `sidekick.ts` contains this line

    import * as awcp from './jex_include/local-awcp-0.1.0/dist/awcp.js';

Notice that we're importing the JS file, not the TS file.  TypeScript
gets its type information from the `dist/awcp.d.ts` file, not from
the `src/awcp.ts` file.  The `src/awcp.ts` file is only included so
the source map works properly in the browser's debugger.