woods 1.0.0

data/exe/woods-console

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Embedded console MCP server — runs inside a Rails environment.
+#
+# Usage (via rake, recommended):
+#   bundle exec rake woods:console
+#
+# Usage (via rails runner):
+#   bundle exec rails runner "$(bundle show woods)/exe/woods-console"
+#
+# The rake task captures stdout before Rails boots and passes the fd via
+# $woods_protocol_out. When run via rails runner, this script
+# captures stdout itself to keep MCP protocol clean.
+
+# Check if the rake task already captured stdout for us.
+protocol_out = $woods_protocol_out # rubocop:disable Style/GlobalVars
+
+unless protocol_out
+  # Running via rails runner — capture stdout ourselves.
+  protocol_out = $stdout.dup
+  $stdout.reopen($stderr)
+end
+
+require 'woods/console/server'
+
+# Ensure all application models are loaded for the registry.
+Rails.application.eager_load!
+
+registry = ActiveRecord::Base.descendants.each_with_object({}) do |model, hash|
+  next if model.abstract_class?
+  next unless model.table_exists?
+
+  hash[model.name] = model.column_names
+rescue StandardError
+  next
+end
+
+validator = Woods::Console::ModelValidator.new(registry: registry)
+safe_context = Woods::Console::SafeContext.new(connection: ActiveRecord::Base.connection)
+
+redacted_columns = if Woods.respond_to?(:configuration) && Woods.configuration
+                     Array(Woods.configuration.console_redacted_columns)
+                   else
+                     []
+                   end
+
+server = Woods::Console::Server.build_embedded(
+  model_validator: validator,
+  safe_context: safe_context,
+  redacted_columns: redacted_columns
+)
+
+# Restore the protocol output for MCP transport.
+$stdout.reopen(protocol_out)
+protocol_out.close unless protocol_out.closed?
+
+transport = MCP::Server::Transports::StdioTransport.new(server)
+transport.open

data/exe/woods-console-mcp

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Console MCP server for querying live Rails application state.
+#
+# Usage:
+#   woods-console-mcp
+#   WOODS_CONSOLE_CONFIG=/path/to/console.yml woods-console-mcp
+#
+# Connects to a Rails application via a bridge process (Docker exec, direct,
+# or SSH) and exposes read-only query tools via the Model Context Protocol
+# (stdio transport).
+
+require 'yaml'
+require_relative '../lib/woods/console/server'
+
+config_path = ENV.fetch('WOODS_CONSOLE_CONFIG', File.expand_path('~/.woods/console.yml'))
+config = File.exist?(config_path) ? YAML.safe_load_file(config_path) : {}
+
+server = Woods::Console::Server.build(config: config)
+transport = MCP::Server::Transports::StdioTransport.new(server)
+transport.open

data/exe/woods-mcp

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# MCP server for querying Woods extraction output.
+#
+# Usage:
+#   woods-mcp [INDEX_DIR]
+#   WOODS_DIR=/path/to/output woods-mcp
+#
+# Reads JSON files from the extraction output directory and exposes
+# them via the Model Context Protocol (stdio transport).
+# Does NOT require Rails — only reads pre-extracted data.
+
+require_relative '../lib/woods'
+require_relative '../lib/woods/dependency_graph'
+require_relative '../lib/woods/graph_analyzer'
+require_relative '../lib/woods/mcp/server'
+require_relative '../lib/woods/mcp/bootstrapper'
+require_relative '../lib/woods/embedding/text_preparer'
+require_relative '../lib/woods/embedding/indexer'
+
+index_dir = Woods::MCP::Bootstrapper.resolve_index_dir(ARGV)
+retriever = Woods::MCP::Bootstrapper.build_retriever
+snapshot_store = Woods::MCP::Bootstrapper.build_snapshot_store(index_dir)
+
+server = Woods::MCP::Server.build(index_dir: index_dir, retriever: retriever, snapshot_store: snapshot_store)
+
+# Pin protocol version for broad client compatibility (Claude Code, Cursor, etc.)
+if ENV['MCP_PROTOCOL_VERSION']
+  server.configuration = MCP::Configuration.new(protocol_version: ENV['MCP_PROTOCOL_VERSION'])
+end
+
+transport = MCP::Server::Transports::StdioTransport.new(server)
+transport.open

data/exe/woods-mcp-http

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# MCP server for querying Woods extraction output over HTTP.
+#
+# Usage:
+#   woods-mcp-http [INDEX_DIR]
+#   WOODS_DIR=/path/to/output woods-mcp-http
+#
+# Reads JSON files from the extraction output directory and exposes
+# them via the Model Context Protocol (Streamable HTTP transport).
+# Requires the `rackup` gem and a Rack-compatible server (e.g., puma).
+
+require 'rackup'
+require_relative '../lib/woods'
+require_relative '../lib/woods/dependency_graph'
+require_relative '../lib/woods/graph_analyzer'
+require_relative '../lib/woods/mcp/server'
+require_relative '../lib/woods/mcp/bootstrapper'
+require_relative '../lib/woods/embedding/text_preparer'
+require_relative '../lib/woods/embedding/indexer'
+
+index_dir = Woods::MCP::Bootstrapper.resolve_index_dir(ARGV)
+retriever = Woods::MCP::Bootstrapper.build_retriever
+snapshot_store = Woods::MCP::Bootstrapper.build_snapshot_store(index_dir)
+
+port = (ENV['PORT'] || 9292).to_i
+host = ENV['HOST'] || 'localhost'
+
+server = Woods::MCP::Server.build(index_dir: index_dir, retriever: retriever, snapshot_store: snapshot_store)
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
+server.transport = transport
+
+app = proc { |env| transport.handle_request(Rack::Request.new(env)) }
+
+warn "Woods MCP HTTP server starting on http://#{host}:#{port}"
+Rackup::Handler.default.run(app, Port: port, Host: host)

data/exe/woods-mcp-start

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Self-healing wrapper for the Woods MCP server.
+# Ensures Ruby dependencies are installed, validates the index directory,
+# and starts the stdio MCP server.
+#
+# Usage (direct):
+#   woods-mcp-start /path/to/index_dir
+#
+# Usage (.mcp.json):
+#   {
+#     "command": "${HOME}/work/codebase_index/exe/woods-mcp-start",
+#     "args": ["${HOME}/my-rails-app/tmp/woods"]
+#   }
+#
+# All diagnostic output goes to stderr to keep stdio clean for MCP protocol.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+GEM_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+INDEX_DIR="${1:-${WOODS_DIR:-}}"
+
+# --- Validate index directory ---
+if [[ -z "$INDEX_DIR" ]]; then
+  echo "Error: No index directory specified." >&2
+  echo "Usage: woods-mcp-start /path/to/index_dir" >&2
+  exit 1
+fi
+
+if [[ ! -d "$INDEX_DIR" ]]; then
+  echo "Error: Index directory does not exist: $INDEX_DIR" >&2
+  echo "Run extraction first: bundle exec rake woods:extract" >&2
+  exit 1
+fi
+
+if [[ ! -f "$INDEX_DIR/manifest.json" ]]; then
+  echo "Error: No manifest.json in: $INDEX_DIR" >&2
+  echo "Run extraction first: bundle exec rake woods:extract" >&2
+  exit 1
+fi
+
+# --- Ensure Ruby dependencies are installed ---
+export BUNDLE_GEMFILE="${GEM_DIR}/Gemfile"
+
+if ! bundle check > /dev/null 2>&1; then
+  echo "Installing woods dependencies..." >&2
+  if ! bundle install --quiet >&2 2>&1; then
+    echo "Error: bundle install failed. Check Ruby version and network." >&2
+    exit 1
+  fi
+  echo "Dependencies installed." >&2
+fi
+
+# --- Pin MCP protocol version for Claude Code compatibility ---
+export MCP_PROTOCOL_VERSION="${MCP_PROTOCOL_VERSION:-2024-11-05}"
+
+# --- Start the MCP server ---
+exec bundle exec ruby "${GEM_DIR}/exe/woods-mcp" "$INDEX_DIR"

data/lib/generators/woods/install_generator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module Woods
+  module Generators
+    # Rails generator that creates a migration for Woods tables.
+    #
+    # Usage:
+    #   rails generate woods:install
+    #
+    # Creates a migration with woods_units, woods_edges, and
+    # woods_embeddings tables. Works with PostgreSQL, MySQL, and SQLite.
+    #
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates a migration for Woods tables (units, edges, embeddings)'
+
+      # @return [void]
+      def create_migration_file
+        migration_template(
+          'create_woods_tables.rb.erb',
+          'db/migrate/create_woods_tables.rb'
+        )
+      end
+    end
+  end
+end

data/lib/generators/woods/pgvector_generator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module Woods
+  module Generators
+    # Rails generator that adds pgvector support to Woods.
+    #
+    # Requires the pgvector PostgreSQL extension. Adds a native vector column
+    # and HNSW index to the woods_embeddings table.
+    #
+    # Usage:
+    #   rails generate woods:pgvector
+    #   rails generate woods:pgvector --dimensions 3072
+    #
+    class PgvectorGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Adds pgvector native vector column and HNSW index to woods_embeddings'
+
+      class_option :dimensions, type: :numeric, default: 1536,
+                                desc: 'Vector dimensions (1536 for text-embedding-3-small, 3072 for large)'
+
+      # @return [void]
+      def create_migration_file
+        @dimensions = options[:dimensions]
+        migration_template(
+          'add_pgvector_to_woods.rb.erb',
+          'db/migrate/add_pgvector_to_woods.rb'
+        )
+      end
+    end
+  end
+end

data/lib/generators/woods/templates/add_pgvector_to_woods.rb.erb

@@ -0,0 +1,15 @@
+class AddPgvectorToWoods < ActiveRecord::Migration[7.0]
+  def change
+    enable_extension 'vector' unless extension_enabled?('vector')
+
+    add_column :woods_embeddings, :embedding_vector, :vector,
+               limit: <%= @dimensions || 1536 %>, null: true
+
+    # HNSW index for fast approximate nearest neighbor search
+    # Using cosine distance operator (vector_cosine_ops)
+    add_index :woods_embeddings, :embedding_vector,
+              using: :hnsw,
+              opclass: :vector_cosine_ops,
+              name: 'idx_woods_embeddings_vector_hnsw'
+  end
+end

data/lib/generators/woods/templates/create_woods_tables.rb.erb

@@ -0,0 +1,43 @@
+class CreateWoodsTables < ActiveRecord::Migration[7.0]
+  def change
+    create_table :woods_units do |t|
+      t.string :unit_type, null: false
+      t.string :identifier, null: false
+      t.string :namespace
+      t.string :file_path, null: false
+      t.text :source_code
+      t.string :source_hash
+      t.json :metadata
+
+      t.timestamps
+    end
+
+    add_index :woods_units, :unit_type
+    add_index :woods_units, :identifier, unique: true
+    add_index :woods_units, :file_path
+
+    create_table :woods_edges do |t|
+      t.references :source, null: false, foreign_key: { to_table: :woods_units }
+      t.references :target, null: false, foreign_key: { to_table: :woods_units }
+      t.string :relationship, null: false
+      t.string :via
+
+      t.datetime :created_at, null: false
+    end
+
+    add_index :woods_edges, [:source_id, :target_id, :relationship], unique: true,
+              name: 'idx_woods_edges_unique'
+
+    create_table :woods_embeddings do |t|
+      t.references :unit, null: false, foreign_key: { to_table: :woods_units }
+      t.string :chunk_type
+      t.text :embedding, null: false
+      t.string :content_hash, null: false
+      t.integer :dimensions, null: false
+
+      t.datetime :created_at, null: false
+    end
+
+    add_index :woods_embeddings, :content_hash
+  end
+end