Quickstart
==========


Running the demo
----------------

In order to run the example runner (`sample_challenge.sh`) you need to clone
this repository, install the Go language binary and run::

        go build -ldflags "-X main.encryption_key=example_key_1234"


Structure of a TA level
------------------------

The respective levels (or stages) of your challenges (shell sessions the
runners start) are described in ``.ta`` files. Levels are separated by Markdown
horizontal lines with at least 10 dashes.

In order for a level to be recognized, it needs to have two parts: ``metadata``
and ``text``. As expected, the ``text`` is just Markdown formatted text that gets
printed in terminal and should guide the user. The ``metadata`` consist of a YAML
document that specifies metadata for a given level. The ``metadata`` are
separated from ``text`` by two new lines. An example challenge (.ta) file might
therefore look as follows::

    name: level0
    test: test $(pwd) = "/tmp"

    In this level your task is to change your working directory to '/tmp'.

    --------------------

    name: level1
    test: test $(pwd) = "$HOME"

    Awesome, you made it to /tmp. Now get back to your home directory.

    --------------------

    name: level2
    test: false

    I see you made it again, awesome! That's all for now, so lay back and enjoy your
    shell!


The basic operation can be described follows:

1. User is first 'dropped' into the first level.
2. The level's text is printed.
3. After each command the ``test`` of the current level is executed.
4. If the ``test`` passes (that is the exit status code of the command
   mentioned in the ``test`` field is ``0``), user's level gets changed to
   the next level and the application proceeds with 2.

Note that in our case it is not possible to get out of ``level2``, since
the ``false`` command never produces an exit status code ``0``, which is
necessary for the test to pass.

Validating a given ``.ta`` file
--------------------------------

The generated binary (``term-adventure``) also provides an option to check,
whether the ``.ta`` file is loaded correctly. In order to check file
``sample.ta`` you can run::

        $ ./term-adventure --print sample.ta


Validating user's progress
--------------------------

The binary uses a hash of many interesting things to keep track of the level
you are currently in. Depending on the name of the challenge and whether you
use the attached ``challenger.sh``, it can be found in the following file::

    $HOME/$CHALLENGE/config.ini


Once you have this hash and the home directory of the user which has managed to
enter the level denoted by this hash, you can reverse-lookup the name of that
level by executing::

    $ ./term-adventure --detect-level ./sample.ta $HASH $HOMEDIR