woods 1.5.0 → 1.6.1

data/lib/woods/flow_assembler.rb

@@ -60,19 +60,26 @@ module Woods
 
     # Recursively expand a unit into flow steps.
     #
+    # A cycle is a re-encounter on the CURRENT recursion path (tracked in
+    # +path+, popped on exit — the gray set of a DFS). A unit already
+    # expanded via a sibling branch (a DAG diamond: two services calling
+    # the same model) is plain dedup, not a cycle — it is skipped silently
+    # rather than mislabeled with a cycle marker.
+    #
     # @param identifier [String] Unit identifier (may include #method)
     # @param steps [Array<Hash>] Accumulator for step hashes
-    # @param visited [Set<String>] Visited unit identifiers for cycle detection
+    # @param visited [Set<String>] Already-expanded unit identifiers (dedup)
     # @param depth [Integer] Current recursion depth
     # @param max_depth [Integer] Maximum recursion depth
-    def expand(identifier, steps, visited, depth:, max_depth:)
+    # @param path [Set<String>] Identifiers on the current recursion path
+    def expand(identifier, steps, visited, depth:, max_depth:, path: Set.new)
       return if depth > max_depth
 
       # Parse identifier into unit name and optional method
       unit_id, method_name = parse_identifier(identifier)
 
-      if visited.include?(unit_id)
-        # Cycle detected - emit a marker step
+      if path.include?(unit_id)
+        # Genuine cycle — the unit is an ancestor of itself on this path.
         steps << {
           unit: unit_id,
           type: 'cycle',
@@ -81,34 +88,44 @@ module Woods
         return
       end
 
+      # Already expanded through another branch — dedup, not a cycle.
+      return if visited.include?(unit_id)
+
       visited.add(unit_id)
+      path.add(unit_id)
 
-      # Load the unit data from disk
-      unit_data = load_unit(unit_id)
-      return unless unit_data
+      begin
+        # Load the unit data from disk
+        unit_data = load_unit(unit_id)
+        return unless unit_data
 
-      source_code = unit_data[:source_code]
-      return unless source_code && !source_code.empty?
+        source_code = unit_data[:source_code]
+        return unless source_code && !source_code.empty?
 
-      metadata = unit_data[:metadata] || {}
-      unit_type = unit_data[:type]&.to_s
-      file_path = unit_data[:file_path]
+        metadata = unit_data[:metadata] || {}
+        unit_type = unit_data[:type]&.to_s
+        file_path = unit_data[:file_path]
 
-      # Extract operations from the relevant method
-      operations = extract_operations(source_code, method_name, metadata, unit_type)
+        # Extract operations from the relevant method
+        operations = extract_operations(source_code, method_name, metadata, unit_type)
 
-      step = {
-        unit: identifier,
-        type: unit_type,
-        file_path: file_path,
-        operations: operations
-      }
+        step = {
+          unit: identifier,
+          type: unit_type,
+          file_path: file_path,
+          operations: operations
+        }
 
-      steps << step
+        steps << step
 
-      # Recursively expand targets that resolve to known units
-      operations.each do |op|
-        expand_operation(op, identifier, steps, visited, depth: depth, max_depth: max_depth)
+        # Recursively expand targets that resolve to known units
+        operations.each do |op|
+          expand_operation(op, identifier, steps, visited, depth: depth, max_depth: max_depth, path: path)
+        end
+      ensure
+        # Pop on every exit (including the early returns above) — a unit
+        # left on the path would make sibling branches report false cycles.
+        path.delete(unit_id)
       end
     end
 
@@ -178,7 +195,7 @@ module Woods
     # @param visited [Set<String>] Visited unit identifiers for cycle detection
     # @param depth [Integer] Current recursion depth
     # @param max_depth [Integer] Maximum recursion depth
-    def expand_operation(op, current_unit, steps, visited, depth:, max_depth:)
+    def expand_operation(op, current_unit, steps, visited, depth:, max_depth:, path: Set.new)
       case op[:type]
       when :call, :async
         target = op[:target]
@@ -187,14 +204,14 @@ module Woods
         candidate = resolve_target(target)
         return unless candidate
 
-        expand(candidate, steps, visited, depth: depth + 1, max_depth: max_depth)
+        expand(candidate, steps, visited, depth: depth + 1, max_depth: max_depth, path: path)
       when :transaction
         (op[:nested] || []).each do |nested_op|
-          expand_operation(nested_op, current_unit, steps, visited, depth: depth, max_depth: max_depth)
+          expand_operation(nested_op, current_unit, steps, visited, depth: depth, max_depth: max_depth, path: path)
         end
       when :conditional
         ((op[:then_ops] || []) + (op[:else_ops] || [])).each do |branch_op|
-          expand_operation(branch_op, current_unit, steps, visited, depth: depth, max_depth: max_depth)
+          expand_operation(branch_op, current_unit, steps, visited, depth: depth, max_depth: max_depth, path: path)
         end
       end
     end

data/lib/woods/flow_precomputer.rb

@@ -2,6 +2,7 @@
 
 require 'json'
 require 'fileutils'
+require_relative 'filename_utils'
 require_relative 'flow_assembler'
 
 module Woods
@@ -80,7 +81,7 @@ module Woods
     def assemble_and_write(assembler, entry_point, controller_id, action)
       flow = assembler.assemble(entry_point, max_depth: @max_depth)
 
-      filename = "#{controller_id.gsub('::', '__')}_#{action}.json"
+      filename = Woods::FilenameUtils.flow_filename(controller_id, action)
       flow_path = File.join(@flows_dir, filename)
 
       File.write(flow_path, canonical_json(flow.to_h))

data/lib/woods/index_artifact.rb

@@ -127,7 +127,11 @@ module Woods
       target_real = target.exist? ? target.realpath.to_s : ''
       # Resolve symlinks on both sides before comparing (handles macOS /tmp → /private/var)
       root_resolved = Pathname.new(root_real).exist? ? Pathname.new(root_real).realpath.to_s : root_real
-      unless target.exist? && target_real.start_with?(root_resolved)
+      # Prefix must end at a path boundary — a bare start_with? would accept
+      # sibling directories like "dumps-backup" or "dumpsevil", and the
+      # basename-only pointer written below would then name a directory that
+      # doesn't exist under dumps_root.
+      unless target.exist? && target_real.start_with?("#{root_resolved}#{File::SEPARATOR}")
         raise ArgumentError,
               'dump_dir must exist inside dumps_root. ' \
               "Got: #{dump_dir.inspect}, dumps_root: #{dumps_root}"

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