termverify 0.1.0__tar.gz

termverify-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: termverify
+Version: 0.1.0
+Summary: Protocol-driven verification for autonomous terminal applications.
+Keywords: agents,testing,terminal,tui,verification
+Author: Matthias Hölzl
+Author-email: Matthias Hölzl <tc@xantira.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Testing
+Requires-Dist: pywinpty>=3.0.5,<4.0 ; sys_platform == 'win32'
+Requires-Dist: rfc8785>=0.1.4
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/hoelzl/termverify
+Project-URL: Repository, https://github.com/hoelzl/termverify
+Project-URL: Issues, https://github.com/hoelzl/termverify/issues
+Description-Content-Type: text/markdown
+
+# TermVerify
+
+Protocol-driven verification for autonomous terminal applications.
+
+TermVerify is a Python library and reference toolkit for testing terminal and TUI applications through reproducible interaction. It combines direct semantic adapters with real PTY-driven runs, then compares structured observations rather than relying only on brittle raw-terminal snapshots.
+
+## Why
+
+An autonomous coding agent is most reliable when it can make a change, exercise the actual program, observe meaningful results, and leave behind replayable evidence. Terminal applications need this especially badly: unit tests alone do not prove that key bindings, focus, rendering, prompts, and real interaction work.
+
+TermVerify provides a common foundation for:
+
+- deterministic interaction transcripts and replay;
+- semantic state and UI observations;
+- property/state-machine testing;
+- reviewed golden snapshots;
+- differential tests against a reference implementation or execution mode;
+- failure minimization and CI-ready artifacts.
+
+## Project status
+
+The repository is in its foundation phase. The reviewed transcript design has
+an initial codec, semantic validator, mandatory safe transcript-persistence
+boundary, immutable producer-side adapter contract, and deterministic in-process
+direct runtime. Requested timezone names and semantic key chords use closed,
+protocol-owned v1 registries; semantic keys also have an immutable direct-dispatch
+representation. The canonical transcript schema ships inside the package with a
+public access API, and isolated installation checks verify the wheel and sdist
+resource contract; the schema's `$id` resolves at
+[termverify.dev](https://termverify.dev/schemas/termverify.transcript/v1.schema.json)
+as a byte-identical mirror of the committed resource, and runtime validation
+remains authoritative. A strict no-regression coverage floor gates the full
+suite. Release governance is defined — changelog and pre-1.0 compatibility
+policy, private security disclosure, reviewed release checklist, and a
+tag-triggered attested draft-artifact workflow — although no release is
+authorized and nothing is published to a package index. A Windows ConPTY
+adapter with Windows-matrix evidence covers native pseudoconsole ownership
+and close, end-of-stream draining, process-tree teardown,
+cancellation/recovery, resize epochs, and replayable evidence normalization,
+and the first fully verified terminal run has landed using opt-in
+cooperation-tier constraint ports: the six non-terminal constraints are
+delivered to the subject's environment with truthful `delivered` receipts,
+honored by subject cooperation rather than OS enforcement. OS-level
+containment is an explicit non-goal by recorded owner decision; TermVerify
+verifies applications whose authors control the subject and is not an
+execution sandbox for adversarial code. Configuration values or receipt
+construction alone do not prove constraint enforcement.
+
+## Design principles
+
+1. **Semantic evidence first.** Verify state, events, and explicit UI semantics before comparing raw ANSI output.
+2. **Production interaction still matters.** PTY/terminal tests validate the application a person or agent actually drives.
+3. **Determinism is a contract.** Seeds, clock, locale, terminal size, filesystem sandbox, and network policy are explicit.
+4. **Human review owns baselines.** Agents may propose snapshot updates; they never silently bless them.
+5. **Harness-neutral by default.** The project works with Hermes, Claude Code, Codex, OpenCode, and ordinary CI without a required proprietary integration.
+
+## Planned architecture
+
+```text
+application under test
+  ├── direct semantic adapter ── fast properties, replay, differential tests
+  └── PTY adapter ───────────── real terminal interaction and rendering evidence
+               │
+          TermVerify
+  ├── run configuration and interaction protocol
+  ├── observation normalization and comparison
+  ├── transcript replay and shrinking
+  ├── property/state-machine support
+  └── reports and CI artifacts
+```
+
+See [the knowledge bundle](docs/knowledge/index.md) for the durable architecture and verification model.
+Browser bridging is deferred until the terminal vertical slice proves a shared
+abstraction is necessary.
+
+## Development
+
+Requirements: [uv](https://docs.astral.sh/uv/) and Python 3.12 or newer. The
+minimum installer version is 3.12; the continuously supported and tested
+versions are currently 3.12 through 3.14. Support for later Python releases is
+not implied until they join the CI matrix.
+
+```bash
+uv --no-config sync --all-groups --locked
+uv --no-config run pytest --cov --cov-report=term-missing
+uv --no-config run ruff check .
+uv --no-config run ruff format --check .
+uv --no-config run mypy src tests scripts
+uv --no-config run pre-commit run --all-files
+uv --no-config run pre-commit run --hook-stage pre-push --all-files
+uv --no-config build
+uv --no-config run pre-commit install --hook-type pre-commit --hook-type pre-push
+```
+
+See [developer workflow](docs/developer-guide/agent-workflow.md) and [contributing guide](CONTRIBUTING.md).
+External subjects implementing the producer contract start with the
+[adapter-author surface](docs/developer-guide/adapter-authors.md).
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE).

termverify-0.1.0/README.md

@@ -0,0 +1,101 @@
+# TermVerify
+
+Protocol-driven verification for autonomous terminal applications.
+
+TermVerify is a Python library and reference toolkit for testing terminal and TUI applications through reproducible interaction. It combines direct semantic adapters with real PTY-driven runs, then compares structured observations rather than relying only on brittle raw-terminal snapshots.
+
+## Why
+
+An autonomous coding agent is most reliable when it can make a change, exercise the actual program, observe meaningful results, and leave behind replayable evidence. Terminal applications need this especially badly: unit tests alone do not prove that key bindings, focus, rendering, prompts, and real interaction work.
+
+TermVerify provides a common foundation for:
+
+- deterministic interaction transcripts and replay;
+- semantic state and UI observations;
+- property/state-machine testing;
+- reviewed golden snapshots;
+- differential tests against a reference implementation or execution mode;
+- failure minimization and CI-ready artifacts.
+
+## Project status
+
+The repository is in its foundation phase. The reviewed transcript design has
+an initial codec, semantic validator, mandatory safe transcript-persistence
+boundary, immutable producer-side adapter contract, and deterministic in-process
+direct runtime. Requested timezone names and semantic key chords use closed,
+protocol-owned v1 registries; semantic keys also have an immutable direct-dispatch
+representation. The canonical transcript schema ships inside the package with a
+public access API, and isolated installation checks verify the wheel and sdist
+resource contract; the schema's `$id` resolves at
+[termverify.dev](https://termverify.dev/schemas/termverify.transcript/v1.schema.json)
+as a byte-identical mirror of the committed resource, and runtime validation
+remains authoritative. A strict no-regression coverage floor gates the full
+suite. Release governance is defined — changelog and pre-1.0 compatibility
+policy, private security disclosure, reviewed release checklist, and a
+tag-triggered attested draft-artifact workflow — although no release is
+authorized and nothing is published to a package index. A Windows ConPTY
+adapter with Windows-matrix evidence covers native pseudoconsole ownership
+and close, end-of-stream draining, process-tree teardown,
+cancellation/recovery, resize epochs, and replayable evidence normalization,
+and the first fully verified terminal run has landed using opt-in
+cooperation-tier constraint ports: the six non-terminal constraints are
+delivered to the subject's environment with truthful `delivered` receipts,
+honored by subject cooperation rather than OS enforcement. OS-level
+containment is an explicit non-goal by recorded owner decision; TermVerify
+verifies applications whose authors control the subject and is not an
+execution sandbox for adversarial code. Configuration values or receipt
+construction alone do not prove constraint enforcement.
+
+## Design principles
+
+1. **Semantic evidence first.** Verify state, events, and explicit UI semantics before comparing raw ANSI output.
+2. **Production interaction still matters.** PTY/terminal tests validate the application a person or agent actually drives.
+3. **Determinism is a contract.** Seeds, clock, locale, terminal size, filesystem sandbox, and network policy are explicit.
+4. **Human review owns baselines.** Agents may propose snapshot updates; they never silently bless them.
+5. **Harness-neutral by default.** The project works with Hermes, Claude Code, Codex, OpenCode, and ordinary CI without a required proprietary integration.
+
+## Planned architecture
+
+```text
+application under test
+  ├── direct semantic adapter ── fast properties, replay, differential tests
+  └── PTY adapter ───────────── real terminal interaction and rendering evidence
+               │
+          TermVerify
+  ├── run configuration and interaction protocol
+  ├── observation normalization and comparison
+  ├── transcript replay and shrinking
+  ├── property/state-machine support
+  └── reports and CI artifacts
+```
+
+See [the knowledge bundle](docs/knowledge/index.md) for the durable architecture and verification model.
+Browser bridging is deferred until the terminal vertical slice proves a shared
+abstraction is necessary.
+
+## Development
+
+Requirements: [uv](https://docs.astral.sh/uv/) and Python 3.12 or newer. The
+minimum installer version is 3.12; the continuously supported and tested
+versions are currently 3.12 through 3.14. Support for later Python releases is
+not implied until they join the CI matrix.
+
+```bash
+uv --no-config sync --all-groups --locked
+uv --no-config run pytest --cov --cov-report=term-missing
+uv --no-config run ruff check .
+uv --no-config run ruff format --check .
+uv --no-config run mypy src tests scripts
+uv --no-config run pre-commit run --all-files
+uv --no-config run pre-commit run --hook-stage pre-push --all-files
+uv --no-config build
+uv --no-config run pre-commit install --hook-type pre-commit --hook-type pre-push
+```
+
+See [developer workflow](docs/developer-guide/agent-workflow.md) and [contributing guide](CONTRIBUTING.md).
+External subjects implementing the producer contract start with the
+[adapter-author surface](docs/developer-guide/adapter-authors.md).
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE).

termverify-0.1.0/pyproject.toml

@@ -0,0 +1,128 @@
+[project]
+name = "termverify"
+version = "0.1.0"
+description = "Protocol-driven verification for autonomous terminal applications."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+authors = [
+    { name = "Matthias Hölzl", email = "tc@xantira.com" },
+]
+keywords = ["agents", "testing", "terminal", "tui", "verification"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "pywinpty>=3.0.5,<4.0; sys_platform == 'win32'",
+    "rfc8785>=0.1.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/hoelzl/termverify"
+Repository = "https://github.com/hoelzl/termverify"
+Issues = "https://github.com/hoelzl/termverify/issues"
+
+[dependency-groups]
+dev = [
+    "bump-my-version>=1.2.4",
+    "hypothesis>=6.156.2",
+    "jsonschema>=4.23",
+    "mypy>=1.0",
+    "pre-commit>=4.0",
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "pyyaml>=6.0",
+    "ruff>=0.11",
+    "types-jsonschema>=4.23",
+    "types-pyyaml>=6.0",
+]
+docs = [
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.7.7",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.28,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+source = ["termverify"]
+# The native ConPTY binding executes only on the Windows CI legs; including it
+# would make the cross-platform ratchet floor depend on the host OS. It stays
+# deliberately thin, its behavior is proven by the Windows-only integration
+# tests, and all adapter logic above it must remain fully ratcheted
+# (docs/developer-guide/development.md).
+omit = ["*/termverify/_conpty.py"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+# No-regression ratchet floor: integer floor of the reviewed observed total
+# (94.43% on 2026-07-17). Raise only for sustained durable coverage; lowering
+# requires explicit owner review (docs/developer-guide/development.md).
+# precision = 2 makes the comparison a strict floor instead of granting a
+# hidden half-point of integer rounding grace.
+fail_under = 94
+precision = 2
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+files = ["src", "tests", "scripts"]
+python_version = "3.12"
+strict = true
+warn_unreachable = true
+
+[[tool.mypy.overrides]]
+# pywinpty ships no type stubs and is absent on non-Windows checkers; the
+# binding wrapper confines its untyped surface to termverify._conpty.
+module = "winpty.*"
+ignore_missing_imports = true
+
+[tool.bumpversion]
+current_version = "0.1.0"
+commit = true
+# No local tag: the Release workflow (.github/workflows/release.yml) creates the
+# authoritative vX.Y.Z tag on the server *after* the CI-green gate, so a red
+# commit is never tagged. bump-my-version only produces the `Bump version …`
+# commit that the workflow keys on. (tag_name documents the format the server
+# uses; it is inert while tag = false.)
+tag = false
+tag_name = "v{new_version}"
+commit_message = "Bump version {current_version} → {new_version}"
+
+[[tool.bumpversion.files]]
+# pyproject.toml is the single version source of truth: [project] version is
+# read directly by the Release workflow's resolve job, and `__version__` is
+# derived from the installed distribution metadata at runtime.
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'
+
+[[tool.bumpversion.files]]
+# uv.lock records the project's own version in its [[package]] block. If it is
+# not updated here, the next `uv sync --locked` fails or silently re-locks.
+# Scope the replacement to the project's own block via the unique two-line
+# name+version pair.
+filename = "uv.lock"
+search = """name = "termverify"
+version = "{current_version}\""""
+replace = """name = "termverify"
+version = "{new_version}\""""

termverify-0.1.0/src/termverify/__init__.py

@@ -0,0 +1,137 @@
+"""Protocol-driven verification for autonomous terminal applications.
+
+The names re-exported here are the curated public surface. Adapter authors
+implement the contract defined in :mod:`termverify.adapter` and, for
+in-process subjects, :mod:`termverify.direct`; every contract name is
+importable from ``termverify`` directly and is identical to its module-path
+definition, so both import styles stay interchangeable. The surface is
+pre-1.0: compatibility intent and changes are recorded in ``CHANGELOG.md``.
+"""
+
+from importlib.metadata import version
+
+from termverify.adapter import (
+    ENFORCEMENT_TIERS,
+    Adapter,
+    AdapterFailure,
+    ClockAdvance,
+    ClockConfiguration,
+    ClockReceipt,
+    ConstraintName,
+    ConstraintPorts,
+    ConstraintUnsupported,
+    Cursor,
+    DeliveryRecord,
+    Diagnostic,
+    DispatchInput,
+    EnforcedConstraints,
+    EnforcementReceipt,
+    EnforcementTier,
+    EpochCompleted,
+    EpochResult,
+    Event,
+    ExitStatus,
+    FilesystemConfiguration,
+    FilesystemReceipt,
+    Frame,
+    FrozenJsonValue,
+    JsonInput,
+    KeyInput,
+    LocaleReceipt,
+    ManualTime,
+    NetworkConfiguration,
+    NetworkEndpoint,
+    NetworkReceipt,
+    Observation,
+    ProcessObservation,
+    Region,
+    Resize,
+    RunConfiguration,
+    RunFailed,
+    RunFinished,
+    SeedReceipt,
+    Started,
+    StartFailed,
+    StartResult,
+    StartTerminated,
+    StartUnsupported,
+    Stop,
+    TerminalConfiguration,
+    TerminalReceipt,
+    TerminalResult,
+    TextInput,
+    TimezoneReceipt,
+    UiObservation,
+    freeze_json,
+)
+from termverify.direct import DirectAdapter, DirectApplication
+from termverify.evidence import persist_transcript_evidence
+from termverify.schema import (
+    TRANSCRIPT_SCHEMA_V1_ID,
+    transcript_schema_v1_bytes,
+    transcript_schema_v1_json,
+)
+
+__all__ = [
+    "Adapter",
+    "AdapterFailure",
+    "ClockAdvance",
+    "ClockConfiguration",
+    "ClockReceipt",
+    "ConstraintName",
+    "ConstraintPorts",
+    "ConstraintUnsupported",
+    "Cursor",
+    "DeliveryRecord",
+    "Diagnostic",
+    "DirectAdapter",
+    "DirectApplication",
+    "DispatchInput",
+    "ENFORCEMENT_TIERS",
+    "EnforcedConstraints",
+    "EnforcementReceipt",
+    "EnforcementTier",
+    "EpochCompleted",
+    "EpochResult",
+    "Event",
+    "ExitStatus",
+    "FilesystemConfiguration",
+    "FilesystemReceipt",
+    "Frame",
+    "FrozenJsonValue",
+    "JsonInput",
+    "KeyInput",
+    "LocaleReceipt",
+    "ManualTime",
+    "NetworkConfiguration",
+    "NetworkEndpoint",
+    "NetworkReceipt",
+    "Observation",
+    "ProcessObservation",
+    "Region",
+    "Resize",
+    "RunConfiguration",
+    "RunFailed",
+    "RunFinished",
+    "SeedReceipt",
+    "StartFailed",
+    "StartResult",
+    "StartTerminated",
+    "StartUnsupported",
+    "Started",
+    "Stop",
+    "TRANSCRIPT_SCHEMA_V1_ID",
+    "TerminalConfiguration",
+    "TerminalReceipt",
+    "TerminalResult",
+    "TextInput",
+    "TimezoneReceipt",
+    "UiObservation",
+    "__version__",
+    "freeze_json",
+    "persist_transcript_evidence",
+    "transcript_schema_v1_bytes",
+    "transcript_schema_v1_json",
+]
+
+__version__ = version("termverify")