ruyi 0.44.0a20251118__tar.gz → 0.44.0b20251219__tar.gz

{ruyi-0.44.0a20251118 → ruyi-0.44.0b20251219}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ruyi
-Version: 0.44.0a20251118
+Version: 0.44.0b20251219
 Summary: Package manager for RuyiSDK
 License: Apache License
                                     Version 2.0, January 2004
@@ -408,7 +408,8 @@ described below.
 There are 3 telemetry modes available:
 
 * `local`: data will be collected but not uploaded without user action.
-* `off`: data will not be collected nor uploaded.
+* `off`: data will neither be collected nor uploaded, except for a one-time
+  upload of `ruyi`'s version number on first run.
 * `on`: data will be collected and periodically uploaded.
 
 By default the `local` mode is active from `ruyi` 0.42.0 (inclusive) on, which

{ruyi-0.44.0a20251118 → ruyi-0.44.0b20251219}/README.md

@@ -163,7 +163,8 @@ described below.
 There are 3 telemetry modes available:
 
 * `local`: data will be collected but not uploaded without user action.
-* `off`: data will not be collected nor uploaded.
+* `off`: data will neither be collected nor uploaded, except for a one-time
+  upload of `ruyi`'s version number on first run.
 * `on`: data will be collected and periodically uploaded.
 
 By default the `local` mode is active from `ruyi` 0.42.0 (inclusive) on, which

{ruyi-0.44.0a20251118 → ruyi-0.44.0b20251219}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "ruyi"
-version = "0.44.0-alpha.20251118"
+version = "0.44.0-beta.20251219"
 description = "Package manager for RuyiSDK"
 keywords = ["ruyi", "ruyisdk"]
 license = { file = "LICENSE-Apache.txt" }

{ruyi-0.44.0a20251118 → ruyi-0.44.0b20251219}/ruyi/cli/main.py

@@ -39,11 +39,11 @@ def main(gm: GlobalModeProvider, gc: GlobalConfig, argv: list[str]) -> int:
     if not gm.is_cli_autocomplete:
         oobe = OOBE(gc)
 
-        if tm := gc.telemetry:
-            tm.check_first_run_status()
-            tm.init_installation(False)
-            atexit.register(tm.flush)
-            oobe.handlers.append(tm.oobe_prompt)
+        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()
 
@@ -59,12 +59,11 @@ def main(gm: GlobalModeProvider, gc: GlobalConfig, argv: list[str]) -> int:
         from ..mux.runtime import mux_main
 
         # record an invocation and the command name being proxied to
-        if tm := gc.telemetry:
-            tm.record(
-                TelemetryScope(None),
-                "cli:mux-invocation-v1",
-                target=os.path.basename(gm.argv0),
-            )
+        gc.telemetry.record(
+            TelemetryScope(None),
+            "cli:mux-invocation-v1",
+            target=os.path.basename(gm.argv0),
+        )
 
         return mux_main(gm, gc, argv)
 
@@ -127,8 +126,16 @@ def main(gm: GlobalModeProvider, gc: GlobalConfig, argv: list[str]) -> int:
     except AttributeError:
         pass
 
-    if tm := gc.telemetry:
-        tm.print_telemetry_notice()
+    tm = gc.telemetry
+    tm.print_telemetry_notice()
+
+    # Do not record `ruyi telemetry --cron-upload` invocations.
+    skip_recording_invocation = telemetry_key == "telemetry" and getattr(
+        args,
+        "cron_upload",
+        False,
+    )
+    if not skip_recording_invocation:
         tm.record(
             TelemetryScope(None),
             "cli:invocation-v1",

{ruyi-0.44.0a20251118 → ruyi-0.44.0b20251219}/ruyi/cli/oobe.py

@@ -30,13 +30,9 @@ class OOBE:
         ]
 
     def is_first_run(self) -> bool:
-        if tm := self._gc.telemetry:
-            return tm.is_first_run
-        # cannot reliably determine first run status without telemetry
-        # we may revisit this later if it turns out users want OOBE tips even
-        # if they know how to disable telemetry (hence more likely to be power
-        # users)
-        return False
+        # We now always have our first-run indicator because of the minimal
+        # telemetry mode.
+        return self._gc.telemetry.is_first_run
 
     def should_prompt(self) -> bool:
         from ..utils.global_mode import is_env_var_truthy

{ruyi-0.44.0a20251118 → ruyi-0.44.0b20251219}/ruyi/cli/self_cli.py

@@ -241,8 +241,7 @@ def _do_reset(
 
     # do not record any telemetry data if we're purging it
     if all_state or telemetry:
-        if tm := cfg.telemetry:
-            tm.discard_events(True)
+        cfg.telemetry.discard_events(True)
 
     if all_state:
         status("removing state data")

{ruyi-0.44.0a20251118 → ruyi-0.44.0b20251219}/ruyi/config/__init__.py

@@ -297,17 +297,13 @@ class GlobalConfig:
     def telemetry_root(self) -> os.PathLike[Any]:
         return pathlib.Path(self.ensure_state_dir()) / "telemetry"
 
-    @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."""
-
+    def telemetry(self) -> "TelemetryProvider":
         from ..telemetry.provider import TelemetryProvider
 
-        return None if self.telemetry_mode == "off" else TelemetryProvider(self)
+        # for allowing minimal uploads when telemetry is off
+        minimal_mode = self.telemetry_mode == "off"
+        return TelemetryProvider(self, minimal_mode)
 
     @property
     def telemetry_mode(self) -> str:

{ruyi-0.44.0a20251118 → ruyi-0.44.0b20251219}/ruyi/ruyipkg/install.py

@@ -168,17 +168,16 @@ def do_install_atoms(
             for s in sv.render_known_issues(pm.repo.messages, config.lang_code):
                 logger.I(s)
 
-        if tm := config.telemetry:
-            tm.record(
-                TelemetryScope(mr.repo_id),
-                "repo:package-install-v1",
-                atom=a_str,
-                host=canonicalized_host,
-                pkg_category=pm.category,
-                pkg_kinds=pm.kind,
-                pkg_name=pm.name,
-                pkg_version=pm.ver,
-            )
+        config.telemetry.record(
+            TelemetryScope(mr.repo_id),
+            "repo:package-install-v1",
+            atom=a_str,
+            host=canonicalized_host,
+            pkg_category=pm.category,
+            pkg_kinds=pm.kind,
+            pkg_name=pm.name,
+            pkg_version=pm.ver,
+        )
 
         if pm.binary_metadata is not None:
             ret = _do_install_binary_pkg(
@@ -478,17 +477,16 @@ def do_uninstall_atoms(
     for a_str, pm in pms_to_uninstall:
         pkg_name = pm.name_for_installation
 
-        if tm := config.telemetry:
-            tm.record(
-                TelemetryScope(mr.repo_id),
-                "repo:package-uninstall-v1",
-                atom=a_str,
-                host=canonicalized_host,
-                pkg_category=pm.category,
-                pkg_kinds=pm.kind,
-                pkg_name=pm.name,
-                pkg_version=pm.ver,
-            )
+        config.telemetry.record(
+            TelemetryScope(mr.repo_id),
+            "repo:package-uninstall-v1",
+            atom=a_str,
+            host=canonicalized_host,
+            pkg_category=pm.category,
+            pkg_kinds=pm.kind,
+            pkg_name=pm.name,
+            pkg_version=pm.ver,
+        )
 
         if pm.binary_metadata is not None:
             ret = _do_uninstall_binary_pkg(

{ruyi-0.44.0a20251118 → ruyi-0.44.0b20251219}/ruyi/telemetry/aggregate.py

@@ -18,8 +18,13 @@ class UploadPayload(TypedDict):
     fmt: int
     nonce: str
     ruyi_version: str
+    report_uuid: "NotRequired[str]"
+    """Optional field in case the client wishes to report this, and nothing
+    else. If `installation` is present, this field is ignored."""
     installation: "NotRequired[NodeInfo | None]"
+    """More detailed installation info that the client has user consent to report."""
     events: list[AggregatedTelemetryEvent]
+    """Aggregated telemetry events that the client has user consent to upload."""
 
 
 def stringify_param_val(v: object) -> str:

{ruyi-0.44.0a20251118 → ruyi-0.44.0b20251219}/ruyi/telemetry/provider.py

@@ -19,22 +19,27 @@ if TYPE_CHECKING:
 FALLBACK_PM_TELEMETRY_ENDPOINT = "https://api.ruyisdk.cn/telemetry/pm/"
 
 TELEMETRY_CONSENT_AND_UPLOAD_DESC = """
-RuyiSDK collects anonymized usage data locally to help us improve the product.
+RuyiSDK collects minimal usage data in the form of just a version number of
+the running [yellow]ruyi[/], to help us improve the product. With your consent,
+RuyiSDK may also collect additional non-tracking usage data to be sent
+periodically. The data will be recorded and processed by RuyiSDK team-managed
+servers located in the Chinese mainland.
 
 [green]By default, nothing leaves your machine[/], and you can also turn off usage data
-collection completely. Only with your explicit permission can [yellow]ruyi[/] upload
-collected telemetry, periodically to RuyiSDK team-managed servers located in
-the Chinese mainland. You can change this setting at any time by running
+collection completely. Only with your explicit permission can [yellow]ruyi[/] collect and
+upload more usage data. You can change this setting at any time by running
 [yellow]ruyi telemetry consent[/], [yellow]ruyi telemetry local[/], or [yellow]ruyi telemetry optout[/].
 
-If you enable uploads now, we'll also send a one-time report from this [yellow]ruyi[/]
-installation so the RuyiSDK team can better understand adoption. Thank you for
-helping us build a better experience!
+We'll also send a one-time report from this [yellow]ruyi[/] installation so the RuyiSDK
+team can better understand adoption. If you choose to opt out, this will be the
+only data to be ever uploaded, without any tracking ID being generated or kept.
+Thank you for helping us build a better experience!
 """
 TELEMETRY_CONSENT_AND_UPLOAD_PROMPT = (
-    "Enable telemetry uploads and send a one-time report now?"
+    "Do you agree to have usage data periodically uploaded?"
 )
-TELEMETRY_OPTOUT_PROMPT = "\nDo you want to disable telemetry entirely?"
+TELEMETRY_OPTOUT_PROMPT = "\nDo you want to opt out of telemetry entirely?"
+MALFORMED_TELEMETRY_STATE_MSG = "malformed telemetry state: unable to determine upload weekday, nothing will be uploaded"
 
 
 def next_utc_weekday(wday: int, now: float | None = None) -> int:
@@ -130,7 +135,7 @@ def set_telemetry_mode(
 
 
 class TelemetryProvider:
-    def __init__(self, gc: "GlobalConfig") -> None:
+    def __init__(self, gc: "GlobalConfig", minimal: bool) -> None:
         self.state_root = pathlib.Path(gc.telemetry_root)
 
         self._discard_events = False
@@ -138,6 +143,7 @@ class TelemetryProvider:
         self._is_first_run = False
         self._stores: dict[TelemetryScope, TelemetryStore] = {}
         self._upload_on_exit = False
+        self.minimal = minimal
 
         # create the PM store
         self.init_store(TelemetryScope(None))
@@ -154,6 +160,8 @@ class TelemetryProvider:
 
     @property
     def upload_consent_time(self) -> datetime.datetime | None:
+        if self.minimal or self.local_mode:
+            return None
         return self._gc.telemetry_upload_consent_time
 
     def store(self, scope: TelemetryScope) -> TelemetryStore | None:
@@ -203,11 +211,18 @@ class TelemetryProvider:
     def installation_file(self) -> pathlib.Path:
         return self.state_root / "installation.json"
 
+    @property
+    def minimal_installation_marker_file(self) -> pathlib.Path:
+        return self.state_root / "minimal-installation-marker"
+
     def check_first_run_status(self) -> None:
         """Check if this is the first run of the application by checking if installation file exists.
         This must be done before init_installation() is potentially called.
         """
-        self._is_first_run = not self.installation_file.exists()
+        self._is_first_run = (
+            not self.installation_file.exists()
+            and not self.minimal_installation_marker_file.exists()
+        )
 
     @property
     def is_first_run(self) -> bool:
@@ -215,9 +230,15 @@ class TelemetryProvider:
         return self._is_first_run
 
     def init_installation(self, force_reinit: bool) -> NodeInfo | None:
+        if self.minimal:
+            # be extra safe by not reading or writing installation data at all
+            # in minimal mode
+            self._init_minimal_installation_marker(force_reinit)
+            return None
+
         installation_file = self.installation_file
         if installation_file.exists() and not force_reinit:
-            return self.read_installation_data()
+            return self._read_installation_data()
 
         # either this is a fresh installation or we're forcing a refresh
         installation_id = uuid.uuid4()
@@ -232,13 +253,26 @@ class TelemetryProvider:
             fp.write(json.dumps(installation_data).encode("utf-8"))
         return installation_data
 
-    def read_installation_data(self) -> NodeInfo | None:
+    def _init_minimal_installation_marker(self, force_reinit: bool) -> None:
+        if self.minimal_installation_marker_file.exists() and not force_reinit:
+            return
+
+        self.logger.D("initializing minimal installation marker file")
+        self.state_root.mkdir(parents=True, exist_ok=True)
+
+        # just touch the file
+        self.minimal_installation_marker_file.touch()
+
+    def _read_installation_data(self) -> NodeInfo | None:
         with open(self.installation_file, "rb") as fp:
             return cast(NodeInfo, json.load(fp))
 
-    def upload_weekday(self) -> int | None:
+    def _upload_weekday(self) -> int | None:
+        if self.minimal:
+            return None
+
         try:
-            installation_data = self.read_installation_data()
+            installation_data = self._read_installation_data()
         except FileNotFoundError:
             # init the node info if it's gone
             installation_data = self.init_installation(False)
@@ -253,55 +287,29 @@ class TelemetryProvider:
 
         return report_uuid_prefix % 7  # 0 is Monday
 
-    def has_upload_consent(self, time_now: float | None = None) -> bool:
+    def _has_upload_consent(self, time_now: float | None = None) -> bool:
         if self.upload_consent_time is None:
             return False
         if time_now is None:
             time_now = time.time()
         return self.upload_consent_time.timestamp() <= time_now
 
-    def print_telemetry_notice(self, for_cli_verbose_output: bool = False) -> None:
-        if self.local_mode:
-            if for_cli_verbose_output:
-                self.logger.I(
-                    "telemetry mode is [green]local[/]: local data collection only, no uploads"
-                )
-            return
-
-        now = time.time()
-        if self.has_upload_consent(now) and not for_cli_verbose_output:
-            self.logger.D("user has consented to telemetry upload")
-            return
-
-        upload_wday = self.upload_weekday()
-        if upload_wday is None:
-            return
-        upload_wday_name = calendar.day_name[upload_wday]
-
+    def _print_upload_schedule_notice(self, upload_wday: int, now: float) -> None:
         next_upload_day_ts = next_utc_weekday(upload_wday, now)
         next_upload_day = time.localtime(next_upload_day_ts)
         next_upload_day_end = time.localtime(next_upload_day_ts + 86400)
         next_upload_day_str = time.strftime("%Y-%m-%d %H:%M:%S %z", next_upload_day)
         next_upload_day_end_str = time.strftime(
-            "%Y-%m-%d %H:%M:%S %z", next_upload_day_end
+            "%Y-%m-%d %H:%M:%S %z",
+            next_upload_day_end,
         )
 
-        today_is_upload_day = self.is_upload_day(now)
-        if for_cli_verbose_output:
-            self.logger.I(
-                "telemetry mode is [green]on[/]: data is collected and periodically uploaded"
-            )
-            self.logger.I(
-                f"non-tracking usage information will be uploaded to RuyiSDK-managed servers [bold green]every {upload_wday_name}[/]"
-            )
-        else:
-            self.logger.W(
-                f"this [yellow]ruyi[/] installation has telemetry mode set to [yellow]on[/], and [bold]will upload non-tracking usage information to RuyiSDK-managed servers[/] [bold green]every {upload_wday_name}[/]"
-            )
-
-        if today_is_upload_day:
+        if self._is_upload_day(now):
             for scope, store in self._stores.items():
-                has_uploaded_today = self.has_uploaded_today(scope, now)
+                has_uploaded_today = self._has_uploaded_today(
+                    store.last_upload_timestamp,
+                    now,
+                )
                 if has_uploaded_today:
                     if last_upload_time := store.last_upload_timestamp:
                         last_upload_time_str = time.strftime(
@@ -320,53 +328,165 @@ class TelemetryProvider:
                     )
         else:
             self.logger.I(
-                f"the next upload will happen anytime [yellow]ruyi[/] is executed between [bold green]{next_upload_day_str}[/] and [bold green]{next_upload_day_end_str}[/]"
+                "the next upload will happen anytime [yellow]ruyi[/] is executed:"
             )
+            self.logger.I(
+                f"  -  between [bold green]{next_upload_day_str}[/] and [bold green]{next_upload_day_end_str}[/]"
+            )
+            self.logger.I("  - or if the last upload is more than a week ago")
+
+    def print_telemetry_notice(self, for_cli_verbose_output: bool = False) -> None:
+        if self.minimal:
+            if for_cli_verbose_output:
+                self.logger.I(
+                    "telemetry mode is [green]off[/]: nothing is collected or uploaded after the first run"
+                )
+            return
+
+        now = time.time()
+        upload_wday = self._upload_weekday()
+        if upload_wday is None:
+            if for_cli_verbose_output:
+                self.logger.W(MALFORMED_TELEMETRY_STATE_MSG)
+            else:
+                self.logger.D(MALFORMED_TELEMETRY_STATE_MSG)
+            return
+
+        upload_wday_name = calendar.day_name[upload_wday]
+
+        if self.local_mode:
+            if for_cli_verbose_output:
+                self.logger.I(
+                    "telemetry mode is [green]local[/]: local usage collection only, no usage uploads except if requested"
+                )
+            return
+
+        if self._has_upload_consent(now) and not for_cli_verbose_output:
+            self.logger.D("user has consented to telemetry upload")
+            return
+
+        if for_cli_verbose_output:
+            self.logger.I(
+                "telemetry mode is [green]on[/]: usage data is collected and periodically uploaded"
+            )
+            self.logger.I(
+                f"non-tracking usage information will be uploaded to RuyiSDK-managed servers [bold green]every {upload_wday_name}[/]"
+            )
+        else:
+            self.logger.W(
+                f"this [yellow]ruyi[/] installation has telemetry mode set to [yellow]on[/], and [bold]will upload non-tracking usage information to RuyiSDK-managed servers[/] [bold green]every {upload_wday_name}[/]"
+            )
+
+        self._print_upload_schedule_notice(upload_wday, now)
 
         if not for_cli_verbose_output:
             self.logger.I("in order to hide this banner:")
             self.logger.I("- opt out with [yellow]ruyi telemetry optout[/]")
             self.logger.I("- or give consent with [yellow]ruyi telemetry consent[/]")
 
-    def next_upload_day(self, time_now: float | None = None) -> int | None:
-        upload_wday = self.upload_weekday()
+    def _next_upload_day(self, time_now: float | None = None) -> int | None:
+        upload_wday = self._upload_weekday()
         if upload_wday is None:
             return None
         return next_utc_weekday(upload_wday, time_now)
 
-    def is_upload_day(self, time_now: float | None = None) -> bool:
+    def _is_upload_day(self, time_now: float | None = None) -> bool:
         if time_now is None:
             time_now = time.time()
-        if upload_day := self.next_upload_day(time_now):
+        if upload_day := self._next_upload_day(time_now):
             return upload_day <= time_now
         return False
 
-    def has_uploaded_today(
+    def _has_uploaded_today(
         self,
-        scope: TelemetryScope,
+        last_upload_time: float | None,
         time_now: float | None = None,
     ) -> bool:
         if time_now is None:
             time_now = time.time()
-        if upload_day := self.next_upload_day(time_now):
+        if upload_day := self._next_upload_day(time_now):
             upload_day_end = upload_day + 86400
-            store = self.store(scope)
-            if store is None:
-                return False
-            if last_upload_time := store.last_upload_timestamp:
+            if last_upload_time is not None:
                 return upload_day <= last_upload_time < upload_day_end
         return False
 
     def record(self, scope: TelemetryScope, kind: str, **params: object) -> None:
+        if self.minimal:
+            self.logger.D(
+                f"minimal telemetry mode enabled, discarding event '{kind}' for scope {scope}"
+            )
+            return
+
         if store := self.store(scope):
             return store.record(kind, **params)
-        self.logger.D(f"no telemetry store for scope {scope}, discarding event")
+        self.logger.D(
+            f"no telemetry store for scope {scope}, discarding event '{kind}'"
+        )
 
     def discard_events(self, v: bool = True) -> None:
         self._discard_events = v
 
-    def flush(self, *, upload_now: bool = False) -> None:
-        now = time.time()
+    def _should_proceed_with_upload(
+        self,
+        scope: TelemetryScope,
+        explicit_request: bool,
+        cron_mode: bool,
+        now: float,
+    ) -> tuple[bool, str]:
+        # proceed to uploading if forced (explicit requested or _upload_on_exit)
+        # regardless of schedule
+        if explicit_request:
+            return True, "explicit request"
+        if self._upload_on_exit:
+            return True, "first-run upload on exit"
+
+        # this is not an explicitly requested upload, so only proceed if today
+        # is the day, or if the last upload is more than a week ago
+        #
+        # the last-upload-more-than-a-week-ago check is to avoid situations
+        # where the user has not run ruyi for a long time, thus missing
+        # the scheduled upload day.
+        #
+        # cron jobs are a mitigation, but we cannot rely on them either, because:
+        #
+        # * ruyi is more likely installed user-locally than system-wide, so
+        #   users may not set up cron jobs for themselves;
+        # * telemetry data is always recorded per user so system-wide cron jobs
+        #   cannot easily access this data.
+        last_upload_time: float | None = None
+        if store := self.store(scope):
+            last_upload_time = store.last_upload_timestamp
+
+        if not self._is_upload_day(now):
+            if last_upload_time is not None and now - last_upload_time >= 7 * 86400:
+                return True, "last upload more than a week ago"
+            return False, "not upload day"
+        # now we're sure today is the day
+
+        # if we're in cron mode, proceed as if it's an explicit request;
+        # otherwise, only proceed if mode is "on" and we haven't uploaded yet today
+        # for this scope
+        if cron_mode:
+            return True, "cron mode upload on upload day"
+
+        if self._gc.telemetry_mode != "on":
+            return False, "telemetry mode not 'on'"
+
+        if not self._has_uploaded_today(last_upload_time, now):
+            return True, "upload day, not yet uploaded today"
+        return False, "upload day, already uploaded today"
+
+    def flush(self, *, upload_now: bool = False, cron_mode: bool = False) -> None:
+        """
+        Flush collected telemetry data to persistent store, and upload if needed.
+
+        :param upload_now: Upload data right now regardless of schedule.
+        :type upload_now: bool
+        :param cron_mode: Whether this flush is called from a cron job. If true,
+            non-upload-day uploads will be skipped, otherwise acts just like
+            explicit uploads via `ruyi telemetry upload`.
+        :type cron_mode: bool
+        """
 
         # We may be self-uninstalling and purging all state data, and in this
         # case we don't want to record anything (thus re-creating directories).
@@ -374,31 +494,50 @@ class TelemetryProvider:
             self.logger.D("discarding collected telemetry data")
             return
 
-        self.logger.D("flushing telemetry to persistent store")
+        now = time.time()
+
+        def should_proceed(scope: TelemetryScope) -> tuple[bool, str]:
+            return self._should_proceed_with_upload(
+                scope,
+                explicit_request=upload_now,
+                cron_mode=cron_mode,
+                now=now,
+            )
+
+        if self.minimal:
+            if not self._upload_on_exit:
+                self.logger.D("skipping upload for non-first-run in minimal mode")
+                return
+
+            for scope, store in self._stores.items():
+                go_ahead, reason = should_proceed(scope)
+                self.logger.D(
+                    f"minimal telemetry upload check for scope {scope}: go_ahead={go_ahead}, reason={reason}"
+                )
+                if not go_ahead:
+                    continue
+                store.upload_minimal()
+            return
 
         for scope, store in self._stores.items():
+            self.logger.D(f"flushing telemetry to persistent store for scope {scope}")
             store.persist(now)
 
-            # try to upload if forced (upload_now or _upload_on_exit), or:
-            #
-            # * we're not in local mode
-            # * today is the day
-            # * we haven't uploaded today
-            if not (upload_now or self._upload_on_exit) and (
-                self.local_mode
-                or not self.is_upload_day(now)
-                or self.has_uploaded_today(scope, now)
-            ):
+            go_ahead, reason = should_proceed(scope)
+            self.logger.D(
+                f"regular telemetry upload check for scope {scope}: go_ahead={go_ahead}, reason={reason}"
+            )
+            if not go_ahead:
                 continue
 
-            self.prepare_data_for_upload(store)
-            self.upload_staged_payloads(store)
+            self._prepare_data_for_upload(store)
+            store.upload_staged_payloads()
 
-    def prepare_data_for_upload(self, store: TelemetryStore) -> None:
+    def _prepare_data_for_upload(self, store: TelemetryStore) -> None:
         installation_data: NodeInfo | None = None
         if store.scope.is_pm:
             try:
-                installation_data = self.read_installation_data()
+                installation_data = self._read_installation_data()
             except FileNotFoundError:
                 # should not happen due to is_upload_day() initializing it for us
                 # beforehand, but proceed without node info nonetheless
@@ -406,16 +545,20 @@ class TelemetryProvider:
 
         return store.prepare_data_for_upload(installation_data)
 
-    def upload_staged_payloads(self, store: TelemetryStore) -> None:
-        if self.local_mode:
-            return
-
-        return store.upload_staged_payloads()
-
     def oobe_prompt(self) -> None:
         """Ask whether the user consents to a first-run telemetry upload, and
         persist the user's exact telemetry choice."""
 
+        if self._gc.is_telemetry_optout:
+            # user has already explicitly opted out via the environment variable,
+            # don't bother asking
+            return
+
+        # We always report installation info on first run, regardless of
+        # user's telemetry choice. In case the user opts out, only do a one-time
+        # upload now, and never upload anything again.
+        self._upload_on_exit = True
+
         from ..cli import user_input
 
         self.logger.stdout(TELEMETRY_CONSENT_AND_UPLOAD_DESC)
@@ -441,4 +584,3 @@ class TelemetryProvider:
 
         consent_time = datetime.datetime.now().astimezone()
         set_telemetry_mode(self._gc, "on", consent_time)
-        self._upload_on_exit = True

{ruyi-0.44.0a20251118 → ruyi-0.44.0b20251219}/ruyi/telemetry/store.py

@@ -85,6 +85,11 @@ class TelemetryStore:
     def record_upload_timestamp(self, time_now: float | None = None) -> None:
         if time_now is None:
             time_now = time.time()
+
+        # We may not have store_root existing yet if we're in minimal telemetry
+        # mode
+        self.store_root.mkdir(parents=True, exist_ok=True)
+
         f = self.last_upload_marker_file
         f.touch()
         os.utime(f, (time_now, time_now))
@@ -122,10 +127,6 @@ class TelemetryStore:
             f"scope {self.scope}: persisted {len(self._events)} telemetry event(s)"
         )
 
-    def upload(self, installation_data: NodeInfo | None = None) -> None:
-        self.prepare_data_for_upload(installation_data)
-        self.upload_staged_payloads()
-
     def read_back_raw_events(self) -> Iterable[TelemetryEvent]:
         try:
             for f in self.raw_events_dir.glob("run.*.ndjson"):
@@ -177,6 +178,47 @@ class TelemetryStore:
 
         self.purge_raw_events()
 
+    def prepare_data_for_minimal_upload(self) -> bytes:
+        """Prepare a minimal upload payload with no installation data and no events.
+
+        Used when user has not consented to telemetry collection but also not
+        explicitly opted out, for gaining minimal insight into adoption.
+        """
+
+        # import ruyi.version here because this package is on the CLI startup
+        # critical path, and version probing is costly there
+        from ..version import RUYI_SEMVER
+
+        payload_nonce = uuid.uuid4().hex  # for server-side dedup purposes
+
+        # We don't have installation data, and cannot have it initialized
+        # in this case because absence of installation data means no user
+        # consent. And making up a persistent installation ID is not a
+        # choice either, because "installation ID" resembles "advertising
+        # ID" a lot, which is considered personally identifiable information
+        # (PII) and not allowed to be collected without user consent.
+        #
+        # So, resort to re-using the completely random nonce as the report
+        # UUID, which does not allow for server-side correlation but at least
+        # allows for some insight into end-user adoption.
+        payload: UploadPayload = {
+            "fmt": 1,
+            "nonce": payload_nonce,
+            "ruyi_version": RUYI_SEMVER,
+            "report_uuid": payload_nonce,
+            "events": [],
+        }
+
+        return json.dumps(payload).encode("utf-8")
+
+    def upload_minimal(self) -> None:
+        if not self.api_url:
+            return
+
+        p = self.prepare_data_for_minimal_upload()
+        self.upload_one_staged_payload(p, self.api_url)
+        self.record_upload_timestamp()
+
     def upload_staged_payloads(self) -> None:
         if not self.api_url:
             return
@@ -198,7 +240,7 @@ class TelemetryStore:
 
     def upload_one_staged_payload(
         self,
-        f: pathlib.Path,
+        f: pathlib.Path | bytes,
         endpoint: str,
     ) -> None:
         # import ruyi.version here because this package is on the CLI startup
@@ -206,13 +248,23 @@ class TelemetryStore:
         from ..version import RUYI_USER_AGENT
 
         api_path = urljoin_for_sure(endpoint, "upload-v1")
-        self._logger.D(f"scope {self.scope}: about to upload payload {f} to {api_path}")
+
+        if isinstance(f, pathlib.Path):
+            self._logger.D(
+                f"scope {self.scope}: about to upload payload {f} to {api_path}"
+            )
+            data = f.read_bytes()
+        else:
+            self._logger.D(
+                f"scope {self.scope}: about to upload in-memory payload to {api_path}"
+            )
+            data = f
 
         import requests
 
         resp = requests.post(
             api_path,
-            data=f.read_bytes(),
+            data=data,
             headers={"User-Agent": RUYI_USER_AGENT},
             allow_redirects=True,
             timeout=5,
@@ -228,11 +280,12 @@ class TelemetryStore:
             f"scope {self.scope}: telemetry upload ok: status code {resp.status_code}"
         )
 
-        # move to completed dir
-        # TODO: rotation
-        try:
-            f.rename(self.uploaded_dir / f.name)
-        except OSError as e:
-            self._logger.D(
-                f"scope {self.scope}: failed to move uploaded payload away: {e}"
-            )
+        if isinstance(f, pathlib.Path):
+            # move to completed dir
+            # TODO: rotation
+            try:
+                f.rename(self.uploaded_dir / f.name)
+            except OSError as e:
+                self._logger.D(
+                    f"scope {self.scope}: failed to move uploaded payload away: {e}"
+                )

{ruyi-0.44.0a20251118 → ruyi-0.44.0b20251219}/ruyi/telemetry/telemetry_cli.py

@@ -13,12 +13,34 @@ if TYPE_CHECKING:
 class TelemetryCommand(
     RootCommand,
     cmd="telemetry",
+    has_main=True,
     has_subcommands=True,
     help="Manage your telemetry preferences",
 ):
     @classmethod
     def configure_args(cls, gc: "GlobalConfig", p: "ArgumentParser") -> None:
-        pass
+        # https://github.com/python/cpython/issues/67037 prevents the registration
+        # of undocumented subcommands, so a preferred usage of
+        # "ruyi telemetry cron-upload" is not possible right now.
+        p.add_argument(
+            "--cron-upload",
+            action="store_true",
+            dest="cron_upload",
+            default=False,
+            help=argparse.SUPPRESS,
+        )
+
+    @classmethod
+    def main(cls, cfg: "GlobalConfig", args: argparse.Namespace) -> int:
+        cron_upload: bool = args.cron_upload
+        if not cron_upload:
+            args._parser.print_help()  # pylint: disable=protected-access
+            return 0
+
+        # the rest are implementation of "--cron-upload"
+
+        cfg.telemetry.flush(cron_mode=True)
+        return 0
 
 
 class TelemetryConsentCommand(
@@ -117,10 +139,6 @@ class TelemetryUploadCommand(
 
     @classmethod
     def main(cls, cfg: "GlobalConfig", args: argparse.Namespace) -> int:
-        if cfg.telemetry is None:
-            cfg.logger.W("telemetry is disabled, nothing to upload")
-            return 0
-
         cfg.telemetry.flush(upload_now=True)
         # disable the flush at program exit because we have just done that
         cfg.telemetry.discard_events()

{ruyi-0.44.0a20251118 → ruyi-0.44.0b20251219}/ruyi/version.py

@@ -1,6 +1,6 @@
 from typing import Final
 
-RUYI_SEMVER: Final = "0.44.0-alpha.20251118"
+RUYI_SEMVER: Final = "0.44.0-beta.20251219"
 RUYI_USER_AGENT: Final = f"ruyi/{RUYI_SEMVER}"
 
 COPYRIGHT_NOTICE: Final = """\