bb-sync 1.9.0__py3-none-any.whl

bb_sync/cli.py

@@ -0,0 +1,302 @@
+"""bb-sync 命令行入口（Typer + Click 延迟注册）。
+
+设计要点：
+
+- **全局选项与子命令分离**：``--json/--quiet/--verbose/--config`` 是全局开关，
+  子命令只管自己的业务参数
+- **退出码语义化**：所有异常在 :func:`main` 统一兜底，由
+  :class:`~bb_sync.core.errors.BbSyncError` 决定退出码，脚本可据此分支
+- **stdout/stderr 严格分流**：结果走 stdout（``--json`` 时是纯 JSON），
+  日志/进度/错误走 stderr
+- **冷启动优先**：命令模块延迟导入（见 :class:`LazyGroup`），
+  避免 ``--version`` / ``--help`` 被 playwright/pydantic/keyring 拖慢
+
+用法速查::
+
+    bb-sync run                    # 增量同步全部课程
+    bb-sync run --course CSC5010   # 只同步一门课
+    bb-sync course list --json     # 机器可读地列出课程
+    bb-sync config set root ~/University/courses
+    bb-sync doctor
+    bb-sync auth login / logout / status
+"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from types import ModuleType
+from typing import Any
+
+import click
+
+from bb_sync import ISSUES_URL, __version__
+from bb_sync.core.errors import BbSyncError, ExitCode, exit_code_for
+
+#: 命令名 → (模块名, 一句话帮助)
+SUBCOMMANDS: dict[str, tuple[str, str]] = {
+    "run": ("run", "执行一次课程同步"),
+    "due": ("due", "整理全部课程的待办到 due.md"),
+    "doctor": ("doctor", "体检：检查前置条件（git / Node / 浏览器 / 网络等）"),
+    "config": ("config", "查看 / 修改配置（如默认下载目录）"),
+    "auth": ("auth", "凭据管理：登录录入 / 退出 / 查看状态"),
+    "course": ("course", "课程操作（列出可同步的课程）"),
+}
+
+#: 扁平命令（无下级子命令）：模块里直接定义 ``<name>_cmd`` 函数，
+#: 其余模块用 ``app = typer.Typer(...)`` 声明为命令组
+FLAT_COMMANDS = frozenset({"run", "due", "doctor"})
+
+
+def _notify_update_after_command(result: Any, **_: Any) -> Any:
+    """普通命令成功后检查更新；提示失败绝不改变命令结果。"""
+    ctx = click.get_current_context(silent=True)
+    app_ctx = ctx.obj if ctx is not None else None
+    if app_ctx is None or getattr(app_ctx, "quiet", False):
+        return result
+    try:
+        from bb_sync.core.update import notify_if_outdated
+
+        notify_if_outdated(app_ctx.console)
+    except Exception:  # 更新检查是附加功能，不能影响正常命令
+        pass
+    return result
+
+
+def _as_click_group(obj: object) -> Any:
+    """把命令模块导出的 Typer 实例转成 Click 命令组。
+
+    Typer 实例不是 Click 组，需要 ``typer.main.get_command`` 转换
+    （延迟到此处调用，避免在模块顶层导入 typer）。
+    """
+    import typer
+
+    return typer.main.get_command(obj)  # type: ignore[arg-type]
+
+
+def _module_command(mod: ModuleType, cmd_name: str) -> click.Command | click.Group:
+    """取出命令模块对外暴露的命令对象（统一为 ``click.Command``）。
+
+    模块统一导出 ``app = typer.Typer(...)``，由本函数按命令类型解包：
+
+    - **扁平命令**（``FLAT_COMMANDS``，如 run / doctor）：模块里只有一条与命令同名的
+      子命令，这里把它取出来直接平铺到根下，得到 ``bb-sync run [OPTIONS]``，
+      而不是多余的 ``bb-sync run run``
+    - **命令组**（config / auth / course）：整体作为组挂上，
+      保留 ``bb-sync config set`` / ``bb-sync course list`` 这样的两级形态
+    """
+    app = getattr(mod, "app", None)
+    if app is None:
+        raise TypeError(f"命令模块 {mod.__name__!r} 缺少 app（Typer 实例）")
+    group = _as_click_group(app)
+
+    if cmd_name in FLAT_COMMANDS:
+        return _unwrap_flat(group, mod.__name__, cmd_name)
+    return _as_real_group(group, mod.__name__, cmd_name)
+
+
+def _unwrap_flat(group: click.Command, mod_name: str, cmd_name: str) -> click.Command:
+    """扁平命令：从（可能被折叠的）Typer 命令里取出唯一那条命令。
+
+    Typer 会把「只有一个子命令」的 app 直接折叠成那条命令（此时没有
+    ``commands`` 属性），两种情况都要兼容，并统一把名字改成 ``cmd_name``，
+    避免出现 ``bb-sync run run``。
+    """
+    if not hasattr(group, "commands"):
+        group.name = cmd_name
+        return group
+
+    commands = getattr(group, "commands", None) or {}
+    if len(commands) != 1:
+        raise TypeError(f"扁平命令模块 {mod_name!r} 应恰好声明 1 条命令，实际 {len(commands)} 条")
+    inner = next(iter(commands.values()))
+    inner.name = cmd_name
+    return inner
+
+
+def _as_real_group(group: click.Command, mod_name: str, cmd_name: str) -> click.Command:
+    """命令组：保证返回的对象带 ``commands``，且名字与注册名一致。
+
+    **不能靠 ``isinstance(group, click.Group)`` 判断**——Typer 0.27 的组类型
+    ``TyperGroup`` 并不继承 ``click.Group``（它继承 ``typer._click.core.Command``）。
+    因此这里用「有没有 ``commands`` 属性」作为「是不是命令组」的判据：
+
+    - 有 ``commands`` → 真命令组（如 config / auth），只把名字对齐注册名即可
+    - 没有 → 被 Typer 折叠成了单条命令（当 app 里的命令名与 app 名同名时会发生），
+      此时把它按真实子命令名重新包进一个 Click 组，否则
+      ``bb-sync course list`` 里的 ``list`` 会被当成多余参数报 UsageError
+    """
+    if hasattr(group, "commands"):
+        group.name = cmd_name
+        return group
+
+    # 被折叠成单条命令：用它的 name（真实子命令名）重建一个组
+    inner_name = group.name or ""
+    wrapper = click.Group(name=cmd_name, help=SUBCOMMANDS.get(cmd_name, ("", ""))[1])
+    wrapper.add_command(group, inner_name)
+    return wrapper
+
+
+class LazyGroup(click.Group):
+    """按需导入子命令模块的 Click 命令组。
+
+    注册时只记下「命令名 → 模块名 + 一句话帮助」，真正解析到该命令时才
+    ``import bb_sync.commands.<模块>``。这样 ``--version`` / ``--help`` 都不必
+    为 playwright、pydantic、keyring 的导入成本买单。
+
+    关键点：``--help`` 渲染命令列表时 Click 会逐个 ``get_command``；若在那里
+    做真实导入，help 就退化成全量加载。因此 :meth:`get_command` 分两级——
+    渲染帮助走 :meth:`_placeholder`（零导入），只有真正要执行命令时才导入。
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._loaded: set[str] = set()
+        #: 正在渲染根帮助（此时只需命令名与一句话说明，不必导入模块）
+        self._listing = False
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        return sorted(SUBCOMMANDS)
+
+    @staticmethod
+    def _placeholder(name: str) -> click.Command:
+        """给根帮助列表用的占位命令：只有元信息，不触发任何导入。"""
+        return click.Command(name, help=SUBCOMMANDS[name][1], params=[], callback=lambda: None)
+
+    def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        """渲染根帮助的命令列表时只读本地元信息，不导入任何命令模块。"""
+        self._listing = True
+        try:
+            super().format_commands(ctx, formatter)
+        finally:
+            self._listing = False
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        if cmd_name not in SUBCOMMANDS:
+            return None
+        # 渲染根帮助列表：给占位符即可，避免为了列一行说明把 playwright 拖进来。
+        # 但用户显式 `bb-sync <cmd> --help` 时必须给真命令，所以用 _listing 区分。
+        if self._listing:
+            return self.commands.get(cmd_name) or self._placeholder(cmd_name)
+
+        module = SUBCOMMANDS[cmd_name][0]
+        if module in self._loaded:
+            return self.commands.get(cmd_name)
+        self._loaded.add(module)
+
+        mod = importlib.import_module(f"bb_sync.commands.{module}")
+        sub = _module_command(mod, cmd_name)
+        sub.help = SUBCOMMANDS[cmd_name][1]
+        self.add_command(sub, cmd_name)
+        return self.commands.get(cmd_name)
+
+
+def _build_cli() -> LazyGroup:
+    """构建带全局选项的根命令组。"""
+
+    @click.group(
+        cls=LazyGroup,
+        name="bb-sync",
+        result_callback=_notify_update_after_command,
+        help="Blackboard 课程资源自动同步（ADFS SSO + Steel 浏览器后端）。",
+        invoke_without_command=True,
+        # 不用 no_args_is_help：那会让「无参数」以退出码 2 结束。
+        # 本工具约定无参数 = 显示帮助 + 退出码 0（见下方回调）。
+        no_args_is_help=False,
+        context_settings={"help_option_names": ["-h", "--help"], "max_content_width": 100},
+    )
+    @click.option("--json", "json_mode", is_flag=True, help="结果以 JSON 输出到 stdout")
+    @click.option("--quiet", "-q", "quiet", is_flag=True, help="抑制 stderr 上的普通日志")
+    @click.option("--verbose", "-v", "verbose", is_flag=True, help="stderr 上输出调试信息")
+    @click.option(
+        "--config",
+        "config_file",
+        default=None,
+        help="指定配置文件路径（默认 CWD，其次 ~/.bb-sync/）",
+    )
+    @click.version_option(
+        __version__, "--version", prog_name="bb-sync", message="%(prog)s %(version)s"
+    )
+    @click.pass_context
+    def cli(
+        ctx: click.Context,
+        json_mode: bool,
+        quiet: bool,
+        verbose: bool,
+        config_file: str | None,
+    ) -> None:
+        """Blackboard 课程资源自动同步。"""
+        from bb_sync.context import Context as _Ctx
+
+        ctx.obj = _Ctx(
+            json_mode=json_mode,
+            quiet=quiet,
+            verbose=verbose,
+            config_file=config_file,
+        )
+        if ctx.invoked_subcommand is None:
+            click.echo(ctx.get_help())
+            ctx.exit(ExitCode.SUCCESS)
+
+    return cli  # type: ignore[return-value]
+
+
+def _clickish_exception(exc: BaseException) -> bool:
+    """判断是否为 Click / Typer 的「用法类」异常。
+
+    **不能直接 ``isinstance(exc, click.ClickException)``**：Typer ≥0.27 内置了
+    一份自己的 ``_click``（``typer._click.exceptions``），它与官方 ``click`` 是
+    两套互不继承的类层级（``typer.ClickException`` 不是 ``click.ClickException``
+    的子类）。若只按官方类型捕获，``No such option`` 这类用法错误会掉进兜底分支，
+    既打印堆栈又返回错误的退出码 1。
+
+    这类异常的共性：带 ``exit_code`` 属性、且定义 ``show()``（官方 click）或
+    ``format_message()``（typer 内置 click）用于渲染错误信息，故按鸭子类型判定。
+    """
+    return hasattr(exc, "exit_code") and (hasattr(exc, "show") or hasattr(exc, "format_message"))
+
+
+def main() -> None:
+    """控制台脚本入口：统一异常处理与退出码。"""
+    import typer
+
+    cli = _build_cli()
+    try:
+        cli.main(standalone_mode=False)
+    except (click.exceptions.Abort, KeyboardInterrupt):
+        sys.stderr.write("\n已中断\n")
+        raise SystemExit(ExitCode.INTERRUPTED) from None
+    except typer.Exit as exc:
+        # --help / --version 的正常退出，携带自己的退出码（通常 0）
+        raise SystemExit(exc.exit_code) from None
+    except Exception as exc:
+        # 用法类异常（官方 click 与 typer 内置 click 都覆盖）：渲染信息后按其退出码退出
+        if _clickish_exception(exc):
+            if hasattr(exc, "show"):
+                exc.show()  # type: ignore[attr-defined]
+            else:
+                sys.stderr.write(str(exc) + "\n")
+            raise SystemExit(int(getattr(exc, "exit_code", ExitCode.USAGE_ERROR))) from None
+        if isinstance(exc, BbSyncError):
+            from bb_sync.core.output import Console
+
+            console = Console()
+            console.error(exc.message)
+            if exc.hint:
+                console.hint(exc.hint)
+            raise SystemExit(exc.exit_code) from None
+        if isinstance(exc, SystemExit):
+            raise
+        # 兜底：非预期异常显示堆栈，并明确引导到 issue 反馈
+        sys.stderr.write(f"✗ 未预期的错误：{exc}\n")
+        import traceback
+
+        traceback.print_exc()
+        sys.stderr.write(
+            f"  这看起来是 bb-sync 的问题，欢迎到 {ISSUES_URL} 提 issue 并附上以上信息\n"
+        )
+        raise SystemExit(exit_code_for(exc)) from None
+
+
+if __name__ == "__main__":
+    main()

bb_sync/commands/__init__.py

@@ -0,0 +1,5 @@
+"""CLI 子命令实现，一个命令一个模块。"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

bb_sync/commands/auth.py

@@ -0,0 +1,80 @@
+"""``bb-sync auth`` —— 凭据管理（login / logout / status）。
+
+密码不通过命令行参数传递：那会进 shell history / 进程列表 / CI 日志。
+一律走隐藏输入（getpass）并存入系统钥匙串，不在任何文件里落明文。
+"""
+
+from __future__ import annotations
+
+import typer
+
+from bb_sync.blackboard import login as login_mod
+from bb_sync.context import Context
+from bb_sync.creds import delete_credentials, load_credentials, mask
+
+app = typer.Typer(
+    help="凭据管理：登录录入 / 退出 / 查看状态", no_args_is_help=True, add_completion=False
+)
+
+
+@app.command("login")
+def login(ctx: typer.Context) -> None:
+    """交互式录入学号与密码，存入系统钥匙串（密码不回显）。"""
+    app_ctx: Context = ctx.obj
+    login_mod.prompt_credentials(app_ctx.console)
+    app_ctx.console.emit({"saved": True, "backend": "keyring"})
+
+
+@app.command("logout")
+def logout(ctx: typer.Context) -> None:
+    """从系统钥匙串删除已保存的凭据。"""
+    app_ctx: Context = ctx.obj
+    removed = delete_credentials()
+    if removed:
+        app_ctx.console.success("已从系统钥匙串删除凭据")
+    else:
+        app_ctx.console.warn("钥匙串中没有保存的凭据")
+    app_ctx.console.emit({"removed": removed})
+
+
+@app.command("status")
+def status(ctx: typer.Context) -> None:
+    """查看凭据当前配置状态（只显示脱敏后的账号）。"""
+    app_ctx: Context = ctx.obj
+    console = app_ctx.console
+
+    creds = load_credentials()
+    if creds.ok:
+        payload = {
+            "configured": True,
+            "source": creds.source,
+            "account": mask(creds.student_id, tail=3),
+        }
+        if console.json_mode:
+            console.emit(payload)
+        else:
+            console.table(
+                ["项目", "值"],
+                [
+                    ["状态", "已配置"],
+                    ["来源", creds.source],
+                    ["账号", mask(creds.student_id, tail=3)],
+                ],
+                json_data=payload,
+            )
+    else:
+        payload = {"configured": False, "source": None, "account": None}
+        if console.json_mode:
+            console.emit(payload)
+        else:
+            console.warn("尚未配置凭据")
+            console.hint("运行 bb-sync auth login 录入")
+            console.emit(payload)
+
+
+def register(root: typer.Typer) -> None:
+    """挂载到根 app。"""
+    root.add_typer(app, name="auth")
+
+
+__all__ = ["app", "register"]

bb_sync/commands/config.py

@@ -0,0 +1,239 @@
+"""``bb-sync config`` —— 查看与修改配置文件（编辑时保留原有注释）。"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import subprocess
+import sys
+from pathlib import Path, PureWindowsPath
+
+import typer
+import yaml
+
+from bb_sync import paths
+from bb_sync.context import Context
+from bb_sync.core import config_store
+from bb_sync.core.config import (
+    DEFAULT_CONFIG_TEXT,
+    Settings,
+    config_target,
+    dump_settings,
+    ensure_config_file,
+    load_settings,
+)
+from bb_sync.core.errors import ConfigError, NotFoundError
+
+app = typer.Typer(
+    help="查看 / 修改配置（如默认下载目录）", no_args_is_help=True, add_completion=False
+)
+
+
+def _target(ctx: typer.Context) -> Path:
+    """本次操作的目标配置文件。"""
+    return config_target(ctx.obj.config_file)
+
+
+def _require(ctx: typer.Context) -> Path:
+    """取配置文件路径，不存在则报错。"""
+    path = _target(ctx)
+    if not path.exists():
+        raise ConfigError(f"配置文件不存在：{path}", "运行 bb-sync config init 生成默认配置")
+    return path
+
+
+def _root_for_home(raw: str, target: Path) -> str:
+    """把目标配置里的 root 转成用户级配置中语义相同的值。
+
+    相对路径在不同配置文件中的基准目录不同；同步到 ``BB_SYNC_HOME`` 前必须先
+    按目标配置文件所在目录解析成绝对路径，否则换目录运行时会指向错误位置。
+    """
+    parsed = config_store.parse_value(raw)
+    if not isinstance(parsed, str):
+        return raw
+    value = parsed.strip()
+    if not value:
+        return raw
+    root = Path(value).expanduser()
+    if root.is_absolute() or PureWindowsPath(value).is_absolute():
+        return raw
+    return str((target.parent / root).resolve())
+
+
+def _sync_home_root(
+    target: Path,
+    key: str,
+    raw: str | None,
+    enabled: bool,
+) -> Path | None:
+    """把 root 的改动同步到用户级配置，避免换目录运行时使用旧值。"""
+    if not enabled or key != "root":
+        return None
+    home = paths.BB_SYNC_HOME / paths.CONFIG_NAME
+    if home.resolve() == target.resolve():
+        return None
+    if raw is None:
+        if not home.exists():
+            return None
+        try:
+            config_store.apply_to_file(home, "root", None)
+        except NotFoundError:
+            return None
+    else:
+        ensure_config_file(home)
+        config_store.apply_to_file(home, "root", _root_for_home(raw, target))
+    return home
+
+
+@app.command("path")
+def path_cmd(ctx: typer.Context) -> None:
+    """显示实际生效的配置文件路径。"""
+    typer.echo(str(_target(ctx)))
+
+
+@app.command("init")
+def init(ctx: typer.Context) -> None:
+    """生成一份默认配置文件（已存在时不覆盖）。"""
+    app_ctx: Context = ctx.obj
+    target = _target(ctx)
+    created = ensure_config_file(target)
+    if created:
+        app_ctx.console.success(f"已生成默认配置 {target}")
+    else:
+        app_ctx.console.log(f"配置文件已存在，未改动：{target}")
+    app_ctx.console.emit({"path": str(target), "created": created})
+
+
+@app.command("show")
+def show(ctx: typer.Context) -> None:
+    """显示整份配置文件内容。"""
+    app_ctx: Context = ctx.obj
+    target = _target(ctx)
+    if not target.exists():
+        raise ConfigError(f"配置文件不存在：{target}", "运行 bb-sync config init 生成默认配置")
+    text = target.read_text(encoding="utf-8")
+    if app_ctx.json_mode:
+        settings, _ = load_settings(target)
+        app_ctx.console.emit(dump_settings(settings))
+    else:
+        app_ctx.console.print_raw(text)
+
+
+@app.command("get")
+def get(
+    ctx: typer.Context,
+    key: str = typer.Argument(..., help="配置键，支持点号子键（如 root、course_dirs.CSC5010）"),
+) -> None:
+    """读取某一项配置。"""
+    app_ctx: Context = ctx.obj
+    target = _require(ctx)
+    settings, _ = load_settings(target)
+    node: object = dump_settings(settings) if not key else None
+
+    if key:
+        node = settings
+        for part in key.split("."):
+            if isinstance(node, dict):
+                node = node.get(part) if part in node else None
+            else:
+                node = getattr(node, part, None)
+            if node is None:
+                raise NotFoundError(f"配置里没有：{key}")
+
+    if isinstance(node, Settings):
+        node = dump_settings(node)
+    if app_ctx.json_mode:
+        app_ctx.console.emit(node)
+    elif isinstance(node, (dict, list)):
+        app_ctx.console.print_raw(
+            yaml.safe_dump(
+                node, allow_unicode=True, default_flow_style=False, sort_keys=False
+            ).rstrip()
+        )
+    else:
+        app_ctx.console.print_raw(str(node))
+
+
+@app.command("set")
+def set_(
+    ctx: typer.Context,
+    key: str = typer.Argument(..., help="配置键（如 root、course_dirs.CSC5010）"),
+    value: str = typer.Argument(..., help="值（YAML 标量或列表，含空格时加引号）"),
+    sync_home: bool = typer.Option(
+        True,
+        "--sync-home/--no-sync-home",
+        help="修改 root 时同步更新用户级配置",
+    ),
+) -> None:
+    """写入一项配置（永久生效）；root 默认同步到用户级配置。"""
+    app_ctx: Context = ctx.obj
+    config_store.parse_value(value)  # 校验 YAML 合法性
+    target = _target(ctx)
+    ensure_config_file(target)
+    action = config_store.apply_to_file(target, key, value)
+    synced = _sync_home_root(target, key, value, sync_home)
+    app_ctx.console.success(f"已写入 {target}")
+    if synced is not None:
+        app_ctx.console.success(f"已同步用户配置 {synced}")
+    payload: dict[str, str] = {
+        "path": str(target),
+        "action": action,
+        "key": key,
+        "value": value,
+    }
+    if synced is not None:
+        payload["synced_path"] = str(synced)
+    app_ctx.console.emit(payload)
+
+
+@app.command("unset")
+def unset(
+    ctx: typer.Context,
+    key: str = typer.Argument(..., help="配置键（如 root、course_dirs.CSC5010）"),
+    sync_home: bool = typer.Option(
+        True,
+        "--sync-home/--no-sync-home",
+        help="删除 root 时同步更新用户级配置",
+    ),
+) -> None:
+    """删除某项配置（恢复内置默认值）；root 默认同步到用户级配置。"""
+    app_ctx: Context = ctx.obj
+    target = _require(ctx)
+    action = config_store.apply_to_file(target, key, None)
+    synced = _sync_home_root(target, key, None, sync_home)
+    app_ctx.console.success(f"{action}（{target}）")
+    if synced is not None:
+        app_ctx.console.success(f"已同步用户配置 {synced}")
+    payload: dict[str, str] = {"path": str(target), "action": action, "key": key}
+    if synced is not None:
+        payload["synced_path"] = str(synced)
+    app_ctx.console.emit(payload)
+
+
+@app.command("edit")
+def edit(ctx: typer.Context) -> None:
+    """用系统默认编辑器打开配置文件。"""
+    app_ctx: Context = ctx.obj
+    target = _target(ctx)
+    ensure_config_file(target)
+    if sys.platform == "win32":
+        os.startfile(target)  # type: ignore[attr-defined]
+    elif sys.platform == "darwin" and not os.environ.get("EDITOR"):
+        # macOS 没有通用的终端默认编辑器；open -t 交给系统默认文本编辑器。
+        subprocess.call(["open", "-t", str(target)])
+    else:
+        editor = shlex.split(os.environ.get("EDITOR", "vi"))
+        subprocess.call([*editor, str(target)])
+    app_ctx.console.emit({"path": str(target), "opened": True})
+
+
+#: ``DEFAULT_CONFIG_TEXT`` 在 help 中被引用，导入即用，避免 linter 报未使用
+_ = DEFAULT_CONFIG_TEXT
+
+
+def register(root: typer.Typer) -> None:
+    """挂载到根 app。"""
+    root.add_typer(app, name="config")
+
+
+__all__ = ["app", "register"]

bb_sync/commands/course.py

@@ -0,0 +1,45 @@
+"""``bb-sync course`` —— 课程相关操作（当前提供 list）。"""
+
+from __future__ import annotations
+
+import typer
+
+from bb_sync.context import Context
+from bb_sync.core import service
+
+app = typer.Typer(help="课程操作（列出可同步的课程）", no_args_is_help=True, add_completion=False)
+
+
+@app.command("list")
+def list_cmd(
+    ctx: typer.Context,
+    course: list[str] = typer.Option(None, "--course", help="只看指定课程代码（可多次）"),
+) -> None:
+    """列出账号下可同步的课程（不下载任何文件）。"""
+    app_ctx: Context = ctx.obj
+    console = app_ctx.console
+    settings, config_path = app_ctx.load_settings(cli_overrides={"include": course or None})
+    options = service.SyncOptions(
+        settings=settings,
+        config_path=config_path,
+        root=service.plan_root(settings, config_path, None),
+        console=console,
+        headed=False,
+        dry_run=True,
+        courses=course or None,
+    )
+    courses = service.list_courses(options)
+    records = [c.as_dict() for c in courses]
+    console.table(
+        ["课程代码", "标题", "本地文件夹"],
+        [[c.code or "-", c.title, c.slug] for c in courses],
+        json_data=records,
+    )
+
+
+def register(root: typer.Typer) -> None:
+    """挂载到根 app。"""
+    root.add_typer(app, name="course")
+
+
+__all__ = ["app", "register"]