krypton-app 0.1.0__py3-none-any.whl

krypton_app/__init__.py

@@ -0,0 +1,2 @@
+# Made with ❤️ by [Vibey](https://the-vibey-project.github.io/vibey/), Developed by [Adam Matthew Steinberger](https://vibewithadam.matthewsteinberger.com/) ([@adammatthewsteinberger](https://github.com/adammatthewsteinberger/)).
+"""krypton-app: the apps of vibey, and the `krypton` command that launches them."""

krypton_app/__main__.py

@@ -0,0 +1,5 @@
+"""python -m krypton_app"""
+
+from krypton_app.cli import main
+
+raise SystemExit(main())

krypton_app/cli.py

@@ -0,0 +1,61 @@
+"""The `krypton` command."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from collections.abc import Sequence
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+from krypton_app.launcher import KryptonLauncher
+
+
+def _version() -> str:
+    # A module-level function because it is a one-line lookup with no state (ADR-0016).
+    try:
+        return version("krypton-app")
+    except PackageNotFoundError:  # pragma: no cover - only in an uninstalled tree
+        return "0+unknown"
+
+
+def _vibey_beside_me() -> str | None:
+    # A module-level function because it is a one-line lookup with no state (ADR-0016).
+    # The engine installed into the same environment as krypton-app comes first: a `vibey`
+    # earlier on PATH may be an older one from another environment.
+    candidate = Path(sys.executable).parent / "vibey"
+    return str(candidate) if os.access(candidate, os.X_OK) else None
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    # A module-level function because a console-script entry point must be one (ADR-0016);
+    # everything it does is KryptonLauncher's.
+    parser = argparse.ArgumentParser(
+        prog="krypton",
+        description=(
+            "krypton, the apps of vibey. Starts the local vibey hub (`vibey serve`) and "
+            "opens it in your browser; if the installed vibey cannot serve it yet, says so "
+            "and lists what is available instead."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"krypton {_version()}")
+    parser.add_argument(
+        "--host", default="127.0.0.1", help="address to serve on (default: 127.0.0.1)"
+    )
+    parser.add_argument("--port", type=int, default=8765, help="port to serve on (default: 8765)")
+    parser.add_argument(
+        "--no-browser", action="store_true", help="start the hub without opening it"
+    )
+    parser.add_argument(
+        "--vibey",
+        default=None,
+        help="the vibey program to use (default: the one beside krypton, else vibey on PATH)",
+    )
+    args = parser.parse_args(argv)
+    launcher = KryptonLauncher(out=sys.stdout, vibey=args.vibey or _vibey_beside_me())
+    return launcher.launch(args.host, args.port, open_browser=not args.no_browser)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

krypton_app/interfaces/__init__.py

@@ -0,0 +1 @@
+"""Interfaces of krypton-app (ADR-0016)."""

krypton_app/interfaces/krypton_launcher_interface.py

@@ -0,0 +1,13 @@
+"""The contract of the krypton launcher (ADR-0016: an interface beside every class)."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class KryptonLauncherInterface(ABC):
+    """Starts the local vibey hub and opens it, or says plainly why it cannot."""
+
+    @abstractmethod
+    def launch(self, host: str, port: int, open_browser: bool) -> int:
+        """Run the hub until it exits; return the process exit status."""

krypton_app/launcher.py

@@ -0,0 +1,104 @@
+"""The krypton launcher: `vibey serve`, then the browser -- or an honest refusal."""
+
+from __future__ import annotations
+
+import subprocess
+import time
+import urllib.error
+import urllib.request
+import webbrowser
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from shutil import which
+from typing import IO, Protocol
+
+from krypton_app.interfaces.krypton_launcher_interface import KryptonLauncherInterface
+
+AVAILABLE_INSTEAD = (
+    "What you can use now:\n"
+    "  vibey --help            the vibey command line\n"
+    "  vibey doctor            what is installed and what is missing\n"
+    "  the VS Code extension   krypton inside your editor (clients/vscode)\n"
+)
+
+
+class _Process(Protocol):
+    def poll(self) -> int | None: ...
+    def wait(self) -> int: ...
+    def terminate(self) -> None: ...
+
+
+def _probe(url: str) -> bool:
+    """Whether anything answers HTTP at `url`, whatever the status."""
+    try:
+        with urllib.request.urlopen(url, timeout=2):  # nosec B310 - loopback URL we built
+            return True
+    except urllib.error.HTTPError:
+        return True
+    except (urllib.error.URLError, OSError):
+        return False
+
+
+@dataclass
+class KryptonLauncher(KryptonLauncherInterface):
+    """Launches the hub through the installed `vibey`, with every side effect injectable."""
+
+    out: IO[str]
+    vibey: str | None = None
+    ready_timeout: float = 60.0
+    find: Callable[[str], str | None] = which
+    run: Callable[[Sequence[str]], int] = field(
+        default=lambda argv: (
+            subprocess.run(  # nosec B603 - argv, no shell
+                list(argv), capture_output=True, timeout=30, check=False
+            ).returncode
+        )
+    )
+    spawn: Callable[[Sequence[str]], _Process] = field(
+        default=lambda argv: subprocess.Popen(list(argv))  # nosec B603 - argv, no shell
+    )
+    probe: Callable[[str], bool] = _probe
+    browse: Callable[[str], object] = webbrowser.open
+    sleep: Callable[[float], None] = time.sleep
+    clock: Callable[[], float] = time.monotonic
+
+    def launch(self, host: str, port: int, open_browser: bool) -> int:
+        vibey = self.vibey or self.find("vibey")
+        if vibey is None:
+            self.out.write(
+                "krypton: the vibey command is not installed, so there is no hub to start.\n"
+                "Install the engine with: pip install vibey-engine\n"
+            )
+            return 1
+        if self.run([vibey, "serve", "--help"]) != 0:
+            self.out.write(
+                "krypton: the local web app is started by `vibey serve`, and the installed\n"
+                f"vibey ({vibey}) does not provide it yet. Nothing was started.\n"
+                + AVAILABLE_INSTEAD
+            )
+            return 1
+        url = f"http://{host}:{port}/"
+        process = self.spawn([vibey, "serve", "--host", host, "--port", str(port)])
+        deadline = self.clock() + self.ready_timeout
+        while not self.probe(url):
+            status = process.poll()
+            if status is not None:
+                self.out.write(
+                    f"krypton: vibey serve exited with status {status} before it answered.\n"
+                )
+                return status or 1
+            if self.clock() >= deadline:
+                self.out.write(
+                    f"krypton: nothing answered at {url} within {self.ready_timeout:g}s.\n"
+                )
+                process.terminate()
+                return 1
+            self.sleep(0.5)
+        self.out.write(f"krypton: the vibey hub is at {url}\n")
+        if open_browser:
+            self.browse(url)
+        try:
+            return process.wait()
+        except KeyboardInterrupt:
+            process.terminate()
+            return 130

krypton_app-0.1.0.dist-info/METADATA

@@ -0,0 +1,46 @@
+Metadata-Version: 2.5
+Name: krypton-app
+Version: 0.1.0
+Summary: krypton, the apps of vibey: launches the local vibey hub and opens it.
+Project-URL: Homepage, https://the-vibey-project.github.io/vibey/
+Project-URL: Source, https://github.com/the-vibey-project/vibey/tree/main/clients/krypton-app
+Project-URL: Issues, https://github.com/the-vibey-project/vibey/issues
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: vibey-engine
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# krypton-app
+
+krypton is every app and interface of [vibey](https://the-vibey-project.github.io/vibey/).
+This package carries them and installs one command, `krypton`.
+
+```bash
+pip install krypton-app      # brings vibey-engine with it
+krypton                      # start the local vibey hub and open it in your browser
+krypton --help
+```
+
+## What `krypton` does today
+
+`krypton` is a launcher. It finds the `vibey` command, starts `vibey serve` on
+`127.0.0.1:8765` (change it with `--host` and `--port`), waits until the hub answers, and
+opens it in your browser. `--no-browser` only starts it.
+
+When the installed vibey-engine has no `vibey serve` yet, `krypton` says so plainly, lists
+what you can use instead, and exits with status 1. It never pretends a hub is running.
+
+## Releases
+
+Published by `.github/workflows/krypton-app.yml` alone, by trusted publishing: a dev build
+to TestPyPI (environment `testpypi`) on each push to `develop` that changes this tree or the
+workflow, and a release to PyPI (environment `pypi`) on each such push to `main`. There is no
+schedule. A push GitHub skips publishes nothing: a squash merge whose message quotes an old
+`[skip ci]` subject skips every push workflow, which is how the 3.0.0 promotion first
+published neither package. Merge a promotion by rebase, or edit the squash message. ADR-0069 records why vibey publishes exactly two packages, `vibey-engine` and
+`krypton-app`.

krypton_app-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+krypton_app/__init__.py,sha256=RDf_IDp2ZN_S_behzNYyFGgBx9nsDQiVOTNHNstss3w,318
+krypton_app/__main__.py,sha256=kXjgx3aDuOwiLYTQTF8o2g0Zg6f69Q-l7Yanf2xYNsk,88
+krypton_app/cli.py,sha256=WCxi74-eBG3qnic0YlxRA4_7_O9j0vkpH5q4MT8UBmY,2354
+krypton_app/launcher.py,sha256=YRqFVRXzTNATuU9S5hu1qq2SELZTGNLSNpH6j9AIuYs,3756
+krypton_app/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+krypton_app/interfaces/__init__.py,sha256=FFuGqyvWl8qYoA51z238K2vrQgRG-qQjLfeTUzSHx1s,44
+krypton_app/interfaces/krypton_launcher_interface.py,sha256=TUzCwsbAw1NCQM3GYbm1nEW0Ixu-lo2vNs1friE9EhQ,448
+krypton_app-0.1.0.dist-info/METADATA,sha256=zY2ksXPpH0u2uJyiZjtNbw64p-ITPUuj2BAppp_9weU,2089
+krypton_app-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+krypton_app-0.1.0.dist-info/entry_points.txt,sha256=SUniEOzAlnva7bhd4Aqm6RZ6CBQ87en-Pnpw7nY-lwE,49
+krypton_app-0.1.0.dist-info/RECORD,,

krypton_app-0.1.0.dist-info/WHEEL

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

krypton_app-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+krypton = krypton_app.cli:main