monash-study-kit 1.2.0__tar.gz

monash_study_kit-1.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,39 @@
+name: Bug report
+description: Something doesn't work or gives a wrong answer
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please don't paste cookies, tokens, calendar links, unit materials, other students' posts or your grades.
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: What you did or asked Claude, what you expected, and what you got.
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    attributes:
+      label: Output of `monash doctor`
+      description: Run `monash doctor --deep` if the problem is a wrong or missing result. The output leaves out credentials.
+      render: text
+    validations:
+      required: true
+  - type: dropdown
+    id: where
+    attributes:
+      label: Where
+      options:
+        - Claude Desktop
+        - Claude Code
+        - The monash command in a terminal
+        - Another MCP client
+    validations:
+      required: true
+  - type: input
+    id: unit
+    attributes:
+      label: Unit code (if it only happens in one unit)
+      placeholder: FIT2102

monash_study_kit-1.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security problem
+    url: https://github.com/Waldo0926/monash-study-kit/security/advisories/new
+    about: Report it privately, not as a public issue.

monash_study_kit-1.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,23 @@
+name: Feature request
+description: Something you'd like it to do
+labels: [enhancement]
+body:
+  - type: textarea
+    id: need
+    attributes:
+      label: What do you want to do
+      description: What you'd ask Claude or type in the terminal, and what answer you'd want.
+    validations:
+      required: true
+  - type: textarea
+    id: where
+    attributes:
+      label: Where the data is
+      description: Which Moodle or Ed page has this information today.
+  - type: checkboxes
+    id: readonly
+    attributes:
+      label: Read-only
+      options:
+        - label: This only reads from Moodle or Ed. (Submitting, posting or changing things is out of scope.)
+          required: true

monash_study_kit-1.2.0/.github/pull_request_template.md

@@ -0,0 +1,10 @@
+Before:
+
+After:
+
+How:
+
+- [ ] Tests added or updated, and `uv run pytest -q` passes
+- [ ] `uvx ruff@0.6.9 check src tests scripts` passes
+- [ ] If `src/` changed: `__version__` bumped and `CHANGELOG.md` updated
+- [ ] Still read-only, and no real names, ids, cookies or tokens in test samples

monash_study_kit-1.2.0/.github/workflows/release.yml

@@ -0,0 +1,115 @@
+name: release
+
+# 推一个 v 开头的 tag 就发版：tag 和 __version__ 对得上、CHANGELOG 写了、全部测试过了，
+# 才打包上传 PyPI（Trusted Publishing，不存任何密码或令牌），再从 PyPI 装一遍确认能用，最后建 GitHub Release。
+#   git tag v1.1.0 && git push origin v1.1.0
+# PyPI 那边第一次要先加好 trusted publisher，步骤见 docs/releasing.md。
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.v.outputs.version }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4
+        with:
+          fetch-depth: 0
+      - name: tag、__version__、CHANGELOG 三处一致，tag 在 main 上
+        id: v
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version=$(sed -n 's/^__version__ = "\(.*\)"/\1/p' src/monash_study_kit/__init__.py)
+          if [ "$tag" != "$version" ]; then
+            echo "::error::tag 是 v$tag，但 __version__ 是 $version"; exit 1
+          fi
+          if ! grep -qx "## $version" CHANGELOG.md; then
+            echo "::error file=CHANGELOG.md::CHANGELOG 里没有 ## $version 这一节"; exit 1
+          fi
+          git fetch origin main
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "::error::v$version 指向的提交不在 main 上，先合进 main 再打 tag"; exit 1
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+  test:
+    needs: check
+    uses: ./.github/workflows/test.yml
+
+  build:
+    needs: [check, test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e  # v6
+      - run: uv build
+      - run: uv run --no-project scripts/check_dist.py dist "${{ needs.check.outputs.version }}"
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: [check, build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/monash-study-kit/${{ needs.check.outputs.version }}/
+    permissions:
+      id-token: write       # Trusted Publishing 靠这个向 PyPI 证明是这个仓库的这个 workflow
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # release/v1
+
+  pypi-smoke:
+    # 用户真正会做的事：从 PyPI 装，然后跑起来
+    needs: [check, publish]
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e  # v6
+      - name: 从 PyPI 装（刚上传可能要等一会儿才装得到）
+        shell: bash
+        run: |
+          v="${{ needs.check.outputs.version }}"
+          uv venv --python 3.13 smoke
+          if [ -d smoke/Scripts ]; then py=smoke/Scripts/python.exe exe=smoke/Scripts/monash.exe; else py=smoke/bin/python exe=smoke/bin/monash; fi
+          for i in 1 2 3 4 5 6; do
+            uv pip install --python "$py" --refresh "monash-study-kit==$v" && break
+            [ "$i" = 6 ] && exit 1
+            sleep 20
+          done
+          "$py" scripts/smoke_test.py "$exe" "$v"
+
+  github-release:
+    needs: [check, build, pypi-smoke]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
+        with:
+          name: dist
+          path: dist/
+      - name: 用 CHANGELOG 里这一版的内容建 Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          v="${{ needs.check.outputs.version }}"
+          awk -v h="## $v" '$0 == h {on=1; next} /^## / && on {exit} on' CHANGELOG.md > notes.md
+          printf '\nInstall: `uv tool install monash-study-kit` (PyPI: https://pypi.org/project/monash-study-kit/%s/)\n' "$v" >> notes.md
+          gh release create "v$v" dist/* --title "v$v" --notes-file notes.md --verify-tag

monash_study_kit-1.2.0/.github/workflows/test.yml

@@ -0,0 +1,71 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:      # release.yml 发版前先跑一遍
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.10", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e  # v6
+      - run: uv sync --python ${{ matrix.python }}
+      - name: ruff（语法错误、未定义的名字、没用的 import）
+        if: matrix.os == 'ubuntu-latest' && matrix.python == '3.13'
+        run: uvx ruff@0.6.9 check src tests
+      - run: uv run pytest -q
+      - name: CLI 能启动
+        run: uv run monash --version
+
+  package:
+    # 打出来的包装进一个干净的 venv 能不能用：只在仓库里 uv run 测不出漏打包的文件
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e  # v6
+      - name: 打包并检查内容
+        shell: bash
+        run: |
+          version=$(sed -n 's/^__version__ = "\(.*\)"/\1/p' src/monash_study_kit/__init__.py)
+          echo "VERSION=$version" >> "$GITHUB_ENV"
+          uv build
+          uv run --no-project scripts/check_dist.py dist "$version"
+      - name: 装进干净的 venv，跑 --version、help 和 MCP 握手
+        shell: bash
+        run: |
+          uv venv --python 3.10 smoke
+          if [ -d smoke/Scripts ]; then py=smoke/Scripts/python.exe exe=smoke/Scripts/monash.exe; else py=smoke/bin/python exe=smoke/bin/monash; fi
+          uv pip install --python "$py" dist/*.whl
+          "$py" scripts/smoke_test.py "$exe" "$VERSION"
+
+  version-bump:
+    # 朋友那边的更新提示比的是 main 上的 __version__：改了代码却没改版本号，他们就收不到提示
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4
+        with:
+          fetch-depth: 0
+      - name: 改了 src/ 就要改版本号
+        run: |
+          base=origin/${{ github.base_ref }}
+          if git diff --quiet "$base"...HEAD -- src/; then
+            echo "没改 src/，不用改版本号"; exit 0
+          fi
+          old=$(git show "$base":src/monash_study_kit/__init__.py | sed -n 's/^__version__ = "\(.*\)"/\1/p')
+          new=$(sed -n 's/^__version__ = "\(.*\)"/\1/p' src/monash_study_kit/__init__.py)
+          echo "main: $old  →  这个 PR: $new"
+          python3 -c "import sys; p=lambda v: tuple(int(x) for x in v.split('.')); sys.exit(0 if p('$new') > p('$old') else 1)" \
+            || { echo "::error file=src/monash_study_kit/__init__.py::改了 src/ 就把 __version__ 加一（修 bug 加最后一位，加功能加中间一位），不然朋友收不到更新提示"; exit 1; }

monash_study_kit-1.2.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+dist/
+build/
+*.egg-info/

monash_study_kit-1.2.0/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+Version numbers follow `__version__` in `src/monash_study_kit/__init__.py`: patch for bug fixes, minor for new features.
+
+## 1.2.0
+
+- `monash connect <client>` connects Study Kit to Codex, Cursor, VS Code, Windsurf or Gemini CLI in one command. It adds only the `monash` entry with the full path to the program, keeps the rest of the config file and saves a backup first. Codex uses `codex mcp add` when the `codex` command is installed. `monash connect` alone lists the clients and whether each is connected, `--print` shows the entry without writing it, and `--remove` takes it out. A config file that isn't plain JSON (for example with comments) is left alone and the entry is printed to paste by hand.
+- `monash uninstall` also removes the entry from those clients.
+
+## 1.1.1
+
+`monash doctor --deep` on my server reported four problems that weren't real. Fixed in the checks, no change to syncing:
+
+- "Never synced" on a deployment that syncs Moodle with its own script: the last sync time now falls back to the one stored in the Moodle database when `status.json` has none (`doctor`, `monash status`).
+- Files the teacher made available but hidden from the course page (Moodle "stealth" activities) were counted as missing. Sync follows the course page, so these are skipped.
+- Videos served from CloudFront were counted as missing: the CloudFront address has no file extension, so the check now also looks at the Moodle file name, as sync does.
+- The search probe sometimes picked a word inside a link (for example a Google Docs ID in `links.md`), which the index stores as a different word. It now picks whole words outside links.
+- Ed posts changed after the last sync started are no longer reported as stale; the next sync picks them up.
+
+## 1.1.0
+
+The code that runs my own server deployment (moodle-sync on a VPS, and ed-digest) used to be a copy of this package and had drifted. Its fixes and features are now here, so both deployments install this package instead of carrying their own copy.
+
+- Full-text search also covers text files inside `.zip` archives (starter code, READMEs). A hit carries `inner`, which `read_file` takes directly.
+- `list_files` takes `since_days` to answer "what's new this week", and `monash todo` / `get_study_todo` list course files synced in the last N days.
+- Ed reading pages saved by ed-digest (`lesson_texts`) are indexed and searchable, and Ed hits carry the original link.
+- Calendar items from the subscription link get a clean activity name: Monash's "- Allocate+ ..." and "- CALLISTA: ..." suffixes are stripped.
+- Forum lists: a row without a discussion id (a pinned-section divider) is skipped instead of breaking the whole list.
+- A lecture transcript is hidden together with its video when the video is removed from Moodle.
+- Interrupted downloads: leftover `.dl-*` files are cleaned up at the start of each unit's sync, temporary names no longer end in `.part.part`, and a cut-off Zoom download is deleted.
+- `monash media` caches each video's fingerprint, so it no longer re-reads every transcribed video on each run.
+- Ed: replies under a deleted reply are kept, as Ed still shows them.
+- Saving the Moodle cookie or Ed token uses a per-process temporary file, so two MCP servers (Claude Desktop and Claude Code) refreshing at once can't clash.
+- Security fixes from a review of the whole package (`docs/security.md`):
+  - The Moodle cookie is only sent over the same scheme as `MOODLE_BASE_URL` (HTTPS), never to an `http://` link.
+  - The Ed token is no longer carried along if Ed ever redirects a request to another site.
+  - The login window talks to the browser over a pipe on macOS and Linux, so no DevTools port is open while you log in.
+  - `read_file` refuses text files over 30 MB and zip entries that unpack to more than that, and docx/pptx text is read with a size cap.
+  - `monash doctor` also hides `sesskey` values and scrubs error messages from checks that crash.
+  - Symlinks in the course-file folders that point outside them are no longer indexed.
+  - `read_file` refuses a file that was taken down on Moodle, even when asked for it by path.
+- `monash doctor --deep` cross-checks the tools against a second source: upcoming due dates against the iCal feed, the assignment overview page against the course structure, synced files against the course structure (lecture videos that are deliberately not downloaded are told apart), the search index against the files on disk plus a few real searches that must find their file again, and the latest Ed posts against the local copy. It only reads, and prints counts, unit codes, dates and activity ids, never titles, file names or grades.
+- Published on PyPI: install with `uv tool install monash-study-kit`. `monash update` installs from PyPI (falling back to GitHub), and the update notice checks PyPI first.
+- Releases are made by pushing a tag: CI checks the tag against `__version__` and this changelog, runs the tests, uploads with Trusted Publishing, installs the result back from PyPI on three OSes and creates the GitHub release. Every PR also installs the built wheel into a clean venv and runs `monash --version`, `monash help` and an MCP handshake. See `docs/releasing.md`.
+- New settings `name_limit` and `pdf_extractor` (`pypdf` or `pdftotext`). Every setting can also be overridden with `MONASH_KIT_<NAME>`, and `MONASH_KIT_DATA`, `MONASH_KIT_SECRETS`, `MONASH_KIT_ED_DATA` and `MONASH_KIT_ED_TOKEN` point the package at an existing server layout.
+
+## 1.0.3
+
+Fixes for things that went wrong halfway through a sync.
+
+- Ed Lessons: if one lesson's details fail to load (a 500 or a timeout), its saved slides and quiz questions are kept instead of being wiped until the next sync.
+- Ed Lessons: lessons that were deleted or hidden on Ed are removed from the local database and from `ed-files`, so search stops returning them.
+- Downloads cut off halfway: Ed lesson PDFs are now written to a `.part` file first, so a half file is never treated as finished, and Moodle downloads clean up their `.part` file instead of leaving it in the course folder.
+- Moodle files: files a teacher removed or re-uploaded under a new name are marked as removed after a clean sync, and drop out of `list_files`, `monash moodle ls`, search and `monash media`. The files stay on disk, and a file that comes back on Moodle is restored. Nothing is marked when any activity in the unit failed to load that run.
+- Ed posts: replies deleted on Ed are removed from the local copy the next time that post is fetched.
+- `monash todo` / `get_study_todo`: when Moodle can't be reached, the Ed half (lessons, announcements, unread replies) is still returned, with a note about what is missing.
+- Full-text index: one unreadable file (encrypted, truncated, deleted mid-sync) no longer stops the whole index run.
+- Word / PowerPoint text: `&amp;` and `&lt;` are decoded, and words split across formatting runs are joined, so searching "Monads" finds a slide written as "Mon" + "ads".
+- Course-notes websites: `robots.txt` is now respected (checked once a day per site).
+- MCP server: a malformed message gets a JSON-RPC error instead of crashing the server, and an unexpected error in the background loop is logged instead of silently stopping hourly sync and session refresh.
+- `monash config`: number settings accept decimals (`tz_offset 9.5` for Adelaide, `auto_sync_hours 0.5`), and a typo in a true/false setting is rejected instead of being read as false.
+- Login window: cookies are only taken from Moodle's own domain or its parent domains, matched on a dot boundary.
+- CI runs `ruff` for syntax errors, undefined names and unused imports.
+
+## 1.0.2
+
+- MCP tools renamed to a consistent `get_` / `list_` / `search_` / `read_` / `start_` / `sync_` scheme. The old names still work when called.
+
+## 1.0.1
+
+- Every MCP tool parameter has a short description, and tool descriptions say which related tool to use instead.
+
+## 1.0.0
+
+First stable release. See the [release notes](https://github.com/Waldo0926/monash-study-kit/releases/tag/v1.0.0).

monash_study_kit-1.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,7 @@
+# Code of conduct
+
+This project uses the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+In short: be kind and patient, assume good intent, and keep discussion about the code. Harassment, insults and personal attacks are not okay. Don't post anyone's personal information, including other students' names, posts or grades from Moodle or Ed.
+
+If something happens, contact the maintainer privately at wensx0926@gmail.com. Reports are kept confidential. The maintainer may remove comments, issues or pull requests that break these rules, and may block people who keep doing it.

monash_study_kit-1.2.0/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+Thanks for helping. Bug reports from other Monash students are the most useful thing, since every unit sets up Moodle a bit differently.
+
+## Reporting a bug
+
+Use the bug report form. Run `monash doctor` (or `monash doctor --deep` if something looks wrong in the results) and paste the output. It leaves out cookies, tokens and calendar links. Please don't paste unit materials, other students' posts or your grades.
+
+## Setting up
+
+```bash
+git clone https://github.com/Waldo0926/monash-study-kit
+cd monash-study-kit
+uv sync
+uv run pytest -q
+uvx ruff@0.6.9 check src tests scripts
+uv run monash --help
+```
+
+`uv run monash ...` uses your real data folder. To try things without touching it, set `MONASH_KIT_HOME` to an empty folder first.
+
+## Making a change
+
+- Keep it read-only. Tools must not submit, post or change anything on Moodle or Ed.
+- Add a test for the bug or feature. Tests never touch the network; save a trimmed HTML or JSON sample in the test instead.
+- Test samples must not contain real names, student ids, emails, cookies or tokens. Replace them with made-up values.
+- If you change anything under `src/`, bump `__version__` in `src/monash_study_kit/__init__.py` (last number for a fix, middle number for a feature) and add a line to `CHANGELOG.md`. CI checks this.
+- Code comments and CLI messages are in Chinese, docs are in English with a Chinese README. Follow whatever the file you're editing already does.
+- Bigger design choices go in [docs/adr](docs/adr) as a short record.
+
+CI runs the tests on macOS, Windows and Linux with Python 3.10 and 3.13, runs ruff, and installs the built package into a clean venv to check that `monash` and the MCP server start.
+
+Releases are made by the maintainer from a tag, see [docs/releasing.md](docs/releasing.md).
+
+## Code of conduct
+
+This project follows the [Code of Conduct](CODE_OF_CONDUCT.md).

monash_study_kit-1.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Waldo0926
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.