From 5ea2f5e0607659a920a66b4405a9b8189c8d08cc Mon Sep 17 00:00:00 2001 From: LizheChen <574118090@qq.com> Date: Tue, 6 Oct 2026 04:29:54 +0800 Subject: [PATCH 1/4] Validate plugin payloads without requiring starter examples --- .github/workflows/validate.yml | 2 + .infernux-dev/validate.py | 16 +------ tests/test_validation.py | 85 ++++++++++++++++++++++++++++++++++ 3 files changed, 89 insertions(+), 14 deletions(-) create mode 100644 tests/test_validation.py diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 1de5f76..b1c1a18 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -22,6 +22,8 @@ jobs: python-version: "3.13" - name: Validate package layout and Python sources run: python .infernux-dev/validate.py + - name: Check validation contracts + run: python -m unittest discover -s tests - name: Build and verify deterministic package bytes run: | mkdir -p dist/repro diff --git a/.infernux-dev/validate.py b/.infernux-dev/validate.py index 513e72c..5128c55 100644 --- a/.infernux-dev/validate.py +++ b/.infernux-dev/validate.py @@ -19,15 +19,7 @@ raise SystemExit(f"Missing template entry: {path}") for path in sorted((*PACKAGE.joinpath("runtime").rglob("*.py"), *PACKAGE.joinpath("editor").rglob("*.py"))): compile(path.read_text(encoding="utf-8"), str(path), "exec") -runtime_sources = tuple(PACKAGE.joinpath("runtime").rglob("*.py")) -editor_sources = tuple(PACKAGE.joinpath("editor").rglob("*.py")) -if not any("InxComponent" in path.read_text(encoding="utf-8") for path in runtime_sources): - raise SystemExit("Template runtime has no InxComponent example") -if not any("InxPreload" in path.read_text(encoding="utf-8") for path in runtime_sources): - raise SystemExit("Template runtime has no Player-safe InxPreload example") -if not any("InxPreload" in path.read_text(encoding="utf-8") for path in editor_sources): - raise SystemExit("Template editor has no editor-owned InxPreload example") -for path in runtime_sources: +for path in PACKAGE.joinpath("runtime").rglob("*.py"): source = path.read_text(encoding="utf-8") if "example_plugin_editor" in source or "Infernux.engine.ui" in source: raise SystemExit(f"Runtime source imports Editor code: {path.relative_to(PACKAGE)}") @@ -37,8 +29,4 @@ localized = english.with_name(f"{english.stem}.zh-CN.md") if not localized.is_file(): raise SystemExit(f"Missing zh-CN page: {localized.name}") - source = english.read_text(encoding="utf-8") - for required_topic in ("runtime/", "editor/", "plugin_pages/", "add_cleanup", "Export InxPackage"): - if required_topic not in source: - raise SystemExit(f"Plugin tutorial is missing {required_topic!r}: {english.name}") -print("Template layout and Python sources are valid.") +print("Package layout and Python sources are valid.") diff --git a/tests/test_validation.py b/tests/test_validation.py new file mode 100644 index 0000000..34d11d1 --- /dev/null +++ b/tests/test_validation.py @@ -0,0 +1,85 @@ +"""A plugin fork may replace every starter example with its own payload.""" + +from pathlib import Path +import json +import shutil +import subprocess +import sys +import tempfile +import unittest + + +class PackageValidationTests(unittest.TestCase): + def setUp(self): + workspace = tempfile.TemporaryDirectory() + self.addCleanup(workspace.cleanup) + self.root = Path(workspace.name) + validator = Path(__file__).resolve().parents[1] / ".infernux-dev/validate.py" + self.script = self.root / ".infernux-dev/validate.py" + self.script.parent.mkdir() + shutil.copyfile(validator, self.script) + self.package = self.root / "package" + self.package.mkdir() + self.manifest = { + "reference": "test/hello", "name": "Hello", "version": "0.1.0", + "engine": ">=0.4,<0.5", + } + self.write_manifest() + for name in ("README.md", "README.zh-CN.md", "LICENSE", "package.py"): + (self.root / name).write_text("", encoding="utf-8") + + def write_manifest(self): + (self.package / "inx_package.json").write_text( + json.dumps(self.manifest), encoding="utf-8" + ) + + def write(self, relative, text): + destination = self.package / relative + destination.parent.mkdir(parents=True, exist_ok=True) + destination.write_text(text, encoding="utf-8") + + def validate(self): + return subprocess.run( + [sys.executable, "-S", str(self.script)], cwd=self.root, + capture_output=True, text=True, encoding="utf-8", + ) + + def test_component_only_plugin_without_preloads_is_valid(self): + self.write("runtime/hello.py", "import infernux as inx\nclass Hello(inx.InxComponent):\n pass\n") + result = self.validate() + self.assertEqual(result.returncode, 0, result.stderr) + + def test_asset_only_plugin_without_python_is_valid(self): + self.write("runtime/data/settings.json", '{"speed": 3}') + result = self.validate() + self.assertEqual(result.returncode, 0, result.stderr) + + def test_short_bilingual_guide_does_not_need_the_starter_tutorial(self): + self.write("plugin_pages/guide.md", "Attach Hello and press Play.\n") + self.write("plugin_pages/guide.zh-CN.md", "挂载 Hello,然后进入播放。\n") + result = self.validate() + self.assertEqual(result.returncode, 0, result.stderr) + + def test_invalid_python_remains_rejected(self): + self.write("runtime/hello.py", "class Hello(\n") + result = self.validate() + self.assertNotEqual(result.returncode, 0) + self.assertIn("SyntaxError", result.stderr) + + def test_missing_manifest_field_remains_rejected(self): + del self.manifest["version"] + self.write_manifest() + result = self.validate() + self.assertNotEqual(result.returncode, 0) + self.assertIn("Missing manifest fields: version", result.stderr) + + def test_unsupported_manifest_dependency_field_remains_rejected(self): + self.manifest["dependencies"] = [] + self.write_manifest() + result = self.validate() + self.assertNotEqual(result.returncode, 0) + self.assertIn("Unsupported manifest fields: dependencies", result.stderr) + + +if __name__ == "__main__": + unittest.main() From f16f4bd65374b539f222dcb0fdc5f5fcd83e3810 Mon Sep 17 00:00:00 2001 From: LizheChen <574118090@qq.com> Date: Thu, 8 Oct 2026 10:54:29 +0800 Subject: [PATCH 2/4] Validate actual runtime imports without rejecting documentation text --- .infernux-dev/validate.py | 51 ++++++++++++++++++++++++++++--- tests/test_validation.py | 64 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 110 insertions(+), 5 deletions(-) diff --git a/.infernux-dev/validate.py b/.infernux-dev/validate.py index 5128c55..13acdd5 100644 --- a/.infernux-dev/validate.py +++ b/.infernux-dev/validate.py @@ -1,5 +1,6 @@ from __future__ import annotations +import ast import json from pathlib import Path @@ -17,12 +18,52 @@ for path in ("README.md", "README.zh-CN.md", "LICENSE", "package", "package.py"): if not (ROOT / path).exists(): raise SystemExit(f"Missing template entry: {path}") -for path in sorted((*PACKAGE.joinpath("runtime").rglob("*.py"), *PACKAGE.joinpath("editor").rglob("*.py"))): - compile(path.read_text(encoding="utf-8"), str(path), "exec") -for path in PACKAGE.joinpath("runtime").rglob("*.py"): + + +def module_names(root): + names = set() + for path in root.rglob("*.py"): + parts = path.relative_to(root).with_suffix("").parts + if parts[-1] == "__init__": + parts = parts[:-1] + if parts: + names.add(".".join(parts)) + return names + + +runtime_root = PACKAGE / "runtime" +editor_root = PACKAGE / "editor" +# Namespace directories alone do not execute editor code and may be shared. +editor_only_modules = module_names(editor_root) - module_names(runtime_root) +editor_imports = {"infernux.engine.ui", "Infernux.engine.ui"} | editor_only_modules + +for path in sorted((*runtime_root.rglob("*.py"), *editor_root.rglob("*.py"))): source = path.read_text(encoding="utf-8") - if "example_plugin_editor" in source or "Infernux.engine.ui" in source: - raise SystemExit(f"Runtime source imports Editor code: {path.relative_to(PACKAGE)}") + compile(source, str(path), "exec") + if not path.is_relative_to(runtime_root): + continue + tree = ast.parse(source, filename=str(path)) + package_parts = path.relative_to(runtime_root).parent.parts + for node in ast.walk(tree): + if isinstance(node, ast.Import): + imports = [alias.name for alias in node.names] + elif isinstance(node, ast.ImportFrom): + if node.level: + if node.level > len(package_parts): + continue # An invalid relative import is a Python runtime error. + prefix = package_parts[:len(package_parts) - node.level + 1] + suffix = node.module.split(".") if node.module else () + module = ".".join((*prefix, *suffix)) + else: + module = node.module or "" + imports = [module, *(f"{module}.{alias.name}" for alias in node.names)] + else: + continue + if any( + name == editor or name.startswith(editor + ".") + for name in imports for editor in editor_imports + ): + raise SystemExit(f"Runtime source imports Editor code: {path.relative_to(PACKAGE)}:{node.lineno}") for english in PACKAGE.joinpath("plugin_pages").glob("*.md"): if english.name.endswith(".zh-CN.md"): continue diff --git a/tests/test_validation.py b/tests/test_validation.py index 34d11d1..27b3cf6 100644 --- a/tests/test_validation.py +++ b/tests/test_validation.py @@ -80,6 +80,70 @@ def test_unsupported_manifest_dependency_field_remains_rejected(self): self.assertNotEqual(result.returncode, 0) self.assertIn("Unsupported manifest fields: dependencies", result.stderr) + def test_runtime_editor_imports_are_rejected_in_both_package_spellings(self): + for source in ( + "import infernux.engine.ui\n", + "from infernux.engine.ui import Panel\n", + "from infernux.engine import ui\n", + "import Infernux.engine.ui\n", + ): + with self.subTest(source=source): + self.write("runtime/hello.py", source) + result = self.validate() + self.assertNotEqual(result.returncode, 0) + self.assertIn("Runtime source imports Editor code", result.stderr) + + def test_runtime_cannot_import_the_plugins_actual_editor_package(self): + self.write("editor/studio/tools/__init__.py", "") + for source in ( + "import studio.tools\n", + "from studio import tools\n", + "from studio.tools import Panel\n", + ): + with self.subTest(source=source): + self.write("runtime/hello.py", source) + result = self.validate() + self.assertNotEqual(result.returncode, 0) + self.assertIn("Runtime source imports Editor code", result.stderr) + + def test_editor_names_in_comments_and_strings_are_valid(self): + self.write( + "runtime/hello.py", + '# Infernux.engine.ui belongs in Editor code.\n' + 'description = "example_plugin_editor documentation"\n', + ) + result = self.validate() + self.assertEqual(result.returncode, 0, result.stderr) + + def test_runtime_subpackages_and_external_libraries_are_valid(self): + self.write("editor/studio/tools/__init__.py", "") + self.write("runtime/studio/game/__init__.py", "") + self.write( + "runtime/hello.py", + "import infernux.renderstack\nimport numpy\n" + "from packaging.version import Version\nfrom studio import game\n", + ) + result = self.validate() + self.assertEqual(result.returncode, 0, result.stderr) + + def test_external_modules_in_a_shared_namespace_are_valid(self): + self.write("editor/studio/tools/__init__.py", "") + self.write("runtime/hello.py", "from studio import external_library\n") + result = self.validate() + self.assertEqual(result.returncode, 0, result.stderr) + + def test_relative_editor_import_is_rejected(self): + self.write("editor/studio/editor_tools.py", "") + self.write("runtime/studio/hello.py", "from . import editor_tools\n") + result = self.validate() + self.assertNotEqual(result.returncode, 0) + self.assertIn("Runtime source imports Editor code", result.stderr) + + def test_editor_source_can_import_editor_apis(self): + self.write("editor/studio/tools.py", "from infernux.engine.ui import Panel\n") + result = self.validate() + self.assertEqual(result.returncode, 0, result.stderr) + if __name__ == "__main__": unittest.main() From 9bd1be47bba5c7a3f4bf2797ac850bb7df13c7cc Mon Sep 17 00:00:00 2001 From: LizheChen <574118090@qq.com> Date: Thu, 8 Oct 2026 11:24:33 +0800 Subject: [PATCH 3/4] Migrate starter payloads to the lowercase Infernux SDK --- README.md | 2 ++ README.zh-CN.md | 2 ++ package/editor/your_studio/example_plugin_editor/panel.py | 6 +++--- package/editor/your_studio/example_plugin_editor/preload.py | 2 +- package/inx_package.json | 2 +- package/runtime/your_studio/example_plugin/component.py | 4 ++-- package/runtime/your_studio/example_plugin/preload.py | 2 +- 7 files changed, 12 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index de50806..ed0d940 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,8 @@ flowchart LR `package.py` uses only the Python standard library, so packaging does not require an Infernux installation. Your repository may use CMake, Gradle, Cargo, npm, or another build system; copy only the files users need at runtime into `package/`. +The included Python starter requires Infernux 0.4.1 and uses the lowercase `infernux` package. Keep the manifest's engine range aligned with the APIs your plugin actually uses. + Inside an Infernux project, the selected folder is already the package root: select it in Project/File Manager, right click, and choose **Export InxPackage...**. The installed Plugins page contains the full tutorial, including lifecycle ownership, hot reload, Player component registration, large imports, and an Editor-only Flask tool window. ## Package layout diff --git a/README.zh-CN.md b/README.zh-CN.md index 6b06b06..80d93c8 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -26,6 +26,8 @@ flowchart LR `package.py` 只使用 Python 标准库,打包时不需要安装 Infernux。仓库可以自由使用 CMake、Gradle、Cargo、npm 或其他构建工具;只需把用户运行插件时真正需要的文件放进 `package/`。 +模板中的 Python 示例需要 Infernux 0.4.1,并使用小写的 `infernux` 包。插件清单中的引擎版本范围应与实际使用的 API 保持一致。 + 在 Infernux 项目中,被选中的文件夹本身就是包根:在 Project/File Manager 中选中它,右键选择**导出 InxPackage...**。安装后插件页面中的完整教程会说明生命周期所有权、热重载、Player 组件注册、大型包导入以及仅 Editor 使用的 Flask 独立工具窗口。 ## 目录结构 diff --git a/package/editor/your_studio/example_plugin_editor/panel.py b/package/editor/your_studio/example_plugin_editor/panel.py index 97c6513..bfb7015 100644 --- a/package/editor/your_studio/example_plugin_editor/panel.py +++ b/package/editor/your_studio/example_plugin_editor/panel.py @@ -1,8 +1,8 @@ """Example panel available only inside the editor.""" -from Infernux.engine.interaction import PanelInteractionDescriptor -from Infernux.engine.ui.editor_panel import EditorPanel -from Infernux.engine.ui.panel_registry import editor_panel +from infernux.engine.interaction import PanelInteractionDescriptor +from infernux.engine.ui.editor_panel import EditorPanel +from infernux.engine.ui.panel_registry import editor_panel @editor_panel( diff --git a/package/editor/your_studio/example_plugin_editor/preload.py b/package/editor/your_studio/example_plugin_editor/preload.py index ca2ec27..2866e86 100644 --- a/package/editor/your_studio/example_plugin_editor/preload.py +++ b/package/editor/your_studio/example_plugin_editor/preload.py @@ -2,7 +2,7 @@ from importlib import import_module -from Infernux.lifecycle import InxPreload, PreloadContext +from infernux.lifecycle import InxPreload, PreloadContext class ExamplePluginEditorPreload(InxPreload): diff --git a/package/inx_package.json b/package/inx_package.json index 3ab2f33..4f08487 100644 --- a/package/inx_package.json +++ b/package/inx_package.json @@ -3,6 +3,6 @@ "reference": "your-studio/example-plugin", "name": "Example Plugin", "version": "0.1.0", - "engine": ">=0.4,<0.5", + "engine": ">=0.4.1,<0.5", "intro": "A minimal Infernux runtime and editor extension." } diff --git a/package/runtime/your_studio/example_plugin/component.py b/package/runtime/your_studio/example_plugin/component.py index cbc86d0..ff50982 100644 --- a/package/runtime/your_studio/example_plugin/component.py +++ b/package/runtime/your_studio/example_plugin/component.py @@ -1,7 +1,7 @@ """Example gameplay component shipped to the player build.""" -from Infernux.components import InxComponent, serialized_field -from Infernux.lib import Vector3, quatf +from infernux.components import InxComponent, serialized_field +from infernux.lib import Vector3, quatf class ExampleRotator(InxComponent): diff --git a/package/runtime/your_studio/example_plugin/preload.py b/package/runtime/your_studio/example_plugin/preload.py index 16df011..19e202c 100644 --- a/package/runtime/your_studio/example_plugin/preload.py +++ b/package/runtime/your_studio/example_plugin/preload.py @@ -1,6 +1,6 @@ """Early lifecycle for services that must exist in Editor and Player.""" -from Infernux.lifecycle import InxPreload, PreloadContext +from infernux.lifecycle import InxPreload, PreloadContext class ExamplePluginPreload(InxPreload): From 76506ce477889ea3115325546024c3ed792a3597 Mon Sep 17 00:00:00 2001 From: LizheChen <574118090@qq.com> Date: Thu, 8 Oct 2026 17:10:14 +0800 Subject: [PATCH 4/4] Keep published plugin release assets immutable --- .github/workflows/validate.yml | 10 ++-- tests/test_release_immutability.py | 95 ++++++++++++++++++++++++++++++ 2 files changed, 99 insertions(+), 6 deletions(-) create mode 100644 tests/test_release_immutability.py diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index b1c1a18..13570ec 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -64,9 +64,7 @@ jobs: env: GH_TOKEN: ${{ github.token }} run: | - if gh release view "${GITHUB_REF_NAME}" >/dev/null 2>&1; then - gh release upload "${GITHUB_REF_NAME}" "dist/${PACKAGE_NAME}" dist/infernux-plugin-release.json --clobber - else - gh release create "${GITHUB_REF_NAME}" "dist/${PACKAGE_NAME}" dist/infernux-plugin-release.json \ - --verify-tag --generate-notes - fi + # Published reference/version pairs are immutable. A duplicate tag + # must fail instead of replacing users' installed archive baseline. + gh release create "${GITHUB_REF_NAME}" "dist/${PACKAGE_NAME}" dist/infernux-plugin-release.json \ + --verify-tag --generate-notes diff --git a/tests/test_release_immutability.py b/tests/test_release_immutability.py new file mode 100644 index 0000000..4e95663 --- /dev/null +++ b/tests/test_release_immutability.py @@ -0,0 +1,95 @@ +"""Run the real release shell step against a local GitHub CLI boundary.""" +from pathlib import Path +import os +import shutil +import subprocess +import tempfile +import unittest + + +ROOT = Path(__file__).resolve().parents[1] + + +class ReleaseImmutabilityTests(unittest.TestCase): + def setUp(self): + workspace = tempfile.TemporaryDirectory() + self.addCleanup(workspace.cleanup) + self.root = Path(workspace.name) + if os.name == "nt": + git = shutil.which("git") + self.assertIsNotNone(git, "Git for Windows is required to run the release shell step") + self.bash = Path(git).resolve().parents[1] / "bin/bash.exe" + else: + self.bash = shutil.which("bash") + self.assertTrue(self.bash and Path(self.bash).is_file(), "Bash is required for release workflow tests") + workflow = (ROOT / ".github/workflows/validate.yml").read_text(encoding="utf-8") + publish = workflow.split(" - name: Publish GitHub Release assets\n", 1)[1] + script = publish.split(" run: |\n", 1)[1] + (self.root / "release.sh").write_text( + "set -e\n" + "\n".join(line[10:] for line in script.splitlines()) + "\n", + encoding="utf-8", + ) + (self.root / "bin").mkdir() + (self.root / "dist").mkdir() + (self.root / "published").mkdir() + (self.root / "dist/studio.demo.inxpkg").write_bytes(b"candidate archive") + (self.root / "dist/infernux-plugin-release.json").write_bytes(b"candidate manifest") + # The adapter implements both the current and legacy CLI routes. An + # overwrite attempt would change the baseline and make the test fail. + adapter = '''#!/usr/bin/env bash +set -eu +printf '%s\\n' "$*" >> calls.txt +case "$1:$2" in + release:view) + test -f published/archive.inxpkg + ;; + release:create) + if test -f published/archive.inxpkg; then + echo "release already exists" >&2 + exit 23 + fi + cp "$4" published/archive.inxpkg + cp "$5" published/manifest.json + ;; + release:upload) + cp "$4" published/archive.inxpkg + cp "$5" published/manifest.json + ;; + *) exit 24 ;; +esac +''' + path = self.root / "bin/gh" + path.write_text(adapter, encoding="utf-8") + path.chmod(0o755) + + def publish(self): + environment = dict(os.environ, GITHUB_REF_NAME="v0.1.0", PACKAGE_NAME="studio.demo.inxpkg") + return subprocess.run( + [str(self.bash), "--noprofile", "--norc", "-c", + 'export PATH="$PWD/bin:$PATH"; exec bash release.sh'], + cwd=self.root, env=environment, capture_output=True, text=True, + ) + + def test_duplicate_release_fails_without_overwriting_either_asset(self): + archive = self.root / "published/archive.inxpkg" + manifest = self.root / "published/manifest.json" + archive.write_bytes(b"original archive") + manifest.write_bytes(b"original manifest") + result = self.publish() + self.assertNotEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertEqual(archive.read_bytes(), b"original archive") + self.assertEqual(manifest.read_bytes(), b"original manifest") + + def test_new_release_publishes_the_archive_and_matching_manifest(self): + result = self.publish() + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertEqual((self.root / "published/archive.inxpkg").read_bytes(), b"candidate archive") + self.assertEqual((self.root / "published/manifest.json").read_bytes(), b"candidate manifest") + self.assertEqual( + (self.root / "calls.txt").read_text(encoding="utf-8").splitlines(), + ["release create v0.1.0 dist/studio.demo.inxpkg dist/infernux-plugin-release.json --verify-tag --generate-notes"], + ) + + +if __name__ == "__main__": + unittest.main()