term-chameleon 0.1.0__tar.gz

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

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv sync --extra dev
+      - run: uv run --extra dev ruff check .
+      - run: uv run --extra dev ruff format --check .
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --extra dev
+      - run: uv run --extra dev pytest -q

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

@@ -0,0 +1,31 @@
+name: Publish
+
+on:
+  release:
+    types: [created]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

term_chameleon-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+artifacts/
+dist/
+*.egg-info/
+*.backup.*
+.DS_Store

term_chameleon-0.1.0/CHANGELOG.md

@@ -0,0 +1,128 @@
+# Changelog
+
+## 0.1.0 - 2026-06-27
+
+### Stable release
+
+- Promoted from beta to stable after sustained daemon dogfood (35+ hours at 0% CPU, bounded disk, no crashes).
+- Removed dead code (`query_dynamic_color`, `supported_color_fields`).
+- Replaced runtime `assert` with explicit `ConfigError` raises for daemon path resolution and region validation.
+- Added `__all__` to package `__init__`.
+- Added `help=` text to all key CLI arguments.
+- Added README Troubleshooting section.
+- Promoted classifier to `Development Status :: 5 - Production/Stable`.
+
+## 0.1.0b4 - 2026-06-27
+
+### Fixed
+
+- `sample` and `adapt-once` now validate `--iterm-window requires --screen` before attempting to contact iTerm2.
+- Long-running watcher now prunes old screenshot artifacts to prevent unbounded disk growth (keeps the 200 most recent).
+
+## 0.1.0b3 - 2026-06-25
+
+### Fixed
+
+- Reduced long-running watcher CPU usage by downsampling screenshots before luminance/variance analysis and raising the AutoLaunch daemon's default interval to 10 seconds.
+
+### Verified
+
+- Durable AutoLaunch watcher from the installed wheel stayed running with sample artifacts and live release gate after optimization.
+
+## 0.1.0b2 - 2026-06-25
+
+### Fixed
+
+- `watch-live` now treats live iTerm2 apply failures as recoverable watcher events instead of exiting the long-running daemon. This keeps AutoLaunch watchers alive when iTerm2 temporarily has no current session.
+
+### Verified
+
+- Durable local install under `~/.local/share/term-chameleon/venv`.
+- Real iTerm2 AutoLaunch restart with default pid/log paths and sample artifacts.
+
+## 0.1.0b1 - 2026-06-25
+
+### Changed
+
+- AutoLaunch-launched `watch-live --iterm-window` now waits briefly for iTerm2 to create a window instead of exiting immediately during app startup.
+- `install-watch-daemon` now defaults to whole-screen sampling for startup robustness and exposes `--iterm-window` as an explicit opt-in.
+- Promoted package metadata to beta after real AutoLaunch daemon dogfood.
+- Updated README with beta install/use path and daemon restart guidance.
+
+### Verified
+
+- Installed the wheel into a fresh venv, ran `setup --yes`, `release-check --live --live-stage`, and installed the real iTerm2 AutoLaunch watcher.
+- Restarted iTerm2 and verified exactly one long-running watcher process from the AutoLaunch script.
+- Confirmed daemon status stayed healthy and watcher screenshot sample artifacts were written.
+
+## 0.1.0a7 - 2026-06-25
+
+### Added
+
+- `term-chameleon release-check` top-level release-readiness gate.
+- Release-check JSON/Markdown reports that compose deterministic checks, optional config validation, readiness status, daemon status, and live-stage screenshot QA.
+- Tests for release-check success/failure behavior.
+
+## 0.1.0a6 - 2026-06-25
+
+### Added
+
+- `term-chameleon config-check` for validating TOML configs before setup/watch/daemon use.
+- Config validation for value types, preset names, region shape, and unknown sections/keys.
+- JSON output for config validation reports.
+
+## 0.1.0a5 - 2026-06-25
+
+### Added
+
+- `term-chameleon watch-daemon-status` to inspect the AutoLaunch script, log path, pid file, and running pid state.
+- `term-chameleon uninstall-watch-daemon` with dry-run and backup support.
+- Tests for watch daemon install/status/uninstall lifecycle behavior.
+
+## 0.1.0a4 - 2026-06-25
+
+### Added
+
+- `term-chameleon config-example` for generating a documented TOML config.
+- `--config` support for `setup`, `watch-live`, and `install-watch-daemon`.
+- Config-driven watcher, daemon, and setup defaults with explicit CLI flags taking precedence.
+
+## 0.1.0a3 - 2026-06-25
+
+### Added
+
+- `term-chameleon setup` guided setup flow.
+- Setup flow runs deterministic self-checks, summarizes readiness, and optionally installs the generated profile with `--yes`.
+- `setup --live` includes live iTerm2 API/window readiness in the final setup result.
+
+## 0.1.0a2 - 2026-06-25
+
+### Added
+
+- `term-chameleon status` readiness summary for local setup/dogfooding.
+- `term-chameleon status --json` machine-readable readiness output.
+- Optional `--live` status probes for iTerm2 Python API connectivity and front-window bounds.
+
+## 0.1.0a1 - 2026-06-25
+
+Initial alpha release candidate for Term Chameleon.
+
+### Added
+
+- iTerm2 Dynamic Profile parsing, diagnostics, and conservative safe fixes.
+- Machine-readable `doctor --json` diagnostics with preserved exit-code semantics.
+- Generated iTerm2 Dynamic Profile preset install flow and optional AutoLaunch default-profile script.
+- Manual profile mode switching and OSC/tmux color sequence generation.
+- Screen/image sampling with one-shot profile adaptation.
+- Live adaptive watcher with dry-run, stability, cooldown, duration, and iTerm2 session-local apply modes.
+- iTerm2 Python API readiness checks, connection probe, window bounds probe, and live-adapter script generation.
+- AutoLaunch watcher daemon packaging for continuous adaptation.
+- Deterministic visual simulation, E2E staging artifacts, screenshot probes, pixel contrast, and text-row contrast reports.
+- Controlled Safari+iTerm2 live GUI staging with explicit `--yes` gate and text-row contrast with pixel-cluster fallback.
+- Permission-free `term-chameleon check` deterministic self-check for post-install validation.
+
+### Notes
+
+- Live GUI and live watcher flows may require macOS Screen Recording, Automation, Accessibility, and iTerm2 Python API permissions.
+- Text-row contrast is heuristic; future releases may add OCR or terminal-cell-aware glyph segmentation.
+- iTerm2 on macOS is the supported terminal target for this alpha.

term_chameleon-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Term Chameleon 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.

term_chameleon-0.1.0/PKG-INFO

@@ -0,0 +1,289 @@
+Metadata-Version: 2.4
+Name: term-chameleon
+Version: 0.1.0
+Summary: Adaptive contrast/readability toolkit for translucent terminals, starting with iTerm2.
+Project-URL: Homepage, https://github.com/bodhi/term-chameleon
+Project-URL: Repository, https://github.com/bodhi/term-chameleon
+Project-URL: Issues, https://github.com/bodhi/term-chameleon/issues
+Project-URL: Changelog, https://github.com/bodhi/term-chameleon/blob/main/CHANGELOG.md
+Author: Term Chameleon contributors
+License: MIT
+License-File: LICENSE
+Keywords: accessibility,contrast,iterm2,osc,terminal,transparency
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Terminals
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: iterm
+Requires-Dist: iterm2>=2.9; extra == 'iterm'
+Provides-Extra: visual
+Requires-Dist: pillow>=10.0; extra == 'visual'
+Description-Content-Type: text/markdown
+
+# Term Chameleon
+
+Term Chameleon is an adaptive contrast/readability toolkit for translucent terminals, starting with iTerm2 on macOS.
+
+Glassy terminal themes look good until white text disappears over a bright window, black/dim text vanishes over dark blur, or iTerm2 Light/Dark profile variants silently override the intended palette. Term Chameleon provides static profile diagnostics/fixes plus live background-aware sampling, staging, and adaptation for iTerm2.
+
+## Current status
+
+This repository is prepared as `v0.1.0` / Python package version `0.1.0`: a dogfooded beta for static profile diagnostics, safe profile mutation, deterministic visual artifacts, live iTerm2 adaptation, controlled macOS GUI/screenshot QA, and real iTerm2 AutoLaunch watcher operation. Implemented:
+
+- iTerm2 Dynamic Profile JSON parsing.
+- Color conversion between hex and iTerm2 color dictionaries.
+- WCAG contrast calculations.
+- Static diagnostics for common glass-terminal readability failures.
+- Conservative static fixer with dry-run, backups, deterministic JSON, and explainable changes.
+- iTerm2 Dynamic Profile preset install flow, including optional AutoLaunch default-profile script.
+- Manual readability mode switching for profile JSON files.
+- OSC color sequence generation, including tmux passthrough wrapping.
+- Dynamic watcher foundation via `watch-sim` risk classifier and hysteresis mode selector.
+- iTerm2 live-adapter script generation/probe foundation for session-local Python API validation.
+- Screen/image sampling one-shot adaptation via `sample` and `adapt-once`.
+- Live adaptive watcher via `watch-live`, with dry-run, stable-sample, cooldown, duration, and real iTerm2 session-local apply modes.
+- Deterministic E2E staging bundle that combines controlled backgrounds, ANSI pattern artifacts, visual simulation, screenshot capture, and screenshot pixel analysis.
+- Screenshot contrast estimation for captured PNG/PPM artifacts.
+- Text-row/glyph-aware screenshot contrast estimation for rendered terminal pattern captures.
+- Live GUI staging that arranges controlled Safari background + iTerm2 ANSI pattern windows and can optionally capture/analyze the result with text-row contrast and pixel-cluster fallback.
+- macOS `screencapture` probe and screenshot-test artifact foundation for screenshot-based visual tests.
+- Long-running daemon packaging for continuous adaptation.
+- Permission-free deterministic self-check command for post-install validation.
+- Local readiness status command with human and JSON output.
+- Guided setup command that runs deterministic checks and optionally installs the default profile.
+- TOML config example, validation, and `--config` support for setup/watch-live/watch daemon flows.
+- Watch daemon status and uninstall commands for AutoLaunch lifecycle management.
+- Top-level release-readiness gate that composes deterministic checks, config validation, readiness, daemon, and live-stage checks.
+- Fixture tests for good and bad iTerm2 profiles.
+
+Optional future refinements:
+
+- Replace heuristic text-row detection with OCR/terminal-cell-aware glyph segmentation.
+- Add broader terminal emulator support beyond iTerm2.
+
+## Beta release verification
+
+Build and install the beta wheel locally:
+
+```bash
+uv build
+python3 -m venv /tmp/term-chameleon-beta-venv
+/tmp/term-chameleon-beta-venv/bin/pip install 'dist/term_chameleon-0.1.0-py3-none-any.whl[iterm]'
+/tmp/term-chameleon-beta-venv/bin/term-chameleon setup --yes
+/tmp/term-chameleon-beta-venv/bin/term-chameleon release-check --output-dir /tmp/term-chameleon-beta-release-check
+/tmp/term-chameleon-beta-venv/bin/term-chameleon release-check --output-dir /tmp/term-chameleon-beta-live-check --live --live-stage --threshold 1.0
+```
+
+The real iTerm2 AutoLaunch watcher was dogfooded for this beta by installing the daemon, restarting iTerm2, verifying a single running watcher process, checking daemon status, and confirming screenshot sample artifacts were written.
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes.
+
+## Use it
+
+```bash
+python3 -m venv ~/.local/share/term-chameleon/venv
+~/.local/share/term-chameleon/venv/bin/pip install 'term-chameleon[iterm]'
+~/.local/share/term-chameleon/venv/bin/term-chameleon setup --yes
+~/.local/share/term-chameleon/venv/bin/term-chameleon release-check --live --live-stage --threshold 1.0
+~/.local/share/term-chameleon/venv/bin/term-chameleon install-watch-daemon
+~/.local/share/term-chameleon/venv/bin/term-chameleon watch-daemon-status
+```
+
+Restart iTerm2 after installing the daemon. The AutoLaunch script starts one long-running `watch-live` process and records its pid/log paths; use `watch-daemon-status` to inspect it and `uninstall-watch-daemon` to remove the AutoLaunch script. The daemon samples the whole screen by default for startup robustness; pass `install-watch-daemon --iterm-window` if you prefer front-iTerm-window sampling after confirming Accessibility/iTerm2 API startup behavior on your machine.
+
+## CLI examples
+
+Run a permission-free deterministic self-check after installation or inspect local readiness:
+
+```bash
+term-chameleon check --output-dir artifacts/check
+term-chameleon release-check --output-dir artifacts/release-check
+term-chameleon setup
+term-chameleon setup --yes
+term-chameleon setup --live
+term-chameleon config-example --output ~/.config/term-chameleon/config.toml
+term-chameleon config-check --config ~/.config/term-chameleon/config.toml
+term-chameleon watch-live --config ~/.config/term-chameleon/config.toml --dry-run
+term-chameleon status
+term-chameleon status --live
+term-chameleon status --json
+```
+
+`setup` is a guided flow: it runs deterministic checks and reports status. On first run, bare `setup` exits nonzero until a healthy profile exists; use `setup --yes` to install the generated profile, and `setup --live` to include live iTerm2 API/window readiness.
+
+`release-check` is the top-level local gate. By default it is permission-free and writes JSON/Markdown reports; add `--config`, `--live`, `--daemon`, or `--live-stage` to include config validation, live iTerm2 probes, AutoLaunch health, or controlled Safari+iTerm2 screenshot QA.
+
+`config-example` prints a commented TOML file. `config-check` validates value types, preset names, region shape, and unknown sections/keys. `watch-live`, `install-watch-daemon`, and `setup` accept `--config`; explicit CLI flags override config values.
+
+Install a balanced preset into a target directory:
+
+```bash
+term-chameleon install --target-dir /tmp/iterm-dynamic-profiles --name "Adaptive Glass"
+```
+
+Install an iTerm2 AutoLaunch script that starts the live watcher whenever iTerm2 launches:
+
+```bash
+term-chameleon install-watch-daemon --dry-run
+term-chameleon watch-daemon-status
+term-chameleon install-watch-daemon
+term-chameleon watch-daemon-status --json
+term-chameleon uninstall-watch-daemon --dry-run
+term-chameleon uninstall-watch-daemon
+```
+
+`uninstall-watch-daemon` removes the iTerm2 AutoLaunch script only; it does not stop an already-running watcher process or remove logs/pid files. It creates a backup by default unless `--no-backup` is passed.
+
+Apply a manual readability mode to a profile JSON file:
+
+```bash
+term-chameleon mode bright-safe ~/Library/Application\ Support/iTerm2/DynamicProfiles/adaptive-glass.json --dry-run
+```
+
+Check iTerm2 Python API readiness and generate a conservative session-local adapter script:
+
+```bash
+term-chameleon iterm-api-check
+term-chameleon iterm-connect-probe
+term-chameleon iterm-window-bounds
+term-chameleon iterm-live-script --preset balanced --output /tmp/term-chameleon-live.py
+```
+
+Probe macOS screenshot availability and generate controlled screenshot-test artifacts:
+
+```bash
+term-chameleon screenshot-probe
+term-chameleon screenshot-probe --capture --output artifacts/screenshot-probe/screen.png
+term-chameleon screenshot-contrast artifacts/screenshot-probe/screen.png --output-dir artifacts/screenshot-contrast
+term-chameleon screenshot-text-contrast artifacts/screenshot-probe/screen.png --output-dir artifacts/screenshot-text-contrast
+term-chameleon screenshot-test --output-dir artifacts/screenshot-test
+term-chameleon screenshot-test --capture --output-dir artifacts/screenshot-test
+term-chameleon background-html --output-dir artifacts/background-html
+term-chameleon pattern-script --output-dir artifacts/pattern-script
+term-chameleon e2e-stage tests/fixtures/iterm/good-dark-glass.json --output-dir artifacts/e2e-stage
+term-chameleon live-stage --dry-run --output-dir artifacts/live-stage
+term-chameleon live-stage --yes --capture --output-dir artifacts/live-stage
+```
+
+`live-stage --yes` is intentionally explicit because it activates Safari, opens the controlled background page, creates/resizes an iTerm2 window, writes the ANSI pattern command into that session, and may require macOS Automation/Accessibility/Screen Recording permissions. It leaves the staged windows open for inspection.
+
+```bash
+term-chameleon sample --screen --output artifacts/adapt/screen.png
+term-chameleon sample --screen --iterm-window --output artifacts/adapt/iterm-window.png
+term-chameleon sample --screen --region 0,0,800,600 --output artifacts/adapt/region.png
+term-chameleon adapt-once tests/fixtures/iterm/good-dark-glass.json --screen --dry-run
+term-chameleon watch-live --dry-run --duration 10 --interval 1 --stable 2
+term-chameleon watch-live --dry-run --iterm-window --duration 10 --interval 1 --stable 2
+term-chameleon watch-live --yes --iterm-window --duration 30 --interval 2 --stable 3 --cooldown 10
+```
+
+Manual live smoke test, once iTerm2 is running and the Python API is enabled:
+
+```bash
+scripts/live-iterm-smoke.sh
+```
+
+Run deterministic visual simulation:
+
+```bash
+term-chameleon visual-test tests/fixtures/iterm/good-dark-glass.json
+```
+
+Doctor a profile:
+
+```bash
+term-chameleon doctor tests/fixtures/iterm/bad-light-variant.json
+term-chameleon doctor tests/fixtures/iterm/bad-light-variant.json --json
+```
+
+`doctor --json` emits machine-readable diagnostics after a profile loads successfully; profile load/parse errors still use the standard nonzero exit code with an error on stderr.
+
+Preview fixes:
+
+```bash
+term-chameleon fix tests/fixtures/iterm/bad-light-variant.json --dry-run
+```
+
+Apply fixes to a copy:
+
+```bash
+cp tests/fixtures/iterm/bad-light-variant.json /tmp/profile.json
+term-chameleon fix /tmp/profile.json --yes
+term-chameleon doctor /tmp/profile.json
+```
+
+## Troubleshooting
+
+**iTerm2 Python API not connected:**
+
+Ensure iTerm2 is running and Python API support is enabled: iTerm2 → Settings → General → Magic → check "Enable Python API". Run `term-chameleon iterm-api-check` to verify.
+
+**Screen Recording permission denied:**
+
+macOS requires Screen Recording permission for `screencapture`. Grant it in System Settings → Privacy & Security → Screen Recording for the terminal running Term Chameleon.
+
+**AutoLaunch daemon not starting:**
+
+Verify the script exists and is executable:
+
+```bash
+term-chameleon watch-daemon-status
+```
+
+If the PID file is stale (process not running), remove it and restart iTerm2:
+
+```bash
+rm ~/Library/Application\ Support/term-chameleon/watch-live.pid
+```
+
+**Stale watcher process after uninstall:**
+
+`uninstall-watch-daemon` removes the AutoLaunch script but does not kill a running watcher. Stop it manually:
+
+```bash
+kill "$(cat ~/Library/Application\ Support/term-chameleon/watch-live.pid)"
+```
+
+**Daemon CPU or disk usage:**
+
+The daemon defaults to a 10-second sampling interval and prunes artifacts to the 200 most recent. To reduce overhead further, increase the interval via config or `--interval`.
+
+**iTerm2 window bounds unavailable on startup:**
+
+The daemon defaults to whole-screen sampling for startup robustness. If using `--iterm-window`, the watcher waits up to 60 seconds for iTerm2 to create a window before failing.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run ruff check .
+```
+
+If you do not use `uv`:
+
+```bash
+python3 -m pytest
+python3 -m term_chameleon.cli doctor tests/fixtures/iterm/bad-light-variant.json
+```
+
+## Safety principles
+
+- Static analysis before mutation.
+- `--dry-run` support for fixes.
+- Timestamped backups before writing.
+- Deterministic JSON output.
+- Explainable diagnostics and fixes.
+- No direct mutation of `~/Library/Preferences/com.googlecode.iterm2.plist` as the primary mechanism.
+
+## Positioning
+
+Term Chameleon is not just another terminal theme and does not claim to invent automatic contrast. Prior art includes iTerm2 Minimum Contrast, Apple Terminal contrast tweaking, Ghostty minimum contrast, terminal opacity/blur settings, CSS blend-mode/backdrop approaches, and WCAG/APCA contrast engines.
+
+The intended differentiated direction is a live contrast controller for translucent terminal windows: sample or infer the actual visual environment behind the terminal, then adapt palette, opacity, blur, and contrast to keep text readable without giving up the glass effect.