Add USK version override support to update releaser

Author: leumor

update_releaser/README.md

@@ -79,6 +79,10 @@ gh auth status
   - Override values must be integer digits only (for example `123`).
   - Optional `--prompt-staging-version-override` asks interactively for a staging override; press Enter to keep the default edition.
   - Passing either staging override option while `--publish-to production` is rejected.
+- Published USK version override:
+  - Optional `--usk-version-override <value>` can force which USK edition `core-info.json` is inserted to for `publish-descriptor` and `promote`.
+  - Values must be URI-safe segments using letters, digits, `.`, `_`, or `-`.
+  - If omitted, publish auto-selects the next available numeric USK version.
 
 ## Quickstart
 
@@ -106,6 +110,7 @@ uv run update-releaser promote \
   "https://github.com/crypta-network/cryptad/releases/tag/v1" \
   --publish-to staging \
   --staging-version-override "123" \
+  --usk-version-override "456" \
   --staging-usk-file ./staging-usk.txt \
   --workdir ./dist
 ```
@@ -185,6 +190,7 @@ uv run update-releaser generate-core-info "$RELEASE_URL" \
 
 uv run update-releaser publish-descriptor "$RELEASE_URL" \
   --publish-to staging \
+  --usk-version-override "456" \
   --staging-usk-file ./staging-usk.txt \
   --fcp-host "$FCP_HOST" \
   --fcp-port "$FCP_PORT" \
@@ -216,6 +222,7 @@ workdir (`./dist-promote/<edition>/`).
 uv run update-releaser promote "$RELEASE_URL" \
   --github-source gh \
   --publish-to staging \
+  --usk-version-override "456" \
   --staging-usk-file ./staging-usk.promote.txt \
   --fcp-host "$FCP_HOST" \
   --fcp-port "$FCP_PORT" \
@@ -289,6 +296,7 @@ For edition `123`, default output root is `dist/123/`:
 
 - `version` in `core-info.json` is always a string containing integer digits only.
 - By default, descriptor `version` equals the release edition. For staging publishes, you may override it with `--staging-version-override` or `--prompt-staging-version-override` (digits only).
+- By default, publish probes for the next available numeric USK version segment. You may force a specific publish target edition with `--usk-version-override` on `publish-descriptor` and `promote`.
 - Edition derivation:
   - `v<digits>` becomes `<digits>`
   - non-numeric tags are sanitized into stable path-safe edition strings

update_releaser/src/update_releaser/cli.py

@@ -5,6 +5,7 @@
 import logging
 import os
 from pathlib import Path
+import re
 from typing import Sequence
 
 from update_releaser.fcp_client import FCPClient
@@ -93,6 +94,7 @@ def _build_parser() -> argparse.ArgumentParser:
     _add_release_args(publish_parser)
     _add_fcp_args(publish_parser)
     _add_publish_args(publish_parser)
+    _add_usk_version_override_arg(publish_parser)
     _add_staging_version_override_args(publish_parser)
     publish_parser.set_defaults(handler=_handle_publish_descriptor)
 
@@ -125,6 +127,7 @@ def _build_parser() -> argparse.ArgumentParser:
     _add_release_args(promote_parser)
     _add_fcp_args(promote_parser)
     _add_publish_args(promote_parser)
+    _add_usk_version_override_arg(promote_parser)
     _add_changelog_args(promote_parser)
     _add_staging_version_override_args(promote_parser)
     promote_parser.add_argument(
@@ -299,6 +302,18 @@ def _add_staging_version_override_args(parser: argparse.ArgumentParser) -> None:
     )
 
 
+def _add_usk_version_override_arg(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--usk-version-override",
+        default=None,
+        help=(
+            "Override the USK edition segment where core-info.json is inserted. "
+            "Must be a non-empty URI-safe segment using letters, digits, '.', '_' or '-'. "
+            "If omitted, defaults to the next available USK version."
+        ),
+    )
+
+
 def _handle_fetch_assets(args: argparse.Namespace) -> int:
     workflow = _build_workflow(args)
     assets = workflow.fetch_assets()
@@ -354,13 +369,15 @@ def _handle_publish_descriptor(args: argparse.Namespace) -> int:
         args,
         publish_to=args.publish_to,
     )
+    usk_version_override = _resolve_usk_version_override(args)
     with _fcp_context(args) as fcp:
         result_uri = workflow.publish_descriptor(
             publish_to=args.publish_to,
             staging_usk_file=staging_usk_file,
             fcp=fcp,
             put_options=put_options,
             staging_version_override=staging_version_override,
+            usk_version_override=usk_version_override,
         )
     LOGGER.info("Published descriptor URI: %s", result_uri)
     return 0
@@ -391,6 +408,7 @@ def _handle_promote(args: argparse.Namespace) -> int:
         args,
         publish_to=args.publish_to,
     )
+    usk_version_override = _resolve_usk_version_override(args)
 
     workflow.fetch_assets()
     with _fcp_context(args) as fcp:
@@ -408,6 +426,7 @@ def _handle_promote(args: argparse.Namespace) -> int:
             fcp=fcp,
             put_options=put_options,
             staging_version_override=staging_version_override,
+            usk_version_override=usk_version_override,
         )
         report = workflow.verify(
             publish_to=args.publish_to,
@@ -486,6 +505,23 @@ def _normalized_version_text(raw: str | None) -> str | None:
     return normalized
 
 
+def _resolve_usk_version_override(args: argparse.Namespace) -> str | None:
+    return _normalized_usk_version_text(args.usk_version_override)
+
+
+def _normalized_usk_version_text(raw: str | None) -> str | None:
+    if raw is None:
+        return None
+    normalized = raw.strip()
+    if not normalized:
+        raise ValueError("USK version override must not be empty.")
+    if not re.fullmatch(r"[A-Za-z0-9._-]+", normalized):
+        raise ValueError(
+            "USK version override must contain only letters, digits, '.', '_' or '-'."
+        )
+    return normalized
+
+
 def _build_workflow(args: argparse.Namespace) -> ReleaseWorkflow:
     release_ref = parse_release_page_url(args.release_url)
     return ReleaseWorkflow(