ttsd-colabcli 1.0.0

package/core/app/colab_cli/auto_update.py

@@ -0,0 +1,248 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Auto-update subsystem.
+
+Owns version detection, the PyPI-style update probe, the on-disk
+``latest_version`` cache, and the upgrade-banner UX. The CLI's global
+callback (``cli.py``) calls ``check_for_updates`` once per day and
+``maybe_show_cached_banner`` on every other invocation; the
+``colab update`` Typer command (``commands/utility.py``) delegates to
+``check_for_updates``.
+"""
+
+import json
+import platform
+import subprocess
+import urllib.request
+from datetime import datetime, timezone
+from importlib.metadata import PackageNotFoundError, version as installed_version
+from packaging.version import InvalidVersion, Version
+from typing import Optional
+
+import typer
+
+from app.colab_cli.common import state
+from app.colab_cli.state import Settings
+
+# PyPI distribution name (different from the importable package name `colab`).
+PYPI_PACKAGE_NAME = "google-colab-cli"
+
+
+# ---------- Version detection -------------------------------------------
+
+
+def is_self_install_supported() -> bool:
+    """Return True if self-install (--install) is supported on the current platform."""
+    return platform.system() in ("Linux", "Darwin")
+
+
+def get_app_version() -> str:
+    """Return the installed package version, falling back to the git short hash."""
+    try:
+        return installed_version("google-colab-cli")
+    except (PackageNotFoundError, InvalidVersion):
+        pass
+
+    try:
+        return subprocess.check_output(
+            ["git", "rev-parse", "--short", "HEAD"],
+            stderr=subprocess.DEVNULL,
+            encoding="utf-8",
+        ).strip()
+    except Exception:
+        return "unknown"
+
+
+# ---------- Source fetchers ---------------------------------------------
+
+
+def _parse_version(payload: Optional[dict]) -> Optional[str]:
+    """Returns ``info.version`` from a PyPI-style payload, or None."""
+    return (payload or {}).get("info", {}).get("version")
+
+
+def _fetch_pypi(url: str, quiet: bool) -> Optional[dict]:
+    """Fetches and parses the PyPI-style JSON document at ``url``."""
+    try:
+        with urllib.request.urlopen(url, timeout=5) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except Exception as e:
+        if not quiet:
+            typer.echo(f"[colab] Warning: Failed to fetch update info: {e}")
+        return None
+
+
+# ---------- Version comparison ------------------------------------------
+
+
+def _is_newer(candidate: Optional[str], current: str) -> bool:
+    """True when ``candidate`` strictly exceeds ``current`` (PEP 440)."""
+    if not candidate:
+        return False
+    try:
+        return Version(candidate) > Version(current)
+    except InvalidVersion:
+        return candidate != current
+
+
+# ---------- UX ----------------------------------------------------------
+
+
+def announce_upgrade(
+    latest: str,
+    current: str,
+    install_cmd: str,
+    *,
+    show_disable_hint: bool = False,
+) -> None:
+    """Print the upgrade banner.
+
+    ``show_disable_hint`` controls whether the trailing line that explains
+    how to silence the auto-check is included. It is only added when the
+    banner is shown unsolicited (the daily background fetch and the cached
+    banner on subsequent invocations); explicit ``colab update`` calls
+    omit it because the user already opted in to seeing the result.
+    """
+    typer.echo(
+        f"\n[colab] A new version of Colab CLI is available: {latest} (current: {current})"
+    )
+    if is_self_install_supported() and ("pip" in install_cmd or "uv" in install_cmd):
+        typer.echo("[colab] You can run 'colab update --install' to upgrade in place.")
+    typer.echo(f"[colab] Run '{install_cmd}' to update.")
+    if show_disable_hint:
+        typer.echo(
+            "[colab] To silence this check, set "
+            '"enable_update_check": false in '
+            "~/.config/colab-cli/settings.json"
+        )
+    typer.echo("")
+
+
+# ---------- Orchestration -----------------------------------------------
+
+
+def _get_install_command() -> str:
+    """Return the recommended installation command based on the environment."""
+    import sys
+
+    if is_self_install_supported() and "/uv/tools/" in sys.executable:
+        return f"uv tool install -U {PYPI_PACKAGE_NAME}"
+    return f"pip install --upgrade {PYPI_PACKAGE_NAME}"
+
+
+def check_for_updates(quiet: bool = False) -> None:
+    """Check PyPI for updates and print a message if a new version is available.
+
+    The disable-hint is appended to the banner only when ``quiet`` is True
+    (the daily background fetch); explicit ``colab update`` invocations
+    (``quiet=False``) omit it because the user asked for the check.
+    """
+    settings = state.settings_store.load()
+    current = get_app_version()
+
+    try:
+        pypi = _fetch_pypi(settings.update_url, quiet)
+        pypi_v = _parse_version(pypi)
+
+        if _is_newer(pypi_v, current):
+            announce_upgrade(
+                pypi_v,
+                current,
+                _get_install_command(),
+                show_disable_hint=quiet,
+            )
+        elif not quiet:
+            suffix = f", latest: {pypi_v}" if pypi_v else ""
+            typer.echo(f"[colab] Colab CLI is up to date (version: {current}{suffix}).")
+
+        # Cache the highest observed version; never downgrade.
+        cached = settings.latest_version or "0"
+        if _is_newer(pypi_v, cached):
+            settings.latest_version = pypi_v
+
+        settings.last_check = datetime.now(timezone.utc)
+        state.settings_store.save(settings)
+
+    except Exception as e:
+        if not quiet:
+            typer.echo(f"[colab] Failed to check for updates: {e}")
+
+
+# ---------- Background hooks (called from cli.py) -----------------------
+
+
+def _is_throttled(settings: Settings, *, now: Optional[datetime] = None) -> bool:
+    """True if the once-per-day fetch should be skipped."""
+    if settings.last_check is None:
+        return False
+    now = now or datetime.now(timezone.utc)
+    return (now - settings.last_check).days < 1
+
+
+def maybe_show_cached_banner(settings: Settings) -> None:
+    """Print the cached upgrade banner if the cache reports a newer version.
+
+    Called from the global CLI callback when the daily fetch is throttled.
+    The banner uses a generic ``colab update`` install hint because the
+    cache does not record which source supplied the version; the disable
+    hint is shown because this is unsolicited output.
+    """
+    if not settings.latest_version:
+        return
+    current = get_app_version()
+    if not _is_newer(settings.latest_version, current):
+        return
+    announce_upgrade(
+        settings.latest_version,
+        current,
+        "colab update",
+        show_disable_hint=True,
+    )
+
+
+def run_background_check() -> None:
+    """Entry point for the global CLI callback.
+
+    Performs either the daily fetch (which writes the cache) or, if
+    throttled, surfaces the cached banner. Honors the
+    ``enable_update_check`` master switch.
+    """
+    settings = state.settings_store.load()
+    if not settings.enable_update_check:
+        return
+    if _is_throttled(settings):
+        maybe_show_cached_banner(settings)
+    else:
+        check_for_updates(quiet=True)
+
+
+# ---------- Self-install ------------------------------------------------
+
+
+def self_install() -> None:
+    """Upgrade the CLI in place, detecting uv vs pip."""
+    import sys
+
+    # If the executable path contains "/uv/", we assume it was installed via
+    # `uv tool install` and use `uv` to upgrade it.
+    if "/uv/tools/" in sys.executable:
+        cmd = ["uv", "tool", "install", "-U", PYPI_PACKAGE_NAME]
+    else:
+        cmd = [sys.executable, "-m", "pip", "install", "-U", PYPI_PACKAGE_NAME]
+
+    typer.echo(f"[colab] Running: {' '.join(cmd)}")
+    result = subprocess.run(cmd)
+    if result.returncode != 0:
+        raise typer.Exit(code=result.returncode)

package/core/app/colab_cli/cli.py

@@ -0,0 +1,155 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+from typing import Optional
+
+import click
+import typer
+from typer.core import TyperGroup
+from typing_extensions import Annotated
+
+from app.colab_cli import auto_update
+from app.colab_cli.auth import AuthProvider
+from app.colab_cli.common import state, setup_logging
+from app.colab_cli.commands import session, execution, files, automation, run, utility
+
+
+class AlphabeticalGroup(TyperGroup):
+    """A `TyperGroup` that lists subcommands alphabetically in `--help` output.
+
+    Subcommands are registered in functional groups (session, execution, files,
+    automation, utility), but users discovering the CLI via `colab --help` /
+    `colab help` benefit from a deterministic, alphabetical listing.
+    """
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        return sorted(super().list_commands(ctx))
+
+
+app = typer.Typer(
+    help="Colab CLI",
+    no_args_is_help=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+    cls=AlphabeticalGroup,
+)
+
+
+@app.callback()
+def callback(
+    ctx: typer.Context,
+    client_oauth_config: Annotated[
+        str,
+        typer.Option(
+            "-c", "--client-oauth-config", help="Path to client OAuth config JSON file"
+        ),
+    ] = os.path.expanduser("~/.colab-cli-oauth-config.json"),
+    config: Annotated[
+        Optional[str],
+        typer.Option(
+            "--config",
+            help="Path to session state file (~/.config/colab-cli/sessions.json)",
+        ),
+    ] = None,
+    logtostderr: Annotated[
+        bool, typer.Option("--logtostderr", help="Log all output to stderr")
+    ] = False,
+    auth: Annotated[
+        AuthProvider,
+        typer.Option(
+            "--auth",
+            help=(
+                "Authentication strategy to use: 'oauth2' (public InstalledAppFlow),"
+                " or 'adc' (Application Default Credentials)."
+            ),
+            case_sensitive=False,
+        ),
+    ] = AuthProvider.OAUTH2,
+):
+    """
+    Colab CLI global configuration.
+    """
+    state.client_oauth_config = client_oauth_config
+    state.config_path = config
+    state.logtostderr = logtostderr
+    state.auth_provider = auth
+    setup_logging(logtostderr)
+
+    # Daily fetch + cached banner on every invocation.
+    #
+    # Suppress the banner for short-lived informational subcommands so their
+    # output stays clean and machine-parseable:
+    #   - `update`: runs its own check + announce; would duplicate the banner.
+    #   - `version`, `log`, `pay`, `help`, `url`: pure-display commands whose
+    #     output users routinely pipe / scrape (e.g. `colab url -s s1 | xclip`);
+    #     a stochastic upgrade banner injected once a day would corrupt those
+    #     pipelines.
+    #   - `whoami`: developer-only debugging tool; banner would obscure the
+    #     auth/scope info the user invoked it to see.
+    _AUTO_UPDATE_SUPPRESSED = {
+        "update",
+        "version",
+        "log",
+        "pay",
+        "help",
+        "url",
+        "whoami",
+        "readme",
+        "README",
+        "skill",
+        "SKILL",
+    }
+    if ctx.invoked_subcommand not in _AUTO_UPDATE_SUPPRESSED:
+        auto_update.run_background_check()
+
+
+@app.command(name="help")
+def help_command(
+    ctx: typer.Context,
+    command: Annotated[
+        Optional[str], typer.Argument(help="Command to show help for")
+    ] = None,
+):
+    """
+    Show help for a command.
+    """
+    if not command:
+        typer.echo(ctx.parent.get_help())
+        return
+
+    group = ctx.parent.command
+    cmd = group.get_command(ctx, command)
+    if cmd is None:
+        typer.echo(f"No such command '{command}'.", err=True)
+        raise typer.Exit(code=2)
+
+    with click.Context(cmd, info_name=command, parent=ctx.parent) as cmd_ctx:
+        typer.echo(cmd.get_help(cmd_ctx))
+
+
+# Register subcommands
+session.register(app)
+execution.register(app)
+files.register(app)
+automation.register(app)
+run.register(app)
+utility.register(app)
+
+
+def main():
+    app()
+
+
+if __name__ == "__main__":
+    main()