superkick 0.1.0

data/lib/superkick/cli/team.rb

@@ -0,0 +1,407 @@
+# frozen_string_literal: true
+
+module Superkick
+  class CLI < Thor
+    class Team < Thor
+      package_name "superkick team"
+
+      desc "list", "List active teams"
+      option :json, type: :boolean, default: false, desc: "Output as JSON"
+      def list
+        client = Control.client_from
+
+        unless client.alive?
+          $stdout.puts "Superkick server is not running."
+          return
+        end
+
+        resp = client.request("list_teams")
+        teams = resp[:teams] || []
+
+        if options[:json]
+          $stdout.puts JSON.pretty_generate(teams)
+          return
+        end
+
+        if teams.empty?
+          $stdout.puts "No active teams."
+          return
+        end
+
+        teams.each do |t|
+          $stdout.puts "Team: #{t[:team_id]} (#{t[:agent_count]} agents)"
+          # Fetch members for this team
+          members_resp = client.request("list_agents", team_id: t[:team_id])
+          (members_resp[:agents] || []).each do |m|
+            team_role = m[:team_role] || "unknown"
+            status = m[:goal_status] || "active"
+            label = m[:role] ? "#{team_role}/#{m[:role]}" : team_role.to_s
+            line = "  #{m[:agent_id].ljust(40)} #{label.ljust(20)} [#{status}]"
+            $stdout.puts line
+          end
+          $stdout.puts ""
+        end
+      rescue Control::Client::ServerUnavailable
+        $stdout.puts "Superkick server is not running."
+      end
+
+      desc "status TEAM_ID", "Show team log summary"
+      option :full, type: :boolean, default: false, desc: "Show full team log"
+      option :json, type: :boolean, default: false, desc: "Output as JSON"
+      def status(team_id)
+        client = Control.client_from
+        result = client.request("team_status", team_id:, full_log: options[:full])
+
+        if options[:json]
+          $stdout.puts JSON.pretty_generate(result.payload)
+          return
+        end
+
+        payload = result.payload
+        $stdout.puts "Team: #{payload[:team_id]} (#{payload[:teammates]&.size || 0} agents)"
+        $stdout.puts ""
+
+        (payload[:teammates] || []).each do |t|
+          team_role = t[:team_role] || "unknown"
+          status = t[:goal_status] || "active"
+          label = t[:role] ? "#{team_role}/#{t[:role]}" : team_role.to_s
+          $stdout.puts "  #{t[:agent_id]} (#{label}) [#{status}]"
+        end
+
+        latest = payload[:latest] || []
+        if latest.any?
+          $stdout.puts ""
+          $stdout.puts "Latest updates:"
+          latest.each do |entry|
+            $stdout.puts "  [#{entry[:agent_id]}] [#{entry[:category]}] #{entry[:message]}"
+          end
+        end
+
+        blockers = payload[:unresolved_blockers] || []
+        if blockers.any?
+          $stdout.puts ""
+          $stdout.puts "Unresolved blockers:"
+          blockers.each do |b|
+            $stdout.puts "  [#{b[:agent_id]}] #{b[:message]}"
+          end
+        end
+
+        entries = payload[:entries] || []
+        if entries.any?
+          $stdout.puts ""
+          $stdout.puts "Full log:"
+          entries.each do |e|
+            $stdout.puts "  #{e[:timestamp]} [#{e[:agent_id]}] [#{e[:category]}] #{e[:message]}"
+          end
+        end
+      rescue Control::Client::ServerUnavailable
+        warn "Superkick server is not running."
+        exit(1)
+      end
+
+      desc "watch TEAM_ID", "Watch team activity in real time"
+      option :no_color, type: :boolean, default: false, desc: "Disable colored output"
+      def watch(team_id)
+        client = Control.client_from
+
+        unless client.alive?
+          warn "Superkick server is not running."
+          exit(1)
+        end
+
+        use_color = !options[:no_color] && $stdout.tty? && !ENV["NO_COLOR"]
+        since = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%6NZ")
+
+        $stdout.puts "Watching team #{team_id}... (Ctrl-C to stop)"
+        $stdout.puts ""
+
+        loop do
+          result = client.request("team_status", team_id:, full_log: true, since:)
+          entries = result.payload[:entries] || []
+
+          entries.each do |e|
+            since = e[:timestamp]
+            $stdout.puts format_watch_entry(e, use_color:)
+          end
+
+          sleep 2
+        rescue Interrupt
+          break
+        end
+
+        $stdout.puts "\nDone."
+      rescue Control::Client::ServerUnavailable
+        warn "Superkick server is not running."
+        exit(1)
+      end
+
+      desc "stop TEAM_ID", "Terminate all agents in a team"
+      def stop(team_id)
+        client = Control.client_from
+
+        resp = client.request("list_agents", team_id:)
+        agents = resp[:agents] || []
+
+        if agents.empty?
+          warn "No agents found for team: #{team_id}"
+          exit(1)
+        end
+
+        terminated = 0
+        agents.each do |a|
+          next unless a[:spawn_info] # Only terminate spawned agents
+          begin
+            client.request("terminate_agent", agent_id: a[:agent_id])
+            terminated += 1
+          rescue => e
+            warn "Failed to terminate #{a[:agent_id]}: #{e.message}"
+          end
+        end
+
+        $stdout.puts "Terminated #{terminated} agent(s) in team #{team_id}."
+      rescue Control::Client::ServerUnavailable
+        warn "Superkick server is not running."
+        exit(1)
+      end
+
+      desc "artifacts TEAM_ID", "List artifacts for a team"
+      option :json, type: :boolean, default: false, desc: "Output as JSON"
+      option :author, type: :string, desc: "Filter by author agent ID"
+      def artifacts(team_id)
+        client = Control.client_from
+        result = client.request("list_team_artifacts", team_id:, author: options[:author])
+
+        if result.error?
+          warn "Error: #{result.error_message}"
+          exit(1)
+        end
+
+        artifacts = result[:artifacts] || []
+
+        if options[:json]
+          $stdout.puts JSON.pretty_generate(artifacts)
+          return
+        end
+
+        if artifacts.empty?
+          $stdout.puts "No artifacts for team #{team_id}."
+          return
+        end
+
+        artifacts.each do |a|
+          $stdout.puts "#{a[:author]}/#{a[:name]}"
+          $stdout.puts "  Created:  #{a[:created_at]}"
+          $stdout.puts "  Updated:  #{a[:updated_at]}"
+          $stdout.puts ""
+        end
+      rescue Control::Client::ServerUnavailable
+        warn "Superkick server is not running."
+        exit(1)
+      end
+
+      desc "artifact TEAM_ID AUTHOR NAME", "Read a team artifact"
+      option :json, type: :boolean, default: false, desc: "Output as JSON"
+      def artifact(team_id, author, name)
+        client = Control.client_from
+        result = client.request("read_team_artifact", team_id:, author:, name:)
+
+        if result.error?
+          warn "Error: #{result.error_message}"
+          exit(1)
+        end
+
+        if options[:json]
+          $stdout.puts JSON.pretty_generate(result.payload)
+          return
+        end
+
+        $stdout.puts "#{result[:author]}/#{result[:name]}"
+        $stdout.puts "Created:  #{result[:created_at]}"
+        $stdout.puts "Updated:  #{result[:updated_at]}"
+        $stdout.puts ""
+        $stdout.puts result[:content]
+      rescue Control::Client::ServerUnavailable
+        warn "Superkick server is not running."
+        exit(1)
+      end
+
+      desc "message TEAM_ID MESSAGE", "Send a message to all agents on a team"
+      long_desc <<~DESC
+        Broadcast a high-priority message to every agent on a team. The message
+        is injected into each agent's prompt and recorded in the team log.
+
+        Useful for operator directives like "shift priority to the API migration"
+        or "stop working on feature X".
+      DESC
+      def message(team_id, *message_parts)
+        message = message_parts.join(" ")
+        if message.empty?
+          warn "Usage: superkick team message TEAM_ID MESSAGE"
+          exit(1)
+        end
+
+        client = Control.client_from
+        result = client.request("post_team_message", team_id:, message:)
+
+        if result.success?
+          $stdout.puts "Message delivered to #{result[:delivered_to]} agent(s)."
+        else
+          warn "Error: #{result.error_message}"
+          exit(1)
+        end
+      rescue Control::Client::ServerUnavailable
+        warn "Superkick server is not running."
+        exit(1)
+      end
+
+      desc "spawn-worker TEAM_ID", "Spawn a worker agent into an existing team"
+      long_desc <<~DESC
+        Spawn a new worker agent into an existing team. The worker gets its own
+        working copy of the specified repository and receives the task as its
+        kickoff prompt. The agent ID is auto-generated from the team ID and role.
+
+        The --task text is injected as the agent's initial prompt, so write it as
+        instructions you'd give to a developer. The --role label appears in team
+        status and helps teammates understand each other's responsibilities.
+
+        Workers use agent_signal as the default goal type, meaning they signal
+        completion by calling the superkick_signal_goal MCP tool. Use --goal-type
+        to override (e.g. "command" for a shell-based goal check).
+
+        The --depends-on flag is informational only — it records which agents this
+        worker depends on but does not enforce ordering.
+
+        Examples:
+
+          superkick team spawn-worker my-team -r api \\
+            --task "Add rate limiting to the /users endpoint" \\
+            --role "Rate limiter"
+
+          superkick team spawn-worker my-team -r web \\
+            --task "Write integration tests for checkout" \\
+            --goal-type command --depends-on agent-a agent-b
+      DESC
+      option :repository, type: :string, aliases: "-r", required: true,
+        desc: "Repository name from the registry"
+      option :task, type: :string, required: true,
+        desc: "Detailed instructions for the worker (kickoff prompt)"
+      option :role, type: :string,
+        desc: "Human-readable role label (e.g. 'Rate limiter')"
+      option :goal_type, type: :string,
+        desc: "Goal type for the worker (default: agent_signal)"
+      option :depends_on, type: :array,
+        desc: "Agent IDs this worker depends on (informational)"
+      option :monitors, type: :string,
+        desc: "JSON/YAML config string or @filepath for monitors to pre-attach"
+      option :notifiers, type: :string,
+        desc: "JSON/YAML config string or @filepath for notifiers to pre-attach"
+      def spawn_worker(team_id)
+        client = Control.client_from
+
+        params = {
+          team_id:,
+          repository: options[:repository],
+          task: options[:task]
+        }
+        params[:role] = options[:role] if options[:role]
+        params[:goal] = {type: options[:goal_type]} if options[:goal_type]
+        params[:depends_on] = options[:depends_on] if options[:depends_on]
+        params[:monitors] = parse_config(options[:monitors]) if options[:monitors]
+        params[:notifiers] = parse_config(options[:notifiers]) if options[:notifiers]
+
+        result = client.request("spawn_worker_by_team", **params)
+
+        if result.success?
+          $stdout.puts "Worker spawned: #{result[:agent_id]}"
+        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
+
+      private
+
+      def parse_config(value)
+        return {} unless value
+
+        raw = if value.start_with?("@")
+          path = File.expand_path(value[1..])
+          unless File.exist?(path)
+            warn "Config file not found: #{path}"
+            exit(1)
+          end
+          File.read(path)
+        else
+          value
+        end
+
+        parsed = YAML.safe_load(raw, symbolize_names: true)
+        unless parsed.is_a?(Hash)
+          warn "Config must be a YAML/JSON object, got: #{parsed.class}"
+          exit(1)
+        end
+        parsed
+      rescue Psych::SyntaxError => e
+        warn "Invalid YAML/JSON config: #{e.message}"
+        exit(1)
+      end
+
+      def format_watch_entry(entry, use_color:)
+        ts = entry[:timestamp]&.then { |t| t[11, 8] } || "??:??:??"
+        agent = entry[:agent_id] || "unknown"
+        category = entry[:category]&.to_sym
+        kind = entry[:kind]
+        message = entry[:message] || ""
+        role_label = entry[:role] ? " (#{entry[:role]})" : ""
+
+        line = case category
+        when :update
+          kind_str = kind ? "[#{kind}]" : ""
+          "[#{ts}] #{agent}#{role_label} #{kind_str} #{message}"
+        when :message
+          target = entry[:target_agent_id] || "?"
+          "[#{ts}] #{agent}#{role_label} -> #{target}: #{message}"
+        when :lifecycle
+          "[#{ts}] * #{agent} #{kind}#{": #{message}" unless message.empty?}"
+        when :artifact
+          artifact_name = entry[:artifact_name] || "?"
+          "[#{ts}] #{agent} published \"#{artifact_name}\""
+        else
+          "[#{ts}] [#{category}] #{agent}: #{message}"
+        end
+
+        return line unless use_color
+
+        colorize_entry(line, category, kind)
+      end
+
+      def colorize_entry(line, category, kind)
+        case category
+        when :update
+          case kind&.to_sym
+          when :blocker then "\e[31m#{line}\e[0m"
+          when :completed then "\e[32m#{line}\e[0m"
+          when :decision then "\e[36m#{line}\e[0m"
+          when :progress then "\e[33m#{line}\e[0m"
+          else line
+          end
+        when :lifecycle
+          case kind&.to_sym
+          when :completed, :joined then "\e[32m#{line}\e[0m"
+          when :failed, :timed_out then "\e[31m#{line}\e[0m"
+          when :blocked then "\e[33m#{line}\e[0m"
+          else "\e[2m#{line}\e[0m"
+          end
+        when :message then "\e[36m#{line}\e[0m"
+        when :artifact then "\e[35m#{line}\e[0m"
+        else line
+        end
+      end
+    end
+  end
+end

data/lib/superkick/cli.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "thor"
+require_relative "cli/server"
+require_relative "cli/agent"
+require_relative "cli/monitor"
+require_relative "cli/spawner"
+require_relative "cli/mcp"
+require_relative "cli/team"
+require_relative "cli/goal"
+require_relative "cli/notifier"
+require_relative "cli/repository"
+require_relative "cli/completion"
+require_relative "cli/setup"
+
+module Superkick
+  class CLI < Thor
+    package_name "superkick"
+
+    class_option :dir, type: :string, aliases: "-C",
+      desc: "Superkick base directory (default: ~/.superkick)"
+
+    def initialize(*args)
+      super
+      Superkick.configure { |c| c.base_dir = File.expand_path(options[:dir]) } if options[:dir]
+    end
+
+    register Server, "server", "server SUBCOMMAND", "Manage the Superkick server"
+    register Agent, "agent", "agent SUBCOMMAND", "Manage Superkick agents"
+    register MonitorCmd, "monitor", "monitor SUBCOMMAND", "Manage monitors"
+    register Spawner, "spawner", "spawner SUBCOMMAND", "Manage spawner monitors"
+    register Mcp, "mcp", "mcp SUBCOMMAND", "Manage MCP server"
+    register Team, "team", "team SUBCOMMAND", "Manage agent teams"
+    register GoalCmd, "goal", "goal SUBCOMMAND", "Manage goal types"
+    register NotifierCmd, "notifier", "notifier SUBCOMMAND", "Manage notifier types"
+    register RepositoryCmd, "repository", "repository SUBCOMMAND", "Manage repositories"
+    register Completion, "completion", "completion SUBCOMMAND", "Shell completion scripts and helpers"
+    register Setup, "setup", "setup", "Interactive first-time setup"
+
+    # ── Approval gates ──────────────────────────────────────────────────
+
+    desc "approve ID", "Approve a pending spawn"
+    def approve(approval_id)
+      client = Control.client_from
+      reply = client.request("approve", approval_id:)
+
+      if reply.success?
+        $stdout.puts "Approved. Agent #{reply[:agent_id] || approval_id} spawning."
+      else
+        warn "Error: #{reply.error_message}"
+        exit(1)
+      end
+    rescue Control::Client::ServerUnavailable
+      warn "Superkick server is not running."
+      exit(1)
+    end
+
+    desc "reject ID", "Reject a pending spawn"
+    option :reason, type: :string, aliases: "-r",
+      desc: "Reason for rejection"
+    option :clear, type: :boolean, default: false,
+      desc: "Clear a specific rejection to allow re-dispatch"
+    option :clear_all, type: :boolean, default: false,
+      desc: "Clear all rejections"
+    def reject(approval_id = nil)
+      client = Control.client_from
+
+      if options[:clear_all]
+        reply = client.request("clear_all_rejections")
+        if reply.success?
+          $stdout.puts "Cleared all rejections."
+        else
+          warn "Error: #{reply.error_message}"
+          exit(1)
+        end
+        return
+      end
+
+      unless approval_id
+        warn "Usage: superkick reject ID [--reason REASON]"
+        exit(1)
+      end
+
+      if options[:clear]
+        reply = client.request("clear_rejection", approval_id:)
+        if reply.success?
+          $stdout.puts "Cleared rejection for #{approval_id}."
+        else
+          warn "Error: #{reply.error_message}"
+          exit(1)
+        end
+        return
+      end
+
+      reply = client.request("reject", approval_id:, reason: options[:reason])
+
+      if reply.success?
+        $stdout.puts "Rejected approval #{approval_id}."
+      else
+        warn "Error: #{reply.error_message}"
+        exit(1)
+      end
+    rescue Control::Client::ServerUnavailable
+      warn "Superkick server is not running."
+      exit(1)
+    end
+
+    desc "approvals", "List pending spawn approvals and rejections"
+    option :json, type: :boolean, default: false, desc: "Output as JSON"
+    option :rejections, type: :boolean, default: false, desc: "Show rejections instead"
+    def approvals
+      client = Control.client_from
+
+      unless client.alive?
+        $stdout.puts "Superkick server is not running."
+        return
+      end
+
+      if options[:rejections]
+        show_rejections(client)
+      else
+        show_approvals(client)
+      end
+    rescue Control::Client::ServerUnavailable
+      $stdout.puts "Superkick server is not running."
+    end
+
+    private
+
+    def show_approvals(client)
+      result = client.request("list_approvals")
+      approvals = result[:approvals] || []
+
+      if options[:json]
+        $stdout.puts JSON.pretty_generate(approvals)
+        return
+      end
+
+      if approvals.empty?
+        $stdout.puts "No pending approvals."
+        return
+      end
+
+      approvals.each do |a|
+        $stdout.puts a[:id].to_s
+        $stdout.puts "  Spawner:    #{a[:spawner_name]}"
+        $stdout.puts "  Event:      #{a[:event_type]}"
+        $stdout.puts "  Created at: #{a[:created_at]}"
+        $stdout.puts ""
+      end
+    end
+
+    def show_rejections(client)
+      result = client.request("list_rejections")
+      rejections = result[:rejections] || []
+
+      if options[:json]
+        $stdout.puts JSON.pretty_generate(rejections)
+        return
+      end
+
+      if rejections.empty?
+        $stdout.puts "No rejections."
+        return
+      end
+
+      rejections.each do |r|
+        $stdout.puts r[:id].to_s
+        $stdout.puts "  Rejected at: #{r[:rejected_at]}"
+        $stdout.puts "  Reason:      #{r[:reason]}" if r[:reason]
+        $stdout.puts ""
+      end
+    end
+  end
+end

data/lib/superkick/client_registry.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Shared registry for client factory methods.
+  #
+  # Each namespace module (Control, Buffer, Attach) extends this to get
+  # `register_client` and `client_from`. The base Client class in each
+  # namespace defines a `from` class method that knows how to build
+  # itself from config.
+  #
+  # Example:
+  #   Superkick::Control.register_client(:hosted, Superkick::Hosted::Control::Client)
+  #   client = Superkick::Control.client_from(config:)
+  module ClientRegistry
+    def register_client(type, klass)
+      @clients[type] = klass
+    end
+
+    def client_from(config: Superkick.config, **kwargs)
+      type = config.server_type
+      if type == :local
+        self::Client.from(config:, **kwargs)
+      elsif (klass = @clients[type])
+        klass.from(config:, **kwargs)
+      else
+        raise ArgumentError, "Unknown server type: #{type}"
+      end
+    end
+  end
+end