Module: Pikuri::Os::Recoll

Defined in:

lib/pikuri/os/recoll.rb

Overview

Backend wrapper over the recoll full-text index, via its headless recollq CLI (Xapian-backed). The DE-independent sibling of LocalSearch: same seam shape (Recoll.search / Recoll.read_text / Recoll.available? / Recoll.check_binaries!), interchangeable behind the fileindex_search / fileindex_read tools, and Extension wires whichever is available? first.

Recall on prose ties localsearch, so recoll is not a better engine — it earns its place where localsearch is structurally blind (source trees, .git checkouts, non-GNOME desktops). Its blind spot is the inverse: recoll indexes exactly the folders the user configured (+topdirs+), source code included — everything outside them is invisible. The measured survey behind the pick-one-per-host order is in pikuri-os/DESIGN.md.

Recoll.search asks recollq -F 'url abstract' for two base64-encoded fields per line (recoll's own recommended machine shape) so paths and snippets with spaces/brackets/newlines survive with no escaping guesswork. Recoll.read_text uses recollq -d, which dumps a document's stored/extracted text (PDFs/office docs included) after a header line.

Defined Under Namespace

Classes: CommandError

Constant Summary

BINARY =

Returns the headless recoll query CLI.

Returns:

• (String) —

  the headless recoll query CLI.

'recollq'

INDEXER =

Returns the recoll indexer/config CLI (used only to locate the config; never invoked to index from here).

Returns:

• (String) —

  the recoll indexer/config CLI (used only to locate the config; never invoked to index from here).

'recollindex'

CONFIG_FILE =

Returns recoll config filename inside the config dir.

Returns:

• (String) —

  recoll config filename inside the config dir.

'recoll.conf'

DEFAULT_TOPDIRS =

recoll's compiled-in default when topdirs is unset: the whole home directory (the sample config ships topdirs = ~ too).

Returns:

• (String)

'~'

INDEX_DIR =

Returns the Xapian index directory name inside the config dir; its presence is what available? treats as "usable".

Returns:

• (String) —

  the Xapian index directory name inside the config dir; its presence is what available? treats as "usable".

'xapiandb'

Class Method Summary

• .available? ⇒ Boolean

  Non-raising usability probe — for callers that select a backend among several and want the one that can actually serve searches.

• .check_binaries! ⇒ Object

  Verify recollq is reachable; raise loudly otherwise.

• .confdir ⇒ String

  The recoll configuration directory recoll would use: $RECOLL_CONFDIR if set and non-empty, else ~/.recoll.

• .extract_dumped_text(raw, abs) ⇒ String^?

  Pull the dumped body of the result whose header line matches abs out of recollq -d output.

• .indexed_dirs ⇒ Array<String>

  Folders recoll is configured to index, read from topdirs in the active config file.

• .label ⇒ String

  Short human name for this backend, used by the fileindex tools when prefixing an "Error: ..." observation.

• .limitations ⇒ String

  Plain-English note of what this backend will not surface, appended to the fileindex tools' LLM description so the model knows when to fall back to a filesystem text/regex search.

• .parse_search_output(raw) ⇒ Array<Hash>

  Parse recollq -F 'url abstract' output into hits.

• .parse_topdirs(raw) ⇒ Array<String>

  Join backslash-continued lines, then read the topdirs value from the global section (everything before the first [section] header).

• .read_text(path) ⇒ String^?

  Full stored/extracted text of an indexed file, via recollq -d scoped to the file's own name.

• .search(query:, limit:) ⇒ Array<Hash>

  Run recollq -F 'url abstract' -n <limit> and parse the results.

Class Method Details

.available? ⇒ Boolean

Non-raising usability probe — for callers that select a backend among several and want the one that can actually serve searches. Stricter than check_binaries!: it requires both the recollq binary and a built index (INDEX_DIR under confdir), because an installed-but-never-indexed recoll errors ("Xapian index open error") on every query — so it must not win backend selection over a working alternative. See check_binaries! for why exit status is ignored for the binary half.

Returns:

• (Boolean)

# File 'lib/pikuri/os/recoll.rb', line 210

def self.available?
  return false unless File.directory?(File.join(confdir, INDEX_DIR))

  Pikuri::Subprocess.spawn(BINARY, '-h', chdir: '/').wait
  true
rescue Errno::ENOENT
  false
end

.check_binaries! ⇒ Object

Verify recollq is reachable; raise loudly otherwise. Presence is judged by whether the binary ran (no Errno::ENOENT), not by exit status: recollq -h exits non-zero by design, so a zero-exit probe would false-negative on a perfectly good install.

Raises:

• (RuntimeError) —

  if the binary is missing

# File 'lib/pikuri/os/recoll.rb', line 194

def self.check_binaries!
  Pikuri::Subprocess.spawn(BINARY, '-h', chdir: '/').wait
rescue Errno::ENOENT
  raise install_hint
end

.confdir ⇒ String

The recoll configuration directory recoll would use: $RECOLL_CONFDIR if set and non-empty, else ~/.recoll.

Returns:

• (String)

# File 'lib/pikuri/os/recoll.rb', line 101

def self.confdir
  env = ENV['RECOLL_CONFDIR']
  env && !env.empty? ? File.expand_path(env) : File.expand_path('~/.recoll')
end

.extract_dumped_text(raw, abs) ⇒ String^?

Pull the dumped body of the result whose header line matches abs out of recollq -d output. Each result is a tab-delimited header line (+\t[]\t[