csspin-rails 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c1717d5c0156c805e78da55e7b3646c305586cc9d74b243d9799b29d76dd2e75
+  data.tar.gz: 6fa180b07893e1c5a119da73c80318eacd7663791ae2c6c149c46031fe8cde45
+SHA512:
+  metadata.gz: 827c66a027c92c20c3e236596903b70cf462eadd8b081dcd491cdb60129791e88b004dfe98576ab8b192a17a90787e766397d3d8e72921f2133e90e67dad4229
+  data.tar.gz: 7a04c7c035d9fa58e151c0c4af7456b9ce0c7923c78495de426dbef7bb99e63ac5310481ac071a0c681d998d77c45a6313c9e4f7e3aebc3867a11600b033c219

data/README.md

@@ -0,0 +1,77 @@
+# csspin-rails
+
+[![CI](https://github.com/elalemanyo/csspin-rails/actions/workflows/ci.yml/badge.svg)](https://github.com/elalemanyo/csspin-rails/actions/workflows/ci.yml)
+
+Pin CSS packages from npm into a Rails app's `vendor/assets/stylesheets` — without Node.js.
+
+Works like [importmap-rails](https://github.com/rails/importmap-rails), but for CSS. Packages are fetched from [jsDelivr](https://www.jsdelivr.com/).
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "csspin-rails"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Usage
+
+```bash
+# Pin a package (latest version)
+bundle exec csspin pin trix
+
+# Pin a specific version
+bundle exec csspin pin trix@2.0.0
+
+# Pin a scoped package
+bundle exec csspin pin @scope/package@1.2.3
+```
+
+CSS is saved to `vendor/assets/stylesheets/<package>.css`.
+
+If you want `bin/csspin`, run `bundle binstubs csspin-rails` first.
+
+After pinning, the CLI prints integration snippets:
+
+```
+Sprockets snippet: *= require trix
+Sass snippet: @import "trix";
+```
+
+## CLI
+
+```
+Usage: csspin pin <package|package@version>
+
+Commands:
+  pin <package|package@version>  Download a CSS package into vendor/assets/stylesheets
+
+Options:
+  -v, --version  Show version
+  -h, --help     Show this help
+```
+
+## How it works
+
+1. Parses the package name and optional version
+2. Resolves candidate URLs on jsDelivr (`/dist/<pkg>.css`, then the bare package URL)
+3. Downloads the first successful CSS response (follows redirects, validates content-type)
+4. Writes the file to `vendor/assets/stylesheets/`
+
+## Development
+
+```bash
+bundle install
+bundle exec standardrb
+bundle exec rake test
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/exe/csspin

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "csspin"
+
+exit Csspin::CLI.run(argv: ARGV)

data/lib/csspin/cli.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Csspin
+  class CLI
+    USAGE = "Usage: csspin pin <package|package@version>"
+
+    def self.run(argv:, root: Dir.pwd, io: $stdout, error_io: $stderr, pin_command: nil)
+      command = argv[0]
+
+      if command == "--version" || command == "-v"
+        io.puts "csspin-rails #{Csspin::VERSION}"
+        return 0
+      end
+
+      if command == "--help" || command == "-h" || command.nil?
+        io.puts USAGE
+        io.puts
+        io.puts "Commands:"
+        io.puts "  pin <package|package@version>  Download a CSS package into vendor/assets/stylesheets"
+        io.puts
+        io.puts "Options:"
+        io.puts "  -v, --version  Show version"
+        io.puts "  -h, --help     Show this help"
+        return 0
+      end
+
+      unless command == "pin"
+        error_io.puts "Unknown command: #{command}"
+        error_io.puts USAGE
+        return 1
+      end
+
+      input = argv[1]
+      if input.to_s.strip.empty?
+        error_io.puts USAGE
+        return 1
+      end
+
+      downloader = Csspin::HTTP::Downloader.new
+
+      cmd = pin_command || Csspin::Commands::Pin.new(
+        resolver: Csspin::Resolver::Jsdelivr.new,
+        downloader: downloader,
+        fallback_candidates: Csspin::CssFallbackCandidates.new(
+          metadata_client: Csspin::JsdelivrMetadataClient.new(downloader: downloader)
+        ),
+        writer: Csspin::VendorWriter.new(root: root),
+        printer: Csspin::InstructionsPrinter.new(io: io),
+        error_io: error_io
+      )
+
+      cmd.run(input: input, root: root, io: io)
+    rescue ArgumentError => e
+      error_io.puts e.message
+      error_io.puts USAGE
+      1
+    end
+  end
+end

data/lib/csspin/commands/pin.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Csspin
+  module Commands
+    class Pin
+      def initialize(resolver:, downloader:, writer:, printer:, fallback_candidates:, error_io: $stderr)
+        @resolver = resolver
+        @downloader = downloader
+        @writer = writer
+        @printer = printer
+        @error_io = error_io
+        @fallback_candidates = fallback_candidates
+      end
+
+      def run(input:, root:, io:)
+        spec = Csspin::PackageSpec.parse(input)
+
+        urls = @resolver.url_candidates_for(spec)
+        tried_urls = []
+        result = download_first_success(urls, tried_urls)
+
+        unless result
+          fallback_urls = @fallback_candidates.for(spec).reject { |url| tried_urls.include?(url) }
+          result = download_first_success(fallback_urls, tried_urls)
+        end
+
+        unless result
+          @error_io.puts "Unable to download CSS from jsDelivr for #{spec.full_name}"
+          @error_io.puts "Tried: #{tried_urls.join(", ")}"
+          return 1
+        end
+
+        saved_path = @writer.write(package_name: spec.package_name, content: result[:body])
+
+        snippet_package = File.basename(saved_path, ".css")
+
+        @printer.print_success(
+          package_name: snippet_package,
+          saved_path: saved_path,
+          source_url: result[:url]
+        )
+
+        0
+      rescue ArgumentError => e
+        @error_io.puts e.message
+        1
+      rescue => e
+        @error_io.puts "Pin failed: #{e.message}"
+        1
+      end
+
+      private
+
+      def download_first_success(urls, tried_urls)
+        urls.each do |url|
+          tried_urls << url
+          response = @downloader.get(url)
+          return response.merge(url: url) if response[:ok]
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/csspin/css_fallback_candidates.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Csspin
+  class CssFallbackCandidates
+    def initialize(metadata_client:)
+      @metadata_client = metadata_client
+    end
+
+    def for(package_spec)
+      metadata = @metadata_client.fetch(package_spec.full_name)
+
+      [
+        metadata_path_for(metadata, "style"),
+        metadata_path_for(metadata, "default"),
+        *css_paths_for(metadata),
+        conventional_path_for(package_spec, "dist/css/"),
+        conventional_path_for(package_spec)
+      ].compact.map { |path| normalize_path(path, package_spec.full_name) }
+        .uniq
+        .map { |path| candidate_url_for(path, package_spec.full_name) }
+    end
+
+    private
+
+    def metadata_path_for(metadata, key)
+      path = metadata[key]
+      path if path&.end_with?(".css")
+    end
+
+    def conventional_path_for(package_spec, prefix = "")
+      "#{prefix}#{package_spec.package_name}.min.css"
+    end
+
+    def css_paths_for(metadata)
+      css_paths_from_entries(metadata["files"])
+    end
+
+    def css_paths_from_entries(entries, prefix = nil)
+      Array(entries).each_with_object([]) do |entry, paths|
+        next unless entry.is_a?(Hash)
+
+        name = entry["name"].to_s
+
+        case entry["type"]
+        when "directory"
+          path = [prefix, name].compact.join("/")
+          paths.concat(css_paths_from_entries(entry["files"], path))
+        when "file"
+          next unless name.end_with?(".css")
+
+          paths << [prefix, name].compact.join("/")
+        end
+      end
+    end
+
+    def normalize_path(path, full_name)
+      path.sub("https://cdn.jsdelivr.net/npm/#{full_name}/", "")
+    end
+
+    def candidate_url_for(path, full_name)
+      return path if path.start_with?("https://cdn.jsdelivr.net/npm/")
+
+      "https://cdn.jsdelivr.net/npm/#{full_name}/#{path}"
+    end
+  end
+end

data/lib/csspin/http/downloader.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module Csspin
+  module HTTP
+    class Downloader
+      MAX_REDIRECTS = 5
+      DEFAULT_ALLOWED_CONTENT_TYPES = ["text/css", "text/plain"].freeze
+
+      def get(url, allowed_content_types: DEFAULT_ALLOWED_CONTENT_TYPES)
+        uri = URI.parse(url)
+        redirects = 0
+
+        loop do
+          http = build_http(uri)
+          response = http.start { |h| h.get(uri.request_uri) }
+
+          if response.is_a?(Net::HTTPRedirection)
+            redirects += 1
+            return {ok: false, error: "Too many redirects", status: response.code.to_i} if redirects > MAX_REDIRECTS
+
+            location = response["location"]
+            uri = URI.join(uri, location)
+            next
+          end
+
+          if response.is_a?(Net::HTTPSuccess)
+            content_type = response["content-type"].to_s
+            unless allowed_content_types.any? { |allowed_content_type| content_type.include?(allowed_content_type) }
+              return {ok: false, error: "Not a CSS file (content-type: #{content_type})", status: response.code.to_i}
+            end
+
+            return {ok: true, body: response.body}
+          end
+
+          return {ok: false, error: "HTTP #{response.code}", status: response.code.to_i}
+        end
+      rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET, SocketError, URI::InvalidURIError => e
+        {ok: false, error: e.message, status: nil}
+      end
+
+      private
+
+      def build_http(uri)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = 5
+        http.read_timeout = 10
+        http.write_timeout = 5
+        http
+      end
+    end
+  end
+end

data/lib/csspin/instructions_printer.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Csspin
+  class InstructionsPrinter
+    def initialize(io: $stdout)
+      @io = io
+    end
+
+    def print_success(package_name:, saved_path:, source_url:)
+      @io.puts "Saved CSS to: #{saved_path}"
+      @io.puts "Source URL: #{source_url}"
+      @io.puts
+      @io.puts "Sprockets snippet: *= require #{package_name}"
+      @io.puts "Sass snippet: @import \"#{package_name}\";"
+    end
+  end
+end

data/lib/csspin/jsdelivr_metadata_client.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Csspin
+  class JsdelivrMetadataClient
+    def initialize(downloader:)
+      @downloader = downloader
+    end
+
+    def fetch(full_name)
+      metadata = fetch_json(full_name)
+      return {} unless metadata
+
+      if !metadata.key?("files") && (latest = resolve_latest_version(metadata))
+        versioned = fetch_json("#{full_name}@#{latest}")
+        return versioned if versioned
+      end
+
+      metadata
+    end
+
+    private
+
+    def fetch_json(full_name)
+      response = @downloader.get(
+        "https://data.jsdelivr.com/v1/packages/npm/#{full_name}",
+        allowed_content_types: ["application/json", "text/json"]
+      )
+      return nil unless response[:ok]
+
+      metadata = JSON.parse(response[:body])
+      metadata.is_a?(Hash) ? metadata : nil
+    rescue JSON::ParserError, TypeError
+      nil
+    end
+
+    def resolve_latest_version(metadata)
+      metadata.dig("tags", "latest")
+    end
+  end
+end

data/lib/csspin/package_spec.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Csspin
+  class PackageSpec
+    attr_reader :full_name, :package_name
+
+    def self.parse(raw)
+      normalized = raw.to_s.strip
+      raise ArgumentError, "package is required" if normalized.empty?
+
+      package_part, = split_package_and_version(normalized)
+
+      package_name = package_part.split("/").last
+      new(full_name: normalized, package_name: package_name)
+    end
+
+    def self.split_package_and_version(normalized)
+      return validate_unscoped_package!(normalized) unless normalized.include?("@")
+
+      if normalized.start_with?("@")
+        scope, remainder = normalized.split("/", 2)
+        raise ArgumentError, "invalid package format: #{normalized}" if scope.nil? || scope.length == 1 || scope.count("@") != 1 || remainder.nil? || remainder.empty?
+
+        package, version = remainder.split("@", 2)
+        raise ArgumentError, "invalid package format: #{normalized}" if package.nil? || package.empty? || package.include?("/") || version&.empty? || version&.include?("/") || version&.include?("@")
+
+        ["#{scope}/#{package}", version]
+      else
+        package, version = normalized.split("@", 2)
+        raise ArgumentError, "invalid package format: #{normalized}" if package.nil? || package.empty? || package.include?("/") || version&.empty? || version&.include?("/") || version&.include?("@")
+
+        [package, version]
+      end
+    end
+
+    def self.validate_unscoped_package!(normalized)
+      raise ArgumentError, "invalid package format: #{normalized}" if normalized.empty? || normalized.include?("/")
+
+      [normalized, nil]
+    end
+
+    def initialize(full_name:, package_name:)
+      @full_name = full_name
+      @package_name = package_name
+    end
+  end
+end

data/lib/csspin/resolver/jsdelivr.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Csspin
+  module Resolver
+    class Jsdelivr
+      def url_candidates_for(package_spec)
+        full = package_spec.full_name
+        package = package_spec.package_name
+
+        [
+          "https://cdn.jsdelivr.net/npm/#{full}/dist/#{package}.css",
+          "https://cdn.jsdelivr.net/npm/#{full}"
+        ]
+      end
+    end
+  end
+end

data/lib/csspin/vendor_writer.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Csspin
+  class VendorWriter
+    def initialize(root: Dir.pwd)
+      @root = root
+    end
+
+    def write(package_name:, content:)
+      package_name = package_name.tr("/", "-").gsub(/[^a-zA-Z0-9\-_]/, "")
+
+      dir = File.join(@root, "vendor/assets/stylesheets")
+      FileUtils.mkdir_p(dir)
+
+      path = File.join(dir, "#{package_name}.css")
+      File.write(path, content)
+      path
+    rescue Errno::ENOENT, Errno::EACCES => e
+      raise "Failed to write vendor file: #{e.message}"
+    end
+  end
+end

data/lib/csspin/version.rb

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

data/lib/csspin.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "csspin/version"
+require_relative "csspin/package_spec"
+require_relative "csspin/css_fallback_candidates"
+require_relative "csspin/jsdelivr_metadata_client"
+require_relative "csspin/resolver/jsdelivr"
+require_relative "csspin/http/downloader"
+require_relative "csspin/vendor_writer"
+require_relative "csspin/instructions_printer"
+require_relative "csspin/commands/pin"
+require_relative "csspin/cli"

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: csspin-rails
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- elalemanyo
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-04-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A CLI tool to pin CSS packages from npm (via jsDelivr) into a Rails app's
+  vendor/assets/stylesheets without Node.js.
+email:
+executables:
+- csspin
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- exe/csspin
+- lib/csspin.rb
+- lib/csspin/cli.rb
+- lib/csspin/commands/pin.rb
+- lib/csspin/css_fallback_candidates.rb
+- lib/csspin/http/downloader.rb
+- lib/csspin/instructions_printer.rb
+- lib/csspin/jsdelivr_metadata_client.rb
+- lib/csspin/package_spec.rb
+- lib/csspin/resolver/jsdelivr.rb
+- lib/csspin/vendor_writer.rb
+- lib/csspin/version.rb
+homepage: https://github.com/elalemanyo/csspin-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/elalemanyo/csspin-rails
+  source_code_uri: https://github.com/elalemanyo/csspin-rails
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Pin CSS dependencies into Rails vendor assets
+test_files: []