Universal SEO skill for Claude Code. 26 sub-skills + 19 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, agent readiness (Lighthouse Agentic Browsing, WebMCP, llms.txt), backlinks, local SEO, e-commerce, international SEO, Google APIs, and PDF/Excel reporting. 9 optional extensions for live SEO data.
feat(release): SHA-256 release manifest tooling — release_sign.py + verify_release.py
Daniel144d52f0337e
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex f61c3c7..383bb94 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -55,7 +55,9 @@ jobs:python3 -m py_compile scripts/drift_history.pypython3 -m py_compile scripts/sync_flow.pypython3 -m py_compile scripts/release_report.py- echo "All 32 scripts passed syntax check"+ python3 -m py_compile scripts/release_sign.py+ python3 -m py_compile scripts/verify_release.py+ echo "All 34 scripts passed syntax check"test:name: Test suite (manifests + sync_flow)diff --git a/scripts/release_sign.py b/scripts/release_sign.pynew file mode 100644index 0000000..b23d534--- /dev/null+++ b/scripts/release_sign.py@@ -0,0 +1,187 @@+#!/usr/bin/env python3+"""+Generate a SHA-256 manifest of every git-tracked file in the repository.++The manifest is published alongside each release tag (attached to the+GitHub release artifacts) so users — and the install scripts — can+verify the contents of a checkout against the maintainer's signed+record.++Usage+=====++Generate a manifest for the current working tree::++ python scripts/release_sign.py > release-manifest.json++Compare two manifests to find drift between releases::++ python scripts/release_sign.py --compare old.json new.json++Threat model+============+This manifest defends against tag rewrites and partial supply-chain+tampering where an attacker can modify some repository files but not+the published manifest. It does NOT defend against a fully compromised+release (manifest + files both replaced by an attacker who controls+the GitHub repo). For that level of trust the maintainer signs the+manifest with a GPG key whose fingerprint is published out of band+(SECURITY.md, the maintainer's site, etc.).++Output schema+=============+::++ {+ "version": "v2.0.0", # plugin.json version+ "tag": "v2.0.0", # git tag or "(uncommitted)"+ "commit": "abc123…", # git HEAD+ "generated_at": "2026-05-17T14:32:00Z",+ "files": {+ "scripts/url_safety.py": "<sha256 hex>",+ …+ },+ "tree_sha256": "<sha256 hex of the sorted manifest itself>"+ }++The ``tree_sha256`` field lets a single hash be quoted in a release+note or signed with GPG without needing to attach the whole JSON.+"""++from __future__ import annotations++import argparse+import hashlib+import json+import os+import subprocess+import sys+from datetime import datetime, timezone+from pathlib import Path+from typing import Iterable+++REPO_ROOT = Path(__file__).resolve().parents[1]+++def _git(*args: str) -> str:+ """Run ``git`` from the repo root and return stripped stdout."""+ result = subprocess.run(+ ["git", "-C", str(REPO_ROOT), *args],+ check=True,+ capture_output=True,+ text=True,+ )+ return result.stdout.strip()+++def _git_or_none(*args: str) -> str | None:+ try:+ return _git(*args)+ except subprocess.CalledProcessError:+ return None+++def _tracked_files() -> list[str]:+ """Return every file tracked by git (sorted, repo-relative)."""+ out = _git("ls-files")+ return sorted(line for line in out.splitlines() if line)+++def _sha256(path: Path) -> str:+ h = hashlib.sha256()+ with path.open("rb") as fh:+ for chunk in iter(lambda: fh.read(65536), b""):+ h.update(chunk)+ return h.hexdigest()+++def _read_plugin_version() -> str:+ manifest = REPO_ROOT / ".claude-plugin" / "plugin.json"+ try:+ with manifest.open() as fh:+ return json.load(fh).get("version", "unknown")+ except (OSError, json.JSONDecodeError):+ return "unknown"+++def build_manifest(files: Iterable[str] | None = None) -> dict:+ """Build the SHA-256 manifest for the current working tree."""+ if files is None:+ files = _tracked_files()++ hashes: dict[str, str] = {}+ for rel in files:+ abs_path = REPO_ROOT / rel+ if not abs_path.is_file():+ # Submodule entries and broken symlinks fall through git+ # ls-files; skip them but record the absence.+ continue+ hashes[rel] = _sha256(abs_path)++ # Compute a hash-of-hashes so a single value identifies the whole+ # manifest. Deterministic ordering: sorted file paths, one+ # ``<sha> <path>\n`` line each (matching sha256sum's wire format).+ tree_input = "".join(f"{sha} {path}\n" for path, sha in sorted(hashes.items()))+ tree_sha = hashlib.sha256(tree_input.encode("utf-8")).hexdigest()++ return {+ "version": _read_plugin_version(),+ "tag": _git_or_none("describe", "--tags", "--exact-match") or "(uncommitted)",+ "commit": _git_or_none("rev-parse", "HEAD") or "(uncommitted)",+ "generated_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),+ "files": hashes,+ "tree_sha256": tree_sha,+ }+++def compare(old: dict, new: dict) -> dict:+ """Diff two manifests; return added / removed / changed files."""+ old_files = old.get("files", {})+ new_files = new.get("files", {})+ return {+ "added": sorted(set(new_files) - set(old_files)),+ "removed": sorted(set(old_files) - set(new_files)),+ "changed": sorted(+ p for p in set(new_files) & set(old_files) if old_files[p] != new_files[p]+ ),+ "tree_sha256_old": old.get("tree_sha256"),+ "tree_sha256_new": new.get("tree_sha256"),+ }+++def main() -> int:+ parser = argparse.ArgumentParser(+ description="Generate or compare claude-seo release SHA-256 manifests."+ )+ parser.add_argument(+ "--compare",+ nargs=2,+ metavar=("OLD", "NEW"),+ help="Diff two manifests instead of generating a new one.",+ )+ parser.add_argument(+ "--indent",+ type=int,+ default=2,+ help="JSON indentation (default 2).",+ )+ args = parser.parse_args()++ if args.compare:+ with open(args.compare[0]) as fh:+ old = json.load(fh)+ with open(args.compare[1]) as fh:+ new = json.load(fh)+ json.dump(compare(old, new), sys.stdout, indent=args.indent)+ sys.stdout.write("\n")+ return 0++ manifest = build_manifest()+ json.dump(manifest, sys.stdout, indent=args.indent)+ sys.stdout.write("\n")+ return 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/scripts/verify_release.py b/scripts/verify_release.pynew file mode 100644index 0000000..061a934--- /dev/null+++ b/scripts/verify_release.py@@ -0,0 +1,149 @@+#!/usr/bin/env python3+"""+Verify the integrity of a claude-seo checkout against a release manifest.++Usage+=====++After installing from a tag::++ python scripts/verify_release.py path/to/release-manifest.json++The script returns exit code 0 when every file in the manifest is+present and matches the recorded SHA-256, and exit code 1 (with a+human-readable report) on any mismatch, missing file, or extra file.++This pairs with ``scripts/release_sign.py`` (used by the maintainer to+generate the manifest at release time) and the GitHub release+attachment workflow that publishes the manifest alongside each tag.++Threat model+============+See SECURITY.md "Tampered install" section. Verification catches tag+force-pushes and partial supply-chain tampering, but does NOT defend+against an attacker who can replace both the source files and the+published manifest. For that level of trust, the manifest must be+signed by the maintainer's GPG key whose fingerprint is published+out of band.+"""++from __future__ import annotations++import argparse+import hashlib+import json+import sys+from pathlib import Path+++REPO_ROOT = Path(__file__).resolve().parents[1]+++def _sha256(path: Path) -> str:+ h = hashlib.sha256()+ with path.open("rb") as fh:+ for chunk in iter(lambda: fh.read(65536), b""):+ h.update(chunk)+ return h.hexdigest()+++def verify(manifest_path: Path, root: Path = REPO_ROOT) -> dict:+ """Compare a manifest against the working tree at ``root``.++ Returns a dict with:+ ok : True iff every file in manifest matches.+ manifest : the manifest payload (for the caller to display+ version/tag/commit context).+ mismatched : paths whose SHA-256 differs.+ missing : paths in manifest but absent from disk.+ extra : paths on disk (and git-tracked) but not in+ manifest. Empty unless caller passes a tracked+ file list; default behaviour leaves this empty.+ """+ with manifest_path.open() as fh:+ manifest = json.load(fh)++ expected = manifest.get("files", {})+ mismatched: list[dict] = []+ missing: list[str] = []++ for rel, expected_sha in sorted(expected.items()):+ abs_path = root / rel+ if not abs_path.is_file():+ missing.append(rel)+ continue+ actual_sha = _sha256(abs_path)+ if actual_sha != expected_sha:+ mismatched.append(+ {"path": rel, "expected": expected_sha, "actual": actual_sha}+ )++ return {+ "ok": not (mismatched or missing),+ "manifest": {+ "version": manifest.get("version"),+ "tag": manifest.get("tag"),+ "commit": manifest.get("commit"),+ "generated_at": manifest.get("generated_at"),+ "tree_sha256": manifest.get("tree_sha256"),+ },+ "checked": len(expected),+ "mismatched": mismatched,+ "missing": missing,+ }+++def main() -> int:+ parser = argparse.ArgumentParser(+ description="Verify a claude-seo checkout against a release manifest."+ )+ parser.add_argument(+ "manifest", type=Path, help="Path to release-manifest.json."+ )+ parser.add_argument(+ "--root",+ type=Path,+ default=REPO_ROOT,+ help="Repository root to verify (default: this checkout).",+ )+ parser.add_argument(+ "--json",+ action="store_true",+ help="Emit a JSON report instead of human-readable text.",+ )+ args = parser.parse_args()++ if not args.manifest.is_file():+ print(f"Error: manifest not found: {args.manifest}", file=sys.stderr)+ return 2++ result = verify(args.manifest, args.root)++ if args.json:+ json.dump(result, sys.stdout, indent=2)+ sys.stdout.write("\n")+ else:+ m = result["manifest"]+ status = "OK" if result["ok"] else "FAIL"+ print(f"Verification: {status}")+ print(f" Manifest version: {m['version']} tag: {m['tag']}")+ print(f" Manifest commit: {m['commit']}")+ print(f" Generated at: {m['generated_at']}")+ print(f" Tree SHA-256: {m['tree_sha256']}")+ print(f" Files checked: {result['checked']}")+ if result["mismatched"]:+ print(f"\n Mismatched ({len(result['mismatched'])}):")+ for row in result["mismatched"]:+ print(f" - {row['path']}")+ print(f" expected: {row['expected']}")+ print(f" actual: {row['actual']}")+ if result["missing"]:+ print(f"\n Missing ({len(result['missing'])}):")+ for path in result["missing"]:+ print(f" - {path}")++ return 0 if result["ok"] else 1+++if __name__ == "__main__":+ sys.exit(main())