superkick 0.1.0

data/lib/superkick/cli/completion.rb

@@ -0,0 +1,591 @@
+# frozen_string_literal: true
+
+module Superkick
+  class CLI < Thor
+    class Completion < Thor
+      package_name "superkick completion"
+
+      desc "install SHELL", "Print shell completion script (bash or zsh)"
+      def install(shell = "bash")
+        case shell.downcase
+        when "bash"
+          $stdout.puts bash_completion_script
+        when "zsh"
+          $stdout.puts zsh_completion_script
+        else
+          warn "Unsupported shell: #{shell}. Use 'bash' or 'zsh'."
+          exit(1)
+        end
+      end
+
+      # ── Hidden helper subcommands for dynamic completions ──────────────
+      # Each outputs newline-separated values suitable for shell completion.
+      # All silently return nothing when the server is unavailable.
+
+      desc "agents", "List agent IDs", hide: true
+      option :spawned, type: :boolean, default: false, desc: "Only spawned agents"
+      option :team, type: :string, desc: "Filter by team ID"
+      def agents
+        params = {}
+        params[:team_id] = options[:team] if options[:team]
+        params[:spawned_only] = true if options[:spawned]
+        result = control_client.request("list_agents", **params)
+        (result[:agents] || []).each { $stdout.puts it[:agent_id] }
+      rescue
+        nil
+      end
+
+      desc "team-ids", "List team IDs", hide: true
+      def team_ids
+        result = control_client.request("list_teams")
+        (result[:teams] || []).each { $stdout.puts it[:team_id] }
+      rescue
+        nil
+      end
+
+      desc "spawner-names", "List spawner names", hide: true
+      def spawner_names
+        result = control_client.request("list_spawners")
+        (result[:spawners] || []).each { $stdout.puts it[:name] }
+      rescue
+        nil
+      end
+
+      desc "approval-ids", "List pending approval IDs", hide: true
+      def approval_ids
+        result = control_client.request("list_approvals")
+        (result[:approvals] || []).each { $stdout.puts it[:id] }
+      rescue
+        nil
+      end
+
+      desc "monitor-types", "List registered monitor types", hide: true
+      def monitor_types
+        result = control_client.request("discover_monitors")
+        (result[:available_monitors] || []).each { $stdout.puts it[:type] }
+      rescue
+        nil
+      end
+
+      desc "monitors-for AGENT_ID", "List monitor names on an agent", hide: true
+      def monitors_for(agent_id)
+        result = control_client.request("list_monitors", agent_id:)
+        (result[:monitors] || []).each { $stdout.puts it[:name] }
+      rescue
+        nil
+      end
+
+      desc "notifier-types", "List registered notifier types", hide: true
+      def notifier_types
+        result = control_client.request("discover_notifiers")
+        (result[:available_notifiers] || []).each { $stdout.puts it[:type] }
+      rescue
+        nil
+      end
+
+      desc "notifiers-for AGENT_ID", "List notifier names on an agent", hide: true
+      def notifiers_for(agent_id)
+        result = control_client.request("list_notifiers", agent_id:)
+        (result[:notifiers] || []).each { $stdout.puts it[:name] }
+      rescue
+        nil
+      end
+
+      desc "goal-types", "List registered goal types", hide: true
+      def goal_types
+        result = control_client.request("discover_goals")
+        (result[:available_goals] || []).each { $stdout.puts it[:type] }
+      rescue
+        nil
+      end
+
+      desc "goal-statuses", "List valid goal statuses", hide: true
+      def goal_statuses
+        %w[completed failed errored in_progress].each { $stdout.puts it }
+      end
+
+      desc "driver-names", "List registered driver names", hide: true
+      def driver_names
+        Superkick::Driver.registered.each_key { $stdout.puts it }
+      end
+
+      desc "repository-names", "List configured repository names", hide: true
+      def repository_names
+        result = control_client.request("discover_repositories")
+        (result[:repositories] || []).each { $stdout.puts it[:name] }
+      rescue
+        nil
+      end
+
+      desc "artifact-authors TEAM_ID", "List artifact authors for a team", hide: true
+      def artifact_authors(team_id)
+        result = control_client.request("list_team_artifacts", team_id:)
+        seen = {}
+        (result[:artifacts] || []).each do |a|
+          unless seen[a[:author]]
+            $stdout.puts a[:author]
+            seen[a[:author]] = true
+          end
+        end
+      rescue
+        nil
+      end
+
+      desc "artifact-names TEAM_ID AUTHOR", "List artifact names for a team/author", hide: true
+      def artifact_names(team_id, author)
+        result = control_client.request("list_team_artifacts", team_id:, author:)
+        (result[:artifacts] || []).each { $stdout.puts it[:name] }
+      rescue
+        nil
+      end
+
+      default_command :install
+
+      private
+
+      def control_client
+        @control_client ||= Control.client_from
+      end
+
+      def bash_completion_script
+        <<~'BASH'
+          # Superkick shell completion — add to .bashrc or .bash_profile:
+          #   eval "$(superkick completion bash)"
+
+          _superkick_completions() {
+            local IFS=$'\n'
+            COMPREPLY=($(compgen -W "$1" -- "${COMP_WORDS[COMP_CWORD]}"))
+          }
+
+          _superkick_file_or_value() {
+            local cur="${COMP_WORDS[COMP_CWORD]}"
+            if [[ "$cur" == @* ]]; then
+              # Strip @ prefix, complete file paths, then re-add @
+              local prefix="${cur#@}"
+              COMPREPLY=($(compgen -f -- "$prefix"))
+              COMPREPLY=("${COMPREPLY[@]/#/@}")
+            fi
+          }
+
+          _superkick() {
+            local cur prev words cword
+            cur="${COMP_WORDS[COMP_CWORD]}"
+            prev="${COMP_WORDS[COMP_CWORD-1]}"
+            words=("${COMP_WORDS[@]}")
+            cword=$COMP_CWORD
+
+            # Top-level commands
+            if [[ $cword -eq 1 ]]; then
+              _superkick_completions "server agent monitor spawner mcp team goal notifier repository approve reject approvals completion setup help"
+              return
+            fi
+
+            local subcmd="${words[1]}"
+
+            case "$subcmd" in
+              agent)
+                if [[ $cword -eq 2 ]]; then
+                  _superkick_completions "start list cost log stop attach claim unclaim report-cost add-monitor remove-monitor add-notifier remove-notifier help"
+                  return
+                fi
+
+                local agent_subcmd="${words[2]}"
+                case "$agent_subcmd" in
+                  log|attach|report-cost|add-monitor|add-notifier)
+                    if [[ $cword -eq 3 ]]; then
+                      _superkick_completions "$(superkick completion agents 2>/dev/null)"
+                    fi
+                    ;;
+                  stop|claim)
+                    if [[ $cword -eq 3 ]]; then
+                      _superkick_completions "$(superkick completion agents --spawned 2>/dev/null)"
+                    fi
+                    ;;
+                  unclaim)
+                    if [[ $cword -eq 3 ]]; then
+                      _superkick_completions "$(superkick completion agents --spawned 2>/dev/null)"
+                    fi
+                    ;;
+                  cost)
+                    if [[ $cword -eq 3 ]]; then
+                      _superkick_completions "$(superkick completion agents 2>/dev/null)"
+                    fi
+                    ;;
+                  remove-monitor)
+                    if [[ $cword -eq 3 ]]; then
+                      _superkick_completions "$(superkick completion agents 2>/dev/null)"
+                    elif [[ $cword -eq 4 ]]; then
+                      _superkick_completions "$(superkick completion monitors-for "${words[3]}" 2>/dev/null)"
+                    fi
+                    ;;
+                  remove-notifier)
+                    if [[ $cword -eq 3 ]]; then
+                      _superkick_completions "$(superkick completion agents 2>/dev/null)"
+                    elif [[ $cword -eq 4 ]]; then
+                      _superkick_completions "$(superkick completion notifiers-for "${words[3]}" 2>/dev/null)"
+                    fi
+                    ;;
+                  start)
+                    case "$prev" in
+                      --driver|-d) _superkick_completions "$(superkick completion driver-names 2>/dev/null)" ;;
+                      --team) _superkick_completions "$(superkick completion team-ids 2>/dev/null)" ;;
+                      --driver_config_dir|--driver_command) compopt -o filenames; COMPREPLY=($(compgen -f -- "$cur")) ;;
+                    esac
+                    ;;
+                esac
+
+                # Option value completions for add-monitor/add-notifier
+                case "$agent_subcmd" in
+                  add-monitor)
+                    case "$prev" in
+                      --type|-t) _superkick_completions "$(superkick completion monitor-types 2>/dev/null)" ;;
+                      --config|-c) _superkick_file_or_value ;;
+                    esac
+                    ;;
+                  add-notifier)
+                    case "$prev" in
+                      --type|-t) _superkick_completions "$(superkick completion notifier-types 2>/dev/null)" ;;
+                      --config|-c) _superkick_file_or_value ;;
+                    esac
+                    ;;
+                esac
+                ;;
+
+              server)
+                if [[ $cword -eq 2 ]]; then
+                  _superkick_completions "start stop status log help"
+                fi
+                ;;
+
+              monitor)
+                if [[ $cword -eq 2 ]]; then
+                  _superkick_completions "list install-templates help"
+                fi
+                ;;
+
+              spawner)
+                if [[ $cword -eq 2 ]]; then
+                  _superkick_completions "list start stop install-templates help"
+                elif [[ $cword -eq 3 ]]; then
+                  case "${words[2]}" in
+                    start|stop) _superkick_completions "$(superkick completion spawner-names 2>/dev/null)" ;;
+                  esac
+                fi
+                ;;
+
+              mcp)
+                if [[ $cword -eq 2 ]]; then
+                  _superkick_completions "start configure help"
+                fi
+                ;;
+
+              team)
+                if [[ $cword -eq 2 ]]; then
+                  _superkick_completions "list status watch stop artifacts artifact message spawn-worker help"
+                  return
+                fi
+
+                local team_subcmd="${words[2]}"
+                case "$team_subcmd" in
+                  status|watch|stop|message|spawn-worker)
+                    if [[ $cword -eq 3 ]]; then
+                      _superkick_completions "$(superkick completion team-ids 2>/dev/null)"
+                    fi
+                    ;;
+                  artifacts)
+                    if [[ $cword -eq 3 ]]; then
+                      _superkick_completions "$(superkick completion team-ids 2>/dev/null)"
+                    fi
+                    case "$prev" in
+                      --author) _superkick_completions "$(superkick completion artifact-authors "${words[3]}" 2>/dev/null)" ;;
+                    esac
+                    ;;
+                  artifact)
+                    if [[ $cword -eq 3 ]]; then
+                      _superkick_completions "$(superkick completion team-ids 2>/dev/null)"
+                    elif [[ $cword -eq 4 ]]; then
+                      _superkick_completions "$(superkick completion artifact-authors "${words[3]}" 2>/dev/null)"
+                    elif [[ $cword -eq 5 ]]; then
+                      _superkick_completions "$(superkick completion artifact-names "${words[3]}" "${words[4]}" 2>/dev/null)"
+                    fi
+                    ;;
+                esac
+
+                # Option value completions for spawn-worker
+                if [[ "$team_subcmd" == "spawn-worker" ]]; then
+                  case "$prev" in
+                    --repository|-r) _superkick_completions "$(superkick completion repository-names 2>/dev/null)" ;;
+                    --goal_type) _superkick_completions "$(superkick completion goal-types 2>/dev/null)" ;;
+                    --depends_on) _superkick_completions "$(superkick completion agents --team "${words[3]}" 2>/dev/null)" ;;
+                  esac
+                fi
+                ;;
+
+              goal)
+                if [[ $cword -eq 2 ]]; then
+                  _superkick_completions "list signal help"
+                elif [[ $cword -eq 3 ]]; then
+                  case "${words[2]}" in
+                    signal) _superkick_completions "$(superkick completion agents --spawned 2>/dev/null)" ;;
+                  esac
+                elif [[ $cword -eq 4 ]]; then
+                  case "${words[2]}" in
+                    signal) _superkick_completions "$(superkick completion goal-statuses 2>/dev/null)" ;;
+                  esac
+                fi
+                ;;
+
+              notifier)
+                if [[ $cword -eq 2 ]]; then
+                  _superkick_completions "list help"
+                fi
+                ;;
+
+              repository)
+                if [[ $cword -eq 2 ]]; then
+                  _superkick_completions "list help"
+                fi
+                ;;
+
+              approve)
+                if [[ $cword -eq 2 ]]; then
+                  _superkick_completions "$(superkick completion approval-ids 2>/dev/null)"
+                fi
+                ;;
+
+              reject)
+                if [[ $cword -eq 2 ]]; then
+                  _superkick_completions "$(superkick completion approval-ids 2>/dev/null)"
+                fi
+                ;;
+
+              completion)
+                if [[ $cword -eq 2 ]]; then
+                  _superkick_completions "install bash zsh"
+                fi
+                ;;
+            esac
+          }
+
+          complete -F _superkick superkick
+        BASH
+      end
+
+      def zsh_completion_script
+        <<~'ZSH'
+          # Superkick shell completion — add to .zshrc:
+          #   eval "$(superkick completion zsh)"
+
+          _superkick_from() {
+            local completions
+            completions=(${(f)"$(eval "$@" 2>/dev/null)"})
+            compadd -a completions
+          }
+
+          _superkick_file_or_value() {
+            local cur="${words[CURRENT]}"
+            if [[ "$cur" == @* ]]; then
+              # Strip @ prefix, complete file paths, then re-add @
+              local prefix="${cur#@}"
+              local -a files
+              files=(${(f)"$(compgen -f -- "$prefix" 2>/dev/null)"})
+              if [[ ${#files} -eq 0 ]]; then
+                _files -W / -P @
+              else
+                compadd -p @ -a files
+              fi
+            fi
+          }
+
+          _superkick() {
+            local -a subcmds agent_cmds server_cmds monitor_cmds spawner_cmds mcp_cmds
+            local -a team_cmds goal_cmds notifier_cmds repository_cmds
+
+            subcmds=(server agent monitor spawner mcp team goal notifier repository approve reject approvals completion setup help)
+            agent_cmds=(start list cost log stop attach claim unclaim report-cost add-monitor remove-monitor add-notifier remove-notifier help)
+            server_cmds=(start stop status log help)
+            monitor_cmds=(list install-templates help)
+            spawner_cmds=(list start stop install-templates help)
+            mcp_cmds=(start configure help)
+            team_cmds=(list status watch stop artifacts artifact message spawn-worker help)
+            goal_cmds=(list signal help)
+            notifier_cmds=(list help)
+            repository_cmds=(list help)
+
+            if (( CURRENT == 2 )); then
+              _describe 'command' subcmds
+              return
+            fi
+
+            case "${words[2]}" in
+              agent)
+                if (( CURRENT == 3 )); then
+                  _describe 'subcommand' agent_cmds
+                  return
+                fi
+
+                local agent_subcmd="${words[3]}"
+                case "$agent_subcmd" in
+                  log|attach|report-cost|add-monitor|add-notifier)
+                    if (( CURRENT == 4 )); then
+                      _superkick_from "superkick completion agents"
+                    fi
+                    ;;
+                  stop|claim|unclaim)
+                    if (( CURRENT == 4 )); then
+                      _superkick_from "superkick completion agents --spawned"
+                    fi
+                    ;;
+                  cost)
+                    if (( CURRENT == 4 )); then
+                      _superkick_from "superkick completion agents"
+                    fi
+                    ;;
+                  remove-monitor)
+                    if (( CURRENT == 4 )); then
+                      _superkick_from "superkick completion agents"
+                    elif (( CURRENT == 5 )); then
+                      _superkick_from "superkick completion monitors-for '${words[4]}'"
+                    fi
+                    ;;
+                  remove-notifier)
+                    if (( CURRENT == 4 )); then
+                      _superkick_from "superkick completion agents"
+                    elif (( CURRENT == 5 )); then
+                      _superkick_from "superkick completion notifiers-for '${words[4]}'"
+                    fi
+                    ;;
+                  start)
+                    case "${words[CURRENT-1]}" in
+                      --driver|-d) _superkick_from "superkick completion driver-names" ;;
+                      --team) _superkick_from "superkick completion team-ids" ;;
+                      --driver_config_dir|--driver_command) _files ;;
+                    esac
+                    ;;
+                esac
+
+                # Option value completions
+                case "$agent_subcmd" in
+                  add-monitor)
+                    case "${words[CURRENT-1]}" in
+                      --type|-t) _superkick_from "superkick completion monitor-types" ;;
+                      --config|-c) _superkick_file_or_value ;;
+                    esac
+                    ;;
+                  add-notifier)
+                    case "${words[CURRENT-1]}" in
+                      --type|-t) _superkick_from "superkick completion notifier-types" ;;
+                      --config|-c) _superkick_file_or_value ;;
+                    esac
+                    ;;
+                esac
+                ;;
+
+              server)
+                if (( CURRENT == 3 )); then _describe 'subcommand' server_cmds; fi ;;
+
+              monitor)
+                if (( CURRENT == 3 )); then _describe 'subcommand' monitor_cmds; fi ;;
+
+              spawner)
+                if (( CURRENT == 3 )); then
+                  _describe 'subcommand' spawner_cmds
+                elif (( CURRENT == 4 )); then
+                  case "${words[3]}" in
+                    start|stop) _superkick_from "superkick completion spawner-names" ;;
+                  esac
+                fi
+                ;;
+
+              mcp)
+                if (( CURRENT == 3 )); then _describe 'subcommand' mcp_cmds; fi ;;
+
+              team)
+                if (( CURRENT == 3 )); then
+                  _describe 'subcommand' team_cmds
+                  return
+                fi
+
+                local team_subcmd="${words[3]}"
+                case "$team_subcmd" in
+                  status|watch|stop|message|spawn-worker)
+                    if (( CURRENT == 4 )); then
+                      _superkick_from "superkick completion team-ids"
+                    fi
+                    ;;
+                  artifacts)
+                    if (( CURRENT == 4 )); then
+                      _superkick_from "superkick completion team-ids"
+                    fi
+                    case "${words[CURRENT-1]}" in
+                      --author) _superkick_from "superkick completion artifact-authors '${words[4]}'" ;;
+                    esac
+                    ;;
+                  artifact)
+                    if (( CURRENT == 4 )); then
+                      _superkick_from "superkick completion team-ids"
+                    elif (( CURRENT == 5 )); then
+                      _superkick_from "superkick completion artifact-authors '${words[4]}'"
+                    elif (( CURRENT == 6 )); then
+                      _superkick_from "superkick completion artifact-names '${words[4]}' '${words[5]}'"
+                    fi
+                    ;;
+                esac
+
+                # Option value completions for spawn-worker
+                if [[ "$team_subcmd" == "spawn-worker" ]]; then
+                  case "${words[CURRENT-1]}" in
+                    --repository|-r) _superkick_from "superkick completion repository-names" ;;
+                    --goal_type) _superkick_from "superkick completion goal-types" ;;
+                    --depends_on) _superkick_from "superkick completion agents --team '${words[4]}'" ;;
+                  esac
+                fi
+                ;;
+
+              goal)
+                if (( CURRENT == 3 )); then
+                  _describe 'subcommand' goal_cmds
+                elif (( CURRENT == 4 )); then
+                  case "${words[3]}" in
+                    signal) _superkick_from "superkick completion agents --spawned" ;;
+                  esac
+                elif (( CURRENT == 5 )); then
+                  case "${words[3]}" in
+                    signal) _superkick_from "superkick completion goal-statuses" ;;
+                  esac
+                fi
+                ;;
+
+              notifier)
+                if (( CURRENT == 3 )); then _describe 'subcommand' notifier_cmds; fi ;;
+
+              repository)
+                if (( CURRENT == 3 )); then _describe 'subcommand' repository_cmds; fi ;;
+
+              approve)
+                if (( CURRENT == 3 )); then
+                  _superkick_from "superkick completion approval-ids"
+                fi
+                ;;
+
+              reject)
+                if (( CURRENT == 3 )); then
+                  _superkick_from "superkick completion approval-ids"
+                fi
+                ;;
+
+              completion)
+                if (( CURRENT == 3 )); then
+                  local -a comp_cmds=(install bash zsh)
+                  _describe 'subcommand' comp_cmds
+                fi
+                ;;
+            esac
+          }
+
+          compdef _superkick superkick
+        ZSH
+      end
+    end
+  end
+end

data/lib/superkick/cli/goal.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Superkick
+  class CLI < Thor
+    class GoalCmd < Thor
+      package_name "superkick goal"
+
+      desc "list", "List available goal types"
+      def list
+        client = Control.client_from
+
+        unless client.alive?
+          $stdout.puts "Superkick server is not running."
+          return
+        end
+
+        result = client.request("discover_goals")
+        goals = result[:available_goals] || []
+
+        if goals.empty?
+          $stdout.puts "No goal types registered."
+          return
+        end
+
+        goals.each do |goal|
+          $stdout.puts "#{goal[:type]}:"
+          $stdout.puts "  #{goal[:description]}" if goal[:description]
+          $stdout.puts "  required config: #{goal[:required_config].join(", ")}" if goal[:required_config]&.any?
+          $stdout.puts ""
+        end
+      rescue Control::Client::ServerUnavailable
+        $stdout.puts "Superkick server is not running."
+      end
+
+      desc "signal AGENT_ID STATUS", "Signal a spawned agent's goal status"
+      long_desc <<~DESC
+        Signal the goal status of a spawned agent. Useful when a human has claimed
+        an agent and completed its task manually, or to force-complete a stuck agent
+        so downstream workflows fire correctly.
+
+        STATUS must be one of: completed, failed, errored, in_progress
+      DESC
+      option :summary, type: :string, aliases: "-s",
+        desc: "Brief summary of the outcome (forwarded to retry agents in workflow chains)"
+      def signal(agent_id, status)
+        unless %w[completed failed errored in_progress].include?(status)
+          warn "Invalid status: #{status}. Must be one of: completed, failed, errored, in_progress"
+          exit(1)
+        end
+
+        client = Control.client_from
+        result = client.request("signal_goal",
+          agent_id:,
+          status:,
+          summary: options[:summary])
+
+        if result.success?
+          $stdout.puts "Goal signaled: #{agent_id} -> #{status}"
+        else
+          warn "Error: #{result.error_message}"
+          exit(1)
+        end
+      rescue Control::Client::ServerUnavailable
+        warn "Superkick server is not running."
+        exit(1)
+      end
+
+      default_command :list
+    end
+  end
+end

data/lib/superkick/cli/mcp.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Superkick
+  class CLI < Thor
+    class Mcp < Thor
+      package_name "superkick mcp"
+
+      desc "start", "Start the MCP stdio server (called by AI CLI, not users)"
+      def start
+        Superkick.load_config!
+
+        if Superkick.config.server_type == :hosted
+          Hosted::McpProxy.start
+        else
+          McpServer.start
+        end
+      end
+
+      desc "configure", "Configure the MCP server for the active driver"
+      def configure
+        Superkick.load_config!
+
+        unless Superkick.driver
+          warn "No driver configured. Set `driver:` in ~/.superkick/config.yml first."
+          exit(1)
+        end
+
+        Superkick.driver.install_mcp(exe_path: File.expand_path($PROGRAM_NAME))
+      end
+
+      default_command :start
+    end
+  end
+end