textus 0.14.4 → 0.18.0

data/lib/textus/cli/verb/list.rb

@@ -2,11 +2,13 @@ module Textus
   class CLI
     class Verb
       class List < Verb
+        command_name "list"
+
         option :prefix, "--prefix=KEY"
         option :zone, "--zone=Z"
 
         def call(store)
-          emit({ "entries" => operations_for(store).reads.list.call(prefix: prefix, zone: zone) })
+          emit({ "entries" => operations_for(store).list(prefix: prefix, zone: zone) })
         end
       end
     end

data/lib/textus/cli/verb/mv.rb

@@ -2,13 +2,16 @@ module Textus
   class CLI
     class Verb
       class Mv < Verb
+        command_name "mv"
+        parent_group Group::Key
+
         option :as_flag, "--as=ROLE"
         option :dry_run, "--dry-run"
 
         def call(store)
           old_key = positional.shift or raise UsageError.new("mv requires <old-key> <new-key>")
           new_key = positional.shift or raise UsageError.new("mv requires <old-key> <new-key>")
-          emit(operations_for(store).writes.mv.call(old_key, new_key, dry_run: dry_run || false))
+          emit(operations_for(store).mv(old_key, new_key, dry_run: dry_run || false))
         end
       end
     end

data/lib/textus/cli/verb/published.rb

@@ -2,8 +2,10 @@ module Textus
   class CLI
     class Verb
       class Published < Verb
+        command_name "published"
+
         def call(store)
-          emit({ "published" => operations_for(store).reads.published.call })
+          emit({ "published" => operations_for(store).published })
         end
       end
     end

data/lib/textus/cli/verb/put.rb

@@ -2,6 +2,8 @@ module Textus
   class CLI
     class Verb
       class Put < Verb
+        command_name "put"
+
         option :as_flag, "--as=ROLE"
         option :use_stdin, "--stdin"
         option :fetch_name, "--fetch=NAME"
@@ -43,7 +45,7 @@ module Textus
           meta = payload["_meta"] || {}
           body = payload["body"] || ""
           if_etag = payload["if_etag"]
-          result = Textus::Operations.for(store, role: role).writes.put.call(key, meta: meta, body: body, if_etag: if_etag)
+          result = Textus::Operations.for(store, role: role).put(key, meta: meta, body: body, if_etag: if_etag)
           emit(result.to_h_for_wire)
         end
       end

data/lib/textus/cli/verb/rdeps.rb

@@ -2,9 +2,11 @@ module Textus
   class CLI
     class Verb
       class Rdeps < Verb
+        command_name "rdeps"
+
         def call(store)
           key = positional.shift or raise UsageError.new("rdeps requires a key")
-          emit({ "key" => key, "rdeps" => operations_for(store).reads.rdeps.call(key) })
+          emit({ "key" => key, "rdeps" => operations_for(store).rdeps(key) })
         end
       end
     end

data/lib/textus/cli/verb/refresh.rb

@@ -6,7 +6,7 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("refresh requires a key")
-          emit(operations_for(store).refresh.worker.run(key).to_h_for_wire)
+          emit(operations_for(store).refresh(key).to_h_for_wire)
         end
       end
     end

data/lib/textus/cli/verb/refresh_stale.rb

@@ -2,6 +2,9 @@ module Textus
   class CLI
     class Verb
       class RefreshStale < Verb
+        command_name "stale"
+        parent_group Group::Refresh
+
         option :prefix, "--prefix=KEY"
         option :zone, "--zone=Z"
         option :as_flag, "--as=ROLE"
@@ -10,7 +13,7 @@ module Textus
           ctx = context_for(store)
           result = Textus::Application::Refresh::All.call(ctx, prefix: prefix, zone: zone)
           emit(result)
-          exit(1) unless result["ok"]
+          result["ok"] ? 0 : 1
         end
       end
     end

data/lib/textus/cli/verb/reject.rb

@@ -2,11 +2,13 @@ module Textus
   class CLI
     class Verb
       class Reject < Verb
+        command_name "reject"
+
         option :as_flag, "--as=ROLE"
 
         def call(store)
           key = positional.shift or raise UsageError.new("reject requires a key")
-          emit(operations_for(store).writes.reject.call(key))
+          emit(operations_for(store).reject(key))
         end
       end
     end

data/lib/textus/cli/verb/rule_explain.rb

@@ -2,9 +2,12 @@ module Textus
   class CLI
     class Verb
       class RuleExplain < Verb
+        command_name "explain"
+        parent_group Group::Rule
+
         def call(store)
           key = positional.shift or raise UsageError.new("policy explain requires a KEY")
-          result = operations_for(store).reads.policy_explain.call(key: key)
+          result = operations_for(store).policy_explain(key: key)
           emit({ "verb" => "policy_explain" }.merge(result.transform_keys(&:to_s)))
         end
       end

data/lib/textus/cli/verb/rule_list.rb

@@ -2,6 +2,9 @@ module Textus
   class CLI
     class Verb
       class RuleList < Verb
+        command_name "list"
+        parent_group Group::Rule
+
         def call(store)
           policies = store.manifest.rules.blocks.map do |b|
             row = { "match" => b.match }

data/lib/textus/cli/verb/schema.rb

@@ -2,9 +2,12 @@ module Textus
   class CLI
     class Verb
       class Schema < Verb
+        command_name "show"
+        parent_group Group::Schema
+
         def call(store)
           key = positional.shift or raise UsageError.new("schema requires a key")
-          emit(operations_for(store).reads.schema_envelope.call(key))
+          emit(operations_for(store).schema_envelope(key))
         end
       end
     end

data/lib/textus/cli/verb/schema_diff.rb

@@ -2,6 +2,9 @@ module Textus
   class CLI
     class Verb
       class SchemaDiff < Verb
+        command_name "diff"
+        parent_group Group::Schema
+
         def call(store)
           name = positional.shift or raise UsageError.new("schema diff NAME")
           emit(Textus::Schema::Tools.diff(store, name: name))

data/lib/textus/cli/verb/schema_init.rb

@@ -2,6 +2,9 @@ module Textus
   class CLI
     class Verb
       class SchemaInit < Verb
+        command_name "init"
+        parent_group Group::Schema
+
         option :from_key, "--from=KEY"
 
         def call(store)

data/lib/textus/cli/verb/schema_migrate.rb

@@ -2,6 +2,9 @@ module Textus
   class CLI
     class Verb
       class SchemaMigrate < Verb
+        command_name "migrate"
+        parent_group Group::Schema
+
         option :rename, "--rename=O:N"
 
         def call(store)

data/lib/textus/cli/verb/uid.rb

@@ -2,9 +2,12 @@ module Textus
   class CLI
     class Verb
       class Uid < Verb
+        command_name "uid"
+        parent_group Group::Key
+
         def call(store)
           key = positional.shift or raise UsageError.new("uid requires a key")
-          emit({ "key" => key, "uid" => operations_for(store).reads.uid.call(key) })
+          emit({ "key" => key, "uid" => operations_for(store).uid(key) })
         end
       end
     end

data/lib/textus/cli/verb/where.rb

@@ -2,9 +2,11 @@ module Textus
   class CLI
     class Verb
       class Where < Verb
+        command_name "where"
+
         def call(store)
           key = positional.shift or raise UsageError.new("where requires a key")
-          emit(operations_for(store).reads.where.call(key))
+          emit(operations_for(store).where(key))
         end
       end
     end

data/lib/textus/cli/verb.rb

@@ -22,9 +22,39 @@ module Textus
           true
         end
 
+        # Declarative CLI name. Reader returns the registered name (or nil
+        # for verbs that aren't directly invokable, like the abstract
+        # Verb/Group base classes). Writer registers it.
+        def command_name(name = nil)
+          if name.nil?
+            @command_name
+          else
+            @command_name = name.to_s
+          end
+        end
+
+        # Declares that this verb is a subcommand of `group_klass`. When
+        # set, the verb is NOT a top-level CLI verb — it's listed under
+        # the group's subcommands instead.
+        def parent_group(group_klass = nil)
+          if group_klass.nil?
+            @parent_group
+          else
+            @parent_group = group_klass
+          end
+        end
+
         def inherited(subclass)
           super
           subclass.instance_variable_set(:@options, [])
+          subclass.instance_variable_set(:@command_name, nil)
+          subclass.instance_variable_set(:@parent_group, nil)
+        end
+
+        # Recursive subclass enumeration. Ruby 3.1 ships Class#subclasses
+        # but not Class#descendants, so we expand it ourselves.
+        def descendants
+          subclasses.flat_map { |k| [k] + k.descendants }
         end
       end
 

data/lib/textus/cli.rb

@@ -3,32 +3,23 @@ require "optparse"
 
 module Textus
   class CLI
-    # verb name → Verb subclass. Adding a new verb is a one-line entry here
-    # plus a new file under lib/textus/cli/.
-    VERBS = {
-      "accept" => Verb::Accept,
-      "audit" => Verb::Audit,
-      "blame" => Verb::Blame,
-      "reject" => Verb::Reject,
-      "build" => Verb::Build,
-      "delete" => Verb::Delete,
-      "deps" => Verb::Deps,
-      "doctor" => Verb::Doctor,
-      "freshness" => Verb::Freshness,
-      "get" => Verb::Get,
-      "hook" => Group::Hook,
-      "init" => Verb::Init,
-      "intro" => Verb::Intro,
-      "key" => Group::Key,
-      "list" => Verb::List,
-      "published" => Verb::Published,
-      "put" => Verb::Put,
-      "rdeps" => Verb::Rdeps,
-      "refresh" => Group::Refresh,
-      "rule" => Group::Rule,
-      "schema" => Group::Schema,
-      "where" => Verb::Where,
-    }.freeze
+    # Auto-derived verb table. Every CLI::Verb (or Group) subclass that
+    # declares `command_name "X"` and has no `parent_group` is a top-level
+    # verb. Sorted alphabetically for stable help output. Adding a new
+    # verb requires only a new file declaring its `command_name`.
+    def self.verbs
+      Verb.descendants
+          .select { |k| k.command_name && k.parent_group.nil? }
+          .sort_by(&:command_name)
+          .to_h { |k| [k.command_name, k] }
+    end
+
+    # Backward-compat constant; callers should prefer `CLI.verbs`.
+    def self.const_missing(name)
+      return verbs.freeze if name == :VERBS
+
+      super
+    end
 
     def self.run(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, cwd: Dir.pwd)
       new(stdin: stdin, stdout: stdout, stderr: stderr, cwd: cwd).run(argv)
@@ -47,21 +38,35 @@ module Textus
       verb = argv.shift
       raise UsageError.new("missing verb") if verb.nil?
 
-      case verb
-      when "--version", "-v" then @stdout.puts(VERSION)
-                                  0
-      when "--help", "-h"    then print_help
-                                  0
-      else
-        klass = VERBS[verb] or raise UsageError.new("unknown verb: #{verb}")
-        dispatch(klass, argv)
-      end
+      result =
+        case verb
+        when "--version", "-v" then @stdout.puts(VERSION)
+                                    0
+        when "--help", "-h"    then print_help
+                                    0
+        else
+          klass = self.class.verbs[verb] or raise UsageError.new("unknown verb: #{verb}")
+          dispatch(klass, argv)
+        end
+
+      coerce_exit_code(result)
     rescue Textus::Error => e
       emit_error(e)
     end
 
     private
 
+    def coerce_exit_code(value)
+      case value
+      when Integer then value
+      when true, nil then 0
+      when false then 1
+      else
+        @stderr.puts("warning: verb returned non-Integer #{value.class}; treating as 0")
+        0
+      end
+    end
+
     def store
       @store ||= Store.discover(@cwd, root: @root_arg)
     end

data/lib/textus/doctor/check/audit_log.rb

@@ -4,7 +4,7 @@ module Textus
       class AuditLog < Check
         def call
           path = File.join(store.root, "audit.log")
-          Textus::Store::AuditLog.new(store.root).verify_integrity.map do |v|
+          Textus::Infra::AuditLog.new(store.root).verify_integrity.map do |v|
             {
               "code" => "audit.parse_error",
               "level" => "warning",

data/lib/textus/doctor/check/hooks.rb

@@ -9,8 +9,10 @@ module Textus
 
           Dir.glob(File.join(dir, "*.rb")).sort.each do |f| # rubocop:disable Lint/RedundantDirGlobSort
             registry = Textus::Hooks::Registry.new
-            Textus.with_registry(registry) do
+            Textus.drain_hook_blocks
+            begin
               load(f)
+              Textus.drain_hook_blocks.each { |b| b.call(registry) }
             end
           rescue StandardError, ScriptError => e
             out << {

data/lib/textus/doctor/check/intake_registration.rb

@@ -13,8 +13,8 @@ module Textus
               "code" => "intake.handler_missing",
               "level" => "error",
               "subject" => name.to_s,
-              "message" => "manifest references intake handler '#{name}' but no Textus.on(:resolve_intake, :#{name}) is registered",
-              "fix" => "create .textus/hooks/#{name}.rb with `Textus.on(:resolve_intake, :#{name}) { ... }`",
+              "message" => "manifest references intake handler '#{name}' but no resolve_intake hook for '#{name}' is registered",
+              "fix" => "create .textus/hooks/#{name}.rb with `Textus.hook { |reg| reg.on(:resolve_intake, :#{name}) { ... } }`",
             }
           end
 
@@ -23,7 +23,7 @@ module Textus
               "code" => "intake.handler_orphan",
               "level" => "warning",
               "subject" => name.to_s,
-              "message" => "Textus.on(:resolve_intake, :#{name}) is registered but no manifest entry references it",
+              "message" => "resolve_intake hook '#{name}' is registered but no manifest entry references it",
               "fix" => "remove the unused handler, or add an entry with `intake.handler: #{name}`",
             }
           end

data/lib/textus/doctor/check/schema_violations.rb

@@ -3,7 +3,7 @@ module Textus
     class Check
       class SchemaViolations < Check
         def call
-          res = Textus::Operations.for(store).reads.validate_all.call
+          res = Textus::Operations.for(store).validate_all
           res["violations"].map do |v|
             fix = v["expected"] &&
                   "field '#{v["field"]}' should be written by '#{v["expected"]}' (last writer: #{v["last_writer"]})"

data/lib/textus/doctor/check/sentinels.rb

@@ -7,7 +7,7 @@ module Textus
           return [] unless File.directory?(dir)
 
           repo_root = File.dirname(store.root)
-          Dir.glob(File.join(dir, "**", "*#{Textus::Store::Sentinel::SUFFIX}")).flat_map do |sentinel_path|
+          Dir.glob(File.join(dir, "**", "*#{Textus::Domain::Sentinel::SUFFIX}")).flat_map do |sentinel_path|
             inspect_sentinel(sentinel_path, repo_root)
           end
         end
@@ -15,7 +15,7 @@ module Textus
         private
 
         def inspect_sentinel(sentinel_path, repo_root)
-          sentinel = Textus::Store::Sentinel.load(sentinel_path, repo_root)
+          sentinel = Textus::Domain::Sentinel.load(sentinel_path, repo_root)
           return [parse_error_issue(sentinel_path)] if sentinel.nil?
           return [orphan_issue(sentinel_path, sentinel)] if sentinel.orphan?
           return [drift_issue(sentinel)] if sentinel.drift?

data/lib/textus/domain/freshness/evaluator.rb

@@ -2,7 +2,7 @@ require "time"
 
 module Textus
   module Domain
-    module Freshness
+    class Freshness
       module Evaluator
         module_function
 

data/lib/textus/domain/freshness/policy.rb

@@ -1,6 +1,6 @@
 module Textus
   module Domain
-    module Freshness
+    class Freshness
       Policy = Data.define(:ttl_seconds, :on_stale, :sync_budget_ms) do
         def decide(verdict)
           return Action::Return.new if verdict.fresh?

data/lib/textus/domain/freshness/verdict.rb

@@ -1,6 +1,6 @@
 module Textus
   module Domain
-    module Freshness
+    class Freshness
       Verdict = Data.define(:fresh, :reason) do
         def self.fresh         = new(fresh: true, reason: nil)
         def self.stale(reason) = new(fresh: false, reason: reason)

data/lib/textus/domain/freshness.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Textus
+  module Domain
+    # Value object describing the freshness annotation attached to an Envelope
+    # after a freshness evaluation. Replaces the loose Hash that used to live
+    # on `Envelope#freshness`.
+    #
+    # Note on wire format: `#to_h_for_wire` is intentionally narrower than the
+    # full field set. It emits the legacy keys ("stale", "stale_reason",
+    # "refreshing", and "refresh_error" when present) so the CLI JSON wire
+    # stays byte-identical with textus/3. The gem-side fields `checked_at`
+    # and `ttl_remaining_ms` are NOT emitted on the wire in this phase.
+    Freshness = Data.define(
+      :stale, :refreshing, :reason, :refresh_error, :checked_at, :ttl_remaining_ms
+    ) do
+      def self.build(stale:, refreshing: false, reason: nil, refresh_error: nil,
+                     checked_at: nil, ttl_remaining_ms: nil)
+        new(
+          stale: stale,
+          refreshing: refreshing,
+          reason: reason,
+          refresh_error: refresh_error,
+          checked_at: checked_at,
+          ttl_remaining_ms: ttl_remaining_ms,
+        )
+      end
+
+      def to_h_for_wire
+        h = {
+          "stale" => stale,
+          "stale_reason" => reason,
+          "refreshing" => refreshing,
+        }
+        h["refresh_error"] = refresh_error unless refresh_error.nil?
+        h
+      end
+    end
+  end
+end

data/lib/textus/domain/policy/predicates/schema_valid.rb

@@ -15,11 +15,11 @@ module Textus
             target_key = entry.meta&.dig("proposal", "target_key")
             return true unless target_key
 
-            mentry, = store.manifest.resolve(target_key)
+            mentry = store.manifest.resolve(target_key).entry
             schema_ref = mentry&.schema
             return true unless schema_ref
 
-            schema = store.schema_for(schema_ref)
+            schema = store.schemas.fetch_or_nil(schema_ref)
             return true unless schema
 
             frontmatter = entry.meta&.dig("frontmatter") || {}

data/lib/textus/{store → domain}/sentinel.rb

@@ -3,7 +3,7 @@ require "digest"
 require "fileutils"
 
 module Textus
-  class Store
+  module Domain
     # Value object for sentinel files written by Infra::Publisher and inspected
     # by Doctor::Check::Sentinels. Owns the JSON shape ({source, target,
     # sha256, mode}) and the on-disk path layout (<store_root>/sentinels/

data/lib/textus/{store → domain}/staleness/generator_check.rb

@@ -1,7 +1,7 @@
 require "time"
 
 module Textus
-  class Store
+  module Domain
     class Staleness
       # Reports staleness for generator-zone entries — derived files whose
       # generator's listed sources have been modified more recently than the

data/lib/textus/{store → domain}/staleness/intake_check.rb

@@ -1,7 +1,7 @@
 require "time"
 
 module Textus
-  class Store
+  module Domain
     class Staleness
       # Reports TTL-exceeded staleness for intake-handler entries. Returns an
       # Array of row hashes (possibly empty) per entry.

data/lib/textus/{store → domain}/staleness.rb

@@ -1,5 +1,5 @@
 module Textus
-  class Store
+  module Domain
     class Staleness
       def initialize(manifest:)
         @manifest = manifest

data/lib/textus/entry/json.rb

@@ -85,7 +85,7 @@ module Textus
 
       def self.inject_uid(meta, content, existing_uid)
         m = meta.is_a?(Hash) ? meta.dup : {}
-        m["uid"] = existing_uid || Textus::Store.mint_uid unless m["uid"].is_a?(String) && !m["uid"].empty?
+        m["uid"] = existing_uid || Textus::Uid.mint unless m["uid"].is_a?(String) && !m["uid"].empty?
         [m, content]
       end
 

data/lib/textus/entry/markdown.rb

@@ -70,7 +70,7 @@ module Textus
 
       def self.inject_uid(meta, content, existing_uid)
         m = meta.is_a?(Hash) ? meta.dup : {}
-        m["uid"] = existing_uid || Textus::Store.mint_uid unless m["uid"].is_a?(String) && !m["uid"].empty?
+        m["uid"] = existing_uid || Textus::Uid.mint unless m["uid"].is_a?(String) && !m["uid"].empty?
         [m, content]
       end
 

data/lib/textus/entry/yaml.rb

@@ -83,7 +83,7 @@ module Textus
 
       def self.inject_uid(meta, content, existing_uid)
         m = meta.is_a?(Hash) ? meta.dup : {}
-        m["uid"] = existing_uid || Textus::Store.mint_uid unless m["uid"].is_a?(String) && !m["uid"].empty?
+        m["uid"] = existing_uid || Textus::Uid.mint unless m["uid"].is_a?(String) && !m["uid"].empty?
         [m, content]
       end
 

data/lib/textus/envelope.rb

@@ -45,16 +45,20 @@ module Textus
         "uid" => uid,
       }
       h["content"] = content unless content.nil?
-      freshness.each { |k, v| h[k.to_s] = v } if freshness.is_a?(Hash)
+      freshness&.to_h_for_wire&.each { |k, v| h[k] = v }
       h
     end
 
     def stale?
-      freshness.is_a?(Hash) && (freshness["stale"] == true || freshness[:stale] == true)
+      return false if freshness.nil?
+
+      freshness.stale == true
     end
 
     def refreshing?
-      freshness.is_a?(Hash) && (freshness["refreshing"] == true || freshness[:refreshing] == true)
+      return false if freshness.nil?
+
+      freshness.refreshing == true
     end
   end
 end

data/lib/textus/errors.rb

@@ -108,6 +108,25 @@ module Textus
     end
   end
 
+  class ReadForbidden < Error
+    def initialize(k, z, readers: nil)
+      readers_str =
+        if readers && !readers.empty?
+          readers.join(", ")
+        else
+          "the role(s) listed in the manifest 'read_policy:'"
+        end
+      details = { "key" => k, "zone" => z }
+      details["readers"] = readers if readers
+      super(
+        "read_forbidden",
+        "zone '#{z}' is not readable by role for key '#{k}'",
+        details: details,
+        hint: "this zone is readable by #{readers_str}; pass --as=<role>",
+      )
+    end
+  end
+
   class EtagMismatch < Error
     def initialize(k, w, g)
       super(