Enhance contributor documentation and VS Code extension setup

.github/workflows/ci.yml

@@ -25,5 +25,31 @@ jobs:
       - name: Install dependencies
         run: pip install -e . -r requirements-dev.txt
 
+      - name: Check release versions
+        run: python scripts/check_release_versions.py
+
       - name: Run tests
         run: pytest -q
+
+  highlighter:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: highlighter
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build extension
+        run: bun run build
+
+      - name: Package extension
+        run: bun run package

.gitignore

@@ -14,5 +14,6 @@ dist/
 build_test/
 highlighter/node_modules/
 highlighter/dist/
+highlighter/*.vsix
 npm/node_modules/
 npm/*.tgz

contributors.md

@@ -1,16 +1,190 @@
 # For Contributors
-If you want to contribute, look here.
 
-## Updating to new version of game
+This fork is maintained at [SpyC0der77/Minecraft-Script](https://github.com/SpyC0der77/Minecraft-Script). Upstream issues and PRs on [Bard-Gaming/Minecraft-Script](https://github.com/Bard-Gaming/Minecraft-Script) are not tracked here.
+
+## Local setup
+
+1. Clone the repository and install the Python package in editable mode:
+
+```commandline
+git clone https://github.com/SpyC0der77/Minecraft-Script.git
+cd Minecraft-Script
+pip install -e . -r requirements-dev.txt
+```
+
+2. Confirm the CLI works:
+
+```commandline
+python -m minecraft_script help
+```
+
+3. Optional — VS Code extension development (`highlighter/`):
+
+```commandline
+cd highlighter
+bun install
+bun run build
+```
+
+Open `highlighter/` in VS Code and press `F5` to launch an Extension Development Host.
+
+## Running tests
+
+From the repository root:
+
+```commandline
+pytest -q
+```
+
+CI runs the same suite on Python 3.10 and 3.12, plus a highlighter build check.
+
+Tests that compile datapacks write output to `build_test/` at the repo root. That folder is gitignored and cleaned up automatically by pytest fixtures.
+
+## Manual test compiles
+
+When checking compiler output by hand, compile into `build_test/` instead of your Minecraft world folder:
+
+```commandline
+python -m minecraft_script compile examples/starter_datapack.mcs "Starter Datapack" build_test
+```
+
+Or with the npm CLI:
+
+```commandline
+mcs compile examples/starter_datapack.mcs "Starter Datapack" build_test
+```
+
+Inspect the generated datapack under `build_test/` before deleting it.
+
+## Release flow
+
+PyPI is not used for this fork — only the original upstream owner can publish the `minecraft-script` package there. Releases are distributed through **GitHub tags** and **npm**.
+
+### Before you release
+
+1. Merge changes to `main` and confirm CI is green.
+2. Bump the version in both:
+   - `pyproject.toml` (`[project].version`)
+   - `npm/package.json` (`version`)
+3. Verify the versions match:
+
+```commandline
+python scripts/check_release_versions.py
+```
+
+4. Commit the version bump (for example: `Release v0.3.5.`).
+
+### Tag and GitHub release
+
+```commandline
+git tag v0.3.5
+git push origin main
+git push origin v0.3.5
+```
+
+Create a GitHub release from the tag on [SpyC0der77/Minecraft-Script/releases](https://github.com/SpyC0der77/Minecraft-Script/releases). Use the tag name as the release title (for example `v0.3.5`).
+
+The npm wrapper installs the matching Python package with:
+
+```commandline
+pip install git+https://github.com/SpyC0der77/Minecraft-Script.git@v<version>
+```
+
+So the GitHub tag must exist before users install that npm version.
+
+### Publish to npm
+
+From the `npm/` directory:
+
+```commandline
+cd npm
+npm publish
+```
+
+You must be logged in (`npm login`) and have publish access to the `minecraft-script` package on npm.
+
+After publishing, users can install with:
+
+```commandline
+npm install -g minecraft-script
+```
+
+### Release checklist
+
+- [ ] CI green on `main`
+- [ ] `pyproject.toml` and `npm/package.json` versions match
+- [ ] `python scripts/check_release_versions.py` passes
+- [ ] Tag pushed (`v<version>`)
+- [ ] GitHub release created from the tag
+- [ ] `npm publish` from `npm/` succeeded
+
+The VS Code extension (`highlighter/`) uses publisher **`SpyC0der77`** and is published to the Marketplace separately — see [Publishing the VS Code extension](#publishing-the-vs-code-extension).
+
+## Publishing the VS Code extension
+
+The highlighter lives in `highlighter/`. It is not published automatically with the Python/npm release.
+
+### One-time setup
+
+1. **Create a Marketplace publisher**
+   - Go to [Visual Studio Marketplace publisher management](https://marketplace.visualstudio.com/manage).
+   - Sign in with a Microsoft account.
+   - Your publisher ID is **`SpyC0der77`** (must match `"publisher"` in `highlighter/package.json`).
+
+2. **Create a Personal Access Token (PAT)**
+   - Open [Azure DevOps](https://dev.azure.com/) → User settings → Personal access tokens.
+   - Create a token with **Marketplace → Manage** scope.
+   - Save the token somewhere safe; you only see it once.
+
+3. **Install dependencies** (if you have not already):
+
+```commandline
+cd highlighter
+bun install
+```
+
+Packaging metadata (`.vscodeignore`, `icon.png`, `CHANGELOG.md`, `LICENSE`, and `bun run package`) is already set up in the repo.
+
+### Each release
+
+1. Bump `"version"` in `highlighter/package.json` (semver, independent of the Python/npm `0.3.x` line).
+2. Update `highlighter/CHANGELOG.md`.
+3. Build, package, and smoke-test locally:
+
+```commandline
+cd highlighter
+bun run package
+```
+
+Install the generated `.vsix` with **Extensions: Install from VSIX** in VS Code, or press `F5` in the `highlighter/` folder to test in the Extension Development Host.
+
+4. Log in and publish:
+
+```commandline
+bunx vsce login SpyC0der77
+bunx vsce publish --no-dependencies
+```
+
+When prompted for the PAT, paste the token from Azure DevOps.
+
+5. Confirm the listing at [marketplace.visualstudio.com/items?itemName=SpyC0der77.minecraft-script-language-support](https://marketplace.visualstudio.com/items?itemName=SpyC0der77.minecraft-script-language-support).
+
+### Updating an existing listing
+
+Bump `highlighter/package.json` version, rebuild, and run `vsce publish` again. Marketplace users receive updates automatically through VS Code.
+
+## Updating to a new version of Minecraft
+
 If you are trying to add compatibility for a new version of Minecraft, here is how you can do it.
 
- 1. Find breaking changes from the [Datapack breaking changes](https://datapack.wiki/wiki/info/breaking-changes) page
- 2. Copy `minecraft_script/versions/1.21.2.json` to `minecraft_script/versions/<version>.json`
- 3. Update the `orchestration` section for datapack layout changes (folder names, `pack.mcmeta` format, function tags, MCS built-in feature paths). See the `breaking_changes` map in the JSON for which keys apply per game version.
- 4. Update Handlebars `templates` only for compiler-generated command shapes (not user NBT in `.mcs` source).
- 5. Copy `minecraft_script/compiler/build_templates/math/1.20.4/` (and `builtins/`, `tags/`) to matching `<version>/` folders; edit predefined `.mcfunction` files as needed
- 6. Add the version to `minecraft_script/versions/index.json`
- 7. Create PR to merge into main branch
+1. Find breaking changes from the [Datapack breaking changes](https://datapack.wiki/wiki/info/breaking-changes) page
+2. Copy `minecraft_script/versions/1.21.2.json` to `minecraft_script/versions/<version>.json`
+3. Update the `orchestration` section for datapack layout changes (folder names, `pack.mcmeta` format, function tags, MCS built-in feature paths). See the `breaking_changes` map in the JSON for which keys apply per game version.
+4. Update Handlebars `templates` only for compiler-generated command shapes (not user NBT in `.mcs` source).
+5. Copy `minecraft_script/compiler/build_templates/math/1.21.2/` (and `builtins/1.21.2/`, `tags/1.21.2/`) to matching `<version>/` folders; edit predefined `.mcfunction` files as needed
+6. Add the version to `minecraft_script/versions/index.json`
+7. Add the version to `highlighter/package.json` → `contributes.configuration.properties.mcsHighlighter.minecraftVersion.enum` if command linting should support it
+8. Open a PR against `main`
 
 Users switch versions with `config set minecraft_version <version>` (default is in `versions/index.json`).
 

highlighter/.vscodeignore

@@ -0,0 +1,12 @@
+*
+**/*
+
+!dist/*.js
+!syntaxes/
+!syntaxes/**
+!language-configuration.json
+!package.json
+!README.md
+!CHANGELOG.md
+!LICENSE
+!icon.png

highlighter/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Change Log
+
+All notable changes to the Minecraft Script Language Support extension are documented here.
+
+## [0.0.1] - 2026-06-07
+
+### Added
+
+- Syntax highlighting for Minecraft Script (`.mcs`) files
+- Hover documentation for keywords, built-in functions, text components, and target selectors
+- Command linting, completion, and hover inside literal `command("...")` and `command('...')` strings via Spyglass
+- Configurable Minecraft version for command validation (`mcsHighlighter.minecraftVersion`)
+- Commands: **Minecraft Script: Select Command Lint Version** and **Minecraft Script: Show Output**

highlighter/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Minecraft Script contributors
+
+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.

highlighter/README.md

@@ -1,28 +1,48 @@
-# Minecraft Script Highlighter
+# Minecraft Script Language Support
 
-VS Code language support for Minecraft Script `.mcs` files.
+Language support for [Minecraft Script](https://github.com/SpyC0der77/Minecraft-Script) `.mcs` files in VS Code.
 
-## Try It Locally
+## Features
 
-1. Open the `highlighter/` folder in VS Code.
-2. Run `bun install` if you have not already.
-3. Press `F5` to build and launch an Extension Development Host.
-4. Open a `.mcs` file in the Extension Development Host.
+- **Syntax highlighting** for MCS keywords, selectors, resource locations, built-in helpers, text components, and `command()` strings
+- **Hover help** for keywords, built-in functions, text component methods, and target selectors (`@a`, `@s`, …)
+- **Command linting and completion** inside literal `command("...")` and `command('...')` calls via [Spyglass](https://github.com/SpyglassMC/Spyglass)
+- **Version picker** for command validation across supported Minecraft releases
+
+## Commands
 
-If command linting fails, open the **Minecraft Script** output channel: in the Output panel, use the dropdown on the right (it may say "Tasks") and select **Minecraft Script**. You can also run **Minecraft Script: Show Output** from the command palette. The first run downloads Minecraft command data from the network.
+| Command | Description |
+| --- | --- |
+| **Minecraft Script: Select Command Lint Version** | Choose the Minecraft version Spyglass uses for command validation |
+| **Minecraft Script: Show Output** | Open the Minecraft Script output channel (useful if linting fails on first run) |
 
-The grammar highlights Minecraft Script-specific syntax such as `set`, `on`, selector-prefixed calls, event bindings, built-in helpers, text component chains, Minecraft resource locations, and `command()` strings. It still includes VS Code's JavaScript grammar as a fallback for JavaScript-like expressions.
+## Settings
 
-Hover over keywords, built-in functions, text component methods (`.text()`, `.color()`, etc.), and target selectors (`@a`, `@s`, ...) to see TypeScript-style syntax help.
+| Setting | Default | Description |
+| --- | --- | --- |
+| `mcsHighlighter.minecraftVersion` | `1.21.2` | Minecraft version used when linting literal `command()` strings |
 
-The small command-name keyword list used inside `command()` strings targets the default `1.21.2` lint version. Full command validation comes from Spyglass and follows the version selected with `Minecraft Script: Select Command Lint Version`.
+The first lint run downloads Minecraft command data from the network. Dynamic commands such as `command(myVar)` are skipped because their final text is not known in the editor.
 
 ## Spyglass
 
-This extension uses Spyglass only for Minecraft command linting inside literal `command("...")` and `command('...')` calls. It does not register `.mcs` files as `.mcfunction`, and it does not enable Spyglass diagnostics across the whole MCS document.
+This extension uses Spyglass only for Minecraft command linting inside literal `command()` strings. It does not register `.mcs` files as `.mcfunction`, and it does not enable Spyglass diagnostics across the whole MCS document.
+
+Spyglass is MIT licensed: [SpyglassMC/Spyglass](https://github.com/SpyglassMC/Spyglass).
+
+## Development
+
+To work on the extension locally:
+
+1. Open the `highlighter/` folder in VS Code.
+2. Run `bun install`.
+3. Run `bun run build` (or press `F5` to build and launch an Extension Development Host).
+4. Open a `.mcs` file in the Extension Development Host.
 
-Dynamic command values such as `command(cmd)` are skipped because their final command text is not available to the editor.
+To package a `.vsix` without publishing:
 
-Use the `Minecraft Script: Select Command Lint Version` command from the VS Code command menu to choose the Minecraft version used by Spyglass. The command updates `mcsHighlighter.minecraftVersion` and re-lints open `.mcs` files.
+```commandline
+bun run package
+```
 
-Spyglass is MIT licensed and available at [SpyglassMC/Spyglass](https://github.com/SpyglassMC/Spyglass). See `../spyglass/LICENSE` for the original license text and copyright notice.
+See [contributors.md](../contributors.md) for the full Marketplace publishing flow.