README & License (#3)

Reviewed-on: #3

.gitea/workflows/ci.yaml

@@ -2,7 +2,7 @@
 name: CI
 on:
   push:
-    branches: ["main", "dev"]
+    branches: ["main"]
   pull_request:
 
 jobs:

.gitea/workflows/release.yaml

@@ -15,5 +15,3 @@ jobs:
         uses: actions/checkout@v4
       - name: Release
         uses: softprops/action-gh-release@v2
-        with:
-          draft: true

LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Michael Housh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,179 @@
+# 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)

Sources/hpa/CreateCommand.swift

@@ -40,7 +40,10 @@ struct CreateCommand: AsyncParsableCommand {
   var templateDir: String?
 
   @Flag(
-    name: .shortAndLong,
+    name: [
+      .short,
+      .customLong("use-local-template")
+    ],
     help: "Force using a local template directory."
   )
   var localTemplateDir = false

justfile

@@ -6,6 +6,8 @@ tap_url := "https://git.housh.dev/michael/homebrew-formula"
 tap := "michael/formula"
 formula := "hpa"
 
+release_base_url := "https://git.housh.dev/michael/swift-hpa/archive"
+
 # Build and bottle homebrew formula.
 bottle:
   @brew uninstall {{formula}} || true
@@ -50,6 +52,10 @@ test-docker *ARGS: (build-docker-test)
     {{docker_image_name}}:test \
     swift test {{ARGS}}
 
+# Remove bottles
+remove-bottles:
+  rm -rf *.gz
+
 # Run the application.
 run *ARGS:
   swift run hpa {{ARGS}}
@@ -67,3 +73,12 @@ update-version:
     --allow-writing-to-package-directory \
     update-version \
     hpa
+
+# Get the sha256 sum of the release and copy to clipboard.
+get-release-sha prefix="": (build "release")
+  version=$(.build/release/hpa --version) && \
+    url="{{release_base_url}}/{{prefix}}${version}.tar.gz" && \
+    sha=$(curl "$url" | shasum -a 256) && \
+    stripped="${sha% *}" && \
+    echo "$stripped" | pbcopy && \
+    echo "Copied sha to clipboard: $stripped"