terret-fortune 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bad4f22d3f92f0e9454dec8d24aec32d3c9879f88bbc22359f5fa8ae73ccd02c
+  data.tar.gz: a2987aeffe819aab4fb6fae17e4bcb03b091c5e00c457124629975a5aac524fb
+SHA512:
+  metadata.gz: 589284cdbcd52f2904a10901f1a563b9766a36eff877a912935b12add8fc6ae4c4790409f161d40abab6f546d72865ddbe59e2afd19923e53b89bb1e91f3a365
+  data.tar.gz: ccf7610b1258fa44b30e4ce5fbbd8b74599b14c0db9d1ad31328fc38b766ac554829485ebebc8df55121548d7e65fffe8f6ec8defafe8b7bbb0632d3e9f30811

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Obie Fernandez
+
+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,139 @@
+# terret-fortune
+
+A worked example of the [Terret](https://terret.org) extension story: a
+third-party gem that ships **one tool** and joins an agent's boot by shipping
+normally. Install it, name it in a profile, permit the tool, and a Terret agent
+can call `fortune` — one short, pithy line from a vendored list.
+
+This gem is the running example of Terret's `docs/cookbook/adding-a-tool.md` and
+`docs/cookbook/adding-a-bundle.md`, kept in lockstep with those pages: what they
+describe generically, this repository is concretely.
+
+## What it is
+
+`fortune` is the smallest honest tool there is: a pure read with no side
+effect. Its metadata says so — `mutating: false`, `approval: :never`,
+`concurrency: :parallel` — and those three fields are what the loop's tool
+barrier and the approvals gate act on, so they are the truth about what calling
+it does, not a convenience.
+
+```
+terret-fortune/
+├── terret-fortune.gemspec      # declares the gem a bundle (metadata["terret"])
+├── config/
+│   └── bundle.yml              # one row mounting Terret::Fortune::Tool
+├── lib/
+│   └── terret/
+│       ├── fortune.rb          # entry: requires terret-core, then the service
+│       └── fortune/
+│           ├── tool.rb         # the Hames service that registers `fortune`
+│           └── fortunes.txt    # the vendored list
+└── test/
+    └── fortune_test.rb         # boots the service, drives the real tool pipeline
+```
+
+## The extension story, end to end
+
+### 1. Write the tool
+
+A tool provider is an ordinary Hames service: it `inject`s `ctx[:tools]` and
+registers a `Definition` in `start`. `lib/terret/fortune/tool.rb` is the whole
+of it — the same shape `gems/terret-tools-std` uses for the standard roster.
+
+### 2. Declare the gem a bundle
+
+One line of gemspec metadata makes the gem discoverable. The value is the
+**string** path to the bundle file — RubyGems validates every metadata value as
+a String, so a nested hash does not build at all:
+
+```ruby
+# terret-fortune.gemspec
+s.metadata = { "terret" => "config/bundle.yml" }
+s.add_dependency "terret-core", "~> 0.1"   # the code the row mounts
+```
+
+The bundle file is an ordered list of rows plus the requires its constants
+need:
+
+```yaml
+# config/bundle.yml
+name: terret-fortune
+requires:
+  - terret/fortune
+rows:
+  - id: fortune
+    plugin: Terret::Fortune::Tool
+```
+
+### 3. Install it
+
+```bash
+gem install terret-fortune
+# or, in a Gemfile:
+#   gem "terret-fortune"
+```
+
+`gem install` is the whole registration mechanism. Terret's discovery walks
+every gemspec it can see, reads the `terret` metadata key, and parses the file
+it points at — so a third-party gem becomes discoverable by shipping normally.
+Nothing to register, no directory to drop a file into.
+
+### 4. Stack it in a profile
+
+A profile names bundles by gem name, in stack order, `terret` (terret-base)
+always layer one:
+
+```yaml
+# ~/.terret/profiles/headless/profile.yml
+bundles:
+  - terret          # terret-base, always first
+  - terret-fortune  # this gem
+```
+
+### 5. Permit the tool
+
+This is the step people forget: **mounting the tool does not make it
+callable.** Terret's allow list is deny-by-default, and the base floor names
+exactly the standard roster and nothing else. `fortune` is denied until a
+profile permits it — and because a patch replaces a row's config **wholesale**,
+you restate the whole list, not just the new name:
+
+```yaml
+# ~/.terret/profiles/headless/patch.yml
+rows:
+  - id: allow_list
+    config:
+      patterns:
+        - Read
+        - Write
+        - Edit
+        - Glob
+        - Grep
+        - Bash
+        - fortune          # the new tool, now permitted
+        # ... restate the rest of the roster you still want
+```
+
+### 6. Boot
+
+```ruby
+ctx = Terret.boot(profile: "headless")
+```
+
+That resolves the layers, discovers `terret-fortune`, requires its code, mounts
+its row, and registers the tool. From here the agent can call `fortune`.
+
+## Running the tests
+
+```bash
+# Against a published terret-core:
+bundle install
+bundle exec rake test
+
+# Against a local Terret monorepo checkout (no publish needed):
+TERRET_CHECKOUT=/path/to/terret bundle exec rake test
+```
+
+## License
+
+MIT. See `LICENSE`.

data/config/bundle.yml

@@ -0,0 +1,14 @@
+# terret-fortune -- a one-row bundle so a profile can stack this gem by name.
+#
+# A bundle ships rows; the code the row names comes from the gem this bundle
+# depends on (terret-core, in terret-fortune.gemspec) plus this gem's own lib.
+# `requires:` is the working half of "make the code available": a load path is
+# not a require, so boot loads this file before the row's constant resolves.
+name: terret-fortune
+
+requires:
+  - terret/fortune
+
+rows:
+  - id: fortune
+    plugin: Terret::Fortune::Tool

data/lib/terret/fortune/fortunes.txt

@@ -0,0 +1,10 @@
+Fortune favors the prepared mind.
+A ship in harbor is safe, but that is not what ships are for.
+The best way out is always through.
+Small deeds done are better than great deeds planned.
+What is not started today is never finished tomorrow.
+Simplicity is the ultimate sophistication.
+Well begun is half done.
+Make it work, make it right, make it fast.
+The obstacle is the way.
+Slow is smooth, and smooth is fast.

data/lib/terret/fortune/tool.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Terret
+  module Fortune
+    # Registers the `fortune` tool: one random line from a vendored list.
+    # An ordinary tool provider -- a Hames service that injects ctx[:tools]
+    # and registers a Definition in `start`, the shape gems/terret-tools-std
+    # uses for the whole standard roster.
+    class Tool < Hames::Service
+      service_key :fortune
+      inject :tools
+      config_schema path: { type: String,
+                            doc: "path to a newline-delimited fortune file; " \
+                                 "defaults to the vendored list" }
+
+      DEFAULT_FILE = File.expand_path("fortunes.txt", __dir__)
+
+      DESCRIPTION = "Return a single fortune: one short, pithy line chosen at random."
+
+      def start(ctx)
+        @ctx = ctx
+        @fortunes = load_fortunes(config[:path] || DEFAULT_FILE)
+        register_fortune
+      end
+
+      # The list is read once at mount. A swapped `path:` needs a remount to
+      # apply, and saying so beats letting the base class warn that a service
+      # it thinks is stateful needs one (docs/hames-primer.md §5).
+      def reconfigure(config)
+        @fortunes = load_fortunes(config[:path] || DEFAULT_FILE)
+      end
+
+      private
+
+      def register_fortune
+        # `ctx:` is passed explicitly, exactly as the std roster does it. The
+        # registry defaults it to the context the service was started in; a
+        # provider mounted into a forked agent scope wants the registration
+        # owned by that fork, so disposing the agent reaps the tool rather
+        # than leaving it live on the root (gems/terret-core tools.rb).
+        @ctx[:tools].register(name: "fortune", description: DESCRIPTION, params: {},
+                              mutating: false, approval: :never, concurrency: :parallel,
+                              ctx: @ctx) do
+          @fortunes.sample
+        end
+      end
+
+      def load_fortunes(path)
+        lines = File.readlines(path, chomp: true).map(&:strip).reject(&:empty?)
+        # A tool that would return nil on every call is a bug worth failing
+        # at mount, not one call at a time.
+        raise "no fortunes in #{path}" if lines.empty?
+
+        lines
+      end
+    end
+  end
+end

data/lib/terret/fortune.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+begin
+  require "terret"
+rescue LoadError
+  require_relative "../../../terret-core/lib/terret" # monorepo path source
+end
+
+require_relative "fortune/tool"

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: terret-fortune
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Obie Fernandez
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: terret-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+description: 'A worked example of the Terret extension story: a third-party gem that
+  ships one tool (`fortune`, one line from a vendored list) and declares itself a
+  bundle in a line of gemspec metadata, so a profile can stack it by name. Stdlib-only
+  beyond terret-core. The running example of docs/cookbook/adding-a-tool.md, kept
+  in lockstep with that page.'
+email:
+- obiefernandez@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- config/bundle.yml
+- lib/terret/fortune.rb
+- lib/terret/fortune/fortunes.txt
+- lib/terret/fortune/tool.rb
+homepage: https://terret.org
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://terret.org
+  source_code_uri: https://github.com/terret-org/terret-fortune
+  bug_tracker_uri: https://github.com/terret-org/terret-fortune/issues
+  rubygems_mfa_required: 'true'
+  terret: config/bundle.yml
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: A fortune tool for Terret
+test_files: []