enola-rb 0.0.0 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49c42cacd2a76196fffc485125ee37e75188acc4a402634a31b7f80d8e543af2
-  data.tar.gz: 1d316a926b68739e7e05ef369af0cbf729ae922335579b5a642d530c98f928b0
+  metadata.gz: 8187cf70720cf851a17def67c9ca82f66766dbf0437779037143298f7b219aec
+  data.tar.gz: da2463ad162461bfcf32015aa7074ef6e5c534e50c3533c995077c53fd1298ab
 SHA512:
-  metadata.gz: 34678e619b8f770de051b56d96730942cd61dc3b8b6bc2bcd2707c4f6b86ed2aa67a9e9760fe12bda6eba88720c52e50392945b2a14ac3200b21f5f055eb0a5b
-  data.tar.gz: 2726fa7f26271a06953f9097767582c864a3d25d2a3e5f55bac785e0139ee5c2fc9a10da897215a87bdee8aefea7a22f57ebe3c7e927d7d1b0801d04c96da387
+  metadata.gz: bd244d2988659a63032fca993b743a12897cc18eaf722e826c4f1f4e63620d60932f0ba481ff095260f0cd9f60bd669d5add4dd4c0b16d3b114fe58b5503456b
+  data.tar.gz: 3faf0965d57a14e8e853a444d9481fd90ae14732006ffc73eb0e2b1da9b14c4740f5af3728bceecb6ff08e370c3b9f335685004976737eacd609fb2c940397bc

data/CHANGELOG.md

@@ -0,0 +1,47 @@
+## munola 0.4.4.1 (2026-08-23)
+
+The wrapper over the munola channel, first release with an implementation.
+`munola init` writes the starter laws and upstream's bindings the way
+`enola:install` does, then the recipe catalogue from enola-guides, binds the
+recipes the tree shows a need for, fills the tenant foreign-key template
+from the schema, writes `mcp-arch.yaml` with Prism and Rubydex on and fetches
+the Rubydex library; `munola --version` names the munola version, its
+upstream base and the binary that answered; `MUNOLA_BINARY` names a binary
+to drive until the first munola release is cut. The channel's tag shape is
+`munola-v<version>` on the fork's releases.
+
+## enola 0.4.4 (2026-08-23)
+
+The wrapper, first release with an implementation: a pure-Ruby `enola`
+executable that drives upstream's v0.4.4. The binary is fetched on first use
+from the release for the running platform, verified against the sha256 the
+release publishes, and kept under `~/.cache/enola/upstream/0.4.4/`; a binary on
+PATH is used only when it answers the pinned version; offline with an empty
+cache is a refusal that names the cache and the release. Every argument and
+exit code is forwarded; `--verbose` adds one stderr line naming channel,
+version and where the binary came from; `enola --wrapper-probe` prints the
+channel, pin, found version and which surfaces the binary answers.
+
+Both providers by default: the gem vendors upstream's Prism provider script
+at the pinned version and depends on the `prism` gem; `enola init` writes
+`mcp-arch.yaml` with Prism (run by this Ruby) and Rubydex on, then runs the
+binary's `constraints init`; the Rubydex engine library is fetched once per
+binary version after the binary itself, a failure printed once as a named
+skip. `Enola::Config.write_default` and `Enola::Providers` are the seams the
+Rails layer and munola call.
+
+## enola-rb 0.4.4 (2026-08-23)
+
+The Rails layer, first release with an implementation. `rails generate
+enola:install` writes `enola/constraints/` from the enola-guides starter laws,
+binds the recipes the binary's own `constraints init` picks, writes the rest
+as commented bindings and ignores `.enola/`; the `enola:init`,
+`enola:snapshot` and `enola:check` rake tasks drive the binary the `enola` gem
+fetches. A surface the pinned binary lacks is refused by name with the remedy;
+an absent binary still leaves the laws written. Depends on `enola` at the same
+version and on `enola-guides`. The generator writes the provider config first,
+so a fresh app's graph carries Prism and Rubydex facts from its first snapshot.
+
+## munola 0.0.0
+
+Placeholder. `munola` is the same wrapper over another channel. Follows.

data/README.md

@@ -1,13 +1,103 @@
 # enola-rb
 
-Runs [enola](https://github.com/enola-labs/enola), the architecture-graph
-tool, from Ruby, with presets and defaults chosen for Rails stacks.
+Three pure-Ruby gems, one repository, for running
+[enola](https://github.com/enola-labs/enola), the architecture-graph tool,
+from Ruby. None of them carries a binary or compiles anything.
 
-Two channels, picked in your Gemfile. `enola-rb` on its own drives whichever
-enola binary is on your path. Adding the `munola` gem switches it to the build
-this project ships, which carries capabilities not yet in an upstream release.
+## `enola`
 
-Presets come from
-[enola-guides](https://github.com/misabegovic/enola-guides).
+The wrapper of the released enola. Its version is the upstream release it
+drives: `enola 0.4.4` runs enola-labs' v0.4.4.
 
-Placeholder release. No implementation yet.
+```ruby
+gem "enola"
+```
+
+```sh
+bundle exec enola --generate .
+bundle exec enola baseline pin .
+bundle exec enola check .
+```
+
+The first command that needs the binary downloads the release for your
+platform (linux, darwin, windows; amd64, arm64), verifies it against the
+sha256 file the same release publishes, and keeps it under
+`~/.cache/enola/upstream/0.4.4/` (`ENOLA_CACHE_DIR` moves the root). An
+`enola` already on your PATH is used only when it answers the pinned version;
+offline with an empty cache is a refusal that names the cache and the release
+rather than a fallback to whatever is installed. Nothing downloads at
+`bundle install`.
+
+Every argument and exit code is forwarded unchanged; the wrapper adds no flag
+of its own to enola's surface. `--verbose` on any command writes one line to
+stderr first, naming the channel, the version and where the binary came from.
+`enola --wrapper-probe` prints the channel, the pin, the version the binary
+answers and which surfaces it has (`constraints`, `providers`, `check`,
+`hook`), read by running them, never by comparing version strings.
+
+This gem is not an enola-labs release; it runs theirs.
+
+## `enola-rb`
+
+The Rails layer over `enola`. It depends on `enola` at the same version and on
+[enola-guides](https://github.com/misabegovic/enola-guides), and adds nothing
+to the binary's surface.
+
+```ruby
+gem "enola-rb"
+```
+
+```sh
+bin/rails generate enola:install
+bin/rake enola:snapshot
+bin/rake enola:check
+```
+
+The generator writes `enola/constraints/` from the guides' starter laws (four
+laws a Rails team keeps, each with its reason), asks the binary's own
+`constraints init` to bind the shipped recipes whose roles resolve in the app,
+writes every other shipped recipe as a commented binding to uncomment once the
+directories exist, and ignores `.enola/`. It reads what `init` wrote rather
+than its exit code, and when the binary cannot be fetched it still writes the
+laws and says so. `enola:snapshot` generates and pins the baseline;
+`enola:check` grades the working tree against it and fails on a new breach of
+a declared law. A surface the pinned binary lacks is refused by name with the
+remedy.
+
+## `munola`
+
+One person's taste on top of enola: the same wrapper over another channel,
+the builds cut from [a fork of enola](https://github.com/misabegovic/enola),
+versioned as the upstream they are built on plus a fourth segment
+(`0.4.4.1` drives a build on v0.4.4), each release naming what differs from
+that upstream. It is offered upstream where it fits and is not positioned
+against it. What it adds is the channel and the catalogue.
+
+```ruby
+gem "munola"
+```
+
+```sh
+bin/rails generate munola:install --tenant-column company_id
+bundle exec munola init .
+bundle exec munola --version
+```
+
+`munola init` does what `enola:install` does, then what only munola carries:
+it writes the recipe catalogue the `enola-guides` gem ships (Ember
+conventions, data ownership, API boundaries, background work, a tenant
+foreign key) into `enola/recipes/`, binds the recipes the tree justifies
+(`ember-cli-build.js`, a schema with `app/models`, `config/routes.rb` with
+`app/policies`, `app/tasks`, a column most tables share confirmed against
+`db/schema.rb`) and writes every other one as a commented binding; it fills
+the tenant template from the schema's own table names, never from an
+inflection table; it writes `mcp-arch.yaml` with both Ruby providers on by
+default, Prism through the script the `enola` gem carries and Rubydex built
+into the binary, and fetches the Rubydex library, a failed fetch reported as a
+named skip. It never asks a question. `munola --version` names the munola
+version, the upstream it is built on and which binary answered.
+
+The first munola release is what makes the channel real; until it is cut,
+`MUNOLA_BINARY=/path/to/enola` names the binary to drive, and every command
+says so. `munola` depends on `enola` and `enola-rb` at its upstream version
+and on `enola-guides` 0.3.1 or later.

data/lib/enola-rb.rb

@@ -1,5 +1,17 @@
 # frozen_string_literal: true
 
-module Enola
-  VERSION = "0.0.0"
+require "enola"
+require_relative "enola_rb/version"
+require_relative "enola_rb/guides"
+require_relative "enola_rb/surface"
+require_relative "enola_rb/installer"
+begin
+  require "rails"
+rescue LoadError
+  nil
+end
+require_relative "enola_rb/railtie" if defined?(Rails::Railtie)
+
+module EnolaRb
+  TASKS = File.expand_path("enola_rb/tasks.rake", __dir__)
 end

data/lib/enola_rb/guides.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module EnolaRb
+  # The enola-guides gem carries the starter laws; it is found at run time so a
+  # missing gem is a refusal naming the Gemfile line rather than a load error.
+  module Guides
+    BUILT_IN_RECIPES = %w[
+      rails-conventions rails-strict vanilla-rails layered ports-and-adapters
+      modular-monolith event-driven clean cqrs ruby-conventions
+    ].freeze
+
+    def self.root
+      ENV.fetch("ENOLA_GUIDES_DIR") { Gem::Specification.find_by_name("enola-guides").gem_dir }
+    rescue Gem::MissingSpecError
+      raise Enola::Unavailable, "the enola-guides gem is not installed; add `gem \"enola-guides\"` to the Gemfile, it carries the starter laws the generator writes"
+    end
+
+    def self.starter_laws
+      Dir.glob(File.join(root, "templates", "constraints-starter", "*.rb")).sort
+    end
+  end
+end

data/lib/enola_rb/installer.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require "yaml"
+
+module EnolaRb
+  class Installer
+    Report = Struct.new(:written, :bound, :unbound, :notes, keyword_init: true) do
+      def lines
+        out = written.map { |path| "wrote #{path}" }
+        out << "bound #{bound.join(', ')}" unless bound.empty?
+        out << "left commented, bind when the directories exist: #{unbound.join(', ')}" unless unbound.empty?
+        out + notes
+      end
+    end
+
+    def initialize(root, binary: nil, stderr: $stderr)
+      @root = File.expand_path(root)
+      @binary = binary
+      @stderr = stderr
+      @report = Report.new(written: [], bound: [], unbound: [], notes: [])
+    end
+
+    def install
+      raise Enola::Unavailable, "#{@root} holds no app/ directory; run this from the Rails root" unless File.directory?(File.join(@root, "app"))
+
+      write_config
+      copy_starter_laws
+      init_with_binary
+      comment_unbound
+      ignore_artifacts
+      @report
+    end
+
+    private
+
+    def write_config
+      written = Enola::Config.write_default(@root)
+      @report.written << relative(written) if written
+    end
+
+    def constraints_dir
+      File.join(@root, "enola", "constraints")
+    end
+
+    def bindings_path
+      File.join(constraints_dir, "recipes.yaml")
+    end
+
+    def copy_starter_laws
+      FileUtils.mkdir_p(constraints_dir)
+      Guides.starter_laws.each do |law|
+        target = File.join(constraints_dir, File.basename(law))
+        next if File.exist?(target)
+
+        FileUtils.cp(law, target)
+        @report.written << relative(target)
+      end
+    end
+
+    # The binary's own `constraints init` decides what binds; what it wrote is
+    # read rather than its exit code, because the release that shipped the
+    # surface exits through its unknown-command line after doing the work.
+    def init_with_binary
+      binary = @binary || Surface.require!(:constraints, binary: Enola.resolver.resolve.path)
+      out, status = Open3.capture2e(binary, "constraints", "init", @root)
+      note("constraints init: #{out.lines.last&.strip}") unless status.success? || File.exist?(bindings_path)
+    rescue Enola::Error => e
+      note("the enola binary is absent (#{e.message}); the laws are written, run `rake enola:init` once it can be fetched")
+    end
+
+    def bound
+      return [] unless File.exist?(bindings_path)
+
+      Array((YAML.safe_load(File.read(bindings_path)) || {})["use_recipe"]).map { |entry| entry["recipe"] }.compact
+    end
+
+    def comment_unbound
+      @report.bound = bound
+      @report.unbound = Guides::BUILT_IN_RECIPES - @report.bound
+      return if @report.unbound.empty?
+
+      existing = File.exist?(bindings_path) ? File.read(bindings_path) : "use_recipe: []\n"
+      return if existing.include?("# Shipped recipes not bound")
+
+      commented = @report.unbound.map { |name| "#  - recipe: #{name}\n#    as: #{name}\n#    mode: ratchet\n" }.join
+      File.write(bindings_path, "#{existing.chomp}\n\n# Shipped recipes not bound because their roles found no directory here.\n# Uncomment one once the directories exist, then run `enola constraints lint`.\n#{commented}")
+      @report.written << relative(bindings_path)
+    end
+
+    def ignore_artifacts
+      path = File.join(@root, ".gitignore")
+      existing = File.exist?(path) ? File.read(path) : ""
+      return if existing.lines.any? { |line| line.strip == ".enola/" }
+
+      File.write(path, "#{existing.chomp}\n.enola/\n".lstrip)
+      @report.written << ".gitignore"
+    end
+
+    def relative(path)
+      path.delete_prefix("#{@root}/")
+    end
+
+    def note(text)
+      @report.notes << text
+      @stderr.puts "enola: #{text}"
+    end
+  end
+end

data/lib/enola_rb/railtie.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module EnolaRb
+  class Railtie < Rails::Railtie
+    rake_tasks { load EnolaRb::TASKS }
+    generators { require_relative "../generators/enola/install/install_generator" }
+  end
+end

data/lib/enola_rb/surface.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module EnolaRb
+  module Surface
+    REMEDY = {
+      upstream: "upgrade the enola gem to a release that carries it, or switch the Gemfile to munola",
+      munola: "upgrade the munola gem"
+    }.freeze
+
+    def self.require!(name, binary:, channel: Enola.channel)
+      return binary if Enola::Probe.new(binary).capabilities.fetch(name.to_sym, false)
+
+      remedy = REMEDY.fetch(channel.name.to_sym, "upgrade the gem that pins this binary")
+      raise Enola::Unavailable, "the #{channel} binary at #{binary} has no `#{name}` surface; #{remedy}"
+    end
+  end
+end

data/lib/enola_rb/tasks.rake

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "enola-rb"
+
+namespace :enola do
+  root = -> { defined?(Rails) && Rails.respond_to?(:root) && Rails.root ? Rails.root.to_s : Dir.pwd }
+  run = lambda do |*args|
+    status = Enola::Runner.new.run(args)
+    abort("enola: exited #{status}") unless status.zero?
+  rescue Enola::Error => e
+    abort("enola: #{e.message}")
+  end
+
+  desc "Write enola/constraints/ from the guides' starter and bind the shipped recipes whose roles resolve"
+  task :init do
+    EnolaRb::Installer.new(root.call).install.lines.each { |line| puts line }
+  rescue Enola::Error => e
+    abort("enola: #{e.message}")
+  end
+
+  desc "Snapshot the application and pin the result as the baseline a change is graded against"
+  task :snapshot do
+    run.call("--generate", root.call)
+    run.call("baseline", "pin", root.call)
+  end
+
+  desc "Grade the working tree against the pinned baseline; fails on a new breach of a declared law"
+  task :check do
+    run.call("check", "--fail-on", "constraints", root.call)
+  end
+end

data/lib/enola_rb/version.rb

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

data/lib/generators/enola/install/install_generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "enola-rb"
+
+module Enola
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc "Writes enola/constraints/ from the guides' starter laws and binds the shipped recipes whose roles resolve"
+      def install
+        EnolaRb::Installer.new(destination_root).install.lines.each { |line| say line }
+      rescue Enola::Error => e
+        raise Thor::Error, "enola: #{e.message}"
+      end
+    end
+  end
+end

data/lib/generators/munola/install/install_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "munola"
+
+module Munola
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc "Writes enola/constraints/ and the munola recipe catalogue, binding what the tree shows a need for"
+      class_option :tenant_column, type: :string, default: nil, desc: "The column most tables carry; confirmed against db/schema.rb"
+
+      def install
+        Munola::Installer.new(destination_root, tenant_column: options[:tenant_column]).install.lines.each { |line| say line }
+      rescue Enola::Error => e
+        raise Thor::Error, "munola: #{e.message}"
+      end
+    end
+  end
+end

metadata

@@ -1,29 +1,67 @@
 --- !ruby/object:Gem::Specification
 name: enola-rb
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.4.4
 platform: ruby
 authors:
 - Muhamed Isabegovic
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-21 00:00:00.000000000 Z
-dependencies: []
+date: 2026-08-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: enola
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.4.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.4.4
+- !ruby/object:Gem::Dependency
+  name: enola-guides
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.1
 description: |
-  A Ruby wrapper around enola, the architecture-graph tool: presets, defaults
-  and a command surface aimed at Rails applications. Drives whichever enola
-  binary is on your path; add the munola gem to use the build this project
-  ships instead. Placeholder release; no implementation yet.
+  Adds the Rails layer to the enola gem: `rails generate enola:install` writes
+  enola/constraints/ from the enola-guides starter laws and binds the recipes
+  the released enola's own `constraints init` picks for the app, and the
+  enola:init, enola:snapshot and enola:check rake tasks drive the binary the
+  `enola` gem fetches and verifies. Pure Ruby; no binary, nothing compiled.
 email:
 - m.isabegovic@hotmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - lib/enola-rb.rb
+- lib/enola_rb/guides.rb
+- lib/enola_rb/installer.rb
+- lib/enola_rb/railtie.rb
+- lib/enola_rb/surface.rb
+- lib/enola_rb/tasks.rake
+- lib/enola_rb/version.rb
+- lib/generators/enola/install/install_generator.rb
+- lib/generators/munola/install/install_generator.rb
 homepage: https://github.com/misabegovic/enola-rb
 licenses:
 - Apache-2.0
@@ -48,5 +86,6 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Runs enola from Ruby, with defaults chosen for Rails stacks.
+summary: 'The Rails layer over the enola gem: rake tasks and a generator that writes
+  the guides'' starter laws.'
 test_files: []