updater-gitplucker 0.1.0__tar.gz

updater_gitplucker-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niccc2007 (https://github.com/uukjtisa)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

updater_gitplucker-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: updater-gitplucker
+Version: 0.1.0
+Summary: Modular, pluggable GitHub updater library for Python-glued projects (release / source / python-source channels with 3-way merge and dependency auto-detection).
+Author: Niccc2007
+License: MIT
+Project-URL: Homepage, https://github.com/uukjtisa/updater-gitplucker
+Project-URL: Repository, https://github.com/uukjtisa/updater-gitplucker
+Project-URL: Issues, https://github.com/uukjtisa/updater-gitplucker/issues
+Keywords: updater,github,auto-update,self-update,merge,dependencies
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: System :: Software Distribution
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# updater-gitplucker
+
+A **modular, pluggable GitHub updater library** for Python-glued projects. Drop
+it into any of your apps to keep them up to date from GitHub — with a safety
+allowlist, a 3-way merge that preserves your local edits, and automatic Python
+dependency detection/installation.
+
+- **Import name:** `gitplucker`  ·  **Package:** `updater-gitplucker`
+- **Zero required dependencies** — the core runs on the Python standard library.
+- **Passive by design** — it hands you an inspectable *plan*; you decide when to
+  apply. Trigger it manually, at startup, or from a background thread.
+
+```python
+from gitplucker import Updater, UpdaterConfig, RepoSubscription, Channel
+from pathlib import Path
+
+config = UpdaterConfig(
+    install_root=Path("/path/to/your/app"),         # where the app lives on disk
+    allowed_repos=["your-org/your-app"],            # nothing outside this is ever fetched
+    subscriptions=[
+        RepoSubscription("your-org/your-app", branches=["main"],
+                         channel=Channel.PYTHON_SOURCE),
+    ],
+    token="ghp_...",                                # optional (private repos / rate limits)
+)
+
+updater = Updater(config)
+for plan in updater.check():                        # dry run — nothing written yet
+    print(plan.summary())
+    if plan.has_update and not plan.conflicts:
+        updater.apply(plan)                         # backup → write → install deps
+    else:
+        updater.discard(plan)
+```
+
+## Install
+
+```bash
+pip install updater-gitplucker
+```
+
+Or the latest from source:
+
+```bash
+pip install "git+https://github.com/uukjtisa/updater-gitplucker.git"
+```
+
+## Concepts
+
+### Allowlist (security boundary)
+`allowed_repos` is enforced at the network layer: any repo not listed is
+rejected **before** any request. Every subscription's repo must be allowlisted.
+
+### Channels — *how* a repo is updated
+| Channel | Source | Best for |
+|---|---|---|
+| `Channel.RELEASE` | Latest GitHub Release + assets (`.zip`, `.whl`, …) | Versioned/shipped builds |
+| `Channel.SOURCE` | Raw source at a branch tip (zipball) | Repos without formal releases |
+| `Channel.PYTHON_SOURCE` | `SOURCE` **+ 3-way merge + dependency auto-detect** | Python apps held together by scripts (the main use case) |
+
+### Apply strategies — *what* an update replaces (`config.apply_strategy`)
+| Strategy | Effect |
+|---|---|
+| `ApplyStrategy.WHOLE_APP` (default) | Add/modify/merge/delete the tracked tree, with backup + rollback |
+| `ApplyStrategy.SELECTIVE` | Only paths matching `selective_globs`; never deletes |
+| `ApplyStrategy.PACKAGE` | `pip install` the downloaded wheel/sdist (RELEASE channel) |
+
+### Triggers — *when* it runs
+- **Manual** — just call `updater.check()` / `updater.apply()` (or `ManualTrigger`).
+- **Startup** — `StartupTrigger(updater).run(on_update=prompt_fn)`.
+- **Background** — `BackgroundTrigger(updater, interval_seconds=3600).start(...)`.
+
+All three are optional wrappers; the library never acts on its own.
+
+### 3-way merge (PYTHON_SOURCE)
+After each apply, gitplucker snapshots the exact files it pulled (the *base*).
+On the next update it merges `base → your local edits` with `base → upstream`.
+Non-overlapping changes merge cleanly; only edits to the **same lines** produce a
+conflict. `config.conflict_policy` decides what happens then: `mark` (git-style
+markers, default), `local`, `remote`, or `abort`.
+
+### Dependency auto-detection (PYTHON_SOURCE)
+Every incoming `.py` is scanned for imports; standard-library and the app's own
+packages are filtered out; anything left that isn't installed is surfaced in
+`plan.dependency_changes` and (if `auto_install_deps=True`) `pip install`-ed on
+apply. Version pins in your `requirements.txt` are honored. Newly-added modules
+are flagged `is_new`.
+
+## Inspecting a plan
+
+```python
+plan.summary()            # one-line human summary
+plan.has_update           # bool
+plan.file_changes         # list[FileChange]  (added/modified/merged/conflict/deleted)
+plan.conflicts            # list[FileChange]  (subset needing attention)
+plan.dependency_changes   # list[DependencyChange]
+plan.new_dependencies     # subset that are newly referenced
+plan.warnings             # e.g. "local changes overwritten (no merge available)"
+plan.release_notes        # release body / source stamp
+```
+
+## Events
+
+```python
+updater.events.on(lambda name, payload: print(name, payload))
+```
+Emitted: `check.start/done`, `download.progress`, `dep.detected/install`,
+`apply.file`, `backup`, `rollback`, `apply.done`. A throwing listener can never
+break an update.
+
+## State & rollback
+Everything lives in `install_root/.gitplucker/` (override via `state_dir`):
+`manifest.json` (installed version + known modules per repo/branch), `base/`
+(merge snapshots), `backups/` (timestamped pre-apply copies for manual
+rollback). A failed apply auto-rolls-back the current batch.
+
+See [`docs/INTEGRATION.md`](docs/INTEGRATION.md) for a step-by-step wiring guide
+and [`examples/basic.py`](examples/basic.py) for a runnable script.

updater_gitplucker-0.1.0/README.md

@@ -0,0 +1,118 @@
+# updater-gitplucker
+
+A **modular, pluggable GitHub updater library** for Python-glued projects. Drop
+it into any of your apps to keep them up to date from GitHub — with a safety
+allowlist, a 3-way merge that preserves your local edits, and automatic Python
+dependency detection/installation.
+
+- **Import name:** `gitplucker`  ·  **Package:** `updater-gitplucker`
+- **Zero required dependencies** — the core runs on the Python standard library.
+- **Passive by design** — it hands you an inspectable *plan*; you decide when to
+  apply. Trigger it manually, at startup, or from a background thread.
+
+```python
+from gitplucker import Updater, UpdaterConfig, RepoSubscription, Channel
+from pathlib import Path
+
+config = UpdaterConfig(
+    install_root=Path("/path/to/your/app"),         # where the app lives on disk
+    allowed_repos=["your-org/your-app"],            # nothing outside this is ever fetched
+    subscriptions=[
+        RepoSubscription("your-org/your-app", branches=["main"],
+                         channel=Channel.PYTHON_SOURCE),
+    ],
+    token="ghp_...",                                # optional (private repos / rate limits)
+)
+
+updater = Updater(config)
+for plan in updater.check():                        # dry run — nothing written yet
+    print(plan.summary())
+    if plan.has_update and not plan.conflicts:
+        updater.apply(plan)                         # backup → write → install deps
+    else:
+        updater.discard(plan)
+```
+
+## Install
+
+```bash
+pip install updater-gitplucker
+```
+
+Or the latest from source:
+
+```bash
+pip install "git+https://github.com/uukjtisa/updater-gitplucker.git"
+```
+
+## Concepts
+
+### Allowlist (security boundary)
+`allowed_repos` is enforced at the network layer: any repo not listed is
+rejected **before** any request. Every subscription's repo must be allowlisted.
+
+### Channels — *how* a repo is updated
+| Channel | Source | Best for |
+|---|---|---|
+| `Channel.RELEASE` | Latest GitHub Release + assets (`.zip`, `.whl`, …) | Versioned/shipped builds |
+| `Channel.SOURCE` | Raw source at a branch tip (zipball) | Repos without formal releases |
+| `Channel.PYTHON_SOURCE` | `SOURCE` **+ 3-way merge + dependency auto-detect** | Python apps held together by scripts (the main use case) |
+
+### Apply strategies — *what* an update replaces (`config.apply_strategy`)
+| Strategy | Effect |
+|---|---|
+| `ApplyStrategy.WHOLE_APP` (default) | Add/modify/merge/delete the tracked tree, with backup + rollback |
+| `ApplyStrategy.SELECTIVE` | Only paths matching `selective_globs`; never deletes |
+| `ApplyStrategy.PACKAGE` | `pip install` the downloaded wheel/sdist (RELEASE channel) |
+
+### Triggers — *when* it runs
+- **Manual** — just call `updater.check()` / `updater.apply()` (or `ManualTrigger`).
+- **Startup** — `StartupTrigger(updater).run(on_update=prompt_fn)`.
+- **Background** — `BackgroundTrigger(updater, interval_seconds=3600).start(...)`.
+
+All three are optional wrappers; the library never acts on its own.
+
+### 3-way merge (PYTHON_SOURCE)
+After each apply, gitplucker snapshots the exact files it pulled (the *base*).
+On the next update it merges `base → your local edits` with `base → upstream`.
+Non-overlapping changes merge cleanly; only edits to the **same lines** produce a
+conflict. `config.conflict_policy` decides what happens then: `mark` (git-style
+markers, default), `local`, `remote`, or `abort`.
+
+### Dependency auto-detection (PYTHON_SOURCE)
+Every incoming `.py` is scanned for imports; standard-library and the app's own
+packages are filtered out; anything left that isn't installed is surfaced in
+`plan.dependency_changes` and (if `auto_install_deps=True`) `pip install`-ed on
+apply. Version pins in your `requirements.txt` are honored. Newly-added modules
+are flagged `is_new`.
+
+## Inspecting a plan
+
+```python
+plan.summary()            # one-line human summary
+plan.has_update           # bool
+plan.file_changes         # list[FileChange]  (added/modified/merged/conflict/deleted)
+plan.conflicts            # list[FileChange]  (subset needing attention)
+plan.dependency_changes   # list[DependencyChange]
+plan.new_dependencies     # subset that are newly referenced
+plan.warnings             # e.g. "local changes overwritten (no merge available)"
+plan.release_notes        # release body / source stamp
+```
+
+## Events
+
+```python
+updater.events.on(lambda name, payload: print(name, payload))
+```
+Emitted: `check.start/done`, `download.progress`, `dep.detected/install`,
+`apply.file`, `backup`, `rollback`, `apply.done`. A throwing listener can never
+break an update.
+
+## State & rollback
+Everything lives in `install_root/.gitplucker/` (override via `state_dir`):
+`manifest.json` (installed version + known modules per repo/branch), `base/`
+(merge snapshots), `backups/` (timestamped pre-apply copies for manual
+rollback). A failed apply auto-rolls-back the current batch.
+
+See [`docs/INTEGRATION.md`](docs/INTEGRATION.md) for a step-by-step wiring guide
+and [`examples/basic.py`](examples/basic.py) for a runnable script.

updater_gitplucker-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "updater-gitplucker"
+version = "0.1.0"
+description = "Modular, pluggable GitHub updater library for Python-glued projects (release / source / python-source channels with 3-way merge and dependency auto-detection)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Niccc2007" }]
+keywords = ["updater", "github", "auto-update", "self-update", "merge", "dependencies"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Version Control :: Git",
+    "Topic :: System :: Software Distribution",
+]
+dependencies = []  # zero required runtime deps: core runs on the stdlib
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/uukjtisa/updater-gitplucker"
+Repository = "https://github.com/uukjtisa/updater-gitplucker"
+Issues = "https://github.com/uukjtisa/updater-gitplucker/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+gitplucker = ["py.typed"]

updater_gitplucker-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

updater_gitplucker-0.1.0/src/gitplucker/__init__.py

@@ -0,0 +1,66 @@
+"""gitplucker — modular, pluggable GitHub updater for Python-glued projects.
+
+Public API (stable):
+
+    from gitplucker import (
+        Updater, UpdaterConfig, RepoSubscription,
+        Channel, ApplyStrategy, ConflictPolicy,
+        ManualTrigger, StartupTrigger, BackgroundTrigger,
+    )
+
+See ``docs/INTEGRATION.md`` for a step-by-step wiring guide (written so an AI
+assistant can drop this into an app unattended).
+"""
+
+from __future__ import annotations
+
+from .config import ApplyStrategy, ConflictPolicy, RepoSubscription, UpdaterConfig
+from .errors import (
+    ApplyError,
+    ConfigError,
+    GitHubAPIError,
+    GitpluckerError,
+    MergeConflictError,
+    RepoNotAllowedError,
+    SourceError,
+)
+from .merge import MergeResult, merge_text
+from .models import (
+    ApplyResult,
+    Channel,
+    ChangeType,
+    DependencyChange,
+    FileChange,
+    UpdatePlan,
+)
+from .triggers import BackgroundTrigger, ManualTrigger, StartupTrigger
+from .updater import Updater
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Updater",
+    "UpdaterConfig",
+    "RepoSubscription",
+    "Channel",
+    "ApplyStrategy",
+    "ConflictPolicy",
+    "ChangeType",
+    "UpdatePlan",
+    "FileChange",
+    "DependencyChange",
+    "ApplyResult",
+    "ManualTrigger",
+    "StartupTrigger",
+    "BackgroundTrigger",
+    "merge_text",
+    "MergeResult",
+    "GitpluckerError",
+    "ConfigError",
+    "RepoNotAllowedError",
+    "SourceError",
+    "GitHubAPIError",
+    "MergeConflictError",
+    "ApplyError",
+    "__version__",
+]

updater_gitplucker-0.1.0/src/gitplucker/backend/__init__.py

@@ -0,0 +1,3 @@
+from .github_api import GitHubClient, ReleaseInfo
+
+__all__ = ["GitHubClient", "ReleaseInfo"]

updater_gitplucker-0.1.0/src/gitplucker/backend/github_api.py

@@ -0,0 +1,133 @@
+"""Zero-dependency GitHub REST client.
+
+Uses only the stdlib (``urllib``) so the core library installs with no third
+party packages. Every method enforces the repository allowlist: a repo that
+was not explicitly permitted can never be contacted.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable
+
+from ..errors import GitHubAPIError, RepoNotAllowedError
+
+ProgressCb = Callable[[int, int], None]
+
+
+@dataclass
+class ReleaseInfo:
+    tag: str
+    name: str
+    body: str
+    prerelease: bool
+    assets: list[dict] = field(default_factory=list)  # each: {name, browser_download_url, url, size}
+    zipball_url: str = ""
+
+
+class GitHubClient:
+    def __init__(
+        self,
+        allowed_repos: set[str] | list[str],
+        token: str | None = None,
+        api_base: str = "https://api.github.com",
+    ) -> None:
+        self._allowed = set(allowed_repos)
+        self._token = token
+        self._api = api_base.rstrip("/")
+
+    # -- allowlist gate ---------------------------------------------------
+    def _guard(self, repo: str) -> None:
+        if repo not in self._allowed:
+            raise RepoNotAllowedError(
+                f"repo {repo!r} is not allowlisted; refusing to contact GitHub."
+            )
+
+    def _headers(self, accept: str = "application/vnd.github+json") -> dict[str, str]:
+        h = {
+            "Accept": accept,
+            "User-Agent": "gitplucker/0.1",
+            "X-GitHub-Api-Version": "2022-11-28",
+        }
+        if self._token:
+            h["Authorization"] = f"Bearer {self._token}"
+        return h
+
+    def _get_json(self, url: str) -> dict | list:
+        req = urllib.request.Request(url, headers=self._headers())
+        try:
+            with urllib.request.urlopen(req) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            raise GitHubAPIError(f"GET {url} failed: {e.reason}", status=e.code) from e
+        except urllib.error.URLError as e:
+            raise GitHubAPIError(f"GET {url} failed: {e.reason}") from e
+
+    # -- API surface ------------------------------------------------------
+    def get_latest_release(self, repo: str, include_prerelease: bool = False) -> ReleaseInfo | None:
+        self._guard(repo)
+        if include_prerelease:
+            data = self._get_json(f"{self._api}/repos/{repo}/releases")
+            if not data:
+                return None
+            rel = data[0]  # releases come newest-first
+        else:
+            try:
+                rel = self._get_json(f"{self._api}/repos/{repo}/releases/latest")
+            except GitHubAPIError as e:
+                if e.status == 404:
+                    return None
+                raise
+        return ReleaseInfo(
+            tag=rel.get("tag_name", ""),
+            name=rel.get("name") or rel.get("tag_name", ""),
+            body=rel.get("body", "") or "",
+            prerelease=bool(rel.get("prerelease")),
+            assets=rel.get("assets", []) or [],
+            zipball_url=rel.get("zipball_url", ""),
+        )
+
+    def get_branch_head(self, repo: str, branch: str) -> tuple[str, str]:
+        """Return ``(sha, iso_date)`` of the branch tip."""
+        self._guard(repo)
+        data = self._get_json(f"{self._api}/repos/{repo}/branches/{branch}")
+        commit = data.get("commit", {})
+        sha = commit.get("sha", "")
+        date = (
+            commit.get("commit", {}).get("committer", {}).get("date", "")
+            or commit.get("commit", {}).get("author", {}).get("date", "")
+        )
+        return sha, date
+
+    def download(self, repo: str, url: str, dest: Path, progress: ProgressCb | None = None) -> Path:
+        """Download a URL (asset or zipball) to ``dest``, enforcing the allowlist."""
+        self._guard(repo)
+        # Asset API URLs need the octet-stream Accept header to get the binary.
+        accept = "application/octet-stream" if "/releases/assets/" in url else "*/*"
+        req = urllib.request.Request(url, headers=self._headers(accept))
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            with urllib.request.urlopen(req) as resp, open(dest, "wb") as fh:
+                total = int(resp.headers.get("Content-Length") or 0)
+                received = 0
+                while True:
+                    chunk = resp.read(65536)
+                    if not chunk:
+                        break
+                    fh.write(chunk)
+                    received += len(chunk)
+                    if progress:
+                        progress(received, total)
+        except urllib.error.HTTPError as e:
+            raise GitHubAPIError(f"download {url} failed: {e.reason}", status=e.code) from e
+        except urllib.error.URLError as e:
+            raise GitHubAPIError(f"download {url} failed: {e.reason}") from e
+        return dest
+
+    def zipball_url(self, repo: str, ref: str) -> str:
+        self._guard(repo)
+        return f"{self._api}/repos/{repo}/zipball/{ref}"

updater_gitplucker-0.1.0/src/gitplucker/config.py

@@ -0,0 +1,105 @@
+"""Configuration objects — the whole behaviour of the updater is data-driven.
+
+A host constructs an :class:`UpdaterConfig`, passes it to
+:class:`~gitplucker.updater.Updater`, and never has to subclass anything.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .errors import ConfigError
+from .models import Channel
+
+
+class ConflictPolicy(str):
+    MARK = "mark"        # write git-style conflict markers, keep going
+    LOCAL = "local"      # keep the local version of a conflicted file
+    REMOTE = "remote"    # take the remote version of a conflicted file
+    ABORT = "abort"      # raise MergeConflictError
+
+
+class ApplyStrategy(str):
+    WHOLE_APP = "whole_app"   # replace the tracked tree, backup + rollback
+    SELECTIVE = "selective"   # only paths matching include_globs
+    PACKAGE = "package"       # pip-install the downloaded wheel/sdist
+
+
+@dataclass
+class RepoSubscription:
+    """One repo the app follows, on one or more branches, via one channel."""
+
+    repo: str                                  # "owner/name"
+    branches: list[str] = field(default_factory=lambda: ["main"])
+    channel: Channel = Channel.PYTHON_SOURCE
+    # RELEASE channel: glob picking which asset to download (falls back to zipball).
+    asset_pattern: str = "*.zip"
+    # Only these paths (relative, glob) are considered part of the app payload.
+    include_globs: list[str] = field(default_factory=lambda: ["**/*"])
+    exclude_globs: list[str] = field(
+        default_factory=lambda: [
+            "**/.git/**", "**/__pycache__/**", "**/*.pyc",
+            "**/.gitplucker/**", "**/.venv/**", "**/node_modules/**",
+        ]
+    )
+    # Subfolder inside the repo that maps to install_root ("" == repo root).
+    source_subdir: str = ""
+
+    def __post_init__(self) -> None:
+        if isinstance(self.channel, str):
+            self.channel = Channel(self.channel)
+        if self.repo.count("/") != 1:
+            raise ConfigError(f"repo must be 'owner/name', got {self.repo!r}")
+
+
+@dataclass
+class UpdaterConfig:
+    """Top-level configuration.
+
+    ``allowed_repos`` is the security allowlist: any subscription (or ad-hoc
+    request) whose repo is not listed here is rejected before any network call.
+    """
+
+    install_root: Path
+    subscriptions: list[RepoSubscription] = field(default_factory=list)
+    allowed_repos: list[str] = field(default_factory=list)
+
+    token: str | None = None                    # GitHub PAT for private repos / rate limits
+    api_base: str = "https://api.github.com"
+
+    apply_strategy: str = ApplyStrategy.WHOLE_APP
+    selective_globs: list[str] = field(default_factory=list)  # used by SELECTIVE
+
+    merge: bool = True                          # 3-way merge on python-source
+    conflict_policy: str = ConflictPolicy.MARK
+    auto_install_deps: bool = True
+    requirements_file: str | None = "requirements.txt"  # relative to install_root
+    backup: bool = True
+
+    # Where gitplucker keeps its state (base snapshots, version manifest, backups).
+    state_dir: Path | None = None
+
+    def __post_init__(self) -> None:
+        self.install_root = Path(self.install_root)
+        if self.state_dir is None:
+            self.state_dir = self.install_root / ".gitplucker"
+        self.state_dir = Path(self.state_dir)
+
+        allowed = set(self.allowed_repos)
+        # A subscription implicitly requires its repo to be allowlisted.
+        for sub in self.subscriptions:
+            if sub.repo not in allowed:
+                raise ConfigError(
+                    f"subscription repo {sub.repo!r} is not in allowed_repos "
+                    f"{sorted(allowed)!r}; add it explicitly to permit updates."
+                )
+
+    def is_allowed(self, repo: str) -> bool:
+        return repo in set(self.allowed_repos)
+
+    def subscription_for(self, repo: str, branch: str | None = None) -> RepoSubscription | None:
+        for sub in self.subscriptions:
+            if sub.repo == repo and (branch is None or branch in sub.branches):
+                return sub
+        return None

updater_gitplucker-0.1.0/src/gitplucker/deps/__init__.py

@@ -0,0 +1,13 @@
+from .python_deps import (
+    scan_imports,
+    resolve_dependencies,
+    install_requirements,
+    PACKAGE_ALIASES,
+)
+
+__all__ = [
+    "scan_imports",
+    "resolve_dependencies",
+    "install_requirements",
+    "PACKAGE_ALIASES",
+]