Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

chore: refactor self command domain (#4685)

Manfred Riem9f745f65c8e3
diff --git a/design/cli.md b/design/cli.md
index 9ee3c91a9..0829df74f 100644
--- a/design/cli.md
+++ b/design/cli.md
@@ -167,6 +167,15 @@ Do not add a nested `_commands.py` merely for symmetry. Create one only when
the nested group develops substantial shared command infrastructure that no
longer fits cleanly in `__init__.py` and `_helpers.py`.
+### Singular command groups
+
+Use the repository's plural command-package convention even when a user-facing
+CLI namespace is singular. The `specify self` group therefore lives in
+`specify_cli/selfs/`, while the established `specify_cli._version` module
+remains the version-domain API and monkeypatch surface. The command adapters
+resolve patch-owned `_version` attributes at execution time, and `_version`
+re-exports the command symbols for compatibility.
+
Do not create a nested directory for an implementation phase that is not a CLI
subcommand. For example, an `update/` directory would incorrectly suggest an
`extension update ...` subcommand group. Use `_command_update_<phase>.py`
diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py
index 126713538..95e023eed 100644
--- a/src/specify_cli/__init__.py
+++ b/src/specify_cli/__init__.py
@@ -70,10 +70,10 @@ from ._utils import (
)
from ._version import (
GITHUB_API_LATEST as GITHUB_API_LATEST,
- self_app as _self_app,
- self_check as self_check,
- self_upgrade as self_upgrade,
)
+from .selfs import self_app as _self_app
+from .selfs import self_check as self_check
+from .selfs import self_upgrade as self_upgrade
from ._agent_config import (
AGENT_CONFIG as AGENT_CONFIG,
DEFAULT_INIT_INTEGRATION as DEFAULT_INIT_INTEGRATION,
diff --git a/src/specify_cli/_version.py b/src/specify_cli/_version.py
index 962e3adff..93b4c6a61 100644
--- a/src/specify_cli/_version.py
+++ b/src/specify_cli/_version.py
@@ -1,8 +1,9 @@
-"""Version checking and self-update commands for specify_cli.
+"""Version checking and self-update domain for specify_cli.
Pure helpers for comparing PEP 440 versions and fetching the latest GitHub
-release tag. The ``self_app`` Typer sub-command group is co-located here so
-all version-related logic lives in one place.
+release tag. This module preserves the established ``specify_cli._version``
+import and monkeypatch surface while ``specify_cli.selfs`` owns the
+``specify self`` command adapters.
Dependencies: stdlib + packaging + ._console + ._download_security only
(keeping this layer thin and circular-import-safe).
@@ -27,8 +28,6 @@ from pathlib import Path
import typer
from packaging.version import InvalidVersion, Version
-from rich.markup import escape as _escape_markup
-
from ._download_security import MAX_JSON_METADATA_BYTES, read_response_limited
from ._console import console
@@ -1136,312 +1135,12 @@ def _emit_failure(
raise RuntimeError(f"Unknown failure category: {category!r}")
-# ===== Self Commands =====
-self_app = typer.Typer(
- name="self",
- help=(
- "Manage the specify CLI itself: check for newer releases, "
- "preview upgrades with --dry-run, and upgrade in place."
- ),
- add_completion=False,
-)
-
-
-@self_app.command("check")
-def self_check() -> None:
- """Check whether a newer specify-cli release is available. Read-only.
-
- This command only checks for updates; it does not modify your installation.
- Use `specify self upgrade` to actually perform the upgrade once you've seen
- the result here, or `specify self upgrade --dry-run` to preview the
- installer command without running it.
- """
-
- installed = _get_installed_version()
- tag, failure_reason = _fetch_latest_release_tag()
-
- if tag is None:
- # Graceful-failure path (FR-008). `failure_reason` is one of the
- # enumerated strings produced by _fetch_latest_release_tag() β€” it
- # never contains a URL, headers, response body, or traceback.
- assert failure_reason is not None
- console.print(f"Installed: {installed}")
- console.print(f"[yellow]Could not check latest release:[/yellow] {failure_reason}")
- return
+def _command_exports():
+ """Load the nested self command group after the domain API is defined."""
+ from .selfs import self_app, self_check, self_upgrade
- manual_tag = _manual_tag_or_placeholder(tag)
- latest_display = manual_tag or _MANUAL_TAG_PLACEHOLDER
+ return self_app, self_check, self_upgrade
- if manual_tag is None:
- if installed == "unknown":
- console.print("Current version could not be determined.")
- console.print(f"Latest release: {latest_display}")
- else:
- console.print(f"Installed: {installed}")
- console.print(f"Latest release: {latest_display}")
- console.print("[yellow]Could not validate latest release tag from GitHub.[/yellow]")
- console.print("\nManual fallback:")
- console.print(
- f" uv tool install specify-cli --force --from {_manual_source_spec(manual_tag)}"
- )
- console.print(f" pipx install --force {_manual_source_spec(manual_tag)}")
- return
- if installed == "unknown":
- # FR-020: surface the latest release and the recovery action even
- # when the local distribution metadata is unavailable.
- console.print("Current version could not be determined.")
- console.print(f"Latest release: {latest_display}")
- console.print("\nManual fallback:")
- console.print(
- f" uv tool install specify-cli --force --from {_manual_source_spec(manual_tag)}"
- )
- console.print(f" pipx install --force {_manual_source_spec(manual_tag)}")
- console.print("\nIf this install can still be detected:")
- console.print(" specify self upgrade")
- return
-
- latest_normalized = _normalize_tag(manual_tag)
- if _is_newer(latest_normalized, installed):
- console.print(f"[green]Update available:[/green] {installed} β†’ {latest_display}")
- console.print("\nTo upgrade:")
- console.print(" specify self upgrade")
- console.print("\nManual fallback:")
- console.print(
- f" uv tool install specify-cli --force --from {_manual_source_spec(manual_tag)}"
- )
- console.print(f" pipx install --force {_manual_source_spec(manual_tag)}")
- return
-
- # Reached only when manual_tag parsed cleanly β€” the unparseable-latest case
- # already returned at the `manual_tag is None` branch above β€” and installed
- # is parseable AND >= latest β†’ "up to date" (FR-006). Do not reintroduce an
- # InvalidVersion-fallback assumption here.
- console.print(f"[green]Up to date:[/green] {installed}")
-
-
-@self_app.command("upgrade")
-def self_upgrade(
- dry_run: bool = typer.Option(
- False,
- "--dry-run",
- help="Print the preview (method, current, target, installer argv) and "
- "exit 0 without launching the installer subprocess.",
- ),
- tag: str | None = typer.Option(
- None,
- "--tag",
- # Typer renders help through Rich, so escape the literal bracket (\[)
- # or `[suffix]` is parsed as a style tag and dropped -- `--help` then
- # advertises only `(vX.Y.Z)`, contradicting docs/upgrade.md and README.
- help="Pin the target version (vX.Y.Z\\[suffix]). Without --tag, the "
- "latest stable release is resolved via GitHub Releases.",
- ),
-) -> None:
- """Upgrade specify-cli to the latest release (or a pinned --tag).
-
- Bare invocation executes immediately with no confirmation prompt, matching
- pip install -U / uv tool upgrade / npm update conventions. Use --dry-run
- to preview without mutating anything. See `specify self check` for the
- non-destructive read-only counterpart.
-
- Detection classifies the runtime into uv-tool / pipx / uvx (ephemeral) /
- source-checkout / unsupported. Only uv-tool and pipx are upgraded
- automatically; the other three paths print path-specific guidance and
- exit 0.
-
- Exit codes:
- 0 success or no-op-success (already on latest, --dry-run, or
- non-upgradable path with guidance shown)
- 1 target-tag resolution failure or --tag regex validation failure
- 2 verification mismatch when the installer exited 0 but
- `specify --version` does not resolve to the target tag; if the
- installer itself exits 2, that installer failure code is
- propagated verbatim
- 3 installer binary not found on PATH, or resolved installer path is
- missing / non-executable
- 124 internal installer timeout when SPECIFY_UPGRADE_TIMEOUT_SECS is set,
- or a real installer exit code 124 propagated verbatim; scripts
- should treat 124 as ambiguous and inspect the failure message
- other installer exit code propagated verbatim
-
- Environment variables:
- SPECIFY_UPGRADE_TIMEOUT_SECS Optional integer/float seconds. Caps how
- long the installer subprocess may run. Unset (default) means no
- timeout β€” interrupt with Ctrl+C if the installer hangs.
- """
- if tag is not None:
- try:
- tag = _validate_tag(tag)
- except typer.BadParameter as exc:
- # Escape at the print site rather than baking `\[` into
- # _INVALID_TAG_MESSAGE: the message is also raised through
- # typer.BadParameter, which Click renders without Rich, so the
- # constant must stay plain text. Unescaped, Rich parses the literal
- # `[suffix]` as a style tag and drops it, leaving the user with
- # "expected vMAJOR.MINOR.PATCH" -- implying a bare vX.Y.Z is the only
- # accepted form when -rc1 / .dev0 / +build.42 are all valid.
- console.print(_escape_markup(str(exc)), soft_wrap=True)
- raise typer.Exit(1) from exc
-
- plan, failure_reason = _build_upgrade_plan(target_tag_override=tag)
-
- # Resolver could not produce a tag β†’ surface the categorized failure
- # and exit non-zero so scripts notice (action-oriented unlike `self check`).
- if plan is None:
- if failure_reason is None:
- # _build_upgrade_plan's contract: if plan is None, failure_reason
- # is set. Defend explicitly so the guard survives `python -O`.
- raise RuntimeError(
- "internal contract violation: _build_upgrade_plan returned (None, None)"
- )
- _emit_failure(failure_reason)
- raise typer.Exit(1)
-
- if failure_reason is not None:
- _emit_failure(failure_reason, plan=plan)
- raise typer.Exit(1)
-
- # --dry-run preview path. Non-upgradable methods still emit guidance
- # rather than a fake preview block β€” there is nothing to preview when
- # there is nothing the CLI would launch.
- if dry_run:
- if plan.method in (
- _InstallMethod.UVX_EPHEMERAL,
- _InstallMethod.SOURCE_CHECKOUT,
- _InstallMethod.UNSUPPORTED,
- ):
- _emit_guidance(plan.method, plan.target_tag)
- raise typer.Exit(0)
- console.print("Dry run β€” no changes will be made.")
- for line in plan.preview_summary.splitlines():
- console.print(line)
- raise typer.Exit(0)
-
- # Non-upgradable runtime: never launch an installer regardless of flags.
- if plan.method in (
- _InstallMethod.UVX_EPHEMERAL,
- _InstallMethod.SOURCE_CHECKOUT,
- _InstallMethod.UNSUPPORTED,
- ):
- _emit_guidance(plan.method, plan.target_tag)
- raise typer.Exit(0)
-
- if plan.installer_argv is None:
- _emit_failure(
- _FAILURE_INSTALLER_MISSING,
- plan=plan,
- installer_name=_installer_binary_name(plan.method),
- )
- raise typer.Exit(3)
-
- if plan.target_tag is None:
- raise RuntimeError("Upgrade target tag is required for upgradable install methods")
- target_tag = plan.target_tag
- target_version = _parse_version_text(target_tag)
- if target_version is None:
- # _build_upgrade_plan() and _validate_tag() should reject bad targets
- # before this point; keep this guard as a defensive invariant check.
- _emit_failure(_FAILURE_TARGET_TAG_UNPARSEABLE, plan=plan)
- raise typer.Exit(1)
- if plan.current_version != "unknown":
- current_version = _parse_version_text(plan.current_version)
- # target_version and current_version are Version instances here, so use
- # packaging's ordering/equality directly rather than comparing canonical
- # strings: Version("1.0") == Version("1.0.0") yet their str() forms
- # differ, so canonical-string equality would misreport equal versions as
- # "or newer". The unparseable-current case stays explicit via the
- # `current_version is not None` guard.
- if tag is None and current_version is not None and not (
- target_version > current_version
- ):
- if target_version == current_version:
- console.print(f"Already on latest release: {target_tag}")
- else:
- console.print(f"Already on latest release or newer: {plan.current_version}")
- raise typer.Exit(0)
- # Pinned upgrades are no-ops only on an exact parseable match β€” the same
- # Version equality used by the unpinned branch above; an unparseable
- # current version deliberately proceeds to installation.
- if (
- tag is not None
- and current_version is not None
- and target_version == current_version
- ):
- console.print(f"Already on requested release: {target_tag}")
- raise typer.Exit(0)
-
- # One-line pre-execution notice so the user sees exactly what will run
- # before the installer's own output starts streaming. A pinned target older
- # than the installed version is a downgrade β€” say so explicitly so
- # `--tag <older>` does not masquerade as a forward upgrade.
- installed_version = _parse_version_text(plan.current_version)
- verb = (
- "Downgrading"
- if tag is not None
- and installed_version is not None
- and target_version < installed_version
- else "Upgrading"
- )
- argv_str = _render_argv(plan.installer_argv) if plan.installer_argv else ""
- console.print(
- f"{verb} specify-cli {plan.current_version} β†’ {plan.target_tag} "
- f"via {_method_label(plan.method)}: {argv_str}",
- soft_wrap=True,
- )
-
- # Launch the installer. Stdout/stderr stream through (no capture) so the
- # user sees real-time progress. We never pass shell=True.
- installer_result = _run_installer(plan)
- installer_name = plan.installer_argv[0] if plan.installer_argv else None
-
- if installer_result.kind == _InstallerResultKind.MISSING:
- _emit_failure(_FAILURE_INSTALLER_MISSING, plan=plan, installer_name=installer_name)
- raise typer.Exit(3)
-
- if installer_result.kind == _InstallerResultKind.INVALID:
- _emit_failure(_FAILURE_INSTALLER_INVALID, plan=plan, installer_name=installer_name)
- raise typer.Exit(3)
-
- if installer_result.kind == _InstallerResultKind.TIMEOUT:
- _emit_failure(_FAILURE_INSTALLER_TIMEOUT, plan=plan)
- raise typer.Exit(124)
-
- if (
- installer_result.kind != _InstallerResultKind.EXITED
- or installer_result.returncode is None
- ):
- raise RuntimeError(f"Unknown installer result: {installer_result!r}")
-
- if installer_result.returncode != 0:
- _emit_failure(
- _FAILURE_INSTALLER_FAILED,
- plan=plan,
- installer_exit=installer_result.returncode,
- )
- raise typer.Exit(installer_result.returncode)
-
- # Verify in a child process: this Python process is still running the
- # pre-upgrade module, so importlib.metadata would lie. A fresh `specify
- # --version` is the only signal that the new binary is actually live.
- verified = _verify_upgrade(plan)
- # Compare as Version instances, not canonical strings: _canonicalize_version_text
- # falls back to _normalize_tag() on unparseable input, so two raw strings could
- # coincidentally match. Requiring a parseable verified version that equals the
- # (already-parsed) target makes a non-version verifier result a mismatch (exit 2)
- # rather than a silently-masked "success".
- verified_version = _parse_version_text(verified) if verified is not None else None
- if verified_version is None or verified_version != target_version:
- _emit_failure(
- _FAILURE_VERIFICATION_MISMATCH,
- plan=plan,
- verified_version=verified,
- )
- raise typer.Exit(2)
-
- pre_upgrade_display = _canonicalize_version_text(plan.pre_upgrade_snapshot)
- verified_display = _canonicalize_version_text(verified)
- console.print(
- f"Upgraded specify-cli: {pre_upgrade_display} β†’ {verified_display}",
- soft_wrap=True,
- )
+self_app, self_check, self_upgrade = _command_exports()
+del _command_exports
diff --git a/src/specify_cli/selfs/__init__.py b/src/specify_cli/selfs/__init__.py
new file mode 100644
index 000000000..a35402a9d
--- /dev/null
+++ b/src/specify_cli/selfs/__init__.py
@@ -0,0 +1,28 @@
+"""Nested command group for ``specify self``.
+
+The plural Python package name follows the repository's command-hierarchy
+convention even though the user-facing CLI namespace is singular.
+"""
+
+import typer
+
+self_app = typer.Typer(
+ name="self",
+ help=(
+ "Manage the specify CLI itself: check for newer releases, "
+ "preview upgrades with --dry-run, and upgrade in place."
+ ),
+ add_completion=False,
+)
+
+
+def _register_commands():
+ """Register command adapters and return compatibility exports."""
+ from .command_check import self_check
+ from .command_upgrade import self_upgrade
+
+ return self_check, self_upgrade
+
+
+self_check, self_upgrade = _register_commands()
+del _register_commands
diff --git a/src/specify_cli/selfs/command_check.py b/src/specify_cli/selfs/command_check.py
new file mode 100644
index 000000000..cd6b25121
--- /dev/null
+++ b/src/specify_cli/selfs/command_check.py
@@ -0,0 +1,79 @@
+"""CLI adapter for ``specify self check``."""
+
+from __future__ import annotations
+
+from . import self_app
+
+
+@self_app.command("check")
+def self_check() -> None:
+ """Check whether a newer specify-cli release is available. Read-only.
+
+ This command only checks for updates; it does not modify your installation.
+ Use `specify self upgrade` to actually perform the upgrade once you've seen
+ the result here, or `specify self upgrade --dry-run` to preview the
+ installer command without running it.
+ """
+ from .._version import (
+ _MANUAL_TAG_PLACEHOLDER,
+ _fetch_latest_release_tag,
+ _get_installed_version,
+ _is_newer,
+ _manual_source_spec,
+ _manual_tag_or_placeholder,
+ _normalize_tag,
+ console,
+ )
+
+ installed = _get_installed_version()
+ tag, failure_reason = _fetch_latest_release_tag()
+
+ if tag is None:
+ assert failure_reason is not None
+ console.print(f"Installed: {installed}")
+ console.print(f"[yellow]Could not check latest release:[/yellow] {failure_reason}")
+ return
+
+ manual_tag = _manual_tag_or_placeholder(tag)
+ latest_display = manual_tag or _MANUAL_TAG_PLACEHOLDER
+
+ if manual_tag is None:
+ if installed == "unknown":
+ console.print("Current version could not be determined.")
+ console.print(f"Latest release: {latest_display}")
+ else:
+ console.print(f"Installed: {installed}")
+ console.print(f"Latest release: {latest_display}")
+ console.print("[yellow]Could not validate latest release tag from GitHub.[/yellow]")
+ console.print("\nManual fallback:")
+ console.print(
+ f" uv tool install specify-cli --force --from {_manual_source_spec(manual_tag)}"
+ )
+ console.print(f" pipx install --force {_manual_source_spec(manual_tag)}")
+ return
+
+ if installed == "unknown":
+ console.print("Current version could not be determined.")
+ console.print(f"Latest release: {latest_display}")
+ console.print("\nManual fallback:")
+ console.print(
+ f" uv tool install specify-cli --force --from {_manual_source_spec(manual_tag)}"
+ )
+ console.print(f" pipx install --force {_manual_source_spec(manual_tag)}")
+ console.print("\nIf this install can still be detected:")
+ console.print(" specify self upgrade")
+ return
+
+ latest_normalized = _normalize_tag(manual_tag)
+ if _is_newer(latest_normalized, installed):
+ console.print(f"[green]Update available:[/green] {installed} β†’ {latest_display}")
+ console.print("\nTo upgrade:")
+ console.print(" specify self upgrade")
+ console.print("\nManual fallback:")
+ console.print(
+ f" uv tool install specify-cli --force --from {_manual_source_spec(manual_tag)}"
+ )
+ console.print(f" pipx install --force {_manual_source_spec(manual_tag)}")
+ return
+
+ console.print(f"[green]Up to date:[/green] {installed}")
diff --git a/src/specify_cli/selfs/command_upgrade.py b/src/specify_cli/selfs/command_upgrade.py
new file mode 100644
index 000000000..1f645c0e4
--- /dev/null
+++ b/src/specify_cli/selfs/command_upgrade.py
@@ -0,0 +1,215 @@
+"""CLI adapter for ``specify self upgrade``."""
+
+from __future__ import annotations
+
+import typer
+from rich.markup import escape as _escape_markup
+
+from . import self_app
+
+
+@self_app.command("upgrade")
+def self_upgrade(
+ dry_run: bool = typer.Option(
+ False,
+ "--dry-run",
+ help="Print the preview (method, current, target, installer argv) and "
+ "exit 0 without launching the installer subprocess.",
+ ),
+ tag: str | None = typer.Option(
+ None,
+ "--tag",
+ help="Pin the target version (vX.Y.Z\\[suffix]). Without --tag, the "
+ "latest stable release is resolved via GitHub Releases.",
+ ),
+) -> None:
+ """Upgrade specify-cli to the latest release (or a pinned --tag).
+
+ Bare invocation executes immediately with no confirmation prompt, matching
+ pip install -U / uv tool upgrade / npm update conventions. Use --dry-run
+ to preview without mutating anything. See `specify self check` for the
+ non-destructive read-only counterpart.
+
+ Detection classifies the runtime into uv-tool / pipx / uvx (ephemeral) /
+ source-checkout / unsupported. Only uv-tool and pipx are upgraded
+ automatically; the other three paths print path-specific guidance and
+ exit 0.
+
+ Exit codes:
+ 0 success or no-op-success (already on latest, --dry-run, or
+ non-upgradable path with guidance shown)
+ 1 target-tag resolution failure or --tag regex validation failure
+ 2 verification mismatch when the installer exited 0 but
+ `specify --version` does not resolve to the target tag; if the
+ installer itself exits 2, that installer failure code is
+ propagated verbatim
+ 3 installer binary not found on PATH, or resolved installer path is
+ missing / non-executable
+ 124 internal installer timeout when SPECIFY_UPGRADE_TIMEOUT_SECS is set,
+ or a real installer exit code 124 propagated verbatim; scripts
+ should treat 124 as ambiguous and inspect the failure message
+ other installer exit code propagated verbatim
+
+ Environment variables:
+ SPECIFY_UPGRADE_TIMEOUT_SECS Optional integer/float seconds. Caps how
+ long the installer subprocess may run. Unset (default) means no
+ timeout β€” interrupt with Ctrl+C if the installer hangs.
+ """
+ from .._version import (
+ _FAILURE_INSTALLER_FAILED,
+ _FAILURE_INSTALLER_INVALID,
+ _FAILURE_INSTALLER_MISSING,
+ _FAILURE_INSTALLER_TIMEOUT,
+ _FAILURE_TARGET_TAG_UNPARSEABLE,
+ _FAILURE_VERIFICATION_MISMATCH,
+ _InstallMethod,
+ _InstallerResultKind,
+ _build_upgrade_plan,
+ _canonicalize_version_text,
+ _emit_failure,
+ _emit_guidance,
+ _installer_binary_name,
+ _method_label,
+ _parse_version_text,
+ _render_argv,
+ _run_installer,
+ _validate_tag,
+ _verify_upgrade,
+ console,
+ )
+
+ if tag is not None:
+ try:
+ tag = _validate_tag(tag)
+ except typer.BadParameter as exc:
+ console.print(_escape_markup(str(exc)), soft_wrap=True)
+ raise typer.Exit(1) from exc
+
+ plan, failure_reason = _build_upgrade_plan(target_tag_override=tag)
+
+ if plan is None:
+ if failure_reason is None:
+ raise RuntimeError(
+ "internal contract violation: _build_upgrade_plan returned (None, None)"
+ )
+ _emit_failure(failure_reason)
+ raise typer.Exit(1)
+
+ if failure_reason is not None:
+ _emit_failure(failure_reason, plan=plan)
+ raise typer.Exit(1)
+
+ if dry_run:
+ if plan.method in (
+ _InstallMethod.UVX_EPHEMERAL,
+ _InstallMethod.SOURCE_CHECKOUT,
+ _InstallMethod.UNSUPPORTED,
+ ):
+ _emit_guidance(plan.method, plan.target_tag)
+ raise typer.Exit(0)
+ console.print("Dry run β€” no changes will be made.")
+ for line in plan.preview_summary.splitlines():
+ console.print(line)
+ raise typer.Exit(0)
+
+ if plan.method in (
+ _InstallMethod.UVX_EPHEMERAL,
+ _InstallMethod.SOURCE_CHECKOUT,
+ _InstallMethod.UNSUPPORTED,
+ ):
+ _emit_guidance(plan.method, plan.target_tag)
+ raise typer.Exit(0)
+
+ if plan.installer_argv is None:
+ _emit_failure(
+ _FAILURE_INSTALLER_MISSING,
+ plan=plan,
+ installer_name=_installer_binary_name(plan.method),
+ )
+ raise typer.Exit(3)
+
+ if plan.target_tag is None:
+ raise RuntimeError("Upgrade target tag is required for upgradable install methods")
+ target_tag = plan.target_tag
+ target_version = _parse_version_text(target_tag)
+ if target_version is None:
+ _emit_failure(_FAILURE_TARGET_TAG_UNPARSEABLE, plan=plan)
+ raise typer.Exit(1)
+ if plan.current_version != "unknown":
+ current_version = _parse_version_text(plan.current_version)
+ if tag is None and current_version is not None and not (
+ target_version > current_version
+ ):
+ if target_version == current_version:
+ console.print(f"Already on latest release: {target_tag}")
+ else:
+ console.print(f"Already on latest release or newer: {plan.current_version}")
+ raise typer.Exit(0)
+ if (
+ tag is not None
+ and current_version is not None
+ and target_version == current_version
+ ):
+ console.print(f"Already on requested release: {target_tag}")
+ raise typer.Exit(0)
+
+ installed_version = _parse_version_text(plan.current_version)
+ verb = (
+ "Downgrading"
+ if tag is not None
+ and installed_version is not None
+ and target_version < installed_version
+ else "Upgrading"
+ )
+ argv_str = _render_argv(plan.installer_argv) if plan.installer_argv else ""
+ console.print(
+ f"{verb} specify-cli {plan.current_version} β†’ {plan.target_tag} "
+ f"via {_method_label(plan.method)}: {argv_str}",
+ soft_wrap=True,
+ )
+
+ installer_result = _run_installer(plan)
+ installer_name = plan.installer_argv[0] if plan.installer_argv else None
+
+ if installer_result.kind == _InstallerResultKind.MISSING:
+ _emit_failure(_FAILURE_INSTALLER_MISSING, plan=plan, installer_name=installer_name)
+ raise typer.Exit(3)
+
+ if installer_result.kind == _InstallerResultKind.INVALID:
+ _emit_failure(_FAILURE_INSTALLER_INVALID, plan=plan, installer_name=installer_name)
+ raise typer.Exit(3)
+
+ if installer_result.kind == _InstallerResultKind.TIMEOUT:
+ _emit_failure(_FAILURE_INSTALLER_TIMEOUT, plan=plan)
+ raise typer.Exit(124)
+
+ if (
+ installer_result.kind != _InstallerResultKind.EXITED
+ or installer_result.returncode is None
+ ):
+ raise RuntimeError(f"Unknown installer result: {installer_result!r}")
+
+ if installer_result.returncode != 0:
+ _emit_failure(
+ _FAILURE_INSTALLER_FAILED,
+ plan=plan,
+ installer_exit=installer_result.returncode,
+ )
+ raise typer.Exit(installer_result.returncode)
+
+ verified = _verify_upgrade(plan)
+ verified_version = _parse_version_text(verified) if verified is not None else None
+ if verified_version is None or verified_version != target_version:
+ _emit_failure(
+ _FAILURE_VERIFICATION_MISMATCH,
+ plan=plan,
+ verified_version=verified,
+ )
+ raise typer.Exit(2)
+
+ pre_upgrade_display = _canonicalize_version_text(plan.pre_upgrade_snapshot)
+ verified_display = _canonicalize_version_text(verified)
+ console.print(
+ f"Upgraded specify-cli: {pre_upgrade_display} β†’ {verified_display}",
+ soft_wrap=True,
+ )
diff --git a/tests/self_upgrade_helpers.py b/tests/specify_cli/self_upgrade_helpers.py
similarity index 100%
rename from tests/self_upgrade_helpers.py
rename to tests/specify_cli/self_upgrade_helpers.py
diff --git a/tests/specify_cli/selfs/__init__.py b/tests/specify_cli/selfs/__init__.py
new file mode 100644
index 000000000..df35e6484
--- /dev/null
+++ b/tests/specify_cli/selfs/__init__.py
@@ -0,0 +1 @@
+"""Command tests for the ``specify self`` hierarchy."""
diff --git a/tests/specify_cli/selfs/test_command_check.py b/tests/specify_cli/selfs/test_command_check.py
new file mode 100644
index 000000000..3bae9d97b
--- /dev/null
+++ b/tests/specify_cli/selfs/test_command_check.py
@@ -0,0 +1,187 @@
+"""Command tests for ``specify self check``."""
+
+import urllib.error
+from unittest.mock import patch
+
+import pytest
+from typer.testing import CliRunner
+
+from specify_cli import app
+from tests.conftest import strip_ansi
+from tests.http_helpers import (
+ mock_urlopen_response,
+ route_opener_open_through_urlopen, # noqa: F401 (autouse fixture)
+)
+
+runner = CliRunner()
+
+SENTINEL_GH_TOKEN = "SENTINEL-GH-TOKEN-VALUE"
+SENTINEL_GITHUB_TOKEN = "SENTINEL-GITHUB-TOKEN-VALUE"
+_RATE_LIMITED_REASON = (
+ "rate limited (configure ~/.specify/auth.json with a GitHub token)"
+)
+
+
+def _http_error(code: int, message: str = "error") -> urllib.error.HTTPError:
+ return urllib.error.HTTPError(
+ url="https://api.github.com/repos/github/spec-kit/releases/latest",
+ code=code,
+ msg=message,
+ hdrs={}, # type: ignore[arg-type]
+ fp=None,
+ )
+
+
+_FAILURE_CASES = [
+ ("offline or timeout", urllib.error.URLError("down")),
+ (_RATE_LIMITED_REASON, _http_error(403)),
+ ("HTTP 500", _http_error(500)),
+]
+
+
+class TestUserStory1:
+ def test_newer_available_prints_update_and_install_command(self):
+ with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
+ "specify_cli.authentication.http.urllib.request.urlopen",
+ return_value=mock_urlopen_response({"tag_name": "v0.9.0"}),
+ ):
+ result = runner.invoke(app, ["self", "check"])
+ output = strip_ansi(result.output)
+ assert result.exit_code == 0
+ assert "Update available" in output
+ assert "0.7.4" in output
+ assert "0.9.0" in output
+ assert "git+https://github.com/github/[email protected]" in output
+
+ def test_up_to_date_prints_current_only(self):
+ with patch("specify_cli._version._get_installed_version", return_value="0.9.0"), patch(
+ "specify_cli.authentication.http.urllib.request.urlopen",
+ return_value=mock_urlopen_response({"tag_name": "v0.9.0"}),
+ ):
+ result = runner.invoke(app, ["self", "check"])
+ output = strip_ansi(result.output)
+ assert result.exit_code == 0
+ assert "Up to date: 0.9.0" in output
+ assert "Update available" not in output
+ assert "git+https://" not in output
+
+ def test_dev_build_ahead_of_release_is_up_to_date(self):
+ with patch("specify_cli._version._get_installed_version", return_value="0.7.5.dev0"), patch(
+ "specify_cli.authentication.http.urllib.request.urlopen",
+ return_value=mock_urlopen_response({"tag_name": "v0.7.4"}),
+ ):
+ result = runner.invoke(app, ["self", "check"])
+ output = strip_ansi(result.output)
+ assert result.exit_code == 0
+ assert "Update available" not in output
+ assert "Up to date" in output
+
+ def test_unknown_installed_still_prints_latest_and_reinstall(self):
+ with patch("specify_cli._version._get_installed_version", return_value="unknown"), patch(
+ "specify_cli.authentication.http.urllib.request.urlopen",
+ return_value=mock_urlopen_response({"tag_name": "v0.7.4"}),
+ ):
+ result = runner.invoke(app, ["self", "check"])
+ output = strip_ansi(result.output)
+ assert result.exit_code == 0
+ assert "Current version could not be determined" in output
+ assert "Latest release: v0.7.4" in output
+ assert "0.7.4" in output
+ assert "git+https://github.com/github/[email protected]" in output
+ assert "specify self upgrade" in output
+ assert "pipx install --force git+https://github.com/github/[email protected]" in output
+
+ def test_unknown_installed_uses_placeholder_when_latest_tag_is_invalid(self):
+ with patch("specify_cli._version._get_installed_version", return_value="unknown"), patch(
+ "specify_cli.authentication.http.urllib.request.urlopen",
+ return_value=mock_urlopen_response({"tag_name": "v0.9.0;echo unsafe"}),
+ ):
+ result = runner.invoke(app, ["self", "check"])
+ output = strip_ansi(result.output)
+ assert result.exit_code == 0
+ assert "Latest release: vX.Y.Z" in output
+ assert "Could not validate latest release tag from GitHub." in output
+ assert "git+https://github.com/github/[email protected]" in output
+ assert "v0.9.0;echo unsafe" not in output
+
+ def test_unparseable_tag_reports_validation_failure_without_raw_tag(self):
+ with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
+ "specify_cli.authentication.http.urllib.request.urlopen",
+ return_value=mock_urlopen_response({"tag_name": "not-a-version"}),
+ ):
+ result = runner.invoke(app, ["self", "check"])
+ output = strip_ansi(result.output)
+ assert result.exit_code == 0
+ assert "Update available" not in output
+ assert "Up to date" not in output
+ assert "Could not validate latest release tag from GitHub." in output
+ assert "Latest release: vX.Y.Z" in output
+ assert "0.7.4" in output
+ assert "not-a-version" not in output
+ assert "git+https://github.com/github/[email protected]" in output
+
+
+class TestUserStory2:
+ @pytest.mark.parametrize("expected_reason, side_effect", _FAILURE_CASES)
+ def test_failure_prints_installed_plus_one_line_reason(
+ self, expected_reason, side_effect
+ ):
+ with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
+ "specify_cli.authentication.http.urllib.request.urlopen", side_effect=side_effect
+ ):
+ result = runner.invoke(app, ["self", "check"])
+ output = strip_ansi(result.output)
+ assert "Installed: 0.7.4" in output
+ if expected_reason == _RATE_LIMITED_REASON:
+ assert "Could not check latest release: rate limited" in output
+ assert "~/.specify/auth.json" in output
+ else:
+ assert f"Could not check latest release: {expected_reason}" in output
+
+ @pytest.mark.parametrize("_expected_reason, side_effect", _FAILURE_CASES)
+ def test_failure_exits_zero(self, _expected_reason, side_effect):
+ with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
+ "specify_cli.authentication.http.urllib.request.urlopen", side_effect=side_effect
+ ):
+ result = runner.invoke(app, ["self", "check"])
+ assert result.exit_code == 0
+
+ @pytest.mark.parametrize("_expected_reason, side_effect", _FAILURE_CASES)
+ def test_failure_output_contains_no_traceback_no_url(
+ self, _expected_reason, side_effect
+ ):
+ with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
+ "specify_cli.authentication.http.urllib.request.urlopen", side_effect=side_effect
+ ):
+ result = runner.invoke(app, ["self", "check"])
+ combined = strip_ansi((result.output or "") + (result.stderr or ""))
+ assert "Traceback" not in combined
+ assert "https://api.github.com" not in combined
+
+
+class TestUserStory3:
+ @pytest.mark.parametrize("_reason, side_effect", _FAILURE_CASES)
+ def test_gh_token_never_appears_in_failure_output(
+ self, _reason, side_effect, monkeypatch
+ ):
+ monkeypatch.setenv("GH_TOKEN", SENTINEL_GH_TOKEN)
+ monkeypatch.delenv("GITHUB_TOKEN", raising=False)
+ with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
+ "specify_cli.authentication.http.urllib.request.urlopen", side_effect=side_effect
+ ):
+ result = runner.invoke(app, ["self", "check"])
+ combined = strip_ansi((result.output or "") + (result.stderr or ""))
+ assert SENTINEL_GH_TOKEN not in combined
+
+ @pytest.mark.parametrize("_reason, side_effect", _FAILURE_CASES)
+ def test_github_token_never_appears_in_failure_output(
+ self, _reason, side_effect, monkeypatch
+ ):
+ monkeypatch.delenv("GH_TOKEN", raising=False)
+ monkeypatch.setenv("GITHUB_TOKEN", SENTINEL_GITHUB_TOKEN)
+ with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
+ "specify_cli.authentication.http.urllib.request.urlopen", side_effect=side_effect
+ ):
+ result = runner.invoke(app, ["self", "check"])
+ combined = strip_ansi((result.output or "") + (result.stderr or ""))
+ assert SENTINEL_GITHUB_TOKEN not in combined
diff --git a/tests/specify_cli/selfs/test_command_upgrade.py b/tests/specify_cli/selfs/test_command_upgrade.py
new file mode 100644
index 000000000..5a39a9ddb
--- /dev/null
+++ b/tests/specify_cli/selfs/test_command_upgrade.py
@@ -0,0 +1,128 @@
+"""Command tests for ``specify self upgrade``."""
+
+from unittest.mock import patch
+
+import pytest
+
+from specify_cli import app
+from tests.specify_cli.self_upgrade_helpers import runner, strip_ansi
+
+
+class TestTagValidation:
+ """--tag option parsing and command help."""
+
+ def test_valid_stable_tag(self, uv_tool_argv0, clean_environ):
+ with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ result = runner.invoke(
+ app,
+ ["self", "upgrade", "--dry-run", "--tag", "v0.7.6"],
+ )
+ assert result.exit_code == 0
+
+ def test_valid_dev_suffix_tag(self, uv_tool_argv0, clean_environ):
+ with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ result = runner.invoke(
+ app,
+ ["self", "upgrade", "--dry-run", "--tag", "v0.8.0.dev0"],
+ )
+ assert result.exit_code == 0
+ assert "Target version: v0.8.0.dev0" in strip_ansi(result.output)
+
+ def test_valid_rc_tag(self, uv_tool_argv0, clean_environ):
+ with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ result = runner.invoke(
+ app,
+ ["self", "upgrade", "--dry-run", "--tag", "v1.0.0-rc1"],
+ )
+ assert result.exit_code == 0
+
+ def test_valid_beta_dot_tag_uses_pep440_equivalent_for_noop(
+ self, uv_tool_argv0, clean_environ
+ ):
+ with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+ "specify_cli._version._get_installed_version", return_value="1.0.0b1"
+ ):
+ result = runner.invoke(
+ app,
+ ["self", "upgrade", "--tag", "v1.0.0-beta.1"],
+ )
+ assert result.exit_code == 0
+ assert "Already on requested release: v1.0.0-beta.1" in strip_ansi(
+ result.output
+ )
+
+ def test_valid_build_metadata_tag(self, uv_tool_argv0, clean_environ):
+ with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ result = runner.invoke(
+ app,
+ ["self", "upgrade", "--dry-run", "--tag", "v0.8.0+build.42"],
+ )
+ assert result.exit_code == 0
+ assert "Target version: v0.8.0+build.42" in strip_ansi(result.output)
+
+ def test_uppercase_v_prefix_is_folded_to_lowercase(
+ self, uv_tool_argv0, clean_environ
+ ):
+ with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ result = runner.invoke(
+ app,
+ ["self", "upgrade", "--dry-run", "--tag", "V0.7.6"],
+ )
+ assert result.exit_code == 0
+ assert "Target version: v0.7.6" in strip_ansi(result.output)
+
+ def test_valid_prerelease_with_build_metadata_tag(
+ self, uv_tool_argv0, clean_environ
+ ):
+ with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ result = runner.invoke(
+ app,
+ ["self", "upgrade", "--dry-run", "--tag", "v1.0.0-rc1+build.42"],
+ )
+ assert result.exit_code == 0
+ assert "Target version: v1.0.0-rc1+build.42" in strip_ansi(result.output)
+
+ @pytest.mark.parametrize(
+ "bad_tag",
+ [
+ "latest",
+ "0.7.5",
+ "main",
+ "v7",
+ "",
+ "v1.2.3abc",
+ "v1.2.3...",
+ "v1.2.3++",
+ "v\uff11.2.3",
+ "v1.\u0662.3",
+ ],
+ )
+ def test_invalid_tags_rejected(self, bad_tag, uv_tool_argv0, clean_environ):
+ result = runner.invoke(app, ["self", "upgrade", "--tag", bad_tag])
+ assert result.exit_code == 1
+ output = strip_ansi(result.output)
+ assert "Invalid --tag" in output or "expected vMAJOR.MINOR.PATCH" in output
+
+ def test_rejection_message_keeps_the_suffix_token(
+ self, uv_tool_argv0, clean_environ
+ ):
+ result = runner.invoke(app, ["self", "upgrade", "--tag", "latest"])
+ assert result.exit_code == 1
+ assert "expected vMAJOR.MINOR.PATCH[suffix]" in strip_ansi(result.output)
+
+ def test_tag_option_help_keeps_the_suffix_token(self):
+ result = runner.invoke(app, ["self", "upgrade", "--help"])
+ assert result.exit_code == 0
+ assert "[suffix]" in strip_ansi(result.output)
diff --git a/tests/test_self_upgrade_detection.py b/tests/specify_cli/test_version_detection.py
similarity index 99%
rename from tests/test_self_upgrade_detection.py
rename to tests/specify_cli/test_version_detection.py
index 73b55ebb7..c76966592 100644
--- a/tests/test_self_upgrade_detection.py
+++ b/tests/specify_cli/test_version_detection.py
@@ -12,7 +12,7 @@ import pytest
import specify_cli
from specify_cli import app
-from tests.self_upgrade_helpers import (
+from tests.specify_cli.self_upgrade_helpers import (
route_opener_open_through_urlopen, # noqa: F401 (autouse fixture)
_InstallMethod,
_assemble_installer_argv,
diff --git a/tests/test_self_upgrade_execution.py b/tests/specify_cli/test_version_execution.py
similarity index 99%
rename from tests/test_self_upgrade_execution.py
rename to tests/specify_cli/test_version_execution.py
index 5c761014b..9e3f2514f 100644
--- a/tests/test_self_upgrade_execution.py
+++ b/tests/specify_cli/test_version_execution.py
@@ -6,7 +6,7 @@ from unittest.mock import patch
from specify_cli import app
-from tests.self_upgrade_helpers import (
+from tests.specify_cli.self_upgrade_helpers import (
route_opener_open_through_urlopen, # noqa: F401 (autouse fixture)
_completed_process,
mock_urlopen_response,
diff --git a/tests/test_self_upgrade_guidance.py b/tests/specify_cli/test_version_guidance.py
similarity index 99%
rename from tests/test_self_upgrade_guidance.py
rename to tests/specify_cli/test_version_guidance.py
index 5fcb6a527..c1d57f9ad 100644
--- a/tests/test_self_upgrade_guidance.py
+++ b/tests/specify_cli/test_version_guidance.py
@@ -4,7 +4,7 @@ from unittest.mock import patch
from specify_cli import app
-from tests.self_upgrade_helpers import (
+from tests.specify_cli.self_upgrade_helpers import (
mock_urlopen_response,
route_opener_open_through_urlopen, # noqa: F401 (autouse fixture)
runner,
diff --git a/tests/test_version_imports.py b/tests/specify_cli/test_version_imports.py
similarity index 100%
rename from tests/test_version_imports.py
rename to tests/specify_cli/test_version_imports.py
diff --git a/tests/test_upgrade.py b/tests/specify_cli/test_version_release.py
similarity index 56%
rename from tests/test_upgrade.py
rename to tests/specify_cli/test_version_release.py
index 513cd2343..d70991421 100644
--- a/tests/test_upgrade.py
+++ b/tests/specify_cli/test_version_release.py
@@ -1,13 +1,10 @@
-"""Tests for the `specify self` sub-app (`self check` and `self upgrade`).
+"""Tests for release lookup and version comparison behavior.
Network isolation contract (SC-004 / FR-014): every test that exercises
-`specify self check` or `_fetch_latest_release_tag()` MUST mock the outbound
-urllib path so no real call reaches api.github.com. Production always uses an
-isolated `build_opener`; this module's autouse fixture routes its `open()` back
-through the locally mocked `urlopen`. Tests for non-network `self upgrade`
-behavior should keep that contract explicit with local mocks. Run this module
-under `pytest-socket` (if installed) with `--disable-socket` as an extra safety
-net.
+`_fetch_latest_release_tag()` MUST mock the outbound urllib path so no real call
+reaches api.github.com. Production always uses an isolated `build_opener`; this
+module's autouse fixture routes its `open()` back through the locally mocked
+`urlopen`.
"""
import urllib.error
@@ -15,9 +12,6 @@ import importlib.metadata
from unittest.mock import MagicMock, patch
import pytest
-from typer.testing import CliRunner
-
-from specify_cli import app
from specify_cli._download_security import read_response_limited as _real_read_response_limited
from specify_cli._version import (
_fetch_latest_release_tag,
@@ -25,14 +19,11 @@ from specify_cli._version import (
_is_newer,
_normalize_tag,
)
-from tests.conftest import strip_ansi
from tests.http_helpers import (
mock_urlopen_response,
route_opener_open_through_urlopen, # noqa: F401 (autouse fixture)
)
-runner = CliRunner()
-
SENTINEL_GH_TOKEN = "SENTINEL-GH-TOKEN-VALUE"
SENTINEL_GITHUB_TOKEN = "SENTINEL-GITHUB-TOKEN-VALUE"
@@ -110,88 +101,6 @@ class TestNormalizeTag:
assert _normalize_tag("") == ""
-class TestUserStory1:
- def test_newer_available_prints_update_and_install_command(self):
- with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
- "specify_cli.authentication.http.urllib.request.urlopen",
- return_value=mock_urlopen_response({"tag_name": "v0.9.0"}),
- ):
- result = runner.invoke(app, ["self", "check"])
- output = strip_ansi(result.output)
- assert result.exit_code == 0
- assert "Update available" in output
- assert "0.7.4" in output
- assert "0.9.0" in output
- assert "git+https://github.com/github/[email protected]" in output
-
- def test_up_to_date_prints_current_only(self):
- with patch("specify_cli._version._get_installed_version", return_value="0.9.0"), patch(
- "specify_cli.authentication.http.urllib.request.urlopen",
- return_value=mock_urlopen_response({"tag_name": "v0.9.0"}),
- ):
- result = runner.invoke(app, ["self", "check"])
- output = strip_ansi(result.output)
- assert result.exit_code == 0
- assert "Up to date: 0.9.0" in output
- assert "Update available" not in output
- assert "git+https://" not in output
-
- def test_dev_build_ahead_of_release_is_up_to_date(self):
- with patch("specify_cli._version._get_installed_version", return_value="0.7.5.dev0"), patch(
- "specify_cli.authentication.http.urllib.request.urlopen",
- return_value=mock_urlopen_response({"tag_name": "v0.7.4"}),
- ):
- result = runner.invoke(app, ["self", "check"])
- output = strip_ansi(result.output)
- assert result.exit_code == 0
- assert "Update available" not in output
- assert "Up to date" in output
-
- def test_unknown_installed_still_prints_latest_and_reinstall(self):
- with patch("specify_cli._version._get_installed_version", return_value="unknown"), patch(
- "specify_cli.authentication.http.urllib.request.urlopen",
- return_value=mock_urlopen_response({"tag_name": "v0.7.4"}),
- ):
- result = runner.invoke(app, ["self", "check"])
- output = strip_ansi(result.output)
- assert result.exit_code == 0
- assert "Current version could not be determined" in output
- assert "Latest release: v0.7.4" in output
- assert "0.7.4" in output
- assert "git+https://github.com/github/[email protected]" in output
- assert "specify self upgrade" in output
- assert "pipx install --force git+https://github.com/github/[email protected]" in output
-
- def test_unknown_installed_uses_placeholder_when_latest_tag_is_invalid(self):
- with patch("specify_cli._version._get_installed_version", return_value="unknown"), patch(
- "specify_cli.authentication.http.urllib.request.urlopen",
- return_value=mock_urlopen_response({"tag_name": "v0.9.0;echo unsafe"}),
- ):
- result = runner.invoke(app, ["self", "check"])
- output = strip_ansi(result.output)
- assert result.exit_code == 0
- assert "Latest release: vX.Y.Z" in output
- assert "Could not validate latest release tag from GitHub." in output
- assert "git+https://github.com/github/[email protected]" in output
- assert "v0.9.0;echo unsafe" not in output
-
- def test_unparseable_tag_reports_validation_failure_without_raw_tag(self):
- with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
- "specify_cli.authentication.http.urllib.request.urlopen",
- return_value=mock_urlopen_response({"tag_name": "not-a-version"}),
- ):
- result = runner.invoke(app, ["self", "check"])
- output = strip_ansi(result.output)
- assert result.exit_code == 0
- assert "Update available" not in output
- assert "Up to date" not in output
- assert "Could not validate latest release tag from GitHub." in output
- assert "Latest release: vX.Y.Z" in output
- assert "0.7.4" in output
- assert "not-a-version" not in output
- assert "git+https://github.com/github/[email protected]" in output
-
-
class TestFailureCategorization:
def test_urlerror_maps_to_offline(self):
with patch(
@@ -280,52 +189,6 @@ class TestBoundedRead:
assert recorded["label"] == "GitHub latest release"
-_FAILURE_CASES = [
- ("offline or timeout", urllib.error.URLError("down")),
- (_RATE_LIMITED_REASON, _http_error(403)),
- ("HTTP 500", _http_error(500)),
-]
-
-
-class TestUserStory2:
- @pytest.mark.parametrize("expected_reason, side_effect", _FAILURE_CASES)
- def test_failure_prints_installed_plus_one_line_reason(
- self, expected_reason, side_effect
- ):
- with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
- "specify_cli.authentication.http.urllib.request.urlopen", side_effect=side_effect
- ):
- result = runner.invoke(app, ["self", "check"])
- output = strip_ansi(result.output)
- assert "Installed: 0.7.4" in output
- if expected_reason == _RATE_LIMITED_REASON:
- assert "Could not check latest release: rate limited" in output
- assert "~/.specify/auth.json" in output
- else:
- assert f"Could not check latest release: {expected_reason}" in output
-
- @pytest.mark.parametrize("_expected_reason, side_effect", _FAILURE_CASES)
- def test_failure_exits_zero(self, _expected_reason, side_effect):
- with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
- "specify_cli.authentication.http.urllib.request.urlopen", side_effect=side_effect
- ):
- result = runner.invoke(app, ["self", "check"])
- assert result.exit_code == 0
-
- @pytest.mark.parametrize("_expected_reason, side_effect", _FAILURE_CASES)
- def test_failure_output_contains_no_traceback_no_url(
- self, _expected_reason, side_effect
- ):
- with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
- "specify_cli.authentication.http.urllib.request.urlopen", side_effect=side_effect
- ):
- result = runner.invoke(app, ["self", "check"])
- combined = (result.output or "") + (result.stderr or "")
- combined = strip_ansi(combined)
- assert "Traceback" not in combined
- assert "https://api.github.com" not in combined
-
-
def _capture_request_via_urlopen():
captured = {}
@@ -421,29 +284,3 @@ class TestUserStory3:
_fetch_latest_release_tag()
req = captured["request"]
assert req.get_header("Authorization") == f"Bearer {SENTINEL_GITHUB_TOKEN}"
-
- @pytest.mark.parametrize("_reason, side_effect", _FAILURE_CASES)
- def test_gh_token_never_appears_in_failure_output(
- self, _reason, side_effect, monkeypatch
- ):
- monkeypatch.setenv("GH_TOKEN", SENTINEL_GH_TOKEN)
- monkeypatch.delenv("GITHUB_TOKEN", raising=False)
- with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
- "specify_cli.authentication.http.urllib.request.urlopen", side_effect=side_effect
- ):
- result = runner.invoke(app, ["self", "check"])
- combined = strip_ansi((result.output or "") + (result.stderr or ""))
- assert SENTINEL_GH_TOKEN not in combined
-
- @pytest.mark.parametrize("_reason, side_effect", _FAILURE_CASES)
- def test_github_token_never_appears_in_failure_output(
- self, _reason, side_effect, monkeypatch
- ):
- monkeypatch.delenv("GH_TOKEN", raising=False)
- monkeypatch.setenv("GITHUB_TOKEN", SENTINEL_GITHUB_TOKEN)
- with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
- "specify_cli.authentication.http.urllib.request.urlopen", side_effect=side_effect
- ):
- result = runner.invoke(app, ["self", "check"])
- combined = strip_ansi((result.output or "") + (result.stderr or ""))
- assert SENTINEL_GITHUB_TOKEN not in combined
diff --git a/tests/test_self_upgrade_verification.py b/tests/specify_cli/test_version_verification.py
similarity index 80%
rename from tests/test_self_upgrade_verification.py
rename to tests/specify_cli/test_version_verification.py
index f320cfe73..f3311bb23 100644
--- a/tests/test_self_upgrade_verification.py
+++ b/tests/specify_cli/test_version_verification.py
@@ -7,7 +7,7 @@ import pytest
import specify_cli
from specify_cli import app
-from tests.self_upgrade_helpers import (
+from tests.specify_cli.self_upgrade_helpers import (
route_opener_open_through_urlopen, # noqa: F401 (autouse fixture)
SENTINEL_GH_TOKEN,
SENTINEL_GITHUB_TOKEN,
@@ -362,137 +362,6 @@ class TestResolutionFailures:
assert mock_run.call_count == 0
-class TestTagValidation:
- """--tag regex enforcement."""
-
- def test_valid_stable_tag(self, uv_tool_argv0, clean_environ):
- with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
- "specify_cli._version._get_installed_version", return_value="0.7.5"
- ):
- result = runner.invoke(
- app,
- ["self", "upgrade", "--dry-run", "--tag", "v0.7.6"],
- )
- assert result.exit_code == 0
-
- def test_valid_dev_suffix_tag(self, uv_tool_argv0, clean_environ):
- with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
- "specify_cli._version._get_installed_version", return_value="0.7.5"
- ):
- result = runner.invoke(
- app,
- ["self", "upgrade", "--dry-run", "--tag", "v0.8.0.dev0"],
- )
- assert result.exit_code == 0
- assert "Target version: v0.8.0.dev0" in strip_ansi(result.output)
-
- def test_valid_rc_tag(self, uv_tool_argv0, clean_environ):
- with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
- "specify_cli._version._get_installed_version", return_value="0.7.5"
- ):
- result = runner.invoke(
- app,
- ["self", "upgrade", "--dry-run", "--tag", "v1.0.0-rc1"],
- )
- assert result.exit_code == 0
-
- def test_valid_beta_dot_tag_uses_pep440_equivalent_for_noop(
- self, uv_tool_argv0, clean_environ
- ):
- with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
- "specify_cli._version._get_installed_version", return_value="1.0.0b1"
- ):
- result = runner.invoke(
- app,
- ["self", "upgrade", "--tag", "v1.0.0-beta.1"],
- )
- assert result.exit_code == 0
- assert "Already on requested release: v1.0.0-beta.1" in strip_ansi(
- result.output
- )
-
- def test_valid_build_metadata_tag(self, uv_tool_argv0, clean_environ):
- with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
- "specify_cli._version._get_installed_version", return_value="0.7.5"
- ):
- result = runner.invoke(
- app,
- ["self", "upgrade", "--dry-run", "--tag", "v0.8.0+build.42"],
- )
- assert result.exit_code == 0
- assert "Target version: v0.8.0+build.42" in strip_ansi(result.output)
-
- def test_uppercase_v_prefix_is_folded_to_lowercase(
- self, uv_tool_argv0, clean_environ
- ):
- # A pasted uppercase `V` prefix is accepted and normalized to `v` so
- # the git ref matches the canonical lowercase release tag.
- with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
- "specify_cli._version._get_installed_version", return_value="0.7.5"
- ):
- result = runner.invoke(
- app,
- ["self", "upgrade", "--dry-run", "--tag", "V0.7.6"],
- )
- assert result.exit_code == 0
- assert "Target version: v0.7.6" in strip_ansi(result.output)
-
- def test_valid_prerelease_with_build_metadata_tag(
- self, uv_tool_argv0, clean_environ
- ):
- # Prerelease and build-metadata suffixes compose (PEP 440 / semver).
- with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
- "specify_cli._version._get_installed_version", return_value="0.7.5"
- ):
- result = runner.invoke(
- app,
- ["self", "upgrade", "--dry-run", "--tag", "v1.0.0-rc1+build.42"],
- )
- assert result.exit_code == 0
- assert "Target version: v1.0.0-rc1+build.42" in strip_ansi(result.output)
-
- @pytest.mark.parametrize(
- "bad_tag",
- [
- "latest",
- "0.7.5",
- "main",
- "v7",
- "",
- "v1.2.3abc",
- "v1.2.3...",
- "v1.2.3++",
- "v\uff11.2.3",
- "v1.\u0662.3",
- ],
- )
- def test_invalid_tags_rejected(self, bad_tag, uv_tool_argv0, clean_environ):
- result = runner.invoke(app, ["self", "upgrade", "--tag", bad_tag])
- assert result.exit_code == 1
- output = strip_ansi(result.output)
- assert "Invalid --tag" in output or "expected vMAJOR.MINOR.PATCH" in output
-
- def test_rejection_message_keeps_the_suffix_token(
- self, uv_tool_argv0, clean_environ
- ):
- """Rich must not swallow the literal `[suffix]`.
-
- Unescaped it is parsed as a style tag and dropped, so the user is told
- only "expected vMAJOR.MINOR.PATCH" -- implying a bare vX.Y.Z is the only
- accepted form, when -rc1 / .dev0 / +build.42 are all valid and are
- documented as such in docs/upgrade.md and README.md.
- """
- result = runner.invoke(app, ["self", "upgrade", "--tag", "latest"])
- assert result.exit_code == 1
- assert "expected vMAJOR.MINOR.PATCH[suffix]" in strip_ansi(result.output)
-
- def test_tag_option_help_keeps_the_suffix_token(self):
- """Typer renders option help through Rich, so `--help` dropped it too."""
- result = runner.invoke(app, ["self", "upgrade", "--help"])
- assert result.exit_code == 0
- assert "[suffix]" in strip_ansi(result.output)
-
-
class TestUnknownCurrent:
"""'unknown' current version renders literally in notice and success message."""