Implement WP-0011 hub service, CLI, and deployment artifacts

Add FederationHubAPI spec, hub registration schema, FastAPI hub with SQLite
persistence, reuse-surface hub CLI client, Dockerfile, and hub tests. Activate
workplan; T05 deploy and T06 ops docs remain open pending railiance01 cutover.

reuse_surface/cli.py

@@ -11,6 +11,7 @@ from jsonschema import Draft202012Validator
 
 from reuse_surface.catalog import write_catalog
 from reuse_surface.federation import write_federated_index
+from reuse_surface import hub_client
 from reuse_surface.graph import check_relations, render_mermaid, write_graph
 from reuse_surface.overlaps import find_overlaps
 from reuse_surface.registry import (
@@ -191,6 +192,101 @@ def cmd_catalog(args: argparse.Namespace) -> int:
     return 0
 
 
+def _hub_url(args: argparse.Namespace) -> str | None:
+    return getattr(args, "hub_url", None)
+
+
+def cmd_hub_status(args: argparse.Namespace) -> int:
+    try:
+        status, payload = hub_client.hub_status(_hub_url(args))
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    if status != 200:
+        print(f"error: hub returned {status}: {payload}", file=sys.stderr)
+        return 1
+    print(f"ok: {payload.get('service')} {payload.get('version')} ({payload.get('status')})")
+    return 0
+
+
+def cmd_hub_list(args: argparse.Namespace) -> int:
+    try:
+        status, payload = hub_client.hub_list(_hub_url(args))
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    if status != 200:
+        print(f"error: hub returned {status}: {payload}", file=sys.stderr)
+        return 1
+    for repo in payload.get("repos", []):
+        enabled = "enabled" if repo.get("enabled") else "disabled"
+        print(f"{repo['repo']}\t{enabled}\t{repo.get('url', '')}")
+    print(f"\n{payload.get('count', 0)} registration(s)")
+    return 0
+
+
+def cmd_hub_show(args: argparse.Namespace) -> int:
+    try:
+        status, payload = hub_client.hub_show(args.repo, _hub_url(args))
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    if status != 200:
+        print(f"error: hub returned {status}: {payload}", file=sys.stderr)
+        return 1
+    print(yaml.safe_dump(payload, sort_keys=False))
+    return 0
+
+
+def cmd_hub_register(args: argparse.Namespace) -> int:
+    body: dict[str, Any] = {
+        "repo": args.repo,
+        "url": args.url,
+        "domain": args.domain,
+        "enabled": args.enabled,
+        "required": args.required,
+    }
+    if args.description:
+        body["description"] = args.description
+    try:
+        status, payload = hub_client.hub_register(body, _hub_url(args))
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    if status != 201:
+        print(f"error: hub returned {status}: {payload}", file=sys.stderr)
+        return 1
+    print(f"ok: registered {args.repo}")
+    return 0
+
+
+def cmd_hub_update(args: argparse.Namespace) -> int:
+    body: dict[str, Any] = {}
+    if args.url is not None:
+        body["url"] = args.url
+    if args.enabled is not None:
+        body["enabled"] = args.enabled
+    if args.required is not None:
+        body["required"] = args.required
+    if args.domain is not None:
+        body["domain"] = args.domain
+    if args.description is not None:
+        body["description"] = args.description
+    if not body:
+        print("error: no fields to update", file=sys.stderr)
+        return 1
+    try:
+        status, payload = hub_client.hub_update(args.repo, body, _hub_url(args))
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    if status != 200:
+        print(f"error: hub returned {status}: {payload}", file=sys.stderr)
+        return 1
+    print(f"ok: updated {args.repo}")
+    return 0
+
+
 def cmd_export(args: argparse.Namespace) -> int:
     index = load_index()
     bundle: dict[str, Any] = {
@@ -316,6 +412,41 @@ def main(argv: list[str] | None = None) -> int:
     )
     graph.set_defaults(func=cmd_graph)
 
+    hub = subparsers.add_parser("hub", help="federation hub client")
+    hub.add_argument(
+        "--hub-url",
+        help="hub base URL (or set REUSE_SURFACE_HUB_URL)",
+    )
+    hub_sub = hub.add_subparsers(dest="hub_command", required=True)
+
+    hub_status = hub_sub.add_parser("status", help="check hub health")
+    hub_status.set_defaults(func=cmd_hub_status)
+
+    hub_list = hub_sub.add_parser("list", help="list registered repos")
+    hub_list.set_defaults(func=cmd_hub_list)
+
+    hub_show = hub_sub.add_parser("show", help="show one registration")
+    hub_show.add_argument("--repo", required=True)
+    hub_show.set_defaults(func=cmd_hub_show)
+
+    hub_register = hub_sub.add_parser("register", help="register a repo index URL")
+    hub_register.add_argument("--repo", required=True)
+    hub_register.add_argument("--url", required=True)
+    hub_register.add_argument("--domain", default="helix_forge")
+    hub_register.add_argument("--description")
+    hub_register.add_argument("--enabled", action=argparse.BooleanOptionalAction, default=True)
+    hub_register.add_argument("--required", action="store_true")
+    hub_register.set_defaults(func=cmd_hub_register)
+
+    hub_update = hub_sub.add_parser("update", help="update a repo registration")
+    hub_update.add_argument("--repo", required=True)
+    hub_update.add_argument("--url")
+    hub_update.add_argument("--domain")
+    hub_update.add_argument("--description")
+    hub_update.add_argument("--enabled", action=argparse.BooleanOptionalAction, default=None)
+    hub_update.add_argument("--required", action=argparse.BooleanOptionalAction, default=None)
+    hub_update.set_defaults(func=cmd_hub_update)
+
     args = parser.parse_args(argv)
     return args.func(args)