Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
Answer the #1123 review threads: tighten the backup ignore glob and guard its cleanup
Louis Choquel03d95bca035e
diff --git a/.badges/tests.json b/.badges/tests.jsonindex c08c8d152..b580eb8a4 100644--- a/.badges/tests.json+++ b/.badges/tests.json@@ -1,7 +1,7 @@{"schemaVersion": 1,"label": "tests",- "message": "10517",+ "message": "10519","color": "blue","cacheSeconds": 300}\ No newline at end of filediff --git a/.test_durations b/.test_durationsindex 13bd8d5cd..743ac828b 100644--- a/.test_durations+++ b/.test_durations@@ -6265,6 +6265,8 @@"tests/unit/pipelex/migration/test_config_dir_gitignore.py::TestARealRunEnsuresIt::test_initializing_a_config_directory_writes_it": 1.1641,"tests/unit/pipelex/migration/test_config_dir_gitignore.py::TestARealRunEnsuresIt::test_migrating_a_directory_leaves_the_rule_behind": 1.2049,"tests/unit/pipelex/migration/test_config_dir_gitignore.py::TestBackupIgnorePattern::test_a_rescue_copy_stays_visible": 1.1969,+ "tests/unit/pipelex/migration/test_config_dir_gitignore.py::TestBackupIgnorePattern::test_a_stamp_of_the_wrong_shape_is_not_one_of_ours": 0.5799,+ "tests/unit/pipelex/migration/test_config_dir_gitignore.py::TestBackupIgnorePattern::test_a_user_named_copy_is_still_theirs_when_it_happens_to_start_with_a_digit": 0.5758,"tests/unit/pipelex/migration/test_config_dir_gitignore.py::TestBackupIgnorePattern::test_it_does_not_hide_a_real_configuration_file": 1.1945,"tests/unit/pipelex/migration/test_config_dir_gitignore.py::TestBackupIgnorePattern::test_it_leaves_a_copy_the_user_named_themselves_alone": 1.2,"tests/unit/pipelex/migration/test_config_dir_gitignore.py::TestBackupIgnorePattern::test_it_matches_a_name_the_backup_module_actually_writes": 1.1902,diff --git a/docs/migration-ledger.md b/docs/migration-ledger.mdindex 2f4d442ca..615308c1c 100644--- a/docs/migration-ledger.md+++ b/docs/migration-ledger.md@@ -673,7 +673,9 @@ Always back up, before writing. Exactly one backup per file — a successful runThe name is the source file's whole name, extension included, followed by `.bak.` and a compact UTC stamp: `pipelex.toml` backs up to `pipelex.toml.bak.20260815T120000Z`. Extension-included so a backup never shadows a real `.toml`, and separator-free so no filesystem objects to it. Pruning matches that whole shape, stamp included — a copy the user made by hand under a name that merely starts the same way (`pipelex.toml.bak.notes`) is theirs, and is never touched.-**A backup does not belong in the user's `git status`, and pipelex writes the rule that keeps it out.** A project's `.pipelex/` is normally inside a git repository, so one run would otherwise put a dozen untracked `.bak.<stamp>` files in front of the user and leave them to work out which are ours. Pipelex therefore keeps a `.gitignore` *inside* the configuration directory, carrying one rule — `*.bak.[0-9]*Z`, built from the same infix and stamp shape the namer uses, so renaming either cannot leave a rule that matches nothing. In-directory rather than in the repository root because the walk is `~/.pipelex/` and the project `.pipelex/` and nothing else: every backup a migration can write inside a repository is already under a directory pipelex owns, which makes a local file a complete answer that needs no idea where the root is and never edits a file the user maintains for their whole project.+**A backup does not belong in the user's `git status`, and pipelex writes the rule that keeps it out.** A project's `.pipelex/` is normally inside a git repository, so one run would otherwise put a dozen untracked `.bak.<stamp>` files in front of the user and leave them to work out which are ours. Pipelex therefore keeps a `.gitignore` *inside* the configuration directory, carrying one rule — `*.bak.` followed by the exact stamp shape, spelled out digit class by digit class, built from the same infix the namer uses so renaming it cannot leave a rule that matches nothing. The stamp is spelled out in full rather than abbreviated to a `[0-9]*` run, because a run would also swallow a copy the user named themselves along the lines of `pipelex.toml.bak.1-notesZ` — one pruning explicitly refuses to touch, and hiding a file we decline to manage is the worse half of both answers. In-directory rather than in the repository root because the walk is `~/.pipelex/` and the project `.pipelex/` and nothing else, so a local file needs no idea where the root is and never edits a file the user maintains for their whole project.++One backup is deliberately out of reach of this rule. A configuration file that is a symlink is migrated through to the file it names, so its backup lands beside *that* file — in a dotfiles directory, which is the user's and not ours. Pipelex does not follow it there: writing into the `.gitignore` of somebody's whole dotfiles repository is a larger liberty than the single untracked copy it would hide.The file is written by `pipelex init`, and by any real (non-`--dry-run`) `pipelex migrate` — the second so that a machine whose `.pipelex/` predates this gets the rule from the very run that would otherwise dirty it. It is **create-if-absent and nothing more**: once a `.gitignore` is there it is a file in the user's repository, possibly theirs, possibly ours with a line taken out on purpose, and re-asserting a rule into it every run would be a tool arguing with its user. Two omissions are deliberate. A `.rescue.` copy is **not** ignored — it exists only because a write could not be vouched for and the report tells the user to go and get it, so turning up in `git status` is that reminder working. Neither is a copy the user named themselves: pruning already refuses to touch a `pipelex.toml.bak.notes` on the grounds that it is theirs, and hiding it from their own `git status` would be the same mistake pointed the other way.diff --git a/pipelex/migration/gitignore.py b/pipelex/migration/gitignore.pyindex f4e03cb19..0587434c8 100644--- a/pipelex/migration/gitignore.py+++ b/pipelex/migration/gitignore.py@@ -8,11 +8,16 @@ them writes a slightly different one, or forgets, and a tool that dirties a repoit runs stops getting run.**Why the rule lives here and not in the user's root `.gitignore`.** The walk is the global-`~/.pipelex/` and the project `.pipelex/`, and nothing else (see `run.py`), so every backup a-migration can ever write inside a repository is under a directory pipelex already owns. That makes-a `.gitignore` *in* that directory a complete answer — it needs no knowledge of where the-repository root is, survives the directory being moved or vendored, and never reaches into a file-the user maintains for their whole project.+`~/.pipelex/` and the project `.pipelex/`, and nothing else (see `run.py`), so a backup written+under a directory pipelex already owns is answered by a `.gitignore` *in* that directory — one that+needs no knowledge of where the repository root is, survives the directory being moved or vendored,+and never reaches into a file the user maintains for their whole project.++**The one backup this does not reach, and why it is left.** A configuration file that is a symlink+is migrated through to the file it names, and its backup lands beside *that* file (see+`runner.migrate_file`) — in a dotfiles directory, which is the user's and not ours. The rule+deliberately does not follow it there: writing into the `.gitignore` of somebody's whole dotfiles+repository is a larger liberty than the one untracked copy it would hide.**The pattern is derived from the namer, not retyped.** `BACKUP_INFIX` is what`backup_path_for` actually writes; spelling `*.bak.…` again here would let a rename of the infix@@ -38,11 +43,25 @@ from pipelex.migration.backup import BACKUP_INFIXCONFIG_DIR_GITIGNORE_NAME = ".gitignore""""What the file is called inside `~/.pipelex/` or a project's `.pipelex/`."""-BACKUP_IGNORE_PATTERN = f"*{BACKUP_INFIX}[0-9]*Z"-"""The one rule the file carries: any name ending in the infix, a digit-led run, and the UTC `Z`.+_STAMP_GLOB = f"{'[0-9]' * 8}T{'[0-9]' * 6}Z"+"""The shape `BACKUP_STAMP_FORMAT` renders, written in the only vocabulary a `.gitignore` has.++A glob has no repetition count, so the eight-digit date and the six-digit time are spelled out+rather than abbreviated to a `[0-9]*` run. The run looks equivalent and is not: its `*` accepts+anything at all, so it also matches `pipelex.toml.bak.1-notesZ` — a name `existing_backups_of`+reads as the user's own and refuses to prune. Hiding a file we have just declined to manage is the+worse half of both answers.++Nothing translates the strftime string into this, on purpose: a parser for format directives is+more machinery than one constant is worth. What holds the two together is the test matching this+pattern against a name `backup_path_for` actually produced, which goes red if the stamp restamps.+"""++BACKUP_IGNORE_PATTERN = f"*{BACKUP_INFIX}{_STAMP_GLOB}"+"""The one rule the file carries: any name ending in the infix followed by exactly the stamp.-The digit and the trailing `Z` are what `BACKUP_STAMP_FORMAT` renders and what a name the user-chose does not, which is how `pipelex.toml.bak.notes` stays visible.+Exactly the stamp, rather than something stamp-shaped, is what keeps `pipelex.toml.bak.notes` — and+every other copy the user named themselves — visible in their own `git status`."""_GITIGNORE_CONTENT = f"""\@@ -90,6 +109,13 @@ def ensure_config_dir_gitignore(*, directory: Path) -> bool:handle.flush()os.fsync(handle.fileno())except OSError:- path.unlink(missing_ok=True)+ try:+ path.unlink(missing_ok=True)+ except OSError:+ # `missing_ok` covers a file that is gone, not a filesystem that says no — and the one+ # that just refused the write is exactly the one that can refuse the removal. Letting+ # that escape would turn a missing convenience rule into a failed migration, which is+ # the outcome every other branch of this function exists to avoid.+ passreturn Falsereturn Truediff --git a/tests/unit/pipelex/migration/test_config_dir_gitignore.py b/tests/unit/pipelex/migration/test_config_dir_gitignore.pyindex b8c983d60..405727245 100644--- a/tests/unit/pipelex/migration/test_config_dir_gitignore.py+++ b/tests/unit/pipelex/migration/test_config_dir_gitignore.py@@ -38,6 +38,20 @@ class TestBackupIgnorePattern:"""`existing_backups_of` refuses to prune one of these; the ignore rule must not hide it."""assert not fnmatch("pipelex.toml.bak.notes", BACKUP_IGNORE_PATTERN)+ def test_a_user_named_copy_is_still_theirs_when_it_happens_to_start_with_a_digit(self) -> None:+ """The near-miss the rule has to survive, since a user name is not required to avoid our shape.++ Pruning reads each of these as the user's file and leaves it standing. A rule loose enough+ to hide one would take the file out of the `git status` it is then never going to manage.+ """+ for name in ("pipelex.toml.bak.1-notesZ", "pipelex.toml.bak.2026notesZ", "pipelex.toml.bak.0Z"):+ assert not fnmatch(name, BACKUP_IGNORE_PATTERN), name++ def test_a_stamp_of_the_wrong_shape_is_not_one_of_ours(self) -> None:+ """The whole stamp is the evidence, so a name carrying only part of it is somebody else's."""+ for name in ("pipelex.toml.bak.2026T121441Z", "pipelex.toml.bak.20260818T1214410Z", "pipelex.toml.bak.20260818121441Z"):+ assert not fnmatch(name, BACKUP_IGNORE_PATTERN), name+def test_a_rescue_copy_stays_visible(self, tmp_path: Path) -> None:"""It is the one file the report tells the user to go and get — hiding it defeats the point."""rescue = rescue_path_for(path=tmp_path / "pipelex.toml", moment=MOMENT)@@ -57,7 +71,11 @@ class TestEnsureConfigDirGitignore:assert (tmp_path / CONFIG_DIR_GITIGNORE_NAME).read_text().splitlines()[-1] == BACKUP_IGNORE_PATTERNdef test_the_file_it_writes_actually_ignores_a_backup(self, tmp_path: Path) -> None:- """The end the whole change exists for, asserted against git itself rather than by eye."""+ """The end the whole change exists for: a real backup name, matched against the file's own rules.++ Read out of the written file and matched line by line, rather than against the constant, so+ a rule that never reached the file — or reached it commented out — is caught here.+ """ensure_config_dir_gitignore(directory=tmp_path)written = (tmp_path / CONFIG_DIR_GITIGNORE_NAME).read_text()diff --git a/wip/pr-1123-review-notes.md b/wip/pr-1123-review-notes.mdnew file mode 100644index 000000000..45f5284e7--- /dev/null+++ b/wip/pr-1123-review-notes.md@@ -0,0 +1,35 @@+# PR #1123 review follow-up — the one backup the config-directory `.gitignore` cannot reach++**Status:** Deferred from the v0.46.2 release review (2026-08-18). Not a regression — the gap arrives with the feature, and the feature is still a strict improvement over having no rule at all. What is deferred is the *remedy*, because every version of it is a design reversal rather than a fix.++**Reported by:** Codex (thread `PRRT_kwDOOwmMFc6aHHck`) and cubic (thread `PRRT_kwDOOwmMFc6aHLr8`), both against `pipelex/migration/run.py:69-71`. Both threads were left open on purpose.++## What is true++`migrate_config_directories` ensures a `.gitignore` in each *walked* configuration directory — `~/.pipelex/` and the project `.pipelex/`. But `migrate_file` resolves symlinks before it snapshots the file (`pipelex/migration/runner.py:42`, `read_file_snapshot(file_path.resolve())`), deliberately and with a comment saying so: an atomic replace of the link path would delete the link and leave the real file unmigrated. The backup is then named from the *resolved* path, so for a dotfiles setup — `.pipelex/pipelex.toml` symlinked to `~/dotfiles/pipelex.toml` — the `.bak.<stamp>` copy lands in `~/dotfiles/`, which the rule in `.pipelex/` cannot match. If that directory is itself a git repository, migrating dirties it, which is the exact workflow the feature exists to fix.++The behavior is covered by an existing test (`tests/unit/pipelex/migration/test_runner.py:602`), so this is a known, intended resolution — not an accident.++## Why nothing was changed++Two remedies present themselves, and both cost more than the gap:++- **Ensure a `.gitignore` beside the resolved backup too.** That means creating or relying on a `.gitignore` at the root of the user's dotfiles repository — a file they maintain for their whole project, which the design of this feature explicitly refuses to touch (`pipelex/migration/gitignore.py`, "never reaches into a file the user maintains for their whole project"). Writing there to hide one transient copy is a much larger liberty than the copy is worth.+- **Write the backup beside the link instead of the target.** That reverses a documented and tested decision about where a copy of a file belongs, and it would put the backup in a directory that is not the one holding the file it copies.++A third possibility exists and is the reason this is written down rather than closed: **do neither, and instead not back up through a symlink at all when the target is outside the walked directory** — reporting the file as one the migration will not rewrite on its own. That is a real behavior change with a real cost (a dotfiles user loses in-place migration), so it is a call for a human, not for a review pass on a release branch.++## What was done instead++The overclaim was removed. Both `pipelex/migration/gitignore.py`'s module docstring and `docs/migration-ledger.md` asserted that *every* backup a migration can write inside a repository is under a directory pipelex owns. That sentence is false under a symlink, and it is now replaced by an explicit statement of the exception and why the rule does not follow it.++## The open question++For a user whose `.pipelex/` configuration files are symlinks into a git-tracked dotfiles directory, should `pipelex migrate`:++1. keep today's behavior and accept that the backup dirties the target's repository (with the docs saying so, which is the current state);+2. leave the backup beside the link rather than the target;+3. decline to migrate through a symlink whose target is outside the walked directory, and report the file as one the user must handle; or+4. something else — e.g. name the escaped backup path in the migration report, so the user is told where the copy went rather than finding it in `git status`?++Option 4 is the cheapest and is worth considering on its own even if the answer to 1–3 is "keep today's behavior": the report already names paths, and a user who is told is not a user who is surprised.