featureparity 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 695b5f522e34a1e886e07177cbbe5ca87b515caf6845e15b50ca9e1c4fb3735e
-  data.tar.gz: 18ff57dfb177341dd4a6f2d8dc05e862a53d8e24eb0c2da4172e022986533cc1
+  metadata.gz: 166fe16ad8636be840cc889d1104ad4e6a5f3c84cd046f0a94f291412083f344
+  data.tar.gz: e88add572a4cfd638768ae4d65de5a207b6a64c450ca0fdce426f48e8e51427e
 SHA512:
-  metadata.gz: 9851ef3ea41669276c356fbe2e5a200ec06d59cea82a9d852eaca71a20297319b4eeb32e5a684921cfba3b298bf1e8931f45bc89ad0c59d802128a5f5940b157
-  data.tar.gz: 1e075a99c1b02368908639649ff45ba78be33f8e0a03756b0f7782275758f326e01992488508c6930d1f5ac65e47eb6ef7b5e24438482e6eac2b855fe06b2557
+  metadata.gz: c3d5bee44367c02c8329c10bdb3c0615978c405c30d46fb002b1ca7fe6676a61075dc83bf4ba02ba01faf828d80fa7f56af2116fd5287f662166bf547d9c5468
+  data.tar.gz: 5b627165e1205cca331626fd46b35d7ad71b9ed666fd63ebe96569b2e2989b4b14ff35426d099a1e7dfd8afe7ac16c7984e53ec1052262a374914505c950404c

data/lib/fp/cli.rb

@@ -12,6 +12,8 @@ module Fp
       'report' => Commands::Report,
       'matrix' => Commands::Matrix,
       'profile' => Commands::Profile,
+      'config' => Commands::ConfigCmd,
+      'repos' => Commands::Repos,
       'setup' => Commands::Setup,
       'version' => Commands::Version,
       'help' => Commands::Help
@@ -32,17 +34,19 @@ module Fp
           exit 1
         end
 
-        # Profile commands don't need auth
-        needs_auth = !%w[profile setup version help].include?(command_name)
+        # Profile/config commands don't need auth
+        needs_auth = !%w[profile config repos setup version help].include?(command_name)
 
         if needs_auth
-          config = Config.new(profile: global_opts[:profile])
+          config = Config.new(profile: global_opts[:profile], api_url: global_opts[:api_url])
           unless config.valid?
             output = Output.new(json: global_opts[:json])
             output.error(config.validation_error.strip)
             exit 1
           end
           client = Client.new(config)
+        else
+          config = Config.new(profile: global_opts[:profile], api_url: global_opts[:api_url])
         end
 
         output = Output.new(json: global_opts[:json])
@@ -60,7 +64,7 @@ module Fp
       private
 
       def extract_global_options(args)
-        opts = { json: false, profile: nil }
+        opts = { json: false, profile: nil, api_url: nil }
 
         # Extract --json flag
         if args.delete('--json')
@@ -89,6 +93,17 @@ module Fp
           opts[:profile] = args.delete_at(idx)
         end
 
+        # Extract --api-url flag
+        if (idx = args.index('--api-url'))
+          args.delete_at(idx)
+          value = args[idx]
+          if value.nil? || value.start_with?('-')
+            $stderr.puts "Error: --api-url requires a value"
+            exit 1
+          end
+          opts[:api_url] = args.delete_at(idx)
+        end
+
         opts
       end
     end

data/lib/fp/client.rb

@@ -12,21 +12,27 @@ module Fp
       @base_url = config.api_url.chomp('/')
     end
 
-    # GET /workspaces (called "projects" in the CLI)
+    # GET /projects
     def list_projects
-      get('/api/workspaces')
+      get('/api/projects')
     end
 
-    # GET /workspaces/:id
+    # GET /projects/:id
     def get_project(id)
-      get("/api/workspaces/#{id}")
+      get("/api/projects/#{id}")
+    end
+
+    # GET /projects/:id/surfaces
+    def list_surfaces(project_id)
+      get("/api/projects/#{project_id}/surfaces")
     end
 
     # GET /requirements
-    def list_requirements(workspace_id: nil, status: nil)
+    def list_requirements(project_id: nil, status: nil, category: nil)
       params = {}
-      params[:workspace_id] = workspace_id if workspace_id
+      params[:project_id] = project_id if project_id
       params[:status] = status if status
+      params[:category] = category if category
       get('/api/requirements', params)
     end
 
@@ -35,10 +41,10 @@ module Fp
       get("/api/requirements/#{id}")
     end
 
-    # GET /requirements by slug within a workspace
-    def find_requirement_by_slug(workspace_id, slug)
-      # List all requirements for the workspace and find by slug
-      result = list_requirements(workspace_id: workspace_id)
+    # GET /requirements by slug within a project
+    def find_requirement_by_slug(project_id, slug)
+      # List all requirements for the project and find by slug
+      result = list_requirements(project_id: project_id)
       return result unless result[:ok]
 
       requirements = result[:data]['requirements'] || []
@@ -47,7 +53,7 @@ module Fp
       if requirement
         { ok: true, data: { 'requirement' => requirement } }
       else
-        { ok: false, error: "Requirement '#{slug}' not found in workspace", status: 404 }
+        { ok: false, error: "Requirement '#{slug}' not found in project", status: 404 }
       end
     end
 
@@ -61,20 +67,21 @@ module Fp
       put("/api/requirements/#{id}", params)
     end
 
-    # POST /evidence (when API is ready)
+    # POST /projects/:project_id/evidence (direct reporting)
     def report_evidence(params)
-      post('/api/evidence', params)
+      project_id = params.delete(:project_id)
+      post("/api/projects/#{project_id}/evidence", params)
     end
 
     # GET /matrix (when API is ready)
-    def get_matrix(workspace_id, format: :json)
+    def get_matrix(project_id, format: :json)
       path = format == :csv ? '/api/matrix.csv' : '/api/matrix'
-      get(path, { workspace_id: workspace_id })
+      get(path, { project_id: project_id })
     end
 
     # GET /gaps (when API is ready)
-    def get_gaps(workspace_id, surface: nil)
-      params = { workspace_id: workspace_id }
+    def get_gaps(project_id, surface: nil)
+      params = { project_id: project_id }
       params[:surface] = surface if surface
       get('/api/gaps', params)
     end

data/lib/fp/commands/base.rb

@@ -50,26 +50,26 @@ module Fp
         [opts, positional]
       end
 
-      # Resolve workspace ID from --project flag (can be slug or ID)
-      def resolve_workspace_id(project_slug_or_id)
+      # Resolve project ID from --project flag (can be slug or ID)
+      def resolve_project_id(project_slug_or_id)
         return nil unless project_slug_or_id
 
-        # First try to find by listing workspaces
+        # First try to find by listing projects
         result = client.list_projects
         unless result[:ok]
           output.error(result[:error], status: result[:status])
           exit 1
         end
 
-        workspaces = result[:data]['workspaces'] || []
-        workspace = workspaces.find { |w| w['slug'] == project_slug_or_id || w['id'] == project_slug_or_id }
+        projects = result[:data]['projects'] || []
+        project = projects.find { |w| w['slug'] == project_slug_or_id || w['id'] == project_slug_or_id }
 
-        unless workspace
+        unless project
           output.error("Project '#{project_slug_or_id}' not found")
           exit 1
         end
 
-        workspace['id']
+        project['id']
       end
 
       def require_flag(opts, flag, message = nil)

data/lib/fp/commands/config_cmd.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # fp config get|set|unset|list
+    # Manage global CLI settings (stored in ~/.config/fp/config.yml)
+    class ConfigCmd < Base
+      ALLOWED_SETTINGS = %w[api_url].freeze
+
+      def run(args)
+        subcommand = args.shift
+
+        case subcommand
+        when 'set'
+          set_setting(args)
+        when 'get'
+          get_setting(args)
+        when 'unset'
+          unset_setting(args)
+        when 'list'
+          list_settings
+        else
+          show_usage
+        end
+      end
+
+      private
+
+      def set_setting(args)
+        key = args.shift
+        value = args.shift
+
+        unless key
+          output.error('Usage: fp config set <key> <value>')
+          exit 1
+        end
+
+        unless ALLOWED_SETTINGS.include?(key)
+          output.error("Unknown setting: '#{key}'. Allowed: #{ALLOWED_SETTINGS.join(', ')}")
+          exit 1
+        end
+
+        unless value
+          output.error("Value is required. Usage: fp config set #{key} <value>")
+          exit 1
+        end
+
+        Config.set_setting(key, value)
+
+        output.success({ key: key, value: value }) do
+          puts "Set #{key} = #{value}"
+        end
+      end
+
+      def get_setting(args)
+        key = args.shift
+
+        unless key
+          output.error('Usage: fp config get <key>')
+          exit 1
+        end
+
+        value = Config.get_setting(key)
+
+        if value
+          output.success({ key: key, value: value }) do
+            puts value
+          end
+        else
+          output.success({ key: key, value: nil }) do
+            puts "(not set)"
+          end
+        end
+      end
+
+      def unset_setting(args)
+        key = args.shift
+
+        unless key
+          output.error('Usage: fp config unset <key>')
+          exit 1
+        end
+
+        Config.set_setting(key, nil)
+
+        output.success({ key: key }) do
+          puts "Unset #{key}"
+        end
+      end
+
+      def list_settings
+        settings = {}
+        ALLOWED_SETTINGS.each do |key|
+          value = Config.get_setting(key)
+          settings[key] = value if value
+        end
+
+        output.success({ settings: settings }) do
+          if settings.empty?
+            puts "No global settings configured."
+            puts
+            puts "Set one with:"
+            puts "  fp config set api_url https://api.dev.featureparity.dev"
+          else
+            puts "Global settings:"
+            settings.each { |k, v| puts "  #{k} = #{v}" }
+          end
+        end
+      end
+
+      def show_usage
+        output.error('Usage: fp config <set|get|unset|list>')
+        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
+        puts 'Available settings:'
+        puts '  api_url   Base URL for the FeatureParity API'
+        puts
+        puts 'Examples:'
+        puts '  fp config set api_url https://api.dev.featureparity.dev'
+        puts '  fp config get api_url'
+        exit 1
+      end
+    end
+  end
+end

data/lib/fp/commands/help.rb

@@ -18,8 +18,11 @@ module Fp
             show <slug> --project <slug>      Show requirement details
             propose --project <slug> ...      Propose a new requirement (as draft)
             report <slug> --project <slug>... Report evidence for a requirement
+            report --junit <file> ...         Upload evidence from a JUnit XML report (no CI)
             matrix --project <slug>           Show the parity matrix
             profile add|list                  Manage named profiles
+            config set|get|unset|list         Manage global settings
+            repos set|get|list|unset          Map surfaces to local repo paths
             setup                             Interactive first-time setup
             version                           Show version
             help                              Show this help
@@ -28,6 +31,7 @@ module Fp
             --json                            Output as JSON envelope
             --profile <name>                  Use a named profile
             -p <name>                         Alias for --profile
+            --api-url <url>                   Override API URL for this command
 
           AUTHENTICATION
             Set FP_API_KEY environment variable, or use a profile:
@@ -61,6 +65,9 @@ module Fp
             # List requirements for a project
             fp list --project stowzilla
 
+            # List requirements filtered by category
+            fp list --project stowzilla --category security
+
             # Show gaps (requirements without evidence)
             fp list --project stowzilla --gaps --surface customer_android
 
@@ -73,7 +80,8 @@ module Fp
               --name "Print QR code on container label" \\
               --why "Customers scan to track containers" \\
               --required api,customer_android,customer_ios \\
-              --acceptance "QR code is printed and scannable"
+              --acceptance "QR code is printed and scannable" \\
+              --category functional
 
             # Report evidence for a requirement
             fp report print_container_qr --project stowzilla \\
@@ -84,12 +92,31 @@ module Fp
               --work-item https://app.fizzy.do/123/cards/456 \\
               --title "prints a QR code onto the container label"
 
+            # Upload evidence without CI: run your suite, emit JUnit XML, upload it.
+            # fp parses the report, finds the fp:<slug> markers in the test files,
+            # and reports evidence for every requirement the suite covered.
+            #   rspec --format RspecJunitFormatter --out junit.xml   # (or your runner's equivalent)
+            fp report --junit junit.xml --project stowzilla \\
+              --surface api \\
+              --repo stowzilla/marketplace \\
+              --work-item https://app.fizzy.do/123/cards/456
+            # --base-dir sets where relative test file paths in the report resolve from
+            # Skipped tests are reported as 'stub'; everything else as 'present'.
+
             # Show the parity matrix
             fp matrix --project stowzilla
 
             # Export matrix as CSV
             fp matrix --project stowzilla --csv > matrix.csv
 
+            # Map a surface to a local repo on this machine
+            fp repos set customer_android ~/code/customer-android \\
+              --project stowzilla --repo stowzilla/customer-android
+
+            # Find where a surface's code lives locally (for agents)
+            fp repos get customer_android --project stowzilla
+            cd "$(fp repos get customer_android --project stowzilla)"
+
           MARKER CONVENTION
             Tests are bound to requirements using the fp:<slug> marker in the test file.
             The CLI does not rewrite test files - you add the marker yourself.
@@ -113,6 +140,18 @@ module Fp
                 ...
               }
 
+            PINNING SURFACES IN THE MARKER
+              A marker may target one or more surfaces with an @suffix. This is
+              handy when a single (e.g. backend) test satisfies several surfaces:
+
+                # fp:print_container_qr            -> uses the --surface flag
+                # fp:print_container_qr@api        -> reports for the api surface
+                # fp:print_container_qr@api,web    -> reports for api AND web
+
+              With `fp report --junit`, each pinned surface produces its own
+              evidence upload. Markers without an @surface fall back to --surface;
+              if a marker pins none and no --surface is given, the run errors.
+
           MORE INFORMATION
             https://featureparity.dev/docs
         HELP

data/lib/fp/commands/list.rb

@@ -2,12 +2,13 @@
 
 module Fp
   module Commands
-    # fp list --project <slug> [--surface X] [--gaps] [--status draft]
+    # fp list --project <slug> [--surface X] [--category Y] [--gaps] [--status draft]
     # List requirements, optionally filtered
     class List < Base
       KNOWN_FLAGS = {
         project: :string,
         surface: :string,
+        category: :string,
         status: :string,
         gaps: :boolean
       }.freeze
@@ -16,19 +17,19 @@ module Fp
         opts, = parse_flags(args, KNOWN_FLAGS)
         require_flag(opts, :project)
 
-        workspace_id = resolve_workspace_id(opts[:project])
+        project_id = resolve_project_id(opts[:project])
 
         if opts[:gaps]
-          list_gaps(workspace_id, opts)
+          list_gaps(project_id, opts)
         else
-          list_requirements(workspace_id, opts)
+          list_requirements(project_id, opts)
         end
       end
 
       private
 
-      def list_requirements(workspace_id, opts)
-        result = client.list_requirements(workspace_id: workspace_id)
+      def list_requirements(project_id, opts)
+        result = client.list_requirements(project_id: project_id, category: opts[:category])
 
         unless result[:ok]
           output.error(result[:error], status: result[:status])
@@ -50,22 +51,53 @@ module Fp
 
         output.success({ requirements: requirements, project: opts[:project] }) do
           if requirements.empty?
-            puts "No #{status_filter} requirements found."
+            filter_desc = [status_filter]
+            filter_desc << "category: #{opts[:category]}" if opts[:category]
+            filter_desc << "surface: #{opts[:surface]}" if opts[:surface]
+            puts "No requirements found (#{filter_desc.join(', ')})."
           else
-            headers = %w[SLUG TITLE SURFACES STATUS]
-            rows = requirements.map do |r|
+            # Group into tree structure: parents first, then children indented
+            parents = requirements.select { |r| r['parent_id'].nil? || r['parent_id'] == '' }
+            children_by_parent = requirements
+              .select { |r| r['parent_id'] && r['parent_id'] != '' }
+              .group_by { |r| r['parent_id'] }
+
+            # Orphaned children (parent not in filtered set) show at top level
+            parent_ids = parents.map { |p| p['id'] }.to_set
+            orphans = requirements.select { |r| r['parent_id'] && r['parent_id'] != '' && !parent_ids.include?(r['parent_id']) }
+
+            headers = %w[SLUG TITLE CATEGORY SURFACES STATUS]
+            rows = []
+
+            parents.each do |r|
               surfaces = (r['required_surfaces'] || []).join(', ')
-              [r['slug'], truncate(r['title'], 40), surfaces.empty? ? '-' : surfaces, r['status']]
+              category = r['category'] || '-'
+              rows << [r['slug'], truncate(r['title'], 40), category, surfaces.empty? ? '-' : surfaces, r['status']]
+
+              # Add children indented
+              (children_by_parent[r['id']] || []).each do |child|
+                child_surfaces = (child['required_surfaces'] || []).join(', ')
+                child_category = child['category'] || '-'
+                rows << ["  └ #{child['slug']}", truncate(child['title'], 36), child_category, child_surfaces.empty? ? '-' : child_surfaces, child['status']]
+              end
             end
+
+            # Show orphans at top level
+            orphans.each do |r|
+              surfaces = (r['required_surfaces'] || []).join(', ')
+              category = r['category'] || '-'
+              rows << [r['slug'], truncate(r['title'], 40), category, surfaces.empty? ? '-' : surfaces, r['status']]
+            end
+
             output.table(headers, rows)
           end
         end
       end
 
-      def list_gaps(workspace_id, opts)
+      def list_gaps(project_id, opts)
         # Gaps endpoint may not exist yet - fall back to computing from requirements
         # For now, list requirements that don't have evidence for a surface
-        result = client.list_requirements(workspace_id: workspace_id)
+        result = client.list_requirements(project_id: project_id, category: opts[:category])
 
         unless result[:ok]
           output.error(result[:error], status: result[:status])
@@ -84,15 +116,24 @@ module Fp
 
         # For now, gaps = all requirements (evidence API is #1214)
         # Once evidence API exists, filter to only those without evidence
-        output.success({ gaps: requirements, project: opts[:project], surface: opts[:surface] }) do
+        output.success({ gaps: requirements, project: opts[:project], surface: opts[:surface], category: opts[:category] }) do
           if requirements.empty?
-            puts 'No gaps found.'
+            filter_desc = []
+            filter_desc << "category: #{opts[:category]}" if opts[:category]
+            filter_desc << "surface: #{opts[:surface]}" if opts[:surface]
+            msg = 'No gaps found'
+            msg += " (#{filter_desc.join(', ')})" unless filter_desc.empty?
+            puts "#{msg}."
           else
-            puts "Gaps for project '#{opts[:project]}'" + (opts[:surface] ? " (surface: #{opts[:surface]})" : '') + ':'
-            headers = %w[SLUG TITLE SURFACES]
+            desc = "Gaps for project '#{opts[:project]}'"
+            desc += " (surface: #{opts[:surface]})" if opts[:surface]
+            desc += " (category: #{opts[:category]})" if opts[:category]
+            puts "#{desc}:"
+            headers = %w[SLUG TITLE CATEGORY SURFACES]
             rows = requirements.map do |r|
               surfaces = (r['required_surfaces'] || []).join(', ')
-              [r['slug'], truncate(r['title'], 40), surfaces]
+              category = r['category'] || '-'
+              [r['slug'], truncate(r['title'], 40), category, surfaces]
             end
             output.table(headers, rows)
           end

data/lib/fp/commands/matrix.rb

@@ -14,20 +14,19 @@ module Fp
         opts, = parse_flags(args, KNOWN_FLAGS)
         require_flag(opts, :project)
 
-        workspace_id = resolve_workspace_id(opts[:project])
+        project_id = resolve_project_id(opts[:project])
 
-        # Get workspace for surfaces
-        ws_result = client.get_project(workspace_id)
-        unless ws_result[:ok]
-          output.error(ws_result[:error], status: ws_result[:status])
+        # Get surfaces for the project
+        surfaces_result = client.list_surfaces(project_id)
+        unless surfaces_result[:ok]
+          output.error(surfaces_result[:error], status: surfaces_result[:status])
           exit 1
         end
 
-        workspace = ws_result[:data]['workspace']
-        surfaces = workspace['available_surfaces'] || []
+        surfaces = (surfaces_result[:data]['surfaces'] || []).map { |s| s['key'] }
 
         # Get active requirements
-        req_result = client.list_requirements(workspace_id: workspace_id)
+        req_result = client.list_requirements(project_id: project_id)
         unless req_result[:ok]
           output.error(req_result[:error], status: req_result[:status])
           exit 1
@@ -68,8 +67,6 @@ module Fp
             output.table(headers, rows)
             puts
             puts 'Legend: ✅ = passing, ⬜ = required (no evidence), - = not required'
-            puts
-            puts '(Evidence status will show when #1214 is complete)'
           end
         end
       end

data/lib/fp/commands/projects.rb

@@ -2,7 +2,7 @@
 
 module Fp
   module Commands
-    # fp projects - list projects/workspaces the API key has access to
+    # fp projects - list projects the API key has access to
     class Projects < Base
       def run(_args)
         result = client.list_projects
@@ -12,15 +12,21 @@ module Fp
           exit 1
         end
 
-        workspaces = result[:data]['workspaces'] || []
+        projects = result[:data]['projects'] || []
 
         output.success(result[:data]) do
-          if workspaces.empty?
+          if projects.empty?
             puts 'No projects found.'
           else
             headers = %w[SLUG NAME SURFACES]
-            rows = workspaces.map do |w|
-              surfaces = (w['available_surfaces'] || []).join(', ')
+            rows = projects.map do |w|
+              surfaces_result = client.list_surfaces(w['id'])
+              surface_keys = if surfaces_result[:ok]
+                               (surfaces_result[:data]['surfaces'] || []).map { |s| s['key'] }
+                             else
+                               []
+                             end
+              surfaces = surface_keys.join(', ')
               [w['slug'], w['name'], surfaces.empty? ? '-' : surfaces]
             end
             output.table(headers, rows)