dotsman 1.0.0__py3-none-any.whl

dots/__init__.py

@@ -0,0 +1 @@
+VERSION = "1.0.0"

dots/cli.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from dots import VERSION
+from dots.errors import DotsError
+from dots.repo import DotRepository
+from dots.ui import UI
+
+app = typer.Typer(
+    name="dots",
+    help="Configuration files management tool.",
+    no_args_is_help=True,
+    add_completion=False,
+    pretty_exceptions_show_locals=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"dots {VERSION}")
+        raise typer.Exit
+
+
+def config_callback(value: Path) -> Path:
+    return value.expanduser()
+
+
+def load_repo(ctx: typer.Context) -> DotRepository:
+    state: State = ctx.obj
+    return DotRepository.load(state.config, state.ui)
+
+
+class State:
+    def __init__(self, config: Path, verbose: bool) -> None:
+        self.config = config
+        self.verbose = verbose
+        self.ui = UI(verbose=verbose)
+
+
+@app.callback()
+def app_main(
+    ctx: typer.Context,
+    config: Annotated[
+        Path,
+        typer.Option(
+            "--config",
+            "-c",
+            help="configuration file",
+            callback=config_callback,
+        ),
+    ] = Path("~/.dots.conf"),
+    verbose: Annotated[
+        bool,
+        typer.Option("--verbose", "-v", help="display debug information"),
+    ] = False,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            help="display program version and exit",
+            callback=version_callback,
+            is_eager=True,
+        ),
+    ] = False,
+) -> None:
+    _ = version  # consumed by version_callback; silence unused-parameter checks
+    ctx.obj = State(config=config, verbose=verbose)
+
+
+@app.command("add")
+def cmd_add(
+    ctx: typer.Context,
+    file: Annotated[Path, typer.Argument(help="path of the file to add")],
+    encrypt: Annotated[
+        bool,
+        typer.Option("--encrypt", "-e", help="encrypt the file with age"),
+    ] = False,
+) -> None:
+    """
+    Add a file to the repository.
+    """
+    load_repo(ctx).add(file, encrypt=encrypt)
+
+
+@app.command("remove")
+def cmd_remove(
+    ctx: typer.Context,
+    file: Annotated[Path, typer.Argument(help="path of the file to remove")],
+) -> None:
+    """
+    Remove a file from the repository.
+    """
+    load_repo(ctx).remove(file)
+
+
+@app.command("list")
+def cmd_list(ctx: typer.Context) -> None:
+    """
+    List repository contents.
+    """
+    load_repo(ctx).sync(list_only=True)
+
+
+@app.command("sync")
+def cmd_sync(
+    ctx: typer.Context,
+    force_relink: Annotated[
+        bool,
+        typer.Option(
+            "--force-relink",
+            "-r",
+            help="if a link points to another file, overwrite without asking",
+        ),
+    ] = False,
+    force_add: Annotated[
+        bool,
+        typer.Option(
+            "--force-add",
+            "-a",
+            help="if a file already exists, overwrite the repository version",
+        ),
+    ] = False,
+    force_link: Annotated[
+        bool,
+        typer.Option(
+            "--force-link",
+            "-l",
+            help="if a file already exists, overwrite the local version",
+        ),
+    ] = False,
+) -> None:
+    """
+    Synchronize repository content with the filesystem.
+    """
+    if force_add and force_link:
+        raise typer.BadParameter("--force-add and --force-link are mutually exclusive")
+    load_repo(ctx).sync(
+        force_relink=force_relink,
+        force_add=force_add,
+        force_link=force_link,
+    )
+
+
+# Command aliases (hidden so they don't clutter --help)
+app.command("a", hidden=True)(cmd_add)
+app.command("rm", hidden=True)(cmd_remove)
+app.command("rem", hidden=True)(cmd_remove)
+app.command("del", hidden=True)(cmd_remove)
+app.command("delete", hidden=True)(cmd_remove)
+app.command("l", hidden=True)(cmd_list)
+app.command("ls", hidden=True)(cmd_list)
+app.command("s", hidden=True)(cmd_sync)
+
+
+def main() -> None:
+    """
+    Script entry point. Wraps ``app`` so ``DotsError`` produces clean output.
+    """
+    try:
+        app()
+    except DotsError as e:
+        UI().error(str(e))
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

dots/crypto.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from pathlib import Path
+
+from pyrage import decrypt, encrypt, x25519
+
+from dots.errors import CryptoError
+
+AGE_EXTENSION = ".age"
+DECRYPTED_DIR = ".decrypted"
+
+
+@dataclass(frozen=True)
+class AgeKeyPair:
+    identity: x25519.Identity
+    recipient: x25519.Recipient
+
+
+def load_identity(identity_path: Path) -> AgeKeyPair:
+    """
+    Read an age identity file and return the keypair.
+
+    The file format is the standard age key file: comment lines start
+    with ``#``, the secret key line starts with ``AGE-SECRET-KEY-``.
+    """
+    try:
+        text = identity_path.read_text().strip()
+    except OSError as e:
+        raise CryptoError(f"cannot read identity file: {e}", identity_path) from e
+
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("AGE-SECRET-KEY-"):
+            try:
+                identity = x25519.Identity.from_str(line)
+            except Exception as e:
+                raise CryptoError(f"invalid age identity: {e}", identity_path) from e
+            return AgeKeyPair(identity=identity, recipient=identity.to_public())
+
+    raise CryptoError("no AGE-SECRET-KEY found in identity file", identity_path)
+
+
+def age_encrypt(plaintext: bytes, recipient: x25519.Recipient) -> bytes:
+    try:
+        return encrypt(plaintext, [recipient])
+    except Exception as e:
+        raise CryptoError(f"encryption failed: {e}") from e
+
+
+def age_decrypt(ciphertext: bytes, identity: x25519.Identity) -> bytes:
+    try:
+        return decrypt(ciphertext, [identity])
+    except Exception as e:
+        raise CryptoError(f"decryption failed: {e}") from e
+
+
+def content_hash(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def is_age_file(path: Path) -> bool:
+    return path.suffix == AGE_EXTENSION
+
+
+def age_to_decrypted_path(repo_path: Path, age_file: Path) -> Path:
+    """
+    Map a ``.age`` repo file to its decrypted working copy path.
+
+    Example: ``repo/.config/secret.age`` -> ``repo/.decrypted/.config/secret``
+    """
+    relpath = age_file.relative_to(repo_path)
+    return repo_path / DECRYPTED_DIR / relpath.with_suffix("")
+
+
+def age_to_home_path(repo_path: Path, home_path: Path, age_file: Path) -> Path:
+    """
+    Map a ``.age`` repo file to the home symlink path.
+
+    Example: ``repo/.config/secret.age`` -> ``home/.config/secret``
+    """
+    relpath = age_file.relative_to(repo_path)
+    return home_path / relpath.with_suffix("")
+
+
+def home_to_age_path(repo_path: Path, home_path: Path, target: Path) -> Path:
+    """
+    Map a home file to its ``.age`` repo path.
+
+    Example: ``home/.config/secret`` -> ``repo/.config/secret.age``
+    """
+    relpath = target.relative_to(home_path)
+    return repo_path / (relpath.as_posix() + AGE_EXTENSION)

dots/errors.py

@@ -0,0 +1,80 @@
+from pathlib import Path
+
+
+class DotsError(Exception):
+    """
+    Base class for all dots errors the CLI is expected to handle.
+    """
+
+
+class ConfigError(DotsError):
+    """
+    Configuration file is missing, unreadable, or invalid.
+    """
+
+
+class RepoError(DotsError):
+    """
+    Dotfiles repository is missing or malformed.
+    """
+
+
+class NotInHomeError(DotsError):
+    """
+    Target file is not under the user's home directory.
+    """
+
+    def __init__(self, path: Path, home: Path) -> None:
+        super().__init__(f"{path} is not inside {home}")
+        self.path = path
+        self.home = home
+
+
+class NotInRepoError(DotsError):
+    """
+    An operation expected a file inside the repository.
+    """
+
+    def __init__(self, path: Path) -> None:
+        super().__init__(f"{path} is not a repository file")
+        self.path = path
+
+
+class AlreadyInRepoError(DotsError):
+    """
+    Trying to add a file that is already tracked.
+    """
+
+    def __init__(self, path: Path) -> None:
+        super().__init__(f"{path} is already in the repository")
+        self.path = path
+
+
+class InvalidTargetError(DotsError):
+    """
+    Target file is of an unexpected kind (e.g. a dangling symlink).
+    """
+
+    def __init__(self, message: str, path: Path) -> None:
+        super().__init__(message)
+        self.path = path
+
+
+class FsError(DotsError):
+    """
+    Atomic filesystem primitive fails and has been rolled back.
+    """
+
+    def __init__(self, message: str, path: Path) -> None:
+        super().__init__(message)
+        self.path = path
+
+
+class CryptoError(DotsError):
+    """
+    Age encryption or decryption failure.
+    """
+
+    def __init__(self, message: str, path: Path | None = None) -> None:
+        super().__init__(message)
+        self.path = path

dots/fs.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import contextlib
+import os
+import shutil
+from pathlib import Path
+
+from dots.errors import FsError
+
+TMP_TEMPLATE = ".{name}.dots-{pid}.tmp"
+
+
+def tmp_path(target: Path) -> Path:
+    return target.with_name(TMP_TEMPLATE.format(name=target.name, pid=os.getpid()))
+
+
+def is_inside(child: Path, parent: Path) -> bool:
+    """
+    Return True if ``child`` is at or under ``parent``.
+
+    Both paths are made absolute, but symlinks are NOT followed.
+    """
+    return child.absolute().is_relative_to(parent.absolute())
+
+
+def ensure_parent_dir(path: Path) -> None:
+    """
+    Create all missing parent directories of ``path``.
+    """
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+    except OSError as e:
+        raise FsError(f"failed to create parent directory for {path}", path) from e
+
+
+def atomic_symlink(target: Path, link: Path) -> None:
+    """
+    Atomically create or replace a symlink at ``link`` pointing to ``target``.
+
+    Works whether ``link`` is currently missing, a regular file, or an existing
+    symlink.
+    """
+    ensure_parent_dir(link)
+    tmp = tmp_path(link)
+    try:
+        tmp.symlink_to(target)
+    except OSError as e:
+        raise FsError(f"failed to create symlink at {link}", link) from e
+    try:
+        tmp.replace(link)
+    except OSError as e:
+        with contextlib.suppress(FileNotFoundError):
+            tmp.unlink()
+        raise FsError(f"failed to install symlink at {link}", link) from e
+
+
+def atomic_copy(src: Path, dst: Path) -> None:
+    """
+    Atomically install a copy of ``src`` at ``dst``.
+
+    Copies to a sibling temp next to ``dst`` then ``os.replace`` to commit.
+    ``src`` is never touched - the caller decides whether to remove it.
+    On any failure, ``dst`` is left in its previous state.
+    """
+    ensure_parent_dir(dst)
+    tmp = tmp_path(dst)
+    try:
+        shutil.copy2(src, tmp)
+    except OSError as e:
+        with contextlib.suppress(FileNotFoundError):
+            tmp.unlink()
+        raise FsError(f"failed to stage copy at {dst}", dst) from e
+    try:
+        tmp.replace(dst)
+    except OSError as e:
+        with contextlib.suppress(FileNotFoundError):
+            tmp.unlink()
+        raise FsError(f"failed to install file at {dst}", dst) from e
+
+
+def atomic_write(dst: Path, data: bytes) -> None:
+    """
+    Atomically write ``data`` to ``dst``.
+
+    Writes to a sibling temp file then ``os.replace`` to commit.
+    On failure, ``dst`` is left in its previous state.
+    """
+    ensure_parent_dir(dst)
+    tmp = tmp_path(dst)
+    try:
+        tmp.write_bytes(data)
+    except OSError as e:
+        with contextlib.suppress(FileNotFoundError):
+            tmp.unlink()
+        raise FsError(f"failed to write to {dst}", dst) from e
+    try:
+        tmp.replace(dst)
+    except OSError as e:
+        with contextlib.suppress(FileNotFoundError):
+            tmp.unlink()
+        raise FsError(f"failed to install file at {dst}", dst) from e
+
+
+def safe_unlink(path: Path) -> None:
+    """
+    Remove ``path`` if it exists. Tolerant of missing paths.
+    """
+    try:
+        path.unlink(missing_ok=True)
+    except OSError as e:
+        raise FsError(f"failed to remove {path}", path) from e

dots/repo.py

@@ -0,0 +1,519 @@
+from __future__ import annotations
+
+import contextlib
+import enum
+import fnmatch
+import platform
+from collections.abc import Iterator
+from configparser import ConfigParser
+from configparser import Error as ConfigParserError
+from dataclasses import dataclass
+from pathlib import Path
+
+from git import Repo as GitRepo
+from git.exc import GitError
+
+from dots import crypto, fs
+from dots.crypto import AgeKeyPair
+from dots.errors import (
+    AlreadyInRepoError,
+    ConfigError,
+    CryptoError,
+    DotsError,
+    InvalidTargetError,
+    NotInHomeError,
+    NotInRepoError,
+    RepoError,
+)
+from dots.ui import UI
+
+
+class SyncOutcome(enum.Enum):
+    OK = "ok"
+    INSTALLED = "installed"
+    REPLACED = "replaced"
+    MISSING = "missing"
+    CONFLICT = "conflict"
+    SKIPPED = "skipped"
+
+
+@dataclass(frozen=True)
+class DotConfig:
+    repo_dir: Path
+    ignored: tuple[str, ...]
+    age_identity: Path | None
+
+
+def load_config(config_path: Path) -> DotConfig:
+    """
+    Parse the config file and return a ``DotConfig``.
+
+    Selects a hostname-specific section if one is present, otherwise falls back
+    to ``[DEFAULT]``. Uses defaults if file is missing.
+    """
+    cfg = ConfigParser(defaults={"repo_dir": "~/dots", "ignored_files": ""})
+    if config_path.is_file():
+        try:
+            cfg.read(config_path)
+        except ConfigParserError as e:
+            raise ConfigError(f"invalid config file {config_path}: {e}") from e
+
+    hostname = platform.node()
+    section_name = hostname if hostname in cfg else "DEFAULT"
+    section = cfg[section_name]
+
+    repo_dir_raw = section.get("repo_dir")
+    if not repo_dir_raw:
+        raise ConfigError(f"missing 'repo_dir' in config section [{section_name}]")
+    repo_dir = Path(repo_dir_raw).expanduser().resolve()
+
+    raw_ignored = section.get("ignored_files", "")
+    ignored = tuple(p.strip() for p in raw_ignored.split(",") if p.strip())
+
+    raw_age_identity = section.get("age_identity", "")
+    age_identity: Path | None = None
+    if raw_age_identity.strip():
+        age_identity = Path(raw_age_identity.strip()).expanduser().resolve()
+
+    return DotConfig(repo_dir=repo_dir, ignored=ignored, age_identity=age_identity)
+
+
+@dataclass(frozen=True)
+class DotRepository:
+    """
+    A dotfiles repository.
+    """
+
+    path: Path
+    home: Path
+    ignored: tuple[str, ...]
+    git: GitRepo | None
+    ui: UI
+    age_keypair: AgeKeyPair | None = None
+
+    @classmethod
+    def load(cls, config_path: Path, ui: UI) -> DotRepository:
+        ui.debug(f"Loading configuration from {config_path}")
+        config = load_config(config_path)
+        if not config.repo_dir.is_dir():
+            raise RepoError(f"no dots repository found at {config.repo_dir}")
+
+        git_repo: GitRepo | None = None
+        if (config.repo_dir / ".git").is_dir():
+            try:
+                git_repo = GitRepo(config.repo_dir)
+            except GitError as e:
+                ui.warning(f"could not open git repo at {config.repo_dir}: {e}")
+
+        age_keypair: AgeKeyPair | None = None
+        if config.age_identity is not None:
+            try:
+                age_keypair = crypto.load_identity(config.age_identity)
+            except CryptoError as e:
+                ui.warning(f"age identity unavailable: {e}")
+
+        return cls(
+            path=config.repo_dir,
+            home=Path.home().resolve(),
+            ignored=config.ignored,
+            git=git_repo,
+            ui=ui,
+            age_keypair=age_keypair,
+        )
+
+    def add(self, target: Path, *, encrypt: bool = False) -> None:
+        """
+        Move ``target`` into the repository and replace it with a symlink.
+
+        When ``encrypt`` is True the file is stored as an age-encrypted
+        ``.age`` file and a decrypted working copy in ``.decrypted/`` is
+        used as the symlink target.
+
+        Safety: the file is copied into the repo first, then the symlink is
+        installed atomically. If the symlink step fails the stray copy is
+        removed - the user's file is never in an unreachable state.
+        """
+        target = target.absolute()
+        self.ui.debug(f"Adding '{target}' to the repository...")
+        self.validate_addable(target)
+
+        if encrypt:
+            self._add_encrypted(target)
+        else:
+            self._add_plain(target)
+
+    def _add_plain(self, target: Path) -> None:
+        relpath = target.relative_to(self.home)
+        repo_file = self.path / relpath
+
+        self.ui.debug(f"Copying {target} to {repo_file}")
+        fs.atomic_copy(target, repo_file)
+
+        try:
+            self.ui.debug(f"Creating symlink at {target}")
+            fs.atomic_symlink(repo_file, target)
+        except DotsError:
+            with contextlib.suppress(DotsError):
+                fs.safe_unlink(repo_file)
+            raise
+
+        self.git_commit_safe(f"added {relpath.as_posix()}")
+        self.ui.installed(target)
+
+    def _add_encrypted(self, target: Path) -> None:
+        if self.age_keypair is None:
+            raise CryptoError("no age identity configured")
+
+        relpath = target.relative_to(self.home)
+        age_file = crypto.home_to_age_path(self.path, self.home, target)
+        decrypted_path = crypto.age_to_decrypted_path(self.path, age_file)
+
+        plaintext = target.read_bytes()
+        ciphertext = crypto.age_encrypt(plaintext, self.age_keypair.recipient)
+
+        self.ui.debug(f"Encrypting {target} to {age_file}")
+        fs.atomic_write(age_file, ciphertext)
+
+        self.ui.debug(f"Writing decrypted copy to {decrypted_path}")
+        fs.atomic_write(decrypted_path, plaintext)
+
+        self.ensure_decrypted_gitignored()
+
+        try:
+            self.ui.debug(f"Creating symlink at {target}")
+            fs.atomic_symlink(decrypted_path, target)
+        except DotsError:
+            with contextlib.suppress(DotsError):
+                fs.safe_unlink(age_file)
+            with contextlib.suppress(DotsError):
+                fs.safe_unlink(decrypted_path)
+            raise
+
+        self.git_commit_safe(f"added {relpath.as_posix()} (encrypted)")
+        self.ui.installed(target, encrypted=True)
+
+    def remove(self, target: Path) -> None:
+        """
+        Restore a repository file to its original location and un-track it.
+
+        Safety: the repo content is copied back to the home location first (an
+        atomic ``os.replace`` that swaps the symlink for a regular file). Only
+        after that commit step is the repo copy deleted.
+        """
+        target = target.absolute()
+        self.ui.debug(f"Removing '{target}' from the repository...")
+
+        repo_file = target.resolve()
+        if not fs.is_inside(repo_file, self.path):
+            raise NotInRepoError(target)
+
+        # detect encrypted files: symlink target is inside .decrypted/
+        decrypted_dir = self.path / crypto.DECRYPTED_DIR
+        if fs.is_inside(repo_file, decrypted_dir):
+            self._remove_encrypted(target, repo_file)
+            return
+
+        relpath = repo_file.relative_to(self.path)
+        home_file = self.home / relpath
+
+        if not home_file.is_symlink():
+            raise InvalidTargetError(f"expected symlink at {home_file}", home_file)
+        if home_file.resolve() != repo_file:
+            raise InvalidTargetError(f"{home_file} does not point to {repo_file}", home_file)
+
+        # install a regular-file copy at home_file (atomically replaces the symlink)
+        self.ui.debug(f"Restoring {repo_file} to {home_file}")
+        fs.atomic_copy(repo_file, home_file)
+
+        # drop the repo-side copy
+        self.ui.debug(f"Removing repo file {repo_file}")
+        fs.safe_unlink(repo_file)
+
+        # clean empty parent dirs in the repo
+        self.rm_empty_folders(repo_file.parent)
+
+        # commit to git
+        self.git_commit_safe(f"removed {relpath.as_posix()}")
+        self.ui.removed(target)
+
+    def _remove_encrypted(self, target: Path, decrypted_file: Path) -> None:
+        decrypted_dir = self.path / crypto.DECRYPTED_DIR
+        rel_in_decrypted = decrypted_file.relative_to(decrypted_dir)
+        age_file = self.path / (rel_in_decrypted.as_posix() + crypto.AGE_EXTENSION)
+        home_file = self.home / rel_in_decrypted
+
+        if not home_file.is_symlink():
+            raise InvalidTargetError(f"expected symlink at {home_file}", home_file)
+        if home_file.resolve() != decrypted_file:
+            raise InvalidTargetError(f"{home_file} does not point to {decrypted_file}", home_file)
+
+        # restore decrypted content to home location
+        self.ui.debug(f"Restoring {decrypted_file} to {home_file}")
+        fs.atomic_copy(decrypted_file, home_file)
+
+        # remove .age file and decrypted copy
+        self.ui.debug(f"Removing {age_file}")
+        fs.safe_unlink(age_file)
+        self.ui.debug(f"Removing {decrypted_file}")
+        fs.safe_unlink(decrypted_file)
+
+        # clean empty dirs in both repo and .decrypted
+        self.rm_empty_folders(age_file.parent)
+        self.rm_empty_folders(decrypted_file.parent)
+
+        self.git_commit_safe(f"removed {rel_in_decrypted.as_posix()} (encrypted)")
+        self.ui.removed(target, encrypted=True)
+
+    def sync(
+        self,
+        *,
+        list_only: bool = False,
+        force_relink: bool = False,
+        force_add: bool = False,
+        force_link: bool = False,
+    ) -> None:
+        if not list_only:
+            self.ui.section("Syncing dotfiles", emoji="📦")
+        else:
+            self.ui.section("Listing dotfiles", emoji="📦")
+
+        changed = 0
+        unchanged = 0
+
+        for repo_file in self.iter_repo_files():
+            relpath = repo_file.relative_to(self.path)
+            if self.is_ignored(relpath):
+                self.ui.debug(f"Ignored: {relpath.as_posix()}")
+                continue
+
+            if crypto.is_age_file(repo_file):
+                outcome = self.sync_one_encrypted(
+                    repo_file=repo_file,
+                    list_only=list_only,
+                )
+            else:
+                link_path = self.home / relpath
+                outcome = self.sync_one(
+                    repo_file=repo_file,
+                    link_path=link_path,
+                    list_only=list_only,
+                    force_relink=force_relink,
+                    force_add=force_add,
+                    force_link=force_link,
+                )
+            if outcome == SyncOutcome.OK:
+                unchanged += 1
+            elif outcome in (SyncOutcome.INSTALLED, SyncOutcome.REPLACED):
+                changed += 1
+
+        self.ui.summary(changed=changed, unchanged=unchanged)
+
+    def validate_addable(self, target: Path) -> None:
+        if target.is_symlink():
+            if fs.is_inside(target.resolve(), self.path):
+                raise AlreadyInRepoError(target)
+            raise InvalidTargetError(f"cannot add a symlink: {target}", target)
+        if not target.exists():
+            raise InvalidTargetError(f"file not found: {target}", target)
+        if not target.is_file():
+            raise InvalidTargetError(f"not a regular file: {target}", target)
+        if not fs.is_inside(target, self.home):
+            raise NotInHomeError(target, self.home)
+        if fs.is_inside(target, self.path):
+            raise InvalidTargetError(f"file is already inside the repository: {target}", target)
+
+    def iter_repo_files(self) -> Iterator[Path]:
+        """
+        Yield every regular file under ``self.path``, skipping ``.git``
+        and ``.decrypted``.
+        """
+        for p in sorted(self.path.rglob("*")):
+            if not p.is_file():
+                continue
+            parts = p.relative_to(self.path).parts
+            if ".git" in parts:
+                continue
+            if parts[0] == crypto.DECRYPTED_DIR:
+                continue
+            yield p
+
+    def is_ignored(self, relpath: Path) -> bool:
+        """
+        Match ``relpath`` (repo-relative) against the ignore patterns.
+
+        Patterns starting with ``/`` are anchored to the repo root and match
+        the full relative path. All other patterns match the filename only.
+        """
+        rel_str = "/" + relpath.as_posix()
+        for pattern in self.ignored:
+            match_target = rel_str if pattern.startswith("/") else relpath.name
+            if fnmatch.fnmatch(match_target, pattern):
+                return True
+        return False
+
+    def sync_one(
+        self,
+        *,
+        repo_file: Path,
+        link_path: Path,
+        list_only: bool,
+        force_relink: bool,
+        force_add: bool,
+        force_link: bool,
+    ) -> SyncOutcome:
+        if not (link_path.is_symlink() or link_path.exists()):
+            if list_only:
+                self.ui.missing(link_path)
+                return SyncOutcome.MISSING
+            fs.atomic_symlink(repo_file, link_path)
+            self.ui.installed(link_path)
+            return SyncOutcome.INSTALLED
+
+        if link_path.is_symlink():
+            link_target = link_path.resolve()
+            if link_target == repo_file:
+                self.ui.ok(link_path)
+                return SyncOutcome.OK
+            state = "valid" if link_target.exists() else "broken"
+            self.ui.conflict(link_path, target=link_target, reason=f"{state} link")
+            if list_only:
+                return SyncOutcome.CONFLICT
+            if not force_relink and not self.ui.ask_yesno("Overwrite existing link?", default=False):
+                return SyncOutcome.SKIPPED
+            fs.atomic_symlink(repo_file, link_path)
+            self.ui.replaced(link_path)
+            return SyncOutcome.REPLACED
+
+        self.ui.conflict(link_path, reason="file exists")
+        if list_only:
+            return SyncOutcome.CONFLICT
+        if force_add:
+            self.force_add(repo_file, link_path)
+            return SyncOutcome.REPLACED
+        if force_link:
+            self.force_link(repo_file, link_path)
+            return SyncOutcome.REPLACED
+        if self.ui.ask_yesno("Replace repository file?", default=False):
+            self.force_add(repo_file, link_path)
+            return SyncOutcome.REPLACED
+        if self.ui.ask_yesno("Replace local file?", default=False):
+            self.force_link(repo_file, link_path)
+            return SyncOutcome.REPLACED
+        return SyncOutcome.SKIPPED
+
+    def force_add(self, repo_file: Path, link_path: Path) -> None:
+        """
+        Promote the user's local file to become the new repo version.
+        """
+        self.ui.debug(f"Force-add: {link_path} -> {repo_file}")
+        fs.atomic_copy(link_path, repo_file)
+        fs.atomic_symlink(repo_file, link_path)
+        self.git_commit_safe(f"force-updated {repo_file.relative_to(self.path).as_posix()}")
+        self.ui.replaced(repo_file)
+
+    def force_link(self, repo_file: Path, link_path: Path) -> None:
+        """
+        Replace the user's local file with a symlink pointing at the repo.
+        """
+        self.ui.debug(f"Force-link: {link_path} -> {repo_file}")
+        fs.atomic_symlink(repo_file, link_path)
+        self.ui.replaced(link_path)
+
+    def sync_one_encrypted(
+        self,
+        *,
+        repo_file: Path,
+        list_only: bool,
+    ) -> SyncOutcome:
+        if self.age_keypair is None:
+            self.ui.warning(f"skipping encrypted file (no age key): {repo_file.name}")
+            return SyncOutcome.SKIPPED
+
+        decrypted_path = crypto.age_to_decrypted_path(self.path, repo_file)
+        home_path = crypto.age_to_home_path(self.path, self.home, repo_file)
+
+        if not decrypted_path.exists():
+            if list_only:
+                self.ui.missing(home_path, encrypted=True)
+                return SyncOutcome.MISSING
+            ciphertext = repo_file.read_bytes()
+            plaintext = crypto.age_decrypt(ciphertext, self.age_keypair.identity)
+            fs.atomic_write(decrypted_path, plaintext)
+            self.ensure_decrypted_gitignored()
+            fs.atomic_symlink(decrypted_path, home_path)
+            self.ui.installed(home_path, encrypted=True)
+            return SyncOutcome.INSTALLED
+
+        if not list_only:
+            # integrity check: has the user modified the decrypted copy?
+            ciphertext = repo_file.read_bytes()
+            repo_plaintext = crypto.age_decrypt(ciphertext, self.age_keypair.identity)
+            disk_plaintext = decrypted_path.read_bytes()
+
+            if crypto.content_hash(repo_plaintext) != crypto.content_hash(disk_plaintext):
+                new_ciphertext = crypto.age_encrypt(disk_plaintext, self.age_keypair.recipient)
+                fs.atomic_write(repo_file, new_ciphertext)
+                relpath = repo_file.relative_to(self.path)
+                self.git_commit_safe(f"re-encrypted {relpath.as_posix()}")
+                self.ui.replaced(home_path, encrypted=True)
+                return SyncOutcome.REPLACED
+
+        # ensure symlink is correct
+        if home_path.is_symlink() and home_path.resolve() == decrypted_path.resolve():
+            self.ui.ok(home_path, encrypted=True)
+            return SyncOutcome.OK
+
+        if list_only:
+            self.ui.missing(home_path, encrypted=True)
+            return SyncOutcome.MISSING
+
+        self.ensure_decrypted_gitignored()
+        fs.atomic_symlink(decrypted_path, home_path)
+        self.ui.installed(home_path, encrypted=True)
+        return SyncOutcome.INSTALLED
+
+    def ensure_decrypted_gitignored(self) -> None:
+        gitignore = self.path / ".gitignore"
+        marker = f"/{crypto.DECRYPTED_DIR}/"
+        if gitignore.is_file():
+            content = gitignore.read_text()
+            if marker in content:
+                return
+            if not content.endswith("\n"):
+                content += "\n"
+            content += f"{marker}\n"
+        else:
+            content = f"{marker}\n"
+        fs.atomic_write(gitignore, content.encode())
+
+    def rm_empty_folders(self, leaf: Path) -> None:
+        """
+        Iteratively delete empty directories up to ``self.path`` (exclusive).
+        """
+        while leaf != self.path and fs.is_inside(leaf, self.path):
+            try:
+                if any(leaf.iterdir()):
+                    return
+            except OSError:
+                return
+            if not self.ui.ask_yesno(f"Delete empty folder '{leaf}'?", default=True):
+                return
+            self.ui.debug(f"Deleting empty folder: {leaf}")
+            try:
+                leaf.rmdir()
+            except OSError as e:
+                self.ui.warning(f"Failed to delete {leaf}: {e}")
+                return
+            leaf = leaf.parent
+
+    def git_commit_safe(self, msg: str) -> None:
+        """
+        Commit all repo changes - non-fatal on failure.
+        """
+        if self.git is None:
+            return
+        try:
+            self.git.git.add(all=True)
+            self.git.git.commit(message=f"[dots] {msg}")
+        except GitError as e:
+            self.ui.warning(f"git commit failed (filesystem change was applied): {e}")

dots/ui.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+from rich.theme import Theme
+
+THEME = Theme(
+    {
+        "ok": "green",
+        "add": "bold green",
+        "replace": "cyan",
+        "missing": "red",
+        "conflict": "yellow",
+        "arrow": "dim",
+        "debug": "dim magenta",
+        "error": "bold red",
+        "meta": "dim",
+        "section": "bold",
+    }
+)
+
+
+def make_console(*, stderr: bool) -> Console:
+    return Console(theme=THEME, stderr=stderr, highlight=False)
+
+
+@dataclass
+class UI:
+    verbose: bool = False
+    out: Console = field(init=False, repr=False, default_factory=lambda: make_console(stderr=False))
+    err: Console = field(init=False, repr=False, default_factory=lambda: make_console(stderr=True))
+
+    # lower-level (free-form messages)
+
+    def debug(self, msg: str) -> None:
+        if self.verbose:
+            self.out.print(f"  [debug]•[/] [meta]{escape(msg)}[/]")
+
+    def info(self, msg: str) -> None:
+        self.out.print(escape(msg))
+
+    def notice(self, msg: str) -> None:
+        self.out.print(f"[bold]{escape(msg)}[/]")
+
+    def warning(self, msg: str) -> None:
+        self.err.print(f"  [conflict]![/] {escape(msg)}")
+
+    def error(self, msg: str) -> None:
+        self.err.print(f"[error]✗ {escape(msg)}[/]")
+
+    # semantic helpers
+
+    def ok(self, path: Path, *, encrypted: bool = False) -> None:
+        tag = " [meta](encrypted)[/]" if encrypted else ""
+        self.out.print(f"  [ok]✓[/] {escape(str(path))}{tag}")
+
+    def installed(self, path: Path, *, encrypted: bool = False) -> None:
+        tag = " [meta](encrypted)[/]" if encrypted else ""
+        self.out.print(f"  [add]+[/] [bold]{escape(str(path))}[/]{tag}")
+
+    def replaced(self, path: Path, *, encrypted: bool = False) -> None:
+        tag = " [meta](encrypted)[/]" if encrypted else ""
+        self.out.print(f"  [replace]↻[/] {escape(str(path))}{tag}")
+
+    def missing(self, path: Path, *, encrypted: bool = False) -> None:
+        extra = ", encrypted" if encrypted else ""
+        self.out.print(f"  [missing]✗[/] {escape(str(path))} [meta](missing{extra})[/]")
+
+    def removed(self, path: Path, *, encrypted: bool = False) -> None:
+        tag = " [meta](encrypted)[/]" if encrypted else ""
+        self.out.print(f"  [missing]-[/] {escape(str(path))}{tag}")
+
+    def conflict(self, path: Path, *, target: Path | None = None, reason: str = "") -> None:
+        parts = [f"  [conflict]![/] {escape(str(path))}"]
+        if target is not None:
+            parts.append(f" [arrow]→[/] [meta]{escape(str(target))}[/]")
+        if reason:
+            parts.append(f" [meta]({escape(reason)})[/]")
+        self.err.print("".join(parts))
+
+    # formatting helpers
+
+    def section(self, title: str, *, emoji: str = "") -> None:
+        prefix = f"{emoji} " if emoji else ""
+        self.out.print(f"\n{prefix}[section]{escape(title)}[/]\n")
+
+    def summary(self, *, changed: int, unchanged: int) -> None:
+        if changed == 0:
+            self.out.print(f"\n[meta]{unchanged} unchanged[/]")
+            return
+        self.out.print(f"\n🎉 [bold]{changed}[/] changed, [meta]{unchanged} unchanged[/]")
+
+    # prompts
+
+    def ask_yesno(self, prompt: str, *, default: bool = False) -> bool:
+        if not sys.stdin.isatty():
+            return default
+        return typer.confirm(prompt, default=default)

dotsman-1.0.0.dist-info/METADATA

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: dotsman
+Version: 1.0.0
+Summary: Configuration files management tool
+Project-URL: Repository, https://github.com/mdeous/dots
+Author-email: Mathieu Deous <mat.deous@gmail.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: gitpython>=3.1.46
+Requires-Dist: pyrage>=1.3.0
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.24.1
+Description-Content-Type: text/markdown
+
+# dots
+
+![Python](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fmdeous%2Fdots%2Fmaster%2Fpyproject.toml)
+![License](https://img.shields.io/github/license/mdeous/dots)
+[![CI](https://github.com/mdeous/dots/actions/workflows/ci.yml/badge.svg)](https://github.com/mdeous/dots/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/mdeous/dots/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/mdeous/dots/actions/workflows/github-code-scanning/codeql)
+
+Yet another dotfiles management tool.
+
+## :sparkles: Features
+
+- :link: Dotfiles stored in a central folder and symlinked to their real location
+- :repeat: Automatic git versioning on every change
+- :computer: Per-machine configuration via hostname-based config sections
+- :warning: Conflict detection and resolution during sync
+- :lock: Encryption for sensitive files
+
+## :clipboard: Requirements
+
+- Python 3.12+
+- git
+
+## :package: Installation
+
+Clone the repository and install with [uv](https://docs.astral.sh/uv/):
+
+```bash
+git clone https://github.com/mdeous/dots.git
+cd dots
+uv sync
+```
+
+Or with pip:
+
+```bash
+git clone https://github.com/mdeous/dots.git
+cd dots
+pip install .
+```
+
+## :gear: Configuration
+
+The configuration file should be located at `~/.dots.conf`.
+
+Settings are organized in sections named after the machine's hostname. The `[DEFAULT]` section provides fallback values used when no hostname-specific section exists.
+
+### Available settings
+
+| Key             | Description                                                               | Default  |
+| --------------- | ------------------------------------------------------------------------- | -------- |
+| `repo_dir`      | Path to the dotfiles repository                                           | `~/dots` |
+| `age_identity`  | Path to an [age](https://age-encryption.org) identity file for encryption | _none_   |
+| `ignored_files` | Comma-separated list of glob patterns to skip during sync                 | _none_   |
+
+### Example
+
+```ini
+[DEFAULT]
+repo_dir = ~/dots
+
+[work-laptop]
+repo_dir = ~/dotfiles
+ignored_files = .bashrc, .config/personal/*
+
+[home-desktop]
+age_identity = ~/.age/dots.key
+```
+
+## :rocket: Usage
+
+### Global options
+
+```text
+dots [--config PATH] [--verbose] [--version] COMMAND
+```
+
+| Option      | Short | Description                                   |
+| ----------- | ----- | --------------------------------------------- |
+| `--config`  | `-c`  | Path to config file (default: `~/.dots.conf`) |
+| `--verbose` | `-v`  | Display debug information                     |
+| `--version` | `-V`  | Display version and exit                      |
+
+### `dots add <file>`
+
+Add a file to the repository. The file is copied into the repo and replaced with a symlink.
+
+```bash
+dots add ~/.bashrc
+dots add ~/.config/git/config
+```
+
+| Option      | Short | Description                                      |
+| ----------- | ----- | ------------------------------------------------ |
+| `--encrypt` | `-e`  | Encrypt the file with age before storing in repo |
+
+When `--encrypt` is used, the file is stored as a `.age` file in the repo (encrypted at rest), with a decrypted working copy in a gitignored `.decrypted/` directory. The symlink points to the decrypted copy so the file remains usable. Requires `age_identity` to be set in the config.
+
+### `dots remove <file>`
+
+Remove a file from the repository. The symlink is replaced with the original file.
+
+```bash
+dots remove ~/.bashrc
+```
+
+### `dots list`
+
+List all files in the repository and their sync status.
+
+```bash
+dots list
+```
+
+### `dots sync`
+
+Synchronize the repository with the filesystem. Creates missing symlinks and detects conflicts.
+
+```bash
+dots sync
+```
+
+| Option           | Short | Description                                    |
+| ---------------- | ----- | ---------------------------------------------- |
+| `--force-relink` | `-r`  | Overwrite links that point to the wrong target |
+| `--force-add`    | `-a`  | Overwrite the repo version with the local file |
+| `--force-link`   | `-l`  | Overwrite the local file with the repo version |
+
+`--force-add` and `--force-link` are mutually exclusive. Without force flags, `dots` prompts interactively when conflicts are found.
+
+## :lock: Encryption
+
+Sensitive dotfiles can be encrypted at rest using [age](https://age-encryption.org). Encrypted files are safe to push to public repositories.
+
+### Setup
+
+1. Generate an age identity:
+
+   ```bash
+   age-keygen -o ~/.age/dots.key
+   ```
+
+2. Add the identity path to your config (`~/.dots.conf`):
+
+   ```ini
+   [DEFAULT]
+   age_identity = ~/.age/dots.key
+   ```
+
+3. Add files with encryption:
+
+   ```bash
+   dots add --encrypt ~/.config/secrets.env
+   ```
+
+### How it works
+
+- Encrypted files are stored in the repo with a `.age` extension (e.g., `secrets.env.age`)
+- Decrypted working copies live in a gitignored `.decrypted/` directory inside the repo
+- Symlinks point to the decrypted copies, so files are usable as normal
+- `dots sync` detects changes to decrypted files and re-encrypts them automatically
+- On a new machine, `dots sync` decrypts all `.age` files and creates symlinks
+- If the age identity is not configured, encrypted files are skipped with a warning during sync
+
+## :scroll: License
+
+BSD 3-Clause. See [LICENSE](LICENSE) for details.

dotsman-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+dots/__init__.py,sha256=lzGFsymf0DtA_1oAZcPbeQ557iY-1BRkekhfA2qaFh8,18
+dots/cli.py,sha256=nJDTzy5yuO_EUMYKhiJmRc3izKoZ39VttK1-7CfSA4Q,4217
+dots/crypto.py,sha256=oHPEu_X_IiQv4X8Um3hEi5FqHWCo68jU4-J-ZPLuo4Y,2888
+dots/errors.py,sha256=WpNSiB5SlQbBxMH8k8o7vgn9x6KUxCnjG8JeB5x4_qc,1777
+dots/fs.py,sha256=aH297gyvo0OxuZ5a7u82x5Uu-juYDUJvVkYM8NP_Lcs,3229
+dots/repo.py,sha256=wvH1cJ4ikHCJfSkdaljwGix_ANlUx0ZrQGFmNlHJw7Q,18966
+dots/ui.py,sha256=K9wwx57yYsxzHUA8r5Y_uEzH5JsFLOYOfyvA5zZoQMI,3501
+dotsman-1.0.0.dist-info/METADATA,sha256=wS0lN_1dt-CSoOal6INVTfi71PF2kNN_qKrY36lToRY,5799
+dotsman-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+dotsman-1.0.0.dist-info/entry_points.txt,sha256=NzIsHc5V1yvSAgw1O1ROrfjpgQOn5DYojoYJtfVOqQ0,39
+dotsman-1.0.0.dist-info/licenses/LICENSE,sha256=HA9_W45keV-IlxU3Lhrgf01OFERlx0GbFSS3UU053mQ,1468
+dotsman-1.0.0.dist-info/RECORD,,

dotsman-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

dotsman-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dots = dots.cli:main

dotsman-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2017 Mathieu Deous
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+* Neither the name of Mathieu Deous nor the names of the project contributors
+  may be used to endorse or promote products derived from this software
+  without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL MATHIEU DEOUS BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.