From 810f50f8f14cb8123fd48268333c91b7d9995162 Mon Sep 17 00:00:00 2001 From: Ezreal Date: Thu, 30 Apr 2026 17:44:03 +0800 Subject: [PATCH 1/8] fix(profiles): reserve "main" + enforce _RESERVED_NAMES in create_profile MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes #17879. `hermes profile create main` succeeded today and produced session keys with the `agent:main:*` prefix — the exact prefix the default profile uses — re-introducing the cross-profile collision #12099 (and the in-flight #12266 fix) is meant to eliminate. The same hole let `root`, `hermes`, `test`, `tmp`, and `sudo` through too: `_RESERVED_NAMES` was defined but only consumed by `check_alias_collision()` (a wrapper-script-creation check), not by `validate_profile_name()` or `create_profile()`. Fix: - Add "main" to `_RESERVED_NAMES`. - Replace the one-name `if name == "default"` hardcode in `create_profile()` with a uniform `if name in _RESERVED_NAMES` check (the new error message still names the offending value and lists all reserved names). `validate_profile_name()` is intentionally left permissive so existing callers (`rename_profile`, `delete_profile`, `set_active_profile`, `export_profile`, `import_profile`, `resolve_profile_env`) keep working for any legacy `"main"` profile that may already exist on disk — only *creation* of a new reserved-name profile is restricted. Orthogonal to #12266: even after that PR lands, a user who runs `hermes profile create main` still hits the original collision because `_resolve_session_key_prefix("main")` evaluates to `"agent:main"`. This PR closes that gap permanently. Tests: `tests/hermes_cli/test_profiles.py::TestReservedNames` parametrises all seven reserved names and verifies (a) each is rejected, (b) the error message lists the offending name plus the full reserved set, (c) no orphan directory is left behind. All 102 existing profile tests still pass. (cherry picked from commit 7aebb2a94bf5d297d27797ab3a28a20391d3259e) --- hermes_cli/profiles.py | 12 ++++--- tests/hermes_cli/test_profiles.py | 53 +++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+), 4 deletions(-) diff --git a/hermes_cli/profiles.py b/hermes_cli/profiles.py index 12c98d10486e..cdf538070597 100644 --- a/hermes_cli/profiles.py +++ b/hermes_cli/profiles.py @@ -116,8 +116,9 @@ def _ignore(directory: str, names: List[str]) -> List[str]: "plugins", "memories", "knowledge", "preferences", }) -# Names that cannot be used as profile aliases -_RESERVED_NAMES = frozenset({"hermes", "default", "test", "tmp", "root", "sudo"}) +# Names that cannot be used as profile aliases or as new-profile names. +# "main" would collide with the default profile's agent:main session namespace. +_RESERVED_NAMES = frozenset({"hermes", "default", "main", "test", "tmp", "root", "sudo"}) # Hermes subcommands that cannot be used as profile names/aliases _HERMES_SUBCOMMANDS = frozenset({ @@ -818,8 +819,11 @@ def create_profile( "(cloning explicitly copies skills from the source profile)." ) canon = _canon_valid(name) - if canon == "default": - raise ValueError("Cannot create a profile named 'default' — it is the built-in profile (~/.hermes).") + if canon in _RESERVED_NAMES: + raise ValueError( + f"Cannot create a profile named {canon!r} — it is reserved. " + f"Reserved names: {', '.join(sorted(_RESERVED_NAMES))}." + ) profile_dir = get_profile_dir(canon) if profile_dir.exists() and named_profile_is_deleted(profile_dir): # Empty shells left by post-delete mkdir may be replaced. Identity files mean the diff --git a/tests/hermes_cli/test_profiles.py b/tests/hermes_cli/test_profiles.py index b7c7bf61a4f0..b9643e725232 100644 --- a/tests/hermes_cli/test_profiles.py +++ b/tests/hermes_cli/test_profiles.py @@ -314,6 +314,59 @@ def test_no_profiles_root_is_noop(self, profile_env): assert backfill_profile_envs(quiet=True) == [] +# =================================================================== +# TestReservedNames — regression coverage for the corner-case branch of +# #12099 in which a user could create a profile literally named "main" +# (or any other supposedly-reserved name) and re-introduce the original +# session-key collision because validate_profile_name() only enforced +# the regex, not _RESERVED_NAMES. +# =================================================================== + +class TestReservedNames: + """create_profile() must reject every entry in _RESERVED_NAMES.""" + + @pytest.mark.parametrize( + "name", + ["main", "hermes", "default", "test", "tmp", "root", "sudo"], + ) + def test_reserved_name_rejected(self, profile_env, name): + """Each reserved name must raise ValueError before any directory is + created. Without this guard, ``hermes profile create main`` would + succeed and silently produce ``agent:main:*`` session keys that + collide with the default profile — re-introducing #12099.""" + with pytest.raises(ValueError, match="reserved"): + create_profile(name, no_alias=True) + + def test_reserved_name_error_lists_all_reserved(self, profile_env): + """The error message should help the user pick a non-reserved name + without forcing them to read the source.""" + from hermes_cli.profiles import _RESERVED_NAMES + + with pytest.raises(ValueError) as exc_info: + create_profile("main", no_alias=True) + + message = str(exc_info.value) + # Mentions the offending name and at least a few reserved names so + # the user can immediately see what to avoid. + assert "'main'" in message + for reserved in ("hermes", "default", "main"): + assert reserved in message, f"error should list {reserved!r}; got: {message}" + assert sorted(_RESERVED_NAMES) == sorted( + {"hermes", "default", "main", "test", "tmp", "root", "sudo"} + ), "reserved set drift — update this test if intentional" + + def test_reserved_name_creates_no_directory(self, profile_env): + """Bug-shaped check: rejection must happen before mkdir, so a failed + attempt must not leave an orphan directory that blocks later use of + the same name once it stops being reserved.""" + from hermes_cli.profiles import get_profile_dir + + with pytest.raises(ValueError): + create_profile("main", no_alias=True) + + assert not get_profile_dir("main").exists() + + # =================================================================== # TestDeleteProfile # =================================================================== From ce433902c32bb984ff8ed76ff3070f49f27e3582 Mon Sep 17 00:00:00 2001 From: guicybercode Date: Sun, 13 Sep 2026 01:02:40 -0300 Subject: [PATCH 2/8] fix(profiles): preserve legacy main profiles across lifecycle operations --- hermes_cli/profile_distribution.py | 4 +- hermes_cli/profiles.py | 24 ++-- .../hermes_cli/test_profile_main_namespace.py | 106 ++++++++++++++++++ tests/hermes_cli/test_profiles.py | 53 --------- .../docs/user-guide/profile-distributions.md | 2 +- website/docs/user-guide/profiles.md | 2 + 6 files changed, 128 insertions(+), 63 deletions(-) create mode 100644 tests/hermes_cli/test_profile_main_namespace.py diff --git a/hermes_cli/profile_distribution.py b/hermes_cli/profile_distribution.py index 2734d2a82210..d06e9a363eb6 100644 --- a/hermes_cli/profile_distribution.py +++ b/hermes_cli/profile_distribution.py @@ -305,7 +305,7 @@ def _has_cron_jobs(staged: Path) -> bool: def plan_install(source: str, workdir: Path, override_name: Optional[str] = None) -> InstallPlan: """Stage *source* and produce a plan describing what install would do.""" - from hermes_cli.profiles import _canon_valid, get_profile_dir + from hermes_cli.profiles import _canon_valid, _validate_new_profile_target, get_profile_dir, profile_exists from hermes_cli import __version__ as hermes_version staged, provenance = _stage_source(source, workdir) _reject_distribution_symlinks(staged) @@ -327,6 +327,8 @@ def plan_install(source: str, workdir: Path, override_name: Optional[str] = None manifest.installed_at = datetime.now(timezone.utc).isoformat(timespec="seconds") target_dir = get_profile_dir(canon) existing = target_dir.is_dir() + if not profile_exists(canon): + _validate_new_profile_target(canon) return InstallPlan( manifest=manifest, staged_dir=staged, provenance=provenance, target_dir=target_dir, existing=existing, preserves_config=existing, has_cron=_has_cron_jobs(staged), diff --git a/hermes_cli/profiles.py b/hermes_cli/profiles.py index cdf538070597..ca35320dbef3 100644 --- a/hermes_cli/profiles.py +++ b/hermes_cli/profiles.py @@ -116,9 +116,8 @@ def _ignore(directory: str, names: List[str]) -> List[str]: "plugins", "memories", "knowledge", "preferences", }) -# Names that cannot be used as profile aliases or as new-profile names. -# "main" would collide with the default profile's agent:main session namespace. -_RESERVED_NAMES = frozenset({"hermes", "default", "main", "test", "tmp", "root", "sudo"}) +# Names that cannot be used as profile aliases +_RESERVED_NAMES = frozenset({"hermes", "default", "test", "tmp", "root", "sudo"}) # Hermes subcommands that cannot be used as profile names/aliases _HERMES_SUBCOMMANDS = frozenset({ @@ -221,6 +220,15 @@ def _canon_valid(name: str) -> str: return canon +def _validate_new_profile_target(canon: str) -> None: + """Reserve the historical default namespace without locking out legacy profiles.""" + if canon == "main": + raise ValueError( + "Profile name 'main' is reserved for the default profile's session namespace. " + "Choose a different name." + ) + + def _existing_profile_dir(name: str) -> Tuple[str, Path]: """``(canon, profile_dir)`` for an existing profile; FileNotFoundError otherwise.""" canon = _canon_valid(name) @@ -819,11 +827,9 @@ def create_profile( "(cloning explicitly copies skills from the source profile)." ) canon = _canon_valid(name) - if canon in _RESERVED_NAMES: - raise ValueError( - f"Cannot create a profile named {canon!r} — it is reserved. " - f"Reserved names: {', '.join(sorted(_RESERVED_NAMES))}." - ) + _validate_new_profile_target(canon) + if canon == "default": + raise ValueError("Cannot create a profile named 'default' — it is the built-in profile (~/.hermes).") profile_dir = get_profile_dir(canon) if profile_dir.exists() and named_profile_is_deleted(profile_dir): # Empty shells left by post-delete mkdir may be replaced. Identity files mean the @@ -1569,6 +1575,7 @@ def import_profile(archive_path: str, name: Optional[str] = None) -> Path: # Default-profile archives have "default/" at top level; importing as "default" would # target ~/.hermes itself. canon = _canon_valid(inferred_name) + _validate_new_profile_target(canon) if canon == "default": raise ValueError( "Cannot import as 'default' — that is the built-in root profile (~/.hermes). " @@ -1657,6 +1664,7 @@ def rename_profile(old_name: str, new_name: str) -> Path: print(f"✓ Display name set: {cleaned} (canonical id remains 'default')") return _get_default_hermes_home() new_canon = _canon_valid(new_name) + _validate_new_profile_target(new_canon) if new_canon == "default": raise ValueError("Cannot rename to 'default' — it is reserved.") old_dir = get_profile_dir(old_canon) diff --git a/tests/hermes_cli/test_profile_main_namespace.py b/tests/hermes_cli/test_profile_main_namespace.py new file mode 100644 index 000000000000..f42604d9b3c0 --- /dev/null +++ b/tests/hermes_cli/test_profile_main_namespace.py @@ -0,0 +1,106 @@ +"""New profile targets must not reuse the default session namespace.""" + +import tarfile +from pathlib import Path + +import pytest + +from hermes_cli import profiles +from hermes_cli.profile_distribution import ( + DistributionManifest, + install_distribution, + update_distribution, + write_manifest, +) +from hermes_constants import mark_named_profile_deleted, named_profile_is_deleted + + +@pytest.fixture +def profile_home(tmp_path, monkeypatch): + monkeypatch.setattr(Path, "home", lambda: tmp_path) + monkeypatch.setenv("HOME", str(tmp_path)) + home = tmp_path / ".hermes" + home.mkdir() + monkeypatch.setenv("HERMES_HOME", str(home)) + # Lifecycle tests use real profile files, never host services or running backends. + for name in ( + "_cleanup_gateway_service", "_maybe_register_gateway_service", "_maybe_unregister_gateway_service", + "_stop_profile_backends", "_notify_multiplexer", + ): + monkeypatch.setattr(profiles, name, lambda *args, **kwargs: None) + return home + + +@pytest.mark.parametrize("operation", ["create", "import", "rename", "distribution", "distribution_tombstone"]) +@pytest.mark.parametrize("name", ["main", "MAIN", " main "]) +def test_new_profile_targets_cannot_claim_default_namespace(profile_home, tmp_path, operation, name): + source = profile_home / "profiles" / "source" + source.mkdir(parents=True) + config = "model:\n provider: custom\n default: local-model\n" + (source / "config.yaml").write_text(config) + archive = tmp_path / "source.tar.gz" + with tarfile.open(archive, "w:gz") as bundle: + bundle.add(source, arcname="source") + write_manifest(source, DistributionManifest(name="source")) + target = profile_home / "profiles" / "main" + tombstoned = operation == "distribution_tombstone" + if tombstoned: + target.mkdir() + mark_named_profile_deleted(target) + actions = { + "create": lambda: profiles.create_profile(name, no_skills=True), + "import": lambda: profiles.import_profile(str(archive), name=name), + "rename": lambda: profiles.rename_profile("source", name), + "distribution": lambda: install_distribution(str(source), name=name, create_alias=True), + "distribution_tombstone": lambda: install_distribution( + str(source), name=name, force=True, create_alias=True, + ), + } + + with pytest.raises(ValueError, match="main"): + actions[operation]() + + assert target.exists() == tombstoned + if tombstoned: + assert named_profile_is_deleted(target) + assert not list(target.iterdir()) + assert (source / "config.yaml").read_text() == config + assert not profiles.find_alias_for_profile("main") + + +@pytest.mark.parametrize("finish", ["rename", "delete"]) +def test_legacy_main_profile_remains_manageable(profile_home, tmp_path, finish): + legacy = profile_home / "profiles" / "main" + legacy.mkdir(parents=True) + config = "model:\n provider: custom\n default: local-model\n" + (legacy / "config.yaml").write_text(config) + if finish == "rename": + profiles.create_wrapper_script("main") + profiles.set_active_profile("main") + + assert profiles.resolve_profile_env("main") == str(legacy) + assert any(profile.name == "main" for profile in profiles.list_profiles()) + clone = profiles.create_profile("copy", clone_from="main", no_alias=True) + assert (clone / "config.yaml").is_file() + + source = tmp_path / "distribution" + source.mkdir() + (source / "SOUL.md").write_text("Updated distribution content") + manifest = DistributionManifest(name="main", source=str(source)) + write_manifest(source, manifest) + write_manifest(legacy, manifest) + updated = update_distribution("main") + assert updated.target_dir == legacy + assert (legacy / "SOUL.md").read_text() == (source / "SOUL.md").read_text() + assert (legacy / "config.yaml").read_text() == config + + if finish == "rename": + renamed = profiles.rename_profile("main", "renamed") + assert profiles.resolve_profile_env("renamed") == str(renamed) + assert (renamed / "config.yaml").read_text() == config + assert profiles.find_alias_for_profile("main") is None + else: + profiles.delete_profile("main", yes=True) + + assert not legacy.exists() + assert (clone / "config.yaml").is_file() diff --git a/tests/hermes_cli/test_profiles.py b/tests/hermes_cli/test_profiles.py index b9643e725232..b7c7bf61a4f0 100644 --- a/tests/hermes_cli/test_profiles.py +++ b/tests/hermes_cli/test_profiles.py @@ -314,59 +314,6 @@ def test_no_profiles_root_is_noop(self, profile_env): assert backfill_profile_envs(quiet=True) == [] -# =================================================================== -# TestReservedNames — regression coverage for the corner-case branch of -# #12099 in which a user could create a profile literally named "main" -# (or any other supposedly-reserved name) and re-introduce the original -# session-key collision because validate_profile_name() only enforced -# the regex, not _RESERVED_NAMES. -# =================================================================== - -class TestReservedNames: - """create_profile() must reject every entry in _RESERVED_NAMES.""" - - @pytest.mark.parametrize( - "name", - ["main", "hermes", "default", "test", "tmp", "root", "sudo"], - ) - def test_reserved_name_rejected(self, profile_env, name): - """Each reserved name must raise ValueError before any directory is - created. Without this guard, ``hermes profile create main`` would - succeed and silently produce ``agent:main:*`` session keys that - collide with the default profile — re-introducing #12099.""" - with pytest.raises(ValueError, match="reserved"): - create_profile(name, no_alias=True) - - def test_reserved_name_error_lists_all_reserved(self, profile_env): - """The error message should help the user pick a non-reserved name - without forcing them to read the source.""" - from hermes_cli.profiles import _RESERVED_NAMES - - with pytest.raises(ValueError) as exc_info: - create_profile("main", no_alias=True) - - message = str(exc_info.value) - # Mentions the offending name and at least a few reserved names so - # the user can immediately see what to avoid. - assert "'main'" in message - for reserved in ("hermes", "default", "main"): - assert reserved in message, f"error should list {reserved!r}; got: {message}" - assert sorted(_RESERVED_NAMES) == sorted( - {"hermes", "default", "main", "test", "tmp", "root", "sudo"} - ), "reserved set drift — update this test if intentional" - - def test_reserved_name_creates_no_directory(self, profile_env): - """Bug-shaped check: rejection must happen before mkdir, so a failed - attempt must not leave an orphan directory that blocks later use of - the same name once it stops being reserved.""" - from hermes_cli.profiles import get_profile_dir - - with pytest.raises(ValueError): - create_profile("main", no_alias=True) - - assert not get_profile_dir("main").exists() - - # =================================================================== # TestDeleteProfile # =================================================================== diff --git a/website/docs/user-guide/profile-distributions.md b/website/docs/user-guide/profile-distributions.md index 14bbba02f75c..620329a1ed26 100644 --- a/website/docs/user-guide/profile-distributions.md +++ b/website/docs/user-guide/profile-distributions.md @@ -744,7 +744,7 @@ The short version: - The manifest format is YAML with a tiny required schema (`name` only). - The installer uses your local `git` binary for cloning, so any auth your shell already handles (SSH keys, credential helpers) works transparently. - After clone, `.git/` is stripped — the installed profile isn't itself a git checkout, avoiding "oh my, I accidentally committed my `.env` to the distribution's git history" traps. -- Reserved profile names (`hermes`, `test`, `tmp`, `root`, `sudo`) are rejected at install time to avoid collisions with common binaries. +- Reserved profile names (`hermes`, `test`, `tmp`, `root`, `sudo`) are rejected at install time to avoid collisions with common binaries. `main` is reserved for new profiles; existing `main` profiles can still be updated. ## See also diff --git a/website/docs/user-guide/profiles.md b/website/docs/user-guide/profiles.md index e2d5da0d1644..95e6580267ef 100644 --- a/website/docs/user-guide/profiles.md +++ b/website/docs/user-guide/profiles.md @@ -40,6 +40,8 @@ hermes profile create mybot Creates a fresh profile with bundled skills seeded. Run `mybot setup` to configure API keys, model, and gateway tokens. +The name `main` is reserved for the default profile's session namespace. Existing profiles named `main` remain usable and can be renamed to a different name. + If you plan to use this profile as a kanban worker (or want the kanban orchestrator to route work to it), pass `--description ""` at create time so the orchestrator knows what it's good at: ```bash From 442b6565f941d14863042844f2a0329fa6cf0a10 Mon Sep 17 00:00:00 2001 From: guicybercode Date: Sun, 13 Sep 2026 02:56:49 -0300 Subject: [PATCH 3/8] fix(profiles): fence distribution publication with lifecycle identity --- hermes_cli/profile_cmd.py | 5 +- hermes_cli/profile_distribution.py | 140 +++++--- hermes_cli/profiles.py | 325 +++++++++--------- hermes_cli/profiles_lifecycle.py | 47 +++ .../hermes_cli/test_profile_main_namespace.py | 132 ++++++- 5 files changed, 434 insertions(+), 215 deletions(-) create mode 100644 hermes_cli/profiles_lifecycle.py diff --git a/hermes_cli/profile_cmd.py b/hermes_cli/profile_cmd.py index 45b67323a9c4..0ac0f7daff11 100644 --- a/hermes_cli/profile_cmd.py +++ b/hermes_cli/profile_cmd.py @@ -616,4 +616,7 @@ def cmd_profile(args): """Profile management — create, delete, list, switch, alias.""" handler = PROFILE_ACTIONS.get(getattr(args, "profile_action", None)) if handler is not None: - return handler(args) + try: + return handler(args) + except TimeoutError as exc: + _die(f"Error: {exc}", err=True) diff --git a/hermes_cli/profile_distribution.py b/hermes_cli/profile_distribution.py index d06e9a363eb6..74c1d3a59857 100644 --- a/hermes_cli/profile_distribution.py +++ b/hermes_cli/profile_distribution.py @@ -12,6 +12,7 @@ import shutil import subprocess import tempfile +from contextlib import ExitStack from dataclasses import dataclass, field from datetime import datetime, timezone from pathlib import Path, PurePosixPath @@ -20,6 +21,8 @@ import yaml from hermes_cli._subprocess_compat import noninteractive_git_env +from hermes_cli.profiles_lifecycle import directory_identity, profile_lifecycle_lock +from hermes_constants import named_profile_is_deleted MANIFEST_FILENAME = "distribution.yaml" @@ -294,6 +297,9 @@ class InstallPlan: provenance: str target_dir: Path existing: bool # True if target profile already exists (update path) + source_identity: tuple + target_identity: tuple | None + target_deleted: bool preserves_config: bool = True has_cron: bool = False @@ -303,36 +309,51 @@ def _has_cron_jobs(staged: Path) -> bool: return cron_dir.is_dir() and (any(cron_dir.rglob("*.json")) or any(cron_dir.rglob("*.yaml"))) -def plan_install(source: str, workdir: Path, override_name: Optional[str] = None) -> InstallPlan: +def plan_install( + source: str, workdir: Path, override_name: Optional[str] = None, *, guards: ExitStack | None = None, +) -> InstallPlan: """Stage *source* and produce a plan describing what install would do.""" from hermes_cli.profiles import _canon_valid, _validate_new_profile_target, get_profile_dir, profile_exists from hermes_cli import __version__ as hermes_version staged, provenance = _stage_source(source, workdir) - _reject_distribution_symlinks(staged) - manifest = read_manifest(staged) - if manifest is None: - raise DistributionError( - f"No {MANIFEST_FILENAME} found at the distribution root — this source is not a Hermes distribution." - ) - check_hermes_requires(manifest.hermes_requires, hermes_version) # fail fast - canon = _canon_valid(override_name or manifest.name) - if canon == "default": - raise DistributionError( - "Cannot install a distribution as 'default' — that is the built-in " - "root profile (~/.hermes). Pass --name to install under a new profile." + with profile_lifecycle_lock(): + _reject_distribution_symlinks(staged) + manifest = read_manifest(staged) + if manifest is None: + raise DistributionError( + f"No {MANIFEST_FILENAME} found at the distribution root — this source is not a Hermes distribution." + ) + check_hermes_requires(manifest.hermes_requires, hermes_version) # fail fast + canon = _canon_valid(override_name or manifest.name) + if canon == "default": + raise DistributionError( + "Cannot install a distribution as 'default' — that is the built-in " + "root profile (~/.hermes). Pass --name to install under a new profile." + ) + manifest.name = canon + manifest.source = provenance + # Stamped once here so both fresh install and update propagate a fresh timestamp. + manifest.installed_at = datetime.now(timezone.utc).isoformat(timespec="seconds") + target_dir = get_profile_dir(canon) + existing = target_dir.is_dir() + if not profile_exists(canon): + _validate_new_profile_target(canon) + return InstallPlan( + manifest=manifest, staged_dir=staged, provenance=provenance, target_dir=target_dir, existing=existing, + source_identity=directory_identity(staged, guards), target_identity=directory_identity(target_dir, guards), + target_deleted=named_profile_is_deleted(target_dir), + preserves_config=existing, has_cron=_has_cron_jobs(staged), ) - manifest.name = canon - manifest.source = provenance - # Stamped once here so both fresh install and update propagate a fresh timestamp. - manifest.installed_at = datetime.now(timezone.utc).isoformat(timespec="seconds") - target_dir = get_profile_dir(canon) - existing = target_dir.is_dir() - if not profile_exists(canon): - _validate_new_profile_target(canon) - return InstallPlan( - manifest=manifest, staged_dir=staged, provenance=provenance, target_dir=target_dir, existing=existing, - preserves_config=existing, has_cron=_has_cron_jobs(staged), - ) + + +def _revalidate_plan(plan: InstallPlan) -> None: + """Called under the lifecycle lock immediately before publishing the payload.""" + if ( + directory_identity(plan.staged_dir) != plan.source_identity + or directory_identity(plan.target_dir) != plan.target_identity + or named_profile_is_deleted(plan.target_dir) != plan.target_deleted + ): + raise DistributionError("Profile distribution source or destination changed after planning; retry the command.") def _owned_entries(staged: Path, manifest: DistributionManifest): @@ -409,19 +430,21 @@ def install_distribution( """Install a distribution from *source* into a new profile; returns the resolved plan. Use :func:`plan_install` first to preview + prompt.""" from hermes_cli.profiles import check_alias_collision, create_wrapper_script - with tempfile.TemporaryDirectory(prefix="hermes_dist_install_") as tmp: - plan = plan_install(source, Path(tmp), override_name=name) - if plan.existing and not force: - raise DistributionError( - f"Profile '{plan.manifest.name}' already exists at {plan.target_dir}. " - "Use `hermes profile update` to upgrade in place, or pass --force to overwrite." - ) - - # Fresh install: config.yaml comes from the distribution. - _bootstrap_user_dirs(plan.target_dir) - _copy_dist_payload(plan.staged_dir, plan.target_dir, plan.manifest, preserve_config=False) - if create_alias and check_alias_collision(plan.manifest.name) is None: - create_wrapper_script(plan.manifest.name) + with ExitStack() as guards, tempfile.TemporaryDirectory(prefix="hermes_dist_install_") as tmp: + plan = plan_install(source, Path(tmp), override_name=name, guards=guards) + with profile_lifecycle_lock(): + _revalidate_plan(plan) + if plan.existing and not force: + raise DistributionError( + f"Profile '{plan.manifest.name}' already exists at {plan.target_dir}. " + "Use `hermes profile update` to upgrade in place, or pass --force to overwrite." + ) + + # Fresh install: config.yaml comes from the distribution. + _bootstrap_user_dirs(plan.target_dir) + _copy_dist_payload(plan.staged_dir, plan.target_dir, plan.manifest, preserve_config=False) + if create_alias and check_alias_collision(plan.manifest.name) is None: + create_wrapper_script(plan.manifest.name) return plan @@ -438,23 +461,30 @@ def _existing_profile(profile_name: str) -> Tuple[str, Path]: def update_distribution(profile_name: str, force_config: bool = False) -> InstallPlan: """Re-pull from the installed manifest's ``source:`` and apply: dist-owned files overwritten, user data never touched, ``config.yaml`` preserved unless ``force_config``.""" - canon, target = _existing_profile(profile_name) - existing_manifest = read_manifest(target) - if existing_manifest is None: - raise DistributionError( - f"Profile '{canon}' is not a distribution (no {MANIFEST_FILENAME}). " - "Only profiles installed via `hermes profile install` can be updated." - ) - if not existing_manifest.source: - raise DistributionError( - f"Profile '{canon}' has no recorded source. Re-install with " - "`hermes profile install --name {canon} --force`." - ) - with tempfile.TemporaryDirectory(prefix="hermes_dist_update_") as tmp: - plan = plan_install(existing_manifest.source, Path(tmp), override_name=canon) - plan.preserves_config = not force_config - _copy_dist_payload(plan.staged_dir, plan.target_dir, plan.manifest, preserve_config=plan.preserves_config) - return plan + with ExitStack() as guards: + with profile_lifecycle_lock(): + canon, target = _existing_profile(profile_name) + original_identity = directory_identity(target, guards) + existing_manifest = read_manifest(target) + if existing_manifest is None: + raise DistributionError( + f"Profile '{canon}' is not a distribution (no {MANIFEST_FILENAME}). " + "Only profiles installed via `hermes profile install` can be updated." + ) + if not existing_manifest.source: + raise DistributionError( + f"Profile '{canon}' has no recorded source. Re-install with " + "`hermes profile install --name {canon} --force`." + ) + with tempfile.TemporaryDirectory(prefix="hermes_dist_update_") as tmp: + plan = plan_install(existing_manifest.source, Path(tmp), override_name=canon, guards=guards) + plan.preserves_config = not force_config + with profile_lifecycle_lock(): + _revalidate_plan(plan) + if plan.target_identity != original_identity or read_manifest(target) != existing_manifest: + raise DistributionError("Profile distribution destination changed while staging its update; retry the command.") + _copy_dist_payload(plan.staged_dir, plan.target_dir, plan.manifest, preserve_config=plan.preserves_config) + return plan def describe_distribution(profile_name: str) -> Dict[str, Any]: diff --git a/hermes_cli/profiles.py b/hermes_cli/profiles.py index ca35320dbef3..be4b9035aa01 100644 --- a/hermes_cli/profiles.py +++ b/hermes_cli/profiles.py @@ -17,6 +17,7 @@ from agent.skill_utils import is_excluded_skill_path from hermes_cli.archive_safe import archive_root_dirs, make_targz, normalize_archive_parts, safe_extract_targz +from hermes_cli.profiles_lifecycle import directory_identity, profile_lifecycle_lock from hermes_constants import clear_named_profile_deleted, mark_named_profile_deleted, named_profile_is_deleted logger = logging.getLogger(__name__) @@ -831,67 +832,68 @@ def create_profile( if canon == "default": raise ValueError("Cannot create a profile named 'default' — it is the built-in profile (~/.hermes).") profile_dir = get_profile_dir(canon) - if profile_dir.exists() and named_profile_is_deleted(profile_dir): - # Empty shells left by post-delete mkdir may be replaced. Identity files mean the - # leftover is not a shell — fail closed, no rmtree. - if (profile_dir / "config.yaml").exists() or (profile_dir / ".env").exists(): + with profile_lifecycle_lock(): + if profile_dir.exists() and named_profile_is_deleted(profile_dir): + # Empty shells left by post-delete mkdir may be replaced. Identity files mean the + # leftover is not a shell — fail closed, no rmtree. + if (profile_dir / "config.yaml").exists() or (profile_dir / ".env").exists(): + raise FileExistsError(f"Profile '{canon}' already exists at {profile_dir}") + shutil.rmtree(profile_dir) + if profile_dir.exists(): raise FileExistsError(f"Profile '{canon}' already exists at {profile_dir}") - shutil.rmtree(profile_dir) - if profile_dir.exists(): - raise FileExistsError(f"Profile '{canon}' already exists at {profile_dir}") - clear_named_profile_deleted(profile_dir) - source_dir = None - if clone_from is not None or clone_all or clone_config: - source_dir = _resolve_clone_source(clone_from) - if clone_all and source_dir: - _clone_all_into(source_dir, profile_dir, canon) - else: - _bootstrap_profile_dir(profile_dir, source_dir) - if source_dir is not None and not clone_channels: - from hermes_cli.profile_channels import strip_channel_settings - stripped = strip_channel_settings(profile_dir, include_state=clone_all) - if stripped: - logger.info("profile %s: cloned without messaging channels %s", canon, stripped) - - # Seed an empty .env so the profile owns a credentials file from day one. Without it, - # profile-scoped env writes (dashboard Channels/Keys pages, `hermes -p auth add`) - # had no file until first write and the profile silently inherited shell API keys — - # read by users as "the new profile reads the root .env". Skipped when a clone copied one. - _seed_file_if_missing(profile_dir / ".env", _PLACEHOLDER_ENV, 0o600) - - # Default SOUL.md to customize immediately (skipped when a clone already provided one). - with contextlib.suppress(Exception): # best-effort — don't fail profile creation over this - from hermes_cli.default_soul import DEFAULT_SOUL_MD - _seed_file_if_missing(profile_dir / "SOUL.md", DEFAULT_SOUL_MD) - - # Opt-out marker read by seed_profile_skills() and `hermes update`'s all-profile sync - # (the feature still works via the empty skills/ dir if this fails). - if no_skills: - _seed_file_if_missing( - profile_dir / NO_BUNDLED_SKILLS_MARKER, - "This profile opted out of bundled-skill seeding (`hermes profile create --no-skills`).\n" - "Delete this file to re-enable sync on the next `hermes update`.\n", - ) + clear_named_profile_deleted(profile_dir) + source_dir = None + if clone_from is not None or clone_all or clone_config: + source_dir = _resolve_clone_source(clone_from) + if clone_all and source_dir: + _clone_all_into(source_dir, profile_dir, canon) + else: + _bootstrap_profile_dir(profile_dir, source_dir) + if source_dir is not None and not clone_channels: + from hermes_cli.profile_channels import strip_channel_settings + stripped = strip_channel_settings(profile_dir, include_state=clone_all) + if stripped: + logger.info("profile %s: cloned without messaging channels %s", canon, stripped) + + # Seed an empty .env so the profile owns a credentials file from day one. Without it, + # profile-scoped env writes (dashboard Channels/Keys pages, `hermes -p auth add`) + # had no file until first write and the profile silently inherited shell API keys — + # read by users as "the new profile reads the root .env". Skipped when a clone copied one. + _seed_file_if_missing(profile_dir / ".env", _PLACEHOLDER_ENV, 0o600) + + # Default SOUL.md to customize immediately (skipped when a clone already provided one). + with contextlib.suppress(Exception): # best-effort — don't fail profile creation over this + from hermes_cli.default_soul import DEFAULT_SOUL_MD + _seed_file_if_missing(profile_dir / "SOUL.md", DEFAULT_SOUL_MD) + + # Opt-out marker read by seed_profile_skills() and `hermes update`'s all-profile sync + # (the feature still works via the empty skills/ dir if this fails). + if no_skills: + _seed_file_if_missing( + profile_dir / NO_BUNDLED_SKILLS_MARKER, + "This profile opted out of bundled-skill seeding (`hermes profile create --no-skills`).\n" + "Delete this file to re-enable sync on the next `hermes update`.\n", + ) - # Migrate config-only clones now so desktop/status don't warn that a just-created - # profile is v0/outdated; --clone-all snapshots stay byte-for-byte apart from the - # explicit runtime/history stripping above. - if not clone_all: - _migrate_profile_config_if_outdated(profile_dir) - - # Description last, so a partial-create failure doesn't strand a description file. - if description and description.strip(): - with contextlib.suppress(Exception): # non-fatal — `hermes profile describe` works later - write_profile_meta(profile_dir, description=description.strip(), description_auto=False) - - # Inside a container under s6, register the gateway as a runtime s6 service so - # `hermes -p gateway start` supervises via `s6-svc -u` instead of a bare - # process. No-op on host (systemd/launchd/windows unit generation handles lifecycle). - _maybe_register_gateway_service(canon) - # A running multiplexer enumerates profiles/ at boot: ask it to serve this one now (it also - # rescans periodically, so a missed signal only delays serving). - _notify_multiplexer(canon) - return profile_dir + # Migrate config-only clones now so desktop/status don't warn that a just-created + # profile is v0/outdated; --clone-all snapshots stay byte-for-byte apart from the + # explicit runtime/history stripping above. + if not clone_all: + _migrate_profile_config_if_outdated(profile_dir) + + # Description last, so a partial-create failure doesn't strand a description file. + if description and description.strip(): + with contextlib.suppress(Exception): # non-fatal — `hermes profile describe` works later + write_profile_meta(profile_dir, description=description.strip(), description_auto=False) + + # Inside a container under s6, register the gateway as a runtime s6 service so + # `hermes -p gateway start` supervises via `s6-svc -u` instead of a bare + # process. No-op on host (systemd/launchd/windows unit generation handles lifecycle). + _maybe_register_gateway_service(canon) + # A running multiplexer enumerates profiles/ at boot: ask it to serve this one now (it also + # rescans periodically, so a missed signal only delays serving). + _notify_multiplexer(canon) + return profile_dir def _notify_multiplexer(canon: str) -> None: @@ -1152,74 +1154,83 @@ def delete_profile(name: str, yes: bool = False) -> Path: canon = normalize_profile_name(name) if canon == "default": raise ValueError("Cannot delete the default profile (~/.hermes).\nTo remove everything, use: hermes uninstall") - canon, profile_dir = _existing_profile_dir(canon) - gw_running = _check_gateway_running(profile_dir) - wrapper_path = _get_wrapper_dir() / canon - has_wrapper = wrapper_path.exists() - _print_delete_summary(canon, profile_dir, gw_running, wrapper_path if has_wrapper else None) - if not yes: - print() - try: - confirm = input(f"Type '{canon}' to confirm: ").strip() - except (KeyboardInterrupt, EOFError): - confirm = None + with contextlib.ExitStack() as guards: + canon, profile_dir = _existing_profile_dir(canon) + original_identity = directory_identity(profile_dir, guards) + original_deleted = named_profile_is_deleted(profile_dir) + gw_running = _check_gateway_running(profile_dir) + wrapper_path = _get_wrapper_dir() / canon + has_wrapper = wrapper_path.exists() + _print_delete_summary(canon, profile_dir, gw_running, wrapper_path if has_wrapper else None) + if not yes: print() - if confirm != canon: - print("Cancelled.") - return profile_dir - - # 1. Disable service (prevents auto-restart); drop the s6 slot on container (host no-op). - _cleanup_gateway_service(canon, profile_dir) - _maybe_unregister_gateway_service(canon) - - # 2. Stop the gateway, then other backends bound to this profile (Desktop-spawned - # serve/dashboard the pid file never names): they hold the SQLite connection open and - # keep writing, which made rmtree fail ENOTEMPTY and resurrected the deleted tree. - if gw_running: - _stop_gateway_process(profile_dir) - _stop_profile_backends(canon, profile_dir) - - # Tombstone before rmtree so a stale serve/logging mkdir cannot relist this name live. - mark_named_profile_deleted(profile_dir) - # The multiplexer sees the tombstone, stops this profile's adapters and releases its handles - # into the directory before we remove it. - _notify_multiplexer(canon) - - # Release this process's holographic memory-store connections into the profile. The - # Desktop's main serve process opens memory_store.db for every profile and is - # deliberately not stopped above; on Windows its handles fail rmtree with WinError 32. - # Inside serve (DELETE /api/profiles/) the handles live here; from the CLI no-op. - with contextlib.suppress(Exception): # best-effort: never block the delete on the release path - # 2c. See #88347. - from plugins.memory.holographic.store import MemoryStore as _MemoryStore - _released = _MemoryStore.release_all_under(profile_dir) - if _released: - print(f"✓ Released {_released} memory-store connection(s) held by this process") - with contextlib.suppress(Exception): - from hermes_state_registry import close_all_under as _close_session_dbs_under - _closed = _close_session_dbs_under(profile_dir) - if _closed: - print(f"✓ Released {_closed} session database connection(s) held by this process") + try: + confirm = input(f"Type '{canon}' to confirm: ").strip() + except (KeyboardInterrupt, EOFError): + confirm = None + print() + if confirm != canon: + print("Cancelled.") + return profile_dir + + with profile_lifecycle_lock(): + if ( + directory_identity(profile_dir) != original_identity + or named_profile_is_deleted(profile_dir) != original_deleted + ): + raise RuntimeError("Profile changed while waiting for deletion; retry the command.") + # 1. Disable service (prevents auto-restart); drop the s6 slot on container (host no-op). + _cleanup_gateway_service(canon, profile_dir) + _maybe_unregister_gateway_service(canon) + + # 2. Stop the gateway, then other backends bound to this profile (Desktop-spawned + # serve/dashboard the pid file never names): they hold the SQLite connection open and + # keep writing, which made rmtree fail ENOTEMPTY and resurrected the deleted tree. + if gw_running: + _stop_gateway_process(profile_dir) + _stop_profile_backends(canon, profile_dir) + + # Tombstone before rmtree so a stale serve/logging mkdir cannot relist this name live. + mark_named_profile_deleted(profile_dir) + # The multiplexer sees the tombstone, stops this profile's adapters and releases its handles + # into the directory before we remove it. + _notify_multiplexer(canon) + + # Release this process's holographic memory-store connections into the profile. The + # Desktop's main serve process opens memory_store.db for every profile and is + # deliberately not stopped above; on Windows its handles fail rmtree with WinError 32. + # Inside serve (DELETE /api/profiles/) the handles live here; from the CLI no-op. + with contextlib.suppress(Exception): # best-effort: never block the delete on the release path + # 2c. See #88347. + from plugins.memory.holographic.store import MemoryStore as _MemoryStore + _released = _MemoryStore.release_all_under(profile_dir) + if _released: + print(f"✓ Released {_released} memory-store connection(s) held by this process") + with contextlib.suppress(Exception): + from hermes_state_registry import close_all_under as _close_session_dbs_under + _closed = _close_session_dbs_under(profile_dir) + if _closed: + print(f"✓ Released {_closed} session database connection(s) held by this process") - # 3. Remove wrapper script - if has_wrapper and remove_wrapper_script(canon): - print(f"✓ Removed {wrapper_path}") + # 3. Remove wrapper script + if has_wrapper and remove_wrapper_script(canon): + print(f"✓ Removed {wrapper_path}") - # 4. Remove profile directory - remove_error: Exception | None = None - try: - _rmtree_with_retry(profile_dir, _rmtree_make_writable) - print(f"✓ Removed {profile_dir}") - except Exception as e: - print(f"⚠ Could not remove {profile_dir}: {e}") - remove_error = e - - # 5. Clear active_profile if it pointed to this profile - _retarget_active_profile(canon, "default", "✓ Active profile reset to default") - if remove_error is not None: - raise RuntimeError(f"Could not remove profile directory {profile_dir}: {remove_error}") from remove_error - print(f"\nProfile '{canon}' deleted.") - return profile_dir + # 4. Remove profile directory + remove_error: Exception | None = None + try: + _rmtree_with_retry(profile_dir, _rmtree_make_writable) + print(f"✓ Removed {profile_dir}") + except Exception as e: + print(f"⚠ Could not remove {profile_dir}: {e}") + remove_error = e + + # 5. Clear active_profile if it pointed to this profile + _retarget_active_profile(canon, "default", "✓ Active profile reset to default") + if remove_error is not None: + raise RuntimeError(f"Could not remove profile directory {profile_dir}: {remove_error}") from remove_error + print(f"\nProfile '{canon}' deleted.") + return profile_dir def _s6_runtime_manager(): @@ -1595,7 +1606,10 @@ def import_profile(archive_path: str, name: Optional[str] = None) -> Path: if archive_root != canon: final_source = staging_root / canon extracted.rename(final_source) - shutil.move(str(final_source), str(profile_dir)) + with profile_lifecycle_lock(): + if profile_dir.exists(): + raise FileExistsError(f"Profile '{canon}' already exists at {profile_dir}") + shutil.move(str(final_source), str(profile_dir)) return profile_dir @@ -1667,37 +1681,38 @@ def rename_profile(old_name: str, new_name: str) -> Path: _validate_new_profile_target(new_canon) if new_canon == "default": raise ValueError("Cannot rename to 'default' — it is reserved.") - old_dir = get_profile_dir(old_canon) - new_dir = get_profile_dir(new_canon) - if not old_dir.is_dir(): - raise FileNotFoundError(f"Profile '{old_canon}' does not exist.") - if new_dir.exists(): - raise FileExistsError(f"Profile '{new_canon}' already exists.") - - # 1. Stop gateway if running - if _check_gateway_running(old_dir): - _cleanup_gateway_service(old_canon, old_dir) - _stop_gateway_process(old_dir) - - # 2. Rename directory - old_dir.rename(new_dir) - print(f"✓ Renamed {old_dir.name} → {new_dir.name}") - - # 3. Update profile-scoped Honcho host blocks, preserving aiPeer identity - _migrate_honcho_profile_host(old_canon, new_canon, new_dir) - - # 4. Update wrapper script - remove_wrapper_script(old_canon) - collision = check_alias_collision(new_canon) - if not collision: - create_wrapper_script(new_canon) - print(f"✓ Alias updated: {new_canon}") - else: - print(f"⚠ Cannot create alias '{new_canon}' — {collision}") + with profile_lifecycle_lock(): + old_dir = get_profile_dir(old_canon) + new_dir = get_profile_dir(new_canon) + if not old_dir.is_dir(): + raise FileNotFoundError(f"Profile '{old_canon}' does not exist.") + if new_dir.exists(): + raise FileExistsError(f"Profile '{new_canon}' already exists.") + + # 1. Stop gateway if running + if _check_gateway_running(old_dir): + _cleanup_gateway_service(old_canon, old_dir) + _stop_gateway_process(old_dir) + + # 2. Rename directory + old_dir.rename(new_dir) + print(f"✓ Renamed {old_dir.name} → {new_dir.name}") + + # 3. Update profile-scoped Honcho host blocks, preserving aiPeer identity + _migrate_honcho_profile_host(old_canon, new_canon, new_dir) + + # 4. Update wrapper script + remove_wrapper_script(old_canon) + collision = check_alias_collision(new_canon) + if not collision: + create_wrapper_script(new_canon) + print(f"✓ Alias updated: {new_canon}") + else: + print(f"⚠ Cannot create alias '{new_canon}' — {collision}") - # 5. Update active_profile if it pointed to old name - _retarget_active_profile(old_canon, new_canon, f"✓ Active profile updated: {new_canon}") - return new_dir + # 5. Update active_profile if it pointed to old name + _retarget_active_profile(old_canon, new_canon, f"✓ Active profile updated: {new_canon}") + return new_dir # Profile env resolution (called from _apply_profile_override) diff --git a/hermes_cli/profiles_lifecycle.py b/hermes_cli/profiles_lifecycle.py new file mode 100644 index 000000000000..6f6a669bcbdc --- /dev/null +++ b/hermes_cli/profiles_lifecycle.py @@ -0,0 +1,47 @@ +"""Coordinate profile directory changes made by cooperating Hermes commands.""" + +from contextlib import ExitStack, contextmanager +import os +from pathlib import Path +import threading + + +_THREAD_LOCK = threading.RLock() +_FILE_LOCK_HOLDER = threading.local() + + +@contextmanager +def profile_lifecycle_lock(): + """Serialize lifecycle writes across threads/processes; external filesystem edits do not participate.""" + from hermes_cli.auth import _file_lock + from hermes_cli.profiles import _get_profiles_root + + # Keep it under profiles/: default-profile clones/exports exclude that infrastructure. + # The lock survives renaming/deleting any profile and is independent of HERMES_HOME. + with _THREAD_LOCK, _file_lock( + _get_profiles_root() / ".lifecycle.lock", _FILE_LOCK_HOLDER, 30, + "Timed out waiting for profile lifecycle lock", + ): + yield + + +def directory_identity(path: Path, guards: ExitStack | None = None) -> tuple | None: + """Pin POSIX directories for a mutation's lifetime so inode reuse cannot pass revalidation. + + Windows stat supplies the file index and creation time without opening a directory. + Plain snapshots are used for previews and comparisons against a pinned identity. + """ + try: + if guards is not None and os.name != "nt": + fd = os.open(path, os.O_RDONLY | os.O_DIRECTORY) + guards.callback(os.close, fd) + info = os.fstat(fd) + else: + info = path.stat() + except FileNotFoundError: + return None + created = getattr(info, "st_birthtime_ns", getattr(info, "st_birthtime", None)) + if os.name == "nt" and created is None: + # Before Python 3.12, Windows exposed creation time only as st_ctime. + created = info.st_ctime_ns + return (str(path.resolve()), info.st_dev, info.st_ino, created) diff --git a/tests/hermes_cli/test_profile_main_namespace.py b/tests/hermes_cli/test_profile_main_namespace.py index f42604d9b3c0..3f387b177f61 100644 --- a/tests/hermes_cli/test_profile_main_namespace.py +++ b/tests/hermes_cli/test_profile_main_namespace.py @@ -1,18 +1,23 @@ """New profile targets must not reuse the default session namespace.""" import tarfile +from concurrent.futures import ThreadPoolExecutor +from contextlib import contextmanager from pathlib import Path +from threading import Event import pytest from hermes_cli import profiles +from hermes_cli import profile_distribution as distributions from hermes_cli.profile_distribution import ( + DistributionError, DistributionManifest, install_distribution, update_distribution, write_manifest, ) -from hermes_constants import mark_named_profile_deleted, named_profile_is_deleted +from hermes_constants import clear_named_profile_deleted, mark_named_profile_deleted, named_profile_is_deleted @pytest.fixture @@ -68,8 +73,15 @@ def test_new_profile_targets_cannot_claim_default_namespace(profile_home, tmp_pa assert not profiles.find_alias_for_profile("main") -@pytest.mark.parametrize("finish", ["rename", "delete"]) -def test_legacy_main_profile_remains_manageable(profile_home, tmp_path, finish): +@pytest.mark.parametrize("finish,change", [("rename", None), ("delete", None), ("retry_delete", None)] + [ + (operation, change) + for operation in ("install", "update") + for change in ( + "delete", "rename", "tombstone", "recreate", "replacement", "source_replacement", + "publication_rename", "publication_delete", + ) +]) +def test_legacy_main_profile_remains_manageable(profile_home, tmp_path, monkeypatch, finish, change): legacy = profile_home / "profiles" / "main" legacy.mkdir(parents=True) config = "model:\n provider: custom\n default: local-model\n" @@ -83,7 +95,7 @@ def test_legacy_main_profile_remains_manageable(profile_home, tmp_path, finish): clone = profiles.create_profile("copy", clone_from="main", no_alias=True) assert (clone / "config.yaml").is_file() - source = tmp_path / "distribution" + source = profile_home / "profiles" / "distribution" source.mkdir() (source / "SOUL.md").write_text("Updated distribution content") manifest = DistributionManifest(name="main", source=str(source)) @@ -94,12 +106,124 @@ def test_legacy_main_profile_remains_manageable(profile_home, tmp_path, finish): assert (legacy / "SOUL.md").read_text() == (source / "SOUL.md").read_text() assert (legacy / "config.yaml").read_text() == config + if change is not None: + target_name = "copy" if change == "replacement" else "main" + target = profiles.get_profile_dir(target_name) + write_manifest(target, manifest) + planned, release = Event(), Event() + real_plan = distributions.plan_install + publish = { + "install": lambda: install_distribution(str(source), name=target_name.upper(), force=True), + "update": lambda: update_distribution(target_name), + } + + if change.startswith("publication_"): + from hermes_cli import profiles_lifecycle + + (source / "new_entry.md").write_text("Published while deletion waits") + entered, attempted = Event(), Event() + real_copy = distributions._copy_dist_payload + real_lock = profiles.profile_lifecycle_lock + + def pause_publication(*args, **kwargs): + entered.set() + assert release.wait(10) + real_copy(*args, **kwargs) + + @contextmanager + def observe_lifecycle_lock(): + # A nonblocking probe proves exclusion without sleep-based assertions. + available = profiles_lifecycle._THREAD_LOCK.acquire(blocking=False) + if available: + profiles_lifecycle._THREAD_LOCK.release() + try: + assert not available, "profile mutation can interleave with payload publication" + finally: + attempted.set() + with real_lock(): + yield + + mutation = { + "publication_rename": lambda: profiles.rename_profile("main", "previous"), + "publication_delete": lambda: profiles.delete_profile("main", yes=True), + }[change] + monkeypatch.setattr(distributions, "_copy_dist_payload", pause_publication) + monkeypatch.setattr(profiles, "profile_lifecycle_lock", observe_lifecycle_lock) + with ThreadPoolExecutor(max_workers=2) as pool: + pending = pool.submit(publish[finish]) + try: + assert entered.wait(10) + changed = pool.submit(mutation) + assert attempted.wait(10) + finally: + release.set() + pending.result(timeout=10) + changed.result(timeout=10) + assert not target.exists() + if change == "publication_rename": + assert (profile_home / "profiles" / "previous" / "SOUL.md").read_text() == (source / "SOUL.md").read_text() + return + + def pause_after_plan(*args, **kwargs): + plan = real_plan(*args, **kwargs) + planned.set() + assert release.wait(10), "test did not release the planned installation" + return plan + + def recreate(): + profiles.delete_profile(target_name, yes=True) + target.mkdir() + clear_named_profile_deleted(target) + + def replace_target(): + profiles.delete_profile(target_name, yes=True) + profiles.create_profile(target_name, no_alias=True, no_skills=True) + + def replace_source(): + profiles.rename_profile("distribution", "previous_source") + profiles.create_profile("distribution", no_alias=True, no_skills=True) + write_manifest(source, manifest) + (source / "SOUL.md").write_text("Unplanned source content") + + mutations = { + "delete": lambda: profiles.delete_profile(target_name, yes=True), + "rename": lambda: profiles.rename_profile(target_name, "previous"), + "tombstone": lambda: mark_named_profile_deleted(target), + "recreate": recreate, + "replacement": replace_target, + "source_replacement": replace_source, + } + monkeypatch.setattr(distributions, "plan_install", pause_after_plan) + with ThreadPoolExecutor(max_workers=1) as pool: + pending = pool.submit(publish[finish]) + try: + assert planned.wait(10), "installation did not reach the planning barrier" + mutations[change]() + existed = target.exists() + contents = {p.relative_to(target): p.read_bytes() for p in target.rglob("*") if p.is_file()} + finally: + release.set() + with pytest.raises(DistributionError, match="changed"): + pending.result(timeout=10) + assert target.exists() == existed + assert {p.relative_to(target): p.read_bytes() for p in target.rglob("*") if p.is_file()} == contents + return + if finish == "rename": renamed = profiles.rename_profile("main", "renamed") assert profiles.resolve_profile_env("renamed") == str(renamed) assert (renamed / "config.yaml").read_text() == config assert profiles.find_alias_for_profile("main") is None else: + if finish == "retry_delete": + def fail_removal(*args): + raise OSError("temporary removal failure") + + with monkeypatch.context() as failing: + failing.setattr(profiles, "_rmtree_with_retry", fail_removal) + with pytest.raises(RuntimeError, match="Could not remove profile directory"): + profiles.delete_profile("main", yes=True) + assert legacy.exists() and named_profile_is_deleted(legacy) profiles.delete_profile("main", yes=True) assert not legacy.exists() From 80191ada0e52537813c5556421ce462b8f70d00a Mon Sep 17 00:00:00 2001 From: guicybercode Date: Sun, 13 Sep 2026 03:58:11 -0300 Subject: [PATCH 4/8] fix(profiles): stage local distributions before planning --- hermes_cli/profile_distribution.py | 13 ++- .../hermes_cli/test_profile_main_namespace.py | 96 ++++++++++++++++++- 2 files changed, 102 insertions(+), 7 deletions(-) diff --git a/hermes_cli/profile_distribution.py b/hermes_cli/profile_distribution.py index 74c1d3a59857..747254be47f4 100644 --- a/hermes_cli/profile_distribution.py +++ b/hermes_cli/profile_distribution.py @@ -248,7 +248,7 @@ def _git_clone(url: str, dest: Path) -> None: def _stage_source(source: str, workdir: Path) -> Tuple[Path, str]: """Resolve *source* to ``(staged_dir, provenance)``: git URLs are shallow-cloned into - *workdir* (``.git`` removed); a local directory is used in place.""" + *workdir* (``.git`` removed); local sources are copied there before planning.""" src_str = source.strip() if _looks_like_git_url(src_str): staged, provenance = workdir / "clone", src_str @@ -259,8 +259,13 @@ def _stage_source(source: str, workdir: Path) -> Tuple[Path, str]: "This repository is not a Hermes profile distribution." ) elif (path_guess := Path(src_str).expanduser()).is_dir(): - staged = path_guess.resolve() - provenance = str(staged) + local_source = path_guess.resolve() + staged, provenance = workdir / "local", str(local_source) + if staged.resolve().is_relative_to(local_source): + raise DistributionError("Distribution staging directory must be outside the local source.") + # Plan and publication read only this copy. Preserve links for the staged-tree + # validation to reject, instead of materializing their external targets. + shutil.copytree(local_source, staged, symlinks=True) missing = ( f"No {MANIFEST_FILENAME} in {path_guess}. " "A local-directory source must contain a distribution.yaml at its root." @@ -335,6 +340,8 @@ def plan_install( # Stamped once here so both fresh install and update propagate a fresh timestamp. manifest.installed_at = datetime.now(timezone.utc).isoformat(timespec="seconds") target_dir = get_profile_dir(canon) + if staged.resolve().is_relative_to(target_dir.resolve()): + raise DistributionError("Distribution staging directory must be outside the target profile.") existing = target_dir.is_dir() if not profile_exists(canon): _validate_new_profile_target(canon) diff --git a/tests/hermes_cli/test_profile_main_namespace.py b/tests/hermes_cli/test_profile_main_namespace.py index 3f387b177f61..6a3566c351f5 100644 --- a/tests/hermes_cli/test_profile_main_namespace.py +++ b/tests/hermes_cli/test_profile_main_namespace.py @@ -1,6 +1,7 @@ """New profile targets must not reuse the default session namespace.""" import tarfile +import shutil from concurrent.futures import ThreadPoolExecutor from contextlib import contextmanager from pathlib import Path @@ -36,9 +37,12 @@ def profile_home(tmp_path, monkeypatch): return home -@pytest.mark.parametrize("operation", ["create", "import", "rename", "distribution", "distribution_tombstone"]) +@pytest.mark.parametrize("operation", [ + "create", "import", "rename", "distribution", "distribution_tombstone", "distribution_symlink", + "stage_inside_source", "stage_inside_target", +]) @pytest.mark.parametrize("name", ["main", "MAIN", " main "]) -def test_new_profile_targets_cannot_claim_default_namespace(profile_home, tmp_path, operation, name): +def test_new_profile_targets_cannot_claim_default_namespace(profile_home, tmp_path, monkeypatch, operation, name): source = profile_home / "profiles" / "source" source.mkdir(parents=True) config = "model:\n provider: custom\n default: local-model\n" @@ -48,6 +52,52 @@ def test_new_profile_targets_cannot_claim_default_namespace(profile_home, tmp_pa bundle.add(source, arcname="source") write_manifest(source, DistributionManifest(name="source")) target = profile_home / "profiles" / "main" + if operation in {"stage_inside_source", "stage_inside_target"}: + parent = source if operation == "stage_inside_source" else target / "skills" + workdir = parent / "tmp" + workdir.mkdir(parents=True) + if operation == "stage_inside_source": + def refuse_recursive_copy(*args, **kwargs): + pytest.fail("staging tried to copy the source into itself") + + monkeypatch.setattr(distributions.shutil, "copytree", refuse_recursive_copy) + else: + (target / "config.yaml").write_text(config) + (parent / "guide.md").write_text("Existing skill content") + + with pytest.raises(DistributionError, match="outside"): + distributions.plan_install(str(source), workdir, override_name=name) + assert (source / "config.yaml").read_text() == config + if operation == "stage_inside_source": + assert not list(workdir.iterdir()) + assert not target.exists() + else: + assert (target / "config.yaml").read_text() == config + assert (parent / "guide.md").read_text() == "Existing skill content" + return + + if operation == "distribution_symlink": + external = tmp_path / "private.md" + external.write_text("Not distribution content") + (source / "SOUL.md").symlink_to(external) + staged = [] + real_reject = distributions._reject_distribution_symlinks + + def inspect_staged(path): + staged.append((path, (path / "SOUL.md").is_symlink())) + real_reject(path) + + monkeypatch.setattr(distributions, "_reject_distribution_symlinks", inspect_staged) + with pytest.raises(DistributionError, match="symlink"): + install_distribution(str(source), name=name) + assert staged and staged[0][1] + assert not staged[0][0].is_relative_to(source) + assert not staged[0][0].is_relative_to(target) + assert not staged[0][0].exists() + assert external.read_text() == "Not distribution content" + assert not target.exists() + return + tombstoned = operation == "distribution_tombstone" if tombstoned: target.mkdir() @@ -78,6 +128,7 @@ def test_new_profile_targets_cannot_claim_default_namespace(profile_home, tmp_pa for operation in ("install", "update") for change in ( "delete", "rename", "tombstone", "recreate", "replacement", "source_replacement", + "source_file", "source_file_link", "source_dir_link", "publication_rename", "publication_delete", ) ]) @@ -98,6 +149,8 @@ def test_legacy_main_profile_remains_manageable(profile_home, tmp_path, monkeypa source = profile_home / "profiles" / "distribution" source.mkdir() (source / "SOUL.md").write_text("Updated distribution content") + (source / "skills").mkdir() + (source / "skills" / "guide.md").write_text("Planned skill content") manifest = DistributionManifest(name="main", source=str(source)) write_manifest(source, manifest) write_manifest(legacy, manifest) @@ -185,6 +238,26 @@ def replace_source(): write_manifest(source, manifest) (source / "SOUL.md").write_text("Unplanned source content") + def replace_payload(): + replacement = tmp_path / "replacement.md" + replacement.write_text("Unplanned source content") + replacement.replace(source / "SOUL.md") + (source / "skills" / "guide.md").write_text("Unplanned skill content") + write_manifest(source, DistributionManifest(name="other", version="9.9.9")) + + def link_payload(entry): + original = source / entry + external = tmp_path / "private" + if original.is_dir(): + shutil.rmtree(original) + external.mkdir() + (external / "guide.md").write_text("Private external content") + original.symlink_to(external, target_is_directory=True) + else: + original.unlink() + external.write_text("Private external content") + original.symlink_to(external) + mutations = { "delete": lambda: profiles.delete_profile(target_name, yes=True), "rename": lambda: profiles.rename_profile(target_name, "previous"), @@ -192,19 +265,34 @@ def replace_source(): "recreate": recreate, "replacement": replace_target, "source_replacement": replace_source, + "source_file": replace_payload, + "source_file_link": lambda: link_payload("SOUL.md"), + "source_dir_link": lambda: link_payload("skills"), } monkeypatch.setattr(distributions, "plan_install", pause_after_plan) with ThreadPoolExecutor(max_workers=1) as pool: pending = pool.submit(publish[finish]) try: assert planned.wait(10), "installation did not reach the planning barrier" + source_inode = source.stat().st_ino mutations[change]() + if change in {"source_file", "source_file_link", "source_dir_link"}: + assert source.stat().st_ino == source_inode existed = target.exists() contents = {p.relative_to(target): p.read_bytes() for p in target.rglob("*") if p.is_file()} finally: release.set() - with pytest.raises(DistributionError, match="changed"): - pending.result(timeout=10) + if change.startswith("source_"): + installed = pending.result(timeout=10) + assert installed.provenance == installed.manifest.source == str(source) + assert installed.manifest.version == manifest.version + assert (target / "SOUL.md").read_text() == "Updated distribution content" + assert (target / "skills" / "guide.md").read_text() == "Planned skill content" + assert not installed.staged_dir.exists() + return + else: + with pytest.raises(DistributionError, match="changed"): + pending.result(timeout=10) assert target.exists() == existed assert {p.relative_to(target): p.read_bytes() for p in target.rglob("*") if p.is_file()} == contents return From 09b60a3ec3eea20721af508229a5f0ec5a98204d Mon Sep 17 00:00:00 2001 From: guicybercode Date: Sun, 13 Sep 2026 04:46:50 -0300 Subject: [PATCH 5/8] fix(profiles): capture local distributions through verified source handles --- hermes_cli/profile_distribution.py | 124 ++++++++----- hermes_cli/profile_distribution_source.py | 66 +++++++ .../profile_distribution_source_windows.py | 173 ++++++++++++++++++ hermes_cli/profile_distribution_staging.py | 56 ++++++ .../hermes_cli/test_profile_main_namespace.py | 90 +++++++-- .../docs/user-guide/profile-distributions.md | 5 + 6 files changed, 449 insertions(+), 65 deletions(-) create mode 100644 hermes_cli/profile_distribution_source.py create mode 100644 hermes_cli/profile_distribution_source_windows.py create mode 100644 hermes_cli/profile_distribution_staging.py diff --git a/hermes_cli/profile_distribution.py b/hermes_cli/profile_distribution.py index 747254be47f4..2c620b960e3f 100644 --- a/hermes_cli/profile_distribution.py +++ b/hermes_cli/profile_distribution.py @@ -12,7 +12,7 @@ import shutil import subprocess import tempfile -from contextlib import ExitStack +from contextlib import ExitStack, contextmanager from dataclasses import dataclass, field from datetime import datetime, timezone from pathlib import Path, PurePosixPath @@ -145,16 +145,24 @@ def to_dict(self) -> Dict[str, Any]: return out +def _parse_manifest(content: bytes, mf_path: Path) -> DistributionManifest: + try: + data = yaml.safe_load(content.decode("utf-8")) + except Exception as exc: + raise DistributionError(f"Failed to parse {mf_path}: {exc}") from exc + return DistributionManifest.from_dict(data or {}) + + def read_manifest(profile_dir: Path) -> Optional[DistributionManifest]: """Return the manifest for *profile_dir*, or None if it isn't a distribution.""" mf_path = profile_dir / MANIFEST_FILENAME if not mf_path.is_file(): return None try: - data = yaml.safe_load(mf_path.read_text(encoding="utf-8")) - except Exception as exc: - raise DistributionError(f"Failed to parse {mf_path}: {exc}") from exc - return DistributionManifest.from_dict(data or {}) + content = mf_path.read_bytes() + except OSError as exc: + raise DistributionError(f"Failed to read {mf_path}: {exc}") from exc + return _parse_manifest(content, mf_path) def write_manifest(profile_dir: Path, manifest: DistributionManifest) -> Path: @@ -246,38 +254,67 @@ def _git_clone(url: str, dest: Path) -> None: raise DistributionError(f"git clone failed: {stderr.strip()}") from exc -def _stage_source(source: str, workdir: Path) -> Tuple[Path, str]: - """Resolve *source* to ``(staged_dir, provenance)``: git URLs are shallow-cloned into - *workdir* (``.git`` removed); local sources are copied there before planning.""" +@contextmanager +def _stage_source(source: str, workdir: Path, override_name: Optional[str] = None): + """Capture inputs before planning; remove only our staged tree on any failure.""" + from hermes_cli.profile_distribution_source import open_source + from hermes_cli.profile_distribution_staging import copy_source_tree, owned_stage, read_source_bytes + src_str = source.strip() - if _looks_like_git_url(src_str): - staged, provenance = workdir / "clone", src_str - _git_clone(src_str, staged) - shutil.rmtree(staged / ".git", ignore_errors=True) - missing = ( - f"No {MANIFEST_FILENAME} at the root of {src_str!r}. " - "This repository is not a Hermes profile distribution." - ) - elif (path_guess := Path(src_str).expanduser()).is_dir(): - local_source = path_guess.resolve() - staged, provenance = workdir / "local", str(local_source) - if staged.resolve().is_relative_to(local_source): - raise DistributionError("Distribution staging directory must be outside the local source.") - # Plan and publication read only this copy. Preserve links for the staged-tree - # validation to reject, instead of materializing their external targets. - shutil.copytree(local_source, staged, symlinks=True) - missing = ( - f"No {MANIFEST_FILENAME} in {path_guess}. " - "A local-directory source must contain a distribution.yaml at its root." - ) - else: + try: + if _looks_like_git_url(src_str): + staged = workdir / "clone" + with owned_stage(staged): + _git_clone(src_str, staged) + shutil.rmtree(staged / ".git", ignore_errors=True) + if not (staged / MANIFEST_FILENAME).is_file(): + raise DistributionError(f"No {MANIFEST_FILENAME} at the root of {src_str!r}.") + yield staged, src_str + elif (path_guess := Path(src_str).expanduser()).is_dir(): + local_source = path_guess.resolve() + staged = workdir / "local" + if staged.resolve().is_relative_to(local_source): + raise DistributionError("Distribution staging directory must be outside the local source.") + with ExitStack() as source_handles: + captured = source_handles.enter_context(open_source(local_source)) + try: + with captured.child(MANIFEST_FILENAME) as entry: + manifest_bytes = read_source_bytes(entry) + except FileNotFoundError as exc: + raise DistributionError(f"No {MANIFEST_FILENAME} in {local_source}.") from exc + manifest = _parse_manifest(manifest_bytes, local_source / MANIFEST_FILENAME) + with profile_lifecycle_lock(): + _plan_target(manifest, override_name, staged) + with owned_stage(staged): + copy_source_tree(captured, staged, MANIFEST_FILENAME, manifest_bytes) + # Validate the root before handing off the independent copy. Keeping + # the stage guard outside this close also cleans up validation failures. + source_handles.close() + yield staged, str(local_source) + else: + raise DistributionError( + f"Cannot resolve distribution source: {source!r}. " + "Expected a git URL (e.g. github.com/user/repo) or a local directory." + ) + except OSError as exc: + raise DistributionError(f"Could not stage profile distribution: {exc}") from exc + + +def _plan_target(manifest: DistributionManifest, override_name: Optional[str], staged: Path): + from hermes_cli.profiles import _canon_valid, _validate_new_profile_target, get_profile_dir, profile_exists + + canon = _canon_valid(override_name or manifest.name) + if canon == "default": raise DistributionError( - f"Cannot resolve distribution source: {source!r}. " - "Expected a git URL (e.g. github.com/user/repo) or a local directory." - ) - if not (staged / MANIFEST_FILENAME).is_file(): - raise DistributionError(missing) - return staged, provenance + "Cannot install a distribution as 'default' — that is the built-in " + "root profile (~/.hermes). Pass --name to install under a new profile." + ) + target_dir = get_profile_dir(canon) + if staged.resolve().is_relative_to(target_dir.resolve()): + raise DistributionError("Distribution staging directory must be outside the target profile.") + if not profile_exists(canon): + _validate_new_profile_target(canon) + return canon, target_dir, target_dir.is_dir() def _reject_distribution_symlinks(staged: Path) -> None: @@ -318,10 +355,8 @@ def plan_install( source: str, workdir: Path, override_name: Optional[str] = None, *, guards: ExitStack | None = None, ) -> InstallPlan: """Stage *source* and produce a plan describing what install would do.""" - from hermes_cli.profiles import _canon_valid, _validate_new_profile_target, get_profile_dir, profile_exists from hermes_cli import __version__ as hermes_version - staged, provenance = _stage_source(source, workdir) - with profile_lifecycle_lock(): + with _stage_source(source, workdir, override_name) as (staged, provenance), profile_lifecycle_lock(): _reject_distribution_symlinks(staged) manifest = read_manifest(staged) if manifest is None: @@ -329,22 +364,11 @@ def plan_install( f"No {MANIFEST_FILENAME} found at the distribution root — this source is not a Hermes distribution." ) check_hermes_requires(manifest.hermes_requires, hermes_version) # fail fast - canon = _canon_valid(override_name or manifest.name) - if canon == "default": - raise DistributionError( - "Cannot install a distribution as 'default' — that is the built-in " - "root profile (~/.hermes). Pass --name to install under a new profile." - ) + canon, target_dir, existing = _plan_target(manifest, override_name, staged) manifest.name = canon manifest.source = provenance # Stamped once here so both fresh install and update propagate a fresh timestamp. manifest.installed_at = datetime.now(timezone.utc).isoformat(timespec="seconds") - target_dir = get_profile_dir(canon) - if staged.resolve().is_relative_to(target_dir.resolve()): - raise DistributionError("Distribution staging directory must be outside the target profile.") - existing = target_dir.is_dir() - if not profile_exists(canon): - _validate_new_profile_target(canon) return InstallPlan( manifest=manifest, staged_dir=staged, provenance=provenance, target_dir=target_dir, existing=existing, source_identity=directory_identity(staged, guards), target_identity=directory_identity(target_dir, guards), diff --git a/hermes_cli/profile_distribution_source.py b/hermes_cli/profile_distribution_source.py new file mode 100644 index 000000000000..3709fa46d8d9 --- /dev/null +++ b/hermes_cli/profile_distribution_source.py @@ -0,0 +1,66 @@ +"""Read local distribution entries through handles that refuse symlinks.""" + +from contextlib import contextmanager +from dataclasses import dataclass +import os +from pathlib import Path +import stat + + +def _snapshot(info): + return (info.st_dev, info.st_ino, info.st_mode, info.st_size, info.st_mtime_ns, info.st_ctime_ns) + + +@dataclass +class _PosixSource: + path: Path + fd: int + mode: int + + @property + def is_dir(self) -> bool: + return stat.S_ISDIR(self.mode) + + def names(self) -> list[str]: + with os.scandir(self.fd) as entries: + return [entry.name for entry in entries] + + def read(self, size: int) -> bytes: + return os.read(self.fd, size) + + def child(self, name: str): + return _open_posix(self.path / name, parent_fd=self.fd) + + +@contextmanager +def _open_posix(path: Path, parent_fd: int | None = None): + address = path.name if parent_fd is not None else path + before = os.stat(address, dir_fd=parent_fd, follow_symlinks=False) + if stat.S_ISLNK(before.st_mode): + raise OSError(f"Profile distribution source contains a symlink: {path}") + if not (stat.S_ISREG(before.st_mode) or stat.S_ISDIR(before.st_mode)): + raise OSError(f"Profile distribution source is not a regular file or directory: {path}") + flags = os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK + if stat.S_ISDIR(before.st_mode): + flags |= os.O_DIRECTORY + fd = os.open(address, flags, dir_fd=parent_fd) + try: + opened = os.fstat(fd) + if _snapshot(before) != _snapshot(opened): + raise OSError(f"Profile distribution source changed before reading: {path}") + yield _PosixSource(path, fd, opened.st_mode) + current = os.stat(address, dir_fd=parent_fd, follow_symlinks=False) + if _snapshot(os.fstat(fd)) != _snapshot(opened) or _snapshot(current) != _snapshot(opened): + raise OSError(f"Profile distribution source changed while reading: {path}") + finally: + os.close(fd) + + +@contextmanager +def open_source(path: Path): + if os.name == "nt": + from hermes_cli.profile_distribution_source_windows import open_source as open_native + else: + open_native = _open_posix + with open_native(path) as source: + yield source diff --git a/hermes_cli/profile_distribution_source_windows.py b/hermes_cli/profile_distribution_source_windows.py new file mode 100644 index 000000000000..d4a3e68232a5 --- /dev/null +++ b/hermes_cli/profile_distribution_source_windows.py @@ -0,0 +1,173 @@ +"""Read a distribution source while native Windows handles pin its ancestry.""" + +from __future__ import annotations + +import ntpath +import os +import stat +import sys +from contextlib import ExitStack, contextmanager +from pathlib import Path + + +def _normal_path(value: str) -> str: + value = value.replace("/", "\\") + if value[:8].lower() == "\\\\?\\unc\\": + value = "\\\\" + value[8:] + elif value.startswith("\\\\?\\"): + value = value[4:] + return ntpath.normcase(ntpath.normpath(value)) + + +def _checked_stat(path: Path): + info = os.lstat(path) + if info.st_file_attributes & stat.FILE_ATTRIBUTE_REPARSE_POINT: + raise OSError(f"Distribution source contains a symlink or reparse point: {path}") + if not (stat.S_ISDIR(info.st_mode) or stat.S_ISREG(info.st_mode)): + raise OSError(f"Distribution source is not a regular file or directory: {path}") + return info + + +def _identity(info) -> tuple: + return info.st_dev, info.st_ino, info.st_mode, info.st_file_attributes + + +def _contents(info) -> tuple: + return _identity(info), info.st_size, info.st_mtime_ns + + +class _Source: + def __init__(self, path: Path, handle, expected, win32file): + self._path = path + self._handle = handle + self._expected = expected + self._win32file = win32file + self._entries = None + self._handle_contents = None + self.is_dir = stat.S_ISDIR(expected.st_mode) + self.mode = expected.st_mode + self._verify() + + def _verify(self) -> None: + win32file = self._win32file + if win32file.GetFileType(self._handle) != win32file.FILE_TYPE_DISK: + raise OSError(f"Distribution source is not a disk file: {self._path}") + info = win32file.GetFileInformationByHandle(self._handle) + if info[0] & stat.FILE_ATTRIBUTE_REPARSE_POINT: + raise OSError(f"Distribution source became a symlink or reparse point: {self._path}") + identity = info[4], (info[8] << 32) | info[9] + if identity != (self._expected.st_dev, self._expected.st_ino): + raise OSError(f"Distribution source identity changed: {self._path}") + if bool(info[0] & stat.FILE_ATTRIBUTE_DIRECTORY) != self.is_dir: + raise OSError(f"Distribution source type changed: {self._path}") + contents = info[3], (info[5] << 32) | info[6] + if self._handle_contents is None: + self._handle_contents = contents + if not self.is_dir and ( + contents != self._handle_contents or contents[1] != self._expected.st_size + ): + raise OSError(f"Distribution source handle changed while reading: {self._path}") + actual = win32file.GetFinalPathNameByHandle(self._handle, 0) + if _normal_path(actual) != _normal_path(str(self._path)): + raise OSError(f"Distribution source handle escaped its path: {self._path}") + current = _checked_stat(self._path) + if _identity(current) != _identity(self._expected): + raise OSError(f"Distribution source path changed: {self._path}") + # Ancestors outside the exported tree may have unrelated child activity. + # Only an enumerated source directory needs content-stability checks. + if (not self.is_dir or self._entries is not None) and ( + _contents(current) != _contents(self._expected) + ): + raise OSError(f"Distribution source changed while reading: {self._path}") + + def _scan(self) -> dict: + with os.scandir(self._path) as entries: + names = sorted(entry.name for entry in entries) + return {name: _checked_stat(self._path / name) for name in names} + + def names(self) -> list[str]: + if not self.is_dir: + raise OSError(f"Distribution source is not a directory: {self._path}") + self._verify() + entries = self._scan() + if self._entries is None: + self._entries = entries + elif {name: _contents(info) for name, info in entries.items()} != { + name: _contents(info) for name, info in self._entries.items() + }: + raise OSError(f"Distribution source entries changed: {self._path}") + self._verify() + return list(entries) + + def read(self, size: int) -> bytes: + if self.is_dir or size < 0: + raise OSError("Distribution source read requires a file and a bounded size") + self._verify() + error, data = self._win32file.ReadFile(self._handle, size) + if error: + raise OSError(error, f"Could not read distribution source: {self._path}") + self._verify() + return bytes(data) + + @contextmanager + def child(self, name: str): + if not self.is_dir or name in ("", ".", "..") or any(c in name for c in "\\/:\0"): + raise OSError("Distribution source child must be one path component") + self._verify() + if self._entries is not None and name not in self._entries: + raise OSError(f"Distribution source entry was not in the snapshot: {name}") + expected = self._entries[name] if self._entries is not None else None + with _open_one(self._path / name, self._win32file, expected) as source: + yield source + self._verify() + + +@contextmanager +def _open_one(path: Path, win32file, expected=None): + # OPEN_REPARSE_POINT applies to the final component only. Callers keep every + # ancestor open without WRITE/DELETE sharing before arriving at this path. + expected = expected if expected is not None else _checked_stat(path) + handle = win32file.CreateFile( + str(path), win32file.GENERIC_READ, win32file.FILE_SHARE_READ, None, + win32file.OPEN_EXISTING, + win32file.FILE_FLAG_OPEN_REPARSE_POINT | win32file.FILE_FLAG_BACKUP_SEMANTICS, + None, + ) + try: + source = _Source(path, handle, expected, win32file) + yield source + source._verify() + if source._entries is not None: + source.names() + finally: + win32file.CloseHandle(handle) + + +@contextmanager +def open_source(path: Path): + """Open without following any reparse component, retaining all ancestor handles.""" + if sys.platform != "win32": + raise OSError("Native Windows distribution sources require Windows") + import pywintypes + import win32file + + raw = str(path) + if "\0" in raw or raw.startswith("\\\\.\\"): + raise OSError("Distribution sources cannot use the Windows device namespace") + if raw[:8].lower() == "\\\\?\\unc\\": + raw = "\\\\" + raw[8:] + elif raw.startswith("\\\\?\\"): + raw = raw[4:] + if not ntpath.splitdrive(raw)[0].endswith(":"): + raise OSError("Distribution source must use a DOS drive or UNC filesystem path") + path = Path(os.path.abspath(raw)) + if not path.anchor or any(":" in part for part in path.parts[1:]): + raise OSError("Distribution source must use a filesystem path without alternate streams") + try: + with ExitStack() as stack: + source = stack.enter_context(_open_one(Path(path.anchor), win32file)) + for name in path.parts[1:]: + source = stack.enter_context(source.child(name)) + yield source + except pywintypes.error as exc: + raise OSError(exc.winerror, exc.strerror, str(path)) from exc diff --git a/hermes_cli/profile_distribution_staging.py b/hermes_cli/profile_distribution_staging.py new file mode 100644 index 000000000000..2fa5f11cc7fa --- /dev/null +++ b/hermes_cli/profile_distribution_staging.py @@ -0,0 +1,56 @@ +"""Capture distribution files into a private tree before interpreting the plan.""" + +from contextlib import contextmanager +import os +from pathlib import Path +import shutil +import stat + + +def read_source_bytes(source) -> bytes: + if source.is_dir: + raise OSError("Distribution manifest is not a regular file") + chunks = [] + while chunk := source.read(1024 * 1024): + chunks.append(chunk) + return b"".join(chunks) + + +def copy_source_tree(source, destination: Path, manifest_name: str = "", manifest_bytes: bytes = b"") -> None: + for name in source.names(): + target = destination / name + with source.child(name) as entry: + if entry.is_dir: + # Scratch directories stay writable until publication/cleanup. + target.mkdir(mode=0o700) + copy_source_tree(entry, target) + else: + with target.open("xb") as output: + if manifest_name and os.path.normcase(name) == os.path.normcase(manifest_name): + content = read_source_bytes(entry) + if content != manifest_bytes: + raise OSError("Distribution manifest changed during staging") + output.write(content) + else: + while chunk := entry.read(1024 * 1024): + output.write(chunk) + os.chmod(target, stat.S_IMODE(entry.mode)) + + +@contextmanager +def owned_stage(path: Path): + # A caller's pre-existing tree is never ours to remove on failure. + path.mkdir(mode=0o700, parents=True, exist_ok=False) + try: + yield path + except BaseException as exc: + from hermes_cli.profiles import _rmtree_make_writable + + try: + shutil.rmtree(path, onerror=_rmtree_make_writable) + except OSError as cleanup_error: + if isinstance(exc, (KeyboardInterrupt, SystemExit)): + exc.add_note(f"Could not clean distribution stage {path}: {cleanup_error}") + else: + raise OSError(f"Could not clean distribution stage {path}: {cleanup_error}") from exc + raise diff --git a/tests/hermes_cli/test_profile_main_namespace.py b/tests/hermes_cli/test_profile_main_namespace.py index 6a3566c351f5..88486bd02ed5 100644 --- a/tests/hermes_cli/test_profile_main_namespace.py +++ b/tests/hermes_cli/test_profile_main_namespace.py @@ -2,6 +2,7 @@ import tarfile import shutil +import os from concurrent.futures import ThreadPoolExecutor from contextlib import contextmanager from pathlib import Path @@ -40,6 +41,7 @@ def profile_home(tmp_path, monkeypatch): @pytest.mark.parametrize("operation", [ "create", "import", "rename", "distribution", "distribution_tombstone", "distribution_symlink", "stage_inside_source", "stage_inside_target", + "stage_file_link", "stage_dir_link", "stage_disappears", "stage_permission", "stage_manifest", "stage_existing", ]) @pytest.mark.parametrize("name", ["main", "MAIN", " main "]) def test_new_profile_targets_cannot_claim_default_namespace(profile_home, tmp_path, monkeypatch, operation, name): @@ -52,6 +54,69 @@ def test_new_profile_targets_cannot_claim_default_namespace(profile_home, tmp_pa bundle.add(source, arcname="source") write_manifest(source, DistributionManifest(name="source")) target = profile_home / "profiles" / "main" + if operation == "stage_existing": + target.mkdir() + (target / "config.yaml").write_text(config) + workdir = tmp_path / "staging" + previous = workdir / "local" + previous.mkdir(parents=True) + (previous / "keep.md").write_text("Caller-owned tree") + with pytest.raises(DistributionError): + distributions.plan_install(str(source), workdir, override_name=name) + assert list(previous.iterdir()) == [previous / "keep.md"] + assert (previous / "keep.md").read_text() == "Caller-owned tree" + assert (target / "config.yaml").read_text() == config + return + + if operation in {"stage_file_link", "stage_dir_link", "stage_disappears", "stage_permission", "stage_manifest"}: + (source / "SOUL.md").write_text("Planned source content") + (source / "skills").mkdir() + (source / "skills" / "guide.md").write_text("Planned skill content") + target.mkdir() + (target / "config.yaml").write_text(config) + workdir = tmp_path / "staging" + external = tmp_path / "external" + root_stat = source.stat() + scanned = False + real_scandir = os.scandir + + @contextmanager + def mutate_after_enumeration(path): + nonlocal scanned + info = os.fstat(path) if isinstance(path, int) else Path(path).stat() + is_source = (info.st_dev, info.st_ino) == (root_stat.st_dev, root_stat.st_ino) + with real_scandir(path) as entries: + yield entries + if not is_source or scanned: + return + scanned = True + if operation == "stage_permission": + raise PermissionError("source permission changed during staging") + if operation == "stage_disappears": + (source / "SOUL.md").unlink() + return + if operation == "stage_manifest": + write_manifest(source, DistributionManifest(name="other", version="9.9.9")) + return + if operation == "stage_dir_link": + shutil.rmtree(source / "skills") + external.mkdir() + (external / "guide.md").write_text("External private content") + (source / "skills").symlink_to(external, target_is_directory=True) + else: + (source / "SOUL.md").unlink() + external.write_text("External private content") + (source / "SOUL.md").symlink_to(external) + + monkeypatch.setattr(os, "scandir", mutate_after_enumeration) + with pytest.raises(DistributionError): + distributions.plan_install(str(source), workdir, override_name=name) + assert scanned + assert not (workdir / "local").exists() + assert (target / "config.yaml").read_text() == config + assert not (target / "SOUL.md").exists() + return + if operation in {"stage_inside_source", "stage_inside_target"}: parent = source if operation == "stage_inside_source" else target / "skills" workdir = parent / "tmp" @@ -64,9 +129,10 @@ def refuse_recursive_copy(*args, **kwargs): else: (target / "config.yaml").write_text(config) (parent / "guide.md").write_text("Existing skill content") + write_manifest(source, DistributionManifest(name=name)) with pytest.raises(DistributionError, match="outside"): - distributions.plan_install(str(source), workdir, override_name=name) + distributions.plan_install(str(source), workdir) assert (source / "config.yaml").read_text() == config if operation == "stage_inside_source": assert not list(workdir.iterdir()) @@ -74,28 +140,22 @@ def refuse_recursive_copy(*args, **kwargs): else: assert (target / "config.yaml").read_text() == config assert (parent / "guide.md").read_text() == "Existing skill content" + assert not list(workdir.iterdir()) return if operation == "distribution_symlink": external = tmp_path / "private.md" external.write_text("Not distribution content") (source / "SOUL.md").symlink_to(external) - staged = [] - real_reject = distributions._reject_distribution_symlinks - - def inspect_staged(path): - staged.append((path, (path / "SOUL.md").is_symlink())) - real_reject(path) - - monkeypatch.setattr(distributions, "_reject_distribution_symlinks", inspect_staged) + target.mkdir() + (target / "config.yaml").write_text(config) + workdir = tmp_path / "staging" with pytest.raises(DistributionError, match="symlink"): - install_distribution(str(source), name=name) - assert staged and staged[0][1] - assert not staged[0][0].is_relative_to(source) - assert not staged[0][0].is_relative_to(target) - assert not staged[0][0].exists() + distributions.plan_install(str(source), workdir, override_name=name) + assert not (workdir / "local").exists() assert external.read_text() == "Not distribution content" - assert not target.exists() + assert (target / "config.yaml").read_text() == config + assert not (target / "SOUL.md").exists() return tombstoned = operation == "distribution_tombstone" diff --git a/website/docs/user-guide/profile-distributions.md b/website/docs/user-guide/profile-distributions.md index 620329a1ed26..3e02f19039b0 100644 --- a/website/docs/user-guide/profile-distributions.md +++ b/website/docs/user-guide/profile-distributions.md @@ -613,6 +613,11 @@ hermes profile delete research-bot-test --yes hermes profile install ~/.hermes/profiles/research-bot --name research-bot-test ``` +Local sources are copied into temporary staging before the install plan is built. +Links or changes detected during that copy stop installation before it updates the +target profile. Finish editing the source and retry. Staging must be outside both +the source directory and the destination profile. + --- ## Export and import a profile file From e8f2a8ebcef4b77a1fa80dab6869fc7400e31139 Mon Sep 17 00:00:00 2001 From: guicybercode Date: Sun, 13 Sep 2026 05:17:08 -0300 Subject: [PATCH 6/8] fix(profiles): publish the approved distribution snapshot --- hermes_cli/profile_cmd.py | 17 +- hermes_cli/profile_distribution.py | 174 ++++++---- .../profile_distribution_source_windows.py | 20 +- hermes_cli/profile_distribution_staging.py | 120 +++++-- .../hermes_cli/test_profile_main_namespace.py | 298 +++++++++++++++++- .../docs/user-guide/profile-distributions.md | 4 + 6 files changed, 535 insertions(+), 98 deletions(-) diff --git a/hermes_cli/profile_cmd.py b/hermes_cli/profile_cmd.py index 0ac0f7daff11..94e20bf5e7fc 100644 --- a/hermes_cli/profile_cmd.py +++ b/hermes_cli/profile_cmd.py @@ -493,20 +493,19 @@ def _profile_import(args): def _profile_install(args): import tempfile - from hermes_cli.profile_distribution import DistributionError, install_distribution, plan_install + from contextlib import ExitStack + from hermes_cli.profile_distribution import DistributionError, install_plan, plan_install try: - # Preview: stage into a scratch dir, show the manifest, then do the real install. - # The double-stage avoids any side-effects if the user declines. - with tempfile.TemporaryDirectory(prefix="hermes_dist_preview_") as tmp: - plan = plan_install(args.source, Path(tmp), override_name=getattr(args, "install_name", None)) + # Keep the approved artifact and directory identities alive through publication. + with tempfile.TemporaryDirectory(prefix="hermes_dist_preview_") as tmp, ExitStack() as guards: + plan = plan_install( + args.source, Path(tmp), override_name=getattr(args, "install_name", None), guards=guards, + ) _render_distribution_plan(plan) if not getattr(args, "yes", False) and not _confirm("\nProceed with install? [y/N] "): print("Install cancelled.") return - plan = install_distribution( - args.source, name=getattr(args, "install_name", None), force=getattr(args, "force", False), - create_alias=getattr(args, "alias", False), - ) + install_plan(plan, force=getattr(args, "force", False), create_alias=getattr(args, "alias", False)) print(f"\n✓ Installed '{plan.manifest.name}' v{plan.manifest.version}") print(f" Profile path: {plan.target_dir}") if plan.manifest.env_requires: diff --git a/hermes_cli/profile_distribution.py b/hermes_cli/profile_distribution.py index 2c620b960e3f..91c13c47e472 100644 --- a/hermes_cli/profile_distribution.py +++ b/hermes_cli/profile_distribution.py @@ -21,6 +21,7 @@ import yaml from hermes_cli._subprocess_compat import noninteractive_git_env +from hermes_cli.profile_distribution_staging import SourceSnapshot from hermes_cli.profiles_lifecycle import directory_identity, profile_lifecycle_lock from hermes_constants import named_profile_is_deleted @@ -317,18 +318,6 @@ def _plan_target(manifest: DistributionManifest, override_name: Optional[str], s return canon, target_dir, target_dir.is_dir() -def _reject_distribution_symlinks(staged: Path) -> None: - """Reject symlinks before reading or copying distribution files.""" - for entry in staged.rglob("*"): - if not entry.is_symlink(): - continue - try: - rel = entry.relative_to(staged) - except ValueError: - rel = entry - raise DistributionError(f"Profile distributions cannot contain symlinks: {rel}") - - # Install @dataclass @@ -342,13 +331,20 @@ class InstallPlan: source_identity: tuple target_identity: tuple | None target_deleted: bool + source_snapshot: SourceSnapshot preserves_config: bool = True has_cron: bool = False -def _has_cron_jobs(staged: Path) -> bool: - cron_dir = staged / "cron" - return cron_dir.is_dir() and (any(cron_dir.rglob("*.json")) or any(cron_dir.rglob("*.yaml"))) +def _has_cron_jobs(snapshot: SourceSnapshot) -> bool: + def contains_jobs(entry): + return entry.children is not None and any( + name.endswith((".json", ".yaml")) or contains_jobs(child) + for name, child in entry.children.items() + ) + + cron = snapshot.children.get("cron") + return cron is not None and contains_jobs(cron) def plan_install( @@ -356,13 +352,17 @@ def plan_install( ) -> InstallPlan: """Stage *source* and produce a plan describing what install would do.""" from hermes_cli import __version__ as hermes_version + from hermes_cli.profile_distribution_source import open_source + from hermes_cli.profile_distribution_staging import read_source_bytes, seal_source_tree + with _stage_source(source, workdir, override_name) as (staged, provenance), profile_lifecycle_lock(): - _reject_distribution_symlinks(staged) - manifest = read_manifest(staged) - if manifest is None: - raise DistributionError( - f"No {MANIFEST_FILENAME} found at the distribution root — this source is not a Hermes distribution." - ) + with open_source(staged) as captured: + snapshot = seal_source_tree(captured) + with captured.child(MANIFEST_FILENAME) as entry: + manifest = _parse_manifest( + read_source_bytes(entry, expected=snapshot.children[MANIFEST_FILENAME]), + staged / MANIFEST_FILENAME, + ) check_hermes_requires(manifest.hermes_requires, hermes_version) # fail fast canon, target_dir, existing = _plan_target(manifest, override_name, staged) manifest.name = canon @@ -373,7 +373,7 @@ def plan_install( manifest=manifest, staged_dir=staged, provenance=provenance, target_dir=target_dir, existing=existing, source_identity=directory_identity(staged, guards), target_identity=directory_identity(target_dir, guards), target_deleted=named_profile_is_deleted(target_dir), - preserves_config=existing, has_cron=_has_cron_jobs(staged), + source_snapshot=snapshot, preserves_config=existing, has_cron=_has_cron_jobs(snapshot), ) @@ -387,16 +387,16 @@ def _revalidate_plan(plan: InstallPlan) -> None: raise DistributionError("Profile distribution source or destination changed after planning; retry the command.") -def _owned_entries(staged: Path, manifest: DistributionManifest): - """Yield ``(src, rel_parts)`` for every staged path the distribution owns.""" +def _owned_entries(snapshot: SourceSnapshot, manifest: DistributionManifest): + """Yield approved relative paths owned by this distribution.""" explicit_owned = [p for p in (p.strip().strip("/") for p in manifest.distribution_owned) if p] if not explicit_owned: # Legacy: no allowlist means the whole payload (minus USER_OWNED_EXCLUDE) is owned. # Do NOT narrow to DEFAULT_DIST_OWNED — existing distributions ship arbitrary extra # top-level paths without declaring them. - for entry in staged.iterdir(): - if entry.name not in USER_OWNED_EXCLUDE: - yield entry, (entry.name,) + for name in snapshot.children: + if name not in USER_OWNED_EXCLUDE: + yield (name,) return # Path-aware allowlist: copy exactly the declared paths. for rel in explicit_owned: @@ -405,47 +405,78 @@ def _owned_entries(staged: Path, manifest: DistributionManifest): continue if ".." in rel_parts or PurePosixPath(rel).is_absolute(): continue - src = staged.joinpath(*rel_parts) - if src.exists(): - yield src, rel_parts + entry = snapshot + for part in rel_parts: + if entry.children is None or part not in entry.children: + break + entry = entry.children[part] + else: + yield rel_parts + + +def _check_directory_snapshot(source, snapshot: SourceSnapshot) -> None: + if ( + not source.is_dir or snapshot.children is None or source.mode != snapshot.mode + or set(source.names()) != set(snapshot.children) + ): + raise DistributionError("Profile distribution contents changed after planning; retry the command.") -def _copy_dist_payload(staged: Path, target: Path, manifest: DistributionManifest, preserve_config: bool) -> None: +def _copy_owned_directory(source, destination: Path, snapshot: SourceSnapshot) -> None: + from hermes_cli.profile_distribution_staging import copy_source_tree + from hermes_cli.profiles import _rmtree_make_writable + + # Verify the entire replacement before removing a previously installed subtree. + with tempfile.TemporaryDirectory(prefix=".hermes-dist-", dir=destination.parent) as tmp: + replacement = Path(tmp) / "payload" + replacement.mkdir(mode=0o700) + copy_source_tree(source, replacement, expected=snapshot) + if destination.is_dir() and not destination.is_symlink(): + shutil.rmtree(destination, onerror=_rmtree_make_writable) + else: + destination.unlink(missing_ok=True) + replacement.replace(destination) + + +def _copy_dist_payload( + staged: Path, target: Path, manifest: DistributionManifest, preserve_config: bool, *, snapshot: SourceSnapshot, +) -> None: """Copy distribution-owned files (see ``_owned_entries``) from *staged* into *target*. User-owned paths are never touched. ``config.yaml`` is replaced only when ``preserve_config`` is False (fresh install / ``--force-config``). ``.env.template`` lands as ``.env.EXAMPLE`` so it never shadows a real ``.env``.""" - target.mkdir(parents=True, exist_ok=True) - staged_resolved = staged.resolve() - - def _ignore_user_owned(d, names): - # Only the staged root's direct children are filtered. - return [n for n in names if n in USER_OWNED_EXCLUDE] if Path(d).resolve() == staged_resolved else [] - - for src, rel_parts in _owned_entries(staged, manifest): - if len(rel_parts) == 1: - name = rel_parts[0] - if name == ENV_TEMPLATE_FILENAME: - shutil.copy2(src, target / ENV_EXAMPLE_FILENAME) - continue - if name == "config.yaml" and preserve_config and (target / "config.yaml").exists(): - continue - dest = target.joinpath(*rel_parts) - dest.parent.mkdir(parents=True, exist_ok=True) - if src.is_dir(): - if dest.exists(): - shutil.rmtree(dest) - shutil.copytree(src, dest, ignore=_ignore_user_owned) - else: - shutil.copy2(src, dest) - - # Emit .env.EXAMPLE from manifest if the staged tree didn't ship one - if manifest.env_requires and not (target / ENV_EXAMPLE_FILENAME).exists(): - (target / ENV_EXAMPLE_FILENAME).write_text(_env_template_from_manifest(manifest), encoding="utf-8") + from hermes_cli.profile_distribution_source import open_source + from hermes_cli.profile_distribution_staging import copy_source_file - # Make sure the manifest on disk reflects resolved name + source - write_manifest(target, manifest) + try: + with open_source(staged) as captured: + _check_directory_snapshot(captured, snapshot) + target.mkdir(parents=True, exist_ok=True) + for rel_parts in _owned_entries(snapshot, manifest): + if rel_parts == ("config.yaml",) and preserve_config and (target / "config.yaml").exists(): + continue + dest_parts = (ENV_EXAMPLE_FILENAME,) if rel_parts == (ENV_TEMPLATE_FILENAME,) else rel_parts + dest = target.joinpath(*dest_parts) + with ExitStack() as handles: + entry, expected = captured, snapshot + for part in rel_parts: + _check_directory_snapshot(entry, expected) + entry = handles.enter_context(entry.child(part)) + expected = expected.children[part] + dest.parent.mkdir(parents=True, exist_ok=True) + if entry.is_dir: + _check_directory_snapshot(entry, expected) + _copy_owned_directory(entry, dest, expected) + else: + copy_source_file(entry, dest, expected=expected) + + # Emit .env.EXAMPLE from manifest if the staged tree didn't ship one. + if manifest.env_requires and not (target / ENV_EXAMPLE_FILENAME).exists(): + (target / ENV_EXAMPLE_FILENAME).write_text(_env_template_from_manifest(manifest), encoding="utf-8") + write_manifest(target, manifest) + except OSError as exc: + raise DistributionError(f"Could not publish profile distribution: {exc}") from exc def _bootstrap_user_dirs(target: Path) -> None: @@ -458,11 +489,17 @@ def _bootstrap_user_dirs(target: Path) -> None: def install_distribution( source: str, name: Optional[str] = None, force: bool = False, create_alias: bool = False ) -> InstallPlan: - """Install a distribution from *source* into a new profile; returns the resolved plan. - Use :func:`plan_install` first to preview + prompt.""" - from hermes_cli.profiles import check_alias_collision, create_wrapper_script + """Stage and install a distribution; returns the resolved plan.""" with ExitStack() as guards, tempfile.TemporaryDirectory(prefix="hermes_dist_install_") as tmp: plan = plan_install(source, Path(tmp), override_name=name, guards=guards) + return install_plan(plan, force=force, create_alias=create_alias) + + +def install_plan(plan: InstallPlan, force: bool = False, create_alias: bool = False) -> InstallPlan: + """Publish the approved artifact while its caller retains the stage and identity guards.""" + from hermes_cli.profiles import check_alias_collision, create_wrapper_script + + try: with profile_lifecycle_lock(): _revalidate_plan(plan) if plan.existing and not force: @@ -473,10 +510,14 @@ def install_distribution( # Fresh install: config.yaml comes from the distribution. _bootstrap_user_dirs(plan.target_dir) - _copy_dist_payload(plan.staged_dir, plan.target_dir, plan.manifest, preserve_config=False) + _copy_dist_payload( + plan.staged_dir, plan.target_dir, plan.manifest, preserve_config=False, snapshot=plan.source_snapshot, + ) if create_alias and check_alias_collision(plan.manifest.name) is None: create_wrapper_script(plan.manifest.name) return plan + except OSError as exc: + raise DistributionError(f"Could not install profile distribution: {exc}") from exc def _existing_profile(profile_name: str) -> Tuple[str, Path]: @@ -514,7 +555,10 @@ def update_distribution(profile_name: str, force_config: bool = False) -> Instal _revalidate_plan(plan) if plan.target_identity != original_identity or read_manifest(target) != existing_manifest: raise DistributionError("Profile distribution destination changed while staging its update; retry the command.") - _copy_dist_payload(plan.staged_dir, plan.target_dir, plan.manifest, preserve_config=plan.preserves_config) + _copy_dist_payload( + plan.staged_dir, plan.target_dir, plan.manifest, + preserve_config=plan.preserves_config, snapshot=plan.source_snapshot, + ) return plan diff --git a/hermes_cli/profile_distribution_source_windows.py b/hermes_cli/profile_distribution_source_windows.py index d4a3e68232a5..96f37078057c 100644 --- a/hermes_cli/profile_distribution_source_windows.py +++ b/hermes_cli/profile_distribution_source_windows.py @@ -16,7 +16,11 @@ def _normal_path(value: str) -> str: value = "\\\\" + value[8:] elif value.startswith("\\\\?\\"): value = value[4:] - return ntpath.normcase(ntpath.normpath(value)) + value = ntpath.normcase(ntpath.normpath(value)) + drive, tail = ntpath.splitdrive(value) + # UNC share roots denote the same directory with or without the final slash. + # Keep drive-root slashes: C: and C:\\ have different meanings. + return drive if drive.startswith("\\\\") and tail == "\\" else value def _checked_stat(path: Path): @@ -68,8 +72,18 @@ def _verify(self) -> None: ): raise OSError(f"Distribution source handle changed while reading: {self._path}") actual = win32file.GetFinalPathNameByHandle(self._handle, 0) - if _normal_path(actual) != _normal_path(str(self._path)): - raise OSError(f"Distribution source handle escaped its path: {self._path}") + expected_path = _normal_path(str(self._path)) + if _normal_path(actual) != expected_path: + import win32api + + # TEMP can contain 8.3 aliases, while the handle reports long names. + # Expand only after validating the pinned handle's identity and type. + expected_path = _normal_path(win32api.GetLongPathNameW(str(self._path))) + if _normal_path(actual) != expected_path: + raise OSError( + f"Distribution source handle escaped its path: {self._path} " + f"(expected {expected_path!r}, handle {actual!r})" + ) current = _checked_stat(self._path) if _identity(current) != _identity(self._expected): raise OSError(f"Distribution source path changed: {self._path}") diff --git a/hermes_cli/profile_distribution_staging.py b/hermes_cli/profile_distribution_staging.py index 2fa5f11cc7fa..4a4e84010a88 100644 --- a/hermes_cli/profile_distribution_staging.py +++ b/hermes_cli/profile_distribution_staging.py @@ -1,40 +1,120 @@ -"""Capture distribution files into a private tree before interpreting the plan.""" +"""Capture distribution files and bind publication to the approved bytes.""" + +from __future__ import annotations from contextlib import contextmanager +from dataclasses import dataclass +import hashlib import os from pathlib import Path import shutil import stat +import tempfile + + +@dataclass(frozen=True) +class SourceSnapshot: + mode: int + digest: bytes | None = None + children: dict[str, SourceSnapshot] | None = None + +def _check_mode(source, expected: SourceSnapshot | None) -> None: + if expected is not None and source.mode != expected.mode: + raise OSError("Distribution source mode changed after planning") -def read_source_bytes(source) -> bytes: + +def _file_chunks(source, expected: SourceSnapshot | None = None): if source.is_dir: - raise OSError("Distribution manifest is not a regular file") - chunks = [] + raise OSError("Distribution source is not a regular file") + _check_mode(source, expected) + digest = hashlib.sha256() if expected is not None else None while chunk := source.read(1024 * 1024): - chunks.append(chunk) - return b"".join(chunks) + if digest is not None: + digest.update(chunk) + yield chunk + if digest is not None and digest.digest() != expected.digest: + raise OSError("Distribution source content changed after planning") + + +def read_source_bytes(source, *, expected: SourceSnapshot | None = None) -> bytes: + return b"".join(_file_chunks(source, expected)) + + +def seal_source_tree(source) -> SourceSnapshot: + """Seal bytes as well as metadata: size and mtime can survive a replacement.""" + if source.is_dir: + children = {} + for name in source.names(): + with source.child(name) as entry: + children[name] = seal_source_tree(entry) + return SourceSnapshot(source.mode, children=children) + digest = hashlib.sha256() + for chunk in _file_chunks(source): + digest.update(chunk) + return SourceSnapshot(source.mode, digest=digest.digest()) + + +def copy_source_file( + source, destination: Path, *, expected_bytes: bytes | None = None, + expected: SourceSnapshot | None = None, +) -> None: + temporary = None + try: + # A sibling temporary keeps unapproved bytes away from an existing file, + # and replace never follows a symlink at the final destination component. + with tempfile.NamedTemporaryFile( + mode="wb", prefix=".hermes-dist-", dir=destination.parent, delete=False, + ) as output: + temporary = Path(output.name) + if expected_bytes is not None: + content = read_source_bytes(source, expected=expected) + if content != expected_bytes: + raise OSError("Distribution manifest changed during staging") + output.write(content) + else: + for chunk in _file_chunks(source, expected): + output.write(chunk) + os.chmod(temporary, stat.S_IMODE(source.mode)) + os.replace(temporary, destination) + finally: + if temporary is not None: + try: + temporary.unlink(missing_ok=True) + except PermissionError: + # A read-only source also makes the temporary read-only on Windows. + temporary.chmod(stat.S_IRUSR | stat.S_IWUSR) + temporary.unlink(missing_ok=True) -def copy_source_tree(source, destination: Path, manifest_name: str = "", manifest_bytes: bytes = b"") -> None: - for name in source.names(): +def copy_source_tree( + source, destination: Path, manifest_name: str = "", manifest_bytes: bytes = b"", + *, expected: SourceSnapshot | None = None, +) -> None: + if not source.is_dir: + raise OSError("Distribution source is not a directory") + _check_mode(source, expected) + names = source.names() + if expected is not None and ( + expected.children is None or set(names) != set(expected.children) + ): + raise OSError("Distribution source entries changed after planning") + for name in names: target = destination / name with source.child(name) as entry: + child_expected = expected.children[name] if expected is not None else None if entry.is_dir: - # Scratch directories stay writable until publication/cleanup. + # Populate writable scratch directories before restoring source modes. target.mkdir(mode=0o700) - copy_source_tree(entry, target) + copy_source_tree(entry, target, expected=child_expected) else: - with target.open("xb") as output: - if manifest_name and os.path.normcase(name) == os.path.normcase(manifest_name): - content = read_source_bytes(entry) - if content != manifest_bytes: - raise OSError("Distribution manifest changed during staging") - output.write(content) - else: - while chunk := entry.read(1024 * 1024): - output.write(chunk) - os.chmod(target, stat.S_IMODE(entry.mode)) + approved_bytes = ( + manifest_bytes + if manifest_name and os.path.normcase(name) == os.path.normcase(manifest_name) + else None + ) + copy_source_file(entry, target, expected_bytes=approved_bytes, expected=child_expected) + os.chmod(destination, stat.S_IMODE(source.mode)) @contextmanager diff --git a/tests/hermes_cli/test_profile_main_namespace.py b/tests/hermes_cli/test_profile_main_namespace.py index 88486bd02ed5..beceb5e12816 100644 --- a/tests/hermes_cli/test_profile_main_namespace.py +++ b/tests/hermes_cli/test_profile_main_namespace.py @@ -3,10 +3,16 @@ import tarfile import shutil import os +import builtins +import io +import stat +import subprocess +import tempfile from concurrent.futures import ThreadPoolExecutor from contextlib import contextmanager from pathlib import Path from threading import Event +from types import SimpleNamespace import pytest @@ -183,16 +189,250 @@ def refuse_recursive_copy(*args, **kwargs): assert not profiles.find_alias_for_profile("main") -@pytest.mark.parametrize("finish,change", [("rename", None), ("delete", None), ("retry_delete", None)] + [ + +def _assert_confirmation_snapshot(source, legacy, tmp_path, monkeypatch, change): + from hermes_cli import profile_cmd + + if change == "confirm_git": + repository = tmp_path / "source.git" + shutil.copytree(source, repository) + + def git(*args): + return subprocess.run( + ["git", "-c", "user.name=Distribution fixture", "-c", "user.email=fixture@example.invalid", + "-C", str(repository), *args], + check=True, capture_output=True, text=True, + ).stdout.strip() + + git("init", "--initial-branch=main") + git("add", ".") + git("commit", "-m", "Approved distribution") + approved_commit = git("rev-parse", "HEAD") + else: + repository = source + approved = [] + render = profile_cmd._render_distribution_plan + + def record_preview(plan): + approved.append(plan) + assert (plan.staged_dir / "SOUL.md").read_text() == "Updated distribution content" + assert not plan.has_cron + render(plan) + + def confirm_and_change_source(prompt): + assert len(approved) == 1 + (repository / "SOUL.md").write_text("Unapproved content") + (repository / "cron").mkdir() + (repository / "cron" / "jobs.json").write_text('{"jobs": [{"prompt": "Unapproved job"}]}') + write_manifest(repository, DistributionManifest(name="main", version="9.9.9")) + if change == "confirm_git": + git("add", ".") + git("commit", "-m", "Move source after approval") + assert git("rev-parse", "HEAD") != approved_commit + return True + + monkeypatch.setattr(profile_cmd, "_render_distribution_plan", record_preview) + monkeypatch.setattr(profile_cmd, "_confirm", confirm_and_change_source) + profile_cmd._profile_install(SimpleNamespace(source=str(repository), install_name="main", force=True)) + assert (legacy / "SOUL.md").read_text() == "Updated distribution content" + assert not (legacy / "cron" / "jobs.json").exists() + installed_manifest = distributions.read_manifest(legacy) + assert installed_manifest.version == approved[0].manifest.version + assert installed_manifest.source == str(repository) + assert not approved[0].staged_dir.exists() + + +def _assert_directory_modes(source, legacy, monkeypatch, finish): + (source / "skills" / "empty").mkdir() + (source / "skills" / "readonly").mkdir() + (source / "skills" / "readonly" / "guide.md").write_text("Readable in an immutable directory") + expected_modes = {"skills": 0o755, "skills/empty": 0o750, "skills/readonly": 0o555} + for relative, mode in expected_modes.items(): + (source / relative).chmod(mode) + stages = [] + real_plan = distributions.plan_install + + def record_staged_modes(*args, **kwargs): + plan = real_plan(*args, **kwargs) + stages.append({relative: stat.S_IMODE((plan.staged_dir / relative).stat().st_mode) + for relative in expected_modes}) + return plan + + monkeypatch.setattr(distributions, "plan_install", record_staged_modes) + if finish == "install": + installed = install_distribution(str(source), name="main", force=True) + else: + installed = update_distribution("main") + assert stages == [expected_modes] + assert {relative: stat.S_IMODE((legacy / relative).stat().st_mode) + for relative in expected_modes} == expected_modes + assert not list((legacy / "skills" / "empty").iterdir()) + assert not installed.staged_dir.exists() + + +def _assert_windows_source_contract(tmp_path, monkeypatch, change): + from hermes_cli.profile_distribution_source import open_source + import win32file + + parent = tmp_path / "source-parent" + source = parent / "distribution" + source.mkdir(parents=True) + write_manifest(source, DistributionManifest(name="native-source")) + payload = b"payload\n" * 262144 + (source / "SOUL.md").write_bytes(payload) + (source / "empty.md").touch() + + if change in {"windows_junction", "windows_sharing"}: + if change == "windows_junction": + external = tmp_path / "private" + external.mkdir() + (external / "guide.md").write_bytes(b"SECRET outside distribution") + subprocess.run( + ["cmd", "/c", "mklink", "/J", str(source / "skills"), str(external)], + check=True, capture_output=True, + ) + observed = [] + read_file = win32file.ReadFile + + def observe_read(*args, **kwargs): + result = read_file(*args, **kwargs) + observed.append(bytes(result[1])) + return result + + monkeypatch.setattr(win32file, "ReadFile", observe_read) + try: + with pytest.raises(DistributionError, match="symlink|reparse"): + distributions.plan_install(str(source), tmp_path / "work") + assert not any(b"SECRET outside distribution" in data for data in observed) + finally: + os.rmdir(source / "skills") + else: + writer = win32file.CreateFile( + str(source / "SOUL.md"), win32file.GENERIC_WRITE, + win32file.FILE_SHARE_READ | win32file.FILE_SHARE_WRITE | win32file.FILE_SHARE_DELETE, + None, win32file.OPEN_EXISTING, 0, None, + ) + try: + with pytest.raises(DistributionError): + distributions.plan_install(str(source), tmp_path / "work") + finally: + win32file.CloseHandle(writer) + assert not (tmp_path / "work" / "local").exists() + moved = tmp_path / "released-parent" + parent.rename(moved) + installed = install_distribution(str(moved / "distribution")) + assert (installed.target_dir / "SOUL.md").read_bytes() == payload + return + + if change == "windows_ancestry": + with open_source(source) as captured: + with pytest.raises(PermissionError): + parent.rename(tmp_path / "moved-parent") + with captured.child("SOUL.md") as entry: + assert entry.read(7) == payload[:7] + parent.rename(tmp_path / "moved-parent") + assert (tmp_path / "moved-parent" / "distribution" / "SOUL.md").read_bytes() == payload + return + + if change in {"windows_unc", "windows_extended_unc"} and not tmp_path.drive.startswith("\\\\"): + pytest.skip("Run with --basetemp on a real writable SMB share for native UNC coverage") + with tempfile.TemporaryDirectory(dir=tmp_path) as workspace: + exported = Path(workspace) / "distribution" + shutil.copytree(source, exported) + raw = str(exported) + if change in {"windows_unc", "windows_extended_unc"}: + assert raw.startswith("\\\\") + if change == "windows_extended_unc": + raw = "\\\\?\\UNC\\" + raw[2:] + elif change == "windows_extended_path": + raw = "\\\\?\\" + raw + elif change == "windows_short_path": + import win32api + + short_path = win32api.GetShortPathName(raw) + if os.path.normcase(short_path) == os.path.normcase(raw): + pytest.skip("The source volume must provide 8.3 aliases for native short-path coverage") + assert Path(short_path).samefile(exported) + raw = short_path + with open_source(Path(raw)) as captured: + for name, expected in (("SOUL.md", payload), ("empty.md", b"")): + with captured.child(name) as entry: + chunks = [] + while chunk := entry.read(1024 * 1024): + chunks.append(chunk) + assert b"".join(chunks) == expected + assert entry.read(1024 * 1024) == b"" + + +def _observe_private_reads(private_file, monkeypatch): + expected = private_file.stat() + observed = [] + + def record(descriptor): + opened = os.fstat(descriptor) + if (opened.st_dev, opened.st_ino) == (expected.st_dev, expected.st_ino): + observed.append("external file opened for reading") + + def observe_open(original): + def tracked(*args, **kwargs): + opened = original(*args, **kwargs) + mode = kwargs.get("mode", args[1] if len(args) > 1 else "r") + if "r" in mode or "+" in mode: + record(opened.fileno()) + return opened + return tracked + + original_open = os.open + + def tracked_descriptor(path, flags, *args, **kwargs): + descriptor = original_open(path, flags, *args, **kwargs) + if flags & (os.O_WRONLY | os.O_RDWR) != os.O_WRONLY: + record(descriptor) + return descriptor + + monkeypatch.setattr(builtins, "open", observe_open(builtins.open)) + monkeypatch.setattr(io, "open", observe_open(io.open)) + monkeypatch.setattr(os, "open", tracked_descriptor) + if os.name == "nt": + import win32file + original_read = win32file.ReadFile + + def tracked_native_read(*args, **kwargs): + result = original_read(*args, **kwargs) + if b"SECRET outside distribution" in result[1]: + observed.append("external bytes read through native handle") + return result + + monkeypatch.setattr(win32file, "ReadFile", tracked_native_read) + return observed + + +@pytest.mark.parametrize("finish,change", [("rename", None), ("delete", None), ("retry_delete", None), + ("install", "confirm_local"), ("install", "confirm_git"), +] + [ (operation, change) for operation in ("install", "update") for change in ( "delete", "rename", "tombstone", "recreate", "replacement", "source_replacement", "source_file", "source_file_link", "source_dir_link", "publication_rename", "publication_delete", + "staged_file_link", "staged_dir_link", "staged_file_replace", "staged_file_write", + ) +] + [ + pytest.param(operation, "directory_modes", marks=marker, id=f"{operation}-directory_modes-{host}") + for operation in ("install", "update") + for host, marker in (("linux", pytest.mark.linux_only), ("macos", pytest.mark.macos_only)) +] + [ + pytest.param("install", change, marks=pytest.mark.windows_only) + for change in ( + "windows_eof", "windows_extended_path", "windows_short_path", "windows_unc", "windows_extended_unc", + "windows_junction", "windows_sharing", "windows_ancestry", ) ]) def test_legacy_main_profile_remains_manageable(profile_home, tmp_path, monkeypatch, finish, change): + if change is not None and change.startswith("windows_"): + _assert_windows_source_contract(tmp_path, monkeypatch, change) + return legacy = profile_home / "profiles" / "main" legacy.mkdir(parents=True) config = "model:\n provider: custom\n default: local-model\n" @@ -219,6 +459,13 @@ def test_legacy_main_profile_remains_manageable(profile_home, tmp_path, monkeypa assert (legacy / "SOUL.md").read_text() == (source / "SOUL.md").read_text() assert (legacy / "config.yaml").read_text() == config + if change in {"confirm_local", "confirm_git"}: + _assert_confirmation_snapshot(source, legacy, tmp_path, monkeypatch, change) + return + if change == "directory_modes": + _assert_directory_modes(source, legacy, monkeypatch, finish) + return + if change is not None: target_name = "copy" if change == "replacement" else "main" target = profiles.get_profile_dir(target_name) @@ -230,6 +477,55 @@ def test_legacy_main_profile_remains_manageable(profile_home, tmp_path, monkeypa "update": lambda: update_distribution(target_name), } + if change.startswith("staged_"): + plans = [] + private_reads = [] + revalidate = distributions._revalidate_plan + + def pause_after_revalidation(plan): + revalidate(plan) + plans.append(plan) + planned.set() + assert release.wait(10), "test did not release publication" + + monkeypatch.setattr(distributions, "_revalidate_plan", pause_after_revalidation) + with ThreadPoolExecutor(max_workers=1) as pool: + pending = pool.submit(publish[finish]) + try: + assert planned.wait(10), "publication did not reach revalidation" + staged = plans[0].staged_dir + root_inode = staged.stat().st_ino + external = tmp_path / "private" + if change == "staged_dir_link": + external.mkdir() + (external / "guide.md").write_text("SECRET outside distribution") + shutil.rmtree(staged / "skills") + (staged / "skills").symlink_to(external, target_is_directory=True) + elif change == "staged_file_link": + external.write_text("SECRET outside distribution") + (staged / "SOUL.md").unlink() + (staged / "SOUL.md").symlink_to(external) + elif change == "staged_file_replace": + external.write_text("Unapproved replacement") + external.replace(staged / "SOUL.md") + else: + (staged / "SOUL.md").write_text("Unapproved overwrite") + assert staged.stat().st_ino == root_inode + if change in {"staged_file_link", "staged_dir_link"}: + private_file = external / "guide.md" if change == "staged_dir_link" else external + private_reads = _observe_private_reads(private_file, monkeypatch) + finally: + release.set() + try: + pending.result(timeout=10) + except DistributionError: + pass + assert not private_reads + assert (target / "SOUL.md").read_text() == "Updated distribution content" + assert (target / "skills" / "guide.md").read_text() == "Planned skill content" + assert not plans[0].staged_dir.exists() + return + if change.startswith("publication_"): from hermes_cli import profiles_lifecycle diff --git a/website/docs/user-guide/profile-distributions.md b/website/docs/user-guide/profile-distributions.md index 3e02f19039b0..3e9f9645f056 100644 --- a/website/docs/user-guide/profile-distributions.md +++ b/website/docs/user-guide/profile-distributions.md @@ -618,6 +618,10 @@ Links or changes detected during that copy stop installation before it updates t target profile. Finish editing the source and retry. Staging must be outside both the source directory and the destination profile. +Interactive installation applies the staged copy shown at confirmation. Later edits +to the source or a moving Git branch do not change that approved installation. +On POSIX systems, file and directory permission bits are preserved when copying. + --- ## Export and import a profile file From af828915b92c200576fbb602fffa4ec7c6d607e3 Mon Sep 17 00:00:00 2001 From: guicybercode Date: Sun, 13 Sep 2026 05:47:33 -0300 Subject: [PATCH 7/8] fix(profiles): publish complete distributions with rollback --- hermes_cli/profile_distribution.py | 135 ++++++++-------- .../profile_distribution_transaction.py | 151 ++++++++++++++++++ .../hermes_cli/test_profile_main_namespace.py | 139 +++++++++++++++- .../docs/user-guide/profile-distributions.md | 4 + 4 files changed, 363 insertions(+), 66 deletions(-) create mode 100644 hermes_cli/profile_distribution_transaction.py diff --git a/hermes_cli/profile_distribution.py b/hermes_cli/profile_distribution.py index 91c13c47e472..2aed9357eea0 100644 --- a/hermes_cli/profile_distribution.py +++ b/hermes_cli/profile_distribution.py @@ -422,70 +422,82 @@ def _check_directory_snapshot(source, snapshot: SourceSnapshot) -> None: raise DistributionError("Profile distribution contents changed after planning; retry the command.") -def _copy_owned_directory(source, destination: Path, snapshot: SourceSnapshot) -> None: - from hermes_cli.profile_distribution_staging import copy_source_tree - from hermes_cli.profiles import _rmtree_make_writable - - # Verify the entire replacement before removing a previously installed subtree. - with tempfile.TemporaryDirectory(prefix=".hermes-dist-", dir=destination.parent) as tmp: - replacement = Path(tmp) / "payload" - replacement.mkdir(mode=0o700) - copy_source_tree(source, replacement, expected=snapshot) - if destination.is_dir() and not destination.is_symlink(): - shutil.rmtree(destination, onerror=_rmtree_make_writable) - else: - destination.unlink(missing_ok=True) - replacement.replace(destination) - +def _publication_entries(plan: InstallPlan, preserve_config: bool): + entries = {} + for source_parts in _owned_entries(plan.source_snapshot, plan.manifest): + if source_parts == ("config.yaml",) and preserve_config and (plan.target_dir / "config.yaml").exists(): + continue + destination = (ENV_EXAMPLE_FILENAME,) if source_parts == (ENV_TEMPLATE_FILENAME,) else source_parts + entries[destination] = source_parts + # Publishing a selected ancestor already includes its selected descendants. + return { + destination: source for destination, source in entries.items() + if not any(destination[:length] in entries for length in range(1, len(destination))) + } -def _copy_dist_payload( - staged: Path, target: Path, manifest: DistributionManifest, preserve_config: bool, *, snapshot: SourceSnapshot, -) -> None: - """Copy distribution-owned files (see ``_owned_entries``) from *staged* into *target*. - User-owned paths are never touched. ``config.yaml`` is replaced only when - ``preserve_config`` is False (fresh install / ``--force-config``). ``.env.template`` lands - as ``.env.EXAMPLE`` so it never shadows a real ``.env``.""" +def _materialize_dist_payload(plan: InstallPlan, prepared: Path, preserve_config: bool): + """Validate every owned entry before touching the installed profile.""" from hermes_cli.profile_distribution_source import open_source - from hermes_cli.profile_distribution_staging import copy_source_file + from hermes_cli.profile_distribution_staging import copy_source_file, copy_source_tree + from utils import _preserve_file_mode + + entries = _publication_entries(plan, preserve_config) + with open_source(plan.staged_dir) as captured: + _check_directory_snapshot(captured, plan.source_snapshot) + for destination, source_parts in entries.items(): + dest = prepared.joinpath(*destination) + with ExitStack() as handles: + entry, expected = captured, plan.source_snapshot + for part in source_parts: + _check_directory_snapshot(entry, expected) + entry = handles.enter_context(entry.child(part)) + expected = expected.children[part] + dest.parent.mkdir(parents=True, exist_ok=True) + if entry.is_dir: + _check_directory_snapshot(entry, expected) + dest.mkdir(mode=0o700) + copy_source_tree(entry, dest, expected=expected) + else: + copy_source_file(entry, dest, expected=expected) + + if ( + plan.manifest.env_requires and not (prepared / ENV_EXAMPLE_FILENAME).exists() + and not (plan.target_dir / ENV_EXAMPLE_FILENAME).exists() + ): + (prepared / ENV_EXAMPLE_FILENAME).write_text(_env_template_from_manifest(plan.manifest), encoding="utf-8") + entries[(ENV_EXAMPLE_FILENAME,)] = None + manifest_mode = ( + _preserve_file_mode(plan.target_dir / MANIFEST_FILENAME) + if (MANIFEST_FILENAME,) not in entries else None + ) + manifest_path = write_manifest(prepared, plan.manifest) + if manifest_mode is not None: + manifest_path.chmod(manifest_mode) + entries[(MANIFEST_FILENAME,)] = None + return list(entries) + + +def _copy_dist_payload(plan: InstallPlan, preserve_config: bool, *, empty_dirs=()) -> None: + """Materialize the approved owned paths, then commit them with rollback on failure. + + The profile root and user-owned paths stay in place. Config preservation and the + .env.template -> .env.EXAMPLE mapping are resolved before publication begins. + """ + from hermes_cli.profile_distribution_transaction import commit_owned_payload try: - with open_source(staged) as captured: - _check_directory_snapshot(captured, snapshot) - target.mkdir(parents=True, exist_ok=True) - for rel_parts in _owned_entries(snapshot, manifest): - if rel_parts == ("config.yaml",) and preserve_config and (target / "config.yaml").exists(): - continue - dest_parts = (ENV_EXAMPLE_FILENAME,) if rel_parts == (ENV_TEMPLATE_FILENAME,) else rel_parts - dest = target.joinpath(*dest_parts) - with ExitStack() as handles: - entry, expected = captured, snapshot - for part in rel_parts: - _check_directory_snapshot(entry, expected) - entry = handles.enter_context(entry.child(part)) - expected = expected.children[part] - dest.parent.mkdir(parents=True, exist_ok=True) - if entry.is_dir: - _check_directory_snapshot(entry, expected) - _copy_owned_directory(entry, dest, expected) - else: - copy_source_file(entry, dest, expected=expected) - - # Emit .env.EXAMPLE from manifest if the staged tree didn't ship one. - if manifest.env_requires and not (target / ENV_EXAMPLE_FILENAME).exists(): - (target / ENV_EXAMPLE_FILENAME).write_text(_env_template_from_manifest(manifest), encoding="utf-8") - write_manifest(target, manifest) + # The lifecycle lock has created this parent. A sibling also keeps all commit + # renames on the target filesystem without putting scratch files in the profile. + with tempfile.TemporaryDirectory(prefix=".hermes-dist-publish-", dir=plan.target_dir.parent) as tmp: + prepared = Path(tmp) + paths = _materialize_dist_payload(plan, prepared, preserve_config) + _revalidate_plan(plan) + commit_owned_payload(plan.target_dir, prepared, paths, empty_dirs=empty_dirs) except OSError as exc: raise DistributionError(f"Could not publish profile distribution: {exc}") from exc -def _bootstrap_user_dirs(target: Path) -> None: - """Create the bootstrap dirs a fresh profile expects (same set as ``create_profile``).""" - from hermes_cli.profiles import _PROFILE_DIRS - for d in _PROFILE_DIRS: - (target / d).mkdir(parents=True, exist_ok=True) - - def install_distribution( source: str, name: Optional[str] = None, force: bool = False, create_alias: bool = False ) -> InstallPlan: @@ -497,7 +509,7 @@ def install_distribution( def install_plan(plan: InstallPlan, force: bool = False, create_alias: bool = False) -> InstallPlan: """Publish the approved artifact while its caller retains the stage and identity guards.""" - from hermes_cli.profiles import check_alias_collision, create_wrapper_script + from hermes_cli.profiles import _PROFILE_DIRS, check_alias_collision, create_wrapper_script try: with profile_lifecycle_lock(): @@ -508,11 +520,7 @@ def install_plan(plan: InstallPlan, force: bool = False, create_alias: bool = Fa "Use `hermes profile update` to upgrade in place, or pass --force to overwrite." ) - # Fresh install: config.yaml comes from the distribution. - _bootstrap_user_dirs(plan.target_dir) - _copy_dist_payload( - plan.staged_dir, plan.target_dir, plan.manifest, preserve_config=False, snapshot=plan.source_snapshot, - ) + _copy_dist_payload(plan, preserve_config=False, empty_dirs=tuple((name,) for name in _PROFILE_DIRS)) if create_alias and check_alias_collision(plan.manifest.name) is None: create_wrapper_script(plan.manifest.name) return plan @@ -555,10 +563,7 @@ def update_distribution(profile_name: str, force_config: bool = False) -> Instal _revalidate_plan(plan) if plan.target_identity != original_identity or read_manifest(target) != existing_manifest: raise DistributionError("Profile distribution destination changed while staging its update; retry the command.") - _copy_dist_payload( - plan.staged_dir, plan.target_dir, plan.manifest, - preserve_config=plan.preserves_config, snapshot=plan.source_snapshot, - ) + _copy_dist_payload(plan, preserve_config=plan.preserves_config) return plan diff --git a/hermes_cli/profile_distribution_transaction.py b/hermes_cli/profile_distribution_transaction.py new file mode 100644 index 000000000000..3ae66dd8de62 --- /dev/null +++ b/hermes_cli/profile_distribution_transaction.py @@ -0,0 +1,151 @@ +"""Publish a prepared distribution without replacing the profile root.""" + +from __future__ import annotations + +import errno +import logging +import os +from pathlib import Path +import shutil +import stat +import tempfile +from collections.abc import Sequence + + +logger = logging.getLogger(__name__) + + +def _checked_paths(paths: Sequence[tuple[str, ...]]) -> tuple[tuple[str, ...], ...]: + result = tuple(tuple(parts) for parts in paths) + for parts in result: + if not parts or any( + not part or part in (".", "..") or "\0" in part or Path(part).name != part + or (os.name == "nt" and ":" in part) + for part in parts + ): + raise OSError("Distribution publication requires relative path components") + return result + + +def _is_reparse(info) -> bool: + return bool(getattr(info, "st_file_attributes", 0) & stat.FILE_ATTRIBUTE_REPARSE_POINT) + + +def _ensure_directory(target: Path, parts: tuple[str, ...], created: list[Path]) -> None: + current = target + for part in (None, *parts): + if part is not None: + current = current / part + try: + info = current.lstat() + except FileNotFoundError: + current.mkdir() + created.append(current) + else: + if not stat.S_ISDIR(info.st_mode) or _is_reparse(info): + raise OSError(f"Distribution destination parent is not a plain directory: {current}") + + +def _remove_backup(path: Path) -> None: + from hermes_cli.profiles import _rmtree_make_writable + + shutil.rmtree(path, onerror=_rmtree_make_writable) + + +def commit_owned_payload( + target: Path, prepared_root: Path, relative_paths: Sequence[tuple[str, ...]], + *, empty_dirs: Sequence[tuple[str, ...]] = (), +) -> None: + """Commit disjoint, fully validated entries under the profile lifecycle lock. + + Renames preserve originals for rollback on an exception, including cancellation. + This does not provide isolation from external readers or recovery after power loss. + """ + paths = _checked_paths(relative_paths) + directories = _checked_paths(empty_dirs) + ordered = sorted(tuple(os.path.normcase(part) for part in parts) for parts in paths) + if any(right[:len(left)] == left for left, right in zip(ordered, ordered[1:])): + raise OSError("Distribution publication paths must be disjoint") + device = target.parent.stat().st_dev + if prepared_root.stat().st_dev != device or ( + os.path.lexists(target) and target.lstat().st_dev != device + ): + raise OSError("Distribution publication requires preparation on the profile filesystem") + for parts in paths: + info = prepared_root.joinpath(*parts).lstat() + if info.st_dev != device or _is_reparse(info) or not ( + stat.S_ISREG(info.st_mode) or stat.S_ISDIR(info.st_mode) + ): + raise OSError("Prepared distribution entries must be local regular files or directories") + + # Keep backups outside the caller's temporary tree: a failed rollback must + # never let its cleanup delete the only recoverable copy of an original. + backup_root = Path(tempfile.mkdtemp(prefix=".hermes-dist-rollback-", dir=target.parent)) + created: list[Path] = [] + journal: list[tuple[Path, Path, Path, bool]] = [] + try: + _ensure_directory(target, (), created) + for parts in paths: + _ensure_directory(target, parts[:-1], created) + source = prepared_root.joinpath(*parts) + destination = target.joinpath(*parts) + backup = backup_root.joinpath(*parts) + existed = os.path.lexists(destination) + # Register before either rename. Presence of source/backup also covers + # an interrupt delivered immediately after a successful native rename. + journal.append((source, destination, backup, existed)) + if existed: + backup.parent.mkdir(parents=True, exist_ok=True) + os.replace(destination, backup) + os.replace(source, destination) + for parts in directories: + # Existing bootstrap dirs can be user-owned links. Reuse them without + # writing through them; parents of published entries remain no-follow. + if target.joinpath(*parts).is_dir(): + continue + _ensure_directory(target, parts, created) + except BaseException as exc: + failures = [] + for source, destination, backup, existed in reversed(journal): + try: + backed_up = os.path.lexists(backup) + if backed_up or not existed: + # Move new payloads back into the caller's scratch tree. This + # also avoids deleting read-only Windows files during rollback. + if not os.path.lexists(source) and os.path.lexists(destination): + os.replace(destination, source) + if backed_up: + os.replace(backup, destination) + except OSError as rollback_error: + failures.append(f"{destination}: {rollback_error}") + for directory in reversed(created): + try: + directory.rmdir() + except FileNotFoundError: + continue + except OSError as rollback_error: + # A concurrent writer's new data is never ours to remove. + if rollback_error.errno not in (errno.ENOTEMPTY, errno.EEXIST): + failures.append(f"{directory}: {rollback_error}") + if not failures: + try: + _remove_backup(backup_root) + except OSError as cleanup_error: + failures.append(f"backup cleanup: {cleanup_error}") + if failures: + message = ( + f"Distribution rollback could not finish; recovery files retained at {backup_root}: " + + "; ".join(failures) + ) + if isinstance(exc, (KeyboardInterrupt, SystemExit)): + exc.add_note(message) + raise + raise OSError(message) from exc + raise + else: + try: + _remove_backup(backup_root) + except OSError: + # The new payload is committed; rollback is no longer possible once + # cleanup has removed some originals. Keep and report any leftovers. + logger.warning("Distribution committed; could not remove backups at %s", backup_root, exc_info=True) diff --git a/tests/hermes_cli/test_profile_main_namespace.py b/tests/hermes_cli/test_profile_main_namespace.py index beceb5e12816..6ebdeed92df3 100644 --- a/tests/hermes_cli/test_profile_main_namespace.py +++ b/tests/hermes_cli/test_profile_main_namespace.py @@ -243,6 +243,11 @@ def confirm_and_change_source(prompt): def _assert_directory_modes(source, legacy, monkeypatch, finish): + manifest = distributions.read_manifest(source) + manifest.distribution_owned = ["SOUL.md", "skills"] + write_manifest(source, manifest) + manifest_mode = 0o600 if finish == "install" else 0o640 + (legacy / distributions.MANIFEST_FILENAME).chmod(manifest_mode) (source / "skills" / "empty").mkdir() (source / "skills" / "readonly").mkdir() (source / "skills" / "readonly" / "guide.md").write_text("Readable in an immutable directory") @@ -266,6 +271,7 @@ def record_staged_modes(*args, **kwargs): assert stages == [expected_modes] assert {relative: stat.S_IMODE((legacy / relative).stat().st_mode) for relative in expected_modes} == expected_modes + assert stat.S_IMODE((legacy / distributions.MANIFEST_FILENAME).stat().st_mode) == manifest_mode assert not list((legacy / "skills" / "empty").iterdir()) assert not installed.staged_dir.exists() @@ -407,8 +413,117 @@ def tracked_native_read(*args, **kwargs): return observed +def _profile_tree_contents(root): + contents = {} + for entry in root.rglob("*"): + mode = entry.lstat().st_mode + if entry.is_symlink(): + value = entry.readlink() + elif entry.is_file(): + value = entry.read_bytes() + else: + value = None + contents[entry.relative_to(root)] = (mode, value) + return contents + + +def _assert_publication_transaction(source, target, monkeypatch, finish, change): + (target / "later.md").write_text("Previously installed later entry") + (target / "skills" / "empty").mkdir() + (target / ".env").write_text("USER_SECRET=preserved\n") + (source / "SOUL.md").write_text("New first entry") + (source / "later.md").write_text("New later entry") + (source / "skills" / "guide.md").write_text("New directory payload") + (source / "skills" / "new-empty").mkdir() + (source / "new" / "parents").mkdir(parents=True) + (source / "new" / "parents" / "new.md").write_text("New nested entry") + manifest_name = distributions.MANIFEST_FILENAME + new_file = "new/parents/new.md" + ordered = { + "transaction_late_second": ["SOUL.md", "later.md", "skills", new_file, manifest_name], + "transaction_late_third": ["SOUL.md", "skills", "later.md", new_file, manifest_name], + "transaction_commit_first": ["SOUL.md", new_file, "skills", "later.md", manifest_name], + "transaction_commit_second": [new_file, "skills", "SOUL.md", "later.md", manifest_name], + "transaction_commit_manifest": [manifest_name, "SOUL.md", new_file, "skills", "later.md"], + "transaction_commit_rollback_failure": ["SOUL.md", "skills", "later.md", new_file, manifest_name], + }[change] + write_manifest(source, DistributionManifest( + name="main", source=str(source), version="2.0.0", distribution_owned=ordered, + )) + before = _profile_tree_contents(target) + parent_entries = set(target.parent.iterdir()) + identity = target.stat().st_dev, target.stat().st_ino + stages = [] + real_plan = distributions.plan_install + + def capture_plan(*args, **kwargs): + plan = real_plan(*args, **kwargs) + stages.append(plan.staged_dir) + if change.startswith("transaction_late_"): + (plan.staged_dir / "later.md").write_text("Changed after approval") + return plan + + monkeypatch.setattr(distributions, "plan_install", capture_plan) + applied, failed, rollback_failed = [], [], [] + backups = {} + if change.startswith("transaction_commit_"): + fail_after = 1 if change == "transaction_commit_first" else 2 + real_replace = os.replace + destinations = {target.joinpath(*Path(relative).parts) for relative in ordered} + + def fail_next_publication(src, dst, *args, **kwargs): + origin = Path(src) + destination = Path(dst) + publishes_owned_entry = destination in destinations + if ( + change == "transaction_commit_rollback_failure" and failed and not rollback_failed + and destination == target / "skills" and origin == backups.get(destination) + ): + rollback_failed.append(origin) + raise OSError("injected one-time restore failure") + if publishes_owned_entry and len(applied) == fail_after and not failed: + failed.append(destination) + raise OSError("injected one-time publication failure") + result = real_replace(src, dst, *args, **kwargs) + if origin in destinations and not publishes_owned_entry and not failed: + backups[origin] = destination + if publishes_owned_entry: + applied.append(destination) + return result + + monkeypatch.setattr(os, "replace", fail_next_publication) + + with pytest.raises(DistributionError) as error: + if finish == "install": + install_distribution(str(source), name="main", force=True) + else: + update_distribution("main") + if change.startswith("transaction_commit_"): + assert len(failed) == 1 + assert len(applied) >= fail_after + assert (target.stat().st_dev, target.stat().st_ino) == identity + if change == "transaction_commit_rollback_failure": + assert rollback_failed == [backups[target / "skills"]] + retained = rollback_failed[0] + backup_root = retained.parent + assert retained.name == "skills" and retained.is_dir() + assert str(backup_root) in str(error.value) + assert set(target.parent.iterdir()) == parent_entries | {backup_root} + recovered = _profile_tree_contents(target) + recovered[Path("skills")] = (retained.lstat().st_mode, None) + recovered.update({Path("skills") / path: value for path, value in _profile_tree_contents(retained).items()}) + assert recovered == before + assert not (backup_root / "SOUL.md").exists() + assert not (backup_root / "later.md").exists() + assert stages and all(not staged.exists() for staged in stages) + return + assert _profile_tree_contents(target) == before + assert set(target.parent.iterdir()) == parent_entries + assert stages and all(not staged.exists() for staged in stages) + + @pytest.mark.parametrize("finish,change", [("rename", None), ("delete", None), ("retry_delete", None), - ("install", "confirm_local"), ("install", "confirm_git"), + ("install", "confirm_local"), ("install", "confirm_git"), ("install", "bootstrap_link"), ] + [ (operation, change) for operation in ("install", "update") @@ -417,6 +532,9 @@ def tracked_native_read(*args, **kwargs): "source_file", "source_file_link", "source_dir_link", "publication_rename", "publication_delete", "staged_file_link", "staged_dir_link", "staged_file_replace", "staged_file_write", + "transaction_late_second", "transaction_late_third", + "transaction_commit_first", "transaction_commit_second", "transaction_commit_manifest", + "transaction_commit_rollback_failure", ) ] + [ pytest.param(operation, "directory_modes", marks=marker, id=f"{operation}-directory_modes-{host}") @@ -459,12 +577,31 @@ def test_legacy_main_profile_remains_manageable(profile_home, tmp_path, monkeypa assert (legacy / "SOUL.md").read_text() == (source / "SOUL.md").read_text() assert (legacy / "config.yaml").read_text() == config + if change == "bootstrap_link": + private = tmp_path / "private-sessions" + private.mkdir() + (private / "session.json").write_text('{"private": "preserved"}') + linked = legacy / "sessions" + linked.symlink_to(private, target_is_directory=True) + link_identity = linked.lstat().st_ino, linked.readlink() + private_contents = _profile_tree_contents(private) + (source / "SOUL.md").write_text("Installed while personal sessions stay linked") + installed = install_distribution(str(source), name="main", force=True) + assert installed.target_dir == legacy + assert (legacy / "SOUL.md").read_bytes() == (source / "SOUL.md").read_bytes() + assert linked.is_symlink() and (linked.lstat().st_ino, linked.readlink()) == link_identity + assert _profile_tree_contents(private) == private_contents + return + if change in {"confirm_local", "confirm_git"}: _assert_confirmation_snapshot(source, legacy, tmp_path, monkeypatch, change) return if change == "directory_modes": _assert_directory_modes(source, legacy, monkeypatch, finish) return + if change is not None and change.startswith("transaction_"): + _assert_publication_transaction(source, legacy, monkeypatch, finish, change) + return if change is not None: target_name = "copy" if change == "replacement" else "main" diff --git a/website/docs/user-guide/profile-distributions.md b/website/docs/user-guide/profile-distributions.md index 3e9f9645f056..d42245a9a77c 100644 --- a/website/docs/user-guide/profile-distributions.md +++ b/website/docs/user-guide/profile-distributions.md @@ -622,6 +622,10 @@ Interactive installation applies the staged copy shown at confirmation. Later ed to the source or a moving Git branch do not change that approved installation. On POSIX systems, file and directory permission bits are preserved when copying. +The installer verifies the complete payload before changing profile files. It keeps +backups during publication and rolls back changes if publication fails. If recovery +cannot finish, the error identifies the retained backup directory. + --- ## Export and import a profile file From 19c57adecd5fe8cba0733b6a004d0dd79f5dfa3a Mon Sep 17 00:00:00 2001 From: guicybercode Date: Sun, 13 Sep 2026 06:39:05 -0300 Subject: [PATCH 8/8] fix(profiles): bind publication to destination directory handles --- .../profile_distribution_destination.py | 122 ++++++++ ...rofile_distribution_destination_windows.py | 192 ++++++++++++ .../profile_distribution_source_windows.py | 21 +- .../profile_distribution_transaction.py | 279 +++++++++++------- .../hermes_cli/test_profile_main_namespace.py | 238 ++++++++++++--- .../docs/user-guide/profile-distributions.md | 2 + 6 files changed, 692 insertions(+), 162 deletions(-) create mode 100644 hermes_cli/profile_distribution_destination.py create mode 100644 hermes_cli/profile_distribution_destination_windows.py diff --git a/hermes_cli/profile_distribution_destination.py b/hermes_cli/profile_distribution_destination.py new file mode 100644 index 000000000000..fb074674e4f2 --- /dev/null +++ b/hermes_cli/profile_distribution_destination.py @@ -0,0 +1,122 @@ +"""Pin destination directories so publication never re-resolves their parents.""" + +from __future__ import annotations + +import os +from pathlib import Path +import stat + + +def _component(name: str) -> None: + if not name or name in (".", "..") or "/" in name or "\0" in name: + raise OSError("Distribution destination requires one path component") + + +class _PosixDirectory: + def __init__(self, path: Path, fd: int, parent=None, name: str = ""): + self.path = path + self.fd = fd + info = os.fstat(fd) + self.identity = info.st_dev, info.st_ino + self._parent = parent + self._name = name + self._children = {} + self._closed = False + self._owner = None + + def stat(self, name: str): + _component(name) + return os.stat(name, dir_fd=self.fd, follow_symlinks=False) + + def child(self, name: str): + _component(name) + cached = self._children.get(name) + if cached is not None and not cached._closed: + return cached + before = self.stat(name) + if not stat.S_ISDIR(before.st_mode): + raise OSError(f"Distribution destination parent is not a plain directory: {self.path / name}") + fd = os.open(name, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=self.fd) + try: + child = _PosixDirectory(self.path / name, fd, self, name) + if child.identity != (before.st_dev, before.st_ino): + raise OSError(f"Distribution destination parent changed: {child.path}") + except BaseException: + os.close(fd) + raise + self._children[name] = child + return child + + def verify(self) -> None: + if self._parent is None: + current = os.lstat(self.path) + else: + self._parent.verify() + current = self._parent.stat(self._name) + held = os.fstat(self.fd) + if ( + self.identity != (held.st_dev, held.st_ino) + or self.identity != (current.st_dev, current.st_ino) + or not stat.S_ISDIR(current.st_mode) + ): + raise OSError(f"Distribution destination parent changed: {self.path}") + + def mkdir(self, name: str, mode: int = 0o777) -> None: + _component(name) + os.mkdir(name, mode, dir_fd=self.fd) + + def replace(self, name: str, destination, destination_name: str) -> None: + _component(name) + _component(destination_name) + os.replace(name, destination_name, src_dir_fd=self.fd, dst_dir_fd=destination.fd) + + def rmdir(self, name: str) -> None: + _component(name) + os.rmdir(name, dir_fd=self.fd) + + def remove_tree(self, name: str) -> None: + info = self.stat(name) + if not stat.S_ISDIR(info.st_mode): + os.unlink(name, dir_fd=self.fd) + return + child = self.child(name) + # Only private scratch/backup trees use this removal path. + os.fchmod(child.fd, stat.S_IMODE(info.st_mode) | stat.S_IRWXU) + try: + for entry in os.listdir(child.fd): + child.remove_tree(entry) + finally: + child.close() + self.rmdir(name) + + def close(self) -> None: + if self._closed: + return + if self._owner is not None: + owner, self._owner = self._owner, None + owner.close() + return + for child in reversed(tuple(self._children.values())): + child.close() + os.close(self.fd) + self._closed = True + + +def open_directory(path: Path): + if os.name == "nt": + from hermes_cli.profile_distribution_destination_windows import open_directory as open_native + + return open_native(path) + path = Path(os.path.abspath(path)) + root = _PosixDirectory(Path(path.anchor), os.open(path.anchor, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)) + try: + current = root + for name in path.parts[1:]: + current = current.child(name) + current.verify() + if current is not root: + current._owner = root + return current + except BaseException: + root.close() + raise diff --git a/hermes_cli/profile_distribution_destination_windows.py b/hermes_cli/profile_distribution_destination_windows.py new file mode 100644 index 000000000000..779a708ed3ec --- /dev/null +++ b/hermes_cli/profile_distribution_destination_windows.py @@ -0,0 +1,192 @@ +"""Anchor publication parents with native handles that deny rename and deletion.""" + +from __future__ import annotations + +import os +import stat +import sys +from contextlib import ExitStack, contextmanager +from pathlib import Path + +from hermes_cli.profile_distribution_source_windows import _Source, _checked_stat, _filesystem_path + + +@contextmanager +def _native_errors(path: Path): + import pywintypes + + try: + yield + except pywintypes.error as exc: + raise OSError(exc.winerror, exc.strerror, str(path)) from exc + + +@contextmanager +def _open_directory_handle(path: Path): + import win32file + + with _native_errors(path): + expected = _checked_stat(path) + if not stat.S_ISDIR(expected.st_mode): + raise OSError(f"Distribution destination parent is not a directory: {path}") + # Read access makes the no-delete sharing rule protect the directory. + # Write sharing permits child publication; source readers stay stricter. + handle = win32file.CreateFile( + str(path), win32file.GENERIC_READ, + win32file.FILE_SHARE_READ | win32file.FILE_SHARE_WRITE, None, + win32file.OPEN_EXISTING, + win32file.FILE_FLAG_OPEN_REPARSE_POINT | win32file.FILE_FLAG_BACKUP_SEMANTICS, None, + ) + try: + source = _Source(path, handle, expected, win32file) + yield source + source._verify() + finally: + win32file.CloseHandle(handle) + + +@contextmanager +def _directory_chain(path: Path): + with ExitStack() as parents: + source = parents.enter_context(_open_directory_handle(Path(path.anchor))) + for name in path.parts[1:]: + source._verify() + source = parents.enter_context(_open_directory_handle(source._path / name)) + yield source + + +class DirAnchor: + def __init__(self, source, manager): + self.path = source._path + self.identity = source._expected.st_dev, source._expected.st_ino + self._source = source + self._manager = manager + self._children: dict[str, DirAnchor] = {} + self._closed = False + + def _entry_path(self, name: str) -> Path: + if self._closed: + raise OSError("Distribution destination directory handle is closed") + if name.rstrip(" .") in ("", ".", "..") or any(char in name for char in "\\/:\0"): + raise OSError("Distribution destination entry must be one path component") + return self.path / name + + def child(self, name: str) -> DirAnchor: + path = self._entry_path(name) + key = os.path.normcase(name) + existing = self._children.get(key) + if existing is not None and not existing._closed: + return existing + # child() retains its parent. Never enumerate it: sibling publications may + # change directory contents while identity and ancestry remain protected. + with _native_errors(path): + self.verify() + manager = _open_directory_handle(path) + source = manager.__enter__() + if not source.is_dir: + manager.__exit__(None, None, None) + raise OSError(f"Distribution destination parent is not a directory: {path}") + anchor = DirAnchor(source, manager) + self._children[key] = anchor + return anchor + + def stat(self, name: str): + return self._entry_path(name).lstat() + + def mkdir(self, name: str, mode: int = 0o777) -> None: + self._entry_path(name).mkdir(mode=mode) + + def replace(self, name: str, destination_anchor: DirAnchor, destination_name: str) -> None: + # Only parents are pinned. The leaf itself must remain renameable both + # during publication and when the transaction restores its originals. + os.replace(self._entry_path(name), destination_anchor._entry_path(destination_name)) + + def rmdir(self, name: str) -> None: + self._entry_path(name).rmdir() + + def _clear_readonly(self, name: str) -> bool: + import win32file + + path = self._entry_path(name) + with _native_errors(path): + # Pin the leaf as well while changing attributes. A replacement link + # must never redirect this cleanup write outside the private backup. + handle = win32file.CreateFile( + str(path), win32file.GENERIC_READ, + win32file.FILE_SHARE_READ | win32file.FILE_SHARE_WRITE, None, + win32file.OPEN_EXISTING, + win32file.FILE_FLAG_OPEN_REPARSE_POINT | win32file.FILE_FLAG_BACKUP_SEMANTICS, None, + ) + try: + attributes = win32file.GetFileInformationByHandle(handle)[0] + if ( + win32file.GetFileType(handle) != win32file.FILE_TYPE_DISK + or attributes & stat.FILE_ATTRIBUTE_REPARSE_POINT + or not attributes & stat.FILE_ATTRIBUTE_READONLY + ): + return False + win32file.SetFileAttributes( + str(path), (attributes & ~stat.FILE_ATTRIBUTE_READONLY) or stat.FILE_ATTRIBUTE_NORMAL, + ) + return True + finally: + win32file.CloseHandle(handle) + + def _remove_leaf(self, name: str, is_dir: bool) -> None: + path = self._entry_path(name) + remove = path.rmdir if is_dir else path.unlink + try: + remove() + except PermissionError: + if not self._clear_readonly(name): + raise + remove() + + def remove_tree(self, name: str) -> None: + try: + info = self.stat(name) + except FileNotFoundError: + return + is_dir = stat.S_ISDIR(info.st_mode) + if is_dir and not info.st_file_attributes & stat.FILE_ATTRIBUTE_REPARSE_POINT: + child = self.child(name) + try: + with os.scandir(child.path) as entries: + names = [entry.name for entry in entries] + for entry_name in names: + child.remove_tree(entry_name) + finally: + child.close() + # A junction/symlink is removed as a leaf; its target is never traversed. + self._remove_leaf(name, is_dir) + + def verify(self) -> None: + if self._closed: + raise OSError("Distribution destination directory handle is closed") + with _native_errors(self.path): + self._source._verify() + + def close(self) -> None: + if self._closed: + return + self._closed = True + with _native_errors(self.path), ExitStack() as pending: + pending.callback(self._manager.__exit__, None, None, None) + for child in self._children.values(): + pending.callback(child.close) + + +def open_directory(path: Path) -> DirAnchor: + """Keep every ancestor open without delete sharing until the anchor closes. + + Reuse the source reader's reparse, identity, UNC and short-name handling. + Directory content checks remain disabled because no names() call is made. + """ + if sys.platform != "win32": + raise OSError("Native Windows distribution destinations require Windows") + manager = _directory_chain(_filesystem_path(path)) + source = manager.__enter__() + if not source.is_dir: + manager.__exit__(None, None, None) + raise OSError(f"Distribution destination parent is not a directory: {path}") + return DirAnchor(source, manager) diff --git a/hermes_cli/profile_distribution_source_windows.py b/hermes_cli/profile_distribution_source_windows.py index 96f37078057c..c92b16f55f92 100644 --- a/hermes_cli/profile_distribution_source_windows.py +++ b/hermes_cli/profile_distribution_source_windows.py @@ -157,14 +157,7 @@ def _open_one(path: Path, win32file, expected=None): win32file.CloseHandle(handle) -@contextmanager -def open_source(path: Path): - """Open without following any reparse component, retaining all ancestor handles.""" - if sys.platform != "win32": - raise OSError("Native Windows distribution sources require Windows") - import pywintypes - import win32file - +def _filesystem_path(path: Path) -> Path: raw = str(path) if "\0" in raw or raw.startswith("\\\\.\\"): raise OSError("Distribution sources cannot use the Windows device namespace") @@ -177,6 +170,18 @@ def open_source(path: Path): path = Path(os.path.abspath(raw)) if not path.anchor or any(":" in part for part in path.parts[1:]): raise OSError("Distribution source must use a filesystem path without alternate streams") + return path + + +@contextmanager +def open_source(path: Path): + """Open without following any reparse component, retaining all ancestor handles.""" + if sys.platform != "win32": + raise OSError("Native Windows distribution sources require Windows") + import pywintypes + import win32file + + path = _filesystem_path(path) try: with ExitStack() as stack: source = stack.enter_context(_open_one(Path(path.anchor), win32file)) diff --git a/hermes_cli/profile_distribution_transaction.py b/hermes_cli/profile_distribution_transaction.py index 3ae66dd8de62..52ffecf93d71 100644 --- a/hermes_cli/profile_distribution_transaction.py +++ b/hermes_cli/profile_distribution_transaction.py @@ -1,20 +1,28 @@ -"""Publish a prepared distribution without replacing the profile root.""" +"""Publish a prepared distribution through retained destination directories.""" from __future__ import annotations -import errno +from collections.abc import Sequence +from contextlib import ExitStack +from dataclasses import dataclass import logging import os from pathlib import Path -import shutil +import secrets import stat -import tempfile -from collections.abc import Sequence logger = logging.getLogger(__name__) +@dataclass +class _CreatedDirectory: + parent: object + name: str + identity: tuple[int, int] | None = None + anchor: object | None = None + + def _checked_paths(paths: Sequence[tuple[str, ...]]) -> tuple[tuple[str, ...], ...]: result = tuple(tuple(parts) for parts in paths) for parts in result: @@ -27,125 +35,184 @@ def _checked_paths(paths: Sequence[tuple[str, ...]]) -> tuple[tuple[str, ...], . return result -def _is_reparse(info) -> bool: - return bool(getattr(info, "st_file_attributes", 0) & stat.FILE_ATTRIBUTE_REPARSE_POINT) +def _exists(parent, name: str) -> bool: + try: + parent.stat(name) + except FileNotFoundError: + return False + return True -def _ensure_directory(target: Path, parts: tuple[str, ...], created: list[Path]) -> None: - current = target - for part in (None, *parts): - if part is not None: - current = current / part - try: - info = current.lstat() - except FileNotFoundError: - current.mkdir() - created.append(current) - else: - if not stat.S_ISDIR(info.st_mode) or _is_reparse(info): - raise OSError(f"Distribution destination parent is not a plain directory: {current}") +def _descend(parent, parts): + for name in parts: + parent = parent.child(name) + return parent + + +def _create_directory(parent, name, created, mode=0o777): + parent.mkdir(name, mode=mode) + # Even stat/pin acquisition can fail after mkdir succeeds. Keep the location + # first; an unknown or replaced identity must be reported, never removed. + record = _CreatedDirectory(parent, name) + created.append(record) + info = parent.stat(name) + record.identity = info.st_dev, info.st_ino + child = parent.child(name) + record.anchor = child + if child.identity != record.identity: + raise OSError(f"Created distribution directory changed before opening: {parent.path / name}") + return child + + +def _ensure_child(parent, name, created): + parent.verify() + child = parent.child(name) if _exists(parent, name) else _create_directory(parent, name, created) + child.verify() + return child + + +def _ensure_directory(parent, parts, created): + for name in parts: + parent = _ensure_child(parent, name, created) + return parent -def _remove_backup(path: Path) -> None: - from hermes_cli.profiles import _rmtree_make_writable +def _replace(source, name, destination): + source.verify() + destination.verify() + source.replace(name, destination, name) + source.verify() + destination.verify() - shutil.rmtree(path, onerror=_rmtree_make_writable) + +def _remove_backup(parent, name, backup): + backup.close() + parent.remove_tree(name) + + +def _undo_created(record, failures): + path = record.parent.path / record.name + try: + if record.anchor is not None: + record.anchor.close() + current = record.parent.stat(record.name) + if ( + record.identity is None or record.identity != (current.st_dev, current.st_ino) + or not stat.S_ISDIR(current.st_mode) + or getattr(current, "st_file_attributes", 0) & stat.FILE_ATTRIBUTE_REPARSE_POINT + ): + failures.append(f"Created directory identity could not be verified; left {path} untouched") + return + record.parent.rmdir(record.name) + except FileNotFoundError: + return + except OSError as cleanup_error: + failures.append(f"Created directory retained at {path}: {cleanup_error}") def commit_owned_payload( target: Path, prepared_root: Path, relative_paths: Sequence[tuple[str, ...]], *, empty_dirs: Sequence[tuple[str, ...]] = (), ) -> None: - """Commit disjoint, fully validated entries under the profile lifecycle lock. + """Commit under the lifecycle lock, rolling back our changes on an exception. - Renames preserve originals for rollback on an exception, including cancellation. - This does not provide isolation from external readers or recovery after power loss. + Rollback uses the same directory objects even if another process renames them; + it never undoes that process's rename. External-reader isolation and recovery + after power loss are outside this in-process transaction. """ + from hermes_cli.profile_distribution_destination import open_directory + paths = _checked_paths(relative_paths) directories = _checked_paths(empty_dirs) ordered = sorted(tuple(os.path.normcase(part) for part in parts) for parts in paths) if any(right[:len(left)] == left for left, right in zip(ordered, ordered[1:])): raise OSError("Distribution publication paths must be disjoint") - device = target.parent.stat().st_dev - if prepared_root.stat().st_dev != device or ( - os.path.lexists(target) and target.lstat().st_dev != device - ): - raise OSError("Distribution publication requires preparation on the profile filesystem") - for parts in paths: - info = prepared_root.joinpath(*parts).lstat() - if info.st_dev != device or _is_reparse(info) or not ( - stat.S_ISREG(info.st_mode) or stat.S_ISDIR(info.st_mode) - ): - raise OSError("Prepared distribution entries must be local regular files or directories") - # Keep backups outside the caller's temporary tree: a failed rollback must - # never let its cleanup delete the only recoverable copy of an original. - backup_root = Path(tempfile.mkdtemp(prefix=".hermes-dist-rollback-", dir=target.parent)) - created: list[Path] = [] - journal: list[tuple[Path, Path, Path, bool]] = [] - try: - _ensure_directory(target, (), created) + with ExitStack() as handles: + parent = open_directory(target.parent) + handles.callback(parent.close) + prepared = open_directory(prepared_root) + handles.callback(prepared.close) + if prepared.identity[0] != parent.identity[0]: + raise OSError("Distribution publication requires preparation on the profile filesystem") + sources = [] for parts in paths: - _ensure_directory(target, parts[:-1], created) - source = prepared_root.joinpath(*parts) - destination = target.joinpath(*parts) - backup = backup_root.joinpath(*parts) - existed = os.path.lexists(destination) - # Register before either rename. Presence of source/backup also covers - # an interrupt delivered immediately after a successful native rename. - journal.append((source, destination, backup, existed)) - if existed: - backup.parent.mkdir(parents=True, exist_ok=True) - os.replace(destination, backup) - os.replace(source, destination) - for parts in directories: - # Existing bootstrap dirs can be user-owned links. Reuse them without - # writing through them; parents of published entries remain no-follow. - if target.joinpath(*parts).is_dir(): - continue - _ensure_directory(target, parts, created) - except BaseException as exc: - failures = [] - for source, destination, backup, existed in reversed(journal): - try: - backed_up = os.path.lexists(backup) - if backed_up or not existed: - # Move new payloads back into the caller's scratch tree. This - # also avoids deleting read-only Windows files during rollback. - if not os.path.lexists(source) and os.path.lexists(destination): - os.replace(destination, source) - if backed_up: - os.replace(backup, destination) - except OSError as rollback_error: - failures.append(f"{destination}: {rollback_error}") - for directory in reversed(created): - try: - directory.rmdir() - except FileNotFoundError: - continue - except OSError as rollback_error: - # A concurrent writer's new data is never ours to remove. - if rollback_error.errno not in (errno.ENOTEMPTY, errno.EEXIST): - failures.append(f"{directory}: {rollback_error}") - if not failures: - try: - _remove_backup(backup_root) - except OSError as cleanup_error: - failures.append(f"backup cleanup: {cleanup_error}") - if failures: - message = ( - f"Distribution rollback could not finish; recovery files retained at {backup_root}: " - + "; ".join(failures) - ) - if isinstance(exc, (KeyboardInterrupt, SystemExit)): - exc.add_note(message) - raise - raise OSError(message) from exc - raise - else: + source = _descend(prepared, parts[:-1]) + info = source.stat(parts[-1]) + if info.st_dev != parent.identity[0] or ( + getattr(info, "st_file_attributes", 0) & stat.FILE_ATTRIBUTE_REPARSE_POINT + ) or not (stat.S_ISREG(info.st_mode) or stat.S_ISDIR(info.st_mode)): + raise OSError("Prepared distribution entries must be local regular files or directories") + sources.append(source) + + # A separate private sibling survives the caller's scratch cleanup if a + # restoration fails. Create it through the pinned parent too. + backup_name = ".hermes-dist-rollback-" + secrets.token_hex(16) + backup_path = parent.path / backup_name + backup = None + backup_created = [] + created = [] + journal = [] try: - _remove_backup(backup_root) - except OSError: - # The new payload is committed; rollback is no longer possible once - # cleanup has removed some originals. Keep and report any leftovers. - logger.warning("Distribution committed; could not remove backups at %s", backup_root, exc_info=True) + parent.verify() + backup = _create_directory(parent, backup_name, backup_created, mode=0o700) + backup.verify() + destination_root = _ensure_child(parent, target.name, created) + if destination_root.identity[0] != prepared.identity[0]: + raise OSError("Distribution publication requires the profile filesystem") + for parts, source in zip(paths, sources): + destination = _ensure_directory(destination_root, parts[:-1], created) + saved = _ensure_directory(backup, parts[:-1], []) + name = parts[-1] + existed = _exists(destination, name) + # Register before either rename, including exceptions raised by + # the post-rename identity check when a parent was moved. + journal.append((source, destination, saved, name, existed)) + if existed: + _replace(destination, name, saved) + _replace(source, name, destination) + for parts in directories: + # Reuse existing user-owned bootstrap links without writing through them. + if target.joinpath(*parts).is_dir(): + continue + _ensure_directory(destination_root, parts, created) + destination_root.verify() + except BaseException as exc: + failures = [] + for source, destination, saved, name, existed in reversed(journal): + try: + backed_up = _exists(saved, name) + if backed_up or not existed: + # Deliberately skip logical-path verification here: these + # anchors still refer to the directories we actually changed. + if not _exists(source, name) and _exists(destination, name): + destination.replace(name, source, name) + if backed_up: + saved.replace(name, destination, name) + except OSError as rollback_error: + failures.append(f"{destination.path / name}: {rollback_error}") + for record in reversed(created): + _undo_created(record, failures) + if backup is None: + for record in reversed(backup_created): + _undo_created(record, failures) + elif not failures: + try: + _remove_backup(parent, backup_name, backup) + except OSError as cleanup_error: + failures.append(f"backup cleanup: {cleanup_error}") + if failures: + message = ( + f"Distribution rollback could not finish; recovery files retained at {backup_path}: " + + "; ".join(failures) + ) + if isinstance(exc, (KeyboardInterrupt, SystemExit)): + exc.add_note(message) + raise + raise OSError(message) from exc + raise + else: + try: + _remove_backup(parent, backup_name, backup) + except OSError: + logger.warning("Distribution committed; could not remove backups at %s", backup_path, exc_info=True) diff --git a/tests/hermes_cli/test_profile_main_namespace.py b/tests/hermes_cli/test_profile_main_namespace.py index 6ebdeed92df3..68e94f2c8f11 100644 --- a/tests/hermes_cli/test_profile_main_namespace.py +++ b/tests/hermes_cli/test_profile_main_namespace.py @@ -427,6 +427,131 @@ def _profile_tree_contents(root): return contents +def _replace_path(path, directory_fd, profiles_root): + path = Path(path) + if directory_fd is None or path.is_absolute(): + return path + expected = os.fstat(directory_fd) + for parent in (profiles_root, *profiles_root.rglob("*")): + if parent.is_symlink() or not parent.is_dir(): + continue + info = parent.stat() + if (info.st_dev, info.st_ino) == (expected.st_dev, expected.st_ino): + return parent / path + pytest.fail("rename used a descriptor outside the real profile transaction directories") + + +def _assert_destination_parent_binding(source, target, tmp_path, monkeypatch, finish, change): + nested = target / "nested" + nested.mkdir() + (nested / "previous.md").write_text("Original parent content") + (source / "nested").mkdir() + (source / "nested" / "new.md").write_text("New approved nested content") + (source / "SOUL.md").write_text("New approved first content") + ordered = ["nested/new.md", "SOUL.md"] + if change == "destination_parent_late": + ordered.reverse() + write_manifest(source, DistributionManifest( + name="main", source=str(source), version="2.0.0", distribution_owned=ordered, + )) + external = tmp_path / "private-parent" + external.mkdir() + (external / "private.md").write_text("Private content must remain untouched") + external_before = _profile_tree_contents(external) + (target / "SOUL.md").chmod(0o444) + target_before = _profile_tree_contents(target) + nested_before = _profile_tree_contents(nested) + parent_entries = set(target.parent.iterdir()) + parent_identity = nested.stat().st_dev, nested.stat().st_ino + moved = tmp_path / "moved-parent" + attempted, swapped = [], [] + real_replace = os.replace + + def swap_parent_before_rename(src, dst, *args, **kwargs): + descriptor = kwargs.get("dst_dir_fd") + if descriptor is None: + is_nested_write = Path(dst) == nested / "new.md" + else: + info = os.fstat(descriptor) + is_nested_write = Path(dst) == Path("new.md") and (info.st_dev, info.st_ino) == parent_identity + if is_nested_write and not attempted: + attempted.append(True) + try: + nested.rename(moved) + except PermissionError: + assert not moved.exists() + else: + if os.name == "nt": + subprocess.run( + ["cmd", "/c", "mklink", "/J", str(nested), str(external)], + check=True, capture_output=True, + ) + else: + nested.symlink_to(external, target_is_directory=True) + swapped.append((nested.lstat().st_mode, nested.readlink() if nested.is_symlink() else None)) + return real_replace(src, dst, *args, **kwargs) + + monkeypatch.setattr(os, "replace", swap_parent_before_rename) + error = None + try: + if finish == "install": + install_distribution(str(source), name="main", force=True) + else: + update_distribution("main") + except DistributionError as exc: + error = exc + assert attempted + assert _profile_tree_contents(external) == external_before + if swapped: + assert error is not None + expected = {path: value for path, value in target_before.items() if path.parts[0] != "nested"} + expected[Path("nested")] = swapped[0] + assert _profile_tree_contents(target) == expected + assert _profile_tree_contents(moved) == nested_before + assert (moved.stat().st_dev, moved.stat().st_ino) == parent_identity + else: + assert error is None + assert (nested / "new.md").read_bytes() == (source / "nested" / "new.md").read_bytes() + assert (target / "SOUL.md").read_bytes() == (source / "SOUL.md").read_bytes() + assert set(target.parent.iterdir()) == parent_entries + + +def _fail_created_directory_open(target, monkeypatch, change): + from hermes_cli.profile_distribution_destination import open_directory + + anchor = open_directory(target.parent) + try: + anchor_type = type(anchor) + finally: + anchor.close() + real_mkdir, real_child = anchor_type.mkdir, anchor_type.child + pending, failed = {}, [] + + def record_creation(parent, name, *args, **kwargs): + result = real_mkdir(parent, name, *args, **kwargs) + selected = { + "transaction_open_destination": parent.path == target and name == "new", + "transaction_open_backup": parent.path == target.parent and name.startswith(".hermes-dist-rollback-"), + }[change] + if selected: + info = parent.stat(name) + pending[(id(parent), name)] = info.st_dev, info.st_ino + return result + + def fail_open_once(parent, name): + identity = pending.get((id(parent), name)) + if identity is not None and not failed: + current = parent.stat(name) + assert (current.st_dev, current.st_ino) == identity + failed.append(parent.path / name) + raise OSError("injected failure opening the directory just created") + return real_child(parent, name) + + monkeypatch.setattr(anchor_type, "mkdir", record_creation) + monkeypatch.setattr(anchor_type, "child", fail_open_once) + return failed + + def _assert_publication_transaction(source, target, monkeypatch, finish, change): (target / "later.md").write_text("Previously installed later entry") (target / "skills" / "empty").mkdir() @@ -446,6 +571,8 @@ def _assert_publication_transaction(source, target, monkeypatch, finish, change) "transaction_commit_second": [new_file, "skills", "SOUL.md", "later.md", manifest_name], "transaction_commit_manifest": [manifest_name, "SOUL.md", new_file, "skills", "later.md"], "transaction_commit_rollback_failure": ["SOUL.md", "skills", "later.md", new_file, manifest_name], + "transaction_open_destination": ["SOUL.md", new_file, "skills", "later.md", manifest_name], + "transaction_open_backup": ["SOUL.md", new_file, "skills", "later.md", manifest_name], }[change] write_manifest(source, DistributionManifest( name="main", source=str(source), version="2.0.0", distribution_owned=ordered, @@ -472,8 +599,8 @@ def capture_plan(*args, **kwargs): destinations = {target.joinpath(*Path(relative).parts) for relative in ordered} def fail_next_publication(src, dst, *args, **kwargs): - origin = Path(src) - destination = Path(dst) + origin = _replace_path(src, kwargs.get("src_dir_fd"), target.parent) + destination = _replace_path(dst, kwargs.get("dst_dir_fd"), target.parent) publishes_owned_entry = destination in destinations if ( change == "transaction_commit_rollback_failure" and failed and not rollback_failed @@ -493,6 +620,9 @@ def fail_next_publication(src, dst, *args, **kwargs): monkeypatch.setattr(os, "replace", fail_next_publication) + failed_open = [] + if change.startswith("transaction_open_"): + failed_open = _fail_created_directory_open(target, monkeypatch, change) with pytest.raises(DistributionError) as error: if finish == "install": install_distribution(str(source), name="main", force=True) @@ -501,6 +631,8 @@ def fail_next_publication(src, dst, *args, **kwargs): if change.startswith("transaction_commit_"): assert len(failed) == 1 assert len(applied) >= fail_after + if change.startswith("transaction_open_"): + assert len(failed_open) == 1 assert (target.stat().st_dev, target.stat().st_ino) == identity if change == "transaction_commit_rollback_failure": assert rollback_failed == [backups[target / "skills"]] @@ -522,8 +654,59 @@ def fail_next_publication(src, dst, *args, **kwargs): assert stages and all(not staged.exists() for staged in stages) +def _assert_staged_publication(target, tmp_path, monkeypatch, publish, change): + planned, release = Event(), Event() + plans = [] + private_reads = [] + revalidate = distributions._revalidate_plan + + def pause_after_revalidation(plan): + revalidate(plan) + plans.append(plan) + planned.set() + assert release.wait(10), "test did not release publication" + + monkeypatch.setattr(distributions, "_revalidate_plan", pause_after_revalidation) + with ThreadPoolExecutor(max_workers=1) as pool: + pending = pool.submit(publish) + try: + assert planned.wait(10), "publication did not reach revalidation" + staged = plans[0].staged_dir + root_inode = staged.stat().st_ino + external = tmp_path / "private" + if change == "staged_dir_link": + external.mkdir() + (external / "guide.md").write_text("SECRET outside distribution") + shutil.rmtree(staged / "skills") + (staged / "skills").symlink_to(external, target_is_directory=True) + elif change == "staged_file_link": + external.write_text("SECRET outside distribution") + (staged / "SOUL.md").unlink() + (staged / "SOUL.md").symlink_to(external) + elif change == "staged_file_replace": + external.write_text("Unapproved replacement") + external.replace(staged / "SOUL.md") + else: + (staged / "SOUL.md").write_text("Unapproved overwrite") + assert staged.stat().st_ino == root_inode + if change in {"staged_file_link", "staged_dir_link"}: + private_file = external / "guide.md" if change == "staged_dir_link" else external + private_reads = _observe_private_reads(private_file, monkeypatch) + finally: + release.set() + try: + pending.result(timeout=10) + except DistributionError: + pass + assert not private_reads + assert (target / "SOUL.md").read_text() == "Updated distribution content" + assert (target / "skills" / "guide.md").read_text() == "Planned skill content" + assert not plans[0].staged_dir.exists() + + @pytest.mark.parametrize("finish,change", [("rename", None), ("delete", None), ("retry_delete", None), ("install", "confirm_local"), ("install", "confirm_git"), ("install", "bootstrap_link"), + ("install", "transaction_open_destination"), ("install", "transaction_open_backup"), ] + [ (operation, change) for operation in ("install", "update") @@ -535,6 +718,7 @@ def fail_next_publication(src, dst, *args, **kwargs): "transaction_late_second", "transaction_late_third", "transaction_commit_first", "transaction_commit_second", "transaction_commit_manifest", "transaction_commit_rollback_failure", + "destination_parent_first", "destination_parent_late", ) ] + [ pytest.param(operation, "directory_modes", marks=marker, id=f"{operation}-directory_modes-{host}") @@ -602,6 +786,9 @@ def test_legacy_main_profile_remains_manageable(profile_home, tmp_path, monkeypa if change is not None and change.startswith("transaction_"): _assert_publication_transaction(source, legacy, monkeypatch, finish, change) return + if change is not None and change.startswith("destination_parent_"): + _assert_destination_parent_binding(source, legacy, tmp_path, monkeypatch, finish, change) + return if change is not None: target_name = "copy" if change == "replacement" else "main" @@ -615,52 +802,7 @@ def test_legacy_main_profile_remains_manageable(profile_home, tmp_path, monkeypa } if change.startswith("staged_"): - plans = [] - private_reads = [] - revalidate = distributions._revalidate_plan - - def pause_after_revalidation(plan): - revalidate(plan) - plans.append(plan) - planned.set() - assert release.wait(10), "test did not release publication" - - monkeypatch.setattr(distributions, "_revalidate_plan", pause_after_revalidation) - with ThreadPoolExecutor(max_workers=1) as pool: - pending = pool.submit(publish[finish]) - try: - assert planned.wait(10), "publication did not reach revalidation" - staged = plans[0].staged_dir - root_inode = staged.stat().st_ino - external = tmp_path / "private" - if change == "staged_dir_link": - external.mkdir() - (external / "guide.md").write_text("SECRET outside distribution") - shutil.rmtree(staged / "skills") - (staged / "skills").symlink_to(external, target_is_directory=True) - elif change == "staged_file_link": - external.write_text("SECRET outside distribution") - (staged / "SOUL.md").unlink() - (staged / "SOUL.md").symlink_to(external) - elif change == "staged_file_replace": - external.write_text("Unapproved replacement") - external.replace(staged / "SOUL.md") - else: - (staged / "SOUL.md").write_text("Unapproved overwrite") - assert staged.stat().st_ino == root_inode - if change in {"staged_file_link", "staged_dir_link"}: - private_file = external / "guide.md" if change == "staged_dir_link" else external - private_reads = _observe_private_reads(private_file, monkeypatch) - finally: - release.set() - try: - pending.result(timeout=10) - except DistributionError: - pass - assert not private_reads - assert (target / "SOUL.md").read_text() == "Updated distribution content" - assert (target / "skills" / "guide.md").read_text() == "Planned skill content" - assert not plans[0].staged_dir.exists() + _assert_staged_publication(target, tmp_path, monkeypatch, publish[finish], change) return if change.startswith("publication_"): diff --git a/website/docs/user-guide/profile-distributions.md b/website/docs/user-guide/profile-distributions.md index d42245a9a77c..34050a30b2bf 100644 --- a/website/docs/user-guide/profile-distributions.md +++ b/website/docs/user-guide/profile-distributions.md @@ -625,6 +625,8 @@ On POSIX systems, file and directory permission bits are preserved when copying. The installer verifies the complete payload before changing profile files. It keeps backups during publication and rolls back changes if publication fails. If recovery cannot finish, the error identifies the retained backup directory. +Destination directory handles remain open during publication and rollback so a +concurrent link replacement cannot redirect writes through that link. ---