featureparity 0.0.2 → 0.0.3

data/lib/fp/commands/report.rb

@@ -2,9 +2,18 @@
 
 module Fp
   module Commands
-    # fp report <slug> --project <slug> --surface X --file path --repo org/repo
-    #   [--pr URL] [--sha X] [--work-item URL] [--ci-url URL] [--title "..."] [--state present|stub]
-    # Report evidence for a requirement
+    # Single requirement:
+    #   fp report <slug> --project <slug> --surface X --file path --repo org/repo
+    #     [--pr URL] [--sha X] [--work-item URL] [--ci-url URL] [--title "..."] [--state present|stub]
+    #
+    # Batch from a JUnit XML report (upload evidence without CI):
+    #   fp report --junit <path> --project <slug> --surface X --repo org/repo
+    #     [--base-dir DIR] [--pr URL] [--sha X] [--work-item URL] [--ci-url URL] [--state present|stub]
+    #
+    # In --junit mode the CLI parses the report, discovers the fp:<slug> markers
+    # in the referenced test files, and uploads evidence for every requirement
+    # the suite covered. This lets an agent run the suite locally and report
+    # evidence without waiting on CI.
     class Report < Base
       KNOWN_FLAGS = {
         project: :string,
@@ -16,7 +25,9 @@ module Fp
         work_item: :string,
         ci_url: :string,
         title: :string,
-        state: :string
+        state: :string,
+        junit: :string,
+        base_dir: :string
       }.freeze
 
       VALID_STATES = %w[present stub].freeze
@@ -24,6 +35,8 @@ module Fp
       def run(args)
         opts, positional = parse_flags(args, KNOWN_FLAGS)
 
+        return run_junit(opts) if opts[:junit]
+
         slug = positional.first
         unless slug
           output.error('Requirement slug is required. Usage: fp report <slug> --project <project> --surface <surface> --file <path> --repo <org/repo>')
@@ -43,20 +56,19 @@ module Fp
           exit 1
         end
 
-        workspace_id = resolve_workspace_id(opts[:project])
+        project_id = resolve_project_id(opts[:project])
 
-        # Find the requirement by slug
-        req_result = client.find_requirement_by_slug(workspace_id, slug)
+        # Verify the requirement exists before reporting evidence
+        req_result = client.find_requirement_by_slug(project_id, slug)
         unless req_result[:ok]
           output.error(req_result[:error], status: req_result[:status])
           exit 1
         end
 
-        requirement = req_result[:data]['requirement']
-
         # Build evidence payload
         params = {
-          requirement_id: requirement['id'],
+          project_id: project_id,
+          slug: slug,
           surface: opts[:surface],
           file: opts[:file],
           repo: opts[:repo],
@@ -66,13 +78,14 @@ module Fp
         params[:sha] = opts[:sha] if opts[:sha]
         params[:work_item_url] = opts[:work_item] if opts[:work_item]
         params[:ci_url] = opts[:ci_url] if opts[:ci_url]
-        params[:example_title] = opts[:title] if opts[:title]
+        params[:title] = opts[:title] if opts[:title]
 
         # Try to report evidence
         result = client.report_evidence(params)
 
         # Evidence API may not exist yet (#1214)
-        if !result[:ok] && result[:status] == 404
+        # API Gateway returns 403 (not 404) for unmatched routes
+        if !result[:ok] && [403, 404].include?(result[:status])
           output.success(params, summary: nil) do
             puts "Evidence for '#{slug}' on surface '#{opts[:surface]}':"
             puts "  State:     #{state}"
@@ -112,6 +125,142 @@ module Fp
           end
         end
       end
+
+      private
+
+      # Batch-upload evidence from a JUnit XML report.
+      def run_junit(opts)
+        require_flag(opts, :project)
+        require_flag(opts, :repo)
+        # --surface is the default for markers that don't pin their own surface
+        # (e.g. `fp:slug@api,web`). It's only strictly required when at least one
+        # matched marker omits a surface — validated below once we know.
+
+        # State override applies to every non-skipped case. Skipped tests always
+        # become stubs regardless. Default lets the report decide per-testcase.
+        state_override = opts[:state]
+        if state_override && !VALID_STATES.include?(state_override)
+          output.error("Invalid state '#{state_override}'. Must be one of: #{VALID_STATES.join(', ')}")
+          output.error('Note: Agents report present or stub. Only CI (#1222) can report passing or failing.')
+          exit 1
+        end
+
+        begin
+          testcases = Fp::JUnit.parse_file(opts[:junit])
+        rescue ArgumentError => e
+          output.error(e.message)
+          exit 1
+        end
+
+        if testcases.empty?
+          output.error("No <testcase> entries found in #{opts[:junit]}")
+          exit 1
+        end
+
+        base_dir = opts[:base_dir] || Dir.pwd
+        result = Fp::JUnit.bind_markers(testcases, base_dir: base_dir, default_surface: opts[:surface])
+        bindings = result[:bindings]
+        unmatched = result[:unmatched]
+        missing_surface = result[:missing_surface] || []
+
+        # Markers that pinned no surface AND no --surface default was given.
+        unless missing_surface.empty?
+          slugs = missing_surface.map { |m| m[:slug] }.uniq.join(', ')
+          output.error("--surface is required: these markers pin no surface of their own: #{slugs}")
+          output.error('Either pass --surface, or annotate the marker (e.g. fp:my_slug@api,web).')
+          exit 1
+        end
+
+        if bindings.empty?
+          output.error("No fp:<slug> markers found for any of the #{testcases.length} testcase(s) in #{opts[:junit]}.")
+          output.error('Ensure your test files contain fp:<slug> markers and that the JUnit report includes file paths.')
+          exit 1
+        end
+
+        project_id = resolve_project_id(opts[:project])
+
+        reported = []
+        skipped_unknown = []
+        api_unavailable = false
+
+        bindings.each do |binding|
+          state = state_override || binding.state
+
+          # Verify the requirement exists before reporting (skip unknown slugs
+          # with a warning rather than aborting the whole batch).
+          req_result = client.find_requirement_by_slug(project_id, binding.slug)
+          unless req_result[:ok]
+            skipped_unknown << binding
+            next
+          end
+
+          params = {
+            project_id: project_id,
+            slug: binding.slug,
+            surface: binding.surface,
+            file: binding.file,
+            repo: opts[:repo],
+            state: state
+          }
+          params[:pr_url] = opts[:pr] if opts[:pr]
+          params[:sha] = opts[:sha] if opts[:sha]
+          params[:work_item_url] = opts[:work_item] if opts[:work_item]
+          params[:ci_url] = opts[:ci_url] if opts[:ci_url]
+          params[:title] = binding.title if binding.title
+
+          report_result = client.report_evidence(params)
+
+          # Evidence API may not exist yet (#1214). API Gateway returns 403
+          # (not 404) for unmatched routes.
+          if !report_result[:ok] && [403, 404].include?(report_result[:status])
+            api_unavailable = true
+            reported << { binding: binding, state: state, recorded: false }
+            next
+          end
+
+          unless report_result[:ok]
+            output.error("Failed to report '#{binding.slug}' (#{binding.surface}): #{report_result[:error]}", status: report_result[:status])
+            exit 1
+          end
+
+          reported << { binding: binding, state: state, recorded: true }
+        end
+
+        emit_junit_summary(opts, reported, skipped_unknown, unmatched, api_unavailable)
+      end
+
+      def emit_junit_summary(opts, reported, skipped_unknown, unmatched, api_unavailable)
+        data = {
+          repo: opts[:repo],
+          reported: reported.map { |r| { slug: r[:binding].slug, surface: r[:binding].surface, file: r[:binding].file, state: r[:state], recorded: r[:recorded] } },
+          skipped_unknown: skipped_unknown.map { |b| { slug: b.slug, surface: b.surface, file: b.file } },
+          unmatched_testcases: unmatched.map { |tc| { name: tc.name, file: tc.file } }
+        }
+
+        output.success(data) do
+          puts "Reported evidence from #{opts[:junit]}:"
+          reported.each do |r|
+            marker = r[:recorded] ? '✓' : '•'
+            puts "  #{marker} #{r[:binding].slug} → #{r[:binding].surface}  (#{r[:state]})  #{r[:binding].file}"
+          end
+
+          unless skipped_unknown.empty?
+            puts
+            puts "⚠️  Skipped #{skipped_unknown.length} marker(s) with no matching requirement in this project:"
+            skipped_unknown.each { |b| puts "     - #{b.slug} → #{b.surface} (#{b.file})" }
+          end
+
+          unless unmatched.empty?
+            puts
+            puts "ℹ️  #{unmatched.length} testcase(s) had no fp:<slug> marker and were skipped."
+          end
+
+          if api_unavailable
+            puts
+            puts '⚠️  Evidence API not available yet. These will be recorded when #1214 is complete.'
+          end
+        end
+      end
     end
   end
 end

data/lib/fp/commands/repos.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # fp repos set|get|list|unset
+    #
+    # Maps FeatureParity surfaces to local repo paths on THIS machine. Stored in
+    # ~/.config/fp/config.yml under `repos`, scoped by project slug. This is a
+    # per-installation convenience (not stored in the FP web app): when an agent
+    # picks up a requirement affecting, say, the `customer_android` surface, it can
+    # run `fp repos get customer_android --project stowzilla` to learn which local
+    # directory to work in. Analogous to how `brainiac projects` maps repos to names.
+    #
+    #   fp repos set <surface> <path> --project <slug> [--repo org/repo]
+    #   fp repos get <surface> --project <slug>
+    #   fp repos list [--project <slug>]
+    #   fp repos unset <surface> --project <slug>
+    class Repos < Base
+      KNOWN_FLAGS = {
+        project: :string,
+        repo: :string
+      }.freeze
+
+      def run(args)
+        subcommand = args.shift
+
+        case subcommand
+        when 'set'   then set_repo(args)
+        when 'get'   then get_repo(args)
+        when 'list'  then list_repos(args)
+        when 'unset' then unset_repo(args)
+        else show_usage
+        end
+      end
+
+      private
+
+      def set_repo(args)
+        opts, positional = parse_flags(args, KNOWN_FLAGS)
+        require_flag(opts, :project)
+
+        surface = positional[0]
+        path = positional[1]
+
+        unless surface && path
+          output.error('Usage: fp repos set <surface> <path> --project <slug> [--repo org/repo]')
+          exit 1
+        end
+
+        # Store an absolute, tilde-expanded path so agents get a directly usable location.
+        expanded = File.expand_path(path)
+        unless File.directory?(expanded)
+          output.error("Path does not exist or is not a directory: #{expanded}")
+          exit 1
+        end
+
+        entry = Config.set_repo(opts[:project], surface, path: expanded, repo: opts[:repo])
+
+        output.success({ project: opts[:project], surface: surface }.merge(entry)) do
+          puts "Mapped surface '#{surface}' (project '#{opts[:project]}') to:"
+          puts "  path: #{entry['path']}"
+          puts "  repo: #{entry['repo']}" if entry['repo']
+        end
+      end
+
+      def get_repo(args)
+        opts, positional = parse_flags(args, KNOWN_FLAGS)
+        require_flag(opts, :project)
+
+        surface = positional[0]
+        unless surface
+          output.error('Usage: fp repos get <surface> --project <slug>')
+          exit 1
+        end
+
+        entry = Config.repo_for_surface(opts[:project], surface)
+
+        unless entry
+          output.error("No repo mapped for surface '#{surface}' in project '#{opts[:project]}'.")
+          output.error("Map one with: fp repos set #{surface} /path/to/repo --project #{opts[:project]}")
+          exit 1
+        end
+
+        output.success({ project: opts[:project], surface: surface }.merge(entry)) do
+          # Print just the path so this composes in shell: cd "$(fp repos get ... )"
+          puts entry['path']
+        end
+      end
+
+      def list_repos(args)
+        opts, = parse_flags(args, KNOWN_FLAGS)
+
+        repos_map = if opts[:project]
+                      { opts[:project] => Config.repos_for_project(opts[:project]) }
+                    else
+                      Config.repos_map
+                    end
+
+        # Drop empty projects (e.g. an explicit --project with no mappings yet).
+        repos_map = repos_map.reject { |_project, surfaces| surfaces.nil? || surfaces.empty? }
+
+        output.success({ repos: repos_map }) do
+          if repos_map.empty?
+            if opts[:project]
+              puts "No repos mapped for project '#{opts[:project]}'."
+            else
+              puts 'No repos mapped on this machine.'
+            end
+            puts
+            puts 'Map one with:'
+            puts '  fp repos set <surface> /path/to/repo --project <slug> [--repo org/repo]'
+          else
+            repos_map.each do |project, surfaces|
+              puts "#{project}:"
+              surfaces.sort.each do |surface, entry|
+                repo = entry['repo'] ? " (#{entry['repo']})" : ''
+                puts "  #{surface} -> #{entry['path']}#{repo}"
+              end
+            end
+          end
+        end
+      end
+
+      def unset_repo(args)
+        opts, positional = parse_flags(args, KNOWN_FLAGS)
+        require_flag(opts, :project)
+
+        surface = positional[0]
+        unless surface
+          output.error('Usage: fp repos unset <surface> --project <slug>')
+          exit 1
+        end
+
+        removed = Config.unset_repo(opts[:project], surface)
+
+        unless removed
+          output.error("No repo mapped for surface '#{surface}' in project '#{opts[:project]}'.")
+          exit 1
+        end
+
+        output.success({ project: opts[:project], surface: surface, removed: true }) do
+          puts "Unmapped surface '#{surface}' from project '#{opts[:project]}'."
+        end
+      end
+
+      def show_usage
+        output.error('Usage: fp repos <set|get|list|unset>')
+        puts
+        puts 'Commands:'
+        puts '  fp repos set <surface> <path> --project <slug> [--repo org/repo]'
+        puts '                                     Map a surface to a local repo path'
+        puts '  fp repos get <surface> --project <slug>'
+        puts '                                     Print the local path for a surface'
+        puts '  fp repos list [--project <slug>]   List surface -> path mappings'
+        puts '  fp repos unset <surface> --project <slug>'
+        puts '                                     Remove a mapping'
+        puts
+        puts 'Mappings are local to this machine (stored in ~/.config/fp/config.yml).'
+        puts
+        puts 'Examples:'
+        puts '  fp repos set customer_android ~/code/customer-android \\'
+        puts '    --project stowzilla --repo stowzilla/customer-android'
+        puts '  fp repos get customer_android --project stowzilla'
+        puts '  cd "$(fp repos get customer_android --project stowzilla)"'
+        exit 1
+      end
+    end
+  end
+end

data/lib/fp/commands/setup.rb

@@ -62,7 +62,7 @@ module Fp
         domain = URI.parse(effective_url).host.sub(/^api\./, '') rescue 'featureparity.dev'
 
         puts "Get your API key from: https://#{domain}"
-        puts "(Workspace Settings → API Keys → Mint Key)"
+        puts "(Project Settings → API Keys → Mint Key)"
         puts
         print "Paste your API key (starts with fp_): "
         $stdout.flush
@@ -107,7 +107,7 @@ module Fp
 
       def validate_key!(api_key, api_url)
         url = (api_url || Config::DEFAULT_API_URL).chomp('/')
-        uri = URI.parse("#{url}/api/workspaces")
+        uri = URI.parse("#{url}/api/projects")
 
         http = Net::HTTP.new(uri.host, uri.port)
         http.use_ssl = uri.scheme == 'https'

data/lib/fp/commands/show.rb

@@ -15,8 +15,8 @@ module Fp
           exit 1
         end
 
-        workspace_id = resolve_workspace_id(opts[:project])
-        result = client.find_requirement_by_slug(workspace_id, slug)
+        project_id = resolve_project_id(opts[:project])
+        result = client.find_requirement_by_slug(project_id, slug)
 
         unless result[:ok]
           output.error(result[:error], status: result[:status])
@@ -38,6 +38,7 @@ module Fp
         puts
         puts "Slug:     #{req['slug']}"
         puts "Status:   #{req['status']}"
+        puts "Category: #{req['category'] || '(none)'}"
         puts "Parent:   #{req['parent_id'] || '(none)'}"
         puts
 

data/lib/fp/commands/surfaces.rb

@@ -8,21 +8,21 @@ module Fp
         opts, = parse_flags(args)
         require_flag(opts, :project)
 
-        workspace_id = resolve_workspace_id(opts[:project])
-        result = client.get_project(workspace_id)
+        project_id = resolve_project_id(opts[:project])
+        result = client.list_surfaces(project_id)
 
         unless result[:ok]
           output.error(result[:error], status: result[:status])
           exit 1
         end
 
-        workspace = result[:data]['workspace']
-        surfaces = workspace['available_surfaces'] || []
+        surface_records = result[:data]['surfaces'] || []
+        surfaces = surface_records.map { |s| s['key'] }
 
         output.success({ surfaces: surfaces, project: opts[:project] }) do
           if surfaces.empty?
             puts "No surfaces configured for project '#{opts[:project]}'."
-            puts 'Configure available_surfaces in the web app.'
+            puts 'Configure surfaces in the web app.'
           else
             puts "Surfaces for '#{opts[:project]}':"
             surfaces.each { |s| puts "  - #{s}" }

data/lib/fp/commands.rb

@@ -10,6 +10,7 @@ require_relative 'commands/report'
 require_relative 'commands/matrix'
 require_relative 'commands/profile'
 require_relative 'commands/config_cmd'
+require_relative 'commands/repos'
 require_relative 'commands/setup'
 require_relative 'commands/version'
 require_relative 'commands/help'

data/lib/fp/config.rb

@@ -15,9 +15,15 @@ module Fp
   #
   # API key resolution priority:
   #   1. FP_API_KEY env var
-  #   2. Profile api_key (--profile flag > FP_PROFILE env var)
+  #   2. Profile api_key (--profile flag > FP_PROFILE env var > "default" profile)
+  #
+  # Profile name resolution priority:
+  #   1. --profile CLI flag
+  #   2. FP_PROFILE env var
+  #   3. A profile literally named "default" (if one exists in config.yml)
   class Config
     DEFAULT_API_URL = 'https://api.featureparity.dev'
+    DEFAULT_PROFILE_NAME = 'default'
     CONFIG_DIR = File.expand_path('~/.config/fp')
     CONFIG_FILE = File.join(CONFIG_DIR, 'config.yml')
 
@@ -99,6 +105,72 @@ module Fp
         load_profiles.key?(name)
       end
 
+      # --- Repo → surface mappings (per-machine, local) ---
+      #
+      # Stored under a top-level `repos` key in config.yml, scoped by project slug:
+      #
+      #   repos:
+      #     stowzilla:
+      #       customer_android:
+      #         path: /home/dev/code/customer-android
+      #         repo: stowzilla/customer-android
+      #
+      # This is intentionally local (per fp installation) — it maps FeatureParity
+      # surfaces to wherever the code lives on THIS machine, so an agent working a
+      # requirement for a given surface knows which directory to open. Analogous to
+      # how `brainiac projects` maps repos to project names.
+
+      # Return the full repos mapping ({ project => { surface => {path, repo} } }).
+      def repos_map
+        config = load_config
+        config['repos'] || {}
+      end
+
+      # Return the surface => {path, repo} mapping for a single project.
+      def repos_for_project(project)
+        repos_map[project.to_s] || {}
+      end
+
+      # Look up the mapping for a single surface within a project.
+      # Returns a hash like { 'path' => ..., 'repo' => ... } or nil if unmapped.
+      def repo_for_surface(project, surface)
+        repos_for_project(project)[surface.to_s]
+      end
+
+      # Map a surface (within a project) to a local path and optional org/repo.
+      def set_repo(project, surface, path:, repo: nil)
+        FileUtils.mkdir_p(CONFIG_DIR)
+        ensure_config_file!
+
+        config = load_config
+        config['repos'] ||= {}
+        config['repos'][project.to_s] ||= {}
+
+        entry = { 'path' => path }
+        entry['repo'] = repo if repo && !repo.to_s.empty?
+        config['repos'][project.to_s][surface.to_s] = entry
+
+        write_config!(config)
+        entry
+      end
+
+      # Remove a surface mapping within a project. Prunes empty project hashes.
+      # Returns true if something was removed, false otherwise.
+      def unset_repo(project, surface)
+        config = load_config
+        return false unless config['repos'].is_a?(Hash)
+
+        project_map = config['repos'][project.to_s]
+        return false unless project_map.is_a?(Hash) && project_map.key?(surface.to_s)
+
+        project_map.delete(surface.to_s)
+        config['repos'].delete(project.to_s) if project_map.empty?
+        config.delete('repos') if config['repos'].empty?
+
+        write_config!(config)
+        true
+      end
+
       private
 
       def ensure_config_file!
@@ -117,7 +189,16 @@ module Fp
     private
 
     def resolve_profile_name(explicit_profile)
-      explicit_profile || ENV['FP_PROFILE']
+      # 1. Explicit --profile flag  2. FP_PROFILE env var
+      name = explicit_profile || ENV['FP_PROFILE']
+      return name if name && !name.empty?
+
+      # 3. Fall back to a profile literally named "default", if one exists.
+      #    This mirrors AWS/git/gcloud, which all consult a default profile when
+      #    nothing else is specified.
+      return DEFAULT_PROFILE_NAME if self.class.profile_exists?(DEFAULT_PROFILE_NAME)
+
+      nil
     end
 
     def resolve_api_key