Skip to content

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

feat(cli): implement specify self upgrade (#2475)

κΉ€μ€€ν˜Έac2cb5daf524
diff --git a/README.md b/README.md
index 5b4a6c5d5..996a7f04d 100644
--- a/README.md
+++ b/README.md
@@ -59,6 +59,24 @@ specify init my-project --integration copilot
cd my-project
```
+To check for updates or upgrade the installed CLI, use the self-management commands. See the [Upgrade Guide](./docs/upgrade.md) for detailed scenarios and customization options.
+
+```bash
+# Check whether a newer release is available (read-only β€” does not modify anything)
+specify self check
+
+# Preview what would run, without actually upgrading
+specify self upgrade --dry-run
+
+# Upgrade in place to the latest stable release (auto-detects uv tool vs pipx install)
+specify self upgrade
+
+# Or pin a specific release tag (replace vX.Y.Z[suffix] with your desired release tag)
+specify self upgrade --tag vX.Y.Z[suffix]
+```
+
+Bare `specify self upgrade` executes immediately, matching the no-prompt behavior of commands like `pip install -U` and `npm update`. For `uv tool` installs, it runs `uv tool install specify-cli --force --from <git ref>` under the hood so pinned release tags work, including dev, alpha/beta/rc, or build metadata suffixes. `uvx` (ephemeral) runs and source checkouts are detected and produce path-specific guidance instead of running an installer. Set `SPECIFY_UPGRADE_TIMEOUT_SECS` to cap how long the installer subprocess may run (default: no timeout β€” interrupt with `Ctrl+C` if needed).
+
### 3. Establish project principles
Launch your coding agent in the project directory. Most agents expose spec-kit as `/speckit.*` slash commands; Codex CLI in skills mode uses `$speckit-*` instead.
@@ -133,7 +151,7 @@ Run `specify integration list` to see all available integrations in your install
After running `specify init`, your AI coding agent will have access to these slash commands for structured development. For integrations that support skills mode, passing `--integration <agent> --integration-options="--skills"` installs agent skills instead of slash-command prompt files.
-#### Core Commands
+### Core Commands
Essential commands for the Spec-Driven Development workflow:
@@ -146,7 +164,7 @@ Essential commands for the Spec-Driven Development workflow:
| `/speckit.taskstoissues` | `speckit-taskstoissues`| Convert generated task lists into GitHub issues for tracking and execution |
| `/speckit.implement` | `speckit-implement` | Execute all tasks to build the feature according to the plan |
-#### Optional Commands
+### Optional Commands
Additional commands for enhanced quality and validation:
diff --git a/docs/installation.md b/docs/installation.md
index 058303188..99b37f0d9 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -88,6 +88,8 @@ specify version
This helps verify you are running the official Spec Kit build from GitHub, not an unrelated package with the same name.
+**Stay current:** Run `specify self check` periodically to learn whether a newer release is available β€” it is read-only and never modifies your installation. When you are ready to upgrade, follow the [Upgrade Guide](./upgrade.md).
+
After initialization, you should see the following commands available in your coding agent:
- `/speckit.specify` - Create specifications
diff --git a/docs/upgrade.md b/docs/upgrade.md
index 5355a0b57..820cc9eab 100644
--- a/docs/upgrade.md
+++ b/docs/upgrade.md
@@ -8,8 +8,10 @@
| What to Upgrade | Command | When to Use |
|----------------|---------|-------------|
-| **CLI Tool Only** | `uv tool install specify-cli --force --from git+https://github.com/github/[email protected]` | Get latest CLI features without touching project files |
-| **CLI Tool Only (pipx)** | `pipx install --force git+https://github.com/github/[email protected]` | Reinstall/upgrade a pipx-installed CLI to a specific release |
+| **CLI Tool (recommended)** | `specify self upgrade` | Latest stable release, in place. Auto-detects whether you installed via `uv tool` or `pipx`. |
+| **CLI Tool β€” pin a version** | `specify self upgrade --tag vX.Y.Z[suffix]` | Upgrade to a specific release tag instead of the latest stable. Suffixes are limited to dev, alpha/beta/rc, and/or build metadata forms. |
+| **CLI Tool β€” manual fallback** | `uv tool install specify-cli --force --from git+https://github.com/github/[email protected]` | When `specify self upgrade` isn't available (older installs) or when you want explicit control. |
+| **CLI Tool β€” manual fallback (pipx)** | `pipx install --force git+https://github.com/github/[email protected]` | Same as above, for pipx installs. |
| **Project Files** | `specify init --here --force --integration <your-agent>` | Update slash commands, templates, and scripts in your project |
| **Both** | Run CLI upgrade, then project update | Recommended for major version updates |
@@ -19,12 +21,32 @@
The CLI tool (`specify`) is separate from your project files. Upgrade it to get the latest features and bug fixes.
-Before upgrading, you can check whether a newer released version is available:
+### Recommended: `specify self upgrade`
+
+The CLI ships with two self-management commands that handle the common case automatically:
```bash
+# Check whether a newer release is available (read-only β€” does not modify anything)
specify self check
+
+# Preview what would run, without actually upgrading
+specify self upgrade --dry-run
+
+# Upgrade in place to the latest stable release (auto-detects uv tool vs pipx install)
+specify self upgrade
+
+# Or pin a specific release tag (replace vX.Y.Z[suffix] with the tag you want)
+specify self upgrade --tag vX.Y.Z[suffix]
```
+Bare `specify self upgrade` executes immediately, matching the no-prompt behavior of commands like `pip install -U` and `npm update`. The CLI classifies your runtime into one of: `uv tool`, `pipx`, `uvx (ephemeral)`, source checkout, or unsupported. Only `uv tool` and `pipx` are upgraded automatically; for `uv tool` installs, it runs `uv tool install specify-cli --force --from <git ref>` under the hood so pinned release tags work. The other paths print path-specific guidance and exit 0 without touching anything.
+
+Pinned tags must start with `vMAJOR.MINOR.PATCH`. Optional suffixes are limited to dev, alpha/beta/rc, and/or build metadata forms such as `v1.0.0-rc1`, `v0.8.0.dev0`, `v0.8.0+build.42`, or the combination `v1.0.0-rc1+build.42`; branch names, hash refs, `latest`, and bare versions without `v` are rejected.
+
+Set `SPECIFY_UPGRADE_TIMEOUT_SECS` to cap how long the installer subprocess may run (default: no timeout β€” interrupt with `Ctrl+C` if needed). If that internal timeout fires, `specify self upgrade` exits 124 and reports that it timed out while waiting for the installer subprocess, including the configured timeout and manual retry command. A real installer exit code 124 is propagated with `Upgrade failed. Installer exit code: 124.`, so scripts should treat exit 124 as ambiguous and inspect the message when they need to distinguish the two cases.
+
+If your installed CLI is older than the release that introduced `specify self upgrade`, use the manual equivalents below. These commands are also useful when you want explicit control over the installer command.
+
### If you installed with `uv tool install`
Upgrade to a specific release (check [Releases](https://github.com/github/spec-kit/releases) for the latest tag):
@@ -54,10 +76,14 @@ pipx install --force git+https://github.com/github/[email protected]
### Verify the upgrade
```bash
+# Confirms the CLI is working and shows installed tools
specify check
+
+# Confirms the installed version against the latest GitHub release
+specify self check
```
-This shows installed tools and confirms the CLI is working. Use `specify version` to confirm which persistent CLI version is currently on your `PATH`.
+`specify check` shows the surrounding tool environment; `specify self check` is read-only and tells you whether you're now on the latest release (`Up to date: X.Y.Z`) or if a newer one became available between releases.
---
@@ -186,8 +212,8 @@ Restart your IDE to refresh the command list.
### Scenario 1: "I just want new slash commands"
```bash
-# Upgrade CLI (if using persistent install)
-uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git
+# Upgrade CLI (auto-detects uv tool vs pipx install)
+specify self upgrade
# Update project files to get new commands
specify init --here --force --integration copilot
@@ -204,7 +230,7 @@ cp .specify/memory/constitution.md /tmp/constitution-backup.md
cp -r .specify/templates /tmp/templates-backup
# 2. Upgrade CLI
-uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git
+specify self upgrade
# 3. Update project
specify init --here --force --integration copilot
@@ -388,15 +414,19 @@ Only Spec Kit infrastructure files:
### "CLI upgrade doesn't seem to work"
-If a command behaves like an older Spec Kit version, first check for local CLI drift:
+If a command behaves like an older Spec Kit version, first ask the CLI itself:
```bash
+# Read-only β€” prints "Up to date: X.Y.Z" or "Update available: X.Y.Z β†’ vY.Z.W"
specify self check
+
+# Preview the install method, current version, and target tag the upgrade would use
+specify self upgrade --dry-run
```
`specify check` is an offline environment scan; `specify self check` is the CLI version lookup.
-Verify the installation:
+If `self check` shows the wrong version, verify the installation:
```bash
# Check installed tools
diff --git a/src/specify_cli/_version.py b/src/specify_cli/_version.py
index 0a52ac7e8..e634a4f28 100644
--- a/src/specify_cli/_version.py
+++ b/src/specify_cli/_version.py
@@ -9,8 +9,21 @@ at module level, keeping this layer thin and circular-import-safe).
"""
from __future__ import annotations
+import errno
import json
+import math
+import os
+import re
+import shlex
+import shutil
+import subprocess
+import sys
import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
import typer
from packaging.version import InvalidVersion, Version
@@ -18,6 +31,23 @@ from packaging.version import InvalidVersion, Version
from ._console import console
GITHUB_API_LATEST = "https://api.github.com/repos/github/spec-kit/releases/latest"
+_RESOLUTION_FAILURE_OFFLINE = "offline or timeout"
+_RESOLUTION_FAILURE_RATE_LIMITED = (
+ "rate limited (configure ~/.specify/auth.json with a GitHub token)"
+)
+_RESOLUTION_FAILURE_HTTP_PREFIX = "HTTP "
+_FAILURE_INSTALLER_MISSING = "installer-missing"
+_FAILURE_INSTALLER_INVALID = "installer-invalid"
+_FAILURE_TARGET_TAG_UNPARSEABLE = "target-tag-unparseable"
+_FAILURE_INSTALLER_TIMEOUT = "installer-timeout"
+_FAILURE_INSTALLER_FAILED = "installer-failed"
+_FAILURE_VERIFICATION_MISMATCH = "verification-mismatch"
+_PRERELEASE_TAG_PATTERN = re.compile(
+ r"^([0-9]+\.[0-9]+\.[0-9]+)[-.]?(alpha|beta|a|b|rc)[-.]?([0-9]+)(.*)$",
+ flags=re.IGNORECASE,
+)
+_TIER3_REGISTRY_TIMEOUT_SECS = 5
+_VERIFY_TIMEOUT_SECS = 10
def _get_installed_version() -> str:
@@ -43,13 +73,19 @@ def _get_installed_version() -> str:
def _normalize_tag(tag: str) -> str:
- """Strip exactly one leading 'v' from a release tag.
+ """Normalize common git release-tag spellings into PEP 440 text.
- Returns the rest of the string unchanged. This handles the common
- 'vX.Y.Z' tag convention in this repo; it MUST NOT strip more
- aggressively (e.g., two leading 'v's keeps one).
+ Any trailing text after a recognized prerelease marker is preserved; callers
+ still validate the returned value with `packaging.version.Version`.
"""
- return tag[1:] if tag.startswith("v") else tag
+ normalized = tag[1:] if tag.startswith("v") else tag
+ prerelease_match = _PRERELEASE_TAG_PATTERN.match(normalized)
+ if prerelease_match is None:
+ return normalized
+
+ base, label, number, rest = prerelease_match.groups()
+ pep440_label = {"alpha": "a", "beta": "b"}.get(label.lower(), label.lower())
+ return f"{base}{pep440_label}{number}{rest}"
def _is_newer(latest: str, current: str) -> bool:
@@ -90,20 +126,1015 @@ def _fetch_latest_release_tag() -> tuple[str | None, str | None]:
return tag, None
except urllib.error.HTTPError as e:
# Order matters: HTTPError is a subclass of URLError.
- if e.code == 403:
- return None, (
- "rate limited (configure ~/.specify/auth.json with a GitHub token)"
- )
- return None, f"HTTP {e.code}"
+ # 403 (primary rate limit / abuse detection) and 429 (Too Many Requests /
+ # secondary rate limit) both get the actionable "configure a token" hint;
+ # every other status is surfaced verbatim as "HTTP {code}".
+ if e.code in (403, 429):
+ return None, _RESOLUTION_FAILURE_RATE_LIMITED
+ return None, f"{_RESOLUTION_FAILURE_HTTP_PREFIX}{e.code}"
except (urllib.error.URLError, OSError):
- return None, "offline or timeout"
+ return None, _RESOLUTION_FAILURE_OFFLINE
-# ===== Self Commands =====
+def _parse_version_text(value: str) -> Version | None:
+ """Parse version-like text after tag normalization, or return None."""
+ normalized = _normalize_tag(value)
+ try:
+ return Version(normalized)
+ except InvalidVersion:
+ return None
+
+
+def _canonicalize_version_text(value: str) -> str:
+ """Normalize version-like text for equality checks when parseable."""
+ parsed = _parse_version_text(value)
+ return str(parsed) if parsed is not None else _normalize_tag(value)
+
+
+def _stable_release_tag_for_version(version_text: str) -> str | None:
+ """Return `vX.Y.Z` only for exact stable release versions."""
+ parsed = _parse_version_text(version_text)
+ if parsed is None:
+ return None
+ if parsed.pre or parsed.post or parsed.dev or parsed.local:
+ return None
+ release = parsed.release
+ if len(release) != 3:
+ return None
+ return f"v{release[0]}.{release[1]}.{release[2]}"
+
+
+def _render_argv(argv: list[str]) -> str:
+ """Render argv as POSIX shell text, or cmd.exe-style text on Windows."""
+ return subprocess.list2cmdline(argv) if os.name == "nt" else shlex.join(argv)
+
+
+_INSTALLER_PATH_PREFIXES: dict[str, list[str]] = {
+ "uv-tool": [
+ "~/.local/share/uv/tools/specify-cli/",
+ "%LOCALAPPDATA%\\uv\\tools\\specify-cli\\",
+ ],
+ "pipx": [
+ "~/.local/pipx/venvs/specify-cli/",
+ "%LOCALAPPDATA%\\pipx\\venvs\\specify-cli\\",
+ ],
+ "uvx-ephemeral": [
+ "~/.cache/uv/archive-v0/",
+ "%LOCALAPPDATA%\\uv\\cache\\archive-v0\\",
+ ],
+}
+
+_RESOLUTION_FAILURE_CATEGORIES: frozenset[str] = frozenset(
+ {
+ _RESOLUTION_FAILURE_OFFLINE,
+ _RESOLUTION_FAILURE_RATE_LIMITED,
+ }
+)
+
+
+class _InstallMethod(str, Enum):
+ """Install-method classification for `specify self upgrade`."""
+
+ UV_TOOL = "uv-tool"
+ PIPX = "pipx"
+ UVX_EPHEMERAL = "uvx-ephemeral"
+ SOURCE_CHECKOUT = "source-checkout"
+ UNSUPPORTED = "unsupported"
+
+
+class _InstallerResultKind(str, Enum):
+ """Installer subprocess outcome, separated from real process exit codes."""
+
+ EXITED = "exited"
+ MISSING = "missing"
+ INVALID = "invalid"
+ TIMEOUT = "timeout"
+
+
+@dataclass(frozen=True)
+class _InstallerResult:
+ """Normalized installer result returned by _run_installer()."""
+
+ kind: _InstallerResultKind
+ returncode: int | None = None
+
+
+@dataclass(frozen=True)
+class _UpgradePlan:
+ """Resolved upgrade decision shared by preview and apply paths."""
+
+ method: _InstallMethod
+ current_version: str
+ target_tag: str | None
+ installer_argv: list[str] | None
+ preview_summary: str
+ pre_upgrade_snapshot: str
+
+
+@dataclass(frozen=True)
+class _DetectionSignals:
+ """Diagnostic record of which detection tier fired."""
+
+ sys_argv0: str
+ matched_tier: int | None
+ matched_prefix: str | None
+ editable_marker_seen: bool
+ installer_registries_consulted: tuple[str, ...]
+ resolved_method: _InstallMethod
+
+
+_GITHUB_CREDENTIAL_SUFFIXES = (
+ "_TOKEN",
+ "_SECRET",
+ "_KEY",
+ "_PAT",
+ "_PASSWORD",
+ "_CREDENTIALS",
+)
+_UNRESOLVED_ENV_VAR_RE = re.compile(r"\$\w+|\$\{\w+\}|%[^%]+%")
+
+
+def _is_github_credential_env_key(key: str) -> bool:
+ """Return whether an env key should be scrubbed as a GitHub credential.
+
+ Matching contract (case-insensitive):
+
+ - Any key with a ``GH_`` or ``GITHUB_`` prefix is scrubbed unconditionally.
+ This is deliberately broad: it catches credential-adjacent names that lack
+ a recognized suffix (e.g. ``GH_TOKEN_FILE``, ``GITHUB_TOKEN_PATH``) at the
+ cost of also dropping benign context vars (``GH_HOST``,
+ ``GITHUB_REPOSITORY``) the installer subprocess does not consume.
+ - Otherwise the key is scrubbed only when it contains an underscore-delimited
+ ``_GITHUB_`` segment *and* ends with a credential suffix
+ (``_TOKEN``/``_SECRET``/``_KEY``/``_PAT``/``_PASSWORD``/``_CREDENTIALS``) β€”
+ e.g. ``HOMEBREW_GITHUB_API_TOKEN``. Un-delimited variants such as a
+ hypothetical ``GITHUBTOKEN`` are not matched by this branch; no real tool
+ sets such a name. Only these recognized shapes are scrubbed β€” this is not
+ blanket coverage of every conceivable secret name.
+ """
+ upper = key.upper()
+ if upper.startswith(("GH_", "GITHUB_")):
+ return True
+ return "_GITHUB_" in upper and upper.endswith(_GITHUB_CREDENTIAL_SUFFIXES)
+
+
+def _scrubbed_env() -> dict[str, str]:
+ """Return a copy of `os.environ` without known GitHub credential keys."""
+
+ return {
+ k: v
+ for k, v in os.environ.items()
+ if not _is_github_credential_env_key(k)
+ }
+
+
+# vMAJOR.MINOR.PATCH, then an optional dev/prerelease segment, then an
+# optional build-metadata segment. The two trailing segments are independent
+# so they can compose (e.g. v1.0.0-rc1+build.42) β€” matching PEP 440 /semver,
+# which the Version() check below then enforces canonically.
+_TAG_REGEX = re.compile(
+ r"^v[0-9]+\.[0-9]+\.[0-9]+"
+ r"(?:(?:\.?dev[0-9]+)|(?:[-.]?(?:a|b|rc|alpha|beta)[-.]?[0-9]+))?"
+ r"(?:\+[A-Za-z0-9]+(?:\.[A-Za-z0-9]+)*)?$"
+)
+_INVALID_TAG_MESSAGE = "Invalid --tag: expected vMAJOR.MINOR.PATCH[suffix]"
+
+
+def _validate_tag(tag: str) -> str:
+ """Validate a user-supplied --tag value.
+
+ Accepts vX.Y.Z plus an optional dev or alpha/beta/rc suffix and/or an
+ optional build-metadata suffix, which may combine (for example:
+ v1.0.0-rc1, v0.8.0.dev0, v0.8.0+build.42, v1.0.0-rc1+build.42). An
+ uppercase ``V`` prefix is accepted and folded to the canonical lowercase
+ ``v``. Rejects everything else, including bare 'latest', hash refs, branch
+ names, and numeric versions without the 'v' prefix.
+ """
+ tag = tag.strip()
+ if not tag:
+ raise typer.BadParameter(_INVALID_TAG_MESSAGE)
+ # Fold a leading uppercase `V` (a common paste) to the canonical lowercase
+ # `v`. The remainder stays case-sensitive on purpose: the validated tag is
+ # used verbatim as a git ref, which is case-sensitive on GitHub, so we must
+ # not rewrite label/build-metadata casing into a ref that may not exist.
+ if tag[:1] == "V":
+ tag = "v" + tag[1:]
+ if not _TAG_REGEX.match(tag):
+ raise typer.BadParameter(_INVALID_TAG_MESSAGE)
+ try:
+ Version(_normalize_tag(tag))
+ except InvalidVersion as exc:
+ raise typer.BadParameter(_INVALID_TAG_MESSAGE) from exc
+
+ return tag
+
+
+def _expand_prefix(prefix: str) -> Path | None:
+ """Expand `~` or `%LOCALAPPDATA%`-style tokens in a path prefix."""
+
+ expanded = os.path.expanduser(prefix)
+ if "%LOCALAPPDATA%" in expanded:
+ local_app_data = os.environ.get("LOCALAPPDATA")
+ if not local_app_data:
+ return None
+ expanded = expanded.replace("%LOCALAPPDATA%", local_app_data)
+ expanded = os.path.expandvars(expanded)
+ if _UNRESOLVED_ENV_VAR_RE.search(expanded):
+ return None
+ try:
+ expanded_path = Path(expanded)
+ return expanded_path.resolve() if expanded_path.is_absolute() else expanded_path
+ except OSError:
+ return None
+
+
+def _path_is_within_prefix(path: Path, prefix: Path) -> bool:
+ """Return whether absolute `path` is under absolute `prefix`."""
+ if not path.is_absolute() or not prefix.is_absolute():
+ return False
+ try:
+ common = os.path.commonpath(
+ [os.path.normcase(str(path)), os.path.normcase(str(prefix))]
+ )
+ except ValueError:
+ return False
+ return common == os.path.normcase(str(prefix))
+
+
+def _resolve_path_or_original(path: Path) -> Path:
+ try:
+ return path.resolve()
+ except OSError:
+ return path
+
+
+def _resolved_argv0_path(argv0: str | None = None) -> Path:
+ """Resolve the running entrypoint path, consulting PATH for bare commands."""
+ raw = argv0 or sys.argv[0]
+ candidate = Path(raw)
+ if candidate.is_absolute():
+ return _resolve_path_or_original(candidate)
+ if candidate.exists():
+ return _resolve_path_or_original(candidate)
+
+ lookup_names = [raw]
+ if len(candidate.parts) > 1:
+ lookup_names.append(candidate.name)
+ if "specify" not in lookup_names:
+ lookup_names.append("specify")
+
+ for lookup_name in lookup_names:
+ resolved = shutil.which(lookup_name)
+ if resolved:
+ return _resolve_path_or_original(Path(resolved))
+ return candidate
+
+
+def _looks_like_specify_entrypoint(path: Path) -> bool:
+ """Return whether a path looks like the `specify` CLI entrypoint."""
+ return path.name.lower() in {"specify", "specify.exe", "specify-cli", "specify-cli.exe"}
+
+
+def _tier3_registry_lookup_allowed(argv0_path: Path) -> bool:
+ """Return whether tier-3 registry reconciliation is safe for this entrypoint."""
+ return argv0_path.is_absolute() and not argv0_path.exists()
+
+
+def _uv_tool_list_contains_specify_cli(stdout: str) -> bool:
+ """Return whether `uv tool list` output includes an exact `specify-cli` entry."""
+ for raw_line in stdout.splitlines():
+ line = raw_line.strip()
+ if not line:
+ continue
+ first_token = line.split(None, 1)[0]
+ if first_token == "specify-cli":
+ return True
+ return False
+
+
+def _git_ancestor(path: Path) -> Path | None:
+ """Return the closest ancestor that looks like a git worktree root."""
+ for ancestor in [path, *path.parents]:
+ if (ancestor / ".git").exists():
+ return ancestor
+ return None
+
+
+def _editable_direct_url_path() -> Path | None:
+ """Return the editable checkout root recorded in direct_url.json, if any."""
+ import importlib.metadata as _md
+
+ metadata_errors = [_md.PackageNotFoundError]
+ invalid_metadata_error = getattr(_md, "InvalidMetadataError", None)
+ if invalid_metadata_error is not None:
+ metadata_errors.append(invalid_metadata_error)
+
+ try:
+ dist = _md.distribution("specify-cli")
+ except tuple(metadata_errors):
+ return None
+
+ payload = dist.read_text("direct_url.json")
+ if not payload:
+ return None
+
+ try:
+ data = json.loads(payload)
+ except (TypeError, ValueError):
+ return None
+ if not data.get("dir_info", {}).get("editable"):
+ return None
+
+ url = data.get("url")
+ if not isinstance(url, str):
+ return None
+
+ parsed = urllib.parse.urlsplit(url)
+ if parsed.scheme != "file":
+ return None
+
+ url_path = urllib.request.url2pathname(urllib.parse.unquote(parsed.path))
+ if parsed.netloc and parsed.netloc not in {"", "localhost"}:
+ url_path = f"//{parsed.netloc}{url_path}"
+
+ try:
+ return Path(url_path).resolve()
+ except OSError:
+ return None
+
+
+def _editable_marker_seen() -> bool:
+ """Return whether the installed distribution is explicitly marked editable."""
+ editable_root = _editable_direct_url_path()
+ return editable_root is not None and _git_ancestor(editable_root) is not None
+
+
+def _detect_install_method(
+ argv0: str | None = None,
+ include_signals: bool = False,
+) -> "_InstallMethod | tuple[_InstallMethod, _DetectionSignals]":
+ """Classify the current runtime into exactly one _InstallMethod.
+
+ Detection order:
+ 1. `sys.argv[0]` path prefix match against `_INSTALLER_PATH_PREFIXES`
+ 2. editable-install marker
+ 3. installer registry reconciliation (`uv tool list` / `pipx list`)
+
+ When `include_signals=True`, also return `_DetectionSignals`.
+ """
+ argv0_path = _resolved_argv0_path(argv0)
+ argv0_resolved = str(argv0_path)
+
+ # --- Tier 1: path prefix match ---
+ for method_str, prefixes in _INSTALLER_PATH_PREFIXES.items():
+ for prefix in prefixes:
+ expanded = _expand_prefix(prefix)
+ if expanded is None:
+ continue
+ if _path_is_within_prefix(argv0_path, expanded):
+ method = _InstallMethod(method_str)
+ if include_signals:
+ return method, _DetectionSignals(
+ sys_argv0=argv0_resolved,
+ matched_tier=1,
+ matched_prefix=prefix,
+ editable_marker_seen=False,
+ installer_registries_consulted=(),
+ resolved_method=method,
+ )
+ return method
+
+ # --- Tier 2: editable install marker ---
+ if _editable_marker_seen():
+ method = _InstallMethod.SOURCE_CHECKOUT
+ if include_signals:
+ return method, _DetectionSignals(
+ sys_argv0=argv0_resolved,
+ matched_tier=2,
+ matched_prefix=None,
+ editable_marker_seen=True,
+ installer_registries_consulted=(),
+ resolved_method=method,
+ )
+ return method
+
+ # --- Tier 3: PATH + registry reconciliation ---
+ consulted: list[str] = []
+ if _tier3_registry_lookup_allowed(argv0_path):
+ uv_tool_match = False
+ uv_bin = shutil.which("uv")
+ if uv_bin is not None:
+ consulted.append("uv tool list")
+ try:
+ result = subprocess.run(
+ [uv_bin, "tool", "list"],
+ capture_output=True,
+ text=True,
+ timeout=_TIER3_REGISTRY_TIMEOUT_SECS,
+ env=_scrubbed_env(),
+ check=False,
+ )
+ if result.returncode == 0 and _uv_tool_list_contains_specify_cli(
+ result.stdout or ""
+ ):
+ uv_tool_match = True
+ except (subprocess.TimeoutExpired, OSError, ValueError):
+ pass
+
+ pipx_match = False
+ pipx_bin = shutil.which("pipx")
+ if pipx_bin is not None:
+ consulted.append("pipx list --json")
+ try:
+ result = subprocess.run(
+ [pipx_bin, "list", "--json"],
+ capture_output=True,
+ text=True,
+ timeout=_TIER3_REGISTRY_TIMEOUT_SECS,
+ env=_scrubbed_env(),
+ check=False,
+ )
+ if result.returncode == 0:
+ payload = json.loads(result.stdout or "")
+ venvs = payload.get("venvs") if isinstance(payload, dict) else None
+ if isinstance(venvs, dict) and "specify-cli" in venvs:
+ pipx_match = True
+ except (subprocess.TimeoutExpired, OSError, ValueError):
+ pass
+
+ # If both registries claim ownership, the active entrypoint is ambiguous.
+ # Treat it as unsupported rather than guessing and upgrading the wrong install.
+ exactly_one_match = uv_tool_match != pipx_match
+ if exactly_one_match:
+ method = _InstallMethod.UV_TOOL if uv_tool_match else _InstallMethod.PIPX
+ if include_signals:
+ return method, _DetectionSignals(
+ sys_argv0=argv0_resolved,
+ matched_tier=3,
+ matched_prefix=None,
+ editable_marker_seen=False,
+ installer_registries_consulted=tuple(consulted),
+ resolved_method=method,
+ )
+ return method
+
+ # Fallthrough
+ method = _InstallMethod.UNSUPPORTED
+ if include_signals:
+ return method, _DetectionSignals(
+ sys_argv0=argv0_resolved,
+ matched_tier=None,
+ matched_prefix=None,
+ editable_marker_seen=False,
+ installer_registries_consulted=tuple(consulted),
+ resolved_method=method,
+ )
+ return method
+
+
+_GITHUB_SOURCE_URL = "git+https://github.com/github/spec-kit.git"
+_MANUAL_TAG_PLACEHOLDER = "vX.Y.Z"
+
+
+def _source_spec(target_tag: str | None) -> str:
+ """Build a git source spec, optionally pinned to a release tag."""
+ return f"{_GITHUB_SOURCE_URL}@{target_tag}" if target_tag else _GITHUB_SOURCE_URL
+
+
+def _manual_source_spec(target_tag: str | None) -> str:
+ """Build a stable-release-oriented source spec for manual guidance."""
+ return f"{_GITHUB_SOURCE_URL}@{target_tag or _MANUAL_TAG_PLACEHOLDER}"
+
+
+def _manual_tag_or_placeholder(tag: str | None) -> str | None:
+ """Return a validated release tag for copy/paste guidance, or None."""
+ if tag is None:
+ return None
+ try:
+ return _validate_tag(tag)
+ except typer.BadParameter:
+ return None
+
+
+def _assemble_installer_argv(
+ method: _InstallMethod, target_tag: str | None
+) -> list[str] | None:
+ """Build the installer argv for an upgradable install method."""
+ source_spec = _source_spec(target_tag)
+
+ if method == _InstallMethod.UV_TOOL:
+ uv_bin = shutil.which("uv")
+ if uv_bin is None:
+ return None
+ return [
+ uv_bin,
+ "tool",
+ "install",
+ "specify-cli",
+ "--force",
+ "--from",
+ source_spec,
+ ]
+
+ if method == _InstallMethod.PIPX:
+ # pipx 1.5+ removed `--spec`; PACKAGE_SPEC is now positional and the
+ # package name is auto-detected from the source's pyproject.toml.
+ pipx_bin = shutil.which("pipx")
+ if pipx_bin is None:
+ return None
+ return [
+ pipx_bin,
+ "install",
+ "--force",
+ source_spec,
+ ]
+
+ return None
+
+
+def _installer_binary_name(method: _InstallMethod) -> str | None:
+ """Return the installer executable name for upgradable methods."""
+ if method == _InstallMethod.UV_TOOL:
+ return "uv"
+ if method == _InstallMethod.PIPX:
+ return "pipx"
+ return None
+
+
+def _is_path_like_command(value: str) -> bool:
+ """Return whether an argv[0] names a path rather than a bare command."""
+ return Path(value).parent != Path(".") or "/" in value or "\\" in value
+
+
+def _method_label(method: _InstallMethod) -> str:
+ """Render the user-facing label for an install method."""
+ return {
+ _InstallMethod.UV_TOOL: "uv tool",
+ _InstallMethod.PIPX: "pipx",
+ _InstallMethod.UVX_EPHEMERAL: "uvx (ephemeral)",
+ _InstallMethod.SOURCE_CHECKOUT: "source checkout",
+ _InstallMethod.UNSUPPORTED: "unsupported",
+ }[method]
+
+
+def _build_upgrade_plan(
+ target_tag_override: str | None,
+) -> tuple[_UpgradePlan | None, str | None]:
+ """Return a resolved upgrade plan or `(None, failure_reason)`.
+
+ A valid `target_tag_override` skips network resolution entirely.
+ A fetched target tag is validated before installer argv construction.
+ """
+ method = _detect_install_method()
+
+ if target_tag_override is not None:
+ target_tag = target_tag_override
+ elif method in (_InstallMethod.UV_TOOL, _InstallMethod.PIPX):
+ tag, failure_reason = _fetch_latest_release_tag()
+ if tag is None:
+ return None, failure_reason # surfaces as exit 1 in the orchestrator
+ try:
+ target_tag = _validate_tag(tag)
+ except typer.BadParameter:
+ current = _get_installed_version()
+ return (
+ _UpgradePlan(
+ method=method,
+ current_version=current,
+ target_tag=tag,
+ installer_argv=None,
+ preview_summary="",
+ pre_upgrade_snapshot=current,
+ ),
+ _FAILURE_TARGET_TAG_UNPARSEABLE,
+ )
+ else:
+ target_tag = None
+
+ current = _get_installed_version()
+ argv = _assemble_installer_argv(method, target_tag)
+ if argv is None and method in (_InstallMethod.UV_TOOL, _InstallMethod.PIPX):
+ command_preview = (
+ f"(installer {_installer_binary_name(method)} not found on PATH)"
+ )
+ else:
+ command_preview = (
+ _render_argv(argv) if argv is not None else "(none β€” non-upgradable path)"
+ )
+
+ preview = (
+ f"Detected install method: {_method_label(method)}\n"
+ f"Current version: {current}\n"
+ f"Target version: {target_tag or '(not resolved for this install method)'}\n"
+ f"Command that would be executed: {command_preview}"
+ )
+
+ plan = _UpgradePlan(
+ method=method,
+ current_version=current,
+ target_tag=target_tag,
+ installer_argv=argv,
+ preview_summary=preview,
+ pre_upgrade_snapshot=current,
+ )
+ return plan, None
+
+
+def _warn_invalid_upgrade_timeout(timeout_raw: str) -> None:
+ """Warn that SPECIFY_UPGRADE_TIMEOUT_SECS could not be applied."""
+ console.print(
+ f"Ignoring invalid SPECIFY_UPGRADE_TIMEOUT_SECS={timeout_raw!r}; "
+ "running without a timeout.",
+ soft_wrap=True,
+ )
+
+
+def _installer_exited_result(
+ completed: subprocess.CompletedProcess,
+) -> _InstallerResult:
+ """Return the normalized result for a real installer process exit."""
+ return _InstallerResult(_InstallerResultKind.EXITED, completed.returncode)
+
+
+def _run_installer(plan: _UpgradePlan) -> _InstallerResult:
+ """Invoke the installer subprocess.
+
+ Returns a normalized `_InstallerResult` so internal states (missing,
+ invalid, timeout) cannot be confused with real installer exit codes.
+
+ stdout/stderr are inherited (not captured) so the user sees installer
+ progress in real time. The child environment has GitHub credential-shaped
+ variables removed.
+
+ Timeout: by default the subprocess runs with no timeout β€” installer
+ operations (dependency resolution, large wheel downloads) can legitimately
+ take many minutes. Set the env var SPECIFY_UPGRADE_TIMEOUT_SECS to an
+ integer/float to enforce a hard cap. On timeout, the orchestrator maps
+ `_InstallerResultKind.TIMEOUT` to user-facing exit code `124`. A real
+ installer process that exits 124 is returned as EXITED with returncode 124.
+ An unparseable, non-positive, or non-finite timeout value emits a warning
+ and runs without a timeout.
+ """
+ if plan.installer_argv is None:
+ # Internal routing error: the orchestrator must route non-upgradable
+ # methods to _emit_guidance and never reach this function. Use a real
+ # raise (not assert) so the guard survives `python -O`.
+ raise RuntimeError(
+ "internal routing error: _run_installer received a plan without an "
+ "installer_argv (non-upgradable methods must route to _emit_guidance)"
+ )
+
+ # Use the argv assembled at plan-build time verbatim. The pre-execution
+ # notice and the actual subprocess argv must be byte-for-byte identical;
+ # any re-resolution here would risk diverging from what the user just
+ # saw printed. A lightweight pre-flight via `shutil.which` short-circuits
+ # the obvious "binary disappeared" case before spawning, and the
+ # try/except below catches the residual race window.
+ installer_name = plan.installer_argv[0]
+ installer_cmd = Path(installer_name)
+ if installer_cmd.is_absolute():
+ if not installer_cmd.exists():
+ return _InstallerResult(_InstallerResultKind.MISSING)
+ elif not installer_cmd.is_file() or not os.access(installer_cmd, os.X_OK):
+ return _InstallerResult(_InstallerResultKind.INVALID)
+ elif _is_path_like_command(installer_name):
+ if not installer_cmd.exists():
+ return _InstallerResult(_InstallerResultKind.MISSING)
+ if not installer_cmd.is_file() or not os.access(installer_cmd, os.X_OK):
+ return _InstallerResult(_InstallerResultKind.INVALID)
+ elif shutil.which(installer_name) is None:
+ return _InstallerResult(_InstallerResultKind.MISSING)
+
+ timeout_raw = os.environ.get("SPECIFY_UPGRADE_TIMEOUT_SECS")
+ timeout: float | None = None
+ if timeout_raw is not None:
+ try:
+ timeout = float(timeout_raw)
+ if timeout <= 0 or not math.isfinite(timeout):
+ _warn_invalid_upgrade_timeout(timeout_raw)
+ timeout = None
+ except ValueError:
+ _warn_invalid_upgrade_timeout(timeout_raw)
+ timeout = None
+
+ try:
+ completed = subprocess.run(
+ plan.installer_argv,
+ shell=False,
+ check=False,
+ env=_scrubbed_env(),
+ timeout=timeout,
+ )
+ return _installer_exited_result(completed)
+ except subprocess.TimeoutExpired:
+ return _InstallerResult(_InstallerResultKind.TIMEOUT)
+ except FileNotFoundError:
+ return _InstallerResult(_InstallerResultKind.MISSING)
+ except (PermissionError, IsADirectoryError):
+ return _InstallerResult(_InstallerResultKind.INVALID)
+ except OSError as exc:
+ if exc.errno in {errno.EACCES, errno.ENOEXEC, errno.EISDIR}:
+ return _InstallerResult(_InstallerResultKind.INVALID)
+ raise
+
+
+_VERIFY_VERSION_LINE_RE = re.compile(
+ r"^\s*(?:specify|specify-cli)\b(?P<rest>.*)$",
+ flags=re.IGNORECASE,
+)
+
+
+def _parse_verify_version_output(output: str) -> str | None:
+ """Return the first parseable version token from `specify --version` output."""
+ for line in output.splitlines():
+ match = _VERIFY_VERSION_LINE_RE.match(line)
+ if not match:
+ continue
+ for token in match.group("rest").split():
+ if _parse_version_text(token) is not None:
+ return token
+ return None
+
+
+def _verify_upgrade(plan: _UpgradePlan) -> str | None:
+ """Spawn a child `specify --version` and parse its output.
+
+ Returns the version string on success, None on parse failure, timeout,
+ or missing binary. Caller compares the returned version to plan.target_tag
+ and raises verification-mismatch if they differ.
+
+ Uses a child process (not in-process importlib.metadata) because Python
+ cannot hot-swap the running module after the installer has replaced it β€”
+ only a fresh process picks up the new binary.
+ """
+ argv0 = _resolved_argv0_path()
+ specify_bin = (
+ str(argv0)
+ if (
+ argv0.exists()
+ and argv0.is_file()
+ and os.access(argv0, os.X_OK)
+ and _looks_like_specify_entrypoint(argv0)
+ )
+ else shutil.which("specify")
+ )
+ if specify_bin is None:
+ return None
+ try:
+ result = subprocess.run(
+ [specify_bin, "--version"],
+ shell=False,
+ check=False,
+ capture_output=True,
+ text=True,
+ timeout=_VERIFY_TIMEOUT_SECS,
+ env=_scrubbed_env(),
+ )
+ except (subprocess.TimeoutExpired, OSError):
+ return None
+ if result.returncode != 0:
+ return None
+ return _parse_verify_version_output(result.stdout or "")
+
+
+def _source_checkout_path() -> Path | None:
+ """Return the working-tree root for an editable install when discoverable."""
+ import importlib.metadata as _md
+
+ editable_root = _editable_direct_url_path()
+ if editable_root is not None:
+ git_root = _git_ancestor(editable_root)
+ if git_root is not None:
+ return git_root
+
+ metadata_errors = [_md.PackageNotFoundError]
+ invalid_metadata_error = getattr(_md, "InvalidMetadataError", None)
+ if invalid_metadata_error is not None:
+ metadata_errors.append(invalid_metadata_error)
+
+ try:
+ dist = _md.distribution("specify-cli")
+ except tuple(metadata_errors):
+ return None
+ files = dist.files or []
+ for f in files:
+ try:
+ abs_path = Path(dist.locate_file(f)).resolve()
+ except (OSError, RuntimeError, TypeError, ValueError):
+ continue
+ git_root = _git_ancestor(abs_path)
+ if git_root is not None:
+ return git_root
+ return None
+
+
+def _emit_guidance(method: _InstallMethod, target_tag: str | None) -> None:
+ """Print path-specific guidance for non-upgradable install methods."""
+ if method == _InstallMethod.UVX_EPHEMERAL:
+ console.print(
+ "Running via uvx (ephemeral); the next uvx invocation already "
+ "resolves to latest β€” no upgrade action needed.",
+ soft_wrap=True,
+ )
+ return
+
+ if method == _InstallMethod.SOURCE_CHECKOUT:
+ tree = _source_checkout_path()
+ if tree is None:
+ console.print(
+ "Running from a source checkout, but the checkout path could not "
+ "be detected; upgrade by running the following commands from your "
+ "checkout directory:",
+ soft_wrap=True,
+ )
+ else:
+ console.print(
+ f"Running from a source checkout at {tree}; "
+ "upgrade by running the following commands from that directory:",
+ soft_wrap=True,
+ )
+ console.print(" git pull")
+ console.print(" pip install -e .")
+ return
+
+ if method == _InstallMethod.UNSUPPORTED:
+ console.print(
+ "Could not identify your install method automatically; "
+ "run one of the following manually:",
+ soft_wrap=True,
+ )
+ console.print(
+ f" uv tool install specify-cli --force --from "
+ f"{_manual_source_spec(target_tag)}",
+ soft_wrap=True,
+ )
+ console.print(
+ f" pipx install --force {_manual_source_spec(target_tag)}",
+ soft_wrap=True,
+ )
+ return
+
+ raise RuntimeError(
+ f"internal routing error: _emit_guidance called on upgradable method: {method}"
+ )
+
+
+def _rollback_hint(plan: _UpgradePlan) -> str:
+ """Build a manual rollback suggestion from the pre-upgrade version."""
+ if plan.pre_upgrade_snapshot == "unknown":
+ return (
+ "Could not determine the previous version; "
+ "reinstall manually from: https://github.com/github/spec-kit/releases"
+ )
+ rollback_tag = _stable_release_tag_for_version(plan.pre_upgrade_snapshot)
+ if rollback_tag is None:
+ return (
+ "Previous version was not an exact stable release tag; "
+ "reinstall manually from: https://github.com/github/spec-kit/releases"
+ )
+ if plan.method == _InstallMethod.PIPX:
+ return (
+ f"To pin back to the previous version: pipx install --force "
+ f"git+https://github.com/github/spec-kit.git@{rollback_tag}"
+ )
+ return (
+ f"To pin back to the previous version: uv tool install specify-cli --force "
+ f"--from git+https://github.com/github/spec-kit.git@{rollback_tag}"
+ )
+
+
+def _emit_failure(
+ category: str,
+ plan: _UpgradePlan | None = None,
+ installer_exit: int | None = None,
+ installer_name: str | None = None,
+ verified_version: str | None = None,
+) -> None:
+ """Render user-facing output for resolver, installer, or verification failures."""
+ if (
+ category in _RESOLUTION_FAILURE_CATEGORIES
+ or category.startswith(_RESOLUTION_FAILURE_HTTP_PREFIX)
+ ):
+ console.print(f"Upgrade aborted: {category}", soft_wrap=True)
+ return
+
+ if category == _FAILURE_INSTALLER_MISSING:
+ if installer_name and (
+ os.path.isabs(installer_name) or _is_path_like_command(installer_name)
+ ):
+ console.print(
+ f"Installer path {installer_name} no longer exists; reinstall it and retry.",
+ soft_wrap=True,
+ )
+ else:
+ name = installer_name or "(unknown)"
+ console.print(
+ f"Installer {name} not found on PATH; reinstall it and retry.",
+ soft_wrap=True,
+ )
+ return
+
+ if category == _FAILURE_INSTALLER_INVALID:
+ name = installer_name or "(unknown)"
+ if installer_name and (
+ os.path.isabs(installer_name) or _is_path_like_command(installer_name)
+ ):
+ message = (
+ f"Installer path {name} is not an executable file; "
+ "fix the path or reinstall it and retry."
+ )
+ else:
+ message = (
+ f"Installer {name} is not executable; "
+ "fix the command or reinstall it and retry."
+ )
+ console.print(message, soft_wrap=True)
+ return
+
+ if category == _FAILURE_TARGET_TAG_UNPARSEABLE:
+ if plan is None:
+ raise RuntimeError(
+ "internal routing error: target-tag-unparseable requires plan to be set"
+ )
+ console.print(
+ "Upgrade aborted: resolved release tag is not a comparable version.",
+ soft_wrap=True,
+ )
+ console.print(
+ "Try again later or pin a stable release with --tag vX.Y.Z.",
+ soft_wrap=True,
+ )
+ return
+
+ if category == _FAILURE_INSTALLER_TIMEOUT:
+ if plan is None:
+ raise RuntimeError(
+ "internal routing error: installer-timeout requires plan to be set"
+ )
+ argv_str = _render_argv(plan.installer_argv) if plan.installer_argv else ""
+ timeout_value = os.environ.get("SPECIFY_UPGRADE_TIMEOUT_SECS", "(unknown)")
+ console.print(
+ "Upgrade timed out while waiting for the installer subprocess.",
+ soft_wrap=True,
+ )
+ console.print(
+ f"Configured timeout: SPECIFY_UPGRADE_TIMEOUT_SECS={timeout_value}",
+ soft_wrap=True,
+ )
+ console.print(
+ f"Try again or run the command manually: {argv_str}",
+ soft_wrap=True,
+ )
+ console.print(_rollback_hint(plan), soft_wrap=True)
+ return
+
+ if category == _FAILURE_INSTALLER_FAILED:
+ if plan is None or installer_exit is None:
+ raise RuntimeError(
+ "internal routing error: installer-failed requires both "
+ "plan and installer_exit to be set"
+ )
+ argv_str = _render_argv(plan.installer_argv) if plan.installer_argv else ""
+ console.print(
+ f"Upgrade failed. Installer exit code: {installer_exit}.",
+ soft_wrap=True,
+ )
+ console.print(
+ f"Try again or run the command manually: {argv_str}",
+ soft_wrap=True,
+ )
+ console.print(_rollback_hint(plan), soft_wrap=True)
+ return
+
+ if category == _FAILURE_VERIFICATION_MISMATCH:
+ if plan is None:
+ raise RuntimeError(
+ "internal routing error: verification-mismatch requires plan to be set"
+ )
+ verified_str = verified_version or "(unknown)"
+ console.print(
+ f"Verification failed: installer reported success but "
+ f"'specify --version' resolves to {verified_str} "
+ f"(expected {plan.target_tag}).",
+ soft_wrap=True,
+ )
+ console.print(
+ "The new version may take effect on your next invocation.",
+ soft_wrap=True,
+ )
+ return
+
+ raise RuntimeError(f"Unknown failure category: {category!r}")
+
+
+# ===== Self Commands =====
self_app = typer.Typer(
name="self",
- help="Manage the specify CLI itself (read-only check and reserved upgrade command).",
+ help=(
+ "Manage the specify CLI itself: check for newer releases, "
+ "preview upgrades with --dry-run, and upgrade in place."
+ ),
add_completion=False,
)
@@ -113,11 +1144,11 @@ 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.
- The reserved (and currently non-destructive) `specify self upgrade` command
- is the name that a future release will use for actual self-upgrade β€” its
- behavior is not implemented in this release and is intentionally out of
- scope here. See `specify self upgrade --help` for its current status.
+ 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()
@@ -130,44 +1161,269 @@ def self_check() -> None:
console.print(f"[yellow]Could not check latest release:[/yellow] {failure_reason}")
return
- latest_normalized = _normalize_tag(tag)
+ 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":
# 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_normalized}")
- console.print("\nTo reinstall:")
- console.print(" uv tool install specify-cli --force \\")
- console.print(f" --from git+https://github.com/github/spec-kit.git@{tag}")
+ 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_normalized}")
+ console.print(f"[green]Update available:[/green] {installed} β†’ {latest_display}")
console.print("\nTo upgrade:")
- console.print(" uv tool install specify-cli --force \\")
- console.print(f" --from git+https://github.com/github/spec-kit.git@{tag}")
+ 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
- # Installed is parseable AND is >= latest β†’ "up to date" (FR-006).
- # Also reached when the tag is unparseable (InvalidVersion) β†’ _is_newer
- # returns False, and the up-to-date branch is the safer default per
- # FR-004 / test T016.
+ # 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() -> None:
- """Reserved command surface for self-upgrade; not implemented in this release.
+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.
- This command is a documented non-destructive stub in this release: it
- performs no outbound network request, no install-method detection, and
- invokes no installer. It prints a three-line guidance message and exits 0.
- Actual self-upgrade is planned as follow-up work.
+ 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
- Use `specify self check` today to see whether a newer release is available
- and to get a copy-pasteable reinstall command.
+ 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.
"""
- console.print("specify self upgrade is not implemented yet.")
- console.print("Run 'specify self check' to see whether a newer release is available.")
- console.print("Actual self-upgrade is planned as follow-up work.")
+ if tag is not None:
+ try:
+ tag = _validate_tag(tag)
+ except typer.BadParameter as exc:
+ console.print(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,
+ )
diff --git a/tests/conftest.py b/tests/conftest.py
index 0e568a1e2..4ef643e12 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -81,3 +81,72 @@ def _isolate_auth_config(monkeypatch):
# Also clear the per-process cache so tests that unset _config_override
# won't see a previously cached real-file result.
monkeypatch.setattr(_auth_http, "_config_cache", None)
+
+
+def clean_environ(monkeypatch):
+ """Strip any real GH_TOKEN / GITHUB_TOKEN from the test environment."""
+ monkeypatch.delenv("GH_TOKEN", raising=False)
+ monkeypatch.delenv("GITHUB_TOKEN", raising=False)
+
+
+def _fake_self_upgrade_argv0(monkeypatch, tmp_path, env_name, path_parts):
+ """Create a fake executable under tmp_path and point sys.argv[0] at it."""
+ monkeypatch.setenv(env_name, str(tmp_path))
+ fake_dir = tmp_path.joinpath(*path_parts)
+ fake_dir.mkdir(parents=True)
+ fake_specify = fake_dir / ("specify.exe" if os.name == "nt" else "specify")
+ fake_specify.write_text("#!/usr/bin/env python\n")
+ fake_specify.chmod(0o755)
+ monkeypatch.setattr("sys.argv", [str(fake_specify)])
+ return fake_specify
+
+
+def uv_tool_argv0(monkeypatch, tmp_path):
+ """Point sys.argv[0] at a simulated `uv tool` install path under tmp HOME."""
+ if os.name == "nt":
+ return _fake_self_upgrade_argv0(
+ monkeypatch, tmp_path, "LOCALAPPDATA", ("uv", "tools", "specify-cli", "bin")
+ )
+ return _fake_self_upgrade_argv0(
+ monkeypatch,
+ tmp_path,
+ "HOME",
+ (".local", "share", "uv", "tools", "specify-cli", "bin"),
+ )
+
+
+def pipx_argv0(monkeypatch, tmp_path):
+ """Point sys.argv[0] at a simulated pipx install path under tmp HOME."""
+ if os.name == "nt":
+ return _fake_self_upgrade_argv0(
+ monkeypatch, tmp_path, "LOCALAPPDATA", ("pipx", "venvs", "specify-cli", "bin")
+ )
+ return _fake_self_upgrade_argv0(
+ monkeypatch, tmp_path, "HOME", (".local", "pipx", "venvs", "specify-cli", "bin")
+ )
+
+
+def uvx_ephemeral_argv0(monkeypatch, tmp_path):
+ """Point sys.argv[0] at a simulated uvx ephemeral-cache path under tmp HOME."""
+ if os.name == "nt":
+ return _fake_self_upgrade_argv0(
+ monkeypatch,
+ tmp_path,
+ "LOCALAPPDATA",
+ ("uv", "cache", "archive-v0", "abc123", "bin"),
+ )
+ return _fake_self_upgrade_argv0(
+ monkeypatch, tmp_path, "HOME", (".cache", "uv", "archive-v0", "abc123", "bin")
+ )
+
+
+def unsupported_argv0(monkeypatch, tmp_path):
+ """Point sys.argv[0] at a path that does not match any installer prefix."""
+ return _fake_self_upgrade_argv0(
+ monkeypatch, tmp_path, "HOME", ("random", "location", "bin")
+ )
diff --git a/tests/http_helpers.py b/tests/http_helpers.py
new file mode 100644
index 000000000..46e26806b
--- /dev/null
+++ b/tests/http_helpers.py
@@ -0,0 +1,15 @@
+"""HTTP test helpers shared by version-related CLI tests."""
+
+import json
+from unittest.mock import MagicMock
+
+
+def mock_urlopen_response(payload: dict) -> MagicMock:
+ """Build a urlopen context-manager mock whose read returns JSON."""
+ body = json.dumps(payload).encode("utf-8")
+ resp = MagicMock()
+ resp.read.return_value = body
+ cm = MagicMock()
+ cm.__enter__.return_value = resp
+ cm.__exit__.return_value = False
+ return cm
diff --git a/tests/self_upgrade_helpers.py b/tests/self_upgrade_helpers.py
new file mode 100644
index 000000000..c363f57b1
--- /dev/null
+++ b/tests/self_upgrade_helpers.py
@@ -0,0 +1,64 @@
+"""Shared fixtures and helpers for `specify self upgrade` tests.
+
+These helpers patch subprocess, PATH lookup, and release-tag resolution so
+the focused test modules stay isolated from the real environment.
+"""
+
+import os
+import subprocess
+
+import pytest
+from typer.testing import CliRunner
+
+from specify_cli._version import (
+ _InstallMethod,
+ _UpgradePlan,
+ _assemble_installer_argv,
+ _detect_install_method,
+ _verify_upgrade,
+)
+from tests.conftest import strip_ansi
+from tests.http_helpers import mock_urlopen_response
+
+__all__ = (
+ "SENTINEL_GH_TOKEN",
+ "SENTINEL_GITHUB_TOKEN",
+ "_InstallMethod",
+ "_UpgradePlan",
+ "_assemble_installer_argv",
+ "_completed_process",
+ "_detect_install_method",
+ "_verify_upgrade",
+ "mock_urlopen_response",
+ "requires_posix",
+ "runner",
+ "strip_ansi",
+)
+
+runner = CliRunner()
+
+# Some installer error-path tests create a relative `./uv` fixture, `chdir`
+# into the tmp dir, and assert POSIX executable-bit semantics (chmod / X_OK).
+# None of that maps cleanly onto Windows: `os.access(path, X_OK)` ignores the
+# mode bits, and pytest cannot rmtree a tmp dir that is still the cwd, so the
+# fixtures raise PermissionError during teardown. Skip these on Windows β€” the
+# realistic absolute-path and bare-PATH-command branches stay covered there.
+requires_posix = pytest.mark.skipif(
+ os.name == "nt",
+ reason="relative-path / executable-bit semantics are POSIX-only",
+)
+
+SENTINEL_GH_TOKEN = "SENTINEL-GH-TOKEN-VALUE"
+SENTINEL_GITHUB_TOKEN = "SENTINEL-GITHUB-TOKEN-VALUE"
+
+
+def _completed_process(
+ returncode: int, stdout: str = "", stderr: str = ""
+) -> subprocess.CompletedProcess:
+ """Build a subprocess.CompletedProcess for installer / verification calls."""
+ return subprocess.CompletedProcess(
+ args=["mocked"],
+ returncode=returncode,
+ stdout=stdout,
+ stderr=stderr,
+ )
diff --git a/tests/test_self_upgrade_detection.py b/tests/test_self_upgrade_detection.py
new file mode 100644
index 000000000..ab575e743
--- /dev/null
+++ b/tests/test_self_upgrade_detection.py
@@ -0,0 +1,887 @@
+"""Detection, argv assembly, and dry-run tests for `specify self upgrade`."""
+
+import importlib.metadata
+import json
+import os
+import subprocess
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+import specify_cli
+from specify_cli import app
+
+from tests.self_upgrade_helpers import (
+ _InstallMethod,
+ _assemble_installer_argv,
+ _completed_process,
+ _detect_install_method,
+ mock_urlopen_response,
+ runner,
+ strip_ansi,
+)
+
+
+class TestDetectionUvTool:
+ """Tier-1 path-prefix detection for uv-tool installs."""
+
+ def test_posix_uv_tool_prefix_matches(self, uv_tool_argv0):
+ method, signals = _detect_install_method(include_signals=True)
+ assert method == _InstallMethod.UV_TOOL
+ assert signals.matched_tier == 1
+ assert "uv/tools/specify-cli" in signals.matched_prefix.replace("\\", "/")
+
+ def test_detection_is_deterministic(self, uv_tool_argv0):
+ a = _detect_install_method()
+ b = _detect_install_method()
+ assert a == b == _InstallMethod.UV_TOOL
+
+ def test_no_argv_match_falls_through_to_unsupported(self, unsupported_argv0):
+ with patch("specify_cli._version.shutil.which", return_value=None), patch(
+ "specify_cli._version._editable_marker_seen", return_value=False
+ ):
+ method = _detect_install_method()
+ assert method == _InstallMethod.UNSUPPORTED
+
+ def test_include_signals_false_returns_bare_enum(self, uv_tool_argv0):
+ result = _detect_install_method(include_signals=False)
+ assert isinstance(result, _InstallMethod)
+
+ def test_bare_argv0_is_resolved_via_path_lookup(self, monkeypatch, tmp_path):
+ if os.name == "nt":
+ monkeypatch.setenv("LOCALAPPDATA", str(tmp_path))
+ fake_dir = tmp_path / "uv" / "tools" / "specify-cli" / "bin"
+ else:
+ monkeypatch.setenv("HOME", str(tmp_path))
+ fake_dir = (
+ tmp_path / ".local" / "share" / "uv" / "tools" / "specify-cli" / "bin"
+ )
+ fake_dir.mkdir(parents=True)
+ fake_specify = fake_dir / "specify"
+ fake_specify.write_text("#!/usr/bin/env python\n")
+ monkeypatch.setattr("sys.argv", ["specify"])
+ with patch(
+ "specify_cli._version.shutil.which",
+ side_effect=lambda name: str(fake_specify) if name == "specify" else None,
+ ):
+ method = _detect_install_method()
+ assert method == _InstallMethod.UV_TOOL
+
+ def test_prefix_match_does_not_accept_sibling_directory(self, monkeypatch, tmp_path):
+ monkeypatch.setenv("HOME", str(tmp_path))
+ fake_dir = tmp_path / ".local" / "share" / "uv" / "tools" / "specify-cli2" / "bin"
+ fake_dir.mkdir(parents=True)
+ fake_specify = fake_dir / "specify"
+ fake_specify.write_text("#!/usr/bin/env python\n")
+ monkeypatch.setattr("sys.argv", [str(fake_specify)])
+ with patch("specify_cli._version.shutil.which", return_value=None), patch(
+ "specify_cli._version._editable_marker_seen", return_value=False
+ ):
+ method = _detect_install_method()
+ assert method == _InstallMethod.UNSUPPORTED
+
+ def test_tier3_uv_tool_when_registry_lists_exact_name(
+ self,
+ monkeypatch,
+ tmp_path,
+ ):
+ monkeypatch.setattr("sys.argv", [str(tmp_path / "missing" / "specify")])
+
+ def fake_which(name):
+ return "uv" if name == "uv" else None
+
+ def fake_run(argv, *args, **kwargs):
+ if argv[:3] == ["uv", "tool", "list"]:
+ return subprocess.CompletedProcess(
+ args=argv,
+ returncode=0,
+ stdout="specify-cli v0.7.6\nother-tool v1.2.3\n",
+ stderr="",
+ )
+ return subprocess.CompletedProcess(
+ args=argv, returncode=1, stdout="", stderr=""
+ )
+
+ with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+ "specify_cli._version.subprocess.run", side_effect=fake_run
+ ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+ method, signals = _detect_install_method(include_signals=True)
+ assert method == _InstallMethod.UV_TOOL
+ assert signals.matched_tier == 3
+ assert "uv tool list" in signals.installer_registries_consulted
+
+ def test_unresolved_bare_argv0_skips_tier3_registry_detection(self, monkeypatch):
+ monkeypatch.setattr("sys.argv", ["specify"])
+
+ def fake_which(name):
+ return "uv" if name == "uv" else None
+
+ def fake_run(argv, *args, **kwargs):
+ return subprocess.CompletedProcess(
+ args=argv,
+ returncode=0,
+ stdout="specify-cli v0.7.6\n",
+ stderr="",
+ )
+
+ with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+ "specify_cli._version.subprocess.run", side_effect=fake_run
+ ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+ method, signals = _detect_install_method(include_signals=True)
+ assert method == _InstallMethod.UNSUPPORTED
+ assert signals.installer_registries_consulted == ()
+
+ def test_bare_argv0_missing_path_resolution_allows_tier3_registry_detection(
+ self, monkeypatch, tmp_path
+ ):
+ missing_specify = tmp_path / "missing" / "specify"
+ monkeypatch.setattr("sys.argv", ["specify"])
+
+ def fake_which(name):
+ if name == "specify":
+ return str(missing_specify)
+ if name == "uv":
+ return "uv"
+ return None
+
+ def fake_run(argv, *args, **kwargs):
+ if argv[:3] == ["uv", "tool", "list"]:
+ return subprocess.CompletedProcess(
+ args=argv,
+ returncode=0,
+ stdout="specify-cli v0.7.6\n",
+ stderr="",
+ )
+ return subprocess.CompletedProcess(
+ args=argv, returncode=1, stdout="", stderr=""
+ )
+
+ with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+ "specify_cli._version.subprocess.run", side_effect=fake_run
+ ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+ method, signals = _detect_install_method(include_signals=True)
+
+ assert method == _InstallMethod.UV_TOOL
+ assert signals.matched_tier == 3
+ assert "uv tool list" in signals.installer_registries_consulted
+
+ def test_missing_relative_argv0_falls_back_to_entrypoint_name_lookup(
+ self, monkeypatch, tmp_path
+ ):
+ if os.name == "nt":
+ monkeypatch.setenv("LOCALAPPDATA", str(tmp_path))
+ fake_dir = tmp_path / "uv" / "tools" / "specify-cli" / "bin"
+ else:
+ monkeypatch.setenv("HOME", str(tmp_path))
+ fake_dir = (
+ tmp_path / ".local" / "share" / "uv" / "tools" / "specify-cli" / "bin"
+ )
+ fake_dir.mkdir(parents=True)
+ fake_specify = fake_dir / "specify"
+ fake_specify.write_text("#!/usr/bin/env python\n")
+ monkeypatch.setattr("sys.argv", ["./bin/specify"])
+
+ def fake_which(name):
+ return str(fake_specify) if name == "specify" else None
+
+ with patch("specify_cli._version.shutil.which", side_effect=fake_which):
+ method = _detect_install_method()
+
+ assert method == _InstallMethod.UV_TOOL
+
+ def test_tier3_uv_tool_ignores_substring_false_positive(
+ self,
+ unsupported_argv0,
+ ):
+ def fake_which(name):
+ return "uv" if name == "uv" else None
+
+ def fake_run(argv, *args, **kwargs):
+ if argv[:3] == ["uv", "tool", "list"]:
+ return subprocess.CompletedProcess(
+ args=argv,
+ returncode=0,
+ stdout="my-specify-cli-helper v0.1.0\n",
+ stderr="",
+ )
+ return subprocess.CompletedProcess(
+ args=argv, returncode=1, stdout="", stderr=""
+ )
+
+ with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+ "specify_cli._version.subprocess.run", side_effect=fake_run
+ ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+ method = _detect_install_method()
+ assert method == _InstallMethod.UNSUPPORTED
+
+ def test_tier3_uv_tool_does_not_override_absolute_unsupported_entrypoint(
+ self,
+ unsupported_argv0,
+ ):
+ def fake_which(name):
+ return "uv" if name == "uv" else None
+
+ def fake_run(argv, *args, **kwargs):
+ if argv[:3] == ["uv", "tool", "list"]:
+ return subprocess.CompletedProcess(
+ args=argv,
+ returncode=0,
+ stdout="specify-cli v0.7.6\n",
+ stderr="",
+ )
+ return subprocess.CompletedProcess(
+ args=argv, returncode=1, stdout="", stderr=""
+ )
+
+ with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+ "specify_cli._version.subprocess.run", side_effect=fake_run
+ ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+ method = _detect_install_method()
+ assert method == _InstallMethod.UNSUPPORTED
+
+ def test_tier3_uv_tool_does_not_override_resolved_bare_unsupported_entrypoint(
+ self,
+ monkeypatch,
+ tmp_path,
+ ):
+ venv_bin = tmp_path / "venv" / "bin"
+ venv_bin.mkdir(parents=True)
+ fake_specify = venv_bin / "specify"
+ fake_specify.write_text("#!/usr/bin/env python\n")
+ fake_specify.chmod(0o755)
+ monkeypatch.setattr("sys.argv", ["specify"])
+
+ def fake_which(name):
+ if name == "specify":
+ return str(fake_specify)
+ if name == "uv":
+ return "uv"
+ return None
+
+ def fake_run(argv, *args, **kwargs):
+ if argv[:3] == ["uv", "tool", "list"]:
+ return subprocess.CompletedProcess(
+ args=argv,
+ returncode=0,
+ stdout="specify-cli v0.7.6\n",
+ stderr="",
+ )
+ return subprocess.CompletedProcess(
+ args=argv, returncode=1, stdout="", stderr=""
+ )
+
+ with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+ "specify_cli._version.subprocess.run", side_effect=fake_run
+ ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+ method, signals = _detect_install_method(include_signals=True)
+ assert method == _InstallMethod.UNSUPPORTED
+ assert signals.matched_tier is None
+ assert signals.installer_registries_consulted == ()
+
+
+class TestPrefixExpansion:
+ """Path-prefix expansion edge cases."""
+
+ def test_literal_dollar_without_variable_name_is_preserved(self, tmp_path):
+ prefix_path = tmp_path / "specify-$-cache" / "tools" / "specify-cli"
+ prefix = str(prefix_path)
+
+ expanded = specify_cli._version._expand_prefix(prefix)
+
+ assert expanded == prefix_path.resolve()
+
+ def test_unresolved_posix_variable_is_rejected(self):
+ assert specify_cli._version._expand_prefix("$SPECIFY_MISSING/specify-cli/") is None
+
+ def test_absolute_prefix_resolve_oserror_is_rejected(self, tmp_path):
+ prefix = str(tmp_path / "specify-cli")
+
+ with patch("pathlib.Path.resolve", side_effect=OSError("bad path")):
+ assert specify_cli._version._expand_prefix(prefix) is None
+
+
+class TestArgv0Resolution:
+ """Entrypoint path resolution edge cases."""
+
+ def test_absolute_argv0_resolve_oserror_returns_original_path(self, tmp_path):
+ argv0 = tmp_path / "specify"
+
+ with patch("pathlib.Path.resolve", side_effect=OSError("bad path")):
+ assert specify_cli._version._resolved_argv0_path(str(argv0)) == argv0
+
+ def test_path_lookup_resolve_oserror_returns_unresolved_lookup_path(self):
+ with patch(
+ "specify_cli._version.shutil.which", return_value="/broken/specify"
+ ), patch("pathlib.Path.resolve", side_effect=OSError("bad path")):
+ result = specify_cli._version._resolved_argv0_path("specify")
+
+ # Compare as Path objects: on Windows the same logical path renders
+ # with backslashes, so a raw string compare against the POSIX form
+ # would spuriously fail.
+ assert result == Path("/broken/specify")
+
+
+class TestArgvAssemblyUvTool:
+ """uv-tool installer argv shape."""
+
+ def test_stable_tag_produces_expected_argv(self):
+ with patch("specify_cli._version.shutil.which", return_value="uv"):
+ argv = _assemble_installer_argv(_InstallMethod.UV_TOOL, "v0.7.6")
+ assert argv == [
+ "uv",
+ "tool",
+ "install",
+ "specify-cli",
+ "--force",
+ "--from",
+ "git+https://github.com/github/[email protected]",
+ ]
+
+ def test_dev_suffix_tag_embedded_literally(self):
+ with patch("specify_cli._version.shutil.which", return_value="uv"):
+ argv = _assemble_installer_argv(_InstallMethod.UV_TOOL, "v0.8.0.dev0")
+ assert "git+https://github.com/github/[email protected]" in argv
+ assert (
+ "upgrade" not in argv
+ ) # never `uv tool upgrade` β€” does not accept --tag pinning
+
+ def test_missing_uv_returns_no_installer_argv(self):
+ with patch("specify_cli._version.shutil.which", return_value=None):
+ assert _assemble_installer_argv(_InstallMethod.UV_TOOL, "v0.7.6") is None
+
+
+class TestBareUpgradeUvTool:
+ """uv-tool happy path, bare invocation."""
+
+ def test_happy_path_end_to_end(self, uv_tool_argv0, clean_environ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ mock_run.side_effect = [
+ _completed_process(0), # installer
+ _completed_process(0, stdout="specify 0.7.6\n"), # verify
+ ]
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 0
+ out = strip_ansi(result.output)
+ assert "Upgrading specify-cli 0.7.5 β†’ v0.7.6 via uv tool:" in out
+ assert "Upgraded specify-cli: 0.7.5 β†’ 0.7.6" in out
+ assert mock_run.call_count == 2
+ for call in mock_run.call_args_list:
+ assert call.kwargs.get("shell", False) is False
+
+ def test_one_user_action_no_prompt(self, uv_tool_argv0, clean_environ):
+ # The single `invoke` represents the single user action β€” no prompt.
+ # If a prompt existed, runner.invoke would hang waiting for input.
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ mock_run.side_effect = [
+ _completed_process(0),
+ _completed_process(0, stdout="specify 0.7.6\n"),
+ ]
+ result = runner.invoke(app, ["self", "upgrade"])
+ assert result.exit_code == 0
+
+
+class TestAlreadyLatestUvTool:
+ """already on latest, no installer launched."""
+
+ def test_already_latest_exits_zero_no_subprocess(
+ self, uv_tool_argv0, clean_environ
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.subprocess.run"
+ ) as mock_run, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version._get_installed_version", return_value="0.7.6"):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 0
+ assert "Already on latest release: v0.7.6" in strip_ansi(result.output)
+ assert mock_run.call_count == 0
+
+ def test_trailing_zero_equivalent_version_reports_latest_not_newer(
+ self, uv_tool_argv0, clean_environ
+ ):
+ # Version("1.0") == Version("1.0.0") under packaging even though their
+ # canonical strings differ. The no-op message must use Version equality
+ # so this prints "Already on latest release", not "... or newer".
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.subprocess.run"
+ ) as mock_run, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version._get_installed_version", return_value="1.0"):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v1.0.0"})
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 0
+ out = strip_ansi(result.output)
+ assert "Already on latest release: v1.0.0" in out
+ assert "or newer" not in out
+ assert mock_run.call_count == 0
+
+ def test_dev_build_ahead_of_release_reports_newer_noop(
+ self, uv_tool_argv0, clean_environ
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.subprocess.run"
+ ) as mock_run, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version._get_installed_version", return_value="0.7.7.dev0"):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 0
+ assert "Already on latest release or newer: 0.7.7.dev0" in strip_ansi(result.output)
+ assert mock_run.call_count == 0
+
+ def test_unparseable_current_version_does_not_false_noop(
+ self, uv_tool_argv0, clean_environ
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.subprocess.run"
+ ) as mock_run, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version._get_installed_version", return_value="release-main"):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ mock_run.side_effect = [
+ _completed_process(0),
+ _completed_process(0, stdout="specify 0.7.6\n"),
+ ]
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 0
+ out = strip_ansi(result.output)
+ assert "Already on latest release" not in out
+ assert "Upgrading specify-cli release-main β†’ v0.7.6 via uv tool:" in out
+ assert mock_run.call_count == 2
+
+ def test_unparseable_resolved_target_fails_before_literal_noop(
+ self, uv_tool_argv0, clean_environ
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.subprocess.run"
+ ) as mock_run, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version._get_installed_version", return_value="release-main"):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "release-main"})
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 1
+ out = strip_ansi(result.output)
+ assert "not a comparable version" in out
+ assert "release-main" not in out
+ assert "Already on latest release" not in out
+ assert mock_run.call_count == 0
+
+ def test_pinned_older_tag_still_runs_installer(
+ self, uv_tool_argv0, clean_environ
+ ):
+ with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+ "specify_cli._version.subprocess.run"
+ ) as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.6"
+ ):
+ mock_run.side_effect = [
+ _completed_process(0),
+ _completed_process(0, stdout="specify 0.7.5\n"),
+ ]
+ result = runner.invoke(app, ["self", "upgrade", "--tag", "v0.7.5"])
+
+ assert result.exit_code == 0
+ out = strip_ansi(result.output)
+ assert "Already on latest release" not in out
+ # A pinned older tag is a downgrade and must be labelled as such.
+ assert "Downgrading specify-cli 0.7.6 β†’ v0.7.5 via uv tool:" in out
+ assert "Upgrading specify-cli" not in out
+ assert mock_run.call_count == 2
+
+ def test_pinned_rc_tag_uses_canonical_version_equality_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.0rc1"
+ ):
+ result = runner.invoke(app, ["self", "upgrade", "--tag", "v1.0.0-rc1"])
+
+ assert result.exit_code == 0
+ assert "Already on requested release: v1.0.0-rc1" in strip_ansi(result.output)
+
+
+class TestDryRunUvTool:
+ """--dry-run preview path + --dry-run combined with --tag."""
+
+ def test_dry_run_without_tag_resolves_network_but_no_subprocess(
+ self,
+ uv_tool_argv0,
+ clean_environ,
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.subprocess.run"
+ ) as mock_run, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ result = runner.invoke(app, ["self", "upgrade", "--dry-run"])
+
+ assert result.exit_code == 0
+ out = strip_ansi(result.output)
+ assert "Dry run β€” no changes will be made." in out
+ assert "Detected install method: uv tool" in out
+ assert "Current version: 0.7.5" in out
+ assert "Target version: v0.7.6" in out
+ assert "Command that would be executed:" in out
+ assert mock_run.call_count == 0
+
+ def test_dry_run_with_tag_skips_network(self, uv_tool_argv0, clean_environ):
+ # --dry-run with --tag must NOT hit the network.
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.subprocess.run"
+ ), 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"],
+ )
+ assert result.exit_code == 0
+ assert "Target version: v0.8.0" in strip_ansi(result.output)
+ mock_urlopen.assert_not_called()
+
+ def test_dry_run_rejects_unparseable_network_tag_before_preview(
+ self, uv_tool_argv0, clean_environ
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.subprocess.run"
+ ) as mock_run, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"):
+ mock_urlopen.return_value = mock_urlopen_response(
+ {"tag_name": "v0.9.0;echo unsafe"}
+ )
+ result = runner.invoke(app, ["self", "upgrade", "--dry-run"])
+
+ out = strip_ansi(result.output)
+ assert result.exit_code == 1
+ assert "not a comparable version" in out
+ assert "v0.9.0;echo unsafe" not in out
+ assert "Command that would be executed:" not in out
+ assert mock_run.call_count == 0
+
+ def test_dry_run_with_missing_uv_flags_unresolved_installer(
+ self, uv_tool_argv0, clean_environ
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.subprocess.run"
+ ) as mock_run, patch(
+ "specify_cli._version.shutil.which", return_value=None
+ ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ result = runner.invoke(app, ["self", "upgrade", "--dry-run"])
+
+ assert result.exit_code == 0
+ out = strip_ansi(result.output)
+ assert "Command that would be executed: (installer uv not found on PATH)" in out
+ assert "uv tool install" not in out
+ assert mock_run.call_count == 0
+
+
+# ===========================================================================
+# Phase 4 β€” User Story 2: `pipx` immediate upgrade (P2)
+# ===========================================================================
+
+
+class TestDetectionPipx:
+ """Pipx detection β€” tier 1 (path) and tier 3 (registry)."""
+
+ def test_posix_pipx_prefix_matches(self, pipx_argv0):
+ method, signals = _detect_install_method(include_signals=True)
+ assert method == _InstallMethod.PIPX
+ assert signals.matched_tier == 1
+
+ def test_tier3_pipx_when_no_prefix_match_but_registry_lists_it(
+ self,
+ monkeypatch,
+ tmp_path,
+ ):
+ monkeypatch.setattr("sys.argv", [str(tmp_path / "missing" / "specify")])
+
+ def fake_which(name):
+ return "pipx" if name == "pipx" else None
+
+ def fake_run(argv, *args, **kwargs):
+ if argv[:3] == ["pipx", "list", "--json"]:
+ return subprocess.CompletedProcess(
+ args=argv,
+ returncode=0,
+ stdout='{"venvs":{"specify-cli":{}}}',
+ stderr="",
+ )
+ return subprocess.CompletedProcess(
+ args=argv, returncode=1, stdout="", stderr=""
+ )
+
+ with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+ "specify_cli._version.subprocess.run", side_effect=fake_run
+ ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+ method, signals = _detect_install_method(include_signals=True)
+ assert method == _InstallMethod.PIPX
+ assert signals.matched_tier == 3
+ assert "pipx list --json" in signals.installer_registries_consulted
+
+ def test_tier3_pipx_does_not_override_absolute_unsupported_entrypoint(
+ self,
+ unsupported_argv0,
+ ):
+ def fake_which(name):
+ return "pipx" if name == "pipx" else None
+
+ def fake_run(argv, *args, **kwargs):
+ if argv[:3] == ["pipx", "list", "--json"]:
+ return subprocess.CompletedProcess(
+ args=argv,
+ returncode=0,
+ stdout='{"venvs":{"specify-cli":{}}}',
+ stderr="",
+ )
+ return subprocess.CompletedProcess(
+ args=argv, returncode=1, stdout="", stderr=""
+ )
+
+ with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+ "specify_cli._version.subprocess.run", side_effect=fake_run
+ ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+ method = _detect_install_method()
+ assert method == _InstallMethod.UNSUPPORTED
+
+ def test_tier3_pipx_ignores_malformed_json_output(
+ self,
+ unsupported_argv0,
+ ):
+ def fake_which(name):
+ return "pipx" if name == "pipx" else None
+
+ def fake_run(argv, *args, **kwargs):
+ if argv[:3] == ["pipx", "list", "--json"]:
+ return subprocess.CompletedProcess(
+ args=argv,
+ returncode=0,
+ stdout="not json but mentions specify-cli",
+ stderr="",
+ )
+ return subprocess.CompletedProcess(
+ args=argv, returncode=1, stdout="", stderr=""
+ )
+
+ with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+ "specify_cli._version.subprocess.run", side_effect=fake_run
+ ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+ method = _detect_install_method()
+ assert method == _InstallMethod.UNSUPPORTED
+
+ def test_tier3_both_uv_tool_and_pipx_match_is_treated_as_unsupported(
+ self,
+ monkeypatch,
+ tmp_path,
+ ):
+ monkeypatch.setattr("sys.argv", [str(tmp_path / "missing" / "specify")])
+
+ def fake_which(name):
+ if name == "uv":
+ return "uv"
+ if name == "pipx":
+ return "pipx"
+ return None
+
+ def fake_run(argv, *args, **kwargs):
+ if argv[:3] == ["uv", "tool", "list"]:
+ return subprocess.CompletedProcess(
+ args=argv,
+ returncode=0,
+ stdout="specify-cli v0.7.6\n",
+ stderr="",
+ )
+ if argv[:3] == ["pipx", "list", "--json"]:
+ return subprocess.CompletedProcess(
+ args=argv,
+ returncode=0,
+ stdout='{"venvs":{"specify-cli":{}}}',
+ stderr="",
+ )
+ return subprocess.CompletedProcess(
+ args=argv, returncode=1, stdout="", stderr=""
+ )
+
+ with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+ "specify_cli._version.subprocess.run", side_effect=fake_run
+ ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+ method, signals = _detect_install_method(include_signals=True)
+ assert method == _InstallMethod.UNSUPPORTED
+ assert signals.matched_tier is None
+ assert "uv tool list" in signals.installer_registries_consulted
+ assert "pipx list --json" in signals.installer_registries_consulted
+
+
+class TestEditableInstallMetadata:
+ @pytest.mark.skipif(
+ not hasattr(importlib.metadata, "InvalidMetadataError"),
+ reason=(
+ "importlib.metadata.InvalidMetadataError does not exist on this "
+ "Python; _editable_direct_url_path only catches it when present, so "
+ "fabricating it would exercise a path that cannot fire in production"
+ ),
+ )
+ def test_editable_marker_false_when_metadata_is_invalid(self):
+ invalid_metadata_error = importlib.metadata.InvalidMetadataError
+
+ with patch(
+ "importlib.metadata.distribution",
+ side_effect=invalid_metadata_error("bad metadata"),
+ ):
+ assert specify_cli._version._editable_marker_seen() is False
+ assert specify_cli._version._source_checkout_path() is None
+
+ def test_direct_url_editable_install_marks_source_checkout(self, tmp_path):
+ project_root = tmp_path / "spec-kit"
+ project_root.mkdir()
+ (project_root / ".git").mkdir()
+
+ class FakeDist:
+ files = []
+
+ def read_text(self, name):
+ if name == "direct_url.json":
+ return json.dumps(
+ {
+ "dir_info": {"editable": True},
+ "url": project_root.as_uri(),
+ }
+ )
+ return None
+
+ def locate_file(self, file):
+ return file
+
+ with patch("importlib.metadata.distribution", return_value=FakeDist()):
+ assert specify_cli._version._editable_marker_seen() is True
+ assert specify_cli._version._source_checkout_path() == project_root.resolve()
+
+ def test_editable_marker_false_without_explicit_editable_metadata(self, tmp_path):
+ repo_root = tmp_path / "repo"
+ repo_root.mkdir()
+ (repo_root / ".git").mkdir()
+ venv_file = repo_root / ".venv" / "lib" / "python3.13" / "site-packages" / "specify_cli.py"
+ venv_file.parent.mkdir(parents=True)
+ venv_file.write_text("# installed module\n")
+
+ class FakeDist:
+ files = ["specify_cli.py"]
+
+ def read_text(self, name):
+ return None
+
+ def locate_file(self, file):
+ return venv_file
+
+ with patch("importlib.metadata.distribution", return_value=FakeDist()):
+ assert specify_cli._version._editable_marker_seen() is False
+
+
+class TestTagValidationWhitespace:
+ def test_tag_whitespace_is_trimmed_before_validation(self, uv_tool_argv0, clean_environ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v9.9.9"})
+ mock_run.side_effect = [
+ _completed_process(0),
+ _completed_process(0, stdout="specify 0.8.0\n"),
+ ]
+ result = runner.invoke(app, ["self", "upgrade", "--tag", " v0.8.0 "])
+
+ assert result.exit_code == 0
+ assert "v0.8.0" in strip_ansi(result.output)
+
+
+class TestArgvAssemblyPipx:
+ """pipx installer argv shape β€” pipx 1.5+ uses positional PACKAGE_SPEC, never `--spec` or `upgrade`."""
+
+ def test_pipx_argv_uses_install_force_positional_not_upgrade(self):
+ with patch("specify_cli._version.shutil.which", return_value="pipx"):
+ argv = _assemble_installer_argv(_InstallMethod.PIPX, "v0.7.6")
+ assert argv == [
+ "pipx",
+ "install",
+ "--force",
+ "git+https://github.com/github/[email protected]",
+ ]
+ assert "upgrade" not in argv # pipx upgrade does not accept arbitrary refs
+ assert "--spec" not in argv # pipx 1.5+ dropped the --spec flag
+
+ def test_missing_pipx_returns_no_installer_argv(self):
+ with patch("specify_cli._version.shutil.which", return_value=None):
+ assert _assemble_installer_argv(_InstallMethod.PIPX, "v0.7.6") is None
+
+
+class TestBareUpgradePipx:
+ """pipx happy path."""
+
+ def test_happy_path(self, pipx_argv0, clean_environ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="pipx"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ mock_run.side_effect = [
+ _completed_process(0),
+ _completed_process(0, stdout="specify 0.7.6\n"),
+ ]
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 0
+ out = strip_ansi(result.output)
+ assert "via pipx:" in out
+ assert "Upgraded specify-cli: 0.7.5 β†’ 0.7.6" in out
+
+
+class TestDetectionShortCircuit:
+ """Tier-1 path-prefix matches short-circuit before registry checks."""
+
+ def test_pipx_argv0_prefix_short_circuits_before_registry_checks(
+ self,
+ pipx_argv0,
+ clean_environ,
+ ):
+ with patch("specify_cli._version.shutil.which", return_value="/usr/bin/X"), patch(
+ "specify_cli._version.subprocess.run"
+ ) as mock_run:
+ method = _detect_install_method()
+ assert method == _InstallMethod.PIPX
+ mock_run.assert_not_called()
+
+
+class TestDryRunPipx:
+ def test_dry_run_preview_names_pipx(self, pipx_argv0, clean_environ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="pipx"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ result = runner.invoke(app, ["self", "upgrade", "--dry-run"])
+ assert result.exit_code == 0
+ assert "Detected install method: pipx" in strip_ansi(result.output)
+ assert mock_run.call_count == 0
diff --git a/tests/test_self_upgrade_execution.py b/tests/test_self_upgrade_execution.py
new file mode 100644
index 000000000..6696b4fc7
--- /dev/null
+++ b/tests/test_self_upgrade_execution.py
@@ -0,0 +1,542 @@
+"""Installer execution, verification, and error-path tests for `specify self upgrade`."""
+
+import errno
+import subprocess
+from unittest.mock import patch
+
+from specify_cli import app
+
+from tests.self_upgrade_helpers import (
+ _completed_process,
+ mock_urlopen_response,
+ requires_posix,
+ runner,
+ strip_ansi,
+)
+
+# ===========================================================================
+# Phase 6 β€” User Story 4: failure recovery (P2)
+# ===========================================================================
+
+
+class TestInstallerMissing:
+ """Installer disappeared between detection and run β†’ exit 3."""
+
+ def test_uv_missing_exits_3(self, uv_tool_argv0, clean_environ):
+ which_results = {"specify": "/usr/local/bin/specify"}
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", side_effect=lambda n: which_results.get(n)
+ ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ result = runner.invoke(app, ["self", "upgrade"])
+ assert result.exit_code == 3
+ out = strip_ansi(result.output)
+ assert "Installer uv not found on PATH; reinstall it and retry." in out
+ assert "Upgrading specify-cli" not in out
+
+ def test_pipx_missing_exits_3(self, pipx_argv0, clean_environ):
+ which_results = {}
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", side_effect=lambda n: which_results.get(n)
+ ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ result = runner.invoke(app, ["self", "upgrade"])
+ assert result.exit_code == 3
+ assert "Installer pipx not found on PATH" in strip_ansi(result.output)
+
+ def test_absolute_installer_path_does_not_require_path_lookup(
+ self, uv_tool_argv0, clean_environ, tmp_path
+ ):
+ fake_uv = tmp_path / "installer-bin" / "uv"
+ fake_uv.parent.mkdir()
+ fake_uv.write_text("#!/bin/sh\n")
+ fake_uv.chmod(0o755)
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", side_effect=lambda name: None
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ), patch(
+ "specify_cli._version._verify_upgrade", return_value="0.7.6"
+ ), patch(
+ "specify_cli._version._assemble_installer_argv",
+ return_value=[
+ str(fake_uv),
+ "tool",
+ "install",
+ "specify-cli",
+ "--force",
+ "--from",
+ "git+https://github.com/github/[email protected]",
+ ],
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ mock_run.side_effect = [_completed_process(0)]
+ result = runner.invoke(app, ["self", "upgrade"])
+ assert result.exit_code == 0
+
+ @requires_posix
+ def test_relative_installer_path_does_not_require_path_lookup(
+ self, monkeypatch, uv_tool_argv0, clean_environ, tmp_path
+ ):
+ fake_uv = tmp_path / "uv"
+ fake_uv.write_text("#!/bin/sh\n")
+ fake_uv.chmod(0o755)
+ monkeypatch.chdir(tmp_path)
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", side_effect=lambda name: None
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ), patch(
+ "specify_cli._version._verify_upgrade", return_value="0.7.6"
+ ), patch(
+ "specify_cli._version._assemble_installer_argv",
+ return_value=[
+ "./uv",
+ "tool",
+ "install",
+ "specify-cli",
+ "--force",
+ "--from",
+ "git+https://github.com/github/[email protected]",
+ ],
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ mock_run.side_effect = [_completed_process(0)]
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 0
+ assert mock_run.call_args.args[0][0] == "./uv"
+
+ @requires_posix
+ def test_relative_installer_path_missing_gets_path_specific_message(
+ self, monkeypatch, uv_tool_argv0, clean_environ, tmp_path
+ ):
+ monkeypatch.chdir(tmp_path)
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", side_effect=lambda name: None
+ ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"), patch(
+ "specify_cli._version._assemble_installer_argv",
+ return_value=[
+ "./uv",
+ "tool",
+ "install",
+ "specify-cli",
+ "--force",
+ "--from",
+ "git+https://github.com/github/[email protected]",
+ ],
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 3
+ assert (
+ "Installer path ./uv no longer exists; reinstall it and retry."
+ in strip_ansi(result.output)
+ )
+ assert "not found on PATH" not in strip_ansi(result.output)
+
+ def test_resolved_absolute_installer_removed_before_exec_gets_missing_path_message(
+ self, uv_tool_argv0, clean_environ, tmp_path
+ ):
+ fake_uv = tmp_path / "installer-bin" / "uv"
+ fake_uv.parent.mkdir()
+ fake_uv.write_text("#!/bin/sh\n")
+ fake_uv.chmod(0o755)
+
+ def fake_run(argv, *args, **kwargs):
+ fake_uv.unlink()
+ raise FileNotFoundError(str(fake_uv))
+
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which",
+ side_effect=lambda name: str(fake_uv) if name == "uv" else None,
+ ), patch("specify_cli._version.subprocess.run", side_effect=fake_run), patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 3
+ assert (
+ f"Installer path {fake_uv} no longer exists; reinstall it and retry."
+ in strip_ansi(result.output)
+ )
+
+ def test_absolute_installer_path_not_executable_gets_specific_message(
+ self, uv_tool_argv0, clean_environ, tmp_path
+ ):
+ fake_uv = tmp_path / "installer-bin" / "uv"
+ fake_uv.parent.mkdir()
+ fake_uv.write_text("#!/bin/sh\n")
+ fake_uv.chmod(0o644)
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", side_effect=lambda name: None
+ ), patch("specify_cli._version.os.access", return_value=False), patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ), patch(
+ "specify_cli._version._assemble_installer_argv",
+ return_value=[
+ str(fake_uv),
+ "tool",
+ "install",
+ "specify-cli",
+ "--force",
+ "--from",
+ "git+https://github.com/github/[email protected]",
+ ],
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ result = runner.invoke(app, ["self", "upgrade"])
+ assert result.exit_code == 3
+ assert (
+ f"Installer path {fake_uv} is not an executable file; fix the path or reinstall it and retry."
+ in strip_ansi(result.output)
+ )
+
+ @requires_posix
+ def test_relative_installer_path_not_executable_gets_path_specific_message(
+ self, monkeypatch, uv_tool_argv0, clean_environ, tmp_path
+ ):
+ fake_uv = tmp_path / "uv"
+ fake_uv.write_text("#!/bin/sh\n")
+ fake_uv.chmod(0o644)
+ monkeypatch.chdir(tmp_path)
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", side_effect=lambda name: None
+ ), patch("specify_cli._version.os.access", return_value=False), patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ), patch(
+ "specify_cli._version._assemble_installer_argv",
+ return_value=[
+ "./uv",
+ "tool",
+ "install",
+ "specify-cli",
+ "--force",
+ "--from",
+ "git+https://github.com/github/[email protected]",
+ ],
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ out = strip_ansi(result.output)
+ assert result.exit_code == 3
+ assert (
+ "Installer path ./uv is not an executable file; fix the path or reinstall it and retry."
+ in out
+ )
+ assert "Installer ./uv is not executable" not in out
+
+ def test_real_installer_exit_126_is_not_treated_as_invalid_path(
+ self, uv_tool_argv0, clean_environ
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ mock_run.side_effect = [_completed_process(126)]
+ result = runner.invoke(app, ["self", "upgrade"])
+ assert result.exit_code == 126
+ out = strip_ansi(result.output)
+ assert "Upgrade failed. Installer exit code: 126." in out
+ assert "not an executable file" not in out
+
+ def test_absolute_installer_path_missing_gets_path_specific_message(
+ self, uv_tool_argv0, clean_environ, tmp_path
+ ):
+ fake_uv = tmp_path / "missing-installer" / "uv"
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", side_effect=lambda name: None
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ), patch(
+ "specify_cli._version._assemble_installer_argv",
+ return_value=[
+ str(fake_uv),
+ "tool",
+ "install",
+ "specify-cli",
+ "--force",
+ "--from",
+ "git+https://github.com/github/[email protected]",
+ ],
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ result = runner.invoke(app, ["self", "upgrade"])
+ assert result.exit_code == 3
+ assert (
+ f"Installer path {fake_uv} no longer exists; reinstall it and retry."
+ in strip_ansi(result.output)
+ )
+ mock_run.assert_not_called()
+
+ def test_exec_oserror_is_treated_as_invalid_installer(
+ self, uv_tool_argv0, clean_environ, tmp_path
+ ):
+ fake_uv = tmp_path / "installer-bin" / "uv"
+ fake_uv.parent.mkdir()
+ fake_uv.write_text("#!/usr/bin/env bash\n", encoding="utf-8")
+ fake_uv.chmod(0o755)
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", side_effect=lambda name: None
+ ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"), patch(
+ "specify_cli._version._assemble_installer_argv",
+ return_value=[
+ str(fake_uv),
+ "tool",
+ "install",
+ "specify-cli",
+ "--force",
+ "--from",
+ "git+https://github.com/github/[email protected]",
+ ],
+ ), patch(
+ "specify_cli._version.subprocess.run",
+ side_effect=PermissionError("Permission denied"),
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ result = runner.invoke(app, ["self", "upgrade"])
+ assert result.exit_code == 3
+ out = strip_ansi(result.output)
+ assert f"Installer path {fake_uv} is not an executable file" in out
+ assert "not found on PATH" not in out
+
+ def test_bare_invalid_installer_message_does_not_call_it_a_path(
+ self, uv_tool_argv0, clean_environ
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"), patch(
+ "specify_cli._version._assemble_installer_argv",
+ return_value=[
+ "uv",
+ "tool",
+ "install",
+ "specify-cli",
+ "--force",
+ "--from",
+ "git+https://github.com/github/[email protected]",
+ ],
+ ), patch(
+ "specify_cli._version.subprocess.run",
+ side_effect=PermissionError("Permission denied"),
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 3
+ out = strip_ansi(result.output)
+ assert "Installer uv is not executable" in out
+ assert "Installer path uv" not in out
+
+ def test_exec_oserror_errno_is_treated_as_invalid_installer(
+ self, uv_tool_argv0, clean_environ, tmp_path
+ ):
+ fake_uv = tmp_path / "installer-bin" / "uv"
+ fake_uv.parent.mkdir()
+ fake_uv.write_text("#!/usr/bin/env bash\n", encoding="utf-8")
+ fake_uv.chmod(0o755)
+ invalid_error = OSError(errno.ENOEXEC, "Exec format error")
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", side_effect=lambda name: None
+ ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"), patch(
+ "specify_cli._version._assemble_installer_argv",
+ return_value=[
+ str(fake_uv),
+ "tool",
+ "install",
+ "specify-cli",
+ "--force",
+ "--from",
+ "git+https://github.com/github/[email protected]",
+ ],
+ ), patch("specify_cli._version.subprocess.run", side_effect=invalid_error):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ result = runner.invoke(app, ["self", "upgrade"])
+ assert result.exit_code == 3
+ out = strip_ansi(result.output)
+ assert f"Installer path {fake_uv} is not an executable file" in out
+ assert "not found on PATH" not in out
+
+ def test_transient_exec_oserror_is_not_treated_as_invalid_installer(
+ self, uv_tool_argv0, clean_environ, tmp_path
+ ):
+ fake_uv = tmp_path / "installer-bin" / "uv"
+ fake_uv.parent.mkdir()
+ fake_uv.write_text("#!/usr/bin/env bash\n", encoding="utf-8")
+ fake_uv.chmod(0o755)
+ transient_error = OSError(errno.EMFILE, "Too many open files")
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", side_effect=lambda name: None
+ ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"), patch(
+ "specify_cli._version._assemble_installer_argv",
+ return_value=[
+ str(fake_uv),
+ "tool",
+ "install",
+ "specify-cli",
+ "--force",
+ "--from",
+ "git+https://github.com/github/[email protected]",
+ ],
+ ), patch("specify_cli._version.subprocess.run", side_effect=transient_error):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ result = runner.invoke(app, ["self", "upgrade"])
+ # Transient/unknown OSErrors are re-raised rather than mapped to the
+ # invalid-installer exit 3, so the CLI surfaces them as an uncaught
+ # error: exit code 1 with the original OSError preserved.
+ assert result.exit_code == 1
+ assert isinstance(result.exception, OSError)
+
+
+class TestInstallerFailed:
+ """Installer non-zero exit β†’ propagate code, print rollback hint."""
+
+ def test_installer_exit_2_propagates(self, uv_tool_argv0, clean_environ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ mock_run.side_effect = [_completed_process(2)] # installer fails
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 2
+ out = strip_ansi(result.output)
+ assert "Upgrade failed. Installer exit code: 2." in out
+ assert "Try again or run the command manually:" in out
+ assert "git+https://github.com/github/[email protected]" in out
+ assert (
+ "To pin back to the previous version: "
+ "uv tool install specify-cli --force --from "
+ "git+https://github.com/github/[email protected]"
+ ) in out
+ # No verification attempted after a failed installer run.
+ assert mock_run.call_count == 1
+
+ def test_installer_exit_127_propagates(self, uv_tool_argv0, clean_environ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ mock_run.side_effect = [_completed_process(127)]
+ result = runner.invoke(app, ["self", "upgrade"])
+ assert result.exit_code == 127
+
+ def test_installer_timeout_prints_timeout_specific_message(
+ self, uv_tool_argv0, clean_environ, monkeypatch
+ ):
+ monkeypatch.setenv("SPECIFY_UPGRADE_TIMEOUT_SECS", "12")
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ mock_run.side_effect = [
+ subprocess.TimeoutExpired(cmd=["uv"], timeout=12)
+ ]
+ result = runner.invoke(app, ["self", "upgrade"])
+ assert result.exit_code == 124
+ out = strip_ansi(result.output)
+ assert "Upgrade timed out while waiting for the installer subprocess." in out
+ assert "SPECIFY_UPGRADE_TIMEOUT_SECS=12" in out
+
+ def test_non_finite_timeout_warns_and_runs_without_timeout(
+ self, uv_tool_argv0, clean_environ, monkeypatch
+ ):
+ monkeypatch.setenv("SPECIFY_UPGRADE_TIMEOUT_SECS", "nan")
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ mock_run.side_effect = [
+ _completed_process(0),
+ _completed_process(0, stdout="specify 0.7.6\n"),
+ ]
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 0
+ assert "Ignoring invalid SPECIFY_UPGRADE_TIMEOUT_SECS='nan'" in strip_ansi(
+ result.output
+ )
+ assert mock_run.call_args_list[0].kwargs["timeout"] is None
+
+ def test_real_installer_exit_124_is_not_treated_as_timeout(
+ self, uv_tool_argv0, clean_environ
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ mock_run.side_effect = [_completed_process(124)]
+ result = runner.invoke(app, ["self", "upgrade"])
+ assert result.exit_code == 124
+ out = strip_ansi(result.output)
+ assert "Upgrade failed. Installer exit code: 124." in out
+ assert "Upgrade timed out while waiting for the installer subprocess." not in out
+
+ def test_pipx_failure_prints_pipx_rollback_hint(self, pipx_argv0, clean_environ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="pipx"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ mock_run.side_effect = [_completed_process(2)]
+ result = runner.invoke(app, ["self", "upgrade"])
+ assert result.exit_code == 2
+ out = strip_ansi(result.output)
+ assert (
+ "To pin back to the previous version: pipx install --force "
+ "git+https://github.com/github/[email protected]"
+ ) in out
+
+ def test_rollback_hint_accepts_normalizable_stable_snapshot(
+ self, uv_tool_argv0, clean_environ
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="v0.7.5"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ mock_run.side_effect = [_completed_process(2)]
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 2
+ out = strip_ansi(result.output)
+ assert (
+ "To pin back to the previous version: uv tool install specify-cli --force "
+ "--from git+https://github.com/github/[email protected]"
+ ) in out
+ assert "Previous version was not an exact stable release tag" not in out
+
+ def test_prerelease_failure_degrades_rollback_hint_to_releases_page(
+ self, uv_tool_argv0, clean_environ
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="1.0.0rc1"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v1.0.0"})
+ mock_run.side_effect = [_completed_process(2)]
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 2
+ out = strip_ansi(result.output)
+ assert "Previous version was not an exact stable release tag" in out
+ assert "https://github.com/github/spec-kit/releases" in out
+ assert "git+https://github.com/github/[email protected]" not in out
diff --git a/tests/test_self_upgrade_guidance.py b/tests/test_self_upgrade_guidance.py
new file mode 100644
index 000000000..55d6c2bf7
--- /dev/null
+++ b/tests/test_self_upgrade_guidance.py
@@ -0,0 +1,184 @@
+"""Non-upgradable path guidance tests for `specify self upgrade`."""
+
+from unittest.mock import patch
+
+from specify_cli import app
+
+from tests.self_upgrade_helpers import (
+ mock_urlopen_response,
+ runner,
+ strip_ansi,
+)
+
+# ===========================================================================
+# Phase 5 β€” User Story 3: non-upgradable path guidance (P3)
+# ===========================================================================
+
+
+class TestUvxEphemeral:
+ """uvx ephemeral path emits exact one-liner, no installer call."""
+
+ def test_uvx_argv0_prints_exact_one_liner_and_exits_zero(
+ self,
+ uvx_ephemeral_argv0,
+ clean_environ,
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.subprocess.run"
+ ) as mock_run:
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ result = runner.invoke(app, ["self", "upgrade"])
+ assert result.exit_code == 0
+ expected = (
+ "Running via uvx (ephemeral); the next uvx invocation already "
+ "resolves to latest β€” no upgrade action needed."
+ )
+ assert expected in strip_ansi(result.output)
+ assert mock_run.call_count == 0
+
+ def test_offline_still_exits_zero_without_tag_resolution(
+ self,
+ uvx_ephemeral_argv0,
+ clean_environ,
+ ):
+ with patch(
+ "specify_cli.authentication.http.urllib.request.urlopen",
+ side_effect=AssertionError("non-upgradable uvx path must not hit network"),
+ ):
+ result = runner.invoke(app, ["self", "upgrade"])
+ assert result.exit_code == 0
+ assert "uvx (ephemeral)" in strip_ansi(result.output)
+
+
+class TestSourceCheckout:
+ """Editable install path emits git pull guidance."""
+
+ def test_source_checkout_prints_git_pull_guidance(
+ self,
+ unsupported_argv0,
+ tmp_path,
+ clean_environ,
+ ):
+ fake_tree = tmp_path / "worktree"
+ fake_tree.mkdir()
+ (fake_tree / ".git").mkdir()
+
+ with patch("specify_cli._version._editable_marker_seen", return_value=True), patch(
+ "specify_cli._version._source_checkout_path", return_value=fake_tree
+ ), patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.subprocess.run"
+ ) as mock_run:
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 0
+ out = strip_ansi(result.output)
+ assert f"Running from a source checkout at {fake_tree}" in out
+ assert "git pull" in out
+ assert "pip install -e ." in out
+ assert mock_run.call_count == 0
+
+ def test_source_checkout_without_path_mentions_checkout_directory(
+ self,
+ unsupported_argv0,
+ clean_environ,
+ ):
+ with patch("specify_cli._version._editable_marker_seen", return_value=True), patch(
+ "specify_cli._version._source_checkout_path", return_value=None
+ ), patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.subprocess.run"
+ ) as mock_run:
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ out = strip_ansi(result.output)
+ assert result.exit_code == 0
+ assert "checkout path could not be detected" in out
+ assert "from your checkout directory" in out
+ assert "(path unavailable)" not in out
+ assert mock_run.call_count == 0
+
+
+class TestUnsupported:
+ """Unsupported path enumerates manual reinstall commands."""
+
+ def test_unsupported_prints_both_reinstall_commands(
+ self,
+ unsupported_argv0,
+ clean_environ,
+ ):
+ with patch("specify_cli._version._editable_marker_seen", return_value=False), patch(
+ "specify_cli._version.shutil.which", return_value=None
+ ), patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.subprocess.run"
+ ) as mock_run:
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 0
+ out = strip_ansi(result.output)
+ assert "Could not identify your install method automatically" in out
+ assert (
+ "uv tool install specify-cli --force --from "
+ "git+https://github.com/github/[email protected]"
+ ) in out
+ assert (
+ "pipx install --force git+https://github.com/github/[email protected]"
+ in out
+ )
+ assert mock_run.call_count == 0
+
+ def test_unsupported_offline_degrades_to_placeholder_manual_commands(
+ self,
+ unsupported_argv0,
+ clean_environ,
+ ):
+ with patch("specify_cli._version._editable_marker_seen", return_value=False), patch(
+ "specify_cli._version.shutil.which", return_value=None
+ ), patch(
+ "specify_cli.authentication.http.urllib.request.urlopen",
+ side_effect=AssertionError("unsupported guidance should not require network"),
+ ):
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 0
+ out = strip_ansi(result.output)
+ assert "Could not identify your install method automatically" in out
+ assert (
+ "uv tool install specify-cli --force --from "
+ "git+https://github.com/github/[email protected]"
+ ) in out
+ assert (
+ "pipx install --force git+https://github.com/github/[email protected]"
+ in out
+ )
+
+
+class TestDryRunNonUpgradablePaths:
+ """--dry-run on non-upgradable paths emits guidance, not preview."""
+
+ def test_dry_run_on_uvx_ephemeral_emits_guidance_not_preview(
+ self,
+ uvx_ephemeral_argv0,
+ clean_environ,
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen:
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ result = runner.invoke(app, ["self", "upgrade", "--dry-run"])
+ assert result.exit_code == 0
+ out = strip_ansi(result.output)
+ assert "Dry run β€” no changes will be made." not in out
+ assert "uvx (ephemeral)" in out
+
+ def test_dry_run_on_unsupported_emits_manual_commands(
+ self,
+ unsupported_argv0,
+ clean_environ,
+ ):
+ with patch("specify_cli._version._editable_marker_seen", return_value=False), patch(
+ "specify_cli._version.shutil.which", return_value=None
+ ), patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen:
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ result = runner.invoke(app, ["self", "upgrade", "--dry-run"])
+ assert result.exit_code == 0
+ assert "Could not identify your install method" in strip_ansi(result.output)
diff --git a/tests/test_self_upgrade_verification.py b/tests/test_self_upgrade_verification.py
new file mode 100644
index 000000000..f1a018f06
--- /dev/null
+++ b/tests/test_self_upgrade_verification.py
@@ -0,0 +1,649 @@
+"""Verification, resolution, and validation tests for `specify self upgrade`."""
+
+import urllib.error
+from unittest.mock import patch
+
+import pytest
+import specify_cli
+from specify_cli import app
+
+from tests.self_upgrade_helpers import (
+ SENTINEL_GH_TOKEN,
+ SENTINEL_GITHUB_TOKEN,
+ _InstallMethod,
+ _UpgradePlan,
+ _completed_process,
+ _verify_upgrade,
+ mock_urlopen_response,
+ runner,
+ strip_ansi,
+)
+
+# ===========================================================================
+# Phase 6 β€” User Story 4: failure recovery (P2)
+# ===========================================================================
+
+
+class TestVerificationMismatch:
+ """Installer says 0 but the binary is still the old version β†’ exit 2."""
+
+ def test_installer_ok_but_verify_returns_old_version(
+ self,
+ uv_tool_argv0,
+ clean_environ,
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ mock_run.side_effect = [
+ _completed_process(0), # installer OK
+ _completed_process(0, stdout="specify 0.7.5\n"), # verify: OLD!
+ ]
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 2
+ out = strip_ansi(result.output)
+ assert "Verification failed" in out
+ assert "resolves to 0.7.5 (expected v0.7.6)" in out
+ assert "The new version may take effect on your next invocation." in out
+
+ def test_verify_nonzero_exit_is_not_treated_as_success(
+ self,
+ uv_tool_argv0,
+ clean_environ,
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ mock_run.side_effect = [
+ _completed_process(0),
+ _completed_process(1, stdout="specify 0.7.6\n"),
+ ]
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 2
+ out = strip_ansi(result.output)
+ assert "Verification failed" in out
+ assert "(unknown) (expected v0.7.6)" in out
+
+ def test_verify_accepts_pep440_equivalent_rc_version(
+ self,
+ uv_tool_argv0,
+ clean_environ,
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.9.0"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v9.9.9"})
+ mock_run.side_effect = [
+ _completed_process(0),
+ _completed_process(0, stdout="specify 1.0.0rc1\n"),
+ ]
+ result = runner.invoke(app, ["self", "upgrade", "--tag", "v1.0.0-rc1"])
+
+ assert result.exit_code == 0
+ assert "Upgraded specify-cli: 0.9.0 β†’ 1.0.0rc1" in strip_ansi(result.output)
+
+ def test_verify_accepts_specify_cli_binary_name_in_version_output(
+ self,
+ uv_tool_argv0,
+ clean_environ,
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ mock_run.side_effect = [
+ _completed_process(0),
+ _completed_process(0, stdout="specify-cli version 0.7.6\n"),
+ ]
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 0
+ assert "Upgraded specify-cli: 0.7.5 β†’ 0.7.6" in strip_ansi(result.output)
+
+ def test_verify_accepts_capitalized_binary_name_in_version_output(
+ self,
+ uv_tool_argv0,
+ clean_environ,
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ mock_run.side_effect = [
+ _completed_process(0),
+ _completed_process(0, stdout="Specify, version 0.7.6\n"),
+ ]
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 0
+ assert "Upgraded specify-cli: 0.7.5 β†’ 0.7.6" in strip_ansi(result.output)
+
+ def test_verify_rejects_output_without_parseable_version(
+ self,
+ uv_tool_argv0,
+ clean_environ,
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ mock_run.side_effect = [
+ _completed_process(0),
+ _completed_process(0, stdout="specify version unknown\n"),
+ ]
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 2
+ out = strip_ansi(result.output)
+ assert "Verification failed" in out
+ assert "(unknown) (expected v0.7.6)" in out
+
+ def test_verify_uses_current_entrypoint_when_not_on_path(
+ self,
+ uv_tool_argv0,
+ clean_environ,
+ ):
+ assert uv_tool_argv0.exists()
+ assert uv_tool_argv0.is_file()
+
+ plan = _UpgradePlan(
+ method=_InstallMethod.UV_TOOL,
+ current_version="0.7.5",
+ target_tag="v0.7.6",
+ installer_argv=["/usr/bin/uv", "tool", "install", "specify-cli"],
+ preview_summary="",
+ pre_upgrade_snapshot="0.7.5",
+ )
+
+ with patch(
+ "specify_cli._version.shutil.which", side_effect=lambda name: None
+ ), patch(
+ "specify_cli._version.subprocess.run"
+ ) as mock_run, patch(
+ "specify_cli._version.os.access", return_value=True
+ ):
+ mock_run.return_value = _completed_process(0, stdout="specify 0.7.6\n")
+ verified = _verify_upgrade(plan)
+
+ assert verified == "0.7.6"
+ assert mock_run.call_args.args[0][0] == str(uv_tool_argv0)
+ assert mock_run.call_args.kwargs["timeout"] == specify_cli._version._VERIFY_TIMEOUT_SECS
+
+ def test_verify_falls_back_to_path_when_current_entrypoint_is_not_executable(
+ self,
+ uv_tool_argv0,
+ clean_environ,
+ ):
+ plan = _UpgradePlan(
+ method=_InstallMethod.UV_TOOL,
+ current_version="0.7.5",
+ target_tag="v0.7.6",
+ installer_argv=["/usr/bin/uv", "tool", "install", "specify-cli"],
+ preview_summary="",
+ pre_upgrade_snapshot="0.7.5",
+ )
+
+ with patch(
+ "specify_cli._version.shutil.which",
+ side_effect=lambda name: "/usr/local/bin/specify" if name == "specify" else None,
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version.os.access", return_value=False
+ ):
+ mock_run.return_value = _completed_process(0, stdout="specify 0.7.6\n")
+ verified = _verify_upgrade(plan)
+
+ assert verified == "0.7.6"
+ assert mock_run.call_args.args[0][0] == "/usr/local/bin/specify"
+
+ def test_verify_ignores_python_entrypoint_and_falls_back_to_specify(
+ self,
+ clean_environ,
+ tmp_path,
+ ):
+ fake_python = tmp_path / "python3"
+ fake_python.write_text("#!/bin/sh\n")
+ fake_python.chmod(0o755)
+
+ plan = _UpgradePlan(
+ method=_InstallMethod.UV_TOOL,
+ current_version="0.7.5",
+ target_tag="v0.7.6",
+ installer_argv=["/usr/bin/uv", "tool", "install", "specify-cli"],
+ preview_summary="",
+ pre_upgrade_snapshot="0.7.5",
+ )
+
+ with patch(
+ "specify_cli._version.shutil.which", side_effect=lambda name: "/usr/local/bin/specify" if name == "specify" else None
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version.sys.argv", [str(fake_python)]
+ ), patch(
+ "specify_cli._version.os.access", return_value=True
+ ):
+ mock_run.return_value = _completed_process(0, stdout="specify 0.7.6\n")
+ verified = _verify_upgrade(plan)
+
+ assert verified == "0.7.6"
+ assert mock_run.call_args.args[0][0] == "/usr/local/bin/specify"
+
+ def test_verify_accepts_specify_cli_named_current_entrypoint(
+ self,
+ clean_environ,
+ tmp_path,
+ ):
+ fake_specify_cli = tmp_path / "specify-cli"
+ fake_specify_cli.write_text("#!/bin/sh\n")
+ fake_specify_cli.chmod(0o755)
+
+ plan = _UpgradePlan(
+ method=_InstallMethod.UV_TOOL,
+ current_version="0.7.5",
+ target_tag="v0.7.6",
+ installer_argv=["/usr/bin/uv", "tool", "install", "specify-cli"],
+ preview_summary="",
+ pre_upgrade_snapshot="0.7.5",
+ )
+
+ with patch("specify_cli._version.shutil.which", return_value=None), patch(
+ "specify_cli._version.subprocess.run"
+ ) as mock_run, patch("specify_cli._version.sys.argv", [str(fake_specify_cli)]), patch(
+ "specify_cli._version.os.access", return_value=True
+ ):
+ mock_run.return_value = _completed_process(0, stdout="specify 0.7.6\n")
+ verified = _verify_upgrade(plan)
+
+ assert verified == "0.7.6"
+ assert mock_run.call_args.args[0][0] == str(fake_specify_cli)
+
+
+class TestResolutionFailures:
+ """Pre-installer resolution failure β†’ exit 1, reusing the resolver category strings."""
+
+ def test_offline_exits_1_with_phase1_string(self, uv_tool_argv0, clean_environ):
+ with patch(
+ "specify_cli.authentication.http.urllib.request.urlopen",
+ side_effect=urllib.error.URLError("nope"),
+ ):
+ result = runner.invoke(app, ["self", "upgrade"])
+ assert result.exit_code == 1
+ assert "Upgrade aborted: offline or timeout" in strip_ansi(result.output)
+
+ def test_rate_limited_exits_1(self, uv_tool_argv0, clean_environ):
+ err = urllib.error.HTTPError(
+ url="https://api.github.com",
+ code=403,
+ msg="rate limited",
+ hdrs={}, # type: ignore[arg-type]
+ fp=None,
+ )
+ with patch("specify_cli.authentication.http.urllib.request.urlopen", side_effect=err):
+ result = runner.invoke(app, ["self", "upgrade"])
+ assert result.exit_code == 1
+ assert (
+ "Upgrade aborted: rate limited (configure ~/.specify/auth.json with a GitHub token)"
+ in strip_ansi(result.output)
+ )
+
+ def test_http_500_exits_1(self, uv_tool_argv0, clean_environ):
+ err = urllib.error.HTTPError(
+ url="https://api.github.com",
+ code=500,
+ msg="srv err",
+ hdrs={}, # type: ignore[arg-type]
+ fp=None,
+ )
+ with patch("specify_cli.authentication.http.urllib.request.urlopen", side_effect=err):
+ result = runner.invoke(app, ["self", "upgrade"])
+ assert result.exit_code == 1
+ assert "Upgrade aborted: HTTP 500" in strip_ansi(result.output)
+
+ @pytest.mark.parametrize(
+ "code, expected",
+ [
+ # 429 (Too Many Requests / secondary rate limit) gets the same
+ # actionable token hint as 403; other statuses surface verbatim.
+ (
+ 429,
+ "Upgrade aborted: rate limited (configure ~/.specify/auth.json "
+ "with a GitHub token)",
+ ),
+ (404, "Upgrade aborted: HTTP 404"),
+ (502, "Upgrade aborted: HTTP 502"),
+ ],
+ )
+ def test_http_error_categorization(
+ self, code, expected, uv_tool_argv0, clean_environ
+ ):
+ err = urllib.error.HTTPError(
+ url="https://api.github.com",
+ code=code,
+ msg="err",
+ hdrs={}, # type: ignore[arg-type]
+ fp=None,
+ )
+ with patch("specify_cli.authentication.http.urllib.request.urlopen", side_effect=err):
+ result = runner.invoke(app, ["self", "upgrade"])
+ assert result.exit_code == 1
+ assert expected in strip_ansi(result.output)
+
+ def test_unparseable_resolved_release_tag_exits_1_without_traceback(
+ self, uv_tool_argv0, clean_environ
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.subprocess.run"
+ ) as mock_run, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "release-main"})
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 1
+ out = strip_ansi(result.output)
+ assert "resolved release tag is not a comparable version" in out
+ assert "release-main" not in out
+ assert "Traceback" not in out
+ 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
+
+
+class TestUnknownCurrent:
+ """'unknown' current version renders literally in notice and success message."""
+
+ def test_unknown_current_renders_literal_in_notice(
+ self,
+ uv_tool_argv0,
+ clean_environ,
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="unknown"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ mock_run.side_effect = [
+ _completed_process(0),
+ _completed_process(0, stdout="specify 0.7.6\n"),
+ ]
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 0
+ out = strip_ansi(result.output)
+ assert "Upgrading specify-cli unknown β†’ v0.7.6 via uv tool:" in out
+ assert "Upgraded specify-cli: unknown β†’ 0.7.6" in out
+
+ def test_unknown_current_rollback_hint_degrades(
+ self,
+ uv_tool_argv0,
+ clean_environ,
+ ):
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="unknown"
+ ):
+ mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+ mock_run.side_effect = [_completed_process(2)] # installer fails
+ result = runner.invoke(app, ["self", "upgrade"])
+
+ assert result.exit_code == 2
+ out = strip_ansi(result.output)
+ assert "Could not determine the previous version" in out
+ assert "https://github.com/github/spec-kit/releases" in out
+
+
+class TestTokenScrubbing:
+ """GH_TOKEN / GITHUB_TOKEN are stripped from every child env."""
+
+ def test_env_passed_to_subprocess_has_no_github_tokens(
+ self,
+ uv_tool_argv0,
+ monkeypatch,
+ ):
+ monkeypatch.setenv("GH_TOKEN", SENTINEL_GH_TOKEN)
+ monkeypatch.setenv("GITHUB_TOKEN", SENTINEL_GITHUB_TOKEN)
+ response = mock_urlopen_response({"tag_name": "v0.7.6"})
+
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli.authentication.http.urllib.request.build_opener"
+ ) as mock_build_opener, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ mock_urlopen.return_value = response
+ mock_build_opener.return_value.open.return_value = response
+ mock_run.side_effect = [
+ _completed_process(0),
+ _completed_process(0, stdout="specify 0.7.6\n"),
+ ]
+ runner.invoke(app, ["self", "upgrade"])
+
+ assert mock_run.call_count >= 1
+ for call in mock_run.call_args_list:
+ env_kwarg = call.kwargs.get("env") or {}
+ assert "GH_TOKEN" not in env_kwarg, f"env leaked GH_TOKEN: {env_kwarg!r}"
+ assert "GITHUB_TOKEN" not in env_kwarg
+ for v in env_kwarg.values():
+ assert SENTINEL_GH_TOKEN not in v
+ assert SENTINEL_GITHUB_TOKEN not in v
+
+ def test_env_scrubbing_is_case_insensitive(
+ self,
+ uv_tool_argv0,
+ monkeypatch,
+ ):
+ monkeypatch.setenv("gh_token", SENTINEL_GH_TOKEN)
+ monkeypatch.setenv("GitHub_Token", SENTINEL_GITHUB_TOKEN)
+ response = mock_urlopen_response({"tag_name": "v0.7.6"})
+
+ with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+ "specify_cli.authentication.http.urllib.request.build_opener"
+ ) as mock_build_opener, patch(
+ "specify_cli._version.shutil.which", return_value="uv"
+ ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+ "specify_cli._version._get_installed_version", return_value="0.7.5"
+ ):
+ mock_urlopen.return_value = response
+ mock_build_opener.return_value.open.return_value = response
+ mock_run.side_effect = [
+ _completed_process(0),
+ _completed_process(0, stdout="specify 0.7.6\n"),
+ ]
+ runner.invoke(app, ["self", "upgrade"])
+
+ assert mock_run.call_count >= 1
+ for call in mock_run.call_args_list:
+ env_kwarg = call.kwargs.get("env") or {}
+ assert "gh_token" not in env_kwarg
+ assert "GitHub_Token" not in env_kwarg
+ for v in env_kwarg.values():
+ assert SENTINEL_GH_TOKEN not in v
+ assert SENTINEL_GITHUB_TOKEN not in v
+
+ def test_env_scrubbing_removes_github_token_variants(self, monkeypatch):
+ monkeypatch.setenv("GH_PAT", "gh-pat")
+ monkeypatch.setenv("GH_TOKEN_FILE", "gh-token-file")
+ monkeypatch.setenv("GH_ENTERPRISE_TOKEN", "enterprise-gh")
+ monkeypatch.setenv("GH_ENTERPRISE_SECRET", "enterprise-secret")
+ monkeypatch.setenv("GH_ENTERPRISE_PRIVATE_KEY", "enterprise-key")
+ monkeypatch.setenv("GITHUB_PAT", "github-pat")
+ monkeypatch.setenv("GITHUB_TOKEN_PATH", "github-token-path")
+ monkeypatch.setenv("GITHUB_ENTERPRISE_TOKEN", "enterprise-github")
+ monkeypatch.setenv("GITHUB_API_TOKEN", "api-token")
+ monkeypatch.setenv("GITHUB_APP_PRIVATE_KEY", "app-private-key")
+ monkeypatch.setenv("GITHUB_OAUTH_CLIENT_SECRET", "oauth-secret")
+ monkeypatch.setenv("HOMEBREW_GITHUB_API_TOKEN", "homebrew-token")
+ monkeypatch.setenv("NOTGITHUB_TOKEN", "not-github-kept")
+ monkeypatch.setenv("GHOST_API_TOKEN", "ghost-kept")
+ monkeypatch.setenv("GHIDRA_API_KEY", "ghidra-kept")
+ monkeypatch.setenv("UNRELATED_TOKEN", "kept")
+
+ env = specify_cli._version._scrubbed_env()
+
+ assert "GH_PAT" not in env
+ assert "GH_TOKEN_FILE" not in env
+ assert "GH_ENTERPRISE_TOKEN" not in env
+ assert "GH_ENTERPRISE_SECRET" not in env
+ assert "GH_ENTERPRISE_PRIVATE_KEY" not in env
+ assert "GITHUB_PAT" not in env
+ assert "GITHUB_TOKEN_PATH" not in env
+ assert "GITHUB_ENTERPRISE_TOKEN" not in env
+ assert "GITHUB_API_TOKEN" not in env
+ assert "GITHUB_APP_PRIVATE_KEY" not in env
+ assert "GITHUB_OAUTH_CLIENT_SECRET" not in env
+ assert "HOMEBREW_GITHUB_API_TOKEN" not in env
+ assert env["NOTGITHUB_TOKEN"] == "not-github-kept"
+ assert env["GHOST_API_TOKEN"] == "ghost-kept"
+ assert env["GHIDRA_API_KEY"] == "ghidra-kept"
+ assert env["UNRELATED_TOKEN"] == "kept"
+
+ def test_env_scrubbing_strips_noncredential_github_vars_by_design(
+ self, monkeypatch
+ ):
+ # The scrub is intentionally broad: every GH_/GITHUB_-prefixed name is
+ # removed from the installer subprocess env, including non-credential
+ # context vars. This is a deliberate fail-safe so credential-adjacent
+ # names that lack a recognized suffix (e.g. GH_TOKEN_FILE,
+ # GITHUB_TOKEN_PATH, asserted above) can never leak. The installer
+ # (`uv tool install` / `pipx install` of a public package) does not
+ # consume routing/context vars like GITHUB_REPOSITORY, so nothing the
+ # subprocess needs is lost by stripping them.
+ monkeypatch.setenv("GH_HOST", "github.example.com")
+ monkeypatch.setenv("GH_CONFIG_DIR", "/home/u/.config/gh")
+ monkeypatch.setenv("GITHUB_REPOSITORY", "github/spec-kit")
+ monkeypatch.setenv("GITHUB_WORKSPACE", "/home/runner/work")
+ monkeypatch.setenv("GITHUB_USER", "octocat")
+
+ env = specify_cli._version._scrubbed_env()
+
+ assert "GH_HOST" not in env
+ assert "GH_CONFIG_DIR" not in env
+ assert "GITHUB_REPOSITORY" not in env
+ assert "GITHUB_WORKSPACE" not in env
+ assert "GITHUB_USER" not in env
diff --git a/tests/test_upgrade.py b/tests/test_upgrade.py
index 4da392c2c..3ad8c84f6 100644
--- a/tests/test_upgrade.py
+++ b/tests/test_upgrade.py
@@ -1,14 +1,14 @@
"""Tests for the `specify self` sub-app (`self check` and `self upgrade`).
Network isolation contract (SC-004 / FR-014): every test that exercises
-`specify self check` or `_fetch_latest_release_tag()` MUST mock
-`urllib.request.urlopen` so no real outbound call ever reaches
-api.github.com. The `self upgrade` stub tests do not need that patch because
-the stub is contractually network-free. Run this module under `pytest-socket`
-(if installed) with `--disable-socket` as an extra safety net.
+`specify self check` or `_fetch_latest_release_tag()` MUST mock the outbound
+urllib path it expects (`urlopen` for unauthenticated requests, `build_opener`
+for authenticated requests) so no real outbound call ever reaches api.github.com.
+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.
"""
-import json
import urllib.error
import importlib.metadata
from unittest.mock import MagicMock, patch
@@ -24,6 +24,7 @@ from specify_cli._version import (
_normalize_tag,
)
from tests.conftest import strip_ansi
+from tests.http_helpers import mock_urlopen_response
runner = CliRunner()
@@ -35,16 +36,6 @@ _RATE_LIMITED_REASON = (
)
-def _mock_urlopen_response(payload: dict) -> MagicMock:
- body = json.dumps(payload).encode("utf-8")
- resp = MagicMock()
- resp.read.return_value = body
- cm = MagicMock()
- cm.__enter__.return_value = resp
- cm.__exit__.return_value = False
- return cm
-
-
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",
@@ -55,39 +46,6 @@ def _http_error(code: int, message: str = "error") -> urllib.error.HTTPError:
)
-class TestSelfUpgradeStub:
- """Pins the `specify self upgrade` stub output + exit code (contract Β§3.5, FR-016)."""
-
- def test_prints_exactly_three_lines_and_exits_zero(self):
- result = runner.invoke(app, ["self", "upgrade"])
- assert result.exit_code == 0
- lines = strip_ansi(result.output).strip().splitlines()
- assert lines == [
- "specify self upgrade is not implemented yet.",
- "Run 'specify self check' to see whether a newer release is available.",
- "Actual self-upgrade is planned as follow-up work.",
- ]
-
- def test_stub_makes_no_network_call(self):
- # The stub must not hit the network via either urllib path:
- # unauthenticated requests use urlopen() directly; authenticated ones
- # go through build_opener(...).open(). Both are patched so that any
- # accidental network call raises immediately.
- network_error = AssertionError("stub must not hit the network")
- with (
- patch(
- "specify_cli.authentication.http.urllib.request.urlopen",
- side_effect=network_error,
- ),
- patch(
- "specify_cli.authentication.http.urllib.request.build_opener",
- side_effect=network_error,
- ),
- ):
- result = runner.invoke(app, ["self", "upgrade"])
- assert result.exit_code == 0
-
-
class TestIsNewer:
def test_latest_strictly_greater_returns_true(self):
assert _is_newer("0.8.0", "0.7.4") is True
@@ -151,7 +109,7 @@ 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"}),
+ return_value=mock_urlopen_response({"tag_name": "v0.9.0"}),
):
result = runner.invoke(app, ["self", "check"])
output = strip_ansi(result.output)
@@ -164,7 +122,7 @@ class TestUserStory1:
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"}),
+ return_value=mock_urlopen_response({"tag_name": "v0.9.0"}),
):
result = runner.invoke(app, ["self", "check"])
output = strip_ansi(result.output)
@@ -176,7 +134,7 @@ class TestUserStory1:
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"}),
+ return_value=mock_urlopen_response({"tag_name": "v0.7.4"}),
):
result = runner.invoke(app, ["self", "check"])
output = strip_ansi(result.output)
@@ -187,26 +145,46 @@ class TestUserStory1:
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"}),
+ 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_unparseable_tag_routes_to_indeterminate(self):
+ 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"}),
+ 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" 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:
@@ -306,13 +284,25 @@ class TestUserStory2:
def _capture_request_via_urlopen():
captured = {}
- def _side_effect(req, timeout=None):
+ def _side_effect(req, *args, **kwargs):
captured["request"] = req
- return _mock_urlopen_response({"tag_name": "v0.7.4"})
+ return mock_urlopen_response({"tag_name": "v0.7.4"})
return captured, _side_effect
+def _capture_request_via_auth_opener():
+ captured = {}
+
+ def _side_effect(req, *args, **kwargs):
+ captured["request"] = req
+ return mock_urlopen_response({"tag_name": "v0.7.4"})
+
+ opener = MagicMock()
+ opener.open.side_effect = _side_effect
+ return captured, opener
+
+
def _inject_github_config(monkeypatch, token_env="GH_TOKEN"):
from tests.auth_helpers import inject_github_config
inject_github_config(monkeypatch, token_env)
@@ -323,10 +313,11 @@ class TestUserStory3:
monkeypatch.setenv("GH_TOKEN", SENTINEL_GH_TOKEN)
monkeypatch.delenv("GITHUB_TOKEN", raising=False)
_inject_github_config(monkeypatch, token_env="GH_TOKEN")
- captured, side_effect = _capture_request_via_urlopen()
- mock_opener = MagicMock()
- mock_opener.open.side_effect = side_effect
- with patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):
+ captured, opener = _capture_request_via_auth_opener()
+ with patch(
+ "specify_cli.authentication.http.urllib.request.build_opener",
+ return_value=opener,
+ ):
_fetch_latest_release_tag()
req = captured["request"]
assert req.get_header("Authorization") == f"Bearer {SENTINEL_GH_TOKEN}"
@@ -335,10 +326,11 @@ class TestUserStory3:
monkeypatch.delenv("GH_TOKEN", raising=False)
monkeypatch.setenv("GITHUB_TOKEN", SENTINEL_GITHUB_TOKEN)
_inject_github_config(monkeypatch, token_env="GITHUB_TOKEN")
- captured, side_effect = _capture_request_via_urlopen()
- mock_opener = MagicMock()
- mock_opener.open.side_effect = side_effect
- with patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):
+ captured, opener = _capture_request_via_auth_opener()
+ with patch(
+ "specify_cli.authentication.http.urllib.request.build_opener",
+ return_value=opener,
+ ):
_fetch_latest_release_tag()
req = captured["request"]
assert req.get_header("Authorization") == f"Bearer {SENTINEL_GITHUB_TOKEN}"
@@ -376,10 +368,11 @@ class TestUserStory3:
monkeypatch.setenv("GH_TOKEN", " ")
monkeypatch.setenv("GITHUB_TOKEN", SENTINEL_GITHUB_TOKEN)
_inject_github_config(monkeypatch, token_env="GITHUB_TOKEN")
- captured, side_effect = _capture_request_via_urlopen()
- mock_opener = MagicMock()
- mock_opener.open.side_effect = side_effect
- with patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):
+ captured, opener = _capture_request_via_auth_opener()
+ with patch(
+ "specify_cli.authentication.http.urllib.request.build_opener",
+ return_value=opener,
+ ):
_fetch_latest_release_tag()
req = captured["request"]
assert req.get_header("Authorization") == f"Bearer {SENTINEL_GITHUB_TOKEN}"