textus 0.10.5 → 0.14.0

data/lib/textus/cli.rb

@@ -21,12 +21,11 @@ module Textus
       "intro" => Verb::Intro,
       "key" => Group::Key,
       "list" => Verb::List,
-      "policy" => Group::Policy,
       "published" => Verb::Published,
       "put" => Verb::Put,
       "rdeps" => Verb::Rdeps,
-      "refresh" => Verb::Refresh,
-      "refresh-stale" => Verb::RefreshStale,
+      "refresh" => Group::Refresh,
+      "rule" => Group::Rule,
       "schema" => Group::Schema,
       "where" => Verb::Where,
     }.freeze
@@ -90,16 +89,17 @@ module Textus
           textus get KEY
           textus put KEY --stdin [--fetch=NAME] --as=ROLE
           textus freshness [--prefix=KEY] [--zone=Z]
-          textus refresh-stale [--prefix=KEY] [--zone=Z]
+          textus refresh KEY
+          textus refresh stale [--prefix=KEY] [--zone=Z]
           textus audit [--key=K] [--zone=Z] [--role=R] [--verb=V] [--since=X] [--correlation-id=ID] [--limit=N]
           textus blame KEY [--limit=N]
           textus doctor
           textus intro
 
-          textus key {mv,uid,migrate}
+          textus key {mv,uid,normalize}
+          textus rule {list,explain}
           textus schema {show,init,diff,migrate}
           textus hook {list,run}
-          textus policy {list,explain}
       HELP
     end
   end

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

@@ -11,7 +11,7 @@ module Textus
             handler = mentry.intake_handler
             next if handler.nil?
 
-            allow = store.manifest.policies_for(mentry.key).handler_allowlist
+            allow = store.manifest.rules_for(mentry.key).handler_allowlist
             next if allow.nil?
             next if allow.allows?(handler)
 

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

@@ -10,28 +10,51 @@ module Textus
             base = File.join(store.root, "zones", entry.path)
             next unless File.directory?(base)
 
-            walk_nested(base) do |abs_path, is_dir|
-              basename = File.basename(abs_path)
-              stem = is_dir ? basename : basename.sub(/#{Regexp.escape(File.extname(basename))}\z/, "")
-              next if stem.match?(Key::Grammar::SEGMENT)
-
-              proposed = Textus::MigrateKeys.normalize(stem)
-              out << {
-                "code" => "key.illegal",
-                "level" => "error",
-                "subject" => abs_path,
-                "path" => abs_path,
-                "proposed_key" => proposed,
-                "message" => "illegal key segment '#{stem}' at #{abs_path}",
-                "fix" => "run 'textus key migrate --dry-run' then '--write' to rename to '#{proposed}'",
-              }
-            end
+            entry.index_filename ? check_index_paths(entry, base, out) : check_all_paths(base, out)
           end
           out
         end
 
         private
 
+        def check_all_paths(base, out)
+          walk_nested(base) do |abs_path, is_dir|
+            basename = File.basename(abs_path)
+            stem = is_dir ? basename : basename.sub(/#{Regexp.escape(File.extname(basename))}\z/, "")
+            next if stem.match?(Key::Grammar::SEGMENT)
+
+            out << issue(abs_path, stem)
+          end
+        end
+
+        # When the entry uses `index_filename:`, only the parent-directory
+        # segments leading to each index file participate in keys. Sibling
+        # files and unrelated subtrees are not enumerated and must not be
+        # flagged. Each illegal segment is reported once per path.
+        def check_index_paths(entry, base, out)
+          Dir.glob(File.join(base, "**", entry.index_filename)).each do |fp|
+            rel = fp.sub(%r{\A#{Regexp.escape(base)}/?}, "")
+            File.dirname(rel).split("/").reject { |s| s.empty? || s == "." }.each do |seg|
+              next if seg.match?(Key::Grammar::SEGMENT)
+
+              out << issue(fp, seg)
+            end
+          end
+        end
+
+        def issue(abs_path, stem)
+          proposed = Textus::MigrateKeys.normalize(stem)
+          {
+            "code" => "key.illegal",
+            "level" => "error",
+            "subject" => abs_path,
+            "path" => abs_path,
+            "proposed_key" => proposed,
+            "message" => "illegal key segment '#{stem}' at #{abs_path}",
+            "fix" => "run 'textus key normalize --dry-run' then '--write' to rename to '#{proposed}'",
+          }
+        end
+
         def walk_nested(root, &block)
           Dir.each_child(root) do |name|
             abs = File.join(root, name)

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

@@ -6,15 +6,15 @@ module Textus
 
         def call
           declared = collect_declared_handlers
-          registered = store.registry.rpc_names(:intake).to_set
+          registered = store.registry.rpc_names(:resolve_intake).to_set
 
           out = (declared - registered).map do |name|
             {
               "code" => "intake.handler_missing",
               "level" => "error",
               "subject" => name.to_s,
-              "message" => "manifest references intake handler '#{name}' but no Textus.intake(:#{name}) is registered",
-              "fix" => "create .textus/hooks/#{name}.rb with `Textus.intake(:#{name}) { ... }`",
+              "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}) { ... }`",
             }
           end
 
@@ -23,7 +23,7 @@ module Textus
               "code" => "intake.handler_orphan",
               "level" => "warning",
               "subject" => name.to_s,
-              "message" => "Textus.intake(:#{name}) is registered but no manifest entry references it",
+              "message" => "Textus.on(:resolve_intake, :#{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/protocol_version.rb

@@ -0,0 +1,47 @@
+require "yaml"
+
+module Textus
+  module Doctor
+    class Check
+      # Runs as a standalone module (Check::ProtocolVersion.run(root:)) and also
+      # as a class-based doctor check (ProtocolVersion.new(store).call).
+      class ProtocolVersion < Check
+        # Standalone interface: root is the project root (parent of .textus/).
+        def self.run(root:)
+          path = File.join(root, ".textus/manifest.yaml")
+          return [] unless File.exist?(path)
+
+          doc = YAML.safe_load_file(path, aliases: false) || {}
+          version = doc["version"]
+          return [] if version == "textus/3"
+
+          [{
+            "code" => "protocol_mismatch",
+            "severity" => "error",
+            "message" => "Store reports version=#{version.inspect}; this gem expects textus/3.",
+            "hint" => "Install textus 0.11.x to run the migrator, then upgrade to this version. See https://github.com/patrick204nqh/textus/blob/main/CHANGELOG.md#0110",
+          }]
+        end
+
+        # Doctor check interface: store.root is the .textus/ directory itself,
+        # so manifest.yaml lives directly inside it.
+        def call
+          path = File.join(store.root, "manifest.yaml")
+          return [] unless File.exist?(path)
+
+          doc = YAML.safe_load_file(path, aliases: false) || {}
+          version = doc["version"]
+          return [] if version == "textus/3"
+
+          [{
+            "code" => "protocol_mismatch",
+            "level" => "error",
+            "subject" => path,
+            "message" => "Store reports version=#{version.inspect}; this gem expects textus/3.",
+            "fix" => "Install textus 0.11.x to run the migrator, then upgrade to this version. See https://github.com/patrick204nqh/textus/blob/main/CHANGELOG.md#0110",
+          }]
+        end
+      end
+    end
+  end
+end

data/lib/textus/doctor/check/{policy_ambiguity.rb → rule_ambiguity.rb}

@@ -1,18 +1,18 @@
 module Textus
   module Doctor
     class Check
-      # Flags entries whose key is matched by two or more policy blocks of the
+      # Flags entries whose key is matched by two or more rule blocks of the
       # SAME specificity in the same slot (refresh / handler_allowlist /
       # promote). Ties are non-deterministic in the parser's pick step, so
       # they're a configuration smell — surface them.
-      class PolicyAmbiguity < Check
+      class RuleAmbiguity < Check
         SLOTS = %i[refresh handler_allowlist promote].freeze
 
         def call
           out = []
-          policies = store.manifest.policies
+          rules = store.manifest.rules
           store.manifest.entries.each do |mentry|
-            matches = policies.explain(mentry.key)
+            matches = rules.explain(mentry.key)
             next if matches.length < 2
 
             SLOTS.each { |slot| out.concat(ambiguities_for(mentry, slot, matches)) }
@@ -34,10 +34,10 @@ module Textus
         def issue_for(mentry, slot, group)
           globs = group.map(&:match).sort
           {
-            "code" => "policy.ambiguity",
+            "code" => "rule.ambiguity",
             "level" => "warning",
             "subject" => mentry.key,
-            "message" => "entry '#{mentry.key}' matches #{group.length} policy blocks at the same " \
+            "message" => "entry '#{mentry.key}' matches #{group.length} rule blocks at the same " \
                          "specificity for #{slot}: #{globs.join(", ")}",
             "fix" => "narrow one of the conflicting match: globs in .textus/manifest.yaml so a single " \
                      "block wins for this key",

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

@@ -3,7 +3,7 @@ module Textus
     class Check
       class SchemaViolations < Check
         def call
-          res = store.validate_all
+          res = Textus::Operations.for(store).reads.validate_all.call
           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.rb

@@ -9,6 +9,7 @@ module Textus
     DOCTOR_CHECK_TIMEOUT_SECONDS = 2
 
     CHECKS = [
+      Check::ProtocolVersion,
       Check::ManifestFiles,
       Check::Schemas,
       Check::SchemaParseError,
@@ -20,7 +21,7 @@ module Textus
       Check::AuditLog,
       Check::UnownedSchemaFields,
       Check::SchemaViolations,
-      Check::PolicyAmbiguity,
+      Check::RuleAmbiguity,
       Check::HandlerAllowlist,
     ].freeze
 
@@ -52,9 +53,9 @@ module Textus
 
     def run_registered_checks(store)
       out = []
-      view = Application::Context.new(store: store, role: "human")
-      store.registry.rpc_names(:check).each do |name|
-        callable = store.registry.rpc_callable(:check, name)
+      view = Application::Context.system(store)
+      store.registry.rpc_names(:validate).each do |name|
+        callable = store.registry.rpc_callable(:validate, name)
         begin
           result = Timeout.timeout(DOCTOR_CHECK_TIMEOUT_SECONDS) { callable.call(store: view) }
           if result.is_a?(Array)
@@ -71,7 +72,7 @@ module Textus
         rescue StandardError => e
           out << fail_issue(name, code: "doctor_check.failed",
                                   message: "#{e.class}: #{e.message}",
-                                  fix: "fix the :check hook in .textus/hooks/")
+                                  fix: "fix the :validate hook in .textus/hooks/")
         end
       end
       out

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

@@ -9,7 +9,7 @@ module Textus
         def call(policy, envelope, now:)
           return Verdict.fresh if policy.ttl_seconds.nil?
 
-          last_str = envelope.dig("_meta", "last_refreshed_at")
+          last_str = envelope&.meta&.dig("last_refreshed_at")
           return Verdict.stale("never refreshed") if last_str.nil?
 
           last = begin

data/lib/textus/domain/permission.rb

@@ -1,14 +1,14 @@
 module Textus
   module Domain
-    Permission = Data.define(:zone, :writable_by, :readable_by) do
+    Permission = Data.define(:zone, :write_policy, :read_policy) do
       def allows_write?(role)
-        writable_by.include?(role.to_s)
+        write_policy.include?(role.to_s)
       end
 
       def allows_read?(role)
-        return true if readable_by == :all
+        return true if [:all, ["all"]].include?(read_policy)
 
-        readable_by.include?(role.to_s)
+        read_policy.include?(role.to_s)
       end
     end
   end

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

@@ -0,0 +1,31 @@
+module Textus
+  module Domain
+    module Policy
+      module Predicates
+        class HumanAccept
+          attr_reader :reason
+
+          def name
+            "human_accept"
+          end
+
+          # The role is passed via `store` (an Application::Context-like object
+          # with a `role` reader) or through the entry metadata. In practice,
+          # Accept already enforces role == "human" before reaching the
+          # promotion gate, so this predicate trivially passes. It documents
+          # intent and future-proofs multi-actor accept flows.
+          def call(store:, entry: nil) # rubocop:disable Lint/UnusedMethodArgument
+            role = store.respond_to?(:role) ? store.role.to_s : nil
+            # If we cannot determine the role (e.g. store doesn't expose it),
+            # we trust that Accept has already checked — allow through.
+            return true if role.nil?
+
+            ok = (role == "human")
+            @reason = "current role is '#{role}', expected 'human'" unless ok
+            ok
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+module Textus
+  module Domain
+    module Policy
+      module Predicates
+        class SchemaValid
+          attr_reader :reason
+
+          def name
+            "schema_valid"
+          end
+
+          def call(entry:, store:) # rubocop:disable Metrics/PerceivedComplexity
+            return true if entry.nil? || store.nil?
+
+            target_key = entry.meta&.dig("proposal", "target_key")
+            return true unless target_key
+
+            mentry, = store.manifest.resolve(target_key)
+            schema_ref = mentry&.schema
+            return true unless schema_ref
+
+            schema = store.schema_for(schema_ref)
+            return true unless schema
+
+            frontmatter = entry.meta&.dig("frontmatter") || {}
+            begin
+              schema.validate!(frontmatter)
+            rescue Textus::SchemaViolation => e
+              @reason = e.message.dup
+              d = e.details
+              if d.is_a?(Hash)
+                if d["missing"]
+                  @reason = "missing required fields: #{Array(d["missing"]).join(", ")}"
+                elsif d["field"]
+                  @reason = "field '#{d["field"]}': #{d["reason"]}"
+                end
+              end
+              return false
+            end
+
+            true
+          rescue StandardError => e
+            @reason = "schema validation error: #{e.message}"
+            false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+module Textus
+  module Domain
+    module Policy
+      # Promotion evaluates a list of named predicates against a pending-proposal
+      # entry and returns a Result indicating whether all requirements are met.
+      class Promotion
+        Result = Struct.new(:ok?, :reasons, keyword_init: true)
+
+        REGISTRY = {
+          "schema_valid" => -> { Predicates::SchemaValid.new },
+          "human_accept" => -> { Predicates::HumanAccept.new },
+        }.freeze
+
+        def self.from_names(names)
+          predicates = Array(names).map do |n|
+            ctor = REGISTRY[n.to_s] or raise Textus::UsageError.new(
+              "unknown promotion predicate: '#{n}' (known: #{REGISTRY.keys.join(", ")})",
+            )
+            ctor.call
+          end
+          new(predicates: predicates)
+        end
+
+        attr_reader :predicates
+
+        def initialize(predicates:)
+          @predicates = predicates
+        end
+
+        def predicate_names
+          @predicates.map(&:name)
+        end
+
+        def evaluate(entry:, store:)
+          reasons = []
+          @predicates.each do |pred|
+            ok = pred.call(entry: entry, store: store)
+            reasons << "#{pred.name}: #{pred.reason || "predicate failed"}" unless ok
+          end
+          Result.new(ok?: reasons.empty?, reasons: reasons)
+        end
+      end
+    end
+  end
+end

data/lib/textus/entry/base.rb

@@ -25,6 +25,34 @@ module Textus
       def self.validate_against(schema, parsed)
         schema.validate!(parsed["_meta"] || {})
       end
+
+      def self.nested_glob
+        raise NotImplementedError.new("#{name}.nested_glob not implemented")
+      end
+
+      def self.validate_path_extension(_path, _nested)
+        raise NotImplementedError.new("#{name}.validate_path_extension not implemented")
+      end
+
+      def self.inject_uid(_meta, _content, _existing_uid)
+        raise NotImplementedError.new("#{name}.inject_uid not implemented")
+      end
+
+      def self.enforce_name_match!(_path, _meta)
+        raise NotImplementedError.new("#{name}.enforce_name_match! not implemented")
+      end
+
+      def self.serialize_for_put(meta:, body:, content:, path:)
+        _ = meta
+        _ = body
+        _ = content
+        _ = path
+        raise NotImplementedError.new("#{name}.serialize_for_put not implemented")
+      end
+
+      def self.rewrite_name(_path, _basename)
+        raise NotImplementedError.new("#{name}.rewrite_name not implemented")
+      end
     end
   end
 end

data/lib/textus/entry/json.rb

@@ -42,6 +42,65 @@ module Textus
       end
 
       def self.extensions = [".json"]
+
+      def self.nested_glob = "**/*.json"
+
+      def self.serialize_for_put(meta:, body:, content:, path:)
+        raise UsageError.new("put for json requires content: or body:") if content.nil? && (body.nil? || body.to_s.empty?)
+
+        if content.nil?
+          begin
+            parsed = parse(body.to_s, path: path)
+          rescue BadFrontmatter => e
+            raise BadContent.new(path, "bad_content: #{e.message}")
+          end
+          [body.to_s, parsed["_meta"], body.to_s, parsed["content"]]
+        else
+          bytes = serialize(meta: meta, body: "", content: content)
+          [bytes, meta, bytes, content]
+        end
+      end
+
+      # Mutating filesystem op; returns true if a write happened.
+      def self.rewrite_name(path, basename) # rubocop:disable Naming/PredicateMethod
+        raw = File.binread(path)
+        parsed = parse(raw, path: path)
+        meta = parsed["_meta"]
+        return false unless meta.is_a?(Hash) && meta["name"].is_a?(String) && meta["name"] != basename
+
+        new_meta = meta.merge("name" => basename)
+        File.binwrite(path, serialize(meta: new_meta, body: "", content: parsed["content"]))
+        true
+      end
+
+      def self.enforce_name_match!(path, meta)
+        return unless meta.is_a?(Hash) && meta["name"]
+
+        ext = extensions.first
+        basename = File.basename(path, ext)
+        return if meta["name"] == basename
+
+        raise BadFrontmatter.new(path, "name '#{meta["name"]}' does not match basename '#{basename}'")
+      end
+
+      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, content]
+      end
+
+      def self.validate_path_extension(path, nested)
+        ext = File.extname(path)
+        if nested
+          return if ext == ""
+
+          raise UsageError.new("nested json path must not have an extension")
+        end
+
+        return if ext == ".json"
+
+        raise UsageError.new("json format requires '.json' path (got #{ext.inspect})")
+      end
     end
   end
 end

data/lib/textus/entry/markdown.rb

@@ -34,6 +34,52 @@ module Textus
       end
 
       def self.extensions = [".md"]
+
+      def self.nested_glob = "**/*.md"
+
+      def self.serialize_for_put(meta:, body:, content:, path:)
+        _ = path
+        _ = content
+        bytes = serialize(meta: meta || {}, body: body.to_s)
+        [bytes, meta, body.to_s, nil]
+      end
+
+      # Mutating filesystem op; returns true if a write happened (boolean is
+      # informational, not a predicate). Rubocop's predicate-name heuristic
+      # disabled here on purpose.
+      def self.rewrite_name(path, basename) # rubocop:disable Naming/PredicateMethod
+        raw = File.binread(path)
+        parsed = parse(raw, path: path)
+        meta = parsed["_meta"] || {}
+        return false unless meta.is_a?(Hash) && meta["name"].is_a?(String) && meta["name"] != basename
+
+        new_meta = meta.merge("name" => basename)
+        File.binwrite(path, serialize(meta: new_meta, body: parsed["body"]))
+        true
+      end
+
+      def self.enforce_name_match!(path, meta)
+        return unless meta.is_a?(Hash) && meta["name"]
+
+        ext = extensions.first
+        basename = File.basename(path, ext)
+        return if meta["name"] == basename
+
+        raise BadFrontmatter.new(path, "name '#{meta["name"]}' does not match basename '#{basename}'")
+      end
+
+      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, content]
+      end
+
+      def self.validate_path_extension(path, _nested)
+        ext = File.extname(path)
+        return if ["", ".md"].include?(ext)
+
+        raise UsageError.new("markdown format requires '.md' path (got #{ext.inspect})")
+      end
     end
   end
 end

data/lib/textus/entry/text.rb

@@ -18,6 +18,41 @@ module Textus
       end
 
       def self.extensions = [".txt"]
+
+      def self.nested_glob = "**/*.txt"
+
+      def self.inject_uid(meta, content, _existing_uid)
+        [meta, content]
+      end
+
+      def self.enforce_name_match!(_path, _meta)
+        # text has no meta home; no-op
+      end
+
+      def self.serialize_for_put(meta:, body:, content:, path:)
+        _ = path
+        _ = content
+        bytes = serialize(meta: meta || {}, body: body.to_s)
+        [bytes, meta, body.to_s, nil]
+      end
+
+      # No-op; text has no meta. Returns false (never writes).
+      def self.rewrite_name(_path, _basename) # rubocop:disable Naming/PredicateMethod
+        false
+      end
+
+      def self.validate_path_extension(path, nested)
+        ext = File.extname(path)
+        if nested
+          return if ext == ""
+
+          raise UsageError.new("nested text path must not have an extension")
+        end
+
+        return if [".txt", ""].include?(ext)
+
+        raise UsageError.new("text format requires '.txt' or no extension (got #{ext.inspect})")
+      end
     end
   end
 end