Remove stale duplicates; generate the README table from index.yaml (P1)

.github/workflows/validate.yml

@@ -37,6 +37,10 @@ jobs:
         working-directory: sharpmush
         run: dotnet run --project tools/PackageValidator -- ../packages --strict
 
+      - name: Check the README package table matches index.yaml
+        working-directory: packages
+        run: python3 tools/readme-packages-table.py --check
+
       - name: Check PF2e navigation and notice links
         working-directory: packages
         run: python3 tools/check-pf2e-navigation.py

index.yaml

@@ -1,32 +1,6 @@
 name: SharpMUSH Packages
 description: Official softcode packages for SharpMUSH.
 packages:
-  - path: hello-world/
-    package: hello-world
-    version: 1.0.0
-    description: Minimal example — one object, one command
-  - path: who-where/
-    name: Who/Where
-    package: who-where
-    version: 1.2.0
-    description: +who and +where commands
-  - path: bbs-lite/
-    name: BBS Lite
-    package: bbs-lite
-    version: 0.9.0-beta
-    description: Tiny bulletin board — dependencies, configure, cross-package refs
-  - path: starter-area/
-    package: starter-area
-    version: 1.0.0
-    description: Two rooms and linked exits
-  - path: http-handler/
-    package: http-handler
-    version: 1.0.0
-    description: Inbound HTTP verb routers (attach mode)
-  - path: profile-handler/
-    package: profile-handler
-    version: 1.0.0
-    description: Read-only character directory + profile API (requires http-handler)
   - path: roll-tables/
     name: Roll Tables
     package: roll-tables

tools/readme-packages-table.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""Writes the README's package table from index.yaml.
+
+The table sits between the two marker comments in README.md. index.yaml is the
+source: add, bump or describe a package there and run this script.
+
+    python3 tools/readme-packages-table.py          # rewrite README.md
+    python3 tools/readme-packages-table.py --check  # fail if README.md is out of date
+"""
+import argparse
+import pathlib
+import sys
+
+import yaml
+
+ROOT = pathlib.Path(__file__).resolve().parent.parent
+README = ROOT / "README.md"
+INDEX = ROOT / "index.yaml"
+BEGIN = "<!-- packages-table:begin (generated from index.yaml by tools/readme-packages-table.py) -->"
+END = "<!-- packages-table:end -->"
+
+
+def cell(text):
+	return " ".join(str(text).split()).replace("|", "\\|")
+
+
+def table():
+	index = yaml.safe_load(INDEX.read_text(encoding="utf-8"))
+	rows = ["| Package | Version | Description |", "|---|---|---|"]
+	for entry in index["packages"]:
+		path = entry["path"]
+		rows.append(f"| [`{path}`]({path}) | {cell(entry['version'])} | {cell(entry['description'])} |")
+	return "\n".join(rows)
+
+
+def render(readme):
+	start = readme.find(BEGIN)
+	stop = readme.find(END)
+	if start < 0 or stop < start:
+		sys.exit(f"README.md: the markers {BEGIN!r} and {END!r} are missing or out of order.")
+	return readme[: start + len(BEGIN)] + "\n" + table() + "\n" + readme[stop:]
+
+
+def main():
+	parser = argparse.ArgumentParser(allow_abbrev=False)
+	parser.add_argument("--check", action="store_true", help="fail if README.md is out of date")
+	args = parser.parse_args()
+	current = README.read_text(encoding="utf-8")
+	wanted = render(current)
+	if args.check:
+		if current != wanted:
+			print("::error file=README.md::The package table is out of date. Run: python3 tools/readme-packages-table.py")
+			return 1
+		print("README package table matches index.yaml.")
+		return 0
+	if current != wanted:
+		README.write_text(wanted, encoding="utf-8")
+		print("README.md updated.")
+	return 0
+
+
+if __name__ == "__main__":
+	sys.exit(main())