nameplate 0.1.0

data/lib/nameplate/results/success_result.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module NamePlate
+  module Results
+    # Represents a successful operation result.
+    #
+    # Provides a consistent API for checking success
+    # and accessing the returned value.
+    class SuccessResult
+      attr_reader :value
+
+      def initialize(value:)
+        @value = value
+      end
+
+      # @return [Boolean]
+      def success?
+        true
+      end
+
+      # @return [Boolean]
+      def failure?
+        false
+      end
+    end
+  end
+end

data/lib/nameplate/utils/path_helper.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Utils
+  module PathHelper
+    module_function
+
+    # Convert a public file-system path to a URL path.
+    #
+    # @param path [String, Pathname]
+    # @return [String]
+    #
+    # Examples:
+    #   PathHelper.path_to_url("public/avatars/a.png") #=> "/avatars/a.png"
+    def path_to_url(path)
+      path.to_s.sub(%r{\Apublic/}, "/")
+    end
+  end
+end

data/lib/nameplate/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module NamePlate
+  VERSION = "0.1.0"
+end

data/lib/nameplate/view_helpers/avatar_helper.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "action_view"
+require "action_view/helpers"
+
+module NamePlate
+  module ViewHelpers
+    # Rails view helpers for rendering avatars in controllers/views.
+    #
+    # Usage in Rails:
+    #   include NamePlate::ViewHelpers::Avatar
+    #
+    # Then in your views:
+    #   nameplate_for("Tony", 200)
+    #   nameplate_url("Tony", 200)
+    #   nameplate_tag("Tony", 200, class: "avatar")
+    module AvatarHelper
+      if defined?(ActionView::Helpers::AssetTagHelper)
+        include ActionView::Helpers::AssetTagHelper
+      end
+
+      # Return path to generated avatar image
+      #
+      # @param name [String] the name to base avatar on
+      # @param size [Integer] requested size in px
+      # @return [String] filesystem path
+      def nameplate_for(name, size = 64)
+        NamePlate::Avatar.generate(name, size)
+      end
+
+      # Return URL for generated avatar image
+      #
+      # @param name [String] the name to base avatar on
+      # @param size [Integer] requested size in px
+      # @return [String] URL path
+      def nameplate_url(name, size = 64)
+        NamePlate.path_to_url(nameplate_for(name, size))
+      end
+
+      # Render an <img> tag for the avatar
+      #
+      # @param name [String] the name to base avatar on
+      # @param size [Integer] requested size
+      # @param options [Hash] HTML options (e.g., :class)
+      # @return [String] HTML img tag
+      def nameplate_tag(name, size = 64, options = {})
+        src = nameplate_url(name, size)
+
+        if defined?(ActionView::Helpers::AssetTagHelper)
+          extend ActionView::Helpers::AssetTagHelper
+          image_tag(src, options.merge(alt: name))
+        else
+          class_attr = options.fetch(:class, nil)
+          class_str = class_attr ? %( class="#{class_attr}") : ""
+          %(<img alt="#{name}"#{class_str} src="#{src}" />)
+        end
+      end
+    end
+  end
+end

data/lib/nameplate.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# stdlib dependencies used internally
+require "open3"
+require_relative "nameplate/version"
+require_relative "nameplate/configuration"
+require_relative "nameplate/results/success_result"
+require_relative "nameplate/results/failure_result"
+require_relative "nameplate/avatar"
+require_relative "nameplate/colors"
+require_relative "nameplate/has_avatar"
+require_relative "nameplate/image/resize"
+require_relative "nameplate/utils/path_helper"
+require_relative "nameplate/view_helpers/avatar_helper"
+
+module NamePlate
+  extend NamePlate::Configuration
+
+  # Setup DSL for configuration
+  #
+  # Example:
+  #   NamePlate.setup do |config|
+  #     config.cache_base_path = "public/system"
+  #     config.colors_palette  = :dracula
+  #   end
+  def self.setup
+    yield(self)
+  end
+
+  # Public API: generate avatar for a given username
+  #
+  # @param username [String]
+  # @param size [Integer]
+  # @return [String] path to generated avatar
+  def self.generate(username, size)
+    Avatar.generate(username, size)
+  end
+
+  # Resize an image and return a structured result
+  #
+  # @param from [String] source path
+  # @param to [String] destination path
+  # @param width [Integer]
+  # @param height [Integer]
+  # @return [SuccessResult, FailureResult]
+  def self.resize_image(from:, to:, width:, height:)
+    Image::Resize.call(from:, to:, width:, height:)
+  end
+
+  # Convert a filesystem path to a URL
+  #
+  # @param path [String, Pathname]
+  # @return [String]
+  def self.path_to_url(path)
+    Utils::PathHelper.path_to_url(path)
+  end
+end

data/spec/nameplate/avatar/cache_spec.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe NamePlate::Avatar::Cache do
+  let(:tmpdir) { File.expand_path("../../tmp/cache", __dir__) }
+
+  before do
+    FileUtils.rm_rf(tmpdir)
+    FileUtils.mkdir_p(tmpdir)
+    @orig = NamePlate.cache_base_path
+    NamePlate.cache_base_path = tmpdir
+  end
+
+  after do
+    NamePlate.cache_base_path = @orig
+    FileUtils.rm_rf(tmpdir)
+  end
+
+  let(:identity) { NamePlate::Avatar::Identity.new([226, 95, 81], "T") }
+
+  describe ".base_path" do
+    it "builds base path with version" do
+      expect(described_class.base_path).to eq(File.join(tmpdir, "nameplate", NamePlate::Avatar::VERSION.to_s))
+    end
+  end
+
+  describe ".path" do
+    it "creates directories and returns full file path" do
+      path = described_class.path(identity, 64)
+      expect(path).to end_with("/T/226_95_81/64.png")
+      expect(File).to exist(File.dirname(path))
+    end
+  end
+end

data/spec/nameplate/avatar/generator_spec.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe NamePlate::Avatar::Generator do
+  let(:identity) { NamePlate::Avatar::Identity.new([226, 95, 81], "T") }
+  let(:target_path) { File.expand_path("../../tmp/generated/64.png", __dir__) }
+  let(:fake_font) { "/fake/font.ttf" }
+  let(:mm_cmd) do
+    double("MiniMagick::Command",
+      :size => nil, :<< => nil, :pointsize => nil, :font => nil,
+      :weight => nil, :fill => nil, :gravity => nil, :annotate => nil)
+  end
+
+  before do
+    # Never touch the filesystem
+    allow(FileUtils).to receive(:mkdir_p)
+    allow(FileUtils).to receive(:rm_f)
+
+    # Stub MiniMagick constant if not loaded
+    stub_const("MiniMagick", Module.new) unless defined?(MiniMagick)
+
+    # Avoid any real font lookups
+    allow(NamePlate).to receive(:font).and_return(fake_font)
+    allow(File).to receive(:exist?).and_call_original
+    allow(File).to receive(:exist?).with(fake_font).and_return(true)
+
+    # Deterministic identity + cache path
+    allow(NamePlate::Avatar::Identity).to receive(:from_username).and_return(identity)
+    allow(NamePlate::Avatar::Cache).to receive(:path).and_return(target_path)
+  end
+
+  describe ".call" do
+    it "returns cached path when file exists and cache=true" do
+      allow(File).to receive(:exist?).with(target_path).and_return(true)
+
+      expect(described_class.call("Tony", 64, cache: true)).to eq(target_path)
+    end
+
+    it "generates via MiniMagick when cache miss" do
+      allow(File).to receive(:exist?).with(target_path).and_return(false)
+      expect(MiniMagick).to receive(:convert).and_yield(mm_cmd)
+
+      expect(described_class.call("Tony", 64, cache: false)).to eq(target_path)
+    end
+
+    it "caps size at Avatar::FULLSIZE" do
+      allow(File).to receive(:exist?).with(target_path).and_return(false)
+      allow(MiniMagick).to receive(:convert).and_yield(mm_cmd)
+
+      expect(NamePlate::Avatar::Cache).to receive(:path) do |_, s|
+        expect(s).to eq(NamePlate::Avatar::FULLSIZE)
+        target_path
+      end
+
+      described_class.call("Tony", NamePlate::Avatar::FULLSIZE + 100, cache: false)
+    end
+  end
+
+  describe ".async_call" do
+    before do
+      # Always simulate cache miss
+      allow(File).to receive(:exist?).with(target_path).and_return(false)
+    end
+
+    let(:future) { described_class.async_call("Tony", 64) }
+
+    def stub_minimagick_success
+      allow(MiniMagick).to receive(:convert).and_yield(mm_cmd)
+    end
+
+    def stub_minimagick_failure(msg = "boom")
+      allow(MiniMagick).to receive(:convert).and_raise(msg)
+    end
+
+    it "returns a future that resolves to the avatar path" do
+      stub_minimagick_success
+      expect(future.value!).to eq(target_path)
+    end
+
+    it "wraps MiniMagick errors in ImageMagickError" do
+      stub_minimagick_failure
+      expect { future.value! }.to raise_error(described_class::ImageMagickError, /MiniMagick failed/)
+    end
+
+    it "wraps filesystem errors in FileSystemError" do
+      allow(NamePlate::Avatar::Cache).to receive(:path).and_raise(Errno::EACCES)
+      expect { future.value! }.to raise_error(described_class::FileSystemError, /Permission denied/)
+    end
+
+    it "wraps unexpected errors in GenerationError" do
+      allow(NamePlate::Avatar::Identity).to receive(:from_username).and_raise("weird failure")
+      expect { future.value! }.to raise_error(described_class::GenerationError, /Unexpected error/)
+    end
+  end
+
+  describe "input validation" do
+    [
+      {input: [" ", 64], error: described_class::ConfigurationError, description: "blank username"},
+      {input: ["Tony", 0], error: described_class::ConfigurationError, description: "non-positive size"},
+      {input: ["Tony", -5], error: described_class::ConfigurationError, description: "negative size"}
+    ].each do |test_case|
+      it "raises #{test_case[:error]} for #{test_case[:description]}" do
+        expect { described_class.call(*test_case[:input]) }.to raise_error(test_case[:error])
+      end
+    end
+  end
+end

data/spec/nameplate/avatar/identity_spec.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe NamePlate::Avatar::Identity do
+  describe ".from_username" do
+    before do
+      allow(NamePlate::Colors).to receive(:for).and_return([1, 2, 3])
+    end
+
+    it "uses first letter for single-word usernames" do
+      identity = described_class.from_username("tony")
+      expect(identity.letters).to eq("T")
+      expect(identity.color).to eq([1, 2, 3])
+    end
+
+    it "uses two letters for multi-word usernames" do
+      identity = described_class.from_username("Tony Lombardi")
+      expect(identity.letters).to eq("TL")
+    end
+
+    it "upcases letters and trims whitespace" do
+      identity = described_class.from_username("  ada  ")
+      expect(identity.letters).to eq("A")
+    end
+  end
+end

data/spec/nameplate/colors_spec.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe NamePlate::Colors do
+  describe ".valid_custom_palette?" do
+    it "returns true for a valid palette of hex colors (2..20)" do
+      palette = ["#fff", "#a1b2c3", "#123456"]
+      expect(described_class.valid_custom_palette?(palette)).to be(true)
+    end
+
+    it "returns false for nil" do
+      expect(described_class.valid_custom_palette?(nil)).to be(false)
+    end
+
+    it "returns false for non-array" do
+      expect(described_class.valid_custom_palette?("#fff")).to be(false)
+    end
+
+    it "returns false for invalid hex strings" do
+      expect(described_class.valid_custom_palette?(["fff", "#12"])).to be(false)
+    end
+
+    it "returns false when too few colors" do
+      expect(described_class.valid_custom_palette?(["#fff"]))
+        .to be(false)
+    end
+
+    it "returns false when too many colors" do
+      palette = Array.new(21, "#fff")
+      expect(described_class.valid_custom_palette?(palette)).to be(false)
+    end
+  end
+end

data/spec/nameplate/image/resize_spec.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe NamePlate::Image::Resize do
+  let(:src) { File.expand_path("../../fixtures/src.png", __dir__) }
+  let(:dst) { File.expand_path("../../tmp/out.png", __dir__) }
+  let(:width) { 200 }
+  let(:height) { 200 }
+
+  before do
+    FileUtils.mkdir_p(File.dirname(src))
+    File.write(src, "PNG") unless File.exist?(src)
+
+    FileUtils.mkdir_p(File.dirname(dst))
+  end
+
+  after do
+    FileUtils.rm_f(src)
+    FileUtils.rm_f(dst)
+  end
+
+  describe ".call" do
+    context "when source does not exist" do
+      it "returns FailureResult" do
+        result = described_class.call(from: "missing.png", to: dst, width: 10, height: 10)
+
+        expect(result).to be_a(NamePlate::Results::FailureResult)
+      end
+    end
+
+    context "when width is not positive" do
+      it "returns FailureResult" do
+        result = described_class.call(from: src, to: dst, width: 0, height: 10)
+
+        expect(result.error[:message]).to include("Width must be positive integer")
+      end
+    end
+
+    context "when height is not positive" do
+      it "returns FailureResult" do
+        result = described_class.call(from: src, to: dst, width: 10, height: 0)
+
+        expect(result.error[:message]).to include("Height must be positive integer")
+      end
+    end
+
+    context "when destination path is empty" do
+      it "returns FailureResult" do
+        result = described_class.call(from: src, to: "   ", width: 10, height: 10)
+
+        expect(result.error[:message]).to include("Destination path cannot be empty")
+      end
+    end
+
+    context "when MiniMagick processes successfully" do
+      let(:image_double) do
+        instance_double(MiniMagick::Image, combine_options: nil, write: true)
+      end
+
+      let(:command_double) do
+        double("MiniMagick::Command").tap do |d|
+          allow(d).to receive(:background)
+          allow(d).to receive(:gravity)
+          allow(d).to receive(:thumbnail)
+          allow(d).to receive(:extent)
+          allow(d).to receive(:unsharp)
+          allow(d).to receive(:quality)
+        end
+      end
+
+      before do
+        allow(MiniMagick::Image).to receive(:open).with(src).and_return(image_double)
+        allow(image_double).to receive(:combine_options).and_yield(command_double)
+      end
+
+      it "returns SuccessResult with the destination path" do
+        result = described_class.call(from: src, to: dst, width: 80, height: 60)
+
+        expect(result.value[:path]).to eq(dst)
+      end
+    end
+
+    context "when MiniMagick raises an error" do
+      before do
+        allow(MiniMagick::Image).to receive(:open).and_raise(StandardError, "boom")
+      end
+
+      it "returns FailureResult with error details" do
+        result = described_class.call(from: src, to: dst, width: 80, height: 60)
+
+        expect(result.error[:message]).to include("Image resize failed: boom")
+      end
+    end
+  end
+end

data/spec/nameplate/utils/path_helper_spec.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Utils::PathHelper do
+  describe ".path_to_url" do
+    it "strips leading public/ and prefixes with /" do
+      expect(described_class.path_to_url("public/system/nameplate/1/T/226_95_81/64.png"))
+        .to eq("/system/nameplate/1/T/226_95_81/64.png")
+    end
+
+    it "returns string unchanged if it does not start with public/" do
+      expect(described_class.path_to_url("/system/nameplate/a.png")).to eq("/system/nameplate/a.png")
+    end
+  end
+end

data/spec/nameplate/view_helpers/avatar_helper_spec.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe NamePlate::ViewHelpers::AvatarHelper do
+  let(:dummy_view) do
+    Class.new do
+      include NamePlate::ViewHelpers::AvatarHelper
+    end.new
+  end
+
+  before do
+    allow(NamePlate::Avatar).to receive(:generate).and_return("public/system/nameplate/1/T/226_95_81/64.png")
+    allow(NamePlate).to receive(:path_to_url).and_call_original
+  end
+
+  describe "#nameplatefor" do
+    it "delegates to NamePlate::Avatar.generate" do
+      expect(NamePlate::Avatar).to receive(:generate).with("Tony", 64)
+      dummy_view.nameplate_for("Tony", 64)
+    end
+  end
+
+  describe "#nameplate_url" do
+    it "returns URL path derived from generated path" do
+      url = dummy_view.nameplate_url("Tony", 64)
+      expect(url).to eq("/system/nameplate/1/T/226_95_81/64.png")
+    end
+  end
+
+  describe "#nameplate_tag" do
+    it "renders a plain img tag when AssetTagHelper is not defined" do
+      hide_const("ActionView::Helpers::AssetTagHelper") if defined?(ActionView::Helpers::AssetTagHelper)
+      html = dummy_view.nameplate_tag("Tony", 64, class: "avatar")
+      expect(html).to eq('<img alt="Tony" class="avatar" src="/system/nameplate/1/T/226_95_81/64.png" />')
+    end
+  end
+end

data/spec/nameplate_spec.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe NamePlate do
+  describe ".setup" do
+    around do |example|
+      original = {
+        cache_base_path: described_class.cache_base_path,
+        pointsize: described_class.pointsize,
+        weight: described_class.weight,
+        annotate_pos: described_class.annotate_position
+      }
+
+      example.run
+    ensure
+      described_class.setup do |c|
+        c.cache_base_path = original[:cache_base_path]
+        c.pointsize = original[:pointsize]
+        c.weight = original[:weight]
+        c.annotate_position = original[:annotate_pos]
+      end
+    end
+
+    it "yields the NamePlate module" do
+      expect { |blk| described_class.setup(&blk) }.to yield_with_args(described_class)
+    end
+
+    it "applies configuration set inside the block" do
+      described_class.setup { |c| c.cache_base_path = "tmp/system" }
+      expect(described_class.cache_base_path).to eq("tmp/system")
+    end
+  end
+
+  describe ".generate" do
+    it "delegates to Avatar.generate with the same arguments" do
+      expect(NamePlate::Avatar).to receive(:generate).with("Tony", 128).and_return("path/to/avatar.png")
+      described_class.generate("Tony", 128)
+    end
+
+    it "returns the value from Avatar.generate" do
+      allow(NamePlate::Avatar).to receive(:generate).and_return("path/to/avatar.png")
+      expect(described_class.generate("Tony", 128)).to eq("path/to/avatar.png")
+    end
+  end
+
+  describe ".resize_image" do
+    let(:src) { File.expand_path("../../fixtures/src.png", __dir__) }
+    let(:dst) { File.expand_path("../../tmp/out.png", __dir__) }
+    let(:width) { 200 }
+    let(:height) { 200 }
+    let(:resize) { NamePlate::Image::Resize }
+    let(:success) { NamePlate::Results::SuccessResult.new(value: {path: "out.png"}) }
+
+    before do
+      FileUtils.mkdir_p(File.dirname(src))
+      File.write(src, "PNG") unless File.exist?(src)
+
+      FileUtils.mkdir_p(File.dirname(dst))
+    end
+
+    after do
+      FileUtils.rm_f(src)
+      FileUtils.rm_f(dst)
+    end
+
+    it "instantiates Image::Resize and calls #resize with keyword args" do
+      expect(resize).to receive(:new).with(from: src, to: dst, width:, height:).and_return(resize)
+      expect(resize).to receive(:resize!).and_return(success)
+      described_class.resize_image(from: src, to: dst, width:, height:)
+    end
+
+    it "returns the result object from Image::Resize#resize" do
+      allow(resize).to receive(:call).and_return(success)
+      expect(
+        described_class.resize_image(from: src, to: dst, width:, height:)
+      ).to eq(success)
+    end
+  end
+
+  describe ".resize (legacy)" do
+    let(:success) { NamePlate::Results::SuccessResult.new(value: {path: "out.png"}) }
+    let(:failure) { NamePlate::Results::FailureResult.new(error: {message: "nope"}) }
+
+    it "returns true when resize_image returns SuccessResult" do
+      allow(described_class).to receive(:resize_image).and_return(success)
+      expect(described_class.resize_image("in.png", "out.png", 50, 50)).to be(success)
+    end
+
+    it "returns false when resize_image returns FailureResult" do
+      allow(described_class).to receive(:resize_image).and_return(failure)
+      expect(described_class.resize_image("in.png", "out.png", 50, 50)).to be(failure)
+    end
+  end
+
+  describe ".path_to_url" do
+    it "converts a public filesystem path to a URL path" do
+      expect(described_class.path_to_url("public/system/nameplate/1/T/226_95_81/64.png"))
+        .to eq("/system/nameplate/1/T/226_95_81/64.png")
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "nameplate"
+require "pry"
+require "pry-byebug"
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = ".rspec_status"
+  config.disable_monkey_patching!
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end