From 8a2759b1da2e56de6e3fd10a834d407656aa6dd8 Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 10:43:32 +0200 Subject: [PATCH 01/15] feat(platform): add reusable pinned GitVersion calculation action --- .github/actions/resolve-version/action.yml | 34 ++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 .github/actions/resolve-version/action.yml diff --git a/.github/actions/resolve-version/action.yml b/.github/actions/resolve-version/action.yml new file mode 100644 index 0000000..d454701 --- /dev/null +++ b/.github/actions/resolve-version/action.yml @@ -0,0 +1,34 @@ +name: "4FusionLab GitVersion 6.8.2" +description: "Resolve a numeric Fusion package version or full SemVer without publishing" +inputs: + variable: + description: "GitVersion variable: MajorMinorPatch or SemVer" + required: false + default: "MajorMinorPatch" +outputs: + version: + description: "Resolved GitVersion value" + value: ${{ steps.version.outputs.version }} +runs: + using: composite + steps: + - id: version + name: Calculate GitVersion + shell: bash + env: + GITVERSION_VARIABLE: ${{ inputs.variable }} + run: | + set -euo pipefail + case "$GITVERSION_VARIABLE" in + MajorMinorPatch|SemVer) ;; + *) echo "Unsupported GitVersion variable: $GITVERSION_VARIABLE" >&2; exit 2 ;; + esac + dotnet tool install GitVersion.Tool --tool-path "$RUNNER_TEMP/gitversion" --version 6.8.2 + version="$("$RUNNER_TEMP/gitversion/dotnet-gitversion" /showvariable "$GITVERSION_VARIABLE")" + if [[ "$GITVERSION_VARIABLE" == MajorMinorPatch ]]; then + [[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || exit 1 + else + [[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$ ]] || exit 1 + fi + echo "version=$version" >> "$GITHUB_OUTPUT" + echo "### GitVersion ($GITVERSION_VARIABLE): $version" >> "$GITHUB_STEP_SUMMARY" From fded6a37931776068f7a623235b1738e814d7204 Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 10:44:10 +0200 Subject: [PATCH 02/15] feat(platform): centralize audited runtime-change release gate --- .github/actions/runtime-changes/action.yml | 37 ++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 .github/actions/runtime-changes/action.yml diff --git a/.github/actions/runtime-changes/action.yml b/.github/actions/runtime-changes/action.yml new file mode 100644 index 0000000..dd568a5 --- /dev/null +++ b/.github/actions/runtime-changes/action.yml @@ -0,0 +1,37 @@ +name: "4FusionLab runtime change detection" +description: "Compare the entire push range to the repository's auditable release-paths allowlist" +inputs: + before: + description: "Previous commit in push event (github.event.before)" + required: true + after: + description: "New commit in push event (github.sha)" + required: true + paths-file: + description: "Repository-relative runtime allowlist" + required: false + default: ".github/release-paths.txt" +outputs: + release: + description: "true iff runtime-affecting file was added/modified/deleted/renamed" + value: ${{ steps.changes.outputs.release }} + matched-count: + description: "Number of matched runtime paths" + value: ${{ steps.changes.outputs.matched_count }} +runs: + using: composite + steps: + - name: Detect eligible runtime changes + id: changes + shell: bash + env: + RELEASE_BEFORE: ${{ inputs.before }} + RELEASE_AFTER: ${{ inputs.after }} + RELEASE_PATHS_FILE: ${{ inputs.paths-file }} + run: | + set -euo pipefail + python3 "${{ github.action_path }}/detect.py" \ + --config "$GITHUB_WORKSPACE/$RELEASE_PATHS_FILE" \ + --before "$RELEASE_BEFORE" \ + --after "$RELEASE_AFTER" \ + --github-output "$GITHUB_OUTPUT" From 0c5d0a769b70b25e6d2018d455de7ccff77671fa Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 10:44:13 +0200 Subject: [PATCH 03/15] feat(platform): centralize audited runtime-change release gate --- .github/actions/runtime-changes/detect.py | 64 +++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 .github/actions/runtime-changes/detect.py diff --git a/.github/actions/runtime-changes/detect.py b/.github/actions/runtime-changes/detect.py new file mode 100644 index 0000000..522cd80 --- /dev/null +++ b/.github/actions/runtime-changes/detect.py @@ -0,0 +1,64 @@ +"""Determine release eligibility from Git changes and a repository-specific allowlist.""" +import argparse +import fnmatch +import subprocess +from pathlib import Path + + +def read_rules(path): + lines = Path(path).read_text(encoding="utf-8").splitlines() + rules = [line.strip() for line in lines if line.strip() and not line.lstrip().startswith("#")] + if not any(not line.startswith("!") for line in rules): + raise ValueError("Release paths must contain at least one positive pattern.") + return rules + + +def impacted(files, rules): + include = [pattern for pattern in rules if not pattern.startswith("!")] + exclude = [pattern[1:] for pattern in rules if pattern.startswith("!")] + return [path for path in files + if any(fnmatch.fnmatchcase(path, pattern) for pattern in include) + and not any(fnmatch.fnmatchcase(path, pattern) for pattern in exclude)] + + +def git_paths(before, after): + if not after: + raise ValueError("An after SHA is required.") + if not before or before == "0" * 40: + command = ["git", "ls-tree", "-rz", "--name-only", after] + else: + # --no-renames reports both old and new paths; deleted runtime files count too. + command = ["git", "diff", "--name-only", "-z", "--no-renames", before, after] + stdout = subprocess.check_output(command) + return [entry.decode("utf-8", errors="surrogateescape") + for entry in stdout.split(b"\0") if entry] + + +def evaluate(paths, rules): + changed = list(paths) + matches = impacted(changed, rules) + return len(matches) > 0, matches + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--config", required=True) + parser.add_argument("--before") + parser.add_argument("--after") + parser.add_argument("--github-output") + parser.add_argument("--changed", nargs="*") + args = parser.parse_args() + rules = read_rules(args.config) + files = args.changed if args.changed is not None else git_paths(args.before, args.after) + eligible, matched = evaluate(files, rules) + value = "true" if eligible else "false" + print(f"Release eligible: {value} ({len(matched)} matching paths)") + for path in matched: + print(" " + path) + if args.github_output: + with open(args.github_output, "a", encoding="utf-8") as output: + output.write(f"release={value}\nmatched_count={len(matched)}\n") + + +if __name__ == "__main__": + main() From 403ae1ada32bfae17f19093a2c2f1afac5d6f60e Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 10:44:27 +0200 Subject: [PATCH 04/15] feat(platform): centralize reviewed and generated release notes --- .github/actions/release-notes/action.yml | 37 ++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 .github/actions/release-notes/action.yml diff --git a/.github/actions/release-notes/action.yml b/.github/actions/release-notes/action.yml new file mode 100644 index 0000000..6688077 --- /dev/null +++ b/.github/actions/release-notes/action.yml @@ -0,0 +1,37 @@ +name: "4FusionLab release notes" +description: "Reuse reviewed version notes or generate readable notes from Git history" +inputs: + product: + description: "Product name for release heading" + required: true + version: + description: "Calculated numeric GitVersion value" + required: true + candidate: + description: "Optional repository-relative version-specific reviewed notes file" + required: false + default: "" + output: + description: "Writable path for generated notes; use a path in runner.temp" + required: true +outputs: + notes-file: + description: "Path to the complete release notes" + value: ${{ steps.notes.outputs.notes_file }} +runs: + using: composite + steps: + - name: Prepare release notes + shell: bash + id: notes + env: + RELEASE_PRODUCT: ${{ inputs.product }} + RELEASE_VERSION: ${{ inputs.version }} + RELEASE_CANDIDATE: ${{ inputs.candidate }} + RELEASE_OUTPUT: ${{ inputs.output }} + run: | + set -euo pipefail + python3 "${{ github.action_path }}/notes.py" \ + --product "$RELEASE_PRODUCT" --version "$RELEASE_VERSION" \ + --candidate "$RELEASE_CANDIDATE" --output "$RELEASE_OUTPUT" + echo "notes_file=$RELEASE_OUTPUT" >> "$GITHUB_OUTPUT" From 859ddd616f4f8e90ffd9a9a44c4f1cc841d2b76f Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 10:44:30 +0200 Subject: [PATCH 05/15] feat(platform): centralize reviewed and generated release notes --- .github/actions/release-notes/notes.py | 46 ++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 .github/actions/release-notes/notes.py diff --git a/.github/actions/release-notes/notes.py b/.github/actions/release-notes/notes.py new file mode 100644 index 0000000..e6a0eaf --- /dev/null +++ b/.github/actions/release-notes/notes.py @@ -0,0 +1,46 @@ +"""Select reviewed notes or generate fallback release notes from Git history.""" +import argparse +import re +import subprocess +from pathlib import Path + + +def git(*args): + return subprocess.run(["git", *args], capture_output=True, text=True, check=False) + + +def create_notes(product, version, candidate, output): + if not re.fullmatch(r"\d+\.\d+\.\d+", version): + raise ValueError("Fusion release version must be MAJOR.MINOR.PATCH") + output = Path(output) + if candidate: + reviewed = Path(candidate) + if reviewed.is_file() and reviewed.read_text(encoding="utf-8").strip(): + output.write_text(reviewed.read_text(encoding="utf-8"), encoding="utf-8") + return "reviewed" + previous = git("describe", "--tags", "--abbrev=0", "--match", "v[0-9]*", "HEAD") + tag = previous.stdout.strip() if previous.returncode == 0 else None + rev = f"{tag}..HEAD" if tag else "HEAD" + logs = subprocess.run(["git", "log", "--max-count=100", "--format=- %s (%h)", rev], + check=True, capture_output=True, text=True).stdout.strip() + if not logs: + raise ValueError("No commits since previous release; cannot generate notes.") + previous_label = f"Changes since {tag}" if tag else "Initial release changes" + output.write_text(f"# {product} v{version}\n\n{previous_label}:\n\n{logs}\n", + encoding="utf-8") + return "generated" + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--product", required=True) + parser.add_argument("--version", required=True) + parser.add_argument("--output", required=True) + parser.add_argument("--candidate", default="") + args = parser.parse_args() + method = create_notes(args.product, args.version, args.candidate, args.output) + print(f"Prepared {method} notes: {args.output}") + + +if __name__ == "__main__": + main() From 8285c6168f727fd2ace9bb971a7ed492402b0458 Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 10:44:45 +0200 Subject: [PATCH 06/15] feat(platform): share read-only ZIP and Fusion manifest release contract --- .github/actions/verify-archive/action.yml | 37 +++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 .github/actions/verify-archive/action.yml diff --git a/.github/actions/verify-archive/action.yml b/.github/actions/verify-archive/action.yml new file mode 100644 index 0000000..43aa29f --- /dev/null +++ b/.github/actions/verify-archive/action.yml @@ -0,0 +1,37 @@ +name: "4FusionLab ZIP integrity" +description: "Read-only validation of versioned release ZIPs, SHA-256 and Fusion manifests" +inputs: + product: + description: "Product prefix for archive filenames" + required: true + version: + description: "GitVersion MajorMinorPatch" + required: true + archives: + description: "Newline-separated ZIP paths relative to caller workspace" + required: true + manifest: + description: "Fusion manifest path inside ZIP, if this is a Fusion add-in" + required: false + default: "" + notes: + description: "Nonempty notes file path; omit for a nonpublishing dry-run" + required: false + default: "" +runs: + using: composite + steps: + - name: Validate release artifacts + shell: bash + env: + RELEASE_PRODUCT: ${{ inputs.product }} + RELEASE_VERSION: ${{ inputs.version }} + RELEASE_ARCHIVES: ${{ inputs.archives }} + RELEASE_MANIFEST: ${{ inputs.manifest }} + RELEASE_NOTES: ${{ inputs.notes }} + run: | + set -euo pipefail + python3 "${{ github.action_path }}/verify.py" \ + --product "$RELEASE_PRODUCT" --version "$RELEASE_VERSION" \ + --archives "$RELEASE_ARCHIVES" \ + --manifest "$RELEASE_MANIFEST" --notes "$RELEASE_NOTES" From 18bd4af8fd26810a6b974e2780c7d1c7c4b1f5e5 Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 10:44:48 +0200 Subject: [PATCH 07/15] feat(platform): share read-only ZIP and Fusion manifest release contract --- .github/actions/verify-archive/verify.py | 65 ++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 .github/actions/verify-archive/verify.py diff --git a/.github/actions/verify-archive/verify.py b/.github/actions/verify-archive/verify.py new file mode 100644 index 0000000..101021b --- /dev/null +++ b/.github/actions/verify-archive/verify.py @@ -0,0 +1,65 @@ +"""Validate versioned ZIP packages, content safety, Fusion manifests and SHA-256.""" +import argparse +import hashlib +import json +import re +import zipfile +from pathlib import Path + + +def verify(product, version, archives, manifest="", notes=""): + if not re.fullmatch(r"[A-Za-z0-9_.-]+", product): + raise ValueError("Invalid product identifier") + if not re.fullmatch(r"(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)", version): + raise ValueError("Expected numeric GitVersion MAJOR.MINOR.PATCH") + if notes and (not Path(notes).is_file() or not Path(notes).read_text(encoding="utf-8").strip()): + raise ValueError("Release notes missing or empty") + if not archives: + raise ValueError("At least one release ZIP is required") + for filename in archives: + archive = Path(filename) + if archive.suffix.lower() != ".zip" or not archive.is_file(): + raise ValueError(f"Missing ZIP: {archive}") + if archive.name != f"{product}-{version}.zip" and not archive.name.startswith( + f"{product}-{version}-" + ): + raise ValueError(f"ZIP version/name mismatch: {archive.name}") + checksum = archive.with_suffix(".zip.sha256") + if not checksum.is_file(): + raise ValueError(f"Missing SHA-256: {checksum}") + digest = hashlib.sha256(archive.read_bytes()).hexdigest() + expected = f"{digest} {archive.name}" + if checksum.read_text(encoding="ascii").strip() != expected: + raise ValueError(f"Incorrect ZIP checksum: {checksum}") + with zipfile.ZipFile(archive) as bundle: + for member in bundle.infolist(): + name = member.filename + p = Path(name) + if not name or name.startswith("/") or "\\" in name or ".." in p.parts: + raise ValueError(f"Unsafe ZIP entry: {name}") + if (member.external_attr >> 16) & 0o170000 == 0o120000: + raise ValueError(f"Symlink in release ZIP: {name}") + if manifest: + metadata = json.loads(bundle.read(manifest)) + if metadata.get("version") != version or metadata.get("type") != "addin": + raise ValueError(f"Fusion manifest version/type mismatch: {archive}") + if bundle.testzip() is not None: + raise ValueError(f"Corrupt ZIP: {archive}") + return len(archives) + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--product", required=True) + parser.add_argument("--version", required=True) + parser.add_argument("--archives", required=True) + parser.add_argument("--manifest", default="") + parser.add_argument("--notes", default="") + args = parser.parse_args() + archives = [line.strip() for line in args.archives.splitlines() if line.strip()] + verified = verify(args.product, args.version, archives, args.manifest, args.notes) + print(f"Verified {verified} immutable ZIP candidates for {args.product} {args.version}") + + +if __name__ == "__main__": + main() From bd8532477d70e3751d1e0a1a4bd64748be0f6a15 Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 10:45:06 +0200 Subject: [PATCH 08/15] test(platform): regression coverage for release gates, notes and archives --- .github/tests/test_platform.py | 146 +++++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 .github/tests/test_platform.py diff --git a/.github/tests/test_platform.py b/.github/tests/test_platform.py new file mode 100644 index 0000000..7793119 --- /dev/null +++ b/.github/tests/test_platform.py @@ -0,0 +1,146 @@ +"""Regression tests for 4FusionLab shared, nonpublishing release actions.""" +import hashlib +import importlib.util +import json +import os +from pathlib import Path +import subprocess +import tempfile +import unittest +import zipfile + + +ROOT = Path(__file__).resolve().parents[1] / "actions" + + +def load(name, file): + spec = importlib.util.spec_from_file_location(name, ROOT / file) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +detect = load("detect", "runtime-changes/detect.py") +notes = load("notes", "release-notes/notes.py") +verify = load("verify", "verify-archive/verify.py") + + +class ChangeGateTests(unittest.TestCase): + def test_documentation_only_does_not_release(self): + rules = ["Perfora/**", "install.py"] + self.assertEqual(detect.impacted(["README.md", "docs/USAGE.md", + "tests/test_engine.py", ".github/workflows/ci.yml"], + rules), []) + + def test_runtime_and_deletions_release(self): + rules = ["Perfora/**", "install.py"] + self.assertEqual(detect.impacted(["Perfora/core.py", "docs/README.md"], rules), + ["Perfora/core.py"]) + self.assertTrue(detect.evaluate(["Perfora/obsolete.py"], rules)[0]) + + def test_nested_exclusions_and_catalog_json(self): + rules = ["frontend/src/**", "!frontend/**/*.test.*", + "catalog/brands/**.json"] + self.assertEqual(detect.impacted(["frontend/src/main.tsx", + "frontend/src/view.test.tsx", + "catalog/brands/abc/pla.json", + "catalog/brands/README.md"], rules), + ["frontend/src/main.tsx", "catalog/brands/abc/pla.json"]) + + def test_diff_for_removed_runtime_file(self): + with tempfile.TemporaryDirectory() as temp: + def git(*args): + return subprocess.run(["git", *args], cwd=temp, text=True, + check=True, capture_output=True).stdout.strip() + git("init", "-b", "main") + git("config", "user.name", "CI") + git("config", "user.email", "ci@example.invalid") + path = Path(temp, "Perfora") + path.mkdir() + (path / "remove.py").write_text("print('hi')\n") + git("add", ".") + git("commit", "-m", "feat: add runtime") + before = git("rev-parse", "HEAD") + (path / "remove.py").unlink() + git("add", "-u") + git("commit", "-m", "fix: remove runtime") + after = git("rev-parse", "HEAD") + previous = os.getcwd() + try: + os.chdir(temp) + self.assertEqual(detect.git_paths(before, after), ["Perfora/remove.py"]) + finally: + os.chdir(previous) + + +class NotesTests(unittest.TestCase): + def test_prefer_reviewed_notes(self): + with tempfile.TemporaryDirectory() as temp: + reviewed = Path(temp, "reviewed.md") + output = Path(temp, "notes.md") + reviewed.write_text("# Reviewed notes\n", encoding="utf-8") + mode = notes.create_notes("Perfora", "1.2.3", str(reviewed), str(output)) + self.assertEqual(mode, "reviewed") + self.assertEqual(output.read_text(), "# Reviewed notes\n") + + def test_generate_from_git_history(self): + with tempfile.TemporaryDirectory() as temp: + def git(*args): + return subprocess.run(["git", *args], cwd=temp, text=True, + check=True, capture_output=True).stdout.strip() + git("init", "-b", "main") + git("config", "user.name", "CI") + git("config", "user.email", "ci@example.invalid") + Path(temp, "README.md").write_text("old") + git("add", ".") + git("commit", "-m", "chore: baseline") + git("tag", "v1.0.0") + Path(temp, "src.py").write_text("new") + git("add", ".") + git("commit", "-m", "feat: useful improvement") + previous = os.getcwd() + try: + os.chdir(temp) + output = Path(temp, "notes.md") + self.assertEqual(notes.create_notes("Perfora", "1.1.0", "", output), + "generated") + self.assertIn("feat: useful improvement", output.read_text()) + self.assertIn("v1.0.0", output.read_text()) + finally: + os.chdir(previous) + + +class PackageTests(unittest.TestCase): + def make_package(self, temp): + archive = Path(temp, "Perfora-1.2.3.zip") + with zipfile.ZipFile(archive, "w") as z: + z.writestr("Perfora/Perfora.manifest", + json.dumps({"type": "addin", "version": "1.2.3"})) + z.writestr("Perfora/Perfora.py", "print('ok')") + checksum = archive.with_suffix(".zip.sha256") + checksum.write_text(hashlib.sha256(archive.read_bytes()).hexdigest() + + " " + archive.name + "\n", encoding="ascii") + return archive, checksum + + def test_valid_archive(self): + with tempfile.TemporaryDirectory() as temp: + archive, _ = self.make_package(temp) + self.assertEqual(verify.verify("Perfora", "1.2.3", + [archive], "Perfora/Perfora.manifest"), 1) + + def test_wrong_checksum_blocks_publication(self): + with tempfile.TemporaryDirectory() as temp: + archive, checksum = self.make_package(temp) + checksum.write_text("invalid\n", encoding="ascii") + with self.assertRaises(ValueError): + verify.verify("Perfora", "1.2.3", [archive], "Perfora/Perfora.manifest") + + def test_wrong_manifest_blocks_publication(self): + with tempfile.TemporaryDirectory() as temp: + archive, _ = self.make_package(temp) + with self.assertRaises(KeyError): + verify.verify("Perfora", "1.2.3", [archive], "Perfora/not-a-file.manifest") + + +if __name__ == "__main__": + unittest.main() From 913ba8bcec5a5993214fb24872bc36013e46df09 Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 10:45:19 +0200 Subject: [PATCH 09/15] ci(platform): test shared composite actions without publishing releases --- .github/workflows/platform-tests.yml | 68 ++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 .github/workflows/platform-tests.yml diff --git a/.github/workflows/platform-tests.yml b/.github/workflows/platform-tests.yml new file mode 100644 index 0000000..5c0b133 --- /dev/null +++ b/.github/workflows/platform-tests.yml @@ -0,0 +1,68 @@ +name: Shared release platform checks + +on: + push: + branches: [main] + paths: + - '.github/actions/**' + - '.github/tests/**' + - '.github/workflows/platform-tests.yml' + pull_request: + paths: + - '.github/actions/**' + - '.github/tests/**' + - '.github/workflows/platform-tests.yml' + workflow_dispatch: + +permissions: + contents: read + +jobs: + self-test: + name: Shared action contract tests + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + persist-credentials: false + - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 + with: + python-version: '3.12' + - name: Test release classifier, notes, ZIP contracts + run: python -m unittest discover -s .github/tests -v + - name: Execute local GitVersion composite action (read-only) + id: version + uses: ./.github/actions/resolve-version + - name: Exercise local release notes composite action + uses: ./.github/actions/release-notes + with: + product: SharedPlatform + version: ${{ steps.version.outputs.version }} + output: ${{ runner.temp }}/platform-notes.md + - name: Generate inert test archive + shell: bash + run: | + set -euo pipefail + python - <<'PY' + import hashlib + import zipfile + from pathlib import Path + path = Path('dist/SharedPlatform-0.0.0.zip') + path.parent.mkdir(exist_ok=True) + with zipfile.ZipFile(path, 'w') as bundle: + bundle.writestr('demo.txt', 'contract check') + digest = hashlib.sha256(path.read_bytes()).hexdigest() + path.with_suffix('.zip.sha256').write_text( + digest + ' ' + path.name + '\n', encoding='ascii') + PY + - name: Exercise local archive verification composite action + uses: ./.github/actions/verify-archive + with: + product: SharedPlatform + version: '0.0.0' + archives: dist/SharedPlatform-0.0.0.zip + notes: ${{ runner.temp }}/platform-notes.md + - name: Check generated notes + run: test -s "${{ runner.temp }}/platform-notes.md" From fa446485e210424935ef084f6ad2d0eb4ed96c29 Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 10:45:39 +0200 Subject: [PATCH 10/15] docs(platform): codify shared engineering and safe migration rules --- AGENTS.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d62770b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,27 @@ +# 4FusionLab engineering instructions + +This repository holds reusable, **read-only** CI building blocks and organization-level defaults. Product-specific instructions belong in each product repository. + +## Language and product documentation +- Discuss requirements and plans in Russian. Use English for Autodesk Fusion UI labels, stable API identifiers and public action input names. +- Maintain separate EN/RU user documentation where a product already has both. Never silently replace either language with spoilers or machine-generated placeholders. +- Respect existing product architecture, UX contracts, tests and CAD compatibility caveats. + +## Git, CI and releasing +- Prefer a small, reviewed PR for CI/publishing changes. Do not force-push or amend public history. Keep direct main pushes possible where repository permissions allow them. +- Do not manually create release tags. A direct push or PR merge to `main` triggers **only if the changed-file set includes shipped runtime inputs**. +- Preserve each repository's `.github/release-paths.txt` as its reviewed release-eligibility allowlist. Pure README, docs, test, workflow, policy and AGENTS.md changes must not create a GitHub Release. +- GitVersion.Tool is pinned to **6.8.2**. Full Git history is required. Published tags, releases and uploaded assets are immutable; never retarget tags, clobber artifacts or downgrade a prerelease to Stable. +- Core shared Actions live at `.github/actions/` and must be pinned by their exact commit SHA in consuming projects. Do not reference the moving `main` branch in production release jobs. +- Only publishing jobs need `contents: write`; package tests, metadata inspection and PR jobs run with least-privilege read permissions. +- A passing offline build or Python test **does not** imply Autodesk Fusion CAD acceptance. Preserve native platform evidence and security/compatibility gates. + +## Quality +- Test common Actions with `python -m unittest discover -s .github/tests -v` and the Shared release platform checks workflow. +- For changed Actions, first merge a tested platform PR, then migrate consumers in separate PRs with green project CI. Avoid changing product runtime sources as part of CI migration. +- Before replacing product packaging commands, verify ZIP contents, manifest version, SHA-256, notes, and OS-platform differences for that product. +- Never place user credentials, secrets, personal CAD files, machine-specific paths or proprietary material into this public repository. + +## Compatibility +- Preserve stable Fusion manifest UUIDs, command IDs, product names, platform-specific assets, supported OS metadata and each repo's installation format. +- Project-level `AGENTS.md` supplements these common expectations and remains authoritative for project-specific API/geometry/UX constraints. From 23eacc643734da00efc4c7a7fc92218eef755d70 Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 10:45:41 +0200 Subject: [PATCH 11/15] docs(platform): codify shared engineering and safe migration rules --- RELEASE_PLATFORM.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 RELEASE_PLATFORM.md diff --git a/RELEASE_PLATFORM.md b/RELEASE_PLATFORM.md new file mode 100644 index 0000000..7e339d3 --- /dev/null +++ b/RELEASE_PLATFORM.md @@ -0,0 +1,44 @@ +# Shared Release Platform + +Central, reusable Actions for 4FusionLab repositories. Source: [4FusionLab/.github](https://github.com/4FusionLab/.github). + +## Compatibility and rollout + +| Action | Purpose | Required context | +| --- | --- | --- | +| `.github/actions/resolve-version` | GitVersion.Tool **6.8.2**, returns numeric version or SemVer | Complete checkout (`fetch-depth: 0`) | +| `.github/actions/runtime-changes` | Compare the full push range to `.github/release-paths.txt` | Full checkout, `before` and `after` commit SHA | +| `.github/actions/release-notes` | Use reviewed version notes or generate from history | Full checkout and writable `runner.temp` file | +| `.github/actions/verify-archive` | Validate package ZIP, SHA-256, optional Fusion manifest and nonempty notes | Built ZIP(s) and checksum files | + +**Pin the action reference to the exact merged platform commit SHA**, not `@main` or a mutable tag. Open a separate consumer PR after the platform tests pass. + +### Read-only release gating example + +```yaml +- uses: actions/checkout@ + with: + fetch-depth: 0 + persist-credentials: false +- id: changes + uses: 4FusionLab/.github/.github/actions/runtime-changes@ + with: + before: ${{ github.event.before }} + after: ${{ github.sha }} + paths-file: .github/release-paths.txt +``` + +A product publishes only on `push` to `main` after its existing tests, build, notes and archive verification pass **and** the runtime-changes Action returns `release=true`. Skip publishing for PR, `workflow_dispatch` and documentation-only changes. + +### Safety contract +- All composite Actions here are **read-only** and create no tags, GitHub Releases or Pages deployments. Final GitHub Release publication stays in the product repository to preserve its acceptance gates, channel semantics and packaging. +- No `contents: write` permission is granted by these Actions. +- A previously published version or mismatched immutable Git tag must never be overwritten. +- Changing tests or docs alone must not create releases. Runtime changes, including additions, deletions and renames, do. +- Do not assume that a successful CI ZIP build is proof of a native Fusion CAD integration test. + +### Execution model + +Repositories keep existing Linux/macOS/Windows CI matrices, Fusion acceptance checks, distribution builders and publishing gates. Centralized Actions only replace duplicated version resolution, path filtering, notes generation and archive validation. + +Platform maintenance: add regression tests in `.github/tests`, pass `.github/workflows/platform-tests.yml`, merge to the platform repository, pin the new SHA in consumer PRs, verify all existing checks, and only then merge consumers. From d4797ffc0682249dec766a7e15b1ae1257a8f371 Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 10:45:53 +0200 Subject: [PATCH 12/15] docs(platform): provide shared PR, issue and security defaults --- .github/PULL_REQUEST_TEMPLATE.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..fb776ac --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,23 @@ +## Summary + +Describe the user-facing value and why this change is needed. + +## Scope and verification + +- [ ] Project-specific `AGENTS.md` and relevant docs were checked +- [ ] Relevant unit/integration tests passed (include commands and results) +- [ ] Impact on native Fusion behaviour and OS compatibility is described +- [ ] Existing Fusion manifest IDs and backward compatibility are preserved +- [ ] No credentials, generated build files or user CAD data added + +## Release impact + +- [ ] Runtime/packaging inputs changed → an automatic release is expected after CI passes on `main` +- [ ] Documentation/tests/CI only → no GitHub Release should be created +- [ ] `.github/release-paths.txt` was updated if shipped-runtime scope changed + +## User documentation + +- [ ] Existing EN and RU guides were updated where relevant, or not applicable + +> Never manually create a tag or GitHub Release for a normal `main` push/merge. This template is a checklist, not an instruction to bypass existing review, platform validation or native-CAD acceptance. From 8d9419cda014afb706048e96216382c6076e199e Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 10:45:55 +0200 Subject: [PATCH 13/15] docs(platform): provide shared PR, issue and security defaults --- .github/ISSUE_TEMPLATE/bug_report.yml | 38 +++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..7ea19df --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,38 @@ +name: Bug report +description: Report a reproducible problem with a 4FusionLab add-in +title: "[Bug] " +labels: ["bug"] +body: + - type: markdown + attributes: + value: "Describe the problem without attaching private CAD data, tokens or credentials." + - type: input + id: fusion + attributes: + label: Autodesk Fusion version + placeholder: "e.g. 2.xxxx" + validations: + required: false + - type: dropdown + id: platform + attributes: + label: Operating system + options: + - macOS + - Windows + - Other / unknown + validations: + required: true + - type: textarea + id: steps + attributes: + label: Reproduction steps + description: Include expected and observed behaviour + validations: + required: true + - type: textarea + id: logs + attributes: + label: Relevant logs or screenshots (redact sensitive information) + validations: + required: false From 74f5370a44b688fb7c6eeeb161b27e58eb71ac7d Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 10:45:57 +0200 Subject: [PATCH 14/15] docs(platform): provide shared PR, issue and security defaults --- .github/ISSUE_TEMPLATE/feature_request.yml | 25 ++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..f82594e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,25 @@ +name: Feature request +description: Suggest a change to an add-in or a new user workflow +title: "[Feature] " +labels: ["enhancement"] +body: + - type: textarea + id: problem + attributes: + label: User problem + description: Explain what you cannot do in Fusion today + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Desired behaviour + description: Include an example modelling scenario and expected outcome + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives and constraints + validations: + required: false From 68839a9d8fa1574aca3d855e01234471127d2250 Mon Sep 17 00:00:00 2001 From: Pavel Kuznetsov Date: Sat, 7 Nov 2026 10:45:59 +0200 Subject: [PATCH 15/15] docs(platform): provide shared PR, issue and security defaults --- SECURITY.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 SECURITY.md diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..fe46751 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,9 @@ +# Security policy + +If you believe you have found a security vulnerability in a 4FusionLab repository or release pipeline, **do not post exploitable details in a public GitHub Issue**. + +Use GitHub's private vulnerability reporting / Security Advisories when enabled for that repository, or contact its maintainers through an existing private communication channel. + +Useful information: affected add-in and version, affected operating systems, severity and impact, private reproduction steps, and proposed mitigation. Never include credentials, customer CAD documents, personal data or sensitive tokens in public reports. + +Security changes are tested and distributed under the same runtime-change GitVersion release policy as other fixes. Product-specific instructions may be stricter.