Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@ python3 install_plugin.py ../MyRPGProject
* 更新 `js/plugins.js` 以啟用外掛。
* 自動搜尋專案根目錄下的 JSON 翻譯檔(如 `A翻譯.json`),並將其安裝為預設中文翻譯 (`translations/zh.json`)。

自動註冊支援 RPG Maker 產生的 JSON 外掛清單,並保留前後的註解及既有外掛設定。若清單包含自訂 JavaScript 運算式、陣列內註解、尾端逗號或格式錯誤,腳本會保留 `plugins.js` 原文並以非零狀態結束;此外掛檔案可能已複製,請改用下方的手動註冊方式。

### 📦 手動安裝

如果您無法使用腳本,也可以手動安裝:
Expand Down
52 changes: 52 additions & 0 deletions docs/research/plugin-registration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# Safe plugin registration

Checked 2026-11-04 against PR #5 head `5cd013fd3bc636bdc6e2d13fcf8cdd1f9bc6e906`.

## Reproduction and decision

The existing 31 installer tests pass. Two authored valid JavaScript fixtures fail:
`var $plugins = [];\n// documentation [optional]\n` is corrupted because the
installer inserts before the last `]` in the entire file. A leading comment
containing `{"name": "DynamicTranslation"}` prevents registration even though
the actual plugin array is empty. Nested parameter objects can likewise match
the whole-file registration regex.

Use the existing Python standard library rather than add a JavaScript parser.
Recognize only an optional leading BOM/comments, followed by a bare JSON array
or `var`/`let`/`const $plugins =` and a JSON array. Decode that array and use the
returned end offset for insertion. Check names only on top-level plugin entries.
Require the array to end the assignment (only comments/whitespace before a
semicolon or EOF), so array-starting expressions such as `[].concat(...)`
cannot be mistaken for a supported JSON value.
Preserve the prefix/suffix and existing registrations. Unsupported or malformed
arrays are left unchanged, with a diagnostic; arbitrary JavaScript expressions,
comments within JSON arrays and JavaScript trailing commas are not supported.
The CLI exits nonzero on parse failure instead of claiming installation completed.
The plugin file has already been copied at that point; no rollback or fully
transactional installation is claimed. The existing missing-plugins.js warning
policy remains unchanged.

## Upstream evidence

Targeted connected GitHub search: `raw_decode` in `python/cpython`. Read
`JSONDecoder.raw_decode` in
[Lib/json/decoder.py](https://github.com/python/cpython/blob/3d6d2a63a23ee4d340ed8df6de0bd70ef175c4cf/Lib/json/decoder.py):
it returns the decoded object and the absolute document-end index, including
when other text follows. It raises JSONDecodeError when no document starts at
the supplied offset. This is precisely the array-boundary primitive needed;
calling `json.loads` on the entire JavaScript file would reject the assignment
and comments. A custom last-bracket scan remains incorrect for strings/comments.

[CPython LICENSE](https://github.com/python/cpython/blob/3d6d2a63a23ee4d340ed8df6de0bd70ef175c4cf/LICENSE)
identifies the PSF License Version 2. The change directly uses the standard-library
API; no upstream implementation is copied or vendored. The repository currently
declares ISC in package.json and has no root license file, so this note does not
assert additional distribution rights for unrelated project files.

## Validation

Run the complete Python installer suite, regression negative controls against
the pre-fix implementation, Python syntax compilation, Node syntax checks, and
an actual installer subprocess followed by Node evaluation of the authored
plugin list. Existing Jest coverage is separate from a real RPG Maker runtime;
no game, paid translation API, or real user content is accessed.
52 changes: 36 additions & 16 deletions install_plugin.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
import os
import shutil
import json
import re
from pathlib import Path

PLUGIN_CONFIG = {
Expand Down Expand Up @@ -89,31 +90,46 @@ def update_plugins_js(target_dir):
return

print("Updating plugins.js...")
with open(plugins_js_path, "r", encoding="utf-8") as f:
with open(plugins_js_path, "r", encoding="utf-8", newline="") as f:
content = f.read()

if '"name":"DynamicTranslation"' in content:
# RPG Maker emits a JSON array after an assignment and optional comments.
# Parse that array, not brackets or name-like text in comments/parameters.
trivia_pattern = r'(?:\s+|//[^\r\n]*(?:\r\n?|\n|$)|/\*.*?\*/)*'
prefix_match = re.match(
r'\A\ufeff?' + trivia_pattern +
r'(?:(?:var|let|const)\s+\$plugins\s*=\s*)?',
content,
re.DOTALL,
)
array_start = prefix_match.end()
try:
if content[array_start:array_start + 1] != "[":
raise ValueError("expected a JSON plugin array")
plugins, array_end = json.JSONDecoder().raw_decode(content, array_start)
if not all(isinstance(plugin, dict) for plugin in plugins):
raise ValueError("plugin entries must be objects")
suffix = content[array_end:]
trivia_end = re.match(trivia_pattern, suffix, re.DOTALL).end()
if suffix[trivia_end:] and suffix[trivia_end] != ";":
raise ValueError("expected the JSON array to end the assignment")
except (ValueError, RecursionError) as error:
print(f"Error: Could not parse plugins.js ({error}). File left unchanged.")
return False

if any(plugin.get("name") == "DynamicTranslation" for plugin in plugins):
print("DynamicTranslation is already in plugins.js. Skipping update.")
return

plugin_string = json.dumps(PLUGIN_CONFIG, ensure_ascii=False)

# Find the last closing bracket
last_bracket_index = content.rfind("]")
if last_bracket_index == -1:
print("Error: Could not parse plugins.js (could not find closing bracket).")
return

before_bracket = content[:last_bracket_index].rstrip()
after_bracket = content[last_bracket_index:]

# Check if we need a comma: if before_bracket not empty and last char != '['
needs_comma = bool(before_bracket) and before_bracket[-1] != "["
prefix = ", " if needs_comma else ""
before_bracket = content[:array_end - 1].rstrip()
after_bracket = content[array_end - 1:]
prefix = ", " if plugins else ""

new_content = f"{before_bracket}\n{prefix}{plugin_string}\n{after_bracket}"

with open(plugins_js_path, "w", encoding="utf-8") as f:
with open(plugins_js_path, "w", encoding="utf-8", newline="") as f:
f.write(new_content)
print("plugins.js updated successfully.")

Expand Down Expand Up @@ -165,7 +181,11 @@ def main():
print(f"Target directory: {target_dir}")

copy_plugin_file(script_dir, www_dir)
update_plugins_js(www_dir)
if update_plugins_js(www_dir) is False:
raise SystemExit(
"Registration failed; plugins.js was not changed. "
"Use RPG Maker's Plugin Manager for manual registration."
)
install_translation(target_dir, www_dir)

print("Installation complete!")
Expand Down
165 changes: 164 additions & 1 deletion tests/test_install_plugin.py
Original file line number Diff line number Diff line change
Expand Up @@ -215,7 +215,7 @@ def test_adds_plugin_to_existing_list(self, tmp_path):

def test_skips_when_plugin_already_registered(self, tmp_path, capsys):
_make_rpg_project(tmp_path)
# Use compact format - install_plugin checks for '"name":"DynamicTranslation"'
# Keep support for the compact format emitted by RPG Maker.
(tmp_path / "www" / "js").mkdir(parents=True, exist_ok=True)
plugins_path = tmp_path / "www" / "js" / "plugins.js"
plugins_path.write_text('[{"name":"DynamicTranslation","status":true}]', encoding="utf-8")
Expand All @@ -229,6 +229,51 @@ def test_skips_when_plugin_already_registered(self, tmp_path, capsys):
out = capsys.readouterr().out.lower()
assert "skipping" in out

@pytest.mark.parametrize("indent", [None, 2])
def test_skips_existing_registration_with_json_whitespace(self, tmp_path, indent):
_make_rpg_project(tmp_path)
plugins_path = tmp_path / "www" / "js" / "plugins.js"
existing = [{
"name": "DynamicTranslation",
"status": False,
"parameters": {"Default Language": "ja"},
}]
content = "var $plugins = " + json.dumps(existing, indent=indent) + ";\n"
plugins_path.write_text(content, encoding="utf-8")

from install_plugin import update_plugins_js

update_plugins_js(str(tmp_path / "www"))

# Existing status, user parameters and formatting must stay untouched.
assert plugins_path.read_text(encoding="utf-8") == content

@pytest.mark.parametrize("with_other_plugin", [False, True])
def test_repeated_registration_is_idempotent(self, tmp_path, with_other_plugin):
_make_rpg_project(tmp_path)
existing = (
[{"name": "OtherPlugin", "status": True}] if with_other_plugin else []
)
plugins_path = _make_plugins_js(tmp_path, existing)
plugins_path.write_text(
"var $plugins = " + plugins_path.read_text(encoding="utf-8") + ";\n",
encoding="utf-8",
)

from install_plugin import update_plugins_js

update_plugins_js(str(tmp_path / "www"))
first_install = plugins_path.read_text(encoding="utf-8")
update_plugins_js(str(tmp_path / "www"))
second_install = plugins_path.read_text(encoding="utf-8")

assert second_install == first_install
entries = json.loads(
second_install.removeprefix("var $plugins = ").rstrip(";\n")
)
assert sum(entry["name"] == "DynamicTranslation" for entry in entries) == 1
assert len(entries) == len(existing) + 1

def test_handles_missing_plugins_js(self, tmp_path, capsys):
_make_rpg_project(tmp_path)
plugins_js = tmp_path / "www" / "js" / "plugins.js"
Expand All @@ -241,6 +286,124 @@ def test_handles_missing_plugins_js(self, tmp_path, capsys):
out = capsys.readouterr().out
assert "Warning" in out

@pytest.mark.parametrize("suffix", [
";\n// documentation [optional]\n",
";\n/* preserve [this] comment */\n",
';\nconst audit = ["preserved"];\n',
' /* preserve comment before semicolon */;\n',
])
def test_inserts_into_plugin_array_not_trailing_brackets(self, tmp_path, suffix):
_make_rpg_project(tmp_path)
plugins_path = _make_plugins_js(tmp_path)
prefix = "// Generated by RPG Maker.\nvar $plugins =\n"
plugins_path.write_text(prefix + "[]" + suffix, encoding="utf-8")

from install_plugin import PLUGIN_CONFIG, update_plugins_js

update_plugins_js(str(tmp_path / "www"))
content = plugins_path.read_text(encoding="utf-8")
entries, end = json.JSONDecoder().raw_decode(content, len(prefix))
assert entries == [PLUGIN_CONFIG]
assert content[end:] == suffix
update_plugins_js(str(tmp_path / "www"))
assert plugins_path.read_text(encoding="utf-8") == content

@pytest.mark.parametrize("comment", [
'// removed {"name": "DynamicTranslation"}\n',
'/* removed {"name": "DynamicTranslation"} */\n',
])
def test_name_in_leading_comment_is_not_registration(self, tmp_path, comment):
_make_rpg_project(tmp_path)
plugins_path = _make_plugins_js(tmp_path)
prefix = comment + "var $plugins = "
plugins_path.write_text(prefix + "[];\n", encoding="utf-8")

from install_plugin import update_plugins_js

update_plugins_js(str(tmp_path / "www"))
content = plugins_path.read_text(encoding="utf-8")
assert content.startswith(prefix)
entries, _ = json.JSONDecoder().raw_decode(content, len(prefix))
assert [entry["name"] for entry in entries] == ["DynamicTranslation"]

def test_nested_name_is_not_registration(self, tmp_path):
_make_rpg_project(tmp_path)
other = {"name": "OtherPlugin", "parameters": {"name": "DynamicTranslation"}}
plugins_path = _make_plugins_js(tmp_path, [other])

from install_plugin import update_plugins_js

update_plugins_js(str(tmp_path / "www"))
entries = json.loads(plugins_path.read_text(encoding="utf-8"))
assert entries[0] == other
assert [entry["name"] for entry in entries] == ["OtherPlugin", "DynamicTranslation"]

def test_escaped_existing_name_preserves_registration(self, tmp_path):
_make_rpg_project(tmp_path)
plugins_path = _make_plugins_js(tmp_path)
content = r'var $plugins = [{"name":"Dynamic\u0054ranslation","status":false}];'
plugins_path.write_text(content, encoding="utf-8")

from install_plugin import update_plugins_js

update_plugins_js(str(tmp_path / "www"))
assert plugins_path.read_text(encoding="utf-8") == content

@pytest.mark.parametrize("content", [
'var $plugins = [{"name": "OtherPlugin"}; // ]\n',
'var $plugins = [null];\n',
'var $plugins = [{"name": "OtherPlugin"},];\n',
'var unrelated = [];\n',
'var $plugins = loadPlugins(); // []\n',
'var $plugins = [].concat([]);\n',
'var $plugins = []\n.concat([]);\n',
'var $plugins = [{"name":"OtherPlugin"}][0];\n',
])
def test_unsupported_or_malformed_list_is_unchanged(self, tmp_path, capsys, content):
_make_rpg_project(tmp_path)
plugins_path = _make_plugins_js(tmp_path)
plugins_path.write_text(content, encoding="utf-8")

from install_plugin import update_plugins_js

assert update_plugins_js(str(tmp_path / "www")) is False
assert plugins_path.read_text(encoding="utf-8") == content
assert "Error:" in capsys.readouterr().out

def test_cli_reports_registration_failure_without_claiming_completion(self, tmp_path):
_make_rpg_project(tmp_path)
plugins_path = _make_plugins_js(tmp_path)
content = 'var $plugins = loadPlugins(); // []\n'
plugins_path.write_text(content, encoding="utf-8")

result = subprocess.run(
[sys.executable, str(PROJECT_ROOT / "install_plugin.py"), str(tmp_path)],
capture_output=True,
text=True,
encoding="utf-8",
)

assert result.returncode != 0
assert "Registration failed" in result.stderr
assert "Installation complete" not in result.stdout
assert plugins_path.read_text(encoding="utf-8") == content

def test_bom_and_crlf_are_preserved(self, tmp_path):
_make_rpg_project(tmp_path)
plugins_path = _make_plugins_js(tmp_path)
prefix = "\ufeff// generated\r\nvar $plugins = "
suffix = ";\r\n// [optional]\r\n"
plugins_path.write_bytes((prefix + "[]" + suffix).encode("utf-8"))

from install_plugin import update_plugins_js

update_plugins_js(str(tmp_path / "www"))
content = plugins_path.read_bytes().decode("utf-8")
assert content.startswith(prefix)
entries, end = json.JSONDecoder().raw_decode(content, len(prefix))
assert len(entries) == 1
assert content[end:] == suffix


class TestInstallTranslation:
"""Tests for install_translation()."""
Expand Down
Loading