tarazed 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a28326d4fd2fe32691844accc2f1c43100d77a356c69f9c24e86da2af8634cc
-  data.tar.gz: f8c9ea79ea97aa1fc8a2ee4218846d0a6bf29a300bea85006b4b84617d6b477b
+  metadata.gz: e7770f7ce8eac23698c2c294317d339ac24135b86b9f8203ee43f63229c1c4d4
+  data.tar.gz: d3aecd412f31417f961d10e07b683c07d2feeea3d5596b8d6218fde0a01e117d
 SHA512:
-  metadata.gz: 3ce64bd1794a8393be042fbd0e8004d024b34e3bc477a3e8b9067ac2e345cfad572f7245332024389208672bd075e6e3509465b9e388a28e1e901038f61d12b9
-  data.tar.gz: 3c7b4e9d94369ba16d7c870cc834d00b994bb67db87254ae2b326d305128fc4f1438959eb955d241083b30962f4cd49a0ae38b5f25c3af2a3a33e00cecbf5cce
+  metadata.gz: 5c6164054701b25e94dac45e3cd5359126f591d450a9ad1c817b9e2537c3117f77286c23354cc9a1b5585d7e991ca919f29085f5fcbab1d414305e97358f0e2a
+  data.tar.gz: 660218a61bf1017d59d90219d9beb040847ccaa8154b2f5dabdca23a0dff72d30a92e4537619a32808dec6d9ea65d64b5c67281e618f389d7978d3ab9c38d7d5

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## Unreleased
+
+## 0.2.1 - 2026-09-16
+
+- Report and cache natural Windows ConPTY process exit status through the cross-platform `PTY#status` API.
+
+## 0.2.0 - 2026-09-16
+
+- Track OSC 133 command boundaries, input, output rows, exit status, and OSC 7 working directories in bounded history.
+- Add a pump-oriented `Tarazed::Session` API and shell integration snippets for bash, zsh, and fish.
+
 ## 0.1.0 - 2026-09-16
 
 - Initial release.

data/README.md

@@ -1,9 +1,40 @@
-# Tarazed
+<h1 align="center">Tarazed</h1>
+
+<p align="center">
+  <strong>Pure Ruby terminal emulator core</strong>
+</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/tarazed"><img src="https://img.shields.io/gem/v/tarazed.svg?colorB=319e8c" alt="Gem Version"></a>
+  <a href="https://rubygems.org/gems/tarazed"><img src="https://img.shields.io/gem/dt/tarazed.svg" alt="Downloads"></a>
+  <img src="https://img.shields.io/badge/ruby-%3E%3D%203.1-ruby.svg" alt="Ruby Version">
+  <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> ·
+  <a href="#installation">Installation</a> ·
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#pty-sessions">PTY Sessions</a> ·
+  <a href="#command-history">Command History</a> ·
+  <a href="#shell-integration">Shell Integration</a>
+</p>
+
+---
 
 Tarazed is a pure Ruby terminal emulator core. It provides the
 terminal cell grid, scrollback, VT parser, keyboard/mouse encoding, and a
 POSIX or Windows ConPTY session without depending on an editor or UI toolkit.
 
+## Features
+
+- Unicode-aware cell grid with bounded scrollback
+- Chunk-safe VT parsing for terminal controls, input, links, and selection
+- Keyboard, mouse, bracketed-paste, and terminal-reply encoding
+- POSIX PTY and 64-bit Windows ConPTY sessions behind one API
+- OSC 133 command history and OSC 7 working-directory tracking
+- Packaged shell integration for bash, zsh, and fish
+
 ## Installation
 
 ```bash
@@ -12,7 +43,9 @@ bundle add tarazed
 
 Or run `gem install tarazed`.
 
-## Usage
+Tarazed supports Ruby 3.1 and later.
+
+## Quick Start
 
 Feed arbitrary byte chunks into a `VT`; incomplete UTF-8 and control sequences
 are retained until the next chunk.
@@ -26,6 +59,8 @@ terminal.feed("\e[32mready\e[0m\r\n")
 puts screen.text
 ```
 
+## PTY Sessions
+
 `Tarazed::PTY` owns a child process and feeds its output into the same grid.
 It uses a POSIX PTY on macOS and Linux and ConPTY on 64-bit Windows:
 
@@ -33,18 +68,46 @@ It uses a POSIX PTY on macOS and Linux and ConPTY on 64-bit Windows:
 terminal = Tarazed::PTY.new(command: ["/bin/sh"], columns: 80, rows: 24)
 terminal.write("printf 'hello\\n'\r")
 terminal.read(timeout: 0.1)
+puts terminal.status.exitstatus if !terminal.alive? && terminal.status
 terminal.close
 ```
 
 ConPTY requires a supported 64-bit Windows release and does not fall back to a
-pipe-only console. Shell integration and the higher-level `Screen`, `Parser`,
-and `Session` APIs remain future work.
+pipe-only console. After natural process exit, `status` provides `exited?`,
+`exitstatus`, `success?`, and `termsig` on every platform.
+
+## Command History
+
+`Tarazed::Session` adds a pump-oriented API and bounded OSC 133 command
+history. Command rows and output ranges use stable absolute history rows, and
+OSC 7 updates the session working directory:
+
+```ruby
+session = Tarazed::Session.new(command: ["/bin/bash"], columns: 80, rows: 24)
+session.pump(timeout: 0.05)
+session.commands.each do |command|
+  puts "#{command.exit_status}: #{command.input} (#{command.cwd})"
+end
+session.close
+```
+
+## Shell Integration
+
+Shell integration snippets for bash, zsh, and fish are packaged with the gem.
+An embedding application can inject one into a new interactive shell with
+`Tarazed::ShellIntegration.read(:bash)` (or `:zsh` / `:fish`). The snippets
+emit prompt, input, execution, and completion markers without changing the
+visible prompt.
 
 ## Development
 
-Run `bundle install`, then `bundle exec rake test`. Validate the signatures with
-`bundle exec rbs -I sig validate` and run the benchmark with
-`BUDGET=1 bundle exec rake bench`.
+```bash
+bundle install
+bundle exec rake test
+bundle exec rbs -I sig validate
+BUDGET=1 bundle exec rake bench
+gem build --strict tarazed.gemspec
+```
 
 ## Contributing
 
@@ -52,4 +115,4 @@ Bug reports and pull requests are welcome at https://github.com/noxdea/tarazed.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Tarazed is available under the [MIT License](LICENSE.txt).

data/assets/shell-integration/tarazed.bash

@@ -0,0 +1,44 @@
+# Tarazed shell integration for bash 3.2 and newer.
+if [[ -z ${TARAZED_SHELL_INTEGRATION-} ]]; then
+TARAZED_SHELL_INTEGRATION=1
+
+__tarazed_urlencode() {
+  local LC_ALL=C value=$1 output= character code hex index=0
+  while (( index < ${#value} )); do
+    character=${value:index:1}
+    case $character in
+      [a-zA-Z0-9.~_/-]) output=$output$character ;;
+      *)
+        printf -v code '%d' "'$character"
+        printf -v hex '%%%02X' "$((code & 255))"
+        output=$output$hex
+        ;;
+    esac
+    (( index += 1 ))
+  done
+  printf '%s' "$output"
+}
+
+__tarazed_prompt_command() {
+  local command_status=$1
+  printf '\e]133;D;%s\a\e]7;file://%s%s\e\\\e]133;A\e\\' \
+    "$command_status" "${HOSTNAME-}" "$(__tarazed_urlencode "$PWD")"
+  __tarazed_command_active=0
+}
+
+PROMPT_COMMAND="__tarazed_prompt_status=\$?${PROMPT_COMMAND:+;$PROMPT_COMMAND};__tarazed_prompt_command \"\$__tarazed_prompt_status\""
+PS1="${PS1-}\[\e]133;B\a\]"
+
+if (( BASH_VERSINFO[0] > 4 || (BASH_VERSINFO[0] == 4 && BASH_VERSINFO[1] >= 4) )); then
+  PS0="${PS0-}\[\e]133;C\a\]"
+else
+  __tarazed_command_active=1
+  __tarazed_preexec() {
+    if (( ! __tarazed_command_active )); then
+      __tarazed_command_active=1
+      printf '\e]133;C\e\\'
+    fi
+  }
+  trap '__tarazed_preexec' DEBUG
+fi
+fi

data/assets/shell-integration/tarazed.fish

@@ -0,0 +1,27 @@
+# Tarazed shell integration for fish.
+if not set -q TARAZED_SHELL_INTEGRATION
+set -g TARAZED_SHELL_INTEGRATION 1
+
+function __tarazed_cwd
+    set -l encoded (string escape --style=url -- $PWD)
+    set encoded (string replace -r '^%2[Ff]' '' -- $encoded)
+    printf '\e]7;file:///%s\e\\' $encoded
+end
+
+function __tarazed_preexec --on-event fish_preexec
+    printf '\e]133;C\e\\'
+end
+
+function __tarazed_postexec --on-event fish_postexec
+    set -l command_status $status
+    printf '\e]133;D;%s\a' $command_status
+end
+
+functions -c fish_prompt __tarazed_original_fish_prompt
+function fish_prompt
+    __tarazed_cwd
+    printf '\e]133;A\e\\'
+    __tarazed_original_fish_prompt
+    printf '\e]133;B\e\\'
+end
+end

data/assets/shell-integration/tarazed.zsh

@@ -0,0 +1,36 @@
+# Tarazed shell integration for zsh.
+if [[ -z ${TARAZED_SHELL_INTEGRATION-} ]]; then
+typeset -g TARAZED_SHELL_INTEGRATION=1
+
+__tarazed_urlencode() {
+  local LC_ALL=C value=$1 output= character code hex
+  integer index=1
+  while (( index <= ${#value} )); do
+    character=${value[index]}
+    case $character in
+      [a-zA-Z0-9.~_/-]) output+=$character ;;
+      *)
+        printf -v code '%d' "'$character"
+        printf -v hex '%%%02X' "$((code & 255))"
+        output+=$hex
+        ;;
+    esac
+    (( index += 1 ))
+  done
+  print -rn -- "$output"
+}
+
+__tarazed_precmd() {
+  local command_status=$?
+  printf '\e]133;D;%s\a\e]7;file://%s%s\e\\\e]133;A\e\\' \
+    "$command_status" "${HOST-}" "$(__tarazed_urlencode "$PWD")"
+}
+
+__tarazed_preexec() {
+  printf '\e]133;C\e\\'
+}
+
+precmd_functions=(__tarazed_precmd ${precmd_functions:#__tarazed_precmd})
+preexec_functions=(__tarazed_preexec ${preexec_functions:#__tarazed_preexec})
+PS1="${PS1-}"$'%{\e]133;B\a%}'
+fi

data/docs/adr/001-terminal-core-boundary.md

@@ -17,8 +17,8 @@ and Linux or a Fiddle-based ConPTY backend on 64-bit Windows. It depends
 directly on `unicode-display_width`; scrollback uses a bounded Array because
 the default 10,000-row limit does not justify a persistent tree dependency.
 
-Higher-level screen, parser, session, and shell integration APIs remain outside
-the extracted API.
+Higher-level screen and parser APIs remain outside the extracted API. Session
+and shell integration are deferred to ADR 002.
 
 ## Consequences
 

data/docs/adr/002-shell-integration.md

@@ -0,0 +1,27 @@
+# ADR 002: Derive shell history from terminal protocols
+
+- Status: Accepted
+- Date: 2026-09-15
+
+## Context
+
+Embedders need command boundaries, exit status, and working directories without
+parsing shell prompts or depending on a particular shell. Terminal output is an
+untrusted, chunked byte stream, and retained history must stay bounded.
+
+## Decision
+
+The existing VT parser consumes OSC 133 and OSC 7 alongside other bounded OSC
+sequences. Completed commands are immutable values retained in a count-bounded
+history. Rows are the grid's cumulative history coordinates, so later
+scrollback eviction does not change recorded ranges. Malformed markers and
+working-directory values do not enter the model.
+
+`Session` remains a thin PTY facade. Shell-specific behavior stays in packaged
+bash, zsh, and fish snippets instead of the emulator core.
+
+## Consequences
+
+Applications can navigate command output consistently on POSIX and ConPTY.
+Command input is reconstructed from retained terminal cells and is therefore
+limited by scrollback and a 64 KiB per-command cap.

data/docs/adr/README.md

@@ -1,3 +1,6 @@
 # Architecture decision records
 
 These records document Tarazed's durable boundaries.
+
+- [001: Keep terminal state independent of renderers](001-terminal-core-boundary.md)
+- [002: Derive shell history from terminal protocols](002-shell-integration.md)

data/lib/tarazed/grid.rb

@@ -33,6 +33,8 @@ module Tarazed
     def alternate? = !@alternate.nil?
     def lines = cells.map { |row| row.map(&:text).join.rstrip }
     def text = lines.join("\n")
+    def history_row = scrollback.total + cursor_y
+    def wrap_pending? = @wrap_pending
 
     def put(char)
       width = self.class.width(char)
@@ -45,6 +47,7 @@ module Tarazed
           width = [self.class.width(joined), columns].min
           if previous_x + width > columns && autowrap
             cells[cursor_y][previous_x] = blank
+            mark_wrapped(cells[cursor_y])
             carriage_return
             linefeed
             return put(joined)
@@ -66,6 +69,7 @@ module Tarazed
       width = 1 if width > columns
       if @wrap_pending || (width == 2 && cursor_x == columns - 1)
         if autowrap
+          mark_wrapped(cells[cursor_y])
           @cursor_x = 0
           linefeed
         elsif width == 2
@@ -104,6 +108,8 @@ module Tarazed
           end
           row.concat(Array.new(columns - row.length) { blank })
         end
+        @cells.each_with_index { |row, index| mark_wrapped(row) if index < @cells.length - 1 }
+        scrollback.advance(complete_rows - retained_complete_rows)
         @cursor_x = remainder.zero? ? columns - 1 : remainder
         @cursor_y = rows - 1
         @wrap_pending = remainder.zero?
@@ -283,10 +289,11 @@ module Tarazed
       validate_dimensions(columns, rows)
       previous_columns = @columns
       @columns, @rows = columns, rows
+      primary = alternate? ? @alternate : cells
       [cells, @alternate].compact.each do |screen|
         while screen.length > rows
           removed = screen.shift
-          scrollback.push(removed) unless alternate?
+          scrollback.push(removed) if screen.equal?(primary)
           @cursor_y -= 1 if screen.equal?(cells)
         end
         screen << blank_row while screen.length < rows
@@ -307,13 +314,17 @@ module Tarazed
     def selection(start, finish, history: false)
       source = history ? scrollback.to_a + cells : cells
       start, finish = finish, start if ([start[1], start[0]] <=> [finish[1], finish[0]]) == 1
-      (start[1]..finish[1]).map do |row|
-        next "" unless source[row]
+      parts = (start[1]..finish[1]).map do |row|
+        next ["", false] unless source[row]
 
         first = row == start[1] ? start[0] : 0
         last = row == finish[1] ? finish[0] : columns
-        source[row][first...last].to_a.map(&:text).join.rstrip
-      end.join("\n")
+        [source[row][first...last].to_a.map(&:text).join.rstrip, source[row].instance_variable_get(:@wrapped)]
+      end
+      parts.each_with_index.each_with_object(+"") do |((part, _), index), text|
+        text << "\n" if index.positive? && !parts[index - 1][1]
+        text << part
+      end
     end
 
     def links(row)
@@ -359,6 +370,7 @@ module Tarazed
 
     def blank = Cell.new(text: " ", width: 1, foreground: foreground, background: background, attributes: {}.freeze)
     def blank_row = Array.new(columns) { blank }
+    def mark_wrapped(row) = row.instance_variable_set(:@wrapped, true)
 
     def clear_wide(row, column)
       return unless column.between?(0, columns - 1)

data/lib/tarazed/pty.rb

@@ -5,10 +5,10 @@ require "shellwords"
 
 module Tarazed
   class PTY
-    attr_reader :reader, :writer, :pid, :grid, :vt, :status, :initial_cwd, :command_name
+    attr_reader :reader, :writer, :pid, :grid, :vt, :initial_cwd, :command_name
 
     def initialize(command: ENV.fetch("SHELL", "/bin/sh"), cwd: Dir.pwd, columns: 80, rows: 24, env: {},
-      scrollback: 10_000, queue_limit_bytes: 8_388_608)
+      scrollback: 10_000, queue_limit_bytes: 8_388_608, command_history_limit: 1_000, on_command: nil)
       unless queue_limit_bytes.is_a?(Integer) && queue_limit_bytes.positive?
         raise ArgumentError, "terminal queue limit must be a positive integer"
       end
@@ -21,7 +21,7 @@ module Tarazed
         command = nil if command == "/bin/sh"
         @native = Windows::ConPTY.new(command: command, cwd: cwd, columns: columns, rows: rows, env: env)
         @pid = @native.pid
-        @vt = VT.new(grid) { |bytes| write(bytes) }
+        @vt = VT.new(grid, command_limit: command_history_limit, on_command: on_command) { |bytes| write(bytes) }
         return
       end
 
@@ -34,7 +34,7 @@ module Tarazed
       @reader.binmode
       @writer.binmode
       @writer.sync = true
-      @vt = VT.new(grid) { |bytes| write(bytes) }
+      @vt = VT.new(grid, command_limit: command_history_limit, on_command: on_command) { |bytes| write(bytes) }
       resize(columns: columns, rows: rows)
       @queue, @queue_bytes, @queue_limit_bytes = [], 0, queue_limit_bytes
       @queue_lock, @queue_ready = Mutex.new, ConditionVariable.new
@@ -124,6 +124,8 @@ module Tarazed
       @foreground_name = nil
     end
 
+    def status = @native ? @native.status : @status
+
     def signal(name = "INT")
       return @native.write("\x03") if @native && name == "INT"
       if @native

data/lib/tarazed/scrollback.rb

@@ -4,12 +4,13 @@ module Tarazed
   class Scrollback
     include Enumerable
 
-    attr_reader :limit
+    attr_reader :limit, :total
 
     def initialize(limit)
       raise ArgumentError, "scrollback limit must be nonnegative" unless limit.is_a?(Integer) && limit >= 0
 
       @limit = limit
+      @total = 0
       clear
     end
 
@@ -20,10 +21,15 @@ module Tarazed
     def each(&block) = block ? @rows.each(&block) : enum_for(__method__)
 
     def push(cells)
+      advance(1)
       return if limit.zero?
 
       @rows.shift if @rows.length == limit
-      @rows << cells.map { |cell| cell.dup.tap { |copy| copy.text = copy.text.dup.freeze }.freeze }.freeze
+      row = cells.map { |cell| cell.dup.tap { |copy| copy.text = copy.text.dup.freeze }.freeze }
+      row.instance_variable_set(:@wrapped, true) if cells.instance_variable_get(:@wrapped)
+      @rows << row.freeze
     end
+
+    def advance(count) = @total += count
   end
 end

data/lib/tarazed/session.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Tarazed
+  class Session < PTY
+    def initialize(command:, env: {}, cwd: Dir.pwd, columns: 80, rows: 24, scrollback_limit: 10_000,
+      command_history_limit: 1_000, queue_limit_bytes: 8_388_608, on_command: nil)
+      super(command: command, env: env, cwd: cwd, columns: columns, rows: rows, scrollback: scrollback_limit,
+        command_history_limit: command_history_limit, queue_limit_bytes: queue_limit_bytes, on_command: on_command)
+    end
+
+    def screen = grid
+    def commands = vt.commands
+    def cwd = vt.cwd || initial_cwd
+    def input(bytes) = write(bytes)
+
+    def pump(timeout: 0)
+      bytes = read(timeout: timeout)
+      !bytes.nil? && !bytes.empty?
+    end
+  end
+end

data/lib/tarazed/shell_integration.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Tarazed
+  module ShellIntegration
+    NAMES = {bash: "tarazed.bash", zsh: "tarazed.zsh", fish: "tarazed.fish"}.freeze
+    private_constant :NAMES
+
+    module_function
+
+    def path(shell)
+      name = File.basename(shell.to_s).to_sym
+      file = NAMES.fetch(name) { raise ArgumentError, "unsupported shell: #{shell}" }
+      File.expand_path("../../assets/shell-integration/#{file}", __dir__)
+    end
+
+    def read(shell) = File.binread(path(shell))
+  end
+end

data/lib/tarazed/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tarazed
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

data/lib/tarazed/vt.rb

@@ -11,9 +11,17 @@ module Tarazed
 
     attr_reader :grid, :title, :cwd, :modes, :replies, :bell_count
 
-    def initialize(grid = Grid.new, &reply)
+    def initialize(grid = Grid.new, command_limit: 1_000, on_command: nil, &reply)
+      unless command_limit.is_a?(Integer) && command_limit >= 0
+        raise ArgumentError, "command history limit must be a nonnegative integer"
+      end
+
       @grid = grid
       @reply = reply
+      @on_command = on_command
+      @command_limit = command_limit
+      @commands = []
+      @next_command_id = 1
       @replies = []
       @input = +"".b
       @state = :ground
@@ -24,6 +32,8 @@ module Tarazed
       @bell_count = 0
     end
 
+    def commands = @commands.dup.freeze
+
     # The parser retains incomplete UTF-8 and control sequences between reads.
     def feed(bytes)
       @input << bytes.b
@@ -413,22 +423,101 @@ module Tarazed
     end
 
     def osc(sequence)
-      command, payload = sequence.force_encoding(Encoding::UTF_8).scrub.split(";", 2)
+      text = sequence.dup.force_encoding(Encoding::UTF_8)
+      valid_utf8 = text.valid_encoding?
+      command, payload = text.scrub.split(";", 2)
       return unless payload
 
       case command
       when "0", "2" then @title = payload
-      when "7"
-        uri = URI.parse(payload)
-        @cwd = URI.decode_uri_component(uri.path) if uri.scheme == "file" && uri.path&.start_with?("/")
+      when "7" then update_cwd(payload) if valid_utf8
       when "8"
         _, url = payload.split(";", 2)
         grid.hyperlink = url.nil? || url.empty? ? nil : url.freeze
+      when "133" then shell_marker(payload)
+      end
+    end
+
+    def update_cwd(payload)
+      match = /\Afile:\/\/([A-Za-z0-9._~%\-:\[\]]*)(\/.*)\z/.match(payload)
+      return unless match
+
+      path = URI.decode_uri_component(match[2])
+      return unless path.valid_encoding? && !path.match?(/[\x00-\x1f\x7f]/)
+
+      if Gem.win_platform?
+        drive_path = /\A\/[A-Za-z]:\//.match?(path)
+        path = path.delete_prefix("/") if drive_path
+        path = "//#{match[1]}#{path}" if !drive_path && !match[1].empty?
       end
-    rescue URI::InvalidURIError, ArgumentError
+      @cwd = path.freeze
+    rescue ArgumentError
       nil
     end
 
+    def shell_marker(payload)
+      case payload
+      when "A"
+        @pending_command = {id: @next_command_id, prompt_row: grid.history_row}
+        @next_command_id += 1
+      when "B"
+        if @pending_command && !@pending_command[:started_at]
+          @pending_command[:input_start] ||= grid.wrap_pending? ? [0, grid.history_row + 1] :
+            [grid.cursor_x, grid.history_row]
+        end
+      when "C"
+        start_command if @pending_command && !@pending_command[:started_at]
+      else
+        finish_command(payload.delete_prefix("D;")) if @pending_command && payload.start_with?("D;")
+      end
+    end
+
+    def start_command
+      @pending_command[:input] = command_input(@pending_command[:input_start])
+      @pending_command[:output_start] = grid.history_row
+      @pending_command[:started_at] = Time.now.freeze
+      @pending_command[:cwd] = cwd&.dup&.freeze
+    end
+
+    def finish_command(value)
+      return unless @pending_command[:started_at]
+      return unless /\A\d{1,10}\z/.match?(value)
+
+      status = value.to_i
+      return if status > 0xffffffff
+
+      pending = @pending_command
+      finished_at = Time.now.freeze
+      output_range = pending[:output_start] && (pending[:output_start]..grid.history_row).freeze
+      command = Command.new(id: pending[:id], prompt_row: pending[:prompt_row], input: (pending[:input] || "").freeze,
+        output_range: output_range, exit_status: status, started_at: pending[:started_at], finished_at: finished_at,
+        cwd: pending[:cwd] || cwd)
+      @pending_command = nil
+      @commands.shift if @commands.length == @command_limit && @command_limit.positive?
+      @commands << command if @command_limit.positive?
+      @on_command&.call(command)
+    end
+
+    def command_input(start)
+      return "" unless start
+      return "" if start[1] > grid.history_row
+
+      base = grid.scrollback.total - grid.scrollback.length
+      first = [start[1] - base, 0].max
+      last = grid.history_row - base
+      return "" if last.negative?
+
+      finish = grid.wrap_pending? ? grid.columns : grid.cursor_x
+      first_column = start[1] < base ? 0 : start[0]
+      input = grid.selection([first_column, first], [finish, last], history: true).sub(/\n+\z/, "")
+      if input.bytesize > 65_536
+        # ponytail: terminal cells are the source of truth; add explicit command metadata if 64 KiB commands matter.
+        input = input.byteslice(0, 65_536)
+        input = input.byteslice(0, input.bytesize - 1) until input.valid_encoding?
+      end
+      input
+    end
+
     def dcs(sequence)
       return unless sequence.start_with?("$q")
 

data/lib/tarazed/windows/conpty.rb

@@ -21,8 +21,23 @@ module Tarazed
     class ConPTY
       P, I, U, N, V = Fiddle::TYPE_VOIDP, Fiddle::TYPE_INT, Fiddle::TYPE_UINT, Fiddle::TYPE_SIZE_T,
         Fiddle::TYPE_VOID
+      STILL_ACTIVE = 259
       private_constant :P, :I, :U, :N, :V
 
+      class Status
+        attr_reader :exitstatus
+
+        def initialize(exitstatus)
+          @exitstatus = exitstatus
+          freeze
+        end
+
+        def exited? = true
+        def success? = exitstatus.zero?
+        def termsig = nil
+      end
+      private_constant :Status
+
       attr_reader :pid
 
       def initialize(command: nil, columns: 80, rows: 24, cwd: nil, env: {}, kernel: nil)
@@ -104,13 +119,17 @@ module Tarazed
         check_hresult(function(:ResizePseudoConsole, [P, I], I).call(@console, coordinate(columns, rows)))
       end
 
-      def alive?
-        !@closed && function(:WaitForSingleObject, [P, U], U).call(@process, 0) == 258
+      def status
+        refresh_status unless @closed
+        @status
       end
 
+      def alive? = !@closed && !status
+
       def close
         return self if @closed
 
+        safely { refresh_status }
         @closed = true
         close_handle(@input_write)
         @input_write = nil
@@ -128,6 +147,15 @@ module Tarazed
         @kernel.fn(name, arguments, result, need_gvl: need_gvl)
       end
 
+      def refresh_status
+        return @status if @status
+
+        code = [0].pack("I")
+        check(function(:GetExitCodeProcess, [P, P], I).call(@process, code), "GetExitCodeProcess")
+        value = code.unpack1("I")
+        @status = Status.new(value) unless value == STILL_ACTIVE
+      end
+
       def process_attributes(console)
         size = [0].pack("J")
         function(:InitializeProcThreadAttributeList, [P, U, U, P], I).call(0, 1, 0, size)

data/lib/tarazed.rb

@@ -9,4 +9,49 @@ require_relative "tarazed/pty"
 
 module Tarazed
   class Error < StandardError; end
+
+  module Value
+    module_function
+
+    def define(*members)
+      return Data.define(*members) if defined?(Data)
+
+      Struct.new(*members) do
+        members.each { |member| undef_method("#{member}=") }
+
+        def initialize(*values, **keywords)
+          if keywords.empty?
+            raise ArgumentError, "wrong number of arguments" unless values.length == self.class.members.length
+
+            super(*values)
+          else
+            raise ArgumentError, "cannot mix positional and keyword arguments" unless values.empty?
+
+            missing = self.class.members - keywords.keys
+            unknown = keywords.keys - self.class.members
+            raise ArgumentError, "missing keyword: #{missing.first.inspect}" unless missing.empty?
+            raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" unless unknown.empty?
+
+            super(*self.class.members.map { |member| keywords.fetch(member) })
+          end
+          freeze
+        end
+
+        def with(**changes)
+          return self if changes.empty?
+
+          unknown = changes.keys - self.class.members
+          raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" unless unknown.empty?
+
+          self.class.new(**to_h.merge(changes))
+        end
+      end
+    end
+  end
+
+  Command = Value.define(:id, :prompt_row, :input, :output_range, :exit_status, :started_at, :finished_at, :cwd)
+  private_constant :Value
 end
+
+require_relative "tarazed/shell_integration"
+require_relative "tarazed/session"

data/sig/tarazed.rbs

@@ -8,6 +8,24 @@ module Tarazed
   type attributes = Hash[Symbol, bool | Integer | [Integer, Integer, Integer]]
   type mouse_action = :press | :move | :release
 
+  class Command
+    attr_reader id: Integer
+    attr_reader prompt_row: Integer
+    attr_reader input: String
+    attr_reader output_range: Range[Integer]?
+    attr_reader exit_status: Integer
+    attr_reader started_at: Time?
+    attr_reader finished_at: Time
+    attr_reader cwd: String?
+
+    def self.new: (Integer id, Integer prompt_row, String input, Range[Integer]? output_range, Integer exit_status,
+      Time? started_at, Time finished_at, String? cwd) -> instance
+                | (id: Integer, prompt_row: Integer, input: String, output_range: Range[Integer]?,
+      exit_status: Integer, started_at: Time?, finished_at: Time, cwd: String?) -> instance
+    def with: (?id: Integer, ?prompt_row: Integer, ?input: String, ?output_range: Range[Integer]?,
+      ?exit_status: Integer, ?started_at: Time?, ?finished_at: Time, ?cwd: String?) -> Command
+  end
+
   class Cell < Struct[untyped]
     attr_accessor text: String
     attr_accessor width: Integer
@@ -24,6 +42,7 @@ module Tarazed
     include Enumerable[Array[Cell]]
 
     attr_reader limit: Integer
+    attr_reader total: Integer
 
     def initialize: (Integer limit) -> void
     def clear: () -> Array[Array[Cell]]
@@ -33,6 +52,7 @@ module Tarazed
     def each: () -> Enumerator[Array[Cell], Array[Array[Cell]]]
             | () { (Array[Cell]) -> void } -> Array[Array[Cell]]
     def push: (Array[Cell] cells) -> Array[Array[Cell]]?
+    def advance: (Integer count) -> Integer
   end
 
   class Grid
@@ -60,6 +80,8 @@ module Tarazed
     def alternate?: () -> bool
     def lines: () -> Array[String]
     def text: () -> String
+    def history_row: () -> Integer
+    def wrap_pending?: () -> bool
     def put: (String char) -> void
     def put_ascii: (String text) -> void
     def self.width: (String char) -> Integer
@@ -101,7 +123,8 @@ module Tarazed
     attr_reader replies: Array[String]
     attr_reader bell_count: Integer
 
-    def initialize: (?Grid grid) ?{ (String) -> void } -> void
+    def initialize: (?Grid grid, ?command_limit: Integer, ?on_command: ^(Command) -> untyped) ?{ (String) -> void } -> void
+    def commands: () -> Array[Command]
     def feed: (String bytes) -> self
     def paste: (String text) -> String
     def mouse: (button: Symbol | Integer | nil, column: Integer, row: Integer, ?action: mouse_action,
@@ -109,18 +132,26 @@ module Tarazed
     def key: (String | Symbol name, ?shift: bool, ?alt: bool, ?control: bool) -> String
   end
 
+  interface _PTYStatus
+    def exited?: () -> bool
+    def exitstatus: () -> Integer?
+    def success?: () -> bool?
+    def termsig: () -> Integer?
+  end
+
   class PTY
     attr_reader reader: IO?
     attr_reader writer: IO?
     attr_reader pid: Integer
     attr_reader grid: Grid
     attr_reader vt: VT
-    attr_reader status: Process::Status?
+    attr_reader status: _PTYStatus?
     attr_reader initial_cwd: String
     attr_reader command_name: String
 
     def initialize: (?command: String | Array[String], ?cwd: String, ?columns: Integer, ?rows: Integer,
-      ?env: Hash[String, String?], ?scrollback: Integer, ?queue_limit_bytes: Integer) -> void
+      ?env: Hash[String, String?], ?scrollback: Integer, ?queue_limit_bytes: Integer,
+      ?command_history_limit: Integer, ?on_command: ^(Command) -> untyped) -> void
     def read: (?timeout: Numeric, ?max_bytes: Integer, ?max_seconds: Numeric?) -> String?
     def pending?: () -> bool
     def write: (String bytes) -> Integer
@@ -136,4 +167,20 @@ module Tarazed
     def close: () -> self
   end
 
+  class Session < PTY
+    def initialize: (command: String | Array[String], ?env: Hash[String, String?], ?cwd: String,
+      ?columns: Integer, ?rows: Integer, ?scrollback_limit: Integer, ?command_history_limit: Integer,
+      ?queue_limit_bytes: Integer, ?on_command: ^(Command) -> untyped) -> void
+    def screen: () -> Grid
+    def commands: () -> Array[Command]
+    def cwd: () -> String
+    def input: (String bytes) -> Integer
+    def pump: (?timeout: Numeric) -> bool
+  end
+
+  module ShellIntegration
+    def self.path: (String | Symbol shell) -> String
+    def self.read: (String | Symbol shell) -> String
+  end
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tarazed
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Yudai Takada
@@ -46,14 +46,20 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- assets/shell-integration/tarazed.bash
+- assets/shell-integration/tarazed.fish
+- assets/shell-integration/tarazed.zsh
 - docs/adr/000-template.md
 - docs/adr/001-terminal-core-boundary.md
+- docs/adr/002-shell-integration.md
 - docs/adr/README.md
 - lib/tarazed.rb
 - lib/tarazed/cell.rb
 - lib/tarazed/grid.rb
 - lib/tarazed/pty.rb
 - lib/tarazed/scrollback.rb
+- lib/tarazed/session.rb
+- lib/tarazed/shell_integration.rb
 - lib/tarazed/version.rb
 - lib/tarazed/vt.rb
 - lib/tarazed/windows/conpty.rb
@@ -80,7 +86,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A pure Ruby terminal emulator core
 test_files: []