docs(backpack,beachcomber,boardwalk,bonfire,bouncer): compile README Go examples via src= (quick-261118-qsd)

- backpack: Greeter and ExampleApp_Publish replace the whole-file fence
- beachcomber: Post's Searchable methods plus a new SearchIndexSchema, a
  Plugin.Boot that installs the gate, and the existing gate/search regions
- boardwalk: new example_test.go; the mount region runs in ExampleHandler
- bonfire: importPostsCommand and acmeMain (the binary's main as a function
  returning the exit code), run by ExampleExecute; ExampleCatalog_Has
- bouncer: users/FindByID and ExampleNewJWTGuard; RefreshRoute run by
  TestDocsRefreshRoute on a production compass config
This commit is contained in:
Jakub Zych
2026-11-18 19:39:50 +01:00
parent 48527e4206
commit a0f5b5e561
9 changed files with 366 additions and 125 deletions

View File

@@ -53,18 +53,12 @@ Use cases:
## Usage
```go
package main
A command declares its arguments and flags and gets an injected console:
import (
"context"
"os"
"git.golem15.com/golem15/summercms/modules/bonfire"
)
func main() {
importPosts := bonfire.Command{
```go src=modules/bonfire/example_test.go#importPostsCommand
// importPostsCommand is the blog:import command of the acme binary.
func importPostsCommand() bonfire.Command {
return bonfire.Command{
Name: "blog:import",
Description: "Import posts from a feed",
Args: []bonfire.Arg{{Name: "url", Description: "Feed URL", Required: true}},
@@ -84,28 +78,43 @@ func main() {
})
},
}
}
```
args := os.Args[1:]
The binary's main function calls this with os.Args[1:], os.Stdout and os.Stderr and exits with the code it returns:
```go src=modules/bonfire/example_test.go#acmeMain
// acmeMain is the body of the acme binary's main function, which calls
// os.Exit(acmeMain(os.Args[1:], os.Stdout, os.Stderr)).
func acmeMain(args []string, stdout, stderr io.Writer) int {
g := bonfire.PeekGlobals(args)
root, err := bonfire.NewRoot("acme", []bonfire.Command{importPosts}, os.Stdout,
root, err := bonfire.NewRoot("acme", []bonfire.Command{importPostsCommand()}, stdout,
bonfire.WithVersion(bonfire.BuildVersion()))
if err != nil {
os.Exit(bonfire.Fail(os.Stderr, "acme", err, g))
return bonfire.Fail(stderr, "acme", err, g)
}
os.Exit(bonfire.Execute(context.Background(), root, args))
return bonfire.Execute(context.Background(), root, args)
}
```
Running a command in-process, with empty stdin so prompts take their defaults:
```go
catalog := bonfire.NewCatalog(commands)
```go src=modules/bonfire/example_test.go#ExampleCatalog_Has
ctx := context.Background()
catalog := bonfire.NewCatalog([]bonfire.Command{importPostsCommand()})
if catalog.Has("blog:import") {
err := catalog.Call(ctx, "blog:import", []string{"--dry-run", "https://example.com/feed"}, os.Stdout)
if errors.Is(err, bonfire.ErrUnknownCommand) {
// not registered in this binary
}
fmt.Println(err)
}
err := catalog.Call(ctx, "blog:export", nil, os.Stdout)
fmt.Println(errors.Is(err, bonfire.ErrUnknownCommand)) // not registered in this binary
// Output:
// [...] Importing https://example.com/feed
// Tag
// news
// ⚠ dry run: nothing written
// <nil>
// true
```
## API reference

View File

@@ -2,7 +2,9 @@ package bonfire_test
import (
"context"
"errors"
"fmt"
"io"
"os"
"strings"
@@ -160,3 +162,68 @@ func ExampleCheckDocs() {
}
// Output: blog:reindex: missing long help, examples, option --batch description
}
// importPostsCommand is the blog:import command of the acme binary.
func importPostsCommand() bonfire.Command {
return bonfire.Command{
Name: "blog:import",
Description: "Import posts from a feed",
Args: []bonfire.Arg{{Name: "url", Description: "Feed URL", Required: true}},
Flags: []bonfire.Flag{
{Name: "dry-run", Description: "Report without writing", Bare: true},
{Name: "tag", Description: "Tag to apply (repeatable)", Repeatable: true},
},
Run: func(ctx context.Context, in bonfire.Input, out bonfire.Output) error {
url, _ := in.Argument("url")
dryRun := bonfire.FlagBool(in, "dry-run")
return out.Spinner("Importing "+url, func() error {
out.Table([]string{"Tag"}, [][]string{{"news"}})
if dryRun {
out.Warning("dry run: nothing written")
}
return nil
})
},
}
}
// acmeMain is the body of the acme binary's main function, which calls
// os.Exit(acmeMain(os.Args[1:], os.Stdout, os.Stderr)).
func acmeMain(args []string, stdout, stderr io.Writer) int {
g := bonfire.PeekGlobals(args)
root, err := bonfire.NewRoot("acme", []bonfire.Command{importPostsCommand()}, stdout,
bonfire.WithVersion(bonfire.BuildVersion()))
if err != nil {
return bonfire.Fail(stderr, "acme", err, g)
}
return bonfire.Execute(context.Background(), root, args)
}
func ExampleExecute() {
code := acmeMain([]string{"blog:import", "--dry-run", "https://example.com/feed"}, os.Stdout, os.Stdout)
fmt.Println("exit code:", code)
// Output:
// [...] Importing https://example.com/feed
// Tag
// news
// ⚠ dry run: nothing written
// exit code: 0
}
func ExampleCatalog_Has() {
ctx := context.Background()
catalog := bonfire.NewCatalog([]bonfire.Command{importPostsCommand()})
if catalog.Has("blog:import") {
err := catalog.Call(ctx, "blog:import", []string{"--dry-run", "https://example.com/feed"}, os.Stdout)
fmt.Println(err)
}
err := catalog.Call(ctx, "blog:export", nil, os.Stdout)
fmt.Println(errors.Is(err, bonfire.ErrUnknownCommand)) // not registered in this binary
// Output:
// [...] Importing https://example.com/feed
// Tag
// news
// ⚠ dry run: nothing written
// <nil>
// true
}