slidict 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc62a4a9def18173cd4fa3c36a07b8113cbd952f3ecef69f25d31bdd8a0c2c29
-  data.tar.gz: b559163e5add314725911941fece8829b47cd79f801369a4735a5b62fb6aadfb
+  metadata.gz: a9f6b8851999b92437addc0186d6a047c1c8317145940987514df479e02fabc2
+  data.tar.gz: fb42f714400e77cbc97931d105cef01a8b54776c0ce67db152ce6ce475136caf
 SHA512:
-  metadata.gz: 7482973532b58361216b54dc6a45e81bee4bc39e65e9a26958c37c271cdcb97f5c915649ee26d88973f4e34f26a9a7eb2b56a0ad7224488bd87a739087201d25
-  data.tar.gz: 946075256cf69b70511aae347f2d6a15164f87aeb4bd0678ac329af8a367773c515aec5a09bc4cab52a42b475e4aff7ec26995cbb7fce8f191ee3c12accea668
+  metadata.gz: 88ad47ca34c0e2d7bcf99f118905ba3b7b7f8df571aa4e118080552659564bc2bb7d79d007c3c67a9dc4ebd291e415e6cf423f93299f013485856737e54f7e77
+  data.tar.gz: 781cd459d6c82e62a29bbc8702bea3c7f9d4125d78341e2b13723608ded41e9131af456b87dbfc61525dbc7ebab91da9729fc4465e3b852c0298a96f1e277223

data/.github/workflows/changelog.yml

@@ -5,36 +5,19 @@ on:
     branches:
       - main
 
+permissions:
+  contents: write
+  pull-requests: read
+
 jobs:
   changelog:
     runs-on: ubuntu-latest
 
     steps:
-      - name: Checkout Code
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-
-      - name: Extract version
-        id: version
-        run: |
-          version=$(grep -Eo "[0-9]+\.[0-9]+\.[0-9]+" lib/slidict/version.rb | head -n 1)
-          echo "version=v$version" >> $GITHUB_ENV
-          echo "VERSION_TAG=v$version" >> $GITHUB_ENV
-
-      - name: Check if version file changed
-        id: version_file
-        run: |
-          if git diff --name-only "${{ github.event.before }}" "${{ github.sha }}" | grep -qx "lib/slidict/version.rb"; then
-            echo "changed=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "changed=false" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Release with release-drafter
+      - name: Update draft release notes
         uses: release-drafter/release-drafter@v5
         with:
           config-name: release-drafter.yml
-          publish: ${{ steps.version_file.outputs.changed == 'true' }}
+          publish: false
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

data/.github/workflows/gem-push.yml

@@ -1,31 +1,51 @@
 name: Ruby Gem
 
 on:
-  push:
-    branches:
-      - main
-    paths:
-      - lib/slidict/version.rb
+  workflow_run:
+    workflows:
+      - Changelog
+    types:
+      - completed
 
 jobs:
   build:
     name: Build + Publish
     runs-on: ubuntu-latest
+    if: github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.head_branch == 'main'
     permissions:
-      contents: read
+      contents: write
       packages: write
 
     steps:
       - uses: actions/checkout@v3
         with:
+          ref: ${{ github.event.workflow_run.head_sha }}
           fetch-depth: 0
 
+      - name: Check if version file changed
+        id: version_file
+        run: |
+          if git diff --name-only HEAD~1 HEAD | grep -qx "lib/slidict/version.rb"; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Extract version
+        if: steps.version_file.outputs.changed == 'true'
+        id: version
+        run: |
+          version=$(grep -Eo "[0-9]+\.[0-9]+\.[0-9]+" lib/slidict/version.rb | head -n 1)
+          echo "tag=v$version" >> "$GITHUB_OUTPUT"
+
       - name: Set up Ruby 3.4
+        if: steps.version_file.outputs.changed == 'true'
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: 3.4.3
 
       - name: Publish to GPR
+        if: steps.version_file.outputs.changed == 'true'
         run: |
           mkdir -p $HOME/.gem
           touch $HOME/.gem/credentials
@@ -38,6 +58,7 @@ jobs:
           OWNER: ${{ github.repository_owner }}
 
       - name: Publish to RubyGems
+        if: steps.version_file.outputs.changed == 'true'
         run: |
           mkdir -p $HOME/.gem
           touch $HOME/.gem/credentials
@@ -47,3 +68,14 @@ jobs:
           gem push *.gem
         env:
           GEM_HOST_API_KEY: "${{ secrets.RUBYGEMS_AUTH_TOKEN }}"
+
+      - name: Publish release notes
+        if: steps.version_file.outputs.changed == 'true'
+        uses: release-drafter/release-drafter@v5
+        with:
+          config-name: release-drafter.yml
+          publish: true
+          tag: ${{ steps.version.outputs.tag }}
+          name: ${{ steps.version.outputs.tag }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

data/AGENTS.md

@@ -21,8 +21,8 @@ OpenAI-compatible chat API.
 
 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.
+When you add or change a feature (a CLI command, its options, or any other
+user-facing behavior), update `README.md` to document it.
 
 ## Commit conventions
 

data/README.md

@@ -11,7 +11,9 @@ 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
+- Presentation structure linter: checks whether a Markdown/Asciidoc deck's *structure* (not its looks) will land with an audience
 
 ## Requirements
 
@@ -28,7 +30,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 +40,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:
@@ -69,12 +71,17 @@ bin/slidict --topic "PDF Difference Monitoring Service" --duration "5 minutes" \
 
 ## 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
@@ -107,9 +114,48 @@ bin/slidict slides edit <id> [--title TEXT] [--body TEXT | --file PATH] [--body-
 
 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.
 
+### `slidict lint`
+
+Diagnoses whether a Markdown or Asciidoc slide deck has a structure an audience can
+actually follow -- not whether it looks nice. Diagnosis only; it does not rewrite the
+file. Requires an LLM endpoint (see [Configuration](#configuration)).
+
+```bash
+bin/slidict lint talk.md --llm-base-url http://localhost:11434/v1 --llm-api-key ollama --llm-model llama3
+```
+
+```text
+[warning] Slide 3: this slide's main point is unclear
+[warning] Slide 5: "MCP" is used without first explaining it
+[info] Slide 8: the closing slide is weak; consider adding a one-sentence takeaway for the audience
+```
+
+It checks six things across the whole deck:
+
+1. Is the audience clear?
+2. Can the overall point be stated in one sentence?
+3. Does the deck flow background → problem → solution → result/learning?
+4. Is any single slide overloaded with information?
+5. Is jargon used without first explaining it?
+6. Does the closing slide give the audience a concrete takeaway?
+
+The deck format (`markdown` or `asciidoc`) is auto-detected from the file extension;
+override it with `--format`. Run `bin/slidict lint -h` for the full list of options.
+
 ## Configuration
 
 Slidict generates slides with an LLM through any OpenAI Compatible API. Configure the
@@ -174,6 +220,7 @@ We optimize for communication, not decoration.
 - [x] Interactive CLI
 - [x] Slide generation
 - [x] OpenAI Compatible API support (configurable base URL, so Ollama, LM Studio, and other compatible servers work out of the box)
+- [x] Presentation structure linter (`slidict lint`)
 
 ## License
 

data/lib/slidict/cli/app.rb

@@ -0,0 +1,336 @@
+# 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, lint_command: nil)
+        @input = input
+        @output = output
+        @renderer = renderer
+        @auth_client = auth_client
+        @credentials = credentials
+        @sleeper = sleeper
+        @slides_command = slides_command
+        @server = server
+        @lint_command = lint_command
+      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"
+        return lint(options[:args]) if options[:command] == "lint"
+
+        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
+
+        if args.first == "lint"
+          args.shift
+          options[:command] = "lint"
+          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 lint(args)
+        lint_command.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 lint_command
+        @lint_command ||= Lint.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]
+          Usage: slidict lint <file> [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
+            lint             Check whether a slide deck's structure will land with its audience
+                             (run `slidict lint -h` for details)
+
+          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