Skip to content

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.

Release v0.46.3

Louis Choquel916e8955f81e
diff --git a/.badges/tests.json b/.badges/tests.json
index b580eb8a4..13eb9eb7b 100644
--- a/.badges/tests.json
+++ b/.badges/tests.json
@@ -1,7 +1,7 @@
{
"schemaVersion": 1,
"label": "tests",
- "message": "10519",
+ "message": "10522",
"color": "blue",
"cacheSeconds": 300
}
\ No newline at end of file
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.toml
index 7e9568718..7bb5f4ba9 100644
--- a/.drift/acks/cli-docs.toml
+++ b/.drift/acks/cli-docs.toml
@@ -1,8 +1,8 @@
contract = "cli-docs"
-digest = "sha256:530a92f6f7fc70d71971da1903871a8504ee180563edca29af83118ba74f6cfe"
+digest = "sha256:c9397a992e49ffb14028f68fde3587b3127f88f7928519a75c0f0f9eabc7312f"
reviewed_by = "Claude (Opus 5 (1M context))"
-reviewed_at = "2026-08-18T12:29:11Z"
-rationale = "init_config now writes a .pipelex/.gitignore, so pipelex init has a new user-visible artifact. Found one stale target and fixed it: the What Gets Initialized list in docs/tools/cli/init.md is a set claim about what the command creates, and it rots by omission - the new file appears nowhere in it - so I added the entry rather than leaving the list quietly incomplete. Also extended the backup section of docs/tools/cli/migrate.md, since migrate ensures the same file for a directory that predates it. Re-derived the reach and the guard from the code rather than from any docstring: both pipelex init and pipelex-agent init call init_config, and both migrate commands call migrate_config_directories, so the write is on every path; each call site guards it with 'if not dry_run', and agent_migrate_cmd passes dry_run = not yes while the bare command's first pass is dry_run=True, which is what keeps the agent-CLI contract's claim that migrate writes only with --yes true. No flag, format, stream, structured field, verdict or exit code moved, so pipelex/cli/agent_cli/CLAUDE.md needed no edit - I checked its migrate report contract line and its migrate command-table row specifically."
+reviewed_at = "2026-08-18T14:03:11Z"
+rationale = "pipelex migrate now ensures the config-directory .gitignore on its clean early-return path, so the reach of that file changed and the account in docs/tools/cli/migrate.md was stale by omission: it read as any real migrate, when the write pass was in fact the only site, which excluded exactly the machines that have nothing to migrate. Extended that paragraph to say the rule lands on a run that finds nothing to carry forward, and that a declined migration still writes nothing. init.md needed no edit since the pipelex init path is untouched. Re-derived the agent-CLI claims from the code rather than from the previous ack: agent_migrate_cmd passes dry_run = not yes into migrate_config_directories and the ensure sits under if not dry_run, so the migrate row claim that it writes only with --yes still holds, and the new write is neither reported nor rendered, so the migrate report-contract line is unchanged. Also re-checked the claim that doctor --fix runs the same run: doctor reaches migrate_config_directories with dry_run False through apply_pending_migrations, so that stays true for the pending-migration case the sentence describes."
[trigger_files]
"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
@@ -105,7 +105,7 @@ rationale = "init_config now writes a .pipelex/.gitignore, so pipelex init has a
"pipelex/cli/commands/init/ui/types.py" = "blob:1361f29ca95bacc90bca90ea6c0e39f44b6734ab"
"pipelex/cli/commands/login/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/commands/login/command.py" = "blob:ace1db9879626cc1722adaac12761aadaa6b24ed"
-"pipelex/cli/commands/migrate_cmd.py" = "blob:ffd3b0ff4fb8448bd03204b4381fb4f214a88271"
+"pipelex/cli/commands/migrate_cmd.py" = "blob:da0a6e4d2f4f730ec27a084f0a013debe10217b0"
"pipelex/cli/commands/plugins_cmd.py" = "blob:9657b713c3650ff4a929e92ae68af453d896393e"
"pipelex/cli/commands/resolve_cmd.py" = "blob:2928a0e26eab7983367a59a78533f6618817feba"
"pipelex/cli/commands/run/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
diff --git a/.test_durations b/.test_durations
index 743ac828b..8ebbd9023 100644
--- a/.test_durations
+++ b/.test_durations
@@ -2456,6 +2456,9 @@
"tests/unit/pipelex/cli/test_method_resolver.py::TestResolveMethodTarget::test_resolve_method_from_url_with_sub_path": 0.0047,
"tests/unit/pipelex/cli/test_method_resolver.py::TestResolveMethodTarget::test_resolve_method_target_dispatches_to_local_path": 0.0982,
"tests/unit/pipelex/cli/test_method_resolver.py::TestResolveMethodTarget::test_resolve_method_target_dispatches_to_url": 0.0026,
+ "tests/unit/pipelex/cli/test_migrate_cmd_gitignore.py::TestTheCommandEnsuresTheGitignore::test_a_declined_migration_still_writes_nothing": 0.6871,
+ "tests/unit/pipelex/cli/test_migrate_cmd_gitignore.py::TestTheCommandEnsuresTheGitignore::test_a_dry_run_over_a_clean_machine_writes_nothing": 0.6738,
+ "tests/unit/pipelex/cli/test_migrate_cmd_gitignore.py::TestTheCommandEnsuresTheGitignore::test_a_machine_with_nothing_to_migrate_still_gets_the_rule": 0.6718,
"tests/unit/pipelex/cli/test_migrate_cmd_summary.py::TestTheCancelPath::test_cancelling_leaves_the_files_alone_and_exits_clean_when_nothing_needs_a_person": 0.0276,
"tests/unit/pipelex/cli/test_migrate_cmd_summary.py::TestTheCancelPath::test_cancelling_still_exits_non_zero_when_the_rehearsal_left_something_for_a_person": 0.1282,
"tests/unit/pipelex/cli/test_migrate_cmd_summary.py::TestTheSummaryPanel::test_a_write_the_run_refused_still_says_nothing_was_written": 0.0428,
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7de24ef40..1fc5c5236 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
# Changelog
+## [v0.46.3] - 2026-08-18
+
+### Fixed
+
+- **The configuration-directory `.gitignore` now reaches machines with nothing to migrate:** v0.46.2 added a `.gitignore` inside `.pipelex/` to keep migration backups out of `git status`, but `pipelex migrate` only wrote it on a run that actually had a file to carry forward. A machine already at the current schema was reported clean and returned before the write pass, so it never got the rule — and that is the state every user is in between schema changes, which meant in practice almost nobody received it. Any real (non-`--dry-run`) `pipelex migrate` now writes it whether or not there is anything to migrate; a run whose migration you decline still writes nothing at all.
+
## [v0.46.2] - 2026-08-18
### Fixed
diff --git a/docs/migration-ledger.md b/docs/migration-ledger.md
index 615308c1c..c8b1f9746 100644
--- a/docs/migration-ledger.md
+++ b/docs/migration-ledger.md
@@ -677,7 +677,7 @@ The name is the source file's whole name, extension included, followed by `.bak.
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.
+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. **Including the run that finds every file already at the current schema**, which is not the edge case it sounds like: that is the state a machine is in from the moment it migrates once until the next schema change, so it is what most users' next `migrate` actually does, and tying the rule to the write pass alone would have delivered it to almost nobody. The one real run that does not write it is the one whose migration the user declined — "nothing was written" has to stay true of the whole directory, convenience file included, and the next run writes 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.
The order of the three steps is itself a guarantee. The backup is written **first**, so there is never a moment with a rewritten file and no copy of the original; the older backups are pruned **last**, so there is never a moment with no backup at all; and a write that fails before touching the file takes its own fresh backup with it, so a failed run leaves the directory exactly as it found it. Nothing that happens after the file is written can un-write it in the report: an older backup that will not prune, or a temp file the transaction could not remove, is a warning on a migrated file, never a blocked one.
diff --git a/docs/tools/cli/migrate.md b/docs/tools/cli/migrate.md
index b9a7fb2cd..f462e1f22 100644
--- a/docs/tools/cli/migrate.md
+++ b/docs/tools/cli/migrate.md
@@ -32,7 +32,7 @@ Within a file it repairs, it only ever undoes a change *we* made. A key you adde
Every file it changes is copied first, beside itself, as `<file>.bak.<UTC timestamp>` — with the original file's permissions, not your umask. The copy is on disk before the file is replaced, and the replacement is atomic: there is never a moment when your configuration is half-written.
-Those copies are ours, not part of your project, so the command keeps them out of your way: it writes a `.gitignore` inside the configuration directory itself, ignoring exactly the timestamped copies it makes. You will see the `.gitignore` — commit it, and your teammates get the same quiet. If you already have one there, it is left alone. A `<file>.rescue.<timestamp>` copy is deliberately *not* ignored: one of those only exists because a write could not be vouched for, and seeing it is how you find out.
+Those copies are ours, not part of your project, so the command keeps them out of your way: it writes a `.gitignore` inside the configuration directory itself, ignoring exactly the timestamped copies it makes. You will see the `.gitignore` — commit it, and your teammates get the same quiet. If you already have one there, it is left alone. You get it from any run that is allowed to write, including one that finds nothing to migrate — so a configuration directory that predates this picks the rule up on your next `pipelex migrate`, whether or not it has anything to carry forward. A `<file>.rescue.<timestamp>` copy is deliberately *not* ignored: one of those only exists because a write could not be vouched for, and seeing it is how you find out.
Running it twice is the same as running it once. Nothing is skipped on the basis of a version record, because there is no version record; every run replays the whole history and leaves alone whatever is already current. A file that is already up to date comes back byte for byte identical.
diff --git a/pipelex/cli/commands/migrate_cmd.py b/pipelex/cli/commands/migrate_cmd.py
index ffd3b0ff4..da0a6e4d2 100644
--- a/pipelex/cli/commands/migrate_cmd.py
+++ b/pipelex/cli/commands/migrate_cmd.py
@@ -34,7 +34,7 @@ from rich.markup import escape
from rich.panel import Panel
from rich.prompt import Confirm
-from pipelex.migration.run import config_directories_to_migrate, migrate_config_directories
+from pipelex.migration.run import config_directories_to_migrate, ensure_config_dir_gitignores, migrate_config_directories
from pipelex.runtime_hub import get_console
from pipelex.suggested_fix import WILDCARD_SEGMENT, DeleteKeyOp, DeleteTableOp, MoveKeyOp, RemapValueOp, RenameTableKeyOp
@@ -75,6 +75,12 @@ def migrate_cmd(*, dry_run: bool = False, yes: bool = False) -> None:
_print_report(report=rehearsal, wrote=False)
if rehearsal.is_clean:
+ if not dry_run:
+ # The write pass is what normally leaves the config-directory `.gitignore` behind, and
+ # this return means it is never going to run. A machine with nothing to carry forward
+ # still owns the directory pipelex writes backups into, so the rule is ensured here —
+ # otherwise it would reach only the machines that happened to have a migration pending.
+ ensure_config_dir_gitignores(config_dirs=config_dirs)
console.print(_panel(message=_NOTHING_TO_DO, style="green"))
console.print()
return
diff --git a/pipelex/migration/run.py b/pipelex/migration/run.py
index 0e8b4356a..8dcdb7892 100644
--- a/pipelex/migration/run.py
+++ b/pipelex/migration/run.py
@@ -53,6 +53,25 @@ def config_directories_to_migrate() -> list[Path]:
return config_manager.existing_config_dirs
+def ensure_config_dir_gitignores(*, config_dirs: list[Path]) -> None:
+ """Give each walked directory the `.gitignore` that keeps our backups out of `git status`.
+
+ Named and separate because the rule is not a migration. It belongs to any write-authorized run
+ over these directories, and a run that finds every file already at the current schema is still
+ one of those — it is in fact the common one, since a machine is in that state from the moment
+ it has migrated once until the next schema change. Tying the rule to the write pass alone meant
+ it reached only the machines that happened to have something pending, which is close to nobody.
+
+ A user who already had a `.pipelex/` before the rule shipped therefore gets it from the very
+ run that would otherwise dirty their repository, and not only from a fresh `init`.
+
+ Never called on a dry run, in any caller: `--dry-run` promises the disk is untouched, and a
+ convenience file is still a write.
+ """
+ for directory in config_dirs:
+ ensure_config_dir_gitignore(directory=directory)
+
+
def migrate_config_directories(*, config_dirs: list[Path], dry_run: bool) -> MigrationReport:
"""Replay every surface's shipped ledger over every claimed file in the given directories.
@@ -62,13 +81,14 @@ def migrate_config_directories(*, config_dirs: list[Path], dry_run: bool) -> Mig
A real run is also where each walked directory gets the `.gitignore` that keeps the backups
it is about to write out of the user's `git status` — here rather than in `migrate_directories`
on purpose, because that function is replayed by the gates over documents that are never
- written anywhere, and a filesystem side effect there would follow them. A user who already had
- a `.pipelex/` before this shipped therefore gets the rule from the very run that would
- otherwise dirty their repository, and not only from a fresh `init`.
+ written anywhere, and a filesystem side effect there would follow them.
+
+ This covers the run that *writes*. It is deliberately not the only place the rule is ensured:
+ a run with nothing to carry forward never reaches this function at all, and that is the state
+ most machines are in. See `ensure_config_dir_gitignores`.
"""
if not dry_run:
- for directory in config_dirs:
- ensure_config_dir_gitignore(directory=directory)
+ ensure_config_dir_gitignores(config_dirs=config_dirs)
return migrate_directories(
registry=build_config_surface_registry(),
migration_dir=packaged_migration_dir(),
diff --git a/pyproject.toml b/pyproject.toml
index c764884cd..54a673f2e 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "pipelex"
-version = "0.46.2"
+version = "0.46.3"
description = "Execute composable AI methods declared in the MTHDS open standard"
authors = [{ name = "Evotis S.A.S.", email = "[email protected]" }]
maintainers = [{ name = "Pipelex staff", email = "[email protected]" }]
diff --git a/tests/unit/pipelex/cli/test_migrate_cmd_gitignore.py b/tests/unit/pipelex/cli/test_migrate_cmd_gitignore.py
new file mode 100644
index 000000000..bad56308d
--- /dev/null
+++ b/tests/unit/pipelex/cli/test_migrate_cmd_gitignore.py
@@ -0,0 +1,82 @@
+"""Whether `pipelex migrate` leaves the config-directory `.gitignore` behind, as a user runs it.
+
+`tests/unit/pipelex/migration/test_config_dir_gitignore.py` proves the engine writes the rule when
+it writes anything. That is one layer below where the user stands, and the command has an early
+return the engine never sees: a machine whose files are all at the current schema is reported clean
+and the write pass is never called at all.
+
+That machine is the steady state, not an edge case — it is every user who migrated once and then
+upgraded, which is exactly the population the rule was promised to. Asserting the wiring on the
+engine alone is how the gap stayed invisible, so it is asserted here on the command.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+from rich.console import Console
+
+from pipelex.cli.commands import migrate_cmd as migrate_cmd_module
+from pipelex.cli.commands.migrate_cmd import migrate_cmd
+from pipelex.migration.gitignore import CONFIG_DIR_GITIGNORE_NAME
+from pipelex.migration.goldens import pre_history_document_path
+from pipelex.migration.ledger import packaged_migration_dir
+from pipelex.system.configuration.config_surface import TELEMETRY_CONFIG_SURFACE_ID
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+ from pytest_mock import MockerFixture
+
+
+def console(mocker: MockerFixture) -> Console:
+ recorded = Console(width=200, record=True, color_system=None)
+ mocker.patch.object(migrate_cmd_module, "get_console", return_value=recorded)
+ return recorded
+
+
+def clean_machine(tmp_path: Path, mocker: MockerFixture) -> Path:
+ """One configuration directory with nothing in it for the ledger to carry forward."""
+ config_dir = tmp_path / ".pipelex"
+ config_dir.mkdir()
+ mocker.patch.object(migrate_cmd_module, "config_directories_to_migrate", return_value=[config_dir])
+ return config_dir
+
+
+class TestTheCommandEnsuresTheGitignore:
+ def test_a_machine_with_nothing_to_migrate_still_gets_the_rule(self, clean_machine: Path, console: Console) -> None:
+ migrate_cmd(yes=True)
+
+ # Pins that this went down the clean early return rather than the write pass, so the test
+ # cannot quietly start proving what the engine tests already prove.
+ assert "current schema" in console.export_text()
+ assert (clean_machine / CONFIG_DIR_GITIGNORE_NAME).is_file()
+
+ def test_a_dry_run_over_a_clean_machine_writes_nothing(self, clean_machine: Path, console: Console) -> None:
+ """`--dry-run` promises the disk is untouched, and that promise outranks the convenience."""
+ migrate_cmd(dry_run=True)
+
+ assert "current schema" in console.export_text()
+ assert not (clean_machine / CONFIG_DIR_GITIGNORE_NAME).exists()
+
+ def test_a_declined_migration_still_writes_nothing(self, tmp_path: Path, mocker: MockerFixture, console: Console) -> None:
+ """The deliberate other half: a person's "no" to the write is a no to every write in the run.
+
+ The rule lands on the clean path because no question was pending there. Here one was, and it
+ was answered no — "Migration cancelled — nothing was written" has to stay true of the whole
+ directory, the convenience file included.
+ """
+ config_dir = tmp_path / ".pipelex"
+ config_dir.mkdir()
+ old_shape = pre_history_document_path(migration_dir=packaged_migration_dir(), surface_id=TELEMETRY_CONFIG_SURFACE_ID, schema_version=2)
+ (config_dir / "telemetry.toml").write_text(old_shape.read_text(encoding="utf-8"), encoding="utf-8")
+ mocker.patch.object(migrate_cmd_module, "config_directories_to_migrate", return_value=[config_dir])
+ mocker.patch.object(migrate_cmd_module.Confirm, "ask", return_value=False)
+
+ migrate_cmd()
+
+ assert "cancelled" in console.export_text().lower()
+ assert not (config_dir / CONFIG_DIR_GITIGNORE_NAME).exists()
diff --git a/uv.lock b/uv.lock
index 521d1b5be..66967823d 100644
--- a/uv.lock
+++ b/uv.lock
@@ -3303,7 +3303,7 @@ wheels = [
[[package]]
name = "pipelex"
-version = "0.46.2"
+version = "0.46.3"
source = { editable = "." }
dependencies = [
{ name = "aiofiles" },
diff --git a/wip/drift-contracts/dogfood-log.md b/wip/drift-contracts/dogfood-log.md
index 66eab8970..34197a0b9 100644
--- a/wip/drift-contracts/dogfood-log.md
+++ b/wip/drift-contracts/dogfood-log.md
@@ -116,3 +116,4 @@ The surviving finding is real and small: the table under "What a programmatic ca
- **2026-08-18 · cli-docs · real-catch** — Triggered by `init_config` gaining a call to `ensure_config_dir_gitignore`, the fix for `pipelex migrate` dropping untracked `.bak.<stamp>` files into a user's `git status`. The catch is the plainest kind and the kind grep cannot find: `docs/tools/cli/init.md`'s **What Gets Initialized** list is a set claim about what the command creates, and a new artifact falsifies it by *absence* — searching the target for `.gitignore` returns nothing, which reads identically to "not mentioned because not relevant". Only reading the page for its quantified claims surfaces it. Worth recording that the contract also earned its keep on a claim that turned out **fine**: `agent_cli/CLAUDE.md` states that `migrate` writes only with `--yes`, and a new write on the migrate path is exactly what would falsify that — re-derived from the code (`agent_migrate_cmd` passes `dry_run = not yes`; the bare command's first pass is `dry_run=True`; both call sites guard the new write with `if not dry_run`) rather than from the guard's own docstring, which is the artifact-not-prose rule applied to a claim I had written myself minutes earlier and was therefore the least trustworthy prose in the repo.
Verdict signal: this breaks `cli-docs`'s run of clean-passes, and it does so on the cheapest possible trigger — a single new call in one CLI module. The contract opened on the right thing and pointed at the right page. No narrowing to propose.
+- **2026-08-18 · cli-docs · real-catch** — A one-line fix to `migrate_cmd.py` (ensure the config-dir `.gitignore` on the clean early-return path) opened the contract, and the review caught the CLI page making a set claim about when you get that file that the fix had just changed — the sort of staleness that reads fine in the diff because the false sentence never mentions what falsified it.