brainiac-fizzy 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 900a770925d9d311e242d2262ba1d55488f1f1d99b706940412c90354fbecbe7
+  data.tar.gz: 10745520e457d223051f8b02451b6648b2fbd63b541a595da7430ef5a22a2580
+SHA512:
+  metadata.gz: b5da5cb4db94444d25292a4521b73229c2e0115eaa14a4f29e1ddc0de47d87cb7bf54294d16ae59615ba0691be76ebf25040895c78a460fa7492b1f12729ff23
+  data.tar.gz: 9d16fc1d6792ddfbd2a0ba983a9bf66b4dc46cf3d2ead4bc3c77a4b6222679d5835cb30161722224cae7578a2ddd2531075090bc1829072f7c343b7bdb30abab

data/README.md

@@ -0,0 +1,111 @@
+# brainiac-fizzy
+
+Fizzy card management plugin for [Brainiac](https://github.com/stowzilla/brainiac).
+
+Handles the full Fizzy integration: card assignment, comment routing, @mentions, cross-agent reviews, duplicate detection, deploy shortcuts, and deployment environment tracking.
+
+## Installation
+
+```bash
+brainiac install fizzy
+brainiac restart
+```
+
+Or manually:
+
+```bash
+gem install brainiac-fizzy
+```
+
+Then add to `~/.brainiac/plugins.json`:
+
+```json
+{
+  "plugins": [
+    { "name": "fizzy", "gem": "brainiac-fizzy" }
+  ]
+}
+```
+
+## Configuration
+
+Fizzy configuration lives in `~/.brainiac/fizzy.json` (same as before):
+
+```json
+{
+  "authorized_users": [
+    { "id": "user-id-1", "name": "Andy", "human": true },
+    { "id": "agent-id-1", "name": "Galen", "human": false }
+  ],
+  "boards": {
+    "development": {
+      "board_id": "your-board-id",
+      "webhook_secret": "secret-for-this-board",
+      "columns": {
+        "right_now": "column-id",
+        "needs_review": "column-id",
+        "uat": "column-id"
+      }
+    }
+  }
+}
+```
+
+## What This Plugin Handles
+
+| Event | Action |
+|-------|--------|
+| Card assigned | Creates worktree, maps card to branch, dispatches assigned agent |
+| Card published | Duplicate detection (trigram + semantic) |
+| @mention in comment | Routes to mentioned agent (cross-agent reviews) |
+| Follow-up comment | Runs card's assigned agent in existing worktree |
+| Deploy shortcut | Clones branch to deployment environment (dev01, dev02) |
+
+## Webhook Setup
+
+Set your Fizzy webhook URL to:
+```
+https://your-ngrok.ngrok-free.app/fizzy/development
+```
+
+Where `development` is the board key from `fizzy.json`. Set the secret to the board's `webhook_secret`.
+
+## Dependencies on Brainiac Core
+
+This plugin runs inside the brainiac server process and uses core functions:
+
+- `verify_signature!` — webhook HMAC verification
+- `run_agent` — agent CLI dispatch
+- `session_active?`, `already_processed?` — deduplication
+- `identify_project_by_tags` — card-to-project mapping
+- `create_or_reuse_worktree` — git worktree management
+- `prefetch_card_context` — card body/comments pre-fetch
+- `render_prompt` — prompt template composition
+- `reload_projects!`, `reload_agent_registry!` — config hot-reload
+
+These are all provided by the `brainiac` gem (runtime dependency).
+
+## Migrating from Built-in Handler
+
+If upgrading from brainiac's built-in Fizzy handler:
+
+1. Install the plugin: `brainiac install fizzy`
+2. Disable the built-in handler in `~/.brainiac/brainiac.json`:
+   ```json
+   { "handlers": { "fizzy": false } }
+   ```
+3. Restart: `brainiac restart`
+
+The plugin uses the exact same config files and functions — it's a drop-in replacement.
+
+## Development
+
+```bash
+cd ~/Code/brainiac-fizzy
+bundle install
+rake test
+```
+
+## License
+
+MIT

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Brainiac
+  module Plugins
+    module Fizzy
+      # Fizzy configuration — loads ~/.brainiac/fizzy.json.
+      # Provides board config, webhook secrets, authorized users, and column IDs.
+      module Config
+        FIZZY_CONFIG_FILE = File.join(
+          ENV.fetch("BRAINIAC_DIR", File.join(Dir.home, ".brainiac")),
+          "fizzy.json"
+        )
+
+        @config = {}
+        @boards = {}
+        @authorized_user_ids = []
+
+        class << self
+          attr_reader :config, :boards, :authorized_user_ids
+
+          def load!
+            @config = if File.exist?(FIZZY_CONFIG_FILE)
+                        JSON.parse(File.read(FIZZY_CONFIG_FILE))
+                      else
+                        {}
+                      end
+            @boards = @config["boards"] || {}
+            @authorized_user_ids = (@config["authorized_users"] || []).map { |u| u["id"] }
+          rescue JSON::ParserError => e
+            LOG.error "[Fizzy] Failed to parse fizzy.json: #{e.message}" if defined?(LOG)
+            @config = {}
+            @boards = {}
+            @authorized_user_ids = []
+          end
+
+          def reload!
+            load!
+          end
+
+          def current
+            @config
+          end
+
+          def board_config(board_key)
+            @boards[board_key.to_s]
+          end
+
+          def board_webhook_secret(board_key)
+            config = board_config(board_key)
+            config&.dig("webhook_secret") || ENV.fetch("FIZZY_WEBHOOK_SECRET", nil)
+          end
+
+          def board_column_id(board_key, column_name)
+            config = board_config(board_key)
+            config&.dig("columns", column_name.to_s)
+          end
+
+          def board_key_for_id(board_id)
+            @boards.each do |key, config|
+              return key if config["board_id"] == board_id
+            end
+            nil
+          end
+
+          def board_key_for_project(project_config)
+            fizzy_yaml = File.join(project_config["repo_path"], ".fizzy.yaml")
+            return nil unless File.exist?(fizzy_yaml)
+
+            require "yaml"
+            data = YAML.safe_load_file(fizzy_yaml)
+            board_id = data["board"]
+            board_key_for_id(board_id)
+          rescue StandardError => e
+            LOG.warn "[Fizzy] Could not read .fizzy.yaml: #{e.message}" if defined?(LOG)
+            nil
+          end
+
+          def authorized?(payload)
+            creator_id = payload.dig("creator", "id")
+            @authorized_user_ids.include?(creator_id)
+          end
+
+          def human_mentioned?(user_id)
+            user = (@config["authorized_users"] || []).find { |u| u["id"] == user_id }
+            user && user["human"]
+          end
+
+          def identify_project_by_tags(tags)
+            tag_names = tags.map { |t| t.is_a?(Hash) ? t["name"] : t.to_s }.map(&:downcase)
+
+            PROJECTS.each do |key, config|
+              project_tags = (config["fizzy_tags"] || []).map(&:downcase)
+              return [key, config] if tag_names.intersect?(project_tags)
+            end
+
+            # Fall back to default project
+            default_key = default_project_key
+            default_key ? [default_key, PROJECTS[default_key]] : nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/brainiac/plugins/fizzy/delegators.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# Top-level convenience methods that delegate to Fizzy plugin modules.
+#
+# The handler files (assignment.rb, comments.rb, etc.) were originally
+# top-level functions in brainiac core. They call helpers like
+# `fizzy_env_for`, `identify_project_by_tags`, etc. as top-level methods.
+#
+# These delegators make them available at top level so the handler files
+# work without modification.
+
+def fizzy_token_for(agent_name)
+  Brainiac::Plugins::Fizzy::Helpers.fizzy_token_for(agent_name)
+end
+
+def fizzy_env_for(agent_name)
+  Brainiac::Plugins::Fizzy::Helpers.fizzy_env_for(agent_name)
+end
+
+def default_fizzy_env
+  Brainiac::Plugins::Fizzy::Helpers.default_fizzy_env
+end
+
+def prefetch_card_context(card_number, repo_path:, agent_name: nil)
+  Brainiac::Plugins::Fizzy::Helpers.prefetch_card_context(card_number, repo_path: repo_path, agent_name: agent_name)
+end
+
+def move_card_to_column(card_number, column_name, project_config:, agent_name: nil)
+  Brainiac::Plugins::Fizzy::Helpers.move_card_to_column(card_number, column_name, project_config: project_config, agent_name: agent_name)
+end
+
+def append_fizzy_comment_footer(card_number, project_config:, agent_name: nil)
+  Brainiac::Plugins::Fizzy::Helpers.append_fizzy_comment_footer(card_number, project_config: project_config, agent_name: agent_name)
+end
+
+def ensure_fizzy_yaml!(chdir, project_config)
+  Brainiac::Plugins::Fizzy::Helpers.ensure_fizzy_yaml!(chdir, project_config)
+end
+
+def scrub_invalid_attachments!(dir)
+  Brainiac::Plugins::Fizzy::Helpers.scrub_invalid_attachments!(dir)
+end
+
+def verify_fizzy_signature!(request, payload_body, board_key: nil)
+  Brainiac::Plugins::Fizzy::Helpers.verify_signature!(request, payload_body, board_key: board_key)
+end
+
+# Legacy alias used by handler files
+def verify_signature!(request, payload_body, board_key: nil)
+  Brainiac::Plugins::Fizzy::Helpers.verify_signature!(request, payload_body, board_key: board_key)
+end
+
+# Config delegators
+def identify_project_by_tags(tags)
+  Brainiac::Plugins::Fizzy::Config.identify_project_by_tags(tags)
+end
+
+def board_config(board_key)
+  Brainiac::Plugins::Fizzy::Config.board_config(board_key)
+end
+
+def board_webhook_secret(board_key)
+  Brainiac::Plugins::Fizzy::Config.board_webhook_secret(board_key)
+end
+
+def board_column_id(board_key, column_name)
+  Brainiac::Plugins::Fizzy::Config.board_column_id(board_key, column_name)
+end
+
+def board_key_for_project(project_config)
+  Brainiac::Plugins::Fizzy::Config.board_key_for_project(project_config)
+end
+
+def board_key_for_id(board_id)
+  Brainiac::Plugins::Fizzy::Config.board_key_for_id(board_id)
+end
+
+def authorized?(payload)
+  Brainiac::Plugins::Fizzy::Config.authorized?(payload)
+end
+
+def human_mentioned?(user_id)
+  Brainiac::Plugins::Fizzy::Config.human_mentioned?(user_id)
+end
+
+# Top-level prompt constants — handler files reference these directly
+PROMPT_CARD_ASSIGNED = Brainiac::Plugins::Fizzy::Prompts::CARD_ASSIGNED
+PROMPT_FOLLOWUP_WORKTREE = Brainiac::Plugins::Fizzy::Prompts::FOLLOWUP_WORKTREE
+PROMPT_FOLLOWUP_NO_WORKTREE = Brainiac::Plugins::Fizzy::Prompts::FOLLOWUP_NO_WORKTREE
+PROMPT_MENTION = Brainiac::Plugins::Fizzy::Prompts::MENTION
+PROMPT_CROSS_AGENT_REVIEW = Brainiac::Plugins::Fizzy::Prompts::CROSS_AGENT_REVIEW
+
+# Config constants — handler files reference these as top-level constants.
+# These are evaluated after Config.load! has been called (during plugin register).
+# Use a delegating object so it always reflects current config state.
+FIZZY_CONFIG = Class.new do
+  def fetch(key, default = nil) = Brainiac::Plugins::Fizzy::Config.current.fetch(key, default)
+  def [](key) = Brainiac::Plugins::Fizzy::Config.current[key]
+  def dig(*keys) = Brainiac::Plugins::Fizzy::Config.current.dig(*keys)
+end.new
+
+AUTHORIZED_USER_IDS = Class.new do
+  def include?(id) = Brainiac::Plugins::Fizzy::Config.authorized_user_ids.include?(id)
+  def map(&) = Brainiac::Plugins::Fizzy::Config.authorized_user_ids.map(&)
+  def any?(&) = Brainiac::Plugins::Fizzy::Config.authorized_user_ids.any?(&)
+end.new

data/lib/brainiac/plugins/fizzy/handlers/assignment.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+# Fizzy card assignment handler.
+#
+# When a card is assigned to a local agent, creates a worktree, builds the prompt,
+# and dispatches the agent to begin work.
+
+def handle_card_assigned(payload)
+  eventable = payload["eventable"] || {}
+  assignees = eventable["assignees"] || []
+
+  local_names = local_agent_names
+  assigned_agent = assignees.map { |a| a["name"] }.find { |name| local_names.include?(name) }
+
+  assignee_names = assignees.map { |a| a["name"] }.join(", ")
+  LOG.info "[Fizzy] Card assigned to: [#{assignee_names}], local agents: [#{local_names.join(", ")}]"
+
+  return ignore_assignment("wrong assignee", assignee_names, local_names) unless assigned_agent
+  return ignore_unauthorized(payload, eventable) unless authorized?(payload)
+
+  card_number = eventable["number"]
+  card_internal_id = eventable["id"]
+  title = eventable["title"] || "untitled"
+  tags = eventable["tags"] || []
+
+  project_result = identify_project_by_tags(tags)
+  unless project_result
+    tag_names = tags.map { |t| t.is_a?(Hash) ? t["name"] : t }.join(", ")
+    LOG.warn "No project found for card ##{card_number} with tags: #{tag_names}"
+    return [200, { status: "ignored", reason: "no matching project" }.to_json]
+  end
+
+  project_key, project_config = project_result
+  repo_path = project_config["repo_path"]
+  branch = "fizzy-#{card_number}-#{slugify(title)}"
+
+  card_key = "card-#{card_number}"
+  if session_active?(card_key)
+    LOG.info "Skipping card ##{card_number} — agent session already active"
+    return [200, { status: "ignored", reason: "session already active" }.to_json]
+  end
+
+  LOG.info "Card ##{card_number} assigned to #{assigned_agent} for project '#{project_key}', " \
+           "creating worktree: #{branch} (model: #{detect_model(project_config, tags: tags) || "default"})"
+
+  react_to_assignment(card_number, repo_path, assigned_agent)
+  worktree_path = setup_assigned_worktree(repo_path, branch, card_internal_id, card_number, project_key, assigned_agent)
+
+  dispatch_assigned_card(
+    card_number: card_number, card_internal_id: card_internal_id, title: title, tags: tags,
+    branch: branch, worktree_path: worktree_path, project_config: project_config, project_key: project_key,
+    agent_name: assigned_agent, model: detect_model(project_config, tags: tags),
+    effort: detect_effort(project_config, tags: tags), cli_provider_override: detect_cli_provider(tags: tags)
+  )
+end
+
+def ignore_assignment(reason, assignee_names, local_names)
+  LOG.info "[Fizzy] No local agent matched. Assignees: [#{assignee_names}], Local: [#{local_names.join(", ")}]"
+  [200, { status: "ignored", reason: reason }.to_json]
+end
+
+def ignore_unauthorized(payload, eventable)
+  creator_name = payload.dig("creator", "name") || "Unknown"
+  notify_unauthorized("card_assigned", creator_name, "card ##{eventable["number"]}")
+  [200, { status: "ignored", reason: "unauthorized" }.to_json]
+end
+
+def react_to_assignment(card_number, repo_path, agent_name)
+  Thread.new do
+    run_cmd("fizzy", "reaction", "create", "--card", card_number.to_s,
+            "--content", "👍", chdir: repo_path, env: fizzy_env_for(agent_name))
+  rescue StandardError => e
+    LOG.warn "Could not add reaction to card: #{e.message}"
+  end
+end
+
+def setup_assigned_worktree(repo_path, branch, card_internal_id, card_number, project_key, agent_name)
+  debounced_repo_fetch(repo_path)
+  worktree_path = File.join(File.dirname(repo_path), "#{File.basename(repo_path)}--#{branch}")
+  worktree_path = create_or_reuse_worktree(repo_path: repo_path, branch: branch, worktree_path: worktree_path)
+
+  map = load_work_item_map
+  map[card_internal_id] = {
+    "number" => card_number, "branch" => branch, "worktree" => worktree_path,
+    "project" => project_key, "agent" => agent_name
+  }
+  save_work_item_map(map)
+  worktree_path
+end
+
+def dispatch_assigned_card(card_number:, card_internal_id:, title:, tags:, branch:, worktree_path:,
+                           project_config:, project_key:, agent_name:, model:, effort:, cli_provider_override:)
+  card_context = prefetch_card_context(card_number, repo_path: project_config["repo_path"], agent_name: agent_name)
+  planning_info = detect_planning_mode(text: title, tags: tags, card_internal_id: card_internal_id, card_number: card_number)
+
+  template_vars = {
+    "CARD_NUMBER" => card_number, "CARD_TITLE" => title,
+    "BRANCH" => branch, "COMMENT_CREATOR" => agent_name
+  }
+  brain_ctx = build_brain_context(
+    agent_name: agent_name, card_title: title,
+    card_number: card_number, project_key: project_key, source: :fizzy
+  )
+
+  prompt = if planning_info
+             LOG.info "[Planning] Planning mode active for card ##{card_number}"
+             template_vars["CARD_ID"] = planning_info[:card_id]
+             render_planning_prompt(PROMPT_CARD_ASSIGNED, template_vars,
+                                    brain_context: brain_ctx, card_context: card_context, agent_name: agent_name)
+           else
+             template_vars["CARD_ID"] = card_number
+             render_prompt(PROMPT_CARD_ASSIGNED, template_vars,
+                           brain_context: brain_ctx, card_context: card_context, agent_name: agent_name)
+           end
+
+  card_key = "card-#{card_number}"
+  pid, log_file = run_agent(prompt,
+                            project_config: project_config, chdir: worktree_path,
+                            log_name: "assigned-#{card_number}", model: model, effort: effort,
+                            agent_name: agent_name, card_number: card_number, source: :fizzy,
+                            source_context: { card_number: card_number },
+                            cli_provider: cli_provider_override)
+  register_session(card_key, pid, log_file: log_file, supersede_key: card_key, agent_name: agent_name)
+
+  Thread.new { move_card_to_column(card_number, "right_now", project_config: project_config, agent_name: agent_name) }
+
+  [200, { status: "processed", card: card_number, branch: branch, project: project_key, agent: agent_name }.to_json]
+end