brainiac-featureparity 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5e779e16dcca90b0d9197b375590889530e09c9cef791ebf5c08af05bf01152d
+  data.tar.gz: 3a59dc6ffe38d72fe0034c9aa3180faf08e0dc27bc0d8aa2b1ae9cc4192a1743
+SHA512:
+  metadata.gz: b239f505695e27823695c4db25265848b267a68ae752533aae0f535248aa68a86e86bf7887da5bd5804d2b04ca546ce05222580627e67d182f91d54a0c5c9069
+  data.tar.gz: bc016d62bb67fc6d3f522c3d3f0b5f02f5189725fa216b2f98946615ed496779ec83b95ead917eeccf892d630fb893c985caaa32bc3221f019ecdf58975f5d25

data/README.md

@@ -0,0 +1,135 @@
+# brainiac-featureparity
+
+FeatureParity plugin for [Brainiac](https://github.com/stowzilla/brainiac): your agents take
+work straight from [FeatureParity](https://featureparity.dev).
+
+- **Start work.** Someone presses **Start work** on a requirement and picks one of your
+  agents. That agent gets a worktree for the requirement and implements it, with tests
+  bound to it (`fp:<slug>`).
+- **Tags.** Someone tags your agent in a requirement's comments (for example "please
+  re-check the suspect tests"). The agent reads the comment, does it, and replies on the
+  requirement.
+- **Coverage gaps** (opt-in). A requirement goes live on a surface with no tests. An agent
+  writes them.
+- **Rejections.** A human rejects a change your agent proposed. The same agent reworks it in
+  its existing worktree.
+
+Every delivery is signed by FeatureParity, and the plugin refuses anything it can't verify.
+
+## Install
+
+You need Brainiac running with a public URL that reaches it (Brainiac's setup uses an
+[ngrok](https://ngrok.com) tunnel), and an account on FeatureParity.
+
+```bash
+gem install brainiac          # if you don't have Brainiac yet
+brainiac setup                # its own first-run setup
+brainiac install featureparity
+brainiac featureparity setup  # writes ~/.brainiac/featureparity.json
+brainiac restart
+```
+
+Every repository your agents should work in must be a project in `~/.brainiac/projects.json`
+(Brainiac's usual setup). FeatureParity names projects by their slug (`fp projects`). Name the
+Brainiac project the same, or map it (see Configuration).
+
+## Connect FeatureParity
+
+### 1. Point your agents at Brainiac
+
+In FeatureParity, open **Agents & API keys** (under your account). For each agent that runs
+on this Brainiac, click **Wake-up** and enter:
+
+```
+https://<your-public-url>/featureparity
+```
+
+FeatureParity shows a signing secret (`whsec_...`) **once**. Add it to
+`~/.brainiac/featureparity.json`:
+
+```json
+{ "signing_secrets": ["whsec_..."] }
+```
+
+All your agents can share the one address, because each delivery names the agent it's for.
+Each key has its own secret, so list every one.
+
+The agent key's name has to match the Brainiac agent: a key named `galen` or shown as `Galen`
+reaches the Brainiac agent `Galen`. Map names that differ with `"agents"`.
+
+### 2. Optional: project-wide events
+
+For events no single agent owns, add a webhook in **Project Settings → Integrations**: same
+URL, provider **generic**. Subscribe to **Change rejected** and, if you turn on
+`dispatch_gaps`, **Coverage gap**. Add its signing secret to `signing_secrets` too.
+
+If your agents already have wake-up addresses, there's no need to subscribe this webhook to
+**Work started** or **Agent tagged**. If you do, the plugin notices the repeat and starts the
+agent only once.
+
+### 3. Try it
+
+Open an approved requirement, click **Start work**, and pick your agent. The page tells you
+whether the agent received it. `brainiac logs` shows the dispatch. Each webhook's **Recent
+deliveries** in FeatureParity shows what was sent and what Brainiac answered.
+
+## Configuration
+
+`~/.brainiac/featureparity.json` (reloaded when it changes):
+
+```json
+{
+  "api_base_url": "https://api.featureparity.dev",
+  "environment": "prod",
+  "accept_environments": ["prod"],
+  "signing_secrets": ["whsec_..."],
+  "agents": { "claude-laptop": "Galen" },
+  "default_agent": "Galen",
+  "projects": { "feature-parity": "feature_parity" },
+  "dispatch_gaps": false,
+  "gap_agent": "Galen"
+}
+```
+
+| Key | What it does |
+|-----|--------------|
+| `signing_secrets` | The `whsec_` secrets FeatureParity showed you. With any set, unsigned or wrongly signed deliveries are refused (401), and so is one stamped more than 5 minutes away from now. Leave it empty only while setting up. |
+| `agents` | FeatureParity agent key name (or display name) → Brainiac agent name, for names that differ. Otherwise they match case-insensitively. |
+| `default_agent` | Who takes **Start work** when no agent was picked. |
+| `projects` | FeatureParity project slug → Brainiac project key, for keys that differ. A project in `projects.json` can also declare `"featureparity_project": "<slug>"`. |
+| `dispatch_gaps` | Start an agent on `coverage.gap_detected` to write the missing tests. Off by default, because approving a batch of requirements reports a gap for each one. |
+| `gap_agent` | Who writes those tests (defaults to `default_agent`). |
+| `environment`, `accept_environments` | Which FeatureParity environments this Brainiac serves. A delivery from a preview environment (`fizzy-1234`) is ignored unless listed here. `["*"]` accepts all. |
+
+## Events
+
+| Event | What happens |
+|-------|--------------|
+| `requirement.work_started` | The named agent (or `default_agent`) gets the requirement's worktree (`fp-<slug>`, reused if it exists) and implements it. |
+| `requirement.agent_mentioned` | The tagged agent, if it runs here, answers the comment, working in the requirement's worktree when there is one. |
+| `coverage.gap_detected` | With `dispatch_gaps`, `gap_agent` writes tests for the surfaces listed. Otherwise it's acknowledged. |
+| `requirement.change_rejected` | The agent that proposed the change reworks it in its worktree, with the reviewer's reason. |
+| others | Acknowledged. |
+
+The plugin answers within FeatureParity's 5-second window and does the work in the
+background. FeatureParity retries a delivery that gets no answer; the plugin acts on each
+delivery, and each Start work, comment or gap, once.
+
+## CLI
+
+```bash
+brainiac featureparity setup   # create the config and show these steps
+brainiac featureparity config  # show the config (secrets shortened)
+brainiac featureparity status  # what's set up
+brainiac featureparity help
+```
+
+## Requirements
+
+- Brainiac >= 0.1.8
+- Ruby >= 3.4
+- A FeatureParity account (agent wake-up addresses and signed deliveries need the current FeatureParity)
+
+## License
+
+MIT

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

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Brainiac
+  module Plugins
+    module Featureparity
+      # CLI commands for the FeatureParity plugin.
+      # Accessed via `brainiac featureparity <command>`.
+      module CLI
+        CONFIG_FILE = File.join(BRAINIAC_DIR, "featureparity.json")
+
+        class << self
+          def cli(args)
+            command = args.shift
+            case command
+            when "setup"
+              setup_command
+            when "config"
+              config_command
+            when "status"
+              status_command
+            when "help", nil
+              help_command
+            else
+              puts "Unknown command: #{command}"
+              puts "Run 'brainiac featureparity help' for usage."
+              exit 1
+            end
+          end
+
+          def completions
+            %w[setup config status help]
+          end
+
+          def configured?
+            File.exist?(CONFIG_FILE)
+          end
+
+          def help_text
+            "Manage FeatureParity webhook integration"
+          end
+
+          private
+
+          def setup_command
+            puts "Setting up FeatureParity plugin..."
+
+            if File.exist?(CONFIG_FILE)
+              puts "Config file already exists at #{CONFIG_FILE}"
+              print "Overwrite? [y/N] "
+              answer = $stdin.gets&.strip&.downcase
+              return unless answer == "y"
+            end
+
+            config = {
+              "api_base_url" => "https://api.featureparity.dev",
+              "signing_secrets" => [],
+              "default_agent" => nil,
+              "dispatch_gaps" => false,
+              "authorized_users" => [],
+              "authorized_role_ids" => []
+            }
+
+            File.write(CONFIG_FILE, JSON.pretty_generate(config))
+            puts "Created config at #{CONFIG_FILE}\n\n"
+            puts <<~STEPS
+              Next steps (your public URL is whatever reaches this server, e.g. an ngrok tunnel):
+              1. In FeatureParity, Agents & API keys: give each agent that runs here the wake-up address
+                 https://<your-public-url>/featureparity, and put the secret it shows in "signing_secrets".
+              2. Optional: Project Settings > Integrations > Add webhook, same URL, provider 'generic'
+                 ('Change rejected', 'Coverage gap'). Add its secret to "signing_secrets" too.
+              3. Agents match by name and projects by slug; map any that differ with "agents"/"projects".
+
+            STEPS
+            puts "Run 'brainiac restart' to load the plugin."
+          end
+
+          def config_command
+            unless File.exist?(CONFIG_FILE)
+              puts "No config file found. Run 'brainiac featureparity setup' first."
+              exit 1
+            end
+
+            config = JSON.parse(File.read(CONFIG_FILE))
+            # Never print the signing secrets themselves.
+            config["signing_secrets"] = Array(config["signing_secrets"]).map { |s| "#{s.to_s[0, 10]}…" }
+            puts "FeatureParity Config (#{CONFIG_FILE}):"
+            puts JSON.pretty_generate(config)
+          end
+
+          def status_command
+            puts "FeatureParity Plugin Status"
+            puts "=" * 30
+
+            if File.exist?(CONFIG_FILE)
+              config = JSON.parse(File.read(CONFIG_FILE))
+              puts "Config: ✓ #{CONFIG_FILE}"
+              puts "API URL: #{config['api_base_url']}"
+              secrets = Array(config["signing_secrets"]).size
+              puts(secrets.zero? ? "Signatures: ✗ not checked (add signing_secrets)" : "Signatures: ✓ #{secrets} secret(s)")
+              gap_agent = config["gap_agent"] || config["default_agent"]
+              puts "Coverage gaps: #{config['dispatch_gaps'] ? "dispatched to #{gap_agent}" : 'acknowledged only'}"
+            else
+              puts "Config: ✗ Not configured (run 'brainiac featureparity setup')"
+            end
+
+            puts
+            puts "Webhook endpoint: POST /featureparity"
+            puts "API endpoint: GET /api/featureparity"
+          end
+
+          def help_command
+            puts <<~HELP
+              brainiac featureparity — #{help_text}
+
+              Usage:
+                brainiac featureparity setup   Create config file and show setup instructions
+                brainiac featureparity config  Show current configuration
+                brainiac featureparity status  Show plugin status
+                brainiac featureparity help    Show this help message
+
+              Webhook Events:
+                The plugin receives webhooks from FeatureParity and dispatches agents
+                when requirements are rejected, evidence fails, or coverage gaps are detected.
+
+                Currently handled:
+                - requirement.change_rejected → Dispatch agent to fix rejected requirement
+
+              Configuration:
+                Config is stored at ~/.brainiac/featureparity.json
+            HELP
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Brainiac
+  module Plugins
+    module Featureparity
+      # Config file at ~/.brainiac/featureparity.json
+      #
+      # {
+      #   "api_base_url": "https://api.featureparity.dev",
+      #   "environment": "prod",
+      #   "accept_environments": ["prod", "staging"],
+      #   "signing_secrets": ["whsec_..."],
+      #   "agents": { "galen": "Galen" },
+      #   "default_agent": "Galen",
+      #   "projects": { "feature-parity": "feature_parity" },
+      #   "dispatch_gaps": false,
+      #   "gap_agent": "Galen",
+      #   "authorized_users": [],
+      #   "authorized_role_ids": []
+      # }
+      #
+      # signing_secrets: the whsec_ secrets FeatureParity showed you, one per project webhook
+      #   or agent wake-up address pointed here. When any are set, an unsigned or wrongly
+      #   signed delivery is refused (401). Leave empty only while setting up.
+      # agents: FeatureParity agent key name (or display name) → Brainiac agent name, for when
+      #   they differ. Otherwise the names are matched case-insensitively.
+      # default_agent: who takes "Start work" with no agent named.
+      # projects: FeatureParity project slug → key in ~/.brainiac/projects.json, for when they
+      #   differ. A project entry can also say "featureparity_project": "<slug>".
+      # dispatch_gaps: start an agent on coverage.gap_detected (write the missing tests).
+      #   Off by default: approving a batch of requirements reports a gap for each.
+      #
+      # Environment matching:
+      # - `environment`: Which environment this brainiac instance represents (default: "prod")
+      # - `accept_environments`: Which environments' webhooks to process (default: same as environment)
+      #
+      # This prevents dev/ephemeral webhooks from triggering prod agents and vice versa.
+      # An ephemeral FP environment like "fizzy-1234" sends webhooks with that environment
+      # in the metadata — unless accept_environments includes "fizzy-1234", those are ignored.
+      module Config
+        CONFIG_FILE = File.join(BRAINIAC_DIR, "featureparity.json")
+        @config = nil
+        @config_mtime = nil
+
+        class << self
+          def load!
+            @config = read_config_file
+            @config_mtime = File.exist?(CONFIG_FILE) ? File.mtime(CONFIG_FILE) : nil
+            LOG.info "[FeatureParity] Config loaded from #{CONFIG_FILE}" if @config
+          end
+
+          def current
+            reload_if_changed
+            @config || {}
+          end
+
+          def reload_if_changed
+            return unless File.exist?(CONFIG_FILE)
+
+            mtime = File.mtime(CONFIG_FILE)
+            return if @config_mtime && mtime == @config_mtime
+
+            @config = read_config_file
+            @config_mtime = mtime
+            LOG.debug "[FeatureParity] Config reloaded" if LOG.debug?
+          end
+
+          def api_base_url
+            current["api_base_url"] || "https://api.featureparity.dev"
+          end
+
+          # Which environment this brainiac instance represents
+          def environment
+            current["environment"] || "prod"
+          end
+
+          # Which environments' webhooks to process. Defaults to just this environment.
+          # Use ["prod", "staging", "dev"] to accept webhooks from multiple environments.
+          # Use ["*"] to accept webhooks from any environment (useful for dev/testing).
+          def accept_environments
+            current["accept_environments"] || [environment]
+          end
+
+          # Check if this brainiac instance should process a webhook from the given environment.
+          # Returns true if:
+          # - accept_environments includes "*" (accept all)
+          # - accept_environments includes the webhook's environment
+          # - The webhook doesn't specify an environment (legacy/backward compatibility)
+          def should_accept_environment?(webhook_environment)
+            # No environment specified in webhook = backward compatibility, accept it
+            return true if webhook_environment.nil? || webhook_environment.to_s.strip.empty?
+
+            # Accept all environments
+            return true if accept_environments.include?("*")
+
+            # Check if this specific environment is accepted
+            accept_environments.include?(webhook_environment.to_s)
+          end
+
+          def signing_secrets
+            Array(current["signing_secrets"]).map(&:to_s).reject(&:empty?)
+          end
+
+          def agent_map
+            (current["agents"] || {}).transform_keys { |k| k.to_s.downcase }
+          end
+
+          def default_agent
+            current["default_agent"]
+          end
+
+          def project_map
+            current["projects"] || {}
+          end
+
+          def dispatch_gaps?
+            current["dispatch_gaps"] == true
+          end
+
+          def gap_agent
+            current["gap_agent"] || default_agent
+          end
+
+          def authorized_users
+            current["authorized_users"] || []
+          end
+
+          def authorized_role_ids
+            current["authorized_role_ids"] || []
+          end
+
+          private
+
+          def read_config_file
+            return {} unless File.exist?(CONFIG_FILE)
+
+            JSON.parse(File.read(CONFIG_FILE))
+          rescue JSON::ParserError => e
+            LOG.warn "[FeatureParity] Invalid JSON in config: #{e.message}"
+            {}
+          end
+        end
+      end
+    end
+  end
+end