dotsync-py 0.1.0__tar.gz

dotsync_py-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# dotsync
+.brew-pending

dotsync_py-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scott Sheffield
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dotsync_py-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: dotsync-py
+Version: 0.1.0
+Summary: Fleet-style dotfiles manager with push cascading and status dashboard
+Project-URL: Homepage, https://github.com/scott-shef/dotsync
+Project-URL: Repository, https://github.com/scott-shef/dotsync
+Project-URL: Issues, https://github.com/scott-shef/dotsync/issues
+Author-email: Scott Sheffield <scott@shef.us>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,dotfiles,fleet,sync
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli-w>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# dotsync
+
+Fleet-style dotfiles manager with push cascading and status dashboard.
+
+## What makes it different
+
+- **Fleet dashboard** — see the sync status of all your machines at once
+- **Push cascading** — push from one machine, auto-pull on all others via SSH
+- **New-machine bootstrap** — SSH key setup, GitHub key, clone, link, brew
+- **Simple config** — one TOML file, no templating engine
+
+## Install
+
+```bash
+pipx install dotsync
+```
+
+## Quick start
+
+```bash
+# Bootstrap a new machine (generates SSH key, clones dotfiles, links, brews)
+dotsync setup
+
+# See fleet status
+dotsync status
+
+# Push changes to all machines
+dotsync push
+
+# Pull latest on this machine
+dotsync pull
+
+# Manage fleet
+dotsync add work-laptop --ssh-alias work
+dotsync remove old-desktop
+
+# Retry failed brew packages
+dotsync pending
+```
+
+## Config
+
+dotsync reads `~/.dotfiles/.dotsync.toml`:
+
+```toml
+[dotsync]
+repo = "git@github.com:you/dotfiles.git"
+dotfiles_path = "~/.dotfiles"
+
+[links]
+".zshrc" = ".zshrc"
+".zprofile" = ".zprofile"
+".gitconfig" = ".gitconfig"
+"ssh/config" = ".ssh/config"
+
+[brew]
+brewfile = "Brewfile"
+pending_file = ".brew-pending"
+
+[[machines]]
+name = "work-mini"
+ssh_alias = "work-mini"
+
+[[machines]]
+name = "home-mini"
+ssh_alias = "home-mini"
+```
+
+## Status
+
+Alpha — core scaffolding complete, implementation in progress.
+
+## License
+
+MIT

dotsync_py-0.1.0/README.md

@@ -0,0 +1,75 @@
+# dotsync
+
+Fleet-style dotfiles manager with push cascading and status dashboard.
+
+## What makes it different
+
+- **Fleet dashboard** — see the sync status of all your machines at once
+- **Push cascading** — push from one machine, auto-pull on all others via SSH
+- **New-machine bootstrap** — SSH key setup, GitHub key, clone, link, brew
+- **Simple config** — one TOML file, no templating engine
+
+## Install
+
+```bash
+pipx install dotsync
+```
+
+## Quick start
+
+```bash
+# Bootstrap a new machine (generates SSH key, clones dotfiles, links, brews)
+dotsync setup
+
+# See fleet status
+dotsync status
+
+# Push changes to all machines
+dotsync push
+
+# Pull latest on this machine
+dotsync pull
+
+# Manage fleet
+dotsync add work-laptop --ssh-alias work
+dotsync remove old-desktop
+
+# Retry failed brew packages
+dotsync pending
+```
+
+## Config
+
+dotsync reads `~/.dotfiles/.dotsync.toml`:
+
+```toml
+[dotsync]
+repo = "git@github.com:you/dotfiles.git"
+dotfiles_path = "~/.dotfiles"
+
+[links]
+".zshrc" = ".zshrc"
+".zprofile" = ".zprofile"
+".gitconfig" = ".gitconfig"
+"ssh/config" = ".ssh/config"
+
+[brew]
+brewfile = "Brewfile"
+pending_file = ".brew-pending"
+
+[[machines]]
+name = "work-mini"
+ssh_alias = "work-mini"
+
+[[machines]]
+name = "home-mini"
+ssh_alias = "home-mini"
+```
+
+## Status
+
+Alpha — core scaffolding complete, implementation in progress.
+
+## License
+
+MIT

dotsync_py-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dotsync-py"
+version = "0.1.0"
+description = "Fleet-style dotfiles manager with push cascading and status dashboard"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "Scott Sheffield", email = "scott@shef.us" },
+]
+keywords = ["dotfiles", "sync", "fleet", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "click>=8.1",
+    "rich>=13.0",
+    "tomli-w>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/scott-shef/dotsync"
+Repository = "https://github.com/scott-shef/dotsync"
+Issues = "https://github.com/scott-shef/dotsync/issues"
+
+[project.scripts]
+dotsync = "dotsync.cli:cli"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dotsync"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-mock>=3.12",
+]

dotsync_py-0.1.0/src/dotsync/__init__.py

@@ -0,0 +1,3 @@
+"""dotsync — Fleet-style dotfiles manager."""
+
+__version__ = "0.1.0"

dotsync_py-0.1.0/src/dotsync/brewfile.py

@@ -0,0 +1,74 @@
+"""Brew bundle with failure capture and pending package management."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from rich.console import Console
+
+from dotsync.config import load_config
+
+
+def capture_failures(output: str, dotfiles_path: Path) -> None:
+    """Parse brew bundle output and save failed packages to .brew-pending."""
+    config = load_config()
+    pending_path = dotfiles_path / config.pending_file
+
+    # Extract failed package names from brew bundle output
+    # Typical failure line: "Installing <name> has failed!"
+    # or "Homebrew Bundle failed! N Brewfile dependencies failed to install."
+    failed = []
+    for line in output.splitlines():
+        line = line.strip()
+        if "has failed" in line.lower():
+            # Try to extract the package name
+            parts = line.split()
+            if len(parts) >= 2:
+                failed.append(parts[1])
+
+    if failed:
+        pending_path.write_text("\n".join(failed) + "\n")
+
+
+def show_pending() -> None:
+    """Show pending (failed) brew packages and offer to install."""
+    console = Console()
+    config = load_config()
+    pending_path = config.dotfiles_dir / config.pending_file
+
+    if not pending_path.exists():
+        console.print("[green]No pending brew packages.[/green]")
+        return
+
+    packages = [p.strip() for p in pending_path.read_text().splitlines() if p.strip()]
+    if not packages:
+        console.print("[green]No pending brew packages.[/green]")
+        pending_path.unlink()
+        return
+
+    console.print(f"[yellow]Pending brew packages ({len(packages)}):[/yellow]")
+    for pkg in packages:
+        console.print(f"  - {pkg}")
+
+    from rich.prompt import Confirm
+    if Confirm.ask("\nAttempt to install now?", default=True):
+        still_failed = []
+        for pkg in packages:
+            console.print(f"  Installing {pkg}...", end=" ")
+            result = subprocess.run(
+                ["brew", "install", pkg],
+                capture_output=True, text=True, check=False,
+            )
+            if result.returncode == 0:
+                console.print("[green]ok[/green]")
+            else:
+                console.print("[red]failed[/red]")
+                still_failed.append(pkg)
+
+        if still_failed:
+            pending_path.write_text("\n".join(still_failed) + "\n")
+            console.print(f"\n[yellow]{len(still_failed)} packages still failing.[/yellow]")
+        else:
+            pending_path.unlink()
+            console.print("\n[green]All pending packages installed![/green]")

dotsync_py-0.1.0/src/dotsync/cli.py

@@ -0,0 +1,74 @@
+"""Click CLI for dotsync."""
+
+import click
+
+from dotsync import __version__
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="dotsync")
+def cli():
+    """Fleet-style dotfiles manager.
+
+    Sync dotfiles across machines with push cascading,
+    fleet status dashboard, and new-machine bootstrap.
+    """
+
+
+@cli.command()
+def status():
+    """Show fleet dashboard — status of all machines."""
+    from dotsync.sync import fleet_status
+
+    fleet_status()
+
+
+@cli.command()
+def push():
+    """Auto-commit, push, and cascade to fleet."""
+    from dotsync.sync import push_dotfiles
+
+    push_dotfiles()
+
+
+@cli.command()
+def pull():
+    """Pull latest changes and run setup locally."""
+    from dotsync.sync import pull_dotfiles
+
+    pull_dotfiles()
+
+
+@cli.command()
+def setup():
+    """Bootstrap this machine (SSH key, GitHub, clone, link, brew)."""
+    from dotsync.setup_machine import bootstrap
+
+    bootstrap()
+
+
+@cli.command()
+@click.argument("name")
+@click.option("--ssh-alias", default=None, help="SSH alias for the machine (defaults to name).")
+def add(name: str, ssh_alias: str | None):
+    """Add a machine to the fleet config."""
+    from dotsync.config import add_machine
+
+    add_machine(name, ssh_alias=ssh_alias or name)
+
+
+@cli.command()
+@click.argument("name")
+def remove(name: str):
+    """Remove a machine from the fleet config."""
+    from dotsync.config import remove_machine
+
+    remove_machine(name)
+
+
+@cli.command()
+def pending():
+    """Show or install failed brew packages."""
+    from dotsync.brewfile import show_pending
+
+    show_pending()

dotsync_py-0.1.0/src/dotsync/config.py

@@ -0,0 +1,128 @@
+"""Load and save ~/.dotfiles/.dotsync.toml config."""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import tomli_w
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+
+DEFAULT_CONFIG_PATH = Path.home() / ".dotfiles" / ".dotsync.toml"
+
+
+@dataclass
+class Machine:
+    name: str
+    ssh_alias: str
+
+
+@dataclass
+class Config:
+    repo: str = ""
+    dotfiles_path: str = "~/.dotfiles"
+    links: dict[str, str] = field(default_factory=dict)
+    brewfile: str = "Brewfile"
+    pending_file: str = ".brew-pending"
+    machines: list[Machine] = field(default_factory=list)
+
+    @property
+    def dotfiles_dir(self) -> Path:
+        return Path(self.dotfiles_path).expanduser()
+
+    @property
+    def config_path(self) -> Path:
+        return self.dotfiles_dir / ".dotsync.toml"
+
+
+def load_config(path: Path | None = None) -> Config:
+    """Load config from TOML file. Returns defaults if file doesn't exist."""
+    config_path = path or DEFAULT_CONFIG_PATH
+    if not config_path.exists():
+        return Config()
+
+    with open(config_path, "rb") as f:
+        data = tomllib.load(f)
+
+    ds = data.get("dotsync", {})
+    brew = data.get("brew", {})
+    machines_raw = data.get("machines", [])
+
+    machines = [
+        Machine(name=m["name"], ssh_alias=m.get("ssh_alias", m["name"]))
+        for m in machines_raw
+    ]
+
+    return Config(
+        repo=ds.get("repo", ""),
+        dotfiles_path=ds.get("dotfiles_path", "~/.dotfiles"),
+        links=data.get("links", {}),
+        brewfile=brew.get("brewfile", "Brewfile"),
+        pending_file=brew.get("pending_file", ".brew-pending"),
+        machines=machines,
+    )
+
+
+def save_config(config: Config, path: Path | None = None) -> None:
+    """Save config to TOML file."""
+    config_path = path or config.config_path
+
+    data: dict = {
+        "dotsync": {
+            "repo": config.repo,
+            "dotfiles_path": config.dotfiles_path,
+        },
+        "links": config.links,
+        "brew": {
+            "brewfile": config.brewfile,
+            "pending_file": config.pending_file,
+        },
+        "machines": [
+            {"name": m.name, "ssh_alias": m.ssh_alias}
+            for m in config.machines
+        ],
+    }
+
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(config_path, "wb") as f:
+        tomli_w.dump(data, f)
+
+
+def add_machine(name: str, ssh_alias: str | None = None) -> None:
+    """Add a machine to the config."""
+    from rich.console import Console
+
+    console = Console()
+    config = load_config()
+
+    if any(m.name == name for m in config.machines):
+        console.print(f"[yellow]Machine '{name}' already exists in config.[/yellow]")
+        return
+
+    config.machines.append(Machine(name=name, ssh_alias=ssh_alias or name))
+    save_config(config)
+    console.print(f"[green]Added machine '{name}' (ssh: {ssh_alias or name})[/green]")
+
+
+def remove_machine(name: str) -> None:
+    """Remove a machine from the config."""
+    from rich.console import Console
+
+    console = Console()
+    config = load_config()
+
+    original_count = len(config.machines)
+    config.machines = [m for m in config.machines if m.name != name]
+
+    if len(config.machines) == original_count:
+        console.print(f"[yellow]Machine '{name}' not found in config.[/yellow]")
+        return
+
+    save_config(config)
+    console.print(f"[green]Removed machine '{name}'[/green]")

dotsync_py-0.1.0/src/dotsync/linker.py

@@ -0,0 +1,49 @@
+"""Symlink dotfiles from the repo to ~."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from rich.console import Console
+
+from dotsync.config import load_config
+
+
+def link_dotfiles() -> None:
+    """Create symlinks for all configured links."""
+    console = Console()
+    config = load_config()
+
+    if not config.links:
+        console.print("[yellow]No links configured in .dotsync.toml.[/yellow]")
+        return
+
+    dotfiles_dir = config.dotfiles_dir
+    home = Path.home()
+
+    for source_rel, target_rel in config.links.items():
+        source = dotfiles_dir / source_rel
+        target = home / target_rel
+
+        if not source.exists():
+            console.print(f"  [red]skip[/red] {source_rel} — source not found")
+            continue
+
+        # Create parent directory if needed
+        target.parent.mkdir(parents=True, exist_ok=True)
+
+        if target.is_symlink():
+            if target.resolve() == source.resolve():
+                console.print(f"  [dim]ok[/dim]   {target_rel} → {source_rel}")
+                continue
+            # Symlink exists but points elsewhere — replace it
+            target.unlink()
+
+        if target.exists():
+            # Real file exists — back it up
+            backup = target.with_suffix(target.suffix + ".dotsync-backup")
+            console.print(f"  [yellow]backup[/yellow] {target_rel} → {backup.name}")
+            target.rename(backup)
+
+        target.symlink_to(source)
+        console.print(f"  [green]link[/green]  {target_rel} → {source_rel}")

dotsync_py-0.1.0/src/dotsync/setup_machine.py

@@ -0,0 +1,134 @@
+"""New-machine bootstrap: SSH key, GitHub, clone, link, brew."""
+
+from __future__ import annotations
+
+import platform
+import subprocess
+import webbrowser
+from pathlib import Path
+
+from rich.console import Console
+from rich.prompt import Confirm
+
+from dotsync.config import load_config
+from dotsync.linker import link_dotfiles
+
+
+def _run(cmd: list[str], check: bool = True, **kwargs) -> subprocess.CompletedProcess:
+    return subprocess.run(cmd, capture_output=True, text=True, check=check, **kwargs)
+
+
+def _generate_ssh_key(console: Console) -> Path:
+    """Generate an ED25519 SSH key if one doesn't exist."""
+    key_path = Path.home() / ".ssh" / "id_ed25519"
+    if key_path.exists():
+        console.print(f"[dim]SSH key already exists at {key_path}[/dim]")
+        return key_path
+
+    console.print("Generating SSH key...")
+    key_path.parent.mkdir(mode=0o700, exist_ok=True)
+    hostname = platform.node()
+    _run([
+        "ssh-keygen", "-t", "ed25519",
+        "-f", str(key_path),
+        "-N", "",  # no passphrase
+        "-C", f"dotsync@{hostname}",
+    ])
+    console.print(f"[green]Created {key_path}[/green]")
+    return key_path
+
+
+def _add_key_to_github(console: Console, key_path: Path) -> None:
+    """Show the public key and open GitHub settings to add it."""
+    pub_path = key_path.with_suffix(".pub")
+    pub_key = pub_path.read_text().strip()
+
+    console.print("\n[bold]Add this SSH key to GitHub:[/bold]")
+    console.print(f"\n  {pub_key}\n")
+
+    if Confirm.ask("Open GitHub SSH settings in browser?", default=True):
+        webbrowser.open("https://github.com/settings/ssh/new")
+        console.print("[dim]Waiting for you to add the key... Press Enter when done.[/dim]")
+        input()
+
+
+def _clone_dotfiles(console: Console, repo: str, dotfiles_path: Path) -> None:
+    """Clone the dotfiles repo if the directory doesn't exist."""
+    if dotfiles_path.exists():
+        console.print(f"[dim]Dotfiles directory already exists at {dotfiles_path}[/dim]")
+        return
+
+    console.print(f"Cloning {repo}...")
+    result = _run(
+        ["git", "clone", repo, str(dotfiles_path)],
+        check=False,
+    )
+    if result.returncode != 0:
+        console.print(f"[red]Clone failed:[/red] {result.stderr.strip()}")
+        console.print("[yellow]Make sure you've added your SSH key to GitHub.[/yellow]")
+        raise SystemExit(1)
+    console.print(f"[green]Cloned to {dotfiles_path}[/green]")
+
+
+def _run_brew_bundle(console: Console, dotfiles_path: Path, brewfile: str) -> None:
+    """Run brew bundle if on macOS and Brewfile exists."""
+    if platform.system() != "Darwin":
+        console.print("[dim]Skipping brew (not macOS).[/dim]")
+        return
+
+    brewfile_path = dotfiles_path / brewfile
+    if not brewfile_path.exists():
+        console.print(f"[dim]No {brewfile} found, skipping brew.[/dim]")
+        return
+
+    console.print("Running brew bundle...")
+    result = _run(
+        ["brew", "bundle", "--file", str(brewfile_path)],
+        check=False,
+    )
+    if result.returncode != 0:
+        console.print("[yellow]Some brew packages failed. Run 'dotsync pending' to retry.[/yellow]")
+        # Capture failed packages
+        from dotsync.brewfile import capture_failures
+        capture_failures(result.stderr + result.stdout, dotfiles_path)
+    else:
+        console.print("[green]Brew bundle complete.[/green]")
+
+
+def bootstrap() -> None:
+    """Full new-machine bootstrap flow."""
+    console = Console()
+    config = load_config()
+
+    console.print("[bold]dotsync setup — bootstrapping this machine[/bold]\n")
+
+    # Step 1: SSH key
+    key_path = _generate_ssh_key(console)
+
+    # Step 2: GitHub key
+    _add_key_to_github(console, key_path)
+
+    # Step 3: Clone dotfiles
+    if config.repo:
+        dotfiles_path = config.dotfiles_dir
+        _clone_dotfiles(console, config.repo, dotfiles_path)
+    else:
+        console.print("[yellow]No repo configured in .dotsync.toml. Skipping clone.[/yellow]")
+        console.print("[dim]Set dotsync.repo in your config after cloning manually.[/dim]")
+        return
+
+    # Step 4: Symlink dotfiles
+    console.print("\nLinking dotfiles...")
+    link_dotfiles()
+
+    # Step 5: Brew bundle
+    _run_brew_bundle(console, config.dotfiles_dir, config.brewfile)
+
+    # Step 6: Add this machine to config
+    hostname = platform.node().split(".")[0].lower()
+    if not any(m.name == hostname for m in config.machines):
+        if Confirm.ask(f"\nAdd this machine ('{hostname}') to fleet config?", default=True):
+            from dotsync.config import add_machine
+            add_machine(hostname)
+
+    console.print("\n[bold green]Setup complete![/bold green]")

dotsync_py-0.1.0/src/dotsync/ssh.py

@@ -0,0 +1,21 @@
+"""SSH key generation and remote command execution."""
+
+from __future__ import annotations
+
+import subprocess
+
+
+def run_remote(host: str, command: str, timeout: int = 10) -> subprocess.CompletedProcess:
+    """Run a command on a remote machine via SSH."""
+    return subprocess.run(
+        ["ssh", "-o", f"ConnectTimeout={timeout}", "-o", "BatchMode=yes", host, command],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def is_reachable(host: str, timeout: int = 3) -> bool:
+    """Check if a host is reachable via SSH."""
+    result = run_remote(host, "echo ok", timeout=timeout)
+    return result.returncode == 0

dotsync_py-0.1.0/src/dotsync/sync.py

@@ -0,0 +1,147 @@
+"""Push, pull, cascade, and fleet status dashboard."""
+
+from __future__ import annotations
+
+import subprocess
+
+from rich.console import Console
+from rich.table import Table
+
+from dotsync.config import load_config
+
+
+def _run(cmd: list[str], cwd: str | None = None, check: bool = True) -> subprocess.CompletedProcess:
+    """Run a subprocess command and return the result."""
+    return subprocess.run(cmd, cwd=cwd, capture_output=True, text=True, check=check)
+
+
+def _git(args: list[str], cwd: str | None = None) -> subprocess.CompletedProcess:
+    """Run a git command in the dotfiles directory."""
+    config = load_config()
+    return _run(["git", *args], cwd=cwd or str(config.dotfiles_dir))
+
+
+def _get_changed_files(cwd: str) -> list[str]:
+    """Get list of changed files (staged + unstaged + untracked)."""
+    result = _run(["git", "status", "--porcelain"], cwd=cwd, check=False)
+    if result.returncode != 0:
+        return []
+    return [
+        line[3:].strip()
+        for line in result.stdout.strip().splitlines()
+        if line.strip()
+    ]
+
+
+def _auto_commit(cwd: str) -> bool:
+    """Auto-commit changes with a generated message. Returns True if a commit was made."""
+    changed = _get_changed_files(cwd)
+    if not changed:
+        return False
+
+    # Stage everything
+    _run(["git", "add", "-A"], cwd=cwd)
+
+    # Generate commit message from changed filenames
+    if len(changed) <= 5:
+        files_desc = ", ".join(changed)
+    else:
+        files_desc = ", ".join(changed[:4]) + f" +{len(changed) - 4} more"
+
+    message = f"update {files_desc}"
+    _run(["git", "commit", "-m", message], cwd=cwd)
+    return True
+
+
+def fleet_status() -> None:
+    """Show fleet dashboard with status of all machines."""
+    console = Console()
+    config = load_config()
+
+    if not config.machines:
+        console.print("[yellow]No machines configured. Run 'dotsync add <name>' to add one.[/yellow]")
+        return
+
+    table = Table(title="dotsync fleet status")
+    table.add_column("Machine", style="cyan")
+    table.add_column("SSH Alias", style="dim")
+    table.add_column("Reachable", justify="center")
+    table.add_column("Git Status", style="yellow")
+
+    for machine in config.machines:
+        # Check if machine is reachable via SSH
+        result = _run(
+            ["ssh", "-o", "ConnectTimeout=3", "-o", "BatchMode=yes",
+             machine.ssh_alias, "echo ok"],
+            check=False,
+        )
+        reachable = "[green]yes[/green]" if result.returncode == 0 else "[red]no[/red]"
+
+        # Try to get git status on remote
+        git_status = "—"
+        if result.returncode == 0:
+            gs = _run(
+                ["ssh", "-o", "ConnectTimeout=3", machine.ssh_alias,
+                 f"cd {config.dotfiles_path} && git status --porcelain 2>/dev/null | wc -l"],
+                check=False,
+            )
+            if gs.returncode == 0:
+                count = gs.stdout.strip()
+                git_status = "clean" if count == "0" else f"{count} changed"
+
+        table.add_row(machine.name, machine.ssh_alias, reachable, git_status)
+
+    console.print(table)
+
+
+def push_dotfiles() -> None:
+    """Auto-commit local changes, push to remote, then cascade pull to fleet."""
+    console = Console()
+    config = load_config()
+    cwd = str(config.dotfiles_dir)
+
+    # Auto-commit
+    if _auto_commit(cwd):
+        console.print("[green]Committed local changes.[/green]")
+    else:
+        console.print("[dim]No local changes to commit.[/dim]")
+
+    # Push to remote
+    console.print("Pushing to remote...")
+    result = _run(["git", "push"], cwd=cwd, check=False)
+    if result.returncode != 0:
+        console.print(f"[red]Push failed:[/red] {result.stderr.strip()}")
+        return
+    console.print("[green]Pushed.[/green]")
+
+    # Cascade to fleet
+    if not config.machines:
+        return
+
+    console.print("\nCascading to fleet...")
+    for machine in config.machines:
+        console.print(f"  {machine.name}...", end=" ")
+        r = _run(
+            ["ssh", "-o", "ConnectTimeout=5", machine.ssh_alias,
+             f"cd {config.dotfiles_path} && git pull --ff-only 2>&1"],
+            check=False,
+        )
+        if r.returncode == 0:
+            console.print("[green]ok[/green]")
+        else:
+            console.print(f"[red]failed[/red] — {r.stderr.strip() or r.stdout.strip()}")
+
+
+def pull_dotfiles() -> None:
+    """Pull latest changes and report."""
+    console = Console()
+    config = load_config()
+    cwd = str(config.dotfiles_dir)
+
+    console.print("Pulling latest changes...")
+    result = _run(["git", "pull", "--ff-only"], cwd=cwd, check=False)
+    if result.returncode != 0:
+        console.print(f"[red]Pull failed:[/red] {result.stderr.strip()}")
+        return
+
+    console.print(f"[green]{result.stdout.strip()}[/green]")

dotsync_py-0.1.0/tests/conftest.py

@@ -0,0 +1,29 @@
+"""Common test fixtures for dotsync."""
+
+import pytest
+
+from dotsync.config import Config, Machine
+
+
+@pytest.fixture
+def sample_config(tmp_path):
+    """A Config pointing at a temp directory with sample machines."""
+    dotfiles = tmp_path / "dotfiles"
+    dotfiles.mkdir()
+    return Config(
+        repo="git@github.com:test/dotfiles.git",
+        dotfiles_path=str(dotfiles),
+        links={".zshrc": ".zshrc", ".gitconfig": ".gitconfig"},
+        machines=[
+            Machine(name="work-mini", ssh_alias="work-mini"),
+            Machine(name="home-mini", ssh_alias="home-mini"),
+        ],
+    )
+
+
+@pytest.fixture
+def empty_config(tmp_path):
+    """A Config with no machines configured."""
+    dotfiles = tmp_path / "dotfiles"
+    dotfiles.mkdir()
+    return Config(dotfiles_path=str(dotfiles))

dotsync_py-0.1.0/tests/test_cli.py

@@ -0,0 +1,61 @@
+"""Test that the CLI loads and --help works for each command."""
+
+from click.testing import CliRunner
+
+from dotsync.cli import cli
+
+
+runner = CliRunner()
+
+
+def test_cli_help():
+    result = runner.invoke(cli, ["--help"])
+    assert result.exit_code == 0
+    assert "Fleet-style dotfiles manager" in result.output
+
+
+def test_cli_version():
+    result = runner.invoke(cli, ["--version"])
+    assert result.exit_code == 0
+    assert "0.1.0" in result.output
+
+
+def test_status_help():
+    result = runner.invoke(cli, ["status", "--help"])
+    assert result.exit_code == 0
+    assert "fleet dashboard" in result.output.lower()
+
+
+def test_push_help():
+    result = runner.invoke(cli, ["push", "--help"])
+    assert result.exit_code == 0
+    assert "cascade" in result.output.lower()
+
+
+def test_pull_help():
+    result = runner.invoke(cli, ["pull", "--help"])
+    assert result.exit_code == 0
+
+
+def test_setup_help():
+    result = runner.invoke(cli, ["setup", "--help"])
+    assert result.exit_code == 0
+    assert "bootstrap" in result.output.lower()
+
+
+def test_add_help():
+    result = runner.invoke(cli, ["add", "--help"])
+    assert result.exit_code == 0
+    assert "machine" in result.output.lower()
+
+
+def test_remove_help():
+    result = runner.invoke(cli, ["remove", "--help"])
+    assert result.exit_code == 0
+    assert "machine" in result.output.lower()
+
+
+def test_pending_help():
+    result = runner.invoke(cli, ["pending", "--help"])
+    assert result.exit_code == 0
+    assert "brew" in result.output.lower()

dotsync_py-0.1.0/tests/test_config.py

@@ -0,0 +1,43 @@
+"""Test config loading and saving."""
+
+from dotsync.config import Config, Machine, load_config, save_config
+
+
+def test_save_and_load_roundtrip(tmp_path):
+    config_path = tmp_path / ".dotsync.toml"
+
+    original = Config(
+        repo="git@github.com:user/dots.git",
+        dotfiles_path=str(tmp_path),
+        links={".zshrc": ".zshrc"},
+        machines=[Machine(name="test-box", ssh_alias="test-box")],
+    )
+
+    save_config(original, path=config_path)
+    assert config_path.exists()
+
+    loaded = load_config(path=config_path)
+    assert loaded.repo == original.repo
+    assert loaded.links == original.links
+    assert len(loaded.machines) == 1
+    assert loaded.machines[0].name == "test-box"
+
+
+def test_load_missing_config_returns_defaults(tmp_path):
+    config = load_config(path=tmp_path / "nonexistent.toml")
+    assert config.repo == ""
+    assert config.machines == []
+    assert config.dotfiles_path == "~/.dotfiles"
+
+
+def test_add_machine_duplicate(tmp_path, capsys):
+    config_path = tmp_path / ".dotsync.toml"
+    config = Config(
+        dotfiles_path=str(tmp_path),
+        machines=[Machine(name="box1", ssh_alias="box1")],
+    )
+    save_config(config, path=config_path)
+
+    # Loading from default path won't work in tests, so we test the logic directly
+    loaded = load_config(path=config_path)
+    assert any(m.name == "box1" for m in loaded.machines)

dotsync_py-0.1.0/tests/test_linker.py

@@ -0,0 +1,72 @@
+"""Test symlink creation."""
+
+from pathlib import Path
+from unittest.mock import patch
+
+from dotsync.config import Config
+from dotsync.linker import link_dotfiles
+
+
+def test_link_creates_symlinks(tmp_path):
+    dotfiles = tmp_path / "dotfiles"
+    dotfiles.mkdir()
+    home = tmp_path / "home"
+    home.mkdir()
+
+    # Create source files
+    (dotfiles / ".zshrc").write_text("# zshrc")
+    (dotfiles / ".gitconfig").write_text("# gitconfig")
+
+    config = Config(
+        dotfiles_path=str(dotfiles),
+        links={".zshrc": ".zshrc", ".gitconfig": ".gitconfig"},
+    )
+
+    with patch("dotsync.linker.load_config", return_value=config), \
+         patch("dotsync.linker.Path.home", return_value=home):
+        link_dotfiles()
+
+    assert (home / ".zshrc").is_symlink()
+    assert (home / ".zshrc").resolve() == (dotfiles / ".zshrc").resolve()
+    assert (home / ".gitconfig").is_symlink()
+
+
+def test_link_backs_up_existing_files(tmp_path):
+    dotfiles = tmp_path / "dotfiles"
+    dotfiles.mkdir()
+    home = tmp_path / "home"
+    home.mkdir()
+
+    (dotfiles / ".zshrc").write_text("# new zshrc")
+    (home / ".zshrc").write_text("# old zshrc")
+
+    config = Config(
+        dotfiles_path=str(dotfiles),
+        links={".zshrc": ".zshrc"},
+    )
+
+    with patch("dotsync.linker.load_config", return_value=config), \
+         patch("dotsync.linker.Path.home", return_value=home):
+        link_dotfiles()
+
+    assert (home / ".zshrc").is_symlink()
+    assert (home / ".zshrc.dotsync-backup").exists()
+    assert (home / ".zshrc.dotsync-backup").read_text() == "# old zshrc"
+
+
+def test_link_skips_missing_source(tmp_path):
+    dotfiles = tmp_path / "dotfiles"
+    dotfiles.mkdir()
+    home = tmp_path / "home"
+    home.mkdir()
+
+    config = Config(
+        dotfiles_path=str(dotfiles),
+        links={".missing": ".missing"},
+    )
+
+    with patch("dotsync.linker.load_config", return_value=config), \
+         patch("dotsync.linker.Path.home", return_value=home):
+        link_dotfiles()
+
+    assert not (home / ".missing").exists()