Skip to content

README.md

Latest commit

 

History

History
88 lines (73 loc) · 3.9 KB

README.md

File metadata and controls

88 lines (73 loc) · 3.9 KB
Raw

Source Code Documentation

This directory contains the core logic of Conch.

Directory Structure

  • conch.ts: Conch Class (Facade)
    • Provides the high-level API used by consumers.
    • Integrates ConchSession and ITerminalBackend, wrapping synchronization (Action Queue) and wait logic.
  • session.ts: ConchSession Class
    • The controller that bridges the backend (process) and the frontend (xterm screen).
    • Responsible for generating snapshots as "Facts", normalizing input, synchronizing resizes, etc.
  • types.ts: Common Type Definitions
    • ITerminalBackend (Interface for backends)
    • ISnapshot (Type definition for snapshots), etc.
  • keymap.ts: Keymap Definitions
    • Mappings between key names used in press / chord methods and ANSI escape sequences.
  • utils.ts: Wait & Locator Utilities
    • waitForText, waitForStable: Functions to wait for screen state changes.
    • cropText, findText: Functions to extract information from snapshots.
    • encodeScriptForShell: Cross-platform (Linux/macOS) shell script injection helper.
  • backend/: Backend Adapters
    • Contains backend implementations (LocalPty, DockerPty, SshPty). TmuxPty is planned.
  • index.ts: Entry Point
    • Exports the public API of the library.

Architecture

Conch follows the design philosophy of separating "Facts" from "Interpretation". Core focuses on maintaining accurate screen state, while leaving semantic interpretation to Userland (test code or agents).

graph TD
    subgraph Backend [Backend Adapters]
        LP[LocalPty]
        DP[DockerPty]
        SP[SshPty]
        TP[TmuxPty 🔜]
    end

    subgraph Core [Conch Core]
        Facade[Conch Facade]
        Session[ConchSession]
        Xterm[xterm-headless]
    end
    
    subgraph Utils [Userland Tools]
        Wait[Wait Utils]
        Locator[Locator Utils]
        Formatter[Formatter]
    end

    Human((Human / Telnet))
    Agent((AI Agent))

    %% Data Flow
    LP -->|onData| Session
    Session -->|write| Xterm
    
    %% Output
    Session -->|onOutput| Human
    
    %% Input
    Human -->|write| Facade
    Agent -->|run/press| Facade
    Facade -->|write| Session
    
    %% Snapshot & Analysis
    Agent -->|getSnapshot| Facade
    Facade -->|getSnapshot| Session
    Agent -.->|use| Wait
    Agent -.->|use| Locator
    Wait -.->|getSnapshot| Session
    Locator -.->|text/meta| Session
Loading

Core Responsibilities (Conch / ConchSession)

  • High-Level Control: Provides high-level flows like run() and pressAndSnapshot() that combine action, waiting, and snapshotting.
  • Terminal State: Accurately reflects and maintains output from the backend in the xterm buffer.
  • Terminal Query Auto-Responder: Intercepts terminal capability queries (DA1, DA2, CPR/DSR, DECRQM) from TUI applications (vim, less, nano, etc.) and writes standard responses back to the backend. Without this, xterm.js headless cannot answer these queries and TUI apps block on startup.
  • Facts Provider: Provides "facts" such as cursor position and viewport information through snapshots, not just text.
  • Input Normalization: Converts abstract operations like press('Enter') into appropriate escape sequences and sends them to the backend.
  • Shell Integration (OSC 133): Injects scripts that emit full A/B/C/D markers. Bash uses a DEBUG trap for the C marker; PowerShell uses a PSReadLine Enter handler. The C/D boundary enables deterministic output extraction in run().
  • Consistency: Guarantees timing consistency between asynchronous write operations and snapshot acquisition via drain().

Userland Responsibilities (Utils / User Code)

  • Interpretation: Application-specific semantics (e.g., "this is the selected line", "an error is displayed") are handled in Userland, not Core.
  • Formatting: Decorations such as adding line numbers or coloring are done through formatter.