na 1.2.94 → 1.2.96

data/lib/na/next_action.rb

@@ -3,6 +3,9 @@
 # Next Action methods
 module NA
   class << self
+    attr_accessor :verbose, :extension, :include_ext, :na_tag, :command_line, :command, :globals, :global_file,
+                  :cwd_is, :cwd, :stdin, :show_cwd_indicator
+
     # Select actions across files using existing search pipeline
     # @return [Array<NA::Action>]
     def select_actions(file: nil, depth: 1, search: [], tagged: [], include_done: false)
@@ -96,9 +99,6 @@ module NA
     end
     include NA::Editor
 
-    attr_accessor :verbose, :extension, :include_ext, :na_tag, :command_line, :command, :globals, :global_file,
-                  :cwd_is, :cwd, :stdin, :show_cwd_indicator
-
     # Returns the current theme hash for color and style settings.
     # @return [Hash] The theme settings
     def theme
@@ -902,7 +902,10 @@ module NA
       end}", debug: true)
 
       if require_last
-        dirs.delete_if { |d| !d.sub(/\.#{NA.extension}$/, '').dir_matches(any: optional, all: required, none: negated) }
+        dirs.delete_if do |d|
+          !d.sub(/\.#{NA.extension}$/, '')
+            .dir_matches?(any: optional, all: required, none: negated, require_last: true, distance: distance)
+        end
       else
         dirs.delete_if do |d|
           !d.sub(/\.#{NA.extension}$/, '')
@@ -1149,6 +1152,170 @@ module NA
       end
     end
 
+    # Resolve a TaskPaper-style item path (subset) into NA project paths.
+    #
+    # Supported subset:
+    #   - Child axis: /Project/Sub
+    #   - Descendant axis: //Sub (e.g. /Inbox//Bugs)
+    #   - Wildcard step: * (matches any project name in that position)
+    #
+    # @param path [String] TaskPaper-style item path (must start with '/')
+    # @param file [String, nil] Optional single file to resolve against
+    # @param depth [Integer] Directory search depth when no file is given
+    # @return [Array<String>] Array of project paths like "Inbox:New Videos"
+    def resolve_item_path(path:, file: nil, depth: 1)
+      return [] if path.nil?
+
+      steps = parse_item_path(path)
+      return [] if steps.empty?
+
+      files = if file
+                [File.expand_path(file)]
+              else
+                find_files(depth: depth)
+              end
+      return [] if files.nil? || files.empty?
+
+      matches = []
+
+      files.each do |f|
+        todo = NA::Todo.new(require_na: false, file_path: f)
+        projects = todo.projects
+        next if projects.empty?
+
+        current = resolve_path_in_projects(projects, steps)
+        current.each do |proj|
+          matches << proj.project
+        end
+      end
+
+      matches.uniq
+    end
+
+    # Parse a TaskPaper-style item path string into steps with axis and text.
+    # Returns an Array of Hashes: { axis: :child|:desc, text: String,
+    # wildcard: Boolean }.
+    def parse_item_path(path)
+      s = path.to_s.strip
+      return [] unless s.start_with?('/')
+
+      steps = []
+      i = 0
+      len = s.length
+
+      while i < len
+        break unless s[i] == '/'
+
+        axis = :child
+        if i + 1 < len && s[i + 1] == '/'
+          axis = :desc
+          i += 1
+        end
+        i += 1
+
+        text = +''
+        quote = nil
+
+        while i < len
+          ch = s[i]
+          if quote
+            text << ch
+            quote = nil if ch == quote
+            i += 1
+            next
+          end
+
+          if ch == '"' || ch == "'"
+            quote = ch
+            text << ch
+            i += 1
+            next
+          end
+
+          break if ch == '/'
+
+          text << ch
+          i += 1
+        end
+
+        t = text.strip
+        wildcard = t.empty? || t == '*'
+        steps << { axis: axis, text: t, wildcard: wildcard }
+      end
+
+      steps
+    end
+
+    # Resolve a parsed item path against a list of NA::Project objects from a
+    # single file.
+    #
+    # @param projects [Array<NA::Project>]
+    # @param steps [Array<Hash>] Parsed steps from parse_item_path
+    # @return [Array<NA::Project>] Matching projects (last step)
+    def resolve_path_in_projects(projects, steps)
+      return [] if steps.empty? || projects.empty?
+
+      # First step: from a virtual root; child axis means top-level projects
+      # (no ':' in path), descendant axis means any project in the file.
+      first = steps.first
+      current = []
+
+      projects.each do |proj|
+        case first[:axis]
+        when :child
+          next unless proj.project.split(':').length == 1
+        when :desc
+          # any project is a descendant of the virtual root
+        end
+
+        current << proj if item_path_step_match?(first, proj)
+      end
+
+      steps[1..].each do |step|
+        next_current = []
+        current.each do |parent|
+          parent_path = parent.project
+          parent_depth = parent_path.split(':').length
+          projects.each do |proj|
+            next if proj.equal?(parent)
+
+            case step[:axis]
+            when :child
+              next unless proj.project.start_with?("#{parent_path}:")
+              next unless proj.project.split(':').length == parent_depth + 1
+            when :desc
+              next unless proj.project.start_with?("#{parent_path}:")
+            end
+
+            next unless item_path_step_match?(step, proj)
+
+            next_current << proj
+            pp next_current.inspect
+          end
+        end
+        current = next_current.uniq
+        break if current.empty?
+      end
+
+      current
+    end
+
+    # Check if a project matches a single item-path step.
+    def item_path_step_match?(step, proj)
+      return true if step[:wildcard]
+
+      name = proj.project.split(':').last.to_s
+      txt = step[:text]
+      return false if txt.nil? || txt.empty?
+
+      if txt =~ /[*?]/
+        rx = Regexp.new(txt.wildcard_to_rx, Regexp::IGNORECASE)
+        !!(name =~ rx)
+      else
+        name.downcase.include?(txt.downcase)
+      end
+    end
+
     # List todo files matching a query.
     # @param query [Array] Query tokens
     # @return [void]
@@ -1188,6 +1355,643 @@ module NA
       NA.notify("#{NA.theme[:success]}Search #{NA.theme[:filename]}#{title}#{NA.theme[:success]} saved", exit_code: 0)
     end
 
+    # Parse a TaskPaper-style @search() expression into NA search components.
+    #
+    # TaskPaper expressions are of the form (subset of full syntax):
+    #   @search(@tag, @tag = 1, @tag contains 1, not @tag, project = "Name", not project = "Name", plain, "text")
+    #
+    # Supported operators (mapped from TaskPaper searches, see:
+    # https://guide.taskpaper.com/reference/searches/):
+    #   - boolean: and / not   (or/parentheses are not yet fully supported)
+    #   - @tag, not @tag
+    #   - @tag = VALUE, @tag > VALUE, @tag < VALUE, @tag >= VALUE, @tag <= VALUE, @tag =~ VALUE
+    #   - @tag contains VALUE, beginswith VALUE, endswith VALUE, matches VALUE
+    #   - @text REL VALUE  (treated as plain-text search on the line)
+    #   - project = "Name", not project = "Name"
+    #
+    # The result can be passed directly to NA::Todo via the returned clause
+    # hashes, which include keys :tokens, :tags, :project, :include_done, and
+    # :exclude_projects.
+    #
+    # @param expr [String] TaskPaper @search() expression or inner content
+    # @return [Hash] Parsed components for a single AND-joined clause
+    def parse_taskpaper_search(expr)
+      clauses = parse_taskpaper_search_clauses(expr)
+      clauses.first || { tokens: [], tags: [], project: nil, include_done: nil, exclude_projects: [] }
+    end
+
+    # Internal: parse a single (AND-joined) TaskPaper clause into search
+    # components.
+    #
+    # @param clause [String] Clause content with no surrounding @search()
+    # @param out [Hash] Accumulator hash (tokens/tags/project/etc.)
+    # @return [Hash] The same +out+ hash
+    def parse_taskpaper_search_clause(clause, out)
+      parts = clause.split(/\band\b/i).map(&:strip).reject(&:empty?)
+
+      parts.each do |raw_part|
+        part = raw_part.dup
+        neg = false
+
+        if part =~ /\Anot\s+(.+)\z/i
+          neg = true
+          part = Regexp.last_match(1).strip
+        end
+
+        # @tag, @tag OP VALUE, or @attribute OP VALUE
+        if part =~ /\A@([A-Za-z0-9_\-:.]+)\s*(?:(=|==|!=|>=|<=|>|<|=~|contains(?:\[[^\]]+\])?|beginswith(?:\[[^\]]+\])?|endswith(?:\[[^\]]+\])?|matches(?:\[[^\]]+\])?)\s*(.+))?\z/i
+          tag = Regexp.last_match(1)
+          op  = Regexp.last_match(2)
+          val = Regexp.last_match(3)&.strip
+          val = val[1..-2] if val && ((val.start_with?('"') && val.end_with?('"')) || (val.start_with?("'") && val.end_with?("'")))
+
+          # Handle @text as a plain-text predicate on the line
+          if tag.casecmp('text').zero?
+            if val
+              token_val = val
+              out[:tokens] << {
+                token: token_val,
+                required: !neg,
+                negate: neg
+              }
+            end
+            next
+          end
+
+          if tag.casecmp('done').zero?
+            # Handle done specially via :include_done; do NOT add a tag filter,
+            # otherwise Todo.parse would force include @done actions.
+            out[:include_done] = !neg
+            next
+          end
+
+          # Normalize operator: strip TaskPaper relation modifiers and map
+          # relation names to our internal comparison codes.
+          op = op.to_s.downcase
+          # Strip relation modifiers like [i], [sl], [dn], etc.
+          op = op.sub(/\[.*\]\z/, '')
+
+          # Translate "!=" into a negated equality check
+          if op == '!='
+            op = '='
+            neg = true
+          elsif op == 'contains'
+            op = '*='
+          elsif op == 'beginswith'
+            op = '^='
+          elsif op == 'endswith'
+            op = '$='
+          elsif op == 'matches'
+            op = '=~'
+          end
+
+          tag_hash = {
+            tag: tag.wildcard_to_rx,
+            comp: op,
+            value: val,
+            required: !neg,
+            negate: neg
+          }
+          out[:tags] << tag_hash
+          next
+        end
+
+        # project = "Name", project != "Name"
+        if part =~ /\Aproject\s*(=|==|!=)\s*(.+)\z/i
+          op = Regexp.last_match(1)
+          val = Regexp.last_match(2).strip
+          val = val[1..-2] if (val.start_with?('"') && val.end_with?('"')) || (val.start_with?("'") && val.end_with?("'"))
+
+          if neg || op == '!='
+            out[:exclude_projects] << val
+          else
+            out[:project] = val
+          end
+          next
+        end
+
+        # Fallback: treat as a plain text token
+        token = part
+        token = token[1..-2] if (token.start_with?('"') && token.end_with?('"')) || (token.start_with?("'") && token.end_with?("'"))
+        out[:tokens] << {
+          token: token,
+          required: !neg,
+          negate: neg
+        }
+      end
+
+      out
+    end
+
+    # Parse a TaskPaper-style @search() expression into multiple OR-joined
+    # clauses. Each clause is an AND-joined set of predicates represented as a
+    # hash compatible with NA::Todo options. Supports nested boolean
+    # expressions with parentheses using `and` / `or`. The unary `not`
+    # operator is handled inside individual predicates.
+    #
+    # Also supports an optional leading item path (subset) before predicates, e.g.:
+    #   @search(/Inbox//Testing and not @done)
+    # The leading path is exposed on each clause as :item_paths and is later
+    # resolved via resolve_item_path in run_taskpaper_search.
+    #
+    # @param expr [String] TaskPaper @search() expression or inner content
+    # @return [Array<Hash>] Array of clause hashes
+    def parse_taskpaper_search_clauses(expr)
+      return [] if expr.nil?
+
+      NA.notify("TP DEBUG expr: #{expr.inspect}", debug: true) if NA.verbose
+
+      inner = expr.to_s.strip
+      NA.notify("TP DEBUG inner initial: #{inner.inspect}", debug: true) if NA.verbose
+      inner = Regexp.last_match(1).strip if inner =~ /\A@search\((.*)\)\s*\z/i
+      NA.notify("TP DEBUG inner after @search strip: #{inner.inspect}", debug: true) if NA.verbose
+
+      return [] if inner.empty?
+
+      # Extract optional leading item path (must start with '/'). The remaining
+      # content is treated as the boolean expression for predicates. We allow
+      # spaces inside the path and stop at the first unquoted AND/OR keyword.
+      item_path = nil
+      if inner.start_with?('/')
+        i = 0
+        quote = nil
+        sep_index = nil
+        sep_len = nil
+        while i < inner.length
+          ch = inner[i]
+          if quote
+            quote = nil if ch == quote
+            i += 1
+            next
+          end
+
+          if ch == '"' || ch == "'"
+            quote = ch
+            i += 1
+            next
+          end
+
+          # Look for unquoted AND/OR separators
+          rest = inner[i..]
+          if rest =~ /\A\s+and\b/i
+            sep_index = i
+            sep_len = rest.match(/\A\s+and\b/i)[0].length
+            break
+          elsif rest =~ /\A\s+or\b/i
+            sep_index = i
+            sep_len = rest.match(/\A\s+or\b/i)[0].length
+            break
+          end
+
+          i += 1
+        end
+
+        if sep_index
+          item_path = inner[0...sep_index].strip
+          inner = inner[(sep_index + sep_len)..].to_s.strip
+        else
+          item_path = inner.strip
+          inner = ''
+        end
+      end
+      NA.notify("TP DEBUG item_path: #{item_path.inspect} inner now: #{inner.inspect}", debug: true) if NA.verbose
+
+      # Extract optional trailing slice, e.g.:
+      #   [index], [start:end], [start:], [:end], [:]
+      # from the entire inner expression (including parenthesized forms like
+      # (expr)[0]).
+      slice = nil
+      if inner =~ /\A(.+)\[(\d*:?(\d*)?)\]\s*\z/m
+        expr_part = Regexp.last_match(1).strip
+        slice_str = Regexp.last_match(2)
+
+        if slice_str.include?(':')
+          start_str, end_str = slice_str.split(':', 2)
+          slice = {
+            start: (start_str.nil? || start_str.empty? ? nil : start_str.to_i),
+            end: (end_str.nil? || end_str.empty? ? nil : end_str.to_i)
+          }
+        else
+          slice = { index: slice_str.to_i }
+        end
+
+        inner = expr_part
+      end
+      NA.notify("TP DEBUG slice: #{slice.inspect} inner after slice: #{inner.inspect}", debug: true) if NA.verbose
+
+      # If the entire expression is wrapped in a single pair of parentheses,
+      # strip them so shortcuts like `project Inbox and @na` can be recognized.
+      if inner.start_with?('(') && inner.end_with?(')')
+        depth = 0
+        balanced = true
+        inner.chars.each_with_index do |ch, idx|
+          depth += 1 if ch == '('
+          depth -= 1 if ch == ')'
+          if depth.zero? && idx < inner.length - 1
+            balanced = false
+            break
+          end
+        end
+        inner = inner[1..-2].strip if balanced
+      end
+
+      # Expand TaskPaper type shortcuts at the start of the predicate expression:
+      #   project NAME  -> project = "NAME"
+      #   task NAME     -> NAME                  (we only search tasks anyway)
+      #   note NAME     -> NAME                  (approximate)
+      if inner =~ /\A(project|task|note)\s+(.+)\z/i
+        kind = Regexp.last_match(1).downcase
+        rest = Regexp.last_match(2).strip
+        case kind
+        when 'project'
+          # If this is just `project NAME`, treat it as a project constraint.
+          # If it contains additional boolean logic (and/or), drop the
+          # `project NAME` prefix and leave the rest of the expression
+          # unchanged for normal predicate parsing.
+          if rest =~ /\b(and|or)\b/i
+            # Drop leading "NAME and" and keep the remainder, e.g.
+            # "Inbox and @na and not @done" -> "@na and not @done"
+            # then strip the leading "and" to leave "@na and not @done".
+            inner = if rest =~ /\A(\S+)\s+and\s+(.+)\z/mi
+                      Regexp.last_match(2).strip
+                    else
+                      rest
+                    end
+          else
+            name = rest
+            # Strip surrounding quotes if present
+            name = name[1..-2] if (name.start_with?('"') && name.end_with?('"')) || (name.start_with?("'") && name.end_with?("'"))
+            inner = %(project = "#{name}")
+          end
+        when 'task', 'note'
+          # For now, treat as a plain text search on the rest
+          inner = rest
+        end
+      end
+
+      NA.notify("TP DEBUG inner before tokenizing: #{inner.inspect}", debug: true) if NA.verbose
+
+      # Tokenize expression into TEXT, AND, OR, '(', ')', preserving quoted
+      # strings and leaving `not` to be handled inside predicates.
+      tokens = []
+      current = +''
+      quote = nil
+      i = 0
+
+      boundary = lambda do |str, idx, len|
+        before = idx.positive? ? str[idx - 1] : nil
+        after = (idx + len) < str.length ? str[idx + len] : nil
+        before_ok = before.nil? || before =~ /\s|\(/
+        after_ok = after.nil? || after =~ /\s|\)/
+        before_ok && after_ok
+      end
+
+      while i < inner.length
+        ch = inner[i]
+
+        if quote
+          current << ch
+          quote = nil if ch == quote
+          i += 1
+          next
+        end
+
+        if ch == '"' || ch == "'"
+          quote = ch
+          current << ch
+          i += 1
+          next
+        end
+
+        if ch == '(' || ch == ')'
+          tokens << [:TEXT, current] unless current.strip.empty?
+          current = +''
+          tokens << [ch, ch]
+          i += 1
+          next
+        end
+
+        if ch =~ /\s/
+          unless current.strip.empty?
+            tokens << [:TEXT, current]
+            current = +''
+          end
+          i += 1
+          next
+        end
+
+        rest = inner[i..]
+        if rest.downcase.start_with?('and') && boundary.call(inner, i, 3)
+          tokens << [:TEXT, current] unless current.strip.empty?
+          current = +''
+          tokens << [:AND, 'and']
+          i += 3
+          next
+        elsif rest.downcase.start_with?('or') && boundary.call(inner, i, 2)
+          tokens << [:TEXT, current] unless current.strip.empty?
+          current = +''
+          tokens << [:OR, 'or']
+          i += 2
+          next
+        else
+          current << ch
+          i += 1
+        end
+      end
+      tokens << [:TEXT, current] unless current.strip.empty?
+
+      # Recursive-descent parser producing DNF (array of AND-clauses)
+      index = 0
+
+      current_token = lambda { tokens[index] }
+      advance = lambda { index += 1 }
+
+      # Declare parse_or in outer scope so it's visible inside parse_primary
+      parse_or = nil
+
+      parse_primary = lambda do
+        tok = current_token.call
+        return [] unless tok
+
+        type, = tok
+        if type == '('
+          advance.call
+          clauses = parse_or.call
+          advance.call if current_token.call && current_token.call[0] == ')'
+          clauses
+        elsif type == :TEXT
+          parts = []
+          while current_token.call && current_token.call[0] == :TEXT
+            parts << current_token.call[1].strip
+            advance.call
+          end
+          pred = parts.join(' ').strip
+          return [] if pred.empty?
+
+          [parse_taskpaper_search_clause(pred, {
+                                           tokens: [],
+                                           tags: [],
+                                           project: nil,
+                                           include_done: nil,
+                                           exclude_projects: [],
+                                           item_paths: [],
+                                           slice: slice
+                                         })]
+        else
+          advance.call
+          []
+        end
+      end
+
+      parse_and = lambda do
+        clauses = parse_primary.call
+        while current_token.call && current_token.call[0] == :AND
+          advance.call
+          right = parse_primary.call
+          combined = []
+          clauses.each do |left_clause|
+            right.each do |right_clause|
+              combined << {
+                tokens: left_clause[:tokens] + right_clause[:tokens],
+                tags: left_clause[:tags] + right_clause[:tags],
+                project: right_clause[:project] || left_clause[:project],
+                include_done: right_clause[:include_done].nil? ? left_clause[:include_done] : right_clause[:include_done],
+                exclude_projects: left_clause[:exclude_projects] + right_clause[:exclude_projects]
+              }
+            end
+          end
+          clauses = combined
+        end
+        clauses
+      end
+
+      parse_or = lambda do
+        clauses = parse_and.call
+        while current_token.call && current_token.call[0] == :OR
+          advance.call
+          right = parse_and.call
+          clauses.concat(right)
+        end
+        clauses
+      end
+
+      clauses = parse_or.call
+
+      # If there was only an item path and no predicates, create a single
+      # empty clause to carry the path.
+      if clauses.empty? && item_path
+        clauses = [{
+          tokens: [],
+          tags: [],
+          project: nil,
+          include_done: nil,
+          exclude_projects: [],
+          item_paths: [],
+          slice: slice
+        }]
+      end
+
+      # Attach leading item path (if any) to all clauses
+      if item_path
+        clauses.each do |clause|
+          clause[:item_paths] ||= []
+          clause[:item_paths] << item_path
+        end
+      end
+
+      clauses
+    end
+
+    # Load TaskPaper-style saved searches from todo files.
+    #
+    # Scans all lines in each file for:
+    #   [WHITESPACE]TITLE @search(PARAMS)
+    # regardless of project name or indentation. This allows searches to live
+    # in any project (e.g. "Searches") or even at top level.
+    #
+    # @param depth [Integer] Directory depth to search for files
+    # @return [Hash{String=>Hash}] Map of title to {:expr, :file}
+    def load_taskpaper_searches(depth: 1)
+      searches = {}
+      files = find_files(depth: depth)
+      return searches if files.nil? || files.empty?
+
+      files.each do |file|
+        content = file.read_file
+        next if content.nil? || content.empty?
+
+        content.each_line do |line|
+          next if line.strip.empty?
+          next unless line =~ /^\s*(.+?)\s+@search\((.+)\)\s*$/
+
+          title = Regexp.last_match(1).strip
+          expr = "@search(#{Regexp.last_match(2).strip})"
+          searches[title] = { expr: expr, file: file }
+        end
+      end
+
+      searches
+    end
+
+    # Evaluate a TaskPaper-style @search() expression and return matching
+    # actions and files, without printing.
+    #
+    # @param expr [String] TaskPaper @search() expression
+    # @param file [String,nil] Optional single file to search within
+    # @param options [Hash] Display/search options (subset of find.rb)
+    # @return [Array(NA::Actions, Array<String>, Array<Hash>)] actions, files, clauses
+    def evaluate_taskpaper_search(expr, file: nil, options: {})
+      clauses = parse_taskpaper_search_clauses(expr)
+      NA.notify("TP DEBUG clauses: #{clauses.inspect}", debug: true) if NA.verbose
+      return [NA::Actions.new, [], []] if clauses.empty?
+
+      depth = options[:depth] || 1
+      all_actions = NA::Actions.new
+      all_files = []
+
+      clauses.each do |parsed|
+        search_tokens = parsed[:tokens]
+        tags = parsed[:tags]
+        include_done = parsed[:include_done]
+        exclude_projects = parsed[:exclude_projects] || []
+        project = parsed[:project] || options[:project]
+        slice = parsed[:slice]
+
+        # Resolve any item-path filters declared on this clause
+        item_paths = Array(parsed[:item_paths]).compact
+        resolved_paths = []
+        item_paths.each do |p|
+          resolved_paths.concat(resolve_item_path(path: p, file: file, depth: depth))
+        end
+
+        todo_options = {
+          depth: depth,
+          done: include_done.nil? ? options[:done] : include_done,
+          query: nil,
+          search: search_tokens,
+          search_note: options.fetch(:search_notes, true),
+          tag: tags,
+          negate: options.fetch(:invert, false),
+          regex: options.fetch(:regex, false),
+          project: project,
+          require_na: options.fetch(:require_na, false)
+        }
+        todo_options[:file_path] = file if file
+
+        todo = NA::Todo.new(todo_options)
+
+        # Start from the full action list for this clause
+        clause_actions = todo.actions.to_a
+        if NA.verbose
+          NA.notify("TP DEBUG initial actions count: #{clause_actions.size}", debug: true)
+          clause_actions.each do |a|
+            NA.notify("TP DEBUG action: #{a.action.inspect} parents=#{Array(a.parent).inspect}", debug: true)
+          end
+        end
+
+        # Apply project exclusions (e.g. "not project = \"Archive\"")
+        unless exclude_projects.empty?
+          before = clause_actions.size
+          clause_actions.delete_if do |action|
+            parents = Array(action.parent)
+            last = parents.last.to_s
+            full = parents.join(':')
+            exclude_projects.any? do |proj|
+              proj_rx = Regexp.new(Regexp.escape(proj), Regexp::IGNORECASE)
+              last =~ proj_rx || full =~ /(^|:)#{Regexp.escape(proj)}$/i
+            end
+          end
+          NA.notify("TP DEBUG after exclude_projects: #{clause_actions.size} (was #{before})", debug: true) if NA.verbose
+        end
+
+        # Apply item-path project filters, if any
+        unless resolved_paths.empty?
+          before = clause_actions.size
+          clause_actions.delete_if do |action|
+            parents = Array(action.parent)
+            path = parents.join(':')
+            resolved_paths.none? do |p|
+              path =~ /\A#{Regexp.escape(p)}(?::|\z)/i
+            end
+          end
+          NA.notify("TP DEBUG after item_path filter: #{clause_actions.size} (was #{before})", debug: true) if NA.verbose
+        end
+
+        # Apply slice, if present, to the filtered clause actions
+        if slice
+          before = clause_actions.size
+          if slice[:index]
+            idx = slice[:index].to_i
+            clause_actions = idx.negative? ? [] : [clause_actions[idx]].compact
+          else
+            start_idx = slice[:start] || 0
+            end_idx = slice[:end] || clause_actions.length
+            clause_actions = clause_actions[start_idx...end_idx] || []
+          end
+          NA.notify("TP DEBUG after slice #{slice.inspect}: #{clause_actions.size} (was #{before})", debug: true) if NA.verbose
+        end
+
+        all_files.concat(todo.files)
+        clause_actions.each { |a| all_actions.push(a) }
+      end
+
+      # De-duplicate actions across clauses
+      seen = {}
+      merged_actions = NA::Actions.new
+      all_actions.each do |a|
+        key = "#{a.file_path}:#{a.file_line}"
+        next if seen[key]
+
+        seen[key] = true
+        merged_actions.push(a)
+      end
+
+      if NA.verbose
+        NA.notify("TP DEBUG merged_actions count: #{merged_actions.size}", debug: true)
+        merged_actions.each do |a|
+          NA.notify("TP DEBUG merged action: #{a.file_path}:#{a.file_line} #{a.action.inspect}", debug: true)
+        end
+      end
+
+      [merged_actions, all_files.uniq, clauses]
+    end
+
+    # Execute a TaskPaper-style @search() expression using NA::Todo and output
+    # results with the standard formatting options.
+    #
+    # @param expr [String] TaskPaper @search() expression
+    # @param file [String,nil] Optional single file to search within
+    # @param options [Hash] Display/search options (subset of find.rb)
+    # @return [void]
+    def run_taskpaper_search(expr, file: nil, options: {})
+      actions, files, clauses = evaluate_taskpaper_search(expr, file: file, options: options)
+      depth = options[:depth] || 1
+
+      # Build regexes for highlighting from all positive tokens across clauses
+      regexes = []
+      clauses.each do |parsed|
+        sts = parsed[:tokens]
+        if sts.is_a?(Array)
+          regexes.concat(sts.delete_if { |token| token[:negate] }.map { |token| token[:token].wildcard_to_rx })
+        elsif sts
+          regexes << sts
+        end
+      end
+      regexes.uniq!
+
+      actions.output(depth,
+                     {
+                       files: files,
+                       regexes: regexes,
+                       notes: options.fetch(:notes, false),
+                       nest: options.fetch(:nest, false),
+                       nest_projects: options.fetch(:omnifocus, false),
+                       no_files: options.fetch(:no_file, false),
+                       times: options.fetch(:times, false),
+                       human: options.fetch(:human, false)
+                     })
+    end
+
     # Load saved search definitions from YAML file
     #
     # @return [Hash] Hash of saved searches