diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml index ddf9963..0911e9a 100644 --- a/.gitea/workflows/ci.yaml +++ b/.gitea/workflows/ci.yaml @@ -2,7 +2,7 @@ name: CI on: push: - branches: ["main", "dev"] + branches: ["main"] pull_request: jobs: diff --git a/.gitea/workflows/release.yaml b/.gitea/workflows/release.yaml index 5a638f9..d9b7369 100644 --- a/.gitea/workflows/release.yaml +++ b/.gitea/workflows/release.yaml @@ -15,5 +15,3 @@ jobs: uses: actions/checkout@v4 - name: Release uses: softprops/action-gh-release@v2 - with: - draft: true diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..debb57b --- /dev/null +++ b/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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..c476a7c --- /dev/null +++ b/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) diff --git a/Sources/hpa/CreateCommand.swift b/Sources/hpa/CreateCommand.swift index d7931d8..a0b0b81 100644 --- a/Sources/hpa/CreateCommand.swift +++ b/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 diff --git a/justfile b/justfile index fbba002..7d153f2 100644 --- a/justfile +++ b/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"