# swift-hpa

A command-line application for managing home performance assessment projects from user defined
template repositories.

This tool is a wrapper around several other command line applications, the primary ones being:

1. `ansible-playbook`
1. `ansible-vault`
1. `pandoc`

## Installation

You can install the application using homebrew.

```bash
brew tap michael/formula https://git.housh.dev/michael/homebrew-formula
brew install michael/formula/hpa
```

Installation on platforms other than `macOS` are currently being worked on, along with support for
running in a `docker` container.

### Ensuring dependencies are installed.

This application requires some dependencies to be installed on your system, you can install the
dependencies with the following command.

```bash
hpa utils install-dependencies
```

The dependencies installed are:

1. ansible
1. imagemagick
1. pandoc
1. texLive

It will also download an ansible-playbook that is used to generate output files, template
repositories, and encrypt / decrypt variable files. The playbook get's installed to
`~/.local/share/hpa/playbook`.

> NOTE: All commands accept a `--help` option which will display the arguments and options a command
> can use, along with example usage of the commands.

### Configure the application.

When you first download the application you can setup the configuration file for your use case.

```bash
hpa utils generate-config
```

This will create a configuration file in the default location: `~/.config/hpa/config.toml`, which
can be edited to suit your needs.

## Getting Started

The first step to getting started is creating your template. This is used to create projects. The
template defines the structure of a project and defines variables which are used to generate the
final output files of a project.

You can generate the template using following command:

```bash
hpa utils generate-template --path ~/projects/my-template
```

Where the `--path` is where you would like the template to be on your local system.

It is recommended that after you get your template setup to your liking that you turn it into a
`git` repository. Therefore your projects can be pinned to specific version of the template. This
allows your template to expand over time.

Once your template is setup, make sure that your configuration file is setup to point to your
customized template.

## Creating a project.

The first step after having your template defined is to create a project that uses it. The below
command will create a template in the `~/consults/my-first-consult` directory.

```bash
hpa create ~/consults/my-first-consult
```

The above assumes that your template is a `git` repository and that your configuration is setup
properly. If you want to experiment with a local template that is on your system then you can you
can use one of the following command options.

```bash
hpa create --template-dir ~/projects/my-template ~/consults/my-first-consult
```

Or if your configuration has `directory` set in the `template` section.

```bash
hpa create --use-local-template ~/consults/my-first-consult
```

## Generating output files.

Once you have created a project and edited the contents to your liking. You can then generate the
final output file (typically a pdf) that can be sent to your customer.

```bash
hpa generate pdf
```

The above _assumes_ that you are inside your project directory, if you would like to generate an
output file from outside of your project directory you can specify the path to the project you would
like to generate output for.

```bash
hpa generate pdf --project-directory ~/consults/my-first-consult
```

Currently the supported output file types are:

1. PDF
1. LaTeX
1. HTML

## Build command.

The command line tool goes through an intermediate step when generating output, which is called
`build`. The build step generates the final output files using defined variables that are located in
your project directory or in your template directory. It will decrypt any sensitive data stored in
`vault` files as well.

These files get placed inside a directory in the project, default location is `.build`. The generate
commands by default build the project for you, unless you specify the `--no-build` option.

You can explore the contents of the `.build` directory or if you'd like to separate the build and
generate steps, you can build a project using the following command:

```bash
hpa build
```

The above _assumes_ that you are inside your project directory, if you would like to generate an
output file from outside of your project directory you can specify the path to the project you would
like to generate output for.

```bash
hpa build --project-directory ~/consults/my-first-consult
```

## Some General Usage Notes:

There is often a lot of output to the console when running commands, which can be problematic if you
want to pipe the output into other command line tools, so all options accept a `-q | --quiet` flag
which will suppress logging output and allow piping into other commands.

Along the similar line, if you would like to increase the logging output then all commands accept
`-v | --verbose` that will increase the logging output. This can be passed multiple times, so for
the highest log output you can do `-vvv`.

## Uninstalling

You can uninstall the application using:

```bash
brew uninstall hpa
```

Also remove the configuration and playbook directories.

```bash
rm -rf ~/.config/hpa
rm -rf ~/.local/share/hpa
```

## LICENSE

This project is licensed under the `MIT` license.

[See license](https://git.housh.dev/michael/swift-hpa/LICENSE)