featureparity 0.0.3 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 166fe16ad8636be840cc889d1104ad4e6a5f3c84cd046f0a94f291412083f344
-  data.tar.gz: e88add572a4cfd638768ae4d65de5a207b6a64c450ca0fdce426f48e8e51427e
+  metadata.gz: 1208887c7ed99691e476438cdcb50d36f09e3ee3b22931c7d8d9ea246438fb89
+  data.tar.gz: b2fb9b9d7bad99bde7e2f8b0789105072cd19647ed46f0ea4d4d6e43a28fd319
 SHA512:
-  metadata.gz: c3d5bee44367c02c8329c10bdb3c0615978c405c30d46fb002b1ca7fe6676a61075dc83bf4ba02ba01faf828d80fa7f56af2116fd5287f662166bf547d9c5468
-  data.tar.gz: 5b627165e1205cca331626fd46b35d7ad71b9ed666fd63ebe96569b2e2989b4b14ff35426d099a1e7dfd8afe7ac16c7984e53ec1052262a374914505c950404c
+  metadata.gz: 5d70c2ae5afb585a1f54da0c2efb244965a0f419001c9ed8f46d1895a5f37ee12ece8a1195627859eeeaff2fd3910cf4dfdb593fc41c69440bc97020ff31a17a
+  data.tar.gz: 23d9038f6850138f295501a56ea00f872ff828eab5a2822482c306a56ba39cdec2a1016761af8f4f87932a3d9f264faf0c9dad3302d2a96ea5adceb86b3e29c6

data/lib/fp/cli.rb

@@ -15,6 +15,7 @@ module Fp
       'config' => Commands::ConfigCmd,
       'repos' => Commands::Repos,
       'setup' => Commands::Setup,
+      'whoami' => Commands::Whoami,
       'version' => Commands::Version,
       'help' => Commands::Help
     }.freeze
@@ -35,7 +36,7 @@ module Fp
         end
 
         # Profile/config commands don't need auth
-        needs_auth = !%w[profile config repos setup version help].include?(command_name)
+        needs_auth = !%w[profile config repos setup whoami version help].include?(command_name)
 
         if needs_auth
           config = Config.new(profile: global_opts[:profile], api_url: global_opts[:api_url])

data/lib/fp/client.rb

@@ -27,6 +27,11 @@ module Fp
       get("/api/projects/#{project_id}/surfaces")
     end
 
+    # POST /projects/:id/surfaces
+    def create_surface(project_id, params)
+      post("/api/projects/#{project_id}/surfaces", params)
+    end
+
     # GET /requirements
     def list_requirements(project_id: nil, status: nil, category: nil)
       params = {}
@@ -67,6 +72,15 @@ module Fp
       put("/api/requirements/#{id}", params)
     end
 
+    # GET /projects/:project_id/evidence — the receipts already filed for a project,
+    # optionally narrowed to one requirement slug and/or surface.
+    def list_evidence(project_id, slug: nil, surface: nil)
+      params = {}
+      params[:slug] = slug if slug
+      params[:surface] = surface if surface
+      get("/api/projects/#{project_id}/evidence", params)
+    end
+
     # POST /projects/:project_id/evidence (direct reporting)
     def report_evidence(params)
       project_id = params.delete(:project_id)

data/lib/fp/commands/config_cmd.rb

@@ -19,6 +19,9 @@ module Fp
           unset_setting(args)
         when 'list'
           list_settings
+        when 'whoami'
+          # Alias for `fp whoami` — show the fully resolved configuration.
+          Whoami.new(client: client, output: output, config: config).run(args)
         else
           show_usage
         end
@@ -105,17 +108,22 @@ module Fp
             puts "Global settings:"
             settings.each { |k, v| puts "  #{k} = #{v}" }
           end
+          puts
+          puts "This shows only global settings. To see the fully resolved config"
+          puts "(profile, environment, API URL, and key — with the source of each):"
+          puts "  fp whoami"
         end
       end
 
       def show_usage
-        output.error('Usage: fp config <set|get|unset|list>')
+        output.error('Usage: fp config <set|get|unset|list|whoami>')
         puts
         puts 'Commands:'
         puts '  fp config set <key> <value>   Set a global setting'
         puts '  fp config get <key>           Get a setting value'
         puts '  fp config unset <key>         Remove a setting'
         puts '  fp config list                Show all global settings'
+        puts '  fp config whoami              Show the resolved config (alias of `fp whoami`)'
         puts
         puts 'Available settings:'
         puts '  api_url   Base URL for the FeatureParity API'
@@ -123,6 +131,7 @@ module Fp
         puts 'Examples:'
         puts '  fp config set api_url https://api.dev.featureparity.dev'
         puts '  fp config get api_url'
+        puts '  fp config whoami'
         exit 1
       end
     end

data/lib/fp/commands/help.rb

@@ -14,6 +14,7 @@ module Fp
           COMMANDS
             projects                          List projects you have access to
             surfaces --project <slug>         List surfaces for a project
+            surfaces add <key> --project ...  Create a surface
             list --project <slug>             List active requirements
             show <slug> --project <slug>      Show requirement details
             propose --project <slug> ...      Propose a new requirement (as draft)
@@ -22,6 +23,7 @@ module Fp
             matrix --project <slug>           Show the parity matrix
             profile add|list                  Manage named profiles
             config set|get|unset|list         Manage global settings
+            whoami                            Show the resolved config (profile, env, API URL, key)
             repos set|get|list|unset          Map surfaces to local repo paths
             setup                             Interactive first-time setup
             version                           Show version
@@ -56,12 +58,26 @@ module Fp
             # First-time setup (interactive)
             fp setup
 
+            # Show the resolved configuration (which profile/env/API URL/key is in effect)
+            fp whoami
+            fp whoami --json
+            fp --profile staging whoami
+
             # Non-interactive setup for CI/automation
             fp setup --api-key fp_... --profile ci-agent --non-interactive
 
             # List projects
             fp projects
 
+            # List the surfaces a project tracks (requirements may only name these)
+            fp surfaces --project stowzilla
+
+            # Create a surface (agents can do this — no need to wait on the web app)
+            fp surfaces add customer_android --project stowzilla \\
+              --name "Customer Android App" \\
+              --kind android \\
+              --repo stowzilla/customer-android
+
             # List requirements for a project
             fp list --project stowzilla
 
@@ -83,6 +99,14 @@ module Fp
               --acceptance "QR code is printed and scannable" \\
               --category functional
 
+            # Nest a requirement under a parent (--parent takes the parent's SLUG).
+            # A child's --required surfaces must be a subset of its parent's.
+            fp propose --project stowzilla \\
+              --slug print_container_qr_ios \\
+              --name "Print QR on iOS" \\
+              --parent print_container_qr \\
+              --required customer_ios
+
             # Report evidence for a requirement
             fp report print_container_qr --project stowzilla \\
               --surface customer_android \\

data/lib/fp/commands/profile.rb

@@ -7,7 +7,8 @@ module Fp
     class Profile < Base
       KNOWN_FLAGS = {
         api_key: :string,
-        api_url: :string
+        api_url: :string,
+        environment: :string
       }.freeze
 
       def run(args)
@@ -42,11 +43,18 @@ module Fp
           exit 1
         end
 
-        Config.save_profile(name, api_key: opts[:api_key], api_url: opts[:api_url])
+        # The global CLI parser consumes --api-url before the command runs, so
+        # honor it via the config object when the local flag wasn't captured.
+        api_url = opts[:api_url] || config&.explicit_api_url
+        Config.save_profile(name, api_key: opts[:api_key], api_url: api_url, environment: opts[:environment])
 
-        output.success({ profile: name, api_url: opts[:api_url] || Config::DEFAULT_API_URL }) do
+        effective_url = api_url || Config.get_setting('api_url') || Config::DEFAULT_API_URL
+        environment = opts[:environment] || Config.environment_for(effective_url)
+
+        output.success({ profile: name, api_url: effective_url, environment: environment }) do
           puts "Profile '#{name}' saved."
-          puts "  API URL: #{opts[:api_url] || Config::DEFAULT_API_URL}"
+          puts "  API URL:     #{effective_url}"
+          puts "  Environment: #{environment}" if environment
           puts
           puts 'Use this profile with:'
           puts "  fp --profile #{name} projects"
@@ -65,11 +73,23 @@ module Fp
             puts '  fp profile add <name> --api-key fp_...'
           end
         else
-          output.success({ profiles: profiles }) do
+          raw = Config.load_profiles
+          detailed = profiles.map do |name|
+            p = raw[name] || {}
+            url = p['api_url'] || Config.get_setting('api_url') || Config::DEFAULT_API_URL
+            env = p['environment'] || Config.environment_for(url)
+            { name: name, environment: env, api_url: url }
+          end
+
+          output.success({ profiles: detailed }) do
             puts 'Configured profiles:'
-            profiles.each { |name| puts "  - #{name}" }
+            detailed.each do |d|
+              tag = d[:environment] ? " (#{d[:environment]})" : ''
+              puts "  - #{d[:name]}#{tag}"
+            end
             puts
             puts 'Note: API keys are never displayed. Use --profile <name> to select.'
+            puts 'Run `fp whoami` to see the fully resolved configuration.'
           end
         end
       end
@@ -78,7 +98,8 @@ module Fp
         output.error('Usage: fp profile <add|list>')
         puts
         puts 'Commands:'
-        puts '  fp profile add <name> --api-key fp_...  Add a named profile'
+        puts '  fp profile add <name> --api-key fp_... [--api-url URL] [--environment ENV]'
+        puts '                                          Add a named profile'
         puts '  fp profile list                         List configured profiles'
         exit 1
       end

data/lib/fp/commands/propose.rb

@@ -13,10 +13,14 @@ module Fp
         required: :string,
         acceptance: :string,
         parent: :string,
-        category: :string
+        category: :string,
+        source_type: :string,
+        source_url: :string,
+        source_context: :string
       }.freeze
 
       VALID_CATEGORIES = %w[functional non-functional ux performance security compliance].freeze
+      VALID_SOURCE_TYPES = %w[fizzy discord github_issue jira notion manual ai_chat].freeze
 
       def run(args)
         opts, = parse_flags(args, KNOWN_FLAGS)
@@ -31,6 +35,11 @@ module Fp
           exit 1
         end
 
+        if opts[:source_type] && !VALID_SOURCE_TYPES.include?(opts[:source_type])
+          output.error("Invalid source type '#{opts[:source_type]}'. Must be one of: #{VALID_SOURCE_TYPES.join(', ')}")
+          exit 1
+        end
+
         project_id = resolve_project_id(opts[:project])
 
         # Parse required surfaces (comma-separated)
@@ -49,6 +58,9 @@ module Fp
         params[:why] = opts[:why] if opts[:why]
         params[:acceptance] = opts[:acceptance] if opts[:acceptance]
         params[:category] = opts[:category] if opts[:category]
+        params[:source_type] = opts[:source_type] if opts[:source_type]
+        params[:source_url] = opts[:source_url] if opts[:source_url]
+        params[:source_context] = opts[:source_context] if opts[:source_context]
 
         # Resolve parent slug to parent_id if provided
         if opts[:parent]

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,7 +64,7 @@ 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'
 
@@ -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]}...")
@@ -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

@@ -25,21 +25,49 @@ module Fp
 
         requirement = result[:data]['requirement']
 
-        output.success(result[:data]) do
-          print_requirement(requirement)
+        # Evidence is not embedded in the requirement payload — it lives on the project's
+        # evidence collection, keyed by slug. Fetch it, or `fp show` reports "(none)" for
+        # every requirement no matter how many receipts have been filed.
+        evidence = fetch_evidence(project_id, slug)
+
+        # Agents only ever speak slugs, so translate the parent's ID back into one.
+        parent_slug = resolve_parent_slug(project_id, requirement['parent_id'])
+
+        payload = result[:data].merge('evidence' => evidence)
+        payload['parent_slug'] = parent_slug if parent_slug
+
+        output.success(payload) do
+          print_requirement(requirement, evidence: evidence, parent_slug: parent_slug)
         end
       end
 
       private
 
-      def print_requirement(req)
+      def fetch_evidence(project_id, slug)
+        result = client.list_evidence(project_id, slug: slug)
+        return [] unless result[:ok]
+
+        result[:data]['evidence'] || []
+      end
+
+      def resolve_parent_slug(project_id, parent_id)
+        return nil if parent_id.nil? || parent_id.to_s.empty?
+
+        result = client.list_requirements(project_id: project_id)
+        return nil unless result[:ok]
+
+        parent = (result[:data]['requirements'] || []).find { |r| r['id'] == parent_id }
+        parent && parent['slug']
+      end
+
+      def print_requirement(req, evidence: [], parent_slug: nil)
         puts "#{req['title']}"
         puts "=" * req['title'].length
         puts
         puts "Slug:     #{req['slug']}"
         puts "Status:   #{req['status']}"
         puts "Category: #{req['category'] || '(none)'}"
-        puts "Parent:   #{req['parent_id'] || '(none)'}"
+        puts "Parent:   #{parent_slug || req['parent_id'] || '(none)'}"
         puts
 
         surfaces = req['required_surfaces'] || []
@@ -63,26 +91,31 @@ module Fp
           puts
         end
 
-        # Evidence receipts (will be populated when Evidence model exists)
-        evidence = req['evidence'] || []
-        if evidence.any?
-          puts 'Evidence:'
-          evidence.each do |e|
-            puts "  #{e['surface']}:"
-            puts "    Status:  #{e['status']}"
-            puts "    File:    #{e['file']}" if e['file']
-            puts "    Repo:    #{e['repo']}" if e['repo']
-            puts "    PR:      #{e['pr_url']}" if e['pr_url']
-            puts "    Work:    #{e['work_item_url']}" if e['work_item_url']
-            puts "    CI:      #{e['ci_url']}" if e['ci_url']
-            puts "    Title:   #{e['example_title']}" if e['example_title']
-            puts "    By:      #{e['reported_by']}" if e['reported_by']
-            puts
-          end
-        else
-          puts 'Evidence:'
+        # Evidence receipts, newest first, grouped per surface.
+        puts 'Evidence:'
+        if evidence.empty?
           puts '  (none reported)'
           puts
+        else
+          evidence
+            .sort_by { |e| e['reported_at'].to_s }
+            .reverse
+            .group_by { |e| e['surface'] }
+            .each do |surface, records|
+              puts "  #{surface}:"
+              records.each do |e|
+                puts "    Status:  #{e['status']}"
+                puts "    File:    #{e['source_file']}" if e['source_file']
+                puts "    Repo:    #{e['repo']}" if e['repo']
+                puts "    PR:      #{e['pr_url']}" if e['pr_url']
+                puts "    Work:    #{e['work_item_url']}" if e['work_item_url']
+                puts "    CI:      #{e['ci_url']}" if e['ci_url']
+                puts "    Title:   #{e['example_title']}" if e['example_title']
+                puts "    By:      #{e['source']}" if e['source']
+                puts "    At:      #{e['reported_at']}" if e['reported_at']
+                puts
+              end
+            end
         end
 
         puts "Created:  #{req['created_at']}"

data/lib/fp/commands/surfaces.rb

@@ -2,9 +2,38 @@
 
 module Fp
   module Commands
-    # fp surfaces --project <slug> - list available surfaces for a project
+    # fp surfaces --project <slug>              - list available surfaces for a project
+    # fp surfaces add <key> --project <slug>    - create a surface
+    #
+    # `add` exists because a requirement can only name surfaces that already exist, so an
+    # agent onboarding a project it hasn't seen before would otherwise be blocked waiting
+    # on a human to click through the web app.
     class Surfaces < Base
+      ADD_FLAGS = {
+        project: :string,
+        name: :string,
+        kind: :string,
+        audience: :string,
+        repo: :string,
+        default_branch: :string
+      }.freeze
+
+      VALID_KINDS = %w[api web android ios other].freeze
+      VALID_AUDIENCES = %w[customer ops both internal].freeze
+
       def run(args)
+        # Subcommand dispatch. Bare `fp surfaces --project X` stays a list, so existing
+        # callers (and the docs) keep working.
+        if args.first == 'add'
+          add(args[1..])
+        else
+          list(args)
+        end
+      end
+
+      private
+
+      def list(args)
         opts, = parse_flags(args)
         require_flag(opts, :project)
 
@@ -22,13 +51,63 @@ module Fp
         output.success({ surfaces: surfaces, project: opts[:project] }) do
           if surfaces.empty?
             puts "No surfaces configured for project '#{opts[:project]}'."
-            puts 'Configure surfaces in the web app.'
+            puts "Add one with: fp surfaces add <key> --project #{opts[:project]} --name \"<Name>\""
           else
             puts "Surfaces for '#{opts[:project]}':"
             surfaces.each { |s| puts "  - #{s}" }
           end
         end
       end
+
+      def add(args)
+        opts, positional = parse_flags(args, ADD_FLAGS)
+        require_flag(opts, :project)
+
+        key = positional.first
+        if key.nil? || key.strip.empty?
+          output.error('Usage: fp surfaces add <key> --project <slug> [--name "Name"] [--kind api|web|android|ios|other]')
+          exit 1
+        end
+
+        validate_choice!(opts[:kind], VALID_KINDS, '--kind')
+        validate_choice!(opts[:audience], VALID_AUDIENCES, '--audience')
+
+        project_id = resolve_project_id(opts[:project])
+
+        # The API derives key from name and defaults kind/audience/default_branch, but we
+        # send the key explicitly because here the key is what the caller actually typed —
+        # `add api --name "Backend API"` must produce `api`, not `backend_api`.
+        params = { key: key, name: opts[:name] || key }
+        params[:kind] = opts[:kind] if opts[:kind]
+        params[:audience] = opts[:audience] if opts[:audience]
+        params[:repo] = opts[:repo] if opts[:repo]
+        params[:default_branch] = opts[:default_branch] if opts[:default_branch]
+
+        result = client.create_surface(project_id, params)
+
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        surface = result[:data]['surface'] || {}
+
+        output.success(result[:data]) do
+          puts "Created surface '#{surface['key'] || key}' in project '#{opts[:project]}'."
+          puts
+          puts "  Name:     #{surface['name']}"
+          puts "  Kind:     #{surface['kind']}"
+          puts "  Audience: #{surface['audience']}"
+          puts "  Repo:     #{surface['repo'] || '(none)'}"
+        end
+      end
+
+      def validate_choice!(value, allowed, flag)
+        return if value.nil? || allowed.include?(value)
+
+        output.error("Invalid #{flag} '#{value}'. Must be one of: #{allowed.join(', ')}")
+        exit 1
+      end
     end
   end
 end

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

@@ -12,6 +12,7 @@ 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'
 

data/lib/fp/config.rb

@@ -2,6 +2,7 @@
 
 require 'yaml'
 require 'fileutils'
+require 'uri'
 
 module Fp
   # Handles configuration: profiles, API keys, API URL.
@@ -29,9 +30,12 @@ module Fp
 
     attr_reader :api_key, :api_url, :profile_name
 
+    # Where a resolved value came from, for `fp whoami` transparency.
+    attr_reader :api_key_source, :api_url_source, :profile_source
+
     def initialize(profile: nil, api_url: nil)
-      @profile_name = resolve_profile_name(profile)
       @explicit_api_url = api_url
+      @profile_name = resolve_profile_name(profile)
       @api_key = resolve_api_key
       @api_url = resolve_api_url
     end
@@ -40,6 +44,56 @@ module Fp
       !@api_key.nil? && !@api_key.empty?
     end
 
+    # The API URL passed via the global --api-url flag, if any (nil otherwise).
+    # `profile add` / `setup` use this so `fp profile add x --api-url URL` still
+    # records URL even though the global parser consumes the flag first.
+    def explicit_api_url
+      return nil if @explicit_api_url.nil? || @explicit_api_url.empty?
+
+      @explicit_api_url
+    end
+
+    # Short, human-readable environment label derived from the API host, e.g.
+    #   https://api.dev.featureparity.dev      -> "dev"
+    #   https://api.staging.featureparity.dev  -> "staging"
+    #   https://api.featureparity.dev          -> "production"
+    #   http://localhost:9292                  -> "local"
+    # This is what "tags" a profile/key to an environment: the API URL it targets.
+    def environment
+      self.class.environment_for(@api_url)
+    end
+
+    # The environment explicitly recorded on the active profile, if any.
+    # Falls back to nil when unset (callers derive from api_url instead).
+    def profile_environment
+      return nil unless @profile_name
+
+      profile = self.class.load_profiles[@profile_name]
+      profile && profile['environment']
+    end
+
+    # Masked hint for display — never reveal the full key.
+    def masked_api_key
+      self.class.mask_key(@api_key)
+    end
+
+    # Full resolved snapshot for `fp whoami` (safe to print / JSON-encode).
+    def resolved
+      {
+        profile: @profile_name,
+        profile_source: @profile_source,
+        api_url: @api_url,
+        api_url_source: @api_url_source,
+        environment: environment,
+        profile_environment: profile_environment,
+        authenticated: valid?,
+        api_key_present: valid?,
+        api_key_hint: masked_api_key,
+        api_key_source: @api_key_source,
+        config_file: self.class::CONFIG_FILE
+      }
+    end
+
     def validation_error
       return nil if valid?
 
@@ -64,7 +118,7 @@ module Fp
         config['profiles'] || {}
       end
 
-      def save_profile(name, api_key:, api_url: nil)
+      def save_profile(name, api_key:, api_url: nil, environment: nil)
         FileUtils.mkdir_p(CONFIG_DIR)
         ensure_config_file!
 
@@ -72,6 +126,10 @@ module Fp
         config['profiles'] ||= {}
         config['profiles'][name] = { 'api_key' => api_key }
         config['profiles'][name]['api_url'] = api_url if api_url
+        # Tag the key/profile with the environment it targets. If not given
+        # explicitly, derive it from the api_url so keys are always tagged.
+        env = environment || environment_for(api_url || get_setting('api_url') || DEFAULT_API_URL)
+        config['profiles'][name]['environment'] = env if env
 
         write_config!(config)
       end
@@ -82,6 +140,67 @@ module Fp
         config[key.to_s]
       end
 
+      # Derive a short environment label from an API URL's host. This mirrors
+      # the Belt DNS convention (see infrastructure/modules/app/dns.tf), which is
+      # what actually "tags" a profile/key to an environment: the API host tells
+      # you which FeatureParity environment the key talks to.
+      #
+      # Standalone environments use a dotted "api." prefix:
+      #   api.featureparity.dev          -> "production"
+      #   api.dev.featureparity.dev      -> "dev"
+      #   api.staging.featureparity.dev  -> "staging"
+      #
+      # Nested / ephemeral (per-branch) environments use a dashed "api-" prefix,
+      # because SSL wildcards are single-level (*.dev.featureparity.dev covers
+      # api-<env>.dev.featureparity.dev but not api.<env>.dev.featureparity.dev).
+      # The env slug is everything after "api-" up to the first dot, and may
+      # itself contain dashes:
+      #   api-abc-1234.dev.featureparity.dev  -> "abc-1234"
+      #   api-fizzy123.dev.featureparity.dev  -> "fizzy123"
+      #
+      # Anything local:
+      #   localhost / 127.0.0.1 / 0.0.0.0     -> "local"
+      def environment_for(url)
+        return nil if url.nil? || url.to_s.empty?
+
+        host = begin
+          URI.parse(url.to_s).host
+        rescue URI::InvalidURIError
+          nil
+        end
+        return nil if host.nil? || host.empty?
+
+        return 'local' if host == 'localhost' || host.start_with?('127.') || host == '0.0.0.0'
+
+        first, *rest = host.split('.')
+
+        # Nested/ephemeral: "api-<env>" where <env> may contain dashes.
+        return first.sub(/\Aapi-/, '') if first.start_with?('api-')
+
+        # Standalone dotted "api." prefix: the env is the next label.
+        if first == 'api'
+          # api.featureparity.dev -> ["featureparity", "dev"] -> production
+          return 'production' if rest.length <= 2
+
+          return rest.first
+        end
+
+        # No recognizable "api" prefix — best effort: treat a bare apex
+        # (two labels, e.g. featureparity.dev) as production, else the left label.
+        return 'production' if rest.length <= 1
+
+        first
+      end
+
+      # Mask an API key for display: keep a short prefix + last 4 chars.
+      #   fp_abcdefgh1234 -> fp_…1234
+      def mask_key(key)
+        return nil if key.nil? || key.empty?
+        return '****' if key.length <= 8
+
+        "#{key[0, 3]}…#{key[-4..]}"
+      end
+
       # Set a global setting (top-level key in config.yml)
       def set_setting(key, value)
         FileUtils.mkdir_p(CONFIG_DIR)
@@ -190,50 +309,84 @@ module Fp
 
     def resolve_profile_name(explicit_profile)
       # 1. Explicit --profile flag  2. FP_PROFILE env var
-      name = explicit_profile || ENV['FP_PROFILE']
-      return name if name && !name.empty?
+      if explicit_profile && !explicit_profile.empty?
+        @profile_source = 'flag'
+        return explicit_profile
+      end
+
+      if ENV['FP_PROFILE'] && !ENV['FP_PROFILE'].empty?
+        @profile_source = 'env (FP_PROFILE)'
+        return ENV['FP_PROFILE']
+      end
 
       # 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)
+      if self.class.profile_exists?(DEFAULT_PROFILE_NAME)
+        @profile_source = 'default profile'
+        return DEFAULT_PROFILE_NAME
+      end
 
+      @profile_source = 'none'
       nil
     end
 
     def resolve_api_key
       # FP_API_KEY env var always wins
-      return ENV['FP_API_KEY'] if ENV['FP_API_KEY'] && !ENV['FP_API_KEY'].empty?
+      if ENV['FP_API_KEY'] && !ENV['FP_API_KEY'].empty?
+        @api_key_source = 'env (FP_API_KEY)'
+        return ENV['FP_API_KEY']
+      end
 
       # Otherwise, use profile if specified
-      return nil unless @profile_name
+      unless @profile_name
+        @api_key_source = 'none'
+        return nil
+      end
 
       profiles = self.class.load_profiles
       profile = profiles[@profile_name]
-      return nil unless profile
+      unless profile
+        @api_key_source = 'none'
+        return nil
+      end
 
+      @api_key_source = "profile (#{@profile_name})"
       profile['api_key']
     end
 
     def resolve_api_url
       # 1. Explicit --api-url flag
-      return @explicit_api_url if @explicit_api_url && !@explicit_api_url.empty?
+      if @explicit_api_url && !@explicit_api_url.empty?
+        @api_url_source = 'flag'
+        return @explicit_api_url
+      end
 
       # 2. FP_API_URL env var
-      return ENV['FP_API_URL'] if ENV['FP_API_URL'] && !ENV['FP_API_URL'].empty?
+      if ENV['FP_API_URL'] && !ENV['FP_API_URL'].empty?
+        @api_url_source = 'env (FP_API_URL)'
+        return ENV['FP_API_URL']
+      end
 
       # 3. Profile-specific URL
       if @profile_name
         profiles = self.class.load_profiles
         profile = profiles[@profile_name]
-        return profile['api_url'] if profile && profile['api_url']
+        if profile && profile['api_url']
+          @api_url_source = "profile (#{@profile_name})"
+          return profile['api_url']
+        end
       end
 
       # 4. Global api_url setting
       global_url = self.class.get_setting('api_url')
-      return global_url if global_url && !global_url.empty?
+      if global_url && !global_url.empty?
+        @api_url_source = 'global setting'
+        return global_url
+      end
 
       # 5. Default
+      @api_url_source = 'default'
       DEFAULT_API_URL
     end
   end

data/lib/fp/junit.rb

@@ -34,6 +34,16 @@ module Fp
     # (matching the propose/report convention).
     MARKER_RE = /fp:([a-z0-9][a-z0-9_-]*)(?:@([a-z0-9_-]+(?:,[a-z0-9_-]+)*))?/.freeze
 
+    # A marker only counts when it is a comment on its own line — the documented
+    # convention ("the fp:<slug> comment sits immediately above its test"). Requiring a
+    # line-leading comment token is what keeps marker-shaped text inside string literals,
+    # fixtures and docs from being mistaken for a real annotation. Without it, any test
+    # suite that has tests *about* fp markers reports evidence for its own fixtures.
+    #
+    # Covers #, //, --, and both the opening and continuation lines of /* ... */ blocks,
+    # which spans every language the marker convention documents.
+    COMMENT_LINE_RE = %r{\A\s*(?:\#|//|--|/\*|\*)}.freeze
+
     module_function
 
     # Parse a JUnit XML file into an array of TestCase structs.
@@ -52,10 +62,14 @@ module Fp
       cases = []
 
       doc.each_element('//testcase') do |el|
+        parent = el.parent
+        suite_name = parent && parent.expanded_name == 'testsuite' ? parent.attributes['name'] : nil
+        classname = el.attributes['classname']
+
         cases << TestCase.new(
           name: el.attributes['name'],
-          classname: el.attributes['classname'],
-          file: el.attributes['file'],
+          classname: classname,
+          file: resolve_file(el.attributes['file'], classname, suite_name),
           line: (el.attributes['line'] && el.attributes['line'].to_i),
           status: testcase_status(el)
         )
@@ -64,6 +78,26 @@ module Fp
       cases
     end
 
+    # Runners disagree about where the source file goes. Minitest- and RSpec-style reports
+    # put it on the testcase's `file` attribute; vitest and jest omit `file` entirely and
+    # carry the path in `classname` and the enclosing `<testsuite name>`. Markers live in
+    # the file, so fall back through the alternatives instead of silently finding nothing.
+    def resolve_file(file, classname, suite_name)
+      return file if file && !file.empty?
+
+      [classname, suite_name].find { |candidate| path_like?(candidate) }
+    end
+
+    # Distinguish a source path from a bare test-class name. Deliberately conservative:
+    # a Java-style `com.example.FooTest` classname must not be mistaken for a file.
+    TEST_FILE_EXT_RE = /\.(rb|js|jsx|mjs|cjs|ts|tsx|kt|kts|swift|java|py|go|cs|php|rs|scala)\z/.freeze
+
+    def path_like?(value)
+      return false if value.nil? || value.empty?
+
+      value.include?('/') || value.match?(TEST_FILE_EXT_RE)
+    end
+
     # Determine present/skipped for a testcase element.
     # Failures/errors still count as "present" for agent evidence — the test
     # exists and was executed. Only skipped/pending tests become stubs.
@@ -113,6 +147,12 @@ module Fp
         markers = markers_for(cases.first, base_dir, marker_cache)
         next if markers.empty?
 
+        # A title is only trustworthy when we know which test the marker annotates: either
+        # the report carried line numbers, or the file holds a single test. Otherwise the
+        # marker was matched file-wide and naming any one test would be a guess — vitest
+        # and jest emit no line numbers, so this is the common case, not an edge one.
+        titles_reliable = cases.any?(&:line) || cases.length == 1
+
         cases.each do |tc|
           marker = marker_for(tc, cases, markers)
           next unless marker
@@ -126,7 +166,7 @@ module Fp
             if surface.nil? || surface.empty?
               missing_surface << { slug: marker[:slug], file: tc.file }
             else
-              record_binding(bindings, marker[:slug], surface, tc)
+              record_binding(bindings, marker[:slug], surface, tc, titles_reliable: titles_reliable)
             end
           end
         end
@@ -163,7 +203,7 @@ module Fp
       candidate
     end
 
-    def record_binding(bindings, slug, surface, testcase)
+    def record_binding(bindings, slug, surface, testcase, titles_reliable: true)
       rel_file = testcase.file
       key = [slug, surface, rel_file]
       state = testcase.stub? ? 'stub' : 'present'
@@ -173,7 +213,7 @@ module Fp
       return if existing && !(existing.state == 'stub' && state == 'present')
 
       bindings[key] = Binding.new(slug: slug, surface: surface, file: rel_file,
-                                  title: testcase.name, state: state)
+                                  title: (testcase.name if titles_reliable), state: state)
     end
 
     # Load and cache the fp:<slug> markers (with line numbers) for a testcase's
@@ -198,9 +238,13 @@ module Fp
     # Scan file contents for fp:<slug>[@surface[,surface...]] markers, returning
     # [{ slug:, surfaces: [..], line: }, ...] (1-based line numbers).
     # `surfaces` is [] when the marker pins none (use the default surface).
+    #
+    # Only comment lines are considered — see COMMENT_LINE_RE.
     def scan_markers(contents)
       markers = []
       contents.each_line.with_index(1) do |line, num|
+        next unless line.match?(COMMENT_LINE_RE)
+
         line.scan(MARKER_RE) do |(slug, surface_list)|
           surfaces = surface_list ? surface_list.split(',').map(&:strip).reject(&:empty?) : []
           markers << { slug: slug, surfaces: surfaces, line: num }

data/lib/fp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fp
-  VERSION = '0.0.3'
+  VERSION = '0.0.5'
 end

data/skills/fp/references/cli.md

@@ -159,15 +159,26 @@ fp matrix --project stowzilla --json    # JSON
 
 ### fp profile
 
-Manage named profiles.
+Manage named profiles. Each profile stores an API key and (optionally) the
+API URL and environment it targets, so a key is always tagged with the
+environment it talks to.
 
 ```bash
 fp profile list
-fp profile add staging --api-key fp_...
-fp profile remove staging
-fp profile show staging
+fp profile add staging --api-key fp_... --api-url https://api.staging.featureparity.dev
+fp profile add staging --api-key fp_... --environment staging
 ```
 
+If `--environment` is omitted it is derived from the API URL's host, following
+the Belt DNS convention (`infrastructure/modules/app/dns.tf`):
+
+- `api.featureparity.dev` → `production`
+- `api.staging.featureparity.dev` → `staging`
+- `api-abc-1234.dev.featureparity.dev` → `abc-1234` (nested/ephemeral env; `api-` prefix)
+- `localhost` / `127.0.0.1` → `local`
+
+`fp profile list` shows the tag.
+
 ### fp config
 
 Manage global settings.
@@ -177,6 +188,21 @@ fp config list
 fp config get api_url
 fp config set api_url https://api.dev.featureparity.dev
 fp config unset api_url
+fp config whoami                 # alias of `fp whoami`
+```
+
+### fp whoami
+
+Show the *resolved* configuration this invocation would use — the active
+profile, the environment, the API URL (and where each value came from), and
+whether an API key is present (masked, never the full token). Makes no API
+calls, so it works even without a valid key.
+
+```bash
+fp whoami
+fp whoami --json
+fp --profile staging whoami       # inspect a specific profile
+fp --api-url http://localhost:9292 whoami
 ```
 
 ### fp repos

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: featureparity
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.5
 platform: ruby
 authors:
 - Stowzilla
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-04 00:00:00.000000000 Z
+date: 2026-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http
@@ -108,6 +108,7 @@ files:
 - lib/fp/commands/show.rb
 - lib/fp/commands/surfaces.rb
 - lib/fp/commands/version.rb
+- lib/fp/commands/whoami.rb
 - lib/fp/config.rb
 - lib/fp/junit.rb
 - lib/fp/output.rb