ruyi 0.41.0b20250924__tar.gz → 0.42.0__tar.gz

{ruyi-0.41.0b20250924 → ruyi-0.42.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ruyi
-Version: 0.41.0b20250924
+Version: 0.42.0
 Summary: Package manager for RuyiSDK
 License: Apache License
                                     Version 2.0, January 2004
@@ -221,7 +221,7 @@ Classifier: Topic :: Software Development :: Build Tools
 Classifier: Topic :: Software Development :: Embedded Systems
 Classifier: Topic :: System :: Software Distribution
 Classifier: Typing :: Typed
-Requires-Dist: argcomplete (>=2.0.0,<4.0.0)
+Requires-Dist: argcomplete (>=2.0.0)
 Requires-Dist: arpy
 Requires-Dist: fastjsonschema (>=2.15.1)
 Requires-Dist: jinja2 (>=3,<4)
@@ -332,6 +332,10 @@ Various aspects of `ruyi` can be configured with files or environment variables.
 look up its config accordingly. If these are not explicitly set though, as in
 typical use cases, the default config directory is most likely `~/.config/ruyi`.
 
+GNU/Linux distribution packagers and system administrators will find that the
+directories `/usr/share/ruyi` and `/usr/local/share/ruyi` are searched for the
+config file on such systems.
+
 ### Config file
 
 Currently `ruyi` will look for an optional `config.toml` in its XDG config
@@ -361,9 +365,8 @@ branch = "main"
 # details.
 #
 # If unset or empty, this default value is used: data will be collected and
-# uploaded every week, on a random weekday determined by the installation's
-# anonymous ID alone.
-mode = "on"
+# stored locally; nothing will be uploaded automatically.
+mode = "local"
 # The time the user's consent is given to telemetry data uploading. If the
 # system time is later than the time given here, telemetry consent banner will
 # not be displayed any more each time `ruyi` is executed. The exact consent
@@ -407,12 +410,16 @@ There are 3 telemetry modes available:
 * `off`: data will not be collected nor uploaded.
 * `on`: data will be collected and periodically uploaded.
 
-By default the `on` mode is active, which means every `ruyi` invocation
-will record some non-sensitive information locally alongside various other
-states of `ruyi`, and collected data will be periodically uploaded to servers
-managed by the RuyiSDK team in the People's Republic of China, in a weekly fashion.
-The upload will happen on a random weekday which is determined by the
-installation's anonymous ID alone.
+By default the `local` mode is active from `ruyi` 0.42.0 (inclusive) on, which
+means every `ruyi` invocation will record some non-sensitive information locally
+alongside various other states of `ruyi`, but collected data will not be
+uploaded automatically unless you explicitly request so (for example by
+switching to the `on` mode, or by executing `ruyi telemetry upload`).
+
+In case the `on` mode is active, collected data will be periodically uploaded
+to servers managed by the RuyiSDK team in the People's Republic of China, in a
+weekly fashion. The upload will happen on a random weekday which is determined
+by the installation's anonymous ID alone.
 
 You can change the telemetry mode by editing `ruyi`'s config file, or simply
 disable telemetry altogether by setting the `RUYI_TELEMETRY_OPTOUT` environment

{ruyi-0.41.0b20250924 → ruyi-0.42.0}/README.md

@@ -88,6 +88,10 @@ Various aspects of `ruyi` can be configured with files or environment variables.
 look up its config accordingly. If these are not explicitly set though, as in
 typical use cases, the default config directory is most likely `~/.config/ruyi`.
 
+GNU/Linux distribution packagers and system administrators will find that the
+directories `/usr/share/ruyi` and `/usr/local/share/ruyi` are searched for the
+config file on such systems.
+
 ### Config file
 
 Currently `ruyi` will look for an optional `config.toml` in its XDG config
@@ -117,9 +121,8 @@ branch = "main"
 # details.
 #
 # If unset or empty, this default value is used: data will be collected and
-# uploaded every week, on a random weekday determined by the installation's
-# anonymous ID alone.
-mode = "on"
+# stored locally; nothing will be uploaded automatically.
+mode = "local"
 # The time the user's consent is given to telemetry data uploading. If the
 # system time is later than the time given here, telemetry consent banner will
 # not be displayed any more each time `ruyi` is executed. The exact consent
@@ -163,12 +166,16 @@ There are 3 telemetry modes available:
 * `off`: data will not be collected nor uploaded.
 * `on`: data will be collected and periodically uploaded.
 
-By default the `on` mode is active, which means every `ruyi` invocation
-will record some non-sensitive information locally alongside various other
-states of `ruyi`, and collected data will be periodically uploaded to servers
-managed by the RuyiSDK team in the People's Republic of China, in a weekly fashion.
-The upload will happen on a random weekday which is determined by the
-installation's anonymous ID alone.
+By default the `local` mode is active from `ruyi` 0.42.0 (inclusive) on, which
+means every `ruyi` invocation will record some non-sensitive information locally
+alongside various other states of `ruyi`, but collected data will not be
+uploaded automatically unless you explicitly request so (for example by
+switching to the `on` mode, or by executing `ruyi telemetry upload`).
+
+In case the `on` mode is active, collected data will be periodically uploaded
+to servers managed by the RuyiSDK team in the People's Republic of China, in a
+weekly fashion. The upload will happen on a random weekday which is determined
+by the installation's anonymous ID alone.
 
 You can change the telemetry mode by editing `ruyi`'s config file, or simply
 disable telemetry altogether by setting the `RUYI_TELEMETRY_OPTOUT` environment

{ruyi-0.41.0b20250924 → ruyi-0.42.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "ruyi"
-version = "0.41.0-beta.20250924"
+version = "0.42.0"
 description = "Package manager for RuyiSDK"
 keywords = ["ruyi", "ruyisdk"]
 license = { file = "LICENSE-Apache.txt" }
@@ -29,6 +29,7 @@ classifiers = [
 ]
 requires-python = ">=3.10"
 dependencies = [
+  "argcomplete>=2.0.0",
   "arpy",
   "fastjsonschema>=2.15.1",
   "jinja2 (>=3, <4)",
@@ -41,7 +42,6 @@ dependencies = [
   "tomlkit>=0.9",
   "tomli>=1.2; python_version<'3.11'",
   "tzdata; sys_platform=='win32'",
-  "argcomplete (>=2.0.0,<4.0.0)",
 ]
 
 [project.scripts]
@@ -57,6 +57,7 @@ repository = "https://github.com/ruyisdk/ruyi.git"
 
 [tool.poetry]
 include = ["ruyi/py.typed"]
+exclude = ["**/.gitignore"]
 
 [tool.poetry.group.dev.dependencies]
 mypy = "^1.9.0"

{ruyi-0.41.0b20250924 → ruyi-0.42.0}/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-0.41.0b20250924 → ruyi-0.42.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-0.41.0b20250924 → ruyi-0.42.0}/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-0.41.0b20250924 → ruyi-0.42.0}/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-0.41.0b20250924 → ruyi-0.42.0}/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-0.41.0b20250924 → ruyi-0.42.0}/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]