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

specify_cli/_install_ignore.py

@@ -0,0 +1,89 @@
+"""Shared source-directory installation filtering for extensions and presets."""
+
+import re
+from pathlib import Path
+from typing import Callable, List, Optional, Set
+
+import pathspec
+
+
+def load_install_ignore(
+    source_dir: Path,
+    ignore_filename: str,
+    validation_error: type[Exception],
+) -> Optional[Callable[[str, List[str]], Set[str]]]:
+    """Load a UTF-8 ignore file as a copytree callback, or return None if absent.
+
+    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.
+    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.
+    try:
+        raw = ignore_file.read_text(encoding="utf-8").removeprefix("\ufeff")
+    except UnicodeDecodeError as e:
+        raise validation_error(
+            f"{ignore_filename} is not valid UTF-8: {ignore_file} "
+            f"({e.reason} at byte {e.start})"
+        )
+    lines: List[str] = raw.splitlines()
+
+    # Normalise backslashes in patterns so Windows-authored files work
+    normalised: List[str] = []
+    for line in lines:
+        stripped = line.strip()
+        if stripped and not stripped.startswith("#"):
+            normalised.append(stripped.replace("\\", "/"))
+        else:
+            # Preserve blanks/comments so pathspec line numbers stay stable
+            normalised.append(line)
+
+    # Always ignore the ignore file itself, even after a negation pattern.
+    normalised.append(ignore_filename)
+
+    try:
+        spec = pathspec.GitIgnoreSpec.from_lines(normalised)
+    except (ValueError, re.error) as e:
+        # Locate the first malformed source rule only on failure. Valid files
+        # compile once; the appended self-exclusion is not a source line.
+        location = ""
+        for line_number, pattern in enumerate(normalised[:len(lines)], start=1):
+            try:
+                pathspec.GitIgnoreSpec.from_lines([pattern])
+            except (ValueError, re.error):
+                location = f" at line {line_number}: {pattern!r}"
+                break
+        raise validation_error(
+            f"Invalid patterns in {ignore_filename}: {ignore_file}{location} ({e})"
+        ) from e
+
+    def _ignore(directory: str, entries: List[str]) -> Set[str]:
+        ignored: Set[str] = set()
+        rel_dir = Path(directory).relative_to(source_dir)
+        for entry in entries:
+            rel_path = str(rel_dir / entry) if str(rel_dir) != "." else entry
+            # Normalise to forward slashes for consistent matching
+            rel_path_fwd = rel_path.replace("\\", "/")
+
+            entry_full = Path(directory) / entry
+            if entry_full.is_dir():
+                # Append '/' so directory-only patterns (e.g. tests/) match
+                if spec.match_file(rel_path_fwd + "/"):
+                    ignored.add(entry)
+            else:
+                if spec.match_file(rel_path_fwd):
+                    ignored.add(entry)
+        return ignored
+
+    return _ignore

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):