hub_kernel 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 595e557959d0639e93e97244f510db28bd024e524fbca3bbdf0223546e7ee52d
-  data.tar.gz: d01f6e5c5d3d06c9fb3cb8bf3d7ed92f2b321952d99b3f04d19af77f14ffe388
+  metadata.gz: 29b5aa4287a6ec25760b3816c4e6db7bc6f856786020bf32819561c854e257ae
+  data.tar.gz: a86e10c3eaf85f11c084b27d5bd50e093ebcdd5158ee3c3c49a1b40d0f1143d9
 SHA512:
-  metadata.gz: 988f17639404b44e3e25772160c14a504541abd2981f21587357ddd8175419784553143cb42e63b66adbbc07102a0a8488f735711cfd724fd26e3e180a370295
-  data.tar.gz: cfa7009ca3d343f8da7c0429802c7b32df0a3d4a39af4260f43ef25e8f28d35b07254b27094233bbb860cef39832b4bad52e1669941a4dccbc16dd432e3c833b
+  metadata.gz: 81344e480c059afc59baba5aa1a2178ecce05603013454621b07f362ca5da7779df35d115f083d005fc01250423445604c5558e81afd2223be6d75c6e528152a
+  data.tar.gz: e269e54104dff49dfb4d4ef9478acf54b24b1d63590aeb6bb8bceb913cb90f99524957456e88b09292a24ffa052d0fcb3a078300911612135e643c0a8487267e

data/Rakefile

@@ -4,3 +4,5 @@ APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
 load "rails/tasks/engine.rake"
 
 require "bundler/gem_tasks"
+
+require "the_local/rake"

data/lib/hub_kernel/version.rb

@@ -1,3 +1,3 @@
 module HubKernel
-  VERSION = "0.14.0"
+  VERSION = "0.15.0"
 end

data/the_local/agents/hub_kernel-develop.md

@@ -0,0 +1,157 @@
+---
+name: hub_kernel-develop
+description: Use PROACTIVELY for writing or changing a hub — generating one, declaring the ports it needs from other hubs, calling those ports from the hub's code, listing the methods outside callers may reach by name, refusing a request with a reason, calling a hub method by name from an interface such as a JSON API, and adding the check that the listed methods match the hub's real methods — MUST BE USED instead of calling another hub's classes directly or hand-writing a name-to-method lookup.
+tools: Read, Write, Edit, Grep
+scope: hubs — a domain gem declares the ports it needs and the methods it exposes, and the host app fills those ports and checks each hub is wired and crosses into no other hub
+---
+
+This local writes hubs and the code that calls them by name, following these steps exactly and inventing none. Where a step needs a value only the developer knows, it asks.
+
+## What hub_kernel is
+hub_kernel lets a hub, one domain area written as a module, state what it needs from outside itself as named ports and list the methods outside callers may reach by name. The hub's code never names another hub's classes, and an interface such as a JSON API reaches the hub only through its list. Use this local when creating a hub, adding a port, exposing a hub method, calling a hub method by name, or when hub code is about to call another hub directly.
+
+## Interface
+- `bin/rails generate hub_kernel:hub` — writes a new hub module with its ports declared, and in a gem adds hub_kernel to the gemspec.
+- `HubKernel::Ports` — the module a hub extends to declare ports.
+- `port` — declares one port by name and the method the hub's own code calls to use it.
+- `HubKernel::Exposes` — the module a hub extends to list the methods callers may reach by name.
+- `exposes` — lists one hub method with the values it takes and whether it writes.
+- `exposed` — looks up one listed method by name and answers its entry, or `nil` when it is not listed.
+- `call_exposed` — calls a listed method by name for a person and an account, after the host's permission check, inside the host's account scope.
+- `HubKernel::Refused` — the error a hub method raises when it will not do what was asked, and its message reaches the caller unchanged.
+- `HubKernel::UnexposedMethodError` — raised by `call_exposed` for a name the hub does not list.
+- `HubKernel::MissingArgumentError` — raised by `call_exposed` for a call with no person, no account, or a value the method requires left out.
+- `HubKernel::NotAllowed` — raised by `call_exposed` when the host's permission check answers `false`, before the method runs.
+- `HubKernel::NonBooleanAnswerError` — raised by `call_exposed` when the host's permission check answers anything but `true` or `false`.
+- `HubKernel::Conformance::Exposed` — a test module that fails naming each listed method the hub has no method for, and each one listed with values it does not take.
+
+## How to use it
+
+### Start a hub
+1. Ask the developer for the hub's name and, for each thing it needs from another hub, a port name and the method name the hub's code will call. Do not invent ports.
+
+2. Run the generator from the root of the gem or app that will hold the hub, naming each port as `port:method`:
+
+   ```bash
+   bin/rails generate hub_kernel:hub Ledger entry_recorder:record_entry
+   ```
+
+   - In a Rails engine gem it writes the hub under the gem's namespace, such as `app/models/billing/ledger.rb` holding `module Billing::Ledger`, and adds hub_kernel to the gemspec. It writes no test, since the gem never fills its own ports.
+   - In an app it writes the hub under `app/models` and the hub's wiring test under `test/models`.
+
+   The generated hub:
+
+   ```ruby
+   module Billing::Ledger
+     extend HubKernel::Ports
+
+     port :entry_recorder, as: :record_entry
+   end
+   ```
+
+### Declare and use a port
+3. Add each new port to the hub with `port`, naming the port and the method the hub's code calls:
+
+   ```ruby
+   module Supplies
+     extend HubKernel::Ports
+
+     port :spend_recorder, as: :record_spend
+   end
+   ```
+
+   - `port` gives the hub a writer for the port, here `Supplies.spend_recorder=`, which the host app uses to fill it.
+   - Filling ports and checking they are filled is the install local's work, not this one's.
+
+4. In the hub's code, call the port through its method, passing whatever positional and keyword values the filler takes:
+
+   ```ruby
+   Supplies.record_spend(amount: 5)
+   ```
+
+   - It returns what the filler returns, and an error the filler raises reaches the caller unchanged.
+   - Calling a port the host left unfilled raises an error naming it, such as "Supplies' spend recorder is not wired".
+   - Never name another hub's classes in place of a port.
+
+### Expose methods
+5. Ask the developer which hub methods outside callers may reach by name, and for each, whether it writes. Do not decide either yourself.
+
+6. Write each exposed method as a module method on the hub that takes keyword arguments only, since a call by name passes values as keywords:
+
+   ```ruby
+   module Supplies
+     extend HubKernel::Exposes
+
+     exposes :record_purchase, takes: %i[supplier_id bought_on lines], writes: true
+
+     def self.record_purchase(supplier_id:, bought_on:, lines: [])
+       raise HubKernel::Refused, "That supplier is closed" if Supplier.find(supplier_id).closed?
+
+       # …
+     end
+   end
+   ```
+
+   - `takes:` lists every value the method requires, and may list optional ones, as symbols.
+   - A method that takes `**` values may be listed with any values, as long as each one it requires is listed.
+   - `writes:` is `true` or `false`, and both `takes:` and `writes:` must be given.
+   - A hub can extend both `HubKernel::Ports` and `HubKernel::Exposes`.
+
+7. When the method will not do what was asked, raise `HubKernel::Refused` with the reason a person should read. The reason reaches the caller unchanged.
+
+### Check the exposed list
+8. Add the exposed-list check to the tests of the gem or app that holds the hub, such as `test/models/supplies_exposed_test.rb`:
+
+   ```ruby
+   require "hub_kernel/conformance/exposed"
+
+   class SuppliesExposedTest < ActiveSupport::TestCase
+     include HubKernel::Conformance::Exposed
+
+     hub { Supplies }
+   end
+   ```
+
+   The `require` line is needed because the gem does not load the test modules on its own. This check needs no ports filled, so it runs in a domain gem's own suite.
+
+### Call a hub method by name
+9. In the interface that serves callers, such as a JSON API controller, look the method up with `exposed` and call it with `call_exposed`:
+
+   ```ruby
+   Supplies.exposed("record_purchase")         # => entry with .name, .takes, .writes
+   Supplies.exposed("delete_everything")       # => nil
+
+   Supplies.call_exposed("record_purchase",
+     values: { supplier_id: 4, bought_on: "2026-10-01", lines: [] },
+     person: current_person,
+     account: current_account)
+   ```
+
+   - The name may be a string or a symbol.
+   - `values:` is a hash with symbol keys, so symbolize request params before passing them, or every required value is reported missing.
+   - Only the values the method is listed with are passed on, and any others are dropped.
+   - `person:` and `account:` must both be given and not `nil`.
+   - The permission is asked for an action named after the hub, without its namespace, and the method, such as `"supplies:record_purchase"` or `"ledger:record_entry"`.
+   - It returns the result of the call made inside the host's account scope.
+
+10. A call by name fails in this order, and each failure stops the call:
+    1. `HubKernel::MissingArgumentError` when `person:` or `account:` is `nil`.
+    2. `HubKernel::UnexposedMethodError` when the hub does not list the name.
+    3. An error naming the host's permission check when the host has not set it.
+    4. `HubKernel::NonBooleanAnswerError` when the permission check answers anything but `true` or `false`.
+    5. `HubKernel::NotAllowed` when the permission check answers `false`.
+    6. `HubKernel::MissingArgumentError` naming each required value left out, such as "Give supplier_id".
+    7. An error naming the host's account scope when the host has not set it.
+    8. `HubKernel::Refused`, or any other error, raised by the hub method itself.
+
+11. Ask the developer how the interface answers each of those failures, such as which HTTP status each one returns. Do not pick the responses yourself. Show a `HubKernel::Refused` message to the caller as it is.
+
+12. Run the test suite and confirm the conventions below hold.
+
+## Conventions
+- A hub's code reaches another hub only through a port, never by naming its classes.
+- An outside caller reaches a hub only through `call_exposed`, never by sending a name to the hub with `public_send` or `send`.
+- Every exposed method is listed with `exposes`, and the exposed-list check passes.
+- When an exposed method gains, loses or renames a keyword, update its `takes:` in the same change.
+- When a hub gains a port, tell the developer every host app must fill it, since calling it unfilled raises an error and the host's start check fails.
+- Adding the gem to a host, filling ports, running the start check, setting the permission check and the account scope, and the host's hub and crossing checks belong to the install local and are out of scope here.

data/the_local/agents/hub_kernel-info.md

@@ -0,0 +1,43 @@
+---
+name: hub_kernel-info
+description: Use to learn what hub_kernel offers — hubs, the ports a hub declares, the methods it lets outside callers reach by name, and the checks that a host app has filled every hub and that no hub reaches into another.
+tools: Read
+scope: hubs — a domain gem declares the ports it needs and the methods it exposes, and the host app fills those ports and checks each hub is wired and crosses into no other hub
+---
+
+This local explains hub_kernel and the words it uses. It makes no changes and gives no steps.
+
+## What hub_kernel is
+
+hub_kernel splits a Rails app into hubs, where each hub is one area of the domain, such as supplies or finance, usually shipped in its own domain gem. A hub states what it needs from outside itself as named ports, and the host app decides what fills each one, so a hub never names another hub's code directly.
+
+A hub also lists the methods outside callers may reach by name, with the values each takes and whether it writes. An interface such as a JSON API calls through that list, and every call is checked against the host's permission rule and run inside the host's account scope. Reach for hub_kernel when an app has several domain areas that should talk to each other only through declared entry points, and you want the app to refuse to start, or the suite to fail, when that is not true.
+
+## Interface
+
+This local documents no commands. The surface belongs to the other two locals:
+
+- **hub_kernel-install** owns everything the host app does: adding the gem, filling each hub's ports, running the start check, setting the permission rule and the account scope, and adding the hub check and the crossing check to the host's tests.
+- **hub_kernel-develop** owns everything a hub's author does: generating a hub, declaring its ports, listing the methods callers may reach by name, refusing a request, and adding the check that the listed methods match the hub's real methods.
+
+## How to use it
+
+Decide which side you are on:
+
+- You are wiring hubs into an app, or the app will not start because something is not wired: use **hub_kernel-install**.
+- You are writing or changing a hub, inside a domain gem or the app: use **hub_kernel-develop**.
+
+## Conventions
+
+- **Hub** — one domain area, written as a module. In a domain gem it sits under the gem's namespace, such as Billing::Ledger.
+- **Ports** — what a hub needs from outside. Each has a name and the method the hub's own code calls, such as a spend recorder called as record_spend.
+- **Filling ports** — the host app sets each of a hub's ports to any callable, usually another hub's method, in its setup that runs again on every code reload. Ports are "wired" once they are filled.
+- **Start check** — the app refuses to start while any hub's ports are not wired, and names each one, such as "Supplies' spend recorder is not wired".
+- **Hub check** — a host test that fails naming each of a hub's ports left unfilled or filled with something that cannot be called. A domain gem never runs it, since the gem never fills its own ports.
+- **Call by name** — a caller reaches a hub method by its name as a string, with the values sent, the person, and the account. Unknown names, a missing person or account, and missing required values are refused.
+- **Action** — the name a permission is asked for, made of the hub and the method, such as supplies:record_purchase.
+- **Permission check** — one host-wide rule answering true or false for a person, an action, and an account. Any other answer is an error.
+- **Account scope** — one host-wide wrapper that runs each call by name inside the account it was made for.
+- **Refusing** — what a hub does when it will not do what was asked, and its reason reaches the caller unchanged.
+- **Crossing** — a file in one hub naming a class another hub owns. A constant inside that class counts.
+- **Crossing map** — the host's statement of which classes each hub owns, plus the classes shared by all, the host's own layer, each hub's interface module, and any namespace a hub owns whole. Only the host's layer may name a hub's interface module, and a view belongs to the hub that owns its controller.

data/the_local/agents/hub_kernel-install.md

@@ -0,0 +1,118 @@
+---
+name: hub_kernel-install
+description: Use to hook hub_kernel into a project — adding the gem, filling each hub's ports and running the start check, listing the loaded hubs, setting the permission check and the account scope, and adding the hub check and the crossing check to the host's tests.
+tools: Bash, Read, Edit
+scope: hubs — a domain gem declares the ports it needs and the methods it exposes, and the host app fills those ports and checks each hub is wired and crosses into no other hub
+---
+
+This local follows these steps exactly and invents none. Where a step needs a value only the developer knows, it asks.
+
+## What hub_kernel is
+hub_kernel lets a Rails host app fill the ports each hub declares, refuse to start while a port is unfilled, answer permission and account scope for calls made by name, and fail its suite when one hub's code names a class another hub owns. Hook it in when the app uses hubs, its own or ones shipped in domain gems.
+
+## Interface
+- `gem "hub_kernel"` — the Gemfile line that adds the gem to the host app.
+- `HubKernel::Hubs.check!` — raises `HubKernel::UnwiredPortError` naming every unfilled port of every loaded hub, one per line, such as "Supplies' spend recorder is not wired".
+- `HubKernel::Hubs.list` — the hubs that have loaded and declared at least one port.
+- `HubKernel::UnwiredPortError` — raised by the start check, by calling an unfilled port, and by a call by name while the permission check or the account scope is unset.
+- `HubKernel::Authz.check` — the host-wide permission rule, a callable taking a person, an action and an account and answering `true` or `false`.
+- `HubKernel::Context.scope` — the host-wide account scope, a callable taking an account and a block and running the block inside that account.
+- `HubKernel::Conformance::Hub` — a test module that fails naming each of one hub's ports left unfilled or filled with something that cannot be called.
+- `HubKernel::Crossings` — the crossing map: which classes each hub owns, the shared classes, the host's layer, each hub's interface module, and any namespace a hub owns whole.
+- `HubKernel::Conformance::Crossings` — a test module that reads the host's files against the crossing map and fails on each crossing, each unowned class, each class owned twice, and each mapped class that does not exist.
+
+## How to use it
+1. Add the gem to the host's `Gemfile`, then run `bundle install`:
+
+   ```ruby
+   gem "hub_kernel"
+   ```
+
+2. List the hubs the app uses and each port they declare. Ask the developer what fills each port, such as another hub's method. Do not pick a filler yourself.
+
+3. Fill every port and run the start check in a `to_prepare` block in an initializer, such as `config/initializers/hubs.rb`, so both run again after every code reload:
+
+   ```ruby
+   Rails.application.config.to_prepare do
+     Supplies.spend_recorder = Finance.method(:record_spend)
+     Billing::Ledger.entry_recorder = Finance.method(:record_entry)
+     HubKernel::Hubs.check!
+   end
+   ```
+
+   A port accepts any object that responds to `call`. The start check only sees hubs that have loaded, so name every hub in this block. Run `HubKernel::Hubs.list` in `bin/rails console` to see which hubs it saw.
+
+4. Ask the developer whether any interface, such as a JSON API, calls hub methods by name. If not, skip to step 6.
+
+5. Ask the developer for the app's permission rule and the account scope, since neither has a default. Set both once, in the same initializer:
+
+   ```ruby
+   HubKernel::Authz.check = ->(person, action, account) { Permissions.allow?(person, action, account) }
+   HubKernel::Context.scope = ->(account, &call) { Current.set(account: account, &call) }
+   ```
+
+   - The action is a string made of the hub and the method, such as `"supplies:record_purchase"`.
+   - The permission check must answer exactly `true` or `false`, and any other answer makes the call raise an error.
+   - The account scope must take the block and run it, or the hub method never runs.
+
+6. Add one hub check per hub to the host's tests, such as `test/hubs/supplies_hub_test.rb`:
+
+   ```ruby
+   require "hub_kernel/conformance/hub"
+
+   class SuppliesHubTest < ActiveSupport::TestCase
+     include HubKernel::Conformance::Hub
+
+     hub { Supplies }
+   end
+   ```
+
+   The `require` line is needed because the gem does not load the test modules on its own.
+
+7. Ask the developer for the crossing map, since only they know which hub owns which class:
+   - which classes each hub owns;
+   - which classes all hubs share, such as a base controller;
+   - which hub name stands for the host's own layer;
+   - each hub's interface module;
+   - any namespace a hub owns whole, such as a hub gem's `Billing`.
+
+   Also ask which files the check should read, and which to skip, such as the file that defines the interface modules.
+
+8. Add the crossing check to the host's tests, such as `test/hub_crossings_test.rb`:
+
+   ```ruby
+   require "hub_kernel/conformance/crossings"
+
+   class HubCrossingsTest < ActiveSupport::TestCase
+     include HubKernel::Conformance::Crossings
+
+     crossings files: "app/{models,controllers,jobs,views}/shop/**/*.{rb,erb}", except: [ "app/models/shop/hubs.rb" ] do
+       HubKernel::Crossings.new(
+         owners: { supplies: %w[Shop::Purchase Shop::PurchasesController], finance: %w[Shop::Expense], shop: %w[Shop::Home] },
+         shared: %w[Shop::BaseController],
+         host_layer: :shop,
+         interfaces: { supplies: "Shop::Hubs::Supplies", finance: "Shop::Hubs::Finance" },
+         namespaces: { billing: %w[Billing] }
+       )
+     end
+   end
+   ```
+
+   - `files:` is a glob read from `Rails.root`, and defaults to `"app/**/*.{rb,erb}"`.
+   - `root:` changes the folder the glob is read from.
+   - `except:` lists paths to skip, written relative to that folder.
+   - Hub names are symbols, and class names are strings.
+
+9. Run the app and the test suite, and confirm the checks below.
+
+## Conventions
+- After installing, `bin/rails runner 'HubKernel::Hubs.check!'` exits with no error, and every hub check and the crossing check pass.
+- The start check reports unfilled ports only, while the hub check also reports a port filled with something that cannot be called.
+- A domain gem never runs the hub check, since it never fills its own ports, so the hub check always lives in the host's tests.
+- A view belongs to the hub that owns its controller, then to the hub that owns the record its folder is named after, and otherwise to the host's layer.
+- A constant inside another hub's class counts as naming that class.
+- Only the host's layer may name a hub's interface module.
+- A class listed by name under `owners` belongs to that hub even inside another hub's namespace.
+- The crossing check fails with "The crossing check found no files to read" when its `files:` pattern matches nothing the map owns, so fix the pattern or the map rather than the test.
+- When a hub gains a port, fill it in the `to_prepare` block. When a class is added, renamed or removed, update the crossing map, since the check fails on a class no hub owns and on a mapped class that no longer exists.
+- Writing a hub, declaring its ports, and listing the methods it exposes are not part of installing and are out of scope here.

data/the_local/interface.yml

@@ -0,0 +1,42 @@
+scope: hubs — a domain gem declares the ports it needs and the methods it exposes, and the host app fills those ports and checks each hub is wired and crosses into no other hub
+
+install:
+  - gem "hub_kernel"
+  - HubKernel::Hubs.check!
+  - HubKernel::Hubs.list
+  - HubKernel::UnwiredPortError
+  - HubKernel::Authz.check
+  - HubKernel::Context.scope
+  - HubKernel::Conformance::Hub
+  - HubKernel::Crossings
+  - HubKernel::Conformance::Crossings
+
+develop:
+  - bin/rails generate hub_kernel:hub
+  - HubKernel::Ports
+  - port
+  - HubKernel::Exposes
+  - exposes
+  - exposed
+  - call_exposed
+  - HubKernel::Refused
+  - HubKernel::UnexposedMethodError
+  - HubKernel::MissingArgumentError
+  - HubKernel::NotAllowed
+  - HubKernel::NonBooleanAnswerError
+  - HubKernel::Conformance::Exposed
+
+sources:
+  - lib/hub_kernel.rb
+  - lib/hub_kernel/ports.rb
+  - lib/hub_kernel/hubs.rb
+  - lib/hub_kernel/exposes.rb
+  - lib/hub_kernel/action.rb
+  - lib/hub_kernel/authz.rb
+  - lib/hub_kernel/context.rb
+  - lib/hub_kernel/crossings.rb
+  - lib/hub_kernel/conformance/hub.rb
+  - lib/hub_kernel/conformance/exposed.rb
+  - lib/hub_kernel/conformance/crossings.rb
+  - lib/generators/hub_kernel/hub/hub_generator.rb
+  - README.md

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hub_kernel
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.0
 platform: ruby
 authors:
 - tylercschneider
@@ -55,6 +55,10 @@ files:
 - lib/hub_kernel/markup.rb
 - lib/hub_kernel/ports.rb
 - lib/hub_kernel/version.rb
+- the_local/agents/hub_kernel-develop.md
+- the_local/agents/hub_kernel-info.md
+- the_local/agents/hub_kernel-install.md
+- the_local/interface.yml
 homepage: https://github.com/tylercschneider/hub_kernel
 licenses:
 - MIT