slidict 0.5.2 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9219a4421ee2daa082652c0967bbc585fff8aadf8ba90becbee2d3293597252
-  data.tar.gz: e1d4fa02a468b3b51d28681168151983cf89464d1dfb9e309d3c8b2a5e56dbee
+  metadata.gz: bc5350820094f49312526c30c254f437edd49374ac0202ba99067637a70dd331
+  data.tar.gz: 130980c85ff4a85a0189b95fddc825ea30eeae131e1549d83e80cee1ae5ba392
 SHA512:
-  metadata.gz: b17f7f5c07ebb337c964e14a0884e2cd8502da2664cbe3d3f8553296596e3cbc40497c2b659fd494dd778effae1ce4c51b9b714266b6527fd2cbc9b233dd5fa9
-  data.tar.gz: 273809d25f6adf3551113f9bd2d7a7d664d3fb58a8e8bac1634dff46e4c41d0c873925537012c1b8c3f7f3e30af18a12b3a497a65835d83c1c4eebc8941d30b5
+  metadata.gz: d27d844ad6ed53f6d860fe92e8614fad35e19caa10a9e5395b4eb6640c314a0224b0c32a5de612f13cababc8e438f61c1d6103d5a5c3a8133e2021eb67be6f73
+  data.tar.gz: 241380442ea402ed968bbd7829ec8ec49446f70d7f80852d75248a829d041b09d7a9c62d9ead1341d49e6dd5beff152340c7766f822bd064c29a1e0c407fb200

data/AGENTS.md

@@ -10,7 +10,7 @@ OpenAI-compatible chat API.
 
 ## Setup
 
-- Ruby 3.1+
+- Ruby 3.2.0+
 - Install dependencies: `bundle install`
 
 ## Development workflow

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+- Add `slidict init` to create a `.env` file (for `SLIDICT_LLM_*`, `SLIDICT_FRAMEWORK`,
+  and `SLIDICT_METHOD`) and add it to `.gitignore`. `.env` is loaded automatically and
+  fills in unset environment variables; CLI flags still take precedence.
+- Add `SLIDICT_FRAMEWORK` and `SLIDICT_METHOD` environment variables as defaults for
+  `--framework` and `--method`.
+- Add `--language` to generate slide titles and bullets in a language other than English,
+  and to translate the interactive prompt questions into that language via the LLM.
+
 ## [0.5.0] - 2026-07-01
 
 - Add data-driven presentation methods with SCQA, PREP, and Pyramid Principle templates.

data/README.md

@@ -25,7 +25,7 @@ Unlike traditional slide generators, Slidict focuses on communication before sli
 
 ## Requirements
 
-- Ruby 3.1 or later
+- Ruby 3.2.0 or later
 
 ## Usage
 
@@ -94,6 +94,16 @@ Asciidoctor Reveal.js   -> public/001.adoc, public/002.adoc, ...
 
 ## Commands
 
+### `slidict init`
+
+Creates a `.env` file for `SLIDICT_LLM_*`, `SLIDICT_FRAMEWORK`, and `SLIDICT_METHOD`
+(see [Configuration](#configuration)) and adds `.env` to `.gitignore`. Does nothing to
+an existing `.env` or an already-updated `.gitignore`.
+
+```bash
+bin/slidict init
+```
+
 ### `slidict auth`
 
 Authenticates the CLI with your GitHub account via the device code flow and saves a
@@ -167,19 +177,55 @@ override it with `--format`. Run `bin/slidict lint -h` for the full list of opti
 ## Configuration
 
 Slidict generates slides with an LLM through any OpenAI Compatible API. Configure the
-target endpoint with environment variables or CLI flags (flags take precedence):
+target endpoint with environment variables, a `.env` file, or CLI flags:
 
 | Environment variable    | CLI flag         | Default        |
 | ------------------------ | ---------------- | -------------- |
 | `SLIDICT_LLM_BASE_URL`    | `--llm-base-url` | _(none)_       |
 | `SLIDICT_LLM_API_KEY`     | `--llm-api-key`  | _(none)_       |
 | `SLIDICT_LLM_MODEL`       | `--llm-model`    | `gpt-4o-mini`  |
+| `SLIDICT_FRAMEWORK`       | `--framework`    | `slidev`       |
+| `SLIDICT_METHOD`          | `--method`       | _(none)_       |
+
+Precedence is CLI flag > real environment variable > `.env` file > built-in default (a
+`.env` value fills in only variables that aren't already set in the environment). Run
+`slidict init` to create a `.env` file in the current directory (with these variables
+commented out) and add `.env` to `.gitignore`:
+
+```bash
+bin/slidict init
+```
+
+```text
+Created .env
+Added .env to .gitignore
+```
+
+Then edit `.env` to set the values you want, for example:
+
+```bash
+SLIDICT_LLM_BASE_URL=http://localhost:11434/v1
+SLIDICT_LLM_API_KEY=ollama
+SLIDICT_LLM_MODEL=llama3
+SLIDICT_FRAMEWORK=marp
+```
+
+Since `.env` is gitignored, it's a good place for secrets like API keys that
+shouldn't be committed. A CLI flag always overrides both `.env` and the real
+environment for that invocation.
 
 If no `llm-base-url` is configured, Slidict uses its built-in slide template and never
 calls an LLM. Once a `llm-base-url` is set, Slidict always calls that endpoint; if the
 request fails, Slidict reports the error and exits without writing a file (no fallback).
 You can force the template even when a base URL is configured with `--no-llm`.
 
+Use `--language LANG` (e.g. `--language Japanese`) to have the LLM write the generated
+slide titles and bullets in a language other than English. When an `llm-base-url` is
+also configured, Slidict asks the LLM to translate any interactive questions it still
+needs to ask (topic, duration, audience, goal) into that language too, so you're not
+answering Japanese-bound slides in English prompts. This only affects LLM-generated
+slides and questions; the built-in template stays in English.
+
 Examples:
 
 ```bash

data/lib/slidict/cli/app.rb

@@ -6,18 +6,58 @@ 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
+      include Options
+
+      # Keyed by the same symbols as the parsed CLI options (options[:topic],
+      # etc.), so a missing answer's question text can be looked up directly
+      # by `questions_for`.
+      QUESTIONS = {
+        topic: "What would you like to talk about?",
+        duration: "How long is the presentation?",
+        audience: "Who is the audience?",
+        goal: "What should the audience remember or do?"
+      }.freeze
+
+      options input: -> { $stdin },
+              output: -> { $stdout },
+              renderer: -> { Output::Renderer.new },
+              auth_client: -> { nil },
+              credentials: -> { nil },
+              sleeper: -> { Kernel },
+              slides_command: -> { nil },
+              server: -> { nil },
+              lint_command: -> { nil }
+
+      flag "--topic",        arg: "TEXT",  desc: "Presentation topic"
+      flag "--duration",     arg: "TEXT",  desc: 'Presentation length, for example "5 minutes"'
+      flag "--audience",     arg: "TEXT",  desc: "Target audience"
+      flag "--goal",         arg: "TEXT",  desc: "Desired audience takeaway or action"
+      flag "--framework",    arg: "NAME",
+                             desc: -> { "#{Output::Format.names.join(", ")} (default: slidev)\n(env: SLIDICT_FRAMEWORK)" }
+      flag "--method",       arg: "ID",    desc: "Presentation method, for example scqa, prep, or pyramid\n" \
+                                                  "(env: SLIDICT_METHOD)"
+      flag "--language",     arg: "LANG",  desc: "Generate slide titles and bullets in the given language\n" \
+                                                  "(e.g. Japanese); only affects LLM-generated slides"
+      flag "--filename",     arg: "NAME",  desc: "File name under public/ (default: next sequential file)"
+      flag "--llm-base-url", arg: "URL",   desc: "OpenAI Compatible API base URL (env: SLIDICT_LLM_BASE_URL).\n" \
+                                                  "When omitted, the built-in slide template is used instead."
+      flag "--llm-api-key",  arg: "KEY",   desc: "API key for the LLM endpoint (env: SLIDICT_LLM_API_KEY)"
+      # rubocop:disable Layout/HashAlignment -- source-only line wrap, desc stays a single displayed line
+      flag "--llm-model", arg: "NAME",
+           desc: "Model name to request (env: SLIDICT_LLM_MODEL); omit to list available models"
+      # rubocop:enable Layout/HashAlignment
+      flag "--no-llm",                     desc: "Skip the LLM call and use the built-in slide template"
+      flag "--publish",                    desc: "Publish the generated slides to slidict.io as a draft\n" \
+                                                  "(requires `slidict auth`; creates a new slide, or edits\n" \
+                                                  "an existing one when --slide-id is given)"
+      # rubocop:disable Layout/HashAlignment -- source-only line wrap, desc stays a single displayed line
+      flag "--slide-id", arg: "ID",
+           desc: "Edit this existing draft instead of creating a new one\n(implies --publish)"
+      # rubocop:enable Layout/HashAlignment
+      flag "--slide-title",  arg: "TEXT",  desc: "Title for the published slide (default: --topic)"
+      flag "--visibility",   arg: "VIS",   desc: "public, unlisted, or group_only (default: public)"
+      flag "-o", "--output", arg: "PATH",  desc: "Output file (overrides --filename and the public/ default)"
+      flag "-h", "--help",                 desc: "Show this help"
 
       def run(argv = [])
         options = parse(argv)
@@ -28,28 +68,30 @@ module Slidict
         return lint(options[:args]) if options[:command] == "lint"
         return list_methods if options[:command] == "list-methods"
         return show_method(options[:args]) if options[:command] == "show-method"
+        return init if options[:command] == "init"
 
         config = build_config(options)
         return print_available_models(config) if config.llm_enabled? && config.model.nil?
 
         client = llm_client_for(config)
-        return 1 if client && !verify_connection(client)
+        return FAILURE if client && !verify_connection(client)
 
+        questions = questions_for(client, options)
         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]),
+          topic: ask(questions[:topic], options[:topic]),
+          duration: ask(questions[:duration], options[:duration]),
+          audience: ask(questions[:audience], options[:audience]),
+          goal: ask(questions[:goal], options[:goal]),
           framework: options[:framework],
           presentation_method: options[:presentation_method]
         )
 
         if client
           begin
-            slides = client.generate_slides(deck)
+            slides = client.generate_slides(deck, language: options[:language])
           rescue Llm::Client::Error => e
             @output.puts "Error: LLM request failed (#{e.message})"
-            return 1
+            return FAILURE
           end
           deck = Deck.new(
             topic: deck.topic, duration: deck.duration, audience: deck.audience, goal: deck.goal,
@@ -65,18 +107,18 @@ module Slidict
 
         return publish_to_slidict(deck, content, options) if options[:publish] || options[:slide_id]
 
-        0
+        SUCCESS
       rescue ArgumentError => e
         @output.puts "Error: #{e.message}"
         @output.puts
         print_help
-        1
+        FAILURE
       end
 
       private
 
       def parse(argv)
-        options = { framework: "slidev" }
+        options = { framework: ENV["SLIDICT_FRAMEWORK"] || "slidev", method: ENV["SLIDICT_METHOD"] }
         args = argv.dup
 
         args.shift if args.first == "new"
@@ -125,47 +167,16 @@ module Slidict
           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 "--method"
-            options[:method] = 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
+        if args.first == "init"
+          args.shift
+          raise ArgumentError, "init does not accept options" unless args.empty?
+
+          options[:command] = "init"
+          return options
         end
 
+        parse_flags!(args, options)
+
         options[:output] ||= output_path_for(options[:framework], options[:filename])
         options[:presentation_method] = method_for(options[:method])
         options
@@ -189,10 +200,10 @@ module Slidict
           @output.puts "Available models (specify one with --llm-model NAME or SLIDICT_LLM_MODEL=NAME):"
           models.each { |m| @output.puts "  #{m}" }
         end
-        0
+        SUCCESS
       rescue Llm::Client::Error => e
         @output.puts "Error: LLM request failed (#{e.message})"
-        1
+        FAILURE
       end
 
       def llm_client_for(config)
@@ -228,7 +239,7 @@ module Slidict
             provider: token.fetch("provider", "github")
           )
           @output.puts "4. Saved CLI access token to #{path}"
-          return 0
+          return SUCCESS
         rescue External::SlidictIo::Auth::Pending
           return login_expired if Time.now >= deadline
 
@@ -236,7 +247,7 @@ module Slidict
         end
       rescue External::SlidictIo::Auth::Error, KeyError => e
         @output.puts "Error: GitHub auth failed (#{e.message})"
-        1
+        FAILURE
       end
 
       def slides(args)
@@ -258,7 +269,7 @@ module Slidict
             id: method.id, name: method.name, category: method.category
           )
         end
-        0
+        SUCCESS
       end
 
       def show_method(args)
@@ -275,13 +286,53 @@ module Slidict
         method.slides.each_with_index { |slide, i| @output.puts "  #{i + 1}. #{slide.title}: #{slide.role}" }
         @output.puts "Review checklist:"
         method.review_checklist.each { |item| @output.puts "  - #{item}" }
-        0
+        SUCCESS
       end
 
       def method_for(id)
         id ? method_registry.fetch(id) : nil
       end
 
+      ENV_TEMPLATE = <<~ENV
+        # Slidict configuration. CLI flags always take precedence over these
+        # values; unset ones fall back to the built-in defaults. This file is
+        # ignored by git (see .gitignore) so it's safe to put secrets here.
+
+        # OpenAI Compatible API endpoint (required to enable LLM-generated slides).
+        # SLIDICT_LLM_BASE_URL=https://api.openai.com/v1
+        # SLIDICT_LLM_API_KEY=sk-...
+        # SLIDICT_LLM_MODEL=gpt-4o-mini
+
+        # Default --framework when it is not given on the command line.
+        # SLIDICT_FRAMEWORK=slidev
+
+        # Default --method when it is not given on the command line.
+        # SLIDICT_METHOD=scqa
+      ENV
+
+      def init
+        env_created = write_env_file
+        @output.puts(env_created ? "Created .env" : ".env already exists, leaving it unchanged")
+
+        gitignore_updated = ensure_env_gitignored
+        @output.puts "Added .env to .gitignore" if gitignore_updated
+        SUCCESS
+      end
+
+      def write_env_file
+        return false if File.exist?(".env")
+
+        File.write(".env", ENV_TEMPLATE)
+        true
+      end
+
+      def ensure_env_gitignored
+        return false if File.exist?(".gitignore") && File.readlines(".gitignore", chomp: true).include?(".env")
+
+        File.open(".gitignore", "a") { |f| f.puts(".env") }
+        true
+      end
+
       def method_registry
         @method_registry ||= PresentationMethodRegistry.new
       end
@@ -314,7 +365,7 @@ module Slidict
 
       def login_expired
         @output.puts "Error: GitHub auth timed out. Run `slidict auth` and try again."
-        1
+        FAILURE
       end
 
       def fetch_value!(args, option)
@@ -332,9 +383,29 @@ module Slidict
         @input.gets&.chomp.to_s
       end
 
-      def print_help
-        @output.puts <<~HELP
+      # Translates only the questions that will actually be asked (those
+      # whose option wasn't already given on the command line). Falls back to
+      # the English questions if there's no client, no --language, nothing
+      # left to ask, or a translation call fails -- this is a nicety, not
+      # something worth aborting slide generation over.
+      def questions_for(client, options)
+        return QUESTIONS unless client && options[:language]
+
+        missing = QUESTIONS.select { |key, _| options[key].to_s.strip.empty? }
+        return QUESTIONS if missing.empty?
+
+        translated = missing.transform_values { |text| client.translate_text(text, options[:language]) }
+        QUESTIONS.merge(translated)
+      rescue Llm::Client::Error => e
+        @output.puts "Warning: could not translate questions into #{options[:language]} " \
+                     "(#{e.message}); asking in English."
+        QUESTIONS
+      end
+
+      usage do
+        <<~USAGE
           Usage: slidict [new] [options]
+          Usage: slidict init
           Usage: slidict auth
           Usage: slidict slides <list|show|create|edit> [options]
           Usage: slidict serve [sinatra options]
@@ -345,6 +416,7 @@ module Slidict
           Generate presentation source files from a short conversation.
 
           Commands:
+            init             Create a .env file for SLIDICT_LLM_* etc. and add it to .gitignore
             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
@@ -354,29 +426,8 @@ module Slidict
             show-method      Show details for one presentation method
 
           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)
-              --method ID        Presentation method, for example scqa, prep, or pyramid
-              --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); omit to list available models
-              --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
+          #{flags_help}
+        USAGE
       end
 
       def output_path_for(framework, filename)

data/lib/slidict/cli/lint.rb

@@ -8,11 +8,21 @@ module Slidict
     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
+      include Options
+
+      options output: Options::MISSING,
+              linter_factory: -> { method(:default_linter) },
+              renderer: -> { Slidict::Lint::Renderer.new }
+
+      flag "--format",       arg: "FORMAT", desc: "markdown or asciidoc (default: auto-detected from extension)"
+      flag "--llm-base-url", arg: "URL",    desc: "OpenAI Compatible API base URL (env: SLIDICT_LLM_BASE_URL)"
+      flag "--llm-api-key",  arg: "KEY",    desc: "API key for the LLM endpoint (env: SLIDICT_LLM_API_KEY)"
+      # rubocop:disable Layout/HashAlignment -- source-only line wrap, desc stays a single displayed line
+      flag "--llm-model", arg: "NAME",
+           desc: "Model name to request (env: SLIDICT_LLM_MODEL); omit to list available models"
+      # rubocop:enable Layout/HashAlignment
+      flag "--translate",    arg: "LANG",   desc: "Translate findings into the given language (e.g. Japanese)"
+      flag "-h", "--help",                  desc: "Show this help"
 
       def run(argv)
         options = parse(argv)
@@ -44,18 +54,18 @@ module Slidict
         print_error(error)
         @output.puts
         print_help
-        1
+        FAILURE
       end
 
       def print_error(error)
         @output.puts "Error: #{error.message}"
-        1
+        FAILURE
       end
 
       def parse(argv)
         args = argv.dup
         options = { path: extract_path!(args) }
-        parse_options!(args, options)
+        parse_flags!(args, options)
         options
       end
 
@@ -63,20 +73,6 @@ module Slidict
         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)
-          when "--translate" then options[:translate] = 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?("-")
@@ -105,12 +101,12 @@ module Slidict
 
       def print_findings(findings)
         @output.puts(findings.empty? ? "No issues found." : @renderer.render(findings))
-        0
+        SUCCESS
       end
 
       def file_not_found(path)
         @output.puts "Error: file not found: #{path}"
-        1
+        FAILURE
       end
 
       def print_available_models(config)
@@ -122,28 +118,22 @@ module Slidict
           @output.puts "Available models (specify one with --llm-model NAME or SLIDICT_LLM_MODEL=NAME):"
           models.each { |m| @output.puts "  #{m}" }
         end
-        0
+        SUCCESS
       rescue Llm::Client::Error => e
         print_error(e)
       end
 
       def llm_required
         @output.puts "Error: lint requires an LLM endpoint (--llm-base-url or SLIDICT_LLM_BASE_URL)"
-        1
+        FAILURE
       end
 
-      def print_help
-        @output.puts <<~HELP
+      usage do
+        <<~USAGE
           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); omit to list available models
-              --translate LANG    Translate findings into the given language (e.g. Japanese)
-          -h, --help               Show this help
-        HELP
-        0
+          #{flags_help}
+        USAGE
       end
     end
   end

data/lib/slidict/cli/options.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Slidict
+  module Cli
+    # Concern for CLI classes with several constructor dependencies. Declaring
+    # `options name: -> { default }, ...` once generates both the attr_reader
+    # and the `initialize` assignment, instead of repeating each dependency in
+    # the method signature and again as `@name = name` in the body.
+    #
+    # Defaults are instance_exec'd lazily (only when the keyword is omitted),
+    # matching plain keyword-argument defaults, and may reference other
+    # options or instance methods (e.g. `-> { method(:default_linter) }`).
+    # Classes that need to post-process a value (e.g. expanding a path) can
+    # still override `initialize`, call `super`, and adjust the ivar.
+    #
+    # Also provides a `flag`/`parse_flags!`/`flags_help` DSL: declaring a
+    # `-x`/`--xxx` switch once (with its arg placeholder and description)
+    # drives both argv parsing and the `--help` listing, so the two can't
+    # drift apart. `usage` then only needs to hold the surrounding usage text
+    # (Usage:/Commands: lines), interpolating `flags_help` for the option list.
+    module Options
+      MISSING = Object.new.freeze
+
+      # Process exit codes (see bin/slidict, which does `exit App.new.run(ARGV)`),
+      # named so command methods don't scatter bare 0/1 literals as return values.
+      SUCCESS = 0
+      FAILURE = 1
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # One `-x`/`--xxx` declaration: how to parse it (arg placeholder,
+      # coercion) and how to describe it in `--help` output.
+      Flag = Struct.new(:switches, :key, :arg, :coerce, :desc, keyword_init: true) do
+        def boolean?
+          arg.nil?
+        end
+
+        def short
+          switches.find { |s| !s.start_with?("--") }
+        end
+
+        def long
+          switches.find { |s| s.start_with?("--") }
+        end
+
+        # Left column of the help listing, e.g. "-o, --output PATH" or, for a
+        # long-only flag, "    --topic TEXT" -- the leading 4 spaces keep the
+        # "--name" text column-aligned either way.
+        def name_column
+          column = "#{short ? "#{short}, " : "    "}#{long}"
+          arg ? "#{column} #{arg}" : column
+        end
+      end
+
+      # Class-level DSL (`options name: -> { default }, ...`) mixed into any
+      # class that includes Options.
+      module ClassMethods
+        # Defines the assignment in an anonymous module (rather than directly
+        # on the including class) so a class that needs to post-process a
+        # value can still define its own `initialize`, call `super`, and have
+        # it reach this one instead of silently overwriting it.
+        def options(**defaults)
+          attr_reader(*defaults.keys)
+
+          include(Module.new do
+            define_method(:initialize) do |**overrides|
+              defaults.each do |name, default|
+                instance_variable_set(:"@#{name}", resolve_option(name, default, overrides))
+              end
+            end
+          end)
+        end
+
+        # Declares a flag. `group` lets a class with several argv shapes
+        # (e.g. Slides' `list` vs. `create`/`edit`) keep separate flag sets;
+        # `parse_flags!`/`flags_help` default to :default. `desc` may be a
+        # Proc (instance_exec'd lazily, like an `options` default) for text
+        # that depends on another file having loaded by call time rather
+        # than by require time (e.g. `Output::Format.names`).
+        def flag(*switches, desc:, arg: nil, coerce: nil, group: :default)
+          key = switches.last.sub(/\A-+/, "").tr("-", "_").to_sym
+          flag_groups[group] << Flag.new(switches: switches, key: key, arg: arg, coerce: coerce, desc: desc)
+        end
+
+        def flag_groups
+          @flag_groups ||= Hash.new { |h, k| h[k] = [] }
+        end
+
+        def flags(group = :default)
+          flag_groups[group]
+        end
+
+        # Declares the `-h`/`--help` usage text, generating a private
+        # `print_help` that writes it to `@output` and returns SUCCESS,
+        # instead of every command spelling that out. Takes a block for the
+        # same lazy-evaluation reason as `flag`'s `desc:`.
+        def usage(&text)
+          private(define_method(:print_help) do
+            @output.puts instance_exec(&text)
+            SUCCESS
+          end)
+        end
+      end
+
+      private
+
+      def resolve_option(name, default, overrides)
+        return overrides[name] if overrides.key?(name)
+        raise ArgumentError, "missing keyword: :#{name}" if default.equal?(MISSING)
+
+        instance_exec(&default)
+      end
+
+      # Consumes `args` against `self.class.flags(group)`: booleans are set to
+      # true, valued flags read their value via the including class's own
+      # `fetch_value!` (whose rules on e.g. a leading "-" differ between
+      # classes), then any `coerce` is applied.
+      def parse_flags!(args, options, group = :default)
+        until args.empty?
+          arg = args.shift
+          flag = self.class.flags(group).find { |f| f.switches.include?(arg) }
+          raise ArgumentError, "unknown option #{arg}" unless flag
+
+          value = flag.boolean? || fetch_value!(args, arg)
+          value = instance_exec(value, &flag.coerce) if flag.coerce
+          options[flag.key] = value
+        end
+      end
+
+      # Renders `self.class.flags(group)` as an aligned --help listing.
+      def flags_help(group = :default)
+        defs = self.class.flags(group)
+        width = defs.map { |f| f.name_column.length }.max
+        defs.map { |f| flag_doc_lines(f, width) }.join("\n")
+      end
+
+      def flag_doc_lines(flag, width)
+        desc = flag.desc.respond_to?(:call) ? instance_exec(&flag.desc) : flag.desc
+        first, *rest = desc.lines(chomp: true)
+        lines = ["#{flag.name_column.ljust(width)}  #{first}"]
+        rest.each { |line| lines << "#{" " * (width + 2)}#{line}" }
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/slidict/cli/serve.rb

@@ -9,9 +9,14 @@ module Slidict
     class Serve
       DEFAULT_PUBLIC_DIR = "public"
 
-      def initialize(public_dir: DEFAULT_PUBLIC_DIR, output: $stdout)
-        @public_dir = File.expand_path(public_dir)
-        @output = output
+      include Options
+
+      options public_dir: -> { DEFAULT_PUBLIC_DIR },
+              output: -> { $stdout }
+
+      def initialize(**)
+        super
+        @public_dir = File.expand_path(@public_dir)
       end
 
       def run(args = [])
@@ -20,7 +25,7 @@ module Slidict
         ARGV.replace(args)
         @output.puts "Serving slides from #{@public_dir}"
         app.run!
-        0
+        SUCCESS
       ensure
         ARGV.replace(original_argv) if original_argv
       end

data/lib/slidict/cli/slides.rb

@@ -4,12 +4,29 @@ 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
+      include Options
+
+      options output: Options::MISSING,
+              credentials: -> { External::SlidictIo::Credentials.new },
+              client: -> { nil },
+              reauthenticate: -> { nil }
+
+      # rubocop:disable Layout/HashAlignment -- source-only line wraps below, kept short rather than column-aligned
+      flag "--page", arg: "N",
+           coerce: ->(v) { Integer(v) }, desc: "Page number (20 slides per page)", group: :list
+      # rubocop:enable Layout/HashAlignment
+      flag "-h", "--help",              desc: "Show this help", group: :list
+
+      flag "--title",      arg: "TEXT", desc: "Slide title", group: :body_options
+      flag "--body",       arg: "TEXT", desc: "Slide body text", group: :body_options
+      # rubocop:disable Layout/HashAlignment -- source-only line wraps below, kept short rather than column-aligned
+      flag "--file",       arg: "PATH", desc: "Read the slide body from a file (instead of --body)",
+           group: :body_options
+      flag "--body-format", arg: "FORMAT", desc: "asciidoc or markdown (default: auto-detected from body)",
+           group: :body_options
+      # rubocop:enable Layout/HashAlignment
+      flag "--visibility", arg: "VIS",  desc: "public, unlisted, or group_only (default: public)", group: :body_options
+      flag "-h", "--help",              desc: "Show this help", group: :body_options
 
       def run(argv)
         options = parse(argv)
@@ -20,7 +37,7 @@ module Slidict
         @output.puts "Error: #{e.message}"
         @output.puts
         print_help
-        1
+        FAILURE
       end
 
       # Creates or edits a draft directly, bypassing argv parsing (and its
@@ -49,13 +66,7 @@ module Slidict
 
       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
+        parse_flags!(args, options, :list)
         options
       end
 
@@ -83,17 +94,7 @@ module Slidict
       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
+        parse_flags!(args, options, :body_options)
         raise ArgumentError, "specify only one of --body or --file" if options[:body] && options[:file]
       end
 
@@ -111,17 +112,17 @@ module Slidict
       def list(options)
         with_reauth_retry do
           print_slide_list(client.list(page: options[:page]))
-          0
+          SUCCESS
         end
       end
 
       def show(options)
         with_reauth_retry do
           print_slide_detail(client.show(options[:id]))
-          0
+          SUCCESS
         rescue External::SlidictIo::Client::NotFound
           @output.puts "Error: slide not found"
-          1
+          FAILURE
         end
       end
 
@@ -147,13 +148,13 @@ module Slidict
           slide = yield
           @output.puts "#{verb} slide ##{slide["id"]} (draft)"
           print_slide_detail(slide)
-          0
+          SUCCESS
         rescue External::SlidictIo::Client::NotFound
           @output.puts "Error: slide not found"
-          1
+          FAILURE
         rescue External::SlidictIo::Client::NotEditable
           @output.puts "Error: this slide is already published. Edit it from the Web UI instead."
-          1
+          FAILURE
         rescue External::SlidictIo::Client::RateLimited
           print_rate_limited
         rescue External::SlidictIo::Client::Unprocessable => e
@@ -230,22 +231,22 @@ module Slidict
 
       def print_rate_limited
         @output.puts "Error: rate limited. Create/edit is limited to once per minute. Wait and try again."
-        1
+        FAILURE
       end
 
       def print_unprocessable(error)
         @output.puts "Error: #{error.message}"
         error.errors.each { |message| @output.puts "  - #{message}" }
-        1
+        FAILURE
       end
 
       def print_client_error(error)
         @output.puts "Error: #{error.message}"
-        1
+        FAILURE
       end
 
-      def print_help
-        @output.puts <<~HELP
+      usage do
+        <<~USAGE
           Usage: slidict slides <command> [options]
 
           Commands:
@@ -255,16 +256,10 @@ module Slidict
             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
+          #{flags_help(:body_options)}
 
           Note: slides are always created/edited as drafts. Publish from the Web UI.
-        HELP
-        0
+        USAGE
       end
     end
   end

data/lib/slidict/env.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Slidict
+  # Loads KEY=VALUE pairs from a .env file (if present) into ENV, so
+  # SLIDICT_LLM_BASE_URL, SLIDICT_FRAMEWORK, etc. can be set once per project
+  # instead of on every invocation. Only keys not already present in ENV are
+  # populated -- a real environment variable always wins over .env, and a CLI
+  # flag (read afterwards, in Cli::App#parse) wins over both. See `slidict
+  # init` for generating a starter file.
+  module Env
+    LINE = /\A(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)\z/
+
+    def self.load!(path = ".env", env = ENV)
+      return unless File.exist?(path)
+
+      File.foreach(path) do |line|
+        key, value = parse_line(line)
+        env[key] = value if key && !env.key?(key)
+      end
+    end
+
+    def self.parse_line(line)
+      line = line.strip
+      return [nil, nil] if line.empty? || line.start_with?("#")
+
+      match = LINE.match(line)
+      return [nil, nil] unless match
+
+      [match[1], unquote(match[2].strip)]
+    end
+    private_class_method :parse_line
+
+    # A quoted value keeps everything up to its closing quote verbatim (so a
+    # "#" inside it isn't mistaken for a comment); an unquoted value has any
+    # trailing "# comment" stripped.
+    def self.unquote(value)
+      if value.start_with?('"', "'")
+        quote = value[0]
+        closing = value.index(quote, 1)
+        return closing ? value[1...closing] : value[1..]
+      end
+
+      value.sub(/\s+#.*\z/, "")
+    end
+    private_class_method :unquote
+  end
+end

data/lib/slidict/llm/client.rb

@@ -35,8 +35,8 @@ module Slidict
         raise Error, "could not parse models response: #{e.message}"
       end
 
-      def generate_slides(deck)
-        content = chat_completion(prompt_for(deck))
+      def generate_slides(deck, language: nil)
+        content = chat_completion(prompt_for(deck, language: language))
         slides_from(content)
       end
 
@@ -48,6 +48,16 @@ module Slidict
         findings_from(content)
       end
 
+      # Translates a single line of text into language. Unlike
+      # generate_slides/lint_slides, the response is a plain string rather
+      # than parsed JSON: asking a (often small, local) model to translate
+      # one line is a task it can follow reliably, whereas asking it to also
+      # return a JSON array of a specific length is exactly the kind of
+      # structured-output instruction weaker models tend to get wrong.
+      def translate_text(text, language)
+        strip_quotes(chat_completion(translate_prompt_for(text, language)).strip)
+      end
+
       private
 
       def get_models_response
@@ -57,7 +67,7 @@ module Slidict
         perform_request(uri, request)
       end
 
-      def prompt_for(deck)
+      def prompt_for(deck, language: nil)
         <<~PROMPT
           You are an assistant that designs presentation slide outlines.
           Topic: #{deck.topic}
@@ -69,11 +79,17 @@ module Slidict
           Return one slide for each required slide role when a presentation method is
           provided; otherwise return exactly 5 slides. 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.
+          #{language_instruction_for(language)}Respond with the JSON array only: no commentary, no markdown code
+          fences, and no reasoning or thinking content before or after it.
         PROMPT
       end
 
+      def language_instruction_for(language)
+        return "" unless language
+
+        "Write the \"title\" and \"bullets\" text in #{language}.\n"
+      end
+
       def method_prompt_for(deck)
         method = deck.presentation_method
         return "" unless method
@@ -132,6 +148,23 @@ module Slidict
         translate ? "#{prompt}\nTranslate only the \"message\" field of each finding into #{translate}. Keep \"slide\" as an integer and \"severity\" as exactly \"warning\" or \"info\" — do not translate those values." : prompt
       end
 
+      def translate_prompt_for(text, language)
+        <<~PROMPT
+          Translate the following text into #{language}. Respond with only the
+          translation: no commentary, no surrounding quotation marks, no
+          markdown formatting, and no reasoning or thinking content before or
+          after it.
+
+          #{text}
+        PROMPT
+      end
+
+      # Small/local models often ignore the "no quotation marks" instruction
+      # above and wrap the translation anyway.
+      def strip_quotes(text)
+        text.sub(/\A["'“”‘’「」]+/, "").sub(/["'“”‘’「」]+\z/, "")
+      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)

data/lib/slidict/version.rb

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

data/lib/slidict.rb

@@ -2,12 +2,14 @@
 
 require "time"
 
+require_relative "slidict/cli/options"
 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/deck"
+require_relative "slidict/env"
 require_relative "slidict/external/slidict_io/auth"
 require_relative "slidict/external/slidict_io/client"
 require_relative "slidict/external/slidict_io/credentials"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: slidict
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.5.3
 platform: ruby
 authors:
 - Yusuke Abe
@@ -83,10 +83,12 @@ files:
 - lib/slidict.rb
 - lib/slidict/cli/app.rb
 - lib/slidict/cli/lint.rb
+- lib/slidict/cli/options.rb
 - lib/slidict/cli/serve.rb
 - lib/slidict/cli/slides.rb
 - lib/slidict/config.rb
 - lib/slidict/deck.rb
+- lib/slidict/env.rb
 - lib/slidict/external/slidict_io/auth.rb
 - lib/slidict/external/slidict_io/client.rb
 - lib/slidict/external/slidict_io/credentials.rb