featureparity 0.0.21 → 0.0.23

data/lib/fp/commands/showroom.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # fp showroom --project <slug>   - the client showroom, as a client will see it
+    #
+    # The showroom (Fizzy #1479) is the one page a client gets: the welcome note, then
+    # a card per surface with a link, a button label, and instructions. Its content is
+    # written through `fp projects edit --showroom-welcome` and `fp surfaces edit
+    # --showroom-*`, and this command is how an agent checks the result without a
+    # browser: the same payload the client is served, plus the surfaces that are *not*
+    # on it and why, so a card that silently dropped out (both fields cleared) is
+    # noticed.
+    #
+    # Whether the share link is on is a human's business — the API refuses an agent's
+    # key — so it is reported as unknown rather than guessed at.
+    #
+    # `fp showroom media ...` manages the screenshots and videos on the showroom — a
+    # surface's card, or the gallery under the welcome note — and is handled by
+    # ShowroomMedia; its flags are documented here so `fp showroom --help` covers both.
+    class Showroom < Base
+      help_summary 'Preview the client showroom exactly as a client will see it, and manage its media'
+      help_usage 'fp showroom --project <slug>',
+                 'fp showroom media --project <slug>',
+                 'fp showroom media add <file> --project <slug> [--surface <key>] [--caption "..."] [--position N]',
+                 'fp showroom media edit <id> --project <slug> [--caption "..."] [--position N]',
+                 'fp showroom media remove <id> --project <slug> [--yes]'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :surface, "media add: the surface whose card shows it (omit for the project gallery)"
+      help_flag :caption, 'media add/edit: text shown under the image or video (edit: empty clears)'
+      help_flag :position, 'media add/edit: slot within its card or the gallery, 1 is first; others shift (edit: empty moves it last)'
+      help_flag :yes, 'media remove: skip the typed-filename confirmation'
+      help_example 'fp showroom --project stowzilla'
+      help_example 'fp showroom media add e2e/checkout.webm --project stowzilla --surface web --caption "Checking out"'
+      help_example 'fp showroom media add overview.png --project stowzilla --position 1'
+      help_example 'fp showroom media edit <id> --project stowzilla --caption ""'
+      help_example 'fp showroom media remove <id> --project stowzilla --yes'
+      help_note "Prints the welcome note, the gallery, and each surface's card, then the surfaces that are NOT shown and why.\n" \
+                "Write the content with `fp projects edit --showroom-welcome` and `fp surfaces edit --showroom-*`.\n" \
+                "Media: png, jpg, gif, webp, mp4, webm, mov; max 100 MB. SVG and PDF are refused.\n" \
+                'The share link is reported as unknown: only a person can see or change it.'
+      def run(args)
+        if args.first == 'media'
+          return ShowroomMedia.new(client: client, output: output, config: config).run(args.drop(1))
+        end
+
+        opts, = parse_flags(args)
+        require_project!(opts)
+
+        project_id = resolve_project_id(opts[:project])
+
+        result = client.get_showroom(project_id)
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        showroom = result[:data]['showroom'] || {}
+        shown_ids = (showroom['surfaces'] || []).map { |surface| surface['id'] }
+        hidden = hidden_surfaces(project_id, shown_ids)
+        share = share_link_status(project_id)
+
+        output.success({ showroom: showroom, hidden: hidden, share_link: share, project: opts[:project] }) do
+          print_showroom(showroom, hidden, share, project: opts[:project])
+        end
+      end
+
+      private
+
+      # Surfaces with no link, no instructions, and no media. The showroom payload leaves
+      # them out (and includes a media-only surface), so whatever the payload doesn't
+      # carry is hidden; they are read from the surface list.
+      def hidden_surfaces(project_id, shown_ids)
+        result = client.list_surfaces(project_id)
+        return [] unless result[:ok]
+
+        (result[:data]['surfaces'] || []).reject { |surface| shown_ids.include?(surface['id']) }.map do |surface|
+          { 'key' => surface['key'], 'name' => surface['name'], 'kind' => surface['kind'],
+            'reason' => 'no showroom link or instructions, and no media' }
+        end
+      end
+
+      # { 'state' => 'on' | 'off' | 'unknown', 'token' => ..., 'reason' => ... }
+      def share_link_status(project_id)
+        result = client.get_showroom_share_link(project_id)
+        if result[:ok]
+          link = result[:data]['share_link']
+          link ? { 'state' => 'on', 'token' => link['token'], 'created_by' => link['created_by'] } : { 'state' => 'off' }
+        elsif result[:status] == 403
+          { 'state' => 'unknown', 'reason' => 'only a person can see or change the share link (Project Settings → Showroom)' }
+        else
+          { 'state' => 'unknown', 'reason' => result[:error] }
+        end
+      end
+
+      def print_showroom(showroom, hidden, share, project:)
+        info = showroom['project'] || {}
+        title = "Showroom: #{info['name'] || project}"
+        puts title
+        puts '=' * title.length
+        puts
+
+        welcome = text_or_nil(info['welcome'])
+        if welcome
+          puts 'Welcome:'
+          welcome.each_line { |line| puts "  #{line.rstrip}" }
+        else
+          puts 'Welcome: (none) — set one with: fp projects edit ' \
+               "#{info['slug'] || project} --showroom-welcome \"...\""
+        end
+        puts
+
+        gallery = showroom['gallery'] || []
+        unless gallery.empty?
+          puts "Gallery (#{media_summary(gallery)}):"
+          print_media(gallery, indent: '  ')
+          puts
+        end
+
+        surfaces = showroom['surfaces'] || []
+        if surfaces.empty?
+          puts "Surfaces shown: none. The client sees only the welcome note#{gallery.empty? ? '' : ' and the gallery'}."
+        else
+          puts "Surfaces shown (#{surfaces.size}):"
+          surfaces.each { |surface| print_card(surface) }
+        end
+
+        unless hidden.empty?
+          puts
+          puts "Not shown (#{hidden.size}):"
+          hidden.each do |surface|
+            puts "  - #{surface['name'] || surface['key']} (#{surface['key']}): #{surface['reason']}"
+          end
+          puts "  Add one with: fp surfaces edit <key> --project #{project} --showroom-url ... " \
+               '--showroom-instructions-file ...'
+          puts "  or: fp showroom media add <file> --project #{project} --surface <key>"
+        end
+
+        puts
+        case share['state']
+        when 'on'
+          puts "Share link: on (created by #{share['created_by'] || 'unknown'}) — the content above is live."
+        when 'off'
+          puts 'Share link: off — only signed-in clients and the team can see this.'
+        else
+          puts "Share link: unknown — #{share['reason']}"
+        end
+      end
+
+      def print_card(surface)
+        puts
+        puts "  #{surface['name']} (#{surface['kind']})"
+        url = text_or_nil(surface['url'])
+        label = text_or_nil(surface['label'])
+        puts "    Link:         #{url ? "#{url}#{label ? " [#{label}]" : ''}" : '(none)'}"
+        instructions = text_or_nil(surface['instructions'])
+        if instructions
+          puts '    Instructions:'
+          instructions.each_line { |line| puts "      #{line.rstrip}" }
+        else
+          puts '    Instructions: (none)'
+        end
+        media = surface['media'] || []
+        if media.empty?
+          puts '    Media:        (none)'
+        else
+          puts "    Media:        #{media_summary(media)}"
+          print_media(media, indent: '      ')
+        end
+      end
+
+      # "2 images, 1 video"
+      def media_summary(media)
+        counts = media.group_by { |item| item['media_kind'] == 'video' ? 'video' : 'image' }
+        %w[image video].filter_map do |kind|
+          count = counts.fetch(kind, []).size
+          "#{count} #{kind}#{count == 1 ? '' : 's'}" if count.positive?
+        end.join(', ')
+      end
+
+      def print_media(media, indent:)
+        media.each do |item|
+          caption = text_or_nil(item['caption'])
+          puts "#{indent}- #{item['media_kind'] || 'image'}: #{caption || '(no caption)'}"
+        end
+      end
+
+      def text_or_nil(value)
+        text = value.to_s.strip
+        text.empty? ? nil : text
+      end
+    end
+  end
+end

data/lib/fp/commands/showroom_media.rb

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'attach'
+
+module Fp
+  module Commands
+    # fp showroom media [--project <slug>]                        - list the showroom's media
+    # fp showroom media add <file> [--surface <key>] [--caption] [--position N]
+    # fp showroom media edit <id> [--caption "..."] [--position N]
+    # fp showroom media remove <id> [--yes]
+    #
+    # Plenty of clients never open the demo, so the showroom can show them the thing
+    # instead: screenshots or a short clip on a surface's card, or in the project gallery
+    # under the welcome note (no --surface). The agent that ran the e2e suite already has
+    # the captures, so it puts them there rather than leaving a human to re-upload them.
+    #
+    # Dispatched from `fp showroom media ...`; its help lives on `fp showroom --help`.
+    # Uploads reuse attach's flow (presign, PUT the bytes, confirm) and its visual file
+    # types — images and videos only. SVG can carry script and PDFs don't render inline,
+    # so both are refused before anything is sent.
+    class ShowroomMedia < Base
+      CONTENT_TYPES = Attach::CONTENT_TYPES.slice(*Attach::VISUAL_EXTENSIONS).freeze
+      MAX_FILE_SIZE = Attach::MAX_FILE_SIZE
+      MAX_CAPTION_LENGTH = 500
+
+      LIST_FLAGS = { project: :string }.freeze
+      ADD_FLAGS = { project: :string, surface: :string, caption: :string, position: :string }.freeze
+      EDIT_FLAGS = { project: :string, caption: :string, position: :string }.freeze
+      REMOVE_FLAGS = { project: :string, yes: :boolean }.freeze
+
+      def run(args)
+        case args.first
+        when 'add'
+          add(args[1..])
+        when 'edit'
+          edit(args[1..])
+        when 'remove', 'rm', 'delete'
+          remove(args[1..])
+        else
+          list(args)
+        end
+      end
+
+      private
+
+      # Gallery first, then each surface's media in the order a client sees the cards.
+      def list(args)
+        opts, = parse_flags(args, LIST_FLAGS)
+        require_project!(opts)
+        project_id = resolve_project_id(opts[:project])
+
+        media = fetch!(client.list_showroom_media(project_id))['media'] || []
+        groups = group_media(media, surfaces_for(project_id))
+
+        flat = groups.flat_map do |group|
+          group[:items].map { |item| item.merge('surface_key' => group[:key]) }
+        end
+
+        output.success({ media: flat, project: opts[:project] }) do
+          if media.empty?
+            puts "No showroom media in project '#{opts[:project]}'."
+            puts "Add some with: fp showroom media add <file> --project #{opts[:project]} [--surface <key>]"
+          else
+            puts "Showroom media for '#{opts[:project]}' (#{media.size}):"
+            groups.each do |group|
+              puts
+              puts "#{group[:title]} (#{group[:items].size}):"
+              group[:items].each { |item| print_item_line(item) }
+            end
+          end
+        end
+      end
+
+      def add(args)
+        opts, positional = parse_flags(args, ADD_FLAGS)
+        path = positional.first
+        if path.nil? || path.strip.empty?
+          output.error('Usage: fp showroom media add <file> --project <slug> [--surface <key>] ' \
+                       '[--caption "..."] [--position N]')
+          exit 1
+        end
+
+        # Everything that can be checked locally is checked before a byte is sent.
+        file = prepare_file!(path)
+        caption = flag_text(opts[:caption]).strip if opts.key?(:caption)
+        caption = nil if caption&.empty?
+        check_caption!(caption) if caption
+        position = position!(opts[:position], clear: nil) if opts.key?(:position)
+        if opts.key?(:surface) && flag_text(opts[:surface]).strip.empty?
+          output.error('--surface needs a surface key. Omit it to add to the project gallery.')
+          exit 1
+        end
+
+        require_project!(opts)
+        project_id = resolve_project_id(opts[:project])
+        surface = opts[:surface] ? find_surface!(project_id, opts[:surface]) : nil
+
+        presign = fetch!(client.presign_showroom_media(
+                           project_id,
+                           filename: file[:filename], content_type: file[:content_type],
+                           size_bytes: file[:size], surface_id: surface&.dig('id')
+                         ), prefix: 'Failed to get upload URL')['presign'] || {}
+
+        uploaded = client.upload_to_presigned_url(presign['upload_url'], file[:path], file[:content_type])
+        fetch!(uploaded, prefix: 'Upload failed')
+
+        item = fetch!(client.create_showroom_media(
+                        project_id,
+                        media_id: presign['media_id'], s3_key: presign['s3_key'],
+                        filename: file[:filename], content_type: file[:content_type], size_bytes: file[:size],
+                        surface_id: surface&.dig('id'), caption: caption, position: position
+                      ), prefix: 'Failed to confirm upload')['media'] || {}
+
+        where = surface ? "surface '#{surface['key']}'" : 'the project gallery'
+        output.success({ media: item, surface: surface&.dig('key'), project: opts[:project] }) do
+          puts "Added #{file[:filename]} to #{where} in project '#{opts[:project]}'."
+          print_item_detail(item)
+        end
+      end
+
+      def edit(args)
+        opts, positional = parse_flags(args, EDIT_FLAGS)
+        media_id = positional.first
+        if media_id.nil? || media_id.strip.empty?
+          output.error('Usage: fp showroom media edit <id> --project <slug> [--caption "..."] [--position N]')
+          exit 1
+        end
+
+        # Only what was passed is sent. Empty caption clears it. Positions are kept dense
+        # (1..n) per card or gallery: N inserts at slot N and shifts the rest, and an empty
+        # value — sent as 0, since the API types it as an integer — moves the item to the end.
+        params = {}
+        if opts.key?(:caption)
+          params[:caption] = flag_text(opts[:caption]).strip
+          check_caption!(params[:caption])
+        end
+        params[:position] = position!(opts[:position], clear: 0) if opts.key?(:position)
+
+        if params.empty?
+          output.error('Nothing to change. Pass --caption and/or --position (an empty value clears either).')
+          exit 1
+        end
+
+        require_project!(opts)
+        project_id = resolve_project_id(opts[:project])
+        item = fetch!(client.update_showroom_media(project_id, media_id, params))['media'] || {}
+
+        output.success({ media: item, project: opts[:project] }) do
+          puts "Updated showroom media #{media_id} in project '#{opts[:project]}'."
+          print_item_detail(item)
+        end
+      end
+
+      def remove(args)
+        opts, positional = parse_flags(args, REMOVE_FLAGS)
+        media_id = positional.first
+        if media_id.nil? || media_id.strip.empty?
+          output.error('Usage: fp showroom media remove <id> --project <slug> [--yes]')
+          exit 1
+        end
+
+        require_project!(opts)
+        project_id = resolve_project_id(opts[:project])
+
+        # Read it first: the confirmation names the file, and an unknown id fails here
+        # rather than as a bare 404 from the delete.
+        media = fetch!(client.list_showroom_media(project_id))['media'] || []
+        item = media.find { |m| m['id'] == media_id }
+        unless item
+          output.error("Showroom media '#{media_id}' not found in project '#{opts[:project]}'. " \
+                       "List it with: fp showroom media --project #{opts[:project]}", status: 404)
+          exit 1
+        end
+
+        confirm_remove!(item, opts)
+        fetch!(client.delete_showroom_media(project_id, media_id), prefix: 'Failed to remove showroom media')
+
+        output.success({ deleted: true, media: { 'id' => media_id, 'filename' => item['filename'] },
+                         project: opts[:project] }) do
+          puts "Removed #{item['filename']} (#{media_id}) from the showroom of project '#{opts[:project]}'."
+        end
+      end
+
+      # Same guard as `fp surfaces delete`: --yes skips the prompt, an interactive
+      # terminal types the filename back, and anything else is refused.
+      def confirm_remove!(item, opts)
+        return if opts[:yes]
+
+        unless interactive?
+          output.error("Refusing to remove '#{item['filename']}' without confirmation. " \
+                       'Re-run with --yes to confirm from a non-interactive session.')
+          exit 1
+        end
+
+        warn "This will remove '#{item['filename']}' from the showroom of project '#{opts[:project]}'. " \
+             'Clients stop seeing it at once.'
+        $stderr.print "Type '#{item['filename']}' to confirm: "
+        $stderr.flush
+
+        typed = $stdin.gets&.strip
+        return if typed == item['filename']
+
+        output.error('Aborted. The filename did not match; nothing was removed.')
+        exit 1
+      end
+
+      def interactive?
+        $stdin.respond_to?(:tty?) && $stdin.tty?
+      end
+
+      # { path:, filename:, content_type:, size: }, or exit with the reason it can't go up.
+      def prepare_file!(path)
+        unless File.file?(path)
+          output.error("File not found: #{path}")
+          exit 1
+        end
+
+        filename = File.basename(path)
+        extension = File.extname(filename).delete('.').downcase
+        content_type = CONTENT_TYPES[extension]
+        unless content_type
+          why = extension == 'svg' ? ' (SVG can carry script)' : ''
+          output.error("Unsupported file type: .#{extension}#{why}. The showroom takes images " \
+                       "(png, jpg, jpeg, gif, webp) and videos (mp4, webm, mov) only.")
+          exit 1
+        end
+
+        size = File.size(path)
+        if size.zero?
+          output.error("File is empty: #{path}")
+          exit 1
+        end
+        if size > MAX_FILE_SIZE
+          output.error("File too large: #{format_size(size)} (max #{format_size(MAX_FILE_SIZE)})")
+          exit 1
+        end
+
+        { path: path, filename: filename, content_type: content_type, size: size }
+      end
+
+      def check_caption!(caption)
+        return if caption.length <= MAX_CAPTION_LENGTH
+
+        output.error("--caption is #{caption.length} characters; the limit is #{MAX_CAPTION_LENGTH}.")
+        exit 1
+      end
+
+      # 1 is first. An empty value returns `clear` (nil on add — it goes at the end
+      # anyway — and 0 on edit, which moves it to the end); anything else must be a whole
+      # number of 1 or more.
+      def position!(value, clear:)
+        text = flag_text(value).strip
+        return clear if text.empty?
+
+        position = Integer(text, 10, exception: false)
+        return position if position&.positive?
+
+        output.error("Invalid --position '#{text}'. Must be a whole number of 1 or more; " \
+                     'pass an empty value to clear it.')
+        exit 1
+      end
+
+      # A string flag given with no value parses as `true`; treat that as empty.
+      def flag_text(value)
+        value == true ? '' : value.to_s
+      end
+
+      def surfaces_for(project_id)
+        result = client.list_surfaces(project_id)
+        result[:ok] ? (result[:data]['surfaces'] || []) : []
+      end
+
+      def find_surface!(project_id, key)
+        fetch!(client.find_surface_by_key(project_id, key))['surface']
+      end
+
+      # [{ title:, key:, items: }] — the gallery, then each surface with media in showroom
+      # order (placed surfaces lowest first, then by name, as Surface#showroom_sort_key
+      # does). Within a group the server's order stands: it already sorts by position.
+      def group_media(media, surfaces)
+        groups = []
+        gallery = media.select { |m| m['surface_id'].to_s.empty? }
+        groups << { title: 'Gallery (under the welcome note)', key: nil, items: gallery } unless gallery.empty?
+
+        by_surface = media.reject { |m| m['surface_id'].to_s.empty? }.group_by { |m| m['surface_id'] }
+        surfaces.sort_by { |s| surface_sort_key(s) }.each do |surface|
+          items = by_surface.delete(surface['id'])
+          next unless items
+
+          groups << { title: "#{surface['name'] || surface['key']} (#{surface['key']})", key: surface['key'],
+                      items: items }
+        end
+        by_surface.each do |surface_id, items|
+          groups << { title: "Unknown surface #{surface_id}", key: nil, items: items }
+        end
+        groups
+      end
+
+      def surface_sort_key(surface)
+        position = surface['showroom_position'].to_i
+        position = nil if position < 1
+        [position ? 0 : 1, position || 0, surface['name'].to_s.downcase, surface['id'].to_s]
+      end
+
+      def print_item_line(item)
+        position = item['position'].to_i.positive? ? "##{item['position'].to_i}" : '-'
+        caption = item['caption'].to_s.strip
+        line = "  #{item['id']}  #{position.ljust(3)}  #{item['media_kind'].to_s.ljust(5)}  #{item['filename']}"
+        line += "  \"#{caption}\"" unless caption.empty?
+        puts line
+      end
+
+      def print_item_detail(item)
+        puts
+        puts "  ID:       #{item['id']}"
+        puts "  Kind:     #{item['media_kind']} (#{item['content_type']})"
+        puts "  File:     #{item['filename']}#{item['size_bytes'] ? " (#{format_size(item['size_bytes'].to_i)})" : ''}"
+        caption = item['caption'].to_s.strip
+        puts "  Caption:  #{caption.empty? ? '(none)' : caption}"
+        position = item['position'].to_i
+        puts "  Position: #{position.positive? ? position : '(last)'}"
+      end
+
+      # The response data, or exit with the API's error.
+      def fetch!(result, prefix: nil)
+        return result[:data] || {} if result[:ok]
+
+        output.error([prefix, result[:error]].compact.join(': '), status: result[:status])
+        exit 1
+      end
+    end
+  end
+end