specify-cli 1.2.3__py3-none-any.whl → 1.2.4__py3-none-any.whl

specify_cli/_install_ignore.py

@@ -17,14 +17,16 @@ def load_install_ignore(
     Match the extension installer's Git-style patterns, including whitespace
     trimming and backslash normalization. Only the named root ignore file is
     read; there are no default exclusions except the ignore filename itself.
-    Invalid encoding or patterns raise the caller's domain validation error
-    before copying.
+    A non-file path, invalid encoding, or invalid patterns raise the caller's
+    domain validation error before copying.
     Excluded directories are pruned by copytree, so child negations cannot
     restore files inside them unless the parent directory is also re-included.
     """
     ignore_file = source_dir / ignore_filename
     if not ignore_file.exists():
         return None
+    if not ignore_file.is_file():
+        raise validation_error(f"{ignore_filename} is not a regular file: {ignore_file}")
 
     # Accept UTF-8 with or without the BOM emitted by Windows PowerShell 5.1.
     # Strip it after decoding so error offsets remain relative to the file.

specify_cli/_version.py

@@ -37,6 +37,7 @@ _RESOLUTION_FAILURE_RATE_LIMITED = (
     "rate limited (configure ~/.specify/auth.json with a GitHub token)"
 )
 _RESOLUTION_FAILURE_HTTP_PREFIX = "HTTP "
+_RESOLUTION_FAILURE_AUTH_PREFIX = "authentication error: "
 _FAILURE_INSTALLER_MISSING = "installer-missing"
 _FAILURE_INSTALLER_INVALID = "installer-invalid"
 _FAILURE_TARGET_TAG_UNPARSEABLE = "target-tag-unparseable"
@@ -108,11 +109,12 @@ def _fetch_latest_release_tag() -> tuple[str | None, str | None]:
     """Return (tag, failure_category). Exactly one outbound call, 5 s timeout.
 
     On success: (tag_name, None).
-    On a documented network/HTTP failure (added in T029/T030): (None, category).
+    On a documented authentication/network/HTTP failure: (None, category).
     On anything else — including a malformed response body — the exception
     propagates; there is no catch-all (research D-006).
     """
     from .authentication.http import open_url
+    from .authentication.github import GitHubCliAuthError
 
     try:
         with open_url(
@@ -131,6 +133,8 @@ def _fetch_latest_release_tag() -> tuple[str | None, str | None]:
             if not isinstance(tag, str) or not tag:
                 raise ValueError("GitHub API response missing valid tag_name")
             return tag, None
+    except GitHubCliAuthError as exc:
+        return None, f"{_RESOLUTION_FAILURE_AUTH_PREFIX}{exc.reason}"
     except urllib.error.HTTPError as e:
         # Order matters: HTTPError is a subclass of URLError.
         # 403 (primary rate limit / abuse detection) and 429 (Too Many Requests /
@@ -1021,7 +1025,10 @@ def _emit_failure(
     """Render user-facing output for resolver, installer, or verification failures."""
     if (
         category in _RESOLUTION_FAILURE_CATEGORIES
-        or category.startswith(_RESOLUTION_FAILURE_HTTP_PREFIX)
+        or category.startswith((
+            _RESOLUTION_FAILURE_HTTP_PREFIX,
+            _RESOLUTION_FAILURE_AUTH_PREFIX,
+        ))
     ):
         console.print(f"Upgrade aborted: {category}", soft_wrap=True)
         return

specify_cli/authentication/github.py

@@ -2,23 +2,144 @@
 
 from __future__ import annotations
 
+import os
+import shutil
+import subprocess
+from typing import TYPE_CHECKING
+from urllib.error import URLError
+
 from .base import AuthProvider
 
+if TYPE_CHECKING:
+    from .config import AuthConfigEntry
 
-class GitHubAuth(AuthProvider):
-    """GitHub authentication provider.
 
-    Supports the ``bearer`` auth scheme, used for PATs, fine-grained PATs,
-    OAuth tokens, and GitHub App installation tokens.
-    """
+_GITHUB_CLI_TIMEOUT_SECONDS = 10
+
+
+def _is_safe_cli_hostname(hostname: str) -> bool:
+    """Return whether *hostname* is a shell-safe DNS hostname."""
+    if not hostname or len(hostname) > 253 or not hostname.isascii():
+        return False
+    labels = hostname.split(".")
+    return all(
+        0 < len(label) <= 63
+        and label[0].isalnum()
+        and label[-1].isalnum()
+        and all(char.isalnum() or char == "-" for char in label)
+        for label in labels
+    )
+
+
+class GitHubCliAuthError(URLError):
+    """Raised when GitHub CLI cannot provide a configured credential."""
+
+
+class GitHubAuth(AuthProvider):
+    """GitHub authentication provider."""
 
     key = "github"
-    supported_auth_schemes = ("bearer",)
+    supported_auth_schemes = ("bearer", "github-cli")
+
+    def __init__(self) -> None:
+        self._github_cli_cache: dict[str, tuple[bool, str]] = {}
 
     def auth_headers(self, token: str, auth_scheme: str) -> dict[str, str]:
-        """Return ``Authorization: Bearer <token>``."""
-        if auth_scheme != "bearer":
+        """Return a bearer authorization header."""
+        if auth_scheme not in self.supported_auth_schemes:
             raise ValueError(
                 f"GitHubAuth does not support auth scheme {auth_scheme!r}"
             )
-        return {"Authorization": f"Bearer {token}"}
+        return {"Authorization": "Bearer " + token}
+
+    def resolve_token(self, entry: AuthConfigEntry) -> str | None:
+        """Resolve a configured token or acquire one from GitHub CLI."""
+        if entry.auth != "github-cli":
+            return super().resolve_token(entry)
+
+        credential_host = self._credential_hostname(entry)
+        cached = self._github_cli_cache.get(credential_host)
+        if cached is not None:
+            succeeded, value = cached
+            if succeeded:
+                return value
+            raise GitHubCliAuthError(value)
+
+        try:
+            token = self._acquire_via_gh_cli(credential_host)
+        except GitHubCliAuthError as exc:
+            message = str(exc.reason)
+            self._github_cli_cache[credential_host] = (False, message)
+            raise GitHubCliAuthError(message) from None
+
+        self._github_cli_cache[credential_host] = (True, token)
+        return token
+
+    @staticmethod
+    def _credential_hostname(entry: AuthConfigEntry) -> str:
+        """Use the first configured host for GitHub CLI credential acquisition."""
+        hostname = entry.hosts[0]
+        if "*" in hostname:
+            raise GitHubCliAuthError(
+                "GitHub authentication failed for provider 'github': "
+                "the first hostname in a github-cli entry must be an exact "
+                "hostname, not a wildcard."
+            )
+        return hostname
+
+    @staticmethod
+    def _acquire_via_gh_cli(hostname: str) -> str:
+        """Run the fixed GitHub CLI token command for *hostname*."""
+        if not _is_safe_cli_hostname(hostname):
+            raise GitHubCliAuthError(
+                "GitHub authentication failed for provider 'github': "
+                "the configured hostname is not valid for GitHub CLI authentication."
+            )
+
+        resolved = shutil.which("gh")
+        if not resolved or not os.path.isabs(resolved):
+            raise GitHubCliAuthError(
+                "GitHub authentication failed for provider 'github': "
+                "GitHub CLI ('gh') was not found."
+            )
+
+        try:
+            result = subprocess.run(  # noqa: S603
+                [resolved, "auth", "token", "--hostname", hostname],
+                capture_output=True,
+                text=True,
+                timeout=_GITHUB_CLI_TIMEOUT_SECONDS,
+                check=False,
+                shell=False,
+            )
+        except subprocess.TimeoutExpired:
+            raise GitHubCliAuthError(
+                "GitHub authentication failed for provider 'github': "
+                f"GitHub CLI timed out while requesting a token for {hostname!r}."
+            ) from None
+        except (OSError, UnicodeDecodeError):
+            raise GitHubCliAuthError(
+                "GitHub authentication failed for provider 'github': "
+                f"GitHub CLI could not provide a token for {hostname!r}."
+            ) from None
+
+        if result.returncode != 0:
+            raise GitHubCliAuthError(
+                "GitHub authentication failed for provider 'github': "
+                f"GitHub CLI could not provide a token for {hostname!r}. "
+                f"Run 'gh auth login --hostname {hostname}'."
+            )
+
+        token = result.stdout.strip()
+        if not token:
+            raise GitHubCliAuthError(
+                "GitHub authentication failed for provider 'github': "
+                f"GitHub CLI returned an empty token for {hostname!r}. "
+                f"Run 'gh auth login --hostname {hostname}'."
+            )
+        if not token.isascii() or "\r" in token or "\n" in token:
+            raise GitHubCliAuthError(
+                "GitHub authentication failed for provider 'github': "
+                f"GitHub CLI returned a malformed token for {hostname!r}."
+            )
+        return token

specify_cli/authentication/http.py

@@ -133,6 +133,8 @@ def build_request(url: str, extra_headers: dict[str, str] | None = None) -> urll
 
     Uses the first matching entry from ``auth.json`` whose token resolves.
     Returns a plain request when no entry matches or the file doesn't exist.
+    A ``github-cli`` acquisition failure raises immediately, without trying
+    later matching entries or returning an unauthenticated request.
     """
     headers: dict[str, str] = {}
     if extra_headers:
@@ -174,9 +176,12 @@ def open_url(
     """Open *url* with config-driven auth, redirect stripping, and fallthrough.
 
     1. Find ``auth.json`` entries whose hosts match the URL.
-    2. For each entry, resolve the token and try the request.
-    3. On 401/403 move to the next matching entry.
-    4. After all entries exhausted (or none matched), try unauthenticated.
+    2. For each entry, resolve the token and try the request. A ``github-cli``
+       acquisition failure raises immediately, with no credential or
+       unauthenticated fallback.
+    3. On HTTP 401/403 after successful acquisition, try the next matching entry.
+    4. After all entries exhausted without an acquisition failure (or none
+       matched), try unauthenticated.
     5. Non-auth errors (404, 500, network) raise immediately.
 
     *extra_headers* (e.g. ``Accept``) are merged into every attempt.

specify_cli/bundles/_commands.py

@@ -46,6 +46,13 @@ def _fail(message: str, *, as_json: bool = False) -> None:
     raise typer.Exit(code=1)
 
 
+def _fail_with_notes(exc: BaseException) -> None:
+    """Exit with the original error first, then any recovery notes."""
+    notes = [str(note) for note in getattr(exc, "__notes__", ())]
+    message = str(exc) if not notes else f"{exc}\n" + "\n".join(notes)
+    _fail(message)
+
+
 def _render_install_warnings(result: InstallResult) -> None:
     for warning in result.warnings:
         err_console.print(f"[yellow]Warning:[/yellow] {_escape_markup(warning.message)}")
@@ -139,7 +146,40 @@ def _resolve_init_integration(override: str | None, manifest) -> str:
     return resolve_default_init_integration()
 
 
-def _bundle_overlaps(project_root: Path, manifest, *, offline: bool) -> list[str]:
+def _expand_manifest(
+    project_root: Path,
+    manifest,
+    *,
+    offline: bool,
+    stack=None,
+    download,
+):
+    """Expand referenced bundles through the effective catalog stack.
+
+    Flat manifests deliberately bypass stack construction: local bundles with
+    no references must retain their existing offline, no-network behavior.
+    ``download`` is supplied by the calling command so its established
+    monkeypatch point also controls referenced-manifest downloads.
+    """
+    from .expansion import ExpandedManifest, expand_manifest
+
+    if not manifest.bundles:
+        return ExpandedManifest.flat(manifest)
+    from .sources import CatalogBundleLoader
+
+    if stack is None:
+        stack = _build_stack(project_root, offline=offline)
+    loader = CatalogBundleLoader(stack, offline=offline, download=download)
+    return expand_manifest(manifest, loader)
+
+
+def _bundle_overlaps(
+    project_root: Path,
+    manifest,
+    *,
+    offline: bool,
+    components=None,
+) -> list[str]:
     """Return informational overlaps between *manifest* and installed bundles."""
     if manifest is None:
         return []
@@ -150,6 +190,7 @@ def _bundle_overlaps(project_root: Path, manifest, *, offline: bool) -> list[str
             manifest,
             active_integration(project_root),
             load_records(project_root),
+            components=components,
         )
         return [*report.overlaps, *report.version_clashes]
     except BundlerError:

specify_cli/bundles/adapters.py

@@ -159,7 +159,7 @@ def make_catalog_fetcher(*, allow_network: bool = True):
             ) from None
         scheme = parsed.scheme.lower()
 
-        if scheme == "builtin":
+        if source.is_builtin:
             repository_url = _BUILTIN_REPOSITORY_URLS.get(url)
             if repository_url is None:
                 raise BundlerError(f"Unknown built-in catalog '{url}'.")
@@ -228,6 +228,7 @@ def _http_get_json(source_id: str, url: str) -> dict:
     HTTPS/host guarantee from ``_validate_remote_url`` is preserved end to end
     rather than only on the initial URL.
     """
+    from ..authentication.github import GitHubCliAuthError
     from ..authentication.http import RedirectPolicyError, open_url
 
     def _validate_redirect(_old_url: str, new_url: str) -> None:
@@ -258,9 +259,9 @@ def _http_get_json(source_id: str, url: str) -> dict:
         raise BundlerError(
             f"Failed to fetch catalog from {url}: {exc}"
         ) from exc
-    except RedirectPolicyError as exc:
-        # Unsafe/malformed redirects are security failures and must surface as
-        # a hard error instead of being downgraded to catalog unavailability.
+    except (GitHubCliAuthError, RedirectPolicyError) as exc:
+        # Authentication and redirect-policy failures are definitive, not
+        # transient catalog unavailability.
         raise BundlerError(
             f"Failed to fetch catalog from {url}: {exc}"
         ) from exc

specify_cli/bundles/catalog_stack.py

@@ -22,6 +22,35 @@ from .catalogs import (
 CatalogFetcher = Callable[[CatalogSource], dict]
 
 
+class BundleNotFoundError(BundlerError):
+    """A bundle ID is absent from every configured catalog."""
+
+    def __init__(self, bundle_id: str) -> None:
+        super().__init__(f"Bundle '{bundle_id}' was not found in any configured catalog.")
+
+
+class ReleaseNotFoundError(BundlerError):
+    """A requested release is absent from the winning catalog entry."""
+
+    def __init__(
+        self,
+        bundle_id: str,
+        version: str,
+        source_id: str,
+        advertised: tuple[str, ...],
+    ) -> None:
+        self.bundle_id = bundle_id
+        self.version = version
+        self.source_id = source_id
+        self.advertised = advertised
+        offered = ", ".join(advertised)
+        super().__init__(
+            f"Bundle '{bundle_id}' has no release {version} in catalog source "
+            f"'{source_id}' (advertised: {offered}). Only the "
+            "highest-precedence source that lists a bundle is consulted."
+        )
+
+
 @dataclass
 class ResolvedBundle:
     entry: CatalogEntry
@@ -80,19 +109,17 @@ class CatalogStack:
             if entry is not None:
                 selected = select_release(entry, version)
                 if selected is None:
-                    advertised = ", ".join(available_versions(entry))
-                    raise BundlerError(
-                        f"Bundle '{bundle_id}' has no release {version} in catalog source "
-                        f"'{source.id}' (advertised: {advertised}). Only the "
-                        "highest-precedence source that lists a bundle is consulted."
+                    raise ReleaseNotFoundError(
+                        bundle_id=bundle_id,
+                        version=version,
+                        source_id=source.id,
+                        advertised=tuple(available_versions(entry)),
                     )
                 return ResolvedBundle(
                     entry=selected.with_provenance(source),
                     source=source,
                 )
-        raise BundlerError(
-            f"Bundle '{bundle_id}' was not found in any configured catalog."
-        )
+        raise BundleNotFoundError(bundle_id)
 
     def search(self, query: str = "") -> list[ResolvedBundle]:
         """Return entries matching *query* (substring over id/name/role/tags/description).

specify_cli/bundles/catalogs.py

@@ -10,7 +10,7 @@ from dataclasses import dataclass, field, replace
 from enum import Enum
 from pathlib import Path
 from typing import Any
-
+from urllib.parse import urlparse
 from . import BundlerError
 from .manifest import _text
 from .yamlio import ensure_within, load_yaml
@@ -67,6 +67,14 @@ class CatalogSource:
     def install_allowed(self) -> bool:
         return self.install_policy is InstallPolicy.INSTALL_ALLOWED
 
+    @property
+    def is_builtin(self) -> bool:
+        """Whether this source is a ``builtin://`` catalog (packaged snapshot offline)."""
+        try:
+            return urlparse(self.url).scheme.lower() == "builtin"
+        except ValueError:
+            return False
+
     @classmethod
     def from_dict(cls, data: Any, scope: Scope) -> "CatalogSource":
         if not isinstance(data, dict):

specify_cli/bundles/command_info.py

@@ -14,13 +14,16 @@ from . import BundlerError
 from ._commands import (
     _build_stack,
     _bundle_overlaps,
+    _expand_manifest,
     _fail,
     _trust_badge,
     _trust_level,
     bundle_app,
 )
+from .conflict import effective_setting
 from .project import find_project_root
 from .sources import _download_manifest
+from .versioning import same_version, strip_version_prefix
 
 
 @bundle_app.command("info")
@@ -77,12 +80,28 @@ def bundle_info(
         # degrading to catalog `provides` counts, so users never mistake an
         # unverifiable bundle for a known/installable one.
         manifest = _download_manifest(resolved, offline=offline)
+        expanded = _expand_manifest(
+            project_root,
+            manifest,
+            offline=offline,
+            stack=stack,
+            download=_download_manifest,
+        )
     except BundlerError as exc:
         _fail(str(exc), as_json=as_json and isinstance(exc.__cause__, ProjectPolicyError))
         return
 
-    overlaps = _bundle_overlaps(project_root, manifest, offline=offline)
-    components = _manifest_component_view(manifest)
+    if expanded.has_references:
+        overlaps = _bundle_overlaps(
+            project_root,
+            manifest,
+            offline=offline,
+            components=expanded.components,
+        )
+    else:
+        # Preserve the flat command's established call shape and rendering.
+        overlaps = _bundle_overlaps(project_root, manifest, offline=offline)
+    components = _manifest_component_view(expanded)
 
     entry = resolved.entry
     if as_json:
@@ -106,6 +125,8 @@ def bundle_info(
             "components": components,
             "overlaps": overlaps,
         }
+        if expanded.has_references:
+            payload["references"] = _reference_view(expanded)
         print(_json.dumps(payload, indent=2))
         return
 
@@ -133,6 +154,11 @@ def bundle_info(
     if manifest and manifest.integration:
         console.print(f"  Integration: {_escape_markup(str(manifest.integration.id))}")
 
+    if expanded.has_references:
+        console.print("\n  [bold]References:[/bold]")
+        for reference in expanded.references:
+            console.print(f"    - {_escape_markup(_format_reference(reference))}")
+
     if components:
         console.print("\n  [bold]Components[/bold] (added on install):")
         for kind in ("extensions", "presets", "steps", "workflows"):
@@ -161,25 +187,82 @@ def bundle_info(
         )
 
 
-def _manifest_component_view(manifest) -> list[dict]:
-    """Flatten a manifest's components to JSON-friendly dicts (id, version, ...)."""
-    if manifest is None:
+def _manifest_component_view(expanded) -> list[dict]:
+    """Flatten an expanded manifest to JSON-friendly component dictionaries."""
+    if expanded is None:
         return []
     view: list[dict] = []
-    for component in manifest.components:
+    for component in expanded.components:
         item = {
             "kind": component.kind,
             "id": component.id,
             "version": component.version,
         }
+        if expanded.has_references and component.source is not None:
+            item["source"] = component.source
         if component.priority is not None:
             item["priority"] = component.priority
         if component.strategy is not None:
             item["strategy"] = component.strategy
+        if expanded.has_references:
+            origin = expanded.origins.get((component.kind, component.id))
+            if origin is not None and origin.origin:
+                item["origin"] = list(origin.origin)
+            if origin is not None and origin.overrides:
+                item["overrides"] = [
+                    _component_provenance(override.component, override.origin)
+                    for override in origin.overrides
+                ]
         view.append(item)
     return view
 
 
+def _component_provenance(component, origin: tuple[str, ...]) -> dict:
+    item = {
+        "version": component.version,
+        "origin": list(origin),
+    }
+    if component.source is not None:
+        item["source"] = component.source
+    if component.priority is not None:
+        item["priority"] = component.priority
+    if component.strategy is not None:
+        item["strategy"] = component.strategy
+    return item
+
+
+def _reference_view(expanded) -> list[dict]:
+    return [
+        {
+            "id": reference.id,
+            "version": reference.version,
+            "source": reference.source_id,
+            "install_policy": (
+                "install-allowed" if reference.install_allowed else "discovery-only"
+            ),
+            "via": list(reference.via),
+            "verified": reference.verified,
+            "trust": _trust_level(reference.verified),
+        }
+        for reference in expanded.references
+    ]
+
+
+def _format_reference(reference) -> str:
+    # The label supplies its own "v", and an accepted pin may already carry one
+    # (``v1.0.1``); strip it here so the text shows one prefix. The JSON view
+    # keeps the recorded spelling.
+    label = f"{reference.id} v{strip_version_prefix(reference.version)}"
+    label += f" ({reference.source_id}"
+    label += f"; {_trust_level(reference.verified)}"
+    if reference.via:
+        label += f"; via {' → '.join(reference.via)}"
+    if not reference.install_allowed:
+        label += "; discovery-only, not installable"
+    label += ")"
+    return label
+
+
 def _format_component(item: dict) -> str:
     label = f"{item['id']} v{item['version']}" if item.get("version") else item["id"]
     extras = []
@@ -187,6 +270,47 @@ def _format_component(item: dict) -> str:
         extras.append(f"priority={item['priority']}")
     if item.get("strategy") is not None:
         extras.append(f"strategy={item['strategy']}")
+    origin = item.get("origin")
+    if origin:
+        extras.append(f"from {' → '.join(origin)}")
+    for override in item.get("overrides", []):
+        extras.append(_format_override(item, override))
     if extras:
         label += f" ({', '.join(extras)})"
     return label
+
+
+def _format_override(item: dict, override: dict) -> str:
+    """Describe the settings replaced by an overriding component."""
+    changed: list[str] = []
+    old_version = override.get("version")
+    current_version = item.get("version")
+    versions_differ = (old_version is None) != (current_version is None)
+    if (
+        versions_differ
+        or (
+            old_version is not None
+            and current_version is not None
+            and not same_version(current_version, old_version)
+        )
+    ):
+        changed.append(str(old_version) if old_version else "unpinned")
+
+    kind = item.get("kind")
+    for field in ("source", "priority", "strategy"):
+        if kind is None:
+            # Provenance without a kind compares raw values.
+            differs = override.get(field) != item.get(field)
+        else:
+            differs = effective_setting(
+                kind, field, override.get(field)
+            ) != effective_setting(kind, field, item.get(field))
+        if differs:
+            value = override.get(field)
+            changed.append(f"{field}={value if value is not None else '<unset>'}")
+
+    origin = " → ".join(override.get("origin", []))
+    if not changed:
+        # Equivalent copies stay in the history; don't invent a difference.
+        return f"also declared by {origin} (same as final)"
+    return f"overrides {', '.join(changed)} from {origin}"