Skip to content

Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.

feat: add Python CI and automated releases

kokorolx5a8a68afb13b
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..a4bde2e
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,19 @@
+name: Python CI
+
+on:
+ pull_request:
+ push:
+ branches: [main]
+
+permissions:
+ contents: read
+
+jobs:
+ test:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-python@v5
+ with:
+ python-version: '3.10'
+ - run: python3 -m unittest discover -s forge/tests
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..532cc62
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,53 @@
+name: Release
+
+on:
+ push:
+ branches: [main]
+
+permissions:
+ contents: write
+
+concurrency:
+ group: release-main
+ cancel-in-progress: false
+
+jobs:
+ release:
+ if: "!startsWith(github.event.head_commit.message, 'chore(release): v')"
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+ - uses: actions/setup-python@v5
+ with:
+ python-version: '3.10'
+ - id: metadata
+ env:
+ REPOSITORY_URL: ${{ github.server_url }}/${{ github.repository }}
+ run: |
+ latest_tag="$(git tag --list 'v*' --sort=-version:refname | head -n 1)"
+ if [ -n "$latest_tag" ]; then
+ git log --format=%B%x1e "$latest_tag..HEAD" > "$RUNNER_TEMP/commits.txt"
+ else
+ git log --format=%B%x1e > "$RUNNER_TEMP/commits.txt"
+ fi
+ result="$(python3 scripts/release_metadata.py --commits-file "$RUNNER_TEMP/commits.txt" --repository-url "$REPOSITORY_URL")"
+ echo "result=$result" >> "$GITHUB_OUTPUT"
+ - name: Commit and tag release
+ if: fromJSON(steps.metadata.outputs.result).release
+ env:
+ VERSION: ${{ fromJSON(steps.metadata.outputs.result).version }}
+ run: |
+ git config user.name "github-actions[bot]"
+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+ git add SKILL.md README.md CHANGELOG.md
+ git commit -m "chore(release): v$VERSION"
+ git tag -a "v$VERSION" -m "v$VERSION"
+ git push origin HEAD:main --follow-tags
+ - name: Create GitHub release
+ if: fromJSON(steps.metadata.outputs.result).release
+ env:
+ GH_TOKEN: ${{ github.token }}
+ VERSION: ${{ fromJSON(steps.metadata.outputs.result).version }}
+ run: gh release create "v$VERSION" --title "v$VERSION" --generate-notes
diff --git a/forge/tests/test_release_metadata.py b/forge/tests/test_release_metadata.py
new file mode 100644
index 0000000..0b85f09
--- /dev/null
+++ b/forge/tests/test_release_metadata.py
@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+SCRIPT = ROOT / "scripts" / "release_metadata.py"
+
+
+class ReleaseMetadataTests(unittest.TestCase):
+ def write_project(self, directory: Path) -> tuple[Path, Path]:
+ (directory / "SKILL.md").write_text("---\nversion: 1.4.1\n---\n", encoding="utf-8")
+ (directory / "README.md").write_text(
+ "[![Version](https://img.shields.io/badge/version-1.4.1-green.svg)](CHANGELOG.md)\n",
+ encoding="utf-8",
+ )
+ (directory / "CHANGELOG.md").write_text(
+ "# Changelog\n\nIntro.\n\n## [1.4.1] — 2026-07-26\n\n- Existing.\n\n"
+ "[1.4.1]: https://github.com/img2threejs/img2threejs/releases/tag/v1.4.1\n",
+ encoding="utf-8",
+ )
+ commits = directory / "commits.txt"
+ return directory, commits
+
+ def run_release(self, directory: Path, commits: Path, dry_run: bool = False) -> subprocess.CompletedProcess[str]:
+ command = [
+ "python3",
+ str(SCRIPT),
+ "--root",
+ str(directory),
+ "--commits-file",
+ str(commits),
+ "--date",
+ "2026-07-26",
+ "--repository-url",
+ "https://github.com/img2threejs/img2threejs",
+ ]
+ if dry_run:
+ command.append("--dry-run")
+ return subprocess.run(
+ command,
+ capture_output=True,
+ check=False,
+ text=True,
+ )
+
+ def test_minor_release_synchronizes_all_version_metadata(self) -> None:
+ with tempfile.TemporaryDirectory() as temporary_directory:
+ project, commits = self.write_project(Path(temporary_directory))
+ commits.write_text("feat: generic image intake\x1efix: image hash stability\x1e", encoding="utf-8")
+
+ result = self.run_release(project, commits)
+
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertEqual(json.loads(result.stdout)["version"], "1.5.0")
+ self.assertIn("version: 1.5.0", (project / "SKILL.md").read_text(encoding="utf-8"))
+ self.assertIn("version-1.5.0-green.svg", (project / "README.md").read_text(encoding="utf-8"))
+ changelog = (project / "CHANGELOG.md").read_text(encoding="utf-8")
+ self.assertIn("## [1.5.0] — 2026-07-26", changelog)
+ self.assertIn("[1.5.0]: https://github.com/img2threejs/img2threejs/compare/v1.4.1...v1.5.0", changelog)
+
+ def test_non_releasable_commits_leave_metadata_unchanged(self) -> None:
+ with tempfile.TemporaryDirectory() as temporary_directory:
+ project, commits = self.write_project(Path(temporary_directory))
+ commits.write_text("docs: clarify usage\x1echore: refresh metadata\x1e", encoding="utf-8")
+ before = (project / "SKILL.md").read_text(encoding="utf-8")
+
+ result = self.run_release(project, commits)
+
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertFalse(json.loads(result.stdout)["release"])
+ self.assertEqual((project / "SKILL.md").read_text(encoding="utf-8"), before)
+
+ def test_dry_run_reports_the_next_version_without_writing_metadata(self) -> None:
+ with tempfile.TemporaryDirectory() as temporary_directory:
+ project, commits = self.write_project(Path(temporary_directory))
+ commits.write_text("fix: image hash stability\x1e", encoding="utf-8")
+ before = (project / "CHANGELOG.md").read_text(encoding="utf-8")
+
+ result = self.run_release(project, commits, dry_run=True)
+
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertEqual(json.loads(result.stdout)["version"], "1.4.2")
+ self.assertEqual((project / "CHANGELOG.md").read_text(encoding="utf-8"), before)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/scripts/release_metadata.py b/scripts/release_metadata.py
new file mode 100644
index 0000000..55e0bb8
--- /dev/null
+++ b/scripts/release_metadata.py
@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from dataclasses import dataclass
+from datetime import date
+from enum import Enum
+from pathlib import Path
+from typing import Final
+
+
+VERSION_PATTERN: Final = re.compile(r"^version: (\d+)\.(\d+)\.(\d+)$", re.MULTILINE)
+BADGE_PATTERN: Final = re.compile(r"version-\d+\.\d+\.\d+-green\.svg")
+HEADING_PATTERN: Final = re.compile(r"^## \[", re.MULTILINE)
+REFERENCE_PATTERN: Final = re.compile(r"^\[", re.MULTILINE)
+BREAKING_PATTERN: Final = re.compile(r"^[a-z]+(?:\([^\n]+\))?!:", re.MULTILINE)
+
+
+class ReleaseLevel(Enum):
+ PATCH = "patch"
+ MINOR = "minor"
+ MAJOR = "major"
+
+
+@dataclass(frozen=True, slots=True)
+class Version:
+ major: int
+ minor: int
+ patch: int
+
+ def __str__(self) -> str:
+ return f"{self.major}.{self.minor}.{self.patch}"
+
+ def bump(self, level: ReleaseLevel) -> "Version":
+ match level:
+ case ReleaseLevel.PATCH:
+ return Version(self.major, self.minor, self.patch + 1)
+ case ReleaseLevel.MINOR:
+ return Version(self.major, self.minor + 1, 0)
+ case ReleaseLevel.MAJOR:
+ return Version(self.major + 1, 0, 0)
+ case unreachable:
+ raise AssertionError(f"unhandled release level: {unreachable}")
+
+
+@dataclass(frozen=True, slots=True)
+class ReleasePlan:
+ current: Version
+ next: Version
+ level: ReleaseLevel
+ commits: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ReleaseRequest:
+ root: Path
+ commits: tuple[str, ...]
+ release_date: str
+ repository_url: str
+ dry_run: bool
+
+
+def release_level(commits: tuple[str, ...]) -> ReleaseLevel | None:
+ if any("BREAKING CHANGE:" in commit or BREAKING_PATTERN.search(commit) for commit in commits):
+ return ReleaseLevel.MAJOR
+ if any(commit.lstrip().startswith("feat") for commit in commits):
+ return ReleaseLevel.MINOR
+ if any(commit.lstrip().startswith("fix") for commit in commits):
+ return ReleaseLevel.PATCH
+ return None
+
+
+def parse_version(skill_text: str) -> Version:
+ match = VERSION_PATTERN.search(skill_text)
+ if match is None:
+ raise ValueError("SKILL.md must contain one semantic version front-matter field")
+ return Version(*(int(value) for value in match.groups()))
+
+
+def parse_commits(commits_text: str) -> tuple[str, ...]:
+ return tuple(commit.strip() for commit in commits_text.split("\x1e") if commit.strip())
+
+
+def change_sections(commits: tuple[str, ...]) -> str:
+ features = [commit.splitlines()[0].removeprefix("feat: ") for commit in commits if commit.lstrip().startswith("feat")]
+ fixes = [commit.splitlines()[0].removeprefix("fix: ") for commit in commits if commit.lstrip().startswith("fix")]
+ breaking = [commit.splitlines()[0] for commit in commits if "BREAKING CHANGE:" in commit or BREAKING_PATTERN.search(commit)]
+ sections: list[str] = []
+ if breaking:
+ sections.extend(["### Breaking Changes", *(f"- {item}" for item in breaking), ""])
+ if features:
+ sections.extend(["### Added", *(f"- {item}" for item in features), ""])
+ if fixes:
+ sections.extend(["### Fixed", *(f"- {item}" for item in fixes), ""])
+ return "\n".join(sections).rstrip()
+
+
+def replace_once(pattern: re.Pattern[str], text: str, replacement: str, description: str) -> str:
+ updated, replacements = pattern.subn(replacement, text, count=1)
+ if replacements != 1:
+ raise ValueError(f"{description} must contain exactly one replaceable version")
+ return updated
+
+
+def update_changelog(changelog: str, plan: ReleasePlan, release_date: str, repository_url: str) -> str:
+ heading = f"## [{plan.next}] — {release_date}\n\n{change_sections(plan.commits)}\n\n"
+ heading_match = HEADING_PATTERN.search(changelog)
+ if heading_match is None:
+ raise ValueError("CHANGELOG.md must contain a version heading")
+ with_heading = changelog[:heading_match.start()] + heading + changelog[heading_match.start():]
+ reference_match = REFERENCE_PATTERN.search(with_heading)
+ if reference_match is None:
+ raise ValueError("CHANGELOG.md must contain version reference links")
+ reference = f"[{plan.next}]: {repository_url}/compare/v{plan.current}...v{plan.next}\n"
+ return with_heading[:reference_match.start()] + reference + with_heading[reference_match.start():]
+
+
+def apply_release(request: ReleaseRequest) -> ReleasePlan | None:
+ level = release_level(request.commits)
+ if level is None:
+ return None
+ skill_path = request.root / "SKILL.md"
+ readme_path = request.root / "README.md"
+ changelog_path = request.root / "CHANGELOG.md"
+ skill_text = skill_path.read_text(encoding="utf-8")
+ current = parse_version(skill_text)
+ plan = ReleasePlan(current=current, next=current.bump(level), level=level, commits=request.commits)
+ updated_skill = replace_once(VERSION_PATTERN, skill_text, f"version: {plan.next}", "SKILL.md")
+ readme_text = readme_path.read_text(encoding="utf-8")
+ updated_readme = replace_once(BADGE_PATTERN, readme_text, f"version-{plan.next}-green.svg", "README.md")
+ changelog_text = changelog_path.read_text(encoding="utf-8")
+ updated_changelog = update_changelog(changelog_text, plan, request.release_date, request.repository_url)
+ if request.dry_run:
+ return plan
+ skill_path.write_text(updated_skill, encoding="utf-8")
+ readme_path.write_text(updated_readme, encoding="utf-8")
+ changelog_path.write_text(updated_changelog, encoding="utf-8")
+ return plan
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--root", type=Path, default=Path.cwd())
+ parser.add_argument("--commits-file", type=Path, required=True)
+ parser.add_argument("--date", default=date.today().isoformat())
+ parser.add_argument("--repository-url", required=True)
+ parser.add_argument("--dry-run", action="store_true")
+ arguments = parser.parse_args()
+ commits = parse_commits(arguments.commits_file.read_text(encoding="utf-8"))
+ request = ReleaseRequest(arguments.root, commits, arguments.date, arguments.repository_url, arguments.dry_run)
+ plan = apply_release(request)
+ if plan is None:
+ print(json.dumps({"release": False}))
+ return 0
+ print(json.dumps({"release": True, "version": str(plan.next), "level": plan.level.value}))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())