diff --git a/hermes_cli/profile_cmd.py b/hermes_cli/profile_cmd.py index 45b67323a9c4..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: @@ -616,4 +615,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 2734d2a82210..2aed9357eea0 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, contextmanager from dataclasses import dataclass, field from datetime import datetime, timezone from pathlib import Path, PurePosixPath @@ -20,6 +21,9 @@ 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 MANIFEST_FILENAME = "distribution.yaml" @@ -142,16 +146,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: @@ -243,45 +255,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); a local directory is used in place.""" +@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(): - staged = path_guess.resolve() - provenance = str(staged) - missing = ( - f"No {MANIFEST_FILENAME} in {path_guess}. " - "A local-directory source must contain a distribution.yaml at its root." - ) - else: - 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 + 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 _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}") +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( + "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() # Install @@ -294,55 +328,75 @@ 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 + 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(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, get_profile_dir 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." + 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(): + 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 + 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") + 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), + source_snapshot=snapshot, preserves_config=existing, has_cron=_has_cron_jobs(snapshot), ) - 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() - 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 _owned_entries(staged: Path, manifest: DistributionManifest): - """Yield ``(src, rel_parts)`` for every staged path the distribution owns.""" +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(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: @@ -351,76 +405,127 @@ 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 - - -def _copy_dist_payload(staged: Path, target: Path, manifest: DistributionManifest, preserve_config: bool) -> 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) + entry = snapshot + for part in rel_parts: + if entry.children is None or part not in entry.children: + break + entry = entry.children[part] else: - shutil.copy2(src, dest) + 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.") - # 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") - # Make sure the manifest on disk reflects resolved name + source - write_manifest(target, manifest) +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 _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, 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 _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 _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: + # 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 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 - 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." - ) + """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) + - # 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) +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 _PROFILE_DIRS, check_alias_collision, create_wrapper_script + + try: + 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." + ) + + _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 + except OSError as exc: + raise DistributionError(f"Could not install profile distribution: {exc}") from exc def _existing_profile(profile_name: str) -> Tuple[str, Path]: @@ -436,23 +541,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, preserve_config=plan.preserves_config) + return plan def describe_distribution(profile_name: str) -> Dict[str, Any]: 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.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..c92b16f55f92 --- /dev/null +++ b/hermes_cli/profile_distribution_source_windows.py @@ -0,0 +1,192 @@ +"""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:] + 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): + 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) + 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}") + # 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) + + +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") + 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") + 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)) + 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..4a4e84010a88 --- /dev/null +++ b/hermes_cli/profile_distribution_staging.py @@ -0,0 +1,136 @@ +"""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 _file_chunks(source, expected: SourceSnapshot | None = None): + if source.is_dir: + 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): + 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"", + *, 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: + # Populate writable scratch directories before restoring source modes. + target.mkdir(mode=0o700) + copy_source_tree(entry, target, expected=child_expected) + else: + 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 +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/hermes_cli/profile_distribution_transaction.py b/hermes_cli/profile_distribution_transaction.py new file mode 100644 index 000000000000..52ffecf93d71 --- /dev/null +++ b/hermes_cli/profile_distribution_transaction.py @@ -0,0 +1,218 @@ +"""Publish a prepared distribution through retained destination directories.""" + +from __future__ import annotations + +from collections.abc import Sequence +from contextlib import ExitStack +from dataclasses import dataclass +import logging +import os +from pathlib import Path +import secrets +import stat + + +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: + 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 _exists(parent, name: str) -> bool: + try: + parent.stat(name) + except FileNotFoundError: + return False + return True + + +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 _replace(source, name, destination): + source.verify() + destination.verify() + source.replace(name, destination, name) + source.verify() + destination.verify() + + +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 under the lifecycle lock, rolling back our changes on an exception. + + 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") + + 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: + 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: + 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/hermes_cli/profiles.py b/hermes_cli/profiles.py index 12c98d10486e..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__) @@ -220,6 +221,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) @@ -818,70 +828,72 @@ def create_profile( "(cloning explicitly copies skills from the source profile)." ) canon = _canon_valid(name) + _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 - # 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: @@ -1142,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(): @@ -1565,6 +1586,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). " @@ -1584,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 @@ -1653,39 +1678,41 @@ 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) - 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 new file mode 100644 index 000000000000..68e94f2c8f11 --- /dev/null +++ b/tests/hermes_cli/test_profile_main_namespace.py @@ -0,0 +1,953 @@ +"""New profile targets must not reuse the default session namespace.""" + +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 + +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 clear_named_profile_deleted, 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", "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): + 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" + 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" + 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") + write_manifest(source, DistributionManifest(name=name)) + + with pytest.raises(DistributionError, match="outside"): + distributions.plan_install(str(source), workdir) + 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" + 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) + target.mkdir() + (target / "config.yaml").write_text(config) + workdir = tmp_path / "staging" + with pytest.raises(DistributionError, match="symlink"): + distributions.plan_install(str(source), workdir, override_name=name) + assert not (workdir / "local").exists() + assert external.read_text() == "Not distribution content" + assert (target / "config.yaml").read_text() == config + assert not (target / "SOUL.md").exists() + return + + 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") + + + +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): + 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") + 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 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() + + +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 + + +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 _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() + (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], + "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, + )) + 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 = _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 + 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) + + 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) + else: + update_distribution("main") + 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"]] + 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) + + +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") + 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", + "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}") + 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" + (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 = 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) + 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 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 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" + 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("staged_"): + _assert_staged_publication(target, tmp_path, monkeypatch, publish[finish], change) + return + + 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") + + 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"), + "tombstone": lambda: mark_named_profile_deleted(target), + "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() + 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 + + 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() + assert (clone / "config.yaml").is_file() diff --git a/website/docs/user-guide/profile-distributions.md b/website/docs/user-guide/profile-distributions.md index 14bbba02f75c..34050a30b2bf 100644 --- a/website/docs/user-guide/profile-distributions.md +++ b/website/docs/user-guide/profile-distributions.md @@ -613,6 +613,21 @@ 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. + +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. + +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. + --- ## Export and import a profile file @@ -744,7 +759,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