bake-node 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: af22a090b1db8846c8025638f07a4bd25dfc4bfb375706b2036181d0213709ab
+  data.tar.gz: eee3a42a3cfef2b7e51b2dfccec24cfd3cc800ff13f1010bfa567d4e1e487a5d
+SHA512:
+  metadata.gz: a1f3644694f0ac6b95c13e2feef8a13209fff23b512ab7a1076488040d0c520fa60bccbc2d1b0719f296c0f0b9952fb1cc263a8abb5e9544b626a039ed856383
+  data.tar.gz: 65c40944f288ad631a07fb913c62dde3af4d1c10494641a1b9a42ab98ac9bb07a6adb691812c74089818de10c4b5e0247a98bb599df1481783be9703c77d06f6

data/bake/node/importmap.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+def initialize(context)
+	super
+	
+	require "bake/node/controller"
+end
+
+# Print the import map for the materialized static packages.
+# @parameter root [String] The directory containing package.json.
+# @parameter output [String | Nil] Override the configured output directory.
+def show(root: context.root, output: nil)
+	puts Bake::Node::Controller.new(root).import_map(output: output)
+end

data/bake/node/packages.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+def initialize(context)
+	super
+	
+	require "bake/node/controller"
+end
+
+# Materialize configured Node.js packages as static files.
+# @parameter root [String] The directory containing package.json.
+# @parameter output [String | Nil] Override the configured output directory.
+def static(root: context.root, output: nil)
+	Bake::Node::Controller.new(root).static(output: output)
+end
+
+# Check that the materialized static packages are current.
+# @parameter root [String] The directory containing package.json.
+# @parameter output [String | Nil] Override the configured output directory.
+def check(root: context.root, output: nil)
+	Bake::Node::Controller.new(root).check(output: output)
+end

data/bake/node.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+def initialize(context)
+	super
+	
+	require "bake/node/controller"
+end
+
+# Install packages using the configured package manager.
+# @parameter root [String] The directory containing package.json.
+# @parameter frozen [Boolean] Require the lock file to remain unchanged.
+def install(root: context.root, frozen: false)
+	Bake::Node::Controller.new(root).install(frozen: frozen)
+end
+
+# Run a package script using the configured package manager.
+# @parameter script [String] The package script to run.
+# @parameter root [String] The directory containing package.json.
+def test(script: "test", root: context.root)
+	Bake::Node::Controller.new(root).run(script)
+end

data/guides/getting-started/readme.md

@@ -0,0 +1,125 @@
+# Getting Started
+
+This guide explains how to use `bake-node` to install an external JavaScript dependency and expose it as static assets from a Ruby project.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add bake-node
+~~~
+
+Your project also needs Node.js and one supported package manager: npm, pnpm, Yarn or Bun. Bake Node delegates dependency resolution and script execution to that package manager.
+
+## Add a JavaScript Dependency
+
+Ruby applications commonly need browser libraries without needing a JavaScript bundler. Declare those libraries as regular production dependencies in `package.json`:
+
+~~~ json
+{
+  "private": true,
+  "packageManager": "pnpm@10",
+  "dependencies": {
+    "morphdom": "^2.7"
+  }
+}
+~~~
+
+Install the dependencies using the detected package manager:
+
+~~~ bash
+$ bundle exec bake node:install
+~~~
+
+The package manager remains responsible for its lock file and `node_modules`. Use immutable installation in CI:
+
+~~~ bash
+$ bundle exec bake node:install frozen=true
+~~~
+
+## Select Browser Files
+
+Packages often contain development sources, tests and metadata that should not be deployed. Add a `bake-node` section which selects the browser-facing files:
+
+~~~ json
+{
+  "private": true,
+  "packageManager": "pnpm@10",
+  "dependencies": {
+    "morphdom": "^2.7"
+  },
+  "bake-node": {
+    "packages": {
+      "morphdom": {
+        "include": ["morphdom-esm.js"],
+        "imports": {
+          "morphdom": "morphdom-esm.js"
+        }
+      }
+    }
+  }
+}
+~~~
+
+Direct production dependencies are selected by default. The package-specific object narrows the copied files and defines an import-map entry.
+
+## Generate Static Packages
+
+Materialize the configured packages:
+
+~~~ bash
+$ bundle exec bake node:packages:static
+~~~
+
+The default output is `public/_components`. Bake Node builds the complete output in a temporary directory and replaces the existing projection only after every package has been validated.
+
+Print the generated browser import map:
+
+~~~ bash
+$ bundle exec bake node:importmap:show
+~~~
+
+For the example above, the result includes:
+
+~~~ json
+{
+  "imports": {
+    "morphdom": "/_components/morphdom/morphdom-esm.js"
+  }
+}
+~~~
+
+Your application can embed this JSON in a `<script type="importmap">` element and serve `public/_components` with its other static assets.
+
+## Run JavaScript Tests
+
+Bake Node runs scripts from the root `package.json` without imposing a test framework:
+
+~~~ json
+{
+  "scripts": {
+    "test": "node --test"
+  }
+}
+~~~
+
+~~~ bash
+$ bundle exec bake node:test
+~~~
+
+Pass another script name when a project has multiple JavaScript test suites:
+
+~~~ bash
+$ bundle exec bake node:test script=test:browser
+~~~
+
+## Verify Generated Files
+
+Projects which commit or deploy the static projection can verify that it matches the current dependencies and configuration:
+
+~~~ bash
+$ bundle exec bake node:packages:check
+~~~
+
+See the [Static Packages](../static-packages/index) guide for detailed selection, manifest and import-map configuration. See [Internal Packages](../internal-packages/index) when JavaScript is developed alongside the Ruby code.

data/guides/internal-packages/readme.md

@@ -0,0 +1,110 @@
+# Internal Packages
+
+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.
+
+## Why Use Workspace Packages?
+
+Internal JavaScript often has its own module boundaries, tests and release concerns. Mixing it into the Ruby `lib/` hierarchy makes both languages harder to navigate, while placing authored code directly in `node_modules` makes it disposable.
+
+Bake Node recommends three distinct layers:
+
+~~~ text
+components/                 # Authored internal JavaScript packages.
+node_modules/               # Disposable package-manager projection.
+public/_components/         # Generated static deployment projection.
+package.json                # Workspace and Bake Node configuration.
+~~~
+
+`components/` describes the role of the code without requiring a second language-level hierarchy. A single directory can contain one or many packages.
+
+## Create an Internal Package
+
+Give each internal library its own `package.json` and tests:
+
+~~~ text
+components/
+  live/
+    package.json
+    Live.js
+    test/
+      Live.js
+~~~
+
+For example:
+
+~~~ json
+{
+  "name": "@example/live",
+  "private": true,
+  "type": "module",
+  "exports": "./Live.js",
+  "scripts": {
+    "test": "node --test"
+  }
+}
+~~~
+
+The directory name and package name do not need to match. Package identity comes from the internal `package.json`.
+
+## Add the Workspace
+
+Expose internal packages through the root workspace configuration:
+
+~~~ json
+{
+  "private": true,
+  "workspaces": ["components/*"],
+  "bake-node": {
+    "packages": {
+      "@example/live": {
+        "include": ["Live.js"],
+        "imports": {
+          "live": "Live.js"
+        }
+      }
+    }
+  }
+}
+~~~
+
+The package manager projects the workspace package into `node_modules/@example/live`, usually using a link. Bake Node resolves that link, ensures selected files remain inside the package, and copies the resulting files into `public/_components/@example/live`.
+
+The `components/` path is a convention rather than a requirement. Any workspace or local-package layout supported by the selected package manager can be used.
+
+## Test Internal Packages
+
+Each package can keep its own test command. Define a root script which invokes the workspace tests according to the selected package manager, then let Bake Node run that script:
+
+~~~ json
+{
+  "scripts": {
+    "test": "npm test --workspaces --if-present"
+  }
+}
+~~~
+
+~~~ bash
+$ bundle exec bake node:test
+~~~
+
+pnpm, Yarn and Bun have their own workspace script syntax. Bake Node deliberately does not abstract those differences; the root script remains the project's explicit test entry point.
+
+## Multiple Internal Libraries
+
+No additional multiplexing layer is needed. Add more package directories beneath `components/`, include them in the workspace pattern, and select the packages which should be deployed:
+
+~~~ text
+components/
+  editor/
+    package.json
+  live/
+    package.json
+  syntax/
+    package.json
+~~~
+
+Packages used only for development do not need to appear in `bake-node.packages`. Packages listed there can be deployed even when they are not direct root dependencies.
+
+## Avoid Authoring in `node_modules`
+
+`node_modules` is owned by the package manager and can be replaced by any installation command. Keep authored packages in `components/` and treat both `node_modules/` and `public/_components/` as projections which can be rebuilt from source and lock files.

data/guides/links.yaml

@@ -0,0 +1,6 @@
+getting-started:
+  order: 1
+internal-packages:
+  order: 2
+static-packages:
+  order: 3

data/guides/static-packages/readme.md

@@ -0,0 +1,134 @@
+# Static Packages
+
+This guide explains how to control which installed package files are deployed, generate browser import maps and verify the resulting static projection.
+
+## Package Selection
+
+All direct `dependencies` from the root `package.json` are selected by default. Use `bake-node.packages` to refine that selection:
+
+~~~ json
+{
+  "dependencies": {
+    "morphdom": "^2.7",
+    "server-only-package": "^1.0"
+  },
+  "bake-node": {
+    "packages": {
+      "morphdom": {
+        "include": ["morphdom-esm.js"]
+      },
+      "server-only-package": false,
+      "@example/internal": true
+    }
+  }
+}
+~~~
+
+Set a dependency to `false` to exclude it. Use `true` or an empty object to accept the default behavior. Additional workspace packages can be listed even when they are not direct dependencies.
+
+## Source Directories
+
+Many packages publish browser-ready files in `dist/`. Bake Node uses `dist` automatically when that directory exists and otherwise uses the package root.
+
+Override the source when a package has another layout:
+
+~~~ json
+{
+  "bake-node": {
+    "packages": {
+      "example": {
+        "source": "browser"
+      }
+    }
+  }
+}
+~~~
+
+Set `source` to `.` when the package root should be used even though a `dist/` directory exists.
+
+## Selecting a Subset of Files
+
+npm packages frequently contain far more than an application needs at runtime. `include` accepts package-source-relative glob patterns:
+
+~~~ json
+{
+  "bake-node": {
+    "packages": {
+      "mermaid": {
+        "source": "dist",
+        "include": [
+          "mermaid.esm.min.mjs",
+          "chunks/mermaid.esm.min/**/*.mjs"
+        ]
+      }
+    }
+  }
+}
+~~~
+
+When `include` is omitted, the complete source directory is copied except for nested `.git` and `node_modules` directories. Absolute paths and parent traversal are rejected, and symbolic links cannot escape the installed package.
+
+## Import Maps
+
+Map browser import specifiers to selected package files:
+
+~~~ json
+{
+  "bake-node": {
+    "base": "/_components/",
+    "packages": {
+      "mermaid": {
+        "source": "dist",
+        "include": ["mermaid.esm.min.mjs"],
+        "imports": {
+          "mermaid": "mermaid.esm.min.mjs"
+        }
+      }
+    }
+  }
+}
+~~~
+
+Relative import targets must refer to files included in the static projection. Absolute paths and URLs are preserved, which allows a project to combine local files and CDN imports explicitly. Duplicate specifiers are rejected.
+
+Generate and inspect the import map with:
+
+~~~ bash
+$ bundle exec bake node:packages:static
+$ bundle exec bake node:importmap:show
+~~~
+
+## Output and Manifest
+
+The default output directory and public URL prefix are configurable:
+
+~~~ json
+{
+  "bake-node": {
+    "output": "public/_components",
+    "base": "/_components/",
+    "packageRoot": "node_modules"
+  }
+}
+~~~
+
+Static installation writes `.bake-node.json` inside the output directory. The deterministic manifest records:
+
+- Package versions and selected source directories.
+- Every installed file and its SHA-256 digest.
+- Import-map entries.
+- A digest of the complete manifest.
+
+The manifest can be loaded once by an application or used as a cache key without repeatedly scanning the package tree.
+
+## Keeping Output Current
+
+The entire output tree is staged and swapped atomically. A missing file, invalid import, unsafe symbolic link or malformed package prevents replacement of the last working output.
+
+Use the check task in deployment or CI when generated files are expected to be current:
+
+~~~ bash
+$ bundle exec bake node:packages:check
+~~~
+
+The check rebuilds the desired manifest in a temporary directory and verifies both the manifest and current file contents.

data/lib/bake/node/configuration.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "json"
+require "pathname"
+
+require_relative "errors"
+require_relative "package"
+
+module Bake
+	module Node
+		# Loads and validates Bake Node settings from a project's `package.json` file.
+		class Configuration
+			DEFAULT_OUTPUT = "public/_components"
+			DEFAULT_BASE = "/_components/"
+			
+			# Load the configuration for a project.
+			# @parameter root [String | Pathname] The project directory containing `package.json`.
+			# @returns [Configuration] The validated project configuration.
+			# @raises [ConfigurationError] If `package.json` is missing, malformed or invalid.
+			def self.load(root)
+				root = Pathname.new(root).expand_path
+				package_path = root + "package.json"
+				
+				unless package_path.file?
+					raise ConfigurationError, "Could not find package.json in #{root}!"
+				end
+				
+				package_json = JSON.parse(package_path.read)
+				new(root, package_json)
+			rescue JSON::ParserError => error
+				raise ConfigurationError, "Could not parse #{package_path}: #{error.message}"
+			end
+			
+			# Initialize a configuration from parsed package metadata.
+			# @parameter root [String | Pathname] The project root directory.
+			# @parameter package_json [Hash] The parsed contents of `package.json`.
+			# @raises [ConfigurationError] If the configuration is invalid.
+			def initialize(root, package_json)
+				@root = Pathname.new(root).expand_path
+				@package_json = package_json
+				
+				unless @package_json.is_a?(Hash)
+					raise ConfigurationError, "package.json must contain an object!"
+				end
+				
+				configuration = @package_json.fetch("bake-node", {})
+				
+				unless configuration.is_a?(Hash)
+					raise ConfigurationError, "bake-node configuration must be an object!"
+				end
+				
+				@package_root = expand_within_root(configuration.fetch("packageRoot", "node_modules"), "packageRoot")
+				@output = configuration.fetch("output", DEFAULT_OUTPUT)
+				@base = configuration.fetch("base", DEFAULT_BASE)
+				@packages = load_packages(configuration["packages"])
+				
+				unless @base.is_a?(String) && @base.end_with?("/")
+					raise ConfigurationError, "bake-node base must be a string ending in '/'!"
+				end
+				
+				output_path
+			end
+			
+			# @attribute [Pathname] The expanded project root directory.
+			attr :root
+			
+			# @attribute [Hash] The parsed contents of `package.json`.
+			attr :package_json
+			
+			# @attribute [Pathname] The directory containing installed Node.js packages.
+			attr :package_root
+			
+			# @attribute [String] The public URL prefix for static packages.
+			attr :base
+			
+			# @attribute [Hash(String, Package)] The packages selected for static deployment.
+			attr :packages
+			
+			# Resolve the configured output directory.
+			# @parameter override [String | Nil] An optional project-relative output directory.
+			# @returns [Pathname] The expanded output directory.
+			# @raises [ConfigurationError] If the output directory escapes the project root.
+			def output_path(override = nil)
+				expand_within_root(override || @output, "output", allow_root: false)
+			end
+			
+			private
+			
+			def load_packages(overrides)
+				configured = {}
+				
+				dependencies = @package_json.fetch("dependencies", {})
+				unless dependencies.is_a?(Hash)
+					raise ConfigurationError, "package.json dependencies must be an object!"
+				end
+				
+				dependencies.each_key do |name|
+					configured[name] = {}
+				end
+				
+				case overrides
+				when nil
+					# All direct dependencies use their defaults.
+				when Array
+					configured = overrides.to_h{|name| [name, {}]}
+				when Hash
+					overrides.each do |name, options|
+						if options == false
+							configured.delete(name)
+						else
+							configured[name] = options == true ? {} : options
+						end
+					end
+				else
+					raise ConfigurationError, "bake-node packages must be an array or object!"
+				end
+				
+				configured.sort.to_h do |name, options|
+					[name, Package.new(name, options)]
+				end
+			end
+			
+			def expand_within_root(path, description, allow_root: true)
+				unless path.is_a?(String) && !path.empty?
+					raise ConfigurationError, "bake-node #{description} must be a non-empty string!"
+				end
+				
+				expanded = (@root + path).expand_path
+				prefix = @root.to_s + File::SEPARATOR
+				
+				unless expanded.to_s.start_with?(prefix) || (allow_root && expanded == @root)
+					raise ConfigurationError, "bake-node #{description} must remain within #{@root}!"
+				end
+				
+				expanded
+			end
+		end
+	end
+end

data/lib/bake/node/controller.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "json"
+
+require_relative "configuration"
+require_relative "manifest"
+require_relative "package_manager"
+require_relative "static"
+
+module Bake
+	module Node
+		# Coordinates package-manager commands and static package deployment for a project.
+		class Controller
+			# Initialize a controller for a project.
+			# @parameter root [String | Pathname] The project directory containing `package.json`.
+			# @raises [ConfigurationError] If the project configuration is invalid.
+			def initialize(root)
+				@configuration = Configuration.load(root)
+			end
+			
+			# @attribute [Configuration] The validated project configuration.
+			attr :configuration
+			
+			# Install Node.js packages using the detected package manager.
+			# @parameter frozen [Boolean] Whether the lock file must remain unchanged.
+			# @raises [Error] If the package-manager command fails.
+			def install(frozen: false)
+				package_manager.install(frozen: frozen)
+			end
+			
+			# Run a script from the root `package.json` file.
+			# @parameter script [String] The script name to run.
+			# @raises [Error] If the package-manager command fails.
+			def run(script)
+				package_manager.run(script)
+			end
+			
+			# Materialize the configured packages as static files.
+			# @parameter output [String | Nil] An optional project-relative output directory.
+			# @returns [Manifest] The generated static package manifest.
+			def static(output: nil)
+				Static.new(@configuration, output: output).update
+			end
+			
+			# Verify that the static package projection is current.
+			# @parameter output [String | Nil] An optional project-relative output directory.
+			# @returns [Boolean] `true` when the static package projection is current.
+			# @raises [CheckError] If the static package projection is missing or out of date.
+			def check(output: nil)
+				Static.new(@configuration, output: output).check!
+			end
+			
+			# Generate an import map from the static package manifest.
+			# @parameter output [String | Nil] An optional project-relative output directory.
+			# @returns [String] The formatted import map JSON.
+			# @raises [CheckError] If the static package manifest is missing or invalid.
+			def import_map(output: nil)
+				root = @configuration.output_path(output)
+				JSON.pretty_generate(Manifest.load(root).import_map)
+			end
+			
+			private
+			
+			def package_manager
+				@package_manager ||= PackageManager.detect(@configuration)
+			end
+		end
+	end
+end

data/lib/bake/node/errors.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Bake
+	module Node
+		# The base class for Bake Node failures.
+		class Error < StandardError
+		end
+		
+		# Raised when project or package configuration is invalid.
+		class ConfigurationError < Error
+		end
+		
+		# Raised when an installed package cannot be materialized safely.
+		class PackageError < Error
+		end
+		
+		# Raised when generated static packages are missing or out of date.
+		class CheckError < Error
+		end
+	end
+end