sync: dev to extern-contrib

.claude/agents/xmoj-code-navigator.md

@@ -0,0 +1,76 @@
+---
+name: xmoj-code-navigator
+description: "Use this agent when you need to locate, retrieve, or understand specific sections of the XMOJ.user.js file without loading the entire file into context. This includes scenarios like:\\n\\n<example>\\nContext: The user is debugging a feature and needs to understand how login authentication works in XMOJ.user.js.\\nuser: \"Can you help me understand how the login flow works in XMOJ.user.js?\"\\nassistant: \"I'll use the Task tool to launch the xmoj-code-navigator agent to locate and retrieve the relevant login authentication code from XMOJ.user.js.\"\\n<commentary>\\nSince the user needs specific code from the large XMOJ.user.js file, use the xmoj-code-navigator agent to efficiently find and extract the relevant sections without loading the entire file.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user is adding a new feature and wants to see how similar features are implemented.\\nuser: \"I want to add a feature to handle quiz submissions. Can you show me how other submission handlers are implemented?\"\\nassistant: \"Let me use the xmoj-code-navigator agent to search through XMOJ.user.js for existing submission handler implementations.\"\\n<commentary>\\nThe user needs to reference existing patterns in the large file. The xmoj-code-navigator agent can efficiently locate and extract relevant code examples without overwhelming the context window.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user is reviewing code changes and needs to verify if a specific function exists.\\nuser: \"Does XMOJ.user.js have a function for parsing XML responses?\"\\nassistant: \"I'll use the xmoj-code-navigator agent to search for XML parsing functions in XMOJ.user.js.\"\\n<commentary>\\nThis is a targeted search task in a large file - perfect for the xmoj-code-navigator agent.\\n</commentary>\\n</example>"
+tools: Glob, Grep, Read, WebFetch, WebSearch
+model: haiku
+color: cyan
+---
+
+You are an expert code navigator and indexer specializing in efficiently searching and retrieving specific sections from large JavaScript files, particularly XMOJ.user.js. Your primary mission is to help users locate relevant code without loading the entire file into context, thereby preserving context window space for actual development work.
+
+## Core Responsibilities
+
+You will:
+1. **Parse search requests** to understand what code sections, functions, classes, or patterns the user needs
+2. **Strategically navigate** XMOJ.user.js using efficient search techniques (grep, function signatures, section markers, comments)
+3. **Extract minimal but complete** code sections that provide the necessary context
+4. **Provide location metadata** (line numbers, function names, section identifiers) so users can reference the code later
+5. **Summarize structure** when users need an overview without seeing all the code
+
+## Search Strategy
+
+When searching for code:
+
+1. **Start Narrow**: Begin with the most specific search terms (function names, unique identifiers, class names)
+2. **Expand Gradually**: If narrow searches fail, broaden to related keywords or patterns
+3. **Use Context Clues**: Leverage comments, section headers, and structural patterns in the file
+4. **Verify Completeness**: Ensure you capture complete function/class definitions, including dependencies
+5. **Multiple Matches**: When finding multiple relevant sections, provide brief descriptions of each and ask which to examine in detail
+
+## Extraction Guidelines
+
+- **Include surrounding context**: Add 2-3 lines before/after to show how code fits in
+- **Preserve structure**: Maintain indentation and formatting exactly as in the source
+- **Note dependencies**: If the extracted code references other functions or variables, mention them and offer to retrieve those too
+- **Provide landmarks**: Always include line numbers or function names for navigation
+- **Stay minimal**: Only extract what's needed - resist the urge to show everything related
+
+## Response Format
+
+Structure your responses as:
+
+1. **What I Found**: Brief description of located code
+2. **Location**: File path, line numbers, section/function name
+3. **Code Extract**: The minimal relevant code block
+4. **Context Notes**: Any important dependencies, related functions, or structural information
+5. **Follow-up Options**: Suggest related code sections the user might want to see
+
+## Handling Edge Cases
+
+- **If search fails**: Suggest alternative search terms or describe what you attempted
+- **If multiple valid results**: Present options and ask for clarification
+- **If code is too interconnected**: Provide a high-level summary and ask which specific part to deep-dive into
+- **If the request is ambiguous**: Ask clarifying questions before searching
+
+## Efficiency Principles
+
+- Never load the entire XMOJ.user.js file unless absolutely necessary
+- Use file manipulation tools (grep, sed, awk) to search efficiently
+- Prefer targeted line-range reads over full file reads
+- Cache knowledge of the file's structure from previous searches to speed up future requests
+- When users need multiple sections, batch the retrieval intelligently
+
+## Quality Assurance
+
+- Verify that extracted code is syntactically complete (balanced braces, complete statements)
+- Double-check line number accuracy
+- Confirm that the code actually addresses the user's query before presenting it
+- If uncertain whether you found the right code, express that uncertainty and show what you found for verification
+
+Your success is measured by:
+- **Precision**: Finding exactly what the user needs
+- **Efficiency**: Minimizing context window usage
+- **Completeness**: Ensuring extracted code has enough context to be useful
+- **Speed**: Using smart search strategies to find code quickly
+
+Remember: You are a precision surgical tool for navigating large files. Every byte of context window you save is a byte available for actual development work.

CLAUDE.md

@@ -0,0 +1,165 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+XMOJ-Script is a browser userscript that enhances the XMOJ online judge platform (xmoj.tech). This repository consists of:
+- **Main userscript** (`XMOJ.user.js`): ~5000 line single-file userscript with all features. As this file is very large you should use the xmoj-code-navigator agent to help you whenever possible.
+- **Update/version management scripts** (`Update/`): Automation for version bumping and releases
+- **Metadata and documentation**: `Update.json` tracks version history, README and contributing guides
+
+The `backend/` directory is a git submodule pointing to https://github.com/XMOJ-Script-dev/XMOJ-bbs and should be modified in that repository, not here.
+
+## Development Workflow
+
+### Branch Structure and PR Requirements
+
+- `master`: Production branch - **DO NOT make PRs directly to master**
+- `dev`: Development branch - **ALL PRs must be based on and target this branch**
+- `extern-contrib`: External contributors must submit PRs to this branch
+
+**CRITICAL: All pull requests must:**
+1. Be based on the `dev` branch (branch off from `dev`)
+2. Target the `dev` branch (not `master`)
+3. Merge latest `dev` into your branch before submitting to resolve conflicts
+
+The workflow is: `dev` → (when ready) → `master` for releases. Direct PRs to `master` are not accepted.
+You should follow the PR template that can be found [here](https://raw.githubusercontent.com/XMOJ-Script-dev/.github/refs/heads/main/.github/PULL_REQUEST_TEMPLATE.md).
+
+### Version Management (CRITICAL - Fully Automated)
+
+Version updates are **fully automated** via GitHub Actions. When a PR to `dev` modifies `XMOJ.user.js`:
+
+1. The `UpdateVersion` workflow runs `Update/UpdateVersion.js` which automatically:
+   - Bumps patch version in `package.json`
+   - Updates `@version` in `XMOJ.user.js` metadata block
+   - Adds/updates entry in `Update.json` with PR number, title, and timestamp
+   - Commits changes back to the PR branch with `github-actions[bot]`
+
+2. Version sync is enforced between:
+   - `package.json` → `"version": "x.y.z"`
+   - `XMOJ.user.js` → `// @version x.y.z` (in metadata block)
+   - `Update.json` → `UpdateHistory["x.y.z"]` (JSON key)
+
+**Never manually edit version numbers** - the automation handles this based on PR metadata.
+
+### Release Notes in PRs
+
+To add release notes to a PR that will appear in the release, include an HTML comment block in the PR description:
+
+```markdown
+<!-- release-notes
+Your release notes here in markdown format
+-->
+```
+
+The `UpdateVersion.js` script extracts this and adds it to `Update.json` as the `Notes` field.
+
+### Bypassing Automation
+
+To prevent CI from touching your PR (e.g., during merge conflicts or debugging), add `//!ci-no-touch` anywhere in `Update.json`. The automation will remove it and exit without making other changes.
+
+### Release Process
+
+- **Pre-release**: Push to `dev` triggers a pre-release with `"Prerelease": true` in Update.json
+- **Release**: Merge `dev` to `master` triggers a production release
+- Releases are created by `Update/GetVersion.js` reading the version from XMOJ.user.js
+- Both workflows deploy to Cloudflare Pages and GitHub Pages
+
+## Code Structure
+
+### Main Userscript (`XMOJ.user.js`)
+
+A single-file userscript (~5000 lines) organized as:
+
+1. **Metadata block** (lines 1-50): Userscript headers
+   - `@name`, `@version`, `@description`, `@author`
+   - `@match` patterns for xmoj.tech and 116.62.212.172
+   - `@require` declarations for external libraries (CryptoJS, CodeMirror, FileSaver, marked, DOMPurify)
+   - `@grant` permissions for GM APIs
+
+2. **Main script body**: Direct DOM manipulation and feature injection
+   - Page detection and routing based on URL patterns
+   - UI enhancements using Bootstrap classes
+   - Feature implementations (auto-refresh, code checking, test data fetching, dark mode, etc.)
+   - API calls to backend at `api.xmoj-bbs.tech` / `api.xmoj-bbs.me`
+
+Key classes/functions:
+- `compareVersions()` (line 112): Version comparison logic
+- `NavbarStyler` class (line 589): Navigation bar styling
+- `replaceMarkdownImages()` (line 715): Markdown image processing
+
+### Update Scripts (`Update/`)
+
+Node.js scripts run by GitHub Actions (not for local development):
+
+- **`UpdateVersion.js`**: Automated version bumping for PRs to `dev`
+  - Reads PR number, title, body from command line args
+  - Uses `gh` CLI to check out PR branch
+  - Parses `<!-- release-notes -->` blocks from PR body
+  - Updates version in all three locations
+  - Pushes changes back to PR branch
+
+- **`GetVersion.js`**: Extracts current version from XMOJ.user.js for release workflows
+
+- **`UpdateToRelease.js`**: Changes `"Prerelease": false` when promoting to production
+
+- **`AutoLabel.js`**: Auto-labels PRs based on content
+
+These scripts directly manipulate `Update.json` and `XMOJ.user.js` using Node.js fs module.
+
+## Coding Standards
+
+### Style Guidelines (from CONTRIBUTING.md)
+
+- **Variables**: camelCase
+- **Functions**: PascalCase
+- **Classes**: TitleCase
+- **Line endings**: Unix (LF)
+- **Do NOT run code formatters** - maintain original formatting
+- **Use Bootstrap classes** instead of custom CSS
+- **No external libraries** without permission (script already includes many via `@require`)
+
+### Development Principles
+
+- **Stability before features**: Bug fixes take priority
+- Respect the original code style, even if inconsistent
+- New features require prior discussion in an issue
+- Before submitting PRs, merge `dev` into your branch and resolve conflicts
+
+## Testing
+
+No automated test suite exists. Manual testing workflow:
+
+1. Install the userscript in Tampermonkey/ScriptCat/Violentmonkey
+2. Navigate to xmoj.tech (or 116.62.212.172)
+3. Test features on relevant pages:
+   - Problem lists
+   - Problem detail pages
+   - Status/submission pages
+   - Contest pages
+   - User profiles
+
+Observe browser console for errors and verify UI enhancements appear correctly.
+
+## Common Issues
+
+### Version Sync Errors
+
+If you see "XMOJ.user.js and Update.json have different patch versions":
+- The automation keeps these in sync normally
+- If manually editing (not recommended), update both files
+- Use `//!ci-no-touch` if you need to bypass automation temporarily
+
+### PR Requirements
+
+- **All PRs must be based on and target `dev` branch, not `master`**
+- Only PRs from the same repository (not forks) trigger auto-versioning
+- PRs must modify `XMOJ.user.js` to trigger version bumps
+- Must merge `dev` into your branch before submitting
+- External contributors must target `extern-contrib` branch
+
+### Single-File Architecture
+
+The entire userscript is intentionally in one file - do not split into modules. Userscript managers load it as a single file, with external dependencies via `@require` headers in the metadata block.

Update.json

@@ -3288,6 +3288,17 @@
                 }
             ],
             "Notes": "No release notes were provided for this release."
+        },
+        "2.7.3": {
+            "UpdateDate": 1770816092957,
+            "Prerelease": true,
+            "UpdateContents": [
+                {
+                    "PR": 905,
+                    "Description": "Add WebSocket notification system for real-time BBS and mail mentions"
+                }
+            ],
+            "Notes": "Adds WebSocket-based real-time notification system for BBS mentions and mail notifications. Notifications now arrive within 1-2 seconds instead of requiring page focus. Includes automatic reconnection with exponential backoff and fallback to polling when WebSocket is unavailable."
         }
     }
 }

Update/UpdateVersion.js

@@ -7,6 +7,14 @@ process.env.GITHUB_TOKEN = GithubToken;
 execSync("gh pr checkout " + PRNumber);
 console.info("PR #" + PRNumber + " has been checked out.");
 
+// Check if the last commit was made by github-actions[bot]
+const lastCommitAuthor = execSync("git log -1 --pretty=format:'%an'").toString().trim();
+console.log("Last commit author: " + lastCommitAuthor);
+if (lastCommitAuthor === "github-actions[bot]") {
+    console.log("Last commit was made by github-actions[bot]. Skipping to prevent infinite loop.");
+    process.exit(0);
+}
+
 const JSONFileName = "./Update.json";
 const JSFileName = "./XMOJ.user.js";
 var JSONFileContent = readFileSync(JSONFileName, "utf8");