diff --git a/cmd/bd/help_all.go b/cmd/bd/help_all.go index b55fed936..1ac505587 100644 --- a/cmd/bd/help_all.go +++ b/cmd/bd/help_all.go @@ -210,7 +210,7 @@ func writeCommandBody(w io.Writer, cmd *cobra.Command) { fmt.Fprintf(w, "%s\n\n", escapeMDXText(cmd.Short)) } - // Usage — mirror : a runnable command shows its + // Usage — mirror the binary's --help output: a runnable command shows its // UseLine; a command with subcommands also shows ` [command]`. // UseLine() alone appends "[flags]" even on non-runnable parents, which // the binary's help never prints. @@ -315,12 +315,21 @@ func writeGenericCLIDocsDir(outDir string, root *cobra.Command) error { return err } + // commandDocID collapses punctuation, so distinct command names can map + // to the same page file; the later write would silently win. + seen := make(map[string]string, len(commands)) for _, name := range commands { + id := commandDocID(name) + if prev, ok := seen[id]; ok { + return fmt.Errorf("commands %q and %q both map to doc page %s.md; rename one", prev, name, id) + } + seen[id] = name + var out bytes.Buffer if err := writeSingleCommandDoc(&out, root, name); err != nil { return err } - path := filepath.Join(outDir, commandDocID(name)+".md") + path := filepath.Join(outDir, id+".md") if err := writeMarkdownFile(path, out.String()); err != nil { return err } diff --git a/cmd/bd/help_all_test.go b/cmd/bd/help_all_test.go index aa5d8f257..56a05beb3 100644 --- a/cmd/bd/help_all_test.go +++ b/cmd/bd/help_all_test.go @@ -294,6 +294,27 @@ func TestWriteGeneratedCLIDocsReplacesStaleStagingFiles(t *testing.T) { } } +// commandDocID collapses punctuation to dashes, so distinct commands like +// `foo-bar` and `foo_bar` map to the same page file. The emitter must fail +// loudly instead of letting the later write silently win. +func TestWriteGenericCLIDocsDirFailsOnDocIDCollision(t *testing.T) { + root := &cobra.Command{Use: "bd"} + root.AddCommand( + testHelpCmd("foo-bar", "First"), + testHelpCmd("foo_bar", "Second"), + ) + + err := writeGenericCLIDocsDir(filepath.Join(t.TempDir(), "cli-docs"), root) + if err == nil { + t.Fatal("writeGenericCLIDocsDir() succeeded with colliding doc IDs; want error") + } + for _, want := range []string{"foo-bar", "foo_bar"} { + if !strings.Contains(err.Error(), want) { + t.Errorf("collision error should name %q: %v", want, err) + } + } +} + func assertFileContains(t *testing.T, path, want string) { t.Helper() data, err := os.ReadFile(path) diff --git a/cmd/bd/pour.go b/cmd/bd/pour.go index e77beddaf..cf68ce2be 100644 --- a/cmd/bd/pour.go +++ b/cmd/bd/pour.go @@ -107,7 +107,7 @@ func runPour(cmd *cobra.Command, args []string) error { fmt.Fprintf(os.Stderr, " --var %s", v) } fmt.Fprintf(os.Stderr, "\n") - fmt.Fprintf(os.Stderr, " Pour creates persistent issues that sync to git.\n") + fmt.Fprintf(os.Stderr, " Pour creates persistent issues that sync like any other bead.\n") fmt.Fprintf(os.Stderr, " Wisp creates ephemeral issues that auto-cleanup.\n\n") } } @@ -252,7 +252,7 @@ func runPour(cmd *cobra.Command, args []string) error { fmt.Printf("%s Poured mol: created %d issues\n", ui.RenderPass("✓"), result.Created) fmt.Printf(" Root issue: %s\n", result.NewEpicID) - fmt.Printf(" Phase: liquid (persistent in .beads/)\n") + fmt.Printf(" Phase: liquid (persistent in the issue database)\n") if totalAttached > 0 { fmt.Printf(" Attached: %d issues from %d protos\n", totalAttached, len(attachments)) } diff --git a/cmd/bd/testdata/formula_help.txt b/cmd/bd/testdata/formula_help.txt index 5393a0abc..7f30b0939 100644 --- a/cmd/bd/testdata/formula_help.txt +++ b/cmd/bd/testdata/formula_help.txt @@ -8,7 +8,7 @@ bd formula --help stdout 'bd formula schema' stdout 'bd formula primitives' stdout 'examples/formulas/primitives/' -stdout 'website/docs/workflows/formulas.md' +stdout 'docs/workflows/formulas.md' # The list and show subcommands also point at the schema index so agents # arriving via either subcommand find the primitive surface. diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.md index 5b386c65a..6e2f2777c 100644 --- a/docs/CLI_REFERENCE.md +++ b/docs/CLI_REFERENCE.md @@ -6204,7 +6204,7 @@ Configuration (checked in order): Examples: # Configure delegation (one-time setup) - export BEADS_MAIL_DELEGATE="gt mail" + `export BEADS_MAIL_DELEGATE="gt mail"` # or bd config set mail.delegate "gt mail" diff --git a/scripts/generate-cli-docs.sh b/scripts/generate-cli-docs.sh index 62d896fe7..694109e70 100755 --- a/scripts/generate-cli-docs.sh +++ b/scripts/generate-cli-docs.sh @@ -67,7 +67,10 @@ trap cleanup EXIT if [ -n "$BD_ARG" ]; then BD="$BD_ARG" -elif [ -x "$PROJECT_ROOT/bd" ]; then +elif [ "$CHECK_MODE" -eq 0 ] && [ -x "$PROJECT_ROOT/bd" ]; then + # Convenience for regeneration only. --check never trusts a repo-root + # ./bd it wasn't explicitly given: the guard below detects CGO-ness, not + # staleness, so a stale pure-go ./bd would produce a false "fresh". BD="$PROJECT_ROOT/bd" else TMP_BUILD_DIR="$(mktemp -d)" diff --git a/test/docsync/docsync_test.go b/test/docsync/docsync_test.go index 50bafac76..e62adeb11 100644 --- a/test/docsync/docsync_test.go +++ b/test/docsync/docsync_test.go @@ -381,3 +381,60 @@ func TestEngdocsAndRootMarkdownLinks(t *testing.T) { } } } + +// TestMintRedirectsResolve: every entry in the docs.json redirects array must +// be well-formed and point at a page that exists. Nothing else validates the +// redirects, so a future page rename would otherwise dangle its redirect +// invisibly. Dynamic destinations (path-to-regexp `:slug*` wildcards) are +// checked for shape only. +func TestMintRedirectsResolve(t *testing.T) { + root := repoRoot() + data, err := os.ReadFile(filepath.Join(root, "docs", "docs.json")) + if err != nil { + t.Fatalf("reading docs.json: %v", err) + } + var decoded struct { + Redirects []struct { + Source string `json:"source"` + Destination string `json:"destination"` + } `json:"redirects"` + } + if err := json.Unmarshal(data, &decoded); err != nil { + t.Fatalf("parsing docs.json: %v", err) + } + if len(decoded.Redirects) == 0 { + t.Fatal("docs.json has no redirects array; the old-route coverage is gone") + } + + navPages := make(map[string]bool) + for _, p := range mintNavPages(t) { + navPages[strings.TrimSuffix(filepath.ToSlash(p), filepath.Ext(p))] = true + } + + seen := make(map[string]bool) + for _, r := range decoded.Redirects { + if !strings.HasPrefix(r.Source, "/") || !strings.HasPrefix(r.Destination, "/") { + t.Errorf("redirect %q -> %q: source and destination must be root-relative", r.Source, r.Destination) + continue + } + if seen[r.Source] { + t.Errorf("duplicate redirect source %q", r.Source) + } + seen[r.Source] = true + + if strings.Contains(r.Destination, ":") { + // Wildcard destination; requires a wildcard source. + if !strings.Contains(r.Source, ":") { + t.Errorf("redirect %q -> %q: static source with dynamic destination", r.Source, r.Destination) + } + continue + } + dest := strings.TrimPrefix(r.Destination, "/") + if navPages[dest] { + continue + } + if _, err := os.Stat(filepath.Join(root, "docs", filepath.FromSlash(dest)+".md")); err != nil { + t.Errorf("redirect %q -> %q: destination page does not exist", r.Source, r.Destination) + } + } +} diff --git a/tools/docsmint/docsmint.go b/tools/docsmint/docsmint.go index 88232636f..a2aa77a59 100644 --- a/tools/docsmint/docsmint.go +++ b/tools/docsmint/docsmint.go @@ -1,6 +1,7 @@ package main import ( + "encoding/json" "fmt" "os" "path/filepath" @@ -44,6 +45,10 @@ func run(root string) error { } sort.Strings(pages) + if err := neutralizeSingleFileReference(filepath.Join(root, "docs", "CLI_REFERENCE.md")); err != nil { + return err + } + if err := os.MkdirAll(target, 0o755); err != nil { return err } @@ -72,20 +77,30 @@ func run(root string) error { return spliceCLINav(docsJSON, append([]string{"cli-reference/index"}, navPages...)) } -// transformPage converts one generic page to Mintlify form. +// transformPage converts one generic page to Mintlify form. Every rewrite +// skips fenced code blocks: fence contents are literal example text (an HTML +// comment or relative link inside a fence must render verbatim). func transformPage(content string) string { - content = htmlCommentRE.ReplaceAllString(content, "{/* $1 */}") - content = relativePageLinkRE.ReplaceAllString(content, "](/cli-reference/$1)") - content = neutralizeESMHazards(content) - return content + lines := strings.Split(content, "\n") + inFence := false + for i, line := range lines { + trimmed := strings.TrimSpace(line) + if strings.HasPrefix(trimmed, "```") { + inFence = !inFence + continue + } + if inFence { + continue + } + line = htmlCommentRE.ReplaceAllString(line, "{/* $1 */}") + line = relativePageLinkRE.ReplaceAllString(line, "](/cli-reference/$1)") + lines[i] = neutralizeESMLine(line) + } + return strings.Join(lines, "\n") } -// neutralizeESMHazards wraps prose lines whose first token is `export` or -// `import` in inline code spans. Such lines are legal CommonMark in bd's -// generic output (indented example lines in help text), but Mintlify's -// prebuild dedents them to column 0 and then parses them as MDX ESM blocks, -// which fails the entire page (observed on cli-reference/mail). Lines inside -// code fences are left untouched. +// neutralizeESMHazards applies neutralizeESMLine to every line outside code +// fences. func neutralizeESMHazards(content string) string { lines := strings.Split(content, "\n") inFence := false @@ -98,18 +113,48 @@ func neutralizeESMHazards(content string) string { if inFence { continue } - if strings.HasPrefix(trimmed, "export ") || strings.HasPrefix(trimmed, "import ") { - indent := line[:len(line)-len(strings.TrimLeft(line, " \t"))] - delim := "`" - if strings.Contains(trimmed, "`") { - delim = "``" - } - lines[i] = indent + delim + trimmed + delim - } + lines[i] = neutralizeESMLine(line) } return strings.Join(lines, "\n") } +// neutralizeESMLine wraps a prose line whose first token is `export` or +// `import` in an inline code span. Such lines are legal CommonMark in bd's +// generic output (indented example lines in help text), but Mintlify's +// prebuild dedents them to column 0 and then parses them as MDX ESM blocks, +// which fails the entire page (observed on cli-reference/mail). +func neutralizeESMLine(line string) string { + trimmed := strings.TrimSpace(line) + if !strings.HasPrefix(trimmed, "export ") && !strings.HasPrefix(trimmed, "import ") { + return line + } + indent := line[:len(line)-len(strings.TrimLeft(line, " \t"))] + delim := "`" + if strings.Contains(trimmed, "`") { + delim = "``" + } + return indent + delim + trimmed + delim +} + +// neutralizeSingleFileReference applies the ESM-hazard neutralization to +// docs/CLI_REFERENCE.md. bd emits it directly — without the per-page +// transforms — but Mintlify still builds it as a hidden page, so a bare +// indented `export ...` line fails it the same way. +func neutralizeSingleFileReference(path string) error { + // #nosec G304: path is derived from the repo root argument this developer + // tool is invoked with; it only ever reads the repo's own generated file. + data, err := os.ReadFile(path) + if err != nil { + return fmt.Errorf("reading %s (run `bd help --docs-root` first): %w", path, err) + } + out := neutralizeESMHazards(string(data)) + if out == string(data) { + return nil + } + // #nosec G306: generated repository Markdown should be readable like source files. + return os.WriteFile(path, []byte(out), 0o644) +} + func removeMarkdownFiles(dir string) error { entries, err := os.ReadDir(dir) if err != nil { @@ -149,6 +194,10 @@ func spliceCLINav(docsJSONPath string, pages []string) error { return fmt.Errorf("%s: \"CLI Reference\" group has no \"pages\" key", docsJSONPath) } pagesIdx += groupIdx + groupEnd := groupIdx + len(`"group": "CLI Reference"`) + if err := verifySiblingGap(s[groupEnd:pagesIdx]); err != nil { + return fmt.Errorf("%s: cannot safely locate the CLI Reference \"pages\" array: %w", docsJSONPath, err) + } openIdx := strings.Index(s[pagesIdx:], "[") if openIdx < 0 { return fmt.Errorf("%s: \"CLI Reference\" pages key has no array", docsJSONPath) @@ -194,6 +243,42 @@ func spliceCLINav(docsJSONPath string, pages []string) error { b.WriteString(indent + "]") out := s[:openIdx] + b.String() + s[closeIdx+1:] + var check any + if err := json.Unmarshal([]byte(out), &check); err != nil { + return fmt.Errorf("%s: splice produced invalid JSON, refusing to write: %w", docsJSONPath, err) + } // #nosec G306: docs.json is repository source, readable like other source files. return os.WriteFile(docsJSONPath, []byte(out), 0o644) } + +// verifySiblingGap ensures the "pages" key found after "group": "CLI +// Reference" is a sibling key of the same object: the gap between them may +// contain only scalar keys (strings, commas, whitespace). Any structural +// brace or bracket outside a string means the textual forward search crossed +// an object boundary — e.g. the group's keys were reordered so its own pages +// array precedes it — and a splice there would rewrite the WRONG group's +// pages. Fail closed instead. +func verifySiblingGap(gap string) error { + inString := false + escaped := false + for _, r := range gap { + if inString { + switch { + case escaped: + escaped = false + case r == '\\': + escaped = true + case r == '"': + inString = false + } + continue + } + switch r { + case '"': + inString = true + case '{', '}', '[', ']': + return fmt.Errorf("structural %q between the group key and the next \"pages\" key; reorder docs.json so the CLI Reference group's \"group\" key precedes its \"pages\" array", r) + } + } + return nil +} diff --git a/tools/docsmint/docsmint_test.go b/tools/docsmint/docsmint_test.go index 6db3682b1..84e14e7c4 100644 --- a/tools/docsmint/docsmint_test.go +++ b/tools/docsmint/docsmint_test.go @@ -57,6 +57,10 @@ title: "bd create" Create an issue +`) + writeFile(t, filepath.Join(root, "docs", "CLI_REFERENCE.md"), `# bd CLI reference + +Generated single-file reference. `) writeFile(t, filepath.Join(root, "docs", "docs.json"), `{ "name": "Beads Documentation", @@ -220,6 +224,140 @@ Examples: } } +// HTML comments and relative .md links inside code fences are literal example +// content (e.g. a future cmd.Example demonstrating markdown) — the Mintlify +// rewrites must not touch them. +func TestRunLeavesFencedCommentAndLinkExamplesVerbatim(t *testing.T) { + root := t.TempDir() + seedStaging(t, root) + writeFile(t, filepath.Join(root, "build", "cli-docs", "fency.md"), `--- +title: "bd fency" +--- + + + +See [the index](./index.md). + +`+"```"+` + +[fenced link](./fenced.md) +`+"```"+` +`) + + if err := run(root); err != nil { + t.Fatalf("run() error = %v", err) + } + + data, err := os.ReadFile(filepath.Join(root, "docs", "cli-reference", "fency.md")) + if err != nil { + t.Fatal(err) + } + got := string(data) + if !strings.Contains(got, "") { + t.Errorf("fenced HTML comment was rewritten; fenced examples must stay verbatim:\n%s", got) + } + if !strings.Contains(got, "[fenced link](./fenced.md)") { + t.Errorf("fenced relative link was rewritten; fenced examples must stay verbatim:\n%s", got) + } + if !strings.Contains(got, "{/* AUTO-GENERATED: do not edit manually */}") { + t.Errorf("out-of-fence HTML comment was not rewritten:\n%s", got) + } + if !strings.Contains(got, "](/cli-reference/index)") { + t.Errorf("out-of-fence relative link was not rewritten:\n%s", got) + } +} + +// docs/CLI_REFERENCE.md is served by Mintlify as a hidden page but is emitted +// by bd without docsmint's per-page transforms, so it carries the same MDX ESM +// hazard (bare indented `export ...` from bd mail). docsmint must neutralize it. +func TestRunNeutralizesSingleFileReferenceESMHazards(t *testing.T) { + root := t.TempDir() + seedStaging(t, root) + writeFile(t, filepath.Join(root, "docs", "CLI_REFERENCE.md"), `# bd CLI reference + +Examples: + export BEADS_MAIL_DELEGATE="gt mail" + +`+"```"+` + export FENCED_STAYS_VERBATIM=1 +`+"```"+` +`) + + if err := run(root); err != nil { + t.Fatalf("run() error = %v", err) + } + + data, err := os.ReadFile(filepath.Join(root, "docs", "CLI_REFERENCE.md")) + if err != nil { + t.Fatal(err) + } + got := string(data) + if !strings.Contains(got, "`export BEADS_MAIL_DELEGATE=\"gt mail\"`") { + t.Errorf("bare export line was not neutralized in CLI_REFERENCE.md:\n%s", got) + } + if !strings.Contains(got, " export FENCED_STAYS_VERBATIM=1") { + t.Errorf("fenced export line must stay verbatim:\n%s", got) + } +} + +func TestRunFailsLoudlyWithoutSingleFileReference(t *testing.T) { + root := t.TempDir() + seedStaging(t, root) + if err := os.Remove(filepath.Join(root, "docs", "CLI_REFERENCE.md")); err != nil { + t.Fatal(err) + } + + err := run(root) + if err == nil { + t.Fatal("run() succeeded without docs/CLI_REFERENCE.md; want loud failure") + } + if !strings.Contains(err.Error(), "CLI_REFERENCE.md") { + t.Errorf("error should name the missing file: %v", err) + } +} + +// If docs.json is ever reformatted so the CLI Reference group's own "pages" +// key precedes its "group" key, a textual forward search finds the NEXT +// group's pages array and silently rewrites the wrong group. The splice must +// fail closed instead of corrupting navigation. +func TestRunFailsClosedWhenPagesIsNotSiblingKey(t *testing.T) { + root := t.TempDir() + seedStaging(t, root) + reordered := `{ + "navigation": { + "groups": [ + { + "pages": [ + "cli-reference/index" + ], + "group": "CLI Reference" + }, + { + "group": "Other", + "pages": [ + "other/index" + ] + } + ] + } +} +` + writeFile(t, filepath.Join(root, "docs", "docs.json"), reordered) + + err := run(root) + if err == nil { + t.Fatal("run() succeeded with a reordered CLI Reference group; want fail-closed error") + } + + data, readErr := os.ReadFile(filepath.Join(root, "docs", "docs.json")) + if readErr != nil { + t.Fatal(readErr) + } + if string(data) != reordered { + t.Errorf("docs.json was modified despite the fail-closed error:\n%s", data) + } +} + func TestRunRemovesStaleTargetPages(t *testing.T) { root := t.TempDir() seedStaging(t, root)