bake-node 0.0.1

data/lib/bake/node/manifest.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "digest"
+require "json"
+require "pathname"
+
+require_relative "errors"
+
+module Bake
+	module Node
+		# Records the content and import mappings of a static package projection.
+		class Manifest
+			FILENAME = ".bake-node.json"
+			
+			# Build a deterministic manifest.
+			# @parameter base [String] The public URL prefix for static packages.
+			# @parameter imports [Hash(String, String)] The import-map entries.
+			# @parameter packages [Hash(String, Hash)] The installed package metadata.
+			# @returns [Manifest] The generated manifest.
+			def self.build(base:, imports:, packages:)
+				data = {
+					"format" => 1,
+					"base" => base,
+					"imports" => imports.sort.to_h,
+					"packages" => packages.sort.to_h,
+				}
+				
+				data["digest"] = Digest::SHA256.hexdigest(JSON.generate(data))
+				new(data)
+			end
+			
+			# Load a manifest from a static output directory.
+			# @parameter root [String | Pathname] The static output directory.
+			# @returns [Manifest] The loaded manifest.
+			# @raises [CheckError] If the manifest is missing or malformed.
+			def self.load(root)
+				path = Pathname.new(root) + FILENAME
+				new(JSON.parse(path.read))
+			rescue Errno::ENOENT
+				raise CheckError, "Static package manifest does not exist at #{path}!"
+			rescue JSON::ParserError => error
+				raise CheckError, "Could not parse #{path}: #{error.message}"
+			end
+			
+			# Initialize a manifest with its serialized data.
+			# @parameter data [Hash] The manifest data.
+			def initialize(data)
+				@data = data
+			end
+			
+			# @attribute [Hash] The serialized manifest data.
+			attr :data
+			
+			# Write the manifest into a static output directory.
+			# @parameter root [String | Pathname] The static output directory.
+			# @returns [Integer] The number of bytes written.
+			def write(root)
+				path = Pathname.new(root) + FILENAME
+				path.write(JSON.pretty_generate(@data) + "\n")
+			end
+			
+			# Extract the browser import map.
+			# @returns [Hash] An import-map object containing the configured imports.
+			def import_map
+				{"imports" => @data.fetch("imports", {})}
+			end
+			
+			# Check whether every manifested file exists with the expected content.
+			# @parameter root [String | Pathname] The static output directory.
+			# @returns [Boolean] Whether the directory exactly matches the manifest.
+			def valid_tree?(root)
+				root = Pathname.new(root)
+				expected = []
+				
+				@data.fetch("packages").each do |name, package|
+					package.fetch("files").each do |relative_path, digest|
+						path = root + name + relative_path
+						expected << path.relative_path_from(root).to_s
+						
+						return false unless path.file?
+						return false unless Digest::SHA256.file(path).hexdigest == digest
+					end
+				end
+				
+				actual = root.glob("**/*", File::FNM_DOTMATCH).select(&:file?).map do |path|
+					path.relative_path_from(root).to_s
+				end
+				actual.delete(FILENAME)
+				
+				actual.sort == expected.sort
+			end
+		end
+	end
+end

data/lib/bake/node/package.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "pathname"
+
+require_relative "errors"
+
+module Bake
+	module Node
+		# Describes how one installed Node.js package is exposed as static files.
+		class Package
+			NAME_PATTERN = /\A(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+\z/i
+			
+			# Initialize a package selection.
+			# @parameter name [String] The npm package name, including an optional scope.
+			# @parameter options [Hash] The package's source, include patterns and import mappings.
+			# @raises [ConfigurationError] If the package name or options are invalid.
+			def initialize(name, options = {})
+				unless name.is_a?(String) && NAME_PATTERN.match?(name)
+					raise ConfigurationError, "Invalid package name: #{name.inspect}!"
+				end
+				
+				unless options.is_a?(Hash)
+					raise ConfigurationError, "Configuration for #{name} must be an object!"
+				end
+				
+				@name = name
+				@source = options["source"]
+				@include_patterns = options["include"]
+				@imports = options.fetch("imports", {})
+				
+				validate
+			end
+			
+			# @attribute [String] The npm package name.
+			attr :name
+			
+			# @attribute [String | Nil] The configured package-relative source directory.
+			attr :source
+			
+			# @attribute [Array(String) | Nil] The package-relative file patterns to include.
+			attr :include_patterns
+			
+			# @attribute [Hash(String, String)] The import specifiers exposed by the package.
+			attr :imports
+			
+			private
+			
+			def validate
+				validate_relative_path(@source, "source") if @source
+				
+				if @include_patterns
+					unless @include_patterns.is_a?(Array) && @include_patterns.any?
+						raise ConfigurationError, "The include patterns for #{@name} must be a non-empty array!"
+					end
+					
+					@include_patterns.each do |pattern|
+						validate_relative_path(pattern, "include pattern")
+					end
+				end
+				
+				unless @imports.is_a?(Hash) && @imports.all?{|key, value| key.is_a?(String) && value.is_a?(String)}
+					raise ConfigurationError, "The imports for #{@name} must map strings to strings!"
+				end
+			end
+			
+			def validate_relative_path(path, description)
+				unless path.is_a?(String) && !path.empty?
+					raise ConfigurationError, "The #{description} for #{@name} must be a non-empty string!"
+				end
+				
+				pathname = Pathname.new(path)
+				
+				if pathname.absolute? || pathname.each_filename.any?{|component| component == ".."}
+					raise ConfigurationError, "The #{description} for #{@name} must remain within the package: #{path.inspect}!"
+				end
+			end
+		end
+	end
+end

data/lib/bake/node/package_manager.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "errors"
+
+module Bake
+	module Node
+		# Detects and invokes npm-compatible package managers without replacing them.
+		class PackageManager
+			LOCK_FILES = {
+				"package-lock.json" => "npm",
+				"npm-shrinkwrap.json" => "npm",
+				"pnpm-lock.yaml" => "pnpm",
+				"yarn.lock" => "yarn",
+				"bun.lock" => "bun",
+				"bun.lockb" => "bun",
+			}.freeze
+			
+			SUPPORTED = ["npm", "pnpm", "yarn", "bun"].freeze
+			
+			# Detect the package manager selected by a project.
+			# @parameter configuration [Configuration] The project configuration.
+			# @parameter environment [Hash] Environment variables used for explicit selection.
+			# @returns [PackageManager] The selected package-manager wrapper.
+			# @raises [ConfigurationError] If selection is ambiguous or unsupported.
+			def self.detect(configuration, environment: ENV)
+				if name = environment["NODE_PACKAGE_MANAGER"]
+					return new(configuration.root, name)
+				end
+				
+				if declaration = configuration.package_json["packageManager"]
+					unless declaration.is_a?(String)
+						raise ConfigurationError, "packageManager must be a string!"
+					end
+					
+					return new(configuration.root, declaration.split("@", 2).first)
+				end
+				
+				managers = LOCK_FILES.filter_map do |path, manager|
+					manager if (configuration.root + path).file?
+				end.uniq
+				
+				if managers.size > 1
+					raise ConfigurationError, "Multiple package manager lock files were found: #{managers.join(', ')}!"
+				end
+				
+				new(configuration.root, managers.first || "npm")
+			end
+			
+			# Initialize a package-manager wrapper.
+			# @parameter root [String | Pathname] The directory in which commands will run.
+			# @parameter name [String] The package-manager executable name.
+			# @raises [ConfigurationError] If the package manager is unsupported.
+			def initialize(root, name)
+				unless SUPPORTED.include?(name)
+					raise ConfigurationError, "Unsupported package manager: #{name.inspect}!"
+				end
+				
+				@root = root
+				@name = name
+			end
+			
+			# @attribute [String | Pathname] The directory in which commands run.
+			attr :root
+			
+			# @attribute [String] The selected package-manager name.
+			attr :name
+			
+			# Install the project's dependencies.
+			# @parameter frozen [Boolean] Whether the lock file must remain unchanged.
+			# @raises [Error] If the package-manager command fails.
+			def install(frozen: false)
+				execute(install_command(frozen: frozen))
+			end
+			
+			# Run a package script.
+			# @parameter script [String] The script name from `package.json`.
+			# @raises [ArgumentError] If the script name is empty.
+			# @raises [Error] If the package-manager command fails.
+			def run(script)
+				unless script.is_a?(String) && !script.empty?
+					raise ArgumentError, "Script must be a non-empty string!"
+				end
+				
+				execute([@name, "run", script])
+			end
+			
+			# Construct the installation command for the selected package manager.
+			# @parameter frozen [Boolean] Whether the lock file must remain unchanged.
+			# @returns [Array(String)] The command and arguments to execute.
+			def install_command(frozen: false)
+				command = case @name
+				when "npm"
+					frozen ? ["npm", "ci"] : ["npm", "install"]
+				when "pnpm"
+					["pnpm", "install"]
+				when "yarn"
+					["yarn", "install"]
+				when "bun"
+					["bun", "install"]
+				end
+				
+				if frozen && @name != "npm"
+					command << (@name == "yarn" ? "--immutable" : "--frozen-lockfile")
+				end
+				
+				command
+			end
+			
+			private
+			
+			def execute(command)
+				unless system(*command, chdir: @root.to_s)
+					raise Error, "Command failed: #{command.join(' ')}"
+				end
+			end
+		end
+	end
+end

data/lib/bake/node/static.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "digest"
+require "fileutils"
+require "json"
+require "pathname"
+require "tmpdir"
+
+require_relative "errors"
+require_relative "manifest"
+
+module Bake
+	module Node
+		# Builds and validates deterministic static projections of installed packages.
+		class Static
+			EXCLUDED_COMPONENTS = [".git", "node_modules"].freeze
+			
+			# Initialize a static package builder.
+			# @parameter configuration [Configuration] The project configuration.
+			# @parameter output [String | Nil] An optional project-relative output directory.
+			def initialize(configuration, output: nil)
+				@configuration = configuration
+				@output = configuration.output_path(output)
+			end
+			
+			# @attribute [Configuration] The project configuration.
+			attr :configuration
+			
+			# @attribute [Pathname] The static output directory.
+			attr :output
+			
+			# Build and atomically replace the static package projection.
+			# @returns [Manifest] The generated manifest.
+			# @raises [PackageError] If an installed package cannot be materialized safely.
+			def update
+				FileUtils.mkdir_p(@output.dirname)
+				
+				Dir.mktmpdir(".bake-node-", @output.dirname.to_s) do |temporary_root|
+					temporary_root = Pathname.new(temporary_root)
+					staging = temporary_root + "static"
+					backup = temporary_root + "backup"
+					
+					build(staging)
+					replace(staging, backup)
+				end
+				
+				Manifest.load(@output)
+			end
+			
+			# Check whether the static package projection is current.
+			# @returns [Boolean] Whether the installed projection matches the desired output.
+			# @raises [CheckError] If the current manifest is missing or malformed.
+			def check
+				installed = Manifest.load(@output)
+				
+				Dir.mktmpdir("bake-node-check-") do |temporary_root|
+					desired = build(Pathname.new(temporary_root) + "static")
+					
+					return installed.data == desired.data && installed.valid_tree?(@output)
+				end
+			end
+			
+			# Require the static package projection to be current.
+			# @returns [Boolean] `true` when the projection is current.
+			# @raises [CheckError] If the projection is missing or out of date.
+			def check!
+				unless check
+					raise CheckError, "Static Node.js packages are out of date. Run `bake node:packages:static`."
+				end
+				
+				true
+			end
+			
+			private
+			
+			def build(destination)
+				FileUtils.mkdir_p(destination)
+				
+				packages = {}
+				imports = {}
+				
+				@configuration.packages.each_value do |package|
+					package_data, package_imports = install(package, destination)
+					packages[package.name] = package_data
+					
+					package_imports.each do |specifier, path|
+						if imports.key?(specifier)
+							raise ConfigurationError, "Import specifier #{specifier.inspect} is configured more than once!"
+						end
+						
+						imports[specifier] = path
+					end
+				end
+				
+				manifest = Manifest.build(base: @configuration.base, imports: imports, packages: packages)
+				manifest.write(destination)
+				manifest
+			end
+			
+			def install(package, destination)
+				package_path = @configuration.package_root + package.name
+				
+				unless package_path.directory?
+					raise PackageError, "Package #{package.name} was not found at #{package_path}!"
+				end
+				
+				package_root = package_path.realpath
+				source = package.source || default_source(package_root)
+				source_root = resolve_within(package_root, source, "source for #{package.name}")
+				
+				unless source_root.directory?
+					raise PackageError, "Package source does not exist for #{package.name}: #{source_root}!"
+				end
+				
+				paths = included_paths(package, source_root)
+				install_root = destination + package.name
+				files = {}
+				
+				paths.each do |relative_path|
+					source_path = source_root + relative_path
+					install_path = install_root + relative_path
+					
+					FileUtils.mkdir_p(install_path.dirname)
+					FileUtils.cp(source_path, install_path)
+					files[relative_path] = Digest::SHA256.file(install_path).hexdigest
+				end
+				
+				package_json = read_package_json(package_root)
+				imports = resolve_imports(package, install_root)
+				
+				[
+					{
+						"version" => package_json["version"],
+						"source" => source,
+						"files" => files.sort.to_h,
+					},
+					imports,
+				]
+			end
+			
+			def default_source(package_root)
+				(package_root + "dist").directory? ? "dist" : "."
+			end
+			
+			def included_paths(package, source_root)
+				patterns = package.include_patterns || ["**/*"]
+				
+				paths = patterns.flat_map do |pattern|
+					Dir.glob(pattern, File::FNM_DOTMATCH, base: source_root.to_s)
+				end.uniq.sort.select do |relative_path|
+					components = Pathname.new(relative_path).each_filename.to_a
+					next false if components.any?{|component| EXCLUDED_COMPONENTS.include?(component)}
+					
+					path = source_root + relative_path
+					next false unless path.file?
+					
+					resolve_within(source_root, relative_path, "included file for #{package.name}")
+					true
+				end
+				
+				if paths.empty?
+					raise PackageError, "No files matched for #{package.name}!"
+				end
+				
+				paths
+			end
+			
+			def resolve_imports(package, install_root)
+				package.imports.sort.to_h do |specifier, value|
+					if value.match?(/\A(?:[a-z][a-z0-9+.-]*:|\/\/|\/)/i)
+						[specifier, value]
+					else
+						path = install_root + value
+						
+						unless path.file?
+							raise PackageError, "Import #{specifier.inspect} refers to a file which was not installed: #{value.inspect}!"
+						end
+						
+						base = @configuration.base
+						[specifier, "#{base}#{package.name}/#{value}"]
+					end
+				end
+			end
+			
+			def read_package_json(package_root)
+				path = package_root + "package.json"
+				return {} unless path.file?
+				
+				JSON.parse(path.read)
+			rescue JSON::ParserError => error
+				raise PackageError, "Could not parse #{path}: #{error.message}"
+			end
+			
+			def resolve_within(root, relative_path, description)
+				path = (root + relative_path).realpath
+				prefix = root.to_s + File::SEPARATOR
+				
+				unless path == root || path.to_s.start_with?(prefix)
+					raise PackageError, "The #{description} escapes #{root}: #{relative_path.inspect}!"
+				end
+				
+				path
+			rescue Errno::ENOENT
+				raise PackageError, "The #{description} does not exist: #{relative_path.inspect}!"
+			end
+			
+			def replace(staging, backup)
+				File.rename(@output, backup) if @output.exist?
+				
+				begin
+					File.rename(staging, @output)
+				rescue Exception
+					File.rename(backup, @output) if backup.exist? && !@output.exist?
+					raise
+				end
+			end
+		end
+	end
+end

data/lib/bake/node/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+# @namespace
+module Bake
+	# @namespace
+	module Node
+		VERSION = "0.0.1"
+	end
+end

data/lib/bake/node.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "node/version"
+require_relative "node/errors"
+require_relative "node/package"
+require_relative "node/configuration"
+require_relative "node/package_manager"
+require_relative "node/manifest"
+require_relative "node/static"
+require_relative "node/controller"

data/license.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright, 2026, by Samuel Williams.  
+
+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,70 @@
+# Bake Node
+
+Bake Node integrates Node.js packages into Ruby projects using [Bake](https://github.com/ioquatix/bake). It delegates installation and scripts to npm-compatible package managers, then materializes selected packages as deterministic static assets.
+
+[![Development Status](https://github.com/socketry/bake-node/workflows/Test/badge.svg)](https://github.com/socketry/bake-node/actions?workflow=Test)
+
+## Features
+
+  - Supports npm, pnpm, Yarn and Bun without replacing their package-management behavior.
+  - Treats registry dependencies and local workspace packages consistently through `node_modules`.
+  - Copies complete distributions or carefully selected files into `public/_components`.
+  - Generates a deterministic manifest and browser import map.
+  - Provides Bake tasks for installation, scripts, static deployment and verification.
+
+## Usage
+
+Please see the [project documentation](https://socketry.github.io/bake-node/) for more details.
+
+  - [Getting Started](https://socketry.github.io/bake-node/guides/getting-started/index) - This guide explains how to use `bake-node` to install an external JavaScript dependency and expose it as static assets from a Ruby project.
+
+  - [Internal Packages](https://socketry.github.io/bake-node/guides/internal-packages/index) - This guide explains how to organize JavaScript developed inside a Ruby project as independent workspace packages while using Bake Node for testing and static deployment.
+
+  - [Static Packages](https://socketry.github.io/bake-node/guides/static-packages/index) - This guide explains how to control which installed package files are deployed, generate browser import maps and verify the resulting static projection.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/bake-node/releases/index) for all releases.
+
+### v0.0.1
+
+  - [Added](https://socketry.github.io/bake-node/releases/index#added)
+
+## Contributing
+
+We welcome contributions to this project.
+
+1.  Fork the repository.
+2.  Create your feature branch (`git checkout -b my-new-feature`).
+3.  Commit your changes (`git commit -am 'Add some feature.'`).
+4.  Push to the branch (`git push origin my-new-feature`).
+5.  Create a new pull request.
+
+### Running Tests
+
+To run the test suite:
+
+``` bash
+$ bundle exec bake test
+```
+
+### Making Releases
+
+To make a new release:
+
+``` bash
+$ bundle exec bake gem:release:patch # or minor or major
+```
+
+### Developer Certificate of Origin
+
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
+
+### Community Guidelines
+
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.
+
+## See Also
+
+  - [Bake](https://github.com/ioquatix/bake) — Ruby task execution.
+  - [Utopia](https://github.com/socketry/utopia) — The original static component installer.

data/releases.md

@@ -0,0 +1,8 @@
+# Releases
+
+## v0.0.1
+
+### Added
+
+  - Add package-manager orchestration and static Node.js package materialization.
+  - Add deterministic manifests and import maps.