brainiac-basecamp 0.0.1

data/lib/brainiac/plugins/basecamp/cli.rb

@@ -0,0 +1,411 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Brainiac
+  module Plugins
+    module Basecamp
+      module Cli
+        BRAINIAC_DIR = ENV.fetch("BRAINIAC_DIR", File.join(Dir.home, ".brainiac"))
+        CONFIG_FILE = File.join(BRAINIAC_DIR, "basecamp.json")
+
+        class << self
+          def run(args)
+            command = args.shift
+
+            case command
+            when "setup"
+              cmd_setup
+            when "config"
+              cmd_config
+            when "status"
+              cmd_status
+            when "epics"
+              cmd_epics(args)
+            when "link"
+              cmd_link(args)
+            when "bot"
+              cmd_bot(args)
+            when "projects"
+              cmd_projects(args)
+            when "set"
+              cmd_set(args)
+            else
+              print_help
+            end
+          end
+
+          private
+
+          def cmd_setup
+            puts "Basecamp Plugin Setup"
+            puts "====================="
+            puts ""
+
+            # Check if basecamp CLI is installed
+            unless system("which basecamp > /dev/null 2>&1")
+              puts "❌ basecamp CLI not found. Install it first:"
+              puts "   curl -fsSL https://basecamp.com/install-cli | bash"
+              return
+            end
+            puts "✓ basecamp CLI found"
+
+            # Check auth status
+            auth_output = `basecamp auth status --json 2>/dev/null`
+            if $?.success? && !auth_output.empty?
+              puts "✓ Authenticated with Basecamp"
+            else
+              puts "❌ Not authenticated. Run: basecamp auth login"
+              return
+            end
+
+            # Create config if it doesn't exist
+            unless File.exist?(CONFIG_FILE)
+              default_config = {
+                "bot_accounts" => {},
+                "project_mappings" => {},
+                "epic_prefix" => "Epic:",
+                "fizzy_account_id" => nil,
+                "review_gate" => "on_complete",
+                "notifications" => {
+                  "epic_started" => true,
+                  "task_dispatched" => true,
+                  "task_completed" => true,
+                  "epic_completed" => true
+                }
+              }
+              File.write(CONFIG_FILE, JSON.pretty_generate(default_config))
+              puts "✓ Created #{CONFIG_FILE}"
+            else
+              puts "✓ Config exists at #{CONFIG_FILE}"
+            end
+
+            puts ""
+            puts "Next steps:"
+            puts "  1. Set Fizzy account ID:  brainiac basecamp set fizzy-account-id <your-fizzy-account-id>"
+            puts "  2. Add bot accounts:     brainiac basecamp bot add <name> <person-id> <agent>"
+            puts "  3. Map projects:         brainiac basecamp projects map <brainiac-key> <basecamp-id>"
+            puts "  4. Set review gate:      brainiac basecamp set review-gate <on_complete|on_pr_merge>"
+            puts "  5. Set up webhooks:      basecamp webhooks create \"https://your-ngrok/basecamp\" --types \"Todo,Todolist\" --in <project>"
+            puts "  6. Restart brainiac:     brainiac restart"
+          end
+
+          def cmd_config
+            if File.exist?(CONFIG_FILE)
+              config = JSON.parse(File.read(CONFIG_FILE))
+              puts JSON.pretty_generate(config)
+            else
+              puts "No config found at #{CONFIG_FILE}"
+              puts "Run: brainiac basecamp setup"
+            end
+          end
+
+          def cmd_status
+            puts "Basecamp Plugin Status"
+            puts "======================"
+            puts ""
+
+            # Check CLI
+            if system("which basecamp > /dev/null 2>&1")
+              puts "  CLI:    ✓ installed"
+            else
+              puts "  CLI:    ✗ not found"
+              return
+            end
+
+            # Check auth
+            auth_output = `basecamp auth status --json 2>/dev/null`
+            if $?.success?
+              puts "  Auth:   ✓ authenticated"
+            else
+              puts "  Auth:   ✗ not authenticated"
+            end
+
+            # Check config
+            if File.exist?(CONFIG_FILE)
+              config = JSON.parse(File.read(CONFIG_FILE))
+              puts "  Config: ✓ #{CONFIG_FILE}"
+              puts "  Bots:   #{config['bot_accounts']&.size || 0} configured"
+              puts "  Maps:   #{config['project_mappings']&.size || 0} project mappings"
+            else
+              puts "  Config: ✗ not configured"
+            end
+
+            # Check active epics
+            epics_file = File.join(BRAINIAC_DIR, "basecamp_epics.json")
+            if File.exist?(epics_file)
+              epics = JSON.parse(File.read(epics_file))
+              active = (epics["epics"] || []).count { |e| e["status"] == "active" }
+              total = (epics["epics"] || []).size
+              puts "  Epics:  #{active} active, #{total} total"
+            else
+              puts "  Epics:  none"
+            end
+          end
+
+          def cmd_epics(args)
+            epics_file = File.join(BRAINIAC_DIR, "basecamp_epics.json")
+            unless File.exist?(epics_file)
+              puts "No epics found."
+              return
+            end
+
+            data = JSON.parse(File.read(epics_file))
+            epics = data["epics"] || []
+
+            if args.first == "--all"
+              display_epics = epics
+            else
+              display_epics = epics.select { |e| e["status"] == "active" }
+            end
+
+            if display_epics.empty?
+              puts "No #{args.first == '--all' ? '' : 'active '}epics."
+              return
+            end
+
+            display_epics.each do |epic|
+              tasks = epic["tasks"] || []
+              complete = tasks.count { |t| t["status"] == "complete" }
+              in_flight = tasks.count { |t| t["status"] == "in_flight" }
+              total = tasks.size
+
+              status_icon = epic["status"] == "active" ? "🚀" : "✅"
+              puts "#{status_icon} #{epic['title']}"
+              puts "   Agent: #{epic['agent']} | Tasks: #{complete}/#{total} complete, #{in_flight} in-flight"
+              puts "   Started: #{epic['started_at']}"
+              puts ""
+            end
+          end
+
+          def cmd_link(args)
+            fizzy_card = args.shift
+            basecamp_url = args.shift
+
+            unless fizzy_card && basecamp_url
+              puts "Usage: brainiac basecamp link <fizzy-card-number> <basecamp-todo-url>"
+              return
+            end
+
+            puts "TODO: Link Fizzy card ##{fizzy_card} to #{basecamp_url}"
+            puts "(This will be used for manual linking outside of epic orchestration)"
+          end
+
+          def cmd_bot(args)
+            action = args.shift
+
+            case action
+            when "add"
+              name = args.shift
+              person_id = args.shift
+              agent = args.shift
+
+              unless name && person_id && agent
+                puts "Usage: brainiac basecamp bot add <name> <basecamp-person-id> <default-agent>"
+                puts ""
+                puts "Example:"
+                puts "  brainiac basecamp bot add andy-server 12345 Galen"
+                return
+              end
+
+              config = load_config
+              config["bot_accounts"] ||= {}
+              config["bot_accounts"][name] = {
+                "person_id" => person_id,
+                "default_agent" => agent
+              }
+              save_config(config)
+              puts "✓ Added bot account '#{name}' (person_id: #{person_id}, agent: #{agent})"
+
+            when "list"
+              config = load_config
+              bots = config["bot_accounts"] || {}
+              if bots.empty?
+                puts "No bot accounts configured."
+              else
+                bots.each do |name, account|
+                  puts "  #{name}: person_id=#{account['person_id']}, agent=#{account['default_agent']}"
+                end
+              end
+
+            when "remove"
+              name = args.shift
+              unless name
+                puts "Usage: brainiac basecamp bot remove <name>"
+                return
+              end
+              config = load_config
+              if config["bot_accounts"]&.delete(name)
+                save_config(config)
+                puts "✓ Removed bot account '#{name}'"
+              else
+                puts "Bot account '#{name}' not found"
+              end
+
+            else
+              puts "Usage: brainiac basecamp bot <add|list|remove>"
+            end
+          end
+
+          def cmd_projects(args)
+            action = args.shift
+
+            case action
+            when "map"
+              brainiac_key = args.shift
+              basecamp_id = args.shift
+
+              unless brainiac_key && basecamp_id
+                puts "Usage: brainiac basecamp projects map <brainiac-project-key> <basecamp-project-id>"
+                puts ""
+                puts "Example:"
+                puts "  brainiac basecamp projects map marketplace 12345"
+                return
+              end
+
+              config = load_config
+              config["project_mappings"] ||= {}
+              config["project_mappings"][brainiac_key] = {
+                "basecamp_project_id" => basecamp_id
+              }
+              save_config(config)
+              puts "✓ Mapped '#{brainiac_key}' → Basecamp project #{basecamp_id}"
+
+            when "list"
+              config = load_config
+              mappings = config["project_mappings"] || {}
+              if mappings.empty?
+                puts "No project mappings configured."
+              else
+                mappings.each do |key, mapping|
+                  puts "  #{key} → Basecamp project #{mapping['basecamp_project_id']}"
+                end
+              end
+
+            when "unmap"
+              key = args.shift
+              unless key
+                puts "Usage: brainiac basecamp projects unmap <brainiac-project-key>"
+                return
+              end
+              config = load_config
+              if config["project_mappings"]&.delete(key)
+                save_config(config)
+                puts "✓ Removed mapping for '#{key}'"
+              else
+                puts "Mapping for '#{key}' not found"
+              end
+
+            else
+              puts "Usage: brainiac basecamp projects <map|list|unmap>"
+            end
+          end
+
+          def print_help
+            puts <<~HELP
+              Usage: brainiac basecamp <command>
+
+              Commands:
+                setup                                   Interactive setup guide
+                config                                  Show current config
+                status                                  Check plugin status
+                epics [--all]                           List active epics (--all for completed too)
+                link <card> <url>                       Link a Fizzy card to a Basecamp todo
+                bot add <name> <person-id> <agent>      Add a bot account mapping
+                bot list                                List bot accounts
+                bot remove <name>                       Remove a bot account
+                projects map <key> <basecamp-id>        Map a Brainiac project to Basecamp
+                projects list                           List project mappings
+                projects unmap <key>                    Remove a project mapping
+                set fizzy-account-id <id>                Set Fizzy account ID (for card URLs)
+                set review-gate <mode>                  Set review gate (on_complete or on_pr_merge)
+                set epic-prefix <prefix>                Set epic todolist prefix (default: "Epic:")
+
+              Config file: ~/.brainiac/basecamp.json
+              Epics state: ~/.brainiac/basecamp_epics.json
+
+              Review gate modes:
+                on_complete   — Advance to next task as soon as agent finishes (default)
+                on_pr_merge   — Wait for PR to be merged before advancing (review gate)
+            HELP
+          end
+
+          def cmd_set(args)
+            key = args.shift
+            value = args.shift
+
+            unless key && value
+              puts "Usage: brainiac basecamp set <key> <value>"
+              puts ""
+              puts "Keys:"
+              puts "  fizzy-account-id <id>      Fizzy account ID (for card URLs)"
+              puts "  review-gate <mode>         on_complete or on_pr_merge"
+              puts "  epic-prefix <prefix>       Todolist prefix for epic detection"
+              return
+            end
+
+            config = load_config
+
+            case key
+            when "fizzy-account-id"
+              config["fizzy_account_id"] = value
+              save_config(config)
+              puts "✓ Set fizzy_account_id = #{value}"
+              puts "  Card URLs will be: https://app.fizzy.do/#{value}/cards/NNNN"
+            when "review-gate"
+              unless %w[on_complete on_pr_merge epic_branch].include?(value)
+                puts "Error: review-gate must be 'on_complete', 'on_pr_merge', or 'epic_branch'"
+                return
+              end
+              config["review_gate"] = value
+              save_config(config)
+              puts "✓ Set review_gate = #{value}"
+              case value
+              when "on_pr_merge"
+                puts "  Epic tasks will wait for PR merge before advancing to next task"
+              when "epic_branch"
+                puts "  Epic tasks auto-merge into an epic branch. Final PR to main when epic completes."
+                puts "  Best for overnight/autonomous execution."
+              else
+                puts "  Epic tasks advance immediately when agent completes"
+              end
+            when "epic-prefix"
+              config["epic_prefix"] = value
+              save_config(config)
+              puts "✓ Set epic_prefix = #{value}"
+            when "profile"
+              config["basecamp_profile"] = value
+              save_config(config)
+              puts "✓ Set basecamp_profile = #{value}"
+              puts "  All basecamp CLI commands will use --profile #{value}"
+              puts "  Set up the profile: basecamp profile create #{value} && basecamp auth login --profile #{value}"
+            else
+              puts "Unknown key: #{key}"
+              puts "Valid keys: fizzy-account-id, review-gate, epic-prefix, profile"
+            end
+          end
+
+          def load_config
+            if File.exist?(CONFIG_FILE)
+              JSON.parse(File.read(CONFIG_FILE))
+            else
+              {}
+            end
+          end
+
+          def save_config(config)
+            File.write(CONFIG_FILE, JSON.pretty_generate(config))
+          end
+        end
+      end
+
+      def self.cli(args)
+        Cli.run(args)
+      end
+
+      def self.completions
+        %w[setup config status epics link bot projects set]
+      end
+    end
+  end
+end

data/lib/brainiac/plugins/basecamp/client.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Brainiac
+  module Plugins
+    module Basecamp
+      # Wrapper around the `basecamp` CLI binary.
+      # Shells out with --json for structured responses.
+      module Client
+        class << self
+          # Set the current agent profile for basecamp CLI commands.
+          # The profile name matches the agent name (e.g., "galen" → basecamp --profile galen).
+          #
+          # @param agent_name [String, nil] Agent name to use as profile
+          def with_agent_profile(agent_name)
+            @current_agent_profile = agent_name&.downcase
+          end
+
+          # Clear the current agent profile.
+          def clear_agent_profile
+            @current_agent_profile = nil
+          end
+
+          # Run a basecamp CLI command as a specific agent.
+          #
+          # @param agent_name [String] Agent name (used as profile)
+          # @param args [Array<String>] CLI arguments
+          # @return [Hash] Parsed JSON response
+          def run_as(agent_name, *args)
+            run(*args, profile: agent_name.downcase)
+          end
+          # Run a basecamp CLI command and return parsed JSON.
+          #
+          # @param args [Array<String>] CLI arguments
+          # @param profile [String, nil] Named profile to use (defaults to agent name)
+          # @return [Hash] Parsed JSON response
+          # @raise [ClientError] If the command fails
+          def run(*args, profile: nil)
+            cmd = ["basecamp"]
+            # Use the specified profile, or fall back to the current agent's name as profile
+            profile ||= @current_agent_profile
+            cmd += ["--profile", profile] if profile
+            cmd += args.flatten
+
+            LOG.debug "[Basecamp:Client] Running: #{cmd.join(' ')}" if defined?(LOG) && LOG.debug?
+
+            stdout, stderr, status = Open3.capture3(*cmd)
+
+            unless status.success?
+              error_body = parse_json_safe(stdout) || parse_json_safe(stderr)
+              error_msg = error_body&.dig("error") || stderr.strip.split("\n").first || "Unknown error"
+              raise ClientError.new(error_msg, exit_code: status.exitstatus, response: error_body)
+            end
+
+            result = parse_json_safe(stdout)
+            unless result
+              raise ClientError.new("Failed to parse JSON response", exit_code: 0, response: nil)
+            end
+
+            result
+          end
+
+          # Run a basecamp CLI command, returning nil on failure instead of raising.
+          #
+          # @param args [Array<String>] CLI arguments
+          # @param profile [String, nil] Named profile to use
+          # @return [Hash, nil] Parsed JSON response or nil
+          def run_safe(*args, profile: nil)
+            run(*args, profile: profile)
+          rescue ClientError => e
+            LOG.warn "[Basecamp:Client] Command failed: #{e.message}" if defined?(LOG)
+            nil
+          end
+
+          # Get a todo by ID with subtasks info.
+          #
+          # @param todo_id [String, Integer] Todo ID
+          # @param project [String, Integer] Basecamp project/bucket ID
+          # @return [Hash, nil]
+          def get_todo(todo_id, project:)
+            run("todos", "show", todo_id.to_s, "--in", project.to_s, "--json")
+          end
+
+          # List subtasks (steps) for a todo.
+          #
+          # @param todo_id [String, Integer] Parent todo ID
+          # @param project [String, Integer] Basecamp project/bucket ID
+          # @return [Hash, nil]
+          def get_subtasks(todo_id, project:)
+            # Basecamp models todo subtasks as Kanban::Step records
+            # Use the recordings list filtered by type and parent
+            run("recordings", "list", "--in", project.to_s, "--type", "Kanban::Step",
+                "--all", "--json")
+          end
+
+          # Complete a subtask.
+          #
+          # @param step_id [String, Integer] Step/subtask ID
+          # @param project [String, Integer] Basecamp project/bucket ID
+          # @return [Hash, nil]
+          def complete_subtask(step_id, project:)
+            # Use raw API to complete a step
+            run("api", "put",
+                "/buckets/#{project}/card_tables/steps/#{step_id}/completions.json",
+                "--data", '{"completion":"on"}', "--json")
+          end
+
+          # Add a comment to a recording (todo, card, message, etc.)
+          #
+          # @param recording_id [String, Integer] The recording to comment on
+          # @param content [String] Comment content (Markdown)
+          # @param project [String, Integer] Basecamp project/bucket ID
+          # @return [Hash, nil]
+          def add_comment(recording_id, content, project:)
+            run("comments", "create", recording_id.to_s, content, "--in", project.to_s, "--json")
+          end
+
+          # Complete a todo.
+          #
+          # @param todo_id [String, Integer] Todo ID
+          # @return [Hash, nil]
+          def complete_todo(todo_id)
+            run("todos", "complete", todo_id.to_s, "--json")
+          end
+
+          # List projects.
+          #
+          # @return [Hash]
+          def list_projects
+            run("projects", "list", "--json")
+          end
+
+          # Parse a Basecamp URL to extract IDs.
+          #
+          # @param url [String] Basecamp URL
+          # @return [Hash, nil]
+          def parse_url(url)
+            run("url", "parse", url, "--json")
+          end
+
+          # Check auth status.
+          #
+          # @return [Hash, nil]
+          def auth_status
+            run_safe("auth", "status", "--json")
+          end
+
+          private
+
+          def parse_json_safe(str)
+            return nil if str.nil? || str.strip.empty?
+
+            JSON.parse(str)
+          rescue JSON::ParserError
+            nil
+          end
+        end
+      end
+
+      # Error class for CLI failures.
+      class ClientError < StandardError
+        attr_reader :exit_code, :response
+
+        def initialize(message, exit_code: nil, response: nil)
+          @exit_code = exit_code
+          @response = response
+          super(message)
+        end
+      end
+    end
+  end
+end

data/lib/brainiac/plugins/basecamp/config.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Brainiac
+  module Plugins
+    module Basecamp
+      # Configuration loader for brainiac-basecamp.
+      #
+      # Config file: ~/.brainiac/basecamp.json
+      module Config
+        BRAINIAC_DIR = ENV.fetch("BRAINIAC_DIR", File.join(Dir.home, ".brainiac"))
+        CONFIG_FILE = File.join(BRAINIAC_DIR, "basecamp.json")
+
+        # Default config structure.
+        DEFAULT_CONFIG = {
+          "bot_accounts" => {},
+          "project_mappings" => {},
+          "epic_prefix" => "Epic:",
+          "fizzy_account_id" => nil,
+          "review_gate" => "on_complete",
+          "review_gates" => [],
+          "notifications" => {
+            "epic_started" => true,
+            "task_dispatched" => true,
+            "task_completed" => true,
+            "epic_completed" => true
+          }
+        }.freeze
+
+        class << self
+          # Load and cache config. Reloads if file has changed since last read.
+          #
+          # @return [Hash]
+          def current
+            return @config if @config && @config_mtime == config_mtime
+
+            load!
+            @config
+          end
+
+          # Force reload config from disk.
+          def load!
+            if File.exist?(CONFIG_FILE)
+              raw = JSON.parse(File.read(CONFIG_FILE))
+              @config = DEFAULT_CONFIG.merge(raw)
+            else
+              @config = DEFAULT_CONFIG.dup
+            end
+            @config_mtime = config_mtime
+          rescue JSON::ParserError => e
+            LOG.error "[Basecamp] Config parse error: #{e.message}" if defined?(LOG)
+            @config = DEFAULT_CONFIG.dup
+          end
+
+          # Get bot account config for a given Basecamp person ID.
+          #
+          # @param person_id [String, Integer] Basecamp person ID
+          # @return [Hash, nil] Bot account config or nil
+          def bot_account_for_person(person_id)
+            current["bot_accounts"].find do |_key, account|
+              account["person_id"].to_s == person_id.to_s
+            end&.then { |key, account| account.merge("key" => key) }
+          end
+
+          # Get the Basecamp project ID for a Brainiac project key.
+          #
+          # @param brainiac_project [String] Brainiac project key
+          # @return [String, nil] Basecamp project ID
+          def basecamp_project_for(brainiac_project)
+            mapping = current["project_mappings"][brainiac_project]
+            mapping&.dig("basecamp_project_id")
+          end
+
+          # Get the Brainiac project key for a Basecamp project/bucket ID.
+          #
+          # @param basecamp_project_id [String, Integer] Basecamp bucket ID
+          # @return [String, nil] Brainiac project key
+          def brainiac_project_for(basecamp_project_id)
+            current["project_mappings"].find do |_key, mapping|
+              mapping["basecamp_project_id"].to_s == basecamp_project_id.to_s
+            end&.first
+          end
+
+          # The prefix used to identify epic todolists (e.g. "Epic: My Feature")
+          #
+          # @return [String]
+          def epic_prefix
+            current["epic_prefix"] || "Epic:"
+          end
+
+          # The Fizzy account ID (for building card URLs like app.fizzy.do/<id>/cards/N).
+          #
+          # @return [String, nil]
+          def fizzy_account_id
+            current["fizzy_account_id"]
+          end
+
+          # Review gate mode: "on_complete" (advance immediately) or "on_pr_merge" (wait for merge).
+          #
+          # @return [String]
+          def review_gate
+            current["review_gate"] || "on_complete"
+          end
+
+          private
+
+          def config_mtime
+            File.exist?(CONFIG_FILE) ? File.mtime(CONFIG_FILE) : nil
+          end
+        end
+      end
+    end
+  end
+end