promptly 0.1.7 → 0.1.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55ee620ab3faf1e3c2d2ff44db3f28fe255a7379431c360f86b6f8dd87a8a752
-  data.tar.gz: ddf1db22fc260b4007e374944833b4ffe08fd5bcab020a033a28956612a26bbc
+  metadata.gz: acd140832db9c4f719f094548791c956ec3cb0f7380cf1c213e9923be1070fe2
+  data.tar.gz: abdba3ecdc1c1d4a03f012944c5ebc08d906c02266872eb9e3fb54483add5f55
 SHA512:
-  metadata.gz: 0f343de865b5a2bef48f3a86cd131c40b8173be6183267fbd22242b228b668891ea191c7dba2597db373a7814bb30e05b8b8e4004cf345defef1d2e84c7b9b92
-  data.tar.gz: 3e872512ba87aa8f387d851d75d378e7b9cba91a20bbc0c316598af80166a71d691751e3a00a1aefda20a132f88e5a9bb58414ba312760dbc02dacec590bc11e
+  metadata.gz: b714d8ec43e3491248fc5a229cbbc2018227a28b32b68d84e8961fab5fe5185b860c55de425f3c573eb9b776f1922b5e56b331a6cf2be95cf7d8f33b303f8d1a
+  data.tar.gz: 69afcef9ff51ba00326a5e1efa1226777aecc97cfc9f9d85998a960353758a05b1fa967cef716dd441618f68afe67194333c0f4c1253a1b773d3f2818930dd12

data/README.md

@@ -1,37 +1,4 @@
-## Generators
-
-Create prompt templates following conventions.
-
-```bash
-# ERB with multiple locales
-rails g promptly:prompt user_onboarding/welcome_email --locales en es --engine erb
-
-# Liquid with a single locale
-rails g promptly:prompt ai_coaching/goal_review --locales en --engine liquid
-
-# Fallback-only (no locale suffix)
-rails g promptly:prompt content_generation/outline --no-locale
-```
-
-Options:
-
-- `--engine` erb|liquid (default: erb)
-- `--locales` space-separated list (default: I18n.available_locales if available, else `en`)
-- `--no-locale` create only fallback file (e.g., `welcome_email.erb`)
-- `--force` overwrite existing files
-
-Generated files are placed under `app/prompts/` and directories are created as needed.
 
-Examples:
-
-- `app/prompts/user_onboarding/welcome_email.en.erb`
-- `app/prompts/user_onboarding/welcome_email.es.erb`
-- `app/prompts/ai_coaching/goal_review.en.liquid`
-- `app/prompts/content_generation/outline.erb` (fallback-only)
-
-The generator seeds a minimal, intention-revealing scaffold you can edit immediately.
-
-## API Reference
 # Promptly
 
 Opinionated Rails integration for reusable AI prompt templates. Build maintainable, localized, and testable AI prompts using ERB or Liquid templates with Rails conventions.
@@ -182,6 +149,32 @@ rails ai_prompts:render[user_onboarding/welcome_email,es]
 rails ai_prompts:render[user_onboarding/welcome_email]
 ```
 
+## Helper: render_prompt
+
+Use a concise helper anywhere in Rails to render prompts with locals that are also exposed as instance variables inside ERB templates.
+
+* **Auto-included**: Controllers, Mailers, and Jobs via Railtie.
+* **Services/Plain Ruby**: `include Promptly::Helper`.
+
+Example template and usage:
+
+```erb
+# app/prompts/welcome_email.erb
+Hello <%= @user.name %>, welcome to our service!
+We're excited to have you join.
+```
+
+```ruby
+# In a mailer, job, controller, or a service that includes Promptly::Helper
+rendered = render_prompt("welcome_email", user: @user)
+```
+
+Notes:
+
+- **Locals become @instance variables** in ERB. Passing `user: @user` makes `@user` available in the template.
+- **Localization**: `render_prompt("welcome_email", locale: :es, user: user)` resolves `welcome_email.es.erb` with fallback per `Promptly::Locator`.
+- **Caching**: Controlled per call (`cache:`, `ttl:`) and globally via `Promptly::Cache`.
+
 ## Rails App Integration
 
 ### Service Object Pattern
@@ -474,6 +467,78 @@ template = "Hello {{ name }}, welcome to {{ app }}!"
 output = Promptly.render_template(template, locals: {name: "John", app: "MyApp"}, engine: :liquid)
 ```
 
+## Generators
+
+Create prompt templates following conventions.
+
+```bash
+# ERB with multiple locales
+rails g promptly:prompt user_onboarding/welcome_email --locales en es --engine erb
+
+# Liquid with a single locale
+rails g promptly:prompt ai_coaching/goal_review --locales en --engine liquid
+
+# Fallback-only (no locale suffix)
+rails g promptly:prompt content_generation/outline --no-locale
+```
+
+Options:
+
+- `--engine` erb|liquid (default: erb)
+- `--locales` space-separated list (default: I18n.available_locales if available, else `en`)
+- `--no-locale` create only fallback file (e.g., `welcome_email.erb`)
+- `--force` overwrite existing files
+
+Generated files are placed under `app/prompts/` and directories are created as needed.
+
+Examples:
+
+- `app/prompts/user_onboarding/welcome_email.en.erb`
+- `app/prompts/user_onboarding/welcome_email.es.erb`
+- `app/prompts/ai_coaching/goal_review.en.liquid`
+- `app/prompts/content_generation/outline.erb` (fallback-only)
+
+The generator seeds a minimal, intention-revealing scaffold you can edit immediately.
+
+## Linting Templates
+
+Validate your prompt templates from the CLI.
+
+```bash
+# Lint all templates under the prompts path
+rake ai_prompts:lint
+
+# Lint a specific identifier (path without locale/ext)
+rake ai_prompts:lint[user_onboarding/welcome_email]
+
+# Specify locales to check for coverage
+LOCALES=en,es rake ai_prompts:lint
+
+# Require placeholders to exist in templates
+REQUIRED=name,app_name rake ai_prompts:lint[user_onboarding/welcome_email]
+
+# Point to a custom prompts directory
+PROMPTS_PATH=lib/ai_prompts rake ai_prompts:lint
+```
+
+What it checks:
+
+- **Syntax errors**
+  - ERB: compiles with `ERB.new` (no execution)
+  - Liquid: parses with `Liquid::Template.parse` (if `liquid` gem present)
+- **Missing locale files**
+  - For each identifier, warns when required locales are missing
+  - Locales source: `LOCALES` env or `I18n.available_locales`
+- **Required placeholders**
+  - Best-effort scan for required keys from `REQUIRED` env
+  - ERB: looks for `<%= ... @key ... %>` or `<%= ... key ... %>` usage
+  - Liquid: looks for `{{ key }}` usage
+
+Exit codes:
+
+- `0` when all checks pass
+- `1` when errors are found (syntax or missing required placeholders)
+
 ## API Reference
 
 ### `Promptly.render(identifier, locale: nil, locals: {}, cache: true, ttl: nil)`

data/lib/promptly/helper.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Promptly
+  module Helper
+    # Render a prompt template by identifier.
+    #
+    # Example:
+    #   # app/prompts/welcome_email.erb
+    #   # Hello <%= @user.name %>, welcome!
+    #
+    #   # In a mailer, job, or service including this module:
+    #   # render_prompt("welcome_email", user: @user)
+    #
+    # Supports locale-aware lookup and caching.
+    def render_prompt(identifier, locale: nil, cache: true, ttl: nil, **locals)
+      Promptly.render(identifier, locale: locale, locals: locals, cache: cache, ttl: ttl)
+    end
+  end
+end

data/lib/promptly/railtie.rb

@@ -11,6 +11,21 @@ module Promptly
       if defined?(Rails.cache)
         Promptly::Cache.store = Rails.cache
       end
+
+      # Make render_prompt available in mailers, jobs, and controllers
+      if defined?(ActiveSupport)
+        ActiveSupport.on_load(:action_mailer) do
+          include Promptly::Helper
+        end
+
+        ActiveSupport.on_load(:active_job) do
+          include Promptly::Helper
+        end
+
+        ActiveSupport.on_load(:action_controller) do
+          include Promptly::Helper
+        end
+      end
     end
 
     rake_tasks do

data/lib/promptly/renderer.rb

@@ -26,6 +26,12 @@ module Promptly
       lookup = ActionView::LookupContext.new(ActionView::PathSet.new([]))
       av = view_class.new(lookup, {}, nil)
 
+      # Make locals available both as locals and instance variables (e.g., @user)
+      (locals || {}).each do |k, v|
+        ivar = "@#{k}"
+        av.instance_variable_set(ivar, v)
+      end
+
       av.render(inline: template, type: :erb, locals: locals || {})
     end
 

data/lib/promptly/tasks/ai_prompts.rake

@@ -22,4 +22,122 @@ namespace :ai_prompts do
       exit 1
     end
   end
+
+  desc "Lint prompt templates. Usage: rake ai_prompts:lint[identifier] LOCALES=en,es REQUIRED=name,app_name PROMPTS_PATH=..."
+  task :lint, [:identifier] => :environment do |_, args|
+    require "erb"
+
+    prompts_path = ENV["PROMPTS_PATH"] || Promptly.prompts_path
+    identifier_filter = args[:identifier]
+
+    locales = if ENV["LOCALES"]
+      ENV["LOCALES"].split(",").map(&:strip).reject(&:empty?)
+    elsif defined?(I18n) && I18n.respond_to?(:available_locales)
+      I18n.available_locales.map(&:to_s)
+    else
+      []
+    end
+
+    required_keys = (ENV["REQUIRED"] || "").split(",").map(&:strip).reject(&:empty?)
+
+    unless File.directory?(prompts_path)
+      warn "[lint] prompts_path not found: #{prompts_path}"
+      exit 1
+    end
+
+    exts = Promptly::Locator::SUPPORTED_EXTS
+
+    files = Dir.glob(File.join(prompts_path, "**", "*{#{exts.join(",")}}"))
+    if identifier_filter
+      files.select! do |f|
+        # match by identifier path without locale/ext
+        rel = f.sub(/^#{Regexp.escape(prompts_path)}\//, "")
+        base = rel.sub(/\.(?:[a-z]{2})?(?:#{exts.map { |e| Regexp.escape(e) }.join("|")})\z/, "")
+        base == identifier_filter
+      end
+    end
+
+    if files.empty?
+      warn "[lint] No templates found under #{prompts_path}#{identifier_filter ? " for '#{identifier_filter}'" : ""}"
+      exit 1
+    end
+
+    status = 0
+
+    # Group by identifier (path without locale/ext)
+    grouped = files.group_by do |f|
+      rel = f.sub(/^#{Regexp.escape(prompts_path)}\//, "")
+      rel.sub(/\.(?:[a-z]{2})?(?:#{exts.map { |e| Regexp.escape(e) }.join("|")})\z/, "")
+    end
+
+    grouped.each do |identifier, paths|
+      puts "[lint] Identifier: #{identifier}"
+
+      # 1) Syntax check and placeholder scan per file
+      paths.each do |path|
+        engine = Promptly::Locator.engine_for(path)
+        content = File.read(path)
+
+        begin
+          case engine
+          when :erb
+            # Compile ERB to Ruby, don't execute
+            ERB.new(content)
+          when :liquid
+            if defined?(::Liquid)
+              ::Liquid::Template.parse(content)
+            else
+              warn "  - WARN: Liquid not available; skipping syntax parse for #{File.basename(path)}"
+            end
+          end
+        rescue => e
+          warn "  - ERROR: Syntax error in #{File.basename(path)}: #{e.class}: #{e.message}"
+          status = 1
+        end
+
+        # Required placeholder presence (best-effort scan)
+        if required_keys.any?
+          missing = []
+          required_keys.each do |key|
+            present = false
+            case engine
+            when :erb
+              # naive checks: @key or key inside ERB output tags
+              present ||= content.match?(/<%[=\-].*?@#{Regexp.escape(key)}[\W]/m)
+              present ||= content.match?(/<%[=\-].*?\b#{Regexp.escape(key)}\b/m)
+            when :liquid
+              present ||= content.match?(/\{\{\s*#{Regexp.escape(key)}[\s\|\}]/)
+            end
+            missing << key unless present
+          end
+          if missing.any?
+            warn "  - ERROR: Missing required placeholders in #{File.basename(path)}: #{missing.join(", ")}"
+            status = 1
+          end
+        end
+      end
+
+      # 2) Missing locale files (if locales provided)
+      if locales.any?
+        found_locales = paths.map do |p|
+          # extract locale between name and extension: name.<locale>.ext
+          File.basename(p)[/\.([a-z]{2})\.(?:erb|liquid)\z/, 1]
+        end.compact.uniq
+
+        missing_locales = locales - found_locales
+        if missing_locales.any?
+          warn "  - WARN: Missing locale templates for #{identifier}: #{missing_locales.join(", ")}"
+        else
+          puts "  - OK: Locale coverage satisfied"
+        end
+      end
+    end
+
+    if status.zero?
+      puts "[lint] OK"
+    else
+      warn "[lint] FAIL"
+    end
+    exit status
+  end
 end

data/lib/promptly/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Promptly
-  VERSION = "0.1.7"
+  VERSION = "0.1.13"
 end

data/lib/promptly.rb

@@ -4,6 +4,7 @@ require_relative "promptly/version"
 require_relative "promptly/renderer"
 require_relative "promptly/locator"
 require_relative "promptly/cache"
+require_relative "promptly/helper"
 
 module Promptly
   class Error < StandardError; end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: promptly
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.13
 platform: ruby
 authors:
 - Wilbur Suero
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-16 00:00:00.000000000 Z
+date: 2025-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionview
@@ -97,12 +97,12 @@ files:
 - lib/generators/promptly/prompt_generator.rb
 - lib/promptly.rb
 - lib/promptly/cache.rb
+- lib/promptly/helper.rb
 - lib/promptly/locator.rb
 - lib/promptly/railtie.rb
 - lib/promptly/renderer.rb
 - lib/promptly/tasks/ai_prompts.rake
 - lib/promptly/version.rb
-- promptly.gemspec
 homepage: https://github.com/wilburhimself/promptly
 licenses:
 - MIT
@@ -120,7 +120,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.3'
+      version: '3.2'
   - - "<"
     - !ruby/object:Gem::Version
       version: '3.4'

data/promptly.gemspec

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/promptly/version"
-
-Gem::Specification.new do |spec|
-  spec.name = "promptly"
-  spec.version = Promptly::VERSION
-  spec.authors = ["Wilbur Suero"]
-  spec.email = ["wilbur@example.com"]
-
-  spec.summary = "Opinionated Rails integration for reusable AI prompt templates"
-  spec.description = "Build maintainable, localized, and testable AI prompts using ERB or Liquid templates with Rails conventions"
-  spec.homepage = "https://github.com/wilburhimself/promptly"
-  spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.3", "< 3.4"
-
-  spec.metadata["allowed_push_host"] = "https://rubygems.org"
-
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/wilburhimself/promptly"
-  spec.metadata["changelog_uri"] = "https://github.com/wilburhimself/promptly/blob/main/CHANGELOG.md"
-  spec.metadata["documentation_uri"] = "https://github.com/wilburhimself/promptly/blob/main/README.md"
-
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  gemfiles = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (File.expand_path(f) == __FILE__) || f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
-    end
-  end
-  spec.files = gemfiles
-
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  # Runtime dependencies (single target: Rails 7.2.x)
-  spec.add_dependency "actionview", "~> 7.2"
-
-  # Development dependencies
-  spec.add_development_dependency "rspec", "~> 3.12"
-  spec.add_development_dependency "standard", "~> 1.37"
-  spec.add_development_dependency "liquid", "~> 5.5"
-  # Development dependencies
-  spec.add_development_dependency "railties", "~> 7.2"
-end