krypton-app 0.1.0__tar.gz

krypton_app-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+*.egg-info/
+/dist/
+/build/
+.claudeloop/
+.playwright-mcp/
+.vibey/plans/
+.agyloop/
+.codexloop/
+.cursorloop/
+.qwenloop/
+.vibey-tmp/site/
+/site/
+
+# Workspace members do not carry their own lockfiles. uv resolves the whole workspace
+# (`[tool.uv.workspace] members`, ADR-0021) into the single root uv.lock, and that is the
+# only one `uv lock --check` validates. The per-runner locks that survived the sibling-repo
+# absorption were installed from by nothing -- CI installs the runners with plain
+# `pip install -e ".[dev]"` -- and served only to raise Dependabot advisories against
+# versions no environment ever resolved. Keep them out.
+src/vibey_runners/*/uv.lock
+src/vibey_tools/*/uv.lock
+
+# pre-commit writes here: `[env] PRE_COMMIT_HOME = ".cache/pre-commit"` in
+# .claude/settings.json keeps its cache inside the sandbox-writable tree, which means
+# every worktree grows a .cache/ that is tooling state, never repository content.
+.cache/
+
+# The npm workspace (root package.json, ADR-0067): its install tree and each package's build.
+/node_modules/
+packages/*/node_modules/
+packages/*/dist/
+packages/*/coverage/

krypton_app-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,29 @@
+# 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/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# krypton-app: the apps' package (sub-doctrine 9.e, ADR-0069). Every app and interface a
+# person uses is krypton; this package carries them and the `krypton` command. It is
+# published by its own workflow, .github/workflows/krypton-app.yml, and by no other.
+[project]
+name = "krypton-app"
+version = "0.1.0"
+description = "krypton, the apps of vibey: launches the local vibey hub and opens it."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+# The launcher starts `vibey serve`, so the engine is what makes it useful. Unpinned: the
+# two packages release on their own cadences, and the launcher checks what the installed
+# engine can do at run time rather than trusting a version number to say it.
+dependencies = ["vibey-engine"]
+
+[project.urls]
+Homepage = "https://the-vibey-project.github.io/vibey/"
+Source = "https://github.com/the-vibey-project/vibey/tree/main/clients/krypton-app"
+Issues = "https://github.com/the-vibey-project/vibey/issues"
+
+[project.scripts]
+krypton = "krypton_app.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.3", "pytest-cov>=6.0", "ruff>=0.8", "mypy>=1.13"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/krypton_app"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.mypy]
+strict = true
+mypy_path = "src"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

krypton_app-0.1.0/src/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-0.1.0/src/krypton_app/__main__.py

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

krypton_app-0.1.0/src/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-0.1.0/src/krypton_app/interfaces/__init__.py

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

krypton_app-0.1.0/src/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-0.1.0/src/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/tests/test_launcher.py

@@ -0,0 +1,141 @@
+"""The krypton launcher, with every side effect faked: no process, browser or network."""
+
+from __future__ import annotations
+
+import io
+from collections.abc import Sequence
+
+import pytest
+
+from krypton_app import cli
+from krypton_app.launcher import KryptonLauncher
+
+
+class FakeProcess:
+    def __init__(
+        self, polls: Sequence[int | None] = (None,), wait: int | BaseException = 0
+    ) -> None:
+        self._polls = list(polls)
+        self._wait = wait
+        self.terminated = False
+
+    def poll(self) -> int | None:
+        return self._polls.pop(0) if len(self._polls) > 1 else self._polls[0]
+
+    def wait(self) -> int:
+        if isinstance(self._wait, BaseException):
+            raise self._wait
+        return self._wait
+
+    def terminate(self) -> None:
+        self.terminated = True
+
+
+def make(
+    *,
+    found: str | None = "/x/vibey",
+    serve_rc: int = 0,
+    process: FakeProcess | None = None,
+    probes: Sequence[bool] = (True,),
+    times: Sequence[float] = (0.0,),
+) -> tuple[KryptonLauncher, io.StringIO, list[list[str]], list[str]]:
+    out = io.StringIO()
+    spawned: list[list[str]] = []
+    browsed: list[str] = []
+    probe_values = list(probes)
+    clock_values = list(times)
+    proc = process or FakeProcess()
+
+    def spawn(argv: Sequence[str]) -> FakeProcess:
+        spawned.append(list(argv))
+        return proc
+
+    launcher = KryptonLauncher(
+        out=out,
+        find=lambda _name: found,
+        run=lambda _argv: serve_rc,
+        spawn=spawn,
+        probe=lambda _url: probe_values.pop(0) if len(probe_values) > 1 else probe_values[0],
+        browse=browsed.append,
+        sleep=lambda _s: None,
+        clock=lambda: clock_values.pop(0) if len(clock_values) > 1 else clock_values[0],
+    )
+    return launcher, out, spawned, browsed
+
+
+def test_no_vibey_says_how_to_install_it() -> None:
+    launcher, out, spawned, _ = make(found=None)
+    assert launcher.launch("127.0.0.1", 8765, open_browser=True) == 1
+    assert "pip install vibey-engine" in out.getvalue()
+    assert spawned == []
+
+
+def test_an_engine_without_serve_starts_nothing_and_says_what_is_available() -> None:
+    launcher, out, spawned, _ = make(serve_rc=2)
+    assert launcher.launch("127.0.0.1", 8765, open_browser=True) == 1
+    assert "does not provide it yet" in out.getvalue()
+    assert "vibey --help" in out.getvalue()
+    assert spawned == []
+
+
+def test_the_hub_starts_and_opens() -> None:
+    launcher, out, spawned, browsed = make()
+    assert launcher.launch("127.0.0.1", 8765, open_browser=True) == 0
+    assert spawned == [["/x/vibey", "serve", "--host", "127.0.0.1", "--port", "8765"]]
+    assert browsed == ["http://127.0.0.1:8765/"]
+    assert "the vibey hub is at" in out.getvalue()
+
+
+def test_no_browser_opens_nothing() -> None:
+    launcher, _, _, browsed = make()
+    assert launcher.launch("127.0.0.1", 8765, open_browser=False) == 0
+    assert browsed == []
+
+
+def test_a_serve_that_dies_early_is_reported() -> None:
+    launcher, out, _, _ = make(process=FakeProcess(polls=[3]), probes=[False])
+    assert launcher.launch("127.0.0.1", 8765, open_browser=True) == 3
+    assert "exited with status 3" in out.getvalue()
+
+
+def test_a_serve_that_never_answers_is_stopped() -> None:
+    proc = FakeProcess()
+    launcher, out, _, _ = make(process=proc, probes=[False], times=[0.0, 100.0])
+    assert launcher.launch("127.0.0.1", 8765, open_browser=True) == 1
+    assert proc.terminated
+    assert "nothing answered" in out.getvalue()
+
+
+def test_a_poll_after_one_wait_then_ready() -> None:
+    launcher, _, _, browsed = make(probes=[False, True], times=[0.0, 1.0])
+    assert launcher.launch("h", 1, open_browser=True) == 0
+    assert browsed == ["http://h:1/"]
+
+
+def test_interrupt_stops_the_hub() -> None:
+    proc = FakeProcess(wait=KeyboardInterrupt())
+    launcher, _, _, _ = make(process=proc)
+    assert launcher.launch("127.0.0.1", 8765, open_browser=False) == 130
+    assert proc.terminated
+
+
+def test_cli_passes_its_options(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls: list[tuple[str, int, bool]] = []
+
+    class Fake:
+        def __init__(self, out: object, vibey: str | None) -> None:
+            assert vibey == "/nonexistent/vibey"
+
+        def launch(self, host: str, port: int, open_browser: bool) -> int:
+            calls.append((host, port, open_browser))
+            return 7
+
+    monkeypatch.setattr(cli, "KryptonLauncher", Fake)
+    assert cli.main(["--no-browser", "--vibey", "/nonexistent/vibey"]) == 7
+    assert calls == [("127.0.0.1", 8765, False)]
+
+
+def test_cli_help_exits_zero() -> None:
+    with pytest.raises(SystemExit) as raised:
+        cli.main(["--help"])
+    assert raised.value.code == 0