strictcli 0.42.0__tar.gz → 0.43.0__tar.gz

{strictcli-0.42.0 → strictcli-0.43.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: strictcli
-Version: 0.42.0
+Version: 0.43.0
 Summary: A CLI framework for the Era of Agents: nothing is inferred, everything is declared. First-class support for Go, Python, and TypeScript (Python implementation)
 Project-URL: Homepage, https://smmh.dev/strictcli/
 Project-URL: Documentation, https://smmh.dev/strictcli/
-Project-URL: Repository, https://github.com/smm-h/strictcli
-Project-URL: Issues, https://github.com/smm-h/strictcli/issues
-Project-URL: Changelog, https://github.com/smm-h/strictcli/blob/main/CHANGELOG.md
+Project-URL: Repository, https://github.com/stricttools/strictcli
+Project-URL: Issues, https://github.com/stricttools/strictcli/issues
+Project-URL: Changelog, https://github.com/stricttools/strictcli/blob/main/CHANGELOG.md
 Author-email: "S. M. Hosseini" <m.hosseini@veliu.com>
 License-Expression: MIT
 License-File: LICENSE
@@ -657,8 +657,8 @@ paths have no TTY contract, so a consequential command is dispatched directly.
 
 ## See also
 
-- [strictcli monorepo](https://github.com/smm-h/strictcli) -- conformance tests, Go implementation, and project documentation
-- [Go implementation](https://github.com/smm-h/strictcli/tree/main/go) -- same semantics, functional options API
+- [strictcli monorepo](https://github.com/stricttools/strictcli) -- conformance tests, Go implementation, and project documentation
+- [Go implementation](https://github.com/stricttools/strictcli/tree/main/go) -- same semantics, functional options API
 
 ## License
 

{strictcli-0.42.0 → strictcli-0.43.0}/README.md

@@ -633,8 +633,8 @@ paths have no TTY contract, so a consequential command is dispatched directly.
 
 ## See also
 
-- [strictcli monorepo](https://github.com/smm-h/strictcli) -- conformance tests, Go implementation, and project documentation
-- [Go implementation](https://github.com/smm-h/strictcli/tree/main/go) -- same semantics, functional options API
+- [strictcli monorepo](https://github.com/stricttools/strictcli) -- conformance tests, Go implementation, and project documentation
+- [Go implementation](https://github.com/stricttools/strictcli/tree/main/go) -- same semantics, functional options API
 
 ## License
 

{strictcli-0.42.0 → strictcli-0.43.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "strictcli"
-version = "0.42.0"
+version = "0.43.0"
 description = "A CLI framework for the Era of Agents: nothing is inferred, everything is declared. First-class support for Go, Python, and TypeScript (Python implementation)"
 readme = "README.md"
 license = "MIT"
@@ -42,6 +42,6 @@ testpaths = ["tests"]
 [project.urls]
 Homepage = "https://smmh.dev/strictcli/"
 Documentation = "https://smmh.dev/strictcli/"
-Repository = "https://github.com/smm-h/strictcli"
-Issues = "https://github.com/smm-h/strictcli/issues"
-Changelog = "https://github.com/smm-h/strictcli/blob/main/CHANGELOG.md"
+Repository = "https://github.com/stricttools/strictcli"
+Issues = "https://github.com/stricttools/strictcli/issues"
+Changelog = "https://github.com/stricttools/strictcli/blob/main/CHANGELOG.md"

{strictcli-0.42.0 → strictcli-0.43.0}/strictcli/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.42.0"
+__version__ = "0.43.0"
 
 __all__ = [
     "App", "Flag", "Arg", "FlagSet",
@@ -15,6 +15,8 @@ __all__ = [
     # The scoped-selector construct (contract §24)
     "Choice", "choice", "choice_flag", "sub_flag", "sub_choice_flag",
     "member_value", "provided",
+    # Retired choices: the value-level twin of the deprecated-command construct
+    "RetiredChoice",
     "Grant", "EffectFailed", "Unsettled", "Completed", "Spawned", "Response",
     "PROC_MUTATE", "PROC_SPAWN", "FILE_WRITE", "NET_MUTATE",
     "flag", "arg",
@@ -2796,36 +2798,89 @@ def _open_is_write_mode(node) -> bool:
     return any(ch in mode for ch in ("w", "a", "x", "+"))
 
 
+class _BypassRootNotAWorkTree(Exception):
+    """The project root handed to the lint is not inside a git work tree."""
+
+
+def _msg_effects_bypass_not_a_work_tree(root: str) -> str:
+    """Message template: the lint's input rule, refused at its one door."""
+    return (
+        f"effects-bypass: project root '{root}' is not a git work tree; "
+        f"the check reads only repository-owned files"
+    )
+
+
+def _bypass_path_is_skipped(rel: str) -> bool:
+    """True when a repository-owned path sits under a skipped directory.
+
+    git lists tracked files wherever they are, including the directories the
+    analyser never reads -- a vendored tree, a committed ``testdata`` or
+    ``build`` directory, a dot-directory's contents. The skip list therefore
+    still applies, now as a filter over git's answer rather than as a walk
+    pruner.
+    """
+    # git reports forward slashes on every platform, so the split is on "/"
+    # rather than os.sep.
+    return any(
+        part in _BYPASS_SKIP_DIRS or part.startswith(".")
+        for part in rel.split("/")[:-1]
+    )
+
+
+def _bypass_repo_files(root: Path) -> list[str]:
+    """The repository-owned Python files under ``root``, relative to it.
+
+    The input set is what git reports: tracked files plus untracked files
+    ``.gitignore`` does not exclude. A release-blocking check reads only inputs
+    the repository owns, so a gitignored scratch file -- present on one machine
+    and absent from a fresh clone -- can never decide the verdict. There is no
+    filesystem-walk fallback: a root outside a work tree is refused.
+    """
+    try:
+        proc = subprocess.run(
+            ["git", "ls-files", "--cached", "--others", "--exclude-standard", "-z"],
+            cwd=str(root),
+            capture_output=True,
+            check=False,
+        )
+    except OSError as exc:
+        raise _BypassRootNotAWorkTree(
+            _msg_effects_bypass_not_a_work_tree(str(root))
+        ) from exc
+    if proc.returncode != 0:
+        raise _BypassRootNotAWorkTree(
+            _msg_effects_bypass_not_a_work_tree(str(root))
+        )
+    listed = proc.stdout.decode("utf-8", "replace").split("\0")
+    return sorted({
+        rel for rel in listed
+        if rel.endswith(".py") and not _bypass_path_is_skipped(rel)
+    })
+
+
 def _scan_effects_bypasses(root: Path) -> list[tuple]:
     """Find direct effect calls REACHABLE FROM a registered command handler.
 
     Returns ``(relative_path, lineno, function_name, target)`` tuples, in file
-    then line order. See :func:`_bypass_reachable_functions` for the scope rule.
+    then line order. See :func:`_bypass_reachable_functions` for the scope rule
+    and :func:`_bypass_repo_files` for the input rule. Raises
+    :class:`_BypassRootNotAWorkTree` when the root is not inside a git work
+    tree.
     """
     findings: list[tuple] = []
-    if not root.is_dir():
-        return findings
-    for dirpath, dirnames, filenames in os.walk(root):
-        dirnames[:] = sorted(
-            d for d in dirnames
-            if d not in _BYPASS_SKIP_DIRS and not d.startswith(".")
-        )
-        for fname in sorted(filenames):
-            if not fname.endswith(".py"):
-                continue
-            path = os.path.join(dirpath, fname)
-            try:
-                tree = ast.parse(Path(path).read_text(encoding="utf-8"), filename=path)
-            except (OSError, SyntaxError, UnicodeDecodeError, ValueError):
-                # A file the analyser cannot read is not evidence of a bypass.
-                continue
-            rel = os.path.relpath(path, root)
-            reachable = _bypass_reachable_functions(tree)
-            if not reachable:
-                continue
-            _bypass_walk(tree, [], reachable, findings, rel,
-                         _bypass_effects_aliases(tree),
-                         _bypass_import_bindings(tree))
+    for rel in _bypass_repo_files(root):
+        path = os.path.join(str(root), rel)
+        try:
+            tree = ast.parse(Path(path).read_text(encoding="utf-8"), filename=path)
+        except (OSError, SyntaxError, UnicodeDecodeError, ValueError):
+            # A file the analyser cannot read is not evidence of a bypass.
+            continue
+        reachable = _bypass_reachable_functions(tree)
+        if not reachable:
+            continue
+        _bypass_walk(tree, [], reachable, findings, rel,
+                     _bypass_effects_aliases(tree),
+                     _bypass_import_bindings(tree))
     return findings
 
 
@@ -4604,6 +4659,7 @@ _SCOPE_FIELD_KEY = "strictcli_scope"
 _RECORD_SOURCES_ATTR = "__strictcli_sources__"
 
 _RECORD_SPELLING = "Choice(<value>, help=...)"
+_RETIRED_RECORD_SPELLING = 'RetiredChoice(<value>, message="<message>")'
 _SELECTOR_SPELLING = "choice_flag(...)"
 _MEMBER_SELECTOR_SPELLING = 'choice_flag(..., elect_by="member-flags")'
 # The payload-carrying member's own declaration, which is where its short goes:
@@ -4636,6 +4692,223 @@ class Choice:
             _require_non_empty_str(self.help, "help", "Choice")
 
 
+@dataclass(frozen=True)
+class RetiredChoice:
+    """One retired spelling of a value flag or positional arg.
+
+    The value-level twin of ``app.deprecate``: a value the declaration used to
+    accept, plus the message that names its replacement. A retired spelling is
+    refused at parse time ahead of the invalid-value check, and it is NOT a
+    choice -- help never lists it, and the published ``value_schema`` enum and
+    the MCP projection derived from it carry the live set only.
+
+    The message is mandatory and non-empty, like every other message the
+    framework prints on a declaration's behalf. There is no exhaustiveness
+    story to tell: a handler never receives a retired value, so no closed set
+    reaches a delivery site.
+    """
+
+    value: object
+    message: str = field(kw_only=True)
+
+
+def _raise_retired_choices_entry_not_record(surface: str, name: str, index: int):
+    """Message template: a bare ``retired_choices=`` entry.
+
+    Python-only. Go's variadic ``RetiredChoices(...RetiredChoiceValue)`` and
+    TypeScript's record type refuse a bare value at compile time, so neither
+    sibling has an input that could produce this line. It mirrors the
+    bare-choice refusal, which is the same mis-declaration one keyword over.
+    """
+    raise ValueError(
+        f'{surface} "{name}": retired_choices entry {index} is a bare value: '
+        f"declare it as {_RETIRED_RECORD_SPELLING}"
+    )
+
+
+def _resolve_retired_choices(
+    surface: str, name: str, entries: object,
+) -> tuple["RetiredChoice", ...]:
+    """Validate a ``retired_choices=`` list's entry SHAPE.
+
+    The per-entry RULES (a live spelling, a duplicate, an empty message) are
+    checked by ``_validate_retired_choices`` once the live choices are known.
+    """
+    if not isinstance(entries, list):
+        _raise_retired_choices_entry_not_record(surface, name, 0)
+    records: list[RetiredChoice] = []
+    for i, entry in enumerate(entries):
+        if not isinstance(entry, RetiredChoice):
+            _raise_retired_choices_entry_not_record(surface, name, i)
+        records.append(entry)
+    return tuple(records)
+
+
+# The registration-time templates, twinned per surface the way Go's err* and
+# TypeScript's err* functions are. Python could parameterize the Flag/Arg
+# prefix into one template, and does elsewhere; here it inlines both so the
+# three implementations share one signature per rule and the parity manifest
+# carries no entry for the family at all.
+
+
+def _raise_flag_retired_choice_is_live(name: str, value: str):
+    raise ValueError(
+        f'Flag "{name}": retired choice \'{value}\' is also a live choice: '
+        f"a value is live or retired, never both"
+    )
+
+
+def _raise_arg_retired_choice_is_live(name: str, value: str):
+    raise ValueError(
+        f'Arg "{name}": retired choice \'{value}\' is also a live choice: '
+        f"a value is live or retired, never both"
+    )
+
+
+def _raise_flag_retired_choice_duplicate(name: str, value: str):
+    raise ValueError(f'Flag "{name}": retired choice \'{value}\' is declared twice')
+
+
+def _raise_arg_retired_choice_duplicate(name: str, value: str):
+    raise ValueError(f'Arg "{name}": retired choice \'{value}\' is declared twice')
+
+
+def _raise_flag_retired_choice_message_empty(name: str, value: str):
+    raise ValueError(
+        f'Flag "{name}": retired choice \'{value}\': message must be a non-empty string'
+    )
+
+
+def _raise_arg_retired_choice_message_empty(name: str, value: str):
+    raise ValueError(
+        f'Arg "{name}": retired choice \'{value}\': message must be a non-empty string'
+    )
+
+
+def _raise_flag_retired_choices_incompatible_bool(name: str):
+    raise ValueError(f'Flag "{name}": retired choices are incompatible with type=bool')
+
+
+def _raise_arg_retired_choices_incompatible_bool(name: str):
+    raise ValueError(f'Arg "{name}": retired choices are incompatible with type=bool')
+
+
+def _raise_flag_default_is_retired_choice(name: str, value: str):
+    raise ValueError(f'Flag "{name}": default \'{value}\' is a retired choice')
+
+
+def _raise_arg_default_is_retired_choice(name: str, value: str):
+    raise ValueError(f'Arg "{name}": default \'{value}\' is a retired choice')
+
+
+def _raise_flag_retired_choice_type_mismatch(name: str, value: str, type_name: str):
+    raise ValueError(
+        f'Flag "{name}": retired choice \'{value}\' is not of type {type_name}'
+    )
+
+
+def _raise_arg_retired_choice_type_mismatch(name: str, value: str, type_name: str):
+    raise ValueError(
+        f'Arg "{name}": retired choice \'{value}\' is not of type {type_name}'
+    )
+
+
+def _raise_flag_retired_choices_require_choices(name: str):
+    raise ValueError(f'Flag "{name}": retired choices require choices')
+
+
+def _raise_arg_retired_choices_require_choices(name: str):
+    raise ValueError(f'Arg "{name}": retired choices require choices')
+
+
+_RETIRED_CHOICE_TEMPLATES = {
+    "Flag": (
+        _raise_flag_retired_choice_is_live,
+        _raise_flag_retired_choice_duplicate,
+        _raise_flag_retired_choice_message_empty,
+        _raise_flag_retired_choices_incompatible_bool,
+        _raise_flag_default_is_retired_choice,
+        _raise_flag_retired_choices_require_choices,
+        _raise_flag_retired_choice_type_mismatch,
+    ),
+    "Arg": (
+        _raise_arg_retired_choice_is_live,
+        _raise_arg_retired_choice_duplicate,
+        _raise_arg_retired_choice_message_empty,
+        _raise_arg_retired_choices_incompatible_bool,
+        _raise_arg_default_is_retired_choice,
+        _raise_arg_retired_choices_require_choices,
+        _raise_arg_retired_choice_type_mismatch,
+    ),
+}
+
+
+def _validate_retired_choices(
+    surface: str,
+    name: str,
+    retired: tuple["RetiredChoice", ...] | None,
+    choices: list | None,
+    item_type: type,
+    has_default: bool,
+    default: object,
+) -> None:
+    """The registration-time guards, one set over both surfaces.
+
+    Every sentence names the CONCEPT ("retired choice") rather than this
+    language's spelling of the declaration, so all three implementations share
+    one signature per rule.
+    """
+    if retired is None:
+        return
+    (
+        is_live, duplicate, message_empty,
+        incompatible_bool, default_is_retired, require_choices, type_mismatch,
+    ) = _RETIRED_CHOICE_TEMPLATES[surface]
+    # The bool refusal comes first so the declaration is named by what it got
+    # wrong: choices are already incompatible with bool, and reporting the
+    # missing choices instead would send a reader to add a declaration the
+    # framework would then refuse for the same reason.
+    if item_type is bool:
+        incompatible_bool(name)
+    if choices is None:
+        require_choices(name)
+    seen: list = []
+    for rc in retired:
+        formatted = _format_value_for_error(rc.value)
+        # The type check comes first: a value of the wrong type can never match
+        # at parse time, so the declaration is dead however it compares against
+        # the live set or against its siblings.
+        if not isinstance(rc.value, item_type):
+            type_mismatch(name, formatted, item_type.__name__)
+        if not isinstance(rc.message, str) or not rc.message.strip():
+            message_empty(name, formatted)
+        if rc.value in choices:
+            is_live(name, formatted)
+        if rc.value in seen:
+            duplicate(name, formatted)
+        seen.append(rc.value)
+    if has_default and default is not None:
+        for rc in retired:
+            if rc.value == default:
+                default_is_retired(name, _format_value_for_error(default))
+
+
+def _retired_choice_message(
+    value: object, retired: tuple["RetiredChoice", ...] | None,
+) -> tuple[str, bool]:
+    """The message declared for a retired spelling, and whether it is retired.
+
+    Retired lists are short and ordered, so the scan mirrors the choices one
+    rather than building a map.
+    """
+    if retired is None:
+        return "", False
+    for rc in retired:
+        if value == rc.value and type(value) is type(rc.value):
+            return rc.message, True
+    return "", False
+
+
 def _raise_choices_entry_not_record(surface: str, name: str, index: int):
     """Message template: a bare `choices=` entry (contract §12.13)."""
     raise ValueError(
@@ -4761,6 +5034,10 @@ class Flag:
     # value list so per-entry help survives to help rendering. Set by
     # __post_init__ from `choices`, never by the caller.
     choice_records: tuple["Choice", ...] | None = None
+    # The spellings this flag USED to accept, each carrying the message that
+    # names its replacement. A retired value is refused at parse time; it is
+    # not a choice, so help and the published value_schema never name it.
+    retired_choices: list | None = None
 
     def __post_init__(self) -> None:
         _require_non_empty_str(self.help, "help", "Flag")
@@ -4943,6 +5220,20 @@ class Flag:
                     f'Flag "{self.name}": type=float requires a float default, '
                     f"got {type(self.default).__name__!r}"
                 )
+        # Retired choices. The entry SHAPE is resolved first, then the rules --
+        # after the live choices are validated, so a declaration that got its
+        # choices wrong is told that first, and BEFORE the default-in-choices
+        # check, so a default naming a retired spelling is answered by the
+        # sentence that names the reason.
+        if self.retired_choices is not None:
+            self.retired_choices = _resolve_retired_choices(
+                "Flag", self.name, self.retired_choices,
+            )
+        _validate_retired_choices(
+            "Flag", self.name, self.retired_choices, self.choices,
+            self.item_type if self.compound == "list" else self.type,
+            self.presence == _PRESENCE_DEFAULT, self.default,
+        )
         # Validate default is in choices. The check applies to declared VALUES
         # only: a required or optional flag has no value to check, and absence
         # is never matched against choices (§23.5).
@@ -4979,6 +5270,8 @@ class Arg:
     item_type: type | None = None
     # The declared `choices=` records (contract §24.2), same as a flag's.
     choice_records: tuple["Choice", ...] | None = None
+    # The arg twin of Flag.retired_choices.
+    retired_choices: list | None = None
 
     def __post_init__(self) -> None:
         _require_non_empty_str(self.help, "help", "Arg")
@@ -5075,6 +5368,17 @@ class Arg:
                         f'Arg "{self.name}": type=str requires a str default, '
                         f"got {type(self.default).__name__!r}"
                     )
+        # Retired choices, ahead of the default-in-choices check for the reason
+        # stated at the flag surface.
+        if self.retired_choices is not None:
+            self.retired_choices = _resolve_retired_choices(
+                "Arg", self.name, self.retired_choices,
+            )
+        _validate_retired_choices(
+            "Arg", self.name, self.retired_choices, self.choices,
+            self.item_type if self.compound == "list" else self.type,
+            self.presence == _PRESENCE_DEFAULT, self.default,
+        )
         # Validate default is in choices -- declared VALUES only (§23.5)
         if self.choices is not None and self.presence == _PRESENCE_DEFAULT:
             if self.default not in self.choices:
@@ -9228,7 +9532,9 @@ class App:
           ctx.effects", so a leaf the handle could not carry must never be a
           finding: the handle's closed method set has no in-process-observe
           method, which is why ``platform.system()`` is exempt while
-          ``os.system(...)`` is not (see :data:`_BYPASS_PROCESS_OS_ONLY`);
+          ``os.system(...)`` is not (see :data:`_BYPASS_PROCESS_OS_ONLY`). It
+          reads only repository-owned files (see :func:`_bypass_repo_files`)
+          and refuses a project root outside a git work tree;
         - ``observe-allowlist-breadth`` (warn) surfaces short
           ``proc_observe_allowlist`` prefixes, which authorize real execution
           under ``--dry-run``;
@@ -9237,7 +9543,13 @@ class App:
           themselves consequential.
         """
         def impl(ctx: CheckContext, reporter: "ErrorReporter") -> "_CheckOutcome":
-            findings = _scan_effects_bypasses(Path(ctx.project_root))
+            try:
+                findings = _scan_effects_bypasses(Path(ctx.project_root))
+            except _BypassRootNotAWorkTree as exc:
+                # The input rule is part of the verdict: a root the repository
+                # does not own is refused here, never scanned another way.
+                reporter.error(str(exc))
+                return reporter.found(str(exc))
             for rel, lineno, func_name, target in findings:
                 reporter.error(
                     f"{rel}:{lineno}: {func_name} calls {target} directly; "
@@ -11419,7 +11731,10 @@ class App:
         # Validate choices for global flags
         for f in self._global_flags:
             if f.name in cli_set:
-                _validate_choices(f.name, cli_set[f.name], f.repeatable, f.choices)
+                _validate_choices(
+                    f.name, cli_set[f.name], f.repeatable, f.choices,
+                    f.retired_choices,
+                )
 
         return cli_set, global_sources, remaining
 
@@ -12734,6 +13049,7 @@ def _validate_choices(
     val: object,
     repeatable: bool,
     choices: list | None,
+    retired: tuple["RetiredChoice", ...] | None = None,
     *,
     is_arg: bool = False,
 ) -> None:
@@ -12745,12 +13061,26 @@ def _validate_choices(
     A None value is exempt from validation: None only arises when the flag or
     arg was not passed (an unset mutex flag, or default=None on an arg) -- a
     CLI-supplied value is never None.
+
+    A RETIRED spelling is checked first, so a reader who typed a value that
+    used to work is told what replaced it instead of being handed the list it
+    is missing from. Every source that reaches this funnel today -- command
+    line, env var, config file, and the programmatic doors -- takes the retired
+    refusal for free; nothing new is resolved here.
     """
-    if choices is None or val is None:
+    if (choices is None and retired is None) or val is None:
         return
     vals = val if repeatable else [val]
     for v in vals:
-        if v not in choices:
+        message, is_retired = _retired_choice_message(v, retired)
+        if is_retired:
+            v_str = _format_value_for_error(v)
+            if is_arg:
+                raise _ParseError(
+                    f"argument '{name}': value '{v_str}' retired: {message}"
+                )
+            raise _ParseError(f"--{name}: value '{v_str}' retired: {message}")
+        if choices is not None and v not in choices:
             choices_str = ", ".join(
                 _format_float_canonical(c) if isinstance(c, float) else str(c)
                 for c in choices
@@ -12913,7 +13243,10 @@ def _validate_and_build_kwargs(
     # Step 5.5: validate choices
     for f in cmd.flags:
         if store.has(f.name):
-            _validate_choices(f.name, store[f.name], f.repeatable, f.choices)
+            _validate_choices(
+                f.name, store[f.name], f.repeatable, f.choices,
+                f.retired_choices,
+            )
 
     # Step 5.6: custom validation. It runs on a SUPPLIED value only: never on
     # absence, and never on a declared default (§23.5's validate row).
@@ -12996,7 +13329,8 @@ def _validate_and_build_kwargs(
     for a in cmd.args:
         if a.name in arg_values:
             _validate_choices(
-                a.name, arg_values[a.name], a.variadic, a.choices, is_arg=True,
+                a.name, arg_values[a.name], a.variadic, a.choices,
+                a.retired_choices, is_arg=True,
             )
 
     # Step 7: build kwargs dict (command flags only)
@@ -13773,7 +14107,7 @@ def _check_scoped_value(
     set and its callback both apply, exactly as they do on the root surface
     (steps 5.5 and 5.6). Only a declared default escapes ``validate``.
     """
-    _validate_choices(f.name, value, f.repeatable, f.choices)
+    _validate_choices(f.name, value, f.repeatable, f.choices, f.retired_choices)
     if f.validate is not None and value is not None:
         for v in (value if f.repeatable else [value]):
             try:
@@ -15606,6 +15940,7 @@ def flag(
     prefixed: bool = True,
     negatable: object = _MISSING,
     choices: list | None = None,
+    retired_choices: list | None = None,
     validate: Callable | None = None,
     repeatable: bool = False,
     unique: object = _MISSING,
@@ -15629,6 +15964,7 @@ def flag(
             prefixed=prefixed,
             negatable=negatable,
             choices=choices,
+            retired_choices=retired_choices,
             validate=validate,
             repeatable=repeatable,
             unique=unique,
@@ -15654,6 +15990,7 @@ def arg(
     variadic: bool = False,
     type: type = str,
     choices: list | None = None,
+    retired_choices: list | None = None,
 ) -> Callable[[F], F]:
     """Module-level decorator to attach an Arg to a command handler."""
 
@@ -15661,6 +15998,7 @@ def arg(
         a = Arg(
             name=name, help=help, presence=presence, default=default,
             variadic=variadic, type=type, choices=choices,
+            retired_choices=retired_choices,
         )
         if not hasattr(func, "_strictcli_args"):
             func._strictcli_args = []
@@ -16859,6 +17197,8 @@ def _serialize_flag(f: Flag) -> dict:
         d["prefixed"] = False
     if f.choice_records is not None:
         d["choices"] = _serialize_choice_records(f.choice_records)
+    if f.retired_choices:
+        d["retired_choices"] = _serialize_retired_choices(f.retired_choices)
     if f.unique is True:
         d["unique"] = True
     # Per-flag conflict mode: serialized only when explicitly set. Absence
@@ -16880,6 +17220,20 @@ def _serialize_flag(f: Flag) -> dict:
     return d
 
 
+def _serialize_retired_choices(retired: tuple["RetiredChoice", ...]) -> dict:
+    """A declaration's retired spellings, as a map from spelling to message.
+
+    SORTED ascending by key -- the treatment a group's `deprecated` map already
+    gets, and for the same reason: a keyed object whose declaration order no
+    implementation is required to retain has sort order as its only reachable
+    canon. The key is the spelling rendered through the error-value formatter,
+    so an int, a float and a string key identically in all three
+    implementations. The map is omitted entirely when nothing is retired.
+    """
+    messages = {_format_value_for_error(rc.value): rc.message for rc in retired}
+    return {key: messages[key] for key in sorted(messages)}
+
+
 def _serialize_choice_object(c: "_ChoiceSpec") -> dict:
     """One choice of one selector: `name`, `help`, and its scope (§25.6).
 
@@ -16982,6 +17336,8 @@ def _serialize_arg(a: Arg) -> dict:
         d["variadic"] = a.variadic
     if a.choice_records is not None:
         d["choices"] = _serialize_choice_records(a.choice_records)
+    if a.retired_choices:
+        d["retired_choices"] = _serialize_retired_choices(a.retired_choices)
     return d