vinopilot 0.1.0__py3-none-any.whl

vinopilot-0.1.0.dist-info/METADATA

@@ -0,0 +1,62 @@
+Metadata-Version: 2.5
+Name: vinopilot
+Version: 0.1.0
+Summary: Terminal UI for vinoPilot: install, update and uninstall the vinoPilot apps
+Project-URL: Homepage, https://vinopilot.ca/
+Project-URL: Repository, https://github.com/karanshukla/vinopilot
+Project-URL: Issues, https://github.com/karanshukla/vinopilot/issues
+Project-URL: Changelog, https://github.com/karanshukla/vinopilot/blob/main/CHANGELOG.md
+Author: Karan Shukla
+License-Expression: MIT
+License-File: LICENSE
+Keywords: installer,linux,textual,tui,vinopilot
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Installation/Setup
+Requires-Python: >=3.11
+Requires-Dist: textual<9,>=8
+Description-Content-Type: text/markdown
+
+# vinoPilot in a terminal
+
+The [vinoPilot](https://github.com/karanshukla/vinopilot) window, for a terminal: a table of the vinoPilot apps with their version, how each is installed and whether there's something newer, the installer's output underneath, and one key per action.
+
+It's a thin frontend. Everything it knows comes from the `vinopilot` command's `--json` output, and every action is a `vinopilot` run, so what the window does and what the table does can't drift apart. If the command isn't there, the first screen offers to fetch it from the latest release with the same hash-checked installer the README gives.
+
+## Install
+
+```sh
+uv tool install vinopilot
+vinopilot-tui
+```
+
+or `pipx install vinopilot`. The command is `vinopilot-tui`, not `vinopilot`: that name is the Rust command this drives, and `uv tool` would otherwise overwrite it in `~/.local/bin`.
+
+## Keys
+
+| Key | Does |
+|---|---|
+| `c` | Check for updates (the only thing that goes online, besides the actions themselves) |
+| `i` | Install the selected app; asks which way when there's more than one |
+| `u` | Update it, the way it's installed |
+| `a` | Update everything that has an update, vinoPilot included |
+| `x` | Uninstall it, after a yes |
+| `s` | Show the shell an action would run, without running it |
+| `r` | Change where source checkouts go |
+| `Esc` | Stop the running action |
+| `q` | Quit |
+
+After an action the table is rescanned: offline, or online again if you had checked for updates.
+
+## Limits
+
+- vinoAuthFace's steps run through `pkexec`. On a desktop the polkit agent asks for your password in a dialog. Over ssh with no agent, pkexec has no way to ask and the step fails.
+- Stopping an action ends the `vinopilot` run, but a `pkexec` child is root's and runs on.
+- `VINOPILOT_BIN=/path/to/vinopilot` picks the command to drive, for a checkout build.

vinopilot-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+vinopilot_tui/__init__.py,sha256=S-EbpoSP-238V25-IZe1ADb9KIepNGoDhDSg1xDkjTk,115
+vinopilot_tui/__main__.py,sha256=ms5-5wjqOB49NeaAd9fViSU1AlpCT6t6KmSvxBXnxJw,43
+vinopilot_tui/app.py,sha256=Lg6lo-5zKvY5CYdfgHo9Bl31ZWTCtLjGkKiW9YODHzw,17550
+vinopilot_tui/app.tcss,sha256=zrbGyMvlBMMwYZIzAXjqQCEFDC7VBNKxhSVZaB3uyLk,839
+vinopilot_tui/cli.py,sha256=GCUHLNL9Gatj1OYCQD4BFeT49WmRvqANb7v8FRIoBsc,6332
+vinopilot-0.1.0.dist-info/METADATA,sha256=-1tAbHXT1MMGoqkuO6p9b3NXZkb363gnUGfK42AOM_c,2944
+vinopilot-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+vinopilot-0.1.0.dist-info/entry_points.txt,sha256=MZZl6NL_qXcXCW7KLWGkxAy-1XQJs-i7p1V9tDfA5-A,57
+vinopilot-0.1.0.dist-info/licenses/LICENSE,sha256=iyzZi_FgxGtvs9sGWkiD7EOpLQmBkwR2OQQ-91oCoXs,1069
+vinopilot-0.1.0.dist-info/RECORD,,

vinopilot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

vinopilot-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vinopilot-tui = vinopilot_tui.app:main

vinopilot-0.1.0.dist-info/licenses/LICENSE

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

vinopilot_tui/__init__.py

@@ -0,0 +1,3 @@
+"""vinoPilot's terminal UI: a thin frontend over the `vinopilot` command's `--json` API."""
+
+__version__ = "0.1.0"

vinopilot_tui/__main__.py

@@ -0,0 +1,3 @@
+from vinopilot_tui.app import main
+
+main()

vinopilot_tui/app.py

@@ -0,0 +1,478 @@
+"""The window, in a terminal: a table of the components, the installer's
+output underneath, one key per action. Every action is a `vinopilot` run."""
+
+from __future__ import annotations
+
+import argparse
+import os
+
+from rich.text import Text
+from textual import work
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Horizontal, Vertical, VerticalScroll
+from textual.screen import ModalScreen
+from textual.widgets import (
+    Button,
+    DataTable,
+    Footer,
+    Input,
+    Label,
+    OptionList,
+    RichLog,
+    Static,
+)
+from textual.widgets.option_list import Option
+
+from vinopilot_tui import __version__, cli
+from vinopilot_tui.cli import CommandError, Event, Job, Pilot
+
+CHANNEL_LABEL = {"release": "Release", "source": "Source"}
+ACTIONS = ["install", "update", "uninstall"]
+
+
+def channel_label(component: dict, channel: str) -> str:
+    """`Release`, `Source`, `PyPI` or `crates.io`."""
+    if channel == "package":
+        return {"pypi": "PyPI", "crates.io": "crates.io"}.get(
+            component.get("registry") or "", "Package"
+        )
+    return CHANNEL_LABEL.get(channel, channel)
+
+
+def tilde(path: str) -> str:
+    home = os.path.expanduser("~")
+    return "~" + path[len(home) :] if path.startswith(home) else path
+
+
+class ChooseScreen(ModalScreen[str | None]):
+    """One of a few options, by id."""
+
+    BINDINGS = [Binding("escape", "dismiss(None)", "Cancel")]
+
+    def __init__(self, title: str, options: list[tuple[str, str]]) -> None:
+        super().__init__()
+        self.title_text = title
+        self.options = options
+
+    def compose(self) -> ComposeResult:
+        with Vertical(classes="dialog"):
+            yield Label(self.title_text, classes="title")
+            yield OptionList(*(Option(label, id=key) for key, label in self.options))
+            yield Label("Enter chooses, Esc cancels", classes="hint")
+
+    def on_mount(self) -> None:
+        option_list = self.query_one(OptionList)
+        option_list.highlighted = 0
+        option_list.focus()
+
+    def on_option_list_option_selected(self, event: OptionList.OptionSelected) -> None:
+        self.dismiss(event.option.id)
+
+
+class ConfirmScreen(ModalScreen[bool]):
+    BINDINGS = [
+        Binding("y", "dismiss(True)", "Yes"),
+        Binding("n", "dismiss(False)", "No"),
+        Binding("escape", "dismiss(False)", "Cancel", show=False),
+    ]
+
+    def __init__(self, question: str, detail: str = "") -> None:
+        super().__init__()
+        self.question = question
+        self.detail = detail
+
+    def compose(self) -> ComposeResult:
+        with Vertical(classes="dialog"):
+            yield Label(self.question, classes="title")
+            if self.detail:
+                yield Static(self.detail)
+            with Horizontal(classes="buttons"):
+                yield Button("Yes", id="yes", variant="error")
+                yield Button("No", id="no", variant="primary")
+
+    def on_mount(self) -> None:
+        self.query_one("#no", Button).focus()
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        self.dismiss(event.button.id == "yes")
+
+
+class TextScreen(ModalScreen[None]):
+    """Read-only text, such as the shell an action runs."""
+
+    BINDINGS = [
+        Binding("escape", "dismiss", "Close"),
+        Binding("q", "dismiss", "Close", show=False),
+    ]
+
+    def __init__(self, title: str, text: str) -> None:
+        super().__init__()
+        self.title_text = title
+        self.text = text
+
+    def compose(self) -> ComposeResult:
+        with Vertical(classes="dialog"):
+            yield Label(self.title_text, classes="title")
+            with VerticalScroll():
+                yield Static(Text(self.text))
+            yield Label("Esc closes", classes="hint")
+
+
+class InputScreen(ModalScreen[str | None]):
+    BINDINGS = [Binding("escape", "dismiss(None)", "Cancel")]
+
+    def __init__(self, title: str, value: str) -> None:
+        super().__init__()
+        self.title_text = title
+        self.value = value
+
+    def compose(self) -> ComposeResult:
+        with Vertical(classes="dialog"):
+            yield Label(self.title_text, classes="title")
+            yield Input(value=self.value)
+            yield Label("Enter saves, Esc cancels", classes="hint")
+
+    def on_mount(self) -> None:
+        self.query_one(Input).focus()
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        self.dismiss(event.value.strip() or None)
+
+
+class MissingScreen(ModalScreen[bool]):
+    """No `vinopilot` command: offer the release installer, or leave."""
+
+    BINDINGS = [Binding("escape", "dismiss(False)", "Quit", show=False)]
+
+    def compose(self) -> ComposeResult:
+        with Vertical(classes="dialog"):
+            yield Label("The vinopilot command isn't installed", classes="title")
+            yield Static(
+                "This terminal UI drives the vinopilot command, which does the "
+                "installing. Get it from the latest release? Its installer checks "
+                "the download against the release's SHA256SUMS and puts the command "
+                "in ~/.local/bin, no sudo.\n\n"
+                f"Or in a shell:\n  curl -fsSL {cli.INSTALLER} | bash -s -- --no-gui"
+            )
+            with Horizontal(classes="buttons"):
+                yield Button("Install", id="install", variant="primary")
+                yield Button("Quit", id="quit")
+            yield RichLog(id="missing-log", markup=False, highlight=False, wrap=True)
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        if event.button.id == "quit":
+            self.dismiss(False)
+            return
+        event.button.disabled = True
+        self.install()
+
+    @work(thread=True, exclusive=True)
+    def install(self) -> None:
+        log = self.query_one(RichLog)
+        job = cli.installer()
+        for event in job.events():
+            if event.kind == "line":
+                self.app.call_from_thread(log.write, event.text)
+            elif event.outcome == "done" and cli.find():
+                self.app.call_from_thread(self.dismiss, True)
+                return
+            else:
+                why = event.reason or "the command still isn't there"
+                self.app.call_from_thread(log.write, f"✗ Not installed: {why}")
+        self.app.call_from_thread(self.query_one("#install", Button).__setattr__, "disabled", False)
+
+
+class PilotApp(App[None]):
+    TITLE = "vinoPilot"
+    CSS_PATH = "app.tcss"
+    BINDINGS = [
+        Binding("c", "check", "Check for updates"),
+        Binding("i", "install", "Install"),
+        Binding("u", "update", "Update"),
+        Binding("a", "update_all", "Update all"),
+        Binding("x", "uninstall", "Uninstall"),
+        Binding("s", "steps", "Steps"),
+        Binding("r", "source_root", "Source folder"),
+        Binding("escape", "stop", "Stop", show=False),
+        Binding("q", "quit", "Quit"),
+    ]
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.pilot: Pilot | None = None
+        self.version = ""
+        self.components: list[dict] = []
+        self.checked = False
+        self.scanning = False
+        self.job: Job | None = None
+        self.status_text = ""
+
+    def compose(self) -> ComposeResult:
+        yield Static("", id="status")
+        yield DataTable(id="table", cursor_type="row", zebra_stripes=True)
+        yield RichLog(id="log", markup=False, highlight=False, wrap=True)
+        yield Footer()
+
+    def on_mount(self) -> None:
+        table = self.query_one(DataTable)
+        table.add_columns("App", "Version", "Via", "Update", "About")
+        found = cli.find()
+        if found is None:
+            self.push_screen(MissingScreen(), self.after_missing)
+        else:
+            self.attach(found)
+
+    def after_missing(self, installed: bool | None) -> None:
+        found = cli.find() if installed else None
+        if found is None:
+            self.exit()
+        else:
+            self.log_line("✓ Installed the vinopilot command")
+            self.attach(found)
+
+    def attach(self, binary: str) -> None:
+        self.pilot = Pilot(binary)
+        try:
+            self.version = self.pilot.version()
+        except (CommandError, OSError) as e:
+            self.log_line(f"✗ {binary} won't run: {e}")
+            return
+        self.scan(False)
+
+    # --- the table ---------------------------------------------------------
+
+    @work(thread=True, exclusive=True, group="scan")
+    def scan(self, online: bool) -> None:
+        assert self.pilot is not None
+        self.call_from_thread(self.set_scanning, True, online)
+        try:
+            doc = self.pilot.check() if online else self.pilot.list()
+        except (CommandError, OSError) as e:
+            self.call_from_thread(self.log_line, f"✗ {e}")
+            self.call_from_thread(self.set_scanning, False, online)
+            return
+        self.call_from_thread(self.show, doc, online)
+
+    def set_scanning(self, scanning: bool, online: bool) -> None:
+        self.scanning = scanning
+        if scanning:
+            self.set_status("Checking for updates…" if online else "Looking…")
+        else:
+            self.set_status()
+
+    def show(self, doc: dict, online: bool) -> None:
+        self.components = list(doc.get("components", []))
+        self.checked = self.checked or online
+        self.source_root = str(doc.get("source_root", ""))
+        table = self.query_one(DataTable)
+        row = table.cursor_row
+        table.clear()
+        for c in self.components:
+            table.add_row(*self.cells(c), key=c["id"])
+        if self.components:
+            table.move_cursor(row=min(row, len(self.components) - 1))
+        self.set_scanning(False, online)
+
+    def cells(self, c: dict) -> tuple:
+        installed = c.get("installed")
+        update = c.get("update") or {}
+        if installed:
+            version = installed.get("version") or "?"
+            via = channel_label(c, installed["channel"])
+        else:
+            version, via = "-", Text("not installed", style="dim")
+        if not self.checked:
+            state: str | Text = ""
+        elif not installed:
+            latest = (c.get("latest") or {}).get("release") or {}
+            state = Text(f"latest {latest['value']}", style="dim") if "value" in latest else ""
+        elif update.get("state") == "available":
+            state = Text(f"{update['to']} available", style="bold")
+        elif update.get("state") == "up_to_date":
+            state = Text("up to date", style="dim")
+        else:
+            state = Text(update.get("reason") or "?", style="dim")
+        return (c["name"], version, via, state, Text(c.get("blurb", ""), style="dim"))
+
+    def set_status(self, busy: str = "") -> None:
+        parts = [f"vinoPilot {self.version}" if self.version else "vinoPilot"]
+        if getattr(self, "source_root", ""):
+            parts.append(f"source folder {tilde(self.source_root)}")
+        if busy:
+            parts.append(busy + ("" if self.job is None else "  (Esc stops)"))
+        elif self.checked:
+            n = sum(
+                1 for c in self.components if (c.get("update") or {}).get("state") == "available"
+            )
+            parts.append(
+                f"{n} update{'s' if n != 1 else ''} available" if n else "no updates found"
+            )
+        self.status_text = " · ".join(parts)
+        self.query_one("#status", Static).update(self.status_text)
+
+    def selected(self) -> dict | None:
+        table = self.query_one(DataTable)
+        if not self.components or table.cursor_row >= len(self.components):
+            self.notify("Nothing selected", severity="warning")
+            return None
+        return self.components[table.cursor_row]
+
+    def ready(self) -> bool:
+        """Whether an action can start now."""
+        if self.pilot is None:
+            self.notify("No vinopilot command", severity="error")
+            return False
+        if self.job is not None:
+            self.notify(f"{self.job.label} is still running (Esc stops it)", severity="warning")
+            return False
+        if self.scanning:
+            self.notify("Still looking", severity="warning")
+            return False
+        return True
+
+    # --- actions -----------------------------------------------------------
+
+    def action_check(self) -> None:
+        if self.ready():
+            self.scan(True)
+
+    def action_install(self) -> None:
+        if not self.ready() or (c := self.selected()) is None:
+            return
+        if c.get("installed"):
+            self.notify(f"{c['name']} is already installed; use Update", severity="warning")
+            return
+        channels = c.get("channels") or []
+        if not channels:
+            self.notify(f"{c['name']} has nothing to install", severity="warning")
+            return
+        if len(channels) == 1:
+            self.run_job(self.pilot.install(c["id"], channels[0]))
+            return
+        options = [(ch, channel_label(c, ch)) for ch in channels]
+        self.push_screen(
+            ChooseScreen(f"Install {c['name']} from", options),
+            lambda via: via and self.run_job(self.pilot.install(c["id"], via)),
+        )
+
+    def action_update(self) -> None:
+        if not self.ready() or (c := self.selected()) is None:
+            return
+        if not c.get("installed"):
+            self.notify(f"{c['name']} isn't installed; use Install", severity="warning")
+            return
+        self.run_job(self.pilot.update(c["id"]))
+
+    def action_update_all(self) -> None:
+        if self.ready():
+            self.run_job(self.pilot.update_all())
+
+    def action_uninstall(self) -> None:
+        if not self.ready() or (c := self.selected()) is None:
+            return
+        installed = c.get("installed")
+        if not installed:
+            self.notify(f"{c['name']} isn't installed", severity="warning")
+            return
+        via = channel_label(c, installed["channel"])
+        self.push_screen(
+            ConfirmScreen(f"Uninstall {c['name']} ({via})?", "y uninstalls, n keeps it"),
+            lambda yes: yes and self.run_job(self.pilot.uninstall(c["id"])),
+        )
+
+    def action_steps(self) -> None:
+        if self.pilot is None or (c := self.selected()) is None:
+            return
+        options = [
+            (a, f"{a} ({channel_label(c, ch)})" if (ch := self.channel_for(c, a)) else a)
+            for a in ACTIONS
+        ]
+        self.push_screen(
+            ChooseScreen(f"Show the steps for {c['name']}", options),
+            lambda action: action and self.show_steps(c, action),
+        )
+
+    def channel_for(self, c: dict, action: str) -> str | None:
+        """The channel `vinopilot steps` would pick: how it's installed, else the first."""
+        installed = c.get("installed")
+        if installed:
+            return installed["channel"]
+        channels = c.get("channels") or []
+        return channels[0] if channels and action == "install" else None
+
+    def show_steps(self, c: dict, action: str) -> None:
+        assert self.pilot is not None
+        try:
+            text = self.pilot.steps(c["id"], action)
+        except (CommandError, OSError) as e:
+            self.log_line(f"✗ {e}")
+            return
+        self.push_screen(TextScreen(f"{action} {c['name']}: what would run", text))
+
+    def action_source_root(self) -> None:
+        if not self.ready():
+            return
+        self.push_screen(
+            InputScreen("Where source checkouts go", getattr(self, "source_root", "")),
+            self.set_source_root,
+        )
+
+    def set_source_root(self, path: str | None) -> None:
+        if not path or self.pilot is None:
+            return
+        try:
+            self.pilot.set_source_root(path)
+        except (CommandError, OSError) as e:
+            self.log_line(f"✗ {e}")
+            return
+        self.log_line(f"Source folder: {path}")
+        self.scan(self.checked)
+
+    def action_stop(self) -> None:
+        if self.job is not None:
+            self.job.stop()
+            self.log_line("Stopping…")
+
+    def action_quit(self) -> None:
+        if self.job is not None:
+            self.job.stop()
+        self.exit()
+
+    # --- jobs --------------------------------------------------------------
+
+    @work(thread=True, exclusive=True, group="job")
+    def run_job(self, job: Job) -> None:
+        self.job = job
+        self.call_from_thread(self.set_status, job.label)
+        self.call_from_thread(self.log_line, f"== {job.label}")
+        for event in job.events():
+            if event.kind == "line":
+                self.call_from_thread(self.log_line, event.text)
+            else:
+                self.call_from_thread(self.log_done, event)
+        self.job = None
+        self.call_from_thread(self.scan, self.checked)
+
+    def log_done(self, event: Event) -> None:
+        what = f" {event.app}" if event.app else ""
+        if event.outcome == "done":
+            self.log_line(f"✓ Done{what}")
+        elif event.outcome == "stopped":
+            self.log_line(f"Stopped{what}")
+        else:
+            self.log_line(f"✗ Failed{what}: {event.reason or 'see above'}")
+
+    def log_line(self, text: str) -> None:
+        self.query_one("#log", RichLog).write(text)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="vinopilot-tui", description=__doc__.splitlines()[0])
+    parser.add_argument("--version", action="version", version=f"vinopilot-tui {__version__}")
+    parser.parse_args()
+    PilotApp().run()
+
+
+if __name__ == "__main__":
+    main()

vinopilot_tui/app.tcss

@@ -0,0 +1,66 @@
+#status {
+    height: 1;
+    padding: 0 1;
+    background: $panel;
+    color: $text-muted;
+}
+
+#table {
+    height: 1fr;
+}
+
+#log {
+    height: 12;
+    border-top: solid $primary;
+    padding: 0 1;
+}
+
+ChooseScreen, ConfirmScreen, TextScreen, InputScreen, MissingScreen {
+    align: center middle;
+}
+
+.dialog {
+    width: 72;
+    height: auto;
+    max-height: 90%;
+    border: thick $primary;
+    background: $surface;
+    padding: 1 2;
+}
+
+TextScreen .dialog {
+    width: 90%;
+    height: 90%;
+}
+
+TextScreen VerticalScroll {
+    height: 1fr;
+}
+
+MissingScreen .dialog {
+    width: 84;
+}
+
+#missing-log {
+    height: 10;
+    margin-top: 1;
+}
+
+.title {
+    text-style: bold;
+    margin-bottom: 1;
+}
+
+.hint {
+    color: $text-muted;
+    margin-top: 1;
+}
+
+.buttons {
+    height: auto;
+    margin-top: 1;
+}
+
+.buttons Button {
+    margin-right: 2;
+}

vinopilot_tui/cli.py

@@ -0,0 +1,187 @@
+"""The Rust `vinopilot` command, driven through `--json` (docs/json-api.md).
+
+Nothing here knows the catalog: which apps exist, how they install, what's
+newer. That all comes back as JSON from the command.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+
+INSTALLER = "https://github.com/karanshukla/vinopilot/releases/latest/download/install.sh"
+
+# How the missing-command screen gets the command: the release installer,
+# hash-checked by itself, without the window. Patched in tests.
+INSTALL_COMMAND = ["bash", "-c", f"curl -fsSL {INSTALLER} | bash -s -- --no-gui"]
+
+
+def find() -> str | None:
+    """`$VINOPILOT_BIN`, else `vinopilot` on PATH or in `~/.local/bin`
+    (where the release installer puts it, PATH or not)."""
+    pinned = os.environ.get("VINOPILOT_BIN")
+    if pinned:
+        return pinned if os.access(pinned, os.X_OK) else None
+    path = os.environ.get("PATH", os.defpath)
+    local = os.path.join(os.path.expanduser("~"), ".local", "bin")
+    return shutil.which("vinopilot", path=f"{path}{os.pathsep}{local}")
+
+
+class CommandError(Exception):
+    """The command exited non-zero where a document was expected."""
+
+
+@dataclass(frozen=True)
+class Event:
+    """One line of an action's output, or its end."""
+
+    kind: str  # "line" or "done"
+    text: str = ""
+    app: str = ""
+    channel: str = ""
+    outcome: str = ""  # done, stopped, failed
+    reason: str = ""
+
+    @staticmethod
+    def parse(line: str) -> Event:
+        try:
+            doc = json.loads(line)
+        except ValueError:
+            # The command's own stderr, merged in: usage errors, `✗ ...`.
+            return Event("line", text=line)
+        if not isinstance(doc, dict) or doc.get("event") not in ("line", "done"):
+            return Event("line", text=line)
+        if doc["event"] == "line":
+            return Event("line", text=str(doc.get("text", "")))
+        result = doc.get("result") or {}
+        return Event(
+            "done",
+            app=str(doc.get("app", "")),
+            channel=str(doc.get("channel", "")),
+            outcome=str(result.get("outcome", "failed")),
+            reason=str(result.get("reason") or ""),
+        )
+
+
+@dataclass
+class Job:
+    """A running install, update or uninstall; iterate `events()` to follow it."""
+
+    process: subprocess.Popen[str]
+    label: str
+    done: list[Event] = field(default_factory=list)
+
+    def events(self) -> Iterator[Event]:
+        assert self.process.stdout is not None
+        last = ""
+        for raw in self.process.stdout:
+            line = raw.rstrip("\n")
+            event = Event.parse(line)
+            if event.kind == "done":
+                self.done.append(event)
+            else:
+                last = event.text or last
+            yield event
+        code = self.process.wait()
+        if not self.done:
+            # Exited without saying so: a usage error, a crash, or stopped
+            # before it started.
+            outcome = "stopped" if code < 0 else ("done" if code == 0 else "failed")
+            event = Event("done", outcome=outcome, reason=last if outcome == "failed" else "")
+            self.done.append(event)
+            yield event
+
+    def stop(self) -> None:
+        """Ends the job. A pkexec child is root's and outlives this."""
+        if self.process.poll() is None:
+            self.process.terminate()
+
+
+@dataclass(frozen=True)
+class Pilot:
+    """A `vinopilot` binary."""
+
+    bin: str
+
+    def _args(self, *args: str, source_root: str | None = None) -> list[str]:
+        argv = [self.bin]
+        if source_root:
+            argv += ["--source-root", source_root]
+        return argv + list(args)
+
+    def _run(self, *args: str, json_out: bool = True) -> str:
+        argv = self._args(*args)
+        if json_out:
+            argv.insert(1, "--json")
+        out = subprocess.run(argv, capture_output=True, text=True, stdin=subprocess.DEVNULL)
+        if out.returncode != 0:
+            raise CommandError((out.stderr or out.stdout).strip() or f"exit {out.returncode}")
+        return out.stdout
+
+    def version(self) -> str:
+        """`0.1.0`, from `vinopilot --version`."""
+        return self._run("--version", json_out=False).split()[-1]
+
+    def list(self) -> dict:
+        """The offline document: what's installed, and how."""
+        return json.loads(self._run("list"))
+
+    def check(self) -> dict:
+        """The same, plus `latest` and a judged `update`. Goes online."""
+        return json.loads(self._run("check"))
+
+    def steps(self, app: str, action: str, via: str | None = None) -> str:
+        """The shell an action would run, as text."""
+        args = ["steps", app, action]
+        if via:
+            args += ["--via", via]
+        return self._run(*args, json_out=False)
+
+    def source_root(self) -> str:
+        return json.loads(self._run("config"))["source_root"]
+
+    def set_source_root(self, path: str) -> None:
+        self._run("config", "source_root", path, json_out=False)
+
+    def start(self, label: str, *args: str) -> Job:
+        """Starts an action; its output arrives as `Event`s, stderr merged in."""
+        argv = self._args(*args)
+        argv.insert(1, "--json")
+        process = subprocess.Popen(
+            argv,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            bufsize=1,
+        )
+        return Job(process, label)
+
+    def install(self, app: str, via: str) -> Job:
+        return self.start(f"Installing {app}", "install", app, "--via", via)
+
+    def update(self, app: str) -> Job:
+        return self.start(f"Updating {app}", "update", app)
+
+    def update_all(self) -> Job:
+        return self.start("Updating everything", "update", "--all")
+
+    def uninstall(self, app: str) -> Job:
+        return self.start(f"Uninstalling {app}", "uninstall", app, "--yes")
+
+
+def installer() -> Job:
+    """Runs the release installer, to get the command when there is none."""
+    process = subprocess.Popen(
+        INSTALL_COMMAND,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        bufsize=1,
+    )
+    return Job(process, "Installing vinopilot")