com.elestrago.unity.package-tools 2.2.3 → 2.4.0

package/Samples~/ClaudeSkills/unity-package-release/scripts/discover_package.py

@@ -0,0 +1,366 @@
+"""Discover the PackageManifestConfig.asset in a Unity-package repo and report
+the fields and files the release skill needs to drive its pipeline.
+
+The skill must not hardcode paths or line numbers because it is shipped to
+multiple repos that all use the same `com.elestrago.unity.package-tools` editor
+tool but differ in their layout, package name, changelog filename, README
+location, and publish flow. Everything repo-specific is read at runtime.
+
+Run from the repo root (default) or pass `--repo <path>`:
+
+    python3 .claude/skills/unity-package-release/scripts/discover_package.py
+
+Output is a single JSON object on stdout. Errors go to stderr; non-zero exit
+codes mean the caller cannot proceed safely.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+
+# A PackageManifestConfig asset is a Unity ScriptableObject with a recognisable
+# set of fields. We detect by signature rather than by path, since the canonical
+# location varies between repos (the package-tool repo keeps it under
+# Assets/PackageManifest/, but consumers are free to put it anywhere under
+# Assets/).
+CONFIG_SIGNATURE_FIELDS = (
+	"packageName:",
+	"packageVersion:",
+	"packageDestinationPath:",
+	"changelogPath:",
+)
+
+# Top-level SO fields in Unity YAML are indented two spaces under `MonoBehaviour:`.
+# Dependency entries are inside a `dependencies:` list and indent four spaces, so
+# the rule "first line matching exactly `^  <field>: `" reliably picks the SO's
+# own value and skips nested `packageVersion:` entries inside dependencies.
+TOP_LEVEL_FIELD_RE = re.compile(r"^  (?P<field>[A-Za-z_][A-Za-z0-9_]*): ?(?P<value>.*)$")
+
+# Inline-list `[a, b, c]` and `[]` show up for string-array fields. We don't
+# parse them here — none of the fields the release skill cares about are arrays
+# of primitives — but the regex above tolerates them by capturing the whole
+# right-hand side as a string.
+
+
+def find_config_asset(repo: Path) -> Path | None:
+	"""Walk `<repo>/Assets/` for the first `.asset` file whose contents contain
+	all of the PackageManifestConfig signature fields. Returns None when no
+	candidate is found — the caller should refuse to proceed in that case."""
+	assets_dir = repo / "Assets"
+	if not assets_dir.is_dir():
+		return None
+	candidates: list[Path] = []
+	for path in assets_dir.rglob("*.asset"):
+		try:
+			head = path.read_text(encoding="utf-8", errors="replace")[:4096]
+		except OSError:
+			continue
+		if all(sig in head for sig in CONFIG_SIGNATURE_FIELDS):
+			candidates.append(path)
+	if not candidates:
+		return None
+	# If multiple configs exist (some repos package more than one), prefer the
+	# one nearest the repo root by path-segment count, then by name for
+	# determinism. Multi-package repos are out of scope for this skill — the
+	# user should pass --config-asset to disambiguate.
+	candidates.sort(key=lambda p: (len(p.relative_to(repo).parts), str(p)))
+	return candidates[0]
+
+
+def parse_config_fields(asset_path: Path) -> dict[str, Any]:
+	"""Extract the top-level scalar fields of a PackageManifestConfig asset.
+	Returns a dict mapping field-name → {"value": str, "line": int} for every
+	top-level field encountered, and a flat dict of values under "_values" for
+	convenience. Skips list-element fields under `dependencies:`, `samples:`,
+	`copyEntries:`, etc., because they sit at four-space indent."""
+	lines = asset_path.read_text(encoding="utf-8").splitlines()
+	fields: dict[str, dict[str, Any]] = {}
+	values: dict[str, str] = {}
+	for idx, raw in enumerate(lines, start=1):
+		m = TOP_LEVEL_FIELD_RE.match(raw)
+		if not m:
+			continue
+		name = m.group("field")
+		val = m.group("value").strip()
+		# Re-occurrences at top level shadow earlier ones; the SO YAML doesn't
+		# normally do that for scalars, but be defensive.
+		fields[name] = {"value": val, "line": idx}
+		values[name] = val
+	return {"_fields": fields, "_values": values}
+
+
+def resolve_repo_relative(repo: Path, value: str) -> Path:
+	"""Mirror the runtime path resolution that
+	`FileTools.CopyOrReplaceFileToDirectory` uses: `Path.GetFullPath(value)` is
+	resolved against the current working directory, which Unity sets to the
+	project root. So a relative path in the asset means "relative to repo
+	root"."""
+	p = Path(value)
+	if p.is_absolute():
+		return p
+	return (repo / p).resolve()
+
+
+def read_last_changelog_heading(changelog_path: Path) -> dict[str, Any] | None:
+	"""Read the first `## ` heading from the changelog and try to extract the
+	version and the URL it links to, so the skill can mirror the same format
+	when prepending a new entry. The skill should not assume any particular URL
+	host — it's free-form text per repo."""
+	if not changelog_path.is_file():
+		return None
+	heading_re = re.compile(r"^##\s+(.*)$")
+	version_in_heading_re = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
+	plain_version_re = re.compile(r"\[?([0-9]+\.[0-9]+\.[0-9]+(?:-[A-Za-z0-9.+-]+)?)\]?")
+	try:
+		text = changelog_path.read_text(encoding="utf-8")
+	except OSError:
+		return None
+	for line in text.splitlines():
+		m = heading_re.match(line)
+		if not m:
+			continue
+		body = m.group(1).strip()
+		linked = version_in_heading_re.search(body)
+		if linked:
+			version = linked.group(1).strip()
+			url = linked.group(2).strip()
+			tag_url_format = url.replace(version, "{version}", 1) if version and version in url else None
+			return {
+				"heading": line.rstrip(),
+				"version": version,
+				"url": url,
+				"tag_url_format": tag_url_format,
+			}
+		# Heading without a markdown link — still useful for showing the user.
+		plain = plain_version_re.search(body)
+		return {
+			"heading": line.rstrip(),
+			"version": plain.group(1) if plain else None,
+			"url": None,
+			"tag_url_format": None,
+		}
+	return None
+
+
+def find_readme_install_snippet(readme_path: Path, package_name: str) -> dict[str, Any] | None:
+	"""Find the consumer-install snippet line in the project-root README — the
+	one that looks like `"com.example.foo": "X.Y.Z"`. Returns the line number,
+	the version string, and the raw line so the skill can do a targeted rewrite
+	without touching anything else in the README. Returns None when the README
+	has no such snippet (some repos document installation differently)."""
+	if not readme_path.is_file():
+		return None
+	pattern = re.compile(r'"' + re.escape(package_name) + r'"\s*:\s*"([^"]+)"')
+	try:
+		text = readme_path.read_text(encoding="utf-8")
+	except OSError:
+		return None
+	for idx, line in enumerate(text.splitlines(), start=1):
+		m = pattern.search(line)
+		if m:
+			return {"line": idx, "version": m.group(1), "raw": line}
+	return None
+
+
+def detect_publish_flow(repo: Path) -> dict[str, Any]:
+	"""Sniff out what publish flow this repo uses. The release skill prints a
+	different handoff block per flow, and the maintainer can override via the
+	`publish-flow=` skill arg. Detection is best-effort — when ambiguous, the
+	skill should ask the user rather than guessing."""
+	gitlab_ci = repo / ".gitlab-ci.yml"
+	github_workflows_dir = repo / ".github" / "workflows"
+	flow: dict[str, Any] = {
+		"gitlab_ci_present": gitlab_ci.is_file(),
+		"gitlab_ci_includes_elestrago_unity_npm": False,
+		"github_workflows_present": github_workflows_dir.is_dir() and any(
+			p.is_file() and p.suffix in {".yml", ".yaml"}
+			for p in github_workflows_dir.iterdir()
+		),
+		"github_workflow_files": [],
+		"detected_flow": "manual",
+	}
+	if gitlab_ci.is_file():
+		try:
+			ci_text = gitlab_ci.read_text(encoding="utf-8")
+		except OSError:
+			ci_text = ""
+		# The shared pipeline include is the signal the skill's original CI
+		# handoff block was written for. Any other GitLab CI setup we treat as
+		# "gitlab-generic" so the skill can degrade gracefully.
+		if "unity-package-npm-publish" in ci_text or "elestrago/ci-pipelines" in ci_text:
+			flow["gitlab_ci_includes_elestrago_unity_npm"] = True
+	if flow["github_workflows_present"]:
+		flow["github_workflow_files"] = sorted(
+			str(p.relative_to(repo)) for p in github_workflows_dir.iterdir()
+			if p.is_file() and p.suffix in {".yml", ".yaml"}
+		)
+	# Prioritise: the elestrago-CI signal is the most specific, then any other
+	# GitLab CI, then GitHub Actions, then manual.
+	if flow["gitlab_ci_includes_elestrago_unity_npm"]:
+		flow["detected_flow"] = "gitlab-elestrago-ci"
+	elif flow["gitlab_ci_present"]:
+		flow["detected_flow"] = "gitlab-generic"
+	elif flow["github_workflows_present"]:
+		flow["detected_flow"] = "github-actions"
+	else:
+		flow["detected_flow"] = "manual"
+	return flow
+
+
+def read_release_package_json(repo: Path, destination_path: str) -> dict[str, Any] | None:
+	"""Read the `package.json` inside the exported destination if it exists.
+	Some CI flows (notably gitlab-elestrago-ci) trigger publishing on a version
+	delta of this file, so the skill needs to know whether it exists and what
+	version it currently advertises — so it can warn when the user is about to
+	skip the Export Package Source step and silently break the publish."""
+	if not destination_path:
+		return None
+	dest = resolve_repo_relative(repo, destination_path)
+	package_json = dest / "package.json"
+	if not package_json.is_file():
+		return {
+			"path": str(package_json.relative_to(repo)) if dest.is_relative_to(repo) else str(package_json),
+			"present": False,
+			"version": None,
+		}
+	try:
+		import json as _json
+		data = _json.loads(package_json.read_text(encoding="utf-8"))
+		version = data.get("version") if isinstance(data, dict) else None
+	except (OSError, ValueError):
+		version = None
+	return {
+		"path": str(package_json.relative_to(repo)) if dest.is_relative_to(repo) else str(package_json),
+		"present": True,
+		"version": version,
+	}
+
+
+def read_git_state(repo: Path) -> dict[str, Any]:
+	"""Best-effort git state. Failures (missing git, not a repo) reduce to
+	empty/null fields rather than aborting — the skill can still do its job
+	without git, just without the convenience signals."""
+	def _run(args: list[str]) -> str | None:
+		try:
+			out = subprocess.check_output(
+				args, cwd=str(repo), stderr=subprocess.DEVNULL, text=True
+			)
+			return out.strip()
+		except (subprocess.CalledProcessError, FileNotFoundError):
+			return None
+	return {
+		"branch": _run(["git", "rev-parse", "--abbrev-ref", "HEAD"]),
+		"remote_url": _run(["git", "remote", "get-url", "origin"]),
+		"recent_commits": _run(["git", "log", "--oneline", "-5"]),
+		"status_porcelain": _run(["git", "status", "--porcelain"]),
+		"diff_stat_head": _run(["git", "diff", "--stat", "HEAD"]),
+	}
+
+
+def discover(repo: Path, override_config: Path | None = None) -> dict[str, Any]:
+	asset = override_config if override_config else find_config_asset(repo)
+	if asset is None or not asset.is_file():
+		return {
+			"ok": False,
+			"error": (
+				"No PackageManifestConfig.asset found under Assets/. This skill "
+				"requires the com.elestrago.unity.package-tools editor tool to be "
+				"installed in the project (it provides the ScriptableObject this "
+				"skill drives)."
+			),
+		}
+	parsed = parse_config_fields(asset)
+	values = parsed["_values"]
+	fields = parsed["_fields"]
+
+	package_name = values.get("packageName", "")
+	package_version = values.get("packageVersion")
+	changelog_path_raw = values.get("changelogPath", "")
+	readme_path_raw = values.get("readmePath", "")
+	license_path_raw = values.get("licensePath", "")
+	documentation_path_raw = values.get("documentationPath", "")
+	destination_path_raw = values.get("packageDestinationPath", "")
+
+	changelog_resolved = resolve_repo_relative(repo, changelog_path_raw) if changelog_path_raw else None
+	readme_resolved = resolve_repo_relative(repo, readme_path_raw) if readme_path_raw else None
+
+	changelog_info = read_last_changelog_heading(changelog_resolved) if changelog_resolved else None
+	readme_snippet = (
+		find_readme_install_snippet(readme_resolved, package_name)
+		if readme_resolved and package_name else None
+	)
+
+	release_json_info = read_release_package_json(repo, destination_path_raw)
+	publish_flow = detect_publish_flow(repo)
+	git_state = read_git_state(repo)
+
+	return {
+		"ok": True,
+		"repo": str(repo),
+		"config_asset": {
+			"path": str(asset.relative_to(repo)) if asset.is_relative_to(repo) else str(asset),
+			"package_version_line": fields.get("packageVersion", {}).get("line"),
+		},
+		"package": {
+			"name": package_name,
+			"display_name": values.get("displayName"),
+			"version": package_version,
+			"unity_version": values.get("unityVersion"),
+			"documentation_path": documentation_path_raw or None,
+			"destination_path": destination_path_raw or None,
+		},
+		"changelog": {
+			"path_in_config": changelog_path_raw or None,
+			"resolved_path": str(changelog_resolved.relative_to(repo)) if changelog_resolved and changelog_resolved.is_relative_to(repo) else (str(changelog_resolved) if changelog_resolved else None),
+			"exists": bool(changelog_resolved and changelog_resolved.is_file()),
+			"latest_heading": changelog_info,
+		},
+		"readme": {
+			"path_in_config": readme_path_raw or None,
+			"resolved_path": str(readme_resolved.relative_to(repo)) if readme_resolved and readme_resolved.is_relative_to(repo) else (str(readme_resolved) if readme_resolved else None),
+			"exists": bool(readme_resolved and readme_resolved.is_file()),
+			"install_snippet": readme_snippet,
+		},
+		"license": {
+			"path_in_config": license_path_raw or None,
+		},
+		"release_package_json": release_json_info,
+		"publish_flow": publish_flow,
+		"git": git_state,
+	}
+
+
+def main() -> int:
+	parser = argparse.ArgumentParser(description=__doc__)
+	parser.add_argument(
+		"--repo",
+		default=os.getcwd(),
+		help="Repository root (defaults to current working directory).",
+	)
+	parser.add_argument(
+		"--config-asset",
+		default=None,
+		help=(
+			"Explicit path to PackageManifestConfig.asset. Use to disambiguate "
+			"in repos that ship multiple configs."
+		),
+	)
+	args = parser.parse_args()
+	repo = Path(args.repo).resolve()
+	override = Path(args.config_asset).resolve() if args.config_asset else None
+	result = discover(repo, override)
+	json.dump(result, sys.stdout, indent=2)
+	sys.stdout.write("\n")
+	return 0 if result.get("ok") else 2
+
+
+if __name__ == "__main__":
+	sys.exit(main())

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "com.elestrago.unity.package-tools",
-  "version": "2.2.3",
+  "version": "2.4.0",
   "displayName": "Package Tool",
   "description": "Tool for create unity packages",
   "category": "unity",
   "unity": "2021.3",
   "homepage": "https://gitlab.com/elestrago-pkg/package-tool",
-  "documentationUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.2.3/README.md",
-  "changelogUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.2.3/CHANGELOG.md",
-  "licensesUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.2.3/LICENSE",
+  "documentationUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.4.0/README.md",
+  "changelogUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.4.0/CHANGELOG.md",
+  "licensesUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.4.0/LICENSE",
   "license": "MIT",
   "keywords": [
     "unity",