woods 1.5.0 → 1.6.0

data/lib/woods/retrieval/ranker.rb

@@ -256,7 +256,7 @@ module Woods
         return 0.5 unless unit
         return 0.5 unless classification.target_type
 
-        unit_type = dig_metadata(unit, :type) || unit[:type]
+        unit_type = dig_metadata(unit, :type)
         unit_type&.to_sym == classification.target_type ? 1.0 : 0.3
       end
 
@@ -297,19 +297,57 @@ module Woods
         penalty
       end
 
-      # Dig into unit metadata, handling both hash and object access.
+      # Dig a value out of a unit's metadata, tolerating both symbol and
+      # string keys at every level.
+      #
+      # Units come from the metadata store, which returns STRING keys on
+      # every real backend (SQLite round-trips through JSON.parse;
+      # InMemory#store calls stringify_keys). The previous implementation
+      # probed only symbol keys, so recency/importance/type_match/diversity
+      # silently scored every unit at their neutral fallback in production —
+      # the specs passed only because they stub symbol-keyed units.
+      #
+      # Looks under the `metadata` wrapper first, then falls back to a
+      # top-level field for single-key lookups (namespace/type live on the
+      # unit itself, not under metadata).
       #
       # @param unit [Hash, Object] Unit data
-      # @param keys [Array<Symbol>] Key path
+      # @param keys [Array<Symbol>] Key path within metadata
       # @return [Object, nil]
       def dig_metadata(unit, *keys)
-        if keys.size == 1
-          unit.is_a?(Hash) ? (unit.dig(:metadata, keys[0]) || unit[keys[0]]) : nil
-        else
-          unit.is_a?(Hash) ? unit.dig(:metadata, *keys) : nil
+        return nil unless unit.is_a?(Hash)
+
+        nested = dig_either(fetch_either(unit, :metadata), keys)
+        return nested unless nested.nil?
+
+        keys.size == 1 ? fetch_either(unit, keys.first) : nil
+      end
+
+      # Walk a key path through nested hashes, trying both key forms.
+      #
+      # @param hash [Object] Starting hash (nil-safe)
+      # @param keys [Array<Symbol>] Key path
+      # @return [Object, nil]
+      def dig_either(hash, keys)
+        keys.reduce(hash) do |acc, key|
+          break nil unless acc.is_a?(Hash)
+
+          fetch_either(acc, key)
         end
       end
 
+      # Fetch a key trying its symbol form, then its string form.
+      #
+      # @param hash [Object] Hash to read (nil-safe)
+      # @param key [Symbol, String] Key to fetch
+      # @return [Object, nil]
+      def fetch_either(hash, key)
+        return nil unless hash.is_a?(Hash)
+
+        value = hash[key]
+        value.nil? ? hash[key.to_s] : value
+      end
+
       # Build a Candidate struct compatible with SearchExecutor::Candidate.
       #
       # @return [Candidate-like Struct]

data/lib/woods/retry_after.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'time' # Time.httpdate
+
+module Woods
+  # Parse an HTTP +Retry-After+ header into a number of seconds to wait.
+  #
+  # Per RFC 9110 the header is either a non-negative integer count of seconds
+  # or an HTTP-date. Calling +.to_f+ on the header directly (the naive
+  # approach) turns the HTTP-date form into +0.0+, so a client honoring it
+  # would retry immediately and hammer a server that is actively asking it to
+  # back off. This helper handles both forms and falls back to a caller-supplied
+  # value when the header is absent or unparseable.
+  module RetryAfter
+    module_function
+
+    # @param header [String, nil] the raw +Retry-After+ header value
+    # @param fallback [Numeric] seconds to use when the header is missing or unparseable
+    # @param now [Time] reference time for the HTTP-date form (injectable for tests)
+    # @return [Float] non-negative seconds to wait
+    def seconds(header, fallback:, now: Time.now)
+      value = header.to_s.strip
+      return fallback.to_f if value.empty?
+
+      # delta-seconds form: a bare non-negative integer.
+      return value.to_f if value.match?(/\A\d+\z/)
+
+      # HTTP-date form: wait until that instant, never negative.
+      begin
+        [Time.httpdate(value) - now, 0.0].max
+      rescue ArgumentError
+        fallback.to_f
+      end
+    end
+  end
+end

data/lib/woods/unblocked/client.rb

@@ -4,6 +4,7 @@ require 'json'
 require 'net/http'
 require 'uri'
 require 'woods'
+require_relative '../retry_after'
 require_relative 'rate_limiter'
 
 module Woods
@@ -175,7 +176,9 @@ module Woods
 
           if response.code == '429' && retries < MAX_RETRIES
             retries += 1
-            wait_time = (response['Retry-After'] || (retries * 2)).to_f
+            # Retry-After may be an HTTP-date, which .to_f would collapse to
+            # 0.0 — honoring it as-is would hammer a throttling server.
+            wait_time = Woods::RetryAfter.seconds(response['Retry-After'], fallback: retries * 2)
             sleep(wait_time)
             next
           end

data/lib/woods/unblocked/document_builder.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'woods/export/unit_facts'
+
 module Woods
   module Unblocked
     # Converts extracted unit JSON into condensed Markdown documents
@@ -96,10 +98,10 @@ module Woods
         sections = []
 
         sections << model_header(unit, meta)
-        sections << model_associations(meta)
+        sections << model_associations(unit)
         sections << model_dependents(unit)
         sections << model_entry_points(unit)
-        sections << model_schema_highlights(meta)
+        sections << model_schema_highlights(unit)
         sections << model_side_effects(unit)
 
         sections.compact.join("\n\n")
@@ -116,22 +118,18 @@ module Woods
         parts.join("\n")
       end
 
-      def model_associations(meta)
-        assocs = meta['associations'] || []
-        return nil if assocs.empty?
+      def model_associations(unit)
+        facts = Woods::Export::UnitFacts.new(unit)
+        by_type = facts.associations_by_type
+        return nil if by_type.empty?
 
-        grouped = assocs.group_by { |a| a['type'] }
-        lines = ["## Associations (#{assocs.size})"]
+        lines = ["## Associations (#{facts.association_count})"]
 
         %w[belongs_to has_many has_one has_and_belongs_to_many].each do |type|
-          items = grouped[type]
+          items = by_type[type]
           next unless items&.any?
 
-          targets = items.map do |a|
-            name = a['target'] || a['name']
-            dep = a.dig('options', 'dependent')
-            dep ? "#{name} (#{dep})" : name
-          end
+          targets = items.map { |a| a[:dependent] ? "#{a[:target]} (#{a[:dependent]})" : a[:target] }
           # Sorted so the body is a function of association content, not order
           # (the exporter hashes this body to detect changes).
           lines << "**#{type}:** #{targets.sort.join(', ')}"
@@ -176,25 +174,21 @@ module Woods
         lines.join("\n")
       end
 
-      def model_schema_highlights(meta)
+      def model_schema_highlights(unit)
+        highlights = Woods::Export::UnitFacts.new(unit).schema_highlights
         parts = []
 
-        enums = meta['enums']
-        if enums.is_a?(Hash) && enums.any?
-          enum_strs = enums.sort_by { |name, _| name.to_s }
-                           .map { |name, values| "#{name} (#{format_enum_values(values)})" }
+        if highlights[:enums].any?
+          enum_strs = highlights[:enums].sort_by { |name, _| name.to_s }
+                                        .map { |name, values| "#{name} (#{format_enum_values(values)})" }
           parts << "**Enums:** #{enum_strs.join('; ')}"
         end
 
-        scopes = meta['scopes']
-        parts << "**Scopes:** #{scopes.map { |s| s['name'] }.sort.join(', ')}" if scopes.is_a?(Array) && scopes.any?
-
-        concerns = meta['inlined_concerns']
-        parts << "**Concerns:** #{concerns.sort.join(', ')}" if concerns.is_a?(Array) && concerns.any?
+        parts << "**Scopes:** #{highlights[:scopes].sort.join(', ')}" if highlights[:scopes].any?
+        parts << "**Concerns:** #{highlights[:concerns].sort.join(', ')}" if highlights[:concerns].any?
 
-        callbacks = meta['callbacks']
-        if callbacks.is_a?(Array) && callbacks.any?
-          parts << "**Callbacks (#{callbacks.size}):** #{format_callbacks(callbacks)}"
+        if highlights[:callbacks].any?
+          parts << "**Callbacks (#{highlights[:callbacks].size}):** #{format_callbacks(highlights[:callbacks])}"
         end
 
         return nil if parts.empty?
@@ -333,7 +327,7 @@ module Woods
       def format_callbacks(callbacks)
         # Sort before truncating so both the selection and order are stable
         # regardless of input order (the body is hashed for change detection).
-        callbacks.map { |cb| "#{cb['type']}: #{cb['filter']}" }.sort.first(5).join(', ')
+        callbacks.map { |cb| "#{cb[:type]}: #{cb[:filter]}" }.sort.first(5).join(', ')
       end
     end
   end

data/lib/woods/update_check.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+require 'tmpdir'
+require_relative 'version'
+require_relative 'atomic_file'
+
+module Woods
+  # Best-effort "is a newer Woods release available?" check.
+  #
+  # Modeled on grove's background update notifier: it queries RubyGems for the
+  # latest published +woods+ version, caches the answer on disk for 24h, and is
+  # fully non-fatal — any network, parse, or filesystem failure degrades to
+  # "no update signal" rather than raising. It exists so the MCP server can tell
+  # an agent (and, through it, the user) that the installed gem is behind, which
+  # matters because the distributed guide skills operate against whatever version
+  # is installed.
+  #
+  # Two surfaces consume this:
+  #   * {Woods::MCP::Server.build_status} embeds {status_hash} under
+  #     +server.update+ so +woods_status+ reports update availability.
+  #   * {Woods::MCP::VersionAwareToolDispatch} uses {tool_not_found_message} to
+  #     turn a bare "Tool not found" into version-aware, self-healing guidance.
+  #
+  # Disable entirely with +WOODS_NO_UPDATE_CHECK=1+.
+  #
+  # @example
+  #   Woods::UpdateCheck.status_hash
+  #   # => { current_version: "1.5.0", latest_version: "1.6.0", update_available: true }
+  module UpdateCheck
+    # RubyGems endpoint returning +{ "version": "x.y.z" }+ for the latest release.
+    RUBYGEMS_LATEST_URL = 'https://rubygems.org/api/v1/versions/woods/latest.json'
+    # How long a successful result is trusted before a re-fetch is attempted.
+    CACHE_TTL = 24 * 60 * 60
+    # A *failed* probe is cached for a shorter window, so an unreachable or slow
+    # RubyGems throttles retries (rather than re-blocking on every call) without
+    # hiding a real update for a full day once connectivity returns.
+    FAILURE_TTL = 60 * 60
+    # Open/read timeout for the (best-effort) network probe, in seconds.
+    HTTP_TIMEOUT = 1.5
+
+    module_function
+
+    # Resolve update availability, using the on-disk cache when fresh and
+    # otherwise fetching once and caching the result.
+    #
+    # @param current [String] Installed version (defaults to {Woods::VERSION})
+    # @param cache_path [String] Path to the JSON cache file
+    # @param ttl [Integer] Cache lifetime in seconds
+    # @param now [Time] Injected clock (for deterministic specs)
+    # @param fetcher [#call] Callable taking the URL and returning a version
+    #   string or nil; injectable for tests
+    # @return [Hash] +{ current:, latest:, update_available: }+ (latest may be nil)
+    def check(current: Woods::VERSION, cache_path: default_cache_path, ttl: CACHE_TTL,
+              now: Time.now, fetcher: method(:fetch_latest_version))
+      return result(current, nil) if disabled?
+
+      result(current, cached_or_refreshed_latest(cache_path, ttl, now, fetcher))
+    end
+
+    # The +server.update+ sub-hash for +woods_status+. Keys are snake_case to
+    # match the rest of the status payload's JSON shape.
+    #
+    # @return [Hash] +{ current_version:, latest_version:, update_available: }+
+    def status_hash(current: Woods::VERSION, **opts)
+      r = check(current: current, **opts)
+      {
+        current_version: r[:current],
+        latest_version: r[:latest],
+        update_available: r[:update_available]
+      }
+    end
+
+    # Version-aware replacement for the MCP layer's bare "Tool not found"
+    # message. Cache-only — it never triggers a network fetch, since it runs on
+    # an error path that must stay cheap.
+    #
+    # @param tool_name [String] The unrecognized tool name
+    # @param current [String] Installed version
+    # @return [String] Guidance an agent can relay to the user
+    def tool_not_found_message(tool_name, current: Woods::VERSION, cache_path: default_cache_path, fetcher: nil)
+      _ = fetcher # accepted so callers/specs can prove it is never invoked on this path
+      latest = disabled? ? nil : read_cache(cache_path)&.fetch('latest', nil)
+      msg = "Tool not found: #{tool_name}. This tool is not available in the installed " \
+            "Woods v#{current}. It may require a newer release — advise the user to run " \
+            '`bundle update woods`, then reconnect the MCP server.'
+      msg << " (latest published: #{latest})" if latest && newer?(latest, current)
+      msg
+    end
+
+    # --- internals -----------------------------------------------------------
+
+    def disabled?
+      ENV['WOODS_NO_UPDATE_CHECK'] == '1'
+    end
+
+    def result(current, latest)
+      { current: current, latest: latest, update_available: latest ? newer?(latest, current) : false }
+    end
+
+    def newer?(latest, current)
+      Gem::Version.new(latest) > Gem::Version.new(current)
+    rescue ArgumentError
+      false
+    end
+
+    # Return the cached latest version when the cache entry is still fresh
+    # (a shorter window applies to a previously-failed probe), otherwise fetch
+    # once and cache the outcome — success *or* failure.
+    #
+    # @return [String, nil]
+    def cached_or_refreshed_latest(cache_path, ttl, now, fetcher)
+      entry = read_cache(cache_path)
+      return entry['latest'] if entry && fresh_entry?(entry, ttl, now)
+
+      refresh(cache_path, now, fetcher)
+    end
+
+    # A success entry is trusted for +ttl+; a failure entry (nil latest) only
+    # for {FAILURE_TTL}.
+    def fresh_entry?(entry, ttl, now)
+      checked_at = entry['checked_at']
+      return false unless checked_at.is_a?(Numeric)
+
+      effective_ttl = entry['latest'] ? ttl : FAILURE_TTL
+      (now.to_i - checked_at) < effective_ttl
+    end
+
+    # Fetch and cache the outcome. A nil latest (unreachable RubyGems, non-2xx,
+    # unparseable body) is cached too, so repeated failures are throttled by
+    # {FAILURE_TTL} instead of re-probing on every call.
+    #
+    # @return [String, nil] the latest version, or nil on failure
+    def refresh(cache_path, now, fetcher)
+      latest = fetcher.call(RUBYGEMS_LATEST_URL)
+      write_cache(cache_path, latest, now)
+      latest
+    rescue StandardError
+      write_cache(cache_path, nil, now)
+      nil
+    end
+
+    # @return [Hash, nil] the parsed cache entry, or nil if absent, unreadable,
+    #   or not a JSON object (guards the "never raise" contract against a
+    #   corrupt/tampered cache holding e.g. +[]+ or +42+)
+    def read_cache(cache_path)
+      return nil unless File.exist?(cache_path)
+
+      parsed = JSON.parse(File.read(cache_path))
+      parsed.is_a?(Hash) ? parsed : nil
+    rescue StandardError
+      nil
+    end
+
+    def write_cache(cache_path, latest, now)
+      Woods::AtomicFile.write(cache_path, JSON.generate('latest' => latest, 'checked_at' => now.to_i))
+    rescue StandardError
+      nil
+    end
+
+    # Default per-user cache location, honoring XDG, falling back to tmpdir.
+    def default_cache_path
+      base = ENV.fetch('XDG_CACHE_HOME', nil)
+      base = File.join(Dir.home, '.cache') if base.nil? || base.empty?
+      File.join(base, 'woods', 'update_check.json')
+    rescue StandardError
+      File.join(Dir.tmpdir, 'woods-update-check.json')
+    end
+
+    # Best-effort RubyGems probe. Kept tiny and self-contained so the module has
+    # no non-stdlib dependencies.
+    #
+    # @return [String, nil] latest version string, or nil on any failure
+    def fetch_latest_version(url)
+      require 'net/http'
+      uri = URI(url)
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https',
+                                                     open_timeout: HTTP_TIMEOUT, read_timeout: HTTP_TIMEOUT) do |http|
+        http.get(uri.request_uri)
+      end
+      return nil unless response.is_a?(Net::HTTPSuccess)
+
+      version = JSON.parse(response.body)['version']
+      version if version.is_a?(String) && !version.empty?
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/woods/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Woods
-  VERSION = '1.5.0'
+  VERSION = '1.6.0'
 end

data/lib/woods.rb

@@ -319,6 +319,30 @@ module Woods
       end
     end
 
+    # Resolve the effective Notion API token.
+    #
+    # A non-blank +NOTION_API_TOKEN+ env var takes precedence; otherwise the
+    # configured +notion_api_token+ is used. A set-but-blank env var — common
+    # with docker-compose +${NOTION_API_TOKEN}+ interpolation of an unset
+    # host variable — is treated as absent, so it never masks a valid
+    # configured token nor slips through as a blank bearer. This is the single
+    # resolution point shared by the Notion exporter, the MCP +notion_sync+
+    # tool + its registration gate, and the rake task, so all four agree on a
+    # given host.
+    #
+    # @param config [Configuration] configuration to read the fallback from
+    # @return [String, nil] the resolved token, or nil when neither source
+    #   supplies a non-blank value
+    def resolve_notion_token(config = configuration)
+      env = ENV.fetch('NOTION_API_TOKEN', nil)
+      return env unless env.nil? || env.strip.empty?
+
+      configured = config.respond_to?(:notion_api_token) ? config.notion_api_token : nil
+      return nil if configured.nil? || configured.to_s.strip.empty?
+
+      configured
+    end
+
     # Build a Retriever wired with adapters from the current configuration.
     #
     # @return [Retriever] A fully wired retriever instance

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: woods
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Leah Armstrong
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-24 00:00:00.000000000 Z
+date: 2026-07-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mcp
@@ -112,6 +112,7 @@ files:
 - lib/woods/ast/method_extractor.rb
 - lib/woods/ast/node.rb
 - lib/woods/ast/parser.rb
+- lib/woods/atomic_file.rb
 - lib/woods/builder.rb
 - lib/woods/cache/cache_middleware.rb
 - lib/woods/cache/cache_store.rb
@@ -176,6 +177,7 @@ files:
 - lib/woods/evaluation/metrics.rb
 - lib/woods/evaluation/query_set.rb
 - lib/woods/evaluation/report_generator.rb
+- lib/woods/export/unit_facts.rb
 - lib/woods/extracted_unit.rb
 - lib/woods/extractor.rb
 - lib/woods/extractors/action_cable_extractor.rb
@@ -250,6 +252,7 @@ files:
 - lib/woods/mcp/renderers/plain_renderer.rb
 - lib/woods/mcp/server.rb
 - lib/woods/mcp/tool_response_renderer.rb
+- lib/woods/mcp/version_aware_tool_dispatch.rb
 - lib/woods/model_name_cache.rb
 - lib/woods/notion/client.rb
 - lib/woods/notion/exporter.rb
@@ -262,6 +265,11 @@ files:
 - lib/woods/observability/health_check.rb
 - lib/woods/observability/instrumentation.rb
 - lib/woods/observability/structured_logger.rb
+- lib/woods/obsidian/errors.rb
+- lib/woods/obsidian/name_mapper.rb
+- lib/woods/obsidian/note_builder.rb
+- lib/woods/obsidian/vault_assets.rb
+- lib/woods/obsidian/vault_exporter.rb
 - lib/woods/operator/error_escalator.rb
 - lib/woods/operator/pipeline_guard.rb
 - lib/woods/operator/status_reporter.rb
@@ -275,6 +283,7 @@ files:
 - lib/woods/retrieval/ranker.rb
 - lib/woods/retrieval/search_executor.rb
 - lib/woods/retriever.rb
+- lib/woods/retry_after.rb
 - lib/woods/ruby_analyzer.rb
 - lib/woods/ruby_analyzer/class_analyzer.rb
 - lib/woods/ruby_analyzer/dataflow_analyzer.rb
@@ -307,6 +316,7 @@ files:
 - lib/woods/unblocked/exporter.rb
 - lib/woods/unblocked/rate_limiter.rb
 - lib/woods/unblocked/sync_manifest.rb
+- lib/woods/update_check.rb
 - lib/woods/util/host_guard.rb
 - lib/woods/version.rb
 homepage: https://github.com/lost-in-the/woods