ghostcfg 0.1.0__tar.gz

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

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

ghostcfg-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# ghostcfg backups
+*.bak.*

ghostcfg-0.1.0/CLAUDE.md

@@ -0,0 +1,56 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Is
+
+ghostcfg is a Python TUI (Textual) application for interactively editing Ghostty terminal configuration. It provides tabbed category browsing, live theme preview, type-aware input widgets, and hot-reload via SIGUSR2 signaling to a running Ghostty process.
+
+## Commands
+
+```bash
+pip install -e .          # Install in editable mode
+ghostcfg                  # Run the app (or: gcfg, python -m ghostcfg)
+pytest                    # Run all tests
+pytest tests/test_schema.py            # Run a single test file
+pytest tests/test_schema.py::test_name # Run a single test
+```
+
+No linter or formatter is configured.
+
+## Architecture
+
+**Entry point:** `src/ghostcfg/app.py:main()` → `GhostCfg(App).run()`
+
+**Data flow:** Ghostty CLI → schema + config parsing → Textual widgets → config write → SIGUSR2 reload
+
+### Core Modules
+
+- **schema.py** — Static metadata for 200+ Ghostty options: type (`string`, `boolean`, `enum`, `integer`, `float`, `color`, `path`, `duration`), default value, category, hot_reload flag, platform filter, repeatability. Options are grouped into `CATEGORIES` (Font, Colors, Cursor, Window, Background, Input, Shell, Advanced) which drive the tab layout.
+
+- **config_io.py** — Roundtrip-safe config parser. `GhosttyConfig` stores a list of `ConfigEntry` objects (kind: `option`/`comment`/`blank`) preserving original comments, blank lines, and ordering through read→modify→write cycles. Creates `.bak` backups before first write per session.
+
+- **ghostty.py** — Ghostty process interface. Detects config path per platform (macOS: `~/Library/Application Support/com.mitchellh.ghostty/config`, Linux: `~/.config/ghostty/config`). Calls `ghostty +list-themes --plain` and `ghostty +show-config --default --docs` for runtime data. Finds Ghostty PIDs with `pgrep -a` (needed since ghostcfg runs inside Ghostty as an ancestor process) and sends SIGUSR2 for hot-reload.
+
+- **app.py** — Main Textual App. Composes a `TabbedContent` with a Themes tab and one tab per category. Tracks `_pending_changes` dict that accumulates until Ctrl+S save. Theme changes bypass pending—they write and reload immediately.
+
+### Widgets (`src/ghostcfg/widgets/`)
+
+- **ThemeBrowser** — Searchable theme list with dark/light filter. Emits `ThemeHighlighted` (live preview on cursor move), `ThemeSelected` (Enter confirms), `ThemeReverted` (Escape restores original).
+
+- **ConfigPanel** — Container for `OptionRow` widgets in a category, with a documentation pane that updates on focus.
+
+- **OptionRow** — Single config option. Selects input widget by type: `Switch` for boolean, `Select` for enum, `Input` for string/number/color. Color options show a live swatch. Tracks original vs current value for modification detection.
+
+### Key Patterns
+
+- **Message-based communication** — Widgets communicate via Textual `Message` subclasses (e.g., `ValueChanged`, `ThemeHighlighted`, `OptionFocused`), not direct method calls.
+- **Reactive properties** — `reactive[bool]` for `has_unsaved` drives the `[modified]` subtitle indicator.
+- **Theme application removes color overrides** — When a theme is applied, `THEME_COLOR_KEYS` (background, foreground, palette, etc.) are stripped from config so the theme's colors take effect.
+- **Platform filtering** — Schema entries with `"platform": "macos"` or `"linux"` are filtered at runtime via `platform.system()`.
+
+## Dependencies
+
+- Python ≥ 3.10
+- textual ≥ 1.0.0
+- Ghostty must be installed and on PATH for runtime data (themes, docs, reload)

ghostcfg-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sam K
+
+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.

ghostcfg-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: ghostcfg
+Version: 0.1.0
+Summary: Interactive TUI for Ghostty terminal configuration
+Project-URL: Homepage, https://github.com/samkleespies/ghostcfg
+Project-URL: Repository, https://github.com/samkleespies/ghostcfg
+Project-URL: Issues, https://github.com/samkleespies/ghostcfg/issues
+Author-email: Sam Kleespies <samkleespies@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: config,ghostty,terminal,textual,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+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 :: Terminals :: Terminal Emulators/X Terminals
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: textual>=1.0.0
+Description-Content-Type: text/markdown
+
+# ghostcfg
+
+A TUI for editing your [Ghostty](https://ghostty.org) config without touching the file by hand.
+
+Browse 200+ options by category, preview themes live with color swatches, and save — ghostcfg hot-reloads your running Ghostty instance automatically.
+
+<p align="center">
+  <img src="assets/demo.gif" alt="ghostcfg demo" width="800">
+</p>
+
+## Install
+
+```bash
+pipx install ghostcfg        # recommended
+uv tool install ghostcfg     # or with uv
+pip install ghostcfg          # or plain pip
+```
+
+On macOS with Homebrew:
+
+```bash
+brew install samkleespies/ghostcfg/ghostcfg
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/samkleespies/ghostcfg.git
+cd ghostcfg
+pip install -e .
+```
+
+Requires Python 3.10+ and [Ghostty](https://ghostty.org) on PATH.
+
+## Usage
+
+```bash
+ghostcfg   # or: gcfg
+```
+
+### Keybindings
+
+| Key | Action |
+|-----|--------|
+| `Tab` / `Shift+Tab` | Switch tabs |
+| `Up` / `Down` | Navigate options |
+| `Enter` | Edit / toggle |
+| `Ctrl+S` | Save and reload Ghostty |
+| `Ctrl+D` | Reset option to default |
+| `?` | Help |
+| `q` | Quit |
+
+In the theme browser:
+
+| Key | Action |
+|-----|--------|
+| `Up` / `Down` | Browse (previews live) |
+| `Enter` | Confirm theme |
+| `Escape` | Revert to original |
+| `d` / `l` / `a` | Dark only / light only / all |
+
+## What it does
+
+- Tabbed categories: Font, Colors, Cursor, Window, Background, Input, Shell, Advanced
+- Theme browser with inline color swatch preview, search, and dark/light filtering
+- Type-aware widgets: toggles for booleans, dropdowns for enums, color pickers, validated number fields
+- Saves trigger SIGUSR2 so Ghostty reloads instantly
+- Roundtrip-safe: your comments, blank lines, and ordering are preserved
+- Platform-aware: only shows options for your OS
+
+ghostcfg finds your config at:
+- **macOS:** `~/Library/Application Support/com.mitchellh.ghostty/config`
+- **Linux:** `~/.config/ghostty/config`
+
+## License
+
+MIT

ghostcfg-0.1.0/README.md

@@ -0,0 +1,77 @@
+# ghostcfg
+
+A TUI for editing your [Ghostty](https://ghostty.org) config without touching the file by hand.
+
+Browse 200+ options by category, preview themes live with color swatches, and save — ghostcfg hot-reloads your running Ghostty instance automatically.
+
+<p align="center">
+  <img src="assets/demo.gif" alt="ghostcfg demo" width="800">
+</p>
+
+## Install
+
+```bash
+pipx install ghostcfg        # recommended
+uv tool install ghostcfg     # or with uv
+pip install ghostcfg          # or plain pip
+```
+
+On macOS with Homebrew:
+
+```bash
+brew install samkleespies/ghostcfg/ghostcfg
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/samkleespies/ghostcfg.git
+cd ghostcfg
+pip install -e .
+```
+
+Requires Python 3.10+ and [Ghostty](https://ghostty.org) on PATH.
+
+## Usage
+
+```bash
+ghostcfg   # or: gcfg
+```
+
+### Keybindings
+
+| Key | Action |
+|-----|--------|
+| `Tab` / `Shift+Tab` | Switch tabs |
+| `Up` / `Down` | Navigate options |
+| `Enter` | Edit / toggle |
+| `Ctrl+S` | Save and reload Ghostty |
+| `Ctrl+D` | Reset option to default |
+| `?` | Help |
+| `q` | Quit |
+
+In the theme browser:
+
+| Key | Action |
+|-----|--------|
+| `Up` / `Down` | Browse (previews live) |
+| `Enter` | Confirm theme |
+| `Escape` | Revert to original |
+| `d` / `l` / `a` | Dark only / light only / all |
+
+## What it does
+
+- Tabbed categories: Font, Colors, Cursor, Window, Background, Input, Shell, Advanced
+- Theme browser with inline color swatch preview, search, and dark/light filtering
+- Type-aware widgets: toggles for booleans, dropdowns for enums, color pickers, validated number fields
+- Saves trigger SIGUSR2 so Ghostty reloads instantly
+- Roundtrip-safe: your comments, blank lines, and ordering are preserved
+- Platform-aware: only shows options for your OS
+
+ghostcfg finds your config at:
+- **macOS:** `~/Library/Application Support/com.mitchellh.ghostty/config`
+- **Linux:** `~/.config/ghostty/config`
+
+## License
+
+MIT

ghostcfg-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ghostcfg"
+version = "0.1.0"
+description = "Interactive TUI for Ghostty terminal configuration"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "Sam Kleespies", email = "samkleespies@gmail.com" },
+]
+keywords = ["ghostty", "terminal", "config", "tui", "textual"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Terminals :: Terminal Emulators/X Terminals",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "textual>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/samkleespies/ghostcfg"
+Repository = "https://github.com/samkleespies/ghostcfg"
+Issues = "https://github.com/samkleespies/ghostcfg/issues"
+
+[project.scripts]
+ghostcfg = "ghostcfg.app:main"
+gcfg = "ghostcfg.app:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ghostcfg"]

ghostcfg-0.1.0/src/ghostcfg/__init__.py

@@ -0,0 +1,3 @@
+"""ghostcfg — Interactive TUI for Ghostty configuration."""
+
+__version__ = "0.1.0"

ghostcfg-0.1.0/src/ghostcfg/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as python -m ghostcfg."""
+
+from ghostcfg.app import main
+
+main()

ghostcfg-0.1.0/src/ghostcfg/app.py

@@ -0,0 +1,271 @@
+"""Main Textual App for ghostcfg."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.reactive import reactive
+from textual.widgets import Footer, Input, TabbedContent, TabPane
+
+from ghostcfg.config_io import GhosttyConfig, backup_config, read_config, write_config
+from ghostcfg.ghostty import (
+    get_config_path,
+    get_config_with_docs,
+    list_themes,
+    reload_config,
+)
+from ghostcfg.schema import CATEGORIES
+from ghostcfg.screens.color_picker import ColorPickerScreen
+from ghostcfg.screens.help_screen import HelpScreen
+from ghostcfg.widgets.config_panel import ConfigPanel
+from ghostcfg.widgets.option_row import OptionRow
+from ghostcfg.widgets.theme_browser import ThemeBrowser
+
+# Color keys that themes control — remove these when applying a theme
+# so the theme's colors take effect instead of being overridden.
+THEME_COLOR_KEYS = {
+    "background",
+    "foreground",
+    "bold-color",
+    "cursor-color",
+    "cursor-text",
+    "selection-foreground",
+    "selection-background",
+    "split-divider-color",
+    "unfocused-split-fill",
+    "window-titlebar-background",
+    "window-titlebar-foreground",
+}
+
+
+class GhostCfg(App):
+    """Interactive TUI for Ghostty configuration."""
+
+    TITLE = "ghostcfg"
+    CSS_PATH = "app.tcss"
+
+    BINDINGS = [
+        Binding("ctrl+s", "save", "Save", show=True, priority=True),
+        Binding("question_mark", "help", "Help", show=True),
+        Binding("q", "quit_app", "Quit", show=True),
+        Binding("ctrl+d", "reset_default", "Default", show=True),
+    ]
+
+    has_unsaved: reactive[bool] = reactive(False)
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._config_path: Path = get_config_path()
+        self._config: GhosttyConfig = GhosttyConfig()
+        self._themes: list[str] = []
+        self._docs: dict[str, str] = {}
+        self._config_values: dict[str, str] = {}
+        self._original_theme: str = ""
+        self._theme_ready = False
+
+    def compose(self) -> ComposeResult:
+        self._load_data()
+        with TabbedContent(id="tabs"):
+            with TabPane("Themes", id="tab-themes"):
+                # Pass empty list; ThemeBrowser is populated in on_mount
+                # to avoid reentrancy in its reactive watchers.
+                yield ThemeBrowser([], id="theme-browser")
+            for category in CATEGORIES:
+                tab_id = f"tab-{category.lower()}"
+                with TabPane(category, id=tab_id):
+                    yield ConfigPanel(
+                        category=category,
+                        config_values=self._config_values,
+                        docs=self._docs,
+                        id=f"panel-{category.lower()}",
+                    )
+        yield Footer()
+
+    def on_mount(self) -> None:
+        try:
+            browser = self.query_one("#theme-browser", ThemeBrowser)
+            browser.all_themes = self._themes
+            browser.set_original_theme(self._original_theme)
+            browser._refresh_list()
+        except Exception:
+            pass
+        self.call_after_refresh(self._enable_theme_preview)
+
+    def _enable_theme_preview(self) -> None:
+        """Allow theme live-preview after initial UI settlement."""
+        self._theme_ready = True
+
+    def _load_data(self) -> None:
+        """Load themes, config, and docs from Ghostty."""
+        self._themes = list_themes()
+        self._config = read_config(self._config_path)
+        cli_data = get_config_with_docs()
+
+        for name, data in cli_data.items():
+            self._docs[name] = data.get("doc", "")
+            file_val = self._config.get(name)
+            if file_val is not None:
+                self._config_values[name] = file_val
+            else:
+                val = data.get("value", "")
+                if isinstance(val, list):
+                    self._config_values[name] = ", ".join(val)
+                else:
+                    self._config_values[name] = val
+
+        self._original_theme = self._config_values.get("theme", "")
+
+    # ── Theme browser handlers ────────────────────────────
+
+    def on_theme_browser_theme_highlighted(
+        self, event: ThemeBrowser.ThemeHighlighted
+    ) -> None:
+        """Live preview: instantly apply theme on cursor movement."""
+        if not self._theme_ready:
+            return
+        self._apply_theme(event.theme)
+
+    def on_theme_browser_theme_selected(
+        self, event: ThemeBrowser.ThemeSelected
+    ) -> None:
+        """Confirm theme selection."""
+        self._original_theme = event.theme
+        self.notify(f"Theme: {event.theme}")
+
+    def on_theme_browser_theme_reverted(
+        self, event: ThemeBrowser.ThemeReverted
+    ) -> None:
+        """Revert to original theme on Escape."""
+        self._apply_theme(self._original_theme)
+
+    def _apply_theme(self, theme: str) -> None:
+        """Apply a theme: set it in config, remove conflicting color overrides, save + reload."""
+        backup_config(self._config)
+        self._config.set("theme", theme)
+        # Remove explicit color keys that would override the theme
+        for key in THEME_COLOR_KEYS:
+            self._config.remove(key)
+        # Also remove palette overrides
+        self._config.remove("palette")
+        try:
+            write_config(self._config)
+            reload_config()
+        except Exception as e:
+            self.notify(f"Theme apply failed: {e}", severity="error")
+
+    # ── Config editor handlers ────────────────────────────
+
+    def on_option_row_value_changed(self, event: OptionRow.ValueChanged) -> None:
+        """Update unsaved indicator when any option changes."""
+        self.has_unsaved = bool(self._collect_changes())
+
+    def on_option_row_color_picker_requested(
+        self, event: OptionRow.ColorPickerRequested
+    ) -> None:
+        """Open the color picker modal for a color option."""
+        # Extract values immediately - event may not persist properly
+        key = event.key
+        current_color = event.current_value
+
+        def on_color_selected(color: str) -> None:
+            if color:
+                try:
+                    input_widget = self.query_one(f"#opt-{key}", Input)
+                    input_widget.value = color
+                except Exception:
+                    pass
+        self.push_screen(ColorPickerScreen(current_color), callback=on_color_selected)
+
+    # ── Persistence ───────────────────────────────────────
+
+    def _collect_changes(self) -> dict[str, str]:
+        """Collect all modified values directly from widgets."""
+        changes: dict[str, str] = {}
+        for panel in self.query(ConfigPanel):
+            changes.update(panel.get_modified_values())
+        return changes
+
+    def action_save(self) -> None:
+        """Save all pending changes to config file and reload."""
+        changes = self._collect_changes()
+        if not changes:
+            self.notify("No changes to save.")
+            return
+
+        backup_config(self._config)
+
+        for key, value in changes.items():
+            if value:
+                self._config.set(key, value)
+            else:
+                self._config.remove(key)
+
+        try:
+            write_config(self._config)
+            reloaded = reload_config()
+
+            for key, value in changes.items():
+                self._config_values[key] = value
+                try:
+                    row = self.query_one(f"#row-{key}", OptionRow)
+                    row.update_original_value(value)
+                except Exception:
+                    pass
+
+            self.has_unsaved = False
+
+            if reloaded:
+                self.notify("Config saved and reloaded!")
+            else:
+                self.notify(
+                    "Saved, but Ghostty reload failed (PID not found).",
+                    severity="warning",
+                )
+
+        except Exception as e:
+            self.notify(f"Save failed: {e}", severity="error")
+
+    # ── Actions ───────────────────────────────────────────
+
+    def action_help(self) -> None:
+        self.push_screen(HelpScreen())
+
+    def action_quit_app(self) -> None:
+        if self.has_unsaved:
+            self.notify(
+                "Unsaved changes! Press Ctrl+S to save, or q again to force quit."
+            )
+            self._force_quit_pending = getattr(self, "_force_quit_pending", False)
+            if self._force_quit_pending:
+                self.exit()
+            else:
+                self._force_quit_pending = True
+        else:
+            self.exit()
+
+    def action_reset_default(self) -> None:
+        """Reset the currently focused option to its default value."""
+        focused = self.focused
+        if focused is None:
+            return
+        widget = focused
+        while widget is not None and not isinstance(widget, OptionRow):
+            widget = widget.parent
+        if isinstance(widget, OptionRow):
+            widget.reset_to_default()
+            self.notify(f"Reset {widget.key} to default")
+
+    def watch_has_unsaved(self, value: bool) -> None:
+        """Update header to show modified indicator."""
+        self.sub_title = "[modified]" if value else ""
+
+
+def main() -> None:
+    app = GhostCfg()
+    app.run()
+
+
+if __name__ == "__main__":
+    main()