featureparity 0.0.2 → 0.0.4

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

@@ -10,6 +10,7 @@ module Fp
         api_key: :string,
         profile: :string,
         api_url: :string,
+        environment: :string,
         non_interactive: :boolean
       }.freeze
 
@@ -22,19 +23,22 @@ module Fp
 
         api_key = resolve_api_key(opts)
         profile_name = resolve_profile_name(opts)
-        api_url = opts[:api_url] || Config.get_setting('api_url')
+        api_url = resolve_api_url(opts)
+        environment = opts[:environment] || Config.environment_for(api_url || Config::DEFAULT_API_URL)
 
         puts "Validating API key..."
         validate_key!(api_key, api_url)
 
-        save_profile!(profile_name, api_key, api_url)
+        save_profile!(profile_name, api_key, api_url, environment)
 
         effective_url = api_url || Config::DEFAULT_API_URL
-        domain = URI.parse(effective_url).host.sub(/^api\./, '') rescue 'featureparity.dev'
 
         puts
         puts "✅ Setup complete!"
         puts
+        puts "  API URL:     #{effective_url}"
+        puts "  Environment: #{environment}" if environment
+        puts
         puts "Your profile '#{profile_name}' is ready. Usage:"
         puts
         puts "  fp --profile #{profile_name} projects"
@@ -42,6 +46,9 @@ module Fp
         puts
         puts "Or set FP_API_KEY to skip profiles:"
         puts "  export FP_API_KEY=#{api_key[0..6]}..."
+        puts
+        puts "Verify the resolved configuration any time with:"
+        puts "  fp whoami"
       end
 
       private
@@ -57,12 +64,12 @@ module Fp
           exit 1
         end
 
-        api_url = opts[:api_url] || Config.get_setting('api_url')
+        api_url = opts[:api_url] || config&.explicit_api_url || Config.get_setting('api_url')
         effective_url = api_url || Config::DEFAULT_API_URL
         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
@@ -78,10 +85,17 @@ module Fp
       end
 
       def resolve_profile_name(opts)
+        # --profile / FP_PROFILE may be consumed by the global parser; honor it
+        # via config, but only when explicitly provided (not the implicit
+        # "default" profile fallback) so interactive setup still prompts.
         if opts[:profile]
           return opts[:profile]
         end
 
+        if config && %w[flag env\ (FP_PROFILE)].include?(config.profile_source)
+          return config.profile_name
+        end
+
         if opts[:non_interactive]
           return 'default'
         end
@@ -93,6 +107,31 @@ module Fp
         name.nil? || name.empty? ? 'default' : name
       end
 
+      # Resolve the API URL for setup. Priority: --api-url flag > global setting.
+      # When neither is set and we're interactive, prompt the user so they can
+      # target a non-default environment (self-hosted, staging, ephemeral PR env)
+      # instead of silently defaulting to production.
+      def resolve_api_url(opts)
+        return opts[:api_url] if opts[:api_url] && !opts[:api_url].empty?
+
+        # The global CLI parser consumes --api-url before setup runs; honor it.
+        flag_url = config&.explicit_api_url
+        return flag_url if flag_url
+
+        existing = Config.get_setting('api_url')
+        return existing if existing && !existing.empty?
+
+        # Non-interactive: fall back to the default (nil => DEFAULT_API_URL).
+        return nil if opts[:non_interactive]
+
+        default = Config::DEFAULT_API_URL
+        print "API URL (default: #{default}): "
+        $stdout.flush
+        url = $stdin.gets&.strip
+
+        url.nil? || url.empty? ? nil : url
+      end
+
       def validate_key_format!(key)
         unless key.start_with?('fp_')
           output.error("API key must start with 'fp_' prefix. Got: #{key[0..3]}...")
@@ -107,7 +146,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'
@@ -146,8 +185,8 @@ module Fp
         exit 1
       end
 
-      def save_profile!(name, api_key, api_url)
-        Config.save_profile(name, api_key: api_key, api_url: api_url)
+      def save_profile!(name, api_key, api_url, environment = nil)
+        Config.save_profile(name, api_key: api_key, api_url: api_url, environment: environment)
         puts "  ✓ Profile '#{name}' saved to ~/.config/fp/config.yml"
       end
     end

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/whoami.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # fp whoami
+    #
+    # Show the *resolved* configuration the CLI would actually use for this
+    # invocation: which profile is active, the API URL and where it came from,
+    # the environment that URL targets, and whether an API key is present
+    # (masked — never the full token). Purely local; makes no API calls, so it
+    # works even without a valid key. Honors --profile / --api-url / --json.
+    class Whoami < Base
+      def run(_args)
+        r = config.resolved
+
+        output.success(r) do
+          puts 'Resolved FeatureParity CLI configuration:'
+          puts
+          puts "  Profile:      #{format_value(r[:profile], r[:profile_source])}"
+          puts "  Environment:  #{r[:environment] || '(unknown)'}"
+          puts "  API URL:      #{format_value(r[:api_url], r[:api_url_source])}"
+          puts "  API key:      #{key_line(r)}"
+          puts "  Config file:  #{r[:config_file]}"
+
+          if r[:profile_environment] && r[:profile_environment] != r[:environment]
+            puts
+            puts "  ⚠ Profile is tagged for environment '#{r[:profile_environment]}' " \
+                 "but the resolved API URL points at '#{r[:environment]}'."
+          end
+
+          unless r[:authenticated]
+            puts
+            puts 'No API key resolved. Set one with:'
+            puts '  export FP_API_KEY=fp_...'
+            puts '  fp setup'
+            puts '  fp profile add <name> --api-key fp_...'
+          end
+        end
+      end
+
+      private
+
+      def format_value(value, source)
+        display = value.nil? || value.to_s.empty? ? '(none)' : value
+        source && source != 'none' ? "#{display}  [from #{source}]" : display.to_s
+      end
+
+      def key_line(r)
+        return '(not set)' unless r[:api_key_present]
+
+        "#{r[:api_key_hint]}  [from #{r[:api_key_source]}]"
+      end
+    end
+  end
+end

data/lib/fp/commands.rb

@@ -10,7 +10,9 @@ 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/whoami'
 require_relative 'commands/version'
 require_relative 'commands/help'