featureparity 0.0.1 → 0.0.3

data/lib/fp/commands/propose.rb

@@ -2,7 +2,7 @@
 
 module Fp
   module Commands
-    # fp propose --project <slug> --slug X --name "..." --why "..." --required a,b,c --acceptance "..."
+    # fp propose --project <slug> --slug X --name "..." --why "..." --required a,b,c --acceptance "..." --parent <slug> --category <cat>
     # Create a new requirement as draft
     class Propose < Base
       KNOWN_FLAGS = {
@@ -11,9 +11,13 @@ module Fp
         name: :string,
         why: :string,
         required: :string,
-        acceptance: :string
+        acceptance: :string,
+        parent: :string,
+        category: :string
       }.freeze
 
+      VALID_CATEGORIES = %w[functional non-functional ux performance security compliance].freeze
+
       def run(args)
         opts, = parse_flags(args, KNOWN_FLAGS)
 
@@ -21,7 +25,13 @@ module Fp
         require_flag(opts, :slug, '--slug is required (immutable identifier for the requirement)')
         require_flag(opts, :name, '--name is required (human-readable title)')
 
-        workspace_id = resolve_workspace_id(opts[:project])
+        # Validate category client-side for better UX (fail fast with helpful message)
+        if opts[:category] && !VALID_CATEGORIES.include?(opts[:category])
+          output.error("Invalid category '#{opts[:category]}'. Must be one of: #{VALID_CATEGORIES.join(', ')}")
+          exit 1
+        end
+
+        project_id = resolve_project_id(opts[:project])
 
         # Parse required surfaces (comma-separated)
         required_surfaces = if opts[:required]
@@ -33,11 +43,19 @@ module Fp
         params = {
           slug: opts[:slug],
           title: opts[:name],
-          workspace_id: workspace_id,
+          project_id: project_id,
           required_surfaces: required_surfaces
         }
         params[:why] = opts[:why] if opts[:why]
         params[:acceptance] = opts[:acceptance] if opts[:acceptance]
+        params[:category] = opts[:category] if opts[:category]
+
+        # Resolve parent slug to parent_id if provided
+        if opts[:parent]
+          parent_id = resolve_parent_id(project_id, opts[:parent])
+          params[:parent_id] = parent_id
+        end
+
         # Note: status is NOT sent - the API enforces draft for agents
 
         result = client.create_requirement(params)
@@ -54,13 +72,36 @@ module Fp
           puts
           puts "  Title:    #{requirement['title']}"
           puts "  Status:   #{requirement['status']}"
+          puts "  Category: #{requirement['category'] || '(none)'}"
           puts "  Surfaces: #{(requirement['required_surfaces'] || []).join(', ')}"
+          puts "  Parent:   #{opts[:parent] || '(none)'}" if opts[:parent]
           puts
           puts '⚠️  This requirement is a DRAFT.'
           puts '   A human must activate it in the web app before it appears in the parity matrix.'
           puts '   Agents cannot activate requirements.'
         end
       end
+
+      private
+
+      # Resolve a parent requirement slug to its ID
+      def resolve_parent_id(project_id, parent_slug)
+        result = client.list_requirements(project_id: project_id)
+        unless result[:ok]
+          output.error("Failed to resolve parent slug '#{parent_slug}': #{result[:error]}")
+          exit 1
+        end
+
+        requirements = result[:data]['requirements'] || []
+        parent = requirements.find { |r| r['slug'] == parent_slug }
+
+        unless parent
+          output.error("Parent requirement '#{parent_slug}' not found in this project")
+          exit 1
+        end
+
+        parent['id']
+      end
     end
   end
 end

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

@@ -22,13 +22,16 @@ module Fp
 
         api_key = resolve_api_key(opts)
         profile_name = resolve_profile_name(opts)
-        api_url = opts[:api_url]
+        api_url = opts[:api_url] || Config.get_setting('api_url')
 
         puts "Validating API key..."
         validate_key!(api_key, api_url)
 
         save_profile!(profile_name, api_key, api_url)
 
+        effective_url = api_url || Config::DEFAULT_API_URL
+        domain = URI.parse(effective_url).host.sub(/^api\./, '') rescue 'featureparity.dev'
+
         puts
         puts "✅ Setup complete!"
         puts
@@ -54,8 +57,12 @@ module Fp
           exit 1
         end
 
-        puts "Get your API key from: https://featureparity.dev"
-        puts "(Workspace Settings → API Keys → Mint Key)"
+        api_url = opts[: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 "(Project Settings → API Keys → Mint Key)"
         puts
         print "Paste your API key (starts with fp_): "
         $stdout.flush
@@ -100,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,8 @@ module Fp
         puts
         puts "Slug:     #{req['slug']}"
         puts "Status:   #{req['status']}"
+        puts "Category: #{req['category'] || '(none)'}"
+        puts "Parent:   #{req['parent_id'] || '(none)'}"
         puts
 
         surfaces = req['required_surfaces'] || []

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

@@ -9,6 +9,8 @@ require_relative 'commands/propose'
 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'