woods 1.5.0 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6be4722cd45cc31537b12abfe0dfc48e211aeffc4cc5ff9d0a378b3c2130eb1d
-  data.tar.gz: ba720873764980d05cb85a8598218e7061fbad8df5a9f29fb091cface39dd500
+  metadata.gz: 4a3bf50a7ad421cc52a336375446c4e08c2583dbf2ce96e4a3038bd8dca7a0ae
+  data.tar.gz: fe9a6512787372c3f3d0cbe4038720f123349b9961c548b1584d21b8b4cbd0fb
 SHA512:
-  metadata.gz: 0273f5abb61b0cdf7ba2ee95bdc8632a7e31f717d2eb039ddea18f21085bd83dd5c158497c693ccdc59e5d480be1162629fcd3324b7a9457e607d91183c4a5dc
-  data.tar.gz: fa24e32b452eb7c9f3a64267f7c1cd45149e9211611ef87432ec6ce82ca9f2955813bfe778f76cf1003daf2e0cdbf76e3b6590067f1c5fa7cf8a93ff482a0aed
+  metadata.gz: 7070f985d4a9bab191593599e4f4f8c807d0378c8345a9aa8a73c2ac4de0200b7959ffd6bb6a823bb12fd67a4afe90ad6d3475eb16bbb60ac320ead1de114b77
+  data.tar.gz: 3c0cd27167baa9cd7e0245894527760e12bf2d038e57819ffa78468e6f0e6e4122dd144129bcfd769bd89965caad7c997299dfc5de9c1c38dfddb88bab8f2f78

data/CHANGELOG.md

@@ -7,6 +7,177 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.1] - 2026-07-22
+
+### Fixed
+
+- **Incremental extraction crash on multi-unit files.** `woods:incremental` raised
+  `NoMethodError: undefined method 'identifier' for an instance of Array` when re-extracting a
+  unit whose extractor returns several units from one file (a `.rake` file defining multiple
+  tasks; i18n, migration, and lib files are shaped the same way). `Extractor#re_extract_unit`
+  now normalizes the extractor result to an array and registers and writes each unit, matching
+  how full extraction already handles per-type results. Full extraction was unaffected.
+
+## [1.6.0] - 2026-07-16
+
+### Added
+
+- **MCP update awareness.** A new `Woods::UpdateCheck` module performs a best-effort,
+  24h-cached RubyGems lookup for a newer `woods` release (disable with
+  `WOODS_NO_UPDATE_CHECK=1`). The Index Server's `woods_status` tool now reports
+  `server.update` (`current_version` / `latest_version` / `update_available`), and a call to a
+  tool the installed gem doesn't define now returns version-aware guidance ("not available in
+  the installed Woods vX — run `bundle update woods`") instead of a bare "Tool not found". This
+  keeps agents that follow a newer guide skill from silently failing against an older gem.
+- **Claude Code plugin.** The three user-facing guide skills (`woods-setup`,
+  `woods-mcp-config`, `woods-diagnose`) are now packaged as the `woods-plugin`, distributed
+  from the [`lost-in-the/plugins`](https://github.com/lost-in-the/plugins) marketplace suite
+  via a `git-subdir` source (installs fetch only the `plugin/` subtree, not the whole gem).
+  Install with `/plugin marketplace add lost-in-the/plugins` then
+  `/plugin install woods-plugin@lost-in-the-plugins`. Each skill gained a **Version Preflight**
+  step so agents operate only against the installed Woods version (≥ 1.5.0) instead of
+  suggesting tools or tasks an older gem lacks.
+
+### Changed
+
+- The user-facing guide skills moved from `docs/skills/` to `plugin/skills/` to form a valid
+  Claude Code plugin root (`plugin/.claude-plugin/plugin.json`). In-repo dev-workflow skills
+  under `.claude/skills/` are unaffected and remain undistributed.
+
+### Security
+
+- **Console `sample`/`recent` tools now validate `columns` against the model's
+  real columns.** They passed the raw array to ActiveRecord's `.select`, which
+  treats string args as SQL fragments — a crafted column could smuggle a
+  subquery into the SELECT list, bypassing TableGate and column redaction
+  (`pluck` already validated; `sample`/`recent` didn't).
+- **`trace_flow` sanitizes the entry point before building the flow file path.**
+  Only `::`→`__` was applied, so `/` and `..` in a client-supplied entry point
+  could traverse outside the `flows/` directory (a file-read oracle over the
+  HTTP transport). Both path segments now go through the `FilenameUtils`
+  allow-list.
+- **TableGate's SQL table detector no longer misses tables on PostgreSQL.** It
+  hardcoded MySQL literal-stripping, so on PostgreSQL (`standard_conforming_strings`)
+  the MySQL `\'` rule could over-strip and swallow a real `FROM <blocked>`
+  clause. It now strips under both dialects and unions the identifiers.
+- **TableGate no longer misses a table hidden behind a comment marker inside a
+  string literal.** `SqlNoiseStripper` stripped comments *before* literals, so
+  `SELECT '-- ' FROM blocked` had its real `FROM blocked` swallowed as a line
+  comment and slipped past the gate. Comment- and literal-stripping now run in a
+  single combined left-to-right pass (`SqlNoiseStripper.strip_noise`) — a
+  comment marker inside a literal, and a quote inside a comment, are each
+  protected by whichever opens first. `SqlValidator` and the scope-template
+  guard route through the same pass.
+- **`EvalGuard` rejects `%x` shell literals with any delimiter — including
+  whitespace.** The delimiter check excluded `\s`, but a newline is a valid `%x`
+  delimiter (`%x\ncmd\n` compiles and executes), so it slipped through to
+  `instance_eval`. The check now matches any non-word delimiter (`[^\w]`).
+- **`PipelineLock` no longer allows two processes to hold the lock.** Both the
+  stale-lock takeover and the release path had TOCTOU windows: a process that
+  passed the staleness check could rename away — or a plain read-then-unlink
+  release could delete — a competitor's *fresh* lock, so both would "hold" it.
+  Takeover now re-verifies the retired file is still stale (restoring it and
+  backing off if a competitor already took over), and release renames the file
+  aside and re-checks its ownership token before deleting.
+
+### Fixed
+
+- **Incremental extraction no longer corrupts the index.** `rake woods:incremental`
+  overwrote `manifest.json` with zero counts, captured an empty temporal snapshot
+  (making the diff report every unit as deleted), wrote absolute file paths into
+  the index, and re-indexed affected units with a null `estimated_tokens`.
+- **Retrieval ranking signals work on real backends again.** Recency, importance,
+  type-match, and diversity read metadata with symbol keys, but every store
+  returns string keys — so all four scored every unit at their neutral fallback
+  in production. The ranker now reads both key forms.
+- **The embedding cache is now scoped to the provider model.** The cache key was
+  `SHA256(text)` with no model, so a persistent shared backend served the
+  previous model's vector after a model switch. `model_name` is now part of the
+  key — a plain attribute rather than `dimensions`, whose Ollama implementation
+  is a live `embed('test')` probe (keying on it made every cache lookup, hits
+  included, depend on the provider being reachable, and defeated the cache while
+  the backend was down).
+- **`callback_count` reports real counts.** It called the nonexistent
+  `CallbackChain#size`, which raised and left the count silently at 0 for every
+  model; switched to `#count`.
+- **`ResolvedConfig` is now deeply immutable.** Nested strings in
+  `embedding_provider`/`stores` stayed mutable, so the frozen snapshot could be
+  corrupted in place.
+- **Model dependency edges are correct for nested and re-registered units.** The
+  `ModelNameCache` alternation matched a prefixed parent (`Library::Book` for
+  `Library::Book::Chapter`); `DependencyGraph#register` left stale reverse edges
+  on re-registration, inflating incremental blast radius.
+- **Precomputed request flows are no longer empty/stale.** `FlowPrecomputer` ran
+  before unit JSON was written to disk; it now runs after `write_results`.
+- **`trace_flow` resolves precomputed flows again.** The reader allow-listed the
+  entry point but the writer left the action name raw, so a flow for an action
+  outside `[A-Za-z0-9_-]` was written under one filename and looked up under
+  another (silently falling back to live assembly). Both sides now derive the
+  filename from the shared `FilenameUtils.flow_filename`.
+- **Flow annotation no longer resurrects deleted units.** On a full extraction
+  with `precompute_flows`, refreshing a type's `_index.json` rebuilt it from a
+  disk glob of the never-wiped output dir, re-adding unit files for classes
+  deleted from the app since the last run. The index is now rebuilt from the
+  in-memory `@results` (the incremental path, which only holds changed units,
+  still rebuilds from disk).
+- **`FlowAssembler` no longer reports DAG diamonds as cycles**, and
+  `IndexArtifact#promote` no longer accepts sibling directories that merely
+  share a name prefix with `dumps/`.
+- **`implicit_belongs_to` metadata is accurate.** It was flagged on every
+  ActiveRecord presence validator; it now keys on `belongs_to` reflections.
+- **Dependency scanning ignores commented references consistently** across all
+  three passes (a commented `Library::Book` still produced a ghost edge), while
+  keeping references that follow a `#` *inside a string literal* (`link_to "Tag
+  #ruby", Article.recent`). Comment-stripping is string-literal-aware — a plain
+  `#…` regex ate the rest of such lines and dropped the real edge.
+- **`pipeline_extract(incremental: true)` requires `changed_files`** instead of
+  silently re-extracting nothing while reporting success.
+- **`pipeline_diagnose` classifies by the supplied error class** (it built a bare
+  `StandardError`, so every `Timeout`/`Net::`/`Errno` error came back
+  `:unknown`).
+- **`notion_sync` honors the `NOTION_API_TOKEN` env var**, matching the gate that
+  registers the tool (ENV-only hosts previously saw the tool but every call
+  failed). A *blank* env var (docker-compose `${NOTION_API_TOKEN}` interpolation
+  of an unset host variable) is now treated as absent rather than masking a
+  configured token or passing through as a blank bearer. All four resolution
+  sites (exporter, `notion_wired?` gate, tool handler, rake task) share
+  `Woods.resolve_notion_token`.
+- **Embedded documents include the `dependencies:` line again** — the indexer
+  leaves dependency hashes string-keyed and the text preparer only read symbol
+  keys.
+- The MCP CLI integration spec no longer fails under a POSIX/C locale (UTF-8
+  subprocess output is normalized before regex matching).
+- **`CircuitBreaker` admits only a single probe in `half_open`.** It let every
+  concurrent call through while half-open (a thundering herd against a
+  recovering service), and a slow probe's success could wipe failures recorded
+  by an overlapping probe. Concurrent probes are now rejected with
+  `CircuitOpenError`, and an optional `success_threshold` requires N consecutive
+  successful probes to close (default 1). Recovery accounting is also keyed to
+  the per-call probe flag, not the shared state: a stale call admitted while the
+  circuit was *closed* that completes after the transition to `half_open` no
+  longer counts as the probe (it could otherwise close the circuit — or clear a
+  concurrent probe's slot — while the service was still down).
+- **`Retry-After` honors the HTTP-date form.** The Notion and Unblocked clients
+  parsed the header with `.to_f`, turning an HTTP-date into `0.0` and retrying
+  immediately against a throttling server. A shared `Woods::RetryAfter` helper
+  now handles both the delta-seconds and HTTP-date forms.
+- **The MCP pipeline lock is no longer racy under the HTTP transport.** The
+  `@pipeline_mutex ||= Mutex.new` lazy init let two concurrent handlers create
+  separate mutexes and run two pipelines of the same kind; the mutex is now
+  eagerly initialized.
+
+### Changed
+
+- Directory globbing and dependency deduplication across the extractor fleet are
+  centralized in `SharedUtilityMethods#find_files_in_directories` and
+  `SharedDependencyScanner#consolidate_dependencies` (behavior-preserving).
+
+### Documentation
+
+- Added an in-container Index Server section to `DOCKER_SETUP.md` (#139),
+  corrected stale tool counts, corrected backend config examples that referenced
+  nonexistent adapters (#83), and listed the previously-undocumented rake tasks.
+
 ## [1.5.0] - 2026-06-23
 
 ### Added

data/CONTRIBUTING.md

@@ -28,7 +28,36 @@ Open an issue describing:
 5. Ensure the test suite passes: `bundle exec rake spec`
 6. Ensure code style passes: `bundle exec rubocop`
 7. Update CHANGELOG.md with your changes
-8. Open a pull request
+8. Complete the **Pre-PR requirements** below
+9. Open a pull request
+
+### Pre-PR requirements
+
+These are hard gates — a PR that fails either is incomplete:
+
+1. **Documentation must be current.** Any doc affected by the change — README, `docs/`, the
+   `plugin/skills/` user guides, `CHANGELOG.md` — must be updated in the *same* PR. Don't ship
+   behavior the docs still describe the old way.
+2. **Investigate plugin-functionality impact.** If the change touches anything the distributed
+   user skills rely on — a rake task, MCP tool or its arguments, an executable (`woods-mcp`,
+   `woods-mcp-start`, `woods-console-mcp`, `woods-mcp-http`), a config key, or setup steps —
+   investigate whether `plugin/skills/{woods-setup,woods-mcp-config,woods-diagnose}` need to
+   change.
+
+### Claude Code plugin changes
+
+`plugin/` is distributed as the `woods-plugin` via the
+[`lost-in-the/plugins`](https://github.com/lost-in-the/plugins) marketplace (a `git-subdir`
+reference to this subtree). Installed users may run an **older** gem than `main`, so:
+
+- If a change adds/removes/renames a tool, task, executable, or config key that a skill
+  documents, **update the skill in the same PR**.
+- The skills carry a Version Preflight (operate only against the installed version). **Land the
+  skill change with the release that ships the capability** — never document a feature in a
+  skill before the version that provides it is released. Bump `plugin/.claude-plugin/plugin.json`
+  `version` when the skill content changes.
+- If the change requires a new marketplace entry, `ref` pin, or metadata edit, open a **paired
+  PR against `lost-in-the/plugins`** and link it from this PR.
 
 ## Development Setup
 

data/README.md

@@ -249,6 +249,31 @@ Static tools miss `status_active?`, `status_pending?`, `build_line_item`, `creat
 
 ---
 
+## Claude Code plugin
+
+Woods publishes three **user-facing guide skills** as a Claude Code plugin so agents can walk
+you through setup, MCP configuration, and troubleshooting without leaving your editor:
+
+- `woods-setup` — install, configure, extract, verify, connect MCP servers
+- `woods-mcp-config` — generate a correct `.mcp.json` for your environment
+- `woods-diagnose` — systematic troubleshooting for extraction/MCP/embedding/storage
+
+The plugin ships from the [`lost-in-the/plugins`](https://github.com/lost-in-the/plugins)
+marketplace suite, which references this repo's `plugin/` subtree via a `git-subdir` source —
+so installing fetches only the skill files, not the whole gem:
+
+```bash
+# In Claude Code:
+/plugin marketplace add lost-in-the/plugins
+/plugin install woods-plugin@lost-in-the-plugins
+```
+
+The skill files live in this repo under [`plugin/skills/`](plugin/skills/) (the plugin root is
+[`plugin/`](plugin/), with its manifest at `plugin/.claude-plugin/plugin.json`). Each skill
+opens with a Version Preflight so agents operate only against your installed Woods version. To
+test a local checkout: `claude --plugin-dir /path/to/woods/plugin`. Requires **Woods ≥ 1.5.0**.
+The internal dev-workflow skills under `.claude/skills/` are **not** part of this plugin.
+
 ## Connect to Your AI Tool
 
 Woods ships two MCP servers. Most users only need the **Index Server**.
@@ -448,8 +473,14 @@ rake woods:clean               # Remove index output (alias: woods:clear)
 rake woods:embed               # Embed units for semantic search (alias: woods:nest)
 rake woods:embed_incremental   # Embed changed units only (alias: woods:hone)
 rake woods:notion_sync         # Sync models/columns to Notion (alias: woods:send)
+rake woods:obsidian            # Export to an Obsidian vault — graph view + Bases (alias: woods:vault)
 ```
 
+> **Visualize connections in Obsidian.** `woods:obsidian` renders the codebase as a self-contained
+> [Obsidian](https://obsidian.md) vault: one interlinked note per unit (explore the dependency graph
+> in graph view), a filterable [Bases](https://help.obsidian.md/bases) table, and a `_woods/` machine
+> sidecar so agents can load the whole topology in one read. See [Obsidian Integration](docs/OBSIDIAN_INTEGRATION.md).
+
 ---
 
 ## How It Works Under the Hood

data/lib/tasks/woods.rake

@@ -534,8 +534,10 @@ namespace :woods do
     require 'woods/notion/exporter'
 
     config = Woods.configuration
-    # Env var takes precedence over configured value
-    config.notion_api_token = ENV.fetch('NOTION_API_TOKEN', nil) || config.notion_api_token
+    # A non-blank env var takes precedence over the configured value; a blank
+    # NOTION_API_TOKEN is treated as absent. Shared resolution keeps the rake
+    # task, the exporter, and the MCP tool consistent.
+    config.notion_api_token = Woods.resolve_notion_token(config)
 
     unless config.notion_api_token
       puts 'ERROR: Notion API token not configured.'
@@ -650,6 +652,54 @@ namespace :woods do
   desc 'Relay findings to Unblocked (alias for unblocked_sync)'
   task relay: :unblocked_sync
 
+  desc 'Export extraction data to a self-contained Obsidian vault'
+  task obsidian: :environment do
+    require 'woods/obsidian/vault_exporter'
+
+    config = Woods.configuration
+    output_dir = ENV.fetch('WOODS_OUTPUT', config.output_dir)
+    vault_path = ENV.fetch('WOODS_OBSIDIAN_VAULT', File.join(output_dir.to_s, 'obsidian_vault'))
+    # Truthy set, so FLAG=false / FLAG=0 disables rather than silently enabling.
+    env_flag = ->(name) { %w[1 true yes].include?(ENV.fetch(name, '').strip.downcase) }
+
+    puts 'Exporting extraction data to an Obsidian vault...'
+    puts "  Output dir: #{output_dir}"
+    puts "  Vault:      #{vault_path}"
+    puts
+
+    begin
+      exporter = Woods::Obsidian::VaultExporter.new(
+        index_dir: output_dir,
+        vault_path: vault_path,
+        include_source: env_flag.call('WOODS_OBSIDIAN_INCLUDE_SOURCE'),
+        include_framework: env_flag.call('WOODS_OBSIDIAN_INCLUDE_FRAMEWORK'),
+        force_purge: env_flag.call('WOODS_OBSIDIAN_FORCE_PURGE')
+      )
+      stats = exporter.export_all
+    rescue Woods::Obsidian::ExportError => e
+      puts "ERROR: #{e.message}"
+      exit 1
+    end
+
+    puts 'Export complete!'
+    puts "  Notes:    #{stats[:exported]}"
+    puts "  Indexes:  #{stats[:indexes]}"
+    puts "  Swept:    #{stats[:swept]}"
+    puts "  Skipped:  #{stats[:skipped]}"
+    puts
+    puts "Open it in Obsidian: 'Open folder as vault' -> #{vault_path}"
+
+    if stats[:errors].any?
+      puts "  Errors:   #{stats[:errors].size}"
+      stats[:errors].first(5).each { |e| puts "    - #{e}" }
+      puts "    ... and #{stats[:errors].size - 5} more" if stats[:errors].size > 5
+      exit 1
+    end
+  end
+
+  desc 'Render the codebase as an Obsidian vault (alias for obsidian)'
+  task vault: :obsidian
+
   desc 'Generate a random bearer token for woods-mcp-http (WOODS_MCP_HTTP_TOKEN)'
   task :generate_token do
     require 'securerandom'

data/lib/woods/atomic_file.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tempfile'
+
+module Woods
+  # Crash-safe file writes via a temp file + atomic rename.
+  #
+  # Extracted from the pattern in {Woods::IndexArtifact} (whose own
+  # +atomic_write+ is private and instance-level) so any component that writes
+  # many files — e.g. the Obsidian exporter writing a vault of notes — can reuse
+  # it. If the process dies mid-write, the destination file is either the old
+  # content or the new content, never a torn partial.
+  #
+  # @example
+  #   Woods::AtomicFile.write("tmp/woods/obsidian_vault/models/User.md", note_body)
+  module AtomicFile
+    module_function
+
+    # Atomically write +content+ to +path+, creating parent directories.
+    #
+    # @param path [String, Pathname] destination path
+    # @param content [String] file content
+    # @return [void]
+    def write(path, content)
+      path = path.to_s
+      FileUtils.mkdir_p(File.dirname(path))
+      tmp = Tempfile.new('.woods-', File.dirname(path))
+      # Binary mode so the content's bytes (e.g. UTF-8) are written verbatim
+      # regardless of the process's default external encoding.
+      tmp.binmode
+      tmp.write(content)
+      tmp.flush
+      tmp.fsync
+      tmp.close
+      File.rename(tmp.path, path)
+    rescue StandardError
+      tmp&.close
+      tmp&.unlink
+      raise
+    end
+  end
+end

data/lib/woods/cache/cache_middleware.rb

@@ -359,10 +359,27 @@ module Woods
 
       # Build a cache key for an embedding text.
       #
+      # The provider's model_name is folded into the key: a cached embedding
+      # is only valid for the exact model that produced it. Without this, a
+      # persistent shared backend (Redis/SolidCache) returns the previous
+      # model's vector after a model switch or upgrade — different dimensions
+      # error mid-batch, same dimensions silently corrupt similarity scores
+      # (which IndexValidator can't detect, since it checks provider-vs-store
+      # dims, not cache contents).
+      #
+      # model_name (a plain attribute) is used rather than dimensions on
+      # purpose: for every supported provider the model uniquely determines
+      # the vector dimensionality, and `Provider#dimensions` can force a live
+      # network probe (Ollama memoizes `embed('test').length`; OpenAI probes
+      # for unknown models). Keying on dimensions made every cache lookup —
+      # including hits — depend on the provider being reachable, defeating the
+      # cache exactly when the backend is down. model_name distinguishes
+      # models without any I/O.
+      #
       # @param text [String]
       # @return [String]
       def embedding_key(text)
-        Cache.cache_key(:embeddings, Digest::SHA256.hexdigest(text))
+        Cache.cache_key(:embeddings, @provider.model_name.to_s, Digest::SHA256.hexdigest(text))
       end
     end
 

data/lib/woods/console/embedded_executor.rb

@@ -458,6 +458,7 @@ module Woods
       end
 
       def handle_sample(params)
+        validate_select_columns!(params)
         model = resolve_model(params['model'])
         limit = [params.fetch('limit', 5).to_i, 25].min
         scope = apply_scope(model, params['scope'], model_name: params['model'])
@@ -563,6 +564,7 @@ module Woods
       end
 
       def handle_recent(params)
+        validate_select_columns!(params)
         model = resolve_model(params['model'])
         order_by = params.fetch('order_by', 'created_at')
         direction = params.fetch('direction', 'desc')
@@ -903,8 +905,10 @@ module Woods
         # instead of a confusing adapter-level syntax failure. It also
         # neutralises `--` line comments and PostgreSQL dollar-quoted
         # strings that could carry forbidden keywords past a naive scan.
-        # `SqlNoiseStripper` is the same module SqlValidator uses.
-        stripped = SqlNoiseStripper.strip_literals(SqlNoiseStripper.strip_comments(template))
+        # `SqlNoiseStripper` is the same module SqlValidator uses. The
+        # combined single-pass strip_noise resolves comments and literals
+        # together so a comment marker inside a literal can't hide a keyword.
+        stripped = SqlNoiseStripper.strip_noise(template)
         if SCOPE_TEMPLATE_FORBIDDEN.match?(stripped)
           raise ValidationError,
                 'scope template contains forbidden SQL keywords ' \
@@ -928,6 +932,20 @@ module Woods
         scope.any? { |k, _| ScopePredicateParser::SUFFIX_PATTERN.match?(k.to_s) }
       end
 
+      # Validate that any requested +columns+ are real model columns before
+      # they reach +apply_columns+. ActiveRecord treats string args to
+      # +.select+ as raw SQL fragments, so an unvalidated column smuggles a
+      # subquery into the SELECT list (the sample/recent tools skip
+      # +check_sql!+, so this is their only gate). Mirrors +handle_pluck+.
+      #
+      # @param params [Hash] Tool params (uses 'model' and 'columns')
+      # @raise [ArgumentError] if any column is not declared on the model
+      def validate_select_columns!(params)
+        return unless params['columns']
+
+        @model_validator.validate_columns!(params['model'], params['columns'])
+      end
+
       # Apply column selection to a relation.
       #
       # @param relation [ActiveRecord::Relation] The relation

data/lib/woods/console/eval_guard.rb

@@ -194,8 +194,14 @@ module Woods
         # `%x{cmd}`) — the AST flavor of these is `:xstr`/`:xstr_heredoc`,
         # which {Woods::Ast::Parser} may normalize differently across
         # Prism/parser-gem backends. A source-level refusal is both cheap
-        # and impossible to evade via AST normalization.
-        if code.include?('`') || code =~ /%x[{<|!@#(\[]/
+        # and impossible to evade via AST normalization. Ruby accepts ANY
+        # non-word character as the %x delimiter — including whitespace:
+        # `%x\ncmd\n` (newline-delimited) is valid and executes. Match
+        # every non-word char (`[^\w]`, which spans newline/space/tab, not
+        # `[^\w\s]` which excluded them and let `%x\n…` slip through). As a
+        # fail-safe, over-refusing odd-but-harmless source beats letting an
+        # unlisted delimiter through.
+        if code.include?('`') || code =~ /%x[^\w]/
           raise ForbiddenExpressionError, 'payload contains a shell-execution literal (backtick or %x)'
         end
 

data/lib/woods/console/sql_noise_stripper.rb

@@ -82,6 +82,119 @@ module Woods
         pattern = dialect == :mysql ? SINGLE_QUOTED_MYSQL : SINGLE_QUOTED_POSTGRES
         out.gsub(pattern, "''")
       end
+
+      # Strip BOTH comments and string literals in a single left-to-right
+      # pass, so a comment marker inside a literal and a quote inside a
+      # comment are each protected by whichever construct opens first.
+      #
+      # Running {.strip_comments} then {.strip_literals} (or vice versa) is
+      # unsafe: `SELECT '-- ' FROM blocked` has its real `FROM blocked`
+      # swallowed as a line comment (the `--` sits inside a string literal),
+      # letting a blocked table slip past {TableGate}; the reverse order
+      # mis-handles an apostrophe inside a `--` comment. Only a combined scan
+      # that tracks literal/comment state correctly resolves both. This
+      # scanner backs security checks (SqlValidator, TableGate) so it must
+      # never under-detect: an unterminated literal is treated as an ordinary
+      # character rather than swallowing the rest of the statement.
+      #
+      # @param sql [String] the SQL string to process
+      # @param dialect [Symbol] `:postgres` (default) or `:mysql` — controls
+      #   single-quote escape rules (see {.strip_literals}).
+      # @return [String] a new string with comments removed and every string
+      #   literal replaced by `''`
+      # @raise [ArgumentError] if an unsupported dialect is provided
+      def self.strip_noise(sql, dialect: :postgres) # rubocop:disable Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity,Metrics/AbcSize
+        unless SUPPORTED_DIALECTS.include?(dialect)
+          raise ArgumentError, "Unknown dialect #{dialect.inspect}. Supported: #{SUPPORTED_DIALECTS.inspect}"
+        end
+
+        mysql = dialect == :mysql
+        out = +''
+        i = 0
+        len = sql.length
+
+        while i < len
+          ch = sql[i]
+
+          if ch == "'"
+            close = single_quote_end(sql, i, mysql: mysql)
+            if close
+              out << "''"
+              i = close
+            else
+              # Unterminated literal — never under-detect; keep the char.
+              out << ch
+              i += 1
+            end
+          elsif ch == '$' && (tag = dollar_tag_at(sql, i))
+            close = sql.index(tag, i + tag.length)
+            if close
+              out << "''"
+              i = close + tag.length
+            else
+              out << ch
+              i += 1
+            end
+          elsif ch == '-' && sql[i + 1] == '-'
+            nl = sql.index("\n", i)
+            i = nl || len
+          elsif ch == '/' && sql[i + 1] == '*'
+            close = sql.index('*/', i + 2)
+            if close
+              i = close + 2
+            else
+              # Unterminated block comment: never under-detect. Leave it in
+              # place (over-detection is safe; the old regex also required a
+              # closing */ and left an unterminated /* untouched).
+              out << ch
+              i += 1
+            end
+          else
+            out << ch
+            i += 1
+          end
+        end
+
+        out
+      end
+
+      # Regexp matching a PostgreSQL dollar-quote opening tag (`$$` or
+      # `$tag$`) at the start of the given slice.
+      DOLLAR_TAG = /\A\$\w*\$/
+      private_constant :DOLLAR_TAG
+
+      # Return the dollar-quote tag opening at +index+, or nil.
+      #
+      # @api private
+      def self.dollar_tag_at(sql, index)
+        m = DOLLAR_TAG.match(sql[index..])
+        m && m[0]
+      end
+      private_class_method :dollar_tag_at
+
+      # Return the index just past the closing quote of the single-quoted
+      # literal that opens at +start+, honoring `''` (both dialects) and `\'`
+      # (MySQL only) escapes. Returns nil when the literal is unterminated.
+      #
+      # @api private
+      def self.single_quote_end(sql, start, mysql:)
+        i = start + 1
+        len = sql.length
+        while i < len
+          c = sql[i]
+          if mysql && c == '\\'
+            i += 2
+          elsif c == "'"
+            return i + 1 unless sql[i + 1] == "'" # closing quote
+
+            i += 2 # doubled-quote escape — literal continues
+          else
+            i += 1
+          end
+        end
+        nil
+      end
+      private_class_method :single_quote_end
     end
   end
 end

data/lib/woods/console/sql_table_scanner.rb

@@ -109,23 +109,36 @@ module Woods
       # stripped before scanning. Both JOIN-style and ANSI-89 comma-join syntax
       # are handled.
       #
+      # Literals are stripped under BOTH supported dialects and the scans
+      # unioned. This scanner backs TableGate, so it may over-detect but must
+      # never under-detect: stripping with the wrong dialect's escape rules
+      # can swallow a real FROM clause — e.g. MySQL's `\'` escape applied on
+      # a PostgreSQL host (where backslash is literal under
+      # standard_conforming_strings) folds `'x\' FROM blocked WHERE y = '`
+      # into one literal, hiding `blocked` from the gate while PostgreSQL
+      # genuinely reads that table.
+      #
       # @param sql [String, nil] the SQL string to scan
-      # @return [Array<String>] identifiers in the order they were encountered;
-      #   may contain duplicates if the same table is referenced multiple times
+      # @return [Array<String>] identifiers in first-encounter order, deduplicated
       def self.identifiers_in(sql)
         return [] if sql.nil? || sql.empty?
 
-        stripped = strip_noise(sql)
         results = []
-        collect_join_identifiers(stripped, results)
-        collect_from_identifiers(stripped, results)
-        results
+        %i[postgres mysql].each do |dialect|
+          stripped = strip_noise(sql, dialect: dialect)
+          collect_join_identifiers(stripped, results)
+          collect_from_identifiers(stripped, results)
+        end
+        results.uniq
       end
 
       # @api private
-      def self.strip_noise(sql)
-        out = SqlNoiseStripper.strip_comments(sql)
-        SqlNoiseStripper.strip_literals(out, dialect: :mysql)
+      # Comments and literals must be stripped in a single combined pass —
+      # stripping them separately lets a comment marker inside a literal
+      # (`'-- '`) hide a real FROM clause from the gate. See
+      # {SqlNoiseStripper.strip_noise}.
+      def self.strip_noise(sql, dialect:)
+        SqlNoiseStripper.strip_noise(sql, dialect: dialect)
       end
       private_class_method :strip_noise
 

data/lib/woods/console/sql_validator.rb

@@ -152,8 +152,7 @@ module Woods
       # @param sql [String]
       # @return [Boolean]
       def contains_multiple_statements?(sql)
-        stripped = SqlNoiseStripper.strip_comments(sql)
-        stripped = SqlNoiseStripper.strip_literals(stripped)
+        stripped = SqlNoiseStripper.strip_noise(sql)
         stripped.include?(';')
       end