canvas-pull 2.4.0__tar.gz → 2.5.0__tar.gz

{canvas_pull-2.4.0 → canvas_pull-2.5.0}/CHANGELOG.md

@@ -6,6 +6,24 @@ uses [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [2.5.0] - 2026-11-01
+
+### Added
+- `--json` on `status`, `sync`, `log`, `courses`, `config` and `init`: one JSON object on stdout,
+  also for errors. Each change includes `local_path`.
+- Stable exit codes: 3 not configured, 4 token rejected, 5 partly failed, 6 another sync running
+  (1 is still a network/Canvas error, 2 invalid arguments).
+- Non-interactive `init`: `--url`, `--save-dir`, `--token-stdin`, `--no-input`.
+- Agent skill (`skills/canvas-pull/SKILL.md`) and a Claude Code plugin:
+  `/plugin install canvas-pull --marketplace gxxxr-111/canvas-pull`.
+
+### Changed
+- A course that can't be scanned now makes `sync`/`status` exit with 5 instead of 0.
+- Token rejected now exits with 4 instead of 1.
+- GitHub Actions are pinned to commit SHAs and updated to their latest versions
+  (checkout v7, setup-uv v10, upload-artifact v7, download-artifact v8). CI now also tests the
+  build-artifact hand-off used by releases.
+
 ## [2.4.0] - 2026-11-01
 
 First release on PyPI: `uv tool install canvas-pull` or `pipx install canvas-pull`.
@@ -76,6 +94,7 @@ Complete rewrite as an installable CLI.
 
 - First version: download all files of enrolled courses.
 
-[Unreleased]: https://github.com/gxxxr-111/canvas-pull/compare/v2.4.0...HEAD
+[Unreleased]: https://github.com/gxxxr-111/canvas-pull/compare/v2.5.0...HEAD
+[2.5.0]: https://github.com/gxxxr-111/canvas-pull/compare/v2.4.0...v2.5.0
 [2.4.0]: https://github.com/gxxxr-111/canvas-pull/compare/v1.0.0...v2.4.0
 [1.0.0]: https://github.com/gxxxr-111/canvas-pull/releases/tag/v1.0.0

{canvas_pull-2.4.0 → canvas_pull-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: canvas-pull
-Version: 2.4.0
+Version: 2.5.0
 Summary: Sync your Canvas LMS course files: download only what changed and see what instructors added, modified, moved or deleted.
 Project-URL: Homepage, https://github.com/gxxxr-111/canvas-pull
 Project-URL: Repository, https://github.com/gxxxr-111/canvas-pull
@@ -41,14 +41,15 @@ Description-Content-Type: text/markdown
 
 <p align="center">
   <a href="https://github.com/gxxxr-111/canvas-pull/actions/workflows/ci.yml"><img src="https://github.com/gxxxr-111/canvas-pull/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
-  <a href="https://pypi.org/project/canvas-pull/"><img src="https://img.shields.io/pypi/v/canvas-pull" alt="PyPI" /></a>
-  <a href="https://pypi.org/project/canvas-pull/"><img src="https://img.shields.io/pypi/pyversions/canvas-pull" alt="Python versions" /></a>
+  <a href="https://pypi.org/project/canvas-pull/"><img src="https://img.shields.io/pypi/v/canvas-pull?cacheSeconds=3600" alt="PyPI" /></a>
+  <a href="https://pypi.org/project/canvas-pull/"><img src="https://img.shields.io/pypi/pyversions/canvas-pull?cacheSeconds=3600" alt="Python versions" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license" /></a>
 </p>
 
 <p align="center">
   <a href="#quick-start">Quick start</a> ·
   <a href="#commands">Commands</a> ·
+  <a href="#use-with-ai-agents">AI agents</a> ·
   <a href="#faq">FAQ</a> ·
   <a href="#中文说明">中文说明</a>
 </p>
@@ -79,6 +80,8 @@ renamed/moved or deleted**. It can run on its own every morning and notify you.
   skip it (use `--refresh` to scan it again).
 - **Safe token storage.** `init` stores your token in the system keychain, not in a text file.
 - **Optional git.** `sync --git` commits each sync in the save folder.
+- **Made for scripts and AI agents.** Every command has `--json` output and stable exit codes,
+  and there's an agent skill / Claude Code plugin.
 - **Read-only and private.** Only reads from Canvas; no telemetry, nothing leaves your machine.
 - **Fast.** Courses are scanned in parallel (a 32-course account scans in about 10 s instead of
   75 s), with parallel downloads, automatic retries with back-off and full pagination.
@@ -118,6 +121,50 @@ To get the latest unreleased code: `uv tool install git+https://github.com/gxxxr
 | `canvas-pull schedule status \| run \| disable` | Show the schedule and its log, trigger it now, or remove it. |
 | `canvas-pull config` | Show settings in use. |
 
+## Use with AI agents
+
+canvas-pull is a plain CLI, so AI coding agents (Claude Code, Codex, Cursor, …) can run it
+directly. Ask *"anything new in my courses?"* or *"summarize this week's new slides"* and the
+agent syncs, reads the changed files and answers.
+
+**Install the skill** so your agent knows how to use it:
+
+```
+/plugin install canvas-pull --marketplace gxxxr-111/canvas-pull
+```
+
+The skill is in [`skills/canvas-pull/SKILL.md`](skills/canvas-pull/SKILL.md). Other agents that
+support Agent Skills can use that file as is.
+
+**JSON output.** Add `--json` to `status`, `sync`, `log`, `courses`, `config` or `init`, and stdout
+holds exactly one JSON object, also on errors:
+
+```bash
+canvas-pull log --since 7d --json | jq -r '.changes[] | select(.kind=="new") | .local_path'
+```
+
+Each change has `kind`, `course`, `path`, `local_path` (and `old_path` for moves).
+
+**Exit codes**
+
+| Code | Meaning |
+| --- | --- |
+| 0 | OK |
+| 1 | Network or Canvas error |
+| 2 | Invalid arguments |
+| 3 | Not configured / invalid settings |
+| 4 | Token rejected or expired |
+| 5 | Finished, but some downloads or courses failed |
+| 6 | Another sync is running |
+
+**Non-interactive setup** (CI, dotfiles, servers):
+
+```bash
+canvas-pull init --url oc.sjtu.edu.cn --save-dir ~/Canvas --token-stdin < token.txt
+```
+
+Agents should never handle your token. Run `canvas-pull init` yourself.
+
 ## Configuration
 
 `init` writes a config file (path shown by `canvas-pull config`). You can edit it:
@@ -219,6 +266,10 @@ No. It only sends read (`GET`) requests.
 Create a new one in Canvas and run `canvas-pull init` again. Scheduled syncs show a notification
 when the token is rejected.
 
+**Can it put assignment deadlines in my calendar?**
+Canvas already can. Open the Canvas **Calendar**, click **Calendar Feed**, and subscribe to
+that link in Apple Calendar, Google Calendar or Outlook.
+
 **How do I skip a course?**
 Add its ID or part of its name to `exclude` in the config file (`canvas-pull courses` shows IDs).
 
@@ -277,4 +328,6 @@ canvas-pull schedule enable --at 08:00   # 每天早上自动同步，有变化
 - 多门课并行扫描，32 门课大约 10 秒扫完。
 - `sync --git` 会在保存目录里自动提交一次 git，方便用 `git log` 回看。
 - 只读取 Canvas，不会修改任何内容；没有遥测，数据不离开你的电脑。
+- 所有命令都支持 `--json` 输出和固定的退出码，方便脚本和 AI 助手调用。在 Claude Code 里运行 `/plugin install canvas-pull --marketplace gxxxr-111/canvas-pull` 安装技能后，就可以直接问「我的课程这周有什么更新？帮我总结新课件」。
+- 作业截止日期：在 Canvas 的「日历」页面点「日历订阅源」，把链接加到系统日历即可，无需本工具。
 - 在你的学校试过了？欢迎提交一个 [School report](https://github.com/gxxxr-111/canvas-pull/issues/new?template=school_report.yml)，无论成功与否。

{canvas_pull-2.4.0 → canvas_pull-2.5.0}/README.md

@@ -6,14 +6,15 @@
 
 <p align="center">
   <a href="https://github.com/gxxxr-111/canvas-pull/actions/workflows/ci.yml"><img src="https://github.com/gxxxr-111/canvas-pull/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
-  <a href="https://pypi.org/project/canvas-pull/"><img src="https://img.shields.io/pypi/v/canvas-pull" alt="PyPI" /></a>
-  <a href="https://pypi.org/project/canvas-pull/"><img src="https://img.shields.io/pypi/pyversions/canvas-pull" alt="Python versions" /></a>
+  <a href="https://pypi.org/project/canvas-pull/"><img src="https://img.shields.io/pypi/v/canvas-pull?cacheSeconds=3600" alt="PyPI" /></a>
+  <a href="https://pypi.org/project/canvas-pull/"><img src="https://img.shields.io/pypi/pyversions/canvas-pull?cacheSeconds=3600" alt="Python versions" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license" /></a>
 </p>
 
 <p align="center">
   <a href="#quick-start">Quick start</a> ·
   <a href="#commands">Commands</a> ·
+  <a href="#use-with-ai-agents">AI agents</a> ·
   <a href="#faq">FAQ</a> ·
   <a href="#中文说明">中文说明</a>
 </p>
@@ -44,6 +45,8 @@ renamed/moved or deleted**. It can run on its own every morning and notify you.
   skip it (use `--refresh` to scan it again).
 - **Safe token storage.** `init` stores your token in the system keychain, not in a text file.
 - **Optional git.** `sync --git` commits each sync in the save folder.
+- **Made for scripts and AI agents.** Every command has `--json` output and stable exit codes,
+  and there's an agent skill / Claude Code plugin.
 - **Read-only and private.** Only reads from Canvas; no telemetry, nothing leaves your machine.
 - **Fast.** Courses are scanned in parallel (a 32-course account scans in about 10 s instead of
   75 s), with parallel downloads, automatic retries with back-off and full pagination.
@@ -83,6 +86,50 @@ To get the latest unreleased code: `uv tool install git+https://github.com/gxxxr
 | `canvas-pull schedule status \| run \| disable` | Show the schedule and its log, trigger it now, or remove it. |
 | `canvas-pull config` | Show settings in use. |
 
+## Use with AI agents
+
+canvas-pull is a plain CLI, so AI coding agents (Claude Code, Codex, Cursor, …) can run it
+directly. Ask *"anything new in my courses?"* or *"summarize this week's new slides"* and the
+agent syncs, reads the changed files and answers.
+
+**Install the skill** so your agent knows how to use it:
+
+```
+/plugin install canvas-pull --marketplace gxxxr-111/canvas-pull
+```
+
+The skill is in [`skills/canvas-pull/SKILL.md`](skills/canvas-pull/SKILL.md). Other agents that
+support Agent Skills can use that file as is.
+
+**JSON output.** Add `--json` to `status`, `sync`, `log`, `courses`, `config` or `init`, and stdout
+holds exactly one JSON object, also on errors:
+
+```bash
+canvas-pull log --since 7d --json | jq -r '.changes[] | select(.kind=="new") | .local_path'
+```
+
+Each change has `kind`, `course`, `path`, `local_path` (and `old_path` for moves).
+
+**Exit codes**
+
+| Code | Meaning |
+| --- | --- |
+| 0 | OK |
+| 1 | Network or Canvas error |
+| 2 | Invalid arguments |
+| 3 | Not configured / invalid settings |
+| 4 | Token rejected or expired |
+| 5 | Finished, but some downloads or courses failed |
+| 6 | Another sync is running |
+
+**Non-interactive setup** (CI, dotfiles, servers):
+
+```bash
+canvas-pull init --url oc.sjtu.edu.cn --save-dir ~/Canvas --token-stdin < token.txt
+```
+
+Agents should never handle your token. Run `canvas-pull init` yourself.
+
 ## Configuration
 
 `init` writes a config file (path shown by `canvas-pull config`). You can edit it:
@@ -184,6 +231,10 @@ No. It only sends read (`GET`) requests.
 Create a new one in Canvas and run `canvas-pull init` again. Scheduled syncs show a notification
 when the token is rejected.
 
+**Can it put assignment deadlines in my calendar?**
+Canvas already can. Open the Canvas **Calendar**, click **Calendar Feed**, and subscribe to
+that link in Apple Calendar, Google Calendar or Outlook.
+
 **How do I skip a course?**
 Add its ID or part of its name to `exclude` in the config file (`canvas-pull courses` shows IDs).
 
@@ -242,4 +293,6 @@ canvas-pull schedule enable --at 08:00   # 每天早上自动同步，有变化
 - 多门课并行扫描，32 门课大约 10 秒扫完。
 - `sync --git` 会在保存目录里自动提交一次 git，方便用 `git log` 回看。
 - 只读取 Canvas，不会修改任何内容；没有遥测，数据不离开你的电脑。
+- 所有命令都支持 `--json` 输出和固定的退出码，方便脚本和 AI 助手调用。在 Claude Code 里运行 `/plugin install canvas-pull --marketplace gxxxr-111/canvas-pull` 安装技能后，就可以直接问「我的课程这周有什么更新？帮我总结新课件」。
+- 作业截止日期：在 Canvas 的「日历」页面点「日历订阅源」，把链接加到系统日历即可，无需本工具。
 - 在你的学校试过了？欢迎提交一个 [School report](https://github.com/gxxxr-111/canvas-pull/issues/new?template=school_report.yml)，无论成功与否。

{canvas_pull-2.4.0 → canvas_pull-2.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "canvas-pull"
-version = "2.4.0"
+version = "2.5.0"
 description = "Sync your Canvas LMS course files: download only what changed and see what instructors added, modified, moved or deleted."
 authors = [{ name = "Mirage_", email = "gaoxuran111@gmail.com" }]
 readme = "README.md"

{canvas_pull-2.4.0 → canvas_pull-2.5.0}/src/canvas_pull/__init__.py

@@ -1,3 +1,3 @@
 """Sync files from your active Canvas LMS courses."""
 
-__version__ = "2.4.0"
+__version__ = "2.5.0"

{canvas_pull-2.4.0 → canvas_pull-2.5.0}/src/canvas_pull/cli.py

@@ -1,11 +1,19 @@
-"""Command-line interface."""
+"""Command-line interface.
+
+Every data command accepts --json: stdout then carries exactly one JSON object (also on
+errors), and human-oriented output is switched off. Exit codes are stable; see `ExitCode`.
+"""
 
 from __future__ import annotations
 
+import json
+import os
+import sys
 from collections import defaultdict
 from contextlib import nullcontext
+from enum import IntEnum
 from pathlib import Path
-from typing import Annotated
+from typing import Annotated, Any
 
 import typer
 from rich.console import Console
@@ -15,7 +23,7 @@ from rich.table import Table
 from . import __version__, notify
 from . import schedule as sched
 from .api import AuthError, CanvasClient, CanvasError
-from .collector import CourseScan, course_dirnames, list_courses, scan_courses
+from .collector import CourseScan, RemoteFile, course_dirnames, list_courses, scan_courses
 from .config import (
     DEFAULT_SAVE_DIR,
     Config,
@@ -40,6 +48,31 @@ app = typer.Typer(
 console = Console(highlight=False)
 err = Console(stderr=True, highlight=False)
 
+
+class ExitCode(IntEnum):
+    OK = 0
+    ERROR = 1  # network or Canvas error
+    USAGE = 2  # bad command-line arguments (Typer's own code)
+    CONFIG = 3  # not configured, or invalid settings
+    AUTH = 4  # Canvas rejected the token (invalid or expired)
+    PARTIAL = 5  # finished, but some downloads or courses failed
+    BUSY = 6  # another sync is running on the same folder
+
+
+_ERROR_TYPES = {
+    ExitCode.ERROR: "canvas",
+    ExitCode.CONFIG: "config",
+    ExitCode.AUTH: "auth",
+    ExitCode.BUSY: "busy",
+}
+
+JsonOpt = Annotated[
+    bool,
+    typer.Option("--json", help="Print one JSON object on stdout (for scripts and AI agents)."),
+]
+
+_json_mode = False
+
 STYLE = {
     Kind.NEW: ("+", "green"),
     Kind.MODIFIED: ("~", "yellow"),
@@ -49,9 +82,25 @@ STYLE = {
 }
 
 
-def _fail(message: str) -> typer.Exit:
-    err.print(f"[red]Error:[/] {message}")
-    return typer.Exit(1)
+def _start(json_: bool) -> None:
+    """Called first by every command: in JSON mode, silence human output."""
+    global _json_mode
+    _json_mode = json_
+    console.quiet = json_
+
+
+def _emit(data: dict[str, Any]) -> None:
+    sys.stdout.write(json.dumps(data, ensure_ascii=False, indent=2) + "\n")
+    sys.stdout.flush()
+
+
+def _fail(message: str, code: ExitCode = ExitCode.ERROR) -> typer.Exit:
+    if _json_mode:
+        kind = _ERROR_TYPES.get(code, "error")
+        _emit({"ok": False, "error": {"type": kind, "message": message, "exit_code": int(code)}})
+    else:
+        err.print(f"[red]Error:[/] {message}")
+    return typer.Exit(int(code))
 
 
 def _pretty(path: Path) -> str:
@@ -66,7 +115,12 @@ def _load(require_token: bool = True) -> Config:
     try:
         return load_config(require_token=require_token)
     except ConfigError as exc:
-        raise _fail(str(exc)) from None
+        raise _fail(str(exc), ExitCode.CONFIG) from None
+
+
+def _canvas_failure(exc: CanvasError) -> typer.Exit:
+    code = ExitCode.AUTH if isinstance(exc, AuthError) else ExitCode.ERROR
+    return _fail(str(exc), code)
 
 
 def _matches(course: Course, patterns: list[str]) -> bool:
@@ -91,40 +145,85 @@ def main(
 
 
 @app.command()
-def init() -> None:
-    """Set your Canvas URL, save folder and access token."""
+def init(
+    url: Annotated[
+        str | None, typer.Option("--url", help="Canvas site, e.g. oc.sjtu.edu.cn.")
+    ] = None,
+    save_dir_opt: Annotated[
+        Path | None, typer.Option("--save-dir", help="Folder to save files in.")
+    ] = None,
+    token_stdin: Annotated[
+        bool, typer.Option("--token-stdin", help="Read the access token from stdin.")
+    ] = False,
+    no_input: Annotated[
+        bool, typer.Option("--no-input", help="Never prompt; fail if something is missing.")
+    ] = False,
+    json_: JsonOpt = False,
+) -> None:
+    """Set your Canvas URL, save folder and access token.
+
+    Non-interactive: canvas-pull init --url oc.sjtu.edu.cn --save-dir ~/Canvas --token-stdin
+    (the token can also come from CANVAS_TOKEN).
+    """
+    _start(json_)
+    interactive = not (no_input or json_ or token_stdin)
     try:
         current = load_config(require_token=False)
     except ConfigError:
         current = None
 
-    console.print(
-        "Create a token in Canvas: [bold]Account → Settings → New Access Token[/].\n"
-        "The token is stored in your system keychain.\n"
-    )
-    website = normalize_website(
-        typer.prompt("Canvas URL", default=current.website if current else "oc.sjtu.edu.cn")
-    )
-    save_dir = (
-        Path(
-            typer.prompt(
-                "Save files to", default=str(current.save_dir) if current else DEFAULT_SAVE_DIR
-            )
+    def ask(label: str, default: str | None, hide: bool = False) -> str:
+        if not interactive:
+            if default:
+                return default
+            raise _fail(f"Missing {label}; pass it as an option.", ExitCode.CONFIG)
+        return typer.prompt(label, default=default, hide_input=hide)
+
+    if interactive:
+        console.print(
+            "Create a token in Canvas: [bold]Account → Settings → New Access Token[/].\n"
+            "The token is stored in your system keychain.\n"
         )
-        .expanduser()
-        .resolve()
+    website_raw = url or ask(
+        "Canvas URL", current.website if current else ("oc.sjtu.edu.cn" if interactive else None)
     )
-    token = typer.prompt("Access token", hide_input=True).strip()
+    try:
+        website = normalize_website(website_raw)
+    except ConfigError as exc:
+        raise _fail(str(exc), ExitCode.CONFIG) from None
+    default_dir = str(current.save_dir) if current else DEFAULT_SAVE_DIR
+    save_dir = Path(save_dir_opt or ask("Save files to", default_dir)).expanduser().resolve()
+
+    if token_stdin:
+        token = sys.stdin.readline().strip()
+    else:
+        token = os.environ.get("CANVAS_TOKEN", "") or ask("Access token", None, hide=True)
+    token = token.strip()
+    if not token:
+        raise _fail("No access token given.", ExitCode.CONFIG)
 
     try:
         with CanvasClient(website, token) as client:
             me = client.get("users/self")
     except CanvasError as exc:
-        raise _fail(f"Could not sign in to {website}: {exc}") from None
+        code = ExitCode.AUTH if isinstance(exc, AuthError) else ExitCode.ERROR
+        raise _fail(f"Could not sign in to {website}: {exc}", code) from None
 
     cfg = current or Config(website=website, save_dir=save_dir)
     cfg.website, cfg.save_dir, cfg.token = website, save_dir, token
     where = save_config(cfg)
+    if json_:
+        _emit(
+            {
+                "ok": True,
+                "user": me.get("name"),
+                "website": website,
+                "save_dir": str(save_dir),
+                "config_file": str(default_config_file()),
+                "token_stored_in": where,
+            }
+        )
+        return
     console.print(f"[green]✓[/] Signed in as [bold]{me.get('name', '?')}[/].")
     console.print(f"Settings: {default_config_file()}  ·  token: {where}")
     console.print("Next: [bold]canvas-pull sync[/]")
@@ -137,16 +236,36 @@ def courses(
         bool | None,
         typer.Option("--completed/--no-completed", help="Include completed (concluded) courses."),
     ] = None,
+    json_: JsonOpt = False,
 ) -> None:
     """List the courses that would be synced."""
+    _start(json_)
     cfg = _load()
     with_completed = cfg.include_completed if completed is None else completed
     try:
         with _client(cfg) as client:
             found = list_courses(client, include_past=all_, include_completed=with_completed)
     except CanvasError as exc:
-        raise _fail(str(exc)) from None
-
+        raise _canvas_failure(exc) from None
+
+    if json_:
+        _emit(
+            {
+                "ok": True,
+                "courses": [
+                    {
+                        "id": c.id,
+                        "name": c.label,
+                        "code": c.course_code,
+                        "term": c.term.name if c.term else None,
+                        "completed": c.completed,
+                        "excluded": _matches(c, cfg.exclude),
+                    }
+                    for c in found
+                ],
+            }
+        )
+        return
     table = Table(box=None, header_style="bold")
     table.add_column("ID", justify="right")
     table.add_column("Course")
@@ -203,10 +322,13 @@ def _scan(
 _KIND_ORDER = {Kind.NEW: 0, Kind.MODIFIED: 1, Kind.MOVED: 2, Kind.RESTORED: 3, Kind.DELETED: 4}
 
 
+def _sorted(changes: list[Change]) -> list[Change]:
+    return sorted(changes, key=lambda c: (c.course.lower(), _KIND_ORDER[c.kind], c.path.lower()))
+
+
 def _print_changes(changes: list[Change]) -> None:
     by_course: dict[str, list[Change]] = defaultdict(list)
-    ordered = sorted(changes, key=lambda c: (c.course.lower(), _KIND_ORDER[c.kind], c.path.lower()))
-    for c in ordered:
+    for c in _sorted(changes):
         by_course[c.course].append(c)
     for course, items in by_course.items():
         console.print(f"\n[bold]{course}[/]")
@@ -226,6 +348,43 @@ def _summary(changes: list[Change]) -> str:
     return ", ".join(parts) if parts else "no changes"
 
 
+def _counts(changes: list[Change]) -> dict[str, int]:
+    counts: dict[str, int] = defaultdict(int)
+    for c in changes:
+        counts[str(c.kind)] += 1
+    return dict(counts)
+
+
+def _change_json(c: Change, save_dir: Path) -> dict[str, Any]:
+    d = c.to_dict()
+    d["local_path"] = str(save_dir / c.path)
+    return d
+
+
+def _sync_json(
+    *,
+    dry_run: bool,
+    save_dir: Path,
+    changes: list[Change],
+    failed: list[tuple[Change, str]] = (),  # type: ignore[assignment]
+    locked: list[RemoteFile] = (),  # type: ignore[assignment]
+    scans: list[CourseScan] = (),  # type: ignore[assignment]
+    archived: int = 0,
+) -> dict[str, Any]:
+    skipped = [{"course": s.course.label, "error": s.error} for s in scans if s.error]
+    return {
+        "ok": not failed and not skipped,
+        "dry_run": dry_run,
+        "save_dir": str(save_dir),
+        "summary": _counts(changes),
+        "changes": [_change_json(c, save_dir) for c in _sorted(changes)],
+        "failed": [{"course": c.course, "path": c.path, "error": e} for c, e in failed],
+        "locked": [{"course": rf.course.label, "path": rf.path} for rf in locked],
+        "skipped_courses": skipped,
+        "archived_courses_skipped": archived,
+    }
+
+
 def _alert(enabled: bool, message: str) -> None:
     if enabled:
         notify.send(message)
@@ -257,15 +416,17 @@ def sync(
     refresh: Annotated[
         bool, typer.Option("--refresh", help="Scan archived completed courses again.")
     ] = False,
+    json_: JsonOpt = False,
 ) -> None:
     """Download new and changed files from your active courses."""
-    if not console.is_terminal and not dry_run:
+    _start(json_)
+    if not console.is_terminal and not dry_run and not json_:
         console.print(f"--- {now_iso()} canvas-pull sync")  # separator in scheduled-run logs
     try:
         cfg = load_config()
     except ConfigError as exc:
         _alert(notify_, f"Sync failed: {exc}")
-        raise _fail(str(exc)) from None
+        raise _fail(str(exc), ExitCode.CONFIG) from None
     use_git = cfg.git if git is None else git
     with_completed = cfg.include_completed if completed is None else completed
     manifest = Manifest.load(cfg.save_dir)
@@ -284,22 +445,46 @@ def sync(
             if not scans:
                 if not archived:
                     console.print("No matching active courses.")
+                if json_:
+                    _emit(
+                        _sync_json(
+                            dry_run=dry_run, save_dir=cfg.save_dir, changes=[], archived=archived
+                        )
+                    )
                 return
             plan = make_plan(scans, manifest, cfg.save_dir)
 
             for s in scans:
                 if s.error:
-                    err.print(f"[yellow]![/] Skipped {s.course.label}: {s.error}")
+                    if not json_:
+                        err.print(f"[yellow]![/] Skipped {s.course.label}: {s.error}")
                 elif s.files_tab_hidden:
                     console.print(
                         f"[dim]{s.course.label}: Files tab hidden; used Modules instead.[/]"
                     )
+            scan_failed = any(s.error for s in scans)
 
             if dry_run:
-                _print_changes(plan.changes)
-                console.print(f"\n{_summary(plan.changes)} · {_pretty(cfg.save_dir)}")
-                if plan.locked:
-                    console.print(f"[dim]{len(plan.locked)} locked file(s) not yet available.[/]")
+                if json_:
+                    _emit(
+                        _sync_json(
+                            dry_run=True,
+                            save_dir=cfg.save_dir,
+                            changes=plan.changes,
+                            locked=plan.locked,
+                            scans=scans,
+                            archived=archived,
+                        )
+                    )
+                else:
+                    _print_changes(plan.changes)
+                    console.print(f"\n{_summary(plan.changes)} · {_pretty(cfg.save_dir)}")
+                    if plan.locked:
+                        console.print(
+                            f"[dim]{len(plan.locked)} locked file(s) not yet available.[/]"
+                        )
+                if scan_failed:
+                    raise typer.Exit(int(ExitCode.PARTIAL))
                 return
 
             total = sum(1 for c in plan.changes if c.needs_download)
@@ -328,39 +513,54 @@ def sync(
                 finally:
                     manifest.save()
     except SyncLocked:
-        raise _fail("Another sync is already running for this folder.") from None
+        raise _fail("Another sync is already running for this folder.", ExitCode.BUSY) from None
     except AuthError as exc:
         _alert(notify_, "Sync failed: Canvas rejected your token. Run `canvas-pull init`.")
-        raise _fail(str(exc)) from None
+        raise _canvas_failure(exc) from None
     except CanvasError as exc:
         if exc.status is not None:  # stay quiet when simply offline
             _alert(notify_, f"Sync failed: {exc}")
-        raise _fail(str(exc)) from None
-
-    _print_changes(result.applied)
-    for change, reason in result.failed:
-        err.print(f"[red]✗[/] {change.path}: {reason}")
-    console.print(f"\n{_summary(result.applied)} · {_pretty(cfg.save_dir)}")
-    if plan.locked:
-        console.print(f"[dim]{len(plan.locked)} locked file(s) not yet available.[/]")
+        raise _canvas_failure(exc) from None
 
     if result.applied:
         record = {"time": now_iso(), "changes": [c.to_dict() for c in result.applied]}
         append_log(cfg.save_dir, record)
+    git_summary = None
     if use_git:
         try:
-            summary = commit_sync(cfg.save_dir, result.applied)
-            if summary:
-                console.print(f"[dim]git: {summary}[/]")
+            git_summary = commit_sync(cfg.save_dir, result.applied)
         except GitError as exc:
-            err.print(f"[yellow]git commit skipped:[/] {exc}")
+            if not json_:
+                err.print(f"[yellow]git commit skipped:[/] {exc}")
     if result.applied or result.failed:
         message = notify.describe(result.applied)
         if result.failed:
             message = f"{message} · {len(result.failed)} failed".lstrip(" ·")
         _alert(notify_, message)
-    if result.failed:
-        raise typer.Exit(1)
+
+    if json_:
+        data = _sync_json(
+            dry_run=False,
+            save_dir=cfg.save_dir,
+            changes=result.applied,
+            failed=result.failed,
+            locked=plan.locked,
+            scans=scans,
+            archived=archived,
+        )
+        data["git_commit"] = git_summary
+        _emit(data)
+    else:
+        _print_changes(result.applied)
+        for change, reason in result.failed:
+            err.print(f"[red]✗[/] {change.path}: {reason}")
+        console.print(f"\n{_summary(result.applied)} · {_pretty(cfg.save_dir)}")
+        if plan.locked:
+            console.print(f"[dim]{len(plan.locked)} locked file(s) not yet available.[/]")
+        if git_summary:
+            console.print(f"[dim]git: {git_summary}[/]")
+    if result.failed or scan_failed:
+        raise typer.Exit(int(ExitCode.PARTIAL))
 
 
 @app.command()
@@ -375,6 +575,7 @@ def status(
     refresh: Annotated[
         bool, typer.Option("--refresh", help="Scan archived completed courses again.")
     ] = False,
+    json_: JsonOpt = False,
 ) -> None:
     """Show what changed on Canvas since the last sync (downloads nothing)."""
     sync(
@@ -385,6 +586,7 @@ def status(
         git=False,
         notify_=False,
         refresh=refresh,
+        json_=json_,
     )
 
 
@@ -397,15 +599,41 @@ def log(
             "--since", "-s", help="Net summary since 7d, 24h, 2w, today or a date (2026-10-01)."
         ),
     ] = None,
+    json_: JsonOpt = False,
 ) -> None:
     """Show recent syncs, or a merged summary with --since (e.g. --since 7d)."""
+    _start(json_)
     cfg = _load(require_token=False)
     if since:
         try:
             start = parse_since(since)
         except ValueError as exc:
-            raise _fail(str(exc)) from None
+            raise _fail(str(exc), ExitCode.USAGE) from None
         net = summarize(read_log(cfg.save_dir, None), start)
+        if json_:
+            counts: dict[str, int] = defaultdict(int)
+            for n in net:
+                counts[n.kind] += 1
+            _emit(
+                {
+                    "ok": True,
+                    "since": start.isoformat(),
+                    "save_dir": str(cfg.save_dir),
+                    "summary": dict(counts),
+                    "changes": [
+                        {
+                            "kind": n.kind,
+                            "course": n.course,
+                            "path": n.path,
+                            **({"old_path": n.old_path} if n.old_path else {}),
+                            "time": n.time,
+                            "local_path": str(cfg.save_dir / n.path),
+                        }
+                        for n in net
+                    ],
+                }
+            )
+            return
         local = start.astimezone().strftime("%Y-%m-%d %H:%M")
         if not net:
             console.print(f"No changes since {local}.")
@@ -415,10 +643,10 @@ def log(
         for n in net:
             by_course[n.course].append(n)
         for course_name, items in by_course.items():
-            counts: dict[str, int] = defaultdict(int)
+            tally_counts: dict[str, int] = defaultdict(int)
             for n in items:
-                counts[n.kind] += 1
-            tally = ", ".join(f"{v} {k}" for k, v in counts.items())
+                tally_counts[n.kind] += 1
+            tally = ", ".join(f"{v} {k}" for k, v in tally_counts.items())
             console.print(f"\n[bold]{course_name}[/]  [dim]{tally}[/]")
             for n in items:
                 mark, color = STYLE[Kind(n.kind)]
@@ -429,6 +657,9 @@ def log(
         return
 
     records = read_log(cfg.save_dir, limit)
+    if json_:
+        _emit({"ok": True, "save_dir": str(cfg.save_dir), "syncs": list(reversed(records))})
+        return
     if not records:
         console.print("No syncs recorded yet.")
         return
@@ -442,25 +673,34 @@ def log(
 
 
 @app.command("config")
-def show_config() -> None:
+def show_config(json_: JsonOpt = False) -> None:
     """Show the settings in use (token hidden)."""
+    _start(json_)
     cfg = _load(require_token=False)
-    token = "set" if cfg.token else "missing"
+    values: dict[str, Any] = {
+        "config_file": str(default_config_file()),
+        "website": cfg.website,
+        "save_dir": str(cfg.save_dir),
+        "token": "set" if cfg.token else "missing",
+        "concurrency": cfg.concurrency,
+        "scan_concurrency": cfg.scan_concurrency,
+        "keep_history": cfg.keep_history,
+        "git": cfg.git,
+        "exclude": cfg.exclude,
+        "include_completed": cfg.include_completed,
+        "sources": cfg.sources,
+    }
+    if json_:
+        _emit({"ok": True, **values})
+        return
     table = Table(box=None, show_header=False)
-    for key, value in [
-        ("config file", str(default_config_file())),
-        ("website", cfg.website),
-        ("save_dir", _pretty(cfg.save_dir)),
-        ("token", token),
-        ("concurrency", str(cfg.concurrency)),
-        ("scan_concurrency", str(cfg.scan_concurrency)),
-        ("keep_history", str(cfg.keep_history)),
-        ("git", str(cfg.git)),
-        ("exclude", ", ".join(cfg.exclude) or "-"),
-        ("include_completed", str(cfg.include_completed)),
-        ("sources", ", ".join(cfg.sources)),
-    ]:
-        table.add_row(f"[bold]{key}[/]", value)
+    for key, value in values.items():
+        if key == "save_dir":
+            value = _pretty(cfg.save_dir)
+        elif isinstance(value, list):
+            value = ", ".join(value) or "-"
+        label = "config file" if key == "config_file" else key
+        table.add_row(f"[bold]{label}[/]", str(value))
     console.print(table)
 
 
@@ -482,12 +722,13 @@ def schedule_enable(
     ] = None,
 ) -> None:
     """Install (or replace) the automatic sync."""
+    _start(False)
     _load()  # fail now, not silently at 9am
     try:
         spec = sched.parse_spec(at or [], every)
         path = sched.enable(spec, workdir=Path.cwd())
     except sched.ScheduleError as exc:
-        raise _fail(str(exc)) from None
+        raise _fail(str(exc), ExitCode.CONFIG) from None
     cmd = sched.command()
     console.print(f"[green]✓[/] canvas-pull will sync [bold]{spec.describe()}[/].")
     console.print(f"[dim]Job: {path}\nCommand: {' '.join(cmd)}\nLog: {sched.log_file()}[/]")

{canvas_pull-2.4.0 → canvas_pull-2.5.0}/tests/test_cli.py

@@ -1,5 +1,7 @@
+import json
 import shutil
 import subprocess
+from pathlib import Path
 
 import pytest
 from typer.testing import CliRunner
@@ -74,7 +76,7 @@ def test_git_commit(env, monkeypatch):
 def test_bad_token_message(env, monkeypatch):
     monkeypatch.setenv("CANVAS_TOKEN", "expired")
     r = runner.invoke(cli.app, ["sync"])
-    assert r.exit_code == 1 and "token" in r.output.lower()
+    assert r.exit_code == 4 and "token" in r.output.lower()
 
 
 def test_notify_on_changes_and_on_bad_token(env, monkeypatch):
@@ -139,3 +141,104 @@ def _loader(cfg_file):
     from canvas_pull.config import load_config
 
     return lambda **kw: load_config(config_file=cfg_file, use_keyring=False, **kw)
+
+
+def _json(result):
+    import json
+
+    return json.loads(result.stdout)
+
+
+def test_json_status_and_sync(env):
+    fake, out = env
+    r = runner.invoke(cli.app, ["status", "--json"])
+    assert r.exit_code == 0, r.output
+    data = _json(r)
+    assert data["ok"] and data["dry_run"] and data["summary"] == {"new": 1}
+    assert data["changes"][0]["path"] == "Algorithms/hw1.pdf"
+
+    r = runner.invoke(cli.app, ["sync", "--json"])
+    data = _json(r)
+    assert data["ok"] and not data["dry_run"]
+    change = data["changes"][0]
+    assert change["kind"] == "new" and Path(change["local_path"]).read_bytes() == b"one"
+
+
+def test_json_log_courses_config(env):
+    fake, _ = env
+    runner.invoke(cli.app, ["sync"])
+    assert _json(runner.invoke(cli.app, ["log", "--since", "7d", "--json"]))["summary"] == {
+        "new": 1
+    }
+    assert len(_json(runner.invoke(cli.app, ["log", "--json"]))["syncs"]) == 1
+    courses = _json(runner.invoke(cli.app, ["courses", "--json"]))["courses"]
+    assert courses == [
+        {
+            "id": 1,
+            "name": "Algorithms",
+            "code": None,
+            "term": "Fall",
+            "completed": False,
+            "excluded": False,
+        }
+    ]
+    cfg = _json(runner.invoke(cli.app, ["config", "--json"]))
+    assert cfg["token"] == "set" and "good-token" not in json.dumps(cfg)
+
+
+def test_json_errors_and_exit_codes(env, monkeypatch):
+    monkeypatch.setenv("CANVAS_TOKEN", "expired")
+    r = runner.invoke(cli.app, ["status", "--json"])
+    assert r.exit_code == 4
+    assert _json(r)["error"]["type"] == "auth"
+
+    r = runner.invoke(cli.app, ["log", "--since", "soon", "--json"])
+    assert r.exit_code == 2
+
+    monkeypatch.delenv("CANVAS_URL")
+    r = runner.invoke(cli.app, ["courses", "--json"])
+    assert r.exit_code == 3 and _json(r)["error"]["type"] == "config"
+
+
+def test_partial_failure_exit_code(env):
+    fake, _ = env
+    fake.flaky["/api/v1/courses/1/folders"] = 99  # this course can't be scanned
+    r = runner.invoke(cli.app, ["sync", "--json"])
+    assert r.exit_code == 5
+    data = _json(r)
+    assert not data["ok"] and data["skipped_courses"][0]["course"] == "Algorithms"
+
+
+def test_busy_exit_code(env):
+    from canvas_pull.manifest import sync_lock
+
+    _, out = env
+    with sync_lock(out):
+        r = runner.invoke(cli.app, ["sync", "--json"])
+    assert r.exit_code == 6 and _json(r)["error"]["type"] == "busy"
+
+
+def test_init_non_interactive(env, monkeypatch, tmp_path):
+    import keyring
+
+    store = {}
+    monkeypatch.setattr(keyring, "set_password", lambda s, u, p: store.__setitem__(u, p))
+    cfg_file = tmp_path / "written.toml"
+    monkeypatch.setattr(config, "default_config_file", lambda: cfg_file)
+    monkeypatch.setattr(cli, "default_config_file", lambda: cfg_file)
+    monkeypatch.delenv("CANVAS_TOKEN")
+    r = runner.invoke(
+        cli.app,
+        ["init", "--url", BASE, "--save-dir", str(tmp_path / "c"), "--token-stdin", "--json"],
+        input="good-token\n",
+    )
+    assert r.exit_code == 0, r.output
+    data = _json(r)
+    assert data["user"] == "Student" and data["token_stored_in"] == "keychain"
+    assert store == {BASE: "good-token"} and "good-token" not in cfg_file.read_text()
+
+
+def test_init_no_input_reports_missing(env, monkeypatch):
+    monkeypatch.delenv("CANVAS_URL")
+    r = runner.invoke(cli.app, ["init", "--no-input", "--json"])
+    assert r.exit_code == 3 and "Canvas URL" in _json(r)["error"]["message"]