diff --git a/.editorconfig b/.editorconfig index 53cc754..69c980c 100644 --- a/.editorconfig +++ b/.editorconfig @@ -61,5 +61,5 @@ shell_variant = bash [managed/dot_zshrc] shell_variant = zsh -[managed/dot_local/bin/{executable_tmx,executable_vscode-extensions-update}] +[managed/dot_local/bin/{executable_dotfiles,executable_tmx,executable_vscode-extensions-update}] indent_size = 4 diff --git a/.gitignore b/.gitignore index 27af880..45e1836 100644 --- a/.gitignore +++ b/.gitignore @@ -367,8 +367,8 @@ vite.config.ts.timestamp-* __MACOSX/ .AppleDouble .LSOverride -Icon[ -] +# Matches the name's trailing carriage return; a literal CR does not survive LF normalization. +Icon[[:cntrl:]] # Resource forks ._* @@ -389,8 +389,8 @@ Icon[ .file .disk_label* lost+found -.HFS+ Private Directory Data[ -] +# Matches the name's trailing carriage return; a literal CR does not survive LF normalization. +.HFS+ Private Directory Data[[:cntrl:]] # Directories potentially created on remote AFP share .AppleDB @@ -569,6 +569,9 @@ mise.*.local.lock .local/ +# Secondary sources are separate repositories checked out here; see docs/adr/0001. +/managed-*/ + # direnv is not used with this repository, and the managed global Git ignore covers .envrc.* # variants on machines that apply these dotfiles. diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 19b8553..bc8f341 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -103,16 +103,16 @@ repos: name: format-sh entry: mise exec -- shfmt -w language: system - files: ^(.*\.(sh|sh\.tmpl|bash|zsh)|managed/dot_(bash|zsh)rc|managed/dot_config/tmux/tmux\.conf\.tmpl|managed/dot_config/zsh/completions/_.*|managed/dot_local/bin/executable_.*)$ - exclude: ^managed/dot_local/bin/executable_(generate-completions|tmx|vscode-extensions-update)$ + files: ^(.*\.(sh|sh\.tmpl|bash|zsh)|(managed/)?dot_(bash|zsh)rc|(managed/)?dot_config/tmux/tmux\.conf\.tmpl|(managed/)?dot_config/zsh/completions/_.*|(managed/)?dot_local/bin/executable_.*)$ + exclude: ^managed/dot_local/bin/executable_(dotfiles|generate-completions|tmx|vscode-extensions-update)$ stages: [pre-commit] - id: format-sh-check name: format-sh-check entry: mise exec -- shfmt -d language: system - files: ^(.*\.(sh|sh\.tmpl|bash|zsh)|managed/dot_(bash|zsh)rc|managed/dot_config/tmux/tmux\.conf\.tmpl|managed/dot_config/zsh/completions/_.*|managed/dot_local/bin/executable_.*)$ - exclude: ^managed/dot_local/bin/executable_(generate-completions|tmx|vscode-extensions-update)$ + files: ^(.*\.(sh|sh\.tmpl|bash|zsh)|(managed/)?dot_(bash|zsh)rc|(managed/)?dot_config/tmux/tmux\.conf\.tmpl|(managed/)?dot_config/zsh/completions/_.*|(managed/)?dot_local/bin/executable_.*)$ + exclude: ^managed/dot_local/bin/executable_(dotfiles|generate-completions|tmx|vscode-extensions-update)$ stages: [manual] # ShellCheck does not support zsh, so this hook covers only sh and bash files. @@ -120,8 +120,8 @@ repos: name: lint-sh entry: mise exec -- shellcheck language: system - files: ^(.*\.(sh|sh\.tmpl|bash)|managed/dot_bashrc|managed/dot_local/bin/executable_.*)$ - exclude: ^managed/dot_local/bin/executable_(generate-completions|tmx|vscode-extensions-update)$ + files: ^(.*\.(sh|sh\.tmpl|bash)|(managed/)?dot_bashrc|(managed/)?dot_local/bin/executable_.*)$ + exclude: ^managed/dot_local/bin/executable_(dotfiles|generate-completions|tmx|vscode-extensions-update)$ stages: [pre-commit] - id: lint-zsh @@ -131,7 +131,7 @@ repos: - 'status=0; for file do zsh --no-exec "$file" || status=1; done; exit "$status"' - -- language: system - files: ^(.*\.zsh|managed/dot_zshrc|managed/dot_config/zsh/completions/_.*)$ + files: ^(.*\.zsh|(managed/)?dot_zshrc|(managed/)?dot_config/zsh/completions/_.*)$ stages: [pre-commit] - id: lint-python-fix diff --git a/.vscode/settings.json b/.vscode/settings.json index 60fc2e2..c415a36 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -23,6 +23,7 @@ "**/dot_local/bin/executable_brew-update": "shellscript", "**/dot_local/bin/executable_claude-commit": "shellscript", "**/dot_local/bin/executable_codex-commit": "shellscript", + "**/dot_local/bin/executable_dotfiles": "python", "**/dot_local/bin/executable_generate-completions": "python", "**/dot_local/bin/executable_op": "shellscript", "**/dot_local/bin/executable_tmx": "python", diff --git a/.yamllint.yaml b/.yamllint.yaml index a0b15f3..dff77be 100644 --- a/.yamllint.yaml +++ b/.yamllint.yaml @@ -5,6 +5,7 @@ ignore: | .cache/ .local/ .venv/ + managed-*/ node_modules/ pnpm-lock.yaml diff --git a/AGENTS.md b/AGENTS.md index 0295b9b..e991e91 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,9 +26,14 @@ chezmoi. Preserve these outcomes: - This repository is intended to remain public-safe. - Do not add private work endpoints, internal package indexes, credentials, tokens, or employer-specific configuration to tracked files. -- Keep work-only, secret, and machine-local values outside tracked files. Template and ignore logic - may control whether public-safe source content is applied, but they do not make tracked private - content safe. +- Keep work-only, secret, and machine-local values outside tracked files; put content private to a + **Secondary source** in that source's own repository. Template and ignore logic may control + whether public-safe source content is applied, but they do not make tracked private content safe. +- Write each target from exactly one source. Before adding a `managed/` file, check that no + **Secondary source** writes its target; route secondary content into shared tools through drop-in + directories, `includeIf`, or environment variables instead. +- Before changing how `dotfiles` applies secondary sources or the `managed-*` layout, read + [ADR 0001](docs/adr/0001-secondary-sources-as-nested-repositories.md). - In tracked Markdown and other public-facing repo content, do not use absolute local filesystem paths such as `/Users/...`. - Use file-relative targets for Markdown links. Use repository-root-relative paths in prose and code @@ -114,12 +119,22 @@ Use this section for durable domain terms that should guide future work in this update entries when a term becomes stable during adversarial review, architecture review, or implementation. -| Term | Definition | Aliases to Avoid | -| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | -| **Managed overlay** | A repo-owned sidecar file, usually named `*.managed.*`, that authoritatively manages selected keys or settings while preserving unrelated live configuration. | managed file, sidecar | -| **Default overlay** | A repo-owned sidecar file, usually named `*.default.*`, that supplies missing settings or an absent unstructured target without changing existing values. | default file, fallback | -| **Modify script** | A chezmoi `modify_` script or modify template that transforms existing target-file content instead of replacing the whole file. | merge script, transform | -| **Modify helper library** | Python helper code under `tools/chezmoi_modify` for use by PEP 723 modify scripts. | helper lib, modify helpers | +- **Managed overlay**: A repo-owned sidecar file, usually named `*.managed.*`, that authoritatively + manages selected keys or settings while preserving unrelated live configuration. Aliases to avoid: + managed file, sidecar. +- **Default overlay**: A repo-owned sidecar file, usually named `*.default.*`, that supplies missing + settings or an absent unstructured target without changing existing values. Aliases to avoid: + default file, fallback. +- **Modify script**: A chezmoi `modify_` script or modify template that transforms existing + target-file content instead of replacing the whole file. Aliases to avoid: merge script, + transform. +- **Modify helper library**: Python helper code under `tools/chezmoi_modify` for use by PEP 723 + modify scripts. Aliases to avoid: helper lib, modify helpers. +- **Primary source**: The chezmoi source state in this repository's `managed/` directory, applied by + plain `chezmoi`. Aliases to avoid: personal source. +- **Secondary source**: A separate Git repository checked out at `managed-/` in this + repository and applied by the `dotfiles` wrapper. Aliases to avoid: work repo (for the general + concept), overlay repo, sub-source. Relationships: @@ -127,3 +142,6 @@ Relationships: - A **Modify script** may apply a **Default overlay** before a **Managed overlay**, so managed values win while existing live values win over defaults. - A **Modify script** may import the **Modify helper library**. +- `dotfiles` applies the **Primary source** first, then each **Secondary source** alphabetically, + each with its own chezmoi state + ([ADR 0001](docs/adr/0001-secondary-sources-as-nested-repositories.md)). diff --git a/README.md b/README.md index febf866..8688637 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,9 @@ Other package-manager and binary install options are available in the official d ## Bootstrap This Repo +The repository's modify scripts run through [uv](https://docs.astral.sh/uv/) during `chezmoi apply`, +so install uv first, for example with `brew install uv`. + Initialize the default chezmoi source directory from GitHub: ```sh @@ -37,6 +40,72 @@ state for the system. The root `.chezmoiroot` file points chezmoi at `managed/`, keeping managed dotfiles separate from project-local test, lint, and package-manager configuration. +## Apply Secondary Sources + +A machine can also apply secondary sources: separate, private chezmoi source repositories checked +out at `managed-/` in this repository. The `dotfiles` command applies this repository first +and then each secondary source. +[ADR 0001](docs/adr/0001-secondary-sources-as-nested-repositories.md) records the design. + +`dotfiles` also runs through uv, installed as described in +[Bootstrap This Repo](#bootstrap-this-repo). + +If you answer yes to "Is this a work machine?" during `chezmoi init`, it also asks for the work +source's Git URL. An empty answer configures no work source. To set the URL later, run +`chezmoi edit-config` and set `work` under `[data.dotfiles_sources]`. + +After `chezmoi apply` installs `~/.local/bin/dotfiles`, apply the secondary sources. If a tool on +the machine must not read work content, follow [Set Up a Work Machine](#set-up-a-work-machine) +instead of the next command. Otherwise, run: + +```sh +~/.local/bin/dotfiles init +``` + +`dotfiles init` reruns `chezmoi init`, which prompts for settings added since the last run. Then it +clones each configured secondary source that is not checked out yet and applies it. If the apply +step fails, fix the cause and run `dotfiles apply`. A rerun of `dotfiles init` skips a source that +is already checked out. + +After setup, use `dotfiles update`, `dotfiles apply`, `dotfiles diff`, and `dotfiles status` to act +on every source. Plain `chezmoi` acts on this repository only. To run a chezmoi command against one +secondary source, use `dotfiles `, such as `dotfiles work diff`. The +aggregate verbs accept only the flags `-n`, `--dry-run`, `-v`, `--verbose`, and `--force`; to pass +other arguments, use plain `chezmoi` for this repository or `dotfiles ` for a secondary +source. + +### Set Up a Work Machine + +The work source's checkout is inside this repository, so a tool that reads this repository can also +read `managed-work/`. Git ignores the checkout, which keeps it out of commits, but Git does not +control what such a tool reads. If a tool on the machine must not read work content, such as a +coding agent that uses this repository as its working directory, set up the machine in this order: + +1. Use the tool's own permission settings to deny it read and write access to + `~/.local/share/chezmoi/managed-work/`. +2. Run `~/.local/bin/dotfiles init` in a shell that the tool does not control. If `chezmoi init` + prompts for the work source's Git URL, enter it. +3. Confirm that the tool cannot read a file under `~/.local/share/chezmoi/managed-work/`. + +### Work in a Secondary Source + +A secondary source uses this repository's tooling, so it has no CI or lint configuration of its own. +A secondary source must not ship a chezmoi config template (`.chezmoi..tmpl`), which would +replace the shared config; `dotfiles` refuses to run against a source that has one. + +From inside `managed-/`, install the commit hooks once: + +```sh +uv run pre-commit install -c ../.pre-commit-config.yaml -t pre-commit -t commit-msg +``` + +Before you push, run the format and lint checks. Run from inside `managed-/`, these tasks +check only that checkout. The `:::` separates the two mise tasks. + +```sh +mise run format:check ::: lint +``` + ## Bootstrap Homebrew The repo manages a curated global Brewfile at diff --git a/docs/adr/0001-secondary-sources-as-nested-repositories.md b/docs/adr/0001-secondary-sources-as-nested-repositories.md new file mode 100644 index 0000000..edf7a57 --- /dev/null +++ b/docs/adr/0001-secondary-sources-as-nested-repositories.md @@ -0,0 +1,43 @@ +# Secondary sources are nested repositories applied by separate chezmoi invocations + +Some machines need dotfiles that must stay out of this public repository, and chezmoi applies only +one source directory per invocation. Each secondary source is a separate Git repository checked out +at `managed-/` in this repository, and this repository ignores `/managed-*/`. The +[`dotfiles`](../../managed/dot_local/bin/executable_dotfiles) wrapper applies the primary source, +`managed/`, and then each secondary source with its own invocation: +`chezmoi --source managed- --persistent-state ~/.config/chezmoi/chezmoistate-.boltdb`. +Every invocation reads the shared chezmoi config. Nesting keeps the shared tooling one directory up, +so a secondary source's modify scripts resolve `tools/` through `CHEZMOI_SOURCE_DIR/..`, and its +targets land in `$HOME` like the primary source's. + +## Considered options + +- **One state file for every source.** The state records the config template's hash, so each + secondary run warns that the template changed. A chezmoi run started from another run's script + also times out waiting for the state lock that the outer run holds. +- **chezmoi hooks or a `git-repo` external in the primary source.** A hook runs during dry runs too, + and a failing external, such as a clone attempted off the work network, aborts the primary apply. +- **A sibling checkout with symlinked tooling.** Git refuses a symlinked `.gitignore`, and pnpm + reinstalls dependencies through the symlinked workspace. + +## Consequences + +- Nesting puts private content under this repository's root. Git ignores `/managed-*/`, so the + checkout stays out of this repository's commits, but a tool that uses this repository as its + working directory, such as a coding agent, can read the checkout unless its permissions deny + `managed-/`. +- Sources must write disjoint targets. A target that two sources write would hold private content at + a path outside `managed-/`, which a tool denied the checkout may still read. Secondary + content reaches shared tools through drop-in directories, `includeIf`, and environment variables. + Revisit this rule when a setting has none of those routes. +- A secondary source must not ship a chezmoi config template (`.chezmoi..tmpl`), which + `chezmoi init` would render over the shared config. The wrapper refuses to run against one. +- A secondary source cannot lint or run CI on its own, because its tooling lives in this repository. + A maintainer runs this repository's format and lint tasks from inside the source and installs only + its commit hooks there, because the pre-push hook runs this repository's test suite, which a + secondary source's push never changes. The [README](../../README.md#work-in-a-secondary-source) + gives the commands. +- Plain `chezmoi` applies only the primary source. `dotfiles` applies the primary source first, then + secondary sources alphabetically. +- `chezmoi purge` deletes the config directory, which holds the shared config and every source's + state, and the source directory, so the wrapper refuses to pass `purge` through. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..a48528d --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,8 @@ +# Architecture decision records + +These records explain choices in this repository that the code alone does not justify: what was +decided, in what context, and why. Read the records whose titles name the area you are about to +change before proposing a different design. + +- [0001](0001-secondary-sources-as-nested-repositories.md): Secondary sources are nested + repositories applied by separate chezmoi invocations diff --git a/managed/.chezmoi.toml.tmpl b/managed/.chezmoi.toml.tmpl index b07c2aa..0a6c8ba 100644 --- a/managed/.chezmoi.toml.tmpl +++ b/managed/.chezmoi.toml.tmpl @@ -9,4 +9,9 @@ work_machine = {{ $workMachine }} {{- $gitWorkEmail := promptStringOnce . "git_work_email" "Work Git email" }} git_work_name = {{ $gitWorkName | quote }} git_work_email = {{ $gitWorkEmail | quote }} +{{- /* Secondary sources that dotfiles applies; an empty URL is inactive. */}} +{{- $workSource := promptStringOnce . "dotfiles_sources.work" "Work dotfiles source Git URL (empty for none)" }} + +[data.dotfiles_sources] +work = {{ $workSource | quote }} {{- end }} diff --git a/managed/dot_config/git/ignore b/managed/dot_config/git/ignore index 3f36538..ce82c46 100644 --- a/managed/dot_config/git/ignore +++ b/managed/dot_config/git/ignore @@ -5,8 +5,8 @@ __MACOSX/ .AppleDouble .LSOverride -Icon[ -] +# Matches the name's trailing carriage return; a literal CR does not survive LF normalization. +Icon[[:cntrl:]] # Thumbnails ._* diff --git a/managed/dot_gitconfig b/managed/dot_gitconfig index e3c7c87..18f9f9e 100644 --- a/managed/dot_gitconfig +++ b/managed/dot_gitconfig @@ -20,5 +20,8 @@ path = ~/.gitconfig-personal [includeIf "gitdir:~/.local/share/chezmoi/"] path = ~/.gitconfig-personal +# A secondary source nested in the dotfiles repo; see docs/adr/0001 there. Later includes win. +[includeIf "gitdir:~/.local/share/chezmoi/managed-work/"] + path = ~/.gitconfig-work [includeIf "gitdir:~/Code/work/"] path = ~/.gitconfig-work diff --git a/managed/dot_local/bin/executable_dotfiles b/managed/dot_local/bin/executable_dotfiles new file mode 100755 index 0000000..c99c83f --- /dev/null +++ b/managed/dot_local/bin/executable_dotfiles @@ -0,0 +1,264 @@ +#!/usr/bin/env -S uv run --script +# /// script +# requires-python = ">=3.14,<3.15" +# /// +"""Apply the primary chezmoi source and every secondary source. + +Design and rejected alternatives: docs/adr/0001-secondary-sources-as-nested-repositories.md in the +dotfiles repository. + +chezmoi applies one source per invocation. The primary source is the dotfiles +repository's managed/ directory, applied by plain chezmoi. A secondary source is a +separate Git repository checked out at managed-/ in the dotfiles repository. +Each secondary runs with the shared chezmoi config and its own persistent state file, +~/.config/chezmoi/chezmoistate-.boltdb: + + chezmoi --persistent-state= --source= + +The config's dotfiles_sources table lists the secondary sources by name and clone +URL. A source is active when its URL is non-empty. + +Usage: + + dotfiles init # chezmoi init, then clone and apply new secondary sources. + dotfiles update # Update each source, cloning a new secondary source first. + dotfiles apply # Apply every source; diff and status work the same way. + dotfiles # Run chezmoi with against one secondary source. + +The aggregate verbs (init, update, apply, diff, status) run the primary source +first, then secondary sources alphabetically. They accept only the flags -n, +--dry-run, -v, --verbose, and --force. For other arguments, use plain chezmoi for +the primary source or dotfiles for a secondary source. + +init and update clone each active secondary source that has no checkout; apply, +diff, and status report it as not cloned. A dry run clones nothing. + +If the primary source fails during init, update, or apply, no secondary source +runs, because secondary sources depend on its targets. Otherwise a failing source +does not stop the others. A run with failures ends with one summary line per failed +source, naming the primary source "personal", and exits 1. + +dotfiles appends --persistent-state and --source after , so they +outvote any in . A flag that takes a value must not end , because it +would take --persistent-state as its value; write it as --flag=value instead. The +form refuses any argument equal to init (use dotfiles init), purge (it deletes the +shared config and every source's state), --init (it renders the source's config +template over the shared config), or -- (arguments after it are not flags, so the +appended flags would not apply). + +A secondary source must not ship a chezmoi config template (.chezmoi..tmpl): +chezmoi init would render it over the shared config. dotfiles refuses to run +against a source that has one, at its root or in the directory that .chezmoiroot +names, including right after cloning it. +""" + +import json +import os +import re +import subprocess +import sys +from dataclasses import dataclass +from pathlib import Path + +USAGE = """\ +usage: dotfiles {init|update|apply|diff|status} [-n|--dry-run] [-v|--verbose] [--force] + dotfiles """ +AGGREGATE_VERBS = ("init", "update", "apply", "diff", "status") +# Global chezmoi flags that take no value, so every verb and source accepts them. +AGGREGATE_FLAGS = ("-n", "--dry-run", "-v", "--verbose", "--force") +# Secondary sources depend on primary targets, such as the fish config that loads work/. +STOP_ON_PERSONAL_FAILURE = ("init", "update", "apply") +CLONING_VERBS = ("init", "update") +CONFIG_TEMPLATES = tuple(f".chezmoi.{fmt}.tmpl" for fmt in ("toml", "yaml", "json", "jsonc")) +SOURCE_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9_-]*") +PREFIX = "managed-" + + +@dataclass(frozen=True) +class Source: + """A secondary source checkout and its chezmoi state file.""" + + name: str + checkout: Path + state: Path + url: str = "" + + @classmethod + def at(cls, root: Path, name: str, url: str = "") -> Source: + """Locate the named source under the dotfiles repository root.""" + config_home = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config") + return cls( + name, + root / f"{PREFIX}{name}", + config_home / "chezmoi" / f"chezmoistate-{name}.boltdb", + url, + ) + + def is_cloned(self) -> bool: + """Report whether the checkout holds a repository, not a failed clone's empty directory.""" + return (self.checkout / ".git").exists() + + def chezmoi(self, *args: str) -> list[str]: + """Build a chezmoi command that targets this source. + + The source and state flags come last because chezmoi takes the last value of a + repeated flag, so they outvote any override in args. + """ + return ["chezmoi", *args, f"--persistent-state={self.state}", f"--source={self.checkout}"] + + def shipped_config_template(self) -> str | None: + """Return a config template's name, after printing why the source is refused.""" + # chezmoi reads the config template from the directory that .chezmoiroot names. + root_file = self.checkout / ".chezmoiroot" + root = ( + self.checkout / root_file.read_text().strip() if root_file.exists() else self.checkout + ) + for name in CONFIG_TEMPLATES: + if (root / name).exists(): + print( + f"dotfiles: {self.name}: refusing {root / name}: a secondary source" + " must not ship a config template, which would replace the shared config", + file=sys.stderr, + ) + return name + return None + + +def run(command: list[str]) -> int: + """Run a command with inherited standard streams, which carry prompts and errors.""" + return subprocess.run(command, check=False).returncode # noqa: S603 + + +def chezmoi_output(*args: str) -> str: + """Run a read-only chezmoi query and return its standard output.""" + return subprocess.run( # noqa: S603 + ["chezmoi", *args], # noqa: S607 + capture_output=True, + text=True, + check=True, + ).stdout + + +def repo_root() -> Path: + """Return the dotfiles repository root, the parent of the primary source.""" + return Path(chezmoi_output("source-path").strip()).parent + + +def active_sources(root: Path) -> list[Source]: + """List active registry entries, warning about checkouts that have none.""" + registry = json.loads(chezmoi_output("data", "--format", "json")).get("dotfiles_sources", {}) + active = {name: url for name, url in registry.items() if url} + for path in sorted(root.glob(f"{PREFIX}*/")): + if path.name.removeprefix(PREFIX) not in active: + print( + f"dotfiles: skipping {path.name}: no active dotfiles_sources entry", file=sys.stderr + ) + return [Source.at(root, name, url) for name, url in sorted(active.items())] + + +def run_secondary(source: Source, verb: str, flags: list[str]) -> str | None: + """Run one aggregate verb against a secondary source; return why it failed, if it did.""" + if not SOURCE_NAME.fullmatch(source.name): + return "invalid source name" + if source.is_cloned(): + if verb == "init": + return None + elif verb in CLONING_VERBS: + if "-n" in flags or "--dry-run" in flags: + print( + f"dotfiles: {source.name}: dry run skips cloning {source.checkout.name}", + file=sys.stderr, + ) + return None + if code := run(["git", "clone", source.url, str(source.checkout)]): + return f"clone exit {code}" + else: + return "not cloned; run dotfiles init" + if template := source.shipped_config_template(): + return f"ships {template}" + # init applies a fresh clone; a dry run never gets here because it clones nothing. + if code := run(source.chezmoi("apply" if verb == "init" else verb, *flags)): + # A rerun of init skips the existing checkout, so only apply recovers it. + return ( + f"apply exit {code}; fix it, then run dotfiles apply" + if verb == "init" + else f"exit {code}" + ) + return None + + +def aggregate(verb: str, flags: list[str]) -> int: + """Run a verb against personal, then each active secondary source.""" + failures = [] + if code := run(["chezmoi", verb, *flags]): + failures.append(f"personal: {verb} failed (exit {code})") + # Read the registry only after personal init or update, which may add entries. + if not (failures and verb in STOP_ON_PERSONAL_FAILURE): + failures.extend( + f"{source.name}: {verb} failed ({reason})" + for source in active_sources(repo_root()) + if (reason := run_secondary(source, verb, flags)) + ) + for failure in failures: + print(f"dotfiles: {failure}", file=sys.stderr) + return 1 if failures else 0 + + +def passthrough(name: str, args: list[str]) -> int: + """Run chezmoi with the given arguments against one secondary source.""" + if name == "personal": + return usage_error("personal is not a secondary source; use chezmoi") + if not SOURCE_NAME.fullmatch(name): + return usage_error(f"invalid source name: {name}") + # A flag value can precede the subcommand, so check every argument. + if "purge" in args: + return usage_error("refusing purge: it deletes the shared config and every source's state") + if "init" in args: + return usage_error("refusing init: use dotfiles init, which clones and guards each source") + if any(arg == "--init" or arg.startswith("--init=") for arg in args): + return usage_error("refusing --init: it renders the source's config template") + if "--" in args: + # Arguments after -- are not flags, so the source and state flags would not apply. + return usage_error("refusing --: dotfiles appends --source and --persistent-state") + source = Source.at(repo_root(), name) + if not source.is_cloned(): + return usage_error(f"no checkout at {source.checkout}") + if source.shipped_config_template(): + return 1 + return run(source.chezmoi(*args)) + + +def usage_error(message: str) -> int: + """Print an error with the usage text and return the usage exit status.""" + print(f"dotfiles: {message}\n{USAGE}", file=sys.stderr) + return 2 + + +def main(argv: list[str] | None = None) -> int: + """Dispatch an aggregate verb or a passthrough to one secondary source.""" + args = sys.argv[1:] if argv is None else argv + if not args: + return usage_error("missing command") + first, rest = args[0], args[1:] + if first in ("-h", "--help"): + print(f"{USAGE}\n\n{__doc__}") + return 0 + try: + if first in AGGREGATE_VERBS: + if other := [arg for arg in rest if arg not in AGGREGATE_FLAGS]: + return usage_error( + f"{first} accepts only {', '.join(AGGREGATE_FLAGS)};" + f" use dotfiles for other arguments (got {other[0]!r})" + ) + return aggregate(first, rest) + return passthrough(first, rest) + except FileNotFoundError as error: + print(f"dotfiles: {error.filename} was not found on PATH", file=sys.stderr) + return 127 + except subprocess.CalledProcessError as error: + print(f"dotfiles: {' '.join(error.cmd)} failed: {error.stderr.strip()}", file=sys.stderr) + return 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/mise.toml b/mise.toml index 980bd0c..18abe52 100644 --- a/mise.toml +++ b/mise.toml @@ -5,6 +5,13 @@ idiomatic_version_file_enable_tools = ["node", "python"] lockfile = true minimum_release_age = "3d" +# Run tasks in the invocation directory, so a secondary source checked out at managed-/ +# runs the shared tasks over its own files. A task run from a subdirectory of this repository +# covers only that subtree; CI and hooks run from the repository root. pre-commit tasks pass the +# shared config with -c because a secondary source has none of its own. +[task_config] +dir = "{{cwd}}" + # Track the latest release and let CI catch breaking changes; mise.lock pins the exact release. # Pin an exact version only to defer a specific incompatibility; a prefix bound never moves. [tools] @@ -47,15 +54,15 @@ description = "Check all formatting without mutating" # filtering, so file discovery lives in the hook filters. [tasks."format:fish"] description = "Format fish files with fish_indent" -run = "uv run pre-commit run format-fish --all-files" +run = "uv run pre-commit run -c {{config_root}}/.pre-commit-config.yaml format-fish --all-files" [tasks."format:fish:check"] description = "Check fish formatting with fish_indent" -run = "uv run pre-commit run format-fish-check --hook-stage manual --all-files" +run = "uv run pre-commit run -c {{config_root}}/.pre-commit-config.yaml format-fish-check --hook-stage manual --all-files" [tasks."format:hygiene"] description = "Run pre-commit hygiene hooks across all files; may modify files" -run = "uv run pre-commit run --all-files --hook-stage manual" +run = "uv run pre-commit run -c {{config_root}}/.pre-commit-config.yaml --all-files --hook-stage manual" # .local/ is gitignored and oxfmt's own glob expansion honors .gitignore, so these tasks rely on # the shell (sh, via mise) expanding the globs. An unmatched glob stays literal under sh, and @@ -99,11 +106,11 @@ run = "uv run ruff format --check" [tasks."format:sh"] description = "Format POSIX shell files with shfmt" -run = "uv run pre-commit run format-sh --all-files" +run = "uv run pre-commit run -c {{config_root}}/.pre-commit-config.yaml format-sh --all-files" [tasks."format:sh:check"] description = "Check POSIX shell formatting with shfmt" -run = "uv run pre-commit run format-sh-check --hook-stage manual --all-files" +run = "uv run pre-commit run -c {{config_root}}/.pre-commit-config.yaml format-sh-check --hook-stage manual --all-files" [tasks."format:shell"] depends = ["format:fish", "format:sh"] @@ -115,11 +122,11 @@ description = "Check all shell formatting" [tasks."format:toml"] description = "Format TOML files with Tombi" -run = "tombi format" +run = "tombi format ." [tasks."format:toml:check"] description = "Check TOML formatting with Tombi" -run = "tombi format --check" +run = "tombi format --check ." [tasks.lint] depends = ["lint:python", "lint:shell", "lint:yaml"] @@ -140,11 +147,11 @@ run = "uv run ruff check --fix" [tasks."lint:fish"] description = "Check fish syntax with fish --no-execute" -run = "uv run pre-commit run lint-fish --all-files" +run = "uv run pre-commit run -c {{config_root}}/.pre-commit-config.yaml lint-fish --all-files" [tasks."lint:sh"] description = "Lint sh and bash files with ShellCheck" -run = "uv run pre-commit run lint-sh --all-files" +run = "uv run pre-commit run -c {{config_root}}/.pre-commit-config.yaml lint-sh --all-files" [tasks."lint:shell"] depends = ["lint:fish", "lint:sh", "lint:zsh"] @@ -152,7 +159,7 @@ description = "Lint all shell files" [tasks."lint:zsh"] description = "Check zsh syntax with zsh --no-exec" -run = "uv run pre-commit run lint-zsh --all-files" +run = "uv run pre-commit run -c {{config_root}}/.pre-commit-config.yaml lint-zsh --all-files" # eval + usage: see the format:lua comment. [tasks."lint:yaml"] diff --git a/pyproject.toml b/pyproject.toml index dc2fd60..97c910f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -25,6 +25,7 @@ cache_dir = ".cache/mypy" python_version = "3.14" files = [ "tools", + "managed/dot_local/bin/executable_dotfiles", "managed/dot_local/bin/executable_generate-completions", "managed/dot_local/bin/executable_tmx", "managed/dot_local/bin/executable_vscode-extensions-update" @@ -61,6 +62,7 @@ unsafe-fixes = false extend-exclude = [".venv/", ".cache/", ".local/", "node_modules/"] # Extensionless Python shims are not matched by the default *.py include extend-include = [ + "managed/dot_local/bin/executable_dotfiles", "managed/dot_local/bin/executable_generate-completions", "managed/dot_local/bin/executable_tmx", "managed/dot_local/bin/executable_vscode-extensions-update" diff --git a/tests/test_dotfiles.py b/tests/test_dotfiles.py new file mode 100644 index 0000000..921526d --- /dev/null +++ b/tests/test_dotfiles.py @@ -0,0 +1,508 @@ +"""Behavior of the dotfiles wrapper, which applies the primary and secondary chezmoi sources. + +Quoted requirements come from the multi-source design handoff; docs/adr/0001 records the +decision. +CI has no chezmoi binary, so a fake subprocess.run stands in for chezmoi and git. +""" + +import importlib.machinery +import importlib.util +import json +import subprocess +from pathlib import Path + +import pytest + +_SCRIPT = Path(__file__).resolve().parent.parent / "managed/dot_local/bin/executable_dotfiles" +_loader = importlib.machinery.SourceFileLoader("dotfiles", str(_SCRIPT)) +_spec = importlib.util.spec_from_loader("dotfiles", _loader) +assert _spec is not None +dotfiles = importlib.util.module_from_spec(_spec) +_loader.exec_module(dotfiles) + +URL = "https://git.example.invalid/dotfiles-work.git" + + +class _FakeTools: + """Stand-in for chezmoi and git that records every mutating call. + + Calls name their source by the --source checkout, or "personal" without one. + """ + + def __init__(self, root: Path, data: dict[str, object]) -> None: + self.root = root + self.data = data + self.data_after_init: dict[str, object] | None = None + self.exit_codes: dict[str, int] = {} + self.clone_files: dict[str, str] = {} + self.clone_exit = 0 + self.calls: list[list[str]] = [] + + def __call__(self, args, **_kwargs): + args = list(args) + if args == ["chezmoi", "source-path"]: + return subprocess.CompletedProcess(args, 0, f"{self.root / 'managed'}\n", "") + if args == ["chezmoi", "data", "--format", "json"]: + return subprocess.CompletedProcess(args, 0, json.dumps(self.data), "") + self.calls.append(args) + if args[:2] == ["git", "clone"]: + if self.clone_exit == 0: + checkout = Path(args[3]) + (checkout / ".git").mkdir(parents=True) + for name, text in self.clone_files.items(): + (checkout / name).write_text(text) + return subprocess.CompletedProcess(args, self.clone_exit) + # chezmoi takes the last --source, so the fake does too. + sources = [arg.removeprefix("--source=") for arg in args if arg.startswith("--source=")] + source = Path(sources[-1]).name.removeprefix("managed-") if sources else "personal" + if source == "personal" and args[1] == "init" and self.data_after_init is not None: + self.data = self.data_after_init + return subprocess.CompletedProcess(args, self.exit_codes.get(source, 0)) + + +@pytest.fixture +def config_home(tmp_path, monkeypatch): + config = tmp_path / "config" + monkeypatch.setenv("XDG_CONFIG_HOME", str(config)) + return config + + +@pytest.fixture +def repo(tmp_path): + root = tmp_path / "repo" + (root / "managed").mkdir(parents=True) + return root + + +def checkout(repo: Path, name: str) -> Path: + path = repo / f"managed-{name}" + (path / ".git").mkdir(parents=True) + return path + + +@pytest.fixture +def tools(repo, config_home, monkeypatch): + del config_home + fake = _FakeTools(repo, {"dotfiles_sources": {"work": URL}}) + monkeypatch.setattr(subprocess, "run", fake) + return fake + + +def secondary(repo: Path, config_home: Path, name: str, *args: str) -> list[str]: + return [ + "chezmoi", + *args, + f"--persistent-state={config_home / 'chezmoi' / f'chezmoistate-{name}.boltdb'}", + f"--source={repo / f'managed-{name}'}", + ] + + +def test_apply_runs_personal_then_each_secondary_with_its_own_source_and_state( + tools, repo, config_home +): + # "chezmoi --source /managed- --persistent-state + # ~/.config/chezmoi/chezmoistate-.boltdb"; "personal first". + checkout(repo, "work") + + assert dotfiles.main(["apply"]) == 0 + + assert tools.calls == [["chezmoi", "apply"], secondary(repo, config_home, "work", "apply")] + + +def test_aggregate_verbs_forward_flags_to_every_source(tools, repo, config_home): + # "Aggregate verbs init, update, apply, diff, status: forward flags (-n, -v, ...)". + checkout(repo, "work") + + assert dotfiles.main(["apply", "-n", "--verbose", "--force"]) == 0 + + assert tools.calls == [ + ["chezmoi", "apply", "-n", "--verbose", "--force"], + secondary(repo, config_home, "work", "apply", "-n", "--verbose", "--force"), + ] + + +@pytest.mark.parametrize("arg", ["~/.gitconfig", "--exclude=scripts", "-nv", "-Dnone"], ids=str) +def test_aggregate_verbs_reject_other_arguments(tools, repo, arg, capsys): + # "reject positional target paths". Other flags may take values or differ by subcommand. + checkout(repo, "work") + + assert dotfiles.main(["apply", "-n", arg, "--bad"]) == 2 + + assert tools.calls == [] + err = capsys.readouterr().err + assert f"got {arg!r}" in err + assert "dotfiles " in err + + +def test_secondaries_run_alphabetically_after_personal(tools, repo, config_home): + # "run personal then secondaries alphabetically". + tools.data = {"dotfiles_sources": {"work": URL, "alpha": URL}} + checkout(repo, "work") + checkout(repo, "alpha") + + assert dotfiles.main(["status"]) == 0 + + assert tools.calls == [ + ["chezmoi", "status"], + secondary(repo, config_home, "alpha", "status"), + secondary(repo, config_home, "work", "status"), + ] + + +@pytest.mark.parametrize("data", [{}, {"dotfiles_sources": {}}], ids=["no-key", "no-sources"]) +def test_machine_without_secondary_sources_runs_personal_only(tools, data): + tools.data = data + + assert dotfiles.main(["apply"]) == 0 + + assert tools.calls == [["chezmoi", "apply"]] + + +def test_checkout_without_active_entry_is_skipped_with_a_warning(tools, repo, capsys): + # "A source is active when its URL is non-empty." "Warn about a managed-* checkout with no + # active entry and skip it." + tools.data = {"dotfiles_sources": {"work": ""}} + checkout(repo, "work") + checkout(repo, "old") + + assert dotfiles.main(["apply"]) == 0 + + assert tools.calls == [["chezmoi", "apply"]] + err = capsys.readouterr().err + assert "dotfiles: skipping managed-old: no active dotfiles_sources entry" in err + assert "dotfiles: skipping managed-work: no active dotfiles_sources entry" in err + + +@pytest.mark.parametrize("verb", ["init", "update", "apply"]) +def test_mutating_verb_stops_when_personal_fails(tools, repo, verb, capsys): + # "init, update, apply: if personal fails, stop, run no secondary, exit nonzero". + checkout(repo, "work") + tools.exit_codes["personal"] = 1 + + assert dotfiles.main([verb]) == 1 + + assert tools.calls == [["chezmoi", verb]] + assert capsys.readouterr().err.splitlines()[-1] == f"dotfiles: personal: {verb} failed (exit 1)" + + +def test_failed_personal_init_clones_nothing(tools): + # "init, update, apply: if personal fails, stop, run no secondary". + tools.exit_codes["personal"] = 1 + + assert dotfiles.main(["init"]) == 1 + + assert tools.calls == [["chezmoi", "init"]] + + +def test_failing_secondary_does_not_stop_the_others(tools, repo, config_home, capsys): + # "A failing secondary does not stop the others." "Every run that had failures ends with one + # summary line per failed source, such as `dotfiles: work: update failed (exit 1)`". + tools.data = {"dotfiles_sources": {"work": URL, "alpha": URL}} + checkout(repo, "work") + checkout(repo, "alpha") + tools.exit_codes["alpha"] = 3 + + assert dotfiles.main(["update"]) == 1 + + assert tools.calls == [ + ["chezmoi", "update"], + secondary(repo, config_home, "alpha", "update"), + secondary(repo, config_home, "work", "update"), + ] + assert capsys.readouterr().err.splitlines()[-1] == "dotfiles: alpha: update failed (exit 3)" + + +@pytest.mark.parametrize("verb", ["diff", "status"]) +def test_read_only_verb_continues_past_personal_failure(tools, repo, config_home, verb, capsys): + # "diff, status: read-only, so continue past any failure." + checkout(repo, "work") + tools.exit_codes["personal"] = 1 + tools.exit_codes["work"] = 1 + + assert dotfiles.main([verb]) == 1 + + assert tools.calls == [["chezmoi", verb], secondary(repo, config_home, "work", verb)] + assert capsys.readouterr().err.splitlines()[-2:] == [ + f"dotfiles: personal: {verb} failed (exit 1)", + f"dotfiles: work: {verb} failed (exit 1)", + ] + + +@pytest.mark.parametrize("verb", ["apply", "diff", "status"]) +def test_active_source_without_checkout_fails_and_points_at_init(tools, verb, capsys): + assert dotfiles.main([verb]) == 1 + + assert tools.calls == [["chezmoi", verb]] + assert capsys.readouterr().err.splitlines()[-1] == ( + f"dotfiles: work: {verb} failed (not cloned; run dotfiles init)" + ) + + +@pytest.mark.parametrize("fmt", ["toml", "yaml", "json", "jsonc"]) +def test_secondary_shipping_a_config_template_is_refused(tools, repo, fmt, capsys): + # "refuse to run any verb or passthrough against a secondary source whose root contains + # .chezmoi..tmpl (toml, yaml, json, jsonc), with an error naming the file." + (checkout(repo, "work") / f".chezmoi.{fmt}.tmpl").write_text("") + + assert dotfiles.main(["apply"]) == 1 + + assert tools.calls == [["chezmoi", "apply"]] + err = capsys.readouterr().err + assert f"managed-work/.chezmoi.{fmt}.tmpl" in err + assert err.splitlines()[-1] == f"dotfiles: work: apply failed (ships .chezmoi.{fmt}.tmpl)" + + +def test_init_reads_sources_after_personal_init_then_clones_and_applies(tools, repo, config_home): + # "run chezmoi init (no args; picks up new *Once prompts) ... Then for each active source + # without /.git: git clone , run the config-template guard, then + # chezmoi --source --persistent-state apply". + tools.data = {} + tools.data_after_init = {"dotfiles_sources": {"work": URL}} + + assert dotfiles.main(["init"]) == 0 + + assert tools.calls == [ + ["chezmoi", "init"], + ["git", "clone", URL, str(repo / "managed-work")], + secondary(repo, config_home, "work", "apply"), + ] + + +def test_init_is_idempotent(tools, repo): + # "Idempotent: a second run prompts and clones nothing." + checkout(repo, "work") + + assert dotfiles.main(["init"]) == 0 + + assert tools.calls == [["chezmoi", "init"]] + + +def test_init_retries_a_clone_that_left_an_empty_directory(tools, repo): + # "A failed chezmoi init clone leaves an empty directory; test for /.git". + (repo / "managed-work").mkdir() + + assert dotfiles.main(["init"]) == 0 + + assert ["git", "clone", URL, str(repo / "managed-work")] in tools.calls + + +def test_init_guards_a_fresh_clone_before_applying_it(tools, repo, capsys): + # "Do not use chezmoi init --apply : it would render a shipped config template before + # the guard runs." + tools.clone_files = {".chezmoi.toml.tmpl": ""} + + assert dotfiles.main(["init"]) == 1 + + assert tools.calls == [["chezmoi", "init"], ["git", "clone", URL, str(repo / "managed-work")]] + assert capsys.readouterr().err.splitlines()[-1] == ( + "dotfiles: work: init failed (ships .chezmoi.toml.tmpl)" + ) + + +def test_failed_clone_is_reported(tools, capsys): + tools.clone_exit = 128 + + assert dotfiles.main(["init"]) == 1 + + assert capsys.readouterr().err.splitlines()[-1] == ( + "dotfiles: work: init failed (clone exit 128)" + ) + + +def test_update_clones_missing_sources_then_updates_every_source(tools, repo, config_home): + # "update runs the clone step before updating." + tools.data = {"dotfiles_sources": {"work": URL, "alpha": URL}} + checkout(repo, "alpha") + + assert dotfiles.main(["update", "-v"]) == 0 + + assert tools.calls == [ + ["chezmoi", "update", "-v"], + secondary(repo, config_home, "alpha", "update", "-v"), + ["git", "clone", URL, str(repo / "managed-work")], + secondary(repo, config_home, "work", "update", "-v"), + ] + + +def test_passthrough_sets_source_and_state_only(tools, repo, config_home): + # "Passthrough dotfiles : sets --source and --persistent-state only. + # Works for a present checkout even when unconfigured." + tools.data = {} + checkout(repo, "work") + + assert dotfiles.main(["work", "diff", "~/.config/fish/work/env.fish"]) == 0 + + assert tools.calls == [ + secondary(repo, config_home, "work", "diff", "~/.config/fish/work/env.fish") + ] + + +def test_passthrough_runs_the_config_template_guard(tools, repo, capsys): + (checkout(repo, "work") / ".chezmoi.jsonc.tmpl").write_text("") + + assert dotfiles.main(["work", "apply"]) == 1 + + assert tools.calls == [] + assert "managed-work/.chezmoi.jsonc.tmpl" in capsys.readouterr().err + + +@pytest.mark.parametrize( + ("argv", "message"), + [ + (["work", "purge"], "refusing purge"), + (["work", "--config", "other.toml", "purge"], "refusing purge"), + (["work", "init"], "use dotfiles init"), + (["work", "-v", "init", "--purge"], "use dotfiles init"), + (["work", "--config", "other.toml", "init"], "use dotfiles init"), + (["work", "apply", "--", "--source=/elsewhere"], "refusing --"), + (["work", "apply", "--init"], "refusing --init"), + (["work", "apply", "--init=true"], "refusing --init"), + (["personal", "apply"], "use chezmoi"), + (["missing", "apply"], "no checkout at"), + (["-x", "apply"], "invalid source name"), + ([".hidden", "apply"], "invalid source name"), + (["../managed-work", "apply"], "invalid source name"), + (["work/../x", "apply"], "invalid source name"), + (["work.x", "apply"], "invalid source name"), + ([], "usage"), + ], + ids=[ + "purge", + "purge-after-a-flag-value", + "init", + "init-after-a-flag", + "init-after-a-flag-value", + "end-of-flags", + "init-flag", + "init-flag-with-value", + "personal", + "missing-checkout", + "leading-dash", + "leading-dot", + "escapes-the-repo", + "escapes-after-a-valid-start", + "invalid-tail", + "no-arguments", + ], +) +def test_passthrough_usage_errors(tools, repo, argv, message, capsys): + # "Refuses purge with a clear error. Personal is not addressable (dotfiles personal is an + # error; use chezmoi)." init would clone and prompt outside dotfiles init. + checkout(repo, "work") + + assert dotfiles.main(argv) == 2 + + assert tools.calls == [] + assert message in capsys.readouterr().err + + +@pytest.mark.parametrize("name", ["../x", "work/../x"]) +def test_registry_name_that_escapes_the_repo_fails_that_source(tools, name, capsys): + tools.data = {"dotfiles_sources": {name: URL}} + + assert dotfiles.main(["apply"]) == 1 + + assert tools.calls == [["chezmoi", "apply"]] + assert capsys.readouterr().err.splitlines()[-1] == ( + f"dotfiles: {name}: apply failed (invalid source name)" + ) + + +@pytest.mark.parametrize("flag", ["-h", "--help"]) +def test_help_prints_usage(tools, flag, capsys): + assert dotfiles.main([flag]) == 0 + + assert tools.calls == [] + assert "usage: dotfiles" in capsys.readouterr().out + + +@pytest.mark.parametrize("flag", ["-n", "--dry-run"]) +@pytest.mark.parametrize("verb", ["init", "update"]) +def test_dry_run_skips_cloning(tools, verb, flag, capsys): + assert dotfiles.main([verb, flag]) == 0 + + assert tools.calls == [["chezmoi", verb, flag]] + assert "dotfiles: work: dry run skips cloning managed-work" in capsys.readouterr().err + + +def test_init_forwards_flags_to_the_fresh_clone_apply(tools, repo, config_home): + assert dotfiles.main(["init", "-v", "--force"]) == 0 + + assert tools.calls == [ + ["chezmoi", "init", "-v", "--force"], + ["git", "clone", URL, str(repo / "managed-work")], + secondary(repo, config_home, "work", "apply", "-v", "--force"), + ] + + +def test_passthrough_returns_chezmoi_exit_code(tools, repo): + checkout(repo, "work") + tools.exit_codes["work"] = 3 + + assert dotfiles.main(["work", "apply"]) == 3 + + +def test_missing_chezmoi_is_reported(monkeypatch, capsys): + def missing(args, **_kwargs): + raise FileNotFoundError(2, "No such file or directory", args[0]) + + monkeypatch.setattr(subprocess, "run", missing) + + assert dotfiles.main(["apply"]) == 127 + + assert capsys.readouterr().err.strip() == "dotfiles: chezmoi was not found on PATH" + + +def test_failed_registry_query_is_reported(tools, monkeypatch, capsys): + def failing_data(args, **kwargs): + if args[:2] == ["chezmoi", "data"]: + if kwargs.get("check"): + raise subprocess.CalledProcessError(1, args, "", "chezmoi: config error\n") + return subprocess.CompletedProcess(args, 1, "", "chezmoi: config error\n") + return tools(args, **kwargs) + + monkeypatch.setattr(subprocess, "run", failing_data) + + assert dotfiles.main(["apply"]) == 1 + + assert capsys.readouterr().err.strip() == ( + "dotfiles: chezmoi data --format json failed: chezmoi: config error" + ) + + +def test_failed_apply_after_a_fresh_clone_points_at_apply(tools, capsys): + # A rerun of init skips the existing checkout, so only apply recovers it. + tools.exit_codes["work"] = 1 + + assert dotfiles.main(["init"]) == 1 + + assert capsys.readouterr().err.splitlines()[-1] == ( + "dotfiles: work: init failed (apply exit 1; fix it, then run dotfiles apply)" + ) + + +@pytest.mark.parametrize( + "override", + [["--source=/elsewhere"], ["-S", "/elsewhere"], ["--persistent-state=x.boltdb"]], + ids=["long", "short", "state"], +) +def test_passthrough_source_and_state_outvote_a_user_override(tools, repo, config_home, override): + # "sets --source and --persistent-state"; chezmoi takes the last value of a repeated flag. + checkout(repo, "work") + + assert dotfiles.main(["work", *override, "apply"]) == 0 + + assert tools.calls == [secondary(repo, config_home, "work", *override, "apply")] + + +def test_config_template_under_chezmoiroot_is_refused(tools, repo, capsys): + # chezmoi reads the config template from the directory that .chezmoiroot names. + source = checkout(repo, "work") + (source / ".chezmoiroot").write_text("home\n") + (source / "home").mkdir() + (source / "home" / ".chezmoi.toml.tmpl").write_text("") + + assert dotfiles.main(["work", "apply"]) == 1 + + assert tools.calls == [] + assert "managed-work/home/.chezmoi.toml.tmpl" in capsys.readouterr().err diff --git a/tests/test_dotfiles_chezmoi.py b/tests/test_dotfiles_chezmoi.py new file mode 100644 index 0000000..ab3a706 --- /dev/null +++ b/tests/test_dotfiles_chezmoi.py @@ -0,0 +1,89 @@ +"""Smoke test of the dotfiles wrapper against a real chezmoi binary. + +test_dotfiles.py fakes chezmoi; this test checks the parts the fake assumes, such as the +output of chezmoi source-path and chezmoi data. CI installs no chezmoi, so it skips there. +""" + +import os +import shutil +import subprocess +import sys +from pathlib import Path + +import pytest + +_SCRIPT = Path(__file__).resolve().parent.parent / "managed/dot_local/bin/executable_dotfiles" + +pytestmark = pytest.mark.skipif(shutil.which("chezmoi") is None, reason="chezmoi is not on PATH") + + +def git(cwd: Path, *args: str) -> None: + subprocess.run(["git", *args], cwd=cwd, check=True, capture_output=True) # noqa: S603, S607 + + +@pytest.fixture +def machine(tmp_path, monkeypatch): + """A home directory whose chezmoi config names a primary source and one secondary.""" + home = tmp_path / "home" + config = home / ".config" + monkeypatch.setenv("HOME", str(home)) + monkeypatch.setenv("XDG_CONFIG_HOME", str(config)) + monkeypatch.setenv("GIT_CONFIG_GLOBAL", os.devnull) + monkeypatch.setenv("GIT_CONFIG_NOSYSTEM", "1") + + primary = tmp_path / "repo" / "managed" + primary.mkdir(parents=True) + (primary / "dot_primary").write_text("primary\n") + + origin = tmp_path / "work-origin" + origin.mkdir() + (origin / "dot_work").write_text("work\n") + git(origin, "init", "--quiet") + git(origin, "add", ".") + git(origin, "-c", "user.name=T", "-c", "user.email=t@example.invalid", "commit", "-qm", "init") + + (config / "chezmoi").mkdir(parents=True) + (config / "chezmoi" / "chezmoi.toml").write_text( + f'sourceDir = "{primary}"\n\n[data.dotfiles_sources]\nwork = "{origin}"\n' + ) + return home + + +def dotfiles(*args: str) -> subprocess.CompletedProcess[str]: + return subprocess.run( # noqa: S603 + [sys.executable, str(_SCRIPT), *args], capture_output=True, text=True, check=False + ) + + +def test_init_clones_and_applies_the_secondary_with_its_own_state(machine): + result = dotfiles("init") + + assert result.returncode == 0, result.stderr + assert (machine / ".work").read_text() == "work\n" + assert (machine / ".config/chezmoi/chezmoistate-work.boltdb").is_file() + + +def test_aggregate_and_per_source_commands_act_on_the_cloned_secondary(machine): + assert dotfiles("init").returncode == 0 + (machine / ".work").write_text("drift\n") + + status = dotfiles("status") + managed = dotfiles("work", "managed") + apply = dotfiles("apply", "--force") + + assert status.returncode == 0, status.stderr + assert apply.returncode == 0, apply.stderr + assert (machine / ".primary").read_text() == "primary\n" + assert (machine / ".work").read_text() == "work\n" + assert ".work" in status.stdout + assert managed.stdout.split() == [".work"] + + +@pytest.mark.usefixtures("machine") +def test_per_source_flags_outvote_a_source_override(tmp_path): + # chezmoi takes the last value of a repeated flag, and dotfiles appends its own. + assert dotfiles("init").returncode == 0 + + managed = dotfiles("work", f"--source={tmp_path / 'repo' / 'managed'}", "managed") + + assert managed.stdout.split() == [".work"], managed.stderr