Metadata-Version: 2.4
Name: pauldot
Version: 0.1.0
Summary: Personal system manager: dotfiles, profiles, and tool installations across machines.
Author: Paul Hallett
License: MIT
Requires-Python: >=3.14
Requires-Dist: platformdirs>=4.3
Requires-Dist: pydantic>=2.10
Requires-Dist: rich>=13.9
Requires-Dist: tomli-w>=1.2
Requires-Dist: typer>=0.15
Description-Content-Type: text/markdown

# pauldot

Personal system manager: dotfiles, profiles, and tool installations across machines. File-first, written in Python, fork-friendly.

## What it does

- Manages `~/.zshrc` (and other dotfiles) from a single git repo
- Layers machine-specific profiles (work, personal) on top of a shared base
- Declares desired tools and installs them on `apply`
- Quick CLI for daily tasks: adding aliases, switching profiles, syncing
- One-line bootstrap on a fresh machine

## Install

```sh
uv tool install pauldot
```

## Quick start (new dotfiles repo)

```sh
# 1. Create your dotfiles repo on GitHub
gh repo create <you>/dotfiles --private --clone

# 2. Scaffold the structure
pauldot init --scaffold ./dotfiles

# 3. Edit pauldot.toml and bootstrap.sh, then push
cd dotfiles && git add . && git commit -m "init" && git push

# 4. On any new machine
curl -sSL https://raw.githubusercontent.com/<you>/dotfiles/main/bootstrap.sh | sh
```

Run `pauldot help fork` for the full walkthrough.

## Quick start (existing dotfiles repo)

```sh
pauldot init git@github.com:<you>/dotfiles
pauldot apply
```

If your repo is private, set up GitHub CLI first — `pauldot help gh` walks you through it.

## Commands

```
pauldot init [<repo-url>]        Clone your dotfiles repo and configure this machine
pauldot init --scaffold <path>   Generate a starter dotfiles repo structure
pauldot apply                    Reconcile current profile (zshrc + tools)
pauldot status                   Dry-run apply — show what would change
pauldot doctor                   Health check

pauldot profile show             Show the active profile
pauldot profile list             List available profiles
pauldot profile set <name>       Switch profile

pauldot tool list                List all defined tools and install status
pauldot tool install [<name>]    Install a tool (or all profile tools)
pauldot tool add                 Interactively add a tool to tools.toml
pauldot tool remove <name>       Remove a tool from tools.toml

pauldot alias add <key> <value>  Add an alias to aliases.zsh
pauldot alias list               List defined aliases

pauldot sync                     Pull latest changes; push local commits
pauldot edit [profile|tools|zshrc|pauldot]  Open a dotfiles file in $EDITOR

pauldot help bootstrap           Bootstrap walkthrough for new machines
pauldot help gh                  GitHub CLI auth walkthrough
pauldot help fork                How to set up your own dotfiles repo
```

## Dotfiles repo layout

```
~/.pauldot/
├── pauldot.toml           # top-level config (shell, git, bootstrap settings)
├── profiles/
│   ├── base.toml          # shared base profile
│   └── personal.toml      # extends base; machine-specific overrides
├── files/
│   ├── zshrc.base         # base zsh config
│   ├── zshrc.personal     # profile-specific zsh config
│   └── aliases.zsh        # managed by `pauldot alias add`
├── tools/
│   └── tools.toml         # tool definitions (check + install commands)
└── bootstrap.sh           # one-liner for new machines
```

`~/.zshrc` is a symlink to a generated file that sources these in order.

## Local state

```
~/.config/pauldot/state.toml    # active profile + repo URL (not committed)
```

## Development

```sh
make install    # uv sync
make test       # uv run pytest
make lint       # uv run ruff check .
make format     # uv run ruff format .
```

Requires Python 3.14+ and [uv](https://github.com/astral-sh/uv).
