featureparity 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 695b5f522e34a1e886e07177cbbe5ca87b515caf6845e15b50ca9e1c4fb3735e
+  data.tar.gz: 18ff57dfb177341dd4a6f2d8dc05e862a53d8e24eb0c2da4172e022986533cc1
+SHA512:
+  metadata.gz: 9851ef3ea41669276c356fbe2e5a200ec06d59cea82a9d852eaca71a20297319b4eeb32e5a684921cfba3b298bf1e8931f45bc89ad0c59d802128a5f5940b157
+  data.tar.gz: 1e075a99c1b02368908639649ff45ba78be33f8e0a03756b0f7782275758f326e01992488508c6930d1f5ac65e47eb6ef7b5e24438482e6eac2b855fe06b2557

data/bin/fp

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/fp'
+
+Fp::CLI.run(ARGV)

data/lib/fp/cli.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Fp
+  # Main CLI entry point - parses global flags and dispatches to commands
+  class CLI
+    COMMANDS = {
+      'projects' => Commands::Projects,
+      'surfaces' => Commands::Surfaces,
+      'list' => Commands::List,
+      'show' => Commands::Show,
+      'propose' => Commands::Propose,
+      'report' => Commands::Report,
+      'matrix' => Commands::Matrix,
+      'profile' => Commands::Profile,
+      'setup' => Commands::Setup,
+      'version' => Commands::Version,
+      'help' => Commands::Help
+    }.freeze
+
+    class << self
+      def run(argv)
+        args = argv.dup
+        global_opts = extract_global_options(args)
+
+        command_name = args.shift || 'help'
+        command_class = COMMANDS[command_name]
+
+        unless command_class
+          output = Output.new(json: global_opts[:json])
+          output.error("Unknown command: #{command_name}")
+          puts "\nRun 'fp help' for usage."
+          exit 1
+        end
+
+        # Profile commands don't need auth
+        needs_auth = !%w[profile setup version help].include?(command_name)
+
+        if needs_auth
+          config = Config.new(profile: global_opts[:profile])
+          unless config.valid?
+            output = Output.new(json: global_opts[:json])
+            output.error(config.validation_error.strip)
+            exit 1
+          end
+          client = Client.new(config)
+        end
+
+        output = Output.new(json: global_opts[:json])
+        command = command_class.new(client: client, output: output, config: config)
+        command.run(args)
+      rescue Interrupt
+        warn "\nAborted."
+        exit 130
+      rescue StandardError => e
+        output = Output.new(json: global_opts&.dig(:json))
+        output.error(e.message)
+        exit 1
+      end
+
+      private
+
+      def extract_global_options(args)
+        opts = { json: false, profile: nil }
+
+        # Extract --json flag
+        if args.delete('--json')
+          opts[:json] = true
+        end
+
+        # Extract --profile flag
+        if (idx = args.index('--profile'))
+          args.delete_at(idx)
+          value = args[idx]
+          if value.nil? || value.start_with?('-')
+            $stderr.puts "Error: --profile requires a value"
+            exit 1
+          end
+          opts[:profile] = args.delete_at(idx)
+        end
+
+        # Also check short form -p
+        if (idx = args.index('-p'))
+          args.delete_at(idx)
+          value = args[idx]
+          if value.nil? || value.start_with?('-')
+            $stderr.puts "Error: -p requires a profile name"
+            exit 1
+          end
+          opts[:profile] = args.delete_at(idx)
+        end
+
+        opts
+      end
+    end
+  end
+end

data/lib/fp/client.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+module Fp
+  # HTTP client for the FeatureParity API
+  class Client
+    def initialize(config)
+      @config = config
+      @base_url = config.api_url.chomp('/')
+    end
+
+    # GET /workspaces (called "projects" in the CLI)
+    def list_projects
+      get('/api/workspaces')
+    end
+
+    # GET /workspaces/:id
+    def get_project(id)
+      get("/api/workspaces/#{id}")
+    end
+
+    # GET /requirements
+    def list_requirements(workspace_id: nil, status: nil)
+      params = {}
+      params[:workspace_id] = workspace_id if workspace_id
+      params[:status] = status if status
+      get('/api/requirements', params)
+    end
+
+    # GET /requirements/:id
+    def get_requirement(id)
+      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)
+      return result unless result[:ok]
+
+      requirements = result[:data]['requirements'] || []
+      requirement = requirements.find { |r| r['slug'] == slug }
+
+      if requirement
+        { ok: true, data: { 'requirement' => requirement } }
+      else
+        { ok: false, error: "Requirement '#{slug}' not found in workspace", status: 404 }
+      end
+    end
+
+    # POST /requirements
+    def create_requirement(params)
+      post('/api/requirements', params)
+    end
+
+    # PUT /requirements/:id
+    def update_requirement(id, params)
+      put("/api/requirements/#{id}", params)
+    end
+
+    # POST /evidence (when API is ready)
+    def report_evidence(params)
+      post('/api/evidence', params)
+    end
+
+    # GET /matrix (when API is ready)
+    def get_matrix(workspace_id, format: :json)
+      path = format == :csv ? '/api/matrix.csv' : '/api/matrix'
+      get(path, { workspace_id: workspace_id })
+    end
+
+    # GET /gaps (when API is ready)
+    def get_gaps(workspace_id, surface: nil)
+      params = { workspace_id: workspace_id }
+      params[:surface] = surface if surface
+      get('/api/gaps', params)
+    end
+
+    private
+
+    def get(path, params = {})
+      uri = build_uri(path, params)
+      request = Net::HTTP::Get.new(uri)
+      execute(uri, request)
+    end
+
+    def post(path, body)
+      uri = build_uri(path)
+      request = Net::HTTP::Post.new(uri)
+      request.body = body.to_json
+      request['Content-Type'] = 'application/json'
+      execute(uri, request)
+    end
+
+    def put(path, body)
+      uri = build_uri(path)
+      request = Net::HTTP::Put.new(uri)
+      request.body = body.to_json
+      request['Content-Type'] = 'application/json'
+      execute(uri, request)
+    end
+
+    def build_uri(path, params = {})
+      uri = URI.parse("#{@base_url}#{path}")
+      uri.query = URI.encode_www_form(params) unless params.empty?
+      uri
+    end
+
+    def execute(uri, request)
+      request['Authorization'] = "Bearer #{@config.api_key}"
+      request['Accept'] = 'application/json'
+      request['User-Agent'] = "fp-cli/#{Fp::VERSION}"
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.open_timeout = 10
+      http.read_timeout = 30
+
+      response = http.request(request)
+      parse_response(response)
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      { ok: false, error: "Request timed out: #{e.message}", status: 0 }
+    rescue SocketError, Errno::ECONNREFUSED => e
+      { ok: false, error: "Connection failed: #{e.message}", status: 0 }
+    rescue StandardError => e
+      { ok: false, error: "Request failed: #{e.message}", status: 0 }
+    end
+
+    def parse_response(response)
+      body = response.body
+      status = response.code.to_i
+
+      # Try to parse as JSON
+      data = JSON.parse(body) rescue nil
+
+      if status >= 200 && status < 300
+        { ok: true, data: data, status: status }
+      else
+        error_message = if data.is_a?(Hash)
+                          data['error'] || data['message'] || "HTTP #{status}"
+                        else
+                          body.to_s.empty? ? "HTTP #{status}" : body.to_s[0..200]
+                        end
+        { ok: false, error: error_message, status: status }
+      end
+    end
+  end
+end

data/lib/fp/commands/base.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # Base class for all commands
+    class Base
+      def initialize(client: nil, output: nil, config: nil)
+        @client = client
+        @output = output
+        @config = config
+      end
+
+      def run(_args)
+        raise NotImplementedError, "#{self.class}#run must be implemented"
+      end
+
+      protected
+
+      attr_reader :client, :output, :config
+
+      # Parse command-line flags into a hash
+      # Supports: --flag value, --flag=value, --boolean-flag
+      def parse_flags(args, known_flags = {})
+        opts = {}
+        positional = []
+        i = 0
+
+        while i < args.length
+          arg = args[i]
+
+          if arg.start_with?('--')
+            if arg.include?('=')
+              key, value = arg[2..].split('=', 2)
+              opts[key.tr('-', '_').to_sym] = value
+            elsif known_flags[arg[2..].tr('-', '_').to_sym] == :boolean
+              opts[arg[2..].tr('-', '_').to_sym] = true
+            elsif i + 1 < args.length && !args[i + 1].start_with?('--')
+              opts[arg[2..].tr('-', '_').to_sym] = args[i + 1]
+              i += 1
+            else
+              opts[arg[2..].tr('-', '_').to_sym] = true
+            end
+          else
+            positional << arg
+          end
+
+          i += 1
+        end
+
+        [opts, positional]
+      end
+
+      # Resolve workspace ID from --project flag (can be slug or ID)
+      def resolve_workspace_id(project_slug_or_id)
+        return nil unless project_slug_or_id
+
+        # First try to find by listing workspaces
+        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 }
+
+        unless workspace
+          output.error("Project '#{project_slug_or_id}' not found")
+          exit 1
+        end
+
+        workspace['id']
+      end
+
+      def require_flag(opts, flag, message = nil)
+        unless opts[flag]
+          message ||= "--#{flag.to_s.tr('_', '-')} is required"
+          output.error(message)
+          exit 1
+        end
+      end
+
+      def truncate(str, max)
+        return str if str.nil? || str.length <= max
+
+        str[0...max - 3] + '...'
+      end
+    end
+  end
+end

data/lib/fp/commands/help.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # fp help
+    class Help < Base
+      def run(_args)
+        puts <<~HELP
+          fp - FeatureParity CLI for agents
+
+          USAGE
+            fp <command> [flags]
+
+          COMMANDS
+            projects                          List projects you have access to
+            surfaces --project <slug>         List surfaces for a project
+            list --project <slug>             List active requirements
+            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
+            matrix --project <slug>           Show the parity matrix
+            profile add|list                  Manage named profiles
+            setup                             Interactive first-time setup
+            version                           Show version
+            help                              Show this help
+
+          GLOBAL FLAGS
+            --json                            Output as JSON envelope
+            --profile <name>                  Use a named profile
+            -p <name>                         Alias for --profile
+
+          AUTHENTICATION
+            Set FP_API_KEY environment variable, or use a profile:
+
+              export FP_API_KEY=fp_...
+              fp projects
+
+            Or run interactive setup (validates key and saves profile):
+
+              fp setup
+              fp setup --api-key fp_... --non-interactive
+
+            Or add a named profile manually:
+
+              fp profile add galen --api-key fp_...
+              fp --profile galen projects
+              FP_PROFILE=galen fp projects
+
+            If both FP_API_KEY and a profile are set, FP_API_KEY wins.
+
+          EXAMPLES
+            # First-time setup (interactive)
+            fp setup
+
+            # Non-interactive setup for CI/automation
+            fp setup --api-key fp_... --profile ci-agent --non-interactive
+
+            # List projects
+            fp projects
+
+            # List requirements for a project
+            fp list --project stowzilla
+
+            # Show gaps (requirements without evidence)
+            fp list --project stowzilla --gaps --surface customer_android
+
+            # Show a specific requirement
+            fp show print_container_qr --project stowzilla
+
+            # Propose a new requirement (creates as draft)
+            fp propose --project stowzilla \\
+              --slug print_container_qr \\
+              --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"
+
+            # Report evidence for a requirement
+            fp report print_container_qr --project stowzilla \\
+              --surface customer_android \\
+              --file app/src/test/java/PrintQrTest.kt \\
+              --repo stowzilla/customer-android \\
+              --pr https://github.com/stowzilla/customer-android/pull/123 \\
+              --work-item https://app.fizzy.do/123/cards/456 \\
+              --title "prints a QR code onto the container label"
+
+            # Show the parity matrix
+            fp matrix --project stowzilla
+
+            # Export matrix as CSV
+            fp matrix --project stowzilla --csv > matrix.csv
+
+          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.
+
+            Example (Ruby/RSpec):
+              # fp:print_container_qr
+              it 'prints a QR code onto the container label' do
+                ...
+              end
+
+            Example (Kotlin):
+              // fp:print_container_qr
+              @Test
+              fun `prints a QR code onto the container label`() {
+                ...
+              }
+
+            Example (Swift/XCTest):
+              // fp:print_container_qr
+              func testPrintsQRCodeOntoContainerLabel() {
+                ...
+              }
+
+          MORE INFORMATION
+            https://featureparity.dev/docs
+        HELP
+      end
+    end
+  end
+end

data/lib/fp/commands/list.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # fp list --project <slug> [--surface X] [--gaps] [--status draft]
+    # List requirements, optionally filtered
+    class List < Base
+      KNOWN_FLAGS = {
+        project: :string,
+        surface: :string,
+        status: :string,
+        gaps: :boolean
+      }.freeze
+
+      def run(args)
+        opts, = parse_flags(args, KNOWN_FLAGS)
+        require_flag(opts, :project)
+
+        workspace_id = resolve_workspace_id(opts[:project])
+
+        if opts[:gaps]
+          list_gaps(workspace_id, opts)
+        else
+          list_requirements(workspace_id, opts)
+        end
+      end
+
+      private
+
+      def list_requirements(workspace_id, opts)
+        result = client.list_requirements(workspace_id: workspace_id)
+
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        requirements = result[:data]['requirements'] || []
+
+        # Filter by status (default: active only)
+        status_filter = opts[:status] || 'active'
+        requirements = requirements.select { |r| r['status'] == status_filter }
+
+        # Filter by surface if specified
+        if opts[:surface]
+          requirements = requirements.select do |r|
+            (r['required_surfaces'] || []).include?(opts[:surface])
+          end
+        end
+
+        output.success({ requirements: requirements, project: opts[:project] }) do
+          if requirements.empty?
+            puts "No #{status_filter} requirements found."
+          else
+            headers = %w[SLUG TITLE SURFACES STATUS]
+            rows = requirements.map do |r|
+              surfaces = (r['required_surfaces'] || []).join(', ')
+              [r['slug'], truncate(r['title'], 40), surfaces.empty? ? '-' : surfaces, r['status']]
+            end
+            output.table(headers, rows)
+          end
+        end
+      end
+
+      def list_gaps(workspace_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)
+
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        # Only show active requirements for gaps
+        requirements = (result[:data]['requirements'] || []).select { |r| r['status'] == 'active' }
+
+        # Filter by surface if specified
+        if opts[:surface]
+          requirements = requirements.select do |r|
+            (r['required_surfaces'] || []).include?(opts[:surface])
+          end
+        end
+
+        # 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
+          if requirements.empty?
+            puts 'No gaps found.'
+          else
+            puts "Gaps for project '#{opts[:project]}'" + (opts[:surface] ? " (surface: #{opts[:surface]})" : '') + ':'
+            headers = %w[SLUG TITLE SURFACES]
+            rows = requirements.map do |r|
+              surfaces = (r['required_surfaces'] || []).join(', ')
+              [r['slug'], truncate(r['title'], 40), surfaces]
+            end
+            output.table(headers, rows)
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/fp/commands/matrix.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # fp matrix --project <slug> [--csv]
+    # Show the requirements traceability matrix
+    class Matrix < Base
+      KNOWN_FLAGS = {
+        project: :string,
+        csv: :boolean
+      }.freeze
+
+      def run(args)
+        opts, = parse_flags(args, KNOWN_FLAGS)
+        require_flag(opts, :project)
+
+        workspace_id = resolve_workspace_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])
+          exit 1
+        end
+
+        workspace = ws_result[:data]['workspace']
+        surfaces = workspace['available_surfaces'] || []
+
+        # Get active requirements
+        req_result = client.list_requirements(workspace_id: workspace_id)
+        unless req_result[:ok]
+          output.error(req_result[:error], status: req_result[:status])
+          exit 1
+        end
+
+        requirements = (req_result[:data]['requirements'] || []).select { |r| r['status'] == 'active' }
+
+        if requirements.empty?
+          output.success({ matrix: [], surfaces: surfaces }) do
+            puts 'No active requirements. The matrix is empty.'
+          end
+          return
+        end
+
+        # Build matrix data
+        # Columns: SLUG, TITLE, then one column per surface
+        headers = %w[SLUG TITLE] + surfaces
+
+        rows = requirements.map do |req|
+          required = req['required_surfaces'] || []
+          # Evidence status per surface (placeholder until Evidence API exists)
+          surface_cells = surfaces.map do |s|
+            if required.include?(s)
+              '⬜'  # Required but no evidence yet
+            else
+              '-'   # Not required
+            end
+          end
+          [req['slug'], truncate(req['title'], 30)] + surface_cells
+        end
+
+        if opts[:csv]
+          output.csv(headers, rows)
+        else
+          output.success({ requirements: requirements, surfaces: surfaces, project: opts[:project] }) do
+            puts "Parity Matrix: #{opts[:project]}"
+            puts
+            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
+
+    end
+  end
+end