npm_extractor 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ee218e1b1a49682045cab6aeff12038c7f0d75955fb7d224424fedccb7331529
+  data.tar.gz: f59e7f9d0172ca39e60a3891539c3b24b630676b4f0e98c7191d9d1cac0c1ef4
+SHA512:
+  metadata.gz: 5b19aea65f315a2d30542c1f35132c964af59ff3eda2cfda01c45c0912d89719aaeeec96e5c24b2782367400a791bbadfb23aec51a95d97202e8fc5dad604386
+  data.tar.gz: 46460ac426fbc23cae612fb34eb51569198f2e063f48f21cd8e3d1bc48a7c16c703892c3b4dcd0a08dc49cca4c45843457f8df3bb65a0fb62042b911520c5adf

data/.devcontainer/devcontainer.json

@@ -0,0 +1,7 @@
+{
+  "image": "mcr.microsoft.com/devcontainers/universal:2",
+  "features": {
+    "ghcr.io/devcontainers/features/ruby:1": {},
+    "ghcr.io/roul/devcontainer-features/bitwarden-cli:1": {}
+  }
+}

data/.gitignore

@@ -0,0 +1,56 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+# Ignore Byebug command history file.
+.byebug_history
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+# .rubocop-https?--*

data/.rubocop.yml

@@ -0,0 +1,14 @@
+AllCops:
+  TargetRubyVersion: 3.1
+  SuggestExtensions: false
+  NewCops: enable
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+plugins:
+  - rubocop-minitest
+  - rubocop-rake

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-11-10
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Daniel Bub
+
+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 to 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,284 @@
+# npm-extractor
+
+A Ruby gem to support obtaining assets from npm. Perfect for vendoring frontend assets in Ruby projects without requiring Node.js or npm installed.
+
+## Features
+
+- 🚀 Download NPM packages directly from the NPM registry
+- 🎯 Selective file extraction with wildcard support (`*` and `**`)
+- 📦 Automatic version resolution (latest or specific versions)
+- 🔧 Zero external dependencies (uses only Ruby standard library)
+- 🛠️ Easy integration with Rake tasks and build processes
+- 🎨 Perfect for Rails asset pipeline integration
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'npm_extractor'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install npm_extractor
+```
+
+## Usage
+
+### Basic Usage
+
+```ruby
+require 'npm_extractor'
+
+# Define file mappings
+file_mapping = {
+  'package/dist/**/*.css' => './app/assets/stylesheets/vendor/',
+  'package/dist/**/*.js' => './app/assets/javascripts/vendor/'
+}
+
+# Extract latest version
+NpmExtractor::Extractor.extract_npm_package('pure-uikit', file_mapping)
+
+# Or specify a specific version
+NpmExtractor::Extractor.extract_npm_package('pure-uikit', file_mapping, version: '1.6.38')
+```
+
+### Wildcard Patterns
+
+The gem supports two types of wildcards:
+
+- `*` - Matches any characters except `/` (single directory level)
+- `**` - Matches any characters including `/` (recursive, all subdirectories)
+
+**Examples:**
+
+```ruby
+file_mapping = {
+  # Extract a specific file
+  'package/LICENSE' => './vendor/licenses/pure-uikit-LICENSE',
+  
+  # Extract all CSS files from dist directory (non-recursive)
+  'package/dist/*.css' => './public/css/',
+  
+  # Extract all JS files recursively from dist and subdirectories
+  'package/dist/**/*.js' => './public/js/',
+  
+  # Extract entire directory tree
+  'package/dist/**' => './vendor/pure-uikit/',
+  
+  # Extract all JSON files from anywhere in package
+  'package/**/*.json' => './config/'
+}
+```
+
+### Rake Task Integration
+
+Create a Rake task in your `Rakefile` or `lib/tasks/npm_assets.rake`:
+
+```ruby
+require 'npm_extractor'
+
+namespace :assets do
+  desc "Download frontend assets from NPM"
+  task :download_npm do
+    # Download Bootstrap
+    bootstrap_mapping = {
+      'package/dist/css/**' => 'app/assets/stylesheets/bootstrap/',
+      'package/dist/js/**' => 'app/assets/javascripts/bootstrap/'
+    }
+    NpmExtractor::Extractor.extract_npm_package('bootstrap', bootstrap_mapping)
+    
+    # Download Pure UI Kit
+    pure_ui_mapping = {
+      'package/dist/**' => 'vendor/assets/pure-uikit/'
+    }
+    NpmExtractor::Extractor.extract_npm_package('pure-uikit', pure_ui_mapping)
+    
+    puts "✅ All NPM assets downloaded!"
+  end
+end
+
+# Hook into Rails asset precompilation
+if Rake::Task.task_defined?('assets:precompile')
+  Rake::Task['assets:precompile'].enhance(['assets:download_npm'])
+end
+```
+
+Then run:
+
+```bash
+rake assets:download_npm
+```
+
+### Rails Integration Example
+
+For a Rails application, you might want to download assets before deployment:
+
+**lib/tasks/frontend_assets.rake:**
+
+```ruby
+namespace :frontend do
+  desc "Download all frontend dependencies from NPM"
+  task :setup do
+    require 'npm_extractor'
+    
+    packages = {
+      'pure-uikit' => {
+        'package/dist/**/*.css' => 'app/assets/stylesheets/vendor/pure-uikit/',
+        'package/dist/**/*.js' => 'app/assets/javascripts/vendor/pure-uikit/'
+      },
+      'htmx.org' => {
+        'package/dist/htmx.min.js' => 'app/assets/javascripts/vendor/htmx.js'
+      },
+      'alpinejs' => {
+        'package/dist/cdn.min.js' => 'app/assets/javascripts/vendor/alpine.js'
+      }
+    }
+    
+    packages.each do |package_name, file_mapping|
+      puts "\n📦 Downloading #{package_name}..."
+      NpmExtractor::Extractor.extract_npm_package(package_name, file_mapping)
+    end
+    
+    puts "\n✅ All frontend assets installed!"
+  end
+end
+```
+
+### Standalone Script Example
+
+```ruby
+#!/usr/bin/env ruby
+require 'npm_extractor'
+
+# Download specific version of a package
+NpmExtractor::Extractor.extract_npm_package(
+  'lodash',
+  {
+    'package/lodash.min.js' => './public/vendor/lodash.js',
+    'package/LICENSE' => './public/vendor/lodash-LICENSE'
+  },
+  version: '4.17.21'
+)
+
+puts "Lodash installed!"
+```
+
+## Understanding NPM Package Structure
+
+NPM packages in tarballs are typically extracted with a `package/` prefix. This means:
+
+- Package root becomes: `package/`
+- Package's `dist/` folder becomes: `package/dist/`
+- Package's `LICENSE` file becomes: `package/LICENSE`
+
+Always include `package/` in your file mapping patterns!
+
+## Common Use Cases
+
+### 1. Vendor CSS Frameworks
+
+```ruby
+# Tailwind CSS
+NpmExtractor::Extractor.extract_npm_package('tailwindcss', {
+  'package/dist/tailwind.min.css' => './public/css/tailwind.css'
+})
+```
+
+### 2. Download JavaScript Libraries
+
+```ruby
+# Chart.js
+NpmExtractor::Extractor.extract_npm_package('chart.js', {
+  'package/dist/chart.min.js' => './public/js/chart.js',
+  'package/dist/chart.min.js.map' => './public/js/chart.min.js.map'
+})
+```
+
+### 3. Extract Documentation or Licenses
+
+```ruby
+# Get all markdown files
+NpmExtractor::Extractor.extract_npm_package('some-package', {
+  'package/**/*.md' => './docs/vendor/some-package/',
+  'package/LICENSE' => './licenses/some-package-LICENSE'
+})
+```
+
+### 4. Download Web Components
+
+```ruby
+# Shoelace (Web Components)
+NpmExtractor::Extractor.extract_npm_package('@shoelace-style/shoelace', {
+  'package/dist/**' => './public/shoelace/'
+})
+```
+
+## Error Handling
+
+The extractor will raise errors for:
+
+- Non-existent packages
+- Network issues
+- Invalid package versions
+- Write permission errors
+
+Wrap your calls in begin/rescue blocks for custom error handling:
+
+```ruby
+begin
+  NpmExtractor::Extractor.extract_npm_package('my-package', file_mapping)
+rescue StandardError => e
+  puts "Failed to download package: #{e.message}"
+  exit 1
+end
+```
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bin/setup    # Install dependencies
+bin/test     # Run tests
+rake         # Run tests and rubocop
+```
+
+To install this gem onto your local machine:
+
+```bash
+bundle exec rake install
+```
+
+To release a new version:
+
+1. Update the version number in `lib/npm_extractor/version.rb`
+2. Run `bundle exec rake release` to create a git tag and push to RubyGems
+
+## Testing
+
+Run the test suite:
+
+```bash
+rake test
+```
+
+Run a specific test:
+
+```bash
+ruby -Ilib:test test/npm_extractor/extractor_test.rb -n test_extract_license_from_acme_package
+```
+
+**Note:** Tests make real network requests to the NPM registry and require an internet connection.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/npm_extractor/extractor.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "rubygems/package"
+require "zlib"
+require "fileutils"
+require "json"
+
+module NpmExtractor
+  # Extractor downloads NPM packages and selectively extract assets from provided release.
+  #
+  # Example:
+  #   Extractor.extract_npm_package('example',{'package/LICENSE' => 'vendor/example/LICENSE'})
+  class Extractor
+    def self.extract_npm_package(package_name, file_mapping, version: "latest")
+      new.extract_npm_package(package_name, file_mapping, version: version)
+    end
+
+    def extract_npm_package(package_name, file_mapping, version: "latest")
+      registry_url = "https://registry.npmjs.org/#{package_name}/#{version}"
+
+      puts "Fetching package metadata from #{registry_url}..."
+
+      package_info = JSON.parse(safe_fetch(registry_url).body)
+      tarball_url = package_info["dist"]["tarball"]
+      package_version = package_info["version"]
+
+      puts "Found version #{package_version}"
+      puts "Downloading from #{tarball_url}..."
+
+      extract_tgz_files(tarball_url, file_mapping)
+    end
+
+    def extract_tgz_files(url, file_mapping)
+      tgz_file = nil
+
+      begin
+        npm_response = safe_fetch(url)
+
+        tgz_file = Tempfile.new(["archive", ".tgz"])
+        tgz_file.binmode
+        tgz_file.write(npm_response.read_body)
+        tgz_file.close
+
+        Zlib::GzipReader.open(tgz_file.path) do |gz|
+          Gem::Package::TarReader.new(gz) do |tar|
+            tar.each do |entry|
+              next if entry.directory?
+
+              matched_pattern, destination_base = find_matching_pattern(entry.full_name, file_mapping)
+              next unless matched_pattern
+
+              destination = calculate_destination(entry.full_name, matched_pattern, destination_base)
+
+              FileUtils.mkdir_p(File.dirname(destination))
+
+              File.binwrite(destination, entry.read)
+
+              puts "Extracted: #{entry.full_name} -> #{destination}"
+            end
+          end
+        end
+
+        puts "Extraction complete!"
+      rescue StandardError => e
+        puts "Error: #{e.message}"
+        raise
+      ensure
+        tgz_file&.unlink
+      end
+    end
+
+    private
+
+    def find_matching_pattern(file_path, file_mapping)
+      file_mapping.each do |pattern, destination|
+        if pattern.include?("*")
+          regex_pattern = pattern.gsub("**", "|DOUBLE|")
+                                 .gsub("*", "[^/]*")
+                                 .gsub("|DOUBLE|", ".*")
+          regex = /^#{regex_pattern}$/
+
+          return [pattern, destination] if file_path.match?(regex)
+        elsif file_path == pattern
+          return [pattern, destination]
+        end
+      end
+      nil
+    end
+
+    def calculate_destination(file_path, pattern, destination_base)
+      if pattern.include?("*")
+        prefix = pattern.split("*").first
+        relative_path = file_path.sub(/^#{Regexp.escape(prefix)}/, "")
+        File.join(destination_base, relative_path)
+      else
+        destination_base
+      end
+    end
+
+    def safe_fetch(uri_str, max_redirects: 5)
+      uri = URI.parse(uri_str)
+
+      redirects = 0
+      loop do
+        http = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https")
+        req = Net::HTTP::Get.new(uri)
+        res = http.request(req)
+
+        case res
+        when Net::HTTPSuccess
+          return res
+        when Net::HTTPRedirection
+          raise "Too many redirects" if (redirects += 1) > max_redirects
+
+          uri = URI.parse(res["location"])
+          next
+        else
+          raise "HTTP error: #{res.code}"
+        end
+      end
+    end
+  end
+end

data/lib/npm_extractor/version.rb

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

data/lib/npm_extractor.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "npm_extractor/version"
+require_relative "npm_extractor/extractor"
+
+module NpmExtractor
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: npm_extractor
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Daniel Bub
+bindir: bin
+cert_chain: []
+date: 2025-11-10 00:00:00.000000000 Z
+dependencies: []
+description: A Ruby gem that downloads NPM packages and selectively extracts files
+  using wildcard patterns.
+email:
+- thebub@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".devcontainer/devcontainer.json"
+- ".gitignore"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/npm_extractor.rb
+- lib/npm_extractor/extractor.rb
+- lib/npm_extractor/version.rb
+homepage: https://github.com/thebub/npm_extractor
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/thebub/npm_extractor
+  source_code_uri: https://github.com/yourusername/npm_extractor
+  changelog_uri: https://github.com/yourusername/npm_extractor/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Extract files from NPM packages with selective file mapping
+test_files: []