slidict 0.2.0 → 0.4.0

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Slidict
+  module External
+    module SlidictIo
+      # Talks to the slidict.io CLI slides API using a CLI access token
+      # (obtained via Slidict::External::SlidictIo::Auth / `slidict auth`).
+      class Client
+        class Error < StandardError; end
+        class Unauthorized < Error; end
+        class Forbidden < Error; end
+        class NotFound < Error; end
+        class NotEditable < Error; end
+        class RateLimited < Error; end
+
+        # Raised for 422 responses other than "not_editable", carrying the API's validation errors.
+        class Unprocessable < Error
+          attr_reader :errors
+
+          def initialize(message, errors: [])
+            super(message)
+            @errors = errors
+          end
+        end
+
+        DEFAULT_BASE_URL = "https://slidict.io"
+
+        attr_reader :base_url
+
+        def initialize(access_token:, token_type: "Bearer",
+                       base_url: ENV.fetch("SLIDICT_AUTH_BASE_URL", DEFAULT_BASE_URL))
+          @access_token = access_token
+          @token_type = token_type
+          @base_url = base_url
+        end
+
+        def list(page: nil)
+          get_json("/api/cli/slides", query: page ? { page: page } : {})
+        end
+
+        def show(id)
+          get_json("/api/cli/slides/#{id}")
+        end
+
+        def create(body:, title: nil, body_format: nil, visibility: nil)
+          post_json("/api/cli/slides",
+                    slide_payload(title: title, body: body, body_format: body_format, visibility: visibility))
+        end
+
+        def update(id, body: nil, title: nil, body_format: nil, visibility: nil)
+          patch_json("/api/cli/slides/#{id}",
+                     slide_payload(title: title, body: body, body_format: body_format, visibility: visibility))
+        end
+
+        private
+
+        def slide_payload(title:, body:, body_format:, visibility:)
+          { title: title, body: body, body_format: body_format, visibility: visibility }.compact
+        end
+
+        def get_json(path, query: {})
+          uri = URI.join(base_url, path)
+          uri.query = URI.encode_www_form(query) unless query.empty?
+          perform(uri, Net::HTTP::Get.new(uri))
+        end
+
+        def post_json(path, payload)
+          uri = URI.join(base_url, path)
+          perform(uri, build_request(Net::HTTP::Post.new(uri), payload))
+        end
+
+        def patch_json(path, payload)
+          uri = URI.join(base_url, path)
+          perform(uri, build_request(Net::HTTP::Patch.new(uri), payload))
+        end
+
+        def build_request(request, payload)
+          request["Content-Type"] = "application/json"
+          request.body = JSON.generate(payload)
+          request
+        end
+
+        def perform(uri, request)
+          request["Accept"] = "application/json"
+          request["Authorization"] = "#{@token_type} #{@access_token}"
+
+          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)
+          handle_response(response, body)
+        rescue JSON::ParserError => e
+          raise Error, "invalid JSON response: #{e.message}"
+        rescue SystemCallError, Timeout::Error => e
+          raise Error, e.message
+        end
+
+        ERROR_CLASSES_BY_STATUS = {
+          "401" => Unauthorized,
+          "403" => Forbidden,
+          "404" => NotFound,
+          "429" => RateLimited
+        }.freeze
+
+        def handle_response(response, body)
+          return body if response.is_a?(Net::HTTPSuccess)
+          return raise_unprocessable(body) if response.code == "422"
+
+          error_class = ERROR_CLASSES_BY_STATUS.fetch(response.code, Error)
+          raise error_class, body["error_description"] || body["error"] || "HTTP #{response.code}"
+        end
+
+        def raise_unprocessable(body)
+          raise NotEditable, "not_editable" if body["error"] == "not_editable"
+
+          raise Unprocessable.new(body["error"] || "unprocessable", errors: Array(body["errors"]))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Slidict
+  module External
+    module SlidictIo
+      class Credentials
+        DEFAULT_PATH = File.expand_path("~/.config/slidict/credentials.json")
+
+        def initialize(path: DEFAULT_PATH)
+          @path = path
+        end
+
+        def write_cli_token!(access_token:, token_type: "Bearer", provider: "github")
+          FileUtils.mkdir_p(File.dirname(@path), mode: 0o700)
+          json = JSON.pretty_generate(
+            "access_token" => access_token,
+            "token_type" => token_type,
+            "provider" => provider,
+            "kind" => "cli_access_token"
+          )
+          File.write(@path, "#{json}\n", mode: "w", perm: 0o600)
+          File.chmod(0o600, @path)
+          @path
+        end
+
+        # Returns { access_token:, token_type: } or nil if no CLI access token is saved.
+        def read_cli_token
+          return nil unless File.exist?(@path)
+
+          data = JSON.parse(File.read(@path))
+          return nil unless data["kind"] == "cli_access_token" && data["access_token"]
+
+          { access_token: data["access_token"], token_type: data.fetch("token_type", "Bearer") }
+        rescue JSON::ParserError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/slidict/lint/finding.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Slidict
+  module Lint
+    # A single diagnostic produced by the linter: which slide it concerns,
+    # how severe it is ("warning" blocks understanding, "info" is a
+    # suggestion), and the human-readable message to show the user.
+    Finding = Struct.new(:slide, :severity, :message, keyword_init: true)
+  end
+end

data/lib/slidict/lint/linter.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Slidict
+  module Lint
+    # Orchestrates a lint run: splits the raw deck source into slides and
+    # asks the LLM client to diagnose the presentation's structure.
+    class Linter
+      class Error < StandardError; end
+
+      def initialize(client:)
+        @client = client
+      end
+
+      def lint(content, format: "markdown")
+        slides = SlideParser.parse(content, format: format)
+        raise Error, "no slides found in the given file" if slides.empty?
+
+        @client.lint_slides(slides)
+      end
+    end
+  end
+end

data/lib/slidict/lint/renderer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Slidict
+  module Lint
+    # Formats findings as one line per finding:
+    #   [warning] Slide 3: this slide's main point is unclear
+    class Renderer
+      def render(findings)
+        findings.sort_by(&:slide).map { |finding| line_for(finding) }.join("\n")
+      end
+
+      private
+
+      def line_for(finding)
+        "[#{finding.severity}] Slide #{finding.slide}: #{finding.message}"
+      end
+    end
+  end
+end

data/lib/slidict/lint/slide_parser.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Slidict
+  module Lint
+    # Splits raw Markdown/Asciidoc slide source into one text block per
+    # slide, so the linter can refer to slides by number. Frontmatter
+    # (Markdown) and the document title/preamble (Asciidoc) are dropped
+    # since they are not slides a reader sees.
+    class SlideParser
+      MARKDOWN_SEPARATOR = /\A-{3,}\s*\z/
+      ASCIIDOC_SLIDE_HEADING = /\A==\s+/
+      MARKDOWN_HEADING = /\A#\s+/
+
+      def self.parse(content, format: "markdown")
+        format == "asciidoc" ? parse_asciidoc(content) : parse_markdown(content)
+      end
+
+      def self.parse_markdown(content)
+        blocks = split_lines(content, MARKDOWN_SEPARATOR)
+        blocks = blocks.drop(2) if content.lines.first&.match?(MARKDOWN_SEPARATOR)
+
+        if blocks.size <= 1
+          by_heading = split_lines(content, MARKDOWN_HEADING, keep_separator: true, drop_preamble: true)
+          blocks = by_heading unless by_heading.empty?
+        end
+
+        clean(blocks)
+      end
+      private_class_method :parse_markdown
+
+      def self.parse_asciidoc(content)
+        clean(split_lines(content, ASCIIDOC_SLIDE_HEADING, keep_separator: true, drop_preamble: true))
+      end
+      private_class_method :parse_asciidoc
+
+      # Splits `content` into blocks every time a line matches `separator`.
+      # With keep_separator: true the matching line starts a new block
+      # instead of being discarded (used for heading-based splitting).
+      # With drop_preamble: true, any lines before the first match are
+      # discarded rather than kept as a leading block.
+      def self.split_lines(content, separator, keep_separator: false, drop_preamble: false)
+        blocks = []
+        current = drop_preamble ? nil : []
+        content.each_line do |line|
+          current = append_line(blocks, current, line, separator, keep_separator)
+        end
+        blocks << current.join if current
+        blocks
+      end
+      private_class_method :split_lines
+
+      def self.append_line(blocks, current, line, separator, keep_separator)
+        return current << line if current && !line.match?(separator)
+
+        blocks << current.join if current
+        return current unless line.match?(separator)
+
+        keep_separator ? [line] : []
+      end
+      private_class_method :append_line
+
+      def self.clean(blocks)
+        blocks.map(&:strip).reject(&:empty?)
+      end
+      private_class_method :clean
+    end
+  end
+end

data/lib/slidict/llm/client.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Slidict
+  module Llm
+    # Talks to any OpenAI Compatible API (OpenAI, Ollama, LM Studio, vLLM, etc.)
+    # via the standard /chat/completions endpoint. Configure the target with
+    # Slidict::Config (base_url, api_key, model).
+    class Client
+      class Error < StandardError; end
+
+      def initialize(base_url:, api_key:, model:)
+        @base_url = base_url
+        @api_key = api_key
+        @model = model
+      end
+
+      # Checks that the endpoint is reachable before the (slower, more
+      # expensive) chat completion request is made. Raises Error on failure.
+      def verify_connection!
+        uri = endpoint_uri("models")
+        request = Net::HTTP::Get.new(uri)
+        request["Authorization"] = "Bearer #{@api_key}"
+        response = perform_request(uri, request)
+
+        raise Error, "#{response.code} #{response.message}" unless response.is_a?(Net::HTTPSuccess)
+      end
+
+      def generate_slides(deck)
+        content = chat_completion(prompt_for(deck))
+        slides_from(content)
+      end
+
+      # slide_texts is an array of slide bodies (1-indexed by position) as
+      # produced by Slidict::Lint::SlideParser. Returns an array of
+      # Slidict::Lint::Finding.
+      def lint_slides(slide_texts)
+        content = chat_completion(lint_prompt_for(slide_texts))
+        findings_from(content)
+      end
+
+      private
+
+      def prompt_for(deck)
+        <<~PROMPT
+          You are an assistant that designs presentation slide outlines.
+          Topic: #{deck.topic}
+          Duration: #{deck.duration}
+          Audience: #{deck.audience}
+          Goal: #{deck.goal}
+
+          Return exactly 5 slides as a JSON array. Each item must be an object with
+          a "title" string and a "bullets" array of 2-4 short strings.
+          Respond with the JSON array only: no commentary, no markdown code fences,
+          and no reasoning or thinking content before or after it.
+        PROMPT
+      end
+
+      LINT_PROMPT_TEMPLATE = <<~PROMPT
+        You are a presentation structure linter for tech talks and lightning talks.
+        Your goal is not to judge how the slides look, but to diagnose whether the
+        structure will actually land with an audience.
+
+        Evaluate the deck as a whole against these six checks:
+
+        1. Is the audience clear (who is this talk for)?
+        2. Can the overall point be stated in one sentence?
+        3. Does the deck flow background -> problem -> solution -> result/learning
+           (call out where the flow breaks down)?
+        4. Is any single slide overloaded with information?
+        5. Is jargon used without first explaining it?
+        6. Does the closing slide give the audience one concrete takeaway?
+
+        For each finding, name the single slide it relates to most. For deck-wide
+        findings (unclear audience, unclear thesis, etc.), point to the slide where
+        the problem is most visible, or slide 1 if you cannot tell.
+
+        Decide severity using these rules:
+        - warning: likely to block audience understanding (checks 1-5)
+        - info: a suggestion that would make things better (check 6, or minor polish)
+
+        Here is the slide content ("--- Slide N ---" marks each slide boundary):
+
+        %<numbered>s
+
+        Respond with a JSON array of findings only. Each item must be an object of
+        the form {"slide": <integer>, "severity": "warning" or "info", "message": "<one sentence>"}.
+
+        Do not include any commentary, markdown code fences, or text other than the
+        JSON array. Return an empty array [] if you find no issues.
+      PROMPT
+
+      def lint_prompt_for(slide_texts)
+        numbered = slide_texts.each_with_index.map { |text, i| "--- Slide #{i + 1} ---\n#{text}" }.join("\n\n")
+        format(LINT_PROMPT_TEMPLATE, numbered: numbered)
+      end
+
+      def findings_from(content)
+        parsed = JSON.parse(extract_json_array(content))
+        raise Error, "expected a JSON array of findings" unless parsed.is_a?(Array)
+
+        parsed.map { |item| finding_from(item) }
+      rescue JSON::ParserError, KeyError, ArgumentError, TypeError => e
+        raise Error, "could not parse model response: #{e.message}"
+      end
+
+      def finding_from(item)
+        Lint::Finding.new(
+          slide: Integer(item.fetch("slide")),
+          severity: normalize_severity(item["severity"]),
+          message: item.fetch("message")
+        )
+      end
+
+      def normalize_severity(value)
+        %w[warning info].include?(value) ? value : "info"
+      end
+
+      def chat_completion(prompt)
+        response = JSON.parse(post_chat_completion(prompt))
+        content = response.dig("choices", 0, "message", "content")
+        raise Error, "empty response from model" if content.to_s.strip.empty?
+
+        content
+      rescue JSON::ParserError => e
+        raise Error, "could not parse model response: #{e.message}"
+      end
+
+      def post_chat_completion(prompt)
+        uri = endpoint_uri("chat/completions")
+        request = build_request(uri, prompt)
+        response = perform_request(uri, request)
+
+        raise Error, "#{response.code} #{response.message}" unless response.is_a?(Net::HTTPSuccess)
+
+        response.body
+      end
+
+      def perform_request(uri, request)
+        Net::HTTP.start(uri.host, uri.port,
+                        use_ssl: uri.scheme == "https",
+                        open_timeout: 5,
+                        read_timeout: 30,
+                        write_timeout: 30) do |http|
+          http.request(request)
+        end
+      rescue StandardError => e
+        raise Error, e.message
+      end
+
+      def endpoint_uri(path)
+        base = @base_url.to_s.sub(%r{/+\z}, "")
+        URI.join("#{base}/", path)
+      end
+
+      def build_request(uri, prompt)
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        request["Authorization"] = "Bearer #{@api_key}"
+        request.body = JSON.generate(
+          model: @model,
+          messages: [{ role: "user", content: prompt }],
+          temperature: 0.7
+        )
+        request
+      end
+
+      def slides_from(content)
+        parsed = JSON.parse(extract_json_array(content))
+        raise Error, "expected a JSON array of slides" unless parsed.is_a?(Array)
+
+        parsed.map do |item|
+          Slide.new(title: item.fetch("title"), bullets: Array(item.fetch("bullets")))
+        end
+      rescue JSON::ParserError, KeyError => e
+        raise Error, "could not parse model response: #{e.message}"
+      end
+
+      # Some models (especially reasoning models served through LM Studio or
+      # Ollama) prepend or append thinking/reasoning text around the JSON
+      # answer instead of returning it verbatim, so the array is extracted from
+      # within the raw content rather than parsed as-is.
+      def extract_json_array(content)
+        content.enum_for(:scan, /\[/).each do
+          start = Regexp.last_match.begin(0)
+          candidate = json_array_from(content, start)
+          return candidate if candidate
+        end
+
+        raise Error, "no JSON array found in model response"
+      end
+
+      def json_array_from(content, start)
+        finish = start
+        while (finish = content.index("]", finish))
+          candidate = content[start..finish]
+          return candidate if parses_to_array?(candidate)
+
+          finish += 1
+        end
+        nil
+      end
+
+      def parses_to_array?(candidate)
+        JSON.parse(candidate).is_a?(Array)
+      rescue JSON::ParserError
+        false
+      end
+    end
+  end
+end

data/lib/slidict/output/format.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Slidict
+  module Output
+    # Single source of truth for everything that varies per output framework:
+    # the output file extension, the body_format sent to the slidict.io API,
+    # and (for markdown-based frameworks) the frontmatter block to render.
+    # Add a new framework by adding one entry to REGISTRY.
+    class Format
+      Definition = Struct.new(:name, :extension, :body_format, :frontmatter, keyword_init: true)
+
+      DEFAULT_NAME = "slidev"
+
+      REGISTRY = {
+        "slidev" => Definition.new(
+          name: "slidev",
+          extension: ".md",
+          body_format: "markdown",
+          frontmatter: "theme: default\nclass: text-center"
+        ),
+        "marp" => Definition.new(
+          name: "marp",
+          extension: ".md",
+          body_format: "markdown",
+          frontmatter: "marp: true\ntheme: default"
+        ),
+        "asciidoctor-revealjs" => Definition.new(
+          name: "asciidoctor-revealjs",
+          extension: ".adoc",
+          body_format: "asciidoc",
+          frontmatter: nil
+        )
+      }.freeze
+
+      def self.fetch(name)
+        REGISTRY.fetch(name.to_s.downcase, REGISTRY.fetch(DEFAULT_NAME))
+      end
+
+      def self.names
+        REGISTRY.keys
+      end
+    end
+  end
+end

data/lib/slidict/output/renderer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Slidict
+  module Output
+    class Renderer
+      def render(deck)
+        return render_asciidoctor_revealjs(deck) if Format.fetch(deck.framework).body_format == "asciidoc"
+
+        [frontmatter(deck.framework), deck.slides.map { |slide| render_slide(slide) }.join("\n---\n\n")].join("\n")
+      end
+
+      private
+
+      def frontmatter(framework)
+        body = Format.fetch(framework).frontmatter
+        "---\n#{body}\ngenerated: #{Time.now.utc.iso8601}\n---\n"
+      end
+
+      def render_slide(slide)
+        lines = ["# #{slide.title}", ""]
+        lines.concat(slide.bullets.map { |bullet| "- #{bullet}" })
+        lines.join("\n")
+      end
+
+      def render_asciidoctor_revealjs(deck)
+        lines = ["= #{deck.topic}", ":revealjs_theme: white", ":slidict_generated: #{Time.now.utc.iso8601}", ""]
+        lines.concat(deck.slides.flat_map { |slide| render_asciidoctor_slide(slide) })
+        lines.join("\n")
+      end
+
+      def render_asciidoctor_slide(slide)
+        ["== #{slide.title}", "", *slide.bullets.map { |bullet| "* #{bullet}" }, ""]
+      end
+    end
+  end
+end

data/lib/slidict/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Slidict
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/slidict.rb

@@ -2,15 +2,22 @@
 
 require "time"
 
-require_relative "slidict/auth_client"
-require_relative "slidict/cli"
+require_relative "slidict/cli/app"
+require_relative "slidict/cli/lint"
+require_relative "slidict/cli/serve"
+require_relative "slidict/cli/slides"
 require_relative "slidict/config"
-require_relative "slidict/credentials"
 require_relative "slidict/deck"
-require_relative "slidict/llm_client"
-require_relative "slidict/markdown_renderer"
-require_relative "slidict/slides_client"
-require_relative "slidict/slides_command"
+require_relative "slidict/external/slidict_io/auth"
+require_relative "slidict/external/slidict_io/client"
+require_relative "slidict/external/slidict_io/credentials"
+require_relative "slidict/lint/finding"
+require_relative "slidict/lint/linter"
+require_relative "slidict/lint/renderer"
+require_relative "slidict/lint/slide_parser"
+require_relative "slidict/llm/client"
+require_relative "slidict/output/format"
+require_relative "slidict/output/renderer"
 require_relative "slidict/version"
 
 module Slidict