pubgate 0.1.0__py3-none-any.whl

pubgate/__init__.py

@@ -0,0 +1,4 @@
+from .core import PubGate
+from .errors import PubGateError
+
+__all__ = ["PubGate", "PubGateError"]

pubgate/__main__.py

@@ -0,0 +1,97 @@
+import argparse
+import enum
+import logging
+import sys
+from pathlib import Path
+
+from ._log import setup_logging
+from .config import load_config
+from .errors import PubGateError
+
+logger = logging.getLogger(__name__)
+
+
+class Command(enum.Enum):
+    ABSORB = "absorb"
+    STAGE = "stage"
+    PUBLISH = "publish"
+    STATUS = "status"
+
+
+def _add_common_flags(subparser: argparse.ArgumentParser) -> None:
+    subparser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Preview planned actions (fetches remotes but skips branch creation, commits, and pushes)",
+    )
+    subparser.add_argument(
+        "--force", action="store_true", help="Overwrite existing PR branch (use when previous PR was not merged)"
+    )
+    subparser.add_argument(
+        "--no-pr", action="store_true", help="Skip automatic PR creation (show manual steps instead)"
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="pubgate", description="Sync internal repo <-> public repo")
+    parser.add_argument("--repo-dir", default=".", help="Path to the internal repo (default: .)")
+
+    sub = parser.add_subparsers(dest="command")
+    for cmd, help_text in (
+        (Command.ABSORB.value, "Bring public repo changes into internal main via PR"),
+        (Command.STAGE.value, "Generate stage candidate and open internal PR into pubgate/public-approved"),
+        (Command.PUBLISH.value, "Push reviewed pubgate/public-approved content to the public repo and open PR"),
+    ):
+        sp = sub.add_parser(cmd, help=help_text)
+        _add_common_flags(sp)
+
+    sub.add_parser(Command.STATUS.value, help="Show sync status of absorb, stage, and publish")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    setup_logging()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    try:
+        cfg = load_config(args.repo_dir)
+    except PubGateError as exc:
+        logger.error("Configuration error: %s", exc)
+        sys.exit(1)
+
+    cmd = Command(args.command)
+
+    from .core import PubGate
+    from .git import GitRepo
+
+    try:
+        git = GitRepo(Path(args.repo_dir))
+        git.verify_repo()
+        git.ensure_remote(cfg.public_remote, cfg.public_url)
+        pg = PubGate(cfg, git)
+
+        if cmd == Command.STATUS:
+            pg.status()
+        else:
+            flags = dict(dry_run=args.dry_run, force=args.force, no_pr=args.no_pr)
+            match cmd:
+                case Command.ABSORB:
+                    pg.absorb(**flags)
+                case Command.STAGE:
+                    pg.stage(**flags)
+                case Command.PUBLISH:
+                    pg.publish(**flags)
+    except PubGateError as exc:
+        logger.error("Command failed: %s", exc)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

pubgate/_log.py

@@ -0,0 +1,42 @@
+import logging
+import os
+import sys
+
+import colorlog
+
+_ENV_VAR = "PUBGATE_LOG_LEVEL"
+
+
+def setup_logging() -> None:
+    env_level = os.environ.get(_ENV_VAR, "INFO").upper()
+    level = getattr(logging, env_level, None)
+    if level is None:
+        level = logging.INFO
+
+    handler = logging.StreamHandler(sys.stderr)
+    if hasattr(sys.stderr, "isatty") and sys.stderr.isatty():
+        handler.setFormatter(
+            colorlog.ColoredFormatter(
+                "%(log_color)s[%(levelname)-7s]:%(reset)s %(message)s",
+                log_colors={
+                    "DEBUG": "cyan",
+                    "INFO": "green",
+                    "WARNING": "yellow",
+                    "ERROR": "red",
+                    "CRITICAL": "bold_red",
+                },
+            )
+        )
+    else:
+        handler.setFormatter(logging.Formatter("[%(levelname)-7s]: %(message)s"))
+
+    root = logging.getLogger()
+    root.handlers.clear()
+    root.addHandler(handler)
+    root.setLevel(logging.WARNING)
+
+    # App logger gets the user-requested level.
+    logging.getLogger("pubgate").setLevel(level)
+
+    # Route warnings.warn() through logging.
+    logging.captureWarnings(True)

pubgate/absorb.py

@@ -0,0 +1,302 @@
+import logging
+import tempfile
+from pathlib import Path
+
+from .config import Config
+from .errors import GitError, PubGateError
+from .filtering import scrub_internal_blocks
+from .git import GitRepo, is_lfs_pointer
+from .models import format_commit
+from .state import AbsorbStatus, StateRef
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+class AbsorbResult:
+    __slots__ = ("status", "public_head", "last_absorbed")
+
+    def __init__(self, status: AbsorbStatus, public_head: str, last_absorbed: str | None) -> None:
+        self.status = status
+        self.public_head = public_head
+        self.last_absorbed = last_absorbed
+
+
+def check_absorb(cfg: Config, git: GitRepo) -> AbsorbResult:
+    if not git.remote_branch_exists(cfg.public_remote, cfg.public_main_branch):
+        raise PubGateError(
+            f"Error: public repo has no '{cfg.public_main_branch}' branch. "
+            f"The public repo must have at least one commit before running absorb."
+        )
+    public_head = git.rev_parse(cfg.public_main_ref)
+
+    absorb_ref = StateRef.read(git, cfg.internal_main_branch, cfg.absorb_state_file)
+    last_absorbed = absorb_ref.sha if absorb_ref else None
+
+    if last_absorbed is None:
+        logger.debug("Inbound status: NEEDS_BOOTSTRAP")
+        return AbsorbResult(AbsorbStatus.NEEDS_BOOTSTRAP, public_head, None)
+
+    if last_absorbed == public_head:
+        logger.debug("Inbound status: UP_TO_DATE")
+        return AbsorbResult(AbsorbStatus.UP_TO_DATE, public_head, last_absorbed)
+
+    logger.debug("Inbound status: NEEDS_ABSORB")
+    return AbsorbResult(AbsorbStatus.NEEDS_ABSORB, public_head, last_absorbed)
+
+
+def resolve_and_apply(cfg: Config, git: GitRepo, base_sha: str, public_head: str) -> list[str]:
+    public_ref = f"{cfg.public_remote}/{cfg.public_main_branch}"
+    excluded = cfg.state_files
+    staged_sha: str | None = None
+    try:
+        stage_ref = StateRef.read(git, public_ref, cfg.stage_state_file)
+        if stage_ref is not None:
+            staged_sha = stage_ref.sha
+    except PubGateError as exc:
+        logger.warning("Could not read stage state from %s: %s", public_ref, exc)
+    return _apply_absorb_changes(git, base_sha, public_head, public_ref, excluded=excluded, staged_sha=staged_sha)
+
+
+def absorb_commit_message(
+    git: GitRepo,
+    last_absorbed: str,
+    public_head: str,
+    conflicted: list[str] | None = None,
+    needs_review: list[str] | None = None,
+) -> str:
+    subject = f"pubgate: absorb public changes {last_absorbed[:7]}..{public_head[:7]}"
+    commits = git.log_oneline(last_absorbed, public_head)
+    lines = [subject]
+    if commits:
+        lines.append("")
+        lines.append(f"Included commits ({last_absorbed[:7]}..{public_head[:7]}):")
+        lines.extend(f"  {i}. {format_commit(c)}" for i, c in enumerate(commits, 1))
+    if conflicted:
+        lines.append("")
+        lines.append("CONFLICTS (resolve before merging):")
+        for path in conflicted:
+            lines.append(f"  {path}")
+    if needs_review:
+        lines.append("")
+        lines.append("Review manually:")
+        for item in needs_review:
+            lines.append(f"  {item}")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Implementation details (private)
+# ---------------------------------------------------------------------------
+
+
+def _read_text_at_ref(git: GitRepo, ref: str, path: str) -> str | None:
+    data = git.read_file_at_ref_bytes(ref, path)
+    if data is None:
+        return None
+    return data.decode("utf-8")
+
+
+def _log_review_diff(git: GitRepo, public_ref: str, path: str, local_path: Path) -> None:
+    """Log debug info comparing local vs public version of a file needing review."""
+    try:
+        public_bytes = git.read_file_at_ref_bytes(public_ref, path)
+        local_bytes = local_path.read_bytes() if local_path.exists() else None
+        pub_size = len(public_bytes) if public_bytes is not None else 0
+        loc_size = len(local_bytes) if local_bytes is not None else 0
+        same = public_bytes == local_bytes
+        logger.debug("    public: %d bytes, local: %d bytes, identical: %s", pub_size, loc_size, same)
+        if same:
+            return
+        # For text files, show a unified diff
+        if public_bytes is not None and local_bytes is not None:
+            try:
+                pub_text = public_bytes.decode("utf-8")
+                loc_text = local_bytes.decode("utf-8")
+            except UnicodeDecodeError:
+                return
+            import difflib
+
+            diff = difflib.unified_diff(
+                pub_text.splitlines(keepends=True),
+                loc_text.splitlines(keepends=True),
+                fromfile=f"public ({public_ref})",
+                tofile="local (working tree)",
+            )
+            diff_text = "".join(diff)
+            if diff_text:
+                for line in diff_text.splitlines():
+                    logger.debug("    %s", line)
+    except Exception:
+        pass  # best-effort debug logging
+
+
+def _apply_absorb_changes(
+    git: GitRepo,
+    base_sha: str,
+    public_head: str,
+    public_ref: str,
+    *,
+    excluded: frozenset[str] = frozenset(),
+    staged_sha: str | None = None,
+) -> list[str]:
+    changes = git.diff_tree(base_sha, public_head)
+    changes = [c for c in changes if c.path not in excluded and (c.old_path is None or c.old_path not in excluded)]
+    actions: list[str] = []
+
+    for change in changes:
+        logger.debug("Processing change: %s %s", change.status, change.path)
+        if change.is_add:
+            local_path = git.repo_dir / change.path
+            if local_path.exists():
+                kind = git.classify_at_ref(public_ref, change.path)
+                if kind != "text":
+                    label = "LFS file" if kind == "lfs" else "binary"
+                    public_bytes = git.read_file_at_ref_bytes(public_ref, change.path)
+                    local_bytes = local_path.read_bytes()
+                    if public_bytes == local_bytes:
+                        actions.append(f"  {label} (identical): {change.path}")
+                    else:
+                        actions.append(
+                            f"  {label} added on public (kept local version, review manually): {change.path}"
+                        )
+                        _log_review_diff(git, public_ref, change.path, local_path)
+                else:
+                    theirs_content = _read_text_at_ref(git, public_ref, change.path)
+                    if theirs_content is None:
+                        actions.append(f"  added on public (kept local version, review manually): {change.path}")
+                        _log_review_diff(git, public_ref, change.path, local_path)
+                        continue
+                    # Try to find the published base: the scrubbed version of
+                    # the file at the internal commit that was staged.
+                    published_base: str | None = None
+                    if staged_sha is not None:
+                        staged_content = _read_text_at_ref(git, staged_sha, change.path)
+                        if staged_content is not None:
+                            published_base = scrub_internal_blocks(staged_content, path=change.path)
+                    if published_base is not None:
+                        # Three-way merge using the published version as base
+                        with tempfile.TemporaryDirectory() as tmpdir:
+                            base_tmp = Path(tmpdir) / "base"
+                            theirs_tmp = Path(tmpdir) / "theirs"
+                            base_tmp.write_text(published_base, encoding="utf-8", newline="")
+                            theirs_tmp.write_text(theirs_content, encoding="utf-8", newline="")
+                            # Read ours from git objects instead of working copy
+                            # to avoid CRLF mismatch on Windows (see _merge_file).
+                            ours_content = _read_text_at_ref(git, "HEAD", change.path)
+                            if ours_content is not None:
+                                local_path.write_text(ours_content, encoding="utf-8", newline="")
+                            clean = git.merge_file(local_path, base_tmp, theirs_tmp)
+                            git.stage(change.path)
+                            if clean:
+                                actions.append(f"  merge (clean): {change.path}")
+                            else:
+                                actions.append(f"  merge (CONFLICTS - resolve manually): {change.path}")
+                    else:
+                        # No staged version; file wasn't published through pubgate
+                        actions.append(f"  added on public (kept local, review manually): {change.path}")
+                        _log_review_diff(git, public_ref, change.path, local_path)
+            else:
+                is_binary = git.copy_file_from_ref(public_ref, change.path)
+                if is_binary:
+                    with open(git.repo_dir / change.path, "rb") as f:
+                        head = f.read(1024)
+                    tag = " (LFS)" if is_lfs_pointer(head) else " (binary)"
+                else:
+                    tag = ""
+                actions.append(f"  add{tag}: {change.path}")
+
+        elif change.is_modify:
+            _merge_file(git, base_sha, public_ref, change.path, actions, staged_sha=staged_sha)
+
+        elif change.is_delete:
+            if (git.repo_dir / change.path).exists():
+                actions.append(f"  deleted on public (kept locally, review manually): {change.path}")
+                logger.debug("    local file exists at %s", git.repo_dir / change.path)
+
+        elif change.is_rename:
+            old_path = change.old_path or ""
+            git.copy_file_from_ref(public_ref, change.path)
+            msg = f"  rename on public: {old_path} → {change.path} (kept old, review manually)"
+            actions.append(msg)
+
+    return actions
+
+
+def _merge_file(
+    git: GitRepo,
+    base_sha: str,
+    public_ref: str,
+    path: str,
+    actions: list[str],
+    *,
+    staged_sha: str | None = None,
+) -> None:
+    if git.is_binary_at_ref(public_ref, path) or git.is_binary_at_ref(base_sha, path):
+        theirs_bytes = git.read_file_at_ref_bytes(public_ref, path)
+        if theirs_bytes is None:
+            raise GitError(
+                ["show", f"{public_ref}:{path}"],
+                1,
+                f"diff_tree reported M for {path} but binary content is unreadable "
+                f"at {public_ref}. Repository may have corrupt objects.",
+            )
+        git.write_file_and_stage_bytes(path, theirs_bytes)
+        label = "LFS file" if is_lfs_pointer(theirs_bytes) else "binary"
+        actions.append(f"  {label} changed on public (replaced locally, review manually): {path}")
+        _log_review_diff(git, public_ref, path, git.repo_dir / path)
+        return
+
+    # Use the scrubbed staged content as merge base when available.
+    # This mirrors the is_add path: after a publish cycle, the correct base
+    # is the scrubbed version of the internal file that was staged, not the
+    # old public content (which would cause false conflicts on internal blocks).
+    base_content: str | None = None
+    if staged_sha is not None:
+        staged_content = _read_text_at_ref(git, staged_sha, path)
+        if staged_content is not None:
+            base_content = scrub_internal_blocks(staged_content, path=path)
+    if base_content is None:
+        base_content = _read_text_at_ref(git, base_sha, path)
+    theirs_content = _read_text_at_ref(git, public_ref, path)
+
+    if base_content is None or theirs_content is None:
+        missing_ref = base_sha if base_content is None else public_ref
+        raise GitError(
+            ["show", f"{missing_ref}:{path}"],
+            1,
+            f"diff_tree reported M for {path} but content is unreadable "
+            f"at {missing_ref}. Repository may have corrupt objects.",
+        )
+
+    ours_path = git.repo_dir / path
+    if not ours_path.exists():
+        if theirs_content is not None:
+            git.write_file_and_stage(path, theirs_content)
+            actions.append(f"  add (was modified on public, missing locally): {path}")
+        return
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        base_tmp = Path(tmpdir) / "base"
+        theirs_tmp = Path(tmpdir) / "theirs"
+        base_tmp.write_text(base_content, encoding="utf-8", newline="")
+        theirs_tmp.write_text(theirs_content, encoding="utf-8", newline="")
+
+        # Read ours from git objects instead of the working copy.
+        # On Windows, checkout may denormalize LF→CRLF, causing
+        # git merge-file to see spurious differences vs the LF
+        # base/theirs content read from git objects.
+        ours_content = _read_text_at_ref(git, "HEAD", path)
+        if ours_content is not None:
+            ours_path.write_text(ours_content, encoding="utf-8", newline="")
+
+        clean = git.merge_file(ours_path, base_tmp, theirs_tmp)
+        git.stage(path)
+        if clean:
+            actions.append(f"  merge (clean): {path}")
+        else:
+            actions.append(f"  merge (CONFLICTS - resolve manually): {path}")

pubgate/config.py

@@ -0,0 +1,157 @@
+import logging
+import re
+import sys
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib  # type: ignore[import-untyped]
+
+from .errors import PubGateError
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+CONFIG_FILE = "pubgate.toml"
+
+DEFAULT_IGNORE_PATTERNS: list[str] = [
+    ".internal/*",
+    "internal/*",
+    "*-internal.*",
+    "*.internal.*",
+    "*_internal.*",
+    "*-private.*",
+    "*.private.*",
+    "*_private.*",
+    "*.secret",
+    "*.secrets",
+]
+
+# Allowed: alphanumeric, underscore, forward slash, dot, colon, hyphen
+_VALID_BRANCH_RE = re.compile(r"^[a-zA-Z0-9_/.:-]+$")
+
+# ---------------------------------------------------------------------------
+# Field helpers
+# ---------------------------------------------------------------------------
+
+
+def _config_field(kind: str, *, scope: str = "", **kwargs):
+    metadata: dict[str, str] = {"kind": kind}
+    if scope:
+        metadata["scope"] = scope
+    return field(metadata=metadata, **kwargs)
+
+
+def _validate_branch_name(name: str, field_name: str) -> None:
+    if not _VALID_BRANCH_RE.match(name):
+        raise PubGateError(f"'{field_name}' contains invalid characters: '{name}'")
+
+
+# ---------------------------------------------------------------------------
+# Field metadata utilities
+# ---------------------------------------------------------------------------
+
+
+def _fields_by_kind(*kinds: str) -> frozenset[str]:
+    return frozenset(f.name for f in fields(Config) if f.metadata.get("kind") in kinds)
+
+
+def _branch_scope_groups() -> dict[str, frozenset[str]]:
+    groups: dict[str, set[str]] = {}
+    for f in fields(Config):
+        if f.metadata.get("kind") == "branch":
+            groups.setdefault(f.metadata.get("scope", ""), set()).add(f.name)
+    return {k: frozenset(v) for k, v in groups.items()}
+
+
+# ---------------------------------------------------------------------------
+# Config dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Config:
+    # Internal repo
+    internal_main_branch: str = _config_field("branch", scope="internal", default="main")
+    internal_approved_branch: str = _config_field("branch", scope="internal", default="pubgate/public-approved")
+    internal_absorb_branch: str = _config_field("branch", scope="internal", default="pubgate/absorb")
+    internal_stage_branch: str = _config_field("branch", scope="internal", default="pubgate/stage")
+
+    # Public repo
+    public_url: str | None = _config_field("str", default=None)
+    public_remote: str = _config_field("str", default="public-remote")
+    public_main_branch: str = _config_field("branch", scope="public", default="main")
+    public_publish_branch: str = _config_field("branch", scope="public", default="pubgate/publish")
+
+    # State tracking
+    absorb_state_file: str = _config_field("state", default=".pubgate-absorbed")
+    stage_state_file: str = _config_field("state", default=".pubgate-staged")
+
+    # Filtering
+    ignore: list[str] = _config_field("list", default_factory=lambda: list(DEFAULT_IGNORE_PATTERNS))
+
+    def __post_init__(self) -> None:
+        for key in _fields_by_kind("branch"):
+            _validate_branch_name(getattr(self, key), key)
+        for keys in _branch_scope_groups().values():
+            self._check_no_duplicates(keys, "branch name")
+        self._check_no_duplicates(_fields_by_kind("state"), "filename")
+
+    def _check_no_duplicates(self, keys: frozenset[str], label: str) -> None:
+        seen: dict[str, str] = {}
+        for key in sorted(keys):
+            val = getattr(self, key)
+            if val in seen:
+                raise PubGateError(f"'{key}' and '{seen[val]}' share the same {label} '{val}'")
+            seen[val] = key
+
+    @property
+    def public_main_ref(self) -> str:
+        return f"{self.public_remote}/{self.public_main_branch}"
+
+    @property
+    def state_files(self) -> frozenset[str]:
+        return frozenset({self.absorb_state_file, self.stage_state_file})
+
+
+# ---------------------------------------------------------------------------
+# TOML loader
+# ---------------------------------------------------------------------------
+
+
+def load_config(repo_dir: str | Path = ".") -> Config:
+    repo_path = Path(repo_dir)
+    config_path = repo_path / CONFIG_FILE
+
+    if not config_path.is_file():
+        raise PubGateError(
+            f'No {CONFIG_FILE} found at {config_path.resolve()}. Create one with at least: public_url = "..."'
+        )
+
+    with config_path.open("rb") as f:
+        data = tomllib.load(f)
+    logger.debug("Loaded config from %s", config_path)
+
+    str_keys = _fields_by_kind("str", "branch", "state")
+    list_keys = _fields_by_kind("list")
+
+    unknown = set(data) - (str_keys | list_keys)
+    if unknown:
+        raise PubGateError(f"Unknown keys in {CONFIG_FILE}: {', '.join(sorted(unknown))}")
+
+    kwargs: dict[str, object] = {}
+    for key, val in data.items():
+        if key in str_keys:
+            if not isinstance(val, str):
+                raise PubGateError(f"{CONFIG_FILE}: '{key}' must be a string")
+        elif key in list_keys:
+            if not isinstance(val, list) or not all(isinstance(v, str) for v in val):
+                raise PubGateError(f"{CONFIG_FILE}: '{key}' must be a list of strings")
+        kwargs[key] = val
+
+    return Config(**kwargs)  # type: ignore[arg-type]