woods 2.0.0.beta2 → 2.0.0.beta4

data/lib/woods/mcp/bootstrapper.rb

@@ -6,6 +6,7 @@ require_relative 'errors'
 require_relative 'bootstrap_state'
 require_relative 'config_resolver'
 require_relative 'provider_probe'
+require_relative 'published_lexical_retriever'
 require_relative '../index_artifact'
 require_relative '../builder'
 require_relative '../resolved_config'
@@ -27,16 +28,19 @@ module Woods
       # @param argv [Array<String>] Command-line arguments
       # @return [String] Validated index directory path
       def self.resolve_index_dir(argv)
-        dir = argv[0] || ENV['WOODS_DIR'] || Dir.pwd
+        dir = argv[0] || ENV['WOODS_DIR'] || ENV['WOODS_OUTPUT'] || Dir.pwd
+        examined = dir.empty? ? '(empty path)' : File.expand_path(dir)
 
         unless Dir.exist?(dir)
-          warn "Error: Index directory does not exist: #{dir}"
+          warn "Error: Index directory does not exist: #{examined}"
+          warn index_path_remedy
           exit 1
         end
 
         unless manifest_present?(dir)
-          warn "Error: No manifest.json found in: #{dir}"
-          warn 'Run `bundle exec rake woods:extract` in your Rails app first.'
+          warn "Error: Could not resolve a published Woods index in: #{examined}"
+          warn 'Expected generation.json pointing to a payload manifest.json, or a legacy flat manifest.json.'
+          warn index_path_remedy
           exit 1
         end
 
@@ -60,9 +64,19 @@ module Woods
 
         generation = Woods::Generation.new(output_dir: dir)
         generation.payload_dir(generation.current).join('manifest.json').file?
+      rescue TypeError, NoMethodError
+        # A malformed marker must remain a startup failure, with the same
+        # selected-path guidance as a missing or unresolved payload.
+        false
       end
       private_class_method :manifest_present?
 
+      def self.index_path_remedy
+        'Point at the existing index with an explicit path, WOODS_DIR, or WOODS_OUTPUT. ' \
+          'If no index exists, run `bundle exec rake woods:extract` in your Rails app.'
+      end
+      private_class_method :index_path_remedy
+
       # Build a snapshot store for temporal tracking.
       #
       # Auto-enables when a SQLite database already exists in the index directory,
@@ -128,6 +142,12 @@ module Woods
       #   credentials, dimension mismatch, unsupported artifact, or a missing
       #   artifact under WOODS_REQUIRE_INDEX=1).
       def self.build_retriever(index_dir: nil)
+        mode = ENV.fetch('WOODS_RETRIEVAL_MODE', Woods.configuration.retrieval_mode.to_s)
+        unless %w[semantic lexical].include?(mode)
+          raise BootstrapError, "WOODS_RETRIEVAL_MODE must be semantic or lexical, got #{mode.inspect}"
+        end
+        return build_lexical_retriever(index_dir) if mode == 'lexical'
+
         state = BootstrapState.new
         state.mark(:hydrating)
 
@@ -161,6 +181,20 @@ module Woods
         [retriever, state]
       end
 
+      def self.build_lexical_retriever(index_dir)
+        state = BootstrapState.new
+        state.mark(:hydrating)
+        retriever = PublishedLexicalRetriever.new(index_dir: index_dir || Woods.configuration.output_dir,
+                                                  default_budget: Woods.configuration.max_context_tokens)
+        retriever.warmup!
+        state.mark(:hydrated)
+        warn '[woods-mcp] lexical retrieval: hydrated (published extraction units; no embeddings)'
+        [retriever, state]
+      rescue StandardError => e
+        raise BootstrapError, "lexical index could not be loaded: #{e.class}: #{e.message}"
+      end
+      private_class_method :build_lexical_retriever
+
       def self.static_source_map_without_embeddings?(artifact)
         return false unless artifact
 
@@ -248,6 +282,10 @@ module Woods
         zero_counts = { vectors: 0, metadata: 0, graph: 0 }
         return refresh_reader_only(reader, zero_counts) unless retriever
 
+        if retriever.is_a?(PublishedLexicalRetriever)
+          return reload_lexical_stores!(retriever, index_dir, reader || retriever.reader, state, hooks)
+        end
+
         target = swap_target(retriever)
         return refresh_reader_only(reader, zero_counts) unless target
 
@@ -312,6 +350,43 @@ module Woods
       # Refresh the reader's cached index state and answer the zero-count
       # no-op (MCP-2).
       #
+      def self.reload_lexical_stores!(retriever, index_dir, reader, state, hooks)
+        generation = Woods::Generation.new(output_dir: index_dir)
+        captured = generation.current
+        candidate = PublishedLexicalRetriever.new(index_dir: index_dir).warmup!
+        run_hook(hooks, :after_candidates)
+        lock = reload_extraction_lock(index_dir)
+        unless acquire_writer_lock_briefly(lock)
+          raise ReloadDegraded.new('lexical reload could not acquire the extraction writer lock',
+                                   generation: reader.loaded_generation || 0, stores: ['metadata'])
+        end
+
+        begin
+          reader.with_exclusive_generation do
+            identity = candidate.snapshot.first
+            expected = [captured.number, captured.token, generation.payload_dir(captured).to_s]
+            unless same_generation_marker?(captured, generation.current) &&
+                   [identity.first.to_i, *identity.drop(1)] == expected
+              raise ReloadGenerationMoved.new('generation moved during lexical reload; nothing was swapped',
+                                              generation: reader.loaded_generation || 0, stores: ['metadata'])
+            end
+            counts = { vectors: 0, metadata: candidate.metadata_store.count, graph: 0 }
+            reader.reload!
+            retriever.install_snapshot!(candidate.snapshot)
+            state&.clear_reload_failure!
+            counts
+          end
+        ensure
+          lock.release
+        end
+      rescue ReloadDegraded
+        raise
+      rescue StandardError => e
+        raise ReloadDegraded.new("lexical snapshot reload failed: #{e.class}: #{e.message}",
+                                 generation: reader.loaded_generation || 0, stores: ['metadata'])
+      end
+      private_class_method :reload_lexical_stores!
+
       # A store no-op is not an index no-op: the caller invoked `reload`
       # because something on disk moved, and on a flat (pre-2.0) index
       # {IndexReader} never self-refreshes, so skipping this reports

data/lib/woods/mcp/config_resolver.rb

@@ -295,7 +295,8 @@ module Woods
         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.'
+               'OPENAI_API_KEY / run Ollama, to enable semantic search. For ranked discovery with no embeddings, ' \
+               'set WOODS_RETRIEVAL_MODE=lexical in the MCP process environment and restart the server.'
         end
         [resolved, :autodetect]
       end