hanami-sprockets 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c506dbf07d8b95e741306b6511182bc1428913b4f081f09a5727143de9f27ba3
+  data.tar.gz: d307f243f6ea655eeeafbddf4b326cd75307ea25321b75215a933563543a456a
+SHA512:
+  metadata.gz: cff9adcbec8df4c221ab3df289b7f33d8065dc12e98f6cb959c0e7828ea1cc01e9208ebba5c7f18d14338244b55160b04fde1e6fabd183b5a2b3beae26163815
+  data.tar.gz: cddf52b5cd2a4c5c968c3d11504f19bae75249239685f4a92664ea93264ed410f2ac625ce1f0954c69759f302bec0d21cfa9b03a055b521c3568b9fe40609f5d

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-09-29
+### Added
+- Initial release
+- Full Sprockets integration with Rails-like asset pipeline
+- Asset fingerprinting and cache busting
+- Development middleware for on-the-fly asset serving
+- Template helpers (stylesheet_tag, javascript_tag, image_tag)
+- Asset precompilation for production
+- Subresource Integrity (SRI) support
+- Cross-origin request detection
+- Compatible with existing Sprockets ecosystem gems
+- No npm/Node.js dependencies required
+- Comprehensive test suite
+- Hanami-compatible API matching original hanami-assets

data/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Andrew Nesbitt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject so the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,234 @@
+# Hanami::Sprockets
+
+Drop-in replacement for hanami-assets that uses Sprockets (like Rails) instead of npm/Node.js.
+
+If you want the Rails asset pipeline in your Hanami app without dealing with npm, this is for you.
+
+## What you get
+
+- Rails-style Sprockets asset pipeline
+- No npm/package.json required
+- Works with existing Sprockets gems (sassc-rails, coffee-rails, etc.)
+- Same API as hanami-assets
+- Asset fingerprinting and precompilation
+- Development middleware for serving assets
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hanami-sprockets'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+## Basic Usage
+
+### Configuration
+
+```ruby
+require 'hanami-sprockets'
+
+# Basic configuration
+config = Hanami::Assets::Config.new(
+  path_prefix: "/assets",
+  digest: true,  # Enable fingerprinting for production
+  subresource_integrity: [:sha256]  # Enable SRI
+)
+
+# Create assets instance
+assets = Hanami::Assets.new(
+  config: config,
+  root: "/path/to/your/app"
+)
+```
+
+### Asset Structure
+
+Follow Rails conventions:
+
+```
+app/
+├── assets/
+│   ├── stylesheets/
+│   │   └── app.css
+│   ├── javascripts/
+│   │   └── app.js
+│   └── images/
+│       └── logo.png
+├── lib/
+│   └── assets/
+└── vendor/
+    └── assets/
+```
+
+### CSS Image References
+
+Reference images in CSS using ERB and the `asset_path` helper:
+
+```css
+/* app.css.erb */
+.header {
+  background-image: url('<%= asset_path("logo.png") %>');
+}
+```
+
+This generates fingerprinted URLs automatically in production. Plain CSS with relative paths also works:
+
+```css
+/* Plain CSS */
+.simple {
+  background-image: url('../images/logo.png');
+}
+```
+
+### Development Server
+
+Add the middleware to your Rack stack:
+
+```ruby
+use Hanami::Assets::Middleware, assets
+```
+
+### Using Assets
+
+```ruby
+# Get an asset
+asset = assets["app.css"]
+puts asset.url  # => "/assets/app-abc123def.css"
+puts asset.path # => "/assets/app-abc123def.css"
+puts asset.sri  # => "sha256-..."
+
+# Check if asset exists
+begin
+  asset = assets["missing.css"]
+rescue Hanami::Assets::AssetMissingError
+  puts "Asset not found"
+end
+```
+
+### Template Helpers
+
+Include the helpers in your templates:
+
+```ruby
+class MyView
+  include Hanami::Assets::Helpers
+
+  private
+
+  def hanami_assets
+    @hanami_assets # Inject your assets instance
+  end
+end
+```
+
+Then use them in templates:
+
+```erb
+<!DOCTYPE html>
+<html>
+<head>
+  <%= stylesheet_tag "reset", "app" %>
+</head>
+<body>
+  <%= image_tag "logo", alt: "Logo" %>
+  <%= javascript_tag "app", async: true %>
+</body>
+</html>
+```
+
+### Precompilation
+
+For production:
+
+```ruby
+# Precompile assets
+manifest = assets.precompile("/path/to/public/assets")
+puts "Compiled assets:", manifest.assets.keys
+```
+
+## Advanced Configuration
+
+```ruby
+config = Hanami::Assets::Config.new do |config|
+  config.path_prefix = "/assets"
+  config.digest = Rails.env.production?
+  config.compress = Rails.env.production?
+  config.subresource_integrity = [:sha256, :sha512]
+  config.base_url = ENV['CDN_URL'] # For CDN support
+  config.asset_paths = [
+    "vendor/assets/custom",
+    "lib/special_assets"
+  ]
+  config.precompile = %w[
+    app.js
+    app.css
+    *.png
+    *.jpg
+    *.svg
+  ]
+end
+```
+
+## Adding processors
+
+Just add the gems you want:
+
+```ruby
+gem 'sassc-rails'      # SCSS/Sass
+gem 'coffee-rails'     # CoffeeScript
+gem 'uglifier'         # JS compression
+```
+
+## Development vs Production
+
+- **Development**: Assets served on-demand via middleware
+- **Production**: Precompile assets with `assets.precompile("/path/to/public/assets")`
+
+## API Reference
+
+### Hanami::Assets
+
+Main class for asset management.
+
+#### Methods
+
+- `#[](path)` - Find and return an asset
+- `#precompile(target_dir)` - Precompile assets for production
+- `#logical_paths` - Get all available asset paths
+- `#subresource_integrity?` - Check if SRI is enabled
+- `#crossorigin?(url)` - Check if URL is cross-origin
+
+### Hanami::Assets::Asset
+
+Represents a single asset.
+
+#### Methods
+
+- `#url` - Full URL to asset
+- `#path` - Path to asset (without base URL)
+- `#sri` - Subresource integrity hash
+- `#logical_path` - Original path without fingerprint
+- `#digest_path` - Fingerprinted path
+
+### Hanami::Assets::Helpers
+
+Template helpers for generating asset HTML tags.
+
+#### Methods
+
+- `stylesheet_tag(*sources, **options)` - Generate `<link>` tags
+- `javascript_tag(*sources, **options)` - Generate `<script>` tags
+- `image_tag(source, **options)` - Generate `<img>` tags
+- `asset_url(source)` - Get URL for asset
+- `asset_path(source)` - Get path for asset
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/hanami-sprockets.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "hanami/sprockets/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "hanami-sprockets"
+  spec.version       = Hanami::Assets::VERSION
+  spec.authors       = ["Andrew Nesbitt"]
+  spec.email         = ["andrewnez@gmail.com"]
+  spec.summary       = "Sprockets-based assets management for Hanami"
+  spec.description   = "Alternative to hanami-assets that uses Sprockets for asset compilation and management, compatible with existing Sprockets gems"
+  spec.homepage      = "https://github.com/andrew/hanami-sprockets"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -- lib/* bin/* CHANGELOG.md LICENSE.md README.md hanami-sprockets.gemspec`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+  spec.metadata["rubygems_mfa_required"] = "true"
+  spec.required_ruby_version = ">= 3.1"
+
+  spec.add_dependency "sprockets", "~> 4.0"
+  spec.add_dependency "zeitwerk", "~> 2.6"
+  spec.add_dependency "base64", "~> 0.1"
+  spec.add_dependency "hanami-view", "~> 2.1"
+
+  spec.add_development_dependency "bundler", ">= 1.6", "< 3"
+  spec.add_development_dependency "rake", "~> 13"
+  spec.add_development_dependency "rspec", "~> 3.9"
+  spec.add_development_dependency "rubocop", "~> 1.0"
+  spec.add_development_dependency "rack", "~> 2.2"
+  spec.add_development_dependency "rack-test", "~> 1.1"
+  spec.add_development_dependency "dry-configurable", "~> 1.1"
+  spec.add_development_dependency "dry-inflector", "~> 1.0"
+end

data/lib/hanami/sprockets/asset.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Hanami
+  class Assets
+    # Represents a single front end asset.
+    #
+    # @api public
+    # @since 0.1.0
+    class Asset
+      # @api private
+      # @since 0.1.0
+      attr_reader :config
+      private :config
+
+      # Returns the asset's absolute URL path.
+      #
+      # @example Asset from local dev server
+      #   asset.path # => "/assets/app.js"
+      #
+      # @example Deployed asset with fingerprinted name
+      #   asset.path # => "/assets/app-28a6b886de2372ee3922fcaf3f78f2d8.js"
+      #
+      # @return [String]
+      #
+      # @api public
+      # @since 0.1.0
+      attr_reader :path
+
+      # @api private
+      # @since 0.1.0
+      attr_reader :base_url
+      private :base_url
+
+      # Returns the asset's subresource integrity value, or nil if none is available.
+      #
+      # @return [String, nil]
+      #
+      # @api public
+      # @since 0.1.0
+      attr_reader :sri
+
+      # Returns the asset's logical path (original path without fingerprinting)
+      #
+      # @return [String]
+      #
+      # @api public
+      # @since 0.1.0
+      attr_reader :logical_path
+
+      # Returns the asset's digest path (fingerprinted path)
+      #
+      # @return [String]
+      #
+      # @api public
+      # @since 0.1.0
+      attr_reader :digest_path
+
+      # Returns the asset's content type
+      #
+      # @return [String]
+      #
+      # @api public
+      # @since 0.1.0
+      attr_reader :content_type
+
+      # Returns the asset's source content
+      #
+      # @return [String]
+      #
+      # @api public
+      # @since 0.1.0
+      attr_reader :source
+
+      # @api private
+      # @since 0.1.0
+      def initialize(path:, base_url:, sri: nil, logical_path: nil, digest_path: nil, content_type: nil, source: nil)
+        @path = path
+        @base_url = base_url
+        @sri = sri
+        @logical_path = logical_path
+        @digest_path = digest_path
+        @content_type = content_type
+        @source = source
+      end
+
+      # @api public
+      # @since 0.1.0
+      alias_method :subresource_integrity_value, :sri
+
+      # Returns the asset's full URL.
+      #
+      # @example Asset from local dev server
+      #   asset.url # => "https://example.com/assets/app.js"
+      #
+      # @example Deployed asset with fingerprinted name
+      #   asset.url # => "https://example.com/assets/app-28a6b886de2372ee3922fcaf3f78f2d8.js"
+      #
+      # @return [String]
+      #
+      # @api public
+      # @since 0.1.0
+      def url
+        base_url.join(path)
+      end
+
+      # Returns the asset's full URL
+      #
+      # @return [String]
+      #
+      # @see #url
+      #
+      # @api public
+      # @since 0.1.0
+      def to_s
+        url
+      end
+    end
+  end
+end

data/lib/hanami/sprockets/base_url.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Hanami
+  class Assets
+    # Base URL for assets
+    #
+    # @api private
+    # @since 0.1.0
+    class BaseUrl
+      # @api private
+      # @since 0.1.0
+      attr_reader :url
+
+      # @api private
+      # @since 0.1.0
+      def initialize(url = "")
+        @url = url.to_s
+      end
+
+      # Join the base URL with a path
+      #
+      # @param path [String] the path to join
+      #
+      # @return [String] the full URL
+      #
+      # @api private
+      # @since 0.1.0
+      def join(path)
+        return path if url.empty?
+
+        if url.end_with?("/")
+          url + path.sub(%r{^/}, "")
+        else
+          url + path
+        end
+      end
+
+      # Returns true if the given source is linked via Cross-Origin policy
+      #
+      # @param source [String] the source URL
+      #
+      # @return [Boolean]
+      #
+      # @api private
+      # @since 0.1.0
+      def crossorigin?(source)
+        return false if url.empty?
+
+        begin
+          base_uri = URI.parse(url)
+          source_uri = URI.parse(source)
+
+          base_uri.host != source_uri.host || base_uri.port != source_uri.port || base_uri.scheme != source_uri.scheme
+        rescue URI::InvalidURIError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/hanami/sprockets/config.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "dry/configurable"
+require_relative "base_url"
+
+module Hanami
+  class Assets
+    # Hanami sprockets configuration.
+    #
+    # @api public
+    # @since 0.1.0
+    class Config
+      include Dry::Configurable
+
+      # @api public
+      # @since 0.1.0
+      BASE_URL = ""
+      private_constant :BASE_URL
+
+      # @!attribute [rw] path_prefix
+      #   @return [String]
+      #
+      #   @api public
+      #   @since 0.1.0
+      setting :path_prefix, default: "/assets"
+
+      # @!attribute [rw] subresource_integrity
+      #   @return [Array<Symbol>]
+      #
+      #   @example
+      #     config.subresource_integrity # => [:sha256, :sha512]
+      #
+      #   @api public
+      #   @since 0.1.0
+      setting :subresource_integrity, default: []
+
+      # @!attribute [rw] base_url
+      #   @return [BaseUrl]
+      #
+      #   @example
+      #     config.base_url = "http://some-cdn.com/assets"
+      #
+      #   @api public
+      #   @since 0.1.0
+      setting :base_url, constructor: -> url { BaseUrl.new(url.to_s) }
+
+      # @!attribute [rw] asset_paths
+      #   @return [Array<String>]
+      #
+      #   @api public
+      #   @since 0.1.0
+      setting :asset_paths, default: []
+
+      # @!attribute [rw] precompile
+      #   @return [Array<String>]
+      #
+      #   @api public
+      #   @since 0.1.0
+      setting :precompile, default: %w[*.js *.css *.png *.jpg *.gif *.svg]
+
+      # @!attribute [rw] digest
+      #   @return [Boolean] Whether to use fingerprinted asset names
+      #
+      #   @api public
+      #   @since 0.1.0
+      setting :digest, default: true
+
+      # @!attribute [rw] compress
+      #   @return [Boolean] Whether to compress assets
+      #
+      #   @api public
+      #   @since 0.1.0
+      setting :compress, default: true
+
+      # @!attribute [rw] cache
+      #   @return [String, nil] Cache directory path
+      #
+      #   @api public
+      #   @since 0.1.0
+      setting :cache, default: nil
+
+      # @api public
+      # @since 0.1.0
+      def initialize(**values)
+        super()
+
+        config.update(values.select { |k| _settings.key?(k) })
+
+        yield(config) if block_given?
+      end
+
+      # Returns true if the given source is linked via Cross-Origin policy (or in other words, if
+      # the given source does not satisfy the Same-Origin policy).
+      #
+      # @param source [String]
+      #
+      # @return [Boolean]
+      #
+      # @see https://en.wikipedia.org/wiki/Same-origin_policy#Origin_determination_rules
+      # @see https://en.wikipedia.org/wiki/Same-origin_policy#document.domain_property
+      #
+      # @api private
+      # @since 0.1.0
+      def crossorigin?(source)
+        base_url.crossorigin?(source)
+      end
+
+      private
+
+      def method_missing(name, ...)
+        if config.respond_to?(name)
+          config.public_send(name, ...)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(name, _incude_all = false)
+        config.respond_to?(name) || super
+      end
+    end
+  end
+end

data/lib/hanami/sprockets/errors.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Hanami
+  class Assets
+    # Base error for Hanami::Assets
+    #
+    # @since 0.1.0
+    class Error < StandardError
+    end
+
+    # Error raised when a requested asset cannot be found
+    #
+    # @since 0.1.0
+    class AssetMissingError < Error
+      def initialize(path)
+        super("Missing asset: #{path}")
+      end
+    end
+
+    # Error raised when the asset manifest cannot be found
+    #
+    # @since 0.1.0
+    class ManifestMissingError < Error
+      def initialize(path)
+        super("Missing manifest: #{path}")
+      end
+    end
+  end
+end