textus 0.14.0 → 0.14.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24eda2a2cfec1884eb3c675189493827b6c0f43d5765922dbee06b70fbdc9685
-  data.tar.gz: 84e3850666541900f4c3b99f71c59b73dd142c7001f80fa9e8233d38f984719e
+  metadata.gz: 4a732844e2441328f7519ffd93571c3ff611fd0514c2b1f927b5c4ada499db16
+  data.tar.gz: 63a3e530439c37fbbff8c8b3864b1489cd34c88c88bd1c10f03ae980f4a66041
 SHA512:
-  metadata.gz: d68ad56bc7891aefda10e47234f1bbd1efbfd75b576f7981c3374641efbd306dc66947b382b74c70da24bc58122090c3e0789c33b1a8291aa1005b9e6c952e2e
-  data.tar.gz: fd1c1cefad648636b4fb5aeba100d81c66472f8e1b50d07ba2239607c19179842902abf0b76925786c66868049acfd507a9a76bd07e39026dd2aa0d261ebfdad
+  metadata.gz: 5470a6aaf29f1b081144b2eca3b1e87e5b1d465977422c967366196d259041cdbb8e0993ce293d87d7903f9446649f80ea99e1e6367b9731f7b839bf18f9d67f
+  data.tar.gz: dcd3f57064d2f6753f049daf1315a937566e3b77a9ec130455a54410292f73ec55104bafe1e1b20431dc186a1c13735a7e6c6018ef8f54b77122f0eb2e267e8c

data/CHANGELOG.md

@@ -9,6 +9,48 @@ The **gem version** (`0.x.y`) is distinct from the **protocol version**
 bump is a breaking change that requires a store migration; the gem version
 tracks both additive improvements and breaking protocol bumps independently.
 
+## 0.14.2 — 2026-05-26
+
+### Added
+
+- Per-rule `fetch_timeout_seconds:` under `rules[].refresh` overrides the
+  hardcoded 30s worker timeout that applies to intake handlers invoked
+  via the refresh pipeline (`textus refresh <key>`, `textus refresh
+  stale`, and read-path `on_stale: sync` / `timed_sync`). Default stays
+  at 30s — opt-in only. Schema validates a positive integer ≤ 3600.
+  Mirrors `sync_budget_ms` plumbing: schema → rules → policy → worker
+  (#54).
+
+### Notes
+
+- `fetch_timeout_seconds` is the worker-side hard cap on the intake
+  call; `sync_budget_ms` is the caller-side wait budget for `timed_sync`
+  on the read path. Two separate concerns, two separate keys.
+- The CLI verbs `textus put --fetch` and `textus hook run` still use the
+  30s constant — only the refresh worker honors the per-rule override in
+  this release.
+- Long timeouts pair with `Timeout.timeout`, which raises in the Ruby
+  thread but does not kill spawned subprocesses. Intake handlers that
+  shell out (e.g. `git clone`) should write to a temp dir and atomically
+  rename so mid-flight aborts leave no observable partial state.
+
+## 0.14.1 — 2026-05-26
+
+### Changed
+
+- Build pipeline now skips rewriting a built artifact when the only
+  difference from the existing file on disk would be the freshly-stamped
+  `generated_at` (markdown: `generated.at`) timestamp. Stores under git
+  versioning no longer churn on every `textus build` (#52).
+- Strict policy: any other byte difference — changed `from`,
+  `template`, `reduce`, body content — still triggers a write. Text
+  format falls back to plain byte-equality (no timestamp to normalize).
+
+### Internal
+
+- Extracted `Manifest.check_version!` to dedupe the parse/load version
+  guard (#51).
+
 ## 0.14.0 — 2026-05-26
 
 ### Breaking (Ruby API only — CLI JSON output unchanged)

data/lib/textus/application/refresh/worker.rb

@@ -26,6 +26,11 @@ module Textus
           Application::Context.new(store: @ctx.store, role: @ctx.role)
         end
 
+        def fetch_timeout_for(key)
+          rule = @ctx.store.manifest.rules_for(key)
+          rule&.refresh&.fetch_timeout_seconds || FETCH_TIMEOUT_SECONDS
+        end
+
         def fetch_with_bus(key, mentry)
           callable = @ctx.store.registry.rpc_callable(:resolve_intake, mentry.intake_handler)
           @bus.publish(:refresh_started, store: read_view, key: key, mode: :sync,
@@ -34,14 +39,15 @@ module Textus
         end
 
         def call_intake(key, mentry, callable)
-          Timeout.timeout(FETCH_TIMEOUT_SECONDS) do
+          timeout = fetch_timeout_for(key)
+          Timeout.timeout(timeout) do
             callable.call(store: @ctx, config: mentry.intake_config, args: {})
           end
         rescue Timeout::Error
           @bus.publish(:refresh_failed, store: read_view, key: key, error_class: "Timeout::Error",
-                                        error_message: "intake '#{mentry.intake_handler}' exceeded #{FETCH_TIMEOUT_SECONDS}s",
+                                        error_message: "intake '#{mentry.intake_handler}' exceeded #{timeout}s",
                                         correlation_id: @ctx.correlation_id)
-          raise UsageError.new("intake '#{mentry.intake_handler}' exceeded #{FETCH_TIMEOUT_SECONDS}s timeout")
+          raise UsageError.new("intake '#{mentry.intake_handler}' exceeded #{timeout}s timeout")
         rescue Textus::Error => e
           @bus.publish(:refresh_failed, store: read_view, key: key, error_class: e.class.name,
                                         error_message: e.message, correlation_id: @ctx.correlation_id)

data/lib/textus/builder/pipeline.rb

@@ -19,6 +19,35 @@ module Textus
       end
     end
 
+    # Replaces the freshly-stamped timestamp inside `new_bytes` with the
+    # timestamp pulled from `old_bytes` (same format). Returns the rewritten
+    # bytes, or nil if either side lacks a parseable timestamp.
+    module IdempotentWrite
+      def self.rewrite_with_prior_timestamp(new_bytes:, old_bytes:, format:)
+        prior = extract_timestamp(old_bytes, format)
+        fresh = extract_timestamp(new_bytes, format)
+        return nil unless prior && fresh
+        return new_bytes if prior == fresh
+
+        new_bytes.sub(fresh, prior)
+      end
+
+      def self.extract_timestamp(bytes, format)
+        case format
+        when "markdown"
+          parsed = Entry.for_format("markdown").parse(bytes)
+          parsed.dig("_meta", "generated", "at")
+        when "json", "yaml"
+          parsed = Entry.for_format(format).parse(bytes)
+          parsed.dig("_meta", "generated_at")
+        else # rubocop:disable Style/EmptyElse
+          nil
+        end
+      rescue Textus::BadFrontmatter
+        nil
+      end
+    end
+
     module Pipeline
       def self.renderers
         @renderers ||= {
@@ -44,13 +73,28 @@ module Textus
           raise UsageError.new("builder: unsupported format #{mentry.format.inspect} for '#{mentry.key}'")
         bytes = klass.new(template_loader: template_loader).call(mentry: mentry, data: data)
 
-        # 3. Write
+        # 3. Write (idempotent: skip if only generated_at would differ)
         target_path = Key::Path.resolve(store.manifest, mentry)
         FileUtils.mkdir_p(File.dirname(target_path))
-        File.binwrite(target_path, bytes)
+        write_if_changed(target_path, bytes, mentry.format)
 
         target_path
       end
+
+      def self.write_if_changed(target_path, bytes, format)
+        if File.exist?(target_path)
+          old_bytes = File.binread(target_path)
+          if format == "text"
+            return if old_bytes == bytes
+          else
+            rewritten = IdempotentWrite.rewrite_with_prior_timestamp(
+              new_bytes: bytes, old_bytes: old_bytes, format: format,
+            )
+            return if rewritten && rewritten == old_bytes
+          end
+        end
+        File.binwrite(target_path, bytes)
+      end
     end
   end
 end

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

@@ -10,6 +10,7 @@ module Textus
                 "ttl_seconds" => b.refresh.ttl_seconds,
                 "on_stale" => b.refresh.on_stale,
                 "sync_budget_ms" => b.refresh.sync_budget_ms,
+                "fetch_timeout_seconds" => b.refresh.fetch_timeout_seconds,
               }
             end
             row["handler_allowlist"] = b.handler_allowlist.handlers if b.handler_allowlist

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

@@ -2,9 +2,9 @@ module Textus
   module Domain
     module Policy
       class Refresh
-        attr_reader :ttl, :on_stale, :sync_budget_ms
+        attr_reader :ttl, :on_stale, :sync_budget_ms, :fetch_timeout_seconds
 
-        def initialize(ttl:, on_stale:, sync_budget_ms:)
+        def initialize(ttl:, on_stale:, sync_budget_ms:, fetch_timeout_seconds: nil)
           on_stale_sym = on_stale.is_a?(Symbol) ? on_stale : on_stale.to_s.to_sym
           unless ALLOWED_ON_STALE.include?(on_stale_sym)
             raise Textus::UsageError.new(
@@ -12,9 +12,10 @@ module Textus
             )
           end
 
-          @ttl            = ttl
-          @on_stale       = on_stale_sym
-          @sync_budget_ms = sync_budget_ms
+          @ttl                   = ttl
+          @on_stale              = on_stale_sym
+          @sync_budget_ms        = sync_budget_ms
+          @fetch_timeout_seconds = fetch_timeout_seconds
         end
 
         def ttl_seconds

data/lib/textus/manifest/rules.rb

@@ -63,6 +63,7 @@ module Textus
             ttl: h["ttl"],
             on_stale: h["on_stale"] || "warn",
             sync_budget_ms: h["sync_budget_ms"],
+            fetch_timeout_seconds: h["fetch_timeout_seconds"],
           )
         end
 

data/lib/textus/manifest/schema.rb

@@ -11,7 +11,8 @@ module Textus
       COMPUTE_KEYS = %w[kind select pluck sort_by limit transform command sources].freeze
       INTAKE_KEYS  = %w[handler config].freeze
       RULE_KEYS    = %w[match refresh intake_handler_allowlist promotion retention].freeze
-      REFRESH_KEYS = %w[ttl on_stale sync_budget_ms].freeze
+      REFRESH_KEYS = %w[ttl on_stale sync_budget_ms fetch_timeout_seconds].freeze
+      FETCH_TIMEOUT_SECONDS_CEILING = 3600
       PROMOTION_KEYS = %w[requires].freeze
 
       def self.validate!(raw)
@@ -30,11 +31,23 @@ module Textus
         Array(raw["rules"]).each_with_index do |r, i|
           path = "$.rules[#{i}]"
           walk(r, RULE_KEYS, path)
-          walk(r["refresh"], REFRESH_KEYS, "#{path}.refresh") if r["refresh"].is_a?(Hash)
+          if r["refresh"].is_a?(Hash)
+            walk(r["refresh"], REFRESH_KEYS, "#{path}.refresh")
+            validate_fetch_timeout!(r["refresh"]["fetch_timeout_seconds"], "#{path}.refresh.fetch_timeout_seconds")
+          end
           walk(r["promotion"], PROMOTION_KEYS, "#{path}.promotion") if r["promotion"].is_a?(Hash)
         end
       end
 
+      def self.validate_fetch_timeout!(value, path)
+        return if value.nil?
+        return if value.is_a?(Integer) && value.positive? && value <= FETCH_TIMEOUT_SECONDS_CEILING
+
+        raise BadManifest.new(
+          "fetch_timeout_seconds at '#{path}' must be a positive integer ≤ #{FETCH_TIMEOUT_SECONDS_CEILING} (got #{value.inspect})",
+        )
+      end
+
       def self.walk(hash, allowed, path)
         return unless hash.is_a?(Hash)
 

data/lib/textus/manifest.rb

@@ -39,14 +39,7 @@ module Textus
 
     def self.parse(yaml_text, root: ".")
       raw = YAML.safe_load(yaml_text, aliases: false)
-      unless raw["version"] == PROTOCOL
-        raise BadFrontmatter.new(
-          "<string>",
-          "unsupported manifest version #{raw["version"].inspect}; expected #{PROTOCOL.inspect}",
-          hint: version_hint_for(raw["version"]),
-        )
-      end
-
+      check_version!(raw, "<string>")
       new(root, raw)
     end
 
@@ -55,17 +48,21 @@ module Textus
       raise IoError.new("manifest not found: #{manifest_path}") unless File.exist?(manifest_path)
 
       raw = YAML.safe_load_file(manifest_path, aliases: false)
-      unless raw["version"] == PROTOCOL
-        raise BadFrontmatter.new(
-          manifest_path,
-          "unsupported manifest version #{raw["version"].inspect}; expected #{PROTOCOL.inspect}",
-          hint: version_hint_for(raw["version"]),
-        )
-      end
-
+      check_version!(raw, manifest_path)
       new(root, raw)
     end
 
+    def self.check_version!(raw, source)
+      return if raw["version"] == PROTOCOL
+
+      raise BadFrontmatter.new(
+        source,
+        "unsupported manifest version #{raw["version"].inspect}; expected #{PROTOCOL.inspect}",
+        hint: version_hint_for(raw["version"]),
+      )
+    end
+    private_class_method :check_version!
+
     def initialize(root, raw)
       @root = root
       @raw = raw

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.14.0"
+  VERSION = "0.14.2"
   PROTOCOL = "textus/3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.14.2
 platform: ruby
 authors:
 - Patrick