slidict 0.2.0 → 0.4.0

data/lib/slidict/cli/lint.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Slidict
+  module Cli
+    # Implements `slidict lint <file>`: diagnoses whether a Markdown/Asciidoc
+    # slide deck has a structure that an audience can actually follow (not
+    # whether it looks nice). Diagnosis only -- it does not rewrite the file.
+    class Lint
+      ASCIIDOC_EXTENSIONS = %w[.adoc .asciidoc].freeze
+
+      def initialize(output:, linter_factory: nil, renderer: Slidict::Lint::Renderer.new)
+        @output = output
+        @linter_factory = linter_factory || method(:default_linter)
+        @renderer = renderer
+      end
+
+      def run(argv)
+        options = parse(argv)
+        return print_help if options[:help] || options[:path].nil?
+        return file_not_found(options[:path]) unless File.exist?(options[:path])
+
+        run_lint(options)
+      rescue ArgumentError => e
+        print_usage_error(e)
+      rescue Slidict::Lint::Linter::Error, Llm::Client::Error => e
+        print_error(e)
+      end
+
+      private
+
+      def run_lint(options)
+        config = build_config(options)
+        return llm_required unless config.llm_enabled?
+
+        print_findings(lint(options, config))
+      end
+
+      def lint(options, config)
+        @linter_factory.call(config).lint(File.read(options[:path]), format: format_for(options))
+      end
+
+      def print_usage_error(error)
+        print_error(error)
+        @output.puts
+        print_help
+        1
+      end
+
+      def print_error(error)
+        @output.puts "Error: #{error.message}"
+        1
+      end
+
+      def parse(argv)
+        args = argv.dup
+        options = { path: extract_path!(args) }
+        parse_options!(args, options)
+        options
+      end
+
+      def extract_path!(args)
+        args.shift unless args.first.to_s.start_with?("-")
+      end
+
+      def parse_options!(args, options)
+        until args.empty?
+          case (arg = args.shift)
+          when "-h", "--help" then options[:help] = true
+          when "--format" then options[:format] = fetch_value!(args, arg)
+          when "--llm-base-url" then options[:llm_base_url] = fetch_value!(args, arg)
+          when "--llm-api-key" then options[:llm_api_key] = fetch_value!(args, arg)
+          when "--llm-model" then options[:llm_model] = fetch_value!(args, arg)
+          else raise ArgumentError, "unknown option #{arg}"
+          end
+        end
+      end
+
+      def fetch_value!(args, option)
+        value = args.shift
+        raise ArgumentError, "#{option} requires a value" if value.nil? || value.start_with?("-")
+
+        value
+      end
+
+      def build_config(options)
+        Config.from_env.merge(
+          base_url: options[:llm_base_url],
+          api_key: options[:llm_api_key],
+          model: options[:llm_model]
+        )
+      end
+
+      def default_linter(config)
+        client = Llm::Client.new(base_url: config.base_url, api_key: config.api_key, model: config.model)
+        Slidict::Lint::Linter.new(client: client)
+      end
+
+      def format_for(options)
+        return options[:format] if options[:format]
+
+        ASCIIDOC_EXTENSIONS.include?(File.extname(options[:path]).downcase) ? "asciidoc" : "markdown"
+      end
+
+      def print_findings(findings)
+        @output.puts(findings.empty? ? "No issues found." : @renderer.render(findings))
+        0
+      end
+
+      def file_not_found(path)
+        @output.puts "Error: file not found: #{path}"
+        1
+      end
+
+      def llm_required
+        @output.puts "Error: lint requires an LLM endpoint (--llm-base-url or SLIDICT_LLM_BASE_URL)"
+        1
+      end
+
+      def print_help
+        @output.puts <<~HELP
+          Usage: slidict lint <file> [options]
+          Diagnoses whether a slide deck's structure will land with its audience.
+              --format FORMAT     markdown or asciidoc (default: auto-detected from extension)
+              --llm-base-url URL  OpenAI Compatible API base URL (env: SLIDICT_LLM_BASE_URL)
+              --llm-api-key KEY   API key for the LLM endpoint (env: SLIDICT_LLM_API_KEY)
+              --llm-model NAME    Model name to request (env: SLIDICT_LLM_MODEL, default: gpt-4o-mini)
+          -h, --help               Show this help
+        HELP
+        0
+      end
+    end
+  end
+end

data/lib/slidict/cli/serve.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "erb"
+require "pathname"
+
+module Slidict
+  module Cli
+    class Serve
+      DEFAULT_PUBLIC_DIR = "public"
+
+      def initialize(public_dir: DEFAULT_PUBLIC_DIR, output: $stdout)
+        @public_dir = File.expand_path(public_dir)
+        @output = output
+      end
+
+      def run(args = [])
+        app = build_app
+        original_argv = ARGV.dup
+        ARGV.replace(args)
+        @output.puts "Serving slides from #{@public_dir}"
+        app.run!
+        0
+      ensure
+        ARGV.replace(original_argv) if original_argv
+      end
+
+      private
+
+      def build_app
+        require "sinatra/base"
+
+        public_dir = @public_dir
+
+        Class.new(Sinatra::Base) do
+          set :public_folder, public_dir
+          set :static, true
+          set :show_exceptions, false
+
+          get "/" do
+            @public_dir = public_dir
+            @entries = slide_entries(public_dir)
+            erb INDEX_TEMPLATE
+          end
+
+          helpers do
+            def slide_entries(public_dir)
+              return [] unless Dir.exist?(public_dir)
+
+              Dir.glob(File.join(public_dir, "**", "*")).filter_map do |path|
+                next unless File.file?(path)
+
+                relative = Pathname.new(path).relative_path_from(Pathname.new(public_dir)).to_s
+                next unless slide_file?(relative)
+
+                { title: title_for(relative), href: "/#{escape_path(relative)}", path: relative }
+              end.sort_by { |entry| entry[:path] }
+            end
+
+            def slide_file?(path)
+              File.extname(path).match?(/\A\.(?:adoc|md|markdown)\z/i)
+            end
+
+            def title_for(path)
+              dirname = File.dirname(path)
+              basename = File.basename(path, File.extname(path))
+              dirname == "." ? basename : dirname
+            end
+
+            def escape_path(path)
+              # CGI.escape turns spaces into "+", which Rack's static file
+              # routing does not unescape back to a literal space. Percent-encode
+              # each segment instead so hrefs match the file on disk.
+              path.split("/").map { |segment| ERB::Util.url_encode(segment) }.join("/")
+            end
+
+            def h(text)
+              CGI.escapeHTML(text.to_s)
+            end
+          end
+        end
+      end
+
+      INDEX_TEMPLATE = <<~ERB.freeze
+        <!doctype html>
+        <html lang="en">
+          <head>
+            <meta charset="utf-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1">
+            <title>Slidict slides</title>
+            <style>
+              body { font-family: system-ui, sans-serif; margin: 2rem; }
+              li { margin: 0.5rem 0; }
+              code { color: #555; }
+            </style>
+          </head>
+          <body>
+            <h1>Slidict slides</h1>
+            <% if @entries.empty? %>
+              <p>No slides found in <code><%= h(@public_dir) %></code>.</p>
+            <% else %>
+              <ul>
+                <% @entries.each do |entry| %>
+                  <li><a href="<%= entry[:href] %>"><%= h(entry[:title]) %></a> <code><%= h(entry[:path]) %></code></li>
+                <% end %>
+              </ul>
+            <% end %>
+          </body>
+        </html>
+      ERB
+    end
+  end
+end

data/lib/slidict/cli/slides.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module Slidict
+  module Cli
+    # Implements the `slidict slides <list|show|create|edit>` subcommands.
+    class Slides
+      def initialize(output:, credentials: nil, client: nil, reauthenticate: nil)
+        @output = output
+        @credentials = credentials || External::SlidictIo::Credentials.new
+        @client = client
+        @reauthenticate = reauthenticate
+      end
+
+      def run(argv)
+        options = parse(argv)
+        return print_help if options[:help] || options[:subcommand].nil?
+
+        send(options[:subcommand], options)
+      rescue ArgumentError => e
+        @output.puts "Error: #{e.message}"
+        @output.puts
+        print_help
+        1
+      end
+
+      # Creates or edits a draft directly, bypassing argv parsing (and its
+      # "looks like a flag" checks, which would reject body text such as
+      # YAML frontmatter that happens to start with "-").
+      def publish(body:, id: nil, title: nil, body_format: nil, visibility: nil)
+        options = { id: id, title: title, body: body, body_format: body_format, visibility: visibility }
+        id ? edit(options) : create(options)
+      end
+
+      private
+
+      def parse(argv)
+        args = argv.dup
+        subcommand = args.shift
+        return { help: true } if subcommand.nil? || %w[-h --help].include?(subcommand)
+
+        case subcommand
+        when "list" then parse_list(args)
+        when "show" then parse_show(args)
+        when "create" then parse_create(args)
+        when "edit" then parse_edit(args)
+        else raise ArgumentError, "unknown slides command #{subcommand}"
+        end
+      end
+
+      def parse_list(args)
+        options = { subcommand: :list }
+        until args.empty?
+          case (arg = args.shift)
+          when "--page" then options[:page] = Integer(fetch_value!(args, arg))
+          when "-h", "--help" then options[:help] = true
+          else raise ArgumentError, "unknown option #{arg}"
+          end
+        end
+        options
+      end
+
+      def parse_show(args)
+        id = args.shift
+        raise ArgumentError, "show requires a slide id" if id.nil?
+        raise ArgumentError, "unknown option #{args.first}" unless args.empty?
+
+        { subcommand: :show, id: id }
+      end
+
+      def parse_create(args)
+        options = { subcommand: :create }
+        parse_body_options!(args, options)
+        options
+      end
+
+      def parse_edit(args)
+        id = args.shift
+        raise ArgumentError, "edit requires a slide id" if id.nil?
+
+        options = { subcommand: :edit, id: id }
+        parse_body_options!(args, options)
+        options
+      end
+
+      def parse_body_options!(args, options)
+        until args.empty?
+          case (arg = args.shift)
+          when "--title" then options[:title] = fetch_value!(args, arg)
+          when "--body" then options[:body] = fetch_value!(args, arg)
+          when "--file" then options[:file] = fetch_value!(args, arg)
+          when "--body-format" then options[:body_format] = fetch_value!(args, arg)
+          when "--visibility" then options[:visibility] = fetch_value!(args, arg)
+          when "-h", "--help" then options[:help] = true
+          else raise ArgumentError, "unknown option #{arg}"
+          end
+        end
+        raise ArgumentError, "specify only one of --body or --file" if options[:body] && options[:file]
+      end
+
+      # Does not reject values starting with "-": body text or titles may
+      # legitimately start with a dash (e.g. YAML frontmatter), and a genuinely
+      # missing value still surfaces as an "unknown option" error from the
+      # next iteration of the parse loop, or a nil check below.
+      def fetch_value!(args, option)
+        value = args.shift
+        raise ArgumentError, "#{option} requires a value" if value.nil?
+
+        value
+      end
+
+      def list(options)
+        with_reauth_retry do
+          print_slide_list(client.list(page: options[:page]))
+          0
+        end
+      end
+
+      def show(options)
+        with_reauth_retry do
+          print_slide_detail(client.show(options[:id]))
+          0
+        rescue External::SlidictIo::Client::NotFound
+          @output.puts "Error: slide not found"
+          1
+        end
+      end
+
+      def create(options)
+        body = read_body(options)
+        raise ArgumentError, "create requires --body or --file" if body.to_s.strip.empty?
+
+        submit("Created") do
+          client.create(title: options[:title], body: body, body_format: options[:body_format],
+                        visibility: options[:visibility])
+        end
+      end
+
+      def edit(options)
+        submit("Updated") do
+          client.update(options[:id], title: options[:title], body: read_body(options),
+                                      body_format: options[:body_format], visibility: options[:visibility])
+        end
+      end
+
+      def submit(verb)
+        with_reauth_retry do
+          slide = yield
+          @output.puts "#{verb} slide ##{slide["id"]} (draft)"
+          print_slide_detail(slide)
+          0
+        rescue External::SlidictIo::Client::NotFound
+          @output.puts "Error: slide not found"
+          1
+        rescue External::SlidictIo::Client::NotEditable
+          @output.puts "Error: this slide is already published. Edit it from the Web UI instead."
+          1
+        rescue External::SlidictIo::Client::RateLimited
+          print_rate_limited
+        rescue External::SlidictIo::Client::Unprocessable => e
+          print_unprocessable(e)
+        end
+      end
+
+      # Shared by list/show/submit: on a 401 from an expired/invalid token,
+      # silently re-authenticate once (via the injected reauthenticate flow)
+      # and retry the same request before giving up.
+      def with_reauth_retry
+        reauthenticated = false
+        begin
+          yield
+        rescue External::SlidictIo::Client::Unauthorized => e
+          if !reauthenticated && reauthenticate!
+            reauthenticated = true
+            retry
+          end
+          print_client_error(e)
+        rescue External::SlidictIo::Client::Error => e
+          print_client_error(e)
+        end
+      end
+
+      def read_body(options)
+        return options[:body] unless options[:file]
+
+        File.read(options[:file])
+      rescue Errno::ENOENT, Errno::EACCES => e
+        raise ArgumentError, "could not read #{options[:file]}: #{e.message}"
+      end
+
+      def client
+        @client ||= begin
+          token = @credentials.read_cli_token
+          token = @credentials.read_cli_token if token.nil? && reauthenticate!
+          raise ArgumentError, "not authenticated. Run `slidict auth` first." unless token
+
+          External::SlidictIo::Client.new(access_token: token[:access_token], token_type: token[:token_type])
+        end
+      end
+
+      # Triggers the injected login flow (see Slidict::Cli::App#auth) and clears the
+      # memoized client so the next call to `client` picks up the fresh token.
+      def reauthenticate!
+        return false unless @reauthenticate
+
+        @client = nil
+        @reauthenticate.call.zero?
+      end
+
+      def print_slide_list(result)
+        slides = result["slides"] || []
+        if slides.empty?
+          @output.puts "No slides found."
+          return
+        end
+
+        slides.each do |slide|
+          @output.puts "##{slide["id"]} [#{slide["status"]}/#{slide["visibility"]}] " \
+                       "#{slide["title"]} (updated_at: #{slide["updated_at"]})"
+        end
+        @output.puts "(more slides available, use --page to see the next page)" if result["has_more"]
+      end
+
+      def print_slide_detail(slide)
+        @output.puts "##{slide["id"]} #{slide["title"]}"
+        @output.puts "status: #{slide["status"]}  visibility: #{slide["visibility"]}  " \
+                     "updated_at: #{slide["updated_at"]}"
+        @output.puts
+        @output.puts slide["body"]
+      end
+
+      def print_rate_limited
+        @output.puts "Error: rate limited. Create/edit is limited to once per minute. Wait and try again."
+        1
+      end
+
+      def print_unprocessable(error)
+        @output.puts "Error: #{error.message}"
+        error.errors.each { |message| @output.puts "  - #{message}" }
+        1
+      end
+
+      def print_client_error(error)
+        @output.puts "Error: #{error.message}"
+        1
+      end
+
+      def print_help
+        @output.puts <<~HELP
+          Usage: slidict slides <command> [options]
+
+          Commands:
+            list [--page N]      List your slides (20 per page)
+            show <id>             Show a slide's details and body
+            create [options]      Create a new draft slide
+            edit <id> [options]   Edit an existing draft slide
+
+          Create/edit options:
+              --title TEXT         Slide title
+              --body TEXT          Slide body text
+              --file PATH          Read the slide body from a file (instead of --body)
+              --body-format FORMAT asciidoc or markdown (default: auto-detected from body)
+              --visibility VIS     public, unlisted, or group_only (default: public)
+          -h, --help                Show this help
+
+          Note: slides are always created/edited as drafts. Publish from the Web UI.
+        HELP
+        0
+      end
+    end
+  end
+end

data/lib/slidict/external/slidict_io/auth.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Slidict
+  module External
+    module SlidictIo
+      class Auth
+        Error = Class.new(StandardError)
+        Pending = Class.new(StandardError)
+
+        DEFAULT_BASE_URL = "https://slidict.io"
+
+        attr_reader :base_url
+
+        def initialize(base_url: ENV.fetch("SLIDICT_AUTH_BASE_URL", DEFAULT_BASE_URL))
+          @base_url = base_url
+        end
+
+        def request_device_code
+          response = post_json("/api/cli/device/code", { provider: "github" })
+          {
+            device_code: fetch!(response, "device_code"),
+            user_code: fetch!(response, "user_code"),
+            verification_uri: response["verification_uri"] || "#{base_url}/cli/activate",
+            interval: response.fetch("interval", 5).to_i,
+            expires_in: response.fetch("expires_in", 600).to_i
+          }
+        end
+
+        def poll_token(device_code:)
+          response = post_json(
+            "/api/cli/device/token",
+            { device_code: device_code, grant_type: "urn:ietf:params:oauth:grant-type:device_code" },
+            raise_on_http_error: false
+          )
+          return response if response["access_token"]
+
+          error = response["error"].to_s
+          raise Pending if %w[authorization_pending slow_down].include?(error)
+
+          raise Error, response["error_description"] || error unless error.empty?
+
+          raise Error, "token response did not include access_token"
+        end
+
+        private
+
+        def post_json(path, payload, raise_on_http_error: true)
+          uri = URI.join(base_url, path)
+          request = Net::HTTP::Post.new(uri)
+          request["Accept"] = "application/json"
+          request["Content-Type"] = "application/json"
+          request.body = JSON.generate(payload)
+
+          response = Net::HTTP.start(uri.hostname, uri.port,
+                                     use_ssl: uri.scheme == "https", open_timeout: 5, read_timeout: 30) do |http|
+            http.request(request)
+          end
+          body = response.body.to_s.empty? ? {} : JSON.parse(response.body)
+          return body if response.is_a?(Net::HTTPSuccess) || !raise_on_http_error
+
+          raise Error, body["error_description"] || body["error"] || "HTTP #{response.code}"
+        rescue JSON::ParserError => e
+          raise Error, "invalid JSON response: #{e.message}"
+        rescue SystemCallError, Timeout::Error => e
+          raise Error, e.message
+        end
+
+        def fetch!(hash, key)
+          hash.fetch(key)
+        rescue KeyError
+          raise Error, "device code response did not include #{key}"
+        end
+      end
+    end
+  end
+end