featureparity 0.0.1

data/lib/fp/commands/profile.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # fp profile add|list
+    # Manage named profiles for API authentication
+    class Profile < Base
+      KNOWN_FLAGS = {
+        api_key: :string,
+        api_url: :string
+      }.freeze
+
+      def run(args)
+        opts, positional = parse_flags(args, KNOWN_FLAGS)
+        subcommand = positional.first
+
+        case subcommand
+        when 'add'
+          add_profile(positional[1], opts)
+        when 'list'
+          list_profiles
+        else
+          show_usage
+        end
+      end
+
+      private
+
+      def add_profile(name, opts)
+        unless name
+          output.error('Profile name is required. Usage: fp profile add <name> --api-key fp_...')
+          exit 1
+        end
+
+        unless opts[:api_key]
+          output.error('--api-key is required')
+          exit 1
+        end
+
+        unless opts[:api_key].start_with?('fp_')
+          output.error("API key must start with 'fp_' prefix")
+          exit 1
+        end
+
+        Config.save_profile(name, api_key: opts[:api_key], api_url: opts[:api_url])
+
+        output.success({ profile: name, api_url: opts[:api_url] || Config::DEFAULT_API_URL }) do
+          puts "Profile '#{name}' saved."
+          puts "  API URL: #{opts[:api_url] || Config::DEFAULT_API_URL}"
+          puts
+          puts 'Use this profile with:'
+          puts "  fp --profile #{name} projects"
+          puts "  FP_PROFILE=#{name} fp projects"
+        end
+      end
+
+      def list_profiles
+        profiles = Config.list_profiles
+
+        if profiles.empty?
+          output.success({ profiles: [] }) do
+            puts 'No profiles configured.'
+            puts
+            puts 'Add a profile with:'
+            puts '  fp profile add <name> --api-key fp_...'
+          end
+        else
+          output.success({ profiles: profiles }) do
+            puts 'Configured profiles:'
+            profiles.each { |name| puts "  - #{name}" }
+            puts
+            puts 'Note: API keys are never displayed. Use --profile <name> to select.'
+          end
+        end
+      end
+
+      def show_usage
+        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 list                         List configured profiles'
+        exit 1
+      end
+    end
+  end
+end

data/lib/fp/commands/projects.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # fp projects - list projects/workspaces the API key has access to
+    class Projects < Base
+      def run(_args)
+        result = client.list_projects
+
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        workspaces = result[:data]['workspaces'] || []
+
+        output.success(result[:data]) do
+          if workspaces.empty?
+            puts 'No projects found.'
+          else
+            headers = %w[SLUG NAME SURFACES]
+            rows = workspaces.map do |w|
+              surfaces = (w['available_surfaces'] || []).join(', ')
+              [w['slug'], w['name'], surfaces.empty? ? '-' : surfaces]
+            end
+            output.table(headers, rows)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/fp/commands/propose.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # fp propose --project <slug> --slug X --name "..." --why "..." --required a,b,c --acceptance "..."
+    # Create a new requirement as draft
+    class Propose < Base
+      KNOWN_FLAGS = {
+        project: :string,
+        slug: :string,
+        name: :string,
+        why: :string,
+        required: :string,
+        acceptance: :string
+      }.freeze
+
+      def run(args)
+        opts, = parse_flags(args, KNOWN_FLAGS)
+
+        require_flag(opts, :project)
+        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])
+
+        # Parse required surfaces (comma-separated)
+        required_surfaces = if opts[:required]
+                              opts[:required].split(',').map(&:strip)
+                            else
+                              []
+                            end
+
+        params = {
+          slug: opts[:slug],
+          title: opts[:name],
+          workspace_id: workspace_id,
+          required_surfaces: required_surfaces
+        }
+        params[:why] = opts[:why] if opts[:why]
+        params[:acceptance] = opts[:acceptance] if opts[:acceptance]
+        # Note: status is NOT sent - the API enforces draft for agents
+
+        result = client.create_requirement(params)
+
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        requirement = result[:data]['requirement']
+
+        output.success(result[:data]) do
+          puts "Created requirement '#{requirement['slug']}' as DRAFT."
+          puts
+          puts "  Title:    #{requirement['title']}"
+          puts "  Status:   #{requirement['status']}"
+          puts "  Surfaces: #{(requirement['required_surfaces'] || []).join(', ')}"
+          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
+    end
+  end
+end

data/lib/fp/commands/report.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+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
+    class Report < Base
+      KNOWN_FLAGS = {
+        project: :string,
+        surface: :string,
+        file: :string,
+        repo: :string,
+        pr: :string,
+        sha: :string,
+        work_item: :string,
+        ci_url: :string,
+        title: :string,
+        state: :string
+      }.freeze
+
+      VALID_STATES = %w[present stub].freeze
+
+      def run(args)
+        opts, positional = parse_flags(args, KNOWN_FLAGS)
+
+        slug = positional.first
+        unless slug
+          output.error('Requirement slug is required. Usage: fp report <slug> --project <project> --surface <surface> --file <path> --repo <org/repo>')
+          exit 1
+        end
+
+        require_flag(opts, :project)
+        require_flag(opts, :surface)
+        require_flag(opts, :file)
+        require_flag(opts, :repo)
+
+        # Validate state
+        state = opts[:state] || 'present'
+        unless VALID_STATES.include?(state)
+          output.error("Invalid state '#{state}'. 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
+
+        workspace_id = resolve_workspace_id(opts[:project])
+
+        # Find the requirement by slug
+        req_result = client.find_requirement_by_slug(workspace_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'],
+          surface: opts[:surface],
+          file: opts[: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[:example_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
+          output.success(params, summary: nil) do
+            puts "Evidence for '#{slug}' on surface '#{opts[:surface]}':"
+            puts "  State:     #{state}"
+            puts "  File:      #{opts[:file]}"
+            puts "  Repo:      #{opts[:repo]}"
+            puts "  PR:        #{opts[:pr]}" if opts[:pr]
+            puts "  SHA:       #{opts[:sha]}" if opts[:sha]
+            puts "  Work Item: #{opts[:work_item]}" if opts[:work_item]
+            puts "  CI URL:    #{opts[:ci_url]}" if opts[:ci_url]
+            puts "  Title:     #{opts[:title]}" if opts[:title]
+            puts
+            puts '⚠️  Evidence API not available yet. This will be recorded when #1214 is complete.'
+          end
+          return
+        end
+
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        output.success(result[:data]) do
+          puts "Evidence reported for '#{slug}' on surface '#{opts[:surface]}'."
+          puts "  State: #{state}"
+          puts "  File:  #{opts[:file]}"
+          if opts[:pr]
+            puts "  PR:    #{opts[:pr]}"
+          end
+          if opts[:work_item]
+            puts "  Work:  #{opts[:work_item]}"
+          end
+          if opts[:ci_url]
+            puts "  CI:    #{opts[:ci_url]}"
+          end
+          if opts[:title]
+            puts "  Title: #{opts[:title]}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/fp/commands/setup.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # fp setup
+    # Interactive guided setup for new users.
+    # Validates the API key, checks connectivity, and saves a profile.
+    class Setup < Base
+      KNOWN_FLAGS = {
+        api_key: :string,
+        profile: :string,
+        api_url: :string,
+        non_interactive: :boolean
+      }.freeze
+
+      def run(args)
+        opts, _positional = parse_flags(args, KNOWN_FLAGS)
+
+        puts "🔧 FeatureParity CLI Setup"
+        puts "=" * 40
+        puts
+
+        api_key = resolve_api_key(opts)
+        profile_name = resolve_profile_name(opts)
+        api_url = opts[:api_url]
+
+        puts "Validating API key..."
+        validate_key!(api_key, api_url)
+
+        save_profile!(profile_name, api_key, api_url)
+
+        puts
+        puts "✅ Setup complete!"
+        puts
+        puts "Your profile '#{profile_name}' is ready. Usage:"
+        puts
+        puts "  fp --profile #{profile_name} projects"
+        puts "  FP_PROFILE=#{profile_name} fp projects"
+        puts
+        puts "Or set FP_API_KEY to skip profiles:"
+        puts "  export FP_API_KEY=#{api_key[0..6]}..."
+      end
+
+      private
+
+      def resolve_api_key(opts)
+        if opts[:api_key]
+          validate_key_format!(opts[:api_key])
+          return opts[:api_key]
+        end
+
+        if opts[:non_interactive]
+          output.error("--api-key is required in non-interactive mode")
+          exit 1
+        end
+
+        puts "Get your API key from: https://featureparity.dev"
+        puts "(Workspace Settings → API Keys → Mint Key)"
+        puts
+        print "Paste your API key (starts with fp_): "
+        $stdout.flush
+        key = $stdin.gets&.strip
+
+        if key.nil? || key.empty?
+          output.error("No API key provided")
+          exit 1
+        end
+
+        validate_key_format!(key)
+        key
+      end
+
+      def resolve_profile_name(opts)
+        if opts[:profile]
+          return opts[:profile]
+        end
+
+        if opts[:non_interactive]
+          return 'default'
+        end
+
+        print "Profile name (default: 'default'): "
+        $stdout.flush
+        name = $stdin.gets&.strip
+
+        name.nil? || name.empty? ? 'default' : name
+      end
+
+      def validate_key_format!(key)
+        unless key.start_with?('fp_')
+          output.error("API key must start with 'fp_' prefix. Got: #{key[0..3]}...")
+          exit 1
+        end
+
+        if key.length < 10
+          output.error("API key looks too short. Check that you copied the full key.")
+          exit 1
+        end
+      end
+
+      def validate_key!(api_key, api_url)
+        url = (api_url || Config::DEFAULT_API_URL).chomp('/')
+        uri = URI.parse("#{url}/api/workspaces")
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == 'https'
+        http.open_timeout = 10
+        http.read_timeout = 10
+
+        request = Net::HTTP::Get.new(uri)
+        request['Authorization'] = "Bearer #{api_key}"
+        request['Accept'] = 'application/json'
+        request['User-Agent'] = "fp-cli/#{Fp::VERSION}"
+
+        response = http.request(request)
+        status = response.code.to_i
+
+        if status == 401 || status == 403
+          output.error("API key is invalid or expired (HTTP #{status}). Mint a new one at https://featureparity.dev")
+          exit 1
+        end
+
+        if status >= 500
+          output.error("API server error (HTTP #{status}). Try again later.")
+          exit 1
+        end
+
+        unless status >= 200 && status < 300
+          output.error("Unexpected response (HTTP #{status}). Check your API URL.")
+          exit 1
+        end
+
+        puts "  ✓ API key is valid"
+      rescue Net::OpenTimeout, Net::ReadTimeout
+        output.error("Connection timed out. Check your network and API URL.")
+        exit 1
+      rescue SocketError, Errno::ECONNREFUSED => e
+        output.error("Cannot connect to API: #{e.message}")
+        exit 1
+      end
+
+      def save_profile!(name, api_key, api_url)
+        Config.save_profile(name, api_key: api_key, api_url: api_url)
+        puts "  ✓ Profile '#{name}' saved to ~/.config/fp/config.yml"
+      end
+    end
+  end
+end

data/lib/fp/commands/show.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # fp show <slug> --project <slug>
+    # Show requirement details including evidence receipts
+    class Show < Base
+      def run(args)
+        opts, positional = parse_flags(args)
+        require_flag(opts, :project)
+
+        slug = positional.first
+        unless slug
+          output.error('Requirement slug is required. Usage: fp show <slug> --project <project>')
+          exit 1
+        end
+
+        workspace_id = resolve_workspace_id(opts[:project])
+        result = client.find_requirement_by_slug(workspace_id, slug)
+
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        requirement = result[:data]['requirement']
+
+        output.success(result[:data]) do
+          print_requirement(requirement)
+        end
+      end
+
+      private
+
+      def print_requirement(req)
+        puts "#{req['title']}"
+        puts "=" * req['title'].length
+        puts
+        puts "Slug:     #{req['slug']}"
+        puts "Status:   #{req['status']}"
+        puts
+
+        surfaces = req['required_surfaces'] || []
+        puts 'Required Surfaces:'
+        if surfaces.empty?
+          puts '  (none)'
+        else
+          surfaces.each { |s| puts "  - #{s}" }
+        end
+        puts
+
+        if req['why'] && !req['why'].empty?
+          puts 'Why:'
+          puts "  #{req['why']}"
+          puts
+        end
+
+        if req['acceptance'] && !req['acceptance'].empty?
+          puts 'Acceptance Criteria:'
+          puts "  #{req['acceptance']}"
+          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:'
+          puts '  (none reported)'
+          puts
+        end
+
+        puts "Created:  #{req['created_at']}"
+        puts "Updated:  #{req['updated_at']}"
+        puts "By:       #{req['created_by']}" if req['created_by']
+      end
+    end
+  end
+end

data/lib/fp/commands/surfaces.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # fp surfaces --project <slug> - list available surfaces for a project
+    class Surfaces < Base
+      def run(args)
+        opts, = parse_flags(args)
+        require_flag(opts, :project)
+
+        workspace_id = resolve_workspace_id(opts[:project])
+        result = client.get_project(workspace_id)
+
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        workspace = result[:data]['workspace']
+        surfaces = workspace['available_surfaces'] || []
+
+        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.'
+          else
+            puts "Surfaces for '#{opts[:project]}':"
+            surfaces.each { |s| puts "  - #{s}" }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/fp/commands/version.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # fp version
+    class Version < Base
+      def run(_args)
+        output.success({ version: Fp::VERSION }) do
+          puts "fp #{Fp::VERSION}"
+        end
+      end
+    end
+  end
+end

data/lib/fp/commands.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'commands/base'
+require_relative 'commands/projects'
+require_relative 'commands/surfaces'
+require_relative 'commands/list'
+require_relative 'commands/show'
+require_relative 'commands/propose'
+require_relative 'commands/report'
+require_relative 'commands/matrix'
+require_relative 'commands/profile'
+require_relative 'commands/setup'
+require_relative 'commands/version'
+require_relative 'commands/help'
+
+module Fp
+  module Commands
+  end
+end