ruyi 0.41.0b20250926__py3-none-any.whl → 0.42.0__py3-none-any.whl

ruyi/cli/config_cli.py

@@ -43,15 +43,23 @@ class ConfigGetCommand(
 
     @classmethod
     def main(cls, cfg: "config.GlobalConfig", args: argparse.Namespace) -> int:
+        from ..config.errors import InvalidConfigKeyError
         from ..config.schema import encode_value
+        from ..utils.toml import NoneValue
 
         key: str = args.key
 
-        val = cfg.get_by_key(key)
-        if val is None:
+        try:
+            val = cfg.get_by_key(key)
+        except InvalidConfigKeyError:
             return 1
 
-        cfg.logger.stdout(encode_value(val))
+        try:
+            encoded_val = encode_value(val)
+        except NoneValue:
+            return 1
+
+        cfg.logger.stdout(encoded_val)
         return 0
 
 
@@ -80,6 +88,7 @@ class ConfigSetCommand(
     @classmethod
     def main(cls, cfg: "config.GlobalConfig", args: argparse.Namespace) -> int:
         from ..config.editor import ConfigEditor
+        from ..config.errors import ProtectedGlobalConfigError
         from ..config.schema import decode_value
 
         key: str = args.key
@@ -87,7 +96,14 @@ class ConfigSetCommand(
 
         pyval = decode_value(key, val)
         with ConfigEditor.work_on_user_local_config(cfg) as ed:
-            ed.set_value(key, pyval)
+            try:
+                ed.set_value(key, pyval)
+            except ProtectedGlobalConfigError:
+                cfg.logger.F(
+                    f"the config [yellow]{key}[/] is protected and not meant to be overridden by users",
+                )
+                return 2
+
             ed.stage()
 
         return 0

ruyi/cli/main.py

@@ -6,6 +6,7 @@ from typing import Final, TYPE_CHECKING
 from ..config import GlobalConfig
 from ..telemetry.scope import TelemetryScope
 from ..utils.global_mode import GlobalModeProvider
+from ..version import RUYI_SEMVER
 from . import RUYI_ENTRYPOINT_NAME
 from .oobe import OOBE
 
@@ -21,18 +22,40 @@ def is_called_as_ruyi(argv0: str) -> bool:
     return os.path.basename(argv0).lower() in ALLOWED_RUYI_ENTRYPOINT_NAMES
 
 
+def should_prompt_for_renaming(argv0: str) -> bool:
+    # We need to allow things like "ruyi-qemu" through, to not break our mux.
+    # Only consider filenames starting with both our name *and* version to be
+    # un-renamed onefile artifacts that warrant a rename prompt.
+    likely_artifact_name_prefix = f"{RUYI_ENTRYPOINT_NAME}-{RUYI_SEMVER}."
+    return os.path.basename(argv0).lower().startswith(likely_artifact_name_prefix)
+
+
 def main(gm: GlobalModeProvider, gc: GlobalConfig, argv: list[str]) -> int:
-    oobe = OOBE(gc)
+    logger = gc.logger
 
-    if tm := gc.telemetry:
-        tm.check_first_run_status()
-        tm.init_installation(False)
-        atexit.register(tm.flush)
-        oobe.handlers.append(tm.oobe_prompt)
+    # do not init telemetry or OOBE on CLI auto-completion invocations, because
+    # our output isn't meant for humans in that case, and a "real" invocation
+    # will likely follow shortly after
+    if not gm.is_cli_autocomplete:
+        oobe = OOBE(gc)
 
-    oobe.maybe_prompt()
+        if tm := gc.telemetry:
+            tm.check_first_run_status()
+            tm.init_installation(False)
+            atexit.register(tm.flush)
+            oobe.handlers.append(tm.oobe_prompt)
+
+        oobe.maybe_prompt()
 
     if not is_called_as_ruyi(gm.argv0):
+        if should_prompt_for_renaming(gm.argv0):
+            logger.F(
+                f"the {RUYI_ENTRYPOINT_NAME} executable must be named [green]'{RUYI_ENTRYPOINT_NAME}'[/] to work"
+            )
+            logger.I(f"it is now [yellow]'{gm.argv0}'[/]")
+            logger.I("please rename the command file and retry")
+            return 1
+
         from ..mux.runtime import mux_main
 
         # record an invocation and the command name being proxied to
@@ -54,7 +77,6 @@ def main(gm: GlobalModeProvider, gc: GlobalConfig, argv: list[str]) -> int:
     if TYPE_CHECKING:
         from .cmd import CLIEntrypoint
 
-    logger = gc.logger
     p = RootCommand.build_argparse(gc)
 
     # We have to ensure argcomplete is only requested when it's supposed to,

ruyi/cli/oobe.py

@@ -41,10 +41,16 @@ class OOBE:
     def should_prompt(self) -> bool:
         from ..utils.global_mode import is_env_var_truthy
 
+        if not sys.stdin.isatty() or not sys.stdout.isatty():
+            # This is of higher priority than even the debug override, because
+            # we don't want to mess up non-interactive sessions even in case of
+            # debugging.
+            return False
+
         if is_env_var_truthy(os.environ, "RUYI_DEBUG_FORCE_FIRST_RUN"):
             return True
 
-        return self.is_first_run() and sys.stdin.isatty()
+        return self.is_first_run()
 
     def maybe_prompt(self) -> None:
         if not self.should_prompt():

ruyi/cli/self_cli.py

@@ -131,12 +131,16 @@ class SelfCleanCommand(
         _do_reset(
             cfg,
             quiet=quiet,
+            # state-related
+            all_state=all,
+            news_read_status=news_read_status,
+            telemetry=telemetry,
+            # cache-related
+            all_cache=all,
             distfiles=distfiles,
             installed_pkgs=installed_pkgs,
-            news_read_status=news_read_status,
             progcache=progcache,
             repo=repo,
-            telemetry=telemetry,
         )
 
         return 0
@@ -233,6 +237,7 @@ def _do_reset(
     if installed_pkgs:
         status("removing installed packages")
         shutil.rmtree(cfg.data_root, True)
+        cfg.ruyipkg_global_state.purge_installation_info()
 
     # do not record any telemetry data if we're purging it
     if all_state or telemetry:

ruyi/config/__init__.py

@@ -15,8 +15,10 @@ if TYPE_CHECKING:
     from ..ruyipkg.state import RuyipkgGlobalStateStore
     from ..telemetry.provider import TelemetryProvider
     from ..utils.global_mode import ProvidesGlobalMode
+    from ..utils.xdg_basedir import XDGPathEntry
     from .news import NewsReadStatusStore
 
+from . import errors
 from . import schema
 
 
@@ -33,6 +35,7 @@ else:
 DEFAULT_APP_NAME: Final = "ruyi"
 DEFAULT_REPO_URL: Final = "https://github.com/ruyisdk/packages-index.git"
 DEFAULT_REPO_BRANCH: Final = "main"
+DEFAULT_TELEMETRY_MODE: Final = "local"  # "off", "local", "on"
 
 
 def get_host_path_fragment_for_binary_install_dir(canonicalized_host: str) -> str:
@@ -101,12 +104,21 @@ class GlobalConfig:
         self._telemetry_upload_consent: datetime.datetime | None = None
         self._telemetry_pm_telemetry_url: str | None = None
 
-    def apply_config(self, config_data: GlobalConfigRootType) -> None:
+    def _apply_config(
+        self,
+        config_data: GlobalConfigRootType,
+        *,
+        is_global_scope: bool,
+    ) -> None:
         if ins_cfg := config_data.get(schema.SECTION_INSTALLATION):
-            self.is_installation_externally_managed = ins_cfg.get(
-                schema.KEY_INSTALLATION_EXTERNALLY_MANAGED,
-                False,
-            )
+            iem = ins_cfg.get(schema.KEY_INSTALLATION_EXTERNALLY_MANAGED, None)
+            if iem is not None and not is_global_scope:
+                iem_cfg_key = f"{schema.SECTION_INSTALLATION}.{schema.KEY_INSTALLATION_EXTERNALLY_MANAGED}"
+                self.logger.W(
+                    f"the config key [yellow]{iem_cfg_key}[/] cannot be set from user config; ignoring",
+                )
+            else:
+                self.is_installation_externally_managed = bool(iem)
 
         if pkgs_cfg := config_data.get(schema.SECTION_PACKAGES):
             self.include_prereleases = pkgs_cfg.get(
@@ -137,61 +149,84 @@ class GlobalConfig:
                 if isinstance(consent, datetime.datetime):
                     self._telemetry_upload_consent = consent
 
-    def get_by_key(self, key: str | Sequence[str]) -> object | None:
+    def get_by_key(self, key: str | Sequence[str]) -> object:
+        parsed_key = schema.parse_config_key(key)
+        section, sel = parsed_key[0], parsed_key[1:]
+        attr_name = self._get_attr_name_by_key(section, sel)
+        if attr_name is None:
+            raise errors.InvalidConfigKeyError(key)
+        return getattr(self, attr_name)
+
+    def set_by_key(self, key: str | Sequence[str], value: object) -> None:
+        # We don't have to check for global-only keys here because this
+        # method is only used for programmatic changes to the in-memory
+        # config, not for loading from config files.
         parsed_key = schema.parse_config_key(key)
         section, sel = parsed_key[0], parsed_key[1:]
+        attr_name = self._get_attr_name_by_key(section, sel)
+        if attr_name is None:
+            raise errors.InvalidConfigKeyError(key)
+        schema.ensure_valid_config_kv(key, True, value)
+        setattr(self, attr_name, value)
+
+    @classmethod
+    def _get_attr_name_by_key(cls, section: str, sel: list[str]) -> str | None:
         if section == schema.SECTION_INSTALLATION:
-            return self._get_section_installation(sel)
+            return cls._get_section_installation(sel)
         elif section == schema.SECTION_PACKAGES:
-            return self._get_section_packages(sel)
+            return cls._get_section_packages(sel)
         elif section == schema.SECTION_REPO:
-            return self._get_section_repo(sel)
+            return cls._get_section_repo(sel)
         elif section == schema.SECTION_TELEMETRY:
-            return self._get_section_telemetry(sel)
+            return cls._get_section_telemetry(sel)
         else:
             return None
 
-    def _get_section_installation(self, selector: list[str]) -> object | None:
+    @classmethod
+    def _get_section_installation(cls, selector: list[str]) -> str | None:
         if len(selector) != 1:
             return None
         leaf = selector[0]
         if leaf == schema.KEY_INSTALLATION_EXTERNALLY_MANAGED:
-            return self.is_installation_externally_managed
+            return "is_installation_externally_managed"
         else:
             return None
 
-    def _get_section_packages(self, selector: list[str]) -> object | None:
+    @classmethod
+    def _get_section_packages(cls, selector: list[str]) -> str | None:
         if len(selector) != 1:
             return None
         leaf = selector[0]
         if leaf == schema.KEY_PACKAGES_PRERELEASES:
-            return self.include_prereleases
+            return "include_prereleases"
         else:
             return None
 
-    def _get_section_repo(self, selector: list[str]) -> object | None:
+    @classmethod
+    def _get_section_repo(cls, selector: list[str]) -> str | None:
         if len(selector) != 1:
             return None
         leaf = selector[0]
         if leaf == schema.KEY_REPO_BRANCH:
-            return self.override_repo_branch
+            return "override_repo_branch"
         elif leaf == schema.KEY_REPO_LOCAL:
-            return self.override_repo_dir
+            return "override_repo_dir"
         elif leaf == schema.KEY_REPO_REMOTE:
-            return self.override_repo_url
+            return "override_repo_url"
         else:
             return None
 
-    def _get_section_telemetry(self, selector: list[str]) -> object | None:
+    @classmethod
+    def _get_section_telemetry(cls, selector: list[str]) -> str | None:
         if len(selector) != 1:
             return None
         leaf = selector[0]
         if leaf == schema.KEY_TELEMETRY_MODE:
-            return self.telemetry_mode
+            return "telemetry_mode"
         elif leaf == schema.KEY_TELEMETRY_PM_TELEMETRY_URL:
-            return self.override_pm_telemetry_url
+            return "override_pm_telemetry_url"
         elif leaf == schema.KEY_TELEMETRY_UPLOAD_CONSENT:
-            return self.telemetry_upload_consent_time
+            return "telemetry_upload_consent_time"
         else:
             return None
 
@@ -262,26 +297,63 @@ class GlobalConfig:
     def telemetry_root(self) -> os.PathLike[Any]:
         return pathlib.Path(self.ensure_state_dir()) / "telemetry"
 
-    @cached_property
+    @property
     def telemetry(self) -> "TelemetryProvider | None":
+        return None if self.telemetry_mode == "off" else self._telemetry_provider
+
+    @cached_property
+    def _telemetry_provider(self) -> "TelemetryProvider | None":
+        """Do not access directly; use the ``telemetry`` property instead."""
+
         from ..telemetry.provider import TelemetryProvider
 
         return None if self.telemetry_mode == "off" else TelemetryProvider(self)
 
     @property
     def telemetry_mode(self) -> str:
-        return self._telemetry_mode or "on"
+        return self._telemetry_mode or DEFAULT_TELEMETRY_MODE
+
+    @telemetry_mode.setter
+    def telemetry_mode(self, mode: str) -> None:
+        if mode not in ("off", "local", "on"):
+            raise ValueError("telemetry mode must be one of: off, local, on")
+        if self._gm.is_telemetry_optout and mode != "off":
+            raise ValueError(
+                "cannot enable telemetry when the environment variable opt-out is set"
+            )
+        self._telemetry_mode = mode
 
     @property
     def telemetry_upload_consent_time(self) -> datetime.datetime | None:
         return self._telemetry_upload_consent
 
+    @telemetry_upload_consent_time.setter
+    def telemetry_upload_consent_time(self, t: datetime.datetime | None) -> None:
+        self._telemetry_upload_consent = t
+
     @property
     def override_pm_telemetry_url(self) -> str | None:
         return self._telemetry_pm_telemetry_url
 
+    @override_pm_telemetry_url.setter
+    def override_pm_telemetry_url(self, url: str | None) -> None:
+        self._telemetry_pm_telemetry_url = url
+
+    @cached_property
+    def default_repo_dir(self) -> str:
+        return os.path.join(self.cache_root, "packages-index")
+
     def get_repo_dir(self) -> str:
-        return self.override_repo_dir or os.path.join(self.cache_root, "packages-index")
+        return self.override_repo_dir or self.default_repo_dir
+
+    @cached_property
+    def have_overridden_repo_dir(self) -> bool:
+        if not self.override_repo_dir:
+            return False
+        override_path = pathlib.Path(self.override_repo_dir)
+        default_path = pathlib.Path(self.default_repo_dir)
+        # we don't use samefile() here because the path may not exist
+        return override_path.resolve() != default_path.resolve()
 
     def get_repo_url(self) -> str:
         return self.override_repo_url or DEFAULT_REPO_URL
@@ -312,7 +384,7 @@ class GlobalConfig:
     def lookup_binary_install_dir(self, host: str, slug: str) -> PathLike[Any] | None:
         host_path = get_host_path_fragment_for_binary_install_dir(host)
         for data_dir in self._dirs.app_data_dirs:
-            p = data_dir / "binaries" / host_path / slug
+            p = data_dir.path / "binaries" / host_path / slug
             if p.exists():
                 return p
         return None
@@ -347,30 +419,40 @@ class GlobalConfig:
         p.mkdir(parents=True, exist_ok=True)
         return p
 
-    def iter_preset_configs(self) -> Iterable[os.PathLike[Any]]:
+    def iter_preset_configs(self) -> "Iterable[XDGPathEntry]":
         """
         Yields possible Ruyi config files in all preset config path locations,
         sorted by precedence from lowest to highest (so that each file may be
         simply applied consecutively).
         """
 
+        from ..utils.xdg_basedir import XDGPathEntry
+
         for path in PRESET_GLOBAL_CONFIG_LOCATIONS:
-            yield pathlib.Path(path)
+            yield XDGPathEntry(pathlib.Path(path), True)
 
-    def iter_xdg_configs(self) -> Iterable[os.PathLike[Any]]:
+    def iter_xdg_configs(self) -> "Iterable[XDGPathEntry]":
         """
         Yields possible Ruyi config files in all XDG config paths, sorted by precedence
         from lowest to highest (so that each file may be simply applied consecutively).
         """
 
-        for config_dir in reversed(list(self._dirs.app_config_dirs)):
-            yield config_dir / "config.toml"
+        from ..utils.xdg_basedir import XDGPathEntry
+
+        entries = list(self._dirs.app_config_dirs)
+        for e in reversed(entries):
+            yield XDGPathEntry(e.path / "config.toml", e.is_global)
 
     @property
     def local_user_config_file(self) -> pathlib.Path:
         return self._dirs.app_config / "config.toml"
 
-    def try_apply_config_file(self, path: os.PathLike[Any]) -> None:
+    def _try_apply_config_file(
+        self,
+        path: os.PathLike[Any],
+        *,
+        is_global_scope: bool,
+    ) -> None:
         import tomlkit
 
         try:
@@ -379,23 +461,24 @@ class GlobalConfig:
         except FileNotFoundError:
             return
 
-        self.logger.D(f"applying config: {data}")
-        self.apply_config(data)
+        self.logger.D(f"applying config: {data}, is_global_scope={is_global_scope}")
+        self._apply_config(data, is_global_scope=is_global_scope)
 
     @classmethod
     def load_from_config(cls, gm: "ProvidesGlobalMode", logger: "RuyiLogger") -> "Self":
         obj = cls(gm, logger)
 
-        for config_path in obj.iter_preset_configs():
+        for config_path, is_global in obj.iter_preset_configs():
             obj.logger.D(f"trying config file from preset location: {config_path}")
-            obj.try_apply_config_file(config_path)
+            obj._try_apply_config_file(config_path, is_global_scope=is_global)
 
-        for config_path in obj.iter_xdg_configs():
+        for config_path, is_global in obj.iter_xdg_configs():
             obj.logger.D(f"trying config file from XDG path: {config_path}")
-            obj.try_apply_config_file(config_path)
+            obj._try_apply_config_file(config_path, is_global_scope=is_global)
 
         # let environment variable take precedence
         if gm.is_telemetry_optout:
             obj._telemetry_mode = "off"
+            obj._telemetry_upload_consent = None
 
         return obj

ruyi/config/editor.py

@@ -1,6 +1,6 @@
 from contextlib import AbstractContextManager
 import pathlib
-from typing import Sequence, TYPE_CHECKING, cast
+from typing import Final, Sequence, TYPE_CHECKING, cast
 
 if TYPE_CHECKING:
     from types import TracebackType
@@ -9,13 +9,35 @@ if TYPE_CHECKING:
 import tomlkit
 from tomlkit.items import Table
 
-from .errors import MalformedConfigFileError
-from .schema import ensure_valid_config_kv, parse_config_key, validate_section
+from .errors import MalformedConfigFileError, ProtectedGlobalConfigError
+from .schema import (
+    SECTION_INSTALLATION,
+    KEY_INSTALLATION_EXTERNALLY_MANAGED,
+    ensure_valid_config_kv,
+    parse_config_key,
+    validate_section,
+)
 
 if TYPE_CHECKING:
     from . import GlobalConfig
 
 
+GLOBAL_ONLY_CONFIG_KEYS: Final[set[tuple[str, str]]] = {
+    (SECTION_INSTALLATION, KEY_INSTALLATION_EXTERNALLY_MANAGED),
+}
+"""Settings that can only be set in global-scope config files.
+
+Changes should be reflected in ``GlobalConfig._apply_config`` too."""
+
+
+def _is_config_key_global_only(key: str | Sequence[str]) -> bool:
+    parsed_key = parse_config_key(key)
+    if len(parsed_key) != 2:
+        return False
+    section, leaf = parsed_key
+    return (section, leaf) in GLOBAL_ONLY_CONFIG_KEYS
+
+
 class ConfigEditor(AbstractContextManager["ConfigEditor"]):
     def __init__(self, path: pathlib.Path) -> None:
         self._path = path
@@ -63,6 +85,15 @@ class ConfigEditor(AbstractContextManager["ConfigEditor"]):
         parsed_key = parse_config_key(key)
         ensure_valid_config_kv(parsed_key, check_val=True, val=val)
 
+        # Gate protected settings: user-local config is not allowed to override
+        # global-only settings.
+        if _is_config_key_global_only(parsed_key):
+            # This mechanism is only meant for modifying user-local configs,
+            # because global configs are assumed to be maintained by packagers
+            # and/or sysadmins, who are expected to write the config file by
+            # hand.
+            raise ProtectedGlobalConfigError(parsed_key)
+
         section, sel = parsed_key[0], parsed_key[1:]
         if section in self._stage:
             existing_section = self._stage[section]

ruyi/config/errors.py

@@ -31,7 +31,7 @@ class InvalidConfigValueTypeError(TypeError):
         self,
         key: str | Sequence[str],
         val: object | None,
-        expected: type,
+        expected: type | Sequence[type],
     ) -> None:
         super().__init__()
         self._key = key
@@ -48,20 +48,24 @@ class InvalidConfigValueTypeError(TypeError):
 class InvalidConfigValueError(ValueError):
     def __init__(
         self,
-        key: str | Sequence[str] | type,
+        key: str | Sequence[str] | None,
         val: object | None,
+        typ: type | Sequence[type],
     ) -> None:
         super().__init__()
         self._key = key
         self._val = val
+        self._typ = typ
 
     def __str__(self) -> str:
-        if isinstance(self._key, type):
-            return f"invalid config value for type {self._key}: {self._val}"
-        return f"invalid config value for key {self._key}: {self._val}"
+        return (
+            f"invalid config value for key {self._key} (type {self._typ}): {self._val}"
+        )
 
     def __repr__(self) -> str:
-        return f"InvalidConfigValueError({self._key:!r}, {self._val:!r})"
+        return (
+            f"InvalidConfigValueError({self._key:!r}, {self._val:!r}, {self._typ:!r})"
+        )
 
 
 class MalformedConfigFileError(Exception):
@@ -74,3 +78,15 @@ class MalformedConfigFileError(Exception):
 
     def __repr__(self) -> str:
         return f"MalformedConfigFileError({self._path:!r})"
+
+
+class ProtectedGlobalConfigError(Exception):
+    def __init__(self, key: str | Sequence[str]) -> None:
+        super().__init__()
+        self._key = key
+
+    def __str__(self) -> str:
+        return f"attempt to modify protected global config key: {self._key}"
+
+    def __repr__(self) -> str:
+        return f"ProtectedGlobalConfigError({self._key!r})"