yarsh 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5273b4e67dcb97cfa9dd5af63b83cfe7aa1d47cf27803baf27a0e35544346c19
-  data.tar.gz: 195f587ad4ee4dda6890520fdf2f2be20c7bdb2a6ab92f6d709dc24aaac5a7ad
+  metadata.gz: 149709074192906833f0d530ba07da00c9a6591ea79864fd5d5f2e9c39019ad8
+  data.tar.gz: 4c7336c81d2531dd94052c05344d186e97878b94c92e1ad5852955d10df07da3
 SHA512:
-  metadata.gz: d0b448b5c4fbdec98e05c3519989e5ff74f8b8a7a5372a7d8772196ced90b15a64a5be7b97af6a7b954d9c08d046172e1c60ebb348018552f56fd09ca85aa8ee
-  data.tar.gz: b177ff3a557c6acdf842e2e29af9dcba09a118926b7d43c7d74507e5877952bef9bdf5faeab6b5f8f210d45ad1e2ce13eb8f01bf5593e08dbbabb464d42aa767
+  metadata.gz: 030f6d98caa7410911fd8cff2e55e9062dda276c6f45f27d2e29073b53717aa273a0b58ad3b761833c1a955fa0b8ade8501c7c0fcab0af8095eff09a906451ce
+  data.tar.gz: 85d5081c0f07e9ddea3e0ea5202abea2d2adbea4b6cedf22f8d9a81c4a34fad0b1a9c037de8da601579b2e5bbbea4f649e9a2661b31c3496bf5f8f91d65f727f

data/AGENTS.md

@@ -15,13 +15,23 @@ A hybrid Ruby/shell interactive REPL. Input is evaluated as Ruby first; on
 
 ## Architecture
 
-- **Main logic** lives in `lib/yarsh.rb` (module `Yarsh` with `self.shell`,
-  `self.console`, `self.execute`, `self.shell_path?`, `self.execute_pipe`, etc.).
-  `bin/console` calls `Yarsh.console` (IRB session); `exe/yarsh` calls `Yarsh.shell`.
-- `exe/yarsh` is the gem executable (packaged via `spec.bindir = "exe"` in the
-  gemspec). `bin/console` is for development only (adds `bundler/setup`).
-- `Yarsh.shell_path?` recognizes absolute/relative/home paths for shell execution.
-- `Yarsh.execute_pipe` enables piping shell output into Ruby via the `-->` operator.
+- **Entry point** is `exe/yarsh`: it `extend`s `Yarsh::InstanceMethods` onto the
+  top-level object, creates `Yarsh::Shell.new(binding)`, and calls `.shell`
+  (the REPL loop). `bin/console` is for development only (adds `bundler/setup`
+  and starts an IRB session via `Yarsh.console`).
+- **`lib/yarsh.rb`** defines the module-level helpers: constants (`YARSH_DIR`,
+  `HISTORY_FILE`, `CONFIG_FILE`), `ExecOutput`, `self.current_shell`,
+  `self.expand_aliases`, `shell_path?` (absolute/relative/home path detection,
+  mixed into `Shell`), `self.execute_system_command` (Open3, dead code), and
+  `self.console`.
+- **`Yarsh::Shell`** (`lib/yarsh/shell.rb`) holds the REPL loop (`shell`),
+  the prompt/history/completion wiring (`setup_reline_*`), the evaluation
+  pipeline (`execute_multiline`, `yarsh_eval`, `execute_pipe`, `__sh_exec`),
+  `cd`, `shell_command?`, and `execute` (`system(cmd, exception: true)`).
+- Multiline input lives in `lib/yarsh/multiline.rb` (`Yarsh::Multiline`):
+  `incomplete?` decides when to keep reading, `transform` rewrites shell lines
+  into `__sh__`/`__yarsh__` calls, `classify_line` classifies each line. The
+  active shell is exposed as `Yarsh.current_shell` for `__sh__` dispatch.
 
 ## `-->` pipe operator
 
@@ -39,15 +49,72 @@ Examples:
 | `ls --> lines.count` | (file count) |
 | `cat data.txt --> _.split("\n").grep(/error/)` | matching lines |
 
-## REPL evaluation flow
+## Multiline input
+
+Input is read via `Reline.readmultiline`; the REPL keeps reading while the
+buffer is syntactically incomplete (`Yarsh::Multiline.incomplete?` checks the
+`SyntaxError` from `RubyVM::InstructionSequence.compile` for unterminated
+constructs: missing `end`, strings, heredocs, regexps, operators, `case`
+clauses). Known-bad syntax (`@@@`) is not incomplete. Shell-command-shaped
+lines (`cd /tmp`, `grep foo /etc/passwd`) never enter multiline mode even
+though they fail to compile as Ruby (unterminated regexp) — `shell_command?`
+is checked first. An empty line forces submission; continuation lines get a
+`  > ` prompt via `Reline.prompt_proc`.
+
+The finished buffer is rewritten by `Yarsh::Multiline.transform` (each line
+classified 1:1 by `classify_line`), then evaluated via `@bind.eval`:
+
+- `:structural` — lines whose `Ripper.lex` tokens include a structural
+  keyword (`do`, `if`, `def`, `class`, `when`, …) are kept verbatim, but an
+  opening structural line gets `bind = binding` appended (nested structures
+  get `bind = binding + bind`) so inner lines can reach outer locals
+- `:yarsh` — every other non-blank line (shell lines *and* Ruby expressions
+  inside a structural block) is rewritten to
+  `__yarsh__("...", bind|nil)`; local variables assigned in an outer
+  structural line are wrapped as `__yarsh__("name", bind)` references
+  (`IdentifierSurround`)
+- `:skip` — blank lines are dropped; heredoc bodies are never rewritten
+- `:shell` — reserved for `__sh__("...")` calls (currently unemitted, see
+  Known issues)
+
+`__yarsh__` (`Yarsh::InstanceMethods`, extended onto the top-level binding in
+`exe/yarsh`) temporarily swaps `Shell#bind` for the block binding and calls
+`Shell#yarsh_eval`, which handles `-->` pipes, shell paths, `cd`, and Ruby
+evaluation with the shell fallback (see REPL evaluation flow). Shell lines
+therefore work inside Ruby blocks, defs, and classes; the whole buffer is
+evaluated in the shared REPL binding so methods/variables persist. Examples:
+
+| Input | Result |
+|---|---|
+| `Dir['*.rb'].each do \|f|` … `ls -l` … `puts f` … `end` | runs `ls -l` for each file |
+| `def hi` … `puts 'yo'` … `end` then `hi` | `yo` (def persists) |
 
-All steps below are wrapped in a single `begin..rescue` so no error crashes the REPL:
+Known limitations:
+
+- Pure-bash multiline (e.g. bash `if ...; then`) is not supported; shell
+  lines only work inside Ruby structures.
+- Shell execution inside a block relies on the `NameError` fallback of
+  `yarsh_eval`, so a Ruby expression that raises a real `NameError` may be
+  shell-executed instead of reported.
+
+## REPL evaluation flow
 
-1. `input.include?("-->")` → `Yarsh.execute_pipe(input)`, print result
-2. `Yarsh.shell_path?(input)` → execute directly via `bash -c`
-3. `bind.eval(input)` — Ruby evaluation
-4. `NameError` → if first token is `cd`, call `Dir.chdir`; else shell-execute
-5. Other exceptions → print `Error: ExceptionClass: message`
+All steps below are wrapped in a single `begin..rescue` in `Shell#shell` so no
+error crashes the REPL:
+
+1. Input is read via `Reline.readmultiline` (see Multiline input above);
+   `read_input` keeps reading while `incomplete_line?` (incomplete and not a
+   shell command) or until a blank line ends the buffer
+2. The whole input goes through `execute_multiline`: `Yarsh::Multiline.transform`
+   rewrites non-structural lines to `__yarsh__(...)` calls (structural lines
+   kept verbatim), then `@bind.eval` runs the buffer; per-line execution
+   happens inside `Shell#yarsh_eval` / `Shell#__sh_exec`
+3. `yarsh_eval`: `-->` pipe → `execute_pipe`; shell path (`shell_path?`) →
+   `execute`; `cd`/`cd <path>` → `Dir.chdir`; otherwise `bind.eval` — on
+   `NameError`/`SyntaxError`/`ArgumentError` it falls back to aliases +
+   shell execution (unless the input looks like a Ruby error, then it is
+   reported)
+4. Other exceptions → print `Error: ExceptionClass: message`
 
 ## Error handling
 
@@ -60,12 +127,30 @@ All steps below are wrapped in a single `begin..rescue` so no error crashes the
 
 ## Known issues
 
-- **Bug:** `Yarsh.execute` (in `lib/yarsh.rb`) uses `system("bash -c 'source
-  ~/.bashrc; #{cmd}'")` — the command is passed correctly, but this depends on
-  `~/.bashrc` existing.
-- **Dead code:** `Yarsh.execute_system_command` (Open3 version) is defined but
-  never called. `Yarsh.shell` calls `Yarsh.execute`, not
-  `Yarsh.execute_system_command`.
+- **Dead code:** `Yarsh.execute_system_command` (Open3 version) in
+  `lib/yarsh.rb` is defined but never called; shell execution goes through
+  `Shell#execute` (`system(cmd, exception: true)`).
+- **Bug risk:** `setup_reline_history` replays history with
+  `@core.readmultiline`-independent heuristics (`incomplete_line?`),
+  which may mishandle historical shell-command lines (see Multiline input).
+- **Unemitted `:shell`:** `Multiline.transform` never emits `:shell`/`__sh__`
+  (the `classify_line` branches are commented out behind FIXMEs); shell lines
+  and Ruby expressions both go through `__yarsh__`, with the shell fallback of
+  `yarsh_eval` deciding. `__sh__`/`__sh_exec` still exist for potential
+  re-enabling.
+
+## Bash autocomplete
+
+`Yarsh::Completion::BashAutocomplete` provides tab-completion by invoking bash
+completion functions:
+
+- For commands supporting the `__complete` subcommand (docker, kubectl, etc.),
+  it calls `<command> __complete <word>` and parses tab-separated output.
+- For all other commands, it sources the bash completion script and runs the
+  registered completion function with `COMP_WORDS`/`COMP_CWORD` set.
+- Privileged commands (`sudo`, `doas`, `pkexec`, `su`) skip the `__complete`
+  path to avoid password prompts; they always use the bash completion function.
+- Results are cached in a bounded in-memory `CACHE` (max 100 entries).
 
 ## Style
 

data/CHANGES.md

@@ -26,19 +26,19 @@ a shell command, matching the existing `NameError` fallback behavior.
 
 ### REPL history persisted to `~/.yarsh/history`
 
-(53032be) Commands are saved to `~/.yarsh/history` across sessions. Max 1000 lines;
+Commands are saved to `~/.yarsh/history` across sessions. Max 1000 lines;
 concurrent-session safe via `File.flock`.
-(77af3b8) Add tests for append_history: creation, append, trim, concurrent safety.
+Add tests for append_history: creation, append, trim, concurrent safety.
 
 ### `bin/console` launches an IRB session
 
-(33f86c8) `bin/console` now starts a standard IRB session with the gem loaded
+`bin/console` now starts a standard IRB session with the gem loaded
 (`Yarsh.console`). The hybrid REPL remains available via `bundle exec ruby exe/yarsh`
 (`Yarsh.shell`).
 
 ### Test suite adapted to multi-file architecture
 
-(13655c4) Tests split per class: `test_yarsh.rb` (module-level: constants,
+Tests split per class: `test_yarsh.rb` (module-level: constants,
 `ExecOutput`, `console`), `test_shell.rb` (`Yarsh::Shell`: `shell_path?`, `cd`,
 completion, history, `execute_pipe` incl. bind-var feature), `test_config.rb`
 (`Yarsh::Config`: prompt, `log_level`), `test_prompt.rb` (`Prompt`,
@@ -47,14 +47,14 @@ validation in `Config#prompt=`.
 
 ### Console test works under minitest 6
 
-(e3d1f44) `test_console_launches_irb_session` no longer uses
+`test_console_launches_irb_session` no longer uses
 `IRB.stub` (`minitest/mock` was removed in minitest 6, breaking plain
 `rake test`); it now stubs `IRB.start` via `define_singleton_method`.
 README documents running tests with `bundle exec rake test`.
 
 ### `expand_aliases` no longer strips whitespace
 
-(ab3998e) Registering the first alias via `sh_alias`/`add_alias` ran the
+Registering the first alias via `sh_alias`/`add_alias` ran the
 command through `expand_aliases` with an empty alias hash; the empty
 alternation degraded the regex to `(^| +)() *` and every space was
 deleted (`exa -l --icons=always` was stored as `exa-l--icons=always`).
@@ -66,7 +66,7 @@ with a regression test for the empty-alias case.
 
 ### `Yarsh::InvalidPromptError` for invalid prompt configuration
 
-(4f0364e) `Config#prompt=` raises the new `Yarsh::InvalidPromptError`
+`Config#prompt=` raises the new `Yarsh::InvalidPromptError`
 (subclass of `Yarsh::Error`) instead of a bare `StandardError`. The
 message is a constructor argument with the documented default.
 `Yarsh::Error` is now defined before sub-files are required, fixing a
@@ -75,7 +75,7 @@ assert the error class, the default message, and custom messages.
 
 ### Logging methods in `InstanceMethods`
 
-(d867a11) Besides the existing `debug`, the REPL now exposes `info`,
+Besides the existing `debug`, the REPL now exposes `info`,
 `warn`, `error`, `fatal`, and `unknown` — each delegating to
 `Config.instance.logger`, covering all `Logger` severities. Methods are
 defined dynamically from the `SEVERITIES` constant
@@ -83,7 +83,7 @@ defined dynamically from the `SEVERITIES` constant
 
 ### 256-color and text styles in `AnsiColorFormatter`
 
-(3883da3) New `fg_color256`/`bg_color256` emit 8-bit indexed color
+New `fg_color256`/`bg_color256` emit 8-bit indexed color
 codes (`38;5;N` / `48;5;N`) and raise `Yarsh::Error` for indices outside
 0..255. Text styles are defined dynamically from `STYLE_CODES`: `bold`,
 `dim`, `italic`, `underline`, `blink`, `reverse`, `hidden`,
@@ -93,7 +93,7 @@ now tolerates calls with neither text nor a block, so bare style calls
 
 ### Real `ArgumentError`s are no longer shell-executed
 
-(13ea85f) Shell commands like `bundle exec rake test` raise
+Shell commands like `bundle exec rake test` raise
 `ArgumentError` (the innermost call resolves to `Kernel#test`, which
 requires 2 args). The fallback previously treated every `ArgumentError`
 as a shell command, so genuine Ruby errors (`"x".sub`) were
@@ -105,10 +105,99 @@ keep their unconditional shell fallback.
 
 ### Renamed from `rsh` to `yarsh`
 
-(9009bfb) The project is now called **yarsh** throughout: module `Rsh`
+The project is now called **yarsh** throughout: module `Rsh`
 → `Yarsh`, gem name `yarsh` (`spec.name`, require paths), data dir
 `~/.rsh` → `~/.yarsh`, executable `exe/ruby-shell` → `exe/yarsh`.
 Files renamed: `rsh.gemspec`, `lib/rsh.rb`, `lib/rsh/`,
 `sig/rsh.rbs`, `test/test_rsh.rb`. All references updated (tests,
 `bin/console`, README, AGENTS.md, CHANGES.md); `Gemfile.lock`
-regenerated. Version stays 0.1.0.
+regenerated.
+
+## 0.1.0
+
+First development release!
+
+* `eee1b3e` Initial commit for a clean git project
+* `da76411` and `b02a1b8` Updated README for better clarity and fix repository links
+
+## 0.1.1
+
+Small correction in the gem description
+
+* `5741a00` update the gem description
+
+## 0.1.2
+
+Bug fix and small improvement for the prompt type **powerline**
+
+See commits:
+
+* `d59834b`
+* `d81ffcb`
+* `3e93937`
+* `4b77901`
+
+## 0.2.0
+
+### Multi-line input with shell lines inside Ruby blocks
+
+Input is now read via `Reline.readmultiline` — the REPL keeps reading while the
+buffer is syntactically incomplete (`Yarsh::Multiline.incomplete?` checks the
+`SyntaxError` from `RubyVM::InstructionSequence.compile` for unterminated
+constructs: missing `end`, strings, heredocs, regexps, operators, `case`
+clauses). Known-bad syntax (`@@@`) is not treated as incomplete, and
+shell-command-shaped lines (`cd /tmp`, `grep foo /etc/passwd`) never enter
+multiline mode even though they fail to compile as Ruby (unterminated regexp).
+An empty line forces submission; continuation lines get a `  > ` prompt via
+`Reline.prompt_proc`.
+
+The finished buffer is rewritten by `Yarsh::Multiline.transform` (each line
+classified 1:1 by `classify_line`), then evaluated via `@bind.eval`:
+
+- Lines whose `Ripper.lex` tokens include a structural keyword (`do`, `if`,
+  `def`, `class`, `when`, …) are kept verbatim; an opening structural line
+  gets `bind = binding` appended (nested structures get `bind = binding +
+  bind`) so inner lines can reach outer locals
+- Every other non-blank line — shell lines *and* Ruby expressions inside a
+  structural block — is rewritten to `__yarsh__(...)` with the surrounding
+  binding; local variables assigned in an outer structural line are wrapped
+  as `__yarsh__("name", bind)` references (`IdentifierSurround`)
+- Blank lines are dropped; heredoc bodies are never rewritten
+
+`__yarsh__` (`Yarsh::InstanceMethods`, extended onto the top-level binding in
+`exe/yarsh`) temporarily swaps `Yarsh::Shell#bind` for the block binding and
+calls `Shell#yarsh_eval`, which handles `-->` pipes, shell paths, `cd`, and
+Ruby evaluation with the shell fallback. Shell lines therefore work inside
+Ruby blocks, defs, and classes; the whole buffer is evaluated in the shared
+REPL binding so methods and variables persist. Examples:
+
+```ruby
+Dir['*.rb'].each do |f|
+  ls -l
+  puts f
+end
+# runs `ls -l` for each file
+```
+
+```ruby
+def hi
+  puts 'yo'
+end
+hi
+#=> yo (def persists)
+```
+
+Known limitations:
+
+- Pure-bash multiline (e.g. bash `if ...; then`) is not supported; shell
+  lines only work inside Ruby structures.
+- Shell execution inside a block relies on the `NameError` fallback of
+  `yarsh_eval`, so a Ruby expression that raises a real `NameError` may be
+  shell-executed instead of reported.
+
+See commits: `bcc25b4`, `ea92742`, `51c9db8`, `2218f29`, `0fceeb8`. Tests in
+`test/test_multiline.rb` (completeness detection, line classification,
+transformation, heredoc handling, binding threading, integration with
+`Yarsh::Shell`).
+
+

data/README.md

@@ -4,7 +4,7 @@ Yet Another Ruby SHell is a mix of Ruby and standard Shell REPL. Priority is giv
 
 This project was made just for fun, to remember the basis of Ruby and to discover new features. To provide a good user experience, it uses `reline` under the hood which already implement all we want for a REPL: History, completion, etc.
 
-I wanted a simple version but already working version. If I have time, more features will come. For example, multi-line editing or non interactive with a file as argument. I dream of a shell syntax we can do:
+I wanted a simple version but already working version. If I have time, more features will come. For example, non interactive with a file as argument. I dream of a shell syntax we can do:
 
 ```ruby
 def install_rails
@@ -16,8 +16,15 @@ end
 install_rails
 ```
 
+And this is now a reality: multi-line editing is supported, and shell commands
+work inside Ruby blocks, defs, and classes (see [Multiline](#multiline)).
+
 I developed this project half of the time offline, another part with the help of AI. It was a way for me to try to develop with AI. I used `opencode` with DeepSeek V4 Flash Free.
 
+## install
+
+Run `gem install yarsh`
+
 ## Usage
 
 `yarsh` start the shell.
@@ -55,9 +62,66 @@ ls -al . -->(sorted) lines.sort {|a, b| a.length <=> b.length  }
 sorted.each { |file| puts "What ever you wanna do" }
 ```
 
+### Multiline
+
+Multi-line input is supported: the REPL keeps reading while the buffer is
+syntactically incomplete (missing `end`, unterminated string/heredoc/regexp,
+trailing operator, ...) and submits when the syntax is complete or on an empty
+line. Continuation lines get a `  > ` prompt.
+
+The best part: you can mix Ruby and shell lines in the same block, def, or
+class:
+
+```ruby
+def install_rails
+  sudo apt update
+  sudo apt install ruby
+  gem install rails
+end
+```
+
+```ruby
+Dir['*.rb'].each do |f|
+  ls -l
+  puts "Processed: #{f}"
+end
+```
+
+The whole buffer is evaluated in the shared REPL binding, so methods,
+variables, and shell side-effects persist between lines and across inputs.
+Shell lines are executed via the usual fallback (they are evaluated as Ruby
+first, then as a shell command). Heredoc bodies are kept verbatim:
+
+```ruby
+x = <<~EOF
+  not evaluated, just a string
+EOF
+```
+
+Known limitations:
+
+- Pure-bash multiline (e.g. bash `if ...; then`) is not supported; shell
+  lines only work inside Ruby structures.
+- A Ruby expression that raises a real `NameError` inside a block may be
+  executed as a shell command instead of being reported.
+
 ### Completion
 
-For the moment, there is autocompletion for exectuables in PATH and for file and dir path for shell commands
+Tab completion is powered by a multi-engine system:
+
+- **Command completion** — completes executables in PATH and shell builtins
+- **Path completion** — completes file and directory paths (including `~` expansion)
+- **Ruby completion** — completes Ruby methods and constants (can be disabled via `Config.instance.ruby_completion = false`)
+- **Bash completion** — invokes bash completion functions for commands that have them (e.g. `git`, `docker`, `systemctl`), including multi-word commands like `systemctl restart <service>`
+- **Gem completion** — provides subcommand and option completion for `gem`, plus installed gem names for subcommands that operate on installed gems (`info`, `uninstall`, `open`, `contents`, `check`, `cleanup`, `pristine`, `rdoc`, `specification`, `dependency`)
+
+Completion is suppressed when the cursor is inside a quoted string, so typing
+`git commit -m ""` won't have options inserted between the quotes.
+
+Privileged commands (`sudo`, `doas`, `pkexec`, `su`) are handled transparently:
+`sudo systemctl restart <Tab>` completes the same as `systemctl restart <Tab>`.
+
+A base completion engine is provided in order to add more completions with ease. See `lib/yarsh/completion/base.rb` for more information and `lib/yarsh/completion/gem.rb` for an example of a completion for the gem command.
 
 ### Errors
 

data/lib/yarsh/binding.rb

@@ -0,0 +1,14 @@
+class Binding
+  def +(other)
+    return self if other.nil?
+
+    other.local_variables.each do |var|
+      local_variable_set(var, other.local_variable_get(var))
+    end
+    self
+  end
+
+  def inspect
+    "#<Binding:>\n  local_vars: #{local_variables.inspect}"
+  end
+end

data/lib/yarsh/completion/bash_autocomplete.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+require 'tempfile'
+require_relative 'engine'
+
+module Yarsh
+  module Completion
+    class BashAutocomplete < Engine
+      BASH_COMPLETION_MAIN = '/usr/share/bash-completion/bash_completion'
+      COMPLETION_DIR = '/usr/share/bash-completion/completions'
+      CACHE = {}
+
+      def supports?(command)
+        return false if command.nil? || command.empty?
+        command = command.strip.split(/\s+/).first
+        File.exist?("#{COMPLETION_DIR}/#{command}") ||
+          File.exist?("#{COMPLETION_DIR}/#{command}.bash") ||
+          bash_completion_defined?(command)
+      end
+
+      def complete(command, word, args = [])
+        command = command.strip.split(/\s+/).first
+        return [] unless supports?(command)
+        return [] unless find_script(command)
+
+        # Try __complete subcommand first (works for docker and others)
+        sub_output = bash_invoke_complete_subcommand(command, word)
+        return sub_output unless sub_output.nil? || sub_output.empty?
+
+        # Fall back to bash completion function
+        func = completion_function(command)
+        return [] if func.nil? || func.empty?
+
+        output = bash_invoke_completion(func, command, word)
+        return [] if output.nil? || output.empty?
+
+        has_trailing_space = word.end_with?(' ')
+        prefix = has_trailing_space ? '' : word.strip.split(/\s+/).last
+        return output.split if prefix == command
+
+        output.split.select { |r| r.start_with?(prefix) }
+      rescue
+        []
+      end
+
+      private
+
+      def find_script(command)
+        return "#{COMPLETION_DIR}/#{command}" if File.exist?("#{COMPLETION_DIR}/#{command}")
+        return "#{COMPLETION_DIR}/#{command}.bash" if File.exist?("#{COMPLETION_DIR}/#{command}.bash")
+        nil
+      end
+
+      def bash_completion_defined?(command)
+        func = completion_function(command)
+        !func.nil? && !func.empty?
+      rescue
+        false
+      end
+
+      def completion_function(command)
+        return '' unless File.exist?(BASH_COMPLETION_MAIN)
+        script = find_script(command)
+        return '' unless script
+
+        `bash -c 'source #{Shellwords.shellescape(BASH_COMPLETION_MAIN)} 2>/dev/null; source #{Shellwords.shellescape(script)} 2>/dev/null; complete -p #{Shellwords.shellescape(command)} 2>/dev/null | grep -oP "(?<= -F )\\S+"' 2>/dev/null`.strip
+      rescue
+        ''
+      end
+
+      def bash_invoke_completion(func, command, partial)
+        has_trailing_space = partial.end_with?(' ')
+        words = if has_trailing_space
+                  partial.strip.split(/\s+/) << ''
+                else
+                  partial.strip.split(/\s+/)
+                end
+        cword = [words.size - 1, 0].max
+        comp_words = words.map { |w| Shellwords.shellescape(w) }.join(' ')
+        comp_words += ' ""' unless has_trailing_space
+        script = Shellwords.shellescape(find_script(command))
+        cmd = "source #{Shellwords.shellescape(BASH_COMPLETION_MAIN)} 2>/dev/null; source #{script} 2>/dev/null; COMP_WORDS=(#{comp_words}); COMP_CWORD=#{cword}; COMPREPLY=(); #{Shellwords.shellescape(func)} 2>/dev/null; IFS=; printf '%s\\n' \"\${COMPREPLY[@]}\""
+        return CACHE[cmd] if CACHE.key?(cmd)
+        raw = nil
+        Tempfile.create('yarsh_completion') do |f|
+          f.write(cmd)
+          f.close
+          raw = `timeout 4 bash #{f.path} 2>/dev/null`.strip
+        end
+        CACHE[cmd] = raw
+        CACHE.delete_if { |_, v| v.nil? || v.empty? } if CACHE.size > 100
+        raw
+      rescue
+        nil
+      end
+
+      def bash_invoke_complete_subcommand(command, partial)
+        has_trailing_space = partial.end_with?(' ')
+        words = partial.strip.split(/\s+/)
+        return nil if words.size > 2
+
+        # Don't invoke __complete for privileged commands (prompts for password)
+        return nil if PRIVILEGED_COMMANDS.include?(command)
+
+        # Don't invoke __complete when only the command + space is typed (no arg yet)
+        return nil if has_trailing_space && words.size == 1
+
+        last_word = has_trailing_space ? '' : (words.last || '')
+        raw = `timeout 4 #{Shellwords.shellescape(command)} __complete #{Shellwords.shellescape(last_word)} 2>/dev/null`.strip
+        return nil if raw.empty?
+
+        # Filter to only lines that contain tab-separated data
+        tab_lines = raw.each_line.select { |line| line.include?("\t") }
+        return nil if tab_lines.empty?
+
+        results = tab_lines.map { |line| line.split("\t").first }.reject(&:empty?)
+        return nil if results.empty?
+
+        # If the only result is the last_word itself, try subcommand completion
+        if results.size == 1 && results.first == last_word
+          sub_cmd = words[1..-1].join(' ')
+          if sub_cmd && !sub_cmd.empty?
+            sub_raw = `timeout 4 #{Shellwords.shellescape(command)} #{Shellwords.shellescape(sub_cmd)} __complete 2>/dev/null`.strip
+            return nil if sub_raw.empty? || !sub_raw.include?("\t")
+            sub_tab_lines = sub_raw.each_line.select { |line| line.include?("\t") }
+            return nil if sub_tab_lines.empty?
+            sub_results = sub_tab_lines.map { |line| line.split("\t").first }.reject(&:empty?)
+            return nil if sub_results.empty?
+            results = sub_results
+          end
+        end
+        results
+      rescue
+        nil
+      end
+    end
+  end
+end

data/lib/yarsh/completion/engine.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Yarsh
+  module Completion
+    class Engine
+      PRIVILEGED_COMMANDS = %w[sudo doas pkexec su].freeze
+
+      def complete(command, word, args = [])
+        raise NotImplementedError, "Subclasses must implement #complete"
+      end
+
+      def supports?(command)
+        false
+      end
+    end
+  end
+end