textus 0.12.1 → 0.14.0

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

@@ -4,7 +4,7 @@ module Textus
       class Uid < Verb
         def call(store)
           key = positional.shift or raise UsageError.new("uid requires a key")
-          emit({ "key" => key, "uid" => store.uid(key) })
+          emit({ "key" => key, "uid" => operations_for(store).reads.uid.call(key) })
         end
       end
     end

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

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

data/lib/textus/cli/verb.rb

@@ -70,7 +70,12 @@ module Textus
       # Convenience for verbs whose only pre-call boilerplate is
       # resolving the role and wrapping it in a context.
       def context_for(store)
-        Textus::Composition.context(store, role: resolved_role(store))
+        Textus::Operations.for(store, role: resolved_role(store)).ctx
+      end
+
+      # Returns an Operations instance bound to the resolved role.
+      def operations_for(store)
+        Textus::Operations.for(store, role: resolved_role(store))
       end
     end
   end

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

@@ -53,7 +53,7 @@ module Textus
 
     def run_registered_checks(store)
       out = []
-      view = Application::Context.new(store: store, role: "human")
+      view = Application::Context.system(store)
       store.registry.rpc_names(:validate).each do |name|
         callable = store.registry.rpc_callable(:validate, name)
         begin

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/policy/predicates/schema_valid.rb

@@ -9,10 +9,10 @@ module Textus
             "schema_valid"
           end
 
-          def call(entry:, store:)
+          def call(entry:, store:) # rubocop:disable Metrics/PerceivedComplexity
             return true if entry.nil? || store.nil?
 
-            target_key = entry.dig("_meta", "proposal", "target_key")
+            target_key = entry.meta&.dig("proposal", "target_key")
             return true unless target_key
 
             mentry, = store.manifest.resolve(target_key)
@@ -22,7 +22,7 @@ module Textus
             schema = store.schema_for(schema_ref)
             return true unless schema
 
-            frontmatter = entry.dig("_meta", "frontmatter") || {}
+            frontmatter = entry.meta&.dig("frontmatter") || {}
             begin
               schema.validate!(frontmatter)
             rescue Textus::SchemaViolation => e

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

data/lib/textus/entry/yaml.rb

@@ -40,6 +40,65 @@ module Textus
       end
 
       def self.extensions = [".yaml", ".yml"]
+
+      def self.nested_glob = "**/*.{yaml,yml}"
+
+      def self.serialize_for_put(meta:, body:, content:, path:)
+        raise UsageError.new("put for yaml 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 yaml path must not have an extension")
+        end
+
+        return if [".yaml", ".yml"].include?(ext)
+
+        raise UsageError.new("yaml format requires '.yaml' or '.yml' path (got #{ext.inspect})")
+      end
     end
   end
 end

data/lib/textus/entry.rb

@@ -10,10 +10,26 @@ module Textus
       "text" => Text,
     }.freeze
 
+    EXT_TO_FORMAT = {
+      ".md" => "markdown",
+      ".json" => "json",
+      ".yaml" => "yaml",
+      ".yml" => "yaml",
+      ".txt" => "text",
+    }.freeze
+
     def self.for_format(format)
       STRATEGIES.fetch(format.to_s) { raise UsageError.new("unknown entry format: #{format.inspect}") }
     end
 
+    def self.infer_from_extension(ext)
+      EXT_TO_FORMAT[ext]
+    end
+
+    def self.formats
+      EXT_TO_FORMAT.values.uniq
+    end
+
     def self.parse(raw, path: nil, format: "markdown")
       for_format(format).parse(raw, path: path)
     end

data/lib/textus/envelope.rb

@@ -1,30 +1,60 @@
 # frozen_string_literal: true
 
 module Textus
-  module Envelope
+  Envelope = Data.define(
+    :protocol, :key, :zone, :owner, :path, :format,
+    :uid, :etag, :schema_ref, :meta, :body, :content, :freshness
+  ) do
     # rubocop:disable Metrics/ParameterLists
-    def self.build(key:, mentry:, path:, meta:, body:, etag:, content: nil)
+    def self.build(key:, mentry:, path:, meta:, body:, etag:, content: nil, freshness: nil)
       # rubocop:enable Metrics/ParameterLists
-      env = {
-        "protocol" => PROTOCOL,
+      new(
+        protocol: Textus::PROTOCOL,
+        key: key,
+        zone: mentry.zone,
+        owner: mentry.owner,
+        path: path,
+        format: mentry.format,
+        uid: extract_uid(meta),
+        etag: etag,
+        schema_ref: mentry.schema,
+        meta: meta,
+        body: body,
+        content: content,
+        freshness: freshness,
+      )
+    end
+
+    def self.extract_uid(meta)
+      v = meta.is_a?(Hash) ? meta["uid"] : nil
+      v.is_a?(String) ? v : nil
+    end
+
+    def to_h_for_wire
+      h = {
+        "protocol" => protocol,
         "key" => key,
-        "zone" => mentry.zone,
-        "owner" => mentry.owner,
+        "zone" => zone,
+        "owner" => owner,
         "path" => path,
-        "format" => mentry.format,
+        "format" => format,
         "_meta" => meta,
         "body" => body,
         "etag" => etag,
-        "schema_ref" => mentry.schema,
-        "uid" => extract_uid(meta),
+        "schema_ref" => schema_ref,
+        "uid" => uid,
       }
-      env["content"] = content unless content.nil?
-      env
+      h["content"] = content unless content.nil?
+      freshness.each { |k, v| h[k.to_s] = v } if freshness.is_a?(Hash)
+      h
     end
 
-    def self.extract_uid(meta)
-      v = meta.is_a?(Hash) ? meta["uid"] : nil
-      v.is_a?(String) ? v : nil
+    def stale?
+      freshness.is_a?(Hash) && (freshness["stale"] == true || freshness[:stale] == true)
+    end
+
+    def refreshing?
+      freshness.is_a?(Hash) && (freshness["refreshing"] == true || freshness[:refreshing] == true)
     end
   end
 end

data/lib/textus/intro.rb

@@ -26,6 +26,61 @@ module Textus
       "builder" => "'textus build' computes output entries from projections; output files are never hand-edited",
     }.freeze
 
+    # Static, store-independent guide to the agent-facing protocol. Surfaced
+    # under the new top-level `agent_protocol` key in Intro.run. Recipes
+    # describe CLI verbs (not Ruby Operations) because the audience is an
+    # agent driving textus from the command line.
+    AGENT_PROTOCOL = {
+      "envelope_shape" => {
+        "summary" => "every read/write payload is a JSON envelope with _meta, body, uid, and etag",
+        "fields" => {
+          "_meta" => "hash of structured frontmatter; schema-validated per entry family",
+          "body" => "string payload (markdown/text) or nil for json/yaml formats where body lives in _meta",
+          "uid" => "stable 16-char hex identifier; preserved across writes and key renames",
+          "etag" => "content hash; pass back on writes to detect concurrent edits",
+        },
+        "ref" => "SPEC.md §8",
+      },
+      "role_resolution" => {
+        "summary" => "write role is resolved in order: --as flag, TEXTUS_ROLE env var, .textus/role file, default human",
+        "roles" => %w[human agent runner builder],
+        "ref" => "SPEC.md §5",
+      },
+      "recipes" => {
+        "read" => {
+          "purpose" => "find and read an entry",
+          "steps" => [
+            "textus list --zone=ZONE --prefix=PREFIX  # discover keys",
+            "textus get KEY                            # returns envelope JSON",
+          ],
+        },
+        "write" => {
+          "purpose" => "create or update an entry",
+          "steps" => [
+            "textus schema get FAMILY                  # learn the _meta field shape",
+            "build an envelope JSON: {_meta: {...}, body: \"...\"}",
+            "echo ENVELOPE | textus put KEY --as=ROLE --stdin",
+          ],
+        },
+        "propose" => {
+          "purpose" => "agent suggests a change for human review",
+          "agent_steps" => [
+            "echo ENVELOPE | textus put review.KEY --as=agent --stdin",
+          ],
+          "human_steps" => [
+            "textus accept review.KEY --as=human       # promotes the proposal to its target zone",
+          ],
+        },
+        "refresh" => {
+          "purpose" => "rebuild stale intake-zone caches from their declared actions",
+          "steps" => [
+            "textus freshness --zone=intake            # report fresh/stale per entry",
+            "textus refresh stale --zone=intake --as=runner",
+          ],
+        },
+      },
+    }.freeze
+
     # The CLI verb catalog. Truth lives here; do not derive dynamically.
     # Agents that read intro should see a stable shape regardless of how
     # verb implementations evolve.
@@ -59,6 +114,7 @@ module Textus
         "hooks" => hooks_for(store),
         "write_flows" => WRITE_FLOWS.dup,
         "cli_verbs" => CLI_VERBS.map(&:dup),
+        "agent_protocol" => AGENT_PROTOCOL,
         "docs" => { "spec" => "SPEC.md", "example" => "examples/claude-plugin/" },
       }
     end

data/lib/textus/manifest/entry/parser.rb

@@ -0,0 +1,84 @@
+module Textus
+  class Manifest
+    class Entry
+      module Parser
+        COMPUTE_KINDS = %w[projection external].freeze
+
+        def self.call(manifest, raw)
+          key = raw["key"] or raise UsageError.new("manifest entry missing key")
+          path = raw["path"] or raise UsageError.new("manifest entry '#{key}' missing path")
+          zone = raw["zone"] or raise UsageError.new("manifest entry '#{key}' missing zone")
+
+          nested = raw["nested"] == true
+          compute, projection, generator = parse_compute(raw, key)
+          intake_handler, intake_config = parse_intake(raw["intake"])
+          format = resolve_format(raw, path, nested)
+
+          Textus::Manifest::Entry.new(
+            manifest: manifest, raw: raw,
+            key: key, path: path, zone: zone,
+            schema: raw["schema"], owner: raw["owner"],
+            nested: nested,
+            template: raw["template"],
+            publish_to: Array(raw["publish_to"]),
+            publish_each: raw["publish_each"],
+            events: raw["events"] || {},
+            inject_intro: raw["inject_intro"] == true,
+            index_filename: raw["index_filename"],
+            format: format,
+            compute: compute, projection: projection, generator: generator,
+            intake_handler: intake_handler, intake_config: intake_config
+          )
+        end
+
+        def self.parse_compute(raw, key)
+          src = raw["compute"]
+          return [nil, nil, nil] if src.nil?
+
+          kind = src["kind"]
+          unless COMPUTE_KINDS.include?(kind)
+            raise BadManifest.new(
+              "entry '#{key}': compute.kind must be one of #{COMPUTE_KINDS.join(", ")} (got #{kind.inspect})",
+            )
+          end
+
+          frozen = src.freeze
+          if kind == "projection"
+            [frozen, frozen, nil]
+          else
+            [frozen, nil, frozen]
+          end
+        end
+
+        def self.parse_intake(src)
+          src ||= {}
+          [src["handler"], src["config"] || {}]
+        end
+
+        def self.resolve_format(raw, path, nested)
+          declared = raw["format"]
+          ext = File.extname(path)
+          inferred = Textus::Entry.infer_from_extension(ext)
+
+          if declared.nil?
+            return inferred if inferred
+            return "markdown" if ext == "" && nested
+            return "markdown" if ext == ""
+
+            return "markdown"
+          end
+
+          raise UsageError.new("entry '#{raw["key"]}': unknown format #{declared.inspect}") unless Textus::Entry.formats.include?(declared)
+
+          if ext != "" && inferred && inferred != declared
+            raise UsageError.new(
+              "entry '#{raw["key"]}': path extension #{ext.inspect} does not match declared format #{declared.inspect}",
+            )
+          end
+
+          declared
+        end
+      end
+    end
+  end
+end

data/lib/textus/manifest/entry/validators/events.rb

@@ -0,0 +1,21 @@
+module Textus
+  class Manifest
+    class Entry
+      module Validators
+        module Events
+          def self.call(entry)
+            pubsub_events = Textus::Hooks::Registry::EVENTS.select { |_, s| s[:mode] == :pubsub }.keys
+            entry.events.each_key do |evt|
+              next if pubsub_events.include?(evt.to_sym)
+
+              raise UsageError.new(
+                "entry '#{entry.key}': unknown event '#{evt}' in events: block. " \
+                "Known events: #{pubsub_events.join(", ")}.",
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/manifest/entry/validators/format_matrix.rb

@@ -0,0 +1,26 @@
+module Textus
+  class Manifest
+    class Entry
+      module Validators
+        module FormatMatrix
+          def self.call(entry)
+            begin
+              Textus::Entry.for_format(entry.format).validate_path_extension(entry.path, entry.nested)
+            rescue UsageError => e
+              raise UsageError.new("entry '#{entry.key}': #{e.message}")
+            end
+
+            if entry.format == "text" && !entry.schema.nil?
+              raise UsageError.new("entry '#{entry.key}': text format must not declare a schema")
+            end
+
+            return unless entry.in_generator_zone? && entry.template.nil? && entry.generator.nil? &&
+                          %w[markdown text].include?(entry.format) && !entry.nested
+
+            raise UsageError.new("entry '#{entry.key}': derived #{entry.format} entries require a template")
+          end
+        end
+      end
+    end
+  end
+end