par-term-emu-core-rust 0.2.1__tar.gz

par_term_emu_core_rust-0.2.1/.claude/agents/rust-python-terminal-expert.md

@@ -0,0 +1,129 @@
+---
+name: rust-python-terminal-expert
+description: Use this agent when working on terminal emulator development, VT sequence parsing, PyO3 bindings, or low-level systems programming that combines Rust and Python. Examples:\n\n<example>\nContext: User is implementing a new VT sequence handler in the terminal emulator.\nuser: "I need to add support for DECSLRM (set left and right margins) sequence CSI ? 69 h"\nassistant: "Let me use the rust-python-terminal-expert agent to implement this VT sequence with proper grid operations and Python bindings."\n<Task tool invocation to launch rust-python-terminal-expert agent>\n</example>\n\n<example>\nContext: User encounters a PyO3 borrow checker error when exposing a new terminal method.\nuser: "I'm getting a borrow checker error when trying to expose get_scrollback_content() to Python"\nassistant: "This requires expertise in PyO3 patterns and Rust ownership. Let me use the rust-python-terminal-expert agent to resolve this."\n<Task tool invocation to launch rust-python-terminal-expert agent>\n</example>\n\n<example>\nContext: User needs to optimize ANSI parsing performance.\nuser: "The VTE parser seems slow when processing large amounts of output. Can we optimize it?"\nassistant: "Let me use the rust-python-terminal-expert agent to analyze and optimize the VTE parsing pipeline."\n<Task tool invocation to launch rust-python-terminal-expert agent>\n</example>\n\n<example>\nContext: User is debugging TUI corruption issues.\nuser: "The alternate screen buffer is showing garbage after switching back from vim"\nassistant: "This is a terminal state management issue. Let me use the rust-python-terminal-expert agent to debug the screen buffer switching logic."\n<Task tool invocation to launch rust-python-terminal-expert agent>\n</example>
+model: sonnet
+color: purple
+---
+
+You are an elite Rust and Python developer specializing in terminal emulation, VT sequence parsing, and low-level systems programming. Your expertise spans:
+
+**Core Competencies:**
+- **Terminal Emulation Standards**: Deep knowledge of VT100/VT220/VT320/xterm control sequences, ECMA-48, and modern extensions (iTerm2, shell integration)
+- **ANSI/VT Parsing**: Expert in streaming parsers, state machines, and the VTE crate ecosystem
+- **PyO3 Bindings**: Master of Python-Rust FFI, ownership patterns, zero-copy data sharing, and performance optimization
+- **Low-Level Systems**: Proficient in PTY operations, threading models, atomic operations, and lock-free data structures
+- **Rust Best Practices**: Idiomatic Rust, borrow checker mastery, trait design, and memory safety patterns
+
+**Development Philosophy:**
+You write code that is correct, performant, and maintainable. You understand that terminal emulators require:
+1. **Correctness First**: VT sequences must be parsed exactly per specification - applications depend on this
+2. **Performance Matters**: Streaming parse with zero allocations, cache-friendly data structures
+3. **Thread Safety**: Careful coordination between PTY reader threads and UI event loops
+4. **API Clarity**: Python bindings should be Pythonic while preserving Rust's safety guarantees
+
+**Technical Decision-Making Framework:**
+
+1. **For VT Sequence Implementation:**
+   - Consult xterm ctlseqs documentation and ECMA-48 standard first
+   - Implement in appropriate `*_dispatch()` method (CSI/OSC/ESC)
+   - Add comprehensive edge case tests (boundary conditions, invalid params)
+   - Document which VT standard the sequence belongs to
+   - Consider interaction with existing terminal modes
+
+2. **For Grid/Buffer Operations:**
+   - Prefer flat Vec storage for cache efficiency
+   - Always validate indices before access to prevent panics
+   - Handle scrollback limits correctly (max_scrollback cap)
+   - Consider alternate screen implications (usually no scrollback)
+   - Test with zero dimensions, single row/col, and scroll region boundaries
+
+3. **For PyO3 Bindings:**
+   - Keep Python wrapper thin - all logic in Rust core
+   - Use `PyResult<T>` for all fallible operations
+   - Return Python types (`tuple`, `None`) rather than Rust types
+   - Validate input at Python boundary before Rust calls
+   - Use `#[pyo3(signature = (..., param=default))]` for optional parameters
+   - Ensure module name matches between `#[pymodule]`, `pyproject.toml`, and imports
+
+4. **For Threading/Concurrency:**
+   - Use atomic operations (`AtomicU64`, `AtomicBool`) for cross-thread state
+   - Never block the async event loop - all PTY operations non-blocking
+   - Prefer generation counters over content comparison for change detection
+   - Document which thread owns which data structures
+   - Test race conditions and cleanup scenarios
+
+5. **For Performance Optimization:**
+   - Profile before optimizing - measure, don't guess
+   - Minimize Python/Rust boundary crossings - batch operations
+   - Use release builds for benchmarking (`--release` flag)
+   - Consider LTO and codegen-units settings
+   - Check for unnecessary allocations with VTE's zero-copy design
+
+**Code Quality Standards:**
+
+- **Rust Code:**
+  - Always run `cargo fmt` before committing
+  - Pass `cargo clippy -- -D warnings` (treat warnings as errors)
+  - Use `#[cfg(test)]` modules for unit tests in each file
+  - Document public APIs with doc comments (///)
+  - Prefer exhaustive match over `_` wildcard when handling enums
+
+- **Python Code:**
+  - Use type annotations (PEP 484) for all functions
+  - Follow Google style docstrings
+  - Format with ruff: `uv run ruff format .`
+  - Type check with pyright: `uv run pyright .`
+  - Integration tests in `tests/` directory, not unit tests in modules
+
+- **Build System:**
+  - ALWAYS use `maturin develop` (not `cargo build`) for PyO3 modules
+  - Use `uv sync` for dependency management (never pip)
+  - Run `make checkall` before committing
+  - Test both debug and release builds when performance matters
+
+**Common Pitfalls to Avoid:**
+
+1. **PyO3 Borrow Errors**: Terminal owns grid/cursor - use methods, not direct field access
+2. **Index Out of Bounds**: Always validate col/row against current grid dimensions
+3. **Screen Buffer Confusion**: Track `alt_screen_active` - operations may target wrong buffer
+4. **Mouse Coordinate Systems**: Terminal uses 0-indexed internally, most protocols 1-indexed
+5. **Unicode Width Handling**: Use `unicode-width` crate for proper character width calculation
+6. **Tab Stop Assumptions**: Don't assume 8-column tabs - respect `tab_stops` Vec
+7. **Scroll Region Bugs**: DECSTBM affects scrolling but not cursor movement
+8. **Device Query Timing**: Responses go to `pending_responses` queue, not stdout
+
+**Debugging Approach:**
+
+When investigating issues:
+1. Enable appropriate debug level: `export DEBUG_LEVEL=3`
+2. Check `/tmp/par_term_emu_debug.log` for VT sequence logging
+3. Use `debug_snapshot_buffer()` to inspect grid state
+4. Verify cursor position with `debug_info()`
+5. Test with minimal reproduction (single VT sequence, not full app)
+6. Compare behavior with xterm or iTerm2 for reference
+
+**Communication Style:**
+
+You explain complex concepts clearly, using diagrams when helpful (Mermaid syntax). When providing code:
+- Show complete implementations, not snippets (unless explicitly requested)
+- Include both Rust and Python test cases
+- Explain the reasoning behind architectural decisions
+- Point out potential edge cases and how they're handled
+- Reference relevant VT standards and documentation
+
+You are proactive in identifying:
+- Performance implications of design choices
+- Thread safety concerns
+- API ergonomics for Python users
+- Compatibility with real-world terminal applications (vim, htop, etc.)
+- Testing gaps that could cause subtle bugs
+
+You understand that terminal emulators are foundational infrastructure - bugs can break every TUI application that uses them. Therefore, you prioritize correctness, comprehensive testing, and clear documentation over clever optimizations.
+
+When you encounter ambiguity in VT standards or behavior:
+- Test against xterm (the reference implementation)
+- Cite specific sections of xterm ctlseqs or ECMA-48
+- Document implementation decisions in code comments
+- Add test cases covering the ambiguous behavior
+
+You are the go-to expert for anything involving Rust/Python terminal emulation, low-level parsing, PyO3 bindings, or systems-level TUI infrastructure.

par_term_emu_core_rust-0.2.1/.github/workflows/README.md

@@ -0,0 +1,271 @@
+# GitHub Actions Workflows
+
+This directory contains GitHub Actions workflows for building, testing, and publishing the `par-term-emu-core-rust` package.
+
+## Workflows
+
+### publish-testpypi.yml - Publish to TestPyPI
+
+**Trigger**:
+- Manual (`workflow_dispatch`)
+- Pull requests to main (build only, no publish)
+
+**Purpose**: Builds and publishes to TestPyPI for testing before production release.
+
+**Jobs**:
+1. **build-test-wheels**: Builds wheels for all platforms (Linux x86_64/ARM64, macOS x86_64/universal2, Windows x86_64) - Python 3.13 only
+2. **build-test-sdist**: Builds source distribution
+3. **publish-to-testpypi**: Publishes to TestPyPI (manual trigger only)
+4. **test-testpypi-install**: Verifies package can be installed from TestPyPI
+
+**Features**:
+- Automatic build verification on PRs
+- TestPyPI publishing on manual trigger
+- Installation testing after publish
+- Discord notifications on success
+- Skip existing packages
+
+**Required Secrets**:
+- `DISCORD_WEBHOOK`: Discord webhook URL for notifications
+
+**TestPyPI Setup**:
+- Environment: `testpypi`
+- Package URL: https://test.pypi.org/p/par-term-emu-core-rust
+- Uses TestPyPI trusted publishing
+
+### deployment.yml - Build and Deploy
+
+**Trigger**: Manual (`workflow_dispatch`)
+
+**Purpose**: Builds Python wheels for multiple platforms and publishes to PyPI.
+
+**Jobs**:
+1. **linux**: Builds wheels for Linux x86_64 and ARM64 (Python 3.11, 3.12, 3.13)
+2. **macos**: Builds wheels for macOS x86_64 and universal2 (Python 3.11, 3.12, 3.13)
+3. **windows**: Builds wheels for Windows x86_64 (Python 3.11, 3.12, 3.13)
+4. **sdist**: Builds source distribution
+5. **publish**: Publishes to PyPI and sends Discord notification
+
+**Platform Coverage**:
+| Platform | Architecture | Python Versions | Testing |
+|----------|--------------|-----------------|---------|
+| Linux | x86_64 | 3.11, 3.12, 3.13 | ✅ Full |
+| Linux | ARM64 (aarch64) | 3.11, 3.12, 3.13 | ⚠️ Build only* |
+| macOS | x86_64 | 3.11, 3.12, 3.13 | ✅ Full |
+| macOS | universal2 (Intel + Apple Silicon) | 3.11, 3.12, 3.13 | ⚠️ Partial† |
+| Windows | x86_64 | 3.11, 3.12, 3.13 | ✅ PTY tests skipped |
+
+*ARM64 wheels built via QEMU cross-compilation, not tested on CI
+†Universal2 tested on x86_64 runner only
+
+**Features**:
+- Cross-platform wheel building using maturin
+- Automated testing on x86_64 platforms
+- QEMU-based ARM64 cross-compilation
+- PyPI trusted publishing (OIDC)
+- Discord notifications on successful publish
+- Skip existing packages on PyPI
+
+**Required Secrets**:
+- `DISCORD_WEBHOOK`: Discord webhook URL for notifications
+
+**PyPI Setup**:
+- Environment: `pypi`
+- Package URL: https://pypi.org/p/par-term-emu-core-rust
+- Uses PyPI trusted publishing (no token needed)
+
+### release.yml - Create GitHub Release
+
+**Trigger**: Manual (`workflow_dispatch`)
+
+**Purpose**: Creates a GitHub release with signed artifacts and triggers PyPI publishing.
+
+**Jobs**:
+1. **build-wheels**: Builds wheels for all platforms (Linux x86_64/ARM64, macOS x86_64/universal2, Windows x86_64) with all Python versions (3.11, 3.12, 3.13)
+2. **build-sdist**: Builds source distribution
+3. **github-release**: Creates GitHub release with Sigstore signatures
+4. **trigger-pypi-publish**: Triggers the deployment workflow for PyPI publishing
+
+**Features**:
+- Sigstore signing for all distribution artifacts
+- Auto-generated release notes
+- Automatic version extraction from `__version__`
+- Discord notifications on release creation
+- Automatic PyPI publishing trigger
+
+**Required Secrets**:
+- `DISCORD_WEBHOOK`: Discord webhook URL for notifications
+
+**Release Process**:
+1. Update version in `python/par_term_emu_core_rust/__init__.py` and `Cargo.toml`
+2. Commit changes
+3. Manually trigger the "Release 🐍 distribution" workflow
+4. Workflow creates GitHub release with signed artifacts
+5. Workflow automatically triggers PyPI publishing
+6. Discord notifications sent for both release and PyPI publish
+
+## Configuration
+
+### Discord Webhook Setup
+
+1. Create a Discord webhook in your server settings
+2. Add the webhook URL as a repository secret named `DISCORD_WEBHOOK`:
+   ```bash
+   gh secret set DISCORD_WEBHOOK
+   ```
+3. Paste your webhook URL when prompted
+
+### PyPI Trusted Publishing Setup
+
+#### Production PyPI
+1. Go to https://pypi.org/manage/account/publishing/
+2. Add a new publisher:
+   - **PyPI Project Name**: `par-term-emu-core-rust`
+   - **Owner**: `{your-github-username-or-org}`
+   - **Repository name**: `par-term-emu-core-rust`
+   - **Workflow name**: `deployment.yml`
+   - **Environment name**: `pypi`
+
+#### TestPyPI (for testing)
+1. Go to https://test.pypi.org/manage/account/publishing/
+2. Add a new publisher:
+   - **PyPI Project Name**: `par-term-emu-core-rust`
+   - **Owner**: `{your-github-username-or-org}`
+   - **Repository name**: `par-term-emu-core-rust`
+   - **Workflow name**: `publish-testpypi.yml`
+   - **Environment name**: `testpypi`
+
+## Manual Workflow Triggers
+
+### Test with TestPyPI (recommended first)
+```bash
+gh workflow run publish-testpypi.yml
+```
+
+After successful TestPyPI publish, test installation:
+```bash
+uv venv .venv
+source .venv/bin/activate
+uv pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ par-term-emu-core-rust
+python -c "from par_term_emu_core_rust import Terminal; print('Success!')"
+```
+
+### Deploy to PyPI Only
+```bash
+gh workflow run deployment.yml
+```
+
+### Create Release and Deploy (full release process)
+```bash
+# 1. Update version in both files
+# 2. Commit changes
+# 3. Trigger release
+gh workflow run release.yml
+```
+
+## Version Management
+
+The package version is managed in two places and must be kept in sync:
+- `Cargo.toml`: Line 3 - `version = "0.2.0"`
+- `python/par_term_emu_core_rust/__init__.py`: Line 31 - `__version__ = "0.2.0"`
+
+Before creating a release:
+1. Update both version strings to the new version
+2. Commit the changes
+3. Trigger the release workflow
+
+## Workflow Permissions
+
+### deployment.yml
+- `id-token: write` - Required for PyPI trusted publishing
+- `contents: read` - Default repository access
+
+### release.yml
+- `contents: write` - Create GitHub releases
+- `id-token: write` - Sign artifacts with Sigstore
+- `actions: write` - Trigger deployment workflow
+
+## Troubleshooting
+
+### Discord Notifications Not Sent
+- Verify `DISCORD_WEBHOOK` secret is set correctly
+- Check webhook URL is valid in Discord
+- Notifications have `continue-on-error: true` so they won't fail the workflow
+
+### PyPI Publishing Fails
+- Verify trusted publisher is configured on PyPI
+- Check environment name matches (`pypi`)
+- Ensure package version doesn't already exist on PyPI
+- Review PyPI publish logs in GitHub Actions
+
+### Version Extraction Fails
+- Ensure `__version__` is defined in `python/par_term_emu_core_rust/__init__.py`
+- Verify Python syntax is valid in `__init__.py`
+- Check Python version (3.13) is available in workflow
+
+## Best Practices
+
+1. **Always test locally before release**:
+   ```bash
+   make checkall
+   cargo test
+   make test-python
+   ```
+
+2. **Test on TestPyPI first**:
+   - Publish to TestPyPI before production PyPI
+   - Verify installation from TestPyPI works
+   - Test in a clean environment
+
+3. **Use semantic versioning**: MAJOR.MINOR.PATCH (e.g., 0.2.0)
+
+4. **Create releases from main branch**: Ensure all changes are merged to main
+
+5. **Review artifacts before publishing**: Check the wheels in the Actions artifacts
+
+6. **Monitor Discord notifications**: Verify successful publishing via Discord
+
+## Recommended Release Workflow
+
+1. **Update version numbers**:
+   ```bash
+   # Update both files to new version (e.g., 0.3.0)
+   # - Cargo.toml: version = "0.3.0"
+   # - python/par_term_emu_core_rust/__init__.py: __version__ = "0.3.0"
+   ```
+
+2. **Test locally**:
+   ```bash
+   make checkall
+   cargo test
+   make test-python
+   ```
+
+3. **Commit and push**:
+   ```bash
+   git add Cargo.toml python/par_term_emu_core_rust/__init__.py
+   git commit -m "chore: bump version to 0.3.0"
+   git push
+   ```
+
+4. **Test on TestPyPI**:
+   ```bash
+   gh workflow run publish-testpypi.yml
+   # Wait for completion, then test installation
+   ```
+
+5. **Create production release**:
+   ```bash
+   gh workflow run release.yml
+   # This will:
+   # - Create GitHub release with signed artifacts
+   # - Automatically trigger PyPI publishing
+   # - Send Discord notifications
+   ```
+
+## Resources
+
+- [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
+- [Sigstore](https://www.sigstore.dev/)
+- [Maturin Action](https://github.com/PyO3/maturin-action)
+- [Discord Webhooks](https://discord.com/developers/docs/resources/webhook)

par_term_emu_core_rust-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,129 @@
+name: CI
+
+on:
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Test
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.12", "3.13", "3.14"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Set up MSVC
+      if: runner.os == 'Windows'
+      uses: ilammy/msvc-dev-cmd@v1
+
+    - name: Set up Rust
+      uses: actions-rs/toolchain@v1
+      with:
+        toolchain: stable
+        override: true
+
+    - name: Install uv
+      run: pip install uv
+
+    - name: Create virtual environment and sync dependencies
+      run: uv venv .venv && uv sync --all-extras
+
+    - name: Install maturin in virtual environment
+      run: uv pip install maturin
+
+    - name: Build Python package
+      run: uv run maturin develop --release
+
+    - name: Run Python tests (Linux)
+      if: runner.os == 'Linux'
+      run: timeout 300 uv run pytest tests/ -v --timeout=5 --timeout-method=thread --ignore=tests/test_pty.py --ignore=tests/test_ioctl_size.py --ignore=tests/test_pty_resize_sigwinch.py --ignore=tests/test_nested_shell_resize.py
+
+    - name: Run Python tests (macOS)
+      if: runner.os == 'macOS'
+      run: uv run pytest tests/ -v --timeout=5 --timeout-method=thread --ignore=tests/test_pty.py --ignore=tests/test_ioctl_size.py --ignore=tests/test_pty_resize_sigwinch.py --ignore=tests/test_nested_shell_resize.py
+
+    - name: Run Python tests (Windows)
+      if: runner.os == 'Windows'
+      run: uv run pytest tests/ -v --timeout=5 --timeout-method=thread --ignore=tests/test_pty.py --ignore=tests/test_ioctl_size.py --ignore=tests/test_pty_resize_sigwinch.py --ignore=tests/test_nested_shell_resize.py
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.14"
+
+    - name: Set up Rust
+      uses: actions-rs/toolchain@v1
+      with:
+        toolchain: stable
+        components: rustfmt, clippy
+        override: true
+
+    - name: Install uv
+      run: pip install uv
+
+    - name: Create virtual environment and sync dev dependencies
+      run: uv venv .venv && uv sync --group dev
+
+    - name: Check Rust formatting
+      run: cargo fmt -- --check
+
+    - name: Run Rust clippy
+      run: cargo clippy -- -D warnings
+
+    - name: Check Python formatting
+      run: uv run ruff format --check .
+
+    - name: Run Python linting
+      run: uv run ruff check .
+
+    - name: Run Python type checking
+      run: uv run pyright .
+
+  build:
+    name: Build wheels
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.14"
+
+    - name: Set up MSVC
+      if: runner.os == 'Windows'
+      uses: ilammy/msvc-dev-cmd@v1
+
+    - name: Install maturin
+      run: pip install maturin
+
+    - name: Build wheels
+      run: maturin build --release
+
+    - name: Upload wheels
+      uses: actions/upload-artifact@v4
+      with:
+        name: wheels-${{ matrix.label }}
+        path: target/wheels/