4 Commits

Author SHA1 Message Date
Zoe
4a70260ea5 Better debugging, and several bug fixes
This commit brings a greater experience for developers working on ZQDGR,
and also fixes a number of bugs. The following bugs have been fixed:
- Scripts that died in watch mode did not restart once changes were made
- Created and deleted files did not cause a reload
- script.Stop is now used in every place where we kill the process, this
  ensures that the process is *eventually* actually killed
2025-10-06 15:54:31 -05:00
Zoe
a62bfdb01d Fix restart after program has died 2025-10-06 14:43:33 +00:00
Zoe
f52a61b9ea ZQDGR v0.0.4: Qualirt of Life Update
This update brings several quality of life enhancements:
- You can now use excluded_files to exclude files from the watcher
- ZQDGR reloads itself when its config changes
- ZQDGR will not start if there are unrecognized keys in the config

It also fixes a bug where if a program was sent a kill signal, but didnt
die, ZQDGR would carry on as if it did, which lead to many issues.
2025-10-03 02:00:22 -05:00
Zoe
adac21ce29 revert flattening (#3), add -C 2025-05-22 15:52:34 -05:00
4 changed files with 315 additions and 158 deletions

View File

@@ -14,11 +14,13 @@ go install github.com/juls0730/zqdgr@latest
## Usage
Full usage
```Bash
zqdgr [options] <command>
```
The list of commands is
### Commands
- `init`
generates a zqdgr.config.json file in the current directory
@@ -30,25 +32,43 @@ The list of commands is
- `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
ZQDGR has the following list of 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');
@@ -75,21 +95,22 @@ socket.addEventListener('message', (event) => {
ZQDGR is solely configured by a `zqdgr.config.json` file in the root of your project. The file has the following keys:
| Key | Type | 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 | An object that maps a script name to a script command, which is just a shell command |
| pattern | string | The GLOB pattern that ZQDGR will watch for changes |
| excluded_dirs | array | The directories that ZQDGR will ignore when in the `watch` mode |
| shutdown_signal | string | The signal that ZQDGR will use to shutdown the script. Currently the only supported signals are `SIGINT`, `SIGTERM`, and `SIGQUIT`, if no shutdown signal is specified, ZQDGR will default to `SIGKILL` |
| 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.

303
main.go
View File

@@ -2,20 +2,21 @@ package main
import (
"bufio"
"bytes"
_ "embed"
"encoding/json"
"flag"
"fmt"
"log"
"log/slog"
"net/http"
"os"
"os/exec"
"os/signal"
"path"
"path/filepath"
"regexp"
"runtime"
"sort"
"strconv"
"strings"
"sync"
"syscall"
@@ -25,8 +26,6 @@ import (
"github.com/gorilla/websocket"
)
var executableName string
//go:embed embed/zqdgr.config.json
var zqdgrConfig []byte
@@ -43,11 +42,15 @@ type Config struct {
} `json:"repository"`
Scripts map[string]string `json:"scripts"`
Pattern string `json:"pattern"`
// Deprecated: use excludedGlobs instead
ExcludedDirs []string `json:"excluded_dirs"`
ExcludedGlobs []string `json:"excluded_files"`
ShutdownSignal string `json:"shutdown_signal"`
ShutdownTimeout int `json:"shutdown_timeout"`
}
type Script struct {
zqdgr *ZQDGR
command *exec.Cmd
mutex sync.Mutex
scriptName string
@@ -57,60 +60,48 @@ type Script struct {
exitCode int
}
func flattenZQDGRScript(commandString string) string {
keys := make([]string, 0, len(config.Scripts))
for k := range config.Scripts {
keys = append(keys, k)
type ZQDGR struct {
Config Config
WorkingDirectory string
EnableWebSocket bool
WSServer *WSServer
}
// Sort the keys in descending order in order to prevent scripts that might be substrings of other scripts to
// evaluate first.
sort.Slice(keys, func(i, j int) bool {
return len(keys[i]) > len(keys[j])
})
// escape scripts to be evaluated via regex
escapedKeys := make([]string, len(keys))
for i, key := range keys {
escapedKeys[i] = regexp.QuoteMeta(key)
}
pattern := `\b(` + executableName + `)\b` + `\s+` + `\b(` + strings.Join(escapedKeys, "|") + `)\b`
re := regexp.MustCompile(pattern)
currentCommand := commandString
for {
previousCommand := currentCommand
currentCommand = re.ReplaceAllStringFunc(currentCommand, func(match string) string {
// match the script name, not the whole `zqdgr script` command
match = strings.Split(match, " ")[1]
if val, ok := config.Scripts[match]; ok {
return val
}
return match
})
// If the current command has not changed, we have completely evaluated the command.
if currentCommand == previousCommand {
break
}
type WSServer struct {
upgrader websocket.Upgrader
clients map[*websocket.Conn]bool
clientsMux sync.Mutex
}
if re.MatchString(currentCommand) {
fmt.Println("Error: circular dependency detected in scripts")
os.Exit(1)
func NewZQDGR(enableWebSocket bool, configDir string) *ZQDGR {
zqdgr := &ZQDGR{
WorkingDirectory: configDir,
}
return currentCommand
err := zqdgr.loadConfig()
if err != nil {
log.Fatal(err)
return nil
}
func NewCommand(scriptName string, args ...string) *exec.Cmd {
if script, ok := config.Scripts[scriptName]; ok {
zqdgr.EnableWebSocket = enableWebSocket
zqdgr.WSServer = &WSServer{
upgrader: websocket.Upgrader{
CheckOrigin: func(r *http.Request) bool {
return true
},
},
clients: make(map[*websocket.Conn]bool),
clientsMux: sync.Mutex{},
}
return zqdgr
}
func (zqdgr *ZQDGR) NewCommand(scriptName string, args ...string) *exec.Cmd {
if script, ok := zqdgr.Config.Scripts[scriptName]; ok {
fullCmd := strings.Join(append([]string{script}, args...), " ")
fullCmd = flattenZQDGRScript(fullCmd)
var cmd *exec.Cmd
if runtime.GOOS == "windows" {
cmd = exec.Command("cmd", "/C", fullCmd)
@@ -118,6 +109,8 @@ func NewCommand(scriptName string, args ...string) *exec.Cmd {
cmd = exec.Command("sh", "-c", fullCmd)
}
cmd.Dir = zqdgr.WorkingDirectory
cmd.SysProcAttr = &syscall.SysProcAttr{
Setpgid: true,
}
@@ -132,8 +125,8 @@ func NewCommand(scriptName string, args ...string) *exec.Cmd {
}
}
func NewScript(scriptName string, args ...string) *Script {
command := NewCommand(scriptName, args...)
func (zqdgr *ZQDGR) NewScript(scriptName string, args ...string) *Script {
command := zqdgr.NewCommand(scriptName, args...)
if command == nil {
log.Fatal("script not found")
@@ -141,6 +134,7 @@ func NewScript(scriptName string, args ...string) *Script {
}
return &Script{
zqdgr: zqdgr,
command: command,
scriptName: scriptName,
isRestarting: false,
@@ -166,10 +160,12 @@ func (s *Script) Start() error {
s.exitCode = exitError.ExitCode()
} else {
// Other errors (e.g., process not found, permission denied)
if !s.isRestarting {
log.Printf("Error waiting for script %s: %v", s.scriptName, err)
s.exitCode = 1
}
}
}
if !s.isRestarting {
s.wg.Done()
@@ -179,14 +175,17 @@ func (s *Script) Start() error {
return err
}
func (s *Script) Restart() error {
func (s *Script) Stop(lock bool) error {
if lock {
s.mutex.Lock()
defer s.mutex.Unlock()
}
s.isRestarting = true
if s.command.Process != nil {
var signal syscall.Signal
switch config.ShutdownSignal {
switch s.zqdgr.Config.ShutdownSignal {
case "SIGINT":
signal = syscall.SIGINT
case "SIGTERM":
@@ -197,12 +196,54 @@ func (s *Script) Restart() error {
signal = syscall.SIGKILL
}
// make sure the process is not dead
if s.command.ProcessState != nil && s.command.ProcessState.Exited() {
return nil
}
if err := syscall.Kill(-s.command.Process.Pid, signal); err != nil {
log.Printf("error killing previous process: %v", err)
return err
}
}
s.command = NewCommand(s.scriptName)
dead := make(chan bool)
go func() {
s.command.Wait()
dead <- true
}()
shutdownTimeout := s.zqdgr.Config.ShutdownTimeout
if shutdownTimeout == 0 {
shutdownTimeout = 1
}
select {
case <-dead:
case <-time.After(time.Duration(shutdownTimeout) * time.Second):
log.Println("Script failed to stop after kill signal, force killing")
if err := syscall.Kill(-s.command.Process.Pid, syscall.SIGKILL); err != nil {
log.Printf("error killing previous process: %v", err)
return err
}
}
return nil
}
func (s *Script) Restart() error {
slog.Debug("Restarting script", "script", s.scriptName)
s.mutex.Lock()
err := s.Stop(false)
if err != nil {
s.mutex.Unlock()
return err
}
s.command = s.zqdgr.NewCommand(s.scriptName)
if s.command == nil {
// this should never happen
@@ -214,20 +255,20 @@ func (s *Script) Restart() error {
s.mutex.Unlock()
err := s.Start()
err = s.Start()
// tell the websocket clients to refresh
if enableWebSocket {
clientsMux.Lock()
for client := range clients {
if s.zqdgr.EnableWebSocket {
s.zqdgr.WSServer.clientsMux.Lock()
for client := range s.zqdgr.WSServer.clients {
err := client.WriteMessage(websocket.TextMessage, []byte("refresh"))
if err != nil {
log.Printf("error broadcasting refresh: %v", err)
client.Close()
delete(clients, client)
delete(s.zqdgr.WSServer.clients, client)
}
}
clientsMux.Unlock()
s.zqdgr.WSServer.clientsMux.Unlock()
}
return err
@@ -237,49 +278,39 @@ func (s *Script) Wait() {
s.wg.Wait()
}
func handleWs(w http.ResponseWriter, r *http.Request) {
conn, err := upgrader.Upgrade(w, r, nil)
func (wsServer *WSServer) handleWs(w http.ResponseWriter, r *http.Request) {
conn, err := wsServer.upgrader.Upgrade(w, r, nil)
if err != nil {
log.Printf("error upgrading connection: %v", err)
return
}
clientsMux.Lock()
clients[conn] = true
clientsMux.Unlock()
wsServer.clientsMux.Lock()
wsServer.clients[conn] = true
wsServer.clientsMux.Unlock()
for {
_, _, err := conn.ReadMessage()
if err != nil {
clientsMux.Lock()
delete(clients, conn)
clientsMux.Unlock()
wsServer.clientsMux.Lock()
delete(wsServer.clients, conn)
wsServer.clientsMux.Unlock()
break
}
}
}
var (
enableWebSocket = false
config Config
script *Script
upgrader = websocket.Upgrader{
CheckOrigin: func(r *http.Request) bool {
return true
},
}
clients = make(map[*websocket.Conn]bool)
clientsMux sync.Mutex
)
func loadConfig() error {
data, err := os.ReadFile("zqdgr.config.json")
func (zqdgr *ZQDGR) loadConfig() error {
data, err := os.ReadFile(path.Join(zqdgr.WorkingDirectory, "zqdgr.config.json"))
if err == nil {
if err := json.Unmarshal(data, &config); err != nil {
decoder := json.NewDecoder(bytes.NewReader(data))
decoder.DisallowUnknownFields()
err := decoder.Decode(&zqdgr.Config)
if err != nil {
return fmt.Errorf("error parsing config file: %v", err)
}
} else {
config = Config{
zqdgr.Config = Config{
Scripts: map[string]string{
"build": "go build",
"run": "go run main.go",
@@ -288,27 +319,54 @@ func loadConfig() error {
}
}
if zqdgr.Config.ExcludedDirs != nil {
fmt.Printf("WARNING: the 'excluded_dirs' key is deprecated, please use 'excluded_globs' instead\n")
zqdgr.Config.ExcludedGlobs = append(zqdgr.Config.ExcludedGlobs, zqdgr.Config.ExcludedDirs...)
}
return nil
}
func main() {
var err error
var debugMode bool
noWs := flag.Bool("no-ws", false, "Disable WebSocket server")
configDir := flag.String("config", ".", "Path to the config directory")
disableReloadConfig := flag.Bool("no-reload-config", false, "Do not restart ZQDGR on config file change")
flag.StringVar(configDir, "C", *configDir, "Path to the config directory")
flag.Parse()
if err := loadConfig(); err != nil {
debugModeVal, ok := os.LookupEnv("ZQDGR_DEBUG")
if ok {
debugMode, err = strconv.ParseBool(debugModeVal)
if err != nil {
log.Fatal(err)
}
if debugMode {
slog.SetLogLoggerLevel(slog.LevelDebug)
}
}
originalArgs := os.Args
os.Args = flag.Args()
zqdgr := NewZQDGR(*noWs, *configDir)
if zqdgr == nil {
return
}
var command string
var commandArgs []string
// get the name of the executable, and if it's a path then get the base name
// this is mainly for testing
executableName = path.Base(os.Args[0])
for i, arg := range os.Args[1:] {
for i, arg := range os.Args {
if arg == "--" {
if i+2 < len(os.Args) {
commandArgs = os.Args[i+2:]
}
break
}
@@ -462,7 +520,7 @@ func main() {
log.Fatal("please specify a script to run")
}
watchMode = true
for i := 0; i < len(commandArgs); i++ {
for i := range commandArgs {
if strings.HasPrefix(commandArgs[i], "-") {
continue
}
@@ -473,7 +531,7 @@ func main() {
scriptName = command
}
script = NewScript(scriptName, commandArgs...)
script := zqdgr.NewScript(scriptName, commandArgs...)
if err := script.Start(); err != nil {
log.Fatal(err)
@@ -486,19 +544,7 @@ func main() {
log.Println("Received signal, exiting...")
if script.command != nil {
var signal syscall.Signal
switch config.ShutdownSignal {
case "SIGINT":
signal = syscall.SIGINT
case "SIGTERM":
signal = syscall.SIGTERM
case "SIGQUIT":
signal = syscall.SIGQUIT
default:
signal = syscall.SIGKILL
}
syscall.Kill(-script.command.Process.Pid, signal)
script.Stop(true)
}
os.Exit(0)
@@ -506,10 +552,10 @@ func main() {
if watchMode {
if !*noWs {
enableWebSocket = true
zqdgr.EnableWebSocket = true
go func() {
http.HandleFunc("/ws", handleWs)
http.HandleFunc("/ws", zqdgr.WSServer.handleWs)
log.Printf("WebSocket server running on :2067")
if err := http.ListenAndServe(":2067", nil); err != nil {
log.Printf("WebSocket server error: %v", err)
@@ -517,15 +563,16 @@ func main() {
}()
}
if config.Pattern == "" {
if zqdgr.Config.Pattern == "" {
log.Fatal("watch pattern not specified in config")
}
// make sure the pattern is valid
var paternArray []string
var currentPattern string
inMatch := false
// iterate over every letter in the pattern
for _, p := range config.Pattern {
for _, p := range zqdgr.Config.Pattern {
if string(p) == "{" {
if inMatch {
log.Fatal("unmatched { in pattern")
@@ -561,7 +608,7 @@ func main() {
}
watcherConfig := WatcherConfig{
excludedDirs: globList(config.ExcludedDirs),
excludedGlobs: globList(zqdgr.Config.ExcludedGlobs),
pattern: paternArray,
}
@@ -577,6 +624,11 @@ func main() {
log.Fatal(err)
}
err = watcher.AddFile(path.Join(zqdgr.WorkingDirectory, "zqdgr.config.json"))
if err != nil {
log.Fatal(err)
}
// We use this timer to deduplicate events.
var (
// Wait 100ms for new events; each new event resets the timer.
@@ -600,9 +652,36 @@ func main() {
if !ok {
timer = time.AfterFunc(waitFor, func() {
slog.Debug("FSnotify event received", "event", event)
if event.Op&fsnotify.Remove == fsnotify.Remove || event.Op&fsnotify.Write == fsnotify.Write || event.Op&fsnotify.Create == fsnotify.Create {
fmt.Println("File changed:", event.Name)
if directoryShouldBeTracked(&watcherConfig, event.Name) {
slog.Debug("File changed", "file", event.Name)
if strings.HasSuffix(event.Name, "zqdgr.config.json") {
// re-exec the exact same command
if !*disableReloadConfig {
fmt.Println("zqdgr.config.json has changed, restarting...")
executable, err := os.Executable()
if err != nil {
log.Fatal(err)
}
err = script.Stop(true)
if err != nil {
log.Fatal(err)
}
err = syscall.Exec(executable, originalArgs, os.Environ())
if err != nil {
log.Fatal(err)
}
panic("unreachable")
}
}
if pathShouldBeTracked(&watcherConfig, event.Name) && event.Op&fsnotify.Create == fsnotify.Create {
slog.Debug("Adding new file to watcher", "file", event.Name)
watcher.(NotifyWatcher).watcher.Add(event.Name)
}

View File

@@ -4,7 +4,9 @@ import (
"errors"
"fmt"
"log"
"log/slog"
"path/filepath"
"strings"
"github.com/bmatcuk/doublestar"
"github.com/fsnotify/fsnotify"
@@ -14,27 +16,45 @@ type globList []string
func (g *globList) Matches(value string) bool {
for _, v := range *g {
// if the pattern matches a filepath pattern
if match, err := filepath.Match(v, value); err != nil {
log.Fatalf("Bad pattern \"%s\": %s", v, err.Error())
} else if match {
return true
}
// or if the path starts with the pattern
if strings.HasSuffix(value, v) {
return true
}
}
return false
}
func matchesPattern(pattern []string, path string) bool {
for _, p := range pattern {
slog.Debug("checking path against pattern", "pattern", p, "path", path)
if matched, _ := doublestar.Match(p, path); matched {
slog.Debug("path matches pattern", "pattern", p, "path", path)
return true
}
}
return false
}
func directoryShouldBeTracked(cfg *WatcherConfig, path string) bool {
func pathShouldBeTracked(cfg *WatcherConfig, path string) bool {
base := filepath.Dir(path)
return matchesPattern(cfg.pattern, path) && !cfg.excludedDirs.Matches(base)
slog.Debug("checking file against path", "path", path, "base", base)
if cfg.excludedGlobs.Matches(base) {
slog.Debug("file is excluded", "path", path)
return false
}
return matchesPattern(cfg.pattern, path)
}
func pathMatches(cfg *WatcherConfig, path string) bool {
@@ -42,13 +62,14 @@ func pathMatches(cfg *WatcherConfig, path string) bool {
}
type WatcherConfig struct {
excludedDirs globList
excludedGlobs globList
pattern globList
}
type FileWatcher interface {
Close() error
AddFiles() error
AddFile(path string) error
add(path string) error
getConfig() *WatcherConfig
}
@@ -62,6 +83,12 @@ func (n NotifyWatcher) Close() error {
return n.watcher.Close()
}
func (n NotifyWatcher) AddFile(path string) error {
slog.Debug("manually adding file", "file", path)
return n.add(path)
}
func (n NotifyWatcher) AddFiles() error {
return addFiles(n)
}
@@ -79,10 +106,12 @@ func NewWatcher(cfg *WatcherConfig) (FileWatcher, error) {
err := errors.New("no config specified")
return nil, err
}
w, err := fsnotify.NewWatcher()
if err != nil {
return nil, err
}
return NotifyWatcher{
watcher: w,
cfg: cfg,
@@ -92,18 +121,43 @@ func NewWatcher(cfg *WatcherConfig) (FileWatcher, error) {
func addFiles(fw FileWatcher) error {
cfg := fw.getConfig()
for _, pattern := range cfg.pattern {
slog.Debug("adding pattern", "pattern", pattern)
matches, err := doublestar.Glob(pattern)
if err != nil {
log.Fatalf("Bad pattern \"%s\": %s", pattern, err.Error())
}
trackedDirs := make(map[string]bool)
for _, match := range matches {
if directoryShouldBeTracked(cfg, match) {
base := filepath.Dir(match)
// this allows us to track file creations and deletions
if !trackedDirs[base] {
if cfg.excludedGlobs.Matches(base) {
slog.Debug("directory is excluded", "file", match)
continue
}
trackedDirs[base] = true
slog.Debug("adding directory", "dir", base)
if err := fw.add(base); err != nil {
return fmt.Errorf("FileWatcher.Add(): %v", err)
}
}
slog.Debug("adding file", "file", match)
if pathShouldBeTracked(cfg, match) {
slog.Debug("path should be tracked", "file", match)
if err := fw.add(match); err != nil {
return fmt.Errorf("FileWatcher.Add(): %v", err)
}
}
}
}
return nil
}

View File

@@ -1,6 +1,6 @@
{
"name": "zqdgr",
"version": "0.0.3",
"version": "0.0.5",
"description": "zqdgr is a quick and dirty Golang runner",
"author": "juls0730",
"license": "BSL-1.0",
@@ -14,9 +14,12 @@
"dev": "sleep 5; echo 'test' && sleep 2 && echo 'test2'",
"test": "zqdgr test:1 && zqdgr test:2 && zqdgr test:3 && zqdgr test:4",
"test:1": "echo 'a'",
"test:2": "false",
"test:2": "true",
"test:3": "echo 'b'",
"test:4": "zqdgr test:3",
"test:5": "zqdgr test:6",
"test:6": "zqdgr test:7",
"test:7": "zqdgr test:5",
"recursive": "zqdgr recursive"
},
"pattern": "**/*.go"