textus 0.4.0 → 0.8.0

data/lib/textus/envelope.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Textus
+  module Envelope
+    # rubocop:disable Metrics/ParameterLists
+    def self.build(key:, mentry:, path:, meta:, body:, etag:, content: nil)
+      # rubocop:enable Metrics/ParameterLists
+      env = {
+        "protocol" => PROTOCOL,
+        "key" => key,
+        "zone" => mentry.zone,
+        "owner" => mentry.owner,
+        "path" => path,
+        "format" => mentry.format,
+        "_meta" => meta,
+        "body" => body,
+        "etag" => etag,
+        "schema_ref" => mentry.schema,
+        "uid" => extract_uid(meta),
+      }
+      env["content"] = content unless content.nil?
+      env
+    end
+
+    def self.extract_uid(meta)
+      v = meta.is_a?(Hash) ? meta["uid"] : nil
+      v.is_a?(String) ? v : nil
+    end
+  end
+end

data/lib/textus/errors.rb

@@ -51,10 +51,10 @@ module Textus
     private
 
     def default_hint_for(path, m)
-      if m.is_a?(String) && (match = m.match(/frontmatter name '([^']+)' does not match basename '([^']+)'/))
+      if m.is_a?(String) && (match = m.match(/name '([^']+)' does not match basename '([^']+)'/))
         name, basename = match.captures
         ext = File.extname(path)
-        "rename the file to '#{name}#{ext}' or change frontmatter name: to '#{basename}'"
+        "rename the file to '#{name}#{ext}' or change _meta.name to '#{basename}'"
       else
         "open #{path} and check the YAML frontmatter for syntax errors"
       end

data/lib/textus/hooks/builtin.rb

@@ -0,0 +1,70 @@
+require "json"
+require "csv"
+require "yaml"
+require "rexml/document"
+
+module Textus
+  module Hooks
+    module Builtin
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def self.register_all
+        Textus.hook(:fetch, :json) do |store:, config:, args:|
+          _ = store
+          _ = args
+          data = JSON.parse(config["bytes"].to_s)
+          { _meta: {}, body: YAML.dump(data) }
+        end
+
+        Textus.hook(:fetch, :csv) do |store:, config:, args:|
+          _ = store
+          _ = args
+          rows = CSV.parse(config["bytes"].to_s, headers: true).map(&:to_h)
+          { _meta: {}, body: YAML.dump(rows) }
+        end
+
+        Textus.hook(:fetch, :"markdown-links") do |store:, config:, args:|
+          _ = store
+          _ = args
+          links = config["bytes"].to_s.scan(%r{\[([^\]]+)\]\((https?://[^)\s]+)\)}).map do |text, href|
+            { "text" => text, "href" => href }
+          end
+          { _meta: {}, body: YAML.dump(links) }
+        end
+
+        Textus.hook(:fetch, :"ical-events") do |store:, config:, args:|
+          _ = store
+          _ = args
+          events = []
+          current = nil
+          config["bytes"].to_s.each_line do |line|
+            line = line.strip
+            case line
+            when "BEGIN:VEVENT" then current = {}
+            when "END:VEVENT"
+              events << current if current
+              current = nil
+            when /\A(SUMMARY|DTSTART|DTEND|UID|LOCATION|DESCRIPTION):(.*)\z/
+              current[Regexp.last_match(1).downcase] = Regexp.last_match(2) if current
+            end
+          end
+          { _meta: {}, body: YAML.dump(events) }
+        end
+
+        Textus.hook(:fetch, :rss) do |store:, config:, args:|
+          _ = store
+          _ = args
+          doc = REXML::Document.new(config["bytes"].to_s)
+          items = doc.elements.to_a("//item").map do |item|
+            {
+              "title" => item.elements["title"]&.text,
+              "link" => item.elements["link"]&.text,
+              "pubDate" => item.elements["pubDate"]&.text,
+            }
+          end
+          { _meta: {}, body: YAML.dump(items) }
+        end
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+    end
+  end
+end

data/lib/textus/hooks/dispatcher.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module Textus
+  module Hooks
+    class Dispatcher
+      HOOK_TIMEOUT_SECONDS = 2
+
+      def initialize(audit_log:)
+        @audit_log = audit_log
+        @subscribers = Hash.new { |h, k| h[k] = [] }
+      end
+
+      def subscribe(event, name, keys: nil, &block)
+        @subscribers[event.to_sym] << { name: name.to_sym, callable: block, keys: keys }
+      end
+
+      def publish(event, **kwargs)
+        key = kwargs[:key] || "-"
+        @subscribers[event.to_sym].each do |sub|
+          next unless match?(sub[:keys], key)
+
+          invoke(event, sub, key, kwargs)
+        end
+      end
+
+      private
+
+      def invoke(event, sub, key, kwargs)
+        Timeout.timeout(HOOK_TIMEOUT_SECONDS) { sub[:callable].call(**kwargs) }
+      rescue StandardError => e
+        extras = { "event" => event.to_s, "hook" => sub[:name].to_s, "error" => "#{e.class}: #{e.message}" }
+        extras["target_key"]  = kwargs[:target_key]  if kwargs.key?(:target_key)
+        extras["pending_key"] = kwargs[:pending_key] if kwargs.key?(:pending_key)
+        @audit_log.append(
+          role: "script", verb: "event_error", key: key,
+          etag_before: nil, etag_after: nil, extras: extras
+        )
+      end
+
+      def match?(globs, key)
+        return true if globs.nil?
+
+        Array(globs).any? { |g| File.fnmatch?(g, key.to_s, File::FNM_PATHNAME) }
+      end
+    end
+  end
+end

data/lib/textus/hooks/loader.rb

@@ -0,0 +1,26 @@
+module Textus
+  module Hooks
+    module Loader
+      THREAD_REGISTRY_KEY = :__textus_active_registry__
+      private_constant :THREAD_REGISTRY_KEY
+
+      def self.with_registry(registry)
+        prev = Thread.current[THREAD_REGISTRY_KEY]
+        Thread.current[THREAD_REGISTRY_KEY] = registry
+        yield
+      ensure
+        Thread.current[THREAD_REGISTRY_KEY] = prev
+      end
+
+      def self.current_registry
+        Thread.current[THREAD_REGISTRY_KEY] or
+          raise UsageError.new("no active registry; hook code must be loaded by a Store")
+      end
+    end
+  end
+
+  # Public DSL — unchanged surface
+  def self.with_registry(registry, &) = Hooks::Loader.with_registry(registry, &)
+  def self.current_registry           = Hooks::Loader.current_registry
+  def self.hook(event, name, **, &)   = Hooks::Loader.current_registry.register(event, name, **, &)
+end

data/lib/textus/hooks/registry.rb

@@ -0,0 +1,73 @@
+module Textus
+  module Hooks
+    class Registry
+      EVENTS = {
+        # RPC: exactly 1 handler per name; return value flows into store; failure aborts.
+        fetch: { mode: :rpc, args: %i[store config args] },
+        reduce: { mode: :rpc, args: %i[store rows config] },
+        check: { mode: :rpc, args: %i[store] },
+
+        # Pub-sub: 0..N handlers per event; return discarded; failure logged to audit.
+        put: { mode: :pubsub, args: %i[store key envelope] },
+        delete: { mode: :pubsub, args: %i[store key] },
+        refresh: { mode: :pubsub, args: %i[store key envelope change] },
+        build: { mode: :pubsub, args: %i[store key envelope sources] },
+        accept: { mode: :pubsub, args: %i[store key target_key] },
+      }.freeze
+
+      def initialize(dispatcher: nil)
+        @rpc        = Hash.new { |h, k| h[k] = {} }   # event => { name => callable }
+        @pubsub     = Hash.new { |h, k| h[k] = [] }   # event => [{name:, callable:, keys:}]
+        @dispatcher = dispatcher
+      end
+
+      def register(event, name, keys: nil, &blk)
+        spec = EVENTS[event.to_sym] or raise UsageError.new("unknown event: #{event}")
+        shape_check!(event, spec, blk)
+        name = name.to_sym
+
+        case spec[:mode]
+        when :rpc
+          raise UsageError.new("#{event} '#{name}' already registered") if @rpc[event.to_sym].key?(name)
+
+          @rpc[event.to_sym][name] = blk
+        when :pubsub
+          raise UsageError.new("#{event} hook '#{name}' already registered") if @pubsub[event.to_sym].any? { |h| h[:name] == name }
+
+          @pubsub[event.to_sym] << { name: name, callable: blk, keys: keys }
+          @dispatcher&.subscribe(event, name, keys: keys, &blk)
+        end
+      end
+
+      def rpc_callable(event, name)
+        @rpc[event.to_sym][name.to_sym] or
+          raise UsageError.new("unknown #{event}: #{name}")
+      end
+
+      def listeners(event, key:)
+        @pubsub[event.to_sym].select { |h| h[:keys].nil? || matches_any?(h[:keys], key) }
+      end
+
+      def rpc_names(event) = @rpc[event.to_sym].keys
+      def pubsub_handlers(event) = @pubsub[event.to_sym]
+
+      private
+
+      def shape_check!(event, spec, blk)
+        required = spec[:args]
+        provided = blk.parameters.select { |t, _| %i[keyreq key keyrest].include?(t) } # rubocop:disable Style/HashSlice
+        keyrest  = provided.any? { |t, _| t == :keyrest }
+        missing  = required - provided.map { |_, n| n }
+        return if keyrest || missing.empty?
+
+        raise UsageError.new(
+          "#{event} hooks must accept kwargs: #{required.join(", ")} (missing: #{missing.join(", ")})",
+        )
+      end
+
+      def matches_any?(globs, key)
+        Array(globs).any? { |g| File.fnmatch?(g, key.to_s, File::FNM_PATHNAME) }
+      end
+    end
+  end
+end

data/lib/textus/init.rb

@@ -5,7 +5,7 @@ module Textus
     ZONES = %w[canon working intake pending derived].freeze
 
     DEFAULT_MANIFEST = <<~YAML
-      version: textus/1
+      version: textus/2
       zones:
         - { name: canon,   writable_by: [human] }
         - { name: working, writable_by: [human, ai, script] }
@@ -22,27 +22,30 @@ module Textus
 
       FileUtils.mkdir_p(File.join(target_root, "schemas"))
       FileUtils.mkdir_p(File.join(target_root, "templates"))
-      FileUtils.mkdir_p(File.join(target_root, "extensions"))
+      FileUtils.mkdir_p(File.join(target_root, "hooks"))
       ZONES.each do |z|
         dir = File.join(target_root, "zones", z)
         FileUtils.mkdir_p(dir)
         File.write(File.join(dir, ".gitkeep"), "")
       end
-      File.write(File.join(target_root, "extensions", "README.md"), <<~MD)
-        # Extensions
+      File.write(File.join(target_root, "hooks", "README.md"), <<~MD)
+        # Hooks
 
-        Drop one Ruby file per extension. Four verbs are available:
+        Drop one Ruby file per hook. All extensions register through one DSL.
+        Every handler receives `store:` as its first kwarg, then event-specific args.
 
         ```ruby
-        Textus.action(:name)         { |config:, store:, args:| ... }
-        Textus.reducer(:name)        { |rows:, config:|         ... }
-        Textus.hook(:event, :name)   { |key:, envelope:, **kw|  ... }
-        Textus.doctor_check(:name)   { |store:|                 ... }
+        Textus.hook(:fetch,  :name) { |store:, config:, args:|  ... }   # bring bytes in
+        Textus.hook(:reduce, :name) { |store:, rows:, config:|  ... }   # transform rows
+        Textus.hook(:check,  :name) { |store:|                  ... }   # doctor check
+        Textus.hook(:put,    :name, keys: ["..."])                      # lifecycle listener
+                                    { |store:, key:, envelope:| ... }
         ```
 
-        Events: :put, :delete, :refresh, :build, :accept.
+        Events: :fetch, :reduce, :check (rpc — return value used)
+                :put, :delete, :refresh, :build, :accept (pub-sub — return discarded)
 
-        See SPEC.md §5.11 for the full contract.
+        See SPEC.md §5.10 for the full table.
       MD
 
       File.write(File.join(target_root, "manifest.yaml"), DEFAULT_MANIFEST)

data/lib/textus/intro.rb

@@ -6,7 +6,7 @@ module Textus
   #
   # Intro is side-effect-free.
   module Intro
-    PROTOCOL_ID = "textus/1".freeze
+    PROTOCOL_ID = PROTOCOL
 
     # Conventional zone purposes. Unknown zones (declared in the manifest
     # but not listed here) get no `purpose` field.
@@ -32,19 +32,19 @@ module Textus
     CLI_VERBS = [
       { "name" => "intro",    "summary" => "this output — orientation for agents and tools" },
       { "name" => "list",     "summary" => "enumerate keys (optional --prefix)" },
-      { "name" => "get",      "summary" => "read an entry; envelope with frontmatter, body, uid, etag" },
+      { "name" => "get",      "summary" => "read an entry; envelope with _meta, body, uid, etag" },
       { "name" => "where",    "summary" => "resolve a key to its zone and path without reading" },
       { "name" => "schema",   "summary" => "field shape for a key family" },
       { "name" => "put",      "summary" => "write an entry; --as=<role>, --stdin payload" },
       { "name" => "accept",   "summary" => "apply a pending.* proposal; --as=human only" },
-      { "name" => "mv",       "summary" => "rename a key in place; uid preserved, audit row written" },
+      { "name" => "key",      "summary" => "key operations: 'key mv', 'key uid', 'key migrate'" },
       { "name" => "delete",   "summary" => "delete an entry; --as=<role>" },
       { "name" => "build",    "summary" => "materialize derived entries; publish_to and publish_each fan out copies" },
       { "name" => "refresh",  "summary" => "run an action for an intake entry" },
       { "name" => "stale",    "summary" => "list derived/intake entries past their freshness check" },
       { "name" => "doctor",   "summary" => "health-check the store (missing schemas, illegal keys, sentinel drift, etc.)" },
-      { "name" => "migrate-keys", "summary" => "rename files whose basenames violate the strict key grammar" },
-      { "name" => "extensions", "summary" => "list registered actions, reducers, doctor_checks, declared hooks" },
+      { "name" => "hook",
+        "summary" => "list and run registered hooks: 'hook list', 'hook run NAME'" },
     ].freeze
 
     def self.run(store)
@@ -80,7 +80,7 @@ module Textus
           "owner" => e.owner,
           "format" => e.format,
           "derived" => derived,
-          "intake" => !e.action.nil?,
+          "intake" => !e.fetch.nil?,
           "publish_to" => Array(e.publish_to),
           "publish_each" => e.publish_each,
         }
@@ -89,18 +89,16 @@ module Textus
 
     def self.extensions_for(store)
       reg = store.registry
-      reducers = reg.reducer_names.map(&:to_s).sort
-      actions = reg.action_names.map(&:to_s).sort
-      doctor_checks = reg.doctor_check_names.map(&:to_s).sort
-      hooks = reg.hook_events.flat_map do |evt|
-        reg.hooks(evt).map { |h| { "event" => evt.to_s, "name" => h[:name].to_s } }
-      end.sort_by { |h| [h["event"], h["name"]] }
-      {
-        "reducers" => reducers,
-        "actions" => actions,
-        "doctor_checks" => doctor_checks,
-        "hooks" => hooks,
-      }
+      sections = {}
+      Hooks::Registry::EVENTS.each do |event, spec|
+        case spec[:mode]
+        when :rpc
+          sections[event.to_s] = reg.rpc_names(event).map(&:to_s).sort
+        when :pubsub
+          sections[event.to_s] = reg.pubsub_handlers(event).map { |h| h[:name].to_s }.sort
+        end
+      end
+      sections
     end
   end
 end

data/lib/textus/key/distance.rb

@@ -0,0 +1,55 @@
+module Textus
+  module Key
+    # Small utilities for ranking key suggestions. Bounded inputs only —
+    # Levenshtein is O(n*m) so we refuse to compute on long strings.
+    class Distance
+      MAX_LEN = 200
+
+      # Length of the shared dot-separated prefix between two dotted keys.
+      def self.shared_prefix_segments(left, right)
+        asegs = left.split(".")
+        bsegs = right.split(".")
+        n = [asegs.length, bsegs.length].min
+        i = 0
+        i += 1 while i < n && asegs[i] == bsegs[i]
+        i
+      end
+
+      # Classic iterative Levenshtein with two rows. Bounded to MAX_LEN.
+      def self.levenshtein(left, right)
+        return nil if left.length > MAX_LEN || right.length > MAX_LEN
+        return right.length if left.empty?
+        return left.length if right.empty?
+
+        prev = (0..right.length).to_a
+        curr = Array.new(right.length + 1, 0)
+        (1..left.length).each do |i|
+          curr[0] = i
+          (1..right.length).each do |j|
+            cost = left[i - 1] == right[j - 1] ? 0 : 1
+            curr[j] = [
+              curr[j - 1] + 1,      # insertion
+              prev[j] + 1,          # deletion
+              prev[j - 1] + cost,   # substitution
+            ].min
+          end
+          prev, curr = curr, prev
+        end
+        prev[right.length]
+      end
+
+      # Rank candidate keys against requested. Returns up to `limit` keys.
+      # Sort: longer shared prefix first; then smaller Levenshtein distance.
+      def self.suggest(requested, candidates, limit: 5)
+        return [] if requested.nil? || requested.empty?
+
+        scored = candidates.first(200).map do |k|
+          prefix = shared_prefix_segments(requested, k)
+          dist = levenshtein(requested, k) || Float::INFINITY
+          [k, prefix, dist]
+        end
+        scored.sort_by { |(_, prefix, dist)| [-prefix, dist] }.first(limit).map(&:first)
+      end
+    end
+  end
+end

data/lib/textus/key/grammar.rb

@@ -0,0 +1,33 @@
+module Textus
+  module Key
+    module Grammar
+      SEGMENT = /\A[a-z0-9][a-z0-9-]*\z/
+      MAX_SEGMENTS = 8
+      MAX_SEGMENT_LEN = 64
+
+      module_function
+
+      def validate!(key) # rubocop:disable Naming/PredicateMethod
+        raise UsageError.new("key must be a String") unless key.is_a?(String)
+        raise UsageError.new("empty key") if key.empty?
+
+        segs = key.split(".")
+        raise UsageError.new("key '#{key}' has #{segs.length} segments (max #{MAX_SEGMENTS})") if segs.length > MAX_SEGMENTS
+
+        segs.each do |seg|
+          if seg.empty?
+            raise UsageError.new("empty segment in key '#{key}'")
+          elsif seg.length > MAX_SEGMENT_LEN
+            raise UsageError.new("segment '#{seg}' in key '#{key}' exceeds #{MAX_SEGMENT_LEN} chars")
+          elsif !seg.match?(SEGMENT)
+            raise UsageError.new(
+              "invalid key segment '#{seg}' in '#{key}': must match [a-z0-9][a-z0-9-]* " \
+              "(lowercase, digits, hyphens; no underscores or uppercase)",
+            )
+          end
+        end
+        true
+      end
+    end
+  end
+end

data/lib/textus/key/path.rb

@@ -0,0 +1,17 @@
+module Textus
+  module Key
+    module Path
+      # Returns the absolute filesystem path for a manifest entry (the leaf file,
+      # not a nested directory). Adds the format's primary extension when the
+      # manifest entry's `path:` is extensionless.
+      def self.resolve(manifest, mentry)
+        primary_ext = Entry.for_format(mentry.format).extensions.first
+        if File.extname(mentry.path) == ""
+          File.join(manifest.root, "zones", mentry.path + primary_ext)
+        else
+          File.join(manifest.root, "zones", mentry.path)
+        end
+      end
+    end
+  end
+end