Refactor matr into a modern minimal CLI runtime

.github/workflows/go.yml

@@ -1,18 +1,18 @@
 name: Go
 on:
   push:
-    branches: [master]
+    branches: [main]
   pull_request:
-    branches: [master]
+    branches: [main]
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v6.0.2
       - name: Set up Go
-        uses: actions/setup-go@v2
+        uses: actions/setup-go@v6.3.0
         with:
-          go-version: 1.19
+          go-version-file: go.mod
       - name: Build
         run: go build -v ./...
       - name: Test

.github/workflows/release.yml

@@ -9,18 +9,18 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out code into the Go module directory
-        uses: actions/checkout@v2
+        uses: actions/checkout@v6.0.2
         with:
           fetch-depth: 0 # See: https://goreleaser.com/ci/actions/
-      - name: Set up Go 1.19
-        uses: actions/setup-go@v2
+      - name: Set up Go
+        uses: actions/setup-go@v6.3.0
         with:
-          go-version: 1.19
+          go-version-file: go.mod
         id: go
       - name: Run GoReleaser
-        uses: goreleaser/goreleaser-action@master
+        uses: goreleaser/goreleaser-action@v7.0.0
         with:
           version: latest
-          args: release --rm-dist
+          args: release --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -6,39 +6,51 @@
 
 ## Install
 
-matr command
-
 ```bash
-$ go get github.com/euforic/matr
+$ go install github.com/euforic/matr/cmd/matr@latest
 ```
 
 ## Usage
 
-Execute target func
+Execute a command
 
 ```bash
 $ matr [target]
 ```
 
-List available targets and matr flags
+Show launcher flags
 
 ```bash
 $ matr -h
-Usage: matr <opts> [target] args...
-
-Targets:
-   build    Build will builds the project
-   run      Run will run the project
-   proto    Proto will build the protobuf files into golang files
-   test     Test runs all go tests
-   bench    Bench runs all the go benchmarks
-   docker   Docker builds static go binary then builds a docker image for it
+Usage of matr:
+  -clean
+    	clean the matr cache
+  -h	display usage info
+  -matrfile string
+    	path to Matrfile (default "./Matrfile.go")
+  -no-cache
+    	don't use the matr cache
+  -timeout duration
+    	task execution timeout; 0 disables the timeout (default 5m0s)
+  -v	display version
+```
+
+Get expanded help for a command
+
+```bash
+$ matr build -h
+```
+
+Override the task timeout
+
+```bash
+$ matr -timeout 30s test
 ```
 
-Get expanded help for a target
+Disable the timeout entirely
 
 ```bash
-$ matr -h [target]
+$ matr -timeout 0 run
 ```
 
 ## Matrfile
@@ -57,48 +69,107 @@ package main
 
 ## Targets
 
-Any exported function that is `func(ctx context.Context, args []string) error` is considered a
+Any exported function that is `func(ctx context.Context, cmd *matr.Invocation, args []string) error` is considered a
 matr target. If the function returns an error it will print to stdout and cause the matrfile
 to exit with an exit with a non 0 exit code.
 
 Comments on the target function will become documentation accessible by running
-`matr` (with no target). This will list all the build targets in this directory with the first
-sentence from their docs.
+`matr <target> -h`. This will show the command docs, aliases, dependencies, and command-scoped
+flags for that target.
 
 A target may be designated the default target, which is run when the user runs
 matr with no target specified. To denote the default, create a function named `Default`.
 If no default target is specified, running `matr` with no target will print the list of targets
 and docs.
 
-## Dependencies
+## Command Metadata
+
+Use comment metadata between the command docs and the function definition.
+
+```go
+// @alias:b
+// @depends:test,proto
+// @release:bool,short=r;build with release settings
+// @timeout:duration,short=t,default=30s;override build timeout
+// @token:string,required;API token used for deploys
+```
+
+Supported flag types:
+
+- `bool`
+- `string`
+- `int`
+- `duration`
+
+Metadata rules:
 
-The helper function `matr.Deps(ctx, ...matr.HandlerFunc)` may be passed a context and any number of
-functions (they do not have to be exported), and the Deps function will not return until all
-declared dependencies have been run (and any dependencies they have are run).
+- `@alias:<name>` adds a command alias.
+- `@depends:<name[,name...]>` declares make-like dependencies.
+- `@<flag>:<type>[,short=<char>][,default=<value>][,required];<description>` declares a local flag.
+- `required` is optional; flags are optional by default.
+- command flags are command-scoped, not global.
+- after parsing command flags, `args` contains only positional arguments.
 
-### Example Dependencies
+Dependencies are resolved as a serial DAG:
+
+- each dependency runs at most once per invocation
+- execution stops on the first dependency error
+- dependency cycles fail with an explicit error
+
+Use `cmd` inside handlers to read parsed flag values:
+
+- `cmd.Bool(name)`
+- `cmd.String(name)`
+- `cmd.Int(name)`
+- `cmd.Duration(name)`
+
+Command help includes aliases, dependencies, defaults, and required flags. Example:
+
+```bash
+$ matr build -h
+matr build:
+
+Build compiles the project.
+
+Aliases: b
+Depends on: test
+
+Flags:
+  --release, -r    build with release settings
+  --timeout, -t    override build timeout (default: 30s)
+  --token          API token used for deploys (required)
+```
+
+## Example
 
 ```go
-func Build(ctx context.Context, args []string) error {
-    err := matr.Deps(ctx, F, G)
-    fmt.Println("Build running")
-    return err
-}
+//go:build matr
 
-func F(ctx context.Context, args []string) error {
-    err := matr.Deps(ctx, h)
-    fmt.Println("f running")
-    return err
-}
+package main
 
-func G(ctx context.Context, args []string) error {
-    err := matr.Deps(ctx, F)
-    fmt.Println("g running")
-    return err
+import (
+    "context"
+    "fmt"
+
+    "github.com/euforic/matr"
+)
+
+// Build compiles the project.
+// @alias:b
+// @depends:test
+// @release:bool,short=r;build with release settings
+// @timeout:duration,short=t,default=30s;override build timeout
+// @token:string,required;API token used for deploys
+func Build(ctx context.Context, cmd *matr.Invocation, args []string) error {
+    fmt.Println("release:", cmd.Bool("release"))
+    fmt.Println("timeout:", cmd.Duration("timeout"))
+    fmt.Println("token:", cmd.String("token"))
+    fmt.Println("args:", args)
+    return nil
 }
 
-func h(ctx context.Context, args []string) error {
-    fmt.Println("h running")
-    return err
+// Test runs unit tests.
+func Test(ctx context.Context, _ *matr.Invocation, args []string) error {
+    return matr.Sh("go test ./...").Run()
 }
 ```

main.go → cmd/matr/main.go

@@ -1,8 +1,6 @@
 package main
 
-import (
-	"github.com/euforic/matr/matr"
-)
+import "github.com/euforic/matr"
 
 func main() {
 	matr.Run()