brainiac-fizzy 0.0.28 → 0.0.30

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5d55859eafd2aeccf63a2083999340a1ce4a77c01b81a8297adf136b0e553b3
-  data.tar.gz: b1dbff19165dec2cf391f4c258ae2a207457cdc53088ee44062ffda050530a48
+  metadata.gz: 8e54fe3a10cd6e39be3f52862b1625e2532be592e5480c11f685423910a75b91
+  data.tar.gz: 77cc0b0ce8a518bde93484bf8513f538f9a26f4412479556d80f83de3ae5c545
 SHA512:
-  metadata.gz: 9438b9143636ab612da09a19be5b672ada809095317ea7ce72d9045acbebe6601d5485ba4bfd234b85edcdb54a6d676edd330a74b4241cc85c0605d590fe523d
-  data.tar.gz: 93fbe26b2a546b1b72e1025f7af334ac6539efe0c4144338bd6d2929b336e2ed21752cc8a1d4ef2949d380cc72635e945e0dad819afe043570c483ddc889d2d7
+  metadata.gz: 71c5abb12093956521a3ebdf78566d416d1c3ed33293d6c402a5236462b524042af9a259a3cda7fbf1930c80b93e7be68462952aed0f61393a1eb84b055a851a
+  data.tar.gz: 1ecc72a231ccef4c9fadbc279fe561628fda23151aad9b8b64afd65cd151d7ec612d95c25daa008958176b0e922b582602689f6c0754a0474643a4216131055c

data/README.md

@@ -37,6 +37,8 @@ Fizzy configuration lives in `~/.brainiac/fizzy.json` (same as before):
     { "id": "user-id-1", "name": "Andy", "human": true },
     { "id": "agent-id-1", "name": "Galen", "human": false }
   ],
+  "uat_agent": false,
+  "uat_agent_tag": "uat",
   "boards": {
     "development": {
       "board_id": "your-board-id",
@@ -51,6 +53,25 @@ Fizzy configuration lives in `~/.brainiac/fizzy.json` (same as before):
 }
 ```
 
+### UAT agent (`uat_agent`)
+
+When a PR is merged and its card moves to the UAT column, Brainiac can dispatch
+an LLM agent to write manual testing steps as a card comment. This spends tokens
+on every merge, so it's **disabled by default**. Set `"uat_agent": true` at the
+top level of `fizzy.json` to opt back in globally. The card still moves to UAT
+and gets the PR-merged comment either way — only the agent dispatch is gated.
+
+**Per-card opt-in:** Even with `uat_agent` off globally, you can trigger the UAT
+agent for a single card by adding the `uat` tag to it. When the card's PR merges,
+Brainiac fetches the card's live tags and dispatches the UAT agent if the tag is
+present. Customize the tag name with `"uat_agent_tag": "your-tag"`, or set it to
+`false`/`null` to disable per-card overrides entirely. This gives you three
+states:
+
+- `uat_agent: true` — dispatch on every merge
+- `uat_agent: false` (default) + `uat` tag on a card — dispatch for that card only
+- `uat_agent: false` + no tag — never dispatch (pure bookkeeping, zero tokens)
+
 ## What This Plugin Handles
 
 | Event | Action |

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

@@ -27,6 +27,8 @@ module Brainiac
               cmd_setup
             when "board"
               cmd_board(args)
+            when "env"
+              cmd_env(args)
             else
               print_help
             end
@@ -126,6 +128,66 @@ module Brainiac
             end
           end
 
+          # --- ephemeral env management ---
+
+          # `brainiac fizzy env setup <card_number>`
+          #
+          # Manually set up (or refresh tracking for) an ephemeral Belt env for a
+          # card that was already worked — no agent, no tokens. Once tracked, PR
+          # updates auto-redeploy it via brainiac-github.
+          def cmd_env(args)
+            sub = args.shift
+            case sub
+            when "setup", "add"
+              env_setup(args)
+            else
+              puts "Usage: brainiac fizzy env setup <card_number>"
+              puts ""
+              puts "Commands:"
+              puts "  setup <card_number>   Configure + deploy an ephemeral Belt env for a"
+              puts "                        card that was already worked (no agent dispatch)."
+            end
+          end
+
+          def env_setup(args)
+            card_number = args.shift
+            if card_number.nil? || card_number.strip.empty?
+              puts "Usage: brainiac fizzy env setup <card_number>"
+              return
+            end
+
+            require "net/http"
+            require "uri"
+
+            server_url = detect_server_url
+            uri = URI("#{server_url}/api/fizzy/ephemeral-env/#{card_number}")
+
+            puts "Setting up ephemeral env for card ##{card_number} (no agent)..."
+            begin
+              http = Net::HTTP.new(uri.host, uri.port)
+              http.read_timeout = 600 # belt deploy can be slow
+              response = http.post(uri.path, "")
+              data = begin
+                JSON.parse(response.body)
+              rescue StandardError
+                {}
+              end
+
+              if response.is_a?(Net::HTTPSuccess) && data["status"] == "ok"
+                puts "✓ Ephemeral env '#{data["env"]}' ready#{" (was already configured)" if data["already_configured"]}"
+                puts "  Worktree: #{data["worktree"]}" if data["worktree"]
+                puts "  URL:      #{data["url"]}" if data["url"]
+                puts ""
+                puts "Tracked in ephemeral_envs.json — PR updates will auto-redeploy it."
+              else
+                puts "✗ Failed: #{data["reason"] || response.message}"
+              end
+            rescue StandardError => e
+              puts "Could not reach server at #{server_url}: #{e.message}"
+              puts "Is the server running? Check with: brainiac status"
+            end
+          end
+
           # --- board setup (split into phases) ---
 
           def board_setup
@@ -629,6 +691,7 @@ module Brainiac
                 board list                          List configured boards and their columns
                 board assign <project> <board_key>  Assign a project to a board
                 board columns <board_key>           Refresh columns for a board from Fizzy
+                env setup <card_number>             Set up an ephemeral Belt env for an already-worked card (no agent)
 
               Fizzy handles card assignment, comments, @mentions, cross-agent reviews,
               duplicate detection, and planning mode via webhooks.
@@ -662,11 +725,13 @@ module Brainiac
       # When called with args (the words typed so far after the plugin name),
       # returns context-sensitive completions for nested subcommands.
       def self.completions(args = [])
-        return %w[board config setup status] if args.empty?
+        return %w[board config env setup status] if args.empty?
 
         case args[0]
         when "board"
           board_completions(args[1..])
+        when "env"
+          args.length <= 1 ? %w[setup add] : []
         else
           []
         end

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

@@ -82,6 +82,26 @@ module Brainiac
             nil
           end
 
+          # Whether to dispatch an LLM agent to write UAT testing steps when a
+          # PR is merged and the card moves to UAT. Disabled by default to save
+          # tokens — set "uat_agent": true in ~/.brainiac/fizzy.json to enable
+          # globally. Individual cards can still opt in via the UAT tag even when
+          # this is false (see #uat_agent_tag).
+          def uat_agent_enabled?
+            @config.fetch("uat_agent", false) == true
+          end
+
+          # The card tag that opts a single card into UAT agent dispatch even
+          # when uat_agent is globally disabled. Defaults to "uat". Set
+          # "uat_agent_tag": "some-tag" in fizzy.json to customize, or false/null
+          # to disable per-card overrides entirely.
+          def uat_agent_tag
+            value = @config.fetch("uat_agent_tag", "uat")
+            return nil if value == false || value.nil? || value.to_s.strip.empty?
+
+            value.to_s
+          end
+
           def authorized?(payload)
             creator_id = payload.dig("creator", "id")
             @authorized_user_ids.include?(creator_id)

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

@@ -194,8 +194,13 @@ end
 #
 # `belt g environment` is synchronous so the worktree is configured before the
 # agent starts. The actual `belt deploy` runs in the background.
+#
+# When `force: true`, the `deploy` tag requirement is bypassed — the caller is
+# explicitly requesting env setup (e.g. the `brainiac fizzy env setup` CLI or
+# the `/api/fizzy/ephemeral-env/:card` endpoint), so no tag is needed.
 def maybe_create_ephemeral_belt_env(worktree_path:, card_number:, project_key:, tags: nil,
-                                    repo_path: nil, agent_name: nil, fetch_live_tags: false)
+                                    repo_path: nil, agent_name: nil, fetch_live_tags: false,
+                                    force: false)
   unless defined?(BeltConfig) && defined?(BeltEnvironment)
     LOG.debug "[EphemeralEnv] Belt utilities not available — skipping"
     return
@@ -216,14 +221,16 @@ def maybe_create_ephemeral_belt_env(worktree_path:, card_number:, project_key:,
     return
   end
 
-  resolved_tags = resolve_ephemeral_env_tags(
-    tags, card_number: card_number, repo_path: repo_path || worktree_path,
-          agent_name: agent_name, fetch_live_tags: fetch_live_tags
-  )
-  tag_list = tag_names(resolved_tags)
-  unless tag_list.include?("deploy")
-    LOG.debug "[EphemeralEnv] Card ##{card_number} tags=#{tag_list.inspect} — no deploy tag, skipping"
-    return
+  unless force
+    resolved_tags = resolve_ephemeral_env_tags(
+      tags, card_number: card_number, repo_path: repo_path || worktree_path,
+            agent_name: agent_name, fetch_live_tags: fetch_live_tags
+    )
+    tag_list = tag_names(resolved_tags)
+    unless tag_list.include?("deploy")
+      LOG.debug "[EphemeralEnv] Card ##{card_number} tags=#{tag_list.inspect} — no deploy tag, skipping"
+      return
+    end
   end
 
   parent_env = BeltConfig.parent_env_for(project_key)
@@ -266,6 +273,75 @@ def ensure_ephemeral_env_for_comment(ctx, card_number, worktree)
   )
 end
 
+# Manually set up an ephemeral Belt env for a card that was already worked,
+# without dispatching an agent. Resolves the card's existing worktree from the
+# work item map, configures + deploys the env synchronously, and tracks it in
+# ephemeral_envs.json so PR-update auto-redeploys (brainiac-github) work.
+#
+# Bypasses the `deploy` tag requirement (force: true) — the caller is asking
+# for this explicitly. Returns a result hash suitable for a JSON API response.
+#
+# @param card_number [Integer, String] Fizzy card number
+# @return [Hash] { status:, env:, url:, worktree:, reason: }
+def setup_ephemeral_env_for_card(card_number)
+  return { status: "error", reason: "card_number required" } unless card_number
+
+  unless defined?(BeltConfig) && defined?(BeltEnvironment)
+    return { status: "error", reason: "Belt utilities not available" }
+  end
+
+  card_number = card_number.to_s
+  entry = work_item_entry_for_card(card_number)
+  return { status: "error", reason: "no work item found for card ##{card_number}" } unless entry
+
+  worktree = entry["worktree"]
+  project_key = entry["project"]
+  unless worktree && File.directory?(worktree)
+    return { status: "error", reason: "worktree missing for card ##{card_number} (#{worktree.inspect})" }
+  end
+
+  env_name = BeltConfig.ephemeral_env_for_card(card_number)
+  already = BeltEnvironment.environment_configured?(worktree: worktree, env_name: env_name)
+
+  maybe_create_ephemeral_belt_env(
+    worktree_path: worktree, card_number: card_number,
+    project_key: project_key, force: true
+  )
+
+  # After setup, resolve the public URL the same way deployment lookups do.
+  url = defined?(deployment_url_for_card) ? (deployment_url_for_card(card_number) || {})[:url] : nil
+
+  {
+    status: "ok",
+    env: env_name,
+    url: url,
+    worktree: worktree,
+    already_configured: already
+  }
+rescue StandardError => e
+  LOG.error "[EphemeralEnv] Manual setup failed for card ##{card_number}: #{e.message}"
+  { status: "error", reason: e.message }
+end
+
+# Resolve the work item entry for a Fizzy card number from work_items.json.
+# Returns a flattened hash with worktree/branch/project or nil.
+def work_item_entry_for_card(card_number)
+  map = load_work_item_map
+  match = map.values.find do |entry|
+    entry.dig("sources", "fizzy", "card_number").to_s == card_number.to_s
+  end
+  return nil unless match
+
+  {
+    "worktree" => match["worktree"],
+    "branch" => match["branch"],
+    "project" => match["project"]
+  }
+rescue StandardError => e
+  LOG.error "[EphemeralEnv] Could not load work item for card ##{card_number}: #{e.message}" if defined?(LOG)
+  nil
+end
+
 def belt_app_for_ephemeral?(worktree_path)
   return BeltEnvironment.belt_app?(worktree_path) if defined?(BeltEnvironment) && BeltEnvironment.respond_to?(:belt_app?)
 

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

@@ -134,36 +134,7 @@ module Brainiac
           # PR merged — post comment on Fizzy card, move to UAT, dispatch UAT agent
           def register_pr_merged
             Brainiac.on(:pr_merged) do |ctx|
-              card_number = ctx[:card_number]
-              next unless card_number
-
-              card_info = ctx[:card_info]
-              card_agent = card_info["agent"]
-              env = Helpers.fizzy_env_for(card_agent)
-              repo_path = ctx[:repo_path]
-              board_key = card_info.dig("sources", "fizzy", "board_key") || Config.board_key_for_project(ctx[:project_config])
-
-              # Post PR link comment
-              pr_url = ctx[:pr_url]
-              pr_title = ctx[:pr_title]
-              branch = ctx[:branch]
-              comment_body = "<p>PR merged into main: <a href=\"#{pr_url}\">#{pr_title}</a></p>" \
-                             "<p>Branch: <code>#{branch}</code></p>"
-              run_cmd("fizzy", "comment", "create", "--card", card_number.to_s, "--body", comment_body,
-                      chdir: repo_path, env: env)
-
-              # Move card to UAT
-              Helpers.move_card_to_column(card_number, "uat",
-                                          project_config: ctx[:project_config],
-                                          agent_name: card_agent,
-                                          board_key: board_key)
-              record_self_move(card_number)
-
-              # Clear deployment tracking
-              clear_deployment_for_card(card_number) if respond_to?(:clear_deployment_for_card)
-
-              # Dispatch UAT agent
-              dispatch_fizzy_uat_agent(ctx)
+              handle_pr_merged(ctx)
             rescue StandardError => e
               LOG.error "[Fizzy] Error in pr_merged hook: #{e.message}" if defined?(LOG)
             end
@@ -292,6 +263,75 @@ module Brainiac
 
           # --- Private helpers ---
 
+          # Body of the :pr_merged hook. Posts the PR link comment, moves the
+          # card to UAT, clears deployment tracking, and dispatches the UAT
+          # agent when enabled. Extracted from the hook block to keep the
+          # registration method within complexity limits.
+          def handle_pr_merged(ctx)
+            card_number = ctx[:card_number]
+            return unless card_number
+
+            card_info = ctx[:card_info]
+            card_agent = card_info["agent"]
+            env = Helpers.fizzy_env_for(card_agent)
+            repo_path = ctx[:repo_path]
+            board_key = card_info.dig("sources", "fizzy", "board_key") || Config.board_key_for_project(ctx[:project_config])
+
+            # Post PR link comment
+            comment_body = "<p>PR merged into main: <a href=\"#{ctx[:pr_url]}\">#{ctx[:pr_title]}</a></p>" \
+                           "<p>Branch: <code>#{ctx[:branch]}</code></p>"
+            run_cmd("fizzy", "comment", "create", "--card", card_number.to_s, "--body", comment_body,
+                    chdir: repo_path, env: env)
+
+            # Move card to UAT
+            Helpers.move_card_to_column(card_number, "uat",
+                                        project_config: ctx[:project_config],
+                                        agent_name: card_agent,
+                                        board_key: board_key)
+            record_self_move(card_number)
+
+            # Clear deployment tracking
+            clear_deployment_for_card(card_number) if respond_to?(:clear_deployment_for_card)
+
+            # Dispatch UAT agent — off by default to save tokens. Globally
+            # enabled via "uat_agent": true, or per-card via the UAT tag
+            # (default "uat") even when the global flag is off.
+            if uat_agent_dispatch?(card_number, repo_path: repo_path, env: env)
+              dispatch_fizzy_uat_agent(ctx)
+            else
+              log_uat_dispatch_skipped(card_number)
+            end
+          end
+
+          # Log that UAT dispatch was skipped for a card (global flag off, no tag).
+          def log_uat_dispatch_skipped(card_number)
+            return unless defined?(LOG)
+
+            LOG.info "[Fizzy] UAT agent disabled (set \"uat_agent\": true in fizzy.json, or add the " \
+                     "\"#{Config.uat_agent_tag}\" tag to this card) — skipping dispatch for card ##{card_number}"
+          end
+
+          # Decide whether to dispatch the UAT agent for a merged card.
+          # True when globally enabled, OR when the card carries the configured
+          # UAT tag (per-card opt-in). Card tags aren't in the pr_merged ctx, so
+          # we fetch them live — only when the global flag is off, to avoid an
+          # extra API call when it's already enabled.
+          def uat_agent_dispatch?(card_number, repo_path:, env: nil)
+            return true if Config.uat_agent_enabled?
+
+            tag = Config.uat_agent_tag
+            return false unless tag && card_number && repo_path
+
+            tags = Helpers.fetch_card_tags(card_number, repo_path: repo_path, env: env)
+            return false unless tags
+
+            has_tag = Helpers.card_has_tag?(tags, tag)
+            if has_tag && defined?(LOG)
+              LOG.info "[Fizzy] Card ##{card_number} has \"#{tag}\" tag — dispatching UAT agent despite global flag being off"
+            end
+            has_tag
+          end
+
           def dispatch_fizzy_uat_agent(ctx)
             card_number = ctx[:card_number]
             card_info = ctx[:card_info]

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

@@ -3,7 +3,7 @@
 module Brainiac
   module Plugins
     module Fizzy
-      VERSION = "0.0.28"
+      VERSION = "0.0.30"
     end
   end
 end

data/lib/brainiac/plugins/fizzy.rb

@@ -103,8 +103,7 @@ module Brainiac
           end
 
           # Card index API (duplicate detection)
-          app.get "/api/card-index" do
-            content_type :json
+          app.get "/api/card-index" do            content_type :json
             halt 404, { error: "Card index not available" }.to_json unless defined?(CARD_INDEX)
 
             query = params["q"]
@@ -116,6 +115,21 @@ module Brainiac
             end
           end
 
+          # Manually set up an ephemeral Belt env for a card that was already
+          # worked — no agent dispatch, no tokens. Configures + deploys the env
+          # in the card's existing worktree and tracks it so PR-update
+          # auto-redeploys keep it fresh.
+          app.post "/api/fizzy/ephemeral-env/:card" do
+            content_type :json
+            card_number = params["card"]
+            result = setup_ephemeral_env_for_card(card_number)
+            if result[:status] == "ok"
+              result.to_json
+            else
+              halt 422, result.to_json
+            end
+          end
+
           # Deployment API routes (if deployments are configured)
           return unless defined?(DEPLOYMENTS_CONFIG)
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brainiac-fizzy
 version: !ruby/object:Gem::Version
-  version: 0.0.28
+  version: 0.0.30
 platform: ruby
 authors:
 - Andy Davis