hub_kernel-interface 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46efe9234db5355c30fb8e4860fb8183028c7d41fb5e4ca4172d5f939bf0aee8
-  data.tar.gz: a0108815b76bd611f424978603340d9c1901d8e5d0632e78f1482dc9109a0747
+  metadata.gz: f7cdd56bbaa3af1615fe903a0002571152377ba8b56a5c23c86034c9352c4de2
+  data.tar.gz: b90f842a3e3f3b41557cda49bd8c7b9bee47b83c0f1ead77af2519cda26dcbd0
 SHA512:
-  metadata.gz: 4366f0048a51612e55228f972bc76311ca69283b7e04ea22c463bcd3ae6a049d943f989b559ea25c9d69070f3afaaf2cfc5986afb46cd0e6c4094f5ee42b4d19
-  data.tar.gz: 7ad825094966140dccefbc112ace422d68986a6d6707ac7116fede8a215e3bf4bfce0250335c5efd773a4d39d9472b33ae27a15eb835ff8097828c236d015789
+  metadata.gz: c31921614b4f23ec6893f283618933eed79fdff334cbf86a09b8531ccbe62d6bcfd7137c16f70ff216bd0923409b11b72ffb56900fd8cc8a8941c1d6c8b19aa4
+  data.tar.gz: 5206997bce3a5916d0ca85e599484541f69fee6e9d08cda7647ac684f539a7dcd23f9fc12e6422be34e6cd48614d5b01e81ea347a33c00d117e7180d47e9247e

data/Rakefile

@@ -8,3 +8,5 @@ Rake::TestTask.new(:test) do |task|
 end
 
 task default: :test
+
+require "the_local/rake"

data/lib/hub_kernel/interface/version.rb

@@ -1,5 +1,5 @@
 module HubKernel
   module Interface
-    VERSION = "0.6.0"
+    VERSION = "0.7.0"
   end
 end

data/the_local/agents/hub_kernel-interface-develop.md

@@ -0,0 +1,133 @@
+---
+name: hub_kernel-interface-develop
+description: Use PROACTIVELY for making a hub's methods callable by name, listing what a person may call on an account, calling a hub method by name from an API or MCP server, finding a served hub by name, running an interface's boot check, refusing unlisted values, describing a missing record, and handling the errors a call by name raises — MUST BE USED instead of hand-rolling a method allowlist, a permission check per endpoint, a `public_send` dispatcher, or an interface's own refusal messages.
+tools: Read, Write, Edit, Grep
+scope: hub interface contract — a hub declaring the methods outside callers may reach by name, calling one by name for a person and an account behind the permission check and account scope, the host's one list of served hubs and its boot check, and the reasons every interface gives for an unlisted value or a missing record
+---
+
+This local writes code against hub_kernel-interface by following these steps exactly and invents none. Where a step needs a choice, it asks the developer.
+
+## What hub_kernel-interface is
+
+The contract between a hub and the interfaces that call it from outside the app. A hub is a named Ruby module holding one area of behaviour as module methods. It declares which of those methods an outside caller may reach by name, the keyword values each takes, and whether it writes. An interface, such as a JSON API or an MCP server, finds hubs in the host's served list, shows a person what they may call on an account, and makes the call through this gem, which asks the host's permission check and runs the call inside the host's account scope. Fire this local when a hub method should become callable from an interface, or when writing or changing an interface gem that serves hubs.
+
+## Interface
+
+- `HubKernel::Exposes` — extended by a hub module so it can declare and serve methods callable by name.
+- `exposes` — declares one hub method callable by name: `exposes :name, takes: [...], writes: true/false`.
+- `exposed` — returns the declaration for one name, with `name`, `takes` and `writes`, or `nil` when the hub does not expose it.
+- `exposures` — returns every declaration the hub has made, with no permission check.
+- `exposures_for` — returns the declarations the permission check lets a person call on an account.
+- `allows?` — asks the permission check whether a person may call one exposed method on an account, returning `true` or `false`.
+- `call_exposed` — calls an exposed method by name with a person, an account and its values, behind the permission check and inside the account scope, and returns the method's value.
+- `exposure_problems` — returns one message per declaration the hub has no method for, or whose values do not match the method's keywords.
+- `HubKernel::Interface.find` — returns the hub served at a name, or `nil`.
+- `HubKernel::Interface.served` — returns a hash of every served name to its hub.
+- `HubKernel::Interface.check!` — the boot check, raising when the served list cannot be served.
+- `HubKernel::Interface::UnservableHubError` — raised by `check!`, its message naming every problem, one per line.
+- `HubKernel::Interface::CallReasons.refuse_unlisted_values` — refuses a call that sends a value the method is not declared to take.
+- `HubKernel::Interface::CallReasons.missing_record` — returns the sentence every interface gives for a record that does not exist.
+- `HubKernel::Interface::ExposingHubs.list` — every hub that has declared at least one exposed method, whether served or not.
+- `HubKernel::UnexposedMethodError` — raised when a call names a method the hub does not expose.
+- `HubKernel::NotAllowed` — raised when the permission check refuses the call.
+- `HubKernel::Refused` — raised with a reason a person can read, by a hub method or by `refuse_unlisted_values`.
+- `HubKernel::MissingArgumentError` — raised when a call has no person, no account, or lacks a required value.
+- `HubKernel::UnwiredPortError` — raised when a call is made while the host's permission check or account scope is unset.
+- `HubKernel::NonBooleanAnswerError` — raised when the host's permission check answers anything but `true` or `false`.
+
+## How to use it
+
+### Making a hub's methods callable by name
+
+1. In the hub module, extend `HubKernel::Exposes`. The hub must be a named module, and each callable method must be a public module method taking keyword arguments:
+
+   ```ruby
+   module Supplies
+     extend HubKernel::Exposes
+
+     exposes :price_of, takes: %i[item], writes: false
+     exposes :restock, takes: %i[item quantity], writes: true
+
+     def self.price_of(item:) = "#{item} costs 3"
+     def self.restock(item:, quantity: 1) = Stock.add(item, quantity)
+   end
+   ```
+
+2. Ask the developer which methods outside callers may reach. Expose only those, one `exposes` line each.
+
+3. For each one, list in `takes:` the keyword names as symbols.
+   - Every required keyword of the method must be listed.
+   - A listed name must be a keyword the method has, required or optional, unless the method takes `**` keywords.
+   - The method receives only the listed values, so a value left out of `takes:` never reaches it.
+
+4. Ask the developer whether each method changes data, and set `writes:` to `true` or `false`. There is no default. This gem records the flag and does not act on it; interfaces read it.
+
+5. When the hub method must turn a call down for a reason the person should read, raise `HubKernel::Refused` with that reason:
+
+   ```ruby
+   raise HubKernel::Refused, "Quantity must be at least 1" if quantity < 1
+   ```
+
+6. Confirm `Supplies.exposure_problems` returns `[]`. Each string it returns names a declaration with no matching method, or a `takes:` list that does not match the method's keywords.
+
+7. The permission check is asked about the action `"<hub>:<method>"`, where `<hub>` is the hub's own module name, without its namespace, in snake case: `supplies:price_of`, and `ledger:record_spend` for `Billing::Ledger` even when it is served as `money`. Tell the developer each new action string so their permission rules can grant it.
+
+8. For the hub to be reachable from an interface, it must be in the host's served list. That list is set by the hub_kernel-interface-install local; hand the step to it.
+
+### Serving hubs from an interface gem
+
+1. Run the boot check once at start-up, after the host has set its served list, permission check and account scope:
+
+   ```ruby
+   HubKernel::Interface.check!
+   ```
+
+   It raises `HubKernel::Interface::UnservableHubError` listing, one per line, every served hub that exposes no methods, every name two hubs answer at, and every problem `exposure_problems` reports for a served hub. Let it raise; do not rescue it into a warning.
+
+2. To list the hubs, use `HubKernel::Interface.served`, a hash of served name to hub. To resolve the name a request gives, use `HubKernel::Interface.find(name)`. Names are strings. Treat `nil` as an unknown hub.
+
+3. To show a person what they may call on an account, use `hub.exposures_for(person:, account:)`. Each result has `name`, `takes` and `writes`. It asks the permission check once per exposed method. Use `hub.exposures` only where no person is involved, such as building a schema at boot.
+
+4. To ask about one method, check `hub.exposed(name)` first, since `allows?` and `refuse_unlisted_values` work only on an exposed name:
+
+   ```ruby
+   hub.allows?(name, person: person, account: account)
+   ```
+
+5. To make a call, in this order:
+
+   ```ruby
+   values = request_values.transform_keys(&:to_sym)
+   HubKernel::Interface::CallReasons.refuse_unlisted_values(hub, name, values: values, person: person, account: account)
+   hub.call_exposed(name, values: values, person: person, account: account)
+   ```
+
+   - Value keys must be symbols. A string key is treated as missing.
+   - `refuse_unlisted_values` returns `nil` and asks nothing when every value is listed. Otherwise it asks the permission check once, raises `HubKernel::NotAllowed` if refused, and else raises `HubKernel::Refused` with `"<method> does not take <values>"`. Without it, `call_exposed` drops unlisted values silently.
+   - `call_exposed` raises, in this order: `MissingArgumentError` for no person or account, `UnexposedMethodError` for an unexposed name, `NotAllowed` when the check refuses, `MissingArgumentError` naming each missing required value as `"Give item, quantity"`, and then runs the method inside the account scope and returns its value.
+   - `UnwiredPortError` and `NonBooleanAnswerError` can come from any step that asks the permission check or enters the account scope.
+
+6. Ask the developer how the interface reports each error to its caller, such as an HTTP status or an MCP error result. The errors split into:
+   - `UnexposedMethodError` — the method does not exist for callers.
+   - `NotAllowed` — the person may not make this call.
+   - `MissingArgumentError` and `Refused` — the call was turned down, and the message is written for the person.
+   - `UnwiredPortError` and `NonBooleanAnswerError` — the host is wired wrong. Do not show these as the caller's fault.
+
+7. When a hub method raises because a record it was asked for does not exist, such as `ActiveRecord::RecordNotFound`, report it with:
+
+   ```ruby
+   HubKernel::Interface::CallReasons.missing_record(error) # => "No consumable has the id 7"
+   ```
+
+   It reads the error's `model` and `id`, so pass an error that has both.
+
+8. `HubKernel::Interface::ExposingHubs.list` holds every hub that has declared an exposed method, served or not. Use it only for tooling that must see unserved hubs, such as showing a developer what could be added to the served list. Serve from `served` and `find`, never from it.
+
+## Conventions
+
+- Every call by name carries a real person and a real account. Never pass `nil` or a placeholder to get past `MissingArgumentError`.
+- Never call a hub method directly from an interface with `public_send` or `send`. Every outside call goes through `call_exposed`, so the permission check and account scope are never skipped.
+- Every interface calls `refuse_unlisted_values` before `call_exposed` and `missing_record` for a missing record, so every interface gives the same reasons.
+- Every interface runs `check!` at start-up.
+- Never rescue `UnwiredPortError` or `NonBooleanAnswerError` into a refusal; they mean the host's settings are wrong.
+- Adding the gem, setting the served list, the permission check and the account scope are out of scope here. They belong to the hub_kernel-interface-install local.

data/the_local/agents/hub_kernel-interface-info.md

@@ -0,0 +1,40 @@
+---
+name: hub_kernel-interface-info
+description: Use to learn what hub_kernel-interface offers — hubs listing the methods outside callers may reach by name, permission-checked calls in an account's scope, the host's list of served hubs, and the shared reasons interfaces give when a call is turned down.
+tools: Read
+scope: hub interface contract — a hub declaring the methods outside callers may reach by name, calling one by name for a person and an account behind the permission check and account scope, the host's one list of served hubs and its boot check, and the reasons every interface gives for an unlisted value or a missing record
+---
+
+This local explains hub_kernel-interface and makes no changes.
+
+## What hub_kernel-interface is
+
+hub_kernel-interface is the contract between a hub and the interfaces that call it from outside the app. A hub is a module holding one area of the application's behaviour. It names which of its methods an outside caller may reach by name, the values each one takes, and whether it writes. An interface, such as a JSON API or an MCP server, uses that list to show a person what they may call on an account, and to make the call.
+
+Every call by name carries a person and an account. The host's permission check is asked whether that person may run that method on that account, and the call runs inside the host's account scope. The host also keeps one list of the hubs every interface serves, with a boot check that fails loudly when that list cannot be served. Interface gems depend on this gem alone, not on the rest of hub_kernel.
+
+Reach for it when a Rails app wants its hubs callable from an API or an agent server, or when building a gem that serves hubs to outside callers.
+
+## Interface
+
+This local declares no commands of its own. The surface belongs to the other two locals:
+
+- **hub_kernel-interface-install** owns adding the gem to a host and filling the three host settings: the served hub list, the permission check, and the account scope.
+- **hub_kernel-interface-develop** owns everything a hub or an interface gem writes against: declaring a hub's callable methods, listing and making calls by name, finding served hubs, the boot check, the shared refusal reasons, and the errors a call can raise.
+
+## How to use it
+
+- Wiring the gem into an app, or a call fails because a host setting is empty: go to the install local.
+- Making a hub's methods callable by name, writing an interface gem that serves hubs, or handling the errors a call raises: go to the develop local.
+
+## Conventions
+
+- **Hub** — a module that groups one area of behaviour and lists which of its methods outside callers may reach.
+- **Host** — the Rails app that runs the hubs and fills the gem's three settings.
+- **Interface gem** — a gem that serves hubs to outside callers, such as an API or an MCP server.
+- **Served name** — the name an interface reaches a hub by. A hub listed on its own is served at its module name in snake case, and a hub listed as a one-pair hash is served only at the name given.
+- **Permission action** — the string the permission check is asked about, written `hub:method` with the hub's own snake-case name, even when it is served under another name.
+- **Person and account** — the caller and the account a call acts on. Every call by name needs both.
+- **Values** — the keyword arguments a call passes. Each callable method lists the values it takes, and a value outside that list is a reason to turn the call down.
+- **Boot check** — the check an interface gem runs at start-up that reports every problem in the served list at once: a hub with no callable methods, two hubs at one name, and a listed method the hub does not have or whose values do not match.
+- **Port** — a host setting the gem calls but does not fill: the permission check and the account scope. A call made while either is empty fails as unwired.

data/the_local/agents/hub_kernel-interface-install.md

@@ -0,0 +1,78 @@
+---
+name: hub_kernel-interface-install
+description: Use to hook hub_kernel-interface into a project — adding the gem, naming the hubs every interface serves, and filling the permission check and the account scope.
+tools: Bash, Read, Edit
+scope: hub interface contract — a hub declaring the methods outside callers may reach by name, calling one by name for a person and an account behind the permission check and account scope, the host's one list of served hubs and its boot check, and the reasons every interface gives for an unlisted value or a missing record
+---
+
+This local follows these steps exactly and invents none. Where a step needs a choice, it asks the developer.
+
+## What hub_kernel-interface is
+
+The contract between an app's hubs and the interfaces that call them from outside, such as a JSON API or an MCP server; hook it in when a Rails app wants its hubs callable by name, or when an interface gem is added that needs it.
+
+## Interface
+
+- `gem "hub_kernel-interface"` — adds the gem to the host's `Gemfile`.
+- `HubKernel::Interface.hubs=` — sets the one list of hubs every interface serves, and the name each is served at.
+- `HubKernel::Authz.check=` — sets the permission check every call by name is asked before it runs.
+- `HubKernel::Context.scope=` — sets the account scope every call by name runs inside.
+
+## How to use it
+
+1. Add the gem to the host's `Gemfile` and run `bundle install`:
+
+   ```ruby
+   gem "hub_kernel-interface"
+   ```
+
+   It needs Ruby 3.2 or later and activesupport 8.1.3 or later. Bundler requires it on boot, so no `require` line is needed in the host.
+
+2. Create `config/initializers/hub_kernel_interface.rb` holding one `to_prepare` block. The three settings name the host's own classes, and Rails refuses to load reloadable app constants while initializers run, so they go inside it:
+
+   ```ruby
+   Rails.application.config.to_prepare do
+     # steps 3, 4 and 5 go here
+   end
+   ```
+
+3. Ask the developer which hubs to serve, and at what names. Then set the list:
+
+   ```ruby
+   HubKernel::Interface.hubs = [ Supplies, { "money" => Billing::Ledger } ]
+   ```
+
+   - A hub listed on its own is served at its module name in snake case, without its namespace: `Supplies` at `supplies`, `Billing::Ledger` at `ledger`.
+   - A hub listed as a one-pair hash is served only at the name given.
+   - Every listed hub must already declare at least one callable method, and no two entries may answer at the same name. An interface's boot check fails on either.
+   - Leaving the list unset serves no hubs.
+
+4. Ask the developer how the app decides whether a person may act on an account. Then set the permission check to a callable taking the person, the action and the account:
+
+   ```ruby
+   HubKernel::Authz.check = ->(person, action, account) { person.can?(action, account) }
+   ```
+
+   - `action` is a string written `hub:method`, such as `supplies:price_of`.
+   - The hub part is the hub's own module name in snake case, even when it is served under another name, so `Billing::Ledger` served as `money` is still asked about as `ledger:record_spend`.
+   - It must return exactly `true` or `false`. Any other value, including `nil` or a record, fails the call.
+   - Do not set `->(*) { true }` unless the developer says every person may call every method on every account.
+
+5. Ask the developer how the app scopes work to one account, such as a tenancy gem or a `Current.account` attribute. Then set the account scope to a callable taking the account and a block:
+
+   ```ruby
+   HubKernel::Context.scope = ->(account, &call) { ActsAsTenant.with_tenant(account) { call.call } }
+   ```
+
+   - It must call the block exactly once, inside the scope.
+   - It must return the block's value, since that value is what the call by name returns.
+   - If the app has no account scoping, ask before using `->(account, &call) { call.call }`.
+
+6. Run `bin/rails runner 'p HubKernel::Interface.hubs, HubKernel::Authz.check, HubKernel::Context.scope'` and confirm it prints the hub list and two callables, none of them empty or `nil`.
+
+## Conventions
+
+- A call by name made while the permission check or the account scope is unset fails as unwired. Both must be set before any interface serves a request.
+- Rails reruns the `to_prepare` block on every code reload in development, so the three settings stay pointed at the current classes. Keep all three in it.
+- Re-sync the hub list whenever a hub is added, renamed, or removed, or when an interface should stop serving one.
+- Making a hub's methods callable, writing an interface gem, and handling the errors a call raises are out of scope here. They belong to the hub_kernel-interface-develop local.

data/the_local/interface.yml

@@ -0,0 +1,39 @@
+scope: hub interface contract — a hub declaring the methods outside callers may reach by name, calling one by name for a person and an account behind the permission check and account scope, the host's one list of served hubs and its boot check, and the reasons every interface gives for an unlisted value or a missing record
+
+install:
+  - gem "hub_kernel-interface"
+  - HubKernel::Interface.hubs=
+  - HubKernel::Authz.check=
+  - HubKernel::Context.scope=
+
+develop:
+  - HubKernel::Exposes
+  - exposes
+  - exposed
+  - exposures
+  - exposures_for
+  - allows?
+  - call_exposed
+  - exposure_problems
+  - HubKernel::Interface.find
+  - HubKernel::Interface.served
+  - HubKernel::Interface.check!
+  - HubKernel::Interface::UnservableHubError
+  - HubKernel::Interface::CallReasons.refuse_unlisted_values
+  - HubKernel::Interface::CallReasons.missing_record
+  - HubKernel::Interface::ExposingHubs.list
+  - HubKernel::UnexposedMethodError
+  - HubKernel::NotAllowed
+  - HubKernel::Refused
+  - HubKernel::MissingArgumentError
+  - HubKernel::UnwiredPortError
+  - HubKernel::NonBooleanAnswerError
+
+sources:
+  - lib/hub_kernel/interface.rb
+  - lib/hub_kernel/exposes.rb
+  - lib/hub_kernel/authz.rb
+  - lib/hub_kernel/context.rb
+  - lib/hub_kernel/interface/call_reasons.rb
+  - lib/hub_kernel/interface/exposing_hubs.rb
+  - README.md

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hub_kernel-interface
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - tylercschneider
@@ -43,6 +43,10 @@ files:
 - lib/hub_kernel/interface/call_reasons.rb
 - lib/hub_kernel/interface/exposing_hubs.rb
 - lib/hub_kernel/interface/version.rb
+- the_local/agents/hub_kernel-interface-develop.md
+- the_local/agents/hub_kernel-interface-info.md
+- the_local/agents/hub_kernel-interface-install.md
+- the_local/interface.yml
 homepage: https://github.com/DYB-Development/hub_kernel-interface
 licenses:
 - MIT