slidict 0.1.9 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbc5e790dd61153be274e56924cf62275c6f7faecc62fadeb1be61112d2b7c22
-  data.tar.gz: 0a1af3694e1bce28b2f21a4d0898fad0034ff6fe3460b9d53e18236668a5b4f4
+  metadata.gz: a58f7f50da42dd170f4f479e90d30f750bfa7e09edc7175b567c34f0637e9d37
+  data.tar.gz: f61880e7f032400e945e5174abae17e15077b0439b352b90af8df2937cf6df9e
 SHA512:
-  metadata.gz: 7f037d810c7174a44b83f83666d186377edc3171d76bbc130f555f856252976065e752e9a44212369bbe08a2354480305ece22b1962851962366137416ef3f60
-  data.tar.gz: 141a0c3e8b00c02f35519b293be29b5033ed61ea75959f25a788c6da977d31907c78470a7fba99f7cc8adcf508880e86f90f4e20cde36da21db6d249690e6eff
+  metadata.gz: 30f98a358a929f7cd6048f3862183bf8a20c901ea6b6c86a3492865b4abbbdf64de140939c6c754168d4645b66e074788fdbf7a669c1176c7d5e9445b2e4edcd
+  data.tar.gz: d89395639ce333ec905175788aa44da292951560d230529d34f0c1be01b2091a9fc827e4986dff8f02cb07535c0d36562bdc9b05704f13cf6da623f16e532b5c

data/AGENTS.md

@@ -0,0 +1,41 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## Project overview
+
+Slidict is a Ruby CLI gem that turns conversational input into presentation
+source files (Slidev, Marp, Asciidoctor Reveal.js, etc.) via an
+OpenAI-compatible chat API.
+
+## Setup
+
+- Ruby 3.1+
+- Install dependencies: `bundle install`
+
+## Development workflow
+
+- Run tests: `bundle exec rspec`
+- Run lint: `bundle exec rubocop`
+- Run the CLI locally: `bin/slidict`
+
+Run both tests and lint before considering a change complete.
+
+When you add or change a CLI command (or its options), update the "Commands" section
+of `README.md` to document it.
+
+## Commit conventions
+
+Use Conventional Commits for every commit message: `<type>: <summary>`.
+
+Common types used in this repo:
+
+- `feat:` new functionality
+- `fix:` bug fixes
+- `chore:` maintenance, version bumps, dependency updates
+- `ci:` CI/workflow changes
+- `docs:` documentation only changes
+- `refactor:` code change that neither fixes a bug nor adds a feature
+- `test:` adding or correcting tests
+
+Keep the summary short and in the imperative mood (e.g. `fix: handle empty topic input`).

data/README.md

@@ -11,6 +11,7 @@ Unlike traditional slide generators, Slidict focuses on communication before sli
 - Interactive CLI conversation
 - Generate slides for Slidev, Marp, Asciidoctor Reveal.js, and other OSS presentation frameworks
 - Local-first MVP implemented in Ruby
+- Built-in Sinatra server for browsing generated slides from `public/`
 - OpenAI Compatible API support, so you can point Slidict at OpenAI, Ollama, LM Studio, vLLM, or any other server implementing the same `/chat/completions` endpoint
 
 ## Requirements
@@ -28,7 +29,7 @@ bin/slidict
 Slidict asks a few questions and generates presentation source files. For example, this creates a Marp Markdown deck:
 
 ```bash
-$ bin/slidict --framework marp --output slides.md
+$ bin/slidict --framework marp
 
 What would you like to talk about?
 > PDF Difference Monitoring Service
@@ -38,7 +39,7 @@ Who is the audience?
 > Engineering managers
 What should the audience remember or do?
 > Approve an MVP pilot
-Created slides.md
+Created public/001.md
 ```
 
 You can also provide answers non-interactively:
@@ -53,16 +54,79 @@ bin/slidict \
   --output slides.adoc
 ```
 
+Add `--publish` to also save the generated slides to slidict.io as a draft (requires
+`slidict auth` first). Pass `--slide-id` to edit an existing draft instead of creating a
+new one:
+
+```bash
+# Create a new draft on slidict.io from the generated slides
+bin/slidict --topic "PDF Difference Monitoring Service" --duration "5 minutes" \
+  --audience "Engineering managers" --goal "Approve an MVP pilot" --publish
+
+# Edit an existing draft (slide #42) instead of creating a new one
+bin/slidict --topic "PDF Difference Monitoring Service" --duration "5 minutes" \
+  --audience "Engineering managers" --goal "Approve an MVP pilot" --slide-id 42
+```
+
 ## Output files
 
-Choose the framework and output path that match the presentation tool you want to use. If you omit `--output`, Slidict chooses a framework-specific default:
+Choose the framework and output path that match the presentation tool you want to use. If you omit `--output`, Slidict writes under `public/` with the next sequential file name. Use `--filename` to choose the relative file name under `public/`; Slidict appends the framework extension when the name has no extension.
+
+```bash
+# Choose a served file name under public/
+bin/slidict --filename product-demo/slides --topic "Product Demo"
+```
 
 ```text
-Slidev                  -> slides.md
-Marp                    -> slides.md
-Asciidoctor Reveal.js   -> slides.adoc
+Slidev                  -> public/001.md, public/002.md, ...
+Marp                    -> public/001.md, public/002.md, ...
+Asciidoctor Reveal.js   -> public/001.adoc, public/002.adoc, ...
 ```
 
+## Commands
+
+### `slidict auth`
+
+Authenticates the CLI with your GitHub account via the device code flow and saves a
+CLI access token to `~/.config/slidict/credentials.json`.
+
+```bash
+bin/slidict auth
+```
+
+### `slidict slides`
+
+Manage your slides on slidict.io using the CLI access token saved by `slidict auth`.
+
+```bash
+bin/slidict slides list [--page N]
+bin/slidict slides show <id>
+bin/slidict slides create [--title TEXT] [--body TEXT | --file PATH] [--body-format asciidoc|markdown] [--visibility public|unlisted|group_only]
+bin/slidict slides edit <id> [--title TEXT] [--body TEXT | --file PATH] [--body-format asciidoc|markdown] [--visibility public|unlisted|group_only]
+```
+
+- `create` and `edit` always save the slide as a draft. Publishing requires going through
+  the moderation flow on the Web UI; the CLI cannot publish a slide.
+- `edit` only works on slides that are still drafts; editing an already-published slide
+  must be done from the Web UI.
+- `create`/`edit` are rate limited to once per minute per user.
+
+Run `bin/slidict slides -h` for the full list of options.
+
+### `slidict serve`
+
+Serve generated slide files from the local `public/` directory with Sinatra. The top
+page lists Markdown and Asciidoc slide files below `public/`, so you can organize
+decks in subdirectories such as `public/product-demo/slides.md`. Any arguments
+after `serve` are passed through to Sinatra.
+
+```bash
+bin/slidict serve -p 4567 -o 0.0.0.0
+```
+
+`bin/slidict --publish` and `--slide-id` (see [Usage](#usage)) wrap this same `create`/`edit`
+behavior so you can save the slides you just generated straight to slidict.io.
+
 ## Configuration
 
 Slidict generates slides with an LLM through any OpenAI Compatible API. Configure the

data/lib/slidict/cli/app.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module Slidict
+  module Cli
+    class App
+      def initialize(input: $stdin, output: $stdout, renderer: Output::Renderer.new, auth_client: nil,
+                     credentials: nil, sleeper: Kernel, slides_command: nil, server: nil)
+        @input = input
+        @output = output
+        @renderer = renderer
+        @auth_client = auth_client
+        @credentials = credentials
+        @sleeper = sleeper
+        @slides_command = slides_command
+        @server = server
+      end
+
+      def run(argv = [])
+        options = parse(argv)
+        return print_help if options[:help]
+        return auth if options[:command] == "auth"
+        return slides(options[:args]) if options[:command] == "slides"
+        return serve(options[:args]) if options[:command] == "serve"
+
+        config = build_config(options)
+        client = llm_client_for(config)
+        return 1 if client && !verify_connection(client)
+
+        deck = Deck.new(
+          topic: ask("What would you like to talk about?", options[:topic]),
+          duration: ask("How long is the presentation?", options[:duration]),
+          audience: ask("Who is the audience?", options[:audience]),
+          goal: ask("What should the audience remember or do?", options[:goal]),
+          framework: options[:framework]
+        )
+
+        if client
+          begin
+            slides = client.generate_slides(deck)
+          rescue Llm::Client::Error => e
+            @output.puts "Error: LLM request failed (#{e.message})"
+            return 1
+          end
+          deck = Deck.new(
+            topic: deck.topic, duration: deck.duration, audience: deck.audience, goal: deck.goal,
+            framework: deck.framework, slides: slides
+          )
+        end
+
+        path = options[:output]
+        content = @renderer.render(deck)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, content)
+        @output.puts "Created #{path}"
+
+        return publish_to_slidict(deck, content, options) if options[:publish] || options[:slide_id]
+
+        0
+      rescue ArgumentError => e
+        @output.puts "Error: #{e.message}"
+        @output.puts
+        print_help
+        1
+      end
+
+      private
+
+      def parse(argv)
+        options = { framework: "slidev" }
+        args = argv.dup
+
+        if args.first == "auth"
+          args.shift
+          raise ArgumentError, "auth does not accept options" unless args.empty?
+
+          options[:command] = "auth"
+          return options
+        end
+
+        if args.first == "slides"
+          args.shift
+          options[:command] = "slides"
+          options[:args] = args
+          return options
+        end
+
+        if args.first == "serve"
+          args.shift
+          options[:command] = "serve"
+          options[:args] = args
+          return options
+        end
+
+        until args.empty?
+          case (arg = args.shift)
+          when "-h", "--help"
+            options[:help] = true
+          when "-o", "--output"
+            options[:output] = fetch_value!(args, arg)
+          when "--filename"
+            options[:filename] = fetch_value!(args, arg)
+          when "--topic"
+            options[:topic] = fetch_value!(args, arg)
+          when "--duration"
+            options[:duration] = fetch_value!(args, arg)
+          when "--audience"
+            options[:audience] = fetch_value!(args, arg)
+          when "--goal"
+            options[:goal] = fetch_value!(args, arg)
+          when "--framework"
+            options[:framework] = fetch_value!(args, arg)
+          when "--llm-base-url"
+            options[:llm_base_url] = fetch_value!(args, arg)
+          when "--llm-api-key"
+            options[:llm_api_key] = fetch_value!(args, arg)
+          when "--llm-model"
+            options[:llm_model] = fetch_value!(args, arg)
+          when "--no-llm"
+            options[:no_llm] = true
+          when "--publish"
+            options[:publish] = true
+          when "--slide-id"
+            options[:slide_id] = fetch_value!(args, arg)
+          when "--slide-title"
+            options[:slide_title] = fetch_value!(args, arg)
+          when "--visibility"
+            options[:visibility] = fetch_value!(args, arg)
+          else
+            raise ArgumentError, "unknown option #{arg}"
+          end
+        end
+
+        options[:output] ||= output_path_for(options[:framework], options[:filename])
+        options
+      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],
+          enabled: options[:no_llm] ? false : nil
+        )
+      end
+
+      def llm_client_for(config)
+        return nil unless config.llm_enabled?
+
+        Llm::Client.new(base_url: config.base_url, api_key: config.api_key, model: config.model)
+      end
+
+      def verify_connection(client)
+        client.verify_connection!
+        true
+      rescue Llm::Client::Error => e
+        @output.puts "Error: LLM request failed (#{e.message})"
+        false
+      end
+
+      def auth
+        client = @auth_client || External::SlidictIo::Auth.new
+        credentials = @credentials || External::SlidictIo::Credentials.new
+
+        device = client.request_device_code
+        @output.puts "1. Open #{device[:verification_uri]} in your browser"
+        @output.puts "2. Enter code: #{device[:user_code]}"
+        @output.puts "3. Log in with GitHub"
+        @output.puts "Waiting for GitHub authentication..."
+
+        deadline = Time.now + device[:expires_in]
+        loop do
+          token = client.poll_token(device_code: device[:device_code])
+          path = credentials.write_cli_token!(
+            access_token: token.fetch("access_token"),
+            token_type: token.fetch("token_type", "Bearer"),
+            provider: token.fetch("provider", "github")
+          )
+          @output.puts "4. Saved CLI access token to #{path}"
+          return 0
+        rescue External::SlidictIo::Auth::Pending
+          return login_expired if Time.now >= deadline
+
+          @sleeper.sleep(device[:interval])
+        end
+      rescue External::SlidictIo::Auth::Error, KeyError => e
+        @output.puts "Error: GitHub auth failed (#{e.message})"
+        1
+      end
+
+      def slides(args)
+        slides_command.run(args)
+      end
+
+      def serve(args)
+        server.run(args)
+      end
+
+      def publish_to_slidict(deck, content, options)
+        slides_command.publish(
+          id: options[:slide_id],
+          title: options[:slide_title] || deck.topic,
+          body: content,
+          body_format: body_format_for(deck.framework),
+          visibility: options[:visibility]
+        )
+      end
+
+      def slides_command
+        @slides_command ||= Slides.new(output: @output, credentials: @credentials, reauthenticate: method(:auth))
+      end
+
+      def server
+        @server ||= Serve.new(output: @output)
+      end
+
+      def body_format_for(framework)
+        Output::Format.fetch(framework).body_format
+      end
+
+      def login_expired
+        @output.puts "Error: GitHub auth timed out. Run `slidict auth` and try again."
+        1
+      end
+
+      def fetch_value!(args, option)
+        value = args.shift
+        raise ArgumentError, "#{option} requires a value" if value.nil? || value.start_with?("-")
+
+        value
+      end
+
+      def ask(question, provided)
+        return provided unless provided.nil? || provided.strip.empty?
+
+        @output.puts question
+        @output.print "> "
+        @input.gets&.chomp.to_s
+      end
+
+      def print_help
+        @output.puts <<~HELP
+          Usage: slidict [options]
+          Usage: slidict auth
+          Usage: slidict slides <list|show|create|edit> [options]
+          Usage: slidict serve [sinatra options]
+
+          Generate presentation source files from a short conversation.
+
+          Commands:
+            auth             Authenticate the CLI with GitHub and save a CLI access token
+            slides           Manage your slides on slidict.io (run `slidict slides -h` for details)
+            serve            Serve slide files from ./public with Sinatra
+
+          Options:
+              --topic TEXT       Presentation topic
+              --duration TEXT    Presentation length, for example "5 minutes"
+              --audience TEXT    Target audience
+              --goal TEXT        Desired audience takeaway or action
+              --framework NAME   #{Output::Format.names.join(", ")} (default: slidev)
+              --filename NAME    File name under public/ (default: next sequential file)
+              --llm-base-url URL OpenAI Compatible API base URL (env: SLIDICT_LLM_BASE_URL).
+                                 When omitted, the built-in slide template is used instead.
+              --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)
+              --no-llm           Skip the LLM call and use the built-in slide template
+              --publish          Publish the generated slides to slidict.io as a draft
+                                 (requires `slidict auth`; creates a new slide, or edits
+                                 an existing one when --slide-id is given)
+              --slide-id ID      Edit this existing draft instead of creating a new one
+                                 (implies --publish)
+              --slide-title TEXT Title for the published slide (default: --topic)
+              --visibility VIS   public, unlisted, or group_only (default: public)
+          -o, --output PATH      Output file (overrides --filename and the public/ default)
+          -h, --help             Show this help
+        HELP
+        0
+      end
+
+      def output_path_for(framework, filename)
+        return File.join("public", normalize_filename(filename, framework)) if filename
+
+        next_sequential_output_for(framework)
+      end
+
+      def normalize_filename(filename, framework)
+        path = filename.to_s.strip
+        raise ArgumentError, "--filename requires a relative path under public" if path.empty?
+        raise ArgumentError, "--filename must be relative" if Pathname.new(path).absolute?
+        raise ArgumentError, "--filename cannot include .." if Pathname.new(path).each_filename.any?("..")
+
+        # --filename is already relative to public/, so drop a redundant leading
+        # "public/" instead of nesting it twice (public/public/...).
+        path = path.delete_prefix("public/")
+        File.extname(path).empty? ? "#{path}#{default_extension_for(framework)}" : path
+      end
+
+      def next_sequential_output_for(framework)
+        extension = default_extension_for(framework)
+        number = 1
+        loop do
+          path = File.join("public", format("%03d%s", number, extension))
+          return path unless File.exist?(path)
+
+          number += 1
+        end
+      end
+
+      def default_extension_for(framework)
+        Output::Format.fetch(framework).extension
+      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