refactor(termhub): compact re-export blocks and wrap companion-module docstrings

2026-09-02 15:59:18 -07:00
parent a8f3dc4946
commit d320d5f741
8 changed files with 56 additions and 119 deletions
@@ -26,11 +26,10 @@ from hermes_constants import get_hermes_home
 from tools.url_safety import is_safe_url
 from tools.website_policy import check_website_access
 from tools.skills_hub_models import (  # noqa: F401  (re-exported public API)
-    SkillMeta, SkillBundle, SkillSource, source_url_for_bundle,
-    _referenced_support_paths, _normalize_bundle_path, _validate_skill_name,
-    _validate_install_parent_path, _normalize_lock_install_path,
-    _validate_bundle_rel_path, _skill_meta_to_dict, _parse_frontmatter,
-    _dedupe_by_trust, TRUST_RANK,
+    SkillMeta, SkillBundle, SkillSource, source_url_for_bundle, _referenced_support_paths,
+    _normalize_bundle_path, _validate_skill_name, _validate_install_parent_path,
+    _normalize_lock_install_path, _validate_bundle_rel_path, _skill_meta_to_dict,
+    _parse_frontmatter, _dedupe_by_trust, TRUST_RANK,
 )
 from tools.skills_hub_github import (  # noqa: F401
    GITHUB_TAP_PROVIDERS, github_provider_for, _PROVIDER_FILTER_VALUES,
@@ -43,30 +42,14 @@ from tools.skills_hub_sources import (  # noqa: F401
 )
 from tools.skills_hub_official import OptionalSkillSource, HermesIndexSource  # noqa: F401
 from tools.skills_hub_search import (  # noqa: F401  (re-exported; tests patch tools.skills_hub.<name>)
-    HERMES_INDEX_TTL,
-    HERMES_INDEX_URL,
-    _API_SOURCE_IDS,
-    _hermes_index_cache_file,
-    _load_hermes_index,
-    _load_stale_index_cache,
-    _search_one_source,
-    _select_active_sources,
-    create_source_router,
-    parallel_search_sources,
-    unified_search,
+    HERMES_INDEX_TTL, HERMES_INDEX_URL, _API_SOURCE_IDS, _hermes_index_cache_file,
+    _load_hermes_index, _load_stale_index_cache, _search_one_source, _select_active_sources,
+    create_source_router, parallel_search_sources, unified_search,
 )
 from tools.skills_hub_install import (  # noqa: F401  (re-exported; tests patch tools.skills_hub.<name>)
-    _SOURCE_ID_ALIASES,
-    _category_skill_dirs,
-    _check_install_target,
-    _is_path_redirect,
-    _resolve_lock_install_path,
-    _source_matches,
-    bundle_content_hash,
-    check_for_skill_updates,
-    install_from_quarantine,
-    quarantine_bundle,
-    uninstall_skill,
+    _SOURCE_ID_ALIASES, _category_skill_dirs, _check_install_target, _is_path_redirect,
+    _resolve_lock_install_path, _source_matches, bundle_content_hash, check_for_skill_updates,
+    install_from_quarantine, quarantine_bundle, uninstall_skill,
 )

 logger = logging.getLogger(__name__)
@@ -1,4 +1,6 @@
-"""Skills Hub install/uninstall/update operations: quarantine staging, install-target safety (symlink/junction, category-bucket and nested-skill checks), lock-file-backed uninstall, bundle hashing and upstream update checks.
+"""Skills Hub install/uninstall/update operations: quarantine staging, install-
+target safety (symlink/junction, category-bucket and nested-skill checks),
+lock-file-backed uninstall, bundle hashing and upstream update checks.

 Split out of ``tools/skills_hub.py``; every public/patched name is re-imported there,
 so ``tools.skills_hub.<name>`` keeps resolving (and monkeypatching) as before.
@@ -1,4 +1,6 @@
-"""Skills Hub discovery: the centralized Hermes index fetch (cached, stale-fallback), the source router, and parallel/unified search across source adapters.
+"""Skills Hub discovery: the centralized Hermes index fetch (cached, stale-
+fallback), the source router, and parallel/unified search across source
+adapters.

 Split out of ``tools/skills_hub.py``; every public/patched name is re-imported there,
 so ``tools.skills_hub.<name>`` keeps resolving (and monkeypatching) as before.
@@ -22,10 +24,8 @@ if TYPE_CHECKING:  # runtime use resolves through the origin (test patch target)
 # Log-record parity with the origin module.
 logger = logging.getLogger("tools.skills_hub")

-
 HERMES_INDEX_URL = "https://hermes-agent.nousresearch.com/docs/api/skills-index.json"

-
 HERMES_INDEX_TTL = 6 * 3600  # 6 hours


@@ -45,79 +45,34 @@ def _redact_terminal_error_text(value: Any) -> str:
 from tools.interrupt import is_interrupted, _interrupt_event  # noqa: F401 — re-exported
 from tools.registry import tool_error
 from tools.terminal_tool_lifecycle import (  # noqa: F401  (re-exported; tests patch tools.terminal_tool.<name>)
-    _DISK_USAGE_CACHE_TTL,
-    _check_disk_usage_warning,
-    _cleanup_inactive_envs,
-    _clear_file_ops_cache,
-    _create_configured_env,
-    _disk_usage_cache,
-    _evict_environment_for_task,
-    _teardown_env,
-    cleanup_all_environments,
-    cleanup_vm,
-    ensure_task_env,
-    get_active_env,
-    is_persistent_env,
+    _DISK_USAGE_CACHE_TTL, _check_disk_usage_warning, _cleanup_inactive_envs,
+    _clear_file_ops_cache, _create_configured_env, _disk_usage_cache,
+    _evict_environment_for_task, _teardown_env, cleanup_all_environments, cleanup_vm,
+    ensure_task_env, get_active_env, is_persistent_env,
 )
 from tools.terminal_tool_config import (  # noqa: F401  (re-exported; tests patch tools.terminal_tool.<name>)
-    _CONTAINER_BACKENDS,
-    _HOST_CWD_PREFIXES,
-    _get_plugin_env_provider,
-    _is_container_backend,
-    _is_unusable_container_cwd,
-    _parse_env_var,
-    _plugin_env_flag,
-    _safe_getcwd,
-    _tenv,
+    _CONTAINER_BACKENDS, _HOST_CWD_PREFIXES, _get_plugin_env_provider, _is_container_backend,
+    _is_unusable_container_cwd, _parse_env_var, _plugin_env_flag, _safe_getcwd, _tenv,
    _tenv_bool,
 )
 from tools.terminal_tool_backends import (  # noqa: F401  (re-exported; tests patch tools.terminal_tool.<name>)
-    _ENV_BUILDERS,
-    _REQUIREMENT_CHECKERS,
-    _SUPPORTED_VERCEL_RUNTIMES,
-    _VERCEL_SANDBOX_DEFAULT_CWD,
-    _build_daytona_env,
-    _build_docker_env,
-    _build_local_env,
-    _build_modal_env,
-    _build_plugin_env,
-    _build_singularity_env,
-    _build_ssh_env,
-    _build_vercel_env,
-    _check_daytona_requirements,
-    _check_docker_requirements,
-    _check_modal_requirements,
-    _check_plugin_requirements,
-    _check_singularity_requirements,
-    _check_ssh_requirements,
-    _check_vercel_sandbox_requirements,
-    _container_config_from_config,
-    _create_environment,
-    _get_modal_backend_state,
-    _is_supported_vercel_runtime,
-    _resources,
+    _ENV_BUILDERS, _REQUIREMENT_CHECKERS, _SUPPORTED_VERCEL_RUNTIMES,
+    _VERCEL_SANDBOX_DEFAULT_CWD, _build_daytona_env, _build_docker_env, _build_local_env,
+    _build_modal_env, _build_plugin_env, _build_singularity_env, _build_ssh_env,
+    _build_vercel_env, _check_daytona_requirements, _check_docker_requirements,
+    _check_modal_requirements, _check_plugin_requirements, _check_singularity_requirements,
+    _check_ssh_requirements, _check_vercel_sandbox_requirements, _container_config_from_config,
+    _create_environment, _get_modal_backend_state, _is_supported_vercel_runtime, _resources,
    _ssh_config_from_config,
 )
 from tools.terminal_tool_sudo import (  # noqa: F401  (re-exported; tests patch tools.terminal_tool.<name>)
-    _SUDO_WRONG_PASSWORD_MARKERS,
-    _count_real_sudo_invocations,
-    _get_cached_sudo_password,
-    _get_sudo_password_cache_scope,
-    _handle_sudo_failure,
-    _in_delegated_child_context,
-    _invalidate_cached_sudo_on_auth_failure,
-    _looks_like_env_assignment,
-    _prompt_for_sudo_password,
-    _read_shell_token,
-    _reset_cached_sudo_passwords,
-    _rewrite_compound_background,
-    _rewrite_real_sudo_invocations,
-    _set_cached_sudo_password,
-    _sudo_nopasswd_works,
-    _sudo_password_cache,
-    _sudo_password_cache_lock,
-    _sudo_wrong_password_failure,
-    _transform_sudo_command,
+    _SUDO_WRONG_PASSWORD_MARKERS, _count_real_sudo_invocations, _get_cached_sudo_password,
+    _get_sudo_password_cache_scope, _handle_sudo_failure, _in_delegated_child_context,
+    _invalidate_cached_sudo_on_auth_failure, _looks_like_env_assignment,
+    _prompt_for_sudo_password, _read_shell_token, _reset_cached_sudo_passwords,
+    _rewrite_compound_background, _rewrite_real_sudo_invocations, _set_cached_sudo_password,
+    _sudo_nopasswd_works, _sudo_password_cache, _sudo_password_cache_lock,
+    _sudo_wrong_password_failure, _transform_sudo_command,
 )
 # display_hermes_home imported lazily at call site (stale-module safety during hermes update)
 from tools.tool_backend_helpers import (  # noqa: F401  (managed_nous_tools_enabled: test patch target)
@@ -848,23 +803,14 @@ def _command_requires_pipe_stdin(command: str) -> bool:


 from tools.terminal_tool_guards import (  # noqa: F401 — re-exported (tests, plugins)
-    _LONG_LIVED_FOREGROUND_PATTERNS,
-    _SHELL_LEVEL_BACKGROUND_RE,
-    _WORKDIR_SAFE_ASCII_CHARS,
-    _foreground_background_guidance,
-    _is_safe_workdir_char,
-    _looks_like_help_or_version_command,
-    _safe_command_preview,
-    _strip_quotes,
-    _validate_workdir,
-    gateway_lifecycle_block,
-    self_repo_block,
+    _LONG_LIVED_FOREGROUND_PATTERNS, _SHELL_LEVEL_BACKGROUND_RE, _WORKDIR_SAFE_ASCII_CHARS,
+    _foreground_background_guidance, _is_safe_workdir_char,
+    _looks_like_help_or_version_command, _safe_command_preview, _strip_quotes,
+    _validate_workdir, gateway_lifecycle_block, self_repo_block,
 )
 from tools.terminal_tool_background import spawn_background_process
 from tools.terminal_tool_result import (  # noqa: F401 — re-exported (tests)
-    _SIGNAL_EXIT_NOTES,
-    _interpret_exit_code,
-    _interpret_signal_exit,
+    _SIGNAL_EXIT_NOTES, _interpret_exit_code, _interpret_signal_exit,
    finalize_foreground_result,
 )

@@ -1,4 +1,7 @@
-"""Execution-environment backends for the terminal tool: per-backend builders (local/docker/singularity/modal/daytona/vercel/ssh/plugin), the config-to-kwargs shapers, and the per-backend requirement checkers, both routed by dispatch table.
+"""Execution-environment backends for the terminal tool: per-backend builders
+(local/docker/singularity/modal/daytona/vercel/ssh/plugin), the config-to-
+kwargs shapers, and the per-backend requirement checkers, both routed by
+dispatch table.

 Split out of ``tools/terminal_tool.py``; every public/patched name is re-imported there,
 so ``tools.terminal_tool.<name>`` keeps resolving (and monkeypatching) as before.
@@ -28,10 +31,8 @@ from tools.tool_backend_helpers import (
 # Log-record parity with the origin module.
 logger = logging.getLogger("tools.terminal_tool")

-
 _VERCEL_SANDBOX_DEFAULT_CWD = "/vercel/sandbox"

-
 _SUPPORTED_VERCEL_RUNTIMES = ("node24", "node22", "python3.13")


@@ -1,4 +1,6 @@
-"""Terminal backend configuration: scope-aware TERMINAL_* reads, env-var parsing, container-cwd sanity checks, plugin-backend classification and the resolved config dict (_get_env_config).
+"""Terminal backend configuration: scope-aware TERMINAL_* reads, env-var parsing,
+container-cwd sanity checks, plugin-backend classification and the resolved
+config dict (_get_env_config).

 Split out of ``tools/terminal_tool.py``; every public/patched name is re-imported there,
 so ``tools.terminal_tool.<name>`` keeps resolving (and monkeypatching) as before.
@@ -43,7 +45,6 @@ def _safe_getcwd() -> str:
 # dirs and Windows drive paths as they leak toward a Linux ``-w`` flag).
 _HOST_CWD_PREFIXES = ("/Users/", "/home/", "C:\\", "C:/")

-
 _CONTAINER_BACKENDS = frozenset({"docker", "singularity", "modal", "daytona", "vercel_sandbox"})


@@ -1,4 +1,7 @@
-"""Sandbox lifecycle for the terminal tool: idle reaping, teardown, manual/atexit cleanup, and the lazy ensure_task_env bring-up. The env cache dicts and locks stay in tools.terminal_tool (tests patch them there) and are read through it at call time.
+"""Sandbox lifecycle for the terminal tool: idle reaping, teardown, manual/atexit
+cleanup, and the lazy ensure_task_env bring-up. The env cache dicts and locks
+stay in tools.terminal_tool (tests patch them there) and are read through it
+at call time.

 Split out of ``tools/terminal_tool.py``; every public/patched name is re-imported there,
 so ``tools.terminal_tool.<name>`` keeps resolving (and monkeypatching) as before.
@@ -25,7 +28,6 @@ logger = logging.getLogger("tools.terminal_tool")
 # every command (a result up to 5 minutes stale is harmless).
 _disk_usage_cache: dict = {"timestamp": 0.0, "result": False}

-
 _DISK_USAGE_CACHE_TTL = 300.0  # seconds


@@ -1,4 +1,7 @@
-"""Sudo password plumbing and shell-command rewrites for the terminal tool: the per-scope interactive password cache, the /dev/tty prompt, real-sudo tokenizer (sudo -S -p '' rewrite), NOPASSWD probe, and the compound-background brace-group rewrite.
+"""Sudo password plumbing and shell-command rewrites for the terminal tool: the
+per-scope interactive password cache, the /dev/tty prompt, real-sudo tokenizer
+(sudo -S -p '' rewrite), NOPASSWD probe, and the compound-background brace-
+group rewrite.

 Split out of ``tools/terminal_tool.py``; every public/patched name is re-imported there,
 so ``tools.terminal_tool.<name>`` keeps resolving (and monkeypatching) as before.
@@ -23,7 +26,6 @@ logger = logging.getLogger("tools.terminal_tool")
 # session can never reuse another's cached password in a long-lived process.
 _sudo_password_cache: dict[str, str] = {}

-
 _sudo_password_cache_lock = threading.Lock()