dotman-cli 0.2.9__tar.gz → 0.4.0__tar.gz

{dotman_cli-0.2.9/src/dotman_cli.egg-info → dotman_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotman-cli
-Version: 0.2.9
+Version: 0.4.0
 Summary: One more dot file manager but an interesting and easy to use one.
 Author: Nimit Bhardwaj
 License: MIT
@@ -155,6 +155,7 @@ packages:
 | `dotman deploy [packages]`   | Deploy dotfiles (create symlinks)              |
 | `dotman undeploy [packages]` | Remove deployed symlinks                       |
 | `dotman status [packages]`   | Show status of deployed dotfiles               |
+| `dotman diff [packages]`     | Diff deployed files against what deploy would write (exit 1 on drift) |
 | `dotman list`                | List all available packages                    |
 | `dotman absorb [packages]`   | Absorb unmanaged files from target directories |
 | `dotman watch`               | Watch for file changes and deploy automatically |
@@ -165,10 +166,13 @@ packages:
 | `dotman rollback [id]`       | Rollback a deployment by ID                    |
 | `dotman repo add <name>`     | Register current directory as a repository     |
 | `dotman repo list`           | List all registered repositories               |
+| `dotman doctor [packages]`   | Check required executables are present         |
 
 ### Options
 
 - `--config-dir, -c` - Override the config directory (default: `.dotman/` in current directory or `DOTMAN_CONFIG_DIR` env var)
+- `--repo, -r` - Use a registered repository. With no flag and no dotman repo in the current directory, the default registered repository is used, so `dotman status` works from anywhere
+- `--backup-dir` - Override `settings.backup_dir` (relative paths are relative to the repo)
 - `--dry-run, -n` - Preview changes without applying them
 - `--force, -f` - Overwrite existing files (with backup)
 - Specific packages can be passed to commands for targeted operations
@@ -219,7 +223,157 @@ packages:
           - ".git/**" # Ignore git directories
 ```
 
-The `absorb_ignore` field accepts a list of regex patterns that are matched against the full file path. If a file matches any pattern, it will be skipped during absorption.
+Each `absorb_ignore` entry is tried as a glob against the path relative to the target (and the file name), then as a regex against the full path. If a file matches any pattern, it is skipped during absorption.
+
+## Doctor Configuration
+
+Dotman can check if required executables are present on your system before deploying packages. This helps identify missing dependencies early, preventing partial deployments and confusing errors.
+
+### Basic Configuration
+
+Define executable requirements in your package configuration:
+
+```yaml
+packages:
+  nvim:
+    depends: []
+    files:
+      - source: "nvim"
+        target: "~/.config/nvim"
+    doctor:
+      executables:
+        - name: nvim
+          severity: error
+        - name: git
+          severity: error
+```
+
+### Severity Levels
+
+The `severity` field determines how missing executables are treated:
+
+- **`error`**: The executable is required for the package to work. If missing, `dotman deploy` may fail or produce unexpected results. The doctor command returns exit code 1.
+- **`warning`**: The executable is optional or only needed for certain features. If missing, the package may still work with reduced functionality. The doctor command returns exit code 0 but shows a warning.
+
+### Example Configuration
+
+```yaml
+packages:
+  nvim-base:
+    description: "Neovim configuration with LazyVim for base"
+    files:
+      - source: "nvim/base/"
+        target: "~/.config/nvim"
+    doctor:
+      executables:
+        - name: nvim
+          severity: error
+        - name: git
+          severity: error
+
+  opencode:
+    description: "OpenCode AI assistant configuration"
+    files:
+      - source: "opencode"
+        target: "~/.config/opencode"
+    doctor:
+      executables:
+        - name: node
+          severity: warning
+        - name: bun
+          severity: warning
+
+  zsh:
+    description: "Zsh Config for the system"
+    files:
+      - source: "zsh/.zshrc"
+        target: "~/.zshrc"
+    doctor:
+      executables:
+        - name: zsh
+          severity: error
+```
+
+### Using the Doctor Command
+
+```bash
+# Check all enabled packages
+dotman doctor
+
+# Check specific packages
+dotman doctor nvim zsh
+
+# Check with custom config directory
+dotman doctor --config-dir ~/.dotfiles
+```
+
+### Example Output
+
+```
+$ dotman doctor
+
+╭───────────────────────────────────────────────────────────────────────────╮
+│ Doctor Check Results                                                      │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Package: nvim-base                                                        │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Executable   Status    Severity    Path                                  │
+│ nvim         ✓ Found   error       /usr/bin/nvim                          │
+│ git          ✓ Found   error       /usr/bin/git                           │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Package: opencode                                                         │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Executable   Status    Severity    Path                                  │
+│ node         ✓ Found   warning     /usr/bin/node                          │
+│ bun          ✗ Missing warning     Not in PATH                           │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Package: zsh                                                              │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Executable   Status    Severity    Path                                  │
+│ zsh          ✓ Found   error       /usr/bin/zsh                           │
+╰───────────────────────────────────────────────────────────────────────────╯
+
+Summary: 0 errors, 1 warning, 4 passed
+```
+
+### Exit Codes
+
+- **Exit code 0**: No error-severity executables are missing (warnings are acceptable)
+- **Exit code 1**: One or more error-severity executables are missing
+
+### How It Works
+
+1. The doctor command loads your configuration and resolves the package dependency tree
+2. For each package with `doctor.executables` defined, it checks if each executable exists in your system's PATH
+3. Executable lookup uses `shutil.which()` for cross-platform compatibility (Linux, macOS, Windows)
+4. Results are displayed in a formatted table grouped by package
+5. A summary shows totals for errors, warnings, and passed checks
+
+### Packages Without Doctor Config
+
+Packages without a `doctor` configuration are still shown in the output with "No executable requirements":
+
+```
+$ dotman doctor
+
+╭───────────────────────────────────────────────────────────────────────────╮
+│ Doctor Check Results                                                      │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Package: simple-config                                                    │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Executable   Status    Severity    Path                                  │
+│              No executable requirements                                   │
+╰───────────────────────────────────────────────────────────────────────────╯
+
+Summary: 0 errors, 0 warnings, 0 passed
+```
+
+### Best Practices
+
+- Set `severity: error` for executables that are strictly required (e.g., `nvim`, `git`)
+- Set `severity: warning` for executables that are optional or only needed for specific features
+- Run `dotman doctor` before `dotman deploy` to catch missing dependencies early
+- Use `--dry-run` with deploy to preview changes after fixing any doctor issues
 
 ### Overlapping Targets
 

{dotman_cli-0.2.9 → dotman_cli-0.4.0}/README.md

@@ -134,6 +134,7 @@ packages:
 | `dotman deploy [packages]`   | Deploy dotfiles (create symlinks)              |
 | `dotman undeploy [packages]` | Remove deployed symlinks                       |
 | `dotman status [packages]`   | Show status of deployed dotfiles               |
+| `dotman diff [packages]`     | Diff deployed files against what deploy would write (exit 1 on drift) |
 | `dotman list`                | List all available packages                    |
 | `dotman absorb [packages]`   | Absorb unmanaged files from target directories |
 | `dotman watch`               | Watch for file changes and deploy automatically |
@@ -144,10 +145,13 @@ packages:
 | `dotman rollback [id]`       | Rollback a deployment by ID                    |
 | `dotman repo add <name>`     | Register current directory as a repository     |
 | `dotman repo list`           | List all registered repositories               |
+| `dotman doctor [packages]`   | Check required executables are present         |
 
 ### Options
 
 - `--config-dir, -c` - Override the config directory (default: `.dotman/` in current directory or `DOTMAN_CONFIG_DIR` env var)
+- `--repo, -r` - Use a registered repository. With no flag and no dotman repo in the current directory, the default registered repository is used, so `dotman status` works from anywhere
+- `--backup-dir` - Override `settings.backup_dir` (relative paths are relative to the repo)
 - `--dry-run, -n` - Preview changes without applying them
 - `--force, -f` - Overwrite existing files (with backup)
 - Specific packages can be passed to commands for targeted operations
@@ -198,7 +202,157 @@ packages:
           - ".git/**" # Ignore git directories
 ```
 
-The `absorb_ignore` field accepts a list of regex patterns that are matched against the full file path. If a file matches any pattern, it will be skipped during absorption.
+Each `absorb_ignore` entry is tried as a glob against the path relative to the target (and the file name), then as a regex against the full path. If a file matches any pattern, it is skipped during absorption.
+
+## Doctor Configuration
+
+Dotman can check if required executables are present on your system before deploying packages. This helps identify missing dependencies early, preventing partial deployments and confusing errors.
+
+### Basic Configuration
+
+Define executable requirements in your package configuration:
+
+```yaml
+packages:
+  nvim:
+    depends: []
+    files:
+      - source: "nvim"
+        target: "~/.config/nvim"
+    doctor:
+      executables:
+        - name: nvim
+          severity: error
+        - name: git
+          severity: error
+```
+
+### Severity Levels
+
+The `severity` field determines how missing executables are treated:
+
+- **`error`**: The executable is required for the package to work. If missing, `dotman deploy` may fail or produce unexpected results. The doctor command returns exit code 1.
+- **`warning`**: The executable is optional or only needed for certain features. If missing, the package may still work with reduced functionality. The doctor command returns exit code 0 but shows a warning.
+
+### Example Configuration
+
+```yaml
+packages:
+  nvim-base:
+    description: "Neovim configuration with LazyVim for base"
+    files:
+      - source: "nvim/base/"
+        target: "~/.config/nvim"
+    doctor:
+      executables:
+        - name: nvim
+          severity: error
+        - name: git
+          severity: error
+
+  opencode:
+    description: "OpenCode AI assistant configuration"
+    files:
+      - source: "opencode"
+        target: "~/.config/opencode"
+    doctor:
+      executables:
+        - name: node
+          severity: warning
+        - name: bun
+          severity: warning
+
+  zsh:
+    description: "Zsh Config for the system"
+    files:
+      - source: "zsh/.zshrc"
+        target: "~/.zshrc"
+    doctor:
+      executables:
+        - name: zsh
+          severity: error
+```
+
+### Using the Doctor Command
+
+```bash
+# Check all enabled packages
+dotman doctor
+
+# Check specific packages
+dotman doctor nvim zsh
+
+# Check with custom config directory
+dotman doctor --config-dir ~/.dotfiles
+```
+
+### Example Output
+
+```
+$ dotman doctor
+
+╭───────────────────────────────────────────────────────────────────────────╮
+│ Doctor Check Results                                                      │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Package: nvim-base                                                        │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Executable   Status    Severity    Path                                  │
+│ nvim         ✓ Found   error       /usr/bin/nvim                          │
+│ git          ✓ Found   error       /usr/bin/git                           │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Package: opencode                                                         │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Executable   Status    Severity    Path                                  │
+│ node         ✓ Found   warning     /usr/bin/node                          │
+│ bun          ✗ Missing warning     Not in PATH                           │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Package: zsh                                                              │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Executable   Status    Severity    Path                                  │
+│ zsh          ✓ Found   error       /usr/bin/zsh                           │
+╰───────────────────────────────────────────────────────────────────────────╯
+
+Summary: 0 errors, 1 warning, 4 passed
+```
+
+### Exit Codes
+
+- **Exit code 0**: No error-severity executables are missing (warnings are acceptable)
+- **Exit code 1**: One or more error-severity executables are missing
+
+### How It Works
+
+1. The doctor command loads your configuration and resolves the package dependency tree
+2. For each package with `doctor.executables` defined, it checks if each executable exists in your system's PATH
+3. Executable lookup uses `shutil.which()` for cross-platform compatibility (Linux, macOS, Windows)
+4. Results are displayed in a formatted table grouped by package
+5. A summary shows totals for errors, warnings, and passed checks
+
+### Packages Without Doctor Config
+
+Packages without a `doctor` configuration are still shown in the output with "No executable requirements":
+
+```
+$ dotman doctor
+
+╭───────────────────────────────────────────────────────────────────────────╮
+│ Doctor Check Results                                                      │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Package: simple-config                                                    │
+├───────────────────────────────────────────────────────────────────────────┤
+│ Executable   Status    Severity    Path                                  │
+│              No executable requirements                                   │
+╰───────────────────────────────────────────────────────────────────────────╯
+
+Summary: 0 errors, 0 warnings, 0 passed
+```
+
+### Best Practices
+
+- Set `severity: error` for executables that are strictly required (e.g., `nvim`, `git`)
+- Set `severity: warning` for executables that are optional or only needed for specific features
+- Run `dotman doctor` before `dotman deploy` to catch missing dependencies early
+- Use `--dry-run` with deploy to preview changes after fixing any doctor issues
 
 ### Overlapping Targets
 

{dotman_cli-0.2.9 → dotman_cli-0.4.0}/pyproject.toml

@@ -15,7 +15,7 @@ classifiers = [
     "Environment :: Console",
     "License :: OSI Approved :: MIT License",
 ]
-version = "0.2.9"
+version = "0.4.0"
 description = "One more dot file manager but an interesting and easy to use one."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -74,6 +74,8 @@ section-order = ["future", "standard-library", "third-party", "first-party", "lo
 combine-as-imports = true
 
 [tool.mypy]
+# select.kqueue only exists in the darwin stubs; check as darwin everywhere
+platform = "darwin"
 warn_return_any = true
 warn_unused_configs = true
 warn_redundant_casts = true

{dotman_cli-0.2.9 → dotman_cli-0.4.0}/src/dotman/cli/__init__.py

@@ -5,6 +5,8 @@ from dotman.cli.commands import (
     add_repository,
     clone,
     deploy,
+    diff,
+    doctor,
     history,
     init,
     list_packages,
@@ -23,7 +25,6 @@ from dotman.cli_utils import (
     app,
     console,
     get_config,
-    get_repository_option,
     repo_app,
 )
 
@@ -32,14 +33,15 @@ __all__ = [
     "add_repository",
     "app",
     "console",
+    "doctor",
     "get_config",
-    "get_repository_option",
     "repo_app",
     "init",
     "clone",
     "push",
     "pull",
     "deploy",
+    "diff",
     "undeploy",
     "status",
     "list_packages",

{dotman_cli-0.2.9 → dotman_cli-0.4.0}/src/dotman/cli/commands/__init__.py

@@ -5,6 +5,8 @@ from dotman.cli.commands.absorb import absorb_changes
 from dotman.cli.commands.clean import clean
 from dotman.cli.commands.clone import clone
 from dotman.cli.commands.deploy import deploy, undeploy
+from dotman.cli.commands.diff import diff
+from dotman.cli.commands.doctor import doctor
 from dotman.cli.commands.init import init
 from dotman.cli.commands.pull import pull
 from dotman.cli.commands.push import push
@@ -27,6 +29,8 @@ __all__ = [
     "clean",
     "clone",
     "deploy",
+    "diff",
+    "doctor",
     "history",
     "init",
     "list_packages",

{dotman_cli-0.2.9 → dotman_cli-0.4.0}/src/dotman/cli/commands/absorb.py

@@ -1,5 +1,6 @@
 """Absorb command for dotman CLI."""
 
+import fnmatch
 import re
 from pathlib import Path
 from typing import Annotated
@@ -10,10 +11,21 @@ from dotman.cli_utils import app, console, get_config
 from dotman.core.link_manager import LinkManager
 
 
+def _is_ignored(pattern: str, path: Path, relative: Path) -> bool:
+    """Match a pattern as a glob on the relative path, or a regex on the full path."""
+    if fnmatch.fnmatch(str(relative), pattern) or fnmatch.fnmatch(path.name, pattern):
+        return True
+    try:
+        return re.search(pattern, str(path)) is not None
+    except re.error:
+        return False
+
+
 def _should_skip_file(
     target_file: Path,
     absorb_ignore: list[str] | None,
     dest_file: Path,
+    relative: Path | None = None,
 ) -> tuple[bool, str]:
     """Check if a file should be skipped during absorption.
 
@@ -24,8 +36,9 @@ def _should_skip_file(
         return True, "symlink"
     if target_file.name.endswith(".j2"):
         return True, "template"
+    relative = relative or Path(target_file.name)
     if absorb_ignore and any(
-        re.search(pattern, str(target_file)) for pattern in absorb_ignore
+        _is_ignored(pattern, target_file, relative) for pattern in absorb_ignore
     ):
         return True, "ignored"
     if dest_file.exists():
@@ -94,9 +107,8 @@ def absorb_changes(
         console.print("[red]Dotman is not initialized. Run 'dotman init' first.[/red]")
         raise typer.Exit(1)
 
-    packages_to_absorb = packages or config.get_enabled_packages()
     # Sort for deterministic behavior (first package wins conflicts)
-    packages_to_absorb.sort()
+    packages_to_absorb = sorted(packages or config.get_enabled_packages())
 
     package_objs = []
     for package_name in packages_to_absorb:
@@ -138,7 +150,7 @@ def absorb_changes(
                     dest_file = source / relative_path
 
                     should_skip, _ = _should_skip_file(
-                        target_file, absorb_ignore, dest_file
+                        target_file, absorb_ignore, dest_file, relative_path
                     )
                     if should_skip:
                         continue

{dotman_cli-0.2.9 → dotman_cli-0.4.0}/src/dotman/cli/commands/deploy.py

@@ -10,8 +10,6 @@ from dotman.cli_utils import app, console, get_config
 from dotman.core.exceptions import (
     DotmanError,
     HookExecutionError,
-    LinkExistsError,
-    LinkTargetMissingError,
     MissingDependencyError,
 )
 from dotman.core.link_manager import LinkManager, LinkStatus
@@ -44,17 +42,13 @@ def deploy(
         str | None,
         typer.Option("--backup-dir", help="Override backup directory"),
     ] = None,
-    template_suffix: Annotated[
-        str | None,
-        typer.Option("--template-suffix", help="Override template suffix"),
-    ] = None,
     repo_name: Annotated[
         str | None,
         typer.Option("--repo", "-r", help="Repository name"),
     ] = None,
 ) -> None:
     """Deploy dotfiles by creating symlinks."""
-    config = get_config(config_dir, backup_dir, template_suffix, repo_name)
+    config = get_config(config_dir, backup_dir, repo_name)
 
     if repo_name:
         console.print(f"[cyan]Using repository: {repo_name}[/cyan]")
@@ -86,6 +80,7 @@ def deploy(
 
     deployment_id = str(uuid.uuid4())[:8]
     deployed_files: list[DeployedFile] = []
+    failed = False
 
     if dry_run:
         console.print("[cyan]Dry run mode - no changes will be made[/cyan]")
@@ -126,6 +121,7 @@ def deploy(
                             f"  [yellow]Skipping package '{pkg_name}'...[/yellow]"
                         )
                         skip_package = True
+                        failed = True
                         break
 
         if skip_package:
@@ -136,57 +132,39 @@ def deploy(
             target = Path(file_mapping.target).expanduser()
 
             try:
-                is_template = link_manager.is_template_file(source)
-
-                if is_template:
-                    if not dry_run:
-                        template_engine.render_file(source, variables, target)
-                        console.print(f"  [green]Rendered:[/green] {target}")
-                    else:
-                        console.print(f"  [cyan]Would render:[/cyan] {target}")
+                results = link_manager.create_link(
+                    source, target, force, dry_run, template_engine, variables
+                )
+            except DotmanError as e:
+                console.print(f"  [red]Error:[/red] {e}")
+                failed = True
+                continue
 
-                    deployed_files.append(
-                        DeployedFile(
-                            source=str(source),
-                            target=str(target),
-                            is_template=True,
-                        )
-                    )
+            for result in results:
+                if result.status != LinkStatus.LINKED:
+                    continue
+                is_template = link_manager.is_template_file(result.source)
+                if dry_run:
+                    console.print(f"  [cyan]{result.message}[/cyan]")
+                elif is_template:
+                    console.print(f"  [green]Rendered:[/green] {result.target}")
                 else:
-                    results = link_manager.create_link(
-                        source, target, force, dry_run, template_engine, variables
+                    console.print(
+                        f"  [green]Linked:[/green] {result.target} -> {result.source}"
+                    )
+                if result.backed_up:
+                    console.print(
+                        f"    [yellow]Backed up to:[/yellow] {result.backed_up}"
                     )
-                    for result in results:
-                        if result.status == LinkStatus.LINKED:
-                            if dry_run:
-                                console.print(f"  [cyan]{result.message}[/cyan]")
-                            else:
-                                console.print(
-                                    f"  [green]Linked:[/green]"
-                                    f" {result.target} -> {result.source}"
-                                )
-                            if result.backed_up:
-                                console.print(
-                                    f"    [yellow]Backed"
-                                    f" up to:[/yellow] {result.backed_up}"
-                                )
-
-                            deployed_files.append(
-                                DeployedFile(
-                                    source=str(result.source),
-                                    target=str(result.target),
-                                    is_template=False,
-                                    backup_path=str(result.backed_up)
-                                    if result.backed_up
-                                    else None,
-                                )
-                            )
-            except LinkExistsError as e:
-                console.print(f"  [red]Error:[/red] {e}")
-            except LinkTargetMissingError as e:
-                console.print(f"  [red]Error:[/red] {e}")
-            except DotmanError as e:
-                console.print(f"  [red]Error:[/red] {e}")
+
+                deployed_files.append(
+                    DeployedFile(
+                        source=str(result.source),
+                        target=str(result.target),
+                        is_template=is_template,
+                        backup_path=str(result.backed_up) if result.backed_up else None,
+                    )
+                )
 
         if pkg.hooks.post_deploy:
             target_dir = None
@@ -232,6 +210,10 @@ def deploy(
     else:
         console.print("\n[green]Deploy complete![/green]")
 
+    if failed:
+        console.print("[red]Some files failed to deploy (see errors above).[/red]")
+        raise typer.Exit(1)
+
 
 @app.command()
 def undeploy(