errlens-cli 0.1.0__tar.gz

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

@@ -0,0 +1,109 @@
+name: Release candidate and Trusted Publishing
+
+on:
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: Publish approved v0.1.0 to PyPI (false builds artifacts only)
+        required: true
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Verify distribution identity
+        run: |
+          python - <<'PY'
+          import tomllib
+          from pathlib import Path
+          project = tomllib.loads(Path('pyproject.toml').read_text())['project']
+          assert project['name'] == 'errlens-cli'
+          assert project['version'] == '0.1.0'
+          assert project['scripts']['errlens'] == 'errlens.cli:main_entry'
+          PY
+      - name: Require approved tag and successful Tests for publication
+        if: inputs.publish
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          test "$GITHUB_REPOSITORY" = 'ErrLens/errlens-cli'
+          test "$GITHUB_REF" = 'refs/tags/v0.1.0'
+          gh run list --repo "$GITHUB_REPOSITORY" --workflow tests.yml --commit "$GITHUB_SHA" --limit 20 --json headSha,status,conclusion > tests-runs.json
+          python - <<'PY'
+          import json, os
+          from pathlib import Path
+          runs = json.loads(Path('tests-runs.json').read_text())
+          assert runs, 'No Tests run exists for the selected commit'
+          latest = runs[0]
+          assert latest['headSha'] == os.environ['GITHUB_SHA']
+          assert latest['status'] == 'completed' and latest['conclusion'] == 'success', latest
+          PY
+      - name: Build and check archives
+        run: |
+          python -m pip install build twine
+          python -m build
+          python -m twine check --strict dist/*
+          python - <<'PY'
+          import email, zipfile
+          from pathlib import Path
+          assert {p.name for p in Path('dist').iterdir()} == {
+              'errlens_cli-0.1.0-py3-none-any.whl', 'errlens_cli-0.1.0.tar.gz'}
+          with zipfile.ZipFile('dist/errlens_cli-0.1.0-py3-none-any.whl') as z:
+              metadata = email.message_from_bytes(z.read('errlens_cli-0.1.0.dist-info/METADATA'))
+              assert metadata['Name'] == 'errlens-cli' and metadata['Version'] == '0.1.0'
+          PY
+      - name: Smoke-test installed wheel outside checkout
+        run: |
+          python -m venv .wheel-check
+          .wheel-check/bin/python -m pip install dist/*.whl pytest
+          .wheel-check/bin/python -m pip check
+          .wheel-check/bin/python -m pytest tests/integration/test_installed_package.py tests/integration/test_vt_forwarding.py tests/unit/test_cli.py
+      - name: Stage canonical artifacts and hashes
+        run: |
+          mkdir -p release-artifact/dist
+          cp dist/* release-artifact/dist/
+          cd release-artifact
+          sha256sum dist/* > SHA256SUMS
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-dist
+          path: release-artifact/
+          if-no-files-found: error
+          retention-days: 30
+
+  publish:
+    if: inputs.publish
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/errlens-cli
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-dist
+          path: candidate
+      - name: Verify retained bytes
+        run: cd candidate && sha256sum --check SHA256SUMS
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: candidate/dist/

errlens_cli-0.1.0/.github/workflows/tests-macos.yml

@@ -0,0 +1,27 @@
+name: Tests (macOS manual)
+
+on: workflow_dispatch
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.11', '3.12', '3.13']
+    runs-on: ${{ matrix.python == '3.11' && 'macos-15' || 'macos-latest' }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Verify shell prerequisites
+        run: command -v bash && command -v zsh
+      - name: Install development package
+        run: python -m pip install -e ".[dev]"
+      - name: Check types
+        run: python -m mypy
+      - name: Test editable package
+        run: python -m pytest

errlens_cli-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,61 @@
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ['3.11', '3.12', '3.13']
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install Zsh on Ubuntu
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y zsh
+      - name: Verify shell prerequisites
+        if: runner.os != 'Windows'
+        run: command -v bash && command -v zsh
+      - name: Verify PowerShell prerequisite
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: if ($PSVersionTable.PSVersion.Major -lt 7) { exit 1 }
+      - name: Install development package
+        run: python -m pip install -e ".[dev]"
+      - name: Check types
+        run: python -m mypy
+      - name: Test editable package
+        run: python -m pytest
+  package:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install build tools
+        run: python -m pip install build
+      - name: Build wheel and sdist
+        run: python -m build
+      - name: Create clean wheel environment
+        run: python -m venv .venv-wheel
+      - name: Test installed wheel outside editable environment
+        shell: python
+        run: |
+          import os
+          from pathlib import Path
+          import subprocess
+          python = Path('.venv-wheel') / ('Scripts/python.exe' if os.name == 'nt' else 'bin/python')
+          wheel = next(Path('dist').glob('*.whl'))
+          subprocess.run([str(python), '-m', 'pip', 'install', str(wheel), 'pytest'], check=True)
+          subprocess.run([str(python), '-m', 'pip', 'check'], check=True)
+          subprocess.run([str(python), '-m', 'pytest'], check=True)

errlens_cli-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+.venv/
+.venv-wheel/
+.venv-release/
+.venv-linux/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+build/
+dist/
+.coverage
+htmlcov/
+venv/
+.ruff_cache/
+.env
+.env.*
+!.env.example
+*.log
+*.tmp
+*.bak
+.idea/
+.vscode/

errlens_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## 0.1.0 — release candidate (unreleased)
+
+Initial CLI candidate. The package metadata remains `0.1.0`; no tag, release date
+or PyPI publication is implied by this entry.
+Distribution: `errlens-cli`; Python import: `errlens`; command: `errlens`.
+
+### Added
+
+- `errlens run` with streaming stdout/stderr, bounded diagnostic capture and
+  child exit-status propagation. Pipe is the default.
+- Rule-based offline explanations in Russian and English for recognized CPython
+  tracebacks, with conservative handling of incomplete diagnostics and chains.
+- Rich terminal cards and plain redirected explanations; `--lang` and `--no-explain`.
+- Explicit `--terminal-mode pty`: POSIX PTY on Linux/macOS and native ConPTY on Windows.
+- Opt-in PowerShell 7, Bash and Zsh integration for `python`, with explicit
+  install/status/uninstall, temporary bypass and profile backup/preservation.
+- MIT licensing, packaged translations, CI across Python 3.11–3.13 on three OSes,
+  wheel/sdist checks and recorded terminal acceptance evidence.
+
+### Fixed during candidate stabilization
+
+- Windows localized Unicode output with non-UTF-8 host text wrappers.
+- Darwin termios assertions account only for kernel-managed PENDIN state.
+- Diagnostic-only VT normalization preserves horizontal traceback indentation,
+  with bounded cursor/text expansion and conservative incomplete flags.
+
+### Limitations
+
+- Terminal mode merges child output and does not preserve binary identity.
+- Full-screen emulation, complex redraw/grapheme reconstruction, transparent
+  pipelines and automatic exception cards inside a successful REPL are not provided.
+- Shell integration is explicit and wraps only `python`; it does not intercept
+  arbitrary commands. No fixes or recommended commands are executed automatically.
+- Some physical host combinations remain NOT TESTED. The historical Zsh prompt
+  observation has no established root cause; a clean Zsh session was successful.
+- The original PyPI name `errlens` conflicts with an existing distribution.
+  The maintainer selected `errlens-cli` instead; publication still requires
+  Trusted Publisher setup and approval. See `docs/releasing.md`.

errlens_cli-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Участие в ErrLens
+
+Используйте Python 3.11+ и локальное виртуальное окружение. Инструкция установки
+находится в README. Перед предложением изменений запустите:
+
+```console
+python -m pytest
+python -m mypy
+python -m build
+```
+
+Описывайте проблему, область изменений и выполненные проверки. Добавляйте
+регрессионные тесты для исправляемого поведения. Не заявляйте проверку ОС,
+на которой тесты не выполнялись. Не включайте секреты или личные данные в fixtures.
+
+Сохраняйте независимость анализаторов от CLI, переводов и ввода-вывода.
+Не выполняйте рекомендации автоматически. Новые переводы должны иметь те же
+ключи и именованные параметры, что и русская локаль. Сторонние плагины и сетевые
+запросы не должны загружаться или запускаться неявно.
+
+Текущий CLI включает объяснения, shell-интеграции и явный PTY/ConPTY-режим.
+Команды рекомендаций должны оставаться display-only argv из доверенных правил;
+не подставляйте произвольные имена из traceback в shell-строки. Проверяйте plain
+text, узкие терминалы и буквальный вывод разметки/управляющих символов.
+Следующие возможности реализуются
+отдельно. Изменения распространяются на условиях MIT License проекта.

errlens_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ErrLens contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

errlens_cli-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include CONTRIBUTING.md
+include CHANGELOG.md
+include .gitignore
+recursive-include tests *.py *.md *.json
+recursive-include .github *.yml
+recursive-include docs *.md
+recursive-include experiments *.py

errlens_cli-0.1.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: errlens-cli
+Version: 0.1.0
+Summary: Local Python error explanations with opt-in terminal and shell integration.
+Author: ErrLens contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ErrLens/errlens-cli
+Project-URL: Source, https://github.com/ErrLens/errlens-cli
+Project-URL: Documentation, https://github.com/ErrLens/errlens-cli/blob/main/README.md
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer<1,>=0.16
+Requires-Dist: rich<15,>=14
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: build<2,>=1.2; extra == "dev"
+Requires-Dist: mypy<2,>=1.15; extra == "dev"
+Dynamic: license-file
+
+# ErrLens
+
+ErrLens is a local, open-source CLI that adds readable Russian or English explanations to recognized Python errors. It helps developers understand tracebacks without copying them to an external service. Explanations are rule-based and work offline after installation; no API key or AI model is required.
+
+ErrLens runs a command through `errlens run`. Its default pipe mode forwards the original stdout and stderr, then appends an explanation to stderr when an error is recognized. Optional shell wrappers intercept only `python`; explicit terminal mode uses merged terminal output.
+
+## Requirements and installation
+
+Python 3.11 or newer is required. On Windows, Linux or macOS, install from a local checkout:
+
+```console
+python -m pip install .
+```
+
+For development, use a virtual environment and install `python -m pip install -e ".[dev]"`. Installing dependencies requires an available package index or local wheels.
+
+The PyPI distribution name is **errlens-cli**; the Python import and executable
+are both **errlens**. This candidate has not been uploaded. After publication,
+install with `python -m pip install errlens-cli==0.1.0`, then run `errlens --version`.
+Until then use this checkout or a verified supplied wheel:
+`python -m pip install /path/to/errlens_cli-0.1.0-py3-none-any.whl`.
+The existing PyPI package named `errlens` is not the distribution selected for
+this repository. See [release preparation](https://github.com/ErrLens/errlens-cli/blob/main/docs/releasing.md).
+CI covers CPython 3.11–3.13; newer Python versions are not yet qualified.
+
+## Usage
+
+```console
+errlens --help
+errlens --version
+errlens run python main.py
+errlens run --lang en -- python main.py
+errlens run --no-explain -- python main.py
+errlens run python -c "print(undefined_variable)"
+```
+
+Russian is the default; `--lang en` selects English. Place ErrLens options before the executable; arguments after the executable belong to the child process. `--no-explain` skips analysis. The optional `--` makes the boundary explicit.
+
+The original traceback remains visible. For example, a `NameError` can be followed by an explanation that the name is unavailable in the current scope and suggestions to check its spelling and definition. Causes are described as possibilities, not established facts. Successful commands and nonzero exits without recognized diagnostics do not produce an explanation.
+
+## Supported diagnostics
+
+Rules cover `ModuleNotFoundError`, `ImportError`, `SyntaxError`, `IndentationError`, `TabError`, `NameError`, `TypeError`, `AttributeError`, `KeyError`, `FileNotFoundError` and `PermissionError`. Other structured exceptions receive a neutral notice. Incomplete diagnostics are marked as such; `ExceptionGroup` is summarized at its outer level. For a chain of exceptions, the final diagnostic is explained and linked predecessors are noted.
+
+Suggested commands are never executed. A pip command is shown only for the exact `requests` import and an explicitly specified absolute Python executable path, with a condition to confirm that the distribution is actually needed in that environment. Import names do not generally identify package names, and a missing module may be local.
+
+## Behavior and limitations
+
+- ErrLens launches argument sequences without `shell=True`. Shell pipelines and builtins are interpreted by the invoking shell, not by ErrLens. On Windows, the operating system may invoke a command interpreter for `.bat` or `.cmd` files even with `shell=False`.
+- Separate bounded buffers retain up to 1 MiB per stream for analysis. Original bytes are forwarded as they arrive; the diagnostic copy may be truncated. No output logs are saved to disk.
+- Pipes change `isatty()` and may affect child buffering and colors. Interactive programs, job control and full-screen applications are not guaranteed to work. The relative ordering of stdout and stderr cannot be reconstructed.
+- The child exit code is preserved for normal exits. On POSIX, signal termination becomes `128 + signal`; user interruption returns 130. Runner failures have their own codes: 125 for internal failures, 126 for permission errors, 127 for missing executables and 141 for broken pipes. Child programs can also use these codes; ErrLens identifies its own failures in stderr when possible.
+- In pipe mode, Ctrl+C handling uses a separate process group. Windows pipe cleanup does not guarantee termination of an arbitrary descendant tree. After the child exits, pipes held open by descendants are subject to a one-second drain timeout. ConPTY uses the Job Object cleanup described below.
+- Recognition targets standard CPython traceback formatting; IPython/Jupyter and logger-prefixed tracebacks are not supported. A traceback-like log can be ambiguous. Stdout diagnostics require a failed Python command. Unknown or incomplete data is not presented as a certain cause.
+- Rich markup and terminal control characters from diagnostic data are rendered literally or escaped in the ErrLens block. Redirected explanations are plain text without ANSI. Original child output is not sanitized.
+- Explanation fields are capped at 2,048 characters; linked exception messages at 256 characters. The forwarded traceback is not shortened by this limit.
+- ErrLens does not fix code, install packages, collect telemetry or contact a service. Shell wrappers and terminal mode are explicit opt-ins; VS Code extension support remains future work.
+
+## Opt-in PowerShell 7 integration (Windows)
+
+```powershell
+errlens shell install powershell
+errlens shell status powershell
+errlens shell uninstall powershell
+```
+
+Installation explicitly edits the current user's **all-hosts PowerShell 7 profile**
+(shared with VS Code), discovered using `pwsh -NoProfile`. Restart PowerShell after
+installation/removal. ExecutionPolicy is never changed; your policy must allow
+loading the profile and the integration script. No administrator access is needed.
+For an isolated trial or a custom host profile use `--profile 'path/to/profile.ps1'`
+on each management command, then dot-source that profile manually.
+
+An owned script is placed in an `ErrLens` subdirectory next to the selected profile.
+Only one guarded dot-source line is appended. Existing profile bytes are preserved;
+each modification of an existing profile creates a uniquely named backup alongside
+it. Backups are retained on removal. Edited connection lines and unowned integration
+files are refused rather than overwritten. A newly created profile is left empty
+after removal. Existing `python` aliases/functions are preserved with a warning.
+
+After loading, plain `python main.py`, `python -c "print(undefined_variable)"` and
+`python --version` delegate to `errlens run`. Only the command name `python` is
+wrapped. Absolute executable paths, `py`, pip and other commands bypass it.
+The native Python application is resolved from PATH on every invocation, so venv
+activation is respected. The ErrLens runtime is bound to the absolute Python path
+used during installation; `errlens` need not be in PATH. Keep that environment
+installed. To migrate it, uninstall the integration and reinstall from the new runtime.
+
+Temporarily bypass analysis with `$env:ERRLENS_DISABLE='1'`; restore it with
+`Remove-Item Env:ERRLENS_DISABLE`. To remove the wrapper from the current session,
+use `Remove-Item Function:python`. Persistent removal takes effect in new sessions.
+
+This is a PowerShell function calling a native program, not transparent terminal
+capture. `$LASTEXITCODE` is explicitly propagated. `$?` may report function success
+even when Python fails; inspect `$LASTEXITCODE`. PowerShell 7.3+ uses Standard
+native argument passing locally inside the wrapper; 7.0–7.2 retain their legacy
+quoting/empty-argument limitations. Global preferences are not changed.
+Pipeline output and `>` pass through PowerShell's object/text conversion and do
+not guarantee byte identity (including PowerShell 7.4 native redirection behavior).
+Pipeline input is not forwarded by this wrapper. Avoid binary pipelines, REPLs,
+interactive and full-screen applications; use an absolute Python executable when
+native semantics are needed. ExecutionPolicy, host-specific profile loading and
+VS Code itself require manual verification on the target machine.
+
+## Opt-in Bash and Zsh integration
+
+On Linux/macOS, explicitly install with `errlens shell install bash` or
+`errlens shell install zsh`; use `status` or `uninstall` in place of `install`.
+Bash uses `~/.bashrc`; Zsh uses `${ZDOTDIR:-$HOME}/.zshrc`. Bash login shells
+do not necessarily load `.bashrc`: configure your login profile to source it
+yourself if needed. These are interactive startup files; noninteractive shells
+do not automatically load them. `--profile PATH` selects an isolated/custom file.
+
+An owned script in `.errlens` beside the profile is sourced by one guarded line.
+Existing profile bytes are retained, changes receive unique backups, repeated
+installation is idempotent, and removal removes only the exact owned line and script.
+Edited lines and unowned scripts are refused. Backups remain after removal.
+Existing `python` functions and aliases take precedence and are preserved.
+
+The `python` function resolves the external interpreter and `errlens` on each
+invocation, forwards `"$@"`, working directory and exit status, and respects an
+activated virtual environment. `ERRLENS_DISABLE=1 python ...` bypasses analysis;
+if ErrLens is absent from PATH, the native Python is run directly. Use `unset -f
+python` to disable the wrapper in the current shell. `command python`, an absolute
+path, `python3`, pip and other commands bypass it. Restart or source the profile
+after installation; restart or unset the function after uninstallation.
+
+When starting Zsh from Bash with an active virtual environment, the Bash
+activation script may have modified and exported prompt variables. Bash prompt
+escapes are not Zsh prompt syntax and may appear literally. Start a clean Zsh,
+then run `source /path/to/venv/bin/activate` within Zsh. The ErrLens integration
+does not change `PS1` or `PROMPT`; your Zsh configuration can define its own prompt.
+Manual reports of Windows 11/PowerShell and Ubuntu 24.04/WSL Bash and Zsh are
+distinct from the automated CI checks; consult CI results for verified runs.
+
+Redirection and pipelines follow the shell and `errlens run` pipe semantics.
+Input is inherited, but interactive/terminal-dependent programs and exact stdout/
+stderr interleaving are not guaranteed. Ctrl+C follows Runner process-group handling;
+PTY and job-control equivalence are not guaranteed. Paths with spaces and Unicode
+are quoted without `eval`. No system profiles or shell settings are modified.
+
+## Explicit terminal mode
+
+Use `errlens run --terminal-mode pty -- python script.py` when terminal stdin
+and stdout are available. Linux/macOS use POSIX PTY; Windows 10 1809+ and Windows
+11 use native ConPTY. Pipe remains the default, including all shell wrappers.
+A transport error never triggers an automatic second run. Windows requires
+actual console handles and a native executable (.exe or .com), with no batch
+file or legacy winpty fallback. No extra runtime dependency or compiler is needed.
+
+Terminal mode supplies a terminal, input, window-size propagation and terminal
+Ctrl+C handling. stdout and stderr merge onto ErrLens stdout; echo and LF-to-CRLF
+conversion are normal terminal behavior. Binary identity and original stream
+separation are not guaranteed. Redirected host stdin/stdout are rejected; use
+pipe mode for pipelines. The combined diagnostic tail is limited to 1 MiB.
+Recognized failed Python commands receive one explanation on stderr after terminal
+restoration. Interactive REPL exceptions followed by a successful exit do not
+produce cards. ANSI forwarding is supported, but screen reconstruction, job-control
+transparency, suspended children and arbitrary full-screen applications are not
+guaranteed. A permanently blocked output sink can still block forwarding.
+
+The host terminal modes and signal handlers are saved and restored on ordinary
+exit, cancellation and transport errors. SIGKILL or a host crash cannot provide
+that guarantee. POSIX processes that deliberately detach from the session may
+outlive cleanup. ConPTY clients belong to a kill-on-close Windows Job Object:
+remaining descendants are terminated when the main client ends or transport fails.
+Windows uses a separate, short-lived owner process to bound ConPTY shutdown on
+older Windows builds. Input/output are UTF-8/VT text, so invalid bytes, NUL, cursor
+movement, wrapping and screen redraws need not survive as original log bytes.
+The analyzer strips ANSI but does not reconstruct a screen; complex redraws can
+produce incomplete or unrecognized diagnostics.
+
+Automated tests use isolated real ConPTY sessions and nested console handles on
+Windows, and nested POSIX PTYs on Linux and in the manual macOS workflow. User-reported manual checks
+cover Windows Terminal and VS Code ConPTY plus selected WSL Bash/Zsh sessions;
+the [acceptance record](https://github.com/ErrLens/errlens-cli/blob/main/docs/manual-acceptance.md) preserves untested combinations.
+Legacy console hosts, detailed REPL editing, Windows 10 lifecycle behavior and
+physical macOS hosts are not fully manually qualified. See
+[Windows ConPTY notes](https://github.com/ErrLens/errlens-cli/blob/main/docs/windows-conpty.md) for lifecycle details.
+
+## Development and checks
+
+```console
+python -m pytest
+python -m mypy
+python -m pip check
+python -m build
+```
+
+The build creates a wheel and source distribution in `dist/`. GitHub Actions #6
+passed all 11 jobs for `84dbb9c927b1b0eaf3ac6efc50863b9f0ef72836`, covering
+Windows, Ubuntu and macOS on Python 3.11–3.13 plus Windows/Ubuntu wheel installation.
+Hosted macOS runners were unavailable in [CI #8](https://github.com/ErrLens/errlens-cli/actions/runs/43235376928).
+The required Tests workflow temporarily runs Linux and Windows on Python 3.11–3.13
+and both packaging jobs. macOS tests remain available through a separate manual
+workflow. Earlier macOS passes apply to their tested commits. The release candidate
+has yet to be tested on macOS. The [release guide](https://github.com/ErrLens/errlens-cli/blob/main/docs/releasing.md)
+records when to restore macOS to the required matrix. The manual publishing workflow
+can retain candidate artifacts for review.
+
+See [CONTRIBUTING.md](https://github.com/ErrLens/errlens-cli/blob/main/CONTRIBUTING.md) for contribution guidance. ErrLens is distributed under the [MIT License](https://github.com/ErrLens/errlens-cli/blob/main/LICENSE).
+
+## Roadmap
+
+The current CLI focuses on local Python diagnostics, localized explanations,
+opt-in shell wrappers and explicit terminal sessions. Future stages may improve
+terminal compatibility and add VS Code integration, additional analyzers and
+optional AI providers. Those future features are not part of the current CLI.