KohakuTerrarium 2.0.0.dev2__tar.gz → 2.0.0.dev3__tar.gz

{kohakuterrarium-2.0.0.dev2/src/KohakuTerrarium.egg-info → kohakuterrarium-2.0.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: KohakuTerrarium
-Version: 2.0.0.dev2
+Version: 2.0.0.dev3
 Summary: A universal agent framework for building self-driven AI agents and multi-agent teams
 Author-email: "Shih-Ying Yeh (KohakuBlueLeaf)" <apolloyeh0123@gmail.com>
 License: KohakuTerrarium-1.0

{kohakuterrarium-2.0.0.dev2 → kohakuterrarium-2.0.0.dev3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "KohakuTerrarium"
-version = "2.0.0.dev2"
+version = "2.0.0.dev3"
 description = "A universal agent framework for building self-driven AI agents and multi-agent teams"
 authors = [
     { name = "Shih-Ying Yeh (KohakuBlueLeaf)", email = "apolloyeh0123@gmail.com" },
@@ -157,7 +157,7 @@ select = ["F401", "F841"]
 [tool.briefcase]
 project_name = "KohakuTerrarium"
 bundle = "com.kohaku.terrarium"
-version = "2.0.0.dev2"
+version = "2.0.0.dev3"
 url = "https://github.com/Kohaku-Lab/KohakuTerrarium"
 license.file = "LICENSE"
 author = "Shih-Ying Yeh (KohakuBlueLeaf)"
@@ -167,32 +167,29 @@ author_email = "apolloyeh0123@gmail.com"
 formal_name = "KohakuTerrarium"
 description = "Universal Agent Framework - Desktop App"
 icon = "src/kohakuterrarium/app_icons/app"
-# Wrapper-only sources.  The full framework is INSTALLED into the
-# launcher's managed venv at first launch (offline from
-# ``wheels-bundle/`` or online from the configured source).  See
-# ``plans/1.5.0-roadmap/06-app-update/`` for the design.
+# 06b — wrapper-only sources.  The framework is DOWNLOADED as a
+# pre-built release tarball at first launch (offline from
+# ``bundled-release/`` or online from the configured channel feed).
+# See ``plans/1.5.0-roadmap/06b-release-bundle-update/`` for the design.
 #
-# ``wheels-bundle/`` ships as a sibling directory inside the bundle so
-# the launcher's ``bundled_wheels_dir()`` finds it at runtime.  CI
-# populates ``wheels-bundle/`` via ``scripts/build_wrapper_wheels.py``
-# before ``briefcase create``; the verify step in release.yml asserts
-# the produced artifact actually carries it.  See
-# ``plans/1.5.0-roadmap/06-app-update/01-bundled-first-install/``.
-sources = ["src/kohakuterrarium", "wheels-bundle"]
+# ``bundled-release/`` ships as a sibling directory inside the bundle
+# so the launcher's ``bundled_release_dir()`` finds it at runtime.
+# CI populates ``bundled-release/`` from the matrix ``release-tree``
+# job before ``briefcase create``.
+sources = ["src/kohakuterrarium", "bundled-release"]
 startup_module = "kohakuterrarium.__briefcase__"
 requires = [
-    # Launcher needs only pip, packaging, and pywebview (for the
-    # splash window).  The framework + its 30+ runtime deps live in
-    # the venv the launcher creates, not the bundle.
-    "pip>=24.0",
+    # Launcher needs only packaging (version compare), pywebview
+    # (splash UI — optional, Tk fallback), and zstandard (preferred
+    # tarball compression — .tar.gz fallback). NO pip, NO venv,
+    # NO ensurepip — the 06 design that depended on those was dead-on-
+    # arrival on Windows briefcase shells that strip stdlib modules.
     "packaging>=23.0",
     "pywebview==6.1",
+    "zstandard>=0.22",
 ]
 # proxy_tools (pywebview dep) only has sdist on PyPI — pre-build wheel in CI.
-# ``wheels-bundle/`` carries the kohakuterrarium wheel + its transitive
-# deps for offline first-launch (populated by
-# ``scripts/build_wrapper_wheels.py`` before ``briefcase build``).
-requirement_installer_args = ["--find-links", "wheels", "--find-links", "wheels-bundle"]
+requirement_installer_args = ["--find-links", "wheels"]
 
 [tool.briefcase.app.kohakuterrarium.macOS]
 universal_build = false

{kohakuterrarium-2.0.0.dev2 → kohakuterrarium-2.0.0.dev3/src/KohakuTerrarium.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: KohakuTerrarium
-Version: 2.0.0.dev2
+Version: 2.0.0.dev3
 Summary: A universal agent framework for building self-driven AI agents and multi-agent teams
 Author-email: "Shih-Ying Yeh (KohakuBlueLeaf)" <apolloyeh0123@gmail.com>
 License: KohakuTerrarium-1.0

{kohakuterrarium-2.0.0.dev2 → kohakuterrarium-2.0.0.dev3}/src/KohakuTerrarium.egg-info/SOURCES.txt

@@ -407,15 +407,16 @@ src/kohakuterrarium/launcher/__init__.py
 src/kohakuterrarium/launcher/__main__.py
 src/kohakuterrarium/launcher/_lock.py
 src/kohakuterrarium/launcher/bootloader.py
+src/kohakuterrarium/launcher/downloader.py
+src/kohakuterrarium/launcher/feeds.py
 src/kohakuterrarium/launcher/log.py
 src/kohakuterrarium/launcher/migration.py
 src/kohakuterrarium/launcher/paths.py
 src/kohakuterrarium/launcher/settings.py
-src/kohakuterrarium/launcher/sources.py
 src/kohakuterrarium/launcher/splash_server.py
 src/kohakuterrarium/launcher/splash_window.py
+src/kohakuterrarium/launcher/tree_ops.py
 src/kohakuterrarium/launcher/update_runner.py
-src/kohakuterrarium/launcher/venv_ops.py
 src/kohakuterrarium/llm/__init__.py
 src/kohakuterrarium/llm/anthropic_cache.py
 src/kohakuterrarium/llm/anthropic_format.py
@@ -766,12 +767,12 @@ src/kohakuterrarium/web_dist/assets/KaTeX_Size4-Regular-Dl5lxZxV.woff2
 src/kohakuterrarium/web_dist/assets/KaTeX_Typewriter-Regular-C0xS9mPB.woff
 src/kohakuterrarium/web_dist/assets/KaTeX_Typewriter-Regular-CO6r4hn1.woff2
 src/kohakuterrarium/web_dist/assets/KaTeX_Typewriter-Regular-D3Ib7_Hf.ttf
-src/kohakuterrarium/web_dist/assets/_id_-CU3uGW47.js
-src/kohakuterrarium/web_dist/assets/_key_-DvKoPuoc.js
+src/kohakuterrarium/web_dist/assets/_id_-CQuALEFj.js
+src/kohakuterrarium/web_dist/assets/_key_-Dwr8H8dF.js
 src/kohakuterrarium/web_dist/assets/abap-DNgBPGRI.js
 src/kohakuterrarium/web_dist/assets/apex-B4r7dYl2.js
-src/kohakuterrarium/web_dist/assets/api-Bu8fp5qd.js
-src/kohakuterrarium/web_dist/assets/axios-DEoS1rCJ.js
+src/kohakuterrarium/web_dist/assets/api-BV0fScbj.js
+src/kohakuterrarium/web_dist/assets/axios-BPEz4Z9Y.js
 src/kohakuterrarium/web_dist/assets/azcli-BKm6S2Cw.js
 src/kohakuterrarium/web_dist/assets/bat-BSxnouuk.js
 src/kohakuterrarium/web_dist/assets/bicep-B_GZ-wpx.js
@@ -805,10 +806,10 @@ src/kohakuterrarium/web_dist/assets/highlight-C8LL_u4z.css
 src/kohakuterrarium/web_dist/assets/html-DVGxM4pJ.js
 src/kohakuterrarium/web_dist/assets/html.worker-wsVgX3gp.js
 src/kohakuterrarium/web_dist/assets/htmlMode-C5KOTPV1.js
-src/kohakuterrarium/web_dist/assets/index-0ZdG87aI.css
-src/kohakuterrarium/web_dist/assets/index-DjzJ77md.js
+src/kohakuterrarium/web_dist/assets/index-DrSNCGQH.css
+src/kohakuterrarium/web_dist/assets/index-WCbP0Trd.js
 src/kohakuterrarium/web_dist/assets/ini-BeMa714h.js
-src/kohakuterrarium/web_dist/assets/instances-BILX_VEN.js
+src/kohakuterrarium/web_dist/assets/instances-DqdS7Lrl.js
 src/kohakuterrarium/web_dist/assets/java-Dq86Qznf.js
 src/kohakuterrarium/web_dist/assets/javascript-BOm_W1Jn.js
 src/kohakuterrarium/web_dist/assets/json.worker-CcNiYOcv.js
@@ -828,8 +829,8 @@ src/kohakuterrarium/web_dist/assets/monaco-editor-Br_kD0ds.css
 src/kohakuterrarium/web_dist/assets/msdax-_4dmgZQ-.js
 src/kohakuterrarium/web_dist/assets/mysql-P77yJQsH.js
 src/kohakuterrarium/web_dist/assets/objective-c-ClnQjoXg.js
-src/kohakuterrarium/web_dist/assets/pages-Cko_YsNQ.js
-src/kohakuterrarium/web_dist/assets/panel-debug-BSGIYOa5.js
+src/kohakuterrarium/web_dist/assets/pages-DSvfMUqz.js
+src/kohakuterrarium/web_dist/assets/panel-debug-D0a3hCe3.js
 src/kohakuterrarium/web_dist/assets/pascal-Bc7vQ0ww.js
 src/kohakuterrarium/web_dist/assets/pascaligo-CU0Jj3mr.js
 src/kohakuterrarium/web_dist/assets/perl-DUQq7oYb.js

kohakuterrarium-2.0.0.dev3/src/kohakuterrarium/api/routes/app_update.py

@@ -0,0 +1,272 @@
+"""``/api/app/*`` — app-update API for the Vue ``Admin → Updates`` tab.
+
+Wraps the launcher's update_runner + feeds + settings helpers in HTTP
++ WebSocket form so the frontend can drive the same flow the CLI's
+``kt self-update`` exposes. Only mounted in standalone and lab-host
+modes; worker installs (lab-client) return 404 across the whole
+namespace.
+
+Endpoints (canonical: ``plans/1.5.0-roadmap/06b-release-bundle-update/design.md`` §11):
+
+| GET  | ``/api/app/settings``       | round-trip settings |
+| PUT  | ``/api/app/settings``       | round-trip settings |
+| POST | ``/api/app/feeds/probe``    | force-fetch channel manifest |
+| GET  | ``/api/app/state``          | aggregate UI state |
+| POST | ``/api/app/update``         | start update; returns WS path |
+| POST | ``/api/app/rollback``       | revert pointer |
+| WS   | ``/ws/app/update``          | streams progress frames |
+"""
+
+import asyncio
+import json
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Request, WebSocket, WebSocketDisconnect
+
+from kohakuterrarium.launcher import settings as _launcher_settings
+from kohakuterrarium.launcher.feeds import (
+    FeedError,
+    current_platform_tag,
+    current_py_abi_tag,
+    fetch_manifest,
+    list_available_releases,
+)
+from kohakuterrarium.launcher.migration import (
+    is_launcher_install,
+    is_legacy_bundle,
+)
+from kohakuterrarium.launcher.tree_ops import (
+    list_installed_versions,
+    read_active_pointer,
+)
+from kohakuterrarium.launcher.update_runner import (
+    UpdateResult,
+    probe_only,
+    rollback,
+    run_update,
+)
+
+router = APIRouter()
+# WebSocket lives on its own router so the API router's ``/api/app``
+# prefix doesn't shift the canonical ``/ws/app/update`` path.
+ws_router = APIRouter()
+
+
+def _wrapper_mode_only(request: Request) -> None:
+    """Reject the call when the host isn't a wrapper / standalone install."""
+    lab_mode = getattr(request.app.state, "lab_mode", "standalone")
+    if lab_mode == "lab-client":
+        raise HTTPException(
+            404, "app-update routes are not available in lab-client mode"
+        )
+
+
+def _result_to_dict(r: UpdateResult) -> dict[str, Any]:
+    return {
+        "ok": r.ok,
+        "version": r.version,
+        "build_id": r.build_id,
+        "error": r.error,
+        "restart-required": r.restart_required,
+        "skipped-reason": r.skipped_reason,
+    }
+
+
+# ── Settings ────────────────────────────────────────────────────────
+
+
+@router.get("/settings")
+async def get_settings(request: Request) -> dict[str, Any]:
+    _wrapper_mode_only(request)
+    return _launcher_settings.to_public_dict(_launcher_settings.load())
+
+
+@router.put("/settings")
+async def put_settings(request: Request, body: dict[str, Any]) -> dict[str, Any]:
+    _wrapper_mode_only(request)
+    if not isinstance(body, dict):
+        raise HTTPException(400, "request body must be a JSON object")
+    new_settings = _launcher_settings.from_public_dict(body)
+    _launcher_settings.save(new_settings)
+    return _launcher_settings.to_public_dict(new_settings)
+
+
+# ── State + probe ───────────────────────────────────────────────────
+
+
+@router.get("/state")
+async def get_state(request: Request) -> dict[str, Any]:
+    _wrapper_mode_only(request)
+    cfg = _launcher_settings.load()
+    ptr = read_active_pointer()
+    installed = [
+        {
+            "version": p.version,
+            "build_id": p.build_id,
+            "installed_at": p.installed_at,
+        }
+        for p in list_installed_versions()
+    ]
+    return {
+        "active": (
+            {
+                "version": ptr.version,
+                "build_id": ptr.build_id,
+                "installed_at": ptr.installed_at,
+            }
+            if ptr is not None
+            else None
+        ),
+        "installed": installed,
+        "settings": _launcher_settings.to_public_dict(cfg),
+        "launcher_install": is_launcher_install(),
+        "legacy_bundle": is_legacy_bundle(),
+        "platform": current_platform_tag(),
+        "py_abi": current_py_abi_tag(),
+        "last_check_at": cfg.runtime.last_check_at,
+        "last_check_error": cfg.runtime.last_check_error,
+    }
+
+
+@router.post("/feeds/probe")
+async def post_feeds_probe(request: Request) -> dict[str, Any]:
+    """Force-fetch the channel manifest; return its releases filtered
+    for the running platform/abi (newest first)."""
+    _wrapper_mode_only(request)
+    cfg = _launcher_settings.load()
+    plat = current_platform_tag()
+    abi = current_py_abi_tag()
+    try:
+        manifest = await asyncio.to_thread(fetch_manifest, cfg, force_refresh=True)
+    except FeedError as e:
+        raise HTTPException(502, f"feed probe failed: {e}") from e
+    releases = list_available_releases(manifest, platform_tag=plat, py_abi_tag=abi)
+    latest = releases[0]["version"] if releases else None
+    return {
+        "channel": cfg.channel,
+        "feed": _launcher_settings.to_public_dict(cfg)["feed"],
+        "platform": plat,
+        "py_abi": abi,
+        "latest_version": latest,
+        "releases": releases,
+    }
+
+
+# ── Update / rollback ───────────────────────────────────────────────
+
+
+@router.post("/update")
+async def post_update(request: Request) -> dict[str, Any]:
+    _wrapper_mode_only(request)
+    if not is_launcher_install():
+        raise HTTPException(
+            409,
+            "this install is not launcher-managed; "
+            "run `kt self-update` from the terminal instead",
+        )
+    return {"websocket": "/ws/app/update"}
+
+
+@router.post("/rollback")
+async def post_rollback(request: Request) -> dict[str, Any]:
+    _wrapper_mode_only(request)
+    if not is_launcher_install():
+        raise HTTPException(409, "rollback is launcher-only")
+    result = await asyncio.to_thread(rollback)
+    return _result_to_dict(result)
+
+
+@router.post("/check")
+async def post_check(request: Request) -> dict[str, Any]:
+    """Probe what would be installed without doing it."""
+    _wrapper_mode_only(request)
+    result = await asyncio.to_thread(probe_only)
+    return _result_to_dict(result)
+
+
+# ── WebSocket ───────────────────────────────────────────────────────
+
+
+_WS_PATH = "/ws/app/update"
+
+
+async def _stream_update(ws: WebSocket) -> None:
+    """Drive run_update() to completion, streaming progress frames."""
+    queue: asyncio.Queue = asyncio.Queue()
+
+    def _push(phase: str, percent: float, message: str) -> None:
+        # Called from the worker thread; thread-safe enqueue.
+        try:
+            queue.put_nowait({"phase": phase, "percent": percent, "message": message})
+        except Exception:  # pragma: no cover - defensive
+            pass
+
+    loop = asyncio.get_running_loop()
+
+    async def _pump() -> UpdateResult:
+        return await loop.run_in_executor(None, lambda: run_update(_push))
+
+    runner_task = asyncio.create_task(_pump())
+    try:
+        while True:
+            done, _ = await asyncio.wait(
+                [runner_task, asyncio.create_task(queue.get())],
+                return_when=asyncio.FIRST_COMPLETED,
+                timeout=0.5,
+            )
+            # Drain whatever frames are pending.
+            while not queue.empty():
+                frame = queue.get_nowait()
+                await ws.send_text(json.dumps(frame))
+            if runner_task in done:
+                break
+    finally:
+        result = await runner_task
+    terminal = {
+        "phase": "done" if result.ok else "failed",
+        "percent": 100,
+        "message": (
+            f"updated to {result.version}" if result.ok else (result.error or "failed")
+        ),
+        "status": "ok" if result.ok else "failed",
+        "restart-required": result.restart_required,
+        "version": result.version,
+        "build_id": result.build_id,
+        "skipped-reason": result.skipped_reason,
+    }
+    await ws.send_text(json.dumps(terminal))
+
+
+@ws_router.websocket(_WS_PATH)
+async def ws_update(ws: WebSocket) -> None:
+    lab_mode = getattr(ws.app.state, "lab_mode", "standalone")
+    if lab_mode == "lab-client":
+        await ws.close(code=4404)
+        return
+    if not is_launcher_install():
+        await ws.accept()
+        await ws.send_text(
+            json.dumps(
+                {
+                    "phase": "refused",
+                    "percent": 0,
+                    "message": "non-launcher install; use `kt self-update` from terminal",
+                    "status": "failed",
+                }
+            )
+        )
+        await ws.close()
+        return
+    await ws.accept()
+    try:
+        await _stream_update(ws)
+    except WebSocketDisconnect:
+        return
+    finally:
+        try:
+            await ws.close()
+        except Exception:  # pragma: no cover - already closed
+            pass
+
+
+__all__ = ["router", "ws_router"]

{kohakuterrarium-2.0.0.dev2 → kohakuterrarium-2.0.0.dev3}/src/kohakuterrarium/api/routes/catalog/server_info.py

@@ -24,7 +24,7 @@ from typing import Any
 from fastapi import APIRouter, Depends, Request
 
 from kohakuterrarium.api.deps import get_service
-from kohakuterrarium.launcher.paths import wrapper_marker_path
+from kohakuterrarium.launcher.migration import is_launcher_install
 from kohakuterrarium.utils.config_dir import config_dir
 from kohakuterrarium.utils.logging import get_logger
 
@@ -45,9 +45,9 @@ def _get_version() -> str:
 
 
 def _install_kind() -> str:
-    """Wrapper-managed venv vs other."""
+    """Launcher-managed install vs other (dev, packaged python, etc.)."""
     try:
-        return "wrapper" if wrapper_marker_path().is_file() else "user"
+        return "launcher" if is_launcher_install() else "user"
     except OSError:
         return "user"
 

kohakuterrarium-2.0.0.dev3/src/kohakuterrarium/cli/self_update.py

@@ -0,0 +1,172 @@
+"""``kt self-update`` — CLI parity for the launcher's update flow.
+
+The 06b launcher is the *only* thing that updates this install. This
+verb is a thin client over :mod:`launcher.update_runner`:
+
+- **Launcher install** (active pointer + interpreter under
+  ``runtime/versions/``) → call :func:`launcher.update_runner.run_update`
+  with optional one-shot overrides (`--channel`, `--feed-url`, `--pin`).
+- **Anything else** (dev install via ``pip install -e .``, lab worker
+  node, system package, pipx) → refuse with a one-line explanation.
+  No more "fall back to pip" — the framework process running outside
+  the launcher is by definition not something we manage.
+"""
+
+import argparse
+import importlib.metadata
+import sys
+
+from kohakuterrarium.launcher import settings as _launcher_settings
+from kohakuterrarium.launcher.feeds import (
+    FeedError,
+    resolve_feed,
+)
+from kohakuterrarium.launcher.migration import is_launcher_install
+from kohakuterrarium.launcher.tree_ops import read_active_pointer
+from kohakuterrarium.launcher.update_runner import (
+    probe_only,
+    rollback,
+    run_update,
+)
+
+
+def _print(line: str) -> None:
+    sys.stdout.write(line + "\n")
+    sys.stdout.flush()
+
+
+def _current_version() -> str | None:
+    try:
+        return importlib.metadata.version("kohakuterrarium")
+    except importlib.metadata.PackageNotFoundError:
+        return None
+
+
+def _apply_overrides(args: argparse.Namespace) -> None:
+    """Apply ``--channel``, ``--feed-url``, ``--pin`` overrides to settings.
+
+    Persisted so the next launcher launch inherits the new choice —
+    matches the GUI's behaviour where the dropdown is sticky.
+    """
+    cfg = _launcher_settings.load()
+    touched = False
+    if args.channel is not None:
+        cfg.channel = args.channel
+        touched = True
+    if args.feed_url is not None:
+        cfg.feed.kind = "custom"
+        cfg.feed.url = args.feed_url
+        touched = True
+    if args.pin is not None:
+        cfg.pinned_version = args.pin or None
+        touched = True
+    if touched:
+        _launcher_settings.save(cfg)
+
+
+def _refuse_non_launcher() -> int:
+    _print("kt self-update: this process is not running inside a launcher install.")
+    _print(
+        "  - Developer checkout?  Run `git pull` (or `pip install -e .`) in your tree."
+    )
+    _print("  - Worker node?         Update the host's launcher install separately.")
+    _print("  - pipx / system pip?   Use those tools' own update commands.")
+    return 2
+
+
+def self_update_cli(args: argparse.Namespace) -> int:
+    cur = _current_version() or "unknown"
+
+    if not is_launcher_install():
+        if args.check_only:
+            _print(
+                f"kt self-update: current={cur}; not running inside a launcher install"
+            )
+            return 2
+        return _refuse_non_launcher()
+
+    _apply_overrides(args)
+
+    if args.check_only:
+        result = probe_only()
+        if not result.ok:
+            _print(f"kt self-update: probe failed — {result.error}")
+            return 2
+        _print(f"kt self-update: current={cur}; latest={result.version}")
+        return 0 if result.skipped_reason != "up-to-date" else 1
+
+    if args.rollback:
+        result = rollback()
+        if not result.ok:
+            _print(f"kt self-update: rollback failed — {result.error}")
+            return 1
+        _print(
+            f"kt self-update: pointer reverted to {result.version}; restart to use it"
+        )
+        return 0
+
+    if args.dry_run:
+        cfg = _launcher_settings.load()
+        try:
+            target = resolve_feed(cfg, force_refresh=True)
+        except FeedError as e:
+            _print(f"kt self-update: dry-run resolution failed — {e}")
+            return 2
+        ptr = read_active_pointer()
+        active = ptr.version if ptr else "<none>"
+        _print(
+            f"kt self-update: --dry-run; would install {target.version} "
+            f"(active={active}, feed={cfg.feed.kind}, channel={cfg.channel})"
+        )
+        return 0
+
+    result = run_update()
+    if not result.ok:
+        _print(f"kt self-update: failed — {result.error}")
+        return 1
+    if result.skipped_reason == "up-to-date":
+        _print(f"kt self-update: already on {result.version}; no change")
+        return 0
+    _print(f"kt self-update: updated to {result.version}; restart the app to use it")
+    return 0
+
+
+def add_self_update_subparser(subparsers) -> None:
+    parser = subparsers.add_parser(
+        "self-update",
+        help="Update KohakuTerrarium via the launcher's release feed",
+    )
+    parser.add_argument(
+        "--check-only",
+        action="store_true",
+        help="Resolve the feed and print latest available; exit 0 if newer, 1 if up-to-date.",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Resolve the feed and print what would be installed; do not install.",
+    )
+    parser.add_argument(
+        "--rollback",
+        action="store_true",
+        help="Revert the active pointer to the previous installed version.",
+    )
+    parser.add_argument(
+        "--channel",
+        choices=("stable", "beta", "nightly"),
+        default=None,
+        help="Persist a new channel before updating (sticky, mirrors the GUI dropdown).",
+    )
+    parser.add_argument(
+        "--feed-url",
+        default=None,
+        help="Switch to a custom feed URL before updating (sticky).",
+    )
+    parser.add_argument(
+        "--pin",
+        default=None,
+        help='Persist a pinned version (e.g. "1.5.1"); empty string clears.',
+    )
+
+
+__all__ = ["add_self_update_subparser", "self_update_cli"]

kohakuterrarium-2.0.0.dev3/src/kohakuterrarium/launcher/__init__.py

@@ -0,0 +1,36 @@
+"""KohakuTerrarium launcher — thin wrapper that owns the runtime tree.
+
+This package is the briefcase desktop bundle's *only* runtime entry
+point. It manages versioned installs under
+``~/.kohakuterrarium/runtime/versions/<X.Y.Z>/``, atomically swaps the
+``runtime/active`` pointer, and ``os.execv``'s into the active
+version's ``scripts/kt`` to replace itself with the real framework
+process.
+
+**Strict isolation rule.** Modules under
+:mod:`kohakuterrarium.launcher` must NOT import from any other
+``kohakuterrarium.*`` package. The launcher runs BEFORE any framework
+code is on ``sys.path`` (first launch, recovery), and a missing
+transitive import would crash the wrapper. A dep-graph guard test in
+``tests/unit/`` enforces this.
+
+The package ``__init__`` deliberately re-exports NOTHING so that
+``import kohakuterrarium.launcher.<submodule>`` from any submodule's
+top of file does not trigger a circular import chain through
+``bootloader`` → ``update_runner`` → ``settings`` → … back to
+``launcher.__init__``. Callers (``__main__``, ``__briefcase__``)
+import :func:`bootloader.main` directly.
+
+Wrapper-only dependencies (intentionally small):
+
+- stdlib: ``argparse``, ``json``, ``os``, ``pathlib``, ``subprocess``,
+  ``shutil``, ``hashlib``, ``urllib``, ``tarfile``, ``http.server``,
+  ``threading``, ``logging``
+- third-party: ``packaging`` (any), ``pywebview`` (splash UI — optional;
+  Tk fallback if missing), ``zstandard`` (optional; ``.tar.gz`` fallback
+  if missing)
+
+Notably **not** required: ``pip``, ``venv``, ``ensurepip``, ``git``,
+``installer``. The launcher never installs Python packages on the
+user's machine — it downloads pre-built site-packages trees.
+"""