From 4ea6fa3ac01ca7bda10f7b7317eea7f073643591 Mon Sep 17 00:00:00 2001 From: Chris Sells Date: Fri, 10 Jul 2026 17:52:08 -0700 Subject: [PATCH] docs(emitter): emit Mintlify CLI reference and generated docs.json nav MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit bd help --docs-root now additionally writes docs/cli-reference/ in Mintlify form (frontmatter title as H1, extensionless root-relative links, JSX auto-generated markers since Mintlify parses .md through MDX) and rewrites the CLI Reference pages array inside docs/docs.json via a textual splice that leaves the rest of the file byte-identical — the ~113 nav entries are never hand-maintained. The Docusaurus outputs (docs/CLI_REFERENCE.md, website/docs/cli-reference/, versioned snapshots) are unchanged. generate-cli-docs.sh --check seeds docs/docs.json and docs/cli-reference/ into its scratch root and diffs both; check-cli-docs-drift.sh adds them to GEN_PATHSPECS and the regeneration fingerprint; docs-autofix-push.sh allowlists the new generated paths; check-doc-flags.sh scans the new docs/ subdirectories and requires command coverage in docs/cli-reference/. Includes the initial docs/docs.json scaffold (nav mirrors the Docusaurus sidebar IA) and the generated docs/cli-reference/ pages. TDD: new emitter behavior covered in cmd/bd/help_all_test.go (Mintlify page format, nav splice correctness + idempotence, bare-root generation without docs.json). --- cmd/bd/help_all.go | 215 ++++++++- cmd/bd/help_all_test.go | 166 +++++++ docs/cli-reference/admin.md | 158 ++++++ docs/cli-reference/ado.md | 115 +++++ docs/cli-reference/assign.md | 20 + docs/cli-reference/audit.md | 57 +++ docs/cli-reference/backup.md | 115 +++++ docs/cli-reference/batch.md | 62 +++ docs/cli-reference/blocked.md | 20 + docs/cli-reference/bootstrap.md | 47 ++ docs/cli-reference/branch.md | 21 + docs/cli-reference/children.md | 29 ++ docs/cli-reference/close.md | 37 ++ docs/cli-reference/comment.md | 29 ++ docs/cli-reference/comments.md | 63 +++ docs/cli-reference/compact.md | 42 ++ docs/cli-reference/completion.md | 133 +++++ docs/cli-reference/config.md | 243 ++++++++++ docs/cli-reference/context.md | 23 + docs/cli-reference/cook.md | 72 +++ docs/cli-reference/count.md | 62 +++ docs/cli-reference/create-form.md | 32 ++ docs/cli-reference/create.md | 64 +++ docs/cli-reference/defer.md | 34 ++ docs/cli-reference/delete.md | 49 ++ docs/cli-reference/dep.md | 183 +++++++ docs/cli-reference/diff.md | 24 + docs/cli-reference/doctor.md | 150 ++++++ docs/cli-reference/dolt.md | 301 ++++++++++++ docs/cli-reference/duplicate.md | 26 + docs/cli-reference/duplicates.md | 30 ++ docs/cli-reference/edit.md | 33 ++ docs/cli-reference/epic.md | 42 ++ docs/cli-reference/export.md | 49 ++ docs/cli-reference/federation.md | 21 + docs/cli-reference/find-duplicates.md | 50 ++ docs/cli-reference/flatten.md | 41 ++ docs/cli-reference/forget.md | 20 + docs/cli-reference/formula.md | 144 ++++++ docs/cli-reference/gate.md | 204 ++++++++ docs/cli-reference/gc.md | 40 ++ docs/cli-reference/github.md | 98 ++++ docs/cli-reference/gitlab.md | 105 ++++ docs/cli-reference/graph.md | 61 +++ docs/cli-reference/heartbeat.md | 31 ++ docs/cli-reference/history.md | 25 + docs/cli-reference/hooks.md | 88 ++++ docs/cli-reference/human.md | 100 ++++ docs/cli-reference/import.md | 84 ++++ docs/cli-reference/index.md | 129 +++++ docs/cli-reference/info.md | 37 ++ docs/cli-reference/init-safety.md | 80 +++ docs/cli-reference/init.md | 101 ++++ docs/cli-reference/jira.md | 120 +++++ docs/cli-reference/kv.md | 75 +++ docs/cli-reference/label.md | 54 +++ docs/cli-reference/linear.md | 223 +++++++++ docs/cli-reference/link.md | 28 ++ docs/cli-reference/lint.md | 38 ++ docs/cli-reference/list.md | 77 +++ docs/cli-reference/mail.md | 33 ++ docs/cli-reference/memories.md | 19 + docs/cli-reference/merge-slot.md | 96 ++++ docs/cli-reference/metrics.md | 49 ++ docs/cli-reference/migrate-personal.md | 33 ++ docs/cli-reference/migrate.md | 156 ++++++ docs/cli-reference/mol.md | 616 ++++++++++++++++++++++++ docs/cli-reference/note.md | 29 ++ docs/cli-reference/notion.md | 109 +++++ docs/cli-reference/onboard.md | 28 ++ docs/cli-reference/orphans.md | 33 ++ docs/cli-reference/ping.md | 26 + docs/cli-reference/preflight.md | 38 ++ docs/cli-reference/prime.md | 60 +++ docs/cli-reference/priority.md | 27 ++ docs/cli-reference/promote.md | 30 ++ docs/cli-reference/prune.md | 54 +++ docs/cli-reference/purge.md | 42 ++ docs/cli-reference/q.md | 30 ++ docs/cli-reference/query.md | 82 ++++ docs/cli-reference/quickstart.md | 14 + docs/cli-reference/ready.md | 58 +++ docs/cli-reference/recall.md | 18 + docs/cli-reference/reclaim.md | 37 ++ docs/cli-reference/recompute-blocked.md | 30 ++ docs/cli-reference/remember.md | 34 ++ docs/cli-reference/rename-prefix.md | 47 ++ docs/cli-reference/rename.md | 26 + docs/cli-reference/reopen.md | 21 + docs/cli-reference/repo.md | 110 +++++ docs/cli-reference/restore.md | 33 ++ docs/cli-reference/rules.md | 46 ++ docs/cli-reference/search.md | 63 +++ docs/cli-reference/set-state.md | 37 ++ docs/cli-reference/setup.md | 48 ++ docs/cli-reference/ship.md | 37 ++ docs/cli-reference/show.md | 33 ++ docs/cli-reference/sql.md | 34 ++ docs/cli-reference/stale.md | 26 + docs/cli-reference/state.md | 43 ++ docs/cli-reference/status.md | 44 ++ docs/cli-reference/statuses.md | 32 ++ docs/cli-reference/supersede.md | 26 + docs/cli-reference/swarm.md | 121 +++++ docs/cli-reference/tag.md | 20 + docs/cli-reference/todo.md | 65 +++ docs/cli-reference/types.md | 29 ++ docs/cli-reference/unclaim.md | 28 ++ docs/cli-reference/undefer.md | 21 + docs/cli-reference/update.md | 55 +++ docs/cli-reference/upgrade.md | 73 +++ docs/cli-reference/vc.md | 73 +++ docs/cli-reference/version.md | 14 + docs/cli-reference/where.md | 22 + docs/cli-reference/worktree.md | 114 +++++ docs/docs.json | 263 ++++++++++ scripts/check-cli-docs-drift.sh | 18 +- scripts/check-doc-flags.sh | 5 +- scripts/docs-autofix-push.sh | 2 + scripts/generate-cli-docs.sh | 22 +- 120 files changed, 8223 insertions(+), 29 deletions(-) create mode 100644 docs/cli-reference/admin.md create mode 100644 docs/cli-reference/ado.md create mode 100644 docs/cli-reference/assign.md create mode 100644 docs/cli-reference/audit.md create mode 100644 docs/cli-reference/backup.md create mode 100644 docs/cli-reference/batch.md create mode 100644 docs/cli-reference/blocked.md create mode 100644 docs/cli-reference/bootstrap.md create mode 100644 docs/cli-reference/branch.md create mode 100644 docs/cli-reference/children.md create mode 100644 docs/cli-reference/close.md create mode 100644 docs/cli-reference/comment.md create mode 100644 docs/cli-reference/comments.md create mode 100644 docs/cli-reference/compact.md create mode 100644 docs/cli-reference/completion.md create mode 100644 docs/cli-reference/config.md create mode 100644 docs/cli-reference/context.md create mode 100644 docs/cli-reference/cook.md create mode 100644 docs/cli-reference/count.md create mode 100644 docs/cli-reference/create-form.md create mode 100644 docs/cli-reference/create.md create mode 100644 docs/cli-reference/defer.md create mode 100644 docs/cli-reference/delete.md create mode 100644 docs/cli-reference/dep.md create mode 100644 docs/cli-reference/diff.md create mode 100644 docs/cli-reference/doctor.md create mode 100644 docs/cli-reference/dolt.md create mode 100644 docs/cli-reference/duplicate.md create mode 100644 docs/cli-reference/duplicates.md create mode 100644 docs/cli-reference/edit.md create mode 100644 docs/cli-reference/epic.md create mode 100644 docs/cli-reference/export.md create mode 100644 docs/cli-reference/federation.md create mode 100644 docs/cli-reference/find-duplicates.md create mode 100644 docs/cli-reference/flatten.md create mode 100644 docs/cli-reference/forget.md create mode 100644 docs/cli-reference/formula.md create mode 100644 docs/cli-reference/gate.md create mode 100644 docs/cli-reference/gc.md create mode 100644 docs/cli-reference/github.md create mode 100644 docs/cli-reference/gitlab.md create mode 100644 docs/cli-reference/graph.md create mode 100644 docs/cli-reference/heartbeat.md create mode 100644 docs/cli-reference/history.md create mode 100644 docs/cli-reference/hooks.md create mode 100644 docs/cli-reference/human.md create mode 100644 docs/cli-reference/import.md create mode 100644 docs/cli-reference/index.md create mode 100644 docs/cli-reference/info.md create mode 100644 docs/cli-reference/init-safety.md create mode 100644 docs/cli-reference/init.md create mode 100644 docs/cli-reference/jira.md create mode 100644 docs/cli-reference/kv.md create mode 100644 docs/cli-reference/label.md create mode 100644 docs/cli-reference/linear.md create mode 100644 docs/cli-reference/link.md create mode 100644 docs/cli-reference/lint.md create mode 100644 docs/cli-reference/list.md create mode 100644 docs/cli-reference/mail.md create mode 100644 docs/cli-reference/memories.md create mode 100644 docs/cli-reference/merge-slot.md create mode 100644 docs/cli-reference/metrics.md create mode 100644 docs/cli-reference/migrate-personal.md create mode 100644 docs/cli-reference/migrate.md create mode 100644 docs/cli-reference/mol.md create mode 100644 docs/cli-reference/note.md create mode 100644 docs/cli-reference/notion.md create mode 100644 docs/cli-reference/onboard.md create mode 100644 docs/cli-reference/orphans.md create mode 100644 docs/cli-reference/ping.md create mode 100644 docs/cli-reference/preflight.md create mode 100644 docs/cli-reference/prime.md create mode 100644 docs/cli-reference/priority.md create mode 100644 docs/cli-reference/promote.md create mode 100644 docs/cli-reference/prune.md create mode 100644 docs/cli-reference/purge.md create mode 100644 docs/cli-reference/q.md create mode 100644 docs/cli-reference/query.md create mode 100644 docs/cli-reference/quickstart.md create mode 100644 docs/cli-reference/ready.md create mode 100644 docs/cli-reference/recall.md create mode 100644 docs/cli-reference/reclaim.md create mode 100644 docs/cli-reference/recompute-blocked.md create mode 100644 docs/cli-reference/remember.md create mode 100644 docs/cli-reference/rename-prefix.md create mode 100644 docs/cli-reference/rename.md create mode 100644 docs/cli-reference/reopen.md create mode 100644 docs/cli-reference/repo.md create mode 100644 docs/cli-reference/restore.md create mode 100644 docs/cli-reference/rules.md create mode 100644 docs/cli-reference/search.md create mode 100644 docs/cli-reference/set-state.md create mode 100644 docs/cli-reference/setup.md create mode 100644 docs/cli-reference/ship.md create mode 100644 docs/cli-reference/show.md create mode 100644 docs/cli-reference/sql.md create mode 100644 docs/cli-reference/stale.md create mode 100644 docs/cli-reference/state.md create mode 100644 docs/cli-reference/status.md create mode 100644 docs/cli-reference/statuses.md create mode 100644 docs/cli-reference/supersede.md create mode 100644 docs/cli-reference/swarm.md create mode 100644 docs/cli-reference/tag.md create mode 100644 docs/cli-reference/todo.md create mode 100644 docs/cli-reference/types.md create mode 100644 docs/cli-reference/unclaim.md create mode 100644 docs/cli-reference/undefer.md create mode 100644 docs/cli-reference/update.md create mode 100644 docs/cli-reference/upgrade.md create mode 100644 docs/cli-reference/vc.md create mode 100644 docs/cli-reference/version.md create mode 100644 docs/cli-reference/where.md create mode 100644 docs/cli-reference/worktree.md create mode 100644 docs/docs.json diff --git a/cmd/bd/help_all.go b/cmd/bd/help_all.go index b65d88586..9a68d28bb 100644 --- a/cmd/bd/help_all.go +++ b/cmd/bd/help_all.go @@ -182,6 +182,31 @@ func writeCommandHelp(w io.Writer, cmd *cobra.Command, parentPath string, depth fmt.Fprintf(w, "%s %s\n\n", heading, fullPath) + writeCommandBody(w, cmd) + + // 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) + } + } +} + +// writeCommandBody writes the heading-independent parts of a command's help: +// description, usage, aliases, examples, and local flags. +func writeCommandBody(w io.Writer, cmd *cobra.Command) { // Description if cmd.Long != "" { fmt.Fprintf(w, "%s\n\n", escapeMDXText(cmd.Long)) @@ -207,25 +232,6 @@ func writeCommandHelp(w io.Writer, cmd *cobra.Command, parentPath string, depth 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 @@ -308,6 +314,25 @@ func writeGeneratedCLIDocs(root *cobra.Command, repoRoot, docsVersion string) er return err } + if err := writeMintlifyCLIReferenceDir(filepath.Join(repoRoot, "docs", "cli-reference"), root); err != nil { + return err + } + + // The Mintlify site's navigation lists every CLI page explicitly; those + // entries are generated here, never hand-maintained. Roots without a + // docs.json (bare output roots, --check scratch dirs before the copy) + // simply get the pages. + docsJSONPath := filepath.Join(repoRoot, "docs", "docs.json") + if _, err := os.Stat(docsJSONPath); err == nil { + navPages := []string{"cli-reference/index"} + for _, name := range availableCommandNames(root) { + navPages = append(navPages, "cli-reference/"+commandDocID(name)) + } + if err := updateMintlifyCLINav(docsJSONPath, navPages); err != nil { + return err + } + } + if docsVersion != "" { versionDir := filepath.Join(repoRoot, "website", "versioned_docs", "version-"+docsVersion, "cli-reference") if err := writeCLIReferenceDir(versionDir, root, "v"+docsVersion); err != nil { @@ -318,6 +343,158 @@ func writeGeneratedCLIDocs(root *cobra.Command, repoRoot, docsVersion string) er return nil } +// writeMintlifyCLIReferenceDir emits the Mintlify-form CLI reference under +// docs/cli-reference/: frontmatter title is the H1 (no body H1), links are +// root-relative and extensionless, and the auto-generated marker is a JSX +// comment because Mintlify parses .md through MDX (HTML comments break it). +func writeMintlifyCLIReferenceDir(outDir string, root *cobra.Command) error { + if err := os.MkdirAll(outDir, 0o755); err != nil { + return err + } + if err := removeMarkdownFiles(outDir); err != nil { + return err + } + + commands := availableCommandNames(root) + if err := writeMarkdownFile(filepath.Join(outDir, "index.md"), mintlifyCLIReferenceIndex(commands)); err != nil { + return err + } + + for _, name := range commands { + var out bytes.Buffer + if err := writeMintlifySingleCommandDoc(&out, root, name); err != nil { + return err + } + path := filepath.Join(outDir, commandDocID(name)+".md") + if err := writeMarkdownFile(path, out.String()); err != nil { + return err + } + } + + return nil +} + +// writeMintlifySingleCommandDoc renders one command as a Mintlify page. The +// frontmatter title renders as the page H1, so the top command emits its body +// without its own heading; subcommands start at ##. +func writeMintlifySingleCommandDoc(w io.Writer, root *cobra.Command, cmdName string) error { + 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())) + if docCommand == "" { + return errors.New("Error: cannot generate docs for root command") + } + + fmt.Fprintf(w, "---\n") + fmt.Fprintf(w, "title: %q\n", "bd "+docCommand) + if cmd.Short != "" { + fmt.Fprintf(w, "description: %q\n", cmd.Short) + } + fmt.Fprintf(w, "---\n\n") + fmt.Fprintf(w, "{/* AUTO-GENERATED: do not edit manually */}\n\n") + fmt.Fprintf(w, "Generated from `bd help --doc %s`.\n\n", docCommand) + + writeCommandBody(w, cmd) + + fullPath := commandPath(cmd) + for _, sub := range cmd.Commands() { + if !sub.IsAvailableCommand() { + continue + } + writeCommandHelp(w, sub, fullPath, 2) + } + return nil +} + +func mintlifyCLIReferenceIndex(commands []string) string { + var b strings.Builder + fmt.Fprintf(&b, "---\n") + fmt.Fprintf(&b, "title: CLI Reference\n") + fmt.Fprintf(&b, "description: Generated reference for every bd command\n") + fmt.Fprintf(&b, "---\n\n") + fmt.Fprintf(&b, "{/* AUTO-GENERATED: do not edit manually */}\n\n") + fmt.Fprintf(&b, "Generated from `bd help --docs-root`.\n\n") + fmt.Fprintf(&b, "This reference covers all %d live top-level `bd` commands. Regenerate it with:\n\n", len(commands)) + fmt.Fprintf(&b, "```bash\n") + fmt.Fprintf(&b, "./scripts/generate-cli-docs.sh\n") + fmt.Fprintf(&b, "```\n\n") + fmt.Fprintf(&b, "## Commands\n\n") + for _, cmd := range commands { + fmt.Fprintf(&b, "- [`bd %s`](/cli-reference/%s)\n", cmd, commandDocID(cmd)) + } + return b.String() +} + +// updateMintlifyCLINav rewrites the "pages" array of the "CLI Reference" +// navigation group in docs.json, leaving every other byte of the file +// untouched. A textual splice (rather than a JSON round-trip) preserves key +// order and formatting so regeneration is diff-stable. The pages entries are +// plain slugs, so bracket matching cannot be confused by string contents. +func updateMintlifyCLINav(docsJSONPath string, pages []string) error { + data, err := os.ReadFile(docsJSONPath) + if err != nil { + return err + } + s := string(data) + + groupIdx := strings.Index(s, `"group": "CLI Reference"`) + if groupIdx < 0 { + return fmt.Errorf("%s: no \"CLI Reference\" navigation group found", docsJSONPath) + } + pagesIdx := strings.Index(s[groupIdx:], `"pages"`) + if pagesIdx < 0 { + return fmt.Errorf("%s: \"CLI Reference\" group has no \"pages\" key", docsJSONPath) + } + pagesIdx += groupIdx + openIdx := strings.Index(s[pagesIdx:], "[") + if openIdx < 0 { + return fmt.Errorf("%s: \"CLI Reference\" pages key has no array", docsJSONPath) + } + openIdx += pagesIdx + + depth := 0 + closeIdx := -1 + for i := openIdx; i < len(s); i++ { + switch s[i] { + case '[': + depth++ + case ']': + depth-- + if depth == 0 { + closeIdx = i + } + } + if closeIdx >= 0 { + break + } + } + if closeIdx < 0 { + return fmt.Errorf("%s: unbalanced \"pages\" array in \"CLI Reference\" group", docsJSONPath) + } + + lineStart := strings.LastIndex(s[:pagesIdx], "\n") + 1 + indent := s[lineStart:pagesIdx] + entryIndent := indent + " " + + var b strings.Builder + b.WriteString("[\n") + for i, p := range pages { + fmt.Fprintf(&b, "%s%q", entryIndent, p) + if i < len(pages)-1 { + b.WriteString(",") + } + b.WriteString("\n") + } + b.WriteString(indent + "]") + + out := s[:openIdx] + b.String() + s[closeIdx+1:] + // #nosec G306: docs.json is repository source, readable like other source files. + return os.WriteFile(docsJSONPath, []byte(out), 0o644) +} + func writeCLIReferenceDir(outDir string, root *cobra.Command, versionLabel string) error { if err := os.MkdirAll(outDir, 0o755); err != nil { return err diff --git a/cmd/bd/help_all_test.go b/cmd/bd/help_all_test.go index 829ccc553..11ec9cc9d 100644 --- a/cmd/bd/help_all_test.go +++ b/cmd/bd/help_all_test.go @@ -2,6 +2,7 @@ package main import ( "bytes" + "encoding/json" "os" "path/filepath" "strings" @@ -205,6 +206,171 @@ func TestWriteGeneratedCLIDocsDoesNotTouchVersionedDocsWithoutVersion(t *testing assertFileContains(t, sentinel, "keep me") } +func TestWriteGeneratedCLIDocsWritesMintlifyCLIReference(t *testing.T) { + root := &cobra.Command{Use: "bd"} + mol := testHelpCmd("mol", "Molecule commands") + mol.AddCommand(testHelpCmd("pour ", "Start a workflow")) + root.AddCommand( + testHelpCmd("show ", "Show an issue"), + mol, + ) + dir := t.TempDir() + + if err := writeGeneratedCLIDocs(root, dir, ""); err != nil { + t.Fatalf("writeGeneratedCLIDocs() error = %v", err) + } + + // Index page: Mintlify frontmatter, no body H1, extensionless links. + indexPath := filepath.Join(dir, "docs", "cli-reference", "index.md") + assertFileContains(t, indexPath, "title: CLI Reference") + assertFileContains(t, indexPath, "](/cli-reference/show)") + index, err := os.ReadFile(indexPath) + if err != nil { + t.Fatal(err) + } + for _, banned := range []string{"\n# ", "