get-class-material 0.2.2__tar.gz → 0.2.4__tar.gz

{get_class_material-0.2.2 → get_class_material-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: get-class-material
-Version: 0.2.2
+Version: 0.2.4
 Summary: One-command bulk downloader for NTU COOL (Canvas) course materials — PDFs, lecture videos, and Pages.
 Author-email: jabir <jabir95tsai@gmail.com>
 License-Expression: MIT

{get_class_material-0.2.2 → get_class_material-0.2.4}/get_class_material.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: get-class-material
-Version: 0.2.2
+Version: 0.2.4
 Summary: One-command bulk downloader for NTU COOL (Canvas) course materials — PDFs, lecture videos, and Pages.
 Author-email: jabir <jabir95tsai@gmail.com>
 License-Expression: MIT

{get_class_material-0.2.2 → get_class_material-0.2.4}/get_class_material.egg-info/SOURCES.txt

@@ -28,6 +28,7 @@ tests/test_announcements.py
 tests/test_browser_session.py
 tests/test_canvas_client.py
 tests/test_cool_video.py
+tests/test_doctor.py
 tests/test_media_naming.py
 tests/test_session_client.py
 tests/test_storage.py

{get_class_material-0.2.2 → get_class_material-0.2.4}/ntu_cool_materials/cli.py

@@ -165,8 +165,9 @@ def _build_parser() -> argparse.ArgumentParser:
         "pick",
         help="Interactive: list your active courses, you pick one, it downloads everything.",
     )
-    pick.add_argument("--out", default="ntu-cool-gcm_material",
-                      help="Output directory (default: ntu-cool-gcm_material/, relative to current directory).")
+    pick.add_argument("--out", default=None,
+                      help="Output directory. Default: ~/Documents/ntu-cool-gcm_material "
+                           "(or ./ntu-cool-gcm_material if you already have one there).")
     pick.add_argument("--headers-file", default=".secrets/ntu_cool_headers.txt")
     pick.add_argument("--refresh-session", action="store_true",
                       help="Open the browser to refresh login before listing.")
@@ -179,6 +180,12 @@ def _build_parser() -> argparse.ArgumentParser:
     pick.add_argument("--skip-pages", action="store_true")
     pick.add_argument("--skip-youtube", action="store_true")
     pick.add_argument("--skip-cool-videos", action="store_true")
+    pick.add_argument(
+        "--all-file-types", action="store_true",
+        help="Also download non-PDF files (.docx / .pptx / .xlsx / .zip / etc.). "
+             "Default skips them so a friend's .doc that breaks when force-renamed "
+             "to .pdf doesn't show up unsolicited.",
+    )
     pick.add_argument(
         "--keep-terminal", action="store_true",
         help="Don't close the PowerShell window on quit (Windows only).",
@@ -193,8 +200,9 @@ def _build_parser() -> argparse.ArgumentParser:
         help="Download every PDF, Page, YouTube link and NTU CDN video for a course.",
     )
     course.add_argument("--course-id", required=True, help="Canvas course id (e.g. 60804).")
-    course.add_argument("--out", default="ntu-cool-gcm_material",
-                        help="Output directory (default: ntu-cool-gcm_material/, relative to current directory).")
+    course.add_argument("--out", default=None,
+                        help="Output directory. Default: ~/Documents/ntu-cool-gcm_material "
+                             "(or ./ntu-cool-gcm_material if you already have one there).")
     course.add_argument(
         "--headers-file",
         default=".secrets/ntu_cool_headers.txt",
@@ -220,6 +228,10 @@ def _build_parser() -> argparse.ArgumentParser:
     course.add_argument("--skip-pages", action="store_true")
     course.add_argument("--skip-youtube", action="store_true")
     course.add_argument("--skip-cool-videos", action="store_true")
+    course.add_argument(
+        "--all-file-types", action="store_true",
+        help="Also download non-PDF files (.docx / .pptx / .xlsx / .zip / etc.).",
+    )
 
     sync = subparsers.add_parser("sync", help="Download course files and module metadata.")
     sync.add_argument("--state", default="active", help="Canvas enrollment_state filter.")
@@ -373,6 +385,90 @@ def _close_parent_terminal_on_quit() -> None:
         pass
 
 
+def _windows_documents_folder() -> Path | None:
+    """Ask Windows itself where the user's Documents folder really is.
+
+    `~/Documents` works on most installs but breaks in two real cases:
+      - OneDrive sync redirects "Documents" to ~/OneDrive/<localized>/...
+        Often that's ~/OneDrive/文件/ on a Traditional Chinese system.
+      - User moved Documents to D drive via Properties → Location.
+
+    Windows' SHGetKnownFolderPath returns the actual filesystem path for
+    FOLDERID_Documents, transparent to OneDrive redirect, locale, and any
+    user customization. Returns None on non-Windows or if the call fails
+    (caller falls back to ~/Documents)."""
+    if os.name != "nt":
+        return None
+    try:
+        import ctypes
+        from ctypes import wintypes
+
+        class _GUID(ctypes.Structure):
+            _fields_ = [
+                ("Data1", wintypes.DWORD),
+                ("Data2", wintypes.WORD),
+                ("Data3", wintypes.WORD),
+                ("Data4", ctypes.c_ubyte * 8),
+            ]
+
+        # FOLDERID_Documents = {FDD39AD0-238F-46AF-ADB4-6C85480369C7}
+        folderid_documents = _GUID(
+            0xFDD39AD0, 0x238F, 0x46AF,
+            (ctypes.c_ubyte * 8)(0xAD, 0xB4, 0x6C, 0x85, 0x48, 0x03, 0x69, 0xC7),
+        )
+
+        SHGetKnownFolderPath = ctypes.windll.shell32.SHGetKnownFolderPath
+        SHGetKnownFolderPath.argtypes = [
+            ctypes.POINTER(_GUID), wintypes.DWORD, wintypes.HANDLE,
+            ctypes.POINTER(ctypes.c_wchar_p),
+        ]
+        SHGetKnownFolderPath.restype = ctypes.HRESULT
+
+        path_ptr = ctypes.c_wchar_p()
+        hr = SHGetKnownFolderPath(
+            ctypes.byref(folderid_documents), 0, None, ctypes.byref(path_ptr),
+        )
+        if hr != 0 or not path_ptr.value:
+            return None
+        result = Path(path_ptr.value)
+        ctypes.windll.ole32.CoTaskMemFree(path_ptr)
+        return result
+    except Exception:
+        return None
+
+
+def _default_documents_root() -> Path:
+    """Where to put the materials folder by default (parent of ntu-cool-gcm_material).
+
+    Windows: SHGetKnownFolderPath if available (handles OneDrive + locale),
+             else ~/Documents.
+    Mac/Linux: ~/Documents.
+    """
+    win_docs = _windows_documents_folder()
+    if win_docs is not None:
+        return win_docs
+    return Path.home() / "Documents"
+
+
+def _resolve_output_dir(arg_value: str | None) -> Path:
+    """Resolve where to put downloaded materials.
+
+    Precedence:
+      1. Explicit --out argument (user wins).
+      2. ./ntu-cool-gcm_material in the current directory IF it already
+         exists (legacy users from <0.2.6 who have stuff there already).
+      3. <Documents>/ntu-cool-gcm_material — Documents resolved via Windows'
+         own KnownFolders API so OneDrive redirects and zh-TW localization
+         go to the right place.
+    """
+    if arg_value:
+        return Path(arg_value).expanduser()
+    legacy = Path("ntu-cool-gcm_material")
+    if legacy.exists() and legacy.is_dir():
+        return legacy
+    return _default_documents_root() / "ntu-cool-gcm_material"
+
+
 def _maybe_set_up_youtube_cookies(cookies_path: Path) -> None:
     """If the user has no YouTube cookies, offer to set them up inline.
     Skips silently when stdin isn't a tty (piped input / tests)."""
@@ -510,7 +606,7 @@ def _cmd_pick(base_url: str, args: argparse.Namespace) -> int:
         try:
             download_course(
                 course_id=course_id,
-                output_dir=Path(args.out),
+                output_dir=_resolve_output_dir(args.out),
                 base_url=base_url,
                 headers_path=headers_path,
                 refresh_session=False,
@@ -523,6 +619,7 @@ def _cmd_pick(base_url: str, args: argparse.Namespace) -> int:
                 skip_pages=args.skip_pages,
                 skip_youtube=args.skip_youtube,
                 skip_cool_videos=args.skip_cool_videos,
+                all_file_types=args.all_file_types,
             )
         except RuntimeError as exc:
             print(t(f"下載失敗: {exc}", f"download failed: {exc}"))
@@ -798,7 +895,7 @@ def _cmd_download_course(base_url: str, args: argparse.Namespace) -> int:
     try:
         download_course(
             course_id=args.course_id,
-            output_dir=Path(args.out),
+            output_dir=_resolve_output_dir(args.out),
             base_url=base_url,
             headers_path=headers_path,
             refresh_session=args.refresh_session,
@@ -809,6 +906,7 @@ def _cmd_download_course(base_url: str, args: argparse.Namespace) -> int:
             skip_pages=args.skip_pages,
             skip_youtube=args.skip_youtube,
             skip_cool_videos=args.skip_cool_videos,
+            all_file_types=args.all_file_types,
         )
         return 0
     except RuntimeError as exc:

{get_class_material-0.2.2 → get_class_material-0.2.4}/ntu_cool_materials/course_pipeline.py

@@ -294,19 +294,66 @@ def _download_signed_url(url: str, target: Path) -> None:
 
 # ---- per-stage workers ----
 
-def download_files(plan: CoursePlan, client: CanvasSessionClient) -> StageStats:
-    """Download every File-type module item directly into the week directory."""
+_KNOWN_FILE_EXTS = {
+    ".pdf", ".doc", ".docx", ".ppt", ".pptx", ".xls", ".xlsx", ".csv",
+    ".zip", ".rar", ".7z", ".tar", ".gz",
+    ".txt", ".md", ".rtf",
+    ".jpg", ".jpeg", ".png", ".gif", ".bmp",
+    ".mp3", ".wav", ".m4a",
+    ".mp4", ".mov", ".avi", ".mkv",
+}
+
+
+def download_files(
+    plan: CoursePlan, client: CanvasSessionClient, *, all_file_types: bool = False,
+) -> StageStats:
+    """Download every File-type module item directly into the week directory.
+
+    Default: download every file but save with .pdf extension regardless of
+    the original type. Most NTU course material is PDF, so this gives a
+    uniform-looking output. Files that aren't really PDF (.docx, .xlsx, .zip,
+    etc.) still download fine — they just sit on disk with a .pdf extension.
+    Most apps still open them (Excel/Word sniff the binary), but if anything
+    won't open, re-run with `all_file_types=True` to get the real extensions.
+
+    With `all_file_types=True`, every file keeps its original extension
+    (.pdf / .docx / .pptx / .xlsx / .zip / etc.) — the cleanest behavior but
+    means the output isn't uniformly .pdf.
+    """
     headers = _session_headers(client)
     stats = StageStats()
+    forced_pdf_count = 0
     for week in plan.weeks:
         for item in week.items:
             if item.get("type") != "File":
                 continue
             file_id = str(item.get("content_id") or "")
             title = str(item.get("title") or "").strip() or f"item-{item.get('id')}"
-            stem = title[:-4] if title.lower().endswith(".pdf") else title
+
+            # Real extension for this file: prefer Canvas's display_name in
+            # content_details, fall back to the title's suffix.
+            content_details = item.get("content_details") or {}
+            display_name = str(content_details.get("display_name") or "")
+            real_ext = Path(display_name).suffix.lower() if display_name else ""
+            if not real_ext:
+                real_ext = Path(title).suffix.lower()
+
+            # Decide what extension to use ON DISK.
+            if all_file_types:
+                use_ext = real_ext or ".pdf"
+            else:
+                use_ext = ".pdf"
+                if real_ext and real_ext != ".pdf":
+                    forced_pdf_count += 1
+
+            # Strip any known extension from the title (case-insensitive) so we
+            # don't double up: "syllabus.pdf" + ".pdf" = "syllabus.pdf", not
+            # "syllabus.pdf.pdf"; "MS-02_C03-Ex.xlsx" + ".pdf" = "MS-02_C03-Ex.pdf",
+            # not "MS-02_C03-Ex.xlsx.pdf".
+            title_ext = Path(title).suffix.lower()
+            stem = title[:-len(title_ext)] if title_ext in _KNOWN_FILE_EXTS else title
             safe_title = sanitize_teacher_title(stem)
-            target = week.week_dir / f"{safe_title}.pdf"
+            target = week.week_dir / f"{safe_title}{use_ext}"
             if target.exists():
                 stats.skipped += 1
                 continue
@@ -327,6 +374,13 @@ def download_files(plan: CoursePlan, client: CanvasSessionClient) -> StageStats:
             except Exception as exc:
                 print(f"      ✗ 失敗: {exc}")
                 stats.failed.append(f"{week.label}/{target.name}: {type(exc).__name__}: {exc}")
+    if forced_pdf_count > 0:
+        print(t(
+            f"  注意: {forced_pdf_count} 個原本不是 PDF 的檔案被存成 .pdf。"
+            f"如果有檔案打不開,加 --all-file-types 重抓會用真實副檔名。",
+            f"  Note: {forced_pdf_count} non-PDF file(s) were saved with a .pdf extension. "
+            f"If any won't open, re-run with --all-file-types to keep their real extension.",
+        ))
     return stats
 
 
@@ -793,6 +847,7 @@ def download_course(
     headless: bool = False,
     skip_pdfs: bool = False, skip_pages: bool = False,
     skip_youtube: bool = False, skip_cool_videos: bool = False,
+    all_file_types: bool = False,
     sso_timeout_sec: int = 600,
 ) -> CoursePlan:
     """Top-level orchestrator. Opens at most ONE Playwright context for the entire run.
@@ -872,7 +927,7 @@ def download_course(
         if not skip_pdfs:
             print(t("\n[1/4] PDF 檔案", "\n[1/4] PDFs / Files"))
             course_stats.pdfs = _run_with_session_retry(
-                lambda c: download_files(plan, c), t("PDF", "files")
+                lambda c: download_files(plan, c, all_file_types=all_file_types), t("PDF", "files")
             )
             print(t(
                 f"  下載 {course_stats.pdfs.done}、跳過 {course_stats.pdfs.skipped}、失敗 {len(course_stats.pdfs.failed)}",

{get_class_material-0.2.2 → get_class_material-0.2.4}/ntu_cool_materials/doctor.py

@@ -14,10 +14,12 @@ print the right command for the user to run themselves.
 """
 from __future__ import annotations
 
+import os
 import platform
 import shutil
 import subprocess
 import sys
+import sysconfig
 import time
 from dataclasses import dataclass
 from pathlib import Path
@@ -123,6 +125,75 @@ def _install_ffmpeg_auto() -> bool:
     return False
 
 
+def _scripts_dir() -> Path | None:
+    """Where pip drops console-script .exe shims for this Python install."""
+    try:
+        path = sysconfig.get_path("scripts")
+    except Exception:
+        return None
+    return Path(path) if path else None
+
+
+def _normalized_path_entries() -> list[str]:
+    raw = os.environ.get("PATH", "")
+    out: list[str] = []
+    for entry in raw.split(os.pathsep):
+        if not entry:
+            continue
+        out.append(os.path.normcase(os.path.normpath(entry)))
+    return out
+
+
+def _scripts_on_path(scripts_dir: Path) -> bool:
+    target = os.path.normcase(os.path.normpath(str(scripts_dir)))
+    return target in _normalized_path_entries()
+
+
+def _add_scripts_to_user_path(scripts_dir: Path) -> bool:
+    """Append scripts_dir to the current user's PATH (Windows only).
+
+    We bypass `setx` for two reasons:
+      1. setx truncates PATH at 1024 chars (legacy registry limit).
+      2. setx reads from the process's PATH (Machine + User merged), so its
+         "write" actually corrupts the User scope with Machine entries.
+    `[Environment]::SetEnvironmentVariable(..., 'User')` reads + writes the
+    HKCU\\Environment hive cleanly, no length limit, no admin required.
+    The change only affects newly-launched processes — the current PowerShell
+    won't see it until reopened, which is fine for our messaging.
+    """
+    if platform.system() != "Windows":
+        return False
+
+    scripts = str(scripts_dir)
+    # Single-quote the path inside the PowerShell literal; PowerShell single
+    # quotes don't expand $vars and treat backslashes literally, so Windows
+    # paths drop in as-is. Embedded apostrophes (rare in usernames) get
+    # doubled-up to escape them.
+    ps_scripts = scripts.replace("'", "''")
+    ps_script = (
+        f"$scripts = '{ps_scripts}'; "
+        "$user = [Environment]::GetEnvironmentVariable('PATH', 'User'); "
+        "if (-not $user) { $user = '' }; "
+        "$entries = @($user -split ';' | Where-Object { $_ -ne '' }); "
+        "if ($entries -notcontains $scripts) { "
+        "  if ($user) { [Environment]::SetEnvironmentVariable('PATH', $user.TrimEnd(';') + ';' + $scripts, 'User') } "
+        "  else { [Environment]::SetEnvironmentVariable('PATH', $scripts, 'User') }; "
+        "  Write-Output 'added' "
+        "} else { Write-Output 'already-present' }"
+    )
+
+    ok = _stream_subprocess(
+        ["powershell", "-NoProfile", "-Command", ps_script],
+        f"add {scripts_dir} to user PATH",
+    )
+    if ok:
+        print(t(
+            "    ⚠ 請關掉這個視窗、重新打開,之後就能直接打 `ntu-cool-gcm` 啟動。",
+            "    ⚠ Close this window, reopen it, then `ntu-cool-gcm` will work directly.",
+        ))
+    return ok
+
+
 # ---- checks ----
 
 def check_python() -> CheckResult:
@@ -226,6 +297,43 @@ def check_ffmpeg() -> CheckResult:
     )
 
 
+def check_scripts_on_path() -> CheckResult:
+    """Python's `Scripts\\` dir must be on PATH or pip's entry-point shims
+    (ntu-cool-gcm.exe etc.) won't resolve from a fresh shell.
+
+    NOTE: keep the `name` string fixed (not localized) — it's used as a
+    set-membership key by `ensure_ready`'s `recommended_names`. The rest
+    of the user-facing strings here can vary by locale.
+    """
+    name = "Python Scripts 在 PATH 上"
+    if platform.system() != "Windows":
+        # On macOS/Linux, pip --user goes to a different dir (~/.local/bin or
+        # /opt/homebrew/bin) and the symptoms / fixes are different enough
+        # that we leave this to the OS package manager and shell rc files.
+        return CheckResult(name=name, ok=True, optional=True, detail="(non-Windows, skipped)")
+
+    scripts_dir = _scripts_dir()
+    if scripts_dir is None:
+        return CheckResult(name=name, ok=True, optional=True, detail="(scripts dir unknown)")
+
+    on_path = _scripts_on_path(scripts_dir)
+    if on_path:
+        return CheckResult(name=name, ok=True, detail=str(scripts_dir))
+
+    return CheckResult(
+        name=name,
+        ok=False,
+        optional=True,
+        detail=f"{scripts_dir} 不在 PATH 上",
+        fix_command=(
+            f'powershell -NoProfile -Command "[Environment]::SetEnvironmentVariable('
+            f"'PATH', [Environment]::GetEnvironmentVariable('PATH', 'User').TrimEnd(';') + "
+            f"';{scripts_dir}', 'User')\""
+        ),
+        auto_install=lambda: _add_scripts_to_user_path(scripts_dir),
+    )
+
+
 def check_ntu_session(headers_path: Path) -> CheckResult:
     if not headers_path.exists():
         return CheckResult(
@@ -271,6 +379,7 @@ def _all_checks(headers_path: Path, youtube_cookies_path: Path) -> list[CheckRes
         check_yt_dlp(),
         check_node(),
         check_ffmpeg(),
+        check_scripts_on_path(),
         check_ntu_session(headers_path),
         check_youtube_cookies(youtube_cookies_path),
     ]
@@ -356,6 +465,11 @@ def ensure_ready(
     recommended_names = {
         "Node.js (下載 YouTube 影片用)",
         "ffmpeg (下載 YouTube 影片用)",
+        # Not blocking — if Scripts isn't on PATH, the user invoked us via
+        # `python -m ntu_cool_materials pick` and the pick already works.
+        # The check exists to upgrade that to the shorter `ntu-cool-gcm`
+        # for future runs.
+        "Python Scripts 在 PATH 上",
     }
     relevant = blocking_names | recommended_names
 

{get_class_material-0.2.2 → get_class_material-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "get-class-material"
-version = "0.2.2"
+version = "0.2.4"
 description = "One-command bulk downloader for NTU COOL (Canvas) course materials — PDFs, lecture videos, and Pages."
 readme = "README.md"
 license = "MIT"

get_class_material-0.2.4/tests/test_doctor.py

@@ -0,0 +1,93 @@
+"""Tests for the PATH-detection bits of doctor.py.
+
+These avoid actually invoking subprocesses or modifying real PATH — we just
+patch `os.environ["PATH"]` and call the pure helpers.
+"""
+from __future__ import annotations
+
+import os
+import unittest
+from pathlib import Path
+from unittest import mock
+
+from ntu_cool_materials import doctor
+
+
+class ScriptsOnPathTests(unittest.TestCase):
+    def test_exact_match(self) -> None:
+        scripts = Path(r"C:\Python\Scripts")
+        with mock.patch.dict(os.environ, {"PATH": r"C:\Windows;C:\Python\Scripts;C:\Other"}):
+            self.assertTrue(doctor._scripts_on_path(scripts))
+
+    def test_missing(self) -> None:
+        scripts = Path(r"C:\Python\Scripts")
+        with mock.patch.dict(os.environ, {"PATH": r"C:\Windows;C:\Other"}):
+            self.assertFalse(doctor._scripts_on_path(scripts))
+
+    def test_case_insensitive_on_windows(self) -> None:
+        # normcase lowercases on Windows; os.pathsep + paths come back upper-cased
+        # from the registry sometimes, so we need to match regardless of case.
+        scripts = Path(r"C:\Python\Scripts")
+        with mock.patch.dict(os.environ, {"PATH": r"C:\WINDOWS;c:\python\scripts;C:\Other"}):
+            if os.name == "nt":
+                self.assertTrue(doctor._scripts_on_path(scripts))
+            else:
+                # POSIX is case-sensitive — the test is only meaningful on Windows.
+                self.assertFalse(doctor._scripts_on_path(scripts))
+
+    def test_trailing_separator_tolerated(self) -> None:
+        scripts = Path(r"C:\Python\Scripts")
+        # Trailing backslash should normpath away.
+        with mock.patch.dict(os.environ, {"PATH": r"C:\Python\Scripts\;C:\Other"}):
+            self.assertTrue(doctor._scripts_on_path(scripts))
+
+    def test_empty_path_entries_ignored(self) -> None:
+        scripts = Path(r"C:\Python\Scripts")
+        # Empty entries from leading/trailing/double separators should not crash
+        # or false-match.
+        with mock.patch.dict(os.environ, {"PATH": f";;{scripts};;"}):
+            self.assertTrue(doctor._scripts_on_path(scripts))
+
+
+class CheckScriptsOnPathTests(unittest.TestCase):
+    def test_non_windows_returns_ok(self) -> None:
+        with mock.patch.object(doctor.platform, "system", return_value="Darwin"):
+            result = doctor.check_scripts_on_path()
+        self.assertTrue(result.ok)
+        self.assertTrue(result.optional)
+
+    def test_windows_on_path(self) -> None:
+        fake_scripts = Path(r"C:\Python\Scripts")
+        with (
+            mock.patch.object(doctor.platform, "system", return_value="Windows"),
+            mock.patch.object(doctor, "_scripts_dir", return_value=fake_scripts),
+            mock.patch.dict(os.environ, {"PATH": str(fake_scripts) + ";C:\\Other"}),
+        ):
+            result = doctor.check_scripts_on_path()
+        self.assertTrue(result.ok)
+        self.assertEqual(result.detail, str(fake_scripts))
+
+    def test_windows_missing_offers_auto_install(self) -> None:
+        fake_scripts = Path(r"C:\Python\Scripts")
+        with (
+            mock.patch.object(doctor.platform, "system", return_value="Windows"),
+            mock.patch.object(doctor, "_scripts_dir", return_value=fake_scripts),
+            mock.patch.dict(os.environ, {"PATH": r"C:\Windows;C:\Other"}),
+        ):
+            result = doctor.check_scripts_on_path()
+        self.assertFalse(result.ok)
+        self.assertTrue(result.optional)  # not blocking
+        self.assertIsNotNone(result.auto_install)
+        self.assertIn(str(fake_scripts), result.fix_command)
+
+    def test_name_is_stable_for_set_membership(self) -> None:
+        """`ensure_ready` matches checks against `recommended_names` by exact
+        string. If we ever localize this check's name via t(), the match breaks
+        silently. Lock the name in place via a test."""
+        with mock.patch.object(doctor.platform, "system", return_value="Linux"):
+            result = doctor.check_scripts_on_path()
+        self.assertEqual(result.name, "Python Scripts 在 PATH 上")
+
+
+if __name__ == "__main__":
+    unittest.main()