samagotchi 0.157.0 → 0.158.0

data/lib/samagotchi/testing/bundle.rb

@@ -25,7 +25,7 @@ require_relative "recording_api"
 
 module Samagotchi
   module Testing
-    # A hook (a plugin's chi.on block or a hook file) raised while the kit
+    # A hook (a plugin's chi.on block) raised while the kit
     # fired it: chi would log it and go on, a test fails with it.
     class HookFailed < StandardError
       # @return [Hooks::Failure]
@@ -53,8 +53,7 @@ module Samagotchi
 
     # One bundle loaded for a test through chi's own seams: its plugin
     # through Plugin::Loader.register_file (Plugin::Api, a real
-    # Plugin::Context) and its hook files through
-    # Hooks::BundleLoader.load_hook_file, into real registries (commands
+    # Plugin::Context), into real registries (commands
     # and tools with chi's built-ins in them, so a name clash fails as in
     # chi). Only the edges are recorded: the Host and hook Runtime
     # (Recorder), ctx.sessions (Testing::Sessions), chi.init tasks and
@@ -130,8 +129,6 @@ module Samagotchi
       # @return [Module, nil] the module the plugin was evaluated in
       #   (bundle.namespace::ThinkingWatch)
       attr_reader :namespace
-      # @return [Module] the module the hook files were evaluated in
-      attr_reader :hooks_namespace
       # @return [Array<Init>]
       attr_reader :inits
       # @return [Array<StagedTools>]
@@ -152,6 +149,9 @@ module Samagotchi
         @session_moves = 1
         own = session_settings.nil? || session_settings.empty? ? {} : { setup: setup_with(session_settings, host[:setup]) }
         @own_sandbox = sandbox.nil? && Sandbox.current.nil?
+        # With no active sandbox, this one saves ENV at construction and
+        # restores that copy at shutdown; don't lazily build it inside a block
+        # that sets ENV for one example (your own helper, or ClimateControl).
         @sandbox = sandbox || Sandbox.current || Sandbox.enter
         build(host, own)
       rescue Exception # rubocop:disable Lint/RescueException -- leave the sandbox it entered, whatever failed
@@ -184,13 +184,6 @@ module Samagotchi
             @plugin = built
           end
         end
-        @hooks_namespace = Module.new
-        @manifest.hooks.each do |basename, hook|
-          next if hook.events.empty?
-
-          Hooks::BundleLoader.load_hook_file(@name, basename, File.join(@dir, "hooks", basename), hook, hooks,
-                                             settings: @settings, namespace: @hooks_namespace)
-        end
         self
       rescue Exception # rubocop:disable Lint/RescueException -- leave the sandbox it entered, whatever failed
         shutdown

data/lib/samagotchi/testing/install.rb

@@ -15,7 +15,7 @@ module Samagotchi
     # A bundle as chi installs and loads it, unlike Bundle (its source as it
     # is): MemoryBundle::Installer copies it into the sandbox's state (sha256
     # and requires_chi checked), then chi's own loaders load what is
-    # installed (ExtensionLoad: the bundle hooks, then the plugins). What
+    # installed (ExtensionLoad: config hooks, then the plugins). What
     # failed names the bundle's source files, not the installed copies.
     #
     #   result = Samagotchi::Testing::Install.run("path/to/bundle", settings: { "every" => 3 })
@@ -23,8 +23,8 @@ module Samagotchi
     module Install
       # warnings: the Installer's; plugin_failures / hook_failures:
       # [Guardrails::LoadFailures::Failure] of this bundle, each location
-      # in the source dir (hook_failures: the guardrails', a required
-      # plugin's among them); registered: what it registered (#registered).
+      # in the source dir (hook_failures: the guardrails': a required
+      # plugin's load failure, a config hook's); registered: what it registered (#registered).
       Result = Data.define(:name, :warnings, :plugin_failures, :hook_failures, :registered) do
         def failures = plugin_failures + hook_failures
       end
@@ -35,7 +35,7 @@ module Samagotchi
       Registered = Data.define(:commands, :tools, :hooks, :inits, :toolkits, :tool_sources, :peer_sources, :prompt_sections)
       # A command: its mid_turn policy and its selection-bar labels (chi.annotation).
       Command = Data.define(:name, :mid_turn, :labels)
-      # A hook on an event: the bundle, the hook (its file, or the plugin's) and its priority.
+      # A hook on an event: the bundle, the hook (the plugin's label) and its priority.
       Hook = Data.define(:bundle, :hook, :priority)
 
       module_function
@@ -119,7 +119,7 @@ module Samagotchi
       # installed copy to the source dir.
       def own(failures, name, installed, dir)
         failures.list.select { |f| f.what.end_with?("(bundle #{name})") }.map do |failure|
-          # The plugin is installed into plugin/, the hooks into hooks/.
+          # The plugin is installed into plugin/.
           location = failure.location&.sub(%r{\A#{Regexp.escape(installed)}/(?:plugin/)?}, "#{dir}/")
           failure.dup.tap { |copy| copy.location = location }
         end

data/lib/samagotchi/testing/recorder.rb

@@ -9,7 +9,7 @@ require_relative "judgments"
 module Samagotchi
   module Testing
     # A line to the user (ctx.notify, event[:notify]); +hook+ is the
-    # plugin's or hook file's label ("plugin.rb (bundle x)").
+    # plugin's label ("plugin.rb (bundle x)").
     Notice = Data.define(:text, :level, :hook, :fallback_for)
     # Text put into the running turn (ctx.steer, event[:steer]).
     Steer = Data.define(:text, :hook)

data/lib/samagotchi/testing.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # The bundle test kit (docs/plugins.md, "Testing a bundle"): load a bundle's
-# plugin and hook files through chi's own loaders, registries, Context and
+# plugin through chi's own loaders, registries, Context and
 # guardrail Gate, with only the edges recorded (the session's Host, the hook
 # runtime, ctx.sessions, init tasks), in a sandboxed environment.
 #

data/lib/samagotchi/tool_declarations.rb

@@ -375,7 +375,7 @@ module Samagotchi
             },
             cwd: {
               type: "string",
-              description: "The new child's working folder: a worktree or subfolder of this session's repository (create a worktree with execute `git worktree add ../<repo>-<name> -b <branch>` first). Default: this session's folder"
+              description: "The new child's working folder: a worktree or subfolder of this session's project (a repository, or a `chi project init` folder; create a worktree with execute `git worktree add ../<repo>-<name> -b <branch>` first). Default: this session's folder"
             },
             toolkit: {
               type: "string",

data/lib/samagotchi/toolkit_binding.rb

@@ -139,10 +139,7 @@ module Samagotchi
 
       toolkit = Toolkit.new(name: name)
       if session.toolkit == toolkit
-        if session.toolkit_origin != "chosen"
-          session.toolkit_origin = "chosen"
-          session.save(state_dir: @state_dir.call)
-        end
+        session.save(state_dir: @state_dir.call) if session.choose_toolkit_origin!
         return true
       end
 

data/lib/samagotchi/toolkit_command.rb

@@ -47,10 +47,7 @@ module Samagotchi
       # Nothing the prompt carries changes (full +delegate on full): only
       # the origin is saved, so a no-op choice still counts as user-selected.
       if after.prompt_key == before.prompt_key
-        if session.toolkit_origin != "chosen"
-          session.toolkit_origin = "chosen"
-          @save.call(session)
-        end
+        @save.call(session) if session.choose_toolkit_origin!
         return [listing(before) + "\n(no change to what the next turn declares)", false, nil]
       end
 

data/lib/samagotchi/tools/delegate.rb

@@ -281,9 +281,10 @@ module Samagotchi
       private_class_method :unknown_toolkit
 
       # The new child's folder: the parent's, or +cwd+ (relative to the
-      # parent's) when it is a folder of the parent's repository, in any of
-      # its worktrees (one project_root, from the common git dir). Outside
-      # git only a subfolder of the parent's folder. Nothing is created
+      # parent's) when it is a folder of the parent's project: in any of its
+      # repository's worktrees (one project_root, from the common git dir), or
+      # in its marked folder. Outside both only a subfolder of the parent's
+      # folder. Nothing is created
       # here: the model makes a worktree with execute, where guardrails see it.
       # @return [String] an absolute folder, or an Error: line
       def self.child_cwd(cwd, parent)
@@ -294,8 +295,8 @@ module Samagotchi
         return "Error: cwd #{folder} is not a folder (create the worktree first)" unless File.directory?(folder)
 
         folder = File.realpath(folder)
-        unless same_repository?(folder, base)
-          return "Error: cwd must be a folder of this session's repository (a worktree or subfolder of it), not #{folder}"
+        unless same_project?(folder, base)
+          return "Error: cwd must be a folder of this session's project (a worktree or subfolder of it), not #{folder}"
         end
         if MemoryPaths.in_repo?(base) && !work_tree?(folder)
           return "Error: cwd #{folder} is not in a work tree of this session's repository (a git dir, or a bare " \
@@ -327,8 +328,11 @@ module Samagotchi
       def self.within?(path, dir) = path == dir || path.start_with?("#{dir}/")
       private_class_method :within?
 
-      def self.same_repository?(folder, base)
-        if MemoryPaths.in_repo?(base)
+      # One project (a git repository or a marked folder): the same project
+      # root, so a nested repository or marked project is another one. A base
+      # in no project: a subfolder of it.
+      def self.same_project?(folder, base)
+        if MemoryPaths.in_project?(base)
           MemoryPaths.project_root(folder) == MemoryPaths.project_root(base)
         else
           within?(folder, File.realpath(base))
@@ -336,7 +340,7 @@ module Samagotchi
       rescue SystemCallError
         false
       end
-      private_class_method :same_repository?
+      private_class_method :same_project?
 
       # @return [String] the child's id, or an Error: line
       def self.follow_up(task, session:, parent:, state_dir:)

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.157.0"
+  VERSION = "0.158.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end

data/lib/samagotchi/web/app.rb

@@ -17,6 +17,7 @@ require_relative "../delivery"
 require_relative "../answer_tail"
 require_relative "../answer_refs"
 require_relative "../question_asked"
+require_relative "../project_init"
 require_relative "../bridge_client"
 require_relative "../worker_link"
 require_relative "../bridge/bounded_queue"
@@ -268,6 +269,7 @@ module Samagotchi
         ["GET", %r{\A/(?:index\.html)?\z}, :serve_index, :participant],
         ["GET", %r{\A/api/sessions\z}, :handle_list, :owner],
         ["GET", %r{\A/api/projects\z}, :handle_projects, :owner],
+        ["POST", %r{\A/api/projects\z}, :handle_project_create, :owner],
         ["POST", %r{\A/api/sessions\z}, :handle_create, :owner],
         ["GET", %r{\A/api/sessions/resolve\z}, :handle_resolve, :participant],
         ["GET", %r{\A/api/sessions/summaries\z}, :handle_summaries, :owner],
@@ -1006,6 +1008,39 @@ module Samagotchi
         json_response(200, ProjectList.build(@hub.snapshot, start_dir: start_dir, current_root: current_root))
       end
 
+      def handle_project_create(req)
+        body = parse_json(request_body(req))
+        return error_response(400, "invalid_json", "invalid JSON body") unless body.is_a?(Hash)
+
+        requested = body["dir"]
+        requested = requested.strip if requested.is_a?(String)
+        unless requested.is_a?(String) && !requested.empty? && !requested.include?("\0")
+          return error_response(400, "invalid_dir", "dir must be an absolute folder")
+        end
+
+        home = Dir.home
+        dir = if requested == "~"
+                home
+              elsif requested.start_with?("~/")
+                File.join(home, requested.delete_prefix("~/"))
+              else
+                requested
+              end
+        return error_response(400, "invalid_dir", "dir must be an absolute folder") unless dir.start_with?("/")
+
+        # One normal form for the decision, the mkdir and the realpath (a `..` after a symlink would differ).
+        dir = File.expand_path(dir)
+        outcome = ProjectInit.call(dir, home: home)
+        return error_response(422, outcome.reason.to_s, outcome.message) if outcome.kind == :refused
+
+        if outcome.kind == :git
+          failed = ProjectInit.ensure_folder(dir)
+          return error_response(422, failed.reason.to_s, failed.message) if failed
+        end
+        dir = File.realpath(dir)
+        json_response(200, outcome: outcome.kind.to_s, root: outcome.root, dir: dir)
+      end
+
       # A scope folder from the page: [dir, nil] (dir nil when none was
       # given), or [nil, a 400 response] when it isn't an existing absolute
       # folder (a bookmarked worktree deleted since, a typo).

data/lib/samagotchi/web/project_list.rb

@@ -6,8 +6,8 @@ require_relative "push/attention"
 
 module Samagotchi
   module Web
-    # Projects represented by the session hub, plus the start project even
-    # when it has no sessions.
+    # Projects represented by the session hub, plus the start and current
+    # projects even when they have no sessions.
     module ProjectList
       module_function
 
@@ -24,6 +24,7 @@ module Samagotchi
           (groups[root] ||= []) << summary
         end
         groups[default_root] ||= [] if valid_root?(default_root)
+        groups[current_root] ||= [] if valid_root?(current_root)
 
         rows = groups.map do |root, sessions|
           default = root == default_root

data/lib/samagotchi/web/public/index.html

@@ -1488,6 +1488,11 @@ body.has-session #newBtn .brand-new{display:inline}
 .project-all::before{content:"";position:absolute;left:-1px;right:-1px;top:-9px;height:1px;background:var(--border);pointer-events:none}
 .project-note{padding:5px 2px;color:var(--text-muted);font-size:12px}
 .project-error{color:var(--warn-text)}
+.project-picker .project-new{width:100%;text-align:left;background:var(--bg-inset);color:var(--accent)}
+.project-create{display:grid;gap:8px;padding:8px 2px}
+.project-create label{color:var(--text-muted);font-size:12px}
+.project-create input{width:100%;padding:9px 10px;border:1px solid var(--border);border-radius:8px;background:var(--bg-inset);color:var(--text)}
+.project-create-actions{display:flex;justify-content:flex-end;gap:8px}
 body.has-session #scope .scope-where{display:none}
 /* A phone has no room for both; the hidden strip's pill (count, live) wins. */
 @media(max-width:600px){body.strip-hidden #scope .scope-where{display:none}}
@@ -1780,7 +1785,7 @@ a{color:var(--accent)}
 @media (max-width:600px),(pointer:coarse){
   #composer textarea,.question-freeform,.continue-reason,.participants-popover input,.participants-popover select,
   .rs-form textarea,.pp-link input,.llmctx-field select,.llmctx-field input,.ws-add-in,.rename-input,
-  #modelSearch{font-size:16px}
+  #modelSearch,.project-create input{font-size:16px}
 }
 </style>
 </head>

data/lib/samagotchi/web/public/project_picker.js

@@ -24,10 +24,19 @@ function projectRow(row) {
   </a>`;
 }
 
+function projectParent(rootLabel) {
+  if (typeof rootLabel !== "string" || !rootLabel) return "~/";
+  const slash = rootLabel.lastIndexOf("/");
+  if (slash < 0) return "~/";
+  const parent = rootLabel.slice(0, slash);
+  return parent ? `${parent.replace(/\/$/, "")}/` : "/";
+}
+
 // +rows+ is the API's ordered list. When there is no project scope, the
 // all-projects row is current; a bad ?dir= has no current project to mark.
 export function pickerTemplate({ rows = [], loading = false, error = "", currentDir = null,
-                                 allCurrent = false } = {}) {
+                                 allCurrent = false, createOpen = false, createPath = "~/", creating = false,
+                                 createError = "", onPathInput = () => {} } = {}) {
   const allHref = allScopeHref("", currentDir);
   return html`<div class="ctx-pop-head"><strong>Projects</strong><button type="button" class="ctx-pop-close"
       data-act="close" aria-label="Close">×</button></div>
@@ -39,7 +48,15 @@ export function pickerTemplate({ rows = [], loading = false, error = "", current
         <span class="project-main"><span class="project-name">All projects</span
           ><span class="project-hint">Every session</span></span>
         ${allCurrent ? html`<span class="project-check" aria-hidden="true">✓</span>` : nothing}
-      </a>
+      </a>${createOpen ? html`<form class="project-create" aria-busy=${creating}>
+        <label for="projectCreatePath">Folder path</label>
+        <input id="projectCreatePath" name="dir" type="text" autocomplete="off" .value=${createPath}
+          aria-invalid=${createError ? "true" : "false"} aria-describedby=${createError ? "projectCreateError" : nothing}
+          @input=${onPathInput}>
+        ${createError ? html`<div class="project-note project-error" id="projectCreateError" role="alert">${createError}</div>` : nothing}
+        <div class="project-create-actions"><button type="submit">${creating ? "Creating…" : "Create"}</button>
+          <button type="button" class="ghost" data-act="cancel-new">Cancel</button></div>
+      </form>` : html`<button type="button" class="project-row project-new" data-act="new-project">New project…</button>`}
     </nav>`;
 }
 
@@ -51,6 +68,12 @@ export function createProjectPicker({ el, scope, scopeError = () => null, api,
   let error = "";
   // Only the newest read is drawn; a close drops the one out (latest.js).
   const latest = createLatest();
+  // Creating a project must not invalidate an in-flight list read.
+  const createLatestAnswer = createLatest();
+  let createOpen = false;
+  let createPath = "~/";
+  let creating = false;
+  let createError = "";
 
   const currentDir = () => scopeError() ? null : scope.dir || null;
   const paint = (focus = false) => {
@@ -58,6 +81,8 @@ export function createProjectPicker({ el, scope, scopeError = () => null, api,
     render(pickerTemplate({
       rows, loading, error, currentDir: currentDir(),
       allCurrent: !scope.dir && !failedScope,
+      createOpen, createPath, creating, createError,
+      onPathInput: (event) => { createPath = event.currentTarget.value; },
     }), shell.pop);
     if (focus) {
       const target = shell.pop.querySelector('.project-row[aria-current="page"]') ||
@@ -89,11 +114,53 @@ export function createProjectPicker({ el, scope, scopeError = () => null, api,
     if (!fresh()) return;
     loading = false;
     if (shell.isOpen()) {
-      paint(focus);
+      // An open form keeps the caret: a late list must not pull focus to a row.
+      paint(focus && !createOpen);
       shell.replace();
     }
   }
 
+  async function submitProject() {
+    if (creating) return;
+    const fresh = createLatestAnswer.begin();
+    creating = true;
+    createError = "";
+    paint();
+    shell.replace();
+    try {
+      const answer = await api("/api/projects", { method: "POST", body: JSON.stringify({ dir: createPath }) });
+      if (!fresh()) return;
+      win.location.assign(projectScopeHref(answer.dir, ""));
+    } catch (e) {
+      if (!fresh()) return;
+      createError = e?.body?.detail || e?.message || String(e);
+      creating = false;
+      paint();
+      shell.replace();
+    }
+  }
+
+  function openCreateForm() {
+    createOpen = true;
+    createPath = projectParent(rows.find((row) => row.default)?.root_label);
+    createError = "";
+    creating = false;
+    paint();
+    shell.replace();
+    const input = shell.pop.querySelector("#projectCreatePath");
+    input?.focus();
+    input?.setSelectionRange(input.value.length, input.value.length);
+  }
+
+  function closeCreateForm() {
+    createLatestAnswer.drop();
+    createOpen = false;
+    creating = false;
+    createError = "";
+    paint();
+    shell.replace();
+  }
+
   const shell = createChipPopover({
     id: "projectPicker", className: "ctx-popover project-picker", width: 380, el, anchor: "#scopePick",
     summary: () => ({}), sheet: true, label: "Projects", doc, win,
@@ -101,10 +168,25 @@ export function createProjectPicker({ el, scope, scopeError = () => null, api,
       rows = [];
       loading = true;
       error = "";
+      createOpen = false;
+      createPath = "~/";
+      creating = false;
+      createError = "";
       paint();
       void load(true);
     },
-    onClose: () => { latest.drop(); },
+    onSubmit: () => { void submitProject(); },
+    onAct: (name) => {
+      if (name === "new-project") openCreateForm();
+      else if (name === "cancel-new") closeCreateForm();
+    },
+    onClose: () => {
+      latest.drop();
+      createLatestAnswer.drop();
+      createOpen = false;
+      creating = false;
+      createError = "";
+    },
   });
 
   return { pop: shell.pop, isOpen: shell.isOpen, load };

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: samagotchi
 version: !ruby/object:Gem::Version
-  version: 0.157.0
+  version: 0.158.0
 platform: ruby
 authors:
 - Dmitry Dedov
@@ -435,7 +435,6 @@ files:
 - lib/samagotchi/hook_question.rb
 - lib/samagotchi/hook_routes.rb
 - lib/samagotchi/hooks.rb
-- lib/samagotchi/hooks/bundle_loader.rb
 - lib/samagotchi/hooks/loader.rb
 - lib/samagotchi/hooks/registry.rb
 - lib/samagotchi/hooks/stream_watch.rb
@@ -592,7 +591,9 @@ files:
 - lib/samagotchi/plugin_tasks.rb
 - lib/samagotchi/private_files.rb
 - lib/samagotchi/process_group.rb
+- lib/samagotchi/project_command.rb
 - lib/samagotchi/project_env.rb
+- lib/samagotchi/project_init.rb
 - lib/samagotchi/project_scope.rb
 - lib/samagotchi/prompt.rb
 - lib/samagotchi/prompt_files.rb

data/lib/samagotchi/hooks/bundle_loader.rb

@@ -1,191 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "registry"
-require "digest"
-require_relative "../log"
-require_relative "../guardrails/load_failures"
-require_relative "../memory_bundle/bundle_hook"
-require_relative "../memory_bundle/provenance"
-
-module Samagotchi
-  # Namespace that wraps hook plugin classes per-bundle. Each bundle's hooks are
-  # evaluated inside `Samagotchi::Bundles::<BundleName>` so that two bundles
-  # shipping a file with the same basename (e.g. `guardrails.rb`) cannot collide
-  # on a top-level constant.
-  module Bundles; end
-
-  module Hooks
-    # Loads bundle-owned hook plugins into a Registry.
-    #
-    # Unlike +Hooks::Loader+ (which `require`s a file and resolves a top-level
-    # constant), this loader `module_eval`s each plugin file inside a
-    # per-bundle namespace module. This gives:
-    #   - zero class-name collisions across bundles
-    #   - a clean uninstall path (`Registry#unregister_bundle`)
-    #
-    # Each plugin must define a class whose PascalCase name matches the file
-    # basename and whose instances respond to +call(event)+.
-    #
-    # A "fail_closed" before_tool_call hook is required: if it is missing,
-    # fails to load, or its file's sha256 differs from the one recorded at
-    # install, the failure is reported and the gate denies every tool call.
-    # Any hook whose sha256 differs is not loaded (reinstall the bundle
-    # after editing a hook by hand), nor any of a bundle whose requires_chi
-    # this chi doesn't meet.
-    #
-    # The +on_error+ policy is applied per hook at fire time (Hooks.wrap):
-    #   - "fail_closed" (on :before_tool_call): a raising guardrail denies
-    #     the tool call (fail-closed).
-    #   - "log": warn to stderr and continue.
-    #   - "skip" (default): silently continue.
-    # Whatever the policy, a hook file that raises is told to the user once
-    # per hook (its +hook_failed+ callback, the Engine's
-    # HookRoutes#plugin_hook_failed): :skip would otherwise leave no trace.
-    module BundleLoader
-      class << self
-        # Load all hook plugins for a bundle into the given registry.
-        #
-        # @param bundle_name [String]
-        # @param hooks_dir [String] directory containing the bundle's .rb hook files
-        # @param metadata [Hash] basename => { event:, on_error:, priority:,
-        #   sha256: } (MemoryBundle::BundleHook.parse reads it)
-        # @param registry [Samagotchi::Hooks::Registry]
-        # @param failures [Guardrails::LoadFailures, nil] collects hooks that
-        #   failed to load
-        # @param settings [Hash] the bundle's section of config.yml
-        #   `bundles:` (string keys); a hook class whose initialize takes an
-        #   argument gets it
-        # @param manifest [MemoryBundle::InstalledManifest, nil] the installed
-        #   bundle's manifest; when this chi doesn't meet its requires_chi no
-        #   hook loads (each is reported, as the plugin loader does)
-        # @param hook_failed [#call, nil] (label, "Class: message", effect:)
-        #   when a hook file raises at fire time — the Engine's HookRoutes;
-        #   nil when there is no UI to tell (the test kit)
-        # @return [Integer] number of hooks successfully registered
-        def load(bundle_name:, hooks_dir:, metadata:, registry:, failures: nil, settings: {}, manifest: nil, hook_failed: nil)
-          return 0 unless metadata.is_a?(Hash)
-
-          too_old = manifest&.requires_chi_failure
-          loaded = 0
-          metadata.each do |raw_basename, raw_meta|
-            basename = raw_basename.to_s
-            next if basename.empty?
-
-            hook = MemoryBundle::BundleHook.parse(raw_meta)
-            # A hook with no declared event cannot be auto-registered.
-            next if hook.events.empty?
-
-            fail_closed = hook.events.any? { |event| hook.fail_closed?(event) }
-            what = "hook #{basename} (bundle #{bundle_name})"
-            file = hooks_dir && File.join(hooks_dir, basename)
-            unless file && File.exist?(file)
-              failures&.add(what, "the file is missing", required: true) if fail_closed
-              next
-            end
-            if (mismatch = too_old || sha_mismatch(file, hook.sha256, required: fail_closed))
-              Log.warn(:hooks, "bundle_hook_mismatch", echo: "[samagotchi:hooks] bundle '#{bundle_name}' hook '#{basename}' not loaded: #{mismatch}", bundle: bundle_name, hook: basename.to_s)
-              failures&.add(what, mismatch, required: fail_closed)
-              next
-            end
-
-            begin
-              load_hook_file(bundle_name, basename, file, hook, registry, settings: settings, hook_failed: hook_failed)
-              loaded += 1
-            rescue Exception => e # rubocop:disable Lint/RescueException -- a hook's SyntaxError or exit must not stop chi
-              raise if e.is_a?(SignalException) # Ctrl-C and kill signals are the user's
-
-              Log.error(:hooks, "bundle_hook_load_failed", echo: "[samagotchi:hooks] bundle '#{bundle_name}' hook '#{basename}' failed to load: #{e.class}: #{e.message}", bundle: bundle_name, hook: basename.to_s, error: e.class.name)
-              failures&.add(what, "#{e.class}: #{e.message}", required: fail_closed,
-                                  location: Guardrails::LoadFailures.location(e, File.dirname(hooks_dir)))
-            end
-          end
-          loaded
-        end
-
-        # Build one hook file and register it in +registry+ under each of
-        # its events (one instance for all: its state is shared), with its
-        # priority and error policy (a fail_closed before_tool_call one
-        # denies when it raises). No missing-file, sha or requires_chi
-        # check: #load makes them; the test kit loads a bundle's source
-        # this way.
-        # @param hook [MemoryBundle::BundleHook] its manifest entry
-        # @param namespace [Module, nil] the module the file is evaluated
-        #   in (default: the bundle's, #namespace_for)
-        # @param hook_failed [#call, nil] (label, "Class: message", effect:)
-        #   on every raise at fire time, whatever the policy; nil gives no
-        #   notice (the log still has a :log hook's failures)
-        # @raise [Exception] what loading or building the file raised;
-        #   nothing is registered then
-        def load_hook_file(bundle_name, basename, file, hook, registry, settings: {}, namespace: nil, hook_failed: nil)
-          plugin = instantiate(bundle_name, basename, file, settings: settings, namespace: namespace)
-          hook.events.each do |event_name|
-            event_sym = event_name.to_sym
-            fail_closed = hook.fail_closed?(event_sym)
-            policy = if fail_closed then :deny
-                     elsif hook.on_error == "log" then :log
-                     else :skip
-                     end
-            label = "#{"guardrail " if fail_closed}#{basename} (bundle #{bundle_name})"
-            # Every policy tells, once per label: a hook file under the
-            # default :skip would raise with no trace anywhere. The label
-            # names the file, the bundle and the event, so one label per
-            # hook and a stream hook can't nag.
-            on_failure = hook_failed && lambda { |hook_label, failed|
-              hook_failed.call("#{hook_label} #{event_sym} hook", failed, effect: policy)
-            }
-            handler = Hooks.wrap(label: label, event: event_sym, policy: policy, log: [:hooks, "bundle_hook_failed"],
-                                 fields: { bundle: bundle_name }, on_failure: on_failure) { |event| plugin.call(event) }
-            registry.register_bundle(bundle_name, event_sym, hook_name: basename, priority: hook.priority, &handler)
-          end
-          nil
-        end
-
-        # Why the file doesn't match the sha256 recorded at install, or nil.
-        # With none recorded, only a required hook counts as a mismatch.
-        def sha_mismatch(file, recorded, required:)
-          return nil if MemoryBundle::Provenance.unchecked?(recorded)
-
-          expected = MemoryBundle::Provenance.recorded_sha(recorded)
-          return (required ? "no sha256 recorded for it (reinstall the bundle)" : nil) if expected.empty?
-
-          actual = MemoryBundle::Provenance.file_sha(file)
-          return nil if actual == expected
-
-          "its sha256 #{actual[0, 12]}… differs from the installed #{expected[0, 12]}… (edited after install? reinstall the bundle)"
-        end
-
-        # Evaluate a plugin file inside the bundle's namespace module (or
-        # +namespace+) and
-        # return an instance that responds to #call. A class whose
-        # initialize takes an argument gets the settings (one Hash, string
-        # keys); one that takes none is built bare.
-        def instantiate(bundle_name, basename, file, settings: {}, namespace: nil)
-          ns = namespace || namespace_for(bundle_name)
-          content = File.read(file)
-          ns.module_eval(content, file, 1)
-          klass = Hooks.class_for(basename, ns)
-          instance = Hooks.build_plugin(klass, settings)
-          raise ArgumentError, "plugin #{klass.name.split("::").last} does not respond to #call" unless instance.respond_to?(:call)
-
-          instance
-        end
-
-        # The (lazily created) namespace module for a bundle.
-        # Sanitization is made injective by appending a short digest so that
-        # `my-bundle` and `my_bundle` do not collide.
-        def namespace_for(bundle_name)
-          raw = bundle_name.to_s
-          base = raw.gsub(/[^A-Za-z0-9_]/, "_")
-          base = "B_#{base}" unless base.match?(/\A[A-Z]/)
-          digest = Digest::MD5.hexdigest(raw)[0, 4]
-          ns_name = "#{base}_#{digest}"
-          if Samagotchi::Bundles.const_defined?(ns_name.to_sym, false)
-            Samagotchi::Bundles.const_get(ns_name.to_sym)
-          else
-            Samagotchi::Bundles.const_set(ns_name.to_sym, Module.new)
-          end
-        end
-      end
-    end
-  end
-end