git-getpkg 0.1.0__py3-none-any.whl

git_getpkg/discovery.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+
+try:  # Python 3.11+
+    import tomllib
+except ModuleNotFoundError:  # Python 3.9-3.10
+    import tomli as tomllib
+from pathlib import Path
+
+from git_getpkg.models import Package
+
+IGNORED_DIRECTORIES = {".git", ".venv", "venv", "node_modules", "vendor", "target", "__pycache__"}
+
+
+def _package(
+    root: Path,
+    manifest: Path,
+    name: str,
+    version: str | None,
+    ecosystem: str,
+    *,
+    installable: bool,
+    warning: str | None = None,
+    signals: tuple[str, ...] = (),
+) -> Package:
+    relative = manifest.parent.relative_to(root)
+    return Package(
+        name,
+        version,
+        ecosystem,
+        manifest.parent,
+        manifest,
+        str(relative) if str(relative) != "." else ".",
+        installable,
+        warning,
+        signals,
+    )
+
+
+def _python_signals(directory: Path, data: dict) -> tuple[str, ...]:
+    signals: list[str] = []
+    build_system = data.get("build-system", {})
+    backend = build_system.get("build-backend")
+    if backend:
+        signals.append(f"Build backend: {backend}")
+    build_requires = build_system.get("requires", [])
+    if build_requires and any("==" not in requirement for requirement in build_requires):
+        signals.append("Build requirements are not exact-pinned")
+    project = data.get("project", {})
+    dependencies = list(project.get("dependencies", []))
+    for group in project.get("optional-dependencies", {}).values():
+        dependencies.extend(group)
+    pinned = sum("==" in dependency for dependency in dependencies if " @ " not in dependency)
+    unpinned = sum("==" not in dependency for dependency in dependencies if " @ " not in dependency)
+    if dependencies:
+        signals.append(f"Dependencies: {pinned} exact-pinned · {unpinned} unpinned")
+    for dependency in dependencies:
+        if " @ " not in dependency:
+            continue
+        source = dependency.split(" @ ", 1)[1].strip().lower()
+        if source.startswith("git+"):
+            signals.append("VCS dependency declared")
+        elif source.startswith(("file:", "./", "../", "/")):
+            signals.append("Local-path dependency declared")
+        else:
+            signals.append("Direct URL dependency declared")
+    for lockfile in ("uv.lock", "poetry.lock", "Pipfile.lock"):
+        if (directory / lockfile).is_file():
+            signals.append(f"Lockfile present: {lockfile}")
+    return tuple(dict.fromkeys(signals))
+
+
+def _python_package(root: Path, manifest: Path) -> Package | None:
+    if manifest.name == "pyproject.toml":
+        data = tomllib.loads(manifest.read_text())
+        project = data.get("project", {})
+        name = project.get("name") or manifest.parent.name
+        version = project.get("version")
+        backend = data.get("build-system", {}).get("build-backend")
+        warning = (
+            f"Uses custom build backend: {backend}"
+            if backend and backend not in {"setuptools.build_meta", "setuptools.build_meta:__legacy__"}
+            else None
+        )
+        return _package(
+            root,
+            manifest,
+            name,
+            version,
+            "Python",
+            installable=True,
+            warning=warning,
+            signals=_python_signals(manifest.parent, data),
+        )
+    text = manifest.read_text(errors="replace")
+    name = re.search(r"name\s*=\s*[\"']([^\"']+)", text)
+    version = re.search(r"version\s*=\s*[\"']([^\"']+)", text)
+    return _package(
+        root,
+        manifest,
+        name.group(1) if name else manifest.parent.name,
+        version.group(1) if version else None,
+        "Python",
+        installable=True,
+        warning="setup.py may execute arbitrary build code",
+    )
+
+
+def discover(root: Path) -> list[Package]:
+    packages: list[Package] = []
+    resolved_root = root.resolve()
+
+    def is_safe_file(path: Path) -> bool:
+        if path.is_symlink() or not path.is_file():
+            return False
+        try:
+            path.resolve().relative_to(resolved_root)
+        except ValueError:
+            return False
+        return True
+
+    manifest_names = {"pyproject.toml", "setup.py", "package.json", "Cargo.toml", "go.mod", "Gemfile", "composer.json"}
+    manifests: list[Path] = []
+    for directory, directories, filenames in os.walk(root, topdown=True, followlinks=False):
+        directories[:] = [name for name in directories if name not in IGNORED_DIRECTORIES]
+        for filename in filenames:
+            if filename in manifest_names:
+                candidate = Path(directory, filename)
+                if is_safe_file(candidate):
+                    manifests.append(candidate)
+    manifests.sort()
+    python_by_directory: dict[Path, Path] = {}
+    priority = {"pyproject.toml": 0, "setup.py": 1}
+    for manifest in manifests:
+        if manifest.name in priority and not any(
+            part in IGNORED_DIRECTORIES for part in manifest.relative_to(root).parts
+        ):
+            existing = python_by_directory.get(manifest.parent)
+            if existing is None or priority[manifest.name] < priority[existing.name]:
+                python_by_directory[manifest.parent] = manifest
+    seen_kinds: set[tuple[Path, str]] = set()
+    for manifest in manifests:
+        if not manifest.is_file() or any(part in IGNORED_DIRECTORIES for part in manifest.relative_to(root).parts):
+            continue
+        if manifest.name in priority and python_by_directory.get(manifest.parent) != manifest:
+            continue
+        package: Package | None = None
+        try:
+            if manifest.name in {"pyproject.toml", "requirements.txt", "setup.py"}:
+                package = _python_package(root, manifest)
+            elif manifest.name == "package.json":
+                data = json.loads(manifest.read_text())
+                scripts = data.get("scripts", {})
+                warning = (
+                    "Defines install lifecycle scripts"
+                    if any(key in scripts for key in ("preinstall", "install", "postinstall"))
+                    else None
+                )
+                package = _package(
+                    root,
+                    manifest,
+                    data.get("name", manifest.parent.name),
+                    data.get("version"),
+                    "Node.js",
+                    installable=False,
+                    warning=warning,
+                )
+            elif manifest.name == "Cargo.toml":
+                data = tomllib.loads(manifest.read_text())
+                item = data.get("package", {})
+                package = _package(
+                    root,
+                    manifest,
+                    item.get("name", manifest.parent.name),
+                    item.get("version"),
+                    "Rust",
+                    installable=False,
+                )
+            elif manifest.name == "go.mod":
+                first = manifest.read_text().splitlines()[0]
+                package = _package(root, manifest, first.removeprefix("module ").strip(), None, "Go", installable=False)
+            elif manifest.name == "Gemfile":
+                package = _package(root, manifest, manifest.parent.name, None, "Ruby", installable=False)
+            elif manifest.name == "composer.json":
+                data = json.loads(manifest.read_text())
+                package = _package(
+                    root,
+                    manifest,
+                    data.get("name", manifest.parent.name),
+                    data.get("version"),
+                    "PHP",
+                    installable=False,
+                )
+        except (OSError, ValueError, tomllib.TOMLDecodeError, json.JSONDecodeError) as error:
+            package = _package(
+                root,
+                manifest,
+                manifest.parent.name,
+                None,
+                "Unknown",
+                installable=False,
+                warning=f"Could not parse manifest: {error}",
+            )
+        if package:
+            key = (manifest.parent, package.ecosystem)
+            if key in seen_kinds:
+                continue
+            packages.append(package)
+            seen_kinds.add(key)
+    return sorted(packages, key=lambda item: (item.name.lower(), item.relative_path))

git_getpkg/github.py

@@ -0,0 +1,127 @@
+"""Optional GitHub context, obtained through the user's existing gh CLI."""
+
+from __future__ import annotations
+
+import json
+import shutil
+from dataclasses import dataclass
+from urllib.parse import urlparse
+
+from git_getpkg.command import run
+from git_getpkg.models import SourceInfo
+
+SUPPORTED_PRIMARY_LANGUAGES = frozenset({"Python", "JavaScript", "TypeScript", "Rust", "Go", "Ruby", "PHP"})
+
+
+class GitHubApiError(RuntimeError):
+    """A failed GitHub CLI API request with enough context for safe recovery."""
+
+    @property
+    def is_not_found(self) -> bool:
+        return "404" in str(self) or "not found" in str(self).lower()
+
+
+@dataclass(frozen=True)
+class Repository:
+    owner: str
+    name: str
+    url: str
+    clone_url: str
+    language: str | None
+    updated_at: str | None
+    private: bool
+    archived: bool
+    fork: bool
+    reported_size_kib: int | None = None
+
+    @property
+    def is_package_candidate(self) -> bool:
+        return self.language in SUPPORTED_PRIMARY_LANGUAGES
+
+
+def _owner_repo(source: SourceInfo) -> tuple[str, str] | None:
+    url = source.repository_url
+    if not url or urlparse(url).hostname != "github.com" or not source.namespace or "/" in source.namespace:
+        return None
+    return source.namespace, source.repository_name
+
+
+def _api(endpoint: str) -> object | None:
+    if not shutil.which("gh"):
+        return None
+    result = run(["gh", "api", endpoint], check=False, timeout=20)
+    if result.returncode:
+        return None
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError:
+        return None
+
+
+def _paged_api(endpoint: str) -> object:
+    if not shutil.which("gh"):
+        raise GitHubApiError(
+            "GitHub owner discovery requires GitHub CLI (`gh`). Install it, run `gh auth login`, then try again."
+        )
+    result = run(["gh", "api", "--paginate", "--slurp", endpoint], check=False, timeout=60)
+    if result.returncode:
+        message = result.stderr.strip() or result.stdout.strip() or "GitHub API request failed"
+        raise GitHubApiError(f"Could not list GitHub repositories: {message}")
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError as error:
+        raise GitHubApiError("GitHub returned an invalid repository listing.") from error
+
+
+def repositories(owner: str) -> list[Repository]:
+    """List an org's repositories, falling back to a user account when needed."""
+    if not owner or "/" in owner:
+        raise ValueError("GitHub owner must be a single organization or user name.")
+    try:
+        payload = _paged_api(f"orgs/{owner}/repos?type=all&per_page=100")
+    except GitHubApiError as organization_error:
+        if not organization_error.is_not_found:
+            raise
+        try:
+            payload = _paged_api(f"users/{owner}/repos?type=owner&per_page=100")
+        except GitHubApiError:
+            raise organization_error
+    pages = payload if isinstance(payload, list) else []
+    rows = [row for page in pages if isinstance(page, list) for row in page if isinstance(row, dict)]
+    return [
+        Repository(
+            owner=owner,
+            name=str(row.get("name", "unknown")),
+            url=str(row.get("html_url", f"https://github.com/{owner}/{row.get('name', '')}")),
+            clone_url=str(row.get("clone_url", f"https://github.com/{owner}/{row.get('name', '')}.git")),
+            language=row.get("language") if isinstance(row.get("language"), str) else None,
+            updated_at=row.get("pushed_at") if isinstance(row.get("pushed_at"), str) else None,
+            private=bool(row.get("private")),
+            archived=bool(row.get("archived")),
+            fork=bool(row.get("fork")),
+            reported_size_kib=row.get("size") if isinstance(row.get("size"), int) and row["size"] >= 0 else None,
+        )
+        for row in rows
+    ]
+
+
+def signals(source: SourceInfo) -> list[str]:
+    target = _owner_repo(source)
+    if not target:
+        return []
+    owner, repository = target
+    repo = _api(f"repos/{owner}/{repository}")
+    if not isinstance(repo, dict):
+        return ["GitHub context unavailable"]
+    values = [f"GitHub: {repo.get('stargazers_count', 0)} stars · {repo.get('forks_count', 0)} forks"]
+    if repo.get("archived"):
+        values.append("GitHub: repository archived")
+    if repo.get("fork"):
+        values.append("GitHub: repository is a fork")
+    contributors = _api(f"repos/{owner}/{repository}/contributors?per_page=100")
+    if isinstance(contributors, list):
+        values.append(f"GitHub: {len(contributors)} visible contributors")
+    organization = _api(f"orgs/{owner}")
+    if isinstance(organization, dict) and organization.get("is_verified"):
+        values.append("GitHub: verified organization")
+    return values

git_getpkg/installer.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import shlex
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from git_getpkg.command import run
+from git_getpkg.models import Package
+
+
+@dataclass(frozen=True)
+class ShimResult:
+    directory: Path
+    created: list[str]
+    conflicts: list[str]
+
+
+@dataclass(frozen=True)
+class PathResult:
+    configured: bool
+    profile: Path | None
+    message: str
+
+
+def environment_path(package: Package, commit: str | None, source_identity: str) -> Path:
+    data_home = Path(os.environ.get("XDG_DATA_HOME", Path.home() / ".local" / "share"))
+    safe_name = re.sub(r"[^A-Za-z0-9_.-]+", "-", package.name).strip("-") or "package"
+    identity = f"{source_identity}\0{commit or 'working-tree'}\0{package.relative_path}"
+    suffix = hashlib.sha256(identity.encode()).hexdigest()[:12]
+    return data_home / "git-getpkg" / "environments" / f"{safe_name}-{suffix}"
+
+
+def bin_directory() -> Path:
+    return Path(os.environ.get("XDG_BIN_HOME", Path.home() / ".local" / "bin"))
+
+
+def ensure_bin_on_path(
+    *, directory: Path | None = None, shell: str | None = None, home: Path | None = None
+) -> PathResult:
+    """Persist a narrowly scoped PATH entry for future interactive shells."""
+    directory = directory or bin_directory()
+    if str(directory) in os.environ.get("PATH", "").split(os.pathsep):
+        return PathResult(False, None, f"{directory} is already on PATH")
+    home = home or Path.home()
+    shell_name = Path(shell or os.environ.get("SHELL", "")).name
+    if shell_name == "zsh":
+        profile = home / ".zshrc"
+        entry = f'export PATH={shlex.quote(str(directory))}:"$PATH"'
+    elif shell_name == "bash":
+        profile = home / (".bash_profile" if (home / ".bash_profile").exists() else ".bashrc")
+        entry = f'export PATH={shlex.quote(str(directory))}:"$PATH"'
+    elif shell_name == "fish":
+        config_home = Path(os.environ.get("XDG_CONFIG_HOME", home / ".config"))
+        profile = config_home / "fish" / "config.fish"
+        entry = f"set -gx PATH {shlex.quote(str(directory))} $PATH"
+    else:
+        return PathResult(False, None, f"Could not identify a supported shell; add {directory} to PATH")
+    start = "# >>> git-getpkg PATH >>>"
+    end = "# <<< git-getpkg PATH <<<"
+    existing = profile.read_text() if profile.exists() else ""
+    if start not in existing:
+        profile.parent.mkdir(parents=True, exist_ok=True)
+        suffix = "" if not existing or existing.endswith("\n") else "\n"
+        profile.write_text(f"{existing}{suffix}{start}\n{entry}\n{end}\n")
+        return PathResult(True, profile, f"Added {directory} to PATH in {profile}")
+    return PathResult(False, profile, f"{directory} is already managed in {profile}")
+
+
+def _console_scripts(package: Package, environment: Path) -> list[str]:
+    python = environment / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
+    query = """
+import json
+import re
+import sys
+from importlib.metadata import distributions
+
+def normalized(value):
+    return re.sub(r"[-_.]+", "-", value).lower()
+
+target = normalized(sys.argv[1])
+for distribution in distributions():
+    name = distribution.metadata.get("Name", "")
+    if normalized(name) == target:
+        print(json.dumps(sorted(entry.name for entry in distribution.entry_points if entry.group == "console_scripts")))
+        break
+else:
+    print("[]")
+"""
+    result = run([str(python), "-c", query, package.name])
+    import json
+
+    return json.loads(result.stdout)
+
+
+def create_command_shims(
+    package: Package,
+    environment: Path,
+    *,
+    directory: Path | None = None,
+    scripts: list[str] | None = None,
+) -> ShimResult:
+    """Expose only this package's console scripts without replacing user-owned commands."""
+    directory = directory or bin_directory()
+    directory.mkdir(parents=True, exist_ok=True)
+    scripts = scripts if scripts is not None else _console_scripts(package, environment)
+    source_directory = environment / ("Scripts" if os.name == "nt" else "bin")
+    created: list[str] = []
+    conflicts: list[str] = []
+    for name in scripts:
+        source = source_directory / (f"{name}.exe" if os.name == "nt" else name)
+        destination = directory / (f"{name}.cmd" if os.name == "nt" else name)
+        if not source.exists():
+            continue
+        if destination.exists() and "Managed by git-getpkg" not in destination.read_text(errors="ignore"):
+            conflicts.append(name)
+            continue
+        if os.name == "nt":
+            destination.write_text(f'@rem Managed by git-getpkg\r\n@"{source}" %*\r\n')
+        else:
+            destination.write_text(f'#!/bin/sh\n# Managed by git-getpkg\nexec {shlex.quote(str(source))} "$@"\n')
+            destination.chmod(0o755)
+        created.append(name)
+    return ShimResult(directory, created, conflicts)
+
+
+def install_python(
+    package: Package, commit: str | None, source_identity: str, *, dry_run: bool
+) -> tuple[Path, list[list[str]]]:
+    target = environment_path(package, commit, source_identity)
+    python = target / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
+    commands = [
+        [sys.executable, "-m", "venv", str(target)],
+        [str(python), "-m", "pip", "install", str(package.directory)],
+    ]
+    if not dry_run:
+        if not python.exists():
+            run(commands[0])
+        run(commands[1])
+    return target, commands
+
+
+def validate_python(environment: Path) -> str | None:
+    """Return a dependency-consistency error after installation, if any."""
+    python = environment / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
+    result = run([str(python), "-m", "pip", "check"], check=False)
+    return None if result.returncode == 0 else (result.stdout.strip() or result.stderr.strip() or "pip check failed")
+
+
+def high_risk_pip_signals() -> list[str]:
+    """Report only dependency-source settings with material supply-chain risk."""
+    signals: list[str] = []
+    if os.environ.get("PIP_EXTRA_INDEX_URL"):
+        signals.append("High risk: PIP_EXTRA_INDEX_URL is active (dependency-confusion exposure)")
+    if os.environ.get("PIP_TRUSTED_HOST"):
+        signals.append("High risk: PIP_TRUSTED_HOST is active")
+    if os.environ.get("PIP_INDEX_URL", "").startswith("http://"):
+        signals.append("High risk: PIP_INDEX_URL uses insecure HTTP")
+    return signals

git_getpkg/models.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class SourceInfo:
+    original: str
+    root: Path
+    is_remote: bool
+    commit: str | None
+    default_branch: str | None
+    repository_url: str | None
+    repository_name: str
+    namespace: str | None
+    namespace_url: str | None
+
+
+@dataclass(frozen=True)
+class Package:
+    name: str
+    version: str | None
+    ecosystem: str
+    directory: Path
+    manifest: Path
+    relative_path: str
+    installable: bool
+    install_warning: str | None = None
+    metadata_signals: tuple[str, ...] = ()
+
+
+@dataclass
+class PackageReport:
+    package: Package
+    last_touched_by: str | None
+    last_touched_at: str | None
+    signals: list[str] = field(default_factory=list)
+
+    def as_dict(self, source: SourceInfo) -> dict:
+        value = asdict(self.package)
+        value["directory"] = str(self.package.directory)
+        value["manifest"] = str(self.package.manifest)
+        value["signals"] = self.signals
+        value["last_touched_by"] = self.last_touched_by
+        value["last_touched_at"] = self.last_touched_at
+        value["source"] = {
+            "url": source.repository_url,
+            "commit": source.commit,
+            "branch": source.default_branch,
+            "repository": source.repository_name,
+            "namespace": source.namespace,
+            "namespace_url": source.namespace_url,
+        }
+        return value

git_getpkg/security.py

@@ -0,0 +1,88 @@
+"""Non-executing security analysis for discovered Python packages."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from git_getpkg.command import CommandError, run
+
+SECURITY_SCAN_EXCLUDES = ".git,.venv,venv,node_modules,tests,test,docs,examples,benchmarks,benchmark"
+
+
+def _bandit(root: Path) -> str:
+    """Return a compact Bandit summary; findings are signals, never a safety verdict."""
+    scan_root = root / "src" if (root / "src").is_dir() else root
+    try:
+        result = run(
+            [
+                sys.executable,
+                "-m",
+                "bandit",
+                "-r",
+                str(scan_root),
+                "-x",
+                SECURITY_SCAN_EXCLUDES,
+                "-f",
+                "json",
+                "--exit-zero",
+                "-q",
+            ],
+            check=False,
+            timeout=30,
+        )
+    except CommandError as error:
+        return f"Live security scan: unavailable ({error})"
+    if result.returncode:
+        detail = result.stderr.strip() or result.stdout.strip() or "Bandit failed"
+        return f"Live security scan: unavailable ({detail.splitlines()[0]})"
+    try:
+        findings = json.loads(result.stdout).get("results", [])
+    except (json.JSONDecodeError, AttributeError):
+        return "Live security scan: unavailable (Bandit returned invalid JSON)"
+    counts = {
+        severity: sum(item.get("issue_severity") == severity for item in findings) for severity in ("HIGH", "MEDIUM")
+    }
+    return f"Live security scan: {counts['HIGH']} high · {counts['MEDIUM']} medium"
+
+
+def scan_python(root: Path) -> str:
+    """Run the built-in non-executing Python security scanner."""
+    return _bandit(root)
+
+
+def findings(root: Path) -> list[tuple[str, str, str, int, str]]:
+    scan_root = root / "src" if (root / "src").is_dir() else root
+    try:
+        result = run(
+            [
+                sys.executable,
+                "-m",
+                "bandit",
+                "-r",
+                str(scan_root),
+                "-x",
+                SECURITY_SCAN_EXCLUDES,
+                "-f",
+                "json",
+                "--exit-zero",
+                "-q",
+            ],
+            check=False,
+            timeout=30,
+        )
+        data = json.loads(result.stdout)
+    except (CommandError, json.JSONDecodeError, OSError):
+        return []
+    return [
+        (
+            item.get("issue_severity", "UNKNOWN"),
+            item.get("test_id", "—"),
+            item.get("filename", "—"),
+            item.get("line_number", 0),
+            item.get("issue_text", ""),
+        )
+        for item in data.get("results", [])
+        if item.get("issue_severity") in {"HIGH", "MEDIUM"}
+    ]