path-sync 0.7.8__tar.gz → 0.9.0__tar.gz

{path_sync-0.7.8 → path_sync-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: path-sync
-Version: 0.7.8
+Version: 0.9.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,8 @@ 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-only extras under dir or glob mappings survive `copy`; `pull --dest-only` harvests them; `prune` deletes them
+- 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,7 +94,106 @@ 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. Prune dest-only files
+
+Delete dest files whose SRC counterpart is missing. Uses the same collect as `pull --dest-only`, then skips opted-out dest files before listing.
+
+The following dest extras differ:
+
+- **copy orphans:** Dest files that still have a path-sync header for this config and are no longer in this copy run. `_cleanup_orphans` deletes them unless `--skip-orphan-cleanup`.
+- **prune dest-only:** Dest files under a dir, glob, or single-file mapping whose SRC counterpart is missing. No header required (`sync_mode: replace` extras such as `.cursor/`). `path-sync prune` unlinks after confirm.
+- **pull dest-only:** Same collect as prune, then copy dest → SRC. Opted-out dest files (`sync_mode: sync`, header removed) stay on dest for prune; pull `--dest-only` can still harvest them.
+
+```bash
+path-sync prune -n myconfig -d dest1
+path-sync prune -n myconfig -d dest1 --dry-run
+path-sync prune -n myconfig -d dest1 -i '.cursor/*'
+```
+
+Unlike `copy`, `prune` never auto-deletes. `--dry-run` and non-TTY list candidates and write nothing.
+
+- **`-d dest`:** Required. Exactly one destination name (not comma-separated).
+- **`--dry-run`:** Print candidates; no prompt; no delete. Non-TTY behaves the same.
+- **`-i`, `--include`:** Allowlist on dest-relative path ([fnmatch](https://docs.python.org/3/library/fnmatch.html); quote globs in zsh).
+- **`-e`, `--exclude`:** Denylist after include (same matcher).
+
+**Dest-only example** (same cursor config as pull):
+
+```bash
+# ../lz/.cursor/rules/bar.mdc exists; SRC has no bar.mdc yet
+path-sync prune -n cursor -d lz
+```
+
+After `copy`, when prune-eligible dest-only files remain, path-sync prints the count plus the pull and prune commands. Copy does not delete them.
+
+See also: [prune command reference](docs/prune/index.md).
+
+### 5. Validate (run in dest repo)
 
 ```bash
 uvx path-sync validate-no-changes -b main
@@ -161,6 +262,8 @@ def hello():
 # === DO_NOT_EDIT: path-sync synced ===
 def hello():
     pass
+
+
 # === OK_EDIT: path-sync synced ===
 ```
 

{path_sync-0.7.8 → path_sync-0.9.0}/README.md

@@ -25,6 +25,8 @@ 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-only extras under dir or glob mappings survive `copy`; `pull --dest-only` harvests them; `prune` deletes them
+- 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,7 +76,106 @@ 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. Prune dest-only files
+
+Delete dest files whose SRC counterpart is missing. Uses the same collect as `pull --dest-only`, then skips opted-out dest files before listing.
+
+The following dest extras differ:
+
+- **copy orphans:** Dest files that still have a path-sync header for this config and are no longer in this copy run. `_cleanup_orphans` deletes them unless `--skip-orphan-cleanup`.
+- **prune dest-only:** Dest files under a dir, glob, or single-file mapping whose SRC counterpart is missing. No header required (`sync_mode: replace` extras such as `.cursor/`). `path-sync prune` unlinks after confirm.
+- **pull dest-only:** Same collect as prune, then copy dest → SRC. Opted-out dest files (`sync_mode: sync`, header removed) stay on dest for prune; pull `--dest-only` can still harvest them.
+
+```bash
+path-sync prune -n myconfig -d dest1
+path-sync prune -n myconfig -d dest1 --dry-run
+path-sync prune -n myconfig -d dest1 -i '.cursor/*'
+```
+
+Unlike `copy`, `prune` never auto-deletes. `--dry-run` and non-TTY list candidates and write nothing.
+
+- **`-d dest`:** Required. Exactly one destination name (not comma-separated).
+- **`--dry-run`:** Print candidates; no prompt; no delete. Non-TTY behaves the same.
+- **`-i`, `--include`:** Allowlist on dest-relative path ([fnmatch](https://docs.python.org/3/library/fnmatch.html); quote globs in zsh).
+- **`-e`, `--exclude`:** Denylist after include (same matcher).
+
+**Dest-only example** (same cursor config as pull):
+
+```bash
+# ../lz/.cursor/rules/bar.mdc exists; SRC has no bar.mdc yet
+path-sync prune -n cursor -d lz
+```
+
+After `copy`, when prune-eligible dest-only files remain, path-sync prints the count plus the pull and prune commands. Copy does not delete them.
+
+See also: [prune command reference](docs/prune/index.md).
+
+### 5. Validate (run in dest repo)
 
 ```bash
 uvx path-sync validate-no-changes -b main
@@ -143,6 +244,8 @@ def hello():
 # === DO_NOT_EDIT: path-sync synced ===
 def hello():
     pass
+
+
 # === OK_EDIT: path-sync synced ===
 ```
 

{path_sync-0.7.8 → path_sync-0.9.0}/path_sync/__init__.py

@@ -2,13 +2,17 @@
 # flake8: noqa
 from path_sync import copy
 from path_sync import dep_update
+from path_sync import prune
+from path_sync import pull
 from path_sync import validate_no_changes
 from path_sync import config
 
-VERSION = "0.7.8"
+VERSION = "0.9.0"
 __all__ = [
     "copy",
     "dep_update",
+    "prune",
+    "pull",
     "validate_no_changes",
     "config",
 ]

{path_sync-0.7.8 → path_sync-0.9.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_prune, 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.8 → path_sync-0.9.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.8 → path_sync-0.9.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.7.8 → path_sync-0.9.0}/path_sync/_internal/cmd_copy.py

@@ -12,6 +12,7 @@ from pydantic import BaseModel
 from path_sync import sections
 from path_sync._internal import cmd_options, git_ops, header, prompt_utils, verify
 from path_sync._internal.auto_merge import PRRef, handle_auto_merge
+from path_sync._internal.dest_only import collect_dest_only_files, prune_eligible
 from path_sync._internal.file_utils import ensure_parents_write_text
 from path_sync._internal.log_capture import capture_log
 from path_sync._internal.models import (
@@ -273,6 +274,7 @@ def _sync_destination(
         )
     result = _sync_paths(config, dest, src_root, dest_root, opts)
     _print_sync_summary(result)
+    _print_dest_only_hint(config, dest, src_root, dest_root)
 
     if result.total == 0:
         typer.echo("  No changes", err=True)
@@ -316,6 +318,22 @@ def _print_dest_header(dest: Destination) -> None:
     typer.echo(line, err=True)
 
 
+def _print_dest_only_hint(config: SrcConfig, dest: Destination, src_root: Path, dest_root: Path) -> None:
+    if not dest_root.exists() or not git_ops.is_git_repo(dest_root):
+        return
+    dest_repo = git_ops.get_repo(dest_root)
+    files = prune_eligible(collect_dest_only_files(config, dest, src_root, dest_root, dest_repo, set()))
+    if not files:
+        return
+    label = "file" if len(files) == 1 else "files"
+    typer.echo(
+        f"  {len(files)} dest-only {label}. "
+        f"Harvest: path-sync pull -n {config.name} -d {dest.name} --dest-only. "
+        f"Delete: path-sync prune -n {config.name} -d {dest.name}.",
+        err=True,
+    )
+
+
 def _print_sync_summary(result: SyncResult) -> None:
     if result.content_changes > 0:
         typer.echo(f"  [{result.content_changes} files synced]", err=True)

path_sync-0.9.0/path_sync/_internal/cmd_prune.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+
+import typer
+from pydantic import BaseModel, Field
+
+from path_sync._internal import git_ops, prompt_utils
+from path_sync._internal.cmd_pull import _EXCLUDE_OPTION, _INCLUDE_OPTION, _keep_pull_path, _validate_dest_name
+from path_sync._internal.dest_only import collect_dest_only_files, prune_eligible
+from path_sync._internal.models import Destination, SrcConfig, 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__)
+
+
+class PruneOptions(BaseModel):
+    dry_run: bool = False
+    include: list[str] = Field(default_factory=list)
+    exclude: list[str] = Field(default_factory=list)
+
+
+def _run_prune(config: SrcConfig, dest: Destination, src_root: Path, opts: PruneOptions) -> 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}")
+
+    dest_repo = git_ops.get_repo(dest_root)
+    files = prune_eligible(collect_dest_only_files(config, dest, src_root, dest_root, dest_repo, set()))
+    files = [
+        row for row in files if _keep_pull_path(str(row.dest_path.relative_to(dest_root)), opts.include, opts.exclude)
+    ]
+
+    if not files:
+        typer.echo("No prune candidates.", err=True)
+        return
+
+    typer.echo(f"\nPrune dest-only files in {dest.name}?\n", err=True)
+    for row in files:
+        typer.echo(str(row.dest_path.relative_to(dest_root)), err=True)
+
+    if opts.dry_run or not sys.stdin.isatty():
+        return
+    if prompt_utils.prompt_pull_confirm("Confirm?"):
+        for row in files:
+            row.dest_path.unlink()
+            logger.info(f"Pruned: {row.dest_path}")
+
+
+@app.command()
+def prune(
+    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 deleting"),
+    include: list[str] = _INCLUDE_OPTION,
+    exclude: list[str] = _EXCLUDE_OPTION,
+) -> None:
+    """Delete dest-only files after one confirm.
+
+    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 = PruneOptions(dry_run=dry_run, include=include, exclude=exclude)
+
+    try:
+        _run_prune(config, dest, src_root, opts)
+    except ValueError as e:
+        logger.error(f"Prune failed: {e}")
+        raise typer.Exit(1)

path_sync-0.9.0/path_sync/_internal/cmd_pull.py

@@ -0,0 +1,356 @@
+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
+
+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.dest_only import DestOnlyFile, collect_dest_only_files, is_opted_out
+from path_sync._internal.file_utils import ensure_parents_write_text
+from path_sync._internal.models import (
+    Destination,
+    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)
+
+
+@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 _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 _dest_only_candidate(row: DestOnlyFile) -> PullCandidate:
+    try:
+        row.dest_path.read_text()
+    except UnicodeDecodeError:
+        kind = PullKind.BINARY
+    else:
+        kind = PullKind.WHOLE
+    return PullCandidate(
+        src_path=row.src_path,
+        dest_path=row.dest_path,
+        dest_key=row.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]:
+    return [
+        _dest_only_candidate(row)
+        for row in collect_dest_only_files(config, dest, src_root, dest_root, dest_repo, skip_keys)
+    ]
+
+
+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.9.0/path_sync/_internal/dest_only.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import NamedTuple
+
+from git import Repo
+
+from path_sync._internal import git_ops, header
+from path_sync._internal.models import Destination, PathMapping, SrcConfig, SyncMode
+
+logger = logging.getLogger(__name__)
+
+
+class DestOnlyFile(NamedTuple):
+    src_path: Path
+    dest_path: Path
+    dest_key: str
+    sync_mode: SyncMode
+
+
+class _DestFileMap(NamedTuple):
+    src_path: Path
+    dest_key: str
+
+
+def is_opted_out(dest_text: str, sync_mode: SyncMode) -> bool:
+    return sync_mode == SyncMode.SYNC and not header.has_header(dest_text)
+
+
+def prune_eligible(files: list[DestOnlyFile]) -> list[DestOnlyFile]:
+    eligible: list[DestOnlyFile] = []
+    for row in files:
+        try:
+            dest_text = row.dest_path.read_text()
+        except UnicodeDecodeError:
+            continue
+        if not is_opted_out(dest_text, row.sync_mode):
+            eligible.append(row)
+    return eligible
+
+
+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 collect_dest_only_files(
+    config: SrcConfig,
+    dest: Destination,
+    src_root: Path,
+    dest_root: Path,
+    dest_repo: Repo,
+    skip_keys: set[str],
+) -> list[DestOnlyFile]:
+    files: list[DestOnlyFile] = []
+    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)
+            files.append(
+                DestOnlyFile(
+                    src_path=mapped.src_path,
+                    dest_path=dest_path,
+                    dest_key=mapped.dest_key,
+                    sync_mode=mapping.sync_mode,
+                )
+            )
+    return files

{path_sync-0.7.8 → path_sync-0.9.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.8 → path_sync-0.9.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.8 → path_sync-0.9.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.9.0/path_sync/prune.py

@@ -0,0 +1,4 @@
+# Generated by pkg-ext
+from path_sync._internal.cmd_prune import prune as _prune
+
+prune = _prune

path_sync-0.9.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.8 → path_sync-0.9.0}/pyproject.toml

@@ -2,7 +2,7 @@
 
 [project]
 name = "path-sync"
-version = "0.7.8"
+version = "0.9.0"
 description = "Sync files from a source repo to multiple destination repos"
 requires-python = ">=3.13"
 license = "MIT"
@@ -124,3 +124,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 ===