add root to command tree, touch up docs (#115)

unRob · web-flow · commit b6b9d4d454c6 · 2023-09-26T01:38:43.000Z
* add root to command tree, touch up docs

* add opengraph image to docs
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,6 +1,12 @@
 blank_issues_enabled: true
-# contact_links:
-#   - name: Twitter
-#     url: https://twitter.com/unRob
-#     about: Got thoughts and a twitter account?
+contact_links:
+  - name: Docs
+    url: https://milpa.dev/
+    about: Documentation on using `milpa`
+  - name: Fediverse
+    url: https://club.pati.to/@rob
+    about: Got thoughts and a twitter account?
+  - name: Twitter
+    url: https://twitter.com/unRob
+    about: Got thoughts and a twitter account?
 
diff --git a/.gitignore b/.gitignore
@@ -3,3 +3,4 @@ compa
 dist
 test/coverage.*
 test/coverage
+!.milpa
diff --git a/.milpa/commands/itself/command-tree.yaml b/.milpa/commands/itself/command-tree.yaml
@@ -1,6 +1,6 @@
 summary: Prints a tree of known commands
 description: |
-  Prints out command names and descriptions, or optionally a nested representation of all properties of commands, serialized as `json` or `yaml`. Custom textual representations of commands can be obtained by using the `--template` option and specifying a [go-template](https://pkg.go.dev/text/template#hdr-Actions) to be applied to every command. See [chinampa/pkg.Command](https://pkg.go.dev/git.rob.mx/nidito/chinampa@v0.0.0-20230324015136-6ec1c56f0fc5/pkg/command#Command) and [milpa/internal/command.Meta](https://pkg.go.dev/github.com/unrob/milpa@v0.0.0-20230321064607-ee1825c67af7/internal/command#Meta) for references on the structs available during template rendering.
+  Prints out command names and descriptions, or optionally a nested representation of all properties of commands, serialized as `json` or `yaml`. Custom textual representations of commands can be obtained by using the `--template` option and specifying a [go-template](https://pkg.go.dev/text/template#hdr-Actions) to be applied to every command. See [chinampa/pkg.Command](https://pkg.go.dev/git.rob.mx/nidito/chinampa/pkg/command#Command) and [milpa/internal/command.Meta](https://pkg.go.dev/github.com/unrob/milpa/internal/command#Meta) for references on the structs available during template rendering.
 
   ## Examples
 
diff --git a/.milpa/docs/milpa/support.md b/.milpa/docs/milpa/support.md
@@ -4,15 +4,11 @@ description: how to deal with bugs in milpa
 weight: 99
 ---
 
-`milpa` is currently alpha software. This means that while I've personally tested it for over a year:
-
-- test coverage is pretty lacking,
-- the command spec and script environment is subject to change, and,
-- there's **no guarantee of stability** of any internal command or utility.
+`milpa` is currently beta software: the tool is mostly feature-complete, but these features are likely to contain bugs, not be properly covered by the test suite nor fully documented. Bug reports, code contributions and general questions are welcome!
 
 ## ℹ️ Requesting help
 
-Please [open a support request](https://github.com/unRob/milpa/issues/new?assignees=&labels=help-requested&template=help-request.yml&title=%5Bhelp%5D%3A+) on github, and I'll do my best to help.
+Please [open a support request](https://github.com/unRob/milpa/issues/new?assignees=&labels=help-requested&template=help-request.yml&title=%5Bhelp%5D%3A+) on Github, and I'll do my best to help.
 
 
 ## 🐛 Reporting bugs
diff --git a/.milpa/docs/milpa/use-case.md b/.milpa/docs/milpa/use-case.md
@@ -22,14 +22,14 @@ My goal with `milpa` is to make following the [Command Line Interface Guidelines
 
 Tasks like bootstrapping development environments are usually left out for the user to accomplish by following through a README or wiki with likely outdated links; `milpa` is great when these tasks can be accomplished by prompting for information, querying identity providers and then running configuration commands or modifying the filesystem directly.
 
-> ⚠️ `milpa` is still under development and is currently on alpha!
+> ⚠️ `milpa` is still under development and is currently on beta!
 
 ### Examples
 
 Here's some examples of how I've used used `milpa` so far:
 
 - for **managing homelab services** (i.e. [unRob/nidito](https://github.com/unRob/nidito/tree/master/.milpa)): building and deploying them, looking at their status and logs. From my personal device or CI.
-- **bootstrapping engineering laptops** (i.e. [unRob/dotfiles](https://github.com/unRob/dotfiles/tree/master/.milpa/commands/computar)): no need to follow a README, you get the right development environment for your os/arch, your credentials setup and the code ready for you to dive in.
+- **bootstrapping workstations** (i.e. [unRob/dotfiles](https://github.com/unRob/dotfiles/tree/master/.milpa/commands/computar)): no need to follow a README, you get the right development environment for your os/arch, your credentials setup and the code ready for you to dive in.
 - **every-day dev workflow** (i.e. [unRob/milpa](https://github.com/unRob/milpa/tree/main/repos/internal/commands/)): lint and test a codebase, connect to vpn, get credentials to resources, maybe `--connect` to them, abstract away APIs (internal, cloud provider and SaaS) and CLIs, toggle feature gates, build reports and update google sheets with the results.
 - as a way to organize all those odd, one-off-but-not-really commands: found a nice home for [shell scripts](https://github.com/unRob/dotfiles/blob/master/.milpa/commands/code/todo.sh), quick ruby scripts, perl hacks and [jq monstrosities](https://github.com/unRob/dotfiles/blob/master/.milpa/commands/creds.sh) that used to live in my `~/.zsh_history`.
 
@@ -77,7 +77,7 @@ That being said, organizing makefiles and dealing with arguments is not somethin
 
 ### BYOCLI
 
-Building your own CLI is usually what ends up happening given a team with enough time and direction to invest in building a proper CLI with whatever language is already at use. Some teams use more than one language, which may complicate this approach. In the microservices world, many codebases come with their own CLIs that may follow slightly different conventions, are seldomly documented and often just end up calling other binaries through `exec`.
+Building your own CLI is usually what ends up happening given a team with enough time and direction to invest in building a proper CLI with whatever language is already at use. Some teams use more than one language, which may complicate this approach. In the micro-services world, many codebases come with their own CLIs that may follow slightly different conventions, are seldomly documented and often just end up calling other binaries through `exec`.
 
 In my limited experience with engineering teams of less than 300 folks, many of the bootstrapping tasks will involve operations that can easily (and more succinctly) be expressed with a shell scripting language. `milpa` could also be a useful intermediate step, that could help teams avoid the dread of confluence/notion/google-docs runbooks until it's a good time to build your own CLI.
 
diff --git a/README.md b/README.md
@@ -7,6 +7,8 @@ For a brief introductory tutorial, check out [`milpa help docs milpa quick-guide
 ```sh
 # install on mac and linux with:
 curl -L https://milpa.dev/install.sh | bash -
+# or with homebrew
+brew install unRob/formulas/milpa
 ```
 
 You and your team write scripts and a little spec for each of them—use bash, or any other language—, and `milpa` provides:
diff --git a/go.mod b/go.mod
@@ -3,7 +3,7 @@ module github.com/unrob/milpa
 go 1.20
 
 require (
-	git.rob.mx/nidito/chinampa v0.1.3
+	git.rob.mx/nidito/chinampa v0.1.4
 	github.com/alecthomas/chroma/v2 v2.9.1
 	github.com/alessio/shellescape v1.4.2
 	github.com/bmatcuk/doublestar/v4 v4.6.0
diff --git a/go.sum b/go.sum
@@ -1,5 +1,5 @@
-git.rob.mx/nidito/chinampa v0.1.3 h1:ZzOZLHZo5g0xKpWW0PM6MrX1dnvzYEQB2V7JZgwTstc=
-git.rob.mx/nidito/chinampa v0.1.3/go.mod h1:isI138ZQ3GN/ZcuRrNPJ48fYnPC+U642gUe5bonhwUo=
+git.rob.mx/nidito/chinampa v0.1.4 h1:rXmtuwYNtBmpLgWnNK7b5Z/styyuFfCP3RqL+qOzlok=
+git.rob.mx/nidito/chinampa v0.1.4/go.mod h1:isI138ZQ3GN/ZcuRrNPJ48fYnPC+U642gUe5bonhwUo=
 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=
diff --git a/internal/actions/command_tree.go b/internal/actions/command_tree.go
@@ -33,6 +33,9 @@ func addMetaToTree(t *tree.CommandTree) {
 			Kind: milpaCmd.KindVirtual,
 		}
 		t.Command.Meta = &meta
+		if t.Command.Path[0] != "milpa" {
+			t.Command.Path = append([]string{"milpa"}, t.Command.Path...)
+		}
 	}
 
 	for _, subT := range t.Children {
@@ -130,6 +133,9 @@ var CommandTree = &command.Command{
 				tree := t.(*tree.CommandTree)
 				addMetaToTree(tree)
 				var output bytes.Buffer
+				if err := tpl.Execute(&output, tree.Command); err != nil {
+					return output.Bytes(), err
+				}
 				err := tree.Traverse(func(cmd *command.Command) error { return tpl.Execute(&output, cmd) })
 				return output.Bytes(), err
 			}
diff --git a/internal/command/meta.go b/internal/command/meta.go
@@ -35,20 +35,23 @@ func metaForPath(path string, repo string) (meta Meta) {
 	var name string
 	if strings.HasSuffix(path, ".yaml") {
 		name = filepath.Dir(path)
-		name = strings.TrimPrefix(name, repo+"/"+_c.RepoCommandFolderName+"/")
+		name = strings.TrimPrefix(name, repo+"/")
+		name = strings.TrimPrefix(name, _c.RepoCommandFolderName+"/")
 		meta.Path = name
 		meta.Kind = KindVirtual
 	} else {
 		meta.Path = path
 		name = strings.TrimSuffix(path, ".sh")
-		name = strings.TrimPrefix(name, repo+"/"+_c.RepoCommandFolderName+"/")
+		name = strings.TrimPrefix(name, repo+"/")
+		name = strings.TrimPrefix(name, _c.RepoCommandFolderName+"/")
 
 		if strings.HasSuffix(path, ".sh") {
 			meta.Kind = KindSource
 		} else {
 			meta.Kind = KindExecutable
 		}
 	}
+
 	meta.Repo = repo
 	meta.Name = strings.Split(name, "/")
 	meta.issues = []error{}
diff --git a/internal/docs/static/ogp.jpg b/internal/docs/static/ogp.jpg
diff --git a/internal/docs/template.html b/internal/docs/template.html
@@ -24,6 +24,7 @@
   <meta property="og:description" content="{{ $description }}" />
   <meta name="description" content="{{ $description }}" />
   <meta property="og:url" content="{{ .Permalink }}" />
+  <meta property="og:image" content="{{ .Base }}/ogp.jpg" />
   <link rel="icon" href="/static/favicon.ico" type="image/x-icon" />
   <title>milpa{{ if not .IsHome }} {{ if not $is404 }}{{ $commandName }}{{else}}Not Found{{end}}{{end}}</title>
 
diff --git a/test/fixtures/docs.html b/test/fixtures/docs.html
@@ -10,6 +10,7 @@
   <meta property="og:description" content="Displays docs on TOPIC" />
   <meta name="description" content="Displays docs on TOPIC" />
   <meta property="og:url" content="http://localhost:4242/help/docs" />
+  <meta property="og:image" content="http://localhost:4242/ogp.jpg" />
   <link rel="icon" href="/static/favicon.ico" type="image/x-icon" />
   <title>milpa help docs</title>
 
diff --git a/test/fixtures/environment.html b/test/fixtures/environment.html
@@ -10,6 +10,7 @@
   <meta property="og:description" content="An overview of all milpa environment variables" />
   <meta name="description" content="An overview of all milpa environment variables" />
   <meta property="og:url" content="http://localhost:4242/help/docs/milpa/environment" />
+  <meta property="og:image" content="http://localhost:4242/ogp.jpg" />
   <link rel="icon" href="/static/favicon.ico" type="image/x-icon" />
   <title>milpa help docs milpa environment</title>
 
diff --git a/test/fixtures/index.html b/test/fixtures/index.html
@@ -10,6 +10,7 @@
   <meta property="og:description" content="A tool to care for one&#39;s own garden of scripts" />
   <meta name="description" content="A tool to care for one&#39;s own garden of scripts" />
   <meta property="og:url" content="http://localhost:4242/" />
+  <meta property="og:image" content="http://localhost:4242/ogp.jpg" />
   <link rel="icon" href="/static/favicon.ico" type="image/x-icon" />
   <title>milpa</title>
 
diff --git a/test/fixtures/readme.html b/test/fixtures/readme.html
@@ -10,6 +10,7 @@
   <meta property="og:description" content="Displays docs on TOPIC" />
   <meta name="description" content="Displays docs on TOPIC" />
   <meta property="og:url" content="http://localhost:4242/help/docs/milpa" />
+  <meta property="og:image" content="http://localhost:4242/ogp.jpg" />
   <link rel="icon" href="/static/favicon.ico" type="image/x-icon" />
   <title>milpa help docs milpa</title>
 
@@ -193,6 +194,8 @@ <h1 id="command-name-header" class="sr-only">milpa help docs milpa</h1>
 <p>For a brief introductory tutorial, check out <a href="/help/docs/milpa/quick-guide/"><code>milpa help docs milpa quick-guide</code></a>.</p>
 <pre class="chroma"><code><span class="line"><span class="cl"><span class="c1"># install on mac and linux with:</span>
 </span></span><span class="line"><span class="cl">curl -L https://milpa.dev/install.sh <span class="p">|</span> bash -
+</span></span><span class="line"><span class="cl"><span class="c1"># or with homebrew</span>
+</span></span><span class="line"><span class="cl">brew install unRob/formulas/milpa
 </span></span></code></pre><p>You and your team write scripts and a little spec for each of them—use bash, or any other language—, and <code>milpa</code> provides:</p>
 <ul>
 <li>argument and option <strong>completions</strong> from static sources, files and directories, other <code>milpa</code> scripts or even other programs;</li>
diff --git a/test/fixtures/readme.txt b/test/fixtures/readme.txt
@@ -7,6 +7,8 @@ For a brief introductory tutorial, check out [`milpa help docs milpa quick-guide
 ```sh
 # install on mac and linux with:
 curl -L https://milpa.dev/install.sh | bash -
+# or with homebrew
+brew install unRob/formulas/milpa
 ```
 
 You and your team write scripts and a little spec for each of them—use bash, or any other language—, and `milpa` provides:

Original file line number	Diff line number	Diff line change
`@@ -33,6 +33,9 @@ func addMetaToTree(t *tree.CommandTree) {`
`33`	`33`	`Kind: milpaCmd.KindVirtual,`
`34`	`34`	`}`
`35`	`35`	`t.Command.Meta = &meta`
	`36`	`+ if t.Command.Path[0] != "milpa" {`
	`37`	`+ t.Command.Path = append([]string{"milpa"}, t.Command.Path...)`
	`38`	`+ }`
`36`	`39`	`}`
`37`	`40`
`38`	`41`	`for _, subT := range t.Children {`
`@@ -130,6 +133,9 @@ var CommandTree = &command.Command{`
`130`	`133`	`tree := t.(*tree.CommandTree)`
`131`	`134`	`addMetaToTree(tree)`
`132`	`135`	`var output bytes.Buffer`
	`136`	`+ if err := tpl.Execute(&output, tree.Command); err != nil {`
	`137`	`+ return output.Bytes(), err`
	`138`	`+ }`
`133`	`139`	`err := tree.Traverse(func(cmd *command.Command) error { return tpl.Execute(&output, cmd) })`
`134`	`140`	`return output.Bytes(), err`
`135`	`141`	`}`