woods 1.4.1 → 1.6.0

data/lib/woods/mcp/config_resolver.rb

@@ -23,9 +23,12 @@ module Woods
     #    compatible via {ResolvedConfig#assert_compatible!}.
     # 2. +woods.json+ snapshot alone (MCP server running without a host initializer).
     #    The stored config is used to populate +config+ in place.
-    # 3. Environment-variable auto-detect (deprecated, opt-in via
-    #    +WOODS_ALLOW_AUTODETECT=1+). Mutates +config+ to set provider and stores.
-    # 4. If none of the above applies, raises {MissingArtifact}.
+    # 3. Environment-variable auto-detect (the default when +woods.json+ is
+    #    absent and no host provider is set). Wires semantic search if
+    #    +OPENAI_API_KEY+ or a reachable Ollama is found; otherwise leaves the
+    #    provider nil so the server boots in pattern/structural-only mode.
+    # 4. +WOODS_REQUIRE_INDEX=1+ overrides (3) to fail closed, raising
+    #    {MissingArtifact} when +woods.json+ is absent.
     #
     # @example Typical Bootstrapper usage
     #   config, source = ConfigResolver.resolve(Woods.configuration, artifact: artifact)
@@ -43,10 +46,11 @@ module Woods
       # When +woods.json+ is absent and the host already has a provider
       # configured, the host config is trusted and used as-is.
       #
-      # When +woods.json+ is absent and the host has no provider configured:
-      # - If +WOODS_ALLOW_AUTODETECT+ is +1+, falls through to env-var
-      #   auto-detect (deprecated, emits a structured warning).
-      # - Otherwise raises {MissingArtifact}.
+      # When +woods.json+ is absent and the host has no provider configured,
+      # auto-detect runs by default: pattern/structural tools always work, and
+      # semantic search wires up only if +OPENAI_API_KEY+ or a reachable Ollama
+      # is found. Set +WOODS_REQUIRE_INDEX=1+ to fail closed and raise
+      # {MissingArtifact} instead.
       #
       # @param config [Woods::Configuration] the live host configuration object.
       #   May be mutated in the auto-detect path.
@@ -61,7 +65,7 @@ module Woods
       #   where +source+ is one of +:snapshot+, +:host_config+, +:autodetect+,
       #   or +:none+. The config is the same object passed in, possibly mutated.
       # @raise [Woods::MCP::MissingArtifact] when +woods.json+ is absent, the
-      #   host has no provider configured, and +WOODS_ALLOW_AUTODETECT+ is unset.
+      #   host has no provider configured, and +WOODS_REQUIRE_INDEX=1+ is set.
       # @raise [Woods::MCP::UnsupportedArtifact] when +woods.json+ has an
       #   unsupported +schema_version+.
       # @raise [Woods::MCP::DimensionMismatch] when stored and live provider
@@ -201,36 +205,53 @@ module Woods
 
       # Handle the no-artifact, no-host-provider case.
       #
-      # Raises {MissingArtifact} unless +WOODS_ALLOW_AUTODETECT=1+ opts in to
-      # the deprecated env-var auto-detect path.
+      # Extract-only hosts — those that ran +woods:extract+ but never
+      # +woods:embed+ and configured no embedding provider — boot in
+      # pattern/structural mode by default. The env-var auto-detect path runs,
+      # wiring semantic search only if +OPENAI_API_KEY+ or a reachable Ollama
+      # instance is found. With neither, +config+ comes back with a nil provider
+      # and {Bootstrapper.build_retriever} returns a nil retriever, leaving the
+      # always-on pattern/regex/structural tools fully functional.
+      #
+      # Set +WOODS_REQUIRE_INDEX=1+ to fail closed instead: demand a real
+      # +woods.json+ and raise {MissingArtifact} when it is absent.
+      # +WOODS_ALLOW_AUTODETECT+ is retained for backward compatibility but no
+      # longer changes behaviour — auto-detect is now the default.
       #
       # @param config [Woods::Configuration]
       # @param artifact [Woods::IndexArtifact, nil]
       # @param env [Hash]
       # @param ollama_probe [#call, nil]
-      # @return [Woods::Configuration]
-      # @raise [Woods::MCP::MissingArtifact]
+      # @return [Array(Woods::Configuration, Symbol)]
+      # @raise [Woods::MCP::MissingArtifact] only when +WOODS_REQUIRE_INDEX=1+.
       def self.resolve_without_artifact(config, artifact:, env:, ollama_probe:)
-        if env['WOODS_ALLOW_AUTODETECT'] != '1'
+        if env['WOODS_REQUIRE_INDEX'] == '1'
           raise MissingArtifact.new(
-            'No woods.json found and WOODS_ALLOW_AUTODETECT is unset. ' \
-            'Run `bundle exec rake woods:extract` in your host app, or set ' \
-            'WOODS_ALLOW_AUTODETECT=1 to probe env vars (deprecated).',
+            'No woods.json found and WOODS_REQUIRE_INDEX=1 demands a real index. ' \
+            'Run `bundle exec rake woods:extract` (then `woods:embed` for semantic ' \
+            'search) in your host app, or unset WOODS_REQUIRE_INDEX to boot in ' \
+            'pattern-only mode.',
             details: { output_dir: artifact&.output_dir&.to_s }
           )
         end
 
-        warn '[woods-mcp] deprecated_autodetect: falling back to env-var auto-detect (no woods.json found)'
-        [autodetect_from_env(config, env: env, ollama_probe: ollama_probe), :autodetect]
+        resolved = autodetect_from_env(config, env: env, ollama_probe: ollama_probe)
+        unless resolved.embedding_provider
+          warn '[woods-mcp] no woods.json and no embedding provider — serving ' \
+               'pattern/structural tools only. Run `rake woods:embed`, or set ' \
+               'OPENAI_API_KEY / run Ollama, to enable semantic search.'
+        end
+        [resolved, :autodetect]
       end
       private_class_method :resolve_without_artifact
 
       # Probe environment variables for provider credentials and configure
       # +config+ accordingly.
       #
-      # Only reachable when +WOODS_ALLOW_AUTODETECT=1+ and no +woods.json+
-      # is present. Mutates +config+ to set provider and stores when a
-      # credential or reachable Ollama instance is found.
+      # Reached by default when no +woods.json+ is present and the host
+      # configured no provider (unless +WOODS_REQUIRE_INDEX=1+). Mutates
+      # +config+ to set provider and stores when a credential or reachable
+      # Ollama instance is found; leaves the provider nil otherwise.
       #
       # @param config [Woods::Configuration]
       # @param env [Hash]

data/lib/woods/mcp/errors.rb

@@ -72,9 +72,11 @@ module Woods
     #   )
     class UnsupportedArtifact < BootstrapError; end
 
-    # Raised when +woods.json+ is absent from +output_dir+ and the env flag
-    # +WOODS_ALLOW_AUTODETECT+ is not set. Hosts that have never run an embed
-    # see a clear failure message rather than silent degradation.
+    # Raised when +woods.json+ is absent from +output_dir+ and the operator has
+    # opted into strict mode with +WOODS_REQUIRE_INDEX=1+. By default an absent
+    # artifact is *not* an error — the server boots in pattern/structural-only
+    # mode (see {ConfigResolver.resolve_without_artifact}). Strict mode exists
+    # for deployments that want to fail closed when an index is missing.
     #
     # @example
     #   raise Woods::MCP::MissingArtifact.new(

data/lib/woods/mcp/server.rb

@@ -7,8 +7,11 @@ require 'open3'
 require 'time'
 require 'set'
 require_relative '../tasks'
+require_relative '../filename_utils'
+require_relative '../update_check'
 require_relative 'index_reader'
 require_relative 'tool_response_renderer'
+require_relative 'version_aware_tool_dispatch'
 
 module Woods
   module MCP
@@ -27,6 +30,15 @@ module Woods
     #   transport.open
     #
     module Server
+      # Module-level pipeline serialization state, eagerly initialized at load
+      # time (self == Server here). The HTTP transport dispatches tool handlers
+      # concurrently, so a lazy `@pipeline_mutex ||= Mutex.new` inside
+      # pipeline_start would let two handlers each create a DIFFERENT mutex and
+      # synchronize on separate locks — defeating the exclusion and allowing two
+      # concurrent pipelines of the same kind.
+      @pipeline_mutex = Mutex.new
+      @pipeline_in_flight = {}
+
       class << self
         # Build a configured MCP::Server with all tools and resources.
         #
@@ -87,6 +99,9 @@ module Woods
             resources: resources,
             resource_templates: resource_templates
           )
+          # Rewrite "Tool not found" into version-aware update guidance for agents
+          # running against an older gem than the skill they're following assumes.
+          server.singleton_class.prepend(VersionAwareToolDispatch)
 
           define_lookup_tool(server, reader, respond, respond_err, renderer)
           define_search_tool(server, reader, respond, respond_err, renderer)
@@ -152,15 +167,18 @@ module Woods
         end
 
         # Notion export needs both an API token and at least one database ID.
-        # NOTION_API_TOKEN env var overrides the config token (see
-        # docs/NOTION_EXPORT.md).
+        # A non-blank NOTION_API_TOKEN env var overrides the config token (see
+        # docs/NOTION_EXPORT.md). Resolution goes through
+        # Woods.resolve_notion_token so a blank env var is treated as absent
+        # (rather than masking a valid configured token) — matching the
+        # exporter and the notion_sync handler.
         def notion_wired?
           config = Woods.configuration
           return false unless config
 
-          token = ENV['NOTION_API_TOKEN'] || (config.respond_to?(:notion_api_token) ? config.notion_api_token : nil)
+          token = Woods.resolve_notion_token(config)
           ids = config.respond_to?(:notion_database_ids) ? config.notion_database_ids : nil
-          token && !token.empty? && ids && !ids.empty?
+          !token.nil? && ids && !ids.empty?
         end
 
         def text_response(text)
@@ -255,7 +273,11 @@ module Woods
           controller, action = entry_point.split('#', 2)
           return nil if controller.empty? || action.empty?
 
-          filename = "#{controller.gsub('::', '__')}_#{action}.json"
+          # entry_point is client input — FilenameUtils.flow_filename
+          # allow-lists both parts (so `/` and `..` can't traverse outside
+          # flows/) using the SAME transform FlowPrecomputer writes with, so a
+          # legitimately precomputed flow always resolves to the file on disk.
+          filename = Woods::FilenameUtils.flow_filename(controller, action)
           path = File.join(index_dir, 'flows', filename)
           return nil unless File.exist?(path)
 
@@ -875,12 +897,34 @@ module Woods
             description: 'Trigger a codebase extraction pipeline run. Checks rate limits before proceeding.',
             input_schema: {
               properties: {
-                incremental: { type: 'boolean', description: 'Run incremental extraction (default: false)' }
+                incremental: { type: 'boolean', description: 'Run incremental extraction (default: false)' },
+                changed_files: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description: 'Required when incremental is true: repo-relative paths of changed files ' \
+                               '(the MCP server has no git context to compute them itself).'
+                }
               }
             }
-          ) do |server_context:, incremental: nil|
+          ) do |server_context:, incremental: nil, changed_files: nil|
             next op_missing.call('pipeline_extract') unless operator
 
+            # Incremental extraction re-extracts only the units affected by
+            # the given files. The MCP server has no git-diff context (unlike
+            # the rake task, which derives them from CHANGED_FILES / CI env),
+            # so an empty list would re-extract nothing while still bumping
+            # the manifest timestamp — a silent no-op reporting success.
+            # Require the caller to supply the changed files explicitly.
+            files = Array(changed_files).map(&:to_s).reject(&:empty?)
+            if incremental && files.empty?
+              next respond_err.call(
+                'Incremental extraction requires a non-empty changed_files list. ' \
+                'Pass the changed paths, or run `rake woods:incremental` which derives them from git.',
+                code: :invalid_params,
+                tool: 'pipeline_extract'
+              )
+            end
+
             guard = operator[:pipeline_guard]
             if guard && !guard.allow?(:extraction)
               next respond_err.call(
@@ -910,7 +954,7 @@ module Woods
               extractor = Woods::Extractor.new(
                 output_dir: Woods.configuration.output_dir
               )
-              incremental ? extractor.extract_changed([]) : extractor.extract_all
+              incremental ? extractor.extract_changed(files) : extractor.extract_all
             rescue StandardError => e
               logger = defined?(Rails) ? Rails.logger : Logger.new($stderr)
               logger.error("[Woods] Pipeline extract failed: #{e.message}")
@@ -987,8 +1031,9 @@ module Woods
         # pipeline). Module-level state — a single MCP server process
         # serializes its own pipelines.
         def pipeline_start(kind)
-          @pipeline_mutex ||= Mutex.new
-          @pipeline_in_flight ||= {}
+          # @pipeline_mutex / @pipeline_in_flight are initialized eagerly in
+          # the module body — no lazy `||=` here, which would race under the
+          # concurrent HTTP transport.
           @pipeline_mutex.synchronize do
             return false if @pipeline_in_flight[kind]
 
@@ -998,7 +1043,7 @@ module Woods
         end
 
         def pipeline_finish(kind)
-          @pipeline_mutex&.synchronize { @pipeline_in_flight&.delete(kind) }
+          @pipeline_mutex.synchronize { @pipeline_in_flight.delete(kind) }
         end
 
         def define_pipeline_status_tool(server, operator, respond, respond_err, op_missing)
@@ -1048,9 +1093,11 @@ module Woods
               )
             end
 
+            # Pass the client-supplied class name so class-keyed patterns
+            # (Timeout, Net::, Errno::ENOENT, …) match — a bare
+            # StandardError would classify everything as :unknown.
             error = StandardError.new(error_message)
-            # Set the class name in the error string for pattern matching
-            result = escalator.classify(error)
+            result = escalator.classify(error, class_name: error_class)
             result[:original_class] = error_class
             respond.call(JSON.pretty_generate(result))
           end
@@ -1302,7 +1349,12 @@ module Woods
             }
           ) do |server_context:|
             config = Woods.configuration
-            unless config.notion_api_token
+            # Mirror notion_wired? (which gates registration) and the
+            # Exporter via the shared resolver: a non-blank NOTION_API_TOKEN
+            # env var satisfies the token requirement (reading config alone
+            # rejected ENV-only hosts even though the tool was registered for
+            # them), while a blank env var is treated as absent.
+            if Woods.resolve_notion_token(config).nil?
               next respond_err.call(
                 'notion_api_token is not configured. Set it in Woods.configure or via the NOTION_API_TOKEN env var.',
                 code: :not_configured,
@@ -1421,7 +1473,8 @@ module Woods
             server: {
               name: 'woods',
               version: Woods::VERSION,
-              index_dir: index_dir.to_s
+              index_dir: index_dir.to_s,
+              update: Woods::UpdateCheck.status_hash
             },
             index: index_section(manifest, extracted_at, staleness, index_dir),
             retriever: {

data/lib/woods/mcp/version_aware_tool_dispatch.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative '../update_check'
+
+module Woods
+  module MCP
+    # Prepended onto a built +MCP::Server+ instance so that a call to a tool the
+    # installed gem does not define produces version-aware, self-healing
+    # guidance instead of a bare "Tool not found".
+    #
+    # An agent following a newer version of the distributed guide skills may try
+    # to call a tool that only exists in a later Woods release. The upstream
+    # +mcp+ gem raises +RequestHandlerError("Tool not found: X")+ with no seam to
+    # customize the message, so we intercept the built server's +call_tool+
+    # (dispatched directly by +handle_request+, so a prepend on the instance is
+    # honored on both the stdio and HTTP transports) and re-raise with the
+    # installed version plus an update hint the agent can relay to the user.
+    #
+    # Only the genuine tool-not-found case is rewritten; every other
+    # +RequestHandlerError+ (missing/invalid arguments, internal errors) is
+    # re-raised untouched.
+    module VersionAwareToolDispatch
+      # @param request [Hash] the tools/call params (carries +:name+)
+      # @return [MCP::Tool::Response] the tool result
+      # @raise [MCP::Server::RequestHandlerError] rewritten for unknown tools
+      def call_tool(request, **)
+        super
+      rescue ::MCP::Server::RequestHandlerError => e
+        raise unless tool_not_found_error?(e)
+
+        raise ::MCP::Server::RequestHandlerError.new(
+          Woods::UpdateCheck.tool_not_found_message(request[:name]),
+          request,
+          error_type: :invalid_params,
+          original_error: e
+        )
+      end
+
+      private
+
+      # The gem raises exactly this shape for an unregistered tool name.
+      def tool_not_found_error?(error)
+        error.error_type == :invalid_params && error.message.to_s.start_with?('Tool not found:')
+      end
+    end
+  end
+end

data/lib/woods/model_name_cache.rb

@@ -87,7 +87,12 @@ module Woods
         names = model_names
         return /(?!)/ if names.empty? # never-matching regex
 
-        /\b(?:#{names.map { |n| Regexp.escape(n) }.join('|')})\b/
+        # Longest-first: regex alternation is ordered, not longest-match.
+        # Without the sort, a reference to Library::Book::Chapter can match
+        # the shorter Library::Book alternative (\b is satisfied at the
+        # following ":"), emitting an edge to the wrong model.
+        sorted = names.sort_by { |n| -n.length }
+        /\b(?:#{sorted.map { |n| Regexp.escape(n) }.join('|')})\b/
       end
 
       # Build short-name → full-name mapping. A short name that appears on

data/lib/woods/notion/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
@@ -135,7 +136,9 @@ module Woods
 
           if response.code == '429' && retries < MAX_RETRIES
             retries += 1
-            wait_time = (response['Retry-After'] || retries).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)
             sleep(wait_time)
             next
           end

data/lib/woods/notion/exporter.rb

@@ -25,7 +25,13 @@ module Woods
       # @param reader [Object, nil] IndexReader instance (auto-created from index_dir if nil)
       # @raise [ConfigurationError] if notion_api_token is not configured
       def initialize(index_dir:, config: Woods.configuration, client: nil, reader: nil)
-        api_token = config.notion_api_token
+        # A non-blank NOTION_API_TOKEN overrides the configured token
+        # (documented contract; also what the MCP notion_wired? gate keys on).
+        # Resolve via the shared Woods.resolve_notion_token so the exporter,
+        # the MCP tool, and the rake task treat a blank env var identically —
+        # a set-but-empty NOTION_API_TOKEN must not mask a configured token or
+        # pass through as a blank bearer.
+        api_token = Woods.resolve_notion_token(config)
         raise ConfigurationError, 'notion_api_token is required for Notion export' unless api_token
 
         @database_ids = config.notion_database_ids || {}

data/lib/woods/obsidian/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'woods'
+
+module Woods
+  module Obsidian
+    # Raised for recoverable Obsidian export failures (e.g. a missing extraction
+    # output dir). Inherits Woods::Error so callers can rescue the gem's hierarchy.
+    class ExportError < Woods::Error; end
+  end
+end

data/lib/woods/obsidian/name_mapper.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'set'
+require 'digest'
+
+module Woods
+  module Obsidian
+    # Centralizes the identifier -> note-filename mapping for an Obsidian vault.
+    #
+    # This is the single source of truth for three things that must always
+    # agree: the filename a note is written to, the wikilink target that points
+    # at it, and the inverse +path -> id+ map shipped in the machine sidecar.
+    # Building them in one place means a link can never point at a filename the
+    # writer didn't produce.
+    #
+    # Rules:
+    # - Sanitize +::+ to +__+ and every other non +[A-Za-z0-9_-]+ char to +_+,
+    #   so the basename is always safe both as a filename and as a wikilink
+    #   target (Obsidian's +# | ^ : %%+ link-breaking chars are all removed).
+    # - Collisions are resolved **per folder**, case-insensitively (macOS/Windows
+    #   fold case): the colliding note gets a short content hash appended. Two
+    #   identical basenames in *different* type folders are distinct paths and
+    #   need no hash.
+    # - The MOC basename +_index+ is reserved in every folder so a (pathological)
+    #   unit named +_index+ can never overwrite a folder's index note.
+    # - Filenames are capped to 255 bytes, truncated on a UTF-8 char boundary.
+    # - The alias (the human-readable display half of a wikilink) keeps the
+    #   original identifier, with only the link-structural chars +[ ] |+ replaced.
+    #
+    # Determinism: ids are processed in sorted order, so the same input always
+    # produces the same collision-hash assignments.
+    class NameMapper
+      MAX_FILENAME_BYTES = 255
+      EXTENSION = '.md'
+      HASH_SUFFIX_BYTES = 9 # "-" + 8 hex chars
+      RESERVED_BASENAMES = %w[_index].freeze
+
+      # @param id_to_dir [Hash{String=>String}] map of unit identifier -> type
+      #   folder name (e.g. "User" => "models")
+      def initialize(id_to_dir)
+        @map = {}
+        @paths = {}
+        build(id_to_dir)
+      end
+
+      # @return [Array<String>] exported identifiers, sorted
+      def ids
+        @map.keys
+      end
+
+      # @param id [String]
+      # @return [Boolean] whether this id has an emitted note
+      def known?(id)
+        @map.key?(id)
+      end
+
+      # @param id [String]
+      # @return [String, nil] vault-relative note path ("models/User.md")
+      def path_for(id)
+        @map[id]&.fetch(:path)
+      end
+
+      # @param id [String]
+      # @return [String, nil] wikilink target with no extension ("models/User")
+      def target_for(id)
+        @map[id]&.fetch(:target)
+      end
+
+      # @param id [String]
+      # @return [String, nil] full wikilink ("[[models/User|User]]") or nil if unknown
+      def wikilink(id)
+        entry = @map[id]
+        return nil unless entry
+
+        "[[#{entry[:target]}|#{entry[:alias]}]]"
+      end
+
+      # @return [Hash{String=>String}] inverse path -> id map (sorted)
+      def paths_to_ids
+        @paths
+      end
+
+      private
+
+      def build(id_to_dir)
+        taken = Hash.new { |h, dir| h[dir] = Set.new(RESERVED_BASENAMES) }
+        id_to_dir.keys.sort.each do |id|
+          dir = id_to_dir[id]
+          basename = assign_basename(id, taken[dir])
+          path = "#{dir}/#{basename}#{EXTENSION}"
+          @map[id] = { dir: dir, basename: basename, path: path, target: "#{dir}/#{basename}", alias: alias_for(id) }
+          @paths[path] = id
+        end
+      end
+
+      def assign_basename(id, used)
+        base = fit(sanitize(id), EXTENSION.bytesize)
+        if used.include?(base.downcase)
+          base = "#{fit(sanitize(id), EXTENSION.bytesize + HASH_SUFFIX_BYTES)}-#{Digest::SHA256.hexdigest(id)[0, 8]}"
+        end
+        used << base.downcase
+        base
+      end
+
+      def sanitize(id)
+        out = id.to_s.gsub('::', '__').gsub(/[^a-zA-Z0-9_-]/, '_')
+        out.empty? ? 'unit' : out
+      end
+
+      # Replace only the chars that are structural inside a wikilink alias.
+      # `#` and `:` are safe in alias display text and are kept for readability.
+      def alias_for(id)
+        id.to_s.gsub('[', '(').gsub(']', ')').gsub('|', '/')
+      end
+
+      # Truncate +str+ so it fits within MAX_FILENAME_BYTES minus +reserve+
+      # bytes, never splitting a multibyte character.
+      def fit(str, reserve)
+        limit = MAX_FILENAME_BYTES - reserve
+        return str if str.bytesize <= limit
+
+        out = +''
+        str.each_char do |ch|
+          break if out.bytesize + ch.bytesize > limit
+
+          out << ch
+        end
+        out
+      end
+    end
+  end
+end