# ZQDGR

ZQDGR is Zoe's Quick and Dirty Golang Runner. This is a simple tool that lets you run a go project in a similar way to
how you would use npm. ZQDGR lets you watch files and rebuild your project as you make changes. ZQDGR also includes an
optional websocket server that will notify listeners that a rebuild has occurred, this is very useful for live reloading
when doing web development with Go.

**Status: Alpha**

This project is not recommend for production use, you are allowed to, and I try
my best to keep it as stable as possible, but features and APIs will change
in nearly every release without backwards compatibility, upgrade carefilly, and
make sure to depend on a specific version of ZQDGR.

## Install

```bash
go install github.com/juls0730/zqdgr@latest
```

## Usage

Full usage

```Bash
zqdgr [options] <command>
```

### Commands

- `init`

  generates a zqdgr.config.json file in the current directory

- `new [project name] [github repo]`

  Creates a new golang project with zqdgr and can optionally run scripts from a github repo

- `watch <script>`

  runs the script in "watch mode", when files that follow the pattern in zqdgr.config.json change, the script restarts

- `<script>`

  runs the script

### Options

- `-no-ws`

  disables the web socket server running at 2067

- `-config`

  specifies the path to the config file

- `-disable-reload-config`

  disables reloading the config file when it changes

- `-C`

  specifies the path to use as the working directry

Example usage:

```bash
zqdgr init
zqdgr watch dev
zqdgr -config ./my-config.json watch dev
zqdgr -C ./my-nested-project watch dev
```

### ZQDGR websocket

ZQDGR comes with a websocket to notify listeners that the application has updates, the websocket is accessible at
`127.0.0.1:2067/ws`. An example dev script to listen for rebuilds might look like this

```Javascript
let host = window.location.hostname;
const socket = new WebSocket('ws://' + host + ':2067/ws');

socket.addEventListener('message', (event) => {
    if (event.data === 'refresh') {
        async function testPage() {
            try {
            let res = await fetch(window.location.href)
            } catch (error) {
                console.error(error);
                setTimeout(testPage, 300);
                return;
            }
            window.location.reload();
        }

        testPage();
    }
});
```

## Configuration

ZQDGR is solely configured by a `zqdgr.config.json` file in the root of your project. The file has the following keys:

| Key              | Type   | Required | default | Description                                                                                              |
| ---------------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------- |
| name             | string | -        | -       | The name of the project                                                                                  |
| version          | string | -        | -       | The version of the project                                                                               |
| description      | string | -        | -       | The description of the project                                                                           |
| author           | string | -        | -       | The author of the project (probably you)                                                                 |
| license          | string | -        | -       | The license of the project                                                                               |
| homepage         | string | -        | -       | The URL to the homepage of the project                                                                   |
| repository       | object | -        | -       | The repository of the project                                                                            |
| repository.type  | string | -        | -       | The type of VCS that you use, most likely git                                                            |
| repository.url   | string | -        | -       | The place where you code is hosted. This should be a URI that can be used as is in a program such as git |
| scripts          | object | true     | -       | An object that maps a script name to a script command, which is just a shell command                     |
| pattern          | string | true     | -       | The GLOB pattern that ZQDGR will watch for changes                                                       |
| excluded_globs   | array  | -        | -       | Globs that ZQDGR will ignore when in the `watch` mode                                                    |
| shutdown_signal  | string | -        | SIGINT  | The signal that ZQDGR will use to shutdown the script. One of SIGKILL, SIGINT, SIGQUIT, SIGTERM          |
| shutdown_timeout | int    | -        | 1       | The amount of time in seconds that ZQDGR will wait for the script to exit before force killing it.       |

The only required key is `scripts`, the rest are optional, but we recommend you set the most important ones.

## ZQDGR `new` scripts

Since ZQDGR v0.0.2, you can easily initialize a new project with `zqdgr new` and optionally, you can specify a git repo
to use as the initializer script. An example script is available at
[github.com/juls0730/zqdgr-script-example](https://github.com/juls0730/zqdgr-script-example).

Every initialize script is expected to follow a few rules:

- The project must be a zqdgr project
- The `build` script must exist and must export a binary named `main`

ZQDGR passes your init script the directory that is being initialized as the first and only argument and runs the script
in the target directory. When your binary is executed, there is a git repository and the project is in the following
state:

- go.mod
- main.go
- zqdgr.config.json

## Attribution

This project uses work from the following projects:

- [CompileDaemon](https://github.com/githubnemo/CompileDaemon)

  ```
    Copyright (c) 2013, Marian Tietz
    All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the above copyright notice, this
      list of conditions and the following disclaimer.

    * Redistributions in binary form must reproduce the above copyright notice,
      this list of conditions and the following disclaimer in the documentation
      and/or other materials provided with the distribution.

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
    OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  ```