From eaf4f215b55bb101882033119f6cfb9b99f8b42e Mon Sep 17 00:00:00 2001 From: zhi Date: Sat, 21 Mar 2026 15:37:13 +0000 Subject: [PATCH] Add detailed leaf help output --- README.md | 1 + cmd/hf/main.go | 20 ++++- internal/help/leaf.go | 178 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 197 insertions(+), 2 deletions(-) create mode 100644 internal/help/leaf.go diff --git a/README.md b/README.md index f03ae40..0d82ddb 100644 --- a/README.md +++ b/README.md @@ -65,6 +65,7 @@ Implemented: - Config file resolution relative to binary directory - Runtime mode detection (`pass_mgr` present/absent) - Top-level and group/leaf help rendering system (`--help` / `--help-brief` / `not permitted` stubs) +- Detailed leaf help text for implemented commands, with padded-cell/manual auth flag differences - Permission-aware command visibility via `/auth/me/permissions` when a token is available - HTTP client wrapper - Output formatting (human-readable + `--json`) diff --git a/cmd/hf/main.go b/cmd/hf/main.go index 46c8222..09b3b43 100644 --- a/cmd/hf/main.go +++ b/cmd/hf/main.go @@ -58,7 +58,11 @@ func parseGlobalFlags(args []string) []string { } func handleLeafOrRun(name string, args []string, run func()) { - if isHelpFlagOnly(args) { + if isLeafHelpFlagOnly(args) { + if text, ok := help.RenderLeafHelp("", name); ok { + fmt.Print(text) + return + } fmt.Printf("hf %s\n", name) return } @@ -70,6 +74,10 @@ func handleLeafOrRun(name string, args []string, run func()) { func handleConfig(args []string) { if isHelpFlagOnly(args) { + if text, ok := help.RenderLeafHelp("config", "show"); ok { + fmt.Print(text) + return + } runConfigHelp() return } @@ -123,11 +131,15 @@ func handleGroup(group help.Group, args []string) { output.Errorf("unknown %s subcommand: %s", group.Name, args[0]) } - if len(args) > 1 && isHelpFlagOnly(args[1:]) { + if len(args) > 1 && isLeafHelpFlagOnly(args[1:]) { if !sub.Permitted { fmt.Println(help.RenderNotPermitted(group.Name, sub.Name)) return } + if text, ok := help.RenderLeafHelp(group.Name, sub.Name); ok { + fmt.Print(text) + return + } fmt.Printf("hf %s %s\n", group.Name, sub.Name) return } @@ -266,6 +278,10 @@ func isHelpFlagOnly(args []string) bool { return len(args) == 1 && (args[0] == "--help" || args[0] == "-h") } +func isLeafHelpFlagOnly(args []string) bool { + return len(args) == 1 && (args[0] == "--help" || args[0] == "-h" || args[0] == "--help-brief") +} + func findGroup(name string) (help.Group, bool) { for _, group := range help.CommandSurface() { if group.Name == name { diff --git a/internal/help/leaf.go b/internal/help/leaf.go new file mode 100644 index 0000000..6610f78 --- /dev/null +++ b/internal/help/leaf.go @@ -0,0 +1,178 @@ +package help + +import ( + "fmt" + "strings" + + "git.hangman-lab.top/zhi/HarborForge.Cli/internal/mode" +) + +type leafHelp struct { + Summary string + Usage []string + Flags []string + Notes []string +} + +func RenderLeafHelp(group, cmd string) (string, bool) { + spec, ok := leafHelpSpec(group, cmd) + if !ok { + return "", false + } + + var b strings.Builder + name := strings.TrimSpace(strings.TrimSpace(group + " " + cmd)) + b.WriteString(fmt.Sprintf("hf %s - %s\n", name, spec.Summary)) + b.WriteString("\nUsage:\n") + for _, line := range spec.Usage { + b.WriteString(" " + line + "\n") + } + if len(spec.Flags) > 0 { + b.WriteString("\nFlags:\n") + for _, line := range spec.Flags { + b.WriteString(" " + line + "\n") + } + } + if len(spec.Notes) > 0 { + b.WriteString("\nNotes:\n") + for _, line := range spec.Notes { + b.WriteString(" - " + line + "\n") + } + } + return b.String(), true +} + +func authFlagHelp() []string { + if mode.IsPaddedCell() { + return []string{ + "--json Output in JSON format", + } + } + return []string{ + "--token HarborForge API token (required in manual mode)", + "--json Output in JSON format", + } +} + +func accountManagerFlagHelp() []string { + flags := []string{ + "--user Username to create", + "--pass Initial password", + "--email Email address (defaults to @harborforge.local)", + "--full-name Full name", + "--json Output in JSON format", + } + if mode.IsPaddedCell() { + return flags + } + return append([]string{"--acc-mgr-token Account-manager token (required in manual mode)"}, flags...) +} + +func leafHelpSpec(group, cmd string) (leafHelp, bool) { + specs := map[string]leafHelp{ + "config/show": { + Summary: "View current CLI configuration", + Usage: []string{"hf config"}, + Flags: []string{"--json Output in JSON format"}, + Notes: []string{ + "Configuration is stored in .hf-config.json next to the hf binary.", + }, + }, + "version": { + Summary: "Show CLI version", + Usage: []string{"hf version"}, + Flags: []string{"--json Output in JSON format"}, + }, + "health": { + Summary: "Check HarborForge API health", + Usage: []string{"hf health", "hf health --json"}, + Flags: authFlagHelp(), + }, + "config/url": { + Summary: "Set HarborForge API base URL", + Usage: []string{"hf config --url "}, + Notes: []string{"Writes base-url into .hf-config.json next to the hf binary."}, + }, + "config/acc-mgr-token": { + Summary: "Store the account-manager token via pass_mgr", + Usage: []string{"hf config --acc-mgr-token "}, + Notes: []string{"Only available in padded-cell mode with pass_mgr installed."}, + }, + "user/create": { + Summary: "Create a user account", + Usage: []string{"hf user create --user [--pass ] [--email ] [--full-name ]"}, + Flags: accountManagerFlagHelp(), + Notes: []string{ + "This command uses the account-manager token flow, not the normal user token flow.", + "In padded-cell mode, --acc-mgr-token is hidden and password generation can fall back to pass_mgr.", + }, + }, + "user/list": {Summary: "List users", Usage: []string{"hf user list"}, Flags: authFlagHelp()}, + "user/get": {Summary: "Show a user by username", Usage: []string{"hf user get "}, Flags: authFlagHelp()}, + "user/update": {Summary: "Update a user", Usage: []string{"hf user update [--email ] [--full-name ] [--pass ] [--active ]"}, Flags: authFlagHelp()}, + "user/activate": {Summary: "Activate a user", Usage: []string{"hf user activate "}, Flags: authFlagHelp()}, + "user/deactivate": {Summary: "Deactivate a user", Usage: []string{"hf user deactivate "}, Flags: authFlagHelp()}, + "user/delete": {Summary: "Delete a user", Usage: []string{"hf user delete "}, Flags: authFlagHelp()}, + "role/list": {Summary: "List roles", Usage: []string{"hf role list"}, Flags: authFlagHelp()}, + "role/get": {Summary: "Show a role by name", Usage: []string{"hf role get "}, Flags: authFlagHelp()}, + "role/create": {Summary: "Create a role", Usage: []string{"hf role create --name [--desc ] [--global ]"}, Flags: authFlagHelp()}, + "role/update": {Summary: "Update a role", Usage: []string{"hf role update [--desc ]"}, Flags: authFlagHelp()}, + "role/delete": {Summary: "Delete a role", Usage: []string{"hf role delete "}, Flags: authFlagHelp()}, + "role/set-permissions": {Summary: "Replace role permissions", Usage: []string{"hf role set-permissions --permission [--permission ...]"}, Flags: authFlagHelp()}, + "role/add-permissions": {Summary: "Add permissions to a role", Usage: []string{"hf role add-permissions --permission [--permission ...]"}, Flags: authFlagHelp()}, + "role/remove-permissions": {Summary: "Remove permissions from a role", Usage: []string{"hf role remove-permissions --permission [--permission ...]"}, Flags: authFlagHelp()}, + "permission/list": {Summary: "List permissions", Usage: []string{"hf permission list"}, Flags: authFlagHelp()}, + "project/list": {Summary: "List projects", Usage: []string{"hf project list [--owner ] [--order-by ] [--order-by <...>]"}, Flags: authFlagHelp()}, + "project/get": {Summary: "Show a project by code", Usage: []string{"hf project get "}, Flags: authFlagHelp()}, + "project/create": {Summary: "Create a project", Usage: []string{"hf project create --name [--desc ] [--repo ]"}, Flags: authFlagHelp()}, + "project/update": {Summary: "Update a project", Usage: []string{"hf project update [--name ] [--desc ] [--repo ]"}, Flags: authFlagHelp()}, + "project/delete": {Summary: "Delete a project", Usage: []string{"hf project delete "}, Flags: authFlagHelp()}, + "project/members": {Summary: "List project members", Usage: []string{"hf project members "}, Flags: authFlagHelp()}, + "project/add-member": {Summary: "Add a member to a project", Usage: []string{"hf project add-member --user --role "}, Flags: authFlagHelp()}, + "project/remove-member": {Summary: "Remove a member from a project", Usage: []string{"hf project remove-member --user "}, Flags: authFlagHelp()}, + "milestone/list": {Summary: "List milestones", Usage: []string{"hf milestone list --project [--status ] [--order-by ] [--order-by <...>]"}, Flags: authFlagHelp()}, + "milestone/get": {Summary: "Show a milestone by code", Usage: []string{"hf milestone get "}, Flags: authFlagHelp()}, + "milestone/create": {Summary: "Create a milestone", Usage: []string{"hf milestone create --project --title [--desc <desc>] [--due <date>]"}, Flags: authFlagHelp()}, + "milestone/update": {Summary: "Update a milestone", Usage: []string{"hf milestone update <milestone-code> [--title <title>] [--desc <desc>] [--status <status>] [--due <date>]"}, Flags: authFlagHelp()}, + "milestone/delete": {Summary: "Delete a milestone", Usage: []string{"hf milestone delete <milestone-code>"}, Flags: authFlagHelp()}, + "milestone/progress": {Summary: "Show milestone progress", Usage: []string{"hf milestone progress <milestone-code>"}, Flags: authFlagHelp()}, + "task/list": {Summary: "List tasks", Usage: []string{"hf task list [--project <project-code>] [--milestone <milestone-code>] [--status <status>] [--taken-by <me|null|username>] [--due-today <true|false>] [--order-by <due-date|priority|created|name>] [--order-by <...>]"}, Flags: authFlagHelp()}, + "task/get": {Summary: "Show a task by code", Usage: []string{"hf task get <task-code>"}, Flags: authFlagHelp()}, + "task/create": {Summary: "Create a task", Usage: []string{"hf task create --project <project-code> --title <title> [--milestone <milestone-code>] [--type <type>] [--priority <priority>] [--desc <desc>]"}, Flags: authFlagHelp()}, + "task/update": {Summary: "Update a task", Usage: []string{"hf task update <task-code> [--title <title>] [--desc <desc>] [--status <status>] [--priority <priority>] [--assignee <username|null>]"}, Flags: authFlagHelp()}, + "task/transition": {Summary: "Transition a task to a new status", Usage: []string{"hf task transition <task-code> <status>"}, Flags: authFlagHelp()}, + "task/take": {Summary: "Assign a task to the current user", Usage: []string{"hf task take <task-code>"}, Flags: authFlagHelp()}, + "task/delete": {Summary: "Delete a task", Usage: []string{"hf task delete <task-code>"}, Flags: authFlagHelp()}, + "task/search": {Summary: "Search tasks", Usage: []string{"hf task search --query <text> [--project <project-code>] [--status <status>]"}, Flags: authFlagHelp()}, + "meeting/list": {Summary: "List meetings", Usage: []string{"hf meeting list [--project <project-code>] [--status <status>] [--order-by <created|due-date|name>] [--order-by <...>]"}, Flags: authFlagHelp()}, + "meeting/get": {Summary: "Show a meeting by code", Usage: []string{"hf meeting get <meeting-code>"}, Flags: authFlagHelp()}, + "meeting/create": {Summary: "Create a meeting", Usage: []string{"hf meeting create --project <project-code> --title <title> [--milestone <milestone-code>] [--desc <desc>] [--time <datetime>]"}, Flags: authFlagHelp()}, + "meeting/update": {Summary: "Update a meeting", Usage: []string{"hf meeting update <meeting-code> [--title <title>] [--desc <desc>] [--status <status>] [--time <datetime>]"}, Flags: authFlagHelp()}, + "meeting/attend": {Summary: "Attend a meeting", Usage: []string{"hf meeting attend <meeting-code>"}, Flags: authFlagHelp()}, + "meeting/delete": {Summary: "Delete a meeting", Usage: []string{"hf meeting delete <meeting-code>"}, Flags: authFlagHelp()}, + "support/list": {Summary: "List support tickets", Usage: []string{"hf support list [--taken-by <me|null|username>] [--status <status>] [--order-by <due-date|priority|created|name>] [--order-by <...>]"}, Flags: authFlagHelp()}, + "support/get": {Summary: "Show a support ticket by code", Usage: []string{"hf support get <support-code>"}, Flags: authFlagHelp()}, + "support/create": {Summary: "Create a support ticket", Usage: []string{"hf support create --title <title> [--project <project-code>] [--desc <desc>] [--priority <priority>]"}, Flags: authFlagHelp()}, + "support/update": {Summary: "Update a support ticket", Usage: []string{"hf support update <support-code> [--title <title>] [--desc <desc>] [--status <status>] [--priority <priority>]"}, Flags: authFlagHelp()}, + "support/take": {Summary: "Assign a support ticket to the current user", Usage: []string{"hf support take <support-code>"}, Flags: authFlagHelp()}, + "support/transition": {Summary: "Transition a support ticket to a new status", Usage: []string{"hf support transition <support-code> <status>"}, Flags: authFlagHelp()}, + "support/delete": {Summary: "Delete a support ticket", Usage: []string{"hf support delete <support-code>"}, Flags: authFlagHelp()}, + "propose/list": {Summary: "List proposals", Usage: []string{"hf propose list --project <project-code> [--status <status>] [--order-by <created|name>] [--order-by <...>]"}, Flags: authFlagHelp()}, + "propose/get": {Summary: "Show a proposal by code", Usage: []string{"hf propose get <propose-code>"}, Flags: authFlagHelp()}, + "propose/create": {Summary: "Create a proposal", Usage: []string{"hf propose create --project <project-code> --title <title> --desc <desc>"}, Flags: authFlagHelp()}, + "propose/update": {Summary: "Update a proposal", Usage: []string{"hf propose update <propose-code> [--title <title>] [--desc <desc>]"}, Flags: authFlagHelp()}, + "propose/accept": {Summary: "Accept a proposal", Usage: []string{"hf propose accept <propose-code> --milestone <milestone-code>"}, Flags: authFlagHelp()}, + "propose/reject": {Summary: "Reject a proposal", Usage: []string{"hf propose reject <propose-code> [--reason <reason>]"}, Flags: authFlagHelp()}, + "propose/reopen": {Summary: "Reopen a proposal", Usage: []string{"hf propose reopen <propose-code>"}, Flags: authFlagHelp()}, + "monitor/overview": {Summary: "Show monitor overview", Usage: []string{"hf monitor overview"}, Flags: authFlagHelp()}, + "monitor/server": {Summary: "Manage monitor servers", Usage: []string{"hf monitor server list", "hf monitor server get <identifier>", "hf monitor server create --identifier <identifier> [--name <display-name>]", "hf monitor server delete <identifier>"}, Flags: authFlagHelp()}, + "monitor/api-key": {Summary: "Manage monitor API keys", Usage: []string{"hf monitor api-key generate <identifier>", "hf monitor api-key revoke <identifier>"}, Flags: authFlagHelp()}, + } + + if group == "" { + spec, ok := specs[cmd] + return spec, ok + } + spec, ok := specs[group+"/"+cmd] + return spec, ok +}