beads/cmd/bd/help_all.go
matt wilkie b2a4d1d04a
docs: generate CLI reference from live help (#3704)
* docs: generate CLI reference from live help

* docs(cli): move bd version stamp from per-command pages to index only

Drops the `(bd version X.Y.Z)` suffix from the auto-generated header on
every per-command CLI reference page (writeSingleCommandDoc) and the
docs/CLI_REFERENCE.md preamble (writeAllHelp). The version label now
lives only on the index page emitted by scripts/generate-cli-docs.sh:

- Dev tree (website/docs/cli-reference/index.md, docs/CLI_REFERENCE.md):
  labelled "Latest"
- Versioned snapshots (website/versioned_docs/version-X.Y.Z/...):
  labelled with the explicit semver tag parsed from the directory name

This eliminates the 100+-file no-signal diff a release version bump
otherwise produces, restoring the "regen as a separate small commit"
workflow PR #3704 enables. After this change a version bump alone
yields zero diff on the dev tree; only the new versioned snapshot
created at release-cut time carries the new tag. No datestamps are
introduced anywhere — scripts/generate-cli-docs.sh --check remains
deterministic across CI runs.

Refs: mybd-afb, PR #3704

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-05 19:43:49 -07:00

374 lines
9.8 KiB
Go

package main
import (
"errors"
"fmt"
"io"
"os"
"sort"
"strings"
"unicode"
"github.com/spf13/cobra"
)
// helpAllFlag is the --all flag for the help command
var helpAllFlag bool
// helpDocFlag is the --doc flag for generating single command docs
var helpDocFlag string
// helpListFlag is the --list flag for listing available commands
var helpListFlag bool
// registerHelpAllFlag adds the --all, --doc, and --list flags to Cobra's auto-generated help command.
// Must be called after rootCmd.InitDefaultHelpCmd() has run (i.e., after first Execute
// or explicit init). We hook it in init() after all subcommands are registered.
func registerHelpAllFlag() {
// Cobra lazily creates the help command. We need to find it.
for _, cmd := range rootCmd.Commands() {
if cmd.Name() == "help" {
if cmd.Flags().Lookup("all") != nil {
return
}
cmd.Flags().BoolVar(&helpAllFlag, "all", false, "Show help for all commands in a single document")
cmd.Flags().StringVar(&helpDocFlag, "doc", "", "Generate markdown docs for a single command")
cmd.Flags().BoolVar(&helpListFlag, "list", false, "List all available commands")
// Wrap the existing Run to check --all, --doc, and --list first
originalRun := cmd.Run
cmd.Run = func(cmd *cobra.Command, args []string) {
if helpListFlag {
// Handle --list flag: list all available commands
listAllCommands(os.Stdout, rootCmd)
return
}
if helpDocFlag != "" {
// Handle --doc flag: generate single command docs
cmdPath := helpDocFlag
if len(args) > 0 {
cmdPath = strings.Join(append([]string{helpDocFlag}, args...), " ")
}
if err := writeSingleCommandDoc(os.Stdout, rootCmd, cmdPath); err != nil {
fmt.Fprintln(os.Stderr, err)
fmt.Fprintf(os.Stderr, "Available commands: %s\n", strings.Join(availableCommandNames(rootCmd), " "))
os.Exit(1)
}
return
}
if helpAllFlag {
writeAllHelp(os.Stdout, rootCmd)
return
}
if originalRun != nil {
originalRun(cmd, args)
}
}
return
}
}
}
// writeAllHelp writes a complete markdown reference for all commands,
// generated from the live Cobra command tree.
func writeAllHelp(w io.Writer, root *cobra.Command) {
fmt.Fprintf(w, "# bd — Complete Command Reference\n\n")
fmt.Fprintf(w, "Reference for bd Latest. Generated from `bd help --all`.\n\n")
// Collect commands grouped by their GroupID
type group struct {
title string
commands []*cobra.Command
}
// Build ordered group list from root's groups
groups := root.Groups()
groupMap := make(map[string]*group, len(groups))
var orderedGroups []*group
for _, g := range groups {
grp := &group{title: g.Title}
groupMap[g.ID] = grp
orderedGroups = append(orderedGroups, grp)
}
// Ungrouped commands (if any)
var ungrouped []*group
for _, cmd := range root.Commands() {
if !cmd.IsAvailableCommand() && cmd.Name() != "help" {
continue
}
if gid := cmd.GroupID; gid != "" {
if grp, ok := groupMap[gid]; ok {
grp.commands = append(grp.commands, cmd)
}
} else {
// Ungrouped
if len(ungrouped) == 0 {
ungrouped = append(ungrouped, &group{title: "Other Commands:"})
}
ungrouped[0].commands = append(ungrouped[0].commands, cmd)
}
}
// Table of contents
fmt.Fprintf(w, "## Table of Contents\n\n")
allGroups := append(orderedGroups, ungrouped...)
for _, grp := range allGroups {
if len(grp.commands) == 0 {
continue
}
fmt.Fprintf(w, "### %s\n\n", grp.title)
for _, cmd := range grp.commands {
anchor := "bd-" + strings.ReplaceAll(cmd.Name(), "-", "-")
fmt.Fprintf(w, "- [bd %s](#%s) — %s\n", cmd.Name(), anchor, escapeMDXText(cmd.Short))
// Include subcommands in TOC
for _, sub := range cmd.Commands() {
if !sub.IsAvailableCommand() {
continue
}
subAnchor := "bd-" + cmd.Name() + "-" + strings.ReplaceAll(sub.Name(), "-", "-")
fmt.Fprintf(w, " - [bd %s %s](#%s) — %s\n", cmd.Name(), sub.Name(), subAnchor, escapeMDXText(sub.Short))
}
}
fmt.Fprintf(w, "\n")
}
// Global flags (once)
fmt.Fprintf(w, "---\n\n## Global Flags\n\n")
fmt.Fprintf(w, "These flags apply to all commands:\n\n")
fmt.Fprintf(w, "```\n")
fmt.Fprintf(w, "%s", root.PersistentFlags().FlagUsages())
fmt.Fprintf(w, "```\n\n")
// Command details
fmt.Fprintf(w, "---\n\n")
for _, grp := range allGroups {
if len(grp.commands) == 0 {
continue
}
fmt.Fprintf(w, "## %s\n\n", grp.title)
for _, cmd := range grp.commands {
writeCommandHelp(w, cmd, "bd", 3)
}
}
}
// writeCommandHelp writes markdown help for a single command and its subcommands.
func writeCommandHelp(w io.Writer, cmd *cobra.Command, parentPath string, depth int) {
fullPath := parentPath + " " + cmd.Name()
heading := strings.Repeat("#", depth)
fmt.Fprintf(w, "%s %s\n\n", heading, fullPath)
// Description
if cmd.Long != "" {
fmt.Fprintf(w, "%s\n\n", escapeMDXText(cmd.Long))
} else if cmd.Short != "" {
fmt.Fprintf(w, "%s\n\n", escapeMDXText(cmd.Short))
}
// Usage
fmt.Fprintf(w, "```\n%s\n```\n\n", strings.TrimRight(cmd.UseLine(), " "))
// Aliases
if len(cmd.Aliases) > 0 {
fmt.Fprintf(w, "**Aliases:** %s\n\n", strings.Join(cmd.Aliases, ", "))
}
// Examples
if cmd.Example != "" {
fmt.Fprintf(w, "**Examples:**\n\n```bash\n%s\n```\n\n", cmd.Example)
}
// Local flags (not inherited/global)
localFlags := cmd.NonInheritedFlags()
if localFlags.HasFlags() {
fmt.Fprintf(w, "**Flags:**\n\n```\n%s```\n\n", localFlags.FlagUsages())
}
// Subcommands
subCmds := cmd.Commands()
hasVisibleSubs := false
for _, sub := range subCmds {
if sub.IsAvailableCommand() {
hasVisibleSubs = true
break
}
}
if hasVisibleSubs {
for _, sub := range subCmds {
if !sub.IsAvailableCommand() {
continue
}
writeCommandHelp(w, sub, fullPath, depth+1)
}
}
}
// sidebarPositionMap maps command names to their Docusaurus sidebar position
// This controls the ordering of commands in the website sidebar.
var sidebarPositionMap = map[string]int{
"create": 10,
"list": 20,
"ready": 30,
"show": 40,
"update": 50,
"close": 60,
"delete": 70,
"reopen": 80,
"dep": 100,
"label": 110,
"state": 120,
"sync": 200,
"import": 210,
"export": 220,
"mol": 300,
"formula": 310,
"init": 400,
"setup": 410,
"config": 420,
"prime": 500,
"doctor": 600,
"admin": 610,
"migrate": 620,
}
// writeSingleCommandDoc generates markdown documentation for a single command
// with Docusaurus frontmatter for website integration.
func writeSingleCommandDoc(w io.Writer, root *cobra.Command, cmdName string) error {
// Find the command (handle nested commands like "mol pour")
cmd := findCommand(root, cmdName)
if cmd == nil {
return fmt.Errorf("Error: command not found: %s", cmdName)
}
docCommand := strings.TrimSpace(strings.TrimPrefix(commandPath(cmd), root.Name()))
docCommand = strings.TrimSpace(docCommand)
if docCommand == "" {
return errors.New("Error: cannot generate docs for root command")
}
docID := commandDocID(docCommand)
// Get sidebar position (default to 999 if not in map)
position := 999
if pos, ok := sidebarPositionMap[docCommand]; ok {
position = pos
}
// Generate Docusaurus frontmatter
fmt.Fprintf(w, "---\n")
fmt.Fprintf(w, "id: %s\n", docID)
fmt.Fprintf(w, "title: bd %s\n", docCommand)
fmt.Fprintf(w, "slug: /cli-reference/%s\n", docID)
fmt.Fprintf(w, "sidebar_position: %d\n", position)
fmt.Fprintf(w, "---\n")
fmt.Fprintf(w, "\n")
fmt.Fprintf(w, "<!-- AUTO-GENERATED: do not edit manually -->\n")
fmt.Fprintf(w, "Generated from `bd help --doc %s`\n\n", docCommand)
// Generate the command help (using h2 for single command)
parentPath := strings.TrimSuffix(commandPath(cmd), " "+cmd.Name())
writeCommandHelp(w, cmd, parentPath, 2)
return nil
}
// findCommand finds a command by name in the command tree.
// Supports nested commands like "mol pour" by splitting on space.
func findCommand(root *cobra.Command, name string) *cobra.Command {
// Handle nested commands (e.g., "mol pour")
parts := strings.Split(name, " ")
var current *cobra.Command
for i, part := range parts {
if i == 0 {
// Start from root's direct commands
current = findDirectCommand(root, part)
} else {
// Look in subcommands of current
if current != nil {
current = findDirectCommand(current, part)
}
}
if current == nil {
return nil
}
}
return current
}
// findDirectCommand finds a direct child command by name.
func findDirectCommand(parent *cobra.Command, name string) *cobra.Command {
for _, cmd := range parent.Commands() {
if cmd.Name() == name {
return cmd
}
// Also check aliases
for _, alias := range cmd.Aliases {
if alias == name {
return cmd
}
}
}
return nil
}
// listAllCommands prints all available commands, one per line.
// Used by the generate-cli-docs.sh script.
func listAllCommands(w io.Writer, root *cobra.Command) {
for _, name := range availableCommandNames(root) {
fmt.Fprintln(w, name)
}
}
func availableCommandNames(root *cobra.Command) []string {
names := make([]string, 0, len(root.Commands()))
for _, cmd := range root.Commands() {
if cmd.IsAvailableCommand() {
names = append(names, cmd.Name())
}
}
sort.Strings(names)
return names
}
func commandPath(cmd *cobra.Command) string {
path := cmd.CommandPath()
if path == "" {
return cmd.Name()
}
return path
}
func commandDocID(commandPath string) string {
var b strings.Builder
lastDash := false
for _, r := range strings.ToLower(commandPath) {
if unicode.IsLetter(r) || unicode.IsDigit(r) {
b.WriteRune(r)
lastDash = false
continue
}
if !lastDash {
b.WriteByte('-')
lastDash = true
}
}
id := strings.Trim(b.String(), "-")
if id == "" {
return "command"
}
return id
}
func escapeMDXText(s string) string {
replacer := strings.NewReplacer(
"&", "&amp;",
"<", "&lt;",
">", "&gt;",
"{", "&#123;",
"}", "&#125;",
)
return replacer.Replace(s)
}