allow per-group options and metadata (#94)

* allow per-group options and metadata

* use tagged chinampa

.milpa/commands/itself/_itself.yaml

@@ -0,0 +1,2 @@
+summary: subcommands that operate on `milpa`, itself
+description: These commands are helpful to operate on milpa repos and the tool itself.

.milpa/commands/itself/repo/install.yaml

@@ -16,7 +16,7 @@ description: |
 
 arguments:
   - name: source
-    description: A go-getter URL to fetch the repo from.
+    description: A go-getter URL to fetch the repo from
     required: true
     values:
       static:

.milpa/docs/milpa/command/spec.md

@@ -126,6 +126,7 @@ options:
     # the `values` property specifies how to provide completions and perform validation on
     values: {}
 ```
+---
 
 ## Value completion and validation
 
@@ -190,3 +191,26 @@ Additionally, the following Go functions are available:
 - `{{ trim " padded " }}`: [`strings.Trim`](https://pkg.go.dev/strings#Trim)
 - `{{ trimSuffix "content" "con" }}`: [`strings.TrimSuffix`](https://pkg.go.dev/strings#TrimSuffix)
 - `{{ trimPrefix "content" "ent" }}`: [`strings.TrimPrefix`](https://pkg.go.dev/strings#TrimPrefix)
+
+---
+
+## _Group Command_ Spec
+
+A _group command_, that is, a command whose only job is to serve as a grouping mechanism for other commands, can also have a limited spec. These are useful to provide clearer documentation on what that set of commands are to be used for, as well as setting group-level **options** (see above).
+
+Let's say we have a few commands under the group `milpa test`: `milpa test unit` and `milpa test integration`. A `summary`, `description` and `options` can be defined for this group by creating a spec at `.milpa/commands/test/_test.yaml`, that is, the name of the group (in this case `test`) prefixed by a single underscore (`_`) with.For example:
+
+```yaml
+# .milpa/commands/test/_test.yaml
+summary: Commands for running tests
+description: |
+  Holds commands to run unit tests and integration tests.
+# any options defined in a group command spec
+# will be available to any immediate children of `test`
+options:
+  coverage:
+    type: bool
+    description: generate coverage reports
+```
+
+> ⚠️ `arguments` are not allowed as part of a _group command_ spec.

compa.go

@@ -45,7 +45,7 @@ func main() {
 		Name:    "milpa",
 		Version: version,
 		Summary: "Runs commands found in " + _c.RepoRoot + " folders",
-		Description: `﹅milpa﹅ is a command-line tool to care for one's own garden of scripts, providing autocomplete, sub-commands, argument parsing and validation, along beautiful documentation—just add a simple YAML spec and a bash (or your language of choice) script.
+		Description: `﹅milpa﹅ is a command-line tool to care for one's own garden of scripts, providing autocomplete, sub-commands, argument parsing and validation, along beautiful documentation—all it takes is a YAML spec and a script: bash or your language of choice.
 
 See [﹅milpa help docs milpa﹅](/.milpa/docs/milpa/index.md) for more information about ﹅milpa﹅.`,
 	}

go.mod

@@ -3,8 +3,8 @@ module github.com/unrob/milpa
 go 1.20
 
 require (
-	git.rob.mx/nidito/chinampa v0.0.0-20230324064447-fef0a55288ea
-	github.com/alecthomas/chroma/v2 v2.5.0
+	git.rob.mx/nidito/chinampa v0.1.0
+	github.com/alecthomas/chroma/v2 v2.7.0
 	github.com/alessio/shellescape v1.4.1
 	github.com/bmatcuk/doublestar/v4 v4.6.0
 	github.com/charmbracelet/glamour v0.6.0

go.sum

@@ -179,17 +179,17 @@ cloud.google.com/go/webrisk v1.5.0/go.mod h1:iPG6fr52Tv7sGk0H6qUFzmL3HHZev1htXuW
 cloud.google.com/go/workflows v1.6.0/go.mod h1:6t9F5h/unJz41YqfBmqSASJSXccBLtD1Vwf+KmJENM0=
 cloud.google.com/go/workflows v1.7.0/go.mod h1:JhSrZuVZWuiDfKEFxU0/F1PQjmpnpcoISEXH2bcHC3M=
 dmitri.shuralyov.com/gpu/mtl v0.0.0-20190408044501-666a987793e9/go.mod h1:H6x//7gZCb22OMCxBHrMx7a5I7Hp++hsVxbQ4BYO7hU=
-git.rob.mx/nidito/chinampa v0.0.0-20230324064447-fef0a55288ea h1:h5/LtKqw3nNwh0di7JJho4r9Ey0MfUKvSDm5A0OFeYA=
-git.rob.mx/nidito/chinampa v0.0.0-20230324064447-fef0a55288ea/go.mod h1:ImvF16HDuvzSgb1VYOlrw6v1Hy/QNNNr2drVetpEvsk=
+git.rob.mx/nidito/chinampa v0.1.0 h1:uEaYTY2HJyNemIWIjERq6LNRrVIkjHoE835PkxmzsNI=
+git.rob.mx/nidito/chinampa v0.1.0/go.mod h1:ImvF16HDuvzSgb1VYOlrw6v1Hy/QNNNr2drVetpEvsk=
 github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU=
 github.com/BurntSushi/xgb v0.0.0-20160522181843-27f122750802/go.mod h1:IVnqGOEym/WlBOVXweHU+Q+/VP0lqqI8lqeDx9IjBqo=
 github.com/OneOfOne/xxhash v1.2.2/go.mod h1:HSdplMjZKSmBqAxg5vPj2TmRDmfkzw+cTzAElWljhcU=
 github.com/alecthomas/assert/v2 v2.2.1 h1:XivOgYcduV98QCahG8T5XTezV5bylXe+lBxLG2K2ink=
 github.com/alecthomas/chroma v0.10.0 h1:7XDcGkCQopCNKjZHfYrNLraA+M7e0fMiJ/Mfikbfjek=
 github.com/alecthomas/chroma v0.10.0/go.mod h1:jtJATyUxlIORhUOFNA9NZDWGAQ8wpxQQqNSB4rjA/1s=
 github.com/alecthomas/chroma/v2 v2.2.0/go.mod h1:vf4zrexSH54oEjJ7EdB65tGNHmH3pGZmVkgTP5RHvAs=
-github.com/alecthomas/chroma/v2 v2.5.0 h1:CQCdj1BiBV17sD4Bd32b/Bzuiq/EqoNTrnIhyQAZ+Rk=
-github.com/alecthomas/chroma/v2 v2.5.0/go.mod h1:yrkMI9807G1ROx13fhe1v6PN2DDeaR73L3d+1nmYQtw=
+github.com/alecthomas/chroma/v2 v2.7.0 h1:hm1rY6c/Ob4eGclpQ7X/A3yhqBOZNUTk9q+yhyLIViI=
+github.com/alecthomas/chroma/v2 v2.7.0/go.mod h1:yrkMI9807G1ROx13fhe1v6PN2DDeaR73L3d+1nmYQtw=
 github.com/alecthomas/repr v0.0.0-20220113201626-b1b626ac65ae/go.mod h1:2kn6fqh/zIyPLmm3ugklbEi5hg5wS435eygvNfaDQL8=
 github.com/alecthomas/repr v0.2.0 h1:HAzS41CIzNW5syS8Mf9UwXhNH1J9aix/BvDRf1Ml2Yk=
 github.com/alessio/shellescape v1.4.1 h1:V7yhSDDn8LP4lc4jS8pFkt0zCnzVJlG5JXy9BVKJUX0=

internal/actions/command_tree.go

@@ -27,7 +27,7 @@ type serializar func(interface{}) ([]byte, error)
 func addMetaToTree(t *tree.CommandTree) {
 	if t.Command != nil && t.Command.Meta == nil {
 		meta := &milpaCmd.Meta{
-			Path: "",
+			Path: t.Command.Name(),
 			Repo: "",
 			Name: t.Command.Path,
 			Kind: milpaCmd.KindVirtual,

internal/command/command.go

@@ -17,8 +17,14 @@ import (
 func New(path string, repo string) (cmd *command.Command, err error) {
 	meta := metaForPath(path, repo)
 	cmd = &command.Command{
-		Path: meta.Name,
-		Action: func(cmd *command.Command) error {
+		Path:      meta.Name,
+		Arguments: []*command.Argument{},
+		Options:   command.Options{},
+	}
+
+	var spec string
+	if meta.Kind != "virtual" {
+		cmd.Action = func(cmd *command.Command) error {
 			if err := canRun(cmd); err != nil {
 				return err
 			}
@@ -32,12 +38,12 @@ func New(path string, repo string) (cmd *command.Command, err error) {
 
 			fmt.Println(env)
 			return nil
-		},
+		}
+		spec = strings.TrimSuffix(path, ".sh") + ".yaml"
+	} else {
+		spec = path
 	}
-	cmd.Arguments = []*command.Argument{}
-	cmd.Options = command.Options{}
 
-	spec := strings.TrimSuffix(path, ".sh") + ".yaml"
 	var contents []byte
 	if contents, err = os.ReadFile(spec); err == nil {
 		err = yaml.Unmarshal(contents, cmd)

internal/command/meta.go

@@ -3,6 +3,7 @@
 package command
 
 import (
+	"path/filepath"
 	"strings"
 
 	_c "github.com/unrob/milpa/internal/constants"
@@ -31,18 +32,26 @@ type Meta struct {
 }
 
 func metaForPath(path string, repo string) (meta Meta) {
-	meta.Path = path
+	var name string
+	if strings.HasSuffix(path, ".yaml") {
+		name = filepath.Dir(path)
+		name = strings.TrimPrefix(name, repo+"/"+_c.RepoCommandFolderName+"/")
+		meta.Path = name
+		meta.Kind = KindVirtual
+	} else {
+		meta.Path = path
+		name = strings.TrimSuffix(path, ".sh")
+		name = strings.TrimPrefix(name, repo+"/"+_c.RepoCommandFolderName+"/")
+
+		if strings.HasSuffix(path, ".sh") {
+			meta.Kind = KindSource
+		} else {
+			meta.Kind = KindExecutable
+		}
+	}
 	meta.Repo = repo
-	name := strings.TrimSuffix(path, ".sh")
-	name = strings.TrimPrefix(name, repo+"/"+_c.RepoCommandFolderName+"/")
 	meta.Name = strings.Split(name, "/")
 	meta.issues = []error{}
 
-	if strings.HasSuffix(path, ".sh") {
-		meta.Kind = "source"
-	} else {
-		meta.Kind = "exec"
-	}
-
 	return
 }

internal/docs/markdown.go

@@ -235,7 +235,10 @@ func (me *milpaExtension) Extend(m goldmark.Markdown) {
 func commandSerializer(pageTree *Page, names *[]string) func(cmd *command.Command) error {
 	return func(cmd *command.Command) error {
 		current := pageTree
-		path := cmd.Path[1:]
+		path := cmd.Path
+		if path[0] == "milpa" {
+			path = path[1:]
+		}
 		log.Tracef("creating tree for %s, current: %d", path, len(*current.Children))
 		for idx, c := range path {
 			if len(path)-1 == idx {
@@ -244,7 +247,7 @@ func commandSerializer(pageTree *Page, names *[]string) func(cmd *command.Comman
 					Path:     strings.Join(path, "/"),
 					Children: &Pages{},
 				})
-				*names = append(*names, strings.Join(cmd.Path[1:], " "))
+				*names = append(*names, strings.Join(path, " "))
 				log.Tracef("inserted %s at %s (%d)", cmd.Name(), current.Path, len(*current.Children))
 				return nil
 			}

internal/lookup/find.go

@@ -45,6 +45,12 @@ func Scripts(query []string) (results map[string]string, err error) {
 				if extension != ".yaml" {
 					log.Debugf("ignoring /%s, unknown extension", match)
 				}
+
+				if "_"+filepath.Base(filepath.Dir(match))+".yaml" == filepath.Base(match) {
+					log.Debugf("found virtual command description: /%s", match)
+					results["/"+match] = path
+				}
+
 				continue
 			}
 

internal/lookup/find_test.go

@@ -198,6 +198,7 @@ func TestAllSubCommands(t *testing.T) {
 		list = append(list, cmd.FullName())
 	}
 	expected := []string{
+		"itself", // this virtual command is found since it has a defaults set
 		"itself command-tree",
 		"itself create",
 		"itself install-autocomplete",

test/fixtures/index.html

@@ -192,12 +192,12 @@ <h1 lang="es" class="emoji-maiz">milpa</h1>
     <h1 id="command-name-header" class="sr-only">milpa </h1>
     <p>Runs commands found in .milpa folders</p>
 <div class="content-header-wrapper"><h2 class="content-header" id="usage">Usage</h2> <a aria-hidden="true" class="heading-anchor" href="#usage" tabindex="-1">#</a></div><p><code>milpa [--silent|-v|--verbose] [--[no-]color] [-h|--help] [--version] SUBCOMMAND</code></p>
-<div class="content-header-wrapper"><h2 class="content-header" id="description">Description</h2> <a aria-hidden="true" class="heading-anchor" href="#description" tabindex="-1">#</a></div><p><code>milpa</code> is a command-line tool to care for one's own garden of scripts, providing autocomplete, sub-commands, argument parsing and validation, along beautiful documentation—just add a simple YAML spec and a bash (or your language of choice) script.</p>
+<div class="content-header-wrapper"><h2 class="content-header" id="description">Description</h2> <a aria-hidden="true" class="heading-anchor" href="#description" tabindex="-1">#</a></div><p><code>milpa</code> is a command-line tool to care for one's own garden of scripts, providing autocomplete, sub-commands, argument parsing and validation, along beautiful documentation—all it takes is a YAML spec and a script: bash or your language of choice.</p>
 <p>See <a href="/help/docs/milpa/"><code>milpa help docs milpa</code></a> for more information about <code>milpa</code>.</p>
 <div class="content-header-wrapper"><h2 class="content-header" id="subcommands">Subcommands</h2> <a aria-hidden="true" class="heading-anchor" href="#subcommands" tabindex="-1">#</a></div><ul>
 <li><a href="debug-env/"><code>debug-env</code></a> - prints a variable from the environment</li>
 <li><a href="help/"><code>help</code></a> - Display usage information for any command</li>
-<li><a href="itself/"><code>itself</code></a> - itself subcommands</li>
+<li><a href="itself/"><code>itself</code></a> - subcommands that operate on <code>milpa</code>, itself</li>
 </ul>
 <div class="content-header-wrapper"><h2 class="content-header" id="options">Options</h2> <a aria-hidden="true" class="heading-anchor" href="#options" tabindex="-1">#</a></div><ul>
 <li><code>--color</code> (<em>bool</em>): Always print colors to stderr.</li>