From 9f7da84915300524f1146500637f3256c0b6b3a0 Mon Sep 17 00:00:00 2001 From: shokollm <270575765+shokollm@users.noreply.github.com> Date: Wed, 8 Apr 2026 05:12:51 +0000 Subject: [PATCH] refactor(cli): restructure help text to show parent commands - kugetsu: show only parent commands, not all subcommands inline - kugetsu help: show help for specific command - kugetsu queue: show queue subcommands (list, stats, clear, enqueue) - kugetsu queue-daemon: show daemon subcommands (start, stop, restart, status, logs) - kugetsu env: show env subcommands (list, get, set, rm) - kugetsu server: show server subcommands (list, add, remove, default, get) Closes #244 --- skills/kugetsu/scripts/kugetsu | 251 +++++++++++++++++++++------------ 1 file changed, 164 insertions(+), 87 deletions(-) diff --git a/skills/kugetsu/scripts/kugetsu b/skills/kugetsu/scripts/kugetsu index 87fbccb..601ee45 100755 --- a/skills/kugetsu/scripts/kugetsu +++ b/skills/kugetsu/scripts/kugetsu @@ -17,77 +17,122 @@ usage() { kugetsu - OpenCode Session Manager (Issue-Driven) Usage: - kugetsu init [--force] Initialize base + pm-agent sessions (requires TTY) - kugetsu start [--debug] Start task for issue (forks base session) - kugetsu continue [message] [--debug] Continue existing task for issue - kugetsu delegate Send message to PM agent (fire-and-forget) - kugetsu logs [n] Show recent delegation logs (default: 10) - kugetsu status Check kugetsu initialization status - kugetsu doctor [--fix] Diagnose and fix kugetsu issues - kugetsu notify [list|clear] Show or clear notifications - kugetsu list List all tracked sessions - kugetsu prune [--force] Remove orphaned sessions (keeps base + pm-agent) - kugetsu destroy [-y] Delete session for issue - kugetsu destroy --pm-agent [-y] Delete pm-agent session (not recommended) - kugetsu destroy --base [-y] Delete base session - kugetsu set-pr Set PR URL for session (for PR tracking) - kugetsu context Show context for issue - kugetsu queue [list|stats|clear] Show queue status or statistics - kugetsu queue enqueue Enqueue a task (normally via delegate) - kugetsu queue-daemon [start|stop|restart|status|logs] Manage queue daemon - kugetsu env [get|set|list] Manage agent environment variables - kugetsu server [list|add|remove|default|get] Manage git server configurations - kugetsu help Show this help + kugetsu [subcommand] [options] + +Commands: + init [--force] Initialize base + pm-agent sessions (requires TTY) + start [--debug] Start task for issue (forks base session) + continue [message] [--debug] Continue existing task for issue + delegate Send message to PM agent (fire-and-forget) + logs [n] Show recent delegation logs (default: 10) + status Check kugetsu initialization status + doctor [--fix] Diagnose and fix kugetsu issues + notify [list|clear] Show or clear notifications + list List all tracked sessions + prune [--force] Remove orphaned sessions + destroy [-y] Delete session (issue, pm-agent, or base) + set-pr Set PR URL for session + context Show context for issue + queue [subcommand] Queue management + queue-daemon [subcommand] Queue daemon management + env [subcommand] Environment variable management + server [subcommand] Git server configuration + help [command] Show help for a command + +Use 'kugetsu help' for subcommand help. +Example: kugetsu queue help, kugetsu queue-daemon help Issue Ref Format: instance/user/repo#number Example: github.com/shoko/kugetsu#14 +EOF +} -Commands: - init Create base + pm-agent sessions via TUI. Requires terminal access. - Use --force to reinitialize if sessions exist. - start Fork new session from base for specific issue. - Requires pm-agent to be running (created by init). - continue Continue work on existing issue session. - delegate Send message to PM agent for task coordination. - Fire-and-forget: returns immediately, runs in background. - Use 'kugetsu logs' to check output. - logs Show recent delegation logs. - Default: 10 most recent. Use 'kugetsu logs 20' for more. - status Check if kugetsu is initialized and PM agent is active. - doctor Diagnose kugetsu issues. Use --fix to attempt repairs. - notify Show or clear notifications from PM agent. - Use 'kugetsu notify list' to see unread notifications. - list Show all sessions (base + pm-agent + forked issues). - prune Remove sessions not in index (orphaned from opencode). - Use --force to skip confirmation. - destroy Delete specific issue, pm-agent, or base session. +usage_queue() { + cat << 'EOF' +kugetsu queue - Queue management -Options: - --debug Show real-time debug output and capture to debug.log +Usage: + kugetsu queue [subcommand] -PM Context: - kugetsu reads ~/.kugetsu/pm-agent.md (if exists) and injects it - into the PM agent session at init time. This allows customizing PM - behavior without recreating the session. - -Notifications: - PM Agent writes task completion notifications to ~/.kugetsu/notifications.json - Use 'kugetsu notify list' to see unread notifications. +Subcommands: + list Show pending tasks (default) + stats Show queue statistics + clear Clear all queue items + enqueue Enqueue a task + help Show this help Examples: - kugetsu init - kugetsu status - kugetsu delegate "work on issue #5" - kugetsu logs - kugetsu logs 20 - kugetsu doctor - kugetsu doctor --fix - kugetsu notify list - kugetsu notify clear - kugetsu start github.com/shoko/kugetsu#14 "fix bug" - kugetsu continue github.com/shoko/kugetsu#14 "add tests" - kugetsu list + kugetsu queue list + kugetsu queue stats + kugetsu queue clear + kugetsu queue enqueue github.com/shoko/kugetsu#14 "fix bug" +EOF +} + +usage_queue_daemon() { + cat << 'EOF' +kugetsu queue-daemon - Queue daemon management + +Usage: + kugetsu queue-daemon [subcommand] + +Subcommands: + start Start the queue daemon + stop Stop the queue daemon + restart Restart the queue daemon + status Check daemon status + logs Show recent daemon logs + help Show this help + +Examples: + kugetsu queue-daemon start + kugetsu queue-daemon status + kugetsu queue-daemon logs +EOF +} + +usage_env() { + cat << 'EOF' +kugetsu env - Environment variable management + +Usage: + kugetsu env [subcommand] + +Subcommands: + list List all environment variables + get Get a specific variable + set Set a variable + rm Remove a variable + help Show this help + +Examples: + kugetsu env list + kugetsu env get GITEA_TOKEN + kugetsu env set CUSTOM_VAR "value" + kugetsu env rm CUSTOM_VAR +EOF +} + +usage_server() { + cat << 'EOF' +kugetsu server - Git server configuration + +Usage: + kugetsu server [subcommand] + +Subcommands: + list List all configured servers (default) + add Add a new server + remove Remove a server + default [] Get or set default server + get [] Get server URL + help Show this help + +Examples: + kugetsu server list + kugetsu server add github.com https://github.com + kugetsu server default github.com EOF } @@ -865,10 +910,15 @@ find_sessions_by_issue_number() { } cmd_queue() { - local action="${1:-list}" - shift + local action="${1:-}" case "$action" in + ""|help|--help|-h) + usage_queue + ;; + help|--help|-h) + usage_queue + ;; list) local pending_tasks=$(get_pending_tasks 10) if [ "$pending_tasks" = "[]" ]; then @@ -898,8 +948,8 @@ cmd_queue() { echo "Queue cleared." ;; enqueue) - local issue_ref="${1:-}" - local message="${2:-}" + local issue_ref="${2:-}" + local message="${3:-}" if [ -z "$issue_ref" ] || [ -z "$message" ]; then echo "Usage: kugetsu queue enqueue " >&2 exit 1 @@ -910,16 +960,20 @@ cmd_queue() { check_task_timeouts ;; *) - echo "Usage: kugetsu queue [list|stats|clear|enqueue]" >&2 + echo "Unknown queue subcommand: $action" >&2 + usage_queue exit 1 ;; esac } cmd_queue_daemon() { - local action="${1:-status}" + local action="${1:-}" case "$action" in + ""|help|--help|-h) + usage_queue_daemon + ;; start) if [ -f "$QUEUE_DAEMON_PID_FILE" ]; then local old_pid=$(cat "$QUEUE_DAEMON_PID_FILE") @@ -978,7 +1032,8 @@ cmd_queue_daemon() { fi ;; *) - echo "Usage: kugetsu queue-daemon [start|stop|restart|status|logs]" >&2 + echo "Unknown queue-daemon subcommand: $action" >&2 + usage_queue_daemon exit 1 ;; esac @@ -1059,10 +1114,12 @@ set_debug_mode() { } cmd_env() { - local action="${1:-list}" - shift + local action="${1:-}" case "$action" in + ""|help|--help|-h) + usage_env + ;; list) echo "Agent environment variables:" if [ -d "$ENV_DIR" ]; then @@ -1080,7 +1137,7 @@ cmd_env() { fi ;; get) - local key="${1:-}" + local key="${2:-}" if [ -z "$key" ]; then echo "Usage: kugetsu env get " >&2 exit 1 @@ -1095,8 +1152,8 @@ cmd_env() { fi ;; set) - local key="${1:-}" - local value="${2:-}" + local key="${2:-}" + local value="${3:-}" if [ -z "$key" ] || [ -z "$value" ]; then echo "Usage: kugetsu env set " >&2 exit 1 @@ -1105,8 +1162,8 @@ cmd_env() { echo "${key}=${value}" >> "$ENV_DIR/default.env" echo "Set $key in $ENV_DIR/default.env" ;; - rm) - local key="${1:-}" + rm|remove) + local key="${2:-}" if [ -z "$key" ]; then echo "Usage: kugetsu env rm " >&2 exit 1 @@ -1117,7 +1174,8 @@ cmd_env() { fi ;; *) - echo "Usage: kugetsu env [list|get|set|rm]" >&2 + echo "Unknown env subcommand: $action" >&2 + usage_env exit 1 ;; esac @@ -1127,7 +1185,10 @@ cmd_server() { local action="${1:-}" case "$action" in - ""|"list") + ""|help|--help|-h) + usage_server + ;; + "list") if [ -z "${GIT_SERVERS+x}" ]; then echo "No git servers configured" return @@ -1204,14 +1265,8 @@ cmd_server() { fi ;; *) - echo "Usage: kugetsu server " >&2 - echo "" >&2 - echo "Commands:" >&2 - echo " list List all configured git servers" >&2 - echo " add Add a new git server" >&2 - echo " remove Remove a git server" >&2 - echo " default [] Get or set default server" >&2 - echo " get [] Get URL for a server (default: current default)" >&2 + echo "Unknown server subcommand: $action" >&2 + usage_server exit 1 ;; esac @@ -1321,7 +1376,29 @@ main() { case "$command" in help|--help|-h) - usage + local subcommand="${1:-}" + case "$subcommand" in + queue|"") + usage_queue + ;; + queue-daemon) + usage_queue_daemon + ;; + env) + usage_env + ;; + server) + usage_server + ;; + "") + usage + ;; + *) + echo "Help not available for '$subcommand'" >&2 + usage + exit 1 + ;; + esac ;; init) cmd_init "$@" -- 2.49.1