ptylink 0.1.0__tar.gz

ptylink-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"

ptylink-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --dev
+      - name: Run tests
+        run: uv run python -m pytest tests/ -q
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Install dependencies
+        run: uv sync --dev
+      - name: mypy --strict
+        run: uv run mypy --strict src/ptylink/
+      - name: pyright
+        run: uv run pyright src/ptylink/
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Install dependencies
+        run: uv sync --dev
+      - name: Ruff check
+        run: uv run ruff check src/ tests/
+      - name: Ruff format check
+        run: uv run ruff format --check src/ tests/

ptylink-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build distribution
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ptylink-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.venv/
+.env
+.mypy_cache/
+.pyright/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+coverage/
+*.so

ptylink-0.1.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+> **Note:** This package was previously published as **tether**. It was renamed to **ptylink** after v0.1.0.
+> If you were using `tether`, update your dependency to `ptylink` and replace any `TetherError` references with `PtylinkError`.
+
+## v0.1.0 (2026-03-13)
+
+Initial release as `tether` — modern drop-in replacement for pexpect. Renamed to `ptylink` post-release.
+
+### Features
+
+- `Spawn` class with PTY-based process interaction
+- `AsyncSpawn`: native `async/await` (not `async_=True` hack)
+- `PopenSpawn`: pipe-based spawn for environments without PTY
+- `SSHSession`: SSH login/command helper built on Spawn
+- `run()` high-level function with events support
+- Pattern matching: regex, exact string, EOF, TIMEOUT sentinels
+- `strip_ansi()` and `has_ansi()` ANSI escape handling
+- `interact()` standalone function with input/output filters
+- pexpect compatibility shim (`ptylink.compat`)
+- Zero dependencies
+- Full type annotations — `mypy --strict` + `pyright strict` clean
+- Python 3.10+
+
+### Bug fixes vs pexpect
+
+- `before` attribute no longer contains leaked `sendline()` echo (#821)
+- No Python 3.12+ `ResourceWarning` on fork (#817)
+- No deprecated `asyncio.coroutine` usage (#677)
+
+### Performance
+
+- 3.6–95× faster than pexpect across all benchmarked operations

ptylink-0.1.0/PKG-INFO

@@ -0,0 +1,291 @@
+Metadata-Version: 2.4
+Name: ptylink
+Version: 0.1.0
+Summary: Modern process interaction library — expect-style automation with PTY support
+Project-URL: Homepage, https://github.com/agentine/ptylink
+Project-URL: Repository, https://github.com/agentine/ptylink
+Project-URL: Issues, https://github.com/agentine/ptylink/issues
+Author: Agentine
+License-Expression: ISC
+Keywords: automation,expect,pexpect,process,pty,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: ISC License (ISCL)
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pexpect>=4.9.0; extra == 'dev'
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ptylink
+
+[![CI](https://github.com/agentine/ptylink/actions/workflows/ci.yml/badge.svg)](https://github.com/agentine/ptylink/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ptylink)](https://pypi.org/project/ptylink/)
+[![Python](https://img.shields.io/pypi/pyversions/ptylink)](https://pypi.org/project/ptylink/)
+
+Modern process interaction library for Python — expect-style automation with PTY support.
+
+Drop-in replacement for [pexpect](https://github.com/pexpect/pexpect) with full type annotations, native async/await, and zero dependencies.
+
+## Why ptylink?
+
+| | pexpect | ptylink |
+|---|---|---|
+| **Type annotations** | No | Full (`mypy --strict` + `pyright strict`) |
+| **Async support** | Deprecated `@asyncio.coroutine` | Native `async/await` via `AsyncSpawn` |
+| **Python 3.12+ fork warning** | Yes (#817) | Fixed |
+| **`before` leaks sendline echo** | Yes (#821) | Fixed |
+| **Dependencies** | `ptyprocess` | Zero |
+| **Performance** | Baseline | 3.6–95× faster |
+
+## Installation
+
+```bash
+pip install ptylink
+```
+
+Requires Python 3.10+.
+
+## Quick Start
+
+```python
+import ptylink
+
+with ptylink.spawn("python3") as child:
+    child.expect(">>> ")
+    child.sendline("print(42)")
+    child.expect("42")
+    print(child.before)  # text before the match
+```
+
+## Context Manager
+
+```python
+from ptylink import Spawn
+
+with Spawn("ssh user@host") as child:
+    child.expect("password:")
+    child.sendline("secret")
+    child.expect(r"\$ ")
+    child.sendline("ls")
+    child.expect(r"\$ ")
+    print(child.before)
+```
+
+## Async Usage
+
+```python
+import asyncio
+from ptylink import AsyncSpawn
+
+async def main():
+    async with AsyncSpawn("python3") as child:
+        await child.expect(">>> ")
+        await child.sendline("1 + 1")
+        await child.expect("2")
+
+asyncio.run(main())
+```
+
+## Pipe-Based (No PTY)
+
+For environments without PTY support (e.g. Windows):
+
+```python
+from ptylink import PopenSpawn
+
+with PopenSpawn("echo hello") as child:
+    child.expect("hello")
+```
+
+## High-Level `run()`
+
+```python
+from ptylink import run
+
+# Simple command
+output = run("ls -la")
+
+# With exit status
+output, status = run("make test", withexitstatus=True)
+
+# Interactive with events
+output = run(
+    "sudo apt install foo",
+    events={"password:": "secret\n"},
+)
+```
+
+## SSH Sessions
+
+```python
+from ptylink import SSHSession
+
+with SSHSession("server.example.com", username="admin") as ssh:
+    ssh.login(password="secret")
+    output = ssh.run("uname -a")
+    print(output)
+```
+
+## Pattern Matching
+
+```python
+import re
+from ptylink import Spawn, EOF_TYPE, TIMEOUT_TYPE
+
+with Spawn("some_program") as child:
+    # String patterns (auto-escaped)
+    child.expect("login:")
+
+    # Regex patterns
+    child.expect(re.compile(r"[\$#] "))
+
+    # Multiple patterns — returns index of match
+    idx = child.expect_list(["error", "success", EOF_TYPE])
+    if idx == 0:
+        print("Error:", child.after)
+    elif idx == 1:
+        print("Success!")
+    elif idx == 2:
+        print("Process ended")
+```
+
+## API Reference
+
+### Classes and Functions
+
+- **`Spawn(command, *, timeout=30, encoding='utf-8', env=None, cwd=None)`** — PTY-based process interaction
+- **`spawn(command, *, timeout=30, encoding='utf-8')`** — Factory function; returns a `Spawn` instance
+- **`AsyncSpawn(command, ...)`** — Async version of Spawn
+- **`PopenSpawn(command, ...)`** — Pipe-based (no PTY) process interaction
+- **`SSHSession(server, *, username=None, port=22, password=None)`** — SSH session helper
+
+### Spawn Methods
+
+| Method | Description |
+|--------|-------------|
+| `expect(pattern, *, timeout=-1)` | Wait for pattern in output |
+| `expect_exact(pattern, *, timeout=-1)` | Wait for exact string |
+| `expect_list(patterns, *, timeout=-1)` | Wait for any pattern, return index |
+| `send(s)` | Send string to process |
+| `sendline(s='')` | Send string + newline |
+| `sendcontrol(char)` | Send control character (e.g. `'c'` for Ctrl-C) |
+| `sendeof()` | Send EOF (Ctrl-D) |
+| `read(size=-1)` | Read from process output |
+| `readline()` | Read a single line |
+| `isalive()` | Check if process is running |
+| `wait()` | Wait for exit, return exit code |
+| `close(force=True)` | Close process and PTY |
+| `setwinsize(rows, cols)` | Set terminal dimensions |
+| `interact()` | Interactive passthrough mode |
+
+### Attributes
+
+- `before` — Text before the last match
+- `after` — Text of the last match
+- `match` — Match object or string from last expect
+
+### Exceptions
+
+- `PtylinkError` — Base exception
+- `Timeout` — Expect timed out
+- `EOF` — Process closed output
+- `ExitStatus` — Process exited with non-zero status
+
+### Sentinels
+
+- `EOF_TYPE` — Use in pattern lists to match EOF without raising
+- `TIMEOUT_TYPE` — Use in pattern lists to match timeout without raising
+
+## ANSI Utilities
+
+```python
+from ptylink import strip_ansi, has_ansi
+
+clean = strip_ansi("\x1b[31mred text\x1b[0m")  # "red text"
+has_ansi("\x1b[1mbold\x1b[0m")  # True
+```
+
+## Migrating from tether
+
+This package was previously named **tether**. To upgrade:
+
+```bash
+pip uninstall tether
+pip install ptylink
+```
+
+Then update your imports and any exception references:
+
+```python
+# Before
+import tether
+from tether import TetherError
+
+# After
+import ptylink
+from ptylink import PtylinkError
+```
+
+All other APIs are identical.
+
+## pexpect Migration Guide
+
+### Zero-Change Migration
+
+```python
+# Before
+import pexpect
+
+# After — just change the import
+import ptylink.compat as pexpect
+```
+
+All pexpect names are available: `spawn`, `run`, `EOF`, `TIMEOUT`, `pxssh`.
+
+### Manual Migration
+
+| pexpect | ptylink |
+|---------|--------|
+| `pexpect.spawn(cmd)` | `ptylink.Spawn(cmd)` |
+| `pexpect.run(cmd)` | `ptylink.run(cmd)` |
+| `pexpect.EOF` | `ptylink.EOF_TYPE` |
+| `pexpect.TIMEOUT` | `ptylink.TIMEOUT_TYPE` |
+| `pexpect.pxssh.pxssh()` | `ptylink.SSHSession()` |
+| `pexpect.spawn(cmd, async_=True)` | `ptylink.AsyncSpawn(cmd)` |
+
+### Breaking Changes
+
+- `EOF` and `TIMEOUT` are sentinel types, not exception classes. Use `EOF_TYPE` and `TIMEOUT_TYPE` in pattern lists.
+- `async_=True` parameter is removed. Use `AsyncSpawn` instead.
+- `before` attribute no longer contains leaked `sendline()` echo text.
+
+## Fixes from pexpect
+
+- **#821** — `before` attribute no longer contains echoed `sendline()` input
+- **#817** — No `ResourceWarning` from `os.fork()` on Python 3.12+
+- **#677** — No deprecated `@asyncio.coroutine` usage; native `async def` throughout
+
+## Benchmarks
+
+| Operation | ptylink (us/op) | pexpect (us/op) | Speedup |
+|-----------|---------------:|----------------:|--------:|
+| spawn+expect (echo) | 3,002 | 285,821 | 95x |
+| spawn+expect (python) | 84,312 | 307,303 | 3.6x |
+| run (echo) | 3,352 | 163,946 | 49x |
+
+## License
+
+ISC

ptylink-0.1.0/PLAN.md

@@ -0,0 +1,266 @@
+# ptylink — Implementation Plan
+
+**Target:** Replace `pexpect` (pexpect/pexpect)
+**Package name:** `ptylink` (verified available on PyPI 2026-03-13)
+**License:** ISC
+**Python:** >= 3.10
+**Dependencies:** Zero (pure Python, PTY handling built-in)
+
+---
+
+## Problem Statement
+
+`pexpect` is the dominant Python library for controlling interactive programs in a pseudo-terminal with **149M downloads/month** (PyPI #152). It has:
+
+- **Two primary maintainers** (takluyver: 432 commits, jquast: 320 commits) — high bus factor risk
+- **Stale releases** — last release v4.9 on November 25, 2023 (2+ years ago); previous release v4.8 was January 2020
+- **165 open issues** including deprecated asyncio.coroutine usage (#677), Python 3.12 fork warnings (#817), ANSI leaks on macOS 3.14 (#824), bare except clauses (#826)
+- **Stale pull requests** — PRs from 2024-2026 unmerged (e.g., #826 basic cleanup, #822 dependency bump)
+- **No type annotations** — no py.typed, no mypy/pyright support
+- **Weak async support** — only `async_=True` parameter hack, uses deprecated `@asyncio.coroutine`
+- **Separate ptyprocess dependency** — also stale (last release v0.7.0, December 2020)
+- **Poor Windows support** — popen_spawn fallback only, no ConPTY
+- **No funding** — not on Tidelift, no GitHub Sponsors, no corporate backing
+- **No well-known replacement** — wexpect is Windows-only; no modern async-first expect library exists
+
+## Scope
+
+Modern process interaction library for controlling interactive CLI programs:
+
+1. **Process spawning** — PTY allocation (Unix), ConPTY (Windows 10+), Popen fallback
+2. **Pattern matching** — expect patterns on process output (regex, literal, EOF, TIMEOUT)
+3. **Input sending** — send, sendline, sendcontrol, sendeof, sendintr
+4. **Timeout handling** — per-operation and default timeouts
+5. **Session state** — before/after/match attributes for matched content
+6. **Interactive mode** — passthrough for manual interaction
+7. **High-level API** — run() for simple command execution with expect
+8. **SSH helper** — SSH session management (login, command execution)
+9. **Async support** — native async/await for all operations
+10. **pexpect compatibility** — drop-in shim for existing code
+
+## Architecture Overview
+
+```
+src/ptylink/
+├── __init__.py          # Public API exports
+├── py.typed             # PEP 561 marker
+├── _types.py            # Type aliases, protocols, sentinel types
+├── _errors.py           # Exception hierarchy (Timeout, EOF, ExitStatus)
+├── _pty.py              # PTY allocation and management (replaces ptyprocess)
+├── _spawn.py            # Spawn class — core process interaction
+├── _expect.py           # Pattern matching engine (compile, search, match)
+├── _interact.py         # Interactive passthrough mode
+├── _run.py              # High-level run() function
+├── _popen.py            # PopenSpawn — non-PTY spawn (Windows, pipes)
+├── _ssh.py              # SSH session helper (login, prompts, commands)
+├── _screen.py           # ANSI escape sequence handling
+├── _async.py            # AsyncSpawn — native async/await spawn
+└── _compat.py           # pexpect drop-in compatibility shim
+```
+
+### Key Design Decisions
+
+- **Private modules, public API via `__init__.py`** — all internal modules prefixed with `_`, public surface is `ptylink.spawn()`, `ptylink.run()`, `ptylink.Spawn`, etc.
+- **Async-first internals** — core I/O uses asyncio; sync API wraps async with `asyncio.run()` / event loop
+- **Built-in PTY** — PTY handling built directly into the library (no ptyprocess dependency)
+- **Context manager support** — `with ptylink.spawn("cmd") as child:` for automatic cleanup
+- **Compiled patterns** — expect patterns compiled once and reused
+- **Sentinel types** — `EOF` and `TIMEOUT` are proper singleton types, not magic integers
+- **Modern Python** — 3.10+ required; uses match statements, `|` union types, slots
+
+## Major Components
+
+### 1. Exception Hierarchy (`_errors.py`)
+
+```python
+class PtylinkError(Exception): ...          # Base
+class Timeout(PtylinkError): ...           # Expect timeout
+class EOF(PtylinkError): ...               # Process closed output
+class ExitStatus(PtylinkError):            # Process exited with error
+    status: int
+    signal: int | None
+```
+
+**Fix over pexpect:** Clear exception types with proper attributes. pexpect EOF/TIMEOUT are exception classes AND sentinel values — ptylink separates these concerns.
+
+### 2. PTY Management (`_pty.py`)
+
+```python
+class PtyProcess:
+    pid: int
+    fd: int
+
+    @classmethod
+    def spawn(cls, argv: list[str], ...) -> PtyProcess: ...
+    def read(self, size: int = 1024) -> bytes: ...
+    def write(self, data: bytes) -> int: ...
+    def setwinsize(self, rows: int, cols: int) -> None: ...
+    def waitpid(self) -> tuple[int, int]: ...
+    def terminate(self, force: bool = False) -> bool: ...
+    def isalive(self) -> bool: ...
+```
+
+Replaces ptyprocess with built-in PTY handling. Uses `pty.openpty()` + `os.fork()` on Unix with proper signal handling.
+
+**Fix over pexpect/ptyprocess:** Handles Python 3.12+ fork-with-threads warning (#817). Uses `os.login_tty()` on Python 3.13+.
+
+### 3. Spawn Class (`_spawn.py`)
+
+```python
+class Spawn:
+    before: str           # Text before last match
+    after: str            # Text that matched
+    match: re.Match | str | None
+
+    def __init__(self, command: str, *, timeout: float = 30, encoding: str = "utf-8", ...) -> None: ...
+    def __enter__(self) -> Spawn: ...
+    def __exit__(self, ...) -> None: ...
+    def expect(self, pattern: Pattern, *, timeout: float = -1) -> int: ...
+    def expect_exact(self, pattern: str | list[str], ...) -> int: ...
+    def expect_list(self, patterns: list[Pattern], ...) -> int: ...
+    def send(self, s: str) -> int: ...
+    def sendline(self, s: str = "") -> int: ...
+    def sendcontrol(self, char: str) -> int: ...
+    def sendeof(self) -> None: ...
+    def sendintr(self) -> None: ...
+    def read(self, size: int = -1) -> str: ...
+    def readline(self) -> str: ...
+    def isalive(self) -> bool: ...
+    def wait(self) -> int: ...
+    def close(self, force: bool = True) -> None: ...
+    def terminate(self, force: bool = False) -> bool: ...
+    def interact(self, ...) -> None: ...
+```
+
+**Fixes over pexpect:**
+- Context manager for automatic cleanup
+- `before` never contains input from `sendline` (#821)
+- No bare except clauses (#826)
+- Proper typing on all methods
+
+### 4. Pattern Matching (`_expect.py`)
+
+```python
+Pattern = str | re.Pattern[str] | type[EOF_TYPE] | type[TIMEOUT_TYPE]
+
+def compile_pattern(pattern: Pattern) -> CompiledPattern: ...
+def expect_loop(spawn: Spawn, patterns: list[CompiledPattern], timeout: float) -> int: ...
+```
+
+Patterns are compiled once. The expect loop uses `select.select()` (Unix) or polling for non-blocking reads.
+
+### 5. Async Spawn (`_async.py`)
+
+```python
+class AsyncSpawn:
+    async def expect(self, pattern: Pattern, *, timeout: float = -1) -> int: ...
+    async def send(self, s: str) -> int: ...
+    async def sendline(self, s: str = "") -> int: ...
+    async def read(self, size: int = -1) -> str: ...
+    async def __aenter__(self) -> AsyncSpawn: ...
+    async def __aexit__(self, ...) -> None: ...
+```
+
+**Fix over pexpect:** Native async/await, not retrofitted `async_=True` parameter. Uses `asyncio.get_event_loop().add_reader()` for non-blocking PTY reads. No deprecated `@asyncio.coroutine`.
+
+### 6. SSH Helper (`_ssh.py`)
+
+```python
+class SSHSession:
+    def __init__(self, server: str, *, username: str | None = None, port: int = 22, ...) -> None: ...
+    def login(self, ...) -> None: ...
+    def prompt(self, timeout: float = -1) -> bool: ...
+    def run(self, command: str, *, timeout: float = -1) -> str: ...
+    def logout(self) -> None: ...
+```
+
+Wraps Spawn for SSH connections with login automation and prompt detection.
+
+### 7. Popen Spawn (`_popen.py`)
+
+```python
+class PopenSpawn:
+    """Non-PTY spawn using subprocess.Popen. Works on Windows."""
+    # Same interface as Spawn but uses pipes instead of PTY
+```
+
+### 8. Compatibility Shim (`_compat.py`)
+
+Drop-in replacement for code using `import pexpect`:
+
+```python
+# ptylink.compat provides all pexpect public names
+from ptylink.compat import spawn, run, EOF, TIMEOUT
+from ptylink.compat import pxssh  # maps to ptylink.SSHSession
+```
+
+## Phases
+
+### Phase 1: Core — PTY, Spawn, Expect (Priority: highest)
+- Exception hierarchy
+- PTY process management (fork, pty, signals)
+- Spawn class with send/sendline/expect/expect_exact
+- Pattern matching engine (regex, literal, EOF, TIMEOUT)
+- Timeout handling
+- Context manager (with/as)
+- before/after/match state
+- isalive/wait/close/terminate
+- Unit tests for all core functionality
+
+### Phase 2: Advanced Features
+- expect_list (multiple pattern matching)
+- sendcontrol/sendeof/sendintr
+- interact() mode
+- run() high-level function
+- Logging/debugging support
+- Window size management (setwinsize)
+- ANSI escape sequence handling
+- Unit tests for advanced features
+
+### Phase 3: Extensions
+- AsyncSpawn — native async/await
+- PopenSpawn — non-PTY (pipes, Windows support)
+- SSHSession — SSH login/command helper
+- Unit tests for extensions
+
+### Phase 4: Quality & Compatibility
+- pexpect compatibility shim
+- Cross-verification tests (run same scenarios with pexpect and ptylink)
+- mypy --strict and pyright clean
+- Benchmarks vs pexpect
+- CI (GitHub Actions: Python 3.10, 3.11, 3.12, 3.13, ubuntu + macos)
+- pyproject.toml with full metadata
+
+### Phase 5: Documentation & Release
+- README.md with migration guide from pexpect
+- CHANGELOG.md
+- API reference (docstrings, all public functions)
+- Release v0.1.0 to PyPI
+
+## Deliverables
+
+- `projects/ptylink/` — complete Python package
+- Process spawning with PTY allocation
+- Expect-style pattern matching on process output
+- Native async/await support
+- SSH session helper
+- PopenSpawn for Windows/pipe-based operation
+- pexpect compatibility shim
+- 100% type-annotated, mypy/pyright strict clean
+- Comprehensive test suite with cross-verification
+- Benchmarks vs pexpect
+- CI pipeline
+- README with pexpect migration guide
+
+## Success Criteria
+
+- `ptylink.spawn("python3")` spawns process with PTY, expect/send works
+- `child.expect(r">>> ")` matches Python REPL prompt
+- `child.sendline("print('hello')")` sends input correctly
+- `child.before` contains output without leaked input (#821 fix)
+- `async with ptylink.AsyncSpawn("cmd") as child:` works with native async
+- `with ptylink.spawn("cmd") as child:` auto-cleans up on exit
+- No Python 3.12+ fork warnings (#817)
+- mypy --strict passes with zero errors
+- pytest passes on Python 3.10, 3.11, 3.12, 3.13
+- Benchmark within 2x of pexpect performance (targeting parity)