feat: console help, examples and named loggers (SummerCMS v0.4.0)

Every command gets long help and examples, descriptions in imperative
sentence case, and a warn-only TestCommandsDocumented over bonfire.CheckDocs.
The plugin logs through a diary component logger instead of the process
default logger. Requires SummerCMS v0.4.0; command names and flags unchanged.

console/import.go

@@ -29,6 +29,17 @@ func Import(app *backpack.App) bonfire.Command {
 	return bonfire.Command{
 		Name:        "sitemap:import",
 		Description: "Import sitemap URLs from a JSON manifest file",
+		Long: `Reads a JSON array of URL entries ({"url": "/path", "changefreq":
+"monthly", "priority": "0.5"}; changefreq and priority are optional) and puts
+them into the sitemap definition that /sitemap.xml serves, in one
+transaction. Every entry needs a url that is a path or an http(s) URL; one
+bad entry stops the import before anything is written.
+
+By default the import replaces the definition's url items and keeps its
+dynamic items (pages, posts and other generated types). --append adds the
+URLs and keeps every existing item. --theme is accepted for the PHP command's
+sake: only the default definition is served, so the URLs always go there.
+It ends with "Imported N URLs into sitemap definition for theme 'default'."`,
 		Args: []bonfire.Arg{
 			{Name: "file", Description: "Path to the JSON manifest (relative to the working directory or absolute)", Required: true},
 		},
@@ -36,6 +47,10 @@ func Import(app *backpack.App) bonfire.Command {
 			{Name: "theme", Description: "Theme code of the PHP plugin; /sitemap.xml serves only the default definition"},
 			{Name: "append", Description: "Add URLs without removing existing url-type items", Bare: true},
 		},
+		Examples: []bonfire.Example{
+			{Command: "sitemap:import urls.json", Description: "Replace the url items with the manifest's URLs"},
+			{Command: "sitemap:import urls.json --append", Description: "Add the URLs and keep every existing item"},
+		},
 		Run: func(ctx context.Context, in bonfire.Input, out bonfire.Output) error {
 			file, _ := in.Argument("file")
 			db, done, err := lookupDB(ctx, app)
@@ -100,7 +115,7 @@ func ImportFile(ctx context.Context, db *gorm.DB, file, theme string, appendMode
 	if err != nil {
 		return err
 	}
-	out.Info(fmt.Sprintf("Imported %d URLs into sitemap definition for theme '%s'.", len(newItems), models.DefinitionTheme))
+	out.Success(fmt.Sprintf("Imported %d URLs into sitemap definition for theme '%s'.", len(newItems), models.DefinitionTheme))
 	if kept > 0 {
 		label := "existing non-URL (dynamic)"
 		if appendMode {

console/import_winter.go

@@ -78,6 +78,19 @@ func ImportWinter(app *backpack.App) bonfire.Command {
 	return bonfire.Command{
 		Name:        "sitemap:import-winter",
 		Description: "Copy a WinterCMS sitemap definition and settings export into this application",
+		Long: `Copies the sitemap definition of a WinterCMS site (the JSON lines that
+scripts/winter-export-definitions.sql prints) and its settings (the JSON
+object from scripts/winter-export-settings.sql) in one transaction. Item
+types this application knows are kept; --map renames a type (old=new) and
+--page-url turns a static or CMS page item into a url item with the given
+path. Items that still have no known type are dropped and listed. When the
+export holds several themes, --theme picks the one to copy.
+
+Run it once when an application moves from WinterCMS, --dry-run first:
+--dry-run reports kept, remapped and dropped items and writes nothing. A
+definition that already has items is replaced only with --force. It ends
+with "Definition copied: N items kept, N remapped, N dropped." and "Settings
+copied." for the parts the export holds.`,
 		Flags: []bonfire.Flag{
 			{Name: "definitions", Description: "Definitions export (JSON lines from scripts/winter-export-definitions.sql)"},
 			{Name: "settings", Description: "Settings export (the JSON object from scripts/winter-export-settings.sql)"},
@@ -87,6 +100,11 @@ func ImportWinter(app *backpack.App) bonfire.Command {
 			{Name: "force", Description: "Replace a definition that already has items", Bare: true},
 			{Name: "dry-run", Description: "Report what would be copied without writing", Bare: true},
 		},
+		Examples: []bonfire.Example{
+			{Command: "sitemap:import-winter --definitions definitions.jsonl --settings settings.json --dry-run", Description: "Show what would be kept, remapped and dropped, without writing"},
+			{Command: "sitemap:import-winter --definitions definitions.jsonl --theme main --map blog-post=journal-post", Description: "Copy the main theme's definition, renaming an item type"},
+			{Command: "sitemap:import-winter --definitions definitions.jsonl --page-url about=/about --force", Description: "Replace the definition, turning the about page into a url item"},
+		},
 		Run: func(ctx context.Context, in bonfire.Input, out bonfire.Output) error {
 			maps, err := parseMaps(in.Flags("map"))
 			if err != nil {
@@ -242,10 +260,10 @@ func ImportWinterFiles(ctx context.Context, db *gorm.DB, reg *signpost.Registry,
 		return report, err
 	}
 	if haveDef {
-		out.Info("Definition copied: " + summary)
+		out.Success("Definition copied: " + summary)
 	}
 	if report.Settings {
-		out.Info("Settings copied.")
+		out.Success("Settings copied.")
 	}
 	return report, nil
 }