path-sync 0.2.1__py3-none-any.whl → 0.3.1__py3-none-any.whl

path_sync/__init__.py

@@ -1 +1,10 @@
-"""Path sync package for syncing files across repositories."""
+# Generated by pkg-ext
+# flake8: noqa
+from path_sync import copy
+from path_sync import config
+
+VERSION = "0.3.1"
+__all__ = [
+    "copy",
+    "config",
+]

path_sync/__main__.py

@@ -1,8 +1,8 @@
 import logging
 
-from path_sync import cmd_boot, cmd_copy, cmd_validate  # noqa: F401
-from path_sync.models import LOG_FORMAT
-from path_sync.typer_app import app
+from path_sync._internal import cmd_boot, cmd_copy, cmd_validate  # noqa: F401
+from path_sync._internal.models import LOG_FORMAT
+from path_sync._internal.typer_app import app
 
 
 def main() -> None:

path_sync/_internal/__init__.py

@@ -0,0 +1 @@
+"""Internal implementation - not part of public API."""

path_sync/{cmd_boot.py → _internal/cmd_boot.py}

@@ -6,17 +6,17 @@ from typing import Annotated
 
 import typer
 
-from path_sync import git_ops
-from path_sync.file_utils import ensure_parents_write_text
-from path_sync.models import (
+from path_sync._internal import git_ops
+from path_sync._internal.file_utils import ensure_parents_write_text
+from path_sync._internal.models import (
     Destination,
     PathMapping,
     SrcConfig,
     find_repo_root,
     resolve_config_path,
 )
-from path_sync.typer_app import app
-from path_sync.yaml_utils import dump_yaml_model, load_yaml_model
+from path_sync._internal.typer_app import app
+from path_sync._internal.yaml_utils import dump_yaml_model, load_yaml_model
 
 logger = logging.getLogger(__name__)
 
@@ -24,12 +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], typer.Option("-d", "--dest", help="Destination relative paths")] = [],
+    sync_paths: Annotated[list[str], typer.Option("-p", "--path", help="Paths to sync (glob patterns)")] = [],
     dry_run: bool = typer.Option(False, "--dry-run", help="Preview without writing"),
     regen: bool = typer.Option(False, "--regen", help="Regenerate config"),
 ) -> None:

path_sync/{cmd_copy.py → _internal/cmd_copy.py}

@@ -9,18 +9,20 @@ from pathlib import Path
 
 import typer
 
-from path_sync import git_ops, header, sections
-from path_sync.file_utils import ensure_parents_write_text
-from path_sync.models import (
+from path_sync import sections
+from path_sync._internal import git_ops, header
+from path_sync._internal.file_utils import ensure_parents_write_text
+from path_sync._internal.models import (
     LOG_FORMAT,
     Destination,
     PathMapping,
     SrcConfig,
+    SyncMode,
     find_repo_root,
     resolve_config_path,
 )
-from path_sync.typer_app import app
-from path_sync.yaml_utils import load_yaml_model
+from path_sync._internal.typer_app import app
+from path_sync._internal.yaml_utils import load_yaml_model
 
 logger = logging.getLogger(__name__)
 
@@ -85,9 +87,7 @@ class CopyOptions:
 @app.command()
 def copy(
     name: str = typer.Option(..., "-n", "--name", help="Config name"),
-    dest_filter: str = typer.Option(
-        "", "-d", "--dest", help="Filter destinations (comma-separated)"
-    ),
+    dest_filter: str = typer.Option("", "-d", "--dest", help="Filter destinations (comma-separated)"),
     dry_run: bool = typer.Option(False, "--dry-run", help="Preview without writing"),
     force_overwrite: bool = typer.Option(
         False,
@@ -188,9 +188,7 @@ def copy(
     for dest in destinations:
         try:
             with capture_sync_log(dest.name) as log_path:
-                changes = _sync_destination(
-                    config, dest, src_root, current_sha, src_repo_url, opts, log_path
-                )
+                changes = _sync_destination(config, dest, src_root, current_sha, src_repo_url, opts, log_path)
             total_changes += changes
         except Exception as e:
             logger.error(f"Failed to sync {dest.name}: {e}")
@@ -214,25 +212,27 @@ def _sync_destination(
     dest_root = (src_root / dest.dest_path_relative).resolve()
 
     if opts.dry_run and not dest_root.exists():
-        raise ValueError(
-            f"Destination repo not found: {dest_root}. "
-            "Clone it first or run without --dry-run."
-        )
+        raise ValueError(f"Destination repo not found: {dest_root}. Clone it first or run without --dry-run.")
 
     dest_repo = _ensure_dest_repo(dest, dest_root, opts.dry_run)
-
-    should_checkout = (
-        not opts.no_checkout
-        and not opts.dry_run
-        and _prompt(f"Switch to {dest.copy_branch}?", opts.no_prompt)
-    )
-    if should_checkout:
+    copy_branch = dest.resolved_copy_branch(config.name)
+
+    # --no-checkout means "I'm already on the right branch"
+    # Prompt decline means "skip git operations for this run"
+    if opts.no_checkout:
+        skip_git_ops = False
+    elif opts.dry_run:
+        skip_git_ops = True
+    elif _prompt(f"Switch {dest.name} to {copy_branch}?", opts.no_prompt):
         git_ops.prepare_copy_branch(
             repo=dest_repo,
             default_branch=dest.default_branch,
-            copy_branch=dest.copy_branch,
+            copy_branch=copy_branch,
             from_default=opts.checkout_from_default,
         )
+        skip_git_ops = False
+    else:
+        skip_git_ops = True
 
     result = _sync_paths(config, dest, src_root, dest_root, opts)
     _print_sync_summary(dest, result)
@@ -241,12 +241,10 @@ def _sync_destination(
         logger.info(f"{dest.name}: No changes")
         return 0
 
-    if opts.dry_run:
+    if skip_git_ops:
         return result.total
 
-    _commit_and_pr(
-        config, dest_repo, dest_root, dest, current_sha, src_repo_url, opts, log_path
-    )
+    _commit_and_pr(config, dest_repo, dest_root, dest, current_sha, src_repo_url, opts, log_path)
     return result.total
 
 
@@ -263,10 +261,7 @@ def _print_sync_summary(dest: Destination, result: SyncResult) -> None:
 def _ensure_dest_repo(dest: Destination, dest_root: Path, dry_run: bool):
     if not dest_root.exists():
         if dry_run:
-            raise ValueError(
-                f"Destination repo not found: {dest_root}. "
-                "Clone it first or run without --dry-run."
-            )
+            raise ValueError(f"Destination repo not found: {dest_root}. Clone it first or run without --dry-run.")
         if not dest.repo_url:
             raise ValueError(f"Dest {dest.name} not found and no repo_url configured")
         git_ops.clone_repo(dest.repo_url, dest_root)
@@ -295,9 +290,7 @@ def _sync_paths(
         result.synced_paths.update(paths)
 
     if not opts.skip_orphan_cleanup:
-        result.orphans_deleted = _cleanup_orphans(
-            dest_root, config.name, result.synced_paths, opts.dry_run
-        )
+        result.orphans_deleted = _cleanup_orphans(dest_root, config.name, result.synced_paths, opts.dry_run)
     return result
 
 
@@ -313,6 +306,7 @@ def _sync_path(
     src_pattern = src_root / mapping.src_path
     changes = 0
     synced: set[Path] = set()
+    sync_mode = mapping.sync_mode
 
     if "*" in mapping.src_path:
         glob_prefix = mapping.src_path.split("*")[0].rstrip("/")
@@ -326,12 +320,13 @@ def _sync_path(
                 rel = src_path.relative_to(src_root / glob_prefix)
                 dest_path = dest_root / dest_base / rel
                 dest_key = str(Path(dest_base) / rel)
-                changes += _copy_with_header(
+                changes += _copy_file(
                     src_path,
                     dest_path,
                     dest,
                     dest_key,
                     config_name,
+                    sync_mode,
                     dry_run,
                     force_overwrite,
                 )
@@ -343,12 +338,13 @@ def _sync_path(
                 rel = src_file.relative_to(src_pattern)
                 dest_path = dest_root / dest_base / rel
                 dest_key = str(Path(dest_base) / rel)
-                changes += _copy_with_header(
+                changes += _copy_file(
                     src_file,
                     dest_path,
                     dest,
                     dest_key,
                     config_name,
+                    sync_mode,
                     dry_run,
                     force_overwrite,
                 )
@@ -356,12 +352,13 @@ def _sync_path(
     elif src_pattern.is_file():
         dest_base = mapping.resolved_dest_path()
         dest_path = dest_root / dest_base
-        changes += _copy_with_header(
+        changes += _copy_file(
             src_pattern,
             dest_path,
             dest,
             dest_base,
             config_name,
+            sync_mode,
             dry_run,
             force_overwrite,
         )
@@ -372,43 +369,74 @@ def _sync_path(
     return changes, synced
 
 
-def _copy_with_header(
+def _copy_file(
     src: Path,
     dest_path: Path,
     dest: Destination,
     dest_key: str,
     config_name: str,
+    sync_mode: SyncMode,
     dry_run: bool,
     force_overwrite: bool = False,
 ) -> int:
-    src_content = src.read_text()
-    skip_list = dest.skip_sections.get(dest_key, [])
+    src_content = header.remove_header(src.read_text())
 
-    if sections.has_sections(src_content):
-        return _copy_with_sections(
-            src_content, dest_path, skip_list, config_name, dry_run, force_overwrite
-        )
+    match sync_mode:
+        case SyncMode.SCAFFOLD:
+            return _handle_scaffold(src_content, dest_path, dry_run)
+        case SyncMode.REPLACE:
+            return _handle_replace(src_content, dest_path, dry_run)
+        case SyncMode.SYNC:
+            skip_list = dest.skip_sections.get(dest_key, [])
+            return _handle_sync(src_content, dest_path, skip_list, config_name, dry_run, force_overwrite)
+
+
+def _handle_scaffold(content: str, dest_path: Path, dry_run: bool) -> int:
+    if dest_path.exists():
+        return 0
+    return _write_file(dest_path, content, dry_run)
+
+
+def _handle_replace(content: str, dest_path: Path, dry_run: bool) -> int:
+    if dest_path.exists() and dest_path.read_text() == content:
+        return 0
+    return _write_file(dest_path, content, dry_run)
+
+
+def _handle_sync(
+    src_content: str,
+    dest_path: Path,
+    skip_list: list[str],
+    config_name: str,
+    dry_run: bool,
+    force_overwrite: bool,
+) -> int:
+    if sections.has_sections(src_content, dest_path):
+        return _handle_sync_sections(src_content, dest_path, skip_list, config_name, dry_run, force_overwrite)
 
     if dest_path.exists():
         existing = dest_path.read_text()
-        has_header = header.has_header(existing)
-        if not has_header and not force_overwrite:
+        has_hdr = header.has_header(existing)
+        if not has_hdr and not force_overwrite:
             logger.info(f"Skipping {dest_path} (header removed - opted out)")
             return 0
-        if header.remove_header(existing) == src_content and has_header:
+        if header.remove_header(existing) == src_content and has_hdr:
             return 0
 
-    new_content = header.add_header(src_content, dest_path.suffix, config_name)
+    new_content = header.add_header(src_content, dest_path, config_name)
+    return _write_file(dest_path, new_content, dry_run)
+
+
+def _write_file(dest_path: Path, content: str, dry_run: bool) -> int:
     if dry_run:
         logger.info(f"[DRY RUN] Would write: {dest_path}")
         return 1
-
-    ensure_parents_write_text(dest_path, new_content)
+    ensure_parents_write_text(dest_path, content)
     logger.info(f"Wrote: {dest_path}")
     return 1
 
 
-def _copy_with_sections(
+def _handle_sync_sections(
     src_content: str,
     dest_path: Path,
     skip_list: list[str],
@@ -416,7 +444,7 @@ def _copy_with_sections(
     dry_run: bool,
     force_overwrite: bool,
 ) -> int:
-    src_sections = sections.extract_sections(src_content)
+    src_sections = sections.extract_sections(src_content, dest_path)
 
     if dest_path.exists():
         existing = dest_path.read_text()
@@ -424,22 +452,16 @@ def _copy_with_sections(
             logger.info(f"Skipping {dest_path} (header removed - opted out)")
             return 0
         dest_body = header.remove_header(existing)
-        new_body = sections.replace_sections(dest_body, src_sections, skip_list)
+        new_body = sections.replace_sections(dest_body, src_sections, dest_path, skip_list)
     else:
         new_body = src_content
 
-    new_content = header.add_header(new_body, dest_path.suffix, config_name)
+    new_content = header.add_header(new_body, dest_path, config_name)
 
     if dest_path.exists() and dest_path.read_text() == new_content:
         return 0
 
-    if dry_run:
-        logger.info(f"[DRY RUN] Would write: {dest_path}")
-        return 1
-
-    ensure_parents_write_text(dest_path, new_content)
-    logger.info(f"Wrote: {dest_path}")
-    return 1
+    return _write_file(dest_path, new_content, dry_run)
 
 
 def _cleanup_orphans(
@@ -462,12 +484,11 @@ def _cleanup_orphans(
 
 def _find_files_with_config(dest_root: Path, config_name: str) -> list[Path]:
     result = []
-    for ext in header.COMMENT_PREFIXES:
-        for path in dest_root.rglob(f"*{ext}"):
-            if ".git" in path.parts:
-                continue
-            if header.file_get_config_name(path) == config_name:
-                result.append(path)
+    for path in dest_root.rglob("*"):
+        if ".git" in path.parts:
+            continue
+        if header.file_get_config_name(path) == config_name:
+            result.append(path)
     return result
 
 
@@ -485,20 +506,22 @@ def _commit_and_pr(
         logger.info("Local mode: skipping commit/push/PR")
         return
 
-    if not _prompt("Commit changes?", opts.no_prompt):
+    copy_branch = dest.resolved_copy_branch(config.name)
+
+    if not _prompt(f"Commit changes to {dest.name}?", opts.no_prompt):
         return
 
     commit_msg = f"chore: sync {config.name} from {sha[:8]}"
     git_ops.commit_changes(repo, commit_msg)
     typer.echo(f"  Committed: {commit_msg}", err=True)
 
-    if not _prompt("Push to origin?", opts.no_prompt):
+    if not _prompt(f"Push {dest.name} to origin?", opts.no_prompt):
         return
 
-    git_ops.push_branch(repo, dest.copy_branch, force=True)
-    typer.echo(f"  Pushed: {dest.copy_branch} (force)", err=True)
+    git_ops.push_branch(repo, copy_branch, force=True)
+    typer.echo(f"  Pushed: {copy_branch} (force)", err=True)
 
-    if opts.no_pr or not _prompt("Create PR?", opts.no_prompt):
+    if opts.no_pr or not _prompt(f"Create PR for {dest.name}?", opts.no_prompt):
         return
 
     sync_log = log_path.read_text() if log_path.exists() else ""
@@ -512,7 +535,7 @@ def _commit_and_pr(
     title = opts.pr_title.format(name=config.name, dest_name=dest.name)
     pr_url = git_ops.create_or_update_pr(
         dest_root,
-        dest.copy_branch,
+        copy_branch,
         title,
         pr_body,
         opts.pr_labels.split(",") if opts.pr_labels else None,

path_sync/{cmd_validate.py → _internal/cmd_validate.py}

@@ -5,19 +5,17 @@ from pathlib import Path
 
 import typer
 
-from path_sync import git_ops
-from path_sync.models import find_repo_root
-from path_sync.typer_app import app
-from path_sync.validation import parse_skip_sections, validate_no_unauthorized_changes
+from path_sync._internal import git_ops
+from path_sync._internal.models import find_repo_root
+from path_sync._internal.typer_app import app
+from path_sync._internal.validation import parse_skip_sections, validate_no_unauthorized_changes
 
 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="Default branch to compare against"),
     skip_sections_opt: str = typer.Option(
         "",
         "--skip-sections",
@@ -36,16 +34,12 @@ def validate_no_changes(
         logger.info(f"On default branch {branch}, validation skipped")
         return
 
-    skip_sections = (
-        parse_skip_sections(skip_sections_opt) if skip_sections_opt else None
-    )
+    skip_sections = parse_skip_sections(skip_sections_opt) if skip_sections_opt else None
     unauthorized = validate_no_unauthorized_changes(repo_root, branch, skip_sections)
 
     if unauthorized:
         files_list = "\n  ".join(unauthorized)
-        logger.error(
-            f"Unauthorized changes in {len(unauthorized)} files:\n  {files_list}"
-        )
+        logger.error(f"Unauthorized changes in {len(unauthorized)} files:\n  {files_list}")
         raise typer.Exit(1)
 
     logger.info("Validation passed: no unauthorized changes")

path_sync/{git_ops.py → _internal/git_ops.py}

@@ -37,9 +37,7 @@ def is_git_repo(path: Path) -> bool:
 
 def get_default_branch(repo: Repo) -> str:
     with suppress(GitCommandError):
-        return repo.git.symbolic_ref("refs/remotes/origin/HEAD", short=True).replace(
-            "origin/", ""
-        )
+        return repo.git.symbolic_ref("refs/remotes/origin/HEAD", short=True).replace("origin/", "")
     return "main"
 
 
@@ -60,9 +58,7 @@ def checkout_branch(repo: Repo, branch: str) -> None:
         repo.git.checkout("-b", branch)
 
 
-def prepare_copy_branch(
-    repo: Repo, default_branch: str, copy_branch: str, from_default: bool = False
-) -> None:
+def prepare_copy_branch(repo: Repo, default_branch: str, copy_branch: str, from_default: bool = False) -> None:
     """Prepare copy_branch for syncing.
 
     Args:
@@ -117,9 +113,7 @@ def _ensure_git_user(repo: Repo) -> None:
         repo.config_reader().get_value("user", "name")
     except Exception:
         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()
+        repo.config_writer().set_value("user", "email", "path-sync[bot]@users.noreply.github.com").release()
 
 
 def push_branch(repo: Repo, branch: str, force: bool = True) -> None:

path_sync/_internal/header.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from zero_3rdparty.sections import CommentConfig, get_comment_config
+
+from path_sync._internal.models import HEADER_TEMPLATE, HeaderConfig
+
+HEADER_PATTERN = re.compile(r"path-sync copy -n (?P<config_name>[\w-]+)")
+
+
+def _resolve_comment_config(path: Path, config: HeaderConfig | None) -> CommentConfig:
+    if config:
+        ext = path.suffix
+        prefix = config.comment_prefixes.get(ext)
+        suffix = config.comment_suffixes.get(ext, "")
+        if prefix:
+            return CommentConfig(prefix, suffix)
+    return get_comment_config(path)
+
+
+def get_comment_prefix(path: Path, config: HeaderConfig | None = None) -> str:
+    return _resolve_comment_config(path, config).prefix
+
+
+def get_comment_suffix(path: Path, config: HeaderConfig | None = None) -> str:
+    return _resolve_comment_config(path, config).suffix
+
+
+def get_header_line(path: Path, config_name: str, config: HeaderConfig | None = None) -> str:
+    cc = _resolve_comment_config(path, config)
+    header_text = HEADER_TEMPLATE.format(config_name=config_name)
+    return f"{cc.prefix} {header_text}{cc.suffix}"
+
+
+def has_header(content: str) -> bool:
+    first_line = content.split("\n", 1)[0] if content else ""
+    return bool(HEADER_PATTERN.search(first_line))
+
+
+def get_config_name(content: str) -> str | None:
+    first_line = content.split("\n", 1)[0] if content else ""
+    if match := HEADER_PATTERN.search(first_line):
+        return match.group("config_name")
+    return None
+
+
+def add_header(content: str, path: Path, config_name: str, config: HeaderConfig | None = None) -> str:
+    header = get_header_line(path, config_name, config)
+    return f"{header}\n{content}"
+
+
+def remove_header(content: str) -> str:
+    if not has_header(content):
+        return content
+    lines = content.split("\n", 1)
+    return lines[1] if len(lines) > 1 else ""
+
+
+def has_known_comment_prefix(path: Path) -> bool:
+    try:
+        get_comment_config(path)
+        return True
+    except ValueError:
+        return False
+
+
+def file_get_config_name(path: Path) -> str | None:
+    if not path.exists() or not has_known_comment_prefix(path):
+        return None
+    try:
+        with path.open() as f:
+            first_line = f.readline()
+    except (UnicodeDecodeError, OSError):
+        return None
+    return get_config_name(first_line)
+
+
+def file_has_header(path: Path, config: HeaderConfig | None = None) -> bool:
+    if config and path.suffix not in config.comment_prefixes:
+        return False
+    return file_get_config_name(path) is not None

path_sync/{models.py → _internal/models.py}

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import glob as glob_mod
+from enum import StrEnum
 from pathlib import Path
 from typing import ClassVar
 
@@ -9,9 +10,16 @@ from pydantic import BaseModel, Field
 LOG_FORMAT = "%(asctime)s %(levelname)s %(message)s"
 
 
+class SyncMode(StrEnum):
+    SYNC = "sync"
+    REPLACE = "replace"
+    SCAFFOLD = "scaffold"
+
+
 class PathMapping(BaseModel):
     src_path: str
     dest_path: str = ""
+    sync_mode: SyncMode = SyncMode.SYNC
 
     def resolved_dest_path(self) -> str:
         return self.dest_path or self.src_path
@@ -30,32 +38,11 @@ class PathMapping(BaseModel):
 
 
 HEADER_TEMPLATE = "path-sync copy -n {config_name}"
-DEFAULT_COMMENT_PREFIXES: dict[str, str] = {
-    ".py": "#",
-    ".sh": "#",
-    ".yaml": "#",
-    ".yml": "#",
-    ".go": "//",
-    ".js": "//",
-    ".ts": "//",
-    ".md": "<!--",
-    ".mdc": "<!--",
-    ".html": "<!--",
-}
-DEFAULT_COMMENT_SUFFIXES: dict[str, str] = {
-    ".md": " -->",
-    ".mdc": " -->",
-    ".html": " -->",
-}
 
 
 class HeaderConfig(BaseModel):
-    comment_prefixes: dict[str, str] = Field(
-        default_factory=DEFAULT_COMMENT_PREFIXES.copy
-    )
-    comment_suffixes: dict[str, str] = Field(
-        default_factory=DEFAULT_COMMENT_SUFFIXES.copy
-    )
+    comment_prefixes: dict[str, str] = Field(default_factory=dict)
+    comment_suffixes: dict[str, str] = Field(default_factory=dict)
 
 
 DEFAULT_BODY_TEMPLATE = """\
@@ -105,10 +92,14 @@ class Destination(BaseModel):
     name: str
     repo_url: str = ""
     dest_path_relative: str
-    copy_branch: str = "sync/path-sync"
+    copy_branch: str = ""
     default_branch: str = "main"
     skip_sections: dict[str, list[str]] = Field(default_factory=dict)
 
+    def resolved_copy_branch(self, config_name: str) -> str:
+        """Returns branch name, defaulting to sync/{config_name} if not set."""
+        return self.copy_branch or f"sync/{config_name}"
+
 
 class SrcConfig(BaseModel):
     CONFIG_EXT: ClassVar[str] = ".src.yaml"