path-sync 0.7.7__tar.gz → 0.8.0__tar.gz

{path_sync-0.7.7 → path_sync-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: path-sync
-Version: 0.7.7
+Version: 0.8.0
 Summary: Sync files from a source repo to multiple destination repos
 Author-email: EspenAlbert <espen.albert1@gmail.com>
 License-Expression: MIT
@@ -43,6 +43,7 @@ Sync files from a source repo to multiple destination repos.
 - Files with headers are updated on each sync
 - Remove a header to opt-out (file becomes DEST-owned)
 - Orphaned files (removed from SRC) are deleted in DEST
+- Dest improvements can be harvested back to SRC with `pull` (local working tree only; you commit SRC yourself)
 - Idempotent: PR body is left unchanged when already synced from an equal or newer source commit
 - Stale PRs auto-close when source and destination are already in sync (zero file changes)
 
@@ -92,14 +93,81 @@ By default, prompts before each git operation. See [Usage Scenarios](#usage-scen
 | `--pr-reviewers` | Comma-separated PR reviewers |
 | `--pr-assignees` | Comma-separated PR assignees |
 
-### 3. Validate (run in dest repo)
+### 3. Pull changes from a destination
+
+Harvest newer dest content into SRC. Reads one dest working tree and writes into SRC. Does not commit, push, open a PR, or run `copy`. The dest repo must already exist at `dest_path_relative`.
+
+```bash
+path-sync pull -n myconfig -d dest1
+path-sync pull -n myconfig -d dest1 --dest-only
+path-sync pull -n myconfig -d dest1 --dest-only -i '.cursor/*'
+```
+
+Unlike `copy`, `pull` never auto-applies. `--dry-run` and non-TTY list candidates and write nothing.
+
+| | `copy` | `pull` |
+|---|--------|--------|
+| Direction | SRC → DEST | DEST → SRC |
+| `-d` | Comma-separated filter (optional) | Exactly one dest (required) |
+| Non-TTY / no-write flags | `-y` auto-confirms git ops | Never writes (`--dry-run` or non-TTY lists only) |
+| Default | Overwrites dest managed content | Only newer mapped content (git timestamp after content diff) |
+
+| Flag | Description |
+|------|-------------|
+| `-d dest` | Required. Exactly one destination name (not comma-separated). |
+| `--dest-only` | Also harvest dest files with no SRC counterpart (additive on mapped pull). |
+| `--dry-run` | Print candidates; no prompt; no write. Non-TTY behaves the same. |
+| `-i`, `--include` | Allowlist on SRC-relative path ([fnmatch](https://docs.python.org/3/library/fnmatch.html); quote globs in zsh). |
+| `-e`, `--exclude` | Denylist after include (same matcher). |
+
+| Scenario | Command |
+|----------|---------|
+| Interactive harvest | `pull -n cfg -d dest1` |
+| Preview candidates | `pull -n cfg -d dest1 --dry-run` |
+| Scripted / CI list only | `pull -n cfg -d dest1` (non-TTY) |
+
+**Pull behavior**:
+- **Mapped files**: Content compare first; equal content skips git. Pull only when dest git time is newer than SRC. Dirty dest or SRC path: warn and skip.
+- **Sectioned dest files**: Copies managed section bodies only; dest text after `OK_EDIT` stays in dest; `skip_sections` honored.
+- **Whole-file dest**: Copies file with path-sync header stripped; no header added on SRC.
+- **Dest-only**: Whole file to mapped SRC path; does not edit `.src.yaml`.
+- **Path filters**: `-i` / `-e` apply after collect; match SRC-relative path; empty after filter prints `No pull candidates.`
+- **Confirm**: One list, one `y/n`; yes applies all rows.
+
+**Dest-only example** (dir mapping; config unchanged):
+
+```yaml
+# .github/cursor.src.yaml (excerpt)
+paths:
+  - src_path: .cursor/**/*.mdc
+destinations:
+  - name: lz
+    dest_path_relative: ../lz
+```
+
+```bash
+# ../lz/.cursor/rules/bar.mdc exists; SRC has no bar.mdc yet
+path-sync pull -n cursor -d lz --dest-only
+```
+
+Creates `.cursor/rules/bar.mdc` in SRC. To limit a mixed dest-only list:
+
+```bash
+path-sync pull -n cursor -d lz --dest-only -i '.cursor/*'
+```
+
+See also: [pull command reference](docs/pull/index.md).
+
+### 4. Validate (run in dest repo)
 
 ```bash
 uvx path-sync validate-no-changes -b main
 ```
 
+In CI, when the workflow runs on `pull_request`, the comparison branch is the PR base. On `push` or locally, pass `-b` with the branch to compare against (e.g. `-b SDLC` for a branch based on SDLC).
+
 Options:
-- `-b, --branch` - Default branch to compare against (default: main)
+- `-b, --branch` - Branch to compare against (default: main). When `GITHUB_BASE_REF` is set (e.g. in GitHub Actions), it overrides the default so CI can use the PR base without passing `-b`. If you set `GITHUB_BASE_REF`, use a non-empty branch name.
 - `--skip-sections` - Comma-separated `path:section_id` pairs to skip (e.g., `justfile:coverage`)
 
 ## Usage Scenarios
@@ -159,6 +227,8 @@ def hello():
 # === DO_NOT_EDIT: path-sync synced ===
 def hello():
     pass
+
+
 # === OK_EDIT: path-sync synced ===
 ```
 
@@ -376,7 +446,10 @@ jobs:
         with:
           fetch-depth: 0
       - uses: astral-sh/setup-uv@v5
-      - run: uvx path-sync validate-no-changes -b main
+      - name: Validate no changes to synced files
+        env:
+          GITHUB_BASE_REF: ${{ github.base_ref || 'main' }}
+        run: uvx path-sync validate-no-changes
 ```
 
 **Validation skips automatically when:**

{path_sync-0.7.7 → path_sync-0.8.0}/README.md

@@ -25,6 +25,7 @@ Sync files from a source repo to multiple destination repos.
 - Files with headers are updated on each sync
 - Remove a header to opt-out (file becomes DEST-owned)
 - Orphaned files (removed from SRC) are deleted in DEST
+- Dest improvements can be harvested back to SRC with `pull` (local working tree only; you commit SRC yourself)
 - Idempotent: PR body is left unchanged when already synced from an equal or newer source commit
 - Stale PRs auto-close when source and destination are already in sync (zero file changes)
 
@@ -74,14 +75,81 @@ By default, prompts before each git operation. See [Usage Scenarios](#usage-scen
 | `--pr-reviewers` | Comma-separated PR reviewers |
 | `--pr-assignees` | Comma-separated PR assignees |
 
-### 3. Validate (run in dest repo)
+### 3. Pull changes from a destination
+
+Harvest newer dest content into SRC. Reads one dest working tree and writes into SRC. Does not commit, push, open a PR, or run `copy`. The dest repo must already exist at `dest_path_relative`.
+
+```bash
+path-sync pull -n myconfig -d dest1
+path-sync pull -n myconfig -d dest1 --dest-only
+path-sync pull -n myconfig -d dest1 --dest-only -i '.cursor/*'
+```
+
+Unlike `copy`, `pull` never auto-applies. `--dry-run` and non-TTY list candidates and write nothing.
+
+| | `copy` | `pull` |
+|---|--------|--------|
+| Direction | SRC → DEST | DEST → SRC |
+| `-d` | Comma-separated filter (optional) | Exactly one dest (required) |
+| Non-TTY / no-write flags | `-y` auto-confirms git ops | Never writes (`--dry-run` or non-TTY lists only) |
+| Default | Overwrites dest managed content | Only newer mapped content (git timestamp after content diff) |
+
+| Flag | Description |
+|------|-------------|
+| `-d dest` | Required. Exactly one destination name (not comma-separated). |
+| `--dest-only` | Also harvest dest files with no SRC counterpart (additive on mapped pull). |
+| `--dry-run` | Print candidates; no prompt; no write. Non-TTY behaves the same. |
+| `-i`, `--include` | Allowlist on SRC-relative path ([fnmatch](https://docs.python.org/3/library/fnmatch.html); quote globs in zsh). |
+| `-e`, `--exclude` | Denylist after include (same matcher). |
+
+| Scenario | Command |
+|----------|---------|
+| Interactive harvest | `pull -n cfg -d dest1` |
+| Preview candidates | `pull -n cfg -d dest1 --dry-run` |
+| Scripted / CI list only | `pull -n cfg -d dest1` (non-TTY) |
+
+**Pull behavior**:
+- **Mapped files**: Content compare first; equal content skips git. Pull only when dest git time is newer than SRC. Dirty dest or SRC path: warn and skip.
+- **Sectioned dest files**: Copies managed section bodies only; dest text after `OK_EDIT` stays in dest; `skip_sections` honored.
+- **Whole-file dest**: Copies file with path-sync header stripped; no header added on SRC.
+- **Dest-only**: Whole file to mapped SRC path; does not edit `.src.yaml`.
+- **Path filters**: `-i` / `-e` apply after collect; match SRC-relative path; empty after filter prints `No pull candidates.`
+- **Confirm**: One list, one `y/n`; yes applies all rows.
+
+**Dest-only example** (dir mapping; config unchanged):
+
+```yaml
+# .github/cursor.src.yaml (excerpt)
+paths:
+  - src_path: .cursor/**/*.mdc
+destinations:
+  - name: lz
+    dest_path_relative: ../lz
+```
+
+```bash
+# ../lz/.cursor/rules/bar.mdc exists; SRC has no bar.mdc yet
+path-sync pull -n cursor -d lz --dest-only
+```
+
+Creates `.cursor/rules/bar.mdc` in SRC. To limit a mixed dest-only list:
+
+```bash
+path-sync pull -n cursor -d lz --dest-only -i '.cursor/*'
+```
+
+See also: [pull command reference](docs/pull/index.md).
+
+### 4. Validate (run in dest repo)
 
 ```bash
 uvx path-sync validate-no-changes -b main
 ```
 
+In CI, when the workflow runs on `pull_request`, the comparison branch is the PR base. On `push` or locally, pass `-b` with the branch to compare against (e.g. `-b SDLC` for a branch based on SDLC).
+
 Options:
-- `-b, --branch` - Default branch to compare against (default: main)
+- `-b, --branch` - Branch to compare against (default: main). When `GITHUB_BASE_REF` is set (e.g. in GitHub Actions), it overrides the default so CI can use the PR base without passing `-b`. If you set `GITHUB_BASE_REF`, use a non-empty branch name.
 - `--skip-sections` - Comma-separated `path:section_id` pairs to skip (e.g., `justfile:coverage`)
 
 ## Usage Scenarios
@@ -141,6 +209,8 @@ def hello():
 # === DO_NOT_EDIT: path-sync synced ===
 def hello():
     pass
+
+
 # === OK_EDIT: path-sync synced ===
 ```
 
@@ -358,7 +428,10 @@ jobs:
         with:
           fetch-depth: 0
       - uses: astral-sh/setup-uv@v5
-      - run: uvx path-sync validate-no-changes -b main
+      - name: Validate no changes to synced files
+        env:
+          GITHUB_BASE_REF: ${{ github.base_ref || 'main' }}
+        run: uvx path-sync validate-no-changes
 ```
 
 **Validation skips automatically when:**

{path_sync-0.7.7 → path_sync-0.8.0}/path_sync/__init__.py

@@ -2,13 +2,15 @@
 # flake8: noqa
 from path_sync import copy
 from path_sync import dep_update
+from path_sync import pull
 from path_sync import validate_no_changes
 from path_sync import config
 
-VERSION = "0.7.7"
+VERSION = "0.8.0"
 __all__ = [
     "copy",
     "dep_update",
+    "pull",
     "validate_no_changes",
     "config",
 ]

{path_sync-0.7.7 → path_sync-0.8.0}/path_sync/__main__.py

@@ -1,6 +1,6 @@
 import logging
 
-from path_sync._internal import cmd_boot, cmd_copy, cmd_dep_update, cmd_validate  # noqa: F401
+from path_sync._internal import cmd_boot, cmd_copy, cmd_dep_update, cmd_pull, cmd_validate  # noqa: F401
 from path_sync._internal.models import LOG_FORMAT
 from path_sync._internal.typer_app import app
 

{path_sync-0.7.7 → path_sync-0.8.0}/path_sync/_internal/auto_merge.py

@@ -77,7 +77,7 @@ def enable_auto_merge(repo_path: Path, pr_ref: str, config: AutoMergeConfig, des
     cmd = ["gh", "pr", "merge", "--auto", f"--{config.method}", pr_ref]
     if config.delete_branch:
         cmd.append("--delete-branch")
-    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True)
+    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True, check=False)
     if result.returncode != 0:
         logger.warning(f"  {label}: auto-merge enable failed: {result.stderr.strip()}")
     else:
@@ -86,7 +86,7 @@ def enable_auto_merge(repo_path: Path, pr_ref: str, config: AutoMergeConfig, des
 
 def get_pr_checks(repo_path: Path, pr_ref: str) -> list[CheckRun]:
     cmd = ["gh", "pr", "checks", pr_ref, "--json", "name,state,workflow,link"]
-    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True)
+    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True, check=False)
     if result.returncode != 0:
         logger.warning(f"Failed to get checks for {pr_ref}: {result.stderr.strip()}")
         return []
@@ -95,7 +95,7 @@ def get_pr_checks(repo_path: Path, pr_ref: str) -> list[CheckRun]:
 
 def get_pr_state(repo_path: Path, pr_ref: str) -> PRState:
     cmd = ["gh", "pr", "view", pr_ref, "--json", "state", "-q", ".state"]
-    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True)
+    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True, check=False)
     if result.returncode != 0:
         logger.warning(f"Failed to get PR state for {pr_ref}: {result.stderr.strip()}")
         return PRState.OPEN
@@ -104,7 +104,7 @@ def get_pr_state(repo_path: Path, pr_ref: str) -> PRState:
 
 def get_pr_url(repo_path: Path, pr_ref: str) -> str:
     cmd = ["gh", "pr", "view", pr_ref, "--json", "url", "-q", ".url"]
-    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True)
+    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True, check=False)
     if result.returncode != 0:
         logger.warning(f"Failed to get PR URL for {pr_ref}: {result.stderr.strip()}")
         return pr_ref

{path_sync-0.7.7 → path_sync-0.8.0}/path_sync/_internal/cmd_boot.py

@@ -24,8 +24,8 @@ logger = logging.getLogger(__name__)
 @app.command()
 def boot(
     name: str = typer.Option(..., "-n", "--name", help="Config name"),
-    dest_paths: Annotated[list[str], typer.Option("-d", "--dest", help="Destination relative paths")] = [],
-    sync_paths: Annotated[list[str], typer.Option("-p", "--path", help="Paths to sync (glob patterns)")] = [],
+    dest_paths: Annotated[list[str] | None, typer.Option("-d", "--dest", help="Destination relative paths")] = None,
+    sync_paths: Annotated[list[str] | None, typer.Option("-p", "--path", help="Paths to sync (glob patterns)")] = None,
     dry_run: bool = typer.Option(False, "--dry-run", help="Preview without writing"),
     regen: bool = typer.Option(False, "--regen", help="Regenerate config"),
     src_root_opt: str = typer.Option(
@@ -35,6 +35,10 @@ def boot(
     ),
 ) -> None:
     """Initialize or update SRC repo config."""
+    if sync_paths is None:
+        sync_paths = []
+    if dest_paths is None:
+        dest_paths = []
     repo_root = Path(src_root_opt) if src_root_opt else find_repo_root(Path.cwd())
     config_path = resolve_config_path(repo_root, name)
 

path_sync-0.8.0/path_sync/_internal/cmd_pull.py

@@ -0,0 +1,407 @@
+from __future__ import annotations
+
+import fnmatch
+import logging
+import sys
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from enum import StrEnum
+from pathlib import Path
+from typing import NamedTuple
+
+import typer
+from git import Repo
+from pydantic import BaseModel, Field
+
+from path_sync import sections
+from path_sync._internal import git_ops, header, prompt_utils
+from path_sync._internal.cmd_copy import _iter_sync_files
+from path_sync._internal.file_utils import ensure_parents_write_text
+from path_sync._internal.models import (
+    Destination,
+    PathMapping,
+    SrcConfig,
+    SyncMode,
+    find_repo_root,
+    resolve_config_path,
+)
+from path_sync._internal.repo_utils import resolve_repo_path
+from path_sync._internal.typer_app import app
+from path_sync._internal.yaml_utils import load_yaml_model
+
+logger = logging.getLogger(__name__)
+
+_EMPTY_STR_LIST: list[str] = []
+_INCLUDE_OPTION = typer.Option(_EMPTY_STR_LIST, "-i", "--include", help="Keep paths matching pattern")
+_EXCLUDE_OPTION = typer.Option(_EMPTY_STR_LIST, "-e", "--exclude", help="Drop paths matching pattern")
+
+
+class PullKind(StrEnum):
+    SECTIONS = "sections"
+    WHOLE = "whole"
+    BINARY = "binary"
+
+
+class PullOptions(BaseModel):
+    dry_run: bool = False
+    dest_only: bool = False
+    include: list[str] = Field(default_factory=list)
+    exclude: list[str] = Field(default_factory=list)
+
+
+class _DestFileMap(NamedTuple):
+    src_path: Path
+    dest_key: str
+
+
+@dataclass
+class PullCandidate:
+    src_path: Path
+    dest_path: Path
+    dest_key: str
+    kind: PullKind
+    section_ids: list[str]
+    dest_ts: int | None
+    src_ts: int | None
+    skip_sections: list[str]
+    dest_only: bool = False
+
+
+def _validate_dest_name(dest: str) -> str:
+    if not dest.strip():
+        raise ValueError("Missing destination: -d is required")
+    if "," in dest:
+        raise ValueError("Exactly one destination required; comma-separated list not supported")
+    return dest.strip()
+
+
+def _format_unix(ts: int) -> str:
+    return datetime.fromtimestamp(ts, UTC).strftime("%Y-%m-%d")
+
+
+def _managed_section_map(content: str, path: Path, skip: list[str]) -> dict[str, str]:
+    body = header.remove_header(content)
+    extracted = sections.extract_sections(body, path)
+    return {k: v for k, v in extracted.items() if k not in skip}
+
+
+def _diff_section_ids(dest_map: dict[str, str], src_map: dict[str, str]) -> list[str]:
+    ids = set(dest_map) | set(src_map)
+    return sorted(i for i in ids if dest_map.get(i) != src_map.get(i))
+
+
+def _is_opted_out(dest_text: str, sync_mode: SyncMode) -> bool:
+    return sync_mode == SyncMode.SYNC and not header.has_header(dest_text)
+
+
+def _collect_mapped_candidates(
+    config: SrcConfig,
+    dest: Destination,
+    src_root: Path,
+    dest_root: Path,
+    src_repo: Repo,
+    dest_repo: Repo,
+) -> list[PullCandidate]:
+    candidates: list[PullCandidate] = []
+    for mapping in config.resolve_paths(dest):
+        for src_path, dest_key, dest_path in _iter_sync_files(mapping, src_root, dest_root):
+            if dest.is_skipped(dest_key):
+                continue
+            if not dest_path.exists():
+                logger.warning(f"Dest not found: {dest_path}")
+                continue
+            if not src_path.exists():
+                continue
+            if mapping.sync_mode == SyncMode.SCAFFOLD:
+                continue
+
+            skip_list = dest.skip_sections.get(dest_key, [])
+            candidate = _candidate_for_path(
+                src_path,
+                dest_path,
+                dest_key,
+                mapping.sync_mode,
+                skip_list,
+                src_repo,
+                dest_repo,
+            )
+            if candidate:
+                candidates.append(candidate)
+    return candidates
+
+
+def _src_for_dest_file(
+    mapping: PathMapping,
+    dest_path: Path,
+    src_root: Path,
+    dest_root: Path,
+) -> _DestFileMap | None:
+    if "*" in mapping.src_path:
+        glob_prefix = mapping.src_path.split("*")[0].rstrip("/")
+        dest_base = mapping.dest_path or glob_prefix
+        src_base = glob_prefix
+    elif (dest_root / mapping.resolved_dest_path()).is_dir():
+        dest_base = mapping.resolved_dest_path()
+        src_base = mapping.src_path
+    elif dest_path == dest_root / mapping.resolved_dest_path():
+        dest_base = mapping.resolved_dest_path()
+        return _DestFileMap(src_root / mapping.src_path, dest_base)
+    else:
+        return None
+
+    dest_anchor = dest_root / dest_base
+    if dest_path.is_relative_to(dest_anchor):
+        rel = dest_path.relative_to(dest_anchor)
+        return _DestFileMap(src_root / src_base / rel, str(Path(dest_base) / rel))
+    return None
+
+
+def _dest_only_candidate(src_path: Path, dest_path: Path, dest_key: str) -> PullCandidate:
+    try:
+        dest_path.read_text()
+    except UnicodeDecodeError:
+        kind = PullKind.BINARY
+    else:
+        kind = PullKind.WHOLE
+    return PullCandidate(
+        src_path=src_path,
+        dest_path=dest_path,
+        dest_key=dest_key,
+        kind=kind,
+        section_ids=[],
+        dest_ts=None,
+        src_ts=None,
+        skip_sections=[],
+        dest_only=True,
+    )
+
+
+def _collect_dest_only_candidates(
+    config: SrcConfig,
+    dest: Destination,
+    src_root: Path,
+    dest_root: Path,
+    dest_repo: Repo,
+    skip_keys: set[str],
+) -> list[PullCandidate]:
+    candidates: list[PullCandidate] = []
+    seen = set(skip_keys)
+    for mapping in config.resolve_paths(dest):
+        if mapping.sync_mode == SyncMode.SCAFFOLD:
+            continue
+        for dest_path in mapping.expand_dest_paths(dest_root):
+            if dest_path.is_dir() or mapping.is_excluded(dest_path):
+                continue
+            mapped = _src_for_dest_file(mapping, dest_path, src_root, dest_root)
+            if mapped is None:
+                continue
+            if dest.is_skipped(mapped.dest_key) or mapped.src_path.exists() or mapped.dest_key in seen:
+                continue
+            if git_ops.path_is_tracked_dirty(dest_repo, dest_path):
+                logger.warning(f"Skipping dirty dest path: {dest_path}")
+                continue
+            seen.add(mapped.dest_key)
+            candidates.append(_dest_only_candidate(mapped.src_path, dest_path, mapped.dest_key))
+    return candidates
+
+
+def _text_pull_kind(
+    src_path: Path,
+    dest_path: Path,
+    dest_text: str,
+    src_text: str,
+    sync_mode: SyncMode,
+    skip_list: list[str],
+) -> tuple[PullKind, list[str]] | None:
+    if _is_opted_out(dest_text, sync_mode):
+        return None
+
+    dest_body = header.remove_header(dest_text)
+    if header.has_known_comment_prefix(dest_path) and sections.has_sections(dest_body, dest_path):
+        dest_map = _managed_section_map(dest_text, dest_path, skip_list)
+        src_map = _managed_section_map(src_text, src_path, skip_list)
+        if dest_map == src_map:
+            return None
+        return PullKind.SECTIONS, _diff_section_ids(dest_map, src_map)
+
+    if header.remove_header(dest_text) == src_text:
+        return None
+    return PullKind.WHOLE, []
+
+
+def _candidate_for_path(
+    src_path: Path,
+    dest_path: Path,
+    dest_key: str,
+    sync_mode: SyncMode,
+    skip_list: list[str],
+    src_repo: Repo,
+    dest_repo: Repo,
+) -> PullCandidate | None:
+    try:
+        dest_text = dest_path.read_text()
+        src_text = src_path.read_text()
+    except UnicodeDecodeError:
+        if dest_path.read_bytes() == src_path.read_bytes():
+            return None
+        kind, section_ids = PullKind.BINARY, []
+    else:
+        kind_info = _text_pull_kind(src_path, dest_path, dest_text, src_text, sync_mode, skip_list)
+        if kind_info is None:
+            return None
+        kind, section_ids = kind_info
+
+    if git_ops.path_is_dirty(dest_repo, dest_path):
+        logger.warning(f"Skipping dirty dest path: {dest_path}")
+        return None
+    if git_ops.path_is_dirty(src_repo, src_path):
+        logger.warning(f"Skipping dirty src path: {src_path}")
+        return None
+
+    dest_ts = git_ops.file_last_commit_unix(dest_repo, dest_path)
+    src_ts = git_ops.file_last_commit_unix(src_repo, src_path)
+    if dest_ts is None or src_ts is None or dest_ts <= src_ts:
+        return None
+
+    return PullCandidate(
+        src_path=src_path,
+        dest_path=dest_path,
+        dest_key=dest_key,
+        kind=kind,
+        section_ids=section_ids,
+        dest_ts=dest_ts,
+        src_ts=src_ts,
+        skip_sections=skip_list,
+    )
+
+
+def _keep_pull_path(rel: str, include: list[str], exclude: list[str]) -> bool:
+    if include and not any(fnmatch.fnmatch(rel, pat) for pat in include):
+        return False
+    return not (exclude and any(fnmatch.fnmatch(rel, pat) for pat in exclude))
+
+
+def _format_candidate_line(candidate: PullCandidate, src_root: Path) -> str:
+    rel = str(candidate.src_path.relative_to(src_root))
+    if candidate.dest_only:
+        return f"  {rel:<30}  dest-only"
+    if candidate.kind == PullKind.SECTIONS:
+        detail = f"sections: {', '.join(candidate.section_ids)}"
+    elif candidate.kind == PullKind.WHOLE:
+        detail = "whole file"
+    else:
+        detail = "binary"
+    dest_ts = candidate.dest_ts
+    src_ts = candidate.src_ts
+    assert dest_ts is not None and src_ts is not None
+    ts = f"dest {_format_unix(dest_ts)} > src {_format_unix(src_ts)}"
+    return f"  {rel:<30}  {detail:<30}  {ts}"
+
+
+def _print_candidates(dest_name: str, candidates: list[PullCandidate], src_root: Path) -> None:
+    typer.echo(f"\nPull from {dest_name} into src?\n", err=True)
+    for c in candidates:
+        typer.echo(_format_candidate_line(c, src_root), err=True)
+
+
+def _apply_candidate(candidate: PullCandidate) -> None:
+    if candidate.kind == PullKind.BINARY:
+        candidate.src_path.parent.mkdir(parents=True, exist_ok=True)
+        candidate.src_path.write_bytes(candidate.dest_path.read_bytes())
+        logger.info(f"Pulled binary: {candidate.src_path}")
+        return
+
+    if candidate.kind == PullKind.SECTIONS:
+        dest_body = header.remove_header(candidate.dest_path.read_text())
+        dest_sections = sections.parse_sections(dest_body, candidate.dest_path)
+        new_content = sections.replace_sections(
+            candidate.src_path.read_text(),
+            dest_sections,
+            candidate.src_path,
+            skip_sections=candidate.skip_sections,
+            keep_deleted_sections=True,
+        )
+    else:
+        new_content = header.remove_header(candidate.dest_path.read_text())
+
+    ensure_parents_write_text(candidate.src_path, new_content)
+    logger.info(f"Pulled: {candidate.src_path}")
+
+
+def _run_pull(config: SrcConfig, dest: Destination, src_root: Path, opts: PullOptions) -> None:
+    dest_root = resolve_repo_path(dest, src_root, "")
+    if not git_ops.is_git_repo(dest_root):
+        raise ValueError(f"Not a git repository: {dest_root}")
+
+    src_repo = git_ops.get_repo(src_root)
+    dest_repo = git_ops.get_repo(dest_root)
+    candidates = _collect_mapped_candidates(config, dest, src_root, dest_root, src_repo, dest_repo)
+    if opts.dest_only:
+        skip_keys = {c.dest_key for c in candidates}
+        candidates.extend(_collect_dest_only_candidates(config, dest, src_root, dest_root, dest_repo, skip_keys))
+
+    candidates = [
+        c for c in candidates if _keep_pull_path(str(c.src_path.relative_to(src_root)), opts.include, opts.exclude)
+    ]
+
+    if not candidates:
+        typer.echo("No pull candidates.", err=True)
+        return
+
+    _print_candidates(dest.name, candidates, src_root)
+
+    if opts.dry_run or not sys.stdin.isatty():
+        return
+    if prompt_utils.prompt_pull_confirm("Confirm?"):
+        for c in candidates:
+            _apply_candidate(c)
+
+
+@app.command()
+def pull(
+    name: str = typer.Option("", "-n", "--name", help="Config name"),
+    config_path_opt: str = typer.Option("", "-c", "--config-path", help="Full path to config file"),
+    src_root_opt: str = typer.Option("", "--src-root", help="Source repo root"),
+    dest_name: str = typer.Option(..., "-d", "--dest", help="Destination name (exactly one)"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Print candidates without writing (same as non-TTY)"),
+    dest_only: bool = typer.Option(False, "--dest-only", help="Also harvest dest files with no src counterpart"),
+    include: list[str] = _INCLUDE_OPTION,
+    exclude: list[str] = _EXCLUDE_OPTION,
+) -> None:
+    """Harvest newer mapped dest files into src after one confirm.
+
+    --dest-only also copies dest-only files. Quote glob patterns (e.g. -i '.cursor/*').
+    """
+    if name and config_path_opt:
+        logger.error("Cannot use both --name and --config-path")
+        raise typer.Exit(1)
+    if not name and not config_path_opt:
+        logger.error("Either --name or --config-path is required")
+        raise typer.Exit(1)
+
+    try:
+        dest_filter = _validate_dest_name(dest_name)
+    except ValueError as e:
+        logger.error(str(e))
+        raise typer.Exit(1)
+
+    src_root = Path(src_root_opt) if src_root_opt else find_repo_root(Path.cwd())
+    config_path = Path(config_path_opt) if config_path_opt else resolve_config_path(src_root, name)
+    if not config_path.exists():
+        logger.error(f"Config not found: {config_path}")
+        raise typer.Exit(1)
+
+    config = load_yaml_model(config_path, SrcConfig)
+    dest = config.find_destination(dest_filter)
+    opts = PullOptions(
+        dry_run=dry_run,
+        dest_only=dest_only,
+        include=include,
+        exclude=exclude,
+    )
+
+    try:
+        _run_pull(config, dest, src_root, opts)
+    except ValueError as e:
+        logger.error(f"Pull failed: {e}")
+        raise typer.Exit(1)

{path_sync-0.7.7 → path_sync-0.8.0}/path_sync/_internal/cmd_validate.py

@@ -15,7 +15,13 @@ logger = logging.getLogger(__name__)
 
 @app.command("validate-no-changes")
 def validate_no_changes(
-    branch: str = typer.Option("main", "-b", "--branch", help="Default branch to compare against"),
+    branch: str = typer.Option(
+        "main",
+        "-b",
+        "--branch",
+        help="Branch to compare against (default: main; uses GITHUB_BASE_REF when set and -b not passed)",
+        envvar="GITHUB_BASE_REF",
+    ),
     skip_sections_opt: str = typer.Option(
         "",
         "--skip-sections",
@@ -36,9 +42,10 @@ def validate_no_changes(
         logger.info(f"On sync branch {current_branch}, validation skipped")
         return
     if current_branch == branch:
-        logger.info(f"On default branch {branch}, validation skipped")
+        logger.info(f"On base branch {branch}, validation skipped")
         return
 
+    logger.info(f"Validating changes against branch {branch}")
     skip_sections = parse_skip_sections(skip_sections_opt) if skip_sections_opt else None
     unauthorized = validate_no_unauthorized_changes(repo_root, branch, skip_sections)
 

{path_sync-0.7.7 → path_sync-0.8.0}/path_sync/_internal/git_ops.py

@@ -4,6 +4,7 @@ import logging
 import os
 import re
 import subprocess
+from configparser import NoOptionError, NoSectionError
 from contextlib import suppress
 from pathlib import Path
 
@@ -155,7 +156,7 @@ def _ensure_git_user(repo: Repo) -> None:
     """Configure git user if not already set."""
     try:
         repo.config_reader().get_value("user", "name")
-    except Exception:
+    except (NoOptionError, NoSectionError):
         repo.config_writer().set_value("user", "name", "path-sync[bot]").release()
         repo.config_writer().set_value("user", "email", "path-sync[bot]@users.noreply.github.com").release()
 
@@ -191,7 +192,7 @@ def _get_repo_full_name(repo_path: Path) -> str | None:
         "-q",
         '.owner.login + "/" + .name',
     ]
-    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True)
+    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True, check=False)
     if result.returncode != 0:
         logger.warning(f"Failed to get repo info: {result.stderr}")
         return None
@@ -201,7 +202,7 @@ def _get_repo_full_name(repo_path: Path) -> str | None:
 def _get_pr_number(repo_path: Path, branch: str) -> str | None:
     """Get PR number for a branch."""
     cmd = ["gh", "pr", "view", branch, "--json", "number", "-q", ".number"]
-    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True)
+    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True, check=False)
     if result.returncode != 0:
         logger.warning(f"Failed to get PR number: {result.stderr}")
         return None
@@ -228,7 +229,7 @@ def update_pr_body(repo_path: Path, branch: str, body: str) -> bool:
         "-f",
         f"body={body}",
     ]
-    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True)
+    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True, check=False)
     if result.returncode != 0:
         logger.warning(f"Failed to update PR body: {result.stderr}")
         return False
@@ -239,7 +240,7 @@ def update_pr_body(repo_path: Path, branch: str, body: str) -> bool:
 
 def get_pr_body(repo_path: Path, branch: str) -> str | None:
     cmd = ["gh", "pr", "view", branch, "--json", "body,state", "-q", 'select(.state == "OPEN") | .body']
-    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True)
+    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True, check=False)
     if result.returncode != 0:
         return None
     body = result.stdout.strip()
@@ -248,7 +249,7 @@ def get_pr_body(repo_path: Path, branch: str) -> str | None:
 
 def has_open_pr(repo_path: Path, branch: str) -> bool:
     cmd = ["gh", "pr", "view", branch, "--json", "state", "-q", ".state"]
-    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True)
+    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True, check=False)
     if result.returncode != 0:
         return False
     return result.stdout.strip() == "OPEN"
@@ -256,7 +257,7 @@ def has_open_pr(repo_path: Path, branch: str) -> bool:
 
 def close_pr(repo_path: Path, branch: str, comment: str) -> bool:
     cmd = ["gh", "pr", "close", branch, "-c", comment]
-    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True)
+    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True, check=False)
     if result.returncode != 0:
         logger.warning(f"Failed to close PR for {branch}: {result.stderr}")
         return False
@@ -283,7 +284,7 @@ def create_or_update_pr(
     if assignees:
         cmd.extend(["--assignee", ",".join(assignees)])
 
-    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True)
+    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True, check=False)
     if result.returncode != 0:
         if "already exists" in result.stderr:
             logger.info("PR already exists, updating body")
@@ -314,3 +315,27 @@ def get_file_content_at_ref(repo: Repo, file_path: Path, ref: str) -> str | None
     with suppress(GitCommandError):
         return repo.git.show(f"{ref}:{rel_path}")
     return None
+
+
+def path_porcelain_status(repo: Repo, file_path: Path) -> str | None:
+    rel_path = str(file_path.relative_to(repo.working_dir))
+    status = repo.git.status("--porcelain", "--", rel_path).strip()
+    return status or None
+
+
+def path_is_dirty(repo: Repo, file_path: Path) -> bool:
+    return path_porcelain_status(repo, file_path) is not None
+
+
+def path_is_tracked_dirty(repo: Repo, file_path: Path) -> bool:
+    if status := path_porcelain_status(repo, file_path):
+        return status[:2] != "??"
+    return False
+
+
+def file_last_commit_unix(repo: Repo, file_path: Path) -> int | None:
+    rel_path = str(file_path.relative_to(repo.working_dir))
+    with suppress(GitCommandError):
+        ts = repo.git.log("-1", "--format=%ct", "--", rel_path).strip()
+        return int(ts) if ts else None
+    return None

{path_sync-0.7.7 → path_sync-0.8.0}/path_sync/_internal/prompt_utils.py

@@ -23,3 +23,12 @@ def prompt_confirm(message: str, no_prompt: bool = False) -> bool:
         return response == "y"
     except (EOFError, KeyboardInterrupt):
         return False
+
+
+def prompt_pull_confirm(message: str) -> bool:
+    if not sys.stdin.isatty():
+        return False
+    try:
+        return input(f"{message} [y/n]: ").strip().lower() == "y"
+    except (EOFError, KeyboardInterrupt):
+        return False

{path_sync-0.7.7 → path_sync-0.8.0}/path_sync/_internal/verify.py

@@ -39,7 +39,7 @@ def run_command(cmd: str, cwd: Path, dry_run: bool = False) -> None:
         logger.info(f"[DRY RUN] Would run: {cmd} from {cwd}")
         return
     logger.info(f"Running: {cmd}")
-    result = subprocess.run(cmd, shell=True, cwd=cwd, capture_output=True, text=True)
+    result = subprocess.run(cmd, shell=True, cwd=cwd, capture_output=True, text=True, check=False)
     prefix = cmd.split()[0]
     for line in result.stdout.strip().splitlines():
         logger.info(f"[{prefix}] {line}")

path_sync-0.8.0/path_sync/pull.py

@@ -0,0 +1,6 @@
+# Generated by pkg-ext
+from path_sync._internal.cmd_pull import PullOptions as _PullOptions
+from path_sync._internal.cmd_pull import pull as _pull
+
+PullOptions = _PullOptions
+pull = _pull

{path_sync-0.7.7 → path_sync-0.8.0}/pyproject.toml

@@ -2,7 +2,7 @@
 
 [project]
 name = "path-sync"
-version = "0.7.7"
+version = "0.8.0"
 description = "Sync files from a source repo to multiple destination repos"
 requires-python = ">=3.13"
 license = "MIT"
@@ -69,6 +69,13 @@ target-version = "py313"
 # UP047: use type parameters instead of `Generic[T]` subclass
 extend-ignore = ["E501", "UP006", "UP007", "UP035", "UP040", "UP046", "UP047"]
 extend-select = ["Q", "RUF100", "C90", "UP", "I", "T", "FURB"]
+
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = ["typer.Option", "typer.Argument"]
+
+[tool.ruff.format]
+# pytest-examples print prefix is `#>`; ruff 0.16 markdown format turns that into `# >`
+exclude = ["docs/examples/**"]
 # === OK_EDIT: path-sync ruff ===
 
 # === DO_NOT_EDIT: path-sync pytest ===
@@ -95,7 +102,7 @@ exclude = [".venv/", "*test.py"]
 # === DO_NOT_EDIT: path-sync dev-lint ===
 [dependency-groups]
 dev-lint = [
-  "pyright>=1.1",
+  "ty==0.0.76",
   "ruff>=0.14",
   "vulture>=2.14",
 ]
@@ -106,6 +113,7 @@ dev-test = [
   "pytest>=9.0",
   "pytest-asyncio>=0.24",
   "pytest-cov>=7.0",
+  "pytest-examples>=0.0.18",
   "pytest-regressions>=2.6",
 ]
 # === OK_EDIT: path-sync dev-test ===
@@ -123,3 +131,12 @@ docs = [
 # === DO_NOT_EDIT: path-sync release ===
 release = ["pkg-ext"]
 # === OK_EDIT: path-sync release ===
+# === DO_NOT_EDIT: path-sync wheel ===
+[tool.hatch.build.targets.wheel]
+exclude = [
+  "*_examples.py",
+  "*_test.py",
+  "conftest.py",
+  "*_test/",
+]
+# === OK_EDIT: path-sync wheel ===